@excom/neutron 0.1.0

package/support/docs/LIFECYCLES.md

@@ -0,0 +1,69 @@
+# Lifecycles
+
+Chain `.on*` handlers that return effects; Neutron applies them, tracks listeners, and routes errors.
+
+## Handlers
+
+Each handler receives the element first, then any lifecycle-specific argument, and returns an [effect](./EFFECTS.md). Prefer effects over mutating the element directly. Every `on*` has an `off*` twin that unregisters the same function.
+
+```ts
+Neutron({ tag: "panel-host", props: { isReady: Boolean } })
+  .onConstructed(() => ({ /* runs in the constructor, before connect */ }))
+  .onConnected(() => ({
+    // every connect, including reconnects
+    isReady: true,
+    emit: ["panel-host-ready"],
+  }))
+  .onDisconnected((el) => ({
+    // tear down; `el.isMoving` is true when a disconnect is followed by a connect in the same tick
+    isReady: false,
+  }))
+  .onAdopted(() => ({}))
+  .onError((_el, err) => {
+    console.error(err);
+  });
+```
+
+Disconnect is settled one microtask after `disconnectedCallback`. If the element is re-inserted before then (a DOM move), `onDisconnected` and `onConnected` both still run, with `isMoving` set. An error thrown by any handler is routed to `onError(el, error)`; without an `onError`, it is rethrown.
+
+Reactions to prop changes, events, commands and promises are their own pages: [Prop reactions](./PROP_REACTIONS.md), [Events](./EVENTS.md), [Commands](./COMMANDS.md), [Promise props](./PROMISE_PROPS.md).
+
+## Destructure the element argument
+
+Prefer `({ prop }) => …` over `(el) => …`. A handler that only ever sees the values it names cannot reach for `el.setAttribute`, `el.querySelector(…).value = …` or any other imperative mutation — reading the signature is enough to know the handler is pure, and the effect it returns is the whole story.
+
+```ts
+Neutron({ tag: "price-tag", props: { amount: Number, currency: String } })
+  .onPropChanged(["amount", "currency"], ({ amount, currency }) => ({
+    ariaLabel: `${amount} ${currency}`,
+  }));
+```
+
+## Pitfall: stale values in async callbacks
+
+Destructuring copies the values at call time. If the handler starts asynchronous work and the callback reads those copies, it sees the element as it was when the work started, not when it finished:
+
+```ts
+// ✗ `amount` here is whatever it was when the fetch began
+.onConnected(({ apiUrl, amount }) => ({
+  addListener: ["price-tag-refresh", () => fetch(apiUrl).then(() => console.log(amount))],
+}))
+```
+
+Make the callback a `defineMethods` method instead. [Methods](./METHODS.md) are effectors too — Neutron calls them with the live element first — so the callback destructures fresh values when it actually runs, and its return value is applied as an effect. The lifecycle keeps `el` only to reach the method (methods are bound to the element; call them as `el.method(…)`):
+
+```ts
+Neutron({ tag: "price-tag", props: { apiUrl: String, amount: Number } })
+  .defineMethods({
+    // runs later, with the element as it is *then*
+    applyQuote: ({ amount }, quote: { rate: number }) => ({
+      amount: amount * quote.rate,
+    }),
+  })
+  .onConnected((el) => ({
+    addListener: [
+      "price-tag-refresh",
+      () => fetch(el.apiUrl).then((r) => r.json()).then((quote) => el.applyQuote(quote)),
+    ],
+  }));
+```

package/support/docs/METHODS.md

@@ -0,0 +1,49 @@
+# Methods
+
+Methods are effectors like lifecycles: they receive the live element, return an effect, and can hand a value back to the caller.
+
+## Defining methods
+
+```ts
+Neutron({ tag: "tally-counter", props: { tallyCount: Number } })
+  .defineMethods({
+    increment: ({ tallyCount }, step = 1) => ({
+      tallyCount: (tallyCount ?? 0) + step,
+      returns: (tallyCount ?? 0) + step, // value returned to the caller
+    }),
+  })
+  .define();
+
+// el.increment(2) → number
+```
+
+Element first, then the call arguments. Other effects can call them by name: `increment: [2]`. Because Neutron calls a method with the element as it is *then*, methods are also the right shape for async callbacks — see [Lifecycles](./LIFECYCLES.md#md-pitfall-stale-values-in-async-callbacks).
+
+### Pre-declaring signatures
+
+`defineMethods` types `element` as the element *before* that call, so a method cannot reach a sibling defined in the same object. `withTypes<T>()` is a type-only step (no runtime effect) that puts the signatures on the element type first — methods are bound and the element argument is stripped, so declare them as the element sees them. It also makes `typeof Builder.CustomElement` usable for module-level helpers.
+
+```ts
+interface Methods {
+  flush: FrameRequestCallback;
+  schedule: () => void;
+}
+
+export const Ticker = Neutron({ tag: "tick-er", props: { tickCount: Number } })
+  .withTypes<Methods>();
+
+type El = typeof Ticker.CustomElement;
+
+const label = (el: El) => `${el.tickCount}`;
+
+Ticker.defineMethods({
+  flush: ({ tickCount }) => ({ tickCount: tickCount + 1 }),
+  schedule: ({ flush }) => {
+    requestAnimationFrame(flush); // sibling method, no cast
+  },
+}).define();
+```
+
+## Keep the imperative surface small
+
+If a method is something the consuming app may want to invoke, accept it as a command (`onCommand("--verb")`, see [Commands](./COMMANDS.md)); if it is something the app may want to cancel, fire an event with a default action (`onEventDefault`, see [Events](./EVENTS.md)). Neither needs a public method.

package/support/docs/PROMISE_PROPS.md

@@ -0,0 +1,29 @@
+# Promise props
+
+Store a promise in a prop and react to its settlement; replacing it cancels the stale one.
+
+## Resolve / reject handlers
+
+```ts
+Neutron({
+  tag: "lazy-item",
+  props: {
+    srcPromise: Promise,
+    provision: Object,
+  },
+})
+  .onConnected(() => ({
+    srcPromise: fetch("/api/item").then((r) => r.json()),
+  }))
+  .onPromiseResolved("srcPromise", (_el, result) => ({
+    srcPromise: null,
+    provision: result.srcPromise,
+  }))
+  .onPromiseRejected("srcPromise", () => ({ srcPromise: null }));
+```
+
+`result` maps the prop name to the resolved value (or the rejection reason).
+
+## Cancellation
+
+Assigning a new promise or `null` while the previous one is pending cancels it — the stale settlement never reaches the handlers.

package/support/docs/PROPS.md

@@ -0,0 +1,64 @@
+# Props
+
+Declare an element's state once; primitives become dashed attributes that CSS and Quark select on, rich values stay on the instance.
+
+## Declaring props
+
+Shorthand constructors reflect primitives to dashed attributes. Rich config adds defaults, validation, storage, and custom serialize / deserialize.
+
+```ts
+import { Neutron, TokenList } from "@excom/neutron";
+
+Neutron({
+  tag: "usage-meter",
+  props: {
+    unitLabel: String, // reflects ↔ `unit-label`
+    maxCount: Number, // reflects ↔ `max-count`
+    isOpen: Boolean, // presence attribute `is-open`
+    featureTags: TokenList, // space-separated tokens ↔ `feature-tags`, read as `string[]`
+    // non-reflecting by default:
+    payload: Object,
+    items: Array,
+    srcPromise: Promise,
+    // rich config:
+    maxValue: {
+      type: Number,
+      defaultValue: () => 100,
+      isValid: (n) => n > 0,
+    },
+    // element references are always weak — never pin another node:
+    inputEl: { type: HTMLInputElement, store: "weak" },
+  },
+});
+```
+
+## Rich config keys
+
+| Key | Purpose |
+| --- | --- |
+| `type` | Constructor. `String` / `Number` / `Boolean` / `TokenList` reflect to an attribute; everything else is instance-only. |
+| `defaultValue` | `() => value`, returned when the prop is nullish or invalid. |
+| `isValid` | `(value) => boolean`. Invalid values fall back to the default; for `TokenList` the invalid tokens are filtered out instead. |
+| `attr` | Override the attribute name, or `false` to keep a primitive off the attribute. |
+| `store` | `"weak"` holds the value in a `WeakRef` and derefs on read. Required for every prop that references another element, so a removed node can be collected. |
+| `serialize` / `deserialize` | Transform on write / read. |
+
+## TokenList
+
+`TokenList` is exported by this package. It marks a space-separated attribute (`feature-tags="a b"`) whose property value is a plain `string[]` — the element-side equivalent of `class`. Prefer it over `Array` whenever the list belongs in the document, so CSS and Quark can select on it (`usage-meter[feature-tags~="a"]`).
+
+## Built-in instance props
+
+`isMounted`, `isMoving`, `isAdopted`, `wasMounted` exist on every element. They are instance-only; list them in `reflectDefaultProps: ["isMounted"]` to reflect them as attributes (`is-mounted`).
+
+## Naming rules
+
+Enforced at definition time or by convention:
+
+- Custom attributes must contain a dash (`max-count`, `is-open`), so they can never collide with a native attribute — now or in the future. Dev mode warns on dash-less, `data-*`, and `aria-*` attributes.
+- Booleans read as assertions: `is-loading`, `did-fail`, `has-rendered`, `should-fetch`.
+- Events are tag-prefixed (`press-tracker-press`), never bare (`change`).
+- Attribute names may not start with `q-`, `n-`, `on-`, or `off-` (reserved by Quark and Neutron).
+- Prop names may not shadow Neutron internals or effect keywords (`returns`, `content`, lifecycle names, `_n_`, `_q_`).
+- Private state and methods take a leading underscore.
+- Loosely couple: element-typed props use `store: "weak"`, and anything else that holds a node is cleared in `onDisconnected`.

package/support/docs/PROP_REACTIONS.md

@@ -0,0 +1,35 @@
+# Prop reactions
+
+React to one prop, or a batch of them, with the previous values in hand.
+
+## Handlers
+
+```ts
+Neutron({ tag: "echo-field", props: { fieldValue: String, isFilled: Boolean } })
+  .onPropSet("fieldValue", () => ({
+    /* fieldValue became truthy for its type */
+    isFilled: true,
+  }))
+  .onPropUnset("fieldValue", () => ({
+    /* fieldValue became falsy / removed */
+    isFilled: false,
+  }))
+  .onPropChanged("fieldValue", ({ fieldValue }, previous) => ({
+    /* any change, including unset → set; `previous.fieldValue` is the old value */
+    emit: ["echo-field-change", { detail: { fieldValue, previous: previous.fieldValue } }],
+  }))
+  // one handler for a batch of props — runs when any of them changed
+  .onEffect(["fieldValue", "isFilled"], (el, previous) => ({
+    emit: ["echo-field-effect", { detail: { previous } }],
+  }));
+```
+
+`onPropChanged` and `onEffect` take one name or an array of names. The second argument maps every prop that changed in the batch to its **previous** value.
+
+## Mount gating
+
+Reactions run only on mounted elements. Changes made before the first connect (attributes parsed from HTML, props set on a detached element) are kept and flushed as one batch on first mount, so reaction handlers always see the settled initial state.
+
+## No self-writes
+
+A handler must not set the same prop it is reacting to — Neutron throws a `NeutronError`. Child effects on element-typed props are the exception, so `.onPropSet("inputEl", () => ({ inputEl: { addListener: [...] } }))` is allowed.

package/support/docs/PROVISION.md

@@ -0,0 +1,31 @@
+# Provision
+
+One property carries everything rich an element publishes to the document, so Quark and app JS have a single place to read it.
+
+## Declaring a provision
+
+All public, rich data an element exposes to the document goes through one property: `provision`. Declare it as `provision: Object` (or a typed constructor), set it from an effect, and tag it `@provision` in JSDoc.
+
+```ts
+Neutron({
+  tag: "provider-ping",
+  props: { provision: Object },
+})
+  .onConnected(() => ({ provision: { at: Date.now() } }))
+  .define();
+```
+
+## Reading it
+
+Every set emits `neutron-provision` for app JS. Quark reads it on the element itself with `prop("provision")` and re-runs when it is assigned — assign a new object rather than mutating the old one.
+
+```quark
+provider-ping {
+  $ping: prop("provision");
+  [bind-at] { content: $ping.at; }
+}
+```
+
+## Ordering
+
+Within one [effect](./EFFECTS.md), `provision` is always applied last, so listeners of `neutron-provision` see every other prop already settled.

package/support/docs/README.md

@@ -0,0 +1,118 @@
+# neutron
+
+Define typed custom elements with effect-based lifecycles — props, events, and compose without rewriting the Custom Elements boilerplate.
+
+Neutron is the element factory of the Nucleus Stack: `Neutron({ tag, props })` returns a builder you chain lifecycles onto, then `define()`. Every Nucleus Kit element is a Neutron element, and so is every element you write yourself.
+
+## Features
+
+- **Declarative factory** `Neutron({ tag, props }).… .define()`
+- **Typed props** Primitives and `TokenList` reflect to dashed attributes; objects / arrays / elements / promises stay on the instance
+- **Effect returns** Lifecycles / methods return a POJO (or an array of them) that sets props, emits, listens, calls methods, and styles
+- **Fine-grained reactions** `onPropSet` / `Unset` / `Changed` / `onEffect`
+- **Events & broadcasts** Tag-prefixed custom events, cancelable default actions, channel broadcasts
+- **Commands** `onCommand("--verb")` handles the HTML Command API — `<button command commandfor>` needs no custom element
+- **Listener cleanup** Listeners added through effects are removed on disconnect and restored on reconnect
+- **Compose** Combine builders (`Neutron.compose`) for mixin-style packages
+- **Recompose** Import a package's raw builder, add / remove lifecycles and methods, then `define()` it yourself
+- **DevTools** `Neutron.attachDevtools()` hooks the Nucleus DevTools extension
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+An element owns its own state (attributes) and announces changes (events). It never renders children or reaches into siblings — coordination belongs to Quark. The rules these examples follow are collected in [Best Practices](/nucleus/docs/best_practices) and [Creating Elements](/nucleus/docs/creating_elements).
+
+```ts
+import { Neutron } from "@excom/neutron";
+
+export const PressTracker = Neutron({
+  tag: "press-tracker",
+  props: {
+    pressCount: { type: Number, defaultValue: () => 0 }, // reflects ↔ `press-count`
+  },
+})
+  .onEvent("click", ({ pressCount }) => ({
+    // effects are declarative instructions, not imperative mutations
+    pressCount: pressCount + 1,
+    emit: ["press-tracker-press", { detail: { pressCount: pressCount + 1 } }],
+  }));
+
+PressTracker.define();
+```
+
+```html
+<press-tracker press-count="0">
+  <button>Press</button>
+</press-tracker>
+<!-- `press-tracker[press-count="3"]` is now a CSS / Quark selector -->
+```
+
+### Documentation
+
+Defining elements
+
+- [Props](./PROPS.md) — typed props, reflection, `TokenList`, naming rules
+- [Provision](./PROVISION.md) — the one property for published rich data
+- [TypeScript](./TYPESCRIPT.md) — global element types, `ConstructorType`
+
+Behavior
+
+- [Lifecycles](./LIFECYCLES.md) — `onConnected` & co., destructuring, async pitfalls
+- [Effects](./EFFECTS.md) — the object a handler returns
+- [Prop reactions](./PROP_REACTIONS.md) — `onPropSet` / `Unset` / `Changed` / `onEffect`
+- [Methods](./METHODS.md) — methods as effectors
+- [Events](./EVENTS.md) — emits, default actions, broadcasts, listener cleanup
+- [Commands](./COMMANDS.md) — `onCommand` for `--verb` commands, the `command` effect
+- [Promise props](./PROMISE_PROPS.md) — `onPromiseResolved` / `Rejected`
+
+Composition
+
+- [Compose](./COMPOSE.md) — stack builders into mixin-style packages
+- [Recompose](./RECOMPOSE.md) — edit a packaged element before defining it
+
+Runtime
+
+- [Define](./DEFINE.md) — `define()` and class introspection
+- [Debug](./DEBUG.md) — DevTools hook, loop guard
+
+### Examples
+
+#### State on connect
+
+```ts
+Neutron({ tag: "ready-flag", props: { isReady: Boolean } })
+  .onConnected(() => ({ isReady: true, emit: ["ready-flag-ready"] }))
+  .define();
+```
+
+#### Child element effect across handlers
+
+Assign an element prop, then react to it with a nested effect. Listener callbacks that return effects must be `defineMethods` methods:
+
+```ts
+Neutron({
+  tag: "focus-host",
+  props: {
+    inputEl: { type: HTMLInputElement, store: "weak" },
+    isFocused: Boolean,
+  },
+})
+  .defineMethods({
+    handleFocus: () => ({ isFocused: true, emit: ["focus-host-focus"] }),
+    handleBlur: () => ({ isFocused: false }),
+  })
+  .onConnected((el) => ({
+    inputEl: el.querySelector("input"),
+  }))
+  .onPropSet("inputEl", ({ handleFocus, handleBlur }) => ({
+    inputEl: {
+      addListeners: [
+        ["focus", handleFocus],
+        ["blur", handleBlur],
+      ],
+    },
+  }));
+```

package/support/docs/RECOMPOSE.md

@@ -0,0 +1,70 @@
+# Recompose
+
+A builder is open until `define()` runs: import a package's raw builder, edit it, then register it yourself.
+
+## Import the raw builder
+
+Every element package ships two entries: `index.ts` (calls `.define()` and registers the global types) and the raw element source (`<element>.ts`), which only exports the builder. Import the raw entry, edit it, then register it yourself:
+
+```ts
+// app.ts — never import "@excom/detect-browser" (or nucleus-kit) here: that entry defines the element immediately
+import { DetectBrowser } from "@excom/detect-browser/detect-browser";
+
+DetectBrowser
+  // add lifecycles / methods the package did not ship
+  .onPropSet("isStandalone", () => ({ emit: ["detect-browser-standalone"] }))
+  .defineMethods({ clearInfo: () => ({ provision: null }) })
+  .define();
+```
+
+Most recomposition is exactly that: chaining new lifecycles onto a packaged element. Unregistering is rarer and goes through `builtConfig`.
+
+## builtConfig
+
+Every builder exposes its definition as `builtConfig`, a plain object you can read before `define()`:
+
+| Key | Shape |
+| --- | --- |
+| `tag` | The packaged tag name (also the event prefix). |
+| `props` | `{ [propName]: PropConfig }` — the normalized prop configs (`type`, `attr`, `defaultValue`, …). |
+| `events` / `broadcasts` | `{ [name]: { prefixWithTag? } }` |
+| `methods` | `[name, fn][]` in definition order. |
+| `lifecycles` | `{ constructed, connected, adopted, disconnected, error, effect, propSet, propUnset, propChanged, promiseResolved, promiseRejected, broadcast, event, eventDefault }`, each an array of `[names, handler]` pairs in registration order. `names` is the prop / event list the handler was registered with (`[]` for lifecycles without one). |
+| `reflectDefaultProps` / `definitionOpts` | As passed to `Neutron()`. |
+
+## Removing a lifecycle
+
+Removal needs the original handler reference, because `off*` matches by function identity. Index into `builtConfig.lifecycles.<lifecycle>[entry][1]` and pass that handler to the matching `off*`:
+
+```ts
+// stop detecting on connect; the app calls `el.setBrowserInfo()` when it wants to
+DetectBrowser.offConnected(DetectBrowser.builtConfig.lifecycles.connected[0][1]);
+
+// named lifecycles: pass the names too — only those names are detached, the handler keeps any others
+DetectBrowser.offPropSet("isStandalone", DetectBrowser.builtConfig.lifecycles.propSet[0][1]);
+```
+
+Indexing by position is intentional for now (a friendlier handle may come later); read `builtConfig.lifecycles.<lifecycle>` once to see which entry you are after.
+
+## Adding props
+
+Adding props goes through [`Neutron.compose`](./COMPOSE.md), which also leaves the imported builder untouched (it deep-clones):
+
+```ts
+import { Neutron } from "@excom/neutron";
+
+export const StampedDetectBrowser = Neutron.compose([
+  DetectBrowser,
+  Neutron({ tag: "detect-browser", props: { detectedAt: String } }),
+]).onPropSet("provision", () => ({ detectedAt: new Date().toISOString() }));
+
+StampedDetectBrowser.define();
+```
+
+## Rules
+
+- Everything must happen before `define()`. The runtime config is built at that moment; later `on*` / `off*` / `defineMethods` calls return the builder but change nothing.
+- The raw builder is a module singleton — an in-place edit is visible to every importer. Use `Neutron.compose` when you want a modified copy instead.
+- Added handlers run after the packaged ones for the same lifecycle (registration order) and batch into the same effect pass.
+- `define("other-tag")` registers the class under a different name. Events configured with `prefixWithTag` keep the packaged prefix, because the prefix comes from the builder's `tag`, not from the registered name.
+- Skipping `index.ts` also skips its `declare global` block — add your own (see [TypeScript](./TYPESCRIPT.md)) if you want the tag typed.

package/support/docs/TYPESCRIPT.md

@@ -0,0 +1,51 @@
+# TypeScript
+
+Expose an element's inferred type the way the DOM exposes its own elements, so queries and `createElement` need no casts.
+
+## Global element types
+
+`Neutron()` infers the element type from `props` and `defineMethods`. Publish it as a global `HTML*Element` interface plus an `HTMLElementTagNameMap` entry, so `document.querySelector("press-tracker")` and `document.createElement("press-tracker")` are typed without casts:
+
+```ts
+// index.ts — the package entry defines and types the element
+import { PressTracker } from "./press-tracker";
+
+PressTracker.define();
+
+export { PressTracker };
+
+type T_HTMLPressTrackerElement = typeof PressTracker.CustomElement;
+declare global {
+  interface HTMLPressTrackerElement extends T_HTMLPressTrackerElement {}
+  interface Window {
+    HTMLPressTrackerElement: HTMLPressTrackerElement;
+  }
+  interface HTMLElementTagNameMap {
+    "press-tracker": HTMLPressTrackerElement;
+  }
+}
+export type { HTMLPressTrackerElement };
+```
+
+`CustomElement` is a type-only handle on the builder (there is no runtime value); `Props` is the inferred props object.
+
+## Typed rich props
+
+To type a rich prop more precisely than its constructor allows, cast the constructor with `ConstructorType<T>`:
+
+```ts
+import { ConstructorType, Neutron } from "@excom/neutron";
+
+type FeatureInfo = { fullSupport: string[]; noSupport: string[] };
+
+Neutron({
+  tag: "detect-features",
+  props: {
+    provision: Object as unknown as ConstructorType<FeatureInfo>, // el.provision: FeatureInfo
+  },
+});
+```
+
+## Event types
+
+Document Neutron-emitted events with `TEvent` plus `type` and `detail` — see [Events](./EVENTS.md#md-typing-events).

package/support/docs-sections.json

@@ -0,0 +1,42 @@
+{
+  "sections": [
+    {
+      "id": "defining-elements",
+      "title": "Defining Elements",
+      "docs": [
+        "props",
+        "provision",
+        "typescript"
+      ]
+    },
+    {
+      "id": "behavior",
+      "title": "Behavior",
+      "docs": [
+        "lifecycles",
+        "effects",
+        "prop_reactions",
+        "methods",
+        "events",
+        "commands",
+        "promise_props"
+      ]
+    },
+    {
+      "id": "composition",
+      "title": "Composition",
+      "docs": [
+        "compose",
+        "recompose"
+      ]
+    },
+    {
+      "id": "runtime",
+      "title": "Runtime",
+      "docs": [
+        "define",
+        "debug"
+      ]
+    }
+  ]
+}