@pine-ds/core 5.0.0-mercury.0 → 5.0.0

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

@@ -1,41 +1,119 @@
+import { EventEmitter } from '../../stencil-public-runtime';
 /**
- * @part button - The main button element that represents the button component.
- * @part caret - The caret icon element that appears when the button variant is 'disclosure'.
- * @part icon - The icon element that appears before the text in the button, if provided.
+ * @part button - Exposes the underlying button (or anchor) element for styling, including custom size, shape, or surface on icon-only placements (e.g. a compact square or inverse icon button).
+ * @part button-content - Exposes the button content for styling.
+ * @part button-text - Exposes the button text for styling.
+ * @part caret - Exposes the caret icon component for styling. Appears only on the disclosure variant.
+ * @part icon - Exposes the icon component for styling.
+ * @part loader-svg - Exposes the loader SVG element for color customization. Appears only when loading.
+ * @slot (default) - Button text.
+ * @slot start - Content to display before the button text.
+ * @slot end - Content to display after the button text.
 */
 export declare class PdsButton {
     el: HTMLPdsButtonElement;
     /**
-     * A unique identifier used for the underlying component `id` attribute.
+     * A unique identifier for this component instance. Does not set the host element's `id` attribute — set `id` directly if you need one.
      */
     componentId: string;
     /**
-     * Toggles disabled state of button
+     * Prompts the user to save the linked URL instead of navigating to it.
+     * It can be used without a value to download with the default filename,
+     * or with a string value to suggest a specific filename for the download.
+     * Only applies when href is set.
+     */
+    download?: string;
+    /**
+     * Determines the button's disabled state.
+     * @defaultValue false
+     */
+    disabled: boolean;
+    /**
+     * Determines if the button should take up the full width of its container.
      * @defaultValue false
      */
-    disabled?: boolean;
+    fullWidth?: boolean;
     /**
-     * Displays icon before text when icon string matches an icon name
+     * If provided, renders the component as an anchor (`<a>`) element instead of a button.
+     * When using href, `type`, `name` and `value` are ignored, `loading` blocks navigation, and `disabled` removes the link's `href`.
+     */
+    href?: string;
+    /**
+     * Displays a leading icon in the button. DEPRECATED.
+     * @defaultValue null
+     * @deprecated Use `start` slot instead.
      */
     icon?: string;
     /**
-     * Provides button with a submittable name
+     * When true, displays only the icon and visually hides the text (keeping it accessible).
+     */
+    iconOnly?: boolean;
+    /**
+     * Determines if the button is in a loading state.
+     * When true, displays a loader and hides the button text.
+     * @defaultValue false
+     */
+    loading?: boolean;
+    /**
+     * Sets the `name` attribute of the inner button. Not included in submitted form data,
+     * because the form is submitted through a hidden button that carries only the `type`.
      */
     name?: string;
     /**
-     * Provides button with a submittable value
+     * Specifies where to open the linked document when href is provided.
+     * Only applies when href is set.
      */
-    value?: string;
+    target?: '_blank' | '_self' | '_parent' | '_top';
     /**
-     * Provides button with a type
+     * Provides button with a type.
      * @defaultValue button
      */
     type?: 'button' | 'reset' | 'submit';
     /**
-     * Sets button variant styles as outlined in Figma documentation
+     * Sets the `value` attribute of the inner button. Not included in submitted form data,
+     * because the form is submitted through a hidden button that carries only the `type`.
+     */
+    value?: string;
+    /**
+     * Sets the size of the button.
+     * @defaultValue default
+     */
+    size?: 'default' | 'small' | 'micro';
+    /**
+     * Sets the style variant of the button.
+     * @defaultValue primary
+     */
+    variant: 'primary' | 'secondary' | 'tertiary' | 'accent' | 'disclosure' | 'destructive' | 'unstyled' | 'filter';
+    hasStartContent: boolean;
+    hasEndContent: boolean;
+    forwardedAria: Record<string, string | null>;
+    private contentEl?;
+    private hostAriaObserver?;
+    /**
+     * Emitted when the button is clicked, including from the keyboard, carrying the native click event.
+     * Not emitted while the button is `disabled` or `loading`. In a form, a `submit` or `reset` button's `submit` or `reset` event fires
+     * before this one. A form that fails validation fires no `submit` event.
+     */
+    pdsClick: EventEmitter<Event>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    componentWillLoad(): void;
+    componentDidRender(): void;
+    /**
+     * Listen for Enter key presses on form inputs to trigger submit
      */
-    variant: 'primary' | 'secondary' | 'accent' | 'disclosure' | 'destructive' | 'unstyled';
+    handleFormKeyDown(event: KeyboardEvent): void;
+    private syncHostAria;
+    private forwardAriaReferences;
+    private handleFocusIn;
+    private hasSlottedElement;
+    private rendersStartSlot;
+    private rendersEndSlot;
+    private handleStartSlotChange;
+    private handleEndSlotChange;
     private handleClick;
     private classNames;
+    private renderStartContent;
+    private renderEndContent;
     render(): any;
 }

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

@@ -1,6 +1,15 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { CheckboxChangeEventDetail } from './checkbox-interface';
+/**
+ * @slot label - Content displayed as the checkbox label in place of the `label` text. Clicking it toggles the checkbox.
+ */
 export declare class PdsCheckbox {
+    private inheritedAttributes;
+    private internals?;
+    private readonly _type;
+    el: HTMLPdsCheckboxElement;
+    private hostKeeper;
+    private hasLabelSlot;
     /**
      * It determines whether or not the checkbox is checked.
      */
@@ -14,30 +23,30 @@ export declare class PdsCheckbox {
      */
     disabled: boolean;
     /**
-     * Displays message text describing an invalid state.
+     * Displays an error message below the checkbox. It becomes the checkbox's accessible description only while `invalid` is set.
      */
     errorMessage: string;
     /**
-     * String used for helper message below checkbox.
+     * Displays a message or hint below the checkbox.
      */
     helperMessage: string;
     /**
-     * If `true`, the checkbox will visually appear as indeterminate.
-     * Only JavaScript can set the objects `indeterminate` property. See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes).
+     * Shows the checkbox as indeterminate, for a checkbox whose group is only partly selected. It's exposed to screen readers as mixed.
+     * Changing `checked` clears it. Has no visual style when `variant` is `pill`.
      */
     indeterminate: boolean;
     /**
-     * It determines whether or not the checkbox is invalid.
+     * Determines whether or not the checkbox is invalid.
      */
     invalid: boolean;
     /**
-     * String used for label text next to checkbox.
+     * Text to be displayed as the checkbox label.
      */
     label: string;
     /**
-   * Visually hides the label text for instances where only the checkbox should be displayed. Label remains accessible to assistive technology such as screen readers.
+   * Visually hides the label text for instances where only the checkbox should be displayed. Label remains accessible to assistive technology such as screen readers. Ignored when `variant` is `pill`.
    */
-    labelHidden: boolean;
+    hideLabel: boolean;
     /**
      * String used for checkbox `name` attribute.
      */
@@ -51,13 +60,38 @@ export declare class PdsCheckbox {
      */
     value: string;
     /**
-     * Event emitted that contains the `value` and `checked`.
+     * Sets the style variant of the checkbox. `pill` renders the label as a pill-shaped choice; the native input still handles keyboard, form, and screen reader behavior.
+     * @defaultValue default
+     */
+    variant: 'default' | 'pill';
+    /**
+     * Emitted when the user toggles the checkbox, by a click or `Space`, carrying the `value` and the new `checked` state.
+     *
+     * This event will not emit when programmatically setting the `checked` property.
      */
     pdsCheckboxChange: EventEmitter<CheckboxChangeEventDetail>;
+    /**
+     * Emitted when the user toggles the checkbox, just before `pdsCheckboxChange`, carrying the `value` and `checked`.
+     * `checked` is still the state from before the toggle, so read the new state from `pdsCheckboxChange`.
+     *
+     * This event will not emit when programmatically setting the `checked` property.
+     */
     pdsCheckboxInput: EventEmitter<CheckboxChangeEventDetail>;
     updateIndeterminate(): void;
     private handleCheckboxChange;
     private handleInput;
     private classNames;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    componentDidLoad(): void;
+    checkedChanged(): void;
+    private updateFormValue;
+    formStateRestoreCallback(state: string | FormData | null): void;
+    /**
+     * Form Associated Custom Elements API: Called when the form is disabled
+     */
+    formDisabledCallback(disabled: boolean): void;
+    componentWillLoad(): void;
+    private updateHasLabelSlot;
     render(): any;
 }

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

@@ -1,39 +1,102 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+import type { ChipSentimentType, ChipSizeType, ChipVariantType } from "../../utils/types";
+/**
+ * @slot (default) - The chip's label text.
+ * @part button - Exposes the trigger button for styling. Appears only on the dropdown variant.
+ * @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;
+    private hostKeeper;
+    connectedCallback(): void;
+    /** The label span that clips; the overflow anchor for the truncation tooltip. */
+    private labelTextEl?;
+    /** The node the tooltip is currently bound to, so a remount can re-bind. */
+    private tooltipBoundEl?;
+    private truncationCleanup;
     /**
-     * A unique identifier used for the underlying component `id` attribute.
+     * A unique identifier for this component instance. Does not set the host element's `id` attribute — set `id` directly if you need one.
      */
     componentId: string;
-    /**
-     * Sets the color scheme of the chip.
-     * @defaultValue 'neutral'
-     */
-    sentiment: 'accent' | 'danger' | 'info' | 'neutral' | 'success' | 'warning';
     /**
      * Determines whether a dot should be displayed on the chip.
+     * Note: This prop is ignored when sentiment is 'brand'.
      * @defaultValue false
      */
     dot: boolean;
     /**
-     *  Sets the text label content of the chip.
+     * 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.
      */
-    label: string;
+    dotColor?: string;
     /**
-     * Determines whether the chip should be rendered in a larger size.
-     * @defaultValue false
+     * 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'
+     */
+    size?: ChipSizeType;
+    /**
+     * Defines the color scheme of the chip.
+     * @defaultValue 'neutral'
      */
-    large: boolean;
+    sentiment: ChipSentimentType;
     /**
      * Sets the style variant of the chip.
+     * Note: This prop is ignored when sentiment is 'brand'.
      * @defaultValue 'text'
      */
-    variant: 'text' | 'tag' | 'dropdown';
+    variant: ChipVariantType;
+    /**
+     * URL to navigate to when the remove button is clicked.
+     * When provided, renders the close button as a link instead of a button.
+     * Only applies to tag variant.
+     */
+    removeUrl?: string;
+    /**
+     * HTTP method to use for the remove action.
+     * Maps to the `data-method` and `data-turbo-method` attributes on the remove link, for frameworks that read link methods from them.
+     * Only applies when removeUrl is provided.
+     */
+    removeHttpMethod?: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    /**
+     * Specifies where to open the linked document when removeUrl is provided.
+     * Only applies when removeUrl is set.
+     */
+    removeTarget?: '_blank' | '_self' | '_parent' | '_top';
+    /**
+     * Accessible label for the remove button. Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Remove'
+     */
+    dismissLabel: string;
+    /**
+     * Sets the maximum width of the chip, truncating the label with an ellipsis when it overflows.
+     * Accepts any CSS length (e.g. '200px', '20ch'). The slot is documented as label text — slotting richer markup may not truncate the way you expect.
+     */
+    maxWidth?: string;
     /**
-     * Event when close button is clicked on tag variant.
+     * Event emitted when the close button is clicked on a tag variant chip.
      */
-    pdsTagCloseClick: EventEmitter;
+    pdsTagCloseClick: EventEmitter<void>;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
+    private initTruncationTooltip;
+    private destroyTruncationTooltip;
     private handleCloseClick;
+    private get effectiveSize();
     private classNames;
+    private get effectiveVariant();
+    private get iconSize();
     private setChipContent;
+    private get hostStyles();
+    private renderCloseButton;
     render(): any;
 }

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

@@ -0,0 +1,73 @@
+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. With `group-display="inline"`, options without a group are listed before every group;
+     * with `flyout` and `drill-in`, options without a group and groups keep the array's order.
+     */
+    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;
+    /**
+     * A small chip after the group's label, such as "Premium". `label` is its text; `sentiment` is a
+     * `pds-chip` sentiment (`neutral` when unset or unknown); `icon` is a Pine icon name (letters,
+     * digits and hyphens, for example `premium`); URLs and file paths are not accepted. The first
+     * option in the group that sets one wins, the same as `data-badge`, `data-badge-sentiment` and
+     * `data-badge-icon` on a slotted `<optgroup>`. It isn't matched by search, and screen readers
+     * read it as part of the group's name. It isn't shown on a drilled-in group's row back.
+     */
+    groupBadge?: {
+        label: string;
+        sentiment?: string;
+        icon?: string;
+    };
+    /**
+     * Pine icon name shown before the option's text (letters, digits and hyphens, for example
+     * `hashtag`); URLs and file paths are not accepted. The same as `data-icon` on a slotted `<option>`.
+     * Once the option is chosen, the `button` trigger shows it too.
+     */
+    icon?: string;
+    /**
+     * A small chip after the option's text, such as "New". `label` is its text; `sentiment` is a
+     * `pds-chip` sentiment (`neutral` when unset or unknown); `icon` is a Pine icon name (letters,
+     * digits and hyphens, for example `star`); URLs and file paths are not accepted. The same as
+     * `data-badge`, `data-badge-sentiment` and `data-badge-icon` on a slotted `<option>`. It isn't
+     * shown in the trigger or matched by search, and screen readers read it as part of the option's
+     * name. Options that are chips or custom layouts don't show it.
+     */
+    badge?: {
+        label: string;
+        sentiment?: string;
+        icon?: 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 {
+    value: string;
+}
+export interface ComboboxSearchEventDetail {
+    query: string;
+}
+export interface ComboboxLoadOptionsEventDetail {
+    query: string;
+    page: number;
+}
+export interface AsyncResponse {
+    results: Array<{
+        id: string | number;
+        text: string;
+        [key: string]: unknown;
+    }>;
+    totalCount?: number;
+}

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

@@ -0,0 +1,128 @@
+import type { ChipSentimentType } from "../../utils/types";
+/**
+ * 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;
+    /** The optgroup's badge from its `data-badge*` attributes, or null. */
+    badge: OptionBadge | 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's `data-icon` when it's a Pine icon name, or null; the same check as a group's. */
+export declare function optionIconOf(option: HTMLOptionElement): string | null;
+export interface OptionBadge {
+    label: string;
+    sentiment: ChipSentimentType;
+    /** A Pine icon name, or null. */
+    icon: string | null;
+}
+/**
+ * An option's badge from its `data-badge*` attributes, or null without a label. An unknown
+ * sentiment falls back to `neutral`, and an icon that isn't a Pine icon name is dropped: the
+ * badge is a `pds-chip`, whose `icon` also loads URLs.
+ */
+export declare function optionBadgeOf(option: HTMLOptionElement): OptionBadge | null;
+/** An optgroup's badge from its `data-badge*` attributes, or null; the same check as an option's. */
+export declare function groupBadgeOf(optgroup: HTMLOptGroupElement): OptionBadge | 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.
+ *
+ * `position`, when given, orders the entries instead: an ungrouped option or an optgroup it knows
+ * goes where it reports, and the rest keep their place after those. Options from the `options` prop
+ * use it, so a row the data lists between two groups is drawn between them.
+ */
+export declare function buildPanelEntries(items: Element[], position?: (element: Element) => number | undefined): 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;
+}