@allxsmith/bestax-bulma 5.26.5 → 5.27.0

package/dist/types/form/_pickerInternals/useSegmentedEntry.d.ts

@@ -37,19 +37,28 @@ export interface UseSegmentedEntryParams {
      * every manual-entry commit; return true to reject the candidate value.
      */
     isBlocked?: (d: Date) => boolean;
+    /**
+     * Rejects a candidate only while the digits typed into its segment leave
+     * it unfinished, such as the first digits of a year. The digit stays in
+     * the segment and the next one tries again, so a value passing through a
+     * candidate it can't commit on the way to one it can costs nothing. A
+     * finished segment, an arrow step and parsed text answer to `isBlocked`
+     * alone.
+     */
+    isUnfinishedBlocked?: (d: Date) => boolean;
     disabled?: boolean;
     readOnly?: boolean;
     /** Allow segmented typing. When false, segment mode never engages. */
     editable?: boolean;
-    /** Whether a popover exists; gates open-on-focus / click / ArrowDown. */
+    /** Whether a popover exists; gates open-on-focus / click / Alt+ArrowDown. */
     popover?: boolean;
     openOnFocus?: boolean;
     closeOnSelect?: boolean;
     isOpen: boolean;
     /**
      * The host's open-state setter. The hook asks it to open on focus, click
-     * or ArrowDown, but not on the focus the popover's focus trap hands back
-     * to the input as it closes, which is not the user arriving.
+     * or Alt+ArrowDown, but not on the focus the popover's focus trap hands
+     * back to the input as it closes, which is not the user arriving.
      */
     setOpen: (next: boolean) => void;
     inputRef: React.RefObject<HTMLInputElement | null>;

package/dist/types/helpers/statusRegion.d.ts

@@ -13,6 +13,7 @@ export declare const announceDelay = 100;
  * again.
  */
 export declare const announcementLifetime = 1000;
+export declare const visuallyHidden: React.CSSProperties;
 /**
  * Reads an element out roughly the way a screen reader would: its text, with
  * an element's `aria-label`, or an image's `alt`, standing in for what's

package/dist/types/index.d.ts

@@ -98,6 +98,10 @@ export { DateTimeInputBase } from './form/DateTimeInputBase.js';
 export type { DateTimeInputBaseProps } from './form/DateTimeInputBase.js';
 export { DateTimeInput } from './form/DateTimeInput.js';
 export type { DateTimeInputProps } from './form/DateTimeInput.js';
+export { DateRangeInputBase } from './form/DateRangeInputBase.js';
+export type { DateRangeInputBaseProps, DateRangeValue, } from './form/DateRangeInputBase.js';
+export { DateRangeInput } from './form/DateRangeInput.js';
+export type { DateRangeInputProps } from './form/DateRangeInput.js';
 export { useInsideField, useInsideControl } from './form/FormContext.js';
 export type { FormFieldProps } from './form/fieldProps.js';
 export * from './grid/Cell.js';

package/dist/types-cjs/components/Tabs.d.ts

@@ -31,11 +31,22 @@ export interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'o
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white';
     /** Controlled active tab index. */
     value?: number;
-    /** Callback when active tab changes. */
+    /**
+     * Callback when active tab changes. Called with the tab's `index` when a
+     * `Tabs.Tab` is activated: clicked, or Enter or Space pressed on it.
+     * Moving focus with the arrow keys, Home or End does not call it, because
+     * activation is manual: focus moves freely and the selected tab changes
+     * only when the user picks one.
+     */
     onChange?: (index: number) => void;
     /** Initial active tab index (uncontrolled). */
     defaultValue?: number;
-    /** Renders tabs vertically. */
+    /**
+     * Renders tabs vertically. With a `Tabs.Content`, the tab list is also
+     * marked `aria-orientation="vertical"` and ArrowUp and ArrowDown move focus
+     * between tabs, alongside ArrowLeft and ArrowRight (the layout stacks
+     * horizontally on mobile).
+     */
     vertical?: boolean;
     /** Side placement when `vertical` is true. */
     side?: 'left' | 'right';
@@ -66,11 +77,18 @@ export declare const TabList: React.FC<TabListProps>;
 type IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
 /**
  * Props for the Tab component.
+ * @extraProp {string} [id] - The tab's id, which its panel names in `aria-labelledby`. Generated inside a `Tabs` when omitted; a passed `id` is used and the panel follows it.
+ * @extraProp {React.KeyboardEventHandler<HTMLLIElement>} [onKeyDown] - Called before the tab handles the key; call `event.preventDefault()` to stop the tab handling it.
  */
 export interface TabProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, 'onClick'> {
     /** **Required.** Tab index for matching with content. */
     index: number;
-    /** Disables the tab. */
+    /**
+     * Disables the tab. A disabled tab is marked `aria-disabled`, cannot be
+     * activated, is skipped by the arrow keys, Home and End, and never holds
+     * the tab list's tab stop. The bestax extras styles also dim it and turn
+     * off its hover.
+     */
     disabled?: boolean;
     /** Icon name for the tab. */
     icon?: string;
@@ -90,6 +108,8 @@ export interface TabProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, 'o
 /**
  * Individual tab button. Consumes Tabs context for active state management.
  * Renders `<a>` internally — consumers provide only the label text/children.
+ * Inside a `Tabs` it takes part in the tab list's keyboard support and links
+ * to the `Tabs.Content.Item` with the same `index`.
  *
  * @function
  * @param {TabProps} props - Props for the Tab component.
@@ -129,6 +149,8 @@ export interface TabsContentProps extends React.HTMLAttributes<HTMLDivElement> {
 }
 /**
  * Props for the TabContentItem component.
+ * @extraProp {string} [id] - The panel's id, which its tab names in `aria-controls`. Generated inside a `Tabs` when omitted; a passed `id` is used and the tab follows it.
+ * @extraProp {number} [tabIndex] - The panel is not focusable by default. Pass `0` when it holds nothing focusable, so Tab moves from the tab list into it.
  */
 export interface TabContentItemProps extends React.HTMLAttributes<HTMLDivElement> {
     /** **Required.** Tab index for matching with content. */

package/dist/types-cjs/form/DateInputBase.d.ts

@@ -11,7 +11,10 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     value?: Date | null;
     /** Initial date for uncontrolled usage. */
     defaultValue?: Date | null;
-    /** Fired when the value changes. */
+    /**
+     * Fired when the value changes. A day picked in the calendar, by click or
+     * by key, arrives at local midnight.
+     */
     onChange?: (d: Date | null) => void;
     /** Fired when the popover opens. */
     onOpen?: () => void;
@@ -87,7 +90,7 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
      * Open the popover when the input is focused. Focus that a closing popover
      * hands back to the input leaves it closed. Dismissing it commits nothing:
      * an empty field stays empty, and leaving afterwards commits only what was
-     * typed since.
+     * typed since. With it off, the launcher or Alt+ArrowDown opens it.
      */
     openOnFocus?: boolean;
     /** Close the popover after a date is selected. */

package/dist/types-cjs/form/DateRangeInput.d.ts

@@ -0,0 +1,91 @@
+import React from 'react';
+import { FieldProps } from './Field.js';
+import { ControlBaseProps } from './Control.js';
+import { DateRangeInputBaseProps } from './DateRangeInputBase.js';
+/**
+ * Props for the DateRangeInput convenience wrapper. Extends
+ * `DateRangeInputBaseProps` with Field-level (label, horizontal) and
+ * Control-level (icons, loading) props. Inside an existing `Control` it
+ * renders no `Control` of its own, so its Control-level props do nothing
+ * there and warn in development; set them on that `Control` instead. In
+ * `inline` mode it renders no `Control` anywhere, so they do nothing inside a
+ * `Control` or out, and warn in development there too. Inside an outer
+ * `Field`, or a `Control` with no `Field` around it, it renders no `Field` of
+ * its own either. The exception is
+ * `label`, `message`, `horizontal` or `fieldClassName` in that bare
+ * `Control`: it keeps a `Field` for them, nested in the `.control`, and warns
+ * in development. Wrap the `Control` in a `Field` instead.
+ * @extraProp {string} [className] - Additional CSS classes for the root, the `role="group"` that holds the two inputs.
+ * @extraProp {React.Ref<HTMLInputElement>} [ref] - Forwarded to the start `<input>`.
+ */
+export interface DateRangeInputProps extends DateRangeInputBaseProps {
+    /** Field label naming the whole range. Associated through `aria-labelledby` on the `role="group"` root, since it names two inputs rather than one; uses your `labelProps.id` when provided, otherwise a generated one. Each input keeps its own name, "Start date" or "End date" (`labels.rangeStart` / `labels.rangeEnd`). Dropped inside an outer `Field`. */
+    label?: React.ReactNode;
+    /** Size for the label. */
+    labelSize?: FieldProps['labelSize'];
+    /** Props for the label element. An `htmlFor` here is dropped, since the label names the group rather than one input. */
+    labelProps?: FieldProps['labelProps'];
+    /** Render the field with horizontal layout. */
+    horizontal?: boolean;
+    /**
+     * Icon props for the left icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the field in its own addon `Control` instead.
+     */
+    iconLeft?: ControlBaseProps['iconLeft'];
+    /**
+     * Icon props for the right icon.
+     * Bulma gives control icons `pointer-events: none`, so a clickable node here
+     * never receives a click. Put a button beside the field in its own addon `Control` instead.
+     */
+    iconRight?: ControlBaseProps['iconRight'];
+    /** Shortcut for the right icon name. */
+    iconRightName?: string;
+    /** Shortcut for left icon size. */
+    iconLeftSize?: ControlBaseProps['iconLeftSize'];
+    /** Shortcut for right icon size. */
+    iconRightSize?: ControlBaseProps['iconRightSize'];
+    /** Force the left icon container. */
+    hasIconsLeft?: boolean;
+    /** Force the right icon container. */
+    hasIconsRight?: boolean;
+    /**
+     * Shows a loading spinner on the `Control` it renders, and hides the
+     * launcher (`triggerIcon`) while it does. Inside your own `Control` it
+     * renders none, so this draws nothing and warns in development; set
+     * `isLoading` on that `Control`.
+     */
+    isLoading?: boolean;
+    /**
+     * Show a clickable launcher button on the right that toggles the popover.
+     * Hidden by default while a spinner shows at the same right edge: this
+     * component's `isLoading` when it renders its own `Control`, or the
+     * enclosing `Control`'s `isLoading` inside one.
+     * @defaultValue true
+     */
+    triggerIcon?: boolean;
+    /** Expand the control to fill its container. */
+    isExpanded?: boolean;
+    /** Size of the wrapping Control. */
+    controlSize?: ControlBaseProps['size'];
+    /** Help/validation text below the field. */
+    message?: React.ReactNode;
+    /** Color modifier for the help message. */
+    messageColor?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+    /** Additional CSS classes for the Field wrapper. */
+    fieldClassName?: string;
+    /** Additional CSS classes for the Control wrapper. */
+    controlClassName?: string;
+}
+/**
+ * The `DateRangeInput` component is a form input for a start and end date, picked from one popover calendar or typed into two segmented inputs.
+ *
+ * @function
+ * @param {DateRangeInputProps} props - Props for the DateRangeInput.
+ * @returns {JSX.Element}
+ *
+ * @example
+ * <DateRangeInput label="Stay" name="stay" min={new Date()} />
+ */
+export declare const DateRangeInput: React.ForwardRefExoticComponent<DateRangeInputProps & React.RefAttributes<HTMLInputElement>>;
+export default DateRangeInput;

package/dist/types-cjs/form/DateRangeInputBase.d.ts

@@ -0,0 +1,172 @@
+import React from 'react';
+import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
+import { DateRangeValue, DayOfWeek, PickerLabels, PickerPosition } from './_pickerInternals/pickerTypes.js';
+import { DateFormatOption } from './_pickerInternals/formatters.js';
+export type { DateRangeValue };
+/**
+ * Props for the raw DateRangeInput base. Use the higher-level
+ * `DateRangeInput` for Field/Control composition; `DateRangeInputBase` is the
+ * two inputs and the popover only.
+ */
+export interface DateRangeInputBaseProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange' | 'color' | 'placeholder' | 'popover'>, Omit<BulmaClassesProps, 'color'> {
+    /**
+     * Controlled range, start first. Either end may be `null`, and
+     * `[null, null]` is empty.
+     */
+    value?: DateRangeValue;
+    /** Initial range for uncontrolled usage. */
+    defaultValue?: DateRangeValue;
+    /**
+     * Fired when the range changes, with the start first. Typing commits one
+     * end at a time, so a range half typed arrives as `[start, null]`. The
+     * calendar commits only a finished range: its first pick marks the start
+     * inside the calendar and its second commits both ends in one call. The
+     * range stays ordered, so the end is never before the start.
+     */
+    onChange?: (range: DateRangeValue) => void;
+    /** Fired when the popover opens. */
+    onOpen?: () => void;
+    /** Fired when the popover closes. */
+    onClose?: () => void;
+    /**
+     * Earliest selectable date, for either end. A `min` before year 1 is raised
+     * to 1 January of year 1, where the range starts without one too.
+     */
+    min?: Date;
+    /** Latest selectable date, for either end. */
+    max?: Date;
+    /** Disable both inputs and the launcher. */
+    disabled?: boolean;
+    /** Make both inputs read-only and keep the popover closed. */
+    readOnly?: boolean;
+    /** Placeholder text, shown in both inputs while they are empty. */
+    placeholder?: string;
+    /**
+     * Token format string or `Intl.DateTimeFormat` options, used by both
+     * inputs.
+     * @defaultValue 'YYYY-MM-DD'
+     */
+    format?: DateFormatOption;
+    /**
+     * Custom parser (use when `format` is `Intl.DateTimeFormatOptions`).
+     * Enter and leaving an input call it only if the user changed its text.
+     */
+    parse?: (s: string) => Date | null;
+    /** BCP-47 locale tag for day/month names and Intl formatting. */
+    locale?: string;
+    /**
+     * Render the calendar inline, with no inputs and no popover. The hidden
+     * form inputs still carry the range.
+     */
+    inline?: boolean;
+    /**
+     * Use two native `<input type="date">`s on coarse-pointer, small-viewport
+     * devices (`'auto'`), always (`true`) or never (`false`). The end input's
+     * `min` follows the start, and a change goes through the same rules as
+     * typing.
+     */
+    mobileNative?: boolean | 'auto';
+    /** Allow segmented keyboard typing in both inputs. `false` makes the field picker-only. */
+    editable?: boolean;
+    /** Whether the calendar popover exists. `false` makes the field input-only. */
+    popover?: boolean;
+    /**
+     * Open the popover when focus arrives in the field. Moving focus between
+     * the two inputs, or back from the launcher, leaves it closed, and so does
+     * the focus a closing popover hands back. A click on either input opens it.
+     * With it off, the launcher or Alt+ArrowDown opens it.
+     */
+    openOnFocus?: boolean;
+    /**
+     * Close the popover once the range is picked. The first pick, which only
+     * marks the start, never closes it.
+     */
+    closeOnSelect?: boolean;
+    /** Popover anchor position relative to the field. */
+    position?: PickerPosition;
+    /** Render the popover into `document.body` via portal. */
+    appendToBody?: boolean;
+    /**
+     * Bulma color modifier for the field, also carried by the calendar, where it
+     * colors the range's ends and the band between them.
+     */
+    color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+    /** Size variant. */
+    size?: 'small' | 'medium' | 'large';
+    /** Render the field with rounded corners. */
+    isRounded?: boolean;
+    /**
+     * Predicate to disable specific dates (e.g. weekends). A disabled day can
+     * be neither end, typing rejects it, and a range can't include one unless
+     * `allowDisabledInRange` is set.
+     */
+    shouldDisableDate?: (d: Date) => boolean;
+    /** Convenience array of disabled dates; merged with `shouldDisableDate`. Matched by calendar day. */
+    unselectableDates?: Date[];
+    /**
+     * Let a range include days that `shouldDisableDate` or `unselectableDates`
+     * disable, such as a stay over a night with no check-ins. Its ends still
+     * can't be such days. Off, a pick in the calendar past a disabled day
+     * starts a new range there, typing refuses an end past one, and a start
+     * typed with one before the end clears the end. Finding one walks the days
+     * between, so off, a span too long to walk is refused as well.
+     */
+    allowDisabledInRange?: boolean;
+    /** Day the week starts on (0 = Sunday). */
+    firstDayOfWeek?: DayOfWeek;
+    /** Override the 7 day-name labels (in calendar order, post-rotation). */
+    dayNames?: string[];
+    /** Override the 12 month-name labels. */
+    monthNames?: string[];
+    /** Show dimmed dates from adjacent months in the grid. */
+    nearbyMonthDays?: boolean;
+    /** Decorative left icon glyph for the wrapping `Control` (shown by default). Set `''` to hide. */
+    iconLeftName?: string;
+    /**
+     * Show a clickable launcher button on the right that toggles the popover.
+     * Hidden by default while a `Control` it sits in shows its `isLoading`
+     * spinner, which shares that right edge.
+     * @defaultValue true
+     */
+    triggerIcon?: boolean;
+    /** Glyph for the right launcher button. */
+    triggerIconName?: string;
+    /**
+     * Optional translatable string overrides. `rangeStart` and `rangeEnd` name
+     * the two inputs and the range's ends in the calendar, `rangePreviewEnd`
+     * describes the day a pending range would end on, `rangeSeparator` sits
+     * between the inputs, and `chooseDateRange` names the launcher and the
+     * popover.
+     */
+    labels?: PickerLabels;
+    /**
+     * Form field name. Two hidden inputs submit the range as `YYYY-MM-DD`,
+     * named `name[start]` and `name[end]`, in every mode. The visible inputs
+     * carry no name.
+     */
+    name?: string;
+    /** Name of the hidden input carrying the start, in place of `name[start]`. */
+    startName?: string;
+    /** Name of the hidden input carrying the end, in place of `name[end]`. */
+    endName?: string;
+    /** Form id the hidden inputs belong to. */
+    form?: string;
+    /**
+     * Mark both visible inputs required, so a form won't submit with either
+     * end empty. An `inline` calendar has no visible input, so it is not
+     * checked there.
+     */
+    required?: boolean;
+    /** Id of the start input. The end input takes `${id}-end`. */
+    id?: string;
+}
+/**
+ * Raw DateRangeInput: the two inputs and the popover calendar without
+ * Field/Control wrapping. Use `DateRangeInput` for the convenience wrapper.
+ *
+ * @function
+ * @param {DateRangeInputBaseProps} props
+ * @returns {JSX.Element}
+ */
+export declare const DateRangeInputBase: React.ForwardRefExoticComponent<DateRangeInputBaseProps & React.RefAttributes<HTMLInputElement>>;
+export default DateRangeInputBase;

package/dist/types-cjs/form/DateTimeInputBase.d.ts

@@ -12,7 +12,12 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
     value?: Date | null;
     /** Initial value for uncontrolled usage. */
     defaultValue?: Date | null;
-    /** Fired when either the date or time portion changes. */
+    /**
+     * Fired when either the date or time portion changes. Picking a day keeps
+     * the value's whole time of day, down to seconds and milliseconds the field
+     * doesn't show, and `min` and `max` judge the picked day at that time. An
+     * empty field's day is picked at midnight.
+     */
     onChange?: (d: Date | null) => void;
     /** Fired when the popover opens. */
     onOpen?: () => void;
@@ -58,7 +63,7 @@ export interface DateTimeInputBaseProps extends Omit<React.InputHTMLAttributes<H
      * Open the popover on focus. Default `true`. Focus that a closing popover
      * hands back to the input leaves it closed. Dismissing it commits nothing:
      * an empty field stays empty, and leaving afterwards commits only what was
-     * typed since.
+     * typed since. With it off, the launcher or Alt+ArrowDown opens it.
      */
     openOnFocus?: boolean;
     /** Off by default — users typically tweak both halves before committing. */

package/dist/types-cjs/form/File.d.ts

@@ -31,7 +31,12 @@ export interface FileProps extends Omit<React.InputHTMLAttributes<HTMLInputEleme
     isRight?: boolean;
     /** Center the file input within its container. */
     isCentered?: boolean;
-    /** Show a file name indicator. */
+    /**
+     * Show a file name area. Without `fileName` it shows what the user picked: the file's name, or
+     * a count when `multiple` lets them pick several (see `pickedFilesLabel`). Before a pick there is
+     * no name area. A reset of the input's form clears the name, but clearing the input from code
+     * fires no change event and leaves it showing, so pass `fileName` to control the text then.
+     */
     hasName?: boolean;
     /** Text on the file CTA button (defaults to "Choose a file…"). */
     buttonLabel?: React.ReactNode;
@@ -50,8 +55,16 @@ export interface FileProps extends Omit<React.InputHTMLAttributes<HTMLInputEleme
     className?: string;
     /** Additional CSS classes for the `<input>`. */
     inputClassName?: string;
-    /** File name to display. */
+    /**
+     * Text for the file name area (with `hasName`), for a file chosen earlier or your own wording.
+     * Setting it takes over from the picked file's name; an empty string shows no name area.
+     */
     fileName?: string;
+    /**
+     * Builds the text `hasName` shows when several files are picked, from their count, for
+     * localization. Default: `` `${count} files` ``. A single pick shows its file's name.
+     */
+    pickedFilesLabel?: (count: number) => string;
 }
 /**
  * The `File` component provides a Bulma-styled file input, supporting color, size, boxed/fullwidth/align styles, icons, "has name", and filename display.

package/dist/types-cjs/form/FormContext.d.ts

@@ -76,6 +76,13 @@ interface OwnControlOptions extends ControlLevelProps {
     insideControl: boolean;
     /** A picker's `inline`, which renders no `Control` inside one or out. */
     inline?: boolean;
+    /**
+     * The left glyph the wrapper's own `Control` shows when the caller sets no
+     * `iconLeftName`; read only then. `bare-control.test.tsx` reads that glyph
+     * from what each wrapper hands its own `Control`, so a wrapper that gains
+     * one fails there until it passes it here.
+     */
+    defaultIconLeftName?: string;
 }
 /**
  * Whether a convenience form wrapper renders a `Control` of its own (#921):
@@ -87,6 +94,10 @@ interface OwnControlOptions extends ControlLevelProps {
  * only the props it hands its own `Control`, as the caller gave them, so a
  * default the wrapper fills in itself never warns. A prop counts when it is
  * truthy, since a falsy one would change nothing on a `Control` either.
+ * `iconLeftSize` and `hasIconsLeft` show nothing on a `Control` without a
+ * glyph, so when they move and the caller chose no left icon, the advice
+ * names the wrapper's default glyph too, and following it draws what the
+ * wrapper's own `Control` did.
  * Internal; not part of the public API.
  */
 export declare const rendersOwnControl: (component: string, options: OwnControlOptions) => boolean;

package/dist/types-cjs/form/Numberinput.d.ts

@@ -45,7 +45,14 @@ export interface NumberinputProps extends Omit<React.InputHTMLAttributes<HTMLInp
     controlsRounded?: boolean;
     /** Uses compact button spacing. */
     compact?: boolean;
-    /** Removes button borders and background. */
+    /**
+     * Renders the plusminus controls without a `.field` row of their own, so
+     * they join the row of a `Field` with `hasAddons` or `grouped` they sit
+     * in. On by default inside a `Field`, unless a `Control` is anywhere above
+     * it: a `Control` stacks its children, so there the controls keep their
+     * own row.
+     * @defaultValue auto
+     */
     bare?: boolean;
     /** Style variant for the control buttons. */
     variant?: NumberinputVariant;

package/dist/types-cjs/form/TimeInputBase.d.ts

@@ -56,7 +56,7 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
      * Open the popover when the input is focused. Focus that a closing popover
      * hands back to the input leaves it closed. Dismissing it commits nothing:
      * an empty field stays empty, and leaving afterwards commits only what was
-     * typed since.
+     * typed since. With it off, the launcher or Alt+ArrowDown opens it.
      */
     openOnFocus?: boolean;
     /** Close the popover after a time is selected (off by default). */

package/dist/types-cjs/form/_pickerInternals/Calendar.d.ts

@@ -1,9 +1,8 @@
 import React from 'react';
-import { DateGranularity, DayOfWeek, PickerLabels } from './pickerTypes.js';
-export interface CalendarProps {
-    value: Date | null;
+import { DateGranularity, DateRangeValue, DayOfWeek, PickerLabels } from './pickerTypes.js';
+/** What every calendar takes, whichever way it picks. */
+interface CalendarBaseProps {
     focusedDate: Date;
-    onSelect: (d: Date) => void;
     onFocusedDateChange: (d: Date) => void;
     /**
      * Earliest selectable date. One before year 1, or none, counts as the start
@@ -47,6 +46,48 @@ export interface CalendarProps {
      */
     granularity?: DateGranularity;
 }
+/** A calendar that picks one day, month or year. */
+interface CalendarSingleProps {
+    /** The selected date. */
+    value: Date | null;
+    /** Called with a picked date, or the first day of a picked period. */
+    onSelect: (d: Date) => void;
+    range?: never;
+    onRangeSelect?: never;
+    allowDisabledInRange?: never;
+}
+/** A calendar that picks a range of days. */
+interface CalendarRangeProps {
+    /**
+     * The committed range, start first, which turns on range mode. The day grid
+     * then picks two days: the first pick marks a start inside the calendar and
+     * commits nothing, and the second calls `onRangeSelect` with both ends. A
+     * pick that cannot end the range starts a new one instead: one before the
+     * start, or one past a disabled day unless `allowDisabledInRange` is set.
+     * While a start is pending the grid previews the range to the hovered day,
+     * or to the focused day, and hides the committed one. A range with a start
+     * and no end opens with that start pending. Escape takes back a pending pick
+     * and stops there, so a popover around the calendar stays open; a pending
+     * start that came from `range` is not a pick, and Escape goes on.
+     */
+    range: DateRangeValue;
+    /** Called with both ends once the second day is picked. */
+    onRangeSelect: (start: Date, end: Date) => void;
+    /**
+     * Let a range include days that `shouldDisableDate` or `unselectableDates`
+     * disable. Its ends can still not be such days.
+     */
+    allowDisabledInRange?: boolean;
+    /** Only the day grid picks a range. */
+    granularity?: 'day';
+    value?: never;
+    onSelect?: never;
+}
+/**
+ * The calendar picks one date through `value` and `onSelect`, or a range
+ * through `range` and `onRangeSelect`, and its props take exactly one pair.
+ */
+export type CalendarProps = CalendarBaseProps & (CalendarSingleProps | CalendarRangeProps);
 /**
  * Selects the calendar's focused cell, the one tab stop of whichever grid or
  * year list is on show, for a popover to put focus on as it opens. It runs

package/dist/types-cjs/form/_pickerInternals/PickerPopover.d.ts

@@ -10,6 +10,7 @@ export interface PickerPopoverProps {
     className?: string;
     trapFocus?: boolean;
     closeOnClickOutside?: boolean;
+    /** Close on Escape and on Alt+ArrowUp. Default `true`. */
     closeOnEscape?: boolean;
     ariaLabel?: string;
     ariaLabelledBy?: string;

package/dist/types-cjs/form/_pickerInternals/dateUtils.d.ts

@@ -60,16 +60,40 @@ export declare function isDayUnselectable(d: Date, c: DayConstraints): boolean;
  * of 3pm on a month's last day leaves that day, and so its month, selectable.
  */
 export declare function isPeriodUnselectable(d: Date, granularity: DateGranularity, c: DayConstraints): boolean;
+/**
+ * The most days {@link canCloseRange} walks between a range's ends, about
+ * eleven years. A span it would have to walk further is refused, so the check
+ * stays cheap enough to run on every pointer move over the calendar.
+ */
+export declare const RANGE_WALK_LIMIT = 4000;
+/**
+ * Whether `end` can close a range that opens on `start`: it falls on `start`'s
+ * day or later, and, unless `allowDisabled`, no day between the two is one
+ * that `shouldDisableDate` or `unselectableDates` disables. Checking that
+ * walks the days between, so with either rule set and `allowDisabled` off,
+ * an `end` more than {@link RANGE_WALK_LIMIT} days after `start` is refused.
+ * The ends' own constraints, `min` and `max` among them, are the caller's to
+ * check. Bounds can't fall between two days inside them, so they are not
+ * walked.
+ */
+export declare function canCloseRange(start: Date, end: Date, c: DayConstraints, allowDisabled?: boolean): boolean;
 export declare function addDays(d: Date, n: number): Date;
 export declare function addMonths(d: Date, n: number): Date;
 export declare function addYears(d: Date, n: number): Date;
 export declare function addHours(d: Date, n: number): Date;
 export declare function addMinutes(d: Date, n: number): Date;
 export declare function addSeconds(d: Date, n: number): Date;
+/**
+ * A copy of `d` with the given parts of its time of day set and the rest
+ * left as they are. A time started from the clock rather than from a value
+ * should pass the seconds its picker does not show, and the milliseconds,
+ * as `0`, or it keeps the ones the clock had.
+ */
 export declare function setTimeOfDay(d: Date, parts: {
     hours?: number;
     minutes?: number;
     seconds?: number;
+    milliseconds?: number;
 }): Date;
 export declare function getTimeOfDay(d: Date): {
     hours: number;

package/dist/types-cjs/form/_pickerInternals/formatters.d.ts

@@ -1,3 +1,4 @@
+import type { DateGranularity } from './pickerTypes.js';
 export type DateFormatOption = Intl.DateTimeFormatOptions | string;
 export declare const DEFAULT_DATE_FORMAT = "YYYY-MM-DD";
 export declare const DEFAULT_MONTH_FORMAT = "YYYY-MM";
@@ -8,6 +9,19 @@ export declare const DEFAULT_DATETIME_FORMAT = "YYYY-MM-DD HH:mm";
 export declare function formatDate(d: Date, fmt: DateFormatOption | undefined, locale?: string): string;
 export declare function formatTime(d: Date, fmt: DateFormatOption | undefined, locale?: string): string;
 export declare function formatDateTime(d: Date, fmt: DateFormatOption | undefined, locale?: string): string;
+/**
+ * The value as a native input and a hidden form input carry it:
+ * `YYYY-MM-DD`, `YYYY-MM` or `YYYY`, the shapes `<input type="date">` and
+ * `<input type="month">` use. The year is padded to four digits, as those
+ * inputs require and as the `YYYY` token displays it. HTML has no such shape
+ * for a year before 1, so a date then is empty, as those inputs would make it.
+ */
+export declare function toIsoValue(d: Date, granularity: DateGranularity): string;
+/**
+ * Read a native `type="date"` or `type="month"` value back into a Date. HTML
+ * allows a year of four or more digits, as `toIsoValue` writes one past 9999.
+ */
+export declare function fromIsoValue(s: string, granularity: DateGranularity): Date | null;
 /**
  * Derive the hour cycle (`'12'` or `'24'`) a display format will render, from
  * its first hour token: `h`/`hh` → 12-hour with meridiem, `H`/`HH` → 24-hour.