@pastweb/components-core 2.0.0 → 2.2.0

package/dist/Input/README.md

@@ -0,0 +1,212 @@
+# Input
+
+Input renders a labelled native text, search, password, email, or number field
+with optional affixes, loading state, and number step controls. Its rendering
+contract targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use Input for short, single-line values. Use TextArea for multi-line content and
+a purpose-built control for dates or constrained choices. A visible label is
+preferred; placeholders do not replace labels.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component, part, and state classes. |
+| `ariaLabel` | `string` | no | `"Input"` | Names the input when no visible `label` is supplied. Pass an empty string to omit the accessible name, including when an external label is associated through `id`. |
+| `className` | `string` | no | `""` | Adds classes to the root. The `is-loading` class is also treated as a loading signal. |
+| `autocomplete` | `string` | no | - | Supplies the native autocomplete token. Use it for personal data and sign-in fields. |
+| `tabIndex` | `number` | no | `0` | Controls sequential focus order. Prefer document order. |
+| `type` | `'text' \| 'search' \| 'password' \| 'email' \| 'number'` | no | `'text'` | Selects native input behavior. |
+| `placeholder` | `string` | no | `""` | Supplies a short input hint. Do not use it as the only label. |
+| `disabled` | `boolean` | no | - | Makes the field unavailable. |
+| `loading` | `boolean` | no | - | Marks the field busy and temporarily unavailable. |
+| `required` | `boolean` | no | - | Marks the value as required. |
+| `name` | `string` | no | - | Supplies the form field name. |
+| `id` | `string` | no | generated | Supplies the native input ID. Generated IDs use the `input` prefix. |
+| `min` | `number` | no | - | Native minimum for number inputs. |
+| `max` | `number` | no | - | Native maximum for number inputs. |
+| `step` | `number` | no | - | Native step for number inputs. |
+| `value` | `string` | no | - | Controls the input value. |
+| `label` | `string` | no | `""` | Supplies the visible accessible label. |
+| `labelPlacement` | `Placement` | no | `'top-start'` | Positions the visible label. |
+| `incrementTitle` | `string` | no | `"Increment"` | Names the optional number increment control. |
+| `decrementTitle` | `string` | no | `"Decrement"` | Names the optional number decrement control. |
+| `onChange` | `(value: string, event?: unknown) => void` | no | noop | Reports value input. Programmatic number stepping has no renderer event. |
+| `onKeyDown` | `(event) => void` | no | noop | Reports available-field keyboard input. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name when no visible `label` is present. Empty labels are omitted. |
+| `disableDownBtn` | `true \| undefined` | Is `true` when the number value is at `min`; otherwise omitted. |
+| `disableUpBtn` | `true \| undefined` | Is `true` when the number value is at `max`; otherwise omitted. |
+| `inputId` | `string` | Native input ID from an explicit `id` or a generated `input` prefix. |
+| `isDisabled` | `true \| undefined` | Is `true` when the Input is disabled; otherwise omitted. Renderers use this value directly for `.is-disabled`, `aria-disabled`, and native `disabled` when loading is not also blocking the field. |
+| `isLoading` | `true \| undefined` | Is `true` when the Input is busy; otherwise omitted. Renderers use this value directly for `.is-loading` and `aria-busy`. |
+
+## Slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| `left` | Supplies a leading affix inside `.leftComponent`. | Empty. |
+| `right` | Supplies a trailing affix inside `.rightComponent`. | Empty. |
+| `loading` | Supplies the politely announced busy status. | A `loading` status region containing `Loading...`. |
+
+Affix content is not automatically decorative. Renderers must preserve an
+interactive affix's accessible name and keyboard behavior. Decorative icons in
+an affix should be marked `aria-hidden` by the consumer.
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-rounded` | Uses the rounded input radius token. |
+| `is-full-width` | Expands the field to the available width. |
+| `is-outlined` | Inverts affix icon colour against the control background. |
+| `is-loading` | Compatibility signal for the loading state. Prefer the `loading` prop. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Input_root_default_margin` | `root` | `default` | `margin` | `var(--pw_vertical_margin)` | Component spacing. | Web, Capacitor, NativeScript |
+| `--pw_Input_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled opacity. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_default_min-width` | `container` | `default` | `min-width` | `5em` | Minimum control width. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_default_min-height` | `container` | `default` | `min-height` | `2.75em` | Minimum control height, with a 44px web target. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_default_background-color` | `container` | `default` | `background-color` | `var(--pw_control_background-color)` | Control background. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_default_color` | `container` | `default` | `color` | `var(--pw_text_color)` | Input and affix foreground. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_default_border-color` | `container` | `default` | `border-color` | `var(--pw_border-color)` | Control border colour. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_default_border-width` | `container` | `default` | `border-width` | `var(--pw_border-width)` | Control border width. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_default_border-style` | `container` | `default` | `border-style` | `var(--pw_border-style)` | Control border style. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_default_border-radius` | `container` | `default` | `border-radius` | `var(--pw_border-radius)` | Control corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_rounded_border-radius` | `container` | `rounded` | `border-radius` | `var(--pw_rounded_border-radius)` | Rounded variant radius. | Web, Capacitor, NativeScript |
+| `--pw_Input_container_hover_box-shadow` | `container` | `hover` | `box-shadow` | shared inset shadow | Pointer hover treatment. | Web, Capacitor |
+| `--pw_Input_container_focus-visible_box-shadow` | `container` | `focus-visible` | `box-shadow` | shared focus shadow | Keyboard focus treatment. | Web, Capacitor |
+| `--pw_Input_container_default_transition-duration` | `container` | `default` | `transition-duration` | `var(--pw_transition-duration)` | Visual state duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_Input_input_default_padding` | `input` | `default` | `padding` | `var(--pw_padding)` | Input spacing. | Web, Capacitor, NativeScript |
+| `--pw_Input_input_default_font-size` | `input` | `default` | `font-size` | `var(--pw_font-size)` | Input text size. | Web, Capacitor, NativeScript |
+| `--pw_Input_input_default_font-weight` | `input` | `default` | `font-weight` | `var(--pw_font-weight)` | Input text weight. | Web, Capacitor, NativeScript |
+| `--pw_Input_affix_default_padding` | `affix` | `default` | `padding` | `var(--pw_horizontal_padding)` | Affix spacing. | Web, Capacitor, NativeScript |
+| `--pw_Input_label_default_color` | `label` | `default` | `color` | `var(--pw_label_text_color)` | Label foreground. | Web, Capacitor, NativeScript |
+| `--pw_Input_label_default_font-size` | `label` | `default` | `font-size` | `var(--pw_font-size)` | Label font size. | Web, Capacitor, NativeScript |
+| `--pw_Input_label_default_font-weight` | `label` | `default` | `font-weight` | `var(--pw_semibold_font-weight)` | Label weight. | Web, Capacitor, NativeScript |
+| `--pw_Input_number-buttons_default_width` | `number-buttons` | `default` | `width` | `2em` | Step-control column width. | Web, Capacitor, NativeScript |
+| `--pw_Input_number-button_default_min-height` | `number-button` | `default` | `min-height` | `1.5em` | Step-control minimum height. | Web, Capacitor, NativeScript |
+| `--pw_Input_number-button_default_font-size` | `number-button` | `default` | `font-size` | `0.813em` | Step-control glyph size. | Web, Capacitor, NativeScript |
+
+```xts
+import {
+  useBeforeUnmount,
+  useMediator,
+  useMounted,
+  useRef,
+  withDefaultProps,
+} from '@pastweb/x';
+import { inputMediator } from '@pastweb/components-core/Input';
+import { DEFAULT_PROPS } from './constants';
+
+export function Input(props: InputProps) {
+  const p = withDefaultProps<InputDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<InputMediator>(inputMediator, p);
+  const s = m.state;
+  const inputRef = useRef(null);
+
+  useMounted(() => m.useMounted(inputRef.value));
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      class={p.cls('Input', `label-${p.labelPlacement}`, p.className, {
+        'is-disabled': s.isDisabled,
+        'is-loading': s.isLoading,
+      })}
+      aria-busy={s.isLoading}
+    >
+      <div class={p.cls('inputContainer')}>
+        <slot name="left" map={content => <span class={p.cls('leftComponent')}>{content}</span>} />
+        <input
+          #ref={inputRef}
+          class={p.cls('inputElement')}
+          type={p.type}
+          tabIndex={p.tabIndex}
+          autocomplete={p.autocomplete}
+          placeholder={p.placeholder}
+          disabled={s.isDisabled || s.isLoading}
+          aria-disabled={s.isDisabled}
+          name={p.name}
+          id={s.inputId}
+          value={p.value}
+          required={p.required}
+          max={p.max}
+          min={p.min}
+          step={p.step}
+          aria-label={s.ariaLabel}
+          @input={event => m.onChange(event.target.value, event)}
+          @keydown={m.onKeyDown}
+        />
+        <div #if={p.type === 'number'} class={p.cls('number-buttons')}>
+          <button type="button" class={p.cls('number-btn')} @click={m.stepUp} disabled={s.isDisabled || s.isLoading || s.disableUpBtn} aria-label={p.incrementTitle}>▲</button>
+          <button type="button" class={p.cls('number-btn')} @click={m.stepDown} disabled={s.isDisabled || s.isLoading || s.disableDownBtn} aria-label={p.decrementTitle}>▼</button>
+        </div>
+        <slot name="right" map={content => <span class={p.cls('rightComponent')}>{content}</span>} />
+        <div #if={s.isLoading} class={p.cls('loading')} role="status" aria-live="polite">
+          <slot name="loading">Loading...</slot>
+        </div>
+      </div>
+      <label #if={p.label} class={p.cls('label', p.labelPlacement)} for={s.inputId}>{p.label}</label>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- `Tab` and `Shift+Tab` move focus to and from the native input in document order.
+- Printable keys, `Backspace`, and `Delete` edit the value through native input
+  behavior.
+- `ArrowUp` and `ArrowDown` on a number input use native stepping. The mediator
+  does not duplicate those keys.
+- Number-step buttons are `type="button"` and are operable with `Enter` or
+  `Space` when available.
+
+## Accessibility notes
+
+- The native input supplies keyboard, form, validation, and autocomplete behavior.
+- The visible label and generated or explicit ID remain connected.
+- When visible label text is absent, the mediator exposes `ariaLabel`. The
+  default name is `Input`. An explicit empty string omits the name so an
+  external label can name the control through `for` and `id`.
+- Disabled inputs use `.is-disabled`, the native `disabled` property, and
+  `aria-disabled="true"`.
+- Loading inputs use `.is-loading`, `aria-busy="true"`, and native `disabled`.
+  Number-step buttons mirror the same unavailable state.
+- Native Arrow Up and Arrow Down behavior is not duplicated by the mediator.
+- Shared web styles provide at least a 44 by 44 CSS-pixel text-field target,
+  visible keyboard focus, forced-colours treatment, and reduced-motion behavior.
+
+## Native renderer mapping
+
+NativeScript renderers map the contract to the appropriate editable native view,
+keyboard type, secure-entry state, form constraints, label relationship, busy
+state, and native accessibility name. Web DOM refs and events are renderer
+details. Do not copy ARIA attributes into native markup.
+
+## Known limitations
+
+- Placeholders do not replace a visible or accessible name.
+- Hint and error text are not built in. Associate them with the native input
+  through `id` when the surrounding form provides that content.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Textbox pattern: https://www.w3.org/WAI/ARIA/apg/patterns/
+- GOV.UK text input guidance: https://design-system.service.gov.uk/components/text-input/

package/dist/Link/README.md

@@ -0,0 +1,108 @@
+# Link
+
+Link renders a native anchor for navigation and prevents unavailable links from
+remaining actionable or focusable. Its rendering contract follows the WAI-ARIA
+Link pattern and targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use Link to navigate to another resource or location. Use Button for actions on
+the current page. Link text should describe its destination without relying on
+surrounding text such as “click here.”
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `href` | `string` | no | `"#"` | Supplies the destination. Prefer a real URL. |
+| `className` | `string` | no | `""` | Adds classes to the anchor. |
+| `disabled` | `boolean` | no | - | Removes navigation and sequential focus. |
+| `target` | `'_self' \| '_blank'` | no | `'_self'` | Selects the browsing context. New-window links must communicate that behavior in their accessible content. |
+| `id` | `string` | no | - | Supplies the anchor ID. |
+| `onClick` | `(event: unknown) => void` | no | noop | Reports available-link activation. Renderers may narrow the event type. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `isDisabled` | `true \| undefined` | Is `true` when the link is unavailable; otherwise omitted. Renderers use this value directly for `.is-disabled`, `aria-disabled`, omitted `href`, and `tabIndex={-1}`. |
+
+## Slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| default | Supplies descriptive link content. | Empty. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Link_root_default_color` | `root` | `default` | `color` | `var(--pw_link_color)` | Link foreground. | Web, Capacitor, NativeScript |
+| `--pw_Link_root_hover_color` | `root` | `hover` | `color` | `var(--pw_link_hover_color)` | Pointer hover foreground. | Web, Capacitor |
+| `--pw_Link_root_default_font-size` | `root` | `default` | `font-size` | `var(--pw_link_font-size)` | Link text size. | Web, Capacitor, NativeScript |
+| `--pw_Link_root_default_font-weight` | `root` | `default` | `font-weight` | `var(--pw_link_font-weight)` | Link text weight. | Web, Capacitor, NativeScript |
+| `--pw_Link_root_default_line-height` | `root` | `default` | `line-height` | `var(--pw_link_line-height)` | Link line height. | Web, Capacitor, NativeScript |
+| `--pw_Link_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled opacity. | Web, Capacitor, NativeScript |
+
+```xts
+import { useMediator, withDefaultProps } from '@pastweb/x';
+import { linkMediator } from '@pastweb/components-core/Link';
+import { DEFAULT_PROPS } from './constants';
+
+export function Link(props: LinkProps) {
+  const p = withDefaultProps<LinkDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<LinkMediator>(linkMediator, p);
+  const s = m.state;
+
+  return (
+    <a
+      class={p.cls('Link', p.className, { 'is-disabled': s.isDisabled })}
+      href={s.isDisabled ? undefined : p.href}
+      target={p.target}
+      rel={p.target === '_blank' ? 'noopener noreferrer' : undefined}
+      id={p.id}
+      aria-disabled={s.isDisabled}
+      tabIndex={s.isDisabled ? -1 : undefined}
+      @click={m.onClick}
+    >
+      <slot />
+    </a>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Available links retain native anchor keyboard activation, typically `Enter`.
+- `Tab` and `Shift+Tab` move sequential focus to available links. Disabled
+  links leave the tab order.
+
+## Accessibility notes
+
+- Available links retain native anchor semantics and keyboard activation.
+- Disabled links omit `href`, expose `aria-disabled="true"`, leave sequential
+  focus, and prevent activation in the mediator.
+- Links opening a new browsing context use `noopener noreferrer`; their content
+  should also tell users that a new tab or window will open.
+- Shared web styles keep underlining, visible keyboard focus, and
+  forced-colours treatment.
+
+## Native renderer mapping
+
+NativeScript renderers map the destination to native URL navigation, unavailable
+state to native enabled/focus/accessibility properties, and external navigation
+to the platform link-opening service. Do not copy ARIA attributes into native
+markup.
+
+## Known limitations
+
+- Placeholders such as `href="#"` do not describe a destination.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Link pattern: https://www.w3.org/WAI/ARIA/apg/patterns/link/
+- GOV.UK links guidance: https://www.gov.uk/guidance/content-design/links

package/dist/Notification/README.md

@@ -0,0 +1,141 @@
+# Notification
+
+Notification presents a short, politely announced message with optional title,
+close action, and footer content. Its rendering contract targets WCAG 2.2
+Level AA.
+
+## When to use
+
+Use Notification for non-urgent status information that may remain in the page.
+Use an alert pattern for urgent information requiring immediate attention, and a
+dialog when users must make a decision before continuing.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component, part, and state classes. |
+| `ariaLabel` | `string` | no | `""` | Names the optional notification region. Pass an empty string to omit the region role. |
+| `className` | `string` | no | `""` | Adds classes to the root article. |
+| `closeButton` | `boolean` | no | `true` | Displays the native close button. |
+| `closeLabel` | `string` | no | `"Close notification"` | Names the close button. |
+| `onClose` | `() => void` | no | noop | Reports close intent. |
+| `rtl` | `boolean` | no | `false` | Reverses header content order. |
+| `title` | `string` | no | - | Supplies the default title content. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name. Empty labels are omitted. |
+| `role` | `'region' \| undefined` | Is `region` when `ariaLabel` supplies a name; otherwise omitted. |
+
+## Slots
+
+| SlotName | Description | Default content | Props |
+|---|---|---|---|
+| default | Supplies the politely announced message. | Empty. | - |
+| `header` | Replaces title and close-button content inside the semantic header. | Title and optional close button. | `{ title, onClose }` |
+| `footer` | Supplies content wrapped in the semantic footer. | Empty. | - |
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-full-width` | Expands the notification to the available width. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Notification_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_control_background-color)` | Notification background. | Web, Capacitor, NativeScript |
+| `--pw_Notification_root_default_color` | `root` | `default` | `color` | `var(--pw_text_color)` | Message foreground. | Web, Capacitor, NativeScript |
+| `--pw_Notification_root_default_padding` | `root` | `default` | `padding` | `var(--pw_padding)` | Inner spacing. | Web, Capacitor, NativeScript |
+| `--pw_Notification_root_default_border-color` | `root` | `default` | `border-color` | `var(--pw_border-color)` | Border colour. | Web, Capacitor, NativeScript |
+| `--pw_Notification_root_default_border-width` | `root` | `default` | `border-width` | `var(--pw_border-width)` | Border width. | Web, Capacitor, NativeScript |
+| `--pw_Notification_root_default_border-style` | `root` | `default` | `border-style` | `var(--pw_border-style)` | Border style. | Web, Capacitor, NativeScript |
+| `--pw_Notification_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Notification_root_default_box-shadow` | `root` | `default` | `box-shadow` | shared shadow | Elevation. | Web, Capacitor |
+| `--pw_Notification_header_default_color` | `header` | `default` | `color` | `var(--pw_text_strong_color)` | Title foreground. | Web, Capacitor, NativeScript |
+| `--pw_Notification_header_default_font-size` | `header` | `default` | `font-size` | `1em` | Title text size. | Web, Capacitor, NativeScript |
+| `--pw_Notification_header_default_font-weight` | `header` | `default` | `font-weight` | `var(--pw_semibold_font-weight)` | Title weight. | Web, Capacitor, NativeScript |
+| `--pw_Notification_header_default_line-height` | `header` | `default` | `line-height` | `var(--pw_line-height)` | Title line height. | Web, Capacitor, NativeScript |
+| `--pw_Notification_header_default_margin-bottom` | `header` | `default` | `margin-bottom` | `0.5em` | Header spacing. | Web, Capacitor, NativeScript |
+| `--pw_Notification_close-button_default_background-color` | `close-button` | `default` | `background-color` | `transparent` | Close-button background. | Web, Capacitor, NativeScript |
+| `--pw_Notification_close-button_hover_background-color` | `close-button` | `hover` | `background-color` | header colour | Hover background. | Web, Capacitor |
+| `--pw_Notification_close-button_default_min-width` | `close-button` | `default` | `min-width` | `1.563em` | Close-button width, matching Panel. | Web, Capacitor, NativeScript |
+| `--pw_Notification_close-button_default_height` | `close-button` | `default` | `height` | `1.563em` | Close-button height, matching Panel. | Web, Capacitor, NativeScript |
+| `--pw_Notification_close-button_default_transition-duration` | `close-button` | `default` | `transition-duration` | `0.5s` | Visual transition duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_Notification_close-bar_default_background-color` | `close-bar` | `default` | `background-color` | header colour | Close glyph colour. | Web, Capacitor, NativeScript |
+| `--pw_Notification_close-bar_hover_background-color` | `close-bar` | `hover` | `background-color` | notification background | Hover glyph colour. | Web, Capacitor |
+| `--pw_Notification_footer_default_margin-top` | `footer` | `default` | `margin-top` | `0.5em` | Footer spacing. | Web, Capacitor, NativeScript |
+
+```xts
+import { useMediator, withDefaultProps } from '@pastweb/x';
+import { notificationMediator } from '@pastweb/components-core/Notification';
+import { DEFAULT_PROPS } from './constants';
+
+export function Notification(props: NotificationProps) {
+  const p = withDefaultProps<NotificationDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<NotificationMediator>(notificationMediator, p);
+  const s = m.state;
+
+  return (
+    <article
+      class={p.cls('Notification', p.className)}
+      role={s.role}
+      aria-label={s.ariaLabel}
+    >
+      <header #if={p.title || p.closeButton} class={p.cls('header', { rtl: p.rtl })}>
+        <slot name="header" props={{ title: p.title, onClose: m.onClose }}>
+          <span #if={p.title} class={p.cls('title')}>{p.title}</span>
+          <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')} role="status" aria-live="polite" aria-atomic="true">
+        <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`.
+- Message content is not interactive unless projected content supplies its own
+  controls.
+
+## Accessibility notes
+
+- Only message content is the polite live region; the interactive close button
+  is outside it.
+- The close action is a native button with a configurable accessible name.
+- `ariaLabel` creates a named region when consumers need direct navigation to a
+  persistent notification. The default is an empty string, which omits the
+  region role. Avoid unnecessary repeated regions.
+- Shared web styles match the Panel close control size, with visible keyboard
+  focus, forced-colours treatment, and reduced-motion behavior.
+
+## Native renderer mapping
+
+NativeScript renderers map the message to native polite announcement APIs, the
+close action to a native button, and optional region naming to native
+accessibility labels. Do not copy ARIA attributes into native markup.
+
+## Known limitations
+
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Status and alert patterns: https://www.w3.org/WAI/ARIA/apg/patterns/
+- GOV.UK notification banner: https://design-system.service.gov.uk/components/notification-banner/

package/dist/Pagination/README.md

@@ -0,0 +1,147 @@
+# Pagination
+
+Pagination provides bounded navigation through a known number of result pages.
+Its rendering contract targets WCAG 2.2 Level AA and follows GOV.UK pagination
+guidance for landmarks, current-page identification, and page naming.
+
+## When to use
+
+Use Pagination when a collection is split into stable, addressable pages. Prefer
+“load more” when preserving context matters more than direct page access. Do not
+use it for linear form journeys; use a continue action and a back link instead.
+Do not show pagination when there is only one page. Keep the current page
+synchronized with the URL when pages are navigable resources.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component, part, and state classes. |
+| `total` | `number` | yes | - | Supplies the number of pages. Values are floored and clamped to zero or greater. |
+| `current` | `number` | yes | - | Supplies the current one-based page. It is clamped to the available range. |
+| `ariaLabel` | `string` | no | `"Pagination"` | Names the navigation landmark. Pass an empty string to omit the name. Provide a unique name when more than one pagination control is on the page. |
+| `disabled` | `boolean` | no | - | Makes every navigation action unavailable. |
+| `onChange` | `(page: number) => void` | no | noop | Reports a valid changed page. |
+| `className` | `string` | no | `""` | Adds classes to the navigation root. |
+| `prev` | `unknown` | no | `◄` | Supplies previous visual content. |
+| `next` | `unknown` | no | `►` | Supplies next visual content. |
+| `prevAriaLabel` | `string` | no | `"Previous page"` | Names the previous control. |
+| `nextAriaLabel` | `string` | no | `"Next page"` | Names the next control. |
+| `pageAriaLabel` | `(page: number) => string` | no | `Page N` | Names a numbered page control. |
+| `jumpBackAriaLabel` | `string` | no | `"Jump backward through pages"` | Names the backward ellipsis jump control. |
+| `jumpForwardAriaLabel` | `string` | no | `"Jump forward through pages"` | Names the forward ellipsis jump control. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized navigation name. Empty labels are omitted. |
+| `current` | `number` | Clamped one-based page. Renderers use this for `.is-active` and `aria-current="page"`. |
+| `isDisabled` | `true \| undefined` | Is `true` when every action is unavailable; otherwise omitted. Renderers use this value directly for `.is-disabled` and page-control `disabled`. |
+| `isNextDisabled` | `true \| undefined` | Is `true` when next is unavailable; otherwise omitted. |
+| `isPrevDisabled` | `true \| undefined` | Is `true` when previous is unavailable; otherwise omitted. |
+| `pages` | `PaginationItem[]` | Visible numbered pages and ellipsis jump controls. |
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-rounded` | Uses the rounded control radius token. |
+| `is-full-width` | Expands the navigation to the available width. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Pagination_button_default_margin` | `button` | `default` | `margin` | `var(--pw_margin)` | Control spacing. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_padding` | `button` | `default` | `padding` | `var(--pw_padding)` | Control inner spacing. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_background-color` | `button` | `default` | `background-color` | `var(--pw_background-color)` | Control background. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_border-color` | `button` | `default` | `border-color` | `var(--pw_border-color)` | Control border colour. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_border-width` | `button` | `default` | `border-width` | `var(--pw_border-width)` | Control border width. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_border-style` | `button` | `default` | `border-style` | `var(--pw_border-style)` | Control border style. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_border-radius` | `button` | `default` | `border-radius` | `var(--pw_border-radius)` | Control corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_rounded_border-radius` | `button` | `rounded` | `border-radius` | `var(--pw_rounded_border-radius)` | Rounded control radius. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_color` | `button` | `default` | `color` | `var(--pw_text_strong_color)` | Control foreground. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_font-size` | `button` | `default` | `font-size` | `var(--pw_font-size)` | Control text size. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_font-weight` | `button` | `default` | `font-weight` | `var(--pw_semibold_font-weight)` | Control text weight. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_line-height` | `button` | `default` | `line-height` | `var(--pw_line-height)` | Control line height. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_default_transition-duration` | `button` | `default` | `transition-duration` | `var(--pw_transition-duration)` | Visual state duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_Pagination_button_disabled_opacity` | `button` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled control opacity. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_button_hover_box-shadow` | `button` | `hover` | `box-shadow` | shared inset shadow | Hover treatment. | Web, Capacitor |
+| `--pw_Pagination_button_focus_box-shadow` | `button` | `focus` | `box-shadow` | shared focus shadow | Keyboard focus treatment. | Web, Capacitor |
+| `--pw_Pagination_page_default_margin` | `page` | `default` | `margin` | shared page margin | Page-control spacing. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_page_active_color` | `page` | `active` | `color` | strong text colour | Current-page foreground. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_page_active_font-weight` | `page` | `active` | `font-weight` | bold | Current-page weight. | Web, Capacitor, NativeScript |
+| `--pw_Pagination_page_active_background-color` | `page` | `active` | `background-color` | control background | Current-page background. | Web, Capacitor, NativeScript |
+
+```xts
+import { useMediator, withDefaultProps } from '@pastweb/x';
+import { paginationMediator } from '@pastweb/components-core/Pagination';
+import { DEFAULT_PROPS } from './constants';
+
+export function Pagination(props: PaginationProps) {
+  const p = withDefaultProps<PaginationDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<PaginationMediator>(paginationMediator, p);
+  const s = m.state;
+
+  return (
+    <nav class={p.cls('Pagination', p.className, { 'is-disabled': s.isDisabled })} aria-label={s.ariaLabel}>
+      <button type="button" class={p.cls('button', 'previous')} disabled={s.isPrevDisabled} @click={m.onPrev} aria-label={p.prevAriaLabel}>
+        <render content={p.prev} />
+      </button>
+      <ul class={p.cls('pages')}>
+        <li #for={page of s.pages} class={p.cls('pageItem')}>
+          <button
+            type="button"
+            class={p.cls('button', 'page', { 'is-active': s.current === page })}
+            disabled={s.isDisabled}
+            aria-current={s.current === page ? 'page' : undefined}
+            aria-label={typeof page === 'number' ? p.pageAriaLabel(page) : page === '... ' ? p.jumpBackAriaLabel : p.jumpForwardAriaLabel}
+            @click={() => m.onPageChange(page)}
+          >
+            {page}
+          </button>
+        </li>
+      </ul>
+      <button type="button" class={p.cls('button', 'next')} disabled={s.isNextDisabled} @click={m.onNext} aria-label={p.nextAriaLabel}>
+        <render content={p.next} />
+      </button>
+    </nav>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Previous, next, page, and jump controls are native buttons and are operable
+  with `Enter` or `Space` when available.
+- `Tab` and `Shift+Tab` move through available controls in document order.
+- Disabled controls, including previous on the first page and next on the last
+  page, are not operable.
+
+## Accessibility notes
+
+- The component is a named navigation landmark containing native buttons in a
+  list. Native buttons are used because page changes are reported through
+  `onChange` rather than URL navigation.
+- The current numbered control exposes `aria-current="page"`.
+- Ellipses are explicit jump controls with meaningful accessible names, not
+  mislabeled page numbers. GOV.UK treats ellipses as non-interactive; this
+  contract keeps them operable so skipped ranges remain reachable by keyboard.
+- Previous and next remain in the layout and become native-disabled at the ends
+  of the range. All controls also mirror the disabled component state.
+- Shared web styles provide at least a 44 by 44 CSS-pixel target, visible 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 pagination: https://design-system.service.gov.uk/components/pagination/