@pastweb/components-core 2.0.0 → 2.2.0

package/dist/Accordion/README.md

@@ -0,0 +1,251 @@
+# Accordion
+
+Accordion presents related sections whose content can be expanded and collapsed.
+Its rendering contract follows the WAI-ARIA Accordion pattern and targets WCAG
+2.2 Level AA.
+
+## When to use
+
+Use an accordion when research shows that users benefit from seeing an overview
+of several related sections and selectively revealing their content. Do not use
+it for content every user must read, for a sequence of form questions, or inside
+another accordion. Prefer ordinary headings, links to page sections, separate
+pages, or native `details` elements when those are simpler.
+
+## Accordion props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `ariaLabel` | `string` | no | `"Accordion"` | Labels the accordion group. Provide a task-specific label when possible; pass an empty string to omit the group semantics. |
+| `className` | `string` | no | `""` | Adds classes to the accordion wrapper. |
+| `disabled` | `boolean` | no | - | Disables every panel trigger. Prefer removing unavailable sections or explaining their unavailable content. |
+| `id` | `string` | no | - | Supplies the root ID. |
+| `rtl` | `boolean` | no | - | Enables right-to-left layout. |
+| `transitionDuration` | `number` | no | `500` | Default panel transition duration in milliseconds. |
+
+## Accordion mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name. An empty string is stored as `undefined` so the group role and label are omitted. |
+| `isDisabled` | `true \| undefined` | Normalized disabled state. Renderers must use this value for the root `is-disabled` class, `aria-disabled`, and must never convert `false`. |
+| `role` | `'group' \| undefined` | Group role present only when `ariaLabel` is a non-empty string. |
+
+## Accordion mediator context
+
+`accordionMediator.getContext()` exposes live getters consumed by each
+`AccordionPanel`. Values that also exist on mediator state are read from that
+normalized state rather than recomputed from raw props.
+
+| Property | Type | Description |
+|---|---|---|
+| `className` | `string` | Root classes inherited by every panel for coordinated styling. |
+| `disabled` | `true \| undefined` | Normalized accordion disabled state. |
+| `rtl` | `boolean` | Root text-direction preference combined with each panel's local `rtl` prop. |
+| `transitionDuration` | `number` | Default panel transition duration in milliseconds. |
+
+## Accordion slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| default | Supplies the ordered `AccordionPanel` children rendered inside the accordion wrapper. | Empty. |
+
+## CSS Variables
+
+Accordion variables follow the
+`--pw_<ComponentName>_<part>_<state>_<css-property>` token grammar. The
+component name is PascalCase; part and state names are lowercase kebab case.
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Accordion_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_background-color)` | Panel background colour. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_color` | `root` | `default` | `color` | `var(--pw_text_color)` | Default accordion text colour. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_font-size` | `root` | `default` | `font-size` | `var(--pw_font-size)` | Base accordion font size. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_line-height` | `root` | `default` | `line-height` | `var(--pw_line-height)` | Base accordion line height. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_border-color` | `root` | `default` | `border-color` | `var(--pw_border-color)` | Border colour used by the wrapper and panel separators. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_border-width` | `root` | `default` | `border-width` | `var(--pw_border-width)` | Border width used by the wrapper and panel separators. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_border-style` | `root` | `default` | `border-style` | `var(--pw_border-style)` | Border style used by the wrapper and panel separators. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Outer accordion corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_border` | `root` | `default` | `border` | width, style and colour tokens | Composed border shorthand. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_root_default_transition-duration` | `root` | `default` | `transition-duration` | `0.5s` | Duration of panel open and close transitions. | Web, Capacitor; NativeScript adapter |
+| `--pw_Accordion_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled accordion opacity. Descendant panels reset their own opacity to avoid compounding it. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_header_default_padding` | `header` | `default` | `padding` | `var(--pw_padding)` | Space inside the panel trigger. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_header_default_background-color` | `header` | `default` | `background-color` | `var(--pw_control_background-color)` | Default trigger background colour. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_header_default_color` | `header` | `default` | `color` | `var(--pw_text_strong_color)` | Trigger text and icon colour. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_header_default_font-size` | `header` | `default` | `font-size` | `1em` | Trigger font size. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_header_default_font-weight` | `header` | `default` | `font-weight` | `var(--bold_font-weight)` | Trigger font weight. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_header_default_line-height` | `header` | `default` | `line-height` | `var(--pw_line-height)` | Trigger line height. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_header_disabled_opacity` | `header` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Opacity of an individually disabled panel. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_close-button_default_background-color` | `close-button` | `default` | `background-color` | header background token | Default expand/collapse icon background. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_close-button_hover_background-color` | `close-button` | `hover` | `background-color` | header colour token | Expand/collapse icon background while the web trigger is hovered. | Web, Capacitor |
+| `--pw_Accordion_close-bar_default_background-color` | `close-bar` | `default` | `background-color` | header colour token | Default expand/collapse icon bar colour. | Web, Capacitor, NativeScript |
+| `--pw_Accordion_close-bar_hover_background-color` | `close-bar` | `hover` | `background-color` | header background token | Expand/collapse icon bar colour while the web trigger is hovered. | Web, Capacitor |
+| `--pw_Accordion_content_default_padding` | `content` | `default` | `padding` | header padding token | Space inside expanded panel content. | Web, Capacitor, NativeScript |
+
+```xts
+// Accordion
+import { setContext, useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { accordionMediator } from '@pastweb/components-core/Accordion';
+import { DEFAULT_PROPS, ACCORDION_CONTEXT_KEY } from './constants';
+
+export function Accordion(props: AccordionProps) {
+  const p = withDefaultProps<AccordionDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<AccordionMediator>(accordionMediator, p);
+  const s = m.state;
+  const c = m.getContext();
+
+  setContext(ACCORDION_CONTEXT_KEY, c);
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      id={m.id}
+      class={p.cls('Accordion', p.className, { 'is-disabled': s.isDisabled })}
+      role={s.role}
+      aria-label={s.ariaLabel}
+      aria-disabled={s.isDisabled}
+    >
+      <slot />
+    </div>
+  );
+}
+```
+
+## AccordionPanel props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `className` | `string` | no | `""` | Adds classes to the panel. |
+| `disabled` | `boolean` | no | - | Disables the native trigger button. |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | `2` | Web renderer property. Selects the heading level required by the surrounding document. |
+| `id` | `string` | no | generated | Supplies the stable base ID used for trigger and panel relationships. |
+| `isOpen` | `boolean` | no | - | Sets the panel's initial open state. |
+| `landmark` | `boolean` | no | - | Gives the content `role="region"`. Enable selectively to avoid landmark proliferation. |
+| `onOpenChange` | `(isOpen: boolean) => void` | no | - | Reports a user-requested state change. |
+| `title` | `string \| number` | no | `""` | Provides the default accessible trigger content. |
+| `rtl` | `boolean` | no | - | Enables right-to-left layout for this panel. |
+| `transitionDuration` | `number` | no | `500` | Sets this panel's transition duration in milliseconds. |
+
+## AccordionPanel mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `className` | `string` | Complete panel class name, including inherited Accordion classes and `is-disabled` / `is-open`. |
+| `hideBorderBottom` | `boolean` | Indicates that the closed panel trigger should hide its bottom border after the close transition. |
+| `isDisabled` | `true \| undefined` | Normalized disabled state from the panel or parent Accordion. Renderers must use this value for `disabled`, `aria-disabled`, and must never convert `false`. |
+| `isOpen` | `boolean` | Current expanded state. |
+| `isRtl` | `true \| undefined` | Normalized right-to-left layout from the panel or parent Accordion. |
+| `role` | `'region' \| undefined` | Optional landmark role when `landmark` is enabled. |
+| `transitionDuration` | `string` | CSS duration used by the open and close transition. |
+
+## AccordionPanel slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| `header` | Replaces content inside the native trigger button. It does not replace the heading or button. | The title and decorative expand/collapse icon. |
+| default | Supplies panel content. | Empty. |
+
+Custom header content must provide a meaningful accessible name. Decorative
+icons must use `aria-hidden="true"`.
+
+```xts
+// AccordionPanel
+import {
+  useBeforeUnmount,
+  useMediator,
+  useMounted,
+  withDefaultProps,
+} from '@pastweb/x';
+import { accordionPanelMediator } from '@pastweb/components-core/Accordion';
+import { DEFAULT_ACCORDION_PANEL_PROPS } from './constants';
+
+export function AccordionPanel(props: AccordionPanelProps) {
+  const p = withDefaultProps<AccordionPanelDefaultProps>(props, DEFAULT_ACCORDION_PANEL_PROPS);
+  const m = useMediator<AccordionPanelMediator>(accordionPanelMediator, p);
+  const s = m.state;
+  const Heading = `h${p.headingLevel}`;
+
+  useMounted(trigger => {
+    m.useMounted({ focus: () => trigger.focus() });
+  });
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <section
+      id={m.id}
+      class={s.className}
+      dir={s.isRtl ? 'rtl' : undefined}
+      aria-disabled={s.isDisabled}
+      style={{
+        transitionDuration: s.transitionDuration,
+        '--pw_Accordion_root_default_transition-duration': s.transitionDuration,
+      }}
+    >
+      <Heading class={p.cls('heading')}>
+        <button
+          id={m.triggerId}
+          type="button"
+          class={p.cls('header', { rtl: s.isRtl, 'hide-border': s.hideBorderBottom })}
+          aria-expanded={s.isOpen}
+          aria-controls={m.panelId}
+          disabled={s.isDisabled}
+          @click={m.onToggle}
+        >
+          <slot name="header">
+            <span class={p.cls('title')}>
+              <render content={p.title} />
+            </span>
+            <span class={p.cls('closeButton', s.isOpen ? 'is-open' : '')} aria-hidden="true">
+              <span class={p.cls('closeBar')} />
+              <span class={p.cls('closeBar')} />
+            </span>
+          </slot>
+        </button>
+      </Heading>
+
+      <div
+        id={m.panelId}
+        class={p.cls('container', s.isOpen ? 'is-open' : '')}
+        role={s.role}
+        aria-labelledby={m.triggerId}
+        aria-hidden={!s.isOpen}
+        inert={!s.isOpen}
+        @transitionend={m.onTransitionEnd}
+      >
+        <div class={p.cls('contentWrapper')}>
+          <div class={p.cls('content')}>
+            <slot />
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+```
+
+## Keyboard interaction
+
+- `Tab` and `Shift+Tab` move through panel triggers and focusable open content in normal document order.
+- `Enter` or `Space` on a trigger toggles its panel through native button behavior.
+- Collapsed panel content is removed from sequential focus navigation.
+
+## Accessibility notes
+
+- The trigger is a native button inside a native heading.
+- `aria-expanded` communicates state, while `aria-controls` and
+  `aria-labelledby` establish the trigger/content relationship.
+- Closing content becomes inert and hidden from the accessibility tree
+  immediately. Web renderers keep it mounted so the grid-row transition can
+  animate the real content height in both directions.
+- `role="region"` is opt-in because repeated regions can create excessive
+  landmarks.
+- Shared styles retain visible focus, support `forced-colors`, and disable
+  non-essential transitions under `prefers-reduced-motion`.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Accordion pattern: https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+- GOV.UK Accordion guidance: https://design-system.service.gov.uk/components/accordion/

package/dist/Button/README.md

@@ -0,0 +1,143 @@
+# Button
+
+Button renders a native action control with independent disabled and loading
+states. Its rendering contract follows the WAI-ARIA Button pattern and targets
+WCAG 2.2 Level AA.
+
+## When to use
+
+Use a button to perform an action on the current page. Use a link when activation
+navigates to another location. Button labels should start with a clear verb and
+describe the result of activation.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `className` | `string` | no | `""` | Adds classes to the native button. The legacy `is-loading` class continues to enable loading behavior. |
+| `disabled` | `boolean` | no | - | Makes the action unavailable. |
+| `id` | `string` | no | generated | Supplies the button ID. Generated IDs use the `button` prefix. |
+| `loading` | `boolean` | no | - | Marks the action busy, suppresses its click handler, and displays the loading slot without disabling the native button. |
+| `onClick` | `(event: unknown) => void` | no | noop | Handles an available button activation. Renderers may narrow the event type. |
+| `tabIndex` | `number` | no | `0` | Controls sequential keyboard focus order. Prefer the default document order. |
+| `type` | `'button' \| 'submit' \| 'reset'` | no | `'button'` | Selects native button behavior. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `isDisabled` | `true \| undefined` | Is `true` when the button or its Buttons context is disabled; otherwise omitted. Renderers use this value directly for `.is-disabled`, `disabled`, and `aria-disabled`. |
+| `isLoading` | `boolean` | Indicates loading independently from `isDisabled`. Loading suppresses the click handler without disabling the native button. |
+
+## Mediator context
+
+Button does not publish its own context. When rendered inside `Buttons`, its
+mediator optionally consumes the parent `ButtonsContext` value below and
+combines it with the local `disabled` prop.
+
+| Context property | Type | Description |
+|---|---|---|
+| `disabled` | `true \| undefined` | Normalized disabled state inherited from the containing Buttons component. |
+
+## Slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| default | Supplies the button's accessible label and optional icon content. | Empty. |
+| `loading` | Supplies status content while `loading` is active. | `Loading...` |
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-rounded` | Uses the rounded button radius token. |
+| `is-full-width` | Expands the button to the available width. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Button_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_control_background-color)` | Button background. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_color` | `root` | `default` | `color` | `var(--pw_text_strong_color)` | Button text colour. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_padding` | `root` | `default` | `padding` | `var(--pw_padding)` | Inner spacing. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_margin` | `root` | `default` | `margin` | `var(--pw_margin)` | Outer spacing. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_border-color` | `root` | `default` | `border-color` | `var(--pw_border-color)` | Default border colour. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_border-width` | `root` | `default` | `border-width` | `var(--pw_border-width)` | Border width. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_border-style` | `root` | `default` | `border-style` | `var(--pw_border-style)` | Border style. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Default corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_rounded_border-radius` | `root` | `rounded` | `border-radius` | `var(--pw_rounded_border-radius)` | Corner radius for `is-rounded`. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_transition-duration` | `root` | `default` | `transition-duration` | `var(--pw_transition-duration)` | Visual state transition duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_Button_color_default_box-shadow` | `color` | `default` | `box-shadow` | `var(--pw_color_box-shadow)` | Focus shadow colour. | Web, Capacitor |
+| `--pw_Button_inset-color_default_box-shadow` | `inset-color` | `default` | `box-shadow` | `var(--pw_inset_color_box-shadow)` | Hover inset shadow colour. | Web, Capacitor |
+| `--pw_Button_size_default_box-shadow` | `size` | `default` | `box-shadow` | `var(--pw_size_box-shadow)` | Shadow size. | Web, Capacitor |
+| `--pw_Button_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled opacity. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_font-size` | `root` | `default` | `font-size` | `var(--pw_font-size)` | Label font size. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_font-weight` | `root` | `default` | `font-weight` | `var(--pw_semibold_font-weight)` | Label font weight. | Web, Capacitor, NativeScript |
+| `--pw_Button_root_default_line-height` | `root` | `default` | `line-height` | `var(--pw_line-height)` | Label line height. | Web, Capacitor, NativeScript |
+| `--pw_Button_item_default_gap` | `item` | `default` | `gap` | `var(--pw_horizontal_padding)` | Spacing between rendered items. | Web, Capacitor |
+| `--pw_Button_icon_default_color` | `icon` | `default` | `color` | button colour | Icon colour. | Web, Capacitor, NativeScript |
+| `--pw_Button_icon_default_stroke` | `icon` | `default` | `stroke` | icon colour | Icon stroke. | Web, Capacitor |
+| `--pw_Button_icon_default_size` | `icon` | `default` | `size` | `var(--pw_icon_size)` | Font-icon size. | Web, Capacitor, NativeScript |
+
+```xts
+import { useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { buttonMediator } from '@pastweb/components-core/Button';
+import { DEFAULT_PROPS } from './constants';
+
+export function Button(props: ButtonProps) {
+  const p = withDefaultProps<ButtonDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<ButtonMediator>(buttonMediator, p);
+  const s = m.state;
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <button
+      id={m.id}
+      type={p.type}
+      class={p.cls('Button', p.className, { 'is-disabled': s.isDisabled, 'is-loading': s.isLoading })}
+      @click={m.onClick}
+      disabled={s.isDisabled}
+      aria-disabled={s.isDisabled}
+      aria-busy={s.isLoading || undefined}
+      tabIndex={p.tabIndex}
+    >
+      <slot
+        map={(child, index) => (
+          <span key={index} class={p.cls('item')}>{child}</span>
+        )}
+      />
+      <span #if={s.isLoading} class={p.cls('loading')} role="status" aria-live="polite">
+        <slot name="loading">Loading...</slot>
+      </span>
+    </button>
+  );
+}
+```
+
+## Accessibility notes
+
+- The renderer must use a native button and preserve its keyboard activation.
+- Disabled buttons use the native `disabled` property, `aria-disabled="true"`,
+  and the `is-disabled` class.
+- Loading buttons remain independently enabled, expose `aria-busy="true"` and
+  the `is-loading` class, and suppress the component click handler. Status
+  content is announced politely.
+- A button may be both disabled and loading when both states are set.
+- The accessible name must remain meaningful without relying on a decorative icon.
+- Shared web styles provide at least a 44 by 44 CSS-pixel target, visible focus,
+  forced-colours treatment, and reduced-motion behavior.
+
+## Keyboard interaction
+
+- `Tab` and `Shift+Tab` move focus to and from the native button in document order.
+- `Enter` or `Space` activates the button through native button behavior.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Button pattern: https://www.w3.org/WAI/ARIA/apg/patterns/button/
+- GOV.UK Button guidance: https://design-system.service.gov.uk/components/button/

package/dist/Buttons/README.md

@@ -0,0 +1,108 @@
+# Buttons
+
+Buttons groups related action controls and gives the collection a shared
+accessible name. Its rendering contract follows the WAI-ARIA Button pattern
+for the grouped native buttons and targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use Buttons when two or more actions belong to the same decision or workflow.
+Keep the primary action first in the expected reading direction and avoid large
+groups that make choices difficult to scan.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `ariaLabel` | `string` | no | `"Button group"` | Supplies the group's accessible name. Applications should provide a task-specific label; pass an empty string to omit the group semantics. |
+| `className` | `string` | no | `""` | Adds classes to the group wrapper. |
+| `disabled` | `boolean` | no | - | Disables descendant Pastweb Button components and marks the group unavailable. |
+| `id` | `string` | no | generated | Supplies the group ID. Generated IDs use the `buttons` prefix. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible label for the group. Empty labels are omitted. |
+| `isDisabled` | `true \| undefined` | Is `true` when the group is disabled; otherwise omitted. Renderers use this value directly for `.is-disabled` and `aria-disabled`, and the Buttons context shares it with descendant Button mediators. |
+| `role` | `'group' \| undefined` | Is `group` when `ariaLabel` supplies an accessible group name; otherwise omitted. |
+
+## Mediator context
+
+`buttonsMediator.getContext()` exposes a live value consumed by descendant
+Button mediators.
+
+| Property | Type | Description |
+|---|---|---|
+| `disabled` | `true \| undefined` | Normalized group disabled state combined with each Button's local `disabled` prop. |
+
+## Slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| default | Supplies the related Button controls in their intended reading and action order. | Empty. |
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-rounded` | Rounds the group's exposed first and last button corners. |
+| `is-full-width` | Expands the group to the available width and distributes its buttons evenly. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Buttons_root_default_margin` | `root` | `default` | `margin` | `var(--pw_margin)` | Group outer spacing. | Web, Capacitor, NativeScript |
+| `--pw_Buttons_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Outer button corner radius. | Web, Capacitor, NativeScript |
+| `--pw_Buttons_root_rounded_border-radius` | `root` | `rounded` | `border-radius` | `var(--pw_rounded_border-radius)` | Outer radius for rounded groups. | Web, Capacitor, NativeScript |
+| `--pw_Buttons_color_default_box-shadow` | `color` | `default` | `box-shadow` | `var(--pw_color_box-shadow)` | First-button focus shadow colour. | Web, Capacitor |
+| `--pw_Buttons_inset-color_default_box-shadow` | `inset-color` | `default` | `box-shadow` | `var(--pw_inset_color_box-shadow)` | First-button hover inset shadow colour. | Web, Capacitor |
+| `--pw_Buttons_size_default_box-shadow` | `size` | `default` | `box-shadow` | `var(--pw_size_box-shadow)` | First-button shadow size. | Web, Capacitor |
+
+```xts
+import { setContext, useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { BUTTONS_CONTEXT_KEY, buttonsMediator } from '@pastweb/components-core/Buttons';
+import { DEFAULT_PROPS } from './constants';
+
+export function Buttons(props: ButtonsProps) {
+  const p = withDefaultProps<ButtonsDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<ButtonsMediator>(buttonsMediator, p);
+  const s = m.state;
+  const c = m.getContext();
+  setContext(BUTTONS_CONTEXT_KEY, c);
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      id={m.id}
+      class={p.cls('Buttons', p.className, { 'is-disabled': s.isDisabled })}
+      role={s.role}
+      aria-label={s.ariaLabel}
+      aria-disabled={s.isDisabled}
+    >
+      <slot />
+    </div>
+  );
+}
+```
+
+## Accessibility notes
+
+- The wrapper uses `role="group"` only when `ariaLabel` provides a meaningful
+  accessible name. The default is `"Button group"`; both attributes are omitted
+  when an empty string is provided explicitly.
+- Buttons retain their normal tab order and native keyboard behavior.
+- Use a toolbar component with documented arrow-key behavior instead when the
+  collection represents a persistent application toolbar.
+- Keep one primary call to action in a group. Additional default buttons make
+  the next step harder to identify.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Button pattern: https://www.w3.org/WAI/ARIA/apg/patterns/button/
+- GOV.UK Button guidance: https://design-system.service.gov.uk/components/button/