@steamfield/decks 0.0.0-stage → 1.0.0-rc.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 +201 -0
- package/README.md +28 -2
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +5 -0
- package/dist/index-B2n69xrC.d.ts +75 -0
- package/dist/index-BURtH7IB.d.ts +182 -0
- package/dist/index-BV_-6L5L.d.ts +136 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +6 -0
- package/dist/kit/chrome/od-byline.css +7 -0
- package/dist/kit/chrome/od-cover-head.css +10 -0
- package/dist/kit/chrome/od-eyebrow.css +13 -0
- package/dist/kit/chrome/od-logo.css +167 -0
- package/dist/kit/chrome/od-qr-card.css +30 -0
- package/dist/kit/ink/code-ink.css +83 -0
- package/dist/kit/ink/graph-3d.css +29 -0
- package/dist/kit/ink/ink-bars.css +7 -0
- package/dist/kit/ink/ink-card-rect.css +6 -0
- package/dist/kit/ink/ink-chip.css +62 -0
- package/dist/kit/ink/ink-line.css +7 -0
- package/dist/kit/ink/ink-number.css +22 -0
- package/dist/kit/ink/ink-ping.css +4 -0
- package/dist/kit/ink/ink-rule.css +4 -0
- package/dist/kit/ink/ink-timeline-cursor.css +3 -0
- package/dist/kit/ink/ink-timeline.css +9 -0
- package/dist/kit/ink/underline.css +12 -0
- package/dist/kit/ink/unit-grid.css +3 -0
- package/dist/kit/story/story-card.css +19 -0
- package/dist/kit/story/story-link.css +13 -0
- package/dist/kit/story/story-stage.css +59 -0
- package/dist/kit/styles/base.css +82 -0
- package/dist/kit/styles/compat.css +78 -0
- package/dist/kit/styles/components.css +224 -0
- package/dist/kit/styles/fonts/inter-cyrillic-ext-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-cyrillic-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-greek-ext-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-greek-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-latin-ext-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-latin-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts/inter-vietnamese-wght-normal.woff2 +0 -0
- package/dist/kit/styles/fonts.css +73 -0
- package/dist/kit/styles/index.css +36 -0
- package/dist/kit/styles/layout.css +181 -0
- package/dist/kit/styles/stats.css +92 -0
- package/dist/kit/styles/story-frame.css +179 -0
- package/dist/kit/styles/story-marks.css +115 -0
- package/dist/kit/styles/story-transition.css +182 -0
- package/dist/kit/styles.css +1 -0
- package/dist/kit.d.ts +880 -0
- package/dist/kit.js +3475 -0
- package/dist/layers.css +60 -0
- package/dist/layouts.css +58 -0
- package/dist/lint/ai-rhetoric-patterns.tsv +110 -0
- package/dist/lint/deck-writing-reminder.md +9 -0
- package/dist/motion.css +215 -0
- package/dist/motion.d.ts +2 -0
- package/dist/motion.js +1 -0
- package/dist/node.d.ts +63 -0
- package/dist/node.js +1 -0
- package/dist/overview-view.css +58 -0
- package/dist/play-view.css +29 -0
- package/dist/plugin/skills/building-a-deck/SKILL.md +22 -0
- package/dist/plugin/skills/building-a-deck/references/workflow.md +86 -0
- package/dist/plugin/skills/deck-data/SKILL.md +27 -0
- package/dist/plugin/skills/deck-data/references/fact-check.md +59 -0
- package/dist/plugin/skills/deck-data/references/provenance.md +61 -0
- package/dist/plugin/skills/deck-design/SKILL.md +31 -0
- package/dist/plugin/skills/deck-design/references/layout.md +55 -0
- package/dist/plugin/skills/deck-motion/SKILL.md +34 -0
- package/dist/plugin/skills/deck-motion/references/motion.md +66 -0
- package/dist/plugin/skills/visualization/SKILL.md +34 -0
- package/dist/plugin/skills/visualization/references/VENDORED.md +25 -0
- package/dist/plugin/skills/visualization/references/annotations.md +27 -0
- package/dist/plugin/skills/visualization/references/chart-selection.md +29 -0
- package/dist/plugin/skills/visualization/references/color-strategy.md +22 -0
- package/dist/plugin/skills/visualization/references/encoding-channels.md +44 -0
- package/dist/plugin/skills/visualization/references/ink.md +38 -0
- package/dist/plugin/skills/visualization/references/marks.md +33 -0
- package/dist/plugin/skills/visualization/references/presentation.md +43 -0
- package/dist/plugin/skills/working-with-decks/SKILL.md +34 -0
- package/dist/plugin/skills/working-with-decks/references/project.md +59 -0
- package/dist/plugin/skills/writing-slides/SKILL.md +45 -0
- package/dist/plugin/skills/writing-slides/references/lint.md +11 -0
- package/dist/plugin/skills/writing-slides/references/prose-patterns.md +48 -0
- package/dist/presenter-view.css +113 -0
- package/dist/print-view.module.css +32 -0
- package/dist/prose-patterns-DPqjGBFu.js +76 -0
- package/dist/prose-scan-BrWZ7gxZ.js +233 -0
- package/dist/src-C-OfT72W.js +396 -0
- package/dist/src-CmQgaG1b.js +2469 -0
- package/dist/src-DizFoqYt.js +1508 -0
- package/dist/templates/conventional/deck.config.ts +7 -0
- package/dist/templates/conventional/setup.ts +3 -0
- package/dist/templates/conventional/slides/01-cover.mdx +9 -0
- package/dist/templates/conventional/slides/02-first-point.mdx +12 -0
- package/dist/templates/conventional/styles/index.css +1 -0
- package/dist/templates/story/components/FirstStage.tsx +34 -0
- package/dist/templates/story/data/01-first.ts +8 -0
- package/dist/templates/story/data-sources.md +7 -0
- package/dist/templates/story/deck.config.ts +8 -0
- package/dist/templates/story/setup.ts +3 -0
- package/dist/templates/story/slides/01-cover.mdx +9 -0
- package/dist/templates/story/slides/02-first-point.mdx +6 -0
- package/dist/templates/story/styles/index.css +1 -0
- package/dist/transition.css +87 -0
- package/docs/README.md +28 -0
- package/docs/canvas.md +134 -0
- package/docs/cli.md +49 -0
- package/docs/code-blocks.md +132 -0
- package/docs/config.md +183 -0
- package/docs/getting-started.md +204 -0
- package/docs/kit.md +371 -0
- package/docs/migrating-from-slidev.md +45 -0
- package/docs/motion.md +396 -0
- package/docs/presenting.md +99 -0
- package/docs/slides.md +246 -0
- package/package.json +108 -4
package/docs/motion.md
ADDED
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
# Motion
|
|
2
|
+
|
|
3
|
+
Motion in a deck is driven by clicks. A slide has a click total; each key press moves one click forward or back; components decide what to show from the current click. Everything on this page is exported by `@steamfield/decks/motion`, and the components are available in slides without an import.
|
|
4
|
+
|
|
5
|
+
## Click steps
|
|
6
|
+
|
|
7
|
+
A slide with a click total of 3 has four states: click 0 (as it first appears), then 1, 2 and 3. The right arrow goes to the next click and, after the last one, to the next slide. The left arrow reverses that and enters the previous slide at its last click.
|
|
8
|
+
|
|
9
|
+
The click is in the URL (`#/5?clicks=2`), so a reload or a shared link lands on the same state.
|
|
10
|
+
|
|
11
|
+
### How the total is counted
|
|
12
|
+
|
|
13
|
+
When a slide's frontmatter has no `clicks`, the total is read from the MDX source at build time. It is the largest of these contributions, or 0:
|
|
14
|
+
|
|
15
|
+
| Written in the slide | Contributes |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| `Step`, `Stagger`, `Highlight`, `Draw` with `at` and optional `until` | `until` if present, else `at` |
|
|
18
|
+
| `TextReveal`, `CountUp` with `at` | `at` |
|
|
19
|
+
| `Steps` with `from` and `k` children (JSX elements, or one list with `k` items) | `from + k - 1` |
|
|
20
|
+
| A fenced code block with `k` highlight steps and `at=<n>` | `at + k - 1` (see [code-blocks.md](code-blocks.md)) |
|
|
21
|
+
|
|
22
|
+
So this slide has two clicks with no `clicks:` line:
|
|
23
|
+
|
|
24
|
+
```mdx
|
|
25
|
+
<Step at={1}>First</Step>
|
|
26
|
+
<Step at={2}>Second</Step>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The count is static. It reads the source and never runs it, which sets these rules:
|
|
30
|
+
|
|
31
|
+
- `at`, `until` and `from` must be literal whole numbers: `at={2}`. An expression, a string or a negative number is an error.
|
|
32
|
+
- `until` must be greater than `at`.
|
|
33
|
+
- No spread attributes on a counted element (`<Step {...props}>`).
|
|
34
|
+
- No counted element inside a JavaScript expression (`{show && <Step at={1} />}`, a `.map()`).
|
|
35
|
+
- Children of `Steps` must be JSX elements or a single markdown list.
|
|
36
|
+
- A motion component counts under another name when a file in `components/` re-exports it from `@steamfield/decks/motion` (`export { Step as Reveal } from "@steamfield/decks/motion"`), or when the slide imports it from there.
|
|
37
|
+
- A deck component that only shares a name with a motion component (`components/Step.tsx`) is not counted.
|
|
38
|
+
|
|
39
|
+
Steps inside a deck component are not seen, and neither is a component that paces itself from `useSlide().clicks` or `useTimeline`. Such a slide sets the total itself:
|
|
40
|
+
|
|
41
|
+
```mdx
|
|
42
|
+
---
|
|
43
|
+
title: useTimeline
|
|
44
|
+
clicks: 3
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
<TimelineScene />
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
When `clicks:` is present it wins, and none of the rules above raise an error.
|
|
51
|
+
|
|
52
|
+
## Step components
|
|
53
|
+
|
|
54
|
+
Every step component takes `at`, the click at which it appears. The ones that can leave take `until`, the click at which they go.
|
|
55
|
+
|
|
56
|
+
A step is always rendered, so it keeps its place in the layout while hidden. A hidden step is `aria-hidden` and `inert`. Going back a click plays the same transition in reverse.
|
|
57
|
+
|
|
58
|
+
Presets, used by `enter` and `exit` (both default to `fade`):
|
|
59
|
+
|
|
60
|
+
| Preset | Start pose |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `fade` | Transparent. |
|
|
63
|
+
| `rise` | Transparent, 24px below. |
|
|
64
|
+
| `drop` | Transparent, 24px above. |
|
|
65
|
+
| `scale` | Transparent, scaled to 0.92. |
|
|
66
|
+
| `blur` | Transparent, blurred 12px. |
|
|
67
|
+
| `wipe` | Clipped from the right. |
|
|
68
|
+
|
|
69
|
+
The examples below are from `examples/motion/slides/`.
|
|
70
|
+
|
|
71
|
+
### `Step`
|
|
72
|
+
|
|
73
|
+
Shows its children from click `at`, and hides them again from `until` if given.
|
|
74
|
+
|
|
75
|
+
```mdx
|
|
76
|
+
<Step at={1} until={2} enter="rise" exit="rise">
|
|
77
|
+
<div className="hero-card">Make room for the idea.</div>
|
|
78
|
+
</Step>
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Props: `at`, `until`, `enter`, `exit`, `as` (`"div"` by default; also `"span"`, `"li"`, `"p"`, `"g"` for use inside an SVG), `className`.
|
|
82
|
+
|
|
83
|
+
### `Steps`
|
|
84
|
+
|
|
85
|
+
One click per child, starting at `from`. A markdown list as its only child reveals one item per click.
|
|
86
|
+
|
|
87
|
+
```mdx
|
|
88
|
+
<Steps from={1} enter="rise" className="sequence">
|
|
89
|
+
|
|
90
|
+
1. Frame the question.
|
|
91
|
+
2. Reveal the evidence.
|
|
92
|
+
3. Connect the pieces.
|
|
93
|
+
4. Leave a clear next step.
|
|
94
|
+
|
|
95
|
+
</Steps>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Props: `from`, `enter`, `as` (`"div"` by default; `"ul"` or `"ol"` wraps each child in an `li`), `className`.
|
|
99
|
+
|
|
100
|
+
### `Stagger`
|
|
101
|
+
|
|
102
|
+
One click for the whole group. The children enter one after another, 60ms apart.
|
|
103
|
+
|
|
104
|
+
```mdx
|
|
105
|
+
<Stagger at={1} until={2} enter="rise" className="cards">
|
|
106
|
+
<div>Notice</div>
|
|
107
|
+
<div>Compare</div>
|
|
108
|
+
<div>Connect</div>
|
|
109
|
+
</Stagger>
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Props: `at`, `until`, `enter`, `as` (`"div"`, `"ul"`, `"ol"`), `className`.
|
|
113
|
+
|
|
114
|
+
### `TextReveal`
|
|
115
|
+
|
|
116
|
+
Reveals text word by word or character by character on one click. Its child must be a plain string. Screen readers get the whole text at once.
|
|
117
|
+
|
|
118
|
+
```mdx
|
|
119
|
+
<TextReveal at={1} by="word" enter="rise">One idea deserves a moment.</TextReveal>
|
|
120
|
+
|
|
121
|
+
<TextReveal at={1} by="char" enter="blur">{"Stay\ncurious."}</TextReveal>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Props: `at`, `by` (`"word"` by default, or `"char"`), `enter`.
|
|
125
|
+
|
|
126
|
+
### `Highlight`
|
|
127
|
+
|
|
128
|
+
Sweeps a marker stroke behind inline text from click `at`. The text itself is always visible.
|
|
129
|
+
|
|
130
|
+
```mdx
|
|
131
|
+
Give <Highlight at={1} until={2}>the important part</Highlight> a little space.
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Props: `at`, `until`. Set the color with the `--deck-highlight` CSS variable; the default is a translucent version of the text color.
|
|
135
|
+
|
|
136
|
+
### `CountUp`
|
|
137
|
+
|
|
138
|
+
Shows `from` before click `at` and counts to `to` on it. Going back shows `from` at once.
|
|
139
|
+
|
|
140
|
+
```mdx
|
|
141
|
+
<CountUp at={1} from={0} to={1200} />
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Props: `at`, `from` (default 0), `to`, `format` (a function from the number to a string; the default rounds and adds thousands separators).
|
|
145
|
+
|
|
146
|
+
### `Draw`
|
|
147
|
+
|
|
148
|
+
Draws the strokes of its SVG shape children on click `at`. It renders a `<g>`, so it goes inside an `<svg>`. Direct children that are `path`, `line`, `polyline`, `polygon`, `circle`, `ellipse` or `rect` are drawn; give them a stroke in CSS.
|
|
149
|
+
|
|
150
|
+
```mdx
|
|
151
|
+
<svg className="drawing" viewBox="0 0 1400 500" role="img" aria-label="A rising curve">
|
|
152
|
+
<Draw at={1} until={2}>
|
|
153
|
+
<path d="M 80 400 C 340 400 220 150 520 260 S 890 450 1320 60" />
|
|
154
|
+
</Draw>
|
|
155
|
+
</svg>
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Props: `at`, `until`.
|
|
159
|
+
|
|
160
|
+
## Hooks
|
|
161
|
+
|
|
162
|
+
### `useStepState(at, until?)`
|
|
163
|
+
|
|
164
|
+
Returns the state of a step on the current slide: `"before"`, `"current"`, `"after"` or `"gone"`. Use it to build a step component of your own.
|
|
165
|
+
|
|
166
|
+
```tsx
|
|
167
|
+
import { useStepState } from "@steamfield/decks/motion";
|
|
168
|
+
|
|
169
|
+
export function Callout({ at }: { at: number }) {
|
|
170
|
+
const state = useStepState(at);
|
|
171
|
+
return <aside className={state === "before" ? "callout is-waiting" : "callout"}>Look here</aside>;
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
A component like this is not counted, so its slide sets `clicks:`.
|
|
176
|
+
|
|
177
|
+
### `useTween(initial)`
|
|
178
|
+
|
|
179
|
+
Returns a stable object of numbers that gsap can tween. The component re-renders as the values change, so you read them in JSX like any other value.
|
|
180
|
+
|
|
181
|
+
```tsx
|
|
182
|
+
const value = useTween({ radius: 48 });
|
|
183
|
+
// ...
|
|
184
|
+
<circle cx="750" cy="260" r={value.radius} />
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Only the fields present in `initial` cause a render. Use it with `useTimeline`, or with `gsap.to(value, { ... })` in an effect.
|
|
188
|
+
|
|
189
|
+
### `useTimeline(build, deps?)`
|
|
190
|
+
|
|
191
|
+
Builds a paused gsap timeline with one label per click and keeps it positioned at the slide's click. `examples/motion/components/TimelineScene.tsx`:
|
|
192
|
+
|
|
193
|
+
```tsx
|
|
194
|
+
import { duration, useTimeline, useTween } from "@steamfield/decks/motion";
|
|
195
|
+
|
|
196
|
+
export function TimelineScene() {
|
|
197
|
+
const value = useTween({ x: 0, turn: 0, color: 0 });
|
|
198
|
+
useTimeline(
|
|
199
|
+
(tl, beat) => {
|
|
200
|
+
beat(0);
|
|
201
|
+
tl.to(value, { x: 320, duration: duration.slow });
|
|
202
|
+
beat(1);
|
|
203
|
+
tl.to(value, { x: 640, color: 1, duration: duration.slow });
|
|
204
|
+
beat(2);
|
|
205
|
+
tl.to(value, { x: 960, turn: 90, color: 2, duration: duration.slow });
|
|
206
|
+
beat(3);
|
|
207
|
+
},
|
|
208
|
+
[value],
|
|
209
|
+
);
|
|
210
|
+
// render from value.x, value.turn, value.color
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`beat(n)` marks where click `n` rests. The tweens between `beat(1)` and `beat(2)` play on the second click.
|
|
215
|
+
|
|
216
|
+
- Call `beat(0)` first, before adding any tween, then `beat(1)`, `beat(2)` in order. Anything else throws, naming the label.
|
|
217
|
+
- A click past the last beat stays on the last beat.
|
|
218
|
+
- One click forward or back on the active slide plays to the label. A second press mid-tween continues from the visible position.
|
|
219
|
+
- Everything else seeks with no animation: the first positioning, a jump of more than one click, an inactive slide, a context other than `slide`, and instant motion.
|
|
220
|
+
- The timeline is rebuilt when `deps` change. A rebuilt timeline of `.to()` tweens starts from whatever the last one left, so a timeline whose `deps` change uses `fromTo`.
|
|
221
|
+
- The slide must set `clicks:` to the number of the last beat.
|
|
222
|
+
|
|
223
|
+
## Motion tokens
|
|
224
|
+
|
|
225
|
+
Use the tokens instead of raw durations and curves, in JavaScript and in CSS. They are the same values.
|
|
226
|
+
|
|
227
|
+
| JavaScript | CSS variable | Value |
|
|
228
|
+
| --- | --- | --- |
|
|
229
|
+
| `duration.quick` | `--deck-dur-quick` | 0.14 s / 140ms |
|
|
230
|
+
| `duration.base` | `--deck-dur-base` | 0.3 s / 300ms |
|
|
231
|
+
| `duration.slow` | `--deck-dur-slow` | 0.6 s / 600ms |
|
|
232
|
+
| `stagger` | `--deck-stagger` | 0.06 s / 60ms |
|
|
233
|
+
| `ease.enter` | `--deck-ease-enter` | `cubic-bezier(0.16, 1, 0.3, 1)` |
|
|
234
|
+
| `ease.exit` | `--deck-ease-exit` | `cubic-bezier(0.7, 0, 0.84, 0)` |
|
|
235
|
+
| `ease.settle` | `--deck-ease-settle` | `cubic-bezier(0.32, 0.72, 0, 1)` |
|
|
236
|
+
| `ease.draw` | `--deck-ease-draw` | `cubic-bezier(0.65, 0, 0.35, 1)` |
|
|
237
|
+
|
|
238
|
+
The JavaScript `ease` values are gsap ease names, and `ease.settle` is gsap's default ease.
|
|
239
|
+
|
|
240
|
+
```tsx
|
|
241
|
+
import { duration, ease, gsap } from "@steamfield/decks/motion";
|
|
242
|
+
|
|
243
|
+
gsap.to(target, { opacity: 1, duration: duration.base, ease: ease.enter });
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
```css
|
|
247
|
+
.panel {
|
|
248
|
+
transition: opacity var(--deck-dur-base) var(--deck-ease-settle);
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
Import `gsap` from `@steamfield/decks/motion` (or from the kit, which re-exports it), not from the `gsap` package, so a deck has one instance with the eases registered. When motion is instant the CSS durations and the stagger are `0ms`, so a CSS transition written on the tokens needs no special case.
|
|
253
|
+
|
|
254
|
+
## Slide transitions
|
|
255
|
+
|
|
256
|
+
Set a deck's default transition in `deck.config.ts` and override it per slide in frontmatter.
|
|
257
|
+
|
|
258
|
+
```ts
|
|
259
|
+
export default defineDeck({ title: "Motion gallery", transition: "fade" });
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
```mdx
|
|
263
|
+
---
|
|
264
|
+
title: Transition / push
|
|
265
|
+
transition: push
|
|
266
|
+
---
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
A slide's `transition` applies to the boundary between it and the next slide, in both directions. Going from slide 4 to 5, or back from 5 to 4, uses slide 4's `transition`, then the deck's, then `fade`. A jump of more than one slide uses the deck's, then `fade`.
|
|
270
|
+
|
|
271
|
+
| Name | What happens |
|
|
272
|
+
| --- | --- |
|
|
273
|
+
| `fade` | Cross-fade over `--deck-dur-base`. The default. |
|
|
274
|
+
| `push` | The old slide slides out and the new one in, horizontally, over `--deck-dur-slow`. The direction follows the navigation. |
|
|
275
|
+
| `zoom` | The old slide scales up and fades while the new one scales in, reversed going back, over `--deck-dur-slow`. |
|
|
276
|
+
| `cut` | No transition. |
|
|
277
|
+
| `story` | Provided by the kit's stylesheet. See [kit.md](kit.md). |
|
|
278
|
+
|
|
279
|
+
Transitions use the browser's View Transitions API. A change is applied with no animation when the browser lacks the API, motion is instant, the view is not the play view, or the target slide's module has not loaded yet.
|
|
280
|
+
|
|
281
|
+
To define your own, pick a name, use it in `transition`, and style the root snapshots. While a transition runs, `<html>` has `data-deck-transition="<name>"` and `data-deck-nav="forward"` or `"backward"`.
|
|
282
|
+
|
|
283
|
+
```css
|
|
284
|
+
html[data-deck-transition="lift"]::view-transition-old(root) {
|
|
285
|
+
animation: lift-out var(--deck-dur-slow) var(--deck-ease-settle) both;
|
|
286
|
+
}
|
|
287
|
+
html[data-deck-transition="lift"]::view-transition-new(root) {
|
|
288
|
+
animation: lift-in var(--deck-dur-slow) var(--deck-ease-settle) both;
|
|
289
|
+
}
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
A name with no CSS gets the browser's default cross-fade.
|
|
293
|
+
|
|
294
|
+
A deck's `layers/above.tsx` holds still while slides transition under it. See [config.md](config.md).
|
|
295
|
+
|
|
296
|
+
## `Morph`
|
|
297
|
+
|
|
298
|
+
`Morph` gives an element an identity that survives a slide change. Put a `Morph` with the same `name` on two neighbouring slides and the element moves and resizes from its old place to its new one while the rest of the slide transitions.
|
|
299
|
+
|
|
300
|
+
`examples/motion/slides/20-morph-start.mdx` and `21-morph-end.mdx`:
|
|
301
|
+
|
|
302
|
+
```mdx
|
|
303
|
+
<Morph name="gallery-card" className="morph-card compact">
|
|
304
|
+
<strong>Room to grow.</strong>
|
|
305
|
+
</Morph>
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
```mdx
|
|
309
|
+
<Morph name="gallery-card" className="morph-card expanded">
|
|
310
|
+
<strong>Room to grow.</strong>
|
|
311
|
+
</Morph>
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Props: `name`, `as` (`"div"` by default; also `"span"`, `"h1"`, `"h2"`, `"h3"`, `"p"`, `"figure"`, `"g"`), `className`.
|
|
315
|
+
|
|
316
|
+
- `name` must be a CSS identifier starting with a letter or underscore. CSS keywords (`none`, `auto`, `root`, `inherit` and the like) and `deck-layer-above` are reserved. A bad name throws.
|
|
317
|
+
- Use each name once per slide.
|
|
318
|
+
- The morph works under any transition preset except `cut`.
|
|
319
|
+
|
|
320
|
+
To morph between clicks of one slide, set `morphSteps: true` in its frontmatter. Each click then runs through a view transition in which only named elements move. `examples/motion/slides/22-morph-steps.mdx` and `components/MorphSteps.tsx`:
|
|
321
|
+
|
|
322
|
+
```mdx
|
|
323
|
+
---
|
|
324
|
+
title: Morph / steps
|
|
325
|
+
clicks: 1
|
|
326
|
+
morphSteps: true
|
|
327
|
+
---
|
|
328
|
+
|
|
329
|
+
<MorphSteps />
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
```tsx
|
|
333
|
+
export function MorphSteps() {
|
|
334
|
+
const { clicks } = useSlide();
|
|
335
|
+
return (
|
|
336
|
+
<Morph name="step-card" className={`morph-card ${clicks ? "expanded" : "compact"}`}>
|
|
337
|
+
<strong>Keep the thread.</strong>
|
|
338
|
+
</Morph>
|
|
339
|
+
);
|
|
340
|
+
}
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
## Motion mode
|
|
344
|
+
|
|
345
|
+
Motion is either `live` or `instant`. The mode is the `data-deck-motion` attribute on `<html>`. It is `instant` when any of these holds, and `live` otherwise:
|
|
346
|
+
|
|
347
|
+
- the view is not the play view (the presenter window and the overview never animate);
|
|
348
|
+
- the system asks for reduced motion (`prefers-reduced-motion: reduce`);
|
|
349
|
+
- the URL's search string has `motion=instant`, as in `http://localhost:3030/?motion=instant#/4`.
|
|
350
|
+
|
|
351
|
+
In instant mode every state is shown at its end pose: steps do not transition, slide changes cut, `useTimeline` seeks, `CountUp` shows its final number.
|
|
352
|
+
|
|
353
|
+
In your own components, read the mode with `motionMode()`. It reads the DOM, so call it in an effect or a handler, never during render:
|
|
354
|
+
|
|
355
|
+
```tsx
|
|
356
|
+
import { gsap, motionMode } from "@steamfield/decks/motion";
|
|
357
|
+
import { useSlide } from "@steamfield/decks";
|
|
358
|
+
|
|
359
|
+
const { isActive, renderContext } = useSlide();
|
|
360
|
+
useLayoutEffect(() => {
|
|
361
|
+
if (!isActive || renderContext !== "slide" || motionMode() === "instant") {
|
|
362
|
+
gsap.set(el.current, { opacity: 1 });
|
|
363
|
+
return;
|
|
364
|
+
}
|
|
365
|
+
const tween = gsap.fromTo(el.current, { opacity: 0 }, { opacity: 1 });
|
|
366
|
+
return () => {
|
|
367
|
+
tween.kill();
|
|
368
|
+
};
|
|
369
|
+
}, [isActive, renderContext]);
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
In CSS, select on `html[data-deck-motion="instant"]`, or just use the duration tokens.
|
|
373
|
+
|
|
374
|
+
Use `?motion=instant` for screenshots and for checking the end state of each click.
|
|
375
|
+
|
|
376
|
+
## `window.__deck.settled()`
|
|
377
|
+
|
|
378
|
+
`window.__deck.settled()` returns a promise that resolves when the deck has stopped moving: no slide transition in flight, no gsap tween or `useTween` update pending, and no finite CSS animation or transition running, for two animation frames in a row. Animations that loop forever are ignored, so a spinning logo does not block it. It never rejects.
|
|
379
|
+
|
|
380
|
+
Use it in browser automation instead of sleeping:
|
|
381
|
+
|
|
382
|
+
```ts
|
|
383
|
+
await page.keyboard.press("ArrowRight");
|
|
384
|
+
await page.evaluate(() => window.__deck?.settled());
|
|
385
|
+
await page.screenshot({ path: "slide.png" });
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
After a change made in another window, wait for the URL to change first; the sync message may not have arrived yet.
|
|
389
|
+
|
|
390
|
+
A component that animates outside gsap and CSS (a canvas loop, a chart library) can report itself busy with `registerSettleProbe` from `@steamfield/decks`:
|
|
391
|
+
|
|
392
|
+
```tsx
|
|
393
|
+
import { registerSettleProbe } from "@steamfield/decks";
|
|
394
|
+
|
|
395
|
+
useEffect(() => registerSettleProbe(() => busy.current), []);
|
|
396
|
+
```
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Presenting
|
|
2
|
+
|
|
3
|
+
Open the deck's URL, press `f` for fullscreen and use the arrow keys. Press `p` for a presenter window with notes, and `o` for an overview of every slide.
|
|
4
|
+
|
|
5
|
+
## Keyboard
|
|
6
|
+
|
|
7
|
+
Navigation, in the play view and the presenter window:
|
|
8
|
+
|
|
9
|
+
| Key | Action |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `ArrowRight`, `Space`, `PageDown` | Next click, or the next slide after the last click. |
|
|
12
|
+
| `ArrowLeft`, `Shift+Space`, `PageUp` | Previous click, or the previous slide at its last click. |
|
|
13
|
+
| `ArrowDown` | Next slide, at click 0. |
|
|
14
|
+
| `ArrowUp` | Previous slide, at click 0. |
|
|
15
|
+
| `Home` | First slide. |
|
|
16
|
+
| `End` | Last slide. |
|
|
17
|
+
|
|
18
|
+
Views and display:
|
|
19
|
+
|
|
20
|
+
| Key | Action | Where |
|
|
21
|
+
| --- | --- | --- |
|
|
22
|
+
| `f` | Toggle fullscreen. | Every view, when the browser allows fullscreen. |
|
|
23
|
+
| `o` | Open the overview, or close it. | Every view. |
|
|
24
|
+
| `Escape` | Close the overview without moving. | The overview. |
|
|
25
|
+
| `p` | Open the presenter window. | The play view, when not embedded. |
|
|
26
|
+
| `Cmd/Ctrl` + `+` or `=` | Larger slide text. | Play view and presenter window. |
|
|
27
|
+
| `Cmd/Ctrl` + `-` | Smaller slide text. | Play view and presenter window. |
|
|
28
|
+
| `Cmd/Ctrl` + `0` | Slide text back to its authored size. | Play view and presenter window. |
|
|
29
|
+
|
|
30
|
+
In the overview the arrow keys move between tiles instead: `ArrowRight` and `ArrowDown` to the next tile, `ArrowLeft` and `ArrowUp` to the previous, `Home` and `End` to the first and last.
|
|
31
|
+
|
|
32
|
+
Keys are ignored while typing in an input, textarea, select or editable element, and a held key acts once. `Space` and `Enter` on a focused button do the button's job, so after clicking "Reset timer" the arrow keys still advance the talk.
|
|
33
|
+
|
|
34
|
+
## The URL
|
|
35
|
+
|
|
36
|
+
The position is in the URL hash, so a reload, a bookmark or a shared link lands on the same state.
|
|
37
|
+
|
|
38
|
+
| URL hash | Shows |
|
|
39
|
+
| --- | --- |
|
|
40
|
+
| `#/5` | Slide 5, click 0. |
|
|
41
|
+
| `#/5?clicks=2` | Slide 5, click 2. |
|
|
42
|
+
| `#/presenter/5?clicks=2` | The presenter view at that position. |
|
|
43
|
+
| `#/overview/5` | The overview, with the talk at slide 5. |
|
|
44
|
+
|
|
45
|
+
A slide change adds a browser history entry and a click does not, so the browser's Back button steps back one slide. A number past the end of the deck is clamped.
|
|
46
|
+
|
|
47
|
+
Two search parameters change behaviour: `?motion=instant` turns animation off (see [motion.md](motion.md)), and `?embedded` marks the deck as running inside another page, which turns off the presenter key and window sync.
|
|
48
|
+
|
|
49
|
+
## Presenter window
|
|
50
|
+
|
|
51
|
+
Press `p` in the play view. A separate window opens at the current position; drag it to your own screen and leave the first window on the projector. Pressing `p` again focuses the existing presenter window. If the browser blocks the popup, nothing happens: allow popups for the page and press `p` again.
|
|
52
|
+
|
|
53
|
+
The presenter window shows:
|
|
54
|
+
|
|
55
|
+
- the current slide, at the current click;
|
|
56
|
+
- the next state: what the next key press leads to, or "End of deck" on the last one;
|
|
57
|
+
- the speaker notes for the slide, with the segment for the current click marked and scrolled into view (write them with `<Notes>` and `[click]` markers, see [slides.md](slides.md));
|
|
58
|
+
- a status bar with the position ("5 / 12"), the click ("click 2 of 3") when the slide has clicks, the local time, and a timer.
|
|
59
|
+
|
|
60
|
+
The timer starts at the first navigation and counts up. "Reset timer" stops it at `00:00` until the next navigation. Opening the overview does not reset it; a reload does.
|
|
61
|
+
|
|
62
|
+
Both slide boxes take the shape of the audience window, so you see the framing the room sees. Nothing animates in the presenter window: each click shows its finished state.
|
|
63
|
+
|
|
64
|
+
## Two-window sync
|
|
65
|
+
|
|
66
|
+
Every window of the same deck in the same browser follows the others. Navigate in the presenter window and the audience window moves, and the other way around. A window opened or reloaded mid-talk joins at the talk's position.
|
|
67
|
+
|
|
68
|
+
- Sync runs over the browser's `BroadcastChannel`, so the windows must be in the same browser profile on the same machine, on the same origin. There is no remote control from another device.
|
|
69
|
+
- Windows are matched by deck name and URL path. Two different decks served from one origin do not drive each other. `/dir/` and `/dir/index.html` count as the same deck.
|
|
70
|
+
- Remote slide changes are added to each window's history, so Back in any window steps the whole room back one slide.
|
|
71
|
+
- An embedded deck (`?embedded`) does not sync.
|
|
72
|
+
|
|
73
|
+
## Overview
|
|
74
|
+
|
|
75
|
+
Press `o`. The overview is a grid with one tile per visible slide, each drawn at its last click and labelled with its number and title. The current slide's tile is focused.
|
|
76
|
+
|
|
77
|
+
- Move with the arrow keys or Tab, and press `Enter` or click a tile to go to that slide at click 0.
|
|
78
|
+
- Activating the current slide's tile, or pressing `Escape` or `o`, returns without moving, clicks included.
|
|
79
|
+
- Browsing the overview does not move the audience. Only choosing a tile does.
|
|
80
|
+
- The overview returns to the view it was opened from: the presenter window goes back to the presenter view.
|
|
81
|
+
|
|
82
|
+
## Fullscreen and the screen
|
|
83
|
+
|
|
84
|
+
`f` toggles browser fullscreen for the window it is pressed in. The slide always fills its window with no letterbox, so on a screen that is not 16:9 the canvas grows on one side; [canvas.md](canvas.md) covers what slides do with it.
|
|
85
|
+
|
|
86
|
+
While the play view or presenter window is visible the deck asks the browser to keep the screen awake, where the browser supports it. In the play view the mouse cursor hides after three seconds without movement.
|
|
87
|
+
|
|
88
|
+
## Text sizing
|
|
89
|
+
|
|
90
|
+
`Cmd` or `Ctrl` with `+`, `-` and `0` resize slide text. The browser's own zoom is replaced on these keys, because zooming a canvas that is scaled to fit would not make its text any larger.
|
|
91
|
+
|
|
92
|
+
- Each press multiplies or divides the size by 1.1, within 0.5 to 2.5 times the authored size. `0` restores the authored size.
|
|
93
|
+
- The size is remembered per deck in the browser's local storage. Every open window of the deck follows, and it survives a reload. Where storage is blocked, the change applies to the current window only.
|
|
94
|
+
- Only text grows; boxes do not. A densely composed slide can overflow after a step or two.
|
|
95
|
+
- It affects text whose CSS follows the rule in [canvas.md](canvas.md): `font-size: calc(<size> * var(--deck-text-scale, 1))`. Text sized any other way stays as it is.
|
|
96
|
+
|
|
97
|
+
## The "Created with Decks" credit
|
|
98
|
+
|
|
99
|
+
Every slide shows a small "Created with Decks" credit at the lower right, linking to the Decks site, in the slide's own text color. It appears in every view. To remove it, set `credit: false` in `deck.config.ts`; to replace it, add `layers/credit.tsx`. See [config.md](config.md).
|