@sesamehr/react-design-system 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/Forms/Inputs/Combobox/ComboboxItem.d.ts

@@ -6,5 +6,9 @@ export interface ComboboxItemProps extends Omit<React.ComponentPropsWithoutRef<t
 /**
  * ComboboxItem — a selectable option, with its own check indicator.
  * Selecting commits the value through the shared context (toggles for multiple).
+ *
+ * See `SelectItem` for why the row is shared and the primitive wrapping it is
+ * not. The indicator is always passed, even while unchecked, so the space it
+ * needs is reserved once rather than appearing the moment the row is picked.
  */
 export declare const ComboboxItem: import('react').ForwardRefExoticComponent<ComboboxItemProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/Combobox/ComboboxItemEdit.d.ts

@@ -0,0 +1,134 @@
+export interface ComboboxItemEditPreview {
+    /**
+     * Enter the editing state. Pass it straight to the control that starts the
+     * edit — `onClick={edit}` — so it receives the event and can stop it.
+     */
+    edit: (event?: {
+        stopPropagation: () => void;
+    }) => void;
+}
+export interface ComboboxItemEditField {
+    /** The text as it currently stands. */
+    value: string | undefined;
+    /** Report a keystroke from the field. */
+    setValue: (value: string | undefined) => void;
+    /** Save, and leave the editing state. */
+    commit: () => void;
+    /** Put the text back as it was, and leave the editing state. */
+    cancel: () => void;
+}
+export interface ComboboxItemEditProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'onChange'> {
+    /**
+     * The text being edited. Pass it one way — `value={label}` — and let
+     * `onCommit` write the new one back: it seeds the draft and re-seeds it
+     * whenever it changes, so the caller never holds the draft and the field
+     * inside `field` never has a second copy of it to disagree with. Add
+     * `onValueChange` for a caller who wants every keystroke.
+     */
+    value?: string;
+    /** The starting text when nothing is passed for `value`. */
+    defaultValue?: string;
+    /** Every keystroke, for a caller controlling the draft. */
+    onValueChange?: (value: string | undefined) => void;
+    /** The edit was saved. Carries the text as it now stands. */
+    onCommit?: (value: string | undefined) => void;
+    /** The edit was abandoned; the draft has already been put back. */
+    onCancel?: () => void;
+    /** The row while it is being edited. */
+    field?: (context: ComboboxItemEditField) => React.ReactNode;
+    /** The row the rest of the time. */
+    children?: (context: ComboboxItemEditPreview) => React.ReactNode;
+}
+/**
+ * An option that can be renamed without leaving the list: the row shows its
+ * normal content until the caller's own control asks to edit it, then hands the
+ * row over to the caller's own field. Port of
+ * `core/src/Forms/Inputs/Combobox/ComboboxItemEdit`.
+ *
+ * It holds no strings and draws no buttons — the design system ships neither.
+ * What it owns is the part a caller cannot get right from outside: a list whose
+ * every reflex is to select the row and close, aimed at a field that needs the
+ * click, the keystroke and the `Escape` for itself.
+ *
+ * ```tsx
+ * <OxComboboxItem value="other">
+ *   <OxComboboxItemEdit
+ *     value={label}
+ *     onCommit={next => setLabel(next ?? '')}
+ *     field={({ value, setValue, commit }) => (
+ *       <>
+ *         <OxInputText size="sm" field={value} onFieldChange={setValue} />
+ *         <OxButton variant="ghost" onClick={commit}>…</OxButton>
+ *       </>
+ *     )}
+ *   >
+ *     {({ edit }) => (
+ *       <>
+ *         {label}
+ *         <OxButton variant="ghost" onClick={edit}>…</OxButton>
+ *       </>
+ *     )}
+ *   </OxComboboxItemEdit>
+ * </OxComboboxItem>
+ * ```
+ *
+ * Both states live here rather than behind the caller's own conditional for one
+ * reason worth the extra render prop: the control that *starts* the edit is
+ * itself inside the row, so its click selects the option and shuts the popover
+ * unless it is stopped. `edit` stops it. A caller assembling the two states
+ * themselves has to know that, and the version that does not know it looks
+ * exactly right until it is clicked.
+ *
+ * ### What is taken away from the list while editing, and by whom
+ *
+ * The Vue half is fighting reka; this one is fighting cmdk, and the two land on
+ * very nearly the same list:
+ *
+ * - **The click.** cmdk's `CommandItem` calls `onSelect` on `click`, and a
+ *   single-select combobox turns a selection into `setOpen(false)`. Clicking
+ *   into the field is a click on the row, so the popover closed under the
+ *   cursor that opened it.
+ * - **`Enter`.** cmdk's `Command` dispatches a select on the highlighted row,
+ *   which is the same close by another route. Here it is what saves the edit.
+ * - **`ArrowUp` / `ArrowDown` / `Home` / `End`.** All four are
+ *   `preventDefault()`ed by `Command`, so the caret could not be moved.
+ * - **`pointermove`.** `CommandItem` moves the highlight onto the row under the
+ *   cursor.
+ * - **`Space`** is in the list for the Vue half's sake — reka's `ListboxItem`
+ *   selects on it *with `prevent`*, so a name with two words in it could not be
+ *   typed. cmdk leaves the space bar alone; stopping it here costs nothing and
+ *   keeps one list of claimed keys instead of two that drift.
+ *
+ * `Escape` is deliberately absent and is answered in `ComboboxContent`. See
+ * `useComboboxEditing` for why it cannot be answered here.
+ *
+ * ### Focus
+ *
+ * Nothing in this half steals focus the way reka's listbox can, so there is no
+ * equivalent of the `focusable` flag the Vue port suspends and restores:
+ * Radix's popover is non-modal and `onOpenAutoFocus` is already prevented,
+ * cmdk's highlight is an `aria-activedescendant` rather than a real focus move,
+ * and its one refocusing path fires only when the active element is cmdk's own
+ * input or root — never a field inside a row. What is left is the same on both
+ * sides: take focus on entering the edit, hand it back to the combobox's own
+ * field on leaving.
+ *
+ * **A dialog around the combobox is free here and was not in Vue.** A dialog
+ * traps focus, the popover is portalled to `body` and is therefore outside what
+ * the trap considers the dialog, so the `.focus()` below reads as focus
+ * escaping — unless a nearer focus layer has suspended the trap.
+ * `Popover.Content` registers one in every Radix build, untrapped when the
+ * popover is non-modal, which ours is. reka gives `SelectContentImpl`,
+ * `PopoverContentImpl` and `MenuContentImpl` a `FocusScope` and
+ * `ComboboxContentImpl` none, so the Vue `ComboboxContent` has to add the layer
+ * by hand to reach the behaviour this side gets for nothing.
+ *
+ * **One thing here has no Vue counterpart.** cmdk re-sorts the option elements
+ * by moving the DOM nodes themselves whenever the search term changes, and a
+ * focused field inside a row that gets reparented loses focus. Typing in the
+ * combobox's own search box while a row edit is open is therefore not the same
+ * experience in the two packages. Editing is reached by clicking a control in
+ * the row, which leaves the search box unfocused, so it takes a deliberate
+ * detour to hit.
+ */
+export declare const ComboboxItemEdit: import('react').ForwardRefExoticComponent<ComboboxItemEditProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Inputs/Combobox/context.d.ts

@@ -1,3 +1,4 @@
+import { ComboboxEditing } from './useComboboxEditing.ts';
 /**
  * Shared Combobox state.
  *
@@ -6,7 +7,7 @@
  * every part needs — the value, `multiple`, `disabled` and the search term — so
  * a part can be used on its own without threading props through the tree.
  */
-export interface ComboboxContextValue {
+export interface ComboboxContextValue extends ComboboxEditing {
     /** Current selection. `string` for single-select, `string[]` for multiple. */
     value: string | string[] | undefined;
     /** Commit a selection (toggles for `multiple`). */
@@ -21,6 +22,25 @@ export interface ComboboxContextValue {
     /** Search string driving cmdk filtering. */
     search: string;
     setSearch: (search: string) => void;
+    /** Typing: restart the quiet period before the root's `onSearch`. */
+    scheduleSearch: (term: string) => void;
+    /** A gesture that settles the term — clearing it. Report now. */
+    searchImmediately: (term: string) => void;
+    /** Whether cmdk should leave the rendered options alone. */
+    skipFilter: boolean;
+    /**
+     * The text each option renders, keyed by the value it selects, so the field
+     * can show `Barcelona` rather than `barcelona`. See `useComboboxLabels` for
+     * why it never forgets an entry.
+     */
+    registerLabel: (value: string, label: string) => void;
+    labelFor: (value: string) => string | undefined;
+    /**
+     * The field itself, so a row that took focus for an in-place edit can hand it
+     * back when the edit ends. reka carries the same element on its own combobox
+     * context, which is where the Vue half gets it.
+     */
+    inputRef: React.RefObject<HTMLInputElement | null>;
 }
 export declare const ComboboxContext: import('react').Context<ComboboxContextValue | null>;
 export declare function useComboboxContext(): ComboboxContextValue;

package/dist/Forms/Inputs/Combobox/index.d.ts

@@ -1,8 +1,10 @@
 export { Combobox, type ComboboxProps } from './Combobox.tsx';
+export { ComboboxCancel, type ComboboxCancelProps } from './ComboboxCancel.tsx';
 export { ComboboxInput, type ComboboxInputProps } from './ComboboxInput.tsx';
 export { ComboboxChipsInput, type ComboboxChipsInputProps, } from './ComboboxChipsInput.tsx';
 export { ComboboxContent, type ComboboxContentProps, } from './ComboboxContent.tsx';
 export { ComboboxItem, type ComboboxItemProps } from './ComboboxItem.tsx';
+export { ComboboxItemEdit, type ComboboxItemEditProps, } from './ComboboxItemEdit.tsx';
 export { ComboboxEmpty, type ComboboxEmptyProps } from './ComboboxEmpty.tsx';
 export { ComboboxGroup, type ComboboxGroupProps } from './ComboboxGroup.tsx';
 export { ComboboxSeparator, type ComboboxSeparatorProps, } from './ComboboxSeparator.tsx';

package/dist/Forms/Inputs/Combobox/useChipOverflow.d.ts

@@ -0,0 +1,30 @@
+import { RefObject } from 'react';
+export interface ChipOverflowTargets {
+    /**
+     * The single-line row holding the chips, the `+N` counter and the query
+     * field. Its width is the whole budget, which only holds because the row is
+     * laid out `flex: 1 1 0` with `min-width: 0` — its width is then whatever its
+     * siblings leave behind and owes nothing to its own content. Measuring an
+     * element whose size depends on how many chips we decided to show is exactly
+     * what turns this into an infinite loop.
+     */
+    row: RefObject<HTMLElement | null>;
+    /** Offscreen stand-in for the `+N` counter, rendered at its widest. */
+    sizer: RefObject<HTMLElement | null>;
+}
+/**
+ * Decides how many chips of a multi-select field fit on one line.
+ *
+ * The chips past the edge are not removed from the DOM — the component keeps
+ * them rendered and takes them out of flow — so every chip reports its natural
+ * width on every pass, whether or not it is currently shown. That is the whole
+ * trick: nothing measured here changes as a result of what is decided here, so
+ * a measurement can never provoke the measurement that follows it.
+ *
+ * With no layout at all — a test environment, the tick before styles land —
+ * every width reads zero, `0 <= 0` holds, and the answer is "all of them".
+ * Showing the full selection is the right way to be wrong: it is what the field
+ * did before, and it fails towards markup that shows too much rather than a
+ * field that hides its own contents.
+ */
+export declare function useChipOverflow({ row, sizer }: ChipOverflowTargets, total: number): number;

package/dist/Forms/Inputs/Combobox/useComboboxEditing.d.ts

@@ -0,0 +1,40 @@
+export interface ComboboxEditing {
+    /** The row entering its editing state announces how to back out of it. */
+    openEdit: (cancel: () => void) => void;
+    /** The row leaving its editing state withdraws that offer. */
+    closeEdit: (cancel: () => void) => void;
+    /**
+     * Back out of the open edit, if there is one. Returns whether there was —
+     * the caller uses that to decide whether the keystroke has been spent.
+     */
+    cancelOpenEdit: () => boolean;
+}
+/**
+ * Which row, if any, is currently being edited in place. Port of
+ * `core/src/Forms/Inputs/Combobox/useComboboxEditing`, where Vue's
+ * `provide`/`inject` does what this hook plus `ComboboxContext` do here.
+ *
+ * It exists for one keystroke. `Escape` inside the edit has to cancel the edit
+ * and leave the list open, and the only thing that can stop the list closing is
+ * the content's `onEscapeKeyDown`: Radix's dismissable layer listens on
+ * `document` with `capture: true`, so the editing field never sees the key
+ * first and cannot swallow it however hard it tries. The layer offers exactly
+ * one way out — `preventDefault()` on the event it hands up. So the content is
+ * where `Escape` has to be answered, the state is in the row, and this is the
+ * wire between them.
+ *
+ * The Vue half reaches the same arrangement from the opposite constraint: reka
+ * listens on `window` in the bubble phase, so there the field *would* see the
+ * key first, and handling it in both places would close the edit before the
+ * content was asked whether to prevent the dismissal — closing the list, which
+ * is the one thing this must not do. One mechanism, in the content, on both
+ * sides.
+ *
+ * A ref rather than state: nothing renders differently for knowing which row is
+ * open, and the only reader is an event handler, which wants the current value
+ * and not the one captured when it was last rendered.
+ *
+ * One edit at a time, and opening a second cancels the first: two rows in edit
+ * mode have two answers to `Escape` and no way to say which one the user meant.
+ */
+export declare function useComboboxEditing(): ComboboxEditing;

package/dist/Forms/Inputs/Combobox/useComboboxLabels.d.ts

@@ -0,0 +1,21 @@
+export interface ComboboxLabels {
+    /** Record the text an option renders, keyed by the value it selects. */
+    register: (value: string, label: string) => void;
+    /** The recorded text for a value, or `undefined` if no option ever had it. */
+    labelFor: (value: string) => string | undefined;
+}
+/**
+ * What lets the field show `Barcelona` where the caller wrote
+ * `<OxComboboxItem value="barcelona">Barcelona</OxComboboxItem>`. Port of
+ * `core/src/Forms/Inputs/Combobox/useComboboxLabels`, where Vue's
+ * `provide`/`inject` does what this hook plus `ComboboxContext` do here.
+ *
+ * **It never forgets.** That is the whole design decision, and it is not
+ * laziness: cmdk unmounts an option that does not match the search, so typing
+ * over a selection removes the very option the field is naming. A registry that
+ * dropped a label on unmount would blank the field mid-search, which is the
+ * common case, not the edge case. The cost is a label that outlives its option,
+ * which is the best answer available and strictly better than the raw value.
+ * Entries are per-root and die with it.
+ */
+export declare function useComboboxLabels(): ComboboxLabels;

package/dist/Forms/Inputs/Combobox/useComboboxSearch.d.ts

@@ -0,0 +1,20 @@
+export interface ComboboxSearch {
+    /** Typing: restart the quiet period, emit when it elapses. */
+    schedule: (term: string) => void;
+    /** A gesture that settles the term — clearing it. Emit now. */
+    immediately: (term: string) => void;
+}
+/**
+ * The wire between whichever field is typed into and the root's `onSearch`.
+ *
+ * The root is where `debounce` and `onSearch` belong — there are three fields
+ * (`ComboboxInput`, `ComboboxChipsInput`, and `ComboboxCancel` clearing one of
+ * them) and a prop on each would be the same number asked three times. The
+ * fields reach it through the shared context, beside `setSearch`.
+ *
+ * The fields report from their `onChange` rather than from the term itself,
+ * because the term is also written when a value is selected — the field is
+ * reset and the resolved label put in its place — and a search fired for the
+ * text of the option the user just picked is a request nobody asked for.
+ */
+export declare function useComboboxSearch(debounce: number, onSearch: ((term: string) => void) | undefined): ComboboxSearch;

package/dist/Forms/Inputs/DatePicker/DatePicker.d.ts

@@ -0,0 +1,51 @@
+import { CalendarDayState } from '../Calendar/CalendarDay.tsx';
+import { CalendarConstraints } from '../Calendar/constraints.ts';
+/**
+ * A field that shows the chosen day and opens a calendar to change it. Mirrors
+ * `@sesame/orxata-core` DatePicker.
+ *
+ * This is `OxCalendar` plus the three things a calendar deliberately refuses to
+ * own: a control to hang off, a popover to live in, and the opinionated header
+ * — the month and an arrow at each end — that an embedded calendar would have to
+ * strip. Nothing here reimplements any of them; `OxPopover`, `OxCalendar` and
+ * `OxDatePickerTrigger` do the work.
+ *
+ * Same date contract as the calendar: a `Date` at the boundary means the
+ * calendar day formed by its local year, month and day. The time is ignored on
+ * the way in and is local midnight on the way out.
+ *
+ * It ships no strings. The trigger shows the day formatted by `Intl` in the
+ * locale `LocaleProvider` publishes, and shows nothing at all until one is
+ * picked — a placeholder is words, so it is `children`'s to supply.
+ */
+export interface DatePickerProps extends Pick<React.ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
+    /** The chosen day, or `undefined` for none. Controlled. */
+    value?: Date;
+    /** The initially chosen day, for the uncontrolled case. */
+    defaultValue?: Date;
+    onValueChange?: (value: Date | undefined) => void;
+    /** How many month grids the popover shows. */
+    months?: number;
+    /** What can be picked, and where navigation stops. Passed straight through. */
+    constraints?: CalendarConstraints;
+    disabled?: boolean;
+    /**
+     * What the trigger shows. Falls back to the day from `Intl`, and to nothing
+     * while none is chosen — pass one to put a placeholder there.
+     */
+    children?: (state: {
+        value: Date | undefined;
+    }) => React.ReactNode;
+    /** The trailing glyph. Falls back to a calendar. */
+    icon?: React.ReactNode;
+    /** One day in the grid. Handed to `OxCalendar` untouched. */
+    day?: (props: {
+        date: Date;
+        state: CalendarDayState;
+    }) => React.ReactNode;
+    dataTestid: string;
+}
+export declare const DatePicker: {
+    ({ className, value, defaultValue, onValueChange, months, constraints, disabled, children, icon, day, dataTestid, }: DatePickerProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/Forms/Inputs/DatePicker/DatePickerHeader.d.ts

@@ -0,0 +1,65 @@
+import { CalendarConstraints } from '../Calendar/constraints.ts';
+import { CalendarNav } from '../Calendar/nav.ts';
+export interface DatePickerHeaderProps {
+    /** Everything the calendar's `header` render prop hands over, passed in. */
+    nav: CalendarNav;
+    /**
+     * The same object the calendar was given. Published to `children` rather than
+     * read here: the year selector offers the years `from` and `to` allow, which
+     * `canGoPrev` and `canGoNext` cannot answer for.
+     */
+    constraints?: CalendarConstraints;
+    /**
+     * What sits between the arrows. Falls back to the months on screen, named by
+     * `Intl`. Fill it with the two selectors to get the design's month-and-year
+     * variant, or with anything else that should be centred there.
+     */
+    children?: React.ReactNode;
+    dataTestid: string;
+}
+/**
+ * The header `Calendar` deliberately does not draw: one arrow at each end, and
+ * whatever names the months between them. Mirrors `@sesame/orxata-core`
+ * DatePickerHeader.
+ *
+ * It exists as its own component because the two pickers share it and because
+ * an embedded `OxCalendar` can wear it too —
+ *
+ * ```tsx
+ * <OxCalendar
+ *   header={nav => <OxDatePickerHeader nav={nav} dataTestid="calendar-header" />}
+ * />
+ * ```
+ *
+ * **Two arrows, not four.** There used to be a year jump at each end as well,
+ * because stepping a month at a time is no way to reach a birth year. The
+ * design answers that with a pair of dropdowns instead, which is both a shorter
+ * journey and one that says where it is going — so the outer arrows are gone
+ * and `OxDatePickerMonthSelect` / `OxDatePickerYearSelect` go in `children`:
+ *
+ * ```tsx
+ * <OxDatePickerHeader nav={nav} constraints={constraints} dataTestid="head">
+ *   <OxDatePickerMonthSelect dataTestid="head-month" />
+ *   <OxDatePickerYearSelect dataTestid="head-year" />
+ * </OxDatePickerHeader>
+ * ```
+ *
+ * `nav.goTo` survives the loss of the year arrows and is now what the selectors
+ * run on: stepping cannot express "the same month in 1974", and in React it
+ * cannot even accumulate — each `goToNext` is computed from the month of the
+ * render that produced it.
+ *
+ * **An arrow is absent, not disabled, when there is nothing that way.** The
+ * design has two independent show/hide axes for them and draws no disabled
+ * state, and `canGoPrev` / `canGoNext` already say exactly when a step is
+ * possible — so they drive presence rather than a second boolean the caller
+ * would have to keep in step with `constraints`.
+ *
+ * It ships no strings. The title is `Intl`'s, and each arrow announces the
+ * month it would move to, which is a date the locale formats rather than a
+ * phrase we would have to translate.
+ */
+export declare const DatePickerHeader: {
+    ({ nav, constraints, children, dataTestid, }: DatePickerHeaderProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/Forms/Inputs/DatePicker/DatePickerMonthSelect.d.ts

@@ -0,0 +1,27 @@
+export interface DatePickerMonthSelectProps {
+    dataTestid: string;
+}
+/**
+ * The month half of the design's "Month and Year Selector" header. Goes in
+ * `OxDatePickerHeader`'s `children`, beside `OxDatePickerYearSelect`. Mirrors
+ * `@sesame/orxata-core` DatePickerMonthSelect.
+ *
+ * It reads the visible month and the bounds out of the header's context rather
+ * than taking them as props: they are the header's already, and a part that
+ * asked for them again would put `nav` on the public API of every piece of a
+ * header a caller assembles.
+ *
+ * Twelve options, named by `Intl` in the locale `LocaleProvider` publishes —
+ * this ships no month names of its own. A month the bounds put out of reach is
+ * offered and disabled rather than dropped, so the list is the same twelve rows
+ * in the same order whatever the constraints say.
+ *
+ * The trigger carries no `aria-label`, and that is the no-strings rule rather
+ * than an oversight: the only honest label would be the word "month" in the
+ * user's language, which this package does not have. What it announces is its
+ * role and its value, and its value is the month it is showing.
+ */
+export declare const DatePickerMonthSelect: {
+    ({ dataTestid, }: DatePickerMonthSelectProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/Forms/Inputs/DatePicker/DatePickerTrigger.d.ts

@@ -0,0 +1,29 @@
+export interface DatePickerTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Nothing chosen yet. Dims the content and marks the button
+     * `data-placeholder`, the flag `OxSelectTrigger` already uses for the same
+     * state — so the styling is a boolean and not a second slot.
+     */
+    empty?: boolean;
+    /** The trailing glyph. Falls back to a calendar. */
+    icon?: React.ReactNode;
+    dataTestid: string;
+}
+/**
+ * The closed control both pickers hang off: what is chosen on one side, a
+ * calendar glyph on the other. Mirrors `@sesame/orxata-core` DatePickerTrigger.
+ *
+ * It is one component and not two copies because the alternative is two
+ * stylesheets describing the same control. That is exactly how `OxSelect` and
+ * `OxCombobox` came to disagree about a radius, a border and a background, and
+ * the fix cost more than the component.
+ *
+ * It takes no size prop: height and radius come from the `--controller-*`
+ * variables every input in the package reads, so `inputSizeClass[size]` on any
+ * ancestor sizes it. Its declarations are `OxSelectTrigger`'s, so the two sit
+ * level in one form.
+ *
+ * It shows what it is given and formats nothing. A date is a date in a locale,
+ * and the picker above it is the one holding the locale.
+ */
+export declare const DatePickerTrigger: import('react').ForwardRefExoticComponent<DatePickerTriggerProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/Forms/Inputs/DatePicker/DatePickerYearSelect.d.ts

@@ -0,0 +1,25 @@
+export interface DatePickerYearSelectProps {
+    dataTestid: string;
+}
+/**
+ * The year half of the design's "Month and Year Selector" header. Goes in
+ * `OxDatePickerHeader`'s `children`, beside `OxDatePickerMonthSelect`. Mirrors
+ * `@sesame/orxata-core` DatePickerYearSelect.
+ *
+ * This is what replaced the header's year arrows. Stepping a year at a time is
+ * no way to reach a birth year, and it was the arrows' only justification; a
+ * list says where it is going and gets there in one move.
+ *
+ * **Which years it offers.** Exactly the ones `constraints` allows, when there
+ * are constraints — that is the only statement about reachable dates this
+ * package will believe. With none, there is no bound to read and any window is
+ * a guess, so it takes the documented default in `month.ts`: deep enough behind
+ * the visible year to hold a date of birth, shallow enough ahead to stay a
+ * list. A caller who wants another window passes `constraints`.
+ *
+ * No `aria-label`, for the reason `OxDatePickerMonthSelect` gives.
+ */
+export declare const DatePickerYearSelect: {
+    ({ dataTestid, }: DatePickerYearSelectProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/Forms/Inputs/DatePicker/DateRangePicker.d.ts

@@ -0,0 +1,61 @@
+import { CalendarDayState } from '../Calendar/CalendarDay.tsx';
+import { CalendarDateRange } from '../Calendar/CalendarRange.tsx';
+import { CalendarConstraints } from '../Calendar/constraints.ts';
+/**
+ * A field that shows the chosen span and opens a range calendar to change it.
+ * Mirrors `@sesame/orxata-core` DateRangePicker.
+ *
+ * A sibling of `OxDatePicker` with its own API, the same way `OxCalendarRange`
+ * is a sibling of `OxCalendar` — not a mode of it.
+ *
+ * Two months by default, because a span usually crosses one. The trigger shows
+ * the span collapsed the way the locale collapses one (`12–15 mar 2026`), from
+ * `Intl.DateTimeFormat.formatRange` where the runtime has it.
+ *
+ * There is an `aside` render prop beside the grids and nothing in it. Presets
+ * are the obvious thing to put there, and they are entirely the caller's: the
+ * design system ships no list, no exported constant of one, and no function
+ * that knows what "this week" means. It lays the column out and hands over
+ * `select`, which sets the span and closes the popover — whether the column
+ * holds shortcuts, a legend or a summary is not this component's business.
+ */
+export interface DateRangePickerProps extends Pick<React.ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
+    /** The chosen span. Either end may be absent while one is being picked. */
+    value?: CalendarDateRange;
+    /** The initially chosen span, for the uncontrolled case. */
+    defaultValue?: CalendarDateRange;
+    onValueChange?: (value: CalendarDateRange) => void;
+    /** How many month grids the popover shows. */
+    months?: number;
+    /** What can be picked, and where navigation stops. Passed straight through. */
+    constraints?: CalendarConstraints;
+    disabled?: boolean;
+    /**
+     * What the trigger shows. Falls back to the span from `Intl`, and to nothing
+     * while neither end is chosen — pass one to put a placeholder there.
+     */
+    children?: (state: {
+        value: CalendarDateRange | undefined;
+    }) => React.ReactNode;
+    /** The trailing glyph. Falls back to a calendar. */
+    icon?: React.ReactNode;
+    /**
+     * A column beside the grids. Receives `select`, which sets the span and
+     * closes the popover in one call — so whatever goes in here behaves like a
+     * second click. Not called until you pass one, and the column is not drawn at
+     * all until then.
+     */
+    aside?: (state: {
+        select: (value: CalendarDateRange) => void;
+    }) => React.ReactNode;
+    /** One day in the grid. Handed to `OxCalendarRange` untouched. */
+    day?: (props: {
+        date: Date;
+        state: CalendarDayState;
+    }) => React.ReactNode;
+    dataTestid: string;
+}
+export declare const DateRangePicker: {
+    ({ className, value, defaultValue, onValueChange, months, constraints, disabled, children, icon, aside, day, dataTestid, }: DateRangePickerProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/Forms/Inputs/DatePicker/format.d.ts

@@ -0,0 +1,44 @@
+/**
+ * How a picker writes a date down.
+ *
+ * Everything here goes through `Intl` and the tag `LocaleProvider` publishes,
+ * so the design system ships no strings: the only characters it contributes are
+ * the separator a runtime too old for `formatRange` never gets from CLDR.
+ * Internal — none of it is exported from the package, because a caller who
+ * wants a different format fills the trigger slot with their own.
+ */
+/** One day, in the locale's medium form — `12 mar 2026`, `Mar 12, 2026`. */
+export declare const formatDay: (locale: string, date: Date) => string;
+/**
+ * A span, collapsed the way the locale collapses one: `12–15 mar 2026` rather
+ * than the two ends spelled out in full.
+ *
+ * A half-made span is the start alone. It is not an error state — it is the
+ * moment between the two clicks, and `CalendarDateRange` makes both ends
+ * optional precisely so it can be shown.
+ */
+export declare const formatDayRange: (locale: string, start: Date | undefined, end: Date | undefined) => string;
+/**
+ * The month a header names, and what its navigation announces.
+ *
+ * Capitalisation is left to CSS: `Intl` lowercases the month in Spanish and
+ * capitalises it in English, and uppercasing it here would be the design system
+ * overruling the locale in the one place it has no business doing so.
+ */
+export declare const formatMonthYear: (locale: string, month: Date) => string;
+/**
+ * The months on screen when there is more than one of them — `March – April
+ * 2026`, with the year said once where the locale says it once.
+ */
+export declare const formatMonthYearRange: (locale: string, first: Date, last: Date) => string;
+/** The year alone, for the year selector's options and its current value. */
+export declare const formatYear: (locale: string, month: Date) => string;
+/**
+ * The month alone and abbreviated — `Jan`, `ene`, `1月` — which is what the
+ * month selector shows and what the design draws in it.
+ *
+ * `Intl` and not a table of our own, for the reason `Calendar` spells out: the
+ * names belong to the runtime's locale, not to a translation this package would
+ * have to carry.
+ */
+export declare const formatMonthShort: (locale: string, month: Date) => string;

package/dist/Forms/Inputs/DatePicker/index.d.ts

@@ -0,0 +1,6 @@
+export { DatePicker, type DatePickerProps } from './DatePicker.tsx';
+export { DateRangePicker, type DateRangePickerProps, } from './DateRangePicker.tsx';
+export { DatePickerTrigger, type DatePickerTriggerProps, } from './DatePickerTrigger.tsx';
+export { DatePickerHeader, type DatePickerHeaderProps, } from './DatePickerHeader.tsx';
+export { DatePickerMonthSelect, type DatePickerMonthSelectProps, } from './DatePickerMonthSelect.tsx';
+export { DatePickerYearSelect, type DatePickerYearSelectProps, } from './DatePickerYearSelect.tsx';