@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-textfield/README.md

@@ -1,106 +1,213 @@
 # rel-textfield
 
-## Overview
-
-A text input field component with support for labels, icons, validation states, and supporting text. Used for single-line text entry in forms and user interfaces.
+`<rel-textfield>` is the single-line and multi-line text input from the Figma "Text Field" component: a labelled control with three chromes (`default` outlined, `underline`, `legend` notched outline), three heights (32 / 40 / 48px), prefix and suffix blocks (icon, short text or slotted content), error / helper text and full-width or inline layout. Use it for free-text entry — names, emails, passwords, numbers, notes (`multiline`). For picking from a fixed list use `rel-select`; for type-ahead against a list use `rel-autocomplete`; for dates and times use the picker components, which reuse this field's chrome.
 
 ## Usage
 
 ```html
-<!-- Basic usage -->
-<rel-textfield label="Email" placeholder="Enter your email"></rel-textfield>
+<!-- Basic field -->
+<rel-textfield label="Email" placeholder="you@example.com" type="email"></rel-textfield>
+
+<!-- Sizes and chromes -->
+<rel-textfield label="Small" size="small"></rel-textfield>
+<rel-textfield label="Large" size="large"></rel-textfield>
+<rel-textfield label="Underline" variant="underline"></rel-textfield>
+<rel-textfield label="Legend" variant="legend"></rel-textfield>
+
+<!-- Label styles -->
+<rel-textfield label="Floating label" label-style="floating"></rel-textfield>
+<rel-textfield label-style="none" placeholder="Search orders" field-aria-label="Search orders"></rel-textfield>
+
+<!-- Leading icon, helper text, required -->
+<rel-textfield label="Search" prefixicon="search" helpertext="Type at least 3 characters" required></rel-textfield>
+
+<!-- Prefix / suffix text (Figma .Preffix / .Suffix) -->
+<rel-textfield label="Website" prefix-text="https://" prefix-style="fill"></rel-textfield>
+<rel-textfield label="Weight" suffix-text="kg" suffix-divider></rel-textfield>
+
+<!-- Slotted prefix / suffix content -->
+<rel-textfield label="Amount">
+  <span slot="prefix">$</span>
+  <rel-button slot="suffix" variant="ghost" size="small">Max</rel-button>
+</rel-textfield>
 
-<!-- With icons and supporting text -->
+<!-- Clickable trailing icon (e.g. password toggle) -->
 <rel-textfield
+  id="pw"
   label="Password"
   type="password"
-  leftIcon="🔒"
-  supportingText="Must be at least 8 characters">
+  righticon="eye"
+  clickable-right-icon
+  right-icon-aria-label="Show password">
 </rel-textfield>
+<script>
+  const pw = document.getElementById("pw");
+  pw.addEventListener("rel-right-icon-click", () => {
+    pw.type = pw.type === "password" ? "text" : "password";
+  });
+  pw.addEventListener("rel-change", (e) => console.log("typed:", e.detail));
+</script>
 
-<!-- No label — an accessible name is required in its place -->
-<rel-textfield
-  label-style="none"
-  placeholder="Search orders"
-  field-aria-label="Search orders">
-</rel-textfield>
+<!-- Error state -->
+<rel-textfield label="Username" value="a" error errormessage="Must be at least 3 characters"></rel-textfield>
+
+<!-- Multiline (textarea) -->
+<rel-textfield label="Notes" multiline rows="5" maxlength="500"></rel-textfield>
 
-<!-- Setting value via JavaScript -->
-<rel-textfield id="myField" label="Username"></rel-textfield>
+<!-- Read-only, disabled, inline width -->
+<rel-textfield label="Order ID" value="SO-4821" readonly></rel-textfield>
+<rel-textfield label="Disabled" disabled></rel-textfield>
+<rel-textfield id="qty" label="Quantity" type="number"></rel-textfield>
 <script>
-  const field = document.getElementById('myField');
-  field.value = 'john.doe';
+  // fullWidth defaults to true; a boolean attribute cannot express false, so unset it via the property
+  document.getElementById("qty").fullWidth = false;
 </script>
 ```
 
+### Deprecated aliases
+
+```html
+<!-- floatingLabel → label-style="floating" (kept permanently as an alias; no console notice) -->
+<rel-textfield label="Old spelling" floatinglabel></rel-textfield>
+<rel-textfield label="Canonical" label-style="floating"></rel-textfield>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-textfield.ts — do not edit; run readme-generate.mjs -->
+
 ## API
 
-### Attributes/Properties
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | - | Label text displayed above the input |
-| `label-style` | `"default" \| "floating" \| "none"` | - | Label presentation. `"none"` renders no label at all. Unset, the deprecated `floatingLabel` boolean decides |
-| `floatingLabel` | `boolean` | `false` | **Deprecated** — use `label-style="floating"`. Kept permanently as an alias |
-| `field-aria-label` | `string` | - | Accessible name for the input. Required with `label-style="none"` |
-| `field-aria-labelledby` | `string` | - | IDREF list of external element(s) naming the input. Wins over `field-aria-label` |
-| `placeholder` | `string` | `""` | Placeholder text |
-| `type` | `string` | `"text"` | Input type (text, email, password, etc.) |
-| `value` | `string` | `""` | Current input value |
-| `leftIcon` | `string` | - | Icon content on the left side |
-| `rightIcon` | `string` | - | Icon content on the right side |
-| `supportingText` | `string` | - | Helper or error text below input |
-| `state` | `"default" \| "focused" \| "error" \| "disabled"` | `"default"` | Visual state |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Size variant |
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `undefined` | Visible label text. Rendered above the control (default), inside it as a floating label (`labelStyle="floating"`) or as the notch of the `legend` variant; omitted entirely under `labelStyle="none"`. |
+| `placeholder` | `placeholder` | `string` | `""` | Placeholder shown while the field is empty. Under the floating label style it stays hidden until the field is focused. |
+| `type` | `type` | `string` | `"text"` | Native input `type` (`text`, `email`, `password`, `number`, …). Ignored when `multiline` is set. |
+| `value` | `value` | `string` | `""` | Current text. Updated on every keystroke; set it to control the field programmatically. |
+| `leftIcon` | `lefticon` | `string` | `undefined` | Legacy name for the leading icon (a `rel-icon` name). `prefixIcon` wins when both are set. |
+| `rightIcon` | `righticon` | `string` | `undefined` | Trailing `rel-icon` name rendered in the suffix block. Decorative unless `clickableRightIcon` is set. |
+| `clickableRightIcon` | `clickable-right-icon` | `boolean` | `false` | Makes the trailing icon interactive (pointer + focusable) and emits `rel-right-icon-click` — e.g. a password show/hide toggle or clear button. |
+| `rightIconAriaLabel` | `right-icon-aria-label` | `string` | `undefined` | Accessible label for the trailing icon when it is clickable. |
+| `prefixText` | `prefix-text` | `string` | `undefined` | Short text rendered before the input, e.g. `"http://"` or `"$"`. Sits in the same prefix block as `prefixIcon` and is styled by `prefixStyle`. |
+| `prefixStyle` | `prefix-style` | `"clear" \| "divider" \| "fill"` | `"clear"` | Visual treatment of the prefix block — applies to the prefix icon, text and slotted `prefix` content alike. See `TextFieldPrefixStyle`. |
+| `suffixText` | `suffix-text` | `string` | `undefined` | Short text rendered after the input, e.g. `"kg"` or `".00"`. Shares the suffix block with `rightIcon` and slotted `suffix` content. |
+| `suffixDivider` | `suffix-divider` | `boolean` | `false` | Draws a hairline between the input and the suffix block. |
+| `supportingText` | `supportingtext` | `string` | `undefined` | Legacy name for the helper line below the control. `helperText` wins when both are set. |
+| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Legacy visual state. `"error"` / `"disabled"` behave like the `error` / `disabled` booleans, which are preferred and take precedence. Typing into a `state="error"` field resets it to `"default"` until the value is emptied again. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control height — `small` 32px, `medium` 40px, `large` 48px — which also scales the text and the affix icons. |
+| `labelStyle` | `label-style` | `"default" \| "floating" \| "none"` | `undefined` | Label presentation. Left `undefined` the deprecated `floatingLabel` boolean decides, so existing markup keeps working; set explicitly and it wins. Declares `attribute` because Lit would otherwise only listen for the all-lowercase `labelstyle`. Reflected. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the input. Required when `labelStyle="none"`, since no `<label>` renders and a placeholder is not a valid naming mechanism. |
+| `fieldAriaLabelledby` | `field-aria-labelledby` | `string` | `undefined` | IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. |
+| `variant` | `variant` | `"default" \| "underline" \| "legend"` | `"default"` | Field chrome: `default` outlined box, `underline` bottom border only, `legend` notched outline with the label sitting in the top border (native fieldset/legend). Reflected. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the input (not focusable, not editable) and dims the control. |
+| `required` | `required` | `boolean` | `false` | Marks the input required: sets native `required` / `aria-required` and appends an asterisk to the label. |
+| `multiline` | `multiline` | `boolean` | `false` | Renders a textarea instead of a single-line input (see `rows`). Prefix/suffix blocks and `type` are ignored in this mode. Reflected. |
+| `rows` | `rows` | `number` | `3` | Visible text rows of the textarea when `multiline` is set. |
+| `prefixIcon` | `prefixicon` | `string` | `undefined` | Leading `rel-icon` name rendered in the prefix block (preferred over the legacy `leftIcon`). |
+| `prefixIconAriaLabel` | `prefixiconarialabel` | `string` | `undefined` | Accessible label for the leading icon. Without it the icon is `aria-hidden` (decorative). |
+| `error` | `error` | `boolean` | `false` | Puts the field in the error state: danger border, `aria-invalid`, and `errorMessage` replacing the helper text. |
+| `errorMessage` | `errormessage` | `string` | `undefined` | Text shown below the control instead of `helperText` while the field is in the error state. |
+| `helperText` | `helpertext` | `string` | `undefined` | Helper line below the control (preferred over the legacy `supportingText`); linked to the input via `aria-describedby`. |
+| `helperIcon` | `helper-icon` | `string` | `undefined` | Icon name from the generated icon dictionary, rendered before the helper line (Figma "Supporting Icon"). Sized 16px, or 14px at `size="small"`, and it takes the helper's colour — so it turns `--rel-text-danger` in the error state. Decorative: it is hidden from screen readers, since the helper text it sits beside is already announced. |
+| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only: focusable and selectable but not editable. |
+| `maxLength` | `maxlength` | `number` | `undefined` | Maximum number of characters (native `maxlength`). |
+| `name` | `name` | `string` | `undefined` | Form field name forwarded to the native input, for form submission and autofill. |
+| `fullWidth` | `fullwidth` | `boolean` | `true` | Fills the parent width as a block element (default). Unset it to render inline at the content's natural width. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `floatingLabel` | `floatinglabel` | `boolean` | Use `labelStyle="floating"`. Kept permanently as an alias. |
+
+### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `focus` | `focus(options?: FocusOptions)` | Focuses the inner input/textarea (the host itself is not focusable). |
 
 ## Events
 
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `input-change` | `string` (the current value) | Fires when the input value changes through user interaction |
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `value` | bubbles / composed | Fired on every keystroke. Detail: the current text (`value`). |
+| `rel-right-icon-click` | — | bubbles / composed | Fired when the trailing icon is clicked or activated with Enter / Space while `clickableRightIcon` is set. No detail. |
 
 ## Slots
 
-Default slot not used. All content controlled via properties.
+| Slot | Description |
+| --- | --- |
+| `prefix` | Custom content at the far left of the control (e.g. a unit dropdown); shares the prefix block with `prefixIcon` / `prefixText`. Hidden when `multiline` is set. |
+| `suffix` | Custom content at the far right of the control (e.g. an action button); shares the suffix block with `rightIcon` / `suffixText`. Hidden when `multiline` is set. |
 
 ## CSS Parts
 
-None exposed.
+| Part | Description |
+| --- | --- |
+| `label` | The visible label element (default and floating label styles) |
+| `input` | The native input / textarea |
+| `right-icon` | The trailing `rel-icon` |
+| `prefix` | The prefix block (leading icon, prefix text and the `prefix` slot) |
+| `suffix` | The suffix block (suffix text, trailing icon and the `suffix` slot) |
+| `helper` | The helper / error text line below the control |
+| `helper-icon` | The leading `rel-icon` in the helper line; rendered only when `helper-icon` is set and there is helper text |
+| `control` | The bordered control box (the fieldset in the legend variant) |
 
 ## Tokens / CSS Variables
 
-- `--rel-fonts-font-family`: Font family
-- `--rel-body-sm-regular-font-size`, `--rel-body-md-regular-font-size`: Font sizes
-- `--rel-fonts-weight-body-medium`: Font weight for label
-- `--rel-text-label`: Label color
-- `--rel-text-default`: Input text color
-- `--rel-text-placeholder`: Placeholder and icon color
-- `--rel-text-disabled`: Disabled text color
-- `--rel-border-default`: Default border color
-- `--rel-bg-info`: Focus border color
-- `--rel-border-danger`: Error state border color
-- `--rel-bg-surface`: Input background (light mode)
-- `--rel-bg-neutral-elevated-1`: Disabled background
-- `--rel-spacing-*`: Spacing tokens
-- `--rel-border-radius-sm`: Border radius
-- `--rel-field-label-reserve`: Height held for the absent label row under `label-style="none"`, so the input bottom-aligns with labelled siblings. Defaults to the label line-height plus the wrapper gap; set to `0` to collapse the row entirely in compact contexts (toolbars, table cells)
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-field-label-reserve` | `calc(var(--rel-body-md-regular-line-height) + var(--rel-spacing-2xs))` | Height held for the label row whenever no label renders above the control — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the control — so the control still lines up with labelled siblings in a form row. Defaults to that size's label line-height plus the wrapper gap (24px at `small`, 26px at `medium` and `large`). Set to `0` to collapse the row entirely (toolbars, table cells). |
+| `--rel-textfield-surface` | `var(--rel-bg-neutral)` | Colour the floating label's strip paints to mask the border behind it; defaults to the control's own fill (`--rel-bg-neutral`). Set it when the field sits on a tinted or elevated surface, otherwise the strip shows as a light dash across the border. |
+
+<!-- readme-gen:end -->
 
 ## Accessibility
 
-- Associates `<label>` with input via `for`/`id`
-- With `label-style="none"` no `<label>` renders, so `field-aria-label` (or
-  `field-aria-labelledby`) must supply the accessible name — a placeholder is
-  not a valid naming mechanism. The component logs a console warning when both
-  are missing.
-- Supports native HTML5 input attributes (`required`, `disabled`, `readonly`, `maxlength`)
-- Focus ring visible on keyboard navigation (`:focus-visible`)
-- Error state communicated visually via border color
-- Supporting text can provide `aria-describedby` context
+- The visible `<label>` is linked to the native input via `for`/`id` (the host `id`, or a generated one). In the `legend` variant the input is instead named through `aria-labelledby` pointing at the `<legend>`.
+- With `label-style="none"` no label renders: `field-aria-labelledby` (wins) or `field-aria-label` must supply the accessible name. The component logs a console warning once when neither is set, because a placeholder is not a valid naming mechanism.
+- The input carries `aria-required`, `aria-invalid` (true in the error state) and `aria-describedby` pointing at the helper line. That line is always rendered with `aria-live="polite"`, so a change from helper text to `errorMessage` is announced.
+- The leading icon is `aria-hidden` unless `prefixIconAriaLabel` is set, in which case it becomes `role="img"` with that label. The trailing icon is `aria-hidden` unless `clickable-right-icon` is set, in which case it is `role="button"`, `tabindex="0"` and named by `right-icon-aria-label`.
+- No screen-reader announcements are made via `announce()`; the live helper region is the only announcement path.
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Focus the input; with `clickable-right-icon` the trailing icon is the next Tab stop |
+| `Enter` / `Space` (on the trailing icon) | Fires `rel-right-icon-click` (default prevented) |
+
+Focus behaviour: `focus()` on the host focuses the inner input / textarea (the host itself is not focusable). A mousedown anywhere on the control — border, legend notch, prefix / suffix padding — focuses the input like clicking a label would; presses on the input, a clickable icon or slotted content keep their native behaviour. The focused control shows a `--rel-border-strong` border plus a 1px ring; the `legend` variant recolours the border and legend only (a ring would strike through the notch).
 
 ## Notes / Edge Cases
 
-- The `state` prop overrides internal focus state if set explicitly
-- Icons are decorative (text content, not `<img>` elements)
-- Input type `password` does not auto-toggle visibility (use `rightIcon` for toggle button)
-- Error state must be set programmatically; no built-in validation
-- Disabled inputs cannot be focused or edited
+- Attribute spellings: props declared with an explicit `attribute` use kebab-case (`label-style`, `prefix-text`, `clickable-right-icon`, `field-aria-label`, …). The others have Lit's default all-lowercase attribute — `prefixicon`, `righticon`, `helpertext`, `errormessage`, `maxlength`, `fullwidth`, `supportingtext`, `floatinglabel` — see the Attribute column above. HTML attribute names are case-insensitive, so `helperText="…"` in markup also works.
+- **The same logical prop can take a _different_ spelling on `rel-autocomplete` / `rel-select`.** Those components declare an explicit kebab `attribute` where this one falls back to Lit's all-lowercase default, so `prefix-icon` works on `<rel-autocomplete>` and is silently ignored on `<rel-textfield>`. There is no error when this happens — an attribute a component does not observe is inert, so the icon simply never appears. The pairs that differ today:
+
+  | Prop | `rel-textfield` | `rel-autocomplete` / `rel-select` |
+  | --- | --- | --- |
+  | `prefixIcon` | `prefixicon` | `prefix-icon` (autocomplete) |
+  | `helperText` | `helpertext` | `helper-text` (autocomplete) |
+  | `errorMessage` | `errormessage` | `error-message` (autocomplete) |
+  | `floatingLabel` | `floatinglabel` | `floating-label` (autocomplete) |
+  | `fullWidth` | `fullwidth` | `full-width` (autocomplete) |
+  | `leftIcon` | `lefticon` | `left-icon` (select) |
+  | `rightIcon` | `righticon` | `right-icon` (select) |
+  | `supportingText` | `supportingtext` | `supporting-text` (select) |
+
+  All three agree on `label-style`, `field-aria-label` and `field-aria-labelledby`. This is an inconsistency, not a design decision: the kebab spellings are the intended direction, and unifying on them means retiring the lowercase ones, which only a major version can do — so it is targeted for 3.0. Until then the Attribute column above is the authority for **this** component. In a Lit template you can sidestep the whole question with a property binding (`.prefixIcon=${…}`), which is spelling-independent; that is also how `rel-autocomplete` drives the field it wraps, so its own forwarding is unaffected by the mismatch.
+- Legacy names still work but the canonical ones win when both are set: `leftIcon` → `prefixIcon`, `supportingText` → `helperText`, `state="error"` → `error`, `state="disabled"` → `disabled`. `lefticon` / `righticon` attributes are also read once at connect time.
+- `errorMessage` replaces the helper line only while the field is in the error state **and** the message is set; otherwise the helper text stays visible. There is no built-in validation — set `error` from your form layer.
+- `state="error"` (legacy) auto-clears to `"default"` as soon as the user types a non-empty value and comes back once the value is emptied again; the `error` boolean never auto-clears.
+- `multiline` renders a `<textarea>` (`rows`, vertical resize, 80px minimum height). `type`, the prefix / suffix blocks and their slots are ignored in this mode (the slots stay mounted but hidden).
+- `fullWidth` defaults to `true` and reflects as `fullwidth`; without it the host becomes `inline-block` at its content width. To turn it off from HTML you must bind the property (`.fullWidth=${false}`), since a boolean attribute cannot express `false`.
+- `label-style="floating"`: the placeholder is hidden until the field is focused; the label floats onto the border when focused or filled. Internally the deprecated `floatingLabel` boolean is kept in sync with `labelStyle` and its reflected `floatinglabel` attribute is the styling hook, so both spellings render identically. With a `prefix-style="clear"` prefix the floated label slides back over the control's left edge (Figma "Floating Label"); `divider` / `fill` prefixes keep it after the block.
+- `variant="legend"` + `label-style="none"` drops the `<legend>` entirely so the top border runs continuous; a `fill` prefix is squared off in this variant because it cannot reach the notched top border.
+- `--rel-field-label-reserve` (see Component hooks) keeps a `label-style="none"` field bottom-aligned with labelled siblings; set it to `0` in toolbars or table cells.
+- Inside the prefix block the order is slotted content → icon → text (nearest the input); in the suffix block it is text → icon → slotted content. Clicking a non-interactive part of either block focuses the input.
+- The control height (32 / 40 / 48px) is explicit so the field lines up with `rel-select` and the date / time / range picker triggers; the textarea keeps the padding model and grows with `rows`.
+- In Figma, the `error` state's border has no focus ring; that matches the code (`box-shadow: none` in error).