@acronis-platform/ui-react 3.0.0 → 4.0.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-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.

package/dist/llms/input-password.md

@@ -0,0 +1,197 @@
+# InputPassword
+
+> 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).
+
+**Status:** ready · **Category:** forms · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { InputPassword } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputPassword label="Password" description="At least 8 characters" />
+
+{/* Error */}
+<InputPassword
+  label="Password"
+  value={value}
+  error="Too short"
+  onChange={onChange}
+/>
+```
+
+A single-line password field: a label, a themed value box with a built-in
+show/hide toggle, and an optional description or error message. Unlike
+[`InputText`](../input-text/README.md), the box isn't the bare `Input`
+primitive — it has its own `--ui-input-password-*` token tier, and the toggle
+is a [`ButtonIconInput`](../button-icon-input/README.md).
+
+## When to use
+
+- Any password / secret entry field that should let the user reveal what
+  they've typed.
+
+## When not to use
+
+- A general single-line text field — use `InputText`.
+- A one-time verification code — use `InputOTP`.
+
+## Examples
+
+```tsx
+import { InputPassword } from '@acronis-platform/ui-react';
+
+// Basic field with helper text
+<InputPassword label="Password" description="At least 8 characters" />;
+
+// Required
+<InputPassword label="Password" required />;
+
+// Error
+<InputPassword
+  label="Password"
+  value={value}
+  error="Enter at least 8 characters"
+  onChange={onChange}
+/>;
+
+// Localized toggle labels
+<InputPassword
+  label="Contraseña"
+  showPasswordLabel="Mostrar contraseña"
+  hidePasswordLabel="Ocultar contraseña"
+/>;
+```
+
+## Parts
+
+| Part          | Element    | Description                                                      |
+| ------------- | ---------- | ---------------------------------------------------------------- |
+| `label`       | `<label>`  | Field label (associated via `htmlFor`/`id`).                     |
+| `required`    | `<span>`   | Required `*` marker.                                             |
+| `box`         | `<div>`    | The themed container (border, fill) around the input + toggle.   |
+| `input`       | `<input>`  | The borderless value input; toggles `type="password" \| "text"`. |
+| `toggle`      | `<button>` | Show/hide button (`ButtonIconInput`).                            |
+| `description` | `<p>`      | Helper text (normal state).                                      |
+| `error`       | `<p>`      | Error message; replaces the description when `error`.            |
+
+## 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 `aria-required` on the input. |
+| `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 + red message + error-toned toggle). |
+| `disabled` | `boolean` | `false` | no | Disables the field and the toggle button (native `<input disabled>`). |
+| `showPasswordLabel` | `string` | `'Show password'` | no | Accessible name for the toggle button while the password is hidden. |
+| `hidePasswordLabel` | `string` | `'Hide password'` | no | Accessible name for the toggle button while the password is shown. |
+| `value` | `string` | — | no | Controlled value. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `change` | `ChangeEvent<HTMLInputElement>` | Native input change — forwarded to the underlying `<input>`. |
+
+## 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 box and is associated with the input via
+`htmlFor`/`id` (clicking the label focuses the input).
+
+**Given** `required`
+**When** the field renders
+**Then** a `*` marker is appended after the label and the input gets
+`aria-required="true"`.
+
+**Given** a `description`
+**When** no `error` is set
+**Then** the helper text shows below the box, associated via
+`aria-describedby`.
+
+### Show / hide toggle
+
+**Given** the field
+**When** it first renders
+**Then** the value is masked (`type="password"`) and the toggle shows the
+crossed-eye icon with accessible name `showPasswordLabel` ("Show password").
+
+**Given** the toggle button
+**When** it is activated
+**Then** the input's `type` flips to `"text"`, the icon becomes the plain eye,
+and the accessible name becomes `hidePasswordLabel` ("Hide password").
+Activating it again reverts both.
+
+### Error
+
+**Given** `error` is set
+**When** the field renders
+**Then** the box shows the error border, the toggle switches to its error
+tone, the error message replaces the description below the box, and the
+message is associated via `aria-describedby`. The input also gets
+`aria-invalid="true"`.
+
+### Interaction
+
+**Given** the box
+**When** the pointer hovers / the input receives keyboard focus
+**Then** the box border shifts to its hover token and keyboard focus paints a
+3px ring — `--ui-focus-primary` normally, `--ui-focus-error` in the error
+state.
+
+**Given** any typing
+**When** the value changes
+**Then** the native `change` event is forwarded to the consumer.
+
+### Disabled
+
+**Given** `disabled`
+**When** the field renders
+**Then** the input and the toggle button are both disabled (native
+`disabled`), and the box/label/description use their disabled tokens.
+
+## Accessibility
+
+- **Label association:** the `label` is a real `<label htmlFor>` tied to the
+  input's `id` (auto-generated when not supplied), so clicking it focuses the
+  input and screen readers announce the field name.
+- **Required:** `required` sets `aria-required="true"` on the input; the visual
+  `*` marker is decorative (no `aria-hidden` needed beyond styling — the
+  required semantics come from the attribute).
+- **Description / error:** whichever message is shown is linked to the input
+  via `aria-describedby`, so it is announced with the field. The error message
+  also drives `aria-invalid="true"` on the input.
+- **Toggle button:** a native `<button>` (`ButtonIconInput`) with an explicit
+  `aria-label` that tracks its state ("Show password" / "Hide password",
+  overridable via `showPasswordLabel`/`hidePasswordLabel`) and `aria-pressed`
+  reflecting whether the value is currently shown. Reachable by Tab and
+  activated by Enter / Space.
+- **Keyboard:** the input is a native text field (`type` toggles between
+  `password`/`text`); the toggle button is a separate tab stop after it.
+- **Focus visible:** keyboard focus on the input paints a 3px ring on the box —
+  `--ui-focus-primary` normally and `--ui-focus-error` in the error state; the
+  toggle button has its own focus ring (see `ButtonIconInput`).
+- **Disabled:** native `disabled` removes both the input and the toggle button
+  from the tab order; not used to convey state by color alone (the field is
+  also inert).
+- **Contrast:** label / value / placeholder / message / 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), 3.3.1 / 3.3.2 (error identification +
+  labels), 4.1.2.