@reliability-design/web 1.4.7 → 1.4.8

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

@@ -110,6 +110,7 @@
 | `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. |
@@ -151,6 +152,7 @@
 | `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
@@ -161,7 +163,8 @@ Set these on the host (or an ancestor) to customise the element without touching
 
 | Custom property | Default | Description |
 | --- | --- | --- |
-| `--rel-field-label-reserve` | `calc(var(--rel-body-sm-medium-line-height) + var(--rel-spacing-2xs))` | Height held for the absent label row under `labelStyle="none"` so the control bottom-aligns with labelled siblings; defaults to the label line-height plus the wrapper gap. Set to `0` to collapse the row entirely (toolbars, table cells). |
+| `--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 -->
 
@@ -183,6 +186,20 @@ Focus behaviour: `focus()` on the host focuses the inner input / textarea (the h
 ## Notes / Edge Cases
 
 - 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.

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

@@ -1,6 +1,6 @@
 # rel-toast
 
-`<rel-toast>` is the transient notification of the Reliability Design System: a dark pill fixed to the bottom centre of the viewport that shows a short message, an optional action button ("Undo", "Retry") and a dismiss button, then hides itself after `duration` milliseconds. It has two tones — `default` and `destructive` — and is driven by the `show` property (or `open()` / `close()`). Use it for brief confirmations that need no reply; use `<rel-snackbar>` when you need the status tones, a stacked layout or your own positioning, and `<rel-alert>` for messages that must stay on the page.
+`<rel-toast>` is the transient notification of the Reliability Design System: a card anchored to one of six viewport positions (bottom centre by default) that shows a short message, an optional action button ("Undo", "Retry") and a dismiss button, then hides itself after `duration` milliseconds. It has two tones — `default` and `destructive` — and is driven by the `show` property (or `open()` / `close()`). Use it for brief confirmations that need no reply; use `<rel-snackbar>` when you need the status tones, a stacked layout or your own positioning, and `<rel-alert>` for messages that must stay on the page.
 
 ## Usage
 
@@ -74,22 +74,26 @@ rel-toast { --rel-z-toast: 10000; }
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `message` | `message` | `string` | `""` | Text of the toast. It is also announced to screen readers through the shared live-region announcer each time `show` becomes true. |
-| `tone` | `tone` | `"default" \| "destructive" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone: `"default"` (dark neutral pill) \| `"destructive"` (danger fill, announced assertively). `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"` and log a one-time console notice. Takes precedence over the deprecated `type` prop. |
+| `tone` | `tone` | `"neutral" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default: neutral surface) \| `"destructive"` (danger fill, announced assertively). `"default"` is a deprecated alias of `"neutral"`; `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"`; each logs a one-time console notice. Takes precedence over the deprecated `type` prop. |
 | `actionLabel` | `actionlabel` | `string` | `undefined` | Label of the optional action button rendered between the message and the dismiss button; the button is omitted when unset. Clicking it fires `action` and then closes the toast. |
 | `duration` | `duration` | `number` | `4000` | Auto-dismiss delay in milliseconds, started each time `show` becomes true. `0` (or a negative value) disables auto-dismiss so the toast stays until `close()` or the dismiss button. Changing it while the toast is visible does not restart the running timer. |
 | `show` | `show` | `boolean` | `false` | Whether the toast is visible. Set it to true (or call `open()`) to show the toast and start the auto-dismiss timer; it is set back to false by `close()`, the dismiss button, the action button and the timer. Reflected. |
+| `dismissible` | `dismissible` | `boolean` | `true` | Shows the trailing dismiss button (Figma "Show Close Button"). Defaults to true; because it is a Lit boolean, `dismissible="false"` is still true — set the property to `false` from script to hide the button. |
+| `position` | `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-center"` | Where the toast is anchored: `bottom-center` (default, unchanged from before this prop existed), `bottom-left`, `bottom-right`, `top-left`, `top-center` or `top-right`. Top anchors also animate in from the top edge rather than upward from the bottom. Figma's Toast has axes Content / Show Button / Show Close Button / Tone and no position, so this axis is ours. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Toast scale: `small`, `medium` (default, unchanged) or `large`. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Scales the padding, the inner gap, the message type role and the close icon. Figma has no Size axis on Toast. Reflected. |
+| `maxVisible` | `max-visible` | `number` | `3` | How many toasts may be on screen at once AT THIS POSITION. Further ones wait their turn rather than being dropped — a notification the user never saw is worse than a late one — and each toast's `duration` only starts once it actually becomes visible, so a queued message cannot expire unseen. Default 3; unbounded stacking just fills the viewport. |
 
 #### Deprecated (still supported — removal targeted for 3.0)
 
 | Property | Attribute | Type | Use instead |
 | --- | --- | --- | --- |
-| `type` | `type` | `"default" \| "destructive" \| "error" \| "danger" \| "critical"` | Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"`. Ignored when `tone` is set. Logs a one-time console notice. |
+| `type` | `type` | `"neutral" \| "destructive" \| "default" \| "error" \| "danger" \| "critical"` | Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"` and `type="default"` to `tone="neutral"`. Ignored when `tone` is set. Logs a one-time console notice. |
 
 ### Public fields / accessors
 
 | Name | Type | Description |
 | --- | --- | --- |
-| `resolvedTone` | `ToastTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"default"`; deprecated aliases are resolved to `"destructive"`. |
+| `resolvedTone` | `ToastTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`. |
 
 ### Methods
 
@@ -118,7 +122,7 @@ rel-toast { --rel-z-toast: 10000; }
 | `base` | The `role="status"` toast container that carries the tone class |
 | `label` | The message text span |
 | `action` | The action button; rendered only when `actionlabel` is set |
-| `close-button` | The dismiss (✕) button |
+| `close-button` | The dismiss button; rendered while `dismissible` is true |
 
 ## Tokens / CSS Variables
 
@@ -149,7 +153,11 @@ Set these on the host (or an ancestor) to customise the element without touching
 ## Notes / Edge Cases
 
 - `show` is a boolean **property**, not a method: `toast.show()` throws. Use `toast.show = true` or `toast.open()`; the old README's `show()` call was wrong.
-- The host is `position: fixed; bottom: 24px; left: 50%` with `pointer-events: none` (the pill itself restores `pointer-events: all`), so it never blocks clicks around it. There is no stacking manager: two visible toasts overlap at the same spot — reuse one element and update `message`.
+- The host is a full-width `position: fixed` bar (`left: 0; right: 0`) pinned to the edge named by `position`, with `pointer-events: none` (the pill itself restores `pointer-events: all`), so it never blocks clicks around it. The corner positions add a 24px side inset so the toast does not sit flush against the viewport edge; the centred ones keep the full width to centre in, which is why `bottom-center` is unchanged from before the axis existed.
+- Top-anchored toasts animate in from the top edge (`fadeInDown`) rather than sliding upward, which would have read as the toast escaping its own anchor.
+- **Toasts at the same `position` stack automatically.** No wrapper element and no change to your markup: each `rel-toast` registers itself, and up to `max-visible` (default 3) show at once with the newest against the anchor edge. Dismissing one closes the gap for the rest, animated. The six positions are independent stacks, and a toast whose `position` changes while it is showing leaves one and joins the other.
+- **Overflow waits; it is never dropped.** Beyond `max-visible`, further toasts queue in arrival order and appear as earlier ones dismiss. A toast's `duration` does not begin until it is actually on screen, so a queued message cannot expire before anyone has seen it. *Behaviour change*: five toasts at one position used to render on top of each other — now three show and two wait.
+- A single toast is unaffected by any of this: the stack only writes a transform from the second card onward, so a lone toast renders exactly as it did before stacking existed.
 - The auto-dismiss timer starts only when `show` changes to true; changing `duration` on a visible toast does not restart it. Re-showing a visible toast (setting `show = true` again) is a no-op because the value did not change — `close()` it first.
 - `close()` always fires `dismissed`, even when the toast was already hidden.
 - The action button's hover state swaps to `--rel-bg-neutral` / `--rel-text-default` at 75% opacity.

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

@@ -60,9 +60,10 @@ Hover/focus tooltip implementing the Figma "Tooltip" component: wraps a trigger
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `text` | `text` | `string` | `""` | Plain-text content of the bubble. Empty text still renders an (empty) bubble on hover, so always set it. |
-| `position` | `position` | `"above" \| "below" \| "left" \| "right"` | `"above"` | Side of the trigger the bubble appears on, 6px away and centred: `above`, `below`, `left` or `right`. No collision detection — pick a side with room in the viewport. |
+| `position` | `position` | `"above" \| "below" \| "left" \| "right"` | `"above"` | Side of the trigger the bubble appears on, centred and 6px away (13px when `show-tail` is set, so the tail clears the trigger; override with `--rel-tooltip-offset`): `above`, `below`, `left` or `right`. No collision detection — pick a side with room in the viewport. |
 | `showTail` | `show-tail` | `boolean` | `false` | Renders the triangular tail (`indicator` part) on the bubble's edge facing the trigger. |
-| `type` | `type` | `"single-line" \| "multi-line"` | `"single-line"` | Figma "Type": `single-line` keeps the text on one line and sizes to content; `multi-line` wraps inside a 220px max-width bubble. Reflected. |
+| `type` | `type` | `"single-line" \| "multi-line"` | `"single-line"` | Figma "Type": `single-line` keeps the text on one line and sizes to content; `multi-line` wraps inside a 200px max-width bubble. Reflected. |
+| `tone` | `tone` | `"inverse" \| "neutral"` | `"inverse"` | Bubble appearance: `inverse` (default) is the original inverse-surface bubble, unchanged; `neutral` is a light surface — `--rel-bg-neutral` with `--rel-text-default` and a 1px `--rel-border-default`, tail included. Figma has no such variant; this is a deliberate addition. Reflected. |
 
 ## Events
 
@@ -83,6 +84,16 @@ Hover/focus tooltip implementing the Figma "Tooltip" component: wraps a trigger
 | `panel` | The tooltip bubble (`role="tooltip"`): background, padding, radius, shadow and max-width. |
 | `indicator` | The triangular tail pointing at the trigger, rendered only when `show-tail` is set. |
 
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-tooltip-offset` | `6px` | Gap between the trigger and the bubble; defaults to `6px`, or `13px` when `show-tail` is set so the tail clears the trigger. |
+
 <!-- readme-gen:end -->
 
 ## Accessibility

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

@@ -146,7 +146,7 @@ File upload: `<rel-upload>` renders the dropzone, the format / size hint, the st
 
 | Part | Description |
 | --- | --- |
-| — | None exposed. |
+| `browse` | The `rel-button` that opens the file picker (Figma "Browse Button": Size=Medium, Style=Secondary). |
 
 ### Tokens / CSS Variables
 
@@ -156,7 +156,7 @@ Set these on the host (or an ancestor) to customise the element without touching
 
 | Custom property | Default | Description |
 | --- | --- | --- |
-| `--rel-upload-browse-hover-bg` | `var(--rel-action-neutral-outline-hover, var(--rel-bg-surface-elevated))` | Background of the Browse button on hover; falls back to `--rel-action-neutral-outline-hover`, then `--rel-bg-surface-elevated` |
+| `--rel-upload-browse-hover-bg` | `transparent` | Background of the Browse button on hover. Defaults to `transparent`, which is what the underlying `rel-button` secondary style draws (Figma's outline button reacts on its border, not its fill), so this only takes effect when you set it. |
 
 ### `<rel-upload-actions>`