@allxsmith/bestax-bulma 5.26.6 → 5.27.0

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/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/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

@@ -83,10 +83,17 @@ 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.

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

@@ -1,6 +1,15 @@
 export type PickerPosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'auto';
 export type HourFormat = '12' | '24';
 export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Whether a key is Alt+ArrowDown or Alt+ArrowUp, which open and close a
+ * picker's popover. The calendar and the time wheels leave both to it rather
+ * than reading them as plain arrows.
+ */
+export declare const isPopoverToggleKey: (e: {
+    altKey: boolean;
+    key: string;
+}) => boolean;
 /** The unit a date picker selects: a day, a month or a year. */
 export type DateGranularity = 'day' | 'month' | 'year';
 /**
@@ -33,6 +42,10 @@ export interface PickerLabels {
      * the pointer or the keyboard is on, until it is picked.
      */
     rangePreviewEnd?: string;
+    /** Range picking: shown between the start and end inputs. */
+    rangeSeparator?: string;
+    /** Range picking: names the launcher and the popover. */
+    chooseDateRange?: string;
     hours?: string;
     minutes?: string;
     seconds?: string;

package/dist/types-cjs/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-cjs/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';