@adia-ai/web-components 0.8.41 → 0.8.42

package/components/color-area/color-area.css

@@ -0,0 +1,188 @@
+/* ADR-0063 (gh#1563) — `@scope` matches by literal tag name, not JS
+ * prototype chain: `<color-picker-ui>` subclasses `UIColorArea` (see
+ * ../color-picker/color-picker.class.js) but needs its OWN tag named in
+ * this scope root to actually receive the styling — same shape as
+ * calendar-picker.css's `@scope (calendar-picker-ui, datetime-picker-ui)`
+ * for its own deprecated alias. */
+@scope (color-area-ui, color-picker-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --color-area-gap:              var(--a-space-2);
+    --color-area-area-height:      10rem;
+    --color-area-area-radius:      var(--a-radius-md);
+    --color-area-track-height:     0.75rem;
+    --color-area-track-radius:     var(--a-radius-full);
+    --color-area-thumb-size:       1.125rem;
+    --color-area-thumb-border:     2px solid var(--a-chrome-border);
+    --color-area-thumb-shadow:     0 0 0 1px var(--a-chrome-ring-subtle), 0 2px 4px var(--a-chrome-shadow-soft);
+    --color-area-font:             var(--a-font-family-code);
+    --color-area-font-size:        var(--a-ui-sm);
+    --color-area-fg:               var(--md-sys-color-neutral-on-surface);
+    --color-area-label-fg:         var(--a-fg-muted);
+    --color-area-border:           var(--md-sys-color-neutral-outline-variant);
+    --color-area-output-bg:        var(--a-bg-muted);
+    --color-area-output-radius:    var(--a-radius-sm);
+    --color-area-fg-disabled:      var(--a-ui-text-disabled);
+
+    /* ── Spacing ── */
+    --color-area-gap-sm:           var(--a-space-1);
+    --color-area-pad-sm:           var(--a-space-2);
+
+    /* ── Interactive ── */
+    --color-area-focus-color:      var(--md-sys-color-primary);
+    --color-area-disabled-border:  var(--md-sys-color-neutral-outline-variant);
+
+    /* ── Transitions ── */
+    --color-area-duration:         var(--a-duration-fast);
+    --color-area-easing:           var(--a-easing);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: var(--color-area-gap);
+    width: 100%;
+  }
+
+  /* ═══════ 2D Color Area ═══════ */
+
+  [data-area] {
+    position: relative;
+    width: 100%;
+    height: var(--color-area-area-height);
+    border-radius: var(--color-area-area-radius);
+    border: 1px solid var(--color-area-border);
+    overflow: hidden;
+    cursor: crosshair;
+    touch-action: none;
+  }
+
+  [data-area]:focus-visible {
+    outline: 2px solid var(--color-area-focus-color);
+    outline-offset: 2px;
+  }
+
+  [data-area] canvas {
+    image-rendering: auto;
+  }
+
+  [data-area-thumb] {
+    position: absolute;
+    width: var(--color-area-thumb-size);
+    height: var(--color-area-thumb-size);
+    border-radius: 50%;
+    border: var(--color-area-thumb-border);
+    box-shadow: var(--color-area-thumb-shadow);
+    transform: translate(-50%, -50%);
+    pointer-events: none;
+    z-index: 1;
+  }
+
+  /* ═══════ Slider Rows (H / C / L) ═══════ */
+
+  [data-sliders] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--color-area-gap-sm);
+  }
+
+  /* ═══════ Hue Track ═══════ */
+
+  [data-hue-track] {
+    position: relative;
+    width: 100%;
+    height: var(--color-area-track-height);
+    border-radius: var(--color-area-track-radius);
+    cursor: pointer;
+    touch-action: none;
+  }
+
+  [data-hue-track]:focus-visible {
+    outline: 2px solid var(--color-area-focus-color);
+    outline-offset: 2px;
+  }
+
+  [data-hue-thumb] {
+    position: absolute;
+    top: 50%;
+    width: var(--color-area-thumb-size);
+    height: var(--color-area-thumb-size);
+    border-radius: 50%;
+    border: var(--color-area-thumb-border);
+    box-shadow: var(--color-area-thumb-shadow);
+    transform: translate(-50%, -50%);
+    pointer-events: none;
+  }
+
+  /* ═══════ Output Values ═══════ */
+
+  [data-output] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--color-area-gap-sm);
+  }
+
+  [data-output-group] {
+    display: flex;
+    align-items: center;
+    gap: var(--color-area-gap-sm);
+    padding: var(--color-area-gap-sm) var(--color-area-pad-sm);
+    background: var(--color-area-output-bg);
+    border-radius: var(--color-area-output-radius);
+  }
+
+  [data-output-value] {
+    font-family: var(--color-area-font);
+    font-size: var(--color-area-font-size);
+    color: var(--color-area-fg);
+    user-select: all;
+    -webkit-user-select: all;
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* Copy button */
+  [data-copy] {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: none;
+    border: none;
+    padding: 0;
+    cursor: pointer;
+    color: var(--color-area-label-fg);
+    transition: color var(--color-area-duration) var(--color-area-easing);
+  }
+
+  [data-copy]:hover {
+    color: var(--color-area-fg);
+  }
+
+  [data-copy] icon-ui {
+    --a-icon-size: var(--color-area-font-size);
+  }
+
+  /* ═══════ Disabled ═══════ */
+
+  :scope[disabled] {
+    pointer-events: none;
+    color: var(--color-area-fg-disabled);
+  }
+  :scope[disabled] [data-area],
+  :scope[disabled] [data-hue-track] {
+    filter: grayscale(1);
+    cursor: not-allowed;
+  }
+  :scope[disabled] slider-ui {
+    --slider-fill-bg: var(--color-area-disabled-border);
+    --slider-thumb-bg: var(--color-area-disabled-border);
+  }
+  :scope[disabled] [data-output-value] {
+    color: var(--color-area-fg-disabled);
+  }
+}

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

@@ -0,0 +1,66 @@
+/**
+ * `<color-area-ui>` — OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead. Renamed from `<color-picker-ui>` (ADR-0063, gh#1563 — `-picker` is reserved for the outer trigger + popover composite shape; this is the inline substrate, mirroring <calendar-grid-ui>'s naming precedent). `<color-picker-ui>` is now a thin deprecated alias subclassing this component.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/color-area
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type ColorAreaChangeEvent = CustomEvent<unknown>;
+export interface ColorAreaConstraintClampEventDetail {
+  /** Array of `{ axis, requested, clamped, reason }` objects. axis is
+one of "l" / "c" / "h". reason names the triggering constraint
+prop. Empty arrays are never emitted.
+ */
+  clamps: unknown[];
+}
+
+export type ColorAreaConstraintClampEvent = CustomEvent<ColorAreaConstraintClampEventDetail>;
+export type ColorAreaInputEvent = CustomEvent<unknown>;
+
+export class UIColorArea extends UIElement {
+  /** Reference hue (degrees) for the [hue-drift-max] constraint. Default
+NaN — falls back to the picker's hue at first commit so the consumer
+can pre-seed the picker and constrain drift from that initial value.
+ */
+  baseHue: number;
+  /** Disables all interaction */
+  disabled: boolean;
+  /** Output format for the value property */
+  format: 'hex' | 'oklch';
+  /** Generation constraint — maximum allowed signed-shortest-path hue
+deviation (degrees) from [base-hue] (or the first-committed hue
+if [base-hue] is unset). Default NaN (no constraint). Wrap-aware
+so a drift of 350 degrees resolves as -10.
+ */
+  hueDriftMax: number;
+  /** Generation constraint (v0.4.9 §99h, FEEDBACK-02 #7) — clamp the
+OKLCH chroma channel to at most this value before commit. Out-of-
+bound mutations round-trip to the nearest in-bound equivalent +
+fire `constraint-clamp`. Default Infinity (no constraint).
+ */
+  maxChroma: number;
+  /** Generation constraint — clamp OKLCH lightness to at most this value (0..1). Default 1 (no constraint). */
+  maxL: number;
+  /** Generation constraint — clamp OKLCH lightness to at least this value (0..1). Default 0 (no constraint). */
+  minL: number;
+  /** Form field name */
+  name: string;
+  /** Current color as hex string */
+  value: string;
+
+  addEventListener(type: 'change', listener: (ev: ColorAreaChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'constraint-clamp', listener: (ev: ColorAreaConstraintClampEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: ColorAreaInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIColorArea, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+}

package/components/color-area/color-area.examples.md

@@ -0,0 +1,19 @@
+# color-area — Examples
+
+## Default
+
+```html
+<color-area-ui></color-area-ui>
+```
+
+## Pre-set Colors
+
+```html
+<color-area-ui value="#3b82f6"></color-area-ui>
+```
+
+## disabled
+
+```html
+<color-area-ui value="#3b82f6" disabled></color-area-ui>
+```

package/components/color-area/color-area.js

@@ -0,0 +1,17 @@
+/**
+ * `<color-area-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIColorArea } from '@adia-ai/web-components/components/color-area/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIColorArea } from './color-area.class.js';
+
+defineIfFree('color-area-ui', UIColorArea);
+
+export { UIColorArea };

package/components/color-area/color-area.yaml

@@ -0,0 +1,183 @@
+# Generated by scripts/migrate-yamls-to-v1.mjs — migrated to v1 contract.
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIColorArea
+tag: color-area-ui
+status: stable
+component: ColorArea
+category: input
+version: 1
+description: >-
+  OKLCH-native color picker with 2D area and H/C/L sliders.
+  Form-associated input emitting OKLCH color strings; canonical color
+  authoring surface in the AdiaUI token system. Use for color input in
+  design tools or theming UIs; for simple color swatches use <swatch-ui>
+  or <color-input-ui> instead. Renamed from `<color-picker-ui>`
+  (ADR-0063, gh#1563 — `-picker` is reserved for the outer trigger +
+  popover composite shape; this is the inline substrate, mirroring
+  <calendar-grid-ui>'s naming precedent). `<color-picker-ui>` is now a
+  thin deprecated alias subclassing this component.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - slider-ui
+props:
+  name:
+    description: Form field name
+    type: string
+    default: ""
+  disabled:
+    description: Disables all interaction
+    type: boolean
+    default: false
+    reflect: true
+  format:
+    description: Output format for the value property
+    type: string
+    default: hex
+    enum:
+      - hex
+      - oklch
+  value:
+    description: Current color as hex string
+    type: string
+    default: "#3b82f6"
+  maxChroma:
+    description: |
+      Generation constraint (v0.4.9 §99h, FEEDBACK-02 #7) — clamp the
+      OKLCH chroma channel to at most this value before commit. Out-of-
+      bound mutations round-trip to the nearest in-bound equivalent +
+      fire `constraint-clamp`. Default Infinity (no constraint).
+    type: number
+    default: Infinity
+    reflect: true
+  maxL:
+    description: Generation constraint — clamp OKLCH lightness to at most this value (0..1). Default 1 (no constraint).
+    type: number
+    default: 1
+    reflect: true
+  minL:
+    description: Generation constraint — clamp OKLCH lightness to at least this value (0..1). Default 0 (no constraint).
+    type: number
+    default: 0
+    reflect: true
+  hueDriftMax:
+    description: |
+      Generation constraint — maximum allowed signed-shortest-path hue
+      deviation (degrees) from [base-hue] (or the first-committed hue
+      if [base-hue] is unset). Default NaN (no constraint). Wrap-aware
+      so a drift of 350 degrees resolves as -10.
+    type: number
+    default: NaN
+    reflect: true
+  baseHue:
+    description: |
+      Reference hue (degrees) for the [hue-drift-max] constraint. Default
+      NaN — falls back to the picker's hue at first commit so the consumer
+      can pre-seed the picker and constrain drift from that initial value.
+    type: number
+    default: NaN
+    reflect: true
+events:
+  change:
+    description: Fired on every color change
+  input:
+    description: Fired during continuous interaction (drag)
+  constraint-clamp:
+    description: |
+      Fired immediately before `change` / `input` when one or more
+      consumer-declared constraints (max-chroma / max-l / min-l /
+      hue-drift-max) clamped a channel away from the user-requested
+      value. detail.clamps is an array of axis-specific clamp records.
+    detail:
+      clamps:
+        type: array
+        description: |
+          Array of `{ axis, requested, clamped, reason }` objects. axis is
+          one of "l" / "c" / "h". reason names the triggering constraint
+          prop. Empty arrays are never emitted.
+slots: {}
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: disabled
+    description: Non-interactive; dimmed.
+    attribute: disabled
+traits: []
+tokens: {}
+requiredIcons:
+  - copy
+  - check
+  - warning
+a2ui:
+  rules:
+    - rule: 'OKLCH-native color picker with 2D color area + H/C/L sliders. Form-associated; emits OKLCH color strings.'
+      reason: 'Canonical color-authoring surface.'
+    - rule: 'For simple color swatches (read-only display) use <swatch-ui>; for hex/rgb text input use <color-input-ui>.'
+      reason: 'Surface boundary.'
+    - rule: 'Renamed from <color-picker-ui> (ADR-0063, gh#1563); the old tag is a deprecated alias that still works — new generation should reach for ColorArea directly.'
+      reason: 'Picker-naming convention: -picker names the outer trigger+popover composite, never the inline substrate.'
+    - rule: 'Output format defaults to oklch(); set format= to override (hex, rgb, hsl).'
+      reason: 'Format knob.'
+anti_patterns: []
+examples:
+  - name: color-area-demo
+    description: Color picker card with a color picker component for selecting colors with swatches.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Card",
+          "children": [
+            "sec"
+          ]
+        },
+        {
+          "id": "sec",
+          "component": "Section",
+          "children": [
+            "cp"
+          ]
+        },
+        {
+          "id": "cp",
+          "component": "ColorArea",
+          "value": "#6366f1"
+        }
+      ]
+  - name: color-area-panel
+    description: Color picker with swatch selection in a card.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Card",
+          "children": [
+            "sec"
+          ]
+        },
+        {
+          "id": "sec",
+          "component": "Section",
+          "children": [
+            "cp"
+          ]
+        },
+        {
+          "id": "cp",
+          "component": "ColorArea",
+          "value": "#3b82f6"
+        }
+      ]
+keywords:
+  - colorarea
+  - color-area
+  - colorpicker
+  - color-picker
+  - color
+  - picker
+synonyms:
+  color-area: [color-canvas, color-surface, swatch-picker, color-picker]
+related:
+  - grid
+  - button

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

@@ -2,7 +2,7 @@
   "$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.).",
+  "description": "Compact form-bearing color input — opens a popover-anchored\n`<color-area-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-area) into a single\nform-associated tag for inline form contexts (settings drawer \"source\ncolor\" field, swatch-row inline-edit, etc.). Composes `<color-area-ui>`\n(ADR-0063, gh#1563 — renamed from `<color-picker-ui>`, which is now a\ndeprecated alias); `color-input-ui`'s own tag/name is unaffected.",
   "type": "object",
   "allOf": [
     {
@@ -41,7 +41,7 @@
       "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",
+      "description": "Generation constraint forwarded to the inner `<color-area-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"
     },
@@ -66,7 +66,7 @@
       "default": false
     },
     "placement": {
-      "description": "Popover placement relative to the trigger. Default `bottom` centers the color-picker panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger).",
+      "description": "Popover placement relative to the trigger. Default `bottom` centers the color-area panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger).",
       "type": "string",
       "enum": [
         "top",
@@ -96,7 +96,7 @@
     "composes": [
       "button-ui",
       "popover-ui",
-      "color-picker-ui"
+      "color-area-ui"
     ],
     "events": {
       "change": {
@@ -177,7 +177,7 @@
     "name": "UIColorInput",
     "parts": {},
     "related": [
-      "color-picker",
+      "color-area",
       "popover",
       "button",
       "swatch"

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

@@ -17,7 +17,7 @@
  *
  * Compact form-bearing color input. §302 (v0.5.12, FEEDBACK-29 re-bucket).
  *
- * Canonicalizes the USAGE.md §221f recipe (popover + button + color-picker)
+ * Canonicalizes the USAGE.md §221f recipe (popover + button + color-area)
  * into a single form-associated tag. Builds its inner DOM in `connected()`
  * as light-DOM children:
  *
@@ -27,10 +27,13 @@
  *         <span class="color-input__swatch"></span>
  *         <span class="color-input__value"></span>
  *       </button-ui>
- *       <color-picker-ui slot="content"></color-picker-ui>
+ *       <color-area-ui slot="content"></color-area-ui>
  *     </popover-ui>
  *   </color-input-ui>
  *
+ * Composes `<color-area-ui>` (ADR-0063, gh#1563 — renamed from
+ * `<color-picker-ui>`, which is now a deprecated alias).
+ *
  * Form-associated via UIFormElement + ElementInternals.
  */
 
@@ -44,7 +47,7 @@ export class UIColorInput extends UIFormElement {
       format:      { type: String,  default: 'hex', reflect: true },
       placement:   { type: String,  default: 'bottom', reflect: true }, // ADR-0034 Rule 2: color picker panel >> swatch trigger
       open:        { type: Boolean, default: false, reflect: true },
-      // Generation-constraint props forwarded to the inner <color-picker-ui>.
+      // Generation-constraint props forwarded to the inner <color-area-ui>.
       // v0.5.13 §-TBD (FB-33 §1) — full parity with color-picker's 5 constraint
       // props (`maxChroma` / `maxL` / `minL` / `hueDriftMax` / `baseHue`) so
       // <color-input-ui> adoption doesn't force a UX regression on consumers
@@ -105,7 +108,7 @@ export class UIColorInput extends UIFormElement {
     if (this.firstElementChild) {
       this.#popover = this.querySelector(':scope > popover-ui');
       this.#button = this.querySelector(':scope > popover-ui > button-ui[slot="trigger"]');
-      this.#picker = this.querySelector(':scope > popover-ui > color-picker-ui[slot="content"]');
+      this.#picker = this.querySelector(':scope > popover-ui > color-area-ui[slot="content"]');
       this.#swatch = this.querySelector('.color-input__swatch');
       this.#valueLabel = this.querySelector('.color-input__value');
       if (this.#popover && this.#button && this.#picker) return;
@@ -130,7 +133,7 @@ export class UIColorInput extends UIFormElement {
 
     button.append(swatch, valueLabel);
 
-    const picker = document.createElement('color-picker-ui');
+    const picker = document.createElement('color-area-ui');
     picker.setAttribute('slot', 'content');
     picker.setAttribute('format', this.format);
     picker.setAttribute('value', this.value);
@@ -197,7 +200,7 @@ export class UIColorInput extends UIFormElement {
     this.#syncFromValue();
     // Forward the inner picker's parsed OKLCH channel scalars (v0.5.13 §-TBD,
     // FB-33 §1-adjacent). Consumers writing OKLCH-native logic get the parsed
-    // {l, c, h} for free, matching <color-picker-ui>'s detail shape.
+    // {l, c, h} for free, matching <color-area-ui>'s detail shape.
     this.dispatchEvent(new CustomEvent(kind, {
       bubbles: true,
       composed: true,

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

@@ -2,7 +2,7 @@
  * <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
+ * <popover-ui> + <button-ui> + <color-area-ui>. The host element
  * carries form-control sizing tokens; inner button + popover keep
  * their own primitive styling.
  */

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

@@ -7,12 +7,12 @@
  *   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
+ * (`<popover-ui>`, `<button-ui>`, `<color-area-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-area';
  *   import '@adia-ai/web-components/components/color-input';
  *
  * @see ../../USAGE.md#registration--auto-vs-explicit