forgebook 0.1.8 → 0.3.0

package/dist/src/storyGlobals.js

@@ -76,7 +76,8 @@ export const fixedViewOf = (globals, parameters, catalogue) => {
  */
 export const withFixed = (view, fixed) => ({
     ...view,
-    switches: { ...view.switches, ...fixed.switches },
+    // the same object when the story fixes no switch: a new one would tell the frames of a view that did not change
+    switches: Object.keys(fixed.switches).length === 0 ? view.switches : { ...view.switches, ...fixed.switches },
     ...(fixed.backdrop === undefined ? {} : { backdrop: fixed.backdrop }),
     ...(fixed.width === undefined || view.width === undefined ? {} : { width: fixed.width })
 });
@@ -114,4 +115,3 @@ export const isFixedView = (value) => isRecord(value) &&
     Object.values(value["switches"]).every((switchValue) => typeof switchValue === "string") &&
     (value["backdrop"] === undefined || typeof value["backdrop"] === "string") &&
     (value["width"] === undefined || typeof value["width"] === "number");
-//# sourceMappingURL=storyGlobals.js.map

package/dist/src/storyHeights.d.ts

@@ -34,4 +34,3 @@ export declare const isStoryHeights: (value: unknown) => value is StoryHeights;
  * @returns the height in CSS px, or none when the story was not measured.
  */
 export declare const knownHeight: (document: StoryHeights | undefined, storyId: string, width: number) => number | undefined;
-//# sourceMappingURL=storyHeights.d.ts.map

package/dist/src/storyHeights.js

@@ -50,4 +50,3 @@ export const knownHeight = (document, storyId, width) => {
     });
     return heights[nearest];
 };
-//# sourceMappingURL=storyHeights.js.map

package/dist/src/storyIds.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Story and component ids as Storybook writes them, so an address, a link or a picture's name carries over from a
+ * Storybook catalogue unchanged.
+ *
+ * @remarks
+ * Storybook's id is its CSF rule: the meta's `id` (else its title) and the story's name made from its export, each
+ * lower-cased with every punctuation mark and space turned into one `-`, joined by `--`. The export's name is first
+ * split into words at its case changes, digits, `_`, `-` and `.` (`HTMLButton2X` → `HTML Button 2 X`); the title is
+ * not, so `Inputs/ReadMore` is `inputs-readmore`. The words also name a story that writes no name (`storyName`). Letters outside ASCII are kept, as Storybook keeps them. Pure, and
+ * small: the shell and every frame carry it.
+ *
+ * @module
+ */
+/**
+ * A text as an id's part, as Storybook's `sanitize`: lower case, each run of spaces and punctuation one `-`, none at
+ * either end.
+ *
+ * @param text - a title, a meta's `id` or a story's name.
+ * @returns the part; empty when the text has no letter or digit.
+ */
+export declare const idPart: (text: string) => string;
+/**
+ * The words of an export's name, as Storybook splits it to name a story: at `_`, `-`, `.`, at case changes and around
+ * digits, each word as written (`KeyboardOpen` → `Keyboard`, `Open`; `CustomSVGIcon` → `Custom`, `SVG`, `Icon`;
+ * `Size2X` → `Size`, `2`, `X`).
+ *
+ * @param exportName - the named export.
+ */
+export declare const exportWords: (exportName: string) => string[];
+/**
+ * A story's id as Storybook writes it, without a source: the component's part and the story's, joined by `--`.
+ *
+ * @param component - the meta's `id` when it writes one, else the title.
+ * @param exportName - the story's export.
+ */
+export declare const csfStoryId: (component: string, exportName: string) => string;

package/dist/src/storyIds.js

@@ -0,0 +1,52 @@
+/**
+ * Story and component ids as Storybook writes them, so an address, a link or a picture's name carries over from a
+ * Storybook catalogue unchanged.
+ *
+ * @remarks
+ * Storybook's id is its CSF rule: the meta's `id` (else its title) and the story's name made from its export, each
+ * lower-cased with every punctuation mark and space turned into one `-`, joined by `--`. The export's name is first
+ * split into words at its case changes, digits, `_`, `-` and `.` (`HTMLButton2X` → `HTML Button 2 X`); the title is
+ * not, so `Inputs/ReadMore` is `inputs-readmore`. The words also name a story that writes no name (`storyName`). Letters outside ASCII are kept, as Storybook keeps them. Pure, and
+ * small: the shell and every frame carry it.
+ *
+ * @module
+ */
+/** The characters Storybook's ids turn into `-`: spaces and punctuation, never letters or digits of any script. */
+const ID_PUNCTUATION = /[ ’–—―′¿'`~!@#$%^&*()_|+\-=?;:'",.<>{}[\]\\/]/g;
+/**
+ * A text as an id's part, as Storybook's `sanitize`: lower case, each run of spaces and punctuation one `-`, none at
+ * either end.
+ *
+ * @param text - a title, a meta's `id` or a story's name.
+ * @returns the part; empty when the text has no letter or digit.
+ */
+export const idPart = (text) => {
+    // after the runs are collapsed, each end holds one hyphen at most: sliced off, with no pattern anchored at the end
+    // that would slow on a long run
+    const collapsed = text.toLowerCase().replace(ID_PUNCTUATION, "-").replace(/-+/g, "-");
+    const start = collapsed.startsWith("-") ? 1 : 0;
+    const end = collapsed.endsWith("-") ? collapsed.length - 1 : collapsed.length;
+    return collapsed.slice(start, Math.max(start, end));
+};
+/**
+ * The words of an export's name, as Storybook splits it to name a story: at `_`, `-`, `.`, at case changes and around
+ * digits, each word as written (`KeyboardOpen` → `Keyboard`, `Open`; `CustomSVGIcon` → `Custom`, `SVG`, `Icon`;
+ * `Size2X` → `Size`, `2`, `X`).
+ *
+ * @param exportName - the named export.
+ */
+export const exportWords = (exportName) => exportName
+    .replace(/[_\-.]/g, " ")
+    .replace(/([^\n])([A-Z])([a-z])/g, "$1 $2$3")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/([a-z])([0-9])/gi, "$1 $2")
+    .replace(/([0-9])([a-z])/gi, "$1 $2")
+    .split(" ")
+    .filter((word) => word !== "");
+/**
+ * A story's id as Storybook writes it, without a source: the component's part and the story's, joined by `--`.
+ *
+ * @param component - the meta's `id` when it writes one, else the title.
+ * @param exportName - the story's export.
+ */
+export const csfStoryId = (component, exportName) => `${idPart(component)}--${idPart(exportWords(exportName).join(" "))}`;

package/dist/src/storyIdsElement.d.ts

@@ -6,4 +6,3 @@
  */
 /** The id of the `<script type="application/json">` that holds every story's id, in the sidebar's order. */
 export declare const STORY_IDS_ELEMENT = "forgebook-story-ids";
-//# sourceMappingURL=storyIdsElement.d.ts.map

package/dist/src/storyIdsElement.js

@@ -6,4 +6,3 @@
  */
 /** The id of the `<script type="application/json">` that holds every story's id, in the sidebar's order. */
 export const STORY_IDS_ELEMENT = "forgebook-story-ids";
-//# sourceMappingURL=storyIdsElement.js.map

package/dist/src/storyTexts.d.ts

@@ -5,11 +5,12 @@
  * @remarks
  * English is the table every key is in (`stories/locales/en.json`); a language that lacks a key shows the English
  * one, so a story is never empty while a translation is under way. An arg written `storyText("key")` becomes the text
- * of its key before the story receives it. Pure.
+ * of its key before the story receives it. A language a source gives as a loader is loaded when it is shown, and only
+ * then. Pure apart from those loaders.
  *
  * @module
  */
-import type { StoryLanguage, StorySource } from "@forgebook/story-format/source";
+import type { StoryLanguage, StorySource, StoryTexts } from "@forgebook/story-format/source";
 import { type StoryTextFunction, type StoryTextTable } from "@forgebook/story-format/texts";
 /** The language every key is in. */
 export declare const BASE_LANGUAGE = "en";
@@ -20,13 +21,19 @@ export declare const BASE_LANGUAGE = "en";
  * @param text - an English text.
  */
 export declare const pseudoText: (text: string) => string;
+/**
+ * A language's table, its loader awaited when the source gives one; empty for a language it has no texts in.
+ *
+ * @param texts - the language's texts in the source.
+ */
+export declare const textTable: (texts: StoryTexts | undefined) => Promise<StoryTextTable>;
 /**
  * The texts of the shown language.
  *
- * @param texts - the source's tables, by language id; none when the source has none.
+ * @param texts - the source's tables or their loaders, by language id; none when the source has none.
  * @param language - the shown language, when one is chosen; none for the stories' own (English).
  */
-export declare const shownTexts: (texts: StorySource["texts"], language: StoryLanguage | undefined) => StoryTextTable;
+export declare const shownTexts: (texts: StorySource["texts"], language: StoryLanguage | undefined) => Promise<StoryTextTable>;
 /**
  * A story's args with each `storyText("key")` turned into the text in the shown language, as the story receives them.
  *
@@ -40,4 +47,3 @@ export declare const withStoryTexts: (args: Readonly<Record<string, unknown>>, t
  * @param args - the story's args.
  */
 export declare const storyTextKeysOf: (args: Readonly<Record<string, unknown>>) => Readonly<Record<string, string>>;
-//# sourceMappingURL=storyTexts.d.ts.map

package/dist/src/storyTexts.js

@@ -35,20 +35,32 @@ export const pseudoText = (text) => {
     const padding = "·".repeat(Math.ceil(text.length / 3));
     return `[${accented}${padding}]`;
 };
+/**
+ * A language's table, its loader awaited when the source gives one; empty for a language it has no texts in.
+ *
+ * @param texts - the language's texts in the source.
+ */
+export const textTable = async (texts) => {
+    if (texts === undefined)
+        return {};
+    return typeof texts === "function" ? (await texts()).default : texts;
+};
 /**
  * The texts of the shown language.
  *
- * @param texts - the source's tables, by language id; none when the source has none.
+ * @param texts - the source's tables or their loaders, by language id; none when the source has none.
  * @param language - the shown language, when one is chosen; none for the stories' own (English).
  */
-export const shownTexts = (texts, language) => {
-    const base = texts?.[BASE_LANGUAGE] ?? {};
+export const shownTexts = async (texts, language) => {
+    // both at once: the shown language's table does not wait for English's
+    const shown = language === undefined || language.isPseudo === true ? undefined : texts?.[language.id];
+    const [base, own] = await Promise.all([textTable(texts?.[BASE_LANGUAGE]), textTable(shown)]);
     if (language === undefined)
         return base;
     if (language.isPseudo === true) {
         return Object.fromEntries(Object.entries(base).map(([key, text]) => [key, pseudoText(text)]));
     }
-    return { ...base, ...texts?.[language.id] };
+    return { ...base, ...own };
 };
 /**
  * A story's args with each `storyText("key")` turned into the text in the shown language, as the story receives them.
@@ -68,4 +80,3 @@ export const withStoryTexts = (args, text) => Object.values(args).some(isStoryTe
  * @param args - the story's args.
  */
 export const storyTextKeysOf = (args) => Object.fromEntries(Object.entries(args).flatMap(([name, value]) => isStoryTextArg(value) ? [[name, value.storyText]] : []));
-//# sourceMappingURL=storyTexts.js.map

package/dist/src/storyTree.d.ts

@@ -4,19 +4,24 @@
  *
  * @remarks
  * A story's place comes from its file's title (`Family/Name` or `Family/Group/Name`, or Storybook's titles of any
- * depth), so the sidebar needs no list kept by hand. Ids follow CSF: the title and the export name in lower-case kebab, joined by `--`, here prefixed by
- * the source's id, so two packages can hold the same title. A component its meta lists in other places (`alsoIn`)
- * gets an alias entry in each, and related components (`related`) name each other both ways: an alias is not
- * a component, so the stories, the ids and the tests stay one per file. Pure.
+ * depth), so the sidebar needs no list kept by hand. Files with the same title make one component, as Storybook merges
+ * them: its stories come from each file in the order of their paths, and its docs and page from the first. Ids are
+ * Storybook's (`storyIds.ts`), prefixed by the source's id so two packages can hold the same title; the ids an earlier
+ * rule gave (titles split at their case changes) still find their story, so old addresses keep working. A component
+ * its meta lists in other places (`alsoIn`) gets an alias entry in each, and related components (`related`) name each
+ * other both ways: an alias is not a component, so the stories, the ids and the tests stay one per story. Pure.
  *
  * @module
  */
-import type { StoryGroup } from "@forgebook/story-format/csf";
-import type { StoryBackground, StoryControlsSetting, StorySource } from "@forgebook/story-format/source";
+import type { RequiredFirst, StoryDeviceSetting, StoryGroup } from "@forgebook/story-format/csf";
+import type { FigmaLink, StoryBackground, StoryControlsSetting, StorySource } from "@forgebook/story-format/source";
+import { type TreePage } from "./pageTree.ts";
 /** One story in the tree. */
 export type TreeStory = {
-    /** `<source>:<title>--<export>` in kebab case: the URL's `story` parameter. */
+    /** `<source>:<component>--<story>`, the rest as Storybook's id (`storyId`): the URL's `story` parameter. */
     readonly id: string;
+    /** The story file it comes from, a key of the source's `index` and `stories`. */
+    readonly file: string;
     /** The name shown in the tabs. */
     readonly name: string;
     /** The named export. */
@@ -35,18 +40,39 @@ export type TreeStory = {
     readonly isLogic: boolean;
     /** The height its scene needs, in CSS px: its own `parameters.height`, else the meta's; none by default. */
     readonly height: number | undefined;
+    /** The device it is shown in by default (`parameters.device`), its own fields over the meta's; none when neither sets one. */
+    readonly device: StoryDeviceSetting | undefined;
+    /** Its design (`parameters.design.figma`): its own, else the meta's; none by default, nor when its own was refused. */
+    readonly design: FigmaLink | undefined;
+    /**
+     * Where its Props tab lists the required props (`parameters.requiredFirst`): its own, else its file's meta's; none
+     * when neither sets one, for the catalogue's.
+     */
+    readonly requiredFirst: RequiredFirst | undefined;
     /** Its tags, the meta's and its own (`!dev` keeps it out of the lists, `!test` out of the generated tests). */
     readonly tags: readonly string[];
+    /** Whether a `play` function acts on it. */
+    readonly hasPlay: boolean;
 };
-/** One component (one story file). */
+/** One component: the story files with its title. */
 export type TreeComponent = {
+    /**
+     * `<source>:<component>` (`componentId`), from its first file's meta: the part of its stories' ids before `--`, but
+     * for a later file whose meta writes another `id`, whose stories start with that one, as in Storybook.
+     */
+    readonly id: string;
     /** The last segment of the title (`Select`). */
     readonly name: string;
     /** The whole title (`Inputs/Selection/Select`). */
     readonly title: string;
-    /** The story file, a key of the source's `index` and `stories`. */
+    /**
+     * Its first story file, a key of the source's `index` and `stories`: the one its docs and its page come from, as
+     * Storybook's docs come from the first file of a title.
+     */
     readonly file: string;
-    /** Its stories the catalogue lists (the sidebar's count, the picker, the page), in the order of the file. */
+    /** Every story file with its title, in the order of their paths; `file` first. */
+    readonly files: readonly string[];
+    /** Its stories the catalogue lists (the sidebar's count, the picker, the page), in the order of the files. */
     readonly stories: readonly TreeStory[];
     /**
      * Its stories tagged `!dev`, as Storybook's: listed nowhere, still opened by their address and tested; empty when
@@ -62,6 +88,15 @@ export type TreeComponent = {
     readonly related: readonly string[];
     /** Other words the search finds it by, as the meta writes them; empty when none. */
     readonly keywords: readonly string[];
+    /** Its design: the meta's `parameters.design.figma`; none by default. */
+    readonly design: FigmaLink | undefined;
+    /** The prop groups its meta lists first (`parameters.propGroups`), in their order; empty when none. */
+    readonly propGroups: readonly string[];
+    /**
+     * Where its page lists the required props (its first file's meta's `parameters.requiredFirst`); none when it sets
+     * none, for the catalogue's.
+     */
+    readonly requiredFirst: RequiredFirst | undefined;
 };
 /** A group's entry for a component that lives elsewhere and is listed here too (the meta's `alsoIn`). */
 export type TreeAlias = {
@@ -101,37 +136,56 @@ export type TreeSource = {
     readonly background: StoryBackground | undefined;
     /** Its families, in the source's order, then alphabetically. */
     readonly families: readonly TreeFamily[];
+    /** Its docs pages: by `order`, the pages without one after, then by title. Empty when it has none. */
+    readonly pages: readonly TreePage[];
 };
-/** The tree, with what is wrong in the indexes (a title without a family, two files with the same title). */
+/** The tree, with what is wrong in the indexes (a title without a family, a story id used twice). */
 export type StoryTree = {
-    /** Every source with stories. */
+    /** Every source with stories or docs pages. */
     readonly sources: readonly TreeSource[];
-    /** One message per problem; the files concerned are left out of the tree. */
+    /** One message per problem; the files or stories concerned are left out of the tree. */
     readonly problems: readonly string[];
 };
 /**
- * A text in lower-case kebab case, as CSF writes ids: every run of other characters becomes one `-`.
+ * A text in lower-case kebab case, split at its case changes: the rule ids had before they followed Storybook's, kept
+ * to find a story by an id written then (`formerStoryId`).
  *
  * @param text - any text.
  */
 export declare const kebab: (text: string) => string;
 /**
- * A story's id.
+ * A story's id: the source's id, then Storybook's id of the story.
  *
  * @param sourceId - the source's id (`acme-ui`).
- * @param title - the file's title.
+ * @param component - the meta's `id` when it writes one, else the title.
  * @param exportName - the story's export.
  */
-export declare const storyId: (sourceId: string, title: string, exportName: string) => string;
+export declare const storyId: (sourceId: string, component: string, exportName: string) => string;
 /**
- * A component's id: its source and title, the part of its stories' ids before `--`.
+ * A component's id: its source and Storybook's id of the component, the part of its stories' ids before `--`.
  *
  * @param sourceId - the source's id (`acme-ui`).
- * @param title - the file's title.
+ * @param component - the meta's `id` when it writes one, else the title.
  */
-export declare const componentId: (sourceId: string, title: string) => string;
+export declare const componentId: (sourceId: string, component: string) => string;
 /**
- * A story's name from its export, in sentence case: `KeyboardOpen` → "Keyboard open", `Size2X` → "Size 2 x".
+ * The id a component had under the former rule (`kebab`), which an address written then still names.
+ *
+ * @param sourceId - the source's id.
+ * @param title - the component's title.
+ */
+export declare const formerComponentId: (sourceId: string, title: string) => string;
+/**
+ * The id a story had under the former rule (`kebab`), which an address written then still names.
+ *
+ * @param sourceId - the source's id.
+ * @param title - the component's title.
+ * @param exportName - the story's export.
+ */
+export declare const formerStoryId: (sourceId: string, title: string, exportName: string) => string;
+/**
+ * A story's name from its export: its words as Storybook splits them (`exportWords`), in sentence case, a word written
+ * in capitals kept so: `KeyboardOpen` → "Keyboard open", `CustomSVGIcon` → "Custom SVG icon", `Size2X` → "Size 2 X".
  *
  * @param exportName - the named export.
  */
@@ -177,7 +231,8 @@ export declare const storyLocations: (tree: StoryTree) => StoryLocation[];
  */
 export declare const testedStoryLocations: (tree: StoryTree) => StoryLocation[];
 /**
- * Where a story sits.
+ * Where a story sits: the story with this id, else the one an earlier rule gave this id (`formerStoryId`), so an
+ * address written then still opens it.
  *
  * @param tree - the tree.
  * @param id - the story's id.
@@ -187,13 +242,23 @@ export declare const findStory: (tree: StoryTree, id: string) => StoryLocation |
 /** Where a component sits: its source, family and group. */
 export type ComponentLocation = Omit<StoryLocation, "story">;
 /**
- * Where a component sits.
+ * Where a component sits: the component with this id, else the one an earlier rule gave this id (its title in
+ * `kebab`), so an address written then still opens it.
  *
  * @param tree - the tree.
- * @param id - the component's id (`componentId`).
+ * @param id - the component's id (`TreeComponent.id`).
  * @returns its place, or `undefined` when no component has this id.
  */
 export declare const findComponent: (tree: StoryTree, id: string) => ComponentLocation | undefined;
+/**
+ * Where the component with a title sits, in one source: what a meta's `related` or `alsoIn`, or "Used in", names.
+ *
+ * @param tree - the tree.
+ * @param sourceId - the source's id.
+ * @param title - the component's title.
+ * @returns its place, or `undefined` when the source has no component with this title.
+ */
+export declare const findComponentByTitle: (tree: StoryTree, sourceId: string, title: string) => ComponentLocation | undefined;
 /** A component's stories under one group heading in the sidebar. */
 export type StoryGroupSection = {
     /** The group; none for the stories above the groups. */
@@ -223,4 +288,3 @@ export declare const sidebarStoryIds: (tree: StoryTree, order: readonly string[]
  * @param component - the component.
  */
 export declare const mainStory: (component: TreeComponent) => TreeStory | undefined;
-//# sourceMappingURL=storyTree.d.ts.map