flarp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,332 @@
+# Flarp
+
+**DOM-native XML State Management for Web Components**
+
+```
+XML is state. Signals are reactive. The DOM is the runtime.
+```
+
+---
+
+## Why Flarp?
+
+State management shouldn't require learning proprietary patterns. Flarp uses what the web already has:
+
+- **XML for state** — Nested structure you can see and understand
+- **Signals for reactivity** — No virtual DOM, no diffing, just updates
+- **Web Components for UI** — Standard, portable, composable
+- **DOM as runtime** — MutationObserver does the scheduling
+
+## Quick Start
+
+```html
+<script type="module">
+  import 'https://unpkg.com/flarp/src/index.js';
+</script>
+
+<f-state key="myapp" autosave="500">
+  <user>
+    <name>Alice</name>
+    <role>Developer</role>
+  </user>
+</f-state>
+
+<main>
+  <h1><f-text path="user.name"></f-text></h1>
+  <f-field path="user.role"></f-field>
+</main>
+```
+
+Components find `<f-state>` automatically — no nesting required!
+
+> **Note:** The DOM lowercases all tag names. Use lowercase paths like `user.name`, not `User.Name`. Path matching is case-insensitive, so `User.Name` will still work, but your XML will appear lowercase in the DOM.
+
+## Key Innovation: Signal-Based Readiness
+
+Events fire once. If you miss them, you miss them. Signals don't have this problem:
+
+```js
+// This works even if 'ready' already happened!
+store.state.when('ready', () => {
+  const name = store.at('User.Name');
+  name.subscribe(v => console.log('Name:', v));
+});
+
+// Or use async/await
+await store.state.until('ready');
+```
+
+## Installation
+
+```bash
+npm install flarp
+```
+
+Or use directly:
+
+```html
+<script type="module">
+  import 'https://unpkg.com/flarp/src/index.js';
+</script>
+```
+
+---
+
+## Components
+
+### `<f-state>` — The Store
+
+```html
+<f-state 
+  key="myapp"      <!-- Persistence key -->
+  autosave="500"   <!-- Debounce ms -->
+  src="/api/data"  <!-- Load from URL -->
+>
+  <User>
+    <n>Alice</n>
+  </User>
+</f-state>
+```
+
+**API:**
+- `at(path)` — Get reactive node
+- `query(path)` — Get all matching nodes
+- `set(path, value)` — Set value
+- `add(path, xml)` — Add child
+- `remove(path)` — Remove node
+- `serialize()` — Get XML string
+- `on(action, fn)` — Register action
+- `emit(action, payload)` — Dispatch action
+- `state.when(name, fn)` — React to state
+- `state.until(name)` — Promise for state
+
+### `<f-text>` — Display
+
+```html
+<f-text path="User.Name"></f-text>
+<f-text path="Price" format="currency"></f-text>
+```
+
+**Formats:** `uppercase`, `lowercase`, `number`, `currency`, `percent`
+
+### `<f-field>` — Two-Way Binding
+
+```html
+<f-field path="User.Name"></f-field>
+<f-field path="User.Age" type="number"></f-field>
+<f-field path="User.Active" type="checkbox"></f-field>
+```
+
+### `<f-each>` — Lists
+
+```html
+<f-each path="Users.User">
+  <template>
+    <div class="card">
+      <f-text path="Name"></f-text>
+      <f-field path="Email"></f-field>
+    </div>
+  </template>
+</f-each>
+```
+
+Paths inside templates are relative to each item.
+
+### `<f-when>` — Conditionals
+
+```html
+<f-when test="User.LoggedIn == 'true'">
+  <span>Welcome!</span>
+</f-when>
+
+<f-when test="Cart.Total > 100">
+  <span>Free shipping!</span>
+</f-when>
+```
+
+### `<f-match>` — Switch
+
+```html
+<f-match test="User.Role">
+  <f-case value="admin">Admin Panel</f-case>
+  <f-case value="user">Dashboard</f-case>
+  <f-else>Please log in</f-else>
+</f-match>
+```
+
+---
+
+## Store Discovery
+
+Components don't need to be nested inside `<f-state>`. Flarp searches siblings and ancestors:
+
+```html
+<div class="app">
+  <f-state id="app">
+    <User><n>Alice</n></User>
+  </f-state>
+  
+  <main>
+    <!-- Finds sibling f-state automatically -->
+    <f-text path="User.Name"></f-text>
+  </main>
+</div>
+```
+
+Or reference explicitly:
+
+```html
+<f-text store="app" path="User.Name"></f-text>
+```
+
+---
+
+## Event Sourcing
+
+```js
+// Register actions
+store.on('addUser', ({ name, role }) => {
+  store.add('Users', `<User><n>${name}</n><Role>${role}</Role></User>`);
+});
+
+// Dispatch
+store.emit('addUser', { name: 'Bob', role: 'Developer' });
+```
+
+---
+
+## Per-Node Reactivity
+
+Every XML node is independently:
+- **Reactive** — Has its own Signal
+- **Identifiable** — UUID attribute
+- **Versioned** — `rev` for conflict resolution
+- **Serializable** — `node.serialize()`
+
+```js
+const node = store.at('User.Name');
+
+node.uuid;        // "a1b2c3..."
+node.rev;         // 5
+node.serialize(); // "<n uuid="..." rev="5">Alice</n>"
+
+// Subscribe to just this node
+node.subscribe(value => console.log(value));
+```
+
+---
+
+## Persistence
+
+State persists to localStorage automatically:
+
+```html
+<f-state key="myapp" autosave="500">
+```
+
+Features:
+- **Crash recovery** — Reload resumes state
+- **Cross-tab sync** — BroadcastChannel
+- **Conflict resolution** — Higher `rev` wins, `uuid` tiebreaker
+
+---
+
+## Modular Architecture
+
+Flarp is built from composable pieces:
+
+```js
+// Just the signal primitive
+import { Signal } from 'flarp/core';
+
+// Just XML utilities
+import { Node, Path } from 'flarp/xml';
+
+// Just persistence
+import { Persist } from 'flarp/sync';
+```
+
+---
+
+## Custom Components
+
+```js
+import { findStore } from 'flarp';
+
+class UserCard extends HTMLElement {
+  connectedCallback() {
+    const store = findStore(this);
+    
+    store.state.when('ready', () => {
+      const name = store.at('User.Name');
+      
+      name.subscribe(v => {
+        this.innerHTML = `<h2>${v}</h2>`;
+      });
+    });
+  }
+}
+
+customElements.define('user-card', UserCard);
+```
+
+---
+
+## Philosophy
+
+1. **XML is data** — Human-readable, self-describing, AI-friendly
+2. **Signals are sync** — No scheduler, no batching, just updates
+3. **DOM is truth** — MutationObserver, not virtual DOM
+4. **State ≠ UI** — Keep them separate, connect with paths
+5. **Persist by default** — State survives refresh
+
+---
+
+## Tag Naming
+
+**Important:** The browser's HTML parser lowercases all tag names. When you write:
+
+```html
+<f-state>
+  <User><Name>Alice</Name></User>
+</f-state>
+```
+
+The DOM actually contains:
+
+```html
+<f-state>
+  <user><name>Alice</name></user>
+</f-state>
+```
+
+**Flarp handles this automatically** — path matching is case-insensitive. Both `user.name` and `User.Name` will work. However, we recommend using lowercase tags for clarity:
+
+```html
+<f-state>
+  <user>
+    <name>Alice</name>
+    <email>alice@example.com</email>
+  </user>
+</f-state>
+```
+
+---
+
+## Browser Support
+
+Modern browsers with ES modules:
+- Chrome 61+
+- Firefox 60+
+- Safari 11+
+- Edge 79+
+
+---
+
+## License
+
+MIT
+
+---
+
+*Built for developers who believe state management can be simple.*

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "flarp",
+  "version": "1.0.0",
+  "description": "DOM-native XML state management for Web Components",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./core": "./src/core/index.js",
+    "./xml": "./src/xml/index.js",
+    "./sync": "./src/sync/index.js",
+    "./dom": "./src/dom/index.js",
+    "./components": "./src/components/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "dev": "http-server -c-1 -o",
+    "start": "http-server -c-1 -o"
+  },
+  "keywords": [
+    "xml",
+    "state",
+    "signals",
+    "reactive",
+    "web-components",
+    "dom"
+  ],
+
+
+  "author": "catpea (https://github.com/catpea)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/catpea/flarp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/catpea/flarp/issues"
+  },
+  "homepage": "https://catpea.github.io/flarp",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/catpea"
+  }
+
+}

package/src/components/FBind.js

@@ -0,0 +1,76 @@
+/**
+ * FBind - One-way binding to external DOM elements
+ * 
+ * @element f-bind
+ * 
+ * @attr {string} path - XML path to bind from
+ * @attr {string} target - CSS selector for target element(s)
+ * @attr {string} attr - Attribute to set (optional)
+ * @attr {string} prop - Property to set (optional)
+ * @attr {string} store - Optional store ID reference
+ * 
+ * @example
+ * <f-bind path="User.Name" target="#header h1"></f-bind>
+ * <f-bind path="App.Theme" target="body" attr="data-theme"></f-bind>
+ * <f-bind path="User.Avatar" target="#avatar" prop="src"></f-bind>
+ */
+
+import { findStore } from '../dom/find.js';
+
+export default class FBind extends HTMLElement {
+  #unsubscribe = null;
+
+  connectedCallback() {
+    this.style.display = 'none';
+    this.#connect();
+  }
+
+  disconnectedCallback() {
+    this.#unsubscribe?.();
+  }
+
+  #connect() {
+    const path = this.getAttribute('path');
+    const target = this.getAttribute('target');
+    const attr = this.getAttribute('attr');
+    const prop = this.getAttribute('prop');
+
+    if (!path || !target) {
+      console.warn('<f-bind> requires path and target attributes');
+      return;
+    }
+
+    const store = this._store || findStore(this);
+    if (!store) {
+      console.warn('<f-bind> could not find store');
+      return;
+    }
+
+    store.state.when('ready', () => {
+      const node = store.at(path);
+      if (!node) return;
+
+      this.#unsubscribe = node.subscribe(value => {
+        const targets = document.querySelectorAll(target);
+
+        for (const el of targets) {
+          if (attr) {
+            if (value != null) {
+              el.setAttribute(attr, value);
+            } else {
+              el.removeAttribute(attr);
+            }
+          } else if (prop) {
+            el[prop] = value ?? '';
+          } else if ('value' in el && (el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA')) {
+            el.value = value ?? '';
+          } else {
+            el.textContent = value ?? '';
+          }
+        }
+      });
+    });
+  }
+}
+
+customElements.define('f-bind', FBind);

package/src/components/FEach.js

@@ -0,0 +1,194 @@
+/**
+ * FEach - Reactive list iteration
+ * 
+ * @element f-each
+ * 
+ * @attr {string} path - XML path to iterate over
+ * @attr {string} store - Optional store ID reference
+ * 
+ * Inside the template, paths are relative to each item.
+ * Use "." for the current node's text content.
+ * 
+ * @example
+ * <f-each path="Users.User">
+ *   <template>
+ *     <div class="user">
+ *       <f-text path="Name"></f-text>
+ *       <f-field path="Email"></f-field>
+ *     </div>
+ *   </template>
+ * </f-each>
+ */
+
+import { findStore, scopedStore } from '../dom/find.js';
+import Node from '../xml/Node.js';
+import * as Path from '../xml/Path.js';
+
+export default class FEach extends HTMLElement {
+  #template = null;
+  #container = null;
+  #instances = new WeakMap();
+  #observer = null;
+
+  connectedCallback() {
+    this.#setup();
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect();
+  }
+
+  #setup() {
+    const path = this.getAttribute('path');
+    this.#template = this.querySelector('template');
+
+    if (!this.#template) {
+      console.warn('<f-each> requires a <template> child');
+      return;
+    }
+
+    const store = this._store || findStore(this);
+    if (!store) {
+      console.warn('<f-each> could not find store');
+      return;
+    }
+
+    // Create container for rendered items
+    this.#container = document.createElement('div');
+    this.#container.style.display = 'contents';
+    this.appendChild(this.#container);
+
+    store.state.when('ready', () => {
+      // Find parent element to observe
+      const parentPath = Path.parent(path);
+      const parentResolved = parentPath 
+        ? Path.resolve(store, parentPath)
+        : { element: store };
+
+      if (!parentResolved) {
+        console.warn(`<f-each> parent path not found: ${parentPath}`);
+        return;
+      }
+
+      const parent = parentResolved.element;
+
+      // Initial render
+      this.#render(store, path);
+
+      // Observe for structural changes
+      this.#observer = new MutationObserver(() => {
+        this.#render(store, path);
+      });
+
+      this.#observer.observe(parent, { childList: true });
+    });
+  }
+
+  #render(store, path) {
+    const elements = Path.resolveAll(store, path);
+    const seen = new Set(elements);
+
+    // Remove stale items
+    for (const child of Array.from(this.#container.children)) {
+      if (!seen.has(child.__element)) {
+        child.remove();
+      }
+    }
+
+    // Add/update items
+    elements.forEach((element, index) => {
+      if (this.#instances.has(element)) {
+        // Ensure correct order
+        const existing = this.#instances.get(element);
+        if (this.#container.children[index] !== existing) {
+          this.#container.insertBefore(existing, this.#container.children[index]);
+        }
+        return;
+      }
+
+      // Create new instance
+      const fragment = this.#template.content.cloneNode(true);
+      const wrapper = document.createElement('div');
+      wrapper.style.display = 'contents';
+      wrapper.appendChild(fragment);
+      wrapper.__element = element;
+
+      // Create scoped store for this item
+      const scoped = this.#createScopedStore(store, element);
+
+      // Set scoped store on all f-* children
+      this.#initializeScoped(wrapper, scoped);
+
+      this.#instances.set(element, wrapper);
+
+      // Insert at correct position
+      if (this.#container.children[index]) {
+        this.#container.insertBefore(wrapper, this.#container.children[index]);
+      } else {
+        this.#container.appendChild(wrapper);
+      }
+    });
+  }
+
+  #createScopedStore(parentStore, element) {
+    return {
+      at(path) {
+        if (path === '.' || path === '') {
+          return Node.wrap(element);
+        }
+        const resolved = Path.resolve(element, path);
+        if (!resolved) return null;
+
+        if (resolved.attr) {
+          const { AttrNode } = parentStore.constructor;
+          return AttrNode.wrap(resolved.element, resolved.attr);
+        }
+        return Node.wrap(resolved.element);
+      },
+
+      query(path) {
+        return Path.resolveAll(element, path).map(el => Node.wrap(el));
+      },
+
+      add: parentStore.add?.bind(parentStore),
+      remove: parentStore.remove?.bind(parentStore),
+      emit: parentStore.emit?.bind(parentStore),
+      on: parentStore.on?.bind(parentStore),
+      state: parentStore.state,
+
+      // For nested f-each
+      constructor: parentStore.constructor
+    };
+  }
+
+  #initializeScoped(root, scoped) {
+    const scopedTags = ['f-text', 'f-field', 'f-each', 'f-when', 'f-bind'];
+    
+    for (const tag of scopedTags) {
+      for (const el of root.querySelectorAll(tag)) {
+        el._store = scoped;
+      }
+    }
+
+    // Handle elements added later
+    const observer = new MutationObserver(mutations => {
+      for (const m of mutations) {
+        for (const node of m.addedNodes) {
+          if (node.nodeType !== 1) continue;
+          if (scopedTags.includes(node.tagName.toLowerCase())) {
+            node._store = scoped;
+          }
+          for (const tag of scopedTags) {
+            for (const el of node.querySelectorAll?.(tag) || []) {
+              el._store = scoped;
+            }
+          }
+        }
+      }
+    });
+
+    observer.observe(root, { childList: true, subtree: true });
+  }
+}
+
+customElements.define('f-each', FEach);