galath 1.0.2

package/packages/galath/src/binding.js

@@ -0,0 +1,247 @@
+// =============================================================================
+// binding.js
+//
+// Expression evaluation, value resolution, and HTML escaping for templates.
+//
+// Galath expressions appear in three places:
+//
+//   1. Attribute interpolation:  class="card {active ? 'on' : ''}"
+//   2. Bind shorthand:           bind:value="/draft/@text"
+//   3. Inline event code:        on:click="set('x', 1)"
+//
+// All three flow through `evaluate(expr, instance, local, fallback, event)`,
+// which:
+//
+//   * Tries a *path* shortcut first (`/foo/@bar`, `$todo`, `signalName`).
+//     Plain identifiers and paths skip JS entirely - that's both faster and
+//     safer (no eval needed for the 90% case).
+//
+//   * Falls back to `Function('ctx', 'with(ctx) { return (expr); }')` so
+//     real expressions like `count > 0 && !disabled` still work. The `with`
+//     block puts every signal value, every helper (`select`, `valueOf`,
+//     `set`, `uid`, `deleteNode`...), and every loop-local (`$todo`,
+//     `index`) in scope. We *do* run user code via Function() - this is the
+//     same threat surface as putting code in `<eval>`. Galath sources are
+//     authored, not user-supplied; treat them like any other web page code.
+//
+//   * Catches exceptions and returns a fallback so a single broken
+//     attribute doesn't blank out the whole view. The renderer logs the
+//     failure to the console.
+//
+// `interpolate(text)` runs `{...}` placeholders through `evaluate` and HTML-
+// escapes the result by default - this is *crucial* for safety. A signal
+// containing user-supplied text must never be injected as raw markup.
+// =============================================================================
+
+import { assert } from './core.js';
+
+export function bindingFeature(language) {
+  /**
+   * Standard HTML escape. Used for any value that goes into the rendered
+   * HTML string before the browser parses it.
+   */
+  function escapeHtml(value) {
+    return String(value ?? '')
+      .replaceAll('&', '&amp;')
+      .replaceAll('<', '&lt;')
+      .replaceAll('>', '&gt;')
+      .replaceAll('"', '&quot;')
+      .replaceAll("'", '&#039;');
+  }
+
+  /**
+   * Build the context object passed to evaluated expressions. This is the
+   * runtime "global" of Galath expressions:
+   *
+   *   * Every signal name is a property holding its current value.
+   *   * Every loop variable from `<repeat as="x">` (and its `$x` form).
+   *   * `$event` - the originating DOM event (for on:* handlers).
+   *   * Helper functions: `uid`, `select`, `valueOf`, `set`, `attr`,
+   *     `deleteNode`, `setNode`.
+   *
+   * Helpers are intentionally minimal. Anything more advanced should live
+   * in a `<controller>` action where it's reviewable and reusable.
+   *
+   * The context is a Proxy so that signal reads are *recorded* on
+   * `instance.readSignals` (when set). The renderer uses that record to
+   * subscribe only to signals that the last render actually consulted -
+   * unrelated signal changes no longer schedule a render. Helpers and
+   * locals fall through to the underlying object; unrecognized names
+   * fall through to the outer scope (via `with`'s standard chain) so
+   * globals like `Number`, `Math`, etc. still resolve.
+   */
+  function buildContext(instance, local = {}, event = null) {
+    const base = {
+      ...local,
+      $event: event,
+      uid: language.uid,
+      select: path => instance.tree?.select(path, local) ?? [],
+      valueOf: path => valueOf(path, instance, local),
+      set: (name, value) => {
+        const sig = instance.scope.signal(name);
+        if (sig) sig.value = value;
+      },
+      attr: (node, name) => node?.get?.(name) ?? '',
+      deleteNode: node => node?.remove(),
+      setNode: (node, name, value) => node?.set?.(name, value),
+      // Climb to the nearest enclosing component instance and read one of
+      // its signals. Returns '' when no parent is found - keeps
+      // expressions safe even if the component is mounted standalone.
+      parentSignal: name => language.parentSignal?.(instance, name) ?? '',
+      // XForms-style validation helpers. They read the `<bind>` declarations
+      // collected during setupModel and evaluate them against the live
+      // instance value. `valid('/path')` returns true when every applicable
+      // bind passes; `invalid` is its inverse. `required('/path')` reports
+      // whether the path was declared required. `validity('/path')` returns
+      // a summary object so views can show targeted error messages.
+      valid: path => language.checkValidity?.(instance, path, local).valid ?? true,
+      invalid: path => !(language.checkValidity?.(instance, path, local).valid ?? true),
+      required: path => language.checkValidity?.(instance, path, local).required ?? false,
+      validity: path => language.checkValidity?.(instance, path, local) ?? { valid: true },
+    };
+    return new Proxy(base, {
+      get(target, key) {
+        if (key in target) return target[key];
+        const sig = instance.scope?.signal?.(key);
+        if (sig) {
+          instance.readSignals?.add(key);
+          return sig.value;
+        }
+        return undefined;
+      },
+      has(target, key) {
+        if (key in target) return true;
+        return Boolean(instance.scope?.signal?.(key));
+      },
+    });
+  }
+
+  /**
+   * Return the value at `path` from the instance tree, falling back to a
+   * named signal if the tree has no match.
+   */
+  function valueOf(path, instance, local = {}) {
+    if (instance.tree) {
+      const treeValue = instance.tree.valueOf(path, local);
+      if (treeValue !== '') return treeValue;
+    }
+    const sig = instance.scope?.signal?.(path);
+    if (sig) {
+      instance.readSignals?.add(path);
+      return sig.value;
+    }
+    return '';
+  }
+
+  /**
+   * The hot path. Evaluate `expr` against the instance + local context.
+   *
+   * Returns `fallback` if evaluation throws (and logs to the console). We
+   * pick the cheap path - signal name or path lookup - first. Only when
+   * neither matches do we compile a Function.
+   */
+  function evaluate(expr, instance, local = {}, fallback = '', event = null) {
+    const direct = simplePathValue(expr, instance, local);
+    if (direct.found) return direct.value;
+    try {
+      // eslint-disable-next-line no-new-func
+      return Function(
+        'ctx',
+        `with (ctx) { return (${expr}); }`,
+      )(buildContext(instance, local, event));
+    } catch (error) {
+      console.warn('[galath] expression failed:', expr, error);
+      return fallback;
+    }
+  }
+
+  /**
+   * Run `code` for side effects (no return value). Used by `on:click` and
+   * `<eval>` operations.
+   */
+  function run(code, instance, local = {}, event = null) {
+    try {
+      // eslint-disable-next-line no-new-func
+      return Function(
+        'ctx',
+        `with (ctx) { ${code}; }`,
+      )(buildContext(instance, local, event));
+    } catch (error) {
+      console.error('[galath] handler failed:', code, error);
+    }
+  }
+
+  /**
+   * Cheap shortcut for "the expression is just a name or a path". Avoids
+   * compiling a Function for the most common case.
+   *
+   * IMPORTANT: only return a path-style match when the expression has no
+   * JS operators / whitespace. Otherwise something like
+   *   $book/@done ? 'on' : 'off'
+   * would short-circuit on the leading `$`, return the boolean, and drop
+   * the ternary.
+   */
+  function simplePathValue(expr, instance, local) {
+    expr = String(expr ?? '').trim();
+    const sig = instance.scope?.signal?.(expr);
+    if (sig) {
+      instance.readSignals?.add(expr);
+      return { found: true, value: sig.value };
+    }
+    if (
+      (expr.startsWith('/') || expr.startsWith('$')) &&
+      !JS_EXPRESSION_HINT.test(expr)
+    ) {
+      return { found: true, value: instance.tree?.valueOf(expr, local) ?? '' };
+    }
+    return { found: false, value: undefined };
+  }
+
+  // Any of these characters mean the expression isn't a bare path - it's
+  // JS we need to compile. We do NOT include parens because `text()`
+  // selectors use them and the JS evaluator can't parse `/foo/text()`
+  // (it parses as `/regex/ / text()`). We do NOT include `*` because it
+  // appears in wildcard path steps. If you write `$a + $b`, the `+`
+  // catches it. Dot is included so `$event.currentTarget...` remains normal
+  // JavaScript property access instead of being mistaken for an XML path.
+  const JS_EXPRESSION_HINT = /[\s.?<>&|,;!{}]/;
+
+  /**
+   * Replace `{expr}` placeholders inside a template string. By default the
+   * result is HTML-escaped. Pass `{ raw: true }` to skip escaping (for
+   * places like component attributes whose value is parsed again later).
+   */
+  function interpolate(text, instance, local = {}, options = {}) {
+    const rendered = String(text ?? '').replace(/\{([^}]+)\}/g, (_, expression) =>
+      String(evaluate(expression.trim(), instance, local)),
+    );
+    return options.raw ? rendered : escapeHtml(rendered);
+  }
+
+  // Publish helpers.
+  language.escapeHtml = escapeHtml;
+  language.evaluate = evaluate;
+  language.run = run;
+  language.valueOf = valueOf;
+  language.interpolate = interpolate;
+  language.buildContext = buildContext;
+
+  // ---------------------------------------------------------------------------
+  // Self-tests
+  // ---------------------------------------------------------------------------
+  language.test('binding: interpolation escapes embedded markup', () => {
+    const fake = { scope: new language.Concern('test'), tree: null };
+    fake.scope.signal('snippet', new language.Signal('<x-unsafe></x-unsafe>'));
+    const r = interpolate('{snippet}', fake);
+    assert(r.includes('&lt;x-unsafe&gt;'), 'snippet was not escaped');
+  });
+
+  language.test('binding: dotted event expressions evaluate as JavaScript', () => {
+    const fake = { scope: new language.Concern('test'), tree: null };
+    const event = { currentTarget: { dataset: { chapterId: 'signals' } } };
+    assert(
+      evaluate('$event.currentTarget.dataset.chapterId', fake, {}, '', event) === 'signals',
+      'dotted $event expression was treated as a data path',
+    );
+  });
+}

package/packages/galath/src/boot.js

@@ -0,0 +1,52 @@
+// =============================================================================
+// boot.js
+//
+// `boot({ source, mount })` - the one-call setup. Creates a language, plugs
+// every standard feature in the right order, and starts it. Returns the
+// language object so callers can poke at internals (instance trees,
+// signals, etc.) for debugging / testing.
+//
+// Order of features matters: core must come first (others depend on
+// `language.parseSource`); rendering must come last (it uses helpers added
+// by every other feature). The order encoded here is the canonical one.
+// =============================================================================
+
+import { createLanguage, coreFeature } from './core.js';
+import { signalsAndScopesFeature } from './signals.js';
+import { instanceModelFeature } from './instance-model.js';
+import { bindingFeature } from './binding.js';
+import { commandFeature } from './command.js';
+import { controllerFeature } from './controller.js';
+import { templateItemsFeature } from './templates.js';
+import { behaviorFeature } from './behavior.js';
+import { xmlEventsFeature } from './xml-events.js';
+import { importFeature } from './imports.js';
+import { componentFeature } from './component.js';
+import { renderingFeature } from './rendering.js';
+
+/**
+ * Build a fully-loaded Galath language and `start()` it.
+ *
+ * @param {object} options
+ * @param {string} options.source  - The Galath XML source.
+ * @param {Element} options.mount  - Mount point for `<application>`.
+ * @returns {Promise<object>} the started language.
+ */
+export async function boot({ source, mount }) {
+  const language = createLanguage({ source, mount })
+    .use(coreFeature)
+    .use(signalsAndScopesFeature)
+    .use(instanceModelFeature)
+    .use(bindingFeature)
+    .use(commandFeature)
+    .use(controllerFeature)
+    .use(templateItemsFeature)
+    .use(behaviorFeature)
+    .use(xmlEventsFeature)
+    .use(importFeature)
+    .use(componentFeature)
+    .use(renderingFeature);
+
+  await language.start();
+  return language;
+}

package/packages/galath/src/command.js

@@ -0,0 +1,117 @@
+// =============================================================================
+// command.js
+//
+// XUL-style commandsets. A `<commandset>` block declares named commands
+// with optional `enabled="..."` predicates. Buttons / menu items reference
+// them with `command="addTodo"` and the runtime wires up:
+//
+//   * Click -> execute the command operations.
+//   * Enabled state -> the button is `disabled` whenever the predicate is
+//     falsey, automatically re-evaluated as part of the render pass.
+//
+// Operations live as the children of `<command>` and are interpreted by
+// `controller.runOperations` (see controller.js). This file only registers
+// commands and exposes execute/enabled helpers.
+// =============================================================================
+
+export function commandFeature(language) {
+  /**
+   * Scan a component definition for its `<commandset>` and index commands
+   * by name. Called once during component connect.
+   *
+   * Commands declaring a `shortcut="ctrl+s"` (etc) get a global keydown
+   * listener installed against the host element. Shortcut grammar is
+   * intentionally tiny: zero or more modifiers from {ctrl, alt, shift,
+   * meta} plus a single key, joined by `+`. Matching is
+   * case-insensitive on the key.
+   */
+  language.setupCommands = instance => {
+    instance.commands = new Map();
+    const commandset = language.firstChildElement(instance.definition, 'commandset');
+    if (!commandset) return;
+    for (const command of language.childElements(commandset, 'command')) {
+      instance.commands.set(command.getAttribute('name'), command);
+    }
+    installCommandShortcuts(instance);
+  };
+
+  /**
+   * Wire up `shortcut="ctrl+s"` keybindings. The listener lives on
+   * `document` so the shortcut works no matter where focus is. We only
+   * install one listener per instance; it dispatches to the correct
+   * command by walking the indexed map. Listener is collected on
+   * instance.scope so it's removed at unmount.
+   */
+  function installCommandShortcuts(instance) {
+    const entries = [];
+    for (const [name, command] of instance.commands) {
+      const shortcut = command.getAttribute('shortcut');
+      if (shortcut) entries.push({ name, combo: parseShortcut(shortcut) });
+    }
+    if (entries.length === 0) return;
+
+    const handler = event => {
+      // Don't poach typing in editable controls unless the shortcut is
+      // explicitly modifier-bearing (Ctrl/Cmd/Alt). Plain alphanumeric
+      // shortcuts would be hostile in an <input>.
+      const target = event.target;
+      const editable =
+        target?.isContentEditable ||
+        target?.matches?.('input, textarea, select');
+      for (const entry of entries) {
+        if (!matches(entry.combo, event)) continue;
+        if (editable && !(entry.combo.ctrl || entry.combo.meta || entry.combo.alt)) continue;
+        event.preventDefault();
+        language.executeCommand(instance, entry.name, {}, event);
+        return;
+      }
+    };
+    document.addEventListener('keydown', handler);
+    instance.scope.collect(() =>
+      document.removeEventListener('keydown', handler),
+    );
+  }
+
+  function parseShortcut(spec) {
+    const parts = String(spec).toLowerCase().split('+').map(s => s.trim()).filter(Boolean);
+    const combo = { ctrl: false, alt: false, shift: false, meta: false, key: '' };
+    for (const part of parts) {
+      if (part === 'ctrl' || part === 'control') combo.ctrl = true;
+      else if (part === 'alt' || part === 'option') combo.alt = true;
+      else if (part === 'shift') combo.shift = true;
+      else if (part === 'meta' || part === 'cmd' || part === 'command') combo.meta = true;
+      else combo.key = part;
+    }
+    return combo;
+  }
+
+  function matches(combo, event) {
+    if (Boolean(event.ctrlKey) !== combo.ctrl) return false;
+    if (Boolean(event.altKey) !== combo.alt) return false;
+    if (Boolean(event.shiftKey) !== combo.shift) return false;
+    if (Boolean(event.metaKey) !== combo.meta) return false;
+    return String(event.key || '').toLowerCase() === combo.key;
+  }
+
+  /**
+   * `true` if the command has no `enabled` attribute, otherwise the value
+   * of evaluating that expression against the current scope.
+   */
+  language.commandEnabled = (instance, name, local = {}) => {
+    const command = instance.commands?.get(name);
+    if (!command) return false;
+    const expression = command.getAttribute('enabled');
+    return expression ? Boolean(language.evaluate(expression, instance, local)) : true;
+  };
+
+  /**
+   * Execute the command. Silently no-ops when the command is missing OR
+   * disabled (so a user double-click on a disabled button can't sneak
+   * through a stale handler).
+   */
+  language.executeCommand = (instance, name, local = {}, event = null) => {
+    const command = instance.commands?.get(name);
+    if (!command || !language.commandEnabled(instance, name, local)) return;
+    language.runOperations([...command.children], instance, local, event);
+  };
+}