flarp 1.0.0

package/src/components/FWhen.js

@@ -0,0 +1,253 @@
+/**
+ * FWhen - Conditional rendering
+ * 
+ * @element f-when
+ * 
+ * @attr {string} test - Condition to evaluate
+ * @attr {string} store - Optional store ID reference
+ * 
+ * Supports:
+ * - Truthy check: test="user.loggedin"
+ * - Equality: test="user.role == 'admin'"
+ * - Comparison: test="cart.total > 100"
+ * 
+ * @example
+ * <f-when test="user.loggedin == 'true'">
+ *   <span>Welcome back!</span>
+ * </f-when>
+ */
+
+import { findStore } from '../dom/find.js';
+
+const OPERATORS = ['>=', '<=', '!=', '==', '>', '<'];
+
+function evaluate(test, store) {
+  const op = OPERATORS.find(o => test.includes(o));
+
+  if (!op) {
+    // Simple truthy check
+    const node = store.at(test.trim());
+    const value = node?.peek?.() ?? node?.value;
+    return Boolean(value) && value !== 'false' && value !== '0' && value !== '';
+  }
+
+  // Parse comparison
+  const [left, right] = test.split(op).map(s => s.trim());
+  const node = store.at(left);
+  const leftVal = node?.peek?.() ?? node?.value;
+
+  // Parse right side literal
+  let rightVal;
+  if ((right.startsWith("'") && right.endsWith("'")) ||
+      (right.startsWith('"') && right.endsWith('"'))) {
+    rightVal = right.slice(1, -1);
+  } else if (right === 'true') {
+    rightVal = true;
+  } else if (right === 'false') {
+    rightVal = false;
+  } else if (right === 'null') {
+    rightVal = null;
+  } else {
+    rightVal = Number(right);
+  }
+
+  switch (op) {
+    case '==': return leftVal == rightVal;
+    case '!=': return leftVal != rightVal;
+    case '>':  return Number(leftVal) > rightVal;
+    case '<':  return Number(leftVal) < rightVal;
+    case '>=': return Number(leftVal) >= rightVal;
+    case '<=': return Number(leftVal) <= rightVal;
+    default:   return false;
+  }
+}
+
+export default class FWhen extends HTMLElement {
+  #container = null;
+  #templateHtml = '';
+  #showing = false;
+  #observer = null;
+  #store = null;
+  #test = null;
+  #lastResult = null;
+
+  connectedCallback() {
+    this.#setup();
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect();
+  }
+
+  #setup() {
+    this.#test = this.getAttribute('test');
+    if (!this.#test) {
+      console.warn('<f-when> requires test attribute');
+      return;
+    }
+
+    this.#store = this._store || findStore(this);
+    if (!this.#store) {
+      console.warn('<f-when> could not find store');
+      return;
+    }
+
+    // Save content as HTML string (simpler than DocumentFragment)
+    this.#templateHtml = this.innerHTML;
+    this.innerHTML = '';
+    
+    // Create container
+    this.#container = document.createElement('span');
+    this.#container.style.display = 'contents';
+    this.appendChild(this.#container);
+
+    this.#store.state.when('ready', () => {
+      this.#update();
+
+      // Observe for changes - debounced
+      let pending = false;
+      this.#observer = new MutationObserver(() => {
+        if (pending) return;
+        pending = true;
+        requestAnimationFrame(() => {
+          pending = false;
+          this.#update();
+        });
+      });
+
+      this.#observer.observe(this.#store, {
+        subtree: true,
+        childList: true,
+        characterData: true,
+        attributes: true
+      });
+    });
+  }
+
+  #update() {
+    const shouldShow = evaluate(this.#test, this.#store);
+
+    // Skip if result unchanged
+    if (shouldShow === this.#lastResult) return;
+    this.#lastResult = shouldShow;
+
+    if (shouldShow) {
+      this.#container.innerHTML = this.#templateHtml;
+      this.#showing = true;
+    } else {
+      this.#container.innerHTML = '';
+      this.#showing = false;
+    }
+  }
+}
+
+customElements.define('f-when', FWhen);
+
+/**
+ * FMatch - Switch-style conditional
+ * 
+ * @element f-match
+ * 
+ * @example
+ * <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>
+ */
+
+export class FMatch extends HTMLElement {
+  #container = null;
+  #cases = [];
+  #activeValue = null;
+  #observer = null;
+  #store = null;
+  #test = null;
+
+  connectedCallback() {
+    this.#setup();
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect();
+  }
+
+  #setup() {
+    this.#test = this.getAttribute('test');
+    if (!this.#test) {
+      console.warn('<f-match> requires test attribute');
+      return;
+    }
+
+    this.#store = this._store || findStore(this);
+    if (!this.#store) {
+      console.warn('<f-match> could not find store');
+      return;
+    }
+
+    // Collect cases before modifying DOM
+    this.#cases = Array.from(this.children).map(child => ({
+      value: child.getAttribute('value'),
+      isElse: child.tagName.toLowerCase() === 'f-else',
+      template: child.innerHTML
+    }));
+
+    // Clear and create container
+    this.innerHTML = '';
+    this.#container = document.createElement('span');
+    this.#container.style.display = 'contents';
+    this.appendChild(this.#container);
+
+    this.#store.state.when('ready', () => {
+      this.#update();
+
+      // Observe for changes - debounced
+      let pending = false;
+      this.#observer = new MutationObserver(() => {
+        if (pending) return;
+        pending = true;
+        requestAnimationFrame(() => {
+          pending = false;
+          this.#update();
+        });
+      });
+
+      this.#observer.observe(this.#store, {
+        subtree: true,
+        childList: true,
+        characterData: true,
+        attributes: true
+      });
+    });
+  }
+
+  #update() {
+    const node = this.#store.at(this.#test);
+    const value = node?.peek?.() ?? node?.value ?? '';
+
+    // Skip if same value
+    if (value === this.#activeValue) return;
+    this.#activeValue = value;
+
+    // Find matching case
+    let matched = this.#cases.find(c => !c.isElse && c.value == value);
+    if (!matched) {
+      matched = this.#cases.find(c => c.isElse);
+    }
+
+    // Render
+    this.#container.innerHTML = matched ? matched.template : '';
+  }
+}
+
+customElements.define('f-match', FMatch);
+
+// Marker elements
+class FCase extends HTMLElement {}
+class FElse extends HTMLElement {}
+
+customElements.define('f-case', FCase);
+customElements.define('f-else', FElse);
+
+export { FCase, FElse };
+

package/src/components/index.js

@@ -0,0 +1,10 @@
+/**
+ * Flarp Web Components
+ */
+
+export { default as FStore } from './FStore.js';
+export { default as FText } from './FText.js';
+export { default as FField } from './FField.js';
+export { default as FBind } from './FBind.js';
+export { default as FEach } from './FEach.js';
+export { default as FWhen, FMatch, FCase, FElse } from './FWhen.js';

package/src/core/Signal.js

@@ -0,0 +1,220 @@
+/**
+ * Signal - Minimal synchronous reactive primitive
+ * 
+ * The foundation of Flarp's reactivity system.
+ * Designed for explicit ownership, deterministic disposal,
+ * and embedding in larger systems.
+ */
+
+export default class Signal {
+
+  static #currentAccess = null;
+
+  #value;
+  #subscribers = new Set();
+  #disposables = new Set();
+  #disposed = false;
+
+  constructor(initialValue) {
+    this.#value = initialValue;
+  }
+
+  get value() {
+    this.#assertAlive();
+    if (Signal.#currentAccess) Signal.#currentAccess(this);
+    return this.#value;
+  }
+
+  set value(next) {
+    this.#assertAlive();
+    if (Object.is(next, this.#value)) return;
+    this.#value = next;
+    this.notify();
+  }
+
+  /**
+   * Read without triggering dependency tracking
+   */
+  peek() {
+    this.#assertAlive();
+    return this.#value;
+  }
+
+  /**
+   * Subscribe to changes
+   * @param {Function} fn - Callback receiving new value
+   * @param {boolean} autorun - Call immediately with current value
+   * @returns {Function} Unsubscribe function
+   */
+  subscribe(fn, autorun = true) {
+    this.#assertAlive();
+
+    if (typeof fn !== "function") {
+      throw new TypeError("Signal.subscribe: expected function");
+    }
+
+    this.#subscribers.add(fn);
+
+    if (autorun) {
+      this.#safeCall(fn, this.#value);
+    }
+
+    return () => this.unsubscribe(fn);
+  }
+
+  unsubscribe(fn) {
+    this.#subscribers.delete(fn);
+  }
+
+  /**
+   * Manually notify subscribers (for mutable data)
+   */
+  notify() {
+    this.#assertAlive();
+    for (const fn of [...this.#subscribers]) {
+      this.#safeCall(fn, this.#value);
+    }
+  }
+
+  /**
+   * Create derived signal from single parent
+   * @param {Function} fn - Transform function
+   * @returns {Signal} Child signal owned by this parent
+   */
+  map(fn) {
+    this.#assertAlive();
+
+    if (typeof fn !== "function") {
+      throw new TypeError("Signal.map: expected function");
+    }
+
+    const child = new Signal(fn(this.peek()));
+
+    const unsubscribe = this.subscribe((value) => {
+      child.value = fn(value);
+    }, false);
+
+    child.collect(unsubscribe);
+    this.collect(child);
+
+    return child;
+  }
+
+  /**
+   * Register disposables owned by this signal
+   */
+  collect(...items) {
+    this.#assertAlive();
+    for (const d of items.flat(Infinity)) {
+      if (d != null) this.#disposables.add(d);
+    }
+  }
+
+  /**
+   * Dispose this signal and all owned resources
+   */
+  dispose() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+
+    this.#subscribers.clear();
+
+    for (const d of this.#disposables) {
+      try {
+        if (typeof d === "function") d();
+        else if (typeof d?.dispose === "function") d.dispose();
+      } catch (err) {
+        console.error("Signal disposal error:", err);
+      }
+    }
+
+    this.#disposables.clear();
+  }
+
+  get disposed() {
+    return this.#disposed;
+  }
+
+  #safeCall(fn, value) {
+    try {
+      fn(value);
+    } catch (err) {
+      console.error("Signal subscriber error:", err);
+    }
+  }
+
+  #assertAlive() {
+    if (this.#disposed) {
+      throw new Error("Signal has been disposed");
+    }
+  }
+
+  /**
+   * Create derived signal with automatic dependency tracking
+   * @param {Function} fn - Computation function
+   * @returns {Signal} Derived signal
+   */
+  static derive(fn) {
+    if (typeof fn !== "function") {
+      throw new TypeError("Signal.derive: expected function");
+    }
+
+    const deps = new Set();
+    const derived = new Signal(undefined);
+    let computing = false;
+
+    const recompute = () => {
+      if (computing) return;
+      computing = true;
+
+      deps.clear();
+
+      const prev = Signal.#currentAccess;
+      Signal.#currentAccess = (signal) => deps.add(signal);
+
+      let next;
+      try {
+        next = fn();
+      } finally {
+        Signal.#currentAccess = prev;
+        computing = false;
+      }
+
+      derived.value = next;
+    };
+
+    recompute();
+
+    const subscriptions = new Set();
+
+    const resubscribe = () => {
+      for (const unsub of subscriptions) unsub();
+      subscriptions.clear();
+
+      for (const dep of deps) {
+        const unsub = dep.subscribe(recompute, false);
+        subscriptions.add(unsub);
+        dep.collect(derived);
+      }
+    };
+
+    resubscribe();
+
+    derived.collect(() => {
+      for (const unsub of subscriptions) unsub();
+      subscriptions.clear();
+    });
+
+    return derived;
+  }
+
+  /**
+   * Create a signal that combines multiple signals
+   * @param {Signal[]} signals - Source signals
+   * @param {Function} fn - Combiner function
+   * @returns {Signal} Combined signal
+   */
+  static combine(signals, fn) {
+    return Signal.derive(() => fn(...signals.map(s => s.value)));
+  }
+}

package/src/core/State.js

@@ -0,0 +1,168 @@
+/**
+ * State - Named state machine built on Signals
+ * 
+ * Solves the "ready event fires before listener attached" problem.
+ * 
+ * @example
+ * const state = new State();
+ * 
+ * // This works even if 'ready' is already true!
+ * state.when('ready', () => console.log('Ready!'));
+ * 
+ * // Later...
+ * state.set('ready');
+ * 
+ * // Check synchronously
+ * if (state.is('ready')) { ... }
+ * 
+ * // Await async
+ * await state.until('ready');
+ */
+
+import Signal from './Signal.js';
+
+export default class State {
+  #signals = new Map();
+  #disposed = false;
+
+  /**
+   * Get or create a signal for a named state
+   * @param {string} name - State name
+   * @returns {Signal<boolean>}
+   */
+  signal(name) {
+    this.#assertAlive();
+    
+    if (!this.#signals.has(name)) {
+      this.#signals.set(name, new Signal(false));
+    }
+    return this.#signals.get(name);
+  }
+
+  /**
+   * Set a state to true (or specific value)
+   * @param {string} name - State name
+   * @param {boolean} value - State value (default: true)
+   */
+  set(name, value = true) {
+    this.signal(name).value = Boolean(value);
+  }
+
+  /**
+   * Clear a state (set to false)
+   * @param {string} name - State name
+   */
+  clear(name) {
+    this.set(name, false);
+  }
+
+  /**
+   * Toggle a state
+   * @param {string} name - State name
+   * @returns {boolean} New value
+   */
+  toggle(name) {
+    const sig = this.signal(name);
+    sig.value = !sig.peek();
+    return sig.peek();
+  }
+
+  /**
+   * Check if a state is true
+   * @param {string} name - State name
+   * @returns {boolean}
+   */
+  is(name) {
+    return this.signal(name).peek();
+  }
+
+  /**
+   * React when state becomes true
+   * Fires immediately if already true, otherwise subscribes
+   * 
+   * @param {string} name - State name
+   * @param {Function} fn - Callback (no arguments)
+   * @returns {Function} Unsubscribe function
+   */
+  when(name, fn) {
+    this.#assertAlive();
+    
+    const sig = this.signal(name);
+    
+    // Already true? Fire immediately
+    if (sig.peek()) {
+      try { fn(); } catch (e) { console.error(e); }
+      return () => {}; // No-op unsubscribe
+    }
+    
+    // Subscribe for future
+    let fired = false;
+    return sig.subscribe(value => {
+      if (value && !fired) {
+        fired = true;
+        fn();
+      }
+    }, false);
+  }
+
+  /**
+   * React to any state change
+   * @param {string} name - State name
+   * @param {Function} fn - Callback receiving boolean value
+   * @returns {Function} Unsubscribe function
+   */
+  watch(name, fn) {
+    return this.signal(name).subscribe(fn);
+  }
+
+  /**
+   * Wait for state to become true
+   * Resolves immediately if already true
+   * 
+   * @param {string} name - State name
+   * @returns {Promise<void>}
+   */
+  until(name) {
+    if (this.is(name)) return Promise.resolve();
+    
+    return new Promise(resolve => {
+      const unsub = this.signal(name).subscribe(value => {
+        if (value) {
+          unsub();
+          resolve();
+        }
+      }, false);
+    });
+  }
+
+  /**
+   * Get all current state names and values
+   * @returns {Object}
+   */
+  snapshot() {
+    const result = {};
+    for (const [name, sig] of this.#signals) {
+      result[name] = sig.peek();
+    }
+    return result;
+  }
+
+  /**
+   * Dispose all state signals
+   */
+  dispose() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    
+    for (const sig of this.#signals.values()) {
+      sig.dispose();
+    }
+    this.#signals.clear();
+  }
+
+  #assertAlive() {
+    if (this.#disposed) {
+      throw new Error("State has been disposed");
+    }
+  }
+}

package/src/core/index.js

@@ -0,0 +1,6 @@
+/**
+ * Core - Reusable reactive primitives
+ */
+
+export { default as Signal } from './Signal.js';
+export { default as State } from './State.js';