@dashforge/tw 0.9.0-beta → 0.10.0-beta

package/src/components/Calendar/calendar.variants.ts

@@ -0,0 +1,64 @@
+import { tv } from 'tailwind-variants';
+
+/**
+ * Structural slots for `<Calendar>`.
+ *
+ * Theme identity: every class is a bare neutral / brand token-backed
+ * Tailwind class. The `dashforgePreset()` CSS-variable swap auto-inverts
+ * the neutral palette, so there are NO `dark:` variants here (a `dark:` on
+ * a neutral class would double-invert — see `_shared/themeIdentity.test.ts`).
+ */
+export const calendarVariants = tv({
+  slots: {
+    root: 'inline-flex w-fit flex-col gap-2 rounded-lg border border-neutral-200 bg-neutral-50 p-3 select-none',
+    header: 'flex items-center justify-between gap-1',
+    navButton:
+      'inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[1rem] text-neutral-600 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 disabled:pointer-events-none disabled:opacity-40',
+    monthLabel: 'flex-1 text-center text-sm font-semibold text-neutral-900',
+    grid: 'flex flex-col gap-1 focus:outline-none',
+    weekdayRow: 'grid grid-cols-7 gap-1',
+    weekday:
+      'flex h-8 items-center justify-center text-xs font-semibold text-neutral-500',
+    weekRow: 'grid grid-cols-7 gap-1',
+  },
+  variants: {
+    disabled: {
+      true: { root: 'opacity-60' },
+    },
+  },
+  defaultVariants: {
+    disabled: false,
+  },
+});
+
+/**
+ * Per-day-cell recipe. Each of the 42 grid cells is rendered with its own
+ * state (`siblingMonth` / `today` / `selected` / `disabled`).
+ */
+export const calendarDayVariants = tv({
+  base: 'flex h-9 w-9 items-center justify-center rounded-md 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',
+  variants: {
+    siblingMonth: {
+      true: 'text-neutral-400',
+    },
+    today: {
+      true: 'font-bold ring-1 ring-inset ring-primary-400',
+    },
+    selected: {
+      true: 'bg-primary-600 text-white hover:bg-primary-600',
+    },
+    disabled: {
+      true: 'cursor-default text-neutral-300 opacity-60 hover:bg-transparent',
+    },
+  },
+  compoundVariants: [
+    // A selected cell drops the "today" ring — the solid fill is enough.
+    { selected: true, today: true, class: 'ring-0' },
+  ],
+  defaultVariants: {
+    siblingMonth: false,
+    today: false,
+    selected: false,
+    disabled: false,
+  },
+});

package/src/components/DatePicker/DatePicker.test.tsx

@@ -0,0 +1,76 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+
+import { DatePicker } from './DatePicker.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('DatePicker', () => {
+  it('renders a labelled trigger with the placeholder', () => {
+    render(
+      <DatePicker name="birthday" label="Birthday" placeholder="Pick one" />,
+    );
+    expect(screen.queryByText('Birthday')).not.toBeNull();
+    expect(screen.getByRole('button').textContent).toContain('Pick one');
+  });
+
+  it('shows a localized controlled value', () => {
+    render(<DatePicker name="d" value="2026-05-20" />);
+    expect(screen.getByRole('button').textContent).toContain('May 20, 2026');
+  });
+
+  it('opens and toggles the calendar popover from the trigger', () => {
+    render(<DatePicker name="d" defaultValue="2026-05-20" />);
+    const trigger = screen.getByRole('button');
+    expect(screen.queryByRole('dialog')).toBeNull();
+    fireEvent.click(trigger);
+    expect(screen.queryByRole('dialog')).not.toBeNull();
+    fireEvent.click(trigger);
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('selects a date from the popover, updates the trigger and closes', () => {
+    const onChange = vi.fn();
+    render(
+      <DatePicker name="d" defaultValue="2026-05-20" onChange={onChange} />,
+    );
+    fireEvent.click(screen.getByRole('button'));
+    fireEvent.click(screen.getByRole('button', { name: /May 15, 2026/ }));
+    expect(onChange).toHaveBeenCalledWith('2026-05-15');
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(screen.getByRole('button').textContent).toContain('May 15, 2026');
+  });
+
+  it('keeps a controlled value fixed but still reports the change', () => {
+    const onChange = vi.fn();
+    render(<DatePicker name="d" value="2026-05-20" onChange={onChange} />);
+    fireEvent.click(screen.getByRole('button'));
+    fireEvent.click(screen.getByRole('button', { name: /May 15, 2026/ }));
+    expect(onChange).toHaveBeenCalledWith('2026-05-15');
+    expect(screen.getByRole('button').textContent).toContain('May 20, 2026');
+  });
+
+  it('does not open the popover when disabled', () => {
+    render(<DatePicker name="d" disabled />);
+    fireEvent.click(screen.getByRole('button'));
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+});

package/src/components/DatePicker/DatePicker.tsx

@@ -0,0 +1,305 @@
+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 { 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 { datePickerVariants } from './datePicker.variants.js';
+import type { DatePickerProps } from './datePicker.types.js';
+
+// 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>
+  );
+}
+
+/**
+ * Formats a stored ISO date for the trigger display, localized to a medium
+ * date style (e.g. `"May 20, 2026"`). Formatting is done in UTC so the
+ * displayed day always matches the stored `YYYY-MM-DD`.
+ */
+function formatDisplayDate(
+  iso: ISODate | null | undefined,
+  locale: string,
+): string {
+  if (iso == null || iso === '') {
+    return '';
+  }
+  const parts = parseISODate(iso);
+  if (parts === null) {
+    return iso;
+  }
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: 'medium',
+    timeZone: 'UTC',
+  }).format(Date.UTC(parts.year, parts.month - 1, parts.day));
+}
+
+/**
+ * Dashforge TW `<DatePicker>` — a form-bound single-date field.
+ *
+ * A read-only trigger button paired with a `<Calendar>` popover (Radix
+ * Popover — toggle / Escape / outside-click / focus-trap are Radix-managed).
+ * Integrates with the Dashforge form bridge + RBAC, mirroring the other
+ * `@dashforge/tw` form fields.
+ *
+ * Storage contract: an ISO `YYYY-MM-DD` string, or `null` — shared with the
+ * MUI `@dashforge/ui` `DatePicker`.
+ */
+export function DatePicker(props: DatePickerProps) {
+  const {
+    name,
+    rules,
+    label,
+    helperText,
+    error,
+    required,
+    disabled,
+    placeholder,
+    layout = 'stacked',
+    visibleWhen,
+    access,
+    value: explicitValue,
+    defaultValue,
+    onChange,
+    minDate,
+    maxDate,
+    disabledDates,
+    isDateDisabled,
+    weekStartDay,
+    locale,
+    fullWidth,
+    sx,
+    slotProps,
+    testId,
+  } = props;
+
+  // ───── Hooks (unconditional, before any early return) ─────
+  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<ISODate | 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 () => {
+      isMountedRef.current = false;
+      const { bridge: cap, name: capName } = unregisterRef.current;
+      queueMicrotask(() => {
+        if (!isMountedRef.current) cap?.unregister?.(capName);
+      });
+    };
+  }, []);
+
+  // ───── Derived ─────
+  const effectiveDisabled = Boolean(disabled) || accessState.disabled;
+  const effectiveReadOnly = accessState.readonly;
+  const isInteractive = !effectiveDisabled && !effectiveReadOnly;
+  const isFormMode = Boolean(bridge?.register);
+
+  let resolvedError = error;
+  let resolvedHelperText: typeof helperText = helperText;
+  let registration: FieldRegistration | null = null;
+  let resolvedValue: ISODate | 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;
+  }
+
+  // RHF threads its own callback ref through here in form mode.
+  const registrationRefFn = registration?.ref;
+  const triggerRef = useCallback(
+    (instance: HTMLButtonElement | null) => {
+      if (typeof registrationRefFn === 'function') {
+        registrationRefFn(instance);
+      }
+    },
+    [registrationRefFn],
+  );
+
+  // ───── Render-time guards (after all hooks) ─────
+  if (!isVisible) return null;
+  if (!accessState.visible) return null;
+
+  const v = datePickerVariants({
+    layout,
+    error: resolvedError,
+    fullWidth,
+  });
+  const resolvedLocale = locale ?? 'en-US';
+  const displayValue = formatDisplayDate(resolvedValue, resolvedLocale);
+
+  const commitValue = (next: ISODate | 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);
+  };
+
+  // Mark the field touched on popover close. Reads the freshest committed
+  // value straight from the bridge so the touched-blur never reverts a
+  // value just chosen in the calendar.
+  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 handleCalendarChange = (next: ISODate) => {
+    commitValue(next);
+    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={
+          <Calendar
+            value={resolvedValue}
+            onChange={handleCalendarChange}
+            minDate={minDate}
+            maxDate={maxDate}
+            disabledDates={disabledDates}
+            isDateDisabled={isDateDisabled}
+            weekStartDay={weekStartDay}
+            locale={locale}
+            aria-label="Choose date"
+            sx="border-0 bg-transparent p-0"
+          />
+        }
+      >
+        <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 date'}
+          </span>
+          <span className={v.icon()}>
+            <CalendarIcon />
+          </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/DatePicker/datePicker.types.ts

@@ -0,0 +1,77 @@
+import type { ReactNode } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { ISODate, WeekDay } from '@dashforge/calendar-core';
+
+/** Per-slot `className` overrides for `<DatePicker>`. */
+export interface DatePickerSlotProps {
+  root?: { className?: string };
+  label?: { className?: string };
+  requiredMark?: { className?: string };
+  trigger?: { className?: string };
+  helperText?: { className?: string };
+  errorText?: { className?: string };
+}
+
+/**
+ * Props for the `<DatePicker>` form field (Tailwind skin).
+ *
+ * A read-only trigger button paired with a `<Calendar>` popover, integrated
+ * with the Dashforge form bridge + RBAC. The stored value is a plain ISO
+ * calendar date — `YYYY-MM-DD` — or `null`. (A pure date carries no time or
+ * timezone, which removes the whole class of DST round-trip hazards.)
+ *
+ * The prop surface mirrors the MUI `@dashforge/ui` `DatePicker` so the API
+ * is consistent across both ecosystems; only the styling escape hatches
+ * (`sx` / `slotProps`) follow the Tailwind conventions.
+ */
+export interface DatePickerProps {
+  /** 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 date 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 — ISO `YYYY-MM-DD` or `null`. */
+  value?: ISODate | null;
+  /** Uncontrolled initial value. */
+  defaultValue?: ISODate | null;
+  /** Fired with the new ISO date (or `null` when cleared). */
+  onChange?: (value: ISODate | 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;
+  /** Stretches the field to its container width. */
+  fullWidth?: boolean;
+  /** Root-level Tailwind class override. */
+  sx?: string;
+  /** Per-slot `className` overrides. */
+  slotProps?: DatePickerSlotProps;
+  /** Test id applied to the field root. */
+  testId?: string;
+}

package/src/components/DatePicker/datePicker.variants.ts

@@ -0,0 +1,50 @@
+import { tv } from 'tailwind-variants';
+
+/**
+ * Slots for `<DatePicker>` — a bridge-integrated date field whose trigger
+ * is a `<button>` styled as an input, opening a `<Calendar>` 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 datePickerVariants = 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-[12rem] 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',
+    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/components/DateRangePicker/DateRangePicker.test.tsx

@@ -0,0 +1,92 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+
+import { DateRangePicker } from './DateRangePicker.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('DateRangePicker', () => {
+  it('renders a labelled trigger with the placeholder', () => {
+    render(
+      <DateRangePicker name="period" label="Period" placeholder="Pick a range" />,
+    );
+    expect(screen.queryByText('Period')).not.toBeNull();
+    expect(screen.getByRole('button').textContent).toContain('Pick a range');
+  });
+
+  it('shows a localized controlled range', () => {
+    render(
+      <DateRangePicker
+        name="p"
+        value={{ start: '2026-05-10', end: '2026-05-15' }}
+      />,
+    );
+    expect(screen.getByRole('button').textContent).toContain(
+      'May 10, 2026 – May 15, 2026',
+    );
+  });
+
+  it('opens a dual-month popover from the trigger', () => {
+    render(
+      <DateRangePicker name="p" defaultValue={{ start: '2026-05-10', end: null }} />,
+    );
+    expect(screen.queryByRole('dialog')).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: /Select|May/ }));
+    expect(screen.queryByRole('dialog')).not.toBeNull();
+    expect(screen.getAllByRole('grid')).toHaveLength(2);
+  });
+
+  it('completes the range on the second click and closes the popover', () => {
+    const onChange = vi.fn();
+    render(
+      <DateRangePicker
+        name="p"
+        defaultValue={{ start: '2026-05-10', end: null }}
+        onChange={onChange}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: /May 10/ }));
+    fireEvent.click(screen.getByRole('button', { name: /May 18, 2026/ }));
+    expect(onChange).toHaveBeenCalledWith({ start: '2026-05-10', end: '2026-05-18' });
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+
+  it('restarts the range on a fresh click and keeps the popover open', () => {
+    const onChange = vi.fn();
+    render(
+      <DateRangePicker
+        name="p"
+        defaultValue={{ start: '2026-05-20', end: '2026-05-25' }}
+        onChange={onChange}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: /May 20/ }));
+    fireEvent.click(screen.getByRole('button', { name: /May 12, 2026/ }));
+    expect(onChange).toHaveBeenCalledWith({ start: '2026-05-12', end: null });
+    expect(screen.queryByRole('dialog')).not.toBeNull();
+  });
+
+  it('does not open the popover when disabled', () => {
+    render(<DateRangePicker name="p" disabled />);
+    fireEvent.click(screen.getByRole('button'));
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+});