@beeq/core 1.12.14-beta.0 → 1.13.0

package/dist/types/components/date-picker/bq-date-picker.types.d.ts

@@ -1,45 +1,36 @@
 /** The first day of the week, where Sunday is 0, Monday is 1, etc. */
 export type DaysOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export declare const DAYS_OF_WEEK: readonly DaysOfWeek[];
 /** The type of the date picker */
 export declare const DATE_PICKER_TYPE: readonly ["single", "multi", "range"];
 /** The type of the date picker */
 export type TDatePickerType = (typeof DATE_PICKER_TYPE)[number];
-export type TCalendarDate = {
-    /** The first day of the week */
-    firstDayOfWeek?: number;
-    /** The focused date */
-    focusedDate: string;
-    /** The locale */
-    locale?: string;
-    /** The maximum date */
-    max?: string;
-    /** The minimum date */
-    min?: string;
-    /** The number of months to show */
-    months?: number;
-    /** How to navigate through the calendar, by single month or by the number of months */
-    pageBy?: 'single' | 'months';
-    /** Whether to show days outside the current month */
-    showOutsideDays?: boolean;
-    /** The tentative selected date, e.g. the start of a date range */
-    tentative?: string;
-    /** The selected date, in ISO-8601 format (YYYY-MM-DD) */
-    value: string;
-    /**
-     * Focuses the <calendar-month> containing the currently focused date.
-     * `option.target` controls which part of the component gets focused.
-     */
-    focus: ({ target }: {
-        target: 'previous' | 'next' | 'day';
-    }) => void;
-    /** Checks if the date is not allowed to be selected */
-    isDateDisallowed?: (date: Date) => boolean;
-    /** Handles the change event, when the user selects a date or a date range */
-    onChange?: (ev: Event) => void;
-    /** Handles the focus date event. E.g. when the user navigates back/forward in the calendar */
-    onFocusDate?: (ev: CustomEvent) => void;
-    /** Handles the date range start event. E.g. when the user starts selecting a date range */
-    onRangestart?: (ev: CustomEvent) => void;
-    /** Handles the date range end event. E.g. when the user finishes selecting a date range */
-    onRangeend?: (ev: CustomEvent) => void;
-};
+/** The calendar view */
+export declare const CALENDAR_VIEW: readonly ["days", "months", "years"];
+/** The calendar view */
+export type TCalendarView = (typeof CALENDAR_VIEW)[number];
+/** Positioning strategy for the panel. */
+export declare const FLOATING_STRATEGY: readonly ["fixed", "absolute"];
+export type TFloatingStrategy = (typeof FLOATING_STRATEGY)[number];
+/** Placement of the panel — mirrors `@floating-ui/dom` placements. */
+export declare const FLOATING_PLACEMENT: readonly ["top", "top-start", "top-end", "right", "right-start", "right-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", "left-end"];
+export type TFloatingPlacement = (typeof FLOATING_PLACEMENT)[number];
+/** How the next/previous buttons should step through months. */
+export declare const MONTHS_PER_VIEW: readonly ["single", "months"];
+export type TMonthsPerView = (typeof MONTHS_PER_VIEW)[number];
+/**
+ * The precision of the value produced by the date picker.
+ * - `day`   → `YYYY-MM-DD` (default; drill-down to days)
+ * - `month` → `YYYY-MM`    (selection commits on the months view)
+ * - `year`  → `YYYY`       (selection commits on the years view)
+ */
+export declare const DATE_PRECISION: readonly ["day", "month", "year"];
+export type TDatePrecision = (typeof DATE_PRECISION)[number];
+/**
+ * Internal representation of a selection.
+ * Always an array of ISO 8601 date strings (YYYY-MM-DD).
+ * - single → 0 or 1 entry
+ * - multi  → N entries
+ * - range  → 0 or 2 entries [startISO, endISO]
+ */
+export type TSelection = string[];

package/dist/types/components/date-picker/components/CalendarDayView.d.ts

@@ -0,0 +1,42 @@
+import { type FunctionalComponent } from '../../../stencil-public-runtime';
+import type { TDatePickerType, TSelection } from '../bq-date-picker.types';
+export type TCalendarDayViewProps = {
+    /** Anchor date for the month grid (any date within the month). */
+    viewDate: Date;
+    /** Current selection (parsed). */
+    selection: TSelection;
+    /** In-progress range selection (start pending or hovered end). */
+    tentativeRange: TSelection;
+    /** Focused date ISO (roving tabindex target). */
+    focusedISO: string;
+    /** Selection type. */
+    type: TDatePickerType;
+    /** Locale. */
+    locale: Intl.LocalesArgument;
+    /** First day of the week. */
+    firstDayOfWeek: number;
+    /** Whether to render outside-month days. */
+    showOutsideDays: boolean;
+    /** Optional min ISO. */
+    minISO?: string;
+    /** Optional max ISO. */
+    maxISO?: string;
+    /** Optional guard for disallowed days. */
+    isDateDisallowed?: (date: Date) => boolean;
+    /** Callback fired when a day is picked. */
+    onDaySelect: (iso: string, ev: MouseEvent | KeyboardEvent) => void;
+    /** Callback fired when the pointer hovers a day (used for range preview). */
+    onDayHover: (iso: string | undefined) => void;
+    /** Callback fired when a day receives focus. */
+    onDayFocus: (iso: string) => void;
+    /** Optional handler for keyboard nav bubbling up (Arrow, Home, End...). */
+    onGridKeyDown: (ev: KeyboardEvent) => void;
+};
+/**
+ * Day-level calendar view — weekday row + 6x7 grid.
+ *
+ * The grid is a `<table role="grid">` so it is announced correctly by screen
+ * readers, and it uses a roving tabindex so only the "focused" day is in the
+ * tab order. Keyboard nav is delegated to the host via `onGridKeyDown`.
+ */
+export declare const CalendarDayView: FunctionalComponent<TCalendarDayViewProps>;

package/dist/types/components/date-picker/components/CalendarHeader.d.ts

@@ -0,0 +1,34 @@
+import { type FunctionalComponent } from '../../../stencil-public-runtime';
+import type { TCalendarView } from '../bq-date-picker.types';
+export type TCalendarHeaderProps = {
+    /** Current view. Used to pick the correct aria label and title. */
+    view: TCalendarView;
+    /** Label rendered inside the title button (e.g. "January 2026", "2026", "2016 – 2027"). */
+    label: string;
+    /** Aria label for the previous button. */
+    previousLabel: string;
+    /** Aria label for the next button. */
+    nextLabel: string;
+    /** Aria label for the title button. */
+    titleLabel: string;
+    /** Whether the previous button is disabled. */
+    previousDisabled?: boolean;
+    /** Whether the next button is disabled. */
+    nextDisabled?: boolean;
+    /** Whether the title button is interactive. `false` when already on the years view. */
+    titleInteractive?: boolean;
+    /** Callback fired when the previous button is activated. */
+    onPrevious: (ev: Event) => void;
+    /** Callback fired when the next button is activated. */
+    onNext: (ev: Event) => void;
+    /** Callback fired when the title button is activated. */
+    onTitleClick: (ev: Event) => void;
+};
+/**
+ * Calendar header — previous / title / next.
+ *
+ * The header is rendered once per calendar panel. It exposes the standard
+ * `calendar__header`, `calendar__previous`, `calendar__heading`, and
+ * `calendar__next` shadow parts so consumers can theme any button.
+ */
+export declare const CalendarHeader: FunctionalComponent<TCalendarHeaderProps>;

package/dist/types/components/date-picker/components/CalendarMonthView.d.ts

@@ -0,0 +1,34 @@
+import { type FunctionalComponent } from '../../../stencil-public-runtime';
+import type { TDatePickerType, TSelection } from '../bq-date-picker.types';
+export type TCalendarMonthViewProps = {
+    /** Year currently shown in the header. */
+    year: number;
+    /** Focused month (0-based), used for the roving tabindex. */
+    focusedMonth: number;
+    /** Locale used for localized month names. */
+    locale: Intl.LocalesArgument;
+    /** Min year/month to keep enabled. */
+    minISO?: string;
+    /** Max year/month to keep enabled. */
+    maxISO?: string;
+    /** Current selection (as stored internally: array of YYYY-MM-DD). */
+    selection: TSelection;
+    /** In-progress range preview while hovering a second endpoint. */
+    tentativeRange: TSelection;
+    /** Selection type — drives multi / range highlighting. */
+    type: TDatePickerType;
+    /** Callback fired when the user picks a month. */
+    onMonthSelect: (month: number, ev: MouseEvent | KeyboardEvent) => void;
+    /** Callback fired when a month button receives focus. */
+    onMonthFocus: (month: number) => void;
+    /** Callback fired when hovering a month cell (range preview). */
+    onMonthHover: (iso: string | undefined) => void;
+    /** Optional keydown handler for the grid (roving tabindex management). */
+    onGridKeyDown: (ev: KeyboardEvent) => void;
+    /** Number of columns rendered by the month grid. */
+    gridColumns: number;
+};
+/**
+ * Month picker — 12 buttons in a 3×4 grid.
+ */
+export declare const CalendarMonthView: FunctionalComponent<TCalendarMonthViewProps>;

package/dist/types/components/date-picker/components/CalendarYearView.d.ts

@@ -0,0 +1,32 @@
+import { type FunctionalComponent } from '../../../stencil-public-runtime';
+import type { TDatePickerType, TSelection } from '../bq-date-picker.types';
+export type TCalendarYearViewProps = {
+    /** Years to render (typically 12). */
+    years: number[];
+    /** Focused year (roving tabindex target). */
+    focusedYear: number;
+    /** Optional min bound (any precision — `YYYY`, `YYYY-MM`, `YYYY-MM-DD`). */
+    minISO?: string;
+    /** Optional max bound (any precision). */
+    maxISO?: string;
+    /** Current selection (as stored internally: array of YYYY-MM-DD). */
+    selection: TSelection;
+    /** In-progress range preview while hovering a second endpoint. */
+    tentativeRange: TSelection;
+    /** Selection type — drives multi / range highlighting. */
+    type: TDatePickerType;
+    /** Callback fired when the user picks a year. */
+    onYearSelect: (year: number, ev: MouseEvent | KeyboardEvent) => void;
+    /** Callback fired when a year button receives focus. */
+    onYearFocus: (year: number) => void;
+    /** Callback fired when hovering a year cell (range preview). */
+    onYearHover: (iso: string | undefined) => void;
+    /** Optional keydown handler for the grid (roving tabindex management). */
+    onGridKeyDown: (ev: KeyboardEvent) => void;
+    /** Number of columns rendered by the year grid. */
+    gridColumns: number;
+};
+/**
+ * Year picker — 12 buttons for a decade grid.
+ */
+export declare const CalendarYearView: FunctionalComponent<TCalendarYearViewProps>;

package/dist/types/components/date-picker/helper/bounds.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Bounds predicates for the calendar.
+ *
+ * `min` and `max` may be at any wire precision (`YYYY`, `YYYY-MM`, or
+ * `YYYY-MM-DD`); internal cell values are always full `YYYY-MM-DD` strings.
+ * All predicates are pure and rely on lexicographic comparison, which is
+ * safe for ISO 8601 dates.
+ */
+/**
+ * Extract the `YYYY` prefix (as a number) from a bound string.
+ * Returns `null` if the string does not begin with a 4-digit year.
+ */
+export declare const boundYear: (iso: string | undefined | null) => number | null;
+/**
+ * Extract `{ year, month }` (month is 0-based) from a bound string. Falls
+ * back to `null` when the string doesn't contain a `YYYY-MM` prefix.
+ */
+export declare const boundYearMonth: (iso: string | undefined | null) => {
+    year: number;
+    month: number;
+} | null;
+/**
+ * Whether a given year is within the (inclusive) `min`/`max` range.
+ * A year cell is considered in-range when any day inside that year is
+ * still selectable — i.e. we compare on the year prefix only, ignoring
+ * the month/day components of `min` / `max`.
+ */
+export declare const isYearWithinBounds: (year: number, min?: string | null, max?: string | null) => boolean;
+/**
+ * Whether a given `(year, month)` pair is within the (inclusive) `min`/`max`
+ * range. A month cell is considered in-range when any day inside that month
+ * would still satisfy the bounds — we compare on the year-month prefix and
+ * ignore the day component of `min` / `max`.
+ */
+export declare const isMonthWithinBounds: (year: number, month: number, min?: string | null, max?: string | null) => boolean;
+/**
+ * Whether a full `YYYY-MM-DD` iso date is within the (inclusive) `min`/`max`
+ * range. Bounds may be at any precision — we pad `min` to the earliest day
+ * (`YYYY-01-01`) and `max` to the latest day (`YYYY-12-31`) before doing a
+ * lexical compare (safe because ISO 8601 sorts by calendar order).
+ */
+export declare const isDateWithinBounds: (iso: string, min?: string | null, max?: string | null) => boolean;
+/**
+ * Pad a bound string up to full `YYYY-MM-DD` length so it can be lexically
+ * compared with a full ISO date. `min` widens down (missing pieces become
+ * `-01`), `max` widens up (missing month → `-12`, missing day → last day of
+ * that month, honoring leap years).
+ */
+export declare const padBound: (iso: string | undefined | null, kind: "min" | "max") => string | null;

package/dist/types/components/date-picker/helper/calendar.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Parse an ISO 8601 date string (`YYYY-MM-DD`) into a local-time `Date`.
+ * Returns `null` when the string is missing or invalid.
+ */
+export declare const parseISO: (iso: string | undefined | null) => Date | null;
+/**
+ * Convert a `Date` to `YYYY-MM-DD` in local time.
+ */
+export declare const toISO: (date: Date) => string;
+/**
+ * Extract the calendar year and 0-based month from an ISO date string.
+ * Returns `null` for missing or malformed input — safer than `Number(iso.slice(...))`
+ * which silently produces `NaN` for invalid bounds.
+ */
+export declare const getISOYearMonth: (iso: string | undefined | null) => {
+    year: number;
+    month: number;
+} | null;
+/**
+ * Whether the ISO string is a valid `YYYY-MM-DD` date (round-trips through
+ * `parseISO`). Convenience predicate for input filtering.
+ */
+export declare const isValidISO: (iso: string | undefined | null) => boolean;
+export declare const startOfDay: (date: Date) => Date;
+export declare const startOfMonth: (date: Date) => Date;
+export declare const endOfMonth: (date: Date) => Date;
+export declare const addDays: (date: Date, amount: number) => Date;
+export declare const addMonths: (date: Date, amount: number) => Date;
+export declare const addYears: (date: Date, amount: number) => Date;
+export declare const isSameDay: (a: Date | null, b: Date | null) => boolean;
+export declare const isSameMonth: (a: Date | null, b: Date | null) => boolean;
+export declare const isSameYear: (a: Date | null, b: Date | null) => boolean;
+/** ISO-string based comparison; safe for `YYYY-MM-DD`. */
+export declare const compareISO: (a: string, b: string) => number;
+export type TCalendarCell = {
+    /** The day's `Date`. */
+    date: Date;
+    /** `YYYY-MM-DD` representation. */
+    iso: string;
+    /** `true` when the cell belongs to a month other than the current view. */
+    outside: boolean;
+};
+/**
+ * Build a 6x7 matrix for the given month starting on `firstDayOfWeek`.
+ * The matrix always has 42 cells so the calendar keeps a stable height.
+ *
+ * @param anchor         Any date within the target month.
+ * @param firstDayOfWeek 0 = Sunday, 1 = Monday, ...
+ */
+export declare const buildMonthMatrix: (anchor: Date, firstDayOfWeek: number) => TCalendarCell[][];
+/**
+ * Given any year, return the anchor year of the decade grid.
+ *
+ * The reference image shows a grid like `2016 – 2027` containing the current
+ * year (`2026`). We anchor the grid so the "round" decade start (e.g. 2020,
+ * 2010, ...) appears at index 1 - i.e. one extra year before the decade and
+ * one extra year after, filling the 3x4 grid cleanly.
+ */
+export declare const getDecadeStart: (year: number) => number;
+/**
+ * Build the 12-year decade grid for the year that contains `anchor`.
+ * Returns `{ start, end, years }` where `years.length === DECADE_GRID_SIZE`.
+ */
+export declare const buildDecade: (anchor: Date) => {
+    start: number;
+    end: number;
+    years: number[];
+};
+/**
+ * Clamp a `Date` between an optional min and max. Bounds may be at any
+ * ISO precision (`YYYY`, `YYYY-MM`, `YYYY-MM-DD`) and are padded to the
+ * widest matching day before comparing (`min` → first day, `max` → last day).
+ */
+export declare const clampDate: (date: Date, minISO?: string, maxISO?: string) => Date;
+/** Whether the given `Date` is within `[min, max]` ISO bounds (inclusive). */
+export declare const isWithinBounds: (date: Date, minISO?: string, maxISO?: string) => boolean;
+/** Sort two ISO strings and return `[start, end]`. */
+export declare const sortRange: (a: string, b: string) => [string, string];

package/dist/types/components/date-picker/helper/constants.d.ts

@@ -1,18 +1,64 @@
-import { ISO_DATE_LOCALE } from '../../../shared/utils/date';
 /** Default fallback input ID */
-declare const DEFAULT_INPUT_ID = "date-picker";
-/** Calendar month shadow DOM parts for common elements */
-declare const CALENDAR_COMMON_EXPORT_PARTS = "calendar__heading,calendar__table,calendar__tr,calendar__head,calendar__week,calendar__th,calendar__td";
-/** Calendar month shadow DOM parts for button elements */
-declare const CALENDAR_BUTTON_EXPORT_PARTS = "calendar__button,calendar__day,calendar__selected,calendar__today,calendar__disallowed,calendar__outside,calendar__range-start,calendar__range-end,calendar__range-inner";
-/** Combined export parts for calendar-month component */
-declare const CALENDAR_MONTH_EXPORT_PARTS = "calendar__heading,calendar__table,calendar__tr,calendar__head,calendar__week,calendar__th,calendar__td,calendar__button,calendar__day,calendar__selected,calendar__today,calendar__disallowed,calendar__outside,calendar__range-start,calendar__range-end,calendar__range-inner";
-/** Export parts for the calendar container component (calendar-date, calendar-range, calendar-multi) */
-declare const CALENDAR_CONTAINER_EXPORT_PARTS = "container:calendar__container,header:calendar__header,button:calendar__button,previous:calendar__previous,next:calendar__next,disabled:calendar__disabled,heading:calendar__heading";
-/** Maps picker type to Cally component tag name */
-declare const CALENDAR_TYPE_MAP: {
-    readonly single: "calendar-date";
-    readonly multi: "calendar-multi";
-    readonly range: "calendar-range";
+export declare const DEFAULT_INPUT_ID = "date-picker";
+/** Default aria labels used by the calendar navigation */
+export declare const DEFAULT_ARIA_LABELS: {
+    readonly previousMonth: "Previous month";
+    readonly nextMonth: "Next month";
+    readonly previousYear: "Previous year";
+    readonly nextYear: "Next year";
+    readonly previousDecade: "Previous decade";
+    readonly nextDecade: "Next decade";
+    readonly chooseMonth: "Choose month";
+    readonly chooseYear: "Choose year";
+    readonly chooseDate: "Choose date";
 };
-export { CALENDAR_BUTTON_EXPORT_PARTS, CALENDAR_COMMON_EXPORT_PARTS, CALENDAR_CONTAINER_EXPORT_PARTS, CALENDAR_MONTH_EXPORT_PARTS, CALENDAR_TYPE_MAP, DEFAULT_INPUT_ID, ISO_DATE_LOCALE, };
+/**
+ * Shadow DOM parts exposed by the component.
+ * Kept as a single list so it is easy to audit against the JSDoc @part list.
+ */
+export declare const CALENDAR_PARTS: {
+    readonly base: "base";
+    readonly label: "label";
+    readonly control: "control";
+    readonly prefix: "prefix";
+    readonly suffix: "suffix";
+    readonly input: "input";
+    readonly clearBtn: "clear-btn";
+    readonly button: "button";
+    readonly panel: "panel";
+    readonly container: "calendar__container";
+    readonly header: "calendar__header";
+    readonly heading: "calendar__heading";
+    readonly previous: "calendar__previous";
+    readonly next: "calendar__next";
+    readonly table: "calendar__table";
+    readonly head: "calendar__head";
+    readonly tr: "calendar__tr";
+    readonly th: "calendar__th";
+    readonly week: "calendar__week";
+    readonly td: "calendar__td";
+    readonly day: "calendar__day";
+    readonly today: "calendar__today";
+    readonly selected: "calendar__selected";
+    readonly outside: "calendar__outside";
+    readonly disallowed: "calendar__disallowed";
+    readonly disabled: "calendar__disabled";
+    readonly rangeStart: "calendar__range-start";
+    readonly rangeEnd: "calendar__range-end";
+    readonly rangeInner: "calendar__range-inner";
+    readonly months: "calendar__months";
+    readonly month: "calendar__month";
+    readonly monthSelected: "calendar__month-selected";
+    readonly years: "calendar__years";
+    readonly year: "calendar__year";
+    readonly yearSelected: "calendar__year-selected";
+    readonly calendarTrigger: "calendar-trigger";
+};
+/** Number of years shown in the decade view grid. Uses 12 to fill a 3x4 grid. */
+export declare const DECADE_GRID_SIZE = 12;
+/**
+ * Maximum number of month panels rendered side-by-side. Range pickers only
+ * benefit from up to 2 panels — beyond that the popover overflows most
+ * viewports and roving keyboard navigation becomes confusing.
+ */
+export declare const MAX_MONTHS_PER_VIEW = 2;

package/dist/types/components/date-picker/helper/input.d.ts

@@ -0,0 +1,23 @@
+import type { TDatePrecision } from '../bq-date-picker.types';
+/**
+ * Result of parsing user-typed input.
+ * - `value` is set when parsing succeeded — always at the configured precision.
+ * - `invalid: true` when the string could not be parsed or `isDateDisallowed`
+ *   rejected the result.
+ */
+export type TParsedInput = {
+    value?: string;
+    invalid?: boolean;
+};
+/**
+ * Precision-aware, bounds-aware parser for the trigger input field.
+ * Returns the parsed date as a wire-format string at the configured
+ * precision, clamped against `min`/`max`, or `{ invalid: true }` on failure.
+ */
+export declare const parseTypedInput: (text: string, locale: Intl.LocalesArgument, precision: TDatePrecision, min?: string, max?: string, isDateDisallowed?: (date: Date) => boolean) => TParsedInput;
+/**
+ * Lexically clamp a full `YYYY-MM-DD` ISO date to precision-padded bounds.
+ * Coarser bounds (`YYYY`, `YYYY-MM`) are padded to the widest matching day
+ * before comparing.
+ */
+export declare const clampISO: (iso: string, min?: string, max?: string) => string;

package/dist/types/components/date-picker/helper/intl.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cached `Intl.DateTimeFormat` factories.
+ *
+ * The Intl API is powerful but relatively expensive to instantiate. Since the
+ * calendar re-renders on every user interaction we keep a small LRU-ish cache
+ * keyed by locale + option shape.
+ */
+/**
+ * Format a full date, e.g. "1 January 2026".
+ */
+export declare const formatDate: (date: Date, locale: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions) => string;
+/**
+ * Format a month, e.g. "January 2026" or "Jan".
+ */
+export declare const formatMonth: (date: Date, locale: Intl.LocalesArgument, monthStyle?: "long" | "short" | "narrow", includeYear?: boolean) => string;
+/**
+ * Format a year, e.g. "2026".
+ */
+export declare const formatYear: (date: Date, locale: Intl.LocalesArgument) => string;
+/**
+ * Returns the weekday names for the given locale ordered from `firstDayOfWeek`.
+ *
+ * @param locale        The locale used for formatting.
+ * @param firstDayOfWeek The first day of the week (0 = Sunday, 1 = Monday, ...).
+ * @param style         Weekday style (long, short, narrow).
+ * @returns             An array of `{short, long}` names in display order.
+ */
+export declare const getWeekdayNames: (locale: Intl.LocalesArgument, firstDayOfWeek: number, style?: "long" | "short" | "narrow") => Array<{
+    short: string;
+    long: string;
+}>;
+/**
+ * Returns the localized month names.
+ *
+ * @param locale The locale used for formatting.
+ * @param style  Month style (long, short, narrow).
+ */
+export declare const getMonthNames: (locale: Intl.LocalesArgument, style?: "long" | "short" | "narrow") => string[];

package/dist/types/components/date-picker/helper/labels.d.ts

@@ -0,0 +1,29 @@
+import type { TCalendarView, TDatePrecision } from '../bq-date-picker.types';
+interface HeaderLabelArgs {
+    view: TCalendarView;
+    viewDate: Date;
+    focusedYear: number;
+    decadeStart: number;
+    monthCount: number;
+    locale: Intl.LocalesArgument;
+}
+/**
+ * Builds the label shown in the calendar header title button.
+ *
+ * - `days`: localized "Month Year" for a single panel, or "StartYear – EndYear"
+ *   when several months are visible at once.
+ * - `months`: the localized year currently in focus.
+ * - `years`: the closed range spanning the visible decade.
+ */
+export declare const getHeaderLabel: ({ view, viewDate, focusedYear, decadeStart, monthCount, locale, }: HeaderLabelArgs) => string;
+/**
+ * Aria label announcing what clicking the title switches to.
+ * Views cycle days → months → years → back to the base view (days for
+ * `precision="day"`, months for `precision="month"`).
+ */
+export declare const getHeaderTitleLabel: (view: TCalendarView, precision?: TDatePrecision) => string;
+/** Aria label for the "previous" navigation button, per view. */
+export declare const getPreviousLabel: (view: TCalendarView) => string;
+/** Aria label for the "next" navigation button, per view. */
+export declare const getNextLabel: (view: TCalendarView) => string;
+export {};

package/dist/types/components/date-picker/helper/navigation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Advances a focused month cursor by `delta` months, carrying over to the
+ * previous or next year as needed. Pure — accepts and returns primitives so
+ * it can be unit-tested and reused by keyboard handlers.
+ */
+export declare const advanceFocusedMonth: (focusedMonth: number, focusedYear: number, delta: number) => {
+    month: number;
+    year: number;
+};
+/**
+ * Advances a focused year cursor by `delta` years, sliding the visible
+ * decade grid so the focused year always stays in view.
+ */
+export declare const advanceFocusedYear: (focusedYear: number, decadeStart: number, delta: number) => {
+    year: number;
+    decadeStart: number;
+};
+/**
+ * Number of columns used to render the months/years grids. The grids widen
+ * from 3 → 4 columns when multiple months are visible, so vertical arrow
+ * navigation stride must match.
+ */
+export declare const getGridColumns: (monthCount: number) => number;

package/dist/types/components/date-picker/helper/selection.d.ts

@@ -0,0 +1,44 @@
+import type { TDatePickerType, TDatePrecision, TSelection } from '../bq-date-picker.types';
+/**
+ * Parse a raw `value` string into an internal `TSelection` array.
+ *
+ * Wire format:
+ * - single: `YYYY-MM-DD` (or `YYYY-MM` / `YYYY` at coarser precision)
+ * - multi:  space-separated tokens
+ * - range:  `<start>/<end>`
+ *
+ * Internally the selection is always stored as full `YYYY-MM-DD` — month
+ * precision expands to the first day of the month; year precision to Jan 1st.
+ *
+ * Invalid tokens (malformed strings, impossible dates like `2026-99-99`,
+ * non-ISO input) are silently discarded — the returned selection is
+ * guaranteed to contain only valid ISO-8601 dates.
+ */
+export declare const parseValue: (value: string | undefined | null, type: TDatePickerType, precision?: TDatePrecision) => TSelection;
+/**
+ * Serialize an internal `TSelection` array back to the wire format.
+ * Truncates each entry to the precision's ISO shape.
+ */
+export declare const serializeValue: (selection: TSelection, type: TDatePickerType, precision?: TDatePrecision) => string;
+/** Whether the given ISO day is included in the selection. */
+export declare const isSelected: (iso: string, selection: TSelection, type: TDatePickerType) => boolean;
+/** Whether the ISO day is the start of a range selection. */
+export declare const isRangeStart: (iso: string, selection: TSelection, type: TDatePickerType) => boolean;
+/** Whether the ISO day is the end of a range selection. */
+export declare const isRangeEnd: (iso: string, selection: TSelection, type: TDatePickerType) => boolean;
+/** Whether the ISO day sits strictly inside the range (not start/end). */
+export declare const isRangeInner: (iso: string, selection: TSelection, type: TDatePickerType) => boolean;
+/**
+ * Apply a click on `iso` and return the next selection.
+ *
+ * - single: always replace.
+ * - multi:  toggle (add if missing, remove if present).
+ * - range:  if there is no start OR a full range exists, start a new range;
+ *           otherwise complete the range (auto-sorted).
+ */
+export declare const applySelection: (iso: string, selection: TSelection, type: TDatePickerType) => TSelection;
+/**
+ * Build the highlighted range while the user is hovering with an in-progress
+ * range selection (`tentative` = the pending start).
+ */
+export declare const buildTentativeRange: (tentative: string | undefined, hovered: string | undefined) => TSelection;

package/dist/types/components/date-picker/helper/value.d.ts

@@ -0,0 +1,31 @@
+import type { TDatePickerType, TDatePrecision } from '../bq-date-picker.types';
+/**
+ * Normalizes a raw public `value` string against the current picker `type`
+ * and `precision`.
+ *
+ * Runs the value through `parseValue`/`serializeValue` so any invalid ISO
+ * tokens are dropped before the value ever reaches the form, the display
+ * input, or the visible selection. Returns `undefined` when normalization
+ * leaves an empty string, so callers can distinguish "no value" from "empty
+ * string value".
+ */
+export declare const normalizeValue: (raw: string | undefined, type: TDatePickerType, precision?: TDatePrecision) => string | undefined;
+/** Whether a value string is present and non-empty — used to drive UI affordances. */
+export declare const computeHasValue: (value: string | undefined) => boolean;
+/**
+ * Formats the current value for display in the trigger input. Thin wrapper
+ * around `formatDisplayValue` that accepts `undefined` and coerces to an
+ * empty string, so callers don't have to repeat the null check.
+ *
+ * Precision-agnostic: internally the selection is stored as full ISO dates
+ * (the first day of the month / January 1st for coarser precisions), so
+ * `Intl.DateTimeFormat(locale, formatOptions)` produces the right label
+ * whether the user asked for `{ year: 'numeric' }` or `{ dateStyle: 'full' }`.
+ */
+export declare const computeDisplayDate: (value: string | undefined, type: TDatePickerType, locale: Intl.LocalesArgument, formatOptions: Intl.DateTimeFormatOptions, precision?: TDatePrecision) => string | undefined;
+/**
+ * Default `Intl.DateTimeFormat` options per precision.
+ * Applied when the consumer hasn't explicitly overridden `formatOptions`, so
+ * a `precision="month"` picker doesn't show "1 May 2026".
+ */
+export declare const DEFAULT_FORMAT_OPTIONS_BY_PRECISION: Record<TDatePrecision, Intl.DateTimeFormatOptions>;

package/dist/types/components/input/bq-input.d.ts

@@ -192,6 +192,7 @@ export declare class BqInput {
     /** The input value, it can be used to reset the input to a previous value */
     value: TInputValue;
     handleValueChange(): void;
+    handleRequiredPropChange(): void;
     /** Callback handler emitted when the input loses focus */
     bqBlur: EventEmitter<HTMLBqInputElement>;
     /**