@adia-ai/web-components 0.6.33 → 0.6.35

package/components/datetime-picker/datetime-picker.css

@@ -0,0 +1,150 @@
+/* ============================================================
+   datetime-picker — two-block @scope per ADR-0003.
+   Block 1 (TOKENS): :where(:scope) — token defaults.
+   Block 2 (BASE): :scope + descendant selectors.
+   Popover surfaces live OUTSIDE @scope because the Popover API
+   lifts them into the top layer; custom-property inheritance
+   still cascades from the host so --datetime-picker-* tokens
+   reach the popover.
+   ============================================================ */
+
+@scope (datetime-picker-ui) {
+  /* ── Block 1 — TOKENS ── */
+  :where(:scope) {
+    --datetime-picker-bg-default:                  var(--a-bg);
+    --datetime-picker-fg-default:                  var(--a-fg);
+
+    /* Popover surface */
+    --datetime-picker-popover-bg-default:          var(--a-bg-subtle);
+    --datetime-picker-popover-border-default:      var(--a-border-subtle);
+    --datetime-picker-popover-radius-default:      var(--a-radius-lg);
+    --datetime-picker-popover-shadow-default:      var(--a-shadow-lg);
+    --datetime-picker-popover-padding-default:     var(--a-space-3);
+    --datetime-picker-popover-gap-default:         var(--a-space-3);
+
+    /* Pane divider */
+    --datetime-picker-divider-default:             var(--a-border-subtle);
+
+    /* Trigger */
+    --datetime-picker-trigger-min-width-default:   16em;
+
+    /* Padding */
+    --datetime-picker-px-default:                  var(--a-space-3);
+    --datetime-picker-py-default:                  var(--a-space-2);
+
+    /* Motion */
+    --datetime-picker-duration-default:            var(--a-duration-fast);
+    --datetime-picker-easing-default:              var(--a-easing);
+  }
+
+  /* ── Block 2 — BASE ── */
+  :scope {
+    box-sizing: border-box;
+    position: relative;
+    display: inline-block;
+    background: var(--datetime-picker-bg, var(--datetime-picker-bg-default));
+    color: var(--datetime-picker-fg, var(--datetime-picker-fg-default));
+    font-size: var(--a-ui-size);
+  }
+
+  /* Default trigger sizing — composes button-ui's surface; just
+     stretches the min-width so "Jan 1, 2026 14:30" fits. */
+  :scope > [slot="trigger"] {
+    min-width: var(--datetime-picker-trigger-min-width, var(--datetime-picker-trigger-min-width-default));
+  }
+
+  /* States */
+  :scope[disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+  :scope[readonly] > [slot="trigger"] {
+    cursor: default;
+  }
+}
+
+/* ============================================================
+   Popover surface — outside @scope (lifted to top layer).
+   Custom properties inherit from the host so
+   --datetime-picker-* tokens are available here.
+   ============================================================ */
+
+/* §FB-Wave1-QA — `display: grid` MUST be guarded by `:popover-open` so the
+   popover honors the UA `popover` `display: none` while closed. */
+datetime-picker-ui [slot="popover"] {
+  margin: 0;
+  padding: var(--datetime-picker-py, var(--datetime-picker-py-default)) var(--datetime-picker-px, var(--datetime-picker-px-default));
+  border: 1px solid var(--datetime-picker-popover-border, var(--datetime-picker-popover-border-default));
+  border-radius: var(--datetime-picker-popover-radius, var(--datetime-picker-popover-radius-default));
+  background: var(--datetime-picker-popover-bg, var(--datetime-picker-popover-bg-default));
+  box-shadow: var(--datetime-picker-popover-shadow, var(--datetime-picker-popover-shadow-default));
+  color: var(--a-fg);
+  /* Anchor-positioning fallback — popover.css and anchor.js handle
+     placement; layout here just sets the grid. */
+  inset: auto;
+  /* Fade + lift in on first paint via @starting-style. */
+  opacity: 1;
+  translate: 0 0;
+  transition:
+    opacity var(--datetime-picker-duration, var(--datetime-picker-duration-default)) var(--datetime-picker-easing, var(--datetime-picker-easing-default)),
+    translate var(--datetime-picker-duration, var(--datetime-picker-duration-default)) var(--datetime-picker-easing, var(--datetime-picker-easing-default));
+}
+
+datetime-picker-ui [slot="popover"]:popover-open {
+  display: grid;
+  grid-template-columns: auto auto auto;
+  grid-template-areas: "cal divider time";
+  gap: var(--datetime-picker-popover-gap, var(--datetime-picker-popover-gap-default));
+  align-items: start;
+}
+
+datetime-picker-ui [slot="popover"]:popover-open {
+  @starting-style {
+    opacity: 0;
+    translate: 0 -4px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  datetime-picker-ui [slot="popover"] { transition: none; }
+}
+
+/* Pane areas. */
+datetime-picker-ui [slot="popover"] > [data-cal-pane] {
+  grid-area: cal;
+}
+datetime-picker-ui [slot="popover"] > [data-pane-divider] {
+  grid-area: divider;
+  align-self: stretch;
+  --divider-color: var(--datetime-picker-divider, var(--datetime-picker-divider-default));
+}
+datetime-picker-ui [slot="popover"] > [data-time-pane] {
+  grid-area: time;
+  align-self: start;
+}
+
+/* Footer area (consumer-supplied [slot="footer"]) — spans all three
+   columns under the panes. */
+datetime-picker-ui [slot="popover"] > [slot="footer"] {
+  grid-column: 1 / -1;
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--a-space-2);
+  padding-block-start: var(--a-space-2);
+  border-block-start: 1px solid var(--a-border-subtle);
+}
+
+/* Narrow surfaces (e.g. inside a card on mobile): stack the panes
+   vertically and replace the vertical divider with a horizontal rule. */
+@container (max-width: 32rem) {
+  datetime-picker-ui [slot="popover"]:popover-open {
+    grid-template-columns: 1fr;
+    grid-template-areas:
+      "cal"
+      "divider"
+      "time";
+  }
+  datetime-picker-ui [slot="popover"] > [data-pane-divider] {
+    align-self: auto;
+  }
+}

package/components/datetime-picker/datetime-picker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `<datetime-picker-ui>` — Single-control date + time selection. Trigger button opens a popover with a `<calendar-picker-ui>` on the left + a `<time-picker-ui>` on the right; commit emits a full ISO 8601 datetime string ("YYYY-MM-DDTHH:mm" or with seconds). Composes the two underlying primitives — never wraps a native `<input type="datetime-local">` (per ADR-0025). Form-associated under one `name`. SPEC-038.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/datetime-picker
+ *
+ * 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 interface DatetimePickerChangeEventDetail {
+  source: string;
+  value: string;
+}
+
+export type DatetimePickerChangeEvent = CustomEvent<DatetimePickerChangeEventDetail>;
+export interface DatetimePickerCloseEventDetail {
+  reason: string;
+}
+
+export type DatetimePickerCloseEvent = CustomEvent<DatetimePickerCloseEventDetail>;
+export interface DatetimePickerInputEventDetail {
+  value: string;
+}
+
+export type DatetimePickerInputEvent = CustomEvent<DatetimePickerInputEventDetail>;
+export interface DatetimePickerInvalidEventDetail {
+  reason: string;
+  value: string;
+}
+
+export type DatetimePickerInvalidEvent = CustomEvent<DatetimePickerInvalidEventDetail>;
+export interface DatetimePickerOpenEventDetail {
+  trigger: string;
+}
+
+export type DatetimePickerOpenEvent = CustomEvent<DatetimePickerOpenEventDetail>;
+
+export class UIDatetimePicker extends UIElement {
+  /** Required for validation when inside a `<form>`. */
+  required: boolean;
+  /** Block all interaction. Trigger remains rendered but does not open the popover. */
+  disabled: boolean;
+  /** Trigger button date format. `short`: `Jan 1, 2026 14:30`; `long`: `January 1, 2026 14:30`; `iso`: full ISO string. */
+  format: 'short' | 'long' | 'iso';
+  /** Hour cycle for the time pane. Empty (default) derives from the
+document locale. `h12` forces a 12-hour cycle with an AM/PM
+(meridiem) segment; `h23` forces 24-hour cycle.
+ */
+  hourcycle: '' | 'h12' | 'h23';
+  /** BCP-47 locale tag used to derive hour-cycle when `hour-cycle` is empty. Falls back to `<html lang>` then to browser default. */
+  locale: string;
+  /** Latest selectable ISO 8601 datetime (inclusive). Days after are disabled in the calendar pane; times after are rejected by the time pane on the same day. */
+  max: string;
+  /** Earliest selectable ISO 8601 datetime (inclusive). Days before are disabled in the calendar pane; times before are rejected by the time pane on the same day. */
+  min: string;
+  /** Form field name. The ISO 8601 datetime is submitted under this key when the picker is inside a `<form>`. */
+  name: string;
+  /** Whether the popover is currently open. */
+  open: boolean;
+  /** Text shown in the trigger when the value is empty. */
+  placeholder: string;
+  /** Time-pane precision. `minute` (default) emits `HH:mm`; `second` exposes the seconds segment and emits `HH:mm:ss`. */
+  precision: 'minute' | 'second';
+  /** Block edits; allow keyboard navigation for screen-reader inspection. */
+  readonly: boolean;
+  /** Per-Arrow-keypress increment in seconds for the time pane. 60 = minute precision (default), 900 = 15-minute, 1 = second precision. */
+  step: number;
+  /** Current value as ISO 8601 datetime ("YYYY-MM-DDTHH:mm" or "YYYY-MM-DDTHH:mm:ss"). Empty when no value selected. */
+  value: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIDatetimePicker, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: DatetimePickerChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'close', listener: (ev: DatetimePickerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: DatetimePickerInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'invalid', listener: (ev: DatetimePickerInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'open', listener: (ev: DatetimePickerOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/datetime-picker/datetime-picker.examples.md

@@ -0,0 +1,46 @@
+# datetime-picker — Examples
+
+## Canonical
+
+```html
+<field-ui label="Appointment">
+  <datetime-picker-ui
+    name="appointment"
+    min="2026-01-01T00:00"
+    max="2026-12-31T23:59">
+  </datetime-picker-ui>
+</field-ui>
+```
+
+## Second precision
+
+```html
+<datetime-picker-ui
+  precision="second"
+  step="1"
+  value="2026-05-24T14:30:45">
+</datetime-picker-ui>
+```
+
+## Forced 24-hour cycle
+
+```html
+<datetime-picker-ui hour-cycle="h23"></datetime-picker-ui>
+```
+
+## Explicit commit (Apply / Cancel)
+
+```html
+<datetime-picker-ui name="explicit">
+  <div slot="footer">
+    <button-ui data-action="cancel" variant="ghost" text="Cancel"></button-ui>
+    <button-ui data-action="apply" variant="primary" text="Apply"></button-ui>
+  </div>
+</datetime-picker-ui>
+```
+
+## Readonly
+
+```html
+<datetime-picker-ui readonly value="2026-05-24T14:30"></datetime-picker-ui>
+```

package/components/datetime-picker/datetime-picker.js

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