@preset.nz/ux-kit 0.1.1 → 0.1.2

package/README.md

@@ -15,44 +15,7 @@ Like [facets](https://github.com/preset-nz/facets), the kit ships unbuilt TypeSc
 
 ## Components
 
-Union of the `src/components/ui` folders in Strata, Oblique, Shard and Map & Territory (Fault has none). Where several apps had the same component, the richest variant was taken. All are exported from the package index.
-
-| Component | In kit | Came from | Notes |
-|---|---|---|---|
-| button | yes | Strata, Shard, M&T | Base UI Button |
-| checkbox | yes | Strata, Oblique, Shard | |
-| input | yes | all four | |
-| label | yes | Strata, Oblique, Shard | |
-| select | yes | Strata, Oblique, Shard | |
-| separator | yes | all four | |
-| dialog | yes | Oblique, Shard, M&T | Shard's themed variant. `render={<Button />}` replaces `asChild` |
-| sheet | yes | M&T | Base UI Dialog docked to an edge (`side`) |
-| popover | yes | Oblique | `PopoverAnchor` dropped: Base UI anchors through the Positioner's `anchor` prop |
-| tooltip | yes | Oblique, M&T | `TooltipProvider delay` replaces `delayDuration` |
-| tabs | yes | Oblique | `TabsTrigger` / `TabsContent` wrap Base UI `Tab` / `Panel`. Orientation uses `data-[orientation=...]` |
-| toggle | yes | Oblique | `data-pressed` replaces `data-[state=on]` |
-| toggle-group | yes | Oblique | Base UI `value` is always an array and `multiple` replaces `type="single" \| "multiple"` |
-| slider | yes | Oblique, Shard, M&T | Takes a number or an array; one thumb per value |
-| dropdown-menu | yes | Shard, M&T | M&T's fuller variant. `DropdownMenuLabel` is Base UI's `GroupLabel`, so it must sit inside a `DropdownMenuGroup` |
-| context-menu | yes | Shard | Same shape as dropdown-menu, same `Label` caveat |
-| navigation-menu | yes | M&T | Always the shared-viewport form. Radix's `NavigationMenuIndicator` and the `viewport={false}` mode are gone |
-| snackbar | yes | Strata, Oblique | The kit's one toast, on Base UI Toast. `useSnackbar().show({ message, kind, description, action, persistent, timeout })` returns an id and `dismiss(id?)` closes one or all; kinds are `plain`, `success`, `warning`, `error`. Mount `SnackbarProvider` once and a `SnackbarViewport` inside it. `notify(opts)` and `dismissNotification(id?)` do the same from outside React |
-| avatar | yes | M&T | Base UI Avatar |
-| badge | yes | M&T | Plain, `render` prop replaces `asChild` |
-| breadcrumb | yes | M&T | Plain `<a>`, no `next/link`. Use `render` for a router link |
-| card | yes | M&T | Plain |
-| skeleton | yes | M&T | Plain |
-| textarea | yes | M&T | Plain, restyled to match Input |
-| sidebar | yes | M&T | Plain, 700 lines. `asChild` became `render`. `useIsMobile` moved into the kit. Untested beyond the `collapsible="none"` form in the playground |
-| toolbar | yes | Oblique, M&T | Base UI Toolbar (roving focus). `ToolbarItems` takes `groups` of `ToolbarItemSpec` (id, label, icon, shortcut, enabled, disabledReason, pressed, menu) and `onCommand(id)`; Oblique's `ToolButtonSpec` table with M&T's disabled reason. Disabled items stay focusable so the tooltip can say why. `ToolbarButton`, `ToolbarGroup`, `ToolbarSeparator`, `ToolbarSpacer` compose by hand. Shard's header buttons are inline JSX and Fault's are not a toolbar, so neither contributed |
-| color-field | yes | M&T, Oblique, Strata | Swatch, hex text (commits on blur or Enter, bad input reverts), optional alpha (`#rrggbbaa`), preset grid in a Popover, native picker with `onPickStart`/`onPickEnd` for undo transactions (Oblique), `clearable` and null value (Strata, Oblique's optional colour), read-only, `trailing` slot for an eyedropper |
-| number-field | yes | Base UI, Oblique | Base UI NumberField with the label as the ScrubArea (drag it; click it to type). Shift is coarse (x10), Alt/Option fine (x0.1), as Oblique's InputNumber, and `integer` keeps Alt on whole steps (integerStepFix). `onValueChange(value, { reason })` is `scrub`, `step` or `typed` (typed commits on blur or Enter, never per keystroke; Escape reverts). `onScrubStart`/`onScrubEnd` bracket one drag as the undo transaction, `onScrubCancel` is Escape mid-drag. `VectorField` is N of them with X/Y/Z/W labels. Scrubbing only on the label: no gutter scrub |
-| color-swatch | yes | Strata, M&T, Oblique | Chip over a checkerboard; `null` is the dashed empty chip |
-| side-panel | yes | Strata, M&T | Docked panel, props only (`open`, `width` owned by the app). Collapsed it leaves an icon rail that reopens it; the inner edge resizes by pointer drag (pointer capture) or arrow keys, clamped by `clampWidth`. `SidePanelHeader`, `SidePanelContent`. Strata's `SidePanel` ideas; persistence stays app-side |
-| status-bar | yes | Oblique, Strata, M&T | `StatusBar`, `StatusItem` (optional label), `StatusSpacer`. Contents stay app-side |
-| empty-state | yes | new | Icon, title, description, action slot |
-
-M&T's `src/palettes/` (presets and derivation) was considered for the colour field and left out: it is map domain data and stays in the app, which passes its colours in through `presets`.
+Every component is exported from `src/index.ts`, which is the list. Each file's top comment says how it differs from shadcn and Radix. M&T's `src/palettes/` (presets and derivation) stays in the app, as map domain data; it passes its colours to the colour field through `presets`.
 
 ## Using it
 
@@ -107,12 +70,11 @@ The components are adapted from Vercel AI Elements (Apache-2.0) and shadcn/ui's
 ## Working on it
 
 ```sh
-just install   # pnpm install
+just install   # pnpm install, and the playground's crates
 just dev       # the playground as a desktop app
-just check     # typecheck and lint the kit
-just check-all # the kit, the playground and cargo check
+just check     # the kit, the playground and cargo check
 ```
 
-The playground links the sibling packages (rhizome, app-kit, preferences, facets, math), so `just dev` and `just check-all` need them checked out next to this repo. `just check` needs only this repo.
+Run them in `ux-kit/` of [preset-nz/packages](https://github.com/preset-nz/packages). The playground links the other packages in that repo (rhizome, app-kit, preferences, facets, math), so a change to one of them that breaks it fails `just check`.
 
 MIT.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@preset.nz/ux-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "One look and one way of working for the preset.nz desktop apps: tokens, palettes, fonts and Base UI primitives.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/preset-nz/ux-kit.git"
+    "url": "git+https://github.com/preset-nz/packages.git",
+    "directory": "ux-kit"
   },
   "type": "module",
   "sideEffects": [
@@ -30,13 +31,13 @@
     "@fontsource-variable/geist": "^5.2.9",
     "@fontsource-variable/jetbrains-mono": "^5.2.8",
     "@phosphor-icons/react": "^2.1.10",
-    "@preset.nz/math": "^0.1.0",
     "@shadcn/react": "^0.3.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "streamdown": "^2.7.0",
     "tailwind-merge": "^3.6.0",
-    "tw-animate-css": "^1.4.0"
+    "tw-animate-css": "^1.4.0",
+    "@preset.nz/math": "^0.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",

package/src/components/alert-shell.tsx

@@ -0,0 +1,66 @@
+import { AlertDialog as AlertDialogPrimitive } from "@base-ui/react/alert-dialog"
+import type * as React from "react"
+import { cn } from "../lib/utils"
+import { DialogFooter, DialogHeader, DialogOverlay } from "./dialog"
+
+// AlertShell: the markup ConfirmDialog and DownloadPrompt share. Internal, not
+// exported from the package. It is answered, not dismissed: no close "x", and a
+// click outside does nothing, so the footer buttons and Escape are the ways out.
+
+interface AlertShellProps {
+  open: boolean
+  /** Escape. The caller decides what that means (and may ignore it). */
+  onDismiss: () => void
+  title: string
+  /** The body, below the title. */
+  children?: React.ReactNode
+  /** The buttons, secondary first and primary last. */
+  footer: React.ReactNode
+  /** The element that takes focus when the dialog opens. */
+  initialFocus?: React.RefObject<HTMLElement | null>
+}
+
+function AlertShell({ open, onDismiss, title, children, footer, initialFocus }: AlertShellProps) {
+  return (
+    <AlertDialogPrimitive.Root
+      data-slot="confirm-dialog"
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) onDismiss()
+      }}
+    >
+      <AlertDialogPrimitive.Portal data-slot="confirm-dialog-portal">
+        <DialogOverlay />
+        <AlertDialogPrimitive.Popup
+          data-slot="confirm-dialog-content"
+          initialFocus={initialFocus}
+          className={cn(
+            "fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-6 rounded-xl bg-popover p-6 text-sm text-popover-foreground ring-1 ring-foreground/10 duration-100 outline-none sm:max-w-md data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          )}
+        >
+          <DialogHeader>
+            <AlertDialogPrimitive.Title
+              data-slot="dialog-title"
+              className="font-heading leading-none font-medium"
+            >
+              {title}
+            </AlertDialogPrimitive.Title>
+            {children ? (
+              <AlertDialogPrimitive.Description
+                render={<div />}
+                data-slot="dialog-description"
+                className="text-sm text-muted-foreground"
+              >
+                {children}
+              </AlertDialogPrimitive.Description>
+            ) : null}
+          </DialogHeader>
+          <DialogFooter>{footer}</DialogFooter>
+        </AlertDialogPrimitive.Popup>
+      </AlertDialogPrimitive.Portal>
+    </AlertDialogPrimitive.Root>
+  )
+}
+
+export type { AlertShellProps }
+export { AlertShell }

package/src/components/badge.tsx

@@ -4,6 +4,8 @@ import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "../lib/utils"
 
+// Badge: a plain span. The `render` prop replaces Radix's `asChild`.
+
 const badgeVariants = cva(
   "inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-md border px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3",
   {

package/src/components/confirm-dialog.tsx

@@ -0,0 +1,93 @@
+import * as React from "react"
+import { AlertShell } from "./alert-shell"
+import { Button } from "./button"
+
+// ConfirmDialog: ask before something that can't be taken back. Controlled
+// only; the caller owns `open`. It is answered, not dismissed: no close "x",
+// and a click outside does nothing, so Cancel and Escape are the ways out.
+
+interface ConfirmDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  title: string
+  /** The body: text, or a node (a list of apps, a size). */
+  children?: React.ReactNode
+  /** What the action is called: "Remove", never "OK". */
+  confirmLabel: string
+  /** Defaults to "Cancel". */
+  cancelLabel?: string
+  /** Confirm uses the destructive Button variant and initial focus is Cancel. */
+  destructive?: boolean
+  /** While a returned promise is pending the dialog stays open; a rejection keeps it open. */
+  onConfirm: () => void | Promise<void>
+}
+
+function ConfirmDialog({
+  open,
+  onOpenChange,
+  title,
+  children,
+  confirmLabel,
+  cancelLabel = "Cancel",
+  destructive = false,
+  onConfirm,
+}: ConfirmDialogProps) {
+  const [pending, setPending] = React.useState(false)
+  const cancelRef = React.useRef<HTMLButtonElement>(null)
+  const confirmRef = React.useRef<HTMLButtonElement>(null)
+
+  // Nothing closes the dialog while the action runs.
+  const handleOpenChange = (next: boolean) => {
+    if (pending && !next) return
+    onOpenChange(next)
+  }
+
+  const handleConfirm = async () => {
+    if (pending) return
+    setPending(true)
+    try {
+      await onConfirm()
+    } catch {
+      // The caller shows its own failure; the dialog stays open.
+      setPending(false)
+      return
+    }
+    setPending(false)
+    onOpenChange(false)
+  }
+
+  return (
+    <AlertShell
+      open={open}
+      onDismiss={() => handleOpenChange(false)}
+      title={title}
+      initialFocus={destructive ? cancelRef : confirmRef}
+      footer={
+        <>
+          <Button
+            ref={cancelRef}
+            variant="outline"
+            disabled={pending}
+            onClick={() => handleOpenChange(false)}
+          >
+            {cancelLabel}
+          </Button>
+          <Button
+            ref={confirmRef}
+            variant={destructive ? "destructive" : "default"}
+            disabled={pending}
+            focusableWhenDisabled
+            onClick={handleConfirm}
+          >
+            {confirmLabel}
+          </Button>
+        </>
+      }
+    >
+      {children}
+    </AlertShell>
+  )
+}
+
+export type { ConfirmDialogProps }
+export { ConfirmDialog }

package/src/components/context-menu.tsx

@@ -4,6 +4,9 @@ import type * as React from "react"
 
 import { cn } from "../lib/utils"
 
+// Base UI: `ContextMenuLabel` is Base UI's `GroupLabel`, so it must sit inside a `ContextMenuGroup`.
+// Same shape as DropdownMenu.
+
 function ContextMenu({ ...props }: ContextMenuPrimitive.Root.Props) {
   return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />
 }

package/src/components/dialog.tsx

@@ -5,6 +5,9 @@ import type * as React from "react"
 import { cn } from "../lib/utils"
 import { Button } from "./button"
 
+// Dialog: Base UI Dialog in the kit's theme. Triggers and closers take
+// `render={<Button />}` where Radix used `asChild`.
+
 function Dialog({ ...props }: DialogPrimitive.Root.Props) {
   return <DialogPrimitive.Root data-slot="dialog" {...props} />
 }

package/src/components/download-prompt.tsx

@@ -0,0 +1,108 @@
+import * as React from "react"
+import { AlertShell } from "./alert-shell"
+import { Button } from "./button"
+import { formatBytes, Progress } from "./progress"
+
+// DownloadPrompt: one dialog for a download, in three states the caller drives:
+// ask first, show progress, offer Retry. It owns no timer and no network; the
+// caller sets `state` to null when the download is done. Escape always means
+// "stop": Not now, Cancel, Close.
+
+type DownloadPromptProps = {
+  /** `null` is closed. */
+  state: "ask" | "downloading" | "failed" | null
+  /** "Smart Select needs a model". */
+  title: string
+  /** What is being downloaded: "MobileSAM". */
+  name: string
+  /** Formatted by the caller; an omitted fact is left out of the line. */
+  facts: { size?: string; licence?: string; host?: string }
+  /** Bytes, while downloading. Without it the bar is indeterminate. */
+  progress?: { done: number; total: number }
+  /** One line, when failed. */
+  reason?: string
+  /** ask: Download. */
+  onDownload: () => void
+  /** ask: Not now. failed: Close. */
+  onDismiss: () => void
+  /** downloading: Cancel. */
+  onCancel: () => void
+  /** failed: Retry. */
+  onRetry: () => void
+}
+
+function DownloadPrompt(props: DownloadPromptProps) {
+  // Keep the last open props so the closing animation shows the old content, not a blank dialog.
+  const last = React.useRef<DownloadPromptProps & { state: "ask" | "downloading" | "failed" }>(null)
+  if (props.state !== null) last.current = { ...props, state: props.state }
+  const shown = last.current
+  const focusRef = React.useRef<HTMLButtonElement>(null)
+
+  // initialFocus only acts on open. A state change swaps the buttons out from under the focus,
+  // so move it to the new state's default button.
+  React.useEffect(() => {
+    if (props.state !== null) focusRef.current?.focus()
+  }, [props.state])
+
+  if (shown === null) return null
+  const { state, title, name, facts, progress, reason } = shown
+  // Callbacks come from the live props: the stored copy may be a render old.
+  const live = props
+  const onEscape = state === "downloading" ? live.onCancel : live.onDismiss
+
+  const factLine = [facts.size, facts.licence, facts.host ? `from ${facts.host}` : undefined]
+    .filter(Boolean)
+    .join(" · ")
+
+  return (
+    <AlertShell
+      open={props.state !== null}
+      onDismiss={onEscape}
+      title={title}
+      initialFocus={focusRef}
+      footer={
+        state === "ask" ? (
+          <>
+            <Button variant="outline" onClick={live.onDismiss}>
+              Not now
+            </Button>
+            <Button ref={focusRef} onClick={live.onDownload}>
+              Download
+            </Button>
+          </>
+        ) : state === "downloading" ? (
+          <Button ref={focusRef} variant="outline" onClick={live.onCancel}>
+            Cancel
+          </Button>
+        ) : (
+          <>
+            <Button variant="outline" onClick={live.onDismiss}>
+              Close
+            </Button>
+            <Button ref={focusRef} onClick={live.onRetry}>
+              Retry
+            </Button>
+          </>
+        )
+      }
+    >
+      <p className="font-medium text-foreground">{name}</p>
+      {state === "ask" && factLine ? <p className="mt-1">{factLine}</p> : null}
+      {state === "downloading" ? (
+        <Progress
+          className="mt-3"
+          label={name}
+          value={progress ? progress.done : null}
+          max={progress?.total}
+          detail={
+            progress ? `${formatBytes(progress.done)} / ${formatBytes(progress.total)}` : undefined
+          }
+        />
+      ) : null}
+      {state === "failed" && reason ? <p className="mt-1">{reason}</p> : null}
+    </AlertShell>
+  )
+}
+
+export type { DownloadPromptProps }
+export { DownloadPrompt }

package/src/components/dropdown-menu.tsx

@@ -4,6 +4,9 @@ import type * as React from "react"
 
 import { cn } from "../lib/utils"
 
+// Base UI: `DropdownMenuLabel` is Base UI's `GroupLabel`, so it must sit inside a `DropdownMenuGroup`.
+// Same shape as ContextMenu.
+
 function DropdownMenu({ ...props }: MenuPrimitive.Root.Props) {
   return <MenuPrimitive.Root data-slot="dropdown-menu" {...props} />
 }

package/src/components/list.tsx

@@ -0,0 +1,205 @@
+import * as React from "react"
+
+import { cn } from "../lib/utils"
+
+// List and ListRow: a set of things (models, files, recent items) built from
+// slots. Without `selection` it is a plain `role="list"` and the rows'
+// `trailing` actions are the only interactive parts (Tab walks them). With
+// `selection` it is a `role="listbox"` with roving tabindex: Up, Down, Home
+// and End move focus, Enter or Space selects. Rows must be direct children of
+// the List (the List reads their ids). A selectable list takes no `trailing`
+// controls: a button inside an option is invalid ARIA, and its click would
+// select the row too. No virtualisation, reorder or sections.
+//
+// `className` and other props go on the List's outer element; the accessible
+// name (`aria-label`, `aria-labelledby`) goes on the element with the role.
+
+interface ListSelection {
+  selectedId: string | null
+  onSelect: (id: string) => void
+}
+
+interface ListContextValue {
+  selection: ListSelection | undefined
+  tabStopId: string | undefined
+  setFocusId: (id: string) => void
+}
+
+const ListContext = React.createContext<ListContextValue>({
+  selection: undefined,
+  tabStopId: undefined,
+  setFocusId: () => {},
+})
+
+interface ListProps extends Omit<React.ComponentProps<"div">, "role" | "children"> {
+  /** Makes the list a selectable listbox. Leave undefined for a plain list. */
+  selection?: ListSelection
+  /** Shown in place of the rows when there are no children. Usually an EmptyState. */
+  empty?: React.ReactNode
+  /** After the rows. */
+  footer?: React.ReactNode
+  children?: React.ReactNode
+}
+
+function List({
+  selection,
+  empty,
+  footer,
+  className,
+  children,
+  onKeyDown,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  ...props
+}: ListProps) {
+  const rows = React.Children.toArray(children)
+  const ids = rows.flatMap((row) =>
+    React.isValidElement<{ id?: string }>(row) && typeof row.props.id === "string"
+      ? [row.props.id]
+      : [],
+  )
+  const [focusId, setFocusId] = React.useState<string | undefined>(undefined)
+  const rowsRef = React.useRef<HTMLDivElement>(null)
+
+  // The one tab stop: the last focused row, else the selected one, else the first.
+  const tabStopId =
+    [focusId, selection?.selectedId ?? undefined].find(
+      (id): id is string => id !== undefined && ids.includes(id),
+    ) ?? ids[0]
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event)
+    if (!selection || event.defaultPrevented) return
+    const options = Array.from(
+      rowsRef.current?.querySelectorAll<HTMLElement>('[role="option"]') ?? [],
+    )
+    const current = options.indexOf(event.target as HTMLElement)
+    if (current === -1) return
+    let next: number
+    switch (event.key) {
+      case "ArrowDown":
+        next = Math.min(current + 1, options.length - 1)
+        break
+      case "ArrowUp":
+        next = Math.max(current - 1, 0)
+        break
+      case "Home":
+        next = 0
+        break
+      case "End":
+        next = options.length - 1
+        break
+      default:
+        return
+    }
+    event.preventDefault()
+    options[next]?.focus()
+  }
+
+  const context = React.useMemo<ListContextValue>(
+    () => ({ selection, tabStopId, setFocusId }),
+    [selection, tabStopId],
+  )
+
+  return (
+    <div data-slot="list" className={cn("flex flex-col", className)} {...props}>
+      {rows.length === 0 ? (
+        empty
+      ) : (
+        <ListContext.Provider value={context}>
+          {/* biome-ignore lint/a11y/noStaticElementInteractions: arrow keys on the listbox are the roving-tabindex pattern, the options hold the focus */}
+          {/* biome-ignore lint/a11y/useAriaPropsSupportedByRole: the role is always list or listbox, and both take a name; Biome can't read the ternary */}
+          <div
+            ref={rowsRef}
+            role={selection ? "listbox" : "list"}
+            aria-label={ariaLabel}
+            aria-labelledby={ariaLabelledBy}
+            data-slot="list-rows"
+            className="flex flex-col divide-y divide-border"
+            onKeyDown={handleKeyDown}
+          >
+            {rows}
+          </div>
+        </ListContext.Provider>
+      )}
+      {footer && rows.length > 0 ? (
+        <div
+          data-slot="list-footer"
+          className="border-t border-border px-3 py-2 text-sm text-muted-foreground"
+        >
+          {footer}
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+interface ListRowProps
+  extends Omit<
+    React.ComponentProps<"div">,
+    "id" | "title" | "role" | "children" | "onClick" | "onSelect"
+  > {
+  /** Identifies the row to `selection`. Not set as the DOM id. */
+  id: string
+  /** Before the text: an icon or thumbnail. */
+  leading?: React.ReactNode
+  title: React.ReactNode
+  /** One muted line under the title. */
+  detail?: React.ReactNode
+  /** After the text: a Button, a Badge. Clickable things go here, not on the row, and only in a plain list. */
+  trailing?: React.ReactNode
+}
+
+function ListRow({ id, leading, title, detail, trailing, className, ...props }: ListRowProps) {
+  const { selection, tabStopId, setFocusId } = React.useContext(ListContext)
+  const selectable = selection !== undefined
+  const selected = selectable && selection.selectedId === id
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    props.onKeyDown?.(event)
+    // Keys from a trailing control stay with that control.
+    if (!selectable || event.defaultPrevented || event.target !== event.currentTarget) return
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault()
+      selection.onSelect(id)
+    }
+  }
+
+  return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: the role is option when selectable; a plain row has no handlers that act
+    // biome-ignore lint/a11y/useAriaPropsSupportedByRole: aria-selected is set only when the role is option
+    <div
+      data-slot="list-row"
+      data-row-id={id}
+      data-selected={selected ? "" : undefined}
+      role={selectable ? "option" : "listitem"}
+      aria-selected={selectable ? selected : undefined}
+      tabIndex={selectable ? (tabStopId === id ? 0 : -1) : undefined}
+      className={cn(
+        "flex min-h-11 items-center gap-3 px-3 py-1.5 outline-none",
+        selectable &&
+          "cursor-default hover:bg-accent/50 focus-visible:bg-accent/50 focus-visible:ring-[3px] focus-visible:ring-inset focus-visible:ring-ring/50 data-selected:bg-accent",
+        className,
+      )}
+      {...props}
+      onKeyDown={handleKeyDown}
+      onFocus={(event) => {
+        props.onFocus?.(event)
+        if (selectable && event.target === event.currentTarget) setFocusId(id)
+      }}
+      onClick={selectable ? () => selection.onSelect(id) : undefined}
+    >
+      {leading ? (
+        <div className="shrink-0 text-muted-foreground [&_svg]:size-5">{leading}</div>
+      ) : null}
+      <div className="min-w-0 flex-1">
+        <p className="truncate text-sm font-medium">{title}</p>
+        {detail ? <p className="truncate text-xs text-muted-foreground">{detail}</p> : null}
+      </div>
+      {trailing ? <div className="flex shrink-0 items-center gap-2">{trailing}</div> : null}
+    </div>
+  )
+}
+
+export type { ListProps, ListRowProps, ListSelection }
+export { List, ListRow }

package/src/components/navigation-menu.tsx

@@ -7,6 +7,7 @@ import { cn } from "../lib/utils"
 // Base UI renders content through a shared Portal > Positioner > Popup >
 // Viewport. NavigationMenu bundles that, so `NavigationMenuContent` items
 // morph inside one popup like the shadcn viewport variant.
+// Always the shared-viewport form: the Radix indicator and viewport={false} mode are gone.
 function NavigationMenu({
   className,
   children,

package/src/components/popover.tsx

@@ -3,6 +3,9 @@ import type * as React from "react"
 
 import { cn } from "../lib/utils"
 
+// Popover: Base UI Popover. There is no `PopoverAnchor`: Base UI anchors through the
+// Positioner's `anchor` prop.
+
 function Popover({ ...props }: PopoverPrimitive.Root.Props) {
   return <PopoverPrimitive.Root data-slot="popover" {...props} />
 }

package/src/components/progress.tsx

@@ -0,0 +1,77 @@
+import { Progress as ProgressPrimitive } from "@base-ui/react/progress"
+
+import { cn } from "../lib/utils"
+
+type ProgressProps = {
+  /** `null` is indeterminate: a slow moving segment, still under `prefers-reduced-motion`. */
+  value: number | null
+  max?: number
+  /** The accessible name; shown above the bar when `showLabel`. */
+  label?: string
+  showLabel?: boolean
+  /** Right-aligned text the caller builds ("12.4 / 44.7 MB", "63%"). The kit does not format it. */
+  detail?: string
+  className?: string
+}
+
+// A 6 px rounded bar that fills its container: `--primary` on `--muted`. No per-state colour:
+// a failure is the caller's message, not a red bar.
+function Progress({
+  value,
+  max = 100,
+  label,
+  showLabel = false,
+  detail,
+  className,
+}: ProgressProps) {
+  const labelShown = showLabel && label !== undefined
+  return (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      value={value}
+      max={max}
+      aria-label={labelShown ? undefined : label}
+      className={cn("flex w-full flex-col gap-1.5", className)}
+    >
+      {(labelShown || detail !== undefined) && (
+        <div className="flex items-baseline justify-between gap-3 text-xs">
+          {labelShown ? (
+            <ProgressPrimitive.Label data-slot="progress-label" className="font-medium">
+              {label}
+            </ProgressPrimitive.Label>
+          ) : (
+            <span />
+          )}
+          {detail !== undefined && (
+            <span data-slot="progress-detail" className="text-muted-foreground tabular-nums">
+              {detail}
+            </span>
+          )}
+        </div>
+      )}
+      <ProgressPrimitive.Track
+        data-slot="progress-track"
+        className="relative h-1.5 w-full overflow-hidden rounded-full bg-muted"
+      >
+        <ProgressPrimitive.Indicator
+          data-slot="progress-indicator"
+          className="h-full rounded-full bg-primary transition-[width] data-indeterminate:w-2/5 data-indeterminate:animate-[progress-slide_2s_ease-in-out_infinite] data-indeterminate:transition-none motion-reduce:data-indeterminate:animate-none"
+        />
+      </ProgressPrimitive.Track>
+    </ProgressPrimitive.Root>
+  )
+}
+
+// Decimal sizes, one place: bytes under a kilobyte, then kilobytes, megabytes and gigabytes.
+// 46_900_000 is "46.9 MB", 1_200_000_000 is "1.2 GB", 2_048 is "2.0 KB", 0 is "0 B".
+function formatBytes(n: number): string {
+  if (!Number.isFinite(n) || n <= 0) return "0 B"
+  if (n < 1_000) return `${Math.round(n)} B`
+  // Each threshold sits where one place rounds up to 1000.0 of the smaller unit.
+  if (n < 999_950) return `${(n / 1_000).toFixed(1)} KB`
+  if (n < 999_950_000) return `${(n / 1_000_000).toFixed(1)} MB`
+  return `${(n / 1_000_000_000).toFixed(1)} GB`
+}
+
+export type { ProgressProps }
+export { formatBytes, Progress }

package/src/components/sidebar.tsx

@@ -14,6 +14,10 @@ import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "
 import { Skeleton } from "./skeleton"
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip"
 
+// Sidebar: shadcn's sidebar with `asChild` replaced by `render`, and `useIsMobile` kept in
+// the kit. Only the `collapsible="none"` form is exercised in the playground; the offcanvas
+// and icon forms are untested here.
+
 // Base UI's replacement for Radix's asChild: pass `render={<a href="..." />}`
 // to swap the element, props and ref are merged onto it.
 function Slotted({

package/src/components/snackbar.tsx

@@ -4,8 +4,9 @@ import type * as React from "react"
 
 import { cn } from "../lib/utils"
 
-// The kit's one toast: Strata's snackbar, on Base UI Toast.
-// One manager for the module, so `notify()` works outside React. Mount one provider per window.
+// The kit's one toast: Strata's snackbar, on Base UI Toast. Kinds: plain, success, warning, error.
+// One manager for the module, so `notify()` works outside React. Mount one `SnackbarProvider` per
+// window, with a `SnackbarViewport` inside it.
 const manager = Toast.createToastManager()
 
 export function SnackbarProvider({ children }: { children: React.ReactNode }) {

package/src/components/tabs.tsx

@@ -44,6 +44,8 @@ function TabsList({
   )
 }
 
+// Orientation styles key on `data-[orientation=...]`.
+
 // Base UI calls the trigger `Tab` and the content `Panel`; the kit keeps the
 // shadcn names (TabsTrigger, TabsContent) so apps read the same.
 function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props) {

package/src/components/toggle.tsx

@@ -3,6 +3,8 @@ import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "../lib/utils"
 
+// Toggle: the pressed state is `data-pressed`, not Radix's `data-[state=on]`. Style with that.
+
 const toggleVariants = cva(
   "group/toggle inline-flex items-center justify-center gap-1 rounded-md text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 data-pressed:bg-muted dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
   {

package/src/index.css

@@ -15,6 +15,14 @@
 
 @custom-variant dark (&:is(.dark *));
 
+/* Progress, indeterminate: the 40%-wide segment crosses the track left to right. */
+@theme inline {
+    @keyframes progress-slide {
+        from { transform: translateX(-100%); }
+        to { transform: translateX(250%); }
+    }
+}
+
 @theme inline {
     /* Headings use the interface face; hierarchy comes from size and weight. */
     --font-heading: 'Geist Variable', ui-sans-serif, system-ui, sans-serif;

package/src/index.ts

@@ -6,15 +6,19 @@ export * from "./components/card"
 export * from "./components/checkbox"
 export * from "./components/color-field"
 export * from "./components/color-swatch"
+export * from "./components/confirm-dialog"
 export * from "./components/context-menu"
 export * from "./components/dialog"
+export * from "./components/download-prompt"
 export * from "./components/dropdown-menu"
 export * from "./components/empty-state"
 export * from "./components/input"
 export * from "./components/label"
+export * from "./components/list"
 export * from "./components/navigation-menu"
 export * from "./components/number-field"
 export * from "./components/popover"
+export * from "./components/progress"
 export * from "./components/select"
 export * from "./components/separator"
 export * from "./components/sheet"