@zeyos/zx 2.1.0 → 2.2.0

package/src/components/date-picker/field-adapter.js

@@ -0,0 +1,36 @@
+import { Field } from '../field/field.js';
+import { MonthPicker } from './month-picker.js';
+
+/**
+ * Registers the MonthPicker-backed `month` field type. Date and datetime fields are registered
+ * by the Datebox adapter so those types retain formatted text-input behavior.
+ * @returns {void}
+ */
+export function registerDatePickerFieldAdapters() {
+  Field.register('month', (field, options) => {
+    const picker = field.own(new MonthPicker(null, {
+      ...(options.props ?? {}),
+      value: options.value
+    }));
+    let disabled = false;
+    const syncDisabled = () => {
+      picker.el.setAttribute('aria-disabled', String(disabled));
+      for (const button of picker.el.querySelectorAll('button')) button.disabled = disabled;
+    };
+    field.listen(picker.el, 'change', (event) => event.stopImmediatePropagation());
+    picker.on('change', (event) => field.emit('change', { value: event.detail.date }));
+    return {
+      el: picker.el,
+      get: () => picker.get(),
+      set: (value) => {
+        picker.set(value instanceof Date ? value : null, { silent: true });
+        syncDisabled();
+      },
+      focus: () => picker.focus(),
+      setDisabled: (value) => {
+        disabled = Boolean(value);
+        syncDisabled();
+      }
+    };
+  });
+}

package/src/components/date-picker/month-picker.js

@@ -0,0 +1,223 @@
+import { formatDate } from '../../core/date.js';
+import { h } from '../../core/dom.js';
+import { icon } from '../../core/icons.js';
+import { DatePicker } from './date-picker.js';
+
+/**
+ * @typedef {Object} MonthPickerOptions
+ * @property {Date|null} [value=null] Initially selected month.
+ * @property {Date|null} [min=null] Earliest selectable month.
+ * @property {Date|null} [max=null] Latest selectable month.
+ * @property {(event: CustomEvent<{date: Date|null}>) => void} [onchange] Change listener.
+ */
+/** @typedef {{silent?: boolean}} MonthPickerSetOptions */
+
+/**
+ * Twelve-month grid with a year stepper.
+ * @fires MonthPicker#change
+ */
+export class MonthPicker extends DatePicker {
+  static cssName = 'month-picker';
+
+  /** @type {MonthPickerOptions} */
+  static defaults = { value: null, min: null, max: null };
+
+  /** @returns {HTMLElement} */
+  render() {
+    const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
+    this._min = firstOfMonth(validDate(this.options.min));
+    this._max = firstOfMonth(validDate(this.options.max));
+    this._value = this._normalizeMonth(validDate(this.options.value));
+    const initial = this._value ?? firstOfMonth(new Date());
+    this._year = initial.getFullYear();
+    this._focusedMonth = initial.getMonth();
+
+    const content = h('div', { class: 'zx-month-picker__surface' },
+      h('div', { class: 'zx-month-picker__header' },
+        h('button', {
+          ref: 'previousYear',
+          class: 'zx-month-picker__nav',
+          type: 'button',
+          ariaLabel: 'Previous year'
+        }, icon('chevron-left')),
+        h('span', { ref: 'year', class: 'zx-month-picker__year', ariaLive: 'polite' }),
+        h('button', {
+          ref: 'nextYear',
+          class: 'zx-month-picker__nav',
+          type: 'button',
+          ariaLabel: 'Next year'
+        }, icon('chevron-right'))
+      ),
+      h('div', {
+        ref: 'grid',
+        class: 'zx-month-picker__grid',
+        role: 'grid',
+        ariaLabel: 'Choose month'
+      })
+    );
+    this._content = content;
+    root.append(content);
+    this.listen(this.refs.previousYear, 'click', () => this._stepYear(-1));
+    this.listen(this.refs.nextYear, 'click', () => this._stepYear(1));
+    this.listen(this.refs.grid, 'click', (event) => this._onMonthClick(event));
+    this.listen(this.refs.grid, 'keydown', (event) => this._onMonthKeydown(event));
+    this._renderMonths();
+    return root;
+  }
+
+  /** @returns {Date|null} */
+  get() {
+    return this._value ? new Date(this._value.getTime()) : null;
+  }
+
+  /**
+   * Selects the first day of a month.
+   * @param {Date|null} date Month to select, or null to clear.
+   * @param {MonthPickerSetOptions} [options={}] Update behavior.
+   * @returns {this}
+   * @fires MonthPicker#change
+   */
+  set(date, { silent = false } = {}) {
+    this._value = this._normalizeMonth(validDate(date));
+    if (this._value) {
+      this._year = this._value.getFullYear();
+      this._focusedMonth = this._value.getMonth();
+    }
+    this._renderMonths();
+    if (!silent) this.emit('change', { date: this.get() });
+    return this;
+  }
+
+  /** @returns {this} */
+  focus() {
+    this._button(this._focusedMonth)?.focus();
+    return this;
+  }
+
+  /** Removes generated content from an enhanced target. @returns {void} */
+  destroy() {
+    this._content?.remove();
+    super.destroy();
+  }
+
+  /** @param {Date|null} date @returns {Date|null} */
+  _normalizeMonth(date) {
+    if (!date) return null;
+    let result = firstOfMonth(date);
+    if (this._min && result < this._min) result = new Date(this._min.getTime());
+    if (this._max && result > this._max) result = new Date(this._max.getTime());
+    return result;
+  }
+
+  /** @returns {void} */
+  _renderMonths() {
+    if (!this.refs?.grid) return;
+    this.refs.year.textContent = String(this._year);
+    const months = [];
+    for (let month = 0; month < 12; month += 1) {
+      const date = new Date(this._year, month, 1);
+      const selected = Boolean(this._value && sameMonth(date, this._value));
+      months.push(h('button', {
+        class: 'zx-month-picker__month',
+        type: 'button',
+        role: 'gridcell',
+        tabindex: month === this._focusedMonth ? 0 : -1,
+        ariaSelected: String(selected),
+        ariaDisabled: String(!this._inRange(date)),
+        ariaLabel: formatDate(date, '%B %Y'),
+        dataset: { month }
+      }, formatDate(date, '%b')));
+    }
+    this.refs.grid.replaceChildren(...months);
+  }
+
+  /** @param {number} amount @returns {void} */
+  _stepYear(amount) {
+    this._year += amount;
+    this._renderMonths();
+  }
+
+  /** @param {Event} event @returns {void} */
+  _onMonthClick(event) {
+    const button = event.target?.closest?.('[data-month]');
+    if (!button || !this.refs.grid.contains(button)) return;
+    this._selectMonth(Number(button.dataset.month));
+  }
+
+  /** @param {KeyboardEvent} event @returns {void} */
+  _onMonthKeydown(event) {
+    const button = event.target?.closest?.('[data-month]');
+    if (!button || !this.refs.grid.contains(button)) return;
+    const current = Number(button.dataset.month);
+    let delta = null;
+    if (event.key === 'ArrowLeft') delta = -1;
+    else if (event.key === 'ArrowRight') delta = 1;
+    else if (event.key === 'ArrowUp') delta = -3;
+    else if (event.key === 'ArrowDown') delta = 3;
+    else if (event.key === 'Home') delta = -(current % 3);
+    else if (event.key === 'End') delta = 2 - (current % 3);
+    else if (event.key === 'PageUp') {
+      event.preventDefault();
+      this._stepYear(-1);
+      this.focus();
+      return;
+    } else if (event.key === 'PageDown') {
+      event.preventDefault();
+      this._stepYear(1);
+      this.focus();
+      return;
+    } else if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      this._selectMonth(current);
+      return;
+    }
+    if (delta === null) return;
+    event.preventDefault();
+    const absolute = this._year * 12 + current + delta;
+    this._year = Math.floor(absolute / 12);
+    this._focusedMonth = ((absolute % 12) + 12) % 12;
+    this._renderMonths();
+    this.focus();
+  }
+
+  /** @param {number} month @returns {void} */
+  _selectMonth(month) {
+    const date = new Date(this._year, month, 1);
+    if (!this._inRange(date)) return;
+    this._focusedMonth = month;
+    this._value = date;
+    this._renderMonths();
+    this.emit('change', { date: this.get() });
+  }
+
+  /** @param {Date} date @returns {boolean} */
+  _inRange(date) {
+    return !(this._min && date < this._min) && !(this._max && date > this._max);
+  }
+
+  /** @param {number} month @returns {HTMLButtonElement|null} */
+  _button(month) {
+    return this.refs.grid.querySelector(`[data-month="${month}"]`);
+  }
+}
+
+/**
+ * Fired when the selected month changes.
+ * @event MonthPicker#change
+ * @type {CustomEvent<{date: Date|null}>}
+ */
+
+/** @param {unknown} value @returns {Date|null} */
+function validDate(value) {
+  return value instanceof Date && !Number.isNaN(value.getTime()) ? new Date(value.getTime()) : null;
+}
+
+/** @param {Date|null} date @returns {Date|null} */
+function firstOfMonth(date) {
+  return date ? new Date(date.getFullYear(), date.getMonth(), 1) : null;
+}
+
+/** @param {Date} a @param {Date} b @returns {boolean} */
+function sameMonth(a, b) {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}

package/src/components/date-picker/range-field-adapter.js

@@ -0,0 +1,31 @@
+import { DateRangeBox } from '../datebox/date-range-box.js';
+import { Field } from '../field/field.js';
+
+/**
+ * Registers the DateRangeBox-backed `daterange` field type, so a Form field declared as
+ * `{ type: 'daterange', label, props: {…} }` renders a formatted range input with an anchored
+ * two-month calendar. Field values are `{start, end}` objects of `Date|null`.
+ * @returns {void}
+ */
+export function registerDateRangeFieldAdapter() {
+  Field.register('daterange', (field, options) => {
+    const box = field.own(new DateRangeBox(null, {
+      ...(options.props ?? {}),
+      disabled: Boolean(options.disabled),
+      start: options.value?.start ?? null,
+      end: options.value?.end ?? null
+    }));
+    // The box already emits its own `change`; stop the DOM copy so Field does not report twice.
+    field.listen(box.el, 'change', (event) => event.stopImmediatePropagation());
+    box.on('change', (event) => field.emit('change', {
+      value: { start: event.detail.start, end: event.detail.end }
+    }));
+    return {
+      el: box.el,
+      get: () => box.get(),
+      set: (value) => box.set(value, { silent: true }),
+      focus: () => box.focus(),
+      setDisabled: (disabled) => disabled ? box.disable() : box.enable()
+    };
+  });
+}

package/src/components/date-picker/time-picker.css

@@ -0,0 +1,191 @@
+.zx-time-picker {
+  display: inline-block;
+  color: var(--zx-color-text);
+  font-size: var(--zx-control-font-size);
+}
+
+.zx-time-picker__segments {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-1);
+}
+
+.zx-time-picker__spin {
+  inline-size: calc(var(--zx-control-height) + var(--zx-space-2));
+  padding-inline: var(--zx-space-1);
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+}
+
+.zx-time-picker__spin:focus-visible {
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-time-picker__separator {
+  color: var(--zx-color-text-muted);
+  font-weight: 700;
+}
+
+.zx-time-picker__clock-toggle {
+  margin-inline-start: var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+}
+
+.zx-time-picker__clock-toggle[aria-expanded="true"] {
+  color: var(--zx-color-accent);
+}
+
+/* -------------------------------------------------------------------- clock -- */
+
+/*
+ * Dial geometry. Every mark is centred on the dial and then pushed out along its own angle,
+ * which keeps the numbers upright: rotate the coordinate system, translate outwards, rotate back.
+ */
+.zx-time-picker__clock {
+  --zx-clock-size: 232px;
+  --zx-clock-mark: 32px;
+  --zx-clock-outer: calc(var(--zx-clock-size) / 2 - var(--zx-clock-mark) / 2 - 4px);
+  --zx-clock-inner: calc(var(--zx-clock-outer) - var(--zx-clock-mark) - 2px);
+  display: grid;
+  justify-items: center;
+  gap: var(--zx-space-2);
+  margin-block-start: var(--zx-space-3);
+  border-block-start: 1px solid var(--zx-color-border);
+  padding-block-start: var(--zx-space-3);
+}
+
+.zx-time-picker__clock[hidden] {
+  display: none;
+}
+
+.zx-time-picker__clock-head {
+  display: flex;
+  align-items: baseline;
+  gap: var(--zx-space-1);
+}
+
+.zx-time-picker__clock-unit {
+  min-block-size: 0;
+  border: 0;
+  border-radius: var(--zx-radius-sm);
+  background: none;
+  padding: 0 var(--zx-space-1);
+  color: var(--zx-color-text-muted);
+  font: inherit;
+  font-size: var(--zx-text-2xl);
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  line-height: 1.2;
+  cursor: pointer;
+}
+
+.zx-time-picker__clock-unit[aria-pressed="true"] {
+  color: var(--zx-color-accent);
+}
+
+.zx-time-picker__clock-unit:focus-visible {
+  outline: 0;
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-time-picker__clock-colon {
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-2xl);
+  font-weight: 600;
+}
+
+.zx-time-picker__dial {
+  position: relative;
+  inline-size: var(--zx-clock-size);
+  block-size: var(--zx-clock-size);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-bg-muted);
+}
+
+.zx-time-picker__mark {
+  position: absolute;
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+  display: grid;
+  place-items: center;
+  inline-size: var(--zx-clock-mark);
+  block-size: var(--zx-clock-mark);
+  min-block-size: 0;
+  border: 0;
+  border-radius: var(--zx-radius-full);
+  background: none;
+  padding: 0;
+  color: var(--zx-color-text);
+  font: inherit;
+  font-size: var(--zx-text-sm);
+  font-variant-numeric: tabular-nums;
+  cursor: pointer;
+  transform: translate(-50%, -50%)
+    rotate(var(--zx-clock-angle))
+    translateY(calc(-1 * var(--zx-clock-outer)))
+    rotate(calc(-1 * var(--zx-clock-angle)));
+}
+
+.zx-time-picker__mark[data-ring="inner"] {
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+  transform: translate(-50%, -50%)
+    rotate(var(--zx-clock-angle))
+    translateY(calc(-1 * var(--zx-clock-inner)))
+    rotate(calc(-1 * var(--zx-clock-angle)));
+}
+
+.zx-time-picker__mark:hover {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-time-picker__mark[aria-checked="true"] {
+  background: var(--zx-color-accent);
+  color: var(--zx-color-on-accent);
+  font-weight: 600;
+}
+
+.zx-time-picker__mark:focus-visible {
+  outline: 0;
+  box-shadow: var(--zx-focus-ring);
+}
+
+/* The hand's box hangs from the dial centre, so a plain rotation sweeps it around the face. */
+.zx-time-picker__hand {
+  position: absolute;
+  inset-block-start: calc(50% - var(--zx-clock-outer));
+  inset-inline-start: 50%;
+  inline-size: 2px;
+  block-size: var(--zx-clock-outer);
+  margin-inline-start: -1px;
+  background: var(--zx-color-accent);
+  transform-origin: 50% 100%;
+  transform: rotate(var(--zx-clock-angle, 0deg));
+}
+
+.zx-time-picker__hand[data-ring="inner"] {
+  inset-block-start: calc(50% - var(--zx-clock-inner));
+  block-size: var(--zx-clock-inner);
+}
+
+.zx-time-picker__pivot {
+  position: absolute;
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+  inline-size: 8px;
+  block-size: 8px;
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  transform: translate(-50%, -50%);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-time-picker__hand {
+    transition: transform var(--zx-dur-base) var(--zx-ease);
+  }
+
+  .zx-time-picker__mark {
+    transition: background-color var(--zx-dur-fast) var(--zx-ease),
+      color var(--zx-dur-fast) var(--zx-ease);
+  }
+}