lime-csr-js 0.1.4

package/src/conditionals.js

@@ -0,0 +1,153 @@
+/**
+ * @module conditionals
+ * @description Statically resolves <if>/<else> condition blocks in the DOM.
+ *
+ * <else> MODEL — a wrapper:
+ *   - <else></else> is a WRAPPER. <else/> or an empty self-close is FORBIDDEN;
+ *     the HTML5 parser doesn't treat it as a void element and swallows the
+ *     following content.
+ *   - Everything among <if>'s DIRECT children EXCEPT the <else> ELEMENT is the "then" group.
+ *   - <else>'s INSIDE (childNodes) is the "else" group.
+ *
+ *     <if is-gt="x" than="0">
+ *       <span>then content</span>    ← direct child other than <else> = then
+ *       <else>
+ *         <span>else content</span>  ← inside of <else> = else
+ *       </else>
+ *     </if>
+ *
+ * Other rules:
+ *   - <if>/<else> do NOT remain in the final DOM; only the winning content is placed.
+ *   - Processing is outer-to-inner; inner <if>s wait their turn until the outer one resolves.
+ *   - Reactivity (data-live) is NOT in this module — handled in bindings.js.
+ *   - Special parsing contexts like <table> TODO: may need a separate mechanism.
+ */
+
+import { getByPath } from './store.js';
+import { errors } from './errors.js';
+import { inLiveBlock } from './shared.js';
+
+/**
+ * Supported condition operators.
+ * A new operator = one line in this table; no other change needed.
+ *
+ * Left side: the operator attribute's value is a path — resolved via getByPath.
+ * Right side: raw string from the "than" or "to" attribute (except is-truthy).
+ *
+ * @type {Record<string, function(*, *=): boolean>}
+ */
+export const OPERATORS = {
+  'is-gt':     (left, right) => Number(left)  >   Number(right),
+  'is-lt':     (left, right) => Number(left)  <   Number(right),
+  'is-gte':    (left, right) => Number(left)  >=  Number(right),
+  'is-lte':    (left, right) => Number(left)  <=  Number(right),
+  'is-eq':     (left, right) => String(left)  === String(right),
+  'is-neq':    (left, right) => String(left)  !== String(right),
+  'is-truthy': (left)        => Boolean(left),
+};
+
+const OPERATOR_NAMES = Object.keys(OPERATORS);
+
+/**
+ * Evaluates an <if> element's condition against the context.
+ *
+ * @param {Element} ifEl    - The <if> element
+ * @param {Object}  context - Plain object for path resolution
+ * @returns {boolean}
+ */
+export function evalCondition(ifEl, context) {
+  const opName = OPERATOR_NAMES.find((op) => ifEl.hasAttribute(op));
+
+  if (!opName) {
+    const unknownOp = Array.from(ifEl.attributes).find((a) => a.name.startsWith('is-'));
+    if (unknownOp) {
+      errors.unknownOperator(unknownOp.name, OPERATOR_NAMES, ifEl);
+    } else {
+      errors.missingOperator(ifEl);
+    }
+    return false;
+  }
+
+  const path      = ifEl.getAttribute(opName);
+  const leftValue = getByPath(context, path);
+  const rightRaw  = ifEl.getAttribute('than') ?? ifEl.getAttribute('to') ?? '';
+
+  return Boolean(OPERATORS[opName](leftValue, rightRaw));
+}
+
+/**
+ * Evaluates a single <if> element; leaves the winning content in its place in the DOM.
+ *
+ * Then group : <if>'s DIRECT children — EXCEPT the <else> element.
+ * Else group : <else>'s childNodes.
+ *
+ * Tolerance: warns the user if another element follows <else>, but still
+ * works (anything after it is counted as then, regardless of position).
+ *
+ * @param {Element} ifEl    - The <if> element
+ * @param {Object}  context
+ * @returns {void}
+ */
+export function processIf(ifEl, context) {
+  const condition     = evalCondition(ifEl, context);
+  // replaceWith on a live NodeList is unsafe; copy first
+  const directChildren = Array.from(ifEl.childNodes);
+
+  // Find only the DIRECT child <else>; don't descend into grandchildren — parentage guarantee
+  const elseEl = directChildren.find(
+    (ch) => ch.nodeType === Node.ELEMENT_NODE && ch.tagName === 'ELSE',
+  ) ?? null;
+
+  // Tolerance: warn if an element node follows <else>, but still proceed
+  if (elseEl) {
+    const idxElse    = directChildren.indexOf(elseEl);
+    const afterElse  = directChildren
+      .slice(idxElse + 1)
+      .filter((ch) => ch.nodeType === Node.ELEMENT_NODE);
+    if (afterElse.length > 0) {
+      errors.elseAfterContent(ifEl);
+    }
+  }
+
+  // Then: all direct children other than the <else> element (position-independent)
+  const thenNodes = directChildren.filter((ch) => ch !== elseEl);
+  // Else: <else>'s inside; empty if there's no <else>
+  const elseNodes = elseEl ? Array.from(elseEl.childNodes) : [];
+
+  // Remove <if>, put the winner in its place (empty spread → element is deleted)
+  ifEl.replaceWith(...(condition ? thenNodes : elseNodes));
+}
+
+/**
+ * Processes every <if> element under root, outer-to-inner.
+ *
+ * Outer-to-inner: elements whose parentElement is not inside an <if> count as
+ * "outermost." The DOM changes after each pass; the loop continues until no
+ * <if> remains.
+ *
+ * @param {Element|DocumentFragment} root
+ * @param {Object}                   context
+ * @returns {void}
+ */
+export function processAllIfs(root, context) {
+  let candidates;
+
+  while ((candidates = Array.from(root.querySelectorAll('if'))).length > 0) {
+    // Outermost <if>s: no ancestor is an <if>, does not carry data-live, AND
+    // is not inside a not-yet-expanded <if data-live>/<for data-live> block.
+    // Ones carrying data-live are left to bindings-blocks.js (reactive tear-down/rebuild);
+    // ordinary <if>s INSIDE a live block are not processed early here, since
+    // they'll only get the correct (branch/item) context via renderFn's (render()) call.
+    const outermost = candidates.filter(
+      (el) =>
+        !el.parentElement?.closest('if') &&
+        !el.hasAttribute('data-live') &&
+        !inLiveBlock(el),
+    );
+    if (outermost.length === 0) break; // deadlock guard (also exits if only live-ifs remain)
+
+    for (const ifEl of outermost) {
+      processIf(ifEl, context);
+    }
+  }
+}

package/src/errors.js

@@ -0,0 +1,414 @@
+/**
+ * @module errors
+ * Dev-mode warning layer.
+ *
+ * Rules:
+ *   - When enabled: console.warn('[lime-csr] CODE: message', context?). Never throw — page must keep running.
+ *   - When disabled: complete silence. End users must not see console noise.
+ *   - This module imports NO other module — no circular dependency risk.
+ *
+ * Default: ON. Enabled by default for developer convenience; disable in production with setDevMode(false).
+ */
+
+/** @type {boolean} */
+let devMode = true;
+
+/**
+ * Enables or disables dev mode.
+ * @param {boolean} enabled
+ */
+export function setDevMode(enabled) {
+  devMode = Boolean(enabled);
+}
+
+/** @returns {boolean} */
+export function isDevMode() {
+  return devMode;
+}
+
+/**
+ * Shows a red error overlay in the bottom right corner of the page (dev mode only).
+ *
+ * @param {string} code
+ * @param {string} message
+ */
+function showOverlay(code, message) {
+  if (typeof document === 'undefined') return;
+  let container = document.getElementById('lime-csr-error-overlay-container');
+  if (!container) {
+    container = document.createElement('div');
+    container.id = 'lime-csr-error-overlay-container';
+    container.style.cssText = 'position:fixed;bottom:16px;right:16px;z-index:999999;max-width:350px;display:flex;flex-direction:column;gap:8px;font-family:sans-serif;font-size:13px;';
+    document.body.appendChild(container);
+  }
+
+  const el = document.createElement('div');
+  el.style.cssText = 'background:#f87171;color:#fff;padding:12px 16px;border-radius:6px;box-shadow:0 4px 12px rgba(0,0,0,0.15);display:flex;align-items:flex-start;justify-content:space-between;gap:12px;animation:lime-fade-in 0.2s ease;border-left:4px solid #b91c1c;';
+
+  const content = document.createElement('div');
+  const title = document.createElement('strong');
+  title.style.cssText = 'display:block;margin-bottom:4px;font-weight:bold;';
+  title.textContent = `[lime-csr] ${code}`;
+  const detail = document.createElement('span');
+  detail.style.cssText = 'opacity:0.95;line-height:1.4;';
+  detail.textContent = message;
+  content.append(title, detail);
+  el.appendChild(content);
+
+  const closeBtn = document.createElement('button');
+  closeBtn.textContent = '\u00d7';
+  closeBtn.style.cssText = 'background:none;border:none;color:#fff;font-size:18px;cursor:pointer;opacity:0.7;padding:0;line-height:1;font-weight:bold;';
+  closeBtn.onmouseover = () => { closeBtn.style.opacity = '1'; };
+  closeBtn.onmouseout = () => { closeBtn.style.opacity = '0.7'; };
+  closeBtn.onclick = () => {
+    el.remove();
+    if (container.childNodes.length === 0) {
+      container.remove();
+    }
+  };
+  el.appendChild(closeBtn);
+  container.appendChild(el);
+
+  if (!document.getElementById('lime-csr-overlay-style')) {
+    const style = document.createElement('style');
+    style.id = 'lime-csr-overlay-style';
+    style.textContent = '@keyframes lime-fade-in { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } }';
+    document.head.appendChild(style);
+  }
+}
+
+/**
+ * Primary warning function. Does nothing if dev mode is off.
+ *
+ * @param {string} code     - Error code (e.g. "PARTIAL_NOT_FOUND")
+ * @param {string} message  - Actionable description — "what's wrong, how to fix it"
+ * @param {*}     [context] - Additional context (element, path, name, etc.) — appended to console output
+ */
+export function warn(code, message, context) {
+  if (!devMode) return;
+  if (context !== undefined) {
+    console.warn(`[lime-csr] ${code}: ${message}`, context);
+  } else {
+    console.warn(`[lime-csr] ${code}: ${message}`);
+  }
+  showOverlay(code, message);
+}
+
+/**
+ * Known error scenario wrappers.
+ * Each one only calls warn() — no logic here, logic is in warn.
+ *
+ * @namespace
+ */
+export const errors = {
+  /** Unknown is-* operator on an <if>. */
+  unknownOperator(op, validOps, context) {
+    warn(
+      'UNKNOWN_OPERATOR',
+      `Unknown condition operator: "${op}". Valid operators: ${validOps.join(', ')}. ` +
+        `Use is-truthy, is-eq, is-gt, etc.`,
+      context,
+    );
+  },
+
+  /** No is-* operator found on an <if>. */
+  missingOperator(context) {
+    warn(
+      'MISSING_OPERATOR',
+      `No condition operator found on <if>. ` +
+        `Add at least one operator attribute: is-gt, is-lt, is-eq, is-truthy...`,
+      context,
+    );
+  },
+
+  /** <else> must be the last direct child of <if>. */
+  elseAfterContent(context) {
+    warn(
+      'ELSE_AFTER_CONTENT',
+      `<else> must be the last direct child of <if>; nodes after it were counted as then. ` +
+        `Move the <else>...</else> block to the end.`,
+      context,
+    );
+  },
+
+  /** Partial requested via <partial name="..."> was not found. */
+  partialNotFound(name, available, context) {
+    const list = available.length ? available.join(', ') : '(no registered partials)';
+    warn(
+      'PARTIAL_NOT_FOUND',
+      `Partial not found: "${name}". Registered partials: ${list}. ` +
+        `Is <template id="tpl-${name}"> defined?`,
+      context,
+    );
+  },
+
+  /** <partial> element is missing the "name" attribute. */
+  partialMissingName(context) {
+    warn(
+      'PARTIAL_MISSING_NAME',
+      `<partial> element is missing the "name" attribute. Use <partial name="..."></partial>.`,
+      context,
+    );
+  },
+
+  /** Recursive partial expansion reached maximum depth. */
+  partialDepthLimit(depth, context) {
+    warn(
+      'PARTIAL_DEPTH_LIMIT',
+      `Partial depth limit (${depth}) reached (possible infinite loop). ` +
+        `A partial may be calling itself directly or indirectly.`,
+      context,
+    );
+  },
+
+  /** Template requested via getTemplate / mount was not found in DOM. */
+  templateNotFound(name) {
+    warn(
+      'TEMPLATE_NOT_FOUND',
+      `Template not found: "tpl-${name}". ` +
+        `Is <template id="tpl-${name}"> present on the page?`,
+    );
+  },
+
+  /** <for> element is missing the "each" or "as" attribute. */
+  forMissingAttr(context) {
+    warn(
+      'FOR_MISSING_ATTR',
+      `<for> element is missing the "each" and/or "as" attribute. ` +
+        `Use <for each="array.path" as="item"></for>.`,
+      context,
+    );
+  },
+
+  /** <for each="..."> value is not an array. */
+  forNotArray(path, type, context) {
+    warn(
+      'FOR_NOT_ARRAY',
+      `<for each="${path}"> value must be an array; got: ${type}. ` +
+        `Is "${path}" an array in context or store?`,
+      context,
+    );
+  },
+
+  /** data-text attribute is present but its value is empty. */
+  bindingMissingPath(context) {
+    warn(
+      'BINDING_MISSING_PATH',
+      `data-text attribute is empty; a store path is required. ` +
+        `Use data-text="path.to.value".`,
+      context,
+    );
+  },
+
+  /** No matching data-x attribute found for the {x} placeholder. */
+  bindingMissingDataAttr(attrName, key, context) {
+    warn(
+      'BINDING_MISSING_DATA_ATTR',
+      `No data-${key} attribute found for {${key}} in "${attrName}"; binding skipped. ` +
+        `Add data-${key}="store.path" or remove the {${key}} placeholder.`,
+      context,
+    );
+  },
+
+  /** A reactive {x}/data-x binding targets an event-handler attribute like onclick/onerror. */
+  unsafeEventAttr(attrName, context) {
+    warn(
+      'UNSAFE_EVENT_ATTR',
+      `"${attrName}" is an event-handler attribute; reactive data cannot bind to it. ` +
+        `Use data-on-{event} for events instead (see README).`,
+      context,
+    );
+  },
+
+  /** No valid condition operator found on <if data-live>. */
+  liveIfMissingOperator(context) {
+    warn(
+      'LIVE_IF_MISSING_OP',
+      `<if data-live>: no valid condition operator found. ` +
+        `Add one: is-gt, is-lt, is-eq, is-truthy, etc.`,
+      context,
+    );
+  },
+
+  /** Render pipeline reached its maximum iteration limit. */
+  pipelineDepthLimit(maxIter, context) {
+    warn(
+      'PIPELINE_DEPTH_LIMIT',
+      `Render pipeline reached the ${maxIter} iteration limit (possible infinite loop). Stopping. ` +
+        `Is a partial calling itself?`,
+      context,
+    );
+  },
+
+  /** Template requested via mount() was not found. */
+  mountTemplateNotFound(name, available, context) {
+    const list = available.length ? available.join(', ') : '(no registered templates)';
+    warn(
+      'MOUNT_TEMPLATE_NOT_FOUND',
+      `mount(): template "${name}" not found. Registered templates: ${list}. ` +
+        `Is <template id="tpl-${name}"> defined?`,
+      context,
+    );
+  },
+
+  // ── Reactive <for data-live> ────────────────────────────────────────────────
+
+  /** Reactive <for data-live> is missing the "key" attribute. */
+  missingKey(templateName) {
+    warn(
+      'FOR_MISSING_KEY',
+      `Reactive <for data-live>: missing "key" attribute. ` +
+        `Add a key for efficient DOM updates. (template: ${templateName ?? '?'})`,
+    );
+  },
+
+  /** Same key used on more than one element in a reactive <for data-live>. */
+  duplicateKey(keyVal, templateName) {
+    warn(
+      'FOR_DUPLICATE_KEY',
+      `Reactive <for data-live>: key "${keyVal}" appears on more than one element; ` +
+        `keys must be unique. (template: ${templateName ?? '?'})`,
+    );
+  },
+
+  /** data-model attribute present but empty. */
+  modelMissingPath(context) {
+    warn(
+      'MODEL_MISSING_PATH',
+      `data-model attribute is empty; a store path is required. ` +
+        `Use data-model="path.to.value".`,
+      context,
+    );
+  },
+
+  /** Custom element written inside <table> — HTML parser will foster-parent it outside. */
+  tableFosterParenting(templateName) {
+    warn(
+      'TABLE_FOSTER_PARENTING',
+      `<if>/<for>/<partial> cannot be used inside <table> — the HTML parser moves them outside. ` +
+        `Solution: move the condition/loop outside the <table>, or treat the tbody as a partial. ` +
+        `(template: ${templateName ?? '?'})`,
+    );
+  },
+
+  /** data-show attribute present but empty. */
+  showMissingPath(context) {
+    warn(
+      'SHOW_MISSING_PATH',
+      `data-show attribute is empty; a store path is required. ` +
+        `Use data-show="path.to.value".`,
+      context,
+    );
+  },
+
+  /** An unsupported event type was used with data-on-{event}. */
+  unknownEvent(eventName, validEvents, context) {
+    warn(
+      'UNKNOWN_EVENT',
+      `Unsupported event type: "data-on-${eventName}". Valid types: ` +
+        `${validEvents.map((e) => `data-on-${e}`).join(', ')}.`,
+      context,
+    );
+  },
+
+  /** data-on-{event} points to a handler name not in the handlers dictionary. */
+  handlerNotFound(name, available, context) {
+    const list = available.length ? available.join(', ') : '(no registered handlers)';
+    warn(
+      'HANDLER_NOT_FOUND',
+      `Handler not found: "${name}". Registered handlers: ${list}. ` +
+        `Is "${name}" defined in the handlers object passed to mount()?`,
+      context,
+    );
+  },
+
+  // ── Phase 2 additions ───────────────────────────────────────────────────────
+
+  /**
+   * A reserved name (text, model, show, live, ref, diff, or on-* prefix) was used
+   * as a placeholder name in {x}/data-x bindings.
+   */
+  reservedAttrName(name, context) {
+    warn(
+      'RESERVED_ATTR_NAME',
+      `"${name}" is reserved by lime-csr and cannot be used as a {x}/data-x placeholder. ` +
+        `Reserved names: text, model, show, live, ref, diff, and any name starting with "on-". ` +
+        `Rename the placeholder.`,
+      context,
+    );
+  },
+
+  /**
+   * data-model path contains a numeric index segment (e.g. "items.0.name").
+   * Path drift: after array mutation the index points to the wrong item.
+   */
+  indexedModelPath(path, context) {
+    warn(
+      'INDEXED_MODEL_PATH',
+      `data-model="${path}" contains a numeric index (e.g. items.0.name). ` +
+        `This is unsafe: if the array is mutated, the path drifts to the wrong item. ` +
+        `Use a reactive <for data-live key=...> loop and bind to the loop variable instead.`,
+      context,
+    );
+  },
+
+  /**
+   * store.set() was called on a path managed by store.computed().
+   * The manual value will be overwritten on the next dep change.
+   */
+  computedManualSet(path) {
+    warn(
+      'COMPUTED_MANUAL_SET',
+      `Path "${path}" is managed by store.computed(). ` +
+        `Manual store.set() will be overwritten on the next dep change. ` +
+        `Use store.computed() or choose a different path.`,
+    );
+  },
+
+  /**
+   * store.set() received the same object/array reference already stored.
+   * In-place mutation: Object.is() returns true, so no subscriber fires.
+   */
+  inPlaceMutation(path) {
+    warn(
+      'IN_PLACE_MUTATION',
+      `store.set("${path}", value): value is the SAME reference as the stored object/array. ` +
+        `In-place mutation detected — subscribers will NOT fire. ` +
+        `Pass a new reference, e.g. store.set("${path}", [...arr]) or {...obj}.`,
+    );
+  },
+
+  // ── Phase 3 additions ───────────────────────────────────────────────────────
+
+  /** <for data-live data-diff="..."> used a value outside simple/lcs/replace. */
+  unknownDiffStrategy(value, templateName) {
+    warn(
+      'UNKNOWN_DIFF_STRATEGY',
+      `<for data-live>: unknown data-diff value "${value}". Valid values: ` +
+        `simple, lcs, replace (or omit the attribute). Falling back to "simple". ` +
+        `(template: ${templateName ?? '?'})`,
+    );
+  },
+
+  /** data-after on <if>/<for> points to a handler name not in the handlers dictionary. */
+  blockAfterNotFound(name, available, context) {
+    const list = available.length ? available.join(', ') : '(no registered handlers)';
+    warn(
+      'BLOCK_AFTER_NOT_FOUND',
+      `data-after handler not found: "${name}". Registered handlers: ${list}. ` +
+        `Is "${name}" defined in the handlers object passed to mount()?`,
+      context,
+    );
+  },
+
+  /** data-before on <if>/<for> points to a handler name not in the handlers dictionary. */
+  blockBeforeNotFound(name, available, context) {
+    const list = available.length ? available.join(', ') : '(no registered handlers)';
+    warn(
+      'BLOCK_BEFORE_NOT_FOUND',
+      `data-before handler not found: "${name}". Registered handlers: ${list}. ` +
+        `Is "${name}" defined in the handlers object passed to mount()?`,
+      context,
+    );
+  },
+};