@allxsmith/bestax-bulma 5.23.0 → 5.24.0

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

@@ -1,6 +1,6 @@
 import React from 'react';
 import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
-import { PickerPosition, DayOfWeek, PickerLabels } from './_pickerInternals/pickerTypes.js';
+import { PickerPosition, DayOfWeek, DateGranularity, PickerLabels } from './_pickerInternals/pickerTypes.js';
 import { DateFormatOption } from './_pickerInternals/formatters.js';
 /**
  * Props for the raw DateInput base. Use the higher-level `DateInput` for
@@ -28,7 +28,29 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     /** Placeholder text for the input. */
     placeholder?: string;
     /**
-     * Token format string or `Intl.DateTimeFormat` options. Default `'YYYY-MM-DD'`.
+     * What the calendar shows and what a selection means: `'day'` shows the
+     * day grid, `'month'` a grid of the focused year's months whose header
+     * steps a year at a time, and `'year'` the year list. A month or year value
+     * is the first day of that period at local midnight, so `onChange` gets
+     * `new Date(2026, 5, 1)` for June 2026. A `value` elsewhere in the period
+     * shows as that period and stays as given until the user picks a period or
+     * types a different one. `min`, `max`,
+     * `shouldDisableDate` and `unselectableDates` judge whole periods: a month
+     * or year can be picked while any day in it can, so a `min` of 15 June
+     * still allows June, and June commits as 1 June, earlier than that `min`.
+     * The default `format` follows the granularity (`'YYYY-MM'`, `'YYYY'`); a
+     * custom `format` with finer tokens still renders them, but typing skips
+     * them. `firstDayOfWeek`, `dayNames` and `nearbyMonthDays` only affect the
+     * day grid, and an `inline` calendar's hidden form value is `YYYY-MM` or
+     * `YYYY`. The `labels` keys `chooseMonth` / `chooseYear` name the launcher
+     * and popover, and `prevYear` / `nextYear` the month grid's header buttons.
+     * @defaultValue 'day'
+     */
+    granularity?: DateGranularity;
+    /**
+     * Token format string or `Intl.DateTimeFormat` options. Defaults to
+     * `'YYYY-MM-DD'`, or to `'YYYY-MM'` / `'YYYY'` when `granularity` is
+     * `'month'` / `'year'`.
      * @defaultValue 'YYYY-MM-DD'
      */
     format?: DateFormatOption;
@@ -38,7 +60,15 @@ export interface DateInputBaseProps extends Omit<React.InputHTMLAttributes<HTMLI
     locale?: string;
     /** Render the calendar inline (no popover). */
     inline?: boolean;
-    /** Use `<input type="date">` on coarse-pointer + small-viewport devices. */
+    /**
+     * Use `<input type="date">` on coarse-pointer + small-viewport devices. At
+     * `'month'` granularity it uses `<input type="month">` where the browser
+     * implements one, as Chromium browsers, Safari on iOS and Firefox for
+     * Android do, and the calendar where it doesn't, as in desktop Firefox.
+     * Desktop Safari accepts the type but draws no month control, so forcing
+     * `true` there shows a plain text box. HTML has no year input, so `'year'`
+     * granularity always renders the calendar.
+     */
     mobileNative?: boolean | 'auto';
     /** Allow segmented keyboard typing in the input (type the date directly, auto-advancing across segments). `false` makes the field picker-only. */
     editable?: boolean;

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import { DayOfWeek, PickerLabels } from './pickerTypes.js';
+import { DateGranularity, DayOfWeek, PickerLabels } from './pickerTypes.js';
 export interface CalendarProps {
     value: Date | null;
     focusedDate: Date;
@@ -25,8 +25,18 @@ export interface CalendarProps {
     /**
      * Inclusive `[min, max]` year range shown in the year-dropdown view.
      * Defaults to ±100 years around the focused year, clamped by `min`/`max`.
+     * At `'year'` granularity the window centres on the year focused when the
+     * calendar mounted, so moving focus never reflows the list.
      */
     yearsRange?: [number, number];
+    /**
+     * What a selection means. `'day'` shows the day grid; `'month'` shows a
+     * month grid for the focused year, with the year list one header click
+     * away for jumping; `'year'` shows the year list as the selection surface.
+     * A month or year cell is disabled when every day in it is, and `onSelect`
+     * receives the period's first day.
+     */
+    granularity?: DateGranularity;
 }
 export declare const Calendar: React.FC<CalendarProps>;
 export default Calendar;

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

@@ -1,4 +1,4 @@
-import { DayOfWeek } from './pickerTypes.js';
+import { DateGranularity, DayOfWeek } from './pickerTypes.js';
 export interface CalendarCell {
     date: Date;
     inCurrentMonth: boolean;
@@ -13,6 +13,41 @@ export declare function startOfDay(d: Date): Date;
 export declare function endOfDay(d: Date): Date;
 export declare function startOfMonth(d: Date): Date;
 export declare function endOfMonth(d: Date): Date;
+/**
+ * Local midnight on `year`-`month`-`day` (`month` from 0), like the
+ * `Date(y, m, d)` constructor except that years 0–99 stay as given rather than
+ * turning into 1900–1999.
+ */
+export declare function makeDate(year: number, month?: number, day?: number): Date;
+/**
+ * First instant of the day, month or year containing `d`. Works by setters on
+ * a copy rather than the `Date(y, m, d)` constructor, which reads years 0–99
+ * as 1900–1999: segmented typing passes through such years on the way to a
+ * four-digit one.
+ */
+export declare function startOfPeriod(d: Date, granularity: DateGranularity): Date;
+/** Last instant of the day, month or year containing `d`. */
+export declare function endOfPeriod(d: Date, granularity: DateGranularity): Date;
+/** The rules that make a single calendar day unselectable. */
+export interface DayConstraints {
+    min?: Date;
+    max?: Date;
+    shouldDisableDate?: (d: Date) => boolean;
+    unselectableDates?: Date[];
+}
+/**
+ * Whether the day `d` falls outside `[min, max]` or is blocked by
+ * `shouldDisableDate` / `unselectableDates`. This is the day grid's rule for a
+ * disabled cell.
+ */
+export declare function isDayUnselectable(d: Date, c: DayConstraints): boolean;
+/**
+ * Whether every day of the month or year containing `d` is unselectable, so
+ * the period as a whole can't be picked. Walks the period's days and stops at
+ * the first selectable one. `min` and `max` count whole days here, so a `min`
+ * 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;
 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;

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

@@ -1,5 +1,7 @@
 export type DateFormatOption = Intl.DateTimeFormatOptions | string;
 export declare const DEFAULT_DATE_FORMAT = "YYYY-MM-DD";
+export declare const DEFAULT_MONTH_FORMAT = "YYYY-MM";
+export declare const DEFAULT_YEAR_FORMAT = "YYYY";
 export declare const DEFAULT_TIME_FORMAT_24 = "HH:mm";
 export declare const DEFAULT_TIME_FORMAT_12 = "hh:mm A";
 export declare const DEFAULT_DATETIME_FORMAT = "YYYY-MM-DD HH:mm";

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

@@ -0,0 +1,11 @@
+/**
+ * Whether this browser implements `<input type={type}>`. A browser that
+ * doesn't know a type reads it back as `'text'`, so this sets the type on a
+ * detached input and checks what sticks. The answer can't change within a
+ * page, so it is worked out once per type.
+ *
+ * It needs a DOM, so callers ask only after hydration. It also can't see a
+ * browser that recognises a type without drawing a control for it: desktop
+ * Safari reports `'month'` but shows a plain text box.
+ */
+export declare function supportsInputType(type: string): boolean;

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

@@ -1,6 +1,8 @@
 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;
+/** The unit a date picker selects: a day, a month or a year. */
+export type DateGranularity = 'day' | 'month' | 'year';
 /**
  * Translatable strings used across all four pickers. Pass via the `labels`
  * prop to override defaults; consumers manage their own locale-driven mapping.
@@ -8,7 +10,15 @@ export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 export interface PickerLabels {
     prevMonth?: string;
     nextMonth?: string;
+    /** Month grid header: steps back a year. */
+    prevYear?: string;
+    /** Month grid header: steps forward a year. */
+    nextYear?: string;
     chooseDate?: string;
+    /** Launcher and popover name when the picker selects a month. */
+    chooseMonth?: string;
+    /** Launcher, popover and year list name when the picker selects a year. */
+    chooseYear?: string;
     hours?: string;
     minutes?: string;
     seconds?: string;

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

@@ -1,9 +1,17 @@
 import React from 'react';
 import { DateFormatOption } from './formatters.js';
-import { SegmentMap } from './segmentMap.js';
+import { SegmentKind, SegmentMap } from './segmentMap.js';
 export interface UseSegmentedEntryParams {
     /** Resolved format actually used to render (the host's default format). */
     format: DateFormatOption;
+    /**
+     * Segment kinds the caret never stops on: they still render, but arrows,
+     * digits and separators pass over them. A month picker skips `'day'` so a
+     * format such as `'YYYY-MM-DD'` edits only the year and month. Must be
+     * referentially stable. A format left with no editable segment falls back
+     * to free-form entry.
+     */
+    skipKinds?: readonly SegmentKind[];
     /** Current canonical value (controlled or internal). */
     value: Date | null;
     /** Commit a new Date through the host's onChange / internal pipeline. */

package/dist/types-cjs/helpers/useAnchoredPosition.d.ts

@@ -0,0 +1,59 @@
+import type { RefObject } from 'react';
+import type { PickerPosition } from '../form/_pickerInternals/pickerTypes.js';
+/** A corner of the anchor the panel opens from, once `auto` is resolved. */
+export type AnchoredCorner = Exclude<PickerPosition, 'auto'>;
+/**
+ * Where the panel goes: the corner it opens from and, when it is fixed to
+ * the viewport, its coordinates there.
+ */
+export interface AnchoredPosition {
+    position: AnchoredCorner;
+    top?: number;
+    left?: number;
+}
+/**
+ * Options for `useAnchoredPosition`.
+ */
+export interface UseAnchoredPositionOptions {
+    /** Whether the panel is on the page. Nothing is measured while it is not. */
+    active: boolean;
+    /** The corner asked for, or `auto` to pick one that keeps the panel in the viewport. */
+    position: PickerPosition;
+    /**
+     * Whether the panel is fixed to the viewport (it was portaled away from the
+     * anchor), which needs coordinates. Otherwise the panel's CSS places it
+     * against the anchor from the corner alone.
+     */
+    fixed: boolean;
+    /**
+     * The gap between the anchor and the panel, in pixels, that the hook puts
+     * there itself: added to the fixed coordinates and to the room `auto` asks
+     * for below the anchor.
+     * @defaultValue 4
+     */
+    offset?: number;
+    /**
+     * Reads the gap the panel's own stylesheet puts between it and the anchor,
+     * in pixels, each time the panel is measured. `auto` leaves room for it as
+     * well; the coordinates don't include it, because the stylesheet applies it.
+     */
+    styledGap?: (panel: HTMLElement) => number;
+}
+/**
+ * Places a floating panel against its anchor: resolves `auto` to a corner
+ * and, for a panel fixed to the viewport, works out its coordinates. It
+ * measures again on resize and on any scroll of the anchor's window (an
+ * iframe's, when the anchor renders into one), so a fixed panel follows its
+ * anchor. A measurement that changes nothing doesn't render again.
+ *
+ * Measuring happens in a layout effect, so the panel is placed before it
+ * paints. It needs both elements on the page while `active` is on, and
+ * keeps the last placement when either is missing.
+ *
+ * @function useAnchoredPosition
+ * @param anchorRef - The element the panel opens from.
+ * @param panelRef - The floating panel.
+ * @param options - Whether to measure, the corner asked for, and how the panel is placed.
+ * @returns The corner the panel opens from, with coordinates when it is fixed.
+ */
+export declare function useAnchoredPosition(anchorRef: RefObject<HTMLElement | null>, panelRef: RefObject<HTMLElement | null>, { active, position, fixed, offset, styledGap }: UseAnchoredPositionOptions): AnchoredPosition;

package/dist/types-cjs/helpers/useClientLayoutEffect.d.ts

@@ -0,0 +1,7 @@
+import { useEffect } from 'react';
+/**
+ * `useLayoutEffect` in the browser, `useEffect` on the server. A server
+ * render runs neither, and React 18 warns about a layout effect there, so the
+ * server is handed the plain one.
+ */
+export declare const useClientLayoutEffect: typeof useEffect;

package/dist/types-cjs/helpers/useFocusTrap.d.ts

@@ -1,4 +1,11 @@
 import type { RefObject } from 'react';
+/**
+ * The first tab stop inside `container`, found the way the trap finds it, or
+ * `null` when there is none. For a component that moves focus into a panel
+ * without trapping it there. `src/index.ts` names its exports from this
+ * module, so this one stays internal.
+ */
+export declare function firstTabStop(container: HTMLElement): HTMLElement | null;
 /**
  * Options for `useFocusTrap`.
  */
@@ -10,9 +17,12 @@ export interface UseFocusTrapOptions {
      */
     active?: boolean;
     /**
-     * The element to focus when the trap turns on. Without it, or while it
-     * points at nothing, focus goes to the first tab stop inside the container,
-     * and to the container itself when there is none.
+     * The element inside the container to focus when the trap turns on. It has
+     * to be one that can take focus, so a heading needs `tabIndex={-1}`. When
+     * focusing it doesn't put focus inside the container (the ref is empty, or
+     * its element is outside, disabled, hidden or can't take focus), focus goes
+     * to the first tab stop inside the container, and to the container itself
+     * when there is none.
      */
     initialFocusRef?: RefObject<HTMLElement | null>;
     /**

package/dist/types-cjs/index.d.ts

@@ -17,6 +17,7 @@ export * from './components/Loading.js';
 export * from './components/Collapse.js';
 export * from './components/Collapses.js';
 export * from './components/Tooltip.js';
+export * from './components/Popover.js';
 export * from './components/Steps.js';
 export * from './components/Sidebar.js';
 export * from './components/Toast.js';