gg-wf-scripts 1.0.0 → 2.5.0

package/README.md

@@ -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 };
 });
@@ -78,6 +86,25 @@ Display data from your queries in the DOM.
 
 `gg-field` supports dot-paths for nested data (e.g. `author.name`).
 
+#### Passing data to web components / React
+
+For elements that manage their own DOM (custom elements wrapping React, Lit, etc.), use `gg-data-key` to receive a JSON-serialized value as a `gg-data-value` attribute. The component listens for attribute changes and updates its own state.
+
+```html
+<div gg-data="post_form">
+  <!-- record.schools is e.g. [{ id, name }, ...] -->
+  <my-select gg-data-key="schools"></my-select>
+</div>
+```
+
+After the query runs, the engine resolves the dot-path against the record and writes the result:
+
+```html
+<my-select gg-data-key="schools" gg-data-value='[{"id":1,"name":"Acme"}]'></my-select>
+```
+
+The lookup pierces shadow roots, so the marker can live inside a component's shadow DOM. Leaving `gg-data-key=""` passes the entire record. Note: if the component renders after the query runs, it won't be found — re-run the query (e.g. via `gg-data-on`) once the component has mounted, or have the component pull from `host.__ggRecord` on connect.
+
 #### Re-running on URL changes
 
 Add `gg-data-on` to re-run a query when specific URL params change:
@@ -100,6 +127,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 +185,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 +195,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 +289,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 +312,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 +326,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 +364,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

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

package/src/action-engine.js

@@ -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

@@ -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

@@ -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

@@ -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) => {
@@ -16,6 +17,23 @@ function applySwitchFields(root, record) {
   });
 }
 
+function queryDeep(root, selector) {
+  const results = [...root.querySelectorAll(selector)];
+  root.querySelectorAll("*").forEach((el) => {
+    if (el.shadowRoot) results.push(...queryDeep(el.shadowRoot, selector));
+  });
+  return results;
+}
+
+function applyDataValues(root, record) {
+  queryDeep(root, "[gg-data-key]").forEach((el) => {
+    const path = el.getAttribute("gg-data-key");
+    const value = path ? getPath(record, path) : record;
+    if (value === undefined) return;
+    el.setAttribute("gg-data-value", JSON.stringify(value));
+  });
+}
+
 function populateFormFields(root, record) {
   root.querySelectorAll(
     "input[name], select[name], textarea[name]",
@@ -41,7 +59,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 +72,74 @@ 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);
+        applyDataValues(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);
+      applyDataValues(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);
+      applyDataValues(container, result);
     }
   }
 

package/src/form-action-engine.js

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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);
+  });
 }