@excom/neutron 0.1.0

package/src/devtools-hook.ts

@@ -0,0 +1,93 @@
+import {
+  type DevtoolsRenderer,
+  injectRenderersIfNeeded,
+  NUCLEUS_DEVTOOLS_HOOK_VERSION,
+  registerRenderer,
+  toDevtoolsJson,
+} from "@excom/kit-devtools";
+
+/**
+ * Nucleus DevTools probe. The hook lives in `@excom/kit-devtools`;
+ * this re-exports it and adds the Neutron renderer.
+ *
+ *   publicize(["neutron", "defined"], { tag, props }): once per `setup()`,
+ *     no `weakElement`; extension audits attr names from it
+ *   publicize(["neutron", "constructed"], { weakElement, tag })
+ *   publicize(["neutron", "connected"], { weakElement, tag, isMoving, isFirstMount })
+ *   publicize(["neutron", "disconnected"], { weakElement, tag, isMoving })
+ *   publicize(["neutron", "effect"], { weakElement, tag, signature, effect, lockDepth, … })
+ *   publicize(["neutron", "commit"], { weakElement, tag, changedProps })
+ *   publicize(["neutron", "error"], { weakElement, tag, errorMessage, errorName })
+ */
+export {
+  attachDevtools,
+  DEVTOOLS_SERIALIZERS,
+  type DevtoolsHook,
+  type DevtoolsRenderer,
+  type DevtoolsRendererKind,
+  getDevtoolsHook,
+  NUCLEUS_DEVTOOLS_HOOK_KEY,
+  NUCLEUS_DEVTOOLS_HOOK_VERSION,
+  pathMatches,
+  publicize,
+  type PublicizeMeta,
+  type PublicizePath,
+} from "@excom/kit-devtools";
+
+export type NeutronInspectSnapshot = {
+  tag: string;
+  id: string | null;
+  isMounted: boolean;
+  wasMounted: boolean;
+  isMoving: boolean;
+  isAdopted: boolean;
+  propNames: string[];
+  /** Primitive-safe prop values. Element/object refs are tagged, not retained. */
+  props: Record<string, unknown>;
+};
+
+export type NeutronRenderer = DevtoolsRenderer & {
+  kind: "neutron";
+  walkRoot: () => Element;
+  isNeutronElement: (el: Element) => boolean;
+  inspect: (el: Element) => NeutronInspectSnapshot | null;
+};
+
+const renderer: NeutronRenderer = {
+  version: NUCLEUS_DEVTOOLS_HOOK_VERSION,
+  kind: "neutron",
+  walkRoot: () => document.body,
+  isNeutronElement: (el) => !!(el as any)?._n_?.ctr,
+  inspect: (el) => {
+    const internal = (el as any)?._n_;
+    if (!internal?.ctr) return null;
+    const propNames = Object.keys(internal.ctr.runtimeConfig?.props ?? {});
+    const props: Record<string, unknown> = {};
+    for (const name of propNames) {
+      try {
+        props[name] = toDevtoolsJson(el[name as keyof typeof el]);
+      } catch {
+        props[name] = "[unreadable]";
+      }
+    }
+    return {
+      tag: el.localName,
+      id: el.id || null,
+      isMounted: !!el["isMounted" as keyof typeof el],
+      wasMounted: !!el["wasMounted" as keyof typeof el],
+      isMoving: !!el["isMoving" as keyof typeof el],
+      isAdopted: !!el["isAdopted" as keyof typeof el],
+      propNames,
+      props,
+    };
+  },
+};
+
+registerRenderer(renderer);
+
+/**
+ * Inject the Neutron renderer into an installed hook (no-op when none, or
+ * when already injected). Called on the first `define()` after a hook is
+ * installed at `document_start`; late attachers use `attachDevtools()`.
+ */
+export const injectRendererIfNeeded = injectRenderersIfNeeded;

package/src/lifecycle-configs.ts

@@ -0,0 +1,304 @@
+import { isCustomCommand, TCommandEvent } from "./command";
+import { NeutronError } from "./neutron-error";
+import type { NeutronInternal as NeutronInternalType } from "./neutron-internal";
+import { AnyFunction, EffectorOptions } from "./types";
+import { isChildEffect, setDebugLifecycleSignature } from "./utils";
+import {
+  Converter,
+  ExecHandlerFn,
+  toArray,
+  unique,
+} from "@excom/kit-utils";
+
+interface TLifecycleConfig {
+  key: string;
+  isBatched: boolean;
+  batchPrefix?: string;
+  triggerFn?: (
+    instance: NeutronInternalType,
+    batchPrefix: string,
+    name: string
+  ) => void;
+  batchNames?: (names: string[]) => string[];
+  batchExecFn?: ExecHandlerFn;
+  effectorOptions?: (nameArray: string[]) => EffectorOptions;
+}
+
+/*
+ * Order matters: several lifecycles share batch names, and earlier
+ * entries run first. `.onConnected()` must beat `.onPropSet("isMounted")`.
+ */
+export const LifecycleConfigs: TLifecycleConfig[] = [
+  {
+    key: "constructed",
+    isBatched: true,
+    batchNames: () => ["message:constructed"],
+  },
+  {
+    key: "connected",
+    isBatched: true,
+    batchNames: () => ["isMounted"],
+    effectorOptions: () => ({
+      validateInput: ([element]) => element.isMounted && [element],
+    }),
+  },
+  {
+    key: "adopted",
+    isBatched: true,
+    batchNames: () => ["isAdopted"],
+    effectorOptions: () => ({
+      validateInput: ([element]) => element.isAdopted && [element],
+    }),
+  },
+  {
+    key: "error",
+    isBatched: true,
+    batchNames: () => ["message:error"],
+    effectorOptions: () => ({
+      validateInput: ([element, notifs]) => [element, notifs["message:error"]],
+    }),
+  },
+  {
+    key: "effect",
+    batchNames: (nameArray) => [...nameArray, "message:first-mount"],
+    isBatched: true,
+    effectorOptions: (nameArray) => ({
+      validateInput: ([element, previous]) =>
+        (element.isMounted || element.wasMounted) &&
+        !!nameArray.find((name) => name in previous) && [element, previous],
+    }),
+  },
+  {
+    key: "propUnset",
+    isBatched: true,
+    batchNames: (nameArray) => [...nameArray, "message:first-mount"],
+    effectorOptions: (nameArray) => ({
+      validateInput: ([element, previous]) =>
+        (element.isMounted || element.wasMounted) &&
+        !!Object.keys(previous).find(
+          (name) =>
+            nameArray.includes(name) &&
+            !(
+              Converter.type(
+                element._n_.ctr.CustomElement.getPropConfig({ prop: name })!
+                  .type
+              )?.prop.isTruthy(element[name]) ?? element[name]
+            )
+        ) && [element, previous],
+      validateOutput: ([element], mutation) =>
+        nameArray.every((name) => {
+          if (
+            name in mutation &&
+            !mutation[name] &&
+            !isChildEffect(
+              mutation[name],
+              element._n_.ctr.CustomElement.getPropConfig({ prop: name })!
+            )
+          ) {
+            throw new NeutronError(
+              `Cannot unset prop ${name} in its own onPropUnset handler.`
+            );
+          }
+          return true;
+        }),
+    }),
+  },
+  {
+    key: "propSet",
+    isBatched: true,
+    batchNames: (nameArray) => [...nameArray, "message:first-mount"],
+    effectorOptions: (nameArray) => ({
+      validateInput: ([element, previous]) =>
+        (element.isMounted || element.wasMounted) &&
+        !!Object.keys(previous).find(
+          (name) =>
+            nameArray.includes(name) &&
+            (Converter.type(
+              element._n_.ctr.CustomElement.getPropConfig({ prop: name })!.type
+            )?.prop.isTruthy(element[name]) ??
+              !!element[name])
+        ) && [element, previous],
+      validateOutput: ([element], mutation) =>
+        nameArray.every((name) => {
+          // child-element effects in own handlers are ok: `.onPropSet("myElement", () => ({myElement: {addListener: [...]}}))`
+          if (
+            mutation[name] &&
+            !isChildEffect(
+              mutation[name],
+              element._n_.ctr.CustomElement.getPropConfig({ prop: name })!
+            )
+          ) {
+            throw new NeutronError(
+              `Cannot set prop ${name} in its own onPropSet handler.`
+            );
+          }
+          return true;
+        }),
+    }),
+  },
+  {
+    key: "propChanged",
+    isBatched: true,
+    batchNames: (nameArray) => [...nameArray, "message:first-mount"],
+    effectorOptions: (nameArray) => ({
+      validateInput: ([element, previous]) =>
+        (element.isMounted || element.wasMounted) &&
+        !!nameArray.find((name) => name in previous) && [element, previous],
+      validateOutput: ([element], mutation) =>
+        nameArray.every((name) => {
+          if (
+            name in mutation &&
+            !isChildEffect(
+              mutation[name],
+              element._n_.ctr.CustomElement.getPropConfig({ prop: name })!
+            )
+          ) {
+            throw new NeutronError(
+              `Cannot change prop ${name} in its own onPropChanged handler.`
+            );
+          }
+          return true;
+        }),
+    }),
+  },
+  {
+    key: "promiseResolved",
+    isBatched: true,
+    batchPrefix: "promise:resolved:",
+    triggerFn: linkPromiseToBatch("onResolved"),
+    effectorOptions: () => ({
+      validateInput: validatePromiseArgs("promise:resolved:"),
+    }),
+  },
+  {
+    key: "promiseRejected",
+    isBatched: true,
+    batchPrefix: "promise:rejected:",
+    triggerFn: linkPromiseToBatch("onRejected"),
+    effectorOptions: () => ({
+      validateInput: validatePromiseArgs("promise:rejected:"),
+    }),
+  },
+  {
+    key: "broadcast",
+    isBatched: false,
+  },
+  {
+    key: "event",
+    isBatched: false,
+  },
+  {
+    key: "eventDefault",
+    isBatched: false,
+    effectorOptions: () => ({
+      delayNextTask: true,
+      validateInput: ([element, e]: [any, Event]) =>
+        element === e.target && !e.defaultPrevented && [element, e],
+    }),
+  },
+  {
+    /*
+     * `command` events (HTML Command API) never bubble; the at-target
+     * check only guards against a hand-made bubbling `Event("command")`.
+     * Runs in a microtask so every listener of the dispatch may still
+     * `preventDefault()`, yet the user activation that invoked it (a
+     * click) is intact for permission prompts and popups.
+     */
+    key: "command",
+    isBatched: false,
+    effectorOptions: (names) => ({
+      delayMicrotask: true,
+      validateInput: ([element, e]: [any, TCommandEvent]) =>
+        element === e.target &&
+        !e.defaultPrevented &&
+        names.includes(e.command) && [element, e],
+    }),
+  },
+  {
+    key: "disconnected",
+    isBatched: true,
+    batchNames: () => ["isMounted"],
+    effectorOptions: () => ({
+      validateInput: ([element]) => !element.isMounted && [element],
+    }),
+  },
+];
+
+export const LifecycleConfigMap: Record<
+  TLifecycleConfig["key"],
+  TLifecycleConfig
+> = LifecycleConfigs.reduce(
+  (acc, config) => {
+    acc[config.key] = config;
+    return acc;
+  },
+  {} as Record<TLifecycleConfig["key"], TLifecycleConfig>
+);
+
+function linkPromiseToBatch(method) {
+  return (instance, batchPrefix, name) => {
+    instance.queueManager.getQueue(name)[method]((state) => {
+      instance.batchManager.notify(batchPrefix + name, state.value);
+    });
+  };
+}
+function validatePromiseArgs(batchPrefix: string) {
+  return ([element, result]) => [
+    element,
+    Object.fromEntries(
+      Object.entries(result as Record<string, unknown>)
+        .filter(([key]) => key.startsWith(batchPrefix))
+        .map(([key, value]) => [key.replace(/(.*):/, ""), value])
+    ),
+  ];
+}
+
+export const registerLifecycle = (
+  ctr: typeof NeutronInternalType,
+  lifecycleName: TLifecycleConfig["key"],
+  nameArg: string | string[],
+  fn: AnyFunction
+) => {
+  const nameArray = unique(toArray(nameArg));
+  if (lifecycleName === "command") {
+    nameArray.forEach((name) => {
+      if (!isCustomCommand(name)) {
+        throw new NeutronError(
+          `Command names must start with "--" (got "${name}"): built-in commands never reach a custom element.`
+        );
+      }
+    });
+  }
+  setDebugLifecycleSignature(fn, lifecycleName, nameArray);
+  ctr.builtConfig.lifecycles[lifecycleName].push([nameArray, fn]);
+  return ctr;
+};
+
+export const unregisterLifecycle = (
+  ctr: typeof NeutronInternalType,
+  lifecycleName: TLifecycleConfig["key"],
+  nameArg: string | string[],
+  fn: AnyFunction
+) => {
+  const nameArray = unique(toArray(nameArg));
+  /* Drop the entry when every name matches `entry[0]`; otherwise
+   * strip only the matching names from `entry[0]`. */
+  ctr.builtConfig.lifecycles[lifecycleName] = ctr.builtConfig.lifecycles[
+    lifecycleName
+  ]
+    .map(([_entryNames, entryFn]) => {
+      if (entryFn === fn) {
+        const entryNames = _entryNames.filter(
+          (name) => !nameArray.includes(name)
+        );
+        if (entryNames.length === 0) {
+          return false;
+        } else {
+          return [entryNames, entryFn];
+        }
+      }
+      return [_entryNames, entryFn];
+    })
+    .filter(Boolean) as [string[], AnyFunction][];
+  return ctr;
+};

package/src/neutron-element.ts

@@ -0,0 +1,72 @@
+import type { NeutronInternal as TNeutronInternal } from "./neutron-internal";
+import type { PropConfig, RuntimeConfig } from "./types";
+
+export class NeutronElement extends HTMLElement {
+  static observedAttributes: string[] = [];
+  static NeutronInternal: typeof TNeutronInternal;
+
+  /* --- PUBLIC: STATIC INTROSPECTION --- */
+  /**
+   * The element's runtime configuration, its `tag`, every prop's
+   * `PropConfig` (keyed by prop name: `prop`, `attr`, `type`, defaults,
+   * `notify`, …), events, broadcasts, methods and lifecycles, as built by
+   * `define()`. `undefined` before the element is defined. Reach it from an
+   * instance through its constructor (`el.constructor.getConfig()`) or from
+   * the registry (`customElements.get("my-tag").getConfig()`). Read-only by
+   * contract: mutating it changes the running definition.
+   */
+  static getConfig(): RuntimeConfig | undefined {
+    return this.NeutronInternal?.runtimeConfig;
+  }
+  /**
+   * One prop's `PropConfig`, looked up by attribute name (`{ attr: "is-open" }`)
+   * or prop name (`{ prop: "isOpen" }`). `undefined` when unknown or before
+   * `define()`.
+   */
+  static getPropConfig({
+    attr,
+    prop,
+  }: {
+    attr?: string;
+    prop?: string;
+  }): PropConfig | undefined {
+    return Object.values(this.getConfig()?.props ?? {}).find((c) =>
+      attr ? c.attr === attr : c.prop === prop
+    );
+  }
+  _n_: TNeutronInternal;
+  isMounted: boolean;
+  isAdopted: boolean;
+  wasMounted: boolean;
+  isMoving: boolean;
+  renderRoot?: HTMLElement;
+
+  constructor() {
+    super();
+    const NeutronInternal = (
+      this.constructor as unknown as typeof NeutronElement
+    ).NeutronInternal;
+    this._n_ = new NeutronInternal(this);
+  }
+
+  /* Native lifecycle callbacks */
+  connectedCallback() {
+    this._n_.connectedCallback();
+  }
+  connectedMoveCallback() {
+    this._n_.connectedMoveCallback();
+  }
+  adoptedCallback() {
+    this._n_.adoptedCallback();
+  }
+  disconnectedCallback() {
+    this._n_.disconnectedCallback();
+  }
+  attributeChangedCallback(
+    name: string,
+    oldValue: string | null,
+    newValue: string | null
+  ) {
+    this._n_.attributeChangedCallback(name, oldValue, newValue);
+  }
+}

package/src/neutron-error.ts

@@ -0,0 +1,6 @@
+export class NeutronError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}