forgebook 0.1.8 → 0.3.0

package/dist/src/vite/hotSnippets.js

@@ -0,0 +1,172 @@
+import { codeLiteral } from "../codeLiteral.js";
+import { RENEWED_MODULE_EVENT, STORY_FILE_EVENT } from "../hotModules.js";
+import { STORY_FILE } from "./autoTitle.js";
+import { FILES_PREFIX } from "./pluginModules.js";
+import { storyFileIndex, storyFilesGroupOf } from "./storyFilesModule.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** The id of a module a plugin makes, which names no file. */
+const VIRTUAL_ID = /^\0/;
+/**
+ * What a story file runs to accept its edit: the frame that draws its stories cancels the event and draws them anew;
+ * when none does, the files that import it take the edit (one that re-exports its stories draws them). The exports the
+ * page drew are kept in the module's hot data, so the version after one that threw while it loaded is matched with
+ * them, not with the version that failed.
+ *
+ * @param file - the story file's path, which it imports itself by.
+ */
+export const storyFileHot = (file) => [
+    `import * as __forgebookShown from ${codeLiteral(file)};`,
+    "if (import.meta.hot) {",
+    // what the page drew, kept across versions: one that threw while it loaded drew nothing
+    "  import.meta.hot.data.forgebookShown ??= __forgebookShown;",
+    "  import.meta.hot.accept((next) => {",
+    "    if (next === undefined) return;",
+    `    const event = new CustomEvent(${codeLiteral(STORY_FILE_EVENT)}, {`,
+    "      cancelable: true,",
+    "      detail: { previous: import.meta.hot.data.forgebookShown, next }",
+    "    });",
+    "    if (window.dispatchEvent(event)) import.meta.hot.invalidate();",
+    "    else import.meta.hot.data.forgebookShown = next;",
+    "  });",
+    "}"
+].join(" ");
+/**
+ * A file's head: its leading comments and its directive prologue (`"use client";`), in any order. The directives must
+ * stay its first statements, and the comments hold the pragmas a compiler reads only before the first statement
+ * (`@jsxImportSource`, `@jsxRuntime`): after added code, a file written for another JSX runtime compiles for React's.
+ */
+const HEAD = /^(?:\s*(?:\/\/[^\n\r\u2028\u2029]*(?:\r\n|[\n\r\u2028\u2029]|$)|\/\*[\s\S]*?\*\/|(["'])use [^"']*\1;?))*/;
+/** What ends a line, and so a line comment, in JavaScript. */
+const LINE_END = /[\n\r\u2028\u2029]$/;
+/**
+ * A story file's code with its accepting code first: it runs before the file's own, so an edit that throws while the
+ * file loads still leaves the next one accepted. After the file's head and on its last line, so no line of the file
+ * moves and its source map stays true.
+ *
+ * @param code - the file's code, as the plugins before have made it.
+ * @param id - the file's path.
+ */
+export const withStoryFileHot = (code, id) => {
+    const head = HEAD.exec(code)?.[0] ?? "";
+    // a file that is all head may end in a line comment, which would take the code in: it goes on a line of its own
+    let separator = " ";
+    if (head === "" || LINE_END.test(head))
+        separator = "";
+    else if (head.length === code.length)
+        separator = "\n";
+    return `${head}${separator}${storyFileHot(id)} ${code.slice(head.length)}`;
+};
+/**
+ * What a story file's docs, code or page module runs to hand its new default export to the shell that read the old one.
+ *
+ * @param id - the module's id, which it imports itself by.
+ */
+export const renewedModuleHot = (id) => [
+    `import * as __forgebookRenewed from ${codeLiteral(id)};`,
+    "if (import.meta.hot) {",
+    "  import.meta.hot.accept((next) => {",
+    "    if (next === undefined) return;",
+    `    window.dispatchEvent(new CustomEvent(${codeLiteral(RENEWED_MODULE_EVENT)}, {`,
+    "      detail: { previous: __forgebookRenewed.default, next: next.default }",
+    "    }));",
+    "  });",
+    "}"
+].join("\n");
+/**
+ * A module as a dev server serves it: a story file's docs, code or page module hands its edit to the shell.
+ *
+ * @param id - the module's id.
+ * @param module - the module.
+ * @param queries - the queries of the modules that hand their edits on.
+ * @param isServing - whether a dev server serves it: a build has no hot updates.
+ */
+export const renewedModule = (id, module, queries, isServing) => isServing && queries.some((query) => id.endsWith(query))
+    ? { ...module, code: `${module.code}\n${renewedModuleHot(id)}` }
+    : module;
+/**
+ * What a pattern's files module runs: it takes the edits its story files hand on, which change nothing it holds. An
+ * edit that changes its list reloads the pages from the server, and its pages keep the module they read.
+ */
+export const FILES_MODULE_HOT = "if (import.meta.hot) import.meta.hot.accept();";
+/**
+ * A story file's index as an edit left it; a message when it cannot be read (an editor writes it anew in place).
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param key - the file's path relative to the declaring module.
+ */
+const readIndex = (root, pattern, key) => {
+    try {
+        return storyFileIndex(root, pattern, key);
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+};
+/** The patterns' modules a dev server serves, kept to tell an edit that changes a list. */
+export const servedPatterns = () => {
+    // by group, each story file as served: its key, the pattern that lists it, its index
+    const served = new Map();
+    return {
+        keep: (id, files) => {
+            served.set(id, new Map(files.map((file) => [
+                file.file,
+                { key: file.key, pattern: file.pattern, index: JSON.stringify(file.index) }
+            ])));
+        },
+        changedBy: (file) => [...served]
+            .filter(([id, files]) => {
+            // in Vite's form, as the served files are kept: a Windows path reaches here either way
+            const kept = files.get(VITE_PATHS.normalize(file));
+            if (kept === undefined)
+                return false;
+            const { root } = storyFilesGroupOf(id.slice(FILES_PREFIX.length));
+            const index = readIndex(root, kept.pattern, kept.key);
+            return typeof index !== "string" && JSON.stringify(index) !== kept.index;
+        })
+            .map(([id]) => id)
+    };
+};
+/**
+ * The plugin's hooks for a story file's edit: the file accepts it on a dev server, and an edit that changes a pattern's
+ * list (a story added, renamed, a title) reloads the pages, which read the list once. A story file a frame loads is
+ * followed closely (`closeWatch.ts`), and the late report of an edit of any file the close watch handed on already is
+ * dropped, so an edit is drawn once.
+ *
+ * @param isServing - whether a dev server runs whose framework draws an edited story file in place.
+ * @param changedFilesModules - the patterns' modules the edit changed.
+ * @param watching - the dev server's close watch.
+ */
+export const storyFileHotHooks = (isServing, changedFilesModules, watching) => ({
+    transform: {
+        // a pattern's module is named after its pattern, which may end like a story file
+        filter: { id: { include: STORY_FILE, exclude: VIRTUAL_ID } },
+        handler(code, id) {
+            if (!isServing() || this.environment.name !== "client")
+                return undefined;
+            watching.follow(id);
+            return { code: withStoryFileHot(code, id), map: null };
+        }
+    },
+    hotUpdate(options) {
+        // a file removed or added changes the lists another way (`modulesListing`)
+        if (options.type !== "update")
+            return undefined;
+        // the system's late report of an edit the close watch handed on already
+        if (watching.isLateReport(this.environment.name, options.file))
+            return [];
+        if (this.environment.name !== "client" || !STORY_FILE.test(options.file))
+            return undefined;
+        const changed = changedFilesModules(options.file);
+        if (changed.length === 0)
+            return undefined;
+        const graph = this.environment.moduleGraph;
+        for (const id of changed) {
+            const module = graph.getModuleById(id);
+            if (module !== undefined)
+                graph.invalidateModule(module);
+        }
+        this.environment.hot.send({ type: "full-reload" });
+        return [];
+    }
+});

package/dist/src/vite/indexFields.d.ts

@@ -0,0 +1,61 @@
+/**
+ * What a story file's index reads of a meta's or a story's fields: each setting as written, `undefined` when it is
+ * missing or left to the frame, an `Error` when it cannot stand, and for a design a note when it is left out.
+ * `indexStoryFile` says which settings are which.
+ *
+ * @module
+ */
+import type { StoryGroup } from "@forgebook/story-format/csf";
+import type { FigmaLink, StoryControlsSetting } from "@forgebook/story-format/source";
+import type { ESTree } from "vite";
+/** A story's or a meta's fields by name: an object's properties, or a function story's assigned properties. */
+export type Fields = (name: string) => ESTree.Expression | undefined;
+/**
+ * An expression without the TypeScript wrappers a meta is often written with (`satisfies Meta<…>`, `as Meta`).
+ *
+ * @param expression - the expression.
+ */
+export declare const unwrapped: (expression: ESTree.Expression) => ESTree.Expression;
+/** A property key's name: an identifier's or a literal's; `undefined` for any other key. */
+export declare const keyName: (key: ESTree.PropertyKey) => string | undefined;
+/**
+ * The value of an object's property written plainly (a name or a string as its key), its TypeScript wrappers removed.
+ *
+ * @param object - the object.
+ * @param name - the property's name.
+ */
+export declare const propertyValue: (object: ESTree.ObjectExpression, name: string) => ESTree.Expression | undefined;
+/** An object's fields. */
+export declare const objectFields: (object: ESTree.ObjectExpression) => Fields;
+/** A field's value when it is a plain string; `undefined` when it is missing or written by code. */
+export declare const stringField: (fields: Fields, name: string) => string | undefined;
+/** A field of the `parameters` object, when the fields write one as an object. */
+export declare const parameter: (fields: Fields, name: string) => ESTree.Expression | undefined;
+/**
+ * `parameters.controls`: `undefined` when none or written by code, `[]` for `false`, the names of a list, or a
+ * problem when written plainly but wrongly.
+ */
+export declare const controlsOf: (fields: Fields) => StoryControlsSetting | undefined | Error;
+/** A list of plain strings: `undefined` when none or written by code, the strings, or a problem when it is wrong. */
+export declare const stringListOf: (fields: Fields, name: string) => readonly string[] | undefined | Error;
+/** `parameters.group`: `undefined` when none or written by code, the group, or a problem when it is wrong. */
+export declare const groupOf: (fields: Fields) => StoryGroup | undefined | Error;
+/**
+ * `parameters.propGroups`, read by the index only since a component's API reference is drawn before any story runs:
+ * `undefined` when none, the names, or a problem when it is not a list of plain strings. Written by code it would be
+ * lost, since the frame does not read it.
+ */
+export declare const propGroupsOf: (fields: Fields) => readonly string[] | undefined | Error;
+/** `parameters.height`: `undefined` when none or written by code, the height in CSS px, or a problem when wrong. */
+export declare const heightOf: (fields: Fields) => number | undefined | Error;
+/**
+ * `parameters.design`, read by the index only since the shell offers the Design tab before any story runs. A design
+ * with no `figma`, or not written as an object, is left alone: it may be another tool's (Storybook's design addon uses
+ * the same parameter).
+ *
+ * @returns the checked link; `undefined` for none; a message when the link is not a Figma file's, which the file's
+ * notes carry while the file keeps its stories and the pages never see the link; an `Error` when it is written by code.
+ */
+export declare const designOf: (fields: Fields) => FigmaLink | undefined | string | Error;
+/** `parameters.docs.description.<kind>`, when written as a plain string. */
+export declare const docsDescription: (fields: Fields, kind: "story" | "component") => string | undefined;

package/dist/src/vite/indexFields.js

@@ -0,0 +1,149 @@
+/**
+ * What a story file's index reads of a meta's or a story's fields: each setting as written, `undefined` when it is
+ * missing or left to the frame, an `Error` when it cannot stand, and for a design a note when it is left out.
+ * `indexStoryFile` says which settings are which.
+ *
+ * @module
+ */
+import { figmaLink } from "./figmaLink.js";
+/**
+ * An expression without the TypeScript wrappers a meta is often written with (`satisfies Meta<…>`, `as Meta`).
+ *
+ * @param expression - the expression.
+ */
+export const unwrapped = (expression) => {
+    if (expression.type === "TSSatisfiesExpression" ||
+        expression.type === "TSAsExpression" ||
+        expression.type === "ParenthesizedExpression") {
+        return unwrapped(expression.expression);
+    }
+    return expression;
+};
+/** A property key's name: an identifier's or a literal's; `undefined` for any other key. */
+export const keyName = (key) => {
+    if (key.type === "Identifier")
+        return key.name;
+    return key.type === "Literal" ? String(key.value) : undefined;
+};
+/**
+ * The value of an object's property written plainly (a name or a string as its key), its TypeScript wrappers removed.
+ *
+ * @param object - the object.
+ * @param name - the property's name.
+ */
+export const propertyValue = (object, name) => {
+    for (const property of object.properties) {
+        if (property.type !== "Property" || property.computed)
+            continue;
+        if (keyName(property.key) === name)
+            return unwrapped(property.value);
+    }
+    return undefined;
+};
+/** An object's fields. */
+export const objectFields = (object) => (name) => propertyValue(object, name);
+/** Whether an expression is written plainly: a literal, or a list of literals; anything else is written by code. */
+const isPlain = (expression) => expression.type === "Literal" ||
+    (expression.type === "ArrayExpression" &&
+        expression.elements.every((element) => element !== null && element.type === "Literal"));
+/** A field's value when it is a plain string; `undefined` when it is missing or written by code. */
+export const stringField = (fields, name) => {
+    const value = fields(name);
+    return value?.type === "Literal" && typeof value.value === "string" ? value.value : undefined;
+};
+/** A field of the `parameters` object, when the fields write one as an object. */
+export const parameter = (fields, name) => {
+    const parameters = fields("parameters");
+    return parameters?.type === "ObjectExpression" ? propertyValue(parameters, name) : undefined;
+};
+/** Why `parameters.controls` cannot be read. */
+const CONTROLS_PROBLEM = "`parameters.controls` must be written as `false` or a list of plain strings";
+/**
+ * `parameters.controls`: `undefined` when none or written by code, `[]` for `false`, the names of a list, or a
+ * problem when written plainly but wrongly.
+ */
+export const controlsOf = (fields) => {
+    const controls = parameter(fields, "controls");
+    if (controls === undefined || !isPlain(controls))
+        return undefined;
+    if (controls.type === "Literal" && controls.value === false)
+        return [];
+    if (controls.type !== "ArrayExpression")
+        return new Error(CONTROLS_PROBLEM);
+    const names = controls.elements.flatMap((element) => element?.type === "Literal" && typeof element.value === "string" ? [element.value] : []);
+    return names.length === controls.elements.length ? names : new Error(CONTROLS_PROBLEM);
+};
+/** A list of plain strings: `undefined` when none or written by code, the strings, or a problem when it is wrong. */
+export const stringListOf = (fields, name) => {
+    const list = fields(name);
+    if (list === undefined || !isPlain(list))
+        return undefined;
+    if (list.type !== "ArrayExpression")
+        return new Error(`\`${name}\` must be written as a list of plain strings`);
+    const strings = list.elements.flatMap((element) => element?.type === "Literal" && typeof element.value === "string" ? [element.value] : []);
+    return strings.length === list.elements.length
+        ? strings
+        : new Error(`\`${name}\` must be written as a list of plain strings`);
+};
+/** `parameters.group`: `undefined` when none or written by code, the group, or a problem when it is wrong. */
+export const groupOf = (fields) => {
+    const group = parameter(fields, "group");
+    if (group === undefined || !isPlain(group))
+        return undefined;
+    if (group.type === "Literal" && typeof group.value === "string" && group.value !== "")
+        return group.value;
+    return new Error("`parameters.group` must be written as a plain string");
+};
+/**
+ * `parameters.propGroups`, read by the index only since a component's API reference is drawn before any story runs:
+ * `undefined` when none, the names, or a problem when it is not a list of plain strings. Written by code it would be
+ * lost, since the frame does not read it.
+ */
+export const propGroupsOf = (fields) => {
+    const groups = parameter(fields, "propGroups");
+    if (groups === undefined)
+        return undefined;
+    const names = groups.type === "ArrayExpression"
+        ? groups.elements.flatMap((element) => element?.type === "Literal" && typeof element.value === "string" ? [element.value] : [])
+        : [];
+    return groups.type === "ArrayExpression" && names.length === groups.elements.length
+        ? names
+        : new Error("`parameters.propGroups` must be written as a list of plain strings");
+};
+/** `parameters.height`: `undefined` when none or written by code, the height in CSS px, or a problem when wrong. */
+export const heightOf = (fields) => {
+    const height = parameter(fields, "height");
+    if (height === undefined || !isPlain(height))
+        return undefined;
+    if (height.type === "Literal" && typeof height.value === "number" && height.value > 0)
+        return height.value;
+    return new Error("`parameters.height` must be written as a plain positive number of CSS px");
+};
+/**
+ * `parameters.design`, read by the index only since the shell offers the Design tab before any story runs. A design
+ * with no `figma`, or not written as an object, is left alone: it may be another tool's (Storybook's design addon uses
+ * the same parameter).
+ *
+ * @returns the checked link; `undefined` for none; a message when the link is not a Figma file's, which the file's
+ * notes carry while the file keeps its stories and the pages never see the link; an `Error` when it is written by code.
+ */
+export const designOf = (fields) => {
+    const design = parameter(fields, "design");
+    const figma = design?.type === "ObjectExpression" ? propertyValue(design, "figma") : undefined;
+    if (figma === undefined)
+        return undefined;
+    if (figma.type !== "Literal" || typeof figma.value !== "string") {
+        return new Error("`parameters.design.figma` must be written as a plain string");
+    }
+    const link = figmaLink(figma.value);
+    return typeof link === "string" ? `\`parameters.design.figma\`: ${link}` : link;
+};
+/** `parameters.docs.description.<kind>`, when written as a plain string. */
+export const docsDescription = (fields, kind) => {
+    const docs = parameter(fields, "docs");
+    const description = docs?.type === "ObjectExpression" ? propertyValue(docs, "description") : undefined;
+    if (description?.type !== "ObjectExpression")
+        return undefined;
+    const text = propertyValue(description, kind);
+    return text?.type === "Literal" && typeof text.value === "string" ? text.value : undefined;
+};

package/dist/src/vite/indexStoryFile.d.ts

@@ -4,39 +4,41 @@
  *
  * @remarks
  * The sidebar lists every story before any is loaded, so the index comes from the code itself, parsed with Vite's
- * parser (the same files Vite compiles). It reads a meta written inline or as a constant (`export default meta`), a
- * story as an object (CSF 3) or as a function with its properties assigned after it (CSF 2: `A.storyName`,
- * `A.parameters`), named exports and re-exports (`export { A as B }`), `includeStories`, `excludeStories`,
- * `__namedExportsOrder`, the meta's and the stories' `tags`, the TSDoc above a story, and `parameters.docs.description`.
+ * parser (the same files Vite compiles). It reads a meta written inline or as a constant (`export default meta`,
+ * `export { meta as default }`), `includeStories`, `excludeStories`, `__namedExportsOrder`, the meta's and the
+ * stories' `tags`, the TSDoc above a story, and `parameters.docs.description`.
+ *
+ * Every named export the meta lets in is a story, as Storybook's indexer has it, whatever writes its value: an object
+ * (CSF 3), a function with its properties assigned after it (CSF 2: `A.storyName`, `A.parameters`), a template bound
+ * into a story, a helper's result (`makeStory(…)`), another constant (`export const B = A`), a re-export
+ * (`export { A as B }`, from this file or another). The fields come from the object a value is or names, and from what
+ * is assigned to the export; anything else is the frame's to read when the story loads. Only what does not exist when
+ * the file runs is left out: `export type`, and `export *`, whose names Storybook does not list either.
  *
  * A value the index needs (the title, a name, `parameters.controls`, `group`, `height`, `main`, the meta's `alsoIn`,
  * `related`, `keywords`) is read when written plainly; written by code, it is left to the frame, which reads it when
- * the story loads. `touch` and `logic` are read by the index only, so written by code they are a problem. A title written by code, or none, is the file's path (`autoTitle`, as Storybook's auto-title); one
- * written by code is also noted, since the author meant another. A value written plainly but wrongly
+ * the story loads. `touch`, `logic`, `device`, `requiredFirst`, `design.figma` and the meta's `propGroups` are read by
+ * the index only (`indexedParameters.ts`, `indexFields.ts`), so written by code they are a problem.
+ * A `design.figma` is checked here too, so the pages never carry the checker: one that is not a link to a Figma file is
+ * noted and left out, and the file keeps its stories. A title written by code, or none, is the file's path
+ * (`autoTitle`, as Storybook's auto-title); one written by code is also noted, since the author meant another. A value written plainly but wrongly
  * (`controls: true`) is a problem. Pure: text in, index or problem out.
  *
  * @module
  */
 import type { StoryFileIndex } from "@forgebook/story-format/source";
-import { type ESTree } from "vite";
+import type { ESTree } from "vite";
 /** What the index is given besides the file: the title its path makes, for a meta that writes none. */
 export type IndexOptions = {
     /** The title from the file's path (`Inputs/Select`); none when the file's place gives none. */
     readonly autoTitle?: string;
 };
 /**
- * An expression without the TypeScript wrappers a meta is often written with (`satisfies Meta<…>`, `as Meta`).
- *
- * @param expression - the expression.
- */
-export declare const unwrapped: (expression: ESTree.Expression) => ESTree.Expression;
-/**
- * The value of an object's property written plainly (a name or a string as its key), its TypeScript wrappers removed.
+ * A story file's meta object, as the index reads it: inline or a constant of the file, exported by default or by name.
  *
- * @param object - the object.
- * @param name - the property's name.
+ * @param program - the parsed file.
  */
-export declare const propertyValue: (object: ESTree.ObjectExpression, name: string) => ESTree.Expression | undefined;
+export declare const storyFileMeta: (program: ESTree.Program) => ESTree.ObjectExpression | undefined;
 /**
  * The index of one story file.
  *
@@ -46,4 +48,3 @@ export declare const propertyValue: (object: ESTree.ObjectExpression, name: stri
  * @returns the title and the stories, or a message saying why the file cannot be indexed.
  */
 export declare const indexStoryFile: (file: string, text: string, options?: IndexOptions) => StoryFileIndex | string;
-//# sourceMappingURL=indexStoryFile.d.ts.map