@chiralkit/design-system 0.1.0-alpha.0

package/dist/types/components/ds-dialog/ds-dialog.d.ts

@@ -0,0 +1,148 @@
+import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * ## Accessibility
+ *
+ * **Category:** state-machine
+ * **APG pattern:** https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+ *
+ * This component wraps the **native `<dialog>` element** rather than
+ * scratch-building the APG pattern on top of a `<div role="dialog">`.
+ * `<dialog>` opened via `showModal()` gives us — from the browser,
+ * verified by the platform, not by us:
+ *
+ * - Focus trap: Tab / Shift+Tab cycle only through focusable
+ *   descendants (including slotted light-DOM descendants; the flattened
+ *   accessibility tree is what the trap operates on).
+ * - Escape: closes the dialog and returns focus to the previously
+ *   focused element (native, not implemented here).
+ * - Inert background: everything outside the dialog is inert while it
+ *   is open — no mouse, no keyboard, not part of the a11y tree.
+ * - Return focus: on close, focus returns to whatever element had it
+ *   before `showModal()` — native, not implemented here.
+ * - Initial focus: browser auto-focuses the first `autofocus` element
+ *   inside, or the first focusable if none — native.
+ * - `role="dialog"` and `aria-modal="true"` semantics: implicit on
+ *   `<dialog>`, no ARIA needed from us.
+ *
+ * This is the deliberate answer to the a11y spec §D warning about
+ * scratch-building Tier 2 components: the native element removes the
+ * "compiles, axe passes, screen-reader user gets trapped" failure
+ * mode by delegating the state machine to the platform.
+ *
+ * **Keyboard interactions (all handled by the native element unless
+ * noted otherwise):**
+ * - Tab: cycles focus within the dialog's focusable descendants
+ *   (native focus trap).
+ * - Shift+Tab: reverse cycle (native).
+ * - Escape: closes the dialog and fires the `close` event (native).
+ *   Consumers who need to prevent dismissal on Escape (destructive
+ *   flows: e.g. an unsaved-changes guard) must call
+ *   `event.preventDefault()` inside their own `keydown` listener on
+ *   the dialog before it reaches the browser — that is an escape
+ *   hatch, not a default we impose.
+ * - Enter / Space: no special dialog behavior; forwarded to
+ *   whatever descendant has focus (a button will activate).
+ * - Home / End / Arrow keys: no special dialog behavior; forwarded
+ *   to descendants.
+ * - Printable characters: forwarded to descendants (e.g. typing
+ *   inside a slotted `<ds-input>`).
+ *
+ * **ARIA attributes and value triggers:**
+ * - Implicit `role="dialog"` on the native `<dialog>`.
+ * - Implicit `aria-modal="true"` when opened via `showModal()`
+ *   (which is what this component always uses; `show()` — the
+ *   non-modal form — is intentionally not exposed in v1).
+ * - `aria-label` set from the `label` prop onto the `<dialog>`.
+ *   Consumers who prefer an in-content title can pass a
+ *   `labelledBy` prop instead, whose value is the id of a heading
+ *   element they render inside the slot — `aria-labelledby`
+ *   resolves that id through the flattened tree.
+ * - `aria-describedby` from the `describedBy` prop, resolving a
+ *   light-DOM id of a descriptive block (e.g. the dialog body copy
+ *   when the label is short).
+ *
+ * **Focus lifecycle:**
+ * - Opening: `showModal()` moves focus to the first `autofocus`
+ *   element inside, or the first focusable if none. Consumers who
+ *   want a specific initial focus target should mark that element
+ *   with `autofocus`.
+ * - While open: focus is trapped within the flattened tree of the
+ *   `<dialog>`; Tab / Shift+Tab cycle through slotted descendants.
+ *   Focus cannot escape into the inert background.
+ * - Closing: `close()` (either from Escape, from a form-submit with
+ *   `method="dialog"`, from a light-dismiss backdrop click handler
+ *   the consumer wires up, or from `open=false`) returns focus to
+ *   the element that had it immediately before `showModal()` was
+ *   called. The `dsClose` event fires after focus has been restored.
+ *
+ * **ARIA labelling contract (choose one):**
+ * - **`label`** (string) — sets `aria-label` on the dialog. Simplest
+ *   for short titles.
+ * - **`labelledBy`** (id) — sets `aria-labelledby` to reference a
+ *   heading rendered inside the slot. Preferred when the dialog has
+ *   a visible title so the accessible name matches the visible name.
+ *
+ * If both are omitted, axe reports `dialog-name` — the dialog has no
+ * accessible name. The a11y test for this component asserts that at
+ * least one of the two is provided.
+ *
+ * **Motion:**
+ * - Animations: none applied by the component. Consumers who want an
+ *   entrance transition can style `::backdrop` and `dialog[open]`
+ *   with their own animation, gated on `@media
+ *   (prefers-reduced-motion: no-preference)`.
+ * - Reduced-motion behavior: N/A — no animation to collapse. If a
+ *   consumer adds one, they own the reduced-motion fallback.
+ *
+ * **Contrast:**
+ * - Text: inherits `color: inherit`; consumer theme owns contrast.
+ * - Non-text: subtle bordered surface via
+ *   `color-mix(in oklch, currentColor N%, transparent)` matching
+ *   `ds-card`. Backdrop is a semi-transparent black by default.
+ *
+ * **Screen reader announcement:**
+ * - Rendered state (closed): dialog is not in the a11y tree.
+ * - Opened: AT announces "dialog" plus the accessible name from
+ *   `label` / `labelledBy`, then reads the content following focus
+ *   (or the descriptive block referenced by `describedBy` first,
+ *   depending on AT).
+ * - State change: on close, AT returns to the element that regained
+ *   focus (the trigger); no `aria-live` announcement is added.
+ *
+ * **Consumer contract:**
+ * - Set `open` to true to show; set to false to close. The component
+ *   syncs the DOM state via `showModal()` / `close()` in a Watch.
+ * - Listen to `dsClose` to know when the dialog was dismissed (by
+ *   Escape, by `open=false`, or by a form submit with
+ *   `method="dialog"`). Listen to `dsOpen` for the mirror event.
+ * - The default backdrop is opaque and NOT click-to-dismiss. Consumers
+ *   who want light-dismiss can add a click listener on the dialog
+ *   that closes when the click target is the dialog itself (not a
+ *   descendant): `if (e.target === dialog) dialog.close()`.
+ * - Put focus targets (form fields, primary action button) inside
+ *   the slot. Use `autofocus` on the element that should receive
+ *   focus first.
+ *
+ * **Pending manual verification (see commit message TODO):**
+ * - VoiceOver on macOS: confirm the dialog announces its accessible
+ *   name + "dialog" on open, focus lands on the correct element,
+ *   Escape closes and focus returns to the trigger.
+ * - Chromium high-contrast / forced-colors: confirm the surface
+ *   still reads as a bordered container with the native ::backdrop
+ *   dim.
+ */
+export declare class DsDialog {
+    private dialogEl?;
+    open: boolean;
+    label?: string;
+    labelledBy?: string;
+    describedBy?: string;
+    dsOpen: EventEmitter<void>;
+    dsClose: EventEmitter<void>;
+    watchOpen(newValue: boolean): void;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
+    private syncOpen;
+    private onNativeClose;
+    render(): any;
+}

package/dist/types/components/ds-input/ds-input.d.ts

@@ -0,0 +1,104 @@
+import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * ## Accessibility
+ *
+ * **Category:** form-field
+ * **APG pattern:** N/A — native element. This wraps a native `<input>`;
+ * there is no WAI-ARIA APG pattern for a plain text input because the
+ * browser already implements it natively. Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input
+ *
+ * **Keyboard interactions:**
+ * - Tab: moves focus to the native `<input>` (shadow DOM does not
+ *   interrupt tab order).
+ * - Printable characters: insert at the caret position (native).
+ * - Backspace / Delete: native editing.
+ * - Arrow keys: move the caret within the value (native); for
+ *   `type="number"` Up/Down step the numeric value (native).
+ * - Enter: on `type="search"` may submit the enclosing form (native);
+ *   no custom handling.
+ * - Escape: no native meaning for a text input.
+ *
+ * **ARIA:**
+ * - Roles used: none explicit — the native `<input>` supplies its
+ *   implicit role (`textbox`, `searchbox`, etc. depending on `type`).
+ * - State attributes: `disabled` (native attribute, not `aria-disabled`),
+ *   `aria-invalid` (from the `invalid` prop), `aria-required` (from the
+ *   `required` prop), `aria-describedby` (from the `describedBy` prop,
+ *   expected to reference a light-DOM node id — typically a hint or
+ *   error message rendered by the consumer alongside the field).
+ * - Labeling strategy: `aria-label` set from the `label` prop onto the
+ *   internal `<input>`. This is the **canonical, recommended** mode —
+ *   explicit and independent of DOM structure. Consumers MUST pass
+ *   `label` (or otherwise give the field an accessible name) — an
+ *   `<input>` with no accessible name is a WCAG failure (axe rule
+ *   `label`). Wrapping the host in a light-DOM `<label>` (e.g.
+ *   `<label>Email <ds-input></ds-input></label>`) also produces an
+ *   accessible name in Chromium via flattened-tree resolution — the
+ *   same secondary mode documented on `ds-select`, verified in this
+ *   component's e2e tests. Setting `aria-label` directly on the
+ *   `<ds-input>` host does NOT work: shadow-DOM attribute forwarding
+ *   would be required — use the `label` prop instead.
+ *
+ * **Focus:**
+ * - On mount: nothing auto-focuses.
+ * - On value change: focus remains on the native `<input>`.
+ * - Focus indicator: the browser default `:focus-visible` ring is kept
+ *   on purpose — a themed focus ring using `--ds-color-focus` is a
+ *   future decision once the DS ships a shared focus utility. Not
+ *   overridden by `ds-input.css`.
+ *
+ * **Motion:**
+ * - Animations: none.
+ * - Reduced-motion behavior: N/A — no animation to collapse.
+ *
+ * **Contrast:**
+ * - Text: inherits `color: inherit` / `currentColor`; ratio depends on
+ *   the consumer's theme, not verified in isolation here.
+ * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+ *   matching `ds-select` — inherits whatever contrast the host page
+ *   sets. WCAG 1.4.11 (3:1 non-text) is the consumer's responsibility
+ *   in themes that override the surface.
+ *
+ * **Screen reader announcement:**
+ * - Rendered state: announces the `label` prop text as the accessible
+ *   name, followed by the browser/AT's role announcement for the
+ *   input type ("edit text", "search text", "password", "phone
+ *   number", "email"…). When `required=true` the announcement
+ *   includes "required"; when `invalid=true` it includes "invalid".
+ * - State change: on value edit, AT typically echoes the typed
+ *   character (native input behavior); no `aria-live` added, per the
+ *   spec's guidance against live-region overuse.
+ *
+ * **Consumer contract:**
+ * - `placeholder` is a hint, not a label. It disappears on focus in
+ *   most browsers and is not reliably announced by every AT — always
+ *   pair with `label`.
+ * - For `type="password"` in a real form, pair with a light-DOM
+ *   `<input type="hidden">` or a form-associated ancestor that gives
+ *   the browser's password manager an `autocomplete` hint. This
+ *   component intentionally does not expose `autocomplete` in v1;
+ *   consumers that need it can render a native `<input>` for that
+ *   field until the prop is added.
+ * - When `invalid=true`, pair with a `describedBy` id that points at
+ *   a visible error message; `aria-invalid` alone gives the AT the
+ *   status but not the reason.
+ */
+export declare class DsInput {
+    private inputEl?;
+    value?: string;
+    name?: string;
+    type: "text" | "email" | "password" | "search" | "tel" | "url" | "number";
+    placeholder?: string;
+    disabled: boolean;
+    required: boolean;
+    invalid: boolean;
+    describedBy?: string;
+    label?: string;
+    size: "md" | "lg";
+    dsInput: EventEmitter<string>;
+    watchValue(newValue?: string): void;
+    componentDidLoad(): void;
+    private onInput;
+    render(): any;
+}

package/dist/types/components/ds-loader/ds-loader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ## Accessibility
+ *
+ * **Category:** static-display (indeterminate progress indicator)
+ * **APG pattern:** N/A — the loader is a passive presence indicator, not a
+ * `progressbar` (no measurable value). Uses `role="status"` per WAI-ARIA
+ * live-region semantics for indeterminate loading states.
+ *
+ * **Keyboard interactions:**
+ * - Tab: N/A — not focusable.
+ * - Enter: N/A.
+ * - Escape: N/A.
+ * - Arrow keys: N/A.
+ * - Printable characters: N/A.
+ *
+ * **ARIA:**
+ * - Roles used: `role="status"` on the host — an implicit polite live
+ *   region ARIA lists as valid for "advisory information" including
+ *   in-progress operations. The inner `<svg>` is decorative and carries
+ *   `aria-hidden="true"` + `focusable="false"` so it never becomes a
+ *   parallel target for screen readers.
+ * - State attributes: none. The loader has no state changes to announce
+ *   beyond its own presence; the polite live region on mount is the
+ *   announcement.
+ * - Labeling strategy: `aria-label` from the `label` prop (default
+ *   "Loading"). Consumers pass a more specific string when the context
+ *   warrants ("Loading ceremonies", "Signing in", …).
+ *
+ * **Focus:**
+ * - On mount: nothing auto-focuses.
+ * - On activate/open: N/A — not interactive.
+ * - On close/deactivate: N/A.
+ * - Focus indicator: N/A — the host is not focusable.
+ *
+ * **Motion:**
+ * - Animations: two mirrored halves of the logo path oscillate
+ *   symmetrically around the visual center, meeting at the ring midpoint
+ *   and separating again. Cycle 1.4s by default (`speed="normal"`);
+ *   `speed="slow"` = 2.2s, `speed="fast"` = 0.9s.
+ * - Reduced-motion behavior: `@media (prefers-reduced-motion: reduce)`
+ *   collapses both halves to a static rendering with a slow opacity
+ *   pulse (2s ease-in-out). No rotation, no lateral movement.
+ *
+ * **Contrast:**
+ * - Text: N/A — the visible surface is the SVG stroke, not text.
+ * - Non-text: stroke inherits `currentColor` from the host. Consumers are
+ *   responsible for confirming the stroke against its background meets
+ *   the ≥ 3:1 non-text contrast threshold (WCAG 1.4.11) where the loader
+ *   conveys state (e.g. distinguishing "still loading" from "idle").
+ *
+ * **Screen reader announcement:**
+ * - Rendered state: the polite live region announces the label
+ *   (e.g. "Loading") when the loader mounts.
+ * - State change: N/A — the loader itself has no state that changes.
+ *   Consumers unmount the loader when the awaited work completes; that
+ *   removal is silent, which is the intended behavior (the arriving
+ *   content is the announcement).
+ */
+export declare class DsLoader {
+    size: "sm" | "md" | "lg";
+    label: string;
+    speed: "slow" | "normal" | "fast";
+    render(): any;
+}

package/dist/types/components/ds-select/ds-select.d.ts

@@ -0,0 +1,123 @@
+import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * ## Accessibility
+ *
+ * **Category:** form-field
+ * **APG pattern:** N/A — native element. This wraps a native `<select>`;
+ * there is no WAI-ARIA APG pattern for it because the browser already
+ * implements the full listbox/combobox behavior natively. Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select
+ *
+ * **Keyboard interactions:**
+ * - Tab: moves focus to the native `<select>` (shadow DOM does not
+ *   interrupt tab order).
+ * - Enter: opens the native options popup on most platforms (browser/OS
+ *   dependent, identical to any bare `<select>`).
+ * - Escape: closes the native options popup without changing the value
+ *   (native behavior, not implemented by us).
+ * - Arrow keys: Up/Down move the selected option when closed; Up/Down/Home/End
+ *   navigate options when the native popup is open (native behavior).
+ * - Printable characters: native typeahead jumps to the option starting
+ *   with the typed character(s) (native behavior).
+ *
+ * **ARIA:**
+ * - Roles used: none explicit — the native `<select>` element supplies the
+ *   implicit `listbox`/`combobox`-equivalent role itself.
+ * - State attributes: `disabled` (native attribute, not `aria-disabled`).
+ * - Labeling strategy: `aria-label`, set from the `label` prop onto the
+ *   internal `<select>`. This is the **canonical, recommended** mode —
+ *   explicit and independent of DOM structure. Consumers MUST pass `label`
+ *   (or otherwise give the field an accessible name) — a `<select>` with no
+ *   accessible name is a WCAG failure (axe rule `select-name`).
+ *   Wrapping the host in a light-DOM `<label>` (e.g.
+ *   `<label>Fruit<ds-select>...</ds-select></label>`) is verified (via
+ *   axe-core/Chrome in this component's e2e tests) to also resolve an
+ *   accessible name for the shadow-nested `<select>` — Chromium computes it
+ *   from the flattened/composed tree even though `ds-select` is not a
+ *   "labelable" element per the strict HTML spec text (it is not a
+ *   form-associated custom element). Treat this as a secondary, best-effort
+ *   mode rather than the primary contract, since it depends on
+ *   browser/AT-specific accessible-name resolution rather than an explicit
+ *   attribute — prefer the `label` prop when in doubt.
+ *   Setting `aria-label` directly on the `<ds-select>` host does NOT work:
+ *   the host's own attributes are not forwarded into its shadow tree, so
+ *   the internal `<select>` still has no accessible name (confirmed by an
+ *   `select-name` axe violation) — use the `label` prop instead.
+ *   Options themselves are **prop-based, not slotted**: a `<slot />` nested
+ *   inside a shadow-DOM `<select>` does not project light-DOM `<option>`
+ *   elements into the native option list in Chromium (`select.options` stays
+ *   empty even though the flattened a11y tree looks correct — the bug this
+ *   prop API replaces). Pass `options` as a JSON string (SSR-friendly
+ *   attribute) or as an array (client-side property); the component renders
+ *   real `<option>` children inside its own shadow `<select>` from that data.
+ *
+ * **Focus:**
+ * - On mount: nothing auto-focuses.
+ * - On activate/open: focus stays on the native `<select>`; the browser
+ *   manages the options popup itself.
+ * - On close/deactivate: focus remains on the native `<select>`.
+ * - Focus indicator: none added by this component — the native `<select>`
+ *   keeps the browser's default `:focus-visible` ring, which is not
+ *   overridden by `ds-select.css`.
+ *
+ * **Motion:**
+ * - Animations: none.
+ * - Reduced-motion behavior: N/A — no animation to collapse.
+ *
+ * **Contrast:**
+ * - Text: inherits `color: inherit` / `currentColor`; ratio depends on the
+ *   consumer's theme, not verified in isolation here (no default text
+ *   color is imposed by this component).
+ * - Non-text (border, caret icon): both use `currentColor`, so they match
+ *   the text color 1:1 and inherit whatever contrast the host page sets;
+ *   the caret is decorative-only (no accessible name), applied via
+ *   `:host::after` mask, `pointer-events: none`.
+ *
+ * **Screen reader announcement:**
+ * - Rendered state: announces the `label` prop text as the accessible
+ *   name, followed by "combo box" / "pop up button" (announcement wording
+ *   is browser/AT dependent, standard for any native `<select>`), and the
+ *   currently selected option's text — sourced from the `label` field of
+ *   each entry in the `options` prop.
+ * - State change: on selection change, AT announces the newly selected
+ *   option text (native `<select>` behavior; no custom `aria-live` added,
+ *   per spec guidance to avoid live-region overuse).
+ *
+ * **Consumer contract:** `value` must correspond to a `value` in `options`.
+ * If `value` is set to a string not present in `options`, the native
+ * `<select>` will silently set `selectedIndex = -1` and no `dsChange` will
+ * fire — the component does not fabricate a fallback selection.
+ */
+export type DsSelectOption = {
+    value: string;
+    label: string;
+};
+export declare class DsSelect {
+    private selectEl?;
+    value?: string;
+    name?: string;
+    disabled: boolean;
+    size: "md" | "lg";
+    label?: string;
+    /**
+     * Options rendered inside the internal shadow `<select>`. Accepts either:
+     * - a JSON string (SSR-friendly — server-rendered HTML can only set
+     *   string attributes, and Stencil does not JSON-parse array attributes),
+     *   e.g. `options='[{"value":"en","label":"EN"}]'`
+     * - an array property set from client-side JS,
+     *   e.g. `el.options = [{ value: 'en', label: 'EN' }]`
+     *
+     * Malformed JSON fails safe to an empty list rather than throwing, so the
+     * component still renders a visible (if empty) select.
+     */
+    options: string | ReadonlyArray<DsSelectOption>;
+    dsChange: EventEmitter<string>;
+    watchValue(newValue?: string): void;
+    watchOptions(): void;
+    componentDidLoad(): void;
+    componentDidUpdate(): void;
+    private syncValue;
+    private parseOptions;
+    private onChange;
+    render(): any;
+}

package/dist/types/components/ds-tabs/ds-tabs.d.ts

@@ -0,0 +1,155 @@
+import { EventEmitter } from "../../stencil-public-runtime";
+/**
+ * ## Accessibility
+ *
+ * **Category:** state-machine (Tier 2)
+ * **APG pattern:** https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ *
+ * This component is a scratch build of the WAI-ARIA Tabs pattern —
+ * there is no native <tabs> element to wrap. Per the a11y spec §D,
+ * scratch-building Tier 2 requires citation + full keyboard/ARIA
+ * enumeration + focus lifecycle + manual VoiceOver evidence
+ * (pending — see commit message TODO).
+ *
+ * **Scope choice — tablist only, panels owned by the consumer.** The
+ * component renders `<button role="tab">` elements based on the
+ * `items` prop and manages roving tabindex + selection. It does NOT
+ * render tabpanels: the consumer renders their own light-DOM
+ * `<div role="tabpanel" aria-labelledby={tabId} hidden={id!==active}>`
+ * and toggles visibility based on the `dsChange` event. This keeps
+ * the state machine narrow (no reparenting, no slot ambiguity) and
+ * matches how ds-select delivers content — declare data, get behavior.
+ *
+ * **shadow: false intentional.** The tab buttons must have `id`
+ * attributes that the consumer's tabpanels reference via
+ * `aria-labelledby`. Shadow-DOM ids are not reachable from light-DOM
+ * ARIA references. Rendering the tab buttons directly in light DOM
+ * makes the ARIA association work correctly, at the cost of style
+ * encapsulation. The visual footprint is small (a bordered button
+ * strip + selected state); consumers can override with their own CSS.
+ *
+ * **Activation model — automatic.** APG allows either automatic
+ * (focus = select) or manual (focus, then Enter/Space to select).
+ * We use automatic because panels are cheap to swap (they are the
+ * consumer's DOM, already rendered). Consumers with expensive panels
+ * can defer the swap by listening to `dsChange` and rendering lazily.
+ *
+ * **Keyboard interactions (full APG enumeration):**
+ * - Tab: from outside the tablist → focus lands on the currently
+ *   selected tab (the only one with tabindex=0). From the selected
+ *   tab → focus moves out of the tablist to the next focusable
+ *   element in the document (typically the active tabpanel via its
+ *   own tabindex=0).
+ * - Shift+Tab: reverse of Tab.
+ * - Arrow Right (horizontal) / Arrow Down (vertical): move focus to
+ *   the next enabled tab; automatic activation fires dsChange with
+ *   the new id. Wraps at the last tab back to the first.
+ * - Arrow Left (horizontal) / Arrow Up (vertical): move focus to the
+ *   previous enabled tab; wraps at the first tab to the last.
+ * - Home: focus and activate the first enabled tab.
+ * - End: focus and activate the last enabled tab.
+ * - Enter / Space: no-op under automatic activation (the tab is
+ *   already selected). We do not preventDefault so consumers can
+ *   still form-submit if the tab is inside a form for some reason.
+ * - Printable characters: no APG-required behavior (typeahead is
+ *   optional and out of scope for v1).
+ *
+ * Wrap-around and skip-disabled behavior: arrow keys skip disabled
+ * tabs; Home/End land on the first/last *enabled* tab. If every tab
+ * is disabled, focus does not move.
+ *
+ * **ARIA attributes and value triggers:**
+ * - Tablist container: `role="tablist"`, `aria-orientation` set from
+ *   the `orientation` prop ("horizontal" is the ARIA default; we
+ *   emit "vertical" explicitly when the prop is "vertical" so AT
+ *   knows which arrow-key axis is meaningful).
+ * - Each tab button: `role="tab"`, `id={item.id}` (the consumer's
+ *   tabpanel references this via `aria-labelledby`),
+ *   `aria-selected="true"` on the active tab and `"false"` on the
+ *   others (toggled every dsChange), `aria-controls={item.controls
+ *   || item.id}` (the id of the tabpanel this tab governs — defaults
+ *   to the tab id when the consumer uses the same id for both),
+ *   `tabindex="0"` on the active tab and `-1` on the others (roving
+ *   tabindex), `disabled` (native) when the item declares
+ *   `disabled: true`.
+ *
+ * **Focus lifecycle:**
+ * - On mount: no auto-focus. The tablist is not focused by default;
+ *   Tab from the previous focusable in the document reaches the
+ *   active tab.
+ * - While focus is inside the tablist: arrow keys, Home, and End
+ *   move focus (and, under automatic activation, selection) among
+ *   the tabs. Focus is bounded to the tabs; there is no focus trap,
+ *   Tab / Shift+Tab still leave the tablist.
+ * - When the active tab changes via arrow / Home / End: the newly
+ *   selected tab's `<button>` receives programmatic focus (via
+ *   `.focus()`) after Stencil re-renders so the visible focus ring
+ *   tracks the selected state.
+ * - On dsChange from a mouse click: focus follows the click to the
+ *   clicked tab, matching native button behavior.
+ *
+ * **Motion:**
+ * - Animations: none applied by the component. Consumers who want
+ *   a selection-indicator slide can style the tabs themselves,
+ *   gated on `prefers-reduced-motion`.
+ *
+ * **Contrast:**
+ * - Text: inherits `color: inherit`.
+ * - Selected-tab visual: an underline drawn with `currentColor`
+ *   (matches the text and inherits whatever contrast the theme
+ *   provides). WCAG 1.4.11 (3:1 non-text) is the consumer theme's
+ *   responsibility.
+ *
+ * **Screen reader announcement:**
+ * - Rendered state: AT announces "tab list, N items" (or the
+ *   equivalent per AT), then each tab as "Label, tab, X of N,
+ *   selected" or "not selected".
+ * - State change: on arrow-key move under automatic activation, AT
+ *   announces the newly focused tab plus its selection status.
+ *
+ * **Consumer contract:**
+ * - `items` is either a JSON string (SSR-friendly attribute) or an
+ *   array (client-side property), matching ds-select's dual API.
+ *   Each item: `{ id, label, controls?, disabled? }`. Malformed
+ *   JSON falls back to an empty list (visible-but-empty tablist).
+ * - `active` is the id of the currently selected tab. If `active`
+ *   is not in `items` at mount, the first enabled tab is selected
+ *   and dsChange fires once to reconcile.
+ * - The consumer's `<div role="tabpanel" aria-labelledby={tabId}
+ *   id={item.controls || item.id} tabindex="0" hidden={id !== active}>`
+ *   is not rendered by this component — it is the consumer's DOM.
+ *
+ * **Pending manual verification (see commit message TODO):**
+ * - VoiceOver on macOS: confirm "tab list" grouping, tab-of-N
+ *   position, selected state on selection change, and that arrow
+ *   navigation announces correctly.
+ * - Chromium high-contrast / forced-colors: confirm the selected
+ *   underline remains visible.
+ */
+export type DsTabItem = {
+    id: string;
+    label: string;
+    /**
+     * Id of the tabpanel this tab controls. Defaults to `id`.
+     */
+    controls?: string;
+    disabled?: boolean;
+};
+export declare class DsTabs {
+    private tabRefs;
+    private pendingFocusId?;
+    items: string | ReadonlyArray<DsTabItem>;
+    active?: string;
+    orientation: "horizontal" | "vertical";
+    label?: string;
+    dsChange: EventEmitter<string>;
+    watchItems(): void;
+    componentWillLoad(): void;
+    componentDidRender(): void;
+    private parseItems;
+    private enabledItems;
+    private selectAndFocus;
+    private onClick;
+    private onKeyDown;
+    render(): any;
+}