@rak200/ui 0.2.0 → 0.2.1

package/README.md

@@ -28,6 +28,12 @@ npm install @rak200/ui
   import '@rak200/ui';
 </script>
 
+<ui-field>
+  <label slot="label">Amount</label>
+  <input type="number" />
+  <span slot="help">In BRL, two decimals.</span>
+</ui-field>
+
 <ui-button>Save</ui-button>
 <ui-button variant="secondary">Cancel</ui-button>
 <ui-button disabled>Unavailable</ui-button>

package/dist/field.d.ts

@@ -0,0 +1,39 @@
+import { LitElement, type TemplateResult } from 'lit';
+/**
+ * Form plumbing: a label bound to a control, help and error text bound through
+ * `aria-describedby`, and `aria-invalid` while the field is in error.
+ *
+ * Written once here rather than per control. Every form component in the v0 cut needs the
+ * same wiring, and five copies of it are five chances to get one subtly wrong.
+ *
+ * **Everything is slotted, and that is forced rather than chosen.** An ARIA relationship
+ * by IDREF does not cross a shadow boundary: a `<label for>` rendered in this element's
+ * shadow root leaves `control.labels` empty, and an `aria-describedby` pointing into it
+ * dangles. So the label, the control, the help and the error all live in the host's tree,
+ * where the association is the platform's job — and this element only generates the ids
+ * and points them at each other.
+ *
+ * @example
+ * ```html
+ * <ui-field>
+ *   <label slot="label">Amount</label>
+ *   <input type="number" />
+ *   <span slot="help">In BRL, two decimals.</span>
+ *   <span slot="error">Amount is required.</span>
+ * </ui-field>
+ * ```
+ */
+export declare class UiField extends LitElement {
+    #private;
+    static readonly styles: import("lit").CSSResult;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(): void;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ui-field': UiField;
+    }
+}
+//# sourceMappingURL=field.d.ts.map

package/dist/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAKjE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,OAAQ,SAAQ,UAAU;;IACnC,gBAAyB,MAAM,0BAuB7B;IAeO,iBAAiB,IAAI,IAAI;IASzB,oBAAoB,IAAI,IAAI;IAK5B,YAAY,IAAI,IAAI;IAIpB,MAAM,IAAI,cAAc;CAyFpC;AAQD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,qBAAqB;QAC3B,UAAU,EAAE,OAAO,CAAC;KACvB;CACJ"}

package/dist/field.js

@@ -0,0 +1,160 @@
+import { LitElement, css, html } from 'lit';
+/** Distinguishes one field's generated ids from another's. */
+let sequence = 0;
+/**
+ * Form plumbing: a label bound to a control, help and error text bound through
+ * `aria-describedby`, and `aria-invalid` while the field is in error.
+ *
+ * Written once here rather than per control. Every form component in the v0 cut needs the
+ * same wiring, and five copies of it are five chances to get one subtly wrong.
+ *
+ * **Everything is slotted, and that is forced rather than chosen.** An ARIA relationship
+ * by IDREF does not cross a shadow boundary: a `<label for>` rendered in this element's
+ * shadow root leaves `control.labels` empty, and an `aria-describedby` pointing into it
+ * dangles. So the label, the control, the help and the error all live in the host's tree,
+ * where the association is the platform's job — and this element only generates the ids
+ * and points them at each other.
+ *
+ * @example
+ * ```html
+ * <ui-field>
+ *   <label slot="label">Amount</label>
+ *   <input type="number" />
+ *   <span slot="help">In BRL, two decimals.</span>
+ *   <span slot="error">Amount is required.</span>
+ * </ui-field>
+ * ```
+ */
+export class UiField extends LitElement {
+    static { this.styles = css `
+        :host {
+            display: block;
+            font-family: var(--ui-font, system-ui, sans-serif);
+        }
+
+        .stack {
+            display: flex;
+            flex-direction: column;
+            gap: calc(var(--ui-space, 0.5rem) / 2);
+        }
+
+        slot[name='help']::slotted(*) {
+            color: var(--ui-color-text, #1f2937);
+            font-size: 0.875em;
+        }
+
+        /* Colour is not the only cue — the error text says what is wrong, and
+       aria-invalid marks the control regardless of styling. */
+        slot[name='error']::slotted(*) {
+            color: var(--ui-color-danger, #b91c1c);
+            font-size: 0.875em;
+        }
+    `; }
+    /** The prefix for this instance's generated ids, allocated on first association. */
+    #uid;
+    /**
+     * Watches the light DOM for anything that changes the association.
+     *
+     * Built here rather than on connection so it is never absent: a disconnect that has to
+     * ask whether the observer exists is a branch no test can reach.
+     */
+    #observer = new MutationObserver(() => {
+        this.#associate();
+    });
+    connectedCallback() {
+        super.connectedCallback();
+        // The host may swap the error text without adding or removing an element, which is
+        // what a re-render looks like from here — so characterData matters as much as
+        // childList, and both can happen below a wrapper.
+        this.#observer.observe(this, { childList: true, characterData: true, subtree: true });
+    }
+    disconnectedCallback() {
+        this.#observer.disconnect();
+        super.disconnectedCallback();
+    }
+    firstUpdated() {
+        this.#associate();
+    }
+    render() {
+        return html `
+            <div class="stack" part="stack">
+                <slot name="label"></slot>
+                <slot></slot>
+                <slot name="help"></slot>
+                <slot name="error"></slot>
+            </div>
+        `;
+    }
+    /** The light-DOM child filling a slot, or `undefined` when nothing does. */
+    #slotted(name) {
+        const selector = name === null ? ':scope > :not([slot])' : `:scope > [slot='${name}']`;
+        const found = this.querySelector(selector);
+        return found instanceof HTMLElement ? found : undefined;
+    }
+    /**
+     * Points the label, the help and the error at the control.
+     *
+     * A host-supplied `id` is never overwritten — it may already be referenced by something
+     * this element cannot see.
+     */
+    #associate() {
+        const control = this.#slotted(null);
+        if (control === undefined) {
+            return;
+        }
+        // Stryker disable next-line UpdateOperator: the contract is that two fields on one
+        // page get different ids, and a decrementing counter delivers that as well as an
+        // incrementing one — `ui-field--1` is as valid an id as `ui-field-1`. No input
+        // distinguishes the two, so this is an equivalent mutant rather than a weak test.
+        const uid = (this.#uid ??= `ui-field-${String(++sequence)}`);
+        if (control.id === '') {
+            control.id = `${uid}-control`;
+        }
+        const label = this.#slotted('label');
+        if (label instanceof HTMLLabelElement) {
+            label.htmlFor = control.id;
+        }
+        const help = this.#describer(this.#slotted('help'), `${uid}-help`);
+        const error = this.#describer(this.#slotted('error'), `${uid}-error`);
+        // The error comes first: a screen reader announces descriptions in order, and the
+        // user needs to know what is wrong before reading how the value should look.
+        //
+        // The error SUPPLEMENTS the help rather than replacing it. Help text is usually the
+        // format requirement, which is exactly the error suggestion the user needs in order
+        // to recover (WCAG 3.3.3) — dropping it at the moment it becomes useful is the
+        // opposite of helping.
+        const described = [error, help].filter((id) => id !== undefined);
+        if (described.length > 0) {
+            control.setAttribute('aria-describedby', described.join(' '));
+        }
+        else {
+            control.removeAttribute('aria-describedby');
+        }
+        if (error === undefined) {
+            control.removeAttribute('aria-invalid');
+        }
+        else {
+            control.setAttribute('aria-invalid', 'true');
+        }
+    }
+    /**
+     * The id to describe the control by, or `undefined` when the element is absent or has
+     * nothing to say. An element rendered empty — the shape a framework produces for
+     * "no error yet" — must not mark the control invalid.
+     */
+    #describer(element, fallbackId) {
+        if (element === undefined || element.textContent.trim() === '') {
+            return undefined;
+        }
+        if (element.id === '') {
+            element.id = fallbackId;
+        }
+        return element.id;
+    }
+}
+// Stryker disable next-line StringLiteral: the registration runs once, at import, inside
+// the warm process Stryker switches mutants in — so by the time a mutant on this line is
+// active the element is already defined under the original name, and no test can observe
+// the change. Outside the runner's reach, not an equivalent mutant.
+customElements.define('ui-field', UiField);
+//# sourceMappingURL=field.js.map

package/dist/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { UiButton, type ButtonVariant } from './button.js';
+export { UiField } from './field.js';
 export { tokens, defaults, tokenStyleSheet, type Token } from './tokens.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { UiButton } from './button.js';
+export { UiField } from './field.js';
 export { tokens, defaults, tokenStyleSheet } from './tokens.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAsB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAc,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAsB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAc,MAAM,aAAa,CAAC"}

package/dist/tokens.d.ts

@@ -10,7 +10,7 @@
  * setting it anywhere above the component — no build step, no theme object, no fork.
  */
 /** The token names this package defines, as they appear in CSS. */
-export declare const tokens: readonly ["--ui-color-accent", "--ui-color-accent-contrast", "--ui-color-surface", "--ui-color-text", "--ui-color-focus", "--ui-radius", "--ui-space", "--ui-font"];
+export declare const tokens: readonly ["--ui-color-accent", "--ui-color-accent-contrast", "--ui-color-surface", "--ui-color-text", "--ui-color-focus", "--ui-color-danger", "--ui-radius", "--ui-space", "--ui-font"];
 /** A CSS custom property this package defines. */
 export type Token = (typeof tokens)[number];
 /**

package/dist/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,eAAO,MAAM,MAAM,qKAST,CAAC;AAEX,kDAAkD;AAClD,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CASpD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,eAAO,MAAM,MAAM,0LAUT,CAAC;AAEX,kDAAkD;AAClD,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAUpD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}

package/dist/tokens.js

@@ -16,6 +16,7 @@ export const tokens = [
     '--ui-color-surface',
     '--ui-color-text',
     '--ui-color-focus',
+    '--ui-color-danger',
     '--ui-radius',
     '--ui-space',
     '--ui-font',
@@ -32,6 +33,7 @@ export const defaults = {
     '--ui-color-surface': '#ffffff',
     '--ui-color-text': '#1f2937',
     '--ui-color-focus': '#f59e0b',
+    '--ui-color-danger': '#b91c1c',
     '--ui-radius': '0.375rem',
     '--ui-space': '0.5rem',
     '--ui-font': 'system-ui, sans-serif',

package/dist/tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,MAAM,GAAG;IAClB,mBAAmB;IACnB,4BAA4B;IAC5B,oBAAoB;IACpB,iBAAiB;IACjB,kBAAkB;IAClB,aAAa;IACb,YAAY;IACZ,WAAW;CACL,CAAC;AAKX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAoC;IACrD,mBAAmB,EAAE,SAAS;IAC9B,4BAA4B,EAAE,SAAS;IACvC,oBAAoB,EAAE,SAAS;IAC/B,iBAAiB,EAAE,SAAS;IAC5B,kBAAkB,EAAE,SAAS;IAC7B,aAAa,EAAE,UAAU;IACzB,YAAY,EAAE,QAAQ;IACtB,WAAW,EAAE,uBAAuB;CACvC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,KAAK,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjF,OAAO,YAAY,IAAI,KAAK,CAAC;AACjC,CAAC"}
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,MAAM,GAAG;IAClB,mBAAmB;IACnB,4BAA4B;IAC5B,oBAAoB;IACpB,iBAAiB;IACjB,kBAAkB;IAClB,mBAAmB;IACnB,aAAa;IACb,YAAY;IACZ,WAAW;CACL,CAAC;AAKX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAoC;IACrD,mBAAmB,EAAE,SAAS;IAC9B,4BAA4B,EAAE,SAAS;IACvC,oBAAoB,EAAE,SAAS;IAC/B,iBAAiB,EAAE,SAAS;IAC5B,kBAAkB,EAAE,SAAS;IAC7B,mBAAmB,EAAE,SAAS;IAC9B,aAAa,EAAE,UAAU;IACzB,YAAY,EAAE,QAAQ;IACtB,WAAW,EAAE,uBAAuB;CACvC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,KAAK,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEjF,OAAO,YAAY,IAAI,KAAK,CAAC;AACjC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rak200/ui",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Host-agnostic custom-element UI components for the rak200 ecosystem",
   "license": "MIT",
   "author": "rak200 <rak.ricardo@windowslive.com>",