forgebook 0.1.8 → 0.3.0

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/argsProps.d.ts

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

package/dist/src/argsProps.js

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

package/dist/src/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