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

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

@@ -0,0 +1,88 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+export declare class PdsModal {
+    private modalRef;
+    private previousActiveElement;
+    private focusableElements;
+    el: HTMLPdsModalElement;
+    /**
+     * Whether the modal can be dismissed by clicking the backdrop
+     * @default true
+     */
+    backdropDismiss: boolean;
+    /**
+     * A unique identifier used for the underlying component `id` attribute.
+     */
+    componentId: string;
+    /**
+     * Whether the modal is open
+     * @default false
+     */
+    open: boolean;
+    /**
+     * The size of the modal
+     * @default 'md'
+     */
+    size: 'sm' | 'md' | 'lg' | 'fullscreen';
+    /**
+     * Whether the modal content should be scrollable
+     * @default true
+     */
+    scrollable: boolean;
+    /**
+     * Whether the modal opens outside the browser top layer as a non-modal dialog.
+     * When `true` it opens with `dialog.show()` instead of `dialog.showModal()`, so
+     * overlays rendered elsewhere in the DOM (file pickers, editor menus) can display
+     * above it via `z-index`. The page is not made inert and focus is not trapped in
+     * this mode. Read when the modal opens; changing it while the modal is open is
+     * not supported.
+     * @default false
+     */
+    disableTopLayer: boolean;
+    /**
+     * Emitted when the modal is opened
+     */
+    pdsModalOpen: EventEmitter<void>;
+    /**
+     * Emitted when the modal is closed
+     */
+    pdsModalClose: EventEmitter<void>;
+    /**
+     * Stores the list of focusable elements in the modal
+     */
+    focusableElementsArray: HTMLElement[];
+    componentDidLoad(): void;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
+    handleOpenChange(newValue: boolean): void;
+    /**
+     * Updates the list of focusable elements in the modal
+     */
+    private updateFocusableElements;
+    /**
+     * Sets focus to the first focusable element in the modal
+     */
+    private setInitialFocus;
+    /**
+     * Helper method to focus an element, with special handling for web components
+     */
+    private focusElement;
+    /**
+     * Opens the modal
+     */
+    showModal(): Promise<void>;
+    /**
+     * Closes the modal
+     */
+    hideModal(): Promise<void>;
+    private handleBackdropClick;
+    /**
+     * Gets the z-index of a modal's backdrop element
+     */
+    private getBackdropZIndex;
+    /**
+     * Checks if this modal is the innermost (highest z-index) modal
+     */
+    private isInnermostModal;
+    private handleKeyDown;
+    render(): any;
+}

package/dist/types/components/pds-modal/test/mock-pds-modal.d.ts

@@ -0,0 +1,68 @@
+import { EventEmitter } from '../../../stencil-public-runtime';
+interface HTMLMockPdsModalElement extends HTMLElement {
+    open: boolean;
+    showModal: () => Promise<void>;
+    hideModal: () => Promise<void>;
+    handleBackdropClick: (event: MouseEvent) => void;
+    handleKeyDown: (event: KeyboardEvent) => void;
+}
+/**
+ * Mock PdsModal component for testing purposes
+ * This component mimics the real PdsModal but without using the Popover API
+ */
+export declare class MockPdsModal {
+    el: HTMLMockPdsModalElement;
+    /**
+     * The ID of the modal component
+     */
+    componentId?: string;
+    /**
+     * The size of the modal
+     */
+    size: 'sm' | 'md' | 'lg' | 'fullscreen';
+    /**
+     * Whether the modal content should be scrollable
+     * @default true
+     */
+    scrollable: boolean;
+    /**
+     * Whether the modal can be dismissed by clicking the backdrop or pressing Escape
+     */
+    backdropDismiss: boolean;
+    /**
+     * Whether the modal is open
+     */
+    open: boolean;
+    /**
+     * Event emitted when the modal is opened
+     */
+    pdsModalOpen: EventEmitter<void>;
+    /**
+     * Event emitted when the modal is closed
+     */
+    pdsModalClose: EventEmitter<void>;
+    /**
+     * Event emitted when the backdrop is clicked
+     */
+    pdsModalBackdropClick: EventEmitter<void>;
+    /**
+     * Shows the modal
+     */
+    showModal(): Promise<void>;
+    /**
+     * Hides the modal
+     */
+    hideModal(): Promise<void>;
+    /**
+     * Listen for click events on the backdrop
+     */
+    handleBackdropClick(event: MouseEvent): void;
+    /**
+     * Listen for keydown events to handle Escape key
+     * Should only close on Escape if backdropDismiss is enabled
+     */
+    handleKeyDown(event: KeyboardEvent): void;
+    componentDidLoad(): void;
+    render(): any;
+}
+export {};

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

@@ -0,0 +1,42 @@
+export interface MultiselectOption {
+    id: string | number;
+    text: string;
+    /** When `true`, the option is rendered as non-interactive and cannot be selected. */
+    disabled?: boolean;
+    /**
+     * Optional section label for grouped rendering (with `options` prop or parsed slots).
+     * Options that share a `group` value must be contiguous in the array; non-contiguous
+     * rows with the same label produce separate headers (mirrors native `<optgroup>`).
+     */
+    group?: string;
+    isCreateOption?: boolean;
+    [key: string]: unknown;
+}
+export interface MultiselectChangeEventDetail {
+    values: string[];
+    items: MultiselectOption[];
+}
+export interface MultiselectSearchEventDetail {
+    query: string;
+}
+export interface MultiselectLoadOptionsEventDetail {
+    query: string;
+    page: number;
+}
+export interface MultiselectCreateEventDetail {
+    query: string;
+    newOption: MultiselectOption;
+}
+export interface AsyncResponse {
+    results: Array<{
+        id: string | number;
+        text: string;
+        [key: string]: unknown;
+    }>;
+    totalCount?: number;
+}
+export interface CreateResponse {
+    id: string | number;
+    text: string;
+    [key: string]: unknown;
+}

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

@@ -0,0 +1,326 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import type { PluralForms } from '../../i18n';
+import type { MultiselectOption, MultiselectChangeEventDetail, MultiselectSearchEventDetail, MultiselectLoadOptionsEventDetail, MultiselectCreateEventDetail } from './multiselect-interface';
+/**
+ * @slot (default) - Static option elements for the multiselect
+ * @slot empty - Custom empty state message when no options match
+ * @slot loading - Custom loading indicator
+ * @part trigger - The trigger surface that opens the dropdown panel
+ * @part pill-toggle - The chevron button inside the inline pill trigger
+ */
+export declare class PdsMultiselect {
+    private triggerEl?;
+    private pillInlineTriggerEl?;
+    private searchInputEl?;
+    private containerEl?;
+    private listboxEl?;
+    private panelEl?;
+    private internals?;
+    private abortController?;
+    private fetchDebounceTimer?;
+    private fetchTimeoutTimer?;
+    private observer?;
+    private cleanupAutoUpdate?;
+    el: HTMLPdsMultiselectElement;
+    /**
+     * A unique identifier used for the underlying component `id` attribute.
+     */
+    componentId: string;
+    /**
+     * Text to be displayed as the multiselect label.
+     */
+    label?: string;
+    /**
+     * Placeholder text for the input field. Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Select...'
+     */
+    placeholder: string;
+    /**
+     * Placeholder text for the search input inside the dropdown panel. Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Find...'
+     */
+    searchPlaceholder: string;
+    /**
+     * Accessible label for the search input. Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Search options'
+     */
+    searchOptionsLabel: string;
+    /**
+     * Accessible label for the selected-items region. Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Selected items'
+     */
+    selectedItemsLabel: string;
+    /**
+     * Accessible label for the options listbox (falls back to this when `label` is unset). Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Options'
+     */
+    optionsLabel: string;
+    /**
+     * Text shown when no options match the search. Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'No options found'
+     */
+    noOptionsFoundLabel: string;
+    /**
+     * Visible label for the create-new-option row. Pass a translated string to localize it; `{text}` is interpolated.
+     * @defaultValue 'Add "{text}"'
+     */
+    createOptionLabel: string;
+    /**
+     * Accessible label for the create-new-option row. Pass a translated string to localize it; `{text}` is interpolated.
+     * @defaultValue 'Create new tag: {text}'
+     */
+    createOptionAriaLabel: string;
+    /**
+     * Screen-reader announcement when an item is removed. Pass a translated string to localize it; `{item}` is interpolated.
+     * @defaultValue '{item} removed'
+     */
+    itemRemovedLabel: string;
+    /**
+     * Accessible label for the remove button on each selected-item pill. Pass a translated string to localize it; defaults to English.
+     * @defaultValue 'Remove'
+     */
+    pillRemoveLabel: string;
+    /**
+     * Singular form of the selected-count trigger text. Pass a translated string to localize it; `{count}` is interpolated.
+     * @defaultValue '{count} item'
+     */
+    selectedCountLabelOne: string;
+    /**
+     * Plural (and fallback) form of the selected-count trigger text — used for English and any locale whose selected plural category isn't supplied via `selectedCountLabels`. Pass a translated string to localize it; `{count}` is interpolated.
+     * @defaultValue '{count} items'
+     */
+    selectedCountLabelOther: string;
+    /**
+     * Full CLDR plural forms for the selected-count trigger text, for locales with more than the English `one`/`other` categories (e.g. Polish `few`/`many`, Arabic `zero`/`two`). Accepts an object property or a JSON string attribute keyed by CLDR category — `{ one, other, few, many, two, zero }`. Any form omitted here falls back to `selectedCountLabelOne`/`selectedCountLabelOther`. `{count}` is interpolated.
+     * @defaultValue undefined
+     */
+    selectedCountLabels?: PluralForms | string;
+    /**
+     * Whether to close the panel after an option is selected.
+     * Defaults to `false` (panel stays open for multi-select).
+     */
+    closePanelOnSelect: boolean;
+    /**
+     * Specifies the name. Submitted with the form as part of a name/value pair.
+     */
+    name?: string;
+    /**
+     * Array of selected option values.
+     */
+    value: string[];
+    /**
+     * Determines whether or not the multiselect is disabled.
+     */
+    disabled: boolean;
+    /**
+     * 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;
+    /**
+     * Maximum number of selections allowed.
+     */
+    maxSelections?: number;
+    /**
+     * Maximum height of the dropdown before scrolling.
+     */
+    maxHeight: string;
+    /**
+     * Width of the trigger button (and reference for dropdown positioning).
+     */
+    triggerWidth: string;
+    /**
+     * Minimum width of the dropdown panel.
+     */
+    minWidth: string;
+    /**
+     * Width of the dropdown panel. Defaults to the trigger width.
+     */
+    panelWidth?: string;
+    /**
+     * Visually hides the label but keeps it accessible.
+     */
+    hideLabel: boolean;
+    /**
+     * Hides the selected items summary section in the dropdown panel.
+     */
+    hideSelectedItems: boolean;
+    /**
+     * Display mode for selected items outside the dropdown panel.
+     * `'count'` shows "N item(s)" text in the trigger (default). `'pill'` renders
+     * selected items as dismissible pds-chip tags.
+     * @default 'count'
+     */
+    selectedDisplay: 'count' | 'pill';
+    /**
+     * Position of pill chips when `selectedDisplay` is `'pill'`.
+     * `'inline'` places chips inside the trigger; `'below'` places chips in a
+     * flex-wrap row directly below the trigger.
+     * @default 'inline'
+     */
+    pillPosition: 'inline' | 'below';
+    /**
+     * Maximum chips shown inline before collapsing to a "+N more" badge.
+     * Only applies when `selectedDisplay='pill'` and `pillPosition='inline'`.
+     * @default 3
+     */
+    maxInlinePills: number;
+    /**
+     * Error message to display.
+     */
+    errorMessage?: string;
+    /**
+     * Helper message to display below the input.
+     */
+    helperMessage?: string;
+    /**
+     * If true, the multiselect is in an invalid state.
+     */
+    invalid?: boolean;
+    /**
+     * If true, the multiselect is required.
+     */
+    required: boolean;
+    /**
+     * Whether the component is currently loading async options.
+     */
+    loading: boolean;
+    /**
+     * Options provided externally (for consumer-managed async).
+     * When using `group` on options, keep each group block contiguous in the array.
+     * The same `group` label appearing again after other items produces a separate header (same as native `<optgroup>`).
+     */
+    options?: MultiselectOption[];
+    /**
+     * Function to format async results. Receives raw API response item.
+     */
+    formatResult?: (item: unknown) => MultiselectOption;
+    /**
+     * URL endpoint for creating new options. When set, shows "Add" option when no matches found.
+     */
+    createUrl?: string;
+    /**
+     * CSRF token for authenticated requests. If not provided, attempts to read from meta tag.
+     */
+    csrfToken?: string;
+    /**
+     * CSRF header name for authenticated requests. Defaults to `X-CSRF-Token`.
+     */
+    csrfHeaderName?: string;
+    isOpen: boolean;
+    searchQuery: string;
+    highlightedIndex: number;
+    internalOptions: MultiselectOption[];
+    selectedItems: MultiselectOption[];
+    currentPage: number;
+    hasMore: boolean;
+    creating: boolean;
+    private removalAnnouncement;
+    private isOpening;
+    private isClosingViaSelection;
+    private initialAsyncFetchTriggered;
+    private pendingUnresolvedFetch;
+    /**
+     * Emitted when selection changes.
+     */
+    pdsMultiselectChange: EventEmitter<MultiselectChangeEventDetail>;
+    /**
+     * Emitted on search input (for consumer-managed async).
+     */
+    pdsMultiselectSearch: EventEmitter<MultiselectSearchEventDetail>;
+    /**
+     * Emitted to request more options (pagination).
+     */
+    pdsMultiselectLoadOptions: EventEmitter<MultiselectLoadOptionsEventDetail>;
+    /**
+     * Emitted when a new option is created.
+     */
+    pdsMultiselectCreate: EventEmitter<MultiselectCreateEventDetail>;
+    /**
+     * Emitted when the dropdown is dismissed via Escape key or click outside.
+     *
+     * This event fires only when the user explicitly dismisses the panel without making a selection:
+     * - ✅ Fires: Pressing Escape key while dropdown is open
+     * - ✅ Fires: Clicking outside the component while dropdown is open
+     * - ❌ Does NOT fire: When panel closes due to selection (including when `closePanelOnSelect` is true)
+     * - ❌ Does NOT fire: When panel closes programmatically via `closeDropdown()`
+     *
+     * Equivalent to Sage's `onEscapeHook`. Use this to restore parent UI state or run cleanup when the user cancels their interaction.
+     */
+    pdsMultiselectDismiss: EventEmitter<void>;
+    private originalSearchEmitter?;
+    connectedCallback(): void;
+    componentWillLoad(): void;
+    componentDidLoad(): void;
+    private setupSlotChangeListener;
+    disconnectedCallback(): void;
+    protected setupDebounce(): void;
+    protected valueChanged(newValue: string[] | string): void;
+    protected optionsChanged(): void;
+    protected internalOptionsChanged(): void;
+    /**
+     * Sets focus on the trigger button.
+     */
+    setFocus(): Promise<void>;
+    /**
+     * Clears all selected values and resets the component.
+     */
+    clear(): Promise<void>;
+    /**
+     * Handle global keyboard events for accessibility.
+     * Closes dropdown on Escape key press regardless of focus location.
+     */
+    handleWindowKeyDown(event: KeyboardEvent): void;
+    private setupMutationObserver;
+    private updateOptionsFromSlot;
+    private clearAsyncFetchState;
+    private debouncedFetchAsyncOptions;
+    private syncSelectedItems;
+    private ensureValueArray;
+    private getAllOptions;
+    private getFilteredOptions;
+    private updateFormValue;
+    private getCsrfToken;
+    private fetchOptions;
+    private createOption;
+    private handleTriggerClick;
+    private handleTriggerKeyDown;
+    private handleSearchInputChange;
+    private handleSearchInputKeyDown;
+    private handleContainerFocusOut;
+    private openDropdown;
+    private closeDropdown;
+    private positionDropdown;
+    private scrollOptionIntoView;
+    private toggleOption;
+    private selectOption;
+    private handleOptionMouseDown;
+    private handleOptionMouseEnter;
+    private handleScroll;
+    private getGroupedRenderItems;
+    private renderOption;
+    private renderSelectedItemsList;
+    private renderDropdown;
+    private handlePillRemove;
+    private renderInlinePills;
+    private renderBelowPills;
+    private getTriggerText;
+    /**
+     * The `one`/`other` props are the ergonomic English defaults; `selectedCountLabels`
+     * (object or JSON-string attribute) layers full CLDR forms on top for locales
+     * that need `few`/`many`/`two`/`zero`. Malformed JSON degrades to the defaults.
+     */
+    private resolveCountForms;
+    render(): any;
+}

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

@@ -0,0 +1,179 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import { PlacementType } from "../../utils/types";
+import { PdsPopoverEventDetail } from './popover-interface';
+/**
+ * @slot trigger - The trigger element for the popover
+ * @slot (default) - The content to display inside the popover
+ */
+export declare class PdsPopover {
+    /**
+     * Reference to the Host element
+     */
+    el: HTMLPdsPopoverElement;
+    /**
+     * Determines when the popover is active
+     * @defaultValue false
+     */
+    active: boolean;
+    /**
+     * Tracks if the component is still mounted to prevent memory leaks
+     */
+    private isComponentMounted;
+    /**
+     * Reference to the trigger element
+     */
+    private triggerEl;
+    /**
+     * Portal element rendered in document.body
+     */
+    private portalEl;
+    /**
+     * Guard to prevent repositioning loops
+     */
+    private isRepositioning;
+    /**
+     * Debounce timers for performance optimization
+     */
+    private scrollDebounceTimer;
+    private resizeDebounceTimer;
+    /**
+     * Track moved nodes and their placeholders for restoration
+     */
+    private movedNodes;
+    /**
+     * Timestamp when popover was opened (for preventing immediate close)
+     */
+    private openTimestamp;
+    /**
+     * Instance counter for unique IDs
+     */
+    private static instanceCounter;
+    /**
+     * Bound handlers for cleanup
+     */
+    private boundClickOutsideHandler;
+    private boundEscapeKeyHandler;
+    private boundScrollHandler;
+    private boundResizeHandler;
+    /**
+     * Emitted when the popover is opened
+     */
+    pdsPopoverOpen: EventEmitter<PdsPopoverEventDetail>;
+    /**
+     * Emitted when the popover is closed
+     */
+    pdsPopoverClose: EventEmitter<PdsPopoverEventDetail>;
+    /**
+     * Determines the action that triggers the popover. For manual popovers, the consumer is responsible for toggling this value.
+     * @defaultValue "show"
+     */
+    popoverTargetAction: 'show' | 'toggle' | 'hide';
+    /**
+     * Determines the type of popover. Auto popovers can be "light dismissed" by clicking outside of the popover.
+     * Manual popovers require the consumer to handle the visibility of the popover.
+     */
+    popoverType: 'auto' | 'manual';
+    /**
+     * A unique identifier used for the underlying component `id` attribute.
+     */
+    componentId: string;
+    /**
+     * Sets the maximum width of the popover content
+     * @defaultValue 352
+     */
+    maxWidth?: number;
+    /**
+     * Determines the preferred position of the popover
+     * @defaultValue "right"
+     */
+    placement: PlacementType;
+    componentDidLoad(): void;
+    /**
+     * Handles changes to the trigger slot
+     */
+    private handleTriggerSlotChange;
+    /**
+     * Handles changes to the default slot (popover content)
+     * When the popover is active, re-sync content with portal to handle dynamic updates
+     */
+    private handleContentSlotChange;
+    /**
+     * Handles clicks on the trigger element
+     */
+    private handleTriggerClick;
+    disconnectedCallback(): void;
+    /**
+     * Clears any pending debounce timers
+     */
+    private clearDebounceTimers;
+    private createPortal;
+    /**
+     * Adds Pine design system focus styles and dark mode border to the portal element
+     * Uses CSS variables from Pine's design tokens
+     */
+    private addPortalFocusStyles;
+    /**
+     * Moves slot content into portal (preserves event handlers and component instances)
+     */
+    private updatePortalContent;
+    /**
+     * Restores moved nodes back to their original positions
+     */
+    private restorePortalContent;
+    private removePortal;
+    /**
+     * Opens the popover programmatically
+     */
+    show(): Promise<void>;
+    /**
+     * Closes the popover programmatically
+     */
+    hide(): Promise<void>;
+    /**
+     * Toggles the popover open/closed state programmatically
+     */
+    toggle(): Promise<void>;
+    /**
+     * Adds light dismiss listeners (click outside and escape key)
+     */
+    private addLightDismissListeners;
+    /**
+     * Removes light dismiss listeners
+     */
+    private removeLightDismissListeners;
+    /**
+     * Adds scroll and resize listeners for repositioning
+     */
+    private addScrollAndResizeListeners;
+    /**
+     * Removes scroll and resize listeners
+     */
+    private removeScrollAndResizeListeners;
+    /**
+     * Handles clicks outside the popover for light dismiss (auto type only)
+     */
+    private handleClickOutside;
+    /**
+     * Returns focus to the trigger element with visible focus indicator
+     * This ensures focus rings/outlines are shown as they would be with keyboard navigation
+     */
+    private returnFocusToTrigger;
+    /**
+     * Handles escape key press to close the popover
+     * Mirrors native Popover API: Escape closes and returns focus to trigger
+     */
+    private handleEscapeKey;
+    /**
+     * Handles scroll events to reposition the popover (debounced for performance)
+     */
+    private handleScroll;
+    /**
+     * Handles resize events to reposition the popover (debounced for performance)
+     */
+    private handleResize;
+    /**
+     * Positions the popover relative to its trigger element
+     */
+    private handlePopoverPositioning;
+    render(): any;
+}