forgebook 0.1.7 → 0.2.0

package/dist/src/shell/useSearchIndex.js

@@ -0,0 +1,51 @@
+import { useEffect, useState } from "react";
+import { isSearchIndex, mergedSearchIndex } from "../searchIndex.js";
+import { sourceSearchLoaders } from "../sourceFiles.js";
+/** Nothing loaded. */
+const NOTHING = { indexes: new Map(), isLoading: true, hasFailed: false };
+/** A group's index, or nothing and the news when it cannot be read. */
+const readGroup = async (load) => {
+    try {
+        const index = await load();
+        return isSearchIndex(index) ? index : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The catalogue's search index.
+ *
+ * @param sources - the sources, with their loaders.
+ * @param isWanted - whether a search asked: nothing loads before.
+ */
+export const useSearchIndex = (sources, isWanted) => {
+    const [loaded, setLoaded] = useState(NOTHING);
+    useEffect(() => {
+        if (!isWanted)
+            return;
+        const loads = sources.flatMap((source) => sourceSearchLoaders(source).map((load) => ({ id: source.id, load })));
+        const bySource = new Map();
+        let isCurrent = true;
+        let waiting = loads.length;
+        let hasFailed = false;
+        const arrive = (id, index) => {
+            waiting -= 1;
+            hasFailed ||= index === undefined;
+            if (index !== undefined)
+                bySource.set(id, [...(bySource.get(id) ?? []), index]);
+            if (!isCurrent)
+                return;
+            const indexes = new Map([...bySource].map(([source, each]) => [source, mergedSearchIndex(each)]));
+            setLoaded({ indexes, isLoading: waiting > 0, hasFailed });
+        };
+        setLoaded({ ...NOTHING, isLoading: loads.length > 0 });
+        for (const { id, load } of loads) {
+            void readGroup(load).then((index) => arrive(id, index));
+        }
+        return () => {
+            isCurrent = false;
+        };
+    }, [sources, isWanted]);
+    return loaded;
+};

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

@@ -0,0 +1,35 @@
+import type { DeviceDefault } from "../deviceView.ts";
+import type { TreeStory } from "../storyTree.ts";
+import type { TouchChoice } from "../switches.ts";
+import type { ViewState } from "../viewState.ts";
+import { type TouchOverrides } from "./storyTouch.ts";
+/** The shown story's view and how to change it. */
+export type ShownView = {
+    /** The view the story is drawn with. */
+    readonly view: ViewState;
+    /** Changes it: the story's own parts to the story, the rest to the address. */
+    readonly onViewChange: (view: ViewState) => void;
+};
+/** What the shown story's view is made of. */
+export type ShownViewInput = {
+    /** The address's view. */
+    readonly addressView: ViewState;
+    /** The shown story; none on another page. */
+    readonly story: TreeStory | undefined;
+    /** The user's choice for each story marked for a phone. */
+    readonly touchOverrides: TouchOverrides;
+    /** Sets the user's choice for a story marked for a phone. */
+    readonly onTouchChange: (storyId: string, isTouch: boolean) => void;
+    /** The catalogue's touch switch. */
+    readonly touch: TouchChoice | undefined;
+    /** The catalogue's default device: a story shown in a device is touched as a phone is. */
+    readonly catalogueDevice: DeviceDefault;
+    /** Changes the address's view. */
+    readonly onAddressViewChange: (view: ViewState) => void;
+};
+/**
+ * The shown story's view.
+ *
+ * @param input - the address's view, the story, the touch choices and the address's setter.
+ */
+export declare const useShownView: (input: ShownViewInput) => ShownView;

package/dist/src/shell/useShownView.js

@@ -0,0 +1,36 @@
+/**
+ * The view the shown story is drawn with, and its change back to the address: a story marked for a phone has its own
+ * Touch, and a story about logic is never compared.
+ *
+ * @remarks
+ * The toolbar and the stage read and change this view; the address keeps what belongs to the other stories (the
+ * Touch switch they follow, the compare they share). The view is kept while nothing it is made of changes: a new
+ * switches' object would send the frame the view again.
+ *
+ * @module
+ */
+import { useMemo } from "react";
+import { logicView, logicViewChange } from "./logicView.js";
+import { phoneStories, storyTouchesOf, storyViewChange, touchedView } from "./storyTouch.js";
+/**
+ * The shown story's view.
+ *
+ * @param input - the address's view, the story, the touch choices and the address's setter.
+ */
+export const useShownView = (input) => {
+    const { addressView, story, touchOverrides, touch, catalogueDevice } = input;
+    const isLogic = story?.isLogic === true;
+    const isPhone = story !== undefined && phoneStories(addressView, catalogueDevice)(story);
+    const view = useMemo(() => logicView(touchedView(addressView, story?.id, storyTouchesOf(story === undefined ? [] : [story], touchOverrides, () => isPhone), touch), isLogic), [addressView, story, touchOverrides, touch, isLogic, isPhone]);
+    const onViewChange = (next) => {
+        if (story === undefined) {
+            input.onAddressViewChange(next);
+            return;
+        }
+        const change = storyViewChange(next, addressView, story, touch, isPhone);
+        if (change.isTouch !== undefined)
+            input.onTouchChange(story.id, change.isTouch);
+        input.onAddressViewChange(logicViewChange(change.view, addressView, isLogic));
+    };
+    return { view, onViewChange };
+};

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

@@ -11,4 +11,3 @@ export type SidebarLayout = {
 };
 /** The sidebar's layout. */
 export declare const useSidebarLayout: () => SidebarLayout;
-//# sourceMappingURL=useSidebarLayout.d.ts.map

package/dist/src/shell/useSidebarLayout.js

@@ -16,4 +16,3 @@ export const useSidebarLayout = () => {
     const [isOpen, setIsOpen] = useStored("sidebar", (stored) => stored !== "hidden", (shown) => (shown ? "shown" : "hidden"));
     return { width, setWidth, isOpen, setIsOpen };
 };
-//# sourceMappingURL=useSidebarLayout.js.map

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

@@ -9,6 +9,19 @@
  * @module
  */
 import { type Dispatch, type SetStateAction } from "react";
+/**
+ * The stored text under a key, or none when there is none or storage is refused.
+ *
+ * @param key - the key.
+ */
+export declare const readStored: (key: string) => string | null;
+/**
+ * Keeps a text under a key, when storage allows it.
+ *
+ * @param key - the key.
+ * @param value - the text.
+ */
+export declare const writeStored: (key: string, value: string) => void;
 /**
  * A value kept in this browser.
  *
@@ -19,4 +32,3 @@ import { type Dispatch, type SetStateAction } from "react";
  * @returns the value and its setter, which also takes a function of the current value.
  */
 export declare const useStored: <TValue>(name: string, read: (stored: string | null) => TValue, write: (value: TValue) => string) => [TValue, Dispatch<SetStateAction<TValue>>];
-//# sourceMappingURL=useStored.d.ts.map

package/dist/src/shell/useStored.js

@@ -10,8 +10,12 @@
  */
 import { useEffect, useState } from "react";
 import { useCatalogue } from "./catalogueContext.js";
-/** The stored text under a key, or none when there is none or storage is refused. */
-const readStored = (key) => {
+/**
+ * The stored text under a key, or none when there is none or storage is refused.
+ *
+ * @param key - the key.
+ */
+export const readStored = (key) => {
     try {
         return window.localStorage.getItem(key);
     }
@@ -19,8 +23,13 @@ const readStored = (key) => {
         return null;
     }
 };
-/** Keeps a text under a key, when storage allows it. */
-const writeStored = (key, value) => {
+/**
+ * Keeps a text under a key, when storage allows it.
+ *
+ * @param key - the key.
+ * @param value - the text.
+ */
+export const writeStored = (key, value) => {
     try {
         window.localStorage.setItem(key, value);
     }
@@ -65,4 +74,3 @@ export const useStored = (name, read, write) => {
     useEffect(() => writeStored(key, text), [key, text]);
     return [value, setValue];
 };
-//# sourceMappingURL=useStored.js.map

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

@@ -0,0 +1,20 @@
+/**
+ * The accessibility check of the story on the stage: its state, and how to run it in the frame.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+import type { CheckState } from "./A11yTab.tsx";
+import type { CheckResult } from "./useFrameMessages.ts";
+/**
+ * The accessibility check of the shown story: its state, cleared when the story or the view changes, and how to run
+ * it in the frame.
+ *
+ * @param frameRef - the story's frame.
+ * @param checkKey - the story and the view, as one text: a check belongs to them.
+ */
+export declare const useStoryCheck: (frameRef: RefObject<HTMLIFrameElement | null>, checkKey: string) => {
+    check: CheckState;
+    run: () => void;
+    receive: (result: CheckResult) => void;
+};

package/dist/src/shell/useStoryCheck.js

@@ -0,0 +1,33 @@
+/**
+ * The accessibility check of the story on the stage: its state, and how to run it in the frame.
+ *
+ * @module
+ */
+import { useState } from "react";
+import { framesOrigin } from "./framesOrigin.js";
+/**
+ * The accessibility check of the shown story: its state, cleared when the story or the view changes, and how to run
+ * it in the frame.
+ *
+ * @param frameRef - the story's frame.
+ * @param checkKey - the story and the view, as one text: a check belongs to them.
+ */
+export const useStoryCheck = (frameRef, checkKey) => {
+    const [check, setCheck] = useState({ status: "idle" });
+    const [checkedKey, setCheckedKey] = useState(checkKey);
+    if (checkedKey !== checkKey) {
+        setCheckedKey(checkKey);
+        setCheck({ status: "idle" });
+    }
+    return {
+        check,
+        run: () => {
+            setCheck({ status: "running" });
+            const message = { type: "forgebook:check" };
+            frameRef.current?.contentWindow?.postMessage(message, framesOrigin());
+        },
+        receive: (result) => setCheck("error" in result
+            ? { status: "error", message: result.error }
+            : { status: "done", violations: result.violations })
+    };
+};

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

@@ -11,4 +11,3 @@ import { type Loaded } from "./useLoaded.ts";
  * @param load - the source's loader for the file; `undefined` when it has none.
  */
 export declare const useStoryCode: (load: (() => Promise<unknown>) | undefined) => Loaded<StoryFileCode>;
-//# sourceMappingURL=useStoryCode.d.ts.map

package/dist/src/shell/useStoryCode.js

@@ -26,4 +26,3 @@ const codeState = (value) => {
  * @param load - the source's loader for the file; `undefined` when it has none.
  */
 export const useStoryCode = (load) => useLoaded(load, codeState);
-//# sourceMappingURL=useStoryCode.js.map

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

@@ -6,4 +6,3 @@ import { type StoryHeights } from "../storyHeights.ts";
  * @returns the heights, or none while they load or when there are none.
  */
 export declare const useStoryHeights: (url: string | undefined) => StoryHeights | undefined;
-//# sourceMappingURL=useStoryHeights.d.ts.map

package/dist/src/shell/useStoryHeights.js

@@ -28,4 +28,3 @@ export const useStoryHeights = (url) => {
     const heights = useLoaded(load, heightsState);
     return heights.status === "ready" ? heights.value : undefined;
 };
-//# sourceMappingURL=useStoryHeights.js.map

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

@@ -4,4 +4,3 @@
  * @param storyIds - every story's id, in the sidebar's order.
  */
 export declare const useStoryIdsElement: (storyIds: readonly string[]) => void;
-//# sourceMappingURL=useStoryIdsElement.d.ts.map

package/dist/src/shell/useStoryIdsElement.js

@@ -26,4 +26,3 @@ export const useStoryIdsElement = (storyIds) => {
         element.textContent = JSON.stringify(storyIds);
     }, [storyIds]);
 };
-//# sourceMappingURL=useStoryIdsElement.js.map

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

@@ -8,4 +8,3 @@ import { type StoryTree } from "../storyTree.ts";
  * @param openStory - opens a story by its id.
  */
 export declare const useStoryKeys: (tree: StoryTree, shownStoryId: string | undefined, firstOfPage: string | undefined, openStory: (id: string) => void) => void;
-//# sourceMappingURL=useStoryKeys.d.ts.map

package/dist/src/shell/useStoryKeys.js

@@ -37,4 +37,3 @@ export const useStoryKeys = (tree, shownStoryId, firstOfPage, openStory) => {
         return () => document.removeEventListener("keydown", walk);
     }, [storyIds, shownStoryId, firstOfPage]);
 };
-//# sourceMappingURL=useStoryKeys.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * The tab a set shows, and how to pick another.
+ *
+ * @param labels - the set's labels, in order.
+ * @param sync - the name the set shares its choice under; none keeps its own.
+ * @returns the place of the tab shown, and a function that shows the tab at a place.
+ */
+export declare const useSyncedTab: (labels: readonly string[], sync: string | undefined) => readonly [number, (place: number) => void];

package/dist/src/shell/useSyncedTab.js

@@ -0,0 +1,60 @@
+/**
+ * The tab a set of docs tabs shows, shared by every set with the same `syncKey`: picking "pnpm" in one picks it in
+ * each, on this page and the next, and the browser keeps it for the next visit.
+ *
+ * @remarks
+ * A set without a name keeps its own choice. A named set whose labels lack the shared choice shows its first tab and
+ * leaves the choice alone, so a page that offers only npm never forgets that the reader picked pnpm elsewhere.
+ *
+ * @module
+ */
+import { useCallback, useMemo, useState, useSyncExternalStore } from "react";
+import { useCatalogue } from "./catalogueContext.js";
+import { readStored, writeStored } from "./useStored.js";
+/** The sets that follow each stored name. */
+const listeners = new Map();
+/** The choices picked while the page is open: what a browser that refuses storage still keeps until it closes. */
+const picked = new Map();
+/** The choice under a name: picked on this page, else kept from a visit before. */
+const choiceOf = (key) => picked.get(key) ?? readStored(key);
+/** Subscribes to a stored name's changes. */
+const subscribeTo = (key) => (listener) => {
+    const set = listeners.get(key) ?? new Set();
+    set.add(listener);
+    listeners.set(key, set);
+    return () => {
+        set.delete(listener);
+    };
+};
+/** A subscription that never fires: a set without a name follows nothing. */
+const subscribeToNothing = () => () => undefined;
+/**
+ * The tab a set shows, and how to pick another.
+ *
+ * @param labels - the set's labels, in order.
+ * @param sync - the name the set shares its choice under; none keeps its own.
+ * @returns the place of the tab shown, and a function that shows the tab at a place.
+ */
+export const useSyncedTab = (labels, sync) => {
+    const { id } = useCatalogue();
+    const key = sync === undefined ? undefined : `${id}:tabs:${sync}`;
+    const [own, setOwn] = useState(0);
+    const subscribe = useMemo(() => (key === undefined ? subscribeToNothing : subscribeTo(key)), [key]);
+    const shared = useSyncExternalStore(subscribe, () => (key === undefined ? null : choiceOf(key)), () => null);
+    const sharedPlace = shared === null ? -1 : labels.indexOf(shared);
+    const shown = key === undefined ? own : Math.max(0, sharedPlace);
+    const pick = useCallback((place) => {
+        if (key === undefined) {
+            setOwn(place);
+            return;
+        }
+        const label = labels[place];
+        if (label === undefined)
+            return;
+        picked.set(key, label);
+        writeStored(key, label);
+        for (const listener of listeners.get(key) ?? [])
+            listener();
+    }, [key, labels]);
+    return [Math.min(shown, Math.max(0, labels.length - 1)), pick];
+};

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

@@ -1,3 +1,2 @@
 /** Whether the system prefers dark; light where there is no window (a test rendering on the server). */
 export declare const useSystemDark: () => boolean;
-//# sourceMappingURL=useSystemDark.d.ts.map

package/dist/src/shell/useSystemDark.js

@@ -16,4 +16,3 @@ const subscribe = (onChange) => {
 const isDarkNow = () => window.matchMedia(DARK).matches;
 /** Whether the system prefers dark; light where there is no window (a test rendering on the server). */
 export const useSystemDark = () => useSyncExternalStore(subscribe, isDarkNow, () => false);
-//# sourceMappingURL=useSystemDark.js.map

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

@@ -36,4 +36,3 @@ export type ToolbarLayout = {
 };
 /** The person's arrangement of the toolbar. */
 export declare const useToolbarLayout: () => ToolbarLayout;
-//# sourceMappingURL=useToolbarLayout.d.ts.map

package/dist/src/shell/useToolbarLayout.js

@@ -55,4 +55,3 @@ export const useToolbarLayout = () => {
         }
     };
 };
-//# sourceMappingURL=useToolbarLayout.js.map

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

@@ -28,4 +28,3 @@ export declare const overflowing: (pinned: readonly string[], widths: ReadonlyMa
  * @returns the ids of those moved into the View menu.
  */
 export declare const useToolbarOverflow: (box: RefObject<HTMLElement | null>, pinned: readonly string[]) => string[];
-//# sourceMappingURL=useToolbarOverflow.d.ts.map

package/dist/src/shell/useToolbarOverflow.js

@@ -59,4 +59,3 @@ export const useToolbarOverflow = (box, pinned) => {
     }, [key]);
     return moved.filter((id) => pinned.includes(id));
 };
-//# sourceMappingURL=useToolbarOverflow.js.map

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

@@ -43,4 +43,3 @@ export type WorstCase = {
  * @param input - the frames, the story, its settable props and its values.
  */
 export declare const useWorstCase: ({ storyRef, storyId, settable, values, panelArgs, onPanelArgsChange }: WorstCaseInput) => WorstCase;
-//# sourceMappingURL=useWorstCase.d.ts.map

package/dist/src/shell/useWorstCase.js

@@ -11,6 +11,7 @@
  */
 import { useEffect, useMemo, useState } from "react";
 import { tellFrames } from "./FrameView.js";
+import { framesOrigin } from "./framesOrigin.js";
 import { isWorstCase, worstArgs } from "./worstArgs.js";
 /**
  * The most spills a story's frames counted: the one to fix first; none before any frame counted.
@@ -41,9 +42,8 @@ export const useWorstCase = ({ storyRef, storyId, settable, values, panelArgs, o
         },
         sendTo: (frame) => {
             const message = { type: "forgebook:spills", isOn };
-            frame.postMessage(message, window.location.origin);
+            frame.postMessage(message, framesOrigin());
         },
         receive: (reported, count, frame) => setCounts((current) => new Map(current).set(reported, new Map(current.get(reported)).set(frame, count)))
     };
 };
-//# sourceMappingURL=useWorstCase.js.map

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

@@ -39,4 +39,3 @@ export type WorstCaseState = {
     /** Sets the worst case over the panel's values. */
     readonly onApply: () => void;
 };
-//# sourceMappingURL=worstArgs.d.ts.map

package/dist/src/shell/worstArgs.js

@@ -44,4 +44,3 @@ export const isWorstCase = (worst, values) => {
     const entries = Object.entries(worst);
     return entries.length > 0 && entries.every(([name, value]) => values[name] === value);
 };
-//# sourceMappingURL=worstArgs.js.map

package/dist/src/shellTheme.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A catalogue's theme of the shell, as the custom properties the shell's style sheets read, with what is wrong with it.
+ *
+ * @remarks
+ * Nothing here runs in the browser: the plugin writes the theme into the shell's page at build, so a catalogue with no
+ * theme gets no bytes and one with a theme no script. The frames belong to the stories and get none of it, but for the
+ * one thing of Forgebook's they draw: the box that says a story failed. The shell's sheet sits in a cascade layer, so the page's unlayered rules outrank it whatever loads first; for that reason
+ * each palette is scoped to its own appearance, or a light colour would reach the dark one. The default palettes are
+ * also the style sheets' (`styles/_tokens.scss`, not shipped): the contrast of a partial theme needs what it leaves
+ * unset, and a test holds the two equal. Layout is not themable: it is what the shell's own tests hold.
+ *
+ * @module
+ */
+import type { ShellTheme } from "./shellTheme.types.ts";
+/** A palette, by role. */
+type Palette = Readonly<Record<string, string>>;
+/** The shell's light palette, every role. */
+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"];
+/** The grounds text is read on. */
+export declare const GROUND_ROLES: readonly ["window", "sidebar", "surface"];
+/** The code roles, read on the code background. */
+export declare const CODE_ROLES: readonly ["code-keyword", "code-type", "code-string", "code-number", "code-punctuation", "code-name"];
+/**
+ * A theme as CSS, for the shell's page.
+ *
+ * @param theme - the theme.
+ * @returns the rules; empty when the theme sets nothing.
+ */
+export declare const shellThemeCss: (theme: ShellTheme) => string;
+/**
+ * What a frame needs of a theme: the box that says a story failed, and nothing a story could read. A frame draws in the
+ * light palette whatever the shell's appearance.
+ *
+ * @param theme - the theme.
+ * @returns the rule; empty when the theme sets nothing the box uses.
+ */
+export declare const frameThemeCss: (theme: ShellTheme) => string;
+/**
+ * Themes over each other, role by role, the last winning: a catalogue over its presets.
+ *
+ * @param themes - the themes, in order.
+ */
+export declare const mergedThemes: (themes: readonly ShellTheme[]) => ShellTheme;
+/**
+ * What in a theme cannot be written into a page.
+ *
+ * @param theme - the theme.
+ * @returns the first value that is not a plain CSS value, named; none when all are.
+ */
+export declare const themeValueProblem: (theme: ShellTheme) => string | undefined;
+/**
+ * What in a theme will not work: a role that does not exist, a text under 4.5:1 on a ground, code under 4.5:1 on its
+ * background, or an accent under 3:1, since it draws the keyboard's focus. Colours that are not hex are left out: a wrong
+ * warning teaches people to ignore the right ones.
+ *
+ * @param theme - the theme.
+ * @returns one line per problem.
+ */
+export declare const shellThemeProblems: (theme: ShellTheme) => string[];
+export {};