@adia-ai/web-components 0.5.11 → 0.5.13

package/components/color-input/color-input.a2ui.json

@@ -0,0 +1,218 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ColorInput.json",
+  "title": "ColorInput",
+  "description": "Compact form-bearing color input — opens a popover-anchored\n`<color-picker-ui>` from an inline swatch button. §302 (v0.5.12,\nFEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f\nOption B recipe (popover + button + color-picker) into a single\nform-associated tag for inline form contexts (settings drawer \"source\ncolor\" field, swatch-row inline-edit, etc.).",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "baseHue": {
+      "description": "Reference hue (degrees) for the hueDriftMax constraint, forwarded to inner picker. Default NaN — picker falls back to its hue at first commit.",
+      "type": "number",
+      "default": "NaN"
+    },
+    "component": {
+      "const": "ColorInput"
+    },
+    "disabled": {
+      "description": "Disables the trigger button + suppresses popover.",
+      "type": "boolean",
+      "default": false
+    },
+    "format": {
+      "description": "Output format for the value property + event detail. Hex (`#rrggbb`) or OKLCH (`oklch(L C H)`).",
+      "type": "string",
+      "enum": [
+        "hex",
+        "oklch"
+      ],
+      "default": "hex"
+    },
+    "hueDriftMax": {
+      "description": "Generation constraint forwarded to inner picker — maximum allowed signed-shortest-path hue deviation (degrees) from baseHue. Default NaN (no constraint).",
+      "type": "number",
+      "default": "NaN"
+    },
+    "maxChroma": {
+      "description": "Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13\n§-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value.\nDefault Infinity (no constraint).\n",
+      "type": "number",
+      "default": "Infinity"
+    },
+    "maxL": {
+      "description": "Generation constraint forwarded to inner picker — clamp OKLCH lightness to at most this value (0..1). Default 1.",
+      "type": "number",
+      "default": 1
+    },
+    "minL": {
+      "description": "Generation constraint forwarded to inner picker — clamp OKLCH lightness to at least this value (0..1). Default 0.",
+      "type": "number",
+      "default": 0
+    },
+    "name": {
+      "description": "Form field name.",
+      "type": "string",
+      "default": ""
+    },
+    "open": {
+      "description": "Reflects the popover's open state. Set programmatically to open/close the picker without a click.",
+      "type": "boolean",
+      "default": false
+    },
+    "placement": {
+      "description": "Popover placement relative to the trigger.",
+      "type": "string",
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "top-start",
+        "top-end",
+        "bottom-start",
+        "bottom-end"
+      ],
+      "default": "bottom-start"
+    },
+    "value": {
+      "description": "Current color as a string in the active [format].",
+      "type": "string",
+      "default": "#3b82f6"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "input",
+    "composes": [
+      "button-ui",
+      "popover-ui",
+      "color-picker-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Fired when the color is committed (pointerup / Enter / picker close). Bubbles from inner picker.",
+        "detail": {
+          "c": {
+            "description": "Parsed OKLCH chroma scalar.",
+            "type": "number"
+          },
+          "h": {
+            "description": "Parsed OKLCH hue scalar (degrees, NaN ok for achromatic).",
+            "type": "number"
+          },
+          "hex": {
+            "description": "Hex form (`#rrggbb`).",
+            "type": "string"
+          },
+          "l": {
+            "description": "Parsed OKLCH lightness scalar (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent).",
+            "type": "number"
+          },
+          "oklch": {
+            "description": "OKLCH string (`oklch(L C H)`).",
+            "type": "string"
+          },
+          "value": {
+            "description": "Color in the active [format] (hex or oklch).",
+            "type": "string"
+          }
+        }
+      },
+      "input": {
+        "description": "Fired during continuous drag of the inner picker. Bubbles from inner picker.",
+        "detail": {
+          "c": {
+            "type": "number"
+          },
+          "h": {
+            "type": "number"
+          },
+          "hex": {
+            "type": "string"
+          },
+          "l": {
+            "type": "number"
+          },
+          "oklch": {
+            "type": "string"
+          },
+          "value": {
+            "description": "Color in the active [format].",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Inline compact color input — popover-anchored picker on click.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"ColorInput\",\n    \"name\": \"brand\",\n    \"value\": \"#3b82f6\"\n  }\n]",
+        "name": "color-input-basic"
+      },
+      {
+        "description": "Compact picker exposing OKLCH value form.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"ColorInput\",\n    \"name\": \"accent\",\n    \"format\": \"oklch\",\n    \"value\": \"oklch(0.7 0.15 220)\"\n  }\n]",
+        "name": "color-input-oklch"
+      }
+    ],
+    "keywords": [
+      "color-input",
+      "color",
+      "input",
+      "picker",
+      "swatch",
+      "inline",
+      "compact"
+    ],
+    "name": "UIColorInput",
+    "related": [
+      "color-picker",
+      "popover",
+      "button",
+      "swatch"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "Popover is open; picker visible.",
+        "attribute": "open",
+        "name": "open"
+      },
+      {
+        "description": "Non-interactive; dimmed.",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "synonyms": {
+      "color-field": [
+        "color-input"
+      ],
+      "inline-color-picker": [
+        "color-input"
+      ]
+    },
+    "tag": "color-input-ui",
+    "tokens": {
+      "--color-input-swatch-size": {
+        "description": "Diameter (em) of the inline swatch circle inside the trigger button. Default 1em."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/color-input/color-input.css

@@ -0,0 +1,47 @@
+/**
+ * <color-input-ui> — compact form-bearing color input.
+ *
+ * §302 (v0.5.12, FEEDBACK-29 re-bucket). Light-DOM composition of
+ * <popover-ui> + <button-ui> + <color-picker-ui>. The host element
+ * carries form-control sizing tokens; inner button + popover keep
+ * their own primitive styling.
+ */
+
+@scope (color-input-ui) {
+  :scope {
+    --color-input-swatch-size: 1em;
+
+    display: inline-flex;
+    vertical-align: middle;
+  }
+
+  :scope[disabled] {
+    opacity: 0.55;
+    pointer-events: none;
+  }
+
+  :scope > popover-ui {
+    display: inline-flex;
+  }
+
+  /* Inline swatch chip inside the trigger button. The button-ui owns its
+   * own padding + height; the swatch is sized in em so it tracks the
+   * button's font-size + density automatically. */
+  .color-input__swatch {
+    display: inline-block;
+    inline-size: var(--color-input-swatch-size);
+    block-size: var(--color-input-swatch-size);
+    border-radius: 50%;
+    background: var(--swatch-color, transparent);
+    border: 1px solid var(--a-ui-border, currentColor);
+    margin-inline-end: var(--a-space-2, 0.5em);
+    flex: 0 0 auto;
+  }
+
+  .color-input__value {
+    font-variant-numeric: tabular-nums;
+    font-family: var(--a-font-family-mono, monospace);
+    font-size: 0.92em;
+    color: var(--a-ui-text, currentColor);
+  }
+}

package/components/color-input/color-input.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `<color-input-ui>` — compact form-bearing color input.
+ *
+ * §302 (v0.5.12, FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the
+ * USAGE.md §221f recipe (popover + button + color-picker) into a single
+ * form-associated tag for inline form contexts (settings drawer "source
+ * color" field, swatch-row inline-edit). Light-DOM composition; the
+ * inner picker fires `change` + `input` which this element re-emits
+ * with a flattened detail payload that always carries both hex + oklch
+ * string forms regardless of `[format]`.
+ *
+ * Hand-authored (FORM_BEARING in dts-codegen) because the rich event
+ * detail (parallel hex+oklch views) can't be expressed by the
+ * yaml `events:` shape alone.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/color-input
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+/**
+ * Output format selected by the `[format]` attribute. Drives the shape of
+ * `value` (and the matching `detail.value` field). Both `hex` and `oklch`
+ * forms are always present on the event detail regardless of `[format]`.
+ */
+export type ColorInputFormat = 'hex' | 'oklch';
+
+/**
+ * Detail payload for both `change` (commit) and `input` (continuous drag)
+ * events. `value` mirrors the current `[format]`; `hex` and `oklch` are
+ * always populated parallel views, so consumers don't need to parse the
+ * string.
+ */
+export interface ColorInputChangeEventDetail {
+  /** Format-respecting string. Equals `hex` when `[format="hex"]`; equals `oklch` when `[format="oklch"]`. */
+  value: string;
+  /** Hex form (`#rrggbb`). Gamut-mapped to sRGB. */
+  hex: string;
+  /** OKLCH string (`oklch(L C H)`, fixed precision). */
+  oklch: string;
+  /** Parsed OKLCH lightness (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent). */
+  l: number;
+  /** Parsed OKLCH chroma. */
+  c: number;
+  /** Parsed OKLCH hue (degrees, NaN ok for achromatic). */
+  h: number;
+}
+export type ColorInputChangeEvent = CustomEvent<ColorInputChangeEventDetail>;
+export type ColorInputInputEvent = CustomEvent<ColorInputChangeEventDetail>;
+
+export class UIColorInput extends UIFormElement {
+  /** Form field name. */
+  name: string;
+  /** Current color string in the active `format`. */
+  value: string;
+  /** Output format — drives the shape of `value`. Detail always carries both `hex` and `oklch`. */
+  format: ColorInputFormat;
+  /** Disables the trigger button + suppresses the popover. */
+  disabled: boolean;
+  /** Popover placement relative to the trigger button. */
+  placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+  /** Reflects the inner popover's open state. Set programmatically to open/close without a click. */
+  open: boolean;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH chroma to at most this value. `Infinity` = unconstrained. v0.5.13 §-TBD (FB-33 §1). */
+  maxChroma: number;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH lightness to at most this value (0..1). `1` = unconstrained. */
+  maxL: number;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH lightness to at least this value (0..1). `0` = unconstrained. */
+  minL: number;
+  /** Generation constraint forwarded to inner picker: maximum allowed signed-shortest-path hue drift in degrees from `baseHue`. `NaN` = unconstrained. */
+  hueDriftMax: number;
+  /** Reference hue (degrees) for `hueDriftMax`, forwarded to inner picker. `NaN` = picker falls back to its hue at first commit. */
+  baseHue: number;
+
+  /** Open the picker programmatically. */
+  showPicker(): void;
+  /** Close the picker programmatically. */
+  hidePicker(): void;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIColorInput, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: ColorInputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: ColorInputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/color-input/color-input.js

@@ -0,0 +1,26 @@
+/**
+ * `<color-input-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIColorInput } from '@adia-ai/web-components/components/color-input/class';
+ *
+ * Per ADR-0027, this module does NOT auto-import the composed primitives
+ * (`<popover-ui>`, `<button-ui>`, `<color-picker-ui>`). Consumers must
+ * register them explicitly before mounting `<color-input-ui>`:
+ *
+ *   import '@adia-ai/web-components/components/popover';
+ *   import '@adia-ai/web-components/components/button';
+ *   import '@adia-ai/web-components/components/color-picker';
+ *   import '@adia-ai/web-components/components/color-input';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIColorInput } from './class.js';
+
+defineIfFree('color-input-ui', UIColorInput);
+
+export { UIColorInput };

package/components/color-input/color-input.yaml

@@ -0,0 +1,188 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIColorInput
+tag: color-input-ui
+component: ColorInput
+category: input
+version: 1
+description: |-
+  Compact form-bearing color input — opens a popover-anchored
+  `<color-picker-ui>` from an inline swatch button. §302 (v0.5.12,
+  FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f
+  Option B recipe (popover + button + color-picker) into a single
+  form-associated tag for inline form contexts (settings drawer "source
+  color" field, swatch-row inline-edit, etc.).
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. The consumer (or demo shell) explicitly imports
+# the composed primitives. This element creates `<button-ui>` +
+# `<popover-ui>` + `<color-picker-ui>` light-DOM children but assumes the
+# consumer has already imported their auto-register modules.
+composes:
+  - button-ui
+  - popover-ui
+  - color-picker-ui
+props:
+  name:
+    description: Form field name.
+    type: string
+    default: ""
+  value:
+    description: Current color as a string in the active [format].
+    type: string
+    default: "#3b82f6"
+  format:
+    description: Output format for the value property + event detail. Hex (`#rrggbb`) or OKLCH (`oklch(L C H)`).
+    type: string
+    default: hex
+    reflect: true
+    enum:
+      - hex
+      - oklch
+  disabled:
+    description: Disables the trigger button + suppresses popover.
+    type: boolean
+    default: false
+    reflect: true
+  placement:
+    description: Popover placement relative to the trigger.
+    type: string
+    default: bottom-start
+    reflect: true
+    enum:
+      - top
+      - bottom
+      - left
+      - right
+      - top-start
+      - top-end
+      - bottom-start
+      - bottom-end
+  open:
+    description: Reflects the popover's open state. Set programmatically to open/close the picker without a click.
+    type: boolean
+    default: false
+    reflect: true
+  maxChroma:
+    description: |
+      Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13
+      §-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value.
+      Default Infinity (no constraint).
+    type: number
+    default: Infinity
+    reflect: true
+  maxL:
+    description: Generation constraint forwarded to inner picker — clamp OKLCH lightness to at most this value (0..1). Default 1.
+    type: number
+    default: 1
+    reflect: true
+  minL:
+    description: Generation constraint forwarded to inner picker — clamp OKLCH lightness to at least this value (0..1). Default 0.
+    type: number
+    default: 0
+    reflect: true
+  hueDriftMax:
+    description: Generation constraint forwarded to inner picker — maximum allowed signed-shortest-path hue deviation (degrees) from baseHue. Default NaN (no constraint).
+    type: number
+    default: NaN
+    reflect: true
+  baseHue:
+    description: Reference hue (degrees) for the hueDriftMax constraint, forwarded to inner picker. Default NaN — picker falls back to its hue at first commit.
+    type: number
+    default: NaN
+    reflect: true
+events:
+  change:
+    description: Fired when the color is committed (pointerup / Enter / picker close). Bubbles from inner picker.
+    detail:
+      value:
+        type: string
+        description: Color in the active [format] (hex or oklch).
+      hex:
+        type: string
+        description: Hex form (`#rrggbb`).
+      oklch:
+        type: string
+        description: OKLCH string (`oklch(L C H)`).
+      l:
+        type: number
+        description: Parsed OKLCH lightness scalar (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent).
+      c:
+        type: number
+        description: Parsed OKLCH chroma scalar.
+      h:
+        type: number
+        description: Parsed OKLCH hue scalar (degrees, NaN ok for achromatic).
+  input:
+    description: Fired during continuous drag of the inner picker. Bubbles from inner picker.
+    detail:
+      value:
+        type: string
+        description: Color in the active [format].
+      hex:
+        type: string
+      oklch:
+        type: string
+      l:
+        type: number
+      c:
+        type: number
+      h:
+        type: number
+slots: {}
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: open
+    description: Popover is open; picker visible.
+    attribute: open
+  - name: disabled
+    description: Non-interactive; dimmed.
+    attribute: disabled
+traits: []
+tokens:
+  --color-input-swatch-size:
+    description: Diameter (em) of the inline swatch circle inside the trigger button. Default 1em.
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: color-input-basic
+    description: Inline compact color input — popover-anchored picker on click.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "ColorInput",
+          "name": "brand",
+          "value": "#3b82f6"
+        }
+      ]
+  - name: color-input-oklch
+    description: Compact picker exposing OKLCH value form.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "ColorInput",
+          "name": "accent",
+          "format": "oklch",
+          "value": "oklch(0.7 0.15 220)"
+        }
+      ]
+keywords:
+  - color-input
+  - color
+  - input
+  - picker
+  - swatch
+  - inline
+  - compact
+synonyms:
+  color-field:
+    - color-input
+  inline-color-picker:
+    - color-input
+related:
+  - color-picker
+  - popover
+  - button
+  - swatch

package/components/index.js

@@ -47,6 +47,7 @@ export { UIBadge } from './badge/badge.js';
 export { UIBreadcrumb } from './breadcrumb/breadcrumb.js';
 export { UICommand } from './command/command.js';
 export { UIColorPicker } from './color-picker/color-picker.js';
+export { UIColorInput } from './color-input/color-input.js';
 export { UINoodles } from './noodles/noodles.js';
 export { UITable } from './table/table.js';
 export { UITableToolbar } from './table-toolbar/table-toolbar.js';

package/components/stat/stat-ui.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `<stat-ui>` — Metric/KPI display. Value + label + optional change indicator and trend.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/stat
+ *
+ * HAND-AUTHORED (v0.5.12 §253 FB-30 close-out). The codegen pipeline's
+ * `isCssOnly()` check at `scripts/build/dts-codegen.mjs:186-194` looks for
+ * `${dirname}.js` — but stat ships `stat-ui.js` (irregular filename; the
+ * v0.6.0 §303 rename will normalize to `stat.js`). Pre-§303 the codegen
+ * false-positives `isCssOnly` and skips this directory entirely. Hand-author
+ * this file matching `stat.yaml` props until §303 lands.
+ *
+ * Filename mirrors the JS file (`stat-ui.js` → `stat-ui.d.ts`) so TypeScript
+ * resolves the side-effect import `import '@adia-ai/web-components/components/stat/stat-ui.js'`
+ * to a typed module. Post-§303, both files rename to `stat.{js,d.ts}` and
+ * codegen takes over.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIStat extends UIElement {
+  /** Eyebrow label describing the metric. */
+  label: string;
+  /** Primary metric value (large display number / string). */
+  value: string;
+  /** Change indicator text (e.g. "+12%", "-3%"). Slotted as a badge next to value. */
+  change: string;
+  /**
+   * Trend direction or narrative subtitle. Canonical values color the change
+   * badge: `up` = success (green), `down` = danger (red), `flat`/`neutral` =
+   * muted. Any other string renders as caption-style text under the primary
+   * value (not enum-validated; yaml documents the canonical set but the type
+   * stays `string` for narrative subtitles).
+   */
+  trend: string;
+  /** Icon name displayed in the icon slot (Phosphor icon registry). */
+  icon: string;
+}

package/components/swatch/class.js

@@ -167,6 +167,14 @@ export class UISwatch extends UIElement {
     selectable:   { type: Boolean, default: false,    reflect: true },
     selected:     { type: Boolean, default: false,    reflect: true },
     autoContrast: { type: Boolean, default: false,    reflect: true },
+    // §253 (v0.5.12, FB-23 §1): label position relative to the tile.
+    // `below` (default) = current shape="block" stacked layout.
+    // `overlay` = label sits ON the tile via absolute positioning;
+    // pair with `[auto-contrast]` for OKLab-L-driven legibility.
+    // Only meaningful when shape="block"; other shapes ignore this prop.
+    // CSS-only behavior; no JS runtime delta beyond yaml-declared
+    // reflective attribute. Unblocks Tokens Studio C1.3 dogfood.
+    labelPosition: { type: String, default: 'below', reflect: true, attribute: 'label-position' },
   };
 
   static template = () => null;
@@ -204,8 +212,20 @@ export class UISwatch extends UIElement {
 
   #stamp() {
     if (this.#stamped) return;
+
+    // v0.5.13 §-TBD (FB-34 §1) — `[slot="chrome"]` children are sibling-of-tile
+    // chrome (gamut badges, override/tracked dots, custom indicators) that must
+    // survive stamping as direct host siblings, NOT funnel into #labelEl where
+    // absolute-positioning anchors against the label text bbox. Pull them out
+    // FIRST so the innerHTML='' wipe below doesn't lose them.
+    const chromeSlot = Array.from(this.children).filter(
+      n => n.getAttribute && n.getAttribute('slot') === 'chrome'
+    );
+    for (const n of chromeSlot) n.remove();
+
     // Capture pre-existing default-slot content so consumer-authored
     // children (e.g. <swatch-ui>Forecast</swatch-ui>) survive stamping.
+    // `[slot="chrome"]` children are already removed above, so won't appear here.
     const slotted = Array.from(this.childNodes).filter(n =>
       !(n.nodeType === 1 && n.dataset && (
         n.dataset.tile !== undefined ||
@@ -222,6 +242,14 @@ export class UISwatch extends UIElement {
     this.#tileEl.setAttribute('aria-hidden', 'true');
     this.appendChild(this.#tileEl);
 
+    // Chrome-slot children re-attach IMMEDIATELY after the tile so they can
+    // position absolutely against the host (host carries position: relative
+    // when shape="block" + label-position="overlay" per swatch.css). Keeping
+    // them sibling-of-tile (not descendant-of-tile) lets consumer CSS use
+    // `position: absolute; top: 2px; right: 2px` and anchor against the host's
+    // padding-box, which matches the tile's geometry in the block layout.
+    for (const n of chromeSlot) this.appendChild(n);
+
     // Badge container — holds one or more <span data-badge-variant="..."> children.
     // Multi-badge support added in v0.4.9 §92 (FEEDBACK-04 follow-up).
     this.#badgeEl = document.createElement('span');