@pastweb/components-core 2.0.0 → 2.2.0

package/dist/DropDown/README.md

@@ -0,0 +1,237 @@
+# DropDown
+
+DropDown reveals contextual content from a trigger. Its rendering contract
+follows the WAI-ARIA Disclosure pattern and targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use DropDown for short contextual content or a collection of actions associated
+with a trigger. Do not use hover-only activation for essential content. Use a
+dialog when the revealed content requires a modal task or a complex form.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `id` | `string` | no | generated | Supplies the stable base for trigger and content IDs. Generated IDs use the `dropDown` prefix. |
+| `ariaLabel` | `string` | no | `"DropDown"` | Names the trigger when its visible content does not provide a name. Pass an empty string to omit the accessible name. |
+| `arrow` | `boolean` | no | `true` | Displays the visual arrow. |
+| `className` | `string` | no | `""` | Adds classes to the root. |
+| `contentClassName` | `string` | no | `""` | Adds classes to the revealed content. |
+| `offset` | `number` | no | `2` | Sets the renderer positioning offset. |
+| `disabled` | `boolean` | no | `false` | Prevents the content from opening. |
+| `isVisible` | `boolean` | no | `false` | Controls the requested visibility. |
+| `visibleOn` | `'click' \| 'over' \| 'context'` | no | `'click'` | Selects the activation model. Essential content must remain available without hover or a context-menu gesture. |
+| `visibleTarget` | `'element' \| 'pointer'` | no | `'element'` | Selects the positioning reference. `element` uses the trigger. `pointer` uses the pointer position from the trigger event. Keyboard and programmatic opens fall back to the trigger. |
+| `placement` | `Placement` | no | `'bottom'` | Requests placement relative to the trigger. |
+| `hideOnClick` | `boolean` | no | `true` | Closes after activation inside the revealed content. |
+| `hideOnClickOut` | `boolean` | no | `true` | Closes after a click or context-menu activation outside the component. |
+| `hideOnBlur` | `boolean` | no | `true` | Closes when focus leaves the component. |
+| `position` | `'absolute' \| 'fixed'` | no | `'absolute'` | Selects the web positioning strategy. |
+| `clickTimeGap` | `number` | no | `16` | Delays click/context activation in milliseconds. |
+| `onChange` | `(isVisible: boolean) => void` | no | noop | Reports visibility changes. |
+| `onClick` | `() => void` | no | noop | Reports click activation. |
+| `onContext` | `() => void` | no | noop | Reports context-menu activation. |
+| `onClickOut` | `() => void` | no | noop | Reports an outside activation that closed the content. |
+| `onMouseEnter` | `() => void` | no | noop | Reports hover open. |
+| `onMouseLeave` | `() => void` | no | noop | Reports hover close. |
+
+## Mediator API
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `string` | Resolved host ID. Generated IDs use the `dropDown` prefix; an explicit `id` is exposed as `_${id}`. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized trigger accessible name. Empty labels are omitted. |
+| `contentId` | `string` | Content relationship ID in the form `content${id}`. |
+| `isDisabled` | `true \| undefined` | Is `true` when the DropDown is disabled; otherwise omitted. Renderers use this value directly for `.is-disabled`, `aria-disabled`, and unavailable keyboard behavior. |
+| `isVisible` | `boolean` | Whether the content is requested open. Renderers use this for `.is-open`, `.is-visible`, `aria-expanded`, and `hidden`. |
+| `triggerId` | `string` | Trigger relationship ID in the form `trigger${id}`. |
+
+## Mediator context
+
+Descendant or replacement-slot content reads this API through the renderer context hook. Live getters stay synchronized with mediator state.
+
+| Context property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized trigger accessible name. |
+| `arrow` | `boolean` | Whether the decorative arrow is requested. |
+| `cls` | `(...args: ClassValue[]) => string` | Resolves component classes. |
+| `contentClassName` | `string` | Classes added to the revealed content. |
+| `contentId` | `string` | Content relationship ID. |
+| `hide` | `() => void` | Closes the DropDown. Nested menus should call this from item activation. |
+| `id` | `string` | Resolved host ID. |
+| `isDisabled` | `true \| undefined` | Normalized disabled state. |
+| `isVisible` | `boolean` | Whether the content is requested open. |
+| `onClick` | `(event?) => void` | Toggles click-activated content. |
+| `onKeyDown` | `(event) => void` | Handles Enter, Space, and Escape. |
+| `position` | `'absolute' \| 'fixed'` | Web positioning strategy. |
+| `setArrowRef` | `(arrow?) => void` | Stores the mounted arrow reference. |
+| `triggerId` | `string` | Trigger relationship ID. |
+
+## Slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| default | Supplies the trigger content. | Empty. |
+| `header` | Supplies optional leading content inside the revealed panel. | Empty. |
+| `content` | Supplies the main revealed content. | Empty. |
+| `footer` | Supplies optional trailing content inside the revealed panel. | Empty. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_DropDown_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled opacity. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_content_default_background-color` | `content` | `default` | `background-color` | `var(--pw_control_background-color)` | Revealed-content background. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_content_default_color` | `content` | `default` | `color` | `var(--pw_text_color)` | Content foreground. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_content_default_border-color` | `content` | `default` | `border-color` | `var(--pw_border-color)` | Content border colour. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_content_default_border-width` | `content` | `default` | `border-width` | `var(--pw_border-width)` | Content border width. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_content_default_border-style` | `content` | `default` | `border-style` | `var(--pw_border-style)` | Content border style. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_content_default_border-radius` | `content` | `default` | `border-radius` | `var(--pw_small_border-radius)` | Content corner radius. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_content_default_padding` | `content` | `default` | `padding` | `var(--pw_padding) 0` | Content spacing. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_content_default_box-shadow` | `content` | `default` | `box-shadow` | shared shadow | Floating-content elevation. | Web, Capacitor |
+| `--pw_DropDown_arrow_default_border-width` | `arrow` | `default` | `border-width` | `1em` | Arrow triangle size. | Web, Capacitor |
+| `--pw_DropDown_target_default_min-width` | `target` | `default` | `min-width` | `2.75em` | Minimum target width. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_target_default_min-height` | `target` | `default` | `min-height` | `2.75em` | Minimum target height. | Web, Capacitor, NativeScript |
+| `--pw_DropDown_target_focus-visible_box-shadow` | `target` | `focus-visible` | `box-shadow` | shared focus shadow | Keyboard focus indicator. | Web, Capacitor |
+
+```xts
+import {
+  setContext,
+  useBeforeUnmount,
+  useMediator,
+  useMounted,
+  useRef,
+  withDefaultProps,
+} from '@pastweb/x';
+import { dropdownMediator } from '@pastweb/components-core/DropDown';
+import { DEFAULT_PROPS, DROPDOWN_CONTEXT_KEY } from './constants';
+
+export function DropDown(props: DropDownProps) {
+  const p = withDefaultProps<DropDownDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<DropDownMediator>(dropdownMediator, p);
+  const s = m.state;
+  const c = m.getContext();
+  const rootRef = useRef(null);
+  const targetRef = useRef(null);
+  const containerRef = useRef(null);
+  const contentRef = useRef(null);
+  const arrowRef = useRef(null);
+
+  setContext(DROPDOWN_CONTEXT_KEY, c);
+  useMounted(() => {
+    if (
+      !rootRef.value
+      || !targetRef.value
+      || !containerRef.value
+      || !contentRef.value
+    ) return;
+
+    m.useMounted(
+      rootRef.value,
+      targetRef.value,
+      containerRef.value,
+      contentRef.value,
+    );
+    if (arrowRef.value) m.setArrowRef(arrowRef.value);
+  });
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      #ref={rootRef}
+      id={m.id}
+      class={p.cls('DropDown', p.className, {
+        'is-disabled': s.isDisabled,
+        'is-open': s.isVisible,
+      })}
+      @click={m.onClick}
+      @contextmenu={m.onContext}
+      @mouseenter={m.onMouseEnter}
+      @mouseleave={m.onMouseLeave}
+      @blur={m.onBlur}
+    >
+      <span
+        #ref={targetRef}
+        id={s.triggerId}
+        class={p.cls('target')}
+        role="button"
+        tabIndex={s.isDisabled ? -1 : 0}
+        aria-label={s.ariaLabel}
+        aria-haspopup="true"
+        aria-expanded={s.isVisible}
+        aria-controls={s.contentId}
+        aria-disabled={s.isDisabled}
+        @keydown={m.onKeyDown}
+      >
+        <slot />
+        <div
+          #ref={containerRef}
+          class={p.cls('container', { 'is-visible': s.isVisible })}
+          style={{ position: p.position }}
+          aria-hidden={!s.isVisible || undefined}
+          inert={!s.isVisible || undefined}
+        >
+          <div
+            #ref={contentRef}
+            id={s.contentId}
+            class={p.cls('content', p.contentClassName)}
+            aria-labelledby={s.triggerId}
+            @click={m.onClick}
+          >
+            <slot name="header" />
+            <slot name="content" />
+            <slot name="footer" />
+          </div>
+          <div #if={p.arrow} #ref={arrowRef} class={p.cls('arrow')} aria-hidden="true">
+            <div class={p.cls('triangle')} />
+          </div>
+        </div>
+      </span>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- `Tab` and `Shift+Tab` move focus to and from the trigger in document order.
+- `Enter` or `Space` on the trigger toggles click-activated content.
+- A click on the trigger hides context-activated content when it is already open.
+- `Escape` closes open content.
+
+## Accessibility notes
+
+- The trigger exposes expanded, disabled, and ID relationship state.
+- Closed content is `inert` and `aria-hidden` so it is removed from keyboard and
+  accessibility navigation. Do not rely on opacity alone.
+- Hover-only activation is not sufficient for essential content.
+- The decorative arrow is hidden from assistive technology.
+- Shared web styles provide at least a 44 by 44 CSS-pixel target and a visible
+  focus indicator.
+
+## Native renderer mapping
+
+NativeScript renderers map the trigger to a focusable native control, visibility
+to the native hidden/collapsed state, and expanded/disabled intent to native
+accessibility state. Positioning, outside activation, and animation completion
+remain renderer responsibilities and require iOS and Android device testing.
+
+## Known limitations
+
+- Positioning uses web layout measurement. Native renderers must supply an
+  equivalent placement adapter.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Disclosure pattern: https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/
+- GOV.UK Details guidance: https://design-system.service.gov.uk/components/details/

package/dist/FileUploader/README.md

@@ -0,0 +1,224 @@
+# FileUploader
+
+FileUploader lets users choose files through a native file picker, with an
+optional dropzone. Its rendering contract uses a native `input type="file"`
+and a visible trigger, and targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use a file uploader only when a file is required to complete the task. Provide
+a visible label that describes the file being requested. Do not rely on
+drag-and-drop as the only way to add files; keyboard and assistive-technology
+users must be able to open the native picker.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `accept` | `string` | no | - | Restricts the native picker to matching file types. |
+| `ariaLabel` | `string` | no | `"Upload a file"` | Names the trigger when no visible `label` is supplied. Pass an empty string to omit the accessible name. |
+| `className` | `string` | no | `""` | Adds classes to the wrapper. |
+| `disabled` | `boolean` | no | - | Makes choosing and dropping files unavailable. |
+| `dropzone` | `boolean` | no | - | Enables drop-to-add in addition to the native picker. |
+| `formData` | `FormData` | no | `new FormData()` | Supplies the store used for selected files. |
+| `id` | `string` | no | generated | Supplies the root ID. Generated IDs use the `fileUploader` prefix. |
+| `label` | `string` | no | `""` | Supplies the visible accessible label. |
+| `maxNumber` | `number` | no | `1` | Limits how many files can be stored. |
+| `maxSize` | `number` | no | - | Maximum file size in bytes. Oversized files are reported through `onAddFile` and are not stored. |
+| `multiple` | `boolean` | no | - | Allows the native picker to select more than one file at a time. |
+| `name` | `string` | no | - | Supplies the native file input name. |
+| `tabIndex` | `number` | no | `0` | Controls sequential focus order of the trigger. Prefer the default document order. |
+| `onAddFile` | `(file: File, data: FormData) => void` | no | noop | Reports each file after a successful store, and oversized files that were rejected. |
+
+## Mediator API
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `string` | Resolved host ID. Generated IDs use the `fileUploader` prefix; an explicit `id` is exposed as `_${id}`. |
+| `inputId` | `string` | File input ID derived as `input${id}`. |
+| `labelId` | `string` | Visible label ID derived as `label${id}`. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name when no visible `label` is present. Empty labels are omitted. |
+| `canAddMore` | `boolean` | Is `true` while stored files are under `maxNumber`. |
+| `fileCount` | `number` | Number of stored files. |
+| `files` | `File[]` | File values currently stored in FormData. |
+| `isDisabled` | `true \| undefined` | Is `true` when the uploader is disabled; otherwise omitted. Renderers use this value directly for `.is-disabled`, `disabled`, and `aria-disabled`. |
+| `isDragging` | `true \| undefined` | Is `true` while files are dragged over an enabled dropzone; otherwise omitted. Renderers use this value for `.is-dragging`. |
+
+## Mediator context
+
+`fileUploaderMediator.getContext()` exposes live getters consumed by custom
+descendant content. Values that also exist on mediator state are read from that
+normalized state rather than recomputed from raw props.
+
+| Property | Type | Description |
+|---|---|---|
+| `accept` | `string \| undefined` | Native picker accept filter. |
+| `canAddMore` | `boolean` | Whether another file can be stored. |
+| `dropzone` | `boolean` | Whether drop-to-add is enabled. |
+| `fileCount` | `number` | Number of stored files. |
+| `files` | `File[]` | Stored File values. |
+| `formData` | `FormData` | The file store. |
+| `id` | `string` | Resolved host ID. |
+| `inputId` | `string` | File input ID. |
+| `isDisabled` | `true \| undefined` | Normalized disabled state. |
+| `labelId` | `string` | Visible label ID. |
+| `maxNumber` | `number` | Stored-file limit. |
+| `maxSize` | `number \| undefined` | Maximum file size in bytes. |
+| `multiple` | `boolean` | Native picker multiple-selection flag. |
+| `removeFile` | `(fileName: string) => void` | Removes a stored file by the FormData key used when it was added. |
+
+## Slots
+
+| SlotName | Description | Default content |
+|---|---|---|
+| default | Supplies trigger content such as an icon or “Choose file” text. Must provide an accessible name when `label` and `ariaLabel` are both empty. | Empty. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_FileUploader_root_default_background-color` | `root` | `default` | `background-color` | `var(--pw_control_background-color)` | Trigger background. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_color` | `root` | `default` | `color` | `var(--pw_text_color)` | Trigger text colour. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_padding` | `root` | `default` | `padding` | `var(--pw_padding)` | Trigger inner spacing. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_margin` | `root` | `default` | `margin` | shared margins | Component spacing. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_border-color` | `root` | `default` | `border-color` | `var(--pw_border-color)` | Trigger border colour. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_border-width` | `root` | `default` | `border-width` | `var(--pw_border-width)` | Trigger border width. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_border-style` | `root` | `default` | `border-style` | `var(--pw_border-style)` | Trigger border style. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_border-radius` | `root` | `default` | `border-radius` | `var(--pw_border-radius)` | Trigger corner radius. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_rounded_border-radius` | `root` | `rounded` | `border-radius` | `var(--pw_rounded_border-radius)` | Trigger corner radius for `is-rounded`. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_min-height` | `root` | `default` | `min-height` | `2.75em` | Minimum trigger size, 44px at the default font size. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_default_transition-duration` | `root` | `default` | `transition-duration` | `var(--pw_transition-duration)` | Visual state transition duration. | Web, Capacitor; NativeScript adapter |
+| `--pw_FileUploader_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled opacity. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_root_highlighted_border-color` | `root` | `highlighted` | `border-color` | `var(--pw_outline_color)` | Drop-target border colour. | Web, Capacitor |
+| `--pw_FileUploader_trigger_default_gap` | `trigger` | `default` | `gap` | `var(--pw_horizontal_padding)` | Space between trigger contents. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_label_default_color` | `label` | `default` | `color` | `var(--pw_label_text_color)` | Visible label colour. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_label_default_font-weight` | `label` | `default` | `font-weight` | `var(--pw_semibold_font-weight)` | Visible label weight. | Web, Capacitor, NativeScript |
+| `--pw_FileUploader_color_default_box-shadow` | `color` | `default` | `box-shadow` | `var(--pw_color_box-shadow)` | Focus and drag shadow colour. | Web, Capacitor |
+| `--pw_FileUploader_size_default_box-shadow` | `size` | `default` | `box-shadow` | `var(--pw_size_box-shadow)` | Shadow size. | Web, Capacitor |
+
+```xts
+import {
+  setContext,
+  useBeforeUnmount,
+  useMediator,
+  useMounted,
+  useRef,
+  withDefaultProps,
+} from '@pastweb/x';
+import { fileUploaderMediator } from '@pastweb/components-core/FileUploader';
+import { DEFAULT_PROPS, FILE_UPLOADER_CONTEXT_KEY } from './constants';
+
+export function FileUploader(props: FileUploaderProps) {
+  const p = withDefaultProps<FileUploaderDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<FileUploaderMediator>(fileUploaderMediator, p);
+  const s = m.state;
+  const inputRef = useRef(null);
+  const c = m.getContext();
+
+  setContext(FILE_UPLOADER_CONTEXT_KEY, c);
+  useMounted(() => m.useMounted(inputRef.value));
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div
+      id={m.id}
+      class={p.cls('FileUploader', p.className, {
+        'is-disabled': s.isDisabled,
+        'is-dragging': s.isDragging,
+        'is-dropzone': p.dropzone,
+        'is-full': !s.canAddMore,
+      })}
+      aria-disabled={s.isDisabled}
+      @dragenter={m.onDragEnter}
+      @dragover={m.onDragOver}
+      @dragleave={m.onDragLeave}
+      @drop={m.onDrop}
+    >
+      <label #if={p.label} id={m.labelId} class={p.cls('label')} for={m.inputId}>
+        {p.label}
+      </label>
+      <button
+        type="button"
+        class={p.cls('trigger')}
+        disabled={s.isDisabled}
+        aria-disabled={s.isDisabled}
+        aria-label={s.ariaLabel}
+        aria-labelledby={p.label ? m.labelId : undefined}
+        tabIndex={p.tabIndex}
+        @click={m.onActivate}
+        @keydown={m.onKeyDown}
+      >
+        <slot />
+      </button>
+      <input
+        #ref={inputRef}
+        id={m.inputId}
+        class={p.cls('inputElement')}
+        type="file"
+        name={p.name}
+        accept={p.accept}
+        multiple={p.multiple}
+        disabled={s.isDisabled}
+        tabIndex={-1}
+        @change={m.onChange}
+      />
+    </div>
+  );
+}
+```
+
+Renderers pass native change and drag events through to the mediator. For a
+native change event, the mediator reads the file input from `event.target` and
+falls back to `event.currentTarget`. This supports both native DOM events and
+renderer event wrappers without renderer-specific adapters. The mediator stops
+drag propagation, prevents the browser from opening dropped files, and converts
+`FileList` values to `File[]`.
+
+## Keyboard interaction
+
+- `Tab` and `Shift+Tab` move focus to and from the trigger in document order.
+- `Enter` and `Space` open the native file picker when another file can be
+  stored.
+- The hidden file input is not in the tab order. Keyboard users operate the
+  visible trigger.
+- Drag-and-drop is pointer-only additional behaviour. It must not replace the
+  picker.
+
+## Accessibility behaviour
+
+- The native file input remains the mechanism that chooses files. The trigger
+  is a `type="button"` control that opens that input.
+- A visible `label` names the control through `aria-labelledby`. When no
+  visible label is supplied, `ariaLabel` names the trigger. Pass an empty
+  `ariaLabel` only when slot content already provides the accessible name.
+- Disabled state is exposed as `.is-disabled`, native `disabled`, and
+  `aria-disabled`.
+- Dropzone entry is a visual `is-dragging` state. Do not make dropping the
+  only way to add files.
+- IDs used for the host, label, and input are mediator-owned and stable.
+
+## Native renderer mapping
+
+NativeScript renderers map the contract to the platform file-picker API, a
+native button or equivalent trigger, disabled state, and native accessibility
+name. Web DOM refs, `FileList`, and drag events are renderer details. Do not
+copy ARIA attributes into native markup.
+
+## Known limitations
+
+- `accept` is enforced by the native picker. Dropped files are not filtered by
+  `accept` in the mediator.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## 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 file upload guidance: https://design-system.service.gov.uk/components/file-upload/

package/dist/Icon/README.md

@@ -0,0 +1,103 @@
+# Icon
+
+Icon renders an inline SVG or image URL from a direct source, local collection,
+or Iconify-compatible API. Its rendering contract targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use Icon for a compact visual symbol. Icons are decorative by default. Supply
+`ariaLabel` only when the icon communicates meaning that is not already present
+in nearby text. Do not use an icon as an unlabeled interactive control. Prefer
+a visible text label alongside an icon when the symbol is part of a control.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component classes. |
+| `ariaLabel` | `string` | no | `""` | Names a meaningful icon and gives it the image role. Pass an empty string to keep the icon decorative. |
+| `className` | `string` | no | `""` | Adds classes to the root. |
+| `src` | `string` | no | `""` | Supplies an SVG string, image URL, or data URL. |
+| `name` | `string` | no | `""` | Selects an icon using `collection:icon` syntax. |
+| `collection` | `Collection` | no | `{}` | Supplies trusted local icon sources by collection and name. |
+| `apiUrl` | `string` | no | `https://api.iconify.design` | Selects the Iconify-compatible API endpoint. |
+
+SVG strings are injected as markup and therefore must come from trusted sources.
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaHidden` | `true \| undefined` | Is `true` when the icon is decorative; otherwise omitted. Renderers use this value directly for `aria-hidden`. |
+| `ariaLabel` | `string \| undefined` | Normalized accessible name. Empty labels are omitted. |
+| `collectionName` | `string` | Collection segment parsed from `name`. |
+| `iconData` | `IconData \| string` | Inline SVG markup when the source is an SVG string. |
+| `iconName` | `string` | Icon segment parsed from `name`. |
+| `role` | `'img' \| undefined` | Is `img` when `ariaLabel` supplies a name; otherwise omitted. |
+| `src` | `string` | Image URL when the source is not inline SVG. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Icon_root_default_color` | `root` | `default` | `color` | `var(--pw_text_strong_color)` | Icon foreground. | Web, Capacitor, NativeScript |
+| `--pw_Icon_graphic_default_width` | `graphic` | `default` | `width` | `1em` | Graphic width. | Web, Capacitor, NativeScript |
+| `--pw_Icon_graphic_default_height` | `graphic` | `default` | `height` | `1em` | Graphic height. | Web, Capacitor, NativeScript |
+
+```xts
+import { useMediator, withDefaultProps } from '@pastweb/x';
+import { iconMediator } from '@pastweb/components-core/Icon';
+import { DEFAULT_PROPS } from './constants';
+
+export function Icon(props: IconProps) {
+  const p = withDefaultProps<IconDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<IconMediator>(iconMediator, p);
+  const s = m.state;
+
+  return (
+    <i
+      #if={s.iconData || s.src}
+      class={p.cls('Icon', p.className)}
+      role={s.role}
+      aria-label={s.ariaLabel}
+      aria-hidden={s.ariaHidden}
+      #html={s.iconData || undefined}
+    >
+      <img #if={s.src} src={s.src} alt="" />
+    </i>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Icon is not interactive. It does not enter the tab order.
+
+## Accessibility notes
+
+- Decorative icons are removed from the accessibility tree with `aria-hidden`.
+- Meaningful icons expose `role="img"` and one accessible name on the root.
+  Nested images use empty alternative text to prevent duplicate announcements.
+- The default `ariaLabel` is an empty string, which keeps the icon decorative.
+  Pass a task-specific name when the icon is meaningful.
+- Icons used inside controls do not replace the control's visible or accessible
+  label.
+
+## Native renderer mapping
+
+NativeScript renderers map trusted vector/image sources to supported native image
+views. Decorative icons disable native accessibility exposure; meaningful icons
+map `ariaLabel` intent to `accessibilityLabel` and image-role state. Do not copy
+ARIA attributes into native markup.
+
+## Known limitations
+
+- Inline SVG markup must come from trusted sources.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Image pattern: https://www.w3.org/WAI/ARIA/apg/patterns/
+- GOV.UK images guidance: https://design-system.service.gov.uk/styles/images/