forgebook 0.1.8 → 0.3.0

package/dist/src/backdrops.js

@@ -1,167 +1,58 @@
 /**
- * A text written inside an SVG document, with the characters XML reserves escaped.
+ * The backdrops Forgebook draws behind a story in place of its page's colour: a checkerboard, a vivid
+ * abstract picture, a light and a dark desktop-like picture, a page of content, and a catalogue's own. They show what a translucent
+ * surface (a menu's or a popover's glass, its blur) does, which the page's plain colour hides.
  *
- * @param text - the text.
- */
-const xmlText = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
-/**
- * An SVG document as a CSS image.
+ * @remarks
+ * What the shell needs of a backdrop lives here: its id, its name and the colour under its picture, which the box a
+ * story waits in takes while it loads (`backdropColor`). Forgebook's own pictures are drawn by the frame alone
+ * (`backdropPictures.ts`, with the style sheet that puts them behind the story), so the shell's first load carries
+ * none of them. The desktop pictures are fixed whatever the theme; the page of content follows the theme, as an app's
+ * page would. Pure.
  *
- * @param width - the picture's width, in its own units.
- * @param height - the picture's height, in its own units.
- * @param content - the SVG elements inside the root.
- */
-const svgImage = (width, height, content) => {
-    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" ` +
-        `viewBox="0 0 ${width} ${height}" preserveAspectRatio="xMidYMid slice">${content}</svg>`;
-    return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
-};
-/** The same look in both themes: a backdrop that does not follow the theme. */
-const fixed = (look) => ({ light: look, dark: look });
-/** The checkerboard: grey and white squares of 8 px, the usual sign of a transparent picture. */
-const CHECKERBOARD = {
-    color: "#ffffff",
-    layers: "repeating-conic-gradient(#d6d6d6 0% 25%, #ffffff 0% 50%) 0 0 / 16px 16px"
-};
-/** The vivid picture's shapes, in its tile of 480 px. */
-const VIVID_SHAPES = svgImage(480, 480, '<circle cx="96" cy="104" r="64" fill="#ffd60a"/>' +
-    '<circle cx="372" cy="336" r="88" fill="#22d3ee"/>' +
-    '<rect x="248" y="56" width="176" height="56" rx="28" fill="#ffffff" fill-opacity="0.85"/>' +
-    '<rect x="40" y="300" width="56" height="140" rx="12" fill="#34d399"/>' +
-    '<path d="M150 240 L330 240 L240 420 Z" fill="#ff4d8d"/>' +
-    '<g stroke="#111827" stroke-width="10" stroke-opacity="0.55">' +
-    '<line x1="300" y1="160" x2="460" y2="160"/><line x1="300" y1="190" x2="460" y2="190"/>' +
-    '<line x1="300" y1="220" x2="460" y2="220"/></g>');
-/**
- * The vivid picture: crisp circles, bars and stripes on a saturated gradient, the shapes repeated every 480 px, so a
- * surface's blur shows on sharp edges wherever it sits.
+ * @module
  */
-const GRADIENT = {
-    color: "#7c3aed",
-    layers: `${VIVID_SHAPES} 0 0 / 480px 480px repeat, linear-gradient(135deg, #5b21b6 0%, #db2777 55%, #f97316 100%)`
+/** The colour under each of Forgebook's pictures: the page of content's follows the theme, the others' do not. */
+export const BUILT_IN_COLORS = {
+    checkerboard: { light: "#ffffff", dark: "#ffffff" },
+    gradient: { light: "#7c3aed", dark: "#7c3aed" },
+    lightDesktop: { light: "#e4ecf8", dark: "#e4ecf8" },
+    darkDesktop: { light: "#0d1226", dark: "#0d1226" },
+    content: { light: "#ffffff", dark: "#16181d" }
 };
 /**
- * Rolling hills under a sky, the shape of a desktop picture.
+ * One of Forgebook's backdrops.
  *
- * @param colors - the sky's two colours, top and bottom, a glow's colour, and the three hills', back to front.
+ * @param id - its id.
+ * @param label - its name in the View menu.
  */
-const hills = (colors) => svgImage(1600, 1000, '<defs><linearGradient id="sky" x1="0" y1="0" x2="0" y2="1">' +
-    `<stop offset="0" stop-color="${colors.skyTop}"/><stop offset="1" stop-color="${colors.skyBottom}"/>` +
-    '</linearGradient><radialGradient id="glow" cx="0.72" cy="0.3" r="0.4">' +
-    `<stop offset="0" stop-color="${colors.glow}" stop-opacity="0.9"/>` +
-    `<stop offset="1" stop-color="${colors.glow}" stop-opacity="0"/></radialGradient></defs>` +
-    '<rect width="1600" height="1000" fill="url(#sky)"/>' +
-    '<rect width="1600" height="1000" fill="url(#glow)"/>' +
-    `<path d="M0 560 C260 470 520 640 820 560 S1360 430 1600 520 L1600 1000 L0 1000 Z" fill="${colors.hills[0]}"/>` +
-    `<path d="M0 700 C320 600 640 780 960 690 S1420 600 1600 660 L1600 1000 L0 1000 Z" fill="${colors.hills[1]}"/>` +
-    `<path d="M0 840 C360 760 700 900 1040 830 S1460 760 1600 800 L1600 1000 L0 1000 Z" fill="${colors.hills[2]}"/>`);
-/** The light desktop: pale hills under a morning sky. */
-const LIGHT_DESKTOP = {
-    color: "#e4ecf8",
-    layers: `${hills({
-        skyTop: "#cfe0fa",
-        skyBottom: "#f8e6ee",
-        glow: "#fff4d6",
-        hills: ["#b7cdf0", "#e8b9cf", "#9fc9b4"]
-    })} center / cover no-repeat`
-};
-/** The dark desktop: deep hills under a night sky with a violet glow. */
-const DARK_DESKTOP = {
-    color: "#0d1226",
-    layers: `${hills({
-        skyTop: "#070b1a",
-        skyBottom: "#1d1547",
-        glow: "#7c3aed",
-        hills: ["#23306b", "#3b2a7a", "#0f3a55"]
-    })} center / cover no-repeat`
-};
-/** A paragraph of the page, one line per entry: SVG text does not wrap. */
-const PARAGRAPH = [
-    "Start the tomatoes indoors six weeks before the last frost, then move",
-    "them out once the nights stay warm. Keep the herbs near the kitchen",
-    "door, where they are easy to reach, and the squash at the far end."
-];
-/** The rows of the page: a title, a line under it, a value at the end. */
-const ROWS = [
-    ["Seed trays", "Delivered on Tuesday", "12"],
-    ["Watering schedule", "Every other morning", "3 zones"],
-    ["Compost bins", "Turned last week", "2"],
-    ["Tool shed", "Needs a new hinge", "1 task"]
-];
-/** The font of the page's text: the system's, the only one a picture drawn as an image can use. */
-const PAGE_FONT = "system-ui, -apple-system, Segoe UI, sans-serif";
-/**
- * A page of content as an app shows it, in a tile of 720 × 600 px repeated: a heading, a paragraph, a coloured
- * picture and a list of rows.
- *
- * @param palette - the theme's colours.
- */
-const contentPage = (palette) => {
-    const paragraph = PARAGRAPH.map((line, index) => `<text x="40" y="${104 + index * 24}" font-size="15" fill="${palette.text}">${xmlText(line)}</text>`).join("");
-    const rows = ROWS.map(([title, detail, value], index) => {
-        const top = 312 + index * 68;
-        const icon = palette.icons[index] ?? palette.secondary;
-        return (`<rect x="40" y="${top + 12}" width="36" height="36" rx="8" fill="${icon}"/>` +
-            `<text x="92" y="${top + 27}" font-size="15" font-weight="600" fill="${palette.text}">${xmlText(title)}</text>` +
-            `<text x="92" y="${top + 47}" font-size="13" fill="${palette.secondary}">${xmlText(detail)}</text>` +
-            `<text x="680" y="${top + 36}" font-size="14" text-anchor="end" fill="${palette.secondary}">` +
-            `${xmlText(value)}</text>` +
-            `<line x1="40" y1="${top + 64}" x2="680" y2="${top + 64}" stroke="${palette.divider}"/>`);
-    }).join("");
-    return {
-        color: palette.page,
-        layers: `${svgImage(720, 600, `<rect width="720" height="600" fill="${palette.page}"/>` +
-            `<g font-family="${PAGE_FONT}">` +
-            `<text x="40" y="64" font-size="26" font-weight="700" fill="${palette.text}">Spring garden plan</text>` +
-            paragraph +
-            '<defs><linearGradient id="picture" x1="0" y1="0" x2="1" y2="1">' +
-            '<stop offset="0" stop-color="#4f7cff"/><stop offset="0.5" stop-color="#a855f7"/>' +
-            '<stop offset="1" stop-color="#f97316"/></linearGradient></defs>' +
-            '<rect x="40" y="184" width="640" height="104" rx="12" fill="url(#picture)"/>' +
-            '<circle cx="600" cy="236" r="30" fill="#ffd60a"/>' +
-            rows +
-            "</g>")} 0 0 / 720px 600px repeat`
-    };
-};
-/** The page of content, in both schemes. */
-const CONTENT = {
-    light: contentPage({
-        page: "#ffffff",
-        text: "#1f2328",
-        secondary: "#656d76",
-        divider: "#d8dee4",
-        icons: ["#4f7cff", "#22c55e", "#f59e0b", "#ec4899"]
-    }),
-    dark: contentPage({
-        page: "#16181d",
-        text: "#e6e8eb",
-        secondary: "#9aa1ab",
-        divider: "#2d3139",
-        icons: ["#6b8cff", "#34d399", "#fbbf24", "#f472b6"]
-    })
-};
+const builtIn = (id, label) => ({
+    kind: "builtIn",
+    id,
+    label,
+    colors: BUILT_IN_COLORS[id]
+});
 /** The backdrops Forgebook draws, in the View menu's order: every one but the page's own colour. */
 export const BUILT_IN_BACKDROPS = [
-    { id: "checkerboard", label: "Checkerboard", drawn: fixed(CHECKERBOARD) },
-    { id: "gradient", label: "Vivid picture", drawn: fixed(GRADIENT) },
-    { id: "lightDesktop", label: "Light desktop", drawn: fixed(LIGHT_DESKTOP) },
-    { id: "darkDesktop", label: "Dark desktop", drawn: fixed(DARK_DESKTOP) },
-    { id: "content", label: "Page of content", drawn: CONTENT }
+    builtIn("checkerboard", "Checkerboard"),
+    builtIn("gradient", "Vivid picture"),
+    builtIn("lightDesktop", "Light desktop"),
+    builtIn("darkDesktop", "Dark desktop"),
+    builtIn("content", "Page of content")
 ];
 /**
- * A catalogue's own backdrop, drawn as the built-in ones are.
+ * A catalogue's own backdrop, offered as the built-in ones are.
  *
  * @param custom - the backdrop as the configuration writes it.
  */
 export const customBackdrop = (custom) => {
-    const look = (written) => ({
-        color: written.color,
-        layers: written.layers ?? "none"
-    });
+    const dark = custom.dark ?? custom.light;
     return {
+        kind: "own",
         id: custom.id,
         label: custom.label,
-        drawn: { light: look(custom.light), dark: look(custom.dark ?? custom.light) }
+        colors: { light: custom.light.color, dark: dark.color },
+        layers: { light: custom.light.layers ?? "none", dark: dark.layers ?? "none" }
     };
 };
 /**
@@ -171,32 +62,4 @@ export const customBackdrop = (custom) => {
  * @param isDark - whether the story is drawn in the dark scheme (a backdrop may follow it).
  * @returns the CSS colour; none for the page's own colour.
  */
-export const backdropColor = (backdrop, isDark) => backdrop === undefined ? undefined : (isDark ? backdrop.drawn.dark : backdrop.drawn.light).color;
-/** A `body` rule that draws a look over whatever background the source's sheets set. */
-const bodyRule = (selector, look) => `${selector} { background: ${look.layers}, ${look.color} !important; }`;
-/**
- * The style sheet that draws a backdrop behind a frame's story.
- *
- * @remarks
- * The rule sits on `body`, where the sources set their page colour, and wins over it with `!important`, so the
- * story's own elements keep every colour they set. The dark look follows the scheme the view draws in (its colour
- * scheme switch's, `switches.ts`), the system's preference for `system`; with forced colours the sheet draws nothing.
- *
- * @param backdrop - the backdrop; none for the page's own colour.
- * @param scheme - the scheme the story is drawn in.
- * @returns the CSS; empty for the page's own colour.
- */
-export const backdropSheet = (backdrop, scheme) => {
-    if (backdrop === undefined)
-        return "";
-    const { light, dark } = backdrop.drawn;
-    if (light === dark || scheme === "light")
-        return `@media (forced-colors: none) { ${bodyRule("body", light)} }`;
-    if (scheme === "dark")
-        return `@media (forced-colors: none) { ${bodyRule("body", dark)} }`;
-    return [
-        `@media (forced-colors: none) { ${bodyRule("body", light)} }`,
-        `@media (forced-colors: none) and (prefers-color-scheme: dark) { ${bodyRule("body", dark)} }`
-    ].join("\n");
-};
-//# sourceMappingURL=backdrops.js.map
+export const backdropColor = (backdrop, isDark) => backdrop?.colors[isDark ? "dark" : "light"];

package/dist/src/catalogue.d.ts

@@ -11,8 +11,11 @@
  *
  * @module
  */
+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";
+import { type DeviceDefault } from "./deviceView.ts";
 import type { CatalogueView } from "./namedViews.ts";
 import { type TouchChoice, type ViewSwitch } from "./switches.ts";
 /** A preset width of the toolbar. */
@@ -29,20 +32,25 @@ export type StoryGroupSetting = {
     /** Its heading in the sidebar (`States`). */
     readonly label: string;
 };
-/** The tabs of the panel under a story. */
+/** Forgebook's own tabs of the panel under a story. */
 export declare const PANEL_TAB_IDS: readonly ["props", "events", "play", "parts", "code", "a11y", "signature"];
-/** A tab of the panel under a story. */
+/** One of Forgebook's own tabs of the panel under a story. */
 export type PanelTabId = (typeof PANEL_TAB_IDS)[number];
 /**
- * Forgebook's own controls of the toolbar and the View menu, beside the catalogue's switches: the background, the
- * style sheets, the text size and the stage's width. Their ids are the address's own parameters, so no switch takes
- * one.
+ * Forgebook's own controls of the toolbar and the View menu, beside the catalogue's switches: the device frame (first,
+ * so it sits beside the Touch switch, the last of the ready-made ones), the background, the style sheets, the text
+ * size, the stage's width and who a component's page is read by. Their ids are their parameters in the address, so no
+ * switch takes one; the device's is under Forgebook's name (`forgebook.device`), so a catalogue's own `device` switch
+ * keeps its id.
  */
-export declare const OWN_CONTROL_IDS: readonly ["backdrop", "sheets", "text", "width"];
+export declare const OWN_CONTROL_IDS: readonly ["forgebook.device", "backdrop", "sheets", "text", "width", "audience"];
 /** One of Forgebook's own controls. */
 export type OwnControlId = (typeof OWN_CONTROL_IDS)[number];
-/** What `controls` turns off: one of Forgebook's own controls, or its ready-made direction or touch switch. */
-export type TurnedOffControl = OwnControlId | "direction" | "touch";
+/**
+ * What `controls` turns off: one of Forgebook's own controls, its ready-made direction or touch switch, or the story
+ * bar's Embed button.
+ */
+export type TurnedOffControl = OwnControlId | "direction" | "touch" | "embed";
 /** The accessibility rules the Accessibility tab and the generated tests check. */
 export type A11ySettings = {
     /** The axe tags whose rules apply. */
@@ -74,23 +82,27 @@ export type CatalogueLists = {
     };
     /** The story groups, in the sidebar's order, with their headings. */
     readonly storyGroups?: readonly StoryGroupSetting[];
-    /** The panel's tabs turned off (`{ a11y: false }`). */
-    readonly tabs?: Readonly<Partial<Record<PanelTabId, false>>>;
-    /** The accessibility rules. */
-    readonly a11y?: Partial<A11ySettings>;
+    /** 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, 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` (a translation, another word). */
+    /** Texts of the shell replaced, by their name in `STRINGS` or `LATER_STRINGS` (a translation, another word). */
     readonly strings?: Readonly<Record<string, string>>;
     /**
      * Forgebook's own controls turned off (`{ sheets: false }`): shown nowhere, and the background, the style sheets
      * and the text size keep their default; the stage's width is still set by the stage's handle. `direction: false`
-     * and `touch: false` drop the ready-made direction and touch switches.
+     * and `touch: false` drop the ready-made direction and touch switches. `embed: false` takes the Embed button off
+     * the story bar; a `?embed` address still works, since any page can frame what it can open.
      */
     readonly controls?: Readonly<Partial<Record<TurnedOffControl, false>>>;
     /**
      * The controls that start on the toolbar, in their order, by id (a switch's id or one of `OWN_CONTROL_IDS`); the
-     * colour scheme, the contrast and the width by default. A control turned off in `controls` (here or by a preset) is
+     * colour scheme, the contrast, the width and the device by default. A control turned off in `controls` (here or by a preset) is
      * left out. A person's own arrangement replaces it.
      */
     readonly toolbar?: readonly string[];
@@ -100,7 +112,21 @@ export type CatalogueLists = {
      */
     readonly usedIn?: boolean;
     /**
-     * The shell's appearance before a reader picks one: `system` (the default) follows the system's light or dark. A
+     * 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;
+     * with `controls: { audience: false }` the catalogue's choice is the only one.
+     */
+    readonly audience?: AudienceId;
+    /**
+     * The shell's appearance before a reader picks one; `story` follows the colour scheme of the story shown, for a
+     * library that wants one page with its stories: `system` (the default) follows the system's light or dark. A
      * reader's choice, kept in their browser, wins over it; the frames follow the view's switches, never this.
      */
     readonly appearance?: Appearance;
@@ -115,9 +141,28 @@ export type CatalogueLists = {
      * (`theme=dark&width=360`) or as words (`"dark it 360"`); a reader saves their own beside them.
      */
     readonly views?: readonly CatalogueView[];
+    /**
+     * The device every story is shown in by default, under each story's own `parameters.device`: `{ frame: true }`
+     * frames them all in a generic phone, `{ model: "pixel-9" }` only sets the model the toolbar's toggle turns on. No
+     * frame by default.
+     */
+    readonly device?: StoryDeviceSetting;
+    /**
+     * The prop groups listed first in every component's API reference and Props tab, in this order, by the name their
+     * props' TSDoc gives (`@group Selection`). A component's meta may name its own first (`parameters.propGroups`); the
+     * 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, or the system's. */
-export type Appearance = "light" | "dark" | "system";
+/** 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";
 /** The appearances, in the order the reader is offered them. */
 export declare const APPEARANCES: readonly Appearance[];
 /** A catalogue's lists with the defaults filled in, and its switches: what the shell and the frame read. */
@@ -143,10 +188,15 @@ export type CatalogueSettings = {
     readonly backdrops: readonly Backdrop[];
     /** The named story groups, in their order. */
     readonly storyGroups: readonly StoryGroupSetting[];
-    /** The panel's tabs shown, in their order. */
-    readonly tabs: readonly PanelTabId[];
-    /** The accessibility rules. */
-    readonly a11y: A11ySettings;
+    /** The panel's tabs shown, Forgebook's then the plugins', by id. */
+    readonly tabs: readonly string[];
+    /**
+     * 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. */
@@ -157,6 +207,10 @@ export type CatalogueSettings = {
     readonly toolbar: readonly string[];
     /** Whether a component's page offers "Used in". */
     readonly hasUsedIn: boolean;
+    /** Who a component's page is read by when the address does not say. */
+    readonly audience: AudienceId;
+    /** Whether the story bar offers the Embed button. */
+    readonly hasEmbed: boolean;
     /** The shell's appearance before a reader picks one. */
     readonly appearance: Appearance;
     /** The keys that cycle the controls, by control id. */
@@ -166,19 +220,45 @@ export type CatalogueSettings = {
         readonly name: string;
         readonly query: string;
     }[];
+    /** The device every story is shown in by default, under its own. */
+    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.
  *
  * @param title - the catalogue's title, for its storage's id.
  * @param switches - its switches.
  * @param lists - the lists its configuration sets.
+ * @param pluginTabs - the ids of the tabs its plugins add.
  * @throws when the toolbar it names holds an id that is no control at all, or one twice; or a key it sets cannot be
  *   used; or a view it names cannot be read.
  */
-export declare const catalogueSettings: (title: string, switches: readonly ViewSwitch[], lists?: CatalogueLists) => CatalogueSettings;
+export declare const catalogueSettings: (title: string, switches: readonly ViewSwitch[], lists?: CatalogueLists, pluginTabs?: readonly string[]) => CatalogueSettings;
 /**
  * A story group's heading: the catalogue's name for it, or its id when it names none.
  *
@@ -186,4 +266,3 @@ export declare const catalogueSettings: (title: string, switches: readonly ViewS
  * @param id - the group's id.
  */
 export declare const groupLabel: (groups: readonly StoryGroupSetting[], id: string) => string;
-//# sourceMappingURL=catalogue.d.ts.map

package/dist/src/catalogue.js

@@ -11,20 +11,24 @@
  *
  * @module
  */
+import { DEFAULT_AUDIENCE } from "./audiences.js";
 import { BUILT_IN_BACKDROPS, customBackdrop } from "./backdrops.js";
 import { catalogueKeys } from "./controlKeys.js";
+import { DEVICE_PARAMETER, deviceDefaultOf, NO_DEVICE } from "./deviceView.js";
 import { switchWithRole, touchChoiceOf } from "./switches.js";
 import { viewQuery } from "./viewWords.js";
-/** The tabs of the panel under a story. */
+/** Forgebook's own tabs of the panel under a story. */
 export const PANEL_TAB_IDS = ["props", "events", "play", "parts", "code", "a11y", "signature"];
 /**
- * Forgebook's own controls of the toolbar and the View menu, beside the catalogue's switches: the background, the
- * style sheets, the text size and the stage's width. Their ids are the address's own parameters, so no switch takes
- * one.
+ * Forgebook's own controls of the toolbar and the View menu, beside the catalogue's switches: the device frame (first,
+ * so it sits beside the Touch switch, the last of the ready-made ones), the background, the style sheets, the text
+ * size, the stage's width and who a component's page is read by. Their ids are their parameters in the address, so no
+ * switch takes one; the device's is under Forgebook's name (`forgebook.device`), so a catalogue's own `device` switch
+ * keeps its id.
  */
-export const OWN_CONTROL_IDS = ["backdrop", "sheets", "text", "width"];
+export const OWN_CONTROL_IDS = [DEVICE_PARAMETER, "backdrop", "sheets", "text", "width", "audience"];
 /** The appearances, in the order the reader is offered them. */
-export const APPEARANCES = ["light", "dark", "system"];
+export const APPEARANCES = ["light", "dark", "system", "story"];
 /** WCAG 2.2 at levels A and AA: the rules every story passes by default. */
 export const DEFAULT_A11Y_TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];
 /** The toolbar's widths by default: a phone, the stage beside the props panel (the tests' narrow variant), a tablet, a laptop. */
@@ -52,15 +56,16 @@ const idOf = (title) => title
  */
 const withHundred = (list, fallback) => list?.includes(100) ? [...list].sort((first, second) => first - second) : fallback;
 /**
- * The controls that start on the toolbar when the configuration names none: the colour scheme, the contrast and the
- * width, those the catalogue has.
+ * The controls that start on the toolbar when the configuration names none: the colour scheme, the contrast, the
+ * width and the device, those the catalogue has.
  *
  * @param switches - the catalogue's switches.
  * @param ownControls - Forgebook's own controls shown.
  */
 const defaultToolbar = (switches, ownControls) => [
     ...[switchWithRole(switches, "colorScheme"), switchWithRole(switches, "contrast")].flatMap((each) => each === undefined ? [] : [each.id]),
-    ...(ownControls.includes("width") ? ["width"] : [])
+    ...(ownControls.includes("width") ? ["width"] : []),
+    ...(ownControls.includes(DEVICE_PARAMETER) ? [DEVICE_PARAMETER] : [])
 ];
 /**
  * Why the toolbar a configuration names cannot be used, or none: every id a control there is (a switch, or one of
@@ -106,21 +111,72 @@ const catalogueViews = (switches, views = []) => views.map((each) => {
         throw new Error(`Forgebook's view "${each.name}": ${read.error}`);
     return { name: each.name, query: read.query };
 });
+/**
+ * The groups a catalogue names, of stories and of props, none by default.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+const namedGroups = (lists) => ({
+    storyGroups: lists.storyGroups ?? [],
+    propGroups: lists.propGroups ?? []
+});
+/**
+ * Whether a catalogue checks accessibility: unless its lists say `a11y: false`.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+export const checksA11y = (lists) => lists.a11y !== false;
+/**
+ * Whether a catalogue reads its components' docs from their types: unless its lists say `componentDocs: false`.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+export const readsComponentDocs = (lists) => lists.componentDocs !== false;
+/**
+ * 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 const offersUsedIn = (lists) => lists.usedIn !== false && readsComponentDocs(lists);
+/**
+ * The panel's tabs a catalogue shows: Forgebook's then its plugins', less those it turns off, and the Accessibility
+ * tab when it checks nothing.
+ *
+ * @param lists - the lists its configuration sets.
+ * @param pluginTabs - the ids of the tabs its plugins add.
+ */
+const shownTabs = (lists, pluginTabs) => {
+    const tabsOff = lists.tabs ?? {};
+    const hasA11y = checksA11y(lists);
+    return [...PANEL_TAB_IDS, ...pluginTabs].filter((tab) => tabsOff[tab] !== false && (hasA11y || tab !== "a11y"));
+};
+/**
+ * A catalogue's accessibility rules, the defaults filled in; none when it checks nothing.
+ *
+ * @param lists - the lists its configuration sets.
+ */
+const a11ySettings = (lists) => {
+    if (lists.a11y === false)
+        return undefined;
+    return { tags: lists.a11y?.tags ?? DEFAULT_A11Y_TAGS, disabledRules: lists.a11y?.disabledRules ?? [] };
+};
 /**
  * A catalogue's settings, its lists' defaults filled in.
  *
  * @param title - the catalogue's title, for its storage's id.
  * @param switches - its switches.
  * @param lists - the lists its configuration sets.
+ * @param pluginTabs - the ids of the tabs its plugins add.
  * @throws when the toolbar it names holds an id that is no control at all, or one twice; or a key it sets cannot be
  *   used; or a view it names cannot be read.
  */
-export const catalogueSettings = (title, switches, lists = {}) => {
+export const catalogueSettings = (title, switches, lists = {}, pluginTabs = []) => {
+    const { audience = DEFAULT_AUDIENCE } = lists;
     const builtIn = lists.backgrounds?.builtIn;
     const offered = builtIn === false
         ? []
         : BUILT_IN_BACKDROPS.filter((backdrop) => builtIn === undefined || builtIn.includes(backdrop.id));
-    const tabsOff = lists.tabs ?? {};
     const controlsOff = lists.controls ?? {};
     const ownControls = OWN_CONTROL_IDS.filter((control) => controlsOff[control] !== false);
     const named = lists.toolbar ?? defaultToolbar(switches, ownControls);
@@ -137,20 +193,23 @@ export const catalogueSettings = (title, switches, lists = {}) => {
         zooms: withHundred(lists.zooms, [50, 75, 100, 125, 150, 200]),
         textSizes: withHundred(lists.textSizes, [100, 125, 150]),
         backdrops: [...offered, ...(lists.backgrounds?.custom ?? []).map(customBackdrop)],
-        storyGroups: lists.storyGroups ?? [],
-        tabs: PANEL_TAB_IDS.filter((tab) => tabsOff[tab] !== false),
-        a11y: {
-            tags: lists.a11y?.tags ?? DEFAULT_A11Y_TAGS,
-            disabledRules: lists.a11y?.disabledRules ?? []
-        },
+        ...namedGroups(lists),
+        tabs: shownTabs(lists, pluginTabs),
+        a11y: a11ySettings(lists),
+        hasComponentDocs: readsComponentDocs(lists),
         gridStep: lists.gridStep ?? 8,
         strings: lists.strings ?? {},
         ownControls,
         toolbar,
-        hasUsedIn: lists.usedIn !== false,
+        hasUsedIn: offersUsedIn(lists),
+        audience,
+        hasEmbed: controlsOff.embed !== false,
         appearance: lists.appearance ?? "system",
         keys: usableKeys([...switches.map((each) => each.id), ...ownControls], lists.keys),
-        views: catalogueViews(switches, lists.views)
+        views: catalogueViews(switches, lists.views),
+        // checked when the configuration loads (`configFile.ts`): a model that is none is left out here
+        device: deviceDefaultOf(NO_DEVICE, lists.device),
+        requiredFirst: lists.requiredFirst ?? "in-groups"
     };
 };
 /**
@@ -160,4 +219,3 @@ export const catalogueSettings = (title, switches, lists = {}) => {
  * @param id - the group's id.
  */
 export const groupLabel = (groups, id) => groups.find((group) => group.id === id)?.label ?? id;
-//# sourceMappingURL=catalogue.js.map