@pastweb/components-core 2.0.0 → 2.2.0

package/dist/RangeSlider/README.md

@@ -0,0 +1,120 @@
+# RangeSlider
+
+RangeSlider selects one numeric value from a bounded range using the native
+range control. Its rendering contract follows the WAI-ARIA Slider pattern and
+targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use it when an approximate value is acceptable and the range is meaningful. Use
+a numeric input when users must enter an exact value. Always supply a visible
+`label` or a specific `ariaLabel`.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component, part, and state classes. |
+| `ariaLabel` | `string` | no | `"Range value"` | Names the slider when no visible label is supplied. Pass an empty string to omit the name. |
+| `id` | `string` | no | generated | Stable native input ID. Generated IDs use the `rangeSlider` prefix. Explicit IDs are stored as `_${id}`. |
+| `label` | `string` | no | `""` | Visible native label. |
+| `labelPlacement` | aligned placement | no | `'top-start'` | Label placement. |
+| `min` | `number` | yes | - | Minimum. |
+| `max` | `number` | yes | - | Maximum. |
+| `step` | `number` | no | browser default | Increment. |
+| `value` | `number` | no | range midpoint | Current value. |
+| `disabled` | `boolean` | no | - | Disables the native input and applies `is-disabled`. |
+| `onChange` | `(value, event) => void` | no | noop | Reports each value change. |
+| `onMouseUp` | `(value) => void` | no | noop | Compatibility callback reporting committed pointer or keyboard value. |
+| `className` | `string` | no | `""` | Additional root classes. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name when no visible `label` is present. Empty labels are omitted. |
+| `inputId` | `string` | Native input ID from an explicit `id` or a generated `rangeSlider` prefix. |
+| `isDisabled` | `true \| undefined` | Is `true` when the slider is disabled; otherwise omitted. Renderers use this value directly for `.is-disabled` and native `disabled`. |
+| `value` | `string` | Clamped current value as a string for the native range input. |
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-full-width` | Expands the slider to the available width. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_RangeSlider_root_default_margin` | `root` | `default` | `margin` | shared margins | Component spacing. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled appearance. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_track_default_height` | `track` | `default` | `height` | `0.8em` | Track height. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_track_default_background-color` | `track` | `default` | `background-color` | `var(--pw_control_background-color)` | Track background. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_track_default_border-color` | `track` | `default` | `border-color` | `var(--pw_border-color)` | Track and thumb border. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_track_default_border-radius` | `track` | `default` | `border-radius` | `var(--pw_border-radius)` | Track corners. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_track_default_border-style` | `track` | `default` | `border-style` | `var(--pw_border-style)` | Track and thumb border style. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_track_default_border-width` | `track` | `default` | `border-width` | `var(--pw_border-width)` | Track and thumb border width. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_thumb_default_width` | `thumb` | `default` | `width` | `1.562em` | Pointer target width. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_thumb_default_height` | `thumb` | `default` | `height` | `1.562em` | Pointer target height. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_thumb_default_background-color` | `thumb` | `default` | `background-color` | track background | Thumb background. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_thumb_default_border-radius` | `thumb` | `default` | `border-radius` | `50%` | Thumb shape. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_thumb_default_transition-duration` | `thumb` | `default` | `transition-duration` | `var(--pw_transition-duration)` | Thumb visual duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_RangeSlider_label_default_color` | `label` | `default` | `color` | `var(--pw_label_text_color)` | Label colour. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_label_default_font-size` | `label` | `default` | `font-size` | `var(--pw_font-size)` | Label font size. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_label_default_font-weight` | `label` | `default` | `font-weight` | `var(--pw_semibold_font-weight)` | Label font weight. | Web, Capacitor, NativeScript |
+| `--pw_RangeSlider_label_default_line-height` | `label` | `default` | `line-height` | `var(--pw_line-height)` | Label line height. | Web, Capacitor, NativeScript |
+
+```xts
+import { useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { rangeSliderMediator } from '@pastweb/components-core/RangeSlider';
+import { DEFAULT_PROPS } from './constants';
+
+export function RangeSlider(props: RangeSliderProps) {
+  const p = withDefaultProps<RangeSliderDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<RangeSliderMediator>(rangeSliderMediator, p);
+  const s = m.state;
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div class={p.cls('RangeSlider', `label-${p.labelPlacement}`, { 'is-disabled': s.isDisabled }, p.className)}>
+      <input class={p.cls('slider')} type="range" id={s.inputId} min={p.min} max={p.max}
+        step={p.step} value={s.value} disabled={s.isDisabled}
+        aria-label={s.ariaLabel}
+        @change={event => m.onChange(event.target.value, event)}
+        @pointerup={m.onChangeEnd} @keyup={m.onChangeEnd} />
+      <label #if={p.label} class={p.cls('label', p.labelPlacement)} for={s.inputId}>{p.label}</label>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Arrow keys, `Home`, `End`, `PageUp`, and `PageDown` adjust the native range
+  value.
+- `Tab` and `Shift+Tab` move sequential focus to the available slider.
+
+## Accessibility notes
+
+- The native input supplies slider role, values, keyboard operation, and
+  disabled behavior.
+- The visible label is connected through `for`/`id`. When it is absent,
+  `ariaLabel` names the slider. The default name is `Range value`.
+- Disabled state is reflected through `.is-disabled` and native `disabled`.
+- Shared web styles provide a visible `:focus-visible` indicator, 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 Slider pattern: https://www.w3.org/WAI/ARIA/apg/patterns/slider/
+- GOV.UK form controls: https://design-system.service.gov.uk/components/

package/dist/ScrollArea/README.md

@@ -0,0 +1,105 @@
+# ScrollArea
+
+ScrollArea provides a named, keyboard-focusable viewport for overflowing
+content. Its rendering contract targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use it when content must remain within a bounded layout. Avoid nested scroll
+areas and never hide an axis when that would make content unreachable.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and part classes. |
+| `ariaLabel` | `string` | no | `"Scrollable content"` | Names the region. Pass an empty string to omit the name. Prefer a specific label. |
+| `id` | `string` | no | - | Root ID. |
+| `className` | `string` | no | `""` | Additional root classes. |
+| `hideX` | `boolean` | no | - | Applies `hide-x` and suppresses horizontal overflow. |
+| `hideY` | `boolean` | no | - | Applies `hide-y` and suppresses vertical overflow. |
+| `scrollRight` | `boolean` | no | - | Applies `scroll-right` and requests initial horizontal end alignment. |
+| `scrollBottom` | `boolean` | no | - | Applies `scroll-bottom` and requests initial vertical end alignment. |
+| `contentPadding` | `number \| string` | no | - | Inline padding scoped to `.content`. |
+| `tabIndex` | `number` | no | `0` | Makes the scroll viewport keyboard focusable. |
+
+The default slot supplies scrollable content.
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized region name. Empty labels are omitted. |
+
+`getContentStyle()` returns `{ padding }` when `contentPadding` is provided,
+including `0`. `getScrollAlignment()` returns semantic `start` or `end` axes
+for the renderer to apply after layout.
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_ScrollArea_content_default_scrollbar-color` | `content` | `default` | `scrollbar-color` | `#e3e3e3 transparent` | Standards scrollbar colours. | Web, Capacitor |
+| `--pw_ScrollArea_content_default_scrollbar-width` | `content` | `default` | `scrollbar-width` | `thin` | Standards scrollbar width. | Web, Capacitor |
+| `--pw_ScrollArea_scrollbar_default_width` | `scrollbar` | `default` | `width` | `12px` | WebKit vertical width. | Web, Capacitor |
+| `--pw_ScrollArea_scrollbar_default_height` | `scrollbar` | `default` | `height` | `12px` | WebKit horizontal height. | Web, Capacitor |
+| `--pw_ScrollArea_scrollbar-track_default_background-color` | `scrollbar-track` | `default` | `background-color` | `#fcfcfc` | Track colour. | Web, Capacitor |
+| `--pw_ScrollArea_scrollbar-thumb_default_background-color` | `scrollbar-thumb` | `default` | `background-color` | `#dfdfdf` | Thumb colour. | Web, Capacitor |
+| `--pw_ScrollArea_scrollbar-thumb_hover_background-color` | `scrollbar-thumb` | `hover` | `background-color` | `#7a7a7a` | Hover thumb colour. | Web, Capacitor |
+| `--pw_ScrollArea_scrollbar-thumb_default_border-radius` | `scrollbar-thumb` | `default` | `border-radius` | `6px` | Thumb corners. | Web, Capacitor |
+| `--pw_ScrollArea_scrollbar-corner_default_background-color` | `scrollbar-corner` | `default` | `background-color` | `#fbfbfb` | Corner colour. | Web, Capacitor |
+
+```xts
+import { useMediator, useMounted, useRef, withDefaultProps } from '@pastweb/x';
+import { scrollAreaMediator } from '@pastweb/components-core/ScrollArea';
+import { DEFAULT_PROPS } from './constants';
+
+export function ScrollArea(props: ScrollAreaProps) {
+  const p = withDefaultProps<ScrollAreaDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<ScrollAreaMediator>(scrollAreaMediator, p);
+  const s = m.state;
+  const content = useRef();
+
+  useMounted(() => {
+    const alignment = m.getScrollAlignment();
+    if (alignment.horizontal === 'end') content.value.scrollLeft = content.value.scrollWidth - content.value.clientWidth;
+    if (alignment.vertical === 'end') content.value.scrollTop = content.value.scrollHeight - content.value.clientHeight;
+  });
+
+  return (
+    <div id={p.id} class={p.cls('ScrollArea', {
+      'hide-x': p.hideX, 'hide-y': p.hideY,
+      'scroll-bottom': p.scrollBottom, 'scroll-right': p.scrollRight,
+    }, p.className)}>
+      <div #ref={content} class={p.cls('content')} #style={m.getContentStyle()}
+        role="region" aria-label={s.ariaLabel} tabindex={p.tabIndex}><slot /></div>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- `Tab` and `Shift+Tab` move sequential focus to the named viewport.
+- Arrow keys, `PageUp`, `PageDown`, `Home`, and `End` scroll native overflow
+  when the viewport is focused.
+
+## Accessibility notes
+
+- The web viewport is a named `region` and is keyboard focusable.
+- Renderers consume `getScrollAlignment()` after layout instead of reversing
+  visual content order.
+- Hiding an axis must not make content unreachable.
+- Shared web styles provide a visible `:focus-visible` indicator.
+
+## Known limitations
+
+- Nested scroll areas make keyboard scrolling harder to discover.
+- 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 components: https://design-system.service.gov.uk/components/

package/dist/Select/README.md

@@ -0,0 +1,243 @@
+# Select
+
+Select chooses one value from a listbox attached to a trigger. The trigger is
+either a styled native button (`content`) or a custom control (`target`). Its
+rendering contract follows the WAI-ARIA Combobox/Listbox pattern and targets
+WCAG 2.2 Level AA.
+
+## When to use
+
+Use Select when the user must pick one option from a known list. Do not use it
+for free-text entry. Prefer a native radio group for a very small set of options
+that should stay visible.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `id` | `string` | no | generated | Supplies the host ID. Generated IDs use the `select` prefix. |
+| `ariaLabel` | `string` | no | `"Select an option"` | Names the trigger when there is no visible `label`. Pass an empty string to omit the accessible name. |
+| `name` | `string` | no | - | Optional form name. |
+| `label` | `string` | no | `""` | Visible label. When set, it names the trigger and `ariaLabel` is omitted. |
+| `labelPlacement` | `Placement` | no | `"top-start"` | Places the visible label relative to the trigger. |
+| `placeholder` | `string` | no | `"Select"` | Default text of the styled `content` trigger when that slot is empty. |
+| `disabled` | `boolean` | no | - | Makes the Select unavailable. |
+| `loading` | `boolean` | no | - | Marks the Select busy and unavailable. |
+| `className` | `string` | no | `""` | Adds classes to the root. The `is-loading` class also enables loading. |
+| `tabIndex` | `number` | no | `0` | Controls sequential keyboard focus order. |
+| `value` | `any` | no | - | Controlled selected value. |
+| `offset` | `number` | no | `3` | Listbox offset from the trigger. |
+| `closeOnSelect` | `boolean` | no | `true` | Closes the listbox after a selection. |
+| `hideOnClick` | `boolean` | no | `true` | Closes the listbox after activation inside the options. |
+| `onChange` | `(value: any) => void` | no | noop | Reports the selected value. |
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-rounded` | Uses the rounded radius token on `.selectButton` and the listbox. Custom `target` triggers are not styled by this class. |
+| `is-full-width` | Expands the Select to the available width. |
+
+## Mediator API
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `string` | Resolved host ID. Generated IDs use the `select` prefix; an explicit `id` is exposed as `_${id}`. |
+| `hide` | `() => void` | Closes the listbox. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized trigger accessible name. Omitted when `label` is set or `ariaLabel` is empty. |
+| `highlightIndex` | `number \| null` | Keyboard highlight index in the listbox. |
+| `inputId` | `string` | Root ID. Same value as mediator `id`. |
+| `isDisabled` | `true \| undefined` | Is `true` when the Select is disabled; otherwise omitted. |
+| `isLoading` | `true \| undefined` | Is `true` when the Select is loading; otherwise omitted. |
+| `isOpen` | `boolean` | Whether the listbox is open. |
+| `isUnavailable` | `true \| undefined` | Is `true` when disabled or loading. |
+| `labelId` | `string` | Visible-label relationship ID in the form `label${id}`. |
+| `listboxId` | `string` | Listbox relationship ID in the form `listbox${id}`. |
+| `triggerId` | `string` | Trigger relationship ID in the form `trigger${id}`. |
+| `value` | `any` | Current selected value. |
+
+## Mediator context
+
+SelectItem reads this API through the renderer context hook. Live getters stay synchronized with mediator state.
+
+| Context property | Type | Description |
+|---|---|---|
+| `hide` | `() => void` | Closes the listbox. |
+| `onChange` | `(value: any) => void` | Selects a value. |
+| `onOptionKeyDown` | `(event, value, disabled?) => void` | Handles option keyboard activation. |
+| `registerItem` | `() => number` | Registers a SelectItem and returns its index. |
+| `state` | `SelectState` | Live mediator state for descendants. |
+
+## Slots
+
+Provide `content` for the styled button trigger, or `target` for a custom
+trigger. Each trigger is mounted only when its slot has content. If neither
+slot is provided, no trigger is rendered. Do not put another button inside
+either trigger slot.
+
+| SlotName | Description | Default content |
+|---|---|---|
+| `target` | Replaces the native trigger. It receives the trigger ID, ARIA state, keyboard handler, toggle handler, and tab index through slot props; the replacement must apply them to one focusable control. | The native `content` trigger. |
+| `content` | Labelled content of the styled native-button trigger (`.selectButton`), which includes a decorative arrow. When present, the button is rendered. | `placeholder` |
+| `options` | Supplies listbox options such as `SelectItem`. | Empty. |
+| default | Supplies additional listbox content. | Empty. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Select_root_default_min-width` | `root` | `default` | `min-width` | `12em` | Minimum control width. The control can grow with trigger content. | Web, Capacitor, NativeScript |
+| `--pw_Select_options_default_width` | `options` | `default` | `width` | `max-content` | Listbox width, sized to option content. | Web, Capacitor |
+| `--pw_Select_options_default_max-height` | `options` | `default` | `max-height` | `16em` | Listbox max height; overflow scrolls vertically. | Web, Capacitor |
+| `--pw_Select_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_control_background-color)` | Control and listbox background. | Web, Capacitor, NativeScript |
+| `--pw_Select_root_default_color` | `root` | `default` | `color` | `var(--pw_text_strong_color)` | Control and option foreground. | Web, Capacitor, NativeScript |
+| `--pw_Select_label_default_color` | `label` | `default` | `color` | `var(--pw_label_text_color)` | Visible label colour. | Web, Capacitor, NativeScript |
+| `--pw_Select_root_default_border-color` | `root` | `default` | `border-color` | `var(--pw_border-color)` | Listbox border colour. | Web, Capacitor, NativeScript |
+| `--pw_Select_root_default_border-width` | `root` | `default` | `border-width` | `var(--pw_border-width)` | Listbox border width. | Web, Capacitor, NativeScript |
+| `--pw_Select_root_default_border-style` | `root` | `default` | `border-style` | `var(--pw_border-style)` | Listbox border style. | Web, Capacitor, NativeScript |
+| `--pw_Select_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Listbox corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Select_root_default_padding` | `root` | `default` | `padding` | `var(--pw_padding)` | Option padding. | Web, Capacitor, NativeScript |
+| `--pw_Select_root_default_margin` | `root` | `default` | `margin` | vertical/horizontal margin | Outer spacing. | Web, Capacitor, NativeScript |
+| `--pw_Select_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled opacity. | Web, Capacitor, NativeScript |
+
+```xts
+import {
+  setContext,
+  useBeforeUnmount,
+  useMediator,
+  useMounted,
+  useRef,
+  withDefaultProps,
+} from '@pastweb/x';
+import { selectMediator } from '@pastweb/components-core/Select';
+import { DEFAULT_PROPS, SELECT_CONTEXT_KEY } from './constants';
+
+export function Select(props: SelectProps) {
+  const p = withDefaultProps<SelectDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<SelectMediator>(selectMediator, p);
+  const s = m.state;
+  const c = m.getContext();
+  const triggerReference = useRef(null);
+  const listboxReference = useRef(null);
+
+  setContext(SELECT_CONTEXT_KEY, c);
+  useMounted(() => {
+    if (triggerReference.value && listboxReference.value) {
+      m.useMounted(triggerReference.value, listboxReference.value);
+    }
+  });
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      id={s.inputId}
+      class={p.cls('Select', `label-${p.labelPlacement}`, p.className, {
+        'is-disabled': s.isDisabled,
+        'is-loading': s.isLoading,
+        'is-open': s.isOpen,
+      })}
+    >
+      <div class={p.cls('selectControl')}>
+        <slot
+          name='target'
+          props={{
+            ariaBusy: s.isLoading || undefined,
+            ariaControls: s.listboxId,
+            ariaExpanded: s.isOpen,
+            ariaHasPopup: 'listbox',
+            ariaLabel: s.ariaLabel,
+            ariaLabelledBy: p.label ? s.labelId : undefined,
+            ariaDisabled: s.isUnavailable,
+            id: s.triggerId,
+            onKeyDown: m.onKeyDown,
+            onToggle: m.onToggle,
+            tabIndex: p.tabIndex,
+          }}
+        >
+          <button
+            #ref={triggerReference}
+            id={s.triggerId}
+            type='button'
+            class={p.cls('selectButton')}
+            tabIndex={p.tabIndex}
+            disabled={s.isUnavailable}
+            aria-haspopup='listbox'
+            aria-expanded={s.isOpen}
+            aria-controls={s.listboxId}
+            aria-labelledby={p.label ? s.labelId : undefined}
+            aria-label={s.ariaLabel}
+            aria-busy={s.isLoading || undefined}
+            @keydown={m.onKeyDown}
+            @click={m.onToggle}
+          >
+            <slot name='content'>{p.placeholder}</slot>
+            <span class={p.cls('arrow')} aria-hidden='true'>▼</span>
+          </button>
+        </slot>
+        <ul
+          #ref={listboxReference}
+          id={s.listboxId}
+          role='listbox'
+          class={p.cls('options')}
+          aria-labelledby={p.label ? s.labelId : s.triggerId}
+          hidden={!s.isOpen}
+        >
+          <slot name='options' />
+          <slot />
+        </ul>
+      </div>
+      <label #if={p.label} id={s.labelId} class={p.cls('label', p.labelPlacement)} for={s.triggerId}>
+        {p.label}
+      </label>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- `Enter` or `Space` on the trigger toggles the listbox.
+- `ArrowDown` opens and highlights the first option, or moves down.
+- `ArrowUp` opens and highlights the last option, or moves up.
+- `Home` and `End` move to the first and last option while open.
+- `Escape` closes an open listbox and restores trigger focus.
+- `Tab` closes an open listbox and continues document order.
+
+## Accessibility notes
+
+- Provide either a `content` trigger or a `target` trigger. Each trigger exposes
+  expanded, controls, disabled, and busy state.
+- The `content` trigger is a native button with a decorative arrow. Do not place
+  another button in the `content` slot.
+- A `target` replacement receives the required trigger semantics as slot props. Apply them to one focusable control and do not nest controls.
+- Visible `label` text is the accessible name. `ariaLabel` is used only when there is no visible label.
+- The visible `label` is associated with the `content` button through `for` and
+  `triggerId`. The `target` trigger is named with `aria-labelledby` when a
+  visible label is present.
+- Disabled and loading states are unavailable and cannot open the listbox.
+- Closed options use `hidden` so they leave the accessibility tree and tab order.
+- The listbox is sized to option content and at least as wide as the trigger. It
+  flips only to the opposite edge when the viewport has no room below, and
+  scrolls vertically when options exceed the max height.
+- Shared web styles provide a visible focus indicator, forced-colours treatment,
+  and reduced-motion behavior.
+
+## Known limitations
+
+- Content-slot and target-slot content should not introduce a nested button.
+- Listbox positioning uses web layout measurement.
+- Automated accessibility checks do not by themselves establish WCAG conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Combobox/Listbox pattern: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+- GOV.UK select: https://design-system.service.gov.uk/components/select/

package/dist/SheetController/README.md

@@ -0,0 +1,143 @@
+# SheetController
+
+SheetController presents an animated, optionally modal dialog surface from an
+edge of its portal container. Its rendering contract follows the WAI-ARIA Dialog
+(Modal) pattern and targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use it for secondary tasks that need more space than a popover without
+navigating away. Do not use it for essential content that should remain
+permanently visible. A modal sheet must include an obvious close control inside
+its content.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and part classes. |
+| `id` | `string` | no | generated | Supplies the dialog ID. Generated IDs use the `sheetController` prefix. Explicit IDs are stored as `_${id}`. |
+| `ariaLabel` | `string` | no | `'Sheet'` | Accessible dialog name. Pass an empty string to omit the name. |
+| `className` | `string` | no | `''` | Additional root classes. |
+| `direction` | `'left' \| 'right' \| 'up' \| 'down'` | no | `'left'` | Entry and exit edge. |
+| `backdrop` | `boolean` | no | - | Displays the native backdrop button and applies `has-backdrop`. |
+| `modal` | `boolean` | no | - | Enables `aria-modal`, focus containment, and `is-modal`. |
+| `closeOnBackdropClick` | `boolean` | no | `true` | Allows backdrop activation to close. |
+| `closeOnEscape` | `boolean` | no | `true` | Allows Escape to close unless the event is prevented. |
+| `animationTime` | `number` | no | `400` | Fallback close duration in milliseconds. |
+| `width`, `height` | `number \| string` | no | - | Inline sheet dimensions. |
+| `top`, `right`, `bottom`, `left` | `number \| string` | no | - | Inline sheet offsets. |
+| `portal`, `portalElement`, `entryId` | portal integration | no | - | Optional host integration used for update/remove/close events. |
+| `onClose` | `() => void` | no | noop | Reports completed closure once. |
+| `onKeyDown` | `(event: SheetKeyboardEvent) => void` | no | noop | Observes keyboard input before default Escape handling. |
+
+The default slot supplies dialog content. Include a native close button that
+calls `useSheetContext().close()`.
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized dialog name. Empty labels are omitted. |
+| `id` | `string` | Dialog ID from an explicit `id` or a generated `sheetController` prefix. |
+| `isClosed` | `boolean` | Is `true` after closure is finalized and the surface should unmount. |
+| `isClosing` | `boolean` | Is `true` during the exit animation; content is inert. |
+| `isOpen` | `boolean` | Is `true` while the sheet is shown and not closing. |
+
+## CSS classes
+
+| Class | Applied when | Notes |
+|---|---|---|
+| `SheetController` | Always | Root overlay class. |
+| `has-backdrop` | `backdrop` is `true` | Backdrop overlay is present. |
+| `is-open` | `isOpen` is `true` | Sheet is visible. |
+| `is-modal` | `modal` is `true` | Modal focus containment is active. |
+| `is-closing` | `isClosing` is `true` | Exit animation; pointer events disabled. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_SheetController_root_default_width` | `root` | `default` | `width` | `100%` | Overlay width. | Web, Capacitor, NativeScript |
+| `--pw_SheetController_root_default_height` | `root` | `default` | `height` | `100%` | Overlay height. | Web, Capacitor, NativeScript |
+| `--pw_SheetController_backdrop_default_background-color` | `backdrop` | `default` | `background-color` | shared backdrop | Backdrop colour. | Web, Capacitor, NativeScript |
+| `--pw_SheetController_sheet_default_background-color` | `sheet` | `default` | `background-color` | shared background | Sheet background. | Web, Capacitor, NativeScript |
+| `--pw_SheetController_sheet_default_color` | `sheet` | `default` | `color` | shared text | Sheet foreground. | Web, Capacitor, NativeScript |
+| `--pw_SheetController_sheet_default_box-shadow` | `sheet` | `default` | `box-shadow` | elevation shadow | Sheet elevation. | Web, Capacitor |
+| `--pw_SheetController_sheet_default_animation-duration` | `sheet` | `default` | `animation-duration` | `400ms` | Edge animation duration. | Web, Capacitor; native adapter |
+| `--pw_SheetController_sheet_default_animation-timing-function` | `sheet` | `default` | `animation-timing-function` | `ease` | Edge animation timing. | Web, Capacitor; native adapter |
+| `--pw_SheetController_sheet_default_animation-fill-mode` | `sheet` | `default` | `animation-fill-mode` | `forwards` | Edge animation fill. | Web, Capacitor; native adapter |
+| `--pw_SheetController_sheet_default_outline` | `sheet` | `default` | `outline` | shared outline | Keyboard focus indicator. | Web, Capacitor |
+| `--pw_SheetController_sheet_default_outline-offset` | `sheet` | `default` | `outline-offset` | `0.125em` | Focus outline offset. | Web, Capacitor |
+
+```xts
+import { setContext, useBeforeUnmount, useMediator, useMounted, useRef, withDefaultProps } from '@pastweb/x';
+import { sheetControllerMediator, SHEET_CONTEXT_KEY } from '@pastweb/components-core/SheetController';
+import { DEFAULT_PROPS } from './constants';
+
+export function SheetController(props: SheetControllerProps) {
+  const p = withDefaultProps<SheetControllerDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<SheetControllerMediator>(sheetControllerMediator, p);
+  const s = m.state;
+  const c = m.getContext();
+  const sheet = useRef();
+
+  setContext(SHEET_CONTEXT_KEY, c);
+  useMounted(() => m.useMounted(sheet.value, p.portalElement));
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  if (s.isClosed) return null;
+
+  return (
+    <div class={p.cls('SheetController', {
+      'has-backdrop': p.backdrop, 'is-closing': s.isClosing,
+      'is-modal': p.modal, 'is-open': s.isOpen,
+    }, p.className)} #style={{ animation-duration: `${p.animationTime}ms` }}>
+      <button #if={p.backdrop} type="button" class={p.cls('backdrop')}
+        tabindex={-1} aria-hidden="true" @click={m.onBackdrop} />
+      <div #ref={sheet} id={m.id} class={p.cls('sheet', {
+        [`sheet-open-${p.direction}`]: s.isOpen,
+        [`sheet-close-${p.direction}`]: s.isClosing,
+      })} role="dialog" aria-label={s.ariaLabel} aria-modal={p.modal || undefined}
+        aria-hidden={s.isClosing || undefined} inert={s.isClosing || undefined} tabindex={-1}
+        @keydown={m.onKeyDown} @animationend={m.onTransitionEnd}>
+        <slot />
+      </div>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Focus moves to the sheet when mounted.
+- `Escape` closes when `closeOnEscape` is enabled, unless the consumer prevents the event.
+- Modal sheets keep `Tab` and `Shift+Tab` inside their focusable content.
+- Focus returns to the previously focused element when closing or unmounting.
+
+## Accessibility notes
+
+- The web renderer exposes a named `dialog`. `aria-modal` is set only when `modal` is true.
+- The backdrop is a native `button` excluded from the tab order and accessibility tree.
+- Closing content becomes inert immediately; animation completion or the timer finalizes portal removal.
+- Shared web styles keep a visible `:focus-visible` indicator and disable non-essential motion under `prefers-reduced-motion`.
+
+## Known limitations
+
+- Nested sheets require distinct labels so dialog announcements remain understandable.
+- A modal sheet still depends on its content to provide a visible close control.
+- Automated accessibility checks do not by themselves establish WCAG conformance.
+
+## Native renderer mapping
+
+NativeScript maps the sheet to an accessible modal or non-modal native container,
+uses native focus containment and restoration, maps edge directions to native
+animations, makes closing content unavailable immediately, and calls
+`onTransitionEnd` when animation completes. Back gestures and Escape-compatible
+keys call the same close intent.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Dialog (Modal) pattern: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+- GOV.UK components: https://design-system.service.gov.uk/components/