@ship-it-ui/ui 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ClassValue } from 'clsx';
+export { ClassValue } from 'clsx';
 import * as react from 'react';
-import { KeyboardEvent, RefObject, ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, AnchorHTMLAttributes, Ref, FC, SVGAttributes } from 'react';
+import { useEffect, KeyboardEvent, RefObject, ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, AnchorHTMLAttributes, Ref, LabelHTMLAttributes, FC, SVGAttributes } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import * as RadixCheckbox from '@radix-ui/react-checkbox';
@@ -44,10 +45,16 @@ interface UseControllableStateProps<T> {
     /** Change callback fired in both modes whenever the value would change. */
     onChange?: (value: T) => void;
 }
-declare function useControllableState<T>({ value: controlledValue, defaultValue, onChange, }: UseControllableStateProps<T>): [
-    T | undefined,
-    (next: T | ((prev: T | undefined) => T)) => void
-];
+declare function useControllableState<T>(opts: {
+    value?: T;
+    defaultValue: T;
+    onChange?: (next: T) => void;
+}): readonly [T, (next: T | ((prev: T) => T)) => void];
+declare function useControllableState<T>(opts: {
+    value?: T;
+    defaultValue?: T;
+    onChange?: (next: T) => void;
+}): readonly [T | undefined, (next: T | ((prev: T | undefined) => T)) => void];
 
 /**
  * Standardized open/close state for overlays.
@@ -66,9 +73,25 @@ declare function useDisclosure(initial?: boolean): {
  * Calls `handler` when Escape is pressed while `enabled` is true.
  * Most overlay components (Dialog, Popover, Drawer) get this for free via Radix,
  * but custom popovers and inline editors need it.
+ *
+ * Implementation note: the handler is stored in a ref so an inline
+ * `() => doThing()` passed by the consumer doesn't detach/reattach the
+ * `keydown` listener every render.
  */
 declare function useEscape(handler: () => void, enabled?: boolean): void;
 
+/**
+ * `useLayoutEffect` on the client, `useEffect` on the server.
+ *
+ * React warns when `useLayoutEffect` runs on the server because there's no
+ * DOM to measure. This shim swaps in `useEffect` during SSR and restores
+ * `useLayoutEffect` once the bundle is evaluated client-side.
+ *
+ * Use when you need to measure or synchronously mutate the DOM before
+ * paint. Plain `useEffect` is preferred otherwise.
+ */
+declare const useIsomorphicLayoutEffect: typeof useEffect;
+
 /**
  * Keyboard navigation for arrow-key selectable lists (Combobox, CommandPalette,
  * filtered dropdown bodies). Tracks the highlighted cursor and exposes a
@@ -97,11 +120,13 @@ interface UseKeyboardListResult {
 declare function useKeyboardList({ count, loop, defaultCursor, onSelect, }: UseKeyboardListOptions): UseKeyboardListResult;
 
 /**
- * Calls `handler` when a mousedown occurs outside the element referenced by `ref`.
+ * Calls `handler` when a pointerdown occurs outside the element referenced by `ref`.
  *
  * Pass `enabled=false` to detach (typically while the popover is closed). Listens on
- * `mousedown` rather than `click` so the trigger sees the close before its own click
- * fires — matches the behavior of most popover libraries.
+ * `pointerdown` rather than `click` so the trigger sees the close before its own click
+ * fires — matches the behavior of most popover libraries. `pointerdown` is the unified
+ * mouse + touch + pen event, so this also works on touch devices (where `mousedown`
+ * is not synthesized for taps until after the click).
  */
 declare function useOutsideClick<T extends HTMLElement>(ref: RefObject<T | null>, handler: () => void, enabled?: boolean): void;
 
@@ -147,7 +172,7 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantPr
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
 
 declare const iconButtonStyles: (props?: ({
-    variant?: "primary" | "secondary" | "ghost" | "outline" | null | undefined;
+    variant?: "primary" | "secondary" | "ghost" | "outline" | "destructive" | "success" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'>, VariantProps<typeof iconButtonStyles> {
@@ -177,9 +202,15 @@ interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
  */
 declare const ButtonGroup: react.ForwardRefExoticComponent<ButtonGroupProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Variant set supported by `SplitButton`. Mirrors `Button`'s set minus `link` —
+ * a split-button "menu" affordance attached to a link variant doesn't compose
+ * visually. Use a regular `<Button variant="link" />` instead.
+ */
+type SplitButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'success';
 interface SplitButtonProps extends HTMLAttributes<HTMLDivElement> {
     /** Visual variant applied to BOTH segments. Defaults to `primary`. */
-    variant?: ButtonProps['variant'];
+    variant?: SplitButtonVariant;
     /** Size applied to both segments. Defaults to `md`. */
     size?: ButtonProps['size'];
     /** Click handler for the main action button. */
@@ -188,6 +219,12 @@ interface SplitButtonProps extends HTMLAttributes<HTMLDivElement> {
     onMenu?: () => void;
     /** Disable both segments. */
     disabled?: boolean;
+    /**
+     * Accessible label for the trailing menu button. Defaults to
+     * `"More actions"`. Override when the menu's purpose is more specific
+     * (e.g. `"Deploy options"`) so screen-reader users hear the right intent.
+     */
+    menuAriaLabel?: string;
     children: ReactNode;
 }
 /**
@@ -249,7 +286,7 @@ declare function Field({ label, hint, error, required, className, children, ...p
 
 declare const inputWrapperStyles: (props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
-    tone?: "error" | "default" | null | undefined;
+    tone?: "default" | "err" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>, VariantProps<typeof inputWrapperStyles> {
     /** Element rendered to the left of the input (an `IconGlyph`, `@`, etc.). */
@@ -354,15 +391,39 @@ interface SelectProps extends Omit<RadixSelect.SelectProps, 'children'> {
  */
 declare function Select({ options, placeholder, size, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...rootProps }: SelectProps): react_jsx_runtime.JSX.Element;
 
-interface SliderProps extends Omit<RadixSlider.SliderProps, 'asChild'> {
+interface SliderProps extends Omit<RadixSlider.SliderProps, 'asChild' | 'value' | 'defaultValue' | 'onValueChange'> {
     /** Show the numeric value to the right of the track. */
     showValue?: boolean;
     /** Pixel width or any CSS length. Defaults to `240`. */
     width?: number | string;
+    /**
+     * Per-thumb accessible names for multi-thumb (range) sliders. The label at
+     * each index is forwarded to the corresponding `<RadixSlider.Thumb>`. When
+     * omitted, every thumb falls back to `aria-label`/`aria-labelledby` (or the
+     * literal `'Value'` when neither is provided).
+     */
+    thumbLabels?: ReadonlyArray<string>;
+    /**
+     * Controlled value. Accepts a scalar for single-thumb sliders or an array
+     * for multi-thumb (range) sliders. The shape passed in mirrors the shape
+     * passed back to `onValueChange`.
+     */
+    value?: number | number[];
+    /** Uncontrolled initial value. Same scalar/array semantics as `value`. */
+    defaultValue?: number | number[];
+    /**
+     * Fires when the value changes. The argument shape mirrors the input shape:
+     * if `value`/`defaultValue` is a scalar, `next` is a scalar; if it's an
+     * array, `next` is an array.
+     */
+    onValueChange?: (next: number | number[]) => void;
 }
 /**
  * Range slider. Built on Radix Slider for keyboard support (arrow keys nudge,
  * Page Up/Down jumps, Home/End snap to extremes).
+ *
+ * Pass `aria-label` / `aria-labelledby` to name a single-thumb slider; pass
+ * `thumbLabels` to name each thumb in a multi-thumb (range) slider.
  */
 declare const Slider: react.ForwardRefExoticComponent<SliderProps & react.RefAttributes<HTMLSpanElement>>;
 
@@ -375,7 +436,7 @@ interface SwitchProps extends Omit<RadixSwitch.SwitchProps, 'asChild' | 'childre
 declare const Switch: react.ForwardRefExoticComponent<SwitchProps & react.RefAttributes<HTMLButtonElement>>;
 
 declare const textareaStyles: (props?: ({
-    tone?: "error" | "default" | null | undefined;
+    tone?: "default" | "err" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement>, VariantProps<typeof textareaStyles> {
     /** Error tone shortcut. Sets `aria-invalid` and the error border. */
@@ -419,7 +480,7 @@ interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
 declare const AvatarGroup: react.ForwardRefExoticComponent<AvatarGroupProps & react.RefAttributes<HTMLDivElement>>;
 
 declare const badgeStyles: (props?: ({
-    variant?: "outline" | "pink" | "purple" | "solid" | "ok" | "warn" | "err" | "neutral" | "accent" | null | undefined;
+    variant?: "outline" | "err" | "pink" | "purple" | "solid" | "ok" | "warn" | "accent" | "neutral" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface BadgeProps extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeStyles> {
@@ -443,6 +504,14 @@ interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>, Varia
     actions?: ReactNode;
     /** Footer slot rendered with a top divider beneath children. */
     footer?: ReactNode;
+    /**
+     * Keyboard activation handler. When provided, Enter/Space on a card with
+     * `role="button"` (i.e. `interactive` truthy) calls this instead of
+     * synthesizing a fake mouse event for `onClick` — downstream `e.button` /
+     * `e.clientX` reads from the synthesized event are `undefined`, so prefer
+     * `onActivate` when you need an intent-only callback.
+     */
+    onActivate?: () => void;
 }
 /**
  * Standard surface for a chunk of content. All cards share the same chrome
@@ -450,8 +519,37 @@ interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>, Varia
  *
  * Compose with the `<Card title="…" actions={…} footer={…}>` API for simple
  * cases, or pass children directly for full control.
+ *
+ * NOTE on `interactive`: a card with `interactive` resolves to
+ * `role="button" tabIndex=0`. If the same card also renders interactive
+ * children (e.g. via `actions`), screen readers see a button-inside-button —
+ * an axe `nested-interactive` violation. For "the whole card is one link"
+ * use `<CardLink>` instead. In the actions-present + interactive case we
+ * downgrade to a plain `<div>` (and warn in dev) so the assistive-tech tree
+ * stays valid.
  */
 declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLDivElement>>;
+interface CardLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'title'>, VariantProps<typeof cardStyles> {
+    /** Destination URL. The whole card becomes a single link to this URL. */
+    href: string;
+    /** Render a header row with this title. */
+    title?: ReactNode;
+    /** Description shown under the title (or above children when no title). */
+    description?: ReactNode;
+    /** Footer slot rendered with a top divider beneath children. */
+    footer?: ReactNode;
+}
+/**
+ * Whole-card link. Use this when "click anywhere on the card" should
+ * navigate — it renders a single `<a>` so assistive tech sees one link
+ * (no nested-interactive problem) and the browser handles middle-click,
+ * cmd-click, hover preview, etc. without bespoke wiring.
+ *
+ * Does not accept an `actions` slot: action buttons inside a link are a
+ * nested-interactive violation. Put per-card actions next to the card
+ * instead, or use the plain `<Card>` for non-link cards.
+ */
+declare const CardLink: react.ForwardRefExoticComponent<CardLinkProps & react.RefAttributes<HTMLAnchorElement>>;
 
 type StatTrend = 'up' | 'down' | 'flat';
 interface StatCardProps extends HTMLAttributes<HTMLDivElement> {
@@ -474,8 +572,10 @@ declare const StatCard: react.ForwardRefExoticComponent<StatCardProps & react.Re
 interface ChipProps extends HTMLAttributes<HTMLSpanElement> {
     /** Pill-style leading icon (typically a glyph or `@`/`#`). */
     icon?: ReactNode;
-    /** Optional remove handler — renders an inset close button. */
-    removable?: boolean;
+    /**
+     * Optional remove handler. When provided, renders an inset close button.
+     * Mirrors the `Tag` API — pass `onRemove` and the X is rendered automatically.
+     */
     onRemove?: () => void;
     children: ReactNode;
 }
@@ -501,8 +601,44 @@ interface SkeletonProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typ
     width?: number | string;
     /** Height override. Defaults differ by shape: `line` = 14, `block` = 80, `circle` = 40. */
     height?: number | string;
+    /**
+     * Render this Skeleton as its own loading announcement (`role="status"`,
+     * `aria-busy="true"`, `aria-label="Loading"`). Default `false` — Skeleton is
+     * `aria-hidden` so a list of N skeletons does not announce N times. Wrap a
+     * group of Skeletons in `<SkeletonGroup>` to get a single aggregate
+     * announcement, or set `standalone` when rendering a single isolated
+     * Skeleton with no surrounding live region.
+     */
+    standalone?: boolean;
 }
+/**
+ * Visual placeholder for content that is loading. By default, Skeleton is
+ * `aria-hidden` and emits no live-region announcement — wrap one or more
+ * Skeletons in `<SkeletonGroup loading>` to get a single "Loading" message
+ * for the whole group. For a single isolated Skeleton outside any group,
+ * pass `standalone` to restore the per-element `role="status"` semantic.
+ */
 declare const Skeleton: react.ForwardRefExoticComponent<SkeletonProps & react.RefAttributes<HTMLDivElement>>;
+interface SkeletonGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Optional override for the announcement text. Defaults to `"Loading"`.
+     * Pass something more specific (e.g., `"Loading inbox"`) when the context
+     * makes it useful.
+     */
+    label?: string;
+    /**
+     * When `false`, the group renders as a plain wrapper with no live region —
+     * useful when toggling between loading and loaded children inside the same
+     * mount. Default `true`.
+     */
+    loading?: boolean;
+}
+/**
+ * Wraps a group of `<Skeleton>` placeholders in a single `role="status"` /
+ * `aria-busy="true"` live region so screen readers announce one "Loading"
+ * message for the whole group instead of one per Skeleton.
+ */
+declare const SkeletonGroup: react.ForwardRefExoticComponent<SkeletonGroupProps & react.RefAttributes<HTMLDivElement>>;
 
 type StatusState = 'ok' | 'warn' | 'err' | 'off' | 'sync' | 'accent';
 interface StatusDotProps extends HTMLAttributes<HTMLSpanElement> {
@@ -600,8 +736,8 @@ interface SheetProps extends RadixDialog.DialogProps {
     children?: ReactNode;
 }
 /**
- * Bottom sheet overlay. Slides up from the bottom edge of the viewport, with a
- * subtle drag-handle. Useful for quick actions on mobile-leaning surfaces.
+ * Bottom sheet overlay. Slides up from the bottom edge of the viewport. Useful
+ * for quick actions on mobile-leaning surfaces.
  */
 declare const Sheet: react.ForwardRefExoticComponent<SheetProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -733,36 +869,46 @@ interface TooltipProps {
 declare function Tooltip({ content, children, side, delayDuration }: TooltipProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Alert — inline messaging block. Four tones (info / ok / warn / err) with a
+ * Alert — inline messaging block. Four tones (accent / ok / warn / err) with a
  * matching glyph, a left accent rule, and an optional dismiss action.
  *
  * For interrupting alerts (errors that need acknowledgment) use AlertDialog.
  * For transient feedback use Toast.
  */
-type AlertVariant = 'info' | 'ok' | 'warn' | 'err';
+type AlertTone = 'accent' | 'ok' | 'warn' | 'err';
 declare const alertStyles: (props?: ({
-    variant?: "ok" | "warn" | "err" | "info" | null | undefined;
+    tone?: "err" | "ok" | "warn" | "accent" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>, VariantProps<typeof alertStyles> {
     /** Bold title text. */
     title?: ReactNode;
     /** Body description. */
     description?: ReactNode;
-    /** Icon override; defaults to a glyph matched to the variant. */
+    /** Icon override; defaults to a glyph matched to the tone. */
     icon?: ReactNode;
     /** Optional trailing actions (rendered to the right of the description). */
     action?: ReactNode;
+    /**
+     * Aria-live behavior for the alert. Default `'polite'`.
+     *
+     * Alerts that are part of the initial page render should leave this at the
+     * default — `role="alert"` (which is `aria-live="assertive"`) interrupts the
+     * screen reader on every page load. Set `'assertive'` only for urgent
+     * alerts that appear *after* initial render. Set `'off'` to suppress
+     * announcements entirely (still rendered, still has `role="status"`).
+     */
+    live?: 'off' | 'polite' | 'assertive';
 }
 declare const Alert: react.ForwardRefExoticComponent<AlertProps & react.RefAttributes<HTMLDivElement>>;
 
 /**
  * Banner — top-of-page notice. Spans the full width of its container, uses a
- * tinted background derived from the variant color, and supports `sticky`
+ * tinted background derived from the tone color, and supports `sticky`
  * positioning so it stays at the top of the viewport on scroll.
  */
-type BannerVariant = 'info' | 'ok' | 'warn' | 'err';
+type BannerTone = 'accent' | 'ok' | 'warn' | 'err';
 declare const bannerStyles: (props?: ({
-    variant?: "ok" | "warn" | "err" | "info" | null | undefined;
+    tone?: "err" | "ok" | "warn" | "accent" | null | undefined;
     sticky?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface BannerProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof bannerStyles> {
@@ -770,6 +916,16 @@ interface BannerProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typeo
     icon?: ReactNode;
     /** Optional trailing action (e.g., a link). Rendered with `ml-auto`. */
     action?: ReactNode;
+    /**
+     * Aria-live behavior for the banner. Default `'polite'`.
+     *
+     * Banners that are part of the initial page render should leave this at the
+     * default — `role="alert"` (which is `aria-live="assertive"`) interrupts the
+     * screen reader on every page load. Set `'assertive'` only for urgent
+     * banners that appear *after* initial render. Set `'off'` to suppress
+     * announcements entirely (still rendered, still has `role="status"`).
+     */
+    live?: 'off' | 'polite' | 'assertive';
 }
 declare const Banner: react.ForwardRefExoticComponent<BannerProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -938,7 +1094,7 @@ interface DataTableProps<T> {
     /** Controlled selection. */
     selected?: ReadonlySet<string>;
     defaultSelected?: ReadonlyArray<string>;
-    onSelectionChange?: (selection: Set<string>) => void;
+    onSelectionChange?: (selection: ReadonlySet<string>) => void;
     /** Rendered when `data` is empty. */
     emptyState?: ReactNode;
     /** Sticky table header (requires the table to live in a scroll container). */
@@ -951,13 +1107,13 @@ declare function DataTable<T>(props: DataTableProps<T> & {
     ref?: Ref<HTMLTableElement>;
 }): react_jsx_runtime.JSX.Element;
 
-interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
-    /** Currently selected date. */
-    selected?: Date;
+interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'defaultValue'> {
+    /** Currently selected date (controlled). */
+    value?: Date;
     /** Default selected date (uncontrolled). */
-    defaultSelected?: Date;
-    /** Fires with the selected date. */
-    onSelect?: (date: Date) => void;
+    defaultValue?: Date;
+    /** Fires with the newly selected date. */
+    onValueChange?: (date: Date) => void;
     /** Currently visible month (0-indexed) and year. */
     month?: number;
     year?: number;
@@ -1014,15 +1170,42 @@ interface DotsProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
 }
 declare const Dots: react.ForwardRefExoticComponent<DotsProps & react.RefAttributes<HTMLElement>>;
 
+/**
+ * Dropzone — drag-and-drop file capture surface with a click-to-browse
+ * fallback. Manages its own drag-over state and forwards file drops to
+ * `onFiles`. Native `<input type="file">` covers keyboard / a11y.
+ */
+interface DropzoneProps extends Omit<LabelHTMLAttributes<HTMLLabelElement>, 'onDrop' | 'onDragOver' | 'onDragLeave' | 'title'> {
+    /** Fired with the dropped or selected files. */
+    onFiles?: (files: File[]) => void;
+    /** Limit accepted MIME types or extensions. Forwarded to the hidden input + filtered on drop. */
+    accept?: string;
+    /** Allow multiple files. Default true. */
+    multiple?: boolean;
+    /** Heading text. Default "Drop files to ingest". */
+    title?: ReactNode;
+    /** Subtitle / hint text rendered below the title. */
+    description?: ReactNode;
+    /** Glyph at the top of the surface. Default `↥`. */
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+declare const Dropzone: react.ForwardRefExoticComponent<DropzoneProps & react.RefAttributes<HTMLLabelElement>>;
+
 /**
  * EmptyState — placeholder for empty lists, no-results states, and error
  * surfaces. A 48×48 icon plate sits above a title + description and an
  * optional action area (button or chip stack).
+ *
+ * Tone controls the icon plate color. Omit `tone` for a neutral plate (the
+ * default for empty lists / no-results); pass `accent | ok | warn | err` to
+ * signal semantic intent (e.g., `err` for sync failures).
  */
 declare const plateStyles: (props?: ({
-    tone?: "accent" | "danger" | "muted" | null | undefined;
+    tone?: "err" | "ok" | "warn" | "accent" | "neutral" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
-interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>, VariantProps<typeof plateStyles> {
+type PlateVariantProps = VariantProps<typeof plateStyles>;
+interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
     /** Glyph or icon node shown in the rounded plate. */
     icon?: ReactNode;
     /** Title heading. */
@@ -1036,6 +1219,8 @@ interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>,
         label: ReactNode;
         onClick?: () => void;
     }>;
+    /** Semantic tone for the icon plate. Omit for the neutral default. */
+    tone?: Exclude<PlateVariantProps['tone'], 'neutral' | null | undefined> | undefined;
 }
 declare const EmptyState: react.ForwardRefExoticComponent<EmptyStateProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -1081,6 +1266,61 @@ interface MenubarItemProps extends RadixMenubar.MenubarItemProps {
 declare const MenubarItem: react.ForwardRefExoticComponent<MenubarItemProps & react.RefAttributes<HTMLDivElement>>;
 declare const MenubarSeparator: react.ForwardRefExoticComponent<RadixMenubar.MenubarSeparatorProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * NavBar — primary app navigation. The same component renders either as a
+ * horizontal top bar (`orientation="horizontal"`) or as a vertical side rail
+ * (`orientation="vertical"`); both layouts are driven by the same `items`
+ * tree. Items can carry nested `children` to produce dropdowns on
+ * horizontal and expand-collapse groups on vertical. Below `md` the bar
+ * collapses to a hamburger that opens a Drawer rendering the items
+ * vertically (set `responsive={false}` to opt out).
+ *
+ * Active state can be controlled (`value` + `onValueChange`) or uncontrolled
+ * (`defaultValue`). Items with an `href` render as anchors; otherwise as
+ * buttons that fire `onValueChange`.
+ */
+interface NavBarItem {
+    /** Stable identifier — what `value` / `onValueChange` reference. */
+    id: string;
+    label: ReactNode;
+    /** Optional left-of-label icon node. */
+    icon?: ReactNode;
+    /** When set, item renders as an `<a>`; otherwise as a `<button>`. */
+    href?: string;
+    /** Trailing badge text. */
+    badge?: ReactNode;
+    disabled?: boolean;
+    /** Nested items — dropdowns on horizontal, expand-groups on vertical. */
+    children?: NavBarItem[];
+}
+type NavBarOrientation = 'horizontal' | 'vertical';
+interface NavBarProps extends Omit<HTMLAttributes<HTMLElement>, 'defaultValue' | 'title'> {
+    /** Layout direction. Default `'horizontal'`. */
+    orientation?: NavBarOrientation;
+    /** Item tree driving the bar. */
+    items: NavBarItem[];
+    /**
+     * Brand / logo slot rendered at the start. When `responsive` is `true`,
+     * `brand` also seeds the mobile Drawer's accessible name, so it should
+     * include text — e.g. `<><Logo /> ShipIt</>` rather than `<Logo />` alone.
+     * Falls back to `'Navigation'` when omitted.
+     */
+    brand?: ReactNode;
+    /** Trailing slot for secondary actions (avatar, settings, theme toggle, …). */
+    actions?: ReactNode;
+    /** Controlled active item id. */
+    value?: string;
+    /** Uncontrolled initial active item id. */
+    defaultValue?: string;
+    /** Fired when an item is activated. */
+    onValueChange?: (id: string) => void;
+    /** Pixel width of the vertical rail. Default 240. */
+    width?: number;
+    /** Collapse to a hamburger drawer below `md`. Default `true`. */
+    responsive?: boolean;
+}
+declare const NavBar: react.ForwardRefExoticComponent<NavBarProps & react.RefAttributes<HTMLElement>>;
+
 /**
  * Pagination — page selector for paginated lists/tables. Renders prev/next
  * arrows plus a compact range of numbered pages. Use `siblings` to control how
@@ -1109,7 +1349,7 @@ declare const trackStyles: (props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare const fillStyles: (props?: ({
-    tone?: "ok" | "warn" | "err" | "accent" | null | undefined;
+    tone?: "err" | "ok" | "warn" | "accent" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'>, VariantProps<typeof trackStyles>, VariantProps<typeof fillStyles> {
     /** Numeric progress, 0..max. Ignored when `indeterminate`. */
@@ -1160,7 +1400,7 @@ interface SidebarProps extends HTMLAttributes<HTMLElement> {
     width?: number;
 }
 declare const Sidebar: react.ForwardRefExoticComponent<SidebarProps & react.RefAttributes<HTMLElement>>;
-interface NavItemProps extends HTMLAttributes<HTMLAnchorElement> {
+type NavItemBaseProps = {
     /** Left-side glyph or icon node. */
     icon?: ReactNode;
     /** Visible label. */
@@ -1169,17 +1409,39 @@ interface NavItemProps extends HTMLAttributes<HTMLAnchorElement> {
     active?: boolean;
     /** Optional trailing badge text. */
     badge?: ReactNode;
-    /** Optional href — when omitted, the row is rendered as a button. */
-    href?: string;
     /** Disabled / read-only display. */
     disabled?: boolean;
-}
-declare const NavItem: react.ForwardRefExoticComponent<NavItemProps & react.RefAttributes<HTMLAnchorElement>>;
+};
+type NavItemProps = NavItemBaseProps & (({
+    href: string;
+} & Omit<HTMLAttributes<HTMLAnchorElement>, keyof NavItemBaseProps>) | ({
+    href?: undefined;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof NavItemBaseProps>));
+declare const NavItem: react.ForwardRefExoticComponent<NavItemProps & react.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
 interface NavSectionProps extends HTMLAttributes<HTMLDivElement> {
     /** Eyebrow heading. Rendered uppercase, mono, dim. */
     label: ReactNode;
+    /** Optional leading glyph or icon node next to the eyebrow. */
+    icon?: ReactNode;
     /** Optional trailing element next to the heading (e.g., a `+` add affordance). */
     action?: ReactNode;
+    /**
+     * When true, the eyebrow becomes a button that toggles the body. The body
+     * is hidden when closed. Default `false` — the eyebrow stays static.
+     */
+    collapsible?: boolean;
+    /** Uncontrolled initial open state. Default `true`. Ignored when `open` is provided. */
+    defaultOpen?: boolean;
+    /** Controlled open state. */
+    open?: boolean;
+    /** Fires when the open state changes. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Pixel indent applied to the body. Useful when this section nests other
+     * sections — the indent visually anchors children to the eyebrow above.
+     * A subtle left rail is drawn alongside the indent. Default `0`.
+     */
+    indent?: number;
 }
 declare const NavSection: react.ForwardRefExoticComponent<NavSectionProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -1209,10 +1471,7 @@ interface SparklineProps extends Omit<SVGAttributes<SVGSVGElement>, 'children' |
 }
 declare const Sparkline: react.ForwardRefExoticComponent<SparklineProps & react.RefAttributes<SVGSVGElement>>;
 
-/**
- * Spinner — circular loading indicator. Three sizes; respects
- * `prefers-reduced-motion` via the global motion override in `tokens.css`.
- */
+/** Spinner — circular loading indicator. Three sizes. */
 declare const sizes: {
     readonly sm: {
         readonly box: "h-3 w-3";
@@ -1239,13 +1498,22 @@ declare const Spinner: react.ForwardRefExoticComponent<SpinnerProps & react.RefA
  * upcoming state from the `current` index so the consumer just passes labels.
  */
 type StepState = 'done' | 'current' | 'upcoming';
-interface StepperProps extends HTMLAttributes<HTMLDivElement> {
-    /** Ordered step labels. */
-    steps: ReadonlyArray<string>;
+/** A step in a Stepper. Pass either a bare string label or a `{ id?, label }` object. */
+type StepperStep = string | {
+    id?: string;
+    label: string;
+};
+interface StepperProps extends HTMLAttributes<HTMLOListElement> {
+    /**
+     * Ordered steps. A step may be either a bare string label or an object
+     * `{ id?, label }`. Use `id` to give React a stable key when two steps
+     * share a label (e.g. ["Plan", "Plan Review"]).
+     */
+    steps: ReadonlyArray<StepperStep>;
     /** Zero-based index of the current step. Steps before are `done`, after are `upcoming`. */
     current: number;
 }
-declare const Stepper: react.ForwardRefExoticComponent<StepperProps & react.RefAttributes<HTMLDivElement>>;
+declare const Stepper: react.ForwardRefExoticComponent<StepperProps & react.RefAttributes<HTMLOListElement>>;
 
 /**
  * Tabs — two visual styles built on Radix Tabs.
@@ -1314,15 +1582,6 @@ interface TopbarProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
 }
 declare const Topbar: react.ForwardRefExoticComponent<TopbarProps & react.RefAttributes<HTMLElement>>;
 
-/**
- * Tree — recursive expandable list. Pass a nested `items` tree; the component
- * handles expand/collapse and selection state. Both can be uncontrolled
- * (`defaultExpanded` / `defaultSelected`) or controlled (`expanded` /
- * `selected` + change callbacks).
- *
- * Implements the simple `aria-tree` pattern: `role="tree"` on the container,
- * `role="treeitem"` on each row, `aria-level`, `aria-expanded`, `aria-selected`.
- */
 interface TreeItem {
     id: string;
     label: ReactNode;
@@ -1340,14 +1599,14 @@ interface TreeProps extends Omit<HTMLAttributes<HTMLUListElement>, 'onSelect'> {
     /** Default expanded ids (uncontrolled). */
     defaultExpanded?: ReadonlyArray<string>;
     /** Fires with the new expanded set whenever a node toggles. */
-    onExpandedChange?: (expanded: Set<string>) => void;
+    onExpandedChange?: (expanded: ReadonlySet<string>) => void;
     /** Controlled selected node id. */
-    selected?: string;
+    value?: string;
     /** Default selected (uncontrolled). */
-    defaultSelected?: string;
+    defaultValue?: string;
     /** Fires with the selected node id. */
-    onSelect?: (id: string) => void;
+    onValueChange?: (id: string) => void;
 }
 declare const Tree: react.ForwardRefExoticComponent<TreeProps & react.RefAttributes<HTMLUListElement>>;
 
-export { Alert, AlertDialog, AlertDialogAction, AlertDialogCancel, type AlertDialogProps, AlertDialogRoot, AlertDialogTrigger, type AlertProps, type AlertVariant, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, Badge, type BadgeProps, Banner, type BannerProps, type BannerVariant, Breadcrumbs, type BreadcrumbsProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Calendar, type CalendarProps, Card, type CardProps, Checkbox, type CheckboxProps, Chip, type ChipProps, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteGroup, type CommandPaletteItem, type CommandPaletteProps, ContextMenu, ContextMenuContent, ContextMenuItem, type ContextMenuItemProps, ContextMenuPortal, ContextMenuRoot, ContextMenuSeparator, ContextMenuTrigger, Crumb, type CrumbProps, DataTable, type DataTableColumn, type DataTableProps, type DataTableSort, DatePicker, type DatePickerProps, Dialog, DialogClose, DialogContent, type DialogContentProps, DialogOverlay, DialogPortal, type DialogProps, DialogRoot, DialogTrigger, Dots, type DotsProps, Drawer, type DrawerProps, type DrawerSide, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRoot, DropdownMenuTrigger, EmptyState, type EmptyStateProps, FAB, type FABProps, Field, type FieldProps, FileChip, type FileChipProps, HoverCard, HoverCardContent, HoverCardPortal, type HoverCardProps, HoverCardRoot, HoverCardTrigger, IconButton, type IconButtonProps, Input, type InputProps, Kbd, type KbdProps, MenuCheckboxItem, MenuItem, type MenuItemProps, MenuSeparator, Menubar, MenubarContent, MenubarItem, type MenubarItemProps, MenubarMenu, MenubarSeparator, MenubarTrigger, NavItem, type NavItemProps, NavSection, type NavSectionProps, type NormalizedOption, OTP, type OTPHandle, type OTPProps, Pagination, type PaginationProps, Popover, PopoverAnchor, PopoverArrow, PopoverClose, PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger, Progress, type ProgressProps, RadialProgress, type RadialProgressProps, type RadialTone, Radio, RadioGroup, type RadioGroupProps, type RadioProps, SearchInput, type SearchInputProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, type SelectOption, type SelectProps, SelectRoot, SelectTrigger, SelectValue, Sheet, type SheetProps, Sidebar, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineProps, Spinner, type SpinnerProps, SplitButton, type SplitButtonProps, StatCard, type StatCardProps, type StatTrend, StatusDot, type StatusDotProps, type StatusState, type StepState, Stepper, type StepperProps, Switch, type SwitchProps, Tab, type TabProps, Tabs, TabsContent, TabsList, type TabsProps, type TabsVariantProps, Tag, type TagProps, Textarea, type TextareaProps, type Theme, Timeline, type TimelineEvent, type TimelineEventTone, TimelineItem, type TimelineItemProps, type TimelineProps, ToastCard, type ToastInput, ToastProvider, type ToastVariant, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, type TooltipProps, TooltipProvider, TooltipRoot, TooltipTrigger, Topbar, type TopbarProps, Tree, type TreeItem, type TreeProps, type UseControllableStateProps, type UseKeyboardListOptions, type UseKeyboardListResult, badgeStyles, buttonStyles, cardStyles, cn, filterCommandItems, iconButtonStyles, useControllableState, useDisclosure, useEscape, useKeyboardList, useOutsideClick, useTheme, useToast };
+export { Alert, AlertDialog, AlertDialogAction, AlertDialogCancel, type AlertDialogProps, AlertDialogRoot, AlertDialogTrigger, type AlertProps, type AlertTone, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, Badge, type BadgeProps, Banner, type BannerProps, type BannerTone, Breadcrumbs, type BreadcrumbsProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Calendar, type CalendarProps, Card, CardLink, type CardLinkProps, type CardProps, Checkbox, type CheckboxProps, Chip, type ChipProps, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteGroup, type CommandPaletteItem, type CommandPaletteProps, ContextMenu, ContextMenuContent, ContextMenuItem, type ContextMenuItemProps, ContextMenuPortal, ContextMenuRoot, ContextMenuSeparator, ContextMenuTrigger, Crumb, type CrumbProps, DataTable, type DataTableColumn, type DataTableProps, type DataTableSort, DatePicker, type DatePickerProps, Dialog, DialogClose, DialogContent, type DialogContentProps, DialogOverlay, DialogPortal, type DialogProps, DialogRoot, DialogTrigger, Dots, type DotsProps, Drawer, type DrawerProps, type DrawerSide, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRoot, DropdownMenuTrigger, Dropzone, type DropzoneProps, EmptyState, type EmptyStateProps, FAB, type FABProps, Field, type FieldProps, FileChip, type FileChipProps, HoverCard, HoverCardContent, HoverCardPortal, type HoverCardProps, HoverCardRoot, HoverCardTrigger, IconButton, type IconButtonProps, Input, type InputProps, Kbd, type KbdProps, MenuCheckboxItem, MenuItem, type MenuItemProps, MenuSeparator, Menubar, MenubarContent, MenubarItem, type MenubarItemProps, MenubarMenu, MenubarSeparator, MenubarTrigger, NavBar, type NavBarItem, type NavBarOrientation, type NavBarProps, NavItem, type NavItemProps, NavSection, type NavSectionProps, type NormalizedOption, OTP, type OTPHandle, type OTPProps, Pagination, type PaginationProps, Popover, PopoverAnchor, PopoverArrow, PopoverClose, PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger, Progress, type ProgressProps, RadialProgress, type RadialProgressProps, type RadialTone, Radio, RadioGroup, type RadioGroupProps, type RadioProps, SearchInput, type SearchInputProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, type SelectOption, type SelectProps, SelectRoot, SelectTrigger, SelectValue, Sheet, type SheetProps, Sidebar, type SidebarProps, Skeleton, SkeletonGroup, type SkeletonGroupProps, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineProps, Spinner, type SpinnerProps, SplitButton, type SplitButtonProps, StatCard, type StatCardProps, type StatTrend, StatusDot, type StatusDotProps, type StatusState, type StepState, Stepper, type StepperProps, type StepperStep, Switch, type SwitchProps, Tab, type TabProps, Tabs, TabsContent, TabsList, type TabsProps, type TabsVariantProps, Tag, type TagProps, Textarea, type TextareaProps, type Theme, Timeline, type TimelineEvent, type TimelineEventTone, TimelineItem, type TimelineItemProps, type TimelineProps, ToastCard, type ToastInput, ToastProvider, type ToastVariant, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, type TooltipProps, TooltipProvider, TooltipRoot, TooltipTrigger, Topbar, type TopbarProps, Tree, type TreeItem, type TreeProps, type UseControllableStateProps, type UseKeyboardListOptions, type UseKeyboardListResult, badgeStyles, buttonStyles, cardStyles, cn, filterCommandItems, iconButtonStyles, useControllableState, useDisclosure, useEscape, useIsomorphicLayoutEffect, useKeyboardList, useOutsideClick, useTheme, useToast };