@faqir-ui/core 1.0.0

package/dist/plugins/faqir-validate.js

@@ -0,0 +1,221 @@
+// @ui:plugin faqir-validate
+// @ui:provides l-validate
+/**
+ * faqir-validate — declarative form validation for the field-group contract. [0.6-02 · §7.1, §A5]
+ *
+ *   <form l-validate>
+ *     <div data-ui="field-group">
+ *       <label data-part="label" for="email">Work email</label>
+ *       <input data-part="input" id="email" name="email" type="email" required
+ *              l-validate:company="isCompanyEmail(value)"
+ *              data-error-company="Use your company address.">
+ *       <p data-part="error"></p>
+ *     </div>
+ *   </form>
+ *
+ * Reflects each control's native `ValidityState` (plus any custom validators)
+ * into the enclosing `[data-ui="field-group"]`: sets `data-state="invalid"`,
+ * fills the group's `[data-part="error"]` with a message, and wires
+ * `aria-invalid` (+ `aria-describedby` to the error part when it has an id).
+ * No JavaScript is required from the page author for the full validation UX.
+ *
+ * ── Revalidation policy (the exact UX contract) ─────────────────────────────
+ *   • On **submit**: every field is validated. If any is invalid the submit is
+ *     blocked (`preventDefault`) and focus moves to the first offender. When all
+ *     are clean the browser submits natively — unless `l-validate` carries an
+ *     expression, which is then treated as an on-valid hook (SPA submit) and run
+ *     while the native submit is suppressed.
+ *   • **After the first submit attempt**, each field additionally revalidates
+ *     live — on `blur` (error surfaces when you leave it) and on `input` (error
+ *     clears as you fix it). Before that first attempt, typing is never
+ *     interrupted with errors. (`blur` doesn't bubble, so both are captured.)
+ *
+ * ── Custom validators ───────────────────────────────────────────────────────
+ *   `l-validate:<name>="expr"` on a control runs only after native constraints
+ *   pass. `expr` is evaluated with the control's current `value` (and `$el`) in
+ *   scope; a falsy result marks the field invalid. Its message comes from
+ *   `data-error-<name>`, then `data-error`, then a default. Multiple named
+ *   validators may coexist on one control; the first to fail wins.
+ *
+ * ── Message resolution (when a field is invalid) ────────────────────────────
+ *   custom-validator message → `data-error-<constraint>` → `data-error`
+ *   → the browser's native `validationMessage` → a built-in default.
+ *
+ * Escape hatch: `data-validate-ignore` on a control opts it out entirely.
+ *
+ * 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. The only attributes it owns are `data-state="invalid"` on the
+ * group and `aria-invalid`/`aria-describedby` on the control — the frozen
+ * five-attribute protocol is untouched.
+ */
+(function () {
+  "use strict";
+
+  // Non-field / non-validatable input types — skipped when scanning a form.
+  var SKIP_TYPES = { submit: 1, button: 1, reset: 1, image: 1, hidden: 1 };
+
+  // ValidityState flag → (author-message attribute suffix, built-in fallback).
+  // Checked in order; the first failing flag decides the message.
+  var CONSTRAINTS = [
+    ["valueMissing", "required", "This field is required."],
+    ["typeMismatch", "type", "Please enter a valid value."],
+    ["patternMismatch", "pattern", "Please match the requested format."],
+    ["tooShort", "short", "Please lengthen this value."],
+    ["tooLong", "long", "Please shorten this value."],
+    ["rangeUnderflow", "min", "Value is too small."],
+    ["rangeOverflow", "max", "Value is too large."],
+    ["stepMismatch", "step", "Please enter a valid value."],
+    ["badInput", "input", "Please enter a valid value."]
+  ];
+
+  function isFormField(el) {
+    var tag = el.tagName;
+    if (tag !== "INPUT" && tag !== "SELECT" && tag !== "TEXTAREA") return false;
+    if (el.disabled) return false;
+    if (el.hasAttribute("data-validate-ignore")) return false;
+    if (tag === "INPUT" && SKIP_TYPES[el.type]) return false;
+    return true;
+  }
+
+  function fields(form) {
+    var out = [];
+    var all = form.querySelectorAll("input, select, textarea");
+    for (var i = 0; i < all.length; i++) if (isFormField(all[i])) out.push(all[i]);
+    return out;
+  }
+
+  // Suffixes of the custom `l-validate:<name>` validators declared on a control.
+  function customNames(el) {
+    var names = [];
+    for (var i = 0; i < el.attributes.length; i++) {
+      var n = el.attributes[i].name;
+      if (n.indexOf("l-validate:") === 0) names.push(n.slice(11));
+    }
+    return names;
+  }
+
+  // Message shown once a control is invalid — see header for the priority order.
+  function messageFor(el) {
+    var v = el.validity;
+    if (v.customError) return el.validationMessage || "This field is invalid.";
+    for (var i = 0; i < CONSTRAINTS.length; i++) {
+      if (v[CONSTRAINTS[i][0]]) {
+        return (
+          el.getAttribute("data-error-" + CONSTRAINTS[i][1]) ||
+          el.getAttribute("data-error") ||
+          el.validationMessage ||
+          CONSTRAINTS[i][2]
+        );
+      }
+    }
+    return el.validationMessage || "This field is invalid.";
+  }
+
+  function group(el) {
+    return el.closest('[data-ui="field-group"]');
+  }
+
+  // Reflect a control's verdict onto itself + its field-group. The plugin owns
+  // the group's `[data-part="error"]` text and toggles `data-state` only between
+  // "invalid" and cleared (an author's "disabled"/"validating" state is left be).
+  function applyState(el, valid, message) {
+    var g = group(el);
+    var err = g && g.querySelector('[data-part="error"]');
+    if (valid) {
+      el.removeAttribute("aria-invalid");
+      if (g && g.getAttribute("data-state") === "invalid") g.removeAttribute("data-state");
+      if (err) {
+        err.textContent = "";
+        if (err.id && el.getAttribute("aria-describedby") === err.id)
+          el.removeAttribute("aria-describedby");
+      }
+    } else {
+      el.setAttribute("aria-invalid", "true");
+      if (g) g.setAttribute("data-state", "invalid");
+      if (err) {
+        err.textContent = message;
+        if (err.id && !el.getAttribute("aria-describedby"))
+          el.setAttribute("aria-describedby", err.id);
+      }
+    }
+  }
+
+  function install(Faqir) {
+    Faqir.directive("validate", function (form, dir, scope) {
+      var submitted = false;
+
+      // Run a control's custom validators (native constraints already passed).
+      // `value` and `$el` are exposed so `l-validate:x="fn(value)"` resolves; the
+      // first falsy verdict sets a custom validity message and stops.
+      function runCustom(el) {
+        var names = customNames(el);
+        if (!names.length) return;
+        var local = Object.create(scope);
+        local.value = "value" in el ? el.value : null;
+        local.$el = el;
+        for (var i = 0; i < names.length; i++) {
+          var ok = !!Faqir.evaluate(el.getAttribute("l-validate:" + names[i]), local, el);
+          if (!ok) {
+            el.setCustomValidity(
+              el.getAttribute("data-error-" + names[i]) ||
+                el.getAttribute("data-error") ||
+                "This field is invalid."
+            );
+            return;
+          }
+        }
+      }
+
+      function validateField(el) {
+        el.setCustomValidity(""); // clear any prior custom verdict
+        if (el.validity.valid) runCustom(el); // native ok → try custom
+        var valid = el.validity.valid;
+        applyState(el, valid, valid ? "" : messageFor(el));
+        return valid;
+      }
+
+      // Submit: validate everything; block + focus the first offender when dirty.
+      form.addEventListener("submit", function (e) {
+        submitted = true;
+        var list = fields(form),
+          firstBad = null;
+        for (var i = 0; i < list.length; i++) {
+          if (!validateField(list[i]) && !firstBad) firstBad = list[i];
+        }
+        if (firstBad) {
+          e.preventDefault();
+          if (typeof firstBad.focus === "function") firstBad.focus();
+          return;
+        }
+        // Clean. A non-empty `l-validate` expression is an on-valid hook (SPA
+        // submit): run it and keep the browser from navigating. Otherwise let
+        // the native submit proceed.
+        if (dir.expression && dir.expression.trim()) {
+          e.preventDefault();
+          Faqir.evaluateAssignment(dir.expression, scope, form);
+        }
+      });
+
+      // After the first submit attempt, revalidate the touched field live.
+      function live(e) {
+        if (submitted && isFormField(e.target)) validateField(e.target);
+      }
+      form.addEventListener("blur", live, true);
+      form.addEventListener("input", live, true);
+    });
+  }
+
+  // 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/sri.json

@@ -0,0 +1,23 @@
+{
+  "faqir-core.js": "sha384-vH2gsWr7R/OAJLvYeBC4txN6mleQzdRiuLsc5AH2xbdge5+zQipF5AqSJS7Yc4Vz",
+  "faqir-core.min.js": "sha384-BHt1gSursbCylX/U3FT6iW5dWukyZcjDXKWOanw4baYgwn8qj1LIpI1It8ct7CyK",
+  "faqir-core.min.js.map": "sha384-io5FkzZ1meZXs3UY/kEJkmvB8YXwO/JfezQe4yZop6KZZjjwn6UCjeDUSh0FG1sz",
+  "faqir-core.mjs": "sha384-jqsZ/HqqXSuUjt6SikvDjynm7EdDVAfVLXYSoJHjzvOF+3V5CDmEZgzXDJPWvQ4I",
+  "faqir.aurora.css": "sha384-M7yDwTC7MuWfGfiIFLv9MFibCkYDDSHx6RFszEQ7iyd4Lp/bEG/SIyRcvSsfn2Vv",
+  "faqir.brutalist.css": "sha384-aRtTqpJetmoMa6uL2krMPEHsjTwF11oNlTzS9zZrdtqXSvzkSUCKKoHyr1WbCBnb",
+  "faqir.contrast.css": "sha384-Fy3tZU7cwb7LGNm9B/5nFNK1yRgwAZqv+FF69pY/w6AEGykZA4jSoDeFKU4hXdBf",
+  "faqir.default.css": "sha384-w2sH1K7AwYMeLQIhxBnAU1LuRrexg/xJx/eLLMgAjG7avxLYhYeuvM2pTu1yJJVi",
+  "faqir.document-serif.css": "sha384-2xWhB1DahXndhbbk7D+RV6w1NI7lPoO3tPgVtDvgWp8G+qE4jjI5nCWZa0IC1XiV",
+  "faqir.document.css": "sha384-loA3uWvclgLBd8OntpB4YrQP/jBsLScb06KI61EMauFjYxOadmCszUBkYYNoo4Wc",
+  "faqir.glass.css": "sha384-OQOzZy8BxLxPl1pFNkCwizX0oqOsmPf49FKhFa4d9HUM6bcJrJnzw3XU8IZGqSkG",
+  "faqir.midnight.css": "sha384-J0SQyAklYwD+yJ7jubtIJ+0t9DWBymcJikhI242PpTvzAL9SU4iWTYCwJBqSUbj0",
+  "faqir.paper.css": "sha384-OCmkztWvVBgacdb9HlGiRl+RRQ1QaFU8MCrQIYLeL17EMsT2tG8lZeU0mfQKLo6N",
+  "faqir.slate.css": "sha384-BxHSyxsLdi690Q1LBWIyAXodugjLNT764ZjqBRAaCtAaQeei81qzV46C5rMYonb4",
+  "faqir.soft.css": "sha384-a77S0Tcfd1I2V+r6Prt4gTtIzSZahltCuQ0jEzOKXUd+taDRjM0EsIy3n5VycLJT",
+  "faqir.terminal.css": "sha384-YvP4CkNUhcsFYJjBgnhcSMthsEheRg2RlZ0837GBzDVfmeJx9IYpMSrG7BkAb697",
+  "plugins/faqir-collapse.js": "sha384-y16PnFkcJiJLQIxuQMtdS+QalrC6lJ0EsPT/oceZWpLMGdqASXq3HhVHebfUWktm",
+  "plugins/faqir-intersect.js": "sha384-AfbB6icyS1ngl1JdiAMZ9//m5lHTMdgXXHWCdi5INfE9FmLbYRUeiyKTv4E4g6ri",
+  "plugins/faqir-mask.js": "sha384-cSq2DpUnoJCxEDAQjsbzAa+jSuHf4WsOaKT8t7b9p8pA7MaaRhA1DLzjMNChSa/I",
+  "plugins/faqir-persist.js": "sha384-o0jfddebC8QZ3S26VXUlOme723BNMlb/N7vqpn+fWpSeEFXzpq+3MoeXhVL/0PSv",
+  "plugins/faqir-validate.js": "sha384-DSzQ7I94Qm+VKjpgBo3qgALyuU3zgQZ+jXOIqgRHkJ6utr8nqF7tQMKWnOv1/YH2"
+}

package/examples/cdn-two-tag.html

@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Faqir UI — two-tag CDN demo</title>
+
+  <!-- The two tags. Local dist paths (swap for the jsDelivr URLs in production). -->
+  <link rel="stylesheet" href="../dist/faqir.default.css">
+  <script src="../dist/faqir-core.min.js" defer></script>
+</head>
+<body>
+  <main l-data="{ count: 0 }" data-ui="stack" data-gap="lg"
+        style="max-width: 40rem; margin: 3rem auto; padding: 0 1rem;">
+
+    <div data-ui="card">
+      <div data-part="header">
+        <h1 data-part="title">Faqir UI is running</h1>
+        <p data-part="description">
+          Styled by <code>faqir.default.css</code>, made interactive by
+          <code>faqir-core.min.js</code> — no build step, no install.
+        </p>
+      </div>
+
+      <div data-part="body" data-ui="stack" data-gap="md">
+        <p>
+          Clicked <span data-ui="badge" data-variant="primary" l-text="count">0</span> times.
+        </p>
+        <div data-ui="button-group">
+          <button data-ui="button" data-variant="primary" l-on:click="count++">Increment</button>
+          <button data-ui="button" data-variant="outline" l-on:click="count = 0">Reset</button>
+        </div>
+        <p data-ui="callout" data-variant="success" l-show="count >= 5">
+          🎉 Reactivity works — this callout appears once you reach 5.
+        </p>
+      </div>
+
+      <div data-part="footer">
+        <button data-ui="button" data-variant="ghost"
+                l-on:click="document.documentElement.dataset.theme =
+                            document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark'">
+          Toggle dark mode
+        </button>
+      </div>
+    </div>
+
+  </main>
+</body>
+</html>