@faqir-ui/core 1.0.0

package/dist/plugins/faqir-collapse.js

@@ -0,0 +1,110 @@
+// @ui:plugin faqir-collapse
+// @ui:provides l-collapse
+/**
+ * faqir-collapse — height auto-animation for a boolean expression. [0.4-11 · §A5]
+ *
+ *   <div l-collapse="open"> … </div>
+ *
+ * When the bound expression is truthy the element animates from 0 → its natural
+ * height and settles at `height: auto`; when falsy it animates back to 0 and is
+ * hidden. Honors `prefers-reduced-motion` (snaps, no animation) and leaves NO
+ * inline `height` residue in either resting state — so content stays responsive.
+ *
+ * Self-registers via `Faqir.plugin` when a global `Faqir` is present (load it
+ * after faqir-core), and is also exported for bundlers/tests. Zero dependencies,
+ * ≤ 2 KB gzip. State it manipulates is inline style only — the DOM contract's
+ * `data-*` attributes are untouched.
+ */
+(function () {
+  "use strict";
+
+  function prefersReducedMotion() {
+    return (
+      typeof window !== "undefined" &&
+      typeof window.matchMedia === "function" &&
+      window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    );
+  }
+
+  // Settle on transitionend, or a timeout fallback so we never hang when the
+  // height does not actually change or the event is missed.
+  function whenSettled(el, cb) {
+    var done = false;
+    function finish(e) {
+      if (e && e.target !== el) return;
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      el.removeEventListener("transitionend", finish);
+      cb();
+    }
+    el.addEventListener("transitionend", finish);
+    var timer = setTimeout(finish, 400);
+  }
+
+  // Reset every inline property this plugin owns → no height/overflow/transition
+  // residue in a resting state.
+  function clearInline(el) {
+    el.style.height = "";
+    el.style.overflow = "";
+    el.style.transition = "";
+  }
+
+  function install(Faqir) {
+    Faqir.directive("collapse", function (el, dir, scope) {
+      var open = null; // unknown until the first effect run
+
+      Faqir.effect(function () {
+        var next = !!Faqir.evaluate(dir.expression, scope, el);
+        if (next === open) return;
+        var firstRun = open === null;
+        open = next;
+
+        // First paint or reduced motion: snap to the resting state, no animation.
+        if (firstRun || prefersReducedMotion()) {
+          clearInline(el);
+          el.style.display = next ? "" : "none";
+          return;
+        }
+
+        el.style.overflow = "hidden";
+        el.style.transition =
+          "height var(--motion-enter-duration, var(--duration-normal, 200ms)) " +
+          "var(--motion-enter-ease, var(--ease-out, ease))";
+
+        if (next) {
+          // opening: 0 → scrollHeight → auto
+          el.style.display = "";
+          el.style.height = "0px";
+          void el.offsetHeight; // reflow so the 0 start commits
+          el.style.height = el.scrollHeight + "px";
+          whenSettled(el, function () {
+            clearInline(el); // height: auto, no residue
+          });
+        } else {
+          // closing: current height → 0 → hidden
+          el.style.height = el.scrollHeight + "px";
+          void el.offsetHeight; // reflow so the explicit start commits
+          el.style.height = "0px";
+          whenSettled(el, function () {
+            clearInline(el);
+            el.style.display = "none";
+          });
+        }
+      });
+    });
+  }
+
+  // CommonJS / bundler export (tests import the installer directly).
+  if (typeof module !== "undefined" && module.exports) {
+    module.exports = install;
+  }
+
+  // Browser self-registration: attach as soon as a global Faqir exists.
+  var F =
+    (typeof globalThis !== "undefined" && globalThis.Faqir) ||
+    (typeof window !== "undefined" && window.Faqir);
+  if (F && typeof F.plugin === "function") {
+    F.plugin(install);
+  }
+})();

package/dist/plugins/faqir-intersect.js

@@ -0,0 +1,64 @@
+// @ui:plugin faqir-intersect
+// @ui:provides l-intersect
+/**
+ * faqir-intersect — declarative IntersectionObserver hooks. [0.6-05 · §A5]
+ *
+ *   <section l-intersect="visible = true"
+ *            l-intersect.leave="visible = false"></section>
+ *   <div l-intersect.once="loadMore()"></div>
+ *
+ * The base directive runs on enter; `.leave` runs when the element leaves;
+ * `.once` disconnects after its first matching observation. The active entry is
+ * available to expressions as `$intersection`. Returning the observer cleanup
+ * to faqir-core makes scope teardown disconnect it automatically.
+ * Self-registering, zero dependencies, and ≤ 2 KB gzip.
+ */
+(function () {
+  "use strict";
+
+  function install(Faqir) {
+    Faqir.directive("intersect", function (el, dir, scope) {
+      var IO =
+        (typeof globalThis !== "undefined" && globalThis.IntersectionObserver) ||
+        (typeof window !== "undefined" && window.IntersectionObserver);
+      if (typeof IO !== "function") return;
+
+      var leave = dir.modifiers.indexOf("leave") >= 0;
+      var once = dir.modifiers.indexOf("once") >= 0;
+      var stopped = false;
+      var observer = new IO(function (entries) {
+        for (var i = 0; i < entries.length && !stopped; i++) {
+          var entry = entries[i];
+          var matches = leave ? !entry.isIntersecting : entry.isIntersecting;
+          if (!matches) continue;
+
+          scope.$intersection = entry;
+          try {
+            Faqir.evaluateAssignment(dir.expression, scope, el);
+          } finally {
+            delete scope.$intersection;
+          }
+
+          if (once) {
+            stopped = true;
+            observer.disconnect();
+          }
+        }
+      });
+
+      observer.observe(el);
+      return function () {
+        if (stopped) return;
+        stopped = true;
+        observer.disconnect();
+      };
+    });
+  }
+
+  if (typeof module !== "undefined" && module.exports) module.exports = install;
+
+  var F =
+    (typeof globalThis !== "undefined" && globalThis.Faqir) ||
+    (typeof window !== "undefined" && window.Faqir);
+  if (F && typeof F.plugin === "function") F.plugin(install);
+})();

package/dist/plugins/faqir-mask.js

@@ -0,0 +1,339 @@
+// @ui:plugin faqir-mask
+// @ui:provides l-mask
+/**
+ * faqir-mask — caret-safe input masking. [0.6-06 · §A5]
+ *
+ *   <input l-model="phone" l-mask="(999) 999-9999">
+ *
+ * Pattern tokens are `9` (digit), `a` (ASCII letter), and `*` (any character);
+ * every other character is a literal inserted by the formatter. The displayed
+ * input value is masked while `l-model` receives the raw token characters.
+ * `faqir:mask` bubbles after edits with `{ raw, value, caret }` for controllers
+ * such as input-otp. The pure `maskEdit()` function owns all edit/caret math;
+ * this directive is only a thin beforeinput/paste/model bridge.
+ *
+ * Self-registering, zero dependencies, and ≤ 2 KB gzip.
+ */
+(function () {
+  "use strict";
+
+  var TOKENS = { "9": /[0-9]/, a: /[A-Za-z]/, "*": /[^]/ };
+
+  function isToken(ch) {
+    return Object.prototype.hasOwnProperty.call(TOKENS, ch);
+  }
+
+  function tokenTypes(mask) {
+    var out = [];
+    for (var i = 0; i < mask.length; i++) if (isToken(mask[i])) out.push(mask[i]);
+    return out;
+  }
+
+  function accepts(token, ch) {
+    return !!ch && TOKENS[token].test(ch);
+  }
+
+  /** Extract token characters from either raw or already-formatted input. */
+  function readRaw(mask, value, startSlot) {
+    var types = tokenTypes(mask);
+    var slot = startSlot || 0;
+    var raw = "";
+    var text = String(value == null ? "" : value);
+    var maskIndex = 0;
+    var seenSlots = 0;
+
+    while (maskIndex < mask.length && seenSlots < slot) {
+      if (isToken(mask[maskIndex])) seenSlots++;
+      maskIndex++;
+    }
+
+    for (var i = 0; i < text.length && slot < types.length; i++) {
+      var ch = text[i];
+      while (maskIndex < mask.length && !isToken(mask[maskIndex])) {
+        if (ch === mask[maskIndex]) {
+          maskIndex++;
+          ch = "";
+          break;
+        }
+        maskIndex++;
+      }
+      if (!ch) continue;
+      if (accepts(types[slot], ch)) {
+        raw += ch;
+        slot++;
+        while (maskIndex < mask.length && !isToken(mask[maskIndex])) maskIndex++;
+        maskIndex++;
+      }
+    }
+    return raw;
+  }
+
+  /** Format raw token characters and retain raw-index ↔ display-position maps. */
+  function format(mask, rawValue) {
+    var raw = readRaw(mask, rawValue, 0);
+    var value = "";
+    var starts = [];
+    var ends = [];
+    var rawIndex = 0;
+
+    for (var i = 0; i < mask.length; i++) {
+      var part = mask[i];
+      if (isToken(part)) {
+        if (rawIndex >= raw.length) break;
+        starts[rawIndex] = value.length;
+        value += raw[rawIndex++];
+        ends[rawIndex - 1] = value.length;
+      } else if (raw.length > 0) {
+        value += part;
+      }
+    }
+    return { raw: raw, value: value, starts: starts, ends: ends };
+  }
+
+  function rawIndexAt(formatted, displayPosition) {
+    var position = Math.max(0, Number(displayPosition) || 0);
+    var rawIndex = 0;
+    for (var i = 0; i < formatted.ends.length; i++) {
+      if (formatted.ends[i] <= position) rawIndex = i + 1;
+      else break;
+    }
+    return rawIndex;
+  }
+
+  function caretAt(formatted, rawIndex) {
+    if (rawIndex < formatted.raw.length) return formatted.starts[rawIndex];
+    return formatted.value.length;
+  }
+
+  /**
+   * Pure edit engine.
+   * @param {string} mask
+   * @param {string} priorValue canonical masked value before the edit
+   * @param {{inputType?:string,data?:string|null,selectionStart?:number,selectionEnd?:number}} edit
+   * @returns {{raw:string,value:string,caret:number}}
+   */
+  function maskEdit(mask, priorValue, edit) {
+    mask = String(mask || "");
+    var types = tokenTypes(mask);
+    if (!types.length) throw new Error("l-mask pattern requires at least one 9, a, or * token");
+
+    edit = edit || {};
+    var prior = format(mask, priorValue);
+    var displayStart = edit.selectionStart == null ? prior.value.length : edit.selectionStart;
+    var displayEnd = edit.selectionEnd == null ? displayStart : edit.selectionEnd;
+    var start = rawIndexAt(prior, Math.min(displayStart, displayEnd));
+    var end = rawIndexAt(prior, Math.max(displayStart, displayEnd));
+    var inputType = edit.inputType || "insertText";
+    var raw = prior.raw;
+    var caretRaw = start;
+
+    if (inputType.indexOf("delete") === 0) {
+      if (start !== end) {
+        raw = raw.slice(0, start) + raw.slice(end);
+      } else if (inputType === "deleteContentBackward" && start > 0) {
+        raw = raw.slice(0, start - 1) + raw.slice(start);
+        caretRaw = start - 1;
+      } else if (inputType === "deleteContentForward") {
+        raw = raw.slice(0, start) + raw.slice(start + 1);
+      }
+    } else {
+      var inserted = readRaw(mask, edit.data == null ? "" : edit.data, start);
+      raw = (raw.slice(0, start) + inserted + raw.slice(end)).slice(0, types.length);
+      caretRaw = start + inserted.length;
+    }
+
+    var next = format(mask, raw);
+    return { raw: next.raw, value: next.value, caret: caretAt(next, caretRaw) };
+  }
+
+  function modelExpression(el) {
+    for (var i = 0; i < el.attributes.length; i++) {
+      if (el.attributes[i].name.indexOf("l-model") === 0) {
+        return el.attributes[i].value;
+      }
+    }
+    return "";
+  }
+
+  function install(Faqir) {
+    Faqir.directive("mask", function (el, dir, scope) {
+      if (!el || !/^(INPUT|TEXTAREA)$/.test(el.tagName)) {
+        console.warn("[Faqir] l-mask must be used on an input or textarea");
+        return;
+      }
+      if (el._faqirMask) {
+        if (el._faqirMask._scope === scope) return;
+        if (typeof el._faqirMask.destroy === "function") el._faqirMask.destroy();
+      }
+
+      var pattern = String(dir.expression || "").trim();
+      try {
+        maskEdit(pattern, "", {});
+      } catch (error) {
+        console.warn("[Faqir] " + error.message);
+        return;
+      }
+
+      var model = modelExpression(el);
+      var destroyed = false;
+      var renderId = 0;
+      var pendingCaret = null;
+      var initial = maskEdit(pattern, "", {
+        inputType: "insertFromPaste",
+        data: el.value,
+        selectionStart: 0,
+        selectionEnd: 0,
+      });
+      var raw = initial.raw;
+
+      function paint(result, caret) {
+        raw = result.raw;
+        if (el.value !== result.value) el.value = result.value;
+        if (caret !== false && typeof el.setSelectionRange === "function") {
+          try {
+            el.setSelectionRange(result.caret, result.caret);
+          } catch (e) {}
+        }
+      }
+
+      function emit(result) {
+        el.dispatchEvent(
+          new CustomEvent("faqir:mask", {
+            bubbles: true,
+            detail: { raw: result.raw, value: result.value, caret: result.caret },
+          }),
+        );
+      }
+
+      function commit(result, shouldEmit) {
+        paint(result, true);
+        if (model) {
+          pendingCaret = result.caret;
+          Faqir.evaluateAssignment(model + " = " + JSON.stringify(result.raw), scope, el);
+          // l-model also reflects the raw scope value into el.value. Repaint after
+          // the reactive flush so the visible value remains masked regardless of
+          // directive attribute order.
+          var id = ++renderId;
+          Faqir.nextTick(function () {
+            if (!destroyed && id === renderId) {
+              var repaint = formatResult(raw);
+              repaint.caret = pendingCaret == null ? repaint.caret : pendingCaret;
+              pendingCaret = null;
+              paint(repaint, true);
+            }
+          });
+        }
+        if (shouldEmit !== false) emit(result);
+        return result;
+      }
+
+      function formatResult(value) {
+        return maskEdit(pattern, "", {
+          inputType: "insertFromPaste",
+          data: value,
+          selectionStart: 0,
+          selectionEnd: 0,
+        });
+      }
+
+      function edit(inputType, data, selectionStart, selectionEnd) {
+        return commit(
+          maskEdit(pattern, el.value, {
+            inputType: inputType,
+            data: data,
+            selectionStart: selectionStart == null ? el.selectionStart : selectionStart,
+            selectionEnd: selectionEnd == null ? el.selectionEnd : selectionEnd,
+          }),
+          true,
+        );
+      }
+
+      function setRaw(value, caret, shouldEmit) {
+        var result = formatResult(value);
+        if (caret != null) {
+          var formatted = format(pattern, result.raw);
+          result.caret = caretAt(formatted, Math.max(0, Math.min(Number(caret) || 0, result.raw.length)));
+        }
+        return commit(result, shouldEmit);
+      }
+
+      function onBeforeInput(event) {
+        var type = event.inputType || "";
+        if (type.indexOf("insert") !== 0 && type.indexOf("delete") !== 0) return;
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        edit(type, event.data);
+      }
+
+      function onPaste(event) {
+        var data = event.clipboardData;
+        if (!data || typeof data.getData !== "function") return;
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        edit("insertFromPaste", data.getData("text"));
+      }
+
+      function onInput(event) {
+        // Fallback for autofill/IME paths that skip cancelable beforeinput.
+        event.stopImmediatePropagation();
+        var caret = el.selectionStart;
+        var result = formatResult(el.value);
+        result.caret = Math.min(caret == null ? result.value.length : caret, result.value.length);
+        commit(result, true);
+      }
+
+      el.addEventListener("beforeinput", onBeforeInput, true);
+      el.addEventListener("paste", onPaste, true);
+      el.addEventListener("input", onInput, true);
+
+      var api;
+      function cleanup() {
+        if (destroyed) return;
+        destroyed = true;
+        el.removeEventListener("beforeinput", onBeforeInput, true);
+        el.removeEventListener("paste", onPaste, true);
+        el.removeEventListener("input", onInput, true);
+        if (typeof stopModel === "function") stopModel();
+        if (el._faqirMask === api) delete el._faqirMask;
+      }
+
+      api = {
+        edit: edit,
+        getRaw: function () { return raw; },
+        setRaw: setRaw,
+        destroy: cleanup,
+        _scope: scope,
+      };
+      el._faqirMask = api;
+      paint(initial, false);
+
+      var stopModel = null;
+      if (model) {
+        stopModel = Faqir.effect(function () {
+          var value = Faqir.evaluate(model, scope, el);
+          var id = ++renderId;
+          Faqir.nextTick(function () {
+            if (!destroyed && id === renderId) {
+              var repaint = formatResult(value);
+              if (pendingCaret != null && repaint.raw === raw) {
+                repaint.caret = pendingCaret;
+                pendingCaret = null;
+                paint(repaint, true);
+              } else {
+                paint(repaint, false);
+              }
+            }
+          });
+        });
+      }
+
+      return cleanup;
+    });
+  }
+
+  install.maskEdit = maskEdit;
+  if (typeof module !== "undefined" && module.exports) module.exports = install;
+
+  var F = typeof globalThis !== "undefined" ? globalThis.Faqir : window.Faqir;
+  if (F && typeof F.plugin === "function") F.plugin(install);
+})();

package/dist/plugins/faqir-persist.js

@@ -0,0 +1,129 @@
+// @ui:plugin faqir-persist
+// @ui:provides l-persist, $persist()
+/**
+ * faqir-persist — localStorage-backed reactive state. [0.6-05 · §A5]
+ *
+ *   <div l-data="{ count: 0 }" l-persist="count">
+ *     <button @click="count++" l-text="count"></button>
+ *   </div>
+ *
+ * `l-persist="expression"` restores the expression before its first effect and
+ * writes every reactive change as JSON. Keys are scoped as
+ * `faqir:<namespace>:<key>`; set `data-persist-namespace` or
+ * `data-persist-key` when the location-derived defaults are not specific enough.
+ * `$persist(key)` reads the current namespace and `$persist(key, value)` writes
+ * it, which is useful from `l-init` and event expressions.
+ *
+ * Storage access is guarded because localStorage can be absent or can throw in
+ * privacy/quota modes. Failed writes fall back to module-local memory, keeping
+ * the page reactive without throwing. Self-registering, zero dependencies,
+ * and ≤ 2 KB gzip.
+ */
+(function () {
+  "use strict";
+
+  var memory = Object.create(null);
+
+  function storage() {
+    try {
+      var g = typeof globalThis !== "undefined" ? globalThis : window;
+      return g.localStorage || null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function namespace(el) {
+    var owner = el.closest && el.closest("[data-persist-namespace]");
+    if (owner) return owner.getAttribute("data-persist-namespace") || "default";
+    try {
+      return (location && location.pathname) || "default";
+    } catch (e) {
+      return "default";
+    }
+  }
+
+  function fullKey(el, key) {
+    return "faqir:" + namespace(el) + ":" + key;
+  }
+
+  function readRaw(key) {
+    if (Object.prototype.hasOwnProperty.call(memory, key)) return memory[key];
+    try {
+      var s = storage();
+      return s ? s.getItem(key) : null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function writeRaw(key, value) {
+    try {
+      var s = storage();
+      if (!s) throw new Error("storage unavailable");
+      if (value == null) s.removeItem(key);
+      else s.setItem(key, value);
+      delete memory[key];
+    } catch (e) {
+      if (value == null) delete memory[key];
+      else memory[key] = value;
+    }
+  }
+
+  function decode(raw) {
+    if (raw == null) return { found: false };
+    try {
+      return { found: true, value: JSON.parse(raw) };
+    } catch (e) {
+      return { found: false };
+    }
+  }
+
+  function encode(value) {
+    try {
+      return JSON.stringify(value);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function install(Faqir) {
+    Faqir.magic("persist", function (el) {
+      return function (key, value) {
+        var storageKey = fullKey(el, String(key));
+        if (arguments.length > 1) {
+          writeRaw(storageKey, encode(value));
+          return value;
+        }
+        var saved = decode(readRaw(storageKey));
+        return saved.found ? saved.value : undefined;
+      };
+    });
+
+    Faqir.directive("persist", function (el, dir, scope) {
+      var expression = (dir.expression || "").trim();
+      if (!expression) {
+        console.warn("[Faqir] l-persist requires a state expression");
+        return;
+      }
+
+      var key = el.getAttribute("data-persist-key") || expression;
+      var storageKey = fullKey(el, key);
+      var saved = decode(readRaw(storageKey));
+      if (saved.found) {
+        Faqir.evaluateAssignment(expression + " = " + JSON.stringify(saved.value), scope, el);
+      }
+
+      return Faqir.effect(function () {
+        writeRaw(storageKey, encode(Faqir.evaluate(expression, scope, el)));
+      });
+    });
+  }
+
+  if (typeof module !== "undefined" && module.exports) module.exports = install;
+
+  var F =
+    (typeof globalThis !== "undefined" && globalThis.Faqir) ||
+    (typeof window !== "undefined" && window.Faqir);
+  if (F && typeof F.plugin === "function") F.plugin(install);
+})();