@nanisoft/prism-ui 0.10.2 → 0.13.0

package/dist/blocks/site-navbar/mobile-nav.d.ts

@@ -0,0 +1,48 @@
+import type { ProductMarkProps } from '../../components/ui/product-mark.js';
+/** One destination in the mobile panel, which is the site's own navigation. */
+export type MobileNavLink = {
+    /** The text of the link. */
+    label: string;
+    /** Where the link goes. */
+    href: string;
+    /** Marks this link as the page the reader is on. */
+    current?: boolean;
+};
+/** The props the mobile navigation takes. */
+export type MobileNavProps = {
+    /** The product this navigation belongs to, drawn as the mark above the list. */
+    product: Pick<ProductMarkProps, 'id' | 'name' | 'pack'>;
+    /** Every destination, in the order a reader should meet them. */
+    links: readonly MobileNavLink[];
+    /** The accessible name of the panel, which is also the trigger's name. */
+    label: string;
+    /** The word on the trigger while the panel is closed. */
+    openLabel: string;
+    /** The word on the trigger while the panel is open. */
+    closeLabel: string;
+};
+/**
+ * The navigation for viewports below the row's own threshold.
+ *
+ * **It carries every destination, not a subset.** From the narrowest phone up to
+ * the width the horizontal row is authored for, this panel is the only way to reach
+ * a section of the site, so a link the row shows at `lg` and the panel omits at
+ * 640 is a route a reader on a small laptop cannot find at all. Both render the one
+ * array, so a destination added to one is in the other by construction rather than
+ * by remembering twice.
+ *
+ * **It is a Sheet rather than a disclosure panel of the navbar's own, and the
+ * difference is the overlay.** A panel that is a child of the bar sits over the
+ * page with the bar still visible and nothing above the rest of the document, so
+ * scrolling the page behind it moves content the reader thought was dismissed. A
+ * sheet owns a modal surface: the rest of the page is not reachable, Escape closes
+ * it, and focus is held inside it and handed back to the trigger on the way out.
+ * That is the behaviour a full-width menu over a long page needs, and it is the
+ * behaviour Prism's own navigation had to hand-write.
+ *
+ * The links are full width with a 44 pixel minimum height, because below the row's
+ * threshold this is a touch target and not a line of text, and the coarse-pointer
+ * floor in the design system asks for exactly that.
+ */
+export declare function MobileNav({ product, links, label, openLabel, closeLabel, }: MobileNavProps): import("react").JSX.Element;
+//# sourceMappingURL=mobile-nav.d.ts.map

package/dist/blocks/site-navbar/mobile-nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobile-nav.d.ts","sourceRoot":"","sources":["../../../src/blocks/site-navbar/mobile-nav.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAA;AAExE,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG;IAC1B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG;IAC3B,gFAAgF;IAChF,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC,CAAA;IACvD,iEAAiE;IACjE,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IAC/B,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,EACxB,OAAO,EACP,KAAK,EACL,KAAK,EACL,SAAS,EACT,UAAU,GACX,EAAE,cAAc,+BAsChB"}

package/dist/blocks/site-navbar/mobile-nav.js

@@ -0,0 +1,35 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Menu, X } from 'lucide-react';
+import { Sheet, SheetContent, SheetTitle, SheetTrigger } from '../../components/ui/sheet.js';
+import { ProductMark } from '../../components/ui/product-mark.js';
+/**
+ * The navigation for viewports below the row's own threshold.
+ *
+ * **It carries every destination, not a subset.** From the narrowest phone up to
+ * the width the horizontal row is authored for, this panel is the only way to reach
+ * a section of the site, so a link the row shows at `lg` and the panel omits at
+ * 640 is a route a reader on a small laptop cannot find at all. Both render the one
+ * array, so a destination added to one is in the other by construction rather than
+ * by remembering twice.
+ *
+ * **It is a Sheet rather than a disclosure panel of the navbar's own, and the
+ * difference is the overlay.** A panel that is a child of the bar sits over the
+ * page with the bar still visible and nothing above the rest of the document, so
+ * scrolling the page behind it moves content the reader thought was dismissed. A
+ * sheet owns a modal surface: the rest of the page is not reachable, Escape closes
+ * it, and focus is held inside it and handed back to the trigger on the way out.
+ * That is the behaviour a full-width menu over a long page needs, and it is the
+ * behaviour Prism's own navigation had to hand-write.
+ *
+ * The links are full width with a 44 pixel minimum height, because below the row's
+ * threshold this is a touch target and not a line of text, and the coarse-pointer
+ * floor in the design system asks for exactly that.
+ */
+export function MobileNav({ product, links, label, openLabel, closeLabel, }) {
+    const [open, setOpen] = useState(false);
+    return (_jsxs(Sheet, { open: open, onOpenChange: setOpen, children: [_jsx(SheetTrigger, { "data-slot": "site-navbar-mobile-trigger", "aria-label": open ? closeLabel : openLabel, className: "border-border bg-card text-foreground hover:bg-accent hover:text-accent-foreground focus-visible:border-ring focus-visible:ring-ring flex size-11 shrink-0 items-center justify-center rounded-full border transition-colors focus-visible:ring-[3px] focus-visible:outline-none lg:hidden", children: open ? _jsx(X, { "aria-hidden": true, className: "size-5" }) : _jsx(Menu, { "aria-hidden": true, className: "size-5" }) }), _jsxs(SheetContent, { side: "right", className: "w-80", children: [_jsx(SheetTitle, { className: "sr-only", children: label }), _jsxs("nav", { "aria-label": label, className: "flex flex-col gap-1", children: [_jsx("div", { className: "mb-4 flex items-center", children: _jsx(ProductMark, { id: product.id, name: product.name, pack: product.pack, size: "md" }) }), links.map((link) => (_jsx("a", { href: link.href, "aria-current": link.current ? 'page' : undefined, onClick: () => setOpen(false), className: link.current
+                                    ? 'bg-accent text-accent-foreground focus-visible:border-ring focus-visible:ring-ring flex min-h-11 items-center rounded-lg px-3 text-sm font-medium transition-colors focus-visible:ring-[3px] focus-visible:outline-none'
+                                    : 'text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:border-ring focus-visible:ring-ring flex min-h-11 items-center rounded-lg px-3 text-sm font-medium transition-colors focus-visible:ring-[3px] focus-visible:outline-none', children: link.label }, link.href)))] })] })] }));
+}

package/dist/blocks/site-navbar/mode-toggle.d.ts

@@ -0,0 +1,39 @@
+/** The props the mode toggle takes. */
+export type ModeToggleProps = {
+    /** The accessible name of the control while the page is in light mode. */
+    lightLabel: string;
+    /** The accessible name of the control while the page is in dark mode. */
+    darkLabel: string;
+};
+/**
+ * The light and dark control.
+ *
+ * One button rather than a menu, because the choice has two members and a menu is
+ * the shape a set of six belongs in. The icon states the mode the page is in and
+ * the name states the mode the button will move it to, which is the pairing that
+ * makes the control readable at a glance and unambiguous to a screen reader: a
+ * button labelled "dark mode" that is currently showing a sun is a control whose
+ * label and its state have to be reconciled before it can be used.
+ *
+ * **It reads the mode from the provider rather than from the document.** The class
+ * on `<html>` is the mode, so this could read `document.documentElement.classList`
+ * and would then hold a value the theme itself owns in two places. The provider is
+ * the single writer of that class, and a control that wrote it directly would be a
+ * second writer of a state every other part of the page reads.
+ *
+ * `aria-pressed` is on the control, and it is worth stating why a toggle rather than
+ * a pair of buttons: the button's accessible name changes with the mode, and a
+ * changing name on a pressed control is the combination that leaves a screen reader
+ * announcing "dark mode, pressed" for a page that is in light mode. The name
+ * describes the destination and the pressed state describes the current mode, so the
+ * two never contradict each other because neither claims to be the other.
+ *
+ * **The two labels are keyed to the mode they are shown in, not to the mode they
+ * name.** `lightLabel` is what the control is called while the page is in light
+ * mode, which is the word that sends a reader to dark mode. Reading them the other
+ * way round is the mistake this control shipped with and the test that found it:
+ * a page in light mode announced "Switch to light mode", which is a control that
+ * claims to do the thing the page is already doing.
+ */
+export declare function ModeToggle({ lightLabel, darkLabel }: ModeToggleProps): import("react").JSX.Element;
+//# sourceMappingURL=mode-toggle.d.ts.map

package/dist/blocks/site-navbar/mode-toggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-toggle.d.ts","sourceRoot":"","sources":["../../../src/blocks/site-navbar/mode-toggle.tsx"],"names":[],"mappings":"AAMA,uCAAuC;AACvC,MAAM,MAAM,eAAe,GAAG;IAC5B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,UAAU,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,eAAe,+BAgBpE"}

package/dist/blocks/site-navbar/mode-toggle.js

@@ -0,0 +1,39 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Moon, Sun } from 'lucide-react';
+import { usePrismTheme } from '../../provider/provider.js';
+/**
+ * The light and dark control.
+ *
+ * One button rather than a menu, because the choice has two members and a menu is
+ * the shape a set of six belongs in. The icon states the mode the page is in and
+ * the name states the mode the button will move it to, which is the pairing that
+ * makes the control readable at a glance and unambiguous to a screen reader: a
+ * button labelled "dark mode" that is currently showing a sun is a control whose
+ * label and its state have to be reconciled before it can be used.
+ *
+ * **It reads the mode from the provider rather than from the document.** The class
+ * on `<html>` is the mode, so this could read `document.documentElement.classList`
+ * and would then hold a value the theme itself owns in two places. The provider is
+ * the single writer of that class, and a control that wrote it directly would be a
+ * second writer of a state every other part of the page reads.
+ *
+ * `aria-pressed` is on the control, and it is worth stating why a toggle rather than
+ * a pair of buttons: the button's accessible name changes with the mode, and a
+ * changing name on a pressed control is the combination that leaves a screen reader
+ * announcing "dark mode, pressed" for a page that is in light mode. The name
+ * describes the destination and the pressed state describes the current mode, so the
+ * two never contradict each other because neither claims to be the other.
+ *
+ * **The two labels are keyed to the mode they are shown in, not to the mode they
+ * name.** `lightLabel` is what the control is called while the page is in light
+ * mode, which is the word that sends a reader to dark mode. Reading them the other
+ * way round is the mistake this control shipped with and the test that found it:
+ * a page in light mode announced "Switch to light mode", which is a control that
+ * claims to do the thing the page is already doing.
+ */
+export function ModeToggle({ lightLabel, darkLabel }) {
+    const { mode, toggleMode } = usePrismTheme();
+    const dark = mode === 'dark';
+    return (_jsx("button", { type: "button", "data-slot": "site-navbar-mode-toggle", onClick: toggleMode, "aria-label": dark ? darkLabel : lightLabel, "aria-pressed": dark, className: "border-border bg-card text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:border-ring focus-visible:ring-ring flex size-11 shrink-0 items-center justify-center rounded-full border transition-colors focus-visible:ring-[3px] focus-visible:outline-none", children: dark ? _jsx(Sun, { "aria-hidden": true, className: "size-4" }) : _jsx(Moon, { "aria-hidden": true, className: "size-4" }) }));
+}

package/dist/blocks/site-navbar/navbar-controls.d.ts

@@ -0,0 +1,79 @@
+import type { Mode, PackId } from '../../theming/index.js';
+import type { SearchDialogMessages } from '../../components/ui/search-dialog.js';
+import { type ThemePack } from './theme-menu.js';
+import type { SwitcherProduct } from '../../components/ui/product-switcher.js';
+import type { MobileNavLink } from './mobile-nav.js';
+/** What the control cluster was told to render. Every field is optional. */
+export type NavbarControlsProps = {
+    /** The product whose mark heads the mobile panel. */
+    product: {
+        id: string;
+        name: string;
+        pack?: PackId | null;
+    };
+    /** The site's own destinations, for the panel below the row's threshold. */
+    nav: readonly MobileNavLink[];
+    /** The accessible name of the panel and of its trigger. */
+    navLabel: string;
+    /** The set of sites, or nothing for a site that is the only one. */
+    sites?: readonly SwitcherProduct[];
+    /** The `id` of the site the reader is on. */
+    currentSiteId?: string;
+    /** The accessible name of the sites menu. */
+    sitesLabel?: string;
+    /** Where the search index is served from, or nothing for no search. */
+    search?: {
+        indexUrl: string;
+        label: string;
+        hint?: string;
+        messages: SearchDialogMessages;
+    };
+    /** The packs the chooser offers, or nothing for no chooser. */
+    theme?: {
+        label: string;
+        packs?: readonly ThemePack[];
+    };
+    /** The two names of the light and dark control, or nothing for no toggle. */
+    mode?: {
+        lightLabel: string;
+        darkLabel: string;
+    };
+    /** The two names of the mobile trigger. */
+    mobileLabels: {
+        open: string;
+        close: string;
+    };
+    /** The pack a reader with no stored choice gets. */
+    defaultPack: PackId;
+    /** The mode a reader with no stored choice gets. */
+    defaultMode: Mode;
+    /** A slot for controls the consumer owns, after the ones above. */
+    actions?: React.ReactNode;
+};
+/**
+ * The bar's controls, and the only client boundary in the navbar.
+ *
+ * Everything interactive in a site header is application state: what a reader has
+ * chosen, what is open, what a search found. None of it is a fact the bar can be
+ * told, so none of it can live in a server Component, and the boundary is drawn
+ * here rather than around the whole bar so that the brand lockup and the
+ * navigation stay server rendered. That is the arrangement that lets a site keep
+ * the rest of its page free of client JavaScript, which is the property three of
+ * the five NaniSoft sites are built around.
+ *
+ * **The provider is mounted here and not in the site's root layout, and that is
+ * deliberate.** A provider in the layout would wrap every page and every provider
+ * is context, so a page that never renders a control would still ship it. Mounted
+ * around five buttons, it ships with the buttons and stops there. It is also the
+ * only writer of the two attributes the boot script reads, so a choice made here
+ * is a choice the next page load resolves to the same theme.
+ *
+ * **The order is fixed and it is a reading order, not a preference.** Search first
+ * because it is the only control that answers a question the reader arrived with;
+ * then the two menus, which are choices about where to be rather than about what to
+ * do; then the mode, which is the choice that persists across every site in the
+ * family; then the mobile trigger, which is last because it is the only one that
+ * appears at the narrow end of the range and appears alone there.
+ */
+export declare function NavbarControls(props: NavbarControlsProps): import("react").JSX.Element | null;
+//# sourceMappingURL=navbar-controls.d.ts.map

package/dist/blocks/site-navbar/navbar-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navbar-controls.d.ts","sourceRoot":"","sources":["../../../src/blocks/site-navbar/navbar-controls.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAA;AAI7E,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAA;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAIjD,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG;IAChC,qDAAqD;IACrD,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;IAC3D,4EAA4E;IAC5E,GAAG,EAAE,SAAS,aAAa,EAAE,CAAA;IAC7B,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IAClC,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,MAAM,CAAC,EAAE;QACP,QAAQ,EAAE,MAAM,CAAA;QAChB,KAAK,EAAE,MAAM,CAAA;QACb,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,QAAQ,EAAE,oBAAoB,CAAA;KAC/B,CAAA;IACD,+DAA+D;IAC/D,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;KAAE,CAAA;IACvD,6EAA6E;IAC7E,IAAI,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD,2CAA2C;IAC3C,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7C,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,oDAAoD;IACpD,WAAW,EAAE,IAAI,CAAA;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,sCAsDxD"}

package/dist/blocks/site-navbar/navbar-controls.js

@@ -0,0 +1,40 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ModeToggle } from './mode-toggle.js';
+import { SearchEntry } from './search-entry.js';
+import { SitesMenu } from './sites-menu.js';
+import { ThemeMenu } from './theme-menu.js';
+import { MobileNav } from './mobile-nav.js';
+import { PrismProvider } from '../../provider/provider.js';
+/**
+ * The bar's controls, and the only client boundary in the navbar.
+ *
+ * Everything interactive in a site header is application state: what a reader has
+ * chosen, what is open, what a search found. None of it is a fact the bar can be
+ * told, so none of it can live in a server Component, and the boundary is drawn
+ * here rather than around the whole bar so that the brand lockup and the
+ * navigation stay server rendered. That is the arrangement that lets a site keep
+ * the rest of its page free of client JavaScript, which is the property three of
+ * the five NaniSoft sites are built around.
+ *
+ * **The provider is mounted here and not in the site's root layout, and that is
+ * deliberate.** A provider in the layout would wrap every page and every provider
+ * is context, so a page that never renders a control would still ship it. Mounted
+ * around five buttons, it ships with the buttons and stops there. It is also the
+ * only writer of the two attributes the boot script reads, so a choice made here
+ * is a choice the next page load resolves to the same theme.
+ *
+ * **The order is fixed and it is a reading order, not a preference.** Search first
+ * because it is the only control that answers a question the reader arrived with;
+ * then the two menus, which are choices about where to be rather than about what to
+ * do; then the mode, which is the choice that persists across every site in the
+ * family; then the mobile trigger, which is last because it is the only one that
+ * appears at the narrow end of the range and appears alone there.
+ */
+export function NavbarControls(props) {
+    const { product, nav, navLabel, sites, currentSiteId, sitesLabel, search, theme, mode, mobileLabels, defaultPack, defaultMode, actions, } = props;
+    const hasThemeControls = Boolean(theme) || Boolean(mode);
+    if (!search && !sites && !hasThemeControls && !actions && nav.length === 0)
+        return null;
+    return (_jsx(PrismProvider, { defaultPack: defaultPack, defaultMode: defaultMode, children: _jsxs("div", { className: "ms-auto flex items-center gap-2", children: [search ? (_jsx(SearchEntry, { indexUrl: search.indexUrl, label: search.label, hint: search.hint, messages: search.messages })) : null, sites && sites.length > 0 && sitesLabel ? (_jsx(SitesMenu, { sites: sites, currentId: currentSiteId, label: sitesLabel })) : null, theme ? _jsx(ThemeMenu, { label: theme.label, packs: theme.packs }) : null, mode ? _jsx(ModeToggle, { lightLabel: mode.lightLabel, darkLabel: mode.darkLabel }) : null, actions, nav.length > 0 ? (_jsx(MobileNav, { product: product, links: nav, label: navLabel, openLabel: mobileLabels.open, closeLabel: mobileLabels.close })) : null] }) }));
+}

package/dist/blocks/site-navbar/search-entry.d.ts

@@ -0,0 +1,29 @@
+import type { SearchDialogProps } from '../../components/ui/search-dialog.js';
+/** The props the search entry takes. It is the dialog's props without its close. */
+export type SearchEntryProps = Omit<SearchDialogProps, 'onClose'>;
+/**
+ * The search trigger, and the dialog it opens.
+ *
+ * **The dialog is loaded on the first activation, so neither the dialog nor the
+ * index is part of any page's first paint.** The index is the largest single asset
+ * on a documentation site, and a statically imported dialog is in the module graph
+ * of every page whether or not the reader ever searches. The trigger is a plain
+ * button and the cost of reaching it is one click.
+ *
+ * **The shortcut is Command-K on Apple platforms and Control-K everywhere else,
+ * and it matches rather than replaces.** The listener calls `preventDefault` so the
+ * browser's own find behaviour does not also fire, and it toggles so pressing it
+ * twice leaves the reader where they started. It is registered on the document
+ * rather than on the button, because a shortcut scoped to a control only works once
+ * that control has focus, and the point of a shortcut is to save the reader from
+ * having to find the control first.
+ *
+ * **It is icon-only at every width.** The control is not a destination, so its word
+ * is the first thing that goes when the bar runs out of room, and the row it sits in
+ * is measured rather than assumed: a labelled search control is 55 pixels wider than
+ * an icon in the same slot, and on a site whose navigation is nine Sections that is
+ * the difference between fitting at the authored breakpoint and folding the brand
+ * onto two lines. The accessible name is what replaces the word.
+ */
+export declare function SearchEntry(props: SearchEntryProps): import("react").JSX.Element;
+//# sourceMappingURL=search-entry.d.ts.map

package/dist/blocks/site-navbar/search-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-entry.d.ts","sourceRoot":"","sources":["../../../src/blocks/site-navbar/search-entry.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AAe1E,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BAwClD"}

package/dist/blocks/site-navbar/search-entry.js

@@ -0,0 +1,52 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense, useEffect, useState } from 'react';
+import { Search } from 'lucide-react';
+/**
+ * The dialog, loaded on the first activation.
+ *
+ * Declared at module scope so the import is shared by every search entry on a page
+ * rather than re-issued per call, which is what makes a second search on the same
+ * page instant. `lazy` is React's own rather than a framework's, because this
+ * package imports no framework and has to stay installable in a bundler that is
+ * not the one its own site uses.
+ */
+const SearchDialog = lazy(() => import('../../components/ui/search-dialog.js').then((module) => ({ default: module.SearchDialog })));
+/**
+ * The search trigger, and the dialog it opens.
+ *
+ * **The dialog is loaded on the first activation, so neither the dialog nor the
+ * index is part of any page's first paint.** The index is the largest single asset
+ * on a documentation site, and a statically imported dialog is in the module graph
+ * of every page whether or not the reader ever searches. The trigger is a plain
+ * button and the cost of reaching it is one click.
+ *
+ * **The shortcut is Command-K on Apple platforms and Control-K everywhere else,
+ * and it matches rather than replaces.** The listener calls `preventDefault` so the
+ * browser's own find behaviour does not also fire, and it toggles so pressing it
+ * twice leaves the reader where they started. It is registered on the document
+ * rather than on the button, because a shortcut scoped to a control only works once
+ * that control has focus, and the point of a shortcut is to save the reader from
+ * having to find the control first.
+ *
+ * **It is icon-only at every width.** The control is not a destination, so its word
+ * is the first thing that goes when the bar runs out of room, and the row it sits in
+ * is measured rather than assumed: a labelled search control is 55 pixels wider than
+ * an icon in the same slot, and on a site whose navigation is nine Sections that is
+ * the difference between fitting at the authored breakpoint and folding the brand
+ * onto two lines. The accessible name is what replaces the word.
+ */
+export function SearchEntry(props) {
+    const [open, setOpen] = useState(false);
+    useEffect(() => {
+        const onKeyDown = (event) => {
+            if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+                event.preventDefault();
+                setOpen((value) => !value);
+            }
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, []);
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", "data-slot": "site-navbar-search-trigger", onClick: () => setOpen(true), "aria-label": props.label, "aria-haspopup": "dialog", "aria-expanded": open, className: "border-border bg-card text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:border-ring focus-visible:ring-ring flex size-11 shrink-0 items-center justify-center rounded-full border transition-colors focus-visible:ring-[3px] focus-visible:outline-none", children: _jsx(Search, { "aria-hidden": true, className: "size-4" }) }), open ? (_jsx(Suspense, { fallback: null, children: _jsx(SearchDialog, { ...props, onClose: () => setOpen(false) }) })) : null] }));
+}

package/dist/blocks/site-navbar/site-navbar.d.ts

@@ -0,0 +1,212 @@
+import type { ReactNode } from 'react';
+import { type ProductMarkProps } from '../../components/ui/product-mark.js';
+import type { SwitcherProduct } from '../../components/ui/product-switcher.js';
+import type { SearchDialogMessages } from '../../components/ui/search-dialog.js';
+import type { Mode, PackId } from '../../theming/index.js';
+import type { ThemePack } from './theme-menu.js';
+/**
+ * One destination in the bar's own navigation.
+ *
+ * `href` is required and `current` is opt-in. The bar marks the current page with
+ * `aria-current="page"` rather than with a colour, so a reader who cannot see the
+ * colour still knows where they are.
+ */
+export type SiteNavLink = {
+    /** The text of the link. */
+    label: string;
+    /** Where the link goes. */
+    href: string;
+    /**
+     * Marks this link as the page the reader is on. Set it on the one link whose
+     * destination is the current route.
+     *
+     * A site that renders the bar once in a root layout cannot know its own route,
+     * because a layout is handed no pathname. Such a site passes `currentPath`
+     * instead and the bar resolves the mark in the browser; see that prop.
+     */
+    current?: boolean;
+    /**
+     * Opens the destination in a new browsing context, which defaults the link
+     * relationship to `noopener noreferrer`. Prism does not decide what counts as
+     * external: a cross-origin destination is not by itself a reason to open a tab.
+     */
+    newTab?: boolean;
+};
+/** The search the bar offers, which is a URL rather than an index. */
+export type SiteNavSearch = {
+    /**
+     * Where this site's JSON index is served from, fetched on the first search and
+     * not before. A URL rather than the index itself, because the index is the
+     * largest asset on a documentation site and a value passed as a prop is
+     * serialized into the document of every route that renders the bar.
+     */
+    indexUrl: string;
+    /** The accessible name of the trigger, of the dialog and of its field. */
+    label: string;
+    /** Every sentence the dialog can say, which a Component does not ship. */
+    messages: SearchDialogMessages;
+    /** The text shown before the reader has typed anything. */
+    hint?: string;
+};
+/** The colour chooser the bar offers, and whether it offers one at all. */
+export type SiteNavTheme = {
+    /** The accessible name of the menu, and of the word on its trigger. */
+    label: string;
+    /**
+     * The packs to choose between, each with the word a reader reads for it. Omit it
+     * to offer every published pack under its own capitalised name.
+     *
+     * A product site passes nothing at all rather than passing this, because a site's
+     * ground is a property of the site and a reader who repaints it is a reader on a
+     * page that is no longer the one the site describes.
+     */
+    packs?: readonly ThemePack[];
+};
+/** The light and dark control the bar offers. */
+export type SiteNavMode = {
+    /** The control's accessible name while the page is in dark mode. */
+    lightLabel: string;
+    /** The control's accessible name while the page is in light mode. */
+    darkLabel: string;
+};
+/** The two names of the control that opens the navigation below the row. */
+export type SiteNavMobileLabels = {
+    /** The word on the trigger while the panel is closed. */
+    open: string;
+    /** The word on the trigger while the panel is open. */
+    close: string;
+};
+/** The props a SiteNavbar takes. */
+export type SiteNavbarProps = {
+    /**
+     * The product this bar belongs to: the id, name and pack its `ProductMark` is
+     * drawn from, and the mark that heads the mobile panel. The bar renders the mark
+     * itself rather than a slot, because a bar whose brand lockup is a slot is a bar
+     * every consumer has to reimplement.
+     */
+    product: Pick<ProductMarkProps, 'id' | 'name' | 'pack'>;
+    /** Where the brand lockup goes. @defaultValue '/' */
+    homeHref?: string;
+    /**
+     * The pack a reader who has never chosen a pack gets. It is passed to the theme
+     * runtime rather than read from the document, so a site states its own default in
+     * one place and the control and the page cannot disagree about it.
+     */
+    defaultPack: PackId;
+    /**
+     * The mode a reader who has never chosen gets. Required for the same reason
+     * `defaultPack` is, and because a toggle with no stated starting mode is a
+     * control whose icon is a guess until it is pressed once.
+     */
+    defaultMode: Mode;
+    /** This site's own destinations. Omit for a bar that carries only the lockup. */
+    nav?: readonly SiteNavLink[];
+    /**
+     * The accessible name of the site's navigation. Required, and required rather
+     * than defaulted because it is a word a reader hears: a Block that ships no copy
+     * ships no reader-facing copy either.
+     */
+    navLabel: string;
+    /**
+     * The route the reader is on, for a site that renders the bar once in a root
+     * layout and therefore cannot mark the current link itself.
+     *
+     * A site that composes the bar per page, which is the arrangement that keeps the
+     * current link server rendered, sets `current` on the one link instead and leaves
+     * this off. The two are alternatives rather than layers, and a site that set both
+     * would have two answers to which link is current.
+     */
+    currentPath?: string;
+    /**
+     * The set of sites to move between, rendered as a menu. Omit it on a site that is
+     * the only one; a set of one is a menu with a single item and no reason to exist.
+     */
+    sites?: readonly SwitcherProduct[];
+    /** The `id` of the site the reader is on, marked in the menu. */
+    currentSiteId?: string;
+    /**
+     * The accessible name of the sites menu. Required whenever `sites` is passed, for
+     * the same reason `navLabel` is.
+     */
+    sitesLabel?: string;
+    /** The search the bar offers, or nothing for no search. */
+    search?: SiteNavSearch;
+    /** The colour chooser the bar offers, or nothing for no chooser. */
+    theme?: SiteNavTheme;
+    /** The light and dark control the bar offers, or nothing for no toggle. */
+    mode?: SiteNavMode;
+    /**
+     * The two names of the mobile trigger, which is a round icon with no visible
+     * word. Required rather than defaulted, because a default would be a sentence
+     * this Block ships about a product that is not the caller's, and because a bar
+     * that renders an unlabelled round control below its own threshold has a
+     * keyboard reader reaching for something it cannot name.
+     */
+    mobileLabels: SiteNavMobileLabels;
+    /**
+     * A slot for controls the product owns, after the ones this bar composes. A slot
+     * rather than a prop, because an account menu and a sign-in link are application
+     * state and neither is a fact a bar can be told.
+     */
+    actions?: ReactNode;
+    /**
+     * Keeps the bar at the top of the viewport as the page scrolls. On by default,
+     * because the bar is how a reader leaves the page they are on, and a bar that
+     * scrolls away takes that with it on exactly the long pages a reader needs it.
+     */
+    sticky?: boolean;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * The bar at the top of a product site, with the controls a reader needs on every
+ * page of it.
+ *
+ * It is `SiteHeader` plus the four controls that were missing from it, and it
+ * exists because all five NaniSoft sites had the same bar and every one of them had
+ * written the missing four separately: Prism's own site had search and a colour
+ * chooser and no way to reach its four siblings, and each of the four had a row of
+ * product marks where a menu belongs and no search, no mode control and no
+ * navigation at all below the width its own row stopped fitting. Five bars, one
+ * design language, and no two of them the same bar.
+ *
+ * Every string is a prop and the Block ships none. There is no site name, no
+ * default navigation, no "Search", no list of packs and no list of sites: a bar
+ * that hardcoded any of them would hand every consumer a claim about a product that
+ * is not theirs, which is the defect this Block exists to remove. The one piece of
+ * copy it derives is a pack's own name from its own identifier, and only when the
+ * caller names none.
+ *
+ * **The bar is one flex row that wraps, and it fits by measurement.** The brand
+ * lockup and the controls hold their ends, the navigation sits in the middle, and
+ * the navigation row is hidden below `lg` where the panel takes over. The brand
+ * lockup is the one element that never wraps: a wordmark broken across two lines is
+ * not a wordmark, and it is also the one element that yields rather than pushing a
+ * control off the right edge of the viewport, which is the harm a header-fit test
+ * exists to catch.
+ *
+ * **The navigation is a `nav` and the sites menu is a second landmark of its own.**
+ * A reader who navigates by landmark needs two regions rather than one region with
+ * two lists in it, and the two sets are different places: one is where this site
+ * goes and the other is where the family goes. The controls are not a region at
+ * all, because they are whatever this bar composed plus whatever the consumer put
+ * in `actions`, and wrapping them in a landmark would be a claim about content the
+ * Block does not own.
+ *
+ * The bottom hairline is `border-border`, so the bar separates from the page by a
+ * line rather than by a fill change, which is how every surface in this system is
+ * separated: in the base pack `background` and `card` resolve to the same value, so
+ * a fill is not available as a separator. The bar is translucent and blurred, so the
+ * content scrolling under it is legible through it rather than hidden by it, which
+ * is the reason a sticky bar can be translucent at all.
+ *
+ * **It is a server Component with one client island inside it.** The lockup and the
+ * navigation are rendered on the server and ship no JavaScript; the controls are a
+ * single boundary, because a control's state is a reader's state. A site that
+ * passes no `search`, `sites`, `theme`, `mode` or `nav` renders the whole bar on the
+ * server and ships none, which is the arrangement a static site wants and the reason
+ * those props are optional rather than required.
+ */
+export declare function SiteNavbar({ product, homeHref, defaultPack, defaultMode, nav, navLabel, currentPath, sites, currentSiteId, sitesLabel, search, theme, mode, mobileLabels, actions, sticky, className, }: SiteNavbarProps): import("react").JSX.Element;
+export default SiteNavbar;
+//# sourceMappingURL=site-navbar.d.ts.map

package/dist/blocks/site-navbar/site-navbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-navbar.d.ts","sourceRoot":"","sources":["../../../src/blocks/site-navbar/site-navbar.tsx"],"names":[],"mappings":"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"}