@reliability-design/web 1.4.5 → 1.4.7

package/dist/index.d.mts

@@ -3,12 +3,32 @@ import * as lit from 'lit';
 import { LitElement, PropertyValues, TemplateResult } from 'lit';
 export * from '@reliability-design/icons';
 
+/**
+ * Single collapsible section (Figma "Accordion", 6021:1085): a clickable header
+ * that expands/collapses the slotted body with an animated chevron.
+ * @slot - Body content, revealed when `open`
+ * @slot icon - Leading icon in the header (`type="action"` only); replaces the default rotating chevron-down
+ * @slot trailing-icon - Trailing icon in the header; replaces the default chevron-down (default type) or arrow-expansion (action type)
+ * @csspart base - The outer card (`.accordion`) carrying the appearance border / shadow
+ * @csspart trigger - The `role="button"` header row
+ * @csspart label - The title row (leading icon + title text)
+ * @csspart icon - The trailing icon wrapper
+ * @csspart content - The `role="region"` body that holds the default slot
+ */
 declare class RelAccordion extends LitElement {
+    /** Header text. Note it is also the native HTML `title` attribute, so browsers show it as a tooltip on hover. */
     title: string;
+    /** Whether the body is expanded; toggled by the header and reported via `open-change`. Setting it from code does not fire the event. */
     open: boolean;
-    size: "md" | "sm";
+    /**
+     * Header scale (Figma "Size"): `large` = 56px header / heading-md title, `medium` = 48px / heading-sm,
+     * `small` = 44px / heading-xs (new in 1.4.7). The historical spellings stay supported as aliases:
+     * `md` = large (the default), `sm` = medium.
+     */
+    size: "md" | "sm" | "large" | "medium" | "small";
+    /** Header layout (Figma "Type"): `default` = title + trailing rotating chevron; `action` = leading icon slot (rotating chevron by default) + static trailing arrow-expansion icon, with the body indented under the title. */
     type: "default" | "action";
-    /** Figma "Style" axis — named appearance because `style` collides with the HTML style attribute. */
+    /** Figma "Style" axis — named appearance because `style` collides with the HTML style attribute. `shadow` = 4px-radius card with the shadow-sm effect and no border; `plain` = square corners with a 1px border-subtle stroke and no elevation. */
     appearance: "shadow" | "plain";
     static styles: lit.CSSResult;
     /** Stable id prefix wiring the header to its panel. */
@@ -17,15 +37,44 @@ declare class RelAccordion extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/** Canonical semantic tones (Figma "Tone"). */
+type AlertTone = "neutral" | "info" | "success" | "warning" | "destructive";
+/** Deprecated tone spellings, all mapped to "destructive". */
+type AlertToneAlias = "error" | "danger" | "critical";
+type AlertToneInput = AlertTone | AlertToneAlias;
+/**
+ * Inline status banner (Figma "Alert"): a tone-coloured box with a leading status icon, a bold title, optional supporting text, an optional link and an optional dismiss button. Use it for persistent page- or section-level messages; use `rel-toast` / `rel-snackbar` for transient feedback.
+ * @csspart base - The `role="alert"` container that carries the tone and appearance styling
+ * @csspart icon - Wrapper around the leading status `<rel-icon>`
+ * @csspart content - Column that stacks the title, helper text and link
+ * @csspart label - The primary message (`message1`) paragraph
+ * @csspart helper - The secondary message (`message2`) paragraph; rendered only when `message2` is set
+ * @csspart action - The inline link; rendered only when both `url-text` and `url-href` are set
+ * @csspart close-button - The dismiss (✕) button; rendered only while `dismissible` is true
+ */
 declare class RelAlert extends LitElement {
-    type: "info" | "success" | "warning" | "error" | "neutral";
-    /** Visual treatment (Figma "Style"): solid | subtle | outline. "filled" is a deprecated alias of solid. */
+    /**
+     * Semantic tone (Figma "Tone"): `"neutral"` (default) | `"info"` | `"success"` | `"warning"` | `"destructive"`. Drives the fill/border colour, the title colour and the leading icon (info, check-circle, alert-circle, error). `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"` and log a one-time console notice. Takes precedence over the deprecated `type` prop.
+     */
+    tone?: AlertToneInput;
+    /** @deprecated 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?: AlertToneInput;
+    /** Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"destructive"`. */
+    get resolvedTone(): AlertTone;
+    willUpdate(changed: Map<string, unknown>): void;
+    /** Visual treatment (Figma "Style"): `"subtle"` (default: tone-light fill, no border) | `"solid"` (tone fill, inverse text, `--rel-shadows-md` elevation) | `"outline"` (transparent fill, tone border). `"filled"` is a deprecated alias of `"solid"` (no console notice). */
     appearance: "solid" | "subtle" | "outline" | "filled";
+    /** Primary message (title), rendered in body-lg medium weight in the tone colour. */
     message1: string;
+    /** Optional secondary message rendered under the title in body-md at 90% opacity; omitted when unset. */
     message2?: string;
+    /** Text of the inline link rendered under the messages. The link appears only when both `urlText` and `urlHref` are set. */
     urlText?: string;
+    /** `href` of the inline link. The link appears only when both `urlText` and `urlHref` are set. */
     urlHref?: string;
+    /** Shows the dismiss (✕) 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. */
     dismissible: boolean;
+    /** True once the alert has been dismissed; hides the host via `:host([dismissed]) { display: none }`. Set it back to `false` to show the alert again. */
     dismissed: boolean;
     static styles: lit.CSSResult;
     private dismissAlert;
@@ -36,6 +85,13 @@ declare class RelAlert extends LitElement {
 type TextFieldState = "default" | "error" | "disabled";
 type TextFieldSize = "small" | "medium" | "large";
 type TextFieldVariant = "default" | "underline" | "legend";
+/**
+ * How the prefix block is drawn (Figma `.Preffix` → Style):
+ *   - `"clear"`   — bare icon/text, no separator (the legacy `leftIcon` look)
+ *   - `"divider"` — hairline between the prefix and the input
+ *   - `"fill"`    — tinted block flush with the control's left edge
+ */
+type TextFieldPrefixStyle = "clear" | "divider" | "fill";
 /**
  * How a field presents its label. Shared by `<rel-textfield>`, `<rel-select>`
  * and `<rel-autocomplete>` so the three stay in step.
@@ -45,20 +101,61 @@ type TextFieldVariant = "default" | "underline" | "legend";
  *                    `fieldAriaLabelledby` to keep an accessible name
  */
 type FieldLabelStyle = "default" | "floating" | "none";
+/**
+ * `<rel-textfield>` — single-line or multi-line text input (Figma "Text Field").
+ * @slot 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.
+ * @slot 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.
+ * @csspart label - The visible label element (default and floating label styles)
+ * @csspart control - The bordered control box (the fieldset in the legend variant)
+ * @csspart input - The native input / textarea
+ * @csspart prefix - The prefix block (leading icon, prefix text and the `prefix` slot)
+ * @csspart suffix - The suffix block (suffix text, trailing icon and the `suffix` slot)
+ * @csspart right-icon - The trailing `rel-icon`
+ * @csspart helper - The helper / error text line below the control
+ * @cssprop --rel-field-label-reserve - 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).
+ */
 declare class RelTextfield extends LitElement {
+    /**
+     * 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"`.
+     */
     label?: string;
+    /** Placeholder shown while the field is empty. Under the floating label style it stays hidden until the field is focused. */
     placeholder: string;
+    /** Native input `type` (`text`, `email`, `password`, `number`, …). Ignored when `multiline` is set. */
     type: string;
+    /** Current text. Updated on every keystroke; set it to control the field programmatically. */
     value: string;
+    /** Legacy name for the leading icon (a `rel-icon` name). `prefixIcon` wins when both are set. */
     leftIcon?: string;
+    /** Trailing `rel-icon` name rendered in the suffix block. Decorative unless `clickableRightIcon` is set. */
     rightIcon?: string;
     /** Makes the trailing icon interactive (pointer + focusable) and emits
      *  `rel-right-icon-click` — e.g. a password show/hide toggle or clear button. */
     clickableRightIcon: boolean;
     /** Accessible label for the trailing icon when it is clickable. */
     rightIconAriaLabel?: string;
+    /** Short text rendered before the input, e.g. `"http://"` or `"$"`. Sits in
+     *  the same prefix block as `prefixIcon` and is styled by `prefixStyle`. */
+    prefixText?: string;
+    /** Visual treatment of the prefix block — applies to the prefix icon, text
+     *  and slotted `prefix` content alike. See `TextFieldPrefixStyle`. */
+    prefixStyle: TextFieldPrefixStyle;
+    /** Short text rendered after the input, e.g. `"kg"` or `".00"`. Shares the
+     *  suffix block with `rightIcon` and slotted `suffix` content. */
+    suffixText?: string;
+    /** Draws a hairline between the input and the suffix block. */
+    suffixDivider: boolean;
+    /** Legacy name for the helper line below the control. `helperText` wins when both are set. */
     supportingText?: string;
+    /**
+     * 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.
+     */
     state: TextFieldState;
+    /** Control height — `small` 32px, `medium` 40px, `large` 48px — which also scales the text and the affix icons. */
     size: TextFieldSize;
     /**
      * Label presentation. Left `undefined` the deprecated `floatingLabel` boolean
@@ -76,22 +173,39 @@ declare class RelTextfield extends LitElement {
     fieldAriaLabel?: string;
     /** IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. */
     fieldAriaLabelledby?: string;
+    /** Field chrome: `default` outlined box, `underline` bottom border only, `legend` notched outline with the label sitting in the top border (native fieldset/legend). */
     variant: TextFieldVariant;
+    /** Disables the input (not focusable, not editable) and dims the control. */
     disabled: boolean;
+    /** Marks the input required: sets native `required` / `aria-required` and appends an asterisk to the label. */
     required: boolean;
+    /** Renders a textarea instead of a single-line input (see `rows`). Prefix/suffix blocks and `type` are ignored in this mode. */
     multiline: boolean;
+    /** Visible text rows of the textarea when `multiline` is set. */
     rows: number;
+    /** Leading `rel-icon` name rendered in the prefix block (preferred over the legacy `leftIcon`). */
     prefixIcon?: string;
+    /** Accessible label for the leading icon. Without it the icon is `aria-hidden` (decorative). */
     prefixIconAriaLabel?: string;
+    /** Puts the field in the error state: danger border, `aria-invalid`, and `errorMessage` replacing the helper text. */
     error: boolean;
+    /** Text shown below the control instead of `helperText` while the field is in the error state. */
     errorMessage?: string;
+    /** Helper line below the control (preferred over the legacy `supportingText`); linked to the input via `aria-describedby`. */
     helperText?: string;
+    /** Makes the input read-only: focusable and selectable but not editable. */
     readonly: boolean;
+    /** Maximum number of characters (native `maxlength`). */
     maxLength?: number;
+    /** Form field name forwarded to the native input, for form submission and autofill. */
     name?: string;
+    /** Fills the parent width as a block element (default). Unset it to render inline at the content's natural width. */
     fullWidth: boolean;
     private internalState;
+    /** Whether the `prefix` / `suffix` named slots currently have content. */
+    private slotted;
     private _wasError;
+    private _prefixObserver?;
     private uniqueId;
     private get isDisabled();
     private get isError();
@@ -103,6 +217,24 @@ declare class RelTextfield extends LitElement {
     private get labelHidden();
     static styles: lit.CSSResult;
     connectedCallback(): void;
+    disconnectedCallback(): void;
+    private handleSlotChange;
+    /**
+     * The whole control is the input's hit area. The input already stretches
+     * to the row (CSS), but the control's own border, the legend notch, and
+     * any padding around slotted content are still container pixels — press
+     * there and focus the input, as clicking a <label> would. Skipped when the
+     * press is on the input itself (native caret placement), a clickable icon,
+     * or slotted content (their own behaviour), and when disabled.
+     * preventDefault keeps the press from moving focus to the body first.
+     */
+    private handleControlMousedown;
+    /** Clicking the (non-interactive) prefix/suffix area focuses the input, as a
+     *  label would. Clickable icons and slotted controls keep their own clicks. */
+    private handleAffixClick;
+    /** Publishes the prefix block's width as --_rel-tf-prefix-w on its parent so
+     *  the floated label can slide back over a clear-style prefix (see CSS). */
+    private observePrefix;
     willUpdate(changed: PropertyValues<this>): void;
     private _warnedNoName;
     updated(): void;
@@ -116,7 +248,12 @@ declare class RelTextfield extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
-/** An item is a plain string or any object read through displayField/valueField. */
+/**
+ * An item is a plain string or any object read through displayField/valueField.
+ * Two keys are read off objects directly, whatever those fields are named:
+ * `icon` (a `rel-icon` name shown before the label) and `disabled` (`true`
+ * renders the row dulled and makes it unselectable by click or keyboard).
+ */
 type AutocompleteItem = string | Record<string, unknown>;
 type AutocompleteFilter = "contains" | "starts-with" | "none";
 type AutocompleteSearchFn = (query: string) => Promise<AutocompleteItem[]>;
@@ -133,6 +270,24 @@ type AutocompleteSearchFn = (query: string) => Promise<AutocompleteItem[]>;
  * `valueField`) — typing alone emits `rel-change` with the raw text but does
  * not change `value` until an item is picked (or the text exactly matches an
  * item's label/value on Enter/blur).
+ * @csspart panel - The suggestion listbox container (same node as `list`)
+ * @csspart list - Alias of `panel`
+ * @csspart option - A suggestion row
+ * @csspart label - The inner field's label (re-exported from `rel-textfield`)
+ * @csspart control - The inner field's bordered control box (re-exported from `rel-textfield`)
+ * @csspart input - The inner native input (re-exported from `rel-textfield`)
+ * @csspart helper - The inner field's helper / error line (re-exported from `rel-textfield`)
+ * @csspart right-icon - The clear icon shown when `clearable` (re-exported from `rel-textfield`)
+ * @cssprop --rel-autocomplete-bg - Panel and row background
+ * @cssprop --rel-autocomplete-menu-border - Panel border colour. The panel is borderless by design and only draws this on dark surfaces, where its shadow alone can't separate it from the page.
+ * @cssprop --rel-autocomplete-menu-radius - Panel corner radius
+ * @cssprop --rel-autocomplete-menu-shadow - Panel box-shadow
+ * @cssprop --rel-autocomplete-divider - Hairline between rows
+ * @cssprop --rel-autocomplete-option-hover - Background of the hovered / keyboard-highlighted / selected row
+ * @cssprop --rel-autocomplete-option-pressed - Background of a row while it is being pressed
+ * @cssprop --rel-autocomplete-value-color - Suggestion label colour
+ * @cssprop --rel-autocomplete-icon-color - Colour of a row's leading `icon`
+ * @cssprop --rel-autocomplete-status-color - Colour of the loading / no-results status rows
  */
 declare class RelAutocomplete extends LitElement {
     /** Local (or fallback initial) suggestion list. Ignored while searchFn drives results. */
@@ -159,12 +314,17 @@ declare class RelAutocomplete extends LitElement {
     loading: boolean;
     /** Row shown when a query yields nothing. */
     noResultsText: string;
+    /** Text shown next to the spinner while suggestions load. */
     loadingText: string;
+    /** Visible label, forwarded to the inner `rel-textfield`. Also names the suggestion panel. */
     label?: string;
+    /** Placeholder of the input, forwarded to the inner `rel-textfield`. */
     placeholder: string;
+    /** Field height — `small` 32px, `medium` 40px, `large` 48px — forwarded to the inner `rel-textfield`. Also drives the suggestion panel's row ramp. */
     size: TextFieldSize;
+    /** Field chrome (`default` outlined, `underline`, `legend` notched outline), forwarded to the inner `rel-textfield`. */
     variant: TextFieldVariant;
-    /** See `FieldLabelStyle`. Left `undefined` the deprecated `floatingLabel` decides. */
+    /** Label presentation (`default` / `floating` / `none`), forwarded to the inner field. Left `undefined`, the deprecated `floatingLabel` decides. */
     labelStyle?: FieldLabelStyle;
     /** @deprecated Use `labelStyle="floating"`. Kept permanently as an alias. */
     floatingLabel: boolean;
@@ -172,14 +332,23 @@ declare class RelAutocomplete extends LitElement {
     fieldAriaLabel?: string;
     /** IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. */
     fieldAriaLabelledby?: string;
+    /** Leading `rel-icon` name in the field's prefix block, e.g. `search`. */
     prefixIcon?: string;
+    /** Disables the field; the panel never opens and the clear affordance is hidden. */
     disabled: boolean;
+    /** Read-only field: focusable but not editable; the panel never opens and the clear affordance is hidden. */
     readonly: boolean;
+    /** Marks the input required (native `required` / `aria-required`, asterisk on the label). */
     required: boolean;
+    /** Puts the field in the error state (danger border, `aria-invalid`); pair with `errorMessage`. */
     error: boolean;
+    /** Text shown below the field instead of `helperText` while `error` is set. */
     errorMessage?: string;
+    /** Helper line below the field, linked to the input via `aria-describedby`. */
     helperText?: string;
+    /** Form field name forwarded to the native input. */
     name?: string;
+    /** Fills the parent width as a block element (default). Unset it to render inline at the content's natural width. */
     fullWidth: boolean;
     private open;
     private inputText;
@@ -202,6 +371,8 @@ declare class RelAutocomplete extends LitElement {
     static styles: lit.CSSResult;
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues<this>): void;
+    private wasLoading;
+    protected updated(): void;
     /** Full normalized source list (remote results while searchFn drives, else items). */
     private get allItems();
     private normalizeItem;
@@ -221,6 +392,7 @@ declare class RelAutocomplete extends LitElement {
     /** Re-evaluates whether the panel should be showing for the current state. */
     private syncPanel;
     private onFieldInput;
+    private announceResults;
     private runSearch;
     private selectItem;
     /** Silent commit when typed text exactly matches an item (label or value, case-insensitive). */
@@ -228,6 +400,9 @@ declare class RelAutocomplete extends LitElement {
     private emitChanged;
     private clear;
     private onKeyDown;
+    /** First selectable row at or past `from`, walking in `step`; -1 if none. */
+    private nextEnabledIndex;
+    private announceHighlighted;
     private onFocusIn;
     private onFocusOut;
     /** Delegates focus to the inner textfield. */
@@ -242,24 +417,58 @@ declare global {
     }
 }
 
+/**
+ * Circular avatar (Figma "Avatar"): shows a photo, text initials or a slotted icon in one of four sizes and three fill variants.
+ * @slot - Icon content rendered when `type="icon"` (typically an inline SVG, sized to 50% of the circle)
+ * @csspart base - The circular wrapper that carries the size, variant and inline `bg` / `color` overrides
+ * @csspart icon - The `<img>` (`type="image"`) or the icon wrapper span around the slot (`type="icon"`)
+ * @csspart label - The `<span>` holding the initials when `type="text"`
+ * @cssprop --rel-avatar-bg-fill - Background colour of the `fill` variant
+ * @cssprop --rel-avatar-color-fill - Text / icon colour of the `fill` variant
+ * @cssprop --rel-avatar-bg-subtle - Background colour of the `subtle` variant
+ * @cssprop --rel-avatar-color-subtle - Text / icon colour of the `subtle` variant
+ * @cssprop --rel-avatar-border-outline - 1px border colour of the `outline` variant
+ * @cssprop --rel-avatar-color-outline - Text / icon colour of the `outline` variant
+ * @cssprop --rel-avatar-size - Overrides the circle's width/height for sizes between (or below) the `size` presets; defaults to the preset's diameter
+ * @cssprop --rel-avatar-font-size - Overrides the initials' font-size, for use alongside `--rel-avatar-size`; defaults to the preset's text role
+ */
 declare class RelAvatar extends LitElement {
+    /** Diameter step: `lg` 40px, `md` 32px, `sm` 24px, `xs` 20px; each binds the matching body-*-semibold text role for initials. */
     size: "lg" | "md" | "sm" | "xs";
+    /** What is rendered inside the circle: `image` shows `src`, `text` shows the `text` initials, `icon` shows the default slot. */
     type: "image" | "text" | "icon";
+    /** Fill style: `fill` = solid inverse background with light text, `subtle` = elevated neutral background, `outline` = transparent with a 1px border. */
     variant: "fill" | "subtle" | "outline";
+    /** Image URL for `type="image"`; when empty nothing is rendered inside the circle (there is no fallback to initials). */
     src: string;
+    /** Initials shown for `type="text"`; rendered uppercase via `text-transform`. */
     text: string;
+    /** Alt text of the `<img>` for `type="image"`; the default is the generic word "Avatar", so pass the person's name. */
     alt: string;
+    /** Any CSS colour applied inline as `background-color` on the circle, overriding the variant background. */
     bg: string;
+    /** Any CSS colour applied inline as `color` on the circle (initials / icon), overriding the variant text colour. */
     color: string;
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Notification badge (Figma "Badge"): a small count pill or an unlabeled dot, usually positioned over an icon or avatar.
+ * @csspart base - The `role="status"` pill / dot that carries the size, variant and colour overrides
+ * @cssprop --rel-badge-bg - Background colour of the badge; the `color` prop writes this on the host
+ * @cssprop --rel-badge-color - Text colour of the count; the `text-color` prop writes this on the host
+ */
 declare class RelBadge extends LitElement {
+    /** Text shown in the `number` variant (a count such as "5" or "99+"); not rendered by `variant="dot"` but still used to build the accessible name. */
     number: string;
+    /** Explicit accessible name; when empty it is composed as "<number> <suffix>" or, with no number, "New <suffix>". Attribute is `arialabel`. */
     ariaLabel: string;
+    /** Noun appended to the count in the generated accessible name, e.g. "3 notifications". */
     suffix: string;
+    /** Badge scale (Figma Badge S/M/L/XL): number badges are 20 / 24 / 28 / 40px tall, dot badges 8 / 10 / 12 / 12px. */
     size: "sm" | "md" | "lg" | "xl";
+    /** `number` renders the `number` text in a pill that widens with its content; `dot` renders a small disc with no text. */
     variant: "dot" | "number";
     /**
      * Direct CSS color override for the badge background. Accepts any valid
@@ -277,6 +486,7 @@ declare class RelBadge extends LitElement {
     textColor: string;
     static styles: lit.CSSResult;
     private get classes();
+    private get computedAriaLabel();
     updated(changedProperties: Map<PropertyKey, unknown>): void;
     render(): lit_html.TemplateResult<1>;
 }
@@ -285,40 +495,62 @@ interface BreadcrumbItem {
     label: string;
     url?: string;
 }
+/**
+ * Breadcrumb trail: a `<nav aria-label="Breadcrumb">` ordered list of links with chevron separators, whose last entry is the current page. Use it to show where a page sits in a hierarchy; do not use it as primary navigation.
+ * @csspart base - The `<nav>` landmark wrapping the ordered list.
+ * @csspart label - The non-link current-page text (`aria-current="page"`), also used for any item without a `url`.
+ */
 declare class RelBreadcrumbs extends LitElement {
+    /** Ordered trail, root first: `{ label: string; url?: string }[]`. Items with a `url` render as links except the last one, which is always the current page (and never a link). Set as a property — arrays do not survive attribute serialisation. */
     items: BreadcrumbItem[];
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
 }
 
 /**
- * Style axis. Canonical values are the historical ones; "outline"/"ghost" are
- * accepted Figma-vocabulary aliases for "secondary"/"text". "static" is the
- * Figma Style=Static treatment (transparent, static-light label — for use on
- * colored/dark surfaces). Legacy "icon" is the pre-2.0 collapsed icon-button
- * variant and keeps its exact behavior; prefer icon-only + a style instead.
+ * Style axis (Figma "Style"): primary | secondary | ghost | link | static.
+ * "outline" (= secondary) and "text" (= ghost) are the historical spellings
+ * and stay supported; "default" is the legacy neutral-fill style. "static" is
+ * the Figma Style=Static treatment (transparent, static-light label — for use
+ * on colored/dark surfaces). Legacy "icon" is the pre-2.0 collapsed
+ * icon-button variant and keeps its exact behavior; prefer icon-only + a
+ * style instead.
  */
 type ButtonVariant = "default" | "primary" | "secondary" | "text" | "link" | "icon" | "static" | "outline" | "ghost";
-/** Tone axis. "neutral"/"brand"/"danger" are Figma-vocabulary aliases. */
-type ButtonTone = "default" | "primary" | "secondary" | "critical" | "success" | "neutral" | "brand" | "danger";
+/**
+ * Tone axis (Figma "Tone"): neutral | brand | destructive. Historical
+ * spellings "default" (= neutral), "primary" (= brand), "critical" and
+ * "danger" (= destructive) stay supported; "critical"/"danger" log a one-time
+ * deprecation notice. "secondary"/"success" are legacy extras.
+ */
+type ButtonTone = "default" | "primary" | "secondary" | "critical" | "success" | "neutral" | "brand" | "danger" | "destructive";
+/**
+ * Action button (Figma "Button"): a native `<button>` with the Figma Style / Tone / Size axes, an icon-only mode, a loading spinner and an optional corner badge. Use it for every clickable action; use an anchor for navigation.
+ * @slot - Button content: label text, a `rel-icon`, or icon + text (kept on one line with the size's gap).
+ * @csspart base - The inner native `<button>` element (padding, min-width, fill, border, focus ring).
+ * @csspart indicator - The loading spinner, rendered only while `loading` is set.
+ * @cssprop --rel-button-min-width - Overrides the per-size minimum width (Figma small/medium/large = 80/100/120px, ghost small = 56px). Ignored by `icon-only` and `link`.
+ */
 declare class RelButton extends LitElement {
+    /** Style axis (Figma "Style"). Canonical: `default` (legacy neutral fill), `primary`, `secondary` (outlined), `ghost` (text-only), `link` (underlined inline text), `static` (transparent, static-light label for dark/colored surfaces). Deprecated aliases still accepted: `outline` = secondary, `text` = ghost, and `icon` (pre-2.0 40px circular icon button — use `icon-only` with a style instead). */
     variant: ButtonVariant;
+    /** Tone axis (Figma "Tone"). Canonical: `neutral` (= `default`), `brand` (= `primary`), `destructive`. Deprecated aliases `critical` and `danger` map to destructive and log a one-time console notice. `secondary` and `success` are legacy extras with no Figma counterpart (secondary only affects the legacy `icon` variant). */
     tone: ButtonTone;
-    /**
-     * Figma "Type=Icon Only" as an independent axis: a square button of the
-     * current style/tone. Unlike legacy variant="icon", this composes with
-     * every style (outline/ghost/link included).
-     */
+    /** Figma "Type=Icon Only": renders a square button (32/40/48px per `size`) of the current style and tone with no padding or min-width. Composes with every `variant`; slot a single `rel-icon` and set `aria-label`. */
     iconOnly: boolean;
-    /** Figma "State=Loading": shows a spinner, blocks interaction. */
+    /** Figma "State=Loading": replaces the label with a spinner (`indicator` part), sets `aria-busy`, and blocks pointer and programmatic clicks. The button keeps its width. */
     loading: boolean;
+    /** Figma "Size": `small` = 32px, `medium` = 40px, `large` = 48px height, with matching padding, typography and minimum width. */
     size: "small" | "medium" | "large";
+    /** Corner treatment: `corner-radius` = fully rounded pill, `small-corner-radius` = small radius token, `no-corner-radius` = square corners. */
     border: "corner-radius" | "small-corner-radius" | "no-corner-radius";
+    /** Figma "State=Disabled": dims the button to 50% opacity, flattens filled styles to the disabled fill, shows a `not-allowed` cursor and swallows every click (including programmatic `.click()`). */
     disabled: boolean;
+    /** Accessible name forwarded to the inner native `<button>`. Required for `icon-only` buttons, whose slotted icon has no visible text. */
     ariaLabel: string | null;
-    /** Numeric/overflow text shown in a corner badge (e.g. "3", "999+"). Ignored when badgeDot is set. */
+    /** Text for a small `rel-badge` anchored to the top-right corner (e.g. "3", "999+"). Empty string renders no badge. Ignored when `badge-dot` is set. */
     badge: string;
-    /** Shows a small corner dot instead of a numbered badge — takes precedence over `badge`. */
+    /** Renders a small dot badge in the top-right corner instead of a numbered badge; takes precedence over `badge`. The dot is inset 2px from the corner so it lands on a circular icon button's edge. */
     badgeDot: boolean;
     static styles: lit.CSSResult;
     connectedCallback(): void;
@@ -326,20 +558,37 @@ declare class RelButton extends LitElement {
     private handleHostClick;
     /** Style axis with Figma-vocabulary aliases folded onto canonical values. */
     private get styleVariant();
-    /** Tone axis with Figma-vocabulary aliases folded onto canonical values. */
+    /** Tone axis with Figma-vocabulary aliases folded onto the internal class names. */
     private get effectiveTone();
+    willUpdate(changed: Map<string, unknown>): void;
     private get classes();
     private handleClick;
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Inline single-date calendar (Figma "Calendar"): a month grid with previous/next
+ * navigation, always visible — no trigger or popover. Use rel-date-picker for a form field.
+ * @csspart header - Month navigation row (previous button, month/year label, next button)
+ * @csspart action - The previous-month and next-month buttons
+ * @csspart label - The month/year heading and each weekday column header
+ * @csspart list - The weekday-header row and the day grid
+ * @csspart item - Each day cell button
+ */
 declare class RelCalendar extends LitElement {
+    /** Selected date as an ISO `YYYY-MM-DD` string, or `null` for no selection; setting it also moves the visible month. */
     value: string | null;
+    /** Earliest selectable date (ISO `YYYY-MM-DD`); earlier days render disabled. */
     min: string | null;
+    /** Latest selectable date (ISO `YYYY-MM-DD`); later days render disabled. */
     max: string | null;
+    /** Disables every day cell and the month navigation; the host dims to 40% opacity (Figma State=Disabled). */
     disabled: boolean;
+    /** First column of the week grid: `"sun"` (default) or `"mon"`. */
     weekStart: "sun" | "mon";
+    /** BCP 47 locale for the month name, weekday headers and day cell labels (via `Intl.DateTimeFormat`). */
     locale: string;
+    /** Custom predicate that disables individual days (return `true` to disable); applied on top of `min`/`max`. Property only — assign it from JavaScript. */
     isDateDisabled?: (date: Date) => boolean;
     private viewYear;
     private viewMonth;
@@ -354,6 +603,10 @@ declare class RelCalendar extends LitElement {
     private getCalendarDays;
     private getWeekdayLabels;
     private getMonthName;
+    private dayLabelFormatter;
+    private dayLabelLocale;
+    private formatDayLabel;
+    private announceMonth;
     private previousMonth;
     private nextMonth;
     private selectDay;
@@ -368,6 +621,15 @@ declare class RelCalendar extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * `<rel-card>` — bordered surface that groups related content (Figma "Card").
+ * Use `type="media"` with a `<rel-card-media>` in the `media` slot for a flush image header.
+ * @slot - Card body; slotted headings and paragraphs receive the Figma card typography
+ * @slot media - Flush media region above the body; rendered only when `type="media"`
+ * @csspart base - The outer bordered card surface
+ * @csspart header - The media region wrapper (present only when `type="media"`)
+ * @csspart content - The padded body that wraps the default slot
+ */
 declare class RelCard extends LitElement {
     /**
      * Figma "Type" axis: custom (default) renders slotted content with card
@@ -379,24 +641,62 @@ declare class RelCard extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Slide carousel (Figma "Carousel"): shows one slotted slide at a time in a horizontal or vertical viewport, with optional arrows, dot indicators, drag/swipe, looping and autoplay.
+ * @slot - The slides: one light-DOM element per slide (each is sized to one panel and given `role="group"` / `aria-roledescription="slide"`).
+ * @csspart viewport - The focusable `role="region"` box that clips the track (also the keyboard target).
+ * @csspart track - The flex row / column that translates to reveal the current slide.
+ * @csspart ${direction}-button - The two arrow buttons, exposed as `prev-button` and `next-button` (`type="side-arrows"` overlays them on the viewport; `type="bottom-arrows"` inlines them in the dots row).
+ * @csspart dots - The indicator row under the viewport (also hosts the arrows for `type="bottom-arrows"`).
+ * @csspart dot - One indicator button per reachable position (per slide at `panels="1"`); the active one carries the `active` class and `aria-current="true"`.
+ * @csspart dot-group - The row of dots inside `dots` (for `type="bottom-arrows"` it is the middle child, between the two arrows).
+ * @cssprop --rel-carousel-height - Viewport height in `orientation="vertical"` (default 320px); the horizontal viewport takes the height of its tallest slide.
+ * @cssprop --rel-carousel-nav-size - Width / height of the arrow buttons (default 32px, matching Figma; applies to both side and bottom arrows).
+ * @cssprop --rel-carousel-dot-size - Diameter of an inactive dot (default 8px).
+ * @cssprop --rel-carousel-dot-size-active - Width of the active (brand-coloured, pill-shaped) dot (default 16px).
+ * @cssprop --rel-carousel-slide-width - Written by the component on its own host to the computed panel width (viewport width for `panels="1"`, a fraction of it above that); not meant to be set by consumers (an inline value is overwritten on resize).
+ * @cssprop --rel-carousel-slide-height - Written by the component on its own host to the computed panel height (used for vertical slides); not meant to be set by consumers.
+ */
 declare class RelCarousel extends LitElement {
+    /** Index of the current slide (0-based). Set it to jump; it is clamped to the slide count and reflected as an attribute. */
     value: number;
+    /** Wrap from the last slide to the first (and back) with a seamless clone transition instead of stopping at the ends. */
     loop: boolean;
+    /** Advance automatically every `interval` ms; implies looping and pauses while hovered (see `pause-on-hover`) or while focus is inside the carousel. */
     autoplay: boolean;
+    /** Autoplay delay between slides, in milliseconds (default 5000). */
     interval: number;
+    /** Pause autoplay while the pointer is over the carousel or while dragging (default true; switch off via the property, e.g. `el.pauseOnHover = false`). */
     pauseOnHover: boolean;
+    /** Legacy toggle for the overlaid previous / next arrows; ignored whenever `type` is set. */
     showButtons: boolean;
-    showDots: boolean;
+    /**
+     * Figma "Show Dots" property. Tri-state: left off it defers to `type` (dots for every type
+     * except `default`, and nothing at all when `type` is unset too); `show-dots` turns them on;
+     * `show-dots="false"` turns them off even when `type` would have shown them.
+     */
+    showDots?: boolean;
     /**
      * Figma "Type" axis. When set it drives which controls render:
      * default = content only · only-indicators = dots · side-arrows = overlaid
      * arrows + dots · bottom-arrows = dots flanked by arrows below the slide.
-     * When unset, the legacy show-buttons/show-dots booleans apply unchanged.
+     * When unset, the legacy show-buttons boolean applies unchanged. The dots a type
+     * implies can always be overridden by an explicit `show-dots`.
      */
     type?: "default" | "only-indicators" | "side-arrows" | "bottom-arrows";
+    /** Slide axis: `horizontal` (default) translates the track left / right; `vertical` stacks slides in a fixed-height viewport (`--rel-carousel-height`) and translates up / down. */
     orientation: "horizontal" | "vertical";
+    /** Accessible name of the carousel region (`aria-label` on the viewport); default "Carousel". */
     label: string;
-    gap?: number;
+    /** Space between consecutive slides in pixels (applied as the track `gap` and added to each slide step); default 8 (Figma `spacing/xs`), 0 = slides touch. */
+    gap: number;
+    /**
+     * Figma "Multi Panels" axis, as a count: how many slides are visible at once (default 1).
+     * Fractions are allowed and produce a peek of the next slide — `panels="1.5"` reproduces the
+     * Figma Multi Panels=True variant. Navigation still advances one slide at a time.
+     */
+    panels: number;
+    /** Disables arrows, dots, drag and keyboard navigation, stops autoplay and renders the carousel at 60% opacity. */
     disabled: boolean;
     private slideCount;
     private isDragging;
@@ -411,15 +711,35 @@ declare class RelCarousel extends LitElement {
     private prefersReducedMotion;
     private clonesBefore;
     private _silentJumping;
+    private _autoplayTick;
     private _ro?;
     static styles: lit.CSSResult;
     connectedCallback(): void;
     firstUpdated(): void;
+    /**
+     * Write the computed panel size to the custom properties the slides (and the loop clones)
+     * are sized from, then re-align the track. The cross axis keeps the raw viewport measurement.
+     */
+    private measure;
     disconnectedCallback(): void;
     private handleSlotChange;
     private get vertical();
     /** Translate along the orientation axis. */
     private axisTransform;
+    private get panelCount();
+    private get gapPx();
+    /**
+     * Size of a single panel along the scroll axis. A viewport showing `n` panels contains
+     * `ceil(n) - 1` whole gaps — one for a 1.5-panel peek, two for three panels — so those are
+     * subtracted before the remainder is split. At `panels="1"` this is just the viewport size.
+     */
+    private panelSize;
+    /**
+     * Highest index that may lead the viewport. Without looping the track stops once the last
+     * slide is flush with the trailing edge, so multi-panel carousels never scroll into empty
+     * space; with clones in play every slide can lead because the clones fill the tail.
+     */
+    private get maxIndex();
     private unit;
     private updateTransform;
     private goToPrevious;
@@ -440,15 +760,27 @@ declare class RelCarousel extends LitElement {
     updated(changedProperties: Map<string, any>): void;
     /** Where nav arrows render, honouring the Figma type when set. */
     private get buttonPlacement();
+    /** Explicit `show-dots` wins; otherwise `type` decides, as it always has. */
     private get dotsVisible();
     private renderNavButton;
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Media card: a bordered surface with an optional full-width image on top, then a title, subtitle and slotted body. Use it for previews with a hero image (articles, products, galleries); use `rel-card` for free-form or custom layouts.
+ * @slot - Body content rendered inside the padded content area below the title and subtitle.
+ * @csspart base - The outer bordered card surface (background, border, radius, overflow clip).
+ * @csspart icon - The image wrapper above the content, rendered only when `image-src` is set.
+ * @csspart content - The padded area holding the title, subtitle and slotted body.
+ */
 declare class RelCardMedia extends LitElement {
+    /** URL of the hero image shown full-width at the top of the card. Empty (the default) omits the image section entirely. */
     imageSrc: string;
+    /** Alternative text for the hero image. Replace the generic default with a real description, or an empty string for purely decorative images. */
     imageAlt: string;
+    /** Heading rendered as an `<h3>` above the subtitle; empty omits it. Note this is also the native `title` attribute, so a value shows as a browser tooltip on hover. */
     title: string;
+    /** Secondary line rendered as a paragraph under the title; empty omits it. */
     subtitle: string;
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
@@ -456,19 +788,32 @@ declare class RelCardMedia extends LitElement {
 
 type CheckboxState = "default" | "error" | "disabled";
 type CheckboxStatus = "unchecked" | "checked" | "indeterminate";
-type CheckboxSize = "small" | "medium";
+type CheckboxSize = "small" | "medium" | "large";
 type CheckboxDensity = "compact" | "comfortable";
 type CheckboxAlignment = "leading" | "trailing";
+/**
+ * Tri-state checkbox (Figma "Checkbox"): a hidden native checkbox behind a custom box, with label, optional prefix icon and supporting text.
+ * @csspart base - The outer wrapper that carries the `state` / `status` classes
+ * @csspart label - The visible label text
+ * @csspart helper - The supporting text (rendered beside the box in comfortable density, under the row in compact)
+ */
 declare class RelCheckbox extends LitElement {
+    /** Label text rendered next to the box. */
     label: string;
-    /** rel-icon name rendered between the checkbox and the label (label prefix icon). */
+    /** rel-icon name rendered between the checkbox and the label (label prefix icon); scales with `size`. Unset renders no icon and reserves no space. */
     icon: string;
+    /** Supporting text under or beside the label; where it renders depends on `density`. */
     supportingtext: string;
+    /** Visual and interaction state (Figma State): `"error"` swaps in the danger colours, `"disabled"` blocks input and dims the control to 0.55 opacity. */
     state: CheckboxState;
+    /** Check state. `"indeterminate"` is programmatic-only — a user toggle always resolves to checked or unchecked. */
     status: CheckboxStatus;
+    /** Value reported in the `rel-change` event detail (it is not submitted with a form). */
     value: string;
     /** Control scale (Figma Size). `"medium"` (default) = 18px box with body-lg
-     *  label; `"small"` = 14px box with body-md label. */
+     *  label; `"small"` = 14px box with body-md label; `"large"` (Figma L,
+     *  added 2026-09-04) = 20px box with body-lg label and body-sm supporting
+     *  text — the same additive step rel-radio took for its large size. */
     size: CheckboxSize;
     /** Supporting-text layout (Figma Density). `"compact"` (default) puts the
      *  supporting text on its own line under the row, indented past the box;
@@ -479,6 +824,7 @@ declare class RelCheckbox extends LitElement {
      *  Trailing has no compact layout in the spec, so it always renders with
      *  comfortable density. */
     alignment: CheckboxAlignment;
+    /** Boolean view of `status`: `true` when `status === "checked"`; setting it writes `"checked"` / `"unchecked"`. */
     get checked(): boolean;
     set checked(val: boolean);
     private _onChange;
@@ -488,52 +834,109 @@ declare class RelCheckbox extends LitElement {
     /** Trailing has no compact layout in the spec — trailing wins. */
     private get effectiveDensity();
     private toggle;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnChange(fn: (value: boolean) => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnTouched(fn: () => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     writeValue(checked: boolean): void;
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Single-date form field (Figma "Date Picker"): a text field with typed date entry plus a
+ * popover calendar whose header pills drill into month and year grids, above
+ * Today/Tomorrow/Yesterday shortcut chips.
+ * Use rel-calendar for an always-visible grid and rel-range-picker for a from/to range.
+ * @csspart base - Outer wrapper carrying the size class (`small` / `medium` / `large`)
+ * @csspart label - The visible field label (rendered only when `label` is set)
+ * @csspart trigger - The field box that wraps the text input and the clear/calendar icons
+ * @csspart value - The editable text input inside the trigger
+ * @csspart shortcuts - The Today / Tomorrow / Yesterday chip row at the top of the popover
+ */
 declare class RelDatePicker extends LitElement {
+    /** Selected date as an ISO `YYYY-MM-DD` string, or `null` when empty; setting it also moves the popover to that month. */
     value: string | null;
+    /** Placeholder text shown while the field is empty (visual only; the accessible name comes from `label`, or "Select date" when unset). */
     placeholder: string;
+    /** Visible label rendered above the field and wired to the input via `aria-labelledby`; `null` renders no label. */
     label: string | null;
+    /** Disables the field, the icons and the popover; the host dims to 60% opacity. */
     disabled: boolean;
+    /** Appends a `*` to the label and sets `aria-required`; no validation is performed. */
     required: boolean;
+    /** Makes the input read-only and stops the field, icon, Enter and ArrowDown from opening the popover. */
     readonly: boolean;
+    /** Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed dates before it are rejected. Wins over the deprecated `min`. */
     minDate: string | null;
+    /** Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed dates after it are rejected. Wins over the deprecated `max`. */
     maxDate: string | null;
-    /** @deprecated use minDate */
+    /** Legacy alias of `minDate`; ignored when `minDate` is set. @deprecated use minDate */
     min: string | null;
-    /** @deprecated use maxDate */
+    /** Legacy alias of `maxDate`; ignored when `maxDate` is set. @deprecated use maxDate */
     max: string | null;
+    /** First column of the calendar grid: `"sun"` (default) or `"mon"`. */
     weekStart: "sun" | "mon";
+    /** BCP 47 locale for weekday/month names, the default long-date display, and day/month order when parsing ambiguous typed input. */
     locale: string;
+    /** Token pattern for the displayed value (`YYYY`, `YY`, `MMMM`, `MMM`, `MM`, `M`, `DD`, `D`; literal text in `[ ]`), e.g. `DD/MM/YYYY`. Unset → the locale long date. Affects only the visible text, never `value`. */
     displayFormat: string | null;
     /**
-     * Full control over the selected-value display; wins over `displayFormat`.
-     * Reactive (attribute:false) so assigning it after render re-renders the
-     * trigger — frameworks set callbacks as properties post-creation.
+     * Callback with full control over the displayed value; wins over `displayFormat`.
+     * Assign it from JavaScript; it stays reactive so setting it after render re-renders
+     * the field. The Date it receives is at local midnight.
      */
     formatDate?: (date: Date) => string;
+    /** Whether the calendar popover is open; set it directly to open/close programmatically (focus then moves into the grid). */
     open: boolean;
+    /** Closes the popover after a day is picked in the grid (default `true`). */
     closeOnSelect: boolean;
+    /** Shows a clear (×) icon while a value is set; clearing fires `rel-change` with `value: null`. */
     clearable: boolean;
+    /**
+     * Figma ".Date Picker Calendar" Show Shortcuts: renders the Today / Tomorrow /
+     * Yesterday chip row and its divider at the top of the popover. On by default —
+     * write `show-shortcuts="false"` to hide both (a plain boolean attribute could
+     * not express a default of `true`). The typed `T` / `T±N` shortcuts and the
+     * in-panel `T` key keep working either way.
+     */
+    showShortcuts: boolean;
+    /** Forces the error style (danger border, `aria-invalid`) and shows `errorMessage` below the field. Typed-entry parse errors set the same style on their own. */
     error: boolean;
+    /** Text shown below the field while `error` is set (or a typed date failed to parse); falls back to `helperText`. */
     errorMessage?: string;
+    /** Supporting text shown below the field when there is no error. */
     helperText?: string;
+    /** When set, renders a hidden `<input name>` carrying the ISO value so the picker submits with a native form. */
     name?: string;
+    /** Field height scale shared with rel-textfield / rel-select: `small` 32px, `medium` 40px (default), `large` 48px. */
     size: "small" | "medium" | "large";
+    /** Visual style of the field; `outlined` is the only variant today. */
     variant: "outlined";
+    /** Stretches the host to fill its parent's width (attribute `fullwidth`); off by default so the field keeps its intrinsic inline width. */
     fullWidth: boolean;
+    /** Custom predicate that disables individual days (return `true` to disable); applied on top of `minDate`/`maxDate` and also rejects typed input. Property only — assign it from JavaScript. */
     isDateDisabled?: (date: Date) => boolean;
     private get minBound();
     private get maxBound();
     private viewYear;
     private viewMonth;
     private focusedDate;
-    private yearDropdownOpen;
-    private monthDropdownOpen;
+    /** Panel body: the day grid, or the month / year picker reached via the header pills. */
+    private panelView;
+    /** First year of the visible Years page; re-anchored whenever that view opens. */
+    private yearPageStart;
+    /** Uncommitted typed text; null → the input shows the committed value. */
+    private inputText;
+    /** Parse/range error message for the typed text (cleared on next input). */
+    private inputError;
+    /**
+     * Whether the next popover open should move focus into the calendar grid.
+     * Icon-click / ArrowDown / external `open` do (previous behavior); opening
+     * by clicking into the text input must NOT, or typing would be impossible.
+     */
+    private focusPanelOnOpen;
+    private triggerInput?;
     private triggerButton?;
     private popoverElement?;
     private calendarGrid?;
@@ -543,6 +946,12 @@ declare class RelDatePicker extends LitElement {
     private handleClickOutside;
     private handleEscapeKey;
     updated(changedProperties: Map<string, any>): void;
+    private showTopLayer;
+    private hideTopLayer;
+    private onReposition;
+    private updatePopoverPosition;
+    /** Focus the roving day cell (selected day, else today, else first). */
+    private focusPanelSelection;
     private parseISODate;
     private formatISODate;
     private formatDisplayDate;
@@ -551,50 +960,134 @@ declare class RelDatePicker extends LitElement {
     private getCalendarDays;
     private getWeekdayLabels;
     private getMonthName;
+    private dayLabelFormatter;
+    private dayLabelLocale;
+    private formatDayLabel;
+    private announceMonth;
+    /** Short month names for the Months grid (Figma shows "Jan", "Feb", …). */
     private getMonthsList;
-    private getYearsList;
+    /** The 12 years on the current Years page. */
+    private getYearsPage;
+    /**
+     * A month or year is out of bounds only when EVERY day it contains is —
+     * a min of the 10th must not grey out that whole month.
+     */
+    private isMonthOutOfBounds;
+    private isYearOutOfBounds;
     private toggleCalendarPopover;
     private closeCalendarPopover;
     private previousMonth;
     private nextMonth;
     private selectDay;
+    /** Commit a date: set value, reset typed text/error, fire rel-change. */
+    private commitDate;
     private clearValue;
-    private handleTriggerKeydown;
+    /** Ambiguous "a/b" day/month order: display format wins, then locale. */
+    private get dayFirst();
+    /**
+     * Parse and commit the typed text (Enter / blur). Invalid or out-of-range
+     * text keeps the field in an error state with the text preserved for
+     * correction; the committed value is untouched (Escape reverts the text).
+     */
+    private commitTypedValue;
+    /** Today ± offset days, committed directly (T shortcuts / popover chips). */
+    private applyDayOffsetShortcut;
+    private handleInputInput;
+    private handleInputKeydown;
+    /** Clicking anywhere on the field opens the popover, keeping focus typed-in. */
+    private handleFieldClick;
+    /** The calendar icon toggles the popover with the previous focus behavior. */
+    private handleIconClick;
+    /** Commit typed text when focus leaves the component entirely. */
+    private handleInputBlur;
+    /** T inside the panel (grid/header focus) applies Today directly. */
+    private handlePanelKeydown;
     private handleDayKeydown;
-    private toggleMonthDropdown;
-    private toggleYearDropdown;
-    private handleDropdownTriggerKeydown;
-    private focusOpenDropdownSelection;
-    private handleDropdownKeydown;
+    /**
+     * The chevrons step by whatever the visible body is made of, so they stay
+     * useful in every view: a month, a year, or a whole 12-year page.
+     */
+    private goPrev;
+    private goNext;
+    private announceYearPage;
+    /** A pill toggles its own view; tapping it again returns to the day grid. */
+    private switchView;
+    /** Focus the selected month/year cell so the keyboard lands somewhere useful. */
+    private focusPanelGridSelection;
     private selectMonth;
     private selectYear;
+    /** Arrow-key roving across the 3-column month / year grid. */
+    private handlePeriodGridKeydown;
     /**
      * Index of the single grid cell carrying tabindex="0". The old expression
      * (`isSelected || (index === 0 && !value)`) left the grid with ZERO tab
      * stops once the user arrowed around without a selection.
      */
     private getRovingIndex;
+    /** Days view: weekday header + the six week rows. */
+    private renderDaysView;
+    /** Months view: the 3x4 grid the month pill drills into. */
+    private renderMonthsView;
+    /** Years view: one 3x4 page, centred on the year in view. */
+    private renderYearsView;
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Date-range form field (Figma "Date Range Picker"): a text field with typed "from → to"
+ * entry and a two-pane panel — quick-select presets with single-key shortcuts on the left,
+ * a month grid on the right — committed with Apply (Reset / Cancel discard the draft).
+ * Use rel-date-picker for a single date.
+ * @csspart trigger - The field box that wraps the text input and the clear/calendar icons (default trigger variant only)
+ * @csspart value - The editable text input inside the trigger
+ * @csspart overlay - The full-screen backdrop rendered in `mode="popup"` while open
+ * @csspart panel - The floating panel (`role="dialog"`) holding presets and calendar
+ * @csspart list - The preset column and the day grid
+ * @csspart option - Each quick-select preset button
+ * @csspart action - The previous-month and next-month buttons
+ * @csspart footer - The Reset / Cancel / Apply button row
+ */
 declare class RelRangePicker extends LitElement {
+    /** Committed range start as an ISO `YYYY-MM-DD` string; empty string when no range is set. */
     from: string;
+    /** Committed range end as an ISO `YYYY-MM-DD` string; empty string when no range is set. Always ≥ `from`. */
     to: string;
+    /** Locale used to match month names in typed input; the visible trigger text and calendar labels are always `en-US` (`MM/DD/YYYY`). */
     locale: string;
+    /** First column of the calendar grid: `"sun"` (default) or `"mon"`. Presets always compute weeks Sunday–Saturday. */
     weekStart: "mon" | "sun";
+    /** Earliest selectable date (ISO `YYYY-MM-DD`); earlier days are disabled and typed ranges starting before it are rejected. */
     minDate: string;
+    /** Latest selectable date (ISO `YYYY-MM-DD`); later days are disabled and typed ranges ending after it are rejected. */
     maxDate: string;
+    /** Disables the trigger, the icons and the panel controls; the host dims to 60% opacity. */
     disabled: boolean;
+    /** Whether the panel is open. Setting it directly shows/hides the panel but does not seed the draft from `from`/`to` or fire `rel-open-change` — user interaction does both. */
     open: boolean;
+    /** `popover` anchors the panel below the trigger; `popup` centres it in the viewport behind a dimmed backdrop (part `overlay`). */
     mode: "popover" | "popup";
+    /** CSS width applied to the host (any CSS length, e.g. `320px`); empty leaves the intrinsic width. */
     width: string;
+    /** CSS `min-width` applied to the host. */
     minWidth: string;
+    /** CSS `max-width` applied to the host. */
     maxWidth: string;
+    /** CSS height applied to the host. */
     height: string;
+    /** CSS `min-height` applied to the host. */
     minHeight: string;
+    /** CSS `max-height` applied to the host. */
     maxHeight: string;
+    /** Placeholder shown in the empty field; also the accessible name of the input (and of the icon trigger while no range is set). */
     placeholder: string;
+    /** `default` renders the text field; `icon` renders a single calendar icon button instead (no typed entry, no clear button, parts `trigger`/`value` absent). */
     triggerVariant: "default" | "icon";
+    /** Shows a clear (×) icon while a range is set; clearing fires `rel-change` with empty `from`/`to`. Only with the default trigger. */
+    clearable: boolean;
+    /** Stretches the host to fill its parent's width (attribute `fullwidth`),
+     *  mirroring rel-time-picker / rel-date-picker. Off by default so the
+     *  existing intrinsic-width (`inline-block`) rendering is unchanged. */
+    fullWidth: boolean;
     private draftFrom;
     private draftTo;
     private draftActivePreset;
@@ -604,7 +1097,11 @@ declare class RelRangePicker extends LitElement {
     private hoverDate;
     /** ISO date of the cell that owns the grid's single Tab stop (roving tabindex). */
     private focusedDate;
-    private triggerButton?;
+    /** Uncommitted typed text; null → the input shows the committed range. */
+    private inputText;
+    /** Parse/range error message for the typed text (cleared on next input). */
+    private inputError;
+    private triggerInput?;
     private popoverEl?;
     private backdropEl?;
     static styles: lit.CSSResult;
@@ -622,6 +1119,31 @@ declare class RelRangePicker extends LitElement {
     private cancelPopover;
     private applySelection;
     private resetDraft;
+    private clearRange;
+    /**
+     * Parse "date → date" text into an ISO from/to pair, or null. Each side
+     * goes through rel-date-picker's parseDateInput, so ISO / numeric /
+     * month-name dates and the t / t±N shortcuts all work per side.
+     * Separators: "→", "..", spaced "-", or the word "to" ("t - t+7",
+     * "21/7 to 28/7"). A single date yields a one-day range. Reversed input
+     * is normalized (from ≤ to). dayFirst is hard-coded false because the
+     * displayed format is always MM/DD/YYYY.
+     */
+    private parseRangeText;
+    /**
+     * Parse and commit the typed text (Enter / blur). Invalid or out-of-range
+     * text keeps the field in an error state with the text preserved for
+     * correction; the committed range is untouched (Escape reverts the text).
+     */
+    private commitTypedValue;
+    private handleInputInput;
+    private handleInputKeydown;
+    /** Clicking anywhere on the field opens the panel (never closes). */
+    private handleFieldClick;
+    /** The calendar icon toggles the panel (previous trigger behavior). */
+    private handleIconClick;
+    /** Commit typed text when focus leaves the component entirely. */
+    private handleInputBlur;
     private getTriggerLabel;
     /** Formatted "MM/DD/YYYY → MM/DD/YYYY" (or single date / "") for the current committed `from`/`to`. */
     get displayLabel(): string;
@@ -635,6 +1157,8 @@ declare class RelRangePicker extends LitElement {
     private previousMonth;
     private nextMonth;
     private getMonthName;
+    private dayLabelFormatter;
+    private formatDayLabel;
     private getWeekdayLabels;
     private getCalendarDays;
     private handleDayClick;
@@ -659,22 +1183,38 @@ type ChipTone = "neutral" | "danger" | "warning" | "success" | "info";
 type ChipVariant = "fill" | "subtle";
 type ChipSize = "sm" | "md" | "lg";
 type ChipBorder = "default" | "rounded";
+/**
+ * Compact chip (Figma "Chip") for tags, filters and selected values: tone x variant
+ * colouring, optional leading icon / avatar / trailing icon, a remove control and
+ * opt-in drag-and-drop.
+ * @csspart base - The chip body (`.chip`) that carries size, tone, variant and border styling
+ * @csspart icon - The leading `<rel-icon>` (rendered only when `leading-icon` is set and no avatar)
+ * @csspart label - The label text
+ * @cssprop --rel-chip-focus-ring - Colour of the keyboard focus outline; default `var(--rel-border-focus)`
+ */
 declare class RelChip extends LitElement {
     static shadowRootOptions: ShadowRootInit;
+    /** Text shown in the chip; also its accessible name and the drag payload. */
     label: string;
+    /** Colour tone (Figma Tone): `neutral`, `danger`, `warning`, `success` or `info`. Combined with `variant`. */
     tone: ChipTone;
+    /** Emphasis (Figma Variant): `fill` = solid tone background, `subtle` = tinted background with tone-coloured text. */
     variant: ChipVariant;
+    /** Height scale (Figma Size): `sm` 24px / body-sm, `md` 28px / body-md, `lg` 32px / body-lg. Icon size follows (12 / 14 / 16px). */
     size: ChipSize;
+    /** Corner shape (Figma Border): `default` = 4px radius, `rounded` = fully rounded with 12px horizontal padding. */
     border: ChipBorder;
-    /** Icon name from the generated icon dictionary (e.g. "settings") — rendered via <rel-icon>. */
+    /** Icon name from the generated icon dictionary (e.g. "settings") — rendered via <rel-icon> before the label. Ignored when `avatar` is set. */
     leadingIcon?: string;
+    /** Icon name from the generated icon dictionary, rendered after the label. */
     trailingIcon?: string;
-    /** Initials text for the avatar (e.g. "JD"). Mutually exclusive with leadingIcon. */
+    /** Initials text for the avatar (e.g. "JD"), rendered as a `<rel-avatar type="text">` before the label. Mutually exclusive with leadingIcon (avatar wins). */
     avatar?: string;
+    /** Shows a remove (close) button after the label; clicking it sets `removed` and fires `removed`. */
     removable: boolean;
-    /** IMPORTANT: reflected so CSS + Angular can see it */
+    /** `true` once the chip has been removed — the host is hidden via `:host([removed])`. Reflected so CSS and Angular can see it; reset to `false` to show the chip again. */
     removed: boolean;
-    /** Opt-in native drag-and-drop — reflects the Figma "Dragged" state automatically during a real drag gesture. */
+    /** Opt-in native drag-and-drop: sets `draggable="true"` on the host, shows the Figma "Dragged" state during a real drag gesture, and makes Left/Right arrow keys fire `chip-move`. */
     draggableChip: boolean;
     /** Reflected so CSS can target the Figma "Dragged" visual state. Driven automatically by dragstart/dragend when draggableChip is set. */
     private dragging;
@@ -698,16 +1238,42 @@ declare global {
     }
 }
 
+/** Canonical surface names (audit 12). */
+type ContainerSurface = "default" | "elevated" | "transparent";
+/** @deprecated since 1.4.7 — use `ContainerSurface` / the `surface` prop. */
+type ContainerBackground = "light" | "white" | "none";
+/**
+ * Padded surface block (Figma "Container"): a full-width wrapper with a surface fill, a padding step and an optional shadow, used to group a section of content.
+ * @slot - Section content; slotted `h1`–`h4` get the headings-sm role and `p` the body-md role
+ * @csspart base - The padded surface `<div>` (same element as `container`)
+ * @csspart container - Alias of `base`, kept for existing `::part(container)` selectors
+ */
 declare class RelContainer extends LitElement {
+    /** Inner padding step: `sm` = spacing-xs, `md` = spacing-md, `lg` = spacing-xl, `xl` = spacing-2xl. */
     padding: "sm" | "md" | "lg" | "xl";
+    /** Adds the shadow-300 elevation box-shadow to the surface. */
     shadow: boolean;
-    background: "light" | "white" | "none";
+    /**
+     * Surface fill: default (page surface) | elevated (raised surface) |
+     * transparent. Takes precedence over the deprecated `background` prop.
+     */
+    surface?: ContainerSurface;
+    /** @deprecated Deprecated since 1.4.7 — use `surface` (white→default, light→elevated, none→transparent). */
+    background?: ContainerBackground;
+    /** Resolved surface: explicit `surface` wins, else mapped `background`, else "default". */
+    get resolvedSurface(): ContainerSurface;
+    willUpdate(changed: Map<string, unknown>): void;
     static styles: lit.CSSResult;
     private get classes();
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Thin separator rule that splits content horizontally or vertically. Use it between sections, list groups or toolbar clusters; do not use it as a spacer.
+ * @csspart base - The rendered rule (`role="separator"` div) — restyle thickness, colour or margin here.
+ */
 declare class RelDivider extends LitElement {
+    /** Axis of the rule: `horizontal` spans the full width with vertical margin; `vertical` is a full-height line with horizontal margin (the parent needs a defined height or a flex row). Mirrored to `aria-orientation` on the host. */
     orientation: "horizontal" | "vertical";
     static styles: lit.CSSResult;
     connectedCallback(): void;
@@ -715,6 +1281,11 @@ declare class RelDivider extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Layout helper used by `<rel-drawer>` for its footer: a right-aligned flex
+ * row with an 8px gap. Can also be used standalone for a matching actions row.
+ * @slot - Footer actions (typically `<rel-button>`s)
+ */
 declare class RelDrawerFooter extends LitElement {
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
@@ -727,19 +1298,51 @@ declare global {
 
 type DrawerSide = "bottom" | "left" | "right";
 type DrawerCloseReason = "backdrop" | "escape" | "drag" | "programmatic";
+/**
+ * Edge-anchored drawer (Figma "Drawer", 5699:6844): a panel that slides in
+ * from the bottom, left or right over a scrim, with an optional drag handle
+ * (bottom only), a title/description header, a scrollable body and a footer.
+ * @slot - Body content of the drawer
+ * @slot footer - Actions row; rendered inside a `<rel-drawer-footer>` (right-aligned, 8px gap)
+ * @csspart overlay - The full-viewport scrim behind the panel
+ * @csspart panel - The sliding panel (role="dialog")
+ * @csspart handle - The drag-to-close grab bar (bottom drawers only)
+ * @csspart header - Header block holding title, description and close button
+ * @csspart close-button - The "X" close button
+ * @csspart content - Scrollable body wrapper around the default slot
+ * @csspart footer - Footer wrapper around the `footer` slot
+ * @cssprop --rel-drawer-width - Panel width. Default `clamp(640px, 66vw, 952px)` for `side="bottom"`, `clamp(280px, 24vw, 420px)` for left/right. The `width` prop sets this on the panel and wins over a host value
+ * @cssprop --rel-drawer-height - Panel height for `side="bottom"`; default `clamp(360px, 49vh, 600px)`. Left/right drawers are always full height
+ * @cssprop --rel-drawer-transition-duration - Slide/scrim animation duration; default `0.3s`
+ * @cssprop --rel-drawer-transition-timing - Slide/scrim animation easing; default `cubic-bezier(0.32, 0.72, 0, 1)`
+ * @cssprop --rel-drawer-scrim-opacity - Opacity of the scrim while open; default `1`
+ */
 declare class RelDrawer extends LitElement {
+    /** Whether the drawer is shown. Toggle it to open/close; every change fires `rel-open-change`. */
     open: boolean;
+    /** Edge the panel slides in from. `bottom` is centred horizontally and supports the drag handle; `left`/`right` are full-height side panels. */
     side: DrawerSide;
+    /** When false the close button is hidden and backdrop clicks / Escape are ignored (drag-to-close still works). */
     dismissible: boolean;
+    /** Modal mode: renders the scrim, sets `role="dialog"` + `aria-modal`, traps Tab inside the panel and moves focus in on open. When false the panel is a `region` with no scrim and no focus trap. */
     modal: boolean;
+    /** Close when the scrim is clicked. Only effective while `dismissible` is true. */
     closeOnBackdrop: boolean;
+    /** Close on the Escape key. Only effective while `dismissible` is true. */
     closeOnEscape: boolean;
+    /** Show the grab bar above the header. Only rendered when `side="bottom"` and `draggable` is true. */
     showHandle: boolean;
+    /** Enable drag-to-close on the handle (pointer or touch). Bottom drawers only. */
     draggable: boolean;
+    /** Fraction (0–1) of the panel height the user must drag down before release closes the drawer; shorter drags snap back. */
     snapThreshold: number;
+    /** Written to the panel as the `--drawer-max-height` custom property (any CSS length). No built-in rule reads it yet; use `--rel-drawer-height` to size a bottom drawer. */
     maxHeight: string;
+    /** Explicit panel width (any CSS length). Empty by default, which uses the per-side `--rel-drawer-width` default. */
     width: string;
+    /** Heading text (rendered as an `<h2>`, linked via `aria-labelledby`). */
     title: string;
+    /** Supporting text under the title (linked via `aria-describedby`). */
     description: string;
     private isDragging;
     private dragOffset;
@@ -776,11 +1379,31 @@ declare global {
     }
 }
 
+/**
+ * Key-cap scale (Figma Kbd 6316:284): S 20 / M 24 / L 28px tall with
+ * label-sm / label-md / label-lg type. `sm` / `md` / `lg` are the original
+ * names; the full words are accepted as aliases (Trello 4).
+ */
+type KbdSize = "sm" | "md" | "lg" | "small" | "medium" | "large";
+/**
+ * Single key cap (Figma "Kbd", 6316:284) for showing a keyboard key or shortcut
+ * inline with text; the key label is the slotted content.
+ * @slot - The key label (e.g. `Ctrl`, `K`, `⌘`)
+ */
 declare class RelKbd extends LitElement {
-    size: "sm" | "md" | "lg";
+    /** Key-cap scale (Figma Size): `small` 20px tall / label-sm, `medium` 24px / label-md, `large` 28px / label-lg; 4px radius at every size. `sm` / `md` / `lg` are the legacy short spellings and stay accepted. */
+    size: KbdSize;
+    /** Fill / text contrast: `default` = elevated-1 background with label text; `muted` = elevated-2 background with placeholder-tone text for secondary shortcuts. Both are flat with a 1px border. */
     variant: "default" | "muted";
+    /**
+     * Fully rounded corners. Logs a one-time console notice when set.
+     * @deprecated The Kbd spec has a single 4px radius at every size (audit
+     * 16); `pill` is kept working as an alias but logs a one-time notice.
+     */
     pill: boolean;
+    /** Pressed look: border-strong stroke, 1px downward nudge and (muted variant) a darker fill. */
     inset: boolean;
+    protected willUpdate(changed: PropertyValues<this>): void;
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
 }
@@ -789,11 +1412,17 @@ declare class RelKbd extends LitElement {
  * entry in `items` with "+" separators between them. Slotted <rel-kbd>
  * children may be used instead of the items array.
  *
- * <rel-kbd-group .items=${["Ctrl", "Shift", "P"]} size="md"></rel-kbd-group>
+ * <rel-kbd-group .items=${["Ctrl", "Shift", "P"]} size="medium"></rel-kbd-group>
+ * @slot - Extra content rendered after the generated keys (e.g. hand-written `<rel-kbd>` children)
+ * @csspart item - Each generated `<rel-kbd>` key cap
+ * @csspart label - The `+` separator between generated keys
  */
 declare class RelKbdGroup extends LitElement {
+    /** Key labels to render, one `<rel-kbd>` each, joined by `+` separators. Set as a property or as a JSON array attribute (`items='["Ctrl","K"]'`). */
     items: string[];
-    size: "sm" | "md" | "lg";
+    /** Passed through to every generated <rel-kbd>: `small` / `medium` / `large` (legacy `sm` / `md` / `lg` still accepted). */
+    size: KbdSize;
+    /** Passed through to every generated <rel-kbd>: `default` or `muted`. */
     variant: "default" | "muted";
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
@@ -820,19 +1449,31 @@ interface Step {
     title: string;
     status: StepStatus;
 }
+/**
+ * Multi-step progress indicator (Figma "Stepper"): renders one focusable step per entry in `steps` — a circular indicator (number, check, dot or icon per `type`), a label and a connector line to the next step — in a row or a column.
+ * @csspart indicator - The 24px circle (8px for `type="dot"`) that holds the step number, check mark or icon.
+ * @csspart track - The 1px connector line from a step to the next one (not rendered on the last step).
+ * @csspart label - The step title text.
+ * @cssprop --rel-stepper-indicator-size - Indicator diameter (default 24px; `type="dot"` is fixed at 8px).
+ * @cssprop --rel-stepper-connector-length-lg - Connector length and step gap for `size="large"` in both orientations (default 86px).
+ * @cssprop --rel-stepper-connector-length-md - Connector length and step gap for `size="small"` in `orientation="horizontal"` (default 60px).
+ * @cssprop --rel-stepper-connector-length-sm - Connector length and step gap for `size="small"` in `orientation="vertical"` (default 42px).
+ */
 declare class RelStepper extends LitElement {
+    /** The steps in order, each `{ title: string; status: "done" | "progress" | "disabled" }`. Set as a property (or a JSON array attribute); the component never mutates it — update it from the `rel-step-change` handler. */
     steps: Step[];
+    /**
+     * Legacy label placement (attribute `textalign`): `below` (default) puts the label under the indicator, `right` puts it beside the indicator. Ignored whenever `label-placement` is set.
+     * @deprecated Deprecated alias of `label-placement`; use `label-placement="inverted"` instead of `textalign="below"` and `label-placement="centered"` instead of `textalign="right"`.
+     */
     textAlign: TextAlign;
+    /** Layout axis: `horizontal` (default) lays the steps out in a centred row; `vertical` stacks them. */
     orientation: Orientation;
+    /** `large` (default) or `small`: controls the label type (body-md vs body-sm) and the connector length / step gap (see the `--rel-stepper-connector-length-*` hooks). */
     size: StepperSize;
+    /** Figma "Type" axis — what the indicator shows: `default` (step number, check mark once done), `dot` (8px dot, no glyph), `number` (always the number) or `icon` (always the check mark). */
     type: StepperType;
-    /**
-     * Figma Typel axis: top = label top-aligned beside the indicator,
-     * centered = label vertically centered beside it, inverted = indicator above
-     * the label. When unset, the legacy textAlign prop drives the layout
-     * (below ≈ inverted, right ≈ centered). Note Figma marks Top+Horizontal
-     * as an unsupported combination.
-     */
+    /** Figma "Typel" axis — where the label sits: `top` (top-aligned beside the indicator), `centered` (vertically centred beside it) or `inverted` (indicator above the label). When unset, the deprecated `textAlign` prop drives the layout (`below` ≈ `inverted`, `right` ≈ `centered`). Figma marks Top + Horizontal as an unsupported combination. */
     labelPlacement?: LabelPlacement;
     static styles: lit.CSSResult;
     private isDone;
@@ -850,35 +1491,92 @@ interface RadioOption {
     label: string;
     supportingText?: string;
     disabled?: boolean;
+    /** rel-icon name rendered before the label (Figma Has Icon/Avatar, Type=Icon). */
+    icon?: string;
+    /** 1–2 initials rendered as a circular chip before the label (Type=Avatar).
+     *  Ignored when `icon` is also set. */
+    avatar?: string;
 }
+type RadioSize = "small" | "medium" | "large";
+type RadioDensity = "compact" | "comfortable";
+type RadioAlignment = "leading" | "trailing";
+/**
+ * Single-select radio group (Figma "Radio"): renders one native radio input per
+ * entry in `options`, with optional supporting text, icon or avatar prefix.
+ * @csspart base - The `role="radiogroup"` container that lays out the options
+ * @csspart label - The visible label text of each option
+ */
 declare class RelRadio extends LitElement {
+    /** The options to render, in order. Each entry is a `RadioOption` (`value`, `label`,
+     *  optional `supportingText`, `disabled`, `icon` or `avatar`). Set as a property
+     *  (`.options=`) or as a JSON attribute. */
     options: RadioOption[];
+    /** `name` given to every native radio input inside this element. It scopes native
+     *  radio-group behaviour (arrow-key movement, mutual exclusion) to this group, so give
+     *  each group on a page a distinct name. */
     name: string;
     /** Layout axis of the option list. `"vertical"` (default) stacks options in
      *  a column; `"horizontal"` lays them out in a wrapping row. */
     orientation: Orientation;
-    /** Control scale. `"medium"` (default) = 20px circle with body-lg labels;
-     *  `"small"` = 16px circle with body-md labels. */
-    size: "small" | "medium";
+    /** Control scale (Figma Size). `"medium"` (default, Figma M) = 20px control
+     *  with body-lg labels; `"large"` (Figma L) = 24px control with body-xl
+     *  labels; `"small"` (Figma S) = 20px control with body-md labels — S and M
+     *  share the control size in the spec, only typography steps down. */
+    size: RadioSize;
+    /** Supporting-text layout (Figma Density). `"compact"` (default) puts the
+     *  supporting text on its own line under the row, indented past the control;
+     *  `"comfortable"` stacks label + supporting text beside the control. */
+    density: RadioDensity;
+    /** Control position (Figma Layout). `"leading"` (default) renders the
+     *  control before the label; `"trailing"` pushes it to the far edge of the
+     *  row. Trailing has no compact layout in the spec, so it always renders
+     *  with comfortable density. Meant for vertical orientation — trailing
+     *  options stretch to the group's full width. */
+    alignment: RadioAlignment;
+    /** `value` of the currently selected option, or `null` when nothing is selected.
+     *  Set it to preselect an option; it is updated on every user selection. */
     selectedValue: string | null;
+    /** Disables every option (Figma State=Disabled: the whole group at 40% opacity).
+     *  Individual options can also be disabled via `RadioOption.disabled`. */
     disabled: boolean;
+    /** Error state (Figma State=Error): rings, dots and supporting text turn danger.
+     *  Applies to every option while nothing is selected, and only to the selected
+     *  option once a choice is made. Selection is still allowed. */
     error: boolean;
+    /** Message rendered under the group (live region) while `error` is set; hidden
+     *  when `error` is false or the text is empty. */
     errorMessage: string;
+    /** Accessible name for the radiogroup (it renders no visible group label). */
+    fieldAriaLabel?: string;
+    /** Value reported to the Angular forms bridge (`registerOnChange` callback) on each
+     *  change and compared by `writeValue`. Not used for rendering; read `selectedValue`
+     *  or the `rel-change` detail for the selected option. */
     value: string;
+    /** Set by the Angular forms bridge (`writeValue`) to whether the written form value
+     *  equals `value`. Not used for rendering — read `selectedValue` for the selection. */
     checked: boolean;
     private _onChange;
     private _onTouched;
     static styles: lit.CSSResult;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** Trailing has no compact layout in the spec — trailing wins. */
+    private get effectiveDensity();
     private onChange;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnChange(fn: (value: string) => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnTouched(fn: () => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     writeValue(value: string): void;
     private get hasSelection();
+    private renderPrefix;
     private renderOption;
     render(): lit_html.TemplateResult<1>;
 }
 
 type MenuType = "default" | "checkbox" | "arrow" | "select-option" | "fixed" | "fit";
+/** Figma ".Menu Item" Size: large (48px rows) | medium (40px) | small (32px). */
+type MenuSize = "large" | "medium" | "small";
 interface MenuItem {
     label: string;
     active?: boolean;
@@ -887,16 +1585,46 @@ interface MenuItem {
     submenu?: MenuItem[];
     open?: boolean;
 }
+/**
+ * Declarative menu-item placeholder. It renders nothing and `<rel-menu>` does not
+ * currently read slotted children — menus are built from the `items` property.
+ * Registered so markup can carry item metadata for future declarative support.
+ */
 declare class RelMenuItem extends LitElement {
+    /** Display text of the item. */
     label: string;
+    /** Value that identifies the item (not used by `rel-menu` today). */
     value: string;
+    /** Marks the item as non-interactive. */
     disabled: boolean;
+    /** `rel-icon` name to render before the label (not used by `rel-menu` today). */
     icon: string;
     createRenderRoot(): this;
     render(): lit_html.TemplateResult<1>;
 }
+/**
+ * Light-DOM menu (Figma "Menu", 6326:2931) driven by the `items` array: single-select
+ * rows, checkbox rows, radio-style select-option rows, or hover/keyboard submenus.
+ * @csspart list - The `role="menu"` root list (a light-DOM `[part="list"]` attribute)
+ * @csspart panel - A submenu flyout (`type="arrow"` only; light-DOM `[part="panel"]` attribute)
+ * @cssprop --rel-menu-width - Width of the menu when `type="fixed"`; default 300px
+ */
 declare class RelMenu extends LitElement {
+    /** Menu behaviour / width mode (Figma Type). `default` = single-select rows
+     *  (`rel-select`); `checkbox` = toggling rows with a checkbox (`rel-check`);
+     *  `select-option` = single-select rows with a radio control; `arrow` = rows whose
+     *  `submenu` opens a flyout (`rel-submenu-select`); `fixed` / `fit` behave like
+     *  `default` but size the menu to `--rel-menu-width` (300px) or to its content. */
     type: MenuType;
+    /**
+     * Row size (Figma ".Menu Item" Size, 6326:616): large = 48px rows with
+     * body-lg labels (Figma default), medium = 40px / body-md, small = 32px /
+     * body-sm. Added in 1.4.7; before that rows were a fixed 36px.
+     */
+    size: MenuSize;
+    /** The rows to render, in order. Each entry is a `MenuItem` (`label`, optional
+     *  `active`, `checked`, `disabled`, `submenu`, `open`). The array is copied on
+     *  assignment, so mutate and reassign it to update the menu. */
     items: MenuItem[];
     private focusedIndex;
     /** Index inside the open submenu that virtual focus sits on; -1 = main list. */
@@ -904,7 +1632,7 @@ declare class RelMenu extends LitElement {
     private _items;
     /** Stable id prefix for aria-activedescendant targets. */
     private menuId;
-    static readonly _css = "\n    :host {\n      color: var(--rel-text-default);\n      display: inline-block;\n    }\n\n    .rel-menu {\n      position: relative;\n      display: inline-block;\n      background: var(--rel-bg-neutral);\n      color: var(--rel-text-default);\n      border-radius: var(--rel-border-radius-md);\n      box-shadow: var(--rel-shadows-shadow-300);\n      min-width: 220px;\n      /* No vertical padding: items fill edge-to-edge so a first/last-item hover\n         reaches the menu's top/bottom. NOT overflow:hidden \u2014 that clips the\n         type=arrow flyout (position:absolute at left:100%). Instead the first\n         and last items carry the outer corner radius so hover backgrounds clip\n         to the rounded shape without any overflow. */\n      padding: 0;\n      outline: none;\n      overflow: visible;\n      font-family: var(--rel-body-lg-regular-font-family);\n      font-weight: var(--rel-body-lg-regular-font-weight);\n      font-size: var(--rel-body-lg-regular-font-size);\n      line-height: var(--rel-body-lg-regular-line-height);\n      letter-spacing: var(--rel-body-lg-regular-letter-spacing);\n    }\n\n    .rel-menu:focus-visible,\n    :host(:focus-visible) .rel-menu {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: 2px;\n    }\n\n    .rel-menu-item {\n      position: relative;\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-xs);\n      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);\n      line-height: var(--rel-body-sm-regular-line-height);\n      cursor: pointer;\n      transition: background 0.15s ease, color 0.15s ease;\n      user-select: none;\n    }\n\n    /* First/last items carry the menu's outer radius so their hover fill clips\n       to the rounded corners (replaces the removed overflow:hidden). */\n    .rel-menu > .rel-menu-item:first-child {\n      border-top-left-radius: var(--rel-border-radius-md);\n      border-top-right-radius: var(--rel-border-radius-md);\n    }\n\n    .rel-menu > .rel-menu-item:last-child {\n      border-bottom-left-radius: var(--rel-border-radius-md);\n      border-bottom-right-radius: var(--rel-border-radius-md);\n    }\n\n    .rel-menu-item:hover {\n      background: var(--rel-bg-neutral-elevated-1);\n    }\n\n    .rel-menu-item:active {\n      background: var(--rel-bg-neutral-elevated-1);\n    }\n\n    .rel-menu-item.active {\n      background: var(--rel-bg-neutral-elevated-2);\n      font-weight: var(--rel-body-lg-medium-font-weight);\n    }\n\n    .rel-menu-item.disabled {\n      background-color: transparent;\n      color: var(--rel-text-disabled);\n      /* Keep the item pointer-interactive so cursor:not-allowed actually\n         renders; clicks are already neutralised by the item.disabled guard in\n         onItemClick/onItemEnter. pointer-events:none here would make the row\n         transparent to the pointer and suppress the cursor. */\n      cursor: not-allowed;\n    }\n\n    /* [data-focused] (presence, not =\"true\"): the ?data-focused boolean\n       binding renders the attribute with an EMPTY value, so a =\"true\"\n       selector never matches. */\n    .rel-menu-item[data-focused] {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: -2px;\n    }\n\n    /* Width modes (Figma Type=Fixed / Type=Fit) */\n    .rel-menu.fixed {\n      width: var(--rel-menu-width, 300px);\n      min-width: 0;\n      box-sizing: border-box;\n    }\n\n    .rel-menu.fit {\n      min-width: 0;\n      width: max-content;\n    }\n\n    /* Checkbox (Type=Checkbox) / radio (Type=Select Option) rows render the real\n       rel-checkbox / rel-radio. pointer-events:none keeps the whole row the click\n       target so onItemClick stays the single source of truth. */\n    .menu-control {\n      pointer-events: none;\n      width: 100%;\n    }\n\n    .menu-label {\n      flex: 1 1 auto;\n    }\n\n    /* Submenu affordance \u2014 same rel-icon chevron the menubar uses. */\n    .submenu-chevron {\n      margin-left: auto;\n      display: inline-flex;\n      align-items: center;\n      opacity: 0.6;\n      pointer-events: none;\n    }\n\n    /* Shortcut / hint text (Figma body-sm-regular, caption tone) */\n    .menu-shortcut,\n    ::slotted([slot=\"shortcut\"]) {\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n      color: var(--rel-text-caption);\n      margin-left: auto;\n      padding-left: var(--rel-spacing-md);\n    }\n\n    \n    .rel-submenu {\n      border: 1px solid var(--rel-border-subtle);\n      position: absolute;\n      top: calc(-1 * var(--rel-spacing-3xs));\n      /* flush against the trigger (no gap) so moving the pointer into the flyout\n         never crosses a dead zone that would fire the trigger's mouseleave */\n      left: 100%;\n      min-width: 200px;\n      background: var(--rel-bg-neutral);\n      color: var(--rel-text-default);\n      border-radius: var(--rel-border-radius-md);\n      box-shadow: var(--rel-shadows-shadow-300);\n      /* padding:0 + overflow:hidden \u2014 safe here (a submenu has no further nested\n         flyout to clip) \u2014 so sub-item hovers fill fully and clip to the corners */\n      padding: 0;\n      overflow: hidden;\n      visibility: hidden;\n      pointer-events: none;\n      z-index: 20;\n    }\n\n    .rel-submenu.visible {\n      visibility: visible;\n      pointer-events: auto;\n    }\n\n    .rel-submenu .rel-menu-item {\n      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);\n    }\n  ";
+    static readonly _css = "\n    :host {\n      color: var(--rel-text-default);\n      display: inline-block;\n    }\n\n    .rel-menu {\n      position: relative;\n      display: inline-block;\n      background: var(--rel-bg-neutral);\n      color: var(--rel-text-default);\n      /* Audit 17: 8px (border-radius/sm), was 16px; Figma Menu (6326:2931) = shadow/md */\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-md);\n      min-width: 220px;\n      /* No vertical padding: items fill edge-to-edge so a first/last-item hover\n         reaches the menu's top/bottom. NOT overflow:hidden \u2014 that clips the\n         type=arrow flyout (position:absolute at left:100%). Instead the first\n         and last items carry the outer corner radius so hover backgrounds clip\n         to the rounded shape without any overflow. */\n      padding: 0;\n      outline: none;\n      overflow: visible;\n      font-family: var(--rel-body-lg-regular-font-family);\n      font-weight: var(--rel-body-lg-regular-font-weight);\n      font-size: var(--rel-body-lg-regular-font-size);\n      line-height: var(--rel-body-lg-regular-line-height);\n      letter-spacing: var(--rel-body-lg-regular-letter-spacing);\n    }\n\n    .rel-menu:focus-visible,\n    :host(:focus-visible) .rel-menu {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: 2px;\n    }\n\n    /* Rows follow Figma \".Menu Item\" (6326:616) per size:\n       Large  48px = pad 12/12 + body-lg (24 line-height)\n       Medium 40px = pad 8/12  + body-md (22)\n       Small  32px = pad 4/8   + body-sm (20)\n       (audit 17a \u2014 before 1.4.7 every row was 36px: pad 8/12 + a 20px line-height) */\n    .rel-menu-item {\n      position: relative;\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-md);\n      padding: var(--rel-spacing-sm) var(--rel-spacing-sm);\n      line-height: var(--rel-body-lg-regular-line-height);\n      min-height: 48px;\n      cursor: pointer;\n      transition: background 0.15s ease, color 0.15s ease;\n      user-select: none;\n      box-sizing: border-box;\n    }\n\n    /* Light-DOM component: :host never matches here, so size rules key off the\n       reflected attribute on the <rel-menu> element itself. */\n    rel-menu[size=\"medium\"] .rel-menu,\n    rel-menu[size=\"medium\"] .rel-submenu {\n      font-family: var(--rel-body-md-regular-font-family);\n      font-weight: var(--rel-body-md-regular-font-weight);\n      font-size: var(--rel-body-md-regular-font-size);\n      line-height: var(--rel-body-md-regular-line-height);\n      letter-spacing: var(--rel-body-md-regular-letter-spacing);\n    }\n\n    /* Figma Medium / Small frames are fixed at 40 / 32 (content sums to 38 / 28) */\n    rel-menu[size=\"medium\"] .rel-menu-item {\n      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);\n      line-height: var(--rel-body-md-regular-line-height);\n      min-height: 40px;\n    }\n\n    rel-menu[size=\"small\"] .rel-menu,\n    rel-menu[size=\"small\"] .rel-submenu {\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n    }\n\n    rel-menu[size=\"small\"] .rel-menu-item {\n      padding: var(--rel-spacing-2xs) var(--rel-spacing-xs);\n      line-height: var(--rel-body-sm-regular-line-height);\n      min-height: 32px;\n    }\n\n    /* First/last items carry the menu's outer radius so their hover fill clips\n       to the rounded corners (replaces the removed overflow:hidden). */\n    .rel-menu > .rel-menu-item:first-child {\n      border-top-left-radius: var(--rel-border-radius-sm);\n      border-top-right-radius: var(--rel-border-radius-sm);\n    }\n\n    .rel-menu > .rel-menu-item:last-child {\n      border-bottom-left-radius: var(--rel-border-radius-sm);\n      border-bottom-right-radius: var(--rel-border-radius-sm);\n    }\n\n    /* Figma states (6326:616): Hover = action overlay 0.05, Pressed = 0.10\n       (nearest token: overlay-pressed), Active/selected list row = the hover\n       overlay + medium label; Checkbox / Select Option rows keep no fill when\n       selected. Disabled = 40% opacity. (audit 17) */\n    .rel-menu-item:hover {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    .rel-menu-item:active {\n      background: var(--rel-action-overlay-pressed);\n    }\n\n    .rel-menu-item.active {\n      background: var(--rel-action-overlay-hover);\n      font-weight: var(--rel-body-lg-medium-font-weight);\n    }\n\n    .rel-menu.type-checkbox .rel-menu-item.active,\n    .rel-menu.type-select-option .rel-menu-item.active {\n      background: transparent;\n    }\n\n    .rel-menu.type-checkbox .rel-menu-item.active:hover,\n    .rel-menu.type-select-option .rel-menu-item.active:hover {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    .rel-menu-item.disabled {\n      background-color: transparent;\n      opacity: 0.4;\n      /* Keep the item pointer-interactive so cursor:not-allowed actually\n         renders; clicks are already neutralised by the item.disabled guard in\n         onItemClick/onItemEnter. pointer-events:none here would make the row\n         transparent to the pointer and suppress the cursor. */\n      cursor: not-allowed;\n    }\n\n    /* [data-focused] (presence, not =\"true\"): the ?data-focused boolean\n       binding renders the attribute with an EMPTY value, so a =\"true\"\n       selector never matches. */\n    .rel-menu-item[data-focused] {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: -2px;\n    }\n\n    /* Width modes (Figma Type=Fixed / Type=Fit) */\n    .rel-menu.fixed {\n      width: var(--rel-menu-width, 300px);\n      min-width: 0;\n      box-sizing: border-box;\n    }\n\n    .rel-menu.fit {\n      min-width: 0;\n      width: max-content;\n    }\n\n    /* Checkbox (Type=Checkbox) / radio (Type=Select Option) rows render the real\n       rel-checkbox / rel-radio. pointer-events:none keeps the whole row the click\n       target so onItemClick stays the single source of truth. */\n    .menu-control {\n      pointer-events: none;\n      width: 100%;\n    }\n\n    .menu-label {\n      flex: 1 1 auto;\n    }\n\n    /* Submenu affordance \u2014 same rel-icon chevron the menubar uses. */\n    .submenu-chevron {\n      margin-left: auto;\n      display: inline-flex;\n      align-items: center;\n      opacity: 0.6;\n      pointer-events: none;\n    }\n\n    /* Shortcut / hint text (Figma body-sm-regular, caption tone) */\n    .menu-shortcut,\n    ::slotted([slot=\"shortcut\"]) {\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n      color: var(--rel-text-caption);\n      margin-left: auto;\n      padding-left: var(--rel-spacing-md);\n    }\n\n    \n    .rel-submenu {\n      border: 1px solid var(--rel-border-subtle);\n      position: absolute;\n      top: calc(-1 * var(--rel-spacing-3xs));\n      /* flush against the trigger (no gap) so moving the pointer into the flyout\n         never crosses a dead zone that would fire the trigger's mouseleave */\n      left: 100%;\n      min-width: 200px;\n      background: var(--rel-bg-neutral);\n      color: var(--rel-text-default);\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-md);\n      /* padding:0 + overflow:hidden \u2014 safe here (a submenu has no further nested\n         flyout to clip) \u2014 so sub-item hovers fill fully and clip to the corners */\n      padding: 0;\n      overflow: hidden;\n      visibility: hidden;\n      pointer-events: none;\n      z-index: 20;\n    }\n\n    .rel-submenu.visible {\n      visibility: visible;\n      pointer-events: auto;\n    }\n\n    .rel-submenu .rel-menu-item {\n      padding: var(--rel-spacing-sm) var(--rel-spacing-sm);\n    }\n\n    rel-menu[size=\"medium\"] .rel-submenu .rel-menu-item {\n      padding: var(--rel-spacing-xs) var(--rel-spacing-sm);\n    }\n\n    rel-menu[size=\"small\"] .rel-submenu .rel-menu-item {\n      padding: var(--rel-spacing-2xs) var(--rel-spacing-xs);\n    }\n  ";
     createRenderRoot(): this;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -925,14 +1653,22 @@ declare class RelMenu extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/** Figma "Menu Bar" Type (8699:4): `fit` hugs the triggers, `fixed` spans the container. */
+type MenubarType = "fixed" | "fit";
+/**
+ * Horizontal application menubar (`role="menubar"`) that turns each child `<rel-menubar-menu>` into a trigger button with a dropdown panel of items, separators, submenus, checkbox items and radio groups; renders into light DOM (no slots or parts).
+ * @cssprop --rel-menubar-width - Width of the bar when `type="fixed"`; default 100%
+ * @cssprop --rel-menubar-panel-width - Width of the dropdown and submenu panels; default 300px
+ */
 declare class RelMenubar extends LitElement {
     /**
-     * Opt-in: actually BIND the keys declared via data-shortcut (e.g.
-     * data-shortcut="Ctrl+Z"), not just display them. "Ctrl" matches Cmd on
-     * Apple platforms when written as "Mod". Keystrokes originating in
-     * inputs/textareas/contenteditable are ignored.
+     * Opt-in: actually bind the keys declared via `data-shortcut` on items (e.g. `data-shortcut="Ctrl+Z"`) instead of only displaying them; a "Mod" token means Cmd on Apple platforms and Ctrl elsewhere, and keystrokes that originate in inputs, textareas or contenteditable regions are ignored.
      */
     bindShortcuts: boolean;
+    /**
+     * Width mode (Figma "Menu Bar" Type, 8699:4): `fit` sizes the bar to its triggers, `fixed` stretches it across its container (override the stretched width with `--rel-menubar-width`). Added in 1.4.8; the default stays `fit`, which is how the bar has always rendered.
+     */
+    type: MenubarType;
     private menus;
     private openMenuIndex;
     private focusedTriggerIndex;
@@ -945,7 +1681,7 @@ declare class RelMenubar extends LitElement {
     /** Stable id prefix for aria-activedescendant targets (light DOM, so ids
      *  must be unique per menubar instance on the page). */
     private menubarId;
-    static readonly _css = "\n    /* This component renders into LIGHT DOM (createRenderRoot returns this), so\n       :host / <slot> don't work here \u2014 the raw <rel-menubar-menu> definitions\n       are data holders that must be hidden with a plain selector. Relying on the\n       global rel-menubar-menu.css is not enough: it can't cross a consumer's\n       shadow boundary AND it's a no-op in the tsup-built package (css:\"copy\"). */\n    rel-menubar {\n      color: var(--rel-text-default);\n      display: block;\n    }\n\n    rel-menubar-menu {\n      display: none;\n    }\n\n    .menubar-container {\n      display: flex;\n      align-items: stretch;\n      background: var(--rel-bg-surface-elevated);\n      border: var(--rel-stroke-sm) solid var(--rel-border-default);\n      border-radius: var(--rel-border-radius-sm);\n      overflow: hidden;\n      padding: 0;\n      gap: var(--rel-spacing-3xs);\n      height: 40px;\n      width: fit-content;\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n    }\n\n    .menubar-trigger {\n      display: flex;\n      align-items: center;\n      align-self: stretch;\n      height: 100%;\n      padding: 0 var(--rel-spacing-sm);\n      background: transparent;\n      border: none;\n      cursor: pointer;\n      font-family: inherit;\n      font-size: inherit;\n      color: var(--rel-text-label);\n      transition: background 0.15s ease;\n      user-select: none;\n      outline: none;\n    }\n\n    .menubar-trigger:hover,\n    .menubar-trigger.active {\n      background: var(--rel-bg-neutral-elevated-2);\n    }\n\n    .menubar-trigger:focus-visible {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: 2px;\n    }\n\n    .menubar-panel {\n      position: fixed;\n      min-width: 220px;\n      background: var(--rel-bg-surface);\n      border: var(--rel-stroke-sm) solid var(--rel-border-default);\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-shadow-300);\n      padding: 0;\n      overflow: hidden;\n      z-index: 1000;\n      display: none;\n    }\n\n    .menubar-panel.open {\n      display: block;\n    }\n\n    .menu-item {\n      position: relative;\n      display: flex;\n      align-items: center;\n      justify-content: space-between;\n      gap: var(--rel-spacing-sm);\n      padding: var(--rel-spacing-xs) var(--rel-spacing-md);\n      cursor: pointer;\n      transition: background 0.15s ease;\n      user-select: none;\n      color: var(--rel-text-label);\n      line-height: var(--rel-body-sm-regular-line-height);\n    }\n\n    .menu-item:hover,\n    .menu-item.focused {\n      background: var(--rel-bg-neutral-elevated-2);\n    }\n\n    .menu-item[data-disabled=\"true\"] {\n      opacity: 0.5;\n      cursor: not-allowed;\n    }\n\n    .menu-separator {\n      height: var(--rel-stroke-sm);\n      background: var(--rel-border-default);\n      margin: 0;\n      padding: 0;\n    }\n\n    rel-icon {\n      display: inline-flex;\n      pointer-events: none;\n    }\n\n    .menu-submenu-trigger {\n      position: relative;\n    }\n\n    .menu-submenu-trigger rel-icon {\n      opacity: 0.6;\n    }\n\n    .submenu-panel {\n      position: fixed;\n      min-width: 200px;\n      background: var(--rel-bg-surface);\n      border: var(--rel-stroke-sm) solid var(--rel-border-default);\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-shadow-300);\n      padding: 0;\n      overflow: hidden;\n      z-index: 1001;\n      display: none;\n    }\n\n    .submenu-panel.open {\n      display: block;\n    }\n\n    .menu-shortcut {\n      opacity: 0.6;\n      margin-left: auto;\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-3xs);\n      font-family: var(--rel-body-xs-regular-font-family);\n      font-weight: var(--rel-body-xs-regular-font-weight);\n      font-size: var(--rel-body-xs-regular-font-size);\n      line-height: var(--rel-body-xs-regular-line-height);\n      letter-spacing: var(--rel-body-xs-regular-letter-spacing);\n    }\n\n    .menubar-panel rel-checkbox {\n      display: block;\n      width: 100%;\n      padding: var(--rel-spacing-xs, 8px) var(--rel-spacing-md, 16px);\n      box-sizing: border-box;\n      cursor: pointer;\n    }\n  ";
+    static readonly _css = "\n    /* This component renders into LIGHT DOM (createRenderRoot returns this), so\n       :host / <slot> don't work here \u2014 the raw <rel-menubar-menu> definitions\n       are data holders that must be hidden with a plain selector. Relying on the\n       global rel-menubar-menu.css is not enough: it can't cross a consumer's\n       shadow boundary AND it's a no-op in the tsup-built package (css:\"copy\"). */\n    rel-menubar {\n      color: var(--rel-text-default);\n      display: block;\n      /* Figma Menu Bar / .Menu Bar Item (8699:4, 8698:13) label = body/lg.\n         Declared on the host, not on .menubar-container, so the position:fixed\n         panels \u2014 siblings of the container, not descendants \u2014 inherit it too. */\n      font-family: var(--rel-body-lg-regular-font-family);\n      font-weight: var(--rel-body-lg-regular-font-weight);\n      font-size: var(--rel-body-lg-regular-font-size);\n      line-height: var(--rel-body-lg-regular-line-height);\n      letter-spacing: var(--rel-body-lg-regular-letter-spacing);\n    }\n\n    rel-menubar-menu {\n      display: none;\n    }\n\n    /* Figma Menu Bar (8699:4): bg/fill/neutral/default on border-radius/sm,\n       clipping its children, gap spacing/none \u2014 no border and no shadow. */\n    .menubar-container {\n      display: flex;\n      align-items: stretch;\n      background: var(--rel-bg-neutral);\n      border-radius: var(--rel-border-radius-sm);\n      overflow: hidden;\n      padding: 0;\n      gap: 0;\n      min-height: 40px;\n      width: fit-content;\n    }\n\n    /* Type=Fit hugs its triggers (the default); Type=Fixed spans its container.\n       Light-DOM component: :host never matches, so these key off the reflected\n       attribute on the <rel-menubar> element itself. */\n    rel-menubar[type=\"fixed\"] .menubar-container {\n      width: var(--rel-menubar-width, 100%);\n    }\n\n    rel-menubar[type=\"fit\"] .menubar-container {\n      width: fit-content;\n    }\n\n    /* Figma .Menu Bar Item (8698:13): spacing/xs vertical + spacing/md\n       horizontal padding around a body/lg label = a 40px trigger. */\n    .menubar-trigger {\n      display: flex;\n      align-items: center;\n      justify-content: center;\n      align-self: stretch;\n      padding: var(--rel-spacing-xs) var(--rel-spacing-md);\n      background: transparent;\n      border: none;\n      cursor: pointer;\n      font: inherit;\n      color: var(--rel-text-default);\n      white-space: nowrap;\n      transition: background 0.15s ease;\n      user-select: none;\n      outline: none;\n    }\n\n    /* State=Hover / State=Pressed / State=Active / State=Disabled. Active (the\n       trigger whose menu is open) is the hover overlay plus a medium label \u2014\n       hence the .open class rather than .active, which would collide with the\n       :active pressed pseudo at equal specificity. */\n    .menubar-trigger:hover:not(.disabled) {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    .menubar-trigger:active:not(.disabled) {\n      background: var(--rel-action-overlay-pressed);\n    }\n\n    .menubar-trigger.open:not(.disabled) {\n      background: var(--rel-action-overlay-hover);\n      font-weight: var(--rel-body-lg-medium-font-weight);\n    }\n\n    .menubar-trigger.disabled {\n      color: var(--rel-text-disabled);\n      background: transparent;\n      cursor: not-allowed;\n    }\n\n    /* Inset ring: the container clips (overflow:hidden), so a positive\n       outline-offset would be cut off on the first and last trigger. */\n    .menubar-trigger:focus-visible {\n      outline: 2px solid var(--rel-border-focus);\n      outline-offset: -2px;\n    }\n\n    /* Figma pairs the Menu Bar with the Menu component (6326:2932) for the\n       panel each trigger opens: 300px, bg/fill/neutral/default, border\n       radius/sm, shadow/md, clipped \u2014 no border. */\n    .menubar-panel,\n    .submenu-panel {\n      position: fixed;\n      width: var(--rel-menubar-panel-width, 300px);\n      box-sizing: border-box;\n      background: var(--rel-bg-neutral);\n      border-radius: var(--rel-border-radius-sm);\n      box-shadow: var(--rel-shadows-md);\n      padding: 0;\n      overflow: hidden;\n      display: none;\n      outline: none;\n    }\n\n    .menubar-panel {\n      z-index: 1000;\n    }\n\n    .submenu-panel {\n      z-index: 1001;\n    }\n\n    .menubar-panel.open,\n    .submenu-panel.open {\n      display: block;\n    }\n\n    /* Rows follow Figma .Menu Item Large (6326:616): spacing/sm padding all\n       round on a body/lg label = 48px, with a border/neutral/subtle rule\n       between rows. The rule is an INSET shadow, not a border: Figma strokes\n       are drawn inside the 48px frame, so a real border-bottom would push\n       every row to 49px. */\n    .menu-item {\n      position: relative;\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-md);\n      padding: var(--rel-spacing-sm);\n      min-height: 48px;\n      box-sizing: border-box;\n      box-shadow: inset 0 calc(-1 * var(--rel-stroke-sm)) 0 var(--rel-border-subtle);\n      cursor: pointer;\n      transition: background 0.15s ease;\n      user-select: none;\n      color: var(--rel-text-default);\n      line-height: var(--rel-body-lg-regular-line-height);\n    }\n\n    .menu-label {\n      flex: 1 1 auto;\n    }\n\n    .menu-item:hover,\n    .menu-item.focused {\n      background: var(--rel-action-overlay-hover);\n    }\n\n    .menu-item:active {\n      background: var(--rel-action-overlay-pressed);\n    }\n\n    .menu-item[data-disabled=\"true\"] {\n      opacity: 0.4;\n      cursor: not-allowed;\n    }\n\n    .menu-separator {\n      height: var(--rel-stroke-sm);\n      background: var(--rel-border-default);\n      margin: 0;\n      padding: 0;\n    }\n\n    /* An explicit data-separator replaces the preceding row's subtle rule\n       instead of stacking a second line on top of it. */\n    .menu-item:has(+ .menu-separator),\n    .menubar-panel > rel-checkbox:has(+ .menu-separator),\n    .menubar-panel > rel-radio:has(+ .menu-separator) {\n      box-shadow: none;\n    }\n\n    rel-icon {\n      display: inline-flex;\n      pointer-events: none;\n    }\n\n    .menu-submenu-trigger {\n      position: relative;\n    }\n\n    /* Figma draws the 20px chevron at full contrast \u2014 no dimming. */\n    .submenu-chevron {\n      margin-left: auto;\n      display: inline-flex;\n      align-items: center;\n      pointer-events: none;\n    }\n\n    .menu-shortcut {\n      margin-left: auto;\n      padding-left: var(--rel-spacing-md);\n      display: flex;\n      align-items: center;\n      gap: var(--rel-spacing-3xs);\n      color: var(--rel-text-caption);\n      font-family: var(--rel-body-sm-regular-font-family);\n      font-weight: var(--rel-body-sm-regular-font-weight);\n      font-size: var(--rel-body-sm-regular-font-size);\n      line-height: var(--rel-body-sm-regular-line-height);\n      letter-spacing: var(--rel-body-sm-regular-letter-spacing);\n    }\n\n    /* Checkbox / radio rows are real rel-checkbox / rel-radio elements rendered\n       straight into the panel, so they carry the .Menu Item row box themselves. */\n    .menubar-panel > rel-checkbox,\n    .menubar-panel > rel-radio {\n      display: block;\n      width: 100%;\n      min-height: 48px;\n      padding: var(--rel-spacing-sm);\n      box-sizing: border-box;\n      box-shadow: inset 0 calc(-1 * var(--rel-stroke-sm)) 0 var(--rel-border-subtle);\n    }\n\n    .menubar-panel > rel-checkbox {\n      cursor: pointer;\n      transition: background 0.15s ease;\n    }\n\n    .menubar-panel > rel-checkbox:hover {\n      background: var(--rel-action-overlay-hover);\n    }\n  ";
     createRenderRoot(): this;
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -960,6 +1696,8 @@ declare class RelMenubar extends LitElement {
      *  openMenuIndex to -1, which used to drop focus to <body>.) */
     private closeAllMenusAndRefocusTrigger;
     private openMenu;
+    /** A disabled <rel-menubar-menu> keeps its trigger focusable but never opens. */
+    private isMenuDisabled;
     private handleTriggerClick;
     private handleTriggerMouseEnter;
     private handleTriggerKeyDown;
@@ -979,276 +1717,94 @@ declare class RelMenubar extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
-declare class RelMenubarMenu extends LitElement {
-    label: string;
-    createRenderRoot(): this;
-    render(): lit_html.TemplateResult<1>;
-}
-
-/**
- * @deprecated rel-navbar is deprecated and will be removed in a future release.
- * Use rel-topbar and its sub-components instead:
- * rel-topbar, rel-topbar-brand, rel-topbar-actions, rel-topbar-utilities,
- * rel-topbar-item, rel-topbar-dropdown, rel-topbar-dropdown-item
- */
-declare class RelNavbar extends LitElement {
-    constructor();
-    sticky: boolean;
-    device: "desktop" | "tablet" | "mobile";
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use a plain
- * `<a>`/logo markup inside the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarBrand extends LitElement {
-    src: string;
-    href: string;
-    label: string;
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-brand": RelTopbarBrand;
-    }
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use plain
- * `rel-button` elements inside the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarActions extends LitElement {
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-actions": RelTopbarActions;
-    }
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use plain
- * `rel-button` (icon variant) elements inside the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarUtilities extends LitElement {
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-utilities": RelTopbarUtilities;
-    }
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use `rel-drawer`
- * for the mobile nav panel in the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarMobilePanel extends LitElement {
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-mobile-panel": RelTopbarMobilePanel;
-    }
-}
-
 /**
- * @deprecated Part of the deprecated rel-topbar family. Use `rel-menu` or
- * `rel-popover` for nav dropdowns in the "Navbar" recipe at /docs/recipes/navbar.
+ * Declarative menu definition for `<rel-menubar>`: a hidden (`display: none`) light-DOM holder whose children (`data-item`, `data-separator`, `data-submenu`, `data-checkbox`, `data-radio-group`) the parent menubar reads and renders into a dropdown panel.
  */
-declare class RelTopbarDropdown extends LitElement {
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-dropdown": RelTopbarDropdown;
-    }
-}
-
-/**
- * @deprecated Part of the deprecated rel-topbar family. Use `rel-menu`'s
- * item slots or `rel-popover` content in the "Navbar" recipe at /docs/recipes/navbar.
- */
-declare class RelTopbarDropdownItem extends LitElement {
+declare class RelMenubarMenu extends LitElement {
+    /** Text of the trigger button the parent menubar renders for this menu. */
     label: string;
-    href: string;
-    active: boolean;
-    static styles: lit.CSSResult;
-    private _handleClick;
-    render(): lit_html.TemplateResult<1>;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        "rel-topbar-dropdown-item": RelTopbarDropdownItem;
-    }
-}
-
-type TopbarVariant = "customer" | "carrier";
-type TopbarForceLayout = "auto" | "desktop" | "tablet" | "mobile";
-/**
- * `rel-topbar` — Application-level top navigation / header shell.
- *
- * @deprecated This component's fixed slot structure, hardcoded breakpoint,
- * and built-in overflow logic are too rigid for most real layouts. Use the
- * "Navbar" recipe at /docs/recipes/navbar instead, composed from
- * rel-menu/rel-popover, rel-drawer, and rel-button. Still supported, but
- * will be removed in a future major version.
- *
- * Slots:
- *   brand        — Logo / wordmark region (left)
- *   (default)    — Primary nav items (rel-topbar-item elements)
- *   actions      — CTA / action buttons (customer) or dark-pill area (carrier)
- *   utilities    — Utility icon buttons (notifications, search, etc.)
- *   profile      — rel-topbar-profile tile
- *   mobile-panel — Collapsed nav panel shown when mobileOpen is true
- *
- * Events:
- *   rel-menu-toggle        — fired when hamburger is clicked  { open: boolean }
- *   rel-mobile-open-change — alias of rel-menu-toggle for convenience
- *   rel-nav-select         — bubbled from child rel-topbar-item  { value, label }
- */
-declare class RelTopbar extends LitElement {
-    /** Visual variant — affects action/profile region styling */
-    variant: TopbarVariant;
-    /** Whether the mobile nav panel is currently open */
-    mobileOpen: boolean;
-    /** Whether to render the hamburger / close toggle button */
-    showMenuToggle: boolean;
-    /** Reduce height to compact (48 px) mode */
-    compact: boolean;
-    /** Stick topbar to top of viewport while scrolling */
-    sticky: boolean;
     /**
-     * Override the responsive layout for demos / storybook.
-     * 'auto' respects CSS media queries.
+     * Renders this menu's trigger in the Figma State=Disabled style and stops it
+     * opening by pointer, keyboard or hover-switch. The trigger stays in the tab
+     * order and reachable with the arrow keys (`aria-disabled`, not the native
+     * `disabled` attribute), matching how disabled `data-item` rows behave.
      */
-    forceLayout: TopbarForceLayout;
-    private _overflowItems;
-    private _overflowCount;
-    private _overflowItemsData;
-    private _resizeObserver?;
-    private _resizeTimer?;
-    private _measuring;
-    private _lastNavWidth;
-    static styles: lit.CSSResult;
-    firstUpdated(): void;
-    disconnectedCallback(): void;
-    private _measureNav;
-    private onRouterSlotChange;
-    private get layoutClass();
-    private handleMenuToggle;
+    disabled: boolean;
+    createRenderRoot(): this;
     render(): lit_html.TemplateResult<1>;
 }
 
+/** What the cells accept — digits only, or digits + ASCII letters. */
+type OtpInputMode = "numeric" | "alphanumeric";
+/** @deprecated Use `OtpInputMode`. */
+type OtpType = OtpInputMode;
 /**
- * `rel-topbar-item` — A navigation item within rel-topbar.
- *
- * @deprecated Part of the deprecated rel-topbar family. Use the "Navbar" recipe at /docs/recipes/navbar, which composes nav links and
- * `rel-menu`/`rel-popover` dropdowns directly instead of a dedicated item component.
- *
- * Renders as an `<a>` when `href` is supplied, otherwise a `<button>`.
- *
- * Slots:
- *   (default)  — Label text / icon (overrides `label` property)
- *   prefix     — Icon/content before the label
- *   suffix     — Icon/content after the label (e.g. badge)
- *   dropdown   — Expandable panel content shown below the item
- *
- * Events:
- *   rel-select — fired when a non-disabled, non-expandable item is activated
- *   rel-toggle — fired when an expandable item is opened/closed  { open: boolean }
+ * Cell scale. Canonical values are the full words (shared field scale:
+ * small 32 / medium 40 / large 48); `sm` / `md` / `lg` are the original
+ * names and keep working as aliases.
  */
-declare class RelTopbarItem extends LitElement {
-    /** Accessible label — also shown as text when no default slot content */
-    label?: string;
-    /** Navigation href — renders an anchor element when set */
-    href?: string;
-    /** Marks this item as the current/active page */
-    active: boolean;
-    /** Prevents interaction */
-    disabled: boolean;
-    /** Shows a chevron and enables dropdown panel */
-    expandable: boolean;
-    /** Controlled open state of the dropdown panel */
-    open: boolean;
-    /** Optional string value forwarded in rel-select / rel-toggle events */
-    value?: string;
-    /** @internal tracks whether dropdown slot has content */
-    private _hasDropdown;
-    static styles: lit.CSSResult;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    private _handleOutsideClick;
-    private _handleDocKeydown;
-    private _setOpen;
-    private _handleTriggerClick;
-    private _routeSlots;
-    private _handleDropdownSlotChange;
-    render(): lit_html.TemplateResult<1>;
-}
-
-type TopbarProfileType = "avatar" | "carrier";
-type TopbarRewardTier = "gold" | "silver" | "platinum" | "bronze" | "regular";
+type OtpSize = "small" | "medium" | "large" | "sm" | "md" | "lg";
 /**
- * `rel-topbar-profile` — Profile / user tile for the topbar right region.
- *
- * @deprecated Part of the deprecated rel-topbar family. Compose `rel-avatar`
- * directly inside the "Navbar" recipe at /docs/recipes/navbar.
- *
- * type="avatar"   Customer avatar with initials circle + optional name/subtitle.
- * type="carrier"  Carrier reward tile with reward-tier badge + name/subtitle.
- */
-declare class RelTopbarProfile extends LitElement {
-    /** Visual mode */
-    type: TopbarProfileType;
-    /** One or two initials shown in the avatar circle */
-    initials?: string;
-    /** Primary display name */
-    name?: string;
-    /** Secondary line (role, plan, etc.) */
-    subtitle?: string;
-    /** Reward tier — only meaningful when type="carrier" */
-    reward: TopbarRewardTier;
-    /** Compact mode — avatar only, no text */
-    compact: boolean;
-    static styles: lit.CSSResult;
-    render(): lit_html.TemplateResult<1>;
-    private _renderAvatar;
-    private _avatarBg;
-    private _renderCarrier;
-}
-
-type OtpType = "numeric" | "alphanumeric";
+ * One-time-password input (Figma "OTP Input"): one single-character cell per position, with auto-advance, smart backspace, paste distribution and optional group separators.
+ * @csspart base - The `role="group"` root container (same element as `root`)
+ * @csspart root - Alias of `base`, kept for existing `::part(root)` selectors
+ * @csspart input - Each single-character cell input (same element as `cell`)
+ * @csspart cell - Alias of `input`, kept for existing `::part(cell)` selectors
+ * @csspart separator - The dash rendered between cell groups
+ * @csspart hidden-input - The hidden form input rendered when `name` is set
+ */
 declare class RelOtp extends LitElement {
+    /** The concatenated code (all cells joined). Set it to fill the cells programmatically; it never exceeds `length` characters. */
     value: string;
+    /** Total number of cells (characters in the code). */
     length: number;
+    /** Cells per visual group; a separator renders between groups. `0` (or `show-separator` off) renders one ungrouped row. */
     groupSize: number;
+    /** Placeholder character shown in every empty cell. */
     placeholder: string;
+    /**
+     * Accepted character set (Trello 5). Describes what the field ACCEPTS, not
+     * a semantic input type — hence the name. Explicitly set it wins over the
+     * deprecated `type`; unset (`""`, like the native `inputMode` accessor it
+     * shadows on the host), `type` (default `"numeric"`) applies. Note the
+     * lowercase `inputmode` prop is a different thing: the raw native keyboard
+     * hint forwarded to each cell.
+     */
+    inputMode: OtpInputMode | "";
+    /** @deprecated Deprecated alias of `inputMode` (attribute `input-mode`); use `input-mode` instead. Kept working in 1.x and logs a one-time console notice. */
     type: OtpType;
+    /** Renders the cells as `type="password"` so entered characters are masked. */
     mask: boolean;
+    /** Disables every cell and dims the control to 0.6 opacity. */
     disabled: boolean;
+    /** Makes every cell read-only: the value is shown but typing, paste and keyboard editing are ignored. */
     readonly: boolean;
+    /** Marks the first cell `required` for native form validation. */
     required: boolean;
+    /** When set, renders a hidden `<input name="…">` (part `hidden-input`) carrying `value` for native form submission. */
     name: string | null;
+    /** Reserved autocomplete hint. Currently every cell always renders `autocomplete="one-time-code"` regardless of this value. */
     autocomplete: string;
+    /** Raw native `inputmode` keyboard hint forwarded to every cell. Unset, it follows the accepted character set: `numeric` for numeric, `text` for alphanumeric. */
     inputmode: "numeric" | "text" | null;
+    /** Native `pattern` attribute forwarded to every cell (per-character regex for form validation). */
     pattern: string | null;
+    /** Accessible name of the whole group; defaults to "One-time password input". Each cell is additionally labelled "Digit/Character N of M". */
     ariaLabel: string | null;
+    /** Error styling (danger border on every cell) and `aria-invalid="true"`. */
     invalid: boolean;
+    /** Renders the dash separator between groups. Boolean attribute: its presence means true — set the property to `false` to hide separators. */
     showSeparator: boolean;
-    size: "sm" | "md" | "lg";
+    /** Cell size on the shared field scale (square, border-box): `small` 32px, `medium` 40px, `large` 48px (the Figma OTP Input cell). `sm` / `md` / `lg` are deprecated aliases of the full words. */
+    size: OtpSize;
     private cells;
     private hiddenInput?;
     private isUpdatingFromValue;
+    /** inputMode supersedes the deprecated type. */
+    private get mode();
     static styles: lit.CSSResult;
     connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
     updated(changedProperties: Map<string, any>): void;
     private initializeCells;
     private syncCellsFromValue;
@@ -1264,6 +1820,9 @@ declare class RelOtp extends LitElement {
     private handleFocus;
     private handleBlur;
     private focusCell;
+    /** Native `inputmode` hint for the cells (mobile keyboard). The lowercase
+     *  `inputmode` prop is a raw passthrough and wins; otherwise it follows
+     *  the accepted character set. */
     private getInputMode;
     private getAriaLabel;
     private getGroups;
@@ -1275,23 +1834,31 @@ declare global {
     }
 }
 
+/**
+ * Page navigation (Figma "Pagination"): prev/next ghost buttons with numbered pages, a compact "Page X of Y" readout, or a "1–10 of 50" item-range readout. Use it under tables and lists that load one page of results at a time; it never fetches data itself — listen for `rel-change`.
+ * @csspart base - The `role="navigation"` root of the extended layout (page buttons plus the optional "Viewing page" label).
+ * @csspart label - The `role="navigation"` root row of the count-text layout (item-range text plus prev/next nav).
+ */
 declare class RelPagination extends LitElement {
-    /** Layout type from Figma: extended (numbered pages), compact (prev/next + page text), count-text (range + nav) */
+    /** Figma "Type": `extended` = prev/next + numbered page buttons (auto-collapses to compact under 480px container width), `compact` = prev/next + "Page X of Y", `count-text` = "start–end of total" item range + prev/next around the current page number. */
     type: "extended" | "compact" | "count-text";
-    /** Controlled current page */
+    /** Controlled current page (1-based). When set, the element only emits `rel-change` and waits for the parent to update `page`; leave unset for uncontrolled behaviour. */
     page?: number;
-    /** Uncontrolled starting page */
+    /** Starting page for uncontrolled use (ignored when `page` is set). Attribute `defaultPage`, also read once as `default-page` on connect. */
     defaultPage: number;
-    /** Total number of pages */
+    /** Total number of pages. `0` (the default) lets `totalItems` / `perPage` compute the page count instead. Attribute `totalPages`, also read once as `total-pages` on connect. */
     totalPages: number;
-    /** Total items (used with perPage to auto-compute totalPages in count-text mode) */
+    /** Total item count; with `perPage` it computes the page count when `totalPages` is `0` and is the "of N" figure in the count-text readout. Attribute `totalItems`, also read once as `total-items` on connect. */
     totalItems: number;
-    /** Items per page (count-text mode) */
+    /** Items per page, used to compute the page count from `totalItems` and the "start–end" range in the count-text readout. Attribute `perPage`, also read once as `per-page` on connect. */
     perPage: number;
-    /** Show "Viewing page X of Y" label below extended pagination */
+    /** Shows a "Viewing page X of Y" caption under the extended layout (ignored by the other types). */
     showLabel: boolean;
+    /** Dims the whole control to 50% opacity, shows a `not-allowed` cursor and ignores every page change. */
     disabled: boolean;
+    /** Reserved for link-mode pagination. Currently accepted but not rendered: every page control is a `<button>`, so navigate in your `rel-change` handler instead. */
     hrefTemplate: string;
+    /** Accessible name of the `role="navigation"` landmark (attribute `ariaLabel`). Set it when a page contains more than one pagination control. */
     ariaLabel: string;
     private currentPage;
     static styles: lit.CSSResult;
@@ -1315,17 +1882,50 @@ declare class RelPagination extends LitElement {
 
 type SideType = "top" | "right" | "bottom" | "left";
 type AlignType = "start" | "center" | "end";
+/**
+ * Click-to-open floating panel anchored to a trigger (Figma "Popover"): the first child is the trigger, the `content` slot is the panel, which is promoted to the browser top layer and positioned in viewport coordinates.
+ * @slot - The trigger: the first slotted element toggles the panel on pointer down / Enter / Space and receives `aria-haspopup`, `aria-expanded` and `aria-controls` (a bare `<div>` / `<span>` also gets `tabindex="0"` and `role="button"`).
+ * @slot content - The panel body, usually a `<rel-popover-content>`; rendered inside the fixed, top-layer wrapper only while open.
+ * @csspart arrow - The 14×14 chevron box rendered on the panel edge facing the trigger when `arrow` is set (absent otherwise).
+ * @cssprop --rel-popover-arrow-bg - Fill of the `arrow` chevron (default `--rel-bg-neutral`, matching `<rel-popover-content>`).
+ * @cssprop --rel-popover-arrow-border - Stroke of the `arrow` chevron's two slanted edges (default `--rel-border-default`).
+ */
 declare class RelPopover extends LitElement {
+    /** Controlled open state. Leave unset for uncontrolled mode; once set (true or false) the component only emits `rel-open-change` and you must update `open` yourself. */
     open?: boolean;
+    /** Initial state in uncontrolled mode (attribute `defaultopen`); ignored when `open` is set. */
     defaultOpen: boolean;
+    /** Blocks trigger interaction and dims the host to 60% opacity; does not close an already-open panel. */
     disabled: boolean;
+    /** Which side of the trigger the panel opens on: `top`, `right`, `bottom` (default) or `left`. The panel is clamped 8px inside the viewport but never flips to another side. */
     side: SideType;
+    /** Alignment along the cross axis: `start` (left / top edge of the trigger), `center` (default) or `end` (right / bottom edge). */
     align: AlignType;
+    /** Gap between trigger and panel in pixels (attribute `sideoffset`, default 8). With `arrow` the effective gap is at least 13px. */
     sideOffset: number;
+    /** Extra shift along the alignment axis in pixels (attribute `alignoffset`, default 0); positive moves right / down. */
     alignOffset: number;
+    /** Keep Tab / Shift+Tab cycling inside the panel while open (attribute `trapfocus`); use for forms. */
     trapFocus: boolean;
+    /** Close on Escape (attribute `closeonescape`, default true; switch off via the property, e.g. `el.closeOnEscape = false`). */
     closeOnEscape: boolean;
+    /** Close on a pointer-down outside the trigger and panel (attribute `closeonoutsideclick`, default true; switch off via the property). Also lets another popover's opening dismiss this one. */
     closeOnOutsideClick: boolean;
+    /**
+     * Opt-in pointer (audit 23a): a 14×11 triangle on the panel edge that faces
+     * the trigger — the Figma Popover "Chevron" — following `side` and tracking
+     * the trigger's centre along the cross axis (clamped inside the panel).
+     * It is drawn with the panel's tokens (`--rel-popover-arrow-bg` /
+     * `--rel-popover-arrow-border`, defaulting to rel-popover-content's
+     * background and border). With the arrow on, the panel keeps at least the
+     * arrow's height plus 2px away from the trigger so the tip never overlaps
+     * it; larger `sideOffset` values still apply. Default off — existing
+     * popovers render exactly as before.
+     */
+    arrow: boolean;
+    /** Figma Popover (6338:563) chevron: 14 wide × 11 tall. */
+    private static readonly ARROW_WIDTH;
+    private static readonly ARROW_HEIGHT;
     private internalOpen;
     private contentStyle;
     private contentWrapper;
@@ -1344,6 +1944,15 @@ declare class RelPopover extends LitElement {
     private onHostKeyDown;
     private onOpen;
     private onClose;
+    /**
+     * Light-dismiss every other open popover that isn't an ancestor of this
+     * one (nested popovers keep their parent open). This is what the outside-
+     * pointerdown listener would do for a click on our trigger — except the
+     * trigger handler stops that pointerdown in the capture phase, and a
+     * keyboard (Enter/Space) or programmatic open never produces one at all.
+     * Honors each popover's own `closeOnOutsideClick` setting.
+     */
+    private closeOtherPopovers;
     private showNativePopover;
     private hideNativePopover;
     private addGlobalListeners;
@@ -1365,7 +1974,13 @@ declare global {
     }
 }
 
+/**
+ * Styled panel body for `<rel-popover>` (Figma "Popover" surface): neutral background, 1px border, 8px radius, shadow-300, max-width 400px, with heading / paragraph typography for slotted content. Place it in the popover's `content` slot; any other element works there too.
+ * @slot - The panel content (headings, paragraphs, form controls, buttons).
+ * @csspart content - The padded `role="dialog"` box that carries the surface, border, shadow and size padding.
+ */
 declare class RelPopoverContent extends LitElement {
+    /** Accessible name applied to the inner `role="dialog"` box (attribute `aria-label`); describe what the panel is for. */
     ariaLabel: string;
     /** Figma Size axis (S/M/L): panel padding 12/16/20px. */
     size: "sm" | "md" | "lg";
@@ -1374,13 +1989,23 @@ declare class RelPopoverContent extends LitElement {
 }
 
 type ProgressMode = "linear-determinate" | "linear-indeterminate" | "circular-determinate" | "circular-indeterminate";
+/**
+ * Progress indicator (Figma "Progress"): a linear bar or a circular ring, each either value-driven (determinate) or looping (indeterminate).
+ * @csspart track - The linear track `<div>` that carries `role="progressbar"` (linear modes only)
+ * @csspart indicator - The filled / sliding bar inside the linear track (linear modes only)
+ */
 declare class RelProgress extends LitElement {
+    /** Shape and behaviour: `linear-*` is a full-width 6px bar, `circular-*` a 48px ring; `*-determinate` fills to `value`, `*-indeterminate` loops an animation and ignores `value`. */
     mode: ProgressMode;
+    /** Completion percentage 0–100 for the determinate modes; out-of-range values are clamped before rendering and before `aria-valuenow`. */
     value: number;
+    /** Accessible name of the progressbar (not rendered visually); defaults to "Progress" for determinate and "Loading" for indeterminate modes. */
+    label: string;
     private radius;
     private circumference;
     static styles: lit.CSSResult;
     private get safeValue();
+    private get accessibleName();
     private renderLinearDeterminate;
     private renderLinearIndeterminate;
     private renderCircularDeterminate;
@@ -1388,7 +2013,14 @@ declare class RelProgress extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Flex container that lays out direct-child `<rel-resizable-panel>`s along one axis and lets the user drag or keyboard-nudge the `<rel-resizable-handle>` between two neighbours to trade percentage width/height between them.
+ * @slot - The panels and handles, as direct children in display order (panel, handle, panel, …)
+ * @fires rel-resize - Fired continuously while a handle is dragged. Detail: `{ direction, sizes: number[] }` with one percentage per panel.
+ * @fires rel-resize-end - Fired once when a drag ends (pointerup) and after every keyboard resize step. Detail: `{ direction, sizes: number[] }` with one percentage per panel.
+ */
 declare class RelResizableGroup extends LitElement {
+    /** Layout axis: `horizontal` places panels side by side and resizes widths, `vertical` stacks them and resizes heights; also pushed to every child handle's `orientation`. */
     direction: "horizontal" | "vertical";
     private panels;
     private handles;
@@ -1421,11 +2053,18 @@ declare global {
     }
 }
 
+/**
+ * One resizable region inside a `<rel-resizable-group>`: a padded, scrollable (`overflow: auto`) flex column whose size along the group axis is a percentage managed by the group.
+ * @slot - The panel's content; slotted `h1`–`h4` get the headings-md role
+ */
 declare class RelResizablePanel extends LitElement {
+    /** Initial size as a percentage of the group; panels without one share whatever is left of 100%, then all sizes are normalised to sum to 100. Attribute is `defaultsize`. */
     defaultSize?: number;
+    /** Smallest size (percentage) the panel can be resized to. Attribute is `minsize`. */
     minSize: number;
+    /** Largest size (percentage) the panel can be resized to. Attribute is `maxsize`. */
     maxSize: number;
-    /** Current computed size in percentage */
+    /** Current size as a percentage of the group (also written to the host's `flex-basis`); read-only — the parent group updates it on every resize. */
     currentSize: number;
     static styles: lit.CSSResult;
     render(): lit_html.TemplateResult<1>;
@@ -1436,16 +2075,21 @@ declare global {
     }
 }
 
+/**
+ * Focusable `role="separator"` splitter placed between two `<rel-resizable-panel>`s inside a `<rel-resizable-group>`; the group owns the drag and keyboard logic, the handle only renders the grab bar and exposes the split via ARIA.
+ */
 declare class RelResizableHandle extends LitElement {
+    /** Axis the handle separates: `horizontal` = 8px-wide vertical bar with `col-resize` cursor, `vertical` = 8px-tall bar with `row-resize`; set automatically from the parent group's `direction` on first render and mirrored to `aria-orientation`. */
     orientation: "horizontal" | "vertical";
-    /** Index of this handle in the parent group */
+    /** @internal Index of this handle in the parent group; assigned by the group on first render. */
     handleIndex: number;
-    /** Current split value (0-100) for aria-valuenow */
+    /** Current split of the two neighbouring panels as a percentage 0–100 (share held by the leading panel); read-only — the parent group updates it and mirrors it to `aria-valuenow`. */
     splitValue: number;
     static styles: lit.CSSResult;
     connectedCallback(): void;
     updated(changed: Map<string, unknown>): void;
     private updateAriaOrientation;
+    /** @internal Called by the parent group after every resize to store `splitValue` and write `aria-valuenow` / `aria-valuemin` / `aria-valuemax`. */
     updateAriaValue(value: number): void;
     render(): lit_html.TemplateResult<1>;
 }
@@ -1455,18 +2099,33 @@ declare global {
     }
 }
 
-type SegmentSize = "small" | "medium";
+type SegmentSize = "small" | "medium" | "large";
 type SegmentAlign = "left" | "middle" | "right";
 interface SegmentOption {
     label: string;
     value: string;
     disabled?: boolean;
+    /** `rel-icon` name rendered before the label (Figma "Left Icon"), sized 16 / 18 / 20 with the control. */
+    icon?: string;
 }
+/**
+ * Single-select segmented button group: renders one `<button role="radio">` per entry in `options` on a 2px-inset track (`role="radiogroup"`), with exactly one segment active at a time.
+ * @csspart base - The `role="radiogroup"` track that lays out the segments.
+ * @csspart option - Each segment's native `<button role="radio">`; the active one carries the `active` class and `aria-checked="true"`.
+ * @csspart icon - A segment's optional leading `rel-icon` element.
+ * @csspart label - The wrapper around a segment's label text.
+ */
 declare class RelSegmentedButton extends LitElement {
+    /** The segments in order, each `{ label: string; value: string; disabled?: boolean; icon?: string }`. Set as a property (or a JSON array attribute); a disabled entry is rendered but cannot be selected, and `icon` names a `rel-icon` drawn before the label. */
     options: SegmentOption[];
+    /** `value` of the currently selected segment. Updated by the component on click / arrow keys; set it to pre-select a segment (an unknown value selects nothing). */
     active: string;
+    /** Control height, matching the TextField ramp: `small` (32px — 28px segments, `action-md` 12px text, 16px icons), `medium` (default, 40px — 36px segments, `action-lg` 14px text, 18px icons) or `large` (48px — 44px segments, `action-xl` 16px text, 20px icons). */
     size: SegmentSize;
+    /** `justify-content` of the group's inline-flex container: `left` (default), `middle` or `right`. Only visible when the host is made wider than its content. */
     align: SegmentAlign;
+    /** Accessible name for the radiogroup (it renders no visible group label). */
+    fieldAriaLabel?: string;
     static styles: lit.CSSResult;
     private setActive;
     /** APG radio-group navigation: arrows move focus AND select, the group is
@@ -1489,8 +2148,47 @@ interface SelectOptionObject {
     icon?: string;
 }
 type SelectOption = string | SelectOptionObject;
+/**
+ * `<rel-select>` — combobox-style dropdown (Figma "Dropdown"): single- or multi-select
+ * with an optional in-panel search field and width-adaptive selection chips.
+ * @csspart label - The visible label above the trigger (default label style)
+ * @csspart trigger - The button that opens the panel; styled like a text field
+ * @csspart value - The value area inside the trigger (selected label, placeholder or chips)
+ * @csspart helper - The supporting / error text below the trigger
+ * @csspart panel - The dropdown listbox container (same node as `list`)
+ * @csspart list - Alias of `panel`
+ * @csspart input - The search input inside the panel
+ * @csspart option - A single-select option row
+ * @cssprop --rel-field-label-reserve - Height held for the absent label row under `labelStyle="none"` so the trigger 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).
+ * @cssprop --rel-select-bg - Background of the trigger, the floating label, the panel and its sticky header
+ * @cssprop --rel-select-bg-disabled - Trigger background when `state="disabled"`
+ * @cssprop --rel-select-border-default - Trigger border colour at rest
+ * @cssprop --rel-select-border-disabled - Trigger border colour when `state="disabled"`
+ * @cssprop --rel-select-border-focus - Trigger border colour on hover, while focused (where it also thickens to 2px) and while the panel is open
+ * @cssprop --rel-select-border-error - Trigger border colour when `state="error"`
+ * @cssprop --rel-select-radius - Trigger corner radius when `border="rounded"`
+ * @cssprop --rel-select-icon-color - Colour of the trigger icons, the search icon and option prefix icons
+ * @cssprop --rel-select-label-color - Colour of the static label and of the floated label
+ * @cssprop --rel-select-value-color - Colour of the selected value, the search text, option labels and the check mark
+ * @cssprop --rel-select-placeholder-color - Placeholder colour (trigger, resting floating label, search field, empty-list message)
+ * @cssprop --rel-select-placeholder-disabled-color - Placeholder colour when disabled
+ * @cssprop --rel-select-supporting-color - Supporting text colour (non-error)
+ * @cssprop --rel-select-menu-border - Panel border colour. The panel is borderless by design and only draws this on dark surfaces, where its shadow alone can't separate it from the page.
+ * @cssprop --rel-select-menu-radius - Panel corner radius
+ * @cssprop --rel-select-menu-shadow - Panel box-shadow
+ * @cssprop --rel-select-search-border - Border colour of the search field inside the panel
+ * @cssprop --rel-select-divider - Hairline under the search field, the Select-all row and every option row
+ * @cssprop --rel-select-option-hover - Background of the hovered / keyboard-highlighted / selected option and Select-all row
+ * @cssprop --rel-select-option-pressed - Background of an option row while it is being pressed
+ */
 declare class RelSelect extends LitElement {
+    /** Visible label. Rendered above the trigger (`labelStyle="default"`) or floating inside it; omitted under `labelStyle="none"`. */
     label: string;
+    /**
+     * Label presentation: `default` static label above the trigger; `floating` label
+     * rests in the value area and floats onto the border when focused, open or filled;
+     * `none` renders no label (supply `fieldAriaLabel` / `fieldAriaLabelledby`).
+     */
     labelStyle: SelectLabelStyle;
     /**
      * Accessible name for the trigger. Required when `labelStyle="none"`, since no
@@ -1499,21 +2197,46 @@ declare class RelSelect extends LitElement {
     fieldAriaLabel?: string;
     /** IDREF list of external element(s) naming the trigger. Wins over `fieldAriaLabel`. */
     fieldAriaLabelledby?: string;
+    /**
+     * Options to list. Each entry is a plain string (used as both value and label) or
+     * `{ value, label?, supportingText?, icon? }`; `icon` is a `rel-icon` name rendered
+     * before the label, `supportingText` shows only in multi-select rows.
+     */
     options: SelectOption[];
-    /** Enables multi-select: selected values render as removable chips and options as checkboxes. */
+    /** Enables multi-select: selected values render as removable chips, options as checkboxes, and a Select-all row appears in the panel. */
     multiple: boolean;
-    /** Selected value — single-select mode only. */
+    /** Selected option value in single-select mode. Ignored when `multiple` is set. */
     selected: string;
-    /** Selected values — multi-select mode only. */
+    /** Selected option values in multi-select mode. Reset to `[]` when `multiple` is turned off. */
     selectedValues: string[];
+    /** Visual / interaction state. `error` colours the border and supporting text and clears itself on the next selection; `disabled` blocks interaction and dims the whole field. */
     state: SelectState;
+    /** Helper line below the trigger; coloured as an error while `state="error"`. */
     supportingText: string;
+    /**
+     * `rel-icon` name shown before the supporting text (16px, 14px at `small`).
+     * Optional: the design pairs the helper line with an icon, but existing
+     * fields without one keep their current single-line look.
+     */
+    supportingIcon: string;
+    /**
+     * Field height — `small` 32px, `medium` 40px, `large` 48px. The whole component
+     * rides this one axis: label and supporting type, trigger padding, icons
+     * (20 / 18 / 16), selection chips, and the panel's rows, search field and
+     * checkboxes all scale with it.
+     */
     size: SelectSize;
+    /** Trigger corners: `rounded` applies the corner radius, `sharp` renders square corners. */
     border: SelectBorder;
+    /** `rel-icon` name rendered at the left edge of the trigger. */
     leftIcon: string;
+    /** `rel-icon` name replacing the default chevron at the right edge of the trigger. A custom icon does not rotate when the panel opens. */
     rightIcon: string;
+    /** Text shown in the trigger while nothing is selected. */
     placeholder: string;
+    /** Placeholder of the in-panel search field (the field is hidden when `noSearch` is set). */
     searchPlaceholder: string;
+    /** Label of the Select-all row shown at the top of the panel in multi-select mode. */
     selectAllLabel: string;
     /**
      * Optional hard cap on visible chips. By default (no cap) the visible
@@ -1539,7 +2262,7 @@ declare class RelSelect extends LitElement {
     private listboxEl;
     private valueEl;
     private chipsMeasureEl;
-    /** Must match the `gap` of .select-chips / .select-chips-measure. */
+    /** Must match the `gap` of .select-chips / .select-chips-measure (spacing/xs). */
     private static readonly CHIP_GAP;
     private chipResizeObserver?;
     private uniqueId;
@@ -1561,10 +2284,19 @@ declare class RelSelect extends LitElement {
     /** Options matching the current search text (substring match, case-insensitive). */
     private get filteredOptions();
     private get hasValue();
-    /** Icon size scales with the select's own size, matching the trigger. */
-    private get iconSize();
-    /** The search field uses "small" sizing for both small and medium select — only "large" select bumps it to "medium". */
-    private get searchIconSize();
+    /**
+     * Selection chips ramp with the field: rel-chip's sm / md / lg are already
+     * the 24 / 28 / 32 heights the spec asks the multi-select value area for.
+     */
+    private get chipSize();
+    /**
+     * Multi-select rows nest the checkbox one step down its own ramp: rel-checkbox
+     * sits a size above the rest of the system (its `large` is body/xl where a
+     * `large` field is body/lg), so large select -> medium checkbox and both
+     * medium and small select -> small checkbox, the smallest it ships. The rows
+     * still land on 48 / 40 / 32 through their own padding and min-height.
+     */
+    private get optionCheckboxSize();
     private get selectAllStatus();
     private addGlobalListeners;
     private removeGlobalListeners;
@@ -1609,12 +2341,24 @@ declare global {
 
 type SkeletonShape = "line" | "circle" | "block";
 type SkeletonAnimation = "pulse" | "shimmer" | "none";
+/**
+ * Loading placeholder: a neutral block, circle or stack of text lines that pulses or shimmers while real content loads, then hides itself once `loaded` is set. Use it in place of content whose size you already know; use a spinner for indeterminate waits.
+ * @csspart base - Each placeholder surface: the single block/circle, or every bar when `shape="line"`.
+ * @cssprop --rel-skeleton-color - Fill colour of the placeholder (defaults to the elevated-3 neutral background token).
+ * @cssprop --rel-skeleton-highlight - Lighter band that sweeps across the placeholder when `animation="shimmer"` (defaults to the elevated-2 neutral background token).
+ */
 declare class RelSkeleton extends LitElement {
+    /** Placeholder shape: `block` fills the host (min 16px tall), `circle` is a square-aspect disc sized by the host width, `line` renders `lines` 14px text bars with the last one at 65% width. */
     shape: SkeletonShape;
+    /** Number of text bars when `shape="line"` (minimum 1, 8px apart); ignored by the other shapes. */
     lines: number;
+    /** Any CSS width (e.g. `"240px"`, `"50%"`) applied to the host's inline style. Empty leaves the host at its natural block width. */
     width: string;
+    /** Any CSS height (e.g. `"120px"`) applied to the host's inline style. Not needed for `circle`, which derives its height from the width. */
     height: string;
+    /** Motion: `pulse` fades opacity between 100% and 40%, `shimmer` sweeps a highlight band left to right, `none` is static. Both animations are disabled under `prefers-reduced-motion: reduce`. */
     animation: SkeletonAnimation;
+    /** Set once the real content is ready: hides the skeleton (`display: none`) and removes its `role="status"` / "Loading" label. */
     loaded: boolean;
     protected updated(changed: Map<string, unknown>): void;
     static styles: lit.CSSResult;
@@ -1627,13 +2371,72 @@ declare global {
 }
 
 type ModalSide = "top" | "bottom" | "center";
+type ModalSize = "sm" | "md" | "lg" | "xl" | "fullscreen";
+/**
+ * `"default"` — the body is a free-form slot (24px padding, your own layout).
+ * `"text"` — the Figma Modal Sheet "Text" slot: a message-only modal whose body
+ * is plain copy (16px vertical / 20px horizontal padding, body-lg type) under
+ * the header divider. Additive, opt-in (audit 20c).
+ */
+type ModalVariant = "default" | "text";
+/**
+ * Modal sheet dialog (Figma "Modal Sheet", 8171:3412) — a centred, top- or
+ * bottom-anchored panel over a scrim with a title/description header, a
+ * scrollable body, an optional footer and a loading state. Lives in the
+ * `rel-sheet` folder and is exported as `RelModal`.
+ * @slot - Body content of the modal
+ * @slot header - Extra header content rendered under the title/description (e.g. a stepper or tabs)
+ * @slot footer - Actions row (right-aligned, 8px gap); the footer only renders when this slot has content
+ * @csspart overlay - The full-viewport scrim behind the panel
+ * @csspart panel - The dialog panel (role="dialog")
+ * @csspart header - Header row holding title, description, header slot and close button
+ * @csspart close-button - The "X" close button
+ * @csspart content - Scrollable body wrapper around the default slot
+ * @csspart footer - Footer wrapper around the `footer` slot
+ * @csspart loading - Spinner overlay shown while `loading` is set
+ * @cssprop --rel-modal-width - Panel width; overrides the `size` scale (md default `clamp(360px, 49vw, 708px)`, sm `min(400px, 100vw - 32px)`, lg `min(900px, 100vw - 48px)`, xl `min(1140px, 100vw - 48px)`). Ignored by `fullscreen` and by the responsive collapse below 480px
+ * @cssprop --rel-modal-transition-duration - Open/close animation duration; default `0.3s`
+ * @cssprop --rel-modal-transition-timing - Open/close animation easing; default `cubic-bezier(0.32, 0.72, 0, 1)`
+ */
 declare class RelModal extends LitElement {
+    /** Whether the modal is shown. Toggle it to open/close; every change fires `rel-open-change`. */
     open: boolean;
+    /** Where the panel is anchored: `bottom` (48px above the bottom edge, slides up), `top` (48px below the top edge, slides down) or `center` (fades and scales in). Below 480px with `breakpoint="responsive"` every side collapses to a full-width bottom sheet. */
     side: ModalSide;
+    /** Heading text (rendered as an `<h2>`, linked via `aria-labelledby`). The `title` attribute is stripped from the host after it is read so no native tooltip appears. */
     title: string;
+    /** Supporting text under the title (linked via `aria-describedby`). */
     description: string;
+    /** Alias for `description`; rendered only when `description` is empty. */
+    subtitle: string;
+    /** Coarse dismissal switch. When false the close button is hidden and backdrop clicks / Escape are ignored regardless of the granular `close-on-*` / `show-close-button` props. */
     dismissible: boolean;
+    /** Modal mode: renders the scrim, sets `role="dialog"` + `aria-modal`, traps Tab inside the panel and moves focus in on open. When false the panel is a `region` with no scrim and no focus trap. */
     modal: boolean;
+    /** Panel width scale. `md` matches the Figma Modal Sheet width; `fullscreen` covers the viewport. */
+    size: ModalSize;
+    /** Body treatment — see `ModalVariant`. `"text"` styles the default slot as
+     *  the Figma "Text" message slot; the header (and its divider) render as
+     *  usual above it. Default rendering is unchanged. */
+    variant: ModalVariant;
+    /** Close when the scrim is clicked. Only effective while `dismissible` is true; ignored while `disabled` or `loading`. */
+    closeOnBackdropClick: boolean;
+    /** Close on the Escape key. Only effective while `dismissible` is true; ignored while `disabled`. */
+    closeOnEscape: boolean;
+    /** Render the "X" close button in the header. Only effective while `dismissible` is true. */
+    showCloseButton: boolean;
+    /** Move focus into the panel when opened (modal mode only). */
+    autoFocus: boolean;
+    /** Return focus to the opener when closed. */
+    restoreFocus: boolean;
+    /** When false, the body no longer scrolls internally — tall content clips at the panel's max height. */
+    scrollable: boolean;
+    /** Shows a spinner overlay and blocks all interaction inside the panel. */
+    loading: boolean;
+    /** Blocks user-initiated closes (X / backdrop / Escape) and footer actions. */
+    disabled: boolean;
+    /** Stacking order of the whole modal (backdrop + panel). */
+    zIndex: number;
     /**
      * Figma "Breakpoint" axis. responsive (default) collapses to a full-width
      * bottom sheet below 480px; web keeps the fixed desktop panel at every size.
@@ -1670,20 +2473,46 @@ declare global {
  */
 type SliderType = "continuous" | "discrete" | "default" | "range";
 type TrackStyle = "solid" | "dotted";
+/**
+ * Slider (Figma "Slider", 6417:1340): a pill track with a stroked round thumb,
+ * optional value tooltip, discrete tick marks and a dual-thumb range mode.
+ * Built on native `<input type="range">` so keyboard and assistive-technology
+ * behaviour come for free.
+ * @csspart track - The rail behind the thumb (the filled portion has no part)
+ * @csspart thumb - The round grab handle (one per thumb in range mode)
+ * @csspart tooltip - The value bubble + chevron above each thumb (only while `showBubble` is on)
+ * @cssprop --rel-slider-track-height - Rail thickness; 6 / 8 / 10px for size sm / md / lg
+ * @cssprop --rel-slider-thumb-size - Thumb diameter; 16 / 20 / 24px for size sm / md / lg
+ * @cssprop --rel-slider-thumb-stroke - Width of the hover / pressed / focus ring around the thumb; default 6px
+ * @cssprop --rel-slider-thumb-halo-color - Colour of the keyboard-focus ring; default `var(--rel-border-default)`
+ * @cssprop --rel-slider-tick-size - Tick-mark diameter in discrete mode; 4 / 5 / 6px for size sm / md / lg
+ * @cssprop --rel-slider-bubble-radius - Corner radius of the value bubble; 8px for size sm, otherwise 10px
+ */
 declare class RelSlider extends LitElement {
+    /** Slider mode: `continuous` (or its alias `default`) accepts any integer value, `discrete` snaps to `step` and draws tick marks, `range` shows two thumbs bounding `value`…`valueEnd`. */
     type: SliderType;
     /** Figma Size axis (S/M/L): scales track, thumb and ticks. */
     size: "sm" | "md" | "lg";
+    /** Lowest selectable value. */
     min: number;
+    /** Highest selectable value. */
     max: number;
+    /** Increment between values. In `discrete` mode it also spaces the tick marks; in `continuous` mode the native input always moves in steps of 1. */
     step: number;
+    /** Disables interaction and dims the track, thumb and ticks; the tooltip is hidden. */
     disabled: boolean;
+    /** Style of the filled part of the track: `solid` or a `dotted` pattern. */
     track: TrackStyle;
+    /** Print the numeric value under every tick mark. Only has an effect in `discrete` mode. */
     showTickLabels: boolean;
+    /** Show the value tooltip above the thumb(s). */
     showBubble: boolean;
+    /** Current value (the lower value in `range` mode). */
     value: number;
     /** Upper value when type="range" (attribute value-end). */
     valueEnd: number;
+    /** Accessible name for the native range input. In `range` mode it is suffixed with " minimum" / " maximum" per thumb; without it the two thumbs read "Minimum value" / "Maximum value" and a single slider has no name. */
+    fieldAriaLabel?: string;
     private ticks;
     private _onChange;
     private _onTouched;
@@ -1706,8 +2535,11 @@ declare class RelSlider extends LitElement {
     private getTickLeftPct;
     private isTickActive;
     private onInput;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnChange(fn: (value: number) => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnTouched(fn: () => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     writeValue(value: number): void;
     private updateActiveWidth;
     private renderThumbContainer;
@@ -1717,16 +2549,42 @@ declare class RelSlider extends LitElement {
 }
 
 type SnackbarLines = "single" | "double";
+/** Canonical semantic tones (Figma "Tone"): neutral | success | warning | destructive. */
+type SnackbarTone = "neutral" | "success" | "warning" | "destructive";
+/** Deprecated spellings: "default" → neutral; "error" | "danger" | "critical" → destructive. */
+type SnackbarToneAlias = "default" | "error" | "danger" | "critical";
+type SnackbarToneInput = SnackbarTone | SnackbarToneAlias;
+/** @deprecated since 1.4.7 — use `SnackbarToneInput`. */
 type SnackbarType = "default" | "success" | "error" | "warning";
+/**
+ * Snackbar (Figma "Snackbar"): a dark, elevated message bar with an optional tone accent and leading status icon, an optional action button and a close icon, shown via `show` and auto-dismissed after `duration` milliseconds. It is not positioned — place it (fixed or in-flow) yourself. Use it for brief feedback with a single follow-up action ("Undo", "Retry"); use `rel-alert` for persistent messages.
+ * @csspart label - The message text container
+ * @csspart action - The action button; rendered only when `action` is set
+ * @csspart close-button - The close icon button; rendered while `iconclose` is true
+ */
 declare class RelSnackbar extends LitElement {
+    /** Message text. Announced to screen readers through the shared live-region announcer when the snackbar is shown and whenever it changes while shown. The default is a placeholder — always set it. */
     message: string;
+    /** Label of the optional action button (Figma trailing button, Static / Small); omitted when unset. Clicking it fires `actionClick` and then dismisses the snackbar. */
     action?: string;
+    /** Doubles the auto-dismiss delay (`duration * 2`) so the user has time to read and use the action button. Pair it with `lines="double"` for the Figma Type=Longer Action layout. */
     longerAction: boolean;
+    /** Shows the trailing close icon button. Defaults to true; because it is a Lit boolean, `iconclose="false"` is still true — set the property to `false` from script to hide the button. */
     iconClose: boolean;
+    /** Layout: `"single"` (default) puts the message and the actions on one row; `"double"` stacks the message above the actions, which align to the end (Figma Type=Longer Action). */
     lines: SnackbarLines;
+    /** Auto-dismiss delay in milliseconds (doubled by `longerAction`), started when `show` becomes true and restarted when `duration` or `longerAction` changes while shown. `0` (or a negative value) disables auto-dismiss. */
     duration: number;
-    type: SnackbarType;
+    /**
+     * Semantic tone (Figma "Tone"): `"neutral"` (default: no accent, no icon) | `"success"` | `"warning"` | `"destructive"` — the status tones add a 4px left accent and a leading icon (check-circle / warning / error) in the tone colour. `"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.
+     */
+    tone?: SnackbarToneInput;
+    /** @deprecated 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. */
+    type?: SnackbarToneInput;
+    /** Whether the snackbar is visible. Set it to true to show the snackbar and start the auto-dismiss timer; it is set back to false by the close icon, the action button and the timer. There is no open/close method — toggle this property. */
     show: boolean;
+    /** Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"neutral"` / `"destructive"`. */
+    get resolvedTone(): SnackbarTone;
     private visible;
     private _dismissTimer;
     static styles: lit.CSSResult;
@@ -1742,18 +2600,40 @@ declare class RelSnackbar extends LitElement {
     render(): lit_html.TemplateResult<1>;
 }
 
+/**
+ * Toggle switch (Figma "Switch", 5917:1174, Type=Line): a 44×20 control with a
+ * thin 10px track and a 20px handle that slides 20px. Wraps a native checkbox
+ * with `role="switch"`, so keyboard and screen-reader behaviour are native.
+ * @csspart base - The `<label>` wrapper around the hidden input and the track
+ * @csspart track - The thin rail; the handle is its `::before` pseudo-element
+ * @cssprop --rel-switch-track-width - Overall control width; default 44px
+ * @cssprop --rel-switch-track-height - Overall control height; default 20px
+ * @cssprop --rel-switch-thumb-size - Handle diameter; default 20px (the handle always travels 20px)
+ * @cssprop --rel-switch-track - Rail colour; default `var(--rel-bg-neutral-elevated-2)`
+ * @cssprop --rel-switch-knob-on - Handle colour when checked; default `var(--rel-bg-neutral-inverse-2)`
+ * @cssprop --rel-switch-knob-off - Handle colour when unchecked; default `var(--rel-text-static-light)`
+ * @cssprop --rel-switch-disabled - Handle colour while disabled; default `var(--rel-bg-neutral-elevated-1)`
+ */
 declare class RelSwitch extends LitElement {
+    /** Whether the switch is on. Set it to control the state programmatically; user toggles update it and fire `rel-change`. */
     checked: boolean;
+    /** Disables interaction, dims the control to 50% and removes the handle shadow. */
     disabled: boolean;
+    /** Arbitrary string echoed in the `rel-change` event detail — useful when one handler serves several switches. */
     value: string;
+    /** Accessible name for the native input. Without it the switch has no label of its own, so pair it with a visible `<label>` or set this. */
+    fieldAriaLabel?: string;
     private _onChange;
     private _onTouched;
     private isFocused;
     private isPressed;
     static styles: lit.CSSResult;
     private toggle;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnChange(fn: (value: boolean) => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     registerOnTouched(fn: () => void): void;
+    /** @internal Angular ControlValueAccessor bridge. */
     writeValue(checked: boolean): void;
     private handleFocus;
     private handleBlur;
@@ -1768,20 +2648,54 @@ interface TabItem {
     badgeDot?: boolean;
     disabled?: boolean;
 }
+/**
+ * Tab-strip scale. `sm` / `md` / `lg` are the original names; the full words
+ * `small` / `medium` / `large` are accepted as aliases (Trello 4). Each step
+ * is an explicit item height — 32 / 40 / 48px (Figma Tab Item S/M/L).
+ */
+type TabSize = "sm" | "md" | "lg" | "small" | "medium" | "large";
+/**
+ * Declarative tab definition for `<rel-tab>`. Renders nothing itself — place
+ * it in the parent's `items` slot and the parent reads its properties.
+ */
 declare class RelTabItem extends LitElement {
+    /** Text shown on the tab. */
     label: string;
+    /** Optional identifier for the tab. `<rel-tab>` does not read it; look it up from the item at `event.detail` when handling `rel-tab-change`. */
     value: string;
+    /** Count shown in a small badge after the label; `0` hides the badge. */
     badge: number;
     /** Shows a small dot instead of a numbered badge — takes precedence over `badge`. */
     badgeDot: boolean;
+    /** Greys the tab out and skips it in click, arrow-key and Home/End navigation. */
     disabled: boolean;
     render(): lit_html.TemplateResult<1>;
 }
+/**
+ * Underline tab strip (Figma "Tab Item", 6473:1075) with roving-tabindex
+ * keyboard navigation, optional count/dot badges and a single shared tabpanel
+ * below the strip. Tabs come either from the `tabs` array or from slotted
+ * `<rel-tab-item>` elements.
+ * @slot items - `<rel-tab-item>` definitions; when present they take precedence over the `tabs` array
+ * @slot - Content of the single tabpanel rendered under the strip (always visible — swap it yourself on `rel-tab-change`)
+ * @csspart list - The `role="tablist"` row
+ * @csspart item - Each `role="tab"` element
+ * @csspart label - The text span inside each tab
+ * @cssprop --rel-tab-active-color - Underline colour of the active tab; default `var(--rel-bg-brand)`
+ * @cssprop --rel-tab-underline-height - Thickness of the active underline; default 3px
+ * @cssprop --rel-tab-text-default - Label colour of the active tab; default `var(--rel-text-default)`
+ * @cssprop --rel-tab-text-hover - Label colour while hovering an enabled tab; default `var(--rel-text-label)`
+ * @cssprop --rel-tab-text-disabled - Label colour of a disabled tab; default `var(--rel-text-disabled)`
+ * @cssprop --rel-tab-hover-color - Background of an inactive tab on hover; default `var(--rel-bg-neutral-elevated-1)`
+ */
 declare class RelTab extends LitElement {
+    /** Tab definitions as `{ label, badge?, badgeDot?, disabled? }` objects — normally set as a property (as an attribute it must be a JSON string). Assign a new array to update; mutating in place does not re-render. Ignored when `<rel-tab-item>` children are slotted into `items`. */
     tabs: TabItem[];
+    /** Zero-based index of the selected tab. Set it to switch tabs programmatically (no event is fired for programmatic changes). */
     activeIndex: number;
-    /** Tab size — styled via :host([size]) rules. */
-    size: "sm" | "md" | "lg";
+    /** Tab size — styled via :host([size]) rules. Explicit item heights
+     *  32 / 40 / 48px (audit 34); `small|medium|large` alias `sm|md|lg`. */
+    size: TabSize;
     private _tabItems;
     /** Stable id prefix linking tabs to the shared tabpanel. */
     private tabsId;
@@ -1810,14 +2724,31 @@ declare class RelTab extends LitElement {
  * V1.0, node 8301:3771): fixed panel widths 220/250/280 by size, full-bleed
  * columns with 1px dividers, neutral selected state, and a Now / Cancel / OK
  * footer whose buttons are always size S.
+ *
+ * @csspart base - Outer wrapper; carries the size / error / readonly classes
+ * @csspart label - The field label above the trigger
+ * @csspart trigger - The field box that anchors the panel (wraps the text input and the icons)
+ * @csspart value - The editable text input showing the formatted time
+ * @csspart icon - The trailing clock icon
+ * @csspart panel - The popover panel (`role="dialog"`)
+ * @csspart shortcuts - The typed-shortcut chip row at the top of the panel (N → Now)
+ * @csspart option - Each hour / minute / second / AM-PM entry button
+ * @csspart footer - The Now / Cancel / OK row
+ * @csspart helper - The helper / error text live region under the field
+ * @fires rel-focus - Fired when the text input receives focus. No detail.
  */
 declare class RelTimePicker extends LitElement {
     /** Committed time, 24-hour "HH:mm" or "HH:mm:ss" (e.g. "09:30", "17:05:30"). */
     value: string | null;
+    /** Placeholder shown in the field while no value is committed and nothing is typed. */
     placeholder: string;
+    /** Field label rendered above the trigger; also the input's accessible name (unset → "Select time"). */
     label: string | null;
+    /** Disables the field (0.6 opacity, no pointer events); the panel cannot open. */
     disabled: boolean;
+    /** Renders the `*` mark after the label and sets `aria-required`; not enforced by the component. */
     required: boolean;
+    /** Shows the value but blocks typing and opening the panel. */
     readonly: boolean;
     /** Display format of the trigger text and hour column. Value stays 24-hour. */
     format: "12h" | "24h";
@@ -1829,23 +2760,42 @@ declare class RelTimePicker extends LitElement {
     minTime: string | null;
     /** Latest selectable time, "HH:mm" (inclusive). */
     maxTime: string | null;
+    /** Whether the panel is open. Settable from outside; opening resets the draft from `value` (programmatic changes do not fire `rel-open-change`). */
     open: boolean;
+    /** Shows a clear (×) button inside the field while a value is set; clearing commits `null`. */
     clearable: boolean;
+    /** Error styling (danger border, `aria-invalid`) and shows `errorMessage` below the field. */
     error: boolean;
     /** Alias for `error` (requested-API compat); either flag applies error styling. */
     invalid: boolean;
+    /** Text shown below the field while `error` / `invalid` is set (falls back to the typed-entry parse error, then `helperText`). */
     errorMessage?: string;
+    /** Assistive text shown below the field when not in error. */
     helperText?: string;
+    /** When set, renders a hidden `<input name="…">` carrying `value` for native form submission. */
     name?: string;
+    /** Trigger height on the shared field scale — small 32 / medium 40 / large 48px border-box; also sets the panel width (220 / 250 / 280px) and option row height (32 / 36 / 40px). Small lowers the trigger min-width from 160 to 128px. */
     size: "small" | "medium" | "large";
+    /** Visual style; only `"outlined"` exists today. */
     variant: "outlined";
+    /** Fills the parent width (the host is inline-block with intrinsic width otherwise). The attribute is lowercase `fullwidth`. */
     fullWidth: boolean;
     private draftHour;
     private draftMinute;
     private draftSecond;
-    /** Panel opens above the field when there is no viewport space below. */
-    private openUp;
+    /** Uncommitted typed text; null → the input shows the committed value. */
+    private inputText;
+    /** Parse/range error message for the typed text (cleared on next input). */
+    private inputError;
+    /**
+     * Whether the next popover open should move focus into the columns.
+     * Icon-click / ArrowDown / external `open` do (previous behavior); opening
+     * by clicking into the text input must NOT, or typing would be impossible.
+     */
+    private focusPanelOnOpen;
+    private triggerInput?;
     private triggerButton?;
+    private popoverElement?;
     private columnsElement?;
     static styles: lit.CSSResult;
     connectedCallback(): void;
@@ -1853,8 +2803,12 @@ declare class RelTimePicker extends LitElement {
     private handleClickOutside;
     private handleEscapeKey;
     updated(changedProperties: Map<string, any>): void;
-    /** Open upward when the panel doesn't fit below but does fit above. */
-    private updatePanelPlacement;
+    private showTopLayer;
+    private hideTopLayer;
+    private onReposition;
+    private updatePopoverPosition;
+    /** Focus the selected (or first enabled) option in the columns. */
+    private focusPanelSelection;
     private parseTime;
     private formatValue;
     private formatDisplay;
@@ -1880,9 +2834,19 @@ declare class RelTimePicker extends LitElement {
     /** Close discarding the draft (Cancel / Escape / outside click). */
     private cancelPopover;
     private applySelection;
+    /** Commit a time: set value, reset typed text/error, fire rel-change. */
+    private commitTime;
     /** Set the draft to the current time, snapped to the minute step and range. */
     private selectNow;
     private clearValue;
+    /**
+     * Parse and commit the typed text (Enter / blur). Invalid or out-of-range
+     * text keeps the field in an error state with the text preserved for
+     * correction; the committed value is untouched (Escape reverts the text).
+     */
+    private commitTypedValue;
+    /** "Now", committed directly (N shortcut / popover chip), clamped to range. */
+    private applyNowShortcut;
     private selectHour;
     private selectMinute;
     private selectSecond;
@@ -1894,7 +2858,16 @@ declare class RelTimePicker extends LitElement {
      */
     private scrollOptionInColumn;
     private scrollColumnsToSelection;
-    private handleTriggerKeydown;
+    private handleInputInput;
+    private handleInputKeydown;
+    /** Clicking anywhere on the field opens the popover, keeping focus typed-in. */
+    private handleFieldClick;
+    /** The clock icon toggles the popover with the previous focus behavior. */
+    private handleIconClick;
+    /** Commit typed text when focus leaves the component entirely. */
+    private handleInputBlur;
+    /** N inside the panel (columns/footer focus) applies Now directly. */
+    private handlePanelKeydown;
     /**
      * Column navigation: Up/Down move within the column (and select), Left/Right
      * jump between columns, Home/End go to the first/last option, Enter applies.
@@ -1909,19 +2882,47 @@ declare global {
     }
 }
 
+/** Canonical semantic tones. */
+type ToastTone = "default" | "destructive";
+/** Deprecated tone spellings, all mapped to "destructive". */
+type ToastToneAlias = "error" | "danger" | "critical";
+type ToastToneInput = ToastTone | ToastToneAlias;
+/** @deprecated since 1.4.7 — use `ToastToneInput`. */
 type ToastType = "default" | "error";
+/**
+ * Transient bottom-centre notification: a fixed-position dark pill with a message, an optional action button and a dismiss button, shown via `show` / `open()` and hidden again after `duration` milliseconds. Use it for brief, non-blocking confirmations; use `rel-alert` for persistent messages.
+ * @csspart base - The `role="status"` toast container that carries the tone class
+ * @csspart label - The message text span
+ * @csspart action - The action button; rendered only when `actionlabel` is set
+ * @csspart close-button - The dismiss (✕) button
+ * @cssprop --rel-toast-z - `z-index` of the fixed host (default `9000`); raise it when a modal or drawer layer covers the toast
+ * @cssprop --rel-z-toast - Deprecated alias of `--rel-toast-z`, still read as its fallback
+ */
 declare class RelToast extends LitElement {
+    /** Text of the toast. It is also announced to screen readers through the shared live-region announcer each time `show` becomes true. */
     message: string;
-    type: ToastType;
+    /**
+     * 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?: ToastToneInput;
+    /** @deprecated 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?: ToastToneInput;
+    /** Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"default"`; deprecated aliases are resolved to `"destructive"`. */
+    get resolvedTone(): ToastTone;
+    /** 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. */
     actionLabel?: string;
+    /** 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. */
     duration: number;
+    /** 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. */
     show: boolean;
     private visible;
     private _dismissTimer;
     static styles: lit.CSSResult;
     willUpdate(changed: Map<string, unknown>): void;
     disconnectedCallback(): void;
+    /** Shows the toast: sets `show = true`, which starts the auto-dismiss timer and announces `message`. */
     open(): void;
+    /** Hides the toast, clears the auto-dismiss timer and fires `dismissed`. It fires `dismissed` even when the toast was already hidden. */
     close(): void;
     private handleActionClick;
     render(): lit_html.TemplateResult<1>;
@@ -1929,11 +2930,20 @@ declare class RelToast extends LitElement {
 
 type TooltipPosition = "above" | "below" | "left" | "right";
 type TooltipType = "single-line" | "multi-line";
+/**
+ * Hover/focus tooltip (Figma "Tooltip"): wraps a trigger element and shows a short inverse-coloured text bubble above, below, left or right of it. Use it for supplementary hints on icons and truncated labels only — the text is not reachable on touch and must never be the only place critical information lives.
+ * @slot - The trigger element (one focusable element such as a button or icon button). It receives `aria-describedby` pointing at the bubble.
+ * @csspart panel - The tooltip bubble (`role="tooltip"`): background, padding, radius, shadow and max-width.
+ * @csspart indicator - The triangular tail pointing at the trigger, rendered only when `show-tail` is set.
+ */
 declare class RelTooltip extends LitElement {
+    /** Plain-text content of the bubble. Empty text still renders an (empty) bubble on hover, so always set it. */
     text: string;
+    /** 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: TooltipPosition;
+    /** Renders the triangular tail (`indicator` part) on the bubble's edge facing the trigger. */
     showTail: boolean;
-    /** Figma "Type": single-line stays on one line; multi-line wraps at a max width. */
+    /** Figma "Type": `single-line` keeps the text on one line and sizes to content; `multi-line` wraps inside a 220px max-width bubble. */
     type: TooltipType;
     private uniqueId;
     static styles: lit.CSSResult;
@@ -2010,21 +3020,22 @@ interface UploadState {
  * `<rel-upload-actions>` so they can sit in `<rel-modal>`'s footer slot and
  * stay pinned while this body scrolls.
  *
- * Emits (bubbling + composed):
- *   - `rel-files-added`  — `{ added: UploadFile[], rejected: UploadRejection[] }`
- *   - `rel-invalid`      — `{ rejected: UploadRejection[] }`
- *   - `rel-change`       — selection changed; `{ files: UploadFile[] }`
- *   - `rel-remove`       — row removed; `{ id, file }`
- *   - `rel-upload`       — Upload pressed; `{ files: UploadFile[] }`
- *   - `rel-retry`        — Retry pressed; `{ files: UploadFile[] }`
- *   - `rel-cancel`       — Cancel pressed
- *   - `rel-progress`     — `{ id, progress, loaded, total }`
- *   - `rel-file-complete`— `{ id, file }`
- *   - `rel-file-error`   — `{ id, file, error }`
- *   - `rel-complete`     — batch settled; `{ succeeded, failed }`
- *   - `rel-state`        — derived snapshot changed; `detail: UploadState`
+ * All events bubble and are composed.
  *
  * @element rel-upload
+ * @fires rel-files-added - Fired after files are picked or dropped and validated. Detail: `{ added: UploadFile[], rejected: UploadRejection[] }`.
+ * @fires rel-invalid - Fired just before `rel-files-added` when at least one picked file fails `accept` / `max-size`. Detail: `{ rejected: UploadRejection[] }`.
+ * @fires rel-change - Fired whenever the file list changes (files added, a row removed, `reset()`). Detail: `{ files: UploadFile[] }`.
+ * @fires rel-remove - Fired when a row is removed via its delete button or `removeFile()`. Detail: `{ id: string, file?: File }`.
+ * @fires rel-upload - Fired when Upload is pressed (or `upload()` is called) with the rows still `ready`; in controlled mode the app performs the transfer. Detail: `{ files: UploadFile[] }`.
+ * @fires rel-retry - Fired when Retry re-queues the retryable failed rows. Detail: `{ files: UploadFile[] }`.
+ * @fires rel-cancel - Fired when Cancel is pressed (or `cancel()` is called); in-flight transfers are aborted, the list is kept. No detail.
+ * @fires rel-progress - Fired on every progress tick in self-driving mode. Detail: `{ id: string, progress: number (0–100), loaded: number, total: number }` (bytes).
+ * @fires rel-file-complete - Fired when one file finishes uploading in self-driving mode. Detail: `{ id: string, file: File }`.
+ * @fires rel-file-error - Fired when one file's `uploader` rejects in self-driving mode. Detail: `{ id: string, file: File, error: string }`.
+ * @fires rel-complete - Fired when the whole self-driving batch settles without being cancelled. Detail: `{ succeeded: UploadFile[], failed: UploadFile[] }`.
+ * @fires rel-state - Fired when the derived `state` snapshot changes (and once after connecting). Detail: `UploadState`.
+ * @cssprop --rel-upload-browse-hover-bg - Background of the Browse button on hover; falls back to `--rel-action-neutral-outline-hover`, then `--rel-bg-surface-elevated`
  */
 declare class RelUpload extends LitElement {
     /** Comma-separated accept list, e.g. ".pdf,.png,.jpg" or "image/*". */
@@ -2046,7 +3057,7 @@ declare class RelUpload extends LitElement {
      * component also maintains it itself as files are added and removed.
      */
     files: UploadFile[];
-    /** Supply to run uploads internally. See {@link Uploader}. */
+    /** Supply an `Uploader` `(file, { file, signal, onProgress }) => Promise<void>` to switch to self-driving mode: the component runs the batch itself with `concurrency`, progress, the delay alert, abort and retry. Unset (default) the component only emits intents. */
     uploader?: Uploader;
     /** Max files transferred at once in self-driving mode. */
     concurrency: number;
@@ -2058,6 +3069,8 @@ declare class RelUpload extends LitElement {
     private aborter?;
     private delayTimer?;
     private lastSignature;
+    private lastHeading;
+    private lastAlertText;
     static styles: lit.CSSResult;
     /**
      * Aggregate state. Read-only; corresponds to the Figma modal variants.
@@ -2075,6 +3088,7 @@ declare class RelUpload extends LitElement {
      * rather than re-queueing it blindly.
      */
     private get retryable();
+    /** Whether the primary action is enabled: not disabled, nothing in flight, and either `ready` rows exist or (in the failed phase) at least one failed row can be retried. */
     get canUpload(): boolean;
     /** Footer button label — "Upload", "Upload 3 files" or "Retry upload". */
     get primaryLabel(): string;
@@ -2150,6 +3164,9 @@ declare global {
  * specific `<rel-upload>` by id when a container holds more than one.
  *
  * @element rel-upload-actions
+ * @csspart base - The right-aligned flex row holding the buttons
+ * @csspart cancel - The secondary Cancel `rel-button` (absent when `no-cancel` is set)
+ * @csspart primary - The primary Upload / Retry `rel-button`
  */
 declare class RelUploadActions extends LitElement {
     /** Id of the `<rel-upload>` to control. Omit to auto-discover a sibling. */
@@ -2238,8 +3255,7 @@ declare class FocusTrap {
  *
  * Shortcut strings are written as "+"-joined tokens, e.g. "mod+b",
  * "ctrl+shift+p", "escape". The "mod" token means Cmd on Apple platforms
- * and Ctrl everywhere else (this is the pattern rel-sidebar's Ctrl/Cmd+B
- * toggle established). Matching is case-insensitive.
+ * and Ctrl everywhere else. Matching is case-insensitive.
  */
 type ShortcutHandler = (e: KeyboardEvent) => void;
 interface ParsedShortcut {
@@ -2282,4 +3298,25 @@ declare function bindShortcut(shortcut: string, handler: ShortcutHandler, option
  */
 declare function formatShortcutParts(shortcut: string): string[];
 
-export { type AutocompleteFilter, type AutocompleteItem, type AutocompleteSearchFn, type BindShortcutOptions, type BreadcrumbItem, type ButtonTone, type ButtonVariant, type ChipBorder, type ChipSize, type ChipTone, type ChipVariant, type DrawerCloseReason, type DrawerSide, type FieldLabelStyle, FocusTrap, type LabelPlacement, type MenuItem, type MenuType, type ModalSide, type Orientation, type OtpType, type ProgressMode, type RadioOption, RelAccordion, RelAlert, RelAutocomplete, RelAvatar, RelBadge, RelBreadcrumbs, RelButton, RelCalendar, RelCard, RelCardMedia, RelCarousel, RelCheckbox, RelChip, RelContainer, RelDatePicker, RelDivider, RelDrawer, RelDrawerFooter, RelKbd, RelKbdGroup, RelLayout, RelMenu, RelMenuItem, RelMenubar, RelMenubarMenu, RelModal, RelNavbar, RelOtp, RelPagination, RelPopover, RelPopoverContent, RelProgress, RelRadio, RelRangePicker, RelResizableGroup, RelResizableHandle, RelResizablePanel, RelSegmentedButton, RelSelect, RelSkeleton, RelSlider, RelSnackbar, RelStepper, RelSwitch, RelTab, RelTabItem, RelTextfield, RelTimePicker, RelToast, RelTooltip, RelTopbar, RelTopbarActions, RelTopbarBrand, RelTopbarDropdown, RelTopbarDropdownItem, RelTopbarItem, RelTopbarMobilePanel, RelTopbarProfile, RelTopbarUtilities, RelUpload, RelUploadActions, type SegmentAlign, type SegmentOption, type SegmentSize, type SelectBorder, type SelectLabelStyle, type SelectOption, type SelectOptionObject, type SelectSize, type SelectState, type ShortcutHandler, type SkeletonAnimation, type SkeletonShape, type SliderType, type SnackbarLines, type SnackbarType, type Step, type StepStatus, type StepperSize, type StepperType, type TabItem, type TextAlign, type TextFieldSize, type TextFieldState, type TextFieldVariant, type ToastType, type TooltipPosition, type TooltipType, type TopbarForceLayout, type TopbarProfileType, type TopbarRewardTier, type TopbarVariant, type TrackStyle, type UploadFile, type UploadPhase, type UploadRejection, type UploadState, type UploadStatus, type Uploader, type UploaderContext, bindShortcut, formatShortcutParts, getDeepActiveElement, getFocusableElements, isApplePlatform, isEditableTarget, matchesShortcut, parseShortcut, trapTabKey };
+/**
+ * Shared screen-reader announcer.
+ *
+ * Maintains two persistent, visually-hidden live regions on document.body
+ * (one polite, one assertive). Because the regions exist before any message
+ * is written into them, text changes are reliably announced — unlike live
+ * regions that are inserted into the DOM at the same moment as their content,
+ * which most screen reader / browser pairs ignore.
+ *
+ * Messages are written on a short delay after clearing the region so that
+ * repeating the same string (e.g. two identical toasts in a row) is
+ * re-announced instead of deduplicated by the browser's accessibility tree.
+ */
+type Politeness = "polite" | "assertive";
+/**
+ * Announce a message to screen reader users without moving focus.
+ * Use "assertive" only for time-sensitive information (errors); everything
+ * else should be "polite" so it does not interrupt the user mid-word.
+ */
+declare function announce(message: string, politeness?: Politeness): void;
+
+export { type AlertTone, type AlertToneAlias, type AlertToneInput, type AutocompleteFilter, type AutocompleteItem, type AutocompleteSearchFn, type BindShortcutOptions, type BreadcrumbItem, type ButtonTone, type ButtonVariant, type ChipBorder, type ChipSize, type ChipTone, type ChipVariant, type ContainerBackground, type ContainerSurface, type DrawerCloseReason, type DrawerSide, type FieldLabelStyle, FocusTrap, type KbdSize, type LabelPlacement, type MenuItem, type MenuSize, type MenuType, type MenubarType, type ModalSide, type ModalSize, type ModalVariant, type Orientation, type OtpInputMode, type OtpSize, type OtpType, type ProgressMode, type RadioOption, RelAccordion, RelAlert, RelAutocomplete, RelAvatar, RelBadge, RelBreadcrumbs, RelButton, RelCalendar, RelCard, RelCardMedia, RelCarousel, RelCheckbox, RelChip, RelContainer, RelDatePicker, RelDivider, RelDrawer, RelDrawerFooter, RelKbd, RelKbdGroup, RelLayout, RelMenu, RelMenuItem, RelMenubar, RelMenubarMenu, RelModal, RelOtp, RelPagination, RelPopover, RelPopoverContent, RelProgress, RelRadio, RelRangePicker, RelResizableGroup, RelResizableHandle, RelResizablePanel, RelSegmentedButton, RelSelect, RelSkeleton, RelSlider, RelSnackbar, RelStepper, RelSwitch, RelTab, RelTabItem, RelTextfield, RelTimePicker, RelToast, RelTooltip, RelUpload, RelUploadActions, type SegmentAlign, type SegmentOption, type SegmentSize, type SelectBorder, type SelectLabelStyle, type SelectOption, type SelectOptionObject, type SelectSize, type SelectState, type ShortcutHandler, type SkeletonAnimation, type SkeletonShape, type SliderType, type SnackbarLines, type SnackbarTone, type SnackbarToneAlias, type SnackbarToneInput, type SnackbarType, type Step, type StepStatus, type StepperSize, type StepperType, type TabItem, type TabSize, type TextAlign, type TextFieldPrefixStyle, type TextFieldSize, type TextFieldState, type TextFieldVariant, type ToastTone, type ToastToneAlias, type ToastToneInput, type ToastType, type TooltipPosition, type TooltipType, type TrackStyle, type UploadFile, type UploadPhase, type UploadRejection, type UploadState, type UploadStatus, type Uploader, type UploaderContext, announce, bindShortcut, formatShortcutParts, getDeepActiveElement, getFocusableElements, isApplePlatform, isEditableTarget, matchesShortcut, parseShortcut, trapTabKey };