@allxsmith/bestax-bulma 5.7.0 → 5.8.1

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

@@ -1,54 +1,128 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
 import { FormFieldProps } from './fieldProps';
+/**
+ * Represents a tag item object with a value and optional label.
+ */
 export interface TaginputItem {
+    /** The tag value. */
     value: string;
+    /** Display label (optional). */
     label?: string;
     [key: string]: unknown;
 }
+/** A tag can be either a TaginputItem object or a plain string. */
 export type TaginputTag = TaginputItem | string;
 type IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
+/**
+ * Props for the Taginput component.
+ * @extraProp {string} [className] - Additional CSS classes.
+ * @extraProp {React.Ref<HTMLElement>} [ref] - Ref forwarded to the input element.
+ */
 export interface TaginputProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<BulmaClassesProps, 'color'>, FormFieldProps {
+    /** The current tags (controlled). */
     value?: TaginputTag[];
+    /** Default tags (uncontrolled). */
     defaultValue?: TaginputTag[];
+    /** Autocomplete suggestions. */
     data?: string[];
+    /** Placeholder text when no tags. */
     placeholder?: string;
+    /** Object property to use as display field. */
     field?: string;
+    /** Allow creating new tags not in suggestions. */
     allowNew?: boolean;
+    /** Allow duplicate tags. */
     allowDuplicates?: boolean;
+    /** Open autocomplete dropdown on focus. */
     openOnFocus?: boolean;
+    /** Remove tag on backspace. Default: true. */
     removeOnKeys?: boolean;
+    /** Keys to confirm tag creation. Default: ['Enter', ',']. */
     confirmKeys?: string[];
+    /** Show close button on tags. Default: true. */
     closable?: boolean;
+    /** Attach tags visually. */
     attached?: boolean;
+    /** Maximum number of tags allowed. */
     maxTags?: number;
+    /** Maximum length of input. */
     maxlength?: number;
+    /** Whether the input is disabled. */
     disabled?: boolean;
+    /** Whether the input is read-only. */
     readonly?: boolean;
+    /** Applies rounded corners to the tags. */
     rounded?: boolean;
+    /** Truncates long tag text with ellipsis. */
     ellipsis?: boolean;
+    /** Shows a counter of the number of tags. */
     hasCounter?: boolean;
+    /** Characters that split pasted text into tags. */
     onPasteSeparators?: string[];
+    /** Validation function called before adding a tag. */
     beforeAdding?: (tag: string) => boolean;
+    /** Custom function for creating tag objects from input. */
     createTag?: (input: string) => TaginputTag;
+    /** Keeps the first autocomplete suggestion highlighted. */
     keepFirst?: boolean;
+    /** Keeps the autocomplete dropdown open after selection. */
     keepOpen?: boolean;
+    /** Shows a loading indicator. */
     loading?: boolean;
+    /** ARIA label for tag close buttons. */
     ariaCloseLabel?: string;
+    /** Icon name for the input field. */
     icon?: string;
+    /** Icon library to use. */
     iconLibrary?: IconLibrary;
+    /** Icon style variant (e.g., 'solid', 'outlined'). */
     iconVariant?: string;
+    /** Additional icon modifiers. */
     iconFeatures?: string | string[];
+    /** Input color variant. */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+    /** Tag color variant. */
     tagColor?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'dark' | 'light';
+    /** Size variant. */
     size?: 'small' | 'medium' | 'large';
+    /** Form field name. When set, one hidden input per tag is rendered. */
     name?: string;
+    /** Optional id of the form the hidden inputs belong to. */
     form?: string;
+    /** Callback when tags change. */
     onChange?: (tags: TaginputTag[]) => void;
+    /** Callback when tag is added. */
     onAdd?: (tag: TaginputTag) => void;
+    /** Callback when tag is removed. */
     onRemove?: (tag: TaginputTag, index: number) => void;
+    /** Callback when typing in input. */
     onTyping?: (value: string) => void;
+    /** Custom render for tags. */
     tagTemplate?: (tag: TaginputTag) => React.ReactNode;
 }
+/**
+ * The `Taginput` component provides a tag/chip input field for managing multiple tags.
+ *
+ * @function
+ * @param {TaginputProps} props - Props for the Taginput component.
+ * @param {React.Ref<HTMLInputElement>} ref - Forwarded ref to the input element.
+ * @returns {JSX.Element} The rendered taginput component.
+ *
+ * @example
+ * // Basic usage
+ * <Taginput
+ *   placeholder="Add a tag..."
+ *   onChange={(tags) => console.log(tags)}
+ * />
+ *
+ * @example
+ * // With autocomplete
+ * <Taginput
+ *   data={['React', 'Vue', 'Angular', 'Svelte']}
+ *   allowNew={false}
+ *   placeholder="Select frameworks..."
+ * />
+ */
 export declare const Taginput: React.ForwardRefExoticComponent<TaginputProps & React.RefAttributes<HTMLInputElement>>;
 export default Taginput;

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

@@ -2,17 +2,51 @@ import React from 'react';
 import { FieldProps } from './Field';
 import { ControlBaseProps } from './Control';
 import { TextAreaBaseProps } from './TextAreaBase';
+/**
+ * Props for the TextArea component.
+ *
+ * Composes Field, Control, and TextAreaBase into a single convenience component.
+ * Supports all TextAreaBase props, plus Field-level (label, horizontal) and
+ * Control-level (loading) props.
+ */
 export interface TextAreaProps extends TextAreaBaseProps {
+    /** Field label. */
     label?: React.ReactNode;
+    /** Size for the label. */
     labelSize?: FieldProps['labelSize'];
+    /** Props for the label element. */
     labelProps?: FieldProps['labelProps'];
+    /** Horizontal field layout. */
     horizontal?: boolean;
+    /** Shows loading indicator on the wrapping Control. */
     isLoading?: boolean;
+    /** Control size. */
     controlSize?: ControlBaseProps['size'];
+    /** Help/validation message below the textarea. */
     message?: React.ReactNode;
+    /** Bulma color for the message. */
     messageColor?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+    /** Additional CSS classes for the Field. */
     fieldClassName?: string;
+    /** Additional CSS classes for the Control. */
     controlClassName?: string;
 }
+/**
+ * The `TextArea` component provides a Bulma-styled multi-line text input, supporting color, size, rounded corners, static/read-only state, hover/focus/loading states, fixed size, and all Bulma helper props.
+ *
+ * @function
+ * @param {TextAreaProps} props - Props for TextArea.
+ * @returns {JSX.Element} The composed field element.
+ *
+ * @example
+ * <TextArea label="Bio" placeholder="Tell us about yourself" rows={4} />
+ *
+ * @example
+ * <TextArea
+ *   label="Comments"
+ *   message="Max 500 characters"
+ *   messageColor="info"
+ * />
+ */
 export declare const TextArea: React.ForwardRefExoticComponent<TextAreaProps & React.RefAttributes<HTMLTextAreaElement>>;
 export default TextArea;

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

@@ -1,19 +1,43 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses';
+/**
+ * Props for the TextArea component.
+ */
 export interface TextAreaBaseProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'size'>, Omit<BulmaClassesProps, 'color'> {
+    /** Bulma color modifier for the textarea. */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white';
+    /** Size modifier for the textarea. */
     size?: 'small' | 'medium' | 'large';
+    /** Rounded textarea corners. */
     isRounded?: boolean;
+    /** Renders textarea as static (styled readonly). */
     isStatic?: boolean;
+    /** Applies hovered state. */
     isHovered?: boolean;
+    /** Applies focused state. */
     isFocused?: boolean;
+    /** Shows loading indicator on the wrapping Control. */
     isLoading?: boolean;
+    /** Applies Bulma's is-active modifier. */
     isActive?: boolean;
+    /** Fixed textarea size (no resize). */
     hasFixedSize?: boolean;
+    /** Additional CSS classes to apply. */
     className?: string;
+    /** Disables the textarea. */
     disabled?: boolean;
+    /** Read-only textarea. */
     readOnly?: boolean;
+    /** Number of visible text lines. */
     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,25 +2,65 @@ 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.
+ * @extraProp {string} [name] - Form field name.
+ * @extraProp {string} [form] - Form id the input belongs to.
+ * @extraProp {boolean} [required=false] - Marks the input as required.
+ * @extraProp {string} [className] - Additional CSS classes for the input.
+ * @extraProp {React.Ref<HTMLInputElement>} [ref] - Forwarded to the underlying `<input>`.
+ */
 export interface TimeInputProps extends TimeInputBaseProps {
+    /** Field label. */
     label?: React.ReactNode;
+    /** Size for the label. */
     labelSize?: FieldProps['labelSize'];
+    /** Props for the label element. */
     labelProps?: FieldProps['labelProps'];
+    /** Render the field with horizontal layout. */
     horizontal?: boolean;
+    /** Icon props for the left icon. */
     iconLeft?: ControlBaseProps['iconLeft'];
+    /** Icon props for the right icon. */
     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;
+    /** Show a loading indicator on the control. */
     isLoading?: boolean;
+    /** Expand the control to fill its container. */
     isExpanded?: boolean;
+    /** Size of the wrapping Control. */
     controlSize?: ControlBaseProps['size'];
+    /** Help/validation text below the input. */
     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 `TimeInput` component is a form input that opens a popover spinner for time-of-day selection.
+ *
+ * @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,43 +2,94 @@ 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.
+ */
 export interface TimeInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'onChange' | 'size' | 'color' | 'min' | 'max' | 'type' | 'popover'>, Omit<BulmaClassesProps, 'color'> {
+    /** Controlled selected time (date portion is preserved). */
     value?: Date | null;
+    /** Initial value for uncontrolled usage. */
     defaultValue?: Date | null;
+    /** Fired when the value changes. */
     onChange?: (d: Date | null) => void;
+    /** Fired when the popover opens. */
     onOpen?: () => void;
+    /** Fired when the popover closes. */
     onClose?: () => void;
+    /** Earliest selectable time. */
     min?: Date;
+    /** Latest selectable time. */
     max?: Date;
+    /** Disable the input. */
     disabled?: boolean;
+    /** Make the input read-only. */
     readOnly?: boolean;
+    /** Placeholder text for the input. */
     placeholder?: string;
+    /**
+     * Token format string or `Intl.DateTimeFormat` options.
+     * @defaultValue (see below)
+     */
     format?: DateFormatOption;
+    /** Custom parser. */
     parse?: (s: string) => Date | null;
+    /** BCP-47 locale tag for Intl formatting. */
     locale?: string;
+    /** Render the spinner inline (no popover). */
     inline?: boolean;
+    /** Use `<input type="time">` on coarse-pointer + small-viewport devices. */
     mobileNative?: boolean | 'auto';
+    /** Allow segmented keyboard typing in the input (type the time directly, auto-advancing across segments). `false` makes the field picker-only. */
     editable?: boolean;
+    /** Whether the spinner popover exists. `false` makes the field input-only (segmented typing, no popover). */
     popover?: boolean;
+    /** Open the popover when the input is focused. */
     openOnFocus?: boolean;
+    /** Close the popover after a time is selected (off by default). */
     closeOnSelect?: boolean;
+    /** Popover anchor position relative to the input. */
     position?: PickerPosition;
+    /** Render the popover into `document.body` via portal. */
     appendToBody?: boolean;
+    /** Bulma color modifier. */
     color?: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger';
+    /** Size variant. */
     size?: 'small' | 'medium' | 'large';
+    /** Render the input with rounded corners. */
     isRounded?: boolean;
+    /** Hour format. `'12'` shows an AM/PM toggle. */
     hourFormat?: HourFormat;
+    /** Show a seconds column. Note: iOS Safari's native time picker UI does not include a seconds wheel; pass `mobileNative={false}` if you need one on iOS. */
     enableSeconds?: boolean;
+    /** Hour step for the spinner. */
     incrementHours?: number;
+    /** Minute step. Combine with `min`/`max` for slot-style pickers. */
     incrementMinutes?: number;
+    /** Second step. Default `1`. */
     incrementSeconds?: number;
+    /** Predicate returning `true` for times that should be skipped. Blocked times are also rejected during manual typing. */
     unselectableTimes?: (d: Date) => 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. Default `true`. */
     triggerIcon?: boolean;
+    /** Glyph for the right launcher button. */
     triggerIconName?: string;
+    /** Optional translatable string overrides. */
     labels?: PickerLabels;
+    /** Play a short audible click on each wheel-item crossing. Substitute for haptic feedback on iOS Safari (which has no web haptic API as of May 2026); on Android, `navigator.vibrate(5)` fires automatically regardless. */
     audioTick?: boolean;
+    /** Auto-route platform-appropriate feedback: vibrate on Android (already happening), audio thunk on iOS (where vibrate is unavailable). One switch instead of platform-sniffing on the consumer side. `audioTick={true}` always 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;