forgebook 0.1.8 → 0.2.0

package/dist/src/searchMarks.js

@@ -0,0 +1,165 @@
+/**
+ * Where a text holds what was searched for: the stretches to mark, and the part of a long text worth showing.
+ *
+ * @remarks
+ * A person has to see why a result is there, so the marks follow the matching rules exactly (`searchMatch.ts`): a
+ * camel-case name is marked word by word, a word found by its start only as far as it was typed, and a synonym where it
+ * stands. Pure.
+ *
+ * @module
+ */
+import { foldedText, meaningsOf, wordMatch } from "./searchMatch.js";
+/** How long a snippet is, in characters. */
+const SNIPPET_LENGTH = 110;
+/** How much of a snippet comes before its first match, in characters. */
+const LEAD_IN = 28;
+/** What stands for the text left out of a snippet. */
+const ELLIPSIS = "…";
+/** The characters two texts start with in common. */
+const commonStart = (first, second) => {
+    let length = 0;
+    while (length < first.length && first[length] === second[length])
+        length += 1;
+    return length;
+};
+/** The pieces of a run of letters a camel-case name splits it into, with where each starts. */
+const piecesOf = (token) => {
+    let offset = 0;
+    return token
+        .replace(/(\p{Ll})(\p{Lu})/gu, "$1 $2")
+        .split(" ")
+        .map((text) => {
+        const piece = { offset, text };
+        offset += text.length;
+        return piece;
+    });
+};
+/** How long a word has to be to be marked by its start: `the` lights up every `theme` of a sentence otherwise. */
+const MIN_MARKED_START = 4;
+/** Where a run of letters answers one word; a whole name typed as one word marks the whole name. */
+const tokenMatches = (token, whole, at, word, isTyped) => {
+    const meanings = meaningsOf(word);
+    // an accent folded into two letters moves every place after it: the run is then marked whole or not at all
+    if (whole.length !== token.length) {
+        return wordMatch(whole, word, meanings) === undefined
+            ? []
+            : [{ start: at, end: at + token.length, word }];
+    }
+    const wholeMatch = wordMatch(whole, word, meanings);
+    if (wholeMatch === "exact")
+        return [{ start: at, end: at + token.length, word }];
+    if (wholeMatch === "start" && isTyped)
+        return [{ start: at, end: at + commonStart(whole, word), word }];
+    return piecesOf(token).flatMap(({ offset, text }) => {
+        const piece = foldedText(text);
+        const found = wordMatch(piece, word, meanings);
+        if (found === undefined || (found === "start" && !isTyped))
+            return [];
+        const length = found === "exact" ? piece.length : commonStart(piece, word);
+        return [{ start: at + offset, end: at + offset + length, word }];
+    });
+};
+/** Where one run of letters answers the query. */
+const runMatches = (token, at, words) => {
+    const whole = foldedText(token);
+    const last = words.at(-1);
+    return words.flatMap((word) => tokenMatches(token, whole, at, word, word === last || word.length >= MIN_MARKED_START));
+};
+/** Whether a character belongs to a word; none at a text's edge. */
+const isWordCharacter = (character) => character !== undefined && /[\p{L}\p{M}\p{N}]/u.test(character);
+/** Where a text holds a query's phrase, each stretch one match; none when an accent moved the text's places. */
+const phraseMatches = (text, phrase, word) => {
+    const folded = foldedText(text);
+    if (folded.length !== text.length)
+        return [];
+    const matches = [];
+    for (let start = folded.indexOf(phrase); start !== -1; start = folded.indexOf(phrase, start + 1)) {
+        const end = start + phrase.length;
+        const isOverlap = (matches.at(-1)?.end ?? 0) > start;
+        if (!isOverlap && !isWordCharacter(folded[start - 1]) && !isWordCharacter(folded[end]))
+            matches.push({ start, end, word });
+    }
+    return matches;
+};
+/** Every stretch of a text that answers a word, in order and without overlaps. */
+const matchesOf = (text, { words, phrase }) => {
+    const whole = phrase === undefined ? [] : phraseMatches(text, phrase, phrase);
+    if (whole.length > 0)
+        return whole;
+    const matches = [...text.matchAll(/[\p{L}\p{M}\p{N}]+/gu)]
+        .flatMap((run) => runMatches(run[0], run.index, words))
+        .toSorted((first, second) => first.start - second.start || second.end - first.end);
+    let reached = 0;
+    return matches.filter((match) => {
+        if (match.start < reached)
+            return false;
+        reached = match.end;
+        return true;
+    });
+};
+/** A stretch of a text as pieces, marked where it matched. */
+const piecesBetween = (text, matches, from, to) => {
+    const pieces = [];
+    let reached = from;
+    for (const match of matches) {
+        if (match.start < from || match.end > to)
+            continue;
+        if (match.start > reached)
+            pieces.push({ text: text.slice(reached, match.start), isMatch: false });
+        pieces.push({ text: text.slice(match.start, match.end), isMatch: true });
+        reached = match.end;
+    }
+    if (reached < to)
+        pieces.push({ text: text.slice(reached, to), isMatch: false });
+    return pieces;
+};
+/**
+ * A short text with what matched marked.
+ *
+ * @param text - the text.
+ * @param query - what was searched for.
+ */
+export const markedText = (text, query) => piecesBetween(text, matchesOf(text, query), 0, text.length);
+/** How many different words of the query a snippet starting at a match would show. */
+const wordsShown = (matches, from) => new Set(matches
+    .filter((match) => match === from || (match.start >= from.start && match.end <= from.start + SNIPPET_LENGTH - LEAD_IN))
+    .map((match) => match.word)).size;
+/** The match a snippet starts around: the first that shows the most words of the query. */
+const bestStart = (matches) => {
+    let best;
+    let bestCount = 0;
+    for (const match of matches) {
+        const count = wordsShown(matches, match);
+        if (count > bestCount) {
+            best = match;
+            bestCount = count;
+        }
+    }
+    return best;
+};
+/**
+ * The part of a text worth showing, with what matched marked: around the matches that show most of the query, cut
+ * between words; the text's start when nothing in it matched.
+ *
+ * @param text - the text.
+ * @param query - what was searched for.
+ */
+export const snippetOf = (text, query) => {
+    const matches = matchesOf(text, query);
+    if (text.length <= SNIPPET_LENGTH)
+        return piecesBetween(text, matches, 0, text.length);
+    const best = bestStart(matches);
+    const around = best?.start ?? 0;
+    const roughStart = Math.max(0, around - LEAD_IN);
+    const nextSpace = roughStart === 0 ? 0 : text.indexOf(" ", roughStart) + 1;
+    const start = nextSpace === 0 || nextSpace > around ? roughStart : nextSpace;
+    // a sentence longer than a snippet still shows whole, or it would show unmarked
+    const roughEnd = Math.min(text.length, Math.max(start + SNIPPET_LENGTH, best?.end ?? 0));
+    const lastSpace = text.lastIndexOf(" ", roughEnd);
+    const end = roughEnd === text.length || lastSpace < (best?.end ?? around) ? roughEnd : lastSpace;
+    return [
+        ...(start === 0 ? [] : [{ text: ELLIPSIS, isMatch: false }]),
+        ...piecesBetween(text, matches, start, end),
+        ...(end === text.length ? [] : [{ text: ELLIPSIS, isMatch: false }])
+    ];
+};

package/dist/src/searchMatch.d.ts

@@ -0,0 +1,58 @@
+/**
+ * How the catalogue's searches read words: what a text's words are, what a word means, and how much a word counts by
+ * where it is found.
+ *
+ * @remarks
+ * The one place both searches take this from, so a person and an agent asking the same words get the same answer:
+ * `forgebook find` ranks components with it (`vite/findComponent.ts`), the shell's search and `forgebook search` rank
+ * everything else (`search.ts`). Pure, with no model: a lexical ranking is instant, works offline and gives the same
+ * answer twice. Case and accents never count. Pure apart from a cache of what a word means.
+ *
+ * @module
+ */
+/** How much a word counts, by where it is found. */
+export declare const WEIGHTS: {
+    readonly name: 8;
+    readonly keyword: 6;
+    readonly prop: 5;
+    readonly heading: 5;
+    readonly title: 3;
+    readonly description: 2;
+    readonly story: 1;
+    readonly text: 1;
+};
+/** The places a word can be found in. */
+export type SearchPlace = keyof typeof WEIGHTS;
+/**
+ * A text as the searches compare it: lower case, without accents.
+ *
+ * @param text - any text.
+ */
+export declare const foldedText: (text: string) => string;
+/**
+ * A text's words, lower case and without accents, a camel-case name split into its words.
+ *
+ * @param text - any text.
+ */
+export declare const wordsOf: (text: string) => string[];
+/**
+ * A word and the ones it means, its plural taken off.
+ *
+ * @param word - a word, as `wordsOf` gives it.
+ */
+export declare const meaningsOf: (word: string) => readonly string[];
+/**
+ * How one of a text's words holds a word asked for: as it is, by its start, or not at all.
+ *
+ * @param held - the text's word.
+ * @param word - the word asked for.
+ * @param meanings - what it means (`meaningsOf`).
+ */
+export declare const wordMatch: (held: string, word: string, meanings: readonly string[]) => "exact" | "start" | undefined;
+/**
+ * A word's worth in something searched: where it counts most; nothing when it is not there.
+ *
+ * @param parts - its words, by where they are.
+ * @param word - the word asked for.
+ */
+export declare const worthOf: (parts: Partial<Record<SearchPlace, readonly string[]>>, word: string) => number;

package/dist/src/searchMatch.js

@@ -0,0 +1,127 @@
+/**
+ * How the catalogue's searches read words: what a text's words are, what a word means, and how much a word counts by
+ * where it is found.
+ *
+ * @remarks
+ * The one place both searches take this from, so a person and an agent asking the same words get the same answer:
+ * `forgebook find` ranks components with it (`vite/findComponent.ts`), the shell's search and `forgebook search` rank
+ * everything else (`search.ts`). Pure, with no model: a lexical ranking is instant, works offline and gives the same
+ * answer twice. Case and accents never count. Pure apart from a cache of what a word means.
+ *
+ * @module
+ */
+/** How much a word counts, by where it is found. */
+export const WEIGHTS = {
+    name: 8,
+    keyword: 6,
+    prop: 5,
+    heading: 5,
+    title: 3,
+    description: 2,
+    story: 1,
+    text: 1
+};
+/** The places, the one that counts most first. */
+const PLACES = [
+    "name",
+    "keyword",
+    "prop",
+    "heading",
+    "title",
+    "description",
+    "story",
+    "text"
+];
+/** What a match by a word's start costs against the word itself, so `card` finds `Card` before `OptionCards`. */
+const STARTING_COST = 0.5;
+/** The shortest word that matches by its start: shorter ones match too much. */
+const MIN_PREFIX = 3;
+/** Words designers and code use for the same thing, each group read as one. */
+const SYNONYMS = [
+    ["dialog", "modal", "popup", "lightbox"],
+    ["select", "dropdown", "picker", "combobox"],
+    ["button", "cta"],
+    ["tooltip", "hint"],
+    ["toast", "snackbar", "notification"],
+    ["tabs", "tabbar"],
+    ["drawer", "sheet", "sidepanel"],
+    ["badge", "tag", "chip", "pill"],
+    ["input", "textfield", "field"],
+    ["checkbox", "tick"],
+    ["switch", "toggle"],
+    ["spinner", "loader"],
+    ["card", "tile"]
+];
+/**
+ * A text as the searches compare it: lower case, without accents.
+ *
+ * @param text - any text.
+ */
+export const foldedText = (text) => text
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase();
+/**
+ * A text's words, lower case and without accents, a camel-case name split into its words.
+ *
+ * @param text - any text.
+ */
+export const wordsOf = (text) => foldedText(text.replace(/(\p{Ll})(\p{Lu})/gu, "$1 $2"))
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter((word) => word !== "");
+/** A word without its plural. */
+const singularOf = (word) => word.length > MIN_PREFIX && word.endsWith("s") ? word.slice(0, -1) : word;
+/** The meanings worked out so far: a search asks for them for every word of every text it marks. */
+const MEANINGS = new Map();
+/**
+ * A word and the ones it means, its plural taken off.
+ *
+ * @param word - a word, as `wordsOf` gives it.
+ */
+export const meaningsOf = (word) => {
+    const known = MEANINGS.get(word);
+    if (known !== undefined)
+        return known;
+    const singular = singularOf(word);
+    const meanings = [
+        ...new Set([word, singular, ...SYNONYMS.filter((group) => group.includes(singular)).flat()])
+    ];
+    MEANINGS.set(word, meanings);
+    return meanings;
+};
+/**
+ * How one of a text's words holds a word asked for: as it is, by its start, or not at all.
+ *
+ * @param held - the text's word.
+ * @param word - the word asked for.
+ * @param meanings - what it means (`meaningsOf`).
+ */
+export const wordMatch = (held, word, meanings) => {
+    if (meanings.includes(held))
+        return "exact";
+    const asked = singularOf(word);
+    return asked.length >= MIN_PREFIX && held.startsWith(asked) ? "start" : undefined;
+};
+/** How a text holds a word: as it is, by its start, which counts a little less, or not at all. */
+const heldAs = (words, word, meanings) => {
+    if (words.some((held) => meanings.includes(held)))
+        return "exact";
+    return words.some((held) => wordMatch(held, word, meanings) === "start") ? "start" : undefined;
+};
+/**
+ * A word's worth in something searched: where it counts most; nothing when it is not there.
+ *
+ * @param parts - its words, by where they are.
+ * @param word - the word asked for.
+ */
+export const worthOf = (parts, word) => {
+    const meanings = meaningsOf(word);
+    for (const place of PLACES) {
+        const found = heldAs(parts[place] ?? [], word, meanings);
+        if (found === "exact")
+            return WEIGHTS[place];
+        if (found === "start")
+            return WEIGHTS[place] - STARTING_COST;
+    }
+    return 0;
+};

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

@@ -29,16 +29,9 @@ export type A11yTabProps = {
     /** Runs the check; none when it cannot run (the compare view). */
     readonly onCheck: (() => void) | undefined;
 };
-/**
- * The tab's hint: how many rules are broken once checked.
- *
- * @param check - the check's state.
- */
-export declare const a11yHint: (check: CheckState) => string | undefined;
 /**
  * The Accessibility tab.
  *
  * @param props - the check's state and how to run it.
  */
 export declare const A11yTab: ({ check, onCheck }: A11yTabProps) => ReactNode;
-//# sourceMappingURL=A11yTab.d.ts.map

package/dist/src/shell/A11yTab.js

@@ -1,24 +1,14 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { STRINGS } from "./strings.js";
-/**
- * The tab's hint: how many rules are broken once checked.
- *
- * @param check - the check's state.
- */
-export const a11yHint = (check) => {
-    if (check.status !== "done")
-        return undefined;
-    return check.violations.length === 0 ? STRINGS.a11yPasses : STRINGS.a11yCount(check.violations.length);
-};
+import { LATER_STRINGS } from "./laterStrings.js";
 /** What the check found. */
 const CheckResult = ({ check }) => {
     if (check.status === "error") {
-        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [STRINGS.a11yError, ": ", check.message] }));
+        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [LATER_STRINGS.a11yError, ": ", check.message] }));
     }
     if (check.status !== "done")
         return null;
     if (check.violations.length === 0)
-        return _jsx("p", { className: "forgebook-prop__description", children: STRINGS.a11yNone });
+        return _jsx("p", { className: "forgebook-prop__description", children: LATER_STRINGS.a11yNone });
     return (_jsx("ul", { className: "forgebook-violations", children: check.violations.map((violation) => (_jsxs("li", { className: "forgebook-violation", "data-impact": violation.impact, children: [_jsxs("div", { className: "forgebook-violation__head", children: [_jsx("a", { className: "forgebook-violation__rule", href: violation.helpUrl, target: "_blank", rel: "noopener", children: violation.id }), violation.impact === undefined ? null : (_jsx("span", { className: "forgebook-violation__impact", children: violation.impact }))] }), _jsx("p", { className: "forgebook-prop__description", children: violation.help }), _jsx("ul", { className: "forgebook-violation__targets", children: violation.targets.map((target) => (_jsx("li", { children: _jsx("code", { children: target }) }, target))) })] }, violation.id))) }));
 };
 /**
@@ -26,5 +16,4 @@ const CheckResult = ({ check }) => {
  *
  * @param props - the check's state and how to run it.
  */
-export const A11yTab = ({ check, onCheck }) => (_jsxs("div", { className: "forgebook-prop-group", children: [_jsxs("div", { className: "forgebook-calls__head", children: [_jsx("button", { type: "button", className: "forgebook-button", disabled: onCheck === undefined || check.status === "running", onClick: onCheck, children: check.status === "running" ? STRINGS.a11yRunning : STRINGS.a11yCheck }), onCheck === undefined ? (_jsx("span", { className: "forgebook-popover__note", children: STRINGS.a11yNotInCompare })) : null] }), _jsx("div", { "aria-live": "polite", children: _jsx(CheckResult, { check: check }) })] }));
-//# sourceMappingURL=A11yTab.js.map
+export const A11yTab = ({ check, onCheck }) => (_jsxs("div", { className: "forgebook-prop-group", children: [_jsxs("div", { className: "forgebook-calls__head", children: [_jsx("button", { type: "button", className: "forgebook-button", disabled: onCheck === undefined || check.status === "running", onClick: onCheck, children: check.status === "running" ? LATER_STRINGS.a11yRunning : LATER_STRINGS.a11yCheck }), onCheck === undefined ? (_jsx("span", { className: "forgebook-popover__note", children: LATER_STRINGS.a11yNotInCompare })) : null] }), _jsx("div", { "aria-live": "polite", children: _jsx(CheckResult, { check: check }) })] }));

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

@@ -0,0 +1,25 @@
+/**
+ * Opens a component's page at the heading or the prop its address names: a piece of its own, so the page pays for it only
+ * when an address names one.
+ *
+ * @module
+ */
+import type { ReactNode, RefObject } from "react";
+import type { PageVisit } from "./useScrollMemory.ts";
+/** What it reads. */
+export type AnchorScrollProps = {
+    /** The page's scrolling element. */
+    readonly pageRef: RefObject<HTMLElement | null>;
+    /** The heading or the prop the address names. */
+    readonly anchor: string;
+    /** The visit of the page. */
+    readonly visit: PageVisit;
+    /** Whether what it names can be there: the page's text and its props arrived. */
+    readonly isReady: boolean;
+};
+/**
+ * Keeps what the address names in view; it draws nothing.
+ *
+ * @param props - the page, the anchor and the visit.
+ */
+export declare const AnchorScroll: ({ pageRef, anchor, visit, isReady }: AnchorScrollProps) => ReactNode;

package/dist/src/shell/AnchorScroll.js

@@ -0,0 +1,10 @@
+import { useAnchorScroll } from "./useAnchorScroll.js";
+/**
+ * Keeps what the address names in view; it draws nothing.
+ *
+ * @param props - the page, the anchor and the visit.
+ */
+export const AnchorScroll = ({ pageRef, anchor, visit, isReady }) => {
+    useAnchorScroll(pageRef, anchor, visit, isReady);
+    return null;
+};

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

@@ -3,17 +3,24 @@
  * (prop, type, default, what it does), never written by hand, then the same for each part the meta names in
  * `subcomponents`. The table scrolls sideways on its own when the page is narrower than it.
  *
+ * @remarks
+ * Props whose TSDoc names a group (`@group Selection`) are listed under its heading, after the props that name none
+ * (`propGroups.ts`), each open, so a reader may fold one away. A prop whose type is an object the
+ * package documents (`texts?: FileFinderTexts`) unfolds in place to list that type's members; they are drawn only
+ * once unfolded, so a library with large text types keeps a light page.
+ *
  * @module
  */
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import type { ComponentDocs } from "../componentDocs.ts";
 /**
  * The API reference.
  *
- * @param props - the component's docs, and whether it is a hook's or a function's (its stories are about logic).
+ * @param props - the component's docs, whether it is a hook's or a function's (its stories are about logic), and the
+ * prop groups its meta lists first, in order (`parameters.propGroups`), ahead of the catalogue's; none by default.
  */
-export declare const ApiReference: ({ docs, isLogic }: {
+export declare const ApiReference: ({ docs, isLogic, componentGroups }: {
     readonly docs: ComponentDocs;
     readonly isLogic: boolean;
+    readonly componentGroups?: readonly string[];
 }) => ReactNode;
-//# sourceMappingURL=ApiReference.d.ts.map

package/dist/src/shell/ApiReference.js

@@ -1,42 +1,96 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The API reference on a component's page: its props and its events, drawn from its types and TSDoc, as a table
+ * (prop, type, default, what it does), never written by hand, then the same for each part the meta names in
+ * `subcomponents`. The table scrolls sideways on its own when the page is narrower than it.
+ *
+ * @remarks
+ * Props whose TSDoc names a group (`@group Selection`) are listed under its heading, after the props that name none
+ * (`propGroups.ts`), each open, so a reader may fold one away. A prop whose type is an object the
+ * package documents (`texts?: FileFinderTexts`) unfolds in place to list that type's members; they are drawn only
+ * once unfolded, so a library with large text types keeps a light page.
+ *
+ * @module
+ */
+import { useState } from "react";
+import { groupedProps, propGroupOrder } from "../propGroups.js";
 import { Code } from "./Code.js";
 import { CodeText } from "./CodeText.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { Icon } from "./icons.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { SignatureReference } from "./SignatureReference.js";
 import { STRINGS } from "./strings.js";
 /** A prop's or an event's type as one line of TypeScript: an event's signature as an arrow. */
-const typeText = (prop) => prop.signature === undefined
-    ? prop.type
-    : `(${prop.signature.parameters.map((parameter) => `${parameter.name}: ${parameter.type}`).join(", ")}) => ${prop.signature.returns}`;
+const typeText = (row) => row.signature === undefined
+    ? row.type
+    : `(${row.signature.parameters.map((parameter) => `${parameter.name}: ${parameter.type}`).join(", ")}) => ${row.signature.returns}`;
+/** A table's first column's heading. */
+const NAME_HEADINGS = {
+    props: () => LATER_STRINGS.apiProp,
+    events: () => LATER_STRINGS.apiEvent,
+    members: () => LATER_STRINGS.apiMember
+};
+/**
+ * One row, and under it, once unfolded, the members of its object type across the whole table.
+ *
+ * @param props - the row, whether the table has a Default column, its number of columns, and the part it belongs to:
+ * the row says its name (`data-prop`), for an address to open it.
+ */
+const Row = ({ row, hasDefaults, columns, part }) => {
+    const [isOpen, setOpen] = useState(false);
+    const { members } = row;
+    return (_jsxs(_Fragment, { children: [_jsxs("tr", { "data-prop": part === undefined ? row.name : `${part}.${row.name}`, children: [_jsxs("th", { scope: "row", children: [_jsx("code", { className: "forgebook-api__name", children: row.name }), row.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null] }), _jsxs("td", { className: "forgebook-api__type", children: [_jsx(Code, { text: typeText(row), names: row.signature?.parameters.map((parameter) => parameter.name) ?? [] }), members === undefined ? null : (_jsxs("button", { type: "button", className: "forgebook-api__members-toggle", "aria-expanded": isOpen, "aria-label": `${LATER_STRINGS.membersOf(row.type)}: ${LATER_STRINGS.memberCount(members.length)}`, onClick: () => setOpen(!isOpen), children: [_jsx(Icon, { name: "chevronRight", size: 12 }), LATER_STRINGS.memberCount(members.length)] }))] }), hasDefaults ? (_jsx("td", { children: row.defaultValue === undefined ? null : (_jsx("code", { className: "forgebook-inline-code", children: row.defaultValue })) })) : null, _jsx("td", { children: _jsx(CodeText, { text: row.description }) })] }), members !== undefined && isOpen ? (_jsx("tr", { className: "forgebook-api__members", children: _jsx("td", { colSpan: columns, children: _jsx(PropTable, { rows: members, kind: "members", label: LATER_STRINGS.membersOf(row.type), part: part === undefined ? row.name : `${part}.${row.name}` }) }) })) : null] }));
+};
 /**
- * A table of props or events: the Default column only when one of them has a default.
+ * A table of props, events or members: the Default column only when one of them has a default.
  *
- * @param props - the props or the events, and which of the two they are.
+ * @param props - the rows, what they are, the table's name when it needs one (a members table), and the part they
+ * belong to.
  */
-const PropTable = ({ props, isEvents }) => {
-    const hasDefaults = !isEvents && props.some((prop) => prop.defaultValue !== undefined);
-    return (_jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: isEvents ? STRINGS.apiEvent : STRINGS.apiProp }), _jsx("th", { scope: "col", children: isEvents ? STRINGS.apiSignature : STRINGS.apiType }), hasDefaults ? _jsx("th", { scope: "col", children: STRINGS.apiDefault }) : null, _jsx("th", { scope: "col", children: STRINGS.apiWhat })] }) }), _jsx("tbody", { children: props.map((prop) => (_jsxs("tr", { children: [_jsxs("th", { scope: "row", children: [_jsx("code", { className: "forgebook-api__name", children: prop.name }), prop.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null] }), _jsx("td", { className: "forgebook-api__type", children: _jsx(Code, { text: typeText(prop), names: prop.signature?.parameters.map((parameter) => parameter.name) ?? [] }) }), hasDefaults ? (_jsx("td", { children: prop.defaultValue === undefined ? null : (_jsx("code", { className: "forgebook-inline-code", children: prop.defaultValue })) })) : null, _jsx("td", { children: _jsx(CodeText, { text: prop.description }) })] }, prop.name))) })] }) }));
+const PropTable = ({ rows, kind, label, part }) => {
+    const hasDefaults = kind !== "events" && rows.some((row) => row.defaultValue !== undefined);
+    return (_jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", "aria-label": label, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: NAME_HEADINGS[kind]() }), _jsx("th", { scope: "col", children: kind === "events" ? LATER_STRINGS.apiSignature : STRINGS.apiType }), hasDefaults ? _jsx("th", { scope: "col", children: LATER_STRINGS.apiDefault }) : null, _jsx("th", { scope: "col", children: STRINGS.apiWhat })] }) }), _jsx("tbody", { children: rows.map((row) => (_jsx(Row, { row: row, hasDefaults: hasDefaults, columns: hasDefaults ? 4 : 3, part: part }, row.name))) })] }) }));
 };
 /**
- * A component's or a part's props, then its events under their own heading.
+ * A group of props: the props that name none as a table alone, a named group under its heading, open until a reader
+ * folds it.
  *
- * @param props - the props, and the level of the events' heading: under the section's, or under a part's.
+ * @param props - the group, the level of its heading, and the part it belongs to.
  */
-const PropsAndEvents = ({ props, eventsLevel }) => {
-    const EventsHeading = eventsLevel === 3 ? "h3" : "h4";
-    const values = props.filter((prop) => prop.kind !== "event");
+const GroupTable = ({ group, level, part }) => {
+    if (group.name === undefined)
+        return _jsx(PropTable, { rows: group.props, kind: "props", part: part });
+    const Heading = level === 3 ? "h3" : "h4";
+    return (_jsxs("details", { className: "forgebook-fold forgebook-api__group", open: true, children: [_jsxs("summary", { className: "forgebook-fold__summary", children: [_jsx(Icon, { name: "chevronRight", size: 14 }), _jsx(Heading, { className: "forgebook-fold__name", children: group.name }), _jsx("span", { className: "forgebook-fold__count", children: STRINGS.propCount(group.props.length) })] }), _jsx(PropTable, { rows: group.props, kind: "props", part: part })] }));
+};
+/**
+ * A component's or a part's props in their groups, then its events under their own heading.
+ *
+ * @param props - the props, the groups to list first, the level of the headings (under the section's, or under a
+ * part's) and the part they belong to.
+ */
+const PropsAndEvents = ({ props, groupOrder, level, part }) => {
+    const EventsHeading = level === 3 ? "h3" : "h4";
+    const groups = groupedProps(props.filter((prop) => prop.kind !== "event"), groupOrder);
     const events = props.filter((prop) => prop.kind === "event");
-    return (_jsxs(_Fragment, { children: [values.length === 0 ? null : _jsx(PropTable, { props: values, isEvents: false }), events.length === 0 ? null : (_jsxs(_Fragment, { children: [_jsx(EventsHeading, { children: STRINGS.events }), _jsx(PropTable, { props: events, isEvents: true })] }))] }));
+    return (_jsxs(_Fragment, { children: [groups.map((group) => (_jsx(GroupTable, { group: group, level: level, part: part }, group.name ?? ""))), events.length === 0 ? null : (_jsxs(_Fragment, { children: [_jsx(EventsHeading, { children: LATER_STRINGS.events }), _jsx(PropTable, { rows: events, kind: "events", part: part })] }))] }));
 };
 /**
  * A part's reference: its name, its summary, its props and events.
  *
- * @param props - the part's docs.
+ * @param props - the part's docs, and the groups to list first.
  */
-const SubcomponentReference = ({ docs }) => (_jsxs("section", { className: "forgebook-api__subcomponent", "aria-label": docs.name, children: [_jsx("h3", { children: _jsx("code", { className: "forgebook-inline-code", children: docs.name }) }), docs.description === "" ? null : (_jsx("p", { children: _jsx(CodeText, { text: docs.description }) })), _jsx(PropsAndEvents, { props: docs.props, eventsLevel: 4 })] }));
+const SubcomponentReference = ({ docs, groupOrder }) => (_jsxs("section", { className: "forgebook-api__subcomponent", "aria-label": docs.name, "data-prop": docs.name, children: [_jsx("h3", { children: _jsx("code", { className: "forgebook-inline-code", children: docs.name }) }), docs.description === "" ? null : (_jsx("p", { children: _jsx(CodeText, { text: docs.description }) })), _jsx(PropsAndEvents, { props: docs.props, groupOrder: groupOrder, level: 4, part: docs.name })] }));
+/** No group named first. */
+const NO_GROUPS = [];
 /**
  * The API reference.
  *
- * @param props - the component's docs, and whether it is a hook's or a function's (its stories are about logic).
+ * @param props - the component's docs, whether it is a hook's or a function's (its stories are about logic), and the
+ * prop groups its meta lists first, in order (`parameters.propGroups`), ahead of the catalogue's; none by default.
  */
-export const ApiReference = ({ docs, isLogic }) => (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-api", children: [_jsx("h2", { id: "forgebook-api", children: STRINGS.apiReference }), isLogic && docs.signature !== undefined ? (_jsx(SignatureReference, { name: docs.name, signature: docs.signature })) : (_jsx(PropsAndEvents, { props: docs.props, eventsLevel: 3 })), docs.subcomponents.map((subcomponent) => (_jsx(SubcomponentReference, { docs: subcomponent }, subcomponent.name)))] }));
-//# sourceMappingURL=ApiReference.js.map
+export const ApiReference = ({ docs, isLogic, componentGroups = NO_GROUPS }) => {
+    const groupOrder = propGroupOrder(componentGroups, useCatalogue().propGroups);
+    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-api", children: [_jsx("h2", { id: "forgebook-api", children: LATER_STRINGS.apiReference }), isLogic && docs.signature !== undefined ? (_jsx(SignatureReference, { name: docs.name, signature: docs.signature })) : (_jsx(PropsAndEvents, { props: docs.props, groupOrder: groupOrder, level: 3 })), docs.subcomponents.map((subcomponent) => (_jsx(SubcomponentReference, { docs: subcomponent, groupOrder: groupOrder }, subcomponent.name)))] }));
+};

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

@@ -11,5 +11,4 @@ import type { AppearanceState } from "./useAppearance.ts";
  *
  * @param props - the appearance shown and its setter.
  */
-export declare const AppearanceMenu: ({ appearance, setAppearance }: AppearanceState) => ReactNode;
-//# sourceMappingURL=AppearanceMenu.d.ts.map
+export declare const AppearanceMenu: ({ appearance, setAppearance, offered }: AppearanceState) => ReactNode;

package/dist/src/shell/AppearanceMenu.js

@@ -6,23 +6,26 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * @module
  */
 import { useId } from "react";
-import { APPEARANCES } from "../catalogue.js";
 import { Icon } from "./icons.js";
 import { STRINGS } from "./strings.js";
 import { usePopover } from "./usePopover.js";
 /** Each appearance's icon. */
-const ICONS = { light: "sun", dark: "moon", system: "monitor" };
+const ICONS = {
+    light: "sun",
+    dark: "moon",
+    system: "monitor",
+    story: "eye"
+};
 /**
  * The appearance menu.
  *
  * @param props - the appearance shown and its setter.
  */
-export const AppearanceMenu = ({ appearance, setAppearance }) => {
+export const AppearanceMenu = ({ appearance, setAppearance, offered }) => {
     const { isOpen, isDrawn, setIsOpen, buttonRef, panelRef, panelId } = usePopover();
     const name = useId();
-    return (_jsxs("div", { className: "forgebook-appearance", children: [_jsxs("button", { ref: buttonRef, type: "button", className: "forgebook-button forgebook-button--quiet", "aria-expanded": isOpen, "aria-controls": panelId, onClick: (event) => setIsOpen(!isOpen, event), children: [_jsx(Icon, { name: ICONS[appearance], size: 14 }), STRINGS.appearanceOf(STRINGS.appearances[appearance])] }), isDrawn ? (_jsx("div", { ref: panelRef, id: panelId, className: "forgebook-popover forgebook-popover--up", role: "dialog", "aria-label": STRINGS.appearance, children: _jsxs("fieldset", { className: "forgebook-choices", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: STRINGS.appearance }), APPEARANCES.map((each) => (_jsxs("label", { className: "forgebook-choice", children: [_jsx("input", { type: "radio", name: name, checked: each === appearance, onChange: () => {
+    return (_jsxs("div", { className: "forgebook-appearance", children: [_jsxs("button", { ref: buttonRef, type: "button", className: "forgebook-button forgebook-button--quiet", "aria-expanded": isOpen, "aria-controls": panelId, onClick: (event) => setIsOpen(!isOpen, event), children: [_jsx(Icon, { name: ICONS[appearance], size: 14 }), STRINGS.appearanceOf(STRINGS.appearances[appearance])] }), isDrawn ? (_jsx("div", { ref: panelRef, id: panelId, className: "forgebook-popover forgebook-popover--up", role: "dialog", "aria-label": STRINGS.appearance, children: _jsxs("fieldset", { className: "forgebook-choices", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: STRINGS.appearance }), offered.map((each) => (_jsxs("label", { className: "forgebook-choice", children: [_jsx("input", { type: "radio", name: name, checked: each === appearance, onChange: () => {
                                         setAppearance(each);
                                         setIsOpen(false);
                                     } }), _jsx(Icon, { name: ICONS[each], size: 14 }), STRINGS.appearances[each]] }, each)))] }) })) : null] }));
 };
-//# sourceMappingURL=AppearanceMenu.js.map