From 338dbb6b6991bc1d3a8da07611b005fa72d61667 Mon Sep 17 00:00:00 2001 From: Marie Chatfield Date: Thu, 25 Jun 2026 14:59:38 -0700 Subject: [PATCH] chore: add docs skills and update doc guides Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .claude/agents/tsdoc-auditor.md | 10 +- .../components.md | 3 +- .claude/doc-guides/docs-shared.md | 51 +++++++ .claude/{tsdoc-guides => doc-guides}/flows.md | 46 ++++++- .claude/{tsdoc-guides => doc-guides}/hooks.md | 6 +- .claude/skills/docs-change-ia/REFERENCE.md | 125 ++++++++++++++++++ .claude/skills/docs-change-ia/SKILL.md | 101 ++++++++++++++ .claude/skills/docs-check/SKILL.md | 93 +++++++++++++ .claude/skills/docs-regen/SKILL.md | 48 +++++++ .claude/skills/tsdoc/SKILL.md | 10 +- cspell.json | 1 + 11 files changed, 475 insertions(+), 19 deletions(-) rename .claude/{tsdoc-guides => doc-guides}/components.md (91%) create mode 100644 .claude/doc-guides/docs-shared.md rename .claude/{tsdoc-guides => doc-guides}/flows.md (53%) rename .claude/{tsdoc-guides => doc-guides}/hooks.md (93%) create mode 100644 .claude/skills/docs-change-ia/REFERENCE.md create mode 100644 .claude/skills/docs-change-ia/SKILL.md create mode 100644 .claude/skills/docs-check/SKILL.md create mode 100644 .claude/skills/docs-regen/SKILL.md diff --git a/.claude/agents/tsdoc-auditor.md b/.claude/agents/tsdoc-auditor.md index 4f91bc97c..46ec1e6e9 100644 --- a/.claude/agents/tsdoc-auditor.md +++ b/.claude/agents/tsdoc-auditor.md @@ -76,11 +76,11 @@ Confirm clean before reporting. Before auditing a specific symbol type, read the relevant guide: -| Symbol type | Guide | -| ----------- | ------------------------------------ | -| Hooks | `.claude/tsdoc-guides/hooks.md` | -| Components | `.claude/tsdoc-guides/components.md` | -| Flows | `.claude/tsdoc-guides/flows.md` | +| Symbol type | Guide | +| ----------- | ---------------------------------- | +| Hooks | `.claude/doc-guides/hooks.md` | +| Components | `.claude/doc-guides/components.md` | +| Flows | `.claude/doc-guides/flows.md` | ## ESLint compliance diff --git a/.claude/tsdoc-guides/components.md b/.claude/doc-guides/components.md similarity index 91% rename from .claude/tsdoc-guides/components.md rename to .claude/doc-guides/components.md index f0675ea0e..ff6786b18 100644 --- a/.claude/tsdoc-guides/components.md +++ b/.claude/doc-guides/components.md @@ -16,8 +16,7 @@ Every exported React component's `@remarks` must include an events table listing ## @example -- **Skip** for components documented in `docs/workflows-overview/` — that page is the canonical integration example. Add a `@see` tag pointing to it instead. -- **Include** for standalone blocks and utilities without a workflow page. +Include for all public block components. For components typically consumed via a flow rather than standalone, a minimal usage example (component with required props) is still useful — it shows the basic API without requiring full flow context. ## Release tags diff --git a/.claude/doc-guides/docs-shared.md b/.claude/doc-guides/docs-shared.md new file mode 100644 index 000000000..ff8081b4e --- /dev/null +++ b/.claude/doc-guides/docs-shared.md @@ -0,0 +1,51 @@ +# Docs site — shared reference + +Canonical facts shared by the docs skills (`docs-check`, `docs-regen`, +`docs-change-ia`) so they don't drift. Read whichever skill matches your task. + +## npm scripts (run from the repo root) + +All docs scripts live in the **root** `package.json` and delegate into `docs-site/`. + +| Script | What it does | +| --------------------------- | ------------------------------------------------------------------------------ | +| `npm run docs` | Docusaurus **dev server** (hot reload) at http://localhost:3000 | +| `npm run docs:install` | Install `docs-site/` deps (`npm install` inside `docs-site/`) | +| `npm run docs:build` | **Production build**. Throws on any broken link/anchor — the real gate | +| `npm run docs:lint` | Verify every `docs/**/*.md` has `title` + `description` frontmatter | +| `npm run docs:serve` | Serve the already-built production site locally | +| `npm run docs:api:generate` | Regenerate **reference docs only** (TypeDoc). Fast iterate path | +| `npm run derive` | Full derived pipeline: SDK build + endpoint inventory + api report + reference | + +Any script that builds or generates needs `docs-site/` deps installed first: + +```bash +test -d docs-site/node_modules || npm run docs:install +``` + +## Two kinds of content — know which you're touching + +Get this wrong and edits either don't stick or break the build. + +| | **Hand-authored** | **Auto-generated reference** | +| ------- | -------------------------------------- | ----------------------------------------------------- | +| Where | `docs/**` _except_ `docs/reference/**` | `docs/reference/**` only | +| Source | the `.md`/`.mdx` file itself | TSDoc in `src/` + reference config | +| Edit by | editing the file | editing TSDoc + `router.config.ts`, then regenerating | +| Sidebar | listed in `docs-site/sidebars.ts` | `{ type: 'autogenerated', dirName: 'reference' }` | + +**Never hand-edit a file under `docs/reference/`** — the next regeneration overwrites it +(its frontmatter carries `generated_by: typedoc`, `custom_edit_url: null`). To change +generated content or structure, use `docs-regen` and `docs-change-ia` → `REFERENCE.md`. + +The dev server hot-reloads hand-authored content only; reference changes need +regenerating. + +## Publishing and writing rules + +Source of truth is **this repo** (`embedded-react-sdk`); a release workflow builds and +publishes to `sdk.gusto.com`. All work is local and previewed first. + +These docs are **partner-facing**. The writing rules (second person, don't speculate +about the reader's app, no internal `@/` import aliases in code samples) live in the +root `CLAUDE.md` under **Documentation** — follow them there. diff --git a/.claude/tsdoc-guides/flows.md b/.claude/doc-guides/flows.md similarity index 53% rename from .claude/tsdoc-guides/flows.md rename to .claude/doc-guides/flows.md index 90b2092c3..857e1d035 100644 --- a/.claude/tsdoc-guides/flows.md +++ b/.claude/doc-guides/flows.md @@ -30,20 +30,58 @@ Flows are the primary user of the `@components` block tag — it documents the b Place it after `@remarks` and before `@param`/`@returns` (the `tsdoc-sort-tags` rule enforces this grouping). Link names must resolve to documented exports for the table to link them; unresolved names still render as plain text rows. +**Correctness rules — get these wrong and the table is misleading:** + +- **List what the machine actually renders.** Trace the `*Components.tsx` return statements. Do not list an umbrella name that is itself a standalone `` the machine never directly mounts. +- **Wrapper flows collapse.** If the flow composes another separately-documented flow as a step (e.g. `OnboardingExecutionFlow`), list just that sub-flow as one entry — not its internal steps. The sub-flow's own `@components` owns its children. +- **Cross-namespace nodes need the namespace.** `{@link EmployeeOnboarding.OnboardingExecutionFlow}`, not just `{@link OnboardingExecutionFlow}`. +- **The diagram and `@components` must agree.** If the GUIDE.md diagram collapses a sub-flow to one node, the `@components` list must match. + ## @example -Flows are always documented in `docs/workflows-overview/` — skip `@example` in TSDoc. Use a `@see` tag pointing to the relevant overview page. +Every flow needs a `@example`. Examples live in TSDoc as the source of truth. + +**Hub/loop flows** (resting list with no terminal state, e.g. `PayrollFlow`, `EmployeeListFlow`) — show minimal wiring; `onEvent` is optional but useful for showing navigation events: + +````ts +@example +```tsx + { + if (event.eventName === 'payroll/exit') navigate('/dashboard') + }} +/> +``` +```` + +**Guided flows** (linear steps with a real exit, e.g. `OnboardingExecutionFlow`, `TerminationFlow`) — `onEvent` is **required** in the example and must handle the exit event by name. A guided flow example that only shows `onDone` is incomplete: + +````ts +@example +```tsx + { + // The flow exits when the partner navigates away or cancels + if (event.eventName === 'employee/onboarding/done') navigate('/employees') + }} +/> +``` +```` + +Pull the exact exit event string from `src/shared/constants.ts` componentEvents — don't guess. If the exit event bubbles via `onEvent` without a machine transition (the machine ignores it), note that in a comment in the example. ## What requires product context The business intent behind a flow's sequence (why these blocks, why this order) often isn't deducible from block names alone. Sources: -1. `docs/workflows-overview/` — typically has the narrative +1. The GUIDE.md colocated with the flow component — typically has the narrative 2. Jira epic or feature ticket in the current conversation -3. Ask the human if the workflow page is missing or incomplete +3. Ask the human if both are missing or incomplete Do not invent the purpose of a flow from its block structure. ## Long-form prose: GUIDE.md -Keep `@remarks` to concise observable behavior. Extended narrative for a flow — walkthroughs, sequencing rationale, integration notes — belongs in a `GUIDE.md` colocated in the flow's source directory; the doc engine slots it into the generated reference page. `GUIDE.md` is authored prose (Prettier-exempt), distinct from generated content. Don't migrate prose into `GUIDE.md` speculatively — the authoring conventions are still being established in the guide-content PRs; write the TSDoc, and leave narrative to the human unless directed otherwise. +Keep `@remarks` to concise observable behavior. Extended narrative for a flow — walkthroughs, sequencing rationale, integration notes — belongs in a `GUIDE.md` colocated in the flow's source directory; the doc engine slots it into the generated reference page. `GUIDE.md` is authored prose (Prettier-exempt), distinct from generated content. diff --git a/.claude/tsdoc-guides/hooks.md b/.claude/doc-guides/hooks.md similarity index 93% rename from .claude/tsdoc-guides/hooks.md rename to .claude/doc-guides/hooks.md index c868beeac..28b53e68a 100644 --- a/.claude/tsdoc-guides/hooks.md +++ b/.claude/doc-guides/hooks.md @@ -41,7 +41,7 @@ This is not inferrable from the hook alone. Read `fields.tsx` before writing `@r ## Usage patterns -Two integration patterns exist — use the one that matches `docs/workflows-overview/` for this hook: +Two integration patterns exist — use the one that matches existing usage in `src/components/` or the flow's GUIDE.md for this hook: **`SDKFormProvider` pattern** — partner wraps a group of fields from one hook: @@ -71,7 +71,7 @@ These cannot be inferred from code alone and need human context before writing ` **Sources in priority order:** 1. Jira ticket or PR description in the current conversation -2. `docs/workflows-overview/` for established patterns +2. GUIDE.md colocated with the flow that uses this hook 3. MCP: Jira, Confluence, or Notion if linked 4. Ask the human — do not invent business rules @@ -83,4 +83,4 @@ If none are available, write the structural parts (`@param`, `@returns`, release ## Long-form prose: GUIDE.md -Like flows, each hook directory can carry a `GUIDE.md` whose authored prose the doc engine slots into the hook's generated reference page. Keep `@remarks` to concise observable behavior; longer walkthroughs go in `GUIDE.md`. Don't create or backfill `GUIDE.md` speculatively — its authoring conventions are still being established in the guide-content PRs. +Like flows, each hook directory can carry a `GUIDE.md` whose authored prose the doc engine slots into the hook's generated reference page. Keep `@remarks` to concise observable behavior; longer walkthroughs go in `GUIDE.md`. Don't create or backfill `GUIDE.md` speculatively without direction. diff --git a/.claude/skills/docs-change-ia/REFERENCE.md b/.claude/skills/docs-change-ia/REFERENCE.md new file mode 100644 index 000000000..f7748478c --- /dev/null +++ b/.claude/skills/docs-change-ia/REFERENCE.md @@ -0,0 +1,125 @@ +# Auto-generated reference — internals + +Read this before touching anything under `docs/reference/**`, the typedoc-custom plugin, +or `GUIDE.md` files. `SKILL.md` covers hand-authored content; this covers the generated +half. + +## How reference docs are produced + +TypeDoc reads TSDoc from `src/`, and a custom plugin (`docs-site/plugins/typedoc-custom/`) +routes each symbol into the `docs/reference/` tree. Output is committed but never +hand-written — including the `_category_.json` sidebar files the plugin emits. + +Regenerate after any change to TSDoc, `router.config.ts`, or `typedoc.config.ts`: + +```bash +test -d docs-site/node_modules || npm run docs:install # one-time prerequisite +npm run docs:api:generate # reference only (TypeDoc) — fast iterate path +npm run derive # full pipeline; use for a clean final pass +git diff docs/reference/ # confirm you changed only what you intended +``` + +## The reference IA config: `router.config.ts` + +`docs-site/plugins/typedoc-custom/router.config.ts` is the single source of truth for +reference structure; its own TSDoc comments are the authoritative spec. Two exported +arrays matter, and **array order sets sidebar position** in both. + +`DOMAINS` — the domain → namespace tree. Each entry is a top-level reference category +(e.g. **Employees**, **Payroll**): + +- `label` — sidebar category label and the domain hub's H1. +- `path` — output slug **and** source-dir lookup (`employee` → `src/components/Employee`; + `time-off` → `src/components/TimeOff`). +- `namespaces` — namespaces under the domain, in render/sidebar order. Add one with + `{ id, subpath }` (id must match the namespace exported from `src/components/index.ts`). + +`STANDALONE_PAGES` — symbols that don't belong to a domain, collected one page each +(currently `theme-variables`, `component-inventory`, `utilities`, `events`): + +- `id` — output slug → `docs/reference/.md`. +- `sources` — source-path fragments; a symbol routes here if its path contains any. +- `groups` — optional `@group` filter (e.g. `events` takes only the `Events` group). +- `displayName` — the page H1. + +Reorder/relabel by editing the arrays, then regenerate. + +## Ordering content within a generated page + +You do **not** edit the generated `.md`. Order comes from two places: + +- **`docs-site/typedoc.config.ts`** — `groupOrder` lists section names top-to-bottom (the + constants live in `docs-site/typedoc-utils.mjs`: `COMPONENT_GROUPS`, `HOOK_GROUPS`, + `COMPONENT_PROP_GROUPS`, `VARIABLE_GROUPS`); `sort: ['required-first', 'alphabetical']` + orders members within a group. +- **`@group` tags** in the TSDoc decide which section a symbol falls into. + +So: reorder _sections_ via `groupOrder` / the group-name arrays; reorder _items within a +section_ via `sort` or names; move an item between sections by changing its `@group` tag. + +## Injecting hand-authored prose into a generated page: `GUIDE.md` + +To make authored narrative read as part of a generated hub/flow page, the plugin slots a +`GUIDE.md`'s sections into the page. Where it looks: + +- **Domain hub** → `src/components//GUIDE.md` (Domain = PascalCase of the domain + `path`, e.g. `time-off` → `src/components/TimeOff/GUIDE.md`). +- **Flow page** → `GUIDE.md` beside the `*Flow` component's source. +- **Hook page** → `GUIDE.md` at the root of the hook's directory. + +Format (parsed by `docs-site/plugins/typedoc-custom/utils.ts`): the leading `# H1` is +dropped as an author title; each `## section` is tagged with a slot comment. + +```markdown +# My Guide (title — not rendered) + +## Overview + + + +Prose that lands at the top of the generated page. + +## Notes + + + +Prose that lands at the bottom. +``` + +Recognized slots are **`overview`** and **`appendix`** (`GUIDE_SLOTS` in `utils.ts`). +Untagged/unknown-slot sections fall through to `appendix` with a build warning — content +is never silently dropped, but tag deliberately. Adding a slot means editing `GUIDE_SLOTS` +in `utils.ts` and the rendering in `theme.ts` — a code change beyond pure IA work, so +coordinate first. + +## Grouping a generated reference page into a hand-authored sidebar section + +The page is already emitted by the autogenerated **Reference** block, so naming it in a +second category duplicates it. Remove the duplicate via the `sidebarItemsGenerator` hook +in `docusaurus.config.ts` (which already does this for `reference/index`): + +```ts +sidebarItemsGenerator: async ({ defaultSidebarItemsGenerator, ...args }) => { + const items = await defaultSidebarItemsGenerator(args) + return items.filter( + item => + !(item.type === 'doc' && item.id === 'reference/index') && + !(item.type === 'doc' && item.id === 'reference/theme-variables'), // ← relocated + ) +}, +``` + +Then add `'reference/theme-variables'` to the **Theming** category's `items` in +`sidebars.ts`. The page now renders once, under Theming. Verify with `npm run docs:build`. + +## Verifying reference changes + +```bash +npm run docs:api:generate # or npm run derive for a clean pass +git diff docs/reference/ # only the intended files changed +npm run docs:build # passes — broken links/anchors throw +``` + +If you change routing _logic_ (not just config), run the docs-site tests +(`npm --prefix docs-site test`); the router suite is +`docs-site/plugins/typedoc-custom/sdk-router.test.ts`. diff --git a/.claude/skills/docs-change-ia/SKILL.md b/.claude/skills/docs-change-ia/SKILL.md new file mode 100644 index 000000000..7061e208b --- /dev/null +++ b/.claude/skills/docs-change-ia/SKILL.md @@ -0,0 +1,101 @@ +--- +name: docs-change-ia +description: >- + Reorganize the docs site's IA — move/split pages, reorder/relabel the sidebar, + restructure the reference. Use when a docs task touches docs-site/sidebars.ts, + page placement, or nav structure, or on "reorganize docs"/"move this page". +argument-hint: '[what you want to reorganize — e.g. "move theming guide next to the reference"]' +--- + +# Reorganize the docs-site IA + +The docs site is a [Docusaurus](https://docusaurus.io) site. For the script map and the +hand-authored-vs-generated content model (which everything below hinges on), see +[`docs-shared.md`](../../doc-guides/docs-shared.md). Deep reference internals are in `REFERENCE.md` in +this folder. The docs are **partner-facing** — follow the writing rules in the root +`CLAUDE.md`. + +**Never hand-edit a file under `docs/reference/`** — it's regenerated and your changes +are overwritten. To change generated content or structure, see `REFERENCE.md`. + +## Where things live + +- `docs/` — all content (hand-authored markdown + generated reference output). +- `docs-site/sidebars.ts` — the sidebar tree. **This is your main lever.** +- `docs-site/docusaurus.config.ts` — site config, **navbar/footer links**. These are + hardcoded `to:` paths; if you move a page they point to, update them here too. +- `docs-site/plugins/typedoc-custom/router.config.ts` — the reference IA (see `REFERENCE.md`). + +## Verify before you're done + +```bash +npm run docs:lint # frontmatter valid (title + description on every page) +npm run docs:build # production build — REQUIRED; broken links/anchors throw +``` + +`docs:build` is non-negotiable: the dev server tolerates broken links, the build (and +the release build) does not. If you touched reference _structure_, also run +`npm run derive` first — see `REFERENCE.md`. + +## Common tasks + +### Create a standalone page + +Create `docs/
/.md` with required frontmatter (both fields, or lint/build +fails): + +```markdown +--- +title: Your Page Title +description: One-sentence summary — shows in search results and link previews. +--- +``` + +Register it in `docs-site/sidebars.ts` by doc id (path under `docs/`, no extension), or +the object form for a custom sidebar label: + +```ts +items: [ + 'getting-started/quick-start', + 'getting-started/your-new-page', // by id + { type: 'doc', id: 'getting-started/your-new-page', label: 'Short label' }, +] +``` + +### Move content into a standalone page + +1. Create the new page (above) and cut the content over. +2. **Fix every inbound link** — relative markdown links, navbar/footer `to:` paths in + `docusaurus.config.ts`, cross-references in other pages. Broken links fail the build. +3. Add the new page to `sidebars.ts`. + +### Reorder or relabel sidebar items + +Edit `docs-site/sidebars.ts`. Order within a category's `items` array **is** the sidebar +order; labels come from `label`; categories take `collapsed` / `collapsible`. Items under +the **Reference** category are auto-generated — their order/labels are set in `REFERENCE.md`. + +### Group hand-authored pages with auto-generated reference + +A category's `items` can mix manually listed docs with the autogenerated block. Two ways: + +- **Sidebar grouping** — put a hand-authored page and a generated reference page in the + same category. ⚠️ The generated page is _already_ in the `{ type: 'autogenerated' }` + block, so listing it again makes it appear twice; drop the duplicate via the + `sidebarItemsGenerator` hook in `docusaurus.config.ts` (worked example in `REFERENCE.md`). +- **Page-level prose injection** — fold hand-authored prose _into_ a generated hub/flow + page via a `GUIDE.md` slot, so narrative and generated API tables read as one page + (mechanism in `REFERENCE.md`). + +If you only need the pages _near_ the reference (not merged), sidebar grouping is simpler +— or just reorder the top-level categories so e.g. **Theming** sits next to **Reference**. + +### Order content within a generated reference page + +Pages like `reference/theme-variables` are generated; on-page order comes from TypeDoc +config and `@group` tags in source, not from editing the page. See `REFERENCE.md`. + +--- + +Read `REFERENCE.md` before any task touching `docs/reference/**`, `router.config.ts`, or +`GUIDE.md` files. diff --git a/.claude/skills/docs-check/SKILL.md b/.claude/skills/docs-check/SKILL.md new file mode 100644 index 000000000..33994e6c2 --- /dev/null +++ b/.claude/skills/docs-check/SKILL.md @@ -0,0 +1,93 @@ +--- +name: docs-check +description: >- + Verify the docs site is publish-ready: frontmatter lint + production build + (catches broken links/anchors the dev server tolerates). Use before finishing + docs work or opening a docs PR, or on "check/verify the docs". +--- + +# Check the docs before you're done + +Run from the repo root, in order. Stop at the first failure and report its output. + +```bash +test -d docs-site/node_modules || npm run docs:install +npm run derive # 1. regenerate reference so checks run against what publishes +npm run docs:lint # 2. every docs/**/*.md needs title + description frontmatter +npm run docs:build # 3. the real gate — broken links/anchors throw +``` + +- **`derive`** rebuilds the generated reference. If TSDoc or reference config changed + since the last regen, the build would otherwise pass against stale content. After it + runs, review `git diff docs/reference/` — unexpected churn is itself a finding. + (`docs-regen` has the fast iterate-only path; for a publish check, `derive` is right.) +- **`docs:build`** is configured to throw on any broken link or anchor + (`onBrokenLinks` / `onBrokenAnchors` / `onBrokenMarkdownLinks` are all `'throw'`), so + it catches what the dev server tolerates. The release build fails the same way. + +## When a build check fails + +- **Broken link/anchor** — the error names the source page and bad target. Fix the + relative markdown link, or the navbar/footer `to:` path in `docs-site/docusaurus.config.ts`. +- **Missing frontmatter** — add `title` and `description` to the named file. +- **Failure under `docs/reference/**`** — don't hand-edit generated files; see +`docs-regen`and`docs-change-ia`. + +## Verifying a Flow component's reference page + +When a task touches a Flow component's generated page, check these by reading the source +(`*StateMachine.ts`, `*Components.tsx`, TSDoc on the flow function) — the build won't +catch them, but they're the difference between a good and a misleading reference. + +### 1. Does it have a GUIDE.md with a step-flow diagram? + +Every Flow needs a `GUIDE.md` beside its source with a Mermaid `flowchart` in an +`` or `` section. After regenerating, +the diagram must appear on the generated flow page. + +### 2. Is it a hub/loop or a guided flow? + +**Hub/loop** — a resting list that routes to sub-flows and back with no terminal state +(e.g. `PayrollFlow`, `EmployeeListFlow`): + +- `flowchart LR` with `<-->` bidirectional spokes between the hub node and each sub-flow. +- Start marker (`start@{ shape: sm-circ }`), **no done marker** — it's a loop. +- Thicken `<-->` edges: `linkStyle stroke-width:2.5px` at the end of the diagram. +- Drop edge labels when every spoke is the same interaction shape (hub→edit→hub); keep + them when spokes route to distinct destinations via distinct events. + +**Guided flow** — linear or branching steps with a real exit (e.g. `OnboardingExecutionFlow`, +`TerminationFlow`): + +- Start marker **and** done marker: `done@{ shape: fr-circ, label: " " }`. +- The exit event must be labeled on the edge to `done` — pull the exact event string + from `src/shared/constants.ts` componentEvents, not from memory. +- If the exit event bubbles via `onEvent` (the machine ignores it, it never transitions), + note that in a prose line in the GUIDE.md. Example: "The flow exits when + `payroll/saveAndExit` fires — it bubbles to the partner's `onEvent` handler." +- The TSDoc `@example` for a guided flow should show an `onEvent` handler that handles + the exit event and navigates away. If the example only shows `onDone`, it's incomplete. + +### 3. Is `@components` correct? + +`@components` must list what the **state machine actually renders** — trace the +`*Components.tsx` return statements, not umbrella names. Common mistakes: + +- **Umbrella trap** — listing a name that is itself a standalone `` the machine + never directly mounts (e.g. listing `Documents` when the machine mounts `DocumentManager`). +- **Wrapper collapse** — when the flow composes another separately-documented flow as a + step, that sub-flow is ONE `@components` entry (the sub-flow's node), not an expansion + of its steps. The sub-flow's own `@components` owns its children. +- **Cross-namespace nodes** — label them with their real namespace: + `{@link EmployeeOnboarding.OnboardingExecutionFlow}`, not just `OnboardingExecutionFlow`. + +The diagram and `@components` must agree: if the diagram collapses a sub-flow to one +node, the `@components` list must also show just that node. + +### 4. Are exit events in the TSDoc events table? + +Any event that exits the flow — whether via a machine terminal transition or by bubbling +through `onEvent` — must appear in the TSDoc `@example` and events `@remarks` table. +Check `*Components.tsx` for `onEvent` calls and `*StateMachine.ts` for terminal states. + +Script map and content model: [`docs-shared.md`](../../doc-guides/docs-shared.md). diff --git a/.claude/skills/docs-regen/SKILL.md b/.claude/skills/docs-regen/SKILL.md new file mode 100644 index 000000000..f5b866302 --- /dev/null +++ b/.claude/skills/docs-regen/SKILL.md @@ -0,0 +1,48 @@ +--- +name: docs-regen +description: >- + Regenerate the auto-generated reference docs (docs/reference/**) from TSDoc + + reference config. Use after editing TSDoc in src/** or the reference router + config, or on "regen the reference". Dev server doesn't hot-reload these. +--- + +# Regenerate the reference docs + +Everything under `docs/reference/**` is generated from TSDoc in `src/` by a TypeDoc +plugin — committed to the repo, never hand-edited. Regenerate when the source TSDoc or +reference config changes. Hand-authored markdown (`docs/**` except `docs/reference/**`) +doesn't need this; the dev server hot-reloads it. + +## When to regenerate + +After changing any of: + +- **TSDoc** in `src/` (descriptions, `@group` tags, params, examples). +- `docs-site/plugins/typedoc-custom/router.config.ts` (reference IA — domains, pages). +- `docs-site/typedoc.config.ts` or `docs-site/typedoc-utils.mjs` (grouping / ordering). + +## Steps + +Run from the repo root: + +```bash +test -d docs-site/node_modules || npm run docs:install # one-time prerequisite +npm run docs:api:generate # fast path: reference only +git diff docs/reference/ # confirm only intended changes +npm run docs:build # broken links/anchors throw +``` + +- `docs:api:generate` (TypeDoc only) is the quick loop while iterating. +- `npm run derive` is the full pipeline (SDK build + endpoint inventory + api report + + reference) — run it for the final pass before a PR. +- The generated `_category_.json` sidebar files come from the plugin too, so they may + legitimately change when you reorder reference IA. + +## Going deeper + +Reference _structure_ — domains, standalone pages, on-page ordering, folding prose into +generated pages via `GUIDE.md` — is documented in `docs-change-ia/REFERENCE.md`. Read it +before changing structure rather than just refreshing content. If you changed routing +_logic_ (not just config), run the router tests: `npm --prefix docs-site test`. + +Script map and content model: [`docs-shared.md`](../../doc-guides/docs-shared.md). diff --git a/.claude/skills/tsdoc/SKILL.md b/.claude/skills/tsdoc/SKILL.md index 92c12dfa0..a799a0f62 100644 --- a/.claude/skills/tsdoc/SKILL.md +++ b/.claude/skills/tsdoc/SKILL.md @@ -101,11 +101,11 @@ Always `@internal`, no prose needed: `createXxxSchema`, `XxxSchemaOptions`, `Xxx For more depth, Read the relevant guide before writing: -| Symbol type | When to load | -| ------------------------------------ | ------------------------------------------------------ | -| `.claude/tsdoc-guides/hooks.md` | Any hook, hook props, hook return types, form fields | -| `.claude/tsdoc-guides/components.md` | React components — events table format, @example rules | -| `.claude/tsdoc-guides/flows.md` | Flow components and FlowComponents props | +| Symbol type | When to load | +| ---------------------------------- | ------------------------------------------------------ | +| `.claude/doc-guides/hooks.md` | Any hook, hook props, hook return types, form fields | +| `.claude/doc-guides/components.md` | React components — events table format, @example rules | +| `.claude/doc-guides/flows.md` | Flow components and FlowComponents props | Load the guide when you'd otherwise be guessing: hook field patterns, events table format, what belongs in `@remarks` vs. what to skip. diff --git a/cspell.json b/cspell.json index fc2ea4390..013c3716a 100644 --- a/cspell.json +++ b/cspell.json @@ -26,6 +26,7 @@ "words": [ "affordances", "frontmatter", + "regen", "Annualization", "autogeneration", "Chakra",