@definite-app/data-apps 1.0.0

package/scripts/headless-smoke.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// Headless smoke check for a built data-app.
+//
+// Usage: node scripts/headless-smoke.mjs <path-to-built-index.html> [--require-text "<text>"]
+//
+// What it does:
+//   1. Serves the directory containing index.html on a localhost port.
+//   2. Launches Playwright Chromium and navigates to the page.
+//   3. Listens for uncaught exceptions, page crashes, and console errors.
+//   4. Waits for the React root (#root) to render at least one child element,
+//      i.e. the runtime mounted without throwing on import or first render.
+//   5. Optionally waits for a specific text snippet (--require-text), useful
+//      when an example has real preview data and the shell paints fully.
+//   6. Exits non-zero if any pageerror/crash fired, or if the wait timed out.
+//
+// Designed to run identically locally and in CI. The static server is
+// stdlib-only (node:http + node:fs); only chromium is an external dep.
+
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const argv = process.argv.slice(2);
+if (argv.length < 1) {
+  console.error("Usage: node scripts/headless-smoke.mjs <path-to-index.html> [--require-text <text>]");
+  process.exit(2);
+}
+
+const htmlPath = path.resolve(argv[0]);
+let requireText = null;
+for (let i = 1; i < argv.length; i++) {
+  if (argv[i] === "--require-text" && argv[i + 1]) {
+    requireText = argv[i + 1];
+    i++;
+  }
+}
+
+const serveDir = path.dirname(htmlPath);
+const htmlFile = path.basename(htmlPath);
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js":   "text/javascript; charset=utf-8",
+  ".mjs":  "text/javascript; charset=utf-8",
+  ".css":  "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".wasm": "application/wasm",
+  ".parquet": "application/octet-stream",
+  ".map":  "application/json; charset=utf-8",
+};
+
+function startServer() {
+  return new Promise((resolve, reject) => {
+    const server = createServer(async (req, res) => {
+      try {
+        const urlPath = decodeURIComponent((req.url ?? "/").split("?")[0]);
+        const rel = urlPath === "/" ? htmlFile : urlPath.replace(/^\/+/, "");
+        const full = path.join(serveDir, rel);
+        // Prevent path traversal outside serveDir.
+        if (!full.startsWith(serveDir)) {
+          res.statusCode = 403;
+          res.end("forbidden");
+          return;
+        }
+        const s = await stat(full).catch(() => null);
+        if (!s || !s.isFile()) {
+          res.statusCode = 404;
+          res.end("not found");
+          return;
+        }
+        const buf = await readFile(full);
+        res.setHeader("Content-Type", MIME[path.extname(full)] ?? "application/octet-stream");
+        res.setHeader("Cache-Control", "no-store");
+        // Permit cross-origin loaders the runtime might use.
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.end(buf);
+      } catch (err) {
+        res.statusCode = 500;
+        res.end(String(err));
+      }
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (typeof addr !== "object" || !addr) {
+        reject(new Error("failed to determine server address"));
+        return;
+      }
+      resolve({ server, port: addr.port });
+    });
+  });
+}
+
+async function main() {
+  const { server, port } = await startServer();
+  const url = `http://127.0.0.1:${port}/${htmlFile}`;
+  console.log(`[smoke] serving ${serveDir}`);
+  console.log(`[smoke] navigating to ${url}`);
+
+  // Lazy-import Playwright so the script can at least print usage without
+  // requiring the dep to be installed.
+  const { chromium } = await import("playwright");
+  const browser = await chromium.launch();
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+  const pageErrors = [];
+  const consoleErrors = [];
+  page.on("pageerror", (err) => {
+    pageErrors.push(err.message ?? String(err));
+  });
+  page.on("crash", () => {
+    pageErrors.push("page crashed");
+  });
+  page.on("console", (msg) => {
+    if (msg.type() === "error") {
+      consoleErrors.push(msg.text());
+    }
+  });
+
+  let timedOut = false;
+  let textMissing = false;
+  try {
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30_000 });
+    // Wait for React to mount _something_ inside #root. If the runtime throws
+    // on import or the first render crashes, #root stays empty and this times
+    // out.
+    await page.waitForFunction(
+      () => {
+        const root = document.querySelector("#root");
+        return !!root && root.childElementCount > 0;
+      },
+      { timeout: 30_000 },
+    );
+    if (requireText) {
+      // Poll for the text to appear in a visible element. DuckDB-WASM init
+      // + first useDataset can take several seconds.
+      try {
+        await page.waitForFunction(
+          (needle) => {
+            const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+            let node;
+            while ((node = walker.nextNode())) {
+              const text = node.nodeValue ?? "";
+              if (!text.includes(needle)) continue;
+              let el = node.parentElement;
+              while (el) {
+                if (el.offsetParent !== null) return true;
+                el = el.parentElement;
+              }
+            }
+            return false;
+          },
+          requireText,
+          { timeout: 30_000 },
+        );
+      } catch {
+        textMissing = true;
+      }
+    } else {
+      // Settle for non-text-required runs so deferred runtime errors get
+      // captured by pageerror.
+      await page.waitForTimeout(2000);
+    }
+  } catch (err) {
+    timedOut = true;
+    pageErrors.push(`navigation/wait failed: ${err?.message ?? err}`);
+  } finally {
+    await browser.close();
+    server.close();
+  }
+
+  const failed = pageErrors.length > 0 || timedOut || textMissing;
+  if (consoleErrors.length > 0) {
+    console.log("[smoke] console.error messages (informational, non-fatal):");
+    for (const e of consoleErrors) console.log(`  - ${e}`);
+  }
+  if (pageErrors.length > 0) {
+    console.log("[smoke] page errors:");
+    for (const e of pageErrors) console.log(`  - ${e}`);
+  }
+  if (textMissing) {
+    console.log(`[smoke] required text not found on page: ${JSON.stringify(requireText)}`);
+  }
+  if (failed) {
+    console.log("[smoke] FAIL");
+    process.exit(1);
+  }
+  console.log("[smoke] PASS");
+}
+
+main().catch((err) => {
+  console.error("[smoke] unexpected error:", err);
+  process.exit(1);
+});

package/templates/blank/app.json

@@ -0,0 +1,15 @@
+{
+  "version": 2,
+  "name": "My App",
+  "entry": "src/main.tsx",
+  "resources": {
+    "main": {
+      "kind": "dataset",
+      "source": {
+        "type": "sql",
+        "sql": "SELECT id, STRFTIME(created_at, '%Y-%m-%d') AS createdDate, name FROM LAKE.SCHEMA.my_table LIMIT 10000"
+      },
+      "public": false
+    }
+  }
+}

package/templates/blank/src/App.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+import {
+  useDataset,
+  useSqlQuery,
+  useTheme,
+  AppShell,
+  Card,
+  KpiCard,
+  DataTable,
+  LoadingState,
+  ErrorState,
+} from "@definite/runtime";
+
+export default function App() {
+  const theme = useTheme();
+  const data = useDataset("main");
+
+  const summary = useSqlQuery(
+    data,
+    data.tableRef
+      ? `SELECT COUNT(*)::INTEGER AS totalRows FROM ${data.tableRef}`
+      : "",
+    [],
+  );
+
+  if (data.loading) return <LoadingState message="Loading data..." />;
+  if (data.error) return <ErrorState title="Load Error" message={data.error} />;
+
+  return (
+    <AppShell title="My App" subtitle="Edit src/App.tsx to build your dashboard">
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-4 mb-6">
+        <KpiCard
+          title="Total Rows"
+          value={summary.data?.[0]?.totalRows}
+          format="number"
+          loading={summary.loading}
+        />
+      </div>
+    </AppShell>
+  );
+}

package/templates/blank/src/main.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+import App from "./App";
+
+const rootElement = document.getElementById("root");
+
+if (!rootElement) {
+  throw new Error("Missing #root mount element");
+}
+
+createRoot(rootElement).render(<App />);

package/templates/refined/app.json

@@ -0,0 +1,15 @@
+{
+  "version": 2,
+  "name": "My App",
+  "entry": "src/main.tsx",
+  "resources": {
+    "main": {
+      "kind": "dataset",
+      "source": {
+        "type": "sql",
+        "sql": "SELECT id, STRFTIME(created_at, '%Y-%m-%d') AS createdDate, name FROM LAKE.SCHEMA.my_table LIMIT 10000"
+      },
+      "public": false
+    }
+  }
+}

package/templates/refined/src/App.tsx

@@ -0,0 +1,198 @@
+import React, { useMemo, useState } from "react";
+
+import {
+  buildPalette,
+  CachePopover,
+  DateRangeFilter,
+  DEFAULT_DATE_RANGE_PRESETS,
+  type DateRangeValue,
+  DrillProvider,
+  ErrorState,
+  FiInspectable,
+  LoadingState,
+  PaletteProvider,
+  SaasKpiCard,
+  ShellLayout,
+  Sidebar,
+  type SidebarNavItem,
+  useDataset,
+  useDrill,
+  usePalette,
+  useSqlQuery,
+  useTheme,
+} from "@definite/runtime";
+
+// Default to the "Last 12 months" preset. The filter is applied against the
+// `createdDate` column declared in app.json — change DATE_COLUMN if you
+// rename it.
+const DATE_COLUMN = "createdDate";
+
+function initialDateRange(): DateRangeValue {
+  const preset =
+    DEFAULT_DATE_RANGE_PRESETS.find((p) => p.key === "last12m") ??
+    DEFAULT_DATE_RANGE_PRESETS[0];
+  return preset.compute();
+}
+
+const escSql = (v: string) => v.replace(/'/g, "''");
+
+function buildWhere(from: string, to: string): string {
+  const clauses: string[] = [];
+  if (from) clauses.push(`${DATE_COLUMN} >= '${escSql(from)}'`);
+  if (to) clauses.push(`${DATE_COLUMN} <= '${escSql(to)}'`);
+  return clauses.length > 0 ? ` WHERE ${clauses.join(" AND ")}` : "";
+}
+
+// ── Sidebar navigation ────────────────────────────────────────────────────
+// Each entry maps to a view rendered in the main pane. Icons are single
+// glyphs (Unicode) so apps don't need an icon library; swap for SVGs when
+// you want brand-specific marks.
+const NAV_ITEMS: SidebarNavItem[] = [
+  { id: "overview", label: "Overview", icon: "◧" },
+  { id: "detail",   label: "Detail",   icon: "≣" },
+];
+
+// ── App root ─────────────────────────────────────────────────────────────
+// Pattern: outer <App> holds dataset-loading fallbacks; <InnerApp> runs
+// inside the palette + drill providers so every descendant can usePalette()
+// and useDrill() without prop-drilling.
+
+export default function App() {
+  const { theme, toggleTheme } = useTheme();
+  // Optionally pass a brand accent: buildPalette(theme, { accent: "#FF006E" })
+  const palette = useMemo(() => buildPalette(theme), [theme]);
+
+  const data = useDataset("main");
+  if (data.loading) return <LoadingState message="Loading data…" />;
+  if (data.error) return <ErrorState title="Dataset failed to load" message={data.error} />;
+
+  return (
+    <PaletteProvider value={palette}>
+      <DrillProvider>
+        <InnerApp
+          theme={theme}
+          onThemeChange={(t) => { if (t !== theme) toggleTheme(); }}
+          dataset={data}
+        />
+      </DrillProvider>
+    </PaletteProvider>
+  );
+}
+
+type DatasetHandle = ReturnType<typeof useDataset>;
+
+function InnerApp({ theme, onThemeChange, dataset }: {
+  theme: "dark" | "light";
+  onThemeChange: (t: "dark" | "light") => void;
+  dataset: DatasetHandle;
+}) {
+  const P = usePalette();
+  const [view, setView] = useState("overview");
+  const [dateRange, setDateRange] = useState<DateRangeValue>(initialDateRange);
+
+  const where = useMemo(
+    () => buildWhere(dateRange.from, dateRange.to),
+    [dateRange.from, dateRange.to],
+  );
+
+  // Example query — replace with your own.
+  const summary = useSqlQuery<Array<{ rowCount: number }>>(
+    dataset,
+    dataset.tableRef
+      ? `SELECT COUNT(*)::INTEGER AS rowCount FROM ${dataset.tableRef}${where}`
+      : "",
+    [where],
+  );
+
+  const rowCount = summary.data?.[0]?.rowCount ?? 0;
+  const navItem = NAV_ITEMS.find((n) => n.id === view) ?? NAV_ITEMS[0];
+
+  const sidebar = (
+    <Sidebar
+      logo={{ title: "My App", subtitle: "Replace this" }}
+      navItems={NAV_ITEMS}
+      activeView={view}
+      onViewChange={setView}
+      dateRangeSlot={
+        <DateRangeFilter
+          value={dateRange}
+          onChange={setDateRange}
+          label={null}
+          popoverPlacement="right-start"
+          triggerStyle={{ width: "100%", minWidth: 0, justifyContent: "space-between", padding: "7px 10px", fontSize: 12 }}
+        />
+      }
+      theme={theme}
+      onThemeChange={onThemeChange}
+      footer={<>Live DuckDB · {rowCount.toLocaleString()} rows</>}
+    />
+  );
+
+  const headerRight = (
+    <CachePopover
+      isLoading={summary.loading}
+      rowCount={dataset.cache?.rowCount ?? rowCount}
+      cache={dataset.cache}
+      onRefresh={dataset.refresh}
+    />
+  );
+
+  return (
+    <ShellLayout
+      palette={P}
+      sidebar={sidebar}
+      title={navItem.label}
+      breadcrumb={["App", navItem.label]}
+      headerRight={headerRight}
+    >
+      {view === "overview" && <OverviewView rowCount={rowCount} loading={summary.loading} />}
+      {view === "detail" && <DetailView rowCount={rowCount} />}
+    </ShellLayout>
+  );
+}
+
+function OverviewView({ rowCount, loading }: { rowCount: number; loading: boolean }) {
+  const drill = useDrill();
+  return (
+    <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(220px, 1fr))", gap: 12 }}>
+      {/* Wrap each tile in <FiInspectable> so the host can pick it as Fi context.
+          `fiId` should be stable across renders; pass `datum` for richer prompts. */}
+      <FiInspectable
+        fiId="kpi-total-rows"
+        datasetKey="main"
+        description="Total row count KPI"
+        datum={{ rowCount }}
+      >
+        <SaasKpiCard
+          title="Total rows"
+          value={rowCount.toLocaleString()}
+          sub="in dataset"
+          loading={loading}
+          onClick={() => drill.open({
+            kind: "kpi",
+            id: "rows",
+            title: "Total rows",
+            value: rowCount.toLocaleString(),
+            breadcrumb: "Overview",
+            stats: [["Row count", rowCount.toLocaleString()]],
+            narrative: "Dataset row count. Replace with your own computed stats.",
+            sql: `SELECT COUNT(*) FROM main;`,
+          })}
+        />
+      </FiInspectable>
+    </div>
+  );
+}
+
+function DetailView({ rowCount }: { rowCount: number }) {
+  const P = usePalette();
+  return (
+    <div style={{
+      background: P.card, border: `1px solid ${P.border}`, borderRadius: 10,
+      padding: 24, color: P.sub, fontSize: 14, lineHeight: 1.6,
+    }}>
+      <div style={{ fontSize: 16, color: P.text, fontWeight: 600, marginBottom: 8 }}>Detail view</div>
+      Replace this with your own detail content — tables, forms, drill-downs. The dataset has <b style={{ color: P.text }}>{rowCount.toLocaleString()}</b> rows available via <code style={{ fontFamily: P.mono, background: P.elev, padding: "1px 5px", borderRadius: 3 }}>useSqlQuery(data, "...")</code>.
+    </div>
+  );
+}

package/templates/refined/src/main.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+import App from "./App";
+
+const rootElement = document.getElementById("root");
+
+if (!rootElement) {
+  throw new Error("Missing #root mount element");
+}
+
+createRoot(rootElement).render(<App />);