@excom/quark 0.1.0

package/support/tests/diagnostics.test.ts

@@ -0,0 +1,224 @@
+/**
+ * `@warn` / `@debug` / `@error` statements inside rules and blocks: they
+ * evaluate on the matched element and report to the logger and the
+ * DevTools hook; `@warn` / `@error` once per element and rule, `@debug` on
+ * every application. Nothing is written to the document.
+ */
+import { Quark } from "../../index";
+import { QuarkLogger } from "../../src/utils";
+import type { QuarkRenderer } from "../../src/devtools-hook";
+import {
+  type DevtoolsHook,
+  NUCLEUS_DEVTOOLS_HOOK_KEY,
+  pathMatches,
+  type PublicizeMeta,
+  type PublicizePath,
+} from "@excom/kit-devtools";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { createSheet, flush, mount, unregisterAll } from "./helpers";
+
+type Spy = ReturnType<typeof vi.spyOn>;
+type LogArg = { message?: string; values?: unknown[] };
+
+const messages = (spy: Spy) =>
+  spy.mock.calls
+    .map(([arg]) => String((arg as LogArg)?.message ?? arg))
+    .filter((m) => m.startsWith("Quark @"));
+const values = (spy: Spy) =>
+  spy.mock.calls
+    .map(([arg]) => arg as LogArg)
+    .filter((arg) => String(arg?.message).startsWith("Quark @"))
+    .map((arg) => arg.values);
+
+describe("@warn / @debug / @error", () => {
+  let warn: Spy;
+  let debug: Spy;
+  let error: Spy;
+  beforeEach(() => {
+    warn = vi.spyOn(QuarkLogger, "warn").mockImplementation(() => {});
+    debug = vi.spyOn(QuarkLogger, "debug").mockImplementation(() => {});
+    error = vi.spyOn(QuarkLogger, "error").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    unregisterAll();
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+    delete (globalThis as Record<string, unknown>)[
+      NUCLEUS_DEVTOOLS_HOOK_KEY
+    ];
+  });
+
+  it("warns once per element and rule, naming the selector; the selector is the condition", async () => {
+    const { root } = mount(
+      `<img id="a" src="a.png"><img id="b" src="b.png" alt="fine">`,
+      `img:not([alt]) { @warn "img needs alt"; }`
+    );
+    await flush();
+    expect(messages(warn)).toEqual([
+      "Quark @warn (img:not([alt])): img needs alt",
+    ]);
+    expect(values(warn)).toEqual([["img needs alt"]]);
+    const a = root.querySelector("#a")!;
+    const b = root.querySelector("#b")!;
+    // `a` stops and starts matching again: no second warning for it
+    a.setAttribute("alt", "");
+    await flush();
+    a.removeAttribute("alt");
+    await flush();
+    expect(messages(warn)).toHaveLength(1);
+    // a new offender is its own warning
+    b.removeAttribute("alt");
+    await flush();
+    expect(messages(warn)).toHaveLength(2);
+    // nothing was written to the document
+    expect([...a.attributes].map((attr) => attr.name)).toEqual(["id", "src"]);
+  });
+
+  it("@debug reports every application and again when a binding it reads changes", async () => {
+    const { root } = mount(
+      `<section id="host" data-count="1"><span bind-count></span></section>`,
+      `#host {
+        $count: +attr("data-count");
+        @debug "count", $count;
+        [bind-count] { content: $count; }
+      }`
+    );
+    await flush();
+    expect(values(debug)).toEqual([["count", 1]]);
+    root.querySelector("#host")!.setAttribute("data-count", "2");
+    await flush();
+    expect(values(debug).at(-1)).toEqual(["count", 2]);
+    expect(values(debug)).toHaveLength(2);
+    expect(root.querySelector("[bind-count]")!.textContent).toBe("2");
+  });
+
+  it("@error reports at error level, inside an @on block with event data", async () => {
+    const { root } = mount(
+      `<form id="f"><button type="button">go</button></form>`,
+      `#f { @on request-failed { @error "request failed", event.detail.code; } }`
+    );
+    await flush();
+    expect(messages(error)).toEqual([]);
+    root
+      .querySelector("#f")!
+      .dispatchEvent(
+        new CustomEvent("request-failed", {
+          bubbles: true,
+          detail: { code: 502 },
+        })
+      );
+    await flush();
+    expect(messages(error)).toEqual(["Quark @error (#f): request failed 502"]);
+    expect(values(error)).toEqual([["request failed", 502]]);
+  });
+
+  it("reports one value per comma-list item and a single expression as one value", async () => {
+    mount(
+      `<p id="p"></p>`,
+      `#p { $pair: (1, 2); @debug $pair; @debug "a", "b"; @debug (x: 1); }`
+    );
+    await flush();
+    expect(values(debug)).toEqual([[[1, 2]], ["a", "b"], [{ x: 1 }]]);
+    expect(messages(debug)[2]).toBe('Quark @debug (#p): {"x":1}');
+  });
+
+  it("publishes quark/diagnostic with level, values, expression and the element", async () => {
+    const publications: { path: PublicizePath; meta: PublicizeMeta }[] = [];
+    const hook: DevtoolsHook = {
+      version: 1,
+      publicize: (path, meta) => {
+        publications.push({ path, meta });
+      },
+    };
+    Quark.attachDevtools(hook);
+    const { root } = mount(
+      `<img id="a" src="a.png">`,
+      `img:not([alt]) { @warn "img needs alt", attr("src"); }`
+    );
+    await flush();
+    const records = publications
+      .filter((p) => pathMatches(p.path, ["quark", "diagnostic"]))
+      .map((p) => p.meta);
+    expect(records).toHaveLength(1);
+    expect(records[0]).toMatchObject({
+      level: "warn",
+      key: "@warn",
+      tag: "img",
+      selector: "img:not([alt])",
+      expression: '"img needs alt", attr("src")',
+      values: ["img needs alt", "a.png"],
+      message: "img needs alt a.png",
+    });
+    expect((records[0].weakElement as WeakRef<Element>).deref()).toBe(
+      root.querySelector("#a")
+    );
+  });
+
+  it("lists diagnostics on the rule for DevTools", async () => {
+    const renderers: QuarkRenderer[] = [];
+    Quark.attachDevtools({
+      version: 1,
+      inject: (renderer) => {
+        renderers.push(renderer as QuarkRenderer);
+      },
+    });
+    const { quark, register } = createSheet(
+      `<p id="p"></p>`,
+      `#p { data-a: 1; @warn "w"; @debug "d", 1; }`
+    );
+    register();
+    await flush();
+    const sheet = renderers
+      .find((r) => r.kind === "quark")!
+      .sheets()
+      .find((s) => s.sheetId === quark.id)!;
+    expect(sheet.rules[0].diagnostics).toEqual([
+      { level: "warn", expression: '"w"' },
+      { level: "debug", expression: '"d", 1' },
+    ]);
+    expect(sheet.rules[0].declarations).toEqual([
+      { key: "data-a", value: "1" },
+    ]);
+  });
+
+  it("rejects statements outside a rule at build", () => {
+    new Quark({ src: '@warn "top"; @delay 10 { x: 1; }' });
+    const built = error.mock.calls.map(([arg]) =>
+      String((arg as LogArg)?.message)
+    );
+    expect(built).toContain("Quark: @warn must be written inside a rule");
+    expect(built).toContain("Quark: @delay must be written inside a rule");
+  });
+
+  it("reports a failing expression as an error, not a diagnostic", async () => {
+    mount(`<p id="p"></p>`, `#p { @warn nope(); }`);
+    await flush();
+    expect(messages(warn)).toEqual([]);
+    expect(
+      error.mock.calls.some(([arg]) =>
+        String((arg as LogArg)?.message).includes(
+          "Could not resolve expression"
+        )
+      )
+    ).toBe(true);
+  });
+
+  it("works inside @view-transition blocks and nested rules", async () => {
+    mount(
+      `<div id="host"><span></span><span></span></div>`,
+      `#host { @view-transition { span { @warn "in block"; } } }`
+    );
+    await flush();
+    expect(messages(warn)).toEqual([
+      "Quark @warn (#host span): in block",
+      "Quark @warn (#host span): in block",
+    ]);
+  });
+});

package/support/tests/dispatch.view.test.ts

@@ -0,0 +1,43 @@
+import "@excom/quark-sheet";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  click,
+  expectComplexity,
+  flush,
+  installDemoModules,
+  measureComplexity,
+  mountView,
+  readDemo,
+  restoreDemoModules,
+} from "./view-helpers";
+
+describe("dispatch view", () => {
+  beforeEach(() => installDemoModules());
+  afterEach(() => {
+    document.body.innerHTML = "";
+    restoreDemoModules();
+  });
+
+  it("relays a click to the panel as a custom event the panel's own block turns into State", async () => {
+    const { root, quark } = await mountView(readDemo(import.meta.url, "dispatch"));
+    const panel = root.querySelector("[aria-label='panel']")!;
+    const meter = measureComplexity(quark!);
+    click(root.querySelector("button"));
+    await flush();
+    const budget = meter.take();
+    meter.stop();
+    expect(panel.getAttribute("data-pings")).toBe("1");
+    expect(root.querySelector("output")?.textContent).toBe("pinged 1×");
+    click(root.querySelector("button"));
+    await flush();
+    expect(panel.getAttribute("data-pings")).toBe("2");
+    expect(root.querySelector("output")?.textContent).toBe("pinged 2×");
+    expectComplexity(budget);
+  });
+});

package/support/tests/element-api.test.ts

@@ -0,0 +1,202 @@
+/**
+ * `element.quark`: the JS side of bindings (`setProperty` /
+ * `setProperties` / `removeProperty` / `getPropertyValue`) on every
+ * element, and how sheets react to those writes.
+ */
+import { Quark } from "../../index";
+import { BINDING_CHANGE_EVENT } from "../../src/bindings";
+import { installElementApi, QuarkElementApi } from "../../src/element-api";
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { createSheet, flush, mount, unregisterAll } from "./helpers";
+
+describe("element.quark", () => {
+  afterEach(() => {
+    unregisterAll();
+    document.body.innerHTML = "";
+  });
+
+  it("is a lazy, stable accessor on every element, SVG included", () => {
+    const div = document.createElement("div");
+    expect(div.quark).toBeInstanceOf(QuarkElementApi);
+    expect(div.quark).toBe(div.quark);
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "g");
+    expect(svg.quark).toBeInstanceOf(QuarkElementApi);
+    expect(svg.quark).not.toBe(div.quark);
+    // not enumerable: never serialized alongside real properties
+    expect(Object.keys(div)).not.toContain("quark");
+  });
+
+  it("installs once and stays configurable", () => {
+    const before = Object.getOwnPropertyDescriptor(Element.prototype, "quark");
+    installElementApi();
+    expect(
+      Object.getOwnPropertyDescriptor(Element.prototype, "quark")?.get
+    ).toBe(before?.get);
+    expect(before?.configurable).toBe(true);
+    // a foreign prototype gets its own accessor
+    const proto = {};
+    installElementApi(proto);
+    expect(typeof Object.getOwnPropertyDescriptor(proto, "quark")?.get).toBe(
+      "function"
+    );
+  });
+
+  it("writes a binding on the owner and re-runs readers below it", async () => {
+    const { root, quark } = mount(
+      `<main><span bind-x></span></main>`,
+      `main { $x: "a"; }
+       [bind-x] { content: $x; }`
+    );
+    await flush();
+    const main = root.querySelector("main")!;
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("a");
+    expect(main.quark.setProperty("$x", "b")).toBe(true);
+    await flush();
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("b");
+    // same value: no change, no re-run
+    const runs = quark.rules[1].numberOfRuns;
+    expect(main.quark.setProperty("x", "b")).toBe(false);
+    await flush();
+    expect(quark.rules[1].numberOfRuns).toBe(runs);
+  });
+
+  it("works on an element no rule matched and shadows an ancestor's binding", async () => {
+    const { root } = mount(
+      `<main><section><span bind-x></span></section></main>`,
+      `main { $x: "outer"; }
+       [bind-x] { content: $x; }`
+    );
+    await flush();
+    const section = root.querySelector("section")!;
+    section.quark.setProperty("$x", "inner");
+    await flush();
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("inner");
+    expect(section.quark.getPropertyValue("$x")).toBe("inner");
+    // removeProperty = unset: the reader falls through to the ancestor
+    expect(section.quark.removeProperty("$x")).toBe(true);
+    await flush();
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("outer");
+    expect(section.quark.getPropertyValue("x")).toBe("outer");
+    expect(section.quark.removeProperty("$x")).toBe(false);
+  });
+
+  it("getPropertyValue resolves upward like a rule would", () => {
+    const root = fixture<HTMLElement>(
+      `<div><main><section><span></span></section></main></div>`
+    );
+    const main = root.querySelector("main")!;
+    const span = root.querySelector("span")!;
+    expect(span.quark.getPropertyValue("$missing")).toBeUndefined();
+    main.quark.setProperty("$list", [1, 2]);
+    expect(span.quark.getPropertyValue("$list")).toEqual([1, 2]);
+    // by value: a new object is a change, an equal one is not
+    expect(main.quark.setProperty("$list", [1, 2])).toBe(false);
+    expect(main.quark.setProperty("$list", [1, 2, 3])).toBe(true);
+  });
+
+  it("setProperties stores every value before announcing any of them", async () => {
+    const { root } = mount(
+      `<main><span bind-sum></span></main>`,
+      `main { $a: 1; $b: 1; }
+       [bind-sum] { content: "#{$a}+#{$b}"; }`
+    );
+    await flush();
+    const main = root.querySelector("main")!;
+    const seen: string[] = [];
+    root.addEventListener(BINDING_CHANGE_EVENT, () => {
+      seen.push(root.querySelector("[bind-sum]")?.textContent ?? "");
+      seen.push(`${main.quark.getPropertyValue("$a")}/${main.quark.getPropertyValue("$b")}`);
+    });
+    expect(main.quark.setProperties({ $a: 2, b: 3 })).toBe(true);
+    await flush();
+    expect(root.querySelector("[bind-sum]")?.textContent).toBe("2+3");
+    // both values were stored when the first change event fired
+    expect(seen[1]).toBe("2/3");
+    expect(main.quark.setProperties({ $a: 2, $b: 3 })).toBe(false);
+  });
+
+  it("tags the change event with sheetId null for DevTools", () => {
+    const el = fixture<HTMLElement>(`<div></div>`);
+    const heard = vi.fn();
+    el.addEventListener(BINDING_CHANGE_EVENT, (e) =>
+      heard((e as CustomEvent).detail)
+    );
+    el.quark.setProperty("$k", 1);
+    expect(heard).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "$k", sheetId: null })
+    );
+  });
+
+  it("is State, not an event: a write before the sheet registers is read on the first run", async () => {
+    const { root, register } = createSheet(
+      `<main><span bind-x></span></main>`,
+      `[bind-x] { content: $x; }`
+    );
+    root.querySelector("main")!.quark.setProperty("$x", "early");
+    register();
+    await flush();
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("early");
+  });
+
+  it("reaches readers in another sheet below the owner", async () => {
+    const root = fixture<HTMLElement>(
+      `<div><main><div id="s1"></div><section><div id="s2"></div><span bind-x></span></section></main></div>`
+    );
+    const outer = new Quark({ src: `:scope { $x: "one"; }`, options: { isScoped: true } });
+    outer.register({ sheetElement: root.querySelector("#s1") as HTMLElement });
+    const inner = new Quark({ src: `[bind-x] { content: $x; }`, options: { isScoped: true } });
+    inner.register({ sheetElement: root.querySelector("#s2") as HTMLElement });
+    await flush();
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("one");
+    root.querySelector("main")!.quark.setProperty("$x", "two");
+    await flush();
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("two");
+  });
+
+  it("a rule's def re-running rewrites a JS value (last writer wins)", async () => {
+    const { root } = mount(
+      `<main><span bind-x></span></main>`,
+      `main { $x: attr("data-mode"); }
+       [bind-x] { content: $x; }`
+    );
+    await flush();
+    const main = root.querySelector("main")!;
+    main.quark.setProperty("$x", "js");
+    await flush();
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("js");
+    // the def's dependency changes: the rule writes again and wins
+    main.setAttribute("data-mode", "rule");
+    await flush();
+    expect(root.querySelector("[bind-x]")?.textContent).toBe("rule");
+  });
+
+  it("lets a @use handler raise state without a signal box", async () => {
+    const { root } = mount(
+      `<div data-demo-counter><button></button><output></output></div>`,
+      `:scope { $count: 0; }
+       button { @on click (handle: bump(closest("[data-demo-counter]"))); }
+       output { content: "#{$count}"; }`,
+      {
+        bump: (owner: Element) => () => {
+          owner.quark.setProperty(
+            "$count",
+            ((owner.quark.getPropertyValue("$count") as number) ?? 0) + 1
+          );
+        },
+      }
+    );
+    await flush();
+    const button = root.querySelector("button")!;
+    button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    await flush();
+    expect(root.querySelector("output")?.textContent).toBe("2");
+  });
+});