galath 1.0.5 → 1.0.6

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "galath",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "XML language for web applications",
   "scripts": {
     "save": "git add .; git commit -m 'Updated Release'; npm version patch; npm publish; git push --follow-tags;",
-    "serve": "http-server -c-1 -o"
+    "dev": "http-server -c-1 -o"
   },
   "keywords": [
     "xml",

package/src/binding.js

@@ -133,6 +133,23 @@ export function bindingFeature(language) {
     return '';
   }
 
+  /**
+   * Translate XML-friendly operator keywords to their JS equivalents so
+   * authors can avoid XML-escaping `&&` and `||` inside attribute values.
+   *
+   *   count and enabled   →  count && enabled
+   *   x or y              →  x || y
+   *
+   * Word-boundary matching prevents false hits inside identifiers like
+   * `android` or `format`. The XML parser already unescapes `&&`
+   * to `&&` before we see it, so both styles continue to work.
+   */
+  function normalizeExpr(expr) {
+    return String(expr ?? '')
+      .replace(/\band\b/g, '&&')
+      .replace(/\bor\b/g, '||');
+  }
+
   /**
    * The hot path. Evaluate `expr` against the instance + local context.
    *
@@ -147,7 +164,7 @@ export function bindingFeature(language) {
       // eslint-disable-next-line no-new-func
       return Function(
         'ctx',
-        `with (ctx) { return (${expr}); }`,
+        `with (ctx) { return (${normalizeExpr(expr)}); }`,
       )(buildContext(instance, local, event));
     } catch (error) {
       console.warn('[galath] expression failed:', expr, error);
@@ -164,7 +181,7 @@ export function bindingFeature(language) {
       // eslint-disable-next-line no-new-func
       return Function(
         'ctx',
-        `with (ctx) { ${code}; }`,
+        `with (ctx) { ${normalizeExpr(code)}; }`,
       )(buildContext(instance, local, event));
     } catch (error) {
       console.error('[galath] handler failed:', code, error);

package/src/boot.js

@@ -47,6 +47,20 @@ export async function boot({ source, mount }) {
     .use(componentFeature)
     .use(renderingFeature);
 
-  await language.start();
+  try {
+    await language.start();
+  } catch (error) {
+    if (mount) {
+      const msg = String(error?.message ?? error);
+      mount.innerHTML = `<pre style="
+        margin:0;padding:1rem 1.25rem;
+        background:#1e1e1e;color:#f14c4c;
+        font-family:monospace;font-size:.85rem;
+        white-space:pre-wrap;word-break:break-word;
+        border-left:4px solid #f14c4c;
+      "><b>[galath] XML parse error</b>\n${msg.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')}</pre>`;
+    }
+    throw error;
+  }
   return language;
 }

package/src/component.js

@@ -192,16 +192,59 @@ export function componentFeature(language) {
           }
 
           // <computed name="x" from="y">expr</computed> - derived signal.
-          // The legacy <map> spelling still works.
+          // `from` accepts a comma-separated list ("a, b, c") to depend on
+          // multiple sources; the body re-runs whenever any source changes.
+          // When `from` is empty (or names only unknown signals) we fall back
+          // to the instance-tree version counter so the body still re-evaluates
+          // on any tree mutation. The legacy <map> spelling still works.
           for (const tagName of ['computed', 'map']) {
             for (const el of language.childElements(model, tagName)) {
-              const sourceName = el.getAttribute('from');
-              const source = this.scope.signal(sourceName) || this.tree?.version;
-              if (!source) continue;
-              const expr = (el.querySelector('expression')?.textContent || el.textContent || 'value').trim();
-              this.scope.map(el.getAttribute('name'), source, value =>
-                language.evaluate(expr, this, { value, [sourceName]: value }, value),
-              );
+              const fromAttr = el.getAttribute('from') || '';
+              const sourceNames = fromAttr
+                .split(',')
+                .map(s => s.trim())
+                .filter(Boolean);
+              const sources = sourceNames
+                .map(name => this.scope.signal(name))
+                .filter(Boolean);
+              if (sources.length === 0 && this.tree) sources.push(this.tree.version);
+              if (sources.length === 0) continue;
+
+              const expr = (
+                el.querySelector('expression')?.textContent ||
+                el.textContent ||
+                'value'
+              ).trim();
+              const name = el.getAttribute('name');
+
+              const recompute = () => {
+                const ctx = {};
+                // Expose each named source value as a same-named local so
+                // the expression can use them directly even when the
+                // proxy-scope path is bypassed.
+                for (const sourceName of sourceNames) {
+                  const sig = this.scope.signal(sourceName);
+                  if (sig) ctx[sourceName] = sig.value;
+                }
+                // Single-source legacy convenience: `value` aliases the
+                // single source's current value. Multi-source computeds
+                // get the *first* declared source under `value`.
+                if (sourceNames.length > 0) {
+                  const first = this.scope.signal(sourceNames[0]);
+                  if (first) ctx.value = first.value;
+                }
+                return language.evaluate(expr, this, ctx, '');
+              };
+
+              const derived = new language.Signal(recompute());
+              this.scope.signal(name, derived);
+              for (const sig of sources) {
+                this.scope.collect(
+                  sig.subscribe(() => {
+                    derived.value = recompute();
+                  }, false),
+                );
+              }
             }
           }
         }

package/src/controller.js

@@ -141,12 +141,57 @@ export function controllerFeature(language) {
         continue;
       }
 
-      // <fetch url="..." into="signalName" as="json|text"> - asynchronous
-      // HTTP load. The result is written to the named signal when the
-      // response resolves. We also flip an optional `loading` signal and
-      // an `error` signal so the view can render spinners / error states
-      // without writing JS. Operations after <fetch> in the same block
-      // run immediately - this is fire-and-forget.
+      // <store signal="name" key="storageKey" /> - persist a signal to localStorage.
+      // <restore signal="name" key="storageKey" default="value" /> - read it back.
+      // Use <restore> in <on:mount> to rehydrate on page load; pair with a
+      // signal-change <listener> that calls <store> to keep it in sync.
+      if (op.localName === 'store') {
+        const sig = instance.scope.signal(op.getAttribute('signal'));
+        const key = language.evaluate(op.getAttribute('key') ?? '', instance, local, '', event);
+        if (sig && key) {
+          try { localStorage.setItem(key, JSON.stringify(sig.value)); } catch { /* quota or private-mode */ }
+        }
+        continue;
+      }
+
+      if (op.localName === 'restore') {
+        const sig = instance.scope.signal(op.getAttribute('signal'));
+        const key = language.evaluate(op.getAttribute('key') ?? '', instance, local, '', event);
+        if (sig && key) {
+          try {
+            const raw = localStorage.getItem(key);
+            if (raw != null) {
+              sig.value = JSON.parse(raw);
+            } else if (op.hasAttribute('default')) {
+              sig.value = language.evaluate(op.getAttribute('default'), instance, local, sig.value, event);
+            }
+          } catch {
+            if (op.hasAttribute('default')) {
+              sig.value = language.evaluate(op.getAttribute('default'), instance, local, sig.value, event);
+            }
+          }
+        }
+        continue;
+      }
+
+      // <fetch url="..." into="signalName" as="json|text"
+      //        method="POST" body="expr" headers="expr" loading="sig"
+      //        error="sig"> - asynchronous HTTP load.
+      //
+      //   url       - evaluated expression yielding the absolute or relative URL
+      //   method    - HTTP method, default GET (literal string, not evaluated)
+      //   body      - evaluated expression; objects are JSON-encoded, strings
+      //               pass through, FormData/Blob/etc are sent as-is
+      //   headers   - evaluated expression; should yield a plain object whose
+      //               keys/values are added to the request (auto-injects
+      //               Content-Type: application/json when body is an object)
+      //   into      - signal to receive the response value
+      //   as        - parse mode: json (default), text, or response (raw)
+      //   loading   - signal toggled true while in-flight
+      //   error     - signal set to an error message when the request fails
+      //
+      // The op is fire-and-forget: operations after <fetch> in the same
+      // block run synchronously, before the response resolves.
       if (op.localName === 'fetch') {
         const url = language.evaluate(
           op.getAttribute('url') ?? "''",
@@ -157,6 +202,7 @@ export function controllerFeature(language) {
         );
         const into = op.getAttribute('into');
         const as = (op.getAttribute('as') || 'json').toLowerCase();
+        const method = (op.getAttribute('method') || 'GET').toUpperCase();
         const loadingSig = op.getAttribute('loading');
         const errorSig = op.getAttribute('error');
         const setSig = (name, value) => {
@@ -164,11 +210,39 @@ export function controllerFeature(language) {
           const sig = instance.scope.signal(name);
           if (sig) sig.value = value;
         };
+
+        const init = { method };
+        const headersAttr = op.getAttribute('headers');
+        const headers = headersAttr
+          ? language.evaluate(headersAttr, instance, local, {}, event)
+          : {};
+        if (op.hasAttribute('body')) {
+          const raw = language.evaluate(op.getAttribute('body'), instance, local, null, event);
+          if (raw == null) {
+            // null body -> send nothing
+          } else if (
+            typeof raw === 'string' ||
+            raw instanceof FormData ||
+            raw instanceof Blob ||
+            raw instanceof ArrayBuffer ||
+            (typeof URLSearchParams !== 'undefined' && raw instanceof URLSearchParams)
+          ) {
+            init.body = raw;
+          } else {
+            init.body = JSON.stringify(raw);
+            if (!('content-type' in lowerKeyed(headers))) {
+              headers['Content-Type'] = 'application/json';
+            }
+          }
+        }
+        if (Object.keys(headers).length) init.headers = headers;
+
         setSig(loadingSig, true);
         setSig(errorSig, '');
-        fetch(url)
+        fetch(url, init)
           .then(response => {
             if (!response.ok) throw new Error(`HTTP ${response.status}`);
+            if (as === 'response') return response;
             return as === 'text' ? response.text() : response.json();
           })
           .then(data => setSig(into, data))
@@ -176,6 +250,35 @@ export function controllerFeature(language) {
           .finally(() => setSig(loadingSig, false));
         continue;
       }
+
+      // <emit name="my-event" detail="expr" bubbles="true|false"
+      //       composed="true|false" /> - dispatch a CustomEvent on the
+      // component host element. Parents listen with on:my-event="..."
+      // and read $event.detail in the handler. This is the standard
+      // child-to-parent signaling pattern for Custom Elements.
+      if (op.localName === 'emit') {
+        const name = op.getAttribute('name');
+        if (!name) continue;
+        const detail = op.hasAttribute('detail')
+          ? language.evaluate(op.getAttribute('detail'), instance, local, null, event)
+          : null;
+        const bubbles = op.getAttribute('bubbles') !== 'false';
+        const composed = op.getAttribute('composed') === 'true';
+        try {
+          instance.dispatchEvent(new CustomEvent(name, { detail, bubbles, composed }));
+        } catch (error) {
+          console.warn('[galath] <emit> failed:', name, error);
+        }
+        continue;
+      }
     }
   };
+
+  // Helper for case-insensitive header lookup. The fetch op auto-injects
+  // Content-Type only when the user has not already provided one.
+  function lowerKeyed(obj) {
+    const out = {};
+    for (const k of Object.keys(obj || {})) out[String(k).toLowerCase()] = obj[k];
+    return out;
+  }
 }

package/src/morph.js

@@ -70,17 +70,45 @@ function isCustomElement(el) {
 // 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.
+//
+// CLASS MERGING
+// Galath stamps `data-xes-classes` on every element whose classes it manages.
+// When that attribute is present on either side, we do a surgical merge instead
+// of a full class replace:
+//   - classes galath owned before but no longer wants → removed
+//   - classes galath now wants → added
+//   - all other classes (added by external JS like bogan-css) → untouched
+//
+// This eliminates the "is-active flicker" where bogan-css adds a class and
+// galath's next morph wipes it out.
 // -----------------------------------------------------------------------------
 function syncAttributes(fromEl, toEl) {
   const isFocusedInput =
     fromEl === document.activeElement && FORM_TAGS.has(fromEl.tagName);
 
+  // Read the galath-owned class sets from both sides up front so we can
+  // apply smart merging whenever `class` is touched below.
+  const newGalathClasses = new Set(
+    (toEl.getAttribute('data-xes-classes') ?? '').split(/\s+/).filter(Boolean),
+  );
+  const oldGalathClasses = new Set(
+    (fromEl.getAttribute('data-xes-classes') ?? '').split(/\s+/).filter(Boolean),
+  );
+  const hasClassTracking =
+    toEl.hasAttribute('data-xes-classes') || fromEl.hasAttribute('data-xes-classes');
+
   // 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 (attr.name === 'class' && hasClassTracking) {
+      mergeClasses(fromEl, oldGalathClasses, newGalathClasses);
+      continue;
+    }
+
     if (fromEl.getAttribute(attr.name) !== attr.value) {
       fromEl.setAttribute(attr.name, attr.value);
     }
@@ -91,6 +119,13 @@ function syncAttributes(fromEl, toEl) {
   for (const attr of [...fromEl.attributes]) {
     if (!toEl.hasAttribute(attr.name)) {
       if (isFocusedInput && (attr.name === 'value' || attr.name === 'checked')) continue;
+
+      if (attr.name === 'class' && hasClassTracking) {
+        // Galath dropped all its classes this render; preserve external ones.
+        mergeClasses(fromEl, oldGalathClasses, newGalathClasses);
+        continue;
+      }
+
       fromEl.removeAttribute(attr.name);
     }
   }
@@ -108,6 +143,23 @@ function syncAttributes(fromEl, toEl) {
   }
 }
 
+// Surgically update `fromEl`'s class list:
+//   remove classes galath no longer owns, add classes it now owns,
+//   leave everything else (external JS additions) untouched.
+function mergeClasses(fromEl, oldGalathClasses, newGalathClasses) {
+  const live = new Set(fromEl.className.split(/\s+/).filter(Boolean));
+  for (const cls of oldGalathClasses) {
+    if (!newGalathClasses.has(cls)) live.delete(cls);
+  }
+  for (const cls of newGalathClasses) live.add(cls);
+  if (live.size === 0) {
+    if (fromEl.hasAttribute('class')) fromEl.removeAttribute('class');
+    return;
+  }
+  const merged = [...live].join(' ');
+  if (fromEl.className !== merged) fromEl.className = merged;
+}
+
 // -----------------------------------------------------------------------------
 // Children sync
 // -----------------------------------------------------------------------------

package/src/rendering.js

@@ -59,6 +59,19 @@ export function renderingFeature(language) {
     'meta', 'source', 'track', 'wbr',
   ]);
 
+  // HTML boolean attributes: their presence means true, absence means false.
+  // When authored as `attr="{expr}"`, galath evaluates the expression and
+  // emits the attribute name only when truthy — never emits `attr="false"`.
+  // This covers every standard HTML boolean attr so authors never have to
+  // write `novalidate="novalidate"` or `selected="selected"` for dynamic cases.
+  const htmlBooleanAttrs = new Set([
+    'allowfullscreen', 'async', 'autofocus', 'autoplay', 'checked',
+    'controls', 'default', 'defer', 'disabled', 'formnovalidate',
+    'hidden', 'ismap', 'loop', 'multiple', 'muted', 'nomodule',
+    'novalidate', 'open', 'readonly', 'required', 'reversed',
+    'selected', 'typemustmatch',
+  ]);
+
   // Tags that the renderer should *display* as their serialized XML rather
   // than recurse into. They are "control plane" tags - if you accidentally
   // write `<commandset>` inside `<view>`, you get a code box, not silent
@@ -118,7 +131,7 @@ export function renderingFeature(language) {
     const items = instance.tree?.select(ref, local) ?? [];
     return items
       .map((item, index) => {
-        const childLocal = { ...local, [as]: item, [`$${as}`]: item, index };
+        const childLocal = makeIterationLocal(local, as, item, index, items.length);
         const html = language.renderChildren(
           [...node.childNodes],
           instance,
@@ -150,7 +163,7 @@ export function renderingFeature(language) {
     const items = instance.tree?.select(node.getAttribute('source'), local) ?? [];
     return items
       .map((item, index) => {
-        const childLocal = { ...local, [as]: item, [`$${as}`]: item, index };
+        const childLocal = makeIterationLocal(local, as, item, index, items.length);
         const html = language.renderChildren(
           [...template.childNodes],
           instance,
@@ -164,6 +177,35 @@ export function renderingFeature(language) {
       .join('');
   }
 
+  // Build the per-iteration local scope for <repeat>/<items>:
+  //
+  //   $name / name  -> the loop item (XNode)
+  //   index, $index -> zero-based offset
+  //   first, $first -> true on the first iteration
+  //   last,  $last  -> true on the final iteration
+  //   count, $count -> total number of items in this iteration
+  //
+  // Both `$x` and `x` spellings work; pick whichever reads better in
+  // your expression. The `$`-prefixed form mirrors how path expressions
+  // refer to locals (`$todo/@text`) so authors can be consistent.
+  function makeIterationLocal(local, as, item, index, count) {
+    const first = index === 0;
+    const last = index === count - 1;
+    return {
+      ...local,
+      [as]: item,
+      [`$${as}`]: item,
+      index,
+      $index: index,
+      first,
+      $first: first,
+      last,
+      $last: last,
+      count,
+      $count: count,
+    };
+  }
+
   // Stamp `data-xes-key="..."` onto the first element opening tag in `html`.
   // Leaves leading whitespace and any leading text alone. This is purely a
   // string rewrite because the rendering pipeline emits HTML strings.
@@ -289,7 +331,12 @@ export function renderingFeature(language) {
     // appear in any order. We accumulate every class fragment here and
     // emit a single `class="..."` at the end so we never produce two
     // class attributes (which would be invalid HTML).
+    // `hasClassDirectives` stays true even when all class: expressions are
+    // currently false, so `data-xes-classes` is always emitted on elements
+    // that declare class management — morph needs it to know the element is
+    // tracked and should preserve external classes across every render pass.
     const classParts = [];
+    let hasClassDirectives = false;
 
     for (const attr of [...node.attributes]) {
       const name = attr.name;
@@ -337,6 +384,7 @@ export function renderingFeature(language) {
 
       // -- class:foo="expr" -----------------------------------------------
       if (name.startsWith('class:')) {
+        hasClassDirectives = true;
         if (language.evaluate(value, instance, local)) classParts.push(name.slice(6));
         continue;
       }
@@ -349,14 +397,17 @@ export function renderingFeature(language) {
         continue;
       }
 
-      // -- disabled="{expr}" ----------------------------------------------
-      if (name === 'disabled' && value.startsWith('{') && value.endsWith('}')) {
-        if (language.evaluate(value.slice(1, -1), instance, local)) attrs.push('disabled');
+      // -- HTML boolean attributes: attr="{expr}" -------------------------
+      // Works for disabled, selected, required, readonly, novalidate, etc.
+      // Emit only the attribute name when truthy; emit nothing when falsy.
+      if (htmlBooleanAttrs.has(name) && value.startsWith('{') && value.endsWith('}')) {
+        if (language.evaluate(value.slice(1, -1), instance, local)) attrs.push(name);
         continue;
       }
 
       // -- class="..." (interpolated; merged with class:* below) ----------
       if (name === 'class') {
+        hasClassDirectives = true;
         classParts.unshift(language.interpolate(value, instance, local));
         continue;
       }
@@ -366,9 +417,16 @@ export function renderingFeature(language) {
     }
 
     // Single class attribute, regardless of source ordering.
-    if (classParts.length) {
+    // `data-xes-classes` records exactly which classes galath owns on this
+    // element so morph can merge rather than replace — preserving any classes
+    // that external JS (e.g. bogan-css components.js) has added at runtime.
+    // It is emitted whenever ANY class directive was declared, even when all
+    // class: expressions are currently false and the merged value is empty.
+    // Without it, morph loses the tracking marker and reverts to naive replace.
+    if (hasClassDirectives) {
       const merged = classParts.filter(Boolean).join(' ').trim();
       if (merged) attrs.push(`class="${merged}"`);
+      attrs.push(`data-xes-classes="${merged}"`);
     }
 
     bindings.push(binding);
@@ -474,6 +532,19 @@ export function renderingFeature(language) {
         instance.renderScope.collect(() =>
           element.removeEventListener(eventName, handler),
         );
+
+        // Seed the initial property value. Morph sets properties only on
+        // *existing* elements; nodes appended on first render arrive via
+        // cloneNode and need an explicit property push here. Skip focused
+        // inputs so we don't clobber text the user is actively typing.
+        if (element !== document.activeElement) {
+          const init = readBindingValue(bind.target, instance, binding.local);
+          if (bind.property === 'checked') {
+            element.checked = Boolean(init);
+          } else if (bind.property in element) {
+            element[bind.property] = init ?? '';
+          }
+        }
       }
 
       // use:* attached behaviors.

package/src/xml-events.js

@@ -32,14 +32,41 @@
 export function xmlEventsFeature(language) {
   language.setupListeners = instance => {
     const listeners = language.firstChildElement(instance.definition, 'listeners');
-    if (!listeners || !instance.tree) return;
+    if (!listeners) return;
     for (const listener of language.childElements(listeners, 'listener')) {
+      const handler = listener.getAttribute('handler');
+
+      // Signal-change listener: fires when the named signal's value changes.
+      // Syntax: <listener signal="theme" handler="#onThemeChange" />
+      //         <listener signal="pinned"><store signal="pinned" key="app:pinned"/></listener>
+      // `$value` is available in inline operations and as a local in the action.
+      if (listener.hasAttribute('signal')) {
+        const signalName = listener.getAttribute('signal');
+        const sig = instance.scope.signal(signalName);
+        if (!sig) {
+          console.warn(`[galath] <listener signal="${signalName}"> — no such signal`);
+          continue;
+        }
+        instance.scope.collect(
+          sig.subscribe(value => {
+            const local = { $value: value, value };
+            if (handler?.startsWith('#')) {
+              language.executeAction(instance, handler.slice(1), local, null);
+            } else {
+              language.runOperations([...listener.children], instance, local, null);
+            }
+          }, false), // false = don't fire immediately on subscribe
+        );
+        continue;
+      }
+
+      // Data-tree event listener (original behaviour).
+      // Requires an instance tree; skip silently when the component has none.
+      if (!instance.tree) continue;
       const eventName = listener.getAttribute('event') || '*';
       const observer = listener.getAttribute('observer');
-      const handler = listener.getAttribute('handler');
       instance.scope.collect(
         instance.tree.on(eventName, event => {
-          // Path filter: only fire when the event is at or under `observer`.
           if (observer && !event.path.startsWith(observer)) return;
           if (handler?.startsWith('#')) {
             language.executeAction(instance, handler.slice(1), {}, event);