npm - gg-wf-scripts - Versions diffs - 1.0.0 → 2.4.0 - Mend

gg-wf-scripts 1.0.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +132 -19
package/package.json +2 -5
package/src/action-engine.js +14 -8
package/src/actions.js +4 -3
package/src/auth.js +9 -9
package/src/data-engine.js +64 -58
package/src/form-action-engine.js +149 -0
package/src/form-actions.js +21 -0
package/src/helpers/log.js +34 -0
package/src/index.js +19 -11
package/src/queries.js +4 -2
package/src/query-params.js +67 -0

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # gg-wf-scripts
-A declarative attribute engine for Webflow sites backed by Supabase. Add `gg-*` attributes to your markup and the library handles data binding, URL-driven state, dialogs, auth gating, form visibility, and user actions.
+A declarative attribute engine for Webflow sites. Add `gg-*` attributes to your markup and the library handles data binding, URL-driven state, dialogs, auth gating, form visibility, and user actions. Backend-agnostic — bring your own client (Supabase, fetch, anything).
 ## Install
@@ -14,21 +14,29 @@ Create a site-specific entry file, register your queries and actions, then bundl
 ```js
 import { init } from "gg-wf-scripts";
+import { createClient } from "@supabase/supabase-js";
+const sb = createClient("https://your-project.supabase.co", "your-publishable-key");
 const app = init({
-  supabaseUrl: "https://your-project.supabase.co",
-  supabaseKey: "your-publishable-key",
+  context: { sb },
+  auth: {
+    getUser: async () => (await sb.auth.getUser()).data.user?.id ?? null,
+    onChange: (cb) => sb.auth.onAuthStateChange((_e, session) => cb(session?.user?.id ?? null)),
+  },
 });
-app.addQuery("posts_list", async (sb) => {
+app.addQuery("posts_list", async ({ sb }, params) => {
+  const q = params.get("q") ?? "";
   const { data } = await sb
     .from("posts")
     .select("*")
+    .ilike("title", `%${q}%`)
     .order("created_at", { ascending: false });
   return data ?? [];
 });
-app.addAction("delete_post", async (sb, { id }) => {
+app.addAction("delete_post", async ({ sb }, { id }) => {
   const { error } = await sb.from("posts").delete().eq("id", id);
   return error ? { ok: false, error } : { ok: true };
 });
@@ -100,6 +108,25 @@ Read and write URL query params declaratively.
 <button gg-query-remove="modal,id">Close</button>
 ```
+#### Two-way input binding
+Mirror an input's value into a URL param as the user types. Empty value removes the param. The input is also populated from the URL on load and back/forward navigation.
+```html
+<!-- Bind to ?q=... with a 300ms debounce -->
+<input gg-query-bind="q" gg-query-debounce="300" placeholder="Search..." />
+```
+Combine with `gg-data-on` to re-run a query as the user types:
+```html
+<input gg-query-bind="q" gg-query-debounce="300" />
+<ul gg-data-list="search_posts" gg-data-on="q">
+  <li gg-list-template><span gg-field="title"></span></li>
+</ul>
+```
 ### Content switcher
 Show/hide children based on a state value.
@@ -139,7 +166,7 @@ Setting `?modal=...` opens the dialog. Removing it (or pressing Escape, or click
 ### Auth and role gating
-Show or hide elements based on Supabase auth state.
+Show or hide elements based on auth state. You provide the auth adapter, so any backend works.
 ```html
 <a href="/login" gg-auth="false">Log in</a>
@@ -149,6 +176,81 @@ Show or hide elements based on Supabase auth state.
 `gg-auth` is set on `<body>` as `"true"` or `"false"`. `gg-role` is set if you provide a `roleQuery` (see [Auth config](#auth-config)).
+### Form actions
+Override a form's submit to run a registered handler instead of the browser default. The handler receives the form's `FormData` directly.
+```html
+<form gg-form-action="create_post">
+  <input name="title" required />
+  <textarea name="body"></textarea>
+  <button type="submit">Save</button>
+</form>
+```
+```js
+app.addFormAction("create_post", async ({ sb }, formData) => {
+  const { error } = await sb.from("posts").insert({
+    title: formData.get("title"),
+    body: formData.get("body"),
+  });
+  return error ? { ok: false, error } : { ok: true };
+});
+```
+The handler receives `(context, formData, params)`. `preventDefault` is called automatically — the form will not submit to its `action` URL. Return `{ ok: true }` or `{ ok: false, error }`.
+#### Validation errors
+Form actions can return validation errors and the engine will display them via attributes on your markup.
+```js
+app.addFormAction("create_post", async ({ sb }, formData) => {
+  const title = formData.get("title");
+  if (!title) {
+    return {
+      ok: false,
+      field_errors: [{ name: "title", message: "Title is required" }],
+    };
+  }
+  const { error } = await sb.from("posts").insert({ title });
+  return error
+    ? { ok: false, error: "Could not save — please try again." }
+    : { ok: true };
+});
+```
+Markup:
+```html
+<form gg-form-action="create_post">
+  <input name="title" />
+  <p gg-form-field-error="title"></p>
+  <textarea name="body"></textarea>
+  <p gg-form-field-error="body"></p>
+  <!-- Optional: list every field error in one place -->
+  <ul gg-form-error-list>
+    <li gg-list-template>
+      <strong gg-field="name"></strong>: <span gg-field="message"></span>
+    </li>
+  </ul>
+  <!-- Optional: form-level error (the result.error string) -->
+  <p gg-form-error></p>
+  <button type="submit">Save</button>
+</form>
+```
+What the engine does:
+- Sets `gg-form-field-invalid="true"` on each invalid input — target with CSS like `input[gg-form-field-invalid="true"] { border-color: red; }`.
+- Sets the `textContent` of `[gg-form-field-error="<name>"]` elements to the matching message.
+- Populates `[gg-form-error-list]` using the same template pattern as `gg-data-list` (clones `[gg-list-template]`, applies `gg-field` bindings).
+- Sets the `textContent` of `[gg-form-error]` to the top-level `error` string.
+- All errors are cleared at the start of each submit, and a field's invalid attr + message are cleared when the user types in that field.
 ### Form visibility
 Conditionally show/hide elements based on form field values.
@@ -168,7 +270,7 @@ Hidden elements get `display: none`, `inert`, and `aria-hidden="true"`. Transiti
 ### Actions
-Run mutations on click. Actions receive the Supabase client and a data object.
+Run mutations on click. Actions receive the context object and a data object.
 ```html
 <!-- Simple action, no data needed -->
@@ -191,7 +293,7 @@ When an action is inside a `gg-data` or `gg-data-list` container, it automatical
 Action functions should return `{ ok: true }` or `{ ok: false, error }`:
 ```js
-app.addAction("delete_post", async (sb, { id }) => {
+app.addAction("delete_post", async ({ sb }, { id }) => {
   const { error } = await sb.from("posts").delete().eq("id", id);
   return error ? { ok: false, error } : { ok: true };
 });
@@ -205,24 +307,31 @@ Returns an app instance with `addQuery`, `addAction`, and `start` methods.
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `supabaseUrl` | `string` | Yes | Your Supabase project URL |
-| `supabaseKey` | `string` | Yes | Your Supabase publishable (anon) key |
-| `auth` | `object` | No | Auth configuration (see below) |
+| `context` | `object` | No | Arbitrary object passed to every query and action. Put backend clients or anything else your handlers need on it. Defaults to `{}`. |
+| `auth` | `object` | No | Auth adapter (see below). If omitted, `gg-auth`/`gg-role` attrs are never set. |
+| `debug` | `boolean` | No | When `true`, every query and action is logged to the console (trigger/container, data, result, duration). Defaults to `false`. |
-### Auth config
+### Auth adapter
 | Option | Type | Description |
 |---|---|---|
-| `auth.roleQuery` | `async (sb, userId) => string \| null` | Returns the user's role string. Called on auth state change. If omitted, `gg-auth` still works but `gg-role` is never set. |
+| `auth.getUser` | `() => string \| null \| Promise<string \| null>` | Returns the current user id, or `null` when signed out. Called once on start. |
+| `auth.onChange` | `(cb: (userId: string \| null) => void) => void` | Subscribe to auth changes. Optional but recommended — without it, `gg-auth` won't update on sign-in/out. |
+| `auth.roleQuery` | `async (context, userId) => string \| null` | Returns the user's role string. Called on every auth change. If omitted, `gg-role` is never set. |
-Example:
+Example with Supabase:
 ```js
+import { createClient } from "@supabase/supabase-js";
+const sb = createClient("...", "...");
 const app = init({
-  supabaseUrl: "...",
-  supabaseKey: "...",
+  context: { sb },
   auth: {
-    roleQuery: async (sb, userId) => {
+    getUser: async () => (await sb.auth.getUser()).data.user?.id ?? null,
+    onChange: (cb) => sb.auth.onAuthStateChange((_e, session) => cb(session?.user?.id ?? null)),
+    roleQuery: async ({ sb }, userId) => {
       const { data } = await sb
         .from("user_roles")
         .select("role")
@@ -236,13 +345,17 @@ const app = init({
 ### `app.addQuery(id, fn)`
-Register a data query. `fn` receives `(sb)` and should return:
+Register a data query. `fn` receives `(context, params)` where `params` is a `URLSearchParams` snapshot of the current URL query string. Use `params.get("id")` for single values or `params.getAll("tag")` for multi-value params. Return:
 - A single object (or `null`) for use with `gg-data` or `gg-data-form`
 - An array for use with `gg-data-list`
 ### `app.addAction(id, fn)`
-Register an action. `fn` receives `(sb, data)` and should return `{ ok: true }` or `{ ok: false, error }`.
+Register an action. `fn` receives `(context, data, params)` where `params` is a `URLSearchParams` snapshot of the current URL query string. Return `{ ok: true }` or `{ ok: false, error }`.
+### `app.addFormAction(id, fn)`
+Register a form action. `fn` receives `(context, formData, params)` where `formData` is a `FormData` snapshot of the submitted form. The default submit is prevented automatically. Return `{ ok: true }` or `{ ok: false, error }`.
 ### `app.start()`

package/package.json CHANGED Viewed

@@ -1,9 +1,6 @@
 {
 	"name": "gg-wf-scripts",
-	"version": "1.0.0",
+	"version": "2.4.0",
 	"type": "module",
-	"exports": "./src/index.js",
-	"dependencies": {
-		"@supabase/supabase-js": "^2"
-	}
+	"exports": "./src/index.js"
 }

package/src/action-engine.js CHANGED Viewed

@@ -1,4 +1,6 @@
 import { actionRegistry } from "./actions.js";
+import { withDebugLog } from "./helpers/log.js";
+import { getParams } from "./query-params.js";
 function parseActionData(el) {
   const attr = el.getAttribute("gg-action-data");
@@ -23,7 +25,7 @@ function findRecord(el) {
   return null;
 }
-export function initActionEngine(sb) {
+export function initActionEngine(context, { debug = false } = {}) {
   async function handleAction(el) {
     const id = el.getAttribute("gg-action");
     const action = actionRegistry[id];
@@ -35,14 +37,18 @@ export function initActionEngine(sb) {
     const record = findRecord(el);
     const explicit = parseActionData(el);
     const data = record ? { ...record, ...explicit } : explicit;
+    const params = getParams();
-    try {
-      const result = await action(sb, data);
-      if (result?.ok === false) {
-        console.warn(`[gg-action] "${id}" failed:`, result.error ?? "unknown error");
-      }
-    } catch (err) {
-      console.error(`[gg-action] "${id}" threw:`, err);
+    const result = await withDebugLog(
+      "[gg-action]",
+      id,
+      { trigger: el, data, params: Object.fromEntries(params) },
+      debug,
+      () => action(context, data, params),
+    );
+    if (result?.ok === false) {
+      console.warn(`[gg-action] "${id}" failed:`, result.error ?? "unknown error");
     }
   }

package/src/actions.js CHANGED Viewed

@@ -4,9 +4,10 @@ export const actionRegistry = {};
  * Register an action triggered by gg-action="<id>" on click.
  *
  * @param {string} id - The action identifier, referenced by gg-action="<id>" in markup.
- * @param {(sb: SupabaseClient, data: object) => Promise<{ok: boolean, error?: any}>} fn
- *   Receives the Supabase client and a data object (merged from the nearest gg-data record
- *   and any explicit gg-action-data attribute). Return { ok: true } or { ok: false, error }.
+ * @param {(context: object, data: object, params: URLSearchParams) => Promise<{ok: boolean, error?: any}>} fn
+ *   Receives the context object passed to init(), a data object (merged from the nearest
+ *   gg-data record and any explicit gg-action-data attribute), and a URLSearchParams snapshot
+ *   of the current URL query string. Return { ok: true } or { ok: false, error }.
  */
 export function registerAction(id, fn) {
   actionRegistry[id] = fn;

package/src/auth.js CHANGED Viewed

@@ -1,4 +1,6 @@
-export async function initAuth(sb, roleQuery) {
+export async function initAuth(context, auth) {
+  const { getUser, onChange, roleQuery } = auth;
   async function applyAuthAttrs(userId) {
     const body = document.body;
     if (!userId) {
@@ -8,7 +10,7 @@ export async function initAuth(sb, roleQuery) {
     }
     body.setAttribute("gg-auth", "true");
     if (roleQuery) {
-      const role = await roleQuery(sb, userId);
+      const role = await roleQuery(context, userId);
       if (role) {
         body.setAttribute("gg-role", role);
       } else {
@@ -17,12 +19,10 @@ export async function initAuth(sb, roleQuery) {
     }
   }
-  const {
-    data: { user },
-  } = await sb.auth.getUser();
-  applyAuthAttrs(user?.id ?? null);
+  const userId = await getUser();
+  applyAuthAttrs(userId ?? null);
-  sb.auth.onAuthStateChange((_event, session) => {
-    applyAuthAttrs(session?.user?.id ?? null);
-  });
+  if (onChange) {
+    onChange((userId) => applyAuthAttrs(userId ?? null));
+  }
 }

package/src/data-engine.js CHANGED Viewed

@@ -4,8 +4,9 @@ import {
   setSwitchState,
   applySwitchState,
 } from "./helpers/dom.js";
+import { withDebugLog } from "./helpers/log.js";
 import { queryRegistry } from "./queries.js";
-import { onQueryChanged } from "./query-params.js";
+import { onQueryChanged, getParams } from "./query-params.js";
 function applySwitchFields(root, record) {
   root.querySelectorAll("[gg-switch-field]").forEach((el) => {
@@ -41,7 +42,7 @@ function populateFormFields(root, record) {
   });
 }
-export function initDataEngine(sb) {
+export function initDataEngine(context, { debug = false } = {}) {
   async function runQuery(container) {
     const isList = container.hasAttribute("gg-data-list");
     const isForm = container.hasAttribute("gg-data-form");
@@ -54,66 +55,71 @@ export function initDataEngine(sb) {
       return;
     }
-    try {
-      const result = await query(sb);
-      if (isList) {
-        if (!Array.isArray(result)) {
-          console.warn(
-            `[gg-data-list] query "${id}" did not return an array`,
-          );
-          return;
-        }
+    const params = getParams();
+    const result = await withDebugLog(
+      "[gg-data]",
+      id,
+      { container, params: Object.fromEntries(params) },
+      debug,
+      () => query(context, params),
+    );
+    if (result === undefined) return;
-        const template = container.querySelector("[gg-list-template]");
-        if (!template) {
-          console.warn(
-            `[gg-data-list] no [gg-list-template] inside "${id}"`,
-          );
-          return;
-        }
+    if (isList) {
+      if (!Array.isArray(result)) {
+        console.warn(
+          `[gg-data-list] query "${id}" did not return an array`,
+        );
+        return;
+      }
-        Array.from(container.children).forEach((child) => {
-          if (child !== template) child.remove();
-        });
+      const template = container.querySelector("[gg-list-template]");
+      if (!template) {
+        console.warn(
+          `[gg-data-list] no [gg-list-template] inside "${id}"`,
+        );
+        return;
+      }
-        result.forEach((record) => {
-          const clone = template.cloneNode(true);
-          clone.removeAttribute("gg-list-template");
-          clone.setAttribute(
-            "gg-query-set",
-            `modal:view,id:${record.id}`,
-          );
-          clone.style.display = "flex";
-          if (record?.id != null) clone.id = String(record.id);
-          clone.__ggRecord = record;
-          populateFields(clone, record);
-          applySwitchFields(clone, record);
-          container.appendChild(clone);
-        });
-      } else if (isForm) {
-        if (Array.isArray(result)) {
-          console.warn(
-            `[gg-data-form] query "${id}" returned an array; expected a single record`,
-          );
-          return;
-        }
-        if (!result) return;
-        container.__ggRecord = result;
-        populateFormFields(container, result);
-      } else {
-        if (Array.isArray(result)) {
-          console.warn(
-            `[gg-data] query "${id}" returned an array; use gg-data-list instead`,
-          );
-          return;
-        }
-        if (!result) return;
-        container.__ggRecord = result;
-        populateFields(container, result);
-        applySwitchFields(container, result);
+      Array.from(container.children).forEach((child) => {
+        if (child !== template) child.remove();
+      });
+      result.forEach((record) => {
+        const clone = template.cloneNode(true);
+        clone.removeAttribute("gg-list-template");
+        clone.setAttribute(
+          "gg-query-set",
+          `modal:view,id:${record.id}`,
+        );
+        clone.style.display = "flex";
+        if (record?.id != null) clone.id = String(record.id);
+        clone.__ggRecord = record;
+        populateFields(clone, record);
+        applySwitchFields(clone, record);
+        container.appendChild(clone);
+      });
+    } else if (isForm) {
+      if (Array.isArray(result)) {
+        console.warn(
+          `[gg-data-form] query "${id}" returned an array; expected a single record`,
+        );
+        return;
+      }
+      if (!result) return;
+      container.__ggRecord = result;
+      populateFormFields(container, result);
+    } else {
+      if (Array.isArray(result)) {
+        console.warn(
+          `[gg-data] query "${id}" returned an array; use gg-data-list instead`,
+        );
+        return;
       }
-    } catch (err) {
-      console.error(`[gg-data] query "${id}" failed:`, err);
+      if (!result) return;
+      container.__ggRecord = result;
+      populateFields(container, result);
+      applySwitchFields(container, result);
     }
   }

package/src/form-action-engine.js ADDED Viewed

@@ -0,0 +1,149 @@
+import { formActionRegistry } from "./form-actions.js";
+import { populateFields } from "./helpers/dom.js";
+import { withDebugLog } from "./helpers/log.js";
+import { getParams } from "./query-params.js";
+function findInputs(form, name) {
+  const escaped = CSS.escape(name);
+  return form.querySelectorAll(
+    `input[name="${escaped}"], select[name="${escaped}"], textarea[name="${escaped}"]`,
+  );
+}
+function clearFieldError(form, name) {
+  findInputs(form, name).forEach((el) => {
+    el.removeAttribute("gg-form-field-invalid");
+  });
+  const escaped = CSS.escape(name);
+  form
+    .querySelectorAll(`[gg-form-field-error="${escaped}"]`)
+    .forEach((el) => {
+      el.textContent = "";
+    });
+}
+function clearFormErrors(form) {
+  form.querySelectorAll("[gg-form-field-invalid]").forEach((el) => {
+    el.removeAttribute("gg-form-field-invalid");
+  });
+  form.querySelectorAll("[gg-form-field-error]").forEach((el) => {
+    el.textContent = "";
+  });
+  form.querySelectorAll("[gg-form-error]").forEach((el) => {
+    el.textContent = "";
+  });
+  form.querySelectorAll("[gg-form-error-list]").forEach((list) => {
+    const template = list.querySelector("[gg-list-template]");
+    Array.from(list.children).forEach((child) => {
+      if (child !== template) child.remove();
+    });
+  });
+}
+function applyFieldErrors(form, fieldErrors) {
+  fieldErrors.forEach(({ name, message }) => {
+    if (!name) return;
+    findInputs(form, name).forEach((el) => {
+      el.setAttribute("gg-form-field-invalid", "true");
+    });
+    const escaped = CSS.escape(name);
+    form
+      .querySelectorAll(`[gg-form-field-error="${escaped}"]`)
+      .forEach((el) => {
+        el.textContent = message ?? "";
+      });
+  });
+}
+function applyErrorList(form, fieldErrors) {
+  form.querySelectorAll("[gg-form-error-list]").forEach((list) => {
+    const template = list.querySelector("[gg-list-template]");
+    if (!template) {
+      console.warn(
+        "[gg-form-error-list] no [gg-list-template] inside list:",
+        list,
+      );
+      return;
+    }
+    fieldErrors.forEach((record) => {
+      const clone = template.cloneNode(true);
+      clone.removeAttribute("gg-list-template");
+      clone.style.display = "";
+      populateFields(clone, record);
+      list.appendChild(clone);
+    });
+  });
+}
+function applyFormError(form, error) {
+  if (error == null) return;
+  const message = typeof error === "string" ? error : String(error);
+  form.querySelectorAll("[gg-form-error]").forEach((el) => {
+    el.textContent = message;
+  });
+}
+function bindFieldClearOnInput(form) {
+  if (form.__ggFormErrorBound) return;
+  form.__ggFormErrorBound = true;
+  form.addEventListener("input", (e) => {
+    const name = e.target?.getAttribute?.("name");
+    if (!name) return;
+    if (e.target.hasAttribute("gg-form-field-invalid")) {
+      clearFieldError(form, name);
+    }
+  });
+}
+export function initFormActionEngine(context, { debug = false } = {}) {
+  async function handleSubmit(form, event) {
+    const id = form.getAttribute("gg-form-action");
+    const action = formActionRegistry[id];
+    if (!action) {
+      console.warn(`[gg-form-action] no form action registered for "${id}"`);
+      return;
+    }
+    event.preventDefault();
+    clearFormErrors(form);
+    const formData = new FormData(form);
+    const params = getParams();
+    const result = await withDebugLog(
+      "[gg-form-action]",
+      id,
+      {
+        form,
+        formData: Object.fromEntries(formData),
+        params: Object.fromEntries(params),
+      },
+      debug,
+      () => action(context, formData, params),
+    );
+    if (result?.ok === false) {
+      const fieldErrors = Array.isArray(result.field_errors)
+        ? result.field_errors
+        : [];
+      applyFieldErrors(form, fieldErrors);
+      applyErrorList(form, fieldErrors);
+      applyFormError(form, result.error);
+      if (!fieldErrors.length && result.error == null) {
+        console.warn(
+          `[gg-form-action] "${id}" returned ok:false with no error or field_errors`,
+        );
+      }
+    }
+  }
+  document.querySelectorAll("form[gg-form-action]").forEach(bindFieldClearOnInput);
+  document.addEventListener("submit", (e) => {
+    const form = e.target;
+    if (form?.tagName === "FORM" && form.hasAttribute("gg-form-action")) {
+      bindFieldClearOnInput(form);
+      handleSubmit(form, e);
+    }
+  });
+}

package/src/form-actions.js ADDED Viewed

@@ -0,0 +1,21 @@
+export const formActionRegistry = {};
+/**
+ * Register a form action triggered by submitting a form with gg-form-action="<id>".
+ *
+ * @param {string} id - The form action identifier, referenced by gg-form-action="<id>" on a form.
+ * @param {(context: object, formData: FormData, params: URLSearchParams) => Promise<{
+ *   ok: boolean,
+ *   error?: any,
+ *   field_errors?: Array<{ name: string, message: string }>,
+ * }>} fn
+ *   Receives the context object passed to init(), a FormData snapshot of the submitted form,
+ *   and a URLSearchParams snapshot of the current URL query string. Return:
+ *   - { ok: true } on success
+ *   - { ok: false, field_errors: [{ name, message }, ...] } for validation errors
+ *   - { ok: false, error: "..." } for a single form-level error
+ *   - Both field_errors and error may be present together.
+ */
+export function registerFormAction(id, fn) {
+  formActionRegistry[id] = fn;
+}

package/src/helpers/log.js ADDED Viewed

@@ -0,0 +1,34 @@
+/**
+ * Wrap an async handler with optional debug logging and uniform throw handling.
+ *
+ * On success, returns the handler's resolved value. On throw, logs the error and
+ * returns `undefined` so callers can branch on it.
+ *
+ * @param {string} prefix - Log prefix, e.g. "[gg-action]".
+ * @param {string} id - Handler identifier shown in the log group.
+ * @param {Record<string, any>} fields - Key/value pairs logged when debug is on.
+ * @param {boolean} debug - Whether to emit grouped debug logs.
+ * @param {() => Promise<any>} run - The handler invocation.
+ */
+export async function withDebugLog(prefix, id, fields, debug, run) {
+  if (debug) {
+    console.groupCollapsed(`${prefix} "${id}"`);
+    for (const [key, value] of Object.entries(fields)) {
+      console.log(`${key}:`, value);
+    }
+  }
+  const startedAt = debug ? performance.now() : 0;
+  try {
+    const result = await run();
+    if (debug) {
+      const ms = (performance.now() - startedAt).toFixed(1);
+      console.log(`result (${ms}ms):`, result);
+    }
+    return result;
+  } catch (err) {
+    console.error(`${prefix} "${id}" threw:`, err);
+    return undefined;
+  } finally {
+    if (debug) console.groupEnd();
+  }
+}

package/src/index.js CHANGED Viewed

@@ -1,6 +1,6 @@
-import { createClient } from "@supabase/supabase-js";
 import { registerQuery } from "./queries.js";
 import { registerAction } from "./actions.js";
+import { registerFormAction } from "./form-actions.js";
 import { setSwitchState, applySwitchState, populateFields } from "./helpers/dom.js";
 import { setQueryParams, removeQueryParams, initQueryParams } from "./query-params.js";
 import { initAuth } from "./auth.js";
@@ -10,6 +10,7 @@ import { initBridges } from "./bridges.js";
 import { initFormVisibility } from "./form-visibility.js";
 import { initDataEngine } from "./data-engine.js";
 import { initActionEngine } from "./action-engine.js";
+import { initFormActionEngine } from "./form-action-engine.js";
 export { setSwitchState, applySwitchState, populateFields, setQueryParams, removeQueryParams };
 export { getPath } from "./helpers/path.js";
@@ -17,29 +18,36 @@ export { getPath } from "./helpers/path.js";
 /**
  * Create a gg-scripts app instance.
  *
- * @param {object} options
- * @param {string} options.supabaseUrl - Your Supabase project URL.
- * @param {string} options.supabaseKey - Your Supabase publishable (anon) key.
- * @param {object} [options.auth] - Auth configuration.
- * @param {(sb: SupabaseClient, userId: string) => Promise<string|null>} [options.auth.roleQuery]
+ * @param {object} [options]
+ * @param {object} [options.context] - Arbitrary object passed to every query and action.
+ *   Put backend clients (Supabase, fetch wrappers, etc.) or anything else your queries need on it.
+ * @param {object} [options.auth] - Auth adapter. If omitted, gg-auth/gg-role attrs are never set.
+ * @param {() => (string|null) | Promise<string|null>} options.auth.getUser
+ *   Returns the current user id, or null when signed out.
+ * @param {(cb: (userId: string|null) => void) => void} [options.auth.onChange]
+ *   Subscribe to auth changes. Called with the new user id (or null) whenever it changes.
+ * @param {(context: object, userId: string) => Promise<string|null>} [options.auth.roleQuery]
  *   Returns the user's role string for gg-role gating. If omitted, gg-role is never set.
+ * @param {boolean} [options.debug=false] - When true, every query and action is logged to the
+ *   console with its trigger/container, data, result, and duration.
  * @returns {{ addQuery: function, addAction: function, start: function }}
  */
-export function init({ supabaseUrl, supabaseKey, auth }) {
+export function init({ context = {}, auth, debug = false } = {}) {
   return {
     addQuery: registerQuery,
     addAction: registerAction,
+    addFormAction: registerFormAction,
     start() {
       function run() {
-        const sb = createClient(supabaseUrl, supabaseKey);
-        initAuth(sb, auth?.roleQuery);
+        if (auth) initAuth(context, auth);
         initSwitchEngine();
         initQueryParams();
         initDialog();
         initBridges();
         initFormVisibility();
-        initDataEngine(sb);
-        initActionEngine(sb);
+        initDataEngine(context, { debug });
+        initActionEngine(context, { debug });
+        initFormActionEngine(context, { debug });
       }
       if (document.readyState === "loading") {

package/src/queries.js CHANGED Viewed

@@ -4,8 +4,10 @@ export const queryRegistry = {};
  * Register a data query for use with gg-data, gg-data-form, or gg-data-list.
  *
  * @param {string} id - The query identifier, referenced by gg-data="<id>" in markup.
- * @param {(sb: SupabaseClient) => Promise<object|object[]|null>} fn
- *   Return a single object (or null) for gg-data/gg-data-form, or an array for gg-data-list.
+ * @param {(context: object, params: URLSearchParams) => Promise<object|object[]|null>} fn
+ *   Receives the context object passed to init() and a URLSearchParams snapshot of the
+ *   current URL query string. Return a single object (or null) for gg-data/gg-data-form,
+ *   or an array for gg-data-list.
  */
 export function registerQuery(id, fn) {
   queryRegistry[id] = fn;

package/src/query-params.js CHANGED Viewed

@@ -1,5 +1,12 @@
 const subscribers = [];
+/**
+ * Snapshot of the current URL query string as a URLSearchParams instance.
+ */
+export function getParams() {
+  return new URL(window.location).searchParams;
+}
 export function onQueryChanged(callback) {
   subscribers.push(callback);
   return () => {
@@ -74,4 +81,64 @@ export function initQueryParams() {
   document.addEventListener("gg:shadow:click", (e) =>
     handleQueryClick(e.detail.target),
   );
+  initQueryBindings();
+}
+// ---- gg-query-bind: input/textarea/select <-> URL param ----
+function syncBindInputFromUrl(el) {
+  const key = el.getAttribute("gg-query-bind");
+  if (!key) return;
+  const value = new URL(window.location).searchParams.get(key) ?? "";
+  if (el.value !== value) el.value = value;
+}
+function setupQueryBindInput(el) {
+  const key = el.getAttribute("gg-query-bind");
+  if (!key) return;
+  const debounceMs = parseInt(el.getAttribute("gg-query-debounce") ?? "0", 10) || 0;
+  syncBindInputFromUrl(el);
+  let timer;
+  let suppress = false;
+  el.addEventListener("input", () => {
+    if (suppress) return;
+    clearTimeout(timer);
+    const fire = () => {
+      const value = el.value;
+      if (value === "") {
+        removeQueryParams([key]);
+      } else {
+        setQueryParams([{ key, value }]);
+      }
+    };
+    if (debounceMs > 0) {
+      timer = setTimeout(fire, debounceMs);
+    } else {
+      fire();
+    }
+  });
+  // When the URL changes from elsewhere (back button, programmatic), mirror
+  // it into the input without re-firing the input listener.
+  onQueryChanged((changedKey, value) => {
+    if (changedKey !== key) return;
+    const next = value ?? "";
+    if (el.value === next) return;
+    suppress = true;
+    el.value = next;
+    suppress = false;
+  });
+}
+function initQueryBindings() {
+  document.querySelectorAll("[gg-query-bind]").forEach(setupQueryBindInput);
+  // Back/forward navigation doesn't fire pushState notifications, so
+  // re-sync all bound inputs from the URL on popstate.
+  window.addEventListener("popstate", () => {
+    document.querySelectorAll("[gg-query-bind]").forEach(syncBindInputFromUrl);
+  });
 }