forgebook 0.1.8 → 0.3.0

package/dist/src/vite/indexStoryFile.js

@@ -4,158 +4,33 @@
  *
  * @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 { parseSync } from "vite";
-/**
- * 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. */
-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. */
-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. */
-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. */
-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.
- */
-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. */
-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. */
-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");
-};
-/**
- * A boolean parameter only the index reads (`touch`, `logic`): `true` or `false` written plainly, `undefined` when
- * none, or a problem otherwise. Written by code it would be lost, since the frame does not read it.
- *
- * @param fields - the story's or the meta's fields.
- * @param name - the parameter's name.
- */
-const booleanParameter = (fields, name) => {
-    const value = parameter(fields, name);
-    if (value === undefined)
-        return undefined;
-    if (value.type === "Literal" && typeof value.value === "boolean")
-        return value.value;
-    return new Error(`\`parameters.${name}\` must be written as a plain \`true\` or \`false\``);
-};
-/**
- * The flags a meta or a story sets (`touch`, `logic`), as the index keeps them: each only when written, or a problem.
- *
- * @param fields - the story's or the meta's fields.
- */
-const flagsOf = (fields) => {
-    const touch = booleanParameter(fields, "touch");
-    if (touch instanceof Error)
-        return touch;
-    const logic = booleanParameter(fields, "logic");
-    if (logic instanceof Error)
-        return logic;
-    return {
-        ...(touch === undefined ? {} : { isTouch: touch }),
-        ...(logic === undefined ? {} : { isLogic: logic })
-    };
-};
-/** `parameters.height`: `undefined` when none or written by code, the height in CSS px, or a problem when wrong. */
-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.docs.description.<kind>`, when written as a plain string. */
-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;
-};
+import { indexedParameters } from "./indexedParameters.js";
+import { controlsOf, designOf, docsDescription, groupOf, heightOf, objectFields, parameter, propertyValue, propGroupsOf, stringField, stringListOf, unwrapped } from "./indexFields.js";
+import { moduleName, namedExports } from "./storyExports.js";
+import { parseStoryFile } from "./storyParse.js";
+import { playField } from "./storyPlay.js";
 /**
  * The first sentence of the TSDoc right above a statement, without its tags; `undefined` when there is none.
  *
@@ -200,14 +75,39 @@ const combinedTags = (lists) => {
     return [...tags];
 };
 /**
- * What the index reads of one story: its name (`name`, or CSF 2's `storyName`), controls, group, height, whether it is
- * the demo, and its tags under the meta's.
+ * A story's own design as the index keeps it: a refused link stays as `null`, since the story meant to replace the
+ * meta's design, not to take it.
+ *
+ * @param design - the design, as `designOf` read it.
+ */
+const storyDesign = (design) => {
+    if (design === undefined)
+        return {};
+    return { design: typeof design === "string" ? null : design };
+};
+/**
+ * What a story's own object and assignments say of who it is: its id (`parameters.__id`, read by Storybook only when
+ * written plainly) and its name (`name`, or CSF 2's `storyName`).
  *
- * @param fields - the story's fields.
+ * @param own - the story's own fields.
+ */
+const identityOf = (own) => {
+    const name = stringField(own, "name") ?? stringField(own, "storyName");
+    const id = parameter(own, "__id");
+    return {
+        ...(id?.type === "Literal" && typeof id.value === "string" ? { id: id.value } : {}),
+        ...(name === undefined ? {} : { name })
+    };
+};
+/**
+ * What the index reads of one story: its own id (`parameters.__id`), its name (`name`, or CSF 2's `storyName`),
+ * controls, group, height, design, whether it is the demo, and its tags under the meta's.
+ *
+ * @param fields - the story's fields: its own, for its name and id, and all it has, for the rest.
  * @param metaTags - the meta's tags.
+ * @param notes - the file's notes, which a design left out adds to.
  */
-const storyFields = (fields, metaTags) => {
-    const name = stringField(fields, "name") ?? stringField(fields, "storyName");
+const storyFields = ({ own, fields }, metaTags, notes) => {
     const controls = controlsOf(fields);
     if (controls instanceof Error)
         return controls;
@@ -217,29 +117,30 @@ const storyFields = (fields, metaTags) => {
     const height = heightOf(fields);
     if (height instanceof Error)
         return height;
+    const design = designOf(fields);
+    if (design instanceof Error)
+        return design;
+    if (typeof design === "string")
+        notes.push(design);
     const ownTags = stringListOf(fields, "tags");
     if (ownTags instanceof Error)
         return ownTags;
     const tags = combinedTags([metaTags, ownTags]);
     const main = parameter(fields, "main");
-    const flags = flagsOf(fields);
+    const flags = indexedParameters(fields);
     if (flags instanceof Error)
         return flags;
     return {
-        ...(name === undefined ? {} : { name }),
+        ...identityOf(own),
         ...(controls === undefined ? {} : { controls }),
         ...(group === undefined ? {} : { group }),
         ...(height === undefined ? {} : { height }),
+        ...storyDesign(design),
         ...(main?.type === "Literal" && main.value === true ? { isMain: true } : {}),
         ...flags,
         ...(tags.length > 0 ? { tags } : {})
     };
 };
-/** Whether an expression binds a template into a story function (`Template.bind({})`). */
-const isBoundTemplate = (value) => value.type === "CallExpression" &&
-    value.callee.type === "MemberExpression" &&
-    value.callee.property.type === "Identifier" &&
-    value.callee.property.name === "bind";
 /**
  * The property a top-level statement assigns to a name, when it assigns one.
  *
@@ -257,36 +158,27 @@ const assignedProperty = (statement) => {
     return { name: object.name, property: property.name, value: unwrapped(expression.right) };
 };
 /**
- * The names a top-level statement declares, exported or not: its constants with a value, its function.
+ * The constants a top-level statement declares with a value, exported or not.
  *
  * @param statement - the statement.
  */
 const declaredBy = (statement) => {
     const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
-    if (declaration?.type === "FunctionDeclaration" && declaration.id !== null)
-        return [{ kind: "function", name: declaration.id.name, value: declaration }];
     if (declaration?.type !== "VariableDeclaration")
         return [];
-    return declaration.declarations.flatMap(({ id, init }) => id.type === "Identifier" && init !== null
-        ? [{ kind: "value", name: id.name, value: unwrapped(init) }]
-        : []);
+    return declaration.declarations.flatMap(({ id, init }) => id.type === "Identifier" && init !== null ? [{ name: id.name, value: unwrapped(init) }] : []);
 };
 /**
- * The file's top level: its constants and functions, exported or not, and the properties assigned to them.
+ * The file's top level: its constants, exported or not, and the properties assigned to names.
  *
  * @param program - the parsed file.
  */
 const topLevelOf = (program) => {
     const values = new Map();
-    const functions = new Map();
     const assigned = new Map();
     for (const statement of program.body) {
-        for (const declared of declaredBy(statement)) {
-            if (declared.kind === "value")
-                values.set(declared.name, declared.value);
-            else
-                functions.set(declared.name, declared.value);
-        }
+        for (const declared of declaredBy(statement))
+            values.set(declared.name, declared.value);
         const property = assignedProperty(statement);
         if (property === undefined)
             continue;
@@ -294,49 +186,41 @@ const topLevelOf = (program) => {
         properties.set(property.property, property.value);
         assigned.set(property.name, properties);
     }
-    return { values, functions, assigned };
+    return { values, assigned };
 };
 /**
- * A story's source and fields, by the local name its export points at.
+ * The object a value is, or the one the constants it names lead to (`export const B = A`); `undefined` for any other
+ * value, or for names that lead back to themselves.
  *
  * @param top - the file's top level.
- * @param local - the local name.
+ * @param value - the value.
+ * @param seen - the names followed so far.
  */
-const storyOf = (top, local) => {
-    const value = top.values.get(local);
-    const isStory = value !== undefined &&
-        (value.type === "ObjectExpression" ||
-            value.type === "ArrowFunctionExpression" ||
-            value.type === "FunctionExpression" ||
-            isBoundTemplate(value));
-    const node = isStory ? value : top.functions.get(local);
-    const properties = top.assigned.get(local);
-    const fields = node?.type === "ObjectExpression"
-        ? objectFields(node)
-        : (name) => properties?.get(name);
-    return { node, fields };
+const objectOf = (top, value, seen = new Set()) => {
+    if (value?.type === "ObjectExpression")
+        return value;
+    if (value?.type !== "Identifier" || seen.has(value.name))
+        return undefined;
+    return objectOf(top, top.values.get(value.name), new Set([...seen, value.name]));
 };
 /**
- * The file's named exports, in their order: declared ones and re-exports of local names (`export { A as B }`), never
- * an export from another file.
+ * A story's fields, by the export that names it: what is assigned to it after its declaration (`A.storyName = "…"`),
+ * else the object its value is or names. A story from another file has none.
  *
- * @param program - the parsed file.
+ * @param top - the file's top level.
+ * @param named - the export.
  */
-const namedExports = (program) => program.body.flatMap((statement) => {
-    if (statement.type !== "ExportNamedDeclaration" || statement.source !== null)
-        return [];
-    const { declaration } = statement;
-    if (declaration?.type === "VariableDeclaration") {
-        return declaration.declarations.flatMap((declarator) => declarator.id.type === "Identifier"
-            ? [{ exportName: declarator.id.name, local: declarator.id.name, start: statement.start }]
-            : []);
-    }
-    if (declaration?.type === "FunctionDeclaration" && declaration.id !== null)
-        return [{ exportName: declaration.id.name, local: declaration.id.name, start: statement.start }];
-    return statement.specifiers.flatMap((specifier) => specifier.local.type === "Identifier" && specifier.exported.type === "Identifier"
-        ? [{ exportName: specifier.exported.name, local: specifier.local.name, start: statement.start }]
-        : []);
-});
+const storyFieldsOf = (top, named) => {
+    const { local } = named;
+    if (local === undefined)
+        return { own: () => undefined, fields: () => undefined };
+    const assigned = top.assigned.get(local);
+    const value = top.values.get(local);
+    const declared = named.isDeclared && value?.type === "ObjectExpression" ? value : undefined;
+    const object = objectOf(top, value);
+    const read = (from) => (name) => assigned?.get(name) ?? (from === undefined ? undefined : propertyValue(from, name));
+    return { own: read(declared), fields: read(object) };
+};
 /**
  * Whether an export is a story, as the meta's `includeStories` and `excludeStories` say (a list of names or a regular
  * expression, written plainly).
@@ -367,7 +251,26 @@ const exportsOrder = (top) => {
     return order.elements.flatMap((element) => element?.type === "Literal" && typeof element.value === "string" ? [element.value] : []);
 };
 /**
- * The meta's object: the default export, inline or a constant of the file (`export default meta`).
+ * The meta exported by name (`export { meta as default }`), when it is a constant of the file written as an object.
+ *
+ * @param program - the parsed file.
+ * @param top - the file's top level.
+ */
+const namedMeta = (program, top) => {
+    for (const statement of program.body) {
+        if (statement.type !== "ExportNamedDeclaration" || statement.source !== null)
+            continue;
+        const specifier = statement.specifiers.find((each) => moduleName(each.exported) === "default");
+        if (specifier === undefined)
+            continue;
+        const value = top.values.get(moduleName(specifier.local));
+        return value?.type === "ObjectExpression" ? value : undefined;
+    }
+    return undefined;
+};
+/**
+ * The meta's object: the default export, inline or a constant of the file (`export default meta`,
+ * `export { meta as default }`).
  *
  * @param program - the parsed file.
  * @param top - the file's top level.
@@ -375,7 +278,7 @@ const exportsOrder = (top) => {
 const metaObject = (program, top) => {
     const meta = program.body.find((statement) => statement.type === "ExportDefaultDeclaration");
     if (meta === undefined)
-        return undefined;
+        return namedMeta(program, top);
     const { declaration } = meta;
     if (declaration.type === "FunctionDeclaration" ||
         declaration.type === "ClassDeclaration" ||
@@ -385,6 +288,12 @@ const metaObject = (program, top) => {
     const value = expression.type === "Identifier" ? top.values.get(expression.name) : expression;
     return value?.type === "ObjectExpression" ? value : undefined;
 };
+/**
+ * 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 program - the parsed file.
+ */
+export const storyFileMeta = (program) => metaObject(program, topLevelOf(program));
 /** The meta's lists of plain strings (`alsoIn`, `related`, `keywords`), each only when set, or the first problem. */
 const metaListsOf = (meta) => {
     const lists = {};
@@ -418,29 +327,60 @@ const titleOf = (meta, options) => {
     };
 };
 /**
- * The meta's fields besides its title and stories, or the first problem.
+ * The meta's design as the index keeps it: a link that is not a Figma file's is noted and left out.
+ *
+ * @param meta - the meta's fields.
+ * @param notes - the file's notes, which a design left out adds to.
+ */
+const metaDesign = (meta, notes) => {
+    const design = designOf(meta);
+    if (design instanceof Error)
+        return design;
+    if (typeof design === "string") {
+        notes.push(design);
+        return {};
+    }
+    return design === undefined ? {} : { design };
+};
+/**
+ * The meta's fields besides its title and stories (its `id` among them), or the first problem.
  *
  * @param meta - the meta's fields.
+ * @param notes - the file's notes, which a design left out adds to.
  */
-const metaFieldsOf = (meta) => {
+const metaFieldsOf = (meta, notes) => {
+    const id = meta("id");
+    // Storybook refuses a component id written by code: it would give ids no link can know
+    if (id !== undefined && (id.type !== "Literal" || typeof id.value !== "string"))
+        return new Error("`id` must be a plain string");
     const controls = controlsOf(meta);
     if (controls instanceof Error)
         return controls;
     const height = heightOf(meta);
     if (height instanceof Error)
         return height;
+    const design = metaDesign(meta, notes);
+    if (design instanceof Error)
+        return design;
     const lists = metaListsOf(meta);
     if (lists instanceof Error)
         return lists;
+    const propGroups = propGroupsOf(meta);
+    if (propGroups instanceof Error)
+        return propGroups;
     const description = docsDescription(meta, "component");
-    const flags = flagsOf(meta);
+    const flags = indexedParameters(meta);
     if (flags instanceof Error)
         return flags;
     return {
+        // an empty id is none, as Storybook's `meta.id || meta.title` has it
+        ...(id === undefined || id.value === "" ? {} : { id: String(id.value) }),
         ...(controls === undefined ? {} : { controls }),
         ...(height === undefined ? {} : { height }),
+        ...design,
         ...flags,
         ...lists,
+        ...(propGroups === undefined ? {} : { propGroups }),
         ...(description === undefined ? {} : { description })
     };
 };
@@ -468,7 +408,7 @@ const storyExports = (program, top, meta) => {
  * @returns the title and the stories, or a message saying why the file cannot be indexed.
  */
 export const indexStoryFile = (file, text, options = {}) => {
-    const { program, comments, errors } = parseSync(file, text);
+    const { program, comments, errors } = parseStoryFile(file, text);
     const [error] = errors;
     if (error !== undefined)
         return `${file} does not parse: ${error.message}`;
@@ -484,24 +424,28 @@ export const indexStoryFile = (file, text, options = {}) => {
     if (metaTags instanceof Error)
         return `${file}: the meta's ${metaTags.message}`;
     const stories = [];
-    for (const { exportName, local, start } of storyExports(program, top, meta)) {
-        const story = storyOf(top, local);
-        if (story.node === undefined)
-            continue;
-        const fields = storyFields(story.fields, metaTags);
+    const storyNotes = [];
+    for (const named of storyExports(program, top, meta)) {
+        const { exportName, start } = named;
+        const sources = storyFieldsOf(top, named);
+        const ownNotes = [];
+        const fields = storyFields(sources, metaTags, ownNotes);
         if (fields instanceof Error)
             return `${file}: story ${exportName}: ${fields.message}`;
-        const description = leadingSentence(text, comments, start) ?? docsDescription(story.fields, "story");
-        stories.push({ exportName, ...fields, ...(description === undefined ? {} : { description }) });
+        storyNotes.push(...ownNotes.map((note) => `story ${exportName}: ${note}`));
+        const description = leadingSentence(text, comments, start) ?? docsDescription(sources.fields, "story");
+        const played = playField(named.local, top, meta("play"));
+        stories.push({ exportName, ...fields, ...(description === undefined ? {} : { description }), ...played });
     }
-    const metaFields = metaFieldsOf(meta);
+    const metaNotes = [];
+    const metaFields = metaFieldsOf(meta, metaNotes);
     if (metaFields instanceof Error)
         return `${file}: the meta's ${metaFields.message}`;
+    const notes = [...title.notes, ...metaNotes, ...storyNotes];
     return {
         title: title.title,
         stories,
         ...metaFields,
-        ...(title.notes.length > 0 ? { notes: title.notes } : {})
+        ...(notes.length > 0 ? { notes } : {})
     };
 };
-//# sourceMappingURL=indexStoryFile.js.map

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

@@ -0,0 +1,10 @@
+import type { StoryIndexEntry } from "@forgebook/story-format/source";
+import { type Fields } from "./indexFields.ts";
+/** What the index keeps of these parameters: each only when written. */
+export type IndexedParameters = Pick<StoryIndexEntry, "isTouch" | "isLogic" | "device" | "requiredFirst">;
+/**
+ * The parameters only the index reads, each only when written, or the first problem.
+ *
+ * @param fields - the story's or the meta's fields.
+ */
+export declare const indexedParameters: (fields: Fields) => IndexedParameters | Error;