@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/config.md
ADDED
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# Configuration
|
|
2
|
+
|
|
3
|
+
A deck is configured by `deck.config.ts` at its root. It must default-export an object; `defineDeck` gives it types.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { defineDeck } from "@steamfield/decks/node";
|
|
7
|
+
|
|
8
|
+
export default defineDeck({
|
|
9
|
+
title: "Building for agents",
|
|
10
|
+
author: "Riley Hilliard",
|
|
11
|
+
transition: "story",
|
|
12
|
+
});
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Only `title` is required. An unknown key is an error that lists the known ones. Editing the file while `decks dev` runs restarts the server and the page comes back at the same slide and click.
|
|
16
|
+
|
|
17
|
+
## Options
|
|
18
|
+
|
|
19
|
+
| Option | Type | Default | Meaning |
|
|
20
|
+
| --- | --- | --- | --- |
|
|
21
|
+
| `title` | `string` | required | The page title. |
|
|
22
|
+
| `author` | `string` | none | Written to `<meta name="author">`. |
|
|
23
|
+
| `info` | `string` | none | One line about the deck. It becomes the page's `description` and the text of a shared link's preview. |
|
|
24
|
+
| `url` | `string` (a URL) | none | Where the built deck is published. Adds `og:url`, and with `public/og.png` or `og.jpg` in the deck an absolute `og:image` for link previews. |
|
|
25
|
+
| `canvas` | `{ width: number; height: number }` | `{ width: 1920, height: 1080 }` | The design canvas in pixels. Both must be positive. |
|
|
26
|
+
| `transition` | `string` | none (slides fade) | Default slide transition: `cut`, `fade`, `push`, `zoom`, or a name your CSS defines. Must not be empty. |
|
|
27
|
+
| `htmlAttrs` | `Record<string, string>` | none | Attributes set on `<html>`. Each key must be a valid HTML attribute name. |
|
|
28
|
+
| `credit` | `boolean` | `true` | The "Created with Decks" credit on every slide. `false` removes it. |
|
|
29
|
+
| `vite` | Vite `UserConfig` | none | Merged into the framework's Vite config. `vite.plugins` are added after the framework's. |
|
|
30
|
+
| `mdx` | `{ remarkPlugins?: PluggableList; rehypePlugins?: PluggableList }` | none | Plugins added to the slide compiler. Each key, when present, must be an array. |
|
|
31
|
+
|
|
32
|
+
Examples of each:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { defineDeck } from "@steamfield/decks/node";
|
|
36
|
+
import rehypeKatex from "rehype-katex";
|
|
37
|
+
import remarkMath from "remark-math";
|
|
38
|
+
|
|
39
|
+
export default defineDeck({
|
|
40
|
+
title: "Tides",
|
|
41
|
+
author: "Riley Hilliard",
|
|
42
|
+
info: "Why the sea rises twice a day.",
|
|
43
|
+
canvas: { width: 1920, height: 1200 },
|
|
44
|
+
transition: "push",
|
|
45
|
+
htmlAttrs: { lang: "en", "data-theme": "night" },
|
|
46
|
+
credit: false,
|
|
47
|
+
vite: {
|
|
48
|
+
optimizeDeps: { include: ["three"] },
|
|
49
|
+
},
|
|
50
|
+
mdx: {
|
|
51
|
+
remarkPlugins: [remarkMath],
|
|
52
|
+
rehypePlugins: [rehypeKatex],
|
|
53
|
+
},
|
|
54
|
+
});
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Notes on individual options:
|
|
58
|
+
|
|
59
|
+
- `canvas` changes the size every slide is designed for. See [canvas.md](canvas.md).
|
|
60
|
+
- `transition` is the fallback for every slide boundary; a slide's frontmatter `transition` overrides it. See [motion.md](motion.md).
|
|
61
|
+
- `vite`: the framework sets the Vite root to the deck directory and the public directory to `public/`. For `decks build`, the base comes from `--base` or `decks.json`, which override a `base` set here. A package imported directly in a slide's MDX (not through a component) can cost one page reload the first time the dev server sees it; import packages from components, or list them under `vite.optimizeDeps.include`.
|
|
62
|
+
|
|
63
|
+
## MDX plugins
|
|
64
|
+
|
|
65
|
+
Add remark and rehype plugins under `mdx` to extend slide markdown: math, diagrams, your own syntax.
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
mdx: {
|
|
69
|
+
remarkPlugins: [remarkMath],
|
|
70
|
+
rehypePlugins: [rehypeKatex],
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- Your remark plugins run after the framework's (frontmatter, notes removal).
|
|
75
|
+
- Your rehype plugins run before the framework's code highlighting, so a plugin can claim a code element first and the highlighter handles what is still a code block.
|
|
76
|
+
- The static click count and the notes extraction parse slides with your remark plugins attached, so syntax they add still parses. Their transforms do not run there: a plugin that generates step components adds no clicks, and such a slide sets `clicks:` in its frontmatter.
|
|
77
|
+
- A plugin that throws while compiling a slide is reported as that slide's compile error.
|
|
78
|
+
|
|
79
|
+
Install the plugins as dependencies of the deck. A plugin's stylesheet (KaTeX's, for example) is yours to import from `styles/index.css`.
|
|
80
|
+
|
|
81
|
+
## Layers
|
|
82
|
+
|
|
83
|
+
A layer is a component drawn on every slide: a logo, a progress bar, a footer, a background. A deck provides up to three, each the default export of its file.
|
|
84
|
+
|
|
85
|
+
| File | Drawn |
|
|
86
|
+
| --- | --- |
|
|
87
|
+
| `layers/above.tsx` | Over the slide's content. |
|
|
88
|
+
| `layers/below.tsx` | Under the slide's content. |
|
|
89
|
+
| `layers/credit.tsx` | In place of the built-in credit. |
|
|
90
|
+
|
|
91
|
+
Any other `.tsx` file under `layers/` is an error.
|
|
92
|
+
|
|
93
|
+
`examples/motion/layers/above.tsx`:
|
|
94
|
+
|
|
95
|
+
```tsx
|
|
96
|
+
import { useDeck, useSlide } from "@steamfield/decks";
|
|
97
|
+
|
|
98
|
+
export default function Above() {
|
|
99
|
+
const { no } = useSlide();
|
|
100
|
+
const { total } = useDeck();
|
|
101
|
+
return (
|
|
102
|
+
<footer className="gallery-progress">
|
|
103
|
+
<span>Motion / field notes</span>
|
|
104
|
+
<output aria-label="Slide number">
|
|
105
|
+
{no} / {total}
|
|
106
|
+
</output>
|
|
107
|
+
</footer>
|
|
108
|
+
);
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
How layers behave:
|
|
113
|
+
|
|
114
|
+
- A layer is rendered inside each slide, so `useSlide()` and `useDeck()` work in it, and it is correct in every render context: an overview tile's layer shows that tile's slide number. It also means a layer follows the rules for slide components in [slides.md](slides.md): several instances exist at once.
|
|
115
|
+
- Each layer's wrapper fills the slide and takes no pointer events. Turn them back on for a child that needs them (`pointer-events: auto`).
|
|
116
|
+
- The above layer holds still while slides transition under it. The below layer moves with its slide, like any background.
|
|
117
|
+
- A slide opts out with frontmatter: `layers: false` shows neither, `layers: "above"` or `layers: "below"` keeps only that one.
|
|
118
|
+
- For CSS, the wrappers carry `data-deck-layer="above"`, `"below"` or `"credit"`.
|
|
119
|
+
|
|
120
|
+
### The credit
|
|
121
|
+
|
|
122
|
+
By default every slide shows "Created with Decks", with the Decks mark and a link, at the lower right, in the slide's text color. It sits in a band along the bottom edge whose height is the CSS variable `--deck-credit-space`; the built-in layouts and the kit keep content above the band.
|
|
123
|
+
|
|
124
|
+
| To | Do |
|
|
125
|
+
| --- | --- |
|
|
126
|
+
| Remove it | Set `credit: false` in `deck.config.ts`. `--deck-credit-space` becomes `0px`. |
|
|
127
|
+
| Replace it | Add `layers/credit.tsx` with a default-exported component. It is rendered in the credit's wrapper, which fills the slide, so position it yourself. |
|
|
128
|
+
|
|
129
|
+
`credit: false` wins over a `layers/credit.tsx`. Frontmatter `layers` does not affect the credit. An above layer is drawn over it.
|
|
130
|
+
|
|
131
|
+
## `setup.ts`
|
|
132
|
+
|
|
133
|
+
A deck may have a `setup.ts` beside `deck.config.ts`. It is imported for its side effects first, before any component module is evaluated and before the deck mounts, so a component can rely on what it set up, even at module level. Editing it reloads the page.
|
|
134
|
+
|
|
135
|
+
A deck that uses the kit installs its theme there. `examples/building-for-agents/setup.ts`:
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
import { installTheme, resolveTheme } from "@steamfield/decks/kit";
|
|
139
|
+
import deckTheme from "./theme.json";
|
|
140
|
+
|
|
141
|
+
installTheme(resolveTheme(deckTheme));
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
It runs in the browser, not in Node. See [kit.md](kit.md) for the theme.
|
|
145
|
+
|
|
146
|
+
## How errors are reported
|
|
147
|
+
|
|
148
|
+
A mistake in a deck is reported once, as a short message that names the file, the value and what to do, without a stack trace:
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
<file>[:line:col]: <what is wrong>. <what to do>
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
| Mistake | Message |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| Config lacks `title` | `deck.config.ts: title is required (a string).` |
|
|
157
|
+
| Unknown config key | `deck.config.ts: unknown key "titel". Known keys: title, author, ...` |
|
|
158
|
+
| Wrong type | `deck.config.ts: canvas.width must be a number, got "1920".` |
|
|
159
|
+
| No default export | `deck.config.ts has no default export. Write: export default defineDeck({ title: "..." })` |
|
|
160
|
+
| No config file | `no deck.config.ts in <dir>. A deck directory holds deck.config.ts and slides/.` |
|
|
161
|
+
| Unknown deck | `"aa" is not a registered deck or a directory. Registered in decks.json: basic, motion.` |
|
|
162
|
+
| Bad frontmatter | `slides/03-x.mdx: frontmatter clicks must be a whole number 0 or greater, got "two".` |
|
|
163
|
+
| No slides | `no slides/*.mdx files in <dir>.` |
|
|
164
|
+
| Uncountable step | `slides/03-x.mdx:7:1: <Step at={n}>: at must be a literal whole number (at={2}). To compute it, set clicks: in the frontmatter.` |
|
|
165
|
+
| Undefined component | `slides/03-x.mdx:3:1: <Nonexistent> is not defined. Export it from a file in components/ or import it in the slide.` |
|
|
166
|
+
| Port in use | `decks dev: port 3040 is already in use. Stop what is using it or pass a different --port.` |
|
|
167
|
+
|
|
168
|
+
Where a message appears:
|
|
169
|
+
|
|
170
|
+
- Before a server exists, and for `decks build`: `decks <command>: <message>` on stderr, exit code 1.
|
|
171
|
+
- While `decks dev` runs: one line in the terminal and the same message in the browser's error overlay, with the file and position.
|
|
172
|
+
- A failure about the deck as a whole (frontmatter, step counts, a component file, `layers/`) stays reported until it is fixed, and the terminal then prints `<file>: fixed`.
|
|
173
|
+
- A slide that fails to compile affects only that slide. Its neighbours keep working.
|
|
174
|
+
- An invalid `deck.config.ts` during a session prints `deck.config.ts is invalid, still serving the last valid config:` and keeps the overlay up until the file is valid again.
|
|
175
|
+
|
|
176
|
+
In the browser:
|
|
177
|
+
|
|
178
|
+
- A slide that throws while rendering shows `Slide <id> (<file>) failed to render: <message>` in place of that slide only, with the component stack in dev. The rest of the deck keeps working, and in dev the next successful hot update reloads the page.
|
|
179
|
+
- A slide whose module failed to load shows `Slide <id> failed to load. See the terminal or the error overlay.`
|
|
180
|
+
- A failure while starting the deck (a component file that throws at import) writes `The deck failed to start: <message>` into the page.
|
|
181
|
+
- `useSlide()` and `useDeck()` called outside a slide or a deck throw a message that names the hook and the remedy.
|
|
182
|
+
|
|
183
|
+
Anything that is not an author mistake keeps its stack trace and ends with `This is a bug in react-decks.`
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
A deck is a directory with a `deck.config.ts` and a `slides/` folder. Run it with `decks dev <deck>` and build it with `decks build <deck>`.
|
|
4
|
+
|
|
5
|
+
## What a deck directory contains
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
my-deck/
|
|
9
|
+
deck.config.ts required: export default defineDeck({ title: "..." })
|
|
10
|
+
package.json the deck's dependencies
|
|
11
|
+
slides/01-cover.mdx required: one .mdx file per slide
|
|
12
|
+
slides/02-point.mdx
|
|
13
|
+
components/*.tsx optional: components every slide can use without importing
|
|
14
|
+
layers/above.tsx optional: drawn over every slide
|
|
15
|
+
layers/below.tsx optional: drawn under every slide
|
|
16
|
+
layers/credit.tsx optional: replaces the built-in credit
|
|
17
|
+
setup.ts optional: runs once before the deck mounts
|
|
18
|
+
styles/index.css optional: loaded once, after the framework's styles
|
|
19
|
+
public/ optional: static files served at the site root
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
There is no `index.html` and no slide list to maintain. The framework generates both.
|
|
23
|
+
|
|
24
|
+
| Path | Rules |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `deck.config.ts` | Must have a default export. See [config.md](config.md). |
|
|
27
|
+
| `slides/*.mdx` | Only `.mdx` files directly under `slides/` are slides. Subdirectories and `.md` files are ignored. |
|
|
28
|
+
| `components/*.tsx` | Only `.tsx` files directly under `components/` are scanned. Each named export is available in every slide under its name, and a default export under the file's basename. See [slides.md](slides.md). |
|
|
29
|
+
| `layers/` | Only `above.tsx`, `below.tsx` and `credit.tsx` are allowed. Any other `.tsx` file there is an error. See [config.md](config.md). |
|
|
30
|
+
| `setup.ts` | Imported for its side effects before any component module. A deck that uses the kit installs its theme here. |
|
|
31
|
+
| `styles/index.css` | The one stylesheet the framework loads for you. Import others from it. |
|
|
32
|
+
| `public/` | Vite's public directory. `public/field.svg` is served as `field.svg`. `public/favicon.svg`, `.png` or `.ico` is used as the page icon (the Decks mark otherwise), and `public/og.png` or `og.jpg` as the link preview image when `url` is set. |
|
|
33
|
+
|
|
34
|
+
Other files and folders (`data/`, `scene/`, a `theme.json`) are yours. Import them from components or slides.
|
|
35
|
+
|
|
36
|
+
Use Node 22.12 or later. In your project directory, install the package and its React peers:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
bun add @steamfield/decks react react-dom
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
With npm, use `npm install @steamfield/decks react react-dom`. The runtime, motion, kit and Node APIs ship in this one package; `/motion`, `/kit` and `/node` are import paths, not separate dependencies.
|
|
43
|
+
|
|
44
|
+
## How slide order works
|
|
45
|
+
|
|
46
|
+
Slides are sorted by filename, compared as plain strings, so number them with a fixed width: `01-cover.mdx`, `02-steps.mdx`, `10-end.mdx`. To reorder, rename.
|
|
47
|
+
|
|
48
|
+
A slide's id is its filename without `.mdx` (`02-steps`). Its number is its 1-based position among visible slides. A slide with `hide: true` in its frontmatter is dropped before numbering, so the slides after it move up by one.
|
|
49
|
+
|
|
50
|
+
## Commands
|
|
51
|
+
|
|
52
|
+
`@steamfield/decks` installs the `decks` command. Run it from the project directory that holds `decks.json`, through the package so the runner never fetches the unrelated package named `decks` on npm:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
bunx -p @steamfield/decks decks dev hello
|
|
56
|
+
npx -p @steamfield/decks decks build hello
|
|
57
|
+
```
|
|
58
|
+
|
|
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
|
+
|
|
61
|
+
### `decks dev <deck> [--port <n>] [--open]`
|
|
62
|
+
|
|
63
|
+
Serves the deck with live updates and prints its URL.
|
|
64
|
+
|
|
65
|
+
| Flag | Default | Meaning |
|
|
66
|
+
| --- | --- | --- |
|
|
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
|
+
| `--open` | off | Open the deck in a browser. |
|
|
69
|
+
|
|
70
|
+
What an edit does while `dev` runs:
|
|
71
|
+
|
|
72
|
+
| Change | Result |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| A slide's body | That slide hot-updates. If the edit changes the slide's counted click total, the page reloads. |
|
|
75
|
+
| A slide's frontmatter; a slide added, removed or renamed | The page reloads. Slide and click are in the URL, so the position survives. |
|
|
76
|
+
| A component file edited | Hot update. If the edit changes which names the file exports, the page reloads. |
|
|
77
|
+
| A file added to or removed from `components/` or `layers/` | The page reloads. |
|
|
78
|
+
| `setup.ts` | The page reloads. |
|
|
79
|
+
| `deck.config.ts` | The server restarts. An invalid config keeps serving the last valid one and shows the error. |
|
|
80
|
+
|
|
81
|
+
### `decks build <deck> [--out <dir>] [--base <path>]`
|
|
82
|
+
|
|
83
|
+
Writes a static site. Navigation uses the URL hash, so the output needs no server rewrites.
|
|
84
|
+
|
|
85
|
+
| Flag | Default | Meaning |
|
|
86
|
+
| --- | --- | --- |
|
|
87
|
+
| `--out <dir>` | `dist/{name}`, or `_config.outDir` from `decks.json` | Output directory. `{name}` is replaced with the deck's name. |
|
|
88
|
+
| `--base <path>` | `./`, or `_config.base` from `decks.json` | Base URL of the built site. The default `./` works from any path. |
|
|
89
|
+
|
|
90
|
+
`build` empties the output directory first, so it refuses to run when `--out`:
|
|
91
|
+
|
|
92
|
+
- is the deck directory or the working directory, or contains either;
|
|
93
|
+
- exists, is not empty, and was not written by `decks build`;
|
|
94
|
+
- is a file, a dangling symlink, or not writable.
|
|
95
|
+
|
|
96
|
+
For a build, set the base with `--base` or `_config.base`. A `base` inside the deck's `vite` option is overridden by them.
|
|
97
|
+
|
|
98
|
+
`decks`, `decks dev --help` and `decks build --help` print usage. An unknown command or option is an error.
|
|
99
|
+
|
|
100
|
+
## How decks are registered
|
|
101
|
+
|
|
102
|
+
`<deck>` is either an alias from `decks.json` in the working directory, or a path to a deck directory.
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{
|
|
106
|
+
"_config": {
|
|
107
|
+
"outDir": "dist/{name}",
|
|
108
|
+
"base": "./"
|
|
109
|
+
},
|
|
110
|
+
"basic": { "dir": "examples/basic" },
|
|
111
|
+
"motion": { "dir": "examples/motion" }
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
- Each key that does not start with `_` is an alias. Its `dir` is resolved against the working directory.
|
|
116
|
+
- `_config.outDir` and `_config.base` are the defaults for `decks build`. Both are optional.
|
|
117
|
+
- With no `decks.json`, or for a deck that is not in it, pass the directory: `decks dev ./my-deck`.
|
|
118
|
+
|
|
119
|
+
The deck's name is the alias, or the directory's basename when you pass a path. The name fills `{name}` in the output path and is part of the channel that syncs a deck's windows, so two decks served from one origin do not drive each other.
|
|
120
|
+
|
|
121
|
+
## A minimal working deck
|
|
122
|
+
|
|
123
|
+
Create these six files under `decks/hello/`, then register the directory in the project's `decks.json`:
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{"hello":{"dir":"decks/hello"}}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`deck.config.ts`:
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
import { defineDeck } from "@steamfield/decks/node";
|
|
133
|
+
|
|
134
|
+
export default defineDeck({ title: "Hello" });
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`setup.ts` installs the kit's default theme:
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
import { installTheme, resolveTheme } from "@steamfield/decks/kit";
|
|
141
|
+
|
|
142
|
+
installTheme(resolveTheme());
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`components/ImportedStep.tsx`:
|
|
146
|
+
|
|
147
|
+
```tsx
|
|
148
|
+
import { Step } from "@steamfield/decks/motion";
|
|
149
|
+
|
|
150
|
+
export function ImportedStep() {
|
|
151
|
+
return <Step at={2}><p>Imported step appears.</p></Step>;
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`slides/01-cover.mdx`:
|
|
156
|
+
|
|
157
|
+
```mdx
|
|
158
|
+
---
|
|
159
|
+
title: Hello
|
|
160
|
+
clicks: 2
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
import { StoryCard } from "@steamfield/decks/kit";
|
|
164
|
+
|
|
165
|
+
# Hello, decks.
|
|
166
|
+
|
|
167
|
+
<Step at={1}><p>Provided step appears.</p></Step>
|
|
168
|
+
|
|
169
|
+
<ImportedStep />
|
|
170
|
+
|
|
171
|
+
<StoryCard lead="The kit loads too." />
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`slides/02-end.mdx`:
|
|
175
|
+
|
|
176
|
+
```mdx
|
|
177
|
+
---
|
|
178
|
+
clicks: 1
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
import { StoryCard, StoryStage, useStage } from "@steamfield/decks/kit";
|
|
182
|
+
|
|
183
|
+
export function Story() {
|
|
184
|
+
const { copy, clicks, beats } = useStage({
|
|
185
|
+
copy: [{ lead: "A story starts here." }, { lead: "The story advances." }],
|
|
186
|
+
beats: (_tl, beat) => { beat(0); beat(1); },
|
|
187
|
+
});
|
|
188
|
+
return <StoryStage beats={beats} click={clicks}
|
|
189
|
+
overlay={<h1 className="od-story-head">Ready to present.</h1>}
|
|
190
|
+
card={<StoryCard lead={copy.lead} />} />;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
<Story />
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
`styles/index.css`:
|
|
197
|
+
|
|
198
|
+
```css
|
|
199
|
+
@import "@steamfield/decks/kit/styles.css";
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The kit stylesheet supplies Inter and its component styles. `<Step>` needs no import in MDX. The custom `ImportedStep` component imports the same motion API and becomes available in MDX by its named export. Set `clicks: 2` because the compiler cannot count the step inside that component's body. Press ArrowRight twice to reveal both steps, then once more to reach slide 2.
|
|
203
|
+
|
|
204
|
+
Working decks to copy from: `examples/basic` (the smallest), `examples/motion` (one slide per motion component, transition and layout), `examples/tides-slide` and `examples/building-for-agents` (story decks on the kit).
|