@dashforge/tw 0.9.0-beta → 0.10.0-beta

package/src/components/DateRangePicker/DateRangePicker.tsx

@@ -0,0 +1,510 @@
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from 'react';
+import type { KeyboardEvent } from 'react';
+import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
+import type { DashFormBridge, FieldRegistration } from '@dashforge/ui-core';
+import { useDashFieldMeta } from '@dashforge/forms';
+import {
+  formatLongDate,
+  parseISODate,
+  resolveCalendarKey,
+  useDateRange,
+} from '@dashforge/calendar-core';
+import type { DateRange, ISODate, WeekDay } 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 {
+  dateRangeDayVariants,
+  dateRangePickerVariants,
+} from './dateRangePicker.variants.js';
+import type { DateRangePickerProps } from './dateRangePicker.types.js';
+
+const EMPTY_RANGE: DateRange = { start: null, end: null };
+
+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>
+  );
+}
+
+function ChevronLeftIcon() {
+  return (
+    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <path
+        d="M10 4 6 8l4 4"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+function ChevronRightIcon() {
+  return (
+    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <path
+        d="m6 4 4 4-4 4"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+/** Formats a stored ISO date for the trigger display (medium style). */
+function formatEndpoint(iso: ISODate | null, 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));
+}
+
+function formatRange(range: DateRange, locale: string): string {
+  const start = formatEndpoint(range.start, locale);
+  const end = formatEndpoint(range.end, locale);
+  if (start === '') {
+    return '';
+  }
+  return end === '' ? start : `${start} – ${end}`;
+}
+
+interface RangeCalendarProps {
+  value: DateRange;
+  onChange: (range: DateRange) => void;
+  minDate?: ISODate;
+  maxDate?: ISODate;
+  disabledDates?: readonly ISODate[];
+  isDateDisabled?: (date: ISODate) => boolean;
+  weekStartDay?: WeekDay;
+  locale?: string;
+}
+
+/** The dual-month range grid rendered inside the popover. */
+function RangeCalendar(props: RangeCalendarProps) {
+  const {
+    value,
+    onChange,
+    minDate,
+    maxDate,
+    disabledDates,
+    isDateDisabled,
+    weekStartDay,
+    locale,
+  } = props;
+
+  const range = useDateRange({
+    value,
+    onChange,
+    monthCount: 2,
+    ...(minDate !== undefined && { minDate }),
+    ...(maxDate !== undefined && { maxDate }),
+    ...(disabledDates !== undefined && { disabledDates }),
+    ...(isDateDisabled !== undefined && { isDateDisabled }),
+    ...(weekStartDay !== undefined && { weekStartDay }),
+    ...(locale !== undefined && { locale }),
+  });
+
+  const focusedCellRef = useRef<HTMLButtonElement | null>(null);
+  const shouldFocusRef = useRef(false);
+  useEffect(() => {
+    if (shouldFocusRef.current && focusedCellRef.current) {
+      focusedCellRef.current.focus({ preventScroll: true });
+      shouldFocusRef.current = false;
+    }
+  }, [range.focusedDate]);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const action = resolveCalendarKey(event.key);
+    if (action === null) {
+      return;
+    }
+    event.preventDefault();
+    shouldFocusRef.current = true;
+    switch (action) {
+      case 'select':
+        range.selectDate(range.focusedDate);
+        break;
+      case 'monthForward':
+        range.goToNextMonth();
+        break;
+      case 'monthBackward':
+        range.goToPreviousMonth();
+        break;
+      default:
+        range.navigate(action);
+    }
+  };
+
+  const v = dateRangePickerVariants();
+  const resolvedLocale = locale ?? 'en-US';
+  const lastIndex = range.months.length - 1;
+
+  return (
+    <div
+      className={v.panel()}
+      onMouseLeave={() => {
+        range.hoverDate(null);
+      }}
+    >
+      {range.months.map((monthView, monthIndex) => (
+        <div
+          key={`${String(monthView.year)}-${String(monthView.month)}`}
+          className={v.month()}
+        >
+          <div className={v.header()}>
+            {monthIndex === 0 ? (
+              <button
+                type="button"
+                className={v.navButton()}
+                aria-label="Previous month"
+                onClick={() => {
+                  range.goToPreviousMonth();
+                }}
+              >
+                <ChevronLeftIcon />
+              </button>
+            ) : (
+              <span className={v.navSpacer()} />
+            )}
+            <span aria-live="polite" className={v.monthLabel()}>
+              {monthView.monthLabel}
+            </span>
+            {monthIndex === lastIndex ? (
+              <button
+                type="button"
+                className={v.navButton()}
+                aria-label="Next month"
+                onClick={() => {
+                  range.goToNextMonth();
+                }}
+              >
+                <ChevronRightIcon />
+              </button>
+            ) : (
+              <span className={v.navSpacer()} />
+            )}
+          </div>
+
+          <div
+            role="grid"
+            aria-label="Choose date range"
+            onKeyDown={handleKeyDown}
+            className={v.grid()}
+          >
+            <div role="row" className={v.weekdayRow()}>
+              {range.weekdayNames.map((dayName, index) => (
+                <span
+                  key={`weekday-${String(index)}`}
+                  role="columnheader"
+                  className={v.weekday()}
+                >
+                  {dayName}
+                </span>
+              ))}
+            </div>
+
+            {monthView.weeks.map((week) => (
+              <div key={week.key} role="row" className={v.weekRow()}>
+                {week.days.map((day) => {
+                  const isActiveCell = day.iso === range.focusedDate;
+                  const endpoint = day.isRangeStart || day.isRangeEnd;
+                  const inBand = day.isInRange || day.isRangePreview;
+                  return (
+                    <span key={day.iso} role="gridcell" className="flex">
+                      <button
+                        type="button"
+                        ref={isActiveCell ? focusedCellRef : null}
+                        tabIndex={isActiveCell ? 0 : -1}
+                        aria-label={formatLongDate(
+                          { year: day.year, month: day.month, day: day.day },
+                          resolvedLocale,
+                        )}
+                        aria-current={day.isToday ? 'date' : undefined}
+                        aria-pressed={endpoint}
+                        aria-disabled={day.isDisabled}
+                        onClick={() => {
+                          range.selectDate(day.iso);
+                        }}
+                        onMouseEnter={() => {
+                          range.hoverDate(day.iso);
+                        }}
+                        className={dateRangeDayVariants({
+                          inBand,
+                          endpoint,
+                          siblingMonth: day.isSiblingMonth,
+                          today: day.isToday,
+                          disabled: day.isDisabled,
+                        })}
+                      >
+                        {day.day}
+                      </button>
+                    </span>
+                  );
+                })}
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Dashforge TW `<DateRangePicker>` — a form-bound start/end date field.
+ *
+ * A read-only trigger button paired with a dual-month range calendar popover
+ * (Radix Popover), built on the headless `useDateRange` engine. Integrates
+ * with the Dashforge form bridge + RBAC.
+ *
+ * Storage contract: a `{ start, end }` pair of ISO `YYYY-MM-DD` dates —
+ * shared with the MUI `@dashforge/ui` `DateRangePicker`.
+ */
+export function DateRangePicker(props: DateRangePickerProps) {
+  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;
+
+  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<DateRange>(
+    defaultValue ?? EMPTY_RANGE,
+  );
+
+  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: DateRange;
+
+  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 as DateRange | null | undefined;
+      resolvedValue = bv ?? EMPTY_RANGE;
+    }
+  } 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 = dateRangePickerVariants({ layout, error: resolvedError, fullWidth });
+  const resolvedLocale = locale ?? 'en-US';
+  const displayValue = formatRange(resolvedValue, resolvedLocale);
+
+  const commitValue = (next: DateRange) => {
+    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 },
+        type: 'blur',
+      });
+    }
+  };
+
+  const handleOpenChange = (next: boolean) => {
+    if (next && !isInteractive) {
+      return;
+    }
+    setIsOpen(next);
+    if (!next) {
+      markTouched();
+    }
+  };
+
+  const handleRangeChange = (next: DateRange) => {
+    commitValue(next);
+    if (next.start !== null && next.end !== null) {
+      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={
+          <RangeCalendar
+            value={resolvedValue}
+            onChange={handleRangeChange}
+            minDate={minDate}
+            maxDate={maxDate}
+            disabledDates={disabledDates}
+            isDateDisabled={isDateDisabled}
+            weekStartDay={weekStartDay}
+            locale={locale}
+          />
+        }
+      >
+        <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 range'}
+          </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/DateRangePicker/dateRangePicker.types.ts

@@ -0,0 +1,74 @@
+import type { ReactNode } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { DateRange, ISODate, WeekDay } from '@dashforge/calendar-core';
+
+/** Per-slot `className` overrides for `<DateRangePicker>`. */
+export interface DateRangePickerSlotProps {
+  root?: { className?: string };
+  label?: { className?: string };
+  requiredMark?: { className?: string };
+  trigger?: { className?: string };
+  helperText?: { className?: string };
+  errorText?: { className?: string };
+}
+
+/**
+ * Props for the `<DateRangePicker>` form field (Tailwind skin).
+ *
+ * A read-only trigger paired with a dual-month range calendar popover. The
+ * stored value is a `{ start, end }` pair of plain ISO calendar dates
+ * (`YYYY-MM-DD`); either side may be `null`. No time, no timezone.
+ *
+ * The prop surface mirrors the MUI `@dashforge/ui` `DateRangePicker`.
+ */
+export interface DateRangePickerProps {
+  /** 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 range 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 — a `{ start, end }` pair. */
+  value?: DateRange;
+  /** Uncontrolled initial value. */
+  defaultValue?: DateRange;
+  /** Fired with the new range (partial on the first click, complete on the second). */
+  onChange?: (value: DateRange) => 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?: DateRangePickerSlotProps;
+  /** Test id applied to the field root. */
+  testId?: string;
+}

package/src/components/DateRangePicker/dateRangePicker.variants.ts

@@ -0,0 +1,101 @@
+import { tv } from 'tailwind-variants';
+
+/**
+ * Slots for `<DateRangePicker>` — a bridge-integrated start/end date field
+ * whose trigger is a `<button>` styled as an input, opening a dual-month
+ * range 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 dateRangePickerVariants = 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-[15rem] 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 gap-3 p-3 select-none',
+    month: 'flex flex-col gap-2',
+    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',
+    navSpacer: 'h-7 w-7 shrink-0',
+    monthLabel: 'flex-1 text-center text-sm font-semibold text-neutral-900',
+    grid: 'flex flex-col gap-1',
+    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',
+    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,
+  },
+});
+
+/**
+ * Per-day-cell recipe for the range grid. `endpoint` (a committed start/end)
+ * is the solid fill; `inBand` (inside the committed or previewed range) is
+ * the light tint. Declared `inBand` before `endpoint` so an endpoint cell —
+ * which is also in-band — resolves to the solid fill.
+ */
+export const dateRangeDayVariants = 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: {
+    inBand: {
+      true: 'bg-primary-100 hover:bg-primary-100',
+    },
+    endpoint: {
+      true: 'bg-primary-600 text-white hover:bg-primary-600',
+    },
+    siblingMonth: {
+      true: 'text-neutral-400',
+    },
+    today: {
+      true: 'font-bold ring-1 ring-inset ring-primary-400',
+    },
+    disabled: {
+      true: 'cursor-default text-neutral-300 opacity-60 hover:bg-transparent',
+    },
+  },
+  compoundVariants: [
+    { endpoint: true, today: true, class: 'ring-0' },
+    { endpoint: true, siblingMonth: true, class: 'text-white' },
+  ],
+  defaultVariants: {
+    inBand: false,
+    endpoint: false,
+    siblingMonth: false,
+    today: false,
+    disabled: false,
+  },
+});