forgebook 0.3.0 → 0.3.2

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
@@ -1028,7 +1037,8 @@ its `frame-src`, in the preview's `frameDomains`).
   read. Vite checks `Host`
   first (`server.allowedHosts`, plain HTTP only), which stops a site that reaches `127.0.0.1` through its own domain.
 - **Only the files your project names are listed or read.** A catalogue's `stories` and `docs`, and the groups a module
-  of yours imports (`?forgebook-files`), are the only groups the server reads, whatever an address names. A query that
+  of yours imports (`?forgebook-files`), are the only groups the server reads, whatever an address names: any other
+  answers 404. A catalogue's tab left open across a restart gets its groups all the same. A query that
   names one file (`?forgebook-code`, `?forgebook-markdown`) follows Vite's `server.fs`, as `?raw` does.
 - **`server.fs.deny` wins over your globs.** A file it refuses stays out of the catalogue, its search and "Used in", with
   a warning. A file your globs name outside `server.fs.allow` is listed and served, as Vite serves any file a module of

package/dist/bin/forgebook/agents.md

@@ -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/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/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;

package/dist/src/shell/Toolbar.js

@@ -73,13 +73,13 @@ const CompareMenu = ({ view, onViewChange, isDisabled, fixed = NOT_FIXED }) => {
  *
  * @param props - what showing the sidebar does.
  */
-export const ShowSidebarButton = ({ onShowSidebar }) => (_jsx("button", { type: "button", className: "forgebook-icon-button", title: STRINGS.showSidebar, "aria-label": STRINGS.showSidebar, onClick: onShowSidebar, children: _jsx(Icon, { name: "sidebar", size: 14 }) }));
+export const ShowSidebarButton = ({ onShowSidebar, showSidebarRef }) => (_jsx("button", { ref: showSidebarRef, type: "button", className: "forgebook-icon-button", title: STRINGS.showSidebar, "aria-label": STRINGS.showSidebar, onClick: onShowSidebar, children: _jsx(Icon, { name: "sidebar", size: 14 }) }));
 /**
  * The toolbar.
  *
  * @param props - the view, its setter, the page shown and the story's width.
  */
-export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage = true, isComponentPage = false, onShowSidebar, shownWidth, fixed = NOT_FIXED, isLogic = false, deviceDefault = NO_DEVICE }) => {
+export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage = true, isComponentPage = false, onShowSidebar, showSidebarRef, shownWidth, fixed = NOT_FIXED, isLogic = false, deviceDefault = NO_DEVICE }) => {
     const layout = useToolbarLayout();
     const catalogue = useCatalogue();
     // the story's fixed values are shown, and a change of anything else keeps the user's own in the address
@@ -96,5 +96,5 @@ export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryP
     const moved = useToolbarOverflow(pinnedRef, pinned.map((each) => each.control.id));
     // a bar that wraps has room for every pinned control
     const onBar = layout.isWrapped ? pinned : pinned.filter((each) => !moved.includes(each.control.id));
-    return (_jsxs("div", { className: layout.isWrapped ? "forgebook-toolbar forgebook-toolbar--wrap" : "forgebook-toolbar", children: [onShowSidebar === undefined ? null : _jsx(ShowSidebarButton, { onShowSidebar: onShowSidebar }), _jsx(ViewMenu, { layout: layout, ownView: ownView, movedIds: [...(layout.isWrapped ? [] : moved), ...putAway], ...context }), onBar.length === 0 ? null : _jsx("span", { className: "forgebook-toolbar__divider" }), _jsx("div", { ref: pinnedRef, className: "forgebook-toolbar__pinned-list", children: onBar.map((each) => (_jsx(PinnedControl, { control: each.control, isHidden: each.isHidden, isChanged: hasViewChanges(ownView, catalogue.switches, [each.control.id], catalogue.audience), layout: layout, ...context }, each.control.id))) }), _jsxs("button", { type: "button", className: "forgebook-button", title: STRINGS.panel, "aria-pressed": view.isPanelOpen, disabled: !isStoryPage, onClick: () => onViewChange({ ...view, isPanelOpen: !view.isPanelOpen }), children: [_jsx(Icon, { name: "panel", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: STRINGS.panel })] }), isLogic ? null : (_jsx(CompareMenu, { view: view, onViewChange: onViewChange, isDisabled: !isStoryPage, fixed: fixed }))] }));
+    return (_jsxs("div", { className: layout.isWrapped ? "forgebook-toolbar forgebook-toolbar--wrap" : "forgebook-toolbar", children: [onShowSidebar === undefined ? null : (_jsx(ShowSidebarButton, { onShowSidebar: onShowSidebar, showSidebarRef: showSidebarRef })), _jsx(ViewMenu, { layout: layout, ownView: ownView, movedIds: [...(layout.isWrapped ? [] : moved), ...putAway], ...context }), onBar.length === 0 ? null : _jsx("span", { className: "forgebook-toolbar__divider" }), _jsx("div", { ref: pinnedRef, className: "forgebook-toolbar__pinned-list", children: onBar.map((each) => (_jsx(PinnedControl, { control: each.control, isHidden: each.isHidden, isChanged: hasViewChanges(ownView, catalogue.switches, [each.control.id], catalogue.audience), layout: layout, ...context }, each.control.id))) }), _jsxs("button", { type: "button", className: "forgebook-button", title: STRINGS.panel, "aria-pressed": view.isPanelOpen, disabled: !isStoryPage, onClick: () => onViewChange({ ...view, isPanelOpen: !view.isPanelOpen }), children: [_jsx(Icon, { name: "panel", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: STRINGS.panel })] }), isLogic ? null : (_jsx(CompareMenu, { view: view, onViewChange: onViewChange, isDisabled: !isStoryPage, fixed: fixed }))] }));
 };

package/dist/src/shell/shell.css

@@ -136,6 +136,31 @@
     border-inline-end: 1px solid var(--forgebook-separator);
     transition: margin-inline-start 320ms cubic-bezier(0.32, 0.72, 0, 1);
   }
+  .forgebook-sidebar[data-overlay] {
+    position: fixed;
+    inset-block: 0;
+    inset-inline-start: 0;
+    z-index: 22;
+    height: auto;
+    max-width: calc(100vw - 2rem);
+    transition: margin-inline-start 320ms cubic-bezier(0.32, 0.72, 0, 1), box-shadow 320ms cubic-bezier(0.32, 0.72, 0, 1);
+  }
+  .forgebook-sidebar[data-overlay][data-open] {
+    box-shadow: 0 0 0 1px var(--forgebook-edge), 0 18px 48px var(--forgebook-shadow-deep), 0 4px 12px var(--forgebook-shadow-lift);
+  }
+  .forgebook-sidebar-shade {
+    position: fixed;
+    inset: 0;
+    z-index: 21;
+    background: var(--forgebook-shade);
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity 320ms cubic-bezier(0.32, 0.72, 0, 1), visibility 320ms;
+  }
+  .forgebook-sidebar-shade[data-open] {
+    opacity: 1;
+    visibility: visible;
+  }
   .forgebook-appearance {
     position: relative;
     flex: none;
@@ -2476,7 +2501,9 @@
     .forgebook-stage-tools {
       animation-name: forgebook-appear;
     }
-    .forgebook-sidebar {
+    .forgebook-sidebar,
+    .forgebook-sidebar[data-overlay],
+    .forgebook-sidebar-shade {
       transition: none;
     }
     .forgebook-example__toggle svg,

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

@@ -1,3 +1,5 @@
+/** The narrowest window with room for the sidebar beside the page and for the search's list beside it, in CSS px. */
+export declare const SIDE_BY_SIDE_WIDTH = 720;
 /** The sidebar's layout and its setters. */
 export type SidebarLayout = {
     /** Its width, in CSS px. */
@@ -6,8 +8,16 @@ export type SidebarLayout = {
     readonly setWidth: (width: number) => void;
     /** Whether it is shown. */
     readonly isOpen: boolean;
-    /** Shows or hides it. */
+    /** Shows or hides it: kept for the next visit on a wide window, only for this visit of the page on a narrow one. */
     readonly setIsOpen: (isOpen: boolean) => void;
+    /** Whether the window is narrow, so that the sidebar, when shown, lies over the page and not beside it. */
+    readonly isOverlay: boolean;
 };
-/** The sidebar's layout. */
-export declare const useSidebarLayout: () => SidebarLayout;
+/**
+ * The sidebar's layout.
+ *
+ * @param visit - the page's visit, new whenever a page is opened or the history moves, the shown page opened again
+ *   included: whatever changes the page under a sidebar lying over it closes the sidebar, in the same render, so that
+ *   the new page is never drawn out of reach.
+ */
+export declare const useSidebarLayout: (visit: object) => SidebarLayout;

package/dist/src/shell/useSidebarLayout.js

@@ -1,18 +1,56 @@
 /**
- * The sidebar's width and whether it is shown: this browser's convenience, kept for the next visit, not the address's.
+ * The sidebar's width and whether it is shown: on a wide window, this browser's convenience, kept for the next visit, not
+ * the address's; on a narrow one, a moment's look over the page, which leaves what was kept alone.
+ *
+ * @remarks
+ * Beside the page, a sidebar on a phone's window leaves the page about 110 px. There it slides over the page instead
+ * (`useSidebarOverlay.ts`), starts closed, and belongs to the visit it was opened on. A choice kept from a wide window
+ * would otherwise cover the page at every load, and opening it on a phone would change what the wide window shows next.
  *
  * @module
  */
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
 import { boundedSidebarWidth, SIDEBAR_WIDTH } from "./SidebarHandle.js";
 import { useStored } from "./useStored.js";
+/** The narrowest window with room for the sidebar beside the page and for the search's list beside it, in CSS px. */
+export const SIDE_BY_SIDE_WIDTH = 720;
+/** The media query of a window too narrow for the sidebar beside the page. */
+const NARROW_WINDOW = `(max-width: ${SIDE_BY_SIDE_WIDTH - 1}px)`;
 /** The width a stored text holds, or the default. */
 const storedWidth = (stored) => {
     const width = Number(stored);
     return stored === null || !Number.isFinite(width) ? SIDEBAR_WIDTH.initial : boundedSidebarWidth(width);
 };
-/** The sidebar's layout. */
-export const useSidebarLayout = () => {
+/** Listens to the window crossing the narrow width. */
+const subscribeToNarrow = (onChange) => {
+    const query = window.matchMedia(NARROW_WINDOW);
+    query.addEventListener("change", onChange);
+    return () => query.removeEventListener("change", onChange);
+};
+/** Whether the window is narrow now. */
+const isNarrowNow = () => window.matchMedia(NARROW_WINDOW).matches;
+/**
+ * The sidebar's layout.
+ *
+ * @param visit - the page's visit, new whenever a page is opened or the history moves, the shown page opened again
+ *   included: whatever changes the page under a sidebar lying over it closes the sidebar, in the same render, so that
+ *   the new page is never drawn out of reach.
+ */
+export const useSidebarLayout = (visit) => {
     const [width, setWidth] = useStored("sidebar-width", storedWidth, String);
-    const [isOpen, setIsOpen] = useStored("sidebar", (stored) => stored !== "hidden", (shown) => (shown ? "shown" : "hidden"));
-    return { width, setWidth, isOpen, setIsOpen };
+    const [isKeptOpen, setIsKeptOpen] = useStored("sidebar", (stored) => stored !== "hidden", (shown) => (shown ? "shown" : "hidden"));
+    const isOverlay = useSyncExternalStore(subscribeToNarrow, isNarrowNow, () => false);
+    const [overlayVisit, setOverlayVisit] = useState(undefined);
+    // it does not come back open when the window turns narrow again
+    useEffect(() => {
+        if (!isOverlay)
+            setOverlayVisit(undefined);
+    }, [isOverlay]);
+    const setIsOpen = useCallback((isOpen) => {
+        if (isOverlay)
+            setOverlayVisit(isOpen ? visit : undefined);
+        else
+            setIsKeptOpen(isOpen);
+    }, [isOverlay, visit, setIsKeptOpen]);
+    return { width, setWidth, isOpen: isOverlay ? overlayVisit === visit : isKeptOpen, setIsOpen, isOverlay };
 };

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

@@ -0,0 +1,34 @@
+/**
+ * What a sidebar lying over the page does beyond its look: Escape closes it, the focus moves into it as it opens and back
+ * to the button that shows it as it closes. The page behind is made inert by the shell, and a tap on the shade closes it.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+/** What the shell reads, and wires to the sidebar and its buttons. */
+export type SidebarOverlay = {
+    /** Whether the sidebar lies over the page now: shown, on a narrow window. */
+    readonly isOver: boolean;
+    /** The sidebar. */
+    readonly sidebarRef: RefObject<HTMLElement | null>;
+    /** The sidebar's button that hides it: where the focus goes as it opens. */
+    readonly hideButtonRef: RefObject<HTMLButtonElement | null>;
+    /** The toolbar's button that shows it: where the focus goes back as it closes. */
+    readonly showButtonRef: RefObject<HTMLButtonElement | null>;
+};
+/** What the wiring needs to know of the sidebar. */
+export type SidebarOverlayState = {
+    /** Whether the window is narrow, so that a shown sidebar lies over the page. */
+    readonly isOverlay: boolean;
+    /** Whether it is shown. */
+    readonly isOpen: boolean;
+    /** Closes it. */
+    readonly onClose: () => void;
+};
+/**
+ * Wires a sidebar lying over the page; nothing on a wide window, where the sidebar sits beside it.
+ *
+ * @param state - the sidebar's state.
+ * @returns whether it lies over the page, and the references to give the sidebar and its buttons.
+ */
+export declare const useSidebarOverlay: ({ isOverlay, isOpen, onClose }: SidebarOverlayState) => SidebarOverlay;

package/dist/src/shell/useSidebarOverlay.js

@@ -0,0 +1,51 @@
+/**
+ * What a sidebar lying over the page does beyond its look: Escape closes it, the focus moves into it as it opens and back
+ * to the button that shows it as it closes. The page behind is made inert by the shell, and a tap on the shade closes it.
+ *
+ * @module
+ */
+import { useEffect, useRef } from "react";
+/**
+ * Wires a sidebar lying over the page; nothing on a wide window, where the sidebar sits beside it.
+ *
+ * @param state - the sidebar's state.
+ * @returns whether it lies over the page, and the references to give the sidebar and its buttons.
+ */
+export const useSidebarOverlay = ({ isOverlay, isOpen, onClose }) => {
+    const sidebarRef = useRef(null);
+    const hideButtonRef = useRef(null);
+    const showButtonRef = useRef(null);
+    const isOver = isOverlay && isOpen;
+    useEffect(() => {
+        if (!isOver)
+            return;
+        const closeOnEscape = (event) => {
+            // a key an input method is composing with, or one the search used to empty itself, is not for the sidebar; neither
+            // is one that closes a menu open in the sidebar, which handles it itself
+            if (event.key !== "Escape" || event.isComposing || event.defaultPrevented)
+                return;
+            const openMenu = sidebarRef.current?.querySelector(".forgebook-popover");
+            if (openMenu === null || openMenu === undefined)
+                onClose();
+        };
+        document.addEventListener("keydown", closeOnEscape);
+        return () => document.removeEventListener("keydown", closeOnEscape);
+    }, [isOver, onClose]);
+    const wasOver = useRef(false);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: also looked at when the window crosses the width, and never when a wide window's sidebar is hidden, which leaves the focus alone
+    useEffect(() => {
+        const focused = document.activeElement;
+        const isFocusInSidebar = sidebarRef.current?.contains(focused) === true;
+        // the platform's search key has already put the focus on the search field
+        if (isOver && !isFocusInSidebar)
+            hideButtonRef.current?.focus({ preventScroll: true });
+        // the sidebar went away with the focus in it, closed or by the window crossing the width; one still shown keeps the
+        // focus, and a search's result that has already taken it to what it found keeps it too
+        const isFocusLost = isFocusInSidebar || (wasOver.current && (focused === document.body || focused === null));
+        if (!isOver && sidebarRef.current?.inert === true && isFocusLost) {
+            showButtonRef.current?.focus({ preventScroll: true });
+        }
+        wasOver.current = isOver;
+    }, [isOver, isOverlay]);
+    return { isOver, sidebarRef, hideButtonRef, showButtonRef };
+};

package/dist/src/storyMocks.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A story's mock handlers (`parameters.msw.handlers`) read from its parameters, and run on a server in place of the
+ * network. Exported as `forgebook/story-mocks`, for `@forgebook/plugin-msw` and the adapters that render on a server.
+ *
+ * @remarks
+ * A server render (the generated server tests) has no service worker, and whatever answers on the test machine must
+ * not decide what a page draws. So the handlers the frame's worker serves are run here through MSW's `getResponse`, a
+ * plain call with no interception, so concurrent renders never see each other's handlers. A request no handler answers,
+ * one a handler answers with `passthrough()`, or one made with `bypass()`, fails with the error the adapter writes, which
+ * knows what its stories can give instead. A handler's `HttpResponse.error()` rejects the fetch and its redirect is
+ * followed, as in the frame.
+ *
+ * Imports nothing, MSW included: `msw` is an optional peer of each adapter that uses this, so it is resolved from that
+ * package and passed in. A strict package manager would not find it from here.
+ *
+ * @module
+ */
+/** What a story's mocks need to answer requests on a server. */
+export type ServerMocks = {
+    /** The story's handlers (`mockHandlersOf`). */
+    readonly handlers: readonly unknown[];
+    /** The origin of the story's page, which a handler's path (`/api/users`) is read from, as the frame reads it. */
+    readonly origin: string;
+    /** Imports `msw`, from the adapter that declares it as a peer; called only when there are handlers to run. */
+    readonly loadMsw: () => Promise<unknown>;
+    /** The error a request fails with when no handler answers it; the adapter also keeps it, to fail the render. */
+    readonly onUnanswered: (request: Request) => Error;
+    /** Whether the mocks answer an address, or the network does; every address by default. */
+    readonly isMocked?: (address: URL) => boolean;
+};
+/**
+ * The handlers a story's parameters declare, flat: a list, or a record of lists as MSW's Storybook addon writes them.
+ *
+ * @param parameters - the story's parameters.
+ * @returns the handlers; none when the story has no mocks.
+ */
+export declare const mockHandlersOf: (parameters: Readonly<Record<string, unknown>>) => readonly unknown[];
+/**
+ * Whether an address reaches the same server as a page: its origin, or another name of this machine on the same scheme
+ * and port (`127.0.0.1` or `[::1]` beside a `localhost` page), which a real machine answers the same.
+ *
+ * @param address - the address.
+ * @param page - the page's address.
+ */
+export declare const isOnPageOrigin: (address: URL, page: URL) => boolean;
+/**
+ * A `fetch` of one render, its requests answered by the story's mocks. Make one per render: its `{ once: true }` handlers
+ * answer again from here.
+ *
+ * @param mocks - the story's mocks.
+ * @returns what sends a request; an address the mocks do not take goes to the global `fetch`.
+ */
+export declare const mockedFetch: (mocks: ServerMocks) => ((request: Request) => Promise<Response>);