forgebook 0.1.8 → 0.3.0

package/dist/src/shell/SearchPanel.js

@@ -0,0 +1,209 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The search's results: beside the sidebar, what the words find across the catalogue, each component or docs page with
+ * what matched inside it and why, and a key for every move.
+ *
+ * @remarks
+ * Loaded with its style sheet on first use, and it loads the index only when something is typed, so a reader who never
+ * searches pays for neither. The focus stays in the search field, as a list that follows the words needs: the arrows
+ * move the row `aria-activedescendant` names. Every row is a real link, so a modified press opens a new tab. The results
+ * sit beside the tree, which goes on filtering by name: the tree is for browsing what the words leave, this list for
+ * going to the exact place.
+ *
+ * @module
+ */
+import "./search.css";
+import { useDeferredValue, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { searchables, searchCatalogue } from "../search.js";
+import { SEARCH_STRINGS } from "./searchStrings.js";
+import { shownTree } from "./treeSearch.js";
+import { useSearchIndex } from "./useSearchIndex.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. */
+const LIST_MARGIN = 8;
+/** The list's widest: long enough for a sentence around a match. */
+const LIST_WIDTH = "38rem";
+/**
+ * Where the list sits: beside the sidebar, or under the field on a small window.
+ *
+ * @param field - where the field is.
+ * @param sidebarWidth - the sidebar's width, in CSS px.
+ */
+const listPlace = (field, sidebarWidth) => {
+    if (window.innerWidth < BESIDE_WIDTH)
+        return { top: field.bottom + LIST_GAP, insetInline: LIST_MARGIN };
+    const start = sidebarWidth + LIST_MARGIN;
+    return {
+        top: field.top,
+        insetInlineStart: start,
+        width: `min(${LIST_WIDTH}, calc(100vw - ${start + LIST_MARGIN}px))`
+    };
+};
+/** How far each key moves the highlighted row. */
+const KEY_STEPS = { ArrowDown: 1, ArrowUp: -1 };
+/** The name of each kind of hit. */
+const HIT_NAMES = {
+    prop: SEARCH_STRINGS.hitProp,
+    event: SEARCH_STRINGS.hitEvent,
+    story: SEARCH_STRINGS.hitStory,
+    heading: SEARCH_STRINGS.hitHeading,
+    text: SEARCH_STRINGS.hitText,
+    description: SEARCH_STRINGS.hitDescription
+};
+/** Whether a press is a modified one, left to the browser: a new tab or a download. */
+const isModified = (event) => event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0;
+/**
+ * A text with what matched marked.
+ *
+ * @param props - the pieces.
+ */
+const Marked = ({ pieces }) => pieces.map((piece, place) => 
+// the pieces of a text never move: their place is who they are
+// biome-ignore lint/suspicious/noArrayIndexKey: see above
+piece.isMatch ? _jsx("mark", { children: piece.text }, place) : _jsx("span", { children: piece.text }, place));
+/** What a reason says. */
+const reasonText = ({ place, means }) => {
+    if (means !== undefined)
+        return SEARCH_STRINGS.means(means);
+    if (place === "keyword")
+        return SEARCH_STRINGS.reasonKeyword;
+    return place === "title" ? SEARCH_STRINGS.reasonPlace : undefined;
+};
+/**
+ * A row's link.
+ *
+ * @param props - the row, whether it is highlighted, and how it opens.
+ */
+const RowLink = ({ row, isActive, hrefOf, onOpen, onActive, className, children }) => (_jsx("a", { id: row.id, role: "option", tabIndex: -1, "aria-selected": isActive, "data-active": isActive ? "" : undefined, className: className, href: hrefOf(row.target), onPointerMove: onActive, onClick: (event) => {
+        if (isModified(event))
+            return;
+        event.preventDefault();
+        onOpen(row.target);
+    }, children: children }));
+/**
+ * A hit's line: what it is, its name, the words around the match.
+ *
+ * @param props - the hit.
+ */
+const HitLine = ({ hit }) => (_jsxs(_Fragment, { children: [_jsx("span", { className: "forgebook-result__why", children: HIT_NAMES[hit.kind] }), _jsxs("span", { className: "forgebook-result__body", children: [hit.label === undefined ? null : (_jsx("span", { className: "forgebook-result__label", "data-code": hit.kind === "prop" || hit.kind === "event" ? "" : undefined, children: _jsx(Marked, { pieces: hit.label }) })), hit.snippet.length === 0 ? null : (_jsx("span", { className: "forgebook-result__snippet", children: _jsx(Marked, { pieces: hit.snippet }) }))] })] }));
+/**
+ * A result's own line: its name, where it sits, and why its name is there.
+ *
+ * @param props - the result.
+ */
+const ResultLine = ({ result }) => {
+    const reasons = result.reasons.flatMap((reason) => reasonText(reason) ?? []);
+    return (_jsxs(_Fragment, { children: [_jsx("span", { className: "forgebook-result__name", children: _jsx(Marked, { pieces: result.name }) }), reasons.map((reason) => (_jsx("span", { className: "forgebook-result__why", children: reason }, reason))), _jsx("span", { className: "forgebook-result__place", children: result.place }), _jsx("span", { className: "forgebook-result__kind", children: result.kind === "page" ? SEARCH_STRINGS.kindPage : SEARCH_STRINGS.kindComponent })] }));
+};
+/**
+ * What a result leaves out: how much more is inside it, and the words it does not hold; nothing when it leaves out
+ * nothing.
+ *
+ * @param props - the result, and how many of its hits are listed.
+ */
+const ResultNote = ({ result, listed }) => {
+    const more = result.hitCount - listed;
+    if (more === 0 && result.missed.length === 0)
+        return null;
+    return (_jsxs("p", { className: "forgebook-result__note", children: [more > 0 ? _jsx("span", { children: SEARCH_STRINGS.more(more) }) : null, result.missed.length > 0 ? _jsx("span", { children: SEARCH_STRINGS.missing(result.missed.join(", ")) }) : null] }));
+};
+/** The answer's rows, for the keys and the list. */
+const useResultRows = (answer) => {
+    const baseId = useId();
+    return useMemo(() => answer.results.map((result, place) => ({
+        result,
+        own: { id: `${baseId}-${place}`, target: result.target },
+        hits: result.hits.map((hit, hitPlace) => ({
+            hit,
+            row: { id: `${baseId}-${place}-${hitPlace}`, target: hit.target }
+        }))
+    })), [answer, baseId]);
+};
+/** The highlighted row: moved by the keys and the pointer, kept in view, named to the field. */
+const useActiveRow = ({ rows, isShown, hrefOf, onOpen, onActiveChange, keysRef }) => {
+    const [place, setPlace] = useState(0);
+    // new words, or an index that arrived, change what each place holds: Enter must not open what the reader never saw
+    // biome-ignore lint/correctness/useExhaustiveDependencies: the rows are what resets it
+    useEffect(() => setPlace(0), [rows]);
+    const active = rows[Math.min(place, rows.length - 1)];
+    const activeId = isShown ? active?.id : undefined;
+    useEffect(() => onActiveChange(activeId), [activeId, onActiveChange]);
+    const listRef = useRef(null);
+    useEffect(() => {
+        if (activeId === undefined)
+            return;
+        listRef.current?.querySelector(`[id="${CSS.escape(activeId)}"]`)?.scrollIntoView({ block: "nearest" });
+    }, [activeId]);
+    useImperativeHandle(keysRef, () => ({
+        press: (key, hasModifier) => {
+            if (activeId === undefined || active === undefined)
+                return false;
+            const step = KEY_STEPS[key];
+            if (step !== undefined)
+                setPlace((row) => (row + step + rows.length) % rows.length);
+            else if (key !== "Enter")
+                return false;
+            else if (hasModifier)
+                window.open(hrefOf(active.target), "_blank", "noopener");
+            else
+                onOpen(active.target);
+            return true;
+        }
+    }));
+    return { active, setActive: (row) => setPlace(rows.indexOf(row)), listRef };
+};
+/** The answer's state, in a line: how many results, what is still coming, what could not be read. */
+const PanelStatus = ({ total, query, isLoading, hasFailed }) => (_jsxs("p", { className: "forgebook-search-panel__status", role: "status", children: [total === 0 && !isLoading ? _jsx("span", { children: SEARCH_STRINGS.nothing(query.trim()) }) : null, total > 0 ? _jsx("span", { children: SEARCH_STRINGS.count(total) }) : null, isLoading ? _jsx("span", { children: SEARCH_STRINGS.reading }) : null, hasFailed ? _jsx("span", { children: SEARCH_STRINGS.unreadable }) : null] }));
+/**
+ * The search's results.
+ *
+ * @param props - what was typed, what can be found and how to go to it.
+ */
+export const SearchPanel = ({ tree, sources, query, isOpen, field, sidebarWidth, onFilterReady, hrefOf, onOpen, onActiveChange, keysRef, id }) => {
+    useEffect(() => onFilterReady(shownTree), [onFilterReady]);
+    // the index is asked for once, by the first words
+    const hasQuery = query.trim() !== "";
+    const [isWanted, setIsWanted] = useState(hasQuery);
+    if (hasQuery && !isWanted)
+        setIsWanted(true);
+    const { indexes, isLoading, hasFailed } = useSearchIndex(sources, isWanted);
+    const all = useMemo(() => searchables(tree, indexes), [tree, indexes]);
+    // the field never waits for a long list
+    const words = useDeferredValue(query);
+    const answer = useMemo(() => searchCatalogue(all, words, LIMITS), [all, words]);
+    const results = useResultRows(answer);
+    const rows = useMemo(() => results.flatMap(({ own, hits }) => [own, ...hits.map(({ row }) => row)]), [results]);
+    const isShown = isOpen && hasQuery;
+    const panelRef = useRef(null);
+    // in the top layer: the sidebar's own stacking would otherwise leave the list under the page it opens over
+    useLayoutEffect(() => {
+        if (isShown)
+            panelRef.current?.showPopover();
+    }, [isShown]);
+    const rect = isShown ? field.current?.closest("label")?.getBoundingClientRect() : undefined;
+    const { active, setActive, listRef } = useActiveRow({
+        rows,
+        isShown,
+        hrefOf,
+        onOpen,
+        onActiveChange,
+        keysRef
+    });
+    if (!isShown)
+        return null;
+    const rowProps = (row) => ({
+        row,
+        hrefOf,
+        onOpen,
+        isActive: row.id === active?.id,
+        onActive: () => setActive(row)
+    });
+    return (_jsxs("section", { ref: panelRef, popover: "manual", className: "forgebook-search-panel", "aria-label": SEARCH_STRINGS.results, "data-ready": isLoading ? undefined : "", style: rect === undefined ? undefined : listPlace(rect, sidebarWidth), 
+        // the focus stays in the field: a press here would take it away and close the list before it opens anything
+        onMouseDown: (event) => event.preventDefault(), children: [_jsx(PanelStatus, { total: answer.total, query: query, isLoading: isLoading, hasFailed: hasFailed }), _jsx("div", { id: id, ref: listRef, className: "forgebook-search-panel__list", role: "listbox", "aria-label": SEARCH_STRINGS.results, children: results.map(({ result, own, hits }) => (_jsxs("div", { className: "forgebook-result", children: [_jsx(RowLink, { ...rowProps(own), className: "forgebook-result__own", children: _jsx(ResultLine, { result: result }) }), hits.map(({ hit, row }) => (_jsx(RowLink, { ...rowProps(row), className: "forgebook-result__hit", children: _jsx(HitLine, { hit: hit }) }, row.id))), _jsx(ResultNote, { result: result, listed: hits.length })] }, own.id))) }), _jsxs("p", { className: "forgebook-search-panel__keys", children: [_jsx("kbd", { children: "\u2191" }), _jsx("kbd", { children: "\u2193" }), " ", SEARCH_STRINGS.keyMove, " ", _jsx("kbd", { children: "\u21B5" }), " ", SEARCH_STRINGS.keyOpen, " ", _jsx("kbd", { children: "esc" }), " ", SEARCH_STRINGS.keyClear] })] }));
+};

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

@@ -38,4 +38,3 @@ export type SegmentedProps<TValue extends string | number> = {
  * @param props - the options and the chosen value.
  */
 export declare const Segmented: <TValue extends string | number>({ label, options, value, onValueChange, isDisabled, disabledNote, after }: SegmentedProps<TValue>) => ReactNode;
-//# sourceMappingURL=Segmented.d.ts.map

package/dist/src/shell/Segmented.js

@@ -16,4 +16,3 @@ export const Segmented = ({ label, options, value, onValueChange, isDisabled = f
     const name = useId();
     return (_jsxs("fieldset", { className: "forgebook-segmented", disabled: isDisabled, title: isDisabled ? disabledNote : undefined, children: [_jsx("legend", { className: "forgebook-visually-hidden", children: label }), options.map((option) => (_jsxs("label", { className: "forgebook-segmented__option", title: option.icon ? option.label : undefined, children: [_jsx("input", { type: "radio", className: "forgebook-visually-hidden", name: name, checked: option.value === value, "aria-label": option.icon ? option.label : undefined, onChange: () => onValueChange(option.value) }), _jsx("span", { className: "forgebook-segmented__face", children: option.icon ? _jsx(Icon, { name: option.icon, size: 14 }) : option.label })] }, String(option.value)))), after] }));
 };
-//# sourceMappingURL=Segmented.js.map

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

@@ -5,18 +5,24 @@
  * @module
  */
 import type { StoryLanguage, StorySource } from "@forgebook/story-format/source";
-import { type ReactNode } from "react";
-import { type CatalogueLists } from "../catalogue.ts";
-import { type ViewSwitch } from "../switches.ts";
+import { type ComponentType, type ReactNode } from "react";
+import { type AddressTexts } from "../addressTexts.ts";
+import type { CatalogueLists } from "../catalogue.ts";
+import type { ViewSwitch } from "../switches.ts";
+import type { WrittenHomeProps } from "./AuthoredHome.tsx";
+import { type LoadPluginHosts } from "./pluginHostsContext.ts";
+import type { ShellPlugin } from "./pluginTabs.tsx";
 /** What an app passes to the shell. */
 export type ShellConfig = {
     /** The catalogue's name, in the page title and the sidebar. */
     readonly title: string;
     /**
      * The catalogue's logo, the URL of a square image: beside its name in the sidebar and as the page's icon. None by
-     * default: the catalogue's own mark. The catalogue belongs to whoever mounts it, so the logo is theirs to give.
+     * default: Forgebook's mark. The catalogue belongs to whoever mounts it, so the logo is theirs to give.
      */
     readonly logo?: string;
+    /** Whether a catalogue without a logo shows Forgebook's mark; off, it shows its name alone. On by default. */
+    readonly hasBranding?: boolean;
     /**
      * The stories' measured heights, the address of the file `forgebook-heights` writes (relative to the page): a story's
      * box waits at its height while it loads. None by default, and a missing file is none: boxes then wait at a guess.
@@ -24,7 +30,10 @@ export type ShellConfig = {
     readonly heights?: string;
     /** The sources, in the order the sidebar lists them. */
     readonly sources: readonly StorySource[];
-    /** The frame page's address, relative to the shell's (`frame.html`). */
+    /**
+     * The frame page's address: relative to the shell's (`frame.html`) when the frames share its origin, on the frames'
+     * origin otherwise (`mountShell` makes it).
+     */
     readonly frameUrl: string;
     /**
      * The languages every story can be drawn in (the View menu's Language row); none turns them off. Give the frame
@@ -38,6 +47,26 @@ export type ShellConfig = {
     readonly switches?: readonly ViewSwitch[];
     /** The catalogue's lists (its widths, zoom steps, backgrounds, story groups…); the defaults when none. */
     readonly lists?: CatalogueLists;
+    /**
+     * Loads the catalogue's written home (`forgebook.home.md`), drawn in place of the generated home: the page's entry
+     * gives it only for a catalogue that has one, so the others' first load carries nothing of it. None keeps the
+     * generated home.
+     */
+    readonly home?: () => Promise<ComponentType<WrittenHomeProps>>;
+    /** Loads the catalogue's design tokens, on first use; none when it has none. */
+    readonly loadTokens?: () => Promise<unknown>;
+    /** The plugins with views (the generated page passes them); none by default. */
+    readonly plugins?: readonly ShellPlugin[];
+    /**
+     * Loads the code that draws the plugins' views (`forgebook/shell/plugin-hosts`): the generated page gives it only
+     * with plugins that have views, so a catalogue without one ships none of it. None draws no plugin's view.
+     */
+    readonly pluginHosts?: LoadPluginHosts;
+    /**
+     * How the framework's stories take the texts the address carries (`addressTexts.ts`): `plain` keeps a shared link's
+     * texts that are not plain words from a story that may write them into markup. `any` by default.
+     */
+    readonly addressTexts?: AddressTexts;
 };
 /**
  * The catalogue's page: its settings computed once from the configuration (its switches, its languages' switch, its
@@ -46,4 +75,3 @@ export type ShellConfig = {
  * @param props - the configuration.
  */
 export declare const Shell: (props: ShellConfig) => ReactNode;
-//# sourceMappingURL=Shell.d.ts.map