Skip to content

AI-native design editor. Open-source Figma alternative.

feat(demo): export the tour's chapter names (#1104)

Danila Poyarkov411f992c68e1
diff --git a/tools/AGENTS.md b/tools/AGENTS.md
index 6da3044f7..f8ccb6af8 100644
--- a/tools/AGENTS.md
+++ b/tools/AGENTS.md
@@ -37,7 +37,7 @@ Private tooling lives under `tools/<role>/<domain>/{src,tests}`; Steiger enforce
## Demo document
-The `/demo` document is a tour of eight chapters on one page, each a section stacked top to bottom, built from `tools/generate/demo/src/document/`: `theme.ts` (the Theme and App chrome collections, each with a Dark and a Light mode that `src/app/demo/theme.ts` switches by name to follow the app's theme; every color in the tour, icons included, is bound to them), `callout.tsx` (the Tip component every chapter instances, whose Where slot each fills with a piece of the app from `chrome.tsx`, drawn to the dark theme's tokens with the target ringed), `player/` (the player card, its artwork slot, and its controls with behaviours), and one file per chapter under `chapters/`, laid out by `chapters/chapter.ts` as numeral, heading, subject, and tip; `src/app/demo/viewport.ts` opens the tour on the first chapter. It renders design JSX through `document/icons.ts`, which serves Lucide from the bundled icon JSON so the build needs no Iconify API, and writes the ignored `public/demo.fig`, which the app opens like any `.fig` file; it is never generated in the browser. `ensureDemoDocument` runs from `vite.config.ts`, rebuilds only when its inputs' fingerprint changes, and runs the build in Bun; `bun run generate:demo` forces it. A chapter that needs something new from the engine adds that package's `src` to the fingerprint in `tools/generate/demo/src/ensure.ts`. Shader fills get their still frames from `src/shaders/stills.ts`, which draws each preset in the Playwright Chromium with WebGPU (`bunx playwright install chromium` locally; the deploy and preview workflows install it); without the browser the build warns and the editor draws the frames when the demo opens.
+The `/demo` document is a tour of eight chapters on one page, each a section stacked top to bottom, built from `tools/generate/demo/src/document/`: `theme.ts` (the Theme and App chrome collections, each with a Dark and a Light mode that `src/app/demo/theme.ts` switches by name to follow the app's theme; every color in the tour, icons included, is bound to them), `callout.tsx` (the Tip component every chapter instances, whose Where slot each fills with a piece of the app from `chrome.tsx`, drawn to the dark theme's tokens with the target ringed), `player/` (the player card, its artwork slot, and its controls with behaviours), and one file per chapter under `chapters/`, laid out by `chapters/chapter.ts` as numeral, heading, subject, and tip, with each section's and subject's name from `chapters/names.ts`, which hosts outside the app such as the docs landing import from `@open-pencil/demo-tools/chapters`; `src/app/demo/viewport.ts` opens the tour on the first chapter. It renders design JSX through `document/icons.ts`, which serves Lucide from the bundled icon JSON so the build needs no Iconify API, and writes the ignored `public/demo.fig`, which the app opens like any `.fig` file; it is never generated in the browser. `ensureDemoDocument` runs from `vite.config.ts`, rebuilds only when its inputs' fingerprint changes, and runs the build in Bun; `bun run generate:demo` forces it. A chapter that needs something new from the engine adds that package's `src` to the fingerprint in `tools/generate/demo/src/ensure.ts`. Shader fills get their still frames from `src/shaders/stills.ts`, which draws each preset as WebP in the Playwright Chromium with WebGPU (`bunx playwright install chromium` locally; the deploy and preview workflows install it); without the browser the build warns and the editor draws the frames when the demo opens.
## Brand assets
diff --git a/tools/generate/demo/package.json b/tools/generate/demo/package.json
index c7792fd27..38c6ec986 100644
--- a/tools/generate/demo/package.json
+++ b/tools/generate/demo/package.json
@@ -6,7 +6,8 @@
"#demo/*": "./src/*.ts"
},
"exports": {
- ".": "./src/ensure.ts"
+ ".": "./src/ensure.ts",
+ "./chapters": "./src/document/chapters/names.ts"
},
"scripts": {
"test": "bun test tests"
diff --git a/tools/generate/demo/src/document/chapters/chapter.ts b/tools/generate/demo/src/document/chapters/chapter.ts
index b7d413464..a8ad79645 100644
--- a/tools/generate/demo/src/document/chapters/chapter.ts
+++ b/tools/generate/demo/src/document/chapters/chapter.ts
@@ -13,6 +13,7 @@ import { tipInstance, type Tip } from '../callout'
import { renderTree } from '../icons'
import { fillSlot } from '../slot-content'
import type { Theme } from '../theme'
+import { sectionName, type TourChapter } from './names'
/** Where the first chapter sits on the page. */
export const PAGE_ORIGIN = 0
@@ -101,15 +102,16 @@ function heading({ vars }: Theme, index: number, { title, subtitle }: Heading):
/**
* Lay a chapter out in a section of its own: heading, then `subject` under it, then `tip` to
- * the subject's right, top aligned. `fill` adds to the subject once it exists, before the tip
- * is placed beside it, for content that needs the subject's layers, such as instances of a
- * component in it. The section is left at the page origin; `arrangeChapters` places it.
+ * the subject's right, top aligned. The section and the subject take their names from
+ * `chapter`, which hosts outside the tour find them by. `fill` adds to the subject once it
+ * exists, before the tip is placed beside it, for content that needs the subject's layers, such
+ * as instances of a component in it. The section is left at the page origin; `arrangeChapters`
+ * places it.
*/
export async function layoutChapter(
context: ChapterContext,
options: {
- index: number
- name: string
+ chapter: TourChapter
heading: Heading
subject: TreeNode
tip: Tip
@@ -117,10 +119,11 @@ export async function layoutChapter(
}
): Promise<Chapter> {
const { graph, pageId } = context
+ const { chapter } = options
const section = await place(
context,
Section({
- name: `${options.index} · ${options.name}`,
+ name: sectionName(chapter),
w: 100,
h: 100,
bg: context.theme.vars.section
@@ -132,13 +135,15 @@ export async function layoutChapter(
const pad = CHAPTER_PADDING
const head = await place(
context,
- heading(context.theme, options.index, options.heading),
+ heading(context.theme, chapter.index, options.heading),
section.id,
pad,
pad
)
const top = pad + head.height + HEADING_GAP
- let subject = await place(context, options.subject, section.id, pad, top)
+ const placed = await place(context, options.subject, section.id, pad, top)
+ graph.updateNode(placed.id, { name: chapter.subject })
+ let subject = graph.getNode(placed.id) ?? placed
if (options.fill) {
await options.fill(subject)
computeAllLayouts(graph, pageId)
diff --git a/tools/generate/demo/src/document/chapters/code.ts b/tools/generate/demo/src/document/chapters/code.ts
index 80f6e31ae..6c9b4aa4e 100644
--- a/tools/generate/demo/src/document/chapters/code.ts
+++ b/tools/generate/demo/src/document/chapters/code.ts
@@ -2,13 +2,13 @@ import { Instance } from '@open-pencil/design-jsx'
import { panelTabs } from '../chrome'
import { layoutChapter, type Chapter, type ChapterContext } from './chapter'
+import { CHAPTERS } from './names'
import type { Player } from './slots'
/** Code: the player once more, for the Code tab to read. */
export function createCodeChapter(context: ChapterContext, player: Player): Promise<Chapter> {
return layoutChapter(context, {
- index: 6,
- name: 'Code',
+ chapter: CHAPTERS.code,
heading: {
title: 'It is code, too.',
subtitle:
diff --git a/tools/generate/demo/src/document/chapters/controls.ts b/tools/generate/demo/src/document/chapters/controls.ts
index 9e0ab30a1..8ba51db98 100644
--- a/tools/generate/demo/src/document/chapters/controls.ts
+++ b/tools/generate/demo/src/document/chapters/controls.ts
@@ -5,6 +5,7 @@ import { previewPill } from '../chrome'
import type { PlayerParts } from '../player/card'
import { optionToggle, playToggle, progressSlider, skipButton } from '../player/controls'
import { layoutChapter, type ChapterContext } from './chapter'
+import { CHAPTERS } from './names'
/** The variant of the set `setId` named `name`. */
export function variantOf(graph: SceneGraph, setId: string, name: string): string {
@@ -20,15 +21,13 @@ export function variantOf(graph: SceneGraph, setId: string, name: string): strin
export async function createControlsChapter(context: ChapterContext): Promise<PlayerParts> {
const { graph, theme } = context
const { subject: board } = await layoutChapter(context, {
- index: 3,
- name: 'Controls',
+ chapter: CHAPTERS.controls,
heading: {
title: 'They work.',
subtitle:
'Each main component has a behaviour from the panel: a slider, two toggles, a button. In preview they run as real Reka UI controls, drawn by their own variants.'
},
subject: Frame({
- name: 'Controls',
flex: 'col',
w: 'hug',
h: 'hug',
diff --git a/tools/generate/demo/src/document/chapters/hello.ts b/tools/generate/demo/src/document/chapters/hello.ts
index fb8da079a..ff0722fb9 100644
--- a/tools/generate/demo/src/document/chapters/hello.ts
+++ b/tools/generate/demo/src/document/chapters/hello.ts
@@ -3,6 +3,7 @@ import type { ShaderPreset } from '@open-pencil/scene-graph'
import { previewButton } from '../chrome'
import { layoutChapter, type Chapter, type ChapterContext } from './chapter'
+import { CHAPTERS } from './names'
import type { Player } from './slots'
export const HERO_WIDTH = 880
@@ -31,15 +32,13 @@ export const HERO_PRESET: ShaderPreset = {
/** Hello: the player on a live background, and the one thing to try first. */
export function createHelloChapter(context: ChapterContext, player: Player): Promise<Chapter> {
return layoutChapter(context, {
- index: 1,
- name: 'Hello',
+ chapter: CHAPTERS.hello,
heading: {
title: 'Hello.',
subtitle:
'This file is a short tour. Scroll down, or drag the canvas with the hand tool, to follow it: every chapter shows one thing and a card tells you what to try. Nothing here is a mock-up: it is all editable.'
},
subject: Frame({
- name: 'Hero',
flex: 'row',
w: HERO_WIDTH,
h: HERO_HEIGHT,
diff --git a/tools/generate/demo/src/document/chapters/lint.ts b/tools/generate/demo/src/document/chapters/lint.ts
index af6c85417..fc4197969 100644
--- a/tools/generate/demo/src/document/chapters/lint.ts
+++ b/tools/generate/demo/src/document/chapters/lint.ts
@@ -2,20 +2,19 @@ import { Frame, Text } from '@open-pencil/design-jsx'
import { panelTabs } from '../chrome'
import { layoutChapter, type Chapter, type ChapterContext } from './chapter'
+import { CHAPTERS } from './names'
/** Lint: a card with issues planted in it, for the Lint tab to find. */
export function createLintChapter(context: ChapterContext): Promise<Chapter> {
const { vars } = context.theme
return layoutChapter(context, {
- index: 7,
- name: 'Lint',
+ chapter: CHAPTERS.lint,
heading: {
title: 'It checks itself.',
subtitle:
'Lint reads the document the way a reviewer would: contrast, touch targets, layer names, spacing, colors that bypass the variables. The same rules run from the CLI, so a CI job can fail on them.'
},
subject: Frame({
- name: 'Sign-in',
flex: 'col',
w: 360,
h: 'hug',
diff --git a/tools/generate/demo/src/document/chapters/modes.ts b/tools/generate/demo/src/document/chapters/modes.ts
index ed4eb647c..ff77b14de 100644
--- a/tools/generate/demo/src/document/chapters/modes.ts
+++ b/tools/generate/demo/src/document/chapters/modes.ts
@@ -2,6 +2,7 @@ import { Frame, Instance } from '@open-pencil/design-jsx'
import { variablesRow } from '../chrome'
import { layoutChapter, type Chapter, type ChapterContext } from './chapter'
+import { CHAPTERS } from './names'
import type { Player } from './slots'
/** Modes: the same player twice, each frame reading the Theme collection in its own mode. */
@@ -22,15 +23,13 @@ export async function createModesChapter(
children: [Instance({ of: player.id })]
})
const chapter = await layoutChapter(context, {
- index: 4,
- name: 'Modes',
+ chapter: CHAPTERS.modes,
heading: {
title: 'It has modes.',
subtitle:
'Every color and radius in the player is a variable from one Theme collection. Each frame reads it in its own mode; nothing else differs. The rest of the tour follows the app’s theme the same way.'
},
subject: Frame({
- name: 'Modes',
flex: 'row',
w: 'hug',
h: 'hug',
diff --git a/tools/generate/demo/src/document/chapters/names.ts b/tools/generate/demo/src/document/chapters/names.ts
new file mode 100644
index 000000000..115440dc7
--- /dev/null
+++ b/tools/generate/demo/src/document/chapters/names.ts
@@ -0,0 +1,28 @@
+/**
+ * The tour's chapters in reading order: the number and name its section shows, and the name of
+ * its subject, the layer the chapter is about. Hosts that show one chapter, such as the docs
+ * landing, find it by these names; `tests/build.test.ts` holds the document to them.
+ */
+export const CHAPTERS = {
+ hello: { index: 1, name: 'Hello', subject: 'Hero' },
+ slots: { index: 2, name: 'Slots', subject: 'Players' },
+ controls: { index: 3, name: 'Controls', subject: 'Controls' },
+ modes: { index: 4, name: 'Modes', subject: 'Modes' },
+ shaders: { index: 5, name: 'Shaders', subject: 'Shaders' },
+ code: { index: 6, name: 'Code', subject: 'Player' },
+ lint: { index: 7, name: 'Lint', subject: 'Sign-in' },
+ yours: { index: 8, name: 'Yours', subject: 'Ways' }
+} as const satisfies Record<string, TourChapter>
+
+export interface TourChapter {
+ index: number
+ name: string
+ subject: string
+}
+
+export type ChapterKey = keyof typeof CHAPTERS
+
+/** The chapter's section name, as the layer list shows it. */
+export function sectionName({ index, name }: TourChapter): string {
+ return `${index} · ${name}`
+}
diff --git a/tools/generate/demo/src/document/chapters/shaders.ts b/tools/generate/demo/src/document/chapters/shaders.ts
index 18010f17b..26f04ab87 100644
--- a/tools/generate/demo/src/document/chapters/shaders.ts
+++ b/tools/generate/demo/src/document/chapters/shaders.ts
@@ -6,6 +6,7 @@ import { fillRow } from '../chrome'
import { COVER_PRESET } from '../player/card'
import type { Theme } from '../theme'
import { layoutChapter, type Chapter, type ChapterContext } from './chapter'
+import { CHAPTERS } from './names'
const TILE = 320
@@ -50,15 +51,13 @@ function tile({ vars }: Theme, { name, preset }: (typeof PRESETS)[number]): Tree
/** Shaders: a fill that moves, on plain rectangles, with its preset editable in the fill picker. */
export function createShadersChapter(context: ChapterContext): Promise<Chapter> {
return layoutChapter(context, {
- index: 5,
- name: 'Shaders',
+ chapter: CHAPTERS.shaders,
heading: {
title: 'Fills can move.',
subtitle:
'A shader is a fill like any other: pick it in the fill picker, stack effects, tune their sliders, or paste a preset from shaders.com. Files keep a still of it, and preview plays it.'
},
subject: Frame({
- name: 'Shaders',
flex: 'row',
w: 'hug',
h: 'hug',
diff --git a/tools/generate/demo/src/document/chapters/slots.ts b/tools/generate/demo/src/document/chapters/slots.ts
index f15eb8e34..2e39e1dfe 100644
--- a/tools/generate/demo/src/document/chapters/slots.ts
+++ b/tools/generate/demo/src/document/chapters/slots.ts
@@ -13,6 +13,7 @@ import { ARTWORK_NAME, PLAYER_PROPERTIES, playerComponent, type PlayerParts } fr
import { fillSlot } from '../slot-content'
import type { Theme } from '../theme'
import { layoutChapter, type ChapterContext } from './chapter'
+import { CHAPTERS } from './names'
export interface Player {
/** The Player main component. */
@@ -78,15 +79,13 @@ export async function createSlotsChapter(
const { graph, theme } = context
const player: Player = { id: '', slotId: createComponentPropertyId() }
await layoutChapter(context, {
- index: 2,
- name: 'Slots',
+ chapter: CHAPTERS.slots,
heading: {
title: 'It is a component.',
subtitle:
'The player on the left is the main component. Its artwork is a slot: every instance keeps the player and brings its own cover.'
},
subject: Frame({
- name: 'Players',
flex: 'row',
w: 'hug',
h: 'hug',
diff --git a/tools/generate/demo/src/document/chapters/yours.ts b/tools/generate/demo/src/document/chapters/yours.ts
index f4d3c1f6e..f61b51549 100644
--- a/tools/generate/demo/src/document/chapters/yours.ts
+++ b/tools/generate/demo/src/document/chapters/yours.ts
@@ -11,6 +11,7 @@ import {
type Chapter,
type ChapterContext
} from './chapter'
+import { CHAPTERS } from './names'
const TIP_COMPONENT_GAP = 96
@@ -83,15 +84,13 @@ function way({ vars }: Theme, { icon, title, body }: (typeof WAYS)[number]): Tre
export async function createYoursChapter(context: ChapterContext): Promise<Chapter> {
const { graph, theme } = context
const chapter = await layoutChapter(context, {
- index: 8,
- name: 'Yours',
+ chapter: CHAPTERS.yours,
heading: {
title: 'Now make it yours.',
subtitle:
'The tour ends here. The document does not: everything in it is yours to edit, and it works with what you already have.'
},
subject: Frame({
- name: 'Ways',
flex: 'col',
w: 640,
h: 'hug',
diff --git a/tools/generate/demo/tests/build.test.ts b/tools/generate/demo/tests/build.test.ts
index b911818a7..df5b36d28 100644
--- a/tools/generate/demo/tests/build.test.ts
+++ b/tools/generate/demo/tests/build.test.ts
@@ -1,6 +1,7 @@
import { beforeAll, describe, expect, test } from 'bun:test'
import { buildDemoGraph, measuringRenderer } from '#demo/build'
+import { CHAPTERS, sectionName } from '#demo/document/chapters/names'
import { exportFigFile, readFigFile } from '@open-pencil/core/io'
import { populateAllFigPages } from '@open-pencil/core/io/formats/fig'
@@ -61,18 +62,21 @@ describe('the demo document', () => {
.getChildren(page.id)
.filter((node) => node.type === 'SECTION')
.sort((a, b) => a.y - b.y)
- expect(chapters.map((chapter) => chapter.name)).toEqual([
- '1 · Hello',
- '2 · Slots',
- '3 · Controls',
- '4 · Modes',
- '5 · Shaders',
- '6 · Code',
- '7 · Lint',
- '8 · Yours'
- ])
+ expect(chapters.map((chapter) => chapter.name)).toEqual(
+ Object.values(CHAPTERS).map(sectionName)
+ )
// The layer list reads the first child first.
- expect(graph.getChildren(page.id)[0]?.name).toBe('1 · Hello')
+ expect(graph.getChildren(page.id)[0]?.name).toBe(sectionName(CHAPTERS.hello))
+ })
+
+ test("names each chapter's subject as hosts look it up", () => {
+ const [page] = graph.getPages()
+ const sections = graph.getChildren(page.id)
+ for (const chapter of Object.values(CHAPTERS)) {
+ const section = sections.find((node) => node.name === sectionName(chapter))
+ const children = section ? graph.getChildren(section.id) : []
+ expect(children.filter((child) => child.name === chapter.subject)).toHaveLength(1)
+ }
})
test('keeps complete behaviours on the player controls', () => {