@vegastack/design 0.3.2 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/design",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "VegaStack design system — cn utility, icon runtime, Tailwind v4 preset, and the vegastack-design CLI (tokens ship separately as @vegastack/design-tokens)",
   "license": "MIT",
   "repository": {
@@ -38,6 +38,12 @@
       "require": "./dist/icons/index.cjs",
       "default": "./dist/icons/index.js"
     },
+    "./create-animated-icon": {
+      "types": "./dist/create-animated-icon.d.ts",
+      "import": "./dist/create-animated-icon.js",
+      "require": "./dist/create-animated-icon.cjs",
+      "default": "./dist/create-animated-icon.js"
+    },
     "./theme-scope": {
       "types": "./dist/theme-scope.d.ts",
       "import": "./dist/theme-scope.js",
@@ -58,7 +64,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "lint": "eslint . && pnpm run verify",
+    "lint": "eslint . && node ../../tooling/design-lint.mjs src && pnpm run verify",
     "verify": "node ../../tooling/verify-preset-source.mjs",
     "typecheck": "tsc --noEmit",
     "test": "node test/compare.test.mjs && node test/check-updates.test.mjs && node test/skills-install.test.mjs"
@@ -74,6 +80,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "lucide-react": "^1.24.0",
+    "motion": "^13.2.0",
     "thesvg": "^3.2.6",
     "tailwindcss": "catalog:"
   },
@@ -84,23 +91,27 @@
     "lucide-react": {
       "optional": true
     },
+    "motion": {
+      "optional": true
+    },
     "thesvg": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@tailwindcss/node": "4.3.1",
-    "@tailwindcss/oxide": "4.3.1",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
+    "@tailwindcss/node": "4.3.3",
+    "@tailwindcss/oxide": "4.3.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
     "@vegastack/eslint-config": "workspace:*",
     "@vegastack/typescript-config": "workspace:*",
-    "eslint": "^10.7.0",
-    "lucide-react": "^1.24.0",
+    "eslint": "^10.10.0",
+    "lucide-react": "^1.42.0",
+    "motion": "^13.2.0",
     "react": "catalog:",
     "react-dom": "catalog:",
     "tailwindcss": "catalog:",
-    "thesvg": "^3.2.6",
+    "thesvg": "^3.3.2",
     "tw-animate-css": "^1.4.0",
     "typescript": "catalog:"
   },

package/preset.css

@@ -13,7 +13,7 @@
  *
  * This package's own `dist` ships the icon runtime (`BrandIcon`'s
  * `inline-flex shrink-0 [&>svg]:size-full`), and `@vegastack/ui` ships a compiled
- * provider + `Toaster` whose sonner `classNames` (e.g. `group-[.toaster]:bg-popover`)
+ * provider + `Toaster` whose Base UI Toast classes (e.g. `bg-popover shadow-overlay`)
  * live in its published `dist/*.js`, NOT in the consumer's own source — so without
  * an explicit `@source` a real npm consumer importing ONLY this preset would get
  * a partially-unstyled provider/Toaster + icon UI.

package/skills/vegastack-consume/SKILL.md

@@ -48,9 +48,9 @@ Or one import that bundles all of it plus tw-animate:
 ```
 
 **No manual `@source` is required.** The preset already declares `@source` for the classes that live
-inside the published builds — the icon runtime, and the provider/Toaster classNames (sonner emits
-`group-[.toaster]:bg-popover`-style classes that Tailwind must be told to generate). Your own
-application and component source is scanned by Tailwind as usual.
+inside the published builds — the icon runtime, and the compiled Toaster (its surface, stacking
+and status-tint classes live in `@vegastack/ui/dist`, and Tailwind has to be told to generate them).
+Your own application and component source is scanned by Tailwind as usual.
 
 ## 3. Wrap the app root in the provider
 
@@ -58,7 +58,7 @@ application and component source is scanned by Tailwind as usual.
 npx shadcn@latest add @vegastack/provider
 ```
 
-This copies `VegaStackProvider` and `useVegaStackTheme` into your project, composing the `sonner`
+This copies `VegaStackProvider` and `useVegaStackTheme` into your project, composing the `toast`
 Toaster item.
 
 ```tsx
@@ -70,7 +70,7 @@ import { VegaStackProvider } from "@/components/ui/provider";
 </body>;
 ```
 
-It bundles theme (next-themes, class-based dark), the Sonner toaster, and the Base UI tooltip and
+It bundles theme (next-themes, class-based dark), the Base UI toast stack, and the tooltip and
 direction providers.
 
 **The `isolate` is required, not cosmetic.** Overlay components (Dialog, Sheet, Popover, Tooltip,

package/skills/vegastack-design-audit/SKILL.md

@@ -70,7 +70,9 @@ rg -n '\b(rounded-xl|rounded-2xl|rounded-3xl|text-4xl|text-5xl|text-6xl|font-bol
 - `font-bold`/`font-semibold` — the weight ladder is 400/500, owned by the type roles. **error**
 - `transition-all` / `transition-colors` — colour changes are immediate; enumerate the causal
   opacity, transform, or geometry properties. **error**
-- a raw `z-N` — two bands only: `z-(--z-raised)`, `z-(--z-overlay)`. **error**
+- a raw `z-N` — three token bands only: `z-(--z-raised)` (local raises), `z-(--z-overlay)` (portaled
+  surfaces), `z-(--z-toast)` (the toast stack alone). DOM order resolves nesting within a band.
+  **error**
 - a raw `opacity-NN` — use an `--opacity-*` role (`opacity-0`/`opacity-100` are exempt). **warning**
 - raw `tracking-*`, `shadow-*`, `blur-*` — owned by the type and effect roles. **warning**
 - a raw `/NN` colour-alpha step — use an `--alpha-*` role. Alpha and opacity are different roles and

package/skills/vegastack-design-system/SKILL.md

@@ -25,10 +25,31 @@ pnpm dlx shadcn@latest list @vegastack
 
 Rules that decide most component questions:
 
+- **`Button` is two axes** — `variant` is the shape (`solid · soft · outline · ghost · link · cta`),
+  `tone` is the hue (`neutral · destructive · success · warning · info`). A destructive action is
+  `variant="soft" tone="destructive"`; a solid red button does not type-check. Icon-only actions are
+  **`IconButton`** (`shape="square" | "round"`) — `Button` has no icon size, and an icon in a bare
+  `<button>` is off-system. An icon-only LINK stays an `<a>`, styled with
+  `buttonVariants(...) + iconButtonGeometry(size)` — never an `IconButton`, which would put
+  `role="button"` on navigation.
+- **One size vocabulary everywhere** — `xs · sm · md · lg`, with `md` the default. No component has a
+  size called `default`.
 - **Compose `app-shell`** for a sidebar + header + main layout — never hand-roll the landmark trio.
+- **`select`** for a short fixed option set; **`searchable-select`** when the list is long enough to
+  need a search field (it is the preset `country-select` and `region-select` are built from — reach
+  for it before composing `combobox` by hand); **`combobox`** directly only for free text,
+  suggestions or multi-select chips.
 - **`segmented`** for 2–5 exclusive options inline; **`tabs`** when the choice switches page regions.
 - **`alert` variant=strip** for in-content notices and plan/trial rows; **`announcement-banner`** only
   for the full-width inverse strip at the very top of the page.
+- **`chip` is the ONE pill** — `hue` × `size` (`sm` inline · `md` control-scale) × `active`, with
+  `onRemove` giving a real 24×24 remove control. `Tag`, `FilterChip` and `ComboboxChip` are that
+  primitive composed through `render`; never hand-roll a pill with its own height, radius, or a
+  sub-24px `×`. A **`badge`** is the different job: status, never removable, never a selection.
+- **`useAnnouncer` is the one live region** — destructure `announce` and `Announcer` from it and
+  render ONE `Announcer` element per component, mounted for its life. It keeps the region observed from first paint
+  and re-keys it per call, so repeating an identical string still announces. Do not hand-roll a
+  `role="status"` node with a `{text, seq}` counter.
 - **`code-block`** for static syntax-highlighted source; **`terminal`** for command sessions.
 - **`navigation-menu`** is top-level site navigation with panels, not a menu inside a page.
 - **Marketing components** (`marketing-surface`, `section-header`, `figure-frame`, `terminal`,
@@ -42,7 +63,8 @@ Always use the utility, never a raw value.
 
 | Role     | Utilities                                                                                        |
 | -------- | ------------------------------------------------------------------------------------------------ |
-| Surface  | `bg-background` `bg-card` `bg-popover` `bg-muted` `bg-accent` `bg-sidebar-*`                     |
+| Surface  | `bg-background` (page) · `bg-card` (every surface; `popover`/`sidebar` ARE `card`)               |
+| Ladder   | `bg-surface-1` (rest fill / well) · `bg-surface-2` (hover) · `bg-surface-3` (pressed / selected) |
 | Text     | `text-foreground` `text-muted-foreground` `text-{primary,accent,popover}-foreground`             |
 | Status   | `bg-{destructive,success,warning,info}` + `-subtle` / `-hover` / `-text` / `-foreground`         |
 | Border   | `border-border` `border-input` — there are no rings; focus is the native outline                 |
@@ -50,7 +72,72 @@ Always use the utility, never a raw value.
 | Type     | `text-{xs…3xl}` · `text-h1…h4` · `text-label` · `text-mono-label` · `text-display-{sm,md,lg,xl}` |
 | Font     | `font-sans` `font-mono` `font-serif`                                                             |
 | Motion   | `duration-{fast,base,slow}` paired with `ease-{standard,emphasized,exit,spring}`                 |
-| Entrance | `motion-pop-in` `motion-enter-up` `motion-shake`                                                 |
+| Entrance | `motion-pop-in` `motion-enter-up` `motion-shake` `motion-flash`                                  |
+| Docked   | `motion-dock-in` / `motion-dock-out` — a control parked at a viewport edge, 150ms in / 100ms out |
+| Prose    | `proseClassName` from `@vegastack/design` — the whole rendered-rich-text recipe, one class       |
+
+**Hover and pressed come from a recipe, never a literal.** Import the two class strings rather than
+writing `hover:bg-*` by hand — that is how a control gets both steps and stays on the ladder:
+
+```tsx
+import { cn, surfaceInteractive, fillInteractive } from "@vegastack/design";
+
+// A transparent control on a known surface.
+<button className={cn("rounded-md px-2", surfaceInteractive)} />;
+// hover:bg-surface-2 active:bg-surface-3
+
+// A control on an unknown backdrop, or one that hovers in its own hue.
+<button className={cn("bg-destructive-subtle", fillInteractive.destructive)} />;
+// hover:bg-destructive/(--alpha-hover) active:bg-destructive/(--alpha-pressed)
+```
+
+A **solid** fill uses neither — it steps through its own darker `-hover` / `-active` tokens.
+
+**Rendered rich text comes from a recipe too.** Anything the system did not author element by element
+— markdown, a contenteditable, CMS copy — wears one class on its root:
+
+```tsx
+import { cn, proseClassName } from "@vegastack/design";
+
+<div
+  className={cn(proseClassName, className)}
+  dangerouslySetInnerHTML={html}
+/>;
+```
+
+`MarkdownView` and `TextEdit` both wear it, so they render identical typography. It is expressed as
+descendant rules (`[&_h1]:…`), which means an element-level class on a child **loses** to it
+(specificity (0,1,0) against (0,1,1)) — restyle by composing `prose` (the per-element record), never
+by setting a class on the rendered element.
+
+**A selected chip on a muted track has a third recipe.** If you are building a view switcher, a
+segmented control or chip-shaped tabs of your own, take `selectedChipVariants` rather than inventing
+a selected look — it is the same formula `Tabs`, `Segmented` and `Toggle` use:
+
+```tsx
+import { cn, selectedChipVariants } from "@vegastack/design";
+
+<div className={cn("rounded-md p-0.5", selectedChipVariants.track)}>
+  <Toggle
+    className={cn(
+      "rounded-sm",
+      selectedChipVariants.item,
+      selectedChipVariants.pressed,
+    )}
+  />
+</div>;
+```
+
+Use `.pressed` for a control whose selected state is Base UI's `data-pressed` and `.active` for one
+using `data-active`. The selected chip keeps its own hover and pressed steps — never guard them off.
+
+`secondary`, `muted`, `accent` and the `sidebar-*` family are **aliases** of ladder rungs
+(`secondary` = `muted` = `surface-1`, `accent` = `sidebar-accent` = `surface-2`, `sidebar` = `card`).
+They still compile; name the rung in new code.
+
+`border` is one translucent hairline — `foreground` at `--alpha-border` — so it reads on the page, on
+a card and inside a well alike. `info` is **links and informational UI only**: promotion and
+selection take a ladder rung or `primary`.
 
 Alpha and opacity are **different roles**: colour compositing takes an `--alpha-*` token
 (`bg-foreground/(--alpha-ink-tint)`), whole-element opacity takes an `--opacity-*` token
@@ -73,7 +160,17 @@ contract.
 ## Composition patterns
 
 - **Forms** — Base UI `Field` + react-hook-form `Controller` + Zod 4 (`z.email()`). `Field.Control`
-  emits `onValueChange`, not a DOM `onChange` event.
+  emits `onValueChange`, not a DOM `onChange` event. **`Field` owns the feedback layer**: helper text
+  renders below the control, the error below that as a polite `role="status"`, and the invalid shake
+  belongs to the field — wrap a control in a `Field` to get it, and pass `shakeSignal` (a
+  submit-attempt counter) there to re-shake a field that never stopped being invalid. A bare
+  `<Input aria-invalid>` outside a `Field` tints its border and does not move.
+- **A set of related checkboxes is a `CheckboxGroup`** — pass `allValues` and mark one child
+  `parent` to get select-all with the mixed state, rather than computing checked/indeterminate in
+  your own state. Name the group with a `FieldSet`/`FieldLegend` or `aria-labelledby`.
+- **Click-to-edit is `useInlineEdit`** — draft, commit, cancel, focus restoration and the
+  double-commit guard, with no opinion about the editor or the display. `FieldInline` and
+  `EditableCell` are built on it.
 - **Overlays** — enter/exit is driven by `data-starting-style`/`data-ending-style` on the popup root,
   inside a portal + positioner. Theme, toast, tooltip, and direction providers all come from
   `<VegaStackProvider>`; your app root needs `isolation: isolate` or portaled popups can render under
@@ -95,6 +192,8 @@ contract.
   chrome.
 - Implement every applicable state: default, hover, focus, loading, empty, error, success, disabled.
 - Put `truncate` on an inner span, with `min-w-0` on the flex container.
+- Let the parent decide a form control's width — every control is `w-full` and takes its height from
+  the `--size-*` scale.
 
 **Don't**
 
@@ -104,6 +203,9 @@ contract.
 - Set `outline-none` without providing another focus affordance.
 - Pull in a second icon library or hand-write an inline `<svg>` as an icon.
 - Put `uppercase` on non-mono type, or on anything above 14px.
+- Hand-roll a removable pill, or a `role="status"` live region with its own sequence counter.
+- Give a form control a fixed width (`w-56`, `w-64`) — it reads fine on the page it was tuned for
+  and overflows at 320px. Constrain the parent instead.
 
 ## Reference
 

package/skills/vegastack-design-system/references/components.md

@@ -3,7 +3,7 @@
 <!-- GENERATED — do not hand-edit. Regenerated from the design system's component contract,
      which is the authority for membership and counts. -->
 
-**110 components**, plus 439 animated-icon items, 6 hooks (`use-animation-replay`, `use-drag-reorder`, `use-file-drop`, `use-list-nav`, `use-mobile`, `use-platform`), and 1 starter block (`dashboard-01`) — 556 registry items in total.
+**116 components**, plus 467 animated-icon items, 11 hooks (`use-animation-replay`, `use-announcer`, `use-drag-reorder`, `use-file-drop`, `use-inline-edit`, `use-list-nav`, `use-media-query`, `use-mobile`, `use-modal-inert`, `use-overflow`, `use-platform`), 1 starter block (`dashboard-01`), and 2 data libs (`geo-data`, `drag-item`) — 597 registry items in total.
 
 Install any of them with `shadcn add @vegastack/<name>`. Animated icons install as
 `@vegastack/icon-<name>`; the bare name is reserved for components, so `icon-button` is the
@@ -11,9 +11,9 @@ component and never an icon.
 
 ## Actions
 
-- **`button`** — Trigger an action. 15 variants × 8 sizes, with loading + Base UI Button semantics.
+- **`button`** — Trigger an action. Six variants × five tones × four sizes, with loading + Base UI Button semantics.
 - **`copy-button`** — Copy a value to the clipboard with transient check feedback — a ghost icon button that swaps Copy → Check and fires onCopied.
-- **`icon-button`** — A square, icon-only action button — a thin Button wrapper that requires an accessible label.
+- **`icon-button`** — A square or round icon-only action button — a thin Button wrapper that requires an accessible label.
 - **`segmented`** — Segmented control — a single-select, always-one-selected view/mode switcher on a muted track with a raised active chip.
 - **`split-button`** — A primary action joined to a dropdown of related secondary actions — one default click, plus a chevron menu.
 - **`toggle`** — A two-state button that can be pressed on or off — bold/italic, mute, pin.
@@ -23,30 +23,33 @@ component and never an icon.
 
 - **`auto-save-input`** — An input that debounces edits and persists them via an async onSave, with an inline idle/saving/saved/error status.
 - **`checkbox`** — A binary (or tri-state) toggle — checked, unchecked, indeterminate, disabled, built on Base UI Checkbox.
+- **`checkbox-group`** — Shared state for a set of checkboxes, with first-class “select all” — parent, mixed, and the whole-set toggle, built on Base UI Checkbox Group.
 - **`chip-input`** — Free-token entry field — Enter/comma/paste commits chips, Backspace removes, per-chip validation marks invalid entries instead of dropping them. Combobox field chrome + real Tag chips.
 - **`color-picker`** — A swatch-triggered popover presenting a grid of preset colors — pick one, fire onValueChange, mark the selection.
 - **`combobox`** — A filterable, keyboard-navigable listbox behind a text input — type-to-filter, grouped items, async status, and a multi-select chip mode.
-- **`country-select`** — A searchable country combobox returning the ISO 3166-1 alpha-2 code, with flag + name. Built on Combobox.
+- **`country-select`** — A searchable country picker returning the ISO 3166-1 alpha-2 code, with flag + name. A thin wrapper over SearchableSelect fed by the geo-data item.
 - **`date-picker`** — Pick a single date or a date range from a calendar popover — token-styled, keyboard-navigable, with optional quick presets.
 - **`dropzone`** — File acquisition surface — drop, click-to-browse, and paste — as a thin shell over use-file-drop; the surface is the named focusable control over a hidden picker-bridge input; data-dragging/data-drag-invalid styling flags.
 - **`editable-cell`** — Inline-editable value with an async commit lifecycle — optimistic display, saving/saved/error status, revert on a rejected write, and a typed text/select/custom editor registry.
 - **`emoji-picker`** — A popover with a searchable, category-grouped grid of emoji that returns the selected character via onSelect (curated set, not full Unicode).
 - **`field`** — A form-field wrapper — label, inline label action, description, and error/success message, built on Base UI Field.
 - **`field-inline`** — Click-to-edit text — displays a value, swaps to a focused input on click, commits on Enter or blur, cancels on Escape.
-- **`input`** — A styled Base UI input — all input types, Field state data attributes, error and disabled states, focus-visible ring, and optional prefix/suffix addons.
+- **`input`** — A styled Base UI input — all input types, Field state data attributes, error and disabled states, a focus border tint, and optional prefix/suffix addons.
 - **`label`** — A styled native label for form controls — htmlFor association, disabled dimming, optional required indicator.
 - **`number-field`** — Locale-aware numeric input on Base UI's NumberField in Input's field chrome — Intl formatting (money is a format prop), min/max/step, keyboard stepping, wheel scrub, full-height steppers.
 - **`otp-input`** — A multi-slot one-time-passcode input — keyboard navigation, paste distribution, masking, disabled, built on Base UI OTP Field.
 - **`password-input`** — A password field with a show/hide eye toggle and an optional live requirements checklist.
 - **`radio-group`** — A set of mutually-exclusive options — single selection, arrow-key navigation, disabled, built on Base UI Radio Group.
-- **`region-select`** — A searchable combobox of states/provinces for a country, with a free-text fallback for countries with no subdivisions.
+- **`region-select`** — A searchable picker of states/provinces for a country, with a free-text fallback for countries with no subdivisions. A thin wrapper over SearchableSelect fed by the geo-data item.
+- **`searchable-select`** — The Select-shaped Combobox preset: a full-width trigger, an in-panel search field, a check on the selected row and an optional clear control. Single-select, controlled through value/onValueChange.
 - **`select`** — A dropdown for choosing one option — trigger with value and chevron, grouped scrollable popup, full keyboard navigation, animated enter/exit.
 - **`slider`** — Pick a number or a [from, to] range from a continuous track — keyboard accessible, with optional steps. Built on Base UI Slider.
 - **`switch`** — An on/off toggle for instant, self-saving binary settings — built on Base UI Switch.
-- **`textarea`** — A styled native textarea for multi-line text — error/disabled states, a focus-visible ring, and an optional auto-grow mode.
+- **`textarea`** — A styled native textarea for multi-line text — error/disabled states, a focus border tint, and an optional auto-grow mode.
 
 ## Display
 
+- **`chip`** — The one labelled pill primitive — 10 decorative hues, two tiers, an optional selection rung, and a real 24x24 remove control. Behind Tag, FilterChip and Combobox chips.
 - **`code-block`** — A code panel with a language header and copy affordance — the shared code surface for chat transcripts, docs, and examples.
 - **`onboarding-checklist`** — A getting-started card — segmented progress + step rows, collapsible to a progress pill.
 - **`stat`** — A labelled value block — muted label over a value, honest faint empty state, optional delta line. Two scales.
@@ -57,24 +60,25 @@ component and never an icon.
 - **`accordion`** — A stack of collapsible sections — single or multiple open, animated height, a rotating chevron, full keyboard support.
 - **`animated-number`** — A number display that tweens from its previous value to a new one on every change — Intl.NumberFormat-aware (currency/percent/compact), instant under reduced motion, the dashboard stat-card counter.
 - **`avatar`** — A circular user/entity image with an initials fallback, five sizes, and an overlapping AvatarGroup stack.
-- **`badge`** — A compact status or label chip. 3 variants × semantic colors × 4 sizes, with dot, loading, and icon support.
+- **`badge`** — A compact status or label chip — solid / soft / outline / minimal × 5 semantic colors × 3 real size tiers, with a dot, a leading icon, and loading.
 - **`card`** — A borders-only content surface — no shadows, with composable header, content, and footer parts.
 - **`chart`** — A themed Recharts wrapper — token-only series colors (--chart-1…--chart-8), a bordered tooltip/legend, and Recharts' own built-in keyboard + screen-reader layer.
 - **`collapsible`** — A single toggleable open/close region with an animated height, built on Base UI Collapsible.
-- **`empty`** — A zero-data placeholder — icon, title, description, actions, with intent tints and an optional dashed border.
+- **`empty`** — A zero-data placeholder — icon, title, description, actions, with intent tints and a plain, card, or dashed container.
 - **`item`** — A compact anatomy row for list/feed content — media, title, description, actions, groupable with dividers.
-- **`kbd`** — A styled keyboard-key indicator — OS-aware modifier glyphs, a keys array, and small sizes.
+- **`kbd`** — The one keyboard-key chip — modifier labels the caller resolves per platform, a keys array, and three inline sizes.
 - **`markdown-view`** — Render a markdown string to safe, token-styled HTML — headings, lists, code, blockquotes, links, GFM tables — XSS-safe, no raw HTML.
 - **`relative-time`** — Render a date as a human-relative string ("2 hours ago", "yesterday") with native Intl.RelativeTimeFormat — self-updating, with an absolute-date tooltip.
 - **`status-icon`** — A small status indicator icon — todo, in progress, blocked, done — each mapping to a lucide icon and semantic color.
 - **`table`** — Styled semantic table primitives — a scrollable container plus header, body, footer, row, head, cell, caption.
 - **`timeline`** — Rail geometry for chronological records — a continuous connector with a node per entry. Rows compose Item parts; separators render through Marker; entries carry content-visibility render skipping.
-- **`truncated-text`** — Truncate text to one line or N lines with an ellipsis, revealing the full text in a tooltip only when it overflows.
+- **`truncated-text`** — Truncate text to one line or N lines with an ellipsis, revealing the full text in a tooltip only when it overflows — with per-region control over the tab stop.
 
 ## Data
 
 - **`data-grid`** — The full-parity grid — TanStack-sorted multi-key sort, column picker with responsive revelation, collapsible grouping, keyboard-continuous load-more, opt-in virtualization, and an APG grid keyboard layer with inline cell editing.
 - **`data-list`** — A generic, typed data table — configurable columns, row selection, sortable headers, plus loading and empty states.
+- **`data-table-parts`** — The chrome DataList and DataGrid share — sort header, selection cells, skeleton rows, the empty row, column class rules, and the selection/sort/controlled-state hooks.
 - **`filter-bar`** — A row of removable filter chips, an "Add filter" dropdown, and an optional search input — for list and table filter toolbars.
 - **`filter-bar-managed`** — The stateful nested and/or filter builder — host-injected field grammar (vocabulary + per-type value editors), depth and condition caps, focus-managed removal, and a removable FilterChip summary.
 - **`property-list`** — Record-facts rows: an icon+label column beside a value column, as an accessible definition list.
@@ -86,6 +90,7 @@ component and never an icon.
 - **`context-menu`** — A menu of actions revealed by right-click (or long-press) — items, submenus, separators, labels, shortcuts, checkbox/radio.
 - **`dialog`** — A modal overlay — five sizes, a header/footer layout, focus trapping, and animated enter/exit.
 - **`dropdown-menu`** — A menu of actions triggered by a button — items, submenus, separators, labels, shortcuts, and checkbox/radio selections.
+- **`floating-surface`** — The shared floating-overlay module: one Portal/Positioner/Popup composer, the popup surface recipes, the list-item recipe, and the in-panel search row.
 - **`hover-card`** — A rich preview panel that opens on hover or focus — interactive content, four directions, forgiving delays.
 - **`popover`** — A click-triggered floating panel for arbitrary content — positioning, an optional arrow, and built-in dismiss.
 - **`sheet`** — A dialog that slides in from a screen edge — four sides, header/footer layout, focus trapping, animated slide.
@@ -107,12 +112,12 @@ component and never an icon.
 
 - **`action-bar`** — Floating contextual bar — status region + action children, CSS-only enter/exit, raised band. Bulk selection, unsaved changes, and batch progress are recipes over it.
 - **`alert`** — A status banner — five semantic variants, an optional icon, and an optional dismiss button.
-- **`progress`** — A determinate horizontal progress bar for measurable, ongoing tasks — built on Base UI Progress.
+- **`progress`** — A horizontal progress bar for measurable, ongoing tasks — determinate or a sweeping indeterminate segment, built on Base UI Progress.
 - **`progress-indicator`** — A compact circular pie-fill progress indicator (0–100%) with optional visible percentage variants.
-- **`provider`** — The single app-root wrapper — theme (next-themes), Sonner toasts, tooltip coordination, and text direction in one mount-once component.
-- **`skeleton`** — A token-driven loading placeholder — line, circle, rect, card shapes, configurable count, reduced-motion-aware pulse.
-- **`sonner`** — Brief, non-blocking notifications — a token-styled Sonner toaster with success/error/warning/info variants that follows the theme.
+- **`provider`** — The single app-root wrapper — theme (next-themes), Base UI toasts, tooltip delays, and text direction in one mount-once component.
+- **`skeleton`** — A token-driven loading placeholder — line, circle, rect, card shapes, a configurable count, and a pulse that stops under reduced motion.
 - **`spinner`** — An indeterminate loading indicator — a spinning icon inheriting currentColor, four sizes, role=status by default.
+- **`toast`** — Brief, non-blocking notifications — a stacking Base UI Toast surface with success, error, warning, info and loading types, promise toasts and swipe-to-dismiss.
 
 ## Layout
 
@@ -127,6 +132,7 @@ component and never an icon.
 
 - **`audio-player`** — A custom audio transport with play/pause, skip, seek, a tappable speed control, and keyboard shortcuts (mute on the M key); a single line on a wide player, two lines with an optional transcript control on a narrow, mobile-width player.
 - **`image`** — A presentational framed image with aspect-ratio, rounding, a loading skeleton, and an error fallback.
+- **`media-player-controls`** — The shared media transport — play/pause, skip, seek, elapsed/duration, mute + volume, playback speed, and one keyboard shortcut map (useMediaShortcuts) — composed by Audio Player and Video Player.
 - **`notification-bell`** — A bell icon button with an unread-count badge overlay. Presentational — the app supplies the count.
 - **`video-player`** — A framed video player with the same grouped custom transport controls as Audio Player.
 

package/dist/chunk-FBU37ITM.js

@@ -1,52 +0,0 @@
-// src/index.ts
-import { clsx } from "clsx";
-import { extendTailwindMerge } from "tailwind-merge";
-var twMerge = extendTailwindMerge({
-  extend: {
-    classGroups: {
-      "font-size": [
-        {
-          text: [
-            "h1",
-            "h2",
-            "h3",
-            "h4",
-            "label",
-            "label-sm",
-            "code",
-            "code-sm",
-            "mono-label",
-            "display-sm",
-            "display-md",
-            "display-lg",
-            "display-xl"
-          ]
-        }
-      ]
-    }
-  }
-});
-function cn(...inputs) {
-  return twMerge(clsx(inputs));
-}
-var TIMINGS = {
-  /** How long transient success feedback holds before reverting (CopyButton "Copied ✓"). */
-  feedbackRevertMs: 1500,
-  /** Debounce before auto-persisting a text field (AutoSaveInput). */
-  autoSaveDebounceMs: 800,
-  /** Hover delay before a rich preview (HoverCard) opens — guards accidental opens. */
-  hoverOpenDelayMs: 700,
-  /** Hover delay before a rich preview closes — lets the pointer travel into the card. */
-  hoverCloseDelayMs: 300
-};
-var FLOATING = {
-  sideOffsetAttached: 4,
-  sideOffsetDetached: 8,
-  collisionPadding: 8
-};
-
-export {
-  cn,
-  TIMINGS,
-  FLOATING
-};