@adia-ai/web-components 0.6.33 → 0.6.35

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

@@ -0,0 +1,326 @@
+/**
+ * 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 },
+    // Range-aware highlighting — when both rangeStart and rangeEnd are
+    // set, day cells whose date falls strictly between them get
+    // `[data-in-range]` stamped on them (the endpoints themselves get
+    // `[data-selected]` via the `value` prop). Consumers like
+    // <date-range-picker-ui> push the same from/to onto both panes so
+    // each independently lights up its in-range cells.
+    rangeStart: { type: String, default: '', reflect: true, attribute: 'range-start' },
+    rangeEnd:   { type: String, default: '', reflect: true, attribute: 'range-end' },
+  };
+
+  // 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);
+    // Range endpoints — only honor when BOTH are set + valid + ordered.
+    const rs = parseISO(this.rangeStart);
+    const re = parseISO(this.rangeEnd);
+    const rangeFrom = (rs && re && rs <= re) ? rs : null;
+    const rangeTo   = (rs && re && rs <= re) ? re : null;
+
+    // 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;
+      // In-range: strictly between rangeStart and rangeEnd (endpoints
+      // themselves render as `[data-selected]` via the `value` prop;
+      // marking them in-range too would double-up the styling).
+      const isInRange = !!(rangeFrom && rangeTo
+        && date > rangeFrom && date < rangeTo);
+      // Range endpoint flags — let CSS render the start/end cell with
+      // half-pill caps so the in-range strip reads as a continuous
+      // band when displayed next to the in-range cells.
+      const isRangeStart = !!(rangeFrom && sameDay(date, rangeFrom));
+      const isRangeEnd   = !!(rangeTo   && sameDay(date, rangeTo));
+
+      const attrs = [
+        'type="button"',
+        'data-cal-day',
+        `data-date="${iso}"`,
+        isToday      ? 'data-today' : '',
+        isSelected   ? 'data-selected' : '',
+        isInRange    ? 'data-in-range' : '',
+        isRangeStart ? 'data-range-start' : '',
+        isRangeEnd   ? 'data-range-end' : '',
+        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;
+    }
+  };
+}

package/components/calendar-grid/calendar-grid.css

@@ -0,0 +1,246 @@
+/* ============================================================
+   <calendar-grid-ui> — Inline single-month calendar grid.
+
+   Substrate primitive consumed by calendar-picker-ui (popover
+   wrapper), date-range-picker-ui (two side-by-side grids), and
+   datetime-picker-ui (one grid + time pane).
+
+   Two-block @scope per docs/specs/component-token-contract.md.
+   Tokens mirror calendar-picker-ui's grid tokens (same surface,
+   shared visual language) so consumers can override either
+   --calendar-grid-* OR --calendar-picker-* and pick up the same
+   look-and-feel through cascade.
+   ============================================================ */
+
+@scope (calendar-grid-ui) {
+  /* ── Block 1 — TOKENS ── */
+  :where(:scope) {
+    /* Layout */
+    --calendar-grid-gap-default:                var(--a-space-1);
+    --calendar-grid-width-default:              16rem;
+
+    /* Header */
+    --calendar-grid-header-gap-default:         var(--a-space-1);
+    --calendar-grid-header-mb-default:          var(--a-space-2);
+    --calendar-grid-title-fg-default:           var(--a-fg);
+    --calendar-grid-title-size-default:         var(--a-ui-size);
+    --calendar-grid-title-weight-default:       var(--a-weight-medium);
+
+    /* Nav buttons (prev/next) */
+    --calendar-grid-nav-size-default:           1.5rem;
+    --calendar-grid-nav-radius-default:         var(--a-radius-sm);
+    --calendar-grid-nav-bg-default:             transparent;
+    --calendar-grid-nav-bg-hover-default:       var(--a-bg-muted);
+    --calendar-grid-nav-fg-default:             var(--a-fg-muted);
+    --calendar-grid-nav-fg-hover-default:       var(--a-fg);
+    --calendar-grid-nav-icon-size-default:      0.75rem;
+
+    /* Weekday header */
+    --calendar-grid-weekday-fg-default:         var(--a-fg-muted);
+    --calendar-grid-weekday-size-default:       var(--a-ui-sm);
+    --calendar-grid-weekday-weight-default:     var(--a-weight-medium);
+    --calendar-grid-weekday-height-default:     1.5rem;
+    --calendar-grid-weekday-mb-default:         var(--a-space-1);
+
+    /* Day cells */
+    --calendar-grid-day-size-default:           2rem;
+    --calendar-grid-day-radius-default:         var(--a-radius);
+    --calendar-grid-day-font-size-default:      var(--a-ui-sm);
+    --calendar-grid-day-bg-default:             transparent;
+    --calendar-grid-day-fg-default:             var(--a-fg-subtle);
+    --calendar-grid-day-bg-hover-default:       var(--a-bg-hover);
+    --calendar-grid-day-fg-hover-default:       var(--a-fg);
+    --calendar-grid-day-bg-selected-default:    var(--a-accent);
+    --calendar-grid-day-fg-selected-default:    var(--a-accent-fg);
+    /* In-range cells (strictly between rangeStart and rangeEnd) — muted
+       accent strip so the endpoints (full --a-accent fill) read as the
+       primary selection while the in-range band reads as secondary
+       context. Stylable independently of `selected`. */
+    --calendar-grid-day-bg-in-range-default:    var(--a-accent-muted);
+    --calendar-grid-day-fg-in-range-default:    var(--a-fg);
+    --calendar-grid-day-fg-outside-default:     var(--a-fg-muted);
+    --calendar-grid-day-fg-disabled-default:    var(--a-ui-text-disabled);
+    --calendar-grid-day-today-color-default:    var(--a-accent);
+    --calendar-grid-day-today-dot-size-default: var(--a-space-0-5);
+    --calendar-grid-day-today-dot-offset-default: var(--a-space-1);
+    --calendar-grid-day-grid-gap-default:       var(--a-space-px);
+    --calendar-grid-day-focus-ring-default:     var(--a-focus-ring);
+
+    /* Transitions */
+    --calendar-grid-duration-default:           var(--a-duration-fast);
+    --calendar-grid-easing-default:             var(--a-easing);
+
+    /* Typography */
+    --calendar-grid-selected-weight-default:    var(--a-weight-medium);
+    --calendar-grid-today-weight-default:       var(--a-weight-medium);
+  }
+
+  /* ── Block 2 — BASE ── */
+  :scope {
+    box-sizing: border-box;
+    display: block;
+    width: var(--calendar-grid-width, var(--calendar-grid-width-default));
+    font-size: var(--calendar-grid-day-font-size, var(--calendar-grid-day-font-size-default));
+  }
+
+  :scope[disabled] {
+    pointer-events: none;
+    opacity: 0.5;
+  }
+
+  /* Header row */
+  [data-cal-header] {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--calendar-grid-header-gap, var(--calendar-grid-header-gap-default));
+    margin-block-end: var(--calendar-grid-header-mb, var(--calendar-grid-header-mb-default));
+  }
+
+  [data-cal-title] {
+    flex: 1;
+    text-align: center;
+    font-size: var(--calendar-grid-title-size, var(--calendar-grid-title-size-default));
+    font-weight: var(--calendar-grid-title-weight, var(--calendar-grid-title-weight-default));
+    color: var(--calendar-grid-title-fg, var(--calendar-grid-title-fg-default));
+  }
+
+  [data-cal-prev],
+  [data-cal-next] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--calendar-grid-nav-size, var(--calendar-grid-nav-size-default));
+    height: var(--calendar-grid-nav-size, var(--calendar-grid-nav-size-default));
+    padding: 0;
+    border: none;
+    border-radius: var(--calendar-grid-nav-radius, var(--calendar-grid-nav-radius-default));
+    background: var(--calendar-grid-nav-bg, var(--calendar-grid-nav-bg-default));
+    color: var(--calendar-grid-nav-fg, var(--calendar-grid-nav-fg-default));
+    cursor: pointer;
+    transition:
+      background var(--calendar-grid-duration, var(--calendar-grid-duration-default)) var(--calendar-grid-easing, var(--calendar-grid-easing-default)),
+      color      var(--calendar-grid-duration, var(--calendar-grid-duration-default)) var(--calendar-grid-easing, var(--calendar-grid-easing-default));
+    --a-icon-size: var(--calendar-grid-nav-icon-size, var(--calendar-grid-nav-icon-size-default));
+  }
+  [data-cal-prev]:hover,
+  [data-cal-next]:hover {
+    background: var(--calendar-grid-nav-bg-hover, var(--calendar-grid-nav-bg-hover-default));
+    color: var(--calendar-grid-nav-fg-hover, var(--calendar-grid-nav-fg-hover-default));
+  }
+
+  /* Day-of-week header */
+  [data-cal-weekdays] {
+    display: grid;
+    grid-template-columns: repeat(7, 1fr);
+    text-align: center;
+    font-size: var(--calendar-grid-weekday-size, var(--calendar-grid-weekday-size-default));
+    font-weight: var(--calendar-grid-weekday-weight, var(--calendar-grid-weekday-weight-default));
+    color: var(--calendar-grid-weekday-fg, var(--calendar-grid-weekday-fg-default));
+    margin-block-end: var(--calendar-grid-weekday-mb, var(--calendar-grid-weekday-mb-default));
+  }
+
+  [data-cal-weekdays] span {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: var(--calendar-grid-weekday-height, var(--calendar-grid-weekday-height-default));
+  }
+
+  /* Day grid */
+  [data-cal-grid] {
+    display: grid;
+    grid-template-columns: repeat(7, 1fr);
+    gap: var(--calendar-grid-day-grid-gap, var(--calendar-grid-day-grid-gap-default));
+  }
+
+  [data-cal-day] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--calendar-grid-day-size, var(--calendar-grid-day-size-default));
+    height: var(--calendar-grid-day-size, var(--calendar-grid-day-size-default));
+    margin: 0 auto;
+    padding: 0;
+    border: 1px solid transparent;
+    border-radius: var(--calendar-grid-day-radius, var(--calendar-grid-day-radius-default));
+    background: var(--calendar-grid-day-bg, var(--calendar-grid-day-bg-default));
+    color: var(--calendar-grid-day-fg, var(--calendar-grid-day-fg-default));
+    font: inherit;
+    font-size: var(--calendar-grid-day-font-size, var(--calendar-grid-day-font-size-default));
+    cursor: pointer;
+    transition:
+      background var(--calendar-grid-duration, var(--calendar-grid-duration-default)) var(--calendar-grid-easing, var(--calendar-grid-easing-default)),
+      color      var(--calendar-grid-duration, var(--calendar-grid-duration-default)) var(--calendar-grid-easing, var(--calendar-grid-easing-default)),
+      border-color var(--calendar-grid-duration, var(--calendar-grid-duration-default)) var(--calendar-grid-easing, var(--calendar-grid-easing-default));
+  }
+
+  /* ── State: hover ── */
+  [data-cal-day]:not([disabled]):not([data-outside]):hover {
+    background: var(--calendar-grid-day-bg-hover, var(--calendar-grid-day-bg-hover-default));
+    color: var(--calendar-grid-day-fg-hover, var(--calendar-grid-day-fg-hover-default));
+  }
+
+  /* ── State: focus ── */
+  [data-cal-day]:not([disabled]):not([data-outside]):focus-visible,
+  [data-cal-day][data-focused] {
+    outline: none;
+    box-shadow: var(--calendar-grid-day-focus-ring, var(--calendar-grid-day-focus-ring-default));
+  }
+
+  /* ── State: selected ── */
+  [data-cal-day][data-selected] {
+    background: var(--calendar-grid-day-bg-selected, var(--calendar-grid-day-bg-selected-default));
+    color: var(--calendar-grid-day-fg-selected, var(--calendar-grid-day-fg-selected-default));
+    font-weight: var(--calendar-grid-selected-weight, var(--calendar-grid-selected-weight-default));
+  }
+  [data-cal-day][data-selected]:not([disabled]):hover {
+    background: var(--calendar-grid-day-bg-selected, var(--calendar-grid-day-bg-selected-default));
+    color: var(--calendar-grid-day-fg-selected, var(--calendar-grid-day-fg-selected-default));
+  }
+
+  /* ── State: in-range ──
+     Cells strictly between rangeStart and rangeEnd get the muted accent
+     strip. Endpoints themselves render as `[data-selected]` (full accent
+     fill); the in-range middle is visually subordinate. `:not([data-selected])`
+     guard prevents the muted fill from overriding the endpoint cells in
+     consumer code that sets both `value` AND `range-start`/`range-end`. */
+  [data-cal-day][data-in-range]:not([data-selected]) {
+    background: var(--calendar-grid-day-bg-in-range, var(--calendar-grid-day-bg-in-range-default));
+    color: var(--calendar-grid-day-fg-in-range, var(--calendar-grid-day-fg-in-range-default));
+  }
+  [data-cal-day][data-in-range]:not([data-selected]):not([disabled]):hover {
+    background: var(--calendar-grid-day-bg-in-range, var(--calendar-grid-day-bg-in-range-default));
+  }
+
+  /* ── State: today (unselected) ── */
+  [data-cal-day][data-today]:not([data-selected]) {
+    position: relative;
+    color: var(--calendar-grid-day-today-color, var(--calendar-grid-day-today-color-default));
+    font-weight: var(--calendar-grid-today-weight, var(--calendar-grid-today-weight-default));
+  }
+  [data-cal-day][data-today]:not([data-selected])::after {
+    content: "";
+    position: absolute;
+    left: 50%;
+    bottom: var(--calendar-grid-day-today-dot-offset, var(--calendar-grid-day-today-dot-offset-default));
+    width: var(--calendar-grid-day-today-dot-size, var(--calendar-grid-day-today-dot-size-default));
+    height: var(--calendar-grid-day-today-dot-size, var(--calendar-grid-day-today-dot-size-default));
+    border-radius: 50%;
+    background: var(--calendar-grid-day-today-color, var(--calendar-grid-day-today-color-default));
+    transform: translateX(-50%);
+    pointer-events: none;
+  }
+
+  /* ── State: outside month ── */
+  [data-cal-day][data-outside] {
+    color: var(--calendar-grid-day-fg-outside, var(--calendar-grid-day-fg-outside-default));
+    cursor: default;
+  }
+
+  /* ── State: disabled (excluding outside) ── */
+  [data-cal-day]:disabled:not([data-outside]) {
+    color: var(--calendar-grid-day-fg-disabled, var(--calendar-grid-day-fg-disabled-default));
+    cursor: not-allowed;
+  }
+}

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

@@ -0,0 +1,41 @@
+/**
+ * `<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;
+  /** End of a date range (ISO YYYY-MM-DD). See `rangeStart` for the full contract. */
+  rangeEnd: string;
+  /** Start of a date range (ISO YYYY-MM-DD). When both rangeStart and rangeEnd are set + ordered, day cells strictly between the endpoints get `[data-in-range]` stamped for visual continuity. Used by `<date-range-picker-ui>` which pushes the same from/to onto both calendar panes. Endpoints themselves render via the `value` prop's `[data-selected]` state. */
+  rangeStart: 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 './calendar-grid.class.js';
+
+defineIfFree('calendar-grid-ui', UICalendarGrid);
+
+export { UICalendarGrid };