galath 1.0.2

package/playground/chapters/02-signals.xml

@@ -0,0 +1,166 @@
+<!--
+  chapters/02-signals.xml
+
+  Signals are reactive cells. This chapter introduces them through three
+  worked examples:
+
+    1. A counter signal with two buttons.
+    2. A computed signal derived from another signal.
+    3. A `name` signal echoed in the heading via interpolation.
+-->
+<galath xmlns:bind="urn:galath:bind" xmlns:on="urn:galath:on" xmlns:use="urn:galath:use" xmlns:drag="urn:galath:drag" xmlns:drop="urn:galath:drop" xmlns:class="urn:galath:class">
+  <component name="chapter-signals" tag="x-chapter-signals">
+    <model>
+      <!-- Demo state. -->
+      <signal name="count"   value="0" />
+      <signal name="step"    value="1" />
+      <signal name="name"    value="World" />
+
+      <!--
+        A computed signal. Re-evaluated whenever `count` changes. Without
+        <computed>, you would write the same logic in every <text>
+        binding - the derived signal centralizes it once.
+      -->
+      <computed name="parity" from="count">
+        <expression>count % 2 === 0 ? 'even' : 'odd'</expression>
+      </computed>
+
+      <!--
+        Computed chain: a -> b -> c. Each computed declares its source
+        with `from=`; when `a` moves, `b` re-runs, which moves `c`. The
+        dependency direction is explicit, which keeps the data flow
+        easy to reason about (no implicit auto-tracking magic).
+      -->
+      <signal name="a" value="2" />
+      <computed name="b" from="a">
+        <expression>a * 10</expression>
+      </computed>
+      <computed name="c" from="b">
+        <expression>b + 1</expression>
+      </computed>
+
+      <signal name="snippet"><![CDATA[<component name="counter" tag="x-counter">
+  <model>
+    <signal name="count" value="0" />
+    <signal name="step"  value="1" />
+    <computed name="parity" from="count">
+      <expression>count % 2 === 0 ? 'even' : 'odd'</expression>
+    </computed>
+  </model>
+
+  <view>
+    <button on:click="set('count', count + step)">+</button>
+    <button on:click="set('count', count - step)">-</button>
+    <span>Count: {count} ({parity})</span>
+    <input type="number" bind:value="step" />
+  </view>
+</component>]]></signal>
+    </model>
+
+    <controller>
+      <action name="bump">
+        <set signal="count" value="count + step" />
+      </action>
+      <action name="bumpDown">
+        <set signal="count" value="count - step" />
+      </action>
+    </controller>
+
+    <view>
+      <div class="px-4 py-5">
+        <x-chapter-heading icon="bi-broadcast" title="Signals"
+          subtitle="The reactive cell. Every dynamic value in Galath is a signal." />
+
+        <div class="row g-4 mb-4">
+          <div class="col-lg-6">
+            <div class="card xes-card h-100">
+              <div class="card-body">
+                <h2 class="h5"><i class="bi bi-journal-text me-2 text-info"></i>How it works</h2>
+                <p class="text-secondary">
+                  A <strong>signal</strong> holds a value. Read it by name in any expression
+                  (<code>count + 1</code>); write it via <code>set('count', ...)</code> in a
+                  handler or with <code>&lt;set signal="count" value="..."/&gt;</code> in a
+                  controller action.
+                </p>
+                <p class="text-secondary">
+                  A <strong>computed</strong> signal is derived from another signal. It
+                  re-evaluates automatically when the source changes. Use it to centralize
+                  formulas you would otherwise repeat across the view.
+                </p>
+                <p class="text-secondary mb-0">
+                  When ANY signal in the component scope changes, the renderer schedules a
+                  microtask-batched re-render. You never call "update".
+                </p>
+              </div>
+            </div>
+          </div>
+          <div class="col-lg-6">
+            <div class="card xes-card h-100">
+              <div class="card-header bg-transparent d-flex justify-content-between align-items-center">
+                <strong><i class="bi bi-code-slash me-2"></i>Source</strong>
+                <div class="btn-group btn-group-sm" role="group"><button class="btn btn-outline-info" on:click="window.galathRunSnippet(snippet)" title="Open this snippet in a new tab"><i class="bi bi-play-fill me-1"></i>Run</button><button class="btn btn-outline-info" use:copy="snippet" title="Copy to clipboard"><i class="bi bi-clipboard me-1"></i>Copy</button></div>
+              </div>
+              <div class="card-body p-0">
+                <pre class="xes-code rounded p-3 mb-0"><code><text value="snippet" /></code></pre>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="card xes-card">
+          <div class="card-header bg-transparent">
+            <strong><i class="bi bi-play-circle me-2"></i>Live demo</strong>
+          </div>
+          <div class="card-body">
+            <div class="row g-3 align-items-end">
+              <div class="col-md-4">
+                <label class="form-label">Greet someone</label>
+                <input class="form-control" bind:value="name" />
+              </div>
+              <div class="col-md-4">
+                <label class="form-label">Step size</label>
+                <input class="form-control" type="number" bind:value="step" />
+              </div>
+              <div class="col-md-4 d-flex gap-2">
+                <button class="btn btn-info flex-grow-1" on:click="#bump">+</button>
+                <button class="btn btn-outline-light flex-grow-1" on:click="#bumpDown">-</button>
+              </div>
+            </div>
+
+            <hr class="my-4" />
+
+            <div class="d-flex flex-column gap-2">
+              <div class="display-6 mb-0">Hello, {name}.</div>
+              <div class="text-secondary">
+                Count: <span class="badge text-bg-info">{count}</span>
+                <span class="ms-2">parity: <span class="badge text-bg-secondary">{parity}</span></span>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="card xes-card mt-4">
+          <div class="card-header bg-transparent">
+            <strong><i class="bi bi-diagram-3 me-2"></i>Computed chain: a &#8594; b &#8594; c</strong>
+          </div>
+          <div class="card-body">
+            <p class="text-secondary">
+              Each derived signal declares its source with <code>from=</code>. When you change
+              <code>a</code>, <code>b = a * 10</code> updates, then <code>c = b + 1</code>
+              follows. Dependency tracking is <em>explicit</em>, not implicit - one less thing
+              to debug.
+            </p>
+            <div class="row g-3 align-items-end">
+              <div class="col-md-3">
+                <label class="form-label">a</label>
+                <input class="form-control" type="number" bind:value="a" />
+              </div>
+              <div class="col-md-3"><div class="text-secondary small">b = a * 10</div><div class="display-6">{b}</div></div>
+              <div class="col-md-3"><div class="text-secondary small">c = b + 1</div><div class="display-6">{c}</div></div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </view>
+  </component>
+</galath>

package/playground/chapters/03-instance.xml

@@ -0,0 +1,130 @@
+<!--
+  chapters/03-instance.xml
+
+  The instance tree: state shaped as XML you can navigate by path.
+
+  Demo: a simple "settings" instance with nested elements; we read and
+  write attribute values from the view and show the live tree as
+  serialized XML.
+-->
+<galath xmlns:bind="urn:galath:bind" xmlns:on="urn:galath:on" xmlns:use="urn:galath:use" xmlns:drag="urn:galath:drag" xmlns:drop="urn:galath:drop" xmlns:class="urn:galath:class">
+  <component name="chapter-instance" tag="x-chapter-instance">
+    <model>
+      <instance>
+        <user name="Ada" theme="dark">
+          <prefs>
+            <pref key="emails" value="weekly" />
+            <pref key="autosave" value="true" />
+          </prefs>
+        </user>
+      </instance>
+
+      <signal name="snippet"><![CDATA[<model>
+  <instance>
+    <user name="Ada" theme="dark">
+      <prefs>
+        <pref key="emails" value="weekly" />
+      </prefs>
+    </user>
+  </instance>
+</model>
+
+<input bind:value="/user/@name" />
+<select bind:value="/user/@theme">
+  <option value="dark">Dark</option>
+  <option value="light">Light</option>
+</select>
+
+<repeat ref="/user/prefs/pref" as="p">
+  <div>
+    <text value="$p/@key" />: <text value="$p/@value" />
+  </div>
+</repeat>]]></signal>
+    </model>
+
+    <view>
+      <div class="px-4 py-5">
+        <x-chapter-heading icon="bi-database" title="Instance Tree"
+          subtitle="Application state lives as XML. Bind to attributes by path." />
+
+        <div class="row g-4 mb-4">
+          <div class="col-lg-6">
+            <div class="card xes-card h-100">
+              <div class="card-body">
+                <h2 class="h5"><i class="bi bi-journal-text me-2 text-info"></i>How it works</h2>
+                <p class="text-secondary">
+                  The <code>&lt;instance&gt;</code> block defines initial state as XML. Every
+                  attribute becomes a reactive signal under the hood, so any change is observed
+                  by the renderer.
+                </p>
+                <p class="text-secondary">
+                  Paths look like a strict subset of XPath:
+                </p>
+                <ul class="text-secondary mb-0">
+                  <li><code>/user/@name</code> - root, child, attribute.</li>
+                  <li><code>/user/prefs/pref[@key=emails]/@value</code> - predicate selector.</li>
+                  <li><code>$p/@key</code> - path under a local variable bound by <code>&lt;repeat as="p"&gt;</code>.</li>
+                </ul>
+              </div>
+            </div>
+          </div>
+          <div class="col-lg-6">
+            <div class="card xes-card h-100">
+              <div class="card-header bg-transparent d-flex justify-content-between align-items-center">
+                <strong><i class="bi bi-code-slash me-2"></i>Source</strong>
+                <div class="btn-group btn-group-sm" role="group"><button class="btn btn-outline-info" on:click="window.galathRunSnippet(snippet)" title="Open this snippet in a new tab"><i class="bi bi-play-fill me-1"></i>Run</button><button class="btn btn-outline-info" use:copy="snippet" title="Copy to clipboard"><i class="bi bi-clipboard me-1"></i>Copy</button></div>
+              </div>
+              <div class="card-body p-0">
+                <pre class="xes-code rounded p-3 mb-0"><code><text value="snippet" /></code></pre>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="card xes-card">
+          <div class="card-header bg-transparent">
+            <strong><i class="bi bi-play-circle me-2"></i>Live demo</strong>
+          </div>
+          <div class="card-body">
+            <div class="row g-3">
+              <div class="col-md-4">
+                <label class="form-label">Name</label>
+                <input class="form-control" bind:value="/user/@name" />
+              </div>
+              <div class="col-md-4">
+                <label class="form-label">Theme</label>
+                <select class="form-select" bind:value="/user/@theme">
+                  <option value="dark">Dark</option>
+                  <option value="light">Light</option>
+                  <option value="contrast">High contrast</option>
+                </select>
+              </div>
+            </div>
+
+            <hr class="my-4" />
+
+            <h3 class="h6 text-uppercase text-secondary">Preferences</h3>
+            <div class="d-flex flex-column gap-2">
+              <repeat ref="/user/prefs/pref" as="p">
+                <div class="input-group">
+                  <span class="input-group-text" style="min-width: 7rem;">
+                    <text value="$p/@key" />
+                  </span>
+                  <input class="form-control" bind:value="$p/@value" />
+                </div>
+              </repeat>
+            </div>
+
+            <hr class="my-4" />
+
+            <div class="alert alert-info mb-0">
+              <i class="bi bi-info-circle me-1"></i>
+              Hello <strong>{valueOf('/user/@name')}</strong>! Your theme is <code>{valueOf('/user/@theme')}</code>.
+              Edit the inputs above and watch this line update without any explicit binding code.
+            </div>
+          </div>
+        </div>
+      </div>
+    </view>
+  </component>
+</galath>

package/playground/chapters/04-bindings.xml

@@ -0,0 +1,156 @@
+<!--
+  chapters/04-bindings.xml
+
+  Directives for connecting view elements to state and behavior:
+
+    bind:property="signal|path"   two-way value/checked/etc.
+    on:event="code | #action"     one-way event handler
+    class:name="expr"             toggle a class
+    {expr}                         attribute interpolation
+-->
+<galath xmlns:bind="urn:galath:bind" xmlns:on="urn:galath:on" xmlns:use="urn:galath:use" xmlns:drag="urn:galath:drag" xmlns:drop="urn:galath:drop" xmlns:class="urn:galath:class">
+  <component name="chapter-bindings" tag="x-chapter-bindings">
+    <model>
+      <signal name="email"      value="ada@example.com" />
+      <signal name="newsletter" value="true" />
+      <signal name="strength"   value="3" />
+      <signal name="role"       value="editor" />
+      <signal name="dueDate"    value="2026-06-01" />
+      <signal name="snippet"><![CDATA[<input bind:value="email" />
+<input type="checkbox" bind:checked="newsletter" />
+
+<button on:click="set('count', count + 1)">+</button>
+<button on:click="#submit">Submit</button>
+
+<div class:active="email.length > 0">
+  ...
+</div>
+
+<select bind:value="role">
+  <option value="viewer">Viewer</option>
+  <option value="editor">Editor</option>
+  <option value="admin">Admin</option>
+</select>
+
+<input type="date" bind:value="dueDate" />]]></signal>
+    </model>
+
+    <controller>
+      <action name="logSubmit">
+        <log value="'Submitted ' + email" />
+      </action>
+    </controller>
+
+    <view>
+      <div class="px-4 py-5">
+        <x-chapter-heading icon="bi-link-45deg" title="Bindings"
+          subtitle="Connect view elements to signals, paths, and event handlers." />
+
+        <div class="row g-4 mb-4">
+          <div class="col-lg-6">
+            <div class="card xes-card h-100">
+              <div class="card-body">
+                <h2 class="h5"><i class="bi bi-journal-text me-2 text-info"></i>How it works</h2>
+                <ul class="text-secondary mb-3">
+                  <li><code>bind:value</code>, <code>bind:checked</code> are two-way binds. Edits
+                    flow back into the underlying signal or instance attribute.</li>
+                  <li><code>on:click</code>, <code>on:input</code>, etc. attach event listeners.
+                    The value can be inline JS (with all signals in scope) or a controller
+                    reference like <code>#submit</code>.</li>
+                  <li><code>class:active="expr"</code> toggles a class when the expression is
+                    truthy.</li>
+                  <li><code>{expr}</code> inside an attribute or text node is interpolation. It is
+                    HTML-escaped automatically - safe by default.</li>
+                </ul>
+              </div>
+            </div>
+          </div>
+          <div class="col-lg-6">
+            <div class="card xes-card h-100">
+              <div class="card-header bg-transparent d-flex justify-content-between align-items-center">
+                <strong><i class="bi bi-code-slash me-2"></i>Source</strong>
+                <div class="btn-group btn-group-sm" role="group"><button class="btn btn-outline-info" on:click="window.galathRunSnippet(snippet)" title="Open this snippet in a new tab"><i class="bi bi-play-fill me-1"></i>Run</button><button class="btn btn-outline-info" use:copy="snippet" title="Copy to clipboard"><i class="bi bi-clipboard me-1"></i>Copy</button></div>
+              </div>
+              <div class="card-body p-0">
+                <pre class="xes-code rounded p-3 mb-0"><code><text value="snippet" /></code></pre>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="card xes-card">
+          <div class="card-header bg-transparent">
+            <strong><i class="bi bi-play-circle me-2"></i>Live demo</strong>
+          </div>
+          <div class="card-body">
+            <div class="mb-3">
+              <label class="form-label">Email</label>
+              <input class="form-control" type="email" bind:value="email" />
+              <small class="text-secondary">Live value: <code>{email}</code></small>
+            </div>
+
+            <div class="form-check mb-3">
+              <input class="form-check-input" type="checkbox" id="cb-news" bind:checked="newsletter" />
+              <label class="form-check-label" for="cb-news">Subscribe to the newsletter</label>
+            </div>
+
+            <div class="mb-3">
+              <label class="form-label">Password strength: {strength}</label>
+              <input class="form-range" type="range" min="0" max="5" bind:value="strength" />
+              <div class="progress" style="height: .35rem;">
+                <div class="progress-bar bg-info" style="width: {strength * 20}%"></div>
+              </div>
+            </div>
+
+            <div class="alert mb-3 {strength &gt;= 4 ? 'alert-success' : strength &gt;= 2 ? 'alert-warning' : 'alert-danger'}">
+              <i class="bi bi-shield-check me-1"></i>
+              <strong>Strength is {strength}/5</strong> -
+              <if test="strength >= 4">strong enough.</if>
+              <if test="strength === 3">acceptable but consider longer.</if>
+              <if test="strength &lt; 3">too weak.</if>
+            </div>
+
+            <button class="btn btn-info" on:click="#logSubmit">
+              <i class="bi bi-send me-1"></i>Submit (logs to console)
+            </button>
+          </div>
+        </div>
+
+        <div class="card xes-card mt-4">
+          <div class="card-header bg-transparent">
+            <strong><i class="bi bi-ui-checks-grid me-2"></i>Selects and date inputs</strong>
+          </div>
+          <div class="card-body">
+            <p class="text-secondary">
+              <code>bind:value</code> works for any control with a string-shaped value -
+              including <code>&lt;select&gt;</code> and <code>&lt;input type="date"&gt;</code>.
+              The signal holds the option value or the ISO date string; the runtime keeps the
+              control in sync after a render.
+            </p>
+            <div class="row g-3 align-items-end">
+              <div class="col-md-4">
+                <label class="form-label">Role</label>
+                <select class="form-select" bind:value="role">
+                  <option value="viewer">Viewer</option>
+                  <option value="editor">Editor</option>
+                  <option value="admin">Admin</option>
+                </select>
+                <small class="text-secondary">Selected: <code>{role}</code></small>
+              </div>
+              <div class="col-md-4">
+                <label class="form-label">Due date</label>
+                <input class="form-control" type="date" bind:value="dueDate" />
+                <small class="text-secondary">Picked: <code>{dueDate}</code></small>
+              </div>
+              <div class="col-md-4">
+                <div class="alert mb-0 alert-info">
+                  Granting <strong>{role}</strong> access until <strong>{dueDate}</strong>.
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </view>
+  </component>
+</galath>

package/playground/chapters/05-lists.xml

@@ -0,0 +1,138 @@
+<!--
+  chapters/05-lists.xml
+
+  <repeat> and <items> + <datatemplate>. Both iterate over a node-set
+  resolved from a path; <items> uses a named template, <repeat> inlines
+  the body.
+-->
+<galath xmlns:bind="urn:galath:bind" xmlns:on="urn:galath:on" xmlns:use="urn:galath:use" xmlns:drag="urn:galath:drag" xmlns:drop="urn:galath:drop" xmlns:class="urn:galath:class">
+  <component name="chapter-lists" tag="x-chapter-lists">
+    <model>
+      <instance>
+        <library>
+          <book title="The Phoenix Project" author="Gene Kim" read="true"  />
+          <book title="Designing Data-Intensive Applications" author="Martin Kleppmann" read="false" />
+          <book title="A Philosophy of Software Design" author="John Ousterhout" read="true"  />
+          <book title="Out of the Tar Pit" author="Moseley &amp; Marks" read="false" />
+        </library>
+      </instance>
+
+      <signal name="snippet"><![CDATA[<datatemplate name="book-row" for="book">
+  <li>
+    <input type="checkbox" bind:checked="$book/@read" />
+    <strong><text value="$book/@title" /></strong>
+    by <text value="$book/@author" />
+  </li>
+</datatemplate>
+
+<ul>
+  <items source="/library/book" as="book" template="book-row" />
+</ul>
+
+<!-- or, lower level: -->
+<ul>
+  <repeat ref="/library/book" as="book">
+    <li><text value="$book/@title" /></li>
+  </repeat>
+</ul>]]></signal>
+    </model>
+
+    <!--
+      A reusable row template. The renderer instantiates it once per
+      matched node and binds $book to the loop item.
+    -->
+    <datatemplate name="book-row" for="book">
+      <div class="list-group-item d-flex align-items-center gap-2">
+        <input class="form-check-input m-0" type="checkbox" bind:checked="$book/@read" />
+        <div class="flex-grow-1">
+          <div class="fw-semibold {$book/@read ? 'text-decoration-line-through text-secondary' : ''}">
+            <text value="$book/@title" />
+          </div>
+          <small class="text-secondary">by <text value="$book/@author" /></small>
+        </div>
+        <span class="badge text-bg-{$book/@read ? 'success' : 'secondary'}">
+          <if test="$book/@read">read</if>
+          <if test="!$book/@read">unread</if>
+        </span>
+      </div>
+    </datatemplate>
+
+    <view>
+      <div class="px-4 py-5">
+        <x-chapter-heading icon="bi-collection" title="Lists &amp; Templates"
+          subtitle="Iterate over selected nodes with &lt;repeat&gt; or a reusable &lt;datatemplate&gt;." />
+
+        <div class="row g-4 mb-4">
+          <div class="col-lg-6">
+            <div class="card xes-card h-100">
+              <div class="card-body">
+                <h2 class="h5"><i class="bi bi-journal-text me-2 text-info"></i>How it works</h2>
+                <p class="text-secondary">
+                  <code>&lt;repeat ref="..." as="x"&gt;</code> renders its children once per node
+                  in the selection, with <code>$x</code> in scope.
+                </p>
+                <p class="text-secondary">
+                  <code>&lt;datatemplate name="..." for="..."&gt;</code> declares a reusable
+                  fragment. <code>&lt;items source="..." template="name"/&gt;</code> instantiates it.
+                  Same effect, less duplication when the row is non-trivial.
+                </p>
+                <p class="text-secondary mb-0">
+                  Inside the template, <code>$x</code> is the loop item (an <code>XNode</code>).
+                  Use <code>$x/@attr</code> to read an attribute, or <code>$x/text()</code> for
+                  the element text.
+                </p>
+              </div>
+            </div>
+          </div>
+          <div class="col-lg-6">
+            <div class="card xes-card h-100">
+              <div class="card-header bg-transparent d-flex justify-content-between align-items-center">
+                <strong><i class="bi bi-code-slash me-2"></i>Source</strong>
+                <div class="btn-group btn-group-sm" role="group"><button class="btn btn-outline-info" on:click="window.galathRunSnippet(snippet)" title="Open this snippet in a new tab"><i class="bi bi-play-fill me-1"></i>Run</button><button class="btn btn-outline-info" use:copy="snippet" title="Copy to clipboard"><i class="bi bi-clipboard me-1"></i>Copy</button></div>
+              </div>
+              <div class="card-body p-0">
+                <pre class="xes-code rounded p-3 mb-0"><code><text value="snippet" /></code></pre>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="card xes-card">
+          <div class="card-header bg-transparent d-flex justify-content-between align-items-center">
+            <strong><i class="bi bi-play-circle me-2"></i>Live demo</strong>
+            <span class="badge text-bg-info">
+              {select('/library/book[@read=true]').length} / {select('/library/book').length} read
+            </span>
+          </div>
+          <div class="card-body">
+            <div class="list-group">
+              <items source="/library/book" as="book" template="book-row" />
+            </div>
+          </div>
+        </div>
+
+        <div class="card xes-card mt-4">
+          <div class="card-header bg-transparent">
+            <strong><i class="bi bi-list-ol me-2"></i>The implicit <code>index</code> local</strong>
+          </div>
+          <div class="card-body">
+            <p class="text-secondary">
+              Inside a <code>&lt;repeat&gt;</code> or <code>&lt;items&gt;</code>, the runtime
+              binds <code>index</code> (zero-based) so you can number rows or alternate styling
+              without touching the data.
+            </p>
+            <ol class="list-group list-group-numbered">
+              <repeat ref="/library/book" as="book">
+                <li class="list-group-item d-flex align-items-center">
+                  <span class="badge text-bg-{index % 2 === 0 ? 'info' : 'secondary'} me-2">#{index + 1}</span>
+                  <span class="flex-grow-1"><text value="$book/@title" /></span>
+                  <small class="text-secondary">index = {index}</small>
+                </li>
+              </repeat>
+            </ol>
+          </div>
+        </div>
+      </div>
+    </view>
+  </component>
+</galath>