@pastweb/components-core 2.0.0 → 2.2.0

package/dist/Spinner/README.md

@@ -0,0 +1,80 @@
+# Spinner
+
+Spinner displays a rotating visual indicator and exposes a polite loading
+status. Its rendering contract targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use it for short waits when completion cannot be calculated. Use ProgressBar for
+determinate work. Do not rely on animation alone: keep the accessible label
+specific to the operation.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and part classes. |
+| `ariaLabel` | `string` | no | `"Loading"` | Accessible status name. Pass an empty string to omit the name. |
+| `decorative` | `boolean` | no | - | Removes status semantics and applies `is-decorative`. |
+| `className` | `string` | no | `""` | Additional root classes. |
+
+The default slot supplies the visual glyph and is hidden from assistive
+technology.
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `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. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Spinner_root_default_width` | `root` | `default` | `width` | `1.5em` | Indicator width. | Web, Capacitor, NativeScript |
+| `--pw_Spinner_root_default_height` | `root` | `default` | `height` | `1.5em` | Indicator height. | Web, Capacitor, NativeScript |
+| `--pw_Spinner_root_default_color` | `root` | `default` | `color` | `currentcolor` | Indicator colour. | Web, Capacitor, NativeScript |
+| `--pw_Spinner_content_default_animation-duration` | `content` | `default` | `animation-duration` | `2s` | Rotation duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_Spinner_content_default_animation-timing-function` | `content` | `default` | `animation-timing-function` | `linear` | Rotation timing. | Web, Capacitor; NativeScript adapter |
+
+```xts
+import { useMediator, withDefaultProps } from '@pastweb/x';
+import { spinnerMediator } from '@pastweb/components-core/Spinner';
+import { DEFAULT_PROPS } from './constants';
+
+export function Spinner(props: SpinnerProps) {
+  const p = withDefaultProps<SpinnerDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<SpinnerMediator>(spinnerMediator, p);
+  const s = m.state;
+
+  return (
+    <div class={p.cls('Spinner', { 'is-decorative': p.decorative }, p.className)}
+      role={s.role} aria-label={s.ariaLabel} aria-live={s.ariaLive}>
+      <span class={p.cls('content')} aria-hidden="true"><slot /></span>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Spinner is not interactive. It does not enter the tab order.
+
+## Accessibility notes
+
+- The web renderer exposes a named polite status unless decorative.
+- Decorative spinners omit role, name, and live region.
+- Shared web styles disable non-essential rotation under `prefers-reduced-motion`.
+
+## 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 guidance: https://www.w3.org/WAI/ARIA/apg/patterns/
+- GOV.UK components: https://design-system.service.gov.uk/components/

package/dist/SplitLayout/README.md

@@ -0,0 +1,132 @@
+# SplitLayout
+
+SplitLayout arranges resizable panels separated by pointer- and keyboard-operable
+controls. Its rendering contract follows the WAI-ARIA Window Splitter pattern
+and targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use it when users benefit from allocating space between adjacent work areas.
+Avoid it for ordinary responsive page columns, and provide a stacked alternative
+when a small viewport cannot support the minimum panel sizes.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves classes. |
+| `ariaLabel` | `string` | no | `'Resizable panels'` | Names the panel group. Pass an empty string to omit the name. |
+| `className` | `string` | no | `''` | Additional root classes. |
+| `orientation` | `'horizontal' \| 'vertical'` | no | `'horizontal'` | Panel and separator axis. |
+| `sizes` | `number[]` | no | equal | Relative percentages normalized to total 100. |
+| `minSize` | `number` | no | `10` | Minimum percentage for each adjacent panel. |
+| `keyboardStep` | `number` | no | `2` | Percentage moved per arrow-key activation. |
+| `disabled` | `boolean` | no | - | Prevents resizing and applies `is-disabled`. |
+| `onSizesChange` | `(sizes: number[]) => void` | no | noop | Reports normalized percentages after resizing. |
+
+`SplitLayoutItem` accepts `id`, `ariaLabel`, and `className`. Only
+`SplitLayoutItem` children are supported.
+
+## Mediator integration
+
+`SplitLayoutItem` owns pointer resizing through its mediator. Framework
+renderers should forward `pointerdown`, `pointermove`, `pointerup`,
+`pointercancel`, and `lostpointercapture` events to the matching mediator
+methods. The mediator normalizes the framework event internally, manages
+pointer capture, and reports resize deltas to the parent layout context.
+
+The `onSizesChange` prop remains the framework-neutral callback for changed
+pane percentages. Renderers may additionally expose that callback through
+their native event convention, such as Vue's `@sizes-change`.
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `activeSeparator` | `number \| null` | Index of the separator currently being resized. |
+| `ariaLabel` | `string \| undefined` | Normalized group name. Empty labels are omitted. |
+| `isDisabled` | `true \| undefined` | Is `true` when resizing is unavailable; otherwise omitted. |
+| `itemCount` | `number` | Registered pane count. |
+| `sizes` | `number[]` | Normalized pane percentages totalling 100. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_SplitLayout_root_default_width` | `root` | `default` | `width` | `100%` | Layout width. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_root_default_height` | `root` | `default` | `height` | `100%` | Layout height. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_root_disabled_opacity` | `root` | `disabled` | `opacity` | shared disabled opacity | Disabled appearance. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_pane_default_background-color` | `pane` | `default` | `background-color` | transparent | Panel background. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_splitter_default_width` | `splitter` | `default` | `width` | `0.2em` | Horizontal visual splitter width. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_splitter_default_height` | `splitter` | `default` | `height` | `0.2em` | Vertical visual splitter height. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_splitter_default_background-color` | `splitter` | `default` | `background-color` | border colour | Splitter colour. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_splitter_hover_background-color` | `splitter` | `hover` | `background-color` | strong text | Hover colour. | Web, Capacitor |
+| `--pw_SplitLayout_splitter_default_border-color` | `splitter` | `default` | `border-color` | shared border | Splitter border colour. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_splitter_default_border-style` | `splitter` | `default` | `border-style` | shared border style | Splitter border style. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_splitter_default_border-width` | `splitter` | `default` | `border-width` | shared border width | Splitter border width. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_splitter_default_outline` | `splitter` | `default` | `outline` | shared outline | Keyboard focus indicator. | Web, Capacitor |
+| `--pw_SplitLayout_splitter-target_default_width` | `splitter-target` | `default` | `width` | `2.75em` | Horizontal pointer target width. | Web, Capacitor, NativeScript |
+| `--pw_SplitLayout_splitter-target_default_height` | `splitter-target` | `default` | `height` | `2.75em` | Vertical pointer target height. | Web, Capacitor, NativeScript |
+
+```xts
+import { setContext, useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { splitLayoutMediator, SPLIT_LAYOUT_CONTEXT_KEY } from '@pastweb/components-core/SplitLayout';
+import { DEFAULT_PROPS } from './constants';
+
+export function SplitLayout(props: SplitLayoutProps) {
+  const p = withDefaultProps<SplitLayoutDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<SplitLayoutMediator>(splitLayoutMediator, p);
+  const s = m.state;
+  const c = m.getContext();
+
+  m.setItemCount(props.children.length);
+  setContext(SPLIT_LAYOUT_CONTEXT_KEY, c);
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div class={p.cls('SplitLayout', p.orientation, {
+      'is-disabled': s.isDisabled, 'is-resizing': s.activeSeparator !== null,
+    }, p.className)} role="group" aria-label={s.ariaLabel}>
+      <slot />
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- A horizontal panel layout has vertical separators and uses `ArrowLeft` and
+  `ArrowRight`.
+- A vertical panel layout has horizontal separators and uses `ArrowUp` and
+  `ArrowDown`.
+- `Home` moves the preceding panel to its minimum.
+- `End` moves the following panel to its minimum.
+- Separators expose orientation and current, minimum, and maximum percentage
+  values.
+
+## Accessibility notes
+
+- The layout is a named group. Each separator is a focusable `separator` with
+  `aria-controls`, `aria-orientation`, and current/min/max values.
+- Disabled state is reflected through `.is-disabled` and removes separator
+  operation.
+- Pointer targets remain at least 44 CSS pixels even when the visible splitter
+  is thinner.
+
+## Known limitations
+
+- Percentages describe the pane proportions within the space left after
+  splitters; very small containers can therefore produce a physical pane size
+  slightly below the percentage calculated against the full container.
+- The component does not yet observe container resizing or automatically switch
+  orientation at responsive breakpoints.
+- Nested layouts require distinct labels so separator announcements remain
+  understandable.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Window Splitter pattern: https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/
+- GOV.UK components: https://design-system.service.gov.uk/components/

package/dist/Stepper/README.md

@@ -0,0 +1,146 @@
+# Stepper
+
+Stepper communicates progress through an ordered sequence. `active` remains
+one-based for compatibility. A step is interactive only when it supplies
+`onClick`; disabled interactive steps use a native disabled button. Its
+rendering contract targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use Stepper for a known sequence of stages. Do not use it as a page navigation
+control unless each step is also a destination. Prefer a native continue action
+and back link for linear form journeys that do not need a visible map of every
+stage.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `steps` | `Step[]` | yes | - | Ordered labels, descriptions, indicators and optional actions. |
+| `active` | `number` | no | `1` | Current one-based step. |
+| `id` | `string` | no | generated | Supplies the host ID. Generated IDs use the `stepper` prefix. Explicit IDs are stored as `_${id}`. |
+| `ariaLabel` | `string` | no | `"Progress"` | Names the ordered sequence. Pass an empty string to omit it. |
+| `orientation` | `'horizontal' \| 'vertical'` | no | `'horizontal'` | Visual direction. |
+| `labelPosition` | `'top' \| 'bottom' \| 'left' \| 'right'` | no | `'top'` | Visual label position. Horizontal uses `top` or `bottom` (`top` when omitted or invalid). Vertical uses `left` or `right` (`right` when omitted or invalid). |
+| `className` | `string` | no | `""` | Additional root classes. |
+
+`Step` supports `label`, `description`, `content`, `ariaLabel`, `className`,
+`disabled`, and `onClick`. The current list item exposes `aria-current="step"`.
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized sequence name. Empty labels are omitted. |
+| `id` | `string` | Host ID from an explicit `id` or a generated `stepper` prefix. |
+| `labelPosition` | `'top' \| 'bottom' \| 'left' \| 'right'` | Resolved label side for the current orientation. |
+
+`getStepState(index)` returns `'active'`, `'complete'`, or `'pending'`. Title
+and description IDs use `title${id}${index}` and `description${id}${index}`.
+
+## CSS classes
+
+| Class | Applied when | Notes |
+|---|---|---|
+| `Stepper` | Always | Root component class. |
+| `is-horizontal` / `is-vertical` | `orientation` | Axis of the ordered list. |
+| `labels-top` / `labels-bottom` / `labels-left` / `labels-right` | resolved `labelPosition` | Horizontal applies `labels-top` or `labels-bottom`. Vertical applies `labels-left` or `labels-right`. |
+| `is-active` | current step | Applied to the list item. |
+| `is-complete` | earlier steps | Applied to the list item. |
+| `is-pending` | later steps | Applied to the list item. |
+| `is-disabled` | `step.disabled` | Applied to the list item. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Stepper_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_background-color)` | Component background. | Web, Capacitor, NativeScript |
+| `--pw_Stepper_root_disabled_opacity` | `root` | `disabled` | `opacity` | shared disabled opacity | Disabled step appearance. | Web, Capacitor, NativeScript |
+| `--pw_Stepper_indicator_default_background-color` | `indicator` | `default` | `background-color` | `var(--pw_control_background-color)` | Indicator background. | Web, Capacitor, NativeScript |
+| `--pw_Stepper_indicator_active_border-color` | `indicator` | `active` | `border-color` | strong text | Active indicator border. | Web, Capacitor, NativeScript |
+| `--pw_Stepper_indicator_complete_background-color` | `indicator` | `complete` | `background-color` | shared text | Complete indicator background. | Web, Capacitor, NativeScript |
+| `--pw_Stepper_indicator_default_outline` | `indicator` | `default` | `outline` | shared outline | Keyboard focus indicator. | Web, Capacitor |
+| `--pw_Stepper_indicator-target_default_width` | `indicator-target` | `default` | `width` | `2.75em` | Pointer target width. | Web, Capacitor, NativeScript |
+| `--pw_Stepper_indicator-target_default_height` | `indicator-target` | `default` | `height` | `2.75em` | Pointer target height. | Web, Capacitor, NativeScript |
+| `--pw_Stepper_indicator_slot_size` | `indicator` | `default` | `width` / `height` | calculated | Indicator box used to centre labels. | Web, Capacitor |
+| `--pw_Stepper_label_default_color` | `label` | `default` | `color` | `var(--pw_text_color)` | Label colour. | Web, Capacitor, NativeScript |
+
+```xts
+import { useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { stepperMediator } from '@pastweb/components-core/Stepper';
+import { DEFAULT_PROPS, DEFAULT_STEP_PROPS } from './constants';
+
+export function Stepper(props: StepperProps) {
+  const p = withDefaultProps<StepperDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<StepperMediator>(stepperMediator, p);
+  const s = m.state;
+  const steps = p.steps.map(step => withDefaultProps<StepDefaultProps>(step, DEFAULT_STEP_PROPS));
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div id={m.id} class={p.cls('Stepper', `is-${p.orientation}`, `labels-${s.labelPosition}`, p.className)}>
+      <ol class={p.cls('steps')} aria-label={s.ariaLabel}>
+        {steps.map((step, index) => {
+          const state = m.getStepState(index);
+          const titleId = `title${m.id}${index}`;
+          return (
+            <li class={p.cls('step', `is-${state}`, { 'is-disabled': step.disabled }, step.className)}
+              aria-current={state === 'active' ? 'step' : undefined}>
+              <div class={p.cls('step-main')}>
+                <button #if={step.onClick !== DEFAULT_STEP_PROPS.onClick} type="button"
+                  class={p.cls('indicator')} disabled={step.disabled} @click={step.onClick}
+                  aria-label={step.ariaLabel} aria-labelledby={!step.ariaLabel && step.label ? titleId : undefined}>
+                  <span class={p.cls('indicator-content')} aria-hidden="true">{step.content ?? index + 1}</span>
+                </button>
+                <span #else class={p.cls('indicator')}>
+                  <span class={p.cls('indicator-content')} aria-hidden="true">{step.content ?? index + 1}</span>
+                </span>
+                <span #if={index < steps.length - 1} class={p.cls('line')} aria-hidden="true" />
+              </div>
+              <div #if={step.label || step.description} class={p.cls('label')}>
+                <span #if={step.label} id={titleId} class={p.cls('title')}>{step.label}</span>
+                <small #if={step.description} id={`description${m.id}${index}`}>{step.description}</small>
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Interactive steps are native buttons operable with `Enter` or `Space`.
+- Disabled interactive steps are skipped in the tab order.
+- Non-interactive steps do not enter the tab order.
+
+## Accessibility notes
+
+- The sequence is a named ordered list. The current item exposes `aria-current="step"`.
+- Visible labels name interactive steps through `aria-labelledby`. Empty `ariaLabel` values fall back to `Step N of M` when no visible label is present.
+- Indicator glyphs are hidden from assistive technology.
+- Connecting lines are decorative.
+- Pointer targets remain at least 44 CSS pixels even when the visible indicator is smaller.
+- Shared web styles keep a visible `:focus-visible` indicator.
+
+## Known limitations
+
+- Nested steppers require distinct labels so the sequences remain distinguishable.
+- Automated accessibility checks do not by themselves establish WCAG conformance.
+
+## Native renderer mapping
+
+Native renderers use an accessible ordered collection. Do not copy ARIA
+attributes into native markup. Interactive steps map to native buttons with
+native disabled state. Focus restoration and current-step identification use
+the platform equivalent of `aria-current="step"`.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA APG patterns: https://www.w3.org/WAI/ARIA/apg/patterns/
+- GOV.UK task list: https://design-system.service.gov.uk/components/task-list/

package/dist/Table/README.md

@@ -0,0 +1,76 @@
+# Table
+
+Table provides data-grid primitives for column visibility, ordering, pinning,
+sorting, filtering, grouping, expansion, and row selection. The mediator owns
+the table state and generated identifiers; framework renderers only connect it
+to their native table elements.
+
+## Identifier lifecycle
+
+Each mediator instance creates an identifier with `idCache.getId('table')`.
+Renderers use `m.id` as the prefix for header and cell identifiers, keeping ARIA
+relationships unique across multiple tables. `m.useBeforeUnmount()` clears both
+row identity records and the generated identifier.
+
+## Mediator API
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `string` | Unique generated prefix for table accessibility identifiers. |
+| `state` | `TableState` | Reactive columns, rows, controlled values, and drag state. |
+| `table` | `TableInstance` | Public table instance used by consumers and slots. |
+| `onMounted` | `(element: HTMLTableElement) => void` | Attaches the rendered table so header groups can be measured. |
+| `onScroll` | `(event: unknown) => void` | Forwards scrolling from the renderer's scrollable table body. |
+| `useBeforeUnmount` | `() => void` | Releases row IDs and the table identifier. |
+
+## Renderer contract
+
+```xts
+import { useBeforeUnmount, useMediator, useMounted, withDefaultProps } from '@pastweb/x';
+import { tableMediator } from '@pastweb/components-core/Table';
+import { DEFAULT_PROPS } from './constants';
+
+export function Table(props: TableProps) {
+  const p = withDefaultProps<TableDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<TableMediator>(tableMediator, p);
+  const s = m.state;
+
+  useMounted(element => m.onMounted(element));
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <table aria-label={p.caption ? undefined : p.ariaLabel}>
+      <caption #if={p.caption}>{p.caption}</caption>
+      <thead>
+        <tr #for={group of s.headerGroups}>
+          <th
+            #for={header of group.headers}
+            id={`${m.id}-${header.column.id}`}
+            scope="col"
+          >
+            <render content={header.column.columnDef.header} props={{ column: header.column }} />
+          </th>
+        </tr>
+      </thead>
+      <tbody>{/* render s.rows with the same m.id prefix for labelled cells */}</tbody>
+    </table>
+  );
+}
+```
+
+Always register `m.useBeforeUnmount` in the framework renderer. Do not create
+table identifiers in a framework-specific hook: a mediator-owned ID makes the
+same accessibility contract portable to every supported renderer.
+
+## Body scrolling
+
+Renderers should attach `m.onScroll` to the scrollable element that contains the
+table body. The core mediator deliberately forwards the event without assuming
+a browser event type, so each renderer can use its native event while consumers
+can implement behaviors such as infinite loading.
+
+```ts
+<div onScroll={m.onScroll}>
+  <table><!-- rows --></table>
+</div>
+```