@emara/ui 1.1.0

package/components/ui/date-picker.tsx

@@ -0,0 +1,597 @@
+"use client";
+
+import { forwardRef, useId, useMemo, useState } from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import {
+  RiArrowLeftSLine,
+  RiArrowRightSLine,
+  RiCalendar2Line,
+  RiCloseLine,
+} from "@remixicon/react";
+import { format as fnsFormat, parse as fnsParse } from "date-fns";
+import { ar, enUS, fr } from "date-fns/locale";
+import { DayPicker, type DayPickerProps } from "react-day-picker";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-2-components.md §6.
+// First pass: single mode + locale + format + min/max + numberingSystem.
+// Range / multiple / inline / presets come in subsequent slices per the v0.3
+// implementation plan.
+
+// ----------------------------------------------------------------------------
+// Numbering system helpers
+// ----------------------------------------------------------------------------
+
+type NumberingSystem = "latn" | "arab";
+
+/**
+ * Build a Intl.NumberFormat configured for a given locale + numbering system.
+ * Used to translate day numbers, week numbers, and year labels when the
+ * consumer asks for non-Latin numerals (e.g. ar/arab → ٠١٢٣٤٥٦٧٨٩).
+ */
+function buildNumberFormatter(
+  locale: string | undefined,
+  system: NumberingSystem,
+): Intl.NumberFormat {
+  // BCP-47 extension subtag `-u-nu-<system>` is the standard way to attach
+  // a numbering system. Works even when the base locale isn't recognized.
+  const base = locale ?? "en-US";
+  try {
+    return new Intl.NumberFormat(`${base}-u-nu-${system}`);
+  } catch {
+    return new Intl.NumberFormat("en-US");
+  }
+}
+
+/** Replace ASCII digits 0-9 in `s` with the equivalents from `nf`. */
+function translateDigits(s: string, nf: Intl.NumberFormat): string {
+  return s.replace(/[0-9]/g, (d) => nf.format(Number(d)));
+}
+
+// ----------------------------------------------------------------------------
+// Locale registry — small built-in set; consumers can extend via the
+// `localeObject` prop when they need a locale not listed here.
+// ----------------------------------------------------------------------------
+
+const BUILT_IN_LOCALES: Record<string, Locale> = {
+  "en-US": enUS,
+  fr: fr,
+  "fr-FR": fr,
+  "fr-MA": fr,
+  ar: ar,
+  "ar-MA": ar,
+};
+
+type Locale = typeof enUS;
+
+function resolveLocale(locale: string | undefined, override: Locale | undefined): Locale {
+  if (override) return override;
+  if (locale && BUILT_IN_LOCALES[locale]) return BUILT_IN_LOCALES[locale]!;
+  // Fall back to a 2-letter prefix lookup (e.g. "fr-CA" → fr).
+  if (locale) {
+    const prefix = locale.slice(0, 2);
+    if (BUILT_IN_LOCALES[prefix]) return BUILT_IN_LOCALES[prefix]!;
+  }
+  return enUS;
+}
+
+// ----------------------------------------------------------------------------
+// Trigger styling — mirrors Input's height + padding scale.
+// ----------------------------------------------------------------------------
+
+const triggerVariants = cva(
+  [
+    "flex items-center justify-between w-full gap-2",
+    "rounded-md border border-input bg-background text-foreground",
+    "transition-colors",
+    "focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+  ].join(" "),
+  {
+    variants: {
+      size: {
+        xs: "h-7 ps-2.5 pe-2 text-xs",
+        sm: "h-8 ps-3 pe-2 text-xs",
+        md: "h-9 ps-3 pe-2 text-sm",
+        lg: "h-10 ps-3.5 pe-2.5 text-base",
+        xl: "h-12 ps-4 pe-3 text-base",
+      },
+      invalid: {
+        true: "border-destructive focus-visible:ring-destructive",
+        false: "",
+      },
+    },
+    defaultVariants: { size: "md", invalid: false },
+  },
+);
+
+type TriggerVariants = VariantProps<typeof triggerVariants>;
+
+// ----------------------------------------------------------------------------
+// DatePicker — single / range mode root.
+// ----------------------------------------------------------------------------
+
+type DateRange = { from: Date | undefined; to?: Date | undefined };
+
+/**
+ * Quick-pick option rendered as a side-column button next to the calendar.
+ * The `value` shape must match the picker's current `mode` — passing a
+ * `Date` to a range-mode picker (or vice versa) is a consumer error and
+ * will be ignored at click time.
+ */
+export type DatePickerPreset = {
+  label: React.ReactNode;
+  value: Date | DateRange | Date[];
+};
+
+type DatePickerCommonProps = Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "value" | "defaultValue" | "onChange"
+> &
+  TriggerVariants & {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    placeholder?: string;
+    /** Range-only: trigger text shown after a start date is picked but the
+     *  end date isn't yet. Default "Pick end date". */
+    rangeEndPlaceholder?: string;
+    /** Display format string per date-fns. Falls back to the locale default. */
+    format?: string;
+    /** BCP-47 locale string (e.g. "fr-MA", "ar-MA"). */
+    locale?: string;
+    /** Direct locale object; takes precedence over `locale`. */
+    localeObject?: Locale;
+    min?: Date;
+    max?: Date;
+    clearable?: boolean;
+    /** Forwarded to react-day-picker's `disabled` for custom disable logic. */
+    disabledDates?: DayPickerProps["disabled"];
+    /** Override the locale's week start (0 = Sunday, 1 = Monday, ...). */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    showOutsideDays?: boolean;
+    showWeekNumbers?: boolean;
+    /**
+     * Numeral system for day numbers, week numbers, and year labels in the
+     * grid + trigger. `"latn"` (default) = Western Arabic digits (0123…);
+     * `"arab"` = Eastern Arabic digits (٠١٢…). Resolves via
+     * `Intl.NumberFormat`; the spec calls it out for Arabic locales.
+     */
+    numberingSystem?: NumberingSystem;
+    /**
+     * Render the calendar inline (no Popover trigger). The component still
+     * controls `value` / `onValueChange`; `placeholder`, `format`, `clearable`,
+     * and trigger-only styling props (`size`, `invalid`) are ignored.
+     * Useful for date-picker filters that sit permanently inside a sidebar.
+     */
+    inline?: boolean;
+    /**
+     * Quick-pick rows rendered in a side column next to the calendar.
+     * Common patterns: Today / Yesterday / Last 7 days / This month.
+     * Clicking a preset applies its `value` to the picker and (in popover
+     * single/range mode) closes the popover.
+     */
+    presets?: DatePickerPreset[];
+  };
+
+type DatePickerSingleProps = DatePickerCommonProps & {
+  mode?: "single";
+  value?: Date | null;
+  defaultValue?: Date | null;
+  onValueChange?: (value: Date | null) => void;
+};
+
+type DatePickerRangeProps = DatePickerCommonProps & {
+  mode: "range";
+  value?: DateRange | null;
+  defaultValue?: DateRange | null;
+  onValueChange?: (value: DateRange | null) => void;
+};
+
+type DatePickerMultipleProps = DatePickerCommonProps & {
+  mode: "multiple";
+  value?: Date[] | null;
+  defaultValue?: Date[] | null;
+  onValueChange?: (value: Date[]) => void;
+  /** Trigger-only: how many dates to render before collapsing the rest into
+   *  "+N more". Default 2. */
+  maxVisibleDates?: number;
+};
+
+type DatePickerProps = DatePickerSingleProps | DatePickerRangeProps | DatePickerMultipleProps;
+
+const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(function DatePicker(props, ref) {
+  // Extract the mode-specific props (value / defaultValue / onValueChange /
+  // mode) explicitly so they don't leak into the underlying <button> via
+  // `...rest`. We cast through `any` because TS can't narrow the union without
+  // a runtime discriminant, and the spreads below are mode-safe.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const propsAny = props as any;
+  const {
+    className,
+    size,
+    invalid,
+    open: openProp,
+    defaultOpen,
+    onOpenChange,
+    placeholder = "Pick a date",
+    rangeEndPlaceholder = "Pick end date",
+    format = "PP",
+    locale,
+    localeObject,
+    min,
+    max,
+    clearable = false,
+    disabledDates,
+    weekStartsOn,
+    showOutsideDays = true,
+    showWeekNumbers = false,
+    numberingSystem = "latn",
+    inline = false,
+    presets,
+    disabled,
+    mode: _mode,
+    value: _value,
+    defaultValue: _defaultValue,
+    onValueChange: _onValueChange,
+    ...rest
+  } = propsAny;
+  void _mode;
+  void _value;
+  void _defaultValue;
+  void _onValueChange;
+  const mode = (props.mode ?? "single") as "single" | "range" | "multiple";
+  const maxVisibleDates =
+    mode === "multiple" ? ((props as DatePickerMultipleProps).maxVisibleDates ?? 2) : 0;
+
+  const isOpenControlled = openProp !== undefined;
+  const [openInternal, setOpenInternal] = useState(defaultOpen ?? false);
+  const open = isOpenControlled ? openProp : openInternal;
+  const setOpen = (next: boolean) => {
+    if (!isOpenControlled) setOpenInternal(next);
+    onOpenChange?.(next);
+  };
+
+  // ---- Single-mode value state ----
+  const singleValueProp = mode === "single" ? (props as DatePickerSingleProps).value : undefined;
+  const singleDefault =
+    mode === "single" ? ((props as DatePickerSingleProps).defaultValue ?? null) : null;
+  const isSingleControlled = mode === "single" && singleValueProp !== undefined;
+  const [singleInternal, setSingleInternal] = useState<Date | null>(singleDefault);
+  const singleValue = isSingleControlled ? (singleValueProp ?? null) : singleInternal;
+  const setSingleValue = (next: Date | null) => {
+    if (!isSingleControlled) setSingleInternal(next);
+    if (mode === "single") (props as DatePickerSingleProps).onValueChange?.(next);
+  };
+
+  // ---- Range-mode value state ----
+  const rangeValueProp = mode === "range" ? (props as DatePickerRangeProps).value : undefined;
+  const rangeDefault =
+    mode === "range" ? ((props as DatePickerRangeProps).defaultValue ?? null) : null;
+  const isRangeControlled = mode === "range" && rangeValueProp !== undefined;
+  const [rangeInternal, setRangeInternal] = useState<DateRange | null>(rangeDefault);
+  const rangeValue = isRangeControlled ? (rangeValueProp ?? null) : rangeInternal;
+  const setRangeValue = (next: DateRange | null) => {
+    if (!isRangeControlled) setRangeInternal(next);
+    if (mode === "range") (props as DatePickerRangeProps).onValueChange?.(next);
+  };
+
+  // ---- Multiple-mode value state ----
+  const multipleValueProp =
+    mode === "multiple" ? (props as DatePickerMultipleProps).value : undefined;
+  const multipleDefault =
+    mode === "multiple" ? ((props as DatePickerMultipleProps).defaultValue ?? []) : [];
+  const isMultipleControlled = mode === "multiple" && multipleValueProp !== undefined;
+  const [multipleInternal, setMultipleInternal] = useState<Date[]>(multipleDefault ?? []);
+  const multipleValue: Date[] = isMultipleControlled ? (multipleValueProp ?? []) : multipleInternal;
+  const setMultipleValue = (next: Date[]) => {
+    if (!isMultipleControlled) setMultipleInternal(next);
+    if (mode === "multiple") (props as DatePickerMultipleProps).onValueChange?.(next);
+  };
+
+  const resolved = resolveLocale(locale, localeObject);
+  const numberFormatter = useMemo(
+    () => buildNumberFormatter(locale, numberingSystem),
+    [locale, numberingSystem],
+  );
+
+  // Display string per mode. For range, format both ends; show
+  // `rangeEndPlaceholder` while the second pick is pending.
+  const fmtOne = (d: Date) => {
+    const raw = fnsFormat(d, format, { locale: resolved });
+    return numberingSystem !== "latn" ? translateDigits(raw, numberFormatter) : raw;
+  };
+  let display: string | null = null;
+  if (mode === "single") {
+    display = singleValue ? fmtOne(singleValue) : null;
+  } else if (mode === "range") {
+    if (rangeValue?.from && rangeValue.to) {
+      display = `${fmtOne(rangeValue.from)} — ${fmtOne(rangeValue.to)}`;
+    } else if (rangeValue?.from) {
+      display = `${fmtOne(rangeValue.from)} — ${rangeEndPlaceholder}`;
+    }
+  } else if (mode === "multiple") {
+    if (multipleValue.length > 0) {
+      const visible = multipleValue.slice(0, maxVisibleDates).map(fmtOne).join(", ");
+      const overflow = multipleValue.length - maxVisibleDates;
+      display = overflow > 0 ? `${visible} +${overflow} more` : visible;
+    }
+  }
+
+  const contentId = useId();
+  const consumerLabelled =
+    rest["aria-label"] !== undefined || rest["aria-labelledby"] !== undefined;
+  const ariaLabelFallback = consumerLabelled ? undefined : (display ?? placeholder);
+
+  const disabledList: DayPickerProps["disabled"] = (() => {
+    const parts: NonNullable<DayPickerProps["disabled"]>[] = [];
+    if (min) parts.push({ before: min });
+    if (max) parts.push({ after: max });
+    if (disabledDates) parts.push(disabledDates);
+    return parts.length === 0 ? undefined : (parts as DayPickerProps["disabled"]);
+  })();
+
+  const handleSingleSelect = (date: Date | undefined) => {
+    setSingleValue(date ?? null);
+    if (date && !inline) setOpen(false);
+  };
+  const handleRangeSelect = (range: DateRange | undefined) => {
+    setRangeValue(range ?? null);
+    // Auto-close only when a complete range is set (both endpoints).
+    if (range?.from && range.to && !inline) setOpen(false);
+  };
+  const handleMultipleSelect = (dates: Date[] | undefined) => {
+    setMultipleValue(dates ?? []);
+    // No auto-close — picking individual dates is open-ended in multiple mode.
+  };
+
+  const applyPreset = (preset: DatePickerPreset) => {
+    const v = preset.value;
+    if (mode === "single" && v instanceof Date) {
+      setSingleValue(v);
+      if (!inline) setOpen(false);
+      return;
+    }
+    if (mode === "range" && !Array.isArray(v) && !(v instanceof Date)) {
+      setRangeValue(v);
+      if (!inline && v.from && v.to) setOpen(false);
+      return;
+    }
+    if (mode === "multiple" && Array.isArray(v)) {
+      setMultipleValue(v);
+      // Multiple mode never auto-closes — matches handleMultipleSelect.
+      return;
+    }
+    // Shape mismatch — silently ignore. Consumers see no effect and can
+    // notice in dev via the visual no-op; we don't throw to keep the
+    // component permissive (per the JSDoc note on DatePickerPreset).
+  };
+
+  // Has-value flag for the clear button + a11y fallback.
+  const hasValue =
+    mode === "single"
+      ? Boolean(singleValue)
+      : mode === "range"
+        ? Boolean(rangeValue?.from)
+        : multipleValue.length > 0;
+  const buttonProps = rest;
+
+  // The DayPicker JSX is reused in both popover and inline branches. Extracted
+  // so we don't duplicate the (sizable) classNames + formatters config.
+  // Shared DayPicker config across modes / branches.
+  const sharedDayPickerProps = {
+    locale: resolved,
+    disabled: disabledList,
+    weekStartsOn,
+    showOutsideDays,
+    showWeekNumber: showWeekNumbers,
+    ...(numberingSystem !== "latn" && {
+      formatters: {
+        formatDay: (date: Date) => numberFormatter.format(date.getDate()),
+        formatWeekNumber: (week: number) => numberFormatter.format(week),
+        formatYearDropdown: (year: Date) => numberFormatter.format(year.getFullYear()),
+        formatMonthDropdown: (month: Date) =>
+          new Intl.DateTimeFormat(locale ?? "en-US", { month: "long" }).format(month),
+      },
+    }),
+    classNames: {
+      months: "flex flex-col sm:flex-row gap-4",
+      month: "space-y-3",
+      month_caption: "flex justify-center pt-1 relative items-center h-7",
+      caption_label: "text-sm font-medium",
+      nav: "absolute inset-x-0 top-1 flex items-center justify-between px-1",
+      button_previous:
+        "inline-flex h-7 w-7 items-center justify-center rounded-md border border-input bg-background text-foreground hover:bg-accent hover:text-accent-foreground disabled:opacity-50",
+      button_next:
+        "inline-flex h-7 w-7 items-center justify-center rounded-md border border-input bg-background text-foreground hover:bg-accent hover:text-accent-foreground disabled:opacity-50",
+      month_grid: "w-full border-collapse",
+      weekdays: "flex",
+      weekday: "text-muted-foreground rounded-md w-9 font-normal text-xs uppercase",
+      week: "flex w-full mt-1",
+      day: "h-9 w-9 text-center text-sm p-0 relative",
+      day_button:
+        "inline-flex h-9 w-9 items-center justify-center rounded-md text-sm font-normal hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      selected:
+        "[&_button]:bg-primary [&_button]:text-primary-foreground [&_button]:hover:bg-primary/90 [&_button]:hover:text-primary-foreground",
+      // Range modifiers — endpoints stay primary (same as selected), the
+      // middle days get a softer accent fill so the range is visible.
+      range_start:
+        "[&_button]:bg-primary [&_button]:text-primary-foreground rounded-s-md rounded-e-none",
+      range_end:
+        "[&_button]:bg-primary [&_button]:text-primary-foreground rounded-e-md rounded-s-none",
+      range_middle:
+        "[&_button]:bg-accent/40 [&_button]:text-foreground [&_button]:rounded-none rounded-none",
+      today: "[&_button]:ring-1 [&_button]:ring-ring",
+      outside: "[&_button]:text-muted-foreground [&_button]:opacity-50",
+      disabled:
+        "[&_button]:text-muted-foreground [&_button]:opacity-40 [&_button]:pointer-events-none",
+      hidden: "invisible",
+    },
+    components: {
+      Chevron: ({ orientation }: { orientation?: "left" | "right" | "up" | "down" }) =>
+        orientation === "left" ? (
+          <RiArrowLeftSLine className="rtl-mirror size-4" aria-hidden="true" />
+        ) : (
+          <RiArrowRightSLine className="rtl-mirror size-4" aria-hidden="true" />
+        ),
+    },
+  } as const;
+
+  const rawDayPicker =
+    mode === "range" ? (
+      <DayPicker
+        mode="range"
+        selected={(rangeValue ?? undefined) as DateRange | undefined}
+        onSelect={handleRangeSelect}
+        {...sharedDayPickerProps}
+      />
+    ) : mode === "multiple" ? (
+      <DayPicker
+        mode="multiple"
+        selected={multipleValue}
+        onSelect={handleMultipleSelect}
+        {...sharedDayPickerProps}
+      />
+    ) : (
+      <DayPicker
+        mode="single"
+        selected={singleValue ?? undefined}
+        onSelect={handleSingleSelect}
+        {...sharedDayPickerProps}
+      />
+    );
+
+  const presetsList =
+    presets && presets.length > 0 ? (
+      <ul
+        aria-label="Quick options"
+        className="border-border me-1 flex shrink-0 flex-col gap-1 border-e pe-3"
+      >
+        {presets.map((preset: DatePickerPreset, idx: number) => (
+          <li key={idx}>
+            <button
+              type="button"
+              onClick={() => applyPreset(preset)}
+              className={cn(
+                "inline-flex w-full items-center rounded-md px-3 py-1.5 text-sm",
+                "text-foreground hover:bg-accent hover:text-accent-foreground",
+                "focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none",
+              )}
+            >
+              {preset.label}
+            </button>
+          </li>
+        ))}
+      </ul>
+    ) : null;
+
+  const dayPicker = presetsList ? (
+    <div className="flex items-start">
+      {presetsList}
+      <div>{rawDayPicker}</div>
+    </div>
+  ) : (
+    rawDayPicker
+  );
+
+  if (inline) {
+    // Inline: no Popover, no trigger button. Render the calendar in a
+    // panel-styled wrapper so it looks consistent with the popover mode.
+    // `ref` is the consumer's button-shaped ref in popover mode; for the
+    // inline div we forward to a div via cast since the component's
+    // primary contract is the button trigger. Consumers needing a ref in
+    // inline mode should use `useRef<HTMLDivElement>()`.
+    return (
+      <div
+        ref={ref as unknown as React.Ref<HTMLDivElement>}
+        id={contentId}
+        className={cn(
+          "border-border bg-popover text-popover-foreground inline-block rounded-md border p-3 shadow-sm",
+          className,
+        )}
+      >
+        {dayPicker}
+      </div>
+    );
+  }
+
+  return (
+    <PopoverPrimitive.Root open={open} onOpenChange={setOpen}>
+      <PopoverPrimitive.Trigger asChild>
+        <button
+          ref={ref}
+          type="button"
+          // role="combobox" so aria-invalid is accepted (WAI-ARIA forbids
+          // it on `role="button"`). Matches Combobox's trigger semantics:
+          // the button represents a value and opens a panel.
+          role="combobox"
+          aria-haspopup="dialog"
+          aria-expanded={open}
+          // aria-controls is only valid when the controlled element exists
+          // in the DOM. Radix unmounts Content when closed, so omit
+          // aria-controls until open. Matches Radix Select's pattern.
+          aria-controls={open ? contentId : undefined}
+          aria-invalid={invalid || undefined}
+          aria-label={ariaLabelFallback}
+          disabled={disabled}
+          className={cn(triggerVariants({ size, invalid }), className)}
+          {...buttonProps}
+        >
+          <RiCalendar2Line className="text-muted-foreground size-4 shrink-0" aria-hidden="true" />
+          <span className={cn("flex-1 truncate text-start", !display && "text-muted-foreground")}>
+            {display ?? placeholder}
+          </span>
+          {clearable && hasValue && !disabled ? (
+            <button
+              type="button"
+              aria-label="Clear"
+              onClick={(e) => {
+                e.preventDefault();
+                e.stopPropagation();
+                if (mode === "range") setRangeValue(null);
+                else if (mode === "multiple") setMultipleValue([]);
+                else setSingleValue(null);
+              }}
+              className={cn(
+                "inline-flex shrink-0 items-center justify-center rounded p-0.5",
+                "text-muted-foreground hover:text-foreground",
+                "focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none",
+              )}
+            >
+              <RiCloseLine className="size-4" />
+            </button>
+          ) : null}
+        </button>
+      </PopoverPrimitive.Trigger>
+
+      <PopoverPrimitive.Portal>
+        <PopoverPrimitive.Content
+          id={contentId}
+          align="start"
+          sideOffset={4}
+          className={cn(
+            "z-popover border-border bg-popover text-popover-foreground rounded-md border p-3 shadow-md outline-none",
+            "data-[state=open]:animate-[scale-in_var(--duration-fast)_var(--ease-out)]",
+            "data-[state=closed]:animate-[scale-out_var(--duration-fast)_var(--ease-in)]",
+          )}
+        >
+          {dayPicker}
+        </PopoverPrimitive.Content>
+      </PopoverPrimitive.Portal>
+    </PopoverPrimitive.Root>
+  );
+});
+DatePicker.displayName = "DatePicker";
+
+export { DatePicker };
+export type { DatePickerProps };
+
+/**
+ * Utility export — re-exports date-fns' `format` + `parse` so consumers don't
+ * have to import them separately for adapter glue. Pulls in date-fns
+ * tree-shakably.
+ */
+export const dateFormat = fnsFormat;
+export const dateParse = fnsParse;