@fusion.dev/helix-diagnostics 0.137.0 → 0.139.0

package/dist/overlay.js

@@ -0,0 +1,278 @@
+import { matchable } from './analyze.js';
+import { OVERLAY } from './page.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 = (finding) => {
+        const target = finding ? locate(finding, page) : null;
+        if (!target) {
+            outline.hidden = true;
+            return;
+        }
+        const box = target.getBoundingClientRect();
+        outline.style.borderColor = `var(--${finding?.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 show = (run) => {
+        const findings = run.findings;
+        const of = (severity) => findings.filter((one) => one.severity === severity).length;
+        const worst = of('error') > 0 ? 'error' : of('warn') > 0 ? 'warn' : 'info';
+        const counts = ['error', 'warn', 'info']
+            .filter((severity) => of(severity) > 0)
+            .map((severity) => counted(of(severity), severity))
+            .join(', ');
+        badge.hidden = findings.length === 0;
+        if (findings.length === 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));
+            }
+            item.addEventListener('mouseenter', () => point(finding));
+            item.addEventListener('focus', () => point(finding));
+            item.addEventListener('mouseleave', () => point(undefined));
+            item.addEventListener('blur', () => point(undefined));
+            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/report.d.ts

@@ -87,7 +87,7 @@ export interface Finding {
     tag: string;
 }
 /** Every fault class, stable across versions. */
-export declare const KINDS: readonly ['dead-hook', 'dead-part', 'duplicate-registration', 'manifest-skew', 'unforwarded-part', 'unknown-tag'];
+export declare const KINDS: readonly ['dead-hook', 'dead-part', 'duplicate-registration', 'invalid-value', 'manifest-skew', 'unforwarded-part', 'unknown-attribute', 'unknown-tag'];
 /** A fault class. */
 export type Kind = (typeof KINDS)[number];
 /** How serious a finding is. */
@@ -204,6 +204,13 @@ export interface Configuration {
             sample: number;
         };
     };
+    /** Where `initDiagnostics()` hands each run, beside the console. */
+    sinks: {
+        /** The overlay on the page. */
+        overlay: boolean;
+        /** The relay, `helix diagnostics`: off, on at its own address, or at this one. */
+        relay: boolean | string;
+    };
     /** Each override in effect, from the file or the call. */
     overrides: Array<{
         kind: Kind;

package/dist/report.js

@@ -2,8 +2,10 @@ export const KINDS = [
     'dead-hook',
     'dead-part',
     'duplicate-registration',
+    'invalid-value',
     'manifest-skew',
     'unforwarded-part',
+    'unknown-attribute',
     'unknown-tag',
 ];
 export const CATEGORIES = [

package/dist/rules.js

@@ -4,8 +4,10 @@ export const SHIPPED_RULES = {
     'dead-hook': 'error',
     'dead-part': 'error',
     'duplicate-registration': 'error',
+    'invalid-value': 'error',
     'manifest-skew': 'error',
     'unforwarded-part': 'warn',
+    'unknown-attribute': 'error',
     'unknown-tag': 'error',
 };
 const SEVERITIES = new Set(['error', 'info', 'off', 'warn']);

package/dist/schedule.d.ts

@@ -0,0 +1,57 @@
+/**
+ * When `initDiagnostics()` runs: debounced, idle, and bounded by its own cost.
+ *
+ * - **After a change**, once changes stop for `quiet` milliseconds, or after
+ *   `longest` milliseconds whatever keeps changing: a page that never stops,
+ *   such as a carousel adding slides, would otherwise never be judged.
+ * - **In an idle moment**, at most `idle` milliseconds later.
+ * - **Never sooner than `gap` after the last run, nor sooner than `factor`
+ *   times its duration**, so a slow page is judged less often.
+ * - **Never in a hidden tab**: a change there waits for the tab to be shown.
+ * - **Never when nothing changed** since the last run.
+ *
+ * The browser's hooks are passed in, so a spec drives it with small numbers
+ * and a pretend tab.
+ */
+/** How long each wait is, in milliseconds. */
+export interface Timing {
+    /** How long changes must stop for before a run. */
+    quiet: number;
+    /** The longest an idle callback may wait. */
+    idle: number;
+    /** The least time between the end of one run and the start of the next. */
+    gap: number;
+    /** The least time between runs, as a multiple of the last run's duration. */
+    factor: number;
+    /** The longest a change waits for the page to go quiet. */
+    longest: number;
+}
+/** The shipped timing. */
+export declare const TIMING: Timing;
+/** What the schedule asks of the browser. */
+export interface Browser {
+    /** Whether the tab is hidden now. */
+    hidden(): boolean;
+    /** Calls `then` once in an idle moment, at most `timeout` later; returns a cancel. */
+    idle(then: () => void, timeout: number): () => void;
+    /** The time now, in milliseconds. */
+    now(): number;
+    /** Calls `then` when the tab is next shown; returns a removal. */
+    shown(then: () => void): () => void;
+}
+/** The browser's own hooks, with a timer where a browser has no idle callback. */
+export declare const browser: () => Browser;
+/** A schedule: told of changes, it decides when `run` runs. */
+export interface Schedule {
+    /** Something changed: a run follows, as the schedule allows. */
+    poke(): void;
+    /** Ends it: nothing more runs. */
+    stop(): void;
+}
+/**
+ * A schedule for `run`, which returns how long it took in milliseconds.
+ *
+ * One run at a time, and a change during a run is a change after it: the run
+ * that follows sees it.
+ */
+export declare const schedule: (run: () => number, timing?: Timing, on?: Browser) => Schedule;

package/dist/schedule.js

@@ -0,0 +1,84 @@
+export const TIMING = { factor: 20, gap: 2000, idle: 3000, longest: 10000, quiet: 1000 };
+export const browser = () => ({
+    hidden: () => globalThis.document?.visibilityState === 'hidden',
+    idle: (then, timeout) => {
+        if (typeof globalThis.requestIdleCallback === 'function') {
+            const id = globalThis.requestIdleCallback(then, { timeout });
+            return () => globalThis.cancelIdleCallback(id);
+        }
+        const id = setTimeout(then, 1);
+        return () => clearTimeout(id);
+    },
+    now: () => globalThis.performance?.now() ?? Date.now(),
+    shown: (then) => {
+        const listener = () => {
+            if (globalThis.document?.visibilityState !== 'hidden') {
+                globalThis.document?.removeEventListener('visibilitychange', listener);
+                then();
+            }
+        };
+        globalThis.document?.addEventListener('visibilitychange', listener);
+        return () => globalThis.document?.removeEventListener('visibilitychange', listener);
+    },
+});
+export const schedule = (run, timing = TIMING, on = browser()) => {
+    let dirty = false;
+    let since = Number.POSITIVE_INFINITY;
+    let live = true;
+    let ended = Number.NEGATIVE_INFINITY;
+    let last = 0;
+    let cancel;
+    let quiet;
+    let wait;
+    const go = () => {
+        cancel = undefined;
+        if (!live || !dirty) {
+            return;
+        }
+        if (on.hidden()) {
+            cancel = on.shown(settle);
+            return;
+        }
+        const rest = Math.max(timing.gap, timing.factor * last) - (on.now() - ended);
+        if (rest > 0) {
+            wait = setTimeout(go, rest);
+            return;
+        }
+        cancel = on.idle(() => {
+            cancel = undefined;
+            if (!live || !dirty) {
+                return;
+            }
+            dirty = false;
+            since = Number.POSITIVE_INFINITY;
+            last = run();
+            ended = on.now();
+            if (dirty) {
+                settle();
+            }
+        }, timing.idle);
+    };
+    const settle = () => {
+        if (!live) {
+            return;
+        }
+        clearTimeout(quiet);
+        clearTimeout(wait);
+        cancel?.();
+        cancel = undefined;
+        quiet = setTimeout(go, Math.min(timing.quiet, Math.max(0, since + timing.longest - on.now())));
+    };
+    return {
+        poke: () => {
+            dirty = true;
+            since = Math.min(since, on.now());
+            settle();
+        },
+        stop: () => {
+            live = false;
+            clearTimeout(quiet);
+            clearTimeout(wait);
+            cancel?.();
+        },
+    };
+};

package/dist/usage.d.ts

@@ -1,5 +1,6 @@
 import type { Answered, Located } from './collect.js';
 import type { Published } from './manifest.js';
+import { type Page } from './page.js';
 import type { Usage } from './report.js';
 /** The element counts, before the stylesheets add theirs. */
 type Counted = Pick<Usage, 'axes' | 'composed' | 'slots' | 'tags'>;
@@ -10,7 +11,7 @@ type Counted = Pick<Usage, 'axes' | 'composed' | 'slots' | 'tags'>;
  */
 export declare const loadedVersions: () => string[];
 /** The elements in the page now, counted once each. */
-export declare const walk: (from: Document) => Counted;
+export declare const walk: (from: Document, page?: Page) => Counted;
 /**
  * The counts for the tags a manifest lists, and the rest apart as `unlisted`.
  *
@@ -40,7 +41,14 @@ export interface Watcher {
  * Two watchers on one page both count: a second one keeps the first's
  * listener and calls it too.
  */
-export declare const watch: (from?: Document) => Watcher;
+export declare const watch: (from?: Document, { onRender, }?: {
+    /**
+     * Called as each Helix element renders for the first time, after it is
+     * counted: how `initDiagnostics()` hears that the page changed when an
+     * element upgrades without adding anything to the DOM.
+     */
+    onRender?: ((element: Element) => void) | undefined;
+}) => Watcher;
 /**
  * The parts and hooks a page's stylesheets reach for, where the manifest or
  * the element's own styles say they exist. A dead one is a finding and is not

package/dist/usage.js

@@ -1,4 +1,5 @@
 import { parts, targets } from './analyze.js';
+import { OVERLAY, pageOf } from './page.js';
 const SLOT = Symbol.for('fusion.dev/helix/usage');
 const AXES = ['emphasis', 'material', 'separation', 'tone'];
 const bump = (into, key, by = 1) => {
@@ -19,7 +20,7 @@ export const loadedVersions = () => {
 };
 const tally = (counted, element) => {
     const tag = element.localName;
-    if (!tag.startsWith('helix-')) {
+    if (!tag.startsWith('helix-') || tag === OVERLAY) {
         return;
     }
     const root = element.getRootNode();
@@ -42,20 +43,11 @@ const tally = (counted, element) => {
         }
     }
 };
-const everyElement = (from, visit, depth = 0) => {
-    if (depth > 32) {
-        return;
-    }
-    for (const element of from.querySelectorAll('*')) {
-        visit(element);
-        if (element.shadowRoot) {
-            everyElement(element.shadowRoot, visit, depth + 1);
-        }
-    }
-};
-export const walk = (from) => {
+export const walk = (from, page = pageOf(from)) => {
     const counted = empty();
-    everyElement(from, (element) => tally(counted, element));
+    for (const element of page.elements) {
+        tally(counted, element);
+    }
     return counted;
 };
 export const listed = (counted, tags) => {
@@ -76,7 +68,7 @@ export const listed = (counted, tags) => {
         unlisted,
     };
 };
-export const watch = (from = document) => {
+export const watch = (from = document, { onRender, } = {}) => {
     const counted = empty();
     const seen = new WeakSet();
     const see = (element) => {
@@ -91,13 +83,16 @@ export const watch = (from = document) => {
     const listener = (element) => {
         if (live) {
             see(element);
+            onRender?.(element);
         }
         if (typeof before === 'function') {
             before(element);
         }
     };
     store[SLOT] = listener;
-    everyElement(from, see);
+    for (const element of pageOf(from).elements) {
+        see(element);
+    }
     return {
         counts: () => structuredClone(counted),
         stop: () => {
@@ -114,32 +109,49 @@ export const styled = (rules, tags, answered, values = true) => {
         hookValues: {},
         parts: {},
     };
+    const listing = new Map();
+    for (const [tag, element] of tags) {
+        for (const property of element.hooks.keys()) {
+            listing.set(property, [...(listing.get(property) ?? []), tag]);
+        }
+    }
+    const count = (located, tag, property) => {
+        bump(under(counted.hooks, tag, () => ({})), property);
+        if (!values) {
+            return;
+        }
+        const value = (located.rule.style?.getPropertyValue?.(property) ?? '').trim().slice(0, 200);
+        if (value !== '') {
+            bump(under(under(counted.hookValues, tag, () => ({})), property, () => ({})), value);
+        }
+    };
     for (const located of rules) {
         const selector = located.rule.selectorText;
-        if (!selector?.includes('helix-')) {
+        if (!selector) {
             continue;
         }
-        for (const { names, tag } of parts(selector)) {
+        for (const { names, tag } of selector.includes('helix-') ? parts(selector) : []) {
             for (const name of names) {
                 if (tags.get(tag)?.parts.has(name)) {
                     bump(under(counted.parts, tag, () => ({})), name);
                 }
             }
         }
-        for (const tag of targets(selector)) {
-            for (const property of Array.from(located.rule.style ?? [])) {
-                if (property.startsWith('--') &&
-                    (tags.get(tag)?.hooks.has(property) || answered.get(tag)?.has(property))) {
-                    bump(under(counted.hooks, tag, () => ({})), property);
-                    if (values) {
-                        const value = (located.rule.style?.getPropertyValue?.(property) ?? '')
-                            .trim()
-                            .slice(0, 200);
-                        if (value !== '') {
-                            bump(under(under(counted.hookValues, tag, () => ({})), property, () => ({})), value);
-                        }
+        const named = targets(selector).filter((tag) => tags.has(tag));
+        for (const property of Array.from(located.rule.style ?? [])) {
+            if (!property.startsWith('--')) {
+                continue;
+            }
+            if (named.length > 0) {
+                for (const tag of named) {
+                    if (tags.get(tag)?.hooks.has(property) || answered.get(tag)?.has(property)) {
+                        count(located, tag, property);
                     }
                 }
+                continue;
+            }
+            for (const tag of listing.get(property) ?? []) {
+                count(located, tag, property);
             }
         }
     }

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.137.0";
+export declare const VERSION = "0.139.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.137.0';
+export const VERSION = '0.139.0';