@pine-ds/core 5.0.0-mercury.0 → 5.0.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/host-strip.js

@@ -0,0 +1,50 @@
+// The browser-side code below is passed as strings, the same workaround `runAxe` uses: under Jest's
+// coverage instrumentation, a function passed to `page.$eval` is serialized with injected `cov_*`
+// counter calls that don't exist in the browser, which throws a `ReferenceError` there.
+const inBrowser = (page, selector, body, args = null) => page.evaluate(`
+    (() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      const args = ${JSON.stringify(args)};
+      ${body}
+    })()
+  `);
+// Computed properties a host class, style or attribute tends to drive, for the host and everything
+// it renders (its shadow tree, or its light DOM for a shadowless component).
+const snapshotStyles = (page, selector) => inBrowser(page, selector, `
+      const nodes = [el, ...Array.from((el.shadowRoot || el).querySelectorAll('*'))];
+      return nodes.map((node) => {
+        const style = getComputedStyle(node);
+        // No sizes: text width shifts as web fonts load, and inner elements can be mid-animation. The
+        // class check covers what a size would have caught.
+        return [
+          style.display, style.visibility, style.opacity, style.position, style.clip, style.overflow, style.flexDirection, style.flex, style.minHeight, style.gap,
+          style.paddingTop, style.maxWidth, style.color, style.backgroundColor, style.fontWeight,
+          style.borderTopStyle, style.borderTopColor, style.borderTopWidth,
+          style.borderBottomStyle, style.borderBottomColor, style.borderBottomWidth,
+          style.animationName, style.cursor,
+        ].join(' | ');
+      });
+    `);
+/**
+ * Strips the host's `class` (keeping a `consumer` class the markup must carry), its `style`, and any
+ * `removeAttributes`, as a DOM morph does when the server's HTML lacks what the component wrote.
+ * Expects every class and removed attribute to come back, and every computed style of the host and
+ * what it renders to be unchanged.
+ */
+export const expectStylingSurvivesStrip = async (page, selector, { removeAttributes = [] } = {}) => {
+    const host = () => inBrowser(page, selector, `
+        return {
+          classes: Array.from(el.classList).sort(),
+          attributes: args.map((name) => [name, el.getAttribute(name)]),
+        };
+      `, removeAttributes);
+    const before = { host: await host(), styles: await snapshotStyles(page, selector) };
+    await inBrowser(page, selector, `
+      el.setAttribute('class', 'consumer');
+      el.removeAttribute('style');
+      args.forEach((name) => el.removeAttribute(name));
+    `, removeAttributes);
+    await page.waitForChanges();
+    expect(await host()).toEqual(before.host);
+    expect(await snapshotStyles(page, selector)).toEqual(before.styles);
+};

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/test/reduced-motion.js

@@ -0,0 +1,78 @@
+/**
+ * Reads a target's computed `transition-duration` from within `hostTag`,
+ * optionally on a pseudo-element (e.g. `::after`). Works whether `hostTag`
+ * renders to a real shadow root (`shadow: true`) or scoped/light DOM
+ * (`shadow: false` / `scoped: true`) — Pine components use both.
+ *
+ * `innerSelector` may be omitted (or `null`) to read the host element itself.
+ *
+ * Embeds the arguments in a string-evaluated IIFE, the same workaround
+ * `runAxe` uses, rather than passing a real function to `page.$eval`: under
+ * Jest's coverage instrumentation, a function reference gets serialized with
+ * injected `cov_*` counter calls that don't exist in the browser's isolated
+ * execution context, throwing a `ReferenceError` there.
+ */
+async function readTransitionDuration(page, hostTag, innerSelector, pseudoElement) {
+    // Normalise to the `::` form. Chrome, which is what these e2e tests drive,
+    // accepts a bare `after` and returns the pseudo-element's style -- verified,
+    // so no assertion is wrong today. The CSSOM spec treats a colonless value as
+    // invalid and returns the originating element's style instead, which would
+    // turn a knob assertion into a silent re-test of its host. Cheap to not
+    // depend on the lenient reading.
+    const normalisedPseudo = pseudoElement
+        ? `::${pseudoElement.replace(/^:{1,2}/, '')}`
+        : null;
+    const argsJson = JSON.stringify({ hostTag, innerSelector, pseudoElement: normalisedPseudo });
+    return page.evaluate(`
+    (() => {
+      const args = ${argsJson};
+      const el = document.querySelector(args.hostTag);
+      const root = el.shadowRoot || el;
+      const target = args.innerSelector ? root.querySelector(args.innerSelector) : el;
+      return getComputedStyle(target, args.pseudoElement || null).transitionDuration;
+    })()
+  `);
+}
+/**
+ * Asserts that an element's `transition-duration` collapses to `0s` once the
+ * page emulates `prefers-reduced-motion: reduce`.
+ *
+ * This is the runtime counterpart to the `pine-design-system/no-hardcoded-motion`
+ * Stylelint rule: the rule can only see a component's *source* — that it
+ * references `var(--pine-motion-duration-*)` somewhere. It can't see whether
+ * that reference actually reaches the declaration that runs at render time
+ * (a `var()` could be shadowed, overridden, or simply never wired up right).
+ * This closes that gap by reading the real computed style before and after
+ * emulating the preference, so a target that *doesn't* zero out fails loudly
+ * here even if it fooled the lint rule.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const page = await newE2EPage();
+ * await page.setContent('<pds-switch></pds-switch>');
+ * await expectRespectsReducedMotion(page, 'pds-switch', 'input', 'after');
+ * ```
+ *
+ * @param page Stencil E2E page.
+ * @param hostTag Custom element tag hosting the shadow root to read from.
+ * @param innerSelector Selector for the element within `hostTag`'s shadow
+ *   root, or `null`/omitted to read `hostTag` itself.
+ * @param pseudoElement Pseudo-element to read from the target (e.g. `'after'`
+ *   for `::after`), or `null`/omitted to read the element's own style.
+ */
+export async function expectRespectsReducedMotion(page, hostTag, innerSelector = null, pseudoElement = null) {
+    const before = await readTransitionDuration(page, hostTag, innerSelector, pseudoElement);
+    await page.emulateMediaFeatures([{ name: 'prefers-reduced-motion', value: 'reduce' }]);
+    await page.waitForChanges();
+    const after = await readTransitionDuration(page, hostTag, innerSelector, pseudoElement);
+    // `transitionDuration` can list one value per transitioned property
+    // (e.g. "0.2s, 0.2s"); every one of them must have zeroed out.
+    const allZero = after.split(',').every((part) => parseFloat(part.trim()) === 0);
+    if (!allZero) {
+        const target = `${hostTag}${innerSelector ? ` >>> ${innerSelector}` : ''}${pseudoElement ? `::${pseudoElement}` : ''}`;
+        throw new Error(`Expected "${target}" to have a zero transition-duration under prefers-reduced-motion, ` +
+            `but got "${after}" (was "${before}" before emulating the preference). Its transition ` +
+            `is not actually routed through a --pine-motion-duration-* token at render time.`);
+    }
+}