@altertable/data-app 0.59.1

package/AGENTS.md

@@ -0,0 +1,35 @@
+# @altertable/data-app
+
+## Build an app with this package
+
+Start with [app authoring](docs/app-authoring.md) for the data flow and ownership
+boundaries. Read the documentation for the entry you use:
+
+| Task                             | Documentation                                                      |
+| -------------------------------- | ------------------------------------------------------------------ |
+| Define operations and inputs     | [Contract](docs/contract.md)                                       |
+| Call operations from the browser | [Client](docs/client.md)                                           |
+| Authorize and execute requests   | [Server](docs/server.md)                                           |
+| Serve locally with Bun           | [Bun server](docs/server-bun.md)                                   |
+| Compose views and request states | [React](docs/react.md), [stylesheet](docs/react-styles.md)         |
+| Embed apps in a host             | [Embedding](docs/embed.md), [React embedding](docs/react-embed.md) |
+| Serve a trusted bootstrap        | [Standalone bootstrap](docs/bootstrap.md)                          |
+| Configure identity and theme     | [Config](docs/config.md), [appearance](docs/appearance.md)         |
+| Format values                    | [Format](docs/format.md)                                           |
+
+Import public package entries. Keep SQL, credentials, and execution on the server;
+use `import type` for operation types in browser code. Import the React stylesheet
+once in the browser entry. Edit app-owned files, not installed package files.
+
+Inspect source data and time coverage before choosing an exploration. Build
+findings from observed results and preserve loading, empty, error, and stale
+states. The consuming app's instructions define its paths, commands, and analysis
+context; the [starter template](docs/starter-agent-instructions.md) shows how to
+connect them to this guide.
+
+## Contribute to the package source
+
+When working in this package's source repository, read
+[Contributing](CONTRIBUTING.md) for setup, architecture, and checks. Update docs
+when changing public APIs and run `bun run check` before committing. Do not edit
+generated `dist` files.

package/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Install the versions of Bun and Node.js in `.bun-version` and `.node-version`.
+Node supplies npm for the packed-package check; Bun runs the build, tools, and tests.
+`bunfig.toml` sets `install.exact = true` so newly added dependencies use exact
+versions. Keep `packageManager` aligned with `.bun-version`.
+
+```fish
+bun install --frozen-lockfile
+bun run check
+```
+
+## Repository layout
+
+`src/core` holds shared contracts and data logic. `src/client` owns Fetch transport,
+`src/embed` owns iframe hosting and trusted bootstrap initialization.
+`src/server` owns request handling and the local Bun adapter, and `src/react` owns
+React bindings; `src/react/embed` provides hosts without app UI dependencies.
+Components and their styles live together in `src/react/ui`.
+`docs` describes each public entry. `scripts` builds and checks the published
+artifact. Workflow validation lives in `scripts/check-workflows.sh`, and release
+helpers live in `scripts/release`. Generated `dist` files are ignored; edit source
+instead.
+
+`src/embed/standalone.ts` emits `dist/bootstrap.js` as a self-contained classic
+script for backend HTML. It reads its trusted parent origin from the script
+element; keep app navigation and UI dependencies out of this artifact.
+
+Keep core, client, server, and embed free of React and UI imports. Client and
+server may depend on core; neither may import the other. Embed may depend on core
+and client. Browser code must not import server
+implementations or credentials. React implementations import focused modules,
+not their own public barrel. Preserve the explicit stylesheet export. Public
+exports and their docs are the consumer interface; internal modules may change.
+
+Use repository-root imports (`@/src/...`, `@/package.json`) in source, tests, and
+scripts. Oxlint rejects relative imports and requires declarations for named
+functions (`func-style`). Use method shorthand for object behavior; retain arrows for inline
+callbacks such as collection transforms and hooks. Leave blank lines around
+function declarations, effect hooks, and before returns. Use `useReducer(value =>
+value + 1, 0)` with a `bump…` dispatcher for increment-only counters rather than
+state setters. Run `bun run lint:fix` and `bun run format` for automated fixes.
+The declaration build rewrites aliases to portable relative imports for npm
+consumers.
+
+## Checks
+
+| Command                   | Purpose                                          |
+| ------------------------- | ------------------------------------------------ |
+| `bun run typecheck`       | Validate source, tests, and scripts              |
+| `bun run lint`            | Run type-aware Oxlint checks                     |
+| `bun run format`          | Format source and documentation with Oxfmt       |
+| `bun run test`            | Run contract, transport, and component tests     |
+| `bun run build`           | Emit ESM, declarations, and the React stylesheet |
+| `bun run test:package`    | Check the built npm archive as a consumer        |
+| `bun run test:browser`    | Test embedding against built exports in Chromium |
+| `bun run check:workflows` | Validate workflows and shell scripts             |
+| `bun run check`           | Run all required checks                          |
+
+Add focused tests for changed behavior and update the corresponding entry docs
+when changing public APIs. JSDoc should explain constraints, ownership, units,
+or runtime boundaries without duplicating the full API guide. The packed-package
+check verifies documentation, exports, declarations, browser CSS, and server
+imports. The package retains the
+runtime's Bun test suite; tests use observable output and contract behavior.
+
+Use Conventional Commits (`fix:`, `feat:`, `docs:`) and describe behavior changes
+and verification in pull requests. PR titles are checked against these types.
+Flag breaking API changes explicitly.
+
+Build the package, then run `bash scripts/install-test-browser.sh` once and
+`bun run test:browser` for iframe work. Browser fixtures import public built
+exports; the bootstrap uses the published standalone asset and app scripts are
+bundled independently.
+
+CI runs source and packed-package checks, validates workflow syntax, reviews
+dependency changes, and analyzes JavaScript and TypeScript with CodeQL.
+Dependabot updates Bun dependencies and GitHub Actions weekly. Release Please
+creates version and changelog PRs; merging a release PR publishes the verified
+release tag to npm. See [Releasing](docs/releasing.md) for setup and recovery.
+
+App-authoring instructions belong to a consuming app's `AGENTS.md`; see the
+[starter template](docs/starter-agent-instructions.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Altertable
+
+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/README.md

@@ -0,0 +1,63 @@
+# Altertable Data App
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+TypeScript contracts, a data client, server handlers, and React UI for building
+interactive apps with Altertable data.
+
+## Installation
+
+```fish
+# npm
+npm install @altertable/data-app
+
+# pnpm
+pnpm add @altertable/data-app
+
+# Bun
+bun add @altertable/data-app
+```
+
+For React apps, also install React 19.2 or newer and React DOM 19.2 or newer, then import the stylesheet
+once in your browser entry:
+
+```tsx
+import '@altertable/data-app/react/styles.css';
+import { mountDataApp } from '@altertable/data-app/react';
+```
+
+## Documentation
+
+| Entry                                     | Use                                                   |
+| ----------------------------------------- | ----------------------------------------------------- |
+| [/contract](docs/contract.md)             | Define typed operations, parsers, and date ranges     |
+| [/client](docs/client.md)                 | Call server operations with `fetch`                   |
+| [/server](docs/server.md)                 | Authorize and execute requests on a hosted server     |
+| [/server/bun](docs/server-bun.md)         | Serve an app locally with Bun                         |
+| [/embed](docs/embed.md)                   | Host URL apps or sandboxed JavaScript bundles         |
+| [/bootstrap](docs/bootstrap.md)           | Embed the standalone bootstrap script in backend HTML |
+| [/react/embed](docs/react-embed.md)       | Embed apps with React shells and bridges              |
+| [/react](docs/react.md)                   | Compose views, filters, widgets, and request states   |
+| [/react/styles.css](docs/react-styles.md) | Load the React UI stylesheet                          |
+| [/config](docs/config.md)                 | Define app identity and scope                         |
+| [/appearance](docs/appearance.md)         | Configure brand tokens and viewer theme               |
+| [/format](docs/format.md)                 | Format dates, counts, ratios, and currencies          |
+
+Start with [app authoring](docs/app-authoring.md) for the complete data flow.
+The package ships these docs alongside its built JavaScript and declarations.
+For agent-assisted work, direct your agent to
+`node_modules/@altertable/data-app/AGENTS.md`.
+
+## Development
+
+```fish
+bun install --frozen-lockfile
+bun run check
+```
+
+See [Contributing](CONTRIBUTING.md) for repository structure and focused checks.
+Releases use [Release Please and npm trusted publishing](docs/releasing.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/bootstrap.js

@@ -0,0 +1,388 @@
+(() => {
+  // src/core/bridge.ts
+  var BRIDGE = "altertable:data-app";
+  var MAX_PENDING = 128;
+  var REQUEST_TIMEOUT_MS = 60000;
+  function isBridgeMessage(value) {
+    if (!value || typeof value !== "object")
+      return false;
+    const message = value;
+    return message.channel === BRIDGE && message.version === 1 && typeof message.type === "string" && typeof message.documentId === "string" && message.documentId.length > 0 && message.documentId.length <= 128;
+  }
+  function validId(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(value);
+  }
+
+  // src/core/messages.ts
+  var errorBrand = Symbol.for("@altertable/data-app/MessageRoutingError");
+
+  class MessageRoutingError extends Error {
+    code;
+    requestId;
+    [errorBrand] = true;
+    static [Symbol.hasInstance](value) {
+      return value instanceof Error && value[errorBrand] === true;
+    }
+    constructor(code, message, requestId) {
+      super(message);
+      this.code = code;
+      this.requestId = requestId;
+      this.name = "MessageRoutingError";
+    }
+  }
+  function defineDataQueryRoute(operations) {
+    return {
+      operations,
+      input(value) {
+        if (!value || typeof value !== "object")
+          throw new Error("Invalid query.");
+        const request = value;
+        if (typeof request.operation !== "string" || !request.operation || request.operation.length > 256 || request.operation.includes("/"))
+          throw new Error("Invalid operation.");
+        const operation = operations && Object.hasOwn(operations, request.operation) ? operations[request.operation] : undefined;
+        if (operations && !operation)
+          throw new Error("Unknown operation.");
+        return {
+          operation: request.operation,
+          input: operation ? operation.input(request.input) : request.input
+        };
+      },
+      output(value, input) {
+        if (!value || typeof value !== "object")
+          throw new Error("Invalid data response.");
+        const response = value;
+        if (!Number.isInteger(response.status) || response.status < 100 || response.status > 599 || !response.body || typeof response.body !== "object")
+          throw new Error("Invalid data response.");
+        const body = response.body;
+        if (response.status < 200 || response.status >= 300) {
+          const failure = body.error;
+          throw new MessageRoutingError(typeof failure?.code === "string" ? failure.code : "request_failed", typeof failure?.message === "string" ? failure.message : "Could not load data.", typeof failure?.requestId === "string" ? failure.requestId : undefined);
+        }
+        if (!("data" in body) || typeof body.requestId !== "string" || typeof body.queriedAt !== "string" || !Array.isArray(body.queryIds) || !body.queryIds.every((id) => typeof id === "string"))
+          throw new Error("Invalid data envelope.");
+        if (body.queries !== undefined && (!Array.isArray(body.queries) || !body.queries.every((query) => query && typeof query === "object" && typeof query.name === "string" && typeof query.statement === "string" && (query.queryId === undefined || typeof query.queryId === "string"))))
+          throw new Error("Invalid query evidence.");
+        const operation = operations?.[input.operation];
+        return {
+          status: response.status,
+          body: {
+            ...body,
+            data: operation ? operation.output(body.data) : body.data
+          }
+        };
+      }
+    };
+  }
+
+  // src/client/messages.ts
+  function createMessageClient(routes, transport) {
+    return {
+      async request(route, payload, { signal } = {}) {
+        signal?.throwIfAborted();
+        if (!Object.hasOwn(routes, route))
+          throw new MessageRoutingError("unknown_route", "Unknown message route.");
+        const contract = routes[route];
+        let input;
+        try {
+          input = contract.input(payload);
+        } catch {
+          throw new MessageRoutingError("invalid_payload", "Invalid message payload.");
+        }
+        const response = await transport({ route, payload: input }, signal);
+        signal?.throwIfAborted();
+        try {
+          return contract.output(response, input);
+        } catch (error) {
+          if (error instanceof MessageRoutingError)
+            throw error;
+          throw new MessageRoutingError("invalid_response", "Invalid message response.");
+        }
+      }
+    };
+  }
+
+  // src/client/transport.ts
+  var errorBrand2 = Symbol.for("@altertable/data-app/DataAppError");
+
+  class DataAppError extends Error {
+    code;
+    requestId;
+    [errorBrand2] = true;
+    static [Symbol.hasInstance](value) {
+      return value instanceof Error && value[errorBrand2] === true;
+    }
+    constructor(message, code, requestId) {
+      super(message);
+      this.code = code;
+      this.requestId = requestId;
+      this.name = "DataAppError";
+    }
+  }
+
+  // src/client/iframe.ts
+  function createIframeTransport({
+    parentOrigin,
+    window: frame = window,
+    timeoutMs = REQUEST_TIMEOUT_MS,
+    mode = "url",
+    loadScript
+  }) {
+    if (new URL(parentOrigin).origin !== parentOrigin)
+      throw new Error("Expected an exact parent origin.");
+    const documentId = crypto.randomUUID();
+    let token;
+    let sessionId;
+    let disposed = false;
+    const pending = new Map;
+    let hostState;
+    const stateListeners = new Set;
+    function send(message) {
+      frame.parent.postMessage({ channel: BRIDGE, version: 1, documentId, sessionId, token, ...message }, parentOrigin);
+    }
+    function receiveState(state) {
+      hostState = state;
+      for (const listener of stateListeners)
+        listener(state);
+    }
+    function receive(event) {
+      if (event.origin !== parentOrigin || event.source !== frame.parent || !isBridgeMessage(event.data))
+        return;
+      const message = event.data;
+      if (message.type === "connect") {
+        if (mode === "bundle") {
+          if (!validId(message.token))
+            return;
+          token = message.token;
+        }
+        send({ type: "ready" });
+        return;
+      }
+      if (mode === "bundle" && (!token || message.token !== token))
+        return;
+      if (message.documentId !== documentId)
+        return;
+      if (message.type === "initialize" && validId(message.sessionId)) {
+        if (sessionId && sessionId !== message.sessionId) {
+          for (const entry of pending.values())
+            entry.reject(new DataAppError("The preview reconnected. Retry the request.", "bridge_reset"));
+        }
+        const first = !sessionId;
+        sessionId = message.sessionId;
+        if (first)
+          for (const entry of pending.values())
+            entry.start();
+        receiveState(message.state);
+        if (mode === "url")
+          send({ type: "runtime.ready" });
+        return;
+      }
+      if (!sessionId || message.sessionId !== sessionId)
+        return;
+      if (message.type === "state") {
+        receiveState(message.state);
+        return;
+      }
+      if (message.type === "script.load" && mode === "bundle" && typeof message.javascript === "string") {
+        loadScript?.(message.javascript);
+        return;
+      }
+      if (typeof message.id !== "string")
+        return;
+      const entry = pending.get(message.id);
+      if (!entry)
+        return;
+      if (message.type === "result" && "response" in message) {
+        entry.resolve(message.response);
+      } else if (message.type === "error" && typeof message.code === "string" && typeof message.message === "string") {
+        entry.reject(new MessageRoutingError(message.code, message.message, typeof message.requestId === "string" ? message.requestId : undefined));
+      }
+    }
+    frame.addEventListener("message", receive);
+    function requestMessage(message, signal) {
+      return new Promise((resolve, reject) => {
+        if (disposed)
+          return reject(new DataAppError("The preview has closed.", "bridge_closed"));
+        if (signal?.aborted)
+          return reject(signal.reason);
+        if (pending.size >= MAX_PENDING)
+          return reject(new DataAppError("Too many pending data requests.", "bridge_busy"));
+        const id = crypto.randomUUID();
+        let sent = false;
+        function cleanup() {
+          clearTimeout(timer);
+          signal?.removeEventListener("abort", abort);
+          pending.delete(id);
+        }
+        function abort() {
+          if (sent)
+            send({ type: "cancel", id });
+          cleanup();
+          reject(signal?.reason);
+        }
+        const timer = setTimeout(() => {
+          if (sent)
+            send({ type: "cancel", id });
+          cleanup();
+          reject(new DataAppError(sessionId ? "The data request timed out." : "The preview shell is unavailable. Reload the preview.", sessionId ? "timeout" : "bridge_unavailable"));
+        }, timeoutMs);
+        const entry = {
+          start() {
+            if (sent)
+              return;
+            try {
+              send({
+                type: "request",
+                id,
+                route: message.route,
+                payload: message.payload
+              });
+              sent = true;
+            } catch {
+              cleanup();
+              reject(new DataAppError("The message payload could not be sent.", "invalid_payload"));
+            }
+          },
+          resolve(value) {
+            cleanup();
+            resolve(value);
+          },
+          reject(error) {
+            cleanup();
+            reject(error);
+          }
+        };
+        pending.set(id, entry);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (sessionId)
+          entry.start();
+        else
+          send({ type: "ready" });
+      });
+    }
+    const messages = createMessageClient({ "data.query": defineDataQueryRoute() }, requestMessage);
+    async function queryData(operation, input, signal) {
+      try {
+        return await messages.request("data.query", { operation, input }, { signal });
+      } catch (error) {
+        if (error instanceof MessageRoutingError)
+          throw new DataAppError(error.message, error.code, error.requestId);
+        throw error;
+      }
+    }
+    function disconnect() {
+      send({ type: "disconnect" });
+      sessionId = undefined;
+      for (const entry of pending.values())
+        entry.reject(new DataAppError("The preview has closed.", "bridge_closed"));
+    }
+    function resume(event) {
+      if (event.persisted)
+        send({ type: "ready" });
+    }
+    function dispose() {
+      if (disposed)
+        return;
+      disconnect();
+      disposed = true;
+      frame.removeEventListener("message", receive);
+      frame.removeEventListener("pagehide", disconnect);
+      frame.removeEventListener("pageshow", resume);
+      stateListeners.clear();
+    }
+    frame.addEventListener("pagehide", disconnect);
+    frame.addEventListener("pageshow", resume);
+    if (mode === "url")
+      send({ type: "ready" });
+    return {
+      request: requestMessage,
+      transport: queryData,
+      dispose,
+      mode,
+      snapshot() {
+        return hostState;
+      },
+      subscribe(listener) {
+        stateListeners.add(listener);
+        return () => {
+          stateListeners.delete(listener);
+        };
+      },
+      ready() {
+        send({ type: "runtime.ready" });
+      },
+      fail() {
+        send({ type: "runtime.error" });
+      }
+    };
+  }
+  var bridgeKey = Symbol.for("altertable.localFrameBridge");
+  var installedKey = Symbol.for("altertable.installedTransport");
+  function installDataAppTransport(bridge, frame = window) {
+    const target = frame;
+    if (target[installedKey])
+      throw new Error("A data app transport is already installed.");
+    target[bridgeKey] = bridge;
+    target[installedKey] = bridge;
+    return () => {
+      if (target[bridgeKey] === bridge)
+        delete target[bridgeKey];
+      if (target[installedKey] === bridge)
+        delete target[installedKey];
+      bridge.dispose();
+    };
+  }
+
+  // src/embed/bootstrap.ts
+  function startDataAppBootstrap({
+    parentOrigin,
+    window: frame = window
+  }) {
+    let loaded;
+    let failed = false;
+    const bridge = createIframeTransport({
+      parentOrigin,
+      window: frame,
+      mode: "bundle",
+      loadScript(javascript) {
+        if (loaded !== undefined) {
+          if (javascript === loaded) {
+            if (failed)
+              bridge.fail();
+            else
+              bridge.ready();
+          } else
+            bridge.fail();
+          return;
+        }
+        loaded = javascript;
+        try {
+          const script = frame.document.createElement("script");
+          script.textContent = javascript;
+          frame.document.body.append(script);
+          if (!failed)
+            bridge.ready();
+        } catch {
+          reportError();
+        }
+      }
+    });
+    function reportError() {
+      failed = true;
+      bridge.fail();
+    }
+    frame.addEventListener("error", reportError);
+    frame.addEventListener("unhandledrejection", reportError);
+    const uninstall = installDataAppTransport(bridge, frame);
+    return () => {
+      frame.removeEventListener("error", reportError);
+      frame.removeEventListener("unhandledrejection", reportError);
+      uninstall();
+    };
+  }
+
+  // src/embed/standalone.ts
+  var parentOrigin = document.currentScript?.dataset.parentOrigin;
+  if (!parentOrigin)
+    throw new Error("Missing trusted parent origin.");
+  startDataAppBootstrap({ parentOrigin });
+})();