@dashforge/tw 1.1.0 → 1.2.0

package/src/components/DateRangePicker/DateRangePicker.tsx

@@ -1,510 +0,0 @@
-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

@@ -1,74 +0,0 @@
-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

@@ -1,101 +0,0 @@
-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,
-  },
-});