@porsche-design-system/components-angular 4.5.0-rc.1 → 4.6.0-rc.0

package/skill/references/components/p-pin-code/examples/Form.ts

@@ -0,0 +1,31 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()" class="flex flex-col gap-fluid-sm">
+      <p-pin-code formControlName="myPinCode" [label]="'Some Label'" />
+      <div class="flex gap-fluid-sm">
+        <p-button type="submit">Submit</p-button>
+        <p-button type="reset">Reset</p-button>
+      </div>
+      <p-text>Last submitted data: {{ submittedValue }}</p-text>
+    </form>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule, FormsModule, ReactiveFormsModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  form = new FormGroup({
+    myPinCode: new FormControl<string>(''),
+  });
+
+  submittedValue: any = undefined;
+
+  onSubmit(): void {
+    this.submittedValue = JSON.stringify(this.form.value);
+  }
+}

package/skill/references/components/p-pin-code/examples/Slots.ts

@@ -0,0 +1,42 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-pin-code state="error">
+        <span slot="label" id="some-label-id">
+          Some label with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+           and a "label-after" slot.
+        </span>
+        <p-popover slot="label-after">
+          Some Popover content with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+          .
+        </p-popover>
+        <span slot="description" id="some-description-id">
+          Some description with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+          .
+        </span>
+        <span slot="message" id="some-message-id">
+          Some error message with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+          .
+        </span>
+      </p-pin-code>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-pin-code/p-pin-code.md

@@ -0,0 +1,109 @@
+# p-pin-code
+
+The `p-pin-code` component is optimized for entering sequences of digits. The most common use case is for entering one-time-passwords (OTP) or pin codes. The input fields allow only one digit at a time. When a digit is entered, the focus shifts automatically to the next input, until every input is filled.
+
+A few things to note:
+
+- Only digits can be entered.
+- Only one digit can be entered per input.
+- Pressing `Delete` or `Backspace`: If the focussed input is blank and `Delete`/`Backspace` is pressed the focus transfers to the next/previous input, and clears the value of the next/previous input (if any). This avoids the need to explicitly `Shift+Tab & Delete`/ `Tab & Backspace`.
+
+A `label` is a caption which informs the user what information a particular form field is asking for. The `p-pin-code` component can be used with or without a label, but it's recommended to keep the label visible for better accessibility whenever possible. When used without a label, it's best practice to provide a descriptive label text for screen readers.
+
+## Usage
+
+### Do:
+
+- Use description text to explain the purpose or context of the `p-pin-code` component.
+- Use either 4 or 6 fields in the `p-pin-code` component based on your specific use case and security requirements.
+- Since only digits can be entered, use for digit codes only.
+- Use type `number` for numeric input or `password` for secure input depending on your application's needs.
+- Use the component's built-in support for inline validation.
+- Use consideration when implementing the component's behavior in a loading state to ensure it remains usable and responsive during data retrieval or processing.
+- If the `p-pin-code` component is isolated e.g. used with only one button use the loading state on the button. This ensures a consistent and intuitive user experience.
+
+### Don't:
+
+- Don't make the description text overly complex. Keep it concise and focused on clarifying the component's purpose.
+- Don't use the wrong field type for your use case. Ensure that type `number` or `password` aligns with the kind of input expected from users.
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label="STRING"` | References the current position of the input group. |
+| `aria-describedby="IDREF"` | References the accessible description and status messages. |
+| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
+
+## Development considerations
+
+### Disabled state
+
+In general, avoid using the `disabled="true"` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.
+
+### Common do's and don'ts
+
+- **Do** provide a clear `label` that describes what the code is for.
+- **Do** use `description` to explain where users can find the code.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Don't** use `hide-label` without an accessible name.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `compact` | `boolean` | `false` | Reduces the pin code field height and spacing for use in dense layouts where vertical space is limited. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to give users additional guidance about the pin code. |
+| `disabled` | `boolean` | `false` | Prevents user interaction with all pin code fields and blocks events while the component is disabled. |
+| `form` | `string` | `undefined` | Associates the pin code with a form element by its ID when it is not a direct descendant of that form. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label and description while keeping them accessible to screen readers. Supports responsive breakpoint values. |
+| `label` | `string` | `''` | Sets the visible label text displayed above the pin code fields to identify their purpose. |
+| `length` | `1` `2` `3` `4` `5` `6` | `4` | Sets the number of individual input fields rendered, determining how many characters the pin code consists of. |
+| `loading` | `boolean` | `false` | Disables the pin code fields and shows a loading spinner to indicate an ongoing background operation. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the pin code when `state` is `success` or `error`. |
+| `name` | `string` | `undefined` | Sets the name of the control submitted with the form data to identify the pin code value on the server. |
+| `required` | `boolean` | `false` | Marks the pin code as required so the form cannot be submitted until all fields are filled. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the pin code, which controls its visual appearance and feedback message style (`none`, `success`, `error`). |
+| `type` | `'number'` `'password'` | `'number'` | Controls whether the individual input fields mask their content as password dots (`password`) or show digits (`number`). |
+| `value` | `string` | `''` | Sets the current concatenated value of all pin code fields and allows setting the initial value. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<void>` | Emitted when the pin code component loses focus after the user finishes entering characters. |
+| `change` | `CustomEvent<PinCodeChangeEventDetail>`<br>`{ value: string; isComplete: boolean }` | Emitted when the pin code value changes as the user types, carrying the new concatenated value in the event detail. |
+
+### Controlled properties
+
+- `value` — a controlled prop, but the component also updates it internally. Listen for the `change` event to observe changes; you do not have to write the value back.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+| `description` | no | — | Shows a description. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Form | The `p-pin-code` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.ts](./examples/Form.ts) |
+| Copy+Paste and autocomplete | By default, only one input can be changed at a time. | [./examples/CopyPaste.ts](./examples/CopyPaste.ts) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.ts](./examples/Slots.ts) |

package/skill/references/components/p-popover/examples/Default.ts

@@ -0,0 +1,17 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-popover>
+        <p-text>
+          Some additional content.
+        </p-text>
+      </p-popover>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-popover/examples/SlottedButton.ts

@@ -0,0 +1,18 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-popover>
+        <p-button slot="button">
+          More information
+        </p-button>
+        Some additional content.
+      </p-popover>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-popover/p-popover.md

@@ -0,0 +1,116 @@
+# p-popover
+
+The `p-popover` component displays additional contextual content in an overlay and should be used when users need optional details without leaving their current context. It is triggered by a button and renders its own info button by default, or you can provide a custom trigger via the `button` slot.
+
+By default, the Popover works **uncontrolled**: it manages its own visibility and toggles open or closed when its info button (or a slotted trigger) is clicked. It is dismissed on outside click, on `Escape`, or when keyboard focus leaves the Popover.
+
+Alternatively, the Popover can be used in a **controlled** mode by setting the `open` prop together with a slotted `button` (the default info button does not toggle in this mode). In this mode you own the open state: the Popover only emits the `dismiss` event when the user requests to close it (via `Escape`, an outside click or when keyboard focus leaves the Popover), and you decide whether to update `open` in response.
+
+**Hint:** The `p-popover` utilizes the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) and gets rendered on the `#top-layer` which enables it to be shown correctly even when used e.g. within a scroll container.
+
+## Usage
+
+### Do:
+
+- Use it to display additional information that is not necessary for task completion or to provide further explanation about a workflow.
+- Position popovers in a way that they do not block related content.
+- Choose a preferred direction in which the popover should open, or it will automatically open in the direction with the most available space.
+- Use it consistently throughout your site.
+
+### Don't:
+
+- Don't use for content that can be displayed directly.
+
+---
+
+## References
+
+Nielsen Norman Group [Tooltip Guidelines](https://nngroup.com/articles/tooltip-guidelines)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Enter`, `Space` | - Opens/closes the popover. |
+
+### ARIA enhancements
+
+#### External **ARIA** provided by the `aria` property:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-label` | Defines a string value that labels the interactive element. |
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-expanded="BOOLEAN"` | Indicates that the popover element is displayed/hidden. |
+| `aria-details="IDREF"` | References the element that provides additional information about the popover. |
+
+## Development considerations
+
+In **uncontrolled** mode the `p-popover` component does not manage `aria-expanded` on a custom slotted button, because it does not expose its internal `open` state publicly. In this case the default info button (which the component fully controls) already exposes `aria-expanded` for you.
+
+In **controlled** mode the consumer owns the `open` state, so the slotted trigger *can* (and should) expose `aria-expanded` to match the default button's semantics. Bind it to your `open` state via the trigger's `aria` property, e.g. `aria={{ 'aria-expanded': open ? 'true' : 'false' }}`, so it stays in sync as the popover opens and closes.
+
+### Common do's and don'ts
+
+- **Do** prefer the built-in popover trigger when possible so `aria-expanded` is managed internally.
+- **Do** provide an accessible name on a custom slotted button when you cannot use the default trigger.
+- **Do** pass additional ARIA via the `aria` prop when the default labeling is not sufficient.
+- **Don't** use an unnamed custom slotted trigger button.
+- **Don't** add native `aria-*` attributes directly on the component host.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria` | `PopoverAriaAttribute` | `undefined` | Sets ARIA attributes on the popover panel to improve accessibility for screen readers. |
+| `compact` | `boolean` | `undefined` | Reduces padding and spacing for a more compact layout, useful in space-constrained interfaces. |
+| `description` | `string` | `undefined` | Sets the text content displayed inside the popover panel when it is open, providing contextual help or information. Takes precedence over the default slot when both are provided. |
+| `direction` | `'top'` `'right'` `'bottom'` `'left'` | `'bottom'` | Sets the preferred direction for the popover to open relative to its trigger button. Falls back to the direction with the most available viewport space. |
+| `open` | `boolean` | `undefined` | Controls whether the popover is visible. When set (controlled mode), visibility follows this prop and the consumer owns the open state via a slotted `button`. When omitted (uncontrolled mode), the component manages visibility itself. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `dismiss` | `CustomEvent<void>` | Emitted in controlled mode when the user requests to close the popover via the Escape key, an outside click, or when keyboard focus leaves the popover (Tab / Shift+Tab). |
+
+### Controlled properties
+
+- `open` — a controlled prop: the component does **not** update it itself. Handle the `dismiss` event and assign the new value to `open` yourself, or the change will not take effect.
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot for the popover content. Ignored when the `description` prop is set, which takes precedence. |
+| `button` | no | — | Renders a custom trigger button. When used, the default info button is replaced. |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--p-popover-w` | `max-content` | Width of the popover. |
+| `--p-popover-h` | `auto` | Height of the popover. |
+| `--p-popover-min-w` | `0px` | Min width of the popover. |
+| `--p-popover-min-h` | `auto` | Min height of the popover. |
+| `--p-popover-max-w` | `min(calc(100dvw - 16px), 48ch)` | Max width of the popover. |
+| `--p-popover-max-h` | `calc(100dvh - 16px)` | Max height of the popover. |
+| `--p-popover-px` | `16px` | Horizontal padding of the popover. It is recommended to apply an existing Porsche Design System spacing token, e.g. the CSS declaration `--p-popover-px: var(--p-spacing-static-md)`, the Tailwind CSS arbitrary property `[--p-popover-px:var(--spacing-static-md)]` or the equivalent SCSS/JS token. |
+| `--p-popover-py` | `16px` | Vertical padding of the popover. It is recommended to apply an existing Porsche Design System spacing token, e.g. the CSS declaration `--p-popover-py: var(--p-spacing-static-sm)`, the Tailwind CSS arbitrary property `[--p-popover-py:var(--spacing-static-sm)]` or the equivalent SCSS/JS token. |
+| `--p-popover-radius` | `12px` | Border radius of the popover. It is recommended to apply an existing Porsche Design System border-radius token, e.g. the CSS declaration `--p-popover-radius: var(--p-radius-lg)`, the Tailwind CSS arbitrary property `[--p-popover-radius:var(--radius-lg)]` or the equivalent SCSS/JS token. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Slotted button | The `p-popover` component can also be used with a **slotted button** via the `button` slot, allowing you to provide a custom button element. | [./examples/SlottedButton.ts](./examples/SlottedButton.ts) |

package/skill/references/components/p-radio-group/examples/Default.ts

@@ -0,0 +1,20 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-radio-group name="options" label="Some Label" description="Some description">
+        <p-radio-group-option value="a" label="Option A"></p-radio-group-option>
+        <p-radio-group-option value="b" label="Option B"></p-radio-group-option>
+        <p-radio-group-option value="c" label="Option C"></p-radio-group-option>
+        <p-radio-group-option value="d" label="Option D"></p-radio-group-option>
+        <p-radio-group-option value="e" label="Option E"></p-radio-group-option>
+        <p-radio-group-option value="f" label="Option F"></p-radio-group-option>
+      </p-radio-group>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-radio-group/examples/Form.ts

@@ -0,0 +1,38 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()" class="flex flex-col gap-fluid-sm">
+      <p-radio-group formControlName="myRadioGroup" [label]="'Some Label'">
+        <p-radio-group-option label="Option A" value="a"></p-radio-group-option>
+        <p-radio-group-option label="Option B" value="b"></p-radio-group-option>
+        <p-radio-group-option label="Option C" value="c"></p-radio-group-option>
+        <p-radio-group-option label="Option D" value="d"></p-radio-group-option>
+        <p-radio-group-option label="Option E" value="e"></p-radio-group-option>
+        <p-radio-group-option label="Option F" value="f"></p-radio-group-option>
+      </p-radio-group>
+      <div class="flex gap-fluid-sm">
+        <p-button type="submit">Submit</p-button>
+        <p-button type="reset">Reset</p-button>
+      </div>
+      <p-text>Last submitted data: {{ submittedValue }}</p-text>
+    </form>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule, FormsModule, ReactiveFormsModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {
+  form = new FormGroup({
+    myRadioGroup: new FormControl<string>(''),
+  });
+
+  submittedValue: any = undefined;
+
+  onSubmit(): void {
+    this.submittedValue = JSON.stringify(this.form.value);
+  }
+}

package/skill/references/components/p-radio-group/examples/Slots.ts

@@ -0,0 +1,72 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-radio-group state="error" value="a">
+        <span slot="label">
+          Some slotted label with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+           text and a "label-after" slot.
+        </span>
+        <p-popover slot="label-after">
+          Some Popover description
+        </p-popover>
+        <span slot="description">
+          Some slotted description with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+          .
+        </span>
+        <span slot="message">
+          Some slotted error message with a 
+          <a href="https://designsystem.porsche.com" class="underline">
+            link
+          </a>
+          .
+        </span>
+        <p-radio-group-option value="a">
+          <span slot="label">
+            <img src="assets/911.png" alt="" class="object-contain inline-block align-middle -mt-2 me-static-sm w-[70px]" />
+            Some slotted label with custom content and a "label-after" slot
+          </span>
+          <p-popover slot="label-after">
+            Option A with slotted label and a popover 
+          </p-popover>
+        </p-radio-group-option>
+        <p-radio-group-option value="b">
+          <span slot="label">
+            Option B with slotted label
+          </span>
+        </p-radio-group-option>
+        <p-radio-group-option value="c" disabled="true">
+          <span slot="label">
+            Disabled Option C with slotted label, a nested 
+            <a href="https://www.porsche.com" class="underline">
+              link
+            </a>
+             and a label-after slot.
+          </span>
+          <p-popover slot="label-after">
+            Some information about the disabled state.
+          </p-popover>
+        </p-radio-group-option>
+        <p-radio-group-option value="d">
+          <span slot="label">
+            Option C with slotted label and a nested 
+            <a href="https://www.porsche.com" class="underline">
+              link
+            </a>
+          </span>
+        </p-radio-group-option>
+      </p-radio-group>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-radio-group/p-radio-group.md

@@ -0,0 +1,157 @@
+# p-radio-group
+
+The `p-radio-group` component is a versatile custom form element that enables the selection of a single option.
+
+> **Attention**
+>
+> The `blur` event is emitted whenever the focused `p-radio-group-option` changes — not only when the entire `p-radio-group` loses focus. This means that switching between options within the same group will also trigger a `blur` event for the previously focused option.
+
+Options are slotted using the `p-radio-group-option` component. Each option needs to have an assigned value, which can be passed via an attribute or property and needs to be of type string. Initial selection states can only be achieved using the value property on the `p-radio-group` component. If an option should be visible but not selectable, it can be disabled by using the `disabled` attribute.
+
+A `label` is a caption which informs the user what information a particular form field is asking for. The `p-radio-group` component can be used with or without a label, but it's recommended to keep the label visible for better accessibility whenever possible. When used without a label, it's best practice to provide a descriptive label text for screen readers.
+
+## Usage
+
+### Do:
+
+- Use to enable a user to select one value from a predefined list. Use as soon as two options are mutually exclusive.
+- Use [Checkbox](../p-checkbox/p-checkbox.md) instead if there is only one option.
+- Use when the user should see all available options.
+- Consider using the [Segmented Control](../p-segmented-control/p-segmented-control.md) for 5 options or fewer.
+- Keep the label text short and descriptive (one or two words).
+- Select one option by default in a group of radio buttons, except for cases where a pre-selection can lead to wrong assumptions.
+- Align radio buttons with more than 2 items vertically left-aligned.
+
+### Don't:
+
+- Don't use a radio Button for a large number of items (≥ 7), use the [Select](../p-select/p-select.md) or [Segmented Control](../p-segmented-control/p-segmented-control.md) component instead.
+
+---
+
+## Related Components
+
+- [Checkbox](../p-checkbox/p-checkbox.md)
+- [Segmented Control](../p-segmented-control/p-segmented-control.md)
+- [Select](../p-select/p-select.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Arrow left`, `Arrow right`, `Down Arrow` `Up Arrow` | Activates and moves focus to the next/prev radio button in a group. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-labelledby="IDREF"` | Defines the accessible name. |
+| `aria-describedby="IDREF"` | Defines the accessible description combined with the status message. |
+| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
+| `aria-hidden="true"` | If `required` attribute is set, the visible asterisk indicator is hidden from assistive technologies. |
+| `aria-invalid="true"` | If `error` state is set. |
+| `aria-required="true"` | Indicates if the element is required. |
+
+## Development considerations
+
+### Disabled state
+
+In general, avoid using the `disabled` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.
+
+### Common do's and don'ts
+
+- **Do** provide a clear group `label` that describes the choice being made.
+- **Do** use meaningful option labels so each choice is understandable out of context.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Don't** rely on adjacent text instead of the group `label` prop.
+- **Don't** use `hide-label` without an accessible name.
+
+## Tests
+
+### Automated
+
+| Technology | Support |
+| --- | --- |
+| AXE-Core (WCAG 2.2 AA, Best-Practice) | ✅ |
+| High-Contrast Mode (light/dark) | ✅ |
+| Text-Zoom (200%) | ✅ |
+
+### Manual
+
+| Technology | Support |
+| --- | --- |
+| Keyboard | ✅ |
+| Screen reader (VoiceOver, NVDA) | ⚠️(Note: VoiceOver/NVDA do not announce the number of options correctly when used with Safari or Chrome) |
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `compact` | `boolean` | `false` | Reduces the spacing between radio options for use in dense layouts where vertical space is limited. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to give users additional guidance about the radio group. |
+| `direction` | `'row'` `'column'`<br>`BreakpointCustomizable<RadioGroupDirection>` | `'column'` | Sets the layout direction of the radio options. Use `column` to stack them vertically or `row` to arrange them horizontally. Supports responsive breakpoint values. |
+| `disabled` | `boolean` | `false` | Disables all radio options in the group, preventing selection and excluding the value from form submissions. |
+| `form` | `string` | `undefined` | Associates the radio group with a form element by its ID when the group is not a direct descendant of that form. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `label` | `string` | `''` | Sets the visible label text displayed above the radio group to identify the group's purpose. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables all radio options and shows a spinner to indicate a background loading operation. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the radio group when `state` is `success` or `error`. |
+| `name` _(required)_ | `string` | `undefined` | Sets the shared name attribute for all radio buttons in the group, grouping them for mutually exclusive selection. |
+| `required` | `boolean` | `false` | Marks the radio group as required so the form cannot be submitted until one option is selected. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state of the radio group, controlling its visual appearance and feedback message style (`none`, `success`, `error`). |
+| `value` | `string` | `''` | Sets the currently selected value that pre-selects the matching radio option and reflects user changes. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<void>` | Emitted when the radio group loses focus after the user interacts with it, useful for triggering validation on blur. |
+| `change` | `CustomEvent<RadioGroupChangeEventDetail>`<br>`Event` | Emitted when the user selects a different option, carrying the new value and the native event in the event detail. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+| `description` | no | — | Shows a description. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| _(default)_ | no | — | Default slot for the p-radio-group-option tags. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+
+## Sub-components
+
+These tags are only valid inside the parent(s) listed under each one — often this component, but some are shared and list a different parent (e.g. a tag documented here via a common ancestor). Their APIs come from the same authoritative `component-meta` as the parent above.
+
+### `p-radio-group-option`
+
+Allowed parent: `p-radio-group`.
+
+#### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Prevents this option from being selected and excludes its value from form submissions while it is disabled. |
+| `label` | `string` | `undefined` | Sets the visible label text displayed next to the radio button that the user reads to identify the option. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables this option and shows a spinner to indicate that this particular option is in a loading state. |
+| `value` | `string` | `undefined` | Sets the value submitted with the form data when this radio option is selected within its parent group. |
+
+#### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Form | The `p-radio-group` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.ts](./examples/Form.ts) |
+| Slots | Use named slots when `label` or `message` need markup such as a link. | [./examples/Slots.ts](./examples/Slots.ts) |