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

gg-wf-scripts 1.0.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 (15) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,265 @@
+# 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.
+## Install
+```
+npm install gg-scripts
+```
+## Quick start
+Create a site-specific entry file, register your queries and actions, then bundle it with esbuild.
+```js
+import { init } from "gg-wf-scripts";
+const app = init({
+  supabaseUrl: "https://your-project.supabase.co",
+  supabaseKey: "your-publishable-key",
+});
+app.addQuery("posts_list", async (sb) => {
+  const { data } = await sb
+    .from("posts")
+    .select("*")
+    .order("created_at", { ascending: false });
+  return data ?? [];
+});
+app.addAction("delete_post", async (sb, { id }) => {
+  const { error } = await sb.from("posts").delete().eq("id", id);
+  return error ? { ok: false, error } : { ok: true };
+});
+app.start();
+```
+Bundle with esbuild:
+```
+npx esbuild src/index.js --bundle --outfile=dist/site.js --format=iife --target=es2020 --platform=browser
+```
+Load on your site:
+```html
+<script src="https://your-cdn.com/site.js"></script>
+```
+## Attributes
+### Data binding
+Display data from your queries in the DOM.
+```html
+<!-- Single record: populates [gg-field] descendants -->
+<div gg-data="post_by_id">
+  <h1 gg-field="title">Loading...</h1>
+  <p gg-field="body"></p>
+</div>
+<!-- Form pre-fill: sets value/checked on named inputs -->
+<form gg-data-form="post_by_id">
+  <input name="title" />
+  <textarea name="body"></textarea>
+</form>
+<!-- List: clones the template for each record -->
+<ul gg-data-list="posts_list">
+  <li gg-list-template>
+    <h3 gg-field="title"></h3>
+    <span gg-field="author.name"></span>
+  </li>
+</ul>
+```
+`gg-field` supports dot-paths for nested data (e.g. `author.name`).
+#### Re-running on URL changes
+Add `gg-data-on` to re-run a query when specific URL params change:
+```html
+<div gg-data="post_by_id" gg-data-on="id">
+  <h1 gg-field="title"></h1>
+</div>
+```
+### URL query params
+Read and write URL query params declaratively.
+```html
+<!-- On click, set ?modal=view&id=42 -->
+<button gg-query-set="modal:view,id:42">Open</button>
+<!-- On click, remove ?modal and ?id -->
+<button gg-query-remove="modal,id">Close</button>
+```
+### Content switcher
+Show/hide children based on a state value.
+```html
+<!-- State driven by URL param ?view=... -->
+<div gg-switch-query="view">
+  <section gg-case="">Pick a view</section>
+  <section gg-case="list">List view</section>
+  <section gg-case="grid">Grid view</section>
+</div>
+<!-- State driven by a field on the nearest gg-data record -->
+<span gg-switch-field="status">
+  <span gg-case="published">Published</span>
+  <span gg-case="draft">Draft</span>
+  <span gg-case="">Unknown</span>
+</span>
+```
+`gg-case=""` acts as the default/empty state.
+### Dialog
+A single `<dialog>` element is managed automatically via the `modal` URL param.
+```html
+<div gg-query-set="modal:confirm,id:42">Delete</div>
+<dialog>
+  <p>Are you sure?</p>
+  <button gg-query-remove="modal,id">Cancel</button>
+</dialog>
+```
+Setting `?modal=...` opens the dialog. Removing it (or pressing Escape, or clicking the backdrop) closes it. Back button navigation is handled automatically.
+### Auth and role gating
+Show or hide elements based on Supabase auth state.
+```html
+<a href="/login" gg-auth="false">Log in</a>
+<a href="/account" gg-auth="true">My account</a>
+<a href="/admin" gg-role="superuser">Admin panel</a>
+```
+`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 visibility
+Conditionally show/hide elements based on form field values.
+```html
+<form>
+  <label><input type="radio" name="reason" value="scheduling" /> Scheduling</label>
+  <label><input type="radio" name="reason" value="other" /> Other</label>
+  <div gg-visible-when="reason:other">
+    <input type="text" name="other_reason" placeholder="Please specify" />
+  </div>
+</form>
+```
+Hidden elements get `display: none`, `inert`, and `aria-hidden="true"`. Transitions are a 200ms opacity fade. Use `gg-form-scope` on a non-`<form>` ancestor when `closest("form")` can't reach the inputs (e.g. shadow DOM).
+### Actions
+Run mutations on click. Actions receive the Supabase client and a data object.
+```html
+<!-- Simple action, no data needed -->
+<button gg-action="sign_out">Sign out</button>
+<!-- Action with explicit data -->
+<button gg-action="update_status" gg-action-data="status:archived">Archive</button>
+<!-- Inside a data list, the action automatically receives the row's record -->
+<ul gg-data-list="posts_list">
+  <li gg-list-template>
+    <h3 gg-field="title"></h3>
+    <button gg-action="delete_post">Delete</button>
+  </li>
+</ul>
+```
+When an action is inside a `gg-data` or `gg-data-list` container, it automatically receives the record as its data. Explicit `gg-action-data` values are merged on top (and win on conflict).
+Action functions should return `{ ok: true }` or `{ ok: false, error }`:
+```js
+app.addAction("delete_post", async (sb, { id }) => {
+  const { error } = await sb.from("posts").delete().eq("id", id);
+  return error ? { ok: false, error } : { ok: true };
+});
+```
+## Config
+### `init(options)`
+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) |
+### Auth config
+| 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. |
+Example:
+```js
+const app = init({
+  supabaseUrl: "...",
+  supabaseKey: "...",
+  auth: {
+    roleQuery: async (sb, userId) => {
+      const { data } = await sb
+        .from("user_roles")
+        .select("role")
+        .eq("user_id", userId)
+        .single();
+      return data?.role ?? null;
+    },
+  },
+});
+```
+### `app.addQuery(id, fn)`
+Register a data query. `fn` receives `(sb)` and should 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 }`.
+### `app.start()`
+Initializes all engines and starts listening for DOM events. Call this after registering all queries and actions.
+## Exports
+The library also exports utility functions for use in your queries and actions:
+```js
+import {
+  init,
+  getPath,            // resolve dot-paths on objects
+  populateFields,     // set [gg-field] descendants from a record
+  setSwitchState,     // write gg-switch-state on an element
+  applySwitchState,   // toggle [gg-case] children to match state
+  setQueryParams,     // programmatically set URL params
+  removeQueryParams,  // programmatically remove URL params
+} from "gg-wf-scripts";
+```

package/package.json ADDED Viewed

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

package/src/action-engine.js ADDED Viewed

@@ -0,0 +1,58 @@
+import { actionRegistry } from "./actions.js";
+function parseActionData(el) {
+  const attr = el.getAttribute("gg-action-data");
+  if (!attr) return {};
+  const data = {};
+  attr
+    .split(",")
+    .filter(Boolean)
+    .forEach((pair) => {
+      const [key, value] = pair.split(":");
+      if (key?.trim()) data[key.trim()] = value?.trim() ?? "";
+    });
+  return data;
+}
+function findRecord(el) {
+  let node = el.parentElement;
+  while (node) {
+    if (node.__ggRecord) return node.__ggRecord;
+    node = node.parentElement;
+  }
+  return null;
+}
+export function initActionEngine(sb) {
+  async function handleAction(el) {
+    const id = el.getAttribute("gg-action");
+    const action = actionRegistry[id];
+    if (!action) {
+      console.warn(`[gg-action] no action registered for "${id}"`);
+      return;
+    }
+    const record = findRecord(el);
+    const explicit = parseActionData(el);
+    const data = record ? { ...record, ...explicit } : explicit;
+    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);
+    }
+  }
+  document.addEventListener("click", (e) => {
+    const trigger = e.target.closest("[gg-action]");
+    if (trigger) handleAction(trigger);
+  });
+  document.addEventListener("gg:shadow:click", (e) => {
+    const trigger = e.detail.target.closest("[gg-action]");
+    if (trigger) handleAction(trigger);
+  });
+}

package/src/actions.js ADDED Viewed

@@ -0,0 +1,13 @@
+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 }.
+ */
+export function registerAction(id, fn) {
+  actionRegistry[id] = fn;
+}

package/src/auth.js ADDED Viewed

@@ -0,0 +1,28 @@
+export async function initAuth(sb, roleQuery) {
+  async function applyAuthAttrs(userId) {
+    const body = document.body;
+    if (!userId) {
+      body.setAttribute("gg-auth", "false");
+      body.removeAttribute("gg-role");
+      return;
+    }
+    body.setAttribute("gg-auth", "true");
+    if (roleQuery) {
+      const role = await roleQuery(sb, userId);
+      if (role) {
+        body.setAttribute("gg-role", role);
+      } else {
+        body.removeAttribute("gg-role");
+      }
+    }
+  }
+  const {
+    data: { user },
+  } = await sb.auth.getUser();
+  applyAuthAttrs(user?.id ?? null);
+  sb.auth.onAuthStateChange((_event, session) => {
+    applyAuthAttrs(session?.user?.id ?? null);
+  });
+}

package/src/bridges.js ADDED Viewed

@@ -0,0 +1,31 @@
+import { setSwitchState } from "./helpers/dom.js";
+import { onQueryChanged } from "./query-params.js";
+export function initBridges() {
+  // ---- gg-switch-query: URL params → gg-switch-state ----
+  // On any URL param change, mirror its value onto matching
+  // [gg-switch-query="<key>"] elements' gg-switch-state.
+  onQueryChanged((key, value) => {
+    document
+      .querySelectorAll(`[gg-switch-query="${CSS.escape(key)}"]`)
+      .forEach((el) => setSwitchState(el, value));
+  });
+  // Initial-load pass: read current URL params and set state for every
+  // [gg-switch-query] on the page, so we don't flash before the first change.
+  const params = new URLSearchParams(window.location.search);
+  document.querySelectorAll("[gg-switch-query]").forEach((el) => {
+    const key = el.getAttribute("gg-switch-query");
+    setSwitchState(el, params.get(key));
+  });
+  // ---- webflow:emit → Webflow IX ----
+  window.addEventListener("load", () => {
+    Webflow.push(() => {
+      const wfIx = Webflow.require("ix3");
+      document.addEventListener("webflow:emit", (e) => {
+        wfIx.emit(e.detail.event);
+      });
+    });
+  });
+}

package/src/data-engine.js ADDED Viewed

@@ -0,0 +1,139 @@
+import { getPath } from "./helpers/path.js";
+import {
+  populateFields,
+  setSwitchState,
+  applySwitchState,
+} from "./helpers/dom.js";
+import { queryRegistry } from "./queries.js";
+import { onQueryChanged } from "./query-params.js";
+function applySwitchFields(root, record) {
+  root.querySelectorAll("[gg-switch-field]").forEach((el) => {
+    const path = el.getAttribute("gg-switch-field");
+    const value = getPath(record, path);
+    setSwitchState(el, value);
+    applySwitchState(el);
+  });
+}
+function populateFormFields(root, record) {
+  root.querySelectorAll(
+    "input[name], select[name], textarea[name]",
+  ).forEach((el) => {
+    const name = el.getAttribute("name");
+    const value = getPath(record, name);
+    if (value == null) return;
+    if (el instanceof HTMLInputElement) {
+      if (el.type === "checkbox") {
+        el.checked = Boolean(value);
+      } else if (el.type === "radio") {
+        el.checked = String(el.value) === String(value);
+      } else {
+        el.value = String(value);
+      }
+    } else {
+      el.value = String(value);
+    }
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    el.dispatchEvent(new Event("change", { bubbles: true }));
+  });
+}
+export function initDataEngine(sb) {
+  async function runQuery(container) {
+    const isList = container.hasAttribute("gg-data-list");
+    const isForm = container.hasAttribute("gg-data-form");
+    const id = container.getAttribute(
+      isList ? "gg-data-list" : isForm ? "gg-data-form" : "gg-data",
+    );
+    const query = queryRegistry[id];
+    if (!query) {
+      console.warn(`[gg-data] no query registered for "${id}"`);
+      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 template = container.querySelector("[gg-list-template]");
+        if (!template) {
+          console.warn(
+            `[gg-data-list] no [gg-list-template] inside "${id}"`,
+          );
+          return;
+        }
+        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;
+        }
+        if (!result) return;
+        container.__ggRecord = result;
+        populateFields(container, result);
+        applySwitchFields(container, result);
+      }
+    } catch (err) {
+      console.error(`[gg-data] query "${id}" failed:`, err);
+    }
+  }
+  // Run all data containers on load
+  document
+    .querySelectorAll("[gg-data], [gg-data-list], [gg-data-form]")
+    .forEach(runQuery);
+  // Re-run queries when matching URL params change
+  onQueryChanged((key) => {
+    document
+      .querySelectorAll(
+        "[gg-data][gg-data-on], [gg-data-list][gg-data-on], [gg-data-form][gg-data-on]",
+      )
+      .forEach((c) => {
+        const keys = c
+          .getAttribute("gg-data-on")
+          .split(",")
+          .map((s) => s.trim());
+        if (keys.includes(key)) runQuery(c);
+      });
+  });
+}

package/src/dialog.js ADDED Viewed

@@ -0,0 +1,86 @@
+import { removeQueryParams, onQueryChanged } from "./query-params.js";
+function stopLenis() {
+  if (typeof lenis !== "undefined") lenis.stop();
+}
+function startLenis() {
+  if (typeof lenis !== "undefined") lenis.start();
+}
+function openDialog() {
+  const dialog = document.querySelector("dialog");
+  if (!dialog) return;
+  dialog.removeAttribute("aria-hidden");
+  dialog.removeAttribute("inert");
+  dialog.showModal();
+  stopLenis();
+}
+function closeDialog() {
+  const dialog = document.querySelector("dialog");
+  if (!dialog) return;
+  dialog.setAttribute("aria-hidden", "true");
+  dialog.setAttribute("inert", "");
+  dialog.close();
+  startLenis();
+}
+function dismissViaUrlOrDirect() {
+  const modalParam = new URLSearchParams(window.location.search).get("modal");
+  if (modalParam) {
+    removeQueryParams(["modal", "id"]);
+  } else {
+    closeDialog();
+  }
+}
+function syncDialogToUrl() {
+  const modalParam = new URLSearchParams(window.location.search).get("modal");
+  if (modalParam) {
+    openDialog();
+  } else {
+    closeDialog();
+  }
+}
+export function initDialog() {
+  // Subscribe to query param changes — open/close when "modal" changes
+  onQueryChanged((key, value) => {
+    if (key !== "modal") return;
+    if (value) {
+      openDialog();
+    } else {
+      closeDialog();
+    }
+  });
+  // Inbound events from external code
+  document.addEventListener("gg:dialog:open", openDialog);
+  document.addEventListener("gg:dialog:close", closeDialog);
+  // Backdrop click
+  document.addEventListener("click", (e) => {
+    if (!e.target.matches("dialog[open]")) return;
+    const rect = e.target.getBoundingClientRect();
+    const outside =
+      e.clientX < rect.left ||
+      e.clientX > rect.right ||
+      e.clientY < rect.top ||
+      e.clientY > rect.bottom;
+    if (outside) dismissViaUrlOrDirect();
+  });
+  // Escape key — preempt the default close so the URL stays source of truth
+  document.addEventListener("cancel", (e) => {
+    if (!e.target.matches("dialog")) return;
+    e.preventDefault();
+    dismissViaUrlOrDirect();
+  });
+  // Back button
+  window.addEventListener("popstate", syncDialogToUrl);
+  // Initial load
+  syncDialogToUrl();
+}

package/src/form-visibility.js ADDED Viewed

@@ -0,0 +1,122 @@
+const TRANSITION_MS = 200;
+function parseConditions(attr) {
+  return attr
+    .split(",")
+    .map((pair) => {
+      const [name, value] = pair.split(":");
+      return { name: name?.trim(), value: value?.trim() };
+    })
+    .filter((p) => p.name && p.value);
+}
+function getFieldValue(scope, name) {
+  const escaped = CSS.escape(name);
+  const inputs = scope.querySelectorAll(
+    `input[name="${escaped}"], select[name="${escaped}"], textarea[name="${escaped}"]`,
+  );
+  if (!inputs.length) return null;
+  const type = (inputs[0].getAttribute("type") || "").toLowerCase();
+  if (type === "radio" || type === "checkbox") {
+    for (const input of inputs) {
+      if (input.checked) return input.value;
+    }
+    return null;
+  }
+  return inputs[0].value.trim();
+}
+function matchesAny(scope, conditions) {
+  return conditions.some(
+    ({ name, value }) => getFieldValue(scope, name) === value,
+  );
+}
+export function initFormVisibility() {
+  // Group all [gg-visible-when] elements by their nearest scope —
+  // either an explicit [gg-form-scope] or a <form>.
+  const scopeTargets = new Map();
+  document.querySelectorAll("[gg-visible-when]").forEach((el) => {
+    if (!Boolean(el.getAttribute("gg-visible-when"))) {
+      return;
+    }
+    const scope = el.closest("[gg-form-scope], form");
+    if (!scope) {
+      console.warn(
+        "[gg-visible-when] element is not inside a <form> or [gg-form-scope]:",
+        el,
+      );
+      return;
+    }
+    if (!scopeTargets.has(scope)) scopeTargets.set(scope, []);
+    scopeTargets.get(scope).push(el);
+  });
+  scopeTargets.forEach((targets, scope) => {
+    const conditions = new WeakMap();
+    const lastState = new WeakMap();
+    const hideTimers = new WeakMap();
+    targets.forEach((el) => {
+      conditions.set(
+        el,
+        parseConditions(el.getAttribute("gg-visible-when")),
+      );
+      el.style.transition = "none";
+      el.style.opacity = "0";
+      el.style.display = "none";
+      el.style.pointerEvents = "none";
+      el.setAttribute("inert", "");
+      el.setAttribute("aria-hidden", "true");
+      lastState.set(el, false);
+    });
+    function show(el) {
+      const pending = hideTimers.get(el);
+      if (pending) {
+        clearTimeout(pending);
+        hideTimers.delete(el);
+      }
+      el.removeAttribute("inert");
+      el.removeAttribute("aria-hidden");
+      el.style.display = "";
+      el.style.pointerEvents = "";
+      requestAnimationFrame(() => {
+        el.style.opacity = "1";
+      });
+    }
+    function hide(el) {
+      el.style.opacity = "0";
+      el.style.pointerEvents = "none";
+      el.setAttribute("inert", "");
+      el.setAttribute("aria-hidden", "true");
+      const t = setTimeout(() => {
+        el.style.display = "none";
+        hideTimers.delete(el);
+      }, TRANSITION_MS);
+      hideTimers.set(el, t);
+    }
+    function evaluate() {
+      targets.forEach((el) => {
+        const shouldShow = matchesAny(scope, conditions.get(el));
+        if (shouldShow === lastState.get(el)) return;
+        lastState.set(el, shouldShow);
+        if (shouldShow) show(el);
+        else hide(el);
+      });
+    }
+    requestAnimationFrame(() => {
+      targets.forEach((el) => {
+        el.style.transition = `opacity ${TRANSITION_MS}ms ease`;
+      });
+      evaluate();
+    });
+    scope.addEventListener("change", evaluate);
+    scope.addEventListener("input", evaluate);
+  });
+}

package/src/helpers/dom.js ADDED Viewed

@@ -0,0 +1,35 @@
+import { getPath } from "./path.js";
+/**
+ * Set textContent on every [gg-field] descendant of `root` to the value
+ * at that field's dot-path on `record`. Null / missing values are left
+ * as-is (keeps whatever the markup's default content was).
+ */
+export function populateFields(root, record) {
+  root.querySelectorAll("[gg-field]").forEach((el) => {
+    const path = el.getAttribute("gg-field");
+    const value = getPath(record, path);
+    if (value != null) el.textContent = String(value);
+  });
+}
+/**
+ * Write a normalized switch state onto an element.
+ * null / undefined become "" so gg-case="" can serve as the empty/default.
+ */
+export function setSwitchState(el, value) {
+  el.setAttribute("gg-switch-state", value == null ? "" : String(value));
+}
+/**
+ * Show the [gg-case] child whose value matches the container's current
+ * gg-switch-state; hide the rest with display:none.
+ */
+export function applySwitchState(container) {
+  const state = container.getAttribute("gg-switch-state") ?? "";
+  Array.from(container.children).forEach((child) => {
+    if (!child.hasAttribute("gg-case")) return;
+    const match = child.getAttribute("gg-case") === state;
+    child.style.display = match ? "" : "none";
+  });
+}

package/src/helpers/path.js ADDED Viewed

@@ -0,0 +1,4 @@
+/** Resolve a dot-path on an object, e.g. getPath(row, "school.name"). */
+export function getPath(obj, path) {
+  return path.split(".").reduce((acc, key) => acc?.[key], obj);
+}

package/src/index.js ADDED Viewed

@@ -0,0 +1,52 @@
+import { createClient } from "@supabase/supabase-js";
+import { registerQuery } from "./queries.js";
+import { registerAction } from "./actions.js";
+import { setSwitchState, applySwitchState, populateFields } from "./helpers/dom.js";
+import { setQueryParams, removeQueryParams, initQueryParams } from "./query-params.js";
+import { initAuth } from "./auth.js";
+import { initSwitchEngine } from "./switch-engine.js";
+import { initDialog } from "./dialog.js";
+import { initBridges } from "./bridges.js";
+import { initFormVisibility } from "./form-visibility.js";
+import { initDataEngine } from "./data-engine.js";
+import { initActionEngine } from "./action-engine.js";
+export { setSwitchState, applySwitchState, populateFields, setQueryParams, removeQueryParams };
+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]
+ *   Returns the user's role string for gg-role gating. If omitted, gg-role is never set.
+ * @returns {{ addQuery: function, addAction: function, start: function }}
+ */
+export function init({ supabaseUrl, supabaseKey, auth }) {
+  return {
+    addQuery: registerQuery,
+    addAction: registerAction,
+    start() {
+      function run() {
+        const sb = createClient(supabaseUrl, supabaseKey);
+        initAuth(sb, auth?.roleQuery);
+        initSwitchEngine();
+        initQueryParams();
+        initDialog();
+        initBridges();
+        initFormVisibility();
+        initDataEngine(sb);
+        initActionEngine(sb);
+      }
+      if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", run);
+      } else {
+        run();
+      }
+    },
+  };
+}

package/src/queries.js ADDED Viewed

@@ -0,0 +1,12 @@
+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.
+ */
+export function registerQuery(id, fn) {
+  queryRegistry[id] = fn;
+}

package/src/query-params.js ADDED Viewed

@@ -0,0 +1,77 @@
+const subscribers = [];
+export function onQueryChanged(callback) {
+  subscribers.push(callback);
+  return () => {
+    const idx = subscribers.indexOf(callback);
+    if (idx >= 0) subscribers.splice(idx, 1);
+  };
+}
+function notify(key, value) {
+  subscribers.forEach((cb) => cb(key, value));
+}
+/**
+ * Set one or more URL query params and notify subscribers.
+ *
+ * @param {Array<{key: string, value: string}>} params - Key/value pairs to set.
+ */
+export function setQueryParams(params) {
+  const url = new URL(window.location);
+  params.forEach(({ key, value }) => url.searchParams.set(key, value));
+  history.pushState({}, "", url);
+  params.forEach(({ key, value }) => notify(key, value));
+}
+/**
+ * Remove one or more URL query params and notify subscribers.
+ *
+ * @param {string[]} keys - Param keys to remove.
+ */
+export function removeQueryParams(keys) {
+  const url = new URL(window.location);
+  keys.forEach((key) => url.searchParams.delete(key));
+  history.pushState({}, "", url);
+  keys.forEach((key) => notify(key, null));
+}
+// ---- click delegation for gg-query-set / gg-query-remove ----
+function handleQueryClick(target) {
+  const setTrigger = target.closest("[gg-query-set]");
+  if (setTrigger) {
+    const params = setTrigger
+      .getAttribute("gg-query-set")
+      .split(",")
+      .filter(Boolean)
+      .map((pair) => {
+        const [key, value] = pair.split(":");
+        return { key: key?.trim(), value: value?.trim() };
+      })
+      .filter((p) => p.key && p.value);
+    if (params.length) setQueryParams(params);
+    return;
+  }
+  const removeTrigger = target.closest("[gg-query-remove]");
+  if (removeTrigger) {
+    const keys = removeTrigger
+      .getAttribute("gg-query-remove")
+      .split(",")
+      .map((k) => k.trim())
+      .filter(Boolean);
+    if (keys.length) removeQueryParams(keys);
+    return;
+  }
+}
+export function initQueryParams() {
+  document.addEventListener("click", (e) => handleQueryClick(e.target));
+  // Shadow-root click forwarder — shadow DOM swallows bubbling, so anything
+  // inside a shadow tree dispatches `gg:shadow:click` with the real target.
+  document.addEventListener("gg:shadow:click", (e) =>
+    handleQueryClick(e.detail.target),
+  );
+}

package/src/switch-engine.js ADDED Viewed

@@ -0,0 +1,22 @@
+import { applySwitchState } from "./helpers/dom.js";
+export function initSwitchEngine() {
+  // Re-apply whenever gg-switch-state changes on any element.
+  new MutationObserver((mutations) => {
+    mutations.forEach((m) => {
+      if (m.attributeName === "gg-switch-state") {
+        applySwitchState(m.target);
+      }
+    });
+  }).observe(document.body, {
+    attributes: true,
+    attributeFilter: ["gg-switch-state"],
+    subtree: true,
+  });
+  // Apply initial state for any elements that already have gg-switch-state
+  // set at load time, so we don't flash all children before the first mutation.
+  document
+    .querySelectorAll("[gg-switch-state]")
+    .forEach(applySwitchState);
+}