@westonkd/sprint 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1210,6 +1210,129 @@ export declare interface ModelContext {
 
 export declare function Nav(props: NavProps): JSX.Element;
 
+export declare function NavBar(props: NavBarProps): JSX.Element;
+
+export declare interface NavBarDestination {
+    href: string;
+    label: string;
+    active?: boolean;
+    external?: boolean;
+}
+
+export declare interface NavBarGroup {
+    label: string;
+    items: readonly NavBarDestination[];
+}
+
+export declare const navBarMeta: {
+    readonly name: "NavBar";
+    readonly category: "navigation";
+    readonly summary: "A navigation landmark that renders as one line: where you are, written as a coordinate you can edit. Every destination stays in the page as an addressable part; the coordinate decides which of them a person is shown.";
+    readonly whenToUse: "Use it as an application's primary navigation when the catalogue is larger than a rail can hold, or when the layout needs its full width. Each segment of the coordinate opens its own level and filters as you type, so what a person chooses from is one level rather than the whole set. It takes destinations as data because it counts, filters and orders them.";
+    readonly whenNotToUse: "Do not use it for a handful of links that fit in a sidebar; that is Nav with NavGroup, which keeps every destination visible at once. Do not use it for links inside prose, and do not pass components in groups: each destination is a label and an href, not a node.";
+    readonly status: "experimental";
+    readonly props: {
+        readonly label: {
+            readonly kind: "string";
+            readonly description: "What this navigation is for. Rendered as the landmark's accessible name and as the root of the coordinate.";
+            readonly required: true;
+        };
+        readonly groups: {
+            readonly kind: "array";
+            readonly description: "The destinations, as groups of { label, items }, each item { href, label, active?, external? }. Order is the order a person travels them.";
+            readonly required: true;
+        };
+        readonly emptyLabel: {
+            readonly kind: "string";
+            readonly description: "What the bar says when a filter matches no destination.";
+            readonly default: "No match";
+        };
+        readonly trailEmptyLabel: {
+            readonly kind: "string";
+            readonly description: "What the bar says when nothing has been visited through it yet.";
+            readonly default: "Nothing visited yet";
+        };
+        readonly open: {
+            readonly kind: "enum";
+            readonly description: "Which segment is open, or 'closed'. Pass it to drive the bar from outside, such as from an application-level shortcut; leave it off and the bar keeps its own state.";
+            readonly values: readonly ["trail", "group", "leaf", "closed"];
+        };
+        readonly onOpenChange: {
+            readonly kind: "handler";
+            readonly description: "Called with the segment the bar wants open, or 'closed'. Required when open is controlled, so the bar can still close itself.";
+        };
+        readonly onNavigate: {
+            readonly kind: "handler";
+            readonly description: "Called with the destination when one is chosen, before the browser follows the href. Use it to record the visit somewhere that outlives this component.";
+        };
+    };
+    readonly state: {
+        readonly destinations: {
+            readonly description: "How many destinations the bar holds.";
+            readonly attribute: "data-sprint-destinations";
+        };
+        readonly open: {
+            readonly description: "Which segment of the coordinate is open: trail, group, or leaf. Absent when the bar is closed to its one line.";
+            readonly attribute: "data-sprint-open";
+        };
+        readonly depth: {
+            readonly description: "How many destinations have been visited through this bar.";
+            readonly attribute: "data-sprint-depth";
+        };
+        readonly matches: {
+            readonly description: "How many destinations the open segment is showing.";
+            readonly attribute: "data-sprint-matches";
+        };
+        readonly shown: {
+            readonly description: "On a destination: present when the open segment is currently showing it to a person. Every destination stays in the page either way.";
+            readonly attribute: "data-sprint-shown";
+        };
+        readonly group: {
+            readonly description: "On a destination: the group it belongs to.";
+            readonly attribute: "data-sprint-group";
+        };
+        readonly href: {
+            readonly description: "On a destination: where it goes.";
+            readonly attribute: "data-sprint-href";
+        };
+        readonly active: {
+            readonly description: "On a destination: present when it is the current page.";
+            readonly attribute: "data-sprint-active";
+        };
+    };
+    readonly agentView: {
+        readonly example: "- **NavBar** \"Workbench\" [destinations=2, depth=0]\n  - part `destination` \"Button\" [group=action, href=#/Button]\n  - part `destination` \"Table\" [group=display, href=#/Table, active, shown]";
+    };
+    readonly a11y: {
+        readonly role: "navigation";
+        readonly notes: "The label is the landmark's accessible name. The current destination carries aria-current=page. Destinations the coordinate is not showing are hidden from the accessibility tree by CSS, so a screen reader travels one level at a time exactly as a sighted reader does, while the page itself keeps all of them. From the field, ArrowDown enters the results and ArrowUp at the top returns to it; typing anywhere in the results goes back to the field and keeps the character. Escape closes the bar, as does a press outside it, and the match count is a polite live region. ArrowUp in an empty field recalls the trail, the way a console recalls history.";
+    };
+    readonly relatedComponents: readonly ["Nav", "NavGroup", "Link", "Shell"];
+    readonly examples: readonly [{
+        readonly title: "A coordinate bar";
+        readonly description: "One line of chrome over a grouped catalogue. Clicking a segment opens that level and filters it as you type.";
+        readonly code: "<NavBar\n  label=\"Workbench\"\n  groups={[\n    { label: \"action\", items: [{ href: \"#/Button\", label: \"Button\" }] },\n    { label: \"display\", items: [{ href: \"#/Table\", label: \"Table\", active: true }] },\n  ]}\n/>";
+    }, {
+        readonly title: "Recording where a person has been";
+        readonly description: "The bar keeps a trail of the destinations chosen through it, reachable from the depth count at its head. onNavigate is how that outlives the component.";
+        readonly code: "<NavBar\n  label=\"Docs\"\n  groups={[{ label: \"guides\", items: [{ href: \"#/guide/webmcp\", label: \"WebMCP\" }] }]}\n  onNavigate={(destination) => console.log(destination.href)}\n/>";
+    }];
+};
+
+export declare type NavBarOpening = NavBarSegment | "closed";
+
+export declare interface NavBarProps extends Omit<ComponentPropsWithRef<"nav">, "children"> {
+    label: string;
+    groups: readonly NavBarGroup[];
+    emptyLabel?: string;
+    trailEmptyLabel?: string;
+    open?: NavBarOpening;
+    onOpenChange?: (opening: NavBarOpening) => void;
+    onNavigate?: (destination: NavBarDestination) => void;
+}
+
+export declare type NavBarSegment = "trail" | "group" | "leaf";
+
 export declare function NavGroup(props: NavGroupProps): JSX.Element;
 
 export declare const navGroupMeta: {