@acronis-platform/ui-react 3.0.0 → 4.1.0

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

@@ -0,0 +1,203 @@
+# InputDatePicker
+
+> 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.
+
+**Status:** ready · **Category:** forms · **Since:** v0.30.0
+
+## Import
+
+```tsx
+import { InputDatePicker } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputDatePicker
+  label="Due date"
+  placeholder="Pick a date"
+  value={selected && format(selected, 'MMM d, yyyy')}
+  open={open}
+  onClick={() => setOpen(true)}
+  description="When the task is due"
+/>
+
+{/* Range */}
+<InputDatePicker
+  label="Period"
+  pickerType="dateRange"
+  startDate={start && format(start, 'MMM d')}
+  endDate={end && format(end, 'MMM d')}
+/>
+```
+
+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 a label (and optional required marker) and an optional description or error.
+Themed by the `--ui-input-date-picker-*` token tier.
+
+> **Scope:** this is the trigger field only. The calendar popup is not part of the
+> Figma design or the token tier yet — the consumer formats the date `value` / range
+> as strings and wires their own calendar to `open` / `onClick` (e.g. a popover).
+
+## When to use
+
+- A labelled date or date-range entry that opens a calendar, where you bring your own
+  calendar/popover and date formatting.
+
+## When not to use
+
+- For free text — use `InputText`; for choosing from a fixed list — use `InputSelect`.
+- If you need a built-in calendar grid — that's a separate, not-yet-designed component.
+
+## Examples
+
+```tsx
+import { InputDatePicker } from '@acronis-platform/ui-react';
+import { format } from 'date-fns';
+
+// Single date
+<InputDatePicker
+  label="Due date"
+  placeholder="Pick a date"
+  value={selected && format(selected, 'MMM d, yyyy')}
+  open={open}
+  onClick={() => setOpen(true)}
+  description="When the task is due"
+/>;
+
+// Range
+<InputDatePicker
+  label="Period"
+  pickerType="dateRange"
+  startDate={start && format(start, 'MMM d')}
+  endDate={end && format(end, 'MMM d')}
+/>;
+
+// Error
+<InputDatePicker label="Due date" error="Pick a valid date" />;
+```
+
+## Parts
+
+| Part          | Element    | Description                                               |
+| ------------- | ---------- | --------------------------------------------------------- |
+| `label`       | `<label>`  | Field label (associated via `htmlFor`/`id`).              |
+| `required`    | `<span>`   | Required `*` marker (decorative; `aria-hidden`).          |
+| `trigger`     | `<button>` | The box; opens the calendar; `aria-invalid` → error look. |
+| `value`       | `<span>`   | Selected date / range, or the placeholder.                |
+| `separator`   | `<span>`   | The `–` between range dates.                              |
+| `icon`        | `<span>`   | Trailing calendar icon.                                   |
+| `description` | `<p>`      | Helper text (normal state).                               |
+| `error`       | `<p>`      | Error message; replaces the description.                  |
+
+## 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 (`*`) and sets `aria-required` on the trigger. |
+| `description` | `ReactNode` | — | no | Helper text below the box. Hidden while `error` is set. |
+| `error` | `ReactNode` | — | no | Error message below the box. Its presence switches the field to the error treatment (red box border via `aria-invalid`, red message replacing the description). |
+| `picker-type` | `'date' | 'dateRange'` | `date` | no | Whether the field holds a single date or a start–end range. |
+| `placeholder` | `ReactNode` | — | no | Hint shown when no value is selected. |
+| `value` | `ReactNode` | — | no | Formatted selected date (`picker-type="date"`). |
+| `start-date` | `ReactNode` | — | no | Formatted range start (`picker-type="dateRange"`). |
+| `end-date` | `ReactNode` | — | no | Formatted range end (`picker-type="dateRange"`). |
+| `separator` | `ReactNode` | `–` | no | Separator rendered between the range dates. |
+| `open` | `boolean` | `false` | no | Whether the consumer-owned calendar is open — paints the active border and sets `aria-expanded`. |
+| `disabled` | `boolean` | `false` | no | Disables the trigger; applies the disabled tokens. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Fired when the trigger is activated (React: native `onClick`). Open your calendar here. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `label` | The label content. |
+| `description` | The helper text. |
+| `error` | The error message. |
+
+## Behavior
+
+### Rendering
+
+**Given** a `label`
+**When** the field renders
+**Then** the label appears above the trigger and is associated with it via
+`htmlFor`/`id`; a `*` follows it when `required` (which also sets `aria-required`).
+
+**Given** `picker-type="date"`
+**When** a `value` is set
+**Then** the trigger shows the formatted value; otherwise it shows the `placeholder`.
+
+**Given** `picker-type="dateRange"`
+**When** `start-date` / `end-date` are set
+**Then** the trigger shows `start separator end` (default separator `–`); otherwise
+the range `placeholder`.
+
+**Given** a `description` and no `error`
+**Then** the helper text shows below the box (associated via `aria-describedby`);
+**given** an `error`, it replaces the description and the box takes the error border.
+
+### Interaction
+
+**Given** the trigger
+**When** it is activated (click, Enter, or Space)
+**Then** `click` fires — the consumer opens its calendar.
+
+**Given** `open` is true (the consumer-owned calendar is shown)
+**Then** the box paints the active border, the trigger sets `aria-expanded="true"`,
+and the label / value / placeholder / separator / description / icon colors
+switch to their `-hover` token — the Figma design groups hover and the open
+(active) state under one visual treatment for these parts.
+
+**Given** the trigger
+**When** the pointer hovers
+**Then** the border shifts to its hover token and the label / value /
+placeholder / separator / description / icon colors switch to their `-hover`
+token too.
+
+**Given** the trigger
+**When** it receives keyboard focus
+**Then** the border shifts to its active token and a 3px ring is painted —
+`--ui-focus-primary` normally, `--ui-focus-error` while in the error state; the
+label / value / placeholder / separator / description / icon colors are
+**not** affected by focus alone.
+
+**Given** the field is `disabled`
+**Then** the trigger is inert (does not open) and uses the disabled token set.
+
+### Scope
+
+The calendar popup itself is **not** part of this component (not in the Figma design
+or the token tier). The consumer renders the date `value` / range as formatted
+strings and wires their own calendar to `open` / `onClick`.
+
+## Accessibility
+
+- **Trigger role:** the trigger is a native `<button>` (`role="button"`) with
+  `aria-haspopup="dialog"` — it announces that activating it opens a calendar.
+- **Label association:** the `label` is a real `<label htmlFor>` tied to the trigger's
+  `id` (auto-generated when not supplied), so clicking it focuses the trigger and
+  screen readers announce the field name.
+- **Required:** `required` sets `aria-required="true"`; the visual `*` is `aria-hidden`.
+- **Open state:** while the consumer's calendar is open, pass `open` so the trigger
+  reflects `aria-expanded="true"` (and paints the active border).
+- **Error:** set `error` (or `aria-invalid`); the message is associated via
+  `aria-describedby` and the trigger gets `aria-invalid="true"` + the error border.
+- **Keyboard:** the trigger is reachable by Tab and activated by Enter / Space; the
+  consumer's calendar owns its own focus management and Escape-to-close.
+- **Focus visible:** keyboard focus paints a 3px ring flush to the box —
+  `--ui-focus-primary` normally, `--ui-focus-error` in the error state.
+- **Disabled:** native `disabled` removes the trigger from the tab order and blocks
+  opening; state is not conveyed by color alone (the control is also inert).
+- **Value text:** the trigger displays consumer-formatted, human-readable dates (not
+  raw ISO) so the announced name is meaningful.
+- **Contrast:** label / value / placeholder / border / icon pairs come from the design
+  tokens, authored to meet WCAG contrast.
+- **WCAG:** 1.3.1, 2.1.1, 2.4.7, 1.4.3 / 1.4.11, 3.3.1 / 3.3.2, 4.1.2.

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-otp.md

@@ -0,0 +1,173 @@
+# InputOTP
+
+> 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.
+
+**Status:** ready · **Category:** forms · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { InputOTP } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputOTP length={6} onComplete={(code) => submit(code)} />
+
+{/* Error */}
+<InputOTP error defaultValue="123456" />
+```
+
+A bare row of single-character boxes for entering a one-time code (e.g. a
+6-digit SMS/authenticator code). Like [`Input`](../input/README.md), it has no
+label/description — a `Field` wrapper composes those around it.
+
+## When to use
+
+- Entering a fixed-length numeric one-time code (e.g. an SMS/authenticator
+  code), with auto-advance between digits and paste support. Input is
+  digit-only — a non-digit keystroke is rejected and non-digit characters are
+  stripped from a paste.
+
+## When not to use
+
+- A general single-line text field — use `InputText`.
+- A field that needs its own label/description/error message wired in — wrap
+  `InputOTP` the same way a future `Field` wraps `Input`.
+
+## Examples
+
+```tsx
+import { InputOTP } from '@acronis-platform/ui-react';
+
+// Basic 6-digit code, auto-focused, submits once complete
+<InputOTP autoFocus onComplete={(code) => verify(code)} />;
+
+// A shorter code
+<InputOTP length={4} />;
+
+// Error (e.g. after a failed verification)
+<InputOTP error defaultValue="123456" />;
+
+// Disabled
+<InputOTP disabled defaultValue="123456" />;
+```
+
+## Parts
+
+| Part   | Element   | Description                                                                                       |
+| ------ | --------- | ------------------------------------------------------------------------------------------------- |
+| `root` | `<div>`   | The `role="group"` row container for the slots.                                                   |
+| `slot` | `<input>` | A single-character box, repeated `length` times; shows its position as a placeholder while empty. |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `length` | `number` | `6` | no | Number of single-character slots. |
+| `value` | `string` | — | no | Controlled value (the digits entered so far, left to right). |
+| `defaultValue` | `string` | — | no | Initial value for uncontrolled usage. |
+| `disabled` | `boolean` | `false` | no | Disables every slot. |
+| `error` | `boolean` | `false` | no | Switches every slot to the error treatment. |
+| `autoFocus` | `boolean` | `false` | no | Focuses the first slot on mount. |
+| `slotAriaLabel` | `(index: number, length: number) => string` | `(index, length) => `Digit ${index} of ${length}`` | no | Builds the accessible name for a slot from its 1-based index and the total length. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `change` | `string` | Fires with the full value on every change. |
+| `complete` | `string` | Fires once, the moment the value reaches `length` characters. |
+
+## Behavior
+
+### Rendering
+
+**Given** `length` (default 6)
+**When** the field renders
+**Then** it shows that many single-character boxes in a row, each labelled
+`Digit N of length`, each showing its own 1-based position as a placeholder
+while empty.
+
+### Typing
+
+**Given** a slot with focus
+**When** a digit is entered
+**Then** the value updates, `onChange` fires with the full value, and focus
+advances to the next slot (if any).
+
+**Given** the value reaches `length` characters
+**When** the last digit is entered
+**Then** `onComplete` fires once with the full value. It does not fire again
+until the value drops below `length` and reaches it again.
+
+### Backspace / navigation
+
+**Given** an empty slot (not the first)
+**When** Backspace is pressed
+**Then** the previous slot is cleared and receives focus.
+
+**Given** any slot
+**When** ArrowLeft / ArrowRight is pressed
+**Then** focus moves to the previous / next slot (clamped at the ends).
+
+### Paste
+
+**Given** a slot with focus
+**When** text is pasted
+**Then** the code is distributed across the slots starting at the focused
+slot, extra characters beyond `length` are discarded, and focus lands on the
+last filled slot (or the last slot).
+
+### Validation
+
+**Given** a slot with focus
+**When** a non-digit character is typed
+**Then** the keystroke is rejected — the slot's value and focus are unchanged.
+
+**Given** a slot with focus
+**When** text containing non-digit characters is pasted
+**Then** only the digit characters are distributed across the slots; all
+other characters (letters, symbols, whitespace) are discarded.
+
+### Error / disabled
+
+**Given** `error`
+**When** the field renders
+**Then** every slot shows the error border and its focus ring switches to
+`--ui-focus-error`.
+
+**Given** `disabled`
+**When** the field renders
+**Then** every slot is a native disabled `<input>` (out of the tab order, no
+interaction).
+
+## Accessibility
+
+- **Grouping:** the root is `role="group"`, so assistive tech announces the
+  slots as a related set. Pass `aria-label`/`aria-labelledby` on the root (it
+  forwards arbitrary `div` props) to name the group — e.g. from an external
+  `Field` label, since InputOTP itself renders no label.
+- **Per-slot name:** each slot is a native `<input>` with its own
+  `aria-label` (default `Digit N of length`, overridable via `slotAriaLabel`).
+- **Keyboard:** digits type normally; ArrowLeft/ArrowRight move focus between
+  slots; Backspace on an empty slot moves back and clears the previous one.
+  Standard Tab/Shift+Tab also move between slots.
+- **Autofill:** each slot carries `autocomplete="one-time-code"`,
+  `inputMode="numeric"`, and `pattern="[0-9]*"` so browsers/password managers
+  can offer OTP autofill and mobile keyboards default to numeric.
+- **Numeric-only:** `inputMode`/`pattern` are keyboard hints only, not
+  enforcement — both typed and pasted input are filtered to digits in JS. A
+  non-digit keystroke is rejected outright; non-digit characters are stripped
+  from a paste.
+- **Error:** `error` sets `aria-invalid="true"` on every slot; the message
+  itself is expected to live in a wrapping `Field` (not part of this bare
+  component), same as `Input`.
+- **Focus visible:** keyboard focus paints a 3px ring on the focused slot —
+  `--ui-focus-primary` normally, `--ui-focus-error` while `error` is set.
+- **Disabled:** native `disabled` removes each slot from the tab order.
+- **Contrast:** value/placeholder/border pairs come from the design tokens,
+  authored to meet WCAG contrast.
+- **WCAG:** 1.3.1 (info/relationships), 2.1.1 (keyboard), 2.4.7 (focus
+  visible), 1.4.3 / 1.4.11 (contrast), 4.1.2.