@chiralkit/design-system 0.1.0-alpha.0

package/dist/collection/components/ds-textarea/ds-textarea.js

@@ -0,0 +1,342 @@
+import { h, Host, } from "@stencil/core";
+/**
+ * ## Accessibility
+ *
+ * **Category:** form-field
+ * **APG pattern:** N/A — native element. This wraps a native
+ * `<textarea>`; there is no WAI-ARIA APG pattern for a plain
+ * multi-line text field because the browser already implements it
+ * natively. Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea
+ *
+ * **Keyboard interactions:**
+ * - Tab: moves focus to the native `<textarea>`; Tab inside the
+ *   textarea inserts a tab character only when the browser is
+ *   configured to do so (default behavior: Tab moves focus out).
+ * - Printable characters: insert at the caret position (native).
+ * - Enter: inserts a newline within the value (native), does not
+ *   submit the enclosing form (unlike a single-line input).
+ * - Backspace / Delete: native editing.
+ * - Arrow keys: move the caret within the value (native).
+ * - Escape: no native meaning for a text area.
+ *
+ * **ARIA:**
+ * - Roles used: none explicit — the native `<textarea>` supplies
+ *   the implicit `textbox` role with multiline behavior.
+ * - 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 `<textarea>`. This is the **canonical, recommended**
+ *   mode. Wrapping the host in a light-DOM `<label>` also produces
+ *   an accessible name in Chromium via flattened-tree resolution —
+ *   same secondary mode documented on `ds-input` and `ds-select`,
+ *   verified in this component's e2e tests. Setting `aria-label`
+ *   directly on the `<ds-textarea>` host does NOT work: shadow-DOM
+ *   attribute forwarding would be required — use the `label` prop.
+ *
+ * **Focus:**
+ * - On mount: nothing auto-focuses.
+ * - On value change: focus remains on the native `<textarea>`.
+ * - 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.
+ *
+ * **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.
+ * - Border: `color-mix(in oklch, currentColor 22%, transparent)`,
+ *   matching `ds-input`.
+ *
+ * **Screen reader announcement:**
+ * - Rendered state: announces the `label` prop text as the
+ *   accessible name, followed by "edit text, multiline" (browser/AT
+ *   wording varies). 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 behavior); no `aria-live` added.
+ *
+ * **Consumer contract:**
+ * - `placeholder` is a hint, not a label — always pair with `label`.
+ * - 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.
+ * - `rows` sets the initial visible line count. Vertical resize is
+ *   left to the native default (`resize: vertical`) so users can
+ *   grow the field for long entries; the consumer's CSS can pin it
+ *   with `resize: none` when a fixed height matters.
+ */
+export class DsTextarea {
+    textareaEl;
+    value;
+    name;
+    placeholder;
+    disabled = false;
+    required = false;
+    invalid = false;
+    describedBy;
+    label;
+    rows = 3;
+    size = "md";
+    dsInput;
+    watchValue(newValue) {
+        if (this.textareaEl && this.textareaEl.value !== (newValue ?? "")) {
+            this.textareaEl.value = newValue ?? "";
+        }
+    }
+    componentDidLoad() {
+        if (this.textareaEl && this.value !== undefined) {
+            this.textareaEl.value = this.value;
+        }
+    }
+    onInput = (event) => {
+        const value = event.target.value;
+        this.dsInput.emit(value);
+    };
+    render() {
+        const cls = `ds-textarea ds-textarea--${this.size}`;
+        return (h(Host, { key: '89e63314bca9f6f1b70f36c540a3ac48eed7311c' }, h("textarea", { key: '59f9b8ee9a48a4e495da7fb56745102a1f0ee7c2', class: cls, name: this.name, placeholder: this.placeholder, disabled: this.disabled, rows: this.rows, "aria-label": this.label, "aria-required": this.required ? "true" : undefined, "aria-invalid": this.invalid ? "true" : undefined, "aria-describedby": this.describedBy, ref: (el) => (this.textareaEl = el), onInput: this.onInput })));
+    }
+    static get is() { return "ds-textarea"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["ds-textarea.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["ds-textarea.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "value": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "value"
+            },
+            "name": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "name"
+            },
+            "placeholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "placeholder"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "required": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "required",
+                "defaultValue": "false"
+            },
+            "invalid": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "invalid",
+                "defaultValue": "false"
+            },
+            "describedBy": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "described-by"
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label"
+            },
+            "rows": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "rows",
+                "defaultValue": "3"
+            },
+            "size": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"md\" | \"lg\"",
+                    "resolved": "\"lg\" | \"md\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "size",
+                "defaultValue": "\"md\""
+            }
+        };
+    }
+    static get events() {
+        return [{
+                "method": "dsInput",
+                "name": "dsInput",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                }
+            }];
+    }
+    static get watchers() {
+        return [{
+                "propName": "value",
+                "methodName": "watchValue"
+            }];
+    }
+}

package/dist/collection/components/ds-tooltip/ds-tooltip.css

@@ -0,0 +1,31 @@
+ds-tooltip {
+  display: inline-block;
+  position: relative;
+  color: inherit;
+}
+
+.ds-tooltip {
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 1;
+  max-width: 240px;
+  padding: var(--ds-spacing-xs) var(--ds-spacing-sm);
+  font-family: var(--ds-font-family);
+  font-size: var(--ds-font-size-md);
+  line-height: 1.3;
+  color: inherit;
+  background-color: Canvas;
+  border: 1px solid color-mix(in oklch, currentColor 25%, transparent);
+  border-radius: var(--ds-radius-sm);
+  pointer-events: none;
+  white-space: normal;
+}
+
+.ds-tooltip--bottom {
+  top: calc(100% + var(--ds-spacing-xs));
+}
+
+.ds-tooltip--top {
+  bottom: calc(100% + var(--ds-spacing-xs));
+}

package/dist/collection/components/ds-tooltip/ds-tooltip.js

@@ -0,0 +1,318 @@
+import { h, Host } from "@stencil/core";
+/**
+ * ## Accessibility
+ *
+ * **Category:** state-machine (Tier 2)
+ * **APG pattern:** https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/
+ *
+ * Scratch build (there is no native tooltip element). Per the a11y
+ * spec §D ceremony: APG citation above, full keyboard enumeration
+ * and ARIA below, focus lifecycle in the tsx and spec.json, manual
+ * VoiceOver evidence pending (see commit message TODO).
+ *
+ * **Scope choice — wraps the consumer's first Element child as the
+ * trigger.** `<ds-tooltip label="Delete"><ds-button>×</ds-button>`
+ * — the first Element inside the ds-tooltip host is treated as the
+ * trigger. shadow:false so we can imperatively set `aria-describedby`
+ * on that light-DOM child (shadow-scoped ids can't be referenced
+ * from a light-DOM `aria-describedby`).
+ *
+ * **Consumer contract:** the first Element child MUST be focusable
+ * (`<button>`, `<a href>`, native form control, or an element with
+ * `tabindex="0"`) — otherwise keyboard users cannot summon the
+ * tooltip and the pattern fails WCAG 1.4.13. The component does not
+ * force focusability onto arbitrary children; that would produce
+ * silent AT surprises. The tooltip's `label` prop is required — a
+ * tooltip with no accessible text is inert.
+ *
+ * **Keyboard interactions (full APG enumeration):**
+ * - Focus (Tab into trigger): tooltip opens immediately (no
+ *   `openDelay`). Delay-on-open is a mouse-hover ergonomic, not a
+ *   keyboard one — waiting for keyboard users to see supplementary
+ *   info is friction, not smoothing.
+ * - Escape (anywhere inside the tooltip's host, tooltip open):
+ *   dismisses the tooltip WITHOUT moving focus. The trigger remains
+ *   focused so the user can Tab away or re-summon. This is the WCAG
+ *   1.4.13 "dismissable" requirement.
+ * - Blur (Tab out of the trigger): tooltip closes immediately.
+ * - Enter / Space / arrow / printable: forwarded to the trigger
+ *   (the tooltip does not intercept them). If Enter activates the
+ *   underlying `<button>`, the button click closes the tooltip via
+ *   the natural blur-then-refocus cycle.
+ *
+ * **Pointer interactions:**
+ * - mouseenter on the host → start `openDelay` timer → show.
+ * - mouseleave on the host → start `closeDelay` timer → hide.
+ * - Re-entering during the closeDelay window cancels the hide (the
+ *   tooltip is "hoverable" — WCAG 1.4.13 — so users can move the
+ *   pointer INTO the tooltip surface without it disappearing).
+ *
+ * **Persistence** (WCAG 1.4.13): the tooltip stays visible while
+ * the trigger is focused or hovered, and while the pointer is over
+ * the tooltip content itself. Dismissal only happens via Escape,
+ * blur, or genuine mouseleave (no residual hover on host or
+ * tooltip content).
+ *
+ * **ARIA attributes and value triggers:**
+ * - Tooltip element: `role="tooltip"`, `id` (auto-generated per
+ *   instance so multiple tooltips on a page do not collide).
+ * - Trigger (the first Element child): `aria-describedby={tooltipId}`
+ *   set on componentDidLoad and refreshed on slot mutations. We use
+ *   describedby (APG default), NOT labelledby — the trigger has its
+ *   own accessible name (its text or aria-label), and the tooltip
+ *   supplements it.
+ *
+ * **Focus lifecycle:**
+ * - On mount: no auto-focus.
+ * - On trigger focus: tooltip opens immediately.
+ * - On trigger blur: tooltip closes.
+ * - On Escape while open: tooltip closes, focus stays on trigger.
+ * - The tooltip surface itself is NOT focusable — it is
+ *   supplementary content, not an interactive region.
+ *
+ * **Motion:**
+ * - Animations: none applied by the component. Consumers who want a
+ *   fade can style `[data-open="true"]` transitions gated on
+ *   `prefers-reduced-motion: no-preference`.
+ *
+ * **Contrast:**
+ * - Tooltip surface: solid background via `Canvas` system color
+ *   with `currentColor` text so it inherits the consumer theme's
+ *   text color. Border uses `color-mix(currentColor 25%,
+ *   transparent)`. Consumer theme owns the 4.5:1 text contrast and
+ *   3:1 non-text.
+ *
+ * **Screen reader announcement:**
+ * - Rendered state (closed): tooltip content is `hidden`, not in
+ *   the a11y tree.
+ * - On focus: because the trigger has `aria-describedby`, AT reads
+ *   the trigger's accessible name plus the tooltip text as a
+ *   description. AT usually announces "…, [description]" after the
+ *   trigger's role.
+ * - On Escape: the tooltip vanishes silently; AT falls back to
+ *   announcing the trigger without its description on next
+ *   interaction. This is APG behavior for dismissed tooltips.
+ *
+ * **Pending manual verification (see commit message TODO):**
+ * - VoiceOver on macOS: confirm the tooltip text is announced as a
+ *   description of the trigger when the trigger gains focus.
+ * - VoiceOver: confirm Escape dismisses the tooltip and leaves the
+ *   trigger focused; confirm re-focusing brings it back.
+ * - Chromium reduced-motion: confirm no residual animation is added
+ *   by the component.
+ */
+let tooltipIdCounter = 0;
+export class DsTooltip {
+    hostEl;
+    label;
+    openDelay = 250;
+    closeDelay = 100;
+    placement = "bottom";
+    tooltipId = `ds-tooltip-${++tooltipIdCounter}`;
+    tooltipEl;
+    openTimer;
+    closeTimer;
+    isOpen = false;
+    watchLabel() {
+        if (this.tooltipEl) {
+            this.tooltipEl.textContent = this.label;
+        }
+    }
+    componentDidLoad() {
+        this.wireTrigger();
+        this.hostEl.addEventListener("mouseenter", this.onMouseEnter);
+        this.hostEl.addEventListener("mouseleave", this.onMouseLeave);
+        this.hostEl.addEventListener("focusin", this.onFocusIn);
+        this.hostEl.addEventListener("focusout", this.onFocusOut);
+        this.hostEl.addEventListener("keydown", this.onKeyDown);
+    }
+    disconnectedCallback() {
+        this.clearTimers();
+        this.hostEl.removeEventListener("mouseenter", this.onMouseEnter);
+        this.hostEl.removeEventListener("mouseleave", this.onMouseLeave);
+        this.hostEl.removeEventListener("focusin", this.onFocusIn);
+        this.hostEl.removeEventListener("focusout", this.onFocusOut);
+        this.hostEl.removeEventListener("keydown", this.onKeyDown);
+    }
+    wireTrigger() {
+        // First Element child within the host, ignoring our own tooltip
+        // <span> which we render at the end.
+        const children = Array.from(this.hostEl.children).filter((el) => el !== this.tooltipEl);
+        const trigger = children[0];
+        if (!trigger)
+            return;
+        trigger.setAttribute("aria-describedby", this.tooltipId);
+    }
+    clearTimers() {
+        if (this.openTimer !== undefined) {
+            window.clearTimeout(this.openTimer);
+            this.openTimer = undefined;
+        }
+        if (this.closeTimer !== undefined) {
+            window.clearTimeout(this.closeTimer);
+            this.closeTimer = undefined;
+        }
+    }
+    show(delay = 0) {
+        if (this.closeTimer !== undefined) {
+            window.clearTimeout(this.closeTimer);
+            this.closeTimer = undefined;
+        }
+        if (this.isOpen)
+            return;
+        if (delay === 0) {
+            this.applyOpen(true);
+            return;
+        }
+        if (this.openTimer !== undefined)
+            return;
+        this.openTimer = window.setTimeout(() => {
+            this.openTimer = undefined;
+            this.applyOpen(true);
+        }, delay);
+    }
+    hide(delay = 0) {
+        if (this.openTimer !== undefined) {
+            window.clearTimeout(this.openTimer);
+            this.openTimer = undefined;
+        }
+        if (!this.isOpen)
+            return;
+        if (delay === 0) {
+            this.applyOpen(false);
+            return;
+        }
+        if (this.closeTimer !== undefined)
+            return;
+        this.closeTimer = window.setTimeout(() => {
+            this.closeTimer = undefined;
+            this.applyOpen(false);
+        }, delay);
+    }
+    applyOpen(open) {
+        this.isOpen = open;
+        if (!this.tooltipEl)
+            return;
+        if (open) {
+            this.tooltipEl.removeAttribute("hidden");
+            this.tooltipEl.dataset.open = "true";
+        }
+        else {
+            this.tooltipEl.setAttribute("hidden", "");
+            this.tooltipEl.dataset.open = "false";
+        }
+    }
+    onMouseEnter = () => this.show(this.openDelay);
+    onMouseLeave = () => this.hide(this.closeDelay);
+    onFocusIn = () => this.show(0);
+    onFocusOut = () => this.hide(0);
+    onKeyDown = (event) => {
+        if (event.key === "Escape" && this.isOpen) {
+            this.hide(0);
+        }
+    };
+    render() {
+        return (h(Host, { key: 'e3822251c9edab36fdffa9178473823f3e9ae525' }, h("slot", { key: 'f7c490f42ae09a739d8d91d32c2394dbdef03aa5' }), h("span", { key: '8bda1876026129859665f82b1983065df602d092', class: `ds-tooltip ds-tooltip--${this.placement}`, role: "tooltip", id: this.tooltipId, hidden: true, "data-open": "false", ref: (el) => (this.tooltipEl = el) }, this.label)));
+    }
+    static get is() { return "ds-tooltip"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["ds-tooltip.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["ds-tooltip.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label"
+            },
+            "openDelay": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "open-delay",
+                "defaultValue": "250"
+            },
+            "closeDelay": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "close-delay",
+                "defaultValue": "100"
+            },
+            "placement": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"top\" | \"bottom\"",
+                    "resolved": "\"bottom\" | \"top\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "placement",
+                "defaultValue": "\"bottom\""
+            }
+        };
+    }
+    static get elementRef() { return "hostEl"; }
+    static get watchers() {
+        return [{
+                "propName": "label",
+                "methodName": "watchLabel"
+            }];
+    }
+}

package/dist/collection/components.js

@@ -0,0 +1,2 @@
+export { DsButton } from "./components/ds-button/ds-button";
+export { DsSelect } from "./components/ds-select/ds-select";

package/dist/collection/index.js

@@ -0,0 +1 @@
+export * from "./components";