forgebook 0.3.3 → 0.4.0

package/dist/src/shell/controlCycle.js

@@ -4,12 +4,13 @@
  *
  * @remarks
  * Pure. A control its toolbar control leaves disabled is left as it is here too: a switch or a background the story
- * fixes (or a width), and a control the compare view draws side by side.
+ * fixes (or a width), a switch another switch's value implies, and a control the compare view draws side by side.
  *
  * @module
  */
 import { AUDIENCE_IDS } from "../audiences.js";
 import { cycledValue, switchValues } from "../controlKeys.js";
+import { impliedSwitches } from "../switches.js";
 import { isComparing, PLAIN_BACKDROP, SHEETS_CHOICES } from "../viewState.js";
 import { withSwitch } from "./switchView.js";
 /**
@@ -52,7 +53,7 @@ export const cycledView = (view, id, step, catalogue, fixed, isStoryPage) => {
         return undefined;
     const each = catalogue.switches.find((candidate) => candidate.id === id);
     if (each !== undefined) {
-        if (fixed.switches[id] !== undefined)
+        if (fixed.switches[id] !== undefined || impliedSwitches(view.switches, catalogue.switches).has(id))
             return undefined;
         const current = view.switches[id] ?? each.default;
         return withSwitch(view, each, cycledValue(switchValues(each), current, step));

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

@@ -0,0 +1,55 @@
+/**
+ * The custom controls of a catalogue, as the shell loads them: a module's check on arrival, and the check of a value before
+ * it reaches the story. Loaded with the first story that names such a control, so a catalogue with none never asks for it.
+ *
+ * @remarks
+ * A module is the catalogue's own code, run with a plugin's trust, and it can be wrong in every way: named by no one, gone,
+ * throwing as it loads, exporting something else. Each ends in a sentence beside the field; none reaches the panel as an
+ * exception.
+ *
+ * @module
+ */
+import type { ArgControlModule } from "../argControl.ts";
+import type { ArgValue } from "../messages.ts";
+/** The texts of the custom controls' host. */
+export declare const CONTROL_STRINGS: {
+    controlUnknown: (name: string) => string;
+    controlFailed: (name: string, reason: string) => string;
+    controlMalformed: (name: string) => string;
+    controlThrew: (name: string, reason: string) => string;
+    controlValue: (name: string, reason: string) => string;
+    controlUnsafe: string;
+};
+/** A catalogue's custom controls: how to load each, by name. */
+export type ArgControlLoaders = Readonly<Record<string, () => Promise<unknown>>>;
+/** A control as loading it ended. */
+export type LoadedControl = {
+    readonly status: "ready";
+    readonly module: ArgControlModule;
+} | {
+    readonly status: "failed";
+    readonly message: string;
+};
+/**
+ * A control, loaded.
+ *
+ * @param name - its name.
+ * @param loaders - the catalogue's custom controls.
+ */
+export declare const loadControl: (name: string, loaders: ArgControlLoaders) => Promise<LoadedControl>;
+/**
+ * What is wrong with a value for a control: its schema's word, or that it holds what would run if a component spread it on
+ * an element, which no schema's author is asked to think of.
+ *
+ * @param module - the control's module.
+ * @param value - the value.
+ * @returns the sentence; none when it fits.
+ */
+export declare const controlValueProblem: (module: ArgControlModule, value: ArgValue) => string | undefined;
+/**
+ * The checks of a story's custom controls, by name; a control that cannot load has none, which refuses its values.
+ *
+ * @param names - the controls the story names.
+ * @param loaders - the catalogue's custom controls.
+ */
+export declare const customChecksOf: (names: readonly string[], loaders: ArgControlLoaders) => Promise<Readonly<Record<string, (value: ArgValue) => string | undefined>>>;

package/dist/src/shell/customControls.js

@@ -0,0 +1,70 @@
+import { holdsUnsafePart } from "../shapeValues.js";
+import { isValueSchema, schemaProblem } from "../valueSchema.js";
+import { lateStrings } from "./strings.js";
+/** The texts of the custom controls' host. */
+export const CONTROL_STRINGS = lateStrings({
+    controlUnknown: (name) => `No control is registered as "${name}": add it to argControls in forgebook.config`,
+    controlFailed: (name, reason) => `The control "${name}" could not be loaded: ${reason}`,
+    controlMalformed: (name) => `The control "${name}" must export mount, a function, and schema, of JSON Schema's keywords Forgebook reads`,
+    controlThrew: (name, reason) => `The control "${name}" failed: ${reason}`,
+    controlValue: (name, reason) => `The control "${name}" was given a value it refuses: ${reason}`,
+    controlUnsafe: "It holds what a link may not give"
+});
+/** Whether a value is a plain object with a function `mount`. */
+const isControlModule = (value) => typeof value === "object" &&
+    value !== null &&
+    "mount" in value &&
+    typeof value.mount === "function" &&
+    "schema" in value &&
+    isValueSchema(value.schema);
+/** Each control's load, kept: every field and check of a page share one. */
+const loads = new Map();
+/** Loads one control's module, once, and reads what it exports. */
+const readControl = async (name, load) => {
+    try {
+        const module = await load();
+        return isControlModule(module)
+            ? { status: "ready", module }
+            : { status: "failed", message: CONTROL_STRINGS.controlMalformed(name) };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { status: "failed", message: CONTROL_STRINGS.controlFailed(name, reason) };
+    }
+};
+/**
+ * A control, loaded.
+ *
+ * @param name - its name.
+ * @param loaders - the catalogue's custom controls.
+ */
+export const loadControl = (name, loaders) => {
+    const load = Object.hasOwn(loaders, name) ? loaders[name] : undefined;
+    if (load === undefined)
+        return Promise.resolve({ status: "failed", message: CONTROL_STRINGS.controlUnknown(name) });
+    const started = loads.get(load) ?? readControl(name, load);
+    loads.set(load, started);
+    return started;
+};
+/**
+ * What is wrong with a value for a control: its schema's word, or that it holds what would run if a component spread it on
+ * an element, which no schema's author is asked to think of.
+ *
+ * @param module - the control's module.
+ * @param value - the value.
+ * @returns the sentence; none when it fits.
+ */
+export const controlValueProblem = (module, value) => schemaProblem(module.schema, value) ??
+    (holdsUnsafePart(value, true) ? CONTROL_STRINGS.controlUnsafe : undefined);
+/**
+ * The checks of a story's custom controls, by name; a control that cannot load has none, which refuses its values.
+ *
+ * @param names - the controls the story names.
+ * @param loaders - the catalogue's custom controls.
+ */
+export const customChecksOf = async (names, loaders) => {
+    const controls = await Promise.all(names.map(async (name) => [name, await loadControl(name, loaders)]));
+    return Object.fromEntries(controls.flatMap(([name, control]) => control.status === "ready"
+        ? [[name, (value) => controlValueProblem(control.module, value)]]
+        : []));
+};

package/dist/src/shell/docPage.css

@@ -92,9 +92,9 @@
     opacity: 1;
   }
   .forgebook-anchor:focus-visible {
-    outline: 2px solid color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    outline: 2px solid var(--forgebook-focus-halo);
     outline-offset: 0;
-    box-shadow: inset 0 0 0 1px var(--forgebook-accent);
+    box-shadow: var(--forgebook-focus-edge);
   }
   .forgebook-docs__code {
     position: relative;
@@ -118,7 +118,7 @@
     margin: 0;
     padding: 0.5rem 1rem;
     box-shadow: inset 0 -1px 0 var(--forgebook-separator);
-    font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono-small);
     color: var(--forgebook-text-secondary);
     padding-inline-end: 5rem;
     overflow: hidden;
@@ -194,7 +194,7 @@
   }
   .forgebook-aside__title {
     margin: 0;
-    font: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-row-label);
     font-weight: 600;
     color: var(--forgebook-tone);
   }
@@ -217,7 +217,7 @@
     border-radius: var(--forgebook-radius-control-small) var(--forgebook-radius-control-small) 0 0;
     background: none;
     box-shadow: inset 0 -2px 0 transparent;
-    font: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-row-label);
     color: var(--forgebook-text-secondary);
     cursor: pointer;
     transition: color 150ms ease-out, box-shadow 150ms ease-out;
@@ -230,9 +230,9 @@
     box-shadow: inset 0 -2px 0 var(--forgebook-accent);
   }
   .forgebook-tabs__tab:focus-visible {
-    outline: 2px solid color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    outline: 2px solid var(--forgebook-focus-halo);
     outline-offset: -2px;
-    box-shadow: inset 0 0 0 1px var(--forgebook-accent);
+    box-shadow: var(--forgebook-focus-edge);
   }
   .forgebook-tabs__panel {
     display: grid;
@@ -273,7 +273,7 @@
     border-radius: 50%;
     background: var(--forgebook-surface);
     box-shadow: inset 0 0 0 1px var(--forgebook-edge);
-    font: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-row-label);
     font-weight: 600;
     color: var(--forgebook-text-secondary);
   }
@@ -311,7 +311,7 @@
     align-items: center;
     gap: 0.25rem;
     margin: 0;
-    font: 600 0.875rem/1.3 var(--forgebook-font-sans);
+    font: var(--forgebook-text-card-title);
   }
   .forgebook-card--link {
     text-decoration: none;
@@ -324,12 +324,12 @@
     box-shadow: 0 0 0 1px var(--forgebook-card-edge-hover), 0 4px 14px var(--forgebook-shadow-lift);
   }
   .forgebook-card--link:focus-visible {
-    outline: 2px solid color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    outline: 2px solid var(--forgebook-focus-halo);
     outline-offset: 0;
-    box-shadow: inset 0 0 0 1px var(--forgebook-accent), 0 0 0 1px var(--forgebook-card-edge), 0 1px 3px var(--forgebook-shadow-soft);
+    box-shadow: var(--forgebook-focus-edge), 0 0 0 1px var(--forgebook-card-edge), 0 1px 3px var(--forgebook-shadow-soft);
   }
   .forgebook-card__description {
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-docs__foot {
@@ -357,24 +357,24 @@
     box-shadow: 0 0 0 1px var(--forgebook-card-edge-hover), 0 4px 14px var(--forgebook-shadow-lift);
   }
   .forgebook-docs__around:focus-visible {
-    outline: 2px solid color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    outline: 2px solid var(--forgebook-focus-halo);
     outline-offset: 0;
-    box-shadow: inset 0 0 0 1px var(--forgebook-accent), 0 0 0 1px var(--forgebook-card-edge), 0 1px 3px var(--forgebook-shadow-soft);
+    box-shadow: var(--forgebook-focus-edge), 0 0 0 1px var(--forgebook-card-edge), 0 1px 3px var(--forgebook-shadow-soft);
   }
   .forgebook-docs__around-label {
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-tertiary);
   }
   .forgebook-docs__around-name {
     display: inline-flex;
     align-items: center;
     gap: 0.25rem;
-    font: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-row-label);
     color: var(--forgebook-accent-text);
   }
   .forgebook-contents__title {
     margin: 0;
-    font: 600 0.6875rem/1.3 var(--forgebook-font-sans);
+    font: var(--forgebook-text-label);
     color: var(--forgebook-text-tertiary);
   }
   .forgebook-contents__list {
@@ -392,7 +392,7 @@
     padding: 0.25rem 0.5rem;
     border-radius: var(--forgebook-radius-control-small);
     box-shadow: inset 2px 0 0 transparent;
-    font: 400 0.78125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-row-compact);
     color: var(--forgebook-text-secondary);
     text-decoration: none;
     transition: color 150ms ease-out, background-color 150ms ease-out;
@@ -406,9 +406,9 @@
     font-weight: 500;
   }
   .forgebook-contents__link:focus-visible {
-    outline: 2px solid color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    outline: 2px solid var(--forgebook-focus-halo);
     outline-offset: -2px;
-    box-shadow: inset 0 0 0 1px var(--forgebook-accent);
+    box-shadow: var(--forgebook-focus-edge);
   }
   .forgebook-contents--column {
     position: sticky;
@@ -433,9 +433,9 @@
     border-radius: var(--forgebook-radius-control-small);
   }
   .forgebook-contents--fold > summary:focus-visible {
-    outline: 2px solid color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    outline: 2px solid var(--forgebook-focus-halo);
     outline-offset: 0;
-    box-shadow: inset 0 0 0 1px var(--forgebook-accent);
+    box-shadow: var(--forgebook-focus-edge);
   }
   .forgebook-contents--fold > nav {
     margin-top: 0.5rem;

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

@@ -13,11 +13,13 @@
 import type { StoryControlsSetting, StoryFileCode } from "@forgebook/story-format/source";
 import { type PanelArgTypes } from "../argTypes.ts";
 import { type ComponentDocs } from "../componentDocs.ts";
-import type { ArgValue, PanelArgs } from "../messages.ts";
+import type { ArgValue, PanelArgs, PlayStepCommand } from "../messages.ts";
 import type { NamedValues } from "../namedValues.ts";
 import type { PlayTrace } from "../playTrace.ts";
 import type { TreeStory } from "../storyTree.ts";
+import type { ViewState } from "../viewState.ts";
 import type { CheckState } from "./A11yTab.tsx";
+import type { ArgControlLoaders } from "./customControls.ts";
 import type { DockTab } from "./Dock.tsx";
 import type { TextArgNote } from "./PropRows.tsx";
 import type { EventCall } from "./useFrameMessages.ts";
@@ -44,6 +46,16 @@ export type DockTabsInput = {
     readonly actions: readonly string[];
     /** The values of the moment: the story's args with the panel's over them. */
     readonly values: PanelArgs;
+    /** The panel's own values, for what can go back to the story's. */
+    readonly panelArgs: PanelArgs;
+    /** The story's own args, for a control no type describes. */
+    readonly storyArgs: PanelArgs;
+    /** Loads the catalogue's design tokens; none when it has none. */
+    readonly loadTokens: (() => Promise<unknown>) | undefined;
+    /** Loads each custom control the catalogue registers, by name; none when it registers none. */
+    readonly argControls?: ArgControlLoaders | undefined;
+    /** The switches' values of the moment, for the args whose `argTypes.if` reads a global. */
+    readonly globals: Readonly<Record<string, unknown>>;
     /** Called with a changed value; `undefined` removes the panel's value. */
     readonly onValueChange: (name: string, value: ArgValue | undefined) => void;
     /** Removes every value the panel set. */
@@ -62,8 +74,12 @@ export type DockTabsInput = {
     readonly onClearCalls: () => void;
     /** The play function's trace; none for a story without a play (or before it ran). */
     readonly trace: PlayTrace | undefined;
-    /** Runs the play again. */
-    readonly onPlayAgain: () => void;
+    /** Runs the play again, or steps through it. */
+    readonly onPlayStep: (command: PlayStepCommand) => void;
+    /** The view, whose play switch the Interactions tab shows. */
+    readonly view: ViewState;
+    /** Changes the view. */
+    readonly onViewChange: (view: ViewState) => void;
     /** The accessibility check. */
     readonly check: CheckState;
     /** Runs it; none when it cannot run. */

package/dist/src/shell/dockTabs.js

@@ -1,12 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { isArgShown } from "../argConditions.js";
 import { panelProps } from "../argTypes.js";
 import { codeNameOf } from "../componentDocs.js";
 import { lazyModule } from "./lazyModule.js";
 import { LazyTab } from "./lazyTab.js";
 import { PropsTab } from "./PropsTab.js";
-import { SignatureReference } from "./SignatureReference.js";
 import { STRINGS } from "./strings.js";
 import { a11yHint, interactionsHint, styleHooks } from "./tabSummaries.js";
+/** The Signature tab's reference, loaded when a story about logic first shows it. */
+const SIGNATURE_TAB = lazyModule(() => import("./SignatureReference.js").then((module) => module.SignatureReference));
 /** The Events tab, its module, loaded when the tab is first chosen. */
 const EVENTS_TAB = lazyModule(() => import("./EventsTab.js").then((module) => module.EventsTab));
 /** The Interactions tab, its module, loaded when the tab is first chosen. */
@@ -25,15 +27,20 @@ const notice = (text, isProblem) => (_jsx("p", { className: isProblem ? "forgebo
  * @param input - what the tabs are built from.
  * @param props - the props, from the types with the `argTypes` laid over them.
  */
-const propsTab = (input, props) => props.some((prop) => prop.kind !== "event")
-    ? [
-        {
-            id: "props",
-            label: STRINGS.tabs.props,
-            content: (_jsx(PropsTab, { props: props, values: input.values, controls: input.controls, onValueChange: input.onValueChange, onReset: input.onReset, worstCase: input.worstCase, namedValues: input.namedValues, textArgs: input.textArgs, componentGroups: input.propGroups, requiredFirst: input.story.requiredFirst }))
-        }
-    ]
-    : [];
+const propsTab = (input, all) => {
+    // the condition is the moment's, so it is tested here and not where the props are declared: a value set while an arg
+    // is hidden, from the address or the story, is still the story's
+    const props = all.filter((prop) => isArgShown(input.argTypes[prop.name]?.if, input.values, input.globals));
+    return props.some((prop) => prop.kind !== "event")
+        ? [
+            {
+                id: "props",
+                label: STRINGS.tabs.props,
+                content: (_jsx(PropsTab, { props: props, values: input.values, panelArgs: input.panelArgs, loadTokens: input.loadTokens, argControls: input.argControls, controls: input.controls, onValueChange: input.onValueChange, onReset: input.onReset, worstCase: input.worstCase, namedValues: input.namedValues, textArgs: input.textArgs, componentGroups: input.propGroups, requiredFirst: input.story.requiredFirst }))
+            }
+        ]
+        : [];
+};
 /**
  * The events the Events tab lists: the component's, then the story's actions its types do not name.
  *
@@ -72,9 +79,9 @@ const docsTabs = (input) => {
     // a story without a component (a render of its own) still has the args its `argTypes` name
     if (docs.status === "none") {
         return [
-            ...propsTab(input, panelProps([], input.argTypes)),
+            ...propsTab(input, panelProps([], input.argTypes, input.storyArgs)),
             ...eventsTab(input, eventsOf([], input.actions)),
-            ...(input.trace === undefined ? [] : [interactionsTab(input.trace, input.onPlayAgain)])
+            ...(input.trace === undefined ? [] : [interactionsTab(input.trace, input)])
         ];
     }
     // the docs' place while they load or fail: the tab the story opens on once they are read
@@ -83,7 +90,7 @@ const docsTabs = (input) => {
         : { id: "props", label: STRINGS.tabs.props };
     // the play's trace comes from the frame, not from the docs: a first read of a project's docs can take seconds, and a
     // play that finished meanwhile is shown without waiting for them, or when they fail
-    const played = input.trace === undefined ? [] : [interactionsTab(input.trace, input.onPlayAgain)];
+    const played = input.trace === undefined ? [] : [interactionsTab(input.trace, input)];
     if (docs.status === "loading")
         return [{ ...docsTab, content: notice(STRINGS.docsLoading, false) }, ...played];
     if (docs.status === "error") {
@@ -94,10 +101,10 @@ const docsTabs = (input) => {
     if (input.story.isLogic)
         return logicTabs(input, component);
     const tabs = [];
-    tabs.push(...propsTab(input, panelProps(component.props, input.argTypes)));
+    tabs.push(...propsTab(input, panelProps(component.props, input.argTypes, input.storyArgs)));
     tabs.push(...eventsTab(input, events));
     if (input.trace !== undefined)
-        tabs.push(interactionsTab(input.trace, input.onPlayAgain));
+        tabs.push(interactionsTab(input.trace, input));
     if (component.parts.length > 0 || styleHooks(component).length > 0) {
         tabs.push({
             id: "parts",
@@ -122,19 +129,19 @@ const logicTabs = (input, component) => {
         tabs.push({
             id: "signature",
             label: STRINGS.tabs.signature,
-            content: (_jsx("div", { className: "forgebook-signature-tab", children: _jsx(SignatureReference, { name: component.name, signature: component.signature }) }))
+            content: (_jsx("div", { className: "forgebook-signature-tab", children: _jsx(LazyTab, { module: SIGNATURE_TAB, tabProps: { name: component.name, signature: component.signature } }) }))
         });
     }
     if (input.trace !== undefined)
-        tabs.push(interactionsTab(input.trace, input.onPlayAgain));
+        tabs.push(interactionsTab(input.trace, input));
     return tabs;
 };
 /** The Interactions tab of a story whose play ran. */
-const interactionsTab = (trace, onPlayAgain) => ({
+const interactionsTab = (trace, { onPlayStep, view, onViewChange }) => ({
     id: "play",
     label: STRINGS.tabs.play,
     hint: interactionsHint(trace),
-    content: _jsx(LazyTab, { module: INTERACTIONS_TAB, tabProps: { trace, onPlayAgain } })
+    content: _jsx(LazyTab, { module: INTERACTIONS_TAB, tabProps: { trace, onPlayStep, view, onViewChange } })
 });
 /** The Code tab, when the story file has code: loading, loaded, or failed to load. */
 const codeTabs = (input) => {
@@ -160,7 +167,8 @@ const codeTabs = (input) => {
                     code: code.value,
                     exportName: input.story.exportName,
                     componentName: docs.status === "ready" ? codeNameOf(docs.value) : input.componentName,
-                    args: input.values
+                    args: input.values,
+                    edited: Object.keys(input.panelArgs)
                 } }))
         }
     ];

package/dist/src/shell/embed.css

@@ -10,7 +10,7 @@
   .forgebook-embed__message {
     margin: 0;
     padding: 1rem;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-embed__message[data-failed] {
@@ -30,7 +30,7 @@
   }
   .forgebook-embed-panel__hint {
     margin: 0;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-embed-panel__hint[data-warning] {
@@ -44,7 +44,7 @@
   }
   .forgebook-embed-field__label {
     grid-column: 1/-1;
-    font: 500 0.75rem/1.3 var(--forgebook-font-sans);
+    font: var(--forgebook-text-control);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-embed-field__value {
@@ -54,21 +54,21 @@
     padding: 0.375rem 0.5rem;
     border: 0;
     border-radius: var(--forgebook-radius-control);
-    font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono-small);
     color: var(--forgebook-text);
     background: var(--forgebook-fill-quiet);
     box-shadow: inset 0 0 0 1px var(--forgebook-edge-field);
   }
   .forgebook-embed-field__value:focus-visible {
-    outline: 2px solid color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    outline: 2px solid var(--forgebook-focus-halo);
     outline-offset: 0;
-    box-shadow: inset 0 0 0 1px var(--forgebook-accent);
+    box-shadow: var(--forgebook-focus-edge);
   }
   .forgebook-embed-panel__follow {
     display: flex;
     gap: 0.5rem;
     align-items: center;
-    font: 500 0.75rem/1.3 var(--forgebook-font-sans);
+    font: var(--forgebook-text-control);
     color: var(--forgebook-text);
   }
 }

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

@@ -12,6 +12,13 @@ export declare const framesOrigin: () => string;
  * @param event - the message's event.
  */
 export declare const isFromFrames: (event: MessageEvent) => boolean;
+/**
+ * What a story's frame may do, as a sandbox: everything a page does but navigate the catalogue's tab, which a story's
+ * link could otherwise send to any address. The frames keep their own origin (`allow-same-origin`): it is not the
+ * catalogue's, so the pair gives the story nothing of the catalogue's. Frames on the catalogue's own origin get none:
+ * there the pair would let a story lift its own sandbox, and browsers warn of it.
+ */
+export declare const FRAME_SANDBOX: string;
 /** What a story's frame element is given, wherever the shell draws one. */
 export type StoryFrameAttributes = {
     /** The browser features it may use. */

package/dist/src/shell/framesOrigin.js

@@ -51,7 +51,7 @@ const FRAME_PERMISSIONS = [
  * catalogue's, so the pair gives the story nothing of the catalogue's. Frames on the catalogue's own origin get none:
  * there the pair would let a story lift its own sandbox, and browsers warn of it.
  */
-const FRAME_SANDBOX = [
+export const FRAME_SANDBOX = [
     "allow-scripts",
     "allow-same-origin",
     "allow-forms",

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

@@ -0,0 +1,20 @@
+/**
+ * Where a gallery's menu sits: under its button, or over it when only there it fits, always inside the window. Pure.
+ *
+ * @module
+ */
+/**
+ * The menu's place, in CSS px from the window's corner.
+ *
+ * @param button - the button's box.
+ * @param panel - the menu's size.
+ * @param room - the window's size.
+ * @returns where its top and left corner go.
+ */
+export declare const galleryPlace: (button: Pick<DOMRect, "top" | "bottom" | "left">, panel: Pick<DOMRect, "width" | "height">, room: {
+    readonly width: number;
+    readonly height: number;
+}) => {
+    readonly top: number;
+    readonly left: number;
+};

package/dist/src/shell/galleryPlace.js

@@ -0,0 +1,26 @@
+/**
+ * Where a gallery's menu sits: under its button, or over it when only there it fits, always inside the window. Pure.
+ *
+ * @module
+ */
+/** The room kept between the menu and its button or the window's edge, in CSS px. */
+const GAP = 6;
+/**
+ * The menu's place, in CSS px from the window's corner.
+ *
+ * @param button - the button's box.
+ * @param panel - the menu's size.
+ * @param room - the window's size.
+ * @returns where its top and left corner go.
+ */
+export const galleryPlace = (button, panel, room) => {
+    const below = button.bottom + GAP;
+    const above = button.top - GAP - panel.height;
+    const isBelowFit = below + panel.height <= room.height - GAP;
+    const top = isBelowFit || above < GAP ? below : above;
+    return {
+        // a menu taller than the room on both sides starts as high as it can and scrolls
+        top: Math.max(GAP, Math.min(top, room.height - GAP - panel.height)),
+        left: Math.max(GAP, Math.min(button.left, room.width - GAP - panel.width))
+    };
+};

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

@@ -31,6 +31,7 @@ declare const PATHS: {
     readonly turn: "M2.5 9.5h7a1 1 0 0 0 1-1v-4a1 1 0 0 0-1-1h-7a1 1 0 0 0-1 1v4a1 1 0 0 0 1 1ZM12 12.5a2.5 2.5 0 0 0 2.5-2.5V8.5M13.5 10l1-1.5 1 1.5";
     readonly device: "M5.5 1.5h5a1 1 0 0 1 1 1v11a1 1 0 0 1-1 1h-5a1 1 0 0 1-1-1v-11a1 1 0 0 1 1-1ZM7.25 3.5h1.5";
     readonly plus: "M8 3.5v9M3.5 8h9";
+    readonly noValue: "M8 2a6 6 0 1 0 0 12A6 6 0 0 0 8 2ZM3.8 3.8l8.4 8.4";
     readonly minus: "M3.5 8h9";
     readonly hash: "M6 2.5 5 13.5M11 2.5l-1 11M3 6h10.5M2.5 10H13";
     readonly check: "m3.5 8.5 3 3 6-7";

package/dist/src/shell/icons.js

@@ -26,6 +26,7 @@ const PATHS = {
     turn: "M2.5 9.5h7a1 1 0 0 0 1-1v-4a1 1 0 0 0-1-1h-7a1 1 0 0 0-1 1v4a1 1 0 0 0 1 1ZM12 12.5a2.5 2.5 0 0 0 2.5-2.5V8.5M13.5 10l1-1.5 1 1.5",
     device: "M5.5 1.5h5a1 1 0 0 1 1 1v11a1 1 0 0 1-1 1h-5a1 1 0 0 1-1-1v-11a1 1 0 0 1 1-1ZM7.25 3.5h1.5",
     plus: "M8 3.5v9M3.5 8h9",
+    noValue: "M8 2a6 6 0 1 0 0 12A6 6 0 0 0 8 2ZM3.8 3.8l8.4 8.4",
     minus: "M3.5 8h9",
     hash: "M6 2.5 5 13.5M11 2.5l-1 11M3 6h10.5M2.5 10H13",
     check: "m3.5 8.5 3 3 6-7",

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

@@ -1,20 +1,22 @@
+/** Where this browser keeps the reader's choice: a person's habit, the same in every catalogue of an origin. */
+export declare const SINGLE_KEYS_STORED = "forgebook-single-keys";
 /**
- * The shell's keys: `/` goes to the search, `[` and `]` open the previous and the next story in the sidebar's order.
- * A key typed into a field, or with a modifier, is the field's or the browser's.
+ * Whether a key event happens while the user types: in a field that takes text, a select or editable content, or in a
+ * custom element (a catalogue's control, a plugin's panel), whose keys are its own whatever it draws. A toolbar's segment
+ * (a radio) or a toggle keeps the page's keys, so they work right after a press on one.
  *
- * @remarks
- * The keys work while the shell has the focus; a frame keeps its own keys, so a story's keyboard behaviour is never
- * taken over. Pure, apart from reading the event's target.
- *
- * @module
+ * @param target - the event's target.
  */
+export declare const isTyping: (target: EventTarget | null) => boolean;
+/** What a key without a modifier reads of its event. */
+export type SingleKeyEvent = Pick<KeyboardEvent, "target"> & Partial<Pick<KeyboardEvent, "composedPath">>;
 /**
- * Whether a key event happens while the user types: in a field that takes text, a select or editable content. A
- * toolbar's segment (a radio) or a toggle keeps the page's keys, so they work right after a press on one.
+ * Whether a key without a modifier is the shell's: the reader left them on and nothing is typed into. The whole path of
+ * the event is read: from inside a shadow root it names only the host, and a custom element keeps what is pressed in it.
  *
- * @param target - the event's target.
+ * @param event - the key's event.
  */
-export declare const isTyping: (target: EventTarget | null) => boolean;
+export declare const isSingleKeyFree: (event: SingleKeyEvent) => boolean;
 /** The move a key asks for in the list of stories. */
 export type StoryStep = -1 | 1;
 /**
@@ -22,7 +24,7 @@ export type StoryStep = -1 | 1;
  *
  * @param event - the key, its modifiers and its target.
  */
-export declare const storyStep: (event: Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "altKey" | "target">) => StoryStep | undefined;
+export declare const storyStep: (event: Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "altKey"> & SingleKeyEvent) => StoryStep | undefined;
 /**
  * The id a step leads to: the neighbour of the current story, or the first (or last) story from a page that is not
  * a story's; none past either end.