forgebook 0.3.3 → 0.4.0

package/dist/src/storyCheck.d.ts

@@ -8,7 +8,8 @@
  * when it runs (the core has no browser), and reads the report back through `isStoryCheckReport`, since it crossed a
  * dynamic import. The problems are those the catalogue's browser tests fail on, with the same messages: a frame that
  * could not show its story, axe's rules, spills, overlays past the frame, and the page's errors (a failed play among
- * them: its rejection reaches the page). Pure.
+ * them: its rejection reaches the page). A story its frame gave up on is neither passed nor failed: `notVerified` says
+ * so. Pure.
  *
  * @module
  */
@@ -31,6 +32,8 @@ export type StoryProblem = {
 export type StoryCheckStory = {
     /** The story's id. */
     readonly id: string;
+    /** Its file, as the catalogue lists it: what a report names when the story cannot be shown. */
+    readonly file?: string;
     /**
      * The id an earlier rule gave it, when it differs from `id`: a baseline stored under that id is still its baseline
      * until `forgebook shot --update` stores one under its id.
@@ -57,6 +60,8 @@ export type StoryCheckRequest = {
     readonly views: readonly string[];
     /** Check every variant the catalogue's browser tests check instead of the views given. */
     readonly isAllVariants: boolean;
+    /** How many pages to open at once; one by default. */
+    readonly concurrency?: number;
     /** The model that judges what axe cannot see; none leaves the pages on this machine. */
     readonly semantic?: SemanticModel;
 };
@@ -86,6 +91,19 @@ export type StoryCheckResult = {
     readonly frame: string;
     /** The problems; none when it passes. */
     readonly problems: readonly StoryProblem[];
+    /**
+     * Why the story's checks did not run: its frame gave up waiting for what it loads, or cannot tell (status `pending`),
+     * so no check saw the story in its final state. Absent when they ran; present, the story has not passed, whatever
+     * `problems` holds.
+     */
+    readonly notVerified?: string;
+    /** Whether the story drew nothing a reader could see: no text, and no element with a size. Absent otherwise. */
+    readonly isBlank?: boolean;
+    /**
+     * Whether the frame did not wait for what the story loads, as it asks (`parameters.suspense.expected`): the checks read
+     * it as it first drew. Absent otherwise.
+     */
+    readonly isNotAwaited?: boolean;
     /** What the model judged, when one was asked; a text says why it could not. */
     readonly judgements?: readonly StoryJudgement[] | string;
 };
@@ -98,6 +116,67 @@ export type StoryCheckReport = {
     /** `"off"` when the catalogue checks no accessibility (`a11y: false`): no result ran axe. Absent when it does. */
     readonly a11y?: "off";
 };
+/** One case of a stress run: the values given, the window, the view, and what it found that the plain story does not. */
+export type StressCase = {
+    /** Its name: `long-text`, `unbreakable`, `huge-number`, `empty`, `rtl`, `zoom-200`, `narrow`, `dark`, `contrast`. */
+    readonly name: string;
+    /** The story's id. */
+    readonly storyId: string;
+    /** The values given over the story's own, by prop. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** The frame, in its view. */
+    readonly frame: string;
+    /** The problems the plain story does not have; none when it holds. */
+    readonly problems: readonly StoryProblem[];
+    /** Why it could not be judged: the story did not draw in it, or not in the plain case. */
+    readonly notVerified?: string;
+};
+/** One case to run, as the command builds it from the story's props and the catalogue's switches. */
+export type StressCaseRequest = {
+    /** Its name. */
+    readonly name: string;
+    /** The values to give, as the props panel gives them. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** The view, in the address's form (`theme=dark`); empty for the default. */
+    readonly view: string;
+    /** The window's width, in CSS px; the default window's when none. */
+    readonly width?: number;
+    /** Whether the frame's document reads right to left. */
+    readonly isRtl?: boolean;
+    /** The axe rules whose finding the case's own values cause, which say nothing of the component. */
+    readonly expectedRules?: readonly string[];
+};
+/** What a stress run is asked. */
+export type StressRequest = {
+    /** The catalogue's frame page, absolute. */
+    readonly frameUrl: string;
+    /** The stories, each with its cases. */
+    readonly stories: readonly {
+        readonly story: StoryCheckStory;
+        readonly cases: readonly StressCaseRequest[];
+    }[];
+    /** The catalogue's switches. */
+    readonly switches: readonly ViewSwitch[];
+    /** The catalogue's lists: its accessibility rules. */
+    readonly lists: CatalogueLists;
+};
+/** What a stress run found. */
+export type StressReport = {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** One result per story and case. */
+    readonly cases: readonly StressCase[];
+    /** The cases not run, each with its story and why: a case with nothing to set is never counted as passed. */
+    readonly skipped: readonly string[];
+    /** `"off"` when the catalogue checks no accessibility (`a11y: false`): no case ran axe. Absent when it does. */
+    readonly a11y?: "off";
+};
+/**
+ * Whether what the testing package answered is a stress run's report.
+ *
+ * @param value - the answer.
+ */
+export declare const isStressReport: (value: unknown) => value is StressReport;
 /**
  * Whether what the testing package answered is a check's report.
  *
@@ -119,8 +198,11 @@ export type StoryShot = {
     readonly frame: string;
     /** The picture, a PNG file's absolute path. */
     readonly file: string;
-    /** Why the story did not draw (`error`, or `silent` when it never said); none when it did. */
-    readonly status?: "error" | "silent";
+    /**
+     * Why the picture is not of the story as drawn (`error`; `silent` when it never said; `pending` when the frame gave up
+     * on what it loads, so this may picture a fallback); none when it is.
+     */
+    readonly status?: "error" | "silent" | "pending";
 };
 /** The pictures taken. */
 export type StoryShotReport = {

package/dist/src/storyCheck.js

@@ -1,3 +1,23 @@
+/**
+ * Whether what the testing package answered is a stress run's report.
+ *
+ * @param value - the answer.
+ */
+export const isStressReport = (value) => typeof value === "object" &&
+    value !== null &&
+    "schema" in value &&
+    value.schema === 1 &&
+    "cases" in value &&
+    Array.isArray(value.cases) &&
+    value.cases.every((each) => typeof each === "object" &&
+        each !== null &&
+        "name" in each &&
+        typeof each.name === "string" &&
+        "storyId" in each &&
+        typeof each.storyId === "string" &&
+        "problems" in each &&
+        Array.isArray(each.problems) &&
+        each.problems.every(isProblem));
 /** Every kind, for reading a report back. */
 const KINDS = ["frame", "axe", "spill", "overlay", "focus", "error"];
 /**
@@ -26,7 +46,9 @@ const isResult = (value) => typeof value === "object" &&
     typeof value.frame === "string" &&
     "problems" in value &&
     Array.isArray(value.problems) &&
-    value.problems.every(isProblem);
+    value.problems.every(isProblem) &&
+    (!("notVerified" in value) || value.notVerified === undefined || typeof value.notVerified === "string") &&
+    (!("isNotAwaited" in value) || value.isNotAwaited === undefined || typeof value.isNotAwaited === "boolean");
 /**
  * Whether what the testing package answered is a check's report.
  *

package/dist/src/storyCodeText.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A story's code as text, as the shell shows and copies it and as `forgebook story` gives it to an agent: its `render`
+ * as written, or, for a story drawn from its args, the component in the framework's code with the args its file writes
+ * as code (functions, elements) as written and the values of the moment for the rest.
+ *
+ * @remarks
+ * An arg the panel or an agent set is written from its value, not from the file's text, which no longer says what the
+ * story draws. Pure: the shell and the dev server read the same text.
+ *
+ * @module
+ */
+import type { StoryCode, StoryFileCode } from "@forgebook/story-format/source";
+import type { StoryCodeWriter } from "./frame/renderer.ts";
+import type { PanelArgs } from "./messages.ts";
+/** Which story's code, and the values its code is drawn from when it has no `render`. */
+export type StoryCodeSource = {
+    /** The story file's code. */
+    readonly code: StoryFileCode;
+    /** The story's export name. */
+    readonly exportName: string;
+    /** The component's name as code writes it (`codeNameOf`), for the code of a story drawn from its args. */
+    readonly componentName: string;
+    /** The values of the moment: the story's args, with the panel's over them on the story page. */
+    readonly args: PanelArgs;
+    /** The args the panel or an agent set, written from their values; none by default. */
+    readonly edited?: readonly string[];
+};
+/**
+ * The story's render as written, when it has one.
+ *
+ * @param source - the file's code and the story.
+ */
+export declare const renderCodeOf: ({ code, exportName }: StoryCodeSource) => StoryCode | undefined;
+/**
+ * The args the story's file writes as code, but those the panel or an agent set.
+ *
+ * @param source - the file's code, the story and what was set.
+ */
+export declare const writtenArgsOf: ({ code, exportName, edited }: StoryCodeSource) => Readonly<Record<string, string>>;
+/**
+ * The story's code as text, as copied.
+ *
+ * @param source - the file's code, the story, the component's name and the args.
+ * @param write - the framework's code writer, for a story drawn from its args.
+ */
+export declare const storyCodeText: (source: StoryCodeSource, write: StoryCodeWriter) => string;

package/dist/src/storyCodeText.js

@@ -0,0 +1,27 @@
+/**
+ * The story's render as written, when it has one.
+ *
+ * @param source - the file's code and the story.
+ */
+export const renderCodeOf = ({ code, exportName }) => {
+    const entry = code[exportName];
+    return entry !== undefined && "text" in entry ? entry : undefined;
+};
+/**
+ * The args the story's file writes as code, but those the panel or an agent set.
+ *
+ * @param source - the file's code, the story and what was set.
+ */
+export const writtenArgsOf = ({ code, exportName, edited = [] }) => {
+    const entry = code[exportName];
+    if (entry === undefined || !("args" in entry))
+        return {};
+    return Object.fromEntries(Object.entries(entry.args).filter(([name]) => !edited.includes(name)));
+};
+/**
+ * The story's code as text, as copied.
+ *
+ * @param source - the file's code, the story, the component's name and the args.
+ * @param write - the framework's code writer, for a story drawn from its args.
+ */
+export const storyCodeText = (source, write) => renderCodeOf(source)?.text ?? write(source.componentName, source.args, writtenArgsOf(source));

package/dist/src/storyControls.d.ts

@@ -0,0 +1,100 @@
+/**
+ * What a story's controls are, for whoever sets its values without the panel: each prop's control and what its value
+ * looks like, as an agent reads them, and the values an agent asks to set, checked as a link's are. Pure.
+ *
+ * @module
+ */
+import type { StoryControlsSetting } from "@forgebook/story-format/source";
+import { type DroppedArg } from "./addressArgs.ts";
+import { type AddressTexts } from "./addressTexts.ts";
+import type { ValueSchema } from "./argControl.ts";
+import { type PanelArgTypes, type PanelControl, type TokenRequest } from "./argTypes.ts";
+import type { PropDocs } from "./componentDocs.ts";
+import { type ArgValue, type PanelArgs } from "./messages.ts";
+import type { NamedValues } from "./namedValues.ts";
+import { type ValueShape } from "./valueShape.ts";
+/** How a value of a prop is set: the panel's control, or a choice among the source's named values. */
+export type ControlKind = Exclude<PanelControl, "none"> | "named" | "custom";
+/** One prop a story's values can set. */
+export type StoryControl = {
+    /** The prop's name: the key in `args`. */
+    readonly name: string;
+    /** Its control, which says what its value is. */
+    readonly control: ControlKind;
+    /** Its type, as the source writes it. */
+    readonly type: string;
+    /** Whether the prop must be passed. */
+    readonly isRequired: boolean;
+    /** What its value looks like, for a value of more than one part. */
+    readonly shape?: ValueShape;
+    /** A choice's values. */
+    readonly choices?: readonly (string | number)[];
+    /** A number's lowest value. */
+    readonly min?: number;
+    /** A number's highest value. */
+    readonly max?: number;
+    /** The names a `named` control takes, as `{ of: type, named: name }`. */
+    readonly named?: readonly string[];
+    /** A `custom` control's name, of those `argControls` registers. */
+    readonly custom?: string;
+    /** A `custom` control's `settings`, as the story writes them. */
+    readonly settings?: ArgValue;
+    /** A `custom` control's schema: what its value must fit. Left out when its module cannot be read. */
+    readonly schema?: ValueSchema;
+    /** A `token` control's tokens, and what the story receives for one (`forgebook tokens` lists them). */
+    readonly tokens?: TokenRequest;
+};
+/** The custom controls' schemas, by name. */
+export type CustomSchemas = Readonly<Record<string, ValueSchema>>;
+/** What a story declares of its args, as the server reads it from the story's module. */
+export type StoryDeclaration = {
+    /** The props its component's types give. */
+    readonly props: readonly PropDocs[];
+    /** Its `argTypes`, as the panel reads them. */
+    readonly argTypes: PanelArgTypes;
+    /** The props the story lets the panel set. */
+    readonly controls: StoryControlsSetting;
+    /** The story's own args, as the panel reads them. */
+    readonly storyArgs: PanelArgs;
+    /** The source's named values. */
+    readonly namedValues: NamedValues;
+    /** The custom controls' schemas, by name, those whose module could be read. */
+    readonly customSchemas?: CustomSchemas;
+};
+/**
+ * The props a story's values can set.
+ *
+ * @param declaration - what the story declares.
+ */
+export declare const storyControlsOf: (declaration: StoryDeclaration) => readonly StoryControl[];
+/** What became of the values asked for. */
+export type SetArgs = {
+    /** The values the story takes, by prop; the links carry them. */
+    readonly accepted: Readonly<Record<string, ArgValue>>;
+    /** The values left out, with the reason. */
+    readonly dropped: readonly DroppedArg[];
+    /** `args=` as the links write it; empty when none is taken. */
+    readonly param: string;
+};
+/**
+ * The values an agent asks to set, checked as a link's are.
+ *
+ * @param text - the values, as JSON.
+ * @param declaration - what the story declares.
+ * @param addressTexts - how the framework's stories take a link's texts; `any` by default.
+ */
+export declare const checkedSetArgs: (text: string, declaration: StoryDeclaration, addressTexts?: AddressTexts) => SetArgs;
+/** The custom controls as the server read them. */
+export type CustomControlsRead = {
+    /** The schemas, by control. */
+    readonly schemas: CustomSchemas;
+    /** Why a control could not be read, by control. */
+    readonly problems: Readonly<Record<string, string>>;
+};
+/**
+ * What is wrong with the custom controls a story names: one no configuration registers, or whose module did not load.
+ *
+ * @param controls - the story's controls.
+ * @param read - the custom controls as the server read them.
+ */
+export declare const customControlProblems: (controls: readonly StoryControl[], read: CustomControlsRead | undefined) => readonly string[];

package/dist/src/storyControls.js

@@ -0,0 +1,100 @@
+import { checkedAddressArgs, declaredArgProps } from "./addressArgs.js";
+import { readArgsParam } from "./addressArgsParam.js";
+import { addressArgsFor } from "./addressTexts.js";
+import { isColorProp, isNamedProp } from "./argTypes.js";
+import { panelArgsParam } from "./messages.js";
+import { holdsUnsafePart, isFileList, isValueOfShape, resolvedShape } from "./shapeValues.js";
+import { schemaProblem } from "./valueSchema.js";
+import { canSetShape } from "./valueShape.js";
+/** A prop's control when no `argTypes` names one: from its kind. */
+const controlOfKind = (prop, namedValues) => {
+    if (isNamedProp(prop, namedValues))
+        return "named";
+    if (prop.shape !== undefined)
+        return "object";
+    if (prop.kind === "choice")
+        return "select";
+    if (prop.kind === "number")
+        return "number";
+    if (prop.kind === "toggle")
+        return "boolean";
+    return isColorProp(prop) ? "color" : "text";
+};
+/**
+ * One settable prop as an agent reads it.
+ *
+ * @param prop - the prop.
+ * @param namedValues - the source's named values.
+ * @param customSchemas - the custom controls' schemas.
+ */
+const storyControl = (prop, namedValues, customSchemas) => {
+    const custom = prop.customControl;
+    const schema = custom !== undefined && Object.hasOwn(customSchemas, custom) ? customSchemas[custom] : undefined;
+    const own = prop.control === undefined || prop.control === "none" ? controlOfKind(prop, namedValues) : prop.control;
+    const control = custom === undefined ? own : "custom";
+    return {
+        name: prop.name,
+        control,
+        type: prop.type,
+        isRequired: prop.isRequired,
+        ...(prop.shape === undefined ? {} : { shape: resolvedShape(prop.shape) }),
+        ...(prop.choices === undefined ? {} : { choices: prop.choices }),
+        ...(prop.min === undefined ? {} : { min: prop.min }),
+        ...(prop.max === undefined ? {} : { max: prop.max }),
+        ...(control === "named" ? { named: Object.keys(namedValues[prop.type] ?? {}) } : {}),
+        ...(prop.tokens === undefined ? {} : { tokens: prop.tokens }),
+        ...(custom === undefined ? {} : { custom }),
+        ...(prop.settings === undefined ? {} : { settings: prop.settings }),
+        ...(schema === undefined ? {} : { schema })
+    };
+};
+/**
+ * The props a story's values can set.
+ *
+ * @param declaration - what the story declares.
+ */
+export const storyControlsOf = (declaration) => {
+    const argDeclaration = declaration;
+    const canSet = (prop) => prop.shape === undefined || canSetShape(prop.shape, declaration.namedValues);
+    return declaredArgProps(argDeclaration)
+        .filter(canSet)
+        .map((prop) => storyControl(prop, declaration.namedValues, declaration.customSchemas ?? {}));
+};
+/**
+ * The values an agent asks to set, checked as a link's are.
+ *
+ * @param text - the values, as JSON.
+ * @param declaration - what the story declares.
+ * @param addressTexts - how the framework's stories take a link's texts; `any` by default.
+ */
+export const checkedSetArgs = (text, declaration, addressTexts = "any") => {
+    const { args, link } = readArgsParam(text.trimStart().startsWith("{") ? text : "{");
+    const unread = (link?.unread ?? []).map((name) => ({ name, reason: "unreadable" }));
+    const plain = addressArgsFor(args, addressTexts);
+    const notPlain = Object.keys(args)
+        .filter((name) => !Object.hasOwn(plain, name))
+        .map((name) => ({ name, reason: "markup" }));
+    const { accepted, dropped } = checkedAddressArgs(plain, declaration, undefined, {
+        isFileList,
+        isValueOfShape,
+        custom: Object.fromEntries(Object.entries(declaration.customSchemas ?? {}).map(([name, schema]) => [
+            name,
+            (value) => holdsUnsafePart(value, true) ? "not what a link may give" : schemaProblem(schema, value)
+        ]))
+    });
+    return { accepted, dropped: [...unread, ...notPlain, ...dropped], param: panelArgsParam(accepted) };
+};
+/**
+ * What is wrong with the custom controls a story names: one no configuration registers, or whose module did not load.
+ *
+ * @param controls - the story's controls.
+ * @param read - the custom controls as the server read them.
+ */
+export const customControlProblems = (controls, read) => controls.flatMap(({ custom, schema }) => {
+    if (custom === undefined || schema !== undefined)
+        return [];
+    const problem = read !== undefined && Object.hasOwn(read.problems, custom) ? read.problems[custom] : undefined;
+    return [
+        `The control "${custom}": ${problem ?? "no control is registered under this name in argControls"}`
+    ];
+});

package/dist/src/storyStatuses.d.ts

@@ -0,0 +1,55 @@
+/** How a status reads at a glance: the colour of its badge, each with its text contrast in both appearances. */
+export declare const STATUS_TONES: readonly ["neutral", "info", "positive", "caution", "critical"];
+/** One of the tones. */
+export type StatusTone = (typeof STATUS_TONES)[number];
+/** A status as a catalogue declares it (`statuses: { review: { label: "In review", tone: "caution" } }`). */
+export type StatusSetting = {
+    /** Its badge's text; the shell's own word for a default status (`strings` replaces it), else its tag. */
+    readonly label?: string;
+    /** Its badge's colour; `neutral` for a status of the catalogue's own. */
+    readonly tone?: StatusTone;
+};
+/** The statuses a configuration declares, by tag: `false` turns a default one off. */
+export type StatusSettings = Readonly<Record<string, StatusSetting | false>>;
+/** A status the catalogue has, its defaults filled in. */
+export type CatalogueStatus = {
+    /** Its tag (`review`). */
+    readonly id: string;
+    /** Its badge's text, when the catalogue writes one. */
+    readonly label?: string;
+    /** Its badge's colour. */
+    readonly tone: StatusTone;
+};
+/** The status whose tag says a component is not to be used any more, as TSDoc's `@deprecated` says it. */
+export declare const DEPRECATED_STATUS = "deprecated";
+/** The statuses every catalogue has unless it turns them off, in the order their badges come. */
+export declare const DEFAULT_STATUSES: Readonly<Record<string, StatusSetting>>;
+/**
+ * A catalogue's statuses: the defaults, each with what the configuration writes of it, then the configuration's own,
+ * less those it turns off.
+ *
+ * @param settings - what the configuration declares; none for the defaults.
+ */
+export declare const catalogueStatuses: (settings?: StatusSettings) => readonly CatalogueStatus[];
+/**
+ * Statuses declared in several places (the presets', then the catalogue's) as one declaration: status by status and
+ * field by field, so a catalogue renames a preset's status and keeps its tone; none when none declares any.
+ *
+ * @param all - the declarations, in order.
+ */
+export declare const mergedStatuses: (all: readonly (StatusSettings | undefined)[]) => {
+    readonly statuses?: StatusSettings;
+};
+/**
+ * The statuses a list of tags holds, in the catalogue's order.
+ *
+ * @param tags - a meta's or a story's tags.
+ * @param statuses - the catalogue's statuses.
+ */
+export declare const statusesOf: (tags: readonly string[], statuses: readonly CatalogueStatus[]) => readonly CatalogueStatus[];
+/**
+ * Why a configuration's statuses cannot be used, or none: they are written by JavaScript too, which no type stops.
+ *
+ * @param settings - the value written.
+ */
+export declare const statusesProblem: (settings: unknown) => string | undefined;

package/dist/src/storyStatuses.js

@@ -0,0 +1,104 @@
+/**
+ * A component's or a story's status (waiting for review, experimental, deprecated): a tag the catalogue declares as a
+ * status, read by the agents' answers on Node and by the shell's badges, which load only for a catalogue whose stories
+ * have tags.
+ *
+ * @remarks
+ * A status is a tag, so it is written where CSF writes one (the preview, a meta, a story; `!name` takes it away) and
+ * filtered by the tag filter; the declaration only says which tags are statuses and how they look. A meta's tags give
+ * the component's status, a story's the story's. Three are declared by default, each a catalogue may restyle, rename
+ * or turn off with `false`. Pure.
+ *
+ * @module
+ */
+import { TOOL_TAGS } from "./storyTagNames.js";
+/** How a status reads at a glance: the colour of its badge, each with its text contrast in both appearances. */
+export const STATUS_TONES = ["neutral", "info", "positive", "caution", "critical"];
+/** The status whose tag says a component is not to be used any more, as TSDoc's `@deprecated` says it. */
+export const DEPRECATED_STATUS = "deprecated";
+/** The statuses every catalogue has unless it turns them off, in the order their badges come. */
+export const DEFAULT_STATUSES = {
+    review: { tone: "caution" },
+    experimental: { tone: "info" },
+    [DEPRECATED_STATUS]: { tone: "critical" }
+};
+/**
+ * A catalogue's statuses: the defaults, each with what the configuration writes of it, then the configuration's own,
+ * less those it turns off.
+ *
+ * @param settings - what the configuration declares; none for the defaults.
+ */
+export const catalogueStatuses = (settings = {}) => Object.entries({ ...DEFAULT_STATUSES, ...settings }).flatMap(([id, setting]) => {
+    if (setting === false)
+        return [];
+    const { label, tone } = { ...DEFAULT_STATUSES[id], ...setting };
+    return [{ id, tone: tone ?? "neutral", ...(label === undefined ? {} : { label }) }];
+});
+/**
+ * Statuses declared in several places (the presets', then the catalogue's) as one declaration: status by status and
+ * field by field, so a catalogue renames a preset's status and keeps its tone; none when none declares any.
+ *
+ * @param all - the declarations, in order.
+ */
+export const mergedStatuses = (all) => {
+    const statuses = {};
+    for (const [id, status] of all.flatMap((each) => Object.entries(each ?? {}))) {
+        const before = statuses[id];
+        statuses[id] = status === false ? false : { ...(before === false ? {} : before), ...status };
+    }
+    return Object.keys(statuses).length === 0 ? {} : { statuses };
+};
+/**
+ * The statuses a list of tags holds, in the catalogue's order.
+ *
+ * @param tags - a meta's or a story's tags.
+ * @param statuses - the catalogue's statuses.
+ */
+export const statusesOf = (tags, statuses) => statuses.filter((status) => tags.includes(status.id));
+/**
+ * Why a status's fields cannot be used, or none: only `label` and `tone`, so a misspelt one is named, not ignored.
+ *
+ * @param id - its tag.
+ * @param setting - what is written for it.
+ */
+const fieldsProblem = (id, setting) => {
+    const unknown = Object.keys(setting).find((key) => key !== "label" && key !== "tone");
+    if (unknown !== undefined)
+        return `the status "${id}" has no field "${unknown}": it takes label and tone`;
+    const label = "label" in setting ? setting.label : undefined;
+    const tone = "tone" in setting ? setting.tone : undefined;
+    if (label !== undefined && (typeof label !== "string" || label === ""))
+        return `the status "${id}" has a label that is no text`;
+    if (tone !== undefined && !STATUS_TONES.some((each) => each === tone))
+        return `the status "${id}" has the tone ${JSON.stringify(tone)}: write one of ${STATUS_TONES.join(", ")}`;
+    return undefined;
+};
+/**
+ * Why one status a configuration declares cannot be used, or none.
+ *
+ * @param id - its tag.
+ * @param setting - what is written for it.
+ */
+const statusProblem = (id, setting) => {
+    if (id === "" || id.startsWith("!") || TOOL_TAGS.has(id))
+        return `"${id}" cannot be a status: a status is a tag of your own, not empty, no !name and none of ${[...TOOL_TAGS].join(", ")}`;
+    if (setting === false)
+        return undefined;
+    if (typeof setting !== "object" || setting === null || Array.isArray(setting))
+        return `the status "${id}" must be { label, tone } or false`;
+    return fieldsProblem(id, setting);
+};
+/**
+ * Why a configuration's statuses cannot be used, or none: they are written by JavaScript too, which no type stops.
+ *
+ * @param settings - the value written.
+ */
+export const statusesProblem = (settings) => {
+    if (settings === undefined)
+        return undefined;
+    if (typeof settings !== "object" || settings === null || Array.isArray(settings))
+        return "statuses must be an object of statuses by tag: { review: { label, tone } }";
+    return Object.entries(settings)
+        .map(([id, setting]) => statusProblem(id, setting))
+        .find((problem) => problem !== undefined);
+};

package/dist/src/storyTagNames.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which of a story's tags a person filters by, apart from the filter itself (`storyTags.ts`).
+ *
+ * @remarks
+ * Apart because the sidebar asks it on every catalogue's first load, to know whether to offer a filter at all, and a
+ * catalogue with no tags must not pay for the rest; a component's page asks it too, to know whether to draw statuses.
+ * Pure.
+ *
+ * @module
+ */
+import { type StoryTree } from "./storyTree.ts";
+/** The tags CSF gives a meaning of its own: they say what a tool does with a story, not what the story is. */
+export declare const TOOL_TAGS: ReadonlySet<string>;
+/**
+ * Whether a person can filter by a tag: any but a tool's tag, and a `!name`, which only takes a tag away.
+ *
+ * @param tag - the tag, as a story holds it.
+ */
+export declare const isFilterTag: (tag: string) => boolean;
+/**
+ * Whether any listed story holds a tag a person can filter by: what offers the filter and draws the statuses' badges.
+ *
+ * @param tree - the tree.
+ */
+export declare const hasFilterTags: (tree: StoryTree) => boolean;

package/dist/src/storyTagNames.js

@@ -0,0 +1,25 @@
+/**
+ * Which of a story's tags a person filters by, apart from the filter itself (`storyTags.ts`).
+ *
+ * @remarks
+ * Apart because the sidebar asks it on every catalogue's first load, to know whether to offer a filter at all, and a
+ * catalogue with no tags must not pay for the rest; a component's page asks it too, to know whether to draw statuses.
+ * Pure.
+ *
+ * @module
+ */
+import { storyLocations } from "./storyTree.js";
+/** The tags CSF gives a meaning of its own: they say what a tool does with a story, not what the story is. */
+export const TOOL_TAGS = new Set(["dev", "test", "autodocs", "play-fn", "test-fn"]);
+/**
+ * Whether a person can filter by a tag: any but a tool's tag, and a `!name`, which only takes a tag away.
+ *
+ * @param tag - the tag, as a story holds it.
+ */
+export const isFilterTag = (tag) => !tag.startsWith("!") && !TOOL_TAGS.has(tag);
+/**
+ * Whether any listed story holds a tag a person can filter by: what offers the filter and draws the statuses' badges.
+ *
+ * @param tree - the tree.
+ */
+export const hasFilterTags = (tree) => storyLocations(tree).some(({ story }) => story.tags.some(isFilterTag));