@xoong/core 0.0.0-stage → 0.0.35

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duong Tran Xuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @xoong/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The reactive base of xoong: signals, `html` templates and Light DOM custom elements. No dependencies.
+
+## Install
+
+```bash
+npm install @xoong/core
+```
+
+## Use
+
+```js
+import { signal, computed, effect, html, render, XoElement, define } from '@xoong/core';
+
+const count = signal(0);
+class ClickCounter extends XoElement {
+  render() { return html`<button @click=${() => count.value++}>Clicked ${() => count.value}</button>`; }
+}
+define('click-counter', ClickCounter);
+```
+
+`XoControl` (also here) is the base of form controls: value, validity, `dirty` and `touched` through `ElementInternals`.
+
+## More
+
+* Documentation and demos: https://github.com/fpt-duongtx/xoong#readme
+* Source: https://github.com/fpt-duongtx/xoong/tree/main/packages/core
+* All packages share one version number and are released together: https://github.com/fpt-duongtx/xoong/releases
+* xoong is a working prototype (0.0.x): the HTML syntax is still Draft.
+
+MIT licence.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@xoong/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.35",
+  "description": "xoong core: signals, Light DOM custom elements, html templates. Zero dependencies.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./signals": "./src/signals.js",
+    "./closest": "./src/closest.js",
+    "./syntax": "./src/syntax.js"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xoong",
+    "web-framework",
+    "openapi",
+    "custom-elements"
+  ],
+  "author": "Duong Tran Xuan <duongtx1505@icloud.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fpt-duongtx/xoong.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/fpt-duongtx/xoong/issues"
+  },
+  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  }
+}

package/src/closest.js

@@ -0,0 +1,24 @@
+// @ts-check
+/** Edit distance between two strings (Levenshtein). */
+export function distance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++)
+    for (let j = 1; j <= b.length; j++)
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return dp[a.length][b.length];
+}
+
+/**
+ * The candidate closest to `ref` (case-insensitive), or undefined when nothing is close enough.
+ * Used for "unknown operation ... closest: ..." messages in the runtime and in `xoong check`.
+ * @param {string} ref @param {Iterable<string>} candidates
+ */
+export function nearest(ref, candidates) {
+  let best, bestD = Infinity;
+  for (const c of candidates) {
+    const d = distance(ref.toLowerCase(), c.toLowerCase());
+    if (d < bestD) { bestD = d; best = c; }
+  }
+  return bestD <= Math.max(3, Math.floor(ref.length / 3)) ? best : undefined;
+}

package/src/control.js

@@ -0,0 +1,230 @@
+// @ts-check
+import { signal, batch } from './signals.js';
+import { XoElement } from './element.js';
+import { text } from './text.js';
+
+/**
+ * Base class for custom form controls (rich text, combobox, tag input, your own image field).
+ *
+ * A control built on it behaves like a native input in a <form>:
+ *   - it submits its value (`name`, `value`) through ElementInternals, so FormData and `xo-submit` see it;
+ *   - it takes part in constraint validation (`required`, `setCustomValidity`, `validity`, `checkValidity`,
+ *     `reportValidity`, the form's own submit validation);
+ *   - it resets with the form, and is disabled with its fieldset;
+ *   - it tracks `dirty`, `touched` and `pristine` as signals, so markup and JS can read them the same way for every control.
+ *
+ * Subclass it, render the inner editing UI (Light DOM), and call `userInput(value)` when the person changes the value:
+ *
+ *   class StarRating extends XoControl {
+ *     static props = { ...XoControl.props, max: Number };
+ *     render() { return html`<button @click=${() => this.userInput(Number(this.value) + 1)}>+</button>`; }
+ *     validate(value) { return Number(value) > this.max ? 'Too many stars' : ''; }   // optional: '' means valid
+ *   }
+ *   define('star-rating', StarRating);
+ *
+ * Where ElementInternals does not exist (older DOMs, happy-dom) the control keeps working on its own: `value`, validity and
+ * state still behave; it just does not appear in a native FormData. `xo-form` reads controls through these properties.
+ */
+export class XoControl extends XoElement {
+  static formAssociated = true;
+  static props = { name: String, required: Boolean, disabled: Boolean, readonly: Boolean };
+
+  /** @type {ElementInternals | null} */ #internals = null;
+  #value = signal(/** @type {any} */ (''));
+  #initial = signal(/** @type {any} */ (''));
+  #touched = signal(false);
+  #custom = signal('');
+  #hook = signal('');
+  #started = false;
+  #formDisabled = false; // disabled by a <fieldset disabled>, tracked apart from the `disabled` attribute
+
+  constructor() {
+    super();
+    try { this.#internals = this.attachInternals?.() ?? null; } catch { this.#internals = null; }
+    this.addEventListener('focusout', (e) => { if (!this.contains(/** @type {Node | null} */ (e.relatedTarget))) this.markTouched(); });
+    // A value set on the element before it was upgraded (the tag was used before `define`) is an own property that would hide the accessor.
+    // It is kept aside and becomes the start value at the first use: a subclass is not ready to run setValue while this constructor runs.
+    if (Object.prototype.hasOwnProperty.call(this, 'value')) { this.#early = { value: /** @type {any} */ (this).value }; delete (/** @type {any} */ (this)).value; }
+  }
+
+  /** @type {{ value: any } | null} */ #early = null;
+  #applyEarly() {
+    if (!this.#early) return;
+    const { value } = this.#early;
+    this.#early = null;
+    this.setValue(value);
+  }
+
+  // ---- value ----------------------------------------------------------------------------------------------------------
+
+  /** The value. Strings by default; a subclass may hold anything and override `serialize`. */
+  get value() { this.#applyEarly(); return this.#value.value; }
+  set value(v) { this.#applyEarly(); this.setValue(v); }
+
+  /**
+   * Set the value programmatically (like `input.value = x`: no events). The first value set while the control is not yet
+   * started (an attribute or property before connection) becomes the initial value that `reset` and `dirty` compare with.
+   */
+  setValue(v) {
+    batch(() => {
+      this.#value.value = v;
+      if (!this.#started) this.#initial.value = v;
+    });
+    this.#sync();
+  }
+
+  /** The person changed the value: set it and fire `input`, like a native control. */
+  userInput(v) {
+    this.setValue(v);
+    this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+  }
+
+  /** The person finished a change (blur after editing, a selection): fire `change`. */
+  userChange() {
+    this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+  }
+
+  /** What the form submits for a value: a string, a File, FormData, or null for nothing. Override for structured values. */
+  serialize(v) {
+    if (v == null || v === '') return v === '' ? '' : null;
+    if (typeof FormData !== 'undefined' && v instanceof FormData) return v;
+    if (typeof File !== 'undefined' && v instanceof File) return v; // a file input-like control submits the file itself
+    return typeof v === 'object' ? JSON.stringify(v) : String(v);
+  }
+
+  /** Whether a value counts as "nothing entered" for `required`. Override for structured values. */
+  isEmpty(v) { return v == null || v === '' || (Array.isArray(v) && v.length === 0); }
+
+  /** Optional validation hook: return an error message for an invalid value, '' when valid. Runs on every change. */
+  validate(_value) { return ''; }
+
+  // ---- state (signals: reading them inside a template or effect is tracked) -----------------------------------------------
+
+  get initialValue() { return this.#initial.value; }
+  get dirty() { return !same(this.#value.value, this.#initial.value); }
+  get pristine() { return !this.dirty; }
+  get touched() { return this.#touched.value; }
+  /** True when the control has no validation error. */
+  get valid() { return this.validationMessage === ''; }
+  get invalid() { return !this.valid; }
+
+  /** Mark the control as visited (blur does this). */
+  markTouched() {
+    if (this.#touched.peek()) return;
+    this.#touched.value = true;
+    this.#reflect();
+  }
+
+  // ---- validation -------------------------------------------------------------------------------------------------------
+
+  /** The message to show, or '' when valid. Reading it is tracked. */
+  get validationMessage() {
+    this.#value.value; // track
+    this.#hook.value;
+    if (this.#custom.value) return this.#custom.value;
+    if (this.required && this.isEmpty(this.#value.value)) return text('xoong.validation.required', 'Please fill in this field.');
+    return this.#hook.value;
+  }
+  /** Disabled by its own attribute or by a disabled fieldset. */
+  get isDisabled() { return this.disabled || this.#formDisabled; }
+  get willValidate() { return !this.isDisabled && !this.readonly; }
+  get validity() {
+    const message = this.validationMessage;
+    const missing = this.required && this.isEmpty(this.#value.peek()) && !this.#custom.peek();
+    return { valid: !message, valueMissing: missing, customError: !!(this.#custom.peek() || (this.#hook.peek() && !missing)), badInput: false, typeMismatch: false, patternMismatch: false, rangeOverflow: false, rangeUnderflow: false, stepMismatch: false, tooLong: false, tooShort: false };
+  }
+  /** Set your own error (cross-field rules, server errors). An empty string clears it. */
+  setCustomValidity(message) {
+    this.#custom.value = String(message ?? '');
+    this.#sync();
+  }
+  checkValidity() {
+    if (!this.willValidate || this.valid) return true;
+    this.dispatchEvent(new Event('invalid', { cancelable: true }));
+    return false;
+  }
+  reportValidity() {
+    const ok = this.checkValidity();
+    if (!ok) { this.markTouched(); this.focusTarget?.focus?.(); }
+    return ok;
+  }
+
+  /** The element inside that takes focus (and anchors the browser's validation bubble). Defaults to the first focusable child. */
+  get focusTarget() {
+    return /** @type {HTMLElement | null} */ (this.querySelector('input:not([type=hidden]),select,textarea,button,[contenteditable="true"],[tabindex]:not([tabindex="-1"])')) ?? (this.hasAttribute('tabindex') ? this : null);
+  }
+
+  // ---- reset to initial -------------------------------------------------------------------------------------------------
+
+  /** Back to the initial value, untouched. The form calls this on reset. */
+  reset() {
+    batch(() => { this.#value.value = this.#initial.peek(); this.#touched.value = false; this.#custom.value = ''; });
+    this.#sync();
+  }
+  /** Make the current value the new baseline, as after a successful save: `dirty` becomes false. */
+  markPristine() {
+    this.#initial.value = this.#value.peek();
+    this.#reflect();
+  }
+
+  // ---- form-associated custom element callbacks ---------------------------------------------------------------------------
+
+  formResetCallback() { this.reset(); }
+  /** A fieldset disabled or enabled us. Not reflected into `disabled`: the browser would then keep us disabled for good. */
+  formDisabledCallback(disabled) {
+    this.#formDisabled = !!disabled;
+    this.toggleAttribute('data-form-disabled', !!disabled);
+    this.#sync();
+  }
+  formStateRestoreCallback(state) { if (state != null) this.setValue(state); }
+  get form() { return this.#internals?.form ?? this.closest('form'); }
+
+  // ---- lifecycle ----------------------------------------------------------------------------------------------------------
+
+  connectedCallback() {
+    this.#applyEarly();
+    super.connectedCallback();
+    if (!this.#started) {
+      this.#started = true;
+      if (this.hasAttribute('value') && this.#value.peek() === '') { this.#value.value = this.getAttribute('value'); this.#initial.value = this.#value.peek(); }
+    }
+    this.#sync();
+  }
+
+  attributeChangedCallback(attr, old, value) {
+    super.attributeChangedCallback(attr, old, value);
+    if (attr === 'value' && !this.#started) this.setValue(value);
+    if (attr === 'required' || attr === 'disabled' || attr === 'readonly') this.#sync();
+  }
+
+  // ---- internals ----------------------------------------------------------------------------------------------------------
+
+  /** Push value and validity to the browser and reflect the state as attributes. */
+  #sync() {
+    this.#hook.value = this.validate(this.#value.peek()) || '';
+    const internals = this.#internals;
+    if (internals) {
+      try {
+        internals.setFormValue(this.isDisabled ? null : this.serialize(this.#value.peek()));
+        const message = this.validationMessage;
+        if (message) internals.setValidity({ valueMissing: this.validity.valueMissing, customError: this.validity.customError }, message, this.focusTarget ?? undefined);
+        else internals.setValidity({});
+      } catch { /* a DOM with a partial ElementInternals: keep our own state */ }
+    }
+    this.#reflect();
+  }
+
+  #reflect() {
+    this.toggleAttribute('data-dirty', this.dirty);
+    this.toggleAttribute('data-touched', this.#touched.peek());
+    this.toggleAttribute('data-invalid', !this.valid && this.willValidate);
+  }
+}
+
+/** Equality for control values: primitives by value, structured values by their JSON form. */
+function same(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a && b && typeof a === 'object' && typeof b === 'object') { try { return JSON.stringify(a) === JSON.stringify(b); } catch { return false; } }
+  return false;
+}
+

package/src/element.js

@@ -0,0 +1,118 @@
+// @ts-check
+import { signal, effect } from './signals.js';
+import { render } from './html.js';
+
+const kebab = (s) => s.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+
+function coerce(type, raw) {
+  if (type === Boolean) return raw !== null && raw !== 'false';
+  if (raw === null) return type === Number ? 0 : '';
+  return type === Number ? Number(raw) : String(raw);
+}
+
+function fromProp(type, v) {
+  if (type === Boolean) return v !== null && v !== undefined && v !== false && v !== 'false';
+  if (type === Number) return Number(v ?? 0);
+  return v == null ? '' : String(v);
+}
+
+/**
+ * Light DOM base element.
+ *
+ *   class UserCard extends XoElement {
+ *     static props = { name: String, age: Number }   // attributes <-> signals
+ *     render() { return html`<h3>${() => this.name}</h3>` }
+ *   }
+ *   define('user-card', UserCard)
+ *
+ * - `props` are reflected from attributes and readable/writable as properties;
+ *   reading `this.name` inside a template function is tracked automatically.
+ * - Implement `render()` only if the element OWNS its content. To enhance
+ *   server-rendered HTML in place, implement `connected()` instead.
+ * - Use `this.effect(fn)` for side effects: it is disposed on disconnect.
+ */
+// Importable outside a browser (SSR, tooling, tests); elements only run in a DOM.
+const Base = /** @type {typeof HTMLElement} */ (globalThis.HTMLElement ?? class {});
+
+export class XoElement extends Base {
+  /** @type {Record<string, typeof String | typeof Number | typeof Boolean>} */
+  static props = {};
+
+  static get observedAttributes() {
+    return Object.keys(this.props).map(kebab);
+  }
+
+  /** @type {Record<string, import('./signals.js').Signal<any>>} */
+  #sigs = {};
+  /** @type {(() => void)[]} */
+  #disposers = [];
+
+  constructor() {
+    super();
+    const props = /** @type {typeof XoElement} */ (this.constructor).props;
+    for (const [name, type] of Object.entries(props)) {
+      // Properties set before the element was upgraded win over defaults.
+      const own = Object.getOwnPropertyDescriptor(this, name);
+      if (own) delete (/** @type {any} */ (this))[name];
+      this.#sigs[name] = signal(own ? own.value : coerce(type, null));
+    }
+  }
+
+  /** @param {string} name */
+  _sig(name) {
+    return this.#sigs[name];
+  }
+
+  attributeChangedCallback(attr, _old, value) {
+    const props = /** @type {typeof XoElement} */ (this.constructor).props;
+    const name = Object.keys(props).find((n) => kebab(n) === attr);
+    if (name) this.#sigs[name].value = coerce(props[name], value);
+  }
+
+  connectedCallback() {
+    const result = this.render?.();
+    if (result) this.#disposers.push(render(result, this));
+    this.connected?.();
+  }
+
+  disconnectedCallback() {
+    this.#disposers.splice(0).forEach((d) => d());
+    this.disconnected?.();
+  }
+
+  /** Resolves when the element's children are there: at once when the page is parsed, else after the parser reached the end of the document. Await it in connected(). */
+  ready() {
+    return new Promise((r) => (document.readyState === 'loading' ? document.addEventListener('DOMContentLoaded', () => r(this), { once: true }) : r(this)));
+  }
+
+  /** Side effect bound to this element's lifetime. @param {() => void | (() => void)} fn */
+  effect(fn) {
+    this.#disposers.push(effect(fn));
+  }
+
+  /** Dispatch a bubbling CustomEvent. */
+  emit(name, detail) {
+    this.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));
+  }
+}
+
+/**
+ * Register a custom element (idempotent). Tag must contain a hyphen.
+ * @param {string} tag
+ * @param {typeof XoElement} cls
+ */
+export function define(tag, cls) {
+  if (customElements.get(tag)) return;
+  for (const name of Object.keys(cls.props)) {
+    Object.defineProperty(cls.prototype, name, {
+      get() {
+        return this._sig(name).value;
+      },
+      set(v) {
+        this._sig(name).value = fromProp(cls.props[name], v);
+      },
+      configurable: true,
+    });
+  }
+  customElements.define(tag, cls);
+}

package/src/html.js

@@ -0,0 +1,153 @@
+// @ts-check
+/**
+ * `html` tagged template with fine-grained reactive bindings (Light DOM, no VDOM).
+ *
+ *   html`<h3 class=${() => cls.value}>${() => name.value}</h3>
+ *        <button @click=${() => save()}>Save</button>`
+ *
+ * Binding rules (the whole language):
+ *   child position : function => reactive, value => static; arrays, nodes and
+ *                    nested `html` results are supported.
+ *   name=${v}      : attribute; function => reactive. null/false removes it.
+ *   ?name=${v}     : boolean attribute.
+ *   .name=${v}     : DOM property (use lowercase-insensitive names; original case is kept).
+ *   @event=${fn}   : event listener.
+ * An attribute value must be exactly one expression (no mixing text and `${}`).
+ */
+import { effect } from './signals.js';
+
+const MARK = '__xo_';
+const cache = new WeakMap();
+
+export class TemplateResult {
+  /** @param {TemplateStringsArray} strings @param {unknown[]} values */
+  constructor(strings, values) {
+    this.strings = strings;
+    this.values = values;
+  }
+}
+
+/**
+ * @param {TemplateStringsArray} strings
+ * @param {...unknown} values
+ */
+export const html = (strings, ...values) => new TemplateResult(strings, values);
+
+/** Parse once per call site. */
+function compile(strings) {
+  let compiled = cache.get(strings);
+  if (compiled) return compiled;
+  let out = '';
+  let cur = strings[0];
+  /** @type {({kind:'child'}|{kind:'attr', name:string, prefix:string})[]} */
+  const parts = [];
+  for (let i = 0; i < strings.length - 1; i++) {
+    out += cur;
+    cur = strings[i + 1];
+    if (out.lastIndexOf('<') > out.lastIndexOf('>')) {
+      const m = /([@.?]?)([^\s"'<>=/@.?]+)=(["']?)$/.exec(out);
+      if (!m) throw new Error('xoong html: an expression inside a tag must be a whole attribute value, e.g. class=${...}');
+      out = out.slice(0, m.index) + `${m[2].toLowerCase()}="${MARK}${i}"`;
+      if (m[3] && cur.startsWith(m[3])) cur = cur.slice(1); // drop the closing quote that wrapped the expression
+      parts.push({ kind: 'attr', name: m[2], prefix: m[1] });
+    } else {
+      out += `<!--${MARK}${i}-->`;
+      parts.push({ kind: 'child' });
+    }
+  }
+  out += cur;
+  const template = document.createElement('template');
+  template.innerHTML = out;
+  compiled = { template, parts };
+  cache.set(strings, compiled);
+  return compiled;
+}
+
+/**
+ * Render a template result into `container`. Returns a dispose function.
+ * @param {TemplateResult} result
+ * @param {Element | DocumentFragment} container
+ * @returns {() => void}
+ */
+export function render(result, container) {
+  const disposers = [];
+  const frag = instantiate(result, disposers);
+  container.replaceChildren(frag);
+  return () => disposers.splice(0).forEach((d) => d());
+}
+
+function instantiate(result, disposers) {
+  const { template, parts } = compile(result.strings);
+  const frag = /** @type {DocumentFragment} */ (template.content.cloneNode(true));
+  const walker = document.createTreeWalker(frag, NodeFilter.SHOW_COMMENT | NodeFilter.SHOW_ELEMENT);
+  /** @type {Comment[]} */ const comments = [];
+  /** @type {Element[]} */ const elements = [];
+  while (walker.nextNode()) {
+    const n = walker.currentNode;
+    if (n.nodeType === 8) {
+      if (/** @type {Comment} */ (n).data.startsWith(MARK)) comments.push(/** @type {Comment} */ (n));
+    } else {
+      elements.push(/** @type {Element} */ (n));
+    }
+  }
+  for (const c of comments) {
+    const i = Number(c.data.slice(MARK.length));
+    bindChild(c, result.values[i], disposers);
+  }
+  for (const el of elements) {
+    for (const attr of [...el.attributes]) {
+      if (!attr.value.startsWith(MARK)) continue;
+      const i = Number(attr.value.slice(MARK.length));
+      const part = /** @type {any} */ (parts[i]);
+      el.removeAttribute(attr.name);
+      bindAttr(el, part, result.values[i], disposers);
+    }
+  }
+  return frag;
+}
+
+function bindAttr(el, part, value, disposers) {
+  const { prefix, name } = part;
+  if (prefix === '@') {
+    el.addEventListener(name, /** @type {EventListener} */ (value));
+    disposers.push(() => el.removeEventListener(name, /** @type {EventListener} */ (value)));
+    return;
+  }
+  const apply = (v) => {
+    if (name.startsWith('style:')) el.style[v == null || v === false ? 'removeProperty' : 'setProperty'](name.slice(6), v); // style:--x=${v}: the CSS object model, so a strict CSP (no style="") allows it
+    else if (prefix === '.') el[name] = v;
+    else if (prefix === '?') el.toggleAttribute(name, !!v);
+    else if (v == null || v === false) el.removeAttribute(name);
+    else el.setAttribute(name, v === true ? '' : String(v));
+  };
+  if (typeof value === 'function') disposers.push(effect(() => apply(value())));
+  else apply(value);
+}
+
+function bindChild(marker, value, disposers) {
+  const end = document.createComment('/xo');
+  marker.after(end);
+  marker.data = 'xo';
+  let inner = [];
+  const clear = () => {
+    inner.splice(0).forEach((d) => d());
+    while (marker.nextSibling && marker.nextSibling !== end) marker.nextSibling.remove();
+  };
+  const put = (v) => {
+    clear();
+    const frag = document.createDocumentFragment();
+    appendValue(frag, v, inner);
+    end.before(frag);
+  };
+  if (typeof value === 'function') disposers.push(effect(() => put(value())));
+  else put(value);
+  disposers.push(clear);
+}
+
+function appendValue(frag, v, disposers) {
+  if (v == null || v === false || v === true) return;
+  if (v instanceof TemplateResult) frag.append(instantiate(v, disposers));
+  else if (v instanceof Node) frag.append(v);
+  else if (Array.isArray(v)) v.forEach((x) => appendValue(frag, x, disposers));
+  else frag.append(document.createTextNode(String(v)));
+}

package/src/index.js

@@ -0,0 +1,5 @@
+export { signal, computed, effect, batch, untracked, disposeComputed, Signal } from './signals.js';
+export { html, render, TemplateResult } from './html.js';
+export { XoElement, define } from './element.js';
+export { XoControl } from './control.js';
+export { text, setTextProvider } from './text.js';

package/src/signals.js

@@ -0,0 +1,235 @@
+// @ts-check
+/**
+ * Minimal signals: signal, computed, effect, batch, untracked.
+ *
+ * Semantics (kept deliberately small):
+ *  - Reads inside a computed/effect are tracked automatically.
+ *  - Writes outside a batch flush effects synchronously.
+ *  - Writes inside `batch` flush once at the end of the outermost batch.
+ *  - `effect` is for side effects only. Never fetch data in an effect:
+ *    declare the operation on a view instead.
+ */
+
+/** @typedef {{ run(): void }} Observer */
+
+/** @type {Observer | null} */
+let active = null;
+let batchDepth = 0;
+/** @type {Set<Effect>} */
+const pending = new Set();
+let flushing = false;
+
+/** Track one source in the active observer. */
+function track(source) {
+  if (active) {
+    source.subs.add(active);
+    active.deps.add(source);
+  }
+}
+
+function flush() {
+  if (flushing) return;
+  flushing = true;
+  /** @type {unknown[]} */
+  const errors = [];
+  try {
+    // Effects may schedule more effects while running; loop until stable.
+    let guard = 0;
+    while (pending.size) {
+      if (++guard > 10000) {
+        pending.clear();
+        throw new Error('xoong: effect loop did not settle (an effect keeps writing a signal it reads)');
+      }
+      const [next] = pending;
+      pending.delete(next);
+      // One broken effect must not stop the others from running.
+      try { next.run(); } catch (e) { errors.push(e); }
+    }
+  } finally {
+    flushing = false;
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, `xoong: ${errors.length} effects threw`);
+}
+
+/** Remove `observer` from `source`; a computed nobody watches lets go of its sources. */
+function unsubscribe(source, observer) {
+  source.subs.delete(observer);
+  if (source.subs.size === 0 && source instanceof Computed) source.detach();
+}
+
+/**
+ * @template T
+ */
+export class Signal {
+  /** @type {T} */ #value;
+  /** @type {Set<any>} */ subs = new Set();
+  /** @param {T} value */
+  constructor(value) {
+    this.#value = value;
+  }
+  get value() {
+    track(this);
+    return this.#value;
+  }
+  set value(next) {
+    if (Object.is(next, this.#value)) return;
+    this.#value = next;
+    for (const sub of [...this.subs]) sub.notify();
+    if (batchDepth === 0) flush();
+  }
+  /** Read without tracking. */
+  peek() {
+    return this.#value;
+  }
+  /** Update from the previous value. */
+  update(fn) {
+    this.value = fn(this.#value);
+  }
+}
+
+/**
+ * @template T
+ * @param {T} value
+ * @returns {Signal<T>}
+ */
+export const signal = (value) => new Signal(value);
+
+class Computed {
+  /** @type {Set<any>} */ deps = new Set();
+  /** @type {Set<any>} */ subs = new Set();
+  dirty = true;
+  /** @type {any} */ #value;
+  /** @type {() => any} */ #fn;
+  constructor(fn) {
+    this.#fn = fn;
+  }
+  notify() {
+    if (this.dirty) return;
+    this.dirty = true;
+    for (const sub of [...this.subs]) sub.notify();
+  }
+  /** Stop listening to sources (no observers left, or the owner is discarding it). */
+  detach() {
+    for (const dep of this.deps) dep.subs.delete(this);
+    this.deps.clear();
+    this.dirty = true; // next read recomputes and re-attaches
+  }
+  run() {
+    // Called when re-evaluation is needed.
+    for (const dep of this.deps) dep.subs.delete(this);
+    this.deps.clear();
+    const prev = active;
+    active = this;
+    try {
+      this.#value = this.#fn();
+      this.dirty = false;
+    } finally {
+      active = prev;
+    }
+  }
+  get value() {
+    if (this.dirty) this.run();
+    track(this);
+    return this.#value;
+  }
+  peek() {
+    if (this.dirty) this.run();
+    return this.#value;
+  }
+}
+
+/**
+ * @template T
+ * @param {() => T} fn
+ * @returns {{ readonly value: T, peek(): T }}
+ */
+export const computed = (fn) => new Computed(fn);
+
+/** Release a computed's subscriptions when its owner is discarded. @param {{detach?: () => void}} c */
+export const disposeComputed = (c) => c.detach?.();
+
+class Effect {
+  /** @type {Set<any>} */ deps = new Set();
+  disposed = false;
+  /** @type {void | (() => void)} */ cleanup;
+  /** @param {() => void | (() => void)} fn */
+  constructor(fn) {
+    this.fn = fn;
+  }
+  notify() {
+    if (!this.disposed) pending.add(this);
+  }
+  run() {
+    if (this.disposed) return;
+    this.cleanup?.();
+    for (const dep of [...this.deps]) unsubscribe(dep, this);
+    this.deps.clear();
+    const prev = active;
+    active = this;
+    try {
+      const out = this.fn();
+      this.cleanup = typeof out === 'function' ? out : undefined;
+    } finally {
+      active = prev;
+    }
+  }
+  dispose() {
+    this.disposed = true;
+    pending.delete(this);
+    this.cleanup?.();
+    for (const dep of [...this.deps]) unsubscribe(dep, this);
+    this.deps.clear();
+  }
+}
+
+/**
+ * Run `fn` now and again whenever a signal it read changes.
+ * The function may return a cleanup callback.
+ * @param {() => void | (() => void)} fn
+ * @returns {() => void} dispose
+ */
+export function effect(fn) {
+  const e = new Effect(fn);
+  // Run inside a batch so an effect created within a write sees a stable graph.
+  batchDepth++;
+  try {
+    e.run();
+  } finally {
+    batchDepth--;
+  }
+  if (batchDepth === 0) flush();
+  return () => e.dispose();
+}
+
+/**
+ * Group writes; effects flush once after the outermost batch.
+ * @template T
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flush();
+  }
+}
+
+/**
+ * Read signals without tracking them.
+ * @template T
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function untracked(fn) {
+  const prev = active;
+  active = null;
+  try {
+    return fn();
+  } finally {
+    active = prev;
+  }
+}

package/src/syntax.js

@@ -0,0 +1,19 @@
+// @ts-check
+/**
+ * The names of xoong's declarative HTML syntax. `xoong check` validates against these lists and
+ * llms.txt documents them; a test keeps the runtime (data/src/view.js) and both in step.
+ */
+
+/** Attributes understood inside <xo-view>. */
+export const XO_ATTRIBUTES = ['xo-each', 'xo-if', 'xo-click', 'xo-submit', 'xo-body', 'xo-keep', 'xo-param', 'xo-refresh', 'xo-optimistic', 'xo-select', 'xo-selected', 'xo-with', 'xo-confirm', 'xo-notice', 'xo-add', 'xo-remove', 'xo-move', 'xo-drag', 'xo-t'];
+
+/** Custom elements shipped by xoong. */
+export const XO_ELEMENTS = ['xo-view'];
+
+/** Attributes and elements that come with @xoong/ui (the admin set). */
+export const XO_UI_ATTRIBUTES = ['xo-open', 'xo-close', 'xo-route', 'xo-layout', 'xo-outlet', 'xo-guard'];
+export const XO_UI_ELEMENTS = ['xo-table', 'xo-form', 'xo-dialog', 'xo-toast', 'xo-router'];
+
+/** Attributes and elements of @xoong/controls and @xoong/richtext. */
+export const XO_CONTROL_ATTRIBUTES = ['xo-tab', 'xo-menu-trigger', 'xo-tooltip'];
+export const XO_CONTROL_ELEMENTS = ['xo-tabs', 'xo-menu', 'xo-combobox', 'xo-tags', 'xo-richtext', 'xo-carousel', 'xo-switch', 'xo-date', 'xo-time', 'xo-slider', 'xo-stepper', 'xo-password', 'xo-copy'];

package/src/text.js

@@ -0,0 +1,28 @@
+// @ts-check
+/**
+ * The text hook: how xoong's own packages (validation messages, table labels, confirm buttons) ask for words without knowing about
+ * translation. `text('xoong.table.next', 'Next')` returns the English default, unless a provider is installed (`@xoong/i18n` installs one) that
+ * knows a translation for the key in the active language. Applications never call this directly: they use `t()` from @xoong/i18n.
+ */
+
+/** @type {((key: string, args?: Record<string, any>) => string | undefined) | null} */
+let provider = null;
+
+/** Install (or remove, with null) the provider. It returns undefined for a key it has no message for. */
+export function setTextProvider(fn) { provider = fn; }
+
+/**
+ * @param {string} key a stable key such as "xoong.table.next"
+ * @param {string} fallback the English text; `{name}` placeholders are filled from `args` when no provider answers
+ * @param {Record<string, any>} [args]
+ */
+export function text(key, fallback, args) {
+  const translated = provider?.(key, args);
+  if (translated !== undefined) return translated;
+  if (!args) return fallback;
+  // The English defaults use `{name}` and the simple form `{n, plural, one {# thing} other {# things}}`; @xoong/i18n handles the whole message language.
+  return fallback.replace(/\{(\w+), plural, one \{([^{}]*)\} other \{([^{}]*)\}\}|\{(\w+)\}/g, (m, n, one, other, name) => {
+    if (n) { const v = Number(args[n]); return (v === 1 ? one : other).replace('#', String(v)); }
+    return name in args ? String(args[name]) : m;
+  });
+}