forgebook 0.1.8 → 0.2.0

package/dist/src/catalogue.d.ts

@@ -11,8 +11,11 @@
  *
  * @module
  */
+import type { 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,24 @@ 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 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 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 +109,14 @@ 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
+     * 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 +131,21 @@ 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[];
 };
-/** 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,8 +171,8 @@ 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 panel's tabs shown, Forgebook's then the plugins', by id. */
+    readonly tabs: readonly string[];
     /** The accessibility rules. */
     readonly a11y: A11ySettings;
     /** The measuring grid's step, in CSS px. */
@@ -157,6 +185,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,6 +198,10 @@ 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[];
 };
 /** WCAG 2.2 at levels A and AA: the rules every story passes by default. */
 export declare const DEFAULT_A11Y_TAGS: readonly string[];
@@ -175,10 +211,11 @@ export declare const DEFAULT_A11Y_TAGS: readonly string[];
  * @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 +223,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,16 +111,27 @@ 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 ?? []
+});
 /**
  * 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
         ? []
@@ -137,8 +153,8 @@ 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),
+        ...namedGroups(lists),
+        tabs: [...PANEL_TAB_IDS, ...pluginTabs].filter((tab) => tabsOff[tab] !== false),
         a11y: {
             tags: lists.a11y?.tags ?? DEFAULT_A11Y_TAGS,
             disabledRules: lists.a11y?.disabledRules ?? []
@@ -148,9 +164,13 @@ export const catalogueSettings = (title, switches, lists = {}) => {
         ownControls,
         toolbar,
         hasUsedIn: lists.usedIn !== false,
+        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)
     };
 };
 /**
@@ -160,4 +180,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

package/dist/src/codeLiteral.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Values written into generated code: a Vite module the plugin or an adapter generates, a `define` value, the code a
+ * transform inserts, or a script set inline in a page. Exported as `forgebook/code-literal`, so every adapter writes
+ * them the same way.
+ *
+ * @remarks
+ * `JSON.stringify` alone writes a valid JavaScript literal, but not one safe everywhere code goes: inside an inline
+ * `<script>`, a string holding `</script>` or `<!--` ends or changes the script, and before ES2019 a raw U+2028 or
+ * U+2029 ended a string literal. The literal written here escapes `<`, `>` and `/` and both separators, so it reads
+ * back as the same value in a module, in an inline script and in an older parser alike, wherever a generator places
+ * it. Each is written as a Unicode escape, never as a backslash before the character, so no escape depends on how the
+ * text's backslashes were escaped. The escapes only ever fall inside string literals: JSON writes those characters
+ * nowhere else. Each is a pass
+ * of its own, a native replacement as fast on a large document as one pass with a callback, and the form code
+ * scanners read as escaping.
+ *
+ * Imports nothing, so the shell (an embed's code), the plugin on Node and the adapters can all use it.
+ *
+ * @module
+ */
+/**
+ * JSON text as code: the same value, with `<`, `>`, `/`, U+2028 and U+2029 escaped. For JSON a caller already holds
+ * (a document also written to a file); otherwise `codeLiteral`. Only for JSON text: JSON writes those characters
+ * nowhere but inside strings, where their escapes read the same, while in other code (`a / b`, `x < y`) they would
+ * change it.
+ *
+ * @param json - the JSON text, as `JSON.stringify` writes it.
+ * @returns the text as a JavaScript expression of the same value.
+ */
+export declare const codeOfJson: (json: string) => string;
+/**
+ * A value as a JavaScript literal for generated code: `JSON.stringify` with the characters that could end a script
+ * or a string escaped (`codeOfJson`).
+ *
+ * @param value - a value JSON can write: a string, number, boolean, null, or an array or object of them.
+ * @returns the literal, which evaluates to an equal value.
+ * @throws `TypeError` when JSON writes nothing for the value (`undefined`, a function, a symbol), which would leave a
+ *   hole in the code, and for a `bigint`, which JSON cannot write. As in JSON, a key whose value is `undefined` is left
+ *   out and `NaN` is written `null`.
+ */
+export declare const codeLiteral: (value: unknown) => string;

package/dist/src/codeLiteral.js

@@ -0,0 +1,51 @@
+/**
+ * Values written into generated code: a Vite module the plugin or an adapter generates, a `define` value, the code a
+ * transform inserts, or a script set inline in a page. Exported as `forgebook/code-literal`, so every adapter writes
+ * them the same way.
+ *
+ * @remarks
+ * `JSON.stringify` alone writes a valid JavaScript literal, but not one safe everywhere code goes: inside an inline
+ * `<script>`, a string holding `</script>` or `<!--` ends or changes the script, and before ES2019 a raw U+2028 or
+ * U+2029 ended a string literal. The literal written here escapes `<`, `>` and `/` and both separators, so it reads
+ * back as the same value in a module, in an inline script and in an older parser alike, wherever a generator places
+ * it. Each is written as a Unicode escape, never as a backslash before the character, so no escape depends on how the
+ * text's backslashes were escaped. The escapes only ever fall inside string literals: JSON writes those characters
+ * nowhere else. Each is a pass
+ * of its own, a native replacement as fast on a large document as one pass with a callback, and the form code
+ * scanners read as escaping.
+ *
+ * Imports nothing, so the shell (an embed's code), the plugin on Node and the adapters can all use it.
+ *
+ * @module
+ */
+/**
+ * JSON text as code: the same value, with `<`, `>`, `/`, U+2028 and U+2029 escaped. For JSON a caller already holds
+ * (a document also written to a file); otherwise `codeLiteral`. Only for JSON text: JSON writes those characters
+ * nowhere but inside strings, where their escapes read the same, while in other code (`a / b`, `x < y`) they would
+ * change it.
+ *
+ * @param json - the JSON text, as `JSON.stringify` writes it.
+ * @returns the text as a JavaScript expression of the same value.
+ */
+export const codeOfJson = (json) => json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/\//g, "\\u002f")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+/**
+ * A value as a JavaScript literal for generated code: `JSON.stringify` with the characters that could end a script
+ * or a string escaped (`codeOfJson`).
+ *
+ * @param value - a value JSON can write: a string, number, boolean, null, or an array or object of them.
+ * @returns the literal, which evaluates to an equal value.
+ * @throws `TypeError` when JSON writes nothing for the value (`undefined`, a function, a symbol), which would leave a
+ *   hole in the code, and for a `bigint`, which JSON cannot write. As in JSON, a key whose value is `undefined` is left
+ *   out and `NaN` is written `null`.
+ */
+export const codeLiteral = (value) => {
+    const json = JSON.stringify(value);
+    if (typeof json !== "string")
+        throw new TypeError(`A ${typeof value} has no literal in generated code`);
+    return codeOfJson(json);
+};

package/dist/src/componentDocs.d.ts

@@ -50,6 +50,22 @@ export type FunctionSignatureDocs = {
     /** Its `@returns` text; empty when it has none. */
     readonly returnsDescription: string;
 };
+/**
+ * One member of a prop's object type (a `texts` prop's `FileFinderTexts`), listed under the prop in the API
+ * reference.
+ */
+export type MemberDocs = {
+    /** The member's name. */
+    readonly name: string;
+    /** Its type as the source writes it, without `undefined` and `null`. */
+    readonly type: string;
+    /** The first paragraph of its TSDoc; empty when it has none. */
+    readonly description: string;
+    /** Its `@defaultValue`, when the TSDoc gives one. */
+    readonly defaultValue?: string;
+    /** Whether the member must be given. */
+    readonly isRequired: boolean;
+};
 /** One prop of a component. */
 export type PropDocs = {
     /** The prop's name. */
@@ -77,6 +93,16 @@ export type PropDocs = {
      * field for it. Left out when `false`.
      */
     readonly canTakeText?: boolean;
+    /**
+     * The group its TSDoc puts it in (`@group Selection`): the API reference and the Props tab list it under that
+     * heading. Left out when it names none.
+     */
+    readonly group?: string;
+    /**
+     * The members of its type, when that type is an object the package declares and documents (`texts?: FileFinderTexts`),
+     * in the order the source declares them: the API reference lists them under the prop, folded. Left out otherwise.
+     */
+    readonly members?: readonly MemberDocs[];
 };
 /** A part the component is used with, named in the meta's `subcomponents`: listed under it on its page. */
 export type SubcomponentDocs = {
@@ -87,6 +113,22 @@ export type SubcomponentDocs = {
     /** Its props declared in the package, in the same order as the component's. */
     readonly props: readonly PropDocs[];
 };
+/**
+ * When to use a component and when not, as its TSDoc says: the rule a person knows and an agent has no way to guess.
+ * Tags: `@useWhen`, `@avoidWhen`, `@alternatives`, `@deprecated`, `@replacedBy`.
+ */
+export type UsageGuidance = {
+    /** The situations it is for, one per `@useWhen`. */
+    readonly useWhen?: readonly string[];
+    /** The situations it is not for, one per `@avoidWhen`. */
+    readonly avoidWhen?: readonly string[];
+    /** Components to consider instead, from `@alternatives`, comma-separated. */
+    readonly alternatives?: readonly string[];
+    /** Why not to use it any more, from `@deprecated`. */
+    readonly deprecated?: string;
+    /** What to use instead, from `@replacedBy`. */
+    readonly replacedBy?: string;
+};
 /** A story file's component. */
 export type ComponentDocs = {
     /** The component's name. */
@@ -107,12 +149,27 @@ export type ComponentDocs = {
     readonly parts: readonly string[];
     /** The parts the meta names in `subcomponents`, in the order it writes them; empty when it names none. */
     readonly subcomponents: readonly SubcomponentDocs[];
+    /** When to use it and when not, from its TSDoc; left out when it says nothing. */
+    readonly guidance?: UsageGuidance;
     /**
      * Its call signature, when it has one: the parameters and the return value a story about logic shows first (the
      * meta's `component` is then the hook or the function).
      */
     readonly signature?: FunctionSignatureDocs;
+    /**
+     * The CSS selector a template writes the component with, for a framework whose components are matched by one rather
+     * than named (an Angular component's `fb-badge`, a directive's `button[fbButton]`): the code writer writes the story's
+     * markup from it. Left out when the component is written by its name.
+     */
+    readonly selector?: string;
 };
+/**
+ * The name a story's code writes the component with: its selector when its framework matches components by one, its
+ * name otherwise.
+ *
+ * @param docs - the component's docs.
+ */
+export declare const codeNameOf: (docs: ComponentDocs) => string;
 /** What the plugin answers for a story file whose meta names no component (a foundations page). */
 export type NoComponentDocs = {
     /** No component. */
@@ -124,4 +181,3 @@ export type NoComponentDocs = {
  * @param value - the module's default export.
  */
 export declare const isComponentDocs: (value: unknown) => value is ComponentDocs;
-//# sourceMappingURL=componentDocs.d.ts.map

package/dist/src/componentDocs.js

@@ -10,12 +10,26 @@
  *
  * @module
  */
+/**
+ * The name a story's code writes the component with: its selector when its framework matches components by one, its
+ * name otherwise.
+ *
+ * @param docs - the component's docs.
+ */
+export const codeNameOf = (docs) => docs.selector ?? docs.name;
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Whether a value is a list of strings. */
 const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 /** The prop kinds, for the check. */
 const PROP_KINDS = ["choice", "text", "number", "toggle", "event", "other"];
+/** Whether a value is one member's docs. */
+const isMemberDocs = (value) => isRecord(value) &&
+    typeof value["name"] === "string" &&
+    typeof value["type"] === "string" &&
+    typeof value["description"] === "string" &&
+    typeof value["isRequired"] === "boolean" &&
+    (value["defaultValue"] === undefined || typeof value["defaultValue"] === "string");
 /** Whether a value is one prop's docs. */
 const isPropDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
@@ -23,7 +37,10 @@ const isPropDocs = (value) => isRecord(value) &&
     typeof value["type"] === "string" &&
     typeof value["description"] === "string" &&
     typeof value["isRequired"] === "boolean" &&
-    (value["canTakeText"] === undefined || typeof value["canTakeText"] === "boolean");
+    (value["canTakeText"] === undefined || typeof value["canTakeText"] === "boolean") &&
+    (value["group"] === undefined || typeof value["group"] === "string") &&
+    (value["members"] === undefined ||
+        (Array.isArray(value["members"]) && value["members"].every(isMemberDocs)));
 /** Whether a value is a subcomponent's docs. */
 const isSubcomponentDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
@@ -56,5 +73,5 @@ export const isComponentDocs = (value) => isRecord(value) &&
     isStringList(value["parts"]) &&
     Array.isArray(value["subcomponents"]) &&
     value["subcomponents"].every(isSubcomponentDocs) &&
-    (value["signature"] === undefined || isFunctionSignatureDocs(value["signature"]));
-//# sourceMappingURL=componentDocs.js.map
+    (value["signature"] === undefined || isFunctionSignatureDocs(value["signature"])) &&
+    (value["selector"] === undefined || typeof value["selector"] === "string");

package/dist/src/controlKeys.d.ts

@@ -82,4 +82,3 @@ export declare const cycledValue: <TValue>(values: readonly TValue[], current: T
  * @param each - the switch.
  */
 export declare const switchValues: (each: ViewSwitch) => string[];
-//# sourceMappingURL=controlKeys.d.ts.map

package/dist/src/controlKeys.js

@@ -120,4 +120,3 @@ export const cycledValue = (values, current, step) => {
  * @param each - the switch.
  */
 export const switchValues = (each) => each.values.map((value) => value.value);
-//# sourceMappingURL=controlKeys.js.map

package/dist/src/deviceDrawing.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A device's drawing: the hardware around the screen (its band, its bezel, its buttons) and what sits over the story
+ * (the camera's cut, the status bar, the home indicator), as shapes in CSS px, for the shell's frame and for
+ * `forgebook shot`'s framed pictures to draw the same device.
+ *
+ * @remarks
+ * Shapes and not markup, so each side draws them its own way (React elements in the shell, an SVG text in the
+ * pictures) from one geometry. The hardware is laid out upright and turned with its top to the left for landscape,
+ * as a phone is turned; the status bar is laid out for the screen as held, since a system lays it out again when
+ * the phone turns (an iPhone on its side shows none). The paints are named, not coloured: the frame takes the
+ * shell's appearance, the status bar's ink the story's scheme, as a phone's status bar follows the app under it.
+ * Pure.
+ *
+ * @module
+ */
+import type { DeviceOrientation } from "@forgebook/story-format/csf";
+import { type DeviceModel } from "./devices.ts";
+/** What a shape is painted with: the hardware's band, its outline, the bezel, the camera's cut, the status bar's ink. */
+export type DevicePaint = "frame" | "edge" | "bezel" | "cutout" | "ink";
+/** One shape of a drawing, in CSS px. */
+export type DeviceShape = {
+    /** A rectangle, its corners rounded. */
+    readonly kind: "rect";
+    /** Its left. */
+    readonly x: number;
+    /** Its top. */
+    readonly y: number;
+    /** Its width. */
+    readonly width: number;
+    /** Its height. */
+    readonly height: number;
+    /** Its corners' radius. */
+    readonly radius: number;
+    /** Its fill; none for an outline only. */
+    readonly fill?: DevicePaint;
+    /** Its outline, 1 px wide; none by default. */
+    readonly stroke?: DevicePaint;
+    /** Its opacity, from 0 to 1; 1 by default. */
+    readonly opacity?: number;
+} | {
+    /** A disc. */
+    readonly kind: "circle";
+    /** Its centre's left. */
+    readonly cx: number;
+    /** Its centre's top. */
+    readonly cy: number;
+    /** Its radius. */
+    readonly r: number;
+    /** Its fill. */
+    readonly fill: DevicePaint;
+} | {
+    /** A path, in SVG's path syntax. */
+    readonly kind: "path";
+    /** Its commands. */
+    readonly d: string;
+    /** Its fill. */
+    readonly fill: DevicePaint;
+} | {
+    /** A line of text, centred on its height. */
+    readonly kind: "text";
+    /** Where it starts, or its middle. */
+    readonly x: number;
+    /** Its middle's height. */
+    readonly y: number;
+    /** What it says. */
+    readonly text: string;
+    /** Its size, in CSS px. */
+    readonly size: number;
+    /** Its weight. */
+    readonly weight: number;
+    /** Whether `x` is its start or its middle. */
+    readonly anchor: "start" | "middle";
+    /** Its fill. */
+    readonly fill: DevicePaint;
+};
+/** A rectangle, its corners rounded, in CSS px. */
+export type DeviceRect = {
+    /** Its left. */
+    readonly x: number;
+    /** Its top. */
+    readonly y: number;
+    /** Its width. */
+    readonly width: number;
+    /** Its height. */
+    readonly height: number;
+    /** Its corners' radius. */
+    readonly radius: number;
+};
+/** A device drawn: its size, where its screen is, and its shapes under and over the screen. */
+export type DeviceDrawing = {
+    /** The drawing's width, the buttons included, in CSS px. */
+    readonly width: number;
+    /** The drawing's height, in CSS px. */
+    readonly height: number;
+    /** The screen, where the story goes: its viewport's size, at its place in the drawing. */
+    readonly screen: DeviceRect;
+    /** Drawn under the screen: the buttons, the band and the bezel. */
+    readonly under: readonly DeviceShape[];
+    /** Drawn over the story, never taking the pointer: the camera's cut, the status bar, the home indicator. */
+    readonly over: readonly DeviceShape[];
+};
+/** The paints of the hardware in each of the shell's appearances: quiet greys, a black bezel, as phones are. */
+export declare const DEVICE_PAINTS: Readonly<Record<"light" | "dark", Readonly<Record<Exclude<DevicePaint, "ink">, string>>>>;
+/** The status bar's ink over a story of each scheme: dark on a light story, light on a dark one. */
+export declare const DEVICE_INK: Readonly<Record<"light" | "dark", string>>;
+/** The status bar's font: the system's, as the devices' own. */
+export declare const DEVICE_FONT = "-apple-system, BlinkMacSystemFont, \"SF Pro Text\", Roboto, system-ui, sans-serif";
+/**
+ * A model drawn, held one way.
+ *
+ * @param model - the model.
+ * @param orientation - how it is held: on its side, its top to the left.
+ */
+export declare const deviceDrawing: (model: DeviceModel, orientation: DeviceOrientation) => DeviceDrawing;