@dvina/widget-kit 0.0.0-stage → 0.0.34

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dvina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/compile.d.ts

@@ -0,0 +1,2 @@
+/** A React widget's source as a browser module (JSX and TypeScript compiled away, imports left as they are). */
+export declare function compileReactWidget(source: string): Promise<{ code: string } | { error: string }>;

package/dist/compile.js

@@ -0,0 +1,18 @@
+// src/runtime/compile.ts
+async function compileReactWidget(source) {
+  try {
+    const { transform } = await import("sucrase");
+    const { code } = transform(source, {
+      transforms: ["jsx", "typescript"],
+      jsxRuntime: "automatic",
+      production: true,
+      filePath: "widget.tsx"
+    });
+    return { code };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+export {
+  compileReactWidget
+};

package/dist/compose.d.ts

@@ -0,0 +1,13 @@
+export type WidgetKind = "html" | "react";
+/** The meta a composed page declares itself with: `<meta name="dvina-widget" content="html|react">`. */
+export declare const WIDGET_PAGE_META: string;
+/** A saved widget as a page of its own: the kit's tokens, stylesheet and script inlined with its code. */
+export declare function composeWidgetPage(input: { kind: WidgetKind; title: string; code: string }): Promise<string>;
+/** Whether a file is a composed widget page, and which kind; null for anything else. */
+export declare function widgetPageKind(page: string): WidgetKind | null;
+/** The widget's own code from a composed page; the text itself for anything else. */
+export declare function widgetSource(page: string): string;
+/** The data a downloaded widget opens with: the reader's own, as it was when they downloaded it. */
+export type WidgetSeedData = { artifactId?: string; version: number; collections: Record<string, Record<string, unknown>> };
+/** A composed page with its seed, for a download; a fresh file id unless one is given. Throws for any other page. */
+export declare function seedWidgetPage(page: string, data: WidgetSeedData, fileId?: string): string;

package/dist/compose.js

@@ -0,0 +1,103 @@
+// src/runtime/compose.ts
+import {
+  kitCss,
+  kitReactScript,
+  kitScript,
+  reactLoaderScript,
+  standaloneScript,
+  tailwindCss,
+  tailwindScript,
+  tokensCss
+} from "./index.js";
+
+// src/runtime/compile.ts
+async function compileReactWidget(source) {
+  try {
+    const { transform } = await import("sucrase");
+    const { code } = transform(source, {
+      transforms: ["jsx", "typescript"],
+      jsxRuntime: "automatic",
+      production: true,
+      filePath: "widget.tsx"
+    });
+    return { code };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// src/runtime/compose.ts
+var WIDGET_PAGE_META = "dvina-widget";
+var START = "<!-- dvina:widget -->";
+var END = "<!-- /dvina:widget -->";
+var escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+var inScript = (text) => text.replace(/<\/(script|style)/gi, "<\\/$1").replace(/<!--/g, "<\\!--");
+var literal = (value) => JSON.stringify(value).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+var STANDALONE_ID = "dvina-standalone";
+var standalone = () => `<script id="${STANDALONE_ID}">${inScript(standaloneScript)}</script>`;
+function head(kind, title, extra = "") {
+  return [
+    '<meta charset="utf-8" />',
+    '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+    `<meta name="${WIDGET_PAGE_META}" content="${kind}" />`,
+    `<title>${escapeHtml(title)}</title>`,
+    `<style id="dvina-tokens">${inScript(tokensCss)}</style>`,
+    `<style id="dvina-kit">${inScript(kitCss)}</style>`,
+    `<script id="dvina-kit-script">${inScript(kitScript)}</script>`,
+    standalone(),
+    extra
+  ].join("");
+}
+async function composeWidgetPage(input) {
+  const title = input.title.trim() || "Widget";
+  if (input.kind === "html") {
+    return `<!doctype html><html lang="en"><head>${head("html", title)}</head><body>${START}
+${input.code}
+${END}</body></html>`;
+  }
+  const compiled = await compileReactWidget(input.code);
+  if ("error" in compiled) throw new Error(`The React widget does not compile: ${compiled.error}`);
+  const react = [
+    `<style type="text/tailwindcss" id="dvina-tailwind">${inScript(tailwindCss)}</style>`,
+    `<script id="dvina-tailwind-script">${inScript(tailwindScript)}</script>`,
+    `<script id="dvina-react-loader">${inScript(reactLoaderScript)}</script>`
+  ].join("");
+  const mount = `var root=document.getElementById("root");window.__dvinaMountReact(root,${literal(compiled.code)},{text:${literal(kitReactScript)}}).catch(function(error){root.textContent=String(error&&error.message||error);});`;
+  return `<!doctype html><html lang="en"><head>${head("react", title, react)}</head><body><div id="root"></div><script type="text/plain" id="dvina-widget-source">${START}
+${inScript(input.code)}
+${END}</script><script>${mount}</script></body></html>`;
+}
+function widgetPageKind(page) {
+  const match = new RegExp(`<meta name="${WIDGET_PAGE_META}" content="(html|react)"`).exec(page.slice(0, 4096));
+  return match ? match[1] : null;
+}
+function widgetSource(page) {
+  const start = page.indexOf(START);
+  const end = page.lastIndexOf(END);
+  if (widgetPageKind(page) === null || start < 0 || end < start) return page;
+  const code = page.slice(start + START.length, end).replace(/^\n/, "").replace(/\n$/, "");
+  return widgetPageKind(page) === "react" ? code.replace(/<\\\/(script|style)/gi, "</$1").replace(/<\\!--/g, "<!--") : code;
+}
+var SEED = /<script type="application\/json" id="dvina-seed">[\s\S]*?<\/script>/;
+function seedWidgetPage(page, data, fileId = crypto.randomUUID()) {
+  if (widgetPageKind(page) === null) throw new Error("Only a composed widget page takes a seed.");
+  const seed = {
+    fileId,
+    ...data.artifactId ? { artifactId: data.artifactId } : {},
+    version: data.version,
+    collections: data.collections
+  };
+  const element = `<script type="application/json" id="dvina-seed">${literal(seed)}</script>`;
+  const end = page.search(/<\/head>/i);
+  if (end < 0) throw new Error("The page has no head to seed.");
+  const head2 = page.slice(0, end).replace(SEED, "");
+  const addition = head2.includes(`id="${STANDALONE_ID}"`) ? element : element + standalone();
+  return head2 + addition + page.slice(end);
+}
+export {
+  WIDGET_PAGE_META,
+  composeWidgetPage,
+  seedWidgetPage,
+  widgetPageKind,
+  widgetSource
+};

package/dist/db.d.ts

@@ -0,0 +1,36 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+export type Doc = { [key: string]: JsonValue };
+export type Collections = Record<string, Record<string, Doc>>;
+export type Snapshot = { version: number; collections: Collections };
+export type Op = { op: "set" | "update" | "delete"; collection: string; id: string; doc?: Doc };
+export type Changed = { collection: string; id: string; doc: Doc | null };
+/** How long writes gather before they go to the transport as one batch. */
+export declare const WRITE_BATCH_MS: number;
+export interface DbTransport {
+  read(): Promise<Snapshot>;
+  apply(ops: Op[]): Promise<{ version: number; changed: Changed[] }>;
+}
+export type ListOptions = {
+  where?: Doc | ((doc: Doc & { id: string }) => boolean);
+  orderBy?: string | [string, "asc" | "desc"];
+  limit?: number;
+};
+export interface Collection {
+  get(id: string): Promise<(Doc & { id: string }) | null>;
+  list(options?: ListOptions): Promise<Array<Doc & { id: string }>>;
+  set(id: string, doc: Doc): Promise<void>;
+  update(id: string, patch: Doc): Promise<void>;
+  delete(id: string): Promise<void>;
+  subscribe(listener: () => void): () => void;
+}
+export interface Db {
+  collection(name: string): Collection;
+}
+export interface KeyValueStorage {
+  get(key: string): Promise<JsonValue | undefined>;
+  set(key: string, value: JsonValue): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: { prefix?: string }): Promise<string[]>;
+}
+/** `dvina.use('db')` and `dvina.use('storage')` over one transport. */
+export declare function createDb(transport: DbTransport, onError?: (error: Error) => void): { db: Db; storage: KeyValueStorage };

package/dist/db.js

@@ -0,0 +1,156 @@
+// src/runtime/db.ts
+var WRITE_BATCH_MS = 300;
+var NAME = /^[A-Za-z0-9_.:-]{1,128}$/;
+function checkName(kind, value) {
+  if (typeof value !== "string" || !NAME.test(value)) {
+    throw new Error(`A ${kind} is 1\u2013128 letters, digits or . _ : - ("${String(value)}" is not).`);
+  }
+}
+function compare(a, b) {
+  if (a === b) return 0;
+  if (a === void 0 || a === null) return 1;
+  if (b === void 0 || b === null) return -1;
+  return a < b ? -1 : 1;
+}
+function createStore(transport, onError) {
+  let snapshot = null;
+  let loading = null;
+  let queue = [];
+  let timer = 0;
+  let inFlight = false;
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => listeners.forEach((listener) => listener());
+  function load(force = false) {
+    if (snapshot && !force) return Promise.resolve(snapshot);
+    if (loading && !force) return loading;
+    loading = transport.read().then(
+      (read) => {
+        loading = null;
+        snapshot = { version: read.version, collections: structuredClone(read.collections) };
+        for (const { op } of queue) applyLocally(op);
+        notify();
+        return snapshot;
+      },
+      (error) => {
+        loading = null;
+        throw error;
+      }
+    );
+    return loading;
+  }
+  function applyLocally(op) {
+    if (!snapshot) return;
+    const docs = snapshot.collections[op.collection] ??= {};
+    if (op.op === "delete") delete docs[op.id];
+    else if (op.op === "set") docs[op.id] = structuredClone(op.doc ?? {});
+    else docs[op.id] = { ...docs[op.id] ?? {}, ...structuredClone(op.doc ?? {}) };
+  }
+  async function flush() {
+    timer = 0;
+    if (inFlight || queue.length === 0) return;
+    inFlight = true;
+    const batch = queue;
+    queue = [];
+    try {
+      const result = await transport.apply(batch.map(({ op }) => op));
+      if (snapshot) {
+        snapshot.version = result.version;
+        for (const { collection, id, doc } of result.changed) {
+          const docs = snapshot.collections[collection] ??= {};
+          if (doc === null) delete docs[id];
+          else docs[id] = doc;
+        }
+        for (const { op } of queue) applyLocally(op);
+      }
+      batch.forEach(({ settle }) => settle());
+      notify();
+    } catch (error) {
+      const reason = error instanceof Error ? error : new Error(String(error));
+      batch.forEach(({ settle }) => settle(reason));
+      onError(reason);
+      await load(true).catch(() => void 0);
+    } finally {
+      inFlight = false;
+      if (queue.length) schedule();
+    }
+  }
+  function schedule() {
+    if (!timer) timer = window.setTimeout(() => void flush(), WRITE_BATCH_MS);
+  }
+  async function write(op) {
+    checkName("collection", op.collection);
+    checkName("document id", op.id);
+    await load();
+    return new Promise((resolve, reject) => {
+      applyLocally(op);
+      queue.push({ op, settle: (error) => error ? reject(error) : resolve() });
+      notify();
+      schedule();
+    });
+  }
+  return {
+    load,
+    /** Reads the host's data again (the frame came back into view), unless writes are on their way. */
+    refresh() {
+      if (snapshot && !inFlight && queue.length === 0) void load(true).catch(() => void 0);
+    },
+    collection(name) {
+      checkName("collection", name);
+      const docs = () => snapshot?.collections[name] ?? {};
+      return Object.freeze({
+        async get(id) {
+          await load();
+          const doc = docs()[id];
+          return doc ? { ...structuredClone(doc), id } : null;
+        },
+        async list(options = {}) {
+          await load();
+          let rows = Object.entries(docs()).map(([id, doc]) => ({ ...structuredClone(doc), id }));
+          const { where, orderBy, limit } = options;
+          if (typeof where === "function") rows = rows.filter(where);
+          else if (where) rows = rows.filter((row) => Object.entries(where).every(([key, value]) => row[key] === value));
+          if (orderBy) {
+            const [field, direction] = Array.isArray(orderBy) ? orderBy : [orderBy, "asc"];
+            rows.sort((a, b) => compare(a[field], b[field]) * (direction === "desc" ? -1 : 1));
+          }
+          return typeof limit === "number" ? rows.slice(0, Math.max(0, limit)) : rows;
+        },
+        set: (id, doc) => write({ op: "set", collection: name, id, doc }),
+        update: (id, patch) => write({ op: "update", collection: name, id, doc: patch }),
+        delete: (id) => write({ op: "delete", collection: name, id }),
+        /** Calls back whenever the collection may have changed (a write here, or fresh data from the host). */
+        subscribe(listener) {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        }
+      });
+    }
+  };
+}
+var KV_COLLECTION = "_kv";
+function createDb(transport, onError = () => void 0) {
+  const store = createStore(transport, onError);
+  const refresh = () => store.refresh();
+  window.addEventListener("focus", refresh);
+  document.addEventListener("visibilitychange", () => document.visibilityState === "visible" && refresh());
+  const db = Object.freeze({
+    collection: (name) => store.collection(name)
+  });
+  const kv = () => store.collection(KV_COLLECTION);
+  const storage = Object.freeze({
+    async get(key) {
+      return (await kv().get(key))?.value;
+    },
+    set: (key, value) => kv().set(key, { value }),
+    delete: (key) => kv().delete(key),
+    async list(options = {}) {
+      const rows = await kv().list();
+      return rows.map((row) => row.id).filter((key) => !options.prefix || key.startsWith(options.prefix));
+    }
+  });
+  return { db, storage };
+}
+export {
+  WRITE_BATCH_MS,
+  createDb
+};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/** The kit's tokens (`--dv-*`), light and dark, in their layer: inlined first wherever the kit is used. */
+export declare const tokensCss: string;
+/** The kit's stylesheet: fonts, bare elements, classes and the SVG kit; no tokens (tokensCss). */
+export declare const kitCss: string;
+/** The kit's script, an IIFE: icons, slider fills, SVG arrow heads, `window.Dvina` (chart themes, formatters). */
+export declare const kitScript: string;
+/** The React components as an IIFE that reads `window.React` and sets `window.DvinaKit`. */
+export declare const kitReactScript: string;
+/** React mode's loader, an IIFE: React from its pinned CDN, the kit's components, then the widget module mounted. */
+export declare const reactLoaderScript: string;
+/** A downloaded widget's data on its own, an IIFE: `window.dvina` over its seed and localStorage, when no viewer set one. */
+export declare const standaloneScript: string;
+/** Tailwind's theme over the kit's tokens, as text for a text/tailwindcss style; React artifacts only. */
+export declare const tailwindCss: string;
+/** Tailwind v4's browser build (pinned), which compiles that theme and the classes it finds in the page. */
+export declare const tailwindScript: string;