@spaethtech/svelte-ui 0.14.0 → 0.15.0

package/dist/components/Stat/index.js

@@ -0,0 +1 @@
+export { default as Stat } from "./Stat.svelte";

package/dist/components/Timeline/Timeline.svelte

@@ -0,0 +1,98 @@
+<!--
+/**
+ * Timeline — a vertical sequence of events: a marker (dot or icon) on a connecting line, with a
+ * title / time / description per item. Per-item `variant` colours its marker. `--ui-*` tokens.
+ * See Timeline.spec.md.
+ */
+-->
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+  import type { Variant } from "../../types/variants.js";
+  export type TimelineItem = {
+    title: string;
+    time?: string;
+    description?: string;
+    icon?: Snippet;
+    variant?: Variant;
+    content?: Snippet;
+  };
+</script>
+
+<script lang="ts">
+  import { variantToken } from "../../types/variants.js";
+  import type { Size } from "../../types/sizes.js";
+  import { responsiveClasses, type Responsive } from "../../types/responsive.js";
+
+  let {
+    items,
+    variant = "primary",
+    size = "md",
+    class: cls = "",
+  }: {
+    items: TimelineItem[];
+    variant?: Variant;
+    size?: Responsive<Size>;
+    class?: string;
+  } = $props();
+
+  const dotSize: Record<Size, string> = { sm: "w-2.5 h-2.5", md: "w-3 h-3", lg: "w-3.5 h-3.5" };
+  const iconBox: Record<Size, string> = {
+    sm: "w-6 h-6 [&_svg]:w-3.5 [&_svg]:h-3.5",
+    md: "w-8 h-8 [&_svg]:w-4 [&_svg]:h-4",
+    lg: "w-9 h-9 [&_svg]:w-5 [&_svg]:h-5",
+  };
+  const titleSize: Record<Size, string> = { sm: "text-sm", md: "text-base", lg: "text-lg" };
+  const tokenFor = (item: TimelineItem) => variantToken[item.variant ?? variant];
+</script>
+
+<ol class="flex flex-col {cls}">
+  {#each items as item, i (i)}
+    {@const last = i === items.length - 1}
+    <li class="flex gap-3">
+      <!-- Marker + connecting line. -->
+      <div class="flex flex-col items-center">
+        {#if item.icon}
+          <span
+            class="inline-flex shrink-0 items-center justify-center rounded-full {responsiveClasses(
+              size,
+              iconBox,
+            )}"
+            style="background-color: color-mix(in srgb, var({tokenFor(item)}) 16%, transparent); color: color-mix(in srgb, var({tokenFor(item)}) var(--ui-tint-strong), var(--ui-color-text));"
+            aria-hidden="true"
+          >
+            {@render item.icon()}
+          </span>
+        {:else}
+          <span
+            class="mt-1.5 shrink-0 rounded-full {responsiveClasses(size, dotSize)}"
+            style="background-color: var({tokenFor(item)});"
+            aria-hidden="true"
+          ></span>
+        {/if}
+        {#if !last}
+          <span class="my-1 w-px flex-1 [background-color:var(--ui-border-color)]" aria-hidden="true"></span>
+        {/if}
+      </div>
+
+      <!-- Content. -->
+      <div class="min-w-0 flex-1 pb-6">
+        <div class="flex flex-wrap items-baseline gap-x-2">
+          <span class="font-medium [color:var(--ui-color-text)] {responsiveClasses(size, titleSize)}">
+            {item.title}
+          </span>
+          {#if item.time}
+            <span class="text-xs [color:color-mix(in_srgb,var(--ui-color-text)_50%,transparent)]">
+              {item.time}
+            </span>
+          {/if}
+        </div>
+        {#if item.description}
+          <p class="mt-0.5 text-sm [color:color-mix(in_srgb,var(--ui-color-text)_65%,transparent)]">
+            {item.description}
+          </p>
+        {/if}
+        {#if item.content}<div class="mt-2">{@render item.content()}</div>{/if}
+      </div>
+    </li>
+  {/each}
+</ol>

package/dist/components/Timeline/Timeline.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from "svelte";
+import type { Variant } from "../../types/variants.js";
+export type TimelineItem = {
+    title: string;
+    time?: string;
+    description?: string;
+    icon?: Snippet;
+    variant?: Variant;
+    content?: Snippet;
+};
+import type { Size } from "../../types/sizes.js";
+import { type Responsive } from "../../types/responsive.js";
+type $$ComponentProps = {
+    items: TimelineItem[];
+    variant?: Variant;
+    size?: Responsive<Size>;
+    class?: string;
+};
+declare const Timeline: import("svelte").Component<$$ComponentProps, {}, "">;
+type Timeline = ReturnType<typeof Timeline>;
+export default Timeline;

package/dist/components/Timeline/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Timeline } from "./Timeline.svelte";
+export type { TimelineItem } from "./Timeline.svelte";

package/dist/components/Timeline/index.js

@@ -0,0 +1 @@
+export { default as Timeline } from "./Timeline.svelte";

package/dist/components/TokenInput/TokenInput.svelte

@@ -62,14 +62,19 @@
       : `color-mix(in srgb, var(${token}) var(--ui-tint-border-hover), transparent)`,
   );
 
+  // Vertical padding is kept small enough that a single token row (chip + 1px border box + padding)
+  // never exceeds the tier's `min-h`, so the field height is CONSTANT whether empty or holding tokens.
+  // Multi-row wrapping still grows the field; row spacing comes from the flex `gap`, not padding.
   const fieldSize: Record<Size, string> = {
-    sm: "min-h-6 px-1.5 py-0.5 gap-1 text-xs",
-    md: "min-h-8 px-2 py-1 gap-1.5 text-sm",
-    lg: "min-h-10 px-2.5 py-1.5 gap-2 text-base",
+    sm: "min-h-6 px-1.5 py-0 gap-1 text-xs",
+    md: "min-h-8 px-2 py-[2px] gap-1.5 text-sm",
+    lg: "min-h-10 px-2.5 py-[2px] gap-2 text-base",
   };
-  const chipSize = $derived<Size>(
-    (typeof size === "string" ? size : "md") === "lg" ? "md" : "sm",
-  );
+  const baseSize = $derived<Size>(typeof size === "string" ? size : "md");
+  const chipSize = $derived<Size>(baseSize === "lg" ? "md" : "sm");
+  // A default `sm` chip is 24px — exactly the sm FIELD height, so it can't fit inside the border box.
+  // Only in the sm field, cap the chip to 20px (still fits the min-h with room to center).
+  const chipHeightClass = $derived(baseSize === "sm" ? "!h-5" : "");
 
   let draft = $state("");
 
@@ -115,6 +120,7 @@
           text={v}
           variant={variant === "ghost" ? "secondary" : variant}
           size={chipSize}
+          class={chipHeightClass}
           removable
           {disabled}
           onremove={() => removeAt(i)}

package/dist/components/Tree/Tree.svelte

@@ -0,0 +1,178 @@
+<!--
+/**
+ * Tree — a hierarchical, expandable tree view (ARIA `tree`). Data-driven nodes; expand/collapse +
+ * single-select with roving-tabindex keyboard nav (↑/↓ move, →/← expand/collapse, Enter/Space select).
+ * Shared `variant`/`size` axes, `--ui-*` tokens. See Tree.spec.md.
+ */
+-->
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+  export type TreeNode = {
+    label: string;
+    /** Stable key; falls back to the index path when omitted. */
+    id?: string;
+    icon?: Snippet;
+    children?: TreeNode[];
+    disabled?: boolean;
+  };
+</script>
+
+<script lang="ts">
+  import IconChevronRight from "~icons/mdi/chevron-right";
+  import type { Variant } from "../../types/variants.js";
+  import { variantToken } from "../../types/variants.js";
+  import type { Size } from "../../types/sizes.js";
+  import { responsiveClasses, type Responsive } from "../../types/responsive.js";
+
+  let {
+    items,
+    expanded = $bindable([]),
+    selected = $bindable(""),
+    onselect,
+    variant = "primary",
+    size = "md",
+    class: cls = "",
+  }: {
+    items: TreeNode[];
+    /** Keys of expanded nodes (bindable). */
+    expanded?: string[];
+    /** Key of the selected node (bindable). */
+    selected?: string;
+    onselect?: (node: TreeNode, key: string) => void;
+    variant?: Variant;
+    size?: Responsive<Size>;
+    class?: string;
+  } = $props();
+
+  const token = $derived(variantToken[variant]);
+  const rowH: Record<Size, string> = { sm: "h-7 text-xs", md: "h-8 text-sm", lg: "h-10 text-base" };
+  const iconCls: Record<Size, string> = {
+    sm: "[&_svg]:w-3.5 [&_svg]:h-3.5",
+    md: "[&_svg]:w-4 [&_svg]:h-4",
+    lg: "[&_svg]:w-5 [&_svg]:h-5",
+  };
+
+  type Flat = { key: string; node: TreeNode; level: number; hasChildren: boolean; open: boolean };
+  // Flattened list of VISIBLE nodes (children shown only under expanded parents) — drives rendering,
+  // roving tabindex, and arrow-key navigation.
+  const flat = $derived.by<Flat[]>(() => {
+    const out: Flat[] = [];
+    const walk = (nodes: TreeNode[], level: number, prefix: string) => {
+      nodes.forEach((node, i) => {
+        const key = node.id ?? `${prefix}${i}`;
+        const hasChildren = !!node.children?.length;
+        const open = expanded.includes(key);
+        out.push({ key, node, level, hasChildren, open });
+        if (hasChildren && open) walk(node.children!, level + 1, `${key}>`);
+      });
+    };
+    walk(items, 0, "");
+    return out;
+  });
+
+  let rowRefs = $state<Record<string, HTMLElement | undefined>>({});
+  let activeKey = $state("");
+  const tabKey = $derived(
+    flat.some((f) => f.key === activeKey) ? activeKey : (flat.find((f) => !f.node.disabled)?.key ?? ""),
+  );
+
+  const toggle = (key: string) =>
+    (expanded = expanded.includes(key) ? expanded.filter((k) => k !== key) : [...expanded, key]);
+  function selectNode(f: Flat) {
+    if (f.node.disabled) return;
+    selected = f.key;
+    onselect?.(f.node, f.key);
+    if (f.hasChildren) toggle(f.key);
+  }
+  const focusKey = (key: string) => {
+    activeKey = key;
+    rowRefs[key]?.focus();
+  };
+
+  function onKeydown(e: KeyboardEvent) {
+    const idx = flat.findIndex((f) => f.key === tabKey);
+    if (idx < 0) return;
+    const f = flat[idx];
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        if (idx < flat.length - 1) focusKey(flat[idx + 1].key);
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        if (idx > 0) focusKey(flat[idx - 1].key);
+        break;
+      case "ArrowRight":
+        e.preventDefault();
+        if (f.hasChildren && !f.open) toggle(f.key);
+        else if (f.hasChildren && flat[idx + 1]) focusKey(flat[idx + 1].key);
+        break;
+      case "ArrowLeft":
+        e.preventDefault();
+        if (f.hasChildren && f.open) toggle(f.key);
+        else {
+          // move to parent (previous node at a lower level)
+          for (let j = idx - 1; j >= 0; j--)
+            if (flat[j].level < f.level) {
+              focusKey(flat[j].key);
+              break;
+            }
+        }
+        break;
+      case "Home":
+        e.preventDefault();
+        focusKey(flat[0].key);
+        break;
+      case "End":
+        e.preventDefault();
+        focusKey(flat[flat.length - 1].key);
+        break;
+      case "Enter":
+      case " ":
+        e.preventDefault();
+        selectNode(f);
+        break;
+    }
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<ul role="tree" class="flex flex-col {responsiveClasses(size, iconCls)} {cls}" onkeydown={onKeydown}>
+  {#each flat as f (f.key)}
+    {@const active = selected === f.key}
+    <li role="none" class="list-none">
+      <!-- svelte-ignore a11y_click_events_have_key_events -->
+      <div
+        bind:this={rowRefs[f.key]}
+        role="treeitem"
+        aria-level={f.level + 1}
+        aria-selected={active}
+        aria-expanded={f.hasChildren ? f.open : undefined}
+        aria-disabled={f.node.disabled || undefined}
+        tabindex={f.key === tabKey ? 0 : -1}
+        onclick={() => selectNode(f)}
+        onfocus={() => (activeKey = f.key)}
+        style="padding-inline-start: {f.level * 1.25 + 0.5}rem; {active
+          ? `background-color: color-mix(in srgb, var(${token}) 16%, transparent);`
+          : ''}"
+        class="group flex items-center gap-1.5 rounded-[var(--ui-border-radius)] pr-2 transition-colors {responsiveClasses(
+          size,
+          rowH,
+        )} {f.node.disabled
+          ? 'opacity-50 cursor-not-allowed'
+          : 'cursor-pointer hover:[background-color:var(--ui-color-hover)]'} focus-visible:[outline:2px_solid_color-mix(in_srgb,var(--ui-color-text)_70%,transparent)] focus-visible:[outline-offset:-2px]"
+      >
+        {#if f.hasChildren}
+          <span
+            class="inline-flex shrink-0 items-center justify-center transition-transform duration-150 {f.open
+              ? 'rotate-90'
+              : ''}"><IconChevronRight /></span>
+        {:else}
+          <span class="inline-block w-4 shrink-0"></span>
+        {/if}
+        {#if f.node.icon}<span class="inline-flex shrink-0">{@render f.node.icon()}</span>{/if}
+        <span class="truncate [color:var(--ui-color-text)]">{f.node.label}</span>
+      </div>
+    </li>
+  {/each}
+</ul>

package/dist/components/Tree/Tree.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Snippet } from "svelte";
+export type TreeNode = {
+    label: string;
+    /** Stable key; falls back to the index path when omitted. */
+    id?: string;
+    icon?: Snippet;
+    children?: TreeNode[];
+    disabled?: boolean;
+};
+import type { Variant } from "../../types/variants.js";
+import type { Size } from "../../types/sizes.js";
+import { type Responsive } from "../../types/responsive.js";
+type $$ComponentProps = {
+    items: TreeNode[];
+    /** Keys of expanded nodes (bindable). */
+    expanded?: string[];
+    /** Key of the selected node (bindable). */
+    selected?: string;
+    onselect?: (node: TreeNode, key: string) => void;
+    variant?: Variant;
+    size?: Responsive<Size>;
+    class?: string;
+};
+declare const Tree: import("svelte").Component<$$ComponentProps, {}, "selected" | "expanded">;
+type Tree = ReturnType<typeof Tree>;
+export default Tree;

package/dist/components/Tree/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Tree } from "./Tree.svelte";
+export type { TreeNode } from "./Tree.svelte";

package/dist/components/Tree/index.js

@@ -0,0 +1 @@
+export { default as Tree } from "./Tree.svelte";

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { default as Alert } from "./components/Alert.svelte";
 export { default as Banner } from "./components/Banner.svelte";
 export { default as Badge } from "./components/Badge/Badge.svelte";
 export { Chip } from "./components/Chip/index.js";
+export { Kbd } from "./components/Kbd/index.js";
+export { EmptyState } from "./components/EmptyState/index.js";
 export { Avatar, AvatarGroup } from "./components/Avatar/index.js";
 export type { AvatarShape, AvatarStatus, AvatarItem } from "./components/Avatar/index.js";
 export { default as Button } from "./components/Button.svelte";
@@ -10,6 +12,9 @@ export { default as Card } from "./components/Card.svelte";
 export { default as CardHeader } from "./components/CardHeader.svelte";
 export { default as CardBody } from "./components/CardBody.svelte";
 export { default as CardFooter } from "./components/CardFooter.svelte";
+export { Stat } from "./components/Stat/index.js";
+export { Timeline } from "./components/Timeline/index.js";
+export type { TimelineItem } from "./components/Timeline/index.js";
 export { default as Toaster } from "./components/Toast/Toaster.svelte";
 export { toast, getToasts, dismissToast, type ToastVariant, type ToastItem, } from "./components/Toast/toast.svelte.js";
 export { default as Dialog } from "./components/Dialog.svelte";
@@ -38,13 +43,16 @@ export { default as DatePicker } from "./components/DatePicker.svelte";
 export { default as TimeSpinner } from "./components/TimeSpinner.svelte";
 export { default as TimePicker } from "./components/TimePicker.svelte";
 export { default as TimeRangeInput } from "./components/TimeRangeInput.svelte";
-export { DateRangePicker } from "./components/DateRangePicker/index.js";
 export { FileUpload } from "./components/FileUpload/index.js";
-export type { RangePreset } from "./components/DateRangePicker/index.js";
 export { default as ThemeSelector } from "./components/ThemeSelector.svelte";
 export { default as ThemeToggle } from "./components/ThemeToggle.svelte";
 export { default as Popup } from "./components/Popup.svelte";
 export { default as Menu } from "./components/Menu.svelte";
+export { ContextMenu } from "./components/ContextMenu/index.js";
+export { CommandPalette } from "./components/CommandPalette/index.js";
+export type { Command } from "./components/CommandPalette/index.js";
+export { Tree } from "./components/Tree/index.js";
+export type { TreeNode } from "./components/Tree/index.js";
 export type { MenuItem } from "./data/table/types.js";
 export { ButtonGroup } from "./components/ButtonGroup/index.js";
 export type { ButtonGroupItem, ButtonGroupSelect } from "./components/ButtonGroup/index.js";
@@ -54,6 +62,9 @@ export { default as Radio } from "./components/Radio.svelte";
 export { default as FieldGroup } from "./components/FieldGroup.svelte";
 export { default as Grid } from "./components/Grid.svelte";
 export { Divider } from "./components/Divider/index.js";
+export { ScrollArea } from "./components/ScrollArea/index.js";
+export { Splitter } from "./components/Splitter/index.js";
+export { Carousel } from "./components/Carousel/index.js";
 export type { Columns, Gap } from "./components/field-group.js";
 export { Stepper } from "./components/Stepper/index.js";
 export type { StepItem } from "./components/Stepper/index.js";

package/dist/index.js

@@ -3,6 +3,8 @@ export { default as Alert } from "./components/Alert.svelte";
 export { default as Banner } from "./components/Banner.svelte";
 export { default as Badge } from "./components/Badge/Badge.svelte";
 export { Chip } from "./components/Chip/index.js";
+export { Kbd } from "./components/Kbd/index.js";
+export { EmptyState } from "./components/EmptyState/index.js";
 export { Avatar, AvatarGroup } from "./components/Avatar/index.js";
 export { default as Button } from "./components/Button.svelte";
 export { default as ButtonDropdown } from "./components/ButtonDropdown.svelte";
@@ -10,6 +12,8 @@ export { default as Card } from "./components/Card.svelte";
 export { default as CardHeader } from "./components/CardHeader.svelte";
 export { default as CardBody } from "./components/CardBody.svelte";
 export { default as CardFooter } from "./components/CardFooter.svelte";
+export { Stat } from "./components/Stat/index.js";
+export { Timeline } from "./components/Timeline/index.js";
 // Toast notifications — `toast.*` pushes from anywhere; mount <Toaster /> once at the app root.
 export { default as Toaster } from "./components/Toast/Toaster.svelte";
 export { toast, getToasts, dismissToast, } from "./components/Toast/toast.svelte.js";
@@ -40,7 +44,6 @@ export { default as DatePicker } from "./components/DatePicker.svelte";
 export { default as TimeSpinner } from "./components/TimeSpinner.svelte";
 export { default as TimePicker } from "./components/TimePicker.svelte";
 export { default as TimeRangeInput } from "./components/TimeRangeInput.svelte";
-export { DateRangePicker } from "./components/DateRangePicker/index.js";
 export { FileUpload } from "./components/FileUpload/index.js";
 // Theme Components
 export { default as ThemeSelector } from "./components/ThemeSelector.svelte";
@@ -48,6 +51,9 @@ export { default as ThemeToggle } from "./components/ThemeToggle.svelte";
 // Utility Components
 export { default as Popup } from "./components/Popup.svelte";
 export { default as Menu } from "./components/Menu.svelte";
+export { ContextMenu } from "./components/ContextMenu/index.js";
+export { CommandPalette } from "./components/CommandPalette/index.js";
+export { Tree } from "./components/Tree/index.js";
 export { ButtonGroup } from "./components/ButtonGroup/index.js";
 export { default as Checkbox } from "./components/Checkbox.svelte";
 export { default as Toggle } from "./components/Toggle.svelte";
@@ -55,6 +61,9 @@ export { default as Radio } from "./components/Radio.svelte";
 export { default as FieldGroup } from "./components/FieldGroup.svelte";
 export { default as Grid } from "./components/Grid.svelte";
 export { Divider } from "./components/Divider/index.js";
+export { ScrollArea } from "./components/ScrollArea/index.js";
+export { Splitter } from "./components/Splitter/index.js";
+export { Carousel } from "./components/Carousel/index.js";
 export { Stepper } from "./components/Stepper/index.js";
 export { default as Disclosure } from "./components/Disclosure.svelte";
 export { default as Accordion } from "./components/Accordion.svelte";

package/docs/components.md

@@ -122,20 +122,6 @@ Drag-and-drop + click file field with thumbnails, remove, and optional progress.
   `<input type=file>`; labelled remove ×s
 - **Composition**: `Button` + `Progress`; FieldChrome for label/error
 
-### DateRangePicker
-
-Start–end date range with a presets rail; composes `Calendar mode="range"` + `Input` + `Popup`.
-
-- **Location**: `src/lib/components/DateRangePicker/DateRangePicker.svelte`
-- **Axes**: `variant`, `size`
-- **Props**: `start`/`end` (bindable ISO), `min`/`max`, `presets` (`RangePreset[]`; default set, `[]`
-  hides the rail), `format`, `placeholder`, plus FieldChrome (`label`/`aside`/`error`/`description`/
-  `id`/`required`), `class`
-- **Behavior**: readonly `Input` trigger shows the formatted range; the popup pairs a presets column
-  (`Button` ghost) with the range calendar; a preset or the second calendar pick closes it
-- **Note**: `DatePicker range` covers a bare range (object value, no presets); this is the
-  presets-first, `bind:start`/`bind:end` variant
-
 ### Slider
 
 Draggable range input — a single value or a `[min, max]` pair.
@@ -285,10 +271,15 @@ independent. Propagates `size`/`variant`/`disabled` to children.
 
 ### Rating
 
-Read-only star-rating display (5-star, from a 10-point average).
+Star rating in two modes: a read-only display, or an interactive picker.
 
 - **Location**: `src/lib/components/Rating.svelte`
-- **Props**: `average` (number), `count` (number)
+- **Display mode** (default): `average` (0–10 score, shown as 5 stars = average/2), `count` (votes).
+- **Interactive mode**: `interactive` + `value` (bindable, 0..`max`). Click a star, hover to preview,
+  or focus and use ←/→ · ↑/↓ · Home/End. `allowHalf` enables half-star selection; `onchange`,
+  `readonly`, `disabled`. Rendered as a `role="slider"` (same a11y pattern as `Slider`).
+- **Shared**: `variant` (filled-star tint; default gold), `size`, `showValue` (numeric readout —
+  defaults on in display mode, off interactive), `label` (slider a11y label).
 
 ## Specialized Input Components
 
@@ -399,13 +390,19 @@ dialog (operators, casts, dynamic `now()` dates, and a worked examples table). T
 Standalone page navigator — the reusable extraction of `DataTable`'s footer pager.
 
 - **Location**: `src/lib/components/Pagination/Pagination.svelte`
-- **Axes**: `variant` (active page fill), `size`
+- **Axes**: `variant` (tints the band **surface + button hover**, like DataTable's footer — NOT a
+  filled button; omit for a neutral band, `ghost` for a transparent one), `size` (scales band, Select,
+  buttons, and the page field)
 - **Props**: `page` (bindable), `total`, `perPage` (bindable), `perPageOptions` (→ rows-per-page
-  `Select`), `siblingCount`/`boundaryCount`, `showEdges` (first/last), `showTotal`, `disabled`, `class`
-- **Behavior**: numbered buttons with ellipsis for long ranges (active = filled, rest `ghost`);
-  prev/next/first/last disable at the ends; choosing `perPage` resets to page 1; `page` clamps to range
-- **Accessibility**: `<nav aria-label="Pagination">`; active page `aria-current="page"`
-- **Composition**: `Button` + `Select` only (no raw `<button>`)
+  `Select` on the left), `showEdges` (first/last, default **true**), `showTotal` (range text, default
+  **true**), `borderless` (drop the band border/surface), `disabled`, `class`
+- **Layout**: a tinted, bordered band (matches `DataTable`'s footer) — per-page `Select` left; range
+  text + a compact `First · Prev · [page]/N · Next · Last` stepper right. The page indicator is an
+  **editable `NumberInput`** (min 1, max N, clamped) — type a page + Enter to jump; ↑/↓ step it.
+- **Behavior**: prev/next/first/last disable at the ends; choosing `perPage` resets to page 1; `page`
+  clamps to range; jump commits on change (Enter/blur)
+- **Accessibility**: `<nav aria-label="Pagination">`; the jump field is `aria-label="Page number"`
+- **Composition**: `Button` + `Select` + `NumberInput` only (no raw `<button>`/`<input>`)
 
 ## Overlays
 
@@ -617,3 +614,109 @@ src/lib/components/ComponentName/
 ```
 src/lib/components/ComponentName.svelte
 ```
+
+### Kbd
+
+Keyboard-key display (`<kbd>` keycap).
+
+- **Location**: `src/lib/components/Kbd/Kbd.svelte`
+- **Axes**: `size`
+- **Props**: `keys` (`string[]` combo, joined with `+`), `text`/`children` (single key), `class`
+- **Theming**: `--ui-color-surface` fill + `--ui-border-color` border with a shallow inset bottom shadow
+
+### EmptyState
+
+Zero-data / empty placeholder — icon + title + description + optional action.
+
+- **Location**: `src/lib/components/EmptyState/EmptyState.svelte`
+- **Axes**: `variant` (icon-badge accent), `size`
+- **Props**: `title`, `description`, `icon` (snippet; default inbox), `action` (CTA snippet),
+  `children`, `class`
+
+### Stat
+
+Metric/KPI card — label, value, delta, icon. Built on `Card`.
+
+- **Location**: `src/lib/components/Stat/Stat.svelte`
+- **Axes**: `variant` (icon-badge accent), `size` (value scale)
+- **Props**: `label`, `value`, `delta` (number → arrow; string → as-is), `deltaLabel`, `invertDelta`
+  (negative is good), `icon` (snippet), `class`
+- **Theming**: rising delta success / falling danger / flat muted; icon badge tints from the variant
+
+### Timeline
+
+Vertical event sequence — marker + connecting line + title/time/description.
+
+- **Location**: `src/lib/components/Timeline/Timeline.svelte`
+- **Axes**: `variant` (default marker accent; per-item override), `size`
+- **Props**: `items` (`TimelineItem[]` = `{ title, time?, description?, icon?, variant?, content? }`), `class`
+- **Theming**: icon marker = variant token @16% badge; dot = solid token; connector `--ui-border-color`
+
+### ContextMenu
+
+Right-click menu over any content; opens `Menu` at the pointer.
+
+- **Location**: `src/lib/components/ContextMenu/ContextMenu.svelte`
+- **Props**: `items` (`MenuItem[]`), `size`, `variant`, `disabled` (leaves the native menu), `class`,
+  `children` (the right-clickable content)
+- **Composition**: `Menu` anchored to a 0-size point at the pointer; flips/shifts at edges
+
+### Tree
+
+Hierarchical, expandable tree view (ARIA `tree`).
+
+- **Location**: `src/lib/components/Tree/Tree.svelte`
+- **Axes**: `variant` (selected-row tint), `size`
+- **Props**: `items` (`TreeNode[]` = `{ label, id?, icon?, children?, disabled? }`), `expanded`
+  (bindable `string[]`), `selected` (bindable key), `onselect`, `class`
+- **Keyboard**: roving tabindex — ↑/↓ move, → expand/into child, ← collapse/to parent, Enter/Space
+  select, Home/End
+- **Accessibility**: `role="tree"`/`treeitem` with `aria-level`/`-expanded`/`-selected`/`-disabled`
+
+### ScrollArea
+
+Scroll container with a themed thin scrollbar.
+
+- **Location**: `src/lib/components/ScrollArea/ScrollArea.svelte`
+- **Props**: `orientation` (`vertical`/`horizontal`/`both`), `maxHeight`/`height` (CSS length), `variant`
+  (thumb accent; default neutral text-tint), `class`, `children`
+- **Theming**: thumb = accent @28% (hover @45%), transparent track, rounded; Firefox `scrollbar-color`/
+  `-width:thin` + WebKit `::-webkit-scrollbar` both styled
+
+### Splitter
+
+Two resizable panes with a draggable divider.
+
+- **Location**: `src/lib/components/Splitter/Splitter.svelte`
+- **Props**: `start`/`end` (snippets), `orientation` (`horizontal`/`vertical`), `size` (bindable %),
+  `min`/`max`/`step`, `variant` (handle accent), `disabled`, `class`
+- **Interaction**: drag the handle or focus it and use ←/→ (or ↑/↓) + Home/End
+- **Accessibility**: WAI-ARIA window-splitter — `role="separator"`, `aria-orientation`,
+  `aria-valuenow`/`min`/`max`, focusable
+
+### Carousel
+
+Sliding, one-at-a-time viewport with controls + dot indicators.
+
+- **Location**: `src/lib/components/Carousel/Carousel.svelte`
+- **Props**: `items` (`T[]`) + `slide` (`Snippet<[item, index]>`), `index` (bindable), `loop`,
+  `autoplay` (ms; pauses on hover/focus), `controls`, `indicators`, `variant`, `ariaLabel`, `class`
+- **Interaction**: prev/next `Button`s, clickable dots, ←/→ keys; `loop` wraps or clamps at ends
+- **Accessibility**: `role="region"` carousel + per-slide `role="group"` (`aria-label="N of M"`, hidden
+  when off); dots are `<button>`s with `aria-current`
+
+### CommandPalette
+
+⌘K/Ctrl+K fuzzy command launcher — a top-centered modal overlay with a search field + filtered,
+grouped, keyboard-navigable command list.
+
+- **Location**: `src/lib/components/CommandPalette/CommandPalette.svelte`
+- **Props**: `open` (bindable), `commands` (`Command[]` = `{ label, keywords?, group?, icon?,
+  shortcut?, disabled?, onrun }`), `hotkey` (default `"mod+k"`; `mod` = ⌘ on macOS / Ctrl elsewhere;
+  `""` disables), `placeholder`, `empty` (no-match text), `onopen`
+- **Interaction**: hotkey toggles open; typing filters (label + keywords); ↑/↓ move (wrapping), Enter
+  runs the highlighted command, Esc / backdrop close; shortcuts render as `Kbd`
+- **Behavior**: portals to `<body>`; on open resets query/highlight, locks scroll, focuses input; on
+  close restores focus. Disabled commands are inert.
+- **Composition**: `Input` (search) + `Kbd` (shortcuts); `role="dialog"`/`combobox`/`listbox` wiring
+- **Exports**: `CommandPalette` + the `Command` type