@dashforge/tw 0.9.1-beta → 0.11.0-beta

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.11.0-beta';

package/src/components/DateTimePicker/DateTimePicker.perf.test.tsx

@@ -1,153 +0,0 @@
-// @vitest-environment jsdom
-/**
- * Performance + re-render budget tests for `<DateTimePicker>`.
- *
- * Guardrails — not absolute benchmarks. They protect against:
- *
- *  1. Pathological mount cost (an accidental quadratic in a future
- *     refactor — much less likely here than in `<Autocomplete>` because
- *     there's no option list, but the test still pins the budget).
- *
- *  2. Sibling re-renders on every keystroke. The bridge subscription
- *     model (`useDashFieldMeta(name)`) must remain GRANULAR — only the
- *     field whose value changed re-renders, never a sibling.
- *
- *  3. Linear render budget per keystroke for THIS field. Aim for 1
- *     render per `onChange`; tolerate 2 (RHF / engine reactive snapshot
- *     batching).
- *
- *  4. Mode switch isn't accidentally expensive (cycling between
- *     `date` / `time` / `datetime` mounts a NEW native input each time
- *     — but the component itself must not allocate per-key arrays etc.).
- */
-import { describe, it, expect } from 'vitest';
-import { render, fireEvent, screen } from '@testing-library/react';
-import { DashFormProvider } from '@dashforge/forms';
-import { DateTimePicker, TextField } from '../../index.js';
-
-function withRenderCounter<P>(
-  Component: React.ComponentType<P>,
-  counterRef: { count: number }
-): React.FC<P> {
-  return function Counted(props: P) {
-    counterRef.count++;
-    return <Component {...(props as P & object)} />;
-  };
-}
-
-describe('<DateTimePicker> performance', () => {
-  it('mounts well under 50ms (standalone, no bridge)', () => {
-    const t0 = performance.now();
-    render(<DateTimePicker name="d" label="Date" />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(50);
-  });
-
-  it('mounts under 100ms inside DashFormProvider (with bridge wiring)', () => {
-    const t0 = performance.now();
-    render(
-      <DashFormProvider defaultValues={{ d: '2026-05-16' }}>
-        <DateTimePicker name="d" label="Date" />
-      </DashFormProvider>
-    );
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(100);
-  });
-
-  it('processes a value change in under 20ms', () => {
-    render(<DateTimePicker name="d" label="Date" />);
-    const input = screen.getByLabelText('Date') as HTMLInputElement;
-    const t0 = performance.now();
-    fireEvent.change(input, { target: { value: '2026-12-25' } });
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(20);
-  });
-});
-
-describe('<DateTimePicker> re-render budget', () => {
-  it('renders at most 2 times on mount', () => {
-    const counter = { count: 0 };
-    const Counted = withRenderCounter(DateTimePicker, counter);
-    render(<Counted name="d" label="Date" />);
-    // 1 initial + (tolerate 1 follow-up commit for any setState
-    // scheduled in a useEffect; today we don't schedule any, but the
-    // budget allows headroom).
-    expect(counter.count).toBeLessThanOrEqual(2);
-  });
-
-  it('keeps controlled re-renders ≤ 1 per value prop change', () => {
-    const counter = { count: 0 };
-    const Counted = withRenderCounter(DateTimePicker, counter);
-    const { rerender } = render(
-      <Counted name="d" label="Date" value="2026-01-01" />
-    );
-    const baseline = counter.count;
-    rerender(<Counted name="d" label="Date" value="2026-01-02" />);
-    rerender(<Counted name="d" label="Date" value="2026-01-03" />);
-    rerender(<Counted name="d" label="Date" value="2026-01-04" />);
-    // 3 prop changes ⇒ ≤ 4 renders (one per change + tolerance).
-    expect(counter.count - baseline).toBeLessThanOrEqual(4);
-  });
-
-  it('does NOT re-render an unrelated sibling on each value change', () => {
-    // Critical perf property: typing into one DateTimePicker must not
-    // cause sibling components to re-render. Granular per-field
-    // subscription via `useDashFieldMeta(name)` is what enforces this.
-    const sibCount = { count: 0 };
-    const Sibling = () => {
-      sibCount.count++;
-      return <div data-testid="sib" />;
-    };
-    render(
-      <DashFormProvider defaultValues={{ d: '2026-01-01', other: 'x' }}>
-        <DateTimePicker name="d" label="Date" />
-        <Sibling />
-      </DashFormProvider>
-    );
-    const before = sibCount.count;
-    const input = screen.getByLabelText('Date') as HTMLInputElement;
-    for (let i = 1; i <= 5; i++) {
-      fireEvent.change(input, {
-        target: { value: `2026-01-0${i + 1}` },
-      });
-    }
-    expect(sibCount.count).toBe(before);
-  });
-
-  it('does NOT re-render when a sibling field changes (per-field subscription)', () => {
-    // Inverse of the above: changing the OTHER field in the bridge
-    // must not re-render the DateTimePicker. Verifies the granular
-    // `useDashFieldMeta` subscription is filtering by name.
-    const dtCount = { count: 0 };
-    const Counted = withRenderCounter(DateTimePicker, dtCount);
-    render(
-      <DashFormProvider defaultValues={{ d: '2026-01-01', other: '' }}>
-        <Counted name="d" label="Date" />
-        <TextField name="other" label="Other" />
-      </DashFormProvider>
-    );
-    const baseline = dtCount.count;
-    const other = screen.getByLabelText('Other') as HTMLInputElement;
-    for (let i = 0; i < 5; i++) {
-      fireEvent.change(other, { target: { value: 'a'.repeat(i + 1) } });
-    }
-    // The DateTimePicker may re-render once on initial mount of the
-    // sibling (parent re-render propagation) but NOT on each sibling
-    // keystroke. Budget: 0 additional renders.
-    expect(dtCount.count - baseline).toBeLessThanOrEqual(1);
-  });
-
-  it('mode switch (date ⇄ datetime) does not leak the previous native input', () => {
-    // Switching `mode` changes the native element's `type` attribute —
-    // React reuses the same DOM node (no remount). Assert that the
-    // input element identity is preserved.
-    const { rerender, container } = render(
-      <DateTimePicker name="d" label="X" mode="date" />
-    );
-    const inputBefore = container.querySelector('input');
-    rerender(<DateTimePicker name="d" label="X" mode="datetime" />);
-    const inputAfter = container.querySelector('input');
-    expect(inputBefore).toBe(inputAfter);
-    expect((inputAfter as HTMLInputElement).type).toBe('datetime-local');
-  });
-});