forgebook 0.1.8 → 0.3.0

package/dist/src/shell/Shell.js

@@ -1,19 +1,23 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef, useState } from "react";
-import { catalogueSettings } from "../catalogue.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { addressArgsFor } from "../addressTexts.js";
+import { deviceDefaultOf, pageDeviceDefault } from "../deviceView.js";
 import { panelArgsParam, parsePanelArgsParam } from "../messages.js";
+import { anchorOf } from "../pageAddress.js";
+import { findPage } from "../pageTree.js";
 import { sourceFiles } from "../sourceFiles.js";
 import { storyBackground } from "../storyBackground.js";
 import { NOT_FIXED } from "../storyGlobals.js";
 import { knownHeight } from "../storyHeights.js";
-import { componentId, findComponent, findStory, isLogicComponent, sidebarStoryIds, storyTree } from "../storyTree.js";
-import { catalogueSwitches } from "../switches.js";
-import { usageLoader } from "../usedIn.js";
+import { componentId, findComponent, findComponentByTitle, findStory, isLogicComponent, sidebarStoryIds, storyTree } from "../storyTree.js";
 import { parseView, viewParams } from "../viewState.js";
-import { ComponentPage } from "./ComponentPage.js";
-import { CatalogueContext, useCatalogue } from "./catalogueContext.js";
-import { HomePage } from "./HomePage.js";
+import { CatalogueContext, NO_PLUGINS, useCatalogue, useConfiguredCatalogue } from "./catalogueContext.js";
+import { filesCodeLoader } from "./filesCode.js";
+import { Icon } from "./icons.js";
+import { LazyPage } from "./LazyPage.js";
 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 { Stage } from "./Stage.js";
@@ -28,12 +32,27 @@ import { useStoryHeights } from "./useStoryHeights.js";
 import { useStoryIdsElement } from "./useStoryIdsElement.js";
 import { useStoryKeys } from "./useStoryKeys.js";
 import { useSystemDark } from "./useSystemDark.js";
-/** No languages: a catalogue that offers none. */
-const NO_LANGUAGES = [];
+/** A docs page, loaded on first use: a catalogue may have none. */
+const DOC_PAGE = lazyModule(() => import("./DocPage.js").then((module) => module.DocPage));
+/** The home, loaded when it is opened. */
+const HOME_PAGE = lazyModule(() => import("./HomePage.js").then((module) => module.HomePage));
+/** A component's page, loaded when one is opened. */
+const COMPONENT_PAGE = lazyModule(() => import("./ComponentPage.js").then((module) => module.ComponentPage));
+/**
+ * The home: the catalogue's written one when it has one, the generated one otherwise, each loaded when first opened.
+ *
+ * @param props - the written home's module, if any, and each home's props.
+ */
+const ShellHome = ({ written, home, writtenProps }) => written === undefined ? (_jsx(LazyPage, { module: HOME_PAGE, header: home.header, pageProps: home })) : (_jsx(LazyPage, { module: written, header: home.header, pageProps: writtenProps }));
 /** The home. */
 const HOME = { kind: "home" };
 /** A page's key: the same for every view of it. */
-const pageKey = (page) => (page.kind === "home" ? page.kind : `${page.kind}:${page.id}`);
+const pageKey = (page) => {
+    if (page.kind === "home")
+        return page.kind;
+    // a heading is a place of its own in the history: Back from it returns to where the reader was
+    return page.kind === "story" ? `story:${page.id}` : `${page.kind}:${page.id}#${page.anchor ?? ""}`;
+};
 /**
  * A visit of the page an address shows.
  *
@@ -64,27 +83,38 @@ const drawnWidth = (width, fill) => (width === "fill" ? fill : width);
  * @param shownWidth - the width the stage measured for Fill; none before it measured.
  */
 const stageHeight = (heights, storyId, width, shownWidth) => knownHeight(heights, storyId, drawnWidth(width, shownWidth ?? FILL_WIDTH));
-/** The page of the address's `story` and `component` parameters: a story wins, none is the home. */
-const pageOf = (story, component) => {
+/**
+ * The page an address's query and fragment name: a story wins, then a component, then a docs page; none is the home.
+ *
+ * @param search - the address's query.
+ * @param hash - its fragment.
+ */
+const pageOf = (search, hash) => {
+    const params = new URLSearchParams(search);
+    const story = params.get("story");
+    const component = params.get("component");
+    const page = params.get("page");
     if (story !== null)
         return { kind: "story", id: story };
+    const anchor = anchorOf(hash.replace(/^#/, ""));
     if (component !== null)
-        return { kind: "component", id: component };
+        return { kind: "component", id: component, anchor };
+    if (page !== null)
+        return { kind: "page", id: page, anchor };
     return HOME;
 };
 /**
  * The current address.
  *
  * @param catalogue - the catalogue's switches and lists, for the view's values.
+ * @param addressTexts - how the framework's stories take the texts of the panel's values.
  */
-const readAddress = (catalogue) => {
+const readAddress = (catalogue, addressTexts) => {
     const params = new URLSearchParams(window.location.search);
-    const story = params.get("story");
-    const component = params.get("component");
     return {
-        page: pageOf(story, component),
+        page: pageOf(window.location.search, window.location.hash),
         view: parseView(window.location.search, catalogue),
-        panelArgs: parsePanelArgsParam(params.get("args")),
+        panelArgs: addressArgsFor(parsePanelArgsParam(params.get("args")), addressTexts),
         matrix: (params.get("matrix") ?? "").split(",").filter((name) => name !== "")
     };
 };
@@ -92,21 +122,27 @@ const readAddress = (catalogue) => {
  * The query of an address.
  *
  * @param address - the page, the view, the panel's values and the matrix's axes.
- * @param switches - the catalogue's switches, for the view's values.
+ * @param catalogue - the catalogue's switches and default audience, for the view's values.
  */
-const addressQuery = ({ page, view, panelArgs, matrix }, switches) => {
-    const params = viewParams(view, switches);
+const addressQuery = ({ page, view, panelArgs, matrix }, catalogue) => {
+    const params = viewParams(view, catalogue.switches, catalogue.audience);
     if (page.kind === "story")
         params.set("story", page.id);
     if (page.kind === "component")
         params.set("component", page.id);
+    if (page.kind === "page")
+        params.set("page", page.id);
     const args = page.kind === "story" ? panelArgsParam(panelArgs) : "";
     if (args !== "")
         params.set("args", args);
     if (page.kind === "story" && matrix.length > 0)
         params.set("matrix", matrix.join(","));
     const query = params.toString();
-    return query === "" ? window.location.pathname : `?${query}`;
+    // the fragment is part of what is written back on every change of the view, or a change would lose the heading
+    const fragment = (page.kind === "page" || page.kind === "component") && page.anchor !== undefined
+        ? `#${encodeURIComponent(page.anchor)}`
+        : "";
+    return `${query === "" ? window.location.pathname : `?${query}`}${fragment}`;
 };
 /** What the address's page shows: a story or a component that is not there (renamed, removed) says so, never another. */
 const shownPage = (tree, page) => {
@@ -120,7 +156,13 @@ const shownPage = (tree, page) => {
         const location = findComponent(tree, page.id);
         return location === undefined
             ? { kind: "missing", message: STRINGS.unknownComponent(page.id) }
-            : { kind: "component", location };
+            : { kind: "component", location, anchor: page.anchor };
+    }
+    if (page.kind === "page") {
+        const location = findPage(tree, page.id);
+        return location === undefined
+            ? { kind: "missing", message: STRINGS.unknownPage(page.id) }
+            : { kind: "page", location, anchor: page.anchor };
     }
     return { kind: "home" };
 };
@@ -129,9 +171,9 @@ const recentPageOf = (shown) => {
     if (shown.kind === "story")
         return { kind: "story", id: shown.location.story.id };
     if (shown.kind === "component") {
-        return { kind: "component", id: componentId(shown.location.source.id, shown.location.component.title) };
+        return { kind: "component", id: shown.location.component.id };
     }
-    return undefined;
+    return shown.kind === "page" ? { kind: "page", id: shown.location.page.id } : undefined;
 };
 /**
  * Whether the shown page is about logic: a story about logic, or a component whose stories all are.
@@ -143,10 +185,30 @@ const isLogicPage = (shown) => {
         return shown.location.story.isLogic;
     return shown.kind === "component" && isLogicComponent(shown.location.component);
 };
+/** The shown component's place, a story's too; none on any other page. */
+const componentLocationOf = (shown) => shown.kind === "story" || shown.kind === "component" ? shown.location : undefined;
+/** The shown docs page's place; none on any other page. */
+const pageLocationOf = (shown) => shown.kind === "page" ? shown.location : undefined;
+/** Whether nothing shown follows the view's switches: the home, or a docs page without a story. */
+const hasNoStories = (shown) => shown.kind === "home" || (shown.kind === "page" && shown.location.page.stories.length === 0);
 /** What the sidebar marks: the shown component and story; none on the home or a missing page. */
 const sidebarCurrent = (location, storyId) => location === undefined
     ? undefined
     : { sourceId: location.source.id, title: location.component.title, storyId };
+/**
+ * The page's default device for the toolbar: the shown story's, a component's stories' on its page (`pageDeviceDefault`),
+ * the catalogue's elsewhere.
+ *
+ * @param catalogueDevice - the catalogue's default.
+ * @param shown - the page shown.
+ */
+const deviceOfShown = (catalogueDevice, shown) => {
+    if (shown.kind === "story")
+        return deviceDefaultOf(catalogueDevice, shown.location.story.device);
+    if (shown.kind === "component")
+        return pageDeviceDefault(catalogueDevice, shown.location.component.stories.map((story) => story.device));
+    return catalogueDevice;
+};
 /**
  * What the shown story fixes of the view, for the toolbar; nothing on any other page.
  *
@@ -161,10 +223,52 @@ 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 }));
-/** A component's page, by its title. */
-const componentPage = (sourceId, title) => ({
+/**
+ * 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.
+ *
+ * @param files - the source's files; none without a source.
+ * @param component - the component.
+ */
+const componentLoaders = (files, component) => ({
+    loadDocs: files?.docs[component.file],
+    loadCode: files === undefined ? undefined : filesCodeLoader(files.code, component.files),
+    loadPage: files?.pages[component.file]
+});
+/**
+ * What a story's page loads: its own file's code, and the docs of the component its file's meta names, which its
+ * controls are for.
+ *
+ * @param files - the source's files; none without a source.
+ * @param story - the story.
+ */
+const storyLoaders = (files, story) => ({
+    loadDocs: files?.docs[story.file],
+    loadCode: files?.code[story.file]
+});
+/** A component's page. */
+const componentPage = (component) => ({ kind: "component", id: component.id });
+/**
+ * Each component's id by its source and title, made once per tree: the sidebar names a component by its title, for
+ * every component on every render.
+ *
+ * @param tree - the tree.
+ */
+const componentIdsByTitle = (tree) => new Map(tree.sources.flatMap((source) => source.families.flatMap((family) => family.groups.flatMap((group) => group.components.map((component) => [
+    `${source.id}\n${component.title}`,
+    component.id
+])))));
+/**
+ * The page of a source's component with a title, as the sidebar names a component and an alias its place; a title no
+ * component has gives the id it would have, which the page reports as missing.
+ *
+ * @param idsByTitle - the components' ids by source and title (`componentIdsByTitle`).
+ * @param sourceId - the source's id.
+ * @param title - the component's title.
+ */
+const titledPage = (idsByTitle, sourceId, title) => ({
     kind: "component",
-    id: componentId(sourceId, title)
+    id: idsByTitle.get(`${sourceId}\n${title}`) ?? componentId(sourceId, title)
 });
 /**
  * What "Used in" reads and opens on a source's component pages: its usage, its components by title, and their pages;
@@ -178,10 +282,10 @@ const componentPage = (sourceId, title) => ({
 const usedInLinks = (source, isOffered, tree, pages) => source === undefined || !isOffered
     ? undefined
     : {
-        load: usageLoader(source),
-        componentOf: (title) => findComponent(tree, componentId(source.id, title))?.component,
-        componentHrefOf: (component) => pages.hrefOf(componentPage(source.id, component.title)),
-        onOpenComponent: (component) => pages.onOpen(componentPage(source.id, component.title)),
+        source,
+        componentOf: (title) => findComponentByTitle(tree, source.id, title)?.component,
+        componentHrefOf: (component) => pages.hrefOf(componentPage(component)),
+        onOpenComponent: (component) => pages.onOpen(componentPage(component)),
         storyHrefOf: (story) => pages.hrefOf(storyPage(story)),
         onOpenStory: (story) => pages.onOpen(storyPage(story))
     };
@@ -194,10 +298,8 @@ const usedInLinks = (source, isOffered, tree, pages) => source === undefined ||
 const relatedComponents = (tree, location) => (location?.component.related ?? []).flatMap((title) => {
     if (location === undefined)
         return [];
-    const found = findComponent(tree, componentId(location.source.id, title));
-    return found === undefined
-        ? []
-        : [{ page: componentPage(location.source.id, title), name: found.component.name }];
+    const found = findComponentByTitle(tree, location.source.id, title);
+    return found === undefined ? [] : [{ page: componentPage(found.component), name: found.component.name }];
 });
 /**
  * The links to the related components, at the top of the page; nothing when there are none.
@@ -211,7 +313,8 @@ const RelatedLinks = ({ related, hrefOf, onOpen }) => related.length === 0 ? nul
                 onOpen(component.page);
             }, children: component.name }, component.name)))] }));
 /**
- * What scrolls above a page: the index's problems, and the component's place and name, or why nothing is shown.
+ * What scrolls above a page: the index's problems, and the component's or the docs page's place and name, or why
+ * nothing is shown.
  *
  * @remarks
  * The place is always where the component lives, with the other places it is listed in, so a page opened from an
@@ -220,25 +323,39 @@ const RelatedLinks = ({ related, hrefOf, onOpen }) => related.length === 0 ? nul
  * @param props - the problems, the shown component's place, the message when a named page is missing, the picker
  * of the component's stories, and the related components.
  */
-const ShellHeader = ({ problems, location, message, picker, related, isLogic }) => (_jsxs(_Fragment, { children: [problems.length > 0 ? (_jsxs("div", { className: "forgebook-problems", role: "alert", children: [_jsx("strong", { children: STRINGS.indexProblems }), _jsx("ul", { children: problems.map((problem) => (_jsx("li", { children: problem }, problem))) })] })) : null, message === undefined ? null : (_jsx("p", { className: "forgebook-empty", role: "alert", children: message })), location === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsxs("p", { className: "forgebook-header__path", children: [[location.source.name, location.family.name, location.group.name]
+const ShellHeader = ({ problems, location, page, message, picker, related, isLogic }) => (_jsxs(_Fragment, { children: [problems.length > 0 ? (_jsxs("div", { className: "forgebook-problems", role: "alert", children: [_jsx("strong", { children: STRINGS.indexProblems }), _jsx("ul", { children: problems.map((problem) => (_jsx("li", { children: problem }, problem))) })] })) : null, message === undefined ? null : (_jsx("p", { className: "forgebook-empty", role: "alert", children: message })), location === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsxs("p", { className: "forgebook-header__path", children: [[location.source.name, location.family.name, location.group.name]
                             .filter((part) => part !== undefined)
-                            .join(" · "), location.component.alsoIn.length === 0 ? null : (_jsxs("span", { className: "forgebook-header__also-in", children: [" · ", STRINGS.alsoIn(location.component.alsoIn.map((place) => place.split("/").join(" › ")).join(", "))] }))] }), _jsxs("div", { className: "forgebook-header__row", children: [_jsx("h1", { className: "forgebook-header__title", children: location.component.name }), isLogic ? _jsx(LogicMark, {}) : null, picker] }), related] }))] }));
+                            .join(" · "), location.component.alsoIn.length === 0 ? null : (_jsxs("span", { className: "forgebook-header__also-in", children: [" · ", STRINGS.alsoIn(location.component.alsoIn.map((place) => place.split("/").join(" › ")).join(", "))] }))] }), _jsxs("div", { className: "forgebook-header__row", children: [_jsx("h1", { className: "forgebook-header__title", children: location.component.name }), isLogic ? _jsx(LogicMark, {}) : null, picker, location.component.design === undefined ? null : (_jsxs("a", { className: "forgebook-button", href: location.component.design.url, target: "_blank", rel: "noopener noreferrer", children: [_jsx(Icon, { name: "external", size: 14 }), STRINGS.openInFigma] }))] }), related] })), page === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsx("p", { className: "forgebook-header__path", children: [page.source.name, page.page.group].filter((part) => part !== undefined).join(" · ") }), _jsx("div", { className: "forgebook-header__row", children: _jsx("h1", { className: "forgebook-header__title", children: page.page.name }) })] }))] }));
 /** A story's page. */
 const storyPage = (story) => ({ kind: "story", id: story.id });
+/**
+ * Opens the page an address of the catalogue names, written in a docs page's text.
+ *
+ * @param href - the address.
+ * @param openPage - opens a page.
+ * @returns whether it names one.
+ */
+const openLinkedPage = (href, openPage) => {
+    const { search, hash } = new URL(href, window.location.href);
+    const page = pageOf(search, hash);
+    if (page.kind === "home")
+        return false;
+    openPage(page);
+    return true;
+};
 /** The address, read again when the history goes back or forth. */
-const useAddress = (catalogue) => {
-    const { switches } = catalogue;
-    const [address, setAddress] = useState(() => readAddress(catalogue));
+const useAddress = (catalogue, addressTexts) => {
+    const [address, setAddress] = useState(() => readAddress(catalogue, addressTexts));
     const [visit, setVisit] = useState(() => visitOf(address, false));
     useEffect(() => {
         const onBack = () => {
-            const next = readAddress(catalogue);
+            const next = readAddress(catalogue, addressTexts);
             setAddress(next);
             setVisit(visitOf(next, true));
         };
         window.addEventListener("popstate", onBack);
         return () => window.removeEventListener("popstate", onBack);
-    }, [catalogue]);
+    }, [catalogue, addressTexts]);
     // a height set with the foot handle belongs to the story it was set on: another page starts at its own
     const pageAddress = (page) => ({
         page,
@@ -246,34 +363,62 @@ const useAddress = (catalogue) => {
         panelArgs: {},
         matrix: []
     });
+    const open = (page, movesFocus) => {
+        const next = pageAddress(page);
+        window.history.pushState(null, "", addressQuery(next, catalogue));
+        setAddress(next);
+        setVisit({ ...visitOf(next, false), movesFocus });
+    };
     return {
         address,
         visit,
         pageAddress,
-        openPage: (page) => {
-            const next = pageAddress(page);
-            window.history.pushState(null, "", addressQuery(next, switches));
+        openPage: (page) => open(page, false),
+        openFound: (page) => open(page, true),
+        openAnchor: (anchor) => {
+            if (address.page.kind !== "page")
+                return;
+            const next = { ...address, page: { ...address.page, anchor } };
+            window.history.pushState(null, "", addressQuery(next, catalogue));
             setAddress(next);
-            setVisit(visitOf(next, false));
+            setVisit({ ...visitOf(next, false), isInPage: true });
         },
         replaceAddress: (next) => {
-            window.history.replaceState(null, "", addressQuery(next, switches));
+            window.history.replaceState(null, "", addressQuery(next, catalogue));
             setAddress(next);
         }
     };
 };
+/**
+ * Writes the shown page's own id into the address when the address named it by a former id (`formerStoryId`), as a
+ * redirect would: a link written then keeps opening its page, and the address then shown is the page's own.
+ *
+ * @param address - the address.
+ * @param ownPage - the shown page by its own id; none on the home or a missing page.
+ * @param replaceAddress - changes the address in place.
+ */
+const useOwnPageId = (address, ownPage, replaceAddress) => {
+    useEffect(() => {
+        if (ownPage === undefined || address.page.kind === "home" || ownPage.id === address.page.id)
+            return;
+        replaceAddress({ ...address, page: { ...address.page, id: ownPage.id } });
+    }, [address, ownPage, replaceAddress]);
+};
 /**
  * The catalogue's page inside its settings: everything below reads them, the shell's own hooks (the sidebar's width,
  * the keys, the recent pages) included.
  *
  * @param props - the configuration.
  */
-const ShellPage = ({ title, logo, heights, sources, frameUrl }) => {
+const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addressTexts = "any", plugins = NO_PLUGINS, loadTokens, home }) => {
     const tree = useMemo(() => storyTree(sources), [sources]);
+    // 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 { switches } = catalogue;
-    const { address, visit, pageAddress, openPage, replaceAddress } = useAddress(catalogue);
+    const { address, visit, pageAddress, openPage, openFound, openAnchor, replaceAddress } = useAddress(catalogue, addressTexts);
     // 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 };
@@ -286,34 +431,95 @@ const ShellPage = ({ title, logo, heights, sources, frameUrl }) => {
     const [touchOverrides, setTouchOverrides] = useState(new Map());
     const setTouchOverride = (storyId, isTouch) => setTouchOverrides((current) => new Map(current).set(storyId, isTouch));
     const isSystemDark = useSystemDark();
-    const appearance = useAppearance();
+    const appearance = useAppearance(address.view, catalogue.switches);
     useStoryIdsElement(useMemo(() => sidebarStoryIds(tree, catalogue.storyGroups.map((group) => group.id)), [tree, catalogue.storyGroups]));
     const shown = shownPage(tree, address.page);
-    const location = shown.kind === "story" || shown.kind === "component" ? shown.location : undefined;
-    const recent = useRecentPages(recentPageOf(shown));
+    const location = componentLocationOf(shown);
+    const ownPage = recentPageOf(shown);
+    const recent = useRecentPages(ownPage);
+    useOwnPageId(address, ownPage, replaceAddress);
+    const shownPageLocation = pageLocationOf(shown);
+    const pageName = shownPageLocation?.page.name ?? location?.component.name;
     useEffect(() => {
-        document.title = location === undefined ? title : `${location.component.name} · ${title}`;
-    }, [location, title]);
+        document.title = pageName === undefined ? title : `${pageName} · ${title}`;
+    }, [pageName, title]);
     const changeView = (view) => replaceAddress({ ...address, view });
-    const shownStoryId = shown.kind === "story" ? shown.location.story.id : undefined;
     // a story marked for a phone has its own Touch on its page, and a story about logic is never compared
     const shownStory = shown.kind === "story" ? shown.location.story : undefined;
+    const shownStoryId = shownStory?.id;
     const { view: shownView, onViewChange: changeShownView } = useShownView({
         addressView: address.view,
         story: shownStory,
         touchOverrides,
         onTouchChange: setTouchOverride,
         touch: catalogue.touch,
+        catalogueDevice: catalogue.device,
         onAddressViewChange: changeView
     });
     useStoryKeys(tree, shownStoryId, shown.kind === "component" ? shown.location.component.stories[0]?.id : undefined, (id) => openPage({ kind: "story", id }));
     const source = sources.find((candidate) => candidate.id === location?.source.id);
     const files = source === undefined ? undefined : sourceFiles(source);
-    const header = (_jsx(ShellHeader, { problems: tree.problems, location: location, isLogic: isLogicPage(shown), message: shown.kind === "missing" ? shown.message : undefined, picker: location === undefined ? null : (_jsx(StoryPicker, { component: location.component, currentStoryId: shownStoryId, onOpenComponent: () => openPage(componentPage(location.source.id, location.component.title)), onOpenStory: (story) => openPage(storyPage(story)) })), related: _jsx(RelatedLinks, { related: relatedComponents(tree, location), hrefOf: (page) => addressQuery(pageAddress(page), switches), onOpen: openPage }) }));
-    return (_jsxs("div", { className: "catalogue", children: [_jsx(Sidebar, { width: sidebarWidth, isOpen: isSidebarOpen, onHide: () => setIsSidebarOpen(false), appearance: appearance, title: title, logo: logo, tree: tree, isHome: shown.kind === "home", homeHref: addressQuery(pageAddress(HOME), switches), onOpenHome: () => openPage(HOME), current: sidebarCurrent(location, shownStoryId), componentHref: (sourceId, componentTitle) => addressQuery(pageAddress(componentPage(sourceId, componentTitle)), switches), onOpenComponent: (sourceId, componentTitle) => openPage(componentPage(sourceId, componentTitle)) }), isSidebarOpen ? _jsx(SidebarHandle, { width: sidebarWidth, onWidthChange: setSidebarWidth }) : null, _jsxs("main", { className: "forgebook-main", children: [_jsx(ShellBar, { isHome: shown.kind === "home", view: shownView, onViewChange: changeShownView, isStoryPage: shown.kind === "story", isLogic: isLogicPage(shown), onShowSidebar: isSidebarOpen ? undefined : () => setIsSidebarOpen(true), shownWidth: shown.kind === "story" ? shownWidth : undefined, fixed: fixedOfShown(fixedViews, shown) }), shown.kind === "home" ? (_jsx(HomePage, { title: title, tree: tree, sources: sources, recent: recent, hrefOf: (page) => addressQuery(pageAddress(page), switches), onOpen: (page) => openPage(page), header: header })) : null, shown.kind === "component" ? (_jsx(ComponentPage, { component: shown.location.component, view: address.view, touchOverrides: touchOverrides, onTouchChange: setTouchOverride, frameUrl: frameUrl, hrefOf: (story) => addressQuery(pageAddress(storyPage(story)), switches), onOpen: (story) => openPage(storyPage(story)), loadDocs: files?.docs[shown.location.component.file], loadCode: files?.code[shown.location.component.file], loadPage: files?.pages[shown.location.component.file], background: storyBackground(shown.location.source.background, address.view, catalogue, isSystemDark), heightOf: (storyId) => knownHeight(storyHeights, storyId, drawnWidth(address.view.width, PAGE_COLUMN_WIDTH)), header: header, scroll: scroll, usedIn: usedInLinks(source, catalogue.hasUsedIn, tree, {
-                            hrefOf: (page) => addressQuery(pageAddress(page), switches),
-                            onOpen: openPage
-                        }) })) : null, shown.kind === "story" ? (_jsx(Stage, { component: shown.location.component, story: shown.location.story, view: shownView, onViewChange: changeShownView, onFixedChange: (storyId, fixed) => setFixedViews((current) => new Map(current).set(storyId, fixed)), panelArgs: address.panelArgs, onPanelArgsChange: (panelArgs) => replaceAddress({ ...address, panelArgs }), matrixAxes: address.matrix, onMatrixAxesChange: (matrix) => replaceAddress({ ...address, matrix }), frameUrl: frameUrl, loadCode: files?.code[shown.location.component.file], loadDocs: files?.docs[shown.location.component.file], namedValues: source?.namedValues, header: header, onShownWidthChange: setShownWidth, scroll: scroll, backgroundOf: (view) => storyBackground(shown.location.source.background, view, catalogue, isSystemDark), measuredHeight: stageHeight(storyHeights, shown.location.story.id, address.view.width, shownWidth) })) : null, shown.kind === "missing" ? header : null] })] }));
+    const storyHrefOf = (story) => addressQuery(pageAddress(storyPage(story)), catalogue);
+    const columnHeightOf = (storyId) => knownHeight(storyHeights, storyId, drawnWidth(address.view.width, PAGE_COLUMN_WIDTH));
+    const header = (_jsx(ShellHeader, { problems: tree.problems, location: location, page: shownPageLocation, isLogic: isLogicPage(shown), message: shown.kind === "missing" ? shown.message : undefined, picker: location === undefined ? null : (_jsx(StoryPicker, { component: location.component, currentStoryId: shownStoryId, onOpenComponent: () => openPage(componentPage(location.component)), onOpenStory: (story) => openPage(storyPage(story)) })), related: _jsx(RelatedLinks, { related: relatedComponents(tree, location), hrefOf: (page) => addressQuery(pageAddress(page), catalogue), onOpen: openPage }) }));
+    const homeProps = {
+        title,
+        tree,
+        sources,
+        recent,
+        hrefOf: (page) => addressQuery(pageAddress(page), catalogue),
+        onOpen: (page) => openPage(page),
+        header
+    };
+    const docProps = {
+        title,
+        plugins,
+        tree,
+        sources,
+        view: address.view,
+        touchOverrides,
+        onTouchChange: setTouchOverride,
+        frameUrl,
+        storyHrefOf,
+        onOpenStory: (story) => openPage(storyPage(story)),
+        pageHrefOf: (id, anchor) => addressQuery(pageAddress({ kind: "page", id, anchor }), catalogue),
+        onOpenAddress: (href) => openLinkedPage(href, openPage),
+        heightOf: columnHeightOf,
+        backgroundOf: (pageSource) => storyBackground(pageSource.background, address.view, catalogue, isSystemDark),
+        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: {
+                            component: shown.location.component,
+                            anchor: shown.anchor,
+                            view: address.view,
+                            touchOverrides,
+                            onTouchChange: setTouchOverride,
+                            frameUrl,
+                            hrefOf: storyHrefOf,
+                            onOpen: (story) => openPage(storyPage(story)),
+                            ...componentLoaders(files, shown.location.component),
+                            background: storyBackground(shown.location.source.background, address.view, catalogue, isSystemDark),
+                            heightOf: columnHeightOf,
+                            header,
+                            scroll,
+                            usedIn: usedInLinks(source, catalogue.hasUsedIn, tree, {
+                                hrefOf: (page) => addressQuery(pageAddress(page), catalogue),
+                                onOpen: openPage
+                            }),
+                            onViewChange: changeView,
+                            tree,
+                            componentId: shown.location.component.id,
+                            pageHrefOf: (id) => addressQuery(pageAddress({ kind: "page", id }), catalogue),
+                            onOpenPage: (id) => openPage({ kind: "page", id }),
+                            loadTokens
+                        } })) : null, shown.kind === "home" ? (_jsx(ShellHome, { written: writtenHome, home: homeProps, writtenProps: { ...homeProps, ...docProps } })) : null, shown.kind === "page" ? (_jsx(LazyPage, { module: DOC_PAGE, header: header, pageProps: {
+                            ...docProps,
+                            location: shown.location,
+                            anchor: shown.anchor,
+                            onOpenPage: (id) => openPage({ kind: "page", id }),
+                            onOpenAnchor: openAnchor
+                        } }, shown.location.page.id)) : null, shown.kind === "story" ? (_jsx(Stage, { component: shown.location.component, story: shown.location.story, view: shownView, onViewChange: changeShownView, onFixedChange: (storyId, fixed) => setFixedViews((current) => new Map(current).set(storyId, fixed)), panelArgs: address.panelArgs, onPanelArgsChange: (panelArgs) => replaceAddress({ ...address, panelArgs }), matrixAxes: address.matrix, onMatrixAxesChange: (matrix) => replaceAddress({ ...address, matrix }), frameUrl: frameUrl, plugins: plugins, ...storyLoaders(files, shown.location.story), namedValues: source?.namedValues, header: header, onShownWidthChange: setShownWidth, scroll: scroll, backgroundOf: (view) => storyBackground(shown.location.source.background, view, catalogue, isSystemDark), measuredHeight: stageHeight(storyHeights, shown.location.story.id, address.view.width, shownWidth) })) : null, shown.kind === "missing" ? header : null] })] }));
 };
 /**
  * The catalogue's page: its settings computed once from the configuration (its switches, its languages' switch, its
@@ -321,9 +527,4 @@ const ShellPage = ({ title, logo, heights, sources, frameUrl }) => {
  *
  * @param props - the configuration.
  */
-export const Shell = (props) => {
-    const { title, switches, languages = NO_LANGUAGES, lists } = props;
-    const catalogue = useMemo(() => catalogueSettings(title, catalogueSwitches(switches, languages, lists?.controls), lists), [title, switches, languages, lists]);
-    return (_jsx(CatalogueContext.Provider, { value: catalogue, children: _jsx(ShellPage, { ...props }) }));
-};
-//# sourceMappingURL=Shell.js.map
+export const Shell = (props) => (_jsx(CatalogueContext.Provider, { value: useConfiguredCatalogue(props), children: _jsx(PluginHostsContext.Provider, { value: props.pluginHosts, children: _jsx(ShellPage, { ...props }) }) }));

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

@@ -5,22 +5,34 @@
  * the pointer. A family or a group stays open once opened; a search opens every one it finds something in, and finds a
  * component by its
  * name, its place, its meta's search words or its stories' names and descriptions. A component listed in other places too (`alsoIn`) has an
- * alias entry in each, beside the components that live there, which says where it lives and opens its page.
+ * alias entry in each, beside the components that live there, which says where it lives and opens its page. Docs pages
+ * come first, in a section of their own (`SidebarDocs.tsx`).
  *
  * @module
  */
+import type { StorySource } from "@forgebook/story-format/source";
 import { type ReactNode } from "react";
+import type { SearchTarget } from "../search.ts";
 import type { StoryTree } from "../storyTree.ts";
+import { type SidebarPageLinks } from "./SidebarDocs.tsx";
 import { type ShownComponent } from "./SidebarEntries.tsx";
 import type { AppearanceState } from "./useAppearance.ts";
 /** The sidebar's props. */
-export type SidebarProps = {
+export type SidebarProps = SidebarPageLinks & {
     /** The catalogue's name. */
     readonly title: string;
-    /** The catalogue's logo, the URL of a square image; none shows the catalogue's own mark. */
+    /** The catalogue's logo, the URL of a square image; none shows Forgebook's mark, or the name alone without branding. */
     readonly logo: string | undefined;
+    /** Whether a catalogue without a logo shows Forgebook's mark. */
+    readonly hasBranding: boolean;
     /** The tree. */
     readonly tree: StoryTree;
+    /** The sources, for the search's index. */
+    readonly sources: readonly StorySource[];
+    /** The address of a search's result. */
+    readonly searchHref: (target: SearchTarget) => string;
+    /** Goes to a search's result. */
+    readonly onOpenResult: (target: SearchTarget) => void;
     /** Whether the home is shown: the logo, its link, is then the current page. */
     readonly isHome: boolean;
     /** The home's address, for the logo's link. */
@@ -32,6 +44,8 @@ export type SidebarProps = {
      * home.
      */
     readonly current: ShownComponent | undefined;
+    /** The shown docs page's id; none on any other page. */
+    readonly currentPageId: string | undefined;
     /** The address of a component's page, by its title, for its link. */
     readonly componentHref: (sourceId: string, title: string) => string;
     /** Opens a component's page, by its title. */
@@ -42,6 +56,8 @@ export type SidebarProps = {
     readonly isOpen: boolean;
     /** Hides the sidebar. */
     readonly onHide: () => void;
+    /** Shows it again. */
+    readonly onShow: () => void;
     /** The shell's appearance and its setter, for the menu at the foot. */
     readonly appearance: AppearanceState;
 };
@@ -50,5 +66,4 @@ export type SidebarProps = {
  *
  * @param props - the tree, the shown component and how to open one.
  */
-export declare const Sidebar: ({ title, logo, tree, isHome, homeHref, onOpenHome, current, width, isOpen, onHide, appearance, ...links }: SidebarProps) => ReactNode;
-//# sourceMappingURL=Sidebar.d.ts.map
+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;