@adia-ai/web-components 0.4.6 → 0.4.8

package/components/calendar-picker/class.js

@@ -0,0 +1,351 @@
+/**
+ * Non-side-effect class export for `<calendar-picker-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/calendar-picker`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <calendar-picker-ui label="Date" placeholder="Select date..." format="short"></calendar-picker-ui>
+ *
+ * Date picker with trigger button and popover calendar grid.
+ * Form-associated via UIFormElement + ElementInternals.
+ *
+ * Properties:
+ *   label       — field label (rendered via CSS ::before)
+ *   placeholder — trigger text when no date selected
+ *   format      — display format: short | long | iso
+ *   min         — minimum selectable date (ISO string)
+ *   max         — maximum selectable date (ISO string)
+ *   open        — popover visibility
+ *
+ * Keyboard: Arrow keys navigate days, Enter selects, Escape closes.
+ */
+
+import { UIFormElement } from '../../core/form.js';
+import { anchorPopover } from '../../core/anchor.js';
+
+const DAYS = ['S', 'M', 'T', 'W', 'T', 'F', 'S'];
+const MONTHS_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const MONTHS_LONG = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+
+function toISO(y, m, d) {
+  return `${y}-${String(m + 1).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
+}
+
+function parseISO(str) {
+  if (!str) return null;
+  const [y, m, d] = str.split('-').map(Number);
+  if (isNaN(y) || isNaN(m) || isNaN(d)) return null;
+  return new Date(y, m - 1, d);
+}
+
+function sameDay(a, b) {
+  return a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate();
+}
+
+export class UICalendarPicker extends UIFormElement {
+  static properties = {
+    ...UIFormElement.properties,
+    label:       { type: String,  default: '', reflect: true },
+    placeholder: { type: String,  default: 'Select date...', reflect: true },
+    format:      { type: String,  default: 'short', reflect: true },
+    min:         { type: String,  default: '', reflect: true },
+    max:         { type: String,  default: '', reflect: true },
+    open:        { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #popover = null;
+  #trigger = null;
+  #anchorCleanup = null;
+  #viewYear = new Date().getFullYear();
+  #viewMonth = new Date().getMonth();
+  #focusedDay = null;
+  #popoverClickBound = false;
+  #openRaf = null;
+
+  #onPopoverClick = (e) => {
+    const target = e.target instanceof Element ? e.target : null;
+    if (!target) return;
+    const prev = target.closest('[data-cal-prev]');
+    if (prev) { e.stopPropagation(); this.#navigate(-1); return; }
+    const next = target.closest('[data-cal-next]');
+    if (next) { e.stopPropagation(); this.#navigate(1); return; }
+    const day = target.closest('[data-cal-day][data-date]:not([disabled])');
+    if (day) { e.stopPropagation(); this.#selectDate(day.dataset.date); }
+  };
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'group');
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('keydown', this.#onKey);
+
+    // Initialize view to selected date or today
+    const sel = parseISO(this.value);
+    if (sel) {
+      this.#viewYear = sel.getFullYear();
+      this.#viewMonth = sel.getMonth();
+    }
+  }
+
+  render() {
+    // Stamp trigger + popover if not present
+    if (!this.querySelector('[slot="trigger"]')) {
+      this.innerHTML = `
+        <span slot="trigger">
+          <span slot="display">${this.#displayText()}</span>
+          <icon-ui name="calendar" slot="caret"></icon-ui>
+        </span>
+      `;
+      this.#trigger = this.querySelector('[slot="trigger"]');
+
+      this.#popover = document.createElement('div');
+      this.#popover.setAttribute('slot', 'popover');
+      this.#popover.setAttribute('popover', 'manual');
+      this.appendChild(this.#popover);
+      this.#popover.addEventListener('click', this.#onPopoverClick);
+      this.#popoverClickBound = true;
+    } else {
+      const display = this.querySelector('[slot="display"]');
+      if (display) display.textContent = this.#displayText();
+    }
+
+    if (!this.#popover) this.#popover = this.querySelector('[slot="popover"]');
+    if (!this.#trigger) this.#trigger = this.querySelector('[slot="trigger"]');
+    if (this.#popover && !this.#popoverClickBound) {
+      this.#popover.addEventListener('click', this.#onPopoverClick);
+      this.#popoverClickBound = true;
+    }
+
+    // Toggle popover
+    if (this.open) {
+      this.#renderCalendar();
+      this.#popover?.showPopover?.();
+      this.#anchorCleanup = anchorPopover(this.#trigger, this.#popover, {
+        placement: 'bottom-start', gap: 4,
+      });
+      this.#openRaf = requestAnimationFrame(() => {
+        this.#openRaf = null;
+        if (!this.isConnected || !this.open) return;
+        document.addEventListener('pointerdown', this.#onOutside, { once: true });
+      });
+    } else {
+      this.#anchorCleanup?.();
+      this.#anchorCleanup = null;
+      if (this.#openRaf != null) {
+        cancelAnimationFrame(this.#openRaf);
+        this.#openRaf = null;
+      }
+      this.#popover?.hidePopover?.();
+      document.removeEventListener('pointerdown', this.#onOutside);
+    }
+  }
+
+  #displayText() {
+    if (!this.value) return this.placeholder;
+    const d = parseISO(this.value);
+    if (!d) return this.value;
+    switch (this.format) {
+      case 'long':
+        return `${MONTHS_LONG[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()}`;
+      case 'iso':
+        return this.value;
+      case 'short':
+      default:
+        return `${MONTHS_SHORT[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()}`;
+    }
+  }
+
+  #renderCalendar() {
+    if (!this.#popover) return;
+
+    const year = this.#viewYear;
+    const month = this.#viewMonth;
+    const today = new Date();
+    const selected = parseISO(this.value);
+    const minDate = parseISO(this.min);
+    const maxDate = parseISO(this.max);
+
+    // Header
+    let h = `<div data-cal-header>
+      <button data-cal-prev type="button" aria-label="Previous month"><icon-ui name="caret-left"></icon-ui></button>
+      <span data-cal-title>${MONTHS_LONG[month]} ${year}</span>
+      <button data-cal-next type="button" aria-label="Next month"><icon-ui name="caret-right"></icon-ui></button>
+    </div>`;
+
+    // Day-of-week header
+    h += `<div data-cal-weekdays>${DAYS.map(d => `<span>${d}</span>`).join('')}</div>`;
+
+    // Calendar grid
+    const firstDay = new Date(year, month, 1).getDay();
+    const daysInMonth = new Date(year, month + 1, 0).getDate();
+    const daysInPrev = new Date(year, month, 0).getDate();
+
+    h += '<div data-cal-grid>';
+
+    // Previous month trailing days
+    for (let i = firstDay - 1; i >= 0; i--) {
+      const day = daysInPrev - i;
+      h += `<button type="button" data-cal-day data-outside disabled tabindex="-1">${day}</button>`;
+    }
+
+    // Current month days
+    for (let d = 1; d <= daysInMonth; d++) {
+      const date = new Date(year, month, d);
+      const iso = toISO(year, month, d);
+      const isToday = sameDay(date, today);
+      const isSelected = selected && sameDay(date, selected);
+      const isDisabled = (minDate && date < minDate) || (maxDate && date > maxDate);
+      const isFocused = this.#focusedDay === d;
+
+      const attrs = [
+        'type="button"',
+        'data-cal-day',
+        `data-date="${iso}"`,
+        isToday ? 'data-today' : '',
+        isSelected ? 'data-selected' : '',
+        isDisabled ? 'disabled' : '',
+        isFocused ? 'data-focused' : '',
+        `tabindex="${isFocused ? '0' : '-1'}"`,
+      ].filter(Boolean).join(' ');
+
+      h += `<button ${attrs}>${d}</button>`;
+    }
+
+    // Next month leading days
+    const totalCells = firstDay + daysInMonth;
+    const remaining = (7 - (totalCells % 7)) % 7;
+    for (let d = 1; d <= remaining; d++) {
+      h += `<button type="button" data-cal-day data-outside disabled tabindex="-1">${d}</button>`;
+    }
+
+    h += '</div>';
+
+    this.#popover.innerHTML = h;
+    // Events are delegated on #popover (see #onPopoverClick) — no per-element wiring.
+  }
+
+  #navigate(delta) {
+    this.#viewMonth += delta;
+    if (this.#viewMonth > 11) { this.#viewMonth = 0; this.#viewYear++; }
+    if (this.#viewMonth < 0) { this.#viewMonth = 11; this.#viewYear--; }
+    this.#focusedDay = null;
+    this.#renderCalendar();
+  }
+
+  #selectDate(iso) {
+    this.value = iso;
+    this.syncValue(iso);
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+    // Re-render grid to reflect new selection; keep popover open until user clicks outside.
+    if (this.open) this.#renderCalendar();
+  }
+
+  #onClick = (e) => {
+    if (this.disabled) return;
+    if (this.#popover && e.composedPath().includes(this.#popover)) return;
+    this.open = !this.open;
+    if (this.open) {
+      const sel = parseISO(this.value);
+      if (sel) {
+        this.#viewYear = sel.getFullYear();
+        this.#viewMonth = sel.getMonth();
+        this.#focusedDay = sel.getDate();
+      } else {
+        const today = new Date();
+        this.#viewYear = today.getFullYear();
+        this.#viewMonth = today.getMonth();
+        this.#focusedDay = today.getDate();
+      }
+    }
+  };
+
+  #onOutside = (e) => {
+    if (!this.contains(e.target) && !(this.#popover && e.composedPath().includes(this.#popover))) {
+      this.open = false;
+    }
+  };
+
+  #onKey = (e) => {
+    if (!this.open) {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        this.open = true;
+      }
+      return;
+    }
+
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      this.open = false;
+      return;
+    }
+
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      if (this.#focusedDay) {
+        const iso = toISO(this.#viewYear, this.#viewMonth, this.#focusedDay);
+        const date = new Date(this.#viewYear, this.#viewMonth, this.#focusedDay);
+        const minDate = parseISO(this.min);
+        const maxDate = parseISO(this.max);
+        if ((!minDate || date >= minDate) && (!maxDate || date <= maxDate)) {
+          this.#selectDate(iso);
+        }
+      }
+      return;
+    }
+
+    const arrows = { ArrowUp: -7, ArrowDown: 7, ArrowLeft: -1, ArrowRight: 1 };
+    if (arrows[e.key] !== undefined) {
+      e.preventDefault();
+      const daysInMonth = new Date(this.#viewYear, this.#viewMonth + 1, 0).getDate();
+      let day = (this.#focusedDay || 1) + arrows[e.key];
+
+      if (day < 1) {
+        this.#navigate(-1);
+        const prevDays = new Date(this.#viewYear, this.#viewMonth + 1, 0).getDate();
+        this.#focusedDay = prevDays + day;
+      } else if (day > daysInMonth) {
+        this.#navigate(1);
+        this.#focusedDay = day - daysInMonth;
+      } else {
+        this.#focusedDay = day;
+      }
+
+      this.#renderCalendar();
+      const focused = this.#popover?.querySelector('[data-focused]');
+      focused?.focus();
+    }
+  };
+
+  disconnected() {
+    super.disconnected();
+    if (this.#openRaf != null) {
+      cancelAnimationFrame(this.#openRaf);
+      this.#openRaf = null;
+    }
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+    document.removeEventListener('pointerdown', this.#onOutside);
+    if (this.#popover && this.#popoverClickBound) {
+      this.#popover.removeEventListener('click', this.#onPopoverClick);
+    }
+    this.#popoverClickBound = false;
+    this.#anchorCleanup?.();
+    this.#anchorCleanup = null;
+    this.#popover?.hidePopover?.();
+    this.#popover = null;
+    this.#trigger = null;
+  }
+}

package/components/canvas/canvas.a2ui.json

@@ -29,6 +29,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "canvas-interaction": {
         "description": "Fired on canvas-interaction."
@@ -66,7 +67,12 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "tags": [
+        "render-surface",
+        "a2ui-host"
+      ]
+    },
     "tag": "canvas-ui",
     "tokens": {},
     "traits": [],

package/components/canvas/canvas.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `<canvas-ui>` — A2UI rendering surface.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/canvas
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 CanvasInteractionEvent = CustomEvent<unknown>;
+export type CanvasChangeEvent = CustomEvent<unknown>;
+export type CanvasClickEvent = CustomEvent<unknown>;
+export type CanvasInputEvent = CustomEvent<unknown>;
+
+export class UICanvas extends UIElement {
+  /** Component property: theme. */
+  theme: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UICanvas, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'canvas-interaction', listener: (ev: CanvasInteractionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: CanvasChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'click', listener: (ev: CanvasClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: CanvasInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/canvas/canvas.yaml

@@ -1,5 +1,3 @@
-# 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: UICanvas
 tag: canvas-ui
@@ -7,56 +5,51 @@ component: Canvas
 category: agent
 version: 1
 description: A2UI rendering surface.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+# NOTE: <canvas-ui> mounts <a2ui-root> (web-modules/runtime) and optionally
+# <theme-ui> (web-modules/theme). These are CROSS-PACKAGE compositions that
+# the current composes: field can't express as same-package siblings. Cross-
+# package composition tracking is queued for v0.4.9; for now consumers
+# loading <canvas-ui> with a2ui-root rendering must import:
+#   @adia-ai/web-modules/runtime/a2ui-root
+#   @adia-ai/web-modules/theme/theme  (only if [theme-wrapper] is used)
+composes: []
 props:
   theme:
-    description: "Component property: theme."
+    description: 'Component property: theme.'
     type: string
-    default: ""
+    default: ''
 events:
   canvas-interaction:
-    description: "Fired on canvas-interaction."
+    description: Fired on canvas-interaction.
   change:
-    description: "Fired when the value changes (on blur for inputs, on selection for pickers)."
+    description: Fired when the value changes (on blur for inputs, on selection for pickers).
   click:
-    description: "Fired on pointer click."
+    description: Fired on pointer click.
   input:
-    description: "Fired on each input change during typing."
+    description: Fired on each input change during typing.
 slots:
   default:
-    description: "Default slot — primary child content."
+    description: Default slot — primary child content.
 states:
-  - name: idle
-    description: Default, ready for interaction.
+- name: idle
+  description: Default, ready for interaction.
 traits: []
 tokens: {}
 a2ui:
   rules: []
 anti_patterns: []
 examples:
-  - name: basic-canvas
-    description: Basic Canvas usage
-    a2ui: >-
-      [
-        {
-          "id": "root",
-          "component": "Card",
-          "children": [
-            "sec"
-          ]
-        },
-        {
-          "id": "sec",
-          "component": "Section",
-          "children": [
-            "comp"
-          ]
-        },
-        {
-          "id": "comp",
-          "component": "Canvas"
-        }
-      ]
+- name: basic-canvas
+  description: Basic Canvas usage
+  a2ui: "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n\
+    \    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"comp\"\n    ]\n  },\n  {\n    \"\
+    id\": \"comp\",\n    \"component\": \"Canvas\"\n  }\n]"
 keywords:
-  - canvas
-synonyms: {}
+- canvas
+synonyms:
+  tags:
+  - render-surface
+  - a2ui-host
 related: []

package/components/card/card.a2ui.json

@@ -75,6 +75,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "drag-end": {
         "description": "Fired when a drag completes."
@@ -211,6 +212,9 @@
         "metric",
         "stat",
         "card"
+      ],
+      "tags": [
+        "ErrorContainer"
       ]
     },
     "tag": "card-ui",

package/components/card/card.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `<card-ui>` — Bordered container with header, body, and footer sections. The nested <header> activates a 3-column grid when any direct [slot="icon|heading|description|action"] child is present (icon column | heading + description stack | action column). Slot-gating uses :has(> [slot="…"]) (direct-child only) so a nested slot inside a composite child — e.g. <avatar-ui> owning an internal <icon-ui slot="icon"> — does not falsely activate the icon column. The nested <footer> flex-rows with a [slot="description"] + [slot="action"] space-between pattern; multiple <section> siblings stack as the body.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/card
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 CardDragEndEvent = CustomEvent<unknown>;
+
+export class UICard extends UIElement {
+  /** Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end. */
+  draggable: boolean;
+  /** Shadow depth 0-3 */
+  elevation: 0 | 1 | 2 | 3;
+  /** Interior padding scale (overrides --card-padding). Accepts the named scale (none/xs/sm/md/lg/xl) or a numeric rung ("1"…"16"). */
+  padding: string;
+  /** Strips background, border, and shadow. Parent owns the surface. Content structure still applies. */
+  raw: boolean;
+  /** Card scale. Controls inset, radius, gap, and font sizes. Default (empty) = md. */
+  size: 'sm' | 'md' | 'lg';
+  /** Visual style. `outline` is an alias for `outlined`; `flat` removes shadow; `soft`/`primary` apply tinted surfaces. */
+  variant: 'default' | 'outlined' | 'outline' | 'filled' | 'ghost' | 'flat' | 'soft' | 'primary';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UICard, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'drag-end', listener: (ev: CardDragEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/card/card.js

@@ -1,58 +1,17 @@
 /**
- * <card-ui> — Bordered container with header, body, and footer.
+ * `<card-ui>` — auto-registers the tag on import.
  *
- * Usage:
- *   <card-ui>
- *     <header>
- *       <span slot="heading">Title</span>
- *       <span slot="description">Subtitle text</span>
- *       <button-ui slot="action" variant="ghost" icon="dots-three"></button-ui>
- *     </header>
- *     <section>Body content</section>
- *     <footer>
- *       <span slot="description">Footer note</span>
- *       <button-ui slot="action" text="Save" variant="primary"></button-ui>
- *     </footer>
- *   </card-ui>
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Attributes:
- *   variant   — "default" | "outlined" | "filled" | "ghost"
- *   size      — "sm" | "md" | "lg" (controls padding + font scale)
- *   elevation — 0-3 (shadow depth)
- *   raw       — strips all chrome (border, bg, shadow, padding)
- *   draggable — enables drag handle + cursor:grab; wires the draggable trait
+ *   import { UICard } from '@adia-ai/web-components/components/card/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-import { draggable } from '../../traits/draggable/draggable.js';
-
-class UICard extends UIElement {
-  static properties = {
-    variant:   { type: String,  default: 'default', reflect: true },
-    size:      { type: String,  default: '',         reflect: true },
-    elevation: { type: Number,  default: 1,          reflect: true },
-    raw:       { type: Boolean, default: false,       reflect: true },
-    draggable: { type: Boolean, default: false,       reflect: true },
-  };
-
-  static template = () => null;
-
-  #dragAttached = false;
-
-  connected() {
-    if (this.draggable && !this.#dragAttached) {
-      this.addTrait(draggable);
-      this.#dragAttached = true;
-    }
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UICard } from './class.js';
 
-  updated(changed) {
-    if (changed.has('draggable') && this.draggable && !this.#dragAttached) {
-      this.addTrait(draggable);
-      this.#dragAttached = true;
-    }
-  }
-}
+defineIfFree('card-ui', UICard);
 
-customElements.define('card-ui', UICard);
 export { UICard };