forgebook 0.1.7 → 0.2.0

package/dist/src/shell/CompareGrid.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { frameAddress, schemeOf } from "../viewState.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { compareVariants } from "./compareVariants.js";
+import { DeviceSlot, deviceAddress, inkScheme } from "./DeviceSlot.js";
+import { FrameView } from "./FrameView.js";
+import { useSystemDark } from "./useSystemDark.js";
+/**
+ * The compare view's cells.
+ *
+ * @param props - the story, the view, the device and the frames' reports.
+ */
+export const CompareGrid = ({ story, title, view, frameUrl, framed, heights, settled, fallbackHeight, backgroundOf }) => {
+    const catalogue = useCatalogue();
+    const { switches } = catalogue;
+    const isSystemDark = useSystemDark();
+    return (_jsx("div", { className: "forgebook-compare", ...framed?.parts.compareGridProps(framed.drawing), children: compareVariants(view.compare, catalogue).map((variant) => {
+            const cellView = variant.viewOf(view);
+            // the label (the shell's text) reads on the page's colour, or on the shell's around a device, whose screen
+            // has it; the frame draws the backdrop
+            const background = backgroundOf({ ...cellView, backdrop: "plain" });
+            return (_jsxs("figure", { className: "forgebook-compare__cell", style: { backgroundColor: framed === undefined ? background : undefined }, children: [_jsx("figcaption", { className: "forgebook-compare__label", children: variant.label }), _jsx(DeviceSlot, { framed: framed, scheme: inkScheme(schemeOf(cellView, switches), isSystemDark), background: background, children: _jsx(FrameView, { title: `${title} · ${variant.label}`, address: deviceAddress(frameAddress(frameUrl, story.id, cellView, switches), framed), heights: heights, settled: settled, fallbackHeight: fallbackHeight, sceneHeight: story.height, fixedHeight: framed?.area.height }) })] }, variant.label));
+        }) }));
+};

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

@@ -4,23 +4,30 @@
  * example.
  *
  * @remarks
- * The demo loads at once; the examples load as they come near the visible part of the page, a few at a time
- * (`useFrameQueue`): a component may have twenty stories. The view's live part reaches every frame as a message, as
+ * The frames load a few at a time (`useFrameQueue`), in the page's order, the demo first, each as it comes near the
+ * visible part of the page: a component may have twenty stories. The view's live part reaches every frame as a message, as
  * on the story page; the props panel and Replay belong to a story's own page, which each story's name links to. The
- * documentation file's HTML is the package's own, made at build time (`vite/componentPage.ts`).
+ * documentation file's HTML is the package's own, made at build time (`vite/componentPage.ts`). Who reads the page
+ * reorders and filters what goes around the frames (`audienceLayout.ts`); what only one audience wants loads on first use,
+ * its data alongside the sections' code rather than after it.
  *
  * @module
  */
 import { type ReactNode } from "react";
-import { type TreeComponent, type TreeStory } from "../storyTree.ts";
+import { type ComponentDocs } from "../componentDocs.ts";
+import { type StoryTree, type TreeComponent, type TreeStory } from "../storyTree.ts";
 import { type ViewState } from "../viewState.ts";
-import { type TouchOverrides } from "./storyTouch.ts";
+import type { TouchOverrides } from "./storyTouch.ts";
 import { type UsedInProps } from "./UsedIn.tsx";
+import type { Loaded } from "./useLoaded.ts";
+import { type PageDoc } from "./usePageDoc.ts";
 import { type PageScroll } from "./useScrollMemory.ts";
 /** The component page's props. */
 export type ComponentPageProps = {
     /** The component. */
     readonly component: TreeComponent;
+    /** The heading or the prop the address names; none when it names none. */
+    readonly anchor: string | undefined;
     /** The view. */
     readonly view: ViewState;
     /** What the user chose for each story marked for a phone. */
@@ -49,11 +56,42 @@ export type ComponentPageProps = {
     readonly scroll: PageScroll;
     /** What "Used in" reads and opens; none when the catalogue turned it off. */
     readonly usedIn?: Omit<UsedInProps, "title"> | undefined;
+    /** Called with the changed view: the page's note goes back to the whole page. */
+    readonly onViewChange: (view: ViewState) => void;
+    /** The tree, where a designer's page finds the docs pages that show the component. */
+    readonly tree: StoryTree;
+    /** The component's id in the tree. */
+    readonly componentId: string;
+    /** The address of a docs page. */
+    readonly pageHrefOf: (id: string) => string;
+    /** Opens a docs page. */
+    readonly onOpenPage: (id: string) => void;
+    /** Loads the catalogue's design tokens, for a designer; `undefined` when it has none. */
+    readonly loadTokens: (() => Promise<unknown>) | undefined;
 };
+/**
+ * The page's lead: what the component is and does, from its file's `@module` comment (its own TSDoc is often a bare
+ * name), read with the documentation file so it comes with the page; else its TSDoc summary, once the docs come.
+ *
+ * @param props - the loaded page and the component's docs.
+ */
+export declare const Lead: ({ page, docs }: {
+    readonly page: Loaded<PageDoc>;
+    readonly docs: ComponentDocs | undefined;
+}) => ReactNode;
+/**
+ * The API reference; nothing without props, or a signature for what is about logic.
+ *
+ * @param props - the component's docs, whether it is about logic, and the prop groups its meta lists first.
+ */
+export declare const PageApi: ({ docs, isLogic, componentGroups }: {
+    readonly docs: ComponentDocs | undefined;
+    readonly isLogic: boolean;
+    readonly componentGroups: readonly string[];
+}) => ReactNode;
 /**
  * A component's page.
  *
  * @param props - the component, the view, its loaders and how to open a story.
  */
-export declare const ComponentPage: ({ component, view, touchOverrides, onTouchChange, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, header, scroll, usedIn }: ComponentPageProps) => ReactNode;
-//# sourceMappingURL=ComponentPage.d.ts.map
+export declare const ComponentPage: ({ component, anchor, view, touchOverrides, onTouchChange, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, header, scroll, usedIn, onViewChange, tree, componentId, pageHrefOf, onOpenPage, loadTokens }: ComponentPageProps) => ReactNode;

package/dist/src/shell/ComponentPage.js

@@ -5,39 +5,69 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * example.
  *
  * @remarks
- * The demo loads at once; the examples load as they come near the visible part of the page, a few at a time
- * (`useFrameQueue`): a component may have twenty stories. The view's live part reaches every frame as a message, as
+ * The frames load a few at a time (`useFrameQueue`), in the page's order, the demo first, each as it comes near the
+ * visible part of the page: a component may have twenty stories. The view's live part reaches every frame as a message, as
  * on the story page; the props panel and Replay belong to a story's own page, which each story's name links to. The
- * documentation file's HTML is the package's own, made at build time (`vite/componentPage.ts`).
+ * documentation file's HTML is the package's own, made at build time (`vite/componentPage.ts`). Who reads the page
+ * reorders and filters what goes around the frames (`audienceLayout.ts`); what only one audience wants loads on first use,
+ * its data alongside the sections' code rather than after it.
  *
  * @module
  */
-import { useMemo, useRef, useState } from "react";
+import { lazy, Suspense, useEffect, useMemo, useRef } from "react";
 import { groupLabel } from "../catalogue.js";
-import { groupedStories, mainStory } from "../storyTree.js";
-import { liveView } from "../viewState.js";
+import { codeNameOf } from "../componentDocs.js";
+import { groupedStories, isLogicComponent, mainStory } from "../storyTree.js";
+import { usageLoader } from "../usedIn.js";
+import { viewParams } from "../viewState.js";
 import { ApiReference } from "./ApiReference.js";
+import { showsSection } from "./audienceLayout.js";
 import { CodeText } from "./CodeText.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { Example } from "./Example.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
 import { PackageHtml } from "./PackageHtml.js";
-import { storyTouchesOf, touchedView } from "./storyTouch.js";
-import { STRINGS } from "./strings.js";
 import { UsedIn } from "./UsedIn.js";
 import { useComponentDocs } from "./useComponentDocs.js";
-import { useFrameMessages } from "./useFrameMessages.js";
-import { useFrameQueue } from "./useFrameQueue.js";
-import { useLiveView, useLoadedView } from "./useLiveView.js";
 import { usePageDoc } from "./usePageDoc.js";
+import { usePageFrames } from "./usePageFrames.js";
 import { useScrollMemory } from "./useScrollMemory.js";
 import { useStoryCode } from "./useStoryCode.js";
+/** What opens the page at an anchor, loaded with the first one: most pages open at their top. */
+const AnchorScroll = lazy(() => import("./AnchorScroll.js").then((module) => ({ default: module.AnchorScroll }), 
+// a chunk gone after a new deployment costs the place on the page, never the page
+() => ({ default: () => null })));
+/** What a page drawn for one audience adds around its frames, loaded the first time a page is drawn for one. */
+const AUDIENCE_SECTIONS = lazyModule(() => import("./AudienceSections.js").then((module) => module.AudienceSections));
+/**
+ * Starts loading what an audience's sections read (the design tokens, "Used in") as soon as the page is drawn for it.
+ * Asked by the sections themselves, these loads would wait for the sections' chunk and its styles first: seconds on a
+ * dev server's first visit, before a request that may itself take seconds. The loaders keep their answer, so the
+ * sections read it at once when they come.
+ *
+ * @param audience - who the page is drawn for.
+ * @param loadTokens - the catalogue's tokens loader; `undefined` when it has none.
+ * @param loadUsage - "Used in"'s loader; `undefined` when the catalogue turned it off.
+ */
+const useAudienceLoads = (audience, loadTokens, loadUsage) => {
+    useEffect(() => {
+        const loads = [
+            showsSection(audience, "tokens") ? loadTokens?.() : undefined,
+            showsSection(audience, "usedIn") ? loadUsage?.() : undefined
+        ];
+        // a failed load is its section's to report, when it asks the same loader
+        for (const load of loads)
+            void load?.catch(() => undefined);
+    }, [audience, loadTokens, loadUsage]);
+};
 /**
  * The page's lead: what the component is and does, from its file's `@module` comment (its own TSDoc is often a bare
  * name), read with the documentation file so it comes with the page; else its TSDoc summary, once the docs come.
  *
  * @param props - the loaded page and the component's docs.
  */
-const Lead = ({ page, docs }) => {
+export const Lead = ({ page, docs }) => {
     const summary = page.status === "ready" ? page.value.summary : "";
     const lead = summary || docs?.summary || docs?.description || "";
     return lead === "" ? null : (_jsx("p", { className: "forgebook-doc__lead", children: _jsx(CodeText, { text: lead }) }));
@@ -49,71 +79,99 @@ const Lead = ({ page, docs }) => {
  */
 const Prose = ({ page }) => {
     if (page.status === "error") {
-        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [STRINGS.pageError, ": ", page.message] }));
+        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [LATER_STRINGS.pageError, ": ", page.message] }));
     }
     if (page.status !== "ready" || page.value.html === "")
         return null;
     return _jsx(PackageHtml, { className: "forgebook-prose", html: page.value.html });
 };
+/**
+ * One place around the frames: the page's own sections, or an audience's in their place. Always one element, so the
+ * frames after it keep their place and never load again.
+ *
+ * @param props - the place, the audience's props (none for everyone) and the page's own sections.
+ */
+const AudienceSlot = ({ place, audience, children }) => audience === undefined ? (children) : (_jsx(LazyView, { module: AUDIENCE_SECTIONS, props: { place, ...audience }, loading: null, failed: (message) => (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [LATER_STRINGS.audienceError, ": ", message] })) }));
+/**
+ * The API reference; nothing without props, or a signature for what is about logic.
+ *
+ * @param props - the component's docs, whether it is about logic, and the prop groups its meta lists first.
+ */
+export const PageApi = ({ docs, isLogic, componentGroups }) => docs === undefined || (docs.props.length === 0 && !(isLogic && docs.signature !== undefined)) ? null : (_jsx(ApiReference, { docs: docs, isLogic: isLogic, componentGroups: componentGroups }));
 /**
  * A component's page.
  *
  * @param props - the component, the view, its loaders and how to open a story.
  */
-export const ComponentPage = ({ component, view, touchOverrides, onTouchChange, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, header, scroll, usedIn }) => {
+export const ComponentPage = ({ component, anchor, view, touchOverrides, onTouchChange, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, header, scroll, usedIn, onViewChange, tree, componentId, pageHrefOf, onOpenPage, loadTokens }) => {
     const pageRef = useRef(null);
     const docs = useComponentDocs(loadDocs);
     const code = useStoryCode(loadCode);
     const page = usePageDoc(loadPage);
-    // each story's own args, as its frame reports them: the code of a story drawn from its args is written from them
-    const [storyArgs, setStoryArgs] = useState(new Map());
     const demo = mainStory(component);
     const examples = useMemo(() => component.stories.filter((story) => story.id !== demo?.id), [component, demo]);
-    // the frames keep the view they loaded with; only the style sheets load them again, the rest of the view (the
-    // switches, the language among them) is sent to them live
-    const frameView = useLoadedView(view.sheets, view);
     const catalogue = useCatalogue();
-    const { switches } = catalogue;
-    // each story marked for a phone with its own finger: its frame gets it in place of the toolbar's Touch
-    const touches = useMemo(() => storyTouchesOf(component.stories, touchOverrides), [component, touchOverrides]);
-    const exampleIds = useMemo(() => examples.map((story) => story.id), [examples]);
-    const queue = useFrameQueue(exampleIds, pageRef);
-    const { heights, settled } = useFrameMessages({
-        onReady: (frame, message) => {
-            queue.markReady(message.storyId);
-            setStoryArgs((current) => new Map(current).set(message.storyId, message.args));
-            const send = (shellMessage) => frame.postMessage(shellMessage, window.location.origin);
-            send({
-                type: "forgebook:view",
-                view: touchedView(liveView(view), message.storyId, touches, catalogue.touch)
-            });
-            send({ type: "forgebook:tools", tools: view.tools });
-        },
-        onCall: () => undefined,
-        // a frame that failed is over too: its place in the queue goes to the next one
-        onFailed: queue.markReady
+    // the demo first in the queue, at the top of the page, and counted in it: a frame of a library served as source asks
+    // for thousands of modules, and one more beside those the queue allows makes the browser refuse some of them
+    const queued = useMemo(() => [...(demo === undefined ? [] : [demo.id]), ...examples.map((story) => story.id)], [demo, examples]);
+    const { queue, ...frames } = usePageFrames({
+        stories: component.stories,
+        queued,
+        pageRef,
+        view,
+        touchOverrides
     });
-    useLiveView(pageRef, view, true, { touches, choice: catalogue.touch });
     useScrollMemory(pageRef, scroll);
+    useAudienceLoads(view.audience, loadTokens, usedIn === undefined ? undefined : usageLoader(usedIn.source));
     const componentDocs = docs.status === "ready" ? docs.value : undefined;
+    const isLogic = isLogicComponent(component);
+    const reading = {
+        hasCode: view.audience !== "designer",
+        isCodeOpen: view.audience === "coder",
+        isDemoLarge: view.audience === "designer"
+    };
     const context = {
+        ...frames,
         component,
         view,
         frameUrl,
         hrefOf,
         onOpen,
-        frameView,
-        switches,
-        touches,
+        switches: catalogue.switches,
         onTouchChange,
-        heights,
-        settled,
         code,
-        componentName: componentDocs?.name ?? component.name,
-        argsOf: (storyId) => storyArgs.get(storyId) ?? {},
+        componentName: componentDocs === undefined ? component.name : codeNameOf(componentDocs),
         heightOf,
-        background
+        background,
+        reading
     };
-    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-doc", children: [_jsx(Lead, { page: page, docs: componentDocs }), demo === undefined ? null : _jsx(Example, { ...context, story: demo, isDemo: true, isMounted: true }), _jsx(Prose, { page: page }), componentDocs === undefined || componentDocs.props.length === 0 ? null : (_jsx(ApiReference, { docs: componentDocs })), examples.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-examples", children: [_jsx("h2", { id: "forgebook-examples", children: STRINGS.examples }), groupedStories(examples, catalogue.storyGroups.map((group) => group.id)).map((section) => (_jsxs("section", { className: "forgebook-doc__group", children: [section.group === undefined ? null : (_jsx("h3", { className: "forgebook-doc__group-name", children: groupLabel(catalogue.storyGroups, section.group) })), section.stories.map((story) => (_jsx(Example, { ...context, story: story, isDemo: false, isMounted: queue.mounted.has(story.id), observe: (element) => queue.observe(story.id, element) }, story.id)))] }, section.group ?? "")))] })), usedIn === undefined ? null : _jsx(UsedIn, { title: component.title, ...usedIn })] }, `${component.file}|${component.title}`) })] }));
+    const audienceProps = view.audience === "everyone"
+        ? undefined
+        : {
+            audience: view.audience,
+            hasNote: catalogue.ownControls.includes("audience"),
+            onShowAll: () => onViewChange({ ...view, audience: "everyone" }),
+            component,
+            docs: componentDocs,
+            isLogic,
+            page,
+            tree,
+            componentId,
+            pageHrefOf,
+            onOpenPage,
+            loadTokens,
+            coverage: {
+                viewKey: viewParams(view, catalogue.switches, catalogue.audience).toString(),
+                stories: component.stories,
+                storyGroups: catalogue.storyGroups,
+                queue,
+                pageRef,
+                settled: frames.settled,
+                hrefOf,
+                onOpen
+            },
+            usedIn,
+            pageRef
+        };
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, anchor === undefined ? null : (_jsx(Suspense, { fallback: null, children: _jsx(AnchorScroll, { pageRef: pageRef, anchor: anchor, visit: scroll.visit, isReady: docs.status !== "loading" && page.status !== "loading" }) })), _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-doc", "data-audience": view.audience === "everyone" ? undefined : view.audience, children: [_jsx(AudienceSlot, { place: "beforeDemo", audience: audienceProps, children: _jsx(Lead, { page: page, docs: componentDocs }) }), demo === undefined ? null : (_jsx(Example, { ...context, story: demo, isDemo: true, isMounted: queue.mounted.has(demo.id), observe: queue.observerOf(demo.id) })), _jsxs(AudienceSlot, { place: "afterDemo", audience: audienceProps, children: [_jsx(Prose, { page: page }), _jsx(PageApi, { docs: componentDocs, isLogic: isLogic, componentGroups: component.propGroups })] }), examples.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-examples", children: [_jsx("h2", { id: "forgebook-examples", children: LATER_STRINGS.examples }), groupedStories(examples, catalogue.storyGroups.map((group) => group.id)).map((section) => (_jsxs("section", { className: "forgebook-doc__group", children: [section.group === undefined ? null : (_jsx("h3", { className: "forgebook-doc__group-name", children: groupLabel(catalogue.storyGroups, section.group) })), section.stories.map((story) => (_jsx(Example, { ...context, story: story, isDemo: false, isMounted: queue.mounted.has(story.id), observe: queue.observerOf(story.id) }, story.id)))] }, section.group ?? "")))] })), _jsx(AudienceSlot, { place: "afterExamples", audience: audienceProps, children: usedIn === undefined ? null : _jsx(UsedIn, { title: component.title, ...usedIn }) })] }, `${component.file}|${component.title}`) })] }));
 };
-//# sourceMappingURL=ComponentPage.js.map

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

@@ -18,4 +18,3 @@ export declare const ControlKeyField: ({ label, shortcut, onKeyChange }: {
     /** Gives it another key (`null` takes it away); answers why a key cannot be given. */
     readonly onKeyChange: (key: string | null) => string | undefined;
 }) => ReactNode;
-//# sourceMappingURL=ControlKeyField.d.ts.map

package/dist/src/shell/ControlKeyField.js

@@ -7,7 +7,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useState } from "react";
 import { keyOf } from "../controlKeys.js";
-import { STRINGS } from "./strings.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 /** The keys that take a control's key away while one is recorded. */
 const REMOVE_KEYS = ["Backspace", "Delete"];
 /**
@@ -38,9 +38,8 @@ export const ControlKeyField = ({ label, shortcut, onKeyChange }) => {
         if (refused === undefined)
             setIsRecording(false);
     };
-    return (_jsxs("span", { className: "forgebook-key-field", children: [_jsx("button", { type: "button", className: "forgebook-key-field__button", "aria-label": STRINGS.controlKey(label, shortcut), "aria-pressed": isRecording, title: isRecording ? STRINGS.pressAKey : STRINGS.changeKey, onClick: () => {
+    return (_jsxs("span", { className: "forgebook-key-field", children: [_jsx("button", { type: "button", className: "forgebook-key-field__button", "aria-label": LATER_STRINGS.controlKey(label, shortcut), "aria-pressed": isRecording, title: isRecording ? LATER_STRINGS.pressAKey : LATER_STRINGS.changeKey, onClick: () => {
                     setProblem(undefined);
                     setIsRecording(!isRecording);
-                }, onBlur: () => setIsRecording(false), onKeyDown: record, children: isRecording ? STRINGS.pressAKey : _jsx("kbd", { children: shortcut?.toUpperCase() ?? "–" }) }), _jsx("span", { className: "forgebook-key-field__problem", role: "status", children: problem ?? "" })] }));
+                }, onBlur: () => setIsRecording(false), onKeyDown: record, children: isRecording ? LATER_STRINGS.pressAKey : _jsx("kbd", { children: shortcut?.toUpperCase() ?? "–" }) }), _jsx("span", { className: "forgebook-key-field__problem", role: "status", children: problem ?? "" })] }));
 };
-//# sourceMappingURL=ControlKeyField.js.map

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

@@ -6,15 +6,14 @@
  * @module
  */
 import type { PointerEvent, ReactNode } from "react";
-import type { PlacedControl } from "../toolbarLayout.ts";
-import { type ControlContext } from "./ToolbarControl.tsx";
+import type { ToolbarControl as Control, PlacedControl } from "../toolbarLayout.ts";
 import type { ToolbarLayout } from "./useToolbarLayout.ts";
 /**
  * One control's row: its handle, its name, its value, its key, its pin and its hide button.
  *
  * @param props - the placed control, its position, what moving and placing it do, and what every control shares.
  */
-export declare const ControlRow: ({ each, index, count, isDragged, isMoved, isChanged, layout, hintId, onGrab, onAnnounce, ...context }: ControlContext & {
+export declare const ControlRow: ({ each, index, count, isDragged, isMoved, isChanged, layout, hintId, onGrab, onAnnounce, drawControl }: {
     readonly each: PlacedControl;
     readonly index: number;
     readonly count: number;
@@ -27,5 +26,6 @@ export declare const ControlRow: ({ each, index, count, isDragged, isMoved, isCh
     readonly hintId: string;
     readonly onGrab: (event: PointerEvent<HTMLButtonElement>, id: string) => void;
     readonly onAnnounce: (text: string) => void;
+    /** Draws a control in a row's form, as the toolbar draws it, with the view it reads and sets. */
+    readonly drawControl: (control: Control) => ReactNode;
 }) => ReactNode;
-//# sourceMappingURL=ControlRow.d.ts.map

package/dist/src/shell/ControlRow.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ControlKeyField } from "./ControlKeyField.js";
+import { controlLabel } from "./controlLabel.js";
 import { InfoTip } from "./InfoTip.js";
 import { Icon } from "./icons.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { STRINGS } from "./strings.js";
-import { controlLabel, ToolbarControl } from "./ToolbarControl.js";
 /** The arrow keys that move a row, and by how much. */
 const ARROW_STEPS = { ArrowUp: -1, ArrowDown: 1 };
 /**
@@ -11,7 +12,7 @@ const ARROW_STEPS = { ArrowUp: -1, ArrowDown: 1 };
  *
  * @param props - the placed control, its position, what moving and placing it do, and what every control shares.
  */
-export const ControlRow = ({ each, index, count, isDragged, isMoved, isChanged, layout, hintId, onGrab, onAnnounce, ...context }) => {
+export const ControlRow = ({ each, index, count, isDragged, isMoved, isChanged, layout, hintId, onGrab, onAnnounce, drawControl }) => {
     const { control, isPinned } = each;
     const label = controlLabel(control);
     const step = (event) => {
@@ -21,10 +22,9 @@ export const ControlRow = ({ each, index, count, isDragged, isMoved, isChanged,
             return;
         event.preventDefault();
         layout.move(control.id, target);
-        onAnnounce(STRINGS.controlMoved(label, target + 1, count));
+        onAnnounce(LATER_STRINGS.controlMoved(label, target + 1, count));
     };
     // a switch's note (the touch simulation's limits): an info button beside its value
     const description = control.kind === "switch" ? control.switch.description : undefined;
-    return (_jsxs("li", { className: "forgebook-arrange", "data-control": control.id, "data-pinned": isPinned ? "" : undefined, "data-dragged": isDragged ? "" : undefined, "data-moved": isMoved ? "" : undefined, children: [_jsx("button", { type: "button", className: "forgebook-arrange__handle", "aria-label": STRINGS.moveControl(label), "aria-describedby": hintId, onPointerDown: (event) => onGrab(event, control.id), onKeyDown: step, children: _jsx(Icon, { name: "grip", size: 14 }) }), _jsxs("span", { className: "forgebook-popover__label", children: [label, isChanged ? (_jsx("span", { className: "forgebook-dot", role: "img", "aria-label": STRINGS.controlChanged(label) })) : null] }), _jsxs("div", { className: "forgebook-arrange__control", children: [_jsx(ToolbarControl, { control: control, form: "row", ...context }), description === undefined ? null : _jsx(InfoTip, { note: description, about: label })] }), _jsx(ControlKeyField, { label: label, shortcut: layout.keys[control.id], onKeyChange: (key) => layout.setKey(control.id, key) }), _jsx("button", { type: "button", className: "forgebook-icon-button", "aria-label": STRINGS.pinControl(label), title: isMoved ? STRINGS.pinnedNoRoom : STRINGS.pinControl(label), "aria-pressed": isPinned, onClick: () => layout.pin(control.id, !isPinned), children: _jsx(Icon, { name: "pin", size: 14 }) }), _jsx("button", { type: "button", className: "forgebook-icon-button", "aria-label": STRINGS.hideControl(label), title: STRINGS.hideControl(label), onClick: () => layout.hide(control.id, true), children: _jsx(Icon, { name: "eyeOff", size: 14 }) })] }));
+    return (_jsxs("li", { className: "forgebook-arrange", "data-control": control.id, "data-pinned": isPinned ? "" : undefined, "data-dragged": isDragged ? "" : undefined, "data-moved": isMoved ? "" : undefined, children: [_jsx("button", { type: "button", className: "forgebook-arrange__handle", "aria-label": LATER_STRINGS.moveControl(label), "aria-describedby": hintId, onPointerDown: (event) => onGrab(event, control.id), onKeyDown: step, children: _jsx(Icon, { name: "grip", size: 14 }) }), _jsxs("span", { className: "forgebook-popover__label", children: [label, isChanged ? (_jsx("span", { className: "forgebook-dot", role: "img", "aria-label": STRINGS.controlChanged(label) })) : null] }), _jsxs("div", { className: "forgebook-arrange__control", children: [drawControl(control), description === undefined ? null : _jsx(InfoTip, { note: description, about: label })] }), _jsx(ControlKeyField, { label: label, shortcut: layout.keys[control.id], onKeyChange: (key) => layout.setKey(control.id, key) }), _jsx("button", { type: "button", className: "forgebook-icon-button", "aria-label": LATER_STRINGS.pinControl(label), title: isMoved ? LATER_STRINGS.pinnedNoRoom : LATER_STRINGS.pinControl(label), "aria-pressed": isPinned, onClick: () => layout.pin(control.id, !isPinned), children: _jsx(Icon, { name: "pin", size: 14 }) }), _jsx("button", { type: "button", className: "forgebook-icon-button", "aria-label": LATER_STRINGS.hideControl(label), title: LATER_STRINGS.hideControl(label), onClick: () => layout.hide(control.id, true), children: _jsx(Icon, { name: "eyeOff", size: 14 }) })] }));
 };
-//# sourceMappingURL=ControlRow.js.map

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

@@ -0,0 +1,31 @@
+/**
+ * The device control of the toolbar and the View menu: a list that says what the story is shown in ("No frame", "iPhone
+ * 16"…), turns the frame off and picks the model, and, while a device is shown, the button that turns it.
+ *
+ * @remarks
+ * A native list, for the platform's keys and screen reader, its models grouped by kind. The address keeps only what
+ * differs from the page's default (`deviceView.ts`, `deviceMenuView.ts`). The device's drawing is not here: it loads
+ * with the device's parts the first time a story is framed (`DeviceSlot.tsx`).
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import { type DeviceDefault } from "../deviceView.ts";
+import type { ViewState } from "../viewState.ts";
+/** The device control's props. */
+export type DeviceControlProps = {
+    /** Where it is drawn: on the toolbar, with its icon, or in a row of the View menu, whose row names it. */
+    readonly form: "bar" | "row";
+    /** The view shown. */
+    readonly view: ViewState;
+    /** Called with the changed view. */
+    readonly onViewChange: (view: ViewState) => void;
+    /** The page's default device: the shown story's, a component's stories', or the catalogue's. */
+    readonly defaults: DeviceDefault;
+};
+/**
+ * The device control.
+ *
+ * @param props - its form, the view, its setter and the page's default device.
+ */
+export declare const DeviceControl: ({ form, view, onViewChange, defaults }: DeviceControlProps) => ReactNode;

package/dist/src/shell/DeviceControl.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { withModel, withTurn } from "../deviceMenuView.js";
+import { DEVICE_ENTRIES, isDeviceId, shownDevice, withFrame } from "../deviceView.js";
+import { Icon } from "./icons.js";
+import { STRINGS } from "./strings.js";
+/** The value of the list's first choice: no device. */
+const NO_FRAME = "off";
+/** The list's groups, in its order. */
+const KIND_GROUPS = [
+    { kind: "phone", label: () => STRINGS.devicePhones },
+    { kind: "tablet", label: () => STRINGS.deviceTablets }
+];
+/**
+ * A model's name in the list: the generic phone's is the shell's text, so a catalogue can translate it.
+ *
+ * @param entry - the model.
+ */
+const entryName = (entry) => (entry.id === "phone" ? STRINGS.deviceGeneric : entry.name);
+/**
+ * The device control.
+ *
+ * @param props - its form, the view, its setter and the page's default device.
+ */
+export const DeviceControl = ({ form, view, onViewChange, defaults }) => {
+    const shown = shownDevice(view, defaults);
+    const choose = (value) => {
+        if (value === NO_FRAME)
+            onViewChange(withFrame(view, defaults, false));
+        else if (isDeviceId(value))
+            onViewChange(withModel(view, defaults, value));
+    };
+    return (_jsxs("div", { className: "forgebook-toolbar__control forgebook-device-control", children: [form === "bar" ? (_jsx("span", { className: "forgebook-toolbar__icon", title: STRINGS.device, children: _jsx(Icon, { name: "device", size: 14 }) })) : null, _jsxs("select", { className: "forgebook-select", "aria-label": STRINGS.device, value: shown?.model ?? NO_FRAME, onChange: (event) => choose(event.currentTarget.value), children: [_jsx("option", { value: NO_FRAME, children: STRINGS.deviceNone }), KIND_GROUPS.map((group) => (_jsx("optgroup", { label: group.label(), children: DEVICE_ENTRIES.filter((entry) => entry.kind === group.kind).map((entry) => (_jsx("option", { value: entry.id, children: entryName(entry) }, entry.id))) }, group.kind)))] }), shown === undefined ? null : (_jsx("button", { type: "button", className: "forgebook-button forgebook-button--icon", title: STRINGS.deviceTurn, "aria-label": STRINGS.deviceTurn, "aria-pressed": shown.orientation === "landscape", onClick: () => onViewChange(withTurn(view, defaults, shown)), children: _jsx(Icon, { name: "turn", size: 14 }) }))] }));
+};

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

@@ -0,0 +1,114 @@
+/**
+ * The place of a story's frame that a device can be drawn around: always there, so turning the device on or off adds
+ * the drawing beside the frame and never mounts the frame again (the story keeps its state), and the loader of the
+ * device's parts, which only a framed story fetches.
+ *
+ * @remarks
+ * The models' sizes, their drawings, the device menu and their styles are one chunk (`device/deviceParts.tsx`),
+ * imported the first time a story is shown in a device: a catalogue that never shows one never loads it, so the
+ * shell's first load does not grow with it. Until it arrives the story is shown as without a device, for the moment
+ * a local chunk takes.
+ *
+ * @module
+ */
+import type { StoryDeviceSetting } from "@forgebook/story-format/csf";
+import { type ReactNode } from "react";
+import type { DeviceDrawing } from "../deviceDrawing.ts";
+import type { StoryArea } from "../devices.ts";
+import { type DeviceView, type ShownDevice, type StoryDevice } from "../deviceView.ts";
+import type * as DevicePartsModule from "./device/deviceParts.tsx";
+import type { StageViewportProps } from "./StageViewport.tsx";
+/** The device's parts, as their chunk exports them. */
+export type DeviceParts = typeof DevicePartsModule;
+/**
+ * The device's parts, loaded the first time they are needed.
+ *
+ * @param isNeeded - whether a device is to be drawn.
+ * @returns the parts once loaded; none before, or when the chunk could not be fetched (the story is then shown
+ *   without its device, never broken).
+ */
+export declare const useDeviceParts: (isNeeded: boolean) => DeviceParts | undefined;
+/** A device ready to draw: its parts, which device, and its drawing. */
+export type FramedDevice = {
+    /** The parts that draw it. */
+    readonly parts: DeviceParts;
+    /** The device shown. */
+    readonly shown: ShownDevice;
+    /** Its drawing. */
+    readonly drawing: DeviceDrawing;
+    /** The part of its screen the story is drawn in: its viewport, and the safe areas it is told. */
+    readonly area: StoryArea;
+};
+/**
+ * The device a story is drawn in, once its parts are there.
+ *
+ * @param shown - the device shown; none for no device.
+ */
+export declare const useFramedDevice: (shown: StoryDevice | undefined) => FramedDevice | undefined;
+/**
+ * The device a story on the stage is drawn in: the view's choice over the story's and the catalogue's defaults, and
+ * once its parts are there, its screen's width told as the story's width.
+ *
+ * @param view - the view's device.
+ * @param storyDevice - the story's own setting, over the catalogue's.
+ * @param onShownWidthChange - told the width the story really has.
+ */
+export declare const useStageDevice: (view: DeviceView, storyDevice: StoryDeviceSetting | undefined, onShownWidthChange: (width: number | undefined) => void) => {
+    readonly shown: StoryDevice | undefined;
+    readonly framed: FramedDevice | undefined;
+};
+/**
+ * Whether a story's frame waits for its device's parts before it loads: a story drawn edge to edge is told its safe
+ * areas in its address, which only the parts know, and loading it first would load it twice.
+ *
+ * @param shown - the device shown; none for none.
+ * @param framed - the device once its parts are there.
+ */
+export declare const isWaitingForDevice: (shown: StoryDevice | undefined, framed: FramedDevice | undefined) => boolean;
+/**
+ * A story frame's address in its device: with the safe areas a story drawn edge to edge is told; as it is otherwise.
+ *
+ * @param address - the frame's address.
+ * @param framed - the device; none for none.
+ */
+export declare const deviceAddress: (address: string, framed: FramedDevice | undefined) => string;
+/** The slot's props. */
+export type DeviceSlotProps = {
+    /** The device drawn around the frame; none shows the frame alone. */
+    readonly framed: FramedDevice | undefined;
+    /** The story's scheme, which the status bar's ink follows. */
+    readonly scheme: "light" | "dark";
+    /** The colour of the story's page, which the screen waits on while the story loads. */
+    readonly background?: string | undefined;
+    /** The frame. */
+    readonly children: ReactNode;
+};
+/**
+ * The frame's place, with the device around it when there is one: the parts draw it, this place stays.
+ *
+ * @param props - the device, the story's scheme and page colour, and the frame.
+ */
+export declare const DeviceSlot: ({ framed, scheme, background, children }: DeviceSlotProps) => ReactNode;
+/**
+ * The scheme a story is drawn in, for the status bar's ink: its colour scheme switch's, the system's for `system`.
+ *
+ * @param scheme - the view's scheme (`schemeOf`).
+ * @param isSystemDark - whether the system is dark.
+ */
+export declare const inkScheme: (scheme: "light" | "dark" | "system", isSystemDark: boolean) => "light" | "dark";
+/**
+ * The scheme a story is drawn in, for the status bar's ink, following the system's for `system`.
+ *
+ * @param scheme - the view's scheme (`schemeOf`).
+ */
+export declare const useInkScheme: (scheme: "light" | "dark" | "system") => "light" | "dark";
+/** What sizes a story's room on the stage, and what the stage's handles and its width field are told. */
+export type RoomSizing = Pick<StageViewportProps, "width" | "onWidthChange" | "onShownWidthChange" | "background" | "height" | "onHeightChange" | "isDevice">;
+/**
+ * The room's sizing with a device: the device's size, no handles (the device sets the width and the height), no
+ * surface of the room's own; the stage's own sizing without one.
+ *
+ * @param framed - the device; none keeps the stage's own.
+ * @param own - the stage's own sizing.
+ */
+export declare const roomSizing: (framed: FramedDevice | undefined, own: RoomSizing) => RoomSizing;