@agent-ui-kit/components 0.0.3

package/dist/traits/tabbable.d.ts

@@ -0,0 +1,12 @@
+import type { UIElement } from '../dom/index.js';
+export interface TabbableOptions {
+    /** True ⇒ the control is disabled and leaves the tab order. Read reactively inside the effect. */
+    disabled: () => boolean;
+}
+/**
+ * Make a `UIElement` keyboard-focusable (`tabindex=0`) while enabled and remove it from the tab order while
+ * disabled, native-button style. Invoke from the control's `connected()` (where the connection scope is
+ * live). Returns `release()` for early teardown (idempotent); otherwise the effect is disposed when the host
+ * disconnects.
+ */
+export declare function tabbable(host: UIElement, opts: TabbableOptions): () => void;

package/dist/traits/tabbable.js

@@ -0,0 +1,59 @@
+// tabbable.ts — the focusability trait (ADR-0010). A light-DOM custom element inherits NONE of a native
+// button's focus behaviour, so an interactive control opts into tab participation by calling this from
+// `connected()`.
+//
+// Semantics (native-button parity):
+//  · enabled  — `host.tabIndex = 0` ⇒ keyboard-focusable (role=button parity; lets the focus ring show).
+//  · disabled — `removeAttribute('tabindex')` ⇒ out of the tab order, matching native `<button disabled>`.
+//  · reactive — the rule runs in a scope-owned `host.effect`, so toggling the `disabled` signal re-applies it.
+//
+// THE ROVING-MARKER CONTRACT (ADR-0121 amendment, post-toolbar): while `disabled` is false, this trait
+// DEFERS the `tabIndex = 0` write whenever the host carries `ROVING_ITEM_ATTR` (`data-roving`) —
+// traits/roving-focus.ts's ownership marker, stamped on every item a roving-focus host manages (see that
+// module's own banner for the full ordering story: a roving PARENT's synchronous init runs before this
+// trait's own `connected()`-installed effect for items connected in the same subtree, so without this
+// deferral a `ui-button`/`ui-radio`/any tabbable item inside a roving host would silently reclaim a second
+// tab stop the instant it connects — `ui-toolbar` → `ui-button` is what surfaced the bug; `ui-radio-group`
+// → `ui-radio` carried it too, latent). The check runs on EVERY effect re-run (not just the first), so a
+// later re-enable while still roving-owned correctly stays deferred (no "two tab stops" regression) —
+// `disabled`/`aria-disabled` semantics are entirely UNCHANGED by this; only the tabIndex=0 WRITE yields.
+// Absent the marker (every non-roving-hosted tabbable control — the overwhelming majority), this trait's
+// behavior is byte-identical to the pre-ADR-0121 rule (tabbable.test.ts's own identity-style probe pins it).
+//
+// Where `press-activation` only GUARDS at event time (no reactivity), `tabbable` must ACTIVELY change a DOM
+// attribute when `disabled` toggles — hence an effect, not listeners. Both are scope/abort-owned + leak-free:
+// the effect is created under the host's connection scope, so it dies on disconnect and re-installs on
+// reconnect (`connected()` re-runs). `release()` is an idempotent early-teardown escape hatch.
+//
+// `traits → dom` is the one allowed cross-layer direction (reactive ← dom ← traits); the host type only.
+// `ROVING_ITEM_ATTR` is imported from the sibling `roving-focus.ts` trait — a same-layer (traits → traits)
+// import, permitted by layering.test.ts (only an upward import is a violation).
+import { ROVING_ITEM_ATTR } from "./roving-focus.js";
+/**
+ * Make a `UIElement` keyboard-focusable (`tabindex=0`) while enabled and remove it from the tab order while
+ * disabled, native-button style. Invoke from the control's `connected()` (where the connection scope is
+ * live). Returns `release()` for early teardown (idempotent); otherwise the effect is disposed when the host
+ * disconnects.
+ */
+export function tabbable(host, opts) {
+    let released = false;
+    const dispose = host.effect(() => {
+        if (released)
+            return;
+        if (opts.disabled()) {
+            host.removeAttribute('tabindex'); // disabled → out of the tab order (native parity)
+            return;
+        }
+        // ROVING-MARKER CONTRACT (see the file banner) — an external roving-focus host already owns this
+        // item's tab-stop; yield the write rather than reclaiming a second tabindex=0.
+        if (host.hasAttribute(ROVING_ITEM_ATTR))
+            return;
+        host.tabIndex = 0; // enabled, not roving-owned → focusable, role=button parity
+    });
+    return () => {
+        if (released)
+            return;
+        released = true;
+        dispose();
+    };
+}

package/dist/traits/track-user-invalid.d.ts

@@ -0,0 +1,36 @@
+import type { ReadonlySignal } from '../reactive/index.js';
+import type { UIElement } from '../dom/index.js';
+export interface TrackUserInvalidOptions {
+    /** True ⇒ the control is currently invalid. Read lazily by `userInvalid()`, never to drive the timing. */
+    invalid: () => boolean;
+}
+export interface TrackUserInvalidController {
+    /**
+     * The TIMING signal: false until the first blur/change on the host, then true. The control reads this
+     * (directly or via `userInvalid()`) to gate the user-invalid treatment. Read-only to consumers.
+     */
+    readonly interacted: ReadonlySignal<boolean>;
+    /**
+     * The composed gate: `interacted.value && invalid()`. The control's apply effect reads this and reflects
+     * it onto `internals` (`states.add/delete('user-invalid')` + the editor `aria-invalid`). Reading it inside
+     * an effect tracks `interacted` (always) and `invalid`'s deps (only once interacted — `&&` short-circuits,
+     * so validity is untracked until the user has interacted, which is the whole point).
+     */
+    userInvalid: () => boolean;
+    /**
+     * Clear the touched state back to its first-paint suppression: flips `interacted` to false so the
+     * user-invalid treatment is gated off again until the next blur/change. The control calls this from its
+     * `formReset()` so a form reset does not leave a required-empty field showing `:state(user-invalid)` (native
+     * parity). Idempotent (a no-op when already false — an Object.is-equal set); does not touch the listeners.
+     */
+    reset: () => void;
+    /** Idempotent early teardown: stops the behaviour. Otherwise the listeners die with the connection. */
+    release: () => void;
+}
+/**
+ * Track first-interaction TIMING for a form control's user-invalid treatment. Invoke from the control's
+ * `connected()` (where the connection scope + `AbortSignal` are live). Returns the `interacted` signal +
+ * the composed `userInvalid()` gate + an idempotent `release()`; the listeners auto-remove on disconnect
+ * and re-arm on reconnect.
+ */
+export declare function trackUserInvalid(host: UIElement, opts: TrackUserInvalidOptions): TrackUserInvalidController;

package/dist/traits/track-user-invalid.js

@@ -0,0 +1,52 @@
+// track-user-invalid.ts — the user-invalid TIMING controller (ADR-0014 clause 2c, G4).
+//
+// A form control must NOT flash `aria-invalid` / `:state(user-invalid)` on first paint — the danger
+// treatment surfaces only AFTER the user has interacted (the first blur or change). This controller owns
+// that TIMING: it watches the host for the first interaction and flips a reactive `interacted` cell true,
+// exposing it so the CONTROL gates the danger state. The control APPLIES the AX/custom state via its
+// protected `internals` (a controller cannot reach `host.internals` — the same `tabbable`/`ariaDisabled`
+// split ADR-0010 forced); this supplies the TIMING, never the application.
+//
+// Stateless trait vs stateful controller (plan §7 'traits + controllers'): `tabbable`/`press-activation`
+// are stateless traits; this OWNS a signal, so it is a CONTROLLER — same `(host, opts) => …` seam, but its
+// return carries the `interacted` signal (+ the composed `userInvalid()` convenience) alongside `release()`.
+//
+// Lifetime (mirrors `press-activation`): the blur/change listeners ride `host.listen` → the connection
+// `AbortSignal`, so they auto-remove on disconnect — zero residue, and re-armed on reconnect when
+// `connected()` re-runs the controller. `release()` is an idempotent early-teardown guard the handlers
+// check; like `press-activation` it stops the BEHAVIOUR (the listeners themselves die with the connection).
+//
+// Layering: `traits → reactive` (the `signal`/`ReadonlySignal` cell) and `traits → dom` (the host type) are
+// both DOWNWARD imports (reactive L0 ← dom L1 ← traits L2), allowed by the import-layering trip-wire — the
+// signal-OWNING controller needs the kernel that the stateless `tabbable`/`press-activation` traits do not.
+import { signal } from "../reactive/index.js";
+/**
+ * Track first-interaction TIMING for a form control's user-invalid treatment. Invoke from the control's
+ * `connected()` (where the connection scope + `AbortSignal` are live). Returns the `interacted` signal +
+ * the composed `userInvalid()` gate + an idempotent `release()`; the listeners auto-remove on disconnect
+ * and re-arm on reconnect.
+ */
+export function trackUserInvalid(host, opts) {
+    let released = false;
+    const interacted = signal(false);
+    const onInteract = () => {
+        if (released)
+            return;
+        interacted.value = true; // first interaction flips it; later sets are Object.is no-ops (idempotent)
+    };
+    // `blur` does NOT bubble, so a host listener captures it — the capture phase reaches the host before a
+    // focusable descendant (e.g. the text-field editor part), catching its blur. `change` bubbles (native +
+    // the control's host-emitted `change`), so it needs no capture.
+    host.listen(host, 'blur', onInteract, { capture: true });
+    host.listen(host, 'change', onInteract);
+    return {
+        interacted,
+        userInvalid: () => interacted.value && opts.invalid(),
+        reset: () => {
+            interacted.value = false; // back to first-paint suppression; equal-set is an Object.is no-op (idempotent)
+        },
+        release: () => {
+            released = true;
+        },
+    };
+}

package/dist/traits/value-codec.d.ts

@@ -0,0 +1,120 @@
+import type { ReadonlySignal } from '../reactive/index.js';
+import type { UIElement } from '../dom/index.js';
+export interface ValueCodecOptions {
+    /** Parse display string → canonical form value (e.g. "1,234.56" → "1234.56"). null = parse error. */
+    parse(display: string): string | null;
+    /** Format canonical form value → display string (e.g. "1234.56" → "1,234.56"). */
+    format(value: string): string;
+    /** Validation message to expose when parse returns null; the control uses it in formValidity(). */
+    errorMessage: string;
+}
+export interface ValueCodecController {
+    /**
+     * The last successfully parsed canonical form value. The control MUST return `canonical.value` from
+     * its formValue() override when the codec is active — host.value holds the formatted display after
+     * blur, not the canonical submission value. Seeded from host.value at attach time.
+     */
+    readonly canonical: ReadonlySignal<string>;
+    /**
+     * True when the most recent blur attempt failed to parse. The control drives its formValidity()
+     * `customError` flag from this signal.
+     */
+    readonly hasError: ReadonlySignal<boolean>;
+    /** The error message string (mirrors opts.errorMessage). */
+    readonly errorMessage: string;
+    /**
+     * Force-update the canonical when the control changes the value programmatically outside the blur
+     * path (e.g. clear button, steppers). Also clears hasError, since the programmatic value is known-valid.
+     */
+    setCanonical(value: string): void;
+    /**
+     * Idempotent early teardown — stops the behaviour on the next event. Listeners auto-die with the
+     * connection scope regardless; call release() from the type-change effect cleanup or disconnected().
+     */
+    release(): void;
+}
+interface CodecHost extends UIElement {
+    value: string;
+}
+/**
+ * Attach the display-codec behaviour to a form control. Invoke from connected(), AFTER the control
+ * has created its [data-part="editor"] child (so the editor is present for listener registration).
+ *
+ * @param host    The control — must have a `value` reactive prop and a `[data-part="editor"]` child.
+ * @param opts    The codec: parse / format / errorMessage.
+ * @param typeSignal  Optional per-type-run `AbortSignal` (from the type-effect's `AbortController`). When
+ *                    provided, both the focus (capture on host) and blur (on editor) listeners are tied
+ *                    to THIS signal, so the type-effect's `typeAc.abort()` removes them immediately on
+ *                    type change. Without the signal, they fall back to `host.listen()` (connection scope)
+ *                    and live until disconnect — which leaks N−1 inert listener pairs after N type-switches.
+ *                    Wave 5B date/time codecs MUST pass `typeAc.signal` on the same seam.
+ * @returns           Controller: canonical + hasError + errorMessage + setCanonical + release.
+ */
+export declare function valueCodec(host: CodecHost, opts: ValueCodecOptions, typeSignal?: AbortSignal): ValueCodecController;
+/**
+ * Codec options for type=number. Parses by stripping grouping separators (accepts "1,234.56" → 1234.56);
+ * formats with Intl.NumberFormat (locale-aware grouping). Accepts both raw and formatted display strings.
+ *
+ * @param locale  BCP 47 locale (default: runtime locale). Pin to 'en-US' in tests for determinism.
+ */
+export declare function numberCodecOptions(locale?: string): ValueCodecOptions;
+/**
+ * Codec options for type=currency. Parses like numberCodecOptions; formats with the per-currency
+ * fraction-digit count resolved from Intl (USD 2 · JPY 0 · BHD 3). The currency symbol is displayed
+ * as the control's leading adornment (not embedded in the formatted number string) — use
+ * `currencySymbol()` to resolve the glyph separately.
+ *
+ * @param currency  ISO 4217 currency code (e.g. 'USD', 'JPY', 'BHD'). Falls back to 2 fraction digits
+ *                  on an invalid code (Intl throws a RangeError — caught defensively).
+ * @param locale    BCP 47 locale (default: runtime locale).
+ */
+export declare function currencyCodecOptions(currency: string, locale?: string): ValueCodecOptions;
+/**
+ * Codec options for type=unit. Delegates to the numeric core today; the `unit` param is RESERVED for
+ * future per-unit precision (e.g. integer-only for °C vs. many decimals for currency ratios). The
+ * unit-specificity that matters today is the trailing adornment label, not the parse/format — so there
+ * is zero distinct numeric behaviour, and this is an honest reserved seam (ADR-0047 alt.2).
+ *
+ * @param unit    CLDR unit identifier (reserved — no numeric effect today).
+ * @param locale  BCP 47 locale (default: runtime locale).
+ */
+export declare function unitCodecOptions(unit: string, locale?: string): ValueCodecOptions;
+/**
+ * Extract the narrow currency symbol for the given ISO 4217 currency code (e.g. 'USD' → '$',
+ * 'JPY' → '¥', 'EUR' → '€'). Uses `currencyDisplay: 'narrowSymbol'` for the compact glyph.
+ * Falls back to the currency string itself on Intl error (invalid code or unsupported locale feature).
+ *
+ * @param currency  ISO 4217 currency code.
+ * @param locale    BCP 47 locale (default: runtime locale). Affects symbol variants in some locales.
+ */
+export declare function currencySymbol(currency: string, locale?: string): string;
+/**
+ * Resolve the short localized unit label for a CLDR unit identifier (e.g. 'kilogram' → 'kg',
+ * 'mile-per-hour' → 'mph'). Falls back to the raw `unit` string if Intl rejects it (an invalid CLDR
+ * id raises a RangeError — caught defensively). The trimmed `unit` part of `formatToParts(1)` is used
+ * to extract just the label without the numeric value.
+ *
+ * @param unit    CLDR unit identifier (e.g. 'kilogram', 'mile-per-hour').
+ * @param locale  BCP 47 locale (default: runtime locale).
+ */
+export declare function unitLabel(unit: string, locale?: string): string;
+/**
+ * Codec options for type=date. Canonical form: ISO `YYYY-MM-DD`. Format: localized medium
+ * date string via Intl.DateTimeFormat `{dateStyle:'medium'}`. Parse: ISO always accepted
+ * (timezone-safe local-time constructor); locale heuristic for numeric inputs (e.g. "03/04/2024"
+ * in en-US → 2024-03-04); last-resort new Date() for named-month forms; null on invalid.
+ * Error message: 'Please enter a valid date.'
+ *
+ * @param locale  BCP 47 locale (default: runtime locale). Pin to 'en-US' in tests for determinism.
+ */
+export declare function dateCodecOptions(locale?: string): ValueCodecOptions;
+/**
+ * Codec options for type=time. Canonical form: `HH:MM` (24h, zero-padded). Format: localized
+ * short time string via Intl.DateTimeFormat `{timeStyle:'short'}`. Parse: accepts HH:MM (24h)
+ * and H:MM AM/PM (best-effort 12h → 24h conversion, handles en-US Intl output including
+ * narrow no-break space variants); null on invalid. Error message: 'Please enter a valid time.'
+ *
+ * @param locale  BCP 47 locale (default: runtime locale). Pin to 'en-US' in tests for determinism.
+ */
+export declare function timeCodecOptions(locale?: string): ValueCodecOptions;
+export {};