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

package/dist/collection/utils/test/axe.js

@@ -0,0 +1,106 @@
+/**
+ * Default tag filter applied by `runAxe`. Mirrors WCAG 2.0 + 2.1 levels A
+ * and AA. Override with `{ tags: [...] }` to widen or narrow the scope.
+ */
+export const DEFAULT_AXE_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
+/**
+ * Page-level axe rules that fire on the bare HTML harness Stencil's E2E
+ * provides (no `<title>`, no `<html lang>`, no landmarks, no `<h1>`, and
+ * often without the full theme/global stylesheet).
+ * They are disabled by default because they describe document chrome or
+ * need themed context — flagging them at component scope yields noise or flakes.
+ *
+ * Tests can opt back in for a specific case:
+ *
+ * ```ts
+ * await runAxe(page, { rules: { 'document-title': { enabled: true } } });
+ * ```
+ */
+export const DEFAULT_DISABLED_RULES = [
+    'document-title',
+    'html-has-lang',
+    'landmark-one-main',
+    'page-has-heading-one',
+    'region',
+    // `color-contrast` cannot be measured reliably on the bare E2E harness: it
+    // renders without the full theme/global stylesheet and with fonts that may
+    // fail to load, so axe computes contrast against incidental colors (results
+    // are flaky run-to-run). Verify contrast in a themed context (Storybook).
+    'color-contrast',
+];
+/**
+ * Injects axe-core into an active Stencil E2EPage and returns any
+ * accessibility violations found in the current document.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const page = await newE2EPage();
+ * await page.setContent('<pds-button>Click me</pds-button>');
+ * const violations = await runAxe(page);
+ * expect(violations).toEqual([]);
+ * ```
+ *
+ * Component tests should assert against the returned array directly so
+ * each component can document its own baseline (zero violations is the
+ * goal; suppressions should be deliberate and commented).
+ */
+export async function runAxe(page, options = {}) {
+    var _a, _b;
+    // Resolve axe-core's UMD bundle from node_modules at test time so we
+    // do not depend on a build step injecting it.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const axePath = require.resolve('axe-core/axe.min.js');
+    await page.addScriptTag({ path: axePath });
+    const defaultRules = DEFAULT_DISABLED_RULES.reduce((acc, rule) => {
+        acc[rule] = { enabled: false };
+        return acc;
+    }, {});
+    const runOptions = {
+        runOnly: {
+            type: 'tag',
+            values: (_a = options.tags) !== null && _a !== void 0 ? _a : [...DEFAULT_AXE_TAGS],
+        },
+        rules: Object.assign(Object.assign({}, defaultRules), ((_b = options.rules) !== null && _b !== void 0 ? _b : {})),
+    };
+    // Embed options in a string-evaluated IIFE so Istanbul does not instrument
+    // the browser-side function (cov_* globals are undefined in Puppeteer).
+    const optsJson = JSON.stringify(runOptions);
+    const violations = await page.evaluate(`
+    (async () => {
+      const opts = ${optsJson};
+      const axe = window.axe;
+      if (!axe) {
+        throw new Error('axe-core failed to load on the page.');
+      }
+      const results = await axe.run(document, opts);
+      return results.violations;
+    })()
+  `);
+    return violations;
+}
+/**
+ * Formats an axe target selector, including nested arrays for shadow DOM
+ * and iframe boundaries (axe's `UnlabelledFrameSelector` shape).
+ */
+export function formatAxeTarget(target) {
+    return target
+        .map((segment) => (Array.isArray(segment) ? segment.join(' ') : segment))
+        .join(' >> ');
+}
+/**
+ * Formats an array of axe violations into a readable failure message for
+ * use in test output. Returns an empty string when there are no
+ * violations, so it can be passed directly into `expect(...).toBe('')`.
+ */
+export function formatViolations(violations) {
+    if (violations.length === 0)
+        return '';
+    return violations
+        .map((v) => {
+        var _a;
+        const targets = v.nodes.map((n) => formatAxeTarget(n.target)).join(', ');
+        return `• [${(_a = v.impact) !== null && _a !== void 0 ? _a : 'unknown'}] ${v.id} — ${v.help}\n    ${targets}\n    ${v.helpUrl}`;
+    })
+        .join('\n\n');
+}

package/dist/collection/utils/test/reconnect-safety.js

@@ -0,0 +1,31 @@
+import { newSpecPage } from "@stencil/core/testing";
+/**
+ * Generic guard against the page-cache (Turbo, browser bfcache) reconnect bug class:
+ * a light-DOM (`shadow: false` or `scoped: true`) component that wraps its slotted
+ * content in a rendered element is reconnected over its own prior render, nesting
+ * (or duplicating, or losing) content.
+ *
+ * Hydrates `html`, re-parses the resulting markup the way a cache restore reconnects
+ * a component over its own output, and asserts no duplicate `id`s and no content
+ * loss or duplication survive the second pass.
+ */
+export async function expectReconnectSafe(components, html) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const first = await newSpecPage({ components: components, html });
+    const hydrated = (_b = (_a = first.root) === null || _a === void 0 ? void 0 : _a.outerHTML) !== null && _b !== void 0 ? _b : '';
+    const originalText = normalizeText((_d = (_c = first.root) === null || _c === void 0 ? void 0 : _c.textContent) !== null && _d !== void 0 ? _d : '');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const second = await newSpecPage({ components: components, html: hydrated });
+    const reconnectedText = normalizeText((_f = (_e = second.root) === null || _e === void 0 ? void 0 : _e.textContent) !== null && _f !== void 0 ? _f : '');
+    expect(reconnectedText).toBe(originalText);
+    const ids = Array.from((_h = (_g = second.root) === null || _g === void 0 ? void 0 : _g.querySelectorAll('[id]')) !== null && _h !== void 0 ? _h : []).map((el) => el.id);
+    const duplicateIds = ids.filter((id, index) => ids.indexOf(id) !== index);
+    expect(duplicateIds).toEqual([]);
+}
+// Strips whitespace entirely rather than collapsing it: an outerHTML round-trip through
+// re-parsing can introduce or lose insignificant whitespace between elements, which isn't
+// the content-loss/duplication bug this guard is checking for.
+function normalizeText(text) {
+    return text.replace(/\s+/g, '');
+}

package/dist/collection/utils/truncation-tooltip.js

@@ -0,0 +1,241 @@
+import { computePosition, flip, offset, shift, } from "@floating-ui/dom";
+/** CSS class prefix used for truncation tooltip portal elements */
+const TOOLTIP_CLASS = 'pds-truncation-tooltip';
+/**
+ * Injects the truncation tooltip styles into the document head.
+ * Uses the same design tokens as pds-tooltip for visual consistency.
+ * Only injects once — checks the DOM to avoid duplicates.
+ *
+ * Z-Index Strategy:
+ * Uses --pine-z-index-nuclear (9999) to ensure tooltips appear above all other UI elements.
+ * This is necessary because tooltips are portaled to document.body and must overlay:
+ * - Modal dialogs
+ * - Dropdown menus
+ * - Other floating UI elements
+ * If you encounter z-index conflicts, ensure your overlays use Pine's z-index tokens
+ * or adjust --pine-z-index-nuclear in your theme.
+ */
+function injectStyles() {
+    if (document.querySelector('[data-pds-truncation-tooltip]'))
+        return;
+    const style = document.createElement('style');
+    style.setAttribute('data-pds-truncation-tooltip', '');
+    style.textContent = `
+    .${TOOLTIP_CLASS} {
+      position: fixed;
+      z-index: var(--pine-z-index-nuclear, 9999);
+    }
+    .${TOOLTIP_CLASS}__content {
+      background-color: var(--pine-color-primary, #1a1a2e);
+      border-radius: calc(var(--pine-dimension-xs, 4px) * 1.25);
+      box-shadow: var(--pine-box-shadow, 0 2px 8px rgba(0,0,0,0.15));
+      color: var(--pine-color-text-primary, #fff);
+      cursor: text;
+      font-family: var(--pine-font-family-body, sans-serif);
+      font-size: var(--pine-font-size-body-sm, 0.875rem);
+      letter-spacing: var(--pine-letter-spacing, normal);
+      line-height: var(--pine-line-height-body, 1.5);
+      max-width: 320px;
+      opacity: 0;
+      padding: var(--pine-dimension-xs, 4px) calc(var(--pine-dimension-md, 12px) / 2);
+      transition: opacity 0.15s ease-in-out, visibility 0.15s ease-in-out;
+      user-select: text;
+      visibility: hidden;
+      width: max-content;
+      word-break: break-word;
+    }
+    .${TOOLTIP_CLASS}--visible .${TOOLTIP_CLASS}__content {
+      opacity: 1;
+      visibility: visible;
+    }
+  `;
+    document.head.appendChild(style);
+}
+/**
+ * Checks if an element's content is overflowing horizontally (i.e. text is truncated).
+ */
+function isOverflowing(el) {
+    return el.scrollWidth > el.clientWidth;
+}
+/**
+ * Sets up automatic tooltip behavior for a truncated element.
+ *
+ * When the element's text overflows, hovering or focusing the host element
+ * will display a tooltip showing the full text content. The tooltip is
+ * rendered as a portal on document.body and positioned with Floating UI.
+ *
+ * @returns A cleanup function that removes all listeners, observers, and DOM elements.
+ */
+export function setupTruncationTooltip(options) {
+    const { hostEl, contentEl, getTooltipText, placement = 'top' } = options;
+    injectStyles();
+    let portalEl = null;
+    let isHovering = false;
+    let isHoveringPortal = false;
+    let isFocused = false;
+    let hideTimeout = null;
+    let resizeObserver = null;
+    let resizeDebounce = null;
+    // Use ResizeObserver to re-evaluate overflow when the element resizes
+    // Debounced to prevent performance issues during rapid window resizing
+    if (typeof ResizeObserver !== 'undefined') {
+        resizeObserver = new ResizeObserver(() => {
+            if (resizeDebounce) {
+                clearTimeout(resizeDebounce);
+            }
+            resizeDebounce = setTimeout(() => {
+                resizeDebounce = null;
+                // If tooltip is showing but text no longer overflows, hide it
+                if (portalEl && portalEl.isConnected && !isOverflowing(contentEl)) {
+                    hideTooltip();
+                }
+            }, 100);
+        });
+        resizeObserver.observe(contentEl);
+    }
+    function createPortal() {
+        if (portalEl)
+            return;
+        const text = getTooltipText();
+        if (!text || text.trim() === '')
+            return;
+        portalEl = document.createElement('div');
+        portalEl.className = TOOLTIP_CLASS;
+        portalEl.setAttribute('role', 'tooltip');
+        portalEl.setAttribute('aria-hidden', 'false');
+        const contentDiv = document.createElement('div');
+        contentDiv.className = `${TOOLTIP_CLASS}__content`;
+        contentDiv.textContent = text.trim();
+        portalEl.appendChild(contentDiv);
+        document.body.appendChild(portalEl);
+        // Allow the user to hover into the tooltip to select/copy text
+        portalEl.addEventListener('mouseenter', handlePortalMouseEnter);
+        portalEl.addEventListener('mouseleave', handlePortalMouseLeave);
+        positionTooltip().then(() => {
+            if (portalEl) {
+                portalEl.classList.add(`${TOOLTIP_CLASS}--visible`);
+            }
+        });
+    }
+    async function positionTooltip() {
+        if (!portalEl)
+            return;
+        try {
+            const { x, y } = await computePosition(hostEl, portalEl, {
+                placement,
+                strategy: 'fixed',
+                middleware: [offset(4), flip(), shift({ padding: 5 })],
+            });
+            Object.assign(portalEl.style, {
+                left: `${x}px`,
+                top: `${y}px`,
+            });
+        }
+        catch (_a) {
+            // Fallback: position above the element with bounds checking
+            if (portalEl) {
+                const rect = hostEl.getBoundingClientRect();
+                const portalRect = portalEl.getBoundingClientRect();
+                const padding = 5;
+                // Ensure tooltip stays within viewport bounds
+                const left = Math.max(padding, Math.min(rect.left, window.innerWidth - portalRect.width - padding));
+                const top = Math.max(padding, rect.top - portalRect.height - 8);
+                portalEl.style.left = `${left}px`;
+                portalEl.style.top = `${top}px`;
+            }
+        }
+    }
+    function removePortal() {
+        if (portalEl) {
+            portalEl.removeEventListener('mouseenter', handlePortalMouseEnter);
+            portalEl.removeEventListener('mouseleave', handlePortalMouseLeave);
+            portalEl.classList.remove(`${TOOLTIP_CLASS}--visible`);
+            // Check if portal is still in the DOM before removing
+            if (portalEl.parentNode && portalEl.isConnected) {
+                try {
+                    portalEl.parentNode.removeChild(portalEl);
+                }
+                catch (e) {
+                    // Portal was already removed, ignore error
+                }
+            }
+            portalEl = null;
+        }
+    }
+    function cancelHideTimeout() {
+        if (hideTimeout !== null) {
+            clearTimeout(hideTimeout);
+            hideTimeout = null;
+        }
+    }
+    function showTooltip() {
+        cancelHideTimeout();
+        if (!isOverflowing(contentEl))
+            return;
+        createPortal();
+    }
+    function hideTooltip() {
+        if (isHovering || isHoveringPortal || isFocused)
+            return;
+        removePortal();
+    }
+    /**
+     * Schedules tooltip removal after a short delay.
+     *
+     * The 100ms delay serves two purposes:
+     * 1. Gives users time to move their cursor from the truncated text to the tooltip portal
+     *    without it closing, enabling text selection/copying from the tooltip
+     * 2. Prevents flickering when the user briefly moves the cursor during normal interaction
+     */
+    function scheduleHide() {
+        cancelHideTimeout();
+        hideTimeout = setTimeout(() => {
+            hideTimeout = null;
+            hideTooltip();
+        }, 100);
+    }
+    function handleMouseEnter() {
+        isHovering = true;
+        showTooltip();
+    }
+    function handleMouseLeave() {
+        isHovering = false;
+        scheduleHide();
+    }
+    function handlePortalMouseEnter() {
+        isHoveringPortal = true;
+        cancelHideTimeout();
+    }
+    function handlePortalMouseLeave() {
+        isHoveringPortal = false;
+        scheduleHide();
+    }
+    function handleFocusIn() {
+        isFocused = true;
+        showTooltip();
+    }
+    function handleFocusOut() {
+        isFocused = false;
+        scheduleHide();
+    }
+    hostEl.addEventListener('mouseenter', handleMouseEnter);
+    hostEl.addEventListener('mouseleave', handleMouseLeave);
+    hostEl.addEventListener('focusin', handleFocusIn);
+    hostEl.addEventListener('focusout', handleFocusOut);
+    // Return cleanup function
+    return () => {
+        cancelHideTimeout();
+        if (resizeDebounce) {
+            clearTimeout(resizeDebounce);
+            resizeDebounce = null;
+        }
+        if (resizeObserver) {
+            resizeObserver.disconnect();
+        }
+        hostEl.removeEventListener('mouseenter', handleMouseEnter);
+        hostEl.removeEventListener('mouseleave', handleMouseLeave);
+        hostEl.removeEventListener('focusin', handleFocusIn);
+        hostEl.removeEventListener('focusout', handleFocusOut);
+        removePortal();
+    };
+}

package/dist/collection/utils/types.js

@@ -1,2 +1,18 @@
-export {};
-//# sourceMappingURL=types.js.map
+// Single source of truth for `pds-text` `size` values. The `as const` tuple is
+// readable at runtime (for validation) and `TextSizeType` is derived from it,
+// so the supported list and the prop type cannot drift apart.
+export const TEXT_SIZES = [
+    '2xl',
+    'xl',
+    'lg',
+    'md',
+    'sm',
+    'xs',
+    '2xs',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+];

package/dist/collection/utils/utils.js

@@ -1,7 +1,69 @@
-export function format(first, middle, last) {
-    return (first || '') + (middle ? ` ${middle}` : '') + (last ? ` ${last}` : '');
-}
 export const hasShadowDom = (el) => {
     return !!el.shadowRoot && !!el.attachShadow;
 };
-//# sourceMappingURL=utils.js.map
+export const debounceEvent = (event, wait) => {
+    const original = event._original || event;
+    return {
+        _original: event,
+        emit: debounce(original.emit.bind(original), wait),
+    };
+};
+export const debounce = (func, wait = 0) => {
+    let timer;
+    return (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(func, wait, ...args);
+    };
+};
+// Add shared color normalization utility to unify token handling across components
+/**
+ * Normalizes color values to ensure consistent CSS variable usage
+ * @param value - Raw token (--token), CSS variable (var(--token)), semantic name, or literal color
+ * @param options.semanticMap - Optional mapping of semantic names to CSS variables
+ * @returns Normalized color value or undefined for invalid inputs
+ */
+export const normalizeColorValue = (value, options) => {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    // Treat whitespace-only as undefined to avoid invalid CSS values
+    if (trimmed === '')
+        return undefined;
+    // If a semantic map is provided and the value matches a key, return mapped CSS var
+    if ((options === null || options === void 0 ? void 0 : options.semanticMap) && options.semanticMap[trimmed]) {
+        return options.semanticMap[trimmed];
+    }
+    // If already a CSS var, pass through
+    if (trimmed.startsWith('var('))
+        return trimmed;
+    // If raw token is provided (e.g., --pine-color-foo), wrap in var(...)
+    if (trimmed.startsWith('--'))
+        return `var(${trimmed})`;
+    // Otherwise treat as literal CSS color value
+    return trimmed;
+};
+export const setColor = (color, customColors) => {
+    // Return an empty object for empty/whitespace/undefined inputs to avoid invalid CSS styles
+    if (!color)
+        return {};
+    const defaultColors = {
+        primary: 'var(--pine-color-text-primary)',
+        secondary: 'var(--pine-color-text-secondary)',
+        neutral: 'var(--pine-color-text-neutral)',
+        accent: 'var(--pine-color-text-accent)',
+        danger: 'var(--pine-color-text-danger)',
+        info: 'var(--pine-color-text-info)',
+        success: 'var(--pine-color-text-success)',
+        warning: 'var(--pine-color-text-warning)',
+    };
+    // Merge defaults with any custom overrides so defaults are preserved
+    const semanticMap = Object.assign(Object.assign({}, defaultColors), (customColors || {}));
+    // Use the shared normalizer so components accept semantic names, raw tokens, var(...), or literals
+    const resolved = normalizeColorValue(color, { semanticMap });
+    // Ensure we never return an undefined style value; if unresolved, omit the property
+    if (!resolved)
+        return {};
+    return {
+        '--color': resolved
+    };
+};

package/dist/docs.d.ts

@@ -38,6 +38,17 @@ interface ComponentCompilerTypeReference {
    * An ID for this type which is unique within a Stencil project.
    */
   id: string;
+  /**
+   * Whether this type was imported as a default import (e.g., `import MyEnum from './my-enum'`)
+   * vs a named import (e.g., `import { MyType } from './my-type'`)
+   */
+  isDefault?: boolean;
+  /**
+   * The name used in the import statement (before any user-defined alias).
+   * For `import { XAxisOption as moo }`, this would be "XAxisOption".
+   * This is the name exported by the source module.
+   */
+  referenceLocation?: string;
 }
 interface ComponentCompilerReferencedType {
   /**
@@ -196,6 +207,10 @@ export interface JsonDocsComponent {
    * Array of component Parts information, generate from `@part` tags
    */
   parts: JsonDocsPart[];
+  /**
+   * Array of custom states defined via @AttachInternals({ states: {...} })
+   */
+  customStates: JsonDocsCustomState[];
   /**
    * Array of metadata describing where the current component is used
    */
@@ -316,6 +331,14 @@ export interface JsonDocsProp {
    * ```
    */
   required: boolean;
+  /**
+   * `true` if the prop has a `get()`. `false` otherwise
+   */
+  getter: boolean;
+  /**
+   * `true` if the prop has a `set()`. `false` otherwise
+   */
+  setter: boolean;
 }
 export interface JsonDocsMethod {
   name: string;
@@ -405,6 +428,28 @@ export interface JsonDocsPart {
    */
   docs: string;
 }
+/**
+ * A descriptor for a Custom State defined via @AttachInternals({ states: {...} })
+ *
+ * Custom states are exposed via the ElementInternals.states CustomStateSet
+ * and can be targeted with the CSS `:state()` pseudo-class.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+ */
+export interface JsonDocsCustomState {
+  /**
+   * The name of the custom state (without dashes)
+   */
+  name: string;
+  /**
+   * The initial/default value of the state
+   */
+  initialValue: boolean;
+  /**
+   * A textual description of the custom state
+   */
+  docs: string;
+}
 /**
  * Represents a parsed block comment in a CSS, Sass, etc. file for a custom property.
  */