@steamfield/decks 1.0.0-rc.1 → 1.1.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/dist/cli.js +1 -1
- package/dist/control-tray.css +84 -0
- package/dist/go-to-dialog.css +57 -0
- package/dist/{index-BURtH7IB.d.ts → index-D3Yj4yT6.d.ts} +11 -2
- package/dist/{index-BV_-6L5L.d.ts → index-DG8UcGQd.d.ts} +77 -1
- package/dist/{index-B2n69xrC.d.ts → index-zg-z6HTy.d.ts} +18 -2
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- package/dist/kit/term/live-term.module.css +36 -0
- package/dist/kit.d.ts +21 -6
- package/dist/kit.js +252 -8
- package/dist/live-term.module.css +36 -0
- package/dist/magic-move.css +30 -0
- package/dist/mark.css +34 -0
- package/dist/motion.d.ts +2 -2
- package/dist/motion.js +1 -1
- package/dist/node.d.ts +5 -1
- package/dist/node.js +1 -1
- package/dist/plugin/skills/building-a-deck/references/workflow.md +10 -0
- package/dist/plugin/skills/deck-design/references/layout.md +2 -0
- package/dist/plugin/skills/deck-motion/references/motion.md +38 -1
- package/dist/plugin/skills/working-with-decks/references/project.md +4 -0
- package/dist/presenter-view.css +14 -0
- package/dist/{prose-patterns-DPqjGBFu.js → prose-patterns-D-tdt0Ab.js} +3 -1
- package/dist/{prose-scan-BrWZ7gxZ.js → prose-scan-ni8g6pc-.js} +2 -2
- package/dist/{src-DizFoqYt.js → src--lhAQ29p.js} +348 -43
- package/dist/{src-C-OfT72W.js → src-BNyL3q7j.js} +212 -3
- package/dist/{src-CmQgaG1b.js → src-Cxck-eLP.js} +588 -68
- package/dist/term/shell_pty.py +38 -0
- package/dist/term/zsh/.zshrc +4 -0
- package/dist/term-protocol-B_qHRDEp.js +11 -0
- package/dist/xterm-host-C6OjffSm.js +282 -0
- package/docs/README.md +1 -0
- package/docs/cli.md +2 -1
- package/docs/code-blocks.md +31 -0
- package/docs/config.md +1 -0
- package/docs/getting-started.md +2 -1
- package/docs/kit.md +7 -6
- package/docs/migrating-from-slidev.md +4 -0
- package/docs/motion.md +25 -1
- package/docs/presenting.md +16 -1
- package/docs/slides.md +20 -1
- package/docs/terminal.md +97 -0
- package/package.json +4 -1
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Run a command on a pseudo-terminal of a set size, relaying stdin and stdout over pipes.
|
|
2
|
+
|
|
3
|
+
usage: shell_pty.py ROWS COLS COMMAND [ARG...]
|
|
4
|
+
The dev-server terminal plugin spawns this, because Node has no pty of its own and macOS
|
|
5
|
+
script(1) refuses a piped stdin. When stdin closes, the terminal is hung up, so the command
|
|
6
|
+
does not outlive the dev server. Exits with the command's exit status.
|
|
7
|
+
"""
|
|
8
|
+
import fcntl
|
|
9
|
+
import os
|
|
10
|
+
import pty
|
|
11
|
+
import select
|
|
12
|
+
import struct
|
|
13
|
+
import sys
|
|
14
|
+
import termios
|
|
15
|
+
|
|
16
|
+
rows, cols = int(sys.argv[1]), int(sys.argv[2])
|
|
17
|
+
pid, fd = pty.fork()
|
|
18
|
+
if pid == 0:
|
|
19
|
+
os.execvp(sys.argv[3], sys.argv[3:])
|
|
20
|
+
fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
|
|
21
|
+
while True:
|
|
22
|
+
readable, _, _ = select.select([fd, 0], [], [])
|
|
23
|
+
try:
|
|
24
|
+
if fd in readable:
|
|
25
|
+
data = os.read(fd, 65536)
|
|
26
|
+
if not data:
|
|
27
|
+
break
|
|
28
|
+
os.write(1, data)
|
|
29
|
+
if 0 in readable:
|
|
30
|
+
data = os.read(0, 65536)
|
|
31
|
+
if not data:
|
|
32
|
+
break
|
|
33
|
+
os.write(fd, data)
|
|
34
|
+
except OSError:
|
|
35
|
+
break
|
|
36
|
+
os.close(fd)
|
|
37
|
+
_, status = os.waitpid(pid, 0)
|
|
38
|
+
sys.exit(os.waitstatus_to_exitcode(status) if os.WIFEXITED(status) else 1)
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// ../core/src/term-protocol.ts
|
|
2
|
+
/** Browser to server. */
|
|
3
|
+
const TERM_ATTACH = "deck-term:attach";
|
|
4
|
+
const TERM_POSITION = "deck-term:position";
|
|
5
|
+
const TERM_INPUT = "deck-term:input";
|
|
6
|
+
/** Server to browser. */
|
|
7
|
+
const TERM_READY = "deck-term:ready";
|
|
8
|
+
const TERM_DATA = "deck-term:data";
|
|
9
|
+
const TERM_STATE = "deck-term:state";
|
|
10
|
+
const TERM_GONE = "deck-term:gone";
|
|
11
|
+
export { TERM_POSITION as a, TERM_INPUT as i, TERM_DATA as n, TERM_READY as o, TERM_GONE as r, TERM_STATE as s, TERM_ATTACH as t };
|
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
import { useLayoutEffect, useRef } from "react";
|
|
2
|
+
import { jsx } from "react/jsx-runtime";
|
|
3
|
+
import styles from "./live-term.module.css";
|
|
4
|
+
import { Terminal } from "@xterm/xterm";
|
|
5
|
+
import "@xterm/xterm/css/xterm.css";
|
|
6
|
+
// ../kit/src/term/output-pacer.ts
|
|
7
|
+
/** Pace bursts without delaying keystrokes, short replies or session replays. */
|
|
8
|
+
function createOutputPacer(write) {
|
|
9
|
+
let pending = "";
|
|
10
|
+
let deadline = 0;
|
|
11
|
+
let recentLines = 0;
|
|
12
|
+
let windowStarted = 0;
|
|
13
|
+
let timer;
|
|
14
|
+
const interval = 1e3 / 30;
|
|
15
|
+
const clear = () => {
|
|
16
|
+
clearTimeout(timer);
|
|
17
|
+
timer = void 0;
|
|
18
|
+
pending = "";
|
|
19
|
+
recentLines = 0;
|
|
20
|
+
windowStarted = Date.now();
|
|
21
|
+
};
|
|
22
|
+
const flush = () => {
|
|
23
|
+
const chunk = pending;
|
|
24
|
+
clear();
|
|
25
|
+
if (chunk) write(chunk, false);
|
|
26
|
+
};
|
|
27
|
+
const drain = () => {
|
|
28
|
+
timer = void 0;
|
|
29
|
+
const lines = pending.split("\n");
|
|
30
|
+
const ticks = Math.max(1, Math.floor((deadline - Date.now()) / interval));
|
|
31
|
+
const count = Math.max(1, Math.ceil(lines.length / ticks));
|
|
32
|
+
write(lines.splice(0, count).join("\n") + (lines.length ? "\n" : ""), false);
|
|
33
|
+
pending = lines.join("\n");
|
|
34
|
+
if (pending) timer = setTimeout(drain, interval);
|
|
35
|
+
};
|
|
36
|
+
return {
|
|
37
|
+
push(chunk, replay = false, immediate = false) {
|
|
38
|
+
if (replay) {
|
|
39
|
+
clear();
|
|
40
|
+
write(chunk, true);
|
|
41
|
+
return;
|
|
42
|
+
}
|
|
43
|
+
if (immediate) {
|
|
44
|
+
flush();
|
|
45
|
+
write(chunk, false);
|
|
46
|
+
return;
|
|
47
|
+
}
|
|
48
|
+
if (Date.now() - windowStarted >= interval) {
|
|
49
|
+
windowStarted = Date.now();
|
|
50
|
+
recentLines = 0;
|
|
51
|
+
}
|
|
52
|
+
const lines = chunk.split("\n").length - 1;
|
|
53
|
+
if (timer === void 0 && recentLines + lines <= 3) {
|
|
54
|
+
recentLines += lines;
|
|
55
|
+
write(chunk, false);
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
pending += chunk;
|
|
59
|
+
if (timer === void 0) {
|
|
60
|
+
deadline = Date.now() + 1500;
|
|
61
|
+
timer = setTimeout(drain, interval);
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
flush,
|
|
65
|
+
dispose: clear
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
// ../kit/src/term/terminal-face.ts
|
|
69
|
+
/** Fit xterm's measured grid at a whole device-pixel advance, without scaling it. */
|
|
70
|
+
function terminalFace(terminal, fontFamily, width, height, devicePixelRatio) {
|
|
71
|
+
const ruler = document.createElement("canvas").getContext("2d");
|
|
72
|
+
if (!ruler) throw new Error("no 2d canvas to measure the terminal font");
|
|
73
|
+
ruler.font = `1000px ${fontFamily}`;
|
|
74
|
+
const advance = ruler.measureText("W").width / 1e3;
|
|
75
|
+
const screen = terminal.element?.querySelector(".xterm-screen");
|
|
76
|
+
if (!screen) throw new Error("no xterm screen to measure");
|
|
77
|
+
const scrollbar = 6;
|
|
78
|
+
let cell = Math.floor((width - scrollbar) * devicePixelRatio / terminal.cols);
|
|
79
|
+
for (; cell >= 1; cell--) {
|
|
80
|
+
terminal.options.fontSize = cell / (advance * devicePixelRatio);
|
|
81
|
+
const gridWidth = screen.offsetWidth;
|
|
82
|
+
const gridHeight = screen.offsetHeight;
|
|
83
|
+
if (Number.isInteger(gridWidth * devicePixelRatio / terminal.cols) && gridWidth + scrollbar <= width && gridHeight <= height) return {
|
|
84
|
+
gridWidth,
|
|
85
|
+
gridHeight,
|
|
86
|
+
rowHeight: gridHeight / terminal.rows,
|
|
87
|
+
scrollbar,
|
|
88
|
+
left: (width - gridWidth - scrollbar) / 2,
|
|
89
|
+
top: (height - gridHeight) / 2
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
throw new Error(`terminal grid ${terminal.cols} by ${terminal.rows} cannot fit ${width} by ${height}`);
|
|
93
|
+
}
|
|
94
|
+
// ../kit/src/term/xterm-host.tsx
|
|
95
|
+
function XtermHost({ connection, rows, cols, scale, onReady }) {
|
|
96
|
+
const host = useRef(null);
|
|
97
|
+
useLayoutEffect(() => {
|
|
98
|
+
const target = host.current;
|
|
99
|
+
if (!target || scale <= 0) return;
|
|
100
|
+
let term;
|
|
101
|
+
let unsubscribe;
|
|
102
|
+
let cleanupOutput;
|
|
103
|
+
let cleanupWheel;
|
|
104
|
+
let cleanupFit;
|
|
105
|
+
let disposed = false;
|
|
106
|
+
const css = getComputedStyle(target.parentElement ?? target);
|
|
107
|
+
const fontFamily = css.fontFamily;
|
|
108
|
+
const fontSize = Number.parseFloat(css.fontSize);
|
|
109
|
+
const foreground = css.color;
|
|
110
|
+
const color = (name) => css.getPropertyValue(`--deck-term-${name}`).trim() || foreground;
|
|
111
|
+
const colors = {
|
|
112
|
+
foreground,
|
|
113
|
+
background: css.backgroundColor,
|
|
114
|
+
cursor: color("cursor"),
|
|
115
|
+
selectionBackground: color("selection"),
|
|
116
|
+
black: color("black"),
|
|
117
|
+
red: color("red"),
|
|
118
|
+
green: color("green"),
|
|
119
|
+
yellow: color("yellow"),
|
|
120
|
+
blue: color("blue"),
|
|
121
|
+
magenta: color("magenta"),
|
|
122
|
+
cyan: color("cyan"),
|
|
123
|
+
white: color("white"),
|
|
124
|
+
brightBlack: color("bright-black"),
|
|
125
|
+
brightRed: color("bright-red"),
|
|
126
|
+
brightGreen: color("bright-green"),
|
|
127
|
+
brightYellow: color("bright-yellow"),
|
|
128
|
+
brightBlue: color("bright-blue"),
|
|
129
|
+
brightMagenta: color("bright-magenta"),
|
|
130
|
+
brightCyan: color("bright-cyan"),
|
|
131
|
+
brightWhite: color("bright-white")
|
|
132
|
+
};
|
|
133
|
+
Promise.all([document.fonts.load(`${fontSize}px ${fontFamily}`), document.fonts.ready]).then(() => {
|
|
134
|
+
if (disposed) return;
|
|
135
|
+
try {
|
|
136
|
+
const frame = target.parentElement;
|
|
137
|
+
if (!frame) throw new Error("no terminal frame to measure");
|
|
138
|
+
term = new Terminal({
|
|
139
|
+
rows,
|
|
140
|
+
cols,
|
|
141
|
+
fontFamily,
|
|
142
|
+
fontSize: fontSize * scale,
|
|
143
|
+
letterSpacing: 0,
|
|
144
|
+
lineHeight: 1.12,
|
|
145
|
+
theme: colors,
|
|
146
|
+
allowTransparency: true,
|
|
147
|
+
drawBoldTextInBrightColors: false,
|
|
148
|
+
cursorBlink: false,
|
|
149
|
+
scrollback: 2e3,
|
|
150
|
+
overviewRuler: {
|
|
151
|
+
width: 6,
|
|
152
|
+
showTopBorder: false,
|
|
153
|
+
showBottomBorder: false
|
|
154
|
+
},
|
|
155
|
+
logLevel: "off"
|
|
156
|
+
});
|
|
157
|
+
term.attachCustomKeyEventHandler((event) => {
|
|
158
|
+
if (event.key !== "Escape") return true;
|
|
159
|
+
event.preventDefault();
|
|
160
|
+
event.stopPropagation();
|
|
161
|
+
term?.blur();
|
|
162
|
+
return false;
|
|
163
|
+
});
|
|
164
|
+
term.open(target);
|
|
165
|
+
const terminal = term;
|
|
166
|
+
const fit = () => {
|
|
167
|
+
const bounds = frame.getBoundingClientRect();
|
|
168
|
+
const face = terminalFace(terminal, fontFamily, bounds.width, bounds.height, window.devicePixelRatio);
|
|
169
|
+
target.style.width = `${face.gridWidth + face.scrollbar}px`;
|
|
170
|
+
target.style.height = `${face.gridHeight}px`;
|
|
171
|
+
target.style.marginLeft = `${face.left / scale}px`;
|
|
172
|
+
target.style.marginTop = `${face.top / scale}px`;
|
|
173
|
+
target.style.transform = `scale(${1 / scale})`;
|
|
174
|
+
return face;
|
|
175
|
+
};
|
|
176
|
+
let face = fit();
|
|
177
|
+
const refit = () => {
|
|
178
|
+
if (disposed) return;
|
|
179
|
+
try {
|
|
180
|
+
face = fit();
|
|
181
|
+
} catch (error) {
|
|
182
|
+
connection.unavailable(`terminal could not fit: ${error instanceof Error ? error.message : String(error)}`);
|
|
183
|
+
}
|
|
184
|
+
};
|
|
185
|
+
const observer = new ResizeObserver(refit);
|
|
186
|
+
observer.observe(frame);
|
|
187
|
+
let resolution = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
|
|
188
|
+
const changedDpr = () => {
|
|
189
|
+
if (disposed) return;
|
|
190
|
+
resolution.removeEventListener("change", changedDpr);
|
|
191
|
+
refit();
|
|
192
|
+
resolution = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
|
|
193
|
+
resolution.addEventListener("change", changedDpr);
|
|
194
|
+
};
|
|
195
|
+
resolution.addEventListener("change", changedDpr);
|
|
196
|
+
cleanupFit = () => {
|
|
197
|
+
observer.disconnect();
|
|
198
|
+
resolution.removeEventListener("change", changedDpr);
|
|
199
|
+
};
|
|
200
|
+
const rendered = terminal.onRender(() => {
|
|
201
|
+
if (disposed || !target.querySelector(".xterm-rows")?.textContent?.trim()) return;
|
|
202
|
+
onReady(true);
|
|
203
|
+
rendered.dispose();
|
|
204
|
+
});
|
|
205
|
+
let replays = 0;
|
|
206
|
+
const paced = createOutputPacer((chunk, replay) => {
|
|
207
|
+
if (replay) {
|
|
208
|
+
replays++;
|
|
209
|
+
terminal.options.disableStdin = true;
|
|
210
|
+
}
|
|
211
|
+
terminal.write(chunk, () => {
|
|
212
|
+
if (disposed) return;
|
|
213
|
+
if (replay) {
|
|
214
|
+
replays--;
|
|
215
|
+
terminal.options.disableStdin = replays > 0;
|
|
216
|
+
}
|
|
217
|
+
terminal.scrollToBottom();
|
|
218
|
+
});
|
|
219
|
+
});
|
|
220
|
+
term.onData((data) => {
|
|
221
|
+
paced.flush();
|
|
222
|
+
connection.input(data);
|
|
223
|
+
});
|
|
224
|
+
cleanupOutput = paced.dispose;
|
|
225
|
+
unsubscribe = connection.subscribeOutput(paced.push);
|
|
226
|
+
let remainder = 0;
|
|
227
|
+
const wheel = (event) => {
|
|
228
|
+
event.preventDefault();
|
|
229
|
+
event.stopPropagation();
|
|
230
|
+
const lineHeight = face.rowHeight;
|
|
231
|
+
const pixels = event.deltaY * (event.deltaMode === 1 ? lineHeight : event.deltaMode === 2 ? rows * lineHeight : 1);
|
|
232
|
+
remainder += pixels / lineHeight;
|
|
233
|
+
const lines = Math.trunc(remainder);
|
|
234
|
+
remainder -= lines;
|
|
235
|
+
if (lines) terminal.scrollLines(lines);
|
|
236
|
+
};
|
|
237
|
+
frame.addEventListener("wheel", wheel, {
|
|
238
|
+
passive: false,
|
|
239
|
+
capture: true
|
|
240
|
+
});
|
|
241
|
+
cleanupWheel = () => frame.removeEventListener("wheel", wheel, true);
|
|
242
|
+
} catch (error) {
|
|
243
|
+
connection.unavailable(`terminal could not open: ${error instanceof Error ? error.message : String(error)}`);
|
|
244
|
+
}
|
|
245
|
+
}).catch((error) => {
|
|
246
|
+
if (!disposed) connection.unavailable(`terminal font could not load: ${error instanceof Error ? error.message : String(error)}`);
|
|
247
|
+
});
|
|
248
|
+
return () => {
|
|
249
|
+
disposed = true;
|
|
250
|
+
onReady(false);
|
|
251
|
+
unsubscribe?.();
|
|
252
|
+
cleanupOutput?.();
|
|
253
|
+
cleanupWheel?.();
|
|
254
|
+
cleanupFit?.();
|
|
255
|
+
term?.dispose();
|
|
256
|
+
};
|
|
257
|
+
}, [
|
|
258
|
+
connection,
|
|
259
|
+
rows,
|
|
260
|
+
cols,
|
|
261
|
+
scale,
|
|
262
|
+
onReady
|
|
263
|
+
]);
|
|
264
|
+
return /* @__PURE__ */ jsx("div", {
|
|
265
|
+
className: styles.viewport,
|
|
266
|
+
children: /* @__PURE__ */ jsx("div", {
|
|
267
|
+
ref: host,
|
|
268
|
+
className: styles.host,
|
|
269
|
+
role: "application",
|
|
270
|
+
"aria-label": "Live terminal",
|
|
271
|
+
onKeyDown: (event) => event.stopPropagation(),
|
|
272
|
+
onKeyUp: (event) => event.stopPropagation(),
|
|
273
|
+
style: {
|
|
274
|
+
fontVariantLigatures: "none",
|
|
275
|
+
width: `${scale * 100}%`,
|
|
276
|
+
height: `${scale * 100}%`,
|
|
277
|
+
transform: `scale(${1 / scale})`
|
|
278
|
+
}
|
|
279
|
+
})
|
|
280
|
+
});
|
|
281
|
+
}
|
|
282
|
+
export { XtermHost };
|
package/docs/README.md
CHANGED
|
@@ -15,6 +15,7 @@ Each page stands alone. Read the one that answers your question.
|
|
|
15
15
|
| [cli.md](cli.md) | What do `decks new`, `check`, `lint`, `hook`, `export`, `shot` and `init` do? |
|
|
16
16
|
| [migrating-from-slidev.md](migrating-from-slidev.md) | How do I move a deck from `slidev-addon-decks`? |
|
|
17
17
|
| [presenting.md](presenting.md) | Which keys do what, and how do the presenter window, overview, sync and text sizing behave? |
|
|
18
|
+
| [terminal.md](terminal.md) | How do I run real commands in a terminal pane on a slide, and what does the deck show when it can't? |
|
|
18
19
|
| [kit.md](kit.md) | What does `@steamfield/decks/kit` provide: theme, story stages, `OpenChart`, the `story` transition? |
|
|
19
20
|
|
|
20
21
|
## Not built yet
|
package/docs/cli.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# The decks command
|
|
2
2
|
|
|
3
|
-
`decks dev` and `decks build` are in [getting-started.md](getting-started.md). This page covers the rest. Every command that takes a deck accepts an alias from `decks.json` or a directory, and a bare name that is neither resolves under `_config.decksDir` (default `decks/`).
|
|
3
|
+
`decks dev` and `decks build` are in [getting-started.md](getting-started.md); `decks dev --live-term` is in [terminal.md](terminal.md). This page covers the rest. Every command that takes a deck accepts an alias from `decks.json` or a directory, and a bare name that is neither resolves under `_config.decksDir` (default `decks/`).
|
|
4
4
|
|
|
5
5
|
## `decks new <alias> [dir] [--story] [--author "Name"] [--url example.com]`
|
|
6
6
|
|
|
@@ -18,6 +18,7 @@ Checks the whole project and exits 1 if anything is wrong, one problem per line:
|
|
|
18
18
|
| `<alias>: <message>` | The deck's config failed to load. |
|
|
19
19
|
| `no slides: <alias>` | The deck has no visible slides (`dev` and `build` would refuse it). |
|
|
20
20
|
| `<alias>: slide name: <file>` | A slide file is not `NN-slug.mdx`, or two share a number. |
|
|
21
|
+
| `<alias>: notes: <file> has [click] cues for N click(s), but the slide has M` | A visible slide's notes use `[click]` markers, and they cover a different number of clicks than the slide has, so cues would highlight on the wrong step. Notes with no markers are not checked. |
|
|
21
22
|
| `N error-level prose hit(s)` | `decks lint` finds error-level patterns. |
|
|
22
23
|
|
|
23
24
|
## `decks lint [alias...] [--stdin]`
|
package/docs/code-blocks.md
CHANGED
|
@@ -71,6 +71,37 @@ At click 0 line 2 is emphasized, at click 1 lines 4 and 5, at click 2 every line
|
|
|
71
71
|
|
|
72
72
|
A block with `k` steps adds `at + k - 1` to the slide's click total, so the slide above has two clicks with no `clicks:` in its frontmatter. A block without braces uses no clicks. See [motion.md](motion.md) for how the total is counted.
|
|
73
73
|
|
|
74
|
+
## Magic move
|
|
75
|
+
|
|
76
|
+
A magic-move fence morphs one code block into the next on a click: tokens that stay move to their new place, removed ones fade out and new ones fade in. The syntax is Slidev's, so a Slidev fence pastes in unchanged. Open with four backticks, the language `md` (or `markdown`) and `magic-move`, then put ordinary code fences inside, one per version.
|
|
77
|
+
|
|
78
|
+
`examples/motion/slides/32-magic-move.mdx`:
|
|
79
|
+
|
|
80
|
+
`````mdx
|
|
81
|
+
````md magic-move "greet.ts" {lines: true}
|
|
82
|
+
```ts {1}
|
|
83
|
+
const greeting = "Hello";
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
```ts {1|2}
|
|
87
|
+
const greet = (name: string) => `Hello, ${name}`;
|
|
88
|
+
greet("Ada");
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```ts {all}
|
|
92
|
+
export function greet(name: string) {
|
|
93
|
+
return `Hello, ${name}!`;
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
````
|
|
97
|
+
`````
|
|
98
|
+
|
|
99
|
+
After `magic-move` come an optional title, either quoted (`"greet.ts"`) or in brackets (`[greet.ts]`), and an optional options object: `at` (the click of the first version, default 0) and `lines` (line numbers, default off). Each inner fence can have its own `{...}` line emphasis, as in a plain block, and its own `lines`.
|
|
100
|
+
|
|
101
|
+
Each version holds for as many clicks as it has emphasis steps, at least one, and the next click morphs to the next version. The slide above shows version 1 at click 0, version 2 with line 1 then line 2 emphasized at clicks 1 and 2, and version 3 at click 3: `at` plus every version's step count, minus 1, so 3 clicks with no `clicks:` in the frontmatter.
|
|
102
|
+
|
|
103
|
+
The morph plays only on a forward step in the play view with live motion. Going back, jumping, reloading, the presenter window, the overview and print show the version for the click at once, and each printed click page shows its own version. Slidev's `{*}` emphasis is not supported; use `{all}`. A fence that does not parse is a compile error naming the slide and the line.
|
|
104
|
+
|
|
74
105
|
## Languages
|
|
75
106
|
|
|
76
107
|
The language is the first word on the fence. Any language Shiki bundles works. A block with no language is plain text. An unknown language is rendered as plain text and logs a warning naming the file.
|
package/docs/config.md
CHANGED
|
@@ -28,6 +28,7 @@ Only `title` is required. An unknown key is an error that lists the known ones.
|
|
|
28
28
|
| `credit` | `boolean` | `true` | The "Created with Decks" credit on every slide. `false` removes it. |
|
|
29
29
|
| `vite` | Vite `UserConfig` | none | Merged into the framework's Vite config. `vite.plugins` are added after the framework's. |
|
|
30
30
|
| `mdx` | `{ remarkPlugins?: PluggableList; rehypePlugins?: PluggableList }` | none | Plugins added to the slide compiler. Each key, when present, must be an array. |
|
|
31
|
+
| `term` | `{ dirs?: Record<string, string> }` | none | Working directories a `LiveTerm` pane can start in, by key, relative to the deck. Each must exist when `decks dev --live-term` starts. See [terminal.md](terminal.md). |
|
|
31
32
|
|
|
32
33
|
Examples of each:
|
|
33
34
|
|
package/docs/getting-started.md
CHANGED
|
@@ -58,7 +58,7 @@ npx -p @steamfield/decks decks build hello
|
|
|
58
58
|
|
|
59
59
|
Or add scripts to `package.json` (`"dev": "decks dev hello"`, `"build": "decks build hello"`), which run the installed bin, and use `bun run dev` or `npm run dev`. The rest of the guide writes the command as `decks` for short.
|
|
60
60
|
|
|
61
|
-
### `decks dev <deck> [--port <n>] [--open]`
|
|
61
|
+
### `decks dev <deck> [--port <n>] [--open] [--live-term]`
|
|
62
62
|
|
|
63
63
|
Serves the deck with live updates and prints its URL.
|
|
64
64
|
|
|
@@ -66,6 +66,7 @@ Serves the deck with live updates and prints its URL.
|
|
|
66
66
|
| --- | --- | --- |
|
|
67
67
|
| `--port <n>` | first free port from 3030 up | A whole number from 0 to 65535. An explicit port is strict: if it is taken the command fails instead of moving to another. `0` lets the OS pick. |
|
|
68
68
|
| `--open` | off | Open the deck in a browser. |
|
|
69
|
+
| `--live-term` | off | Run real shells in the deck's `LiveTerm` panes, on macOS and Linux. See [terminal.md](terminal.md). `decks build` and the other commands reject it. |
|
|
69
70
|
|
|
70
71
|
What an edit does while `dev` runs:
|
|
71
72
|
|
package/docs/kit.md
CHANGED
|
@@ -48,6 +48,7 @@ export { StoryCover } from "@steamfield/decks/kit";
|
|
|
48
48
|
| `DUR`, `SETTLE`, `DRAW`, `TRACE`, `SETTLE_CSS`, `DRAW_CSS`, `TRACE_CSS`, `easedStagger` | The story duration table (seconds), three gsap ease names, the same curves as CSS strings, and an eased stagger offset. |
|
|
49
49
|
| `xScale`, `yScale`, `clamp01`, `stagger` | Linear scales (d3-scale) for stage coordinates, a 0 to 1 clamp, and per-item progress within one staggered beat. |
|
|
50
50
|
| `FILTER_IDS`, `filterUrl` | SVG filters every `StoryStage` defines (marker textures and a glow), referenced as `filter={filterUrl(FILTER_IDS.glow)}`. |
|
|
51
|
+
| `LiveTerm`; type `LiveTermStatus` | A real shell on a slide, one command per click, with a fallback wherever a shell can't run. See [terminal.md](terminal.md). |
|
|
51
52
|
| `gsap` | The motion package's gsap instance, re-exported. |
|
|
52
53
|
|
|
53
54
|
The package also exports `@steamfield/decks/kit/styles.css`. Nothing else is public.
|
|
@@ -72,11 +73,11 @@ installTheme(resolveTheme(deckTheme));
|
|
|
72
73
|
| `theme()` | Returns the active theme. Throws if none is installed. |
|
|
73
74
|
| `ink(hue, step)` | One color of a ramp. `hue` is `"cyan"`, `"amber"`, `"rose"`, `"emerald"`, `"violet"` or `"slate"`; `step` is 1 to 4, darkest to lightest. |
|
|
74
75
|
|
|
75
|
-
`setup.ts` runs before any component module, so a component may call `ink()` at module level, as `examples/
|
|
76
|
+
`setup.ts` runs before any component module, so a component may call `ink()` at module level, as `examples/opendata-pitch/components/BootstrapStage.tsx` does:
|
|
76
77
|
|
|
77
78
|
```tsx
|
|
78
|
-
const
|
|
79
|
-
const
|
|
79
|
+
const RULE_INK = ink("slate", 1);
|
|
80
|
+
const DISK_WALL = ink("amber", 3);
|
|
80
81
|
```
|
|
81
82
|
|
|
82
83
|
### A deck's `theme.json`
|
|
@@ -330,15 +331,15 @@ The chart animates in when its slide is arrived at on click 0 in the play view,
|
|
|
330
331
|
|
|
331
332
|
The chart draws at screen size, not canvas size, so font sizes in a spec are screen pixels. Multiply them by the frame scale: `useFrameScale()` returns it, and `scaleChartTheme(theme, scale)` applies it to a chart theme's font sizes and axis spacing. `slideChartTheme` is a chart theme that reads its colors and fonts from the installed kit theme, and `slideChartAnimation` is the entrance timing for slides.
|
|
332
333
|
|
|
333
|
-
|
|
334
|
+
A stage that draws one chart from a module-level `SPEC`, colored with a module-level `DATA = ink("cyan", 2)`:
|
|
334
335
|
|
|
335
336
|
```tsx
|
|
336
337
|
const scale = useFrameScale();
|
|
337
338
|
const chartSpec = useMemo<ComponentProps<typeof OpenChart>["spec"]>(() => {
|
|
338
339
|
const base = scaleChartTheme(slideChartTheme, scale);
|
|
339
340
|
return {
|
|
340
|
-
...
|
|
341
|
-
data: [...
|
|
341
|
+
...SPEC,
|
|
342
|
+
data: [...SPEC.data],
|
|
342
343
|
theme: { ...base, colors: { ...base.colors, categorical: [DATA] } },
|
|
343
344
|
animation: slideChartAnimation,
|
|
344
345
|
};
|
|
@@ -35,6 +35,10 @@ Decks used to be a Slidev addon, `slidev-addon-decks`. It is now its own React f
|
|
|
35
35
|
| `<!-- notes -->` at the end of a page | `<Notes>...</Notes>`, `[click]` markers included |
|
|
36
36
|
| `<!-- lint-allow: id -->` on a line | `{/* lint-allow: id */}` on the same line |
|
|
37
37
|
| `routeEmbedNavigation` from `slidev-addon-decks/composables/embed-navigation` | `routeEmbedNavigation` from `@steamfield/decks` |
|
|
38
|
+
| `v-mark` (`v-mark.circle`, `v-mark.box`, ...) | `<Mark kind="circle" at={n}>` around the text; see [motion.md](motion.md) |
|
|
39
|
+
| a four-backtick `md magic-move` fence | the same fence; `{*}` emphasis becomes `{all}`. See [code-blocks.md](code-blocks.md) |
|
|
40
|
+
| `<Toc />`, `<Link to="5">` | `<Toc />`, `<Link to={5}>` (a number); see [slides.md](slides.md) |
|
|
41
|
+
| the bottom-left navigation controls and `g` | the control tray and `g`; see [presenting.md](presenting.md) |
|
|
38
42
|
|
|
39
43
|
## Commands
|
|
40
44
|
|
package/docs/motion.md
CHANGED
|
@@ -14,10 +14,11 @@ When a slide's frontmatter has no `clicks`, the total is read from the MDX sourc
|
|
|
14
14
|
|
|
15
15
|
| Written in the slide | Contributes |
|
|
16
16
|
| --- | --- |
|
|
17
|
-
| `Step`, `Stagger`, `Highlight`, `Draw` with `at` and optional `until` | `until` if present, else `at` |
|
|
17
|
+
| `Step`, `Stagger`, `Highlight`, `Draw`, `Mark` with `at` and optional `until` | `until` if present, else `at` |
|
|
18
18
|
| `TextReveal`, `CountUp` with `at` | `at` |
|
|
19
19
|
| `Steps` with `from` and `k` children (JSX elements, or one list with `k` items) | `from + k - 1` |
|
|
20
20
|
| A fenced code block with `k` highlight steps and `at=<n>` | `at + k - 1` (see [code-blocks.md](code-blocks.md)) |
|
|
21
|
+
| A magic-move fence | `at` plus each version's highlight steps (at least 1 each), minus 1 (see [code-blocks.md](code-blocks.md)) |
|
|
21
22
|
|
|
22
23
|
So this slide has two clicks with no `clicks:` line:
|
|
23
24
|
|
|
@@ -157,6 +158,29 @@ Draws the strokes of its SVG shape children on click `at`. It renders a `<g>`, s
|
|
|
157
158
|
|
|
158
159
|
Props: `at`, `until`.
|
|
159
160
|
|
|
161
|
+
### `Mark`
|
|
162
|
+
|
|
163
|
+
Draws a hand-drawn mark around inline text on click `at`, and removes it at `until`. The text is always visible and readable; only the mark comes and goes. Going back un-draws it.
|
|
164
|
+
|
|
165
|
+
```mdx
|
|
166
|
+
The fix was <Mark kind="circle" at={1}>one line</Mark>, and <Mark at={2}>nobody</Mark> had read it.
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Props: `at`, `until`, `kind` and `color`.
|
|
170
|
+
|
|
171
|
+
| `kind` | Draws |
|
|
172
|
+
| --- | --- |
|
|
173
|
+
| `underline` (default) | A line under the text. |
|
|
174
|
+
| `circle` | An ellipse around it. |
|
|
175
|
+
| `box` | A rectangle around it. |
|
|
176
|
+
| `strike` | A line through its middle. |
|
|
177
|
+
| `cross` | Two diagonals across it. |
|
|
178
|
+
| `bracket` | A bracket either side. |
|
|
179
|
+
|
|
180
|
+
`color` takes any CSS colour, including a theme token (`color="var(--accent)"`); the default is the text colour. Set the stroke width with the `--deck-mark-width` CSS variable (default `3px`). The strokes come from [Rough.js](https://roughjs.com) with a fixed seed, so the same mark looks the same on every load and in every view. A mark over text that wraps onto two lines surrounds the whole box, and an `underline` sits under the last line only, so keep marked phrases short.
|
|
181
|
+
|
|
182
|
+
`Mark` is the counterpart of Slidev's `v-mark`.
|
|
183
|
+
|
|
160
184
|
## Hooks
|
|
161
185
|
|
|
162
186
|
### `useStepState(at, until?)`
|
package/docs/presenting.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Presenting
|
|
2
2
|
|
|
3
|
-
Open the deck's URL, press `f` for fullscreen and use the arrow keys. Press `p` for a presenter window with notes,
|
|
3
|
+
Open the deck's URL, press `f` for fullscreen and use the arrow keys. Press `p` for a presenter window with notes, `o` for an overview of every slide, and `g` to jump to a slide by number or title. Everything the keys do is also on the control tray in the bottom-left corner.
|
|
4
4
|
|
|
5
5
|
## Keyboard
|
|
6
6
|
|
|
@@ -23,6 +23,7 @@ Views and display:
|
|
|
23
23
|
| `o` | Open the overview, or close it. | Every view. |
|
|
24
24
|
| `Escape` | Close the overview without moving. | The overview. |
|
|
25
25
|
| `p` | Open the presenter window. | The play view, when not embedded. |
|
|
26
|
+
| `g` | Open the go-to dialog. | The play view and presenter window, when not embedded or in the site player. |
|
|
26
27
|
| `Cmd/Ctrl` + `+` or `=` | Larger slide text. | Play view and presenter window. |
|
|
27
28
|
| `Cmd/Ctrl` + `-` | Smaller slide text. | Play view and presenter window. |
|
|
28
29
|
| `Cmd/Ctrl` + `0` | Slide text back to its authored size. | Play view and presenter window. |
|
|
@@ -31,6 +32,20 @@ In the overview the arrow keys move between tiles instead: `ArrowRight` and `Arr
|
|
|
31
32
|
|
|
32
33
|
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
|
|
|
35
|
+
## Control tray
|
|
36
|
+
|
|
37
|
+
Move the pointer to the bottom-left corner of the play view and a row of controls appears: previous, next, the position ("3 / 12", which opens the go-to dialog), overview, presenter, fullscreen and smaller or larger text. It fades out again when the pointer leaves, and `Tab` reaches it from the keyboard. Previous and next are disabled at the first and last click of the deck, and the fullscreen button is absent where the browser does not allow fullscreen.
|
|
38
|
+
|
|
39
|
+
Moving the pointer away also releases a clicked tray button's focus, so `Space` advances the talk again rather than pressing the button. The tray is not shown in the presenter window, the overview, print, or a deck running `?embedded`.
|
|
40
|
+
|
|
41
|
+
During a slide transition the browser routes clicks to the transition's snapshot, so a tray click in that moment is dropped. Keys still work; wait for the transition to finish or use the keyboard.
|
|
42
|
+
|
|
43
|
+
## Go to a slide
|
|
44
|
+
|
|
45
|
+
Press `g`, or click the position in the tray. Type a number to pick that slide, or any other text to filter slides by title; `ArrowUp` and `ArrowDown` move the selection and `Enter` goes there, at click 0. `Escape` or a click outside closes the dialog without moving. A search that is only digits always means a slide number, so a title such as "2026" is found by another word in it.
|
|
46
|
+
|
|
47
|
+
In a synced talk, going to a slide from the presenter window moves the audience window too, as any other navigation does.
|
|
48
|
+
|
|
34
49
|
## The URL
|
|
35
50
|
|
|
36
51
|
The position is in the URL hash, so a reload, a bookmark or a shared link lands on the same state.
|
package/docs/slides.md
CHANGED
|
@@ -92,8 +92,9 @@ Every slide can use these names with no import.
|
|
|
92
92
|
| Source | Names |
|
|
93
93
|
| --- | --- |
|
|
94
94
|
| The deck's `components/*.tsx` | Every named export under its own name; a default export under the file's basename. |
|
|
95
|
-
| Motion (`@steamfield/decks/motion`) | `Step`, `Steps`, `Stagger`, `TextReveal`, `Highlight`, `CountUp`, `Draw`, `Morph` |
|
|
95
|
+
| Motion (`@steamfield/decks/motion`) | `Step`, `Steps`, `Stagger`, `TextReveal`, `Highlight`, `CountUp`, `Draw`, `Morph`, `Mark` |
|
|
96
96
|
| Layouts (`@steamfield/decks`) | `Center`, `Cover`, `Section`, `TwoCol`, `ImageSide` |
|
|
97
|
+
| Navigation (`@steamfield/decks`) | `Toc`, `Link` |
|
|
97
98
|
| Built in | `Notes`; fenced code blocks render through `CodeBlock` |
|
|
98
99
|
|
|
99
100
|
A deck component with the same name as a framework one replaces it for that deck. A replaced motion component no longer adds clicks.
|
|
@@ -121,6 +122,24 @@ slides/03-x.mdx:3:1: <Nonexistent> is not defined. Export it from a file in comp
|
|
|
121
122
|
|
|
122
123
|
Lowercase elements and member names such as `<motion.div>` are not checked.
|
|
123
124
|
|
|
125
|
+
## Links between slides
|
|
126
|
+
|
|
127
|
+
`<Link to={5}>the results</Link>` is a link to slide 5 at click 0. In the play view and the presenter window a click goes there, and in a synced talk the other windows follow. A `Cmd`- or `Ctrl`-click opens the slide in a new tab, which joins the talk's sync and then follows the talk's position. A `to` that is not a slide number in the deck is an error naming it.
|
|
128
|
+
|
|
129
|
+
`<Toc />` is an agenda: a numbered list of every slide's title as a `Link`, with the current slide marked (`aria-current="page"`). Slides without a `title` in their frontmatter are listed by number, and hidden slides are left out.
|
|
130
|
+
|
|
131
|
+
In the overview, a preview, and print, both render as plain text, so a thumbnail never navigates.
|
|
132
|
+
|
|
133
|
+
```mdx
|
|
134
|
+
---
|
|
135
|
+
title: What this talk covers.
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
<h1>What this talk covers.</h1>
|
|
139
|
+
|
|
140
|
+
<Toc />
|
|
141
|
+
```
|
|
142
|
+
|
|
124
143
|
## Built-in layouts
|
|
125
144
|
|
|
126
145
|
Layouts arrange their children and nothing else. They set no fonts, colors or sizes. Each fills the slide and pads its content with `--deck-pad-x` (120px) and `--deck-pad-y` (96px); the gap between children is `--deck-gap` (80px). Override the variables in your CSS.
|