@allxsmith/bestax-bulma 5.6.2 → 5.8.0

package/dist/types/form/TextAreaBase.d.ts

@@ -1,5 +1,22 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
+/**
+ * Props for the TextArea component.
+ *
+ * @property {'primary'|'link'|'info'|'success'|'warning'|'danger'|'black'|'dark'|'light'|'white'} [color] - Bulma color modifier for the textarea.
+ * @property {'small'|'medium'|'large'} [size] - Size modifier for the textarea.
+ * @property {boolean} [isRounded] - Renders the textarea with rounded corners.
+ * @property {boolean} [isStatic] - Renders the textarea as static text.
+ * @property {boolean} [isHovered] - Applies the hovered state.
+ * @property {boolean} [isFocused] - Applies the focused state.
+ * @property {boolean} [isLoading] - Shows loading indicator.
+ * @property {boolean} [isActive] - Applies Bulma's is-active modifier.
+ * @property {boolean} [hasFixedSize] - Applies Bulma's has-fixed-size modifier.
+ * @property {string} [className] - Additional CSS classes to apply.
+ * @property {boolean} [disabled] - Whether the textarea is disabled.
+ * @property {boolean} [readOnly] - Whether the textarea is read-only.
+ * @property {number} [rows] - Number of visible text lines.
+ */
 export interface TextAreaBaseProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'size'>, Omit<BulmaClassesProps, 'color'> {
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white';
     size?: 'small' | 'medium' | 'large';
@@ -15,5 +32,13 @@ export interface TextAreaBaseProps extends Omit<React.TextareaHTMLAttributes<HTM
     readOnly?: boolean;
     rows?: number;
 }
+/**
+ * Bulma TextArea component with full Bulma helper class support.
+ *
+ * @function
+ * @param {TextAreaBaseProps} props - Props for the TextAreaBase component.
+ * @returns {JSX.Element} The rendered textarea element.
+ * @see {@link https://bulma.io/documentation/form/textarea/ | Bulma Textarea documentation}
+ */
 export declare const TextAreaBase: React.ForwardRefExoticComponent<TextAreaBaseProps & React.RefAttributes<HTMLTextAreaElement>>;
 export default TextAreaBase;

package/dist/types/form/TimeInput.d.ts

@@ -2,6 +2,29 @@ import React from 'react';
 import { FieldProps } from './Field';
 import { ControlBaseProps } from './Control';
 import { TimeInputBaseProps } from './TimeInputBase';
+/**
+ * Props for the TimeInput convenience wrapper. Extends `TimeInputBaseProps`
+ * with Field-level (label, horizontal) and Control-level (icons, loading) props.
+ *
+ * @property {React.ReactNode} [label] - Field label.
+ * @property {FieldProps['labelSize']} [labelSize] - Size for the label.
+ * @property {FieldProps['labelProps']} [labelProps] - Props for the label element.
+ * @property {boolean} [horizontal] - Render the field with horizontal layout.
+ * @property {ControlBaseProps['iconLeft']} [iconLeft] - Icon props for the left icon.
+ * @property {ControlBaseProps['iconRight']} [iconRight] - Icon props for the right icon.
+ * @property {string} [iconRightName] - Shortcut for the right icon name.
+ * @property {ControlBaseProps['iconLeftSize']} [iconLeftSize] - Shortcut for left icon size.
+ * @property {ControlBaseProps['iconRightSize']} [iconRightSize] - Shortcut for right icon size.
+ * @property {boolean} [hasIconsLeft] - Force the left icon container.
+ * @property {boolean} [hasIconsRight] - Force the right icon container.
+ * @property {boolean} [isLoading] - Show a loading indicator on the control.
+ * @property {boolean} [isExpanded] - Expand the control to fill its container.
+ * @property {ControlBaseProps['size']} [controlSize] - Size of the wrapping Control.
+ * @property {React.ReactNode} [message] - Help/validation text below the input.
+ * @property {'primary'|'link'|'info'|'success'|'warning'|'danger'} [messageColor] - Message color.
+ * @property {string} [fieldClassName] - Additional CSS classes for the Field wrapper.
+ * @property {string} [controlClassName] - Additional CSS classes for the Control wrapper.
+ */
 export interface TimeInputProps extends TimeInputBaseProps {
     label?: React.ReactNode;
     labelSize?: FieldProps['labelSize'];
@@ -22,5 +45,21 @@ export interface TimeInputProps extends TimeInputBaseProps {
     fieldClassName?: string;
     controlClassName?: string;
 }
+/**
+ * TimeInput is a form input that opens a popover spinner for time-of-day
+ * selection. Supports 12h/24h, optional seconds, custom step increments,
+ * min/max bounds, an unselectable-times predicate, and a native
+ * `<input type="time">` fallback for touch devices.
+ *
+ * @function
+ * @param {TimeInputProps} props
+ * @returns {JSX.Element}
+ *
+ * @example
+ * <TimeInput label="Departure" defaultValue={new Date()} />
+ *
+ * @example
+ * <TimeInput label="Slot" hourFormat="12" incrementMinutes={15} />
+ */
 export declare const TimeInput: React.ForwardRefExoticComponent<TimeInputProps & React.RefAttributes<HTMLInputElement>>;
 export default TimeInput;

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

@@ -2,6 +2,46 @@ import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
 import { PickerPosition, HourFormat, PickerLabels } from './_pickerInternals/pickerTypes';
 import { DateFormatOption } from './_pickerInternals/formatters';
+/**
+ * Props for the raw TimeInput base. Use the higher-level `TimeInput` for
+ * Field/Control composition; `TimeInputBase` is the input + popover only.
+ *
+ * @property {Date | null} [value] - Controlled selected time.
+ * @property {Date | null} [defaultValue] - Initial value for uncontrolled usage.
+ * @property {(d: Date | null) => void} [onChange] - Fired when the value changes.
+ * @property {() => void} [onOpen] - Fired when the popover opens.
+ * @property {() => void} [onClose] - Fired when the popover closes.
+ * @property {Date} [min] - Earliest selectable time.
+ * @property {Date} [max] - Latest selectable time.
+ * @property {boolean} [disabled] - Disable the input.
+ * @property {boolean} [readOnly] - Make the input read-only.
+ * @property {string} [placeholder] - Placeholder text.
+ * @property {DateFormatOption} [format] - Token format string or `Intl.DateTimeFormat` options.
+ * @property {(s: string) => Date | null} [parse] - Custom parser.
+ * @property {string} [locale] - BCP-47 locale tag.
+ * @property {boolean} [inline] - Render the spinner inline (no popover).
+ * @property {boolean | 'auto'} [mobileNative] - Use native `<input type="time">` on coarse-pointer devices.
+ * @property {boolean} [editable] - Allow segmented keyboard typing in the input (type the time directly, auto-advancing across segments). Default `true`.
+ * @property {boolean} [popover] - Whether the spinner popover exists. `false` makes the field input-only (segmented typing with no popover). Default `true`.
+ * @property {boolean} [openOnFocus] - Open the popover on focus. Default `true`.
+ * @property {boolean} [closeOnSelect] - Close after selection. Default `false`.
+ * @property {PickerPosition} [position] - Popover anchor position.
+ * @property {boolean} [appendToBody] - Render the popover into `document.body` via portal.
+ * @property {'primary'|'link'|'info'|'success'|'warning'|'danger'} [color] - Bulma color modifier.
+ * @property {'small'|'medium'|'large'} [size] - Size variant.
+ * @property {boolean} [isRounded] - Rounded input corners.
+ * @property {HourFormat} [hourFormat] - `'12'` or `'24'`. Default `'24'`.
+ * @property {boolean} [enableSeconds] - Show a seconds column. Note: iOS Safari's native time picker has no seconds wheel; combine with `mobileNative={false}` if a seconds wheel is required on iOS.
+ * @property {number} [incrementHours] - Hour step. Default `1`.
+ * @property {number} [incrementMinutes] - Minute step. Default `1`.
+ * @property {number} [incrementSeconds] - Second step. Default `1`.
+ * @property {(d: Date) => boolean} [unselectableTimes] - Predicate for blocked times (the spinner skips ahead; manual typing rejects them).
+ * @property {string} [iconLeftName] - Decorative left icon glyph for the wrapping Control (shown by default; set to '' to hide).
+ * @property {boolean} [triggerIcon] - Show a clickable launcher button on the right that toggles the popover. Default `true`.
+ * @property {string} [triggerIconName] - Glyph name for the right launcher button. Default `'chevron-down'`.
+ * @property {boolean} [audioTick] - Play a short audible tick on each wheel-item crossing. Useful as a substitute for haptic feedback on iOS Safari, which has no web-accessible haptic API. Off by default.
+ * @property {boolean} [haptics] - Auto-route platform-appropriate tactile feedback per wheel tick: real vibration on Android (via `navigator.vibrate`) and an audible thunk on iOS (where no haptic API exists). Adds the audio thunk only when vibrate is unavailable, so Android devices aren't subjected to extra sound. The visual band pulse fires regardless. Off by default for backward compat.
+ */
 export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'onChange' | 'size' | 'color' | 'min' | 'max' | 'type' | 'popover'>, Omit<BulmaClassesProps, 'color'> {
     value?: Date | null;
     defaultValue?: Date | null;
@@ -36,9 +76,41 @@ export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     iconLeftName?: string;
     triggerIcon?: boolean;
     triggerIconName?: string;
+    /** Optional translatable string overrides. */
     labels?: PickerLabels;
+    /**
+     * Play a short audible tick on each wheel-item crossing. Provides a
+     * substitute for haptic feedback on iOS Safari, which has no web-
+     * accessible haptic API as of May 2026. Off by default to avoid
+     * surprising users with sound; the tick respects the device's silent
+     * switch and is suppressed when no audio device is available.
+     */
     audioTick?: boolean;
+    /**
+     * Auto-route platform-appropriate tactile feedback per wheel tick. When
+     * `true`:
+     *  - On platforms where `navigator.vibrate` is implemented (Android
+     *    Chrome / Firefox Android / Samsung Internet), the existing
+     *    unconditional `navigator.vibrate(5)` carries the haptic — no audio
+     *    is added (don't want to subject Android users to extra sound).
+     *  - On platforms where `navigator.vibrate` is absent (notably iOS
+     *    Safari, which has no web-accessible haptic API as of May 2026),
+     *    the audio thunk is enabled automatically — same as setting
+     *    `audioTick={true}` manually.
+     *  - The visual band pulse fires regardless (gated only by
+     *    `prefers-reduced-motion`).
+     * Off by default for backward compat. If `audioTick` is also set, the
+     * audio fires regardless of detection (manual opt-in wins).
+     */
     haptics?: boolean;
 }
+/**
+ * Raw TimeInput — input + popover spinner without Field/Control wrapping.
+ * Use `TimeInput` for the convenience wrapper.
+ *
+ * @function
+ * @param {TimeInputBaseProps} props
+ * @returns {JSX.Element}
+ */
 export declare const TimeInputBase: React.ForwardRefExoticComponent<TimeInputBaseProps & React.RefAttributes<HTMLInputElement>>;
 export default TimeInputBase;

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

@@ -18,8 +18,14 @@ export interface CalendarProps {
     size?: 'small' | 'medium' | 'large';
     className?: string;
     id?: string;
+    /** When true, focus the cell matching `focusedDate` after each render. */
     autoFocusCell?: boolean;
+    /** Optional translatable string overrides. */
     labels?: PickerLabels;
+    /**
+     * Inclusive `[min, max]` year range shown in the year-dropdown view.
+     * Defaults to ±100 years around the focused year, clamped by `min`/`max`.
+     */
     yearsRange?: [number, number];
 }
 export declare const Calendar: React.FC<CalendarProps>;

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

@@ -10,6 +10,7 @@ export interface TimeWheelsProps {
     onChange: (v: TimeWheelsValue) => void;
     hourFormat?: HourFormat;
     enableSeconds?: boolean;
+    /** Step between visible values in the wheel. Default `1`. */
     incrementHours?: number;
     incrementMinutes?: number;
     incrementSeconds?: number;
@@ -20,9 +21,21 @@ export interface TimeWheelsProps {
     className?: string;
     id?: string;
     labels?: PickerLabels;
+    /** Number of items visible at once (must be odd). Default 5. */
     visibleCount?: number;
+    /** Item height in px. Default 32. */
     itemHeight?: number;
+    /**
+     * Play a short audible tick on each item crossing. Useful as a fallback on
+     * iOS Safari, where there is no web-accessible haptic API. Off by default
+     * to avoid surprising users with sound; flip on for iOS-targeted UIs.
+     */
     audioTick?: boolean;
+    /**
+     * Fired when the user presses Enter on a wheel column. The current value is
+     * already committed (each wheel-tick calls onChange), so this typically just
+     * needs to close the surrounding popover.
+     */
     onCommit?: () => void;
 }
 export declare const TimeWheels: React.FC<TimeWheelsProps>;

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

@@ -1,3 +1,50 @@
+/**
+ * Audio-tick fallback for platforms with no haptic API. iOS Safari has no
+ * web-accessible Taptic path (see `./haptics.ts` for the full story), so the
+ * closest UX substitute is a very short audible thunk played per item tick.
+ *
+ * Sound design — tuned to read as a body-felt impact, not an ear-felt beep:
+ *
+ * - Single triangle-wave oscillator at 160Hz, exponentially sweeping down to
+ *   110Hz over ~30ms. The low fundamental matches the frequency band where
+ *   the Taptic Engine fires its UI pops (~150–200Hz); the downward sweep is
+ *   the single biggest contributor to the perception of a damped physical
+ *   impact (vs. a flat tone, which reads as a beep).
+ *
+ * - Triangle adds one odd harmonic over sine — just enough body to feel
+ *   "soft" without the buzz of square or sawtooth.
+ *
+ * - Quick 1ms attack to 0.08 gain; exponential decay to silence over ~30ms;
+ *   oscillator stops at +0.04s. Ramped envelope (no hard 0→1 jumps) avoids
+ *   the classic Web Audio speaker pop on attack/release.
+ *
+ * - Uses a single oscillator + envelope rather than an audio buffer /
+ *   decoded sample so there's no asset to ship and no `decodeAudioData`
+ *   round-trip.
+ *
+ * - iOS Safari requires a user gesture to *resume* a suspended
+ *   `AudioContext`. Call `unlockAudioTick()` from inside a touch / click
+ *   handler before the first `playAudioTick()`. After that single resume,
+ *   the context stays running and subsequent ticks play with no further
+ *   gesture needed.
+ *
+ * - Silent / Ring switch behaviour on iOS: with the side switch in silent
+ *   mode, this tick is suppressed (Web Audio respects the ringer). That
+ *   matches iOS native UX expectations — silent mode means silent UI.
+ *
+ * - On hardware with neither speakers nor an audio device, every call
+ *   silently no-ops.
+ */
+/**
+ * Call from inside a user-gesture handler (pointerdown, click, touchstart)
+ * to resume the AudioContext on iOS Safari. Idempotent and cheap; safe to
+ * call on every gesture. No-ops on platforms without Web Audio.
+ */
 export declare const unlockAudioTick: () => void;
+/**
+ * Play a single short tick. No-op if Web Audio is unavailable or the
+ * context hasn't been unlocked yet.
+ */
 export declare const playAudioTick: () => void;
+/** Test-only hook to drop the singleton AudioContext. */
 export declare const __resetAudioTickForTest: () => void;

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

@@ -30,10 +30,23 @@ export declare function getTimeOfDay(d: Date): {
     seconds: number;
 };
 export declare function clampDate(d: Date, min?: Date, max?: Date): Date;
+/**
+ * Snap a Date's time-of-day to the nearest grid defined by the given
+ * increment steps. Used by the "Now" button in pickers configured with
+ * non-1 hour / minute / second steps so the committed time always lands on
+ * a slot that exists on the wheel. Overflows roll up: e.g.
+ * 13:58 with step=15 → 14:00. Seconds are zeroed when `enableSeconds` is
+ * false, regardless of step.
+ */
 export declare function snapTimeToIncrement(d: Date, opts?: {
     incrementHours?: number;
     incrementMinutes?: number;
     incrementSeconds?: number;
     enableSeconds?: boolean;
 }): Date;
+/**
+ * Build a 6-week × 7-day grid (42 cells) anchored on the month containing
+ * `monthAnchor`. The first cell is the start of the week containing the first
+ * of the month, where the week starts on `firstDayOfWeek`.
+ */
 export declare function buildMonthGrid(monthAnchor: Date, firstDayOfWeek?: DayOfWeek): CalendarCell[];

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

@@ -6,8 +6,27 @@ 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;
+/**
+ * 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.
+ *
+ * Returns `null` when the cycle can't be read from the format — it's an
+ * `Intl.DateTimeFormat` options object (no token string), `undefined`, or has
+ * no hour token — so callers fall back to the raw `hourFormat` prop. Scans with
+ * the same {@link TOKEN_RE} grammar the input renders with, so the derived cycle
+ * always agrees with what the field actually displays.
+ */
 export declare function hourCycleFromFormat(fmt: DateFormatOption | undefined): '12' | '24' | null;
+/**
+ * Parse a date string against a token format. Returns null on mismatch.
+ * For Intl-options formats parsing is the consumer's responsibility — pass
+ * a custom `parse` prop on the picker.
+ */
 export declare function parseDate(s: string, fmt?: string, _locale?: string): Date | null;
 export declare function parseTime(s: string, fmt?: string): Date | null;
+/**
+ * Locale-aware day name labels in calendar order (Sunday → Saturday).
+ * Caller rotates by `firstDayOfWeek`.
+ */
 export declare function getDayNames(locale: string | undefined, length?: 'narrow' | 'short' | 'long'): string[];
 export declare function getMonthNames(locale: string | undefined, length?: 'short' | 'long'): string[];

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

@@ -1 +1,24 @@
+/**
+ * Tiny haptic blip used to signal each item tick on the time-wheel scroller.
+ *
+ * Implementation: feature-detect `navigator.vibrate()` and call it with a
+ * 5ms duration. Supported on Android Chrome (since v30), Firefox Android,
+ * and Samsung Internet. Silently no-ops elsewhere.
+ *
+ * iOS Safari does not expose `navigator.vibrate` and has no other web-
+ * accessible haptic API as of May 2026. We previously shipped a fallback
+ * that toggled a hidden `<input type="checkbox" switch>` element via
+ * `.click()` — that produced toggle haptics on iOS 17.4 through 26.4, but
+ * Apple patched the loophole in iOS 26.5: haptics now only fire on
+ * genuine, user-initiated taps on a visible switch, not on programmatic
+ * invocation. There is no public WebKit ticket for the patch; it's
+ * documented in the `tijnjh/ios-haptics` README and downstream community
+ * write-ups. The Web Audio "silent buffer" trick unlocks audio playback
+ * but never produced Taptic Engine output. PWAs added to the Home Screen
+ * use the same WebKit and gain no extra haptic capability.
+ *
+ * If you need haptics on iOS, the only path today is wrapping the web view
+ * in a native shell (Capacitor, react-native-webview) and bridging to
+ * `UIImpactFeedbackGenerator`. Pure web cannot do it.
+ */
 export declare const tickHaptic: () => void;

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

@@ -1,6 +1,10 @@
 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;
+/**
+ * Translatable strings used across all four pickers. Pass via the `labels`
+ * prop to override defaults; consumers manage their own locale-driven mapping.
+ */
 export interface PickerLabels {
     prevMonth?: string;
     nextMonth?: string;
@@ -23,9 +27,13 @@ export interface PickerLabels {
     clear?: string;
     cancel?: string;
     ok?: string;
+    /** Mobile footer: text link that reverts to the value at open (like iOS). */
     reset?: string;
+    /** Mobile footer: aria-label for the circular checkmark commit button. */
     done?: string;
+    /** DateTimeInput footer: label preceding the selected-time display. */
     time?: string;
 }
 export declare const DEFAULT_PICKER_LABELS: Required<PickerLabels>;
+/** Merge user-supplied label overrides with the defaults. */
 export declare const mergeLabels: (overrides?: PickerLabels) => Required<PickerLabels>;

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

@@ -1,20 +1,68 @@
+/**
+ * Segment-map utility for manual keyboard entry on a date / time picker input.
+ * Given a token-format string like `'YYYY-MM-DD'`, `'HH:mm:ss'`, `'hh:mm A'`,
+ * or a combined `'YYYY-MM-DD HH:mm'`, we compute the character ranges of each
+ * editable segment in the formatted output, plus arithmetic helpers
+ * (increment / digit-set) for each kind.
+ *
+ * Variable-width tokens (`Y`, `YYY`, `M`, `D`, `H`, `h`, `m`, `s`) cause the
+ * renderer to emit output of unpredictable width depending on value, which
+ * would shift segment boundaries between renders and break the selection.
+ * `buildSegmentMap` returns `null` for any format containing those, signalling
+ * the caller to fall back to free-form text entry.
+ */
 export type SegmentKind = 'year' | 'month' | 'day' | 'hours' | 'minutes' | 'seconds' | 'ampm' | 'literal';
 export interface Segment {
     kind: SegmentKind;
+    /** Source token (e.g., `'HH'`) for editable segments; literal text for `'literal'`. */
     token: string;
+    /** Inclusive char index into the formatted-string output. */
     start: number;
+    /** Exclusive char index. */
     end: number;
+    /** Populated only when `kind === 'hours'`. */
     hourFormat?: '12' | '24';
 }
 export interface SegmentMap {
     segments: Segment[];
+    /** Indices of non-literal segments, left to right. */
     editable: number[];
 }
+/**
+ * Walk a token-format string and produce a {@link SegmentMap}, or `null` if
+ * the format contains any variable-width tokens (`H`, `h`, `m`, `s`) — the
+ * caller should treat that case as "segment mode unsupported, use the input's
+ * free-form text-entry fallback".
+ */
 export declare function buildSegmentMap(format: string): SegmentMap | null;
+/**
+ * Returns a new Date with the given segment incremented (`delta` = +1 or -1).
+ * Wraps at segment boundaries: year is unbounded, month 0↔11 (in place, no
+ * year roll), day within the current month's length, hours-24 0↔23, hours-12
+ * 1↔12, minutes/seconds 0↔59, am/pm toggles. Day is re-clamped after a
+ * month/year change (Jan 31 → Feb 28/29). `isPm` is the *current* meridiem
+ * when editing a 12h hour segment so we preserve it across the increment;
+ * date segments ignore it.
+ */
 export declare function incrementSegmentValue(segment: Segment, currentDate: Date, delta: number, isPm: boolean): Date;
+/**
+ * Apply a buffered string of typed digits to the active segment. Returns the
+ * updated Date plus an `advance` flag — `true` when the buffer is full (its
+ * token width) or when the first digit alone forecloses any valid multi-digit
+ * completion (e.g., first digit `3` for hours-24 since 30+ is out of range, or
+ * `2` for month since there is no month 20+).
+ *
+ * Special cases: a leading `'0'` is held without committing for hours-12,
+ * month, and day (00 isn't a valid display value for any of them) — the buffer
+ * must reach `'0X'` first. Month/day writes clamp to range and re-clamp the
+ * day to the month's length; year writes re-clamp the day across leap-year
+ * boundaries.
+ */
 export declare function setSegmentValue(segment: Segment, currentDate: Date, rawDigits: string, isPm: boolean): {
     date: Date;
     advance: boolean;
 };
+/** Force the meridiem of `currentDate` to AM (isPm=false) or PM (true). */
 export declare function setAmPm(currentDate: Date, isPm: boolean): Date;
+/** Map a caret position into the index of the segment that contains it. */
 export declare function segmentIndexAtCaret(map: SegmentMap, caret: number): number | null;

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

@@ -5,6 +5,7 @@ export interface NativeMobileDetect {
 }
 export interface UseNativeMobilePickerOptions {
     smallViewportMaxPx?: number;
+    /** When set, overrides detection. */
     force?: boolean;
 }
 export declare function useNativeMobilePicker(options?: UseNativeMobilePickerOptions): NativeMobileDetect;

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

@@ -2,21 +2,38 @@ import React from 'react';
 import { DateFormatOption } from './formatters';
 import { SegmentMap } from './segmentMap';
 export interface UseSegmentedEntryParams {
+    /** Resolved format actually used to render (the host's default format). */
     format: DateFormatOption;
+    /** Current canonical value (controlled or internal). */
     value: Date | null;
+    /** Commit a new Date through the host's onChange / internal pipeline. */
     commitValue: (next: Date | null) => void;
+    /** Host formatter: formatDate | formatTime | formatDateTime. */
     formatFn: (d: Date, fmt: DateFormatOption | undefined, locale?: string) => string;
+    /** Host parser used by the free-form fallback (parseDate / parseTime / custom). */
     tryParse: (s: string) => Date | null;
+    /** Host's displayed-text state and setter (the hook drives it during edits). */
     text: string;
     setText: (s: string) => void;
+    /**
+     * Seed for an empty value when the user starts typing: Time → today at noon,
+     * Date → today at 00:00, DateTime → now. Should be referentially stable.
+     */
     makeBaseDate: () => Date;
     locale?: string;
     min?: Date;
     max?: Date;
+    /**
+     * Host-supplied blocking predicate (composed from shouldDisableDate /
+     * unselectableDates / unselectableTimes). Checked alongside min/max on
+     * every manual-entry commit; return true to reject the candidate value.
+     */
     isBlocked?: (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. */
     popover?: boolean;
     openOnFocus?: boolean;
     closeOnSelect?: boolean;
@@ -32,8 +49,11 @@ export interface UseSegmentedEntryParams {
 export interface UseSegmentedEntryResult {
     segmentMap: SegmentMap | null;
     activeSegmentIdx: number | null;
+    /** True when segment typing is available (map + editable + not disabled/readOnly). */
     segmentEditable: boolean;
+    /** True when a segment is actively selected. */
     inSegmentMode: boolean;
+    /** Spread onto the combobox `<input>`. */
     inputHandlers: {
         onChange: React.ChangeEventHandler<HTMLInputElement>;
         onFocus: React.FocusEventHandler<HTMLInputElement>;
@@ -42,4 +62,14 @@ export interface UseSegmentedEntryResult {
         onBlur: React.FocusEventHandler<HTMLInputElement>;
     };
 }
+/**
+ * Segmented manual keyboard entry for a date / time picker input. Computes a
+ * segment map from the token format, tracks the active segment, and returns
+ * the full set of `<input>` event handlers — segment-mutating keys (arrows,
+ * digits, AM/PM, separators) are handled here, while popover open/close and
+ * free-form parse-on-blur/Enter are driven through the host-supplied
+ * `setOpen` / `tryParse` / `commitValue` callbacks. When the format is an
+ * `Intl` options object or contains variable-width tokens, the segment map is
+ * null and the input transparently falls back to free-form text entry.
+ */
 export declare function useSegmentedEntry(params: UseSegmentedEntryParams): UseSegmentedEntryResult;

package/dist/types/form/fieldProps.d.ts

@@ -1,12 +1,24 @@
 import React from 'react';
+/**
+ * Shared props for form components that render an optional Field wrapper.
+ * When these props are provided and the component is not already inside a Field,
+ * it will automatically render a Field around itself.
+ */
 export interface FormFieldProps {
+    /** Field label. */
     label?: React.ReactNode;
+    /** Size for the label (used in horizontal layouts). */
     labelSize?: 'small' | 'normal' | 'medium' | 'large';
+    /** Props for the label element. */
     labelProps?: React.LabelHTMLAttributes<HTMLLabelElement> & {
         [key: string]: unknown;
     };
+    /** Horizontal field layout. */
     horizontal?: boolean;
+    /** Help/validation message below the input. */
     message?: React.ReactNode;
+    /** Bulma color for the message. */
     messageColor?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+    /** Additional CSS classes for the Field wrapper. */
     fieldClassName?: string;
 }

package/dist/types/grid/Cell.d.ts

@@ -1,6 +1,24 @@
 import React from 'react';
 import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses';
+/**
+ * Type for grid cell span values.
+ */
 export type CellSpanValue = number;
+/**
+ * Props for the Cell component.
+ *
+ * @property {number} [colStart] - Which column the cell starts at (Bulma: is-col-start-x).
+ * @property {number} [colFromEnd] - Which column the cell ends at, counting from the end (Bulma: is-col-from-end-x).
+ * @property {CellSpanValue} [colSpan] - How many columns the cell will span (Bulma: is-col-span-x).
+ * @property {number} [rowStart] - Which row the cell starts at (Bulma: is-row-start-x).
+ * @property {number} [rowFromEnd] - Which row the cell ends at, counting from the end (Bulma: is-row-from-end-x).
+ * @property {CellSpanValue} [rowSpan] - How many rows the cell will span (Bulma: is-row-span-x).
+ * @property {string} [className] - Additional CSS class names.
+ * @property {(typeof validColors)[number] | 'inherit' | 'current'} [textColor] - Text color (Bulma color, 'inherit', or 'current').
+ * @property {'primary'|'link'|'info'|'success'|'warning'|'danger'} [color] - Bulma color modifier for the cell.
+ * @property {(typeof validColors)[number] | 'inherit' | 'current'} [bgColor] - Background color (Bulma color, 'inherit', or 'current').
+ * @property {React.ReactNode} [children] - Children to render inside the cell.
+ */
 export interface CellProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
     colStart?: number;
     colFromEnd?: number;
@@ -14,4 +32,12 @@ export interface CellProps extends React.HTMLAttributes<HTMLDivElement>, Omit<Bu
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
     children?: React.ReactNode;
 }
+/**
+ * Bulma Cell component for CSS Grid layouts.
+ *
+ * @function
+ * @param {CellProps} props - Props for the Cell component.
+ * @returns {JSX.Element} The rendered grid cell.
+ * @see {@link https://bulma.io/documentation/grid/ | Bulma Grid documentation}
+ */
 export declare const Cell: React.FC<CellProps>;

package/dist/types/grid/Grid.d.ts

@@ -1,9 +1,42 @@
 import React from 'react';
 import { BulmaClassesProps, validColors } from '../helpers/useBulmaClasses';
+/**
+ * Allowed gap values for Bulma's 0-8 spacing scale, shared by `Grid` and
+ * `Columns`. Accepts the value as a number or a numeric string.
+ */
 export type BulmaGapValue = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8';
+/**
+ * Allowed minimum column values for Bulma grid.
+ */
 export type BulmaMinColValue = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32;
+/**
+ * Allowed fixed grid columns for Bulma grid.
+ */
 export type BulmaFixedGridCols = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/**
+ * Allowed fixed grid columns prop for Bulma grid.
+ */
 export type BulmaFixedGridColsProp = BulmaFixedGridCols | 'auto';
+/**
+ * Props for the Grid component.
+ *
+ * @property {boolean} [isFixed] - Use a fixed grid layout (Bulma's .fixed-grid > .grid).
+ * @property {BulmaGapValue} [gap] - Main gap for grid (applies is-gap-X, 0-8).
+ * @property {BulmaGapValue} [columnGap] - Column gap for grid (applies is-column-gap-X, 0-8).
+ * @property {BulmaGapValue} [rowGap] - Row gap for grid (applies is-row-gap-X, 0-8).
+ * @property {BulmaMinColValue} [minCol] - Minimum column width for the grid (applies is-col-min-X, 1-32).
+ * @property {BulmaFixedGridColsProp} [fixedCols] - For fixed grid only: explicit column count (applies has-X-cols, 0-12), or 'auto' for has-auto-count.
+ * @property {BulmaFixedGridCols} [fixedColsMobile] - For fixed grid only: explicit column count for mobile.
+ * @property {BulmaFixedGridCols} [fixedColsTablet] - For fixed grid only: explicit column count for tablet.
+ * @property {BulmaFixedGridCols} [fixedColsDesktop] - For fixed grid only: explicit column count for desktop.
+ * @property {BulmaFixedGridCols} [fixedColsWidescreen] - For fixed grid only: explicit column count for widescreen.
+ * @property {BulmaFixedGridCols} [fixedColsFullhd] - For fixed grid only: explicit column count for fullhd.
+ * @property {string} [className] - Additional CSS class names.
+ * @property {(typeof validColors)[number] | 'inherit' | 'current'} [textColor] - Text color (Bulma color, 'inherit', or 'current').
+ * @property {'primary'|'link'|'info'|'success'|'warning'|'danger'} [color] - Bulma color modifier for the grid.
+ * @property {(typeof validColors)[number] | 'inherit' | 'current'} [bgColor] - Background color (Bulma color, 'inherit', or 'current').
+ * @property {React.ReactNode} [children] - Children to render inside the grid.
+ */
 export interface GridProps extends React.HTMLAttributes<HTMLDivElement>, Omit<BulmaClassesProps, 'color' | 'backgroundColor'> {
     isFixed?: boolean;
     gap?: BulmaGapValue;
@@ -22,4 +55,6 @@ export interface GridProps extends React.HTMLAttributes<HTMLDivElement>, Omit<Bu
     bgColor?: (typeof validColors)[number] | 'inherit' | 'current';
     children?: React.ReactNode;
 }
-export declare const Grid: React.FC<GridProps>;
+export declare const Grid: React.FC<GridProps> & {
+    Cell: React.FC<import("./Cell").CellProps>;
+};