flarp 1.0.0

package/src/dom/find.js

@@ -0,0 +1,128 @@
+/**
+ * DOM utilities for Flarp
+ * 
+ * Intelligent store discovery that doesn't require nesting.
+ */
+
+/**
+ * Find nearest store by searching up the DOM tree
+ * 
+ * @param {Element} element - Starting element
+ * @param {string} selector - Store selector (default: 'f-state')
+ * @returns {Element|null}
+ * 
+ * Search order:
+ * 1. Explicit store="id" attribute
+ * 2. Scoped store from f-each
+ * 3. Nearest f-state in same container hierarchy
+ * 4. Document-level fallback by ID proximity
+ */
+export function findStore(element, selector = 'f-state') {
+  // 1. Check explicit reference
+  const ref = element.getAttribute('store');
+  if (ref) {
+    const explicit = document.getElementById(ref);
+    if (explicit) return explicit;
+  }
+
+  // 2. Check scoped store (from f-each)
+  if (element._store) {
+    return element._store;
+  }
+
+  // 3. Walk up and search within each ancestor's subtree
+  let current = element.parentElement;
+  
+  while (current) {
+    // Search for f-state within this ancestor (but not within nested components)
+    const store = current.querySelector(selector);
+    if (store) {
+      return store;
+    }
+    current = current.parentElement;
+  }
+
+  // 4. Fallback - shouldn't normally reach here if structure is correct
+  return document.querySelector(selector);
+}
+
+/**
+ * Find all stores relevant to an element
+ * @param {Element} element
+ * @param {string} selector
+ * @returns {Element[]}
+ */
+export function findAllStores(element, selector = 'f-state') {
+  const stores = [];
+  const seen = new Set();
+  let current = element.parentElement;
+
+  while (current) {
+    for (const store of current.querySelectorAll(selector)) {
+      if (!seen.has(store)) {
+        seen.add(store);
+        stores.push(store);
+      }
+    }
+    current = current.parentElement;
+  }
+
+  return stores;
+}
+
+/**
+ * Wait for store to be ready
+ * @param {Element} store
+ * @returns {Promise}
+ */
+export function whenReady(store) {
+  if (store.state?.is('ready')) {
+    return Promise.resolve(store);
+  }
+  return store.state?.until('ready').then(() => store) 
+    || Promise.resolve(store);
+}
+
+/**
+ * Create a scoped store proxy for iteration contexts
+ * @param {Object} parentStore - Parent store reference
+ * @param {Element} scopeElement - XML element for this iteration
+ * @returns {Object} Scoped store proxy
+ */
+export function scopedStore(parentStore, scopeElement) {
+  return {
+    at(path) {
+      if (path === '.' || path === '') {
+        const { Node } = parentStore.constructor;
+        return Node ? Node.wrap(scopeElement) : null;
+      }
+      // Resolve relative to scope element
+      const { Path, Node, AttrNode } = parentStore.constructor;
+      const resolved = Path.resolve(scopeElement, path);
+      if (!resolved) return null;
+      
+      if (resolved.attr) {
+        return AttrNode.wrap(resolved.element, resolved.attr);
+      }
+      return Node.wrap(resolved.element);
+    },
+
+    query(path) {
+      const { Path, Node } = parentStore.constructor;
+      return Path.resolveAll(scopeElement, path).map(el => Node.wrap(el));
+    },
+
+    // Delegate other methods to parent
+    add: parentStore.add?.bind(parentStore),
+    remove: parentStore.remove?.bind(parentStore),
+    emit: parentStore.emit?.bind(parentStore),
+    on: parentStore.on?.bind(parentStore),
+    state: parentStore.state,
+
+    // Mark as scoped
+    _scoped: true,
+    _element: scopeElement
+  };
+}
+
+export default { findStore, findAllStores, whenReady, scopedStore };

package/src/dom/index.js

@@ -0,0 +1,5 @@
+/**
+ * DOM - DOM utilities for Flarp
+ */
+
+export { findStore, findAllStores, whenReady, scopedStore } from './find.js';

package/src/index.js

@@ -0,0 +1,63 @@
+/**
+ * Flarp - DOM-native XML State Management
+ * 
+ * XML is state. Signals are reactive. The DOM is the runtime.
+ * 
+ * @example
+ * ```html
+ * <f-state key="myapp" autosave="500">
+ *   <User>
+ *     <n>Alice</n>
+ *     <Role>Developer</Role>
+ *   </User>
+ * </f-state>
+ * 
+ * <main>
+ *   <f-text path="User.Name"></f-text>
+ *   <f-field path="User.Role"></f-field>
+ * </main>
+ * 
+ * <script type="module">
+ *   import 'flarp';
+ *   
+ *   const store = document.querySelector('f-state');
+ *   
+ *   store.state.when('ready', () => {
+ *     const name = store.at('User.Name');
+ *     name.subscribe(v => console.log('Name:', v));
+ *   });
+ * </script>
+ * ```
+ */
+
+// Core reactive primitives
+export { default as Signal } from './core/Signal.js';
+export { default as State } from './core/State.js';
+
+// XML utilities
+export { default as Node, AttrNode } from './xml/Node.js';
+export { default as Tree } from './xml/Tree.js';
+export * as Path from './xml/Path.js';
+
+// Sync utilities
+export * as Persist from './sync/Persist.js';
+export { default as Channel, Protocol } from './sync/Channel.js';
+
+// DOM utilities
+export { findStore, findAllStores, whenReady, scopedStore } from './dom/find.js';
+
+// Web Components
+export { 
+  FStore, 
+  FText, 
+  FField, 
+  FBind, 
+  FEach, 
+  FWhen, 
+  FMatch, 
+  FCase, 
+  FElse 
+} from './components/index.js';
+
+// Version
+export const VERSION = '2.0.0';

package/src/sync/Channel.js

@@ -0,0 +1,113 @@
+/**
+ * Channel - Cross-tab synchronization via BroadcastChannel
+ * 
+ * @example
+ * const channel = new Channel('myapp');
+ * 
+ * channel.onMessage(data => {
+ *   console.log('Received from other tab:', data);
+ * });
+ * 
+ * channel.send({ type: 'update', xml: '...' });
+ */
+
+export default class Channel {
+  #channel;
+  #key;
+  #handlers = new Set();
+
+  /**
+   * @param {string} key - Channel identifier
+   */
+  constructor(key) {
+    this.#key = key;
+
+    if (typeof BroadcastChannel !== 'undefined') {
+      this.#channel = new BroadcastChannel(`flarp:${key}`);
+      this.#channel.onmessage = (e) => {
+        for (const handler of this.#handlers) {
+          try {
+            handler(e.data);
+          } catch (err) {
+            console.error('Channel handler error:', err);
+          }
+        }
+      };
+    }
+  }
+
+  /**
+   * Send data to other tabs
+   * @param {*} data - Serializable data
+   */
+  send(data) {
+    this.#channel?.postMessage(data);
+  }
+
+  /**
+   * Register message handler
+   * @param {Function} fn - Handler function
+   * @returns {Function} Unsubscribe
+   */
+  onMessage(fn) {
+    this.#handlers.add(fn);
+    return () => this.#handlers.delete(fn);
+  }
+
+  /**
+   * Close channel
+   */
+  close() {
+    this.#channel?.close();
+    this.#handlers.clear();
+  }
+
+  /**
+   * Check if BroadcastChannel is supported
+   */
+  static get supported() {
+    return typeof BroadcastChannel !== 'undefined';
+  }
+}
+
+/**
+ * Sync protocol messages
+ */
+export const Protocol = {
+  UPDATE: 'update',
+  REQUEST: 'request',
+  RESPONSE: 'response',
+
+  /**
+   * Create update message
+   */
+  update(xml, nodeId = null) {
+    return {
+      type: this.UPDATE,
+      xml,
+      nodeId,
+      timestamp: Date.now()
+    };
+  },
+
+  /**
+   * Create state request
+   */
+  request() {
+    return {
+      type: this.REQUEST,
+      timestamp: Date.now()
+    };
+  },
+
+  /**
+   * Create state response
+   */
+  response(xml) {
+    return {
+      type: this.RESPONSE,
+      xml,
+      timestamp: Date.now()
+    };
+  }
+};

package/src/sync/Persist.js

@@ -0,0 +1,216 @@
+/**
+ * Persist - Storage adapters for XML state
+ * 
+ * Supports localStorage, sessionStorage, and IndexedDB.
+ * All adapters share the same async interface.
+ */
+
+const PREFIX = 'flarp:';
+
+/**
+ * localStorage adapter
+ */
+export const local = {
+  name: 'localStorage',
+
+  async get(key) {
+    try {
+      return localStorage.getItem(PREFIX + key);
+    } catch (e) {
+      console.warn('localStorage get failed:', e);
+      return null;
+    }
+  },
+
+  async set(key, value) {
+    try {
+      localStorage.setItem(PREFIX + key, value);
+      return true;
+    } catch (e) {
+      console.warn('localStorage set failed:', e);
+      return false;
+    }
+  },
+
+  async remove(key) {
+    try {
+      localStorage.removeItem(PREFIX + key);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  },
+
+  async keys() {
+    const result = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(PREFIX)) {
+        result.push(key.slice(PREFIX.length));
+      }
+    }
+    return result;
+  }
+};
+
+/**
+ * sessionStorage adapter (per-tab)
+ */
+export const session = {
+  name: 'sessionStorage',
+
+  async get(key) {
+    try {
+      return sessionStorage.getItem(PREFIX + key);
+    } catch (e) {
+      return null;
+    }
+  },
+
+  async set(key, value) {
+    try {
+      sessionStorage.setItem(PREFIX + key, value);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  },
+
+  async remove(key) {
+    try {
+      sessionStorage.removeItem(PREFIX + key);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  },
+
+  async keys() {
+    const result = [];
+    for (let i = 0; i < sessionStorage.length; i++) {
+      const key = sessionStorage.key(i);
+      if (key?.startsWith(PREFIX)) {
+        result.push(key.slice(PREFIX.length));
+      }
+    }
+    return result;
+  }
+};
+
+/**
+ * IndexedDB adapter (for large state)
+ */
+export const indexed = {
+  name: 'indexedDB',
+  _db: null,
+  _dbName: 'flarp',
+  _storeName: 'state',
+
+  async _open() {
+    if (this._db) return this._db;
+
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this._dbName, 1);
+
+      request.onerror = () => reject(request.error);
+
+      request.onupgradeneeded = (e) => {
+        const db = e.target.result;
+        if (!db.objectStoreNames.contains(this._storeName)) {
+          db.createObjectStore(this._storeName);
+        }
+      };
+
+      request.onsuccess = () => {
+        this._db = request.result;
+        resolve(this._db);
+      };
+    });
+  },
+
+  async get(key) {
+    try {
+      const db = await this._open();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(this._storeName, 'readonly');
+        const store = tx.objectStore(this._storeName);
+        const request = store.get(key);
+        request.onsuccess = () => resolve(request.result || null);
+        request.onerror = () => reject(request.error);
+      });
+    } catch (e) {
+      return null;
+    }
+  },
+
+  async set(key, value) {
+    try {
+      const db = await this._open();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(this._storeName, 'readwrite');
+        const store = tx.objectStore(this._storeName);
+        const request = store.put(value, key);
+        request.onsuccess = () => resolve(true);
+        request.onerror = () => reject(request.error);
+      });
+    } catch (e) {
+      return false;
+    }
+  },
+
+  async remove(key) {
+    try {
+      const db = await this._open();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(this._storeName, 'readwrite');
+        const store = tx.objectStore(this._storeName);
+        const request = store.delete(key);
+        request.onsuccess = () => resolve(true);
+        request.onerror = () => reject(request.error);
+      });
+    } catch (e) {
+      return false;
+    }
+  },
+
+  async keys() {
+    try {
+      const db = await this._open();
+      return new Promise((resolve, reject) => {
+        const tx = db.transaction(this._storeName, 'readonly');
+        const store = tx.objectStore(this._storeName);
+        const request = store.getAllKeys();
+        request.onsuccess = () => resolve(request.result || []);
+        request.onerror = () => reject(request.error);
+      });
+    } catch (e) {
+      return [];
+    }
+  }
+};
+
+/**
+ * Get best available adapter
+ */
+export function auto() {
+  try {
+    localStorage.setItem('__test__', '1');
+    localStorage.removeItem('__test__');
+    return local;
+  } catch (e) {
+    return indexed;
+  }
+}
+
+/**
+ * Debounce utility
+ */
+export function debounce(fn, ms) {
+  let timer = null;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), ms);
+  };
+}
+
+export default { local, session, indexed, auto, debounce };

package/src/sync/index.js

@@ -0,0 +1,6 @@
+/**
+ * Sync - Persistence and cross-tab synchronization
+ */
+
+export * as Persist from './Persist.js';
+export { default as Channel, Protocol } from './Channel.js';