@pine-ds/core 4.0.0-mercury.0 → 4.1.0

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

@@ -1,39 +1,88 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+import type { ChipSentimentType, ChipSizeType, ChipVariantType } from "../../utils/types";
+/**
+ * @slot (default) - The chip's label text.
+ * @part button
+ */
 export declare class PdsChip {
+    el: HTMLPdsChipElement;
+    /** 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.
      */
     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.
+     * The name of the icon to display before the chip text.
      */
-    label: string;
+    icon?: string;
     /**
-     * Determines whether the chip should be rendered in a larger size.
-     * @defaultValue false
+     * Sets the size of the chip.
+     * @defaultValue 'md'
      */
-    large: boolean;
+    size?: ChipSizeType;
+    /**
+     * Defines the color scheme of the chip.
+     * @defaultValue 'neutral'
+     */
+    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.
+     * Adds data-method and data-turbo-method attributes for Rails/Turbo compatibility.
+     * 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,23 @@
+export interface ComboboxOption {
+    id: string | number;
+    text: string;
+    [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/pds-combobox.d.ts

@@ -0,0 +1,372 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import type { BasePdsProps } from "../../utils/interfaces";
+import type { ChipSentimentType } from "../../utils/types";
+import type { ComboboxOption, ComboboxSearchEventDetail, ComboboxLoadOptionsEventDetail } from './combobox-interface';
+/**
+ * @slot option - Option elements for the combobox dropdown
+ * @slot trigger-content - Custom content for the button trigger when customTriggerContent is true
+ * @slot empty - Custom empty state message when no options match
+ * @slot loading - Custom loading indicator
+ */
+export declare class PdsCombobox implements BasePdsProps {
+    /** Reference to the host element */
+    el: HTMLPdsComboboxElement;
+    /**
+     * A unique identifier used for the underlying component `id` attribute.
+     */
+    componentId: string;
+    /**
+     * The name of the form control. Submitted with the form as part of a name/value pair.
+     */
+    name?: string;
+    /**
+     * Enable custom layout content for options. Options with data-layout attribute will render their HTML content.
+     * ⚠️ Security Warning: Only use with trusted content. Basic XSS protection is applied, but avoid user-generated content.
+     * @default false
+     */
+    customOptionLayouts: boolean;
+    /**
+     * Enable custom layout content for the button trigger via the trigger-content slot.
+     * When true, uses slot content for initial state but updates dynamically with selected option layout.
+     * ⚠️ Security Warning: Only use with trusted content. Basic XSS protection is applied, but avoid user-generated content.
+     * @default false
+     */
+    customTriggerContent: boolean;
+    /**
+     * If true, the combobox is disabled.
+     */
+    disabled: boolean;
+    /**
+     * Error message to display.
+     */
+    errorMessage?: string;
+    /**
+     * Placement of the dropdown relative to the trigger.
+     * @default 'bottom-start'
+     */
+    dropdownPlacement: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+    /**
+     * Width of the dropdown. Any valid CSS width value.
+     * @default '236px'
+     */
+    dropdownWidth: string;
+    /**
+     * Where to mount the dropdown listbox (`host` or `body`, sometimes called “append to body”).
+     * Use `body` inside scrollable containers (for example modals) so the list is not clipped by
+     * `overflow: hidden` ancestors. The portal is appended to the nearest `<dialog>` when present
+     * (including `pds-modal` / `showModal()`), using a composed ascent so shadow DOM and slot
+     * boundaries do not hide the dialog from discovery; otherwise it is appended to `document.body`.
+     * Keyboard focus remains on the trigger via
+     * `aria-activedescendant` so modal focus traps continue to work. Custom `empty` and `loading`
+     * slots are not supported when `body` is used; the default empty and loading content is shown instead.
+     * @default 'host'
+     */
+    dropdownMount: 'host' | 'body';
+    /**
+     * Helper message to display below the combobox.
+     */
+    helperMessage?: string;
+    /**
+     * Visually hides the label text for instances where only the combobox should be displayed.
+     * The visible `<label>` is omitted (same pattern as `pds-select`) so label spacing does not reserve layout;
+     * the trigger uses `aria-label` so the name stays available to assistive technology.
+     */
+    hideLabel: boolean;
+    /**
+     * If true, the combobox is in an invalid state.
+     */
+    invalid?: boolean;
+    /**
+     * Text to be displayed as the combobox label.
+     */
+    label?: string;
+    /**
+     * Maximum height of the dropdown. Can be any valid CSS height value (e.g., '200px', '10rem').
+     * When content exceeds this height, the dropdown will scroll.
+     */
+    maxHeight?: string;
+    /**
+     * Determines the combobox mode: 'filter' (filter options as you type) or 'select-only' (show all options).
+     * In filter mode, reopening the menu while the input still shows the label of the selected option temporarily lists
+     * all options until you type (so you can switch to a different choice without clearing the field first).
+     * @default 'filter'
+     */
+    mode: 'filter' | 'select-only';
+    /**
+     * Placeholder text for the input field.
+     */
+    placeholder?: string;
+    /**
+     * Determines the combobox trigger: 'input' (editable input), 'button' (button-like, non-editable), or 'chip' (chip-like, non-editable).
+     * @default 'input'
+     */
+    trigger: 'input' | 'button' | 'chip';
+    /**
+     * Width of the trigger (button or input). Any valid CSS width value.
+     * @default 'fit-content'
+     */
+    triggerWidth: string;
+    /**
+     * The visual variant for the button trigger. Matches Pine button variants.
+     * @default 'secondary'
+     */
+    triggerVariant: 'secondary' | 'primary' | 'accent' | 'destructive';
+    /**
+     * The shape of the button trigger. Use 'input' to render the trigger with input-like styling
+     * (subtle border radius, input height) for use in form or filter rows alongside PdsSelect and PdsMultiselect.
+     * @default 'pill'
+     */
+    triggerShape: 'pill' | 'input';
+    /**
+     * The sentiment for the chip trigger. Matches Pine chip sentiments.
+     * @default 'neutral'
+     */
+    chipSentiment: ChipSentimentType;
+    /**
+     * Whether the chip trigger should be displayed in a larger size.
+     * @default false
+     */
+    chipLarge: boolean;
+    /**
+     * The name of the icon to display in the chip trigger.
+     */
+    chipIcon?: string;
+    /**
+     * Whether a dot should be displayed on the chip trigger.
+     * @default false
+     */
+    chipDot: boolean;
+    /**
+     * The value of the combobox input.
+     */
+    value: string;
+    /**
+     * URL endpoint for async data fetching.
+     */
+    asyncUrl?: string;
+    /**
+     * HTTP method for async requests.
+     */
+    asyncMethod: 'GET' | 'POST';
+    /**
+     * Debounce delay in milliseconds for search/fetch.
+     */
+    debounce: number;
+    /**
+     * Timeout in milliseconds for async fetch requests.
+     */
+    fetchTimeout: number;
+    /**
+     * Whether the component is currently loading async options.
+     */
+    loading: boolean;
+    /**
+     * Options provided externally (for consumer-managed async).
+     */
+    options?: ComboboxOption[];
+    /**
+     * Function to format async results. Receives raw API response item.
+     */
+    formatResult?: (item: unknown) => ComboboxOption;
+    /**
+     * Emitted when the value changes.
+     */
+    pdsComboboxChange: EventEmitter<{
+        value: string;
+    }>;
+    /**
+     * Emitted on search input (for consumer-managed async).
+     */
+    pdsComboboxSearch: EventEmitter<ComboboxSearchEventDetail>;
+    /**
+     * Emitted to request more options (pagination).
+     */
+    pdsComboboxLoadOptions: EventEmitter<ComboboxLoadOptionsEventDetail>;
+    /**
+     * Internal state for the display text shown in the input/trigger
+     */
+    displayText: string;
+    /**
+     * Internal state for filtered options and group labels
+     */
+    filteredItems: (HTMLOptionElement | HTMLOptGroupElement | HTMLPdsTextElement)[];
+    /**
+     * Internal state for the currently highlighted option index
+     */
+    highlightedIndex: number;
+    /**
+     * Internal state for dropdown open/close
+     */
+    isOpen: boolean;
+    /**
+     * Internal state for the currently selected option
+     */
+    selectedOption: HTMLOptionElement | null;
+    /**
+     * Internal state for the sanitized layout content of the selected option
+     */
+    selectedOptionLayoutContent: string;
+    /**
+     * Internal state to track chip properties for automatic rendering
+     */
+    selectedOptionChipProps: any;
+    /**
+     * Internal state for async options.
+     */
+    internalOptions: ComboboxOption[];
+    /**
+     * Internal state for current page (pagination).
+     */
+    currentPage: number;
+    /**
+     * Internal state for hasMore (pagination).
+     */
+    hasMore: boolean;
+    private inputEl?;
+    private optionEls;
+    private allItems;
+    private triggerEl?;
+    private listboxEl?;
+    private portalEl;
+    private cleanupPositionAutoUpdate?;
+    private bodyPortalAutoUpdateActive;
+    /** Deferred so portal teardown runs after Stencil reconciles `isOpen === false`. */
+    private deferredPortalTeardownId?;
+    private internals?;
+    private isUpdatingFromSelection;
+    private abortController?;
+    private fetchDebounceTimer?;
+    private fetchTimeoutTimer?;
+    private observer?;
+    private originalSearchEmitter?;
+    /**
+     * 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,
+     * the list shows every option until the user types (then normal filtering applies).
+     */
+    private expandFilterListWhileOpen;
+    connectedCallback(): void;
+    componentWillLoad(): void;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
+    componentDidRender(): void;
+    protected isOpenChanged(isOpen: boolean): void;
+    private get usesBodyPortal();
+    private get listboxId();
+    private optionDomId;
+    protected setupDebounce(): void;
+    protected optionsChanged(): void;
+    handleValueChange(): void;
+    handleSelectedOptionChange(): void;
+    private updateFormValue;
+    private clearAsyncFetchState;
+    private debouncedFetchAsyncOptions;
+    private fetchOptions;
+    private updateOptionsFromAsync;
+    private updateOptions;
+    private getOptionLabel;
+    private getOptionLayoutContent;
+    private sanitizeHtml;
+    private isOptionLayout;
+    private isOptionChip;
+    private getOptionChipProps;
+    private isOptionSelected;
+    private setSelectedOption;
+    private filterOptions;
+    private clearExpandFilterList;
+    /**
+     * When reopening the dropdown in filter mode with the input still showing the
+     * committed selection label, show the full option list until the user edits the query.
+     */
+    private prepareExpandFilterListOnOpen;
+    private positionDropdown;
+    private openDropdownPositioning;
+    private startBodyPortalAutoUpdate;
+    private stopBodyPortalAutoUpdate;
+    private getPortalMountRoot;
+    /**
+     * Resolves the native `<dialog>` to host the portaled listbox so it stays in the same top layer
+     * as `showModal()`. `Element.closest('dialog')` stops at shadow boundaries and can miss a
+     * dialog that only wraps slotted content; this walks assigned slots and shadow hosts, and
+     * falls back to `pds-modal`'s dialog when the combobox lives inside that subtree.
+     */
+    private findNearestDialogForPortal;
+    private ensureBodyPortal;
+    private syncBodyPortal;
+    private removeBodyPortal;
+    private handleInput;
+    private handleInputClick;
+    private handleKeyDown;
+    /**
+     * 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.
+     */
+    private setInitialHighlightedIndex;
+    /**
+     * Focus management helper - moves focus to the first option when dropdown opens
+     */
+    private focusFirstOption;
+    /**
+     * Focus management helper - actually focuses the first option when opened via arrow keys
+     */
+    private focusFirstOptionForArrowKeys;
+    private isArrowKeyNavigationMode;
+    /**
+     * Focus management helper - updates visual state and scrolling for the currently highlighted option
+     * Note: We don't actually focus the option to prevent focusout events that close the dropdown
+     */
+    private updateOptionFocus;
+    /**
+     * Updates aria-activedescendant on the trigger element
+     */
+    private updateAriaActiveDescendant;
+    /**
+     * Focus management helper - restores focus to the trigger element
+     */
+    private restoreFocusToTrigger;
+    /**
+     * Gets the value of the currently selected option.
+     */
+    getSelectedValue(): Promise<string | null>;
+    /**
+     * Clears the selected value and resets the component.
+     */
+    clear(): Promise<void>;
+    private onOptionClick;
+    private onOptionMouseEnter;
+    private onOptionMouseDown;
+    private onOptionKeyDown;
+    private get selectedLabel();
+    private get selectedLayoutContent();
+    private get selectedHasLayout();
+    private get selectedChipSentiment();
+    private get selectedChipLarge();
+    private get selectedChipIcon();
+    private get selectedChipDot();
+    private onButtonTriggerClick;
+    private onButtonTriggerKeyDown;
+    private onButtonTriggerKeyUp;
+    private onComboboxFocusOut;
+    private handleOptionClick;
+    private handleScroll;
+    private renderDropdown;
+    private renderCaretIcon;
+    private renderLayoutContent;
+    private renderDefaultContent;
+    private shouldShowLayoutContent;
+    private getChipTriggerClass;
+    private renderButtonTriggerContent;
+    private renderChipTriggerContent;
+    private renderSelectedOptionAsChip;
+    private renderChipTriggerLayoutContent;
+    private getModifiedLayoutContentForTrigger;
+    private renderChipTriggerDefaultContent;
+    private renderOptionChip;
+    private isInvalid;
+    private renderMessages;
+    render(): any;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * @part container - The inner semantic container element
+ */
+export declare class PdsContainer {
+    /**
+     * Sets the maximum width of the container. Accepts a named size token
+     * (`'sm'` | `'md'` | `'lg'` | `'xl'` | `'full'`) or any valid CSS length value (e.g. `'640px'`, `'50rem'`).
+     * When omitted, no max-width is applied.
+     */
+    size?: string;
+    /**
+     * Sets the semantic HTML tag rendered as the inner container element.
+     * @default 'div'
+     */
+    tag: 'div' | 'main' | 'section' | 'article';
+    /**
+     * If `true`, the container is centered horizontally using `margin-inline: auto`.
+     * @default true
+     */
+    centered: boolean;
+    render(): any;
+}

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

@@ -1,7 +1,10 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 export declare class PdsCopytext {
+    el: HTMLPdsCopytextElement;
+    private truncationCleanup;
+    private valueSpanEl;
     /**
-     * Determines whether `copytext` should have a border.
+     * Determines whether `copytext` should have a visible border.
      * @defaultValue true
      */
     border: boolean;
@@ -16,17 +19,24 @@ export declare class PdsCopytext {
     fullWidth: boolean;
     /**
      * Determines whether the `value` should truncate and display with an ellipsis.
+     * When text overflows, a tooltip showing the full value will appear on hover/focus.
      * @defaultValue false
      */
     truncate: boolean;
     /**
-     * String that is displayed and that is also copied to the clipboard upon interaction.
+     * The string displayed that is also copied to the clipboard upon interaction.
      */
     value: string;
+    handleTruncateChange(newValue: boolean): void;
+    handleValueChange(): void;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
+    private initTruncationTooltip;
+    private destroyTruncationTooltip;
     /**
-     * Event when copyText button is clicked.
+     * Event fired when copyText button is clicked.
      */
-    pdsCopyTextClick: EventEmitter;
+    pdsCopyTextClick: EventEmitter<string>;
     private copyToClipboard;
     private handleClick;
     private classNames;

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

@@ -1,17 +1,25 @@
+/**
+ * @part label - Exposes the label text for styling, such as a custom color. Appears only when `label` is set and `vertical` is `false`.
+ */
 export declare class PdsDivider {
     /**
      * A unique identifier used for the underlying component `id` attribute.
      */
     componentId: string;
+    /**
+     * Text to be displayed as the divider label, centered between two lines. Ignored when `vertical` is `true`.
+     */
+    label?: string;
     /**
      * Adds offset margin/padding to expand the width (horizontal) or the height (vertical) of divider.
      */
     offset: 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
     /**
-     * Sets divider to display vertically
+     * Sets divider to display vertically.
      * @defaultValue false
      */
     vertical: boolean;
+    private get hasLabel();
     private classNames;
     render(): any;
 }

package/dist/types/components/pds-dropdown-menu/pds-dropdown-menu-item/pds-dropdown-menu-item.d.ts

@@ -0,0 +1,66 @@
+import { EventEmitter } from '../../../stencil-public-runtime';
+import type { BasePdsProps } from "../../../utils/interfaces";
+/**
+ * @part button
+ */
+export declare class PdsDropdownMenuItem implements BasePdsProps {
+    host: HTMLPdsDropdownMenuItemElement;
+    /**
+     * A unique identifier used for the underlying component `id` attribute.
+     */
+    componentId: string;
+    /**
+     * It determines whether or not the dropdown-item is destructive.
+     * @defaultValue false
+     */
+    destructive: boolean;
+    /**
+     * It determines whether or not the dropdown-item is disabled.
+     * @defaultValue false
+     */
+    disabled: boolean;
+    /**
+     * 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;
+    /**
+     *  If provided, renders the dropdown-item as an anchor (`<a>`) element instead of a button.
+     */
+    href: string | undefined;
+    /**
+     * Determines whether the link should open in a new tab and display an external icon.
+     * This is a simpler alternative to using `target="_blank"` for the common case.
+     * @defaultValue false
+     */
+    external: boolean;
+    /**
+     * Specifies where to open the linked document when href is provided.
+     * Takes precedence over the `external` prop if both are set.
+     * Only applies when href is set.
+     * @defaultValue undefined
+     */
+    target?: '_blank' | '_self' | '_parent' | '_top';
+    /**
+     * Emitted when the dropdown-item is clicked.
+     *
+     */
+    pdsClick: EventEmitter<{
+        itemIndex: number;
+        item: HTMLPdsDropdownMenuItemElement;
+        content: string;
+    }>;
+    /**
+     * Trigger the click event
+     */
+    clickItem(): Promise<void>;
+    private handleClick;
+    hasFocus: boolean;
+    private handleFocus;
+    private handleBlur;
+    private renderElement;
+    private handleKeyDown;
+    render(): any;
+}

package/dist/types/components/pds-dropdown-menu/pds-dropdown-menu-separator/pds-dropdown-menu-separator.d.ts

@@ -0,0 +1,13 @@
+import type { BasePdsProps } from "../../../utils/interfaces";
+export declare class PdsDropdownMenuSeparator implements BasePdsProps {
+    /**
+     * A unique identifier used for the underlying component `id` attribute.
+     */
+    componentId: string;
+    /**
+     * It determines whether or not the dropdown-item is disabled.
+     * @defaultValue false
+     */
+    disabled: boolean;
+    render(): any;
+}