@dashforge/tw 0.9.1-beta → 0.11.0-beta

package/src/components/DateTimePicker/DateTimePicker.tsx

@@ -1,166 +1,154 @@
-import {
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useRef,
-} from 'react';
+import { useCallback, useContext, useEffect, useId, useRef, useState } from 'react';
 import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
 import type { DashFormBridge, FieldRegistration } from '@dashforge/ui-core';
 import { useDashFieldMeta } from '@dashforge/forms';
+import {
+  formatTime,
+  generateTimeOptions,
+  getTodayISODate,
+  parseISODate,
+} from '@dashforge/calendar-core';
+import type { ISODate } from '@dashforge/calendar-core';
 import { cn } from '../../utils/cn.js';
 import { useAccessState } from '../../hooks/useAccessState.js';
 import { resolveValidationState } from '../_shared/resolveValidationState.js';
+import { Popover } from '../Popover/Popover.js';
+import { Calendar } from '../Calendar/Calendar.js';
 import { dateTimePickerVariants } from './dateTimePicker.variants.js';
-import type {
-  DateTimePickerMode,
-  DateTimePickerProps,
-} from './dateTimePicker.types.js';
+import type { DateTimePickerProps } from './dateTimePicker.types.js';
 
-/**
- * Resolve the native HTML input `type` for a given picker mode.
- */
-function inputTypeFor(mode: DateTimePickerMode): string {
-  switch (mode) {
-    case 'time':
-      return 'time';
-    case 'datetime':
-      return 'datetime-local';
-    case 'date':
-    default:
-      return 'date';
-  }
+// Inline 16×16 stroke calendar glyph — no icon dependency (tw convention).
+function CalendarIcon() {
+  return (
+    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <rect
+        x="2.5"
+        y="3.5"
+        width="11"
+        height="10"
+        rx="1.5"
+        stroke="currentColor"
+        strokeWidth="1.5"
+      />
+      <path
+        d="M2.5 6.5h11M5.5 2v3M10.5 2v3"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
 }
 
-/**
- * Coerce a stored/exposed value (ISO 8601-ish string or `null`/`undefined`)
- * into the format the native input expects.
- *
- * Contract:
- *   - `date`     → `YYYY-MM-DD`
- *   - `time`     → `HH:mm` (or `HH:mm:ss` if seconds present)
- *   - `datetime` → `YYYY-MM-DDTHH:mm` (no timezone, datetime-local
- *                  rejects `Z` / offset suffixes)
- *
- * The function is intentionally lenient:
- *   - Pass-through when the input already matches the expected shape.
- *   - Truncates a richer ISO string (e.g. `2026-05-16T10:23:45.000Z`)
- *     down to the mode-appropriate prefix.
- *   - Returns `''` for null / undefined / unparseable inputs (native
- *     inputs use `''` to represent "no value").
- */
-export function isoToInputValue(
-  mode: DateTimePickerMode,
-  raw: string | null | undefined
-): string {
-  if (raw == null || raw === '') return '';
+const DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})/;
 
-  // Fast path: already in the expected shape.
-  if (mode === 'date' && /^\d{4}-\d{2}-\d{2}$/.test(raw)) return raw;
-  if (mode === 'time' && /^\d{2}:\d{2}(:\d{2})?$/.test(raw)) return raw;
-  if (
-    mode === 'datetime' &&
-    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?$/.test(raw)
-  ) {
-    return raw;
+/** Splits a stored `YYYY-MM-DDTHH:mm` value into its date and time parts. */
+function splitDateTime(value: string | null | undefined): {
+  date: ISODate | null;
+  time: string | null;
+} {
+  if (value == null || value === '') {
+    return { date: null, time: null };
   }
+  const match = DATETIME_PATTERN.exec(value);
+  if (match !== null) {
+    return {
+      date: match[1] ?? null,
+      time: `${match[2] ?? '00'}:${match[3] ?? '00'}`,
+    };
+  }
+  return { date: parseISODate(value) !== null ? value : null, time: null };
+}
 
-  // Slow path: parse via Date and re-format locally.
-  const d = new Date(raw);
-  if (isNaN(d.getTime())) return '';
-
-  const pad = (n: number) => String(n).padStart(2, '0');
-  const yyyy = d.getFullYear();
-  const mm = pad(d.getMonth() + 1);
-  const dd = pad(d.getDate());
-  const hh = pad(d.getHours());
-  const mi = pad(d.getMinutes());
-
-  if (mode === 'date') return `${yyyy}-${mm}-${dd}`;
-  if (mode === 'time') return `${hh}:${mi}`;
-  return `${yyyy}-${mm}-${dd}T${hh}:${mi}`;
+/** Combines a date and a time into a `YYYY-MM-DDTHH:mm` value (or `null`). */
+function joinDateTime(date: ISODate | null, time: string | null): string | null {
+  if (date === null && time === null) {
+    return null;
+  }
+  return `${date ?? getTodayISODate()}T${time ?? '00:00'}`;
 }
 
-/**
- * Take a native input string and return the canonical "stored" value:
- * the same string for non-empty input, or `null` for empty (so the
- * bridge / consumer never receives the ambiguous empty string).
- */
-function inputValueToStored(raw: string): string | null {
-  return raw === '' ? null : raw;
+/** Formats a stored datetime for the trigger display. */
+function formatDateTime(
+  value: string | null,
+  locale: string,
+  hour12: boolean,
+): string {
+  const { date, time } = splitDateTime(value);
+  const parts: string[] = [];
+  if (date !== null) {
+    const parsed = parseISODate(date);
+    parts.push(
+      parsed === null
+        ? date
+        : new Intl.DateTimeFormat(locale, {
+            dateStyle: 'medium',
+            timeZone: 'UTC',
+          }).format(Date.UTC(parsed.year, parsed.month - 1, parsed.day)),
+    );
+  }
+  if (time !== null) {
+    parts.push(formatTime(time, { hour12 }));
+  }
+  return parts.join(', ');
 }
 
 /**
- * Dashforge TW DateTimePicker — bridge-integrated native date/time input.
- *
- * Three modes (`mode` prop):
- *   - `date`     — `<input type="date">` → `YYYY-MM-DD`
- *   - `time`     — `<input type="time">` → `HH:mm` (`HH:mm:ss` with `step={1}`)
- *   - `datetime` — `<input type="datetime-local">` → `YYYY-MM-DDTHH:mm`
+ * Dashforge TW `<DateTimePicker>` — a form-bound date + time field.
  *
- * **Why native inputs instead of React Aria `<DatePicker>`?**
+ * A read-only trigger button paired with a popover combining a `<Calendar>`
+ * and a time list (Radix Popover). Integrates with the Dashforge form
+ * bridge + RBAC.
  *
- * 1. Zero new deps (`@internationalized/date` would add ~30 KB).
- * 2. Mirrors `@dashforge/ui/DateTimePicker` (MUI side) for API parity.
- * 3. Native inputs are AAA-grade a11y out of the box — screen readers,
- *    keyboard nav, OS-provided calendar/clock UI.
- * 4. Predictable state (no internal Aria state machine that fights
- *    controlled props — the F5-A lesson learned in `<Autocomplete>`).
- *
- * A richer custom-calendar version (range mode, locale awareness,
- * custom popover styling) can land as F5-B-bis built on Aria
- * `<DatePicker>` / `<Calendar>`.
- *
- * **A11y**:
- *   - `aria-invalid` driven by the resolved validation state.
- *   - `aria-describedby` links input ↔ helper/error.
- *   - Required fields get the native `required` attribute + a visual `*`.
- *   - `color-scheme: light dark` keeps the OS calendar icon readable
- *     in both color schemes.
+ * Storage contract: a naive ISO datetime `"YYYY-MM-DDTHH:mm"` — no seconds,
+ * no timezone. Shared with the MUI `@dashforge/ui` `DateTimePicker`.
  */
 export function DateTimePicker(props: DateTimePickerProps) {
   const {
     name,
     rules,
-    mode = 'date',
-    visibleWhen,
-    layout = 'stacked',
-    size,
     label,
     helperText,
-    required,
     error,
+    required,
     disabled,
-    fullWidth,
-    access,
-    sx,
-    slotProps,
     placeholder,
-    min,
-    max,
-    step,
+    layout = 'stacked',
+    visibleWhen,
+    access,
     value: explicitValue,
     defaultValue,
-    onValueChange,
+    onChange,
+    minDate,
+    maxDate,
+    disabledDates,
+    isDateDisabled,
+    weekStartDay,
+    locale,
+    stepMinutes,
+    hour12 = false,
+    fullWidth,
+    sx,
+    slotProps,
+    testId,
   } = props;
 
-  // ───── Hooks (unconditional) ─────
   const bridge = useContext(DashFormContext) as DashFormBridge | null;
   const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
-  // Per-field reactive snapshot. Same pattern as <TextField> — re-renders
-  // this component when its OWN bridge value changes, but not when a
-  // sibling field changes (perf contract).
   const fieldMeta = useDashFieldMeta(name);
   const accessState = useAccessState(access);
 
-  const inputId = useId();
-  const helperId = `${inputId}-help`;
+  const fieldId = useId();
+  const helperId = `${fieldId}-help`;
+
+  const [isOpen, setIsOpen] = useState(false);
+  const [internalValue, setInternalValue] = useState<string | null>(
+    defaultValue ?? null,
+  );
 
-  // StrictMode-safe unregister-on-unmount.
   const unregisterRef = useRef({ bridge, name });
   unregisterRef.current = { bridge, name };
   const isMountedRef = useRef(false);
-   
   useEffect(() => {
     isMountedRef.current = true;
     return () => {
@@ -172,15 +160,14 @@ export function DateTimePicker(props: DateTimePickerProps) {
     };
   }, []);
 
-  // ───── Derived ─────
   const effectiveDisabled = Boolean(disabled) || accessState.disabled;
-  const effectiveReadOnly = accessState.readonly;
+  const isInteractive = !effectiveDisabled && !accessState.readonly;
   const isFormMode = Boolean(bridge?.register);
 
   let resolvedError = error;
   let resolvedHelperText: typeof helperText = helperText;
   let registration: FieldRegistration | null = null;
-  let resolvedValue: string | null | undefined;
+  let resolvedValue: string | null;
 
   if (isFormMode && bridge) {
     registration = bridge.register(name, rules);
@@ -196,77 +183,89 @@ export function DateTimePicker(props: DateTimePickerProps) {
   } else if (explicitValue !== undefined) {
     resolvedValue = explicitValue;
   } else {
-    // Pure uncontrolled mode: defer to native input's defaultValue.
-    resolvedValue = undefined;
+    resolvedValue = internalValue;
   }
 
-  // Registration-supplied callback ref (RHF threads its own ref through
-  // here in form mode). Stable callback to keep React 19 happy.
   const registrationRefFn = registration?.ref;
-  const inputRef = useCallback(
-    (instance: HTMLInputElement | null) => {
+  const triggerRef = useCallback(
+    (instance: HTMLButtonElement | null) => {
       if (typeof registrationRefFn === 'function') {
         registrationRefFn(instance);
       }
     },
-    [registrationRefFn]
+    [registrationRefFn],
   );
 
-  // ───── Render-time guards (after all hooks) ─────
   if (!isVisible) return null;
   if (!accessState.visible) return null;
 
-  const v = dateTimePickerVariants({
-    size,
-    layout,
-    error: resolvedError,
-    fullWidth,
-    disabled: effectiveDisabled,
+  const v = dateTimePickerVariants({ layout, error: resolvedError, fullWidth });
+  const resolvedLocale = locale ?? 'en-US';
+  const { date, time } = splitDateTime(resolvedValue);
+  const displayValue = formatDateTime(resolvedValue, resolvedLocale, hour12);
+  const options = generateTimeOptions({
+    ...(stepMinutes !== undefined && { stepMinutes }),
   });
 
-  const inputType = inputTypeFor(mode);
-  const nativeValue =
-    resolvedValue === undefined ? undefined : isoToInputValue(mode, resolvedValue);
-  const nativeDefault =
-    !isFormMode && explicitValue === undefined && defaultValue !== undefined
-      ? isoToInputValue(mode, defaultValue)
-      : undefined;
-  const nativeMin = min != null ? isoToInputValue(mode, min) : undefined;
-  const nativeMax = max != null ? isoToInputValue(mode, max) : undefined;
-
-  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
-    const next = inputValueToStored(event.target.value);
+  const commitValue = (next: string | null) => {
     if (isFormMode && bridge) {
       bridge.setValue?.(name, next);
       void registration?.onChange?.({
         target: { name, value: next ?? '' },
         type: 'change',
       });
+    } else if (explicitValue === undefined) {
+      setInternalValue(next);
     }
-    onValueChange?.(next);
+    onChange?.(next);
   };
 
-  const handleBlur = (event: React.FocusEvent<HTMLInputElement>) => {
+  const markTouched = () => {
     if (isFormMode && bridge) {
-      registration?.onBlur?.(event);
+      const committed = bridge.getValue(name);
+      void registration?.onBlur?.({
+        target: { name, value: committed == null ? '' : String(committed) },
+        type: 'blur',
+      });
     }
   };
 
+  const handleOpenChange = (next: boolean) => {
+    if (next && !isInteractive) {
+      return;
+    }
+    setIsOpen(next);
+    if (!next) {
+      markTouched();
+    }
+  };
+
+  // Picking a date keeps the popover open — the user still needs a time.
+  const handleDateSelect = (nextDate: ISODate) => {
+    commitValue(joinDateTime(nextDate, time));
+  };
+  // Picking a time completes the value and closes the popover.
+  const handleTimeSelect = (nextTime: string) => {
+    commitValue(joinDateTime(date, nextTime));
+    setIsOpen(false);
+    markTouched();
+  };
+
   return (
-    <div className={cn(v.root(), sx, slotProps?.root?.className)}>
+    <div
+      data-testid={testId}
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+    >
       {label && (
         <label
-          htmlFor={inputId}
+          htmlFor={fieldId}
           className={cn(v.label(), slotProps?.label?.className)}
         >
           {label}
           {required && (
             <span
               aria-hidden="true"
-              className={cn(
-                v.requiredMark(),
-                slotProps?.requiredMark?.className
-              )}
+              className={cn(v.requiredMark(), slotProps?.requiredMark?.className)}
             >
               *
             </span>
@@ -274,32 +273,61 @@ export function DateTimePicker(props: DateTimePickerProps) {
         </label>
       )}
 
-      <div
-        className={cn(v.inputWrapper(), slotProps?.inputWrapper?.className)}
+      <Popover
+        open={isOpen}
+        onOpenChange={handleOpenChange}
+        side="bottom"
+        align="start"
+        content={
+          <div className={v.panel()}>
+            <Calendar
+              value={date}
+              onChange={handleDateSelect}
+              minDate={minDate}
+              maxDate={maxDate}
+              disabledDates={disabledDates}
+              isDateDisabled={isDateDisabled}
+              weekStartDay={weekStartDay}
+              locale={locale}
+              aria-label="Choose date"
+              sx="border-0 bg-transparent p-0"
+            />
+            <div role="listbox" aria-label="Time options" className={v.list()}>
+              {options.map((option) => (
+                <button
+                  key={option}
+                  type="button"
+                  role="option"
+                  aria-selected={option === time}
+                  className={v.option()}
+                  onClick={() => {
+                    handleTimeSelect(option);
+                  }}
+                >
+                  {formatTime(option, { hour12 })}
+                </button>
+              ))}
+            </div>
+          </div>
+        }
       >
-        <input
-          id={inputId}
-          ref={inputRef}
-          name={name}
-          type={inputType}
-          // Controlled in form / explicit-value mode; uncontrolled with
-          // `defaultValue` otherwise. Mirrors the TextField pattern.
-          value={nativeValue}
-          defaultValue={nativeDefault}
-          min={nativeMin}
-          max={nativeMax}
-          step={step}
-          placeholder={placeholder}
+        <button
+          type="button"
+          id={fieldId}
+          ref={triggerRef}
           disabled={effectiveDisabled}
-          readOnly={effectiveReadOnly}
-          required={required}
           aria-invalid={resolvedError ? true : undefined}
           aria-describedby={resolvedHelperText ? helperId : undefined}
-          onChange={handleChange}
-          onBlur={handleBlur}
-          className={cn(v.input(), slotProps?.input?.className)}
-        />
-      </div>
+          className={cn(v.trigger(), slotProps?.trigger?.className)}
+        >
+          <span className={displayValue ? v.value() : v.placeholder()}>
+            {displayValue || placeholder || 'Select date and time'}
+          </span>
+          <span className={v.icon()}>
+            <CalendarIcon />
+          </span>
+        </button>
+      </Popover>
 
       {resolvedHelperText && (
         <p
@@ -308,7 +336,7 @@ export function DateTimePicker(props: DateTimePickerProps) {
             resolvedError ? v.errorText() : v.helperText(),
             resolvedError
               ? slotProps?.errorText?.className
-              : slotProps?.helperText?.className
+              : slotProps?.helperText?.className,
           )}
         >
           {resolvedHelperText}

package/src/components/DateTimePicker/dateTimePicker.types.ts

@@ -1,83 +1,79 @@
 import type { ReactNode } from 'react';
 import type { Engine } from '@dashforge/ui-core';
 import type { AccessRequirement } from '@dashforge/rbac';
-import type { DateTimePickerVariants } from './dateTimePicker.variants.js';
-
-/**
- * Operating mode of the picker.
- *
- *  - `'date'`     — `YYYY-MM-DD` (native `<input type="date">`)
- *  - `'time'`     — `HH:mm` or `HH:mm:ss` (native `<input type="time">`)
- *  - `'datetime'` — `YYYY-MM-DDTHH:mm` (native `<input type="datetime-local">`)
- *
- * Note: `datetime-local` does NOT include timezone info. Values are
- * naive local-time strings. If you need TZ-aware persistence, convert
- * upstream (e.g., interpret as UTC, or attach the user's TZ from a
- * separate field).
- */
-export type DateTimePickerMode = 'date' | 'time' | 'datetime';
+import type { ISODate, WeekDay } from '@dashforge/calendar-core';
 
+/** Per-slot `className` overrides for `<DateTimePicker>`. */
 export interface DateTimePickerSlotProps {
   root?: { className?: string };
   label?: { className?: string };
   requiredMark?: { className?: string };
-  inputWrapper?: { className?: string };
-  input?: { className?: string };
+  trigger?: { className?: string };
   helperText?: { className?: string };
   errorText?: { className?: string };
 }
 
 /**
- * Props for `<DateTimePicker>`.
- *
- * Bridge-integrated date / time / datetime input built on the native
- * HTML5 input types (`type="date|time|datetime-local"`). Chosen over a
- * custom React Aria `<DatePicker>` for F5-B because:
- *
- *  1. **Zero new deps** — no `@internationalized/date`.
- *  2. **A11y by default** — screen readers know how to announce these
- *     inputs, including the OS-provided calendar/clock popup.
- *  3. **Bundle size** — saves ~30KB minified over the Aria stack.
- *  4. **API parity** with the MUI side (`@dashforge/ui/DateTimePicker`).
- *  5. **Predictability** — no internal state machine to fight (see the
- *     ComboBox lesson learned in `<Autocomplete>` F5-A).
+ * Props for the `<DateTimePicker>` form field (Tailwind skin).
  *
- * A richer "always-visible calendar grid" upgrade can come as F5-B-bis.
+ * A read-only trigger paired with a popover combining a `<Calendar>` and a
+ * time list. The stored value is a naive ISO datetime — `"YYYY-MM-DDTHH:mm"`
+ * — or `null`. No seconds, no timezone.
  *
- * Value contract: ISO 8601-ish naive strings, always.
+ * For a date-only field use `<DatePicker>`; for time-only use `<TimePicker>`.
+ * The prop surface mirrors the MUI `@dashforge/ui` `DateTimePicker`.
  */
-export interface DateTimePickerProps extends DateTimePickerVariants {
+export interface DateTimePickerProps {
+  /** Field name — the bridge registration key. Required. */
   name: string;
+  /** Validation rules forwarded to the form bridge. */
   rules?: unknown;
-  /** Which native input to render. @default 'date' */
-  mode?: DateTimePickerMode;
+  /** Field label. */
   label?: ReactNode;
+  /** Helper text below the control (overrides a bridge error message). */
   helperText?: ReactNode;
-  required?: boolean;
+  /** Explicit error state (overrides the bridge's auto error). */
   error?: boolean;
+  /** Marks the field required (adds the label asterisk). */
+  required?: boolean;
+  /** Disables the field. */
   disabled?: boolean;
+  /** Placeholder shown when no value is selected. */
   placeholder?: string;
-  /** Minimum value (ISO string compatible with the mode). */
-  min?: string;
-  /** Maximum value (ISO string compatible with the mode). */
-  max?: string;
-  /**
-   * Step in seconds (time / datetime). Default 60 ⇒ minute precision.
-   * Set to 1 to allow seconds.
-   */
-  step?: number;
-  /** Engine predicate — field not rendered when it returns `false`. */
+  /** Label/control layout. */
+  layout?: 'stacked' | 'inline';
+  /** Reactive visibility predicate evaluated against the form engine. */
   visibleWhen?: (engine: Engine) => boolean;
   /** RBAC access requirement. */
   access?: AccessRequirement;
-  /** Root className shortcut. */
-  sx?: string;
-  /** Per-slot className overrides. */
-  slotProps?: DateTimePickerSlotProps;
-  /** Controlled value (form mode reads from the bridge if omitted). */
+  /** Controlled value — `"YYYY-MM-DDTHH:mm"` or `null`. */
   value?: string | null;
-  /** Default value for uncontrolled mode (no-op in form mode). */
+  /** Uncontrolled initial value. */
   defaultValue?: string | null;
-  /** Fires when the user picks a date/time (after bridge update in form mode). */
-  onValueChange?: (value: string | null) => void;
+  /** Fired with the new datetime (or `null` when cleared). */
+  onChange?: (value: string | null) => void;
+  /** Earliest selectable date (inclusive). */
+  minDate?: ISODate;
+  /** Latest selectable date (inclusive). */
+  maxDate?: ISODate;
+  /** Explicit list of disabled dates. */
+  disabledDates?: readonly ISODate[];
+  /** Predicate marking arbitrary dates disabled. */
+  isDateDisabled?: (date: ISODate) => boolean;
+  /** Weekday of the calendar's first column (`0` = Sunday). */
+  weekStartDay?: WeekDay;
+  /** BCP-47 locale for the calendar and the display format. */
+  locale?: string;
+  /** Step between time-list options, in minutes. Default `30`. */
+  stepMinutes?: number;
+  /** Render the time list in 12-hour notation. Default `false`. */
+  hour12?: boolean;
+  /** Stretches the field to its container width. */
+  fullWidth?: boolean;
+  /** Root-level Tailwind class override. */
+  sx?: string;
+  /** Per-slot `className` overrides. */
+  slotProps?: DateTimePickerSlotProps;
+  /** Test id applied to the field root. */
+  testId?: string;
 }