forgebook 0.2.0 → 0.3.1

package/dist/src/shell/usePanelDocs.d.ts

@@ -0,0 +1,11 @@
+import type { PanelArgs } from "../messages.ts";
+import { type DocsState } from "./useComponentDocs.ts";
+/**
+ * The panel's docs of the shown story.
+ *
+ * @param loadDocs - loads the component's docs; `undefined` when the source has none for the file.
+ * @param name - the component's name.
+ * @param args - the story's args, as its frame reported them; none before it did.
+ * @param actions - the args the frame records as actions.
+ */
+export declare const usePanelDocs: (loadDocs: (() => Promise<unknown>) | undefined, name: string, args: PanelArgs | undefined, actions: readonly string[]) => DocsState;

package/dist/src/shell/usePanelDocs.js

@@ -0,0 +1,29 @@
+/**
+ * The docs the story's panel reads: the component's, read from its types, or for a catalogue that reads none
+ * (`componentDocs: false`) the story's args as its props (`argsProps.ts`), once its frame reported them.
+ *
+ * @module
+ */
+import { useMemo } from "react";
+import { docsOfArgs } from "../argsProps.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { useComponentDocs } from "./useComponentDocs.js";
+/** The state before a story's frame reported its args: one value, so what reads it is not renewed each render. */
+const DOCS_LOADING = { status: "loading" };
+/**
+ * The panel's docs of the shown story.
+ *
+ * @param loadDocs - loads the component's docs; `undefined` when the source has none for the file.
+ * @param name - the component's name.
+ * @param args - the story's args, as its frame reported them; none before it did.
+ * @param actions - the args the frame records as actions.
+ */
+export const usePanelDocs = (loadDocs, name, args, actions) => {
+    const { hasComponentDocs } = useCatalogue();
+    const typeDocs = useComponentDocs(loadDocs);
+    return useMemo(() => {
+        if (hasComponentDocs)
+            return typeDocs;
+        return args === undefined ? DOCS_LOADING : { status: "ready", value: docsOfArgs(name, args, actions) };
+    }, [hasComponentDocs, typeDocs, name, args, actions]);
+};

package/dist/src/shell/useRequiredFirst.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The reader's "Required first" switch, kept in this browser for the whole catalogue, and the layout of the required
+ * props it leaves for a component or a story (`requiredFirstLayout`).
+ *
+ * @remarks
+ * Stored as `useStored` stores a reader's preference (under the catalogue's id), but shared live by every table that
+ * shows it: a docs page may hold several API references, and turning the switch in one turns it in all. Storage may
+ * be refused (a private window): the switch then holds for the page only, and nothing fails.
+ *
+ * @module
+ */
+import type { RequiredFirst } from "@forgebook/story-format/csf";
+/** Where the required props go, and the reader's switch over it. */
+export type RequiredFirstState = {
+    /** The layout to draw. */
+    readonly layout: RequiredFirst;
+    /** Whether the switch shows on: the layout puts the required props first. */
+    readonly isOn: boolean;
+    /** Turns the switch, for every component, and keeps it in this browser. */
+    readonly setIsOn: (isOn: boolean) => void;
+};
+/**
+ * Where a component's or a story's required props go for this reader.
+ *
+ * @param own - the story's or the component's own setting (`parameters.requiredFirst`); none for the catalogue's.
+ */
+export declare const useRequiredFirst: (own: RequiredFirst | undefined) => RequiredFirstState;

package/dist/src/shell/useRequiredFirst.js

@@ -0,0 +1,67 @@
+import { useSyncExternalStore } from "react";
+import { requiredFirstLayout } from "../propGroups.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { readStored, writeStored } from "./useStored.js";
+/**
+ * The reader's switch from the text it is stored as: none for anything else, a text another script wrote included.
+ *
+ * @param stored - the stored text; none when nothing is stored.
+ */
+const readerSwitch = (stored) => {
+    if (stored === "on")
+        return true;
+    return stored === "off" ? false : undefined;
+};
+/** The tables showing the switch, told when it turns. */
+const listeners = new Set();
+/**
+ * The switch as turned in this page, by key: it wins over storage, which a browser may refuse to write (a private
+ * window, a full quota) while still reading an older value.
+ */
+const turnedInPage = new Map();
+/**
+ * Listens to the switch: turned in this page, or in another of the catalogue's tabs.
+ *
+ * @param listener - called when it may have turned.
+ * @returns what stops listening.
+ */
+const subscribe = (listener) => {
+    // another tab's choice is the newer one: this page's own gives way to it
+    const onStorage = (event) => {
+        if (event.key === null)
+            turnedInPage.clear();
+        else
+            turnedInPage.delete(event.key);
+        listener();
+    };
+    listeners.add(listener);
+    window.addEventListener("storage", onStorage);
+    return () => {
+        listeners.delete(listener);
+        window.removeEventListener("storage", onStorage);
+    };
+};
+/** No stored switch where there is no page to store it in. */
+const NOT_STORED = () => null;
+/**
+ * Where a component's or a story's required props go for this reader.
+ *
+ * @param own - the story's or the component's own setting (`parameters.requiredFirst`); none for the catalogue's.
+ */
+export const useRequiredFirst = (own) => {
+    const catalogue = useCatalogue();
+    const key = `${catalogue.id}:required-first`;
+    const stored = useSyncExternalStore(subscribe, () => turnedInPage.get(key) ?? readStored(key), NOT_STORED);
+    const layout = requiredFirstLayout(own, catalogue.requiredFirst, readerSwitch(stored));
+    return {
+        layout,
+        isOn: layout !== false,
+        setIsOn: (isOn) => {
+            const text = isOn ? "on" : "off";
+            turnedInPage.set(key, text);
+            writeStored(key, text);
+            for (const listener of listeners)
+                listener();
+        }
+    };
+};

package/dist/src/storyCheck.d.ts

@@ -95,6 +95,8 @@ export type StoryCheckReport = {
     readonly schema: 1;
     /** One result per story and view. */
     readonly results: readonly StoryCheckResult[];
+    /** `"off"` when the catalogue checks no accessibility (`a11y: false`): no result ran axe. Absent when it does. */
+    readonly a11y?: "off";
 };
 /**
  * Whether what the testing package answered is a check's report.

package/dist/src/storyCheck.js

@@ -38,7 +38,8 @@ export const isStoryCheckReport = (value) => typeof value === "object" &&
     value.schema === 1 &&
     "results" in value &&
     Array.isArray(value.results) &&
-    value.results.every(isResult);
+    value.results.every(isResult) &&
+    (!("a11y" in value) || value.a11y === undefined || value.a11y === "off");
 /**
  * Whether what the testing package answered is a comparison's report.
  *

package/dist/src/storyGlobals.js

@@ -76,7 +76,8 @@ export const fixedViewOf = (globals, parameters, catalogue) => {
  */
 export const withFixed = (view, fixed) => ({
     ...view,
-    switches: { ...view.switches, ...fixed.switches },
+    // the same object when the story fixes no switch: a new one would tell the frames of a view that did not change
+    switches: Object.keys(fixed.switches).length === 0 ? view.switches : { ...view.switches, ...fixed.switches },
     ...(fixed.backdrop === undefined ? {} : { backdrop: fixed.backdrop }),
     ...(fixed.width === undefined || view.width === undefined ? {} : { width: fixed.width })
 });

package/dist/src/storyTree.d.ts

@@ -13,7 +13,7 @@
  *
  * @module
  */
-import type { StoryDeviceSetting, StoryGroup } from "@forgebook/story-format/csf";
+import type { RequiredFirst, StoryDeviceSetting, StoryGroup } from "@forgebook/story-format/csf";
 import type { FigmaLink, StoryBackground, StoryControlsSetting, StorySource } from "@forgebook/story-format/source";
 import { type TreePage } from "./pageTree.ts";
 /** One story in the tree. */
@@ -44,6 +44,11 @@ export type TreeStory = {
     readonly device: StoryDeviceSetting | undefined;
     /** Its design (`parameters.design.figma`): its own, else the meta's; none by default, nor when its own was refused. */
     readonly design: FigmaLink | undefined;
+    /**
+     * Where its Props tab lists the required props (`parameters.requiredFirst`): its own, else its file's meta's; none
+     * when neither sets one, for the catalogue's.
+     */
+    readonly requiredFirst: RequiredFirst | undefined;
     /** Its tags, the meta's and its own (`!dev` keeps it out of the lists, `!test` out of the generated tests). */
     readonly tags: readonly string[];
     /** Whether a `play` function acts on it. */
@@ -87,6 +92,11 @@ export type TreeComponent = {
     readonly design: FigmaLink | undefined;
     /** The prop groups its meta lists first (`parameters.propGroups`), in their order; empty when none. */
     readonly propGroups: readonly string[];
+    /**
+     * Where its page lists the required props (its first file's meta's `parameters.requiredFirst`); none when it sets
+     * none, for the catalogue's.
+     */
+    readonly requiredFirst: RequiredFirst | undefined;
 };
 /** A group's entry for a component that lives elsewhere and is listed here too (the meta's `alsoIn`). */
 export type TreeAlias = {

package/dist/src/storyTree.js

@@ -176,6 +176,7 @@ const treeStory = (id, file, entry, story, design) => ({
         ? undefined
         : { ...entry.device, ...story.device },
     design,
+    requiredFirst: story.requiredFirst ?? entry.requiredFirst,
     tags: story.tags ?? [],
     hasPlay: story.hasPlay === true
 });
@@ -247,7 +248,8 @@ const sourceFamilies = (source, problems) => {
             keywords: metaList(component, "keywords"),
             design: componentDesign(component),
             // its first file's, as its docs are
-            propGroups: component.files[0]?.entry.propGroups ?? []
+            propGroups: component.files[0]?.entry.propGroups ?? [],
+            requiredFirst: component.files[0]?.entry.requiredFirst
         });
     }
     placeAliases(source, placed, families, problems);

package/dist/src/viewState.d.ts

@@ -162,6 +162,13 @@ export declare const frameAddress: (frameUrl: string, id: string, view: ViewStat
  * @param view - the view.
  */
 export declare const liveView: (view: ViewState) => LiveView;
+/**
+ * Whether two live views show the same: their backdrop, text size and each switch's value, whatever the objects.
+ *
+ * @param left - a live view.
+ * @param right - the other.
+ */
+export declare const isSameLiveView: (left: LiveView, right: LiveView) => boolean;
 /**
  * The scheme a view draws in: its colour scheme switch's, light when the catalogue has none.
  *

package/dist/src/viewState.js

@@ -255,6 +255,19 @@ export const liveView = (view) => ({
     backdrop: view.backdrop,
     text: view.text
 });
+/**
+ * Whether two live views show the same: their backdrop, text size and each switch's value, whatever the objects.
+ *
+ * @param left - a live view.
+ * @param right - the other.
+ */
+export const isSameLiveView = (left, right) => {
+    const leftIds = Object.keys(left.switches);
+    return (left.backdrop === right.backdrop &&
+        left.text === right.text &&
+        leftIds.length === Object.keys(right.switches).length &&
+        leftIds.every((id) => left.switches[id] === right.switches[id]));
+};
 /**
  * The scheme a view draws in: its colour scheme switch's, light when the catalogue has none.
  *

package/dist/src/vite/agent.types.d.ts

@@ -145,6 +145,13 @@ export type StoriesDocument = {
 export type StoryDocument = {
     /** The shape's version. */
     readonly schema: AgentSchema;
+    /**
+     * The names of the component's required props (`isRequired`), events among them, in the order of the source: what
+     * every use must set. Its subcomponents' are not listed: their own `isRequired` says it. First in the answer, so a client that cuts a long one keeps it; `docs` keeps the source's
+     * order, whatever the catalogue's `requiredFirst` says, since that setting shapes the pages only. Empty when there
+     * are no docs.
+     */
+    readonly requiredProps: readonly string[];
     /** The story, with its links in the view asked for. */
     readonly story: AgentStory;
     /** Its component's id and title, and its "Used in" when the catalogue offers it. */
@@ -160,6 +167,11 @@ export type StoryDocument = {
     readonly args: Readonly<Record<string, unknown>>;
     /** What went wrong while reading it: its module failing to load, its docs failing to be read. */
     readonly problems: readonly string[];
+    /**
+     * `"off"` when the catalogue reads no component docs (`componentDocs: false`): `docs` is then none and
+     * `requiredProps` empty whatever the component declares, and there is no "Used in". Absent when it reads them.
+     */
+    readonly componentDocs?: "off";
 };
 /** Where a docs page opens, in the view the answer describes. */
 export type PageLinks = {

package/dist/src/vite/agentApi.js

@@ -186,6 +186,7 @@ export const storyDocument = (location, parts, pages, view, usage) => {
         problems.push(problem);
     return {
         schema: 1,
+        requiredProps: (docs?.props ?? []).filter((prop) => prop.isRequired).map((prop) => prop.name),
         story,
         component: {
             id: component.id,
@@ -250,7 +251,11 @@ export const isStoriesDocument = (value) => isRecord(value) &&
  *
  * @param value - the answer's body.
  */
-export const isStoryDocument = (value) => isRecord(value) && value["schema"] === 1 && isRecord(value["story"]) && Array.isArray(value["problems"]);
+export const isStoryDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    Array.isArray(value["requiredProps"]) &&
+    isRecord(value["story"]) &&
+    Array.isArray(value["problems"]);
 /**
  * Whether a value is the tokens document, as a client receives it over HTTP.
  *

package/dist/src/vite/agentRoutes.js

@@ -17,6 +17,7 @@
  */
 import { realpath } from "node:fs/promises";
 import { createIdResolver } from "vite";
+import { offersUsedIn, readsComponentDocs } from "../catalogue.js";
 import { mergedPreviews, NO_PREVIEW, readPreview } from "../frame/storyModule.js";
 import { sourceFiles } from "../sourceFiles.js";
 import { findComponentByTitle, findStory, storyTree } from "../storyTree.js";
@@ -144,7 +145,7 @@ const errorsAnswer = (context, live) => {
  */
 export const storiesAnswer = async (context) => {
     const { config, params, tree, pages, view, loaded } = context;
-    const usage = config.lists.usedIn !== false && params.get("usedIn") === "true"
+    const usage = offersUsedIn(config.lists) && params.get("usedIn") === "true"
         ? await usageBySource(loaded.sources)
         : undefined;
     return { status: 200, body: storiesDocument(config.title, tree, pages, view, usage) };
@@ -174,7 +175,15 @@ const changedAnswer = async ({ config, loaded, tree, params, pages, view }) => {
             ? []
             : [{ id: found.id, title: story.title, links: storyLinks(pages, found.id, view) }];
     }));
-    const body = { schema: 1, since, files, stories, problems: [] };
+    // without the import graph no story is found, which must not read as a change that touches none
+    const problems = offersUsedIn(config.lists)
+        ? []
+        : [
+            readsComponentDocs(config.lists)
+                ? "No story is found through the imports: the catalogue turns Used in off (usedIn: false), whose import graph this reads"
+                : "No story is found through the imports: the catalogue reads no component docs (componentDocs: false), whose programs read the import graph"
+        ];
+    const body = { schema: 1, since, files, stories, problems };
     return { status: 200, body };
 };
 /**
@@ -197,10 +206,15 @@ export const storyAnswer = async (context) => {
         docs: await settled(files.docs[file]),
         preview: loaded.preview
     };
-    const index = config.lists.usedIn === false ? undefined : await sourceUsage(source);
+    const index = offersUsedIn(config.lists) ? await sourceUsage(source) : undefined;
     // a usage that cannot be read leaves "Used in" out, never the story
     const usage = index === undefined || typeof index === "string" ? undefined : { tree, index };
-    return { status: 200, body: storyDocument(location, parts, pages, view, usage) };
+    const document = storyDocument(location, parts, pages, view, usage);
+    // an agent must tell docs turned off from a story file that names no component
+    const body = readsComponentDocs(config.lists)
+        ? document
+        : { ...document, componentDocs: "off" };
+    return { status: 200, body };
 };
 /**
  * Answers one of the API's paths.

package/dist/src/vite/builtTexts.d.ts

@@ -33,8 +33,8 @@ export type FileTexts = readonly [docs: unknown, code: KeptCode, page: Component
 export declare const textsModuleCode: (texts: readonly FileTexts[], emit: EmitAsset) => string;
 /** What the plugin gives a build's texts: the docs as the panel reads them, and what reading a page needs. */
 export type TextSources = Pick<TextModuleContext, "watch" | "resolveImport" | "componentFiles"> & {
-    /** A story file's component docs as the panel reads them, or `{ error }`. */
-    readonly docsOf: (storyFile: string) => Promise<unknown>;
+    /** A story file's component docs as the panel reads them, or `{ error }`; none when the catalogue reads none. */
+    readonly docsOf: ((storyFile: string) => Promise<unknown>) | undefined;
 };
 /** The module a build's texts are answered as. */
 type TextsModule = {

package/dist/src/vite/builtTexts.js

@@ -63,7 +63,7 @@ const textWriter = (emit) => {
  * @param read - reads a file's texts.
  * @returns each file's texts, in the files' order.
  */
-const readTexts = (files, read) => Promise.all(files.map(({ file }) => Promise.all([read.docsOf(file), read.codeOf(file), read.pageOf(file)])));
+const readTexts = (files, read) => Promise.all(files.map(({ file }) => Promise.all([read.docsOf?.(file), read.codeOf(file), read.pageOf(file)])));
 /**
  * The code of a group's texts module: the functions its loaders call, then, as its default, each file's loaders of its
  * docs, code and page, in the order of the group's rows.
@@ -74,7 +74,8 @@ const readTexts = (files, read) => Promise.all(files.map(({ file }) => Promise.a
 export const textsModuleCode = (texts, emit) => {
     // written in the files' order once all are read, so the names in the module do not depend on which read ended first
     const writer = textWriter(emit);
-    const rows = texts.map((each) => `[${each.map((text) => writer.loaderOf(text)).join(", ")}]`);
+    // a text not read (the docs of a catalogue that reads none) has no loader, and its place stays in the row
+    const rows = texts.map((each) => `[${each.map((text) => (text === undefined ? "null" : writer.loaderOf(text))).join(", ")}]`);
     return [packedLoaderMaker(PACKED), ...writer.written(), `export default [${rows.join(",\n")}];`].join("\n");
 };
 /**
@@ -99,8 +100,8 @@ const textReaders = async (sources) => {
  * @param group - the group (`storyFilesGroupText`).
  */
 const groupKey = (group) => {
-    const { root, pattern } = storyFilesGroupOf(group);
-    return storyFilesGroupText(VITE_PATHS.normalize(root), pattern);
+    const { root, patterns } = storyFilesGroupOf(group);
+    return storyFilesGroupText(VITE_PATHS.normalize(root), patterns);
 };
 /**
  * A build's texts, by group.
@@ -118,8 +119,8 @@ export const groupTexts = () => {
         const reading = started.get(key);
         started.delete(key);
         if (reading === undefined) {
-            const { root, pattern } = storyFilesGroupOf(group);
-            return textsModuleCode(await read(indexedStoryFiles(root, pattern, sources.watch), sources), emit);
+            const { root, patterns } = storyFilesGroupOf(group);
+            return textsModuleCode(await read(indexedStoryFiles(root, patterns, sources.watch), sources), emit);
         }
         const texts = await reading.texts;
         for (const file of reading.watched)

package/dist/src/vite/configFile.d.ts

@@ -109,8 +109,9 @@ export declare const findConfigFile: (dir: string) => string | undefined;
 /**
  * The lists of the presets and the catalogue, in that order, merged: a single value (a width range, the grid's step)
  * the last that gives one; the backgrounds, the story groups and the texts entry by entry, a later one replacing an
- * earlier one with the same id or name; the tabs, the controls and the rules turned off by any; the toolbar and the
- * prop groups' order the last that names one; the device field by field.
+ * earlier one with the same id or name; the tabs, the controls and the rules turned off by any, and the accessibility
+ * check too (`a11y: false`); the toolbar, the prop groups' order, where the required props go and whether the
+ * component docs are read the last that names one; the device field by field.
  *
  * @param all - the presets' lists, then the catalogue's.
  */

package/dist/src/vite/configFile.js

@@ -23,10 +23,12 @@ import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { AUDIENCE_IDS } from "../audiences.js";
 import { deviceSettingProblem } from "../deviceView.js";
+import { REQUIRED_FIRST_LAYOUTS } from "../propGroups.js";
 import { frameThemeCss, mergedThemes, shellThemeCss, shellThemeProblems, themeValueProblem } from "../shellTheme.js";
 import { switchesProblem } from "../switches.js";
 import { framesProblem, resolvedFrames } from "./framesConfig.js";
 import { pluginsProblem, withPluginSwitches } from "./pluginConfig.js";
+import { patternsProblem } from "./storyPatterns.js";
 import { tokenThemeOf } from "./themeFromTokens.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** The names a configuration file may have, in the order they are looked for. */
@@ -96,15 +98,18 @@ const singleValues = (lists) => ({
     ...(lists.gridStep === undefined ? {} : { gridStep: lists.gridStep }),
     ...(lists.toolbar === undefined ? {} : { toolbar: lists.toolbar }),
     ...(lists.usedIn === undefined ? {} : { usedIn: lists.usedIn }),
+    ...(lists.componentDocs === undefined ? {} : { componentDocs: lists.componentDocs }),
     ...(lists.audience === undefined ? {} : { audience: lists.audience }),
     ...(lists.appearance === undefined ? {} : { appearance: lists.appearance }),
-    ...(lists.propGroups === undefined ? {} : { propGroups: lists.propGroups })
+    ...(lists.propGroups === undefined ? {} : { propGroups: lists.propGroups }),
+    ...(lists.requiredFirst === undefined ? {} : { requiredFirst: lists.requiredFirst })
 });
 /**
  * The lists of the presets and the catalogue, in that order, merged: a single value (a width range, the grid's step)
  * the last that gives one; the backgrounds, the story groups and the texts entry by entry, a later one replacing an
- * earlier one with the same id or name; the tabs, the controls and the rules turned off by any; the toolbar and the
- * prop groups' order the last that names one; the device field by field.
+ * earlier one with the same id or name; the tabs, the controls and the rules turned off by any, and the accessibility
+ * check too (`a11y: false`); the toolbar, the prop groups' order, where the required props go and whether the
+ * component docs are read the last that names one; the device field by field.
  *
  * @param all - the presets' lists, then the catalogue's.
  */
@@ -126,7 +131,8 @@ export const mergedLists = (all) => {
         merged = { ...merged, ...singleValues(lists) };
     }
     const builtIn = all.findLast((lists) => lists.backgrounds?.builtIn !== undefined)?.backgrounds?.builtIn;
-    const tags = all.findLast((lists) => lists.a11y?.tags !== undefined)?.a11y?.tags;
+    const rules = all.flatMap((lists) => lists.a11y === undefined || lists.a11y === false ? [] : [lists.a11y]);
+    const tags = rules.findLast((each) => each.tags !== undefined)?.tags;
     return {
         ...merged,
         ...(device === undefined ? {} : { device }),
@@ -137,10 +143,13 @@ export const mergedLists = (all) => {
         storyGroups: mergedById(all.map((lists) => lists.storyGroups)),
         tabs,
         controls,
-        a11y: {
-            ...(tags === undefined ? {} : { tags }),
-            disabledRules: [...new Set(all.flatMap((lists) => lists.a11y?.disabledRules ?? []))]
-        },
+        // a check one list turns off stays off, as a tab does: a preset's library may have no use for it
+        a11y: all.some((lists) => lists.a11y === false)
+            ? false
+            : {
+                ...(tags === undefined ? {} : { tags }),
+                disabledRules: [...new Set(rules.flatMap((each) => each.disabledRules ?? []))]
+            },
         strings,
         keys,
         // a later list's view of the same name replaces an earlier one's, where it was
@@ -152,6 +161,18 @@ const isListed = (config, key) => {
     const list = Reflect.get(config, key);
     return Array.isArray(list) && list.length > 0;
 };
+/**
+ * Why a configuration's list of globs lists nothing by construction (only `!` patterns), or none.
+ *
+ * @param config - what the file exports by default.
+ * @param key - the list's key.
+ */
+const globsProblem = (config, key) => {
+    const list = Reflect.get(config, key);
+    return Array.isArray(list)
+        ? patternsProblem(list.filter((item) => typeof item === "string"))
+        : undefined;
+};
 /**
  * Why a loaded configuration cannot be used, or none.
  *
@@ -171,6 +192,11 @@ const configProblem = (config) => {
         return 'its home is neither a path (`home: "docs/home.md"`) nor false';
     if (!["stories", "sources", "docs"].some((key) => isListed(config, key)))
         return 'it names no stories (`stories: ["src/**/*.stories.tsx"]`) and no sources';
+    for (const key of ["stories", "docs"]) {
+        const problem = globsProblem(config, key);
+        if (problem !== undefined)
+            return `its ${key} list nothing: ${problem}`;
+    }
     return framesProblem("frames" in config ? config.frames : undefined);
 };
 /**
@@ -213,20 +239,44 @@ const deviceProblem = (device) => {
 };
 /**
  * The configuration's and the presets' lists, once checked where the shell would leave a mistake out: a device that
- * cannot be used.
+ * cannot be used, a place for the required props that is none, an accessibility setting that is neither rules nor
+ * `false`.
  *
  * @param all - the presets' lists, then the configuration's.
  * @param dir - the configuration's folder, for the message.
- * @throws when a device cannot be used.
+ * @throws when a device cannot be used, `requiredFirst` is none of its layouts, or `a11y` is neither rules nor
+ *   `false`.
  */
 const checkedLists = (all, dir) => {
     for (const lists of all) {
         const problem = lists.device === undefined ? undefined : deviceProblem(lists.device);
         if (problem !== undefined)
             throw new Error(`${resolve(dir, "forgebook.config")}: Forgebook's device: ${problem}`);
+        // a configuration is written by JavaScript too, which no type stops
+        if (lists.requiredFirst !== undefined && !REQUIRED_FIRST_LAYOUTS.includes(lists.requiredFirst))
+            throw new Error(`${resolve(dir, "forgebook.config")}: requiredFirst is ${typeof lists.requiredFirst === "string" ? `"${lists.requiredFirst}"` : String(lists.requiredFirst)}, none of "in-groups", "section" and false`);
+        const a11y = lists.a11y;
+        if (a11y !== undefined &&
+            a11y !== false &&
+            (typeof a11y !== "object" || a11y === null || Array.isArray(a11y)))
+            throw new Error(`${resolve(dir, "forgebook.config")}: a11y is ${String(a11y)}: write its rules ({ tags, disabledRules }), or false to check nothing`);
     }
     return all;
 };
+/**
+ * Why the merged lists ask for what cannot be, or none: an audience that is none of the ids (the page reads it as one,
+ * and a configuration is written by JavaScript too, which no type stops), or "Used in" turned on with the component
+ * docs off, whose TypeScript programs read the import graph it is joined from.
+ *
+ * @param lists - the presets' lists and the configuration's, merged.
+ */
+const mergedListsProblem = (lists) => {
+    if (lists.audience !== undefined && !AUDIENCE_IDS.includes(lists.audience))
+        return `the audience "${lists.audience}" is none of ${AUDIENCE_IDS.join(", ")}`;
+    if (lists.usedIn === true && lists.componentDocs === false)
+        return "usedIn is true with componentDocs false: Used in reads the import graph with the programs componentDocs turns off";
+    return undefined;
+};
 /** What a catalogue shows: its own stories and docs pages, and the sources; none where it names none. */
 const shownFiles = (config) => ({
     stories: config.stories ?? [],
@@ -301,10 +351,9 @@ export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
     const tokenThemed = tokenThemeOf(fromTokens, tokens, dir);
     const theme = mergedThemes([tokenThemed.theme, ...declaredThemes]);
     const lists = mergedLists(checkedLists([...presets, config], dir));
-    // the page reads it as one of the ids, and a configuration is written by JavaScript too, which no type stops
-    if (lists.audience !== undefined && !AUDIENCE_IDS.includes(lists.audience)) {
-        throw new Error(`${resolve(dir, "forgebook.config")}: the audience "${lists.audience}" is none of ${AUDIENCE_IDS.join(", ")}`);
-    }
+    const listsProblem = mergedListsProblem(lists);
+    if (listsProblem !== undefined)
+        throw new Error(`${resolve(dir, "forgebook.config")}: ${listsProblem}`);
     const themeProblem = themeValueProblem(theme);
     if (themeProblem !== undefined)
         throw new Error(`${resolve(dir, "forgebook.config")}: ${themeProblem}`);

package/dist/src/vite/docPagesModule.d.ts

@@ -1,6 +1,7 @@
 import type { DocPageIndex } from "@forgebook/story-format/source";
 import type { ForgebookPlugin } from "../plugin.ts";
-/** A page a pattern matches, with its key and its index. */
+import { type IsFileKept } from "./storyFilesModule.ts";
+/** A page a group lists, with its key and its index. */
 export type IndexedDocPage = {
     /** Its path relative to the declaring module (`./docs/theming.md`). */
     readonly key: string;
@@ -10,24 +11,26 @@ export type IndexedDocPage = {
     readonly index: DocPageIndex;
 };
 /**
- * Every page a pattern matches, indexed.
+ * Every page a group's patterns list, indexed.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern.
+ * @param patterns - the patterns, `!` ones included (`listedFiles`).
  * @param watch - adds a file whose edit renews the module that read it.
  * @param fences - the fences the catalogue's plugins draw, which are not code; none by default.
+ * @param isKept - whether a listed page may be read; every one by default.
  */
-export declare const indexedDocPages: (root: string, pattern: string, watch: (file: string) => void, fences?: readonly string[]) => IndexedDocPage[];
+export declare const indexedDocPages: (root: string, patterns: readonly string[], watch: (file: string) => void, fences?: readonly string[], isKept?: IsFileKept) => IndexedDocPage[];
 /**
- * The code of the module for one pattern.
+ * The code of the module for one group.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern before `?forgebook-docs-pages`.
+ * @param patterns - the group's patterns.
  * @param watch - adds a file whose edit renews the module (each page: its index is in the module).
  * @param isServing - whether a dev server runs, whose tools read a page's Markdown.
  * @param plugins - the catalogue's plugins, whose fences a page may draw; none by default.
+ * @param isKept - whether a listed page may be read; every one by default.
  */
-export declare const docPagesModule: (root: string, pattern: string, watch: (file: string) => void, isServing: boolean, plugins?: readonly ForgebookPlugin[]) => string;
+export declare const docPagesModule: (root: string, patterns: readonly string[], watch: (file: string) => void, isServing: boolean, plugins?: readonly ForgebookPlugin[], isKept?: IsFileKept) => string;
 /**
  * The code of one page's module: what the shell draws, each image imported so Vite answers its address, and, on the dev
  * server, the page's Markdown for tools.