forgebook 0.1.3 → 0.1.4

package/dist/src/vite/usageGraph.js

@@ -0,0 +1,246 @@
+/**
+ * What each story renders and what each module imports, read from the TypeScript programs the docs already build:
+ * the facts "Used in" is joined from (`usageModule.ts`).
+ *
+ * @remarks
+ * Runs in the docs worker (`docsWorker.ts`), which holds the programs; a package's first read builds its program,
+ * the API tables reuse it. A story renders the components its JSX names, resolved by the type checker as its types are
+ * (a package-name import, an alias, `<Menu.Item>`); a component declared in the story file itself (a scene) is followed
+ * into its own JSX; a story without JSX renders its meta's component. A component is known by the file that declares
+ * it and its name there, so two imports of one component are one. The import graph holds the modules the rendered
+ * components reach through the package's own imports, never a dependency's (`node_modules`): "used through" follows
+ * those edges. A lowercase tag is an element (`<div>`), not a component. A component reached only through code the
+ * checker cannot follow (a computed lazy import, a component handed in as a prop) is not found.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { programFor } from "./docsProgram.js";
+/**
+ * The symbol a name stands for, through its imports and re-exports.
+ *
+ * @param symbol - the symbol at the name.
+ * @param checker - the program's checker.
+ */
+const declared = (symbol, checker) => symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0
+    ? checker.getAliasedSymbol(symbol)
+    : symbol;
+/**
+ * A component's reference from its symbol: the file of its first declaration, and its name.
+ *
+ * @param symbol - the component's symbol.
+ */
+const refOf = (symbol) => {
+    const declaration = symbol?.declarations?.[0];
+    if (symbol === undefined || declaration === undefined)
+        return undefined;
+    return { file: declaration.getSourceFile().fileName, name: symbol.getName() };
+};
+/**
+ * An expression without the wrappers a meta is written with (`satisfies Meta<…>`, `as Meta`, parentheses).
+ *
+ * @param expression - the expression.
+ */
+const unwrap = (expression) => {
+    if (ts.isSatisfiesExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isParenthesizedExpression(expression))
+        return unwrap(expression.expression);
+    return expression;
+};
+/**
+ * The meta's object: the default export, written inline or as a constant.
+ *
+ * @param source - the story file.
+ * @param checker - the program's checker.
+ */
+const metaObject = (source, checker) => {
+    const assignment = source.statements.find((statement) => ts.isExportAssignment(statement) && !statement.isExportEquals);
+    if (assignment === undefined)
+        return undefined;
+    let value = unwrap(assignment.expression);
+    if (ts.isIdentifier(value)) {
+        const declaration = declared(checker.getSymbolAtLocation(value), checker)?.valueDeclaration;
+        if (declaration !== undefined &&
+            ts.isVariableDeclaration(declaration) &&
+            declaration.initializer !== undefined)
+            value = unwrap(declaration.initializer);
+    }
+    return ts.isObjectLiteralExpression(value) ? value : undefined;
+};
+/**
+ * The meta's component, as the checker resolves its `component` property.
+ *
+ * @param meta - the meta's object.
+ * @param checker - the program's checker.
+ */
+const metaComponent = (meta, checker) => {
+    const property = meta.properties.find((each) => each.name !== undefined && each.name.getText() === "component");
+    if (property === undefined)
+        return undefined;
+    if (ts.isShorthandPropertyAssignment(property))
+        return refOf(declared(checker.getShorthandAssignmentValueSymbol(property), checker));
+    if (ts.isPropertyAssignment(property))
+        return refOf(declared(checker.getSymbolAtLocation(unwrap(property.initializer)), checker));
+    return undefined;
+};
+/**
+ * The symbol a JSX element's tag stands for; none for an element of the page (a lowercase name, `<div>`).
+ *
+ * @param element - the element's opening or self-closing tag.
+ * @param checker - the program's checker.
+ */
+const tagSymbol = (element, checker) => {
+    const tag = element.tagName;
+    if (ts.isIdentifier(tag) && /^[a-z]/.test(tag.text))
+        return undefined;
+    return declared(checker.getSymbolAtLocation(tag), checker);
+};
+/**
+ * The components a node's JSX names: those declared elsewhere as references, those declared in the story file followed
+ * into their own declarations, each declaration once.
+ *
+ * @param node - the story's node.
+ * @param source - the story file.
+ * @param checker - the program's checker.
+ * @param seen - the declarations already followed.
+ */
+const jsxRenders = (node, source, checker, seen) => {
+    const found = [];
+    const named = (symbol) => {
+        const declaration = symbol?.declarations?.[0];
+        const isLocal = declaration !== undefined && declaration.getSourceFile() === source;
+        if (!isLocal) {
+            const ref = refOf(symbol);
+            if (ref !== undefined)
+                found.push(ref);
+            return;
+        }
+        if (seen.has(declaration))
+            return;
+        seen.add(declaration);
+        found.push(...jsxRenders(declaration, source, checker, seen));
+    };
+    const visit = (current) => {
+        if (ts.isJsxOpeningElement(current) || ts.isJsxSelfClosingElement(current))
+            named(tagSymbol(current, checker));
+        ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return found;
+};
+/**
+ * References without repeats, in their first order.
+ *
+ * @param refs - the references.
+ */
+const unique = (refs) => {
+    const keys = new Set();
+    return refs.filter((ref) => {
+        const key = `${ref.file}#${ref.name}`;
+        if (keys.has(key))
+            return false;
+        keys.add(key);
+        return true;
+    });
+};
+/**
+ * One story file's facts, from the program that holds it.
+ *
+ * @param request - the story file and its stories' exports.
+ * @param program - the program.
+ */
+const fileUsage = (request, program) => {
+    const source = program.getSourceFile(request.storyFile);
+    if (source === undefined)
+        return undefined;
+    const checker = program.getTypeChecker();
+    const meta = metaObject(source, checker);
+    const component = meta === undefined ? undefined : metaComponent(meta, checker);
+    const moduleSymbol = checker.getSymbolAtLocation(source);
+    const exported = moduleSymbol === undefined ? [] : checker.getExportsOfModule(moduleSymbol);
+    const stories = request.exports.map((exportName) => {
+        const symbol = declared(exported.find((each) => each.getName() === exportName), checker);
+        const declaration = symbol?.declarations?.[0];
+        const named = declaration === undefined ? [] : jsxRenders(declaration, source, checker, new Set([declaration]));
+        const renders = named.length === 0 && component !== undefined ? [component] : unique(named);
+        return { exportName, renders };
+    });
+    return { storyFile: request.storyFile, ...(component === undefined ? {} : { component }), stories };
+};
+/**
+ * The package's own modules a module imports or re-exports from, resolved as its program resolves them.
+ *
+ * @param source - the module.
+ * @param program - its program.
+ * @param cache - the program's resolution cache.
+ */
+const importsOf = (source, program, cache) => {
+    const targets = [];
+    for (const statement of source.statements) {
+        const specifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) &&
+            statement.moduleSpecifier !== undefined &&
+            ts.isStringLiteral(statement.moduleSpecifier)
+            ? statement.moduleSpecifier.text
+            : undefined;
+        if (specifier === undefined)
+            continue;
+        const resolved = ts.resolveModuleName(specifier, source.fileName, program.getCompilerOptions(), ts.sys, cache).resolvedModule;
+        if (resolved !== undefined && !resolved.isExternalLibraryImport)
+            targets.push(resolved.resolvedFileName);
+    }
+    return targets;
+};
+/**
+ * The import graph of the modules the given files reach, through the package's own imports.
+ *
+ * @param starts - the files to start from.
+ * @param programs - the programs that may hold them.
+ */
+const reachedImports = (starts, programs) => {
+    const caches = new Map(programs.map((program) => [
+        program,
+        ts.createModuleResolutionCache(program.getCurrentDirectory(), (name) => name, program.getCompilerOptions())
+    ]));
+    const imports = {};
+    const queue = [...starts];
+    while (queue.length > 0) {
+        const file = queue.pop() ?? "";
+        if (file in imports)
+            continue;
+        const program = programs.find((candidate) => candidate.getSourceFile(file) !== undefined);
+        const source = program?.getSourceFile(file);
+        const cache = program === undefined ? undefined : caches.get(program);
+        const targets = program === undefined || source === undefined || cache === undefined
+            ? []
+            : importsOf(source, program, cache);
+        imports[file] = targets;
+        queue.push(...targets);
+    }
+    return imports;
+};
+/**
+ * The facts of a group of story files: what each story renders, and the import graph the rendered components reach.
+ *
+ * @param requests - the story files and their stories' exports.
+ * @returns the facts, or why a story file's program could not be read.
+ */
+export const usageGraph = (requests) => {
+    const files = [];
+    const programs = new Set();
+    for (const request of requests) {
+        const docsProgram = programFor(request.storyFile);
+        if (typeof docsProgram === "string")
+            return docsProgram;
+        programs.add(docsProgram.program);
+        const usage = fileUsage(request, docsProgram.program);
+        if (usage !== undefined)
+            files.push(usage);
+    }
+    const starts = files.flatMap((file) => [
+        ...(file.component === undefined ? [] : [file.component.file]),
+        ...file.stories.flatMap((story) => story.renders.map((ref) => ref.file))
+    ]);
+    return { files, imports: reachedImports([...new Set(starts)], [...programs]) };
+};
+//# sourceMappingURL=usageGraph.js.map

package/dist/src/vite/usageGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageGraph.js","sourceRoot":"","sources":["../../../src/vite/usageGraph.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,33 @@
+/**
+ * "Used in" joined from the facts the docs worker reads (`usageGraph.ts`): for each component of a `?forgebook-files`
+ * group, the other components whose stories render it or render a component whose modules import it.
+ *
+ * @remarks
+ * A story uses a component directly when its JSX renders it, and through another when a component it renders reaches
+ * the component's file through the package's own imports, followed all the way (Tree renders Row, Row renders
+ * DropLine: Tree's stories use DropLine). The file of a component the story renders counts only when an import reaches
+ * it, so a file's other exports are not used just for sitting beside one. The component's own stories, the components
+ * its meta names in `related`, and another page of the same component (two story files with one meta component) are
+ * left out. Pure: facts in, index out.
+ *
+ * @module
+ */
+import { type UsageIndex } from "../usedIn.ts";
+import type { UsageGraph } from "./usageGraph.ts";
+/** What the join knows of a story file besides its facts: its component's title and its meta's `related`. */
+export type UsageFile = {
+    /** The story file's absolute path. */
+    readonly storyFile: string;
+    /** Its title. */
+    readonly title: string;
+    /** The titles its meta names in `related`. */
+    readonly related: readonly string[];
+};
+/**
+ * A group's "Used in".
+ *
+ * @param graph - the facts the worker read.
+ * @param files - each story file's title and `related`.
+ */
+export declare const joinedUsage: (graph: UsageGraph, files: readonly UsageFile[]) => UsageIndex;
+//# sourceMappingURL=usageModule.d.ts.map

package/dist/src/vite/usageModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageModule.d.ts","sourceRoot":"","sources":["../../../src/vite/usageModule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,KAAK,UAAU,EAAqC,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEhE,6GAA6G;AAC7G,MAAM,MAAM,SAAS,GAAG;IACtB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iBAAiB;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAyHF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,UAAU,EAAE,OAAO,SAAS,SAAS,EAAE,KAAG,UAuB5E,CAAC"}

package/dist/src/vite/usageModule.js

@@ -0,0 +1,135 @@
+/**
+ * "Used in" joined from the facts the docs worker reads (`usageGraph.ts`): for each component of a `?forgebook-files`
+ * group, the other components whose stories render it or render a component whose modules import it.
+ *
+ * @remarks
+ * A story uses a component directly when its JSX renders it, and through another when a component it renders reaches
+ * the component's file through the package's own imports, followed all the way (Tree renders Row, Row renders
+ * DropLine: Tree's stories use DropLine). The file of a component the story renders counts only when an import reaches
+ * it, so a file's other exports are not used just for sitting beside one. The component's own stories, the components
+ * its meta names in `related`, and another page of the same component (two story files with one meta component) are
+ * left out. Pure: facts in, index out.
+ *
+ * @module
+ */
+import { usersInOrder } from "../usedIn.js";
+/**
+ * A component's key, unique across files.
+ *
+ * @param ref - the component.
+ */
+const keyOf = (ref) => `${ref.file}#${ref.name}`;
+/**
+ * The files a module reaches through its imports, itself left out unless an import comes back to it.
+ *
+ * @param imports - the import graph.
+ * @param start - the module.
+ */
+const reachedFrom = (imports, start) => {
+    const reached = new Set();
+    const queue = [...(imports[start] ?? [])];
+    while (queue.length > 0) {
+        const file = queue.pop() ?? "";
+        if (reached.has(file))
+            continue;
+        reached.add(file);
+        queue.push(...(imports[file] ?? []));
+    }
+    return reached;
+};
+/**
+ * Values pushed into a map's list, the list made when it is missing.
+ *
+ * @param map - the map.
+ * @param key - the key.
+ * @param value - the value.
+ */
+const pushed = (map, key, value) => {
+    map.set(key, [...(map.get(key) ?? []), value]);
+};
+/**
+ * The pages of the group's components.
+ *
+ * @param graph - the facts.
+ * @param fileOf - each story file's title and `related`, by its path.
+ */
+const pagesOf = (graph, fileOf) => {
+    const byComponent = new Map();
+    const byFile = new Map();
+    const componentOf = new Map();
+    for (const facts of graph.files) {
+        const page = fileOf.get(facts.storyFile);
+        if (page === undefined || facts.component === undefined)
+            continue;
+        pushed(byComponent, keyOf(facts.component), page);
+        pushed(byFile, facts.component.file, page);
+        componentOf.set(page.title, keyOf(facts.component));
+    }
+    return { byComponent, byFile, componentOf };
+};
+/**
+ * Notes that a story uses a component, unless it is the component's own, the component's meta names it in `related`,
+ * or it is another page of the same component.
+ *
+ * @param found - what the join found so far.
+ * @param pages - the group's pages.
+ * @param target - the used component's page.
+ * @param user - the using component's page.
+ * @param story - the story's export.
+ * @param isDirect - whether the story renders the component itself.
+ */
+const note = (found, pages, target, user, story, isDirect) => {
+    if (target.title === user.title || target.related.includes(user.title))
+        return;
+    const component = pages.componentOf.get(target.title);
+    if (component !== undefined && component === pages.componentOf.get(user.title))
+        return;
+    const users = found.get(target.title) ?? new Map();
+    found.set(target.title, users);
+    const entry = users.get(user.title) ?? { isDirect: false, stories: [] };
+    users.set(user.title, entry);
+    entry.isDirect ||= isDirect;
+    if (!entry.stories.includes(story))
+        entry.stories.push(story);
+};
+/**
+ * The pages a story uses: those of the components it renders (directly), those of the files they reach (through).
+ *
+ * @param renders - what the story renders.
+ * @param pages - the group's pages.
+ * @param reach - the files a module reaches.
+ */
+const usedBy = (renders, pages, reach) => [
+    ...renders.flatMap((ref) => (pages.byComponent.get(keyOf(ref)) ?? []).map((target) => ({ target, isDirect: true }))),
+    ...[...new Set(renders.flatMap((ref) => [...reach(ref.file)]))].flatMap((file) => (pages.byFile.get(file) ?? []).map((target) => ({ target, isDirect: false })))
+];
+/**
+ * A group's "Used in".
+ *
+ * @param graph - the facts the worker read.
+ * @param files - each story file's title and `related`.
+ */
+export const joinedUsage = (graph, files) => {
+    const fileOf = new Map(files.map((file) => [file.storyFile, file]));
+    const pages = pagesOf(graph, fileOf);
+    const reachMemo = new Map();
+    const reach = (file) => {
+        const known = reachMemo.get(file) ?? reachedFrom(graph.imports, file);
+        reachMemo.set(file, known);
+        return known;
+    };
+    const found = new Map();
+    for (const facts of graph.files) {
+        const user = fileOf.get(facts.storyFile);
+        if (user === undefined)
+            continue;
+        for (const story of facts.stories)
+            for (const { target, isDirect } of usedBy(story.renders, pages, reach))
+                note(found, pages, target, user, story.exportName, isDirect);
+    }
+    return Object.fromEntries([...found].map(([title, users]) => [
+        title,
+        usersInOrder([...users].map(([user, entry]) => ({ title: user, ...entry })))
+    ]));
+};
+//# sourceMappingURL=usageModule.js.map

package/dist/src/vite/usageModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageModule.js","sourceRoot":"","sources":["../../../src/vite/usageModule.ts"],"names":[],"mappings":"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"}

package/dist/src/worstCase.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The worst-case values a story can give a component: a long text with spaces, a word too long to break, scripts and
+ * emoji that change a line's height and width, a huge number. One set, for the stories `forgebook new` writes and for
+ * the catalogue's worst-case data, so both test the same edges.
+ *
+ * @module
+ */
+/** A text long enough to wrap several times in any box. */
+export declare const WORST_TEXT = "A label long enough to wrap onto several lines in any box it is given, with words of every length in it";
+/** A word with no place to break, for a box that must cut or scroll it. */
+export declare const WORST_WORD = "Supercalifragilisticexpialidocious_with_no_place_to_break_it_at_all_1234567890";
+/** Scripts and emoji that change a line's height and width. */
+export declare const WORST_SCRIPTS = "\u00DCn\u00EFc\u00F6d\u00E9 \u540D\u524D \u0645\u0631\u062D\u0628\u0627 \uD83D\uDC69\uD83C\uDFFD\u200D\uD83D\uDCBB";
+/** A number with more digits than a box usually holds. */
+export declare const WORST_NUMBER = 123456789012;
+//# sourceMappingURL=worstCase.d.ts.map

package/dist/src/worstCase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worstCase.d.ts","sourceRoot":"","sources":["../../src/worstCase.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,UAAU,4GACoF,CAAC;AAE5G,2EAA2E;AAC3E,eAAO,MAAM,UAAU,mFAAmF,CAAC;AAE3G,+DAA+D;AAC/D,eAAO,MAAM,aAAa,uHAA6B,CAAC;AAExD,0DAA0D;AAC1D,eAAO,MAAM,YAAY,eAAkB,CAAC"}

package/dist/src/worstCase.js

@@ -0,0 +1,16 @@
+/**
+ * The worst-case values a story can give a component: a long text with spaces, a word too long to break, scripts and
+ * emoji that change a line's height and width, a huge number. One set, for the stories `forgebook new` writes and for
+ * the catalogue's worst-case data, so both test the same edges.
+ *
+ * @module
+ */
+/** A text long enough to wrap several times in any box. */
+export const WORST_TEXT = "A label long enough to wrap onto several lines in any box it is given, with words of every length in it";
+/** A word with no place to break, for a box that must cut or scroll it. */
+export const WORST_WORD = "Supercalifragilisticexpialidocious_with_no_place_to_break_it_at_all_1234567890";
+/** Scripts and emoji that change a line's height and width. */
+export const WORST_SCRIPTS = "Ünïcödé 名前 مرحبا 👩🏽‍💻";
+/** A number with more digits than a box usually holds. */
+export const WORST_NUMBER = 123_456_789_012;
+//# sourceMappingURL=worstCase.js.map

package/dist/src/worstCase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worstCase.js","sourceRoot":"","sources":["../../src/worstCase.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,UAAU,GACrB,yGAAyG,CAAC;AAE5G,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,gFAAgF,CAAC;AAE3G,+DAA+D;AAC/D,MAAM,CAAC,MAAM,aAAa,GAAG,0BAA0B,CAAC;AAExD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgebook",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "See every component in every theme, contrast, language and width: CSF stories, one frame per story, and a props table from the components' types.",
   "keywords": [
     "react",
@@ -97,6 +97,10 @@
       "types": "./dist/bin/forgebook-docs/catalogueMarkdown.d.ts",
       "default": "./dist/bin/forgebook-docs/catalogueMarkdown.js"
     },
+    "./catalogue-options": {
+      "types": "./dist/bin/forgebook-docs/catalogueOptions.d.ts",
+      "default": "./dist/bin/forgebook-docs/catalogueOptions.js"
+    },
     "./a11y": {
       "types": "./dist/src/a11y.d.ts",
       "default": "./dist/src/a11y.js"
@@ -152,6 +156,14 @@
     "./catalogue": {
       "types": "./dist/src/catalogue.d.ts",
       "default": "./dist/src/catalogue.js"
+    },
+    "./story-check": {
+      "types": "./dist/src/storyCheck.d.ts",
+      "default": "./dist/src/storyCheck.js"
+    },
+    "./spills": {
+      "types": "./dist/src/spills.d.ts",
+      "default": "./dist/src/spills.js"
     }
   },
   "dependencies": {
@@ -161,7 +173,7 @@
     "lightningcss": "1.33.0",
     "marked": "18.1.0",
     "typescript-6": "npm:typescript@6.0.3",
-    "@forgebook/story-format": "0.1.2"
+    "@forgebook/story-format": "0.1.3"
   },
   "peerDependencies": {
     "@testing-library/dom": "^10.4.0",

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

@@ -1,24 +0,0 @@
-/**
- * The colour scheme and contrast switches at the toolbar's start, off while the compare view sets them or the story
- * fixes them.
- *
- * @module
- */
-import type { ReactNode } from "react";
-import type { FixedView } from "../storyGlobals.ts";
-import type { ViewState } from "../viewState.ts";
-/**
- * The colour scheme switch and the contrast switch, at the toolbar's start: the scheme as segments with icons, a
- * two-value contrast as a toggle (a longer one as segments).
- *
- * @param props - the view, its setter, and whether a story's page is shown (the compare view sets them there).
- */
-export declare const SchemeSwitches: ({ view, onViewChange, isStoryPage, fixed }: {
-    /** The view shown. */
-    readonly view: ViewState;
-    /** Called with the changed view. */
-    readonly onViewChange: (view: ViewState) => void;
-    readonly isStoryPage: boolean;
-    readonly fixed: FixedView;
-}) => ReactNode;
-//# sourceMappingURL=SchemeSwitches.d.ts.map

package/dist/src/shell/SchemeSwitches.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SchemeSwitches.d.ts","sourceRoot":"","sources":["../../../src/shell/SchemeSwitches.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAcjD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,4CAK5B;IACD,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B,KAAG,SAiDH,CAAC"}

package/dist/src/shell/SchemeSwitches.js

@@ -1,36 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { switchWithRole } from "../switches.js";
-import { useCatalogue } from "./catalogueContext.js";
-import { Icon } from "./icons.js";
-import { Segmented } from "./Segmented.js";
-import { STRINGS } from "./strings.js";
-import { switchValueIn, withSwitch } from "./switchView.js";
-/** The icon of each scheme a colour scheme switch's values draw in. */
-const SCHEME_ICONS = {
-    light: "sun",
-    dark: "moon",
-    system: "monitor"
-};
-/**
- * The colour scheme switch and the contrast switch, at the toolbar's start: the scheme as segments with icons, a
- * two-value contrast as a toggle (a longer one as segments).
- *
- * @param props - the view, its setter, and whether a story's page is shown (the compare view sets them there).
- */
-export const SchemeSwitches = ({ view, onViewChange, isStoryPage, fixed }) => {
-    const switches = useCatalogue().switches;
-    const scheme = switchWithRole(switches, "colorScheme");
-    const contrast = switchWithRole(switches, "contrast");
-    const isFixed = (each) => fixed.switches[each.id] !== undefined;
-    const isCompared = (each) => (isStoryPage && view.compare.includes(each.id)) || isFixed(each);
-    const more = contrast?.values.find((value) => value.isMore === true);
-    const standard = contrast?.values.find((value) => value.isMore !== true);
-    if (scheme === undefined && contrast === undefined)
-        return null;
-    return (_jsxs("div", { className: "forgebook-toolbar__group", children: [scheme === undefined ? null : (_jsx(Segmented, { label: scheme.label, isDisabled: isCompared(scheme), disabledNote: isFixed(scheme) ? STRINGS.setByStory : undefined, options: scheme.values.map((value) => ({
-                    value: value.value,
-                    label: value.label,
-                    icon: SCHEME_ICONS[value.scheme ?? "light"]
-                })), value: switchValueIn(view, scheme), onValueChange: (value) => onViewChange(withSwitch(view, scheme, value)) })), contrast === undefined || more === undefined || standard === undefined ? null : (_jsxs("button", { type: "button", className: "forgebook-button", title: isFixed(contrast) ? STRINGS.setByStory : contrast.label, "aria-pressed": switchValueIn(view, contrast) === more.value, disabled: isCompared(contrast), onClick: () => onViewChange(withSwitch(view, contrast, switchValueIn(view, contrast) === more.value ? standard.value : more.value)), children: [_jsx(Icon, { name: "contrast", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: contrast.label })] }))] }));
-};
-//# sourceMappingURL=SchemeSwitches.js.map

package/dist/src/shell/SchemeSwitches.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"SchemeSwitches.js","sourceRoot":"","sources":["../../../src/shell/SchemeSwitches.tsx"],"names":[],"mappings":"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"}