forgebook 0.3.2 → 0.4.0

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;
@@ -79,6 +105,9 @@ export declare const LATER_STRINGS: {
     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,17 @@ 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",
     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;

package/dist/src/shell/pageTagView.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { LazyView, lazyModule } from "./lazyModule.js";
+/** What the tags draw on the page, loaded on first use. */
+const PAGE_TAG_VIEW = lazyModule(() => import("./TagViews.js").then((module) => module.TagView));
+/**
+ * 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 const PageTagView = (props) => (_jsx(LazyView, { module: PAGE_TAG_VIEW, props: props, loading: null, failed: () => null }));

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

@@ -0,0 +1,14 @@
+/**
+ * Keeps a reader's play switch for their next visits, on what a browser keeps for a catalogue. Loaded with the parts that
+ * show the switch; the shell reads the choice back with its settings (`catalogueContext.ts`).
+ *
+ * @module
+ */
+import type { CatalogueSettings, PlaySwitch } from "../catalogue.ts";
+/**
+ * Keeps a reader's choice.
+ *
+ * @param catalogue - the catalogue, whose id the choice is kept under.
+ * @param play - the choice.
+ */
+export declare const rememberPlay: (catalogue: Pick<CatalogueSettings, "id">, play: PlaySwitch) => void;

package/dist/src/shell/playMemory.js

@@ -0,0 +1,8 @@
+import { writeStored } from "./useStored.js";
+/**
+ * Keeps a reader's choice.
+ *
+ * @param catalogue - the catalogue, whose id the choice is kept under.
+ * @param play - the choice.
+ */
+export const rememberPlay = (catalogue, play) => writeStored(`${catalogue.id}:play`, play);

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

@@ -0,0 +1,23 @@
+/**
+ * The sentences the API reference writes under a prop, and under a component that lists none: when a variant's prop can
+ * be passed, why a type is not the one its source writes, why no props are listed. Used by `ApiReference.tsx`.
+ *
+ * @remarks
+ * The shell checks these fields loosely when the docs arrive, so a reason it does not know is left out here rather
+ * than drawn wrong.
+ *
+ * @module
+ */
+import type { ComponentDocs, PropDocs } from "../componentDocs.ts";
+/**
+ * A prop's notes, in the order they are drawn: when it can be passed, then each note on its type.
+ *
+ * @param prop - the prop's condition and notes.
+ */
+export declare const propNoteTexts: (prop: Pick<PropDocs, "onlyWhen" | "notes">) => string[];
+/**
+ * Why a component lists no props, or none when its props are read.
+ *
+ * @param docs - the component's docs.
+ */
+export declare const propsNoteText: (docs: Pick<ComponentDocs, "propsNote">) => string | undefined;

package/dist/src/shell/propNotes.js

@@ -0,0 +1,37 @@
+import { codeSpan } from "./codeSpans.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+/**
+ * A prop's notes, in the order they are drawn: when it can be passed, then each note on its type.
+ *
+ * @param prop - the prop's condition and notes.
+ */
+export const propNoteTexts = (prop) => {
+    const { onlyWhen } = prop;
+    const condition = onlyWhen === undefined
+        ? []
+        : [
+            LATER_STRINGS.propOnlyWhen(codeSpan(onlyWhen.prop), onlyWhen.values.map((value) => codeSpan(typeof value === "string" ? JSON.stringify(value) : String(value))), onlyWhen.orOmitted === true)
+        ];
+    const types = (prop.notes ?? []).flatMap((note) => {
+        if (note.reason === "generic") {
+            return [LATER_STRINGS.propGeneric(codeSpan(note.parameter), codeSpan(note.type), note.shownAs)];
+        }
+        if (note.reason === "unresolved")
+            return [LATER_STRINGS.propUnresolved(codeSpan(note.name))];
+        return note.reason === "any" ? [LATER_STRINGS.propAny] : [];
+    });
+    return [...condition, ...types];
+};
+/**
+ * Why a component lists no props, or none when its props are read.
+ *
+ * @param docs - the component's docs.
+ */
+export const propsNoteText = (docs) => {
+    const note = docs.propsNote;
+    if (note?.reason === "untyped")
+        return LATER_STRINGS.propsUntyped;
+    if (note?.reason === "no-signature")
+        return LATER_STRINGS.propsNoSignature;
+    return note?.reason === "outside-package" ? LATER_STRINGS.propsOutsidePackage(note.count) : undefined;
+};

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

@@ -0,0 +1,17 @@
+/**
+ * A composed catalogue's index, fetched once per page when its section is first opened or one of its stories is shown.
+ *
+ * @remarks
+ * Read with no credentials: the index is public, and a cookie of the other host has nothing to do with it. A failure is
+ * kept too, so a section opened again says why without asking again; the page's next load tries once more.
+ *
+ * @module
+ */
+import { type CatalogueRef, type RefIndex } from "../catalogueRefs.ts";
+/**
+ * A composed catalogue's index.
+ *
+ * @param ref - the composed catalogue.
+ * @returns the index; rejected with the reason it could not be read.
+ */
+export declare const loadRefIndex: (ref: CatalogueRef) => Promise<RefIndex>;

package/dist/src/shell/refIndexLoad.js

@@ -0,0 +1,38 @@
+/**
+ * A composed catalogue's index, fetched once per page when its section is first opened or one of its stories is shown.
+ *
+ * @remarks
+ * Read with no credentials: the index is public, and a cookie of the other host has nothing to do with it. A failure is
+ * kept too, so a section opened again says why without asking again; the page's next load tries once more.
+ *
+ * @module
+ */
+import { refIndexAddress, refIndexOf } from "../catalogueRefs.js";
+import { REF_STRINGS } from "./refStrings.js";
+/** Each composed catalogue's index, by its address, as fetched once. */
+const loads = new Map();
+/** Fetches and reads an index. */
+const fetchIndex = async (address) => {
+    const answer = await fetch(address, { credentials: "omit" });
+    if (!answer.ok)
+        throw new Error(`${answer.status} ${answer.statusText}`.trim());
+    const index = refIndexOf(await answer.json());
+    if (index === undefined)
+        throw new Error(REF_STRINGS.notIndex);
+    return index;
+};
+/**
+ * A composed catalogue's index.
+ *
+ * @param ref - the composed catalogue.
+ * @returns the index; rejected with the reason it could not be read.
+ */
+export const loadRefIndex = (ref) => {
+    const address = refIndexAddress(ref);
+    const known = loads.get(address);
+    if (known !== undefined)
+        return known;
+    const load = fetchIndex(address);
+    loads.set(address, load);
+    return load;
+};

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

@@ -0,0 +1,34 @@
+/**
+ * What the shell draws of the composed catalogues (`refs`): their sidebar sections and the page of one of their stories.
+ * The generated page imports it (`forgebook/shell/refs`) only for a catalogue that composes one, so the others' first
+ * load carries not even the way to it.
+ *
+ * @remarks
+ * One module for both places, so a catalogue that composes others loads one chunk for them, and the shell keeps one
+ * slot type: a part drawn with the place it is drawn in.
+ *
+ * @module
+ */
+import type { ComponentType, ReactNode } from "react";
+import type { CatalogueRef } from "../catalogueRefs.ts";
+import { type RefStoryPageProps } from "./RefStoryPage.tsx";
+import { type SidebarRefsProps } from "./SidebarRefs.tsx";
+/** A part of the composed catalogues, with the place it is drawn in. */
+export type RefPartProps = ({
+    readonly place: "sidebar";
+} & SidebarRefsProps) | ({
+    readonly place: "page";
+} & RefStoryPageProps);
+/** The composed catalogues, as the generated page hands them to the shell. */
+export type ShellRefs = {
+    /** The catalogues, in the configuration's order. */
+    readonly catalogues: readonly CatalogueRef[];
+    /** Loads what draws them (`RefPart`). */
+    readonly load: () => Promise<ComponentType<RefPartProps>>;
+};
+/**
+ * A part of the composed catalogues: the sidebar's sections, or a story's page.
+ *
+ * @param props - the place, and that part's props.
+ */
+export declare const RefPart: (props: RefPartProps) => ReactNode;

package/dist/src/shell/refParts.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RefStoryPage } from "./RefStoryPage.js";
+import { SidebarRefs } from "./SidebarRefs.js";
+/**
+ * A part of the composed catalogues: the sidebar's sections, or a story's page.
+ *
+ * @param props - the place, and that part's props.
+ */
+export const RefPart = (props) => props.place === "sidebar" ? _jsx(SidebarRefs, { ...props }) : _jsx(RefStoryPage, { ...props });

package/dist/src/shell/refStory.css

@@ -0,0 +1,21 @@
+@layer catalogue {
+  .forgebook-ref-story {
+    overflow: auto;
+  }
+  .forgebook-ref-story__note {
+    margin: 0.25rem 0 0;
+    font: var(--forgebook-text-caption);
+    color: var(--forgebook-text-secondary);
+  }
+  .forgebook-ref-story__stage {
+    padding: 1rem;
+  }
+  .forgebook-ref-story__frame {
+    display: block;
+    width: 100%;
+    border: 0;
+    border-radius: var(--forgebook-radius-card);
+    box-shadow: 0 0 0 1px var(--forgebook-card-edge), 0 1px 3px var(--forgebook-shadow-soft);
+    background: var(--forgebook-surface);
+  }
+}

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

@@ -0,0 +1,13 @@
+/** The composed catalogues' texts, as shown: Forgebook's, with the catalogue's replacements. */
+export declare const REF_STRINGS: {
+    section: (title: string) => string;
+    loading: string;
+    empty: string;
+    unreadable: (title: string, reason: string) => string;
+    notIndex: string;
+    storyTitle: (story: string, catalogue: string) => string;
+    openThere: (catalogue: string) => string;
+    readOnly: string;
+    onFramesOrigin: (title: string) => string;
+    unknownRef: (id: string) => string;
+};

package/dist/src/shell/refStrings.js

@@ -0,0 +1,21 @@
+/**
+ * The words of the composed catalogues (`refs`): their sidebar section and their story's page, loaded with them, so a
+ * catalogue that composes none carries none. A catalogue replaces them as any other text of the shell
+ * (`strings: { "refs.loading": "Caricamento…" }`).
+ *
+ * @module
+ */
+import { textsOfGroup } from "./strings.js";
+/** The composed catalogues' texts, as shown: Forgebook's, with the catalogue's replacements. */
+export const REF_STRINGS = textsOfGroup("refs", {
+    section: (title) => `${title}, another catalogue`,
+    loading: "Loading its stories…",
+    empty: "It lists no story",
+    unreadable: (title, reason) => `${title} could not be read: ${reason}. It is built with forgebook build --agent-index, and its host lets this catalogue fetch its index (CORS).`,
+    notIndex: "its forgebook-agent.json is not an index this version reads",
+    storyTitle: (story, catalogue) => `${story}, from ${catalogue}`,
+    openThere: (catalogue) => `Open in ${catalogue}`,
+    readOnly: "Shown from another catalogue, read-only: its controls and panel are in its own page.",
+    onFramesOrigin: (title) => `${title} is served on the origin this catalogue's stories run on, where it would share their storage: serve it elsewhere.`,
+    unknownRef: (id) => `No composed catalogue "${id}" in this configuration: it may have been removed. Pick one in the sidebar.`
+});