@dashforge/tw 0.9.1-beta → 0.10.0-beta

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

@@ -1,84 +1,55 @@
-import { tv, type VariantProps } from 'tailwind-variants';
+import { tv } from 'tailwind-variants';
 
 /**
- * Tailwind-variants recipe for `<DateTimePicker>` with 6 slots.
+ * Slots for `<DateTimePicker>` — a bridge-integrated date+time field whose
+ * trigger is a `<button>` styled as an input, opening a popover that
+ * combines a `<Calendar>` with a time list.
  *
- * Styling mirrors `<TextField>` for layout / sizes / error states so
- * the two field types compose visually in the same form.
- *
- * Native `<input type="date|time|datetime-local">` quirks handled here:
- *
- *  - The browser-rendered placeholder mask (e.g., `mm/dd/yyyy`) is
- *    invisible on `bg-neutral-50` by default in some themes; we keep
- *    the same neutral palette and rely on the input's own contrast
- *    rules (no extra `::placeholder` styling — browsers don't honor it
- *    on these input types).
- *  - The native picker indicator (calendar / clock icon) is
- *    browser-supplied; we ensure it stays visible in dark mode via
- *    `color-scheme: light dark` on the input (set inline below).
+ * Theme identity: bare neutral / brand token-backed classes only — no
+ * `dark:` variants on the neutral palette (the preset CSS-var swap
+ * auto-inverts). See `_shared/themeIdentity.test.ts`.
  */
 export const dateTimePickerVariants = tv({
   slots: {
-    root: 'flex',
+    root: 'flex flex-col',
     label: 'block text-sm font-medium text-neutral-900 mb-1',
     requiredMark: 'text-danger-500 ml-0.5',
-    inputWrapper: [
-      'relative flex items-center',
-      'rounded-md border bg-neutral-50',
-      'border-neutral-300',
-      'transition-colors',
-      'focus-within:border-primary-500 focus-within:ring-2 focus-within:ring-primary-500/30',
-    ],
-    input: [
-      'block w-full bg-transparent outline-none',
-      'text-neutral-900 placeholder:text-neutral-400',
-      'disabled:cursor-not-allowed disabled:opacity-60',
-      'read-only:cursor-default',
-      // `color-scheme` lets the native calendar / clock icon respect
-      // the dark mode (otherwise it stays light-themed against dark bg)
-      '[color-scheme:light_dark]',
-    ],
+    trigger:
+      'flex items-center gap-2 h-10 min-w-[13rem] rounded-md border border-neutral-300 bg-neutral-50 px-3 text-base text-neutral-900 cursor-pointer transition-colors hover:border-neutral-400 focus-visible:outline-none focus-visible:border-primary-500 focus-visible:ring-2 focus-visible:ring-primary-500/30 disabled:cursor-not-allowed disabled:opacity-60 disabled:bg-neutral-200',
+    value: 'flex-1 truncate text-left',
+    placeholder: 'flex-1 truncate text-left text-neutral-400',
+    icon: 'shrink-0 text-[1rem] text-neutral-500',
+    panel: 'flex items-stretch',
+    list: 'flex max-h-[19rem] min-w-[6.5rem] flex-col gap-0.5 overflow-y-auto border-l border-neutral-200 p-1',
+    option:
+      'flex w-full cursor-pointer items-center rounded px-2.5 py-1.5 text-sm text-neutral-900 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500 aria-selected:bg-primary-600 aria-selected:text-white aria-selected:hover:bg-primary-600',
     helperText: 'mt-1 text-sm text-neutral-600',
     errorText: 'mt-1 text-sm text-danger-600',
   },
   variants: {
-    size: {
-      sm: { inputWrapper: 'h-8 px-2', input: 'text-sm' },
-      md: { inputWrapper: 'h-10 px-3', input: 'text-base' },
-      lg: { inputWrapper: 'h-12 px-4', input: 'text-lg' },
-    },
     layout: {
-      stacked: { root: 'flex-col' },
+      stacked: {},
       inline: {
         root: 'flex-row items-start gap-3',
-        label: 'mb-0 pt-2 whitespace-nowrap shrink-0',
+        label: 'mb-0 pt-2.5 whitespace-nowrap shrink-0',
       },
     },
     error: {
       true: {
-        inputWrapper:
-          'border-danger-500 focus-within:border-danger-500 focus-within:ring-danger-500/30',
+        trigger:
+          'border-danger-500 hover:border-danger-500 focus-visible:border-danger-500 focus-visible:ring-danger-500/30',
       },
     },
     fullWidth: {
       true: {
         root: 'w-full',
-        inputWrapper: 'w-full',
-      },
-    },
-    disabled: {
-      true: {
-        inputWrapper: 'opacity-60 cursor-not-allowed bg-neutral-200',
+        trigger: 'w-full min-w-0',
       },
     },
   },
   defaultVariants: {
-    size: 'md',
     layout: 'stacked',
     error: false,
     fullWidth: false,
-    disabled: false,
   },
 });
-
-export type DateTimePickerVariants = VariantProps<typeof dateTimePickerVariants>;

package/src/components/TimePicker/TimePicker.test.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+
+import { TimePicker } from './TimePicker.js';
+
+beforeAll(() => {
+  // Radix Popover (Floating UI) needs ResizeObserver — jsdom lacks it.
+  if (!('ResizeObserver' in globalThis)) {
+    class ResizeObserverStub {
+      observe(): void {
+        /* no-op */
+      }
+      unobserve(): void {
+        /* no-op */
+      }
+      disconnect(): void {
+        /* no-op */
+      }
+    }
+    (globalThis as { ResizeObserver?: unknown }).ResizeObserver =
+      ResizeObserverStub;
+  }
+});
+
+describe('TimePicker', () => {
+  it('renders a labelled trigger with the placeholder', () => {
+    render(<TimePicker name="alarm" label="Alarm" placeholder="Pick a time" />);
+    expect(screen.queryByText('Alarm')).not.toBeNull();
+    expect(screen.getByRole('button').textContent).toContain('Pick a time');
+  });
+
+  it('shows a 24-hour controlled value', () => {
+    render(<TimePicker name="t" value="14:30" />);
+    expect(screen.getByRole('button').textContent).toContain('14:30');
+  });
+
+  it('formats the value in 12-hour notation when hour12 is set', () => {
+    render(<TimePicker name="t" value="14:30" hour12 />);
+    expect(screen.getByRole('button').textContent).toContain('2:30 PM');
+  });
+
+  it('opens the time-list popover from the trigger', () => {
+    render(<TimePicker name="t" />);
+    expect(screen.queryByRole('listbox')).toBeNull();
+    fireEvent.click(screen.getByRole('button'));
+    expect(screen.getByRole('listbox', { name: 'Time options' })).not.toBeNull();
+  });
+
+  it('selects a time from the popover, updates the trigger and closes', () => {
+    const onChange = vi.fn();
+    render(<TimePicker name="t" onChange={onChange} />);
+    fireEvent.click(screen.getByRole('button'));
+    fireEvent.click(screen.getByRole('option', { name: '09:00' }));
+    expect(onChange).toHaveBeenCalledWith('09:00');
+    expect(screen.queryByRole('listbox')).toBeNull();
+    expect(screen.getByRole('button').textContent).toContain('09:00');
+  });
+
+  it('does not open the popover when disabled', () => {
+    render(<TimePicker name="t" disabled />);
+    fireEvent.click(screen.getByRole('button'));
+    expect(screen.queryByRole('listbox')).toBeNull();
+  });
+});

package/src/components/TimePicker/TimePicker.tsx

@@ -0,0 +1,274 @@
+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,
+  timeStringToMinutes,
+} 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 { timePickerVariants } from './timePicker.variants.js';
+import type { TimePickerProps } from './timePicker.types.js';
+
+// Inline 16×16 stroke clock glyph — no icon dependency (tw convention).
+function ClockIcon() {
+  return (
+    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="1.5" />
+      <path
+        d="M8 4.5V8l2.4 1.4"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Dashforge TW `<TimePicker>` — a form-bound time-of-day field.
+ *
+ * A read-only trigger button paired with a time-list popover (Radix
+ * Popover). Integrates with the Dashforge form bridge + RBAC.
+ *
+ * Storage contract: a canonical 24-hour `"HH:mm"` string, or `null` —
+ * shared with the MUI `@dashforge/ui` `TimePicker`. `hour12` is display-only.
+ */
+export function TimePicker(props: TimePickerProps) {
+  const {
+    name,
+    rules,
+    label,
+    helperText,
+    error,
+    required,
+    disabled,
+    placeholder,
+    layout = 'stacked',
+    visibleWhen,
+    access,
+    value: explicitValue,
+    defaultValue,
+    onChange,
+    minTime,
+    maxTime,
+    stepMinutes,
+    hour12 = false,
+    fullWidth,
+    sx,
+    slotProps,
+    testId,
+  } = props;
+
+  const bridge = useContext(DashFormContext) as DashFormBridge | null;
+  const isVisible = useEngineVisibility(bridge?.engine, visibleWhen);
+  const fieldMeta = useDashFieldMeta(name);
+  const accessState = useAccessState(access);
+
+  const fieldId = useId();
+  const helperId = `${fieldId}-help`;
+
+  const [isOpen, setIsOpen] = useState(false);
+  const [internalValue, setInternalValue] = useState<string | null>(
+    defaultValue ?? null,
+  );
+
+  const unregisterRef = useRef({ bridge, name });
+  unregisterRef.current = { bridge, name };
+  const isMountedRef = useRef(false);
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      const { bridge: cap, name: capName } = unregisterRef.current;
+      queueMicrotask(() => {
+        if (!isMountedRef.current) cap?.unregister?.(capName);
+      });
+    };
+  }, []);
+
+  const effectiveDisabled = Boolean(disabled) || accessState.disabled;
+  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;
+
+  if (isFormMode && bridge) {
+    registration = bridge.register(name, rules);
+    const validation = resolveValidationState(name, bridge, error, helperText);
+    resolvedError = validation.error;
+    resolvedHelperText = validation.helperText;
+    if (explicitValue !== undefined) {
+      resolvedValue = explicitValue;
+    } else {
+      const bv = fieldMeta.value;
+      resolvedValue = bv == null ? null : String(bv);
+    }
+  } else if (explicitValue !== undefined) {
+    resolvedValue = explicitValue;
+  } else {
+    resolvedValue = internalValue;
+  }
+
+  const registrationRefFn = registration?.ref;
+  const triggerRef = useCallback(
+    (instance: HTMLButtonElement | null) => {
+      if (typeof registrationRefFn === 'function') {
+        registrationRefFn(instance);
+      }
+    },
+    [registrationRefFn],
+  );
+
+  if (!isVisible) return null;
+  if (!accessState.visible) return null;
+
+  const v = timePickerVariants({ layout, error: resolvedError, fullWidth });
+  const displayValue =
+    resolvedValue != null && resolvedValue !== ''
+      ? formatTime(resolvedValue, { hour12 })
+      : '';
+
+  const options = generateTimeOptions({
+    ...(minTime !== undefined && { start: minTime }),
+    ...(maxTime !== undefined && { end: maxTime }),
+    ...(stepMinutes !== undefined && { stepMinutes }),
+  });
+  const minMinutes = timeStringToMinutes(minTime ?? '00:00') ?? 0;
+  const maxMinutes = timeStringToMinutes(maxTime ?? '23:59') ?? 1439;
+  const isTimeDisabled = (time: string): boolean => {
+    const minutes = timeStringToMinutes(time);
+    return minutes === null || minutes < minMinutes || minutes > maxMinutes;
+  };
+
+  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);
+    }
+    onChange?.(next);
+  };
+
+  const markTouched = () => {
+    if (isFormMode && bridge) {
+      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();
+    }
+  };
+
+  const handleSelect = (time: string) => {
+    if (isTimeDisabled(time)) {
+      return;
+    }
+    commitValue(time);
+    setIsOpen(false);
+    markTouched();
+  };
+
+  return (
+    <div
+      data-testid={testId}
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+    >
+      {label && (
+        <label
+          htmlFor={fieldId}
+          className={cn(v.label(), slotProps?.label?.className)}
+        >
+          {label}
+          {required && (
+            <span
+              aria-hidden="true"
+              className={cn(v.requiredMark(), slotProps?.requiredMark?.className)}
+            >
+              *
+            </span>
+          )}
+        </label>
+      )}
+
+      <Popover
+        open={isOpen}
+        onOpenChange={handleOpenChange}
+        side="bottom"
+        align="start"
+        content={
+          <div role="listbox" aria-label="Time options" className={v.list()}>
+            {options.map((time) => (
+              <button
+                key={time}
+                type="button"
+                role="option"
+                aria-selected={time === resolvedValue}
+                aria-disabled={isTimeDisabled(time)}
+                className={v.option()}
+                onClick={() => {
+                  handleSelect(time);
+                }}
+              >
+                {formatTime(time, { hour12 })}
+              </button>
+            ))}
+          </div>
+        }
+      >
+        <button
+          type="button"
+          id={fieldId}
+          ref={triggerRef}
+          disabled={effectiveDisabled}
+          aria-invalid={resolvedError ? true : undefined}
+          aria-describedby={resolvedHelperText ? helperId : undefined}
+          className={cn(v.trigger(), slotProps?.trigger?.className)}
+        >
+          <span className={displayValue ? v.value() : v.placeholder()}>
+            {displayValue || placeholder || 'Select a time'}
+          </span>
+          <span className={v.icon()}>
+            <ClockIcon />
+          </span>
+        </button>
+      </Popover>
+
+      {resolvedHelperText && (
+        <p
+          id={helperId}
+          className={cn(
+            resolvedError ? v.errorText() : v.helperText(),
+            resolvedError
+              ? slotProps?.errorText?.className
+              : slotProps?.helperText?.className,
+          )}
+        >
+          {resolvedHelperText}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/TimePicker/timePicker.types.ts

@@ -0,0 +1,69 @@
+import type { ReactNode } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+
+/** Per-slot `className` overrides for `<TimePicker>`. */
+export interface TimePickerSlotProps {
+  root?: { className?: string };
+  label?: { className?: string };
+  requiredMark?: { className?: string };
+  trigger?: { className?: string };
+  helperText?: { className?: string };
+  errorText?: { className?: string };
+}
+
+/**
+ * Props for the `<TimePicker>` form field (Tailwind skin).
+ *
+ * A read-only trigger paired with a `<Calendar>`-style time-list popover.
+ * The stored value is a canonical 24-hour `"HH:mm"` string, or `null`.
+ * 12-hour notation (`hour12`) is display-only. No date, no timezone.
+ *
+ * The prop surface mirrors the MUI `@dashforge/ui` `TimePicker`.
+ */
+export interface TimePickerProps {
+  /** Field name — the bridge registration key. Required. */
+  name: string;
+  /** Validation rules forwarded to the form bridge. */
+  rules?: unknown;
+  /** Field label. */
+  label?: ReactNode;
+  /** Helper text below the control (overrides a bridge error message). */
+  helperText?: ReactNode;
+  /** 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 time is selected. */
+  placeholder?: string;
+  /** Label/control layout. */
+  layout?: 'stacked' | 'inline';
+  /** Reactive visibility predicate evaluated against the form engine. */
+  visibleWhen?: (engine: Engine) => boolean;
+  /** RBAC access requirement. */
+  access?: AccessRequirement;
+  /** Controlled value — `"HH:mm"` (24-hour) or `null`. */
+  value?: string | null;
+  /** Uncontrolled initial value. */
+  defaultValue?: string | null;
+  /** Fired with the new time (or `null` when cleared). */
+  onChange?: (value: string | null) => void;
+  /** Earliest selectable time, `"HH:mm"`. Default `"00:00"`. */
+  minTime?: string;
+  /** Latest selectable time, `"HH:mm"`. Default `"23:30"`. */
+  maxTime?: 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?: TimePickerSlotProps;
+  /** Test id applied to the field root. */
+  testId?: string;
+}

package/src/components/TimePicker/timePicker.variants.ts

@@ -0,0 +1,53 @@
+import { tv } from 'tailwind-variants';
+
+/**
+ * Slots for `<TimePicker>` — a bridge-integrated time field whose trigger
+ * is a `<button>` styled as an input, opening a time-list popover.
+ *
+ * Theme identity: bare neutral / brand token-backed classes only — no
+ * `dark:` variants on the neutral palette (the preset CSS-var swap
+ * auto-inverts). See `_shared/themeIdentity.test.ts`.
+ */
+export const timePickerVariants = tv({
+  slots: {
+    root: 'flex flex-col',
+    label: 'block text-sm font-medium text-neutral-900 mb-1',
+    requiredMark: 'text-danger-500 ml-0.5',
+    trigger:
+      'flex items-center gap-2 h-10 min-w-[10rem] rounded-md border border-neutral-300 bg-neutral-50 px-3 text-base text-neutral-900 cursor-pointer transition-colors hover:border-neutral-400 focus-visible:outline-none focus-visible:border-primary-500 focus-visible:ring-2 focus-visible:ring-primary-500/30 disabled:cursor-not-allowed disabled:opacity-60 disabled:bg-neutral-200',
+    value: 'flex-1 truncate text-left',
+    placeholder: 'flex-1 truncate text-left text-neutral-400',
+    icon: 'shrink-0 text-[1rem] text-neutral-500',
+    list: 'flex max-h-64 min-w-[8rem] flex-col gap-0.5 overflow-y-auto p-1',
+    option:
+      'flex w-full cursor-pointer items-center rounded px-2.5 py-1.5 text-sm text-neutral-900 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500 aria-selected:bg-primary-600 aria-selected:text-white aria-selected:hover:bg-primary-600 aria-disabled:cursor-default aria-disabled:text-neutral-300 aria-disabled:opacity-60 aria-disabled:hover:bg-transparent',
+    helperText: 'mt-1 text-sm text-neutral-600',
+    errorText: 'mt-1 text-sm text-danger-600',
+  },
+  variants: {
+    layout: {
+      stacked: {},
+      inline: {
+        root: 'flex-row items-start gap-3',
+        label: 'mb-0 pt-2.5 whitespace-nowrap shrink-0',
+      },
+    },
+    error: {
+      true: {
+        trigger:
+          'border-danger-500 hover:border-danger-500 focus-visible:border-danger-500 focus-visible:ring-danger-500/30',
+      },
+    },
+    fullWidth: {
+      true: {
+        root: 'w-full',
+        trigger: 'w-full min-w-0',
+      },
+    },
+  },
+  defaultVariants: {
+    layout: 'stacked',
+    error: false,
+    fullWidth: false,
+  },
+});

package/src/index.ts

@@ -95,21 +95,9 @@ export type {
 } from './components/Autocomplete/autocomplete.types.js';
 export { autocompleteVariants } from './components/Autocomplete/autocomplete.variants.js';
 
-// F5-B tier-3: native HTML5 date / time / datetime picker, bridge-integrated.
-
-export {
-  DateTimePicker,
-  isoToInputValue,
-} from './components/DateTimePicker/DateTimePicker.js';
-export type {
-  DateTimePickerProps,
-  DateTimePickerMode,
-  DateTimePickerSlotProps,
-} from './components/DateTimePicker/dateTimePicker.types.js';
-export { dateTimePickerVariants } from './components/DateTimePicker/dateTimePicker.variants.js';
-
-// Custom calendar suite — Calendar primitive + bridge-integrated DatePicker,
-// both built on the shared headless `@dashforge/calendar-core` engine.
+// Custom calendar suite — Calendar primitive + bridge-integrated DatePicker /
+// TimePicker / DateTimePicker / DateRangePicker, all built on the shared
+// headless `@dashforge/calendar-core` engine.
 
 export { Calendar } from './components/Calendar/Calendar.js';
 export type {
@@ -128,6 +116,30 @@ export type {
 } from './components/DatePicker/datePicker.types.js';
 export { datePickerVariants } from './components/DatePicker/datePicker.variants.js';
 
+export { TimePicker } from './components/TimePicker/TimePicker.js';
+export type {
+  TimePickerProps,
+  TimePickerSlotProps,
+} from './components/TimePicker/timePicker.types.js';
+export { timePickerVariants } from './components/TimePicker/timePicker.variants.js';
+
+export { DateTimePicker } from './components/DateTimePicker/DateTimePicker.js';
+export type {
+  DateTimePickerProps,
+  DateTimePickerSlotProps,
+} from './components/DateTimePicker/dateTimePicker.types.js';
+export { dateTimePickerVariants } from './components/DateTimePicker/dateTimePicker.variants.js';
+
+export { DateRangePicker } from './components/DateRangePicker/DateRangePicker.js';
+export type {
+  DateRangePickerProps,
+  DateRangePickerSlotProps,
+} from './components/DateRangePicker/dateRangePicker.types.js';
+export {
+  dateRangePickerVariants,
+  dateRangeDayVariants,
+} from './components/DateRangePicker/dateRangePicker.variants.js';
+
 // F6 layout: router-agnostic navigation primitives.
 
 export { Breadcrumbs } from './components/Breadcrumbs/Breadcrumbs.js';
@@ -373,4 +385,4 @@ export type { VariantProps } from 'tailwind-variants';
 /**
  * Package version (synced with `package.json` at publish time).
  */
-export const VERSION = '0.9.1-beta';
+export const VERSION = '0.10.0-beta';