gg-wf-scripts 2.5.0 → 2.8.0

package/src/form-action-engine.js

@@ -1,149 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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/form-visibility.js

@@ -1,122 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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/log.js

@@ -1,34 +0,0 @@
-/**
- * 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/helpers/path.js

@@ -1,4 +0,0 @@
-/** 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

@@ -1,60 +0,0 @@
-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";
-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";
-import { initFormActionEngine } from "./form-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 {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({ context = {}, auth, debug = false } = {}) {
-  return {
-    addQuery: registerQuery,
-    addAction: registerAction,
-    addFormAction: registerFormAction,
-    start() {
-      function run() {
-        if (auth) initAuth(context, auth);
-        initSwitchEngine();
-        initQueryParams();
-        initDialog();
-        initBridges();
-        initFormVisibility();
-        initDataEngine(context, { debug });
-        initActionEngine(context, { debug });
-        initFormActionEngine(context, { debug });
-      }
-
-      if (document.readyState === "loading") {
-        document.addEventListener("DOMContentLoaded", run);
-      } else {
-        run();
-      }
-    },
-  };
-}

package/src/queries.js

@@ -1,14 +0,0 @@
-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 {(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,144 +0,0 @@
-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 () => {
-    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),
-  );
-
-  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);
-  });
-}

package/src/switch-engine.js

@@ -1,22 +0,0 @@
-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);
-}