@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/calendar.d.ts

@@ -0,0 +1,240 @@
+import * as React from "react";
+import { type DayPickerProps, type Matcher, type Modifiers } from "react-day-picker";
+import { type IsoDateRange, type IsoDateString } from "../lib/date.js";
+import type { Holiday, HolidayProvider } from "../locale-data/core/types.js";
+declare const calendarLabels: {
+    prevMonth: string;
+    nextMonth: string;
+    prevYear: string;
+    nextYear: string;
+    selectMonth: string;
+    selectYear: string;
+    nav: string;
+    today: string;
+    todayDay: string;
+    selectedDay: string;
+    weekNumber: string;
+    weekColumn: string;
+    weekColumnShort: string;
+    holiday: string;
+    halfDay: string;
+    weekend: string;
+    more: string;
+    loading: string;
+    slots: string;
+    noSlots: string;
+    slotsError: string;
+    retry: string;
+    slotsLeft: string;
+    unavailable: string;
+};
+export type CalendarLabels = typeof calendarLabels;
+/** A day matcher: any react-day-picker matcher, or a `YYYY-MM-DD` string. */
+export type DayMatcher = Matcher | IsoDateString;
+/** Turns string / matcher input into react-day-picker matchers (min/max become `before`/`after`). */
+export declare function toDayMatchers(options: {
+    min?: IsoDateString;
+    max?: IsoDateString;
+    disabledDays?: DayMatcher | DayMatcher[];
+}): Matcher[];
+/** react-day-picker `weekStartsOn` (0 = Sunday) and `firstWeekContainsDate` of a locale. */
+export declare function useCalendarWeek(locale?: string): {
+    weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    firstWeekContainsDate: 1 | 4;
+    /** ISO weekdays (1 = Monday … 7 = Sunday) of the weekend. */
+    weekend: number[];
+};
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type CalendarGridSize = "sm" | "md" | "lg";
+interface CalendarGridOwnProps {
+    /** Cell size: sm = 32px, md = `--control-h` (density axis), lg = 76px cells with a content area. */
+    size?: CalendarGridSize;
+    /** Content under the day number: dots, a count, a price. */
+    renderDayExtra?: (date: Date, modifiers: Modifiers) => React.ReactNode;
+    /** Extra words appended to a day's accessible name ("Republic Day, 2 scheduled posts"). */
+    describeDay?: (date: Date, modifiers: Modifiers) => string | undefined;
+    /** Native tooltip of a day (holiday names). */
+    dayTitle?: (date: Date, modifiers: Modifiers) => string | undefined;
+    /** Mark the locale's weekend days with `data-weekend`. Default `true`. */
+    markWeekends?: boolean;
+    /** Built-in strings (`calendar` namespace). */
+    labels?: Partial<CalendarLabels>;
+    /** react-day-picker's own label functions (advanced). */
+    ariaLabels?: DayPickerProps["labels"];
+}
+/**
+ * The shared month grid behind Calendar, Date picker and Date range picker: react-day-picker v9
+ * styled with tokens, with locale-aware week start (`getWeekInfo`), weekend marks, localized
+ * labels, and stable `data-*` hooks (`data-today`, `data-selected`, `data-range-start|middle|end`,
+ * `data-disabled`, `data-outside`, `data-weekend`, `data-holiday`).
+ *
+ * All react-day-picker props pass through (`mode`, `selected`, `onSelect`, `modifiers`,
+ * `numberOfMonths`, `captionLayout`, `showWeekNumber`…). Dates here are `Date` objects; the
+ * higher-level components take `YYYY-MM-DD` strings.
+ *
+ * ```tsx
+ * <CalendarGrid mode="single" selected={day} onSelect={setDay} />
+ * ```
+ */
+export type CalendarGridProps = DistributiveOmit<DayPickerProps, "labels"> & CalendarGridOwnProps;
+/** react-day-picker styled with tokens. See `CalendarGridProps`. */
+export declare function CalendarGrid(props: CalendarGridProps): React.JSX.Element;
+export type CalendarTone = "neutral" | "accent" | "success" | "warning" | "danger" | "info";
+/** Something on a day: a scheduled post, an absence, "3 slots left". */
+export interface CalendarMarker {
+    label: string;
+    tone?: CalendarTone;
+    /** Shown as a number in `lg` cells and summed for density. */
+    count?: number;
+}
+export interface CalendarDayInfo {
+    iso: IsoDateString;
+    isToday: boolean;
+    isWeekend: boolean;
+    outside: boolean;
+    selected: boolean;
+    disabled: boolean;
+    holidays: Holiday[];
+    markers: CalendarMarker[];
+}
+export interface CalendarLegendItem {
+    label: string;
+    tone?: CalendarTone;
+    /** `"dot"` (default), `"holiday"` (tinted cell) or `"today"` (accent bar). */
+    kind?: "dot" | "holiday" | "today";
+}
+type CalendarSelectionProps = {
+    /** Selection mode. Default `"single"`. */
+    mode?: "single";
+    value?: IsoDateString | null;
+    defaultValue?: IsoDateString | null;
+    onValueChange?: (value: IsoDateString | null) => void;
+} | {
+    mode: "multiple";
+    value?: IsoDateString[];
+    defaultValue?: IsoDateString[];
+    onValueChange?: (value: IsoDateString[]) => void;
+} | {
+    mode: "range";
+    value?: IsoDateRange | null;
+    defaultValue?: IsoDateRange | null;
+    onValueChange?: (value: IsoDateRange | null) => void;
+} | {
+    /** Display only: no selection. */
+    mode: "none";
+    value?: undefined;
+    defaultValue?: undefined;
+    onValueChange?: undefined;
+};
+interface CalendarBaseProps {
+    /** Visible months: 1, 2, 3, or 12 (year view with compact cells). Default 1. */
+    months?: 1 | 2 | 3 | 12;
+    /** Visible month (`YYYY-MM` or any date in it), controlled. */
+    month?: string;
+    /** Initial visible month. Default: the month of the value, else today. */
+    defaultMonth?: string;
+    /** Called with `YYYY-MM-01` of the first visible month. */
+    onMonthChange?: (month: IsoDateString) => void;
+    /** Called with the visible window, e.g. to fetch events for it. */
+    onVisibleRangeChange?: (range: {
+        start: IsoDateString;
+        end: IsoDateString;
+    }) => void;
+    /** Earliest selectable date. */
+    min?: IsoDateString;
+    /** Latest selectable date. */
+    max?: IsoDateString;
+    /** Days that cannot be picked (unavailable, fully booked). */
+    disabledDays?: DayMatcher | DayMatcher[];
+    /** `true`: a selected day cannot be cleared by clicking it again (single mode). */
+    required?: boolean;
+    /** Week numbers in the first column (locale week rules). */
+    showWeekNumbers?: boolean;
+    /** Holiday data. Default: the active locale's pack (`tr` → Turkish public holidays); `false` hides them. */
+    holidays?: HolidayProvider | HolidayProvider[] | false;
+    /** Holiday region filter (ISO 3166-2). */
+    holidayRegion?: string;
+    /** Per-day markers, keyed by `YYYY-MM-DD`. */
+    markers?: Record<IsoDateString, CalendarMarker | CalendarMarker[]>;
+    /** Custom content under the day number (replaces the marker dots). */
+    renderDay?: (date: Date, info: CalendarDayInfo) => React.ReactNode;
+    /** Cell size. sm 32px, md `--control-h`, lg 76px with a content area. Default `"md"` (`"sm"` in the year view). */
+    size?: CalendarGridSize;
+    /** `"card"` wraps the calendar in a surface. Default `"plain"`. */
+    variant?: "plain" | "card";
+    /** Header with title, previous / next and Today. Default `true`. */
+    header?: boolean;
+    /** Extra content at the end of the header (filters, a view switch). */
+    headerAction?: React.ReactNode;
+    /** Legend under the grid. Holidays in view are added automatically. */
+    legend?: CalendarLegendItem[] | boolean;
+    /** Placeholder dots while the visible range is loading. */
+    loading?: boolean;
+    /** Week start override (0 = Sunday … 6). Default from the locale. */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /** Content under the grid (pickers put Clear / Apply here). */
+    footer?: React.ReactNode;
+    /** Extra react-day-picker props for the grid. */
+    gridProps?: Partial<CalendarGridOwnProps> & Omit<Partial<DayPickerProps>, "mode" | "selected" | "onSelect" | "labels">;
+    className?: string;
+    id?: string;
+    "aria-label"?: string;
+    labels?: Partial<CalendarLabels>;
+}
+export type CalendarProps = CalendarBaseProps & CalendarSelectionProps;
+/**
+ * Standalone month, multi-month or year calendar with per-day content: marker dots, holidays,
+ * counts, availability. Values are `YYYY-MM-DD` strings. Week start, weekend and month names
+ * follow the locale; holidays come from the locale pack (Turkish public holidays for `tr`).
+ *
+ * ```tsx
+ * <Calendar
+ *   value={day}
+ *   onValueChange={setDay}
+ *   markers={{ "2026-11-12": { label: "2 scheduled posts", tone: "accent", count: 2 } }}
+ * />
+ * <Calendar months={12} size="sm" markers={density} />
+ * ```
+ */
+export declare const Calendar: React.ForwardRefExoticComponent<CalendarProps & React.RefAttributes<HTMLDivElement>>;
+export interface CalendarLegendProps extends React.HTMLAttributes<HTMLUListElement> {
+    items: CalendarLegendItem[];
+    labels?: Partial<CalendarLabels>;
+}
+/** Key for the marks on a Calendar (dot tones, holidays, today). */
+export declare const CalendarLegend: React.ForwardRefExoticComponent<CalendarLegendProps & React.RefAttributes<HTMLUListElement>>;
+export interface CalendarSlot {
+    /** `"HH:mm"` (24h). The value reported on select. */
+    start: string;
+    end?: string;
+    available: boolean;
+    /** Extra text ("1 left", "$45"). */
+    label?: string;
+}
+export interface CalendarSlotsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    slots: CalendarSlot[];
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (start: string | null) => void;
+    /** The day the slots belong to (`YYYY-MM-DD`), shown as the heading. */
+    day?: IsoDateString | null;
+    loading?: boolean;
+    /** Error text; shows a retry button when `onRetry` is set. */
+    error?: React.ReactNode;
+    onRetry?: () => void;
+    /** Display hour cycle. Default from the locale. */
+    hourCycle?: 12 | 24;
+    /** Columns of the slot grid. Default 3. */
+    columns?: 2 | 3 | 4;
+    labels?: Partial<CalendarLabels>;
+}
+/**
+ * Time slots for the selected day (booking). A `radiogroup` with roving focus: arrows move,
+ * Space / Enter selects. Unavailable slots are shown struck through and skipped.
+ *
+ * ```tsx
+ * <CalendarSlots day={day} slots={slots} value={time} onValueChange={setTime} />
+ * ```
+ */
+export declare const CalendarSlots: React.ForwardRefExoticComponent<CalendarSlotsProps & React.RefAttributes<HTMLDivElement>>;
+export {};