@pine-ds/core 4.2.0 → 4.4.0

package/dist/types/components/pds-chip/pds-chip.d.ts

@@ -3,6 +3,8 @@ import type { ChipSentimentType, ChipSizeType, ChipVariantType } from "../../uti
 /**
  * @slot (default) - The chip's label text.
  * @part button
+ * @part dot - Exposes the dot for styling, such as a custom color. Appears only when `dot` is set.
+ * @part icon - Exposes the icon component for styling, such as a custom color. Appears only when `icon` is set.
  */
 export declare class PdsChip {
     el: HTMLPdsChipElement;
@@ -21,10 +23,20 @@ export declare class PdsChip {
      * @defaultValue false
      */
     dot: boolean;
+    /**
+     * Sets the dot color. Accepts a sentiment name other than `brand` (e.g. `success`), a color token, or a [valid color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+     * Defaults to the dot color of the chip's sentiment. Only applies when `dot` is set.
+     */
+    dotColor?: string;
     /**
      * The name of the icon to display before the chip text.
      */
     icon?: string;
+    /**
+     * Sets the icon color. Accepts a sentiment name other than `brand` (e.g. `success`), a color token, or a [valid color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+     * Defaults to the chip's text color. Only applies when `icon` is set.
+     */
+    iconColor?: string;
     /**
      * Sets the size of the chip.
      * @defaultValue 'md'

package/dist/types/components/pds-combobox/combobox-interface.d.ts

@@ -1,6 +1,23 @@
 export interface ComboboxOption {
     id: string | number;
     text: string;
+    /**
+     * Label of the group this option belongs to. Options sharing a group are rendered together
+     * under one group label, where the group first appears, the same as slotted `<optgroup>`
+     * markup. Options without a group are listed before every group.
+     */
+    group?: string;
+    /**
+     * Pine icon name shown beside the group's label (letters, digits and hyphens, for example
+     * `hashtag`); URLs and file paths are not accepted. The first option in the group that sets
+     * one wins, the same as `data-icon` on a slotted `<optgroup>`.
+     */
+    groupIcon?: string;
+    /**
+     * When `true`, the option stays reachable by the arrow keys and the pointer, so assistive tech
+     * announces it as unavailable, but it cannot be selected.
+     */
+    disabled?: boolean;
     [key: string]: unknown;
 }
 export interface ComboboxChangeEventDetail {

package/dist/types/components/pds-combobox/grouped-options-panel.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Internal to Pine: the grouped panel behind `pds-combobox`'s `group-display` modes. It owns the
+ * group model, hover intent and flyout positioning; the combobox owns rendering and selection,
+ * so options keep the indexes its click, hover and keyboard handlers already use.
+ */
+/** An option in the panel, with its index among the combobox's selectable options. */
+export interface PanelOption {
+    option: HTMLOptionElement;
+    index: number;
+}
+export interface PanelGroup {
+    /** The group's identity: two optgroups may share a label. */
+    optgroup: HTMLOptGroupElement;
+    label: string;
+    /** Pine icon name from the optgroup's `data-icon`, or null. */
+    icon: string | null;
+    options: PanelOption[];
+}
+export type PanelEntry = {
+    kind: 'group';
+    group: PanelGroup;
+} | ({
+    kind: 'option';
+} & PanelOption);
+/** The optgroup an option sits in, or null for an ungrouped option. */
+export declare function parentOptgroupOf(option: HTMLOptionElement | null | undefined): HTMLOptGroupElement | null;
+/**
+ * An optgroup's `data-icon` when it's a Pine icon name, or null. One definition of a usable group
+ * icon for every mode, checked here rather than trusting `pds-icon` to reject anything else; it is
+ * only ever passed to `pds-icon` as `name`.
+ */
+export declare function groupIconOf(optgroup: HTMLOptGroupElement): string | null;
+/** An option is disabled by its own `disabled` or its optgroup's, as in a native select. */
+export declare function isOptionDisabled(option: HTMLOptionElement | null | undefined): boolean;
+/** A group with no option left to choose. It still opens, so its options can be seen. */
+export declare function isGroupDisabled(group: PanelGroup): boolean;
+/**
+ * Groups the combobox's filtered items for the panel: each optgroup becomes one entry holding its
+ * options, and ungrouped options stay where they are. Indexes count options in list order, the
+ * same as the inline listbox, so `data-option-index` means the same thing in every mode.
+ */
+export declare function buildPanelEntries(items: Element[]): PanelEntry[];
+/** The label of the optgroup an option sits in, or null for an ungrouped option. */
+export declare function groupLabelOf(option: HTMLOptionElement | null | undefined): string | null;
+/** Where the keyboard is in the grouped panel: a group's row, or an option by its index. */
+export type PanelItem = HTMLOptGroupElement | number;
+/**
+ * The items Up and Down move through from `current`, one tree level at a time: the panel's rows
+ * (groups and ungrouped options), or the open group's options. Drilled into a group, its row
+ * (drawn as the row back) comes first, above its options, as a tree draws a parent above its children.
+ * Disabled options and groups stay in it, as the APG listbox and tree patterns advise, so they're
+ * announced as unavailable rather than hidden from the keyboard.
+ */
+export declare function panelColumn(entries: PanelEntry[], openGroup: HTMLOptGroupElement | null, current: PanelItem | null, drilledIn: boolean): PanelItem[];
+/** The panel's group for an optgroup, if it's showing. */
+export declare function findGroup(entries: PanelEntry[], optgroup: HTMLOptGroupElement): PanelGroup | undefined;
+/**
+ * Opens and closes a group's flyout with hover intent, and keeps the open flyout positioned beside
+ * its group row. The flyout renders inside the row, so moving the pointer into it never leaves
+ * the row; the delays cover the gap between panel and flyout and diagonal moves across rows.
+ */
+/**
+ * Scrolls `el` into view inside `container` only. A flyout option needs this: the flyout is `fixed`
+ * beside the panel but sits inside it in the DOM, so `scrollIntoView` would also scroll the panel
+ * and the page, moving the flyout's row out from under it.
+ */
+export declare function scrollIntoViewWithin(container: HTMLElement, el: HTMLElement): void;
+export declare class FlyoutController<T> {
+    private readonly getOpenGroup;
+    private readonly setOpenGroup;
+    private switchTimer?;
+    private closeTimer?;
+    private stopAutoUpdate?;
+    private positionedFlyout?;
+    /** An option to scroll into view once the flyout is placed and its height capped. */
+    private pendingReveal?;
+    constructor(getOpenGroup: () => T | null, setOpenGroup: (group: T | null) => void);
+    /** Pointer entered a group row (or its flyout, which sits inside it). */
+    enter(label: T): void;
+    /** Pointer left a group row and its flyout. */
+    leave(label: T): void;
+    /**
+     * A click or tap on a group row opens it. It never closes it: on desktop the hover that preceded
+     * the click has already opened it, and touch browsers fire an emulated mouseenter and then click
+     * in the same tap. Closing happens on leaving the row or closing the panel.
+     */
+    open(label: T): void;
+    /**
+     * Keeps `flyout` beside `row`: horizontally against the panel's edge, vertically so its first
+     * option lines up with the row. `fixed` positioning so the panel's scrolling can't clip it,
+     * including when the panel is portaled into a dialog.
+     */
+    position(row: HTMLElement, panel: HTMLElement, flyout: HTMLElement): void;
+    /**
+     * Scrolls `option` into view inside its flyout. Before the flyout's first placement its height
+     * isn't capped yet, so the option looks visible; it's revealed again once the placement lands.
+     */
+    reveal(flyout: HTMLElement, option: HTMLElement): void;
+    stopPositioning(): void;
+    /** The panel closed or the component left the page. */
+    reset(): void;
+    private clearTimers;
+    private clearSwitch;
+    private clearClose;
+}

package/dist/types/components/pds-combobox/pds-combobox.d.ts

@@ -62,6 +62,35 @@ export declare class PdsCombobox implements BasePdsProps {
      * @default 'host'
      */
     dropdownMount: 'host' | 'body';
+    /**
+     * Accessible prefix for the row that returns to the group list when `group-display` is
+     * `drill-in`, read before the open group's label. Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Back'
+     */
+    drillInBackLabel: string;
+    /**
+     * Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value.
+     * @default '380px'
+     */
+    flyoutMaxWidth: string;
+    /**
+     * Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value.
+     * The flyout is as wide as its options, between this and `flyout-max-width`.
+     * @default '280px'
+     */
+    flyoutMinWidth: string;
+    /**
+     * How option groups (`<optgroup>`, or the `group` field of `options`) are shown in the dropdown.
+     * `inline` lists each group's label above its options. `flyout` lists the groups, and opens a
+     * group's options in a panel beside it on hover or click; while searching, the matching options
+     * are listed under their group labels, and search also matches group labels. `flyout` groups
+     * by `<optgroup>` (or `group`) only: options under a `<pds-text>` heading are listed ungrouped.
+     * `drill-in` lists the groups too, but a click replaces the list with that group's options and a
+     * row back to the groups; use it where nothing can open beside the dropdown, such as a side
+     * panel. `flyout` falls back to `drill-in` when there is no room for a flyout on either side.
+     * @default 'inline'
+     */
+    groupDisplay: 'inline' | 'flyout' | 'drill-in';
     /**
      * Helper message to display below the combobox.
      */
@@ -92,10 +121,27 @@ export declare class PdsCombobox implements BasePdsProps {
      * @default 'filter'
      */
     mode: 'filter' | 'select-only';
+    /**
+     * Shows a search field at the top of the dropdown for the `button` and `chip` triggers, which
+     * can't be typed into. Search filters the options the same way typing in the `input` trigger
+     * does; in a grouped display it also matches group labels.
+     * @default false
+     */
+    panelSearch: boolean;
     /**
      * Placeholder text for the input field.
      */
     placeholder?: string;
+    /**
+     * Accessible label for the search input inside the dropdown panel (`panel-search`). Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Search options'
+     */
+    searchOptionsLabel: string;
+    /**
+     * Placeholder text for the search input inside the dropdown panel (`panel-search`). Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Find...'
+     */
+    searchPlaceholder: string;
     /**
      * Determines the combobox trigger: 'input' (editable input), 'button' (button-like, non-editable), or 'chip' (chip-like, non-editable).
      * @default 'input'
@@ -198,6 +244,30 @@ export declare class PdsCombobox implements BasePdsProps {
      * Internal state for dropdown open/close
      */
     isOpen: boolean;
+    /**
+     * The optgroup whose flyout is open, when `groupDisplay` is `flyout`.
+     */
+    openGroup: HTMLOptGroupElement | null;
+    /**
+     * Which way drill-in just moved, so the list slides that way: `in` to a group, `out` back to the
+     * groups. Cleared once the slide ends, so later renders don't animate.
+     */
+    drillDirection: 'in' | 'out' | null;
+    /**
+     * The group row highlighted in the grouped panel. It counts only while no option is
+     * highlighted (`highlightedIndex` is -1); see `highlightedGroupRow`.
+     */
+    highlightedGroup: HTMLOptGroupElement | null;
+    /** The keys, not the pointer, moved the highlight last; the focus ring shows only then. */
+    keyboardNavigating: boolean;
+    /**
+     * What's typed in the dropdown's own search field (`panelSearch`).
+     */
+    panelQuery: string;
+    /**
+     * `groupDisplay` is `flyout` but there's no room beside the dropdown, so groups drill in instead.
+     */
+    flyoutFallback: boolean;
     /**
      * Internal state for the currently selected option
      */
@@ -239,6 +309,21 @@ export declare class PdsCombobox implements BasePdsProps {
     private fetchTimeoutTimer?;
     private observer?;
     private originalSearchEmitter?;
+    private flyout;
+    /** The groups in the flyout panel's last render, so a row's index finds its optgroup. */
+    private renderedGroups;
+    private panelSearchEl?;
+    /** With panel search, the options' list, which takes focus while a group is drilled into. */
+    private panelTreeEl?;
+    /** What panel search last focused this open: the search field, or the list while drilled in. */
+    private panelFocusEl?;
+    /** Room for a flyout was checked for this open. */
+    private flyoutRoomChecked;
+    /** The highlighted option sits in a flyout that hasn't rendered yet; focus it after the next render. */
+    private pendingOptionFocus;
+    /** Group rows' DOM ids, stable across renders so `aria-activedescendant` can point at a row. */
+    private groupIds;
+    private groupIdCount;
     /**
      * In filter mode, after choosing an option the input still shows the label and would
      * otherwise filter the list to matching substrings only. While this flag is true,
@@ -250,16 +335,45 @@ export declare class PdsCombobox implements BasePdsProps {
     componentDidLoad(): void;
     disconnectedCallback(): void;
     componentDidRender(): void;
+    private focusPanel;
+    /** Switching display mode leaves no flyout or hover timer from the last one. */
+    protected groupDisplayChanged(): void;
+    protected openGroupChanged(next: HTMLOptGroupElement | null, previous: HTMLOptGroupElement | null): void;
+    /** A flyout with no room beside the dropdown drills in, which can hide the focused search field too. */
+    protected flyoutFallbackChanged(): void;
+    /**
+     * Drilling into a group hides the search field, so focus moves to the list before the field
+     * unmounts: focus lost with it would leave the combobox and close the dropdown.
+     */
+    private handPanelFocusToList;
+    private onDrillAnimationEnd;
     protected isOpenChanged(isOpen: boolean): void;
     private get usesBodyPortal();
+    private get labelId();
+    /** One check for "the `<label>` is rendered", so the label and the reference to it can't disagree. */
+    private get hasVisibleLabel();
+    /**
+     * The button and chip triggers are `div`s, which `<label for>` can't name, so they point at the
+     * visible label instead. With `hide-label` there is no visible label and `aria-label` names them.
+     * With panel search the trigger is a button, which has no value, so its own text (the selection
+     * or placeholder) joins the label in its name.
+     */
+    private get triggerLabelledBy();
+    /** The div triggers' `aria-label` when the label is hidden; with panel search it names the selection too. */
+    private get triggerAriaLabel();
+    /** `<label for>` only works on the input trigger; for a div trigger a click on the label focuses it. */
+    private onLabelClick;
     private get listboxId();
     private optionDomId;
+    private groupDomId;
     protected setupDebounce(): void;
     protected optionsChanged(): void;
     handleValueChange(): void;
     handleSelectedOptionChange(): void;
     private updateFormValue;
     private clearAsyncFetchState;
+    /** The query behind the options loaded from `async-url`. */
+    private lastFetchedQuery;
     private debouncedFetchAsyncOptions;
     private fetchOptions;
     private updateOptionsFromAsync;
@@ -280,6 +394,11 @@ export declare class PdsCombobox implements BasePdsProps {
      */
     private prepareExpandFilterListOnOpen;
     private positionDropdown;
+    /**
+     * Once per open, after the dropdown is placed: with no room for a flyout on either side of it,
+     * `flyout` drills in instead. `flyout-min-width` is resolved through CSS, so any length works.
+     */
+    private checkFlyoutRoom;
     private openDropdownPositioning;
     private startBodyPortalAutoUpdate;
     private stopBodyPortalAutoUpdate;
@@ -297,13 +416,37 @@ export declare class PdsCombobox implements BasePdsProps {
     private handleInput;
     private handleInputClick;
     private handleKeyDown;
+    /**
+     * The tree keys in the grouped panel. Up, Down, Home, End, PageUp and PageDown move within one
+     * level; Right, Enter or Space opens a group at its first option; Left, or Escape, closes the
+     * open group back to its row. Returns false for keys the listbox handling covers, such as
+     * Enter on an option.
+     */
+    private handleGroupedPanelKey;
+    /**
+     * Where the keyboard is in the grouped panel. An option highlighted in a group that has since
+     * closed (the pointer left its flyout) counts as its group's row, so the keys carry on from
+     * what's showing rather than from an option that isn't.
+     */
+    private currentPanelItem;
+    /**
+     * Highlights the option at `index`, kept within the list. Disabled options can be highlighted,
+     * so assistive tech announces them as unavailable, but not chosen.
+     */
+    private highlightOptionAt;
+    /** Highlights a group row or an option, opening or closing flyouts to match. */
+    private highlightPanelItem;
+    private expandGroup;
+    /** Closes the open group and highlights its row, as a tree's Left does from a child. */
+    private collapseToGroup;
     /**
      * Sets focus on the native input element.
      */
     setFocus(): Promise<void>;
     /**
-     * Sets the initial highlighted index when dropdown opens.
-     * If there's a selected option, highlight it. Otherwise, highlight the first option.
+     * Sets the initial highlighted index when dropdown opens. Highlights the selected option unless
+     * it's disabled. Otherwise highlights the first enabled option, or, in the grouped panel, the
+     * first row with something to choose, or nothing when every option is disabled.
      */
     private setInitialHighlightedIndex;
     /**
@@ -320,9 +463,15 @@ export declare class PdsCombobox implements BasePdsProps {
      * Note: We don't actually focus the option to prevent focusout events that close the dropdown
      */
     private updateOptionFocus;
+    /** The highlighted group row in the grouped panel, or null while an option is highlighted. */
+    private get highlightedGroupRow();
     /**
-     * Updates aria-activedescendant on the trigger element
+     * The id of the highlighted option or group row, only while it's rendered. In the flyout panel
+     * an option in a closed group isn't in the DOM, and drilled into a group the other groups' rows
+     * aren't; `aria-activedescendant` must not point at a missing element.
      */
+    private get activeDescendantId();
+    /** Points the focused element's aria-activedescendant at the highlighted option, or clears it. */
     private updateAriaActiveDescendant;
     /**
      * Focus management helper - restores focus to the trigger element
@@ -338,6 +487,13 @@ export declare class PdsCombobox implements BasePdsProps {
     clear(): Promise<void>;
     private onOptionClick;
     private onOptionMouseEnter;
+    private groupFromEvent;
+    private onGroupRowMouseEnter;
+    private onGroupRowMouseLeave;
+    private onGroupRowTriggerMouseEnter;
+    private onGroupBackMouseEnter;
+    private highlightGroupRowByPointer;
+    private onGroupRowClick;
     private onOptionMouseDown;
     private onOptionKeyDown;
     private get selectedLabel();
@@ -348,12 +504,88 @@ export declare class PdsCombobox implements BasePdsProps {
     private get selectedChipIcon();
     private get selectedChipDot();
     private onButtonTriggerClick;
+    /**
+     * With `async-url`, fetches when the button trigger opens: the first page if nothing has loaded.
+     * The panel's search field opens empty, so results left from the last search are refetched for
+     * an empty query.
+     */
+    private fetchAsyncOptionsOnOpen;
     private onButtonTriggerKeyDown;
     private onButtonTriggerKeyUp;
     private onComboboxFocusOut;
     private handleOptionClick;
     private handleScroll;
     private renderDropdown;
+    private onPanelMouseDown;
+    /**
+     * The listbox's items. Each optgroup's options sit in a `group` named for it, as in
+     * `pds-multiselect`, so assistive tech announces the group on entering it; a `pds-text` label
+     * stays a caption above the options that follow it.
+     */
+    private renderListboxItems;
+    /** `panelSearch` applies to the triggers that can't be typed into. */
+    private get usesPanelSearch();
+    /** `groupDisplay`, with `flyout` drilling in when there's no room beside the dropdown. */
+    private get effectiveGroupDisplay();
+    /**
+     * The popup's role, for the triggers' `aria-haspopup`: a `tree` while the grouped panel shows
+     * groups, and a `listbox` of options otherwise, search results included.
+     */
+    private get popupRole();
+    /**
+     * The input trigger's `aria-haspopup`. While closed it names what opening shows: the full list,
+     * so the grouped panel in a grouped display, even though the input still holds the selection's
+     * label.
+     */
+    private get inputPopupRole();
+    /**
+     * The button and chip triggers' `aria-haspopup`. With panel search the trigger opens the panel,
+     * which starts as a tree in a grouped display, so typing in the panel doesn't change it.
+     */
+    private get triggerPopupRole();
+    /**
+     * Drilled into a group with panel search: the group's row back takes the search field's place,
+     * since one group's options don't need searching. Typing searches the whole list again.
+     */
+    private get hidesPanelSearch();
+    /** The grouped panel is showing groups rather than search results. */
+    private get showsGroupedPanel();
+    private onPanelSearchInput;
+    private setPanelQuery;
+    /** What's being searched: the panel's field, or the input trigger's text. */
+    private get activeQuery();
+    private onPanelSearchKeyDown;
+    /**
+     * Keys in the list while a drilled-in group hides the search field. Backspace, like ArrowLeft,
+     * steps back to the groups; a character starts a search of the whole list. Characters typed
+     * before the search field renders and takes focus still land on the list, so they add to the
+     * query rather than starting it again.
+     */
+    private onPanelTreeKeyDown;
+    private handlePanelTab;
+    /** Returns from a drilled-in group to the group list; false when not drilled in. */
+    private leaveDrilledInGroup;
+    private onGroupBackClick;
+    private renderPanelSearch;
+    /**
+     * An option, as a listbox `option` or, given a tree `level`, a `treeitem`. `posinset` and
+     * `setsize` place it among its siblings.
+     */
+    private renderOption;
+    /**
+     * `flyout`: one row per group, its options in a flyout beside it. `drill-in`: the same rows, and
+     * an opened group replaces them with its row, drawn as a row back, above its options. Either way
+     * it's a tree: the rows and ungrouped options are level 1, a group's options level 2.
+     */
+    private renderGroupedPanel;
+    /** A group's options, as its children in the tree. */
+    private renderGroupOptions;
+    /**
+     * Drilled into a group: its treeitem, expanded. Its row reads as a way back ("Back: Tag") and
+     * leads its options.
+     */
+    private renderGroupBackRow;
+    private renderGroupRow;
     private renderCaretIcon;
     private renderLayoutContent;
     private renderDefaultContent;

package/dist/types/components/pds-datepicker/calendar-portal.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Where the open calendar lives: a `div` in `document.body`, or in the nearest `<dialog>` so it
+ * shares a modal's top layer, outside any `overflow: hidden` or transformed ancestor that would
+ * clip or misplace a fixed-position popup. The portal has its own shadow root carrying the
+ * datepicker's styles, so the calendar looks the same there without any global CSS.
+ */
+export declare class CalendarPortal {
+    private readonly datepicker;
+    static readonly className = "pds-datepicker-calendar-portal";
+    readonly host: HTMLElement;
+    private readonly root;
+    private locale?;
+    /** The custom properties copyContext set on the host, cleared before it copies again. */
+    private copiedProperties;
+    constructor(datepicker: HTMLElement);
+    /**
+     * Moves the calendar into the portal, mounting the portal first. Context is copied when the portal
+     * is attached or the locale changes, not on every render while it's open (in range mode, every
+     * hovered day). A theme set on an ancestor while the calendar is open applies when it next opens.
+     */
+    mount(calendar: HTMLElement, locale: string): void;
+    remove(): void;
+    /** Whether a node is the portal or inside it, as a focus or pointer target. */
+    contains(node: Node | null): boolean;
+    /**
+     * Carries over what the calendar would otherwise inherit from the datepicker: its styles, the
+     * reading direction and language, a theme set on an ancestor, and size overrides.
+     */
+    private copyContext;
+    /**
+     * Custom properties set on an ancestor of the datepicker that isn't an ancestor of the portal,
+     * as a token override on a card or panel, or the datepicker's own size properties: each one whose
+     * value at the datepicker differs from where the portal mounts is set on the portal host.
+     */
+    private copyCustomProperties;
+}
+/**
+ * The native `<dialog>` or open `popover` (as pds-filter's) the datepicker sits in, so the
+ * calendar shares its top layer and a click in it isn't outside it; otherwise `document.body`.
+ * `closest()` stops at shadow boundaries and misses one that only wraps slotted content, so this
+ * walks assigned slots and shadow hosts, as pds-combobox does.
+ */
+export declare function findPortalTarget(from: HTMLElement): HTMLElement;

package/dist/types/components/pds-datepicker/date-utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Date-only helpers for pds-datepicker. Dates are `YYYY-MM-DD` strings and all arithmetic runs in
+ * UTC, so a date never shifts by a day with the viewer's time zone or a daylight-saving change.
+ */
+/** Parses a `YYYY-MM-DD` string to a UTC `Date`, or `null` when it isn't a real calendar date. */
+export declare function parseIsoDate(value: string | null | undefined): Date | null;
+export declare function toIsoDate(date: Date): string;
+/** Today in the viewer's time zone, as a UTC date. */
+export declare function today(): Date;
+export declare function addDays(date: Date, days: number): Date;
+/** Moves by whole months, keeping the day where it exists (Jan 31 + 1 month is Feb 28 or 29). */
+export declare function addMonths(date: Date, months: number): Date;
+export declare function daysInMonth(year: number, month: number): number;
+export declare function isSameDay(a: Date | null, b: Date | null): boolean;
+/** Clamps a date into the `[min, max]` range; either bound may be missing. */
+export declare function clampDate(date: Date, min: Date | null, max: Date | null): Date;
+export declare function isOutOfRange(date: Date, min: Date | null, max: Date | null): boolean;
+/** The column (0–6) a date falls in, for a week starting on `firstDayOfWeek` (0 = Sunday). */
+export declare function weekdayColumn(date: Date, firstDayOfWeek: number): number;
+/**
+ * The month's weeks, each seven cells long. Days from the neighbouring months are `null`, so the
+ * grid only offers dates in the month on view.
+ */
+export declare function monthWeeks(year: number, month: number, firstDayOfWeek: number): (Date | null)[][];
+/**
+ * The locale's first day of the week (0 = Sunday), from `Intl.Locale` week info where the browser
+ * has it. Falls back to Sunday.
+ */
+export declare function localeFirstDayOfWeek(locale: string): number;
+/**
+ * Weekday names, starting from `firstDayOfWeek`: a short form for the column heading and the long
+ * form for assistive tech. Latin-script names shorten to two letters (Su Mo, lu ma, Mo Di), as the
+ * admin date picker does, while the seven stay distinct; other scripts keep the locale's short form,
+ * which is already compact.
+ */
+export declare function weekdayNames(locale: string, firstDayOfWeek: number): {
+    short: string;
+    long: string;
+}[];
+/** The locale if the browser supports it, otherwise `en-US`, so a bad tag never throws while rendering. */
+export declare function supportedLocale(locale: string | null | undefined): string;
+/**
+ * A formatter for the UTC dates these helpers return. Build it once per render, not per day.
+ * Always on the Gregorian calendar the grid is laid out in, while keeping the locale's language and
+ * digits: some locales default to another calendar (Persian for `fa`, Buddhist for `th`).
+ */
+export declare function dateFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+export declare function formatDate(date: Date, locale: string, options: Intl.DateTimeFormatOptions): string;

package/dist/types/components/pds-datepicker/datepicker-interface.d.ts

@@ -0,0 +1,30 @@
+export interface DatepickerChangeEventDetail {
+    /**
+     * The selected date as `YYYY-MM-DD`, or in range mode the range as `YYYY-MM-DD/YYYY-MM-DD`; with
+     * the time picker, each date as `YYYY-MM-DDTHH:mm`. An empty string when cleared.
+     */
+    value: string;
+    /** Range mode: the first day of the range, `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` with the time picker. */
+    start?: string;
+    /** Range mode: the last day of the range, `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` with the time picker. */
+    end?: string;
+    /**
+     * Range mode: the key of the preset the range matches, such as `last-30-days`, so a filter can
+     * keep the range relative to today.
+     */
+    preset?: string;
+}
+export interface DatepickerPreset {
+    /**
+     * A built-in key (`today`, `yesterday`, `last-7-days`, `last-30-days`, `last-90-days`,
+     * `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-year`, `last-year`,
+     * `year-to-date`, `last-12-months`), or your own key when `start` and `end` are set.
+     */
+    key: string;
+    /** The text shown in the list. Built-in keys have English defaults; set it to translate them. */
+    label?: string;
+    /** For a preset of your own: its first day, `YYYY-MM-DD`. */
+    start?: string;
+    /** For a preset of your own: its last day, `YYYY-MM-DD`. */
+    end?: string;
+}