@dxos/react-ui-animation 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +105 -0
- package/dist/lib/index.mjs +306 -0
- package/dist/lib/index.mjs.map +1 -0
- package/dist/px-icons/anthropic.svg +12 -0
- package/dist/px-icons/bar-high.svg +21 -0
- package/dist/px-icons/bar-low.svg +18 -0
- package/dist/px-icons/bar-medium.svg +20 -0
- package/dist/px-icons/circle.svg +5 -0
- package/dist/px-icons/context-panel.svg +6 -0
- package/dist/px-icons/deepseek.svg +10 -0
- package/dist/types/src/components/TimelineBar/TimelineBar.d.ts +38 -0
- package/dist/types/src/components/TimelineBar/TimelineBar.d.ts.map +1 -0
- package/dist/types/src/components/TimelineBar/TimelineBar.stories.d.ts +23 -0
- package/dist/types/src/components/TimelineBar/TimelineBar.stories.d.ts.map +1 -0
- package/dist/types/src/components/TimelineBar/TimelineBar.test.d.ts +2 -0
- package/dist/types/src/components/TimelineBar/TimelineBar.test.d.ts.map +1 -0
- package/dist/types/src/components/TimelineBar/index.d.ts +2 -0
- package/dist/types/src/components/TimelineBar/index.d.ts.map +1 -0
- package/dist/types/src/components/index.d.ts +2 -0
- package/dist/types/src/components/index.d.ts.map +1 -0
- package/dist/types/src/hooks/index.d.ts +3 -0
- package/dist/types/src/hooks/index.d.ts.map +1 -0
- package/dist/types/src/hooks/useClock.d.ts +13 -0
- package/dist/types/src/hooks/useClock.d.ts.map +1 -0
- package/dist/types/src/hooks/useExposedClock.d.ts +10 -0
- package/dist/types/src/hooks/useExposedClock.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +3 -0
- package/dist/types/src/index.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -0
- package/package.json +49 -3
- package/src/components/TimelineBar/TimelineBar.stories.tsx +200 -0
- package/src/components/TimelineBar/TimelineBar.test.ts +20 -0
- package/src/components/TimelineBar/TimelineBar.tsx +288 -0
- package/src/components/TimelineBar/index.ts +5 -0
- package/src/components/index.ts +5 -0
- package/src/hooks/index.ts +6 -0
- package/src/hooks/useClock.ts +56 -0
- package/src/hooks/useExposedClock.ts +35 -0
- package/src/index.ts +6 -0
- package/README.md +0 -3
package/package.json
CHANGED
|
@@ -1,6 +1,52 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dxos/react-ui-animation",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"description": "Timeline controls and clock hooks for @dxos/animation.",
|
|
5
|
+
"homepage": "https://dxos.org",
|
|
6
|
+
"bugs": "https://github.com/dxos/dxos/issues",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "https://github.com/dxos/dxos"
|
|
10
|
+
},
|
|
11
|
+
"license": "FSL-1.1-Apache-2.0",
|
|
12
|
+
"author": "DXOS.org",
|
|
13
|
+
"sideEffects": false,
|
|
14
|
+
"type": "module",
|
|
15
|
+
"exports": {
|
|
16
|
+
".": {
|
|
17
|
+
"source": "./src/index.ts",
|
|
18
|
+
"types": "./dist/types/src/index.d.ts",
|
|
19
|
+
"import": "./dist/lib/index.mjs"
|
|
20
|
+
}
|
|
21
|
+
},
|
|
22
|
+
"types": "dist/types/src/index.d.ts",
|
|
23
|
+
"files": [
|
|
24
|
+
"dist",
|
|
25
|
+
"src"
|
|
26
|
+
],
|
|
27
|
+
"dependencies": {
|
|
28
|
+
"@effect/atom-react": "4.0.4",
|
|
29
|
+
"@dxos/animation": "0.16.0"
|
|
30
|
+
},
|
|
31
|
+
"devDependencies": {
|
|
32
|
+
"@storybook/react-vite": "^10.6.0",
|
|
33
|
+
"@types/react": "~19.3.0",
|
|
34
|
+
"@types/react-dom": "~19.3.0",
|
|
35
|
+
"effect": "4.0.4",
|
|
36
|
+
"react": "~19.3.1",
|
|
37
|
+
"react-dom": "~19.3.1",
|
|
38
|
+
"vite": "^8.3.4",
|
|
39
|
+
"@dxos/react-ui": "0.16.0",
|
|
40
|
+
"@dxos/ui-theme": "0.16.0"
|
|
41
|
+
},
|
|
42
|
+
"peerDependencies": {
|
|
43
|
+
"effect": "4.0.4",
|
|
44
|
+
"react": "~19.3.1",
|
|
45
|
+
"react-dom": "~19.3.1",
|
|
46
|
+
"@dxos/react-ui": "^0.16.0",
|
|
47
|
+
"@dxos/ui-theme": "^0.16.0"
|
|
48
|
+
},
|
|
49
|
+
"publishConfig": {
|
|
50
|
+
"access": "public"
|
|
51
|
+
}
|
|
6
52
|
}
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import { useAtomValue } from '@effect/atom-react/Hooks';
|
|
6
|
+
import { RegistryContext } from '@effect/atom-react/RegistryContext';
|
|
7
|
+
import { type Meta, type StoryObj } from '@storybook/react-vite';
|
|
8
|
+
import React, { useContext, useMemo, useState } from 'react';
|
|
9
|
+
import { expect, fireEvent, userEvent, waitFor, within } from 'storybook/test';
|
|
10
|
+
|
|
11
|
+
import { createClock } from '@dxos/animation';
|
|
12
|
+
import { withLayout, withRegistry, withTheme } from '@dxos/react-ui/testing';
|
|
13
|
+
import { translations as uiTranslations } from '@dxos/react-ui/translations';
|
|
14
|
+
|
|
15
|
+
import { useClock } from '../../hooks/index.ts';
|
|
16
|
+
import { TimelineBar, keyAt } from './TimelineBar.tsx';
|
|
17
|
+
|
|
18
|
+
type StoryArgs = { duration: number; fps: number; readonly?: boolean };
|
|
19
|
+
|
|
20
|
+
/** The bar over a real clock, as react-ui-canvas's `Canvas.Timeline` drives it, with keys kept in local state. */
|
|
21
|
+
const DefaultStory = ({ duration, fps, readonly }: StoryArgs) => {
|
|
22
|
+
const registry = useContext(RegistryContext);
|
|
23
|
+
const clock = useMemo(() => createClock(), []);
|
|
24
|
+
useClock(clock, { duration });
|
|
25
|
+
const time = useAtomValue(clock.time);
|
|
26
|
+
const playing = useAtomValue(clock.playing);
|
|
27
|
+
const [keys, setKeys] = useState<number[]>([0, 1.5]);
|
|
28
|
+
const [autoKey, setAutoKey] = useState(true);
|
|
29
|
+
return (
|
|
30
|
+
<TimelineBar
|
|
31
|
+
time={time}
|
|
32
|
+
duration={duration}
|
|
33
|
+
playing={playing}
|
|
34
|
+
fps={fps}
|
|
35
|
+
keys={keys}
|
|
36
|
+
autoKey={autoKey}
|
|
37
|
+
readonly={readonly}
|
|
38
|
+
onPlayingChange={(next) => registry.set(clock.playing, next)}
|
|
39
|
+
onTimeChange={(next) => registry.set(clock.time, next)}
|
|
40
|
+
onAutoKeyChange={setAutoKey}
|
|
41
|
+
onAddKey={() => setKeys((keys) => [...new Set([...keys, time])].sort((left, right) => left - right))}
|
|
42
|
+
onRemoveKey={() => setKeys((keys) => keys.filter((key) => key !== keyAt(keys, time, fps)))}
|
|
43
|
+
onMoveKey={(from, to) =>
|
|
44
|
+
setKeys((keys) =>
|
|
45
|
+
[...new Set(keys.map((key) => (key === from ? to : key)))].sort((left, right) => left - right),
|
|
46
|
+
)
|
|
47
|
+
}
|
|
48
|
+
/>
|
|
49
|
+
);
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
const meta: Meta<StoryArgs> = {
|
|
53
|
+
title: 'ui/react-ui-animation/components/TimelineBar',
|
|
54
|
+
render: DefaultStory,
|
|
55
|
+
decorators: [withRegistry, withTheme(), withLayout({ layout: 'centered' })],
|
|
56
|
+
parameters: { translations: uiTranslations },
|
|
57
|
+
args: { duration: 4, fps: 30 },
|
|
58
|
+
argTypes: {
|
|
59
|
+
duration: { control: { type: 'range', min: 1, max: 20, step: 1 }, description: 'Seconds' },
|
|
60
|
+
fps: { control: { type: 'inline-radio' }, options: [24, 30, 60] },
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
|
|
64
|
+
export default meta;
|
|
65
|
+
|
|
66
|
+
type Story = StoryObj<typeof meta>;
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Test:
|
|
70
|
+
* 1. The bar shows the time against the duration and a diamond per key.
|
|
71
|
+
* 2. Pressing the middle of the track moves the playhead there, on the frame grid.
|
|
72
|
+
* 3. Add key puts a diamond at the playhead; on a key the same button removes it.
|
|
73
|
+
* 4. ⌘← and ⌘→ jump between keys; Delete removes the key under the playhead.
|
|
74
|
+
* 5. Play advances the clock; pressing it again pauses.
|
|
75
|
+
*/
|
|
76
|
+
export const Default: Story = {};
|
|
77
|
+
|
|
78
|
+
/** The default story, driven: its steps run as a play test. */
|
|
79
|
+
export const Test: Story = {
|
|
80
|
+
play: async ({ canvasElement }) => {
|
|
81
|
+
const canvas = within(canvasElement);
|
|
82
|
+
// 1. Time and keys.
|
|
83
|
+
await expect(await canvas.findByTestId('timeline-time')).toHaveTextContent('0.00 / 4.00');
|
|
84
|
+
await expect(canvas.getAllByTestId('timeline-key')).toHaveLength(2);
|
|
85
|
+
|
|
86
|
+
// 2. Scrub to the middle.
|
|
87
|
+
const track = canvas.getByTestId('timeline-track');
|
|
88
|
+
const rect = track.getBoundingClientRect();
|
|
89
|
+
await userEvent.pointer({
|
|
90
|
+
keys: '[MouseLeft]',
|
|
91
|
+
target: track,
|
|
92
|
+
coords: { clientX: rect.left + rect.width / 2, clientY: rect.top + 4 },
|
|
93
|
+
});
|
|
94
|
+
await waitFor(() => expect(canvas.getByTestId('timeline-time')).toHaveTextContent('2.00 / 4.00'));
|
|
95
|
+
|
|
96
|
+
// 3. From the menu: a key at the playhead, deleted and added back; auto-key turns off and on.
|
|
97
|
+
const choose = async (testId: string) => {
|
|
98
|
+
await userEvent.click(canvas.getByTestId('timeline-menu'));
|
|
99
|
+
const item = await within(document.body).findByTestId(testId);
|
|
100
|
+
await waitFor(() => expect(item).toBeVisible());
|
|
101
|
+
// The menu ignores synthetic pointer events on its items, so the item is highlighted and chosen from the keyboard.
|
|
102
|
+
for (let step = 0; step < 4 && !item.hasAttribute('data-highlighted'); step++) {
|
|
103
|
+
await userEvent.keyboard('{ArrowDown}');
|
|
104
|
+
}
|
|
105
|
+
await expect(item).toHaveAttribute('data-highlighted');
|
|
106
|
+
await userEvent.keyboard('{Enter}');
|
|
107
|
+
await waitFor(() => expect(item).not.toBeVisible());
|
|
108
|
+
};
|
|
109
|
+
await choose('timeline-add-key');
|
|
110
|
+
await waitFor(() => expect(canvas.getAllByTestId('timeline-key')).toHaveLength(3));
|
|
111
|
+
await choose('timeline-remove-key');
|
|
112
|
+
await waitFor(() => expect(canvas.getAllByTestId('timeline-key')).toHaveLength(2));
|
|
113
|
+
await choose('timeline-add-key');
|
|
114
|
+
await waitFor(() => expect(canvas.getAllByTestId('timeline-key')).toHaveLength(3));
|
|
115
|
+
await choose('timeline-auto-key');
|
|
116
|
+
await userEvent.click(canvas.getByTestId('timeline-menu'));
|
|
117
|
+
await expect(await within(document.body).findByTestId('timeline-auto-key')).toHaveAttribute(
|
|
118
|
+
'data-state',
|
|
119
|
+
'unchecked',
|
|
120
|
+
);
|
|
121
|
+
await userEvent.keyboard('{Escape}');
|
|
122
|
+
|
|
123
|
+
// 4. Jump between keys from the track, and delete one.
|
|
124
|
+
track.focus();
|
|
125
|
+
await userEvent.keyboard('{Meta>}{ArrowLeft}{/Meta}');
|
|
126
|
+
await waitFor(() => expect(canvas.getByTestId('timeline-time')).toHaveTextContent('1.15 / 4.00'));
|
|
127
|
+
await userEvent.keyboard('{Meta>}{ArrowRight}{/Meta}');
|
|
128
|
+
await waitFor(() => expect(canvas.getByTestId('timeline-time')).toHaveTextContent('2.00 / 4.00'));
|
|
129
|
+
await userEvent.keyboard('{Delete}');
|
|
130
|
+
await waitFor(() => expect(canvas.getAllByTestId('timeline-key')).toHaveLength(2));
|
|
131
|
+
|
|
132
|
+
// 5. A diamond drags along the track: the key moves where it is dropped, and the playhead with it.
|
|
133
|
+
const [first] = canvas.getAllByTestId('timeline-key');
|
|
134
|
+
const from = first.getBoundingClientRect();
|
|
135
|
+
const quarter = rect.left + rect.width / 4;
|
|
136
|
+
await fireEvent.pointerDown(first, { clientX: from.left, clientY: from.top, pointerId: 1 });
|
|
137
|
+
await fireEvent.pointerMove(first, { clientX: quarter, clientY: from.top, pointerId: 1 });
|
|
138
|
+
await fireEvent.pointerUp(first, { clientX: quarter, clientY: from.top, pointerId: 1 });
|
|
139
|
+
await waitFor(() => expect(canvas.getByTestId('timeline-time')).toHaveTextContent('1.00 / 4.00'));
|
|
140
|
+
await waitFor(() =>
|
|
141
|
+
expect(canvas.getAllByTestId('timeline-key').map((key) => key.getAttribute('aria-label'))).toContain(
|
|
142
|
+
'Key at 1.00 s',
|
|
143
|
+
),
|
|
144
|
+
);
|
|
145
|
+
|
|
146
|
+
// 6. From the play button: ⌘ with an arrow walks the keys and then reaches the end (or the start), a plain arrow
|
|
147
|
+
// scrubs a frame, Enter keys the playhead once, Delete removes that key and Space plays and pauses.
|
|
148
|
+
const play = canvas.getByTestId('timeline-play');
|
|
149
|
+
play.focus();
|
|
150
|
+
const keyCount = canvas.getAllByTestId('timeline-key').length;
|
|
151
|
+
for (let step = 0; step <= keyCount; step++) {
|
|
152
|
+
await userEvent.keyboard('{Meta>}{ArrowRight}{/Meta}');
|
|
153
|
+
}
|
|
154
|
+
await waitFor(() => expect(canvas.getByTestId('timeline-time')).toHaveTextContent('4.00 / 4.00'));
|
|
155
|
+
for (let step = 0; step <= keyCount; step++) {
|
|
156
|
+
await userEvent.keyboard('{Meta>}{ArrowLeft}{/Meta}');
|
|
157
|
+
}
|
|
158
|
+
await waitFor(() => expect(canvas.getByTestId('timeline-time')).toHaveTextContent('0.00 / 4.00'));
|
|
159
|
+
await userEvent.keyboard('{ArrowRight}');
|
|
160
|
+
await waitFor(() => expect(canvas.getByTestId('timeline-time')).toHaveTextContent('0.01 / 4.00'));
|
|
161
|
+
for (let step = 0; step <= keyCount; step++) {
|
|
162
|
+
await userEvent.keyboard('{Meta>}{ArrowRight}{/Meta}');
|
|
163
|
+
}
|
|
164
|
+
const count = canvas.getAllByTestId('timeline-key').length;
|
|
165
|
+
await userEvent.keyboard('{Enter}');
|
|
166
|
+
await waitFor(() => expect(canvas.getAllByTestId('timeline-key')).toHaveLength(count + 1));
|
|
167
|
+
// Already on a key: Enter adds nothing, and it never presses the button (still paused).
|
|
168
|
+
await userEvent.keyboard('{Enter}');
|
|
169
|
+
await expect(canvas.getAllByTestId('timeline-key')).toHaveLength(count + 1);
|
|
170
|
+
await expect(play).toHaveAccessibleName('Play');
|
|
171
|
+
await userEvent.keyboard('{Delete}');
|
|
172
|
+
await waitFor(() => expect(canvas.getAllByTestId('timeline-key')).toHaveLength(count));
|
|
173
|
+
await userEvent.keyboard('{Meta>}{ArrowLeft}{/Meta}');
|
|
174
|
+
for (let step = 0; step <= keyCount; step++) {
|
|
175
|
+
await userEvent.keyboard('{Meta>}{ArrowLeft}{/Meta}');
|
|
176
|
+
}
|
|
177
|
+
await userEvent.keyboard(' ');
|
|
178
|
+
await waitFor(() => expect(play).toHaveAccessibleName('Pause'));
|
|
179
|
+
await userEvent.keyboard(' ');
|
|
180
|
+
await waitFor(() => expect(play).toHaveAccessibleName('Play'));
|
|
181
|
+
|
|
182
|
+
// 7. Play, then pause.
|
|
183
|
+
await userEvent.click(canvas.getByTestId('timeline-play'));
|
|
184
|
+
await waitFor(() => expect(canvas.getByTestId('timeline-time')).not.toHaveTextContent(/^2\.00/), {
|
|
185
|
+
timeout: 5_000,
|
|
186
|
+
});
|
|
187
|
+
await userEvent.click(canvas.getByTestId('timeline-play'));
|
|
188
|
+
await expect(canvas.getByTestId('timeline-play')).toHaveAccessibleName('Play');
|
|
189
|
+
},
|
|
190
|
+
};
|
|
191
|
+
|
|
192
|
+
/** Read-only: play and scrub stay, the key and auto-key menu goes. */
|
|
193
|
+
export const Readonly: Story = {
|
|
194
|
+
args: { readonly: true },
|
|
195
|
+
play: async ({ canvasElement }) => {
|
|
196
|
+
const canvas = within(canvasElement);
|
|
197
|
+
await expect(await canvas.findByTestId('timeline-play')).toBeInTheDocument();
|
|
198
|
+
await expect(canvas.queryByTestId('timeline-menu')).toBeNull();
|
|
199
|
+
},
|
|
200
|
+
};
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import { describe, test } from 'vitest';
|
|
6
|
+
|
|
7
|
+
import { jumpTarget } from './TimelineBar.tsx';
|
|
8
|
+
|
|
9
|
+
describe('jumpTarget', () => {
|
|
10
|
+
test('goes to the next or previous key, and to the end or start when there is none that way', ({ expect }) => {
|
|
11
|
+
const keys = [1, 2];
|
|
12
|
+
expect(jumpTarget(keys, 0, 30, 4, false)).toBe(1);
|
|
13
|
+
expect(jumpTarget(keys, 1, 30, 4, false)).toBe(2);
|
|
14
|
+
expect(jumpTarget(keys, 2, 30, 4, false)).toBe(4);
|
|
15
|
+
expect(jumpTarget(keys, 3, 30, 4, true)).toBe(2);
|
|
16
|
+
expect(jumpTarget(keys, 1, 30, 4, true)).toBe(0);
|
|
17
|
+
expect(jumpTarget([], 2, 30, 4, false)).toBe(4);
|
|
18
|
+
expect(jumpTarget([], 2, 30, 4, true)).toBe(0);
|
|
19
|
+
});
|
|
20
|
+
});
|
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import React, { type KeyboardEvent, type PointerEvent, useCallback, useRef, useState } from 'react';
|
|
6
|
+
|
|
7
|
+
import * as Button from '@dxos/react-ui/Button';
|
|
8
|
+
import * as Menu from '@dxos/react-ui/Menu';
|
|
9
|
+
import * as Toolbar from '@dxos/react-ui/Toolbar';
|
|
10
|
+
import type * as Util from '@dxos/react-ui/Util';
|
|
11
|
+
import { mx } from '@dxos/ui-theme';
|
|
12
|
+
|
|
13
|
+
export type TimelineBarProps = Util.ThemedClassName<{
|
|
14
|
+
/** Shows its controls without letting them change the keys. */
|
|
15
|
+
readonly?: boolean;
|
|
16
|
+
/** Seconds. */
|
|
17
|
+
time: number;
|
|
18
|
+
duration: number;
|
|
19
|
+
playing: boolean;
|
|
20
|
+
fps: number;
|
|
21
|
+
/** Times of the selection's keys, drawn as diamonds on the track. */
|
|
22
|
+
keys?: readonly number[];
|
|
23
|
+
autoKey?: boolean;
|
|
24
|
+
onPlayingChange?: (playing: boolean) => void;
|
|
25
|
+
onTimeChange?: (time: number) => void;
|
|
26
|
+
onAutoKeyChange?: (autoKey: boolean) => void;
|
|
27
|
+
/** Keys the selection's animatable properties at the playhead; offered while something is selected. */
|
|
28
|
+
onAddKey?: () => void;
|
|
29
|
+
/** Removes the selection's keys at the playhead; offered while the playhead is on one. */
|
|
30
|
+
onRemoveKey?: () => void;
|
|
31
|
+
/** Moves the selection's keys at `from` to `to`; offered, a diamond drags along the track. */
|
|
32
|
+
onMoveKey?: (from: number, to: number) => void;
|
|
33
|
+
}>;
|
|
34
|
+
|
|
35
|
+
/** The timeline's controls show no focus ring: focus is visible as the playhead and keys respond to the keyboard. */
|
|
36
|
+
const NO_RING = 'focus-visible:ring-0';
|
|
37
|
+
|
|
38
|
+
/** The key at time `t`, if one is within half a frame of it. */
|
|
39
|
+
export const keyAt = (keys: readonly number[], t: number, fps: number): number | undefined =>
|
|
40
|
+
keys.find((key) => Math.abs(key - t) < 0.5 / fps);
|
|
41
|
+
|
|
42
|
+
/** Where ⌘ with an arrow goes from `t`: the next (or previous) key, else the end (or start) when there is none that way. */
|
|
43
|
+
export const jumpTarget = (keys: readonly number[], t: number, fps: number, duration: number, back: boolean): number =>
|
|
44
|
+
(back ? [...keys].reverse().find((key) => key < t - 0.5 / fps) : keys.find((key) => key > t + 0.5 / fps)) ??
|
|
45
|
+
(back ? 0 : duration);
|
|
46
|
+
|
|
47
|
+
/** `t` as `s.ff`, seconds and frames, as an editor's timecode reads. */
|
|
48
|
+
export const formatTime = (t: number, fps: number): string => {
|
|
49
|
+
const frame = Math.round(t * fps);
|
|
50
|
+
const seconds = Math.floor(frame / fps);
|
|
51
|
+
return `${seconds}.${String(frame % fps).padStart(2, '0')}`;
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* The collapsed timeline (react-ui-canvas ANIMATION.md §5.8): play and pause, a track to scrub the playhead along with the selection's
|
|
56
|
+
* keys on it, the time, the key toggle and the auto-key toggle. Dragging the track scrubs; clicking a diamond moves the
|
|
57
|
+
* playhead to it. On the track, the arrows step a frame (with Shift, a second), ⌘ or Ctrl with an arrow jumps to the
|
|
58
|
+
* previous or next key (the start or end when there is none that way), and Delete removes the key under the playhead. On the play button, Left and Right jump to the
|
|
59
|
+
* keys (or ends) with ⌘ or Ctrl and scrub otherwise, Enter keys the playhead, Delete removes the key there and Space plays and pauses.
|
|
60
|
+
*/
|
|
61
|
+
export const TimelineBar = ({
|
|
62
|
+
classNames,
|
|
63
|
+
time,
|
|
64
|
+
duration,
|
|
65
|
+
playing,
|
|
66
|
+
fps,
|
|
67
|
+
keys = [],
|
|
68
|
+
autoKey,
|
|
69
|
+
readonly,
|
|
70
|
+
onPlayingChange,
|
|
71
|
+
onTimeChange,
|
|
72
|
+
onAutoKeyChange,
|
|
73
|
+
onAddKey,
|
|
74
|
+
onRemoveKey,
|
|
75
|
+
onMoveKey,
|
|
76
|
+
}: TimelineBarProps) => {
|
|
77
|
+
const current = keyAt(keys, time, fps);
|
|
78
|
+
// The key being dragged and where it would land; a press that never moves stays a click that seeks.
|
|
79
|
+
const [dragging, setDragging] = useState<{ from: number; to: number }>();
|
|
80
|
+
const trackRef = useRef<HTMLDivElement>(null);
|
|
81
|
+
const timeAt = useCallback(
|
|
82
|
+
(clientX: number) => {
|
|
83
|
+
const track = trackRef.current?.getBoundingClientRect();
|
|
84
|
+
if (!track || track.width === 0 || duration <= 0) {
|
|
85
|
+
return 0;
|
|
86
|
+
}
|
|
87
|
+
// On the frame grid, so a scrub lands where frame stepping and export would.
|
|
88
|
+
const raw = ((clientX - track.left) / track.width) * duration;
|
|
89
|
+
return Math.min(duration, Math.max(0, Math.round(raw * fps) / fps));
|
|
90
|
+
},
|
|
91
|
+
[duration, fps],
|
|
92
|
+
);
|
|
93
|
+
const onPointerDown = useCallback(
|
|
94
|
+
(event: PointerEvent<HTMLDivElement>) => {
|
|
95
|
+
event.stopPropagation();
|
|
96
|
+
event.currentTarget.setPointerCapture(event.pointerId);
|
|
97
|
+
onPlayingChange?.(false);
|
|
98
|
+
onTimeChange?.(timeAt(event.clientX));
|
|
99
|
+
},
|
|
100
|
+
[onPlayingChange, onTimeChange, timeAt],
|
|
101
|
+
);
|
|
102
|
+
const onPointerMove = useCallback(
|
|
103
|
+
(event: PointerEvent<HTMLDivElement>) => {
|
|
104
|
+
if (event.currentTarget.hasPointerCapture(event.pointerId)) {
|
|
105
|
+
onTimeChange?.(timeAt(event.clientX));
|
|
106
|
+
}
|
|
107
|
+
},
|
|
108
|
+
[onTimeChange, timeAt],
|
|
109
|
+
);
|
|
110
|
+
const onKeyDown = useCallback(
|
|
111
|
+
(event: KeyboardEvent<HTMLDivElement>) => {
|
|
112
|
+
if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
|
|
113
|
+
event.preventDefault();
|
|
114
|
+
event.stopPropagation();
|
|
115
|
+
const back = event.key === 'ArrowLeft';
|
|
116
|
+
if (event.metaKey || event.ctrlKey) {
|
|
117
|
+
onTimeChange?.(jumpTarget(keys, time, fps, duration, back));
|
|
118
|
+
return;
|
|
119
|
+
}
|
|
120
|
+
const step = event.shiftKey ? 1 : 1 / fps;
|
|
121
|
+
onTimeChange?.(Math.min(duration, Math.max(0, time + (back ? -step : step))));
|
|
122
|
+
} else if ((event.key === 'Delete' || event.key === 'Backspace') && current !== undefined && onRemoveKey) {
|
|
123
|
+
event.preventDefault();
|
|
124
|
+
event.stopPropagation();
|
|
125
|
+
onRemoveKey();
|
|
126
|
+
}
|
|
127
|
+
},
|
|
128
|
+
[time, duration, fps, keys, current, onTimeChange, onRemoveKey],
|
|
129
|
+
);
|
|
130
|
+
const at = (t: number) => `${duration > 0 ? (t / duration) * 100 : 0}%`;
|
|
131
|
+
return (
|
|
132
|
+
<Toolbar.Root classNames={mx('min-w-[24rem]', classNames)} data-testid='timeline'>
|
|
133
|
+
<Button.Root
|
|
134
|
+
variant='ghost'
|
|
135
|
+
iconOnly
|
|
136
|
+
classNames={NO_RING}
|
|
137
|
+
icon={playing ? 'ph--pause--regular' : 'ph--play--regular'}
|
|
138
|
+
label={playing ? 'Pause' : 'Play'}
|
|
139
|
+
data-testid='timeline-play'
|
|
140
|
+
// Focused, the button drives the playhead and keys: Left and Right scrub a frame (Shift, a second), with ⌘ or
|
|
141
|
+
// Ctrl they jump to the next key, or the end when there is none; Enter keys the playhead (unless it is on a key)
|
|
142
|
+
// and Delete removes the key there. Space, the button's own key, plays and pauses.
|
|
143
|
+
onKeyDown={(event) => {
|
|
144
|
+
if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
|
|
145
|
+
event.preventDefault();
|
|
146
|
+
event.stopPropagation();
|
|
147
|
+
onPlayingChange?.(false);
|
|
148
|
+
const back = event.key === 'ArrowLeft';
|
|
149
|
+
if (event.metaKey || event.ctrlKey) {
|
|
150
|
+
onTimeChange?.(jumpTarget(keys, time, fps, duration, back));
|
|
151
|
+
} else {
|
|
152
|
+
const step = event.shiftKey ? 1 : 1 / fps;
|
|
153
|
+
onTimeChange?.(Math.min(duration, Math.max(0, time + (back ? -step : step))));
|
|
154
|
+
}
|
|
155
|
+
} else if (event.key === 'Enter') {
|
|
156
|
+
// Enter keys rather than presses: preventing it here keeps the button from playing.
|
|
157
|
+
event.preventDefault();
|
|
158
|
+
event.stopPropagation();
|
|
159
|
+
if (current === undefined && onAddKey && !readonly) {
|
|
160
|
+
onAddKey();
|
|
161
|
+
}
|
|
162
|
+
} else if ((event.key === 'Delete' || event.key === 'Backspace') && current !== undefined && onRemoveKey) {
|
|
163
|
+
event.preventDefault();
|
|
164
|
+
event.stopPropagation();
|
|
165
|
+
onRemoveKey();
|
|
166
|
+
}
|
|
167
|
+
}}
|
|
168
|
+
onClick={() => {
|
|
169
|
+
// Played from the end, the timeline starts over.
|
|
170
|
+
if (!playing && time >= duration) {
|
|
171
|
+
onTimeChange?.(0);
|
|
172
|
+
}
|
|
173
|
+
onPlayingChange?.(!playing);
|
|
174
|
+
}}
|
|
175
|
+
/>
|
|
176
|
+
<div
|
|
177
|
+
ref={trackRef}
|
|
178
|
+
role='slider'
|
|
179
|
+
tabIndex={0}
|
|
180
|
+
aria-label='Playhead'
|
|
181
|
+
aria-valuemin={0}
|
|
182
|
+
aria-valuemax={duration}
|
|
183
|
+
aria-valuenow={time}
|
|
184
|
+
aria-valuetext={`${formatTime(time, fps)} s`}
|
|
185
|
+
className='relative grow h-6 mx-2 cursor-pointer touch-none outline-none rounded-xs'
|
|
186
|
+
data-testid='timeline-track'
|
|
187
|
+
onPointerDown={onPointerDown}
|
|
188
|
+
onPointerMove={onPointerMove}
|
|
189
|
+
onKeyDown={onKeyDown}
|
|
190
|
+
>
|
|
191
|
+
<div className='absolute inset-x-0 top-1/2 h-0.5 -translate-y-1/2 bg-separator rounded-full' />
|
|
192
|
+
<div
|
|
193
|
+
className='absolute left-0 top-1/2 h-0.5 -translate-y-1/2 bg-accent-bg rounded-full'
|
|
194
|
+
style={{ width: at(time) }}
|
|
195
|
+
/>
|
|
196
|
+
{keys.map((key) => {
|
|
197
|
+
const shown = dragging?.from === key ? dragging.to : key;
|
|
198
|
+
return (
|
|
199
|
+
<button
|
|
200
|
+
key={key}
|
|
201
|
+
type='button'
|
|
202
|
+
aria-label={`Key at ${formatTime(key, fps)} s`}
|
|
203
|
+
className={mx(
|
|
204
|
+
'absolute top-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rotate-45 border border-separator',
|
|
205
|
+
onMoveKey && !readonly && 'cursor-ew-resize',
|
|
206
|
+
key === current || dragging?.from === key ? 'bg-amber-300 ring-1 ring-amber-300' : 'bg-amber-500',
|
|
207
|
+
)}
|
|
208
|
+
style={{ left: at(shown) }}
|
|
209
|
+
data-testid='timeline-key'
|
|
210
|
+
onPointerDown={(event) => {
|
|
211
|
+
event.stopPropagation();
|
|
212
|
+
onPlayingChange?.(false);
|
|
213
|
+
onTimeChange?.(key);
|
|
214
|
+
if (onMoveKey && !readonly) {
|
|
215
|
+
event.currentTarget.setPointerCapture(event.pointerId);
|
|
216
|
+
setDragging({ from: key, to: key });
|
|
217
|
+
}
|
|
218
|
+
}}
|
|
219
|
+
onPointerMove={(event) => {
|
|
220
|
+
if (dragging?.from === key) {
|
|
221
|
+
const to = timeAt(event.clientX);
|
|
222
|
+
setDragging({ from: key, to });
|
|
223
|
+
onTimeChange?.(to);
|
|
224
|
+
}
|
|
225
|
+
}}
|
|
226
|
+
onPointerUp={() => {
|
|
227
|
+
if (dragging?.from === key && dragging.to !== key) {
|
|
228
|
+
onMoveKey?.(key, dragging.to);
|
|
229
|
+
}
|
|
230
|
+
setDragging(undefined);
|
|
231
|
+
}}
|
|
232
|
+
onPointerCancel={() => setDragging(undefined)}
|
|
233
|
+
/>
|
|
234
|
+
);
|
|
235
|
+
})}
|
|
236
|
+
<div
|
|
237
|
+
className='absolute top-0 bottom-0 w-0.5 -translate-x-1/2 bg-accent-bg pointer-events-none'
|
|
238
|
+
style={{ left: at(time) }}
|
|
239
|
+
data-testid='timeline-playhead'
|
|
240
|
+
/>
|
|
241
|
+
</div>
|
|
242
|
+
<span
|
|
243
|
+
className='shrink-0 text-end text-sm whitespace-nowrap tabular-nums text-fg-muted'
|
|
244
|
+
data-testid='timeline-time'
|
|
245
|
+
>
|
|
246
|
+
{formatTime(time, fps)} / {formatTime(duration, fps)}
|
|
247
|
+
</span>
|
|
248
|
+
{!readonly && (
|
|
249
|
+
<>
|
|
250
|
+
{/* The less frequent actions, in one menu: the keyboard covers keying from the play button. */}
|
|
251
|
+
<Menu.Root positioning={{ placement: 'top-end', gutter: 4 }}>
|
|
252
|
+
<Menu.Trigger asChild>
|
|
253
|
+
<Button.Root
|
|
254
|
+
variant='ghost'
|
|
255
|
+
iconOnly
|
|
256
|
+
classNames={NO_RING}
|
|
257
|
+
icon='ph--dots-three-vertical--regular'
|
|
258
|
+
label='Timeline actions'
|
|
259
|
+
data-testid='timeline-menu'
|
|
260
|
+
/>
|
|
261
|
+
</Menu.Trigger>
|
|
262
|
+
<Menu.Content>
|
|
263
|
+
<Menu.Item
|
|
264
|
+
item={{ value: 'add-key', label: 'Add key', shortcut: '↵' }}
|
|
265
|
+
disabled={current !== undefined || !onAddKey}
|
|
266
|
+
data-testid='timeline-add-key'
|
|
267
|
+
onSelect={() => onAddKey?.()}
|
|
268
|
+
/>
|
|
269
|
+
<Menu.Item
|
|
270
|
+
item={{ value: 'remove-key', label: 'Delete key', shortcut: '⌫' }}
|
|
271
|
+
disabled={current === undefined || !onRemoveKey}
|
|
272
|
+
data-testid='timeline-remove-key'
|
|
273
|
+
onSelect={() => onRemoveKey?.()}
|
|
274
|
+
/>
|
|
275
|
+
<Menu.Separator />
|
|
276
|
+
<Menu.CheckboxItem
|
|
277
|
+
item={{ value: 'auto-key', label: 'Auto-key' }}
|
|
278
|
+
checked={!!autoKey}
|
|
279
|
+
data-testid='timeline-auto-key'
|
|
280
|
+
onCheckedChange={(checked) => onAutoKeyChange?.(checked === true)}
|
|
281
|
+
/>
|
|
282
|
+
</Menu.Content>
|
|
283
|
+
</Menu.Root>
|
|
284
|
+
</>
|
|
285
|
+
)}
|
|
286
|
+
</Toolbar.Root>
|
|
287
|
+
);
|
|
288
|
+
};
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import { useAtomValue } from '@effect/atom-react/Hooks';
|
|
6
|
+
import { RegistryContext } from '@effect/atom-react/RegistryContext';
|
|
7
|
+
import { useContext, useEffect, useRef } from 'react';
|
|
8
|
+
|
|
9
|
+
import { type Clock, MAX_CLOCK_STEP } from '@dxos/animation';
|
|
10
|
+
|
|
11
|
+
export type UseClockOptions = {
|
|
12
|
+
/** Seconds; playback stops (or wraps) there. Unbounded when unset or zero. */
|
|
13
|
+
duration?: number;
|
|
14
|
+
loop?: boolean;
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* A clock's one animation loop (react-ui-canvas ANIMATION.md §5.1): while the clock plays, each frame advances its
|
|
19
|
+
* time by the wall time since the last, capped at `MAX_CLOCK_STEP`. The first frame after a start advances nothing, so
|
|
20
|
+
* no step is ever negative. Reading the wall clock is this hook's alone; everything animated reads the clock's time.
|
|
21
|
+
*/
|
|
22
|
+
export const useClock = (clock: Clock, { duration = 0, loop = false }: UseClockOptions = {}): void => {
|
|
23
|
+
const registry = useContext(RegistryContext);
|
|
24
|
+
const playing = useAtomValue(clock.playing);
|
|
25
|
+
// Read per frame, so a change of length or looping does not restart the loop (a restart's first step is empty).
|
|
26
|
+
const boundsRef = useRef({ duration, loop });
|
|
27
|
+
boundsRef.current = { duration, loop };
|
|
28
|
+
useEffect(() => {
|
|
29
|
+
if (!playing) {
|
|
30
|
+
return;
|
|
31
|
+
}
|
|
32
|
+
let last: number | undefined;
|
|
33
|
+
let frame = requestAnimationFrame(function step() {
|
|
34
|
+
const now = performance.now();
|
|
35
|
+
const seconds = last === undefined ? 0 : Math.min(MAX_CLOCK_STEP, Math.max(0, (now - last) / 1000));
|
|
36
|
+
last = now;
|
|
37
|
+
if (seconds > 0) {
|
|
38
|
+
const { duration, loop } = boundsRef.current;
|
|
39
|
+
const next = registry.get(clock.time) + seconds * registry.get(clock.rate);
|
|
40
|
+
if (duration > 0 && next >= duration) {
|
|
41
|
+
if (loop) {
|
|
42
|
+
registry.set(clock.time, next % duration);
|
|
43
|
+
} else {
|
|
44
|
+
registry.set(clock.time, duration);
|
|
45
|
+
registry.set(clock.playing, false);
|
|
46
|
+
return;
|
|
47
|
+
}
|
|
48
|
+
} else {
|
|
49
|
+
registry.set(clock.time, next);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
frame = requestAnimationFrame(step);
|
|
53
|
+
});
|
|
54
|
+
return () => cancelAnimationFrame(frame);
|
|
55
|
+
}, [playing, registry, clock]);
|
|
56
|
+
};
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import type * as Registry from 'effect/reactivity/AtomRegistry';
|
|
6
|
+
import { useEffect, useRef } from 'react';
|
|
7
|
+
|
|
8
|
+
import { type Clock, DEFAULT_FPS, type Timeline, exposeClock } from '@dxos/animation';
|
|
9
|
+
|
|
10
|
+
/** What a frame renderer exports: the clock's length and rate. */
|
|
11
|
+
export type ExposedSpan = Pick<Timeline, 'duration' | 'fps'>;
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Publishes a clock for a frame renderer, which seeks the clock rather than faking the browser's
|
|
15
|
+
* (react-ui-canvas ANIMATION.md §7.2); `exportable` off, nothing is published.
|
|
16
|
+
*/
|
|
17
|
+
export const useExposedClock = (
|
|
18
|
+
registry: Registry.AtomRegistry,
|
|
19
|
+
clock: Clock,
|
|
20
|
+
span: ExposedSpan | undefined,
|
|
21
|
+
exportable: boolean | undefined,
|
|
22
|
+
) => {
|
|
23
|
+
const spanRef = useRef<ExposedSpan | undefined>(span);
|
|
24
|
+
spanRef.current = span;
|
|
25
|
+
useEffect(
|
|
26
|
+
() =>
|
|
27
|
+
exportable
|
|
28
|
+
? exposeClock(registry, clock, () => ({
|
|
29
|
+
duration: spanRef.current?.duration ?? 0,
|
|
30
|
+
fps: spanRef.current?.fps ?? DEFAULT_FPS,
|
|
31
|
+
}))
|
|
32
|
+
: undefined,
|
|
33
|
+
[exportable, registry, clock],
|
|
34
|
+
);
|
|
35
|
+
};
|