galath 1.0.2

package/packages/galath/src/instance-model.js

@@ -0,0 +1,343 @@
+// =============================================================================
+// instance-model.js
+//
+// XForms-style data model. State is an XML *instance tree* of `XNode`s.
+// Every attribute and text node is itself a `Signal`, so views can bind
+// directly to paths and react to mutations.
+//
+// Public surface:
+//
+//   XNode    - one element node with its own attribute signals.
+//   XTree    - the tree wrapper; emits routed events on every mutation.
+//   coerce   - string -> primitive coercion shared with bindings.
+//   parseDataElement - parse an XML element into an XNode, recursively.
+//
+// Path syntax (a strict subset of XPath - intentional):
+//
+//   /todos/todo                       child step
+//   /todos/todo[@done=true]           attribute predicate (equality)
+//   /todos/todo[@text=hello]          unquoted predicate value
+//   /todos/todo[2]                    1-based index predicate
+//   $todo                             local variable bound by repeat/items
+//   $todo/@text                       attribute on a local variable
+//
+// We only implement what views need; full XPath is deliberately out of scope.
+// If you find yourself wanting predicates with `or`, multi-step descendants,
+// or function calls, please reach for a `<computed>` instead - that's the
+// pressure valve.
+// =============================================================================
+
+import { assert } from './core.js';
+
+export function instanceModelFeature(language) {
+  const { Signal, Disposable } = language;
+
+  // ---------------------------------------------------------------------------
+  // XNode - reactive XML element node
+  // ---------------------------------------------------------------------------
+  class XNode {
+    constructor(name, attrs = {}, text = '') {
+      this.name = name;
+      this.parent = null;
+      this.children = [];
+      this.tree = null; // back-pointer to the owning XTree, set on insert.
+      this.text = new Signal(text); // own text content (not children's).
+      this.attributes = new Map();
+      for (const [k, v] of Object.entries(attrs)) {
+        this.attributes.set(k, new Signal(coerce(v)));
+      }
+    }
+
+    /**
+     * Get the signal for an attribute, creating an empty one if it doesn't
+     * exist. Lazy creation matters: a binding can subscribe to `@foo` before
+     * any code has set it, and we want the first set to fire that
+     * subscriber.
+     */
+    attr(name) {
+      if (!this.attributes.has(name)) this.attributes.set(name, new Signal(''));
+      return this.attributes.get(name);
+    }
+
+    get(name) {
+      return this.attr(name).value;
+    }
+
+    set(name, value) {
+      const sig = this.attr(name);
+      const oldValue = sig.value;
+      sig.value = coerce(value);
+      if (!Object.is(oldValue, sig.value)) {
+        this.tree?.notify({
+          type: 'xforms-value-changed',
+          node: this,
+          attribute: name,
+          oldValue,
+          value: sig.value,
+        });
+      }
+    }
+
+    /** Append a child. Pass `silent: true` during initial parse to skip events. */
+    append(child, { silent = false } = {}) {
+      child.parent = this;
+      this.children.push(child);
+      child.adoptTree(this.tree);
+      if (!silent) {
+        this.tree?.notify({ type: 'xforms-insert', node: child, parent: this });
+      }
+      return child;
+    }
+
+    insertBefore(child, reference, { silent = false } = {}) {
+      child.parent = this;
+      child.adoptTree(this.tree);
+      const i = this.children.indexOf(reference);
+      if (i < 0) this.children.push(child);
+      else this.children.splice(i, 0, child);
+      if (!silent) {
+        this.tree?.notify({ type: 'xforms-insert', node: child, parent: this });
+      }
+      return child;
+    }
+
+    remove() {
+      if (!this.parent) return;
+      const parent = this.parent;
+      parent.children = parent.children.filter(c => c !== this);
+      this.parent = null;
+      parent.tree?.notify({ type: 'xforms-delete', node: this, parent });
+    }
+
+    /** Recursively claim a tree pointer for this subtree (after splicing). */
+    adoptTree(tree) {
+      this.tree = tree;
+      for (const c of this.children) c.adoptTree(tree);
+    }
+
+    /** Slash-separated path from the root, e.g. "/todos/todo". */
+    path() {
+      const parts = [];
+      let n = this;
+      while (n && n.parent) {
+        parts.unshift(n.name);
+        n = n.parent;
+      }
+      return '/' + parts.join('/');
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // XTree - owner of the root XNode plus listener bus
+  // ---------------------------------------------------------------------------
+  class XTree {
+    constructor(root) {
+      this.root = root;
+      // Monotonic version counter. The renderer subscribes to this so any
+      // mutation in the tree triggers a re-render.
+      this.version = new Signal(0);
+      // Routed listeners by event type. Use '*' to listen to everything.
+      this.listeners = new Map();
+      root.adoptTree(this);
+    }
+
+    on(type, fn) {
+      if (!this.listeners.has(type)) this.listeners.set(type, new Set());
+      this.listeners.get(type).add(fn);
+      return new Disposable(() => this.listeners.get(type)?.delete(fn));
+    }
+
+    /**
+     * Dispatch an event to subscribers. Always increments `version` so the
+     * renderer wakes up. Event objects are augmented with a `path` so XML
+     * `<listener observer="/some/path">` can filter by prefix.
+     */
+    notify(event) {
+      event.path = event.node?.path?.() || event.parent?.path?.() || '/';
+      this.version.value = this.version.value + 1;
+      for (const fn of [...(this.listeners.get(event.type) ?? [])]) fn(event);
+      for (const fn of [...(this.listeners.get('*') ?? [])]) fn(event);
+    }
+
+    /** Resolve a path to a list of XNodes. Returns [] when no match. */
+    select(path, context = {}) {
+      if (!path) return [];
+      path = String(path).trim();
+      // `/foo/@attr` and `/foo/text()` are *value* selectors; treated here as
+      // "node containing the value" so callers can post-process.
+      if (path.includes('/@')) path = path.slice(0, path.lastIndexOf('/@'));
+      if (path.endsWith('/text()')) path = path.slice(0, -7);
+
+      // Local variable form: $name or $name/...
+      if (path.startsWith('$')) {
+        const m = path.match(/^\$([A-Za-z_][\w-]*)(?:\/(.*))?$/);
+        if (!m) return [];
+        const base = context[`$${m[1]}`] ?? context[m[1]];
+        if (!base) return [];
+        const rest = m[2];
+        return rest ? selectFrom(base, splitPath(rest)) : [base];
+      }
+
+      // Absolute form: /foo/bar
+      return selectFrom(this.root, splitPath(path.replace(/^\//, '')));
+    }
+
+    /** Resolve a path or `path/@attr` or `path/text()` to a value. */
+    valueOf(path, context = {}) {
+      const a = String(path).match(/^(.*)\/@([\w:-]+)$/);
+      if (a) return this.select(a[1], context)[0]?.get(a[2]) ?? '';
+      const t = String(path).match(/^(.*)\/text\(\)$/);
+      if (t) return this.select(t[1], context)[0]?.text.value ?? '';
+      const node = this.select(path, context)[0];
+      return node?.text.value ?? node ?? '';
+    }
+
+    /** Write a value to `path/@attr` or `path/text()`. */
+    setValue(path, value, context = {}) {
+      const a = String(path).match(/^(.*)\/@([\w:-]+)$/);
+      if (a) {
+        for (const node of this.select(a[1], context)) node.set(a[2], value);
+        return;
+      }
+      const t = String(path).match(/^(.*)\/text\(\)$/);
+      if (t) {
+        for (const node of this.select(t[1], context)) {
+          const old = node.text.value;
+          node.text.value = coerce(value);
+          if (!Object.is(old, node.text.value)) {
+            this.notify({
+              type: 'xforms-value-changed',
+              node,
+              oldValue: old,
+              value: node.text.value,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Path internals
+  // ---------------------------------------------------------------------------
+
+  // Split a path into steps but tolerate predicate brackets that may
+  // contain slashes in the value. Today we don't allow slashes in values, so
+  // the simple split is fine; this helper keeps the call site readable.
+  function splitPath(pathBody) {
+    return pathBody.split('/').filter(Boolean);
+  }
+
+  // Recursive walk: from `node`, take the step in `parts[0]` and recurse on
+  // the rest. `*` matches any element name.
+  function selectFrom(node, parts) {
+    if (parts.length === 0) return [node];
+    const [raw, ...tail] = parts;
+    const step = parseStep(raw);
+    if (!step) return [];
+    let matches = node.children.filter(c => step.name === '*' || c.name === step.name);
+    if (step.attr) {
+      matches = matches.filter(c => looseEqual(c.get(step.attr), step.value));
+    }
+    if (step.index != null) {
+      matches = matches[step.index - 1] ? [matches[step.index - 1]] : [];
+    }
+    return matches.flatMap(c => selectFrom(c, tail));
+  }
+
+  // Parse one step: `name`, `name[@attr=value]`, `name[2]`.
+  function parseStep(step) {
+    const m = step.match(
+      /^([\w:-]+|\*)(?:\[@([\w:-]+)=['"]?([^'"\]]+)['"]?\])?(?:\[(\d+)\])?$/,
+    );
+    if (!m) return null;
+    return {
+      name: m[1],
+      attr: m[2],
+      value: coerce(m[3]),
+      index: m[4] ? Number(m[4]) : null,
+    };
+  }
+
+  // Equality is "loose" (string comparison) because XML attributes start as
+  // strings; we coerce on the right side, so for a predicate like
+  // `[@done=true]` against `done="true"` the comparison succeeds.
+  function looseEqual(a, b) {
+    return String(a) === String(b);
+  }
+
+  /**
+   * Coerce a string into a primitive: "true"/"false" -> Boolean,
+   * "12.5" -> Number, "" -> empty string. Used everywhere a value enters
+   * the tree from text.
+   */
+  function coerce(value) {
+    if (value === true || value === 'true') return true;
+    if (value === false || value === 'false') return false;
+    if (
+      typeof value === 'string' &&
+      value.trim() !== '' &&
+      /^-?\d+(\.\d+)?$/.test(value)
+    ) {
+      return Number(value);
+    }
+    return value ?? '';
+  }
+
+  // Read element attributes into a plain object, optionally interpolating
+  // `{expr}` placeholders. Skips namespaced attrs (those with `:`) because
+  // those carry framework directives like `bind:` / `on:`.
+  function attrsObject(element, instance = null, local = {}) {
+    const out = {};
+    for (const attr of [...element.attributes]) {
+      if (attr.name.includes(':')) continue;
+      out[attr.name] = instance
+        ? language.interpolate(attr.value, instance, local, { raw: true })
+        : attr.value;
+    }
+    return out;
+  }
+
+  /**
+   * Recursively turn an XML element tree (as produced by DOMParser) into an
+   * XNode tree. `silent: true` skips events while the tree is still empty.
+   */
+  function parseDataElement(element, instance = null, local = {}) {
+    const node = new XNode(
+      element.localName,
+      attrsObject(element, instance, local),
+      ownText(element),
+    );
+    for (const child of [...element.children]) {
+      node.append(parseDataElement(child, instance, local), { silent: true });
+    }
+    return node;
+  }
+
+  // Direct text children only - we don't merge descendant text.
+  function ownText(element) {
+    return [...element.childNodes]
+      .filter(n => n.nodeType === Node.TEXT_NODE)
+      .map(n => n.textContent)
+      .join('')
+      .trim();
+  }
+
+  // Expose to other features.
+  language.XNode = XNode;
+  language.XTree = XTree;
+  language.coerce = coerce;
+  language.parseDataElement = parseDataElement;
+
+  // ---------------------------------------------------------------------------
+  // Self-tests
+  // ---------------------------------------------------------------------------
+  language.test('instance: path selection, predicate, valueOf', () => {
+    const root = new XNode('data');
+    const tree = new XTree(root);
+    root.append(new XNode('todo', { id: 'a', done: 'true' }), { silent: true });
+    root.append(new XNode('todo', { id: 'b', done: 'false' }), { silent: true });
+    assert(tree.select('/todo[@done=true]').length === 1, 'predicate failed');
+    assert(tree.valueOf('/todo[@id=b]/@done') === false, 'valueOf failed');
+  });
+}

package/packages/galath/src/morph.js

@@ -0,0 +1,237 @@
+// =============================================================================
+// morph.js
+//
+// A small, dependency-free DOM morpher.
+//
+// The Galath rendering pipeline produces a fresh HTML string on every change
+// and would prefer to *replace* the DOM each time. That's catastrophic for UX:
+// inputs lose focus, scroll positions reset, transitions tear. We can't ship
+// that. Instead we compute the new HTML, parse it into an off-screen tree,
+// and surgically rewrite the *live* tree to match the new tree, leaving every
+// untouched node alone.
+//
+// This is the same job morphdom does. We write our own here because the
+// project rule is "no external npm packages". Ours is intentionally short
+// (~80 lines of logic) and tuned for Galath's needs:
+//
+//   * Preserve focus. If the user is typing in an <input> when the morph
+//     happens, we DO NOT clobber their value or selection. We let the live
+//     element keep its state and just sync attributes that aren't user-typed.
+//
+//   * Preserve checkbox / radio state in the same way.
+//
+//   * Match children purely by position. Galath's renderer emits stable order
+//     based on selection results, so positional matching is fine. Keyed
+//     reconciliation is intentionally out of scope - if you need stable
+//     identity across reorders, write a `<datatemplate key="...">` and rely
+//     on the rendering layer to emit a stable order.
+//
+//   * Skip subtrees the renderer marked `data-xes-frozen`. (Reserved for
+//     future use; right now nothing emits it, but leaving the hook open lets
+//     us escape-hatch later without touching every caller.)
+//
+// The exported function `morph(fromNode, toNode)` mutates `fromNode` in place
+// so its content equals `toNode`. It returns nothing.
+// =============================================================================
+
+// Element tags whose content is "user input" - we should never overwrite
+// `value`, `selectionStart`, etc. on these while they have focus.
+const FORM_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+
+/**
+ * Morph `fromNode` so it structurally matches `toNode`.
+ * Both should be Elements (not DocumentFragments).
+ *
+ * IMPORTANT: when `fromNode` is a Custom Element (its tag contains a hyphen
+ * AND it's a registered element), we sync ATTRIBUTES but never recurse into
+ * its children. Custom elements own their internal DOM via their own
+ * renderNow; parents must not clobber that. Attribute changes still flow,
+ * which lets prop updates re-trigger the child component's render.
+ */
+export function morph(fromNode, toNode) {
+  if (fromNode.nodeName !== toNode.nodeName) {
+    fromNode.replaceWith(toNode);
+    return;
+  }
+  syncAttributes(fromNode, toNode);
+  if (isCustomElement(fromNode)) return; // its internals are not ours.
+  syncChildren(fromNode, toNode);
+}
+
+function isCustomElement(el) {
+  if (!el || el.nodeType !== Node.ELEMENT_NODE) return false;
+  const name = el.localName;
+  return name.includes('-') && !!customElements.get(name);
+}
+
+// -----------------------------------------------------------------------------
+// Attribute sync
+// -----------------------------------------------------------------------------
+// Walk the new attribute set and copy values across; remove attributes that
+// don't exist in the new tree. We special-case form fields so that an input
+// being edited doesn't have its `value` ripped out from under the user.
+// -----------------------------------------------------------------------------
+function syncAttributes(fromEl, toEl) {
+  const isFocusedInput =
+    fromEl === document.activeElement && FORM_TAGS.has(fromEl.tagName);
+
+  // Copy/replace attributes from the new element.
+  for (const attr of toEl.attributes) {
+    // The DOM `value` attribute is only the *initial* value of an input, but
+    // many devs (and Galath bindings) write to .value as a property. If the
+    // input is currently focused we leave its live value alone.
+    if (isFocusedInput && (attr.name === 'value' || attr.name === 'checked')) continue;
+    if (fromEl.getAttribute(attr.name) !== attr.value) {
+      fromEl.setAttribute(attr.name, attr.value);
+    }
+  }
+
+  // Remove attributes that no longer exist in the new tree.
+  // We iterate over a snapshot because we mutate during the loop.
+  for (const attr of [...fromEl.attributes]) {
+    if (!toEl.hasAttribute(attr.name)) {
+      if (isFocusedInput && (attr.name === 'value' || attr.name === 'checked')) continue;
+      fromEl.removeAttribute(attr.name);
+    }
+  }
+
+  // Sync the `value` *property* of form inputs that aren't focused. The
+  // attribute alone doesn't update the live input box once it's been typed
+  // into.
+  if (FORM_TAGS.has(fromEl.tagName) && !isFocusedInput) {
+    const newValue = toEl.getAttribute('value') ?? '';
+    if (fromEl.value !== newValue) fromEl.value = newValue;
+    if ('checked' in fromEl) {
+      const newChecked = toEl.hasAttribute('checked');
+      if (fromEl.checked !== newChecked) fromEl.checked = newChecked;
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Children sync
+// -----------------------------------------------------------------------------
+// Pair children by index. Where a child changes type (e.g. <span> became
+// <div>), we replace it. Where it's the same tag, we recurse. Where the new
+// tree has fewer children, we trim. Where it has more, we append.
+//
+// Text nodes are handled specially because they can't be morphed - we just
+// overwrite their `data` property when it differs.
+// -----------------------------------------------------------------------------
+function syncChildren(fromEl, toEl) {
+  const fromChildren = [...fromEl.childNodes];
+  const toChildren = [...toEl.childNodes];
+
+  // Keyed fast path: when *every* element child of the new tree carries
+  // `data-xes-key`, reconcile by key instead of by position. This survives
+  // reorders without churning DOM that just changed places.
+  if (allKeyed(toChildren)) {
+    syncKeyedChildren(fromEl, fromChildren, toChildren);
+    return;
+  }
+
+  const max = Math.max(fromChildren.length, toChildren.length);
+
+  for (let i = 0; i < max; i++) {
+    const fromChild = fromChildren[i];
+    const toChild = toChildren[i];
+
+    if (!toChild) {
+      // New tree is shorter - drop the extra live node.
+      fromChild.remove();
+      continue;
+    }
+
+    if (!fromChild) {
+      // New tree is longer - append the new node (cloned so the off-screen
+      // template stays reusable).
+      fromEl.appendChild(toChild.cloneNode(true));
+      continue;
+    }
+
+    // Both exist at this index. Decide what to do based on node types.
+    if (fromChild.nodeType !== toChild.nodeType) {
+      // E.g. text became element. Just replace.
+      fromChild.replaceWith(toChild.cloneNode(true));
+      continue;
+    }
+
+    if (fromChild.nodeType === Node.TEXT_NODE) {
+      if (fromChild.data !== toChild.data) fromChild.data = toChild.data;
+      continue;
+    }
+
+    if (fromChild.nodeType === Node.COMMENT_NODE) {
+      // Comments rarely matter for behavior; sync data anyway.
+      if (fromChild.data !== toChild.data) fromChild.data = toChild.data;
+      continue;
+    }
+
+    if (fromChild.nodeType === Node.ELEMENT_NODE) {
+      // Future hook: a renderer can mark a subtree `data-xes-frozen` to opt
+      // out of morphing. Today nothing emits it. Cheap to keep.
+      if (fromChild.hasAttribute && fromChild.hasAttribute('data-xes-frozen')) continue;
+
+      if (fromChild.nodeName !== toChild.nodeName) {
+        fromChild.replaceWith(toChild.cloneNode(true));
+        continue;
+      }
+
+      // Same tag. Recurse.
+      morph(fromChild, toChild);
+    }
+  }
+}
+
+// Returns true when there is at least one element child and every element
+// child has `data-xes-key`. Non-element nodes (text, comments) are ignored
+// for this decision but are dropped during the keyed sync.
+function allKeyed(nodes) {
+  let any = false;
+  for (const n of nodes) {
+    if (n.nodeType !== Node.ELEMENT_NODE) continue;
+    if (!n.hasAttribute || !n.hasAttribute('data-xes-key')) return false;
+    any = true;
+  }
+  return any;
+}
+
+// Reorder `fromEl`'s children to match `toChildren` by key. Existing nodes
+// are MOVED (not recreated) so their internal state - input value, scroll,
+// focus, attached listeners - survives a list reorder. Missing keys are
+// inserted from a deep clone of the new template; surplus keyed nodes are
+// removed.
+function syncKeyedChildren(fromEl, fromChildren, toChildren) {
+  // Drop any non-keyed live children up front; they don't survive keying.
+  for (const child of fromChildren) {
+    if (child.nodeType !== Node.ELEMENT_NODE) {
+      child.remove();
+      continue;
+    }
+    if (!child.hasAttribute('data-xes-key')) child.remove();
+  }
+  const byKey = new Map();
+  for (const child of [...fromEl.childNodes]) {
+    if (child.nodeType === Node.ELEMENT_NODE && child.hasAttribute('data-xes-key')) {
+      byKey.set(child.getAttribute('data-xes-key'), child);
+    }
+  }
+  const used = new Set();
+  for (const newChild of toChildren) {
+    if (newChild.nodeType !== Node.ELEMENT_NODE) continue;
+    const key = newChild.getAttribute('data-xes-key');
+    const existing = byKey.get(key);
+    if (existing) {
+      // appendChild on a child already inside fromEl moves it, which is
+      // exactly what we want for "place at the next position".
+      fromEl.appendChild(existing);
+      morph(existing, newChild);
+      used.add(key);
+    } else {
+      fromEl.appendChild(newChild.cloneNode(true));
+    }
+  }
+  for (const [key, el] of byKey) {
+    if (!used.has(key) && el.parentNode === fromEl) el.remove();
+  }
+}