@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
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Encodings and formats
|
|
2
|
+
|
|
3
|
+
Adapted from the OpenChart encoding and format references identified in [VENDORED.md](VENDORED.md). Read installed `ChartSpec`, `LayerSpec`, `MarkDef`, `Encoding` and `EncodingChannel` declarations for complete shapes.
|
|
4
|
+
|
|
5
|
+
## Spec shape
|
|
6
|
+
|
|
7
|
+
Charts use `mark`, commonly a string or `{ type: ... }`, plus `data` and `encoding`. `type: "line"` is not a chart discriminant. Non-chart visualization families use their own `type` and renderer. Do not pass host options such as dark mode or renderer selection inside a chart spec.
|
|
8
|
+
|
|
9
|
+
Map real numeric fields as `quantitative`, dates as `temporal`, unordered categories as `nominal`, and ordered categories as `ordinal`. `field` must match the data exactly. Use the channel's audience-facing `title` instead of showing an internal column name. Add `color` for series identity; grouping without color uses `detail` where supported.
|
|
10
|
+
|
|
11
|
+
`scale.domain` sets explicit bounds. `scale.zero` controls inclusion of zero. For a precise temporal window, `nice: false` prevents a rounded domain from adding unrelated time. `sort: null` preserves categorical order; ascending/descending category sort is lexical, not a value ranking. Order rows yourself for ranked bars and check the render.
|
|
12
|
+
|
|
13
|
+
`bin`, `timeUnit` and `aggregate` can express documented transforms on channels. Keep statistical definitions and aggregation rules in the source record. A transform is not a substitute for preserving where the input rows came from.
|
|
14
|
+
|
|
15
|
+
## Stacking
|
|
16
|
+
|
|
17
|
+
| Mark | When colored |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| Bar | Stacked by default; `stack: null` on the quantitative channel gives grouped comparisons |
|
|
20
|
+
| Area | Stacked by default; `stack: null` on y gives overlap |
|
|
21
|
+
| Line | Does not stack |
|
|
22
|
+
|
|
23
|
+
Use `stack: "normalize"` for shares, producing a 0-to-1 domain. Use `"zero"` for cumulative totals. Never leave stacking to defaults when it changes the meaning of the comparison.
|
|
24
|
+
|
|
25
|
+
## Color channels
|
|
26
|
+
|
|
27
|
+
For a constant fill, prefer `mark.fill`, resolved through the Decks theme. Installed versions that export `ValueDef` also accept a bare `encoding.color: { value: ... }` and expand it to a mark property. A field-based channel maps data; a conditional channel uses `condition.test` with a field predicate and `condition.value`, plus a fallback `value`. Read the installed channel and condition types before authoring them.
|
|
28
|
+
|
|
29
|
+
## Formatting
|
|
30
|
+
|
|
31
|
+
OpenChart supports d3-format strings plus a literal suffix extension. These are format demonstrations, not source data:
|
|
32
|
+
|
|
33
|
+
| Format | Meaning |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| `.1f` | One decimal place |
|
|
36
|
+
| `.1f%` | One decimal plus literal percent sign; use for values already in percent units |
|
|
37
|
+
| `.1%` | Multiply a fraction by 100 and show percent |
|
|
38
|
+
| `$,.0f` | Currency with comma groups and no decimals |
|
|
39
|
+
| `,.0f` | Count with comma groups |
|
|
40
|
+
| `~s` | SI suffix for large values |
|
|
41
|
+
|
|
42
|
+
Use matching `axis.format` and `labels.format`. State the units even if no tooltip is available. Do not round the underlying data merely to make labels shorter. For normalized stacks use fractional-percent formatting, not the percent-unit suffix form.
|
|
43
|
+
|
|
44
|
+
`axis.tickCount` is a suggestion, not an exact count. Use enough intermediate ticks to make the scale readable. Log axes need fewer subdivisions and a stated rationale. A short unit-bearing tick can make a redundant unit in the axis title unnecessary.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Story marks
|
|
2
|
+
|
|
3
|
+
Use the public marks from `@steamfield/decks/kit` for a scene that must remain pinned and evolve over beats. For a conventional statistical chart, prefer `OpenChart` rather than rebuilding axes, legends and accessibility yourself. Read the installed kit declarations for exact props and handle signatures.
|
|
4
|
+
|
|
5
|
+
| Mark | Fits |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `InkLine` | A sourced series drawn into explicit x/y domains and ranges |
|
|
8
|
+
| `InkBars` | Comparable rows that grow, recolor, exit or reorder across beats |
|
|
9
|
+
| `InkRule` | A baseline or reference rule |
|
|
10
|
+
| `InkNumber` | One sourced magnitude, optionally grown through a parent timeline |
|
|
11
|
+
| `InkChip` | A short label tied to a mark, not another prose card |
|
|
12
|
+
| `InkTimeline`, `InkTimelineCursor` | Dated events and a moving position on a common time scale |
|
|
13
|
+
| `UnitGrid`, `InkPing` | Tangible individual units and a selected unit needing attention |
|
|
14
|
+
| `InkCardRect`, `Underline` | Meaningful grouping or emphasis in the same scene |
|
|
15
|
+
|
|
16
|
+
`InkStep` is a public ramp-step type, not a component. `UnitGridItem` is a data type, not a component. Do not invent JSX tags from type names.
|
|
17
|
+
|
|
18
|
+
## Data and geometry
|
|
19
|
+
|
|
20
|
+
Import observed values and factual labels from `data/*.ts`; keep geometry separate. Explicit domains/ranges determine the quantitative meaning. Bars need a zero baseline; line positions can use a justified tighter domain. Unit grids must define what one unit represents and disclose any aggregation or rounding. A square must not silently switch population between beats.
|
|
21
|
+
|
|
22
|
+
`InkLine` takes `series`, `xDomain`, `yDomain`, `xRange`, `yRange` and optional hue/style controls. `InkBars` takes `rows`, `domain`, `xRange`, `yBand`; each `InkBarRow` has `id`, `label`, `value`, with optional display and hue fields. Use stable ids across reorderings. `InkRule` uses `x1`, `x2`, `y`.
|
|
23
|
+
|
|
24
|
+
`UnitGrid` can take explicit items or a count; its `reveal`, `recolor`, `scatter` and `collapse` are progress props driven by parent state, not autonomous story clocks. Use stable item identity for seeds, not geometry that changes on resize. Where a count is sampled or symbolic, disclose it.
|
|
25
|
+
|
|
26
|
+
Colors come from `ink(hue, step)` and `theme()`. Use neutral ink for context and one saturated subject when possible. Do not add independent animation or another scale system inside a mark to avoid learning the parent timeline.
|
|
27
|
+
|
|
28
|
+
## Timeline ownership
|
|
29
|
+
|
|
30
|
+
Use `useStage` with `useTween` for seekable state. Imperative marks append to the parent's timeline through public handles: `LineHandle.addDraw`, `BarsHandle.addGrow`/`addReorder`/`addExit`/`addRecolor`, `RuleHandle.addDraw`, `GrowHandle.addGrow`, `TimelineHandle.addInk`/`addLift`. The stage decides which click owns the change. Import handle types from the kit.
|
|
31
|
+
|
|
32
|
+
Omitted positions append; `"<"` explicitly overlaps with the last inserted tween. Keep ref-driven marks outside any subtree keyed by `playCount`. A timeline must not retain a destroyed instance. Use the deck-motion reference for entrance versus beat state and context behavior.
|
|
33
|
+
|
|
34
|
+
## Frame and text
|
|
35
|
+
|
|
36
|
+
`StoryStage` SVG is 1920x1080; `StoryLayer` supplies overlay SVG in the same coordinates. Use `STAGE`, frame units `--sw`/`--sh`/`--lw`, or data-to-range scales so labels stay aligned. `InkChip` is HTML positioned against the frame; put it in the overlay rather than inside SVG. Inspect its placement after reflow.
|
|
37
|
+
|
|
38
|
+
Keep ink out of the actual headline and card rectangles. `StoryCard` is the one prose surface; at most one chip or end label should compete for active reading. Render every beat in both directions, instant mode, presenter, preview, overview and print. Custom marks must keep the same settled meaning without timers or WebGL outside the active live slide, and must provide understandable labels/source context for their data.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Mark behavior
|
|
2
|
+
|
|
3
|
+
Adapted from the OpenChart bar, line, area, scatter and series-style references identified in [VENDORED.md](VENDORED.md). Read the installed mark and encoding declarations before using optional fields.
|
|
4
|
+
|
|
5
|
+
## Bars
|
|
6
|
+
|
|
7
|
+
`mark: "bar"` covers horizontal and vertical bars. Quantitative x plus categorical y gives horizontal bars; categorical/temporal x plus quantitative y gives columns. Keep the magnitude axis at zero. For a narrow range where zero obscures the change, choose a position-based dot plot rather than truncating bars.
|
|
8
|
+
|
|
9
|
+
Color groups stack by default. Use `stack: null` on the quantitative channel for independent side-by-side comparisons. `"normalize"` gives shares of the total; it is wrong when the audience needs absolute values. Preserve or deliberately sort category order, and inspect the displayed order. Values should be readable without hover when precision matters.
|
|
10
|
+
|
|
11
|
+
## Lines
|
|
12
|
+
|
|
13
|
+
`mark: "line"` connects ordered observations. Use temporal x for real dates; ordinal x for a deliberate ordered sequence. Use color for distinct series. `point: true` helps show sparse observations; dense observations may need aggregation instead.
|
|
14
|
+
|
|
15
|
+
For multiple line/area series, endpoint chip labels are on by default and the traditional legend can be auto-suppressed. `endpointLabels: false` restores the default legend behavior. To request a top legend instead, use `legend: { position: "top" }` with endpoint labels off. To force both, set `legend.show: true`.
|
|
16
|
+
|
|
17
|
+
`labels.density` does not add per-point text to lines/areas. Annotate selected values. `crosshair: true` is useful for interactive detail but cannot carry a presentation's main value alone. Do not connect across missing periods as if measurements exist there.
|
|
18
|
+
|
|
19
|
+
## Areas
|
|
20
|
+
|
|
21
|
+
`mark: "area"` emphasizes magnitude through filled area. Use a zero baseline for magnitude. Colored areas stack by default; `encoding.y.stack: null` overlaps them, while `"normalize"` shows shares. Use `y2` for a genuine range or interval, with both boundaries documented. Do not present uncertainty bands as measured totals.
|
|
22
|
+
|
|
23
|
+
## Scatter and bubble
|
|
24
|
+
|
|
25
|
+
`mark: "point"` maps quantitative x/y. Use `filled: true` for solid points when that improves projection contrast. `size` is a quantitative encoding for bubble area. Fit domains to the question, leave space for the largest marks and label the extent. A correlation is not evidence of causation.
|
|
26
|
+
|
|
27
|
+
Use color only for a meaningful category, magnitude or highlight. Dense plots need fewer labels and selected annotations. Prefer a couple of labeled comparisons over shrinking every campus or customer name until it becomes unreadable.
|
|
28
|
+
|
|
29
|
+
## Series identity
|
|
30
|
+
|
|
31
|
+
`seriesStyles` overrides a series by its color-field value. Public fields include `lineStyle`, `showPoints`, `strokeWidth` and `opacity`. Use dashed estimates/benchmarks, dim context and a clear subject. Resolve colors from the Decks theme and keep identities stable across slides and beats.
|
|
32
|
+
|
|
33
|
+
Legend toggling can change the visible scale; do not rely on an interactive filtered state to establish a headline without documenting the filter. The exported frame must still identify what is plotted.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Charts on slides
|
|
2
|
+
|
|
3
|
+
## Setup and size
|
|
4
|
+
|
|
5
|
+
Import `OpenChart`, `slideChartTheme`, `scaleChartTheme`, `slideChartAnimation`, `useFrameScale`, `ink` and `theme` from `@steamfield/decks/kit`. Install the theme in `setup.ts` and import the kit stylesheet before deck CSS. `OpenChart` takes `spec`, optional `onMarkHover` and `onMarkLeave`; it accepts chart or layer specs.
|
|
6
|
+
|
|
7
|
+
Give the host a definite size or a flex-fill region with `min-height: 0`. A chart should fill most of a chart slide's free area, not sit in a small decorative card. Avoid duplicate titles in the stage headline and chart chrome.
|
|
8
|
+
|
|
9
|
+
The wrapper counter-scales its host, so OpenChart draws at screen size. Its theme sizes therefore need `scaleChartTheme(slideChartTheme, useFrameScale())`. Recompute the spec when scale changes, normally with React `useMemo`; do not multiply ordinary HTML or SVG sizes by this scale.
|
|
10
|
+
|
|
11
|
+
The slide theme's design-size defaults are title 30, subtitle 22, body 21, small 18 and axis ticks 20. These are a starting point; increase text or reduce complexity when the actual chart host makes them unreadable. Explicit annotation/data-label font sizes and offsets are screen pixels too; scale authored design-size overrides rather than scaling the chart host again. Theme scaling does not traverse arbitrary spec fields.
|
|
12
|
+
|
|
13
|
+
Use the shared `slideChartAnimation`, not raw timing numbers per spec. The wrapper enables chart animation only for eligible live slide arrivals at click 0; other contexts, instant motion and later-click arrivals settle. Do not wrap it in a second decorative entrance.
|
|
14
|
+
|
|
15
|
+
## Theme and color
|
|
16
|
+
|
|
17
|
+
Start from `scaleChartTheme(slideChartTheme, scale)`. Spread nested overrides so you preserve fonts, spacing and chrome. Colors must be resolved JavaScript strings from `ink()` or `theme()`, never CSS variables or hex literals in specs. Set categorical colors through the theme, with stable assignments across related charts.
|
|
18
|
+
|
|
19
|
+
For one highlighted series, use its hue and neutral context series. For conditional color, a `condition` uses the documented field predicate and resolved token colors. Prefer `mark.fill` for a constant color; check the installed types before using value-only channel shorthand.
|
|
20
|
+
|
|
21
|
+
## Axes and honest domains
|
|
22
|
+
|
|
23
|
+
- Specify quantitative domains deliberately, including both scatter axes. Include zero for bars and area magnitude. For lines and scatter a tighter domain is acceptable if the visible scale makes its extent clear. Preserve comparable domains across beats and small multiples unless a change is explicit.
|
|
24
|
+
- Include source-relevant extremes and uncertainty. Give bubbles enough space for their radii. Do not set the ceiling to the point center and clip the mark.
|
|
25
|
+
- Use `sort: null` on a categorical channel to preserve supplied order; sort the rows explicitly when ranking. Check the rendered top-to-bottom order instead of assuming it.
|
|
26
|
+
- Give ticks their units. Use `.1f%` for values already expressed as percent and `.1%` for fractions. Keep label and axis formats consistent. Use enough intermediate ticks to read values without visual clutter.
|
|
27
|
+
- Use restrained gridlines, readable theme text and short axis titles. Never remove a necessary scale merely for a cleaner screenshot.
|
|
28
|
+
|
|
29
|
+
## Marks, annotations and chrome
|
|
30
|
+
|
|
31
|
+
Use a line with points when individual observations matter; a design stroke around 2.5 units is a useful starting point. Dense observations may need aggregation, not hundreds of dots. Bars should carry readable values where the precision matters. Lines do not gain per-point text labels through `labels.density`; use annotations or endpoint labels.
|
|
32
|
+
|
|
33
|
+
Keep at most a couple of text callouts. Reference lines are better for repeated thresholds. Anchor a text annotation in data coordinates and offset its text into empty space. Show uncertainty and projected status, using dashed estimates with the same semantic hue as observed values.
|
|
34
|
+
|
|
35
|
+
Chart chrome carries a finding, a short scope/method subtitle when needed, and source attribution. An eyebrow is optional and must add information. A story headline or external source line can do that job instead; avoid two competing header stacks.
|
|
36
|
+
|
|
37
|
+
Put legends at the top when used. Prefer clear direct or endpoint labels where they fit. Never turn off both legend and endpoint labels for multiple series unless another visible key identifies each one. Hover-only information is unavailable to most of the room and to PDF readers.
|
|
38
|
+
|
|
39
|
+
## Inspect and verify
|
|
40
|
+
|
|
41
|
+
Inspect the built chart in the slide, not only in an isolated chart preview. Check the smallest presenter/preview frame, projection size, 4:3 and 21:9 windows, instant mode and PDF. Look for cropped legends, tiny ticks, source clipping, colliding annotations, insufficient contrast and missing values silently connected.
|
|
42
|
+
|
|
43
|
+
Walk all click states if the data, domain or highlighted series changes. Recompute claims from data rather than inferring them from pixel geometry. Finish with the fact-check in `decks:deck-data`, tracing every plotted row and annotation to `data-sources.md`.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: working-with-decks
|
|
3
|
+
description: Use when starting work in a project using @steamfield/decks, finding the installed framework documentation, running the CLI, or choosing a Decks authoring skill.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Working with Decks
|
|
7
|
+
|
|
8
|
+
Start here before creating or editing a deck. Use the project's installed version.
|
|
9
|
+
|
|
10
|
+
1. Read `node_modules/@steamfield/decks/package.json` for the version and public exports.
|
|
11
|
+
2. Read `node_modules/@steamfield/decks/docs/README.md`, then the relevant files in that directory. These are the installed version's guide.
|
|
12
|
+
3. If local docs are missing or insufficient, use the documentation in the [Decks GitHub repository](https://github.com/steamfield/decks) at the release tag matching that exact version. Do not substitute the default branch or a guessed tag. If no matching tag exists, use the installed declarations and CLI help and report the documentation gap.
|
|
13
|
+
4. Check signatures against the installed `.d.ts` files selected by the package's exports. Do not use private, deprecated or experimental APIs. When docs and the implementation differ, confirm the installed behavior and report the discrepancy.
|
|
14
|
+
|
|
15
|
+
This package uses MDX slides and React components; a Slidev/Vue deck with `slides.md`, `pages/` or `slidev-addon-decks` needs migration before these workflows apply.
|
|
16
|
+
|
|
17
|
+
Read [project layout and CLI](references/project.md) for file discovery, imports and commands. Use `decks` through the project's package manager or local bin; the commands below assume it is on PATH. Run from the project directory containing `decks.json`. A deck argument can also be a directory.
|
|
18
|
+
|
|
19
|
+
## Load the skill for the work
|
|
20
|
+
|
|
21
|
+
These are plugin skills, invoked as `decks:<name>`. Follow their linked references before authoring the relevant part.
|
|
22
|
+
|
|
23
|
+
| Request | Load next, in order |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| Make a deck or change its structure | `decks:building-a-deck`, which routes the full workflow |
|
|
26
|
+
| Write, shorten or revise visible text | `decks:writing-slides` |
|
|
27
|
+
| Choose a layout, typography, theme or visual hierarchy | `decks:deck-design` |
|
|
28
|
+
| Add reveals, transitions, demos or story beats | `decks:deck-motion` |
|
|
29
|
+
| Add or edit a chart, table, map or Ink visualization | `decks:visualization`, then `decks:deck-data` before writing any figure |
|
|
30
|
+
| Add numbers, refresh evidence or fact-check | `decks:deck-data` |
|
|
31
|
+
|
|
32
|
+
For a six-slide story about Q3 numbers: load `building-a-deck`, then `writing-slides`, `deck-design`, `deck-motion`, and `deck-data`; load `visualization` before selecting marks or writing a chart spec. Source the actual Q3 data before drafting numeric claims. Finish the building workflow, including `decks check`, `decks lint`, visual QA and the fact-check in `deck-data`.
|
|
33
|
+
|
|
34
|
+
For a churn-by-month chart: load `visualization` and `deck-data` before entering values; define the churn denominator, time window and missing-month treatment, then select and encode the chart. Finish with the relevant checks and a fact-check of the new claims.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Project layout and commands
|
|
2
|
+
|
|
3
|
+
Read the installed guide's getting-started, configuration and slide-authoring pages for details. A deck has:
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
my-deck/
|
|
7
|
+
deck.config.ts
|
|
8
|
+
slides/01-cover.mdx
|
|
9
|
+
slides/02-first-point.mdx
|
|
10
|
+
components/FirstStage.tsx
|
|
11
|
+
setup.ts
|
|
12
|
+
styles/index.css
|
|
13
|
+
public/
|
|
14
|
+
data/
|
|
15
|
+
data-sources.md
|
|
16
|
+
theme.json
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Only the config and slides are required by the framework. `data/`, `data-sources.md` and `theme.json` are authoring conventions. The story scaffold provides the first two.
|
|
20
|
+
|
|
21
|
+
- Slides are direct `slides/*.mdx` files, sorted by filename as strings. Use `NN-slug.mdx`. `decks check` expects unique two-digit prefixes and lowercase hyphenated slugs. Gaps are fine. A slide id is its basename without the extension; its number is its 1-based visible position.
|
|
22
|
+
- `hide: true` removes a slide before numbering. Keep its evidence so it can be restored safely.
|
|
23
|
+
- `components/*.tsx` direct children expose named exports to all MDX slides; default exports use the filename. Duplicate names and `export *` are errors. Helpers can be `.ts` or live outside this discovery folder.
|
|
24
|
+
- `Step`, `Steps`, `Stagger`, `TextReveal`, `Highlight`, `CountUp`, `Draw`, `Morph`, `Center`, `Cover`, `Section`, `TwoCol`, `ImageSide` and `Notes` are available in MDX without imports. Kit components require an explicit import or named re-export from `components/`.
|
|
25
|
+
- `styles/index.css` loads after framework styles. Import the kit stylesheet first when using the kit: `@import "@steamfield/decks/kit/styles.css";`.
|
|
26
|
+
- `setup.ts` runs in the browser before component modules. Install the kit theme there with `installTheme(resolveTheme())`, imported from `@steamfield/decks/kit`. For an override, import `./theme.json` and pass it to `resolveTheme`.
|
|
27
|
+
- `public/` contains assets served at the site root. Only `above.tsx`, `below.tsx` and `credit.tsx` are allowed as React layers under `layers/`; each default-exports a component. They render per slide instance.
|
|
28
|
+
|
|
29
|
+
## Public import roots
|
|
30
|
+
|
|
31
|
+
| Import | Use |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| `@steamfield/decks` | React runtime hooks and layouts, including `useSlide`, `useDeck`, `useSlideScale` |
|
|
34
|
+
| `@steamfield/decks/motion` | Motion components, `useTween`, `useTimeline`, tokens and the registered `gsap` instance |
|
|
35
|
+
| `@steamfield/decks/kit` | Theme, story stages, Ink marks and slide-aware `OpenChart` |
|
|
36
|
+
| `@steamfield/decks/node` | `defineDeck` for `deck.config.ts`; tooling belongs outside browser components |
|
|
37
|
+
|
|
38
|
+
Do not import the node entry into a slide. No automatic utility CSS framework is installed. Use ordinary CSS, CSS Modules, or the kit's documented classes.
|
|
39
|
+
|
|
40
|
+
## CLI
|
|
41
|
+
|
|
42
|
+
Use `decks <command> --help` to confirm the installed version's flags.
|
|
43
|
+
|
|
44
|
+
| Command | Behavior |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| `decks new <alias> [dir] [--story] [--author "Name"] [--url example.com]` | Scaffold a conventional or story deck under `_config.decksDir` (default `decks/`) and register it in `decks.json`. `dir` is a bare directory name. Existing aliases/directories are refused. |
|
|
47
|
+
| `decks dev <deck> [--port N] [--open]` | Serve with live updates; default first free port at or above 3030. Explicit ports are strict; `0` asks the OS. |
|
|
48
|
+
| `decks check` | Check registered configs, slide names/counts, alias collisions, unregistered decks under `decksDir`, and error-level prose. Register a path-only deck if you need this command to cover it. |
|
|
49
|
+
| `decks lint [deck ...]` | Report prose errors and warnings; defaults to every registered deck. Error hits fail. |
|
|
50
|
+
| `decks lint --stdin` | Lint MDX from stdin, without deck arguments. |
|
|
51
|
+
| `decks build <deck> [--out dir] [--base path]` | Build a static site; default output `dist/{name}`, base `./`, overridable by registry defaults. Output is emptied, with protections against unrelated directories. |
|
|
52
|
+
| `decks shot <deck> <slide> [clicks] [--out file.png] [--width N] [--height N]` | Build and capture one settled frame with instant motion. Defaults: click 0, 1920x1080, `slide-<slide>-c<clicks>.png`. Owns its browser and preview server. |
|
|
53
|
+
| `decks export <deck> [--out file.pdf] [--final]` | Build and export all click states to PDF; `--final` exports only each slide's final click. Default PDF is `<outDir>/<name>.pdf`, using the registry output default. |
|
|
54
|
+
|
|
55
|
+
Screenshot and PDF commands use Chromium. If the CLI reports it missing, follow its instruction: `npx playwright install chromium`. A capture failure is a failed verification, not a successful export. Build also generates an `og.png` preview from the first slide when `public/og.png` is absent; missing Chromium skips that preview with a warning rather than failing the build.
|
|
56
|
+
|
|
57
|
+
Edits hot-update or reload as needed: adding a component or changing exports reloads; editing config restarts the server. Do not prescribe manual restarts after every new component.
|
|
58
|
+
|
|
59
|
+
`decks check` and lint do not prove that a deck compiles or fits on screen. Build and inspect rendered frames too. There is no figure extractor or automatic fact-check command; use `decks:deck-data`.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: writing-slides
|
|
3
|
+
description: Use when drafting, revising or reviewing Decks headlines, bullets, story cards, chart text, labels or speaker notes for presentation-distance reading.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Writing slides
|
|
7
|
+
|
|
8
|
+
The audience gets one pass while a person talks. Put only what must be read on the slide; put explanation in speaker notes. Load `decks:working-with-decks` for the installed MDX and notes syntax.
|
|
9
|
+
|
|
10
|
+
Read [prose patterns](references/prose-patterns.md) before writing or reviewing copy. Slide rules take precedence over article habits.
|
|
11
|
+
|
|
12
|
+
| Element | Budget and shape |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| Normal conventional slide | About 70 visible words, including labels and chrome. At 150, split it. Four separate figures on one slide means redesign it. |
|
|
15
|
+
| Headline | One claim, a full sentence ending in a period. State the finding. Topic labels do not carry the talk. |
|
|
16
|
+
| Bullets | At most three, one sentence each, parallel grammatical shape. No third wrapped line. Each stands alone; dependent neighbors are one bullet. |
|
|
17
|
+
| Story card | Lead at most eight words; optional body at most twenty. One supporting sentence. Budget the rendered text, including interpolated values. |
|
|
18
|
+
| Lede | One sentence. No paragraphs anywhere in visible slide prose. |
|
|
19
|
+
| Chart title | A one-sentence finding. Units, population and period belong in a short subtitle or source context. |
|
|
20
|
+
|
|
21
|
+
This conventional scaffold excerpt shows the shape. Replace its instructional bullets with the deck's actual evidence:
|
|
22
|
+
|
|
23
|
+
```mdx
|
|
24
|
+
<h1 className="od-h2">Give each slide one claim.</h1>
|
|
25
|
+
<ul className="od-body">
|
|
26
|
+
<li>Replace this point with evidence for your claim.</li>
|
|
27
|
+
<li>Keep each bullet to one sentence.</li>
|
|
28
|
+
<li>Put supporting detail in speaker notes.</li>
|
|
29
|
+
</ul>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Write and review
|
|
33
|
+
|
|
34
|
+
1. Read just the headlines in order. They should carry the argument without the bodies.
|
|
35
|
+
2. Count visible words per conventional slide or per story beat, not words in the MDX alone. A React stage's `COPY`, labels and chips count too.
|
|
36
|
+
3. Cut paragraphs, redundant subtitles, mood-word eyebrows and repeated labels. An eyebrow earns space only by adding a fact or useful orientation.
|
|
37
|
+
4. Translate dataset column names and codes to audience language. Record recurring mappings in the deck's source notes or existing glossary; no glossary rule is enforced automatically.
|
|
38
|
+
5. Trace every proposed numeric phrase, including “half”, rankings and ratios, to `data/*.ts` and `data-sources.md` using `decks:deck-data`. Review suggestions need sources too.
|
|
39
|
+
6. Read the slide aloud with the speaker notes. The slide states the point; notes supply the qualifications, method and pacing.
|
|
40
|
+
|
|
41
|
+
## Lint is one part of review
|
|
42
|
+
|
|
43
|
+
Run `decks lint <deck>` and `decks check`. The installed lint hook, when configured and active, blocks newly written error-level rhetorical patterns in deck MDX and component prose, including literal `COPY` leads/bodies. Notes are reported as warnings. See [lint coverage and limits](references/lint.md).
|
|
44
|
+
|
|
45
|
+
Never route a denied write through another tool. Rewrite the sentence structure. A clean lint result does not check word budgets, truth, hierarchy or every rhetorical shape; inspect the rendered text yourself.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Lint coverage and limits
|
|
2
|
+
|
|
3
|
+
`decks lint [deck ...]` scans MDX under `slides/`, and TypeScript/TSX under `components/` and `layers/`, recursively. It reads visible text, MDX string props, and literal/template portions of `COPY` leads and bodies. `decks lint --stdin` reads MDX, not TSX or a whole skill document.
|
|
4
|
+
|
|
5
|
+
Notes are warnings even when the same phrase would be an on-slide error. Code, imports, comments and ordinary data identifiers are not visible prose. Interpolated values and arbitrary computed strings need rendered review; the scanner does not execute components. Text stored outside scanned directories needs manual review too.
|
|
6
|
+
|
|
7
|
+
The active pre-write lint hook checks scoped deck files for error-level hits. Its presence depends on the plugin/project hook setup. It does not enforce the full design or prose guide. `decks check` includes error-level prose; `decks lint` also exposes warnings. Treat scanner setup/parse failures as verification failures and fix the cause.
|
|
8
|
+
|
|
9
|
+
On a denied write, change the sentence's argument or structure. A synonym substitution leaves the tell intact. Do not bypass the hook with shell writes. A justified direct quotation may need a narrow documented lint allowance supported by the installed version; do not use allowances to preserve original copy that fails.
|
|
10
|
+
|
|
11
|
+
Manually verify word budgets, claim headlines, single-sentence bullets, source accuracy and repeated slide anatomy. None is established by “lint passed”.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Prose patterns
|
|
2
|
+
|
|
3
|
+
Adapted from the claude-essentials writer guidance, https://github.com/rileyhilliard/claude-essentials.
|
|
4
|
+
Copyright (c) 2025 Riley Hilliard. MIT License: permission is granted to use, copy,
|
|
5
|
+
modify, merge, publish, distribute, sublicense, and/or sell copies, provided this
|
|
6
|
+
notice is kept. The software is provided "as is", without warranty of any kind.
|
|
7
|
+
|
|
8
|
+
## Voice and concrete claims
|
|
9
|
+
|
|
10
|
+
Match the author's supplied voice: cadence, word choices and register. Do not polish it toward corporate prose. State what happened, name the actor and support the claim. Describe limits plainly. A real voice sample outranks a generic stylistic preference; evidence and slide readability still matter.
|
|
11
|
+
|
|
12
|
+
Slide headlines state claims and end in periods. Article section labels and paragraph-level rules do not apply. Slides have no visible paragraphs. Sentence rhythm can vary across the talk without making every card a slogan.
|
|
13
|
+
|
|
14
|
+
## Fix the sentence shape first
|
|
15
|
+
|
|
16
|
+
| Pattern | How to recognize it | Repair |
|
|
17
|
+
| --- | --- | --- |
|
|
18
|
+
| Negative parallelism | “Not X, but Y”, “less about X, more about Y”, or two sentences denying a straw version before asserting the point | Start with the substantive claim. |
|
|
19
|
+
| Mechanical triads | Every point has three ascending nouns, verbs or adjectives | Keep only the items the claim needs. A three-bullet ceiling is not a quota. |
|
|
20
|
+
| False range | “From X to Y” lists two examples without a meaningful scale | Name the examples directly. |
|
|
21
|
+
| Unearned profundity | “Something shifted”, “everything changed”, “X is real” | State the observable change. |
|
|
22
|
+
| Self-answered question | A rhetorical question immediately followed by the answer | Write the answer as the sentence. |
|
|
23
|
+
| Inflated significance | Calling a result pivotal, transformative or a broader movement | Give the actual result. |
|
|
24
|
+
| Characterizing a finding | “The real question is”, “that's the whole answer”, “that is the mechanism” | Delete the label; state what it refers to. |
|
|
25
|
+
| Reader direction | Telling people to sit with a number or feel its importance | Show the comparison. |
|
|
26
|
+
| Participial significance | A trailing clause about cementing, enhancing or underscoring importance | Cut it or replace it with evidence. |
|
|
27
|
+
| Copula avoidance | “Serves as”, “stands as”, “represents” in place of a plain “is” | Use the plain verb when that is the meaning. |
|
|
28
|
+
| Dramatic kicker | A final slogan restates each slide's finding | Stop at the finding. |
|
|
29
|
+
| Recap or windup | Setup that announces what the slide will cover | Start where the actual claim starts. |
|
|
30
|
+
| Hedging seesaw | Qualifiers stacked before a claim, immediately softened after it | State the claim and name its limit once. |
|
|
31
|
+
| Vague attribution | “Experts say”, “reports suggest”, “many reviewers” | Name the source or cut the claim. |
|
|
32
|
+
|
|
33
|
+
Do not add transition openers such as “Importantly”, “Notably”, “Interestingly”, “That said”, “Of course”, “In other words”, “Simply put”, “The reality is” or “It's worth noting”. They consume the first words without carrying evidence.
|
|
34
|
+
|
|
35
|
+
Avoid press-release positivity and generic benefits. Replace “seamless” with what makes the operation work; replace “powerful” with what it does. Use “use” for “leverage” or “utilize”, “show” for “underscore”, and “explain” for “delve”. Changing vocabulary alone does not fix a repeated rhetorical skeleton.
|
|
36
|
+
|
|
37
|
+
## Visible formatting
|
|
38
|
+
|
|
39
|
+
- Use sentence case. No em dashes. Use a colon, comma, parentheses or separate sentences.
|
|
40
|
+
- Bold only what needs emphasis, not scattered nouns. Remove decoration and unsolicited emoji.
|
|
41
|
+
- Keep lists for parallel points and tables for comparisons. Do not turn every point into a bold label followed by a paragraph.
|
|
42
|
+
- An eyebrow or subtitle must add scope, status, period, category or a constraint missing from the headline. Delete paraphrases.
|
|
43
|
+
|
|
44
|
+
## Review at the right scale
|
|
45
|
+
|
|
46
|
+
Read each card alone, then all headlines, then the full talk. Look for repeated syntax, identical rhetorical weight and a dramatic line at the end of every slide. Phrase matching cannot reliably find those patterns.
|
|
47
|
+
|
|
48
|
+
Put the causal explanation, uncertainty, methodology and transitions in `<Notes>`. Notes can be connected prose; on-slide text cannot. Attribute every quotation and real reported scene through `decks:deck-data`.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
@layer react-decks {
|
|
2
|
+
.rd-presenter-view {
|
|
3
|
+
--rd-ui-panel: color-mix(in oklab, currentColor 7%, transparent);
|
|
4
|
+
--rd-ui-line: color-mix(in oklab, currentColor 22%, transparent);
|
|
5
|
+
--rd-ui-dim: color-mix(in oklab, currentColor 62%, transparent);
|
|
6
|
+
--rd-ui-accent: oklch(0.8 0.13 200);
|
|
7
|
+
box-sizing: border-box;
|
|
8
|
+
position: fixed;
|
|
9
|
+
inset: 0;
|
|
10
|
+
padding: 1.25rem;
|
|
11
|
+
display: grid;
|
|
12
|
+
grid-template-columns: minmax(0, 3fr) minmax(0, 2fr);
|
|
13
|
+
grid-template-rows: minmax(0, 2fr) minmax(0, 3fr) auto;
|
|
14
|
+
gap: 1.25rem;
|
|
15
|
+
font:
|
|
16
|
+
1rem / 1.5 system-ui,
|
|
17
|
+
sans-serif;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
.rd-presenter-current,
|
|
21
|
+
.rd-presenter-next {
|
|
22
|
+
container-type: size;
|
|
23
|
+
display: grid;
|
|
24
|
+
place-items: center;
|
|
25
|
+
min-height: 0;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
.rd-presenter-current {
|
|
29
|
+
grid-row: 1 / 3;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
.rd-presenter-next {
|
|
33
|
+
grid-column: 2;
|
|
34
|
+
grid-row: 1;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/* The largest box of the audience's aspect ratio that fits the region. */
|
|
38
|
+
.rd-presenter-box {
|
|
39
|
+
position: relative;
|
|
40
|
+
width: min(100cqw, 100cqh * var(--rd-aspect));
|
|
41
|
+
overflow: hidden;
|
|
42
|
+
border-radius: 0.5rem;
|
|
43
|
+
box-shadow: 0 0 0 1px var(--rd-ui-line);
|
|
44
|
+
display: grid;
|
|
45
|
+
place-items: center;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
.rd-presenter-notes {
|
|
49
|
+
grid-column: 2;
|
|
50
|
+
grid-row: 2;
|
|
51
|
+
overflow: auto;
|
|
52
|
+
padding: 1rem 1.25rem;
|
|
53
|
+
border-radius: 0.5rem;
|
|
54
|
+
background: var(--rd-ui-panel);
|
|
55
|
+
font-size: 1.375rem;
|
|
56
|
+
line-height: 1.45;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
.rd-presenter-notes > div {
|
|
60
|
+
opacity: 0.6;
|
|
61
|
+
padding-inline-start: 0.875rem;
|
|
62
|
+
border-inline-start: 3px solid transparent;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
.rd-presenter-notes :is(p, ul, ol) {
|
|
66
|
+
margin-block: 0 0.75em;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
.rd-presenter-notes [aria-current="true"] {
|
|
70
|
+
border-inline-start-color: var(--rd-ui-accent);
|
|
71
|
+
opacity: 1;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
.rd-presenter-status {
|
|
75
|
+
grid-column: 1 / -1;
|
|
76
|
+
grid-row: 3;
|
|
77
|
+
display: flex;
|
|
78
|
+
align-items: baseline;
|
|
79
|
+
gap: 1.5rem;
|
|
80
|
+
font-variant-numeric: tabular-nums;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
.rd-presenter-status > span:not([role]),
|
|
84
|
+
.rd-presenter-status [aria-label="Local time"] {
|
|
85
|
+
color: var(--rd-ui-dim);
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
.rd-presenter-status [aria-label="Elapsed time"] {
|
|
89
|
+
margin-inline-start: auto;
|
|
90
|
+
font-size: 2.25rem;
|
|
91
|
+
font-weight: 600;
|
|
92
|
+
line-height: 1;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
.rd-presenter-status [aria-label="Local time"] {
|
|
96
|
+
font-size: 1.25rem;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
.rd-presenter-status button {
|
|
100
|
+
padding: 0.375rem 0.75rem;
|
|
101
|
+
border: 1px solid var(--rd-ui-line);
|
|
102
|
+
border-radius: 0.375rem;
|
|
103
|
+
color: inherit;
|
|
104
|
+
background: transparent;
|
|
105
|
+
font: inherit;
|
|
106
|
+
cursor: pointer;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
.rd-presenter-status button:hover,
|
|
110
|
+
.rd-presenter-status button:focus-visible {
|
|
111
|
+
border-color: var(--rd-ui-dim);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
@page {
|
|
2
|
+
margin: 0;
|
|
3
|
+
}
|
|
4
|
+
|
|
5
|
+
@layer react-decks {
|
|
6
|
+
html[data-deck-view="print"],
|
|
7
|
+
html[data-deck-view="print"] body {
|
|
8
|
+
margin: 0;
|
|
9
|
+
overflow: visible;
|
|
10
|
+
print-color-adjust: exact;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
.print {
|
|
14
|
+
width: max-content;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
.page {
|
|
18
|
+
position: relative;
|
|
19
|
+
overflow: hidden;
|
|
20
|
+
break-after: page;
|
|
21
|
+
break-inside: avoid;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
.page:last-child {
|
|
25
|
+
break-after: auto;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
.page > div > [data-deck-slide] {
|
|
29
|
+
position: absolute;
|
|
30
|
+
inset: 0;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { relative } from "node:path";
|
|
2
|
+
import { readFileSync } from "node:fs";
|
|
3
|
+
// ../node/src/dev/errors.ts
|
|
4
|
+
const displayPath = (file) => relative(process.cwd(), file) || ".";
|
|
5
|
+
/** Author input is reported at the CLI or Vite boundary, never where it is detected. */
|
|
6
|
+
var DeckError = class extends Error {
|
|
7
|
+
loc;
|
|
8
|
+
file;
|
|
9
|
+
id;
|
|
10
|
+
constructor(message, file, loc, options) {
|
|
11
|
+
const path = file === void 0 ? void 0 : displayPath(file);
|
|
12
|
+
super(`${path && options?.prefix !== false ? `${path}${loc ? `:${loc.line}:${loc.column}` : ""}: ` : ""}${message}`, options);
|
|
13
|
+
this.loc = loc;
|
|
14
|
+
this.name = "DeckError";
|
|
15
|
+
this.file = file;
|
|
16
|
+
this.id = file;
|
|
17
|
+
this.stack = "";
|
|
18
|
+
}
|
|
19
|
+
};
|
|
20
|
+
function validationError(file, issues, input, knownKeys = [], frontmatter = false) {
|
|
21
|
+
return new DeckError(issues.flatMap((issue) => {
|
|
22
|
+
const key = issue.path.join(".");
|
|
23
|
+
let value = input;
|
|
24
|
+
for (const part of issue.path) value = typeof value === "object" && value !== null ? Reflect.get(value, part) : void 0;
|
|
25
|
+
const field = `${frontmatter ? "frontmatter " : ""}${key || "config"}`;
|
|
26
|
+
const got = typeof value === "number" && !Number.isFinite(value) ? String(value) : JSON.stringify(value) ?? String(value);
|
|
27
|
+
if (issue.code === "unrecognized_keys") return issue.keys.map((key) => `unknown key ${JSON.stringify(key)}. Known keys: ${knownKeys.join(", ")}.`);
|
|
28
|
+
if (frontmatter && key === "clicks") return [`${field} must be a whole number 0 or greater, got ${got}.`];
|
|
29
|
+
if (frontmatter && key === "layers") return [`${field} must be false, "above" or "below", got ${got}.`];
|
|
30
|
+
if (issue.code === "invalid_type") return [value === void 0 ? `${field} is required (a ${issue.expected}).` : `${field} must be ${/^[aeiou]/.test(issue.expected) ? "an" : "a"} ${issue.expected}, got ${got}.`];
|
|
31
|
+
if (issue.code === "too_small" && issue.origin === "string") return [`${field} must not be empty, got ${got}.`];
|
|
32
|
+
return [`${field}: ${issue.message}, got ${got}.`];
|
|
33
|
+
}).join(`\n${displayPath(file)}: `), file);
|
|
34
|
+
}
|
|
35
|
+
function compileError(cause, file) {
|
|
36
|
+
if (cause instanceof DeckError) return cause;
|
|
37
|
+
if (!(cause instanceof Error) || !("source" in cause) || typeof cause.source !== "string" || !("ruleId" in cause) || typeof cause.ruleId !== "string") throw cause;
|
|
38
|
+
const loc = cause instanceof Error && "line" in cause && typeof cause.line === "number" && "column" in cause && typeof cause.column === "number" ? {
|
|
39
|
+
line: cause.line,
|
|
40
|
+
column: cause.column
|
|
41
|
+
} : void 0;
|
|
42
|
+
const message = cause instanceof Error ? cause.message : String(cause);
|
|
43
|
+
return new DeckError(`${message}${/[.!?]$/.test(message) ? "" : "."} Check the slide and its MDX plugins.`, file, loc, { cause });
|
|
44
|
+
}
|
|
45
|
+
/** Vite and Rolldown may wrap a plugin error while retaining its cause. */
|
|
46
|
+
function authorError(error) {
|
|
47
|
+
if (error instanceof DeckError) return error;
|
|
48
|
+
if (error instanceof Error && error.cause) return authorError(error.cause);
|
|
49
|
+
if (typeof error === "object" && error !== null && "errors" in error && Array.isArray(error.errors)) for (const child of error.errors) {
|
|
50
|
+
const found = authorError(child);
|
|
51
|
+
if (found) return found;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
// ../node/src/prose/prose-patterns.ts
|
|
55
|
+
const patternsFile = new URL(`${import.meta.url.endsWith(".ts") ? "../../lint/" : "./lint/"}ai-rhetoric-patterns.tsv`, import.meta.url);
|
|
56
|
+
function loadPatterns(file = patternsFile) {
|
|
57
|
+
const patterns = readFileSync(file, "utf8").split(/\r?\n/).filter((line) => line.trim() && !line.startsWith("#")).map((line) => {
|
|
58
|
+
const [id, severity, ere, message] = line.split(" ");
|
|
59
|
+
if (severity !== "error" && severity !== "warn") throw new Error(`${file}: pattern "${id}" has severity "${severity}", not error or warn`);
|
|
60
|
+
if (!ere) throw new Error(`${file}: pattern "${id}" has no regex`);
|
|
61
|
+
return {
|
|
62
|
+
id: id ?? "",
|
|
63
|
+
severity,
|
|
64
|
+
message,
|
|
65
|
+
re: new RegExp(ere.replaceAll("[[:space:]]", "\\s"))
|
|
66
|
+
};
|
|
67
|
+
});
|
|
68
|
+
if (!patterns.some((pattern) => pattern.severity === "error")) throw new Error(`${file} has no error-severity patterns (empty or truncated?)`);
|
|
69
|
+
return patterns;
|
|
70
|
+
}
|
|
71
|
+
function allowOf(line) {
|
|
72
|
+
if (/lint-allow\s*([}*]|-->|$)/.test(line)) return ["*"];
|
|
73
|
+
const match = /lint-allow:\s*/.exec(line);
|
|
74
|
+
return match ? line.slice(match.index + match[0].length).replace(/\s*(\*\/|-->|}).*/, "").replace(/\s/g, "").split(",") : [];
|
|
75
|
+
}
|
|
76
|
+
export { authorError as a, validationError as c, DeckError as i, loadPatterns as n, compileError as o, patternsFile as r, displayPath as s, allowOf as t };
|