@dashforge/tw 0.9.0-beta → 0.9.1-beta

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/index.ts

@@ -108,6 +108,26 @@ export type {
 } 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.
+
+export { Calendar } from './components/Calendar/Calendar.js';
+export type {
+  CalendarProps,
+  CalendarSlotProps,
+} from './components/Calendar/calendar.types.js';
+export {
+  calendarVariants,
+  calendarDayVariants,
+} from './components/Calendar/calendar.variants.js';
+
+export { DatePicker } from './components/DatePicker/DatePicker.js';
+export type {
+  DatePickerProps,
+  DatePickerSlotProps,
+} from './components/DatePicker/datePicker.types.js';
+export { datePickerVariants } from './components/DatePicker/datePicker.variants.js';
+
 // F6 layout: router-agnostic navigation primitives.
 
 export { Breadcrumbs } from './components/Breadcrumbs/Breadcrumbs.js';
@@ -353,4 +373,4 @@ export type { VariantProps } from 'tailwind-variants';
 /**
  * Package version (synced with `package.json` at publish time).
  */
-export const VERSION = '0.7.0-beta';
+export const VERSION = '0.9.1-beta';

package/tsconfig.lib.json

@@ -40,16 +40,19 @@
       "path": "../ui-core/tsconfig.lib.json"
     },
     {
-      "path": "../tw-tokens/tsconfig.lib.json"
+      "path": "../rbac/tsconfig.lib.json"
     },
     {
-      "path": "../tw-theme/tsconfig.lib.json"
+      "path": "../forms/tsconfig.lib.json"
     },
     {
-      "path": "../rbac/tsconfig.lib.json"
+      "path": "../calendar-core/tsconfig.lib.json"
     },
     {
-      "path": "../forms/tsconfig.lib.json"
+      "path": "../tw-tokens/tsconfig.lib.json"
+    },
+    {
+      "path": "../tw-theme/tsconfig.lib.json"
     }
   ]
 }