@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/date-picker/core/types.ts

@@ -0,0 +1,68 @@
+/** Values accepted wherever a date comes in: a Date, an ISO `yyyy-mm-dd` string or a timestamp. */
+export type DateInput = Date | string | number;
+
+export interface DateRange {
+  start: Date | null;
+  end: Date | null;
+}
+
+export type DatePickerSize = "sm" | "md" | "lg";
+
+/** Panel shown inside the popover. */
+export type CalendarView = "days" | "months" | "years";
+
+export interface CalendarDay {
+  date: Date;
+  /** Day of the month, 1-31. */
+  day: number;
+  /** `yyyy-mm-dd` in local time: a stable key, and safe to compare. */
+  key: string;
+  /** Belongs to a neighbouring month. */
+  outside: boolean;
+  today: boolean;
+  weekend: boolean;
+  disabled: boolean;
+}
+
+export interface CalendarWeek {
+  /** ISO week number, shown when `showWeekNumbers` is set. */
+  weekNumber: number;
+  days: CalendarDay[];
+}
+
+export interface CalendarMonth {
+  year: number;
+  /** 0-11, as in `Date.prototype.getMonth`. */
+  month: number;
+  weeks: CalendarWeek[];
+}
+
+/** What makes a day unselectable. */
+export interface DateLimits {
+  min?: Date | null;
+  max?: Date | null;
+  isDateDisabled?(date: Date): boolean;
+}
+
+export interface DatePickerLocaleText {
+  calendarLabel: string;
+  openCalendar: string;
+  clear: string;
+  today: string;
+  previousMonth: string;
+  nextMonth: string;
+  previousYears: string;
+  nextYears: string;
+  /** Button that switches the day grid to the month and year panels. */
+  chooseMonthYear: string;
+  monthPanelLabel: string;
+  yearPanelLabel: string;
+  weekNumber: string;
+  startDate: string;
+  endDate: string;
+  invalidDate: string;
+  outOfRange: string;
+  presets: string;
+  selectedDate(date: string): string;
+  selectedRange(start: string, end: string): string;
+}

package/source/components/date-picker/index.ts

@@ -0,0 +1,16 @@
+export { DatePicker } from "./react/DatePicker";
+export type { DatePickerProps } from "./react/DatePicker";
+export { DateRangePicker } from "./react/DateRangePicker";
+export type { DateRangePickerProps, DateRangeInput } from "./react/DateRangePicker";
+export type { DatePreset } from "./react/CalendarPanel";
+export { formatWith, useDatePicker } from "./react/useDatePicker";
+export type { DatePickerEngine, RangeField, UseDatePickerParams } from "./react/useDatePicker";
+export { defaultDatePickerText } from "./react/locale";
+export type { DayState } from "./react/Calendar";
+export type {
+  DateFormat,
+  DatePickerHandle,
+  DatePickerSharedProps,
+  DatePickerSlot,
+} from "./react/props";
+export * from "./core";

package/source/components/date-picker/passport.json

@@ -0,0 +1,407 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "DatePicker",
+    "folder": "date-picker",
+    "exports": [
+      "DEFAULT_DATE_FORMAT",
+      "DatePicker",
+      "DateRangePicker"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/calendar.ts",
+      "core/format.ts",
+      "core/index.ts",
+      "core/today.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Calendar.tsx",
+      "react/CalendarPanel.tsx",
+      "react/DatePicker.tsx",
+      "react/DateRangePicker.tsx",
+      "react/MonthYearPanels.tsx",
+      "react/Popover.tsx",
+      "react/icons.tsx",
+      "react/locale.ts",
+      "react/props.ts",
+      "react/useDatePicker.ts"
+    ],
+    "sourceHash": "sha256:3dba4cc6b29876969fcc114163bd9efae4ebcf6257e23b258d4f12f643115b78"
+  },
+  "props": [
+    {
+      "name": "allowInput",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Let people type a date instead of picking one. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<DatePickerSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "clearable",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Show the clear button. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "closeOnSelect",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Close the calendar after choosing a date. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "defaultValue",
+      "type": "other",
+      "typeText": "DateInput | null | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "error",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Message shown below the control; also marks the control invalid.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "fixedWeeks",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Always six week rows, so the popover never changes height. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "format",
+      "type": "other",
+      "typeText": "DateFormat | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "isDateDisabled",
+      "type": "function",
+      "signature": "((date: Date) => boolean) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Called for every rendered day; return true to block it (weekends, holidays).",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "label",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "locale",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "BCP-47 tag deciding month names, field order and the first day of the week.\nDefaults to the runtime's locale — pass it explicitly when you render on a\nserver, so the markup matches what the browser produces.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<DatePickerLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "max",
+      "type": "other",
+      "typeText": "DateInput | null | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "min",
+      "type": "other",
+      "typeText": "DateInput | null | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Earliest and latest selectable day.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Posts the value as `yyyy-mm-dd` in a hidden input.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "numberOfMonths",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 1,
+      "origin": "derived",
+      "description": "Months shown side by side. Default 1, or 2 for the range picker.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onChange",
+      "type": "function",
+      "signature": "((date: Date | null) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onOpenChange",
+      "type": "function",
+      "signature": "((open: boolean) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "presets",
+      "type": "other",
+      "typeText": "readonly DatePreset[] | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Shortcuts shown beside the calendar (\"Last 7 days\").",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "readOnly",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Shows the value but blocks typing and picking.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<DatePickerHandle<Date | null>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "showToday",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Show the \"Today\" shortcut in the footer. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "showWeekNumbers",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "DatePickerSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "value",
+      "type": "other",
+      "typeText": "DateInput | null | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "weekStartsOn",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "0 = Sunday. Defaults to the locale's first day of the week.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "events": [
+    {
+      "name": "onChange",
+      "signature": "((date: Date | null) => void) | undefined"
+    },
+    {
+      "name": "onOpenChange",
+      "signature": "((open: boolean) => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "label",
+    "control",
+    "input",
+    "popover",
+    "calendar",
+    "day",
+    "footer",
+    "presets"
+  ],
+  "states": [
+    {
+      "attr": "data-autofocus"
+    },
+    {
+      "attr": "data-disabled"
+    },
+    {
+      "attr": "data-in-range"
+    },
+    {
+      "attr": "data-invalid"
+    },
+    {
+      "attr": "data-key"
+    },
+    {
+      "attr": "data-outside"
+    },
+    {
+      "attr": "data-range-end"
+    },
+    {
+      "attr": "data-range-start"
+    },
+    {
+      "attr": "data-required"
+    },
+    {
+      "attr": "data-selected"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-state",
+      "values": [
+        "open"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-today"
+    },
+    {
+      "attr": "data-weekend"
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 33,
+    "propsDescribed": 14,
+    "describedPct": 42,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/date-picker/react/Calendar.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import { useEffect, useRef, type KeyboardEvent } from "react";
+import { formatDate } from "../core/format";
+import type { CalendarDay, CalendarMonth, DatePickerLocaleText } from "../core/types";
+import type { WeekdayName } from "../core/format";
+import { cx } from "./props";
+
+export interface DayState {
+  selected: boolean;
+  rangeStart: boolean;
+  rangeEnd: boolean;
+  inRange: boolean;
+}
+
+interface CalendarProps {
+  months: CalendarMonth[];
+  weekdays: WeekdayName[];
+  locale?: string;
+  /** `yyyy-mm-dd` of the one day that is in the tab order. */
+  focusedKey: string;
+  /** Pull DOM focus to the focused day (false while someone types in the field). */
+  gridFocus: boolean;
+  showWeekNumbers: boolean;
+  text: DatePickerLocaleText;
+  dayClassName?: string;
+  monthLabel(month: CalendarMonth): string;
+  getDayState(date: Date): DayState;
+  onSelect(date: Date): void;
+  onPreview(date: Date | null): void;
+  onKeyDown(event: KeyboardEvent<HTMLElement>): void;
+}
+
+const FULL_DATE: Intl.DateTimeFormatOptions = {
+  weekday: "long",
+  day: "numeric",
+  month: "long",
+  year: "numeric",
+};
+
+/**
+ * One or more month grids. Only the focused day is tabbable; the arrow keys move
+ * it, which is the WAI-ARIA grid pattern for a date picker.
+ */
+export function Calendar({
+  months,
+  weekdays,
+  locale,
+  focusedKey,
+  gridFocus,
+  showWeekNumbers,
+  text,
+  dayClassName,
+  monthLabel,
+  getDayState,
+  onSelect,
+  onPreview,
+  onKeyDown,
+}: CalendarProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  // With two months side by side the same day appears twice, so the neighbouring
+  // month's days are blanked out rather than rendered as duplicates.
+  const hideOutside = months.length > 1;
+
+  useEffect(() => {
+    if (!gridFocus) return;
+    const day = ref.current?.querySelector<HTMLElement>(`[data-key="${focusedKey}"]`);
+    if (day && day !== document.activeElement) day.focus({ preventScroll: true });
+  }, [gridFocus, focusedKey]);
+
+  const renderDay = (day: CalendarDay) => {
+    if (day.outside && hideOutside) {
+      return <td key={day.key} className="dp-cell" aria-hidden="true" />;
+    }
+    const state = getDayState(day.date);
+    const focused = day.key === focusedKey;
+    return (
+      <td
+        key={day.key}
+        role="gridcell"
+        className="dp-cell"
+        aria-selected={state.selected || undefined}
+        data-in-range={state.inRange || undefined}
+        data-range-start={state.rangeStart || undefined}
+        data-range-end={state.rangeEnd || undefined}
+      >
+        <button
+          type="button"
+          className={cx("dp-day", dayClassName)}
+          data-key={day.key}
+          data-autofocus={focused || undefined}
+          data-today={day.today || undefined}
+          data-outside={day.outside || undefined}
+          data-weekend={day.weekend || undefined}
+          data-selected={state.selected || undefined}
+          tabIndex={focused ? 0 : -1}
+          disabled={day.disabled}
+          aria-label={formatDate(day.date, locale, FULL_DATE)}
+          aria-current={day.today ? "date" : undefined}
+          onClick={() => onSelect(day.date)}
+          onPointerEnter={() => onPreview(day.date)}
+          onFocus={() => onPreview(day.date)}
+        >
+          {day.day}
+        </button>
+      </td>
+    );
+  };
+
+  return (
+    <div
+      ref={ref}
+      className="dp-months"
+      onKeyDown={onKeyDown}
+      onPointerLeave={() => onPreview(null)}
+    >
+      {months.map((month) => {
+        const label = monthLabel(month);
+        return (
+          <div key={`${month.year}-${month.month}`} className="dp-month">
+            {months.length > 1 && (
+              <div className="dp-month-caption" aria-hidden="true">
+                {label}
+              </div>
+            )}
+            <table role="grid" aria-label={label} className="dp-grid">
+              <thead>
+                <tr>
+                  {showWeekNumbers && (
+                    <th scope="col" className="dp-week-number">
+                      <abbr title={text.weekNumber}>#</abbr>
+                    </th>
+                  )}
+                  {weekdays.map((weekday) => (
+                    <th key={weekday.long} scope="col" abbr={weekday.long} className="dp-weekday">
+                      <span aria-hidden="true">{weekday.short}</span>
+                      <span className="dp-sr-only">{weekday.long}</span>
+                    </th>
+                  ))}
+                </tr>
+              </thead>
+              <tbody>
+                {month.weeks.map((week) => (
+                  <tr key={week.days[0].key} role="row">
+                    {showWeekNumbers && (
+                      <th scope="row" className="dp-week-number">
+                        {week.weekNumber}
+                      </th>
+                    )}
+                    {week.days.map(renderDay)}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        );
+      })}
+    </div>
+  );
+}