npm - @malloydata/malloyyo - Versions diffs - 0.2.23 → 0.2.25 - Mend

@malloydata/malloyyo 0.2.23 → 0.2.25

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 (11) hide show

package/dist/frame-inpage-entry.tsx +23 -3
package/dist/frame-runtime/index.ts +20 -2
package/dist/frame-runtime/runtime.tsx +128 -19
package/dist/frame-wasm-entry.tsx +36 -9
package/dist/index.js +191 -51
package/dist/shared/givens-url.ts +49 -2
package/dist/templates/skills/malloyyo-auto-update/SKILL.md +117 -0
package/dist/templates/skills/malloyyo-data-site/SKILL.md +174 -0
package/dist/templates/skills/malloyyo-data-site/reference/data-to-parquet.md +109 -0
package/dist/templates/skills/malloyyo-data-site/reference/publish-to-github-pages.md +61 -0
package/package.json +1 -1

package/dist/frame-inpage-entry.tsx CHANGED Viewed

@@ -10,14 +10,28 @@ import { mountInPage } from "./frame-runtime/index";
 const info = window.__DASHBOARD__ || {};
 const name = info.name;
-// Reflect committed givens into the shell URL as `?d=<name>&$NAME=…`.
-const givensToUrl = (dashboard, givens) => {
+// Reflect committed givens into the shell URL as `?d=<name>&$NAME=…`, plus any
+// `~key` view-state (useUrlState). A tag-only dashboard runs no custom code, so
+// there's normally no view-state here — but the two namespaces share one query
+// string, so each write re-emits the other's params rather than erasing them.
+let lastGivens = {};
+// Seeded (`~key` -> value, prefix stripped) from what the shell put in the page,
+// so a link's view-state survives the very first givens sync.
+let lastUrlState = Object.fromEntries(
+  Object.entries(window.__INITIAL_URLSTATE__ || {}).map(([k, v]) => [k[0] === "~" ? k.slice(1) : k, v]),
+);
+const shareUrl = (dashboard) => {
   const u = new URL(location.href);
   u.search = "";
   u.searchParams.set("d", dashboard);
-  for (const [k, v] of Object.entries(givens)) if (v != null && String(v) !== "") u.searchParams.set("$" + k, String(v));
+  for (const [k, v] of Object.entries(lastGivens)) if (v != null && String(v) !== "") u.searchParams.set("$" + k, String(v));
+  for (const [k, v] of Object.entries(lastUrlState)) if (v != null) u.searchParams.set("~" + k, String(v));
   return u.pathname + u.search;
 };
+const givensToUrl = (dashboard, givens) => {
+  lastGivens = givens;
+  return shareUrl(dashboard);
+};
 mountInPage({
   root: document.getElementById("root"),
@@ -32,7 +46,13 @@ mountInPage({
       .then((r) => r.json())
       .catch((e) => ({ ok: false, problems: [{ message: String(e) }] })),
   navigate: (dashboard, givens) => {
+    // Leaving this dashboard: carry the drilled givens, drop the view-state.
+    lastUrlState = {};
     location.href = givensToUrl(dashboard, givens);
   },
   syncGivens: (givens) => history.replaceState(null, "", givensToUrl(name, givens)),
+  syncUrlState: (state) => {
+    lastUrlState = state;
+    history.replaceState(null, "", shareUrl(name));
+  },
 });

package/dist/frame-runtime/index.ts CHANGED Viewed

@@ -18,6 +18,7 @@ export {
   useGiven,
   useOptions,
   useQuery,
+  useUrlState,
   mount,
   setHost,
   dashboardInfo,
@@ -59,8 +60,17 @@ export function mountInPage(opts: {
   run: (req: { query?: string; malloy?: string }, givens: Record<string, unknown>) => Promise<unknown>;
   navigate: (dashboard: string, givens: Record<string, unknown>) => void;
   syncGivens: (givens: Record<string, unknown>) => void;
+  /** Mirror useUrlState view-state into the URL as `~key` params. Optional: a
+      host that omits it simply has no shareable view-state (tag-only
+      dashboards run no custom code, so none exists). */
+  syncUrlState?: (state: Record<string, string>) => void;
 }): { unmount: () => void } {
-  setHost({ run: opts.run, navigate: opts.navigate, syncGivens: opts.syncGivens });
+  setHost({
+    run: opts.run,
+    navigate: opts.navigate,
+    syncGivens: opts.syncGivens,
+    syncUrlState: opts.syncUrlState,
+  });
   // bodyReset:false — the dashboard is one element in the app shell, so it must
   // not restyle <body> (the iframe host DOES own the whole document, so it keeps
   // the reset). Returns the React root so the caller can unmount() on teardown.
@@ -80,8 +90,16 @@ export function mountStatic(
     run: (req: { query?: string; malloy?: string }, givens: Record<string, unknown>) => Promise<unknown>;
     navigate: (dashboard: string, givens: Record<string, unknown>) => void;
     syncGivens: (givens: Record<string, unknown>) => void;
+    /** Mirror useUrlState view-state into the URL as `~key` params — a static
+        site's custom components DO use it, so this host should supply it. */
+    syncUrlState?: (state: Record<string, string>) => void;
   },
 ): { unmount: () => void } {
-  setHost({ run: opts.run, navigate: opts.navigate, syncGivens: opts.syncGivens });
+  setHost({
+    run: opts.run,
+    navigate: opts.navigate,
+    syncGivens: opts.syncGivens,
+    syncUrlState: opts.syncUrlState,
+  });
   return mount(Dashboard ?? DefaultDashboard, WIDGETS, opts.root, { bodyReset: false });
 }

package/dist/frame-runtime/runtime.tsx CHANGED Viewed

@@ -9,9 +9,10 @@
 // and posts results back.
 //
 // Injected frame globals (read lazily — script order differs between hosts):
-//   window.__DASHBOARD__      { name, query, title, description? }  (the # artifact tag)
-//   window.__GIVENS__         given specs introspected from the model's given: decls
-//   window.__INITIAL_GIVENS__ URL-seeded given values for shareable links
+//   window.__DASHBOARD__        { name, query, title, description? }  (the # artifact tag)
+//   window.__GIVENS__           given specs introspected from the model's given: decls
+//   window.__INITIAL_GIVENS__   URL-seeded given values ($-prefixed) for shareable links
+//   window.__INITIAL_URLSTATE__ URL-seeded useUrlState view-state (~-prefixed)
 import React, {
   createContext,
   useCallback,
@@ -35,9 +36,10 @@ export const dashboardInfo = () => window.__DASHBOARD__ || {};
 export const givenSpecs = () => window.__GIVENS__ || [];
 // ── host bridge ─────────────────────────────────────────────────────
-// The runtime performs three privileged actions it can't do itself: run a
-// governed query, navigate to a sibling dashboard, and mirror the committed
-// givens into the shareable URL. It delegates all three to a HOST. Two hosts
+// The runtime performs four privileged actions it can't do itself: run a
+// governed query, navigate to a sibling dashboard, mirror the committed givens
+// into the shareable URL, and mirror a custom component's view-state
+// (useUrlState) into it too. It delegates all of them to a HOST. Two hosts
 // implement the contract:
 //   • postMessage host (default) — the sandboxed iframe: posts to the trusted
 //     parent shell, which holds the runner. This is the CUSTOM-dashboard path.
@@ -74,6 +76,9 @@ let host = {
   syncGivens(givens) {
     parent.postMessage({ type: "givens", givens }, "*");
   },
+  syncUrlState(state) {
+    parent.postMessage({ type: "urlstate", state }, "*");
+  },
 };
 /** Swap the host — a tag-only dashboard mounted in the trusted page (mountInPage)
@@ -133,6 +138,74 @@ export function useGiven(name) {
   };
 }
+// ── view-state in the URL (useUrlState) ─────────────────────────────
+// Givens are the GOVERNED QUERY CONTRACT: declared in the model, filter-typed,
+// they drive the auto-rendered controls and are visible to MCP. A custom
+// component that computes its query inputs in JS has other state that belongs
+// in the URL but is not a query parameter — an anagram rack, a Scrabble board,
+// a "reuse letters" checkbox. Stuffing those into givens overloads what a given
+// is (and they aren't in givenSpecs(), so they never rehydrate).
+//
+// useUrlState is that second channel: a useState twin whose value lives in the
+// URL under a `~key` param, on the same parent<->frame transport as givens. The
+// component runs in a sandboxed cross-origin iframe and CANNOT touch the
+// top-level URL itself, so only the runtime + trusted parent can do this.
+const UrlStateCtx = createContext(null);
+/** value -> URL string. Strings pass through verbatim (a readable `~rack=cats`
+    beats `~rack=%22cats%22`); numbers/booleans stringify; everything else is
+    JSON. */
+export function serializeUrlState(v) {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return JSON.stringify(v ?? null);
+}
+/** URL string -> value, typed by the `initial` the caller declared. A value the
+    URL can't produce (a bad number, malformed JSON) falls back to `initial`
+    rather than throwing — a hand-edited link must not white-screen a page. */
+export function deserializeUrlState(raw, initial) {
+  if (typeof initial === "string") return raw;
+  if (typeof initial === "number") {
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : initial;
+  }
+  if (typeof initial === "boolean") return raw === "true" || raw === "1";
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return initial;
+  }
+}
+/** A `useState` twin backed by the browser URL — the dashboard-runtime
+    equivalent of useSearchParams, abstracted over the iframe boundary:
+      const [rack, setRack] = useUrlState("rack", "");        // string
+      const [reuse, setReuse] = useUrlState("reuse", false);  // boolean
+      const [board, setBoard] = useUrlState("board", "........");
+    The value is read from `?~rack=…` on load (else `initial`), and every change
+    is mirrored back (debounced, replaceState — no history spam), so the URL is
+    always shareable/bookmarkable. `setValue` takes a value or an updater fn.
+    Typing follows `initial` (string / number / boolean / JSON-serializable);
+    it has nothing to do with Malloy given types. A value equal to `initial` is
+    dropped from the URL, so defaults never clutter the link. */
+export function useUrlState(key, initial) {
+  const ctx = useContext(UrlStateCtx);
+  if (!ctx) throw new Error("useUrlState must run inside the dashboard runtime");
+  const { state, setKey } = ctx;
+  const raw = state[key];
+  const value = raw === undefined ? initial : deserializeUrlState(raw, initial);
+  // `initial` is usually an inline literal (a fresh array each render), so it
+  // can't be a dep — capture it in a ref the setter reads. The default a key is
+  // declared with doesn't change over a component's life.
+  const initialRef = useRef(initial);
+  initialRef.current = initial;
+  const set = useCallback((next) => setKey(key, next, initialRef.current), [key, setKey]);
+  return [value, set];
+}
 // ── queries as hooks ────────────────────────────────────────────────
 /** Run a query and get plain data back: { rows, result, loading, error }.
     req: { query?: string, malloy?: string, givens?: object }. For charting
@@ -821,25 +894,61 @@ function Root({ Dashboard, extraProps }) {
   useEffect(() => {
     host.syncGivens(committed);
   }, [committed]);
+  // useUrlState's store: `~key` -> serialized string, seeded from the URL. It
+  // starts as the WHOLE seed (not just keys some hook has claimed) so params
+  // belonging to a component that hasn't mounted yet survive the first sync.
+  const urlSeed = useMemo(() => {
+    const s = {};
+    for (const [k, v] of Object.entries(window.__INITIAL_URLSTATE__ || {})) {
+      s[k[0] === "~" ? k.slice(1) : k] = v;
+    }
+    return s;
+  }, []);
+  const [urlState, setUrlState] = useState(urlSeed);
+  const setUrlKey = useCallback((key, next, initial) => {
+    setUrlState((prev) => {
+      const cur = prev[key] === undefined ? initial : deserializeUrlState(prev[key], initial);
+      const v = typeof next === "function" ? next(cur) : next;
+      const s = serializeUrlState(v);
+      if (s === prev[key]) return prev; // no-op set: don't re-render or re-sync
+      const out = { ...prev };
+      // A value back at its default is absent, not empty — keeps links clean.
+      if (s === serializeUrlState(initial)) delete out[key];
+      else out[key] = s;
+      return out;
+    });
+  }, []);
+  // Debounced: view-state is typed into (a rack, a board cell), and Safari
+  // throttles replaceState. Givens commit discretely, so they sync immediately.
+  useEffect(() => {
+    const t = setTimeout(() => host.syncUrlState?.(urlState), 150);
+    return () => clearTimeout(t);
+  }, [urlState]);
+  const urlCtx = useMemo(() => ({ state: urlState, setKey: setUrlKey }), [urlState, setUrlKey]);
   const ctx = useMemo(
     () => ({ givens: committed, draft, setGiven, apply, reset, dirty, autorun }),
     [committed, draft, setGiven, apply, reset, dirty, autorun],
   );
   return (
     <Ctx.Provider value={ctx}>
-      <Dashboard
-        dashboard={dashboardInfo()}
-        givenSpecs={givenSpecs()}
-        givens={committed}
-        setGiven={setGiven}
-        Panel={Panel}
-        filters={filters}
-        useGiven={useGiven}
-        useOptions={useOptions}
-        useQuery={useQuery}
-        runData={runData}
-        {...extraProps}
-      />
+      <UrlStateCtx.Provider value={urlCtx}>
+        <Dashboard
+          dashboard={dashboardInfo()}
+          givenSpecs={givenSpecs()}
+          givens={committed}
+          setGiven={setGiven}
+          Panel={Panel}
+          filters={filters}
+          useGiven={useGiven}
+          useOptions={useOptions}
+          useQuery={useQuery}
+          useUrlState={useUrlState}
+          runData={runData}
+          {...extraProps}
+        />
+      </UrlStateCtx.Provider>
     </Ctx.Provider>
   );
 }

package/dist/frame-wasm-entry.tsx CHANGED Viewed

@@ -16,7 +16,7 @@ import * as duckdb from "@duckdb/duckdb-wasm";
 import { DuckDBWASMConnection } from "@malloydata/db-duckdb/wasm";
 import { API, SingleConnectionRuntime } from "@malloydata/malloy";
 import { mountStatic } from "./frame-runtime/index";
-import { givensFromSearch, givensToParams } from "./shared/givens-url";
+import { givensFromSearch, shareSearch, urlStateFromSearch } from "./shared/givens-url";
 const info = window.__DASHBOARD__ || {};
 const MODEL_FILES = window.__MODEL_FILES__ || {};
@@ -138,11 +138,22 @@ async function run(req: { query?: string; malloy?: string }, givens: Record<stri
 // Same param encoding as the dev server (shared/givens-url); only the path
 // shape differs — sibling .html pages here vs `/?d=` there.
-const givensToUrl = (dashboard: string, givens: Record<string, unknown>) => {
+//
+// The URL carries TWO namespaces — `$given` and `~view-state` (useUrlState) —
+// written by two independent syncs, so each write must re-emit the other's
+// params or it would erase them. Both are cached here, seeded from the URL this
+// page opened with, and every write rebuilds the whole query string.
+let lastGivens: Record<string, unknown> = givensFromSearch(location.search);
+let lastUrlState: Record<string, unknown> = urlStateFromSearch(location.search);
+const dashUrl = (dashboard: string, givens: Record<string, unknown>, urlState: Record<string, unknown>) => {
   const u = new URL(`./${dashboard}.html`, document.baseURI);
-  u.search = givensToParams(givens).toString();
-  return u.pathname + u.search;
+  return u.pathname + shareSearch({ givens, urlState });
 };
+// A drill LEAVES this dashboard: carry the givens it seeded, but not this
+// component's view-state — that belongs to the component being left.
+const navigateUrl = (dashboard: string, givens: Record<string, unknown>) =>
+  dashUrl(dashboard, givens, {});
 // Custom dashboards drive drills by posting to `parent` directly:
 //   parent.postMessage({ type: "navigate", dashboard, givens }, "*")
@@ -157,11 +168,17 @@ function installMessageBridge(name: string) {
     const m = e.data;
     if (!m || typeof m !== "object") return;
     if (m.type === "givens" && m.givens) {
-      history.replaceState(null, "", givensToUrl(name, m.givens));
+      lastGivens = m.givens;
+      history.replaceState(null, "", dashUrl(name, lastGivens, lastUrlState));
+      return;
+    }
+    if (m.type === "urlstate" && m.state) {
+      lastUrlState = m.state;
+      history.replaceState(null, "", dashUrl(name, lastGivens, lastUrlState));
       return;
     }
     if (m.type === "navigate" && typeof m.dashboard === "string") {
-      location.href = givensToUrl(m.dashboard, m.givens || {});
+      location.href = navigateUrl(m.dashboard, m.givens || {});
     }
   });
 }
@@ -173,14 +190,24 @@ export function boot(Dashboard: unknown) {
   // there, here from our own query string, but through the SAME encoder, so the
   // `$` prefix the runtime keys off is preserved. Set before mount: the runtime
   // reads this global lazily when it computes initial given values.
-  (window as any).__INITIAL_GIVENS__ = givensFromSearch(location.search);
+  (window as any).__INITIAL_GIVENS__ = lastGivens;
+  // …and the `~` half: a custom component's useUrlState (a rack, a board) —
+  // view-state, not a query parameter, but just as shareable.
+  (window as any).__INITIAL_URLSTATE__ = lastUrlState;
   installMessageBridge(info.name);
   return mountStatic(Dashboard, {
     root: document.getElementById("root") as HTMLElement,
     run,
     navigate: (dashboard, givens) => {
-      location.href = givensToUrl(dashboard, givens);
+      location.href = navigateUrl(dashboard, givens);
+    },
+    syncGivens: (givens) => {
+      lastGivens = givens;
+      history.replaceState(null, "", dashUrl(info.name, lastGivens, lastUrlState));
+    },
+    syncUrlState: (state) => {
+      lastUrlState = state;
+      history.replaceState(null, "", dashUrl(info.name, lastGivens, lastUrlState));
     },
-    syncGivens: (givens) => history.replaceState(null, "", givensToUrl(info.name, givens)),
   });
 }