@pastweb/components-core 2.0.0 → 2.2.0

package/dist/TextArea/README.md

@@ -0,0 +1,141 @@
+# TextArea
+
+TextArea is a labelled multiline text control with explicit disabled, read-only,
+required, resizable, and loading states. Its rendering contract targets WCAG
+2.2 Level AA.
+
+## When to use
+
+Use TextArea for multi-line values. Use Input for a single line. Prefer a
+visible label; placeholders do not replace labels. If there is a good reason to
+limit length, associate a character-count message through `id` rather than
+relying on `maxLength` alone.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component, part, and state classes. |
+| `ariaLabel` | `string` | no | `"TextArea"` | Names the field when no visible `label` is supplied. Pass an empty string to omit it. |
+| `className` | `string` | no | `""` | Additional root classes. The `is-loading` class is also treated as a loading signal. |
+| `cols` | `number` | no | - | Native column count. |
+| `disabled` | `boolean` | no | - | Makes the field unavailable. |
+| `id` | `string` | no | generated | Native textarea ID. Generated IDs use the `textArea` prefix. |
+| `label` | `string` | no | `""` | Visible accessible label. |
+| `labelPlacement` | `Placement` | no | `'top-start'` | Visual label placement. |
+| `loading` | `boolean` | no | - | Marks the field busy and temporarily unavailable. |
+| `maxLength` | `number` | no | - | Native maximum character length. |
+| `name` | `string` | no | - | Native form name. |
+| `onChange` | `(value: string) => void` | no | noop | Reports edited text. |
+| `placeholder` | `string` | no | `""` | Short input hint. Do not use it as the only label. |
+| `readOnly` | `boolean` | no | - | Prevents editing and applies `is-readonly`. |
+| `required` | `boolean` | no | - | Marks the value as required. |
+| `resizeable` | `boolean` | no | - | Enables two-axis web resizing and `is-resizeable`. |
+| `rows` | `number` | no | - | Native row count. |
+| `tabIndex` | `number` | no | `0` | Sequential focus order. Prefer document order. |
+| `value` | `string` | no | `""` | Controlled value. |
+
+The named `loading` slot defaults to “Loading...”.
+
+## Utility classes
+
+Apply these classes through `className`.
+
+| Class | Description |
+|---|---|
+| `is-rounded` | Uses the rounded control radius token. |
+| `is-full-width` | Expands the field to the available width. |
+| `is-loading` | Compatibility signal for the loading state. Prefer the `loading` prop. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name when no visible `label` is present. Empty labels are omitted. |
+| `inputId` | `string` | Native textarea ID from an explicit `id` or a generated `textArea` prefix. |
+| `isDisabled` | `true \| undefined` | Is `true` when disabled; otherwise omitted. |
+| `isLoading` | `true \| undefined` | Is `true` when busy; otherwise omitted. |
+| `isReadOnly` | `true \| undefined` | Is `true` when read-only; otherwise omitted. |
+| `isResizeable` | `true \| undefined` | Is `true` when resizing is enabled; otherwise omitted. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_TextArea_root_default_margin` | `root` | `default` | `margin` | shared margins | Component spacing. | Web, Capacitor, NativeScript |
+| `--pw_TextArea_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled appearance. | Web, Capacitor, NativeScript |
+| `--pw_TextArea_control_default_min-height` | `control` | `default` | `min-height` | `2.75em` | Minimum control height, with a 44px web target. | Web, Capacitor, NativeScript |
+| `--pw_TextArea_root_default_background-color` | `control` | `default` | `background-color` | `var(--pw_control_background-color)` | Control background. | Web, Capacitor, NativeScript |
+| `--pw_TextArea_root_default_color` | `control` | `default` | `color` | `var(--pw_text_color)` | Control foreground. | Web, Capacitor, NativeScript |
+| `--pw_TextArea_root_default_border-color` | `control` | `default` | `border-color` | `var(--pw_border-color)` | Border colour. | Web, Capacitor, NativeScript |
+| `--pw_TextArea_root_default_border-radius` | `control` | `default` | `border-radius` | `var(--pw_border-radius)` | Corner radius. | Web, Capacitor, NativeScript |
+| `--pw_TextArea_label_default_color` | `label` | `default` | `color` | `var(--pw_label_text_color)` | Label colour. | Web, Capacitor, NativeScript |
+| `--pw_TextArea_loading_default_background-color` | `loading` | `default` | `background-color` | control background | Loading overlay. | Web, Capacitor, NativeScript |
+
+```xts
+import { useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { textAreaMediator } from '@pastweb/components-core/TextArea';
+import { DEFAULT_PROPS } from './constants';
+
+export function TextArea(props: TextAreaProps) {
+  const p = withDefaultProps<TextAreaDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<TextAreaMediator>(textAreaMediator, p);
+  const s = m.state;
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div class={p.cls('TextArea', `label-${p.labelPlacement}`, {
+      'is-disabled': s.isDisabled, 'is-loading': s.isLoading, 'is-readonly': s.isReadOnly, 'is-resizeable': s.isResizeable,
+    }, p.className)} aria-busy={s.isLoading}>
+      <div class={p.cls('textarea')}>
+        <textarea id={s.inputId} class={p.cls('input')} disabled={s.isDisabled || s.isLoading} readonly={s.isReadOnly}
+          required={p.required} value={p.value} aria-label={s.ariaLabel} aria-busy={s.isLoading} aria-disabled={s.isDisabled}
+          @change={event => m.onChange(event.target.value)} />
+        <div #if={s.isLoading} class={p.cls('loading')} role="status" aria-live="polite">
+          <slot name="loading">Loading...</slot>
+        </div>
+      </div>
+      <label #if={p.label} class={p.cls('label', p.labelPlacement)} for={s.inputId}>{p.label}</label>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Printable keys, `Backspace`, and `Delete` edit the value through native
+  textarea behavior.
+- `Tab` and `Shift+Tab` move sequential focus.
+
+## Accessibility notes
+
+- The native textarea supplies keyboard, form, and validation behavior.
+- Visible `label` text is connected through `for`/`id`. When it is absent,
+  `ariaLabel` names the field. The default name is `TextArea`.
+- Disabled fields use `.is-disabled`, native `disabled`, and `aria-disabled`.
+- Loading disables the field, applies `aria-busy`, and displays a polite status
+  region.
+- Shared web styles provide at least a 44 by 44 CSS-pixel target, visible
+  `:focus-visible` indication, forced-colours treatment, and reduced-motion
+  behavior.
+
+## Native renderer mapping
+
+Native renderers use a multiline editable text view. Do not copy ARIA attributes
+into native markup.
+
+## Known limitations
+
+- Placeholders do not replace a visible or accessible name.
+- Hint, error, and character-count text are not built in. Associate them with
+  the native textarea through `id` when the surrounding form provides that
+  content.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Textbox pattern: https://www.w3.org/WAI/ARIA/apg/patterns/
+- GOV.UK textarea: https://design-system.service.gov.uk/components/textarea/

package/dist/ToastController/README.md

@@ -0,0 +1,119 @@
+# ToastController
+
+ToastController presents a temporary, politely announced status message. Its
+rendering contract targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use ToastController for non-urgent confirmation or status that can disappear.
+Use Notification for a persistent in-page message, an alert pattern for urgent
+information, and a dialog when the user must decide before continuing.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `ariaLabel` | `string` | no | `""` | Names the status region. Pass an empty string to omit it. |
+| `portal` | `Portal` | no | - | Portal configuration. |
+| `portalElement` | `HTMLElement` | no | - | Portal container. |
+| `entryId` | `string` | no | - | Portal entry ID. |
+| `placement` | `PLACEMENT` | no | `top-right` | Viewport placement. |
+| `padding` | `number` | no | `15` | Inner padding in pixels. |
+| `delay` | `number` | no | `5` | Auto-dismiss delay in seconds. |
+| `timeUpdate` | `number` | no | `10` | Timer tick interval. |
+| `animation` | `Animation` | no | `slide` | Entry and exit animation. |
+| `closeOnEscKey` | `boolean` | no | - | Dismisses on `Escape`. |
+| `pauseTimerOnOver` | `boolean` | no | - | Pauses the timer on pointer or keyboard focus. |
+| `resetTimerOnPause` | `boolean` | no | - | Resets the timer when pausing. |
+| `onClose` | `() => void` | no | noop | Reports close intent. |
+| `onDestroy` | `() => void` | no | noop | Reports portal removal. |
+| `onKeyDown` | `(event) => void` | no | noop | Observes keyboard input. |
+
+## XTS rendering contract
+
+```xts
+import { setContext, useMediator, useRef, withDefaultProps } from '@pastweb/x';
+import {
+  JUSTIFY,
+  TOAST_CONTEXT_KEY,
+  toastControllerMediator,
+} from '@pastweb/components-core/ToastController';
+import { DEFAULT_PROPS } from './constants';
+
+export function ToastController(props: ToastControllerProps) {
+  const p = withDefaultProps<ToastControllerDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<ToastControllerMediator>(toastControllerMediator, p);
+  const s = m.state;
+  const c = m.getContext();
+  const toastReference = useRef(null);
+
+  setContext(TOAST_CONTEXT_KEY, c);
+
+  return (
+    <div
+      #ref={(element) => {
+        toastReference.value = element;
+        if (element) m.onMounted(element);
+      }}
+      class={p.cls('ToastController', p.placement)}
+      style={{ [s.y]: s.top || s.bottom, justifyContent: JUSTIFY[s.x] }}
+    >
+      <div
+        class={p.cls('toast', {
+          [`${p.animation.name}-in-${s.x}-${s.y}`]: s.isOpen,
+          [`${p.animation.name}-out-${s.x}-${s.y}`]: !s.isOpen,
+        })}
+        role='status'
+        aria-live='polite'
+        aria-atomic='true'
+        aria-label={p.ariaLabel || undefined}
+        @keydown={m.onKeyDown}
+        @mouseenter={m.onMouseOver}
+        @mouseleave={m.onMouseLeave}
+        @focus={m.onMouseOver}
+        @blur={m.onMouseLeave}
+      >
+        <slot />
+      </div>
+    </div>
+  );
+}
+```
+
+ToastController is a browser-only portal controller. Create it only while its
+portal element is available; it is not part of initial server rendering.
+
+## Keyboard interaction
+
+- `Escape` dismisses the toast when `closeOnEscKey` is enabled.
+- The toast does not enter sequential tab order. Interactive content inside it
+  remains operable.
+
+## Accessibility notes
+
+- The toast is a polite `status` live region. It does not move focus on open.
+- The auto-dismiss timer pauses while the pointer is over the toast, while it
+  has keyboard focus, and while it is not fully visible.
+- Time limits can be paused (`pauseTimerOnOver`) and dismissed early (`Escape`
+  or a consumer close control).
+- Shared web styles keep a visible `:focus-visible` indicator and disable
+  non-essential motion under `prefers-reduced-motion`.
+
+## Known limitations
+
+- A visible close control is not built in. Supply one in the toast content when
+  users must dismiss without waiting.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Native renderer mapping
+
+Native renderers map the toast to a native polite announcement and timed overlay.
+Do not copy ARIA attributes into native markup.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Status and alert patterns: https://www.w3.org/WAI/ARIA/apg/patterns/
+- GOV.UK notification banner: https://design-system.service.gov.uk/components/notification-banner/

package/dist/Toggle/README.md

@@ -0,0 +1,109 @@
+# Toggle
+
+Toggle represents an immediate binary setting. The web renderer uses a native
+checkbox with `role="switch"`. Its rendering contract follows the WAI-ARIA
+Switch pattern and targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use Toggle for an immediate on/off setting. Use Checkbox for a form choice that
+is submitted later. Prefer a pair of radios when both options need visible
+labels, such as “On” and “Off”.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `ariaLabel` | `string` | no | `"Toggle"` | Names the switch when no visible `label` is supplied. Pass an empty string to omit it. |
+| `className` | `string` | no | `""` | Additional root classes. |
+| `disabled` | `boolean` | no | - | Disables the control and applies `is-disabled`. |
+| `id` | `string \| number` | no | generated | Native control ID. Generated IDs use the `toggle` prefix. |
+| `label` | `string` | no | `""` | Visible accessible label. |
+| `labelPlacement` | `Placement` | no | `'top-start'` | Visual label position. |
+| `name` | `string` | no | - | Native form name. |
+| `onChange` | `(checked, event) => void` | no | noop | Reports state changes. |
+| `tabIndex` | `number` | no | `0` | Sequential focus order. |
+| `value` | `boolean` | no | - | Controlled checked state. |
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `ariaLabel` | `string \| undefined` | Normalized accessible name when no visible `label` is present. |
+| `inputId` | `string` | Native input ID from an explicit `id` or a generated `toggle` prefix. |
+| `isDisabled` | `true \| undefined` | Is `true` when the Toggle is disabled; otherwise omitted. |
+| `value` | `boolean` | Checked state used for `.is-checked`, native `checked`, and `aria-checked`. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Toggle_root_default_margin` | `root` | `default` | `margin` | shared margins | Component spacing. | Web, Capacitor, NativeScript |
+| `--pw_Toggle_root_disabled_opacity` | `root` | `disabled` | `opacity` | `var(--pw_disabled_opacity)` | Disabled appearance. | Web, Capacitor, NativeScript |
+| `--pw_Toggle_background_default_width` | `track` | `default` | `width` | `4em` | Track width. | Web, Capacitor, NativeScript |
+| `--pw_Toggle_background_default_height` | `track` | `default` | `height` | `2.75em` | Track height, with a 44px web target. | Web, Capacitor, NativeScript |
+| `--pw_Toggle_root_default_background-color` | `track` | `default` | `background-color` | `var(--pw_control_background-color)` | Unchecked track. | Web, Capacitor, NativeScript |
+| `--pw_Toggle_label_default_color` | `label` | `default` | `color` | `var(--pw_label_text_color)` | Label colour. | Web, Capacitor, NativeScript |
+
+```xts
+import { useBeforeUnmount, useMediator, withDefaultProps } from '@pastweb/x';
+import { toggleMediator } from '@pastweb/components-core/Toggle';
+import { DEFAULT_PROPS } from './constants';
+
+export function Toggle(props: ToggleProps) {
+  const p = withDefaultProps<ToggleDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<ToggleMediator>(toggleMediator, p);
+  const s = m.state;
+
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <div class={p.cls('Toggle', `label-${p.labelPlacement}`, { 'is-checked': s.value, 'is-disabled': s.isDisabled }, p.className)}>
+      <label class={p.cls('control')}>
+        <span class={p.cls('button')}>
+          <input type="checkbox" role="switch" id={s.inputId} checked={s.value} disabled={s.isDisabled}
+            aria-checked={s.value} aria-disabled={s.isDisabled} aria-label={s.ariaLabel}
+            @change={event => m.onChange(event.target.checked, event)} />
+        </span>
+        <span #if={p.label} class={p.cls('label', p.labelPlacement)}>{p.label}</span>
+      </label>
+    </div>
+  );
+}
+```
+
+## Keyboard interaction
+
+- `Space` toggles the native switch.
+- `Tab` and `Shift+Tab` move sequential focus.
+
+## Accessibility notes
+
+- The web renderer uses a native checkbox with `role="switch"` and
+  `aria-checked`.
+- One wrapping label supplies the visible accessible name. When visible label
+  text is absent, the mediator exposes `ariaLabel`.
+- Disabled switches use native `disabled`, `aria-disabled="true"`, and
+  `is-disabled`.
+- Shared web styles provide at least a 44 by 44 CSS-pixel target, visible
+  `:focus-visible` indication, forced-colours treatment, and reduced-motion
+  behavior.
+
+## Native renderer mapping
+
+Native renderers map Toggle to the platform switch control. Do not copy ARIA
+attributes into native markup.
+
+## Known limitations
+
+- GOV.UK prefers radios or checkboxes when both options need equal visible
+  labels. Use Toggle only for an immediate setting.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Switch pattern: https://www.w3.org/WAI/ARIA/apg/patterns/switch/
+- GOV.UK radios: https://design-system.service.gov.uk/components/radios/

package/dist/Tooltip/README.md

@@ -0,0 +1,128 @@
+# Tooltip
+
+Tooltip provides a short, non-interactive description for a focused or hovered
+control. Its rendering contract follows the WAI-ARIA Tooltip pattern and
+targets WCAG 2.2 Level AA.
+
+## When to use
+
+Use Tooltip to supplement a control’s visible name with extra description. Do
+not put essential instructions, errors, or interactive content in a tooltip.
+Prefer visible hint text, especially in forms. Hover-only UI is unreliable on
+touch devices.
+
+## Props
+
+| PropName | Type | Required | Default | Description |
+|---|---|---:|---:|---|
+| `cls` | `(...args: ClassValue[]) => string` | yes | - | Resolves component and state classes. |
+| `content` | `string` | no | `""` | Tooltip description. Empty content never opens. |
+| `id` | `string` | no | generated | Stable ID used by the trigger description relationship. Generated IDs use the `tooltip` prefix. |
+| `placement` | `TooltipPlacement` | no | `'top'` | Preferred side and optional start/end alignment. |
+| `offset` | `number` | no | `8` | Renderer positioning gap. |
+| `showDelay` | `number` | no | `300` | Pointer-hover opening delay in milliseconds. Focus opens immediately. |
+| `hideDelay` | `number` | no | `100` | Pointer-leave closing delay in milliseconds. Blur and Escape close immediately. |
+| `disabled` | `boolean` | no | - | Prevents opening and applies `is-disabled`. |
+| `className` | `string` | no | `""` | Additional root classes. |
+| `tooltipClassName` | `string` | no | `""` | Additional tooltip-surface classes. |
+
+`TooltipPlacement` supports `top`, `right`, `bottom`, and `left`, each
+optionally followed by `-start` or `-end`. `Placement` remains a deprecated
+alias.
+
+## Mediator state
+
+| Property | Type | Description |
+|---|---|---|
+| `isDisabled` | `true \| undefined` | Is `true` when the Tooltip is disabled; otherwise omitted. |
+| `isVisible` | `boolean` | Whether the tooltip is requested open. |
+| `tooltipId` | `string` | Tooltip relationship ID from an explicit `id` or a generated `tooltip` prefix. |
+
+## CSS Variables
+
+| Variable | Part | State | CSS property | Default | Description | Platforms |
+|---|---|---|---|---|---|---|
+| `--pw_Tooltip_content_default_background-color` | `content` | `default` | `background-color` | `var(--pw_background-color)` | Tooltip background. | Web, Capacitor |
+| `--pw_Tooltip_content_default_color` | `content` | `default` | `color` | `var(--pw_text_color)` | Tooltip foreground. | Web, Capacitor |
+| `--pw_Tooltip_content_default_border-color` | `content` | `default` | `border-color` | `var(--pw_border-color)` | Border colour. | Web, Capacitor |
+| `--pw_Tooltip_content_default_max-width` | `content` | `default` | `max-width` | `20rem` | Maximum tooltip width. | Web, Capacitor |
+| `--pw_Tooltip_content_default_font-size` | `content` | `default` | `font-size` | shared font size | Tooltip type size. | Web, Capacitor |
+| `--pw_Tooltip_content_default_line-height` | `content` | `default` | `line-height` | `1.5em` | Tooltip line box. With vertical padding this matches the arrow box. | Web, Capacitor |
+| `--pw_Tooltip_content_default_padding` | `content` | `default` | `padding` | `0.25em` plus shared horizontal padding | Inner spacing, in `em` so it tracks font size. | Web, Capacitor |
+| `--pw_Tooltip_content_default_drop-shadow` | `content` | `default` | `filter` | `0 0 0.2em` shared shadow colour | Shadow that follows the tooltip and arrow. | Web, Capacitor |
+| `--pw_Tooltip_arrow_default_size` | `arrow` | `default` | `size` | `1em` | Decorative arrow size, in `em` so it tracks the tooltip font. | Web, Capacitor |
+
+```xts
+import { useBeforeUnmount, useMediator, useMounted, useRef, withDefaultProps } from '@pastweb/x';
+import { tooltipMediator } from '@pastweb/components-core/Tooltip';
+import { DEFAULT_PROPS } from './constants';
+
+export function Tooltip(props: TooltipProps) {
+  const p = withDefaultProps<TooltipDefaultProps>(props, DEFAULT_PROPS);
+  const m = useMediator<TooltipMediator>(tooltipMediator, p);
+  const s = m.state;
+  const trigger = useRef(null);
+  const tooltip = useRef(null);
+  const arrow = useRef(null);
+
+  useMounted(() => m.useMounted(trigger.value, tooltip.value, arrow.value));
+  useBeforeUnmount(m.useBeforeUnmount);
+
+  return (
+    <span class={p.cls('Tooltip', { 'is-disabled': s.isDisabled }, p.className)}
+      @pointerenter={event => event.pointerType !== 'touch' && m.show()}
+      @pointerleave={() => m.hide()} @focusin={() => m.show(true)}
+      @focusout={() => m.hide(true)} @keydown={m.onKeyDown}>
+      <span #ref={trigger} class={p.cls('trigger')} aria-describedby={s.isDisabled ? undefined : s.tooltipId}>
+        <slot />
+      </span>
+      <div #ref={tooltip} id={s.tooltipId} role="tooltip"
+        class={p.cls('tooltipContent', { 'is-visible': s.isVisible }, p.tooltipClassName)}>
+        <Render content={p.content} />
+        <div #ref={arrow} class={p.cls('arrow')} aria-hidden="true" />
+      </div>
+    </span>
+  );
+}
+```
+
+## Keyboard interaction
+
+- Focus on the trigger opens the tooltip immediately.
+- Blur closes the tooltip immediately.
+- `Escape` dismisses an open tooltip without moving focus.
+- The tooltip itself does not enter the tab order.
+
+## Accessibility notes
+
+- The popup uses `role="tooltip"`. The trigger references it with
+  `aria-describedby`.
+- A single element trigger receives `aria-describedby` on that element. Plain
+  text triggers are wrapped in a focusable span.
+- Pointer hover opens after `showDelay`. Pointer leave closes after
+  `hideDelay` so the pointer can move onto the tooltip (WCAG 1.4.13).
+- Touch pointer entry is ignored because hover-only UI is unreliable on touch
+  devices.
+- Empty `content` never opens.
+- The decorative arrow is hidden from assistive technology.
+- Shared web styles wrap long text, keep a visible trigger focus indicator,
+  support forced colours, and disable non-essential motion under
+  `prefers-reduced-motion`.
+
+## Native renderer mapping
+
+NativeScript renderers map show/hide intent to a native accessible hint or
+non-interactive popup. Do not copy ARIA attributes into native markup.
+
+## Known limitations
+
+- Tooltip content must not be interactive. Use a dialog or disclosure for
+  actions or forms.
+- Automated accessibility checks do not by themselves establish WCAG
+  conformance.
+
+## Standards
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA Tooltip pattern: https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/
+- GOV.UK components: https://design-system.service.gov.uk/components/