forgebook 0.3.1 → 0.3.3

package/README.md

@@ -9,7 +9,7 @@ per story, switches for theme, contrast, motion and language, and a props table
 > and every change is in the
 > [changelog](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/CHANGELOG.md).
 
-**Requirements:** Node 22.18 or later · Vite 8 (the catalogue is built on it; other bundlers are not supported) · React 19 through
+**Requirements:** Node 22.18 or later · Vite 8.3.4+ (the catalogue is built on it; other bundlers are not supported) · React 19 through
 [`@forgebook/react`](https://www.npmjs.com/package/@forgebook/react), Vue 3.5 through
 [`@forgebook/vue`](https://www.npmjs.com/package/@forgebook/vue) (a Nuxt project's through
 [`@forgebook/nuxt`](https://www.npmjs.com/package/@forgebook/nuxt)), Svelte 5 through
@@ -194,6 +194,15 @@ too, with a warning.
 
 It adds about a dozen packages to a React and Vite project.
 
+## On a narrow window
+
+Below 720 px the sidebar stops taking room from the page. It starts closed, opens from the toolbar's sidebar button and
+slides over the page, which keeps the whole width and cannot be reached while the sidebar is open. A tap outside it,
+Escape (once the search is empty and no menu is open), its own button or opening any page closes it, and the focus goes
+back to the button, unless a search's result has taken it to what it found. Opening it there changes
+nothing a wider window remembers: the sidebar a person showed or hid on a wide window is as they left it, width
+included. A reduced-motion preference shows and hides it at once.
+
 ## The toolbar
 
 The View menu holds every control: the catalogue's switches, and Forgebook's own (the background, the style sheets, the
@@ -498,8 +507,8 @@ The buttons read their colours from the page's theme.
 
 The field at the top of the sidebar searches the whole catalogue. The tree filters by name as you type, for browsing;
 beside it a list ranks everything the words find, each component or page with what matched inside it and why (a prop,
-an event, a heading, a sentence, a story), the words marked. `/` or ⌘K (Ctrl+K) comes to the field from anywhere, ↑ and ↓
-move, Enter opens at the exact heading or prop, ⌘Enter or a modified press opens a new tab, Escape empties the field.
+an event, a heading, a sentence, a story), the words marked. `/` or ⌘K (Ctrl+K) comes to the field from anywhere (with the sidebar hidden, ⌘K alone,
+which shows it), ↑ and ↓ move, Enter opens at the exact heading or prop, ⌘Enter or a modified press opens a new tab, Escape empties the field.
 
 A prop has an address of its own, so a link to one can be pasted anywhere: `?component=acme:inputs-select#prop.value`,
 and `#prop.Group.label` for a prop of a part named in `subcomponents`. A heading of a component's documentation file
@@ -1086,8 +1095,9 @@ it, and the Embed button's **Follow the story's height** adds the few lines that
 iframe, since its modules are loaded as those of its own origin.
 
 An embed sends nothing but the height and listens to nothing from the page around it, and it keeps working where a browser
-denies a third-party frame its storage. What it does take from outside is its address: like the catalogue's own `args`, the
-address reaches the story's props, so a story that renders a prop as raw HTML should not be published for anyone to frame.
+denies a third-party frame its storage. What it does take from outside is its address, checked as the catalogue's own
+`args` are: a story receives only the props its panel can set, with a value of their type. A prop the story does declare
+still reaches it, so a story that renders a prop as raw HTML should not be published for anyone to frame.
 And a height says something: a page that can reach your catalogue can tell whether a story exists.
 
 Forgebook sets no framing headers, on the dev server or in a build, so what you host keeps the rules it has. To choose who may

package/dist/bin/forgebook/agents.md

@@ -84,9 +84,9 @@ in JSON with `--json`, and every answer about a story carries the links that ope
   the window (`style={{ flex: 1 }}`) needs `parameters.layout: "fullscreen"`; the app's root providers
   (`SafeAreaProvider`, a theme) go in the preview's decorators. A component that calls a native module or a gesture
   of native code does not draw in a browser: give it a `.web.tsx` file, or mock what it calls in the preview.
-- A link may carry the Props tab's values (`args=` in the address, JSON). The catalogue applies only the props the
-  story's panel can set, with a value of their type; to show a story with other values, write a story with those
-  args rather than a link.
+- A link or an embed may carry the Props tab's values (`args=` in the address, JSON). The catalogue applies only the
+  props the story's panel can set, with a value of their type; to show a story with other values, write a story with
+  those args rather than a link.
 - `parameters.height` gives the frame the room an overlay the story opens needs (a menu, a popover), in CSS px.
 - A screen meant for a phone or a tablet can be shown in a drawn device by default:
   `parameters: { device: { frame: true, model: "iphone-16" } }` (on the meta for every story; `orientation:
@@ -115,7 +115,8 @@ in JSON with `--json`, and every answer about a story carries the links that ope
   and what its server code reads with `nextjs.cookies`, `headers` and `draftMode`. A link or a router call moves the
   story's route and is listed among its events; a `play` reads where it went with `storyRoute()`
   (`@forgebook/nextjs/route`). Async server components are drawn; what they reach on a server (a database, the file
-  system) is not there: fetch it and mock it with `parameters.msw`.
+  system) is not there: fetch it and mock it with `parameters.msw`. In the server tests a server component's `fetch` never
+  reaches the network, whatever its address: a fetch no handler answers fails the story, naming the address.
 
 - Say when a component is for and when it is not, in its TSDoc: `@useWhen`, `@avoidWhen`, `@alternatives`, `@deprecated`,
   `@replacedBy`. `forgebook story` returns them as `docs.guidance`: read them before using a component, and never use a

package/dist/src/addressArgs.d.ts

@@ -12,12 +12,16 @@
  * left out and reported. A value that is code never comes from an address: a named value is looked up among the
  * source's own entries only, never through an object's prototype (`constructor`). Pure.
  *
+ * A frame takes values from one kind of message only, whichever frame it is (the stage's, an embed's, a plugin's aside),
+ * so `checkedArgsMessage` builds it, from nothing but what this check sealed (`AcceptedArgs`): a page that skipped the
+ * check has no value of that type to give it. A test holds every other module to not writing the message itself.
+ *
  * @module
  */
 import type { StoryControlsSetting } from "@forgebook/story-format/source";
 import { type PanelArgTypes, type PanelProp } from "./argTypes.ts";
 import type { PropDocs } from "./componentDocs.ts";
-import { type ArgValue, type PanelArgs } from "./messages.ts";
+import { type ArgValue, type PanelArgs, type ShellMessage } from "./messages.ts";
 import { type NamedValues } from "./namedValues.ts";
 /** What a story declares about the args the panel sets, as the shell knows it once the story's frame is ready. */
 export type ArgDeclaration = {
@@ -47,7 +51,20 @@ export type CheckedArgs = {
     readonly accepted: PanelArgs;
     /** The values left out, in the address's order. */
     readonly dropped: readonly DroppedArg[];
+    /** The values the story receives, as a frame can be told them. */
+    readonly sealed: AcceptedArgs;
+};
+/** What only this module can write on values: the type system's proof that they went through the check. */
+declare const ACCEPTED: unique symbol;
+/** Values the check accepted, the only ones a frame can be told. */
+export type AcceptedArgs = {
+    /** The values. */
+    readonly values: PanelArgs;
+    /** Marks them as the check's. */
+    readonly [ACCEPTED]: true;
 };
+/** No values: what a frame the address has no say in receives (a story on a docs page). */
+export declare const NO_ACCEPTED_ARGS: AcceptedArgs;
 /**
  * The props the panel sets for a story, whatever the address says: the component's props with the `argTypes` over
  * them and the args only the `argTypes` name, then the story's own args the two leave out, each kept only when the
@@ -72,3 +89,10 @@ export declare const isValueOfProp: (prop: PanelProp, value: ArgValue, namedValu
  * @param declaration - what the story declares.
  */
 export declare const checkedAddressArgs: (args: PanelArgs, declaration: ArgDeclaration) => CheckedArgs;
+/**
+ * The message that gives a frame its values.
+ *
+ * @param accepted - the values `checkedAddressArgs` accepted.
+ */
+export declare const checkedArgsMessage: (accepted: AcceptedArgs) => ShellMessage;
+export {};

package/dist/src/addressArgs.js

@@ -1,6 +1,10 @@
 import { panelProps, settableProps } from "./argTypes.js";
 import { isChoiceList, isNamedArg } from "./messages.js";
 import { namedValueOf } from "./namedValues.js";
+/** What only this module can write on values: the type system's proof that they went through the check. */
+const ACCEPTED = Symbol("accepted");
+/** No values: what a frame the address has no say in receives (a story on a docs page). */
+export const NO_ACCEPTED_ARGS = { values: {}, [ACCEPTED]: true };
 /** A prop made from one of the story's own args, for an arg neither the types nor the `argTypes` name. */
 const propOfStoryArg = (name, value) => {
     const prop = { name, type: "", description: "", isRequired: false };
@@ -105,5 +109,15 @@ export const checkedAddressArgs = (args, declaration) => {
         else
             accepted.push([name, value]);
     }
-    return { accepted: Object.fromEntries(accepted), dropped };
+    const values = Object.fromEntries(accepted);
+    return { accepted: values, dropped, sealed: { values, [ACCEPTED]: true } };
 };
+/**
+ * The message that gives a frame its values.
+ *
+ * @param accepted - the values `checkedAddressArgs` accepted.
+ */
+export const checkedArgsMessage = (accepted) => ({
+    type: "forgebook:args",
+    args: accepted.values
+});

package/dist/src/shell/EmbedPage.js

@@ -15,9 +15,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import "./embed.css";
 import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { checkedArgsMessage } from "../addressArgs.js";
 import { addressArgsFor } from "../addressTexts.js";
 import { EMBED_SIZE_TYPE } from "../embed.js";
 import { parsePanelArgsParam } from "../messages.js";
+import { sourceFiles } from "../sourceFiles.js";
 import { storyBackground } from "../storyBackground.js";
 import { NOT_FIXED, withFixed } from "../storyGlobals.js";
 import { findStory, storyTree } from "../storyTree.js";
@@ -28,11 +30,17 @@ import { framesOrigin } from "./framesOrigin.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { shellIsDark } from "./shellScheme.js";
 import { STRINGS } from "./strings.js";
+import { useAddressArgs } from "./useAddressArgs.js";
 import { APPEARANCE_ATTRIBUTE } from "./useAppearance.js";
 import { useFrameMessages } from "./useFrameMessages.js";
+import { usePanelDocs } from "./usePanelDocs.js";
 import { useSystemDark } from "./useSystemDark.js";
 /** The height of the frame before its story reports its own, in CSS px, in a page with no height of its own yet. */
 const WAITING_HEIGHT = 240;
+/** No actions, before the frame reported its own. */
+const NO_ACTIONS = [];
+/** No `argTypes`, before the frame reported its own. */
+const NO_ARG_TYPES = {};
 /**
  * Tells the page around the embed how tall the story is.
  *
@@ -98,17 +106,34 @@ const EmbedNotice = ({ message, detail, isFailure }) => {
  *
  * @param props - the story, the view, its args and the frame page.
  */
-const EmbedStory = ({ location, view, panelArgs, frameUrl }) => {
+const EmbedStory = ({ location, view, panelArgs, loadDocs, namedValues, frameUrl }) => {
     const catalogue = useCatalogue();
     const { story, component, source } = location;
     const [fixed, setFixed] = useState(NOT_FIXED);
     const [failure, setFailure] = useState(undefined);
+    const [ready, setReady] = useState(undefined);
+    const storyRef = useRef(null);
+    // the docs only serve the check: an embed whose address names no value does not load them
+    const hasValues = Object.keys(panelArgs).length > 0;
+    const docs = usePanelDocs(hasValues ? loadDocs : undefined, component.name, ready?.args, ready?.actions ?? NO_ACTIONS);
+    // whoever embeds the story writes its address, as whoever shares a link does: the same check applies
+    const addressArgs = useAddressArgs({
+        panelArgs,
+        docs,
+        storyArgs: ready?.args,
+        argTypes: ready?.argTypes ?? NO_ARG_TYPES,
+        controls: ready?.controls ?? "all",
+        namedValues,
+        frames: storyRef
+    });
     const { heights, settled } = useFrameMessages({
         onReady: (frame, message) => {
             setFixed(message.fixed);
             setFailure(undefined);
-            const args = { type: "forgebook:args", args: panelArgs };
-            frame.postMessage(args, framesOrigin());
+            setReady(message);
+            const accepted = addressArgs.acceptedFor(message);
+            if (accepted !== undefined)
+                frame.postMessage(checkedArgsMessage(accepted), framesOrigin());
         },
         onCall: () => undefined,
         onFailed: (_storyId, message) => setFailure(message)
@@ -135,7 +160,7 @@ const EmbedStory = ({ location, view, panelArgs, frameUrl }) => {
     useHostHeight(failure === undefined ? ownHeight : undefined);
     return (_jsxs("main", { className: "forgebook-embed", style: {
             backgroundColor: storyBackground(source.background, shownView, catalogue, isSystemDark)
-        }, children: [failure === undefined ? null : (_jsx(EmbedNotice, { message: STRINGS.embedFailed, detail: failure, isFailure: true })), _jsx("div", { className: "forgebook-embed__story", hidden: failure !== undefined, style: { width: shownView.width === "fill" ? undefined : shownView.width }, children: _jsx(FrameView, { title: STRINGS.frameTitle(component.name, story.name), address: address, heights: heights, settled: settled, fallbackHeight: WAITING_HEIGHT, sceneHeight: Math.max(story.height ?? 0, windowHeight), fixedHeight: fixedHeight }) })] }));
+        }, children: [failure === undefined ? null : (_jsx(EmbedNotice, { message: STRINGS.embedFailed, detail: failure, isFailure: true })), _jsx("div", { ref: storyRef, className: "forgebook-embed__story", hidden: failure !== undefined, style: { width: shownView.width === "fill" ? undefined : shownView.width }, children: _jsx(FrameView, { title: STRINGS.frameTitle(component.name, story.name), address: address, heights: heights, settled: settled, fallbackHeight: WAITING_HEIGHT, sceneHeight: Math.max(story.height ?? 0, windowHeight), fixedHeight: fixedHeight }) })] }));
 };
 /**
  * The page: the story the address names, or why there is none.
@@ -150,15 +175,16 @@ const EmbedContent = ({ title, sources, frameUrl, addressTexts }) => {
     const storyId = params.get("story");
     const location = storyId === null ? undefined : findStory(tree, storyId);
     const name = location?.component.name;
+    // one object for as long as the address is read: the check is not run again for each render
+    const panelArgs = useMemo(() => addressArgsFor(parsePanelArgsParam(params.get("args")), addressTexts), [params, addressTexts]);
     useEffect(() => {
         document.title = name === undefined ? title : `${name} · ${title}`;
     }, [name, title]);
     if (location === undefined) {
         return (_jsx("main", { className: "forgebook-embed", children: _jsx(EmbedNotice, { message: storyId === null ? LATER_STRINGS.embedNoStory : LATER_STRINGS.embedUnknownStory(storyId) }) }));
     }
-    return (_jsx(EmbedStory, { location: location, view: parseView(params.toString(), catalogue), 
-        // whoever embeds the story writes its address, as whoever shares a link does: the same rule applies
-        panelArgs: addressArgsFor(parsePanelArgsParam(params.get("args")), addressTexts), frameUrl: frameUrl }));
+    const source = sources.find((each) => each.id === location.source.id);
+    return (_jsx(EmbedStory, { location: location, view: parseView(params.toString(), catalogue), panelArgs: panelArgs, loadDocs: source === undefined ? undefined : sourceFiles(source).docs[location.story.file], namedValues: source?.namedValues, frameUrl: frameUrl }));
 };
 /**
  * One story alone, inside the catalogue's settings.

package/dist/src/shell/PluginBlockHost.js

@@ -5,6 +5,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * @module
  */
 import { useCallback, useMemo, useRef } from "react";
+import { NO_ACCEPTED_ARGS } from "../addressArgs.js";
 import { findStory } from "../storyTree.js";
 import { frameAddress, isComparing, liveView } from "../viewState.js";
 import { showAsideStory } from "./asideStory.js";
@@ -29,7 +30,7 @@ export const PluginBlockHost = ({ load, pluginId, argument, body, page }) => {
             address: frameAddress(frameUrl, options.storyId, view, switches),
             width: "fill",
             background: backgroundOf(location.source),
-            args: {},
+            args: NO_ACCEPTED_ARGS,
             view: isComparing(view) ? undefined : liveView(view)
         });
     }, []);

package/dist/src/shell/PluginTabHost.js

@@ -5,7 +5,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  * @module
  */
-import { useCallback, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 import { showAsideStory } from "./asideStory.js";
 import { PluginViewHost, pluginText, useShellAppearance } from "./PluginViewHost.js";
 /**
@@ -18,7 +18,24 @@ export const PluginTabHost = ({ load, pluginId, strings, story, report, aside })
     // read when the view asks: the stage of that moment, without a new context for every change of the stage
     const asideRef = useRef(aside);
     asideRef.current = aside;
-    const showStory = useCallback((target, { title }) => showAsideStory(target, title, asideRef.current), []);
+    const asideFrames = useRef(new Set());
+    const showStory = useCallback((target, { title }) => {
+        const frame = showAsideStory(target, title, asideRef.current);
+        asideFrames.current.add(frame);
+        return {
+            remove: () => {
+                asideFrames.current.delete(frame);
+                frame.remove();
+            }
+        };
+    }, []);
+    const { args } = aside;
+    useEffect(() => {
+        if (args === undefined)
+            return;
+        for (const frame of asideFrames.current)
+            frame.settle(args);
+    }, [args]);
     const text = useMemo(() => pluginText(strings, pluginId), [strings, pluginId]);
     const context = useMemo(() => ({ appearance, text, story, report, showStory }), [appearance, text, story, report, showStory]);
     return _jsx(PluginViewHost, { load: load, context: context });

package/dist/src/shell/SearchPanel.js

@@ -18,10 +18,9 @@ import { searchables, searchCatalogue } from "../search.js";
 import { SEARCH_STRINGS } from "./searchStrings.js";
 import { shownTree } from "./treeSearch.js";
 import { useSearchIndex } from "./useSearchIndex.js";
+import { SIDE_BY_SIDE_WIDTH } from "./useSidebarLayout.js";
 /** How much a page shows: what a person reads before refining the words. */
 const LIMITS = { results: 24, hits: 3 };
-/** The narrowest window where the list opens beside the sidebar: a smaller one has it over the sidebar, under the field. */
-const BESIDE_WIDTH = 720;
 /** The room between the field and the list when the list opens under it, in CSS px. */
 const LIST_GAP = 6;
 /** The room the list leaves around it, in CSS px. */
@@ -35,7 +34,7 @@ const LIST_WIDTH = "38rem";
  * @param sidebarWidth - the sidebar's width, in CSS px.
  */
 const listPlace = (field, sidebarWidth) => {
-    if (window.innerWidth < BESIDE_WIDTH)
+    if (window.innerWidth < SIDE_BY_SIDE_WIDTH)
         return { top: field.bottom + LIST_GAP, insetInline: LIST_MARGIN };
     const start = sidebarWidth + LIST_MARGIN;
     return {

package/dist/src/shell/Shell.js

@@ -19,7 +19,7 @@ import { LogicMark } from "./LogicMark.js";
 import { lazyModule } from "./lazyModule.js";
 import { PluginHostsContext } from "./pluginHostsContext.js";
 import { Sidebar } from "./Sidebar.js";
-import { SidebarHandle } from "./SidebarHandle.js";
+import { SidebarEdge } from "./SidebarHandle.js";
 import { Stage } from "./Stage.js";
 import { StoryPicker } from "./StoryPicker.js";
 import { STRINGS } from "./strings.js";
@@ -28,6 +28,7 @@ import { useAppearance } from "./useAppearance.js";
 import { useRecentPages } from "./useRecentPages.js";
 import { useShownView } from "./useShownView.js";
 import { useSidebarLayout } from "./useSidebarLayout.js";
+import { useSidebarOverlay } from "./useSidebarOverlay.js";
 import { useStoryHeights } from "./useStoryHeights.js";
 import { useStoryIdsElement } from "./useStoryIdsElement.js";
 import { useStoryKeys } from "./useStoryKeys.js";
@@ -222,7 +223,7 @@ const fixedOfShown = (fixedViews, shown) => shown.kind === "story" ? (fixedViews
  *
  * @param props - whether the home is shown, and the toolbar's props.
  */
-const ShellBar = ({ isHome, ...toolbar }) => isHome ? (_jsx("div", { className: "forgebook-toolbar", children: toolbar.onShowSidebar === undefined ? null : (_jsx(ShowSidebarButton, { onShowSidebar: toolbar.onShowSidebar })) })) : (_jsx(Toolbar, { ...toolbar }));
+const ShellBar = ({ isHome, ...toolbar }) => isHome ? (_jsx("div", { className: "forgebook-toolbar", children: toolbar.onShowSidebar === undefined ? null : (_jsx(ShowSidebarButton, { onShowSidebar: toolbar.onShowSidebar, showSidebarRef: toolbar.showSidebarRef })) })) : (_jsx(Toolbar, { ...toolbar }));
 /**
  * What a component's page loads: its first file's docs and page, as Storybook's docs come from the first file of a
  * title, and the code of every file, for each example's Code card.
@@ -415,10 +416,16 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
     // the written home's module, loaded when the home is first opened
     const writtenHome = useMemo(() => (home === undefined ? undefined : lazyModule(home)), [home]);
     const idsByTitle = useMemo(() => componentIdsByTitle(tree), [tree]);
-    const { width: sidebarWidth, setWidth: setSidebarWidth, isOpen: isSidebarOpen, setIsOpen: setIsSidebarOpen } = useSidebarLayout();
-    const showSidebar = useCallback(() => setIsSidebarOpen(true), [setIsSidebarOpen]);
     const catalogue = useCatalogue();
     const { address, visit, pageAddress, openPage, openFound, openAnchor, replaceAddress } = useAddress(catalogue, addressTexts);
+    const { width: sidebarWidth, setWidth: setSidebarWidth, isOpen: isSidebarOpen, setIsOpen: setIsSidebarOpen, isOverlay: isSidebarOverlay } = useSidebarLayout(visit);
+    const showSidebar = useCallback(() => setIsSidebarOpen(true), [setIsSidebarOpen]);
+    const hideSidebar = useCallback(() => setIsSidebarOpen(false), [setIsSidebarOpen]);
+    const { isOver: isSidebarOver, sidebarRef, hideButtonRef, showButtonRef } = useSidebarOverlay({
+        isOverlay: isSidebarOverlay,
+        isOpen: isSidebarOpen,
+        onClose: hideSidebar
+    });
     // each page's last scroll position, kept across the component pages and the stage
     const scrollPositions = useRef(new Map());
     const scroll = { visit, positions: scrollPositions.current };
@@ -489,7 +496,9 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
         header,
         scroll
     };
-    return (_jsxs("div", { className: "catalogue", children: [_jsx(Sidebar, { width: sidebarWidth, isOpen: isSidebarOpen, onHide: () => setIsSidebarOpen(false), onShow: showSidebar, appearance: appearance, title: title, logo: logo, hasBranding: hasBranding !== false, tree: tree, sources: sources, searchHref: (target) => addressQuery(pageAddress(target), catalogue), onOpenResult: openFound, isHome: shown.kind === "home", homeHref: addressQuery(pageAddress(HOME), catalogue), onOpenHome: () => openPage(HOME), current: sidebarCurrent(location, shownStoryId), currentPageId: shownPageLocation?.page.id, pageHref: (id) => addressQuery(pageAddress({ kind: "page", id }), catalogue), onOpenPage: (id) => openPage({ kind: "page", id }), componentHref: (sourceId, componentTitle) => addressQuery(pageAddress(titledPage(idsByTitle, sourceId, componentTitle)), catalogue), onOpenComponent: (sourceId, componentTitle) => openPage(titledPage(idsByTitle, sourceId, componentTitle)) }), isSidebarOpen ? _jsx(SidebarHandle, { width: sidebarWidth, onWidthChange: setSidebarWidth }) : null, _jsxs("main", { className: "forgebook-main", children: [_jsx(ShellBar, { isHome: hasNoStories(shown), view: shownView, onViewChange: changeShownView, isStoryPage: shown.kind === "story", isComponentPage: shown.kind === "component", isLogic: isLogicPage(shown), onShowSidebar: isSidebarOpen ? undefined : () => setIsSidebarOpen(true), shownWidth: shown.kind === "story" ? shownWidth : undefined, fixed: fixedOfShown(fixedViews, shown), deviceDefault: deviceOfShown(catalogue.device, shown) }), shown.kind === "component" ? (_jsx(LazyPage, { module: COMPONENT_PAGE, header: header, pageProps: {
+    return (_jsxs("div", { className: "catalogue", children: [_jsx(Sidebar, { width: sidebarWidth, isOpen: isSidebarOpen, isOverlay: isSidebarOverlay, sidebarRef: sidebarRef, hideButtonRef: hideButtonRef, onHide: hideSidebar, onShow: showSidebar, appearance: appearance, title: title, logo: logo, hasBranding: hasBranding !== false, tree: tree, sources: sources, searchHref: (target) => addressQuery(pageAddress(target), catalogue), onOpenResult: openFound, isHome: shown.kind === "home", homeHref: addressQuery(pageAddress(HOME), catalogue), onOpenHome: () => openPage(HOME), current: sidebarCurrent(location, shownStoryId), currentPageId: shownPageLocation?.page.id, pageHref: (id) => addressQuery(pageAddress({ kind: "page", id }), catalogue), onOpenPage: (id) => openPage({ kind: "page", id }), componentHref: (sourceId, componentTitle) => addressQuery(pageAddress(titledPage(idsByTitle, sourceId, componentTitle)), catalogue), onOpenComponent: (sourceId, componentTitle) => openPage(titledPage(idsByTitle, sourceId, componentTitle)) }), _jsx(SidebarEdge, { isOverlay: isSidebarOverlay, isOpen: isSidebarOpen, width: sidebarWidth, onWidthChange: setSidebarWidth, onHide: hideSidebar }), _jsxs("main", { className: "forgebook-main", inert: isSidebarOver, children: [_jsx(ShellBar, { isHome: hasNoStories(shown), view: shownView, onViewChange: changeShownView, isStoryPage: shown.kind === "story", isComponentPage: shown.kind === "component", isLogic: isLogicPage(shown), 
+                        // under a sidebar lying over the page the button stays, so the bar's controls never move behind it
+                        onShowSidebar: isSidebarOpen && !isSidebarOver ? undefined : showSidebar, showSidebarRef: showButtonRef, shownWidth: shown.kind === "story" ? shownWidth : undefined, fixed: fixedOfShown(fixedViews, shown), deviceDefault: deviceOfShown(catalogue.device, shown) }), shown.kind === "component" ? (_jsx(LazyPage, { module: COMPONENT_PAGE, header: header, pageProps: {
                             component: shown.location.component,
                             anchor: shown.anchor,
                             view: address.view,

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

@@ -11,7 +11,7 @@
  * @module
  */
 import type { StorySource } from "@forgebook/story-format/source";
-import { type ReactNode } from "react";
+import { type ReactNode, type Ref } from "react";
 import type { SearchTarget } from "../search.ts";
 import type { StoryTree } from "../storyTree.ts";
 import { type SidebarPageLinks } from "./SidebarDocs.tsx";
@@ -54,6 +54,12 @@ export type SidebarProps = SidebarPageLinks & {
     readonly width: number;
     /** Whether it is shown: hidden, it slides out and stays mounted, so its search and open families come back with it. */
     readonly isOpen: boolean;
+    /** Whether it lies over the page and not beside it, on a narrow window. */
+    readonly isOverlay: boolean;
+    /** The sidebar's element. */
+    readonly sidebarRef: Ref<HTMLElement>;
+    /** Its button that hides it. */
+    readonly hideButtonRef: Ref<HTMLButtonElement>;
     /** Hides the sidebar. */
     readonly onHide: () => void;
     /** Shows it again. */
@@ -66,4 +72,4 @@ export type SidebarProps = SidebarPageLinks & {
  *
  * @param props - the tree, the shown component and how to open one.
  */
-export declare const Sidebar: ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, onHide, onShow, appearance, ...links }: SidebarProps) => ReactNode;
+export declare const Sidebar: ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, isOverlay, sidebarRef, hideButtonRef, onHide, onShow, appearance, ...links }: SidebarProps) => ReactNode;

package/dist/src/shell/Sidebar.js

@@ -50,7 +50,7 @@ const componentCount = (family) => family.groups.reduce((count, group) => count
  *
  * @param props - the tree, the shown component and how to open one.
  */
-export const Sidebar = ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, onHide, onShow, appearance, ...links }) => {
+export const Sidebar = ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, isOverlay, sidebarRef, hideButtonRef, onHide, onShow, appearance, ...links }) => {
     const [query, setQuery] = useState("");
     const [filterTree, setFilterTree] = useState();
     const showFiltered = useCallback((filter) => setFilterTree(() => filter), []);
@@ -86,12 +86,12 @@ export const Sidebar = ({ title, logo, hasBranding, tree, sources: storySources,
     // the filter comes with the search's list; a moment before it, or with no words, the tree shows whole
     const { sources, pages } = isSearching && filterTree !== undefined ? filterTree(tree, query) : wholeTree(tree);
     const hasMatches = pages.length > 0 || sources.some(({ families }) => families.length > 0);
-    return (_jsxs("aside", { className: "forgebook-sidebar", "data-open": isOpen ? "" : undefined, inert: !isOpen, style: { width, marginInlineStart: isOpen ? 0 : -width }, children: [_jsxs("div", { className: "forgebook-brand", children: [_jsxs("a", { className: "forgebook-brand__home", href: homeHref, "aria-current": isHome ? "page" : undefined, title: STRINGS.home, onClick: (event) => {
+    return (_jsxs("aside", { ref: sidebarRef, className: "forgebook-sidebar", "data-open": isOpen ? "" : undefined, "data-overlay": isOverlay ? "" : undefined, inert: !isOpen, style: { width, marginInlineStart: isOpen ? 0 : -width }, children: [_jsxs("div", { className: "forgebook-brand", children: [_jsxs("a", { className: "forgebook-brand__home", href: homeHref, "aria-current": isHome ? "page" : undefined, title: STRINGS.home, onClick: (event) => {
                             if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
                                 return;
                             event.preventDefault();
                             onOpenHome();
-                        }, children: [mark === undefined ? null : (_jsx("img", { className: "forgebook-brand__logo", src: mark, alt: "", width: 28, height: 28 })), _jsx("span", { className: "forgebook-brand__name", children: title })] }), _jsx("button", { type: "button", className: "forgebook-icon-button forgebook-brand__hide", title: STRINGS.hideSidebar, "aria-label": STRINGS.hideSidebar, onClick: onHide, children: _jsx(Icon, { name: "sidebar", size: 14 }) })] }), _jsx(SidebarSearch, { query: query, onQueryChange: setQuery, onFilterReady: showFiltered, tree: tree, sources: storySources, sidebarWidth: width, isSidebarOpen: isOpen, onShowSidebar: onShow, searchHref: searchHref, onOpenResult: onOpenResult }), _jsxs("nav", { ref: navRef, className: "forgebook-tree", "aria-label": STRINGS.componentsNav, children: [hasMatches ? null : _jsx("p", { className: "forgebook-tree__empty", children: STRINGS.noMatch }), _jsx(SidebarDocs, { sources: pages, currentPageId: currentPageId, isSearching: isSearching, foldChoices: foldChoices, onFoldChange: setFoldOpen, pageHref: pageHref, onOpenPage: onOpenPage }), sources.map(({ source, families }) => families.length === 0 ? null : (_jsxs("section", { className: "forgebook-tree__source", children: [_jsxs("h2", { className: "forgebook-tree__source-name", children: [source.logo === undefined ? null : (_jsx("img", { className: "forgebook-source-logo", src: source.logo, alt: "", width: 14, height: 14 })), source.name] }), families.map((family) => {
+                        }, children: [mark === undefined ? null : (_jsx("img", { className: "forgebook-brand__logo", src: mark, alt: "", width: 28, height: 28 })), _jsx("span", { className: "forgebook-brand__name", children: title })] }), _jsx("button", { ref: hideButtonRef, type: "button", className: "forgebook-icon-button forgebook-brand__hide", title: STRINGS.hideSidebar, "aria-label": STRINGS.hideSidebar, onClick: onHide, children: _jsx(Icon, { name: "sidebar", size: 14 }) })] }), _jsx(SidebarSearch, { query: query, onQueryChange: setQuery, onFilterReady: showFiltered, tree: tree, sources: storySources, sidebarWidth: width, isSidebarOpen: isOpen, onShowSidebar: onShow, searchHref: searchHref, onOpenResult: onOpenResult }), _jsxs("nav", { ref: navRef, className: "forgebook-tree", "aria-label": STRINGS.componentsNav, children: [hasMatches ? null : _jsx("p", { className: "forgebook-tree__empty", children: STRINGS.noMatch }), _jsx(SidebarDocs, { sources: pages, currentPageId: currentPageId, isSearching: isSearching, foldChoices: foldChoices, onFoldChange: setFoldOpen, pageHref: pageHref, onOpenPage: onOpenPage }), sources.map(({ source, families }) => families.length === 0 ? null : (_jsxs("section", { className: "forgebook-tree__source", children: [_jsxs("h2", { className: "forgebook-tree__source-name", children: [source.logo === undefined ? null : (_jsx("img", { className: "forgebook-source-logo", src: source.logo, alt: "", width: 14, height: 14 })), source.name] }), families.map((family) => {
                                 const key = familyKey(source, family);
                                 // a search opens every family it finds something in
                                 const isOpen = isSearching || (foldChoices.get(key) ?? isCurrentFamily(source, family));

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

@@ -1,5 +1,6 @@
 /**
- * The handle on the sidebar's right edge: dragged, or moved with the arrow keys, it sets the sidebar's width.
+ * The handle on the sidebar's right edge: dragged, or moved with the arrow keys, it sets the sidebar's width; on a narrow
+ * window, where the sidebar lies over the page at no chosen width, the shade on the page takes its place.
  *
  * @module
  */
@@ -26,3 +27,15 @@ export declare const SidebarHandle: ({ width, onWidthChange }: {
     readonly width: number;
     readonly onWidthChange: (width: number) => void;
 }) => ReactNode;
+/**
+ * What borders the sidebar: beside the page its handle, while shown; over it the shade on the page.
+ *
+ * @param props - where the sidebar lies, whether it is shown, its width and how to hide it.
+ */
+export declare const SidebarEdge: ({ isOverlay, isOpen, width, onWidthChange, onHide }: {
+    readonly isOverlay: boolean;
+    readonly isOpen: boolean;
+    readonly width: number;
+    readonly onWidthChange: (width: number) => void;
+    readonly onHide: () => void;
+}) => ReactNode;

package/dist/src/shell/SidebarHandle.js

@@ -43,3 +43,13 @@ export const SidebarHandle = ({ width, onWidthChange }) => {
     };
     return (_jsx("div", { className: "forgebook-sidebar-handle", role: "separator", "aria-orientation": "vertical", "aria-label": STRINGS.sidebarWidth, "aria-valuenow": width, "aria-valuemin": SIDEBAR_WIDTH.min, "aria-valuemax": SIDEBAR_WIDTH.max, tabIndex: 0, onPointerDown: startResize, onKeyDown: resizeWithKeys }));
 };
+/**
+ * What borders the sidebar: beside the page its handle, while shown; over it the shade on the page.
+ *
+ * @param props - where the sidebar lies, whether it is shown, its width and how to hide it.
+ */
+export const SidebarEdge = ({ isOverlay, isOpen, width, onWidthChange, onHide }) => {
+    if (!isOverlay)
+        return isOpen ? _jsx(SidebarHandle, { width: width, onWidthChange: onWidthChange }) : null;
+    return (_jsx("div", { className: "forgebook-sidebar-shade", "data-open": isOpen ? "" : undefined, "aria-hidden": "true", onClick: onHide }));
+};

package/dist/src/shell/SidebarSearch.js

@@ -68,13 +68,16 @@ export const SidebarSearch = ({ query, onQueryChange, onFilterReady, tree, sourc
                                 event.preventDefault();
                                 return;
                             }
-                            // Escape empties the search first, then leaves the field
+                            // Escape empties the search first, then leaves the field; emptying uses the key up, so a sidebar lying over
+                            // the page stays open for it (`useSidebarOverlay.ts`)
                             if (event.key !== "Escape")
                                 return;
-                            if (query === "")
+                            if (query === "") {
                                 event.currentTarget.blur();
-                            else
-                                onQueryChange("");
+                                return;
+                            }
+                            event.preventDefault();
+                            onQueryChange("");
                         }, placeholder: STRINGS.searchPlaceholder, "aria-label": STRINGS.searchLabel, onChange: (event) => {
                             onQueryChange(event.target.value);
                             setIsListOpen(true);

package/dist/src/shell/Stage.js

@@ -12,9 +12,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * @module
  */
 import { useEffect, useMemo, useRef, useState } from "react";
+import { checkedArgsMessage } from "../addressArgs.js";
 import { panelProps, settableProps } from "../argTypes.js";
 import { matrixOf, matrixProps } from "../matrix.js";
-import { panelArgsParam, parsePanelArgsParam } from "../messages.js";
+import { panelArgsParam } from "../messages.js";
 import { withFixed, withOwnFixed } from "../storyGlobals.js";
 import { frameAddress, isComparing, liveView, schemeOf, viewParams } from "../viewState.js";
 import { useStoryClockControls } from "./ClockControls.js";
@@ -127,7 +128,8 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         storyArgs: storyArgs.get(story.id),
         argTypes: panel.argTypes,
         controls: panel.controls,
-        namedValues
+        namedValues,
+        frames: storyRef
     });
     const acceptedArgs = addressArgs.accepted;
     const values = { ...storyArgs.get(story.id), ...acceptedArgs };
@@ -160,7 +162,7 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
             // checked against the shown story's declaration only: a late message of the story shown before sends nothing
             const accepted = message.storyId === story.id ? addressArgs.acceptedFor(message) : undefined;
             if (accepted !== undefined)
-                send({ type: "forgebook:args", args: accepted });
+                send(checkedArgsMessage(accepted));
             send({ type: "forgebook:matrix", matrix });
             // the view may have changed while the frame loaded
             if (!isComparing(view))
@@ -186,14 +188,6 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
     // the docs may arrive after the frames: they learn the events then
     useEffect(() => tellFrames(storyRef.current, { type: "forgebook:events", names: eventNames }), [eventNames]);
     useEffect(() => tellFrames(storyRef.current, { type: "forgebook:matrix", matrix }), [matrix]);
-    // the values reach the frames from the address, so going back in the history sets them too; compared as text, so
-    // a frame is told again only when they change
-    const { acceptedParam } = addressArgs;
-    useEffect(() => {
-        if (acceptedParam === undefined)
-            return;
-        tellFrames(storyRef.current, { type: "forgebook:args", args: parsePanelArgsParam(acceptedParam) });
-    }, [acceptedParam]);
     // a change starts from the values the story takes: one the address named and the story does not is let go
     const changeValue = (name, value) => {
         const { [name]: _removed, ...rest } = acceptedArgs;
@@ -235,7 +229,8 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
             address: deviceAddress(frameAddress(frameUrl, story.id, view, switches), framed),
             width: framed?.area.width ?? view.width,
             background: backgroundOf(view),
-            args: panelArgs,
+            // as the stage's frames receive them: an aside asked for while the check waits for the docs is told when it ends
+            args: addressArgs.checked,
             view: liveView(view)
         }
     });

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

@@ -9,7 +9,7 @@
  *
  * @module
  */
-import { type ReactNode } from "react";
+import { type ReactNode, type Ref } from "react";
 import { type DeviceDefault } from "../deviceView.ts";
 import { type FixedView } from "../storyGlobals.ts";
 import { type ViewState } from "../viewState.ts";
@@ -23,8 +23,10 @@ export type ToolbarProps = {
     readonly isStoryPage?: boolean;
     /** Whether a component's page is shown: the audience changes nothing elsewhere. */
     readonly isComponentPage?: boolean;
-    /** Shows the hidden sidebar; none while it is shown. */
+    /** Shows the hidden sidebar; none while it is shown beside the page. */
     readonly onShowSidebar?: (() => void) | undefined;
+    /** The button that shows the sidebar, where the focus goes back when a sidebar over the page closes. */
+    readonly showSidebarRef?: Ref<HTMLButtonElement> | undefined;
     /** The width the shown story really has, in CSS px, for the width field; none on a component's page. */
     readonly shownWidth?: number | undefined;
     /** What the shown story fixes of the view: shown, and not changeable here; nothing by default. */
@@ -39,7 +41,7 @@ export type ToolbarProps = {
  *
  * @param props - what showing the sidebar does.
  */
-export declare const ShowSidebarButton: ({ onShowSidebar }: {
+export declare const ShowSidebarButton: ({ onShowSidebar, showSidebarRef }: Pick<ToolbarProps, "showSidebarRef"> & {
     readonly onShowSidebar: () => void;
 }) => ReactNode;
 /**
@@ -47,4 +49,4 @@ export declare const ShowSidebarButton: ({ onShowSidebar }: {
  *
  * @param props - the view, its setter, the page shown and the story's width.
  */
-export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, isComponentPage, onShowSidebar, shownWidth, fixed, isLogic, deviceDefault }: ToolbarProps) => ReactNode;
+export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, isComponentPage, onShowSidebar, showSidebarRef, shownWidth, fixed, isLogic, deviceDefault }: ToolbarProps) => ReactNode;