@opentf/web 0.4.0 → 0.6.0

package/runtime/code-block.js

@@ -0,0 +1,47 @@
+//! Code block — a built-in that renders a (build-time syntax-highlighted) code block
+//! and **owns its copy behavior**.
+//
+//   <CodeFence html={"<div class='otfw-code'>…<button class='otfw-copy'>…</button><pre>…</pre></div>"} />
+//
+// The MDX front-end emits this for fenced code (compiles to `web-internal-code-block`,
+// like `<RawHtml>` → `web-internal-raw-html`). The highlighted markup is a trusted
+// string from the compiler, so it's assigned to `innerHTML`; the difference from
+// `RawHtml` is that on connect this element wires its own `.otfw-copy` button to copy
+// the `<pre>` text. That keeps copy working wherever a code block is rendered (docs,
+// blog, anywhere) — no delegated listener in a layout. SSG renders the string inline
+// (server/builtins.js); the behavior wires when the element upgrades in the browser.
+
+import { copyWithFeedback } from "./clipboard.js";
+
+export class CodeBlockElement extends HTMLElement {
+  set html(v) {
+    this._html = v;
+    if (this.isConnected) this.render();
+  }
+  get html() {
+    return this._html;
+  }
+
+  connectedCallback() {
+    // The `html` property is set before append during a CSR build; render once.
+    if (!this._rendered) this.render();
+  }
+
+  render() {
+    this.innerHTML = this._html == null ? "" : String(this._html);
+    const button = this.querySelector(".otfw-copy");
+    const pre = this.querySelector("pre");
+    if (button && pre && !button._otfwWired) {
+      button._otfwWired = true;
+      button.addEventListener("click", () => copyWithFeedback(button, pre.innerText));
+    }
+    this._rendered = true;
+  }
+}
+
+// Exported so the bare import in runtime/index.js retains the registration side
+// effect; JSX addresses it by the `web-internal-code-block` tag (no import needed).
+export const CodeFence = CodeBlockElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-code-block")) {
+  customElements.define("web-internal-code-block", CodeBlockElement);
+}

package/runtime/context.js

@@ -0,0 +1,99 @@
+//! Context API — scoped dependency injection over the component tree.
+//
+// Unlike a module-level signal (which is global) or a prop (which must be drilled),
+// context provides a value to a *subtree* and lets a nested provider override it.
+// Because components compile to Custom Elements, the component tree *is* the DOM
+// tree, so we resolve a consumer's provider with `closest()` — no special graph.
+//
+//   const ThemeContext = createContext("dark");
+//   <ContextProvider context={ThemeContext} value={theme}> … </ContextProvider>
+//   const theme = $context(ThemeContext);   // compiler macro; use the bare name
+//
+// `value` flows through the provider's element as a signal, so a reactive `value`
+// (e.g. backed by `$state`) updates every consumer fine-grained.
+
+import { signal } from "../core/signals.js";
+
+let nextId = 0;
+
+// Stack of the elements whose component bodies are currently executing. A stack
+// (not a single slot) because filling a component's children slot connects nested
+// components synchronously inside the parent's connect — each push is balanced by
+// a pop in the generated `finally`, so the parent's host is restored after.
+const hostStack = [];
+
+/** Push the current component host (compiler-emitted, paired with `exitHost`). */
+export function enterHost(el) {
+  hostStack.push(el);
+}
+
+/** Pop the current component host (compiler-emitted, in a `finally`). */
+export function exitHost() {
+  hostStack.pop();
+}
+
+/**
+ * The component host element currently executing its body, or `null` outside a
+ * component (e.g. a form created in module scope or a test). Libraries use this
+ * as a per-instance identity to scope state to the mounting component — the
+ * compiler emits `enterHost(this)` around every component body (csr.rs).
+ */
+export function getCurrentInstance() {
+  return hostStack[hostStack.length - 1] ?? null;
+}
+
+/**
+ * Create a context with a default value. The returned token is passed to
+ * `<ContextProvider context={…}>` and `$context(…)`.
+ */
+export function createContext(defaultValue) {
+  return { id: `otfw-ctx-${nextId++}`, fallback: signal(defaultValue) };
+}
+
+/**
+ * Resolve the value provided by the nearest ancestor `ContextProvider` for
+ * `context`, or the context's default if there is none. Returns a **signal**. This
+ * is what the `$context(Ctx)` compiler macro lowers to; the macro registers the
+ * binding as a signal so the bare name reads `.value` reactively.
+ */
+export function readContext(context) {
+  let el = hostStack[hostStack.length - 1];
+  const sel = `[data-otfw-ctx~="${context.id}"]`;
+  // Walk up the DOM; when the search reaches a portal boundary without finding a
+  // provider, hop to the portal's logical location (`__portalHost`) and continue,
+  // so context resolves across a <Portal> as if the content were still in place.
+  while (el) {
+    const provider = el.closest(sel);
+    if (provider) return provider._signal;
+    const boundary = el.closest("[data-otfw-portal]");
+    el = boundary ? boundary.__portalHost : null;
+  }
+  return context.fallback;
+}
+
+// `<ContextProvider context={Ctx} value={v}>`: a host element that publishes `v`
+// (as a signal) for `Ctx` to its subtree. `context`/`value` arrive as element
+// properties (the compiler sets component props reactively), so a changing `value`
+// propagates to consumers automatically.
+export class ContextProviderElement extends HTMLElement {
+  constructor() {
+    super();
+    this._signal = signal(undefined);
+  }
+  set context(ctx) {
+    if (ctx && ctx.id) this.setAttribute("data-otfw-ctx", ctx.id);
+  }
+  set value(v) {
+    this._signal.value = v;
+  }
+  get value() {
+    return this._signal.value;
+  }
+}
+
+// Exported so `import { ContextProvider } from "@opentf/web"` resolves; the import
+// side effect registers the element (JSX uses the `web-internal-context-provider` tag).
+export const ContextProvider = ContextProviderElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-context-provider")) {
+  customElements.define("web-internal-context-provider", ContextProviderElement);
+}

package/runtime/dom.js

@@ -0,0 +1,368 @@
+// Zero-VDOM DOM operations. CSR codegen emits calls into these helpers; they
+// also back runtime-driven updates (reactive text/attributes). No virtual DOM,
+// no diffing — just direct, fine-grained DOM writes wired to signals.
+
+import { effect, signal } from "../core/signals.js";
+
+// Attribute names that must be assigned as JS properties (not setAttribute) for
+// correct behavior. Mirrors the set the old runtime relied on (core/constants).
+const AS_PROPERTY = new Set([
+  "value",
+  "checked",
+  "selected",
+  "disabled",
+  "readOnly",
+  "className",
+  "htmlFor",
+  "indeterminate",
+]);
+
+// Enumerated attributes: their value is a keyword string ("true"/"false"), not a
+// boolean-attribute presence toggle. `draggable={true}` must become
+// draggable="true" — draggable="" reads back as the default (false). ARIA states
+// behave the same (aria-*="true"/"false").
+const ENUMERATED = new Set(["draggable", "spellcheck", "contenteditable"]);
+
+// CSS properties whose numeric values are unitless; every other numeric value
+// gets "px" appended (matching React/JSX conventions, so `style={{ width: 8 }}`
+// means 8px). Mirrors React's CSSProperty unitless list.
+const UNITLESS = new Set([
+  "animationIterationCount", "aspectRatio", "borderImageOutset", "borderImageSlice",
+  "borderImageWidth", "boxFlex", "boxFlexGroup", "boxOrdinalGroup", "columnCount",
+  "columns", "flex", "flexGrow", "flexShrink", "flexOrder", "gridArea", "gridRow",
+  "gridRowEnd", "gridRowStart", "gridColumn", "gridColumnEnd", "gridColumnStart",
+  "fontWeight", "lineClamp", "lineHeight", "opacity", "order", "orphans", "tabSize",
+  "widows", "zIndex", "zoom", "fillOpacity", "floodOpacity", "stopOpacity",
+  "strokeDasharray", "strokeDashoffset", "strokeMiterlimit", "strokeOpacity",
+  "strokeWidth",
+]);
+
+/**
+ * Apply a `style` object to an element. Numbers get "px" appended unless the
+ * property is unitless; CSS custom properties (`--foo`) go through setProperty;
+ * nullish values clear the property. A string value is treated as raw cssText.
+ */
+export function applyStyle(el, value) {
+  if (typeof value === "string") {
+    el.style.cssText = value;
+    return;
+  }
+  for (const key in value) {
+    const v = value[key];
+    if (key.startsWith("--")) {
+      el.style.setProperty(key, v == null ? "" : String(v));
+    } else if (v == null) {
+      el.style[key] = "";
+    } else {
+      el.style[key] = typeof v === "number" && !UNITLESS.has(key) ? `${v}px` : v;
+    }
+  }
+}
+
+/** Render a reactive value to its text form: null/undefined/false → "". */
+export function toText(value) {
+  return value == null || value === false ? "" : String(value);
+}
+
+/** Sentinel for "nothing written yet" — distinct from any real attribute value. */
+const UNSET = Symbol("unset");
+
+/** A value safe to compare by identity for write elision (no internal mutation). */
+const isPrimitive = (v) =>
+  v === null || (typeof v !== "object" && typeof v !== "function");
+
+/**
+ * clsx-style class normalization. Falsy entries are skipped; strings/numbers are
+ * kept; arrays recurse; objects contribute the keys whose values are truthy. Lets
+ * JSX write `class={["btn", active && "on", { lg: size === "lg" }]}`.
+ */
+export function clsx(value) {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (Array.isArray(value)) {
+    const parts = [];
+    for (const v of value) {
+      const s = clsx(v);
+      if (s) parts.push(s);
+    }
+    return parts.join(" ");
+  }
+  if (typeof value === "object") {
+    const parts = [];
+    for (const k in value) if (value[k]) parts.push(k);
+    return parts.join(" ");
+  }
+  return "";
+}
+
+/**
+ * Apply a single static prop/attribute. Handles `style` objects, `on*` event
+ * handlers, property-backed attributes, and boolean/nullish removal; everything
+ * else falls back to `setAttribute`.
+ */
+export function setAttr(el, name, value) {
+  if (name === "style" && value && (typeof value === "object" || typeof value === "string")) {
+    applyStyle(el, value);
+    return;
+  }
+  if (name === "class" && value && typeof value === "object") {
+    const c = clsx(value); // array/object form → a normalized class string
+    if (c) el.setAttribute("class", c);
+    else el.removeAttribute("class");
+    return;
+  }
+  if (name.startsWith("on") && typeof value === "function") {
+    el[name.toLowerCase()] = value;
+    return;
+  }
+  if (AS_PROPERTY.has(name)) {
+    el[name] = value;
+    return;
+  }
+  if (ENUMERATED.has(name) || name.startsWith("aria-")) {
+    if (value == null) el.removeAttribute(name);
+    else el.setAttribute(name, value === true ? "true" : value === false ? "false" : String(value));
+    return;
+  }
+  if (value == null || value === false) {
+    el.removeAttribute(name);
+    return;
+  }
+  if (value === true) {
+    el.setAttribute(name, "");
+    return;
+  }
+  el.setAttribute(name, String(value));
+}
+
+/**
+ * Apply a named prop to a *child component* element. Set it as a property when the
+ * element exposes one (custom-element prop setters, `value`, `checked`, …) so rich
+ * values (objects, signals) reach the component's setter; otherwise fall back to an
+ * attribute so plain ones (`class`, `data-*`, `aria-*`) still land correctly. This
+ * mirrors how JSX libraries target custom elements. If the element is not yet
+ * upgraded `name in el` is false, so the value lands as an attribute and the
+ * component picks it up from `getAttribute` when it upgrades.
+ */
+export function setProp(el, name, value) {
+  if (name in el) el[name] = value;
+  else setAttr(el, name, value);
+}
+
+/**
+ * Apply every own enumerable key of `obj` to `el` (`<div {...obj}/>`, SPEC §5.5).
+ * `asProps` sets element properties (for components) instead of attributes (for
+ * host elements). Keys are applied in object order; the caller wraps this in an
+ * effect so a reactive source re-applies.
+ */
+export function spread(el, obj, asProps) {
+  if (!obj) return;
+  for (const k in obj) {
+    if (asProps) el[k] = obj[k];
+    else setAttr(el, k, obj[k]);
+  }
+}
+
+/**
+ * Wire a text node to a reactive expression. Primitive values update the text in
+ * place; a DOM node (or array of them) — e.g. JSX stored as a value, `{iconMap[k]}`
+ * — is inserted before the text node, which stays as a stable anchor. Returns the
+ * effect disposer so the caller (component lifecycle) can stop updates.
+ */
+export function bindText(node, fn) {
+  let inserted = [];
+  let lastText; // undefined sentinel — toText() never returns undefined
+  return effect(() => {
+    const value = fn();
+
+    // Primitive text: the common case. Skip the write when the rendered string
+    // is unchanged (a shared dependency can re-run this effect with the same
+    // result), so unchanged text nodes don't churn.
+    if (!(value instanceof Node) && !Array.isArray(value)) {
+      const text = toText(value);
+      if (text === lastText) return;
+      lastText = text;
+      for (const n of inserted) {
+        if (n.parentNode) n.parentNode.removeChild(n);
+      }
+      inserted = [];
+      node.data = text;
+      return;
+    }
+
+    // Node / array value (e.g. JSX stored as a value): insert before the stable
+    // text anchor. Reset the text memo so a later primitive value re-applies.
+    lastText = undefined;
+    for (const n of inserted) {
+      if (n.parentNode) n.parentNode.removeChild(n);
+    }
+    inserted = [];
+    node.data = "";
+    const parent = node.parentNode;
+    if (parent) {
+      for (const n of toNodes(value)) {
+        parent.insertBefore(n, node);
+        inserted.push(n);
+      }
+    }
+  });
+}
+
+/**
+ * Wire an element attribute/prop to a reactive expression. Returns the disposer.
+ *
+ * No-op writes are elided for primitive values: when the expression recomputes
+ * to the same primitive it last wrote, the DOM write is skipped. This matters
+ * when many elements share one dependency — e.g. a keyed list where every row's
+ * `class={selected === row.id ? "danger" : ""}` subscribes to a single
+ * `selected` signal. Changing it re-runs every row's effect, but only the two
+ * rows whose class actually changes should touch the DOM; the rest would
+ * otherwise call `setAttribute` with an unchanged value and trigger needless
+ * style invalidation. Object values (style/class objects, spreads) may have
+ * mutated internally, so they are always re-applied.
+ */
+export function bindAttr(el, name, fn) {
+  let last = UNSET;
+  return effect(() => {
+    const value = fn();
+    if (isPrimitive(value) && Object.is(value, last)) return;
+    last = value;
+    setAttr(el, name, value);
+  });
+}
+
+/** Flatten a reactive child value into DOM nodes: nodes pass through, arrays
+ * recurse, nullish/booleans render nothing, primitives become text nodes. */
+function toNodes(value) {
+  if (value == null || typeof value === "boolean") return [];
+  if (Array.isArray(value)) {
+    const out = [];
+    for (const v of value) for (const n of toNodes(v)) out.push(n);
+    return out;
+  }
+  if (value instanceof Node) return [value];
+  return [document.createTextNode(String(value))];
+}
+
+/**
+ * Wire a dynamic child region (conditional/element-valued holes like
+ * `{cond && <p/>}` or `{cond ? <a/> : <b/>}`) to a reactive expression. The
+ * region is delimited by `anchor` (a comment); on every change the previous
+ * nodes are replaced with the new ones, inserted just before the anchor.
+ * Returns the effect disposer.
+ */
+export function bindChild(anchor, fn) {
+  let current = [];
+  return effect(() => {
+    const next = toNodes(fn());
+    const host = anchor.parentNode;
+    for (const n of current) {
+      if (n.parentNode === host) host.removeChild(n);
+    }
+    if (host) for (const n of next) host.insertBefore(n, anchor);
+    current = next;
+  });
+}
+
+/**
+ * Render a keyed list (`array.map(...)`, SPEC §5.4.4) into `parent`, reconciling
+ * by key on every change to `sourceFn`'s dependencies.
+ *
+ * - `sourceFn()` returns the current array (plain data).
+ * - `renderItem(itemSignal, index)` builds a node for a new item; the item's
+ *   value is a signal so per-item bindings update fine-grained on data changes.
+ * - `keyFn(item, index)` returns a stable key; falls back to `index` when omitted.
+ *
+ * Returns the effect disposer (stops reconciliation; used by component cleanup).
+ */
+export function bindList(parent, sourceFn, renderItem, keyFn) {
+  const anchor = document.createComment("");
+  parent.appendChild(anchor);
+  let cache = new Map(); // key -> { sig, node }
+  let prevKeys = []; // keys in current DOM order, for minimal-move reconciliation
+
+  return effect(() => {
+    const data = sourceFn();
+    const items = Array.isArray(data) ? data : [];
+    const next = new Map();
+    const nodes = new Array(items.length);
+    const newKeys = new Array(items.length);
+    // For each new position, the node's index in the *previous* order, or -1 if
+    // it is newly created. Drives the LIS-based minimal move below.
+    const prevIndex = new Array(items.length);
+
+    const prevPos = new Map();
+    for (let i = 0; i < prevKeys.length; i++) prevPos.set(prevKeys[i], i);
+
+    for (let index = 0; index < items.length; index++) {
+      const item = items[index];
+      const key = keyFn ? keyFn(item, index) : index;
+      let entry = cache.get(key);
+      if (entry) {
+        cache.delete(key);
+        entry.sig.value = item; // fine-grained per-item update (no-op if unchanged)
+        prevIndex[index] = prevPos.has(key) ? prevPos.get(key) : -1;
+      } else {
+        const sig = signal(item);
+        entry = { sig, node: renderItem(sig, index) };
+        prevIndex[index] = -1;
+      }
+      next.set(key, entry);
+      newKeys[index] = key;
+      nodes[index] = entry.node;
+    }
+
+    // Remove nodes whose keys disappeared.
+    for (const entry of cache.values()) {
+      if (entry.node.parentNode) entry.node.parentNode.removeChild(entry.node);
+    }
+    cache = next;
+    prevKeys = newKeys;
+
+    // Minimal-move placement. Nodes whose previous indices form the longest
+    // increasing subsequence are already in relative order and stay put; only
+    // the rest (and newly created nodes) are inserted. A 2-row swap moves 2
+    // nodes, not the ~n nodes a naive "fix every wrong nextSibling" pass would
+    // cascade into. Walk back to front so each insertion's reference node is
+    // already in its final position.
+    const keep = longestIncreasingRun(prevIndex);
+    const host = anchor.parentNode || parent;
+    for (let i = nodes.length - 1; i >= 0; i--) {
+      if (keep.has(i)) continue;
+      const ref = i + 1 < nodes.length ? nodes[i + 1] : anchor;
+      if (nodes[i].nextSibling !== ref) host.insertBefore(nodes[i], ref);
+    }
+  });
+}
+
+/**
+ * Indices `i` of `seq` whose values form a longest strictly-increasing
+ * subsequence (patience sorting, O(n log n)). Entries equal to -1 (new nodes)
+ * are excluded — they always need insertion. Returned as a Set for O(1) lookup
+ * during placement; these are the nodes that can stay where they are.
+ */
+function longestIncreasingRun(seq) {
+  const piles = []; // piles[k] = index of the smallest tail of a length-(k+1) run
+  const prev = new Array(seq.length).fill(-1);
+  for (let i = 0; i < seq.length; i++) {
+    const v = seq[i];
+    if (v < 0) continue; // new node — never part of the stable run
+    let lo = 0;
+    let hi = piles.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (seq[piles[mid]] < v) lo = mid + 1;
+      else hi = mid;
+    }
+    if (lo > 0) prev[i] = piles[lo - 1];
+    piles[lo] = i;
+  }
+  const keep = new Set();
+  let k = piles.length ? piles[piles.length - 1] : -1;
+  while (k >= 0) {
+    keep.add(k);
+    k = prev[k];
+  }
+  return keep;
+}

package/runtime/error-boundary.js

@@ -0,0 +1,109 @@
+//! ErrorBoundary — catch render/mount errors from descendant components and show
+//! a fallback instead of letting the broken subtree (or its siblings) take the
+//! page down.
+//
+//   <ErrorBoundary fallback={(error, reset) => `Oops: ${error.message}`}>
+//     <Risky/>
+//   </ErrorBoundary>
+//
+// A descendant component's connectedCallback funnels a thrown error through
+// `handleError(this, …)` (emitted by the compiler): it reports the error (dev
+// overlay / logging) and walks up the DOM — hopping across portals, like
+// `readContext` — to the nearest `web-internal-error-boundary`, which swaps its children
+// for the fallback. `reset()` rebuilds the original subtree (snapshotted before it
+// ran) to retry. Only synchronous render/mount errors are caught; later
+// effect/event errors still go to global reporting (as with React boundaries).
+
+import { reportError } from "../core/errors.js";
+
+/**
+ * Report a caught render/mount error and route it to the nearest enclosing
+ * `<ErrorBoundary>`. Called from a throwing component's connectedCallback catch.
+ */
+export function handleError(el, error, context = {}) {
+  reportError(error, context); // always log / surface in the dev overlay
+  let node = el;
+  while (node) {
+    const boundary = node.closest ? node.closest("web-internal-error-boundary") : null;
+    if (boundary) {
+      boundary.catch(error, context);
+      return;
+    }
+    const portal = node.closest ? node.closest("[data-otfw-portal]") : null;
+    node = portal ? portal.__portalHost : null;
+  }
+}
+
+// A self-contained fallback (inline-styled so it reads fine without any app CSS).
+function defaultFallback(message, reset) {
+  const box = document.createElement("div");
+  box.setAttribute("role", "alert");
+  box.setAttribute("data-otfw-fallback", "");
+  box.style.cssText =
+    "display:flex;align-items:center;gap:.75rem;padding:.75rem 1rem;border:1px solid #ef4444;" +
+    "border-radius:.5rem;background:rgba(239,68,68,.1);color:#fca5a5;font:14px system-ui,sans-serif";
+  const text = document.createElement("span");
+  text.textContent = message;
+  box.appendChild(text);
+  const retry = document.createElement("button");
+  retry.textContent = "Retry";
+  retry.style.cssText =
+    "margin-left:auto;padding:.25rem .75rem;border-radius:.375rem;border:none;cursor:pointer;" +
+    "background:#ef4444;color:#fff;font:inherit";
+  retry.addEventListener("click", reset);
+  box.appendChild(retry);
+  return box;
+}
+
+export class ErrorBoundaryElement extends HTMLElement {
+  set fallback(fn) {
+    this._fallback = fn;
+  }
+  get fallback() {
+    return this._fallback;
+  }
+
+  connectedCallback() {
+    if (this._mounted) return;
+    this._mounted = true;
+    // Snapshot the children before they connect (and possibly throw) so reset()
+    // can rebuild a pristine subtree.
+    this._blueprint = Array.from(this.childNodes).map((n) => n.cloneNode(true));
+  }
+
+  // Invoked by handleError when a descendant throws during render/mount. Deferred
+  // to a microtask so we never mutate the tree mid-connectedCallback (re-entrancy).
+  catch(error) {
+    if (this._failed) return; // first error wins; ignore the cascade
+    this._failed = true;
+    queueMicrotask(() => this.#renderFallback(error));
+  }
+
+  #renderFallback(error) {
+    this.replaceChildren(); // tear the broken subtree down (runs disconnect cleanups)
+    const reset = () => this.reset();
+    let view = null;
+    try {
+      view = this._fallback ? this._fallback(error, reset) : null;
+    } catch (e) {
+      reportError(e, { phase: "fallback" });
+    }
+    const message = typeof view === "string" ? view : (error && error.message) || "Something went wrong";
+    this.appendChild(view instanceof Node ? view : defaultFallback(message, reset));
+  }
+
+  reset() {
+    if (!this._failed) return;
+    this._failed = false;
+    // Re-clone the blueprint: the rebuilt subtree connects fresh and may throw
+    // again (→ catch), or render cleanly if the cause is gone.
+    this.replaceChildren(...this._blueprint.map((n) => n.cloneNode(true)));
+  }
+}
+
+// Exported so `import { ErrorBoundary } from "@opentf/web"` resolves; the import
+// side effect registers the element (JSX uses the `web-internal-error-boundary` tag).
+export const ErrorBoundary = ErrorBoundaryElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-error-boundary")) {
+  customElements.define("web-internal-error-boundary", ErrorBoundaryElement);
+}

package/runtime/events.js

@@ -0,0 +1,17 @@
+//! Events — the dispatch half of the hybrid event model.
+//
+// Two channels (SPEC §5.4):
+//   • callback props  — `<Picker onSelect={fn}>` sets a property; the component
+//     calls `this.onSelect?.(detail)`. Direct parent→child, no bubbling.
+//   • event listeners — `<Picker onSelect:listen={fn}>` compiles to
+//     `addEventListener("select", fn, opts)` (with `:capture`/`:passive`/`:once`),
+//     for bubbling/interop/multiple subscribers. `emit` is the matching dispatch.
+//
+// `emit(el, "select", detail)` fires a CustomEvent that bubbles and crosses shadow
+// boundaries by default, so a `web-*` element is a first-class event source for any
+// framework consuming it. Returns false if a listener called preventDefault().
+
+export function emit(el, name, detail, options = {}) {
+  const { bubbles = true, composed = true, cancelable = false } = options;
+  return el.dispatchEvent(new CustomEvent(name, { detail, bubbles, composed, cancelable }));
+}