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

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

@@ -0,0 +1,89 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A side panel composed from `pds-modal`, non-modal by default.
+ *
+ * By default, unlike `pds-modal`, the page stays interactive while a drawer
+ * is open: no dimming, no blur, no click blocking.
+ * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
+ * its backdrop suppressed, and adds the edge, width and dismiss behavior a
+ * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
+ * layer instead and keeps its backdrop. It does not reimplement focus, Escape or dialog semantics —
+ * those come from `pds-modal` unchanged.
+ * @lightDom renders-markup
+ */
+export declare class PdsDrawer {
+    el: HTMLPdsDrawerElement;
+    private modalEl?;
+    componentDidRender(): void;
+    /**
+     * A unique identifier used for the underlying component `id` attribute.
+     */
+    componentId: string;
+    /**
+     * Whether the drawer is open
+     * @default false
+     */
+    open: boolean;
+    /**
+     * Which edge of the viewport the drawer is docked to. Logical: `end` is the
+     * inline-end edge, so an `end` drawer docks on the left in right-to-left layouts.
+     * @default 'end'
+     */
+    side: 'start' | 'end';
+    /**
+     * The drawer's width.
+     * @default 'md'
+     */
+    size: 'sm' | 'md';
+    /**
+     * Whether the drawer content should be scrollable
+     * @default true
+     */
+    scrollable: boolean;
+    /**
+     * Whether the drawer is modal. A modal drawer dims the page behind it with a
+     * backdrop, makes the page inert, and keeps focus inside the drawer, like
+     * `pds-modal`. Use it for a task the page should wait on. Leave it off for a
+     * panel people work alongside the page. Read when the drawer opens; changing
+     * it while the drawer is open is not supported.
+     * @default false
+     */
+    modal: boolean;
+    /**
+     * Whether the drawer can be dismissed with a pointerdown outside it (in a
+     * `modal` drawer, a click on its backdrop).
+     * Setting it to `false` also turns off Escape, so the close button is the
+     * only way out.
+     *
+     * A trigger outside the drawer should only ever set `open` to `true` and
+     * leave closing to the drawer itself. A toggle-style trigger (`open =
+     * !open`) fights light dismiss: clicking it while open closes the drawer
+     * on `pointerdown`, then the trigger's own click handler re-opens it.
+     * @default true
+     */
+    lightDismiss: boolean;
+    /**
+     * Whether to move focus into the drawer when it opens. `auto` is right for
+     * a drawer opened by a direct user action (a click, a deep link the user
+     * just navigated to). Set to `none` for a drawer that can open from a
+     * background event while the user is mid-task elsewhere on the page —
+     * moving focus there would interrupt them, and the page stays live under
+     * a non-modal drawer, so it is a genuine data-entry risk, not just an
+     * annoyance. A `modal` drawer ignores `none`: the page behind it is inert,
+     * so focus starts in the drawer.
+     * @default 'auto'
+     */
+    initialFocus: 'auto' | 'none';
+    /**
+     * Emitted when the drawer is opened
+     */
+    pdsDrawerOpen: EventEmitter<void>;
+    /**
+     * Emitted when the drawer is closed
+     */
+    pdsDrawerClose: EventEmitter<void>;
+    handleModalClose(e: CustomEvent<void>): void;
+    handleModalOpen(e: CustomEvent<void>): void;
+    handleOutsidePointerDown(e: PointerEvent): void;
+    render(): any;
+}

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

@@ -0,0 +1,87 @@
+import { EventEmitter } from '../../../stencil-public-runtime';
+import type { BasePdsProps } from "../../../utils/interfaces";
+/**
+ * @slot (default) - The item's label.
+ * @slot start - Content to display before the item's label, such as a `pds-icon`. A `pds-icon` without an `aria-label` or `aria-labelledby` is decorative; a named one is announced before the label, so leave decorative icons unnamed.
+ * @part button - Exposes the item's inner element for styling. Appears on button and informational items, not on links.
+ */
+export declare class PdsDropdownMenuItem implements BasePdsProps {
+    host: HTMLPdsDropdownMenuItemElement;
+    /**
+     * 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;
+    /**
+     * Determines whether or not the dropdown menu item is destructive.
+     * @defaultValue false
+     */
+    destructive: boolean;
+    /**
+     * Determines whether or not the dropdown menu 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. Ignored when `informational` is set.
+     */
+    download?: string;
+    /**
+     *  If provided, renders the dropdown menu item as an anchor (`<a>`) element instead of a button.
+     *  Ignored when `informational` is set.
+     */
+    href: string | undefined;
+    /**
+     * Determines whether or not the dropdown menu item is informational: text that the arrow keys
+     * reach but that can't be activated. Takes precedence over `href` and `destructive`.
+     * Screen readers announce it as dimmed or unavailable, the same way as a disabled item.
+     * @defaultValue false
+     */
+    informational: boolean;
+    /**
+     * Shows the external-link (launch) icon. Opens in a new tab unless `target` says otherwise.
+     * Only applies when href is set. Ignored when `informational` is set.
+     * @defaultValue false
+     */
+    external: boolean;
+    /**
+     * Accessible label for the icon that `external` shows, passed to the inner
+     * `pds-link` and appended to the item's name. It isn't announced when
+     * `target` is anything other than `_blank`. Pass a translated string to
+     * localize it; defaults to English. Pass an empty string to make the icon
+     * decorative.
+     * @defaultValue '(opens in a new tab)'
+     */
+    externalLabel?: string;
+    /**
+     * Specifies where to open the linked document when href is provided.
+     * Overrides the new-tab default of `external`; the icon still shows.
+     * Only applies when href is set. Ignored when `informational` is set.
+     * @defaultValue undefined
+     */
+    target?: '_blank' | '_self' | '_parent' | '_top';
+    /**
+     * Emitted when the dropdown menu item is clicked.
+     *
+     */
+    pdsClick: EventEmitter<{
+        itemIndex: number;
+        item: HTMLPdsDropdownMenuItemElement;
+        content: string;
+    }>;
+    /**
+     * Trigger the click event. Does nothing when the item is disabled or informational.
+     */
+    clickItem(): Promise<void>;
+    private handleClick;
+    private startSlotEl?;
+    private updateStartSlotEmpty;
+    private renderContent;
+    private handleInformationalKeyDown;
+    private renderElement;
+    private innerAnchor;
+    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 for this component instance. Does not set the host element's `id` attribute — set `id` directly if you need one.
+     */
+    componentId: string;
+    /**
+     * Has no effect. A separator can't be focused or activated.
+     * @defaultValue false
+     */
+    disabled: boolean;
+    render(): any;
+}

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

@@ -0,0 +1,60 @@
+import type { BasePdsProps } from "../../utils/interfaces";
+import { PlacementType } from "../../utils/types";
+/**
+ * @slot trigger - The trigger element for the dropdown menu. It receives `aria-expanded` and `aria-haspopup`, so slot the focusable control itself, such as a `pds-button`, not a wrapper around it.
+ * @slot (default) - The menu items: `pds-dropdown-menu-item` and `pds-dropdown-menu-separator` elements, or raw `<a>` and `<button>` elements.
+ * @slot header - Non-interactive content displayed above the menu items inside the dropdown panel. It renders outside the menu role, so assistive tech reads it as plain content rather than as a menu item.
+ * @part menu-panel - Exposes the dropdown menu container for styling.
+ */
+export declare class PdsDropdownMenu implements BasePdsProps {
+    private slotEl;
+    private triggerEl;
+    private panelEl;
+    private isOpen;
+    private menuItems;
+    private cleanupAutoUpdate;
+    private openCount;
+    private triggerObserver;
+    private triggerVisibility;
+    host: HTMLPdsDropdownMenuElement;
+    currentFocusIndex: number;
+    hasHeader: boolean;
+    /**
+     * 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;
+    /**
+     * The placement of the dropdown panel relative to the trigger.
+     */
+    placement: PlacementType;
+    componentWillLoad(): void;
+    componentDidRender(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private handleTriggerSlotChange;
+    private syncTriggerAria;
+    private observeTrigger;
+    private handleHeaderSlotChange;
+    private handleSlotChange;
+    private toggleDropdown;
+    private openDropdown;
+    private capPanelHeight;
+    private watchTriggerVisibility;
+    private stopWatchingTriggerVisibility;
+    private closeDropdown;
+    private isFocusInMenu;
+    private focusTrigger;
+    private handleClick;
+    private isItemDisabled;
+    private getFocusedItemIndex;
+    private focusItemByIndex;
+    private focusNextItem;
+    private focusPreviousItem;
+    private adjacentEnabledIndex;
+    private focusAdjacentItem;
+    handleEscapeKeyDown(event: KeyboardEvent): void;
+    handleTabKeyDown(event: KeyboardEvent): void;
+    handleKeyDown(event: KeyboardEvent): void;
+    handleWindowClick(event: MouseEvent): void;
+    render(): any;
+}

package/dist/types/components/pds-filters/pds-filter/filter-interface.d.ts

@@ -0,0 +1,19 @@
+export type PdsFilterVariant = 'default' | 'selected' | 'more' | 'clear';
+export interface PdsFilterOpenEventDetail {
+    componentId: string;
+    variant: PdsFilterVariant;
+    text?: string;
+}
+export interface PdsFilterCloseEventDetail {
+    componentId: string;
+    variant: PdsFilterVariant;
+    text?: string;
+}
+export interface PdsFilterClearEventDetail {
+    componentId: string;
+    text?: string;
+}
+export interface PdsFilterEvent<T> extends CustomEvent<T> {
+    readonly detail: T;
+    readonly target: HTMLPdsFilterElement | null;
+}

package/dist/types/components/pds-filters/pds-filter/pds-filter.d.ts

@@ -0,0 +1,135 @@
+import { EventEmitter } from '../../../stencil-public-runtime';
+import type { BasePdsProps } from "../../../utils/interfaces";
+import type { PdsFilterOpenEventDetail, PdsFilterCloseEventDetail, PdsFilterClearEventDetail, PdsFilterVariant } from './filter-interface';
+/**
+ * A single filter in `pds-filters`: a trigger button that opens a popover holding the filter controls.
+ * The `clear` variant has no popover and emits `pdsFilterClear` instead.
+ *
+ * @part button - Exposes the trigger button element for styling.
+ * @part button-content - Exposes the button content container for styling.
+ * @part button-text - Exposes the button text for styling.
+ * @part icon - Exposes the icon component for styling.
+ * @part popover - Exposes the popover container for styling.
+ * @slot (default) - Popover content that will be displayed when the filter is open.
+ */
+export declare class PdsFilter implements BasePdsProps {
+    el: HTMLPdsFilterElement;
+    private popoverEl;
+    private scrollRAF;
+    private lastScrollTime;
+    private truncationTooltip;
+    /**
+     * A unique identifier for this component instance, used to build its internal popover's `id`.
+     * Does not set the host element's `id` attribute — set `id` directly if you need one.
+     */
+    componentId: string;
+    /**
+     * The variant style of the filter trigger.
+     * @defaultValue 'default'
+     */
+    variant: PdsFilterVariant;
+    /**
+     * The name of the icon to display in the trigger button.
+     * For 'clear' variant, this is ignored as it always shows trash icon.
+     */
+    icon?: string;
+    /**
+     * The text content displayed in the trigger button.
+     * When text overflows, a tooltip showing the full text will appear on hover/focus.
+     */
+    text?: string;
+    /**
+     * State to track if the popover is open.
+     */
+    isOpen: boolean;
+    /**
+     * Event emitted when the filter popover is opened.
+     */
+    pdsFilterOpen: EventEmitter<PdsFilterOpenEventDetail>;
+    /**
+     * Event emitted when the filter popover is closed.
+     */
+    pdsFilterClose: EventEmitter<PdsFilterCloseEventDetail>;
+    /**
+     * Event emitted when the clear variant is clicked.
+     */
+    pdsFilterClear: EventEmitter<PdsFilterClearEventDetail>;
+    connectedCallback(): void;
+    /**
+     * Component lifecycle: Clean up when disconnected from DOM.
+     * Prevents memory leaks by canceling pending operations and closing popovers.
+     */
+    disconnectedCallback(): void;
+    componentDidRender(): void;
+    private syncTruncationTooltip;
+    /**
+     * Handle native popover toggle events directly on the element
+     * This is needed for browsers with native Popover API support
+     */
+    private handleNativePopoverToggle;
+    /**
+     * Reposition popovers on window resize.
+     */
+    handleWindowResize(): void;
+    /**
+     * Reposition popovers on scroll with performance throttling.
+     */
+    handleWindowScroll(): void;
+    /**
+     * Closes other open filter popovers to ensure only one is open at a time.
+     */
+    private closeOtherPopovers;
+    /**
+     * Adjusts popover position to keep it within viewport bounds.
+     * Uses CSS anchor positioning for modern browsers, JavaScript for fallback browsers.
+     */
+    private adjustPopoverPosition;
+    /**
+     * Opens the filter popover programmatically.
+     * Note: Clear variant does not support popover functionality.
+     */
+    showFilter(): Promise<void>;
+    /**
+     * Closes the filter popover programmatically.
+     * Note: Clear variant does not support popover functionality.
+     */
+    hideFilter(): Promise<void>;
+    /**
+     * Listen for popover toggle events for browsers without native Popover API (fallback).
+     * Native API browsers use direct element listeners to avoid conflicts.
+     */
+    handlePopoverToggle(event: Event): void;
+    /**
+     * Listen for clicks to detect outside dismissal.
+     */
+    handleDocumentClick(event: Event): void;
+    /**
+     * Listen for Escape key to ensure close event fires.
+     */
+    handleEscapeKey(event: KeyboardEvent): void;
+    /**
+     * Handle keyboard interactions for clear variant only.
+     */
+    private handleKeyDown;
+    /**
+     * Handle trigger button click. Clear variant emits event, others toggle popover.
+     */
+    private handleClick;
+    /**
+     * Get the appropriate icon for the variant.
+     */
+    private getIcon;
+    /**
+     * Get CSS classes for the trigger button.
+     */
+    private getTriggerClasses;
+    /**
+     * Render the trigger icon.
+     */
+    private renderIcon;
+    /**
+     * Render the dropdown icon for selected variant.
+     */
+    private renderDropdownIcon;
+    render(): any;
+}

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

@@ -0,0 +1,11 @@
+import type { BasePdsProps } from "../../utils/interfaces";
+/**
+ * @slot (default) - Container for pds-filter components.
+ */
+export declare class PdsFilters implements BasePdsProps {
+    /**
+     * 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;
+    render(): any;
+}

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

@@ -0,0 +1,12 @@
+export interface ImageLoadEventDetail {
+    /** The URL the browser loaded, which can be a `srcset` candidate rather than `src`. */
+    currentSrc: string;
+    /** The loaded image's intrinsic height in pixels. */
+    naturalHeight: number;
+    /** The loaded image's intrinsic width in pixels. */
+    naturalWidth: number;
+}
+export interface ImageErrorEventDetail {
+    /** The URL that failed to load, which can be a `srcset` candidate rather than `src`. */
+    currentSrc: string;
+}

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

@@ -1,26 +1,45 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import type { ImageRatioType } from "../../utils/types";
+import type { ImageErrorEventDetail, ImageLoadEventDetail } from './image-interface';
 export declare class PdsImage {
     /**
-     * The image's alt tag. If none is provided,
-     * it will default to an empty string.
+     * The image's alt text. Defaults to an empty string, which marks the image
+     * as decorative and hides it from screen readers, so set it on any image
+     * that carries information.
+     * @defaultValue ''
      */
     alt?: string;
     /**
-     * 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;
     /**
-     * The height of the image in pixels. Setting this will
-     * devote space in the layout to prevent layout
-     * shifts when the image is loaded.
+     * Determines how the image fills the shape set by `ratio`.
+     * Has no effect if `ratio` is not set.
+     * @defaultValue cover
+     */
+    fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    /**
+     * The height of the image in pixels. `height: auto` lets the loaded image's own
+     * proportions decide its rendered height, so unlike `width` this does not reserve
+     * space before the image loads.
      */
     height?: number;
     /**
      * Indicates how the browser should load the image.
+     * @defaultValue eager
      */
     loading?: 'eager' | 'lazy';
+    /**
+     * The aspect ratio the image is sized to, cropping whatever overflows the shape. A preset
+     * (`square` 1/1, `landscape` 4/3, `wide` 16/9, `portrait` 3/4, `tall` 9/16) or any custom
+     * CSS ratio, such as `21 / 9`. Use this, not `height` and `width`, to crop: those only
+     * reserve space, and only `width` reliably does even that.
+     */
+    ratio?: ImageRatioType | (string & Record<never, never>);
     /**
      * Determines the intended display size of an image
-     * within certian breakpoints. Has no effect if `srcset`
+     * within certain breakpoints. Has no effect if `srcset`
      * is not set or value has no width descriptor.
      */
     sizes?: string;
@@ -29,14 +48,59 @@ export declare class PdsImage {
      */
     src: string;
     /**
-     * A set of image sources for the browser to use.
+     * A set of image sources for the browser to use
+     * for responsiveness.
      */
     srcset?: string;
     /**
-     * The width of the image in pixels. Setting this will
-     * devote space in the layout to prevent layout
-     * shifts when the image is loaded.
+     * The width of the image in pixels. This reserves the image's width before it
+     * loads, but not its height: to reserve the height too, set
+     * `--dimension-aspect-ratio` to the image's own proportions.
      */
     width?: number;
+    /**
+     * Emitted when the image loads. Also emitted on first render for an image that
+     * finished loading before the component could listen, such as a server-rendered
+     * image. Emitted again after `src` or `srcset` changes and the new image loads, or
+     * when the browser picks a different `srcset` candidate, such as on a resize. Bubbles
+     * and is composed, so a listener on an ancestor gets every `pds-image`'s events —
+     * check `event.target` when more than one is in scope.
+     */
+    pdsImageLoad: EventEmitter<ImageLoadEventDetail>;
+    /**
+     * Emitted when the image fails to load, such as for a broken or empty `src`. An image
+     * with no `src` or `srcset` at all emits neither event, since it has nothing to load.
+     * Emitted again after `src` or `srcset` changes and the new image fails. Bubbles and is
+     * composed, so a listener on an ancestor gets every `pds-image`'s events — check
+     * `event.target` when more than one is in scope.
+     */
+    pdsImageError: EventEmitter<ImageErrorEventDetail>;
+    private imageEl?;
+    /**
+     * The source and event last emitted. A cached image can report `complete` on first
+     * render and still fire its own `load` event afterwards, so this keeps one source
+     * from emitting twice. A `load` still replaces an `error` for the same source, in
+     * case `decode()` misjudged an image that did load.
+     */
+    private settled;
+    handleSourceChange(): void;
+    componentDidLoad(): void;
+    private hasSource;
+    /**
+     * The resolved absolute URL `src` would become once applied, or `undefined` for no
+     * `src`. Resolving it (rather than comparing raw attribute text) matches `img.src`
+     * even when Stencil skipped writing the attribute because the resolved value already
+     * equaled it, such as a `src` change from a relative to an equivalent absolute URL.
+     */
+    private resolvedSrc;
+    /**
+     * Whether the inner image is showing the current `src` and `srcset`. Right after
+     * either changes, and before the next render applies it, an event can still arrive
+     * for the old source, and it shouldn't be emitted for the new one.
+     */
+    private showsCurrentSource;
+    private emitLoad;
+    private emitError;
+    private imageRatio;
     render(): any;
 }

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

@@ -0,0 +1,12 @@
+export interface InputChangeEventDetail {
+    value?: string | number | null;
+    event?: Event;
+}
+export interface InputInputEventDetail {
+    value?: string | number | null;
+    event?: Event;
+}
+export interface InputEvent<T = InputChangeEventDetail> extends CustomEvent {
+    detail: T;
+    target: HTMLPdsInputElement;
+}