forgebook 0.3.3 → 0.4.1

package/dist/src/shell/valueEditors/ValueField.js

@@ -0,0 +1,148 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * One value's field, by what it looks like: a text, a number, a toggle, a choice, a named value, or the editor of a list,
+ * an object, a union or JSON. A value that does not fit its shape, or is too much to draw, falls back to JSON with a note,
+ * so what the panel sends always fits and nothing a story holds is hidden.
+ *
+ * @module
+ */
+import { useState } from "react";
+import { isArgList, isArgObject, isDateArg, isNamedArg } from "../../messages.js";
+import { isValueOfShape } from "../../shapeValues.js";
+import { MOST_PLAIN_OPTIONS } from "../PropFields.js";
+import { Switch } from "../Switch.js";
+import { STRINGS } from "../strings.js";
+import { EDITOR_STRINGS } from "./editorStrings.js";
+import { JsonEditor } from "./JsonEditor.js";
+import { ListEditor } from "./ListEditor.js";
+import { ObjectEditor, TupleEditor } from "./ObjectEditor.js";
+import { RecordEditor } from "./RecordEditor.js";
+import { SearchSelect } from "./SearchSelect.js";
+import { UnionEditor } from "./UnionEditor.js";
+/** The most parts of a value drawn as fields: past it, a page of inputs is slower to use than its JSON. */
+const MOST_DRAWN_PARTS = 150;
+/** How many parts a value has. */
+const partsOf = (value) => {
+    if (isArgList(value))
+        return value.reduce((sum, item) => sum + partsOf(item), 1);
+    if (isArgObject(value))
+        return Object.values(value).reduce((sum, item) => sum + partsOf(item), 1);
+    return 1;
+};
+/** Whether a shape is drawn as more than one field, so a person may want its JSON instead. */
+const isStructured = (shape) => shape.kind === "object" || shape.kind === "list" || shape.kind === "record" || shape.kind === "tuple";
+/**
+ * A number's field: what is typed stays as typed, and only a number reaches the value. A required number has no empty
+ * value, so what was left empty comes back when the field is left.
+ *
+ * @param props - the field's props.
+ */
+const NumberLeaf = ({ value, label, describedBy, onChange }) => {
+    const shown = typeof value === "number" ? String(value) : "";
+    const [draft, setDraft] = useState(undefined);
+    return (_jsx("input", { type: "number", "aria-label": label, "aria-describedby": describedBy, value: draft ?? shown, onChange: (event) => {
+            const text = event.target.value;
+            setDraft(text);
+            if (text !== "" && Number.isFinite(Number(text)))
+                onChange(Number(text));
+        }, onBlur: () => setDraft(undefined) }));
+};
+/** A choice's field: a native list for a few options, a search among many. */
+const ChoiceLeaf = ({ shape, value, label, describedBy, isRequired = false, onChange }) => {
+    const shown = typeof value === "string" || typeof value === "number" ? String(value) : undefined;
+    const chooseText = (text) => onChange(shape.values.find((each) => String(each) === text));
+    if (shape.values.length > MOST_PLAIN_OPTIONS) {
+        return (_jsx(SearchSelect, { label: label, describedBy: describedBy, options: shape.values.map((each) => ({ value: String(each), label: String(each) })), value: shown, canClear: !isRequired, onChange: chooseText }));
+    }
+    return (_jsxs("select", { "aria-label": label, "aria-describedby": describedBy, value: shown ?? "", onChange: (event) => chooseText(event.target.value), children: [isRequired ? null : _jsx("option", { value: "", children: STRINGS.unset }), shape.values.map((each) => (_jsx("option", { value: String(each), children: String(each) }, String(each))))] }));
+};
+/** A named value's field: a search among the names the source offers for its type. */
+const NamedLeaf = ({ shape, value, label, describedBy, namedValues, depth, isRequired = false, onChange }) => {
+    const names = Object.hasOwn(namedValues, shape.type) ? Object.keys(namedValues[shape.type] ?? {}) : [];
+    if (shape.canTakeText === true) {
+        // a slot takes a named value or a text: the same choice as any union
+        const members = names.length === 0 ? [{ kind: "text" }] : [{ kind: "named", type: shape.type }, { kind: "text" }];
+        return ValueField({
+            shape: members.length === 1 ? { kind: "text" } : { kind: "union", of: members },
+            value,
+            label,
+            describedBy,
+            namedValues,
+            depth,
+            isRequired,
+            onChange
+        });
+    }
+    return (_jsx(SearchSelect, { label: label, describedBy: describedBy, options: names.map((name) => ({ value: name, label: name })), value: value !== undefined && isNamedArg(value) ? value.named : undefined, canClear: !isRequired, onChange: (name) => onChange(name === undefined ? undefined : { of: shape.type, named: name }) }));
+};
+/** A text's field: one line, or several once the text holds a line break, which a one-line field would drop. */
+const TextLeaf = ({ value, label, describedBy, onChange }) => {
+    const text = typeof value === "string" ? value : "";
+    return text.includes("\n") ? (_jsx("textarea", { "aria-label": label, "aria-describedby": describedBy, rows: 3, value: text, onChange: (event) => onChange(event.target.value) })) : (_jsx("input", { type: "text", "aria-label": label, "aria-describedby": describedBy, value: text, onChange: (event) => onChange(event.target.value) }));
+};
+/** A moment's field, in the browser's time zone; what is left empty has no value. */
+const DateLeaf = ({ value, label, describedBy, onChange }) => {
+    const time = value !== undefined && isDateArg(value) ? Date.parse(value.forgebookDate) : undefined;
+    const shown = time === undefined
+        ? ""
+        : new Date(time - new Date(time).getTimezoneOffset() * 60_000).toISOString().slice(0, 16);
+    return (_jsx("input", { type: "datetime-local", "aria-label": label, "aria-describedby": describedBy, value: shown, onChange: (event) => {
+            const read = new Date(event.target.value);
+            onChange(Number.isNaN(read.getTime()) ? undefined : { forgebookDate: read.toISOString() });
+        } }));
+};
+/** A value's fields, or its JSON when a reader asks for it. */
+const StructuredField = (props) => {
+    const { shape, value, label, namedValues, depth } = props;
+    const [isJson, setIsJson] = useState(false);
+    const isMisfit = value !== undefined && !isValueOfShape(shape, value, namedValues);
+    const isTooLarge = value !== undefined && partsOf(value) > MOST_DRAWN_PARTS;
+    const drawn = () => {
+        switch (shape.kind) {
+            case "list":
+                return _jsx(ListEditor, { ...props, shape: shape, drawField: ValueField });
+            case "tuple":
+                return _jsx(TupleEditor, { ...props, shape: shape, drawField: ValueField });
+            case "object":
+                return _jsx(ObjectEditor, { ...props, shape: shape, drawField: ValueField });
+            case "record":
+                return _jsx(RecordEditor, { ...props, shape: shape, drawField: ValueField });
+            default:
+                return _jsx(JsonEditor, { ...props });
+        }
+    };
+    if (isMisfit || isTooLarge) {
+        return (_jsxs(_Fragment, { children: [_jsx("p", { className: "forgebook-value-note", children: isMisfit ? EDITOR_STRINGS.misfitNote : EDITOR_STRINGS.tooLargeNote }), _jsx(JsonEditor, { ...props })] }));
+    }
+    if (depth > 0)
+        return drawn();
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "forgebook-value-switch", children: _jsx("button", { type: "button", className: "forgebook-text-button", "aria-pressed": isJson, "aria-label": EDITOR_STRINGS.editAsJsonHint(label), onClick: () => setIsJson(!isJson), children: EDITOR_STRINGS.editAsJson }) }), isJson ? _jsx(JsonEditor, { ...props }) : drawn()] }));
+};
+/**
+ * One value's field.
+ *
+ * @param props - the field's props.
+ */
+export const ValueField = (props) => {
+    const { shape } = props;
+    if (isStructured(shape))
+        return _jsx(StructuredField, { ...props });
+    switch (shape.kind) {
+        case "text":
+            return _jsx(TextLeaf, { ...props });
+        case "number":
+            return _jsx(NumberLeaf, { ...props });
+        case "date":
+            return _jsx(DateLeaf, { ...props });
+        case "boolean":
+            return (_jsx(Switch, { label: props.label, isOn: shape.only ?? props.value === true, describedBy: props.describedBy, disabled: shape.only !== undefined, onChange: props.onChange }));
+        case "choice":
+            return _jsx(ChoiceLeaf, { ...props, shape: shape });
+        case "named":
+            return _jsx(NamedLeaf, { ...props, shape: shape });
+        case "union":
+            return _jsx(UnionEditor, { ...props, shape: shape, drawField: ValueField });
+        default:
+            return _jsx(JsonEditor, { ...props });
+    }
+};

package/dist/src/shell/valueEditors/editorStrings.d.ts

@@ -0,0 +1,56 @@
+/** The editors' texts, as shown: Forgebook's, with the catalogue's replacements. */
+export declare const EDITOR_STRINGS: {
+    addItem: (label: string) => string;
+    addField: (label: string) => string;
+    itemName: (label: string, position: number) => string;
+    moveUp: (label: string) => string;
+    moveDown: (label: string) => string;
+    removeItem: (label: string) => string;
+    itemMoved: (label: string, position: number, count: number) => string;
+    itemRemoved: (label: string, count: number) => string;
+    emptyList: string;
+    cannotSet: string;
+    clearField: (label: string) => string;
+    fieldName: (label: string) => string;
+    fieldValue: (label: string, name: string) => string;
+    nameTaken: string;
+    nameRefused: string;
+    nameEmpty: string;
+    newField: string;
+    memberKind: (label: string) => string;
+    memberKinds: {
+        text: string;
+        number: string;
+        date: string;
+        boolean: string;
+        choice: string;
+        list: string;
+        tuple: string;
+        object: string;
+        record: string;
+        union: string;
+        named: string;
+        json: string;
+        like: string;
+    };
+    editAsJson: string;
+    editAsJsonHint: (label: string) => string;
+    jsonInvalid: (reason: string) => string;
+    jsonRefused: string;
+    jsonMisfit: string;
+    misfitNote: string;
+    tooLargeNote: string;
+    searchEmpty: string;
+    searchMore: (count: number) => string;
+    searchClear: string;
+    searchOptions: (label: string) => string;
+    tokensLoading: string;
+    tokensFailed: (message: string) => string;
+    tokensNone: (asked: string) => string;
+    fileChoose: (label: string) => string;
+    fileRemove: (name: string) => string;
+    fileLine: (type: string, size: string) => string;
+    fileTooLarge: (name: string, most: string) => string;
+    fileRefused: (name: string) => string;
+    fileFailed: (name: string) => string;
+};

package/dist/src/shell/valueEditors/editorStrings.js

@@ -0,0 +1,66 @@
+/**
+ * The texts of the panel's editors that load on use (`PropEditor.tsx`): nested fields, a searchable list, the tokens, the
+ * files. They load with the editors, so a catalogue of plain props carries none of them.
+ *
+ * @remarks
+ * Each keeps the plain name it would have in `STRINGS`, so a catalogue replaces it the same way (`lateStrings`).
+ *
+ * @module
+ */
+import { lateStrings } from "../strings.js";
+/** The editors' texts, as shown: Forgebook's, with the catalogue's replacements. */
+export const EDITOR_STRINGS = lateStrings({
+    addItem: (label) => `Add to ${label}`,
+    addField: (label) => `Add ${label}`,
+    itemName: (label, position) => `${label} ${position}`,
+    moveUp: (label) => `Move ${label} up`,
+    moveDown: (label) => `Move ${label} down`,
+    removeItem: (label) => `Remove ${label}`,
+    itemMoved: (label, position, count) => `${label}: now ${position} of ${count}`,
+    itemRemoved: (label, count) => `${label} removed, ${count} left`,
+    emptyList: "No items",
+    cannotSet: "It needs what only the source's named values can give, and they name none",
+    clearField: (label) => `${label}: no value`,
+    fieldName: (label) => `${label}: name`,
+    fieldValue: (label, name) => `${label} ${name}`,
+    nameTaken: "Another field has this name",
+    nameRefused: "This name cannot be set from the panel or a link",
+    nameEmpty: "A field needs a name",
+    newField: "key",
+    memberKind: (label) => `${label}: type`,
+    memberKinds: {
+        text: "Text",
+        number: "Number",
+        date: "Date",
+        boolean: "On or off",
+        choice: "Choice",
+        list: "List",
+        tuple: "List",
+        object: "Object",
+        record: "Object",
+        union: "Choice",
+        named: "Named",
+        json: "JSON",
+        like: "Object"
+    },
+    editAsJson: "JSON",
+    editAsJsonHint: (label) => `Edit ${label} as JSON`,
+    jsonInvalid: (reason) => `Not valid JSON: ${reason}`,
+    jsonRefused: "It holds a name a value cannot hold (__proto__, constructor, prototype), or nests too deep",
+    jsonMisfit: "Valid JSON, but not what this prop takes, or it holds what a link may not give",
+    misfitNote: "The story's value does not match this prop's type: it is shown as JSON",
+    tooLargeNote: "Too much to show as fields: it is shown as JSON",
+    searchEmpty: "Nothing matches",
+    searchMore: (count) => `And ${count} more: type to narrow them down`,
+    searchClear: "No value",
+    searchOptions: (label) => `${label}: options`,
+    tokensLoading: "Loading the tokens…",
+    tokensFailed: (message) => `The tokens could not be read: ${message}`,
+    tokensNone: (asked) => `This catalogue has no ${asked} tokens: type a value`,
+    fileChoose: (label) => `${label}: choose files`,
+    fileRemove: (name) => `Remove ${name}`,
+    fileLine: (type, size) => `${type}, ${size}`,
+    fileTooLarge: (name, most) => `${name} is too large for a link, which holds the file: at most ${most}`,
+    fileRefused: (name) => `${name} is of a type a link cannot hold: it could run as a page`,
+    fileFailed: (name) => `${name} could not be read`
+});

package/dist/src/shell/valueEditors/fieldTypes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What the panel's nested fields are given: the same for every kind of value, so a field of a list can be an object, a
+ * union, or anything else a type says.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { ArgValue } from "../../messages.ts";
+import type { NamedValues } from "../../namedValues.ts";
+import type { ValueShape } from "../../valueShape.ts";
+/** One value's field. */
+export type FieldProps = {
+    /** What the value looks like. */
+    readonly shape: ValueShape;
+    /** The value; none when it has none. */
+    readonly value: ArgValue | undefined;
+    /** The name a screen reader reads: the prop's, and the path down to this part. */
+    readonly label: string;
+    /** The element that describes it, at the top of a prop. */
+    readonly describedBy?: string | undefined;
+    /** The source's named values. */
+    readonly namedValues: NamedValues;
+    /** How deep it is: the prop itself is 0. */
+    readonly depth: number;
+    /** Whether it must hold a value, so nothing offers to take it away; `false` by default. */
+    readonly isRequired?: boolean;
+    /** Called with a changed value; none takes it away. */
+    readonly onChange: (value: ArgValue | undefined) => void;
+};
+/** Draws a field, handed down so that the nested editors need not import what imports them. */
+export type DrawField = (props: FieldProps) => ReactNode;

package/dist/src/shell/valueEditors/valueEditors.css

@@ -0,0 +1,153 @@
+@layer catalogue {
+  .forgebook-value-object,
+  .forgebook-value-list,
+  .forgebook-value-tuple,
+  .forgebook-value-union,
+  .forgebook-value-json,
+  .forgebook-value-search {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    min-width: 0;
+  }
+  .forgebook-value-object[data-depth]:not([data-depth="0"]) {
+    padding-inline-start: 0.5rem;
+    box-shadow: inset 2px 0 0 0 var(--forgebook-separator);
+  }
+  .forgebook-value-tuple {
+    flex-direction: row;
+    flex-wrap: wrap;
+  }
+  .forgebook-value-tuple > * {
+    flex: 1 1 5rem;
+    min-width: 0;
+  }
+  .forgebook-value-field {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    min-width: 0;
+  }
+  .forgebook-value-field > input[type=checkbox] {
+    align-self: flex-start;
+  }
+  .forgebook-value-field__head {
+    display: flex;
+    align-items: center;
+    gap: 0.375rem;
+  }
+  .forgebook-value-field__name {
+    font: var(--forgebook-text-mono-small);
+    color: var(--forgebook-text-secondary);
+  }
+  .forgebook-value-list__item {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.375rem;
+    padding: 0.375rem;
+    border-radius: var(--forgebook-radius-control);
+    box-shadow: inset 0 0 0 1px var(--forgebook-edge-field);
+  }
+  .forgebook-value-list__field {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    gap: 0.375rem;
+    min-width: 0;
+  }
+  .forgebook-value-list__buttons {
+    display: flex;
+    flex: none;
+    gap: 0.125rem;
+  }
+  .forgebook-value-record__entry {
+    display: flex;
+    flex: 1;
+    flex-wrap: wrap;
+    gap: 0.375rem;
+    min-width: 0;
+  }
+  .forgebook-value-record__entry > * {
+    flex: 1 1 7rem;
+  }
+  .forgebook-value-record__name {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    min-width: 0;
+  }
+  .forgebook-value-add {
+    display: inline-flex;
+    align-self: flex-start;
+    align-items: center;
+    gap: 0.25rem;
+  }
+  .forgebook-value-switch {
+    display: flex;
+    justify-content: flex-end;
+  }
+  .forgebook-value-note {
+    margin: 0;
+    font: var(--forgebook-text-caption);
+    color: var(--forgebook-text-secondary);
+  }
+  .forgebook-value-note[data-tone=problem] {
+    color: var(--forgebook-danger-text);
+  }
+  .forgebook-value-json__text {
+    font: var(--forgebook-text-mono-small);
+    white-space: pre;
+    overflow: auto;
+  }
+  .forgebook-value-search__list {
+    display: flex;
+    flex-direction: column;
+    max-height: 13rem;
+    padding: 0.25rem;
+    overflow-y: auto;
+    border-radius: var(--forgebook-radius-control);
+    background: var(--forgebook-surface);
+    box-shadow: inset 0 0 0 1px var(--forgebook-edge-field);
+  }
+  .forgebook-value-search__option {
+    display: flex;
+    align-items: center;
+    gap: 0.375rem;
+    min-height: 1.5rem;
+    padding: 0.125rem 0.375rem;
+    border-radius: var(--forgebook-radius-control-small);
+    font: var(--forgebook-text-row-compact);
+    color: var(--forgebook-text);
+    cursor: pointer;
+  }
+  .forgebook-value-search__option[aria-selected=true] {
+    font-weight: 600;
+  }
+  .forgebook-value-search__option[data-active], .forgebook-value-search__option:hover {
+    background: var(--forgebook-hover);
+  }
+  .forgebook-value-search__swatch {
+    flex: none;
+    width: 0.75rem;
+    height: 0.75rem;
+    border-radius: 50%;
+    box-shadow: inset 0 0 0 1px var(--forgebook-edge-field);
+  }
+  .forgebook-value-search__name {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    min-width: 0;
+    flex: 1 1 auto;
+  }
+  .forgebook-value-search__hint {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    min-width: 0;
+    flex: 0 1 45%;
+    font: var(--forgebook-text-mono-small);
+    color: var(--forgebook-text-secondary);
+    text-align: end;
+  }
+}

package/dist/src/shell/worstArgs.d.ts

@@ -6,21 +6,24 @@
  * The values are the ones `forgebook new` writes in a story's worst case (`worstCase.ts`). The text joins the long text
  * and the unbreakable word, so one value shows both a box that must wrap and one that must cut or scroll. A colour, a
  * date and a prop whose `argTypes` give it a list keep their values: a long text there is not a case, only an invalid
- * value. A number with a highest value takes that value, the largest the story says it accepts.
+ * value. A number with a highest value takes that value, the largest the story says it accepts. An object's fields take
+ * theirs, a list many items, a mixed union its first member that has a worst case: what the type allows at its fullest.
  *
  * @module
  */
 import { type PanelProp } from "../argTypes.ts";
-import type { PanelArgs } from "../messages.ts";
-/** The worst text: a long one, with a word that cannot break. */
-export declare const WORST_ARG_TEXT = "A label long enough to wrap onto several lines in any box it is given, with words of every length in it Supercalifragilisticexpialidocious_with_no_place_to_break_it_at_all_1234567890";
+import type { ArgValue, PanelArgs } from "../messages.ts";
+import type { NamedValues } from "../namedValues.ts";
+import type { ValueShape } from "../valueShape.ts";
 /**
  * The worst-case args for the props the panel can set.
  *
  * @param props - the props the panel can set.
+ * @param namedValues - the source's named values; none by default.
+ * @param worstOfShape - gives a prop with a shape its worst value, once its module loaded; until then they keep theirs.
  * @returns the args, by prop name; empty when no prop takes a text or a number.
  */
-export declare const worstArgs: (props: readonly PanelProp[]) => PanelArgs;
+export declare const worstArgs: (props: readonly PanelProp[], namedValues?: NamedValues, worstOfShape?: (shape: ValueShape, namedValues: NamedValues) => ArgValue | undefined) => PanelArgs;
 /**
  * Whether the values shown are the worst case: every worst-case arg is set to its worst value.
  *

package/dist/src/shell/worstArgs.js

@@ -6,17 +6,16 @@
  * The values are the ones `forgebook new` writes in a story's worst case (`worstCase.ts`). The text joins the long text
  * and the unbreakable word, so one value shows both a box that must wrap and one that must cut or scroll. A colour, a
  * date and a prop whose `argTypes` give it a list keep their values: a long text there is not a case, only an invalid
- * value. A number with a highest value takes that value, the largest the story says it accepts.
+ * value. A number with a highest value takes that value, the largest the story says it accepts. An object's fields take
+ * theirs, a list many items, a mixed union its first member that has a worst case: what the type allows at its fullest.
  *
  * @module
  */
 import { isColorProp } from "../argTypes.js";
-import { WORST_NUMBER, WORST_TEXT, WORST_WORD } from "../worstCase.js";
-/** The worst text: a long one, with a word that cannot break. */
-export const WORST_ARG_TEXT = `${WORST_TEXT} ${WORST_WORD}`;
+import { WORST_ARG_TEXT, WORST_NUMBER } from "../worstCase.js";
 /** Whether a prop is set as a text: of kind text, or a node that takes one, with no other control named. */
 const isText = (prop) => (prop.kind === "text" || (prop.kind === "other" && prop.canTakeText === true)) &&
-    (prop.control === undefined || prop.control === "text") &&
+    (prop.control === undefined || prop.control === "text" || prop.control === "textarea") &&
     !isColorProp(prop);
 /** Whether a prop is set as a number, with no other control named. */
 const isNumber = (prop) => prop.kind === "number" &&
@@ -25,9 +24,15 @@ const isNumber = (prop) => prop.kind === "number" &&
  * The worst-case args for the props the panel can set.
  *
  * @param props - the props the panel can set.
+ * @param namedValues - the source's named values; none by default.
+ * @param worstOfShape - gives a prop with a shape its worst value, once its module loaded; until then they keep theirs.
  * @returns the args, by prop name; empty when no prop takes a text or a number.
  */
-export const worstArgs = (props) => Object.fromEntries(props.flatMap((prop) => {
+export const worstArgs = (props, namedValues = {}, worstOfShape) => Object.fromEntries(props.flatMap((prop) => {
+    if (prop.shape !== undefined && (prop.control === undefined || prop.control === "object")) {
+        const worst = worstOfShape?.(prop.shape, namedValues);
+        return worst === undefined ? [] : [[prop.name, worst]];
+    }
     if (isText(prop))
         return [[prop.name, WORST_ARG_TEXT]];
     if (isNumber(prop))
@@ -42,5 +47,7 @@ export const worstArgs = (props) => Object.fromEntries(props.flatMap((prop) => {
  */
 export const isWorstCase = (worst, values) => {
     const entries = Object.entries(worst);
-    return entries.length > 0 && entries.every(([name, value]) => values[name] === value);
+    // compared as text: a list or an object comes back from the address as another one that reads the same
+    return (entries.length > 0 &&
+        entries.every(([name, value]) => JSON.stringify(values[name]) === JSON.stringify(value)));
 };

package/dist/src/shellTheme.d.ts

@@ -19,7 +19,7 @@ export declare const LIGHT_PALETTE: Palette;
 /** The shell's dark palette, every role. */
 export declare const DARK_PALETTE: Palette;
 /** The text roles, each read on every ground. */
-export declare const TEXT_ROLES: readonly ["text", "text-secondary", "text-tertiary", "accent-text", "danger-text"];
+export declare const TEXT_ROLES: readonly ["text", "text-secondary", "text-tertiary", "accent-text", "danger-text", "caution-text", "positive-text"];
 /** The grounds text is read on. */
 export declare const GROUND_ROLES: readonly ["window", "sidebar", "surface"];
 /** The code roles, read on the code background. */

package/dist/src/shellTheme.js

@@ -14,6 +14,8 @@ export const LIGHT_PALETTE = {
     "accent-text": "#0059d2",
     "on-accent": "#fff",
     "danger-text": "#bc1f16",
+    "caution-text": "#935200",
+    "positive-text": "#077229",
     "code-keyword": "#7036c4",
     "code-type": "#0059d2",
     "code-string": "#077229",
@@ -46,6 +48,8 @@ export const DARK_PALETTE = {
     "accent-text": "#7ab3ff",
     "on-accent": "#fff",
     "danger-text": "#ff8a80",
+    "caution-text": "#f2b46b",
+    "positive-text": "#7fdc8f",
     "code-keyword": "#c9a8ff",
     "code-type": "#7ab3ff",
     "code-string": "#7fdc8f",
@@ -75,6 +79,8 @@ const THEME_ROLES = [
     "accent",
     "accent-text",
     "danger-text",
+    "caution-text",
+    "positive-text",
     "code-keyword",
     "code-type",
     "code-string",
@@ -87,7 +93,15 @@ const TEXT_CONTRAST = 4.5;
 /** The contrast a focus ring needs against what it sits on, WCAG 2.1 AA for non-text. */
 const FOCUS_CONTRAST = 3;
 /** The text roles, each read on every ground. */
-export const TEXT_ROLES = ["text", "text-secondary", "text-tertiary", "accent-text", "danger-text"];
+export const TEXT_ROLES = [
+    "text",
+    "text-secondary",
+    "text-tertiary",
+    "accent-text",
+    "danger-text",
+    "caution-text",
+    "positive-text"
+];
 /** The grounds text is read on. */
 export const GROUND_ROLES = ["window", "sidebar", "surface"];
 /** The code roles, read on the code background. */

package/dist/src/shellTheme.types.d.ts

@@ -32,6 +32,10 @@ export type ShellPalette = {
     readonly "accent-text": string;
     /** Errors, as text. */
     readonly "danger-text": string;
+    /** A warning, as text: a status's badge in the `caution` tone. */
+    readonly "caution-text": string;
+    /** Something done or safe, as text: a status's badge in the `positive` tone. */
+    readonly "positive-text": string;
     /** Keywords in code. */
     readonly "code-keyword": string;
     /** Types in code. */

package/dist/src/shellWord.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A file's name as one word of a command an agent will run: a name comes from a branch that may not be trusted, and
+ * `$(…)` in it must stay text. Shared by what `verify` and `visibility` tell an agent to run.
+ *
+ * @module
+ */
+/**
+ * The word.
+ *
+ * @param path - the file's name.
+ */
+export declare const shellWord: (path: string) => string;

package/dist/src/shellWord.js

@@ -0,0 +1,15 @@
+/**
+ * A file's name as one word of a command an agent will run: a name comes from a branch that may not be trusted, and
+ * `$(…)` in it must stay text. Shared by what `verify` and `visibility` tell an agent to run.
+ *
+ * @module
+ */
+/**
+ * The word.
+ *
+ * @param path - the file's name.
+ */
+export const shellWord = (path) => {
+    const named = path.startsWith("-") ? `./${path}` : path;
+    return /^[\w./@+-]+$/.test(named) ? named : `'${named.replaceAll("'", `'\\''`)}'`;
+};

package/dist/src/sourceFiles.js

@@ -14,7 +14,8 @@ export const sourceFiles = (source) => {
         stories: Object.assign({}, ...source.files.map((group) => group.stories)),
         docs: Object.assign({}, ...source.files.map((group) => group.docs)),
         code: Object.assign({}, ...source.files.map((group) => group.code)),
-        pages: Object.assign({}, ...source.files.map((group) => group.pages))
+        pages: Object.assign({}, ...source.files.map((group) => group.pages)),
+        problems: source.files.flatMap((group) => group.problems ?? [])
     };
     MERGED.set(source, merged);
     return merged;