@fusion.dev/helix-diagnostics 0.138.0 → 0.140.0

package/dist/manifest.js

@@ -1,42 +1,75 @@
+export const lintOf = (manifest, name) => {
+    const tags = {};
+    for (const module of manifest.modules ?? []) {
+        const family = /^src\/([^/]+)\//.exec(module.path ?? '')?.[1];
+        for (const declaration of module.declarations ?? []) {
+            const tag = declaration.tagName;
+            if (!tag) {
+                continue;
+            }
+            const entry = tags[tag] ?? {
+                attributes: {},
+                family,
+                hooks: [],
+                parts: [],
+                written: [],
+            };
+            tags[tag] = entry;
+            for (const member of declaration.members ?? []) {
+                if (member.readonly && !member.static && member.kind === 'field') {
+                    entry.written.push(member.name, member.name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`));
+                }
+            }
+            for (const attribute of declaration.attributes ?? []) {
+                const values = allowed(attribute.type?.text);
+                entry.attributes[attribute.name] = values ? [...values] : null;
+            }
+            entry.parts.push(...(declaration.cssParts ?? []).map((part) => part.name));
+            entry.hooks.push(...(declaration.cssProperties ?? []).map((hook) => hook.name));
+        }
+    }
+    for (const entry of Object.values(tags)) {
+        entry.written = [...new Set(entry.written)];
+        entry.parts = [...new Set(entry.parts)];
+        entry.hooks = [...new Set(entry.hooks)];
+    }
+    return {
+        package: manifest.helix?.package ?? name,
+        tags,
+        ...(manifest.helix?.version ? { version: manifest.helix.version } : {}),
+    };
+};
+export const lintFor = (tier) => 'lint' in tier ? tier.lint : lintOf(tier.manifest, tier.name);
 export const index = (tiers) => {
     const tags = new Map();
     for (const tier of tiers) {
-        for (const module of tier.manifest.modules ?? []) {
-            const family = /^src\/([^/]+)\//.exec(module.path ?? '')?.[1];
-            for (const declaration of module.declarations ?? []) {
-                const tag = declaration.tagName;
-                if (!tag) {
-                    continue;
-                }
-                let element = tags.get(tag);
-                if (!element) {
-                    element = {
-                        attributes: new Map(),
-                        family,
-                        hooks: new Map(),
-                        parts: new Map(),
-                        written: new Set(),
-                    };
-                    tags.set(tag, element);
-                }
-                for (const member of declaration.members ?? []) {
-                    if (member.readonly && !member.static && member.kind === 'field') {
-                        element.written.add(member.name);
-                        element.written.add(member.name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`));
-                    }
-                }
-                for (const attribute of declaration.attributes ?? []) {
-                    element.attributes.set(attribute.name, allowed(attribute.type?.text));
-                }
-                for (const [field, into] of [
-                    [declaration.cssParts, element.parts],
-                    [declaration.cssProperties, element.hooks],
-                ]) {
-                    for (const entry of field ?? []) {
-                        const publishers = into.get(entry.name) ?? new Set();
-                        publishers.add(tier.name);
-                        into.set(entry.name, publishers);
-                    }
+        const lint = lintFor(tier);
+        for (const [tag, entry] of Object.entries(lint.tags)) {
+            let element = tags.get(tag);
+            if (!element) {
+                element = {
+                    attributes: new Map(),
+                    family: entry.family,
+                    hooks: new Map(),
+                    parts: new Map(),
+                    written: new Set(),
+                };
+                tags.set(tag, element);
+            }
+            for (const name of entry.written) {
+                element.written.add(name);
+            }
+            for (const [name, values] of Object.entries(entry.attributes)) {
+                element.attributes.set(name, values ? new Set(values) : null);
+            }
+            for (const [names, into] of [
+                [entry.parts, element.parts],
+                [entry.hooks, element.hooks],
+            ]) {
+                for (const name of names) {
+                    const publishers = into.get(name) ?? new Set();
+                    publishers.add(lint.package);
+                    into.set(name, publishers);
                 }
             }
         }
@@ -57,9 +90,9 @@ const allowed = (type) => {
 export const versionsOf = (tiers) => {
     const versions = {};
     for (const tier of tiers) {
-        const version = tier.manifest.helix?.version;
-        if (version) {
-            versions[tier.manifest.helix?.package ?? tier.name] = version;
+        const lint = lintFor(tier);
+        if (lint.version) {
+            versions[lint.package] = lint.version;
         }
     }
     return versions;
@@ -83,8 +116,14 @@ const within = (from, to, ceiling) => {
     let previous = Array.from({ length: to.length + 1 }, (_, column) => column);
     for (let row = 1; row <= from.length; row += 1) {
         const current = [row];
+        let least = row;
         for (let column = 1; column <= to.length; column += 1) {
-            current[column] = Math.min((previous[column] ?? 0) + 1, (current[column - 1] ?? 0) + 1, (previous[column - 1] ?? 0) + (from[row - 1] === to[column - 1] ? 0 : 1));
+            const cell = Math.min((previous[column] ?? 0) + 1, (current[column - 1] ?? 0) + 1, (previous[column - 1] ?? 0) + (from[row - 1] === to[column - 1] ? 0 : 1));
+            current[column] = cell;
+            least = Math.min(least, cell);
+        }
+        if (least > ceiling) {
+            return undefined;
         }
         previous = current;
     }

package/dist/overlay.d.ts

@@ -0,0 +1,12 @@
+import type { Report } from './report.js';
+/** What a running instance does with the overlay. */
+export interface Overlay {
+    /** The element, so a change it makes to the page is known for its own. */
+    readonly element: HTMLElement;
+    /** Removes it from the page. */
+    remove(): void;
+    /** Shows a run: the counts on the badge and the findings in the panel. */
+    show(run: Report): void;
+}
+/** Puts the overlay on `page`. */
+export declare const overlayOn: (page: Document) => Overlay;

package/dist/overlay.js

@@ -0,0 +1,300 @@
+import { matchable } from './analyze.js';
+import { OVERLAY } from './page.js';
+import { shownRuntime } from './runtime.js';
+const STYLE = `
+:host {
+  all: initial;
+  --ink: #111113;
+  --muted: #55555c;
+  --ground: #ffffff;
+  --raised: #f4f4f5;
+  --edge: #d4d4d8;
+  --error: #b42318;
+  --warn: #8a5a00;
+  --info: #1d4ed8;
+  color-scheme: light dark;
+  font: 13px/1.45 system-ui, sans-serif;
+  inset-block-end: 16px;
+  inset-inline-end: 16px;
+  position: fixed;
+  z-index: 2147483647;
+}
+@media (prefers-color-scheme: dark) {
+  :host {
+    --ink: #f4f4f5;
+    --muted: #a1a1aa;
+    --ground: #18181b;
+    --raised: #27272a;
+    --edge: #3f3f46;
+    --error: #f97066;
+    --warn: #fdb022;
+    --info: #84adff;
+  }
+}
+[hidden] { display: none !important; }
+.stack {
+  align-items: flex-end;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+button {
+  background: var(--ground);
+  border: 1px solid var(--edge);
+  border-radius: 999px;
+  color: var(--ink);
+  cursor: pointer;
+  font: inherit;
+}
+button:focus-visible, li:focus-visible {
+  outline: 2px solid var(--info);
+  outline-offset: 2px;
+}
+.badge {
+  align-items: center;
+  box-shadow: 0 2px 10px rgb(0 0 0 / 0.18);
+  display: flex;
+  gap: 8px;
+  padding: 6px 12px;
+}
+.dot {
+  block-size: 8px;
+  border-radius: 50%;
+  inline-size: 8px;
+}
+.panel {
+  background: var(--ground);
+  border: 1px solid var(--edge);
+  border-radius: 10px;
+  box-shadow: 0 8px 30px rgb(0 0 0 / 0.24);
+  color: var(--ink);
+  display: flex;
+  flex-direction: column;
+  inline-size: min(440px, calc(100vw - 32px));
+  max-block-size: min(70vh, 560px);
+  overflow: hidden;
+}
+header {
+  align-items: center;
+  border-block-end: 1px solid var(--edge);
+  display: flex;
+  gap: 8px;
+  padding: 10px 12px;
+}
+h2 { font-size: 14px; font-weight: 600; margin: 0; }
+.counts { color: var(--muted); flex: 1; margin: 0; }
+.close { border-radius: 6px; padding: 2px 8px; }
+ol { list-style: none; margin: 0; overflow: auto; padding: 0; }
+li {
+  border-block-end: 1px solid var(--edge);
+  display: grid;
+  gap: 4px;
+  padding: 10px 12px;
+}
+li:last-child { border-block-end: none; }
+.kind { font-weight: 600; }
+.error { color: var(--error); }
+.warn { color: var(--warn); }
+.info { color: var(--info); }
+.message code {
+  background: var(--raised);
+  border-radius: 3px;
+  font: 12px/1.4 ui-monospace, monospace;
+  padding: 1px 4px;
+  white-space: nowrap;
+}
+.subject, pre {
+  font: 12px/1.4 ui-monospace, monospace;
+  margin: 0;
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+}
+pre {
+  background: var(--raised);
+  border-radius: 6px;
+  padding: 6px 8px;
+}
+.where { color: var(--muted); font-size: 12px; }
+.outline {
+  border: 2px dashed var(--error);
+  border-radius: 4px;
+  pointer-events: none;
+  position: fixed;
+}
+`;
+const WORDS = {
+    error: ['error', 'errors'],
+    info: ['info', 'info'],
+    warn: ['warning', 'warnings'],
+};
+const counted = (count, severity) => `${count} ${WORDS[severity][count === 1 ? 0 : 1]}`;
+const make = (tag, name, text) => {
+    const element = document.createElement(tag);
+    if (name) {
+        element.className = name;
+    }
+    if (text !== undefined) {
+        element.textContent = text;
+    }
+    return element;
+};
+const worded = (message) => {
+    const out = make('span', 'message');
+    message.split('`').forEach((piece, at) => {
+        if (piece === '') {
+            return;
+        }
+        out.append(at % 2 === 1 ? make('code', undefined, piece) : document.createTextNode(piece));
+    });
+    return out;
+};
+const locate = (finding, page) => {
+    const markup = /^<([a-z][a-z0-9-]*) ([^\s=>]+)(?:="(.*)")?>$/.exec(finding.subject);
+    let selector;
+    if (markup) {
+        const [, tag, name, value] = markup;
+        selector =
+            value === undefined
+                ? `${tag}[${CSS.escape(name ?? '')}]`
+                : `${tag}[${CSS.escape(name ?? '')}="${CSS.escape(value)}"]`;
+    }
+    else {
+        selector = matchable(finding.subject.split(' { ')[0] ?? '');
+    }
+    if (!selector) {
+        return null;
+    }
+    try {
+        return page.querySelector(selector);
+    }
+    catch {
+        return null;
+    }
+};
+const define = () => {
+    if (customElements.get(OVERLAY)) {
+        return;
+    }
+    customElements.define(OVERLAY, class extends HTMLElement {
+    });
+};
+export const overlayOn = (page) => {
+    define();
+    const element = page.createElement(OVERLAY);
+    const root = element.attachShadow({ mode: 'open' });
+    const style = make('style');
+    style.textContent = STYLE;
+    const badge = make('button', 'badge');
+    badge.type = 'button';
+    badge.hidden = true;
+    badge.setAttribute('aria-expanded', 'false');
+    badge.setAttribute('aria-controls', 'panel');
+    const dot = make('span', 'dot');
+    const label = make('span');
+    badge.append(dot, label);
+    const panel = make('section', 'panel');
+    panel.id = 'panel';
+    panel.hidden = true;
+    panel.setAttribute('aria-label', 'Helix diagnostics');
+    const header = make('header');
+    const title = make('h2', undefined, 'Helix diagnostics');
+    const summary = make('p', 'counts');
+    const close = make('button', 'close', '×');
+    close.type = 'button';
+    close.setAttribute('aria-label', 'Close Helix diagnostics');
+    header.append(title, summary, close);
+    const list = make('ol');
+    panel.append(header, list);
+    const outline = make('div', 'outline');
+    outline.hidden = true;
+    const stack = make('div', 'stack');
+    stack.append(panel, badge);
+    root.append(style, stack, outline);
+    (page.body ?? page.documentElement).append(element);
+    const open = (value) => {
+        panel.hidden = !value;
+        badge.setAttribute('aria-expanded', String(value));
+        if (!value) {
+            outline.hidden = true;
+        }
+    };
+    badge.addEventListener('click', () => open(panel.hasAttribute('hidden')));
+    close.addEventListener('click', () => {
+        open(false);
+        badge.focus();
+    });
+    element.addEventListener('keydown', (event) => {
+        if (event.key === 'Escape' && !panel.hidden) {
+            open(false);
+            badge.focus();
+        }
+    });
+    const point = (target, severity) => {
+        if (!target) {
+            outline.hidden = true;
+            return;
+        }
+        const box = target.getBoundingClientRect();
+        outline.style.borderColor = `var(--${severity})`;
+        outline.style.insetBlockStart = `${box.top - 3}px`;
+        outline.style.insetInlineStart = `${box.left - 3}px`;
+        outline.style.blockSize = `${box.height + 2}px`;
+        outline.style.inlineSize = `${box.width + 2}px`;
+        outline.hidden = false;
+    };
+    const follow = (item, target, severity) => {
+        item.addEventListener('mouseenter', () => point(target(), severity));
+        item.addEventListener('focus', () => point(target(), severity));
+        item.addEventListener('mouseleave', () => point(null));
+        item.addEventListener('blur', () => point(null));
+    };
+    const show = (run) => {
+        const findings = run.findings;
+        const runtime = shownRuntime(run.runtime);
+        const of = (severity) => findings.filter((one) => one.severity === severity).length;
+        const failed = runtime.some((one) => one.level === 'error');
+        const worst = of('error') > 0 || failed ? 'error' : of('warn') > 0 || runtime.length > 0 ? 'warn' : 'info';
+        const counts = [
+            ...['error', 'warn', 'info']
+                .filter((severity) => of(severity) > 0)
+                .map((severity) => counted(of(severity), severity)),
+            ...(runtime.length > 0 ? [`${runtime.length} runtime`] : []),
+        ].join(', ');
+        const total = findings.length + runtime.length;
+        badge.hidden = total === 0;
+        if (total === 0) {
+            open(false);
+        }
+        dot.style.background = `var(--${worst})`;
+        label.textContent = counts;
+        badge.setAttribute('aria-label', `Helix diagnostics: ${counts}`);
+        summary.textContent = run.run.page ? `${counts} on ${run.run.page}` : counts;
+        list.replaceChildren(...findings.map((finding) => {
+            const item = make('li');
+            item.tabIndex = 0;
+            const head = make('span', 'kind');
+            head.append(make('span', finding.severity, `${finding.severity} `), document.createTextNode(finding.kind));
+            item.append(head, make('code', 'subject', finding.subject), worded(finding.message));
+            if (finding.origin) {
+                item.append(make('span', 'where', `in ${finding.origin.sheet}`), make('pre', undefined, finding.origin.cssText));
+            }
+            follow(item, () => locate(finding, page), finding.severity);
+            return item;
+        }), ...runtime.map((one) => {
+            const item = make('li');
+            item.tabIndex = 0;
+            const head = make('span', 'kind');
+            head.append(make('span', one.level, `${one.level} `), document.createTextNode(one.kind));
+            item.append(head);
+            if (one.tag) {
+                item.append(make('code', 'subject', `<${one.tag}>`));
+            }
+            item.append(worded(one.message), make('span', 'where', one.count === 1
+                ? 'Reported by Helix as the page ran'
+                : `Reported by Helix ${one.count} times as the page ran`));
+            follow(item, () => (one.tag ? page.querySelector(one.tag) : null), one.level);
+            return item;
+        }));
+    };
+    return { element, remove: () => element.remove(), show };
+};

package/dist/page.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Everything on a page, gathered in one walk.
+ *
+ * **One walk for every check in a run.** The stylesheets, the usage, the
+ * attributes, the version evidence, and the duplicate check each walked the
+ * whole page, shadow roots included, before this: five walks a run, which a
+ * run by hand never feels and a run after every change would.
+ */
+/**
+ * The tag of the overlay `initDiagnostics()` puts on a page: the one element
+ * diagnostics adds, which it leaves out of everything it counts and reads.
+ */
+export declare const OVERLAY = "helix-diagnostics-overlay";
+/** Every element on a page and every shadow root, from one walk. */
+export interface Page {
+    /**
+     * Every element, the document's and every shadow root's, each shadow
+     * root's elements following the host it belongs to.
+     */
+    elements: Element[];
+    /** Every shadow root, nested ones included. */
+    roots: ShadowRoot[];
+}
+/** Walks `from` once, shadow roots included. */
+export declare const pageOf: (from: ParentNode) => Page;

package/dist/page.js

@@ -0,0 +1,21 @@
+export const OVERLAY = 'helix-diagnostics-overlay';
+const DEPTH = 32;
+export const pageOf = (from) => {
+    const elements = [];
+    const roots = [];
+    const visit = (root, depth) => {
+        if (depth > DEPTH) {
+            return;
+        }
+        for (const element of root.querySelectorAll('*')) {
+            elements.push(element);
+            const shadow = element.shadowRoot;
+            if (shadow) {
+                roots.push(shadow);
+                visit(shadow, depth + 1);
+            }
+        }
+    };
+    visit(from, 0);
+    return { elements, roots };
+};

package/dist/performance.d.ts

@@ -0,0 +1,34 @@
+import type { PerformanceReport } from './report.js';
+/** The key `@fusion.dev/helix-core` hands each first update's timing to. */
+export declare const RENDER_SLOT: unique symbol;
+/** A measure as the page holds it, until a run reads it. */
+export interface Measurer {
+    /** The measures so far. A copy: measuring goes on after it is read. */
+    results(): PerformanceReport;
+    /** Stops measuring, and gives the slot back to whatever held it before. */
+    stop(): void;
+}
+/**
+ * The tag of the Helix element a node belongs to: the node itself, or the
+ * nearest Helix element above it, through shadow roots.
+ */
+export declare const helixOf: (node: Node | null | undefined) => string | undefined;
+/** The value at a fraction of the way through sorted numbers, by nearest rank. */
+export declare const percentile: (sorted: readonly number[], fraction: number) => number;
+/** A layout-shift entry's part, as this reads it. */
+interface Shift {
+    hadRecentInput?: boolean;
+    sources?: ReadonlyArray<{
+        node?: Node | null | undefined;
+    }>;
+    value: number;
+}
+/**
+ * Shares one shift's score out among the Helix elements its sources belong
+ * to, an equal share each. A shift a reader caused, by typing or pressing, is
+ * no fault of the page's, which is how the browser scores it too.
+ */
+export declare const shares: (shift: Shift) => Map<string, number>;
+/** Starts measuring, from now on, and the layout shift and long tasks the browser kept from before. */
+export declare const measure: () => Measurer;
+export {};

package/dist/performance.js

@@ -0,0 +1,121 @@
+import { OVERLAY } from './page.js';
+export const RENDER_SLOT = Symbol.for('fusion.dev/helix/render');
+const KEPT = 1000;
+export const helixOf = (node) => {
+    let at = node;
+    while (at) {
+        if (at.nodeType === 1) {
+            const tag = at.localName;
+            if (tag.startsWith('helix-') && tag !== OVERLAY) {
+                return tag;
+            }
+        }
+        at = at.parentNode ?? at.host ?? null;
+    }
+    return undefined;
+};
+export const percentile = (sorted, fraction) => sorted.length === 0
+    ? 0
+    : (sorted[Math.min(sorted.length - 1, Math.ceil(fraction * sorted.length) - 1)] ?? 0);
+const tenth = (value) => Math.round(value * 10) / 10;
+const thousandth = (value) => Math.round(value * 1000) / 1000;
+export const shares = (shift) => {
+    const out = new Map();
+    const sources = shift.sources ?? [];
+    if (shift.hadRecentInput || sources.length === 0) {
+        return out;
+    }
+    const each = shift.value / sources.length;
+    for (const source of sources) {
+        const tag = helixOf(source.node);
+        if (tag) {
+            out.set(tag, (out.get(tag) ?? 0) + each);
+        }
+    }
+    return out;
+};
+const supports = (type) => typeof PerformanceObserver === 'function' &&
+    (PerformanceObserver.supportedEntryTypes ?? []).includes(type);
+export const measure = () => {
+    const gathered = new Map();
+    const of = (tag) => {
+        let one = gathered.get(tag);
+        if (!one) {
+            one = { durations: [], shift: 0, spans: [] };
+            gathered.set(tag, one);
+        }
+        return one;
+    };
+    const long = [];
+    const store = globalThis;
+    const before = store[RENDER_SLOT];
+    let live = true;
+    const listener = (element, timing) => {
+        if (live && element?.localName !== OVERLAY) {
+            const one = of(element.localName);
+            one.durations.push(timing.duration);
+            if (one.spans.length < KEPT) {
+                one.spans.push({ end: timing.start + timing.duration, start: timing.start });
+            }
+        }
+        if (typeof before === 'function') {
+            before(element, timing);
+        }
+    };
+    store[RENDER_SLOT] = listener;
+    const observers = [];
+    const observe = (type, take) => {
+        if (!supports(type)) {
+            return false;
+        }
+        try {
+            const observer = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    take(entry);
+                }
+            });
+            observer.observe({ buffered: true, type });
+            observers.push(observer);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const layoutShift = observe('layout-shift', (entry) => {
+        for (const [tag, share] of shares(entry)) {
+            of(tag).shift += share;
+        }
+    });
+    const longTasks = observe('longtask', (entry) => {
+        long.push({ end: entry.startTime + entry.duration, start: entry.startTime });
+    });
+    return {
+        results: () => {
+            const tags = {};
+            for (const [tag, one] of [...gathered].sort(([a], [b]) => (a < b ? -1 : 1))) {
+                const sorted = [...one.durations].sort((a, b) => a - b);
+                tags[tag] = {
+                    longTasks: long.filter((task) => one.spans.some((span) => span.start < task.end && span.end > task.start)).length,
+                    render: {
+                        count: sorted.length,
+                        max: tenth(sorted.at(-1) ?? 0),
+                        p50: tenth(percentile(sorted, 0.5)),
+                        p95: tenth(percentile(sorted, 0.95)),
+                    },
+                    shift: thousandth(one.shift),
+                };
+            }
+            return { measured: { layoutShift, longTasks }, tags };
+        },
+        stop: () => {
+            live = false;
+            for (const observer of observers) {
+                observer.disconnect();
+            }
+            if (store[RENDER_SLOT] === listener) {
+                store[RENDER_SLOT] = before;
+            }
+        },
+    };
+};