galath 1.0.2

package/packages/galath/src/core.js

@@ -0,0 +1,190 @@
+// =============================================================================
+// core.js
+//
+// Defines the language *kernel*: a tiny dependency-injection container that
+// "features" plug into. Each feature attaches its own functions and classes
+// onto the language object. We pick the order at boot time, so a downstream
+// project can swap, omit, or extend features without forking the runtime.
+//
+// This file deliberately stays small. It is the only thing that knows
+// nothing about XML, signals, components, or DOM. Everything else is a
+// feature plugged in via `.use(...)`.
+//
+// Public exports:
+//
+//   createLanguage({ source, mount })  - Construct an empty language.
+//   coreFeature(language)              - Wires up XML parsing + small helpers.
+//
+// =============================================================================
+
+/**
+ * Create a brand-new Galath language container.
+ *
+ * Because each call returns a fresh object (no shared state), you can run
+ * multiple Galath apps on the same page if you want.
+ *
+ * @param {object} options
+ * @param {string} options.source  - The Galath XML source as a string.
+ * @param {Element} options.mount  - DOM element to mount the <application> into.
+ * @returns {object} the language object.
+ */
+export function createLanguage({ source, mount }) {
+  return {
+    // Raw inputs - features may rewrite `source` (e.g. when imports inline
+    // additional XML) before it is finally parsed.
+    source,
+    mount,
+    // Resolved DOM document and root after `parseSource()` runs.
+    document: null,
+    root: null,
+    // Names of applied features, useful for debugging / introspection.
+    features: [],
+    // Custom components keyed by their tag name (e.g. "xes-feature-badge").
+    components: new Map(),
+    // Behaviors keyed by short name (e.g. "copy", "drag", "drop").
+    behaviors: new Map(),
+    // Tests collected during feature install. Run on `start()` for sanity.
+    tests: [],
+
+    /**
+     * Apply a feature plugin.
+     *
+     * A feature is a function that receives the language object and adds
+     * methods/state onto it. We intentionally do not use classes here -
+     * mutation by feature keeps the surface area readable for new readers.
+     */
+    use(feature) {
+      this.features.push(feature.name || 'anonymousFeature');
+      feature(this);
+      return this;
+    },
+
+    /**
+     * Register a self-test. Tests are run during `start()` so a broken
+     * feature fails loudly rather than silently corrupting later runs.
+     */
+    test(name, fn) {
+      this.tests.push({ name, fn });
+    },
+
+    /**
+     * Execute all collected tests. Failed tests print to console.error but
+     * do NOT throw - rendering should still proceed so users can see any
+     * UI even when a self-test regressed.
+     */
+    runTests() {
+      const rows = [];
+      for (const t of this.tests) {
+        try {
+          t.fn();
+          rows.push({ test: t.name, ok: true });
+        } catch (error) {
+          rows.push({ test: t.name, ok: false });
+          console.error(`[galath test failed] ${t.name}`, error);
+        }
+      }
+      // console.table is a friendly summary in dev tools; no-op in stripped
+      // production builds.
+      if (typeof console.table === 'function') console.table(rows);
+    },
+
+    /**
+     * Run the language: parse, resolve imports, register components, run
+     * tests, mount the application. This is async because import resolution
+     * may fetch additional XML files over the network.
+     *
+     * Order matters:
+     *   1. parseSource     - the entry document becomes a DOM tree.
+     *   2. resolveImports  - <import src="..."> nodes are replaced by the
+     *                        children of the fetched documents (recursive,
+     *                        deduped by absolute URL).
+     *   3. registerComponents - now all <component> elements are present.
+     *   4. runTests / mountApplication - sanity + render.
+     */
+    async start() {
+      this.parseSource();
+      if (typeof this.resolveImports === 'function') await this.resolveImports();
+      this.registerComponents();
+      this.runTests();
+      this.mountApplication();
+      return this;
+    },
+  };
+}
+
+/**
+ * The CORE feature: XML parsing + tiny utilities every other feature needs.
+ *
+ * Other features can rely on:
+ *
+ *   - `language.parseSource()` populates `language.document` / `language.root`.
+ *   - `language.childElements(parent, name?)` returns element children.
+ *   - `language.firstChildElement(parent, name)` is a shortcut.
+ *   - `language.serialize(node)` emits XML text.
+ *   - `language.uid()` generates a short, monotonic-ish unique id.
+ */
+export function coreFeature(language) {
+  language.parseSource = () => {
+    // DOMParser is the platform's XML parser. It returns a Document with a
+    // <parsererror> element when input is malformed; we surface the error
+    // text so users see exactly what went wrong, with line/column info.
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(language.source, 'application/xml');
+    const err = doc.querySelector('parsererror');
+    if (err) throw new Error(err.textContent.trim());
+    language.document = doc;
+    language.root = doc.documentElement;
+  };
+
+  /**
+   * Like `parent.children` but optionally filtered by local or qualified tag
+   * name. This handles both `<gal:component>` lookups by local name and
+   * lifecycle hooks like `<on:mount>` that are addressed by qualified name.
+   */
+  language.childElements = (parent, name = null) =>
+    [...parent.children].filter(
+      el => !name || el.localName === name || el.nodeName === name,
+    );
+
+  /** Convenience: first child matching `name`, or null. */
+  language.firstChildElement = (parent, name) =>
+    language.childElements(parent, name)[0] ?? null;
+
+  /** Re-serialize a parsed XML node back to a string (for echo/debug views). */
+  language.serialize = node => new XMLSerializer().serializeToString(node);
+
+  /**
+   * Short, unique, mostly-monotonic id. Used as a default for newly inserted
+   * nodes so XPath predicates like `[@id=...]` work without manual ids.
+   */
+  language.uid = () =>
+    `n${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+
+  // -- self-tests -------------------------------------------------------------
+  language.test('core: source parses as well-formed XML', () => {
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(language.source, 'application/xml');
+    assert(!doc.querySelector('parsererror'), 'source is not well-formed XML');
+  });
+
+  language.test('core: childElements matches qualified namespaced tags', () => {
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(
+      '<root xmlns:on="urn:galath:on"><on:mount /></root>',
+      'application/xml',
+    );
+    assert(
+      language.childElements(doc.documentElement, 'on:mount').length === 1,
+      'qualified namespaced element was not matched',
+    );
+  });
+}
+
+/**
+ * Tiny assertion helper. Re-exported so feature tests don't have to ship
+ * their own. We don't import a test framework - keeping galath
+ * dependency-free is part of the design.
+ */
+export function assert(condition, message = 'assertion failed') {
+  if (!condition) throw new Error(message);
+}

package/packages/galath/src/imports.js

@@ -0,0 +1,132 @@
+// =============================================================================
+// imports.js
+//
+// `<import src="./foo.xml" />` - the XML modularity primitive.
+//
+// Why this matters:
+//   * One huge document is unreadable. We let authors split a Galath app
+//     across files the same way ES modules let you split a JS app.
+//   * Components live alongside their styles and their data, in their own
+//     files, in their own folders.
+//   * The playground depends on this: each tutorial chapter is a separate
+//     XML file imported into the shell.
+//
+// How it works:
+//
+//   1. Walk every `<import src="...">` in the document, top-down.
+//   2. Fetch the URL relative to either the importing document's URL (for
+//      nested imports) or `document.baseURI` (for the entry source).
+//   3. Parse the fetched XML.
+//   4. The fetched document's *root* may be either:
+//        - `<galath>` - a root with multiple children, all of which are
+//          spliced in at the import point;
+//        - or any single element, which is also spliced in.
+//   5. Replace the `<import>` element with those nodes.
+//   6. Recurse into the freshly inlined nodes (their imports are still to
+//      be resolved). Cycles are caught by URL: if a URL is already on the
+//      resolution stack, skip the re-import.
+//
+// The fetch is gated on a Map keyed by absolute URL. Repeated imports of
+// the same file (e.g. a shared header component) reuse the parsed source.
+//
+// Errors during fetch produce a clear console error AND inject a small
+// `<parseerror>` element so the page surfaces the failure visibly rather
+// than silently dropping content.
+// =============================================================================
+
+export function importFeature(language) {
+  // url -> Promise<DocumentFragment-like Element[]>. Cached so duplicate
+  // imports re-use one network round-trip.
+  const cache = new Map();
+
+  language.resolveImports = async () => {
+    if (!language.document) return;
+    // Track the resolution stack to break cycles. Keys are absolute URLs.
+    const stack = new Set();
+    await resolveContainer(language.document.documentElement, document.baseURI, stack);
+  };
+
+  /**
+   * Recursively resolve `<import>` elements that are direct or transitive
+   * children of `container`. We snapshot the list of imports first because
+   * we mutate the DOM as we go.
+   *
+   * `baseUrl` is the URL relative to which `<import src>` is resolved -
+   * typically the URL of the document `container` came from.
+   */
+  async function resolveContainer(container, baseUrl, stack) {
+    // Snapshot of all imports anywhere in the subtree, in document order.
+    // We process them sequentially so error handling is straightforward.
+    const imports = [...container.querySelectorAll('import[src]')];
+    for (const importEl of imports) {
+      // Skip imports nested inside CDATA/code samples - they live in text,
+      // not in real DOM nodes, so they wouldn't be caught here anyway.
+      // Skip imports that are themselves still in the document but were
+      // already replaced as part of resolving an outer import.
+      if (!importEl.isConnected || !importEl.parentNode) continue;
+      const src = importEl.getAttribute('src');
+      if (!src) continue;
+      const url = new URL(src, baseUrl).toString();
+
+      // Cycle? Replace with an empty marker so future passes ignore it.
+      if (stack.has(url)) {
+        console.warn(`[galath import] cycle detected, skipping ${url}`);
+        importEl.replaceWith(...[]);
+        continue;
+      }
+
+      try {
+        const nodes = await loadImport(url);
+        // Recurse into the fetched fragment first - so its own <import>s
+        // resolve against its URL, not ours.
+        for (const node of nodes) {
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            stack.add(url);
+            await resolveContainer(node, url, stack);
+            stack.delete(url);
+          }
+        }
+        // Splice the resolved nodes in place of the <import> element.
+        // We import them into the host document so namespaces are preserved.
+        const owner = importEl.ownerDocument;
+        const adopted = nodes.map(n => owner.importNode(n, true));
+        importEl.replaceWith(...adopted);
+      } catch (error) {
+        console.error(`[galath import] failed to load ${url}:`, error);
+        const errorEl = importEl.ownerDocument.createElement('parseerror');
+        errorEl.textContent = `Failed to import ${url}: ${error.message}`;
+        importEl.replaceWith(errorEl);
+      }
+    }
+  }
+
+  /**
+   * Fetch and parse an XML import. Returns the children of the fetched
+   * document's root element (or `[root]` when the root is not a wrapper
+   * like `<galath>` / `<fragment>`).
+   *
+   * Cached by URL.
+   */
+  function loadImport(url) {
+    if (cache.has(url)) return cache.get(url);
+    const promise = (async () => {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status} ${response.statusText}`);
+      }
+      const text = await response.text();
+      const doc = new DOMParser().parseFromString(text, 'application/xml');
+      const err = doc.querySelector('parsererror');
+      if (err) throw new Error(err.textContent.trim());
+      const root = doc.documentElement;
+      // Wrapper roots - their *children* are what we splice. Otherwise
+      // splice the root itself.
+      const wrapperNames = new Set(['galath', 'fragment', 'xes']);
+      return wrapperNames.has(root.localName)
+        ? [...root.children]
+        : [root];
+    })();
+    cache.set(url, promise);
+    return promise;
+  }
+}

package/packages/galath/src/index.js

@@ -0,0 +1,38 @@
+// =============================================================================
+// index.js
+//
+// Public surface of the Galath runtime.
+//
+// Two ways to use the library:
+//
+//   1. Compose your own:
+//
+//        import { createLanguage, coreFeature, ... } from 'galath';
+//        const lang = createLanguage({ source, mount })
+//          .use(coreFeature)
+//          .use(...other features...)
+//        await lang.start();
+//
+//   2. Boot with all features (the 99% case):
+//
+//        import { boot } from 'galath';
+//        await boot({ source, mount });
+//
+// Re-exporting individual features lets advanced users swap one out (e.g. a
+// custom rendering layer) without forking the package.
+// =============================================================================
+
+export { createLanguage, coreFeature, assert } from './core.js';
+export { signalsAndScopesFeature } from './signals.js';
+export { instanceModelFeature } from './instance-model.js';
+export { bindingFeature } from './binding.js';
+export { commandFeature } from './command.js';
+export { controllerFeature } from './controller.js';
+export { templateItemsFeature } from './templates.js';
+export { behaviorFeature } from './behavior.js';
+export { xmlEventsFeature } from './xml-events.js';
+export { importFeature } from './imports.js';
+export { componentFeature } from './component.js';
+export { renderingFeature } from './rendering.js';
+export { morph } from './morph.js';
+export { boot } from './boot.js';