forgebook 0.1.7 → 0.2.0

package/dist/src/addressArgs.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The props panel's values an address names (`?args=`), checked against what the story declares before any reaches
+ * its frame.
+ *
+ * @remarks
+ * A link shares a view, so whoever writes the link chooses these values, and the frame runs on the catalogue's own
+ * origin. Handed on unchecked, a name the story never declared reaches the component, which may pass it to an element
+ * as an attribute: `innerHTML` or `onclick` on Vue's fallthrough attributes, `srcDoc` on a React element that spreads
+ * its rest props; each runs a script with the catalogue's rights. So a value is kept only when the panel itself could
+ * have set it: a prop the panel lets the person set (the component's props with the story's `argTypes` laid over them,
+ * or an arg only the `argTypes` or the story's own args name), with a value of that prop's type. Everything else is
+ * left out and reported. A value that is code never comes from an address: a named value is looked up among the
+ * source's own entries only, never through an object's prototype (`constructor`). Pure.
+ *
+ * @module
+ */
+import type { StoryControlsSetting } from "@forgebook/story-format/source";
+import { type PanelArgTypes, type PanelProp } from "./argTypes.ts";
+import type { PropDocs } from "./componentDocs.ts";
+import { type ArgValue, type PanelArgs } from "./messages.ts";
+import { type NamedValues } from "./namedValues.ts";
+/** What a story declares about the args the panel sets, as the shell knows it once the story's frame is ready. */
+export type ArgDeclaration = {
+    /** The props the component's types give; none when the story has no component or its docs could not be read. */
+    readonly props: readonly PropDocs[];
+    /** The story's `argTypes`, as its frame reported them. */
+    readonly argTypes: PanelArgTypes;
+    /** The props the story lets the panel set. */
+    readonly controls: StoryControlsSetting;
+    /** The story's own args the panel can show, as its frame reported them. */
+    readonly storyArgs: PanelArgs;
+    /** The values the source names for types the panel cannot write. */
+    readonly namedValues: NamedValues;
+};
+/** Why a value of the address was left out: its name is not one the panel sets, or its value is not of the prop's type. */
+export type DroppedArgReason = "undeclared" | "type";
+/** A value of the address left out. */
+export type DroppedArg = {
+    /** The arg's name, as the address wrote it. */
+    readonly name: string;
+    /** Why it was left out. */
+    readonly reason: DroppedArgReason;
+};
+/** The address's values once checked. */
+export type CheckedArgs = {
+    /** The values the story receives. */
+    readonly accepted: PanelArgs;
+    /** The values left out, in the address's order. */
+    readonly dropped: readonly DroppedArg[];
+};
+/**
+ * The props the panel sets for a story, whatever the address says: the component's props with the `argTypes` over
+ * them and the args only the `argTypes` name, then the story's own args the two leave out, each kept only when the
+ * story's controls let the panel set it.
+ *
+ * @param declaration - what the story declares.
+ */
+export declare const declaredArgProps: (declaration: ArgDeclaration) => readonly PanelProp[];
+/**
+ * Whether a value is one the panel could set for a prop: of the control the `argTypes` name, otherwise of the prop's
+ * kind.
+ *
+ * @param prop - a prop the panel sets.
+ * @param value - the address's value.
+ * @param namedValues - the source's named values.
+ */
+export declare const isValueOfProp: (prop: PanelProp, value: ArgValue, namedValues: NamedValues) => boolean;
+/**
+ * The address's values the story receives, and those left out with the reason.
+ *
+ * @param args - the values the address names.
+ * @param declaration - what the story declares.
+ */
+export declare const checkedAddressArgs: (args: PanelArgs, declaration: ArgDeclaration) => CheckedArgs;

package/dist/src/addressArgs.js

@@ -0,0 +1,109 @@
+import { panelProps, settableProps } from "./argTypes.js";
+import { isChoiceList, isNamedArg } from "./messages.js";
+import { namedValueOf } from "./namedValues.js";
+/** A prop made from one of the story's own args, for an arg neither the types nor the `argTypes` name. */
+const propOfStoryArg = (name, value) => {
+    const prop = { name, type: "", description: "", isRequired: false };
+    if (typeof value === "string")
+        return { ...prop, kind: "text" };
+    if (typeof value === "number")
+        return { ...prop, kind: "number" };
+    if (typeof value === "boolean")
+        return { ...prop, kind: "toggle" };
+    // a named value keeps the type it is offered for, so only another value named for it is taken
+    if (isNamedArg(value))
+        return { ...prop, kind: "other", type: value.of };
+    // a list's options and a `null`'s type are not known: nothing the address names is taken for them
+    return undefined;
+};
+/**
+ * The props the panel sets for a story, whatever the address says: the component's props with the `argTypes` over
+ * them and the args only the `argTypes` name, then the story's own args the two leave out, each kept only when the
+ * story's controls let the panel set it.
+ *
+ * @param declaration - what the story declares.
+ */
+export const declaredArgProps = (declaration) => {
+    const { props, argTypes, controls, storyArgs, namedValues } = declaration;
+    const named = new Set([...props.map((prop) => prop.name), ...Object.keys(argTypes)]);
+    const ownProps = Object.entries(storyArgs).flatMap(([name, value]) => {
+        if (named.has(name))
+            return [];
+        const prop = propOfStoryArg(name, value);
+        return prop === undefined ? [] : [prop];
+    });
+    return settableProps([...panelProps(props, argTypes), ...ownProps], controls, namedValues);
+};
+/** Whether a value is a finite number: what a number field sets (an address's JSON has no `NaN` anyway). */
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** Whether a value is one of a choice's options. */
+const isOption = (prop, value) => (typeof value === "string" || typeof value === "number") && (prop.choices ?? []).includes(value);
+/**
+ * Whether a value is one the panel could set for a prop: of the control the `argTypes` name, otherwise of the prop's
+ * kind.
+ *
+ * @param prop - a prop the panel sets.
+ * @param value - the address's value.
+ * @param namedValues - the source's named values.
+ */
+export const isValueOfProp = (prop, value, namedValues) => {
+    switch (prop.control) {
+        case "select":
+        case "radio":
+            return isOption(prop, value);
+        case "check":
+        case "multi-select":
+            return isChoiceList(value) && value.every((item) => isOption(prop, item));
+        case "boolean":
+            return typeof value === "boolean";
+        case "text":
+        case "color":
+            return typeof value === "string";
+        case "number":
+        case "range":
+        case "date":
+            return isFiniteNumber(value);
+        case "none":
+            return false;
+        case undefined:
+            break;
+    }
+    switch (prop.kind) {
+        case "choice":
+            return isOption(prop, value);
+        case "text":
+            return typeof value === "string";
+        case "number":
+            return isFiniteNumber(value);
+        case "toggle":
+            return typeof value === "boolean";
+        case "other":
+            if (isNamedArg(value)) {
+                return value.of === prop.type && namedValueOf(namedValues, value.of, value.named) !== undefined;
+            }
+            return prop.canTakeText === true && typeof value === "string";
+        case "event":
+            return false;
+    }
+};
+/**
+ * The address's values the story receives, and those left out with the reason.
+ *
+ * @param args - the values the address names.
+ * @param declaration - what the story declares.
+ */
+export const checkedAddressArgs = (args, declaration) => {
+    const declared = declaredArgProps(declaration);
+    const accepted = [];
+    const dropped = [];
+    for (const [name, value] of Object.entries(args)) {
+        const prop = declared.find((each) => each.name === name);
+        if (prop === undefined)
+            dropped.push({ name, reason: "undeclared" });
+        else if (!isValueOfProp(prop, value, declaration.namedValues))
+            dropped.push({ name, reason: "type" });
+        else
+            accepted.push([name, value]);
+    }
+    return { accepted: Object.fromEntries(accepted), dropped };
+};

package/dist/src/addressTexts.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The texts a catalogue's address may hand a story whose framework writes texts into markup: plain words only.
+ *
+ * @remarks
+ * A link shares the props panel's values in its address (`?args=`), so whoever writes the link chooses them, and the
+ * frame runs on the catalogue's own origin. React and Vue put a text into the page as text; a plain HTML story
+ * writes it into an HTML string (`<button class="${tone}">${label}</button>` in a template literal), where `<`, a
+ * quote or a `javascript:` address becomes markup or code. So for a framework that says its texts may become markup
+ * (`FrameworkAdapter.addressTexts`), a value the address carries reaches the story only when its name and its texts
+ * are plain: letters and digits of any script, spaces and a few marks that close no tag, attribute or address. The
+ * panel's own edits are the person's and are not checked; a link, or a reload of an edit with markup, falls back to
+ * the story's own value, as Storybook's address does. Pure.
+ *
+ * @module
+ */
+import { type PanelArgs } from "./messages.ts";
+/**
+ * How a framework's stories take the texts an address carries: `any` where a text stays text (React, Vue), `plain`
+ * where a story may write it into markup (an HTML string).
+ */
+export type AddressTexts = "any" | "plain";
+/**
+ * Whether a text can become nothing but text wherever an HTML string puts it: between tags, inside a quoted or bare
+ * attribute, as an address.
+ *
+ * @param text - the text.
+ */
+export declare const isPlainText: (text: string) => boolean;
+/**
+ * The address's values a story receives under a framework's rule: all of them, or only those whose texts are plain.
+ *
+ * @param args - the values the address names.
+ * @param addressTexts - the framework's rule.
+ */
+export declare const addressArgsFor: (args: PanelArgs, addressTexts: AddressTexts) => PanelArgs;

package/dist/src/addressTexts.js

@@ -0,0 +1,51 @@
+/**
+ * The texts a catalogue's address may hand a story whose framework writes texts into markup: plain words only.
+ *
+ * @remarks
+ * A link shares the props panel's values in its address (`?args=`), so whoever writes the link chooses them, and the
+ * frame runs on the catalogue's own origin. React and Vue put a text into the page as text; a plain HTML story
+ * writes it into an HTML string (`<button class="${tone}">${label}</button>` in a template literal), where `<`, a
+ * quote or a `javascript:` address becomes markup or code. So for a framework that says its texts may become markup
+ * (`FrameworkAdapter.addressTexts`), a value the address carries reaches the story only when its name and its texts
+ * are plain: letters and digits of any script, spaces and a few marks that close no tag, attribute or address. The
+ * panel's own edits are the person's and are not checked; a link, or a reload of an edit with markup, falls back to
+ * the story's own value, as Storybook's address does. Pure.
+ *
+ * @module
+ */
+import { isNamedArg } from "./messages.js";
+/** A plain text: letters, marks and digits of any script, spaces, and `_ . , ! ? # % + -`. */
+const PLAIN_TEXT = /^[\p{L}\p{M}\p{N} _.,!?#%+-]*$/u;
+/** A plain name: what a script and an attribute both write bare (`label`, `item-count`, `$size`). */
+const PLAIN_NAME = /^[A-Za-z_$][\w$-]*$/;
+/**
+ * Whether a text can become nothing but text wherever an HTML string puts it: between tags, inside a quoted or bare
+ * attribute, as an address.
+ *
+ * @param text - the text.
+ */
+export const isPlainText = (text) => PLAIN_TEXT.test(text);
+/**
+ * Whether an address's value can reach a story whose texts may become markup: every text in it plain. A named value is
+ * looked up among the source's own values, so its name is never written into the page.
+ *
+ * @param value - the value.
+ */
+const isPlainValue = (value) => {
+    if (typeof value === "string")
+        return isPlainText(value);
+    if (Array.isArray(value))
+        return value.every((item) => typeof item !== "string" || isPlainText(item));
+    return value === null || isNamedArg(value) || typeof value !== "object";
+};
+/**
+ * The address's values a story receives under a framework's rule: all of them, or only those whose texts are plain.
+ *
+ * @param args - the values the address names.
+ * @param addressTexts - the framework's rule.
+ */
+export const addressArgsFor = (args, addressTexts) => addressTexts === "any"
+    ? args
+    : Object.fromEntries(
+    // a name is checked too: a story that spreads its args into attributes writes it into the markup
+    Object.entries(args).filter(([name, value]) => PLAIN_NAME.test(name) && isPlainValue(value)));

package/dist/src/argTypes.d.ts

@@ -134,4 +134,3 @@ export declare const isPanelArgTypes: (value: unknown) => value is PanelArgTypes
  * @param argTypes - the merged `argTypes`.
  */
 export declare const actionNames: (args: Readonly<Record<string, unknown>>, argTypes: Readonly<Record<string, Readonly<Record<string, unknown>>>>) => readonly string[];
-//# sourceMappingURL=argTypes.d.ts.map

package/dist/src/argTypes.js

@@ -166,7 +166,8 @@ export const mappedArgs = (args, argTypes) => Object.fromEntries(Object.entries(
     if (!isRecord(mapping) || (typeof value !== "string" && typeof value !== "number"))
         return [name, value];
     const key = String(value);
-    return [name, key in mapping ? mapping[key] : value];
+    // the mapping's own keys only: a value a shared link chose (`constructor`) never reaches its prototype
+    return [name, Object.hasOwn(mapping, key) ? mapping[key] : value];
 }));
 /** The prop kind a control sets, for the panel's groups. */
 const KIND_OF_CONTROL = {
@@ -278,4 +279,3 @@ export const actionNames = (args, argTypes) => [
         ...Object.entries(argTypes).flatMap(([name, entry]) => typeof entry["action"] === "string" || entry["action"] === true ? [name] : [])
     ])
 ];
-//# sourceMappingURL=argTypes.js.map

package/dist/src/audiences.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Who a component's page is read by: the address's `audience` and a catalogue's default. Each audience is the same page
+ * reordered and filtered (`shell/audienceLayout.ts`), never a page of its own.
+ *
+ * @remarks
+ * `everyone` is the page as a catalogue that sets nothing has always drawn it. The list is short on purpose: each
+ * audience answers a different question of the page, and a catalogue renames one with `strings`. Pure, and read by the
+ * frame's `parseView` too, so it holds the ids and nothing else.
+ *
+ * @module
+ */
+/** Every audience, in the order the control lists them. */
+export declare const AUDIENCE_IDS: readonly ["everyone", "designer", "coder", "tester"];
+/** Who a component's page is read by. */
+export type AudienceId = (typeof AUDIENCE_IDS)[number];
+/** The audience of a catalogue that names none. */
+export declare const DEFAULT_AUDIENCE: AudienceId;

package/dist/src/audiences.js

@@ -0,0 +1,15 @@
+/**
+ * Who a component's page is read by: the address's `audience` and a catalogue's default. Each audience is the same page
+ * reordered and filtered (`shell/audienceLayout.ts`), never a page of its own.
+ *
+ * @remarks
+ * `everyone` is the page as a catalogue that sets nothing has always drawn it. The list is short on purpose: each
+ * audience answers a different question of the page, and a catalogue renames one with `strings`. Pure, and read by the
+ * frame's `parseView` too, so it holds the ids and nothing else.
+ *
+ * @module
+ */
+/** Every audience, in the order the control lists them. */
+export const AUDIENCE_IDS = ["everyone", "designer", "coder", "tester"];
+/** The audience of a catalogue that names none. */
+export const DEFAULT_AUDIENCE = "everyone";

package/dist/src/backdrops.d.ts

@@ -4,38 +4,49 @@
  * surface (a menu's or a popover's glass, its blur) does, which the page's plain colour hides.
  *
  * @remarks
- * Every picture is drawn here in CSS gradients and inline SVG: no image file, nothing fetched, nothing of the library
- * the catalogue shows, invented words only. The frame turns the chosen backdrop into a style sheet of its
- * own (`backdropSheet`) that replaces the `body` background its source sets, so the story's own layout and colours
- * are unchanged; the shell reads the backdrop's colour (`backdropColor`) for the box a story waits in while it loads.
- * The desktop pictures are fixed whatever the theme; the page of content follows the theme, as an app's page would.
- * With forced colours nothing is drawn: the system's palette decides the page. Pure.
+ * 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.
  *
  * @module
  */
-/** A backdrop as CSS, for one colour scheme. */
-export type BackdropLook = {
-    /** The colour under the pictures, which the box of a loading story waits on. */
-    readonly color: string;
-    /** The picture's layers, as the `background` shorthand writes them (image, position, size, repeat), top first. */
-    readonly layers: string;
+/** A value for each colour scheme: the light one's and the dark one's, the same when it does not follow the theme. */
+export type SchemePair = {
+    /** The value in the light scheme. */
+    readonly light: string;
+    /** The value in the dark scheme. */
+    readonly dark: string;
 };
-/** A drawn backdrop: its look in a light and a dark theme, the same look when it does not follow the theme. */
-export type DrawnBackdrop = {
-    /** The look in the light theme. */
-    readonly light: BackdropLook;
-    /** The look in the dark theme. */
-    readonly dark: BackdropLook;
-};
-/** A backdrop the View menu offers: its id (the address's `backdrop`), its name, its look. */
-export type Backdrop = {
+/** The ids of the backdrops Forgebook draws, as the address writes them. */
+export type BuiltInBackdropId = "checkerboard" | "gradient" | "lightDesktop" | "darkDesktop" | "content";
+/** One of Forgebook's backdrops: the frame draws its picture (`backdropPictures.ts`). */
+export type BuiltInBackdrop = {
+    /** Forgebook's own. */
+    readonly kind: "builtIn";
     /** Its id, as the address writes it (`checkerboard`). */
+    readonly id: BuiltInBackdropId;
+    /** Its name in the View menu. */
+    readonly label: string;
+    /** The colour under its picture, in each scheme. */
+    readonly colors: SchemePair;
+};
+/** A catalogue's own backdrop: a colour and the CSS layers over it, in each scheme. */
+export type OwnBackdrop = {
+    /** The catalogue's. */
+    readonly kind: "own";
+    /** Its id, as the address writes it. */
     readonly id: string;
     /** Its name in the View menu. */
     readonly label: string;
-    /** Its look in each scheme. */
-    readonly drawn: DrawnBackdrop;
+    /** The colour under its layers, in each scheme. */
+    readonly colors: SchemePair;
+    /** Its layers, as the `background` shorthand writes them (image, position, size, repeat), top first; `none` for none. */
+    readonly layers: SchemePair;
 };
+/** A backdrop the View menu offers. */
+export type Backdrop = BuiltInBackdrop | OwnBackdrop;
 /**
  * A catalogue's own backdrop, as its configuration writes it: a colour and, optionally, CSS layers over it, for the
  * light scheme and, when it differs, the dark one.
@@ -56,14 +67,16 @@ export type CustomBackdrop = {
         readonly layers?: string;
     };
 };
+/** The colour under each of Forgebook's pictures: the page of content's follows the theme, the others' do not. */
+export declare const BUILT_IN_COLORS: Readonly<Record<BuiltInBackdropId, SchemePair>>;
 /** The backdrops Forgebook draws, in the View menu's order: every one but the page's own colour. */
-export declare const BUILT_IN_BACKDROPS: readonly Backdrop[];
+export declare const BUILT_IN_BACKDROPS: readonly BuiltInBackdrop[];
 /**
- * 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 declare const customBackdrop: (custom: CustomBackdrop) => Backdrop;
+export declare const customBackdrop: (custom: CustomBackdrop) => OwnBackdrop;
 /**
  * The colour a backdrop is drawn on, which the box of a loading story waits on.
  *
@@ -72,17 +85,3 @@ export declare const customBackdrop: (custom: CustomBackdrop) => Backdrop;
  * @returns the CSS colour; none for the page's own colour.
  */
 export declare const backdropColor: (backdrop: Backdrop | undefined, isDark: boolean) => string | undefined;
-/**
- * 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 declare const backdropSheet: (backdrop: Backdrop | undefined, scheme: "light" | "dark" | "system") => string;
-//# sourceMappingURL=backdrops.d.ts.map