@faqir-ui/core 1.0.0 → 1.1.0

package/dist/sri.json

@@ -1,23 +1,39 @@
 {
-  "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",
+  "faqir-core.js": "sha384-Ehw+8Knrsxpt9enram44fdKrZh9cJoKDO8WeN7+gZ4DDJEH/RwHiceK7lgfiGprw",
+  "faqir-core.min.js": "sha384-+FqfiMSc4+AeDam5DHWdByfqFpegDaGaYGsKVFeKqrV2YHahZla6egt04qPvvHSc",
+  "faqir-core.min.js.map": "sha384-eMfL8gnKtbSNBDSDa8FvuTsbIe5QFjcgaMktueIfzLSGL48HzFBmCA6Wt4mMKapj",
+  "faqir-core.mjs": "sha384-GIAWwY5wDRhwHb3/yKRvQ7D8oSmMI4PZKI0IsSMye5K1mnIwtCbgG20zphtOCn2x",
+  "faqir.aurora.css": "sha384-TrPBHGXGxwY6sLypt3kbjbhEHz87wsYgqQhzPqi5zghmsiqewgykQx6aS+WP2O0h",
+  "faqir.brutalist.css": "sha384-N/VfEAEdOZ2PGFX4xsPzlHEmDkXtjzmkXXW1Ta3PCtBV/RZm1rF4EYsfwLEvwqPZ",
+  "faqir.candy.css": "sha384-/lk9HAr46O2pYwsM8vE8MBVkPLB1t2otA3Edfux98b564DvNkWqpsD4DSVdcmHAX",
+  "faqir.clinical.css": "sha384-quTFS0lcUB0sz5ysan8vVX75oBDNzY+of7CmKDEoX5fM5OCIbYEttiZ8eLL/vQ4u",
+  "faqir.contrast.css": "sha384-Kkc5S9mDWhATTvHHfZhNd+rN06hSCvbKLuqa5y+cwtvlF7jSunMH1bLkfrZsVw5f",
+  "faqir.default.css": "sha384-bbc2p6aV7UYxrmv8M6x0buppf4uT7yh8DZ9d///ykZjXQokcZNtOk6xK1UUl6Mnj",
+  "faqir.document-serif.css": "sha384-gruBhX1KhlPRKzCVMODRBoOB+IpJM3lgYB+xQgCbu35onXyy+OFvh0MBDThrRFSq",
+  "faqir.document.css": "sha384-oC4VnHJi2ez8nAPSBwN4GWOz+BraAWcXXcGjNrQmdKujuA3fVmawKwolH1zIEzT0",
+  "faqir.editorial-document.css": "sha384-sKWLbBQ4IvgSvhLYo0nE95l6pqku+T0VTmkkoTwg/YOx5vM9gBAPA7f6CLE8gLNa",
+  "faqir.editorial.css": "sha384-N5sYSpAAOB81nDI+eShZ+gTZ5zbTMwaUt9fIPxwiNWBkKdaEJnsvyP3na/2SyNbv",
+  "faqir.fintech.css": "sha384-xY6baIhCB0boozwIAPzhPg2FFZ8RhqSf/13CWeda9Bd+9D5bvZbNuiFcO67GGLOL",
+  "faqir.glass.css": "sha384-MW9qUMfNSCgUyQjY/UqCpRxsXxuDEoVFvvpLy2htmV1Vc2mtn/z7uCXscj6Yn5zq",
+  "faqir.ink-document.css": "sha384-uWhbYEZwSDk3QHPMWe7lzYM0HELolHkW8xyqoowVvXrToqTXnSYVw7zTVET3kTVC",
+  "faqir.ink.css": "sha384-57zpUenZ+vVG/PViYuf1yxB0VxdV/5hxhZbKy9vi8XawKTMpbbU7AtnvgZ81ZIvs",
+  "faqir.luxe.css": "sha384-AP+OFzUaZ0RNEOGS95dsf09tD8ltts0VslqgCyaJ3CBHHkesKJ+/MT3SA4gZPxbe",
+  "faqir.midnight.css": "sha384-xsSMTT7Pf9i0CDFfx5hlzCBkHx5gsfORYS3rZuKnasgMkHumNUsy0fTBFcHBxSo3",
+  "faqir.neo.css": "sha384-rNHNMTeReWOmjhAayIam2CSmH3cUpHI3VbCOxg1hhk0GE3pAB2GX6tqzXH8OU9kX",
+  "faqir.neumorph.css": "sha384-7N6RHoYWSlnTHeTwVWrCn4ey1KR62fsAS0p1QVyb0gcljIYhcMWADZrmH/hOjhx+",
+  "faqir.nordic.css": "sha384-A/O40XHz2mMUs3tKWT7usnwgAxSsdFpb8uXKNMtoIa3OBaR2Ibpqg5mGNov90PaT",
+  "faqir.organic.css": "sha384-acTW5ka4Zy5SXHHn1My078WAnPkj6/KbLHKuWzToArB8rWlwZGRqlFxfq8VNAaqY",
+  "faqir.paper.css": "sha384-O26GS1gp6lFBZmollq/g21aUGVoWixAfBEsFxhWzPif1X2ZrjeXyIOEmCn25R1Dz",
+  "faqir.slate.css": "sha384-lSeSUhJCMUsQxM1oS2AbeqbfdLzquz4zYDYSF1N2bpA4JC0g/7fcJA/lWvkZugyq",
+  "faqir.soft.css": "sha384-G7xaO/Rr9RdMdBch66kUiS+atQOluVXhwIb039G7WJg6KvAxDBSbA/7v8y9ouhZH",
+  "faqir.sunset.css": "sha384-7FyjK1RJrkGTvOSFLH15WiRI1i8V3bbfpUuv4Gq3stG1NwC56/JkXOH4uPscY95b",
+  "faqir.swiss-document.css": "sha384-hQKtiQvaCu9ot5TJnCIlPjZhUJif5cacuE27IvJi1j99iF9HuNOvfGp+epSzJlMT",
+  "faqir.swiss.css": "sha384-Ki39mfAWeHD1KRjAB07b4MygOk5swzXSp5sUKcTWldXuiNhpNTWo+vOeponF4yfB",
+  "faqir.terminal.css": "sha384-EE2EAqi6sG4GTe8l+7w0p8gqCjZu8A+dkfNFCx90Ue/loSNUSnLIYDqdAsApyOOR",
+  "plugins/faqir-collapse.js": "sha384-3l5Z+isXlDkidRevDGkuNOiDp6eJ2ML11RkXA0j4ixQBaepuu8pAhyY4YRnR1qB7",
+  "plugins/faqir-intersect.js": "sha384-Q/akZjAcnTnGYPKBP7b8c3iyYbHTIW1IPjBivzOH9dE7Nflr9Cu6adjeDXU2bhk6",
+  "plugins/faqir-mask.js": "sha384-7yA/VdjGdg/6vwX+zUbughO6ERyV2rEsVyNYBO5ghqJbAhj9912F9qMPTkLc55B6",
   "plugins/faqir-persist.js": "sha384-o0jfddebC8QZ3S26VXUlOme723BNMlb/N7vqpn+fWpSeEFXzpq+3MoeXhVL/0PSv",
-  "plugins/faqir-validate.js": "sha384-DSzQ7I94Qm+VKjpgBo3qgALyuU3zgQZ+jXOIqgRHkJ6utr8nqF7tQMKWnOv1/YH2"
+  "plugins/faqir-rules.js": "sha384-xE90r5W3AlWKu+idcwx6NAkVUcRWMgM9ZJ1VgJLOguj/0GYP0jfflCojiCWt4FVq",
+  "plugins/faqir-validate.js": "sha384-TIyGNL8dHBnFdV56LAhdklvhQLsClQqGuQ7DT0Zgxva8DIzfONXZSJYTXhQxJcN0"
 }

package/faqir-core.d.ts

@@ -137,9 +137,95 @@ export interface Magics {
  * The interfaces are module-level exports, so an augmentation names one
  * directly — there is no `namespace Faqir` wrapper to reach through. The same
  * form opens {@link ControllerApis} and {@link Stores}.
+ *
+ * A magic whose SHAPE is fixed by the plugin gets its shape declared here even
+ * though the property is not: `plugins/faqir-rules.js` registers `$rules`, and
+ * {@link RulesState} is what it answers, so the augmentation is one line rather
+ * than a re-description —
+ *
+ *     declare module "@faqir-ui/core" {
+ *       interface PluginMagics { $rules: RulesState }
+ *     }
  */
 export interface PluginMagics {}
 
+/**
+ * What `$rules` answers — the live verdict of the `l-rules` definition bound to
+ * the form in this scope, installed by `plugins/faqir-rules.js`.  [1.1B-07]
+ *
+ * Reactive, so an expression that reads it re-runs when the form changes; and
+ * never undefined — a scope with no rules form gets the same shape with every
+ * map empty, so `$rules.next[step]` is safe to read anywhere.
+ *
+ * The keys of `visible`, `required` and `computed` are field paths as the
+ * definition spells them (`"seats"`, `"address.city"`); `next` is keyed by the
+ * page a `jump` rule fires ON and valued with the page it sends the form to, so
+ * a wizard reads `$rules.next[currentPage]` instead of counting by one.
+ */
+export interface RulesState {
+  /** path → whether a `show` rule leaves the field on screen. */
+  readonly visible: Readonly<Record<string, boolean>>;
+  /** path → whether a `require` rule makes the field mandatory right now. */
+  readonly required: Readonly<Record<string, boolean>>;
+  /** path → the value its `compute` rule derived. */
+  readonly computed: Readonly<Record<string, unknown>>;
+  /** from-page → to-page, for every `jump` rule whose `when` currently holds. */
+  readonly next: Readonly<Record<string, string>>;
+}
+
+/** What one programmatic validator answers: pass, fail, or a message. */
+export type ValidatorResult = boolean | string;
+
+/** The second argument every registered validator receives. */
+export interface ValidatorContext {
+  /** The control being validated. */
+  el: Element;
+  /** The form it was registered against. */
+  form: Element;
+  /** The form's `l-data` scope, or null when the form carries no `l-validate`. */
+  data: Scope | null;
+}
+
+/**
+ * A programmatic validator. Return `true` to pass, `false` to fail with the
+ * registered message, or a string to fail with that message — or a promise of
+ * any of those, which puts the field-group in `data-state="validating"` until
+ * it settles. Throwing or rejecting is a failure with a built-in message.
+ */
+export type FieldValidator = (
+  value: string | null,
+  ctx: ValidatorContext,
+) => ValidatorResult | Promise<ValidatorResult>;
+
+/**
+ * `Faqir.validate` — installed by `plugins/faqir-validate.js`, which is why the
+ * member is optional on {@link FaqirGlobal}. A page that does not load the
+ * plugin does not have it.  [1.1B-03]
+ */
+export interface ValidateApi {
+  /**
+   * Add a named validator to the control(s) named `field` in `form` (an element
+   * or a selector). Registered validators run after native constraints and
+   * after the `l-validate:<name>` attribute validators, in registration order,
+   * first failure wins. Returns a function that removes this one again.
+   */
+  register(
+    form: Element | string,
+    field: string,
+    name: string,
+    fn: FieldValidator,
+    message?: string,
+  ): Disposer;
+  /** Remove one named validator — or, with no `name`, all of the field's. */
+  unregister(form: Element | string, field: string, name?: string): void;
+  /**
+   * Validate every control of `form` and resolve to whether it is clean.
+   * Flushes any pending debounce, waits for every async check, and turns live
+   * revalidation on the way a submit attempt does.
+   */
+  run(form: Element | string): Promise<boolean>;
+}
+
 /**
  * A live reactive scope: the `l-data` object, the `data-prop-*` values merged
  * over it, whatever `l-source` injected, and the magics on its prototype.
@@ -652,11 +738,11 @@ export interface DevtoolsComponent {
 
 /**
  * One recorded diagnostic. The production engine records none, so
- * `warnings()` is always `[]` there — the four classes exist only in
- * `faqir-core.dev.js`.
+ * `warnings()` is always `[]` there — every class exists only in
+ * `faqir-core.dev.js`. `key` is a duplicate `l-key` in a keyed `l-for`.
  */
 export interface DevtoolsWarning {
-  kind: "expression" | "directive" | "reorder" | "html";
+  kind: "expression" | "directive" | "reorder" | "key" | "html" | "plugin";
   message: string;
   /** The offending element, as a short label. */
   element: string | null;
@@ -687,6 +773,14 @@ export interface Devtools {
   stores(): Record<string, Record<string, unknown>>;
   /** Diagnostics recorded so far, oldest first. */
   warnings(): DevtoolsWarning[];
+  /**
+   * Record one diagnostic on a plugin's behalf — the seam a plugin file uses to
+   * be as loud in the dev build as the engine is, having no reach into the
+   * engine's own hooks. `true` when it was recorded, `false` in the production
+   * build (which records nothing) and for a repeat the dev build has already
+   * printed.  [1.1B-03]
+   */
+  report(message: string, el?: Element | null): boolean;
 }
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -777,6 +871,16 @@ export interface FaqirGlobal {
    * than whichever engine touched the global last.
    */
   readonly devtools: Devtools;
+
+  // ── Plugin-installed ──
+  /**
+   * The programmatic validation surface `plugins/faqir-validate.js` installs.
+   * Optional because it is a plugin's, not the engine's: on a page that never
+   * loads the file it is simply absent, so reach it as `Faqir.validate?.run(f)`.
+   * The reflective drift test knows an optional member here may be missing from
+   * the engine for exactly this reason.  [1.1B-03]
+   */
+  readonly validate?: ValidateApi;
 }
 
 declare const Faqir: FaqirGlobal;
@@ -797,7 +901,8 @@ declare namespace Faqir {
     TableSort, TableState, TableApi, TabsApi, TagInputApi, ToastApi,
     ToggleGroupApi, TooltipApi, TreeViewApi, ControllerApis, ProtocolState,
     Inspection, DevtoolsScope, DevtoolsComponent, DevtoolsWarning, Devtools,
-    FaqirGlobal };
+    ValidatorResult, ValidatorContext, FieldValidator, ValidateApi,
+    RulesState, FaqirGlobal };
 }
 
 export default Faqir;
@@ -845,7 +950,8 @@ declare global {
       SidebarApi, SliderApi, TableSort, TableState, TableApi, TabsApi,
       TagInputApi, ToastApi, ToggleGroupApi, TooltipApi, TreeViewApi,
       ControllerApis, ProtocolState, Inspection, DevtoolsScope,
-      DevtoolsComponent, DevtoolsWarning, Devtools, FaqirGlobal };
+      DevtoolsComponent, DevtoolsWarning, Devtools, ValidatorResult,
+      ValidatorContext, FieldValidator, ValidateApi, RulesState, FaqirGlobal };
   }
   interface Window {
     /** Set by the classic-script build; absent under a bundler import. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faqir-ui/core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Faqir UI runtime engine — the Alpine-style reactive core (faqir-core.js), minified CDN build, and prebuilt per-theme CSS bundles. Zero dependencies.",
   "type": "module",
   "main": "./dist/faqir-core.mjs",