@eifi1/ui-kit 0.33.0 → 0.34.0

package/dist/components/date-picker.d.ts

@@ -1,138 +1,8 @@
-import * as react from 'react';
-import { ComponentPropsWithoutRef, ReactNode, RefObject } from 'react';
-import { MiniCalendarProps } from './mini-calendar.js';
-
-/**
- * What both pickers share — and, through `ComponentPropsWithoutRef<"div">`, everything a
- * `<div>` takes, so a `data-tour` anchor, a test id or an `aria-describedby` reaches the
- * field's root element instead of being dropped (audit §api-design).
- *
- * `onChange` is omitted from those attributes: the DOM event of that name carries a
- * `FormEvent`, while both pickers answer with ISO date strings. Each declares its own
- * below.
- */
-interface DatePickerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
-    /** BCP 47 tag for the trigger's date and the calendar. Falls back to
-     *  `<UiKitProvider locale>`, then to the runtime's default. */
-    locale?: string;
-    /** Embedded top-boundary label, matching the native Input/Select fields. */
-    label?: ReactNode;
-    placeholder?: string;
-    /** Inclusive ISO bounds for selectable days. */
-    min?: string;
-    max?: string;
-    /** Show an X to clear the value (emits `""`). */
-    clearable?: boolean;
-    /** Accessible name of the clear button. Wins over `datePicker.clear` from
-     *  `<UiKitProvider labels>`; kept as a prop because it predates the provider. */
-    clearLabel?: string;
-    disabled?: boolean;
-    /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */
-    invalid?: boolean;
-    /**
-     * Standing advice for the field (keksdose K4, "uniform field anatomy"), as on a
-     * {@link Select}: plain TEXT is a caption under the field, attached with
-     * `aria-describedby`; a {@link FieldHint} rides the label line (or, unlabelled, sits
-     * at the field's end, outside the box).
-     */
-    hint?: ReactNode;
-    /**
-     * What is wrong with the date, in the caller's words ("The due date is before the
-     * invoice date") — {@link Input}'s `error` (keksdose K4: DateField errors had no slot).
-     * Rendered under the field (under the whole row, with `step` / `today`), attached to
-     * the trigger with `aria-describedby` — merged with any the caller passed, after the
-     * caption — and implies `invalid`. Passing the key at all keeps the field's box while
-     * there is no message, so the trigger is never remounted as one comes and goes.
-     */
-    error?: ReactNode;
-    className?: string;
-    /** Intl options for the trigger's formatted date (default: locale short date). Win
-     *  over the provider's `formatDate`. */
-    formatOptions?: Intl.DateTimeFormatOptions;
-    /** Render the trigger's text for an ISO date yourself; wins over `formatOptions` and
-     *  over the provider's `formatDate`.
-     *  For a host whose date rendering is more than one `Intl` call can say — Keksdose
-     *  puts the weekday's name in the UI language beside digits ordered by a separate
-     *  format preference, two locales in one string. `locale` still drives the calendar.
-     *  Set that rendering once with `<UiKitProvider formatDate>` (keksdose K12) and this
-     *  is for the one field that differs. */
-    formatValue?: (iso: string) => string;
-    /** Passed through to the {@link MiniCalendar} this opens. Its month arrows are
-     *  icon-only, so their `aria-label` is the only name they have — and the package
-     *  ships English defaults, which a translating host has to be able to replace.
-     *  Usually unnecessary now: the calendar reads `miniCalendar` from the provider. */
-    calendarLabels?: MiniCalendarProps["labels"];
-    /**
-     * Make the panel's caption ("July 2026") a button that opens the year's twelve
-     * months, with ‹ › stepping a year; picking a month returns to its days. Far dates
-     * stop being a march of month arrows.
-     *
-     * kastlan is why: its service-charge period runs July to June, and with one month on
-     * screen and ‹ › the only way across, the end of the period was eleven clicks past
-     * the start — so kastlan kept two date fields instead of `RhfDateRangePicker`. With
-     * the jump the whole period is open, caption, Jul, 1, caption, next year, Jun, 30.
-     *
-     * What it adds, for the keyboard and a screen reader:
-     *  - the caption is a disclosure button (`aria-expanded`). Its name is the month it
-     *    shows, so speech input can say what it sees; it is `aria-live`, as the
-     *    calendar's caption was, so paging months still says where you landed; and it is
-     *    described by `monthPicker.panel` ("Choose a month").
-     *  - the month grid is `MonthPicker`'s grid: one tab stop, arrows walk the months
-     *    (across the year's edge), Home/End the row, PageUp/PageDown a year, Enter or a
-     *    click picks. Focus opens on the month on show and comes back on its days — the
-     *    selected day if it is in that month, else the 1st. Months outside `min`/`max`
-     *    are `aria-disabled`, and a year arrow is once the whole year beyond is.
-     *  - Escape in the month grid goes back to the days without closing the panel (focus
-     *    on the caption); in the days, Escape closes the panel as before.
-     *
-     * No new strings: the month arrows keep `miniCalendar.previousMonth` / `nextMonth`
-     * (`calendarLabels`), and the month grid speaks with `MonthPicker`'s words —
-     * `monthPicker.previousYear` / `nextYear` / `month` / `panel` — because it is that
-     * grid, and a host that translated it once should not have to again.
-     *
-     * Off by default: the caption becomes one more stop in the panel's tab order, which a
-     * 0.x minor does not spring on a form. Works in the popover and in
-     * `DateRangePicker`'s phone sheet alike, beside presets and in `commit="apply"`
-     * (a preset picked while the months are open goes back to the days, on its start).
-     *
-     * Why not a two-month panel (`months={2}`) instead, or beside it: for a twelve-month
-     * period it still pages six times where this takes one year step, and two
-     * `MiniCalendar`s side by side each follow the value on their own — picking the end
-     * in the right-hand month would pull the left one onto it — so the calendar would
-     * have to learn to share a month first. Not worth that for a saving of one arrow on a
-     * range across a single month boundary.
-     */
-    monthJump?: boolean;
-}
-/**
- * Everything the kit's own trigger button carries, handed to a custom one
- * ({@link DateRangePickerProps.renderTrigger}) to spread onto its `<button>`. Spread
- * it WHOLE: the ref is how focus comes back when the panel closes, the id pair and
- * `aria-labelledby` are the 0.5.1 naming (an external `<label htmlFor>`, a form
- * library's `aria-describedby`), and `role`/`aria-haspopup`/`aria-controls`/
- * `aria-expanded` are what tell a screen reader this opens a calendar and whether it
- * is open. `className` is the kit's field look (42px with a label, `pe-9` for the
- * glyph the field draws at its end) — merge yours after it with `cn`.
- */
-interface DateTriggerAttributes {
-    ref: RefObject<HTMLButtonElement | null>;
-    type: "button";
-    id?: string;
-    role: "combobox";
-    "aria-haspopup": "dialog";
-    "aria-controls": string;
-    "aria-expanded": boolean;
-    "aria-labelledby"?: string;
-    "aria-label"?: string;
-    "aria-describedby"?: string;
-    "aria-invalid"?: true;
-    /** The field's required state — `Field required` hands it down with the id pair. */
-    "aria-required"?: boolean | "true" | "false";
-    disabled?: boolean;
-    onClick: () => void;
-    className: string;
-}
-interface DatePickerProps extends DatePickerBaseProps {
+import { type DatePickerBaseProps } from "./date-field.js";
+export type { DateTriggerAttributes } from "./date-field.js";
+export { DateRangePicker } from "./date-range-picker.js";
+export type { DateRangeCommit, DateRangeDraftSummary, DateRangePickerPreset, DateRangePickerProps, DateRangeTriggerRenderProps, } from "./date-range-picker.js";
+export interface DatePickerProps extends DatePickerBaseProps {
     /** ISO "YYYY-MM-DD", or "" for empty. */
     value: string;
     onChange: (iso: string) => void;
@@ -168,129 +38,4 @@ interface DatePickerProps extends DatePickerBaseProps {
     todayLabel?: string;
 }
 /** Single-date picker: a field showing the formatted date, opening a calendar. */
-declare function DatePicker(props: DatePickerProps): react.JSX.Element;
-interface DateRangePickerPreset {
-    /**
-     * The preset's identity, independent of its dates — `"last_3_months"`, not two ISO
-     * strings. Optional for the 0.x callers that pass anonymous pairs.
-     *
-     * keksdose's report range field (report-range-field.tsx, "Why this is app-level")
-     * is why it exists: its URL stores `?preset=last_3_months` and recomputes the dates
-     * from today on every read, so a preset that is only its dates froze "last 3 months"
-     * at whatever day the panel rendered, and two presets that happen to cover the same
-     * days (this week and today, on a Monday) could not be told apart. With an `id` the
-     * choice is reported to `onChange` and shown as selected for as long as the range
-     * still matches it. Recompute `from`/`to` on every render (`calendarMonthPresets()`,
-     * `dateRangePresets()`) and pass the key as the id.
-     */
-    id?: string;
-    label: ReactNode;
-    from: string;
-    to: string;
-}
-/**
- * When the picker hands its range to `onChange`.
- *
- *  - `"immediate"` (the default, and all of 0.7): a preset click commits and closes,
- *    and each calendar click is reported as it happens — the half-made `(from, "")`
- *    included. The right shape for quick ranges on a filter, where one click is one
- *    answer.
- *  - `"apply"`: the panel works on a DRAFT. A preset ARMS the calendar instead of
- *    committing, days can then be nudged ("last 3 months, but end it last Friday"),
- *    and nothing reaches `onChange` until Apply — which stays disabled until both ends
- *    exist. Cancel, Escape and an outside click discard the draft, and every open
- *    starts again from the committed value. keksdose's report range asked for exactly
- *    this: each commit there re-runs a whole page of charts, so an intermediate state
- *    must never escape the panel.
- */
-type DateRangeCommit = "immediate" | "apply";
-interface DateRangePickerProps extends DatePickerBaseProps {
-    from: string;
-    to: string;
-    /** The committed range. `presetId` is the chosen preset's `id` when a preset
-     *  produced it (and the range was not nudged since), `undefined` for days picked by
-     *  hand. A 0.x two-argument handler simply ignores it. */
-    onChange: (from: string, to: string, presetId?: string) => void;
-    /** Separator between the two formatted dates in the trigger (default " – "). */
-    separator?: string;
-    /** Optional named ranges rendered as a start-side column (last month / YTD / …). */
-    presets?: DateRangePickerPreset[];
-    /**
-     * The active preset's `id`, controlled — e.g. straight from keksdose's `?preset=`.
-     * `null` (or an id no preset has, such as `"custom"`) says "no preset": nothing in
-     * the column is marked even if a preset happens to cover the same days. A preset is
-     * marked only while its dates still equal `from`/`to`.
-     *
-     * Leave it `undefined` and the picker remembers the last preset it committed
-     * itself; with no memory at all it falls back to the first preset whose dates match.
-     */
-    preset?: string | null;
-    /** See {@link DateRangeCommit}. Default `"immediate"`. */
-    commit?: DateRangeCommit;
-    /**
-     * Draw the trigger yourself. keksdose's report range field
-     * (reports/report-range-field.tsx, "Why this is app-level") is why: its trigger
-     * NAMES the active preset ("Last 3 months", the window as a muted suffix) where the
-     * kit's shows two dates, sits inside a Tooltip, and is squared off on one side so the
-     * granularity control can join it flush at the field's 42px.
-     *
-     * Spread `props.triggerProps` onto a `<button>` whole and put `props.valueProps` on
-     * the element that shows the value — see {@link DateTriggerAttributes} for what each
-     * part is for. The field around it (label, hidden name twin, clear/calendar glyph,
-     * popover or phone sheet) is unchanged.
-     */
-    renderTrigger?: (props: DateRangeTriggerRenderProps) => ReactNode;
-    /**
-     * In the phone layout (`usePhoneLayout()`) the panel opens as a full-screen sheet (`FullBleedDialog`)
-     * with presets in a grid above the calendar and Apply pinned in the footer, instead
-     * of the 440px popover that hung off a 360px screen (keksdose's report range field,
-     * which hand-rolled exactly this). This is its `backCloses`: on by default, so Back
-     * dismisses the sheet; off for a caller whose commit rewrites the URL with
-     * `replaceState` in the same tick — keksdose's `?preset/from/to` — where the router
-     * would overwrite the sheet's history marker.
-     */
-    sheetBackCloses?: boolean;
-    /**
-     * With `commit="apply"`: a line above the calendar saying what Apply would commit —
-     * keksdose's report range writes "Custom · 1 Mar 2026 – …" there
-     * (report-range-field.tsx), the one place a preset armed and then nudged by a day is
-     * seen to have become "Custom", and a half-made range to still lack its end. Called
-     * with the DRAFT on every change, in the popover and the phone sheet alike; `preset`
-     * is the preset the column marks for it (none once a day was picked by hand), `to` is
-     * `""` until the second click. The line is a polite live region, so a screen reader
-     * hears the draft change as the calendar is used.
-     *
-     * Ignored in `"immediate"` mode, where there is no draft: every click is the value.
-     */
-    renderDraftSummary?: (draft: DateRangeDraftSummary) => ReactNode;
-}
-/** What {@link DateRangePickerProps.renderDraftSummary} is called with. */
-interface DateRangeDraftSummary {
-    from: string;
-    to: string;
-    /** The preset the column marks for the draft, if any. */
-    preset: DateRangePickerPreset | undefined;
-}
-/** What {@link DateRangePickerProps.renderTrigger} is called with. */
-interface DateRangeTriggerRenderProps {
-    /** Spread onto the `<button>`, whole. Merge your class after `triggerProps.className`. */
-    triggerProps: DateTriggerAttributes;
-    /** Put on the element showing the value: the trigger is named "label, value" by
-     *  reference to this id. Without it the name is the label alone. */
-    valueProps: {
-        id: string;
-    };
-    open: boolean;
-    from: string;
-    to: string;
-    /** The preset the column marks for the committed range, if any — the one to name. */
-    preset: DateRangePickerPreset | undefined;
-    /** What the kit's own trigger would show: the formatted range, or the placeholder. */
-    text: string;
-}
-/** Two-date range picker: click a start then an end; closes once both are set.
- *  With `presets`, a column of named ranges is shown beside the calendar; with
- *  `commit="apply"` the panel drafts and commits on Apply (see {@link DateRangeCommit}). */
-declare function DateRangePicker(props: DateRangePickerProps): react.JSX.Element;
-
-export { DatePicker, type DatePickerProps, type DateRangeCommit, type DateRangeDraftSummary, DateRangePicker, type DateRangePickerPreset, type DateRangePickerProps, type DateRangeTriggerRenderProps, type DateTriggerAttributes };
+export declare function DatePicker(props: DatePickerProps): import("react").JSX.Element;