@chiralkit/design-system 0.1.0-alpha.0

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

@@ -0,0 +1,313 @@
+import { h, Host, } from "@stencil/core";
+/**
+ * ## 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 class DsDialog {
+    dialogEl;
+    open = false;
+    label;
+    labelledBy;
+    describedBy;
+    dsOpen;
+    dsClose;
+    watchOpen(newValue) {
+        this.syncOpen(newValue);
+    }
+    componentDidLoad() {
+        // The `close` event on the native <dialog> is not composed by
+        // default, so it does not bubble out of the shadow root. Wire it
+        // here rather than in the JSX so we can re-emit as a Stencil
+        // Event that composed-crosses the boundary.
+        this.dialogEl?.addEventListener("close", this.onNativeClose);
+        if (this.open) {
+            this.syncOpen(true);
+        }
+    }
+    disconnectedCallback() {
+        this.dialogEl?.removeEventListener("close", this.onNativeClose);
+    }
+    syncOpen(shouldOpen) {
+        if (!this.dialogEl)
+            return;
+        const isOpen = this.dialogEl.open;
+        if (shouldOpen && !isOpen) {
+            // showModal() is the modal form — traps focus, adds the ::backdrop,
+            // makes background inert. show() (non-modal) is intentionally not
+            // exposed in v1.
+            this.dialogEl.showModal();
+            this.dsOpen.emit();
+        }
+        else if (!shouldOpen && isOpen) {
+            this.dialogEl.close();
+            // dsClose is emitted by onNativeClose to also cover Escape /
+            // form-submit paths — no need to emit here.
+        }
+    }
+    onNativeClose = () => {
+        this.dsClose.emit();
+    };
+    render() {
+        return (h(Host, { key: '8b25b70865ea028c81405f77a4d016348507aae6' }, h("dialog", { key: '0c82754fe4e4ecf68232a93616bbff3621866375', class: "ds-dialog", "aria-label": this.label, "aria-labelledby": this.labelledBy, "aria-describedby": this.describedBy, ref: (el) => (this.dialogEl = el) }, h("slot", { key: '30131eed9eec7db67a407770b5caefe42c78b68a' }))));
+    }
+    static get is() { return "ds-dialog"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["ds-dialog.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["ds-dialog.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "open": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "open",
+                "defaultValue": "false"
+            },
+            "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"
+            },
+            "labelledBy": {
+                "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": "labelled-by"
+            },
+            "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"
+            }
+        };
+    }
+    static get events() {
+        return [{
+                "method": "dsOpen",
+                "name": "dsOpen",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "dsClose",
+                "name": "dsClose",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }];
+    }
+    static get watchers() {
+        return [{
+                "propName": "open",
+                "methodName": "watchOpen"
+            }];
+    }
+}

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

@@ -0,0 +1,38 @@
+:host {
+  display: inline-block;
+}
+
+.ds-input {
+  font-family: var(--ds-font-family);
+  font-size: var(--ds-font-size-md);
+  background-color: transparent;
+  color: inherit;
+  border: 1px solid color-mix(in oklch, currentColor 22%, transparent);
+  -webkit-appearance: none;
+  appearance: none;
+  box-sizing: border-box;
+  width: 100%;
+}
+
+.ds-input::placeholder {
+  color: color-mix(in oklch, currentColor 45%, transparent);
+}
+
+.ds-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.ds-input[aria-invalid="true"] {
+  border-color: color-mix(in oklch, currentColor 55%, transparent);
+}
+
+.ds-input--md {
+  border-radius: var(--ds-radius-sm);
+  padding: var(--ds-spacing-sm) var(--ds-spacing-lg);
+}
+
+.ds-input--lg {
+  border-radius: var(--ds-radius-md);
+  padding: var(--ds-spacing-md) var(--ds-spacing-xl);
+}