Skip to content

Commit 4c8b88c

Browse files
committed
feat(studio): asset click policy and canvas nudge gate
What: two small pure modules with tests — assetClickBehavior (click vs double-click policy for sidebar assets) and canvasNudgeGate (debounce gate for arrow-key canvas nudges). Why: policy dependencies of the upcoming asset card and nudge hook, reviewable as plain decision tables. How: new files only. Test plan: bunx vitest run on both test files; tsc --noEmit; fallow audit clean.
1 parent 2733e34 commit 4c8b88c

4 files changed

Lines changed: 242 additions & 0 deletions

File tree

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
import { describe, expect, it } from "vitest";
2+
import { findClipForAsset, isPointerClick, DRAG_THRESHOLD_PX } from "./assetClickBehavior";
3+
import type { TimelineElement } from "../player/store/playerStore";
4+
5+
// Minimal TimelineElement factory — only the fields the function inspects.
6+
function makeEl(overrides: Partial<TimelineElement> & { id: string }): TimelineElement {
7+
return {
8+
tag: "div",
9+
start: 0,
10+
duration: 5,
11+
track: 0,
12+
...overrides,
13+
};
14+
}
15+
16+
describe("findClipForAsset", () => {
17+
it("returns null when elements array is empty", () => {
18+
expect(findClipForAsset([], "assets/foo.mp4")).toBeNull();
19+
});
20+
21+
it("returns null when no element matches", () => {
22+
const el = makeEl({ id: "el1", src: "assets/other.mp4" });
23+
expect(findClipForAsset([el], "assets/foo.mp4")).toBeNull();
24+
});
25+
26+
it("matches a bare relative src against the project-relative asset path", () => {
27+
const el = makeEl({ id: "el1", src: "assets/clip.mp4", start: 2 });
28+
expect(findClipForAsset([el], "assets/clip.mp4")).toBe(el);
29+
});
30+
31+
it("matches a src with a ./ prefix", () => {
32+
const el = makeEl({ id: "el1", src: "./assets/logo.png" });
33+
expect(findClipForAsset([el], "assets/logo.png")).toBe(el);
34+
});
35+
36+
it("matches a server-relative /api/projects/…/preview/ src", () => {
37+
const el = makeEl({ id: "el1", src: "/api/projects/demo/preview/assets/bgm.mp3" });
38+
expect(findClipForAsset([el], "assets/bgm.mp3")).toBe(el);
39+
});
40+
41+
it("matches a fully-absolute URL (as produced by the core runtime)", () => {
42+
const el = makeEl({
43+
id: "el1",
44+
src: "http://localhost:3012/api/projects/demo/preview/assets/clip.mp4",
45+
});
46+
expect(findClipForAsset([el], "assets/clip.mp4")).toBe(el);
47+
});
48+
49+
it("decodes percent-encoded filenames when matching", () => {
50+
const el = makeEl({
51+
id: "el1",
52+
src: "http://localhost:3012/api/projects/p/preview/assets/my%20file%20(1).mp4",
53+
});
54+
expect(findClipForAsset([el], "assets/my file (1).mp4")).toBe(el);
55+
});
56+
57+
it("strips query strings from src before matching", () => {
58+
const el = makeEl({ id: "el1", src: "assets/clip.mp4?v=2" });
59+
expect(findClipForAsset([el], "assets/clip.mp4")).toBe(el);
60+
});
61+
62+
it("returns the element with the earliest start when multiple clips match", () => {
63+
const later = makeEl({ id: "late", src: "assets/clip.mp4", start: 10 });
64+
const earlier = makeEl({ id: "early", src: "assets/clip.mp4", start: 2 });
65+
const first = makeEl({ id: "first", src: "assets/clip.mp4", start: 0 });
66+
expect(findClipForAsset([later, earlier, first], "assets/clip.mp4")).toBe(first);
67+
});
68+
69+
it("prefers the key over id when the element has both", () => {
70+
// findClipForAsset returns the element object itself; callers do `clip.key ?? clip.id`
71+
const el = makeEl({ id: "el1", key: "clip-key", src: "assets/img.png" });
72+
const found = findClipForAsset([el], "assets/img.png");
73+
expect(found?.key).toBe("clip-key");
74+
});
75+
76+
it("skips elements with no src", () => {
77+
const noSrc = makeEl({ id: "nosrc" });
78+
const withSrc = makeEl({ id: "withsrc", src: "assets/img.png" });
79+
expect(findClipForAsset([noSrc, withSrc], "assets/img.png")).toBe(withSrc);
80+
});
81+
});
82+
83+
describe("isPointerClick", () => {
84+
it("returns true for zero movement", () => {
85+
expect(isPointerClick(0, 0)).toBe(true);
86+
});
87+
88+
it("returns true for movement within the threshold", () => {
89+
expect(isPointerClick(DRAG_THRESHOLD_PX - 1, 0)).toBe(true);
90+
expect(isPointerClick(0, DRAG_THRESHOLD_PX - 1)).toBe(true);
91+
expect(isPointerClick(DRAG_THRESHOLD_PX - 1, DRAG_THRESHOLD_PX - 1)).toBe(true);
92+
});
93+
94+
it("returns false at or beyond the threshold", () => {
95+
expect(isPointerClick(DRAG_THRESHOLD_PX, 0)).toBe(false);
96+
expect(isPointerClick(0, DRAG_THRESHOLD_PX)).toBe(false);
97+
expect(isPointerClick(DRAG_THRESHOLD_PX + 10, 0)).toBe(false);
98+
});
99+
100+
it("handles negative movement (pointer moved left/up)", () => {
101+
expect(isPointerClick(-(DRAG_THRESHOLD_PX - 1), 0)).toBe(true);
102+
expect(isPointerClick(-DRAG_THRESHOLD_PX, 0)).toBe(false);
103+
});
104+
});
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
/**
2+
* Pure helpers for CapCut-style asset card click behavior.
3+
*
4+
* Clicking an asset card that is ALREADY ADDED to the timeline selects the
5+
* corresponding clip. Clicking one NOT yet in the timeline opens a lightweight
6+
* preview overlay. Both behaviors are gated on "this was a click, not a drag".
7+
*
8+
* Pure — unit-tested.
9+
*/
10+
import type { TimelineElement } from "../player/store/playerStore";
11+
12+
/**
13+
* Find the TimelineElement that references `assetPath`, returning the one with
14+
* the earliest start time when multiple clips share the same source.
15+
*
16+
* Matching mirrors `deriveUsedPaths` in AssetsTab: an element's `src` may be a
17+
* fully-absolute URL, a server-relative `/api/projects/…/preview/…` path, a
18+
* `./`-prefixed relative path, or a bare relative path — all normalised to the
19+
* project-relative form that `assetPath` carries.
20+
*
21+
* Returns `null` when no element matches.
22+
*/
23+
export function findClipForAsset(
24+
elements: TimelineElement[],
25+
assetPath: string,
26+
): TimelineElement | null {
27+
let best: TimelineElement | null = null;
28+
for (const el of elements) {
29+
if (!el.src) continue;
30+
if (normalizeSrc(el.src) !== assetPath) continue;
31+
if (best === null || el.start < best.start) best = el;
32+
}
33+
return best;
34+
}
35+
36+
/**
37+
* Normalise a raw element `src` to the bare project-relative path so it can be
38+
* compared against the asset-list strings (which have no leading slash, no
39+
* origin, no query string).
40+
*
41+
* Mirrors the logic in `deriveUsedPaths` (AssetsTab.tsx) — keep in sync.
42+
*/
43+
function normalizeSrc(src: string): string {
44+
let s = src;
45+
try {
46+
const u = new URL(s);
47+
s = u.pathname;
48+
} catch {
49+
// Not an absolute URL — leave as-is
50+
}
51+
s = s
52+
.replace(/^\/api\/projects\/[^/]+\/preview\//, "")
53+
.replace(/^\.?\//, "")
54+
.split(/[?#]/)[0];
55+
try {
56+
s = decodeURIComponent(s);
57+
} catch {
58+
// Malformed encoding — use as-is
59+
}
60+
return s;
61+
}
62+
63+
/** Drag-detection threshold in pixels — movements within this are treated as clicks. */
64+
export const DRAG_THRESHOLD_PX = 4;
65+
66+
/**
67+
* Determine whether a pointer-up event should be treated as a click given the
68+
* total pointer displacement since pointer-down.
69+
*
70+
* @param dx Horizontal distance moved in pixels.
71+
* @param dy Vertical distance moved in pixels.
72+
*/
73+
export function isPointerClick(dx: number, dy: number): boolean {
74+
return Math.abs(dx) < DRAG_THRESHOLD_PX && Math.abs(dy) < DRAG_THRESHOLD_PX;
75+
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { beforeEach, describe, expect, it } from "vitest";
2+
import { __resetForTests, acquireCanvasNudgeKeys, canvasNudgeKeysClaimed } from "./canvasNudgeGate";
3+
4+
describe("canvasNudgeGate", () => {
5+
// The claim counter is module-level state; reset it so an unbalanced claim in one
6+
// test can't leak into the next.
7+
beforeEach(() => {
8+
__resetForTests();
9+
});
10+
11+
it("reports claimed while at least one claim is held", () => {
12+
expect(canvasNudgeKeysClaimed()).toBe(false);
13+
const releaseA = acquireCanvasNudgeKeys();
14+
const releaseB = acquireCanvasNudgeKeys();
15+
expect(canvasNudgeKeysClaimed()).toBe(true);
16+
releaseA();
17+
expect(canvasNudgeKeysClaimed()).toBe(true);
18+
releaseB();
19+
expect(canvasNudgeKeysClaimed()).toBe(false);
20+
});
21+
22+
it("makes release idempotent so an effect re-run cannot underflow", () => {
23+
const release = acquireCanvasNudgeKeys();
24+
release();
25+
release();
26+
expect(canvasNudgeKeysClaimed()).toBe(false);
27+
const releaseNext = acquireCanvasNudgeKeys();
28+
expect(canvasNudgeKeysClaimed()).toBe(true);
29+
releaseNext();
30+
});
31+
});
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
/**
2+
* Arrow-key ownership gate between the canvas nudge (DomEditOverlay) and the
3+
* playback frame-step shortcuts (usePlaybackKeyboard). Both listen for arrow
4+
* keys with window capture listeners, and their relative order depends on
5+
* mount order (DomEditOverlay remounts when caption edit mode toggles), so
6+
* `event.defaultPrevented` alone can't arbitrate. While a nudgeable canvas
7+
* selection holds a claim, the playback handler skips ArrowLeft/ArrowRight.
8+
*/
9+
10+
let claims = 0;
11+
12+
/** Claim the arrow keys for canvas nudging. Returns an idempotent release. */
13+
export function acquireCanvasNudgeKeys(): () => void {
14+
claims += 1;
15+
let released = false;
16+
return () => {
17+
if (released) return;
18+
released = true;
19+
claims -= 1;
20+
};
21+
}
22+
23+
/** True while a nudgeable canvas selection owns the arrow keys. */
24+
export function canvasNudgeKeysClaimed(): boolean {
25+
return claims > 0;
26+
}
27+
28+
/** Test-only: reset the module-level claim counter so leaked claims from one test
29+
* can't bleed into the next (call in a `beforeEach`). */
30+
export function __resetForTests(): void {
31+
claims = 0;
32+
}

0 commit comments

Comments
 (0)