Skip to content

Commit af7ff3b

Browse files
feat(studio): enter a sub-composition from the keyboard and host its navigation (#4672)
* feat(studio): enter a sub-composition from the keyboard and host its navigation * fix(studio): drop a comment the element field already says
1 parent 5f7c6bc commit af7ff3b

8 files changed

Lines changed: 52 additions & 11 deletions

File tree

‎docs/packages/studio.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ Peer dependencies are React 19, React DOM 19, and Zustand 4 or 5.
7575
| ----------------------------------------------------------- | ----------------------------------------------------- |
7676
| `useTimelinePlayer` | Read and control the shared player state |
7777
| `usePlayerStore` | Access the Zustand player store |
78+
| `useCompositionStack` | Drill into and back out of nested compositions |
7879
| `useElementPicker` | Select and edit an element through the preview iframe |
7980
| `resolveSourceFile`, `applyPatch` | Locate and patch source |
8081
| `parseStyleString`, `mergeStyleIntoTag`, `findElementBlock` | Work with inline source styles and elements |

‎packages/studio/src/components/nle/CompositionBreadcrumb.tsx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ export function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcru
2121
return (
2222
<nav
2323
aria-label="Composition navigation"
24-
className="flex items-center gap-1 px-2 h-8 border-b border-neutral-800/50 bg-neutral-900/50 shrink-0"
24+
className="flex items-center gap-1 px-2 h-8 border-b border-hairline bg-bg-1 shrink-0"
2525
>
2626
{/* Back button — always goes to parent */}
2727
<button
@@ -33,7 +33,7 @@ export function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcru
3333
});
3434
onNavigate(stack.length - 2);
3535
}}
36-
className="flex items-center gap-1 px-1.5 py-0.5 rounded-sm text-xs text-neutral-400 hover:text-white hover:bg-neutral-800 active:scale-[0.98] transition-colors"
36+
className="flex items-center gap-1 px-1.5 py-0.5 rounded-sm text-xs text-text-3 hover:text-text-0 hover:bg-hover active:scale-[0.98] transition-colors"
3737
title="Back (Esc, or double-click empty timeline)"
3838
aria-label="Back to parent composition"
3939
>
@@ -45,17 +45,17 @@ export function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcru
4545
const isLast = i === stack.length - 1;
4646
return (
4747
<span key={level.id} className="flex items-center gap-1">
48-
{i > 0 && <CaretRight size={10} className="text-neutral-600 shrink-0" />}
48+
{i > 0 && <CaretRight size={10} className="text-text-4 shrink-0" />}
4949
{isLast ? (
50-
<span className="text-xs text-neutral-200 font-medium">{level.label}</span>
50+
<span className="text-xs text-text-1 font-medium">{level.label}</span>
5151
) : (
5252
<button
5353
type="button"
5454
onClick={() => {
5555
trackStudioEvent("navigation", { action: "breadcrumb", target: level.label });
5656
onNavigate(i);
5757
}}
58-
className="text-xs text-neutral-500 hover:text-neutral-200 transition-colors"
58+
className="text-xs text-text-3 hover:text-text-1 transition-colors"
5959
>
6060
{level.label}
6161
</button>
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import { expect, it } from "vitest";
2+
import { CompositionBreadcrumb, useCompositionStack } from "@hyperframes/studio";
3+
4+
it("exports the composition stack hook beside the breadcrumb it feeds", () => {
5+
expect(typeof useCompositionStack).toBe("function");
6+
expect(typeof CompositionBreadcrumb).toBe("function");
7+
});

‎packages/studio/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ export { DEFAULT_SHORTCUT_SECTIONS } from "./player/components/studioShortcuts";
99
export type { ShortcutHint, ShortcutSection } from "./player/components/studioShortcuts";
1010
export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
1111
export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
12+
export { useCompositionStack } from "./components/nle/useCompositionStack";
1213

1314
// Player (preview, timeline, playback controls)
1415
export {

‎packages/studio/src/player/components/TimelineLanes.tsx‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,9 +134,8 @@ export function TimelineLanes({
134134
focusedTargetId,
135135
rowGeometry,
136136
scrollRef,
137-
onToggleRow: (row) => {
138-
if (row.elementId) toggleClipExpandedTracked(row.elementId);
139-
},
137+
onToggleRow: (row) => row.elementId && toggleClipExpandedTracked(row.elementId),
138+
onDrillDown,
140139
});
141140
return (
142141
<div

‎packages/studio/src/player/components/timelineKeyboardNavigation.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ export interface TimelineLogicalItem {
4949
elementId: string;
5050
/** The item's time anchor. Clips use their midpoint; ease controls use the segment midpoint. */
5151
time: number;
52+
element?: TimelineElement;
5253
keyframeTarget?: TimelineKeyframeTarget;
5354
}
5455

@@ -113,6 +114,7 @@ function clipItems(rowId: string, elements: readonly TimelineElement[]): Timelin
113114
rowId,
114115
elementId: id,
115116
time: element.start + element.duration / 2,
117+
element,
116118
};
117119
});
118120
}

‎packages/studio/src/player/components/useTimelineKeyboardActor.test.tsx‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import React, { act, useRef } from "react";
44
import { createRoot } from "react-dom/client";
55
import { afterEach, describe, expect, it, vi } from "vitest";
6-
import { usePlayerStore } from "../store/playerStore";
6+
import { usePlayerStore, type TimelineElement } from "../store/playerStore";
77
import { createTimelineRowGeometry } from "./timelineLayout";
88
import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
99
import { useTimelineKeyboardActor } from "./useTimelineKeyboardActor";
@@ -57,13 +57,15 @@ interface HarnessProps {
5757
logicalRows?: readonly TimelineLogicalRow[];
5858
rowHeights?: readonly number[];
5959
onToggleRow?: (target: TimelineLogicalRow) => void;
60+
onDrillDown?: (element: TimelineElement) => void;
6061
}
6162

6263
function Harness({
6364
focusedTargetId = null,
6465
logicalRows = rows,
6566
rowHeights = logicalRows.map(() => 48),
6667
onToggleRow = vi.fn(),
68+
onDrillDown,
6769
}: HarnessProps) {
6870
const scrollRef = useRef<HTMLDivElement>(null);
6971
const keyboard = useTimelineKeyboardActor({
@@ -75,6 +77,7 @@ function Harness({
7577
),
7678
scrollRef,
7779
onToggleRow,
80+
onDrillDown,
7881
});
7982
return (
8083
<div ref={scrollRef} onFocus={keyboard.onFocus} onKeyDown={keyboard.onKeyDown}>
@@ -228,6 +231,26 @@ describe("useTimelineKeyboardActor", () => {
228231
act(() => root.unmount());
229232
});
230233

234+
it("drills into a composition clip on Enter and leaves a plain clip alone", () => {
235+
const scene = { id: "scene", tag: "div", start: 0, duration: 2, track: 1 };
236+
const withElements = rows.map((row, index) => ({
237+
...row,
238+
items: row.items.map((item) => ({
239+
...item,
240+
element: index === 0 ? { ...scene, compositionSrc: "scene.html" } : scene,
241+
})),
242+
}));
243+
const onDrillDown = vi.fn();
244+
const { host, root } = renderHarness({ logicalRows: withElements, onDrillDown });
245+
const composition = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-1"]')!;
246+
const plain = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-2"]')!;
247+
expect(key(plain, "Enter").defaultPrevented).toBe(false);
248+
expect(onDrillDown).not.toHaveBeenCalled();
249+
expect(key(composition, "Enter").defaultPrevented).toBe(true);
250+
expect(onDrillDown).toHaveBeenCalledWith(withElements[0]!.items[0]!.element);
251+
act(() => root.unmount());
252+
});
253+
231254
it("collapses expanded rows and leaves native header controls to the browser", () => {
232255
const onToggleRow = vi.fn();
233256
const expandedRows = [{ ...rows[0]!, expanded: true }, ...rows.slice(1)];

‎packages/studio/src/player/components/useTimelineKeyboardActor.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { useCallback, useMemo, type FocusEvent, type KeyboardEvent, type RefObject } from "react";
2-
import { usePlayerStore } from "../store/playerStore";
2+
import { usePlayerStore, type TimelineElement } from "../store/playerStore";
33
import type { TimelineRowGeometry } from "./timelineLayout";
44
import {
55
isTimelineNavigationKey,
@@ -14,6 +14,7 @@ interface TimelineKeyboardActorInput {
1414
rowGeometry: TimelineRowGeometry;
1515
scrollRef: RefObject<HTMLDivElement | null>;
1616
onToggleRow: (target: TimelineLogicalRow) => void;
17+
onDrillDown?: (element: TimelineElement) => void;
1718
}
1819

1920
function eventTarget(event: FocusEvent | KeyboardEvent): HTMLElement | null {
@@ -70,6 +71,7 @@ export function useTimelineKeyboardActor({
7071
rowGeometry,
7172
scrollRef,
7273
onToggleRow,
74+
onDrillDown,
7375
}: TimelineKeyboardActorInput) {
7476
const rovingTargetId =
7577
(focusedTargetId && locateTimelineLogicalTarget(logicalRows, focusedTargetId)?.target.id) ??
@@ -130,6 +132,12 @@ export function useTimelineKeyboardActor({
130132
openContextMenu(targetElement);
131133
return;
132134
}
135+
const composition = located.target.kind === "clip" && located.target.element;
136+
if (event.key === "Enter" && composition && composition.compositionSrc && onDrillDown) {
137+
event.preventDefault();
138+
onDrillDown(composition);
139+
return;
140+
}
133141
if (
134142
(event.key !== "Enter" && event.key !== " ") ||
135143
located.target.kind !== "row" ||
@@ -140,7 +148,7 @@ export function useTimelineKeyboardActor({
140148
event.preventDefault();
141149
onToggleRow(located.target);
142150
},
143-
[logicalRowCountByTrack, logicalRows, onToggleRow, rowGeometry, scrollRef],
151+
[logicalRowCountByTrack, logicalRows, onDrillDown, onToggleRow, rowGeometry, scrollRef],
144152
);
145153

146154
return { rovingTargetId, onFocus, onKeyDown };

0 commit comments

Comments
 (0)