@fluixi/devtools 0.2.0-alpha.2 → 0.2.0-alpha.3

package/dist/kind-filter.js

@@ -0,0 +1,151 @@
+/** Every kind a graph can hold, in the order they are offered. */
+export const FILTERABLE_KINDS = [
+    'state', 'memo', 'effect', 'store', 'resource', 'component', 'provider', 'control', 'router', 'handler',
+    'context', 'directive',
+];
+/** Only `handler` needs renaming; the other kinds read fine as they are. */
+const LABEL = { handler: 'route' };
+/**
+ * Builds the control inside `host`. Call `destroy` to remove it — it holds a document
+ * listener for closing the panel on an outside click.
+ */
+export function createKindFilter(host, options) {
+    const doc = host.ownerDocument;
+    const kinds = options.kinds ?? FILTERABLE_KINDS;
+    const on = new Set(kinds);
+    const root = doc.createElement('div');
+    root.className = 'fx-kinds';
+    const button = doc.createElement('button');
+    button.type = 'button';
+    button.className = 'fx-kinds-button fx-dropdown-btn';
+    button.setAttribute('aria-haspopup', 'true');
+    button.setAttribute('aria-expanded', 'false');
+    button.title = 'Choose which kinds of node the graph draws';
+    const caret = doc.createElement('div');
+    caret.className = 'fx-dropdown-caret';
+    const panel = doc.createElement('div');
+    panel.className = 'fx-kinds-panel';
+    if (options.panelClass) {
+        panel.classList.add(...options.panelClass.split(/\s+/).filter((c) => c));
+    }
+    panel.hidden = true;
+    const all = doc.createElement('input');
+    all.type = 'checkbox';
+    const allRow = doc.createElement('label');
+    allRow.className = 'fx-kinds-all';
+    allRow.append(all, doc.createTextNode('all'));
+    const boxes = new Map();
+    for (const kind of kinds) {
+        const box = doc.createElement('input');
+        box.type = 'checkbox';
+        box.checked = true;
+        const row = doc.createElement('label');
+        row.append(box, doc.createTextNode(LABEL[kind] ?? kind));
+        panel.append(row);
+        boxes.set(kind, box);
+    }
+    panel.prepend(allRow);
+    root.append(button, panel);
+    host.append(root);
+    const everything = () => on.size === kinds.length;
+    // Read back in the order they are offered: a Set re-orders as entries come and go.
+    const chosen = () => kinds.filter((kind) => on.has(kind));
+    function paint() {
+        const name = options.label ?? 'Kinds';
+        button.textContent = everything() ? name : `${name} · ${on.size}`;
+        button.classList.toggle('on', !everything());
+        all.checked = everything();
+        button.appendChild(caret);
+        // Partly selected: show the box as indeterminate rather than guessing a state.
+        all.indeterminate = on.size > 0 && !everything();
+        for (const [kind, box] of boxes)
+            box.checked = on.has(kind);
+    }
+    function report() {
+        options.onChange(everything() ? null : chosen());
+    }
+    for (const [kind, box] of boxes) {
+        box.addEventListener('change', () => {
+            if (box.checked)
+                on.add(kind);
+            else
+                on.delete(kind);
+            paint();
+            report();
+        });
+    }
+    all.addEventListener('change', () => {
+        // Unticking would select nothing, leaving an empty graph with no obvious way back,
+        // so either direction turns everything on.
+        for (const kind of kinds)
+            on.add(kind);
+        paint();
+        report();
+    });
+    const close = () => {
+        panel.hidden = true;
+        button.setAttribute('aria-expanded', 'false');
+    };
+    button.addEventListener('click', (event) => {
+        event.stopPropagation();
+        panel.hidden = !panel.hidden;
+        button.setAttribute('aria-expanded', String(!panel.hidden));
+    });
+    // Stop clicks inside the panel reaching the document listener, which would close it.
+    panel.addEventListener('click', (event) => event.stopPropagation());
+    const away = () => close();
+    const key = (event) => {
+        if (event.key === 'Escape')
+            close();
+    };
+    doc.addEventListener('click', away);
+    doc.addEventListener('keydown', key);
+    paint();
+    return {
+        get selected() {
+            return chosen();
+        },
+        select(next) {
+            on.clear();
+            for (const kind of next ?? kinds)
+                on.add(kind);
+            paint();
+        },
+        destroy() {
+            doc.removeEventListener('click', away);
+            doc.removeEventListener('keydown', key);
+            root.remove();
+        },
+    };
+}
+export const KIND_FILTER_CSS = `
+.fx-kinds { position: relative; display: inline-flex; }
+.fx-kinds-button { white-space: nowrap; }
+/* The hidden attribute is display:none from the user agent, which a class setting display outranks. */
+.fx-kinds-panel[hidden] { display: none; }
+.fx-kinds-panel {
+  position: absolute; top: calc(100% + 4px); z-index: 40;
+  display: grid; gap: 2px; padding: 6px 8px; min-width: 132px;
+  background: var(--fx-panel, #14161c);
+  border: 1px solid var(--fx-line, #262a35); border-radius: 6px;
+  box-shadow: 0 6px 18px rgba(0, 0, 0, .38);
+  }
+.fx-kinds-panel:not(.fx-panel-left){ right: 0; }
+.fx-kinds-panel.fx-panel-left { left: 0; }
+.fx-kinds-panel label {
+  display: flex; align-items: center; gap: 6px;
+  font-size: 11px; color: var(--fx-muted, #8a90a2); cursor: pointer; user-select: none;
+}
+.fx-kinds-panel label:hover { color: var(--fx-label, #e7e9ee); }
+.fx-kinds-panel input { width: 11px; height: 11px; margin: 0; accent-color: var(--fx-accent, #5eead4); }
+.fx-kinds-all {
+  padding-bottom: 4px; margin-bottom: 2px;
+  border-bottom: 1px solid var(--fx-line, #262a35);
+  color: var(--fx-label, #e7e9ee) !important;
+}
+`;
+export const DROPDOWN_FILTER_CSS = `
+.fx-dropdown-btn { background-color: transparent; appearance: none; border: 1px solid var(--line-strong); outline: none; border-radius: .25rem; padding-block: .25rem; padding-inline: .875rem; font-size: .75rem; cursor: pointer }
+.fx-dropdown-btn:hover { border-color: color-mix(in oklab, var(--accent) 50%, transparent); background-color: var(--bg); }
+.fx-dropdown-caret { width: 0;height: 0;border-left: .15rem solid transparent; border-right: .15rem solid transparent; border-top: .15rem solid currentColor; transition: transform 0.2s ease; right: .4rem; top: 50%; color: color-mix(in oklab, var(--muted) 50%, transparent); position: absolute; }
+`;

package/dist/menu.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A labelled dropdown of toggles and actions.
+ *
+ * The graph toolbar had grown to nine bare glyphs. Every one carried a `title`, so the only
+ * way to learn what `⇥` did was to hover it and wait, and a reader who was not the author had
+ * no chance. This is the same shape as the kind filter, which already solved that for kinds:
+ * a named button, and the detail behind it.
+ */
+export type MenuItem = {
+    type: 'toggle';
+    label: string;
+    /** Starting state. Read once. */
+    on?: boolean;
+    hint?: string;
+    onChange: (on: boolean) => void;
+} | {
+    type: 'action';
+    label: string;
+    hint?: string;
+    onRun: () => void;
+};
+export interface MenuOptions {
+    /** What the button says when nothing is on. */
+    label: string;
+    items: readonly MenuItem[];
+    /** The button's own tooltip. */
+    hint?: string;
+    menuClass?: string;
+}
+export interface Menu {
+    /** Set a toggle from outside, by label, for a host restoring what was last used. */
+    set(label: string, on: boolean): void;
+    destroy(): void;
+}
+export declare function createMenu(host: HTMLElement, options: MenuOptions): Menu;
+export declare const MENU_CSS = "\n/* The button itself is styled by DROPDOWN_FILTER_CSS, shared with the kind filter. */\n.fx-menu { position: relative; display: inline-flex; }\n.fx-menu-button { white-space: nowrap; position: relative; padding-inline-end: 1.1rem; }\n/* hidden is display:none from the user agent, which a class setting display outranks. */\n.fx-menu-panel[hidden] { display: none; }\n.fx-menu-panel {\n  position: absolute; top: calc(100% + 4px); z-index: 40;\n  display: grid; gap: 2px; padding: 6px 8px; min-width: 150px;\n  background: var(--fx-panel, #14161c);\n  border: 1px solid var(--fx-line, #262a35); border-radius: 6px;\n  box-shadow: 0 6px 18px rgba(0, 0, 0, .38);\n}\n.fx-menu-panel:not(.fx-panel-left){ right: 0; }\n.fx-menu-panel.fx-panel-left { left: 0; }\n.fx-menu-panel label {\n  display: flex; align-items: center; gap: 6px;\n  font-size: 11px; color: var(--fx-muted, #8a90a2); cursor: pointer; user-select: none;\n}\n.fx-menu-panel label:hover { color: var(--fx-label, #e7e9ee); }\n.fx-menu-panel input { width: 11px; height: 11px; margin: 0; accent-color: var(--fx-accent, #5eead4); }\n.fx-menu-action {\n  text-align: left; padding: 2px 0; border: 0; background: none; cursor: pointer;\n  font: inherit; font-size: 11px; color: var(--fx-muted, #8a90a2);\n  /* A button does not inherit this, so an action read lowercase beside uppercase toggles. */\n  text-transform: inherit; letter-spacing: inherit;\n}\n.fx-menu-action:hover { color: var(--fx-accent, #5eead4); }\n";
+//# sourceMappingURL=menu.d.ts.map

package/dist/menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu.d.ts","sourceRoot":"","sources":["../src/menu.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAChB;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC;CACjC,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEN,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,IAAI;IACnB,oFAAoF;IACpF,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAmGxE;AAED,eAAO,MAAM,QAAQ,y8CA4BpB,CAAC"}

package/dist/menu.js

@@ -0,0 +1,125 @@
+export function createMenu(host, options) {
+    const doc = host.ownerDocument;
+    const root = doc.createElement('div');
+    root.className = 'fx-menu';
+    const button = doc.createElement('button');
+    button.type = 'button';
+    button.className = 'fx-menu-button fx-dropdown-btn';
+    button.setAttribute('aria-haspopup', 'true');
+    button.setAttribute('aria-expanded', 'false');
+    if (options.hint)
+        button.title = options.hint;
+    const caret = doc.createElement('div');
+    caret.className = 'fx-dropdown-caret';
+    const panel = doc.createElement('div');
+    panel.className = 'fx-menu-panel';
+    if (options.menuClass) {
+        panel.classList.add(...options.menuClass.split(/\s+/).filter((c) => c));
+    }
+    panel.hidden = true;
+    const boxes = new Map();
+    for (const item of options.items) {
+        if (item.type === 'action') {
+            const run = doc.createElement('button');
+            run.type = 'button';
+            run.className = 'fx-menu-action';
+            run.textContent = item.label;
+            if (item.hint)
+                run.title = item.hint;
+            run.addEventListener('click', () => {
+                close();
+                item.onRun();
+            });
+            panel.append(run);
+            continue;
+        }
+        const box = doc.createElement('input');
+        box.type = 'checkbox';
+        box.checked = item.on === true;
+        const row = doc.createElement('label');
+        if (item.hint)
+            row.title = item.hint;
+        row.append(box, doc.createTextNode(item.label));
+        box.addEventListener('change', () => {
+            paint();
+            item.onChange(box.checked);
+        });
+        panel.append(row);
+        boxes.set(item.label, box);
+    }
+    root.append(button, panel);
+    host.append(root);
+    /** The count is what makes a folded menu honest: something is on in here. */
+    function paint() {
+        let on = 0;
+        for (const box of boxes.values())
+            if (box.checked)
+                on++;
+        button.textContent = on ? `${options.label} · ${on}` : options.label;
+        // textContent clears it, so the caret goes back after every repaint.
+        button.appendChild(caret);
+        button.classList.toggle('on', on > 0);
+    }
+    function close() {
+        panel.hidden = true;
+        button.setAttribute('aria-expanded', 'false');
+    }
+    button.addEventListener('click', (event) => {
+        event.stopPropagation();
+        panel.hidden = !panel.hidden;
+        button.setAttribute('aria-expanded', String(!panel.hidden));
+    });
+    // Clicks inside must not reach the document listener, which closes it.
+    panel.addEventListener('click', (event) => event.stopPropagation());
+    const away = () => close();
+    const key = (event) => {
+        if (event.key === 'Escape')
+            close();
+    };
+    doc.addEventListener('click', away);
+    doc.addEventListener('keydown', key);
+    paint();
+    return {
+        set(label, on) {
+            const box = boxes.get(label);
+            if (!box)
+                return;
+            box.checked = on;
+            paint();
+        },
+        destroy() {
+            doc.removeEventListener('click', away);
+            doc.removeEventListener('keydown', key);
+            root.remove();
+        },
+    };
+}
+export const MENU_CSS = `
+/* The button itself is styled by DROPDOWN_FILTER_CSS, shared with the kind filter. */
+.fx-menu { position: relative; display: inline-flex; }
+.fx-menu-button { white-space: nowrap; position: relative; padding-inline-end: 1.1rem; }
+/* hidden is display:none from the user agent, which a class setting display outranks. */
+.fx-menu-panel[hidden] { display: none; }
+.fx-menu-panel {
+  position: absolute; top: calc(100% + 4px); z-index: 40;
+  display: grid; gap: 2px; padding: 6px 8px; min-width: 150px;
+  background: var(--fx-panel, #14161c);
+  border: 1px solid var(--fx-line, #262a35); border-radius: 6px;
+  box-shadow: 0 6px 18px rgba(0, 0, 0, .38);
+}
+.fx-menu-panel:not(.fx-panel-left){ right: 0; }
+.fx-menu-panel.fx-panel-left { left: 0; }
+.fx-menu-panel label {
+  display: flex; align-items: center; gap: 6px;
+  font-size: 11px; color: var(--fx-muted, #8a90a2); cursor: pointer; user-select: none;
+}
+.fx-menu-panel label:hover { color: var(--fx-label, #e7e9ee); }
+.fx-menu-panel input { width: 11px; height: 11px; margin: 0; accent-color: var(--fx-accent, #5eead4); }
+.fx-menu-action {
+  text-align: left; padding: 2px 0; border: 0; background: none; cursor: pointer;
+  font: inherit; font-size: 11px; color: var(--fx-muted, #8a90a2);
+  /* A button does not inherit this, so an action read lowercase beside uppercase toggles. */
+  text-transform: inherit; letter-spacing: inherit;
+}
+.fx-menu-action:hover { color: var(--fx-accent, #5eead4); }
+`;

package/dist/observe.d.ts

@@ -0,0 +1,80 @@
+import { type ReactiveObserver } from '@fluixi/reactive/signal';
+import { type RNode } from './instrument.js';
+import type { ReactiveSourceLocation } from './source.js';
+import { type GraphEvent } from './history.js';
+import { type DomNode } from './dom.js';
+export interface ObservedGraph {
+    readonly graph: Map<number, RNode>;
+    /** Ids whose value or run count moved since the last call. Drives the pulse. */
+    sample(): number[];
+    /**
+     * The cursor as it stands. A consumer folding in deltas keeps the one it was given and
+     * asks for what came after it.
+     */
+    readonly revision: number;
+    /**
+     * Ids that moved after `rev`. Unlike `sample`, asking does not consume anything, so two
+     * consumers reading at their own pace each see every change.
+     */
+    changedSince(rev: number): number[];
+    /** Ids dropped after `rev`. Bounded: a consumer further back than that is told to reload. */
+    removedSince(rev: number): number[];
+    /** Whether `rev` is old enough that the removal log no longer covers it. */
+    outrun(rev: number): boolean;
+    /**
+     * Removals since the last call, draining as it goes.
+     *
+     * Superseded by `removedSince`, and kept because the hook that calls it can be older
+     * than this: a browser extension bundles its own and hands the application's observer
+     * to it. Removing the method outright crashed every panel that had not been reloaded.
+     */
+    takeRemoved(): number[];
+    /** What happened since the last call, in order. Empty when history is off. */
+    takeEvents(): GraphEvent[];
+    /** Where this node reaches the page, for whatever is still on it. */
+    elementsFor(id: number): Element[];
+    /** The node driving `element`, or the nearest ancestor that has one. */
+    nodeAt(element: Element | null): number | undefined;
+    /**
+     * What this node rendered, described so it can be shown by a panel that is not in the
+     * page. Stops wherever another tag begins, naming it.
+     */
+    domFor(id: number): DomNode[];
+    /**
+     * The elements this tag returned, and nothing else. Unlike `elementsFor` there is no
+     * fallback to what the values inside it write to, so two tags can never claim the same
+     * element.
+     */
+    renderedFor(id: number): Element[];
+    /**
+     * Write a signal from outside the application. False when the node is not something that
+     * can be written. A memo is computed, and setting it would be a lie the next run undoes.
+     */
+    setValue(id: number, next: unknown): boolean;
+    detach(): void;
+}
+export interface ObserveOptions {
+    /**
+     * Trimmed off a file name that a dev server serves from its own origin. Defaults to the
+     * page's origin, which is what a preview in an iframe wants too.
+     */
+    origin?: string;
+    /**
+     * How to register. Defaults to this copy of the runtime, so pass the application's own
+     * `observeReactiveNodes` when watching from outside its module graph, since a second copy
+     * of the framework watches a graph nobody is using.
+     */
+    observe?: (observer: ReactiveObserver) => () => void;
+    /** Events kept for the timeline. 0 for a host that only draws the graph. */
+    history?: number;
+    /** One stack capture per binding, at creation. Off for a host that never asks. */
+    bindingSources?: boolean;
+    /**
+     * Put a stack location back in the author's file. A frame reports the compiled position and
+     * knows nothing of the file it was generated from; a host with the source maps closes that.
+     * Only stack-derived locations pass through. A compiler mark is already original.
+     */
+    mapSource?: (location: ReactiveSourceLocation) => ReactiveSourceLocation | undefined;
+}
+export declare function observeGraph(options?: ObserveOptions): ObservedGraph;
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAmE,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC9G,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAG9D,OAAO,EAA0B,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAmDhE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACnC,gFAAgF;IAChF,MAAM,IAAI,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACpC,6FAA6F;IAC7F,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACpC,4EAA4E;IAC5E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,WAAW,IAAI,MAAM,EAAE,CAAC;IACxB,8EAA8E;IAC9E,UAAU,IAAI,UAAU,EAAE,CAAC;IAC3B,qEAAqE;IACrE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;IACnC,wEAAwE;IACxE,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IACpD;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7C,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IACrD,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,sBAAsB,GAAG,SAAS,CAAC;CACtF;AAsED,wBAAgB,YAAY,CAAC,OAAO,GAAE,cAAmB,GAAG,aAAa,CA4tBxE"}