@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/input-text-area.md

@@ -0,0 +1,271 @@
+# InputTextArea
+
+> A full multiline text field: an optional label (with an optional required marker), a `<textarea>` box that grows with vertical resize, and an optional description or error message. For entering and editing longer free-text (notes, comments, descriptions). Themed by the `--ui-input-text-area-*` token tier.
+
+**Status:** ready · **Category:** forms · **Since:** v0.23.0
+
+## Import
+
+```tsx
+import { InputTextArea } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputTextArea
+  label="Bio"
+  placeholder="Tell us about yourself"
+  description="Shown on your profile"
+  value={bio}
+  onChange={(e) => setBio(e.target.value)}
+/>
+
+{/* Error */}
+<InputTextArea label="Comment" value={value} error="Must be at least 20 characters" onChange={onChange} />
+```
+
+A multiline text field for entering and editing longer free-text — notes,
+comments, descriptions, and other multi-line content. It grows with vertical
+resize. Pair it with a clear label and, when validation fails, an associated
+error message.
+
+## When to Use
+
+- Collect a longer, multi-line value (notes, comments, descriptions, …).
+- Any free-text where line breaks are expected.
+
+## When NOT to Use
+
+- **Single short value** (name, email, URL) — use an Input.
+- **Choosing from a fixed set** — use a select / combobox / radio group.
+- **Binary on/off** — use a checkbox or switch.
+
+## States
+
+| State    | How                      | Visual                                                              |
+| -------- | ------------------------ | ------------------------------------------------------------------- |
+| Idle     | default                  | Idle border, idle fill                                              |
+| Hover    | pointer hover            | `border-color-hover` + `box-color-hover`                            |
+| Focus    | focus                    | `border-color-focus` + 3px `--ui-focus-primary` ring                |
+| Error    | `error` / `aria-invalid` | Red `error-msg-box-border-color-*` border + `--ui-focus-error` ring |
+| Disabled | `disabled`               | Faint fill/border, muted text, not interactive                      |
+
+## Quick Examples
+
+### React
+
+```tsx
+import { InputTextArea } from '@acronis-platform/ui-react';
+
+function BioField() {
+  const [bio, setBio] = useState('');
+  return (
+    <InputTextArea
+      label="Bio"
+      description="Shown on your profile"
+      placeholder="Tell us about yourself"
+      value={bio}
+      onChange={(e) => setBio(e.target.value)}
+    />
+  );
+}
+```
+
+Error state — `error` switches the field to the error treatment (red border +
+red message replacing the description):
+
+```tsx
+<InputTextArea
+  label="Comment"
+  value={value}
+  error="Comment must be at least 20 characters."
+  onChange={onChange}
+/>
+```
+
+## Spec Files
+
+| File               | Contents                                                    |
+| ------------------ | ----------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category                                  |
+| `anatomy.yaml`     | Root element/role, pseudo + prop states                     |
+| `api.yaml`         | Framework-agnostic contract + framework adapters            |
+| `tokens.yaml`      | `--ui-input-text-area-*` + focus-ring token references      |
+| `behavior.md`      | Given/When/Then behavior scenarios                          |
+| `accessibility.md` | ARIA, keyboard map, screen-reader and contrast requirements |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `label` | `ReactNode` | — | no | Field label rendered above the textarea, associated via `htmlFor`/`id`. |
+| `required` | `boolean` | `false` | no | Appends a required marker (`*`) after the label and sets `aria-required` on the textarea. |
+| `description` | `ReactNode` | — | no | Helper text below the textarea. Hidden while `error` is set. |
+| `error` | `ReactNode` | — | no | Error message below the textarea. Its presence switches the field to the error treatment (red box border via `aria-invalid`, red message replacing the description). |
+| `placeholder` | `string` | — | no | Example/hint text shown when empty. Not a label substitute. |
+| `value` | `string` | — | no | Controlled value. Pair with the change event. |
+| `default-value` | `string` | — | no | Initial value when uncontrolled. |
+| `rows` | `number` | — | no | Initial visible number of text rows. The field can still grow taller via vertical resize; its minimum height is the `box-height-min` token. |
+| `disabled` | `boolean` | `false` | no | Disables interaction; applies the disabled form tokens. |
+| `name` | `string` | — | no | Form field name submitted with the form. |
+| `aria-invalid` | `boolean` | `false` | no | Marks the textarea invalid directly (an alternative to the `error` prop when the consumer renders its own message). Switches the border to `error-msg-box-border-color-{idle,hover}` and the focus ring to `--ui-focus-error`. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `change` | `string` | Fired as the value changes (React: native `onChange`). The new value is on `event.target.value`. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `label` | The label content. |
+| `description` | The helper text. |
+| `error` | The error message. |
+
+## Behavior
+
+### Rendering
+
+#### Renders an empty multiline field
+
+**Given** an InputTextArea with no value
+**When** it renders
+**Then** it exposes `role="textbox"` on a native `<textarea>`
+**And** the placeholder (if set) is shown in `--ui-input-text-area-placeholder-color-idle`
+**And** its height is at least `--ui-input-text-area-box-height-min`
+
+#### Grows with vertical resize
+
+**Given** a rendered InputTextArea
+**When** the user drags the resize handle down
+**Then** the field grows taller (vertical resize only)
+**And** it never shrinks below `--ui-input-text-area-box-height-min`
+
+---
+
+### Interaction
+
+#### Accepts typed input
+
+**Given** an enabled InputTextArea
+**When** the user types (including line breaks)
+**Then** the value updates
+**And** the change event fires with the new value
+
+#### Disabled blocks input
+
+**Given** an InputTextArea with `disabled`
+**When** the user attempts to type
+**Then** the value does not change
+**And** the disabled form tokens (faint fill/border, muted text) apply
+
+---
+
+### States
+
+#### Hover
+
+**Given** an enabled InputTextArea
+**When** the pointer hovers it
+**Then** the border uses `--ui-input-text-area-border-color-hover`
+**And** the fill uses `--ui-input-text-area-box-color-hover`
+
+#### Focus
+
+**Given** an InputTextArea
+**When** it receives focus
+**Then** the border uses `--ui-input-text-area-border-color-focus`
+**And** a 3px `--ui-focus-primary` ring is shown
+
+#### Error (error prop / aria-invalid)
+
+**Given** an InputTextArea with `error` set (or `aria-invalid`)
+**When** it renders
+**Then** the box border uses `--ui-input-text-area-error-msg-box-border-color-idle`
+(`-hover` on hover / focus)
+**And** on focus the ring uses `--ui-focus-error` (not the primary ring)
+**And** the `error` message replaces the description below the field, in
+`--ui-input-text-area-error-msg-error-color`
+
+#### Label, required, description
+
+**Given** a `label` (with optional `required`) and a `description`
+**When** the field renders
+**Then** the label appears above the box (associated via `htmlFor`/`id`), a `*`
+marker follows it when `required`, and the description shows below — associated
+via `aria-describedby`.
+
+---
+
+### Edge Cases
+
+#### Placeholder is not a label
+
+**Given** an InputTextArea that relies on a placeholder for its name
+**When** reviewed for accessibility
+**Then** it still needs an associated `<label>` / `aria-label` — the
+placeholder is guidance, not a label.
+
+#### Controlled vs uncontrolled
+
+**Given** an InputTextArea with `value` and a change handler
+**When** the user types
+**Then** the displayed value changes only when the consumer updates `value`
+(uncontrolled fields update themselves via `default-value`).
+
+## Accessibility
+
+## ARIA Roles and Attributes
+
+| Attribute           | Value                       | Reason                                       |
+| ------------------- | --------------------------- | -------------------------------------------- |
+| native `<textarea>` | —                           | Exposes `role="textbox"` (multiline)         |
+| `aria-invalid`      | `"true"` when invalid       | Conveys the error state to assistive tech    |
+| `aria-describedby`  | id of the error/description | Associates the message text with the field   |
+| `aria-disabled`     | implied by `disabled`       | Disabled fields are skipped in the tab order |
+
+**Always provide an accessible name** — the built-in `label` prop (preferred,
+auto-associated via `htmlFor`/`id`) or `aria-label` / `aria-labelledby` for the
+bare usage. The placeholder is **not** a label; it disappears on input and fails
+contrast as a label.
+
+## Keyboard Navigation
+
+| Key        | Action                          |
+| ---------- | ------------------------------- |
+| Tab        | Moves focus to / from the field |
+| Enter      | Inserts a line break (native)   |
+| Text keys  | Edit the value                  |
+| Home / End | Move the caret (native)         |
+
+Disabled fields are removed from the tab order.
+
+## Screen Reader Requirements
+
+1. Announced as a multiline edit/text field with its accessible name.
+2. Announces the current value (or placeholder when empty).
+3. When `aria-invalid="true"`, announces "invalid"; the message referenced by
+   `aria-describedby` is read.
+
+## Color and Contrast
+
+| Element                          | Minimum Ratio | Standard               |
+| -------------------------------- | ------------- | ---------------------- |
+| Value text vs field background   | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Placeholder text vs background   | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Border vs surrounding background | 3:1           | WCAG 1.4.11 (non-text) |
+| Focus ring                       | 3:1           | WCAG 1.4.11            |
+
+Error is not signalled by color alone — pair `aria-invalid` with a visible,
+associated error message.
+
+## Testing Checklist
+
+- [ ] Has an accessible name (label / `aria-label`)
+- [ ] `aria-invalid="true"` + `aria-describedby` wired for errors
+- [ ] Reachable via Tab; disabled removes it from the tab order
+- [ ] Value / placeholder text meet 4.5:1; border + focus ring meet 3:1
+- [ ] Placeholder is not used as the only label

package/dist/llms/input-text.md

@@ -0,0 +1,192 @@
+# InputText
+
+> A full single-line text field: an optional label (with an optional required marker), the text input box, an optional clear button, and an optional description or error message. Builds on the bare `Input` primitive and the `--ui-input-text-*` token tier.
+
+**Status:** ready · **Category:** forms · **Since:** v0.26.0
+
+## Import
+
+```tsx
+import { InputText } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputText label="Email" placeholder="you@example.com" description="We never share it" />
+
+{/* Error */}
+<InputText label="Email" value={value} error="Enter a valid email" onChange={onChange} />
+
+{/* Clearable (controlled) */}
+<InputText
+  label="Search"
+  value={value}
+  clearable
+  onChange={onChange}
+  onClear={() => setValue('')}
+/>
+```
+
+A full single-line text field: a label, the input box, an optional clear button,
+and an optional description or error message. It composes the bare
+[`Input`](../input/README.md) primitive and adds the surrounding field furniture.
+
+## When to use
+
+- Any labelled single-line text entry in a form (email, name, search term…).
+- When you need built-in label / description / error wiring and an optional clear
+  affordance.
+
+## When not to use
+
+- For a bare input with no label/description (e.g. inside a custom layout) — use
+  the `Input` primitive directly.
+- For multi-line text — use `InputTextArea`.
+- For a search field with a leading icon — use `Search`.
+
+## Examples
+
+```tsx
+import { InputText } from '@acronis-platform/ui-react';
+
+// Basic field with helper text
+<InputText
+  label="Email"
+  placeholder="you@example.com"
+  description="We never share it"
+/>;
+
+// Required
+<InputText label="Email" required />;
+
+// Error
+<InputText
+  label="Email"
+  value={value}
+  error="Enter a valid email"
+  onChange={onChange}
+/>;
+
+// Clearable (controlled)
+<InputText
+  label="Search"
+  value={value}
+  clearable
+  onChange={(e) => setValue(e.target.value)}
+  onClear={() => setValue('')}
+/>;
+```
+
+## Parts
+
+| Part          | Element    | Description                                           |
+| ------------- | ---------- | ----------------------------------------------------- |
+| `label`       | `<label>`  | Field label (associated via `htmlFor`/`id`).          |
+| `required`    | `<span>`   | Required `*` marker (decorative; `aria-hidden`).      |
+| `input`       | `<input>`  | The text box (the `Input` primitive).                 |
+| `clear`       | `<button>` | Optional clear (✕) button; calls `onClear`.           |
+| `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 input, 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 input. Hidden while `error` is set. |
+| `error` | `ReactNode` | — | no | Error message below the input. Its presence switches the field to the error treatment (red box border via `aria-invalid`, red message replacing the description). |
+| `clearable` | `boolean` | `false` | no | Show a clear (✕) button while the (controlled) field has a value. |
+| `disabled` | `boolean` | `false` | no | Disables the field (native `<input disabled>`). |
+| `value` | `string` | — | no | Controlled value. Required for the clear button to appear. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `change` | `ChangeEvent<HTMLInputElement>` | Native input change — forwarded to the underlying `<input>`. |
+| `clear` | `void` | Fired when the clear (✕) button is activated. |
+
+## 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 input and is associated with it 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 input, associated via `aria-describedby`.
+
+### Error
+
+**Given** `error` is set
+**When** the field renders
+**Then** the input shows the error border (via `aria-invalid`), the error message
+replaces the description below the input, and the message is associated via
+`aria-describedby`.
+
+### Clear
+
+**Given** `clearable` and a non-empty (controlled) `value`
+**When** the field is not disabled
+**Then** a clear (✕) button appears inside the box.
+
+**Given** the clear button
+**When** it is activated (click, Enter, or Space)
+**Then** `onClear` fires (the consumer clears the value).
+
+**Given** the field is `disabled`
+**Then** the clear button is not shown.
+
+### Interaction
+
+**Given** the input
+**When** the pointer hovers / it 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` while in the error state.
+
+**Given** any typing
+**When** the value changes
+**Then** the native `change` event is forwarded to the consumer.
+
+## 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 `aria-hidden` (the asterisk is decorative — 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.
+- **Clear button:** a native `<button>` with `aria-label="Clear"`; reachable by Tab
+  and activated by Enter / Space.
+- **Keyboard:** the input is a native text field; the clear button is a separate tab
+  stop after it.
+- **Focus visible:** keyboard focus paints a 3px ring — `--ui-focus-primary` normally
+  and `--ui-focus-error` in the error state — flush to the box; the clear button has
+  its own focus ring.
+- **Disabled:** native `disabled` removes the input (and clear 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.