forgebook 0.3.3 → 0.4.1

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,9 @@ 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),
+                    panel: input
                 } }))
         }
     ];

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/frameOrder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Which waiting frames of a page start first: the ones the reader is looking at, then their neighbours outward.
+ *
+ * @remarks
+ * A page lists its stories top to bottom, but the reader may be anywhere on it: after a scroll to the end, the stories
+ * in view must not wait behind the ones above them that are still near. Read by `useFrameQueue`.
+ *
+ * @module
+ */
+/** A box's vertical extent, in the same coordinates as the visible part of the page. */
+export type VerticalBox = {
+    /** Its top edge, in CSS px. */
+    readonly top: number;
+    /** Its bottom edge, in CSS px. */
+    readonly bottom: number;
+};
+/**
+ * How far a box is from the visible part of the page: 0 when any of it is in view, otherwise the gap to the nearest
+ * edge.
+ *
+ * @param box - the box of a story's frame.
+ * @param view - the visible part of the page.
+ * @returns The distance, in CSS px.
+ */
+export declare const distanceFromView: (box: VerticalBox, view: VerticalBox) => number;
+/**
+ * The frames to start now: the nearest to the visible part first, in the page's order among equals, at most `free`.
+ *
+ * @param waiting - the stories waiting for their frame, in the page's order.
+ * @param distances - each story's distance from the visible part, in CSS px; a story with none comes after every
+ * other.
+ * @param free - how many frames may start.
+ * @returns The stories to start, nearest first.
+ */
+export declare const nearestFrames: (waiting: readonly string[], distances: ReadonlyMap<string, number>, free: number) => string[];

package/dist/src/shell/frameOrder.js

@@ -0,0 +1,45 @@
+/**
+ * Which waiting frames of a page start first: the ones the reader is looking at, then their neighbours outward.
+ *
+ * @remarks
+ * A page lists its stories top to bottom, but the reader may be anywhere on it: after a scroll to the end, the stories
+ * in view must not wait behind the ones above them that are still near. Read by `useFrameQueue`.
+ *
+ * @module
+ */
+/**
+ * How far a box is from the visible part of the page: 0 when any of it is in view, otherwise the gap to the nearest
+ * edge.
+ *
+ * @param box - the box of a story's frame.
+ * @param view - the visible part of the page.
+ * @returns The distance, in CSS px.
+ */
+export const distanceFromView = (box, view) => {
+    if (box.bottom <= view.top)
+        return view.top - box.bottom;
+    if (box.top >= view.bottom)
+        return box.top - view.bottom;
+    return 0;
+};
+/**
+ * The frames to start now: the nearest to the visible part first, in the page's order among equals, at most `free`.
+ *
+ * @param waiting - the stories waiting for their frame, in the page's order.
+ * @param distances - each story's distance from the visible part, in CSS px; a story with none comes after every
+ * other.
+ * @param free - how many frames may start.
+ * @returns The stories to start, nearest first.
+ */
+export const nearestFrames = (waiting, distances, free) => {
+    const distanceOf = (storyId) => distances.get(storyId) ?? Number.POSITIVE_INFINITY;
+    // a stable sort keeps the page's order among stories at the same distance, the demo first among those in view
+    // (compared rather than subtracted: two stories with no distance would give NaN)
+    const byDistance = (first, second) => {
+        const [one, other] = [distanceOf(first), distanceOf(second)];
+        if (one === other)
+            return 0;
+        return one < other ? -1 : 1;
+    };
+    return [...waiting].sort(byDistance).slice(0, Math.max(0, free));
+};

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.

package/dist/src/shell/keyboard.js

@@ -1,34 +1,49 @@
 /**
- * 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.
+ * The shell's keys: `/` goes to the search, `[` and `]` open the previous and the next story in the sidebar's order,
+ * `?` lists them. A key typed into a field or a custom element, or with a modifier, is theirs or the browser's; a reader
+ * can turn every key without a modifier off.
  *
  * @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.
+ * taken over. Pure, apart from reading the event's target and the reader's choice.
  *
  * @module
  */
+import { readStored } from "./useStored.js";
+/** Where this browser keeps the reader's choice: a person's habit, the same in every catalogue of an origin. */
+export const SINGLE_KEYS_STORED = "forgebook-single-keys";
+/** Whether the reader left the keys without a modifier on, as they are unless turned off. */
+const areSingleKeysOn = () => readStored(SINGLE_KEYS_STORED) !== "off";
 /** The inputs that take no text: a key pressed on one is the page's, not the field's. */
 const NOT_TEXT_INPUTS = ["checkbox", "radio", "button", "submit", "reset", "range", "color", "file"];
 /**
- * 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 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.
  *
  * @param target - the event's target.
  */
 export const isTyping = (target) => typeof HTMLElement !== "undefined" &&
     target instanceof HTMLElement &&
     (target.isContentEditable ||
+        target.localName.includes("-") ||
         (target instanceof HTMLInputElement && !NOT_TEXT_INPUTS.includes(target.type)) ||
         target instanceof HTMLTextAreaElement ||
         target instanceof HTMLSelectElement);
+/**
+ * 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 event - the key's event.
+ */
+export const isSingleKeyFree = (event) => areSingleKeysOn() && !(event.composedPath?.() ?? [event.target]).some(isTyping);
 /**
  * The step a key asks for: `[` the previous story, `]` the next; none for any other key or one with a modifier.
  *
  * @param event - the key, its modifiers and its target.
  */
 export const storyStep = (event) => {
-    if (event.metaKey || event.ctrlKey || event.altKey || isTyping(event.target))
+    if (event.metaKey || event.ctrlKey || event.altKey || !isSingleKeyFree(event))
         return undefined;
     if (event.key === "[")
         return -1;

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

@@ -1,6 +1,17 @@
 /** The later parts' texts, as shown: Forgebook's, with the catalogue's replacements. */
 export declare const LATER_STRINGS: {
+    docsNav: string;
+    aboutControl: (control: string) => string;
+    signatureParameter: string;
+    signatureReturns: string;
+    signatureNone: string;
+    apiType: string;
+    apiWhat: string;
     audienceError: string;
+    controlMenu: (label: string) => string;
+    unpinControl: string;
+    hideInView: string;
+    showInView: string;
     controlKey: (control: string, key: string | undefined) => string;
     changeKey: string;
     pressAKey: string;
@@ -36,6 +47,14 @@ export declare const LATER_STRINGS: {
     playTitle: string;
     playTime: (ms: number) => string;
     playAgain: string;
+    playRun: string;
+    playOnOpen: string;
+    playOff: string;
+    playStepThrough: string;
+    playNext: string;
+    playContinue: string;
+    playPaused: (action: string) => string;
+    playActionsNote: string;
     playNoSteps: string;
     codeFromArgs: string;
     codeRender: string;
@@ -59,6 +78,13 @@ export declare const LATER_STRINGS: {
     apiMember: string;
     memberCount: (count: number) => string;
     membersOf: (type: string) => string;
+    propOnlyWhen: (prop: string, values: readonly string[], orOmitted: boolean) => string;
+    propGeneric: (parameter: string, type: string, shownAs: "constraint" | "default" | "unknown") => string;
+    propUnresolved: (name: string) => string;
+    propAny: string;
+    propsUntyped: string;
+    propsNoSignature: string;
+    propsOutsidePackage: (count: number) => string;
     showCode: string;
     hideCode: string;
     openStory: string;
@@ -74,11 +100,15 @@ export declare const LATER_STRINGS: {
     backToPlace: string;
     backToPlaceNamed: (name: string) => string;
     examples: string;
+    pageContained: string;
     pageError: string;
     droppedArgs: string;
     droppedArgReasons: {
         undeclared: string;
         type: string;
+        unreadable: string;
+        markup: string;
+        control: string;
     };
     removeDroppedArgs: string;
     events: string;

package/dist/src/shell/laterStrings.js

@@ -1,6 +1,6 @@
 /**
  * The texts of the shell's parts that load after the first screen, but for the home and the docs pages
- * (`pageStrings.ts`): a component's page, the panel's tabs but Props, the View menu's panel, the embed panel and page,
+ * (`pageStrings.ts`): a component's page, the panel's tabs but Props, the View menu's panel, a pinned control's menu, the embed panel and page,
  * the comparison, the story clock's bar, the plugins' hosts and the note on args a link dropped. They load with the
  * first of those parts, so a first load carries none of them.
  *
@@ -14,7 +14,18 @@
 import { lateStrings } from "./strings.js";
 /** The later parts' texts, as shown: Forgebook's, with the catalogue's replacements. */
 export const LATER_STRINGS = lateStrings({
+    docsNav: "Docs",
+    aboutControl: (control) => `About ${control}`,
+    signatureParameter: "Parameter",
+    signatureReturns: "Returns",
+    signatureNone: "It takes no parameters.",
+    apiType: "Type",
+    apiWhat: "What it does",
     audienceError: "This part of the page could not be loaded",
+    controlMenu: (label) => `${label} on the toolbar`,
+    unpinControl: "Remove from the toolbar",
+    hideInView: "Hide in View",
+    showInView: "Show in View",
     controlKey: (control, key) => key === undefined ? `${control}: no key` : `${control}: key ${key.toUpperCase()}`,
     changeKey: "Change the key: press it, then the new key; Backspace takes it away",
     pressAKey: "Press a key",
@@ -50,6 +61,14 @@ export const LATER_STRINGS = lateStrings({
     playTitle: "Play function",
     playTime: (ms) => `${ms} ms`,
     playAgain: "Run again",
+    playRun: "Run",
+    playOnOpen: "Play stories when they open",
+    playOff: "This story has a play function. It has not run: run it, or have stories play when they open.",
+    playStepThrough: "Step through",
+    playNext: "Next",
+    playContinue: "Continue",
+    playPaused: (action) => `Next: ${action}`,
+    playActionsNote: "The log and the stepping follow the canvas and userEvent of the play's context; what a play imports itself runs unrecorded.",
     playNoSteps: "The play names no steps: wrap its parts in step(label, run) to see them here.",
     codeFromArgs: "from the args",
     codeRender: "the story's render",
@@ -73,6 +92,20 @@ export const LATER_STRINGS = lateStrings({
     apiMember: "Member",
     memberCount: (count) => `${count} ${count === 1 ? "member" : "members"}`,
     membersOf: (type) => `Members of ${type}`,
+    // the names and types below come written as code spans (`codeSpans.ts`), since a type may hold backticks
+    propOnlyWhen: (prop, values, orOmitted) => {
+        if (values.length === 0)
+            return `Only when ${prop} is left out.`;
+        return `Only when ${prop} is ${values.join(" or ")}${orOmitted ? ", or left out" : ""}.`;
+    },
+    propGeneric: (parameter, type, shownAs) => shownAs === "unknown"
+        ? `${parameter} is generic, with no constraint: shown as \`unknown\`.`
+        : `${parameter} is generic: shown as its ${shownAs}, ${type}.`,
+    propUnresolved: (name) => `${name} cannot be found, so this type is read as \`any\`.`,
+    propAny: "Typed `any`: nothing is known of its values.",
+    propsUntyped: "Its props are typed `any`, so none can be listed.",
+    propsNoSignature: "Its type cannot be called with props, so none can be listed.",
+    propsOutsidePackage: (count) => `${count === 1 ? "Its one prop comes" : `All ${count} of its props come`} from outside its package (an element's attributes), which the reference leaves out.`,
     showCode: "Show code",
     hideCode: "Hide code",
     openStory: "Open the story",
@@ -86,11 +119,18 @@ export const LATER_STRINGS = lateStrings({
     fillPage: "Fill the page",
     fillPageNamed: (name) => `Fill the page with ${name}`,
     backToPlace: "Back to its place",
-    backToPlaceNamed: (name) => `Put ${name} back in its place`,
+    backToPlaceNamed: (name) => `Back to its place: ${name}`,
     examples: "Examples",
+    pageContained: "Contained width",
     pageError: "The component's page could not be read",
     droppedArgs: "The link sets values this story does not take; they were left out:",
-    droppedArgReasons: { undeclared: "not one of its props", type: "not of the prop's type" },
+    droppedArgReasons: {
+        undeclared: "not one of its props",
+        type: "not of the prop's type",
+        unreadable: "its value could not be read",
+        markup: "this framework writes it into HTML, so a link may give only plain text",
+        control: "its control refuses it, or could not be loaded"
+    },
     removeDroppedArgs: "Remove them from the address",
     events: "Events",
     calls: "Calls",

package/dist/src/shell/mountShell.js

@@ -10,6 +10,7 @@ import { createRoot } from "react-dom/client";
 import { isEmbedAddress } from "../embed.js";
 import { framePageAddress, pageOrigins, SAME_ORIGIN } from "../frameOrigins.js";
 import { CodeWriterContext } from "./codeWriter.js";
+import { HAS_REFS, setShellRefs } from "./composition.js";
 import { FORGEBOOK_MARK_URL } from "./forgebookMark.js";
 import { setFramesOrigin } from "./framesOrigin.js";
 import { Shell } from "./Shell.js";
@@ -57,6 +58,8 @@ export const mountShell = (container, config) => {
     // set before anything renders, the embed included: its story's frame runs on the frames' origin too
     const origins = pageOrigins(frames, window.location, "catalogue");
     setFramesOrigin(origins.frames);
+    if (HAS_REFS)
+        setShellRefs(config.refs);
     const shell = {
         ...page,
         frameUrl: framePageAddress(page.frameUrl, origins.frames, window.location.pathname)

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

@@ -1,6 +1,10 @@
 /** The texts of the home and the docs pages, the catalogue's replacements applied. */
 export declare const PAGE_STRINGS: {
     homeEmpty: string;
+    homeNoStoryTitle: string;
+    homeNoStoryLead: string;
+    homeNoStoryHelp: string;
+    homeNoStoryCommand: string;
     homeSummary: (components: number, sources: number) => string;
     homeIntroError: string;
     recentlyOpened: string;

package/dist/src/shell/pageStrings.js

@@ -9,6 +9,10 @@ import { lateStrings } from "./strings.js";
 /** The texts of the home and the docs pages, the catalogue's replacements applied. */
 export const PAGE_STRINGS = lateStrings({
     homeEmpty: "No stories yet: a source with story files shows its families here.",
+    homeNoStoryTitle: "No stories yet",
+    homeNoStoryLead: "This catalogue lists the story files these patterns match, and none is there yet:",
+    homeNoStoryHelp: "Save a file one of them matches, and it shows here. To have one written from a component, run:",
+    homeNoStoryCommand: "npx forgebook new src/Button.tsx",
     homeSummary: (components, sources) => `${components} ${components === 1 ? "component" : "components"} in ${sources} ${sources === 1 ? "library" : "libraries"}.`,
     homeIntroError: "The library's introduction could not be read",
     recentlyOpened: "Recently opened",

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

@@ -0,0 +1,18 @@
+/**
+ * What a story's tags draw on a component's page (its status, a story's own), loaded from the page's own chunk with the
+ * same module as the sidebar's (`TagViews.tsx`).
+ *
+ * @remarks
+ * Kept apart from `tagView.tsx`, which the first load carries: imported by the pages that load later too, that module
+ * would be split out of the first load's chunk into one of its own, a request and some bytes more on every first load.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { TagViewProps } from "./TagViews.tsx";
+/**
+ * What the tags draw in one place of a component's page, once its code is there.
+ *
+ * @param props - the place, and what it reads.
+ */
+export declare const PageTagView: (props: TagViewProps) => ReactNode;