@nanisoft/prism-ui 0.10.2 → 0.13.0

package/dist/live/run-stream-01/run-stream.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Who produced an event, as a closed set.
+ *
+ * The four are the ones an agent run actually has, and they are closed because the
+ * treatment is not the caller's: a role is a slot for a colour, a mark and an
+ * announcement, and a free-text role would be a string with no rendering behind it.
+ * The **words** are still the caller's, in `message`. Prism owns which role looks
+ * like what, and ships none of the labels.
+ */
+export type RunEventRole = 'agent' | 'tool' | 'system' | 'error';
+/** One event, as the surface receives it. */
+export type RunEvent = {
+    /** Stable across re-renders, so an event is never re-announced because its index moved. */
+    id: string;
+    role: RunEventRole;
+    /** Epoch milliseconds, used for order and for the elapsed column. */
+    at: number;
+    /** What happened, in the consumer's words. */
+    message: string;
+    /** Optional second line: a tool's arguments, a path, a code. */
+    detail?: string;
+};
+/** Where a run has got to. The tiers are Prism's; the words beside them are the caller's. */
+export type RunStatus = 'queued' | 'running' | 'waiting' | 'done' | 'failed';
+/**
+ * How the surface receives events.
+ *
+ * The consumer owns the socket, the transport and the persistence, so this is a
+ * function it supplies rather than a connection Prism opens. It is called once on
+ * mount and must return an unsubscribe, which is what makes a WebSocket, an
+ * `EventSource`, a polling timer or a test's own array all the same shape to the
+ * surface. Nothing here knows which one it got.
+ */
+export type RunSubscribe = (emit: (event: RunEvent) => void) => () => void;
+export type RunStream01Props = {
+    /**
+     * Called once to begin receiving, and again whenever `resubscribeKey` changes.
+     * Must return an unsubscribe; the surface calls it on unmount and before
+     * re-subscribing, so a consumer that returns nothing leaks its connection.
+     */
+    subscribe: RunSubscribe;
+    /**
+     * Which run this surface is showing, and the reset lever.
+     *
+     * Changing it **clears the log and reseeds it from `initial`**, as well as
+     * tearing the subscription down and opening a new one. A run is identified by
+     * whatever the consumer already uses to identify it, so a second run in the same
+     * surface is a new subscription rather than two consumers of one, and it is a new
+     * log rather than the old run's events with the new run's appended, which is the
+     * reading a reader would not distinguish from one run being longer than it was.
+     */
+    resubscribeKey?: string | number;
+    /**
+     * The events already known when this run is opened, so a surface opened mid-run
+     * is not blank. Oldest first.
+     *
+     * Read when the run is opened, and again whenever `resubscribeKey` changes. It is
+     * **not** read on every render: a prop that looked like the current event list
+     * and quietly seeded only once would be a trap, and a prop that re-seeded on
+     * every render would discard the stream. This seeds, and the stream takes over.
+     */
+    initial?: readonly RunEvent[];
+    /** Where the run has got to. */
+    status?: RunStatus;
+    /** The word beside the status. Required when a status is passed. */
+    statusLabel?: string;
+    /** Optional label above the surface's heading. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The surface's heading. Omit it for one composed under its own. */
+    title?: string;
+    /** One or two sentences under the heading. */
+    description?: string;
+    /** What the surface says when it holds no events yet. */
+    emptyLabel?: string;
+    /**
+     * The accessible name of the scrolling region.
+     *
+     * Required, because `ScrollArea` requires it and the reason is the right one: a
+     * scroll region with no name is announced as a group of focusable nothing, and a
+     * keyboard reader who tabs into it cannot tell what is in it or what is past the
+     * edge. The name is the consumer's word, as every other word here is.
+     */
+    eventsLabel: string;
+    /** Announced to assistive technology as events arrive. */
+    liveLabel?: string;
+    /** How many events to keep. Older events fall off the top. */
+    limit?: number;
+    className?: string;
+};
+/**
+ * The event log of a run, receiving events as they arrive.
+ *
+ * **This is the first surface in the package that is a client Component**, and that
+ * is the whole of what the fourth Kind is for. A Block takes its content as props,
+ * so it is rendered once and re-rendered when the consumer's framework decides; a
+ * `live` surface's content changes **without a navigation event**, which no amount
+ * of prop-passing expresses. So this owns a subscription and the accumulation
+ * behind it.
+ *
+ * **Prism owns the surface, the consumer owns the transport.** `subscribe` is a
+ * function the consumer supplies and a function it tears down. There is no socket
+ * in this file, no endpoint, no retry policy and no persistence, and there is no
+ * provider to mount: a consumer that already has a connection passes it in, and one
+ * that does not has not acquired a client runtime by importing this.
+ *
+ * **The events are kept sorted by `at`, not by arrival.** A consumer's transport
+ * decides when a message is delivered, and a reconnect can deliver an older event
+ * after a newer one. Sorting on arrival would put a run's own history out of order
+ * in exactly the case where a reader is most likely to be watching. Ties break on
+ * `id`, so the order is total and two runs of the same suite render the same log.
+ *
+ * **New events are announced once, politely, and the log itself is not a live
+ * region.** Announcing a growing list would make a screen reader read the whole run
+ * again on every arrival, which is the failure a live region on a list guarantees.
+ * `LiveRegion` carries the newest event's message alone, and the log is an ordinary
+ * scrollable list a reader can move through at their own pace.
+ *
+ * `limit` bounds what is held, because an agent run can produce thousands of events
+ * and a surface that grows without bound is a surface that eventually stops
+ * repainting. Older events fall off the top, which is the direction a reader wants:
+ * the run's beginning is the part they can scroll back to in another surface.
+ */
+export declare function RunStream01({ subscribe, resubscribeKey, initial, status, statusLabel, eyebrow, title, description, emptyLabel, eventsLabel, liveLabel, limit, className, }: RunStream01Props): import("react").JSX.Element;
+export default RunStream01;
+//# sourceMappingURL=run-stream.d.ts.map

package/dist/live/run-stream-01/run-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-stream.d.ts","sourceRoot":"","sources":["../../../src/live/run-stream-01/run-stream.tsx"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEhE,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,GAAG;IACrB,2FAA2F;IAC3F,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,YAAY,CAAA;IAClB,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,6FAA6F;AAC7F,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;AAE1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,SAAS,EAAE,YAAY,CAAA;IACvB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC7B,gCAAgC;IAChC,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,EAC1B,SAAS,EACT,cAAc,EACd,OAAO,EACP,MAAM,EACN,WAAW,EACX,OAAO,EACP,KAAK,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,KAAW,EACX,SAAS,GACV,EAAE,gBAAgB,+BA8HlB;AAED,eAAe,WAAW,CAAA"}

package/dist/live/run-stream-01/run-stream.js

@@ -0,0 +1,111 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { LiveRegion } from '../../components/ui/live-region.js';
+import { ScrollArea } from '../../components/ui/scroll-area.js';
+import { cn } from '../../lib/utils.js';
+/** The ink each role is stated in, and the tick beside it. */
+const ROLE_INK = {
+    agent: 'text-foreground',
+    tool: 'text-foreground',
+    system: 'text-muted-foreground',
+    error: 'text-destructive',
+};
+/** The tick each role draws, so the four are told apart without relying on colour. */
+const ROLE_MARK = {
+    agent: '●',
+    tool: 'â–¸',
+    system: '·',
+    error: '×',
+};
+const STATUS_INK = {
+    queued: 'text-muted-foreground',
+    running: 'text-foreground',
+    waiting: 'text-warning',
+    done: 'text-success',
+    failed: 'text-destructive',
+};
+/** The one source of truth for order, so a late event with an earlier `at` sorts there. */
+const byTimeThenId = (a, b) => a.at - b.at || a.id.localeCompare(b.id);
+/**
+ * The event log of a run, receiving events as they arrive.
+ *
+ * **This is the first surface in the package that is a client Component**, and that
+ * is the whole of what the fourth Kind is for. A Block takes its content as props,
+ * so it is rendered once and re-rendered when the consumer's framework decides; a
+ * `live` surface's content changes **without a navigation event**, which no amount
+ * of prop-passing expresses. So this owns a subscription and the accumulation
+ * behind it.
+ *
+ * **Prism owns the surface, the consumer owns the transport.** `subscribe` is a
+ * function the consumer supplies and a function it tears down. There is no socket
+ * in this file, no endpoint, no retry policy and no persistence, and there is no
+ * provider to mount: a consumer that already has a connection passes it in, and one
+ * that does not has not acquired a client runtime by importing this.
+ *
+ * **The events are kept sorted by `at`, not by arrival.** A consumer's transport
+ * decides when a message is delivered, and a reconnect can deliver an older event
+ * after a newer one. Sorting on arrival would put a run's own history out of order
+ * in exactly the case where a reader is most likely to be watching. Ties break on
+ * `id`, so the order is total and two runs of the same suite render the same log.
+ *
+ * **New events are announced once, politely, and the log itself is not a live
+ * region.** Announcing a growing list would make a screen reader read the whole run
+ * again on every arrival, which is the failure a live region on a list guarantees.
+ * `LiveRegion` carries the newest event's message alone, and the log is an ordinary
+ * scrollable list a reader can move through at their own pace.
+ *
+ * `limit` bounds what is held, because an agent run can produce thousands of events
+ * and a surface that grows without bound is a surface that eventually stops
+ * repainting. Older events fall off the top, which is the direction a reader wants:
+ * the run's beginning is the part they can scroll back to in another surface.
+ */
+export function RunStream01({ subscribe, resubscribeKey, initial, status, statusLabel, eyebrow, title, description, emptyLabel, eventsLabel, liveLabel, limit = 500, className, }) {
+    /**
+     * The run's log, held against the key that produced it.
+     *
+     * Adjusting state during render when the key changes is React's documented
+     * pattern for "a prop changed, start over", and it is the right one here: the
+     * alternative is an effect, and an effect that clears the log runs *after* a
+     * render, so the surface would paint one frame holding the previous run's events
+     * under the new run's heading.
+     */
+    const [newest, setNewest] = useState(undefined);
+    const [run, setRun] = useState(() => ({
+        key: resubscribeKey,
+        events: [...(initial ?? [])].sort(byTimeThenId),
+    }));
+    if (run.key !== resubscribeKey) {
+        setRun({ key: resubscribeKey, events: [...(initial ?? [])].sort(byTimeThenId) });
+        // The announcement is cleared with the log it announced, so a run switch does
+        // not leave the previous run's last event in the live region saying so.
+        setNewest(undefined);
+    }
+    const events = run.events;
+    const setEvents = (next) => {
+        setRun((current) => ({ ...current, events: next(current.events) }));
+    };
+    // A ref rather than state, so the effect does not re-subscribe because an event
+    // arrived. An effect that depended on the value it writes re-runs itself, and the
+    // surface would open a new subscription per event.
+    const emit = useRef(() => { });
+    useEffect(() => {
+        emit.current = (event) => {
+            setEvents((current) => {
+                const next = [...current, event].sort(byTimeThenId);
+                return next.length > limit ? next.slice(next.length - limit) : next;
+            });
+            setNewest(event.message);
+        };
+        const stop = subscribe(emit.current);
+        return () => {
+            // Calling an unsubscribe the consumer did not return would throw during
+            // unmount, so a missing one is stepped over and the leak is the consumer's to
+            // fix rather than a crash in someone else's teardown.
+            if (typeof stop === 'function')
+                stop();
+        };
+    }, [subscribe, resubscribeKey, limit]);
+    return (_jsxs("section", { "data-slot": "run-stream", className: cn('border-border flex flex-col gap-4 rounded-lg border p-4', className), children: [LiveRegion({ politeness: 'polite', label: liveLabel, children: newest }), title !== undefined || eyebrow !== undefined || description !== undefined ? (_jsxs("header", { className: "flex flex-col gap-1", children: [eyebrow ? (_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: eyebrow })) : null, title ? _jsx("h2", { className: "text-lg font-semibold tracking-tight", children: title }) : null, description ? (_jsx("p", { className: "text-muted-foreground text-pretty text-sm", children: description })) : null] })) : null, status !== undefined ? (_jsx("p", { "data-slot": "run-status", className: cn('font-mono text-xs', STATUS_INK[status]), children: statusLabel })) : null, events.length === 0 ? (_jsx("p", { "data-slot": "run-stream-empty", className: "text-muted-foreground text-sm", children: emptyLabel })) : (_jsx(ScrollArea, { label: eventsLabel, className: "max-h-80", children: _jsx("ol", { "data-slot": "run-events", className: "flex flex-col gap-2", children: events.map((event) => (_jsxs("li", { "data-slot": "run-event", "data-role": event.role, className: "grid grid-cols-[auto_auto_1fr] items-baseline gap-x-3 gap-y-0.5", children: [_jsx("span", { "aria-hidden": "true", className: cn('font-mono text-xs', ROLE_INK[event.role]), children: ROLE_MARK[event.role] }), _jsx("time", { dateTime: new Date(event.at).toISOString(), className: "text-muted-foreground font-mono text-xs tabular-nums", children: new Date(event.at).toISOString().slice(11, 19) }), _jsxs("span", { className: cn('text-pretty text-sm', ROLE_INK[event.role]), children: [event.message, event.detail ? (_jsx("span", { className: "text-muted-foreground block font-mono text-xs", children: event.detail })) : null] })] }, event.id))) }) }))] }));
+}
+export default RunStream01;

package/dist/pages/auth-page/index.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentProps, ReactNode } from 'react';
-import { AuthForm01 } from '../../blocks/auth-form-01';
+import { AuthForm01 } from '../../blocks/auth-form-01/index.js';
+import type { HeadingLevel } from '../../components/ui/section.js';
 export type AuthPageAside = {
     /** The supporting card's title. */
     title: string;
@@ -17,6 +18,18 @@ export type AuthPageProps = {
     aside?: AuthPageAside;
     /** A node under the form, such as a legal line or a link to another screen. */
     footer?: ReactNode;
+    /**
+     * Heading level for the two region titles, the form's and the aside's. See
+     * `HeadingLevel`.
+     *
+     * The page draws no heading of its own, so each region names itself and the two
+     * are siblings in the outline. They therefore take one level between them
+     * rather than each choosing one: two regions that announced themselves at
+     * different depths would read as one inside the other, and nothing in the layout
+     * says so. Defaults to `h2`, because a page composes under a document that has
+     * its own `h1`.
+     */
+    headingLevel?: HeadingLevel;
 };
 /**
  * A complete authentication screen.
@@ -31,6 +44,6 @@ export type AuthPageProps = {
  * split from the large breakpoint up when one is. That keeps the docs preview
  * and a narrow screen on the same, readable path.
  */
-export declare function AuthPage({ form, aside, footer }: AuthPageProps): import("react").JSX.Element;
+export declare function AuthPage({ form, aside, footer, headingLevel }: AuthPageProps): import("react").JSX.Element;
 export default AuthPage;
 //# sourceMappingURL=index.d.ts.map

package/dist/pages/auth-page/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/auth-page/index.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAStD,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,2BAA2B;IAC3B,IAAI,EAAE,cAAc,CAAC,OAAO,UAAU,CAAC,CAAA;IACvC;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,aAAa,+BA+B9D;AAED,eAAe,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pages/auth-page/index.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAQtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAE/D,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,2BAA2B;IAC3B,IAAI,EAAE,cAAc,CAAC,OAAO,UAAU,CAAC,CAAA;IACvC;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,YAAmB,EAAE,EAAE,aAAa,+BAqCnF;AAED,eAAe,QAAQ,CAAA"}

package/dist/pages/auth-page/index.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { AuthForm01 } from '../../blocks/auth-form-01';
-import { Card, CardContent, CardDescription, CardHeader, CardTitle, } from '../../components/ui/card';
+import { AuthForm01 } from '../../blocks/auth-form-01/index.js';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle, } from '../../components/ui/card.js';
 /**
  * A complete authentication screen.
  *
@@ -15,9 +15,13 @@ import { Card, CardContent, CardDescription, CardHeader, CardTitle, } from '../.
  * split from the large breakpoint up when one is. That keeps the docs preview
  * and a narrow screen on the same, readable path.
  */
-export function AuthPage({ form, aside, footer }) {
+export function AuthPage({ form, aside, footer, headingLevel = 'h2' }) {
+    // The form and the aside are sibling regions, so they announce themselves at the
+    // same depth: at different depths one would read as inside the other, and
+    // nothing in the layout says so.
+    const Title = headingLevel;
     return (_jsx("div", { className: "bg-background text-foreground flex min-h-svh w-full items-center justify-center px-6 py-16", children: _jsxs("div", { className: aside
                 ? 'grid w-full max-w-page items-center gap-10 lg:grid-cols-2'
-                : 'w-full max-w-measure-narrow', children: [aside ? (_jsxs(Card, { children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { children: aside.title }), aside.description ? (_jsx(CardDescription, { children: aside.description })) : null] }), aside.children ? _jsx(CardContent, { children: aside.children }) : null] })) : null, _jsxs("div", { className: "mx-auto w-full max-w-measure-narrow", children: [_jsx(AuthForm01, { ...form }), footer ? (_jsx("div", { className: "text-muted-foreground mt-4 text-center text-sm", children: footer })) : null] })] }) }));
+                : 'w-full max-w-measure-narrow', children: [aside ? (_jsxs(Card, { children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { children: _jsx(Title, { children: aside.title }) }), aside.description ? (_jsx(CardDescription, { children: aside.description })) : null] }), aside.children ? _jsx(CardContent, { children: aside.children }) : null] })) : null, _jsxs("div", { className: "mx-auto w-full max-w-measure-narrow", children: [_jsx(AuthForm01, { ...form, headingLevel: headingLevel }), footer ? (_jsx("div", { className: "text-muted-foreground mt-4 text-center text-sm", children: footer })) : null] })] }) }));
 }
 export default AuthPage;

package/dist/pages/blog-post-page/index.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Badge } from '../../components/ui/badge';
-import { CtaLink } from '../../components/ui/cta-link';
-import { Heading, Text } from '../../components/ui/typography';
-import { Prose } from '../../components/ui/prose';
-import { Section } from '../../components/ui/section';
+import { Badge } from '../../components/ui/badge.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Heading, Text } from '../../components/ui/typography.js';
+import { Prose } from '../../components/ui/prose.js';
+import { Section } from '../../components/ui/section.js';
 /**
  * A complete blog post screen: the title, the standfirst, the byline, the body at
  * the measure, and the trail to the neighbouring posts.

package/dist/pages/dashboard-page/index.d.ts

@@ -1,8 +1,8 @@
 import type { ComponentProps } from 'react';
-import { AppShell01 } from '../../blocks/app-shell-01';
-import { DataTable01 } from '../../blocks/data-table-01';
-import { PageHeader01 } from '../../blocks/page-header-01';
-import { Stats01 } from '../../blocks/stats-01';
+import { AppShell01 } from '../../blocks/app-shell-01/index.js';
+import { DataTable01 } from '../../blocks/data-table-01/index.js';
+import { PageHeader01 } from '../../blocks/page-header-01/index.js';
+import { Stats01 } from '../../blocks/stats-01/index.js';
 export type DashboardPageProps = {
     /**
      * The frame: the navigation rail, the top bar and the mobile navigation

package/dist/pages/dashboard-page/index.js

@@ -1,9 +1,9 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { AppShell01 } from '../../blocks/app-shell-01';
-import { DataTable01 } from '../../blocks/data-table-01';
-import { PageHeader01 } from '../../blocks/page-header-01';
-import { Stats01 } from '../../blocks/stats-01';
+import { AppShell01 } from '../../blocks/app-shell-01/index.js';
+import { DataTable01 } from '../../blocks/data-table-01/index.js';
+import { PageHeader01 } from '../../blocks/page-header-01/index.js';
+import { Stats01 } from '../../blocks/stats-01/index.js';
 /**
  * A complete dashboard screen.
  *

package/dist/pages/docs-shell/docs-shell.d.ts

@@ -5,12 +5,27 @@ import type { ReactNode } from 'react';
  * `href` is required. A page in the navigation that goes nowhere is an entry a
  * reader can focus and not follow, and the Page renders every page entry as a
  * native anchor so a reader can see where a destination is before taking it.
+ *
+ * **Required is not the same as enforced, and the difference is stated here
+ * rather than left to be discovered.** `href: string` admits `''`, because the
+ * empty string is a legal `string` and the only type that refuses it is a branded
+ * one, which would put an `as` in every consumer's adapter for three sites this
+ * Page is already published to. So the type admits the value and `readTree`
+ * refuses it, at the boundary, by throwing and naming the entry. The promise this
+ * block used to make was true only of the group arm; it is now true of what the
+ * Page renders, and it says which of the two is doing the work.
+ *
+ * `title` may be the empty string, and an entry with no words is not a page: it
+ * renders as a label on the same rule that makes a group with no index a label,
+ * and it is not a page the pager can reach either. A link with no accessible name
+ * is announced as "link" and nothing else, which is the one thing a link in a
+ * rail must never be.
  */
 export type DocsNavPage = {
     type: 'page';
-    /** The words the reader meets. */
+    /** The words the reader meets. An empty string makes this a label, not a link. */
     title: string;
-    /** The address the page is read at. */
+    /** The address the page is read at. An empty string is refused, by name. */
     href: string;
 };
 /**
@@ -37,6 +52,13 @@ export type DocsNavGroup = {
     /**
      * The group's own index page, where it has one. Omit it for a group that is
      * only a heading over its pages.
+     *
+     * An empty or blank string is the same answer as omitting it, and deliberately
+     * so: all three consumer adapters write `url: node.index?.url ?? ''` for a
+     * folder holding no `index.mdx`, so the empty string is how they have always
+     * spelled "this group is not a route", and reading it as the absence is what
+     * keeps those adapters correct without a change in any of them. A page has no
+     * such reading: there, an empty address is a fault, and `readTree` says so.
      */
     href?: string;
     /** The pages under this group, in the order a reader should meet them. */
@@ -209,8 +231,19 @@ export type DocsShellProps = {
  * consumer sites all write `url: node.index?.url ?? ''` in their own adapter
  * today, which is the same fact spelled as an empty string, and two of the three
  * then carry a stylesheet rule that styles the resulting anchor-with-no-href
- * back into a label. Naming the case in the type makes those two rules dead
- * rather than load-bearing, and the type is the only place that had to change.
+ * back into a label. So the Page reads an empty or blank `href` as the absence on
+ * this arm, and the two stylesheet rules are dead rather than load-bearing. It
+ * takes one function rather than only a type, because an optional field the
+ * caller spells as `''` is not an optional field the type can see.
+ *
+ * **An entry with no words is a label too, and a page with no address is
+ * refused.** Both halves of "what makes this a destination" are answered in one
+ * function, `destinationOf`, and both the rail and the pager ask it. An entry
+ * that is a label on the rail is not a page the pager reaches either, so one
+ * malformed row cannot become two surfaces' worth of broken link. A page whose
+ * address is empty or blank has no such reading: there is nothing to render in
+ * place of the link, so the Page throws, naming the entry, before any of the tree
+ * renders.
  *
  * **The pager is derived from the navigation rather than passed.** The rail
  * already knows every page and the order a reader meets them in, and deriving the

package/dist/pages/docs-shell/docs-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-shell.d.ts","sourceRoot":"","sources":["../../../src/pages/docs-shell/docs-shell.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMtC;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,CAAA;AAEtE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,WAAW,EACX,GAAG,EACH,GAAG,EACH,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,WAAW,EACX,MAAM,EACN,MAAM,EACN,SAAS,EACT,QAAQ,GACT,EAAE,cAAc,+BAmFhB;AA4QD,eAAe,SAAS,CAAA"}
+{"version":3,"file":"docs-shell.d.ts","sourceRoot":"","sources":["../../../src/pages/docs-shell/docs-shell.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMtC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAC/B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,CAAA;AAEtE;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,WAAW,EACX,GAAG,EACH,GAAG,EACH,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,WAAW,EACX,MAAM,EACN,MAAM,EACN,SAAS,EACT,QAAQ,GACT,EAAE,cAAc,+BAsFhB;AAwWD,eAAe,SAAS,CAAA"}

package/dist/pages/docs-shell/docs-shell.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Prose } from '../../components/ui/prose';
-import { Heading, Text } from '../../components/ui/typography';
-import { cn } from '../../lib/utils';
+import { Prose } from '../../components/ui/prose.js';
+import { Heading, Text } from '../../components/ui/typography.js';
+import { cn } from '../../lib/utils.js';
 /**
  * A documentation screen: a navigation rail, the document, a contents rail and
  * the pager to the neighbouring pages.
@@ -31,8 +31,19 @@ import { cn } from '../../lib/utils';
  * consumer sites all write `url: node.index?.url ?? ''` in their own adapter
  * today, which is the same fact spelled as an empty string, and two of the three
  * then carry a stylesheet rule that styles the resulting anchor-with-no-href
- * back into a label. Naming the case in the type makes those two rules dead
- * rather than load-bearing, and the type is the only place that had to change.
+ * back into a label. So the Page reads an empty or blank `href` as the absence on
+ * this arm, and the two stylesheet rules are dead rather than load-bearing. It
+ * takes one function rather than only a type, because an optional field the
+ * caller spells as `''` is not an optional field the type can see.
+ *
+ * **An entry with no words is a label too, and a page with no address is
+ * refused.** Both halves of "what makes this a destination" are answered in one
+ * function, `destinationOf`, and both the rail and the pager ask it. An entry
+ * that is a label on the rail is not a page the pager reaches either, so one
+ * malformed row cannot become two surfaces' worth of broken link. A page whose
+ * address is empty or blank has no such reading: there is nothing to render in
+ * place of the link, so the Page throws, naming the entry, before any of the tree
+ * renders.
  *
  * **The pager is derived from the navigation rather than passed.** The rail
  * already knows every page and the order a reader meets them in, and deriving the
@@ -68,6 +79,8 @@ import { cn } from '../../lib/utils';
  * and hands it the document their pipeline produced.
  */
 export function DocsShell({ title, description, nav, toc, currentHref, navLabel, tocLabel, pagerLabel, pagerLabels, header, footer, className, children, }) {
+    readTree(nav, 'nav');
+    readTree(toc, 'toc');
     const rail = nav && nav.length > 0 ? nav : undefined;
     const contents = toc && toc.length > 0 ? toc : undefined;
     const neighbours = currentHref === undefined ? undefined : deriveNeighbours(nav ?? [], currentHref);
@@ -79,6 +92,68 @@ export function DocsShell({ title, description, nav, toc, currentHref, navLabel,
                 // them.
                 contents ? 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)] xl:grid-cols-[15rem_minmax(0,1fr)_13rem]' : 'lg:grid lg:grid-cols-[15rem_minmax(0,1fr)]'), children: [rail ? (_jsx("aside", { "data-slot": "docs-rail", className: "hidden lg:col-start-1 lg:row-start-1 lg:block", children: _jsx("nav", { "aria-label": navLabel, className: "lg:sticky lg:top-20 lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto lg:pe-4", children: _jsx(NavList, { entries: rail, currentHref: currentHref, depth: 0 }) }) })) : null, _jsxs("article", { "data-slot": "docs-article", className: "flex min-w-0 flex-col gap-8", children: [title ? (_jsxs("header", { className: "flex flex-col gap-3", children: [_jsx(Heading, { as: "h1", size: "3xl", children: title }), description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null] })) : description ? (_jsx(Text, { size: "lg", tone: "muted", className: "max-w-measure", children: description })) : null, _jsx(Prose, { fullWidth: true, children: children }), neighbours ? (_jsx(Pager, { previous: neighbours.previous, next: neighbours.next, label: pagerLabel, labels: pagerLabels })) : null] }), contents ? (_jsx("aside", { "data-slot": "docs-contents", className: "hidden lg:col-start-3 lg:row-start-1 lg:block", children: _jsx("nav", { "aria-label": tocLabel, className: "lg:sticky lg:top-20 lg:max-h-[calc(100svh-7rem)] lg:overflow-y-auto", children: _jsx(NavList, { entries: contents, currentHref: currentHref, depth: 0 }) }) })) : null] }), footer] }));
 }
+/* ------------------------------------------------------------------ *
+ * The tree
+ * ------------------------------------------------------------------ */
+/**
+ * The address an entry has, or `undefined` when it has none.
+ *
+ * Blank counts as none, which is not pedantry. All three consumer adapters write
+ * `url: node.index?.url ?? ''` for a folder holding no index, so the empty string
+ * is how they spell "this group is not a route", and a guard that read only
+ * `=== undefined` let that same spelling through to the renderer on the arm where
+ * it means something else entirely.
+ */
+function addressOf(href) {
+    return href !== undefined && href.trim() !== '' ? href : undefined;
+}
+/**
+ * The address an entry is reachable at, or `undefined` when it is not a
+ * destination at all.
+ *
+ * An entry is a destination only when it has an address AND words, and both
+ * halves live here so that one rule answers for both surfaces that read a tree.
+ * The rail asks it to decide between an anchor and a label; the pager asks it to
+ * decide between a neighbour and nothing. Two places deciding that separately is
+ * how one malformed row becomes a nameless anchor in the rail and a nameless
+ * `Next` link under it.
+ */
+function destinationOf(entry) {
+    return entry.title === '' ? undefined : addressOf(entry.href);
+}
+/**
+ * Reads a tree before any of it renders, and refuses the one shape it cannot
+ * render honestly.
+ *
+ * A page entry whose address is empty or blank is an entry whose whole content is
+ * a route the consumer does not have. There is no honest rendering of it: a label
+ * in its place would hide a page the tree is missing rather than report it, and an
+ * anchor would be a control a reader can focus and cannot operate. So the Page
+ * throws, naming the entry, which is the opposite of copy and reaches a developer
+ * rather than a reader.
+ *
+ * Two things are deliberate here. The pass is in the component and not in a
+ * renderer, so it runs once for both trees and cannot be reached only on the path
+ * that happens to draw the bad row. And a GROUP is not refused: no address is a
+ * documented state for a group and the empty string is how all three consumers
+ * already spell it, so it renders as a label. Only the arm where an address is
+ * the entire entry is a fault.
+ */
+function readTree(entries, source) {
+    for (const entry of entries ?? []) {
+        if (entry.type === 'divider')
+            continue;
+        if (entry.type === 'group') {
+            readTree(entry.items, source);
+            continue;
+        }
+        if (addressOf(entry.href) === undefined) {
+            throw new Error(`docs-shell: a page entry in the ${source} has no address, and an anchor with no address is a ` +
+                'control a reader can focus and cannot follow. Give the entry the address its page is read at, or ' +
+                `remove it from the tree. Its title is ${JSON.stringify(entry.title)}.`);
+        }
+    }
+}
 /* ------------------------------------------------------------------ *
  * The rail
  * ------------------------------------------------------------------ */
@@ -111,12 +186,17 @@ function NavNode({ entry, currentHref, depth, }) {
         // above the hairline rather than a word a reader has to interpret.
         return (_jsx("li", { "data-slot": "docs-nav-divider", className: "border-border mt-2 border-t pt-2 first:mt-0 first:border-t-0 first:pt-0", children: entry.title ? (_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: entry.title })) : null }));
     }
+    const href = destinationOf(entry);
     if (entry.type === 'group') {
-        return (_jsx("li", { "data-slot": "docs-nav-group", children: _jsxs("div", { className: "flex flex-col gap-1", children: [entry.href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(entry, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-heading", href: entry.href, "aria-current": currentHref === entry.href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(entry.href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })), entry.items.length > 0 ? (_jsx(NavList, { entries: entry.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
+        return (_jsx("li", { "data-slot": "docs-nav-group", children: _jsxs("div", { className: "flex flex-col gap-1", children: [href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(entry, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-heading", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: entry.title })), entry.items.length > 0 ? (_jsx(NavList, { entries: entry.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
     }
-    return (_jsx("li", { "data-slot": "docs-nav-page", children: _jsx("a", { "data-slot": "docs-nav-link", href: entry.href, "aria-current": currentHref === entry.href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === entry.href
+    // The page arm. `href` is never empty here: `readTree` refused that above and
+    // named the entry, so what is left to decide is the words. A nameless page is
+    // the same rule as a group with no index, rendered as a label, because a link
+    // with no accessible name is announced as "link" and nothing else.
+    return (_jsx("li", { "data-slot": "docs-nav-page", children: href === undefined ? (_jsx("span", { "data-slot": "docs-nav-label", className: "-ms-px block border-l-2 border-transparent py-1 ps-3 text-sm text-muted-foreground", children: entry.title })) : (_jsx("a", { "data-slot": "docs-nav-link", href: href, "aria-current": currentHref === href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === href
                 ? 'text-foreground border-primary font-medium'
-                : 'text-muted-foreground hover:text-foreground border-transparent'), children: entry.title }) }));
+                : 'text-muted-foreground hover:text-foreground border-transparent'), children: entry.title })) }));
 }
 /**
  * Every page the tree holds, in the order a reader meets them.
@@ -126,18 +206,23 @@ function NavNode({ entry, currentHref, depth, }) {
  * contributes its children and nothing else, which is the second thing that
  * makes an absent `href` a label rather than a route: there is no page there for
  * the pager to reach either. A divider contributes nothing at all.
+ *
+ * The row a reader can click and the row the pager can reach are decided by the
+ * SAME function, `destinationOf`. A nameless entry is a label on the rail and is
+ * dropped here, so one malformed row cannot be published twice: a nameless anchor
+ * in the rail, and a `Next` link under it carrying the text of whichever entry
+ * happened to follow, is what deriving without asking produced. The two surfaces
+ * do not each get their own opinion about a row that is not a page.
  */
 function flatten(entries, into = []) {
     for (const entry of entries) {
-        if (entry.type === 'page') {
-            into.push({ title: entry.title, href: entry.href });
+        if (entry.type === 'divider')
             continue;
-        }
-        if (entry.type === 'group') {
-            if (entry.href !== undefined)
-                into.push({ title: entry.title, href: entry.href });
+        const href = destinationOf(entry);
+        if (href !== undefined)
+            into.push({ title: entry.title, href });
+        if (entry.type === 'group')
             flatten(entry.items, into);
-        }
     }
     return into;
 }
@@ -182,9 +267,15 @@ function under(href, currentHref) {
  * A group with a route answers for that route and everything under it. A group
  * without one has no route to answer with, so it asks its children, which is the
  * only way a label can still show a reader that they are inside it.
+ *
+ * The group's own address is read through `addressOf`, like every other read of
+ * it. A group whose `href` is the empty string is a label, and a blank string
+ * handed to `under` as though it were a route matches every absolute address on
+ * the site, which is every label-only section claiming to be the current one at
+ * once.
  */
 function containsHref(group, currentHref) {
-    if (under(group.href, currentHref))
+    if (under(addressOf(group.href), currentHref))
         return true;
     return group.items.some((entry) => {
         if (entry.type === 'page')

package/dist/pages/docs-shell/index.d.ts

@@ -1,3 +1,3 @@
-export { DocsShell, default } from './docs-shell';
-export type { DocsShellProps, DocsNavEntry, DocsNavPage, DocsNavGroup, DocsNavDivider, DocsPagerLabels, } from './docs-shell';
+export { DocsShell, default } from './docs-shell.js';
+export type { DocsShellProps, DocsNavEntry, DocsNavPage, DocsNavGroup, DocsNavDivider, DocsPagerLabels, } from './docs-shell.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/pages/docs-shell/index.js

@@ -1 +1 @@
-export { DocsShell, default } from './docs-shell';
+export { DocsShell, default } from './docs-shell.js';