lime-csr-js 0.1.4

package/src/bindings-model.js

@@ -0,0 +1,262 @@
+/**
+ * @module bindings-model
+ * Two-way form binding — `data-model="path"`.
+ *
+ * WHAT IT DOES
+ *   <input data-model="user.name">
+ *   - DOM to state: on element event (see "EVENT SELECTION"), store.set(path, ...).
+ *   - State to DOM: store.subscribe on path change, updates element value.
+ *   Both directions — the read-write counterpart of data-text's "read-only".
+ *   NO EVAL: path is a fixed string, no expression is executed; only
+ *   getByPath/store API is used (see store.js).
+ *
+ * SUPPORTED INPUT TYPES (see classify()):
+ *   - text/textarea/email/password/... (default) → el.value, 'input' event.
+ *   - number/range → el.value read as Number(), 'input' event.
+ *   - checkbox → el.checked (boolean), 'change' event.
+ *   - radio → group sharing the same data-model path; only the checked
+ *     radio's value is written to state; state change makes the matching radio
+ *     checked (see "RADIO GROUPS"), 'change' event.
+ *   - select (single) → el.value, 'change' event.
+ *   - select[multiple] → array of selected option values, 'change' event.
+ *
+ * NUMERIC INPUT DECISION (number/range):
+ *   Read value is converted via Number() (stored as number in state — so
+ *   comparisons with is-gt etc. work directly). Exception: if the field is
+ *   empty or Number() returns NaN (user typing "-" or "1." etc.), the RAW
+ *   STRING is stored — otherwise data would silently disappear (jump to NaN
+ *   or 0).
+ *
+ * LOOP GUARD (write ↔ read):
+ *   User types → store.set → subscribe fires → element updated.
+ *   If the new value equals the element's current value, the write is skipped
+ *   (see write() functions) — otherwise cursor position (input/textarea)
+ *   could reset. Since store.set's own subscribe trigger always has
+ *   "new value == element's current value", this in practice COMPLETELY prevents
+ *   unnecessary writes (and therefore cursor jumps).
+ *
+ * RADIO GROUPS:
+ *   input[type=radio][data-model="x"] may share the same path across multiple
+ *   elements (a group). The group gets ONE subscribe (not one per element) —
+ *   when state changes, every radio's checked is updated to match its value.
+ *   Each radio still has its own 'change' listener (writes only when checked).
+ *
+ * OUT OF SCOPE (same pattern as bindings.js):
+ *   data-model inside an unexpanded <if data-live>/<for data-live> block is
+ *   NOT bound here — that content is bound only by renderFn (render()) with
+ *   the correct dal/element context. Otherwise, on branch change, the old
+ *   subscription/listener cannot be cancelled → leak.
+ *
+ * data-model + data-on-input ON SAME ELEMENT (2h):
+ *   When both attributes are on the same element, data-model runs FIRST.
+ *   This order is enforced in index.js (setupModelBindings before event bindings).
+ *   Result: the model handler fires before any data-on-input handler, so the
+ *   store is updated by the time the application handler runs.
+ *
+ * INDEXED PATH WARNING (2a — T1 fix):
+ *   If data-model path contains a numeric index segment (e.g. "items.0.name"),
+ *   a dev-mode warning is issued: after array mutation the path drifts and
+ *   points to the wrong item. Use a reactive <for data-live key=...> loop instead.
+ */
+
+import { errors } from './errors.js';
+import { inLiveBlock } from './shared.js';
+
+const MODEL_ATTR = 'data-model';
+
+// Detect paths like "items.0.name" or "list.2" (numeric segment anywhere)
+const INDEXED_PATH_RE = /(?:^|\.)\d+(?:\.|$)/;
+
+
+
+/**
+ * Determines the element's data-model kind.
+ *
+ * @param {Element} el
+ * @returns {'checkbox'|'radio'|'select-multiple'|'select-single'|'number'|'text'}
+ */
+function classify(el) {
+  if (el.tagName === 'SELECT') return el.multiple ? 'select-multiple' : 'select-single';
+  if (el.tagName === 'TEXTAREA') return 'text';
+  const type = (el.getAttribute('type') || 'text').toLowerCase();
+  if (type === 'checkbox') return 'checkbox';
+  if (type === 'radio') return 'radio';
+  if (type === 'number' || type === 'range') return 'number';
+  return 'text';
+}
+
+/**
+ * For each input kind: which event to listen for, how to read from the DOM,
+ * how to write to the DOM (skip if same value — loop/cursor protection).
+ *
+ * @type {Object<string, { event: string, read: function(Element): *, write: function(Element, *): void }>}
+ */
+const KIND_HANDLERS = {
+  text: {
+    event: 'input',
+    read: (el) => el.value,
+    write: (el, val) => {
+      const next = val == null ? '' : String(val);
+      if (el.value === next) return;
+      el.value = next;
+    },
+  },
+  number: {
+    event: 'input',
+    read: (el) => {
+      const raw = el.value;
+      if (raw === '') return '';
+      const n = Number(raw);
+      return Number.isNaN(n) ? raw : n; // invalid/partial input → raw string (no data loss)
+    },
+    write: (el, val) => {
+      const next = val == null ? '' : String(val);
+      if (el.value === next) return;
+      el.value = next;
+    },
+  },
+  checkbox: {
+    event: 'change',
+    read: (el) => el.checked,
+    write: (el, val) => {
+      const next = Boolean(val);
+      if (el.checked === next) return;
+      el.checked = next;
+    },
+  },
+  'select-single': {
+    event: 'change',
+    read: (el) => el.value,
+    write: (el, val) => {
+      const next = val == null ? '' : String(val);
+      if (el.value === next) return;
+      el.value = next;
+    },
+  },
+  'select-multiple': {
+    event: 'change',
+    read: (el) => Array.from(el.selectedOptions).map((opt) => opt.value),
+    write: (el, val) => {
+      const arr = Array.isArray(val) ? val.map(String) : [];
+      for (const opt of el.options) {
+        const shouldSelect = arr.includes(opt.value);
+        if (opt.selected !== shouldSelect) opt.selected = shouldSelect;
+      }
+    },
+  },
+};
+
+/**
+ * Binds a single (non-radio) data-model element.
+ *
+ * @param {Element} el
+ * @param {import('./store.js').Store} store
+ * @returns {function(): void} cleanup
+ */
+function bindElement(el, store) {
+  const path = el.getAttribute(MODEL_ATTR);
+  const handler = KIND_HANDLERS[classify(el)];
+
+  // 2a T1: warn if path contains numeric index (path drift risk)
+  if (INDEXED_PATH_RE.test(path)) {
+    errors.indexedModelPath(path, el);
+  }
+
+  handler.write(el, store.get(path)); // initial value: state → DOM
+
+  // 2h: data-model handler runs FIRST (before data-on-input handlers)
+  const onEvent = () => { store.set(path, handler.read(el)); }; // DOM → state
+  el.addEventListener(handler.event, onEvent);
+
+  const unsubscribe = store.subscribe(path, (val) => handler.write(el, val)); // state → DOM
+
+  return function cleanup() {
+    el.removeEventListener(handler.event, onEvent);
+    unsubscribe();
+  };
+}
+
+/**
+ * Binds a radio group sharing the same path with a SINGLE subscription.
+ *
+ * @param {string}    path
+ * @param {Element[]} radios
+ * @param {import('./store.js').Store} store
+ * @returns {function(): void} cleanup
+ */
+function bindRadioGroup(path, radios, store) {
+  const applyStoreValue = (val) => {
+    const str = val == null ? '' : String(val);
+    for (const radio of radios) {
+      const next = radio.value === str;
+      if (radio.checked !== next) radio.checked = next;
+    }
+  };
+
+  applyStoreValue(store.get(path)); // initial value: state → DOM
+
+  const listeners = radios.map((radio) => {
+    const onChange = () => { if (radio.checked) store.set(path, radio.value); };
+    radio.addEventListener('change', onChange);
+    return { radio, onChange };
+  });
+
+  const unsubscribe = store.subscribe(path, applyStoreValue); // state → DOM
+
+  return function cleanup() {
+    for (const { radio, onChange } of listeners) radio.removeEventListener('change', onChange);
+    unsubscribe();
+  };
+}
+
+/**
+ * Two-way binds every [data-model] element under root to the store.
+ * Opens subscriptions + event listeners; the returned cleanup() cancels all of them.
+ *
+ * @param {Element|DocumentFragment} root
+ * @param {import('./store.js').Store} store
+ * @returns {function(): void} cleanup
+ */
+export function setupModelBindings(root, store) {
+  const cleanups = [];
+
+  // Elements inside <if data-live>/<for data-live> are bound separately by
+  // renderFn; if we processed them here, the old subscription/listener could
+  // not be cancelled when the branch/block changes → leak.
+  const elements = [
+    ...(root.nodeType === Node.ELEMENT_NODE && root.hasAttribute?.(MODEL_ATTR) && !inLiveBlock(root)
+      ? [root]
+      : []),
+    ...Array.from(root.querySelectorAll(`[${MODEL_ATTR}]`)).filter((el) => !inLiveBlock(el)),
+  ];
+
+  const radioGroups = new Map(); // path → Element[]
+  const others = [];
+
+  for (const el of elements) {
+    const path = el.getAttribute(MODEL_ATTR);
+    if (!path) {
+      errors.modelMissingPath(el);
+      continue;
+    }
+    if (classify(el) === 'radio') {
+      if (!radioGroups.has(path)) radioGroups.set(path, []);
+      radioGroups.get(path).push(el);
+    } else {
+      others.push(el);
+    }
+  }
+
+  for (const el of others) {
+    cleanups.push(bindElement(el, store));
+  }
+
+  for (const [path, radios] of radioGroups) {
+    cleanups.push(bindRadioGroup(path, radios, store));
+  }
+
+  return function cleanup() {
+    for (const unsub of cleanups) unsub();
+    cleanups.length = 0; // guard against double cleanup calls
+  };
+}

package/src/bindings-show.js

@@ -0,0 +1,97 @@
+/**
+ * @module bindings-show
+ * Reactive visibility toggle — `data-show="path"` (the `x-show` counterpart).
+ *
+ * WHAT IT DOES
+ *   <div data-show="isModalOpen">...</div>
+ *   The element is visible if the store path is truthy; `display:none` if falsy.
+ *   NO EVAL — path is a fixed string, the value is interpreted only via
+ *   `Boolean()` (same logic as the is-truthy operator).
+ *
+ * DIFFERENCE FROM `<if data-live>` (CRITICAL):
+ *   `<if data-live>` COMPLETELY REMOVES the branch from the DOM and rebuilds
+ *   it when the condition changes — input value/scroll/animation state/DOM
+ *   identity are LOST. `data-show`, on the other hand, NEVER REMOVES the
+ *   element from the DOM; it only hides/shows it via CSS `display` — the
+ *   element keeps living (see the "Two-way binding" and "Condition" sections
+ *   in README). This is the right tool for modals/accordions/tabs — anything
+ *   needing CSS transitions or preserved form state.
+ *
+ * PRESERVING THE ORIGINAL display VALUE (design decision #1):
+ *   A fixed `"block"` is NOT assigned when hiding — this would break elements
+ *   with a `display:flex`/`grid`/`inline-block` CSS rule (dropping a flex
+ *   container down to `block`). Instead: the element's inline `style.display`
+ *   value AT SETUP TIME (`originalDisplay`) is captured ONCE; the value
+ *   written to the DOM in the "show" state is ALWAYS this original value —
+ *   so CSS's own (stylesheet-derived) display rule is restored as-is. In the
+ *   "hide" state, `display:none` is assigned as an inline style (overriding
+ *   everything in CSS — required for hiding to be guaranteed).
+ *
+ * NO FOUC (design decision #2):
+ *   setupShowBindings runs in index.js's render() flow BEFORE the fragment is
+ *   added to the DOM (before mount()'s `target.appendChild` call). So the
+ *   initial state is applied correctly from the start, with no
+ *   "flash of visible content, then disappear" (the fragment is already
+ *   invisible/detached while being hidden).
+ *
+ * ALWAYS REACTIVE (design decision #3):
+ *   `data-*` present = reactive (existing project convention). Anyone wanting
+ *   static/one-time hiding already writes plain CSS ("display:none" or a
+ *   class) — no separate "static data-show" variant is needed.
+ *
+ * OUT OF SCOPE (same pattern as bindings.js/bindings-model.js):
+ *   data-show elements INSIDE a not-yet-expanded <if data-live>/<for
+ *   data-live> block are NOT bound here — that content is bound only by
+ *   renderFn's (render()) call, in its own (correct) branch/item context.
+ */
+
+import { errors } from './errors.js';
+import { inLiveBlock } from './shared.js';
+
+const SHOW_ATTR = 'data-show';
+
+
+
+/**
+ * Reactively binds every [data-show] element under root to the store.
+ * Opens subscriptions; the returned cleanup() cancels all of them.
+ *
+ * @param {Element|DocumentFragment} root
+ * @param {import('./store.js').Store} store
+ * @returns {function(): void} cleanup
+ */
+export function setupShowBindings(root, store) {
+  const cleanups = [];
+
+  const elements = [
+    ...(root.nodeType === Node.ELEMENT_NODE && root.hasAttribute?.(SHOW_ATTR) && !inLiveBlock(root)
+      ? [root]
+      : []),
+    ...Array.from(root.querySelectorAll(`[${SHOW_ATTR}]`)).filter((el) => !inLiveBlock(el)),
+  ];
+
+  for (const el of elements) {
+    const path = el.getAttribute(SHOW_ATTR);
+    if (!path) {
+      errors.showMissingPath(el);
+      continue;
+    }
+
+    // Capture ONCE: the "original" inline display, unaffected by any toggle.
+    // The "show" state always returns to THIS — CSS's own display rule isn't broken.
+    const originalDisplay = el.style.display;
+
+    const apply = (val) => {
+      el.style.display = val ? originalDisplay : 'none';
+    };
+
+    apply(store.get(path)); // initial state — before the fragment is added to the DOM (no FOUC)
+
+    cleanups.push(store.subscribe(path, apply));
+  }
+
+  return function cleanup() {
+    for (const unsub of cleanups) unsub();
+    cleanups.length = 0; // guard against double cleanup calls
+  };
+}

package/src/bindings.js

@@ -0,0 +1,240 @@
+/**
+ * @module bindings
+ * Reactive data-text (text) + {x}/data-x (attribute) bindings.
+ *
+ * SCOPE — THIS MODULE:
+ *   - data-text="path"            → watch store, update el.textContent.
+ *   - href="/u/{x}" data-x="p"   → template + watch store, update attribute.
+ *
+ * OUT OF SCOPE — next step (bindings-blocks.js / mount.js):
+ *   Reactive block reactivity (<if data-live>, reactive <for>). These
+ *   require tear-down/rebuild + inner binding cleanup, so handled separately.
+ *
+ * CORE RULE:
+ *   - No data-*: static — template.js already resolved it, this module skips it.
+ *   - Has data-*: reactive — updates when state changes.
+ *   - Reactive data comes ONLY from the store; context is not carried here.
+ *
+ * SECURITY NOTE:
+ *   - el.textContent: does not parse HTML → escapeHtml NOT needed (written as text).
+ *   - el.setAttribute: DOM API HTML-encodes itself → safeAttr is WRONG
+ *     (safeAttr() + setAttribute() = double-encoding: "&amp;" → "&amp;amp;").
+ *     Therefore setAttribute receives the RAW value.
+ *   - URL attributes: checked with utils.isSafeUrlProtocol() before setAttribute
+ *     (shared whitelist with utils.js).
+ *   - on* (onclick, onerror, ...) attributes never receive reactive data:
+ *     browsers actually execute event-handler attributes set via setAttribute;
+ *     this would violate the "no JS execution from templates" principle.
+ *
+ * RESERVED PLACEHOLDER NAMES (2b):
+ *   The following names CANNOT be used as {x} placeholders in attribute templates
+ *   because lime-csr uses data-{name} for its own engine attributes:
+ *   text, model, show, live, ref, diff — and any name starting with "on-".
+ *   Detected in setupAttrBindings; errors.reservedAttrName is issued.
+ */
+
+
+import { errors } from './errors.js';
+import { isSafeUrlProtocol } from './utils.js';
+import { inLiveBlock } from './shared.js';
+
+// URL attributes: protocol check required before assignment.
+const URL_ATTRS = new Set(['href', 'src', 'action', 'formaction', 'data', 'cite', 'poster', 'ping']);
+
+// Event-handler attributes: reactive binding completely refused.
+const EVENT_ATTR_PATTERN = /^on/i;
+
+// Reactive attribute placeholder: {key}  (different syntax from template.js's ${path})
+const ATTR_PLACEHOLDER = /\{([^}]+)\}/g;
+
+// Reserved placeholder names: engine uses data-{name} for its own attributes.
+// Also blocks any name starting with "on-" (would conflict with data-on-{event}).
+const RESERVED_NAMES = new Set(['text', 'model', 'show', 'live', 'ref', 'diff']);
+function isReservedName(name) {
+  return RESERVED_NAMES.has(name) || name.startsWith('on-');
+}
+
+let refCounter = 0;
+function nextRef() { return `lcsr-${++refCounter}`; }
+
+/**
+ * Binds every [data-text] element under root to the store.
+ * textContent tracks state, not a static value.
+ *
+ * @param {Element|DocumentFragment} root
+ * @param {import('./store.js').Store} store
+ * @returns {Array<function(): void>} list of unsubscribe functions
+ */
+function setupTextBindings(root, store) {
+  const cleanups = [];
+
+  for (const el of root.querySelectorAll('[data-text]')) {
+    // data-text inside <if data-live> and <for data-live> is bound by renderFn.
+    // If we bound it here, the old subscription couldn't be cancelled when the
+    // branch/block changes → leak.
+    if (inLiveBlock(el)) continue;
+
+    const path = el.getAttribute('data-text');
+
+    if (!path) {
+      errors.bindingMissingPath(el);
+      continue;
+    }
+
+    // Write the initial value immediately.
+    // textContent does not parse HTML → escapeHtml is not needed.
+    el.textContent = store.get(path) ?? '';
+
+    cleanups.push(
+      store.subscribe(path, (val) => {
+        el.textContent = val ?? '';
+      }),
+    );
+  }
+
+  return cleanups;
+}
+
+/**
+ * Finds attributes under root that contain an {x} placeholder; reads the
+ * store path from the matching data-x attribute and binds it reactively.
+ *
+ * Template storage: the original attribute value ("/u/{handle}") is kept in
+ * JS. On every store change, the template is re-filled from scratch — not
+ * find-and-replace.
+ *
+ * The consumed data-x attributes are removed from the DOM once binding is set
+ * up (clean output). The data-ref handle stays in the DOM for debugging + cleanup.
+ *
+ * @param {Element|DocumentFragment} root
+ * @param {import('./store.js').Store} store
+ * @returns {Array<function(): void>} list of unsubscribe functions
+ */
+function setupAttrBindings(root, store) {
+  const cleanups = [];
+
+  // Include root itself in the scan if it's an Element; a DocumentFragment has no attributes.
+  // Elements inside <if data-live> and <for data-live> are bound separately by
+  // renderFn; if we processed them here, the old subscriptions couldn't be
+  // cancelled when the branch/block changes → leak.
+
+  const elements = [
+    ...(root.nodeType === Node.ELEMENT_NODE && !inLiveBlock(root) ? [root] : []),
+    ...Array.from(root.querySelectorAll('*')).filter((el) => !inLiveBlock(el)),
+  ];
+
+  for (const el of elements) {
+    const attrs = Array.from(el.attributes);
+
+    // Collect the reactive attribute bindings for this element
+    const boundAttrs = []; // { attrName, template, bindings: {key → storePath} }
+
+    for (const attr of attrs) {
+      // data-* attributes are a source, not a target; skip
+      if (attr.name.startsWith('data-')) continue;
+
+      ATTR_PLACEHOLDER.lastIndex = 0;
+      if (!ATTR_PLACEHOLDER.test(attr.value)) continue;
+
+      // onclick/onerror/... : reactive data is never bound to an event handler.
+      if (EVENT_ATTR_PATTERN.test(attr.name)) {
+        errors.unsafeEventAttr(attr.name, el);
+        continue;
+      }
+
+      const template = attr.value;
+      const bindings = {}; // {key} → store path
+      let allResolved = true;
+
+      for (const [, key] of template.matchAll(/\{([^}]+)\}/g)) {
+        if (key in bindings) continue; // same key may appear more than once
+
+        // 2b: reserved name check
+        if (isReservedName(key)) {
+          errors.reservedAttrName(key, el);
+          allResolved = false;
+          break;
+        }
+
+        const storePath = el.getAttribute(`data-${key}`);
+        if (!storePath) {
+          errors.bindingMissingDataAttr(attr.name, key, el);
+          allResolved = false;
+          break;
+        }
+        bindings[key] = storePath;
+      }
+
+      if (allResolved && Object.keys(bindings).length > 0) {
+        boundAttrs.push({ attrName: attr.name, template, bindings });
+      }
+    }
+
+    if (boundAttrs.length === 0) continue;
+
+    // Identification / debug handle — stays in the DOM so updates from the
+    // store can find the correct element.
+    if (!el.dataset.ref) el.dataset.ref = nextRef();
+
+    // Remove the consumed data-x attributes from the DOM (data-ref stays).
+    const usedKeys = new Set(
+      boundAttrs.flatMap(({ bindings: b }) => Object.keys(b)),
+    );
+    for (const key of usedKeys) el.removeAttribute(`data-${key}`);
+
+    // Update function + subscription for each attribute
+    for (const { attrName, template, bindings } of boundAttrs) {
+      // Re-fills the template from scratch with current store values — not find-and-replace.
+      const resolve = () => {
+        let resolved = template.replace(/\{([^}]+)\}/g, (_, key) =>
+          String(store.get(bindings[key]) ?? ''),
+        );
+
+        // URL attribute: block dangerous protocols like javascript:, data:.
+        // NOTE: setAttribute does its own HTML-encoding → the RAW value is given.
+        if (URL_ATTRS.has(attrName)) {
+          resolved = isSafeUrlProtocol(resolved) ? resolved : '';
+        }
+
+        el.setAttribute(attrName, resolved);
+      };
+
+      resolve(); // initial value
+
+      // Subscribe to every unique store path in the template.
+      // The template is re-resolved FROM SCRATCH when any of them changes.
+      const uniquePaths = [...new Set(Object.values(bindings))];
+      for (const path of uniquePaths) {
+        cleanups.push(store.subscribe(path, resolve));
+      }
+    }
+  }
+
+  return cleanups;
+}
+
+/**
+ * Sets up every reactive binding (data-text + {x}/data-x) under root.
+ * Subscriptions are opened; calling the returned cleanup() cancels all of them.
+ *
+ * Usage:
+ *   const cleanup = setupBindings(document.body, store);
+ *   // ... when the component unmounts:
+ *   cleanup(); // prevents a memory leak
+ *
+ * @param {Element|DocumentFragment} root
+ * @param {import('./store.js').Store} store
+ * @returns {function(): void} cleanup — cancels all subscriptions
+ */
+export function setupBindings(root, store) {
+  const cleanups = [
+    ...setupTextBindings(root, store),
+    ...setupAttrBindings(root, store),
+  ];
+
+  return function cleanup() {
+    for (const unsub of cleanups) unsub();
+    // Empty the list: guard against double cleanup calls
+    cleanups.length = 0;
+  };
+}