@pastweb/components-core 2.0.0 → 2.2.0

package/dist/Panel/README.md

@@ -0,0 +1,158 @@
+# Panel
+
+Panel groups related content in a bordered, optionally rounded article with a
+semantic heading, close action, and footer. Its rendering contract targets
+WCAG 2.2 Level AA. It is a content grouping container, not a confirmation or
+interruption panel.
+
+## When to use
+
+Use Panel to visually group a self-contained section of page content. Keep
+heading levels consistent with the surrounding document. Do not use it as a
+modal dialog without adding the separate dialog focus and interaction contract.
+Do not use it as a GOV.UK confirmation or interruption panel.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component, part, and state classes. |
+| `ariaLabel` | `string` | no | `""` | Names the article when no title is supplied. Pass an empty string to omit the name. |
+| `border` | `boolean` | no | `true` | Applies the `has-border` class. The public prop name remains `border`. |
+| `borderRadius` | `boolean` | no | `true` | Applies the `has-border-radius` class. The public prop name remains `borderRadius`. |
+| `className` | `string` | no | `""` | Adds classes to the root article. |
+| `closeButton` | `boolean` | no | `true` | Displays the native close button. |
+| `closeLabel` | `string` | no | `"Close panel"` | Names the close button. |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | no | `2` | Selects the native title heading level. |
+| `id` | `string` | no | generated | Supplies the stable panel ID and title-ID base. Generated IDs use the `panel` prefix. Explicit IDs are stored as `_${id}`. |
+| `title` | `string` | no | `""` | Supplies the default heading content. |
+| `contentPadding` | `number \| string` | no | `0` | Sets inline padding on the content area. |
+| `onClose` | `() => void` | no | noop | Reports close intent. |
+| `rtl` | `boolean` | no | - | Reverses header content order. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name when no title is present. Empty labels are omitted. |
+| `heading` | `PanelHeading` | Native title tag from `headingLevel`, such as `h2`. |
+| `id` | `string` | Article ID from an explicit `id` or a generated `panel` prefix. |
+| `titleId` | `string \| undefined` | Title relationship ID `title${id}` when heading content is present; otherwise omitted. |
+
+## Slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| default | Supplies panel body content. | Empty. |
+| `header` | Replaces title and close content inside the semantic header. | Heading and optional close button. |
+| `footer` | Supplies content wrapped in the semantic footer. | Empty. |
+
+## CSS classes
+
+| Class | Applied when | Notes |
+|---|---|---|
+| `Panel` | Always | Root component class. |
+| `has-border` | `border` is `true` | Optional article border. |
+| `has-border-radius` | `borderRadius` is `true` | Optional article corner radius. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Panel_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_background-color)` | Panel background. | Web, Capacitor, NativeScript |
+| `--pw_Panel_root_default_color` | `root` | `default` | `color` | `var(--pw_text_color)` | Panel foreground. | Web, Capacitor, NativeScript |
+| `--pw_Panel_root_default_font-size` | `root` | `default` | `font-size` | `var(--pw_font-size)` | Body text size. | Web, Capacitor, NativeScript |
+| `--pw_Panel_root_default_font-weight` | `root` | `default` | `font-weight` | `var(--pw_font-weight)` | Body text weight. | Web, Capacitor, NativeScript |
+| `--pw_Panel_root_default_line-height` | `root` | `default` | `line-height` | `var(--pw_line-height)` | Body line height. | Web, Capacitor, NativeScript |
+| `--pw_Panel_root_default_border-color` | `root` | `default` | `border-color` | `var(--pw_border-color)` | Optional border colour. | Web, Capacitor, NativeScript |
+| `--pw_Panel_root_default_border-width` | `root` | `default` | `border-width` | `var(--pw_border-width)` | Optional border width. | Web, Capacitor, NativeScript |
+| `--pw_Panel_root_default_border-style` | `root` | `default` | `border-style` | `var(--pw_border-style)` | Optional border style. | Web, Capacitor, NativeScript |
+| `--pw_Panel_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Optional corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Panel_header_default_padding` | `header` | `default` | `padding` | `var(--pw_padding)` | Header spacing. | Web, Capacitor, NativeScript |
+| `--pw_Panel_header_default_background-color` | `header` | `default` | `background-color` | `var(--pw_control_background-color)` | Header background. | Web, Capacitor, NativeScript |
+| `--pw_Panel_header_default_border-bottom` | `header` | `default` | `border-bottom` | shared border | Header separator. | Web, Capacitor, NativeScript |
+| `--pw_Panel_header_default_color` | `header` | `default` | `color` | `var(--pw_text_strong_color)` | Header foreground. | Web, Capacitor, NativeScript |
+| `--pw_Panel_header_default_font-size` | `header` | `default` | `font-size` | `1em` | Heading text size. | Web, Capacitor, NativeScript |
+| `--pw_Panel_header_default_font-weight` | `header` | `default` | `font-weight` | `var(--pw_bold_font-weight)` | Heading weight. | Web, Capacitor, NativeScript |
+| `--pw_Panel_header_default_line-height` | `header` | `default` | `line-height` | `var(--pw_line-height)` | Heading line height. | Web, Capacitor, NativeScript |
+| `--pw_Panel_close-button_default_background-color` | `close-button` | `default` | `background-color` | header background | Close-button background. | Web, Capacitor, NativeScript |
+| `--pw_Panel_close-button_hover_background-color` | `close-button` | `hover` | `background-color` | header colour | Hover background. | Web, Capacitor |
+| `--pw_Panel_close-button_default_min-width` | `close-button` | `default` | `min-width` | `1.563em` | Close-button width, matching Notification. | Web, Capacitor, NativeScript |
+| `--pw_Panel_close-button_default_height` | `close-button` | `default` | `height` | `1.563em` | Close-button height, matching Notification. | Web, Capacitor, NativeScript |
+| `--pw_Panel_close-button_default_transition-duration` | `close-button` | `default` | `transition-duration` | `0.5s` | Visual transition duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_Panel_close-bar_default_background-color` | `close-bar` | `default` | `background-color` | header colour | Close glyph colour. | Web, Capacitor, NativeScript |
+| `--pw_Panel_close-bar_hover_background-color` | `close-bar` | `hover` | `background-color` | close-button background | Hover glyph colour. | Web, Capacitor |
+| `--pw_Panel_footer_default_padding` | `footer` | `default` | `padding` | header padding | Footer spacing. | Web, Capacitor, NativeScript |
+| `--pw_Panel_footer_default_background-color` | `footer` | `default` | `background-color` | header background | Footer background. | Web, Capacitor, NativeScript |
+| `--pw_Panel_footer_default_border-top` | `footer` | `default` | `border-top` | header separator | Footer separator. | Web, Capacitor, NativeScript |
+
+```xts
+import { useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { panelMediator } from '@pastweb/components-core/Panel';
+import { DEFAULT_PROPS } from './constants';
+
+export function Panel(props: PanelProps) {
+  const p = withDefaultProps<PanelDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<PanelMediator>(panelMediator, p);
+  const s = m.state;
+  const Heading = s.heading;
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <article
+      id={s.id}
+      class={p.cls('Panel', {
+        'has-border': p.border,
+        'has-border-radius': p.borderRadius,
+      }, p.className)}
+      aria-label={s.ariaLabel}
+      aria-labelledby={s.titleId}
+    >
+      <header class={p.cls('header', { rtl: p.rtl })}>
+        <slot name="header">
+          <Heading #if={p.title} id={s.titleId} class={p.cls('title')}>{p.title}</Heading>
+          <button #if={p.closeButton} type="button" class={p.cls('closeButton')} @click={m.onClose} aria-label={p.closeLabel}>
+            <span class={p.cls('closeBar')} aria-hidden="true" />
+            <span class={p.cls('closeBar')} aria-hidden="true" />
+          </button>
+        </slot>
+      </header>
+      <div class={p.cls('content')} #style={p.contentPadding ? { padding: p.contentPadding } : {}}>
+        <slot />
+      </div>
+      <slot name="footer" map={content => <footer class={p.cls('footer')}>{content}</footer>} />
+    </article>
+  );
+}
+```
+
+## Keyboard interaction
+
+- The close action is a native button and is operable with `Enter` or `Space`.
+- Body content is not interactive unless projected content supplies its own
+  controls.
+
+## Accessibility notes
+
+- The default title is a native heading connected to the article through
+  `aria-labelledby` and the `title${id}` relationship ID.
+- Without a title, `ariaLabel` can provide the article's accessible name. The
+  default is an empty string, which omits the name.
+- The close action is a native button with a configurable name. Decorative close
+  bars are excluded from the accessibility tree.
+- A custom header must preserve an appropriate heading and close-action name.
+- Shared web styles match the Notification close control size, with visible
+  keyboard focus, forced-colours treatment, and reduced-motion behavior.
+
+## Known limitations
+
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA landmark regions: https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/
+- GOV.UK Panel guidance: https://design-system.service.gov.uk/components/panel/
+- GOV.UK headings guidance: https://design-system.service.gov.uk/styles/headings/

package/dist/Placeholder/README.md

@@ -0,0 +1,124 @@
+# Placeholder
+
+Placeholder renders a non-interactive shape that stands in for content that has
+not loaded yet. Its rendering contract targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use Placeholder to reserve layout while content loads. Keep placeholders
+decorative when several shapes compose one skeleton, and announce loading once
+on a parent region or with a single non-decorative Placeholder. Do not rely on
+the pulse animation as the only loading signal. Use Spinner for a compact
+indeterminate status, and ProgressBar when completion can be calculated.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `ariaLabel` | `string` | no | `"Loading"` | Names the status when the placeholder is not decorative. Pass an empty string to omit the name. |
+| `className` | `string` | no | `""` | Adds classes to the root, including shape utilities. |
+| `decorative` | `boolean` | no | `true` | Removes status semantics, hides the shape from the accessibility tree, and applies `is-decorative`. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaHidden` | `true \| undefined` | Is `true` when the placeholder is decorative; otherwise omitted. Renderers use this value directly for `aria-hidden`. |
+| `ariaLabel` | `string \| undefined` | Normalized status name. Decorative and empty labels are omitted. |
+| `ariaLive` | `'polite' \| undefined` | Is `polite` unless decorative. |
+| `role` | `'status' \| undefined` | Is `status` unless decorative. |
+
+## Utility classes
+
+Apply these classes through `className`. The default shape is a full-width bar
+at Button height using the same `--pw_border-radius` token as Button.
+`is-circle`, `is-square`, and `is-block` replace that size. `is-rounded` and
+`is-pill` change the corner radius and can combine with the default, square, or
+block shapes. A circle keeps a 50% radius.
+
+| Class | Description |
+|---|---|
+| `is-circle` | Equal sides and a circular radius, for avatars and round media. |
+| `is-square` | Equal sides with the default corner radius. |
+| `is-block` | A taller full-width rectangle, for images and cards. |
+| `is-rounded` | Uses the rounded corner-radius token. |
+| `is-pill` | Uses a fully rounded capsule radius. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Placeholder_root_default_color` | `root` | `default` | `color` | `var(--pw_text_color)` | Colour used by the `currentcolor` fill. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_default_background-color` | `root` | `default` | `background-color` | `currentcolor` | Placeholder fill. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_default_opacity` | `root` | `default` | `opacity` | `0.5` | Resting fill opacity. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_pulse_opacity` | `root` | `pulse` | `opacity` | `0.2` | Glow opacity at the midpoint of the pulse. | Web, Capacitor; NativeScript adapter |
+| `--pw_Placeholder_root_default_width` | `root` | `default` | `width` | `100%` | Default width. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_default_height` | `root` | `default` | `height` | `2.75em` | Default height, matching Button. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Default corner radius, matching Button. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_rounded_border-radius` | `root` | `rounded` | `border-radius` | `var(--pw_rounded_border-radius)` | Corner radius for `is-rounded`. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_pill_border-radius` | `root` | `pill` | `border-radius` | `999px` | Corner radius for `is-pill`. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_circle_width` | `root` | `circle` | `width` | `3em` | Width for `is-circle`. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_circle_height` | `root` | `circle` | `height` | `3em` | Height for `is-circle`. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_square_width` | `root` | `square` | `width` | `3em` | Width for `is-square`. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_square_height` | `root` | `square` | `height` | `3em` | Height for `is-square`. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_block_width` | `root` | `block` | `width` | `100%` | Width for `is-block`. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_block_height` | `root` | `block` | `height` | `8em` | Height for `is-block`. | Web, Capacitor, NativeScript |
+| `--pw_Placeholder_root_default_animation-duration` | `root` | `default` | `animation-duration` | `2s` | Pulse duration. | Web, Capacitor; NativeScript adapter |
+
+```xts
+import { useMediator, withDefaultProps } from '@pastweb/x';
+import { placeholderMediator } from '@pastweb/components-core/Placeholder';
+import { DEFAULT_PROPS } from './constants';
+
+export function Placeholder(props: PlaceholderProps) {
+  const p = withDefaultProps<PlaceholderDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<PlaceholderMediator>(placeholderMediator, p);
+  const s = m.state;
+
+  return (
+    <div
+      class={p.cls('Placeholder', { 'is-decorative': p.decorative }, p.className)}
+      role={s.role}
+      aria-label={s.ariaLabel}
+      aria-live={s.ariaLive}
+      aria-hidden={s.ariaHidden}
+    />
+  );
+}
+```
+
+## Keyboard interaction
+
+- Placeholder is not interactive. It does not enter the tab order.
+
+## Accessibility notes
+
+- Placeholders are decorative by default and are removed from the accessibility
+  tree with `aria-hidden`.
+- A non-decorative Placeholder exposes `role="status"`, a polite live region,
+  and `ariaLabel`. Use that mode only for a single loading signal.
+- When several placeholders compose a skeleton, keep them decorative and
+  announce loading once on a parent region.
+- The pulse animation is suppressed when the user prefers reduced motion.
+- Do not use Placeholder as an unlabeled interactive control.
+
+## Native renderer mapping
+
+NativeScript renderers map the shape to a native view with the configured size
+and corner radius. Decorative placeholders disable native accessibility
+exposure; a non-decorative placeholder maps `ariaLabel` intent to
+`accessibilityLabel` and status semantics. Do not copy ARIA attributes into
+native markup.
+
+## Known limitations
+
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+- The fill colour must remain distinguishable from the page background.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA status guidance: https://www.w3.org/WAI/ARIA/apg/patterns/
+- GOV.UK components guidance: https://design-system.service.gov.uk/components/

package/dist/ProgressBar/README.md

@@ -0,0 +1,137 @@
+# ProgressBar
+
+ProgressBar communicates the completion of a determinate task in linear or
+circular form. Its rendering contract targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use it when a numeric completion value is known, such as an upload or processing
+task. Use a separate indeterminate status indicator when completion cannot be
+calculated. Keep important status text available as accessible value text, not
+only as a visual bar.
+
+Do not use it as a multi-step form progress indicator. GOV.UK guidance is to
+avoid step trackers that show every question at once.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and part classes. |
+| `ariaLabel` | `string` | no | `"Progress"` | Accessible name for the progressbar. Pass an empty string to omit the name. |
+| `total` | `number` | conditional | - | Total used with `current`. |
+| `current` | `number` | conditional | - | Current value used with `total`. |
+| `percentage` | `number` | conditional | - | Direct percentage; clamped from 0 to 100. |
+| `label` | `string \| (values) => string` | no | `"%"` | Visible and accessible value text; use an empty string to hide it. |
+| `type` | `'linear' \| 'circular'` | no | `'linear'` | Visual presentation. |
+| `size` | `number` | no | `100` | Circular SVG coordinate size. |
+| `className` | `string` | no | `""` | Additional root classes. |
+
+Provide either `percentage` or both `total` and `current`.
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-rounded` | Uses the rounded progress-bar radius token. |
+| `is-outlined` | Uses the page background for the unfilled track so the bar reads as outlined. |
+| `is-full-width` | Expands the progress bar to the available width. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name. Empty labels are omitted. |
+| `circumference` | `number` | Circular stroke length. |
+| `labelContent` | `string \| null` | Visible value label, or `null` when `label` is empty. |
+| `offset` | `number` | Circular stroke offset for the remaining portion. |
+| `percentage` | `number` | Completion from 0 to 100. Renderers use this for `aria-valuenow`. |
+| `radius` | `number` | Circular track radius from `size`. |
+| `valueText` | `string` | Accessible value text. Falls back to `percentage%` when the label is hidden. |
+| `width` | `string` | Linear filler width as a percentage string. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_ProgressBar_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_control_background-color)` | Unfilled track colour. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_root_default_border-color` | `root` | `default` | `border-color` | `var(--pw_border-color)` | Linear border colour. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Linear corner radius. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_root_rounded_border-radius` | `root` | `rounded` | `border-radius` | `var(--pw_rounded_border-radius)` | Corner radius for `is-rounded`. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_root_default_border-style` | `root` | `default` | `border-style` | `var(--pw_border-style)` | Linear border style. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_root_default_border-width` | `root` | `default` | `border-width` | `var(--pw_border-width)` | Linear border width. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_label_default_color` | `label` | `default` | `color` | `inherit` | Value-label colour. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_fill_default_background-color` | `fill` | `default` | `background-color` | border colour | Linear completion colour. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_fill_default_stroke` | `fill` | `default` | `stroke` | border colour | Circular completion stroke. | Web, Capacitor |
+| `--pw_ProgressBar_linear_default_height` | `linear` | `default` | `height` | `2em` | Linear bar height. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_circular_default_width` | `circular` | `default` | `width` | `5em` | Circular width. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_circular_default_height` | `circular` | `default` | `height` | `5em` | Circular height. | Web, Capacitor, NativeScript |
+| `--pw_ProgressBar_circle_default_stroke-width` | `circle` | `default` | `stroke-width` | `0.5em` | Circular stroke width. | Web, Capacitor |
+| `--pw_ProgressBar_circle_default_stroke-linecap` | `circle` | `default` | `stroke-linecap` | `round` | Circular stroke cap. | Web, Capacitor |
+
+```xts
+import { useMediator, withDefaultProps } from '@pastweb/x';
+import { progressbarMediator } from '@pastweb/components-core/ProgressBar';
+import { DEFAULT_PROPS } from './constants';
+
+export function ProgressBar(props: ProgressBarProps) {
+  const p = withDefaultProps<ProgressBarDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<ProgressBarMediator>(progressbarMediator, p);
+  const s = m.state;
+
+  return (
+    <div
+      class={p.cls('ProgressBar', `type-${p.type}`, p.className)}
+      role="progressbar"
+      aria-label={s.ariaLabel}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={s.percentage}
+      aria-valuetext={s.valueText}
+    >
+      <div #if={p.type === 'linear'} class={p.cls('linear')}>
+        <div class={p.cls('filler')} #style={{ width: s.width }}>
+          <div #if={s.labelContent} class={p.cls('label')}>{s.labelContent}</div>
+        </div>
+      </div>
+      <div #if={p.type === 'circular'} class={p.cls('circular')}>
+        <svg class={p.cls('svg')} viewBox={`0 0 ${p.size} ${p.size}`} aria-hidden="true">
+          <circle class={p.cls('track')} cx={p.size / 2} cy={p.size / 2} r={s.radius} />
+          <circle class={p.cls('fill')} cx={p.size / 2} cy={p.size / 2} r={s.radius}
+            stroke-dasharray={s.circumference} stroke-dashoffset={s.offset} />
+        </svg>
+        <div #if={s.labelContent} class={p.cls('label')}>{s.labelContent}</div>
+      </div>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- ProgressBar is not interactive. It does not enter the tab order.
+
+## Accessibility notes
+
+- The web renderer exposes the `progressbar` role, a name, and values from 0 to
+  100. The SVG is decorative.
+- The default accessible name is `Progress`. An explicit empty string omits the
+  name.
+- Visible `label` content is also used as `aria-valuetext`. Hiding the label
+  still exposes a numeric value text.
+- Shared web styles support `forced-colors` and disable non-essential
+  transitions under `prefers-reduced-motion`.
+
+## Known limitations
+
+- ProgressBar is determinate only. It does not represent unknown remaining time.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Meter pattern: https://www.w3.org/WAI/ARIA/apg/patterns/meter/
+- GOV.UK components: https://design-system.service.gov.uk/components/

package/dist/Radio/README.md

@@ -0,0 +1,144 @@
+# Radio
+
+Radio presents a labelled group in which exactly one enabled option can be
+selected. Its rendering contract follows the WAI-ARIA Radio Group pattern and
+targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use radios when choices are mutually exclusive and should remain visible. Use
+Select for a long option list. Provide a concise group label and clear option
+labels. Do not pre-select an option unless a default is required.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component, part, and state classes. |
+| `ariaLabel` | `string` | no | `"Radio options"` | Names the group when `label` is absent. Pass an empty string to omit the name. |
+| `id` | `string` | no | generated | Stable group and relationship ID base. Generated IDs use the `radio` prefix. Explicit IDs are stored as `_${id}`. |
+| `label` | `string` | no | `""` | Visible group label. |
+| `labelPlacement` | `Placement` | no | `'top-start'` | Group-label placement. |
+| `name` | `string` | no | generated group ID | Shared native form name. |
+| `options` | `RadioOption[]` | yes | - | Options to render. |
+| `orientation` | `'horizontal' \| 'vertical' \| string` | no | `'horizontal'` | Option layout. |
+| `disabled` | `boolean` | no | - | Disables every option and applies `is-disabled`. |
+| `value` | `string` | no | `""` | Selected value. |
+| `onChange` | `(value, event) => void` | no | noop | Reports selection. |
+| `className` | `string` | no | `""` | Additional root classes. |
+
+`RadioOption` accepts `label`, `value`, optional `id`, `name`, `disabled`,
+`tabIndex`, and `labelPosition`. The option default is `labelPosition: 'right'`.
+Do not set `tabIndex` on every option; native radios
+keep only the selected or first available option in sequential tab order.
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized group name when no visible `label` is present. Empty labels are omitted. |
+| `groupId` | `string` | Group ID from an explicit `id` or a generated `radio` prefix. |
+| `groupLabelId` | `string \| undefined` | Label relationship ID `label${groupId}` when visible label text is present; otherwise omitted. |
+| `isDisabled` | `true \| undefined` | Is `true` when the group is disabled; otherwise omitted. Renderers use this value directly for `.is-disabled`, `aria-disabled`, and native `disabled`. |
+| `value` | `string` | Selected option value. |
+
+Option IDs are `option${groupId}${index}` unless an option supplies an explicit
+`id`.
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Radio_root_default_margin` | `root` | `default` | `margin` | shared margins | Group spacing. | Web, Capacitor, NativeScript |
+| `--pw_Radio_root_default_font-size` | `root` | `default` | `font-size` | `var(--pw_font-size)` | Group text size. | Web, Capacitor, NativeScript |
+| `--pw_Radio_root_default_font-weight` | `root` | `default` | `font-weight` | `var(--pw_semibold_font-weight)` | Group text weight. | Web, Capacitor, NativeScript |
+| `--pw_Radio_root_default_line-height` | `root` | `default` | `line-height` | `var(--pw_line-height)` | Group line height. | Web, Capacitor, NativeScript |
+| `--pw_Radio_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled appearance. | Web, Capacitor, NativeScript |
+| `--pw_Radio_option_default_margin` | `option` | `default` | `margin` | shared margins | Horizontal option spacing. | Web, Capacitor, NativeScript |
+| `--pw_Radio_option_vertical_margin` | `option` | `vertical` | `margin` | `1em 0.5em` | Vertical option spacing. | Web, Capacitor, NativeScript |
+| `--pw_Radio_control_default_width` | `control` | `default` | `width` | `2.375em` | Control width. | Web, Capacitor, NativeScript |
+| `--pw_Radio_control_default_height` | `control` | `default` | `height` | `2.375em` | Control height. | Web, Capacitor, NativeScript |
+| `--pw_Radio_control_default_background-color` | `control` | `default` | `background-color` | `var(--pw_control_background-color)` | Control background. | Web, Capacitor, NativeScript |
+| `--pw_Radio_control_default_border-color` | `control` | `default` | `border-color` | `var(--pw_border-color)` | Control border colour. | Web, Capacitor, NativeScript |
+| `--pw_Radio_control_default_border-radius` | `control` | `default` | `border-radius` | `var(--pw_rounded_border-radius)` | Control shape. | Web, Capacitor, NativeScript |
+| `--pw_Radio_control_default_border-style` | `control` | `default` | `border-style` | `var(--pw_border-style)` | Control border style. | Web, Capacitor, NativeScript |
+| `--pw_Radio_control_default_border-width` | `control` | `default` | `border-width` | `var(--pw_border-width)` | Control border width. | Web, Capacitor, NativeScript |
+| `--pw_Radio_control_default_transition-duration` | `control` | `default` | `transition-duration` | `var(--pw_transition-duration)` | Indicator transition duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_Radio_control_hover_box-shadow` | `control` | `hover` | `box-shadow` | shared inset shadow | Hover treatment. | Web, Capacitor |
+| `--pw_Radio_control_focus_box-shadow` | `control` | `focus` | `box-shadow` | shared focus shadow | Keyboard focus treatment. | Web, Capacitor |
+| `--pw_Radio_indicator_default_width` | `indicator` | `default` | `width` | `1em` | Indicator width. | Web, Capacitor, NativeScript |
+| `--pw_Radio_indicator_default_height` | `indicator` | `default` | `height` | `1em` | Indicator height. | Web, Capacitor, NativeScript |
+| `--pw_Radio_indicator_default_background-color` | `indicator` | `default` | `background-color` | `var(--pw_text_strong_color)` | Selected indicator colour. | Web, Capacitor, NativeScript |
+| `--pw_Radio_label_default_color` | `label` | `default` | `color` | `var(--pw_label_text_color)` | Label colour. | Web, Capacitor, NativeScript |
+
+```xts
+import { useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { radioMediator } from '@pastweb/components-core/Radio';
+import { DEFAULT_PROPS } from './constants';
+
+export function Radio(props: RadioProps) {
+  const p = withDefaultProps<RadioDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<RadioMediator>(radioMediator, p);
+  const s = m.state;
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      id={s.groupId}
+      class={p.cls('Radio', `label-${p.labelPlacement}`, { 'is-disabled': s.isDisabled }, p.className)}
+      role="radiogroup"
+      aria-labelledby={s.groupLabelId}
+      aria-label={s.ariaLabel}
+      aria-disabled={s.isDisabled}
+    >
+      <div class={p.cls('buttons', { vertical: p.orientation === 'vertical' })}>
+        {p.options.map((option, index) => (
+          <label class={p.cls('group', `label-${option.labelPosition || 'right'}`, {
+            'is-checked': s.value === `${option.value}`,
+            'is-disabled': s.isDisabled || option.disabled,
+          })}>
+            <input type="radio" class={p.cls('input')} id={m.getOptionId(index, option.id)}
+              name={option.name || p.name || s.groupId} value={option.value}
+              checked={s.value === `${option.value}`} disabled={s.isDisabled || option.disabled}
+              @change={event => m.onChange(event.target.value, event)} />
+            <span class={p.cls('box')} aria-hidden="true"><span class={p.cls('indicator')} /></span>
+            <span class={p.cls('buttonLabel')}>{option.label}</span>
+          </label>
+        ))}
+      </div>
+      <span #if={p.label} id={s.groupLabelId} class={p.cls('label', p.labelPlacement)}>{p.label}</span>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Native radio inputs provide arrow-key selection within the group.
+- `Tab` and `Shift+Tab` move sequential focus to the selected or first available
+  option.
+- Disabled options and a disabled group are not operable.
+
+## Accessibility notes
+
+- Native radio inputs provide group semantics, checked state, and form behavior.
+  The visual control is decorative; the native input remains in the
+  accessibility tree and tab order.
+- The visible group label is connected through `aria-labelledby`. When it is
+  absent, `ariaLabel` names the group. The default name is `Radio options`.
+- Disabled state is reflected through `.is-disabled`, native `disabled`, and
+  `aria-disabled`.
+- Shared web styles provide visible keyboard focus, forced-colours treatment,
+  and reduced-motion behavior.
+
+## Known limitations
+
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Radio Group pattern: https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+- GOV.UK radios: https://design-system.service.gov.uk/components/radios/