@excom/neutron 0.1.0

package/support/tests/effects.test.ts

@@ -0,0 +1,253 @@
+import { Neutron } from "../../src/neutron";
+import { NeutronError } from "../../src/neutron-error";
+import { effector, processEffectorResult } from "../../src/utils/effect";
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { KitLogger } from "@excom/kit-logger";
+import { observeProperty } from "@excom/kit-utils";
+
+Neutron({
+  tag: "order-host",
+  props: {
+    childEl: { type: HTMLElement, store: "weak" },
+    stepText: String,
+    provision: Object,
+    recordFn: Function,
+    payload: Object,
+  },
+})
+  .defineMethods({
+    // applies whatever effect the caller passes
+    run: (_el, effect) => effect,
+  })
+  .define();
+
+const mount = async () => {
+  const el = fixture<any>(`<order-host></order-host>`);
+  await wait(0);
+  return el;
+};
+
+describe("Effects: application", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("applies the keys of one effect in the documented order", async () => {
+    const el = await mount();
+    const order: string[] = [];
+    observeProperty(el, "childEl", () => {
+      order.push("childEl");
+    });
+    observeProperty(el, "stepText", () => {
+      order.push("stepText");
+    });
+    observeProperty(el, "provision", () => {
+      order.push("provision");
+    });
+    el.recordFn = function () {
+      order.push(`method:${this === el}`);
+    };
+    el.addEventListener("order-host-done", () => {
+      order.push("emit");
+    });
+    // remove runs before add, so a listener removed and re-added in the
+    // same effect ends up registered exactly once
+    const fnX = vi.fn();
+    el.run({ addListener: ["order-host-x", fnX] });
+
+    const child = document.createElement("span");
+    const result = el.run({
+      emit: ["order-host-done"],
+      recordFn: [],
+      provision: { ready: true },
+      stepText: "step",
+      childEl: child,
+      addListener: ["order-host-x", fnX],
+      removeListener: ["order-host-x", fnX],
+      returns: "done",
+    });
+    expect(result).toBe("done");
+    expect(order).toEqual([
+      "childEl",
+      "stepText",
+      "method:true",
+      "provision",
+      "emit",
+    ]);
+    expect(el.childEl).toBe(child);
+    expect(el.provision).toEqual({ ready: true });
+    el.dispatchEvent(new CustomEvent("order-host-x"));
+    expect(fnX).toHaveBeenCalledTimes(1);
+  });
+
+  it("collects `returns` across array effects and skips empty / non-object entries", async () => {
+    const el = await mount();
+    expect(
+      el.run([
+        { stepText: "a" },
+        null,
+        false,
+        { stepText: "b", returns: 1 },
+        { returns: 2 },
+      ])
+    ).toEqual([1, 2]);
+    expect(el.stepText).toBe("b");
+    expect(el.run({ stepText: "c" })).toBeUndefined();
+    expect(el.stepText).toBe("c");
+    // non-POJO results are ignored
+    expect(el.run(new Map())).toBeUndefined();
+    expect(el.run(undefined)).toBeUndefined();
+  });
+
+  it("calls native methods and Function props with array arguments; ignores empty values", async () => {
+    const el = await mount();
+    el.recordFn = vi.fn();
+    const onEmpty = vi.fn();
+    el.addEventListener("order-host-empty", onEmpty);
+    el.run({
+      setAttribute: ["data-marker", "set"],
+      focus: null,
+      blur: undefined,
+      recordFn: false,
+      emit: null,
+      emits: "",
+    });
+    expect(el.getAttribute("data-marker")).toBe("set");
+    expect(el.recordFn).not.toHaveBeenCalled();
+    expect(onEmpty).not.toHaveBeenCalled();
+    el.run({ recordFn: ["a", "b"] });
+    expect(el.recordFn).toHaveBeenCalledWith("a", "b");
+    // a function held by an Object prop is a value, so it is replaced, not called
+    el.payload = () => "fn";
+    el.run({ payload: 5 });
+    expect(el.payload).toBe(5);
+  });
+
+  it("rejects non-array arguments for calls", async () => {
+    const el = await mount();
+    expect(() => el.run({ emit: true })).toThrow(NeutronError);
+    expect(() => el.run({ emit: true })).toThrow(
+      "Cannot call function `emit` on order-host - arguments must be an array. Received: `true`..."
+    );
+    expect(() => el.run({ setAttribute: "data-marker" })).toThrow(
+      "Cannot call function `setAttribute` on order-host - arguments must be an array. Received: `data-marke`..."
+    );
+    const unnamed = { toString: () => "", constructor: { name: "" } };
+    expect(() => el.run({ setAttribute: unnamed })).toThrow(
+      "Received: unknown"
+    );
+  });
+
+  it("validates element-prop effects", async () => {
+    const el = await mount();
+    expect(() => el.run({ childEl: { title: "x" } })).toThrow(
+      "Cannot set properties of `childEl` on element. Element must be set as a property first."
+    );
+    expect(() => el.run({ childEl: "nope" })).toThrow(
+      "Cannot set property `childEl` on order-host - value must be an element or an object."
+    );
+    const child = document.createElement("span");
+    el.run({ childEl: child });
+    el.run({ childEl: { title: "nested" } });
+    expect(child.title).toBe("nested");
+    el.run({ childEl: null });
+    expect(el.childEl).toBe(null);
+    // renderRoot is always treated as an element prop
+    const root = document.createElement("div");
+    el.run({ renderRoot: root });
+    el.run({ renderRoot: { title: "root" } });
+    expect(el.renderRoot).toBe(root);
+    expect(root.title).toBe("root");
+  });
+});
+
+describe("Effects: effector()", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns the same wrapper when given an effector and warns", () => {
+    const warn = vi.spyOn(KitLogger, "warn").mockImplementation(() => {});
+    const wrapped = effector(() => ({ title: "t" }));
+    expect(effector(wrapped)).toBe(wrapped);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain("is already an effector");
+  });
+
+  it("returns several `returns` values as an array and undefined without any", () => {
+    const div = document.createElement("div");
+    expect(
+      effector(() => [{ returns: 1 }, { title: "x" }, { returns: 2 }]).call(div)
+    ).toEqual([1, 2]);
+    expect(effector(() => ({ title: "y" })).call(div)).toBeUndefined();
+    expect(div.title).toBe("y");
+  });
+
+  it("validateInput reshapes arguments and validateOutput can veto a result", () => {
+    const div = document.createElement("div");
+    const fn = vi.fn((_el, n: number) => ({ title: `n${n}`, returns: n }));
+    const run = effector(fn, {
+      validateInput: ([el, n]) => [el, n * 2],
+      validateOutput: (_args, result: any) => result.returns < 10,
+    });
+    expect(run.call(div, 2)).toBe(4);
+    expect(div.title).toBe("n4");
+    expect(run.call(div, 10)).toBeUndefined();
+    expect(div.title).toBe("n4");
+
+    const skipped = vi.fn(() => ({ title: "no" }));
+    expect(
+      effector(skipped, { validateInput: () => false }).call(div)
+    ).toBeUndefined();
+    expect(skipped).not.toHaveBeenCalled();
+  });
+
+  it("rethrows errors with or without a host element", () => {
+    const div = document.createElement("div");
+    expect(() =>
+      effector(() => {
+        throw new Error("unhosted");
+      })()
+    ).toThrow("unhosted");
+    expect(() =>
+      effector(() => {
+        throw new Error("hosted");
+      }).call(div)
+    ).toThrow("hosted");
+  });
+
+  it("delayNextTask defers the effect to the next task and returns a promise", async () => {
+    const div = document.createElement("div");
+    const p = effector(() => ({ title: "later", returns: "r" }), {
+      delayNextTask: true,
+    }).call(div);
+    expect(p).toBeInstanceOf(Promise);
+    expect(div.title).toBe("");
+    expect(await p).toBe("r");
+    expect(div.title).toBe("later");
+  });
+
+  it("processEffectorResult ignores non-object results and merges style", () => {
+    const div = document.createElement("div");
+    expect(processEffectorResult(div, null)).toBeUndefined();
+    expect(processEffectorResult(div, 0)).toBeUndefined();
+    expect(
+      processEffectorResult(div, {
+        returns: "r",
+        style: { color: "red" },
+      })
+    ).toBe("r");
+    expect(div.style.color).toBe("red");
+    processEffectorResult(div, { style: { marginTop: "1px" } });
+    expect(div.style.color).toBe("red");
+    expect(div.style.marginTop).toBe("1px");
+  });
+});

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

@@ -0,0 +1,331 @@
+import { Neutron } from "../../src/neutron";
+import { NeutronElement } from "../../src/neutron-element";
+import { NeutronError } from "../../src/neutron-error";
+import {
+  createPropConfig,
+  initRenderRootConfig,
+  isBuiltInElement,
+} from "../../src/utils/element";
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { TokenList } from "@excom/kit-utils";
+
+describe("Prop configuration", () => {
+  it("rejects incomplete configs, protected prop names, and protected attribute names", () => {
+    const build = (props: Record<string, unknown>) => () =>
+      Neutron({ tag: "bad-host", props: props as any });
+    expect(build({ badProp: {} })).toThrow(NeutronError);
+    expect(build({ badProp: {} })).toThrow(
+      'Incorrect property config: "badProp"'
+    );
+    expect(build({ content: String })).toThrow(
+      'Cannot use protected prop name: "content"'
+    );
+    expect(build({ renderRoot: HTMLElement })).toThrow(NeutronError);
+    expect(build({ qValue: String })).toThrow(
+      'Cannot use protected attr: "q-value"'
+    );
+    expect(build({ onValue: String })).toThrow(
+      'Cannot use protected attr: "on-value"'
+    );
+    // default props are allowed to use otherwise protected names
+    expect(
+      createPropConfig("isMounted", { type: Boolean, attr: false }, true).prop
+    ).toBe("isMounted");
+  });
+
+  it("expands a bare constructor and honours custom serializers", () => {
+    const bare = createPropConfig("labelText", String);
+    expect(bare).toMatchObject({
+      prop: "labelText",
+      attr: "label-text",
+      type: String,
+      store: "default",
+      notify: false,
+      isValid: null,
+    });
+    expect(bare.defaultValue()).toBe(null);
+
+    const custom = {
+      serialize: (v: unknown) => v,
+      deserialize: (v: unknown) => v,
+    };
+    expect(
+      createPropConfig("secretText", { type: String, store: custom as any })
+    ).toMatchObject({
+      serialize: custom.serialize,
+      deserialize: custom.deserialize,
+      store: custom,
+    });
+
+    const weak = createPropConfig("childEl", {
+      type: HTMLElement,
+      store: "weak",
+    });
+    expect(weak.attr).toBe(false);
+    const div = document.createElement("div");
+    expect(weak.serialize(div)).toBeInstanceOf(WeakRef);
+    expect(weak.deserialize(weak.serialize(div))).toBe(div);
+    // an unknown store name falls back to the default serializer
+    expect(
+      createPropConfig("childEl", { type: HTMLElement, store: "bogus" as any })
+        .serialize
+    ).toBe(bare.serialize);
+  });
+
+  it("initRenderRootConfig defaults the tag and derives defaultSlots from shadow", () => {
+    expect(initRenderRootConfig(undefined)).toBeUndefined();
+    expect(initRenderRootConfig({})).toEqual({
+      tag: "div",
+      shadow: undefined,
+      defaultSlots: false,
+    });
+    expect(initRenderRootConfig({ shadow: "open" })).toEqual({
+      tag: "div",
+      shadow: "open",
+      defaultSlots: true,
+    });
+    expect(
+      initRenderRootConfig({
+        tag: "main",
+        shadow: "closed",
+        defaultSlots: false,
+      })
+    ).toEqual({ tag: "main", shadow: "closed", defaultSlots: false });
+    expect(
+      initRenderRootConfig({ shadow: "bogus" as any, defaultSlots: true })
+    ).toEqual({ tag: "div", shadow: undefined, defaultSlots: true });
+  });
+});
+
+describe("Prop reflection", () => {
+  const ReflectHost = Neutron({
+    tag: "reflect-props",
+    props: {
+      labelText: String,
+      countValue: Number,
+      isOpen: Boolean,
+      tagNames: TokenList,
+      payload: Object,
+      childEl: { type: HTMLElement, store: "weak" },
+      hardEl: HTMLElement,
+      secretText: {
+        type: String,
+        store: {
+          serialize: (v: unknown) => (v == null ? v : `s:${v}`),
+          deserialize: (v: unknown) =>
+            typeof v === "string" ? v.replace(/^s:/, "") : v,
+        },
+      },
+    },
+  }).onPropChanged(["labelText", "countValue"], vi.fn());
+  ReflectHost.define();
+
+  it("reflects primitives in both directions", () => {
+    const el = document.createElement("reflect-props") as any;
+    // String (observed attribute: read back from the prop store)
+    el.labelText = 5;
+    expect(el.getAttribute("label-text")).toBe("5");
+    expect(el.labelText).toBe("5");
+    el.setAttribute("label-text", "from-attr");
+    expect(el.labelText).toBe("from-attr");
+    el.labelText = null;
+    expect(el.hasAttribute("label-text")).toBe(false);
+    expect(el.labelText).toBe(null);
+    // Number
+    el.countValue = 3;
+    expect(el.getAttribute("count-value")).toBe("3");
+    el.setAttribute("count-value", "4.5");
+    expect(el.countValue).toBe(4.5);
+    el.setAttribute("count-value", "not-a-number");
+    expect(el.countValue).toBe(null);
+    el.setAttribute("count-value", "");
+    expect(el.countValue).toBe(null);
+    el.countValue = 7;
+    el.countValue = "";
+    expect(el.hasAttribute("count-value")).toBe(false);
+    // Boolean (unobserved attribute: parsed from the attribute on read)
+    el.isOpen = true;
+    expect(el.getAttribute("is-open")).toBe("");
+    el.isOpen = false;
+    expect(el.hasAttribute("is-open")).toBe(false);
+    el.setAttribute("is-open", "anything");
+    expect(el.isOpen).toBe(true);
+    el.removeAttribute("is-open");
+    expect(el.isOpen).toBe(false);
+    // TokenList
+    el.tagNames = ["a", "", null, "b"];
+    expect(el.getAttribute("tag-names")).toBe("a b");
+    expect(el.tagNames).toEqual(["a", "b"]);
+    el.setAttribute("tag-names", " x  y ");
+    expect(el.tagNames).toEqual(["x", "y"]);
+    el.tagNames = null;
+    expect(el.hasAttribute("tag-names")).toBe(false);
+    expect(el.tagNames).toBe(null);
+    // custom serializer wraps the attribute value only
+    el.secretText = "abc";
+    expect(el.getAttribute("secret-text")).toBe("s:abc");
+    expect(el.secretText).toBe("abc");
+  });
+
+  it("stores rich props on the instance, weakly when configured", () => {
+    const el = document.createElement("reflect-props") as any;
+    el.payload = { a: 1 };
+    expect(el.hasAttribute("payload")).toBe(false);
+    expect(el.payload).toEqual({ a: 1 });
+    expect(el._n_.propStore.payload).toEqual({ a: 1 });
+    const child = document.createElement("span");
+    el.childEl = child;
+    expect(el._n_.propStore.childEl).toBeInstanceOf(WeakRef);
+    expect(el.childEl).toBe(child);
+    el.hardEl = child;
+    expect(el._n_.propStore.hardEl).toBe(child);
+    el.childEl = null;
+    expect(el.childEl).toBe(null);
+    // only props with a reaction observe their attribute
+    expect(ReflectHost.CustomElement.observedAttributes).toEqual([
+      "label-text",
+      "count-value",
+    ]);
+  });
+});
+
+describe("renderRoot", () => {
+  Neutron({
+    tag: "root-light",
+    props: {},
+    renderRoot: { tag: "section" },
+  }).define();
+  Neutron({
+    tag: "root-shadow",
+    props: {},
+    renderRoot: { shadow: "open" },
+  }).define();
+  Neutron({
+    tag: "root-closed",
+    props: {},
+    renderRoot: { tag: "main", shadow: "closed", defaultSlots: false },
+  }).define();
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("appends a light-DOM render root once, on first connect", async () => {
+    const el = fixture<any>(`<root-light><p>kept</p></root-light>`);
+    await wait(0);
+    expect(el.shadowRoot).toBe(null);
+    expect(el.renderRoot.localName).toBe("section");
+    expect(el.lastElementChild).toBe(el.renderRoot);
+    expect(el.querySelector("p")!.textContent).toBe("kept");
+    expect(el.querySelector("slot")).toBe(null);
+    el.remove();
+    await wait(0);
+    document.body.append(el);
+    expect(el.querySelectorAll("section")).toHaveLength(1);
+  });
+
+  it("attaches an open shadow root with a display:contents host and an adopt slot", async () => {
+    const el = fixture<any>(`<root-shadow></root-shadow>`);
+    await wait(0);
+    const root = el.shadowRoot as ShadowRoot;
+    expect(root).not.toBe(null);
+    expect(el.renderRoot.parentNode).toBe(root);
+    expect(el.renderRoot.localName).toBe("div");
+    expect(el.renderRoot.getAttribute("style")).toContain("display: contents");
+    const slot = root.querySelector(
+      "slot[name=neutron-adopt]"
+    ) as HTMLSlotElement;
+    expect(slot).not.toBe(null);
+
+    // slotted templates are imported into the shadow root; other slotted
+    // nodes are ignored
+    el.innerHTML = `<template slot="neutron-adopt"><p class="adopted">hi</p></template><span slot="neutron-adopt">no</span>`;
+    slot.dispatchEvent(new Event("slotchange"));
+    expect(root.querySelectorAll(".adopted")).toHaveLength(1);
+    expect(root.querySelector("span")).toBe(null);
+    // a re-import replaces the previous content instead of duplicating it
+    slot.dispatchEvent(new Event("slotchange"));
+    expect(root.querySelectorAll(".adopted")).toHaveLength(1);
+  });
+
+  it("supports a closed shadow root without default slots", async () => {
+    const el = fixture<any>(`<root-closed></root-closed>`);
+    await wait(0);
+    expect(el.shadowRoot).toBe(null);
+    const root = el.renderRoot.parentNode as ShadowRoot;
+    expect(root).toBeInstanceOf(ShadowRoot);
+    expect(root.mode).toBe("closed");
+    expect(el.renderRoot.localName).toBe("main");
+    expect(root.querySelector("slot")).toBe(null);
+  });
+});
+
+describe("Element definition", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("Neutron() without props still defines a working element", async () => {
+    const Empty = Neutron({ tag: "empty-host" } as any);
+    Empty.define();
+    const el = fixture<any>(`<empty-host></empty-host>`);
+    await wait(0);
+    expect(el.isMounted).toBe(true);
+    expect(Object.keys(Empty.runtimeConfig.props)).toEqual([
+      "isMounted",
+      "isAdopted",
+      "wasMounted",
+      "isMoving",
+      "renderRoot",
+    ]);
+    expect(isBuiltInElement(el)).toBe(false);
+    expect(isBuiltInElement(undefined as any)).toBe(false);
+  });
+});
+
+describe("static introspection", () => {
+  it("getConfig() returns the runtime config after define() and undefined before", () => {
+    const Builder = Neutron({
+      tag: "config-probe",
+      props: { isOpen: Boolean, openStage: Number, _secret: String },
+      events: { toggled: { prefixWithTag: true } },
+    });
+    const Ctor = Builder.CustomElement as unknown as typeof NeutronElement;
+    expect(Ctor.getConfig()).toBeUndefined();
+    Builder.define();
+    const config = Ctor.getConfig()!;
+    expect(config.tag).toBe("config-probe");
+    expect(Object.keys(config.props)).toEqual(
+      expect.arrayContaining(["isOpen", "openStage", "_secret"])
+    );
+    expect(config.lifecycles.propSet).toBeDefined();
+    // reachable through the registry and an instance's constructor
+    const Registered = customElements.get("config-probe") as typeof NeutronElement;
+    expect(Registered.getConfig()).toBe(config);
+    const el = document.createElement("config-probe");
+    expect((el.constructor as typeof NeutronElement).getConfig()).toBe(config);
+  });
+
+  it("getPropConfig() looks a prop up by attr or prop name", () => {
+    const Ctor = customElements.get("config-probe") as typeof NeutronElement;
+    expect(Ctor.getPropConfig({ attr: "open-stage" })).toMatchObject({
+      prop: "openStage",
+      attr: "open-stage",
+      type: Number,
+    });
+    expect(Ctor.getPropConfig({ prop: "isOpen" })).toMatchObject({
+      attr: "is-open",
+      type: Boolean,
+    });
+    expect(Ctor.getPropConfig({ attr: "nope" })).toBeUndefined();
+    expect(Ctor.getPropConfig({ prop: "nope" })).toBeUndefined();
+  });
+});

package/support/tests/entry.test.ts

@@ -0,0 +1,68 @@
+import * as barrel from "../../index";
+import { NeutronError } from "../../src/neutron-error";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { NUCLEUS_DEVTOOLS_HOOK_KEY } from "@excom/kit-devtools";
+
+describe("Package entry", () => {
+  afterEach(() => {
+    delete (globalThis as Record<string, unknown>)[
+      NUCLEUS_DEVTOOLS_HOOK_KEY
+    ];
+  });
+
+  it("re-exports the public surface", () => {
+    expect(barrel.Neutron).toBeTypeOf("function");
+    expect(barrel.NeutronElement).toBeTypeOf("function");
+    expect(barrel.NeutronInternal).toBeTypeOf("function");
+    expect(barrel.TokenList).toBeTypeOf("function");
+    expect(barrel.attachDevtools).toBeTypeOf("function");
+    expect(barrel.effector).toBeTypeOf("function");
+    expect(barrel.compose).toBe(barrel.Neutron.compose);
+    expect(barrel.Neutron.DOM.TokenList).toBe(barrel.TokenList);
+    expect(barrel.Neutron.attachDevtools).toBe(barrel.attachDevtools);
+  });
+
+  it("NeutronError carries its class name", () => {
+    const err = new NeutronError("boom");
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(NeutronError);
+    expect(err.name).toBe("NeutronError");
+    expect(err.message).toBe("boom");
+    class SubError extends NeutronError {}
+    expect(new SubError("x").name).toBe("SubError");
+  });
+
+  it("publishes `neutron/defined` with the tag and prop / attr pairs when an element is defined", () => {
+    const published: Array<{ path: string[]; meta: Record<string, unknown> }> =
+      [];
+    barrel.attachDevtools({
+      version: 1,
+      publicize: (path, meta) => published.push({ path: [...path], meta }),
+    });
+    barrel.Neutron({
+      tag: "defined-host",
+      props: {
+        labelText: String,
+        hostEl: { type: HTMLElement, store: "weak" },
+      },
+    });
+    const defined = published.filter(
+      (p) => p.path.join("/") === "neutron/defined"
+    );
+    expect(defined).toHaveLength(1);
+    expect(defined[0].meta).toEqual({
+      tag: "defined-host",
+      props: [
+        { prop: "labelText", attr: "label-text" },
+        { prop: "hostEl", attr: false },
+      ],
+    });
+    // a definition, not an instance: nothing to deref
+    expect(defined[0].meta.weakElement).toBeUndefined();
+  });
+});