@dashforge/tw 1.1.0 → 1.2.0

package/src/components/DatePicker/DatePicker.tsx

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

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

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

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