@lmvz-ds/components 0.24.0 → 0.25.0

package/manifest.json

@@ -1,8 +1,8 @@
 {
-  "timestamp": "2026-06-01T13:24:33",
+  "timestamp": "2026-06-02T16:23:34",
   "compiler": {
     "name": "@stencil/core",
-    "version": "4.43.4",
+    "version": "4.43.5",
     "typescriptVersion": "5.8.3"
   },
   "components": [
@@ -5878,6 +5878,414 @@
         ]
       }
     },
+    {
+      "filePath": "src/components/lmvz-radio/lmvz-radio.tsx",
+      "encapsulation": "scoped",
+      "tag": "lmvz-radio",
+      "readme": "# lmvz-radio\n\nAccessible, form-associated radio button built as a Stencil scoped web component. Supports form association, native radio group mutual exclusion via `name` forwarding, roving tabindex, and ARIA APG-compliant keyboard navigation.\n\n## Usage\n\n### Basic\n\n```html\n<lmvz-radio name=\"choice\" value=\"a\" label=\"Option A\"></lmvz-radio>\n<lmvz-radio name=\"choice\" value=\"b\" label=\"Option B\"></lmvz-radio>\n```\n\n## Form Integration\n\n`lmvz-radio` is a FACE (Form-Associated Custom Element). It participates in native HTML forms via `ElementInternals`: the `name` and `value` attributes are submitted to the form when the radio is `checked`.\n\nSetting `required` triggers native form validation — the form will not submit unless a radio with the given `name` is checked.\n\n### Form Reset Behavior\n\nWhen a form is reset, `lmvz-radio` restores its `checked` state to the value it held when the component first mounted (the `initialChecked` value), without emitting `lmvzChange`. This matches native `<input type=\"radio\">` behavior. Internal form state (via `ElementInternals.setFormValue`) is always updated regardless. Browser autofill and session-restore operations (via `formStateRestoreCallback`) also do not emit `lmvzChange`.\n\n> **Note:** `aria-required` is intentionally absent from `lmvz-radio`. When a radio group is required, expose `aria-required` on the `role=\"radiogroup\"` wrapper element via your application code. This is the consumer's responsibility.\n\n## Radio Group Behavior\n\nWhen multiple `lmvz-radio` elements share the same `name` attribute and are within the same form (or document scope if outside any form), they form a native radio group. The `name` is forwarded directly to the native `<input type=\"radio\">`, enabling the browser's built-in mutual-exclusion logic: selecting one radio automatically deselects all others with the same name in the same scope. Radios with the same `name` in different forms are treated as independent groups.\n\n**Roving tabindex:** The component automatically manages keyboard focus navigation via the `RadioGroupController`. When a group of radios shares the same `name`:\n- The checked radio has `tabindex=\"0\"` and is reachable via Tab.\n- All other enabled radios have `tabindex=\"-1\"` and are not directly tabbable.\n- If no radio is checked, the first enabled radio in DOM order receives `tabindex=\"0\"`, ensuring the group is always reachable.\n\n**Keyboard navigation (manual selection pattern):**\n\n| Key | Action |\n|-----|--------|\n| Arrow Down / Arrow Right | Moves focus to the next radio in the group (no selection) |\n| Arrow Up / Arrow Left | Moves focus to the previous radio in the group (no selection) |\n| Home | Moves focus to the first radio in the group (no selection) |\n| End | Moves focus to the last radio in the group (no selection) |\n| Space | Selects the focused radio; emits `lmvzActivation` and (if state changed) `lmvzChange` |\n| Tab | Moves focus out of the radio group |\n\nDisabled radios are skipped during navigation.\n\nThis component implements the WAI-ARIA [manual selection](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) pattern: focus and selection are decoupled. Arrow keys move focus without selecting. The consumer is responsible for wrapping grouped radios in a `role=\"radiogroup\"` element.\n\n**Consumer responsibility — `role=\"radiogroup\"`:**\nWrap a group of related `lmvz-radio` elements in a container element with `role=\"radiogroup\"` and an accessible label via `aria-label` or `aria-labelledby`. The radio component does not add this role itself because a radio button cannot also be a radiogroup.\n\n## Accessibility\n\n- A native `<input type=\"radio\">` is rendered inside the component for full keyboard and screen reader support.\n- `role=\"radiogroup\"` must be added by the consumer on a wrapper element (see \"Radio Group Behavior\" above).\n- `aria-invalid` is set when `error=true`.\n- `aria-describedby` links the input to helper text when `helper-text` is provided.\n- Helper text uses `aria-live=\"polite\"` for dynamic updates.\n- The focus ring is visible and meets WCAG 2.1 AA contrast requirements.\n- Forced Colors (Windows High Contrast Mode) is supported.\n\n## CSS Custom Properties\n\nOverride these on the `:host` element to theme the component. All defaults reference LMVZ semantic or global design tokens.\n\n| Property | Default | Description |\n|---|---|---|\n| `--radio-circle-size` | `var(--lmvz-global-s18)` | Width and height of the radio circle |\n| `--radio-dot-size` | `0.5rem` | Size of the inner selected dot |\n| `--radio-bg` | `var(--lmvz-semantic-color-surface-input-primary)` | Circle background (unchecked) |\n| `--radio-border-color` | `var(--lmvz-semantic-color-border-default)` | Circle border (default) |\n| `--radio-border-color-hover` | `var(--lmvz-semantic-color-border-hover)` | Circle border on hover |\n| `--radio-border-color-checked` | `var(--lmvz-semantic-color-border-active)` | Circle border when checked |\n| `--radio-border-color-error` | `var(--lmvz-semantic-color-status-on-danger)` | Circle border in error state |\n| `--radio-dot-color` | `var(--lmvz-semantic-color-border-active)` | Color of the inner dot |\n| `--radio-wrapper-bg-hover` | `var(--lmvz-semantic-color-int-tertiary-hover)` | Pill background on hover |\n| `--radio-wrapper-bg-active` | `var(--lmvz-semantic-color-int-tertiary-active)` | Pill background when pressed |\n| `--radio-wrapper-bg-checked` | `var(--lmvz-semantic-color-status-active)` | Pill background when checked |\n| `--radio-label-color` | `var(--lmvz-semantic-color-on-surface-primary)` | Label text color (default) |\n| `--radio-label-color-checked` | `var(--lmvz-semantic-color-status-on-active)` | Label text color when checked |\n| `--radio-helper-color` | `var(--lmvz-semantic-color-on-surface-secondary)` | Helper text color |\n| `--radio-focus-color` | `var(--lmvz-semantic-color-status-on-active)` | Focus ring color |\n| `--radio-easing` | `var(--lmvz-global-easing-default, ease)` | Transition easing function |\n| `--radio-duration` | `0.2s` | Transition duration |\n\n## lmvzChange Emission Contract\n\nThe `lmvzChange` event emits only when the radio's checked state changes. The event detail contains the new `checked` boolean value.\n\n**Fires on:**\n- User activation: clicking the radio or pressing Space (only if state changes)\n- Programmatic checked state transitions: setting `checked = true` or `checked = false`\n\n**Does NOT fire on:**\n- Arrow key navigation (Arrow Down, Arrow Up, Home, End). These move focus only, without selection.\n- Browser form lifecycle callbacks (`formResetCallback`, `formStateRestoreCallback`). This matches native `<input type=\"radio\">` behavior, which does not fire `change` on form reset. Internal form state (`ElementInternals.setFormValue`) is always updated regardless.\n\n## Angular Integration\n\n### Automatic Form Integration\n\nUse the `LmvzCheckableValueChangeHelper` directive (included in `@lmvz-ds/angular`) to automatically wire `lmvz-radio` to Angular form controls. When this directive is present on the element, it automatically binds the `lmvzChange` event to the form control's `valueChange` output:\n\n```html\n<!-- With [(ngModel)] -->\n<lmvz-radio\n  label=\"Option A\"\n  name=\"choice\"\n  value=\"a\"\n  [(ngModel)]=\"selectedValue\">\n</lmvz-radio>\n\n<!-- With [formControl] -->\n<lmvz-radio\n  label=\"Option B\"\n  name=\"choice\"\n  value=\"b\"\n  [formControl]=\"controlRef\">\n</lmvz-radio>\n```\n\nNo additional setup is required — the directive is applied automatically via the selector `lmvz-checkbox, lmvz-radio`.\n\n### Manual Event Binding\n\nIf you need direct event handling, listen to the `lmvzChange` event:\n\n```html\n<lmvz-radio\n  label=\"Option\"\n  name=\"choice\"\n  [checked]=\"isChecked\"\n  (lmvzChange)=\"isChecked = $event.target.checked\">\n</lmvz-radio>\n```\n\n## Public Methods\n\n### focusInput()\n\nProgrammatically set focus on the native radio input. Use this method when you need to move keyboard focus to a radio after a user interaction or page state change:\n\n```typescript\nconst radioEl = document.querySelector('lmvz-radio');\nawait radioEl.focusInput();\n```\n\n## Event Reference\n\n### lmvzActivation\n\nThe `lmvzActivation` event fires on every explicit user activation: click or Space on the native input. This includes re-activation of an already-checked radio. Use this event to react directly to user intent, distinct from state transitions.\n\n### lmvzChange vs lmvzActivation\n\n- **`lmvzActivation`:** Fires on every explicit user activation (click or Space), regardless of whether the checked state actually changes.\n- **`lmvzChange`:** Fires only on state transitions (checked ↔ unchecked).\n\nWhen a user selects a different radio in a group, both events fire together. When a user re-activates an already-checked radio, only `lmvzActivation` fires.\n\n## Design Notes / Waivers\n\n### Checked + hover state (OQ-5)\n\nWhen a radio is both checked and hovered, the checked background (`--radio-wrapper-bg-checked`) is held — the hover background does not override it. No Figma spec exists for this combined state; this behavior is an intentional implementation decision.\n\n### Label wrapping (OQ-3)\n\nThe label uses `overflow-wrap: break-word` (normal wrapping). `white-space: nowrap` is intentionally not applied.\n",
+      "docs": "Radio button component with form association, ARIA validation, accessible label support,\nand ARIA APG-compliant Arrow-key keyboard navigation.\n\n**Consumer responsibility — `role=\"radiogroup\"`:**\nWrap a group of `lmvz-radio` elements in a container element with `role=\"radiogroup\"` and\nan accessible label via `aria-label` or `aria-labelledby`. `lmvz-radio` must not carry\n`role=\"radiogroup\"` itself because a radio cannot also be a radiogroup.\n\n**Arrow-key navigation and roving tabindex:**\nWhen multiple `lmvz-radio` elements share the same `name` attribute, this component\nautomatically handles Arrow Down / Arrow Right (next), Arrow Up / Arrow Left (previous),\nHome (first), and End (last) navigation with wrapping. Disabled radios are skipped.\nThe checked radio has `tabindex=\"0\"`. When no radio is checked, the first enabled radio\nin DOM order receives `tabindex=\"0\"`, ensuring the group is always reachable by Tab.",
+      "docsTags": [
+        {
+          "name": "example",
+          "text": "```html\n<div role=\"radiogroup\" aria-label=\"Choose an option\">\n  <lmvz-radio label=\"Option A\" name=\"choice\" checked></lmvz-radio>\n  <lmvz-radio label=\"Option B\" name=\"choice\"></lmvz-radio>\n</div>\n```"
+        }
+      ],
+      "usage": {},
+      "props": [
+        {
+          "name": "autofocus",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "autofocus",
+          "reflectToAttr": false,
+          "docs": "Whether the radio should autofocus.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "checked",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": true,
+          "attr": "checked",
+          "reflectToAttr": true,
+          "docs": "Whether the radio is checked.\n\nSetting this prop programmatically (e.g. `element.checked = true`) fires `lmvzChange`\nwith the new value, unless the change occurs during native form lifecycle callbacks\n(`formResetCallback` or `formStateRestoreCallback`), in which case emission is suppressed\nto match native `<input type=\"radio\">` behavior. Internal form state is always updated\nregardless of emission suppression.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "disabled",
+          "reflectToAttr": true,
+          "docs": "Whether the radio is disabled.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "error",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "error",
+          "reflectToAttr": true,
+          "docs": "Whether the radio is in an error state.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "form",
+          "type": "string | undefined",
+          "complexType": {
+            "original": "string",
+            "resolved": "string | undefined",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "form",
+          "reflectToAttr": true,
+          "docs": "Form id to associate with (for out-of-form usage).\nReflected to the host attribute so both HTML attribute and programmatic assignment work.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "helperText",
+          "type": "string | undefined",
+          "complexType": {
+            "original": "string",
+            "resolved": "string | undefined",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "helper-text",
+          "reflectToAttr": false,
+          "docs": "Helper / description text displayed below the label.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "label",
+          "reflectToAttr": false,
+          "docs": "Label text for the radio. Required for accessibility.",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": false,
+          "required": true,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "name",
+          "type": "string | undefined",
+          "complexType": {
+            "original": "string",
+            "resolved": "string | undefined",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "name",
+          "reflectToAttr": false,
+          "docs": "Name attribute for form submission via ElementInternals.\n\nWhen multiple `lmvz-radio` elements share the same `name` and form scope,\nthe `name` is forwarded directly to the native `<input type=\"radio\">`,\nenabling browser-native mutual exclusion: selecting one radio automatically\ndeselects all others with the same name in that form. If a radio is outside\nany form, its scope defaults to the document level — same-name radios\noutside forms form a document-scoped group. Radios with the same `name` in\ndifferent forms are independent groups.\n\nThe `RadioGroupController` automatically manages roving tabindex (only the\nchecked radio has `tabindex=\"0\"`) and keyboard navigation (Arrow keys, Home, End)\nwithin the form-scoped group.",
+          "docsTags": [
+            {
+              "name": "remarks",
+              "text": "A value of `\"\"` (empty string) is forwarded to the native `<input>`, but\n`RadioGroupController` treats it as unnamed — no group coordination occurs between\nradios with `name=\"\"`."
+            }
+          ],
+          "values": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "required",
+          "reflectToAttr": true,
+          "docs": "Whether the radio is required.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "complexType": {
+            "original": "string",
+            "resolved": "string",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "value",
+          "reflectToAttr": false,
+          "docs": "Form submission value when checked.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "'on'"
+            }
+          ],
+          "default": "'on'",
+          "values": [
+            {
+              "type": "string"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        }
+      ],
+      "methods": [
+        {
+          "name": "checkValidity",
+          "returns": {
+            "type": "Promise<boolean>",
+            "docs": ""
+          },
+          "complexType": {
+            "signature": "() => Promise<boolean>",
+            "parameters": [],
+            "references": {
+              "Promise": {
+                "location": "global",
+                "id": "global::Promise"
+              }
+            },
+            "return": "Promise<boolean>"
+          },
+          "signature": "checkValidity() => Promise<boolean>",
+          "parameters": [],
+          "docs": "Returns whether the radio satisfies its validation constraints.",
+          "docsTags": []
+        },
+        {
+          "name": "focusInput",
+          "returns": {
+            "type": "Promise<void>",
+            "docs": ""
+          },
+          "complexType": {
+            "signature": "() => Promise<void>",
+            "parameters": [],
+            "references": {
+              "Promise": {
+                "location": "global",
+                "id": "global::Promise"
+              }
+            },
+            "return": "Promise<void>"
+          },
+          "signature": "focusInput() => Promise<void>",
+          "parameters": [],
+          "docs": "Sets focus on the native radio input.",
+          "docsTags": []
+        },
+        {
+          "name": "reportValidity",
+          "returns": {
+            "type": "Promise<boolean>",
+            "docs": ""
+          },
+          "complexType": {
+            "signature": "() => Promise<boolean>",
+            "parameters": [],
+            "references": {
+              "Promise": {
+                "location": "global",
+                "id": "global::Promise"
+              }
+            },
+            "return": "Promise<boolean>"
+          },
+          "signature": "reportValidity() => Promise<boolean>",
+          "parameters": [],
+          "docs": "Reports validation errors to the user.",
+          "docsTags": []
+        }
+      ],
+      "events": [
+        {
+          "event": "lmvzActivation",
+          "detail": "void",
+          "bubbles": true,
+          "complexType": {
+            "original": "void",
+            "resolved": "void",
+            "references": {}
+          },
+          "cancelable": true,
+          "composed": true,
+          "docs": "Fired on every explicit user activation of this radio — via click or Space key on the\nnative input. Fires even when the radio is already checked (re-activation). Use this\nevent to react to user intent; use `lmvzChange` to react to state transitions.",
+          "docsTags": []
+        },
+        {
+          "event": "lmvzChange",
+          "detail": "boolean",
+          "bubbles": true,
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "cancelable": true,
+          "composed": true,
+          "docs": "Emitted whenever the radio checked state changes.\nEvent detail contains the new checked boolean value.\n\nEmission contract:\n- Fires `true` on user selection (native `change` event).\n- Fires on programmatic external prop transitions: `true → false` (emits `false`) and\n  `false → true` (emits `true`), e.g. `element.checked = false` or `element.checked = true`.\n- Does NOT fire during browser-driven form lifecycle callbacks: `formResetCallback` and\n  `formStateRestoreCallback` (autofill / session restore). This matches native `<input type=\"radio\">`\n  behaviour, which does not fire `change` on form reset. Note that internal form state\n  (`ElementInternals.setFormValue`) is always updated regardless of suppression — only the\n  event channel is silenced.\n- Does NOT re-fire from the `@Watch('checked')` watcher during the same tick as the native\n  `change` handler, preventing a double-emission when the user clicks the radio.",
+          "docsTags": []
+        }
+      ],
+      "listeners": [
+        {
+          "event": "keydown",
+          "capture": false,
+          "passive": false
+        }
+      ],
+      "styles": [],
+      "slots": [],
+      "parts": [],
+      "states": [],
+      "dependents": [],
+      "dependencies": [],
+      "dependencyGraph": {}
+    },
     {
       "filePath": "src/components/lmvz-select/lmvz-select.tsx",
       "encapsulation": "scoped",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmvz-ds/components",
   "private": false,
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "description": "The components of the design system",
   "author": "Patrick Nemenz <patrick.nemenz@adesso.at>",
@@ -83,6 +83,10 @@
     "./lmvz-button-group": {
       "import": "./components/lmvz-button-group.js",
       "types": "./components/lmvz-button-group.d.ts"
+    },
+    "./lmvz-radio": {
+      "import": "./components/lmvz-radio.js",
+      "types": "./components/lmvz-radio.d.ts"
     }
   },
   "main": "./index.cjs.js",

package/types/components/lmvz-radio/lmvz-radio.d.ts

@@ -0,0 +1,42 @@
+import { type EventEmitter } from '../../stencil-public-runtime';
+import { type AriaValidationHost } from '../../utils/aria/aria-validation-controller';
+import { type RadioHost } from '../../utils/radio/radio-group-controller';
+import { ReactiveControllerHost } from '../../utils/reactive-controller-host';
+export declare class LmvzRadio extends ReactiveControllerHost implements AriaValidationHost, RadioHost {
+    readonly el: HTMLElement;
+    get validationEl(): HTMLElement;
+    internals: ElementInternals;
+    private nativeInput;
+    private radioId;
+    private initialChecked;
+    private radioGroupController;
+    private get helperId();
+    label: string;
+    checked: boolean;
+    value: string;
+    name?: string;
+    disabled: boolean;
+    required: boolean;
+    error: boolean;
+    helperText?: string;
+    form?: string;
+    autofocus: boolean;
+    private _handlingNativeChange;
+    private _handlingFormReset;
+    protected handleCheckedChange(newVal: boolean, oldVal: boolean): void;
+    protected handleValueChange(newVal: string): void;
+    protected handleLabelChange(newVal: string): void;
+    lmvzChange: EventEmitter<boolean>;
+    lmvzActivation: EventEmitter<void>;
+    focusInput(): Promise<void>;
+    checkValidity(): Promise<boolean>;
+    reportValidity(): Promise<boolean>;
+    constructor();
+    componentWillLoad(): void;
+    formAssociatedCallback(): void;
+    formResetCallback(): void;
+    formStateRestoreCallback(state: string | File | FormData): void;
+    private handleChange;
+    handleKeydown(event: KeyboardEvent): void;
+    render(): any;
+}