@acronis-platform/ui-react 4.0.0 → 5.0.0

package/dist/llms/input-num-picker.md

@@ -0,0 +1,180 @@
+# InputNumPicker
+
+> A numeric stepper field: an optional label (with an optional required marker), and a bordered box with decrement/increment buttons around the numeric value. Built on Base UI's NumberField and its own `--ui-input-num-picker-*` token tier; the steppers reuse `ButtonIconInput`.
+
+**Status:** ready · **Category:** forms · **Since:** v3.0.0
+
+## Import
+
+```tsx
+import { InputNumPicker } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputNumPicker label="Quantity" defaultValue={1} min={0} max={10} />
+
+{/* Required */}
+<InputNumPicker label="Quantity" required />
+
+{/* Controlled */}
+<InputNumPicker label="Quantity" value={value} onValueChange={setValue} />
+```
+
+A numeric stepper field: an optional label (with an optional required
+marker), and a bordered box with decrement/increment buttons around the
+numeric value. Built on Base UI's `NumberField`; the steppers reuse the
+already-themed [`ButtonIconInput`](../button-icon-input/README.md).
+
+## When to use
+
+- A small, labelled numeric input where the primary interaction is
+  incrementing/decrementing by a fixed step (quantity pickers, counters).
+
+## When not to use
+
+- For a bare numeric field with no label/steppers — use Base UI's
+  `NumberField` primitives directly.
+- For free-form numeric or text entry without stepping — use `InputText`.
+
+## Examples
+
+```tsx
+import { InputNumPicker } from '@acronis-platform/ui-react';
+
+// Basic field
+<InputNumPicker label="Quantity" defaultValue={1} min={0} max={10} />;
+
+// Required
+<InputNumPicker label="Quantity" required />;
+
+// Controlled
+<InputNumPicker label="Quantity" value={value} onValueChange={setValue} />;
+
+// Disabled
+<InputNumPicker label="Quantity" disabled defaultValue={3} />;
+```
+
+## Parts
+
+| Part        | Element    | Description                                        |
+| ----------- | ---------- | -------------------------------------------------- |
+| `label`     | `<label>`  | Field label (associated via `htmlFor`/`id`).       |
+| `required`  | `<span>`   | Required `*` marker (decorative; `aria-hidden`).   |
+| `box`       | `<div>`    | The bordered box wrapping the steppers + value.    |
+| `decrement` | `<button>` | Decrement (−) stepper; a themed `ButtonIconInput`. |
+| `value`     | `<input>`  | The numeric value, centered.                       |
+| `increment` | `<button>` | Increment (+) stepper; a themed `ButtonIconInput`. |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `label` | `ReactNode` | — | no | Field label rendered above the box, associated via `htmlFor`/`id`. |
+| `required` | `boolean` | `false` | no | Appends a required marker (`*`) after the label and sets `required` on the field. |
+| `disabled` | `boolean` | `false` | no | Disables the field and both steppers (native `disabled`). |
+| `min` | `number` | — | no | The minimum value of the field. |
+| `max` | `number` | — | no | The maximum value of the field. |
+| `step` | `number | "any"` | `1` | no | Amount to increment/decrement with the steppers or arrow keys. |
+| `value` | `number | null` | — | no | Controlled numeric value. |
+| `defaultValue` | `number` | — | no | Uncontrolled initial numeric value. |
+| `decrementLabel` | `string` | `Decrease` | no | Accessible label for the decrement button. |
+| `incrementLabel` | `string` | `Increase` | no | Accessible label for the increment button. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onValueChange` | `value: number | null, eventDetails` | Fired when the numeric value changes (typing, steppers, keyboard). |
+| `onValueCommitted` | `value: number | null, eventDetails` | Fired when a value change is committed (blur, pointer release). |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `label` | The label content. |
+
+## Behavior
+
+### Rendering
+
+**Given** a `label`
+**When** the field renders
+**Then** the label appears above the box and is associated with the value
+input via `htmlFor`/`id` (clicking the label focuses the input).
+
+**Given** no `label`
+**When** the field renders
+**Then** no label element is rendered.
+
+**Given** `required`
+**When** the field renders
+**Then** a `*` marker is appended after the label and the field is marked
+required.
+
+### Stepping
+
+**Given** the increment button
+**When** it is activated (click, Enter, or Space)
+**Then** the value increases by `step` (default `1`) and `onValueChange`
+fires with the new value.
+
+**Given** the decrement button
+**When** it is activated
+**Then** the value decreases by `step`.
+
+**Given** `min` / `max`
+**When** the value reaches either bound
+**Then** the corresponding stepper is disabled and further presses in that
+direction have no effect.
+
+**Given** the value input has keyboard focus
+**When** the user presses Arrow Up / Arrow Down
+**Then** the value increases / decreases by `step`; Shift snaps to
+`largeStep`.
+
+### Interaction
+
+**Given** the box
+**When** the pointer hovers over it, or the value input receives keyboard
+focus
+**Then** the border shifts to its hover token, and keyboard focus additionally
+paints a 3px `--ui-focus-primary` ring.
+
+**Given** the field is `disabled`
+**Then** the value input and both steppers are inert and styled with their
+disabled tokens.
+
+## Accessibility
+
+- **Label association:** the `label` is a real `<label htmlFor>` tied to the
+  value input's `id` (auto-generated when not supplied), so clicking it
+  focuses the input and screen readers announce the field name.
+- **Required:** `required` is set on the field; the visual `*` marker is
+  `aria-hidden` (the asterisk is decorative — the required semantics come from
+  the field, not the glyph).
+- **Stepper labels:** `decrementLabel`/`incrementLabel` (default "Decrease" /
+  "Increase") give each stepper button an accessible name via `aria-label`,
+  since the buttons carry only a glyph.
+- **Keyboard:** the value input supports Arrow Up/Down (± `step`), Shift+Arrow
+  (± `largeStep`), Home/End (to `min`/`max`). Both steppers are native
+  `<button>`s but Base UI's `NumberField` hard-codes `tabindex="-1"` on them, so
+  they are pointer-activated only and never receive keyboard focus. The tab
+  sequence through the component is: value input → the next focusable element
+  outside the component.
+- **Bounds:** a stepper is `disabled` (genuinely inert — it ignores pointer
+  activation, not just visually muted) once its direction is exhausted at
+  `min`/`max`.
+- **Focus visible:** keyboard focus on the value input paints a 3px
+  `--ui-focus-primary` ring on the box (the ring is painted by the box, not by
+  the input itself).
+- **Disabled:** native `disabled` removes the value input from the tab order and
+  makes both steppers inert.
+- **Contrast:** label / value / border pairs come from the design tokens,
+  authored to meet WCAG contrast.
+- **WCAG:** 1.3.1 (info/relationships), 2.1.1 (keyboard) — every value change
+  the steppers offer is also reachable from the keyboard on the value input
+  (Arrow Up/Down, Shift+Arrow, Home/End), so no functionality is pointer-only
+  even though the steppers themselves are pointer-activated — 2.4.7 (focus
+  visible), 1.4.3 / 1.4.11 (contrast), 4.1.2 (name, role, value).

package/dist/llms/input-select.md

@@ -45,7 +45,10 @@ The next-gen select **field**: a label (with an optional required marker), a tri
 box showing the value / placeholder and a chevron, an optional description or error,
 and a floating dropdown with an in-dropdown search, sections, single- or
 multiple-selectable items, and loading / empty / error status. It composes Base UI
-`Select` and the `--ui-input-select-*` token tier.
+`Select` and the `--ui-input-select-*` token tier. The dropdown's placement is
+controllable (`side` / `align` / offsets / collision avoidance, or an explicit
+`anchor` element to position against instead of the trigger), and
+`is-popover-styled` swaps its chrome to the popover look — see `behavior.md`.
 
 > `Select` is an alias of this family (re-pointed off the deleted `--ui-form-*` tier).
 > Prefer importing `InputSelect*` directly in new code.
@@ -151,6 +154,14 @@ use it inside a custom tree/item renderer to filter items the flat
 | `name` | `string` | — | no | Form field name submitted with the form (via a hidden input). |
 | `placeholder` | `string` | — | no | Hint shown by the value part when nothing is selected. |
 | `items` | `Record<string, string>` | — | no | Map of value → label for every selectable option, so the value part can render a selected option's label while the popup is closed without inspecting the rendered items. |
+| `side` | `'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end'` | `'bottom'` | no | On the content — which side of the trigger the popup renders on. |
+| `align` | `'start' | 'center' | 'end'` | `'start'` | no | On the content — alignment along the chosen side. |
+| `side-offset` | `number` | `4` | no | On the content — distance in px from the trigger. |
+| `align-offset` | `number` | `0` | no | On the content — offset in px along the alignment axis (perpendicular to `side`), to nudge the popup along the trigger's edge without changing its alignment. |
+| `collision-avoidance` | `{ side?: 'flip' | 'shift' | 'none'; align?: 'flip' | 'shift' | 'none'; fallbackAxisSide?: 'start' | 'end' | 'none' }` | `the platform default (flip/shift)` | no | On the content — collision-avoidance strategy. Pass `{ side: 'none', fallbackAxisSide: 'none' }` alongside an explicit `side`/`align` to lock the popup to that placement with no auto-flip fallback. |
+| `anchor` | `Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null` | `the trigger element` | no | On the content — element (or ref/getter) the popup positions itself against, overriding the default of anchoring to the trigger. Use when the visible trigger isn't the element tracked internally — e.g. an external button drives a hidden trigger, and the popup should align with the button instead. |
+| `portal-container` | `Element | ShadowRoot | null | RefObject<Element | ShadowRoot | null>` | `nearest PortalContainerProvider, or document.body` | no | On the content — container to portal the dropdown into. Pass an element to scope the portal (e.g. a shadow root, so the popup inherits styles defined there). |
+| `is-popover-styled` | `boolean` | `false` | no | On the content — render the dropdown chrome like `PopoverContent` (fade/zoom/slide animation, no shadow) instead of the default static-shadow dropdown chrome. |
 
 ## Events
 
@@ -229,6 +240,112 @@ border.
 **Then** it shows the matching icon and message (and, for `error`, an optional retry
 action).
 
+### Popup placement and chrome
+
+**Given** no positioning props on the content
+**When** the popup opens
+**Then** it is placed against the **trigger**, below it and aligned to its start
+edge, and the platform's own collision handling may flip or shift it to keep it in
+view. `side` / `align` / `side-offset` / `align-offset` / `collision-avoidance`
+each override one part of that; passing `collision-avoidance` with no fallbacks
+alongside an explicit `side` pins the popup to that placement even when it
+overflows.
+
+**Given** an `anchor` on the content
+**When** the popup opens
+**Then** it positions itself against **that** element instead of the trigger,
+decoupling where the popup appears from where the trigger sits in layout. This is
+for the case where the element the user actually operates is not the trigger — an
+external button drives the open state and the trigger stays mounted but visually
+hidden — so the popup should align with the button, not with the hidden trigger's
+position in flow. The trigger still owns the combobox semantics either way (see
+`accessibility.md`).
+
+**Given** an external button that drives a controlled `open` and is the popup's
+`anchor`
+**When** the user presses that button while the popup is open
+**Then** the platform reports the press as an **outside press** close before the
+button's own activation handler runs, so the consumer must cancel that specific
+close (`open-change` with `reason = outside-press` and the event target inside
+the button → `cancel()`) for the button to act as a toggle; otherwise the
+activation handler reopens the popup and it can never be dismissed from the
+button. A press outside both the button and the popup still closes it.
+
+**Given** an external button that drives a controlled `open`, with the real
+trigger kept mounted but visually hidden (screen-reader-only, not removed)
+**When** the popup closes via Escape or by selecting an item
+**Then** at the moment the close is reported focus is **still inside the popup
+that is about to unmount**, and the platform can move it to **its own trigger** —
+which is invisible — only **afterwards**, asynchronously. Neither path reports
+the close with focus already on the trigger. So the consumer must (a) mark the
+trigger `tab-index = -1` so it is never reached by Tab, and (b) reclaim focus for
+their visible external control themselves once the close is committed,
+**re-asserted once the platform's own focus-restore attempts have settled**. On
+Escape, a gate that recognizes "focus is still inside the closing popup" matches
+at the moment of the synchronous reclaim and moves focus to the external control
+before the platform's own move happens, so nothing overwrites it afterwards; the
+deferred re-assertion then finds the external control already focused and is a
+no-op. On item selection, the same synchronous reclaim also lands, but the
+platform's async move to the hidden trigger can still happen afterwards and pull
+focus back onto it — so the deferred re-assertion is load-bearing on this path,
+not a no-op, and reclaims focus a second time once that move has settled. Doing
+only one of (a)/(b) is a WCAG 2.4.7 failure: `tab-index = -1` does not block the
+platform's programmatic focus call, and the manual reclaim alone leaves an
+invisible control in the tab order. The reclaim belongs after the state commit
+in the same `open-change` handler, so a close the consumer cancels (see below)
+does not move focus.
+
+**Given** the same visually hidden trigger
+**When** the popup closes because of an outside press onto **nothing focusable**
+(a blank area of the page)
+**Then** the platform performs **no** focus restore at all — focus is simply lost
+to the document body. The consumer's own reclaim is the only thing that recovers
+it, so it must cover this case too, not just the trigger-focused one.
+
+**Given** the same visually hidden trigger
+**When** the popup closes because of an outside press onto **another focusable
+element** (an input elsewhere on the page)
+**Then** focus must end up on **that** element, not on the external button — the
+user deliberately focused it and pulling focus back is a bug. The platform
+reports this close **once** (reason = outside press), while focus is still inside
+the popup, so a gate keyed on "focus is unclaimed" (still inside the closing
+popup, on the hidden trigger, or on the document body) **does** match on that
+single report and does issue its focus call. The correct end state comes from the
+platform's own native focus move to the pressed element happening **after** that
+synchronous call and overriding it — not from the gate recognizing and skipping
+this case. What the gate does guarantee is that the **deferred** re-assertion
+cannot undo that: by the time it runs the pressed element holds focus, which is
+not an unclaimed state, so it is a no-op. An unconditional focus return on close
+is therefore still wrong — it would fire again after the platform's move and
+steal focus back.
+
+**Given** a cancelled close (the consumer called `cancel()` on `open-change`)
+**When** the popup therefore stays open
+**Then** the in-dropdown search query is **preserved** — a cancelled close does
+not silently clear what the user typed. (A consumer that leaves the close
+un-cancelled but simply doesn't act on it still gets the query reset; cancelling
+is what marks the close as not taking effect.)
+
+**Given** an external button that drives a controlled `open` and closes the
+popup directly (its own handler sets `open = false`, so the platform never
+reports the transition through `open-change`)
+**When** the popup is reopened
+**Then** the in-dropdown search query is **empty** — the reset follows the
+`open` prop's `true → false` transition as well as `open-change`, so a
+button-driven close cannot carry a stale query into the next open.
+
+**Given** `is-popover-styled`
+**When** the popup opens
+**Then** its container chrome is drawn from the **popover** tokens rather than the
+dropdown ones (fill / border / corner radius), the dropdown's static shadow is
+dropped, and open/close is animated (fade + zoom, sliding in from the resolved
+`side`) instead of appearing instantly. Reach for it when the dropdown is acting
+as a floating menu that should read in the same visual language as `Popover` —
+a tenant/entity picker opened from a page control, not a plain form field's
+option list. It changes only the container chrome and the enter/exit transition:
+the popup still sizes to the anchor width, keeps the dropdown's vertical padding,
+and every row inside (search, sections, items, status) is unchanged.
+
 ### Interaction
 
 **Given** the trigger
@@ -264,6 +381,63 @@ action).
   Arrow-key roaming inside the listbox skips it entirely — it cannot be
   reached with the keyboard once the popup is open, only by pointer. It
   remains a normal native tab stop outside that roving focus order.
+- **Decoupled anchor:** `anchor` moves only where the popup is _drawn_ — the
+  combobox semantics (`aria-expanded`, `aria-controls`, the accessible name) and
+  the focus return on close stay on the **trigger**, and cannot be relocated. So
+  if the visible control is a separate element (an external button opening a
+  visually hidden trigger), that button needs its own accessible name (visible
+  text or `aria-label`) and, because it is the control the user actually
+  operates, its own `aria-expanded` bound to the same controlled `open` state
+  that drives the popup. `aria-controls` on the button is optional and only
+  wirable by giving `InputSelectContent` an explicit `id` and referencing it
+  while the popup is open. Keep the trigger reachable — do not `display: none`
+  it, or closing returns focus to nothing. Prefer opening from the real trigger
+  whenever the design allows it.
+- **Visually hidden trigger — focus is the consumer's job (2.4.7):** leaving the
+  trigger merely `sr-only`-reachable is **not** sufficient. It is still
+  focusable while invisible, and on the close paths where the platform restores
+  focus to it (Escape, selecting an item) keyboard focus lands on a control the
+  user cannot see — a WCAG 2.4.7 Focus Visible failure. On other close paths
+  (an outside press onto nothing focusable) the platform does not restore focus
+  at all and it is simply lost to the document body — also a failure. The
+  required pattern is **both** of:
+  1. `tabIndex={-1}` on the **trigger** (`InputSelectTrigger`) — not on the
+     `InputSelectField` wrapper, which is a plain non-focusable element — so the
+     invisible trigger is out of the natural Tab sequence;
+  2. a **conditional** focus return to the consumer's own visible control on
+     close (`onOpenChange` → after committing the new state, `if (!nextOpen)`
+     reclaim focus for the external button). Two properties of the platform make
+     this non-trivial. First, **the platform's own focus restore may still be
+     pending when the close is reported** — on the Escape and item-selection
+     paths focus is still inside the popup that is about to unmount at handler
+     time, and the move to the (invisible) trigger can land afterwards. On
+     Escape a synchronous reclaim already lands on the visible control before
+     that move happens, so nothing overwrites it; on item selection the
+     platform's move can still land on the hidden trigger after a synchronous
+     reclaim, so the reclaim must be re-asserted once that settles. Second,
+     **on some close reasons the platform's restore does not happen at all** —
+     an outside press onto nothing focusable leaves focus on the document
+     body. So the focus return must be **re-asserted once the platform's own
+     focus-restore attempts have settled**, not only synchronously during the
+     handler — even where the synchronous call already suffices, the deferred
+     re-assertion is a harmless no-op.
+     Crucially, the reclaim must **never override an element the user has
+     legitimately focused since** — an outside press onto another focusable
+     control is that user's choice of focus, and an unconditional refocus steals
+     it. Gate the reclaim on focus being _unclaimed_: still inside the closing
+     popup, on the hidden trigger, or lost to the document body. Anything else
+     is left alone.
+     `tabIndex={-1}` alone does not stop the platform's programmatic `.focus()`
+     call, and the reclaim alone leaves the invisible trigger in the Tab order —
+     each fixes one half. The reclaim must sit after the state commit, so the
+     cancelled `outside-press` branch (which returns early) does not move focus
+     for a close that never happened.
+- **External-button toggle:** an external button must also cancel the
+  `outside-press` close that its own pointerdown triggers (`onOpenChange` →
+  `eventDetails.reason === 'outside-press'` and the event target inside the
+  button → `eventDetails.cancel()`), otherwise the popup cannot be dismissed
+  from the button at all — a keyboard/AT user who activates the button a second
+  time gets a popup that reopens instead of closing. Escape still closes it.
 - **Selection indicator:** single-select shows a trailing check on the selected item;
   multiple-select shows a leading checkbox per item (not focusable — the row is the
   control).

package/dist/llms/radar-chart.md

@@ -98,8 +98,8 @@ across brands until the real data-viz palette lands.
 | `seriesSettings` | `Record<string, RadarChartSeriesSettings>` | — | no | Per-series style overrides keyed by a `dataKeys` entry — `color`, `stroke`, `fillOpacity`, `strokeWidth`, `dot`, `dotRadius`, `activeDot`. Unplotted keys are ignored. An overridden `color` — or `stroke`, which the renderer reads first — carries into that series' legend swatch and tooltip dot. |
 | `fillOpacity` | `number` | `0.3` | no | Fill opacity of each radar area. |
 | `strokeWidth` | `number` | `2` | no | Stroke width of each radar outline. |
-| `showDots` | `boolean` | `false` | no | Render a dot at each axis point. |
-| `dotRadius` | `number` | `3` | no | Radius of the per-point dots when `showDots` is on. |
+| `showDots` | `boolean` | `true` | no | Render a dot at each axis point. Visible by default to match the Figma chart. |
+| `dotRadius` | `number` | `2` | no | Radius of the per-point dots when `showDots` is on. |
 | `activeDot` | `boolean` | `true` | no | Enlarge the hovered point's dot. On by default; `false` for a chart that should not react to the pointer. |
 | `showGrid` | `boolean` | `true` | no | Render the polar grid (the web). |
 | `radialLines` | `boolean` | `true` | no | Draw the grid's spokes (the radial lines out to each category). Off leaves only the concentric rings. |
@@ -117,15 +117,14 @@ across brands until the real data-viz palette lands.
 | `radiusAxisTickCount` | `number` | `5` | no | Desired number of ticks on the value scale (a hint, not exact). Also sets how many rings the grid draws, whether or not the scale is shown. |
 | `radiusAxisReversed` | `boolean` | `false` | no | Invert the value scale (maximum at the centre) for a metric where less is better. |
 | `cx` | `number | string` | `'50%'` | no | Horizontal centre of the web, in px or a percentage of the width. |
-| `cy` | `number | string` | `'50%'` | no | Vertical centre of the web, in px or a percentage of the height. |
+| `cy` | `number | string` | `the middle of the plot band` | no | Vertical centre of the web, in px or a percentage of the height. Defaults to the middle of the plot band — 50% of what the legend leaves, not of the whole box — because the underlying chart centres a polar plot on the whole surface and takes no account of the legend band beneath it. |
 | `startAngle` | `number` | `90` | no | Angle the first category sits at, in degrees. |
 | `endAngle` | `number` | `-270` | no | Angle the sweep ends at, in degrees — a full clockwise turn from `startAngle` by default. |
 | `innerRadius` | `number | string` | `0` | no | Radius of the hole at the centre, in px or a percentage of the available radius. Lifts the grid and the areas off the centre. |
-| `outerRadius` | `number | string` | `'80%'` | no | Outer radius of the web, in px or a percentage of the available radius. |
+| `outerRadius` | `number | string` | `78` | no | Outer radius of the web, in px or a percentage of the available radius. Defaults to 78px to match the Figma geometry; the legend and labels do not change the radius. |
 | `margin` | `{ top?: number; right?: number; bottom?: number; left?: number }` | — | no | Plot-area margin, in px. Passing the object replaces all four sides; a side left out is `0`, not the default `5`, so name every side. |
 | `showTooltip` | `boolean` | `true` | no | Render the hover tooltip. |
 | `showLegend` | `boolean` | `true` | no | Render the legend. |
-| `legendPosition` | `'top' | 'bottom'` | `'bottom'` | no | Which side of the chart the legend sits on. |
 | `tooltipContent` | `ReactElement | ((props) => ReactNode)` | — | no | Replace the default tooltip. Pass a configured ChartTooltipContent (from this library) — e.g. with a formatter / labelFormatter — to customize the tooltip content without composing recharts. Ignored when showTooltip is false. |
 | `animate` | `boolean` | `false` | no | Enable entrance animation. Off by default so output/baselines are unchanged. |
 | `animationDuration` | `number` | — | no | Animation duration in ms. |
@@ -231,6 +230,17 @@ Scenario: Geometry
   Then the web, its axes, and the areas are all laid out to match
 ```
 
+```gherkin
+Scenario: The box holds the category labels
+  Given a fixed outerRadius
+  Then the chart reserves a plot band tall enough for the outer category labels
+    — the outer radius, the tick size, and half a line of tick text on each side
+  And showLabels, which widens the tick gap, widens that band with it
+  And the web is centred on the plot band rather than on the whole box, so the
+    bottom label clears the legend and the top one clears the upper edge
+  And a caller-supplied height or cy wins over both
+```
+
 ```gherkin
 Scenario: Tooltip on hover
   Given showTooltip is true

package/dist/llms.txt

@@ -1,6 +1,6 @@
 # Acronis UI Kit for React — LLM Reference
 
-> `@acronis-platform/ui-react` v4.0.0
+> `@acronis-platform/ui-react` v5.0.0
 
 Machine-readable component reference compiled from framework-agnostic specs.
 Each entry links to a self-contained markdown file with props, behavior,
@@ -44,7 +44,7 @@ accessibility notes, and usage examples.
 - [EmptyOverlay](./llms/empty-overlay.md): A full-bleed empty-state overlay — a colored icon badge over a centered title/description, on a fade-to-solid backdrop. Meant to sit over other content (e.g. a frozen/blurred widget preview); the developer sizes it (typically `absolute inset-0` over a positioned parent).
 - [FilterCards](./llms/filter-cards.md): A horizontal row container (the Figma `FilterCards` component) that lays out a set of `CardFilter` items, stretching each to an equal share of the available width. Pure layout — it owns no visual styling of its own besides the inter-card gap. Figma's nested `ListCards` slot maps to `children`.
 - [FilterChips](./llms/filter-chips.md): A wrapping row that summarises the filters currently applied to a data set (the Figma `FilterChips` component): one removable `Chip` per filter, closed by a ghost "Reset filters" action that clears them all at once. Pure layout — it owns no visual styling of its own besides the two gaps. Figma's nested `ListChips` slot maps to `FilterChipsList`'s children.
-- [FunnelChart](./llms/funnel-chart.md): A typed funnel-chart composition over the shared `Chart` primitives. Plots a single series of stages (rows) as stacked, narrowing segments inside a `ChartContainer`, with a tooltip and on-chart stage labels (no legend — the inline labels name every stage). One variant axis: `lastShape` (the funnel narrows to a `triangle` point or ends `rectangle` flat). Ported from the apps/demo `FunnelChartPlayground`.
+- [FunnelChart](./llms/funnel-chart.md): A typed funnel-chart composition over the shared `Chart` primitives. The root is a row: a 120×120 square plot, a 16px gutter, then a stage-list legend taking every remaining pixel — the same composition `PieChart` and `RadialBarChart` use. The plot stacks one series of stages (`data` rows) as narrowing, 2px-gapped, 2px-rounded segments inside a `ChartContainer`, with a tooltip and optional on-plot labels. One variant axis: `lastShape` (the funnel narrows to a `triangle` point or ends `rectangle` flat). Stages are painted from the sequential blue ramp by default, because a funnel's stages are an ordered series rather than unrelated categories. Card-less by design: Figma's card, header and metric row are `ChartWidget`'s.
 - [Histogram](./llms/histogram.md): A frequency histogram — bins a set of continuous samples (`values`) into equal-width ranges and plots the count of each as contiguous bars. Distinct from `BarChart`, which plots pre-categorized rows: the binning is the component's own job (a pure helper). Built on the shared `Chart` primitives; design-pending v1 (no `--ui-chart-*` palette yet, no `apps/demo` playground).
 - [LineChart](./llms/line-chart.md): A typed line-chart composition over the shared `Chart` primitives. Takes `data` + `config` + a set of series `dataKeys` and renders a themed recharts `LineChart` inside a `ChartContainer`, with tooltip and legend chrome. Two variant axes: `curve` (linear / monotone / step interpolation) and `lineStyle` (solid / dashed stroke); single vs multi line is driven by the number of `dataKeys`. Ported from the apps/demo `ChartPlayground`.
 - [Meter](./llms/meter.md): A labelled bar showing a scalar value within a known range — a fractional value / share (`role="meter"`, mirroring the HTML `<meter>` element), as opposed to `Progress` which tracks a task over time. One row: label + `value · %` over a proportional track bar, with a hover tooltip; designed to be stacked into a ranked breakdown (a "bar list"). Design-pending v1 (no `--ui-chart-*` palette; the fill color is caller-supplied per row).
@@ -82,6 +82,7 @@ accessibility notes, and usage examples.
 - [Field](./llms/field.md): A form-field wrapper that ties a control to its label, description, and error, built on Base UI's Field primitive so those associations (and the validity state) are wired automatically. Ships structural parts (fieldset, legend, group, content, separator) for composing and grouping fields. Ported from the legacy shadcn-uikit `field`.
 - [Form](./llms/form.md): A native form element with consolidated validation, built on Base UI's Form. It collects values by each Field's name, runs the Fields' validation on submit (or per validationMode), surfaces server errors keyed by field name, and calls onFormSubmit with the values when every field is valid. Ported from the legacy shadcn-uikit `form` (which wrapped react-hook-form); this version drops that dependency and composes the ui-react Field directly.
 - [InputDatePicker](./llms/input-date-picker.md): The date-field trigger: a button box that displays a formatted date (or a start–end range when `pickerType="dateRange"`) and a trailing calendar icon, with an optional label (and required marker) and an optional description or error message. Opens a consumer-owned calendar. Themed by the `--ui-input-date-picker-*` token tier.
+- [InputNumPicker](./llms/input-num-picker.md): A numeric stepper field: an optional label (with an optional required marker), and a bordered box with decrement/increment buttons around the numeric value. Built on Base UI's NumberField and its own `--ui-input-num-picker-*` token tier; the steppers reuse `ButtonIconInput`.
 - [InputOTP](./llms/input-otp.md): A bare row of single-character boxes for entering a one-time code. No label/description — like `Input`, field furniture is a future `Field` wrapper. Typing a digit advances focus to the next slot; Backspace on an empty slot clears and moves back; pasting a full code distributes it across the slots.
 - [InputPassword](./llms/input-password.md): A single-line password field: an optional label (with an optional required marker), the value box with a built-in show/hide toggle, and an optional description or error message. Its own `--ui-input-password-*` token tier covers the box down to fill/border (unlike `InputText`, it doesn't build on the bare `Input` primitive).
 - [InputSearch](./llms/input-search.md): A full search field: an optional label (with an optional required marker) above the search box. Builds on the bare `Search` box (leading magnifier, input, and clear button) and the `--ui-input-search-*` token tier.

package/dist/node_modules/.pnpm/@date-fns_tz@1.5.0/node_modules/@date-fns/tz/date/index.js

@@ -1,62 +1,59 @@
-import { tzName as o } from "../tzName/index.js";
-import { TZDateMini as s } from "./mini.js";
-class i extends s {
-  //#region static
-  static tz(e, ...t) {
-    return t.length ? new i(...t, e) : new i(Date.now(), e);
-  }
-  //#endregion
-  //#region representation
-  toISOString() {
-    const [e, t, n] = this.tzComponents(), r = `${e}${t}:${n}`;
-    return this.internal.toISOString().slice(0, -1) + r;
-  }
-  toString() {
-    return `${this.toDateString()} ${this.toTimeString()}`;
-  }
-  toDateString() {
-    const [e, t, n, r] = this.internal.toUTCString().split(" ");
-    return `${e == null ? void 0 : e.slice(0, -1)} ${n} ${t} ${r}`;
-  }
-  toTimeString() {
-    const e = this.internal.toUTCString().split(" ")[4], [t, n, r] = this.tzComponents();
-    return `${e} GMT${t}${n}${r} (${o(this.timeZone, this)})`;
-  }
-  toLocaleString(e, t) {
-    return Date.prototype.toLocaleString.call(this, e, {
-      ...t,
-      timeZone: (t == null ? void 0 : t.timeZone) || this.timeZone
-    });
-  }
-  toLocaleDateString(e, t) {
-    return Date.prototype.toLocaleDateString.call(this, e, {
-      ...t,
-      timeZone: (t == null ? void 0 : t.timeZone) || this.timeZone
-    });
-  }
-  toLocaleTimeString(e, t) {
-    return Date.prototype.toLocaleTimeString.call(this, e, {
-      ...t,
-      timeZone: (t == null ? void 0 : t.timeZone) || this.timeZone
-    });
-  }
-  //#endregion
-  //#region private
-  tzComponents() {
-    const e = this.getTimezoneOffset(), t = e > 0 ? "-" : "+", n = String(Math.floor(Math.abs(e) / 60)).padStart(2, "0"), r = String(Math.abs(e) % 60).padStart(2, "0");
-    return [t, n, r];
-  }
-  //#endregion
-  withTimeZone(e) {
-    return new i(+this, e);
-  }
-  //#region date-fns integration
-  [Symbol.for("constructDateFrom")](e) {
-    return new i(+new Date(e), this.timeZone);
-  }
-  //#endregion
-}
-export {
-  i as TZDate
+import { tzName as e } from "../tzName/index.js";
+import { TZDateMini as t } from "./mini.js";
+//#region ../../node_modules/.pnpm/@date-fns+tz@1.5.0/node_modules/@date-fns/tz/date/index.js
+var n = class n extends t {
+	static tz(e, ...t) {
+		return t.length ? new n(...t, e) : new n(Date.now(), e);
+	}
+	toISOString() {
+		let [e, t, n] = this.tzComponents(), r = `${e}${t}:${n}`;
+		return this.internal.toISOString().slice(0, -1) + r;
+	}
+	toString() {
+		return `${this.toDateString()} ${this.toTimeString()}`;
+	}
+	toDateString() {
+		let [e, t, n, r] = this.internal.toUTCString().split(" ");
+		return `${e?.slice(0, -1)} ${n} ${t} ${r}`;
+	}
+	toTimeString() {
+		let t = this.internal.toUTCString().split(" ")[4], [n, r, i] = this.tzComponents();
+		return `${t} GMT${n}${r}${i} (${e(this.timeZone, this)})`;
+	}
+	toLocaleString(e, t) {
+		return Date.prototype.toLocaleString.call(this, e, {
+			...t,
+			timeZone: t?.timeZone || this.timeZone
+		});
+	}
+	toLocaleDateString(e, t) {
+		return Date.prototype.toLocaleDateString.call(this, e, {
+			...t,
+			timeZone: t?.timeZone || this.timeZone
+		});
+	}
+	toLocaleTimeString(e, t) {
+		return Date.prototype.toLocaleTimeString.call(this, e, {
+			...t,
+			timeZone: t?.timeZone || this.timeZone
+		});
+	}
+	tzComponents() {
+		let e = this.getTimezoneOffset();
+		return [
+			e > 0 ? "-" : "+",
+			String(Math.floor(Math.abs(e) / 60)).padStart(2, "0"),
+			String(Math.abs(e) % 60).padStart(2, "0")
+		];
+	}
+	withTimeZone(e) {
+		return new n(+this, e);
+	}
+	[Symbol.for("constructDateFrom")](e) {
+		return new n(+new Date(e), this.timeZone);
+	}
 };
-//# sourceMappingURL=index.js.map
+//#endregion
+export { n as TZDate };
+
+//# sourceMappingURL=index.js.map

package/dist/node_modules/.pnpm/@date-fns_tz@1.5.0/node_modules/@date-fns/tz/date/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../../../../../../../../node_modules/.pnpm/@date-fns+tz@1.5.0/node_modules/@date-fns/tz/date/index.js"],"sourcesContent":["import { tzName } from \"../tzName/index.js\";\nimport { TZDateMini } from \"./mini.js\";\nexport class TZDate extends TZDateMini {\n  //#region static\n\n  static tz(tz, ...args) {\n    return args.length ? new TZDate(...args, tz) : new TZDate(Date.now(), tz);\n  }\n\n  //#endregion\n\n  //#region representation\n\n  toISOString() {\n    const [sign, hours, minutes] = this.tzComponents();\n    const tz = `${sign}${hours}:${minutes}`;\n    return this.internal.toISOString().slice(0, -1) + tz;\n  }\n  toString() {\n    // \"Tue Aug 13 2024 07:50:19 GMT+0800 (Singapore Standard Time)\";\n    return `${this.toDateString()} ${this.toTimeString()}`;\n  }\n  toDateString() {\n    // toUTCString returns RFC 7231 (\"Mon, 12 Aug 2024 23:36:08 GMT\")\n    const [day, date, month, year] = this.internal.toUTCString().split(\" \");\n    // \"Tue Aug 13 2024\"\n    return `${day?.slice(0, -1) /* Remove \",\" */} ${month} ${date} ${year}`;\n  }\n  toTimeString() {\n    // toUTCString returns RFC 7231 (\"Mon, 12 Aug 2024 23:36:08 GMT\")\n    const time = this.internal.toUTCString().split(\" \")[4];\n    const [sign, hours, minutes] = this.tzComponents();\n    // \"07:42:23 GMT+0800 (Singapore Standard Time)\"\n    return `${time} GMT${sign}${hours}${minutes} (${tzName(this.timeZone, this)})`;\n  }\n  toLocaleString(locales, options) {\n    return Date.prototype.toLocaleString.call(this, locales, {\n      ...options,\n      timeZone: options?.timeZone || this.timeZone\n    });\n  }\n  toLocaleDateString(locales, options) {\n    return Date.prototype.toLocaleDateString.call(this, locales, {\n      ...options,\n      timeZone: options?.timeZone || this.timeZone\n    });\n  }\n  toLocaleTimeString(locales, options) {\n    return Date.prototype.toLocaleTimeString.call(this, locales, {\n      ...options,\n      timeZone: options?.timeZone || this.timeZone\n    });\n  }\n\n  //#endregion\n\n  //#region private\n\n  tzComponents() {\n    const offset = this.getTimezoneOffset();\n    const sign = offset > 0 ? \"-\" : \"+\";\n    const hours = String(Math.floor(Math.abs(offset) / 60)).padStart(2, \"0\");\n    const minutes = String(Math.abs(offset) % 60).padStart(2, \"0\");\n    return [sign, hours, minutes];\n  }\n\n  //#endregion\n\n  withTimeZone(timeZone) {\n    return new TZDate(+this, timeZone);\n  }\n\n  //#region date-fns integration\n\n  [Symbol.for(\"constructDateFrom\")](date) {\n    return new TZDate(+new Date(date), this.timeZone);\n  }\n\n  //#endregion\n}"],"names":["TZDate","TZDateMini","tz","args","sign","hours","minutes","day","date","month","year","time","tzName","locales","options","offset","timeZone"],"mappings":";;AAEO,MAAMA,UAAeC,EAAW;AAAA;AAAA,EAGrC,OAAO,GAAGC,MAAOC,GAAM;AACrB,WAAOA,EAAK,SAAS,IAAIH,EAAO,GAAGG,GAAMD,CAAE,IAAI,IAAIF,EAAO,KAAK,IAAG,GAAIE,CAAE;AAAA,EAC1E;AAAA;AAAA;AAAA,EAMA,cAAc;AACZ,UAAM,CAACE,GAAMC,GAAOC,CAAO,IAAI,KAAK,aAAY,GAC1CJ,IAAK,GAAGE,CAAI,GAAGC,CAAK,IAAIC,CAAO;AACrC,WAAO,KAAK,SAAS,YAAW,EAAG,MAAM,GAAG,EAAE,IAAIJ;AAAA,EACpD;AAAA,EACA,WAAW;AAET,WAAO,GAAG,KAAK,aAAY,CAAE,IAAI,KAAK,aAAY,CAAE;AAAA,EACtD;AAAA,EACA,eAAe;AAEb,UAAM,CAACK,GAAKC,GAAMC,GAAOC,CAAI,IAAI,KAAK,SAAS,cAAc,MAAM,GAAG;AAEtE,WAAO,GAAGH,KAAA,gBAAAA,EAAK,MAAM,GAAG,GAAG,IAAqBE,CAAK,IAAID,CAAI,IAAIE,CAAI;AAAA,EACvE;AAAA,EACA,eAAe;AAEb,UAAMC,IAAO,KAAK,SAAS,YAAW,EAAG,MAAM,GAAG,EAAE,CAAC,GAC/C,CAACP,GAAMC,GAAOC,CAAO,IAAI,KAAK,aAAY;AAEhD,WAAO,GAAGK,CAAI,OAAOP,CAAI,GAAGC,CAAK,GAAGC,CAAO,KAAKM,EAAO,KAAK,UAAU,IAAI,CAAC;AAAA,EAC7E;AAAA,EACA,eAAeC,GAASC,GAAS;AAC/B,WAAO,KAAK,UAAU,eAAe,KAAK,MAAMD,GAAS;AAAA,MACvD,GAAGC;AAAA,MACH,WAAUA,KAAA,gBAAAA,EAAS,aAAY,KAAK;AAAA,IAC1C,CAAK;AAAA,EACH;AAAA,EACA,mBAAmBD,GAASC,GAAS;AACnC,WAAO,KAAK,UAAU,mBAAmB,KAAK,MAAMD,GAAS;AAAA,MAC3D,GAAGC;AAAA,MACH,WAAUA,KAAA,gBAAAA,EAAS,aAAY,KAAK;AAAA,IAC1C,CAAK;AAAA,EACH;AAAA,EACA,mBAAmBD,GAASC,GAAS;AACnC,WAAO,KAAK,UAAU,mBAAmB,KAAK,MAAMD,GAAS;AAAA,MAC3D,GAAGC;AAAA,MACH,WAAUA,KAAA,gBAAAA,EAAS,aAAY,KAAK;AAAA,IAC1C,CAAK;AAAA,EACH;AAAA;AAAA;AAAA,EAMA,eAAe;AACb,UAAMC,IAAS,KAAK,kBAAiB,GAC/BX,IAAOW,IAAS,IAAI,MAAM,KAC1BV,IAAQ,OAAO,KAAK,MAAM,KAAK,IAAIU,CAAM,IAAI,EAAE,CAAC,EAAE,SAAS,GAAG,GAAG,GACjET,IAAU,OAAO,KAAK,IAAIS,CAAM,IAAI,EAAE,EAAE,SAAS,GAAG,GAAG;AAC7D,WAAO,CAACX,GAAMC,GAAOC,CAAO;AAAA,EAC9B;AAAA;AAAA,EAIA,aAAaU,GAAU;AACrB,WAAO,IAAIhB,EAAO,CAAC,MAAMgB,CAAQ;AAAA,EACnC;AAAA;AAAA,EAIA,CAAC,OAAO,IAAI,mBAAmB,CAAC,EAAER,GAAM;AACtC,WAAO,IAAIR,EAAO,CAAC,IAAI,KAAKQ,CAAI,GAAG,KAAK,QAAQ;AAAA,EAClD;AAAA;AAGF;","x_google_ignoreList":[0]}
+{"version":3,"file":"index.js","names":[],"sources":["../../../../../../../../../../node_modules/.pnpm/@date-fns+tz@1.5.0/node_modules/@date-fns/tz/date/index.js"],"sourcesContent":["import { tzName } from \"../tzName/index.js\";\nimport { TZDateMini } from \"./mini.js\";\nexport class TZDate extends TZDateMini {\n  //#region static\n\n  static tz(tz, ...args) {\n    return args.length ? new TZDate(...args, tz) : new TZDate(Date.now(), tz);\n  }\n\n  //#endregion\n\n  //#region representation\n\n  toISOString() {\n    const [sign, hours, minutes] = this.tzComponents();\n    const tz = `${sign}${hours}:${minutes}`;\n    return this.internal.toISOString().slice(0, -1) + tz;\n  }\n  toString() {\n    // \"Tue Aug 13 2024 07:50:19 GMT+0800 (Singapore Standard Time)\";\n    return `${this.toDateString()} ${this.toTimeString()}`;\n  }\n  toDateString() {\n    // toUTCString returns RFC 7231 (\"Mon, 12 Aug 2024 23:36:08 GMT\")\n    const [day, date, month, year] = this.internal.toUTCString().split(\" \");\n    // \"Tue Aug 13 2024\"\n    return `${day?.slice(0, -1) /* Remove \",\" */} ${month} ${date} ${year}`;\n  }\n  toTimeString() {\n    // toUTCString returns RFC 7231 (\"Mon, 12 Aug 2024 23:36:08 GMT\")\n    const time = this.internal.toUTCString().split(\" \")[4];\n    const [sign, hours, minutes] = this.tzComponents();\n    // \"07:42:23 GMT+0800 (Singapore Standard Time)\"\n    return `${time} GMT${sign}${hours}${minutes} (${tzName(this.timeZone, this)})`;\n  }\n  toLocaleString(locales, options) {\n    return Date.prototype.toLocaleString.call(this, locales, {\n      ...options,\n      timeZone: options?.timeZone || this.timeZone\n    });\n  }\n  toLocaleDateString(locales, options) {\n    return Date.prototype.toLocaleDateString.call(this, locales, {\n      ...options,\n      timeZone: options?.timeZone || this.timeZone\n    });\n  }\n  toLocaleTimeString(locales, options) {\n    return Date.prototype.toLocaleTimeString.call(this, locales, {\n      ...options,\n      timeZone: options?.timeZone || this.timeZone\n    });\n  }\n\n  //#endregion\n\n  //#region private\n\n  tzComponents() {\n    const offset = this.getTimezoneOffset();\n    const sign = offset > 0 ? \"-\" : \"+\";\n    const hours = String(Math.floor(Math.abs(offset) / 60)).padStart(2, \"0\");\n    const minutes = String(Math.abs(offset) % 60).padStart(2, \"0\");\n    return [sign, hours, minutes];\n  }\n\n  //#endregion\n\n  withTimeZone(timeZone) {\n    return new TZDate(+this, timeZone);\n  }\n\n  //#region date-fns integration\n\n  [Symbol.for(\"constructDateFrom\")](date) {\n    return new TZDate(+new Date(date), this.timeZone);\n  }\n\n  //#endregion\n}"],"x_google_ignoreList":[0],"mappings":";;;AAEA,IAAa,IAAb,MAAa,UAAe,EAAW;CAGrC,OAAO,GAAG,GAAI,GAAG,GAAM;EACrB,OAAO,EAAK,SAAS,IAAI,EAAO,GAAG,GAAM,CAAE,IAAI,IAAI,EAAO,KAAK,IAAI,GAAG,CAAE;CAC1E;CAMA,cAAc;EACZ,IAAM,CAAC,GAAM,GAAO,KAAW,KAAK,aAAa,GAC3C,IAAK,GAAG,IAAO,EAAM,GAAG;EAC9B,OAAO,KAAK,SAAS,YAAY,CAAC,CAAC,MAAM,GAAG,EAAE,IAAI;CACpD;CACA,WAAW;EAET,OAAO,GAAG,KAAK,aAAa,EAAE,GAAG,KAAK,aAAa;CACrD;CACA,eAAe;EAEb,IAAM,CAAC,GAAK,GAAM,GAAO,KAAQ,KAAK,SAAS,YAAY,CAAC,CAAC,MAAM,GAAG;EAEtE,OAAO,GAAG,GAAK,MAAM,GAAG,EAAE,EAAmB,GAAG,EAAM,GAAG,EAAK,GAAG;CACnE;CACA,eAAe;EAEb,IAAM,IAAO,KAAK,SAAS,YAAY,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAC9C,CAAC,GAAM,GAAO,KAAW,KAAK,aAAa;EAEjD,OAAO,GAAG,EAAK,MAAM,IAAO,IAAQ,EAAQ,IAAI,EAAO,KAAK,UAAU,IAAI,EAAE;CAC9E;CACA,eAAe,GAAS,GAAS;EAC/B,OAAO,KAAK,UAAU,eAAe,KAAK,MAAM,GAAS;GACvD,GAAG;GACH,UAAU,GAAS,YAAY,KAAK;EACtC,CAAC;CACH;CACA,mBAAmB,GAAS,GAAS;EACnC,OAAO,KAAK,UAAU,mBAAmB,KAAK,MAAM,GAAS;GAC3D,GAAG;GACH,UAAU,GAAS,YAAY,KAAK;EACtC,CAAC;CACH;CACA,mBAAmB,GAAS,GAAS;EACnC,OAAO,KAAK,UAAU,mBAAmB,KAAK,MAAM,GAAS;GAC3D,GAAG;GACH,UAAU,GAAS,YAAY,KAAK;EACtC,CAAC;CACH;CAMA,eAAe;EACb,IAAM,IAAS,KAAK,kBAAkB;EAItC,OAAO;GAHM,IAAS,IAAI,MAAM;GAClB,OAAO,KAAK,MAAM,KAAK,IAAI,CAAM,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,GAElD;GADF,OAAO,KAAK,IAAI,CAAM,IAAI,EAAE,CAAC,CAAC,SAAS,GAAG,GAC/B;EAAC;CAC9B;CAIA,aAAa,GAAU;EACrB,OAAO,IAAI,EAAO,CAAC,MAAM,CAAQ;CACnC;CAIA,CAAC,OAAO,IAAI,mBAAmB,GAAG,GAAM;EACtC,OAAO,IAAI,EAAO,CAAC,IAAI,KAAK,CAAI,GAAG,KAAK,QAAQ;CAClD;AAGF"}