@nanisoft/prism-ui 0.10.2 → 0.15.0

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

@@ -0,0 +1,246 @@
+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.
+     *
+     * `false` is honoured: the bar is then part of the flow and scrolls away with the
+     * page. It was accepted and ignored until this release, so a site that passed it
+     * was given the sticky bar it had asked not to have, and `SiteHeader` has always
+     * applied it the other way round.
+     */
+    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 opaque, and it used not to be.** It carried `bg-background/80` and
+ * `backdrop-blur`, so the page showed through it blurred. A backdrop filter is
+ * evaluated against everything painted behind the element, and this element is a
+ * full-viewport-width sticky bar, so on a scrolling page the browser re-sampled and
+ * re-blurred that backdrop on every frame of the scroll, on every page of every site
+ * that composes this bar. It is the most expensive thing in the document for the
+ * least visible return: the twenty percent of the page showing through a bar that
+ * carries its own labels on top of it is not what a reader looks at.
+ *
+ * **The blur is not kept behind a capability check, because a capability check does
+ * not pay for it.** `@supports (backdrop-filter: blur(1px))` is false only in a
+ * browser that would have dropped the declaration and composited no no-op, and it is
+ * true in every browser that does the expensive thing, so it changes no reader's
+ * cost. It would also leave a third outcome in the world, and the worst one: a bar
+ * that is a flat eighty percent veil with unblurred text passing under it.
+ *
+ * What replaces the pair is `bg-background`, which is what `SiteHeader` already
+ * ships, and the reason this is legible rather than merely cheaper is that an opaque
+ * bar makes its own contrast the token pair the contrast gate already holds:
+ * `muted-foreground` on `background` in every pack and in both modes, with nothing
+ * composited between the ink and the ground. A `/80` background has no such pair at
+ * all, because the colour under it is a decision the reader's scroll position makes
+ * and no token in this system describes it.
+ *
+ * `will-change` is absent and stays absent. A `backdrop-filter` is promoted to its
+ * own layer by the browser when it has something to filter, so `will-change` on the
+ * bar would only keep that layer alive: nothing on this bar animates, there is no
+ * frame coming for the hint to be ready for, and a hint applied at rest is a hint
+ * with no release. This package ships no `will-change` anywhere, and the bar is not
+ * the place to start one.
+ *
+ * **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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"}

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

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ProductMark } from '../../components/ui/product-mark.js';
+import { cn } from '../../lib/utils.js';
+import { NavbarControls } from './navbar-controls.js';
+/**
+ * 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 opaque, and it used not to be.** It carried `bg-background/80` and
+ * `backdrop-blur`, so the page showed through it blurred. A backdrop filter is
+ * evaluated against everything painted behind the element, and this element is a
+ * full-viewport-width sticky bar, so on a scrolling page the browser re-sampled and
+ * re-blurred that backdrop on every frame of the scroll, on every page of every site
+ * that composes this bar. It is the most expensive thing in the document for the
+ * least visible return: the twenty percent of the page showing through a bar that
+ * carries its own labels on top of it is not what a reader looks at.
+ *
+ * **The blur is not kept behind a capability check, because a capability check does
+ * not pay for it.** `@supports (backdrop-filter: blur(1px))` is false only in a
+ * browser that would have dropped the declaration and composited no no-op, and it is
+ * true in every browser that does the expensive thing, so it changes no reader's
+ * cost. It would also leave a third outcome in the world, and the worst one: a bar
+ * that is a flat eighty percent veil with unblurred text passing under it.
+ *
+ * What replaces the pair is `bg-background`, which is what `SiteHeader` already
+ * ships, and the reason this is legible rather than merely cheaper is that an opaque
+ * bar makes its own contrast the token pair the contrast gate already holds:
+ * `muted-foreground` on `background` in every pack and in both modes, with nothing
+ * composited between the ink and the ground. A `/80` background has no such pair at
+ * all, because the colour under it is a decision the reader's scroll position makes
+ * and no token in this system describes it.
+ *
+ * `will-change` is absent and stays absent. A `backdrop-filter` is promoted to its
+ * own layer by the browser when it has something to filter, so `will-change` on the
+ * bar would only keep that layer alive: nothing on this bar animates, there is no
+ * frame coming for the hint to be ready for, and a hint applied at rest is a hint
+ * with no release. This package ships no `will-change` anywhere, and the bar is not
+ * the place to start one.
+ *
+ * **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 function SiteNavbar({ product, homeHref = '/', defaultPack, defaultMode, nav, navLabel, currentPath, sites, currentSiteId, sitesLabel, search, theme, mode, mobileLabels, actions, sticky = true, className, }) {
+    const links = nav ?? [];
+    const isCurrent = (link) => link.current ?? (currentPath !== undefined && link.href === currentPath);
+    return (_jsx("header", { "data-slot": "site-navbar", className: cn('border-border bg-background w-full border-b', sticky && 'sticky top-0 z-20', className), children: _jsxs("div", { className: "mx-auto flex h-14 w-full max-w-page items-center gap-2 px-6", children: [_jsx("a", { href: homeHref, className: "focus-visible:border-ring focus-visible:ring-ring shrink-0 rounded-sm focus-visible:ring-[3px] focus-visible:outline-none", children: _jsx(ProductMark, { id: product.id, name: product.name, pack: product.pack, size: "sm" }) }), links.length > 0 ? (_jsx("nav", { "aria-label": navLabel, className: "hidden items-center lg:flex", children: links.map((link) => (_jsx("a", { href: link.href, "aria-current": isCurrent(link) ? 'page' : undefined, rel: link.newTab ? 'noopener noreferrer' : undefined, target: link.newTab ? '_blank' : undefined, className: isCurrent(link)
+                            ? 'bg-accent text-accent-foreground focus-visible:border-ring focus-visible:ring-ring rounded-md px-2 py-1.5 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 rounded-md px-2 py-1.5 text-sm font-medium transition-colors focus-visible:ring-[3px] focus-visible:outline-none', children: link.label }, link.href))) })) : null, _jsx(NavbarControls, { product: product, nav: links.map((link) => ({ ...link, current: isCurrent(link) })), navLabel: navLabel, sites: sites, currentSiteId: currentSiteId, sitesLabel: sitesLabel, search: search, theme: theme, mode: mode, mobileLabels: mobileLabels, defaultPack: defaultPack, defaultMode: defaultMode, actions: actions })] }) }));
+}
+export default SiteNavbar;

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

@@ -0,0 +1,40 @@
+import type { SwitcherProduct } from '../../components/ui/product-switcher.js';
+/** The props the sites menu takes. */
+export type SitesMenuProps = {
+    /** The set to move between, in the order a reader should meet it. */
+    sites: readonly SwitcherProduct[];
+    /** The `id` of the site the reader is on. Marked `aria-current="page"`. */
+    currentId?: string;
+    /** The accessible name of the menu and of its trigger. A word a reader hears. */
+    label: string;
+};
+/**
+ * The set of sites, as a menu.
+ *
+ * Prism's own site had no way to reach its four siblings and each of the four had
+ * written its own way to reach the other four, so a reader on one site had to know
+ * that four other hosts existed before they could be found. This is the one control
+ * that states the set, and every site that composes it states the same five.
+ *
+ * **The trigger is an icon rather than a word, for the same reason Prism's search
+ * trigger is.** The bar carries the brand, the site's own destinations and a row of
+ * controls, and at the width the row is authored to fit, a fourth labelled control
+ * is the difference between fitting and folding the brand onto two lines. A control
+ * that is not a destination is the right place to spend that width, because a
+ * reader who does not recognise the icon is losing a word rather than a route.
+ *
+ * **The items are links, not commands, and the current one is marked rather than
+ * styled.** A menu item that navigated was a command wearing a link's clothes, and
+ * the cost of that is a reader with a middle-click expecting a new tab and getting
+ * nothing. `aria-current="page"` on the member the reader is on is the state a
+ * screen reader announces, and it is why the set is a list of anchors inside a menu
+ * rather than a `ProductSwitcher` row: the switcher renders every mark at once and
+ * this renders them on demand, which is what makes room for the icon-only trigger.
+ *
+ * Each item carries the site's own `ProductMark`, so a reader recognises a
+ * destination by its colour before they read its name, and the mark is where a
+ * pack boundary is safe: it is a fully rounded disc, so repointing the pack's corner
+ * radius beneath it moves nothing about its shape.
+ */
+export declare function SitesMenu({ sites, currentId, label }: SitesMenuProps): import("react").JSX.Element | null;
+//# sourceMappingURL=sites-menu.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sites-menu.d.ts","sourceRoot":"","sources":["../../../src/blocks/site-navbar/sites-menu.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAA;AAE3E,sCAAsC;AACtC,MAAM,MAAM,cAAc,GAAG;IAC3B,qEAAqE;IACrE,KAAK,EAAE,SAAS,eAAe,EAAE,CAAA;IACjC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,cAAc,sCAmDpE"}

package/dist/blocks/site-navbar/sites-menu.js

@@ -0,0 +1,48 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { LayoutGrid } from 'lucide-react';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuTrigger, } from '../../components/ui/dropdown-menu.js';
+import { ProductMark } from '../../components/ui/product-mark.js';
+/**
+ * The set of sites, as a menu.
+ *
+ * Prism's own site had no way to reach its four siblings and each of the four had
+ * written its own way to reach the other four, so a reader on one site had to know
+ * that four other hosts existed before they could be found. This is the one control
+ * that states the set, and every site that composes it states the same five.
+ *
+ * **The trigger is an icon rather than a word, for the same reason Prism's search
+ * trigger is.** The bar carries the brand, the site's own destinations and a row of
+ * controls, and at the width the row is authored to fit, a fourth labelled control
+ * is the difference between fitting and folding the brand onto two lines. A control
+ * that is not a destination is the right place to spend that width, because a
+ * reader who does not recognise the icon is losing a word rather than a route.
+ *
+ * **The items are links, not commands, and the current one is marked rather than
+ * styled.** A menu item that navigated was a command wearing a link's clothes, and
+ * the cost of that is a reader with a middle-click expecting a new tab and getting
+ * nothing. `aria-current="page"` on the member the reader is on is the state a
+ * screen reader announces, and it is why the set is a list of anchors inside a menu
+ * rather than a `ProductSwitcher` row: the switcher renders every mark at once and
+ * this renders them on demand, which is what makes room for the icon-only trigger.
+ *
+ * Each item carries the site's own `ProductMark`, so a reader recognises a
+ * destination by its colour before they read its name, and the mark is where a
+ * pack boundary is safe: it is a fully rounded disc, so repointing the pack's corner
+ * radius beneath it moves nothing about its shape.
+ */
+export function SitesMenu({ sites, currentId, label }) {
+    if (sites.length === 0)
+        return null;
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { "data-slot": "site-navbar-sites-trigger", "aria-label": label, className: "border-border bg-card text-muted-foreground hover:bg-accent hover:text-accent-foreground data-[popup-open]:bg-accent data-[popup-open]:text-accent-foreground size-11 shrink-0 rounded-full border", children: _jsx(LayoutGrid, { "aria-hidden": true, className: "size-4" }) }), _jsx(DropdownMenuContent, { align: "end", sideOffset: 8, className: "min-w-56", children: _jsxs(DropdownMenuGroup, { children: [_jsx(DropdownMenuLabel, { children: label }), sites.map((site) => {
+                            const current = site.id === currentId;
+                            return (_jsx(DropdownMenuItem, { 
+                                /*
+                                 * Rendered AS the link rather than wrapping one. A focusable menu
+                                 * item with an anchor inside it is two tab stops for one row, and a
+                                 * reader who middle-clicks a row that only looks like a link gets no
+                                 * new tab and no way to tell that the row was a link at all.
+                                 */
+                                render: _jsx("a", { href: site.href, target: "_blank", rel: "noopener noreferrer", "aria-current": current ? 'page' : undefined, "data-current": current ? 'true' : undefined }), children: _jsx(ProductMark, { id: site.id, name: site.name, pack: site.pack, size: "sm" }) }, site.id));
+                        })] }) })] }));
+}

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

@@ -0,0 +1,47 @@
+import { type PackId } from '../../theming/index.js';
+/** One pack the menu offers, and the word a reader reads for it. */
+export type ThemePack = {
+    /** The pack identifier, which is a token rather than a string. */
+    id: PackId;
+    /** The pack's own name. */
+    name: string;
+};
+/** The props the theme menu takes. */
+export type ThemeMenuProps = {
+    /** The packs to choose between. Defaults to every published pack. */
+    packs?: readonly ThemePack[];
+    /** The accessible name of the menu, and of the word on its trigger. */
+    label: string;
+};
+/**
+ * The pack chooser, as a menu.
+ *
+ * **The swatch is a pack boundary rather than a literal colour, and that is the
+ * whole of how this component avoids a runtime token read.** The obvious
+ * implementation reads each pack's compiled `--primary` and paints it as an inline
+ * style, which is what Prism's own documentation site did. A token resolved at
+ * runtime does not follow the cascade, so the dot holding a pack's colour is right
+ * in one mode and stale in the other, and it is the exact defect the
+ * `runtime-token-read` law names: the disagreement is between what is painted and
+ * what the cascade says, and only a program that reads the read can see it.
+ *
+ * `data-pack` on a span carrying `bg-primary` resolves through the cascade, holds
+ * every pack at once, and ships no client code. The boundary is safe on this shape
+ * and only this shape: a pack repoints its own corner radius as well as its colour,
+ * so a boundary on anything that is not fully rounded would quietly restyle that
+ * element's corners. A disc is fully rounded, so the radius axis is a no-op here.
+ *
+ * **It is a radio group rather than a list of commands.** One pack is active at a
+ * time out of a known set, which is what a radio group is for, and it is what
+ * gives the menu its announced state: a reader who opens the chooser hears which
+ * of the packs is in use, where a list of commands would announce six buttons and
+ * leave them to work out which one took effect.
+ *
+ * **The trigger shows the active pack's name, and drops it below `sm`.** Six
+ * options side by side need about 380 pixels, which is why this is a menu at all
+ * rather than a row of pills, and the name on the trigger is the one place the
+ * choice stays visible once the menu is closed. It is hidden rather than shortened
+ * below `sm` because a truncated pack name is a word that names nothing.
+ */
+export declare function ThemeMenu({ packs, label }: ThemeMenuProps): import("react").JSX.Element | null;
+//# sourceMappingURL=theme-menu.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"theme-menu.d.ts","sourceRoot":"","sources":["../../../src/blocks/site-navbar/theme-menu.tsx"],"names":[],"mappings":"AAcA,OAAO,EAAS,KAAK,MAAM,EAAE,MAAM,eAAe,CAAA;AAElD,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG;IACtB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAA;IACV,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,sCAAsC;AACtC,MAAM,MAAM,cAAc,GAAG;IAC3B,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,cAAc,sCA8CzD"}

package/dist/blocks/site-navbar/theme-menu.js

@@ -0,0 +1,55 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronDown } from 'lucide-react';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuTrigger, } from '../../components/ui/dropdown-menu.js';
+import { usePrismTheme } from '../../provider/provider.js';
+import { PACKS } from '../../theming/index.js';
+/**
+ * The name a pack is offered under when the caller names none.
+ *
+ * Capitalising the identifier is enough rather than a table, because the pack
+ * vocabulary is closed and every id in it is the lowercased form of its own name.
+ * The alternative is a lookup that could fall through for a pack added after this
+ * line was written, and a fallthrough here is a menu item with no readable name.
+ */
+function nameOf(pack) {
+    return pack.charAt(0).toUpperCase() + pack.slice(1);
+}
+/**
+ * The pack chooser, as a menu.
+ *
+ * **The swatch is a pack boundary rather than a literal colour, and that is the
+ * whole of how this component avoids a runtime token read.** The obvious
+ * implementation reads each pack's compiled `--primary` and paints it as an inline
+ * style, which is what Prism's own documentation site did. A token resolved at
+ * runtime does not follow the cascade, so the dot holding a pack's colour is right
+ * in one mode and stale in the other, and it is the exact defect the
+ * `runtime-token-read` law names: the disagreement is between what is painted and
+ * what the cascade says, and only a program that reads the read can see it.
+ *
+ * `data-pack` on a span carrying `bg-primary` resolves through the cascade, holds
+ * every pack at once, and ships no client code. The boundary is safe on this shape
+ * and only this shape: a pack repoints its own corner radius as well as its colour,
+ * so a boundary on anything that is not fully rounded would quietly restyle that
+ * element's corners. A disc is fully rounded, so the radius axis is a no-op here.
+ *
+ * **It is a radio group rather than a list of commands.** One pack is active at a
+ * time out of a known set, which is what a radio group is for, and it is what
+ * gives the menu its announced state: a reader who opens the chooser hears which
+ * of the packs is in use, where a list of commands would announce six buttons and
+ * leave them to work out which one took effect.
+ *
+ * **The trigger shows the active pack's name, and drops it below `sm`.** Six
+ * options side by side need about 380 pixels, which is why this is a menu at all
+ * rather than a row of pills, and the name on the trigger is the one place the
+ * choice stays visible once the menu is closed. It is hidden rather than shortened
+ * below `sm` because a truncated pack name is a word that names nothing.
+ */
+export function ThemeMenu({ packs, label }) {
+    const { pack, setPack } = usePrismTheme();
+    const options = packs ?? PACKS.map((id) => ({ id, name: nameOf(id) }));
+    const active = options.find((option) => option.id === pack) ?? options[0];
+    if (!active)
+        return null;
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { "data-slot": "site-navbar-theme-trigger", "aria-label": `${label}: ${active.name}`, className: "border-border bg-card text-foreground hover:bg-accent hover:text-accent-foreground data-[popup-open]:bg-accent data-[popup-open]:text-accent-foreground h-11 shrink-0 gap-2 rounded-full border pr-2.5 pl-3", children: [_jsx("span", { "data-pack": active.id, "aria-hidden": true, className: "border-border/60 bg-primary size-3.5 rounded-full border" }), _jsx("span", { className: "hidden sm:inline", children: active.name }), _jsx(ChevronDown, { "aria-hidden": true, className: "size-3.5" })] }), _jsx(DropdownMenuContent, { align: "end", sideOffset: 8, className: "min-w-52", children: _jsxs(DropdownMenuRadioGroup, { value: active.id, onValueChange: (value) => setPack(value), children: [_jsx(DropdownMenuLabel, { children: label }), options.map((option) => (_jsxs(DropdownMenuRadioItem, { value: option.id, closeOnClick: true, children: [_jsx("span", { "data-pack": option.id, "aria-hidden": true, className: "border-border/60 bg-primary size-3.5 shrink-0 rounded-full border" }), _jsx("span", { className: "flex-1", children: option.name })] }, option.id)))] }) })] }));
+}

package/dist/blocks/spec-table-01/index.d.ts

@@ -0,0 +1,3 @@
+export { SpecTable01, default } from './spec-table.js';
+export type { SpecTable01Group, SpecTable01Props, SpecTable01Row, SpecTable01Summary, SpecTableCell, SpecTableColumn, } from './spec-table.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/spec-table-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/spec-table-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAKnD,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,eAAe,GAChB,MAAM,cAAc,CAAA"}

package/dist/blocks/spec-table-01/index.js

@@ -0,0 +1 @@
+export { SpecTable01, default } from './spec-table.js';