import type { ElementType } from 'react'; import type { DateTime } from 'luxon'; /** A selected date range as a luxon tuple. */ export type DateRangeValue = [DateTime | null, DateTime | null]; /** Calendar unit a range snap-shifts by when stepped with the arrows. */ export type StepUnit = 'week' | 'month' | 'quarter' | 'year'; export interface PredefinedRange { /** Stable identifier, e.g. `Last_7Days`. Used as the selected key. */ key: string; /** Human label shown in the menu and as the pill's left label. */ label: string; /** Computes the concrete range from a (timezone-applied) `now`. */ getValue: (now: DateTime) => DateRangeValue; /** Render a divider before this option in the menu (group separator). */ hasDivider?: boolean; /** * Snap-shift both endpoints by one of these units when the user steps with * the arrows (e.g. `week` moves a "This Week" range to the previous/next * week). When omitted, stepping shifts the whole window by its own span. */ stepUnit?: StepUnit; /** * Full stepping override. Given the current value and a direction (`-1` * back, `1` forward), returns the new range. Takes precedence over * `stepUnit`. Use for app-specific stepping such as a fiscal calendar. */ step?: (value: DateRangeValue, direction: 1 | -1) => DateRangeValue; /** * Left label shown after the user steps this range with the arrows, e.g. * `Week Of` for "This Week" or `7-Day` for "Last 7 Days". Falls back to * `label` when omitted. */ steppedLabel?: string; /** Tooltip / aria labels for the arrows, e.g. `Previous Week` / `Next Week`. */ stepTooltips?: { previous: string; next: string; }; } export interface InkDateRangeCalendarProps { /** Current range. */ value: DateRangeValue; /** Called when a complete range has been picked. */ onChange: (value: DateRangeValue) => void; /** IANA timezone the picker uses for range math; selections are created in it. */ timeZone?: string; } export interface InkDateRangePickerSlots { /** * Calendar rendered in the popover for custom selection. Defaults to the * built-in free range calendar. Inject the Pro `StaticDateRangePicker`, * a fiscal calendar, etc. */ calendar?: ElementType; } export interface InkDateRangePickerSlotProps { /** * Extra props forwarded to the calendar slot. `value`, `onChange` and * `timeZone` are always supplied by the picker and cannot be overridden. */ calendar?: Record; } export interface InkDateRangePickerProps { /** Controlled selected range. */ value: DateRangeValue; /** Called with the new range and the selected range key (`Custom` when none). */ onChange: (value: DateRangeValue, rangeKey: string) => void; /** Controlled selected range key. When omitted the component tracks it internally. */ rangeKey?: string; /** Initial selected key when uncontrolled. Defaults to `Last_7Days`. */ defaultRangeKey?: string; /** Ordered predefined ranges shown in the menu. Defaults to `DEFAULT_RANGES`. */ ranges?: PredefinedRange[]; /** Append a `Custom` option that opens the calendar. Default `true`. */ enableCustom?: boolean; /** Show the predefined-ranges menu. When `false`, the pill opens the calendar directly. Default `true`. */ enablePredefinedRanges?: boolean; /** * Show the ◀ ▶ stepper arrows that move the range backward/forward by its * own period. Default `true`. See `PredefinedRange.stepUnit` / `step`. */ enableStepping?: boolean; /** IANA timezone used for range math. Default `UTC`. */ timeZone?: string; /** * Background the pill is rendered on, which drives its fill/border: * - `neutral100` (default): white fill + 1px neutral200 border. * - `white`: neutral100 fill, no border. */ surface?: 'neutral100' | 'white'; /** Left-hand label shown when the range matches no predefined range. Default `Custom`. */ customLabel?: string; /** Formats the right-hand range text. Defaults to e.g. `Apr 1 - 7, 2026`. */ formatRange?: (value: DateRangeValue) => string; /** Disables the pill. */ disabled?: boolean; /** * Stable identifier used for `data-test-*` hooks and ARIA wiring. When * omitted, the `data-test-ink-date-range-picker*` attributes are not * rendered and ARIA ids fall back to a generated id, so pass `name` if you * need deterministic test selectors. */ name?: string; /** Override the calendar rendered inside the popover. */ slots?: InkDateRangePickerSlots; /** Props forwarded to the calendar slot. */ slotProps?: InkDateRangePickerSlotProps; }