@xh/hoist 87.1.0 → 87.2.0

package/build/types/cmp/daterange/DateRangePickerModel.d.ts

@@ -0,0 +1,266 @@
+import { HoistModel, type PersistOptions } from '@xh/hoist/core';
+import type { FieldFilterSpec } from '@xh/hoist/data';
+import { LocalDate } from '@xh/hoist/utils/datetime';
+import type { DateRangeAnchorDay, DateRangeContext, DateRangeFormat, DateRangePickerTab, DateRangePreset, DateRangePresetToken, DateRangeSelection, LocalDateRange, ResolvedDateRange } from './Types';
+/**
+ * Configuration for a {@link DateRangePickerModel} - a control for selecting a period of time
+ * as a preset, relative lookback, calendar month or year, or custom range of dates.
+ */
+export interface DateRangePickerConfig {
+    /**
+     * The day that relative and to-date selections resolve against, and (unless `maxDate` is set)
+     * the latest selectable date. Default `'localDay'` - the current day in the browser's time
+     * zone, kept current as the day rolls. See {@link DateRangeAnchorDay} for the app-day, pinned,
+     * and computed alternatives.
+     */
+    anchorDay?: DateRangeAnchorDay;
+    /**
+     * True to treat single days by business day: a live `anchorDay` (`'localDay'` or `'appDay'`)
+     * snaps back to the most recent business day, and single-day selections step by business day
+     * rather than calendar day. Multi-day ranges are unaffected - seven days is still seven days.
+     * A pinned or computed `anchorDay` is honored verbatim, never snapped. Default false.
+     */
+    businessDayMode?: boolean;
+    /**
+     * False (default) waits for the user to apply a relative or custom draft before updating the
+     * value. True commits those drafts as they change, and applies a tab's current draft as soon
+     * as the tab is activated, so the popover never shows a period other than the applied one. The
+     * Apply and Cancel buttons are omitted. Preset and month/year picks commit on click either way.
+     * Overridable app-wide via `DateRangePickerModel.defaults`.
+     */
+    commitOnChange?: boolean;
+    /**
+     * Format for the dates of a range - the two ends shown on the trigger, beside presets, and in
+     * `rangeLabel`. A moment.js format string, or a function of the date. Default `YYYY-MM-DD`,
+     * overridable app-wide via `DateRangePickerModel.defaults`. The Custom tab's date inputs use
+     * it when it is a string, else `YYYY-MM-DD`.
+     */
+    dateFormat?: DateRangeFormat;
+    /**
+     * Format for a single day - a one-day range, and the anchor date in the popover footer -
+     * where the weekday matters more than the year. A moment.js format string, or a function of
+     * the date. Default `ddd MMM D`, overridable app-wide via `DateRangePickerModel.defaults`.
+     */
+    singleDayFormat?: DateRangeFormat;
+    /**
+     * Name of the field to filter in the {@link FieldFilterSpec}s produced by
+     * {@link DateRangePickerModel.currentRangeFilter} and `priorRangeFilter`. Required to read
+     * those properties.
+     */
+    filterField?: string;
+    /**
+     * Initial value, and the fallback when a persisted value is missing or fails validation.
+     * Accepts a preset token string as shorthand for a preset selection. Default: the first
+     * configured preset, or a rolling 30 days if no presets are configured.
+     */
+    initialValue?: DateRangeSelection | DateRangePresetToken | string;
+    /**
+     * Test for whether a date is a business day, consulted by `businessDayMode` and available to
+     * app-defined presets via {@link DateRangeContext}. Default: weekdays. Supply to honor a
+     * holiday calendar.
+     */
+    isBusinessDay?: (date: LocalDate) => boolean;
+    /**
+     * Latest selectable date. Default: the anchor date, so nothing beyond it can be selected. Set
+     * later than the anchor to allow selection of future dates.
+     */
+    maxDate?: LocalDate;
+    /** Earliest selectable date. Default: none. */
+    minDate?: LocalDate;
+    /**
+     * Options governing persistence. The value persists under a `dateRangePicker.value` path by
+     * default - set `path` to disambiguate multiple pickers sharing one provider.
+     */
+    persistWith?: DateRangePickerPersistOptions;
+    /**
+     * Presets offered on the Presets tab, in display order - tokens of Hoist's built-in
+     * {@link dateRangePresets}, app-defined {@link DateRangePreset} objects, or a mix.
+     * Default: {@link DEFAULT_DATE_RANGE_PRESETS}.
+     */
+    presets?: Array<DateRangePresetToken | DateRangePreset>;
+    /**
+     * Tabs to offer within the picker popover, in display order. Default: all tabs, less the
+     * Presets tab when `presets` is empty. A single tab renders without a rail.
+     */
+    tabs?: DateRangePickerTab[];
+    /** See {@link HoistBase.xhName}. */
+    xhName?: string;
+}
+export interface DateRangePickerPersistOptions extends PersistOptions {
+    /** True (default) to persist the value, or provide value-specific PersistOptions. */
+    persistValue?: boolean | PersistOptions;
+}
+/**
+ * App-wide overridable defaults for {@link DateRangePickerModel}. Instance config takes precedence.
+ */
+export interface DateRangePickerModelDefaults {
+    anchorDay?: DateRangeAnchorDay;
+    businessDayMode?: boolean;
+    commitOnChange?: boolean;
+    dateFormat?: DateRangeFormat;
+    singleDayFormat?: DateRangeFormat;
+}
+/**
+ * Model for a control that allows users to select a period of time - a preset (e.g. MTD, Prev
+ * 30 Days), a relative lookback (e.g. Prev 6 Months), a calendar month or year, or a custom
+ * range of dates - and the API through which an app reads the applied period.
+ *
+ * The value is a single compound {@link DateRangeSelection}, which this model resolves to a
+ * concrete {@link LocalDateRange} anchored to `anchorDate`, alongside the comparable prior range.
+ * The value is plain JSON, so it persists via `persistWith` (including through saved views)
+ * without custom serialization, and re-resolves as the anchor date moves forward - a persisted
+ * `mtd` stays month-to-date.
+ *
+ * The anchor date is live by default: this model keeps it on the current day as midnight passes,
+ * so every derived range, label, and filter follows without app intervention. See `anchorDay`.
+ *
+ * Construct one within an app model and render a {@link DateRangePicker} bound to it to let users
+ * view and change the value. The value and its derived ranges and filters stay live whether or
+ * not a picker is mounted - a locked dashboard widget, for example, can hide its picker but still
+ * query by period.
+ *
+ * @see DateRangePicker
+ * @see dateRangePresets
+ */
+export declare class DateRangePickerModel extends HoistModel {
+    /** App-level defaults for DateRangePickerModel. Instance config takes precedence. */
+    static defaults: DateRangePickerModelDefaults;
+    /** The applied selection, always in normalized form. Set via `setValue()`. */
+    value: DateRangeSelection;
+    /** Tabs offered in the popover, in display order. Set via `setTabs()` - the picker follows. */
+    tabs: DateRangePickerTab[];
+    /** Presets offered on the Presets tab, in display order. Set via `setPresets()`. */
+    presets: DateRangePreset[];
+    /** How the anchor date is determined - see {@link DateRangeAnchorDay}. Set via `setAnchorDay()`. */
+    anchorDay: DateRangeAnchorDay;
+    /**
+     * Date that relative and to-date selections resolve against - `anchorDay` resolved, and (in
+     * `businessDayMode`) snapped to a business day when live. Kept current by this model.
+     */
+    anchorDate: LocalDate;
+    /** The current day in the browser's time zone - the reader's "today". Kept current. */
+    today: LocalDate;
+    /** Earliest selectable date, or null if unbounded. Set via `setMinDate()`. */
+    minDate: LocalDate | null;
+    /** Business-day test used by `businessDayMode` and presets. Set via `setIsBusinessDay()`. */
+    isBusinessDay: (date: LocalDate) => boolean;
+    businessDayMode: boolean;
+    commitOnChange: boolean;
+    dateFormat: DateRangeFormat;
+    singleDayFormat: DateRangeFormat;
+    filterField: string;
+    /** The initial value, and the fallback for a missing or invalid persisted value. */
+    readonly defaultValue: DateRangeSelection;
+    private explicitMaxDate;
+    private anchorTimer;
+    /** Latest selectable date - the explicit `maxDate` config if set, otherwise `anchorDate`. */
+    get maxDate(): LocalDate;
+    /**
+     * True if the anchor date is the reader's current day - when `anchorDay` reads "Today". False
+     * for any other day, however the anchor got there (pinned, business-day snapped, or an app
+     * time zone a day apart from the browser's) - the picker then reads "As Of" with the date.
+     */
+    get isAnchorToday(): boolean;
+    /** Configured presets, keyed by token. */
+    get presetMap(): Record<string, DateRangePreset>;
+    /** The live context that selections resolve against. */
+    get context(): DateRangeContext;
+    /** Resolved date range for the applied value. */
+    get currentRange(): LocalDateRange;
+    /**
+     * The immediately preceding, non-overlapping range of comparable shape - the same span one
+     * unit earlier for a period-to-date, `count` units earlier for a lookback in weeks or larger
+     * units, an equal number of days for day-based windows. Null when the current range is
+     * unbounded.
+     */
+    get priorRange(): LocalDateRange | null;
+    /** Short label for the applied value - e.g. `MTD`, `Prev 6 Months`, `Aug 2026`, `Custom`. */
+    get label(): string;
+    /**
+     * Resolved range as `start ▸ end` per `dateFormat`, with `…` for an unbounded edge. A single
+     * day reads as that one date, per `singleDayFormat`.
+     */
+    get rangeLabel(): string;
+    /**
+     * Longer-form name for the applied value, suitable for panel titles - the period's name
+     * rather than its dates, with months spelled out (e.g. `August 2026`). A custom range, and the
+     * anchor day when it is not today, have no name beyond their dates, so they read as those.
+     */
+    get displayName(): string;
+    /**
+     * True when `label` alone does not identify the period - a custom range, or the anchor day
+     * when it is not today and so reads only as `As Of`. The picker shows the dates instead.
+     */
+    get labelNeedsDates(): boolean;
+    /** True if `stepRange(-1)` would move the applied range - bounded and not yet at `minDate`. */
+    get canStepBack(): boolean;
+    /** True if `stepRange(1)` would move the applied range - bounded, and not yet at `maxDate`. */
+    get canStepForward(): boolean;
+    /** Filters for `currentRange` on `filterField`, ready to apply to a Store, View, or query. */
+    get currentRangeFilter(): FieldFilterSpec[];
+    /** Filters for `priorRange` on `filterField`. Empty when there is no prior range. */
+    get priorRangeFilter(): FieldFilterSpec[];
+    constructor({ tabs, presets, initialValue, anchorDay, businessDayMode, commitOnChange, minDate, maxDate, isBusinessDay, filterField, dateFormat, singleDayFormat, persistWith, xhName }?: DateRangePickerConfig);
+    /**
+     * Set the applied value. Accepts a preset token string as shorthand for a preset selection.
+     * An invalid value (unknown preset, out-of-bounds count or year, malformed date) is logged
+     * and ignored.
+     */
+    setValue(value: DateRangeSelection | DateRangePresetToken | string): void;
+    setTabs(tabs: DateRangePickerTab[]): void;
+    setPresets(presets: Array<DateRangePresetToken | DateRangePreset>): void;
+    /** Set how the anchor date is determined - see {@link DateRangeAnchorDay}. */
+    setAnchorDay(anchorDay: DateRangeAnchorDay): void;
+    setMinDate(minDate: LocalDate | null): void;
+    /** Set the latest selectable date, or null to revert to `anchorDate`. */
+    setMaxDate(maxDate: LocalDate | null): void;
+    setIsBusinessDay(isBusinessDay: (date: LocalDate) => boolean): void;
+    /**
+     * Move the applied range by `steps` periods - e.g. `stepRange(-1)` for the previous period.
+     * No selection changes kind: presets and relative lookbacks step through their own prior- and
+     * next-range logic via `offset`, months and years by calendar unit, and custom ranges by their
+     * length. Stops at `minDate` and `maxDate`, and a no-op when the range cannot move - see
+     * {@link stepDateRangeSelection}.
+     */
+    stepRange(steps: number): void;
+    /** The selection `stepRange(steps)` would apply, or null if the range cannot move that way. */
+    getSteppedValue(steps: number): DateRangeSelection | null;
+    /**
+     * Validate and normalize a raw value against this model's presets. Returns null for anything
+     * unrecognized - see {@link parseDateRangeSelection}.
+     */
+    parseValue(raw: unknown): DateRangeSelection | null;
+    validateValue(raw: unknown): boolean;
+    /** Resolve any selection against this model's current context. */
+    resolve(sel: DateRangeSelection): ResolvedDateRange;
+    /** Short label for any selection, as it would read on the picker trigger. */
+    getLabel(sel: DateRangeSelection): string;
+    /**
+     * Filters bounding `field` to the given range - a `>=` filter for a bounded start and a `<=`
+     * filter for a bounded end, so an unbounded range produces no filters at all.
+     */
+    getRangeFilter(range: LocalDateRange, field?: string): FieldFilterSpec[];
+    /** Format a range as `start ▸ end` per this model's `dateFormat` - a single day per `singleDayFormat`. */
+    fmtRange(range: LocalDateRange): string;
+    /** Format a single day per this model's `singleDayFormat`. */
+    fmtSingleDay(date: LocalDate): string;
+    private get resolvedValue();
+    /** True unless `anchorDay` is a pinned LocalDate. */
+    private get isLiveAnchor();
+    /**
+     * Re-evaluate `today` and `anchorDate` from `anchorDay`. Assignments are identity no-ops until
+     * the day actually changes, as LocalDate instances are memoized.
+     */
+    private refreshAnchorDate;
+    private initPersist;
+    /**
+     * Persisted state can be missing (a saved view with no value) or stale (a preset since
+     * removed) - either way, fall back to the default rather than carrying a prior value over.
+     */
+    private restoreValue;
+    /**
+     * `defaultValue` while it still resolves, else the first configured preset, else a rolling 30
+     * days - `defaultValue` can itself name a preset that `setPresets()` has since removed.
+     */
+    private get fallbackValue();
+}

package/build/types/cmp/daterange/DateRangePresets.d.ts

@@ -0,0 +1,26 @@
+import type { DateRangePreset, DateRangePresetToken } from './Types';
+/**
+ * Presets shipped with Hoist, keyed by token. Offer any subset (in any order) via the `presets`
+ * config of {@link DateRangePickerModel}, alongside any app-defined {@link DateRangePreset}s.
+ *
+ * Labels describe a range without claiming it ends today, since the anchor date need not be
+ * today: `Prev 7 Days` rather than `Last 7 Days`. The one exception is `anchorDay`, which reads
+ * `Today` when the anchor date is the current day and `As Of` otherwise - the trigger's dates
+ * supply the day itself.
+ *
+ * Period-to-date presets (`wtd`, `mtd`, `qtd`, `ytd`) resolve their prior range as the same span
+ * one unit earlier - e.g. MTD on the 12th compares against the 1st through 12th of the prior
+ * month. Previous-unit presets (`prevWeek`, `prevMonth`, ...) compare against the unit before.
+ * Rolling windows compare against the window of equal length immediately preceding them. The
+ * same logic, mirrored by `resolveNext`, drives stepping: `mtd` stepped back once is the prior MTD.
+ *
+ * A preset that names a specific period reads the same as a pick of that period on the Months &
+ * Years tab - `prevMonth` labels as e.g. `Aug 2026` and `prevYear` as `2025` - so the trigger
+ * describes the period, whichever way it was chosen. The underlying values stay distinct: a preset
+ * re-resolves against the anchor date as time passes, where a pinned month or year does not.
+ */
+export declare const dateRangePresets: Record<DateRangePresetToken, DateRangePreset>;
+/** Tokens of the presets shipped with Hoist, in a sensible display order. */
+export declare const DATE_RANGE_PRESET_TOKENS: DateRangePresetToken[];
+/** Presets offered by {@link DateRangePickerModel} when none are configured. */
+export declare const DEFAULT_DATE_RANGE_PRESETS: DateRangePresetToken[];

package/build/types/cmp/daterange/DateRangeUtils.d.ts

@@ -0,0 +1,96 @@
+import { LocalDate } from '@xh/hoist/utils/datetime';
+import type { DateRangeContext, DateRangeFormat, DateRangePickerTab, DateRangePreset, DateRangeSelection, DateRangeUnit, LocalDateRange, ResolvedDateRange } from './Types';
+/** All picker tabs, in their default display order. */
+export declare const DATE_RANGE_PICKER_TABS: DateRangePickerTab[];
+/** Units offered on the Relative tab's unit control, in display order. */
+export declare const DATE_RANGE_UNITS: DateRangeUnit[];
+/** Largest `count` accepted for a relative selection. */
+export declare const MAX_RELATIVE_COUNT = 999;
+/** Furthest a preset or relative selection can be stepped from its natural range, either way. */
+export declare const MAX_STEP_OFFSET = 9999;
+/** Year bounds for month and year selections - shared by validation and picker navigation. */
+export declare const MIN_SELECTION_YEAR = 1900;
+export declare const MAX_SELECTION_YEAR = 9999;
+/**
+ * Resolve a selection to its current range, and to the comparable range immediately before it.
+ * Throws if the selection is a preset unknown to the context - validate with
+ * {@link parseDateRangeSelection} first for untrusted input.
+ */
+export declare function resolveDateRange(sel: DateRangeSelection, ctx: DateRangeContext): ResolvedDateRange;
+/** A range of the one given day. */
+export declare function singleDay(day: LocalDate): LocalDateRange;
+/**
+ * The nearest business day strictly before `date`, per the context's `isBusinessDay`. Bounded, to
+ * guard against a test that never returns true.
+ */
+export declare function previousBusinessDay(date: LocalDate, ctx: BusinessDayContext): LocalDate;
+/** The nearest business day strictly after `date`, per the context's `isBusinessDay`. Bounded. */
+export declare function nextBusinessDay(date: LocalDate, ctx: BusinessDayContext): LocalDate;
+/** `date` itself if it is a business day, else the nearest business day before it. */
+export declare function businessDayOnOrBefore(date: LocalDate, ctx: BusinessDayContext): LocalDate;
+type BusinessDayContext = Pick<DateRangeContext, 'isBusinessDay'>;
+/**
+ * The day before `date` - the previous business day in `businessDayMode`, else the previous
+ * calendar day. The step taken by single-day presets and their prior ranges.
+ */
+export declare function previousDayInMode(date: LocalDate, ctx: DateRangeContext): LocalDate;
+/** The day after `date` - the next business day in `businessDayMode`, else the next calendar day. */
+export declare function nextDayInMode(date: LocalDate, ctx: DateRangeContext): LocalDate;
+/**
+ * Validate and normalize a raw (e.g. persisted or app-supplied) value into a
+ * {@link DateRangeSelection}. Accepts a bare preset token string as shorthand for a preset
+ * selection. Returns null for anything unrecognized, out of bounds, or naming a preset not in
+ * `presets` - callers should substitute their default.
+ */
+export declare function parseDateRangeSelection(raw: unknown, presets: Record<string, DateRangePreset>): DateRangeSelection | null;
+/**
+ * Short label for a selection, suitable for the picker trigger - e.g. `MTD`, `Prev 6 Months`,
+ * `Aug 2026`, `2025`, or `Custom`.
+ *
+ * Month and year picks read as the period they name - `Sep 2026`, `2026` - even when clamped to
+ * the anchor date, with the trigger's dates showing the clamp. `MTD` and `YTD` are reserved for
+ * the presets, which are live and step to the same partial span a unit earlier, where a pinned
+ * month or year steps by whole units. The `prevMonth` and `prevYear` presets read as the period
+ * too, since they resolve to a full one.
+ *
+ * Once stepped to a non-zero offset, the trigger's dates locate the range and the label describes
+ * only its shape: a rolling window reads as its length (`7 Days`, `3 Months`), a named period as
+ * the period (`Jul 2026`), and a to-date preset as its name with the signed offset (`MTD −1`,
+ * `MTD +1`).
+ */
+export declare function getDateRangeLabel(sel: DateRangeSelection, ctx: DateRangeContext): string;
+/** Display name for a preset's row within the picker - its `name`, falling back to its `label`. */
+export declare function getDateRangePresetName(preset: DateRangePreset, ctx: DateRangeContext): string;
+/** A signed offset as `−n` or `+n`, with a true minus sign - the default suffix for a stepped label. */
+export declare function fmtDateRangeOffset(offset: number): string;
+/** Title-case unit label, singular when count is 1 - e.g. `Days`, `Month`. */
+export declare function getDateRangeUnitLabel(unit: DateRangeUnit, count?: number): string;
+/** Format a date per a {@link DateRangeFormat} - a moment.js format string or a function. */
+export declare function fmtDate(date: LocalDate, format: DateRangeFormat): string;
+/**
+ * Format a range as `start ▸ end` per `dateFormat`, with `…` for an unbounded edge. A single-day
+ * range formats as that one date per `singleDayFormat`, which defaults to `dateFormat`. Returns an empty
+ * string for a null range.
+ */
+export declare function fmtDateRange(range: LocalDateRange, dateFormat?: DateRangeFormat, singleDayFormat?: DateRangeFormat): string;
+/** First day of the given month (1-12) of the given year. */
+export declare function getMonthStart(year: number, month: number): LocalDate;
+/** First day of the given quarter (1-4) of the given year. */
+export declare function getQuarterStart(year: number, quarter: number): LocalDate;
+/**
+ * Move a selection by `steps` periods - negative to go back, positive to go forward. No selection
+ * changes kind:
+ *
+ * - Preset and relative selections adjust their `offset`, stepping through their own prior- and
+ *   next-range logic - so a lookback in months steps by months, and a single day steps by
+ *   business day in `businessDayMode`. Their natural range ends on the anchor date, so a positive
+ *   offset is reachable only when `maxDate` allows dates beyond it.
+ * - Month, quarter and year selections step by calendar unit.
+ * - Custom selections step by their length in days - or by business day when a single day in
+ *   `businessDayMode`.
+ *
+ * Steps stop at the context's `minDate` and `maxDate`. Returns null when the selection cannot
+ * move that way: it is already at a bound, or unbounded.
+ */
+export declare function stepDateRangeSelection(sel: DateRangeSelection, steps: number, ctx: DateRangeContext): DateRangeSelection | null;
+export {};

package/build/types/cmp/daterange/Types.d.ts

@@ -0,0 +1,152 @@
+import type { LocalDate } from '@xh/hoist/utils/datetime';
+/** An inclusive range of days. A null edge is unbounded. */
+export interface LocalDateRange {
+    start: LocalDate | null;
+    end: LocalDate | null;
+}
+/** A selection resolved to its current range and the comparable range immediately before it. */
+export interface ResolvedDateRange {
+    current: LocalDateRange;
+    /** The immediately preceding, non-overlapping range of comparable shape, or null if none. */
+    prior: LocalDateRange | null;
+}
+/** Calendar units supported by relative selections. */
+export type DateRangeUnit = 'days' | 'weeks' | 'months' | 'quarters' | 'years';
+/**
+ * How the picker renders a date - a moment.js format string, or a function for formats that
+ * depend on the date itself, e.g. one that adds the year only when it is not the current year.
+ */
+export type DateRangeFormat = string | ((date: LocalDate) => string);
+/** Tabs available within the DateRangePicker popover. */
+export type DateRangePickerTab = 'presets' | 'relative' | 'period' | 'custom';
+/**
+ * The day that relative and to-date selections resolve against - see the `anchorDay` config of
+ * {@link DateRangePickerModel}.
+ *
+ * - `'localDay'` - the current day in the browser's time zone, kept current as the day rolls.
+ * - `'appDay'` - the current day in the app's time zone (`LocalDate.currentAppDay()`), likewise.
+ * - A `LocalDate` - a pinned day that never moves, honored verbatim.
+ * - A function returning a `LocalDate` - re-evaluated every few seconds and whenever any
+ *   observables it reads change. Must be pure and cheap. For as-of dates with their own rule, e.g.
+ *   the latest loaded data date, or a day that rolls forward at an evening cutoff.
+ */
+export type DateRangeAnchorDay = 'localDay' | 'appDay' | LocalDate | (() => LocalDate);
+/** Tokens for the presets shipped with Hoist - see {@link dateRangePresets}. */
+export type DateRangePresetToken = 'anchorDay' | 'prevDay' | 'wtd' | 'mtd' | 'qtd' | 'ytd' | 'prev7Days' | 'prev30Days' | 'prev90Days' | 'prev3Months' | 'prev6Months' | 'prev12Months' | 'prevWeek' | 'prevMonth' | 'prevQuarter' | 'prevYear' | 'all';
+/**
+ * The dates a selection resolves against - the live state of a {@link DateRangePickerModel}.
+ * Passed to preset resolvers and to the resolution utilities in this package.
+ */
+export interface DateRangeContext {
+    /** Date that relative and to-date selections resolve against. */
+    anchorDate: LocalDate;
+    /**
+     * The current day in the browser's time zone - what "Today" means to the person looking at
+     * the screen, whatever zone the anchor date is drawn from.
+     */
+    today: LocalDate;
+    /** Earliest selectable date, or null if unbounded. */
+    minDate: LocalDate | null;
+    /** Latest selectable date. Month, quarter and year selections spanning it are clamped to it. */
+    maxDate: LocalDate;
+    /** Whether a date is a business day - weekdays by default, or the model's `isBusinessDay`. */
+    isBusinessDay: (date: LocalDate) => boolean;
+    /** True if single-day selections step by business day - see the model config of that name. */
+    businessDayMode: boolean;
+    /** Presets available for selection, keyed by token. */
+    presets: Record<string, DateRangePreset>;
+}
+/**
+ * A named, one-click range offered on the picker's Presets tab. Hoist ships a set of common
+ * presets ({@link dateRangePresets}) - apps can offer a subset of those, add their own, or both
+ * via the `presets` config of {@link DateRangePickerModel}.
+ */
+export interface DateRangePreset {
+    /** Unique key for this preset. Persisted as the `token` of a `preset` selection. */
+    token: string;
+    /** Short label for the picker trigger, e.g. `MTD`. May be derived from the context. */
+    label: string | ((ctx: DateRangeContext) => string);
+    /** Longer name for the preset's row in the picker, e.g. `Month to Date`. Default `label`. */
+    name?: string | ((ctx: DateRangeContext) => string);
+    /** Resolve this preset to a concrete range. */
+    resolve: (ctx: DateRangeContext) => LocalDateRange;
+    /**
+     * Resolve the comparable prior range for a given current range. Default is the immediately
+     * preceding range of equal duration in days, or null when the current range is unbounded.
+     * Also drives stepping back: a selection at `offset` -n is this applied n times.
+     */
+    resolvePrior?: (current: LocalDateRange, ctx: DateRangeContext) => LocalDateRange | null;
+    /**
+     * Resolve the comparable range immediately after a given current range - the mirror of
+     * `resolvePrior`, driving stepping forward when `maxDate` allows dates beyond the anchor.
+     * Default is the immediately following range of equal duration in days, or null when the
+     * current range is unbounded.
+     */
+    resolveNext?: (current: LocalDateRange, ctx: DateRangeContext) => LocalDateRange | null;
+    /**
+     * Label for this preset once stepped to a non-zero `offset`, when the trigger's dates locate
+     * the range and the label need only describe its shape - e.g. `7 Days` for a rolling window,
+     * or the month itself for a previous-month preset. Default is the label with the signed
+     * offset appended, e.g. `MTD −1`.
+     */
+    shiftedLabel?: (range: LocalDateRange, offset: number, ctx: DateRangeContext) => string;
+}
+/** A one-click preset, re-resolved against the anchor date as time passes. */
+export interface PresetDateRangeSelection {
+    kind: 'preset';
+    /** Token of a preset configured on the owning model. */
+    token: string;
+    /**
+     * Number of periods stepped from the preset's natural range - negative for earlier periods,
+     * each applying the preset's prior-range logic once, positive for later ones (reachable only
+     * when `maxDate` allows dates beyond the anchor). Omitted when zero. See `stepRange()`.
+     */
+    offset?: number;
+}
+/** A lookback of `count` units ending on the anchor date. */
+export interface RelativeDateRangeSelection {
+    kind: 'relative';
+    /** Number of units, from 1 to {@link MAX_RELATIVE_COUNT}. */
+    count: number;
+    unit: DateRangeUnit;
+    /**
+     * True to snap the window to calendar boundaries of `unit`, counting the current (partial)
+     * unit as one - e.g. 3 calendar months ending today covers the prior two full months plus
+     * the current month to date. False (default) for a rolling window of exactly `count` units
+     * ending on the anchor date. Has no effect for days, where each day is its own boundary.
+     */
+    snap?: boolean;
+    /** Periods stepped from the natural window - negative back, positive forward. Omitted when zero. */
+    offset?: number;
+}
+/** A calendar month, clamped to the context's `maxDate` when that date falls within it. */
+export interface MonthDateRangeSelection {
+    kind: 'month';
+    year: number;
+    /** Month of the year, 1-12. */
+    month: number;
+}
+/** A calendar quarter, clamped to the context's `maxDate` when that date falls within it. */
+export interface QuarterDateRangeSelection {
+    kind: 'quarter';
+    year: number;
+    /** Quarter of the year, 1-4. */
+    quarter: number;
+}
+/** A calendar year, clamped to the context's `maxDate` when that date falls within it. */
+export interface YearDateRangeSelection {
+    kind: 'year';
+    year: number;
+}
+/** A fixed range of specific dates, as `YYYY-MM-DD` strings so the value persists as plain JSON. */
+export interface CustomDateRangeSelection {
+    kind: 'custom';
+    start: string;
+    end: string;
+}
+/**
+ * The value of a {@link DateRangePickerModel} - a user's period selection, resolved to concrete
+ * dates against a {@link DateRangeContext}. Plain JSON in all its forms, so it round-trips through
+ * persistence without custom serialization.
+ */
+export type DateRangeSelection = PresetDateRangeSelection | RelativeDateRangeSelection | MonthDateRangeSelection | QuarterDateRangeSelection | YearDateRangeSelection | CustomDateRangeSelection;

package/build/types/cmp/daterange/index.d.ts

@@ -0,0 +1,4 @@
+export * from './DateRangePickerModel';
+export * from './DateRangePresets';
+export * from './DateRangeUtils';
+export * from './Types';

package/build/types/cmp/filter/FilterChooserModel.d.ts

@@ -73,6 +73,8 @@ export interface FilterChooserConfig {
     introHelpText?: ReactNode;
     /** Options governing persistence. */
     persistWith?: FilterChooserPersistOptions;
+    /** See {@link HoistBase.xhName}. */
+    xhName?: string;
 }
 /**
  * Model for a Select-based filter control that allows users to search for and compose filters
@@ -113,7 +115,7 @@ export declare class FilterChooserModel extends HoistModel {
     unsupportedFilter: boolean;
     inputRef: import("react").RefObject<HTMLElement> & import("react").RefCallback<HTMLElement>;
     get tagCount(): number;
-    constructor({ fieldSpecs, fieldSpecDefaults, bind, valueSource, initialValue, initialFavorites, suggestFieldsWhenEmpty, sortFieldSuggestions, maxTags, maxResults, persistWith, introHelpText }?: FilterChooserConfig);
+    constructor({ fieldSpecs, fieldSpecDefaults, bind, valueSource, initialValue, initialFavorites, suggestFieldsWhenEmpty, sortFieldSuggestions, maxTags, maxResults, persistWith, introHelpText, xhName }?: FilterChooserConfig);
     /**
      * Set the value displayed by this control.
      *

package/build/types/cmp/form/FormModel.d.ts

@@ -20,6 +20,8 @@ export interface FormConfig {
     persistWith?: FormPersistOptions;
     disabled?: boolean;
     readonly?: boolean;
+    /** See {@link HoistBase.xhName}. */
+    xhName?: string;
     /** @internal */
     xhImpl?: boolean;
 }
@@ -81,7 +83,7 @@ export declare class FormModel extends HoistModel {
      * See {@link getData} instead if you need to get or react to the values of *any/all* fields.
      */
     get values(): PlainObject;
-    constructor({ fields, initialValues, disabled, persistWith, readonly, xhImpl }?: FormConfig);
+    constructor({ fields, initialValues, disabled, persistWith, readonly, xhName, xhImpl }?: FormConfig);
     getField(fieldName: string): BaseFieldModel;
     /**
      * Snapshot of current field values, keyed by field name.

package/build/types/cmp/grid/GridModel.d.ts

@@ -224,6 +224,8 @@ export interface GridConfig {
     experimental?: GridExperimentalFlags;
     /** Extra app-specific data for the GridModel. */
     appData?: PlainObject;
+    /** See {@link HoistBase.xhName}. */
+    xhName?: string;
     /** @internal */
     xhImpl?: boolean;
 }

package/build/types/cmp/grid/Types.d.ts

@@ -120,6 +120,8 @@ export interface GridFilterModelConfig {
      * Defaults to `Icon.filter()` (the standard funnel icon in regular/outline style).
      */
     activeFilterIcon?: ReactElement;
+    /** See {@link HoistBase.xhName}. */
+    xhName?: string;
 }
 /**
  * {@link GridFilterModel} currently accepts a single `bind` target that also provides available

package/build/types/cmp/grid/filter/GridFilterModel.d.ts

@@ -22,7 +22,7 @@ export declare class GridFilterModel extends HoistModel {
     get filter(): Filter;
     dialogOpen: boolean;
     static BLANK_PLACEHOLDER: string;
-    constructor({ bind, commitOnChange, fieldSpecs, fieldSpecDefaults, activeFilterIcon }: GridFilterModelConfig, gridModel: GridModel);
+    constructor({ bind, commitOnChange, fieldSpecs, fieldSpecDefaults, activeFilterIcon, xhName }: GridFilterModelConfig, gridModel: GridModel);
     /**
      * Set / replace the filters for a given field.
      * @param field - field to identify this filter

package/build/types/cmp/grouping/GroupingChooserModel.d.ts

@@ -51,6 +51,8 @@ export interface GroupingChooserConfig {
      * provided in the `dimensions` config.
      */
     sortDimensions?: boolean;
+    /** See {@link HoistBase.xhName}. */
+    xhName?: string;
 }
 export interface GroupingChooserModelDefaults {
     commitOnChange?: boolean;
@@ -104,7 +106,7 @@ export declare class GroupingChooserModel extends HoistModel {
     dimensionNames: string[];
     get dimensionSpecs(): DimensionSpec[];
     get valueDisplayNames(): string[];
-    constructor({ allowEmpty, bind, commitOnChange, dimensions, initialFavorites, initialValue, maxDepth, persistWith, sortDimensions }: GroupingChooserConfig);
+    constructor({ allowEmpty, bind, commitOnChange, dimensions, initialFavorites, initialValue, maxDepth, persistWith, sortDimensions, xhName }: GroupingChooserConfig);
     setDimensions(dimensions: Array<DimensionSpec | string>): void;
     setValue(value: string[]): void;
     validateValue(value: string[]): boolean;