forgebook 0.2.0 → 0.3.0

package/README.md

@@ -107,6 +107,28 @@ npx forgebook build    # static files in dist/, for any web server
 Badge's page shows its stories, each in its own frame, and an API table read from `BadgeProps`: `label` required,
 `tone` with its three values and its default, each with its TSDoc.
 
+### Which files
+
+`stories` (and `docs`, for [docs pages](#docs-pages)) lists globs from the configuration's folder. A glob that starts
+with `!` leaves out the files it matches from what the others list, wherever it stands in the list, as Vite's
+`import.meta.glob` and fast-glob read it:
+
+```ts
+stories: [
+  "src/**/*.stories.tsx",
+  "src/**/*-story.tsx",
+  // drafts and the components still being moved in: listed by neither glob above
+  "!src/**/drafts/**",
+  "!src/components/Legacy*/**"
+]
+```
+
+A `!` glob is written from the same folder and with the same syntax as the others; one that names a folder
+(`!src/legacy`) leaves out every file in it. A file two globs list is listed once, its title made from the first one
+(when its meta writes none). A list of `!` globs alone lists nothing, and the catalogue refuses it. Adding a file a `!`
+glob leaves out, while the catalogue runs, changes nothing on the page. A file Vite's `server.fs.deny` refuses stays out
+too, with a warning.
+
 ## What a catalogue gives you
 
 - **One frame per story**, so a story's styles and globals never leak into another, and its address opens it alone.
@@ -139,6 +161,8 @@ Badge's page shows its stories, each in its own frame, and an API table read fro
 - **Props in groups**: a component with many props lists them under the groups their TSDoc names (`@group Paging`),
   and a prop typed with a documented object (`texts?: FinderTexts`) unfolds to list its members
   ([below](#props-in-groups)).
+- **Required props first**: what every use must set comes first, in each group or in a section of its own, and a
+  reader turns the ordering off with a switch ([below](#required-props-first)).
 - **Shared values, checked**: the values set in the Props tab stay in the address (`args=`), so a link shares them.
   Since whoever writes a link chooses them, a story receives only the props it declares (its component's props, its
   `argTypes`, its own args) that the panel lets a person set, each with a value of that prop's type; anything else
@@ -214,7 +238,11 @@ The Touch switch (in View, `m` by default) lets a story be tried as on a phone,
   `navigator.maxTouchPoints` says 5;
 - the cursor is a round dot; Shift fixes a centre, and a press then puts a second finger mirrored around it, so a drag
   pinches and rotates;
-- a drag scrolls what it can, as the `touch-action` on the way allows, and flings on.
+- a drag scrolls what it can, as the `touch-action` on the way allows, and flings on;
+- a tap on a text field (an input, a textarea, a contenteditable) focuses it and puts the caret under the finger, a
+  drag or a long press there does not, and a handler that cancels the tap leaves it unfocused, as on a phone; the
+  keyboard then types and selects in it as usual (in a closed shadow root, or on a non-editable part of a
+  contenteditable, a press focuses at once and the caret is the browser's, the simulation not reaching them).
 
 A story reads the switch in its globals (`context.globals.touch`, `"mouse"` or `"touch"`) to draw only the version
 that fits the pointer, and follows the switch live; a story fixes it with `globals: { touch: "touch" }`.
@@ -225,9 +253,9 @@ its example's bar turns that off for it; on its own page, the Touch switch is th
 catalogue is open, and the address keeps the switch the other stories follow.
 
 **It is a simulation.** Events made by a page are not trusted, so the browser's own reactions do not follow them:
-its native scrolling (the drag's scrolling is an approximation, without the rubber band), focus and selection from a
-touch, and `touch-action` applied by the browser. In Safari and Firefox the stories get pointer events only (only
-Chromium lets a page build touch events). A virtual keyboard, the viewport shrinking under it, safe areas and real iOS
+its native scrolling (the drag's scrolling is an approximation, without the rubber band), selecting a word or the page's
+text with a finger, and `touch-action` applied by the browser. In Safari and Firefox the stories get pointer events only (only
+Chromium lets a page build touch events), and Firefox does not place the caret inside an email or number field. A virtual keyboard, the viewport shrinking under it, safe areas and real iOS
 Safari need a device. For real touch events and native scrolling, `forgebook dev --touch` opens the catalogue in a
 Chromium window with Chromium's own touch emulation (it needs `@forgebook/testing` and Playwright, as `check` does).
 `controls: { touch: false }` takes the switch away.
@@ -409,6 +437,34 @@ export type FinderProps = {
 - With `eslint-plugin-tsdoc`, declare the tag in your `tsdoc.json`:
   `{ "tagName": "@group", "syntaxKind": "block", "allowMultiple": false }`.
 
+## Required props first
+
+The API reference and the Props tab list a component's required props before the others, so a reader sees at once
+what every use must set. Where they go is `requiredFirst`:
+
+```ts
+// forgebook.config.ts: every component
+export default defineConfig({ requiredFirst: "section" });
+
+// a component's meta, for its page and its stories; or one story, for its own Props tab
+export default { component: Finder, parameters: { requiredFirst: false } } satisfies Meta<typeof Finder>;
+```
+
+- `"in-groups"`, the default: the required props first inside each group, and among the props that name no group and
+  the events; the others keep the order of the source. In the Props tab, first among each kind of control.
+- `"section"`: one "Required" section before every group, all the required props in it, each naming its group (an
+  event says "Event"; the Props tab, which lists no events, leaves them to the Events tab); then the groups with the
+  others. A component whose props name no group has nothing to section, so it reads as
+  `"in-groups"`.
+- `false`: the order of the source.
+- The narrowest wins: a story's over its meta's, a meta's over the configuration's. Write it plainly (the index reads
+  it); anything else is reported where it is written.
+- A reader's "Required first" switch, in the header of both tables, turns the ordering on or off for the whole
+  catalogue, kept in the browser: off, the order of the source; on, the developer's layout (`"in-groups"` where the
+  developer chose `false` everywhere). The switch never picks between the two layouts.
+- Agents get the props in the order of the source and the names of the required ones at the top of
+  `forgebook story --json` and `get_story` (`requiredProps`): the setting shapes the pages only.
+
 ## Docs pages
 
 Guides, foundations and recipes are Markdown files with a little front matter, not MDX: a page is read at build time, and
@@ -711,7 +767,9 @@ its name.
 To try it on a Storybook project, run `npx forgebook init --from storybook` in the folder that holds `.storybook`. It
 writes `forgebook.config.ts`: the story globs of `main` (the MDX pages left out), the preview as Forgebook's preview,
 and a switch for each toolbar global of the preview, applied by code as its decorators expect. `main` is loaded, so a
-computed `stories` list is read too; the preview is read from its source, so only `globalTypes` written as plain values
+computed `stories` list is read too, as the files it names (a list made with fast-glob and its `ignore`, for one,
+arrives with the ignored files already out); to keep the exclusion as globs, write it as `!` globs
+([above](#which-files)) in place of the files. The preview is read from its source, so only `globalTypes` written as plain values
 become switches. It reads React, Vue, Svelte, Preact, Solid, Web Components and plain HTML on Vite
 (`@storybook/react-vite`, `@storybook/vue3-vite`, `@storybook/svelte-vite`, `@storybook/sveltekit` (whose
 `sveltekit_experimental` parameters `@forgebook/sveltekit` reads as they are),
@@ -767,6 +825,35 @@ A monorepo that points its packages at their sources with an export condition (`
 `forgebook` command: its dev server reads the stories and previews it answers tools with on Node under the same
 conditions, those of other runtimes (`browser`) aside, unless a plugin names the server's own.
 
+## A lighter catalogue
+
+Two features cost the most and are on by default: the accessibility check, which ships axe (about 180 KB gzipped in a
+build), and the props read from the types, whose TypeScript programs are most of what the dev server holds on a first
+start. A catalogue that does not want them turns them off:
+
+```ts
+export default defineConfig({
+  framework: react(),
+  title: "Acme",
+  stories: ["src/**/*.stories.tsx"],
+  a11y: false,
+  componentDocs: false
+});
+```
+
+- `a11y: false` checks nothing: no Accessibility tab and no accessibility column on a tester's page, axe neither written
+  in a build nor offered to the frames (whose code that loads it is fetched only on a check), and the generated tests,
+  `forgebook check`, `check-page` and their tools leave axe out (their reports say `"a11y": "off"`). `tabs: { a11y: false }`
+  only hides the tab and keeps the rest. A preset that turns the check off keeps it off, whatever rules the catalogue writes.
+- `componentDocs: false` starts no TypeScript program: no API reference and no `props` fence on a page, no "Used in", and
+  the search finds names, stories and docs pages but no props. The Props tab still works: its controls come from the
+  story's args and `argTypes`, as Storybook's do without a docgen (a text, a number, a toggle from each arg's value, an
+  action as an event); a prop the story gives no arg is not listed. A shared link is then checked against those kinds:
+  where the story gives a text, a link may set any text, even for a prop whose type takes a few values only, so give
+  such a prop `argTypes` options (`{ control: "select", options: [...] }`) to keep a link to them. `forgebook story` answers `"componentDocs": "off"`
+  with no `docs`, and `forgebook changed` says it finds no story through the imports. `forgebook docs` and `forgebook new`
+  still read the types when run, since they are asked for that. `usedIn: true` with it is an error.
+
 ## Commands
 
 | Command | What it does |
@@ -931,6 +1018,26 @@ An embed (`?embed`) and an MCP client's inline preview are pages of the catalogu
 frames' origin in turn, as the catalogue does: a page or a host that frames them names the catalogue's origin only (in
 its `frame-src`, in the preview's `frameDomains`).
 
+### What the dev server gives a client
+
+`forgebook dev` listens on localhost unless you pass `--host`, and on both of its ports it answers with these limits:
+
+- **Another site's page gets nothing it can read.** A request a browser marks as another site's (`Sec-Fetch-Site`), or
+  with a foreign `Origin`, is refused for every module, file and API. A link or a frame from elsewhere can open the
+  catalogue's page, the frame page, an inline preview and a file of the public folder, whose content that site cannot
+  read. Vite checks `Host`
+  first (`server.allowedHosts`, plain HTTP only), which stops a site that reaches `127.0.0.1` through its own domain.
+- **Only the files your project names are listed or read.** A catalogue's `stories` and `docs`, and the groups a module
+  of yours imports (`?forgebook-files`), are the only groups the server reads, whatever an address names. A query that
+  names one file (`?forgebook-code`, `?forgebook-markdown`) follows Vite's `server.fs`, as `?raw` does.
+- **`server.fs.deny` wins over your globs.** A file it refuses stays out of the catalogue, its search and "Used in", with
+  a warning. A file your globs name outside `server.fs.allow` is listed and served, as Vite serves any file a module of
+  the project imports.
+
+A command, an agent or `curl` sends no browser headers: `forgebook mcp`, `forgebook stories` and the agent API
+(`/__forgebook/api/`) work as usual, and anyone who can reach the port can use them. With `--host` that means your whole
+network, so use it only on one you trust.
+
 ## Your look in the shell
 The catalogue's page can take your library's colours, fonts and corners. Nothing runs in the browser for it: the theme is
 written into the page at build, and the frames are left alone, since they belong to your stories.

package/dist/bin/forgebook/agentLoopCommands.mjs

@@ -60,6 +60,9 @@ const changedOf = async (config, options, log) => {
     const body = await askCatalogue(config, options.url, "changed", params, log);
     if (!isChangedStoriesDocument(body))
         throw new ScriptError("The catalogue's answer has an unexpected shape");
+    // said aloud: an empty list then means the imports were not read, not that the change touches nothing
+    for (const problem of body.problems)
+        log.warn(problem);
     return body;
 };
 /**

package/dist/bin/forgebook/agentText.d.ts

@@ -12,7 +12,7 @@ import type { TokenClash } from "../../src/vite/tokenClashes.ts";
  */
 export declare const storiesText: (document: StoriesDocument, style: OutputStyle) => string;
 /**
- * One story's facts: where it is, where it opens, its args and its component's props.
+ * One story's facts: where it is, where it opens, its args, its component's props and those every use must set.
  *
  * @param document - the story document.
  * @param style - colours, glyphs and width.
@@ -20,7 +20,7 @@ export declare const storiesText: (document: StoriesDocument, style: OutputStyle
 export declare const storyText: (document: StoryDocument, style: OutputStyle) => string;
 /**
  * A check's report as a table: one row per problem, its story, its view and its kind; a story that passes in a view gets
- * one row saying so.
+ * one row saying so. A catalogue that checks no accessibility says so first, so "passes" is not read as axe's.
  *
  * @param report - the check's report.
  * @param style - colours, glyphs and width.

package/dist/bin/forgebook/agentText.js

@@ -23,7 +23,7 @@ export const storiesText = (document, style) => table(document.components.flatMa
     `${component.title} › ${story.name}${story.isUnlisted ? " (unlisted)" : ""}`
 ])), { columns: [{ header: "Id" }, { header: "Story", tone: "muted" }] }, uncut(style));
 /**
- * One story's facts: where it is, where it opens, its args and its component's props.
+ * One story's facts: where it is, where it opens, its args, its component's props and those every use must set.
  *
  * @param document - the story document.
  * @param style - colours, glyphs and width.
@@ -37,7 +37,8 @@ export const storyText = (document, style) => {
         ["Frame", document.story.links.frame],
         ["Embed", document.story.links.embed],
         ["Args", JSON.stringify(document.args)],
-        ["Props", document.docs === undefined ? "none" : document.docs.props.map((prop) => prop.name).join(", ")]
+        ["Props", document.docs === undefined ? "none" : document.docs.props.map((prop) => prop.name).join(", ")],
+        ["Required", document.requiredProps.length === 0 ? "none" : document.requiredProps.join(", ")]
     ];
     if (document.story.description !== undefined)
         entries.push(["About", document.story.description]);
@@ -63,21 +64,22 @@ const judgementLines = (result) => {
 };
 /**
  * A check's report as a table: one row per problem, its story, its view and its kind; a story that passes in a view gets
- * one row saying so.
+ * one row saying so. A catalogue that checks no accessibility says so first, so "passes" is not read as axe's.
  *
  * @param report - the check's report.
  * @param style - colours, glyphs and width.
  */
-export const checkText = (report, style) => table(report.results.flatMap((result) => [
-    ...(result.problems.length === 0
-        ? [[result.storyId, result.view || "default", "passes"]]
-        : result.problems.map((problem) => [
-            result.storyId,
-            result.view || "default",
-            `${problem.kind}: ${problem.message}`
-        ])),
-    ...judgementLines(result)
-]), { columns: [{ header: "Story" }, { header: "View", tone: "muted" }, { header: "Result" }] }, uncut(style));
+export const checkText = (report, style) => (report.a11y === "off" ? "Accessibility is not checked: the catalogue sets a11y: false.\n" : "") +
+    table(report.results.flatMap((result) => [
+        ...(result.problems.length === 0
+            ? [[result.storyId, result.view || "default", "passes"]]
+            : result.problems.map((problem) => [
+                result.storyId,
+                result.view || "default",
+                `${problem.kind}: ${problem.message}`
+            ])),
+        ...judgementLines(result)
+    ]), { columns: [{ header: "Story" }, { header: "View", tone: "muted" }, { header: "Result" }] }, uncut(style));
 /**
  * The frames' errors as a table: their number, the story, what went wrong; nothing when there are none.
  *

package/dist/bin/forgebook/agents.md

@@ -10,6 +10,10 @@ in JSON with `--json`, and every answer about a story carries the links that ope
   reads it, never MDX or addons). Files with the same title are one component, as in Storybook: each story keeps its
   own file (`file` in `forgebook stories --json`), and the component lists them all (`files`).
 - Every named export of a story file is a story; leave helpers and data out with the meta's `excludeStories`.
+- The catalogue lists the files its `stories` globs name in `forgebook.config.ts`; a glob that starts with `!` leaves
+  files out (`"!src/**/drafts/**"`), whatever its place in the list. A new story file that `forgebook stories` does not
+  list is outside the globs, left out by a `!` one, or refused by Vite's `server.fs.deny` (the dev server warns): put it
+  where they list it, or change the globs on purpose.
 - Story ids are Storybook's (`inputs-readmore--open-by-default`, prefixed by the source's id); the commands also take
   the ids Forgebook gave before (`inputs-read-more--open-by-default`) and answer with the current one.
 - The meta is the default export; the stories are named exports, each with a one-line TSDoc saying what it shows (the
@@ -59,8 +63,9 @@ in JSON with `--json`, and every answer about a story carries the links that ope
   `({ props: args, template: "…" })`. The Code tab writes the story by the component's selector.
 - In a SvelteKit app (`framework: sveltekit()`), the types come from `@forgebook/sveltekit`, and a story sets the page its
   components read with `parameters.sveltekit`: `page: { url: "/blog/hello" }` (the route and params are read from
-  `src/routes`), `page.data` or the page's own `load` (run in the frame, its fetch answered by `parameters.msw`), and
-  `forms.result` for what an enhanced form's action answers. Links and `goto` move the story's page and are listed among
+  `src/routes`), `page.data` or the page's own `load` (run before the story is drawn, its fetch answered by
+  `parameters.msw` in the frame and in the server tests, where a fetch of the page's origin that no handler answers
+  fails the story), and `forms.result` for what an enhanced form's action answers. Links and `goto` move the story's page and are listed among
   its events; in a play, `storyPage()` from `@forgebook/sveltekit/page` reads where it went and the calls it made. A
   component that imports `$app/env/private` or `$app/server` fails in its frame by design: give it what it reads instead.
 - `parameters.main: true` marks the one real, well-made use drawn at the top of the component's page.
@@ -68,7 +73,8 @@ in JSON with `--json`, and every answer about a story carries the links that ope
   meaningful state, not one per prop value.
 - Add a worst case: very long text, words without spaces, huge numbers (`forgebook new` writes one).
 - To try a component as on a phone, the catalogue's Touch switch (`touch=touch` in a view: `--view "touch=touch"`)
-  sends the story a finger's events and a phone's hover and pointer media. It is a simulation: native scrolling, the
+  sends the story a finger's events and a phone's hover and pointer media; a tap on a text field focuses it and puts the
+  caret there. It is a simulation: native scrolling, the
   virtual keyboard and real Safari still need a device, or `forgebook dev --touch` (Chromium's real touch).
   A story reads it as `context.globals.touch` (`"mouse"` or `"touch"`) or fixes it with
   `globals: { touch: "touch" }`. A story meant for a phone writes `parameters.touch: true` (or its meta does): the
@@ -102,8 +108,8 @@ in JSON with `--json`, and every answer about a story carries the links that ope
 - Texts a person reads come from the source's texts, not from the story: `args: { label: storyText("badge.new") }`
   (`@forgebook/story-format/texts`), or `useStoryText()` inside a `render`. A source gives each language's table, or a
   loader of it (`texts: { en: () => import("./locales/en.json") }`), which keeps the texts out of the catalogue's page.
-- Write `title`, `parameters.main`, `group`, `height`, `touch`, `logic` and `design.figma` as plain values: the catalogue reads them without running
-  the file.
+- Write `title`, `parameters.main`, `group`, `height`, `touch`, `logic`, `requiredFirst` and `design.figma` as plain
+  values: the catalogue reads them without running the file.
 - In a Next.js project (`framework: nextjs()`), stories take their types from `@forgebook/nextjs`. A story says where
   its component is with `parameters.nextjs.navigation` (`pathname`, `query`, `params`; `router` for the Pages Router),
   and what its server code reads with `nextjs.cookies`, `headers` and `draftMode`. A link or a router call moves the
@@ -117,6 +123,10 @@ in JSON with `--json`, and every answer about a story carries the links that ope
 - A component with many props names their groups in its TSDoc (`@group Paging`): `forgebook story` returns each
   prop's `group`, and a prop typed with a documented object (`texts?: FinderTexts`) its `members`, each with its type,
   default and TSDoc: read them to know every text a component takes before passing one.
+- `forgebook story --json` and `get_story` give `requiredProps` at the top, the names of the component's props every
+  use must set (events among them; a subcomponent's say it with their own `isRequired`); `docs.props` stays in the
+  order of the source, whatever the catalogue's `requiredFirst` shows a person.
+  Set every name in `requiredProps` when you use the component or write its story.
 
 ### Docs pages
 
@@ -154,7 +164,7 @@ leave it out.
 | `npx forgebook search onValueChange --json` | The whole catalogue by its text: which component has a prop, where the docs say something, with the address of the exact heading or prop |
 | `npx forgebook new src/Badge.tsx` | A component's first stories, from its typed props (`Badge.vue` or `badge.component.ts` writes `Badge.stories.ts`) |
 | `npx forgebook stories --component badge --json` | The stories and their ids; fails when a story file is broken |
-| `npx forgebook story <id> --json` | One story: its args, its component's props, the components whose stories use it, its design |
+| `npx forgebook story <id> --json` | One story: the props every use must set (`requiredProps`), its args, its component's props, the components whose stories use it, its design |
 | `npx forgebook pages --json` | The docs pages, with their ids and addresses; fails when a page names what is not there |
 | `npx forgebook page <id> --json` | One docs page: its Markdown, its headings, the address that opens it |
 | `npx forgebook check <id> --json` | The catalogue's checks on one story: accessibility, spills, overlays, a modal's focus, errors, a failed play |
@@ -174,6 +184,11 @@ leave it out.
 Never write a raw colour or size when a token exists: ask `tokens --nearest` first, and use a match only when it says
 `isClose` or `isExact`. A match that is not close means no token fits: say so, do not force one.
 
+A catalogue may turn off its accessibility check (`a11y: false`) or its component docs (`componentDocs: false`). Then a
+check's report says `"a11y": "off"` (it ran no axe: a pass says nothing of accessibility), and `story` says
+`"componentDocs": "off"` with no `docs` and no required props: read the component's source for its props, and the
+story's args for what it sets; `changed` finds no story through the imports, so check the stories you touched by name.
+
 A story's frame runs on its own origin (the dev server's second port), unless the catalogue keeps it on its own
 (`frames: "same-origin"`, `forgebook dev --frames same-origin`): open a story by the `page` or `frame` link an answer
 gives, never by building a frame's address yourself, and do not expect a story's code to reach the catalogue's page or

package/dist/bin/forgebook/mcpTools.js

@@ -186,7 +186,7 @@ export const catalogueTools = ({ ask, writeNew, check, shot, checkPage, servePre
     },
     {
         name: "get_story",
-        description: "One story in detail: its args as the catalogue renders it, its component's props (types, defaults, descriptions), the components whose stories use it (usedIn), the device it is shown in by default (device), its design in Figma when it has one (design: the link, the file key and the node id, and the address where a person sees it beside the story), its links in the view asked for, and what failed while reading it.",
+        description: "One story in detail: the names of the props every use must set (requiredProps, first), its args as the catalogue renders it, its component's props in the order of the source (types, defaults, descriptions), the components whose stories use it (usedIn), the device it is shown in by default (device), its design in Figma when it has one (design: the link, the file key and the node id, and the address where a person sees it beside the story), its links in the view asked for, and what failed while reading it.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/bin/forgebook/newStoriesFile.js

@@ -10,13 +10,18 @@ import { findUp } from "@ensiria/cli-kit/files";
 import { ScriptError } from "@ensiria/cli-kit/script";
 import { autoTitle, patternBase } from "../../src/vite/autoTitle.js";
 import { findConfigFile, loadConfigFile } from "../../src/vite/configFile.js";
+import { isNegated } from "../../src/vite/storyPatterns.js";
 import { VITE_PATHS } from "../../src/vite/vitePaths.js";
 import { frameworkDocsModule } from "../frameworkDocs.js";
 import { newStories } from "./newStories.js";
-/** The folder the title starts from: the catalogue's first stories pattern's, else `src` for a file under it. */
+/**
+ * The folder the title starts from: the catalogue's first stories pattern's (a `!` one lists nothing), else `src` for
+ * a file under it.
+ */
 const titleBase = async (packageDir, storiesFile) => {
     const config = findConfigFile(packageDir);
-    const [pattern] = config === undefined ? [] : (await loadConfigFile(config)).stories;
+    const patterns = config === undefined ? [] : (await loadConfigFile(config)).stories;
+    const pattern = patterns.find((each) => !isNegated(each));
     if (pattern !== undefined)
         return patternBase(pattern).replace(/^\.\//, "");
     return VITE_PATHS.relative(packageDir, storiesFile).split("/")[0] === "src" ? "src" : "";

package/dist/bin/forgebook-docs/collectDocs.js

@@ -174,7 +174,7 @@ const collectPages = (packageDir, exports, problems) => {
         return [];
     const file = VITE_PATHS.resolve(packageDir, source);
     const patterns = [...(readLinkedFile(file) ?? "").matchAll(PAGES_IMPORT)].flatMap((match) => match[1] ?? []);
-    const pages = patterns.flatMap((pattern) => indexedDocPages(VITE_PATHS.dirname(file), pattern, () => undefined));
+    const pages = patterns.flatMap((pattern) => indexedDocPages(VITE_PATHS.dirname(file), [pattern], () => undefined));
     for (const page of pages)
         for (const note of page.index.notes ?? [])
             problems.push(`${VITE_PATHS.relative(packageDir, page.file)}: ${note}`);

package/dist/src/argsProps.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The props a story's args stand for, for a catalogue that reads no component docs (`componentDocs: false`): the Props
+ * tab's controls then come from the story's own args and its `argTypes`, as Storybook's do without a docgen.
+ *
+ * @remarks
+ * An arg's kind is read from its value: a text, a number, a toggle, an event for an arg the frame records as an
+ * action. A list or a value the source names (`namedValues`) is listed for reading, unless its type is one the source
+ * names values for. Nothing is said of a prop the story gives no arg: without the types there is no way to know it.
+ * The story's `argTypes` are laid over these as over the types' props (`argTypes.ts`). A shared link's values are
+ * checked against these kinds (`addressArgs.ts`): without the types, a text arg takes any text, so a prop of a few
+ * values keeps a link to them only through its `argTypes` options. Pure.
+ *
+ * @module
+ */
+import type { ComponentDocs, PropDocs } from "./componentDocs.ts";
+import type { PanelArgs } from "./messages.ts";
+/**
+ * The props a story's args stand for, in the args' order, then its actions the args do not hold.
+ *
+ * @param args - the story's args, as its frame reported them.
+ * @param actions - the args the frame records as actions.
+ */
+export declare const propsOfArgs: (args: PanelArgs, actions: readonly string[]) => readonly PropDocs[];
+/**
+ * A component's docs made from a story's args: its name, and the props its args stand for; nothing else is known
+ * without its types.
+ *
+ * @param name - the component's name.
+ * @param args - the story's args, as its frame reported them.
+ * @param actions - the args the frame records as actions.
+ */
+export declare const docsOfArgs: (name: string, args: PanelArgs, actions: readonly string[]) => ComponentDocs;

package/dist/src/argsProps.js

@@ -0,0 +1,69 @@
+/**
+ * The props a story's args stand for, for a catalogue that reads no component docs (`componentDocs: false`): the Props
+ * tab's controls then come from the story's own args and its `argTypes`, as Storybook's do without a docgen.
+ *
+ * @remarks
+ * An arg's kind is read from its value: a text, a number, a toggle, an event for an arg the frame records as an
+ * action. A list or a value the source names (`namedValues`) is listed for reading, unless its type is one the source
+ * names values for. Nothing is said of a prop the story gives no arg: without the types there is no way to know it.
+ * The story's `argTypes` are laid over these as over the types' props (`argTypes.ts`). A shared link's values are
+ * checked against these kinds (`addressArgs.ts`): without the types, a text arg takes any text, so a prop of a few
+ * values keeps a link to them only through its `argTypes` options. Pure.
+ *
+ * @module
+ */
+/**
+ * The prop an arg stands for, its kind and type read from its value.
+ *
+ * @param name - the arg's name.
+ * @param value - its value, as the frame reported it.
+ * @param isAction - whether the frame records it as an action.
+ */
+const propOfArg = (name, value, isAction) => {
+    const prop = { name, description: "", isRequired: false };
+    if (isAction)
+        return { ...prop, kind: "event", type: "function" };
+    if (typeof value === "string")
+        return { ...prop, kind: "text", type: "string" };
+    if (typeof value === "number")
+        return { ...prop, kind: "number", type: "number" };
+    if (typeof value === "boolean")
+        return { ...prop, kind: "toggle", type: "boolean" };
+    if (value === null)
+        return { ...prop, kind: "other", type: "null" };
+    if (Array.isArray(value))
+        return { ...prop, kind: "other", type: "array" };
+    // a value the source names: its type, so the panel offers the source's values for it
+    return { ...prop, kind: "other", type: "of" in value ? value.of : "unknown" };
+};
+/**
+ * The props a story's args stand for, in the args' order, then its actions the args do not hold.
+ *
+ * @param args - the story's args, as its frame reported them.
+ * @param actions - the args the frame records as actions.
+ */
+export const propsOfArgs = (args, actions) => {
+    const recorded = new Set(actions);
+    const fromArgs = Object.entries(args).map(([name, value]) => propOfArg(name, value, recorded.has(name)));
+    const named = new Set(Object.keys(args));
+    const fromActions = actions
+        .filter((name) => !named.has(name))
+        .map((name) => ({ name, kind: "event", type: "function", description: "", isRequired: false }));
+    return [...fromArgs, ...fromActions];
+};
+/**
+ * A component's docs made from a story's args: its name, and the props its args stand for; nothing else is known
+ * without its types.
+ *
+ * @param name - the component's name.
+ * @param args - the story's args, as its frame reported them.
+ * @param actions - the args the frame records as actions.
+ */
+export const docsOfArgs = (name, args, actions) => ({
+    name,
+    description: "",
+    summary: "",
+    props: propsOfArgs(args, actions),
+    parts: [],
+    subcomponents: []
+});

package/dist/src/catalogue.d.ts

@@ -11,7 +11,7 @@
  *
  * @module
  */
-import type { StoryDeviceSetting } from "@forgebook/story-format/csf";
+import type { RequiredFirst, StoryDeviceSetting } from "@forgebook/story-format/csf";
 import { type AudienceId } from "./audiences.ts";
 import { type Backdrop, type CustomBackdrop } from "./backdrops.ts";
 import { type ControlKeys } from "./controlKeys.ts";
@@ -84,8 +84,11 @@ export type CatalogueLists = {
     readonly storyGroups?: readonly StoryGroupSetting[];
     /** The panel's tabs turned off, Forgebook's or a plugin's (`{ a11y: false }`). */
     readonly tabs?: Readonly<Partial<Record<PanelTabId, false>> & Record<string, false>>;
-    /** The accessibility rules. */
-    readonly a11y?: Partial<A11ySettings>;
+    /**
+     * The accessibility rules, or `false` to check nothing: no Accessibility tab or column, axe's script neither in a
+     * build nor offered to the frames, and the generated tests and `forgebook check` leave axe out.
+     */
+    readonly a11y?: false | Partial<A11ySettings>;
     /** The measuring grid's step, in CSS px. */
     readonly gridStep?: number;
     /** Texts of the shell replaced, by their name in `STRINGS` or `LATER_STRINGS` (a translation, another word). */
@@ -108,6 +111,13 @@ export type CatalogueLists = {
      * `false` builds nothing for it (no import graph is read) and leaves it out of the agents' answers.
      */
     readonly usedIn?: boolean;
+    /**
+     * Whether each component's docs are read from its types and TSDoc (its props, events, description, guidance and
+     * signature); `true` by default. `false` starts no TypeScript program: no API reference, the Props tab's controls
+     * come from the story's args and `argTypes`, and "Used in", which reads the import graph with the same programs, is
+     * off too.
+     */
+    readonly componentDocs?: boolean;
     /**
      * Who a component's page is read by before a person picks: `designer`, `coder` or `tester` reorder and filter the
      * page for them, and `everyone` (the default) draws all of it. The address's `audience` wins, so a link keeps its view;
@@ -143,6 +153,13 @@ export type CatalogueLists = {
      * groups named nowhere follow in the order they first appear. The props that name no group always come first.
      */
     readonly propGroups?: readonly string[];
+    /**
+     * Where every component's API reference and Props tab list the required props: first inside each group
+     * (`"in-groups"`, the default), all in one "Required" section before the groups (`"section"`), or in the order of
+     * the source (`false`). A meta's or a story's `parameters.requiredFirst` wins over it; a reader's "Required first"
+     * switch turns the ordering on or off over both.
+     */
+    readonly requiredFirst?: RequiredFirst;
 };
 /** The shell's own appearance: light, dark, the system's, or the colour scheme of the story shown. */
 export type Appearance = "light" | "dark" | "system" | "story";
@@ -173,8 +190,13 @@ export type CatalogueSettings = {
     readonly storyGroups: readonly StoryGroupSetting[];
     /** The panel's tabs shown, Forgebook's then the plugins', by id. */
     readonly tabs: readonly string[];
-    /** The accessibility rules. */
-    readonly a11y: A11ySettings;
+    /**
+     * The accessibility rules the Accessibility tab and column, the frames and the tests check; none when it checks
+     * nothing (`a11y: false`).
+     */
+    readonly a11y: A11ySettings | undefined;
+    /** Whether each component's docs are read from its types. */
+    readonly hasComponentDocs: boolean;
     /** The measuring grid's step, in CSS px. */
     readonly gridStep: number;
     /** The shell's texts replaced, by name. */
@@ -202,9 +224,30 @@ export type CatalogueSettings = {
     readonly device: DeviceDefault;
     /** The prop groups listed first, in their order; none by default. */
     readonly propGroups: readonly string[];
+    /** Where the required props are listed when a component or a story does not say; `"in-groups"` by default. */
+    readonly requiredFirst: RequiredFirst;
 };
 /** WCAG 2.2 at levels A and AA: the rules every story passes by default. */
 export declare const DEFAULT_A11Y_TAGS: readonly string[];
+/**
+ * Whether a catalogue checks accessibility: unless its lists say `a11y: false`.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+export declare const checksA11y: (lists: CatalogueLists) => boolean;
+/**
+ * Whether a catalogue reads its components' docs from their types: unless its lists say `componentDocs: false`.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+export declare const readsComponentDocs: (lists: CatalogueLists) => boolean;
+/**
+ * Whether a catalogue offers "Used in": unless its lists turn it off, or turn off the component docs, whose
+ * TypeScript programs read the import graph it is joined from.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+export declare const offersUsedIn: (lists: CatalogueLists) => boolean;
 /**
  * A catalogue's settings, its lists' defaults filled in.
  *