@adia-ai/web-components 0.6.32 → 0.6.34

package/components/calendar-grid/calendar-grid.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `<calendar-grid-ui>` — Substrate primitive — a single-month calendar grid (month nav + day cells + keyboard nav). Renders inline; no trigger, no popover. Used as a substrate by calendar-picker-ui (popover wrapper), date-range-picker-ui (two side-by-side grids), and datetime-picker-ui (one grid + time pane). For a complete date-picker affordance (trigger + popover + form participation), use calendar-picker-ui.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/calendar-grid
+ *
+ * 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 CalendarGridChangeEvent = CustomEvent<unknown>;
+export type CalendarGridInputEvent = CustomEvent<unknown>;
+
+export class UICalendarGrid extends UIElement {
+  /** Disables all interaction. */
+  disabled: boolean;
+  /** Maximum selectable date in ISO format (YYYY-MM-DD). */
+  max: string;
+  /** Minimum selectable date in ISO format (YYYY-MM-DD). */
+  min: string;
+  /** Blocks selection but allows month navigation. */
+  readonly: boolean;
+  /** Selected date in ISO format (YYYY-MM-DD). */
+  value: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UICalendarGrid, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: CalendarGridChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: CalendarGridInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/calendar-grid/calendar-grid.js

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

package/components/calendar-grid/calendar-grid.yaml

@@ -0,0 +1,116 @@
+# Hand-authored substrate primitive — the inline calendar grid extracted
+# from calendar-picker-ui so date-range-picker-ui + datetime-picker-ui can
+# compose JUST the grid (no trigger, no popover). Edit this file; run
+# `npm run components` to regenerate calendar-grid.a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UICalendarGrid
+tag: calendar-grid-ui
+status: stable
+component: CalendarGrid
+category: input
+version: 1
+description: >-
+  Substrate primitive — a single-month calendar grid (month nav + day
+  cells + keyboard nav). Renders inline; no trigger, no popover. Used as
+  a substrate by calendar-picker-ui (popover wrapper), date-range-picker-ui
+  (two side-by-side grids), and datetime-picker-ui (one grid + time pane).
+  For a complete date-picker affordance (trigger + popover + form
+  participation), use calendar-picker-ui.
+props:
+  value:
+    description: Selected date in ISO format (YYYY-MM-DD).
+    type: string
+    default: ''
+    reflect: true
+  min:
+    description: Minimum selectable date in ISO format (YYYY-MM-DD).
+    type: string
+    default: ''
+    reflect: true
+  max:
+    description: Maximum selectable date in ISO format (YYYY-MM-DD).
+    type: string
+    default: ''
+    reflect: true
+  disabled:
+    description: Disables all interaction.
+    type: boolean
+    default: false
+    reflect: true
+  readonly:
+    description: Blocks selection but allows month navigation.
+    type: boolean
+    default: false
+    reflect: true
+events:
+  change:
+    description: User selected a date. detail.value is the ISO string.
+  input:
+    description: Focus moved between days during keyboard nav. detail.focusDate is the ISO string.
+slots: {}
+states:
+  - name: disabled
+    description: Pointer-events off, reduced opacity, no selection.
+    attribute: disabled
+  - name: readonly
+    description: Navigation allowed, selection blocked.
+    attribute: readonly
+traits: []
+tokens:
+  --calendar-grid-width:
+    description: Grid container width.
+    default: 16rem
+  --calendar-grid-day-size:
+    description: Square cell size for day buttons.
+    default: 2rem
+  --calendar-grid-day-bg-selected:
+    description: Background of the selected day cell.
+    default: var(--a-accent)
+  --calendar-grid-day-fg-selected:
+    description: Text color of the selected day cell.
+    default: var(--a-accent-fg)
+  --calendar-grid-day-bg-hover:
+    description: Background on hover (non-selected, non-outside, non-disabled).
+    default: var(--a-bg-hover)
+  --calendar-grid-day-today-color:
+    description: Accent color used for the today-indicator dot + numeral tint.
+    default: var(--a-accent)
+a2ui:
+  rules:
+    - >-
+      Use <CalendarGrid> only as a substrate primitive composed inside a
+      higher-level component (date-range picker, datetime picker, custom
+      date affordance). For a full single-date input, use
+      <CalendarPicker> — it adds a trigger button, popover surface, and
+      form-association.
+    - >-
+      <CalendarGrid> is NOT form-associated. Its emitted `change` event
+      is the sole signal to the parent — the parent owns the canonical
+      value + form participation.
+anti_patterns:
+  - wrong: |
+      {"component": "CalendarGrid", "name": "birthdate"}
+    why: |
+      CalendarGrid is a substrate primitive — it does not participate in
+      forms. The `name` attribute has no effect. Use CalendarPicker
+      (form-associated) for single-date input.
+    fix: |
+      {"component": "CalendarPicker", "name": "birthdate"}
+keywords:
+  - calendar
+  - date
+  - grid
+  - month
+  - day-picker
+  - substrate
+synonyms:
+  calendar:
+    - calendar
+    - date
+  grid:
+    - grid
+    - calendar
+related:
+  - CalendarPicker
+  - DateRangePicker
+  - DatetimePicker

package/components/calendar-grid/class.js

@@ -0,0 +1,300 @@
+/**
+ * Non-side-effect class export for `<calendar-grid-ui>`.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/calendar-grid`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * `<calendar-grid-ui>` — Substrate primitive: a single-month calendar grid.
+ *
+ * Renders ONLY the inline grid (month nav + day-cells + keyboard nav). No
+ * trigger, no popover — used as a substrate by <calendar-picker-ui> (trigger
+ * + popover wrapper), <date-range-picker-ui> (two side-by-side grids), and
+ * <datetime-picker-ui> (one grid + time pane).
+ *
+ *   <calendar-grid-ui value="2026-05-23" min="2026-01-01" max="2026-12-31">
+ *   </calendar-grid-ui>
+ *
+ * Properties:
+ *   value — selected ISO date (YYYY-MM-DD)
+ *   min   — minimum selectable date (ISO)
+ *   max   — maximum selectable date (ISO)
+ *   focus-date — the date that holds the roving tabindex (ISO, defaults to value or today)
+ *   disabled / readonly — disables / blocks selection
+ *
+ * Events:
+ *   change — { value: "2026-05-23" } when a date is selected
+ *   input  — emitted as the user navigates without committing
+ *
+ * Keyboard: ArrowUp/Down/Left/Right navigate days; Enter selects;
+ *   PageUp/Down jump month; Home/End first/last of month.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+const DAYS = ['S', 'M', 'T', 'W', 'T', 'F', 'S'];
+const MONTHS_LONG = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+];
+
+function pad(n) { return String(n).padStart(2, '0'); }
+function toISO(y, m, d) { return `${y}-${pad(m + 1)}-${pad(d)}`; }
+function parseISO(str) {
+  if (!str) return null;
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(str).trim());
+  if (!m) return null;
+  return new Date(+m[1], +m[2] - 1, +m[3]);
+}
+function sameDay(a, b) {
+  return a.getFullYear() === b.getFullYear()
+      && a.getMonth()    === b.getMonth()
+      && a.getDate()     === b.getDate();
+}
+
+export class UICalendarGrid extends UIElement {
+  // §154 Phosphor icons stamped without consumer markup.
+  static requiredIcons = ['caret-left', 'caret-right'];
+
+  static properties = {
+    value:    { type: String,  default: '', reflect: true },
+    min:      { type: String,  default: '', reflect: true },
+    max:      { type: String,  default: '', reflect: true },
+    disabled: { type: Boolean, default: false, reflect: true },
+    readonly: { type: Boolean, default: false, reflect: true },
+  };
+
+  // No html`` template — we render imperatively via #renderCalendar so we can
+  // mutate per-day cells without diffing.
+  static template = () => null;
+
+  #viewYear = new Date().getFullYear();
+  #viewMonth = new Date().getMonth();
+  #focusedDay = null;
+  #bound = false;
+
+  // ── Lifecycle ──────────────────────────────────────────────────────
+
+  connected() {
+    this.setAttribute('role', 'group');
+    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Calendar');
+
+    // Initialize view to selected date or today.
+    const sel = parseISO(this.value);
+    if (sel) {
+      this.#viewYear = sel.getFullYear();
+      this.#viewMonth = sel.getMonth();
+    }
+
+    if (!this.#bound) {
+      this.#bound = true;
+      this.addEventListener('click', this.#onClick);
+      this.addEventListener('keydown', this.#onKey);
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+    this.#bound = false;
+  }
+
+  render() {
+    // If a selected value changed externally, re-sync the visible month so it
+    // contains the selection (without clobbering the user's mid-flight nav).
+    const sel = parseISO(this.value);
+    if (sel && (sel.getFullYear() !== this.#viewYear || sel.getMonth() !== this.#viewMonth)) {
+      this.#viewYear = sel.getFullYear();
+      this.#viewMonth = sel.getMonth();
+    }
+    this.#renderCalendar();
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────
+
+  /** Move the visible month by ±N months. */
+  navigate(delta) {
+    this.#viewMonth += delta;
+    while (this.#viewMonth > 11) { this.#viewMonth -= 12; this.#viewYear++; }
+    while (this.#viewMonth < 0)  { this.#viewMonth += 12; this.#viewYear--; }
+    this.#focusedDay = null;
+    this.#renderCalendar();
+  }
+
+  /** Programmatically focus a day (1-based) inside the visible month. */
+  focusDay(day) {
+    const daysInMonth = new Date(this.#viewYear, this.#viewMonth + 1, 0).getDate();
+    if (day < 1 || day > daysInMonth) return;
+    this.#focusedDay = day;
+    this.#renderCalendar();
+    this.querySelector('[data-cal-day][data-focused]')?.focus?.();
+  }
+
+  // ── Internal — render the grid ────────────────────────────────────
+
+  #renderCalendar() {
+    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 — Prev / Title / Next
+    let h = `<div data-cal-header>
+      <button data-cal-prev type="button" aria-label="Previous month" tabindex="-1"><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" tabindex="-1"><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>`;
+
+    // Day 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 (outside, disabled)
+    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.innerHTML = h;
+  }
+
+  // ── Selection ─────────────────────────────────────────────────────
+
+  #selectDate(iso) {
+    if (this.disabled || this.readonly) return;
+    this.value = iso;
+    // Re-render to reflect new selection.
+    this.#renderCalendar();
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value: iso },
+    }));
+  }
+
+  // ── Event handlers ────────────────────────────────────────────────
+
+  #onClick = (e) => {
+    if (this.disabled) return;
+    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); }
+  };
+
+  #onKey = (e) => {
+    if (this.disabled) return;
+
+    if (e.key === 'Enter' || e.key === ' ') {
+      if (this.#focusedDay) {
+        e.preventDefault();
+        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.querySelector('[data-cal-day][data-focused]');
+      focused?.focus?.();
+      this.dispatchEvent(new CustomEvent('input', {
+        bubbles: true,
+        detail: { focusDate: toISO(this.#viewYear, this.#viewMonth, this.#focusedDay) },
+      }));
+      return;
+    }
+
+    if (e.key === 'PageUp') {
+      e.preventDefault();
+      this.navigate(-1);
+      return;
+    }
+    if (e.key === 'PageDown') {
+      e.preventDefault();
+      this.navigate(1);
+      return;
+    }
+    if (e.key === 'Home') {
+      e.preventDefault();
+      this.#focusedDay = 1;
+      this.#renderCalendar();
+      this.querySelector('[data-cal-day][data-focused]')?.focus?.();
+      return;
+    }
+    if (e.key === 'End') {
+      e.preventDefault();
+      this.#focusedDay = new Date(this.#viewYear, this.#viewMonth + 1, 0).getDate();
+      this.#renderCalendar();
+      this.querySelector('[data-cal-day][data-focused]')?.focus?.();
+      return;
+    }
+  };
+}