@altertable/data-app 0.65.0 → 0.67.0

package/AGENTS.md

@@ -3,8 +3,45 @@
 Build Altertable data apps with `@altertable/data-app`. They render in an iframe
 in Altertable, a chat app, or locally in a browser.
 
-Every analytical app includes CSV export and a story in the built-in toolbar,
+Every data app includes CSV export and a story in the built-in toolbar,
 both derived from the displayed result. Setup and static screens may omit them.
 
 Follow [app authoring](docs/app-authoring.md) for the shared workflow, the data app
 and local data app paths, and task-specific documentation.
+
+## Styling
+
+Use components and typed props first; customize through app-owned `className`
+and public tokens. Follow [Styling](docs/styling.md)
+and [UI quality](docs/ui-quality.md).
+Do not copy package classes onto markup or select private descendants.
+
+## Documentation
+
+Use `<Component>` notation for React components. Keep guidance concise; leave
+prop details to TypeScript and JSDoc. Describe the current API without migration
+or legacy instructions.
+
+## App authoring
+
+Read the matching guide before generating an app. Package contributors follow
+[Contributing](CONTRIBUTING.md).
+
+| Task                                   | Read                                                           |
+| -------------------------------------- | -------------------------------------------------------------- |
+| Choose hosted or local execution       | [App authoring](docs/app-authoring.md)                         |
+| Load data and compose loading states   | [Views](docs/views.md)                                         |
+| Add filters                            | [Variables](docs/variables.md)                                 |
+| Compose visuals, tables, and narrative | [Widgets](docs/widgets.md), [layout](docs/layout.md)           |
+| Define sources and evidence            | [Data context](docs/data-context.md)                           |
+| Present findings and export results    | [Stories and export](docs/stories-and-export.md)               |
+| Format values and appearance           | [Formatting and appearance](docs/formatting-and-appearance.md) |
+
+Use `/react` with declared views and bound widgets. `/react/ui` is for setup,
+static displays, and deliberately custom UI; see [direct composition](docs/ui.md).
+Prefer derivation over repeated configuration. Keep static context outside loading boundaries. Derive labels, findings, and
+exports from the displayed result and its input. Edit app-owned files; installed
+package files are dependencies.
+
+Keep `docs/` focused on knowledge agents need to build data apps. Put package
+implementation, testing, and release guidance in `CONTRIBUTING.md`.

package/CONTRIBUTING.md

@@ -4,6 +4,7 @@ Use the Bun and Node.js versions in `.bun-version` and `.node-version`.
 
 ```fish
 bun install --frozen-lockfile
+bash scripts/install-test-browser.sh
 bun run check
 ```
 
@@ -36,12 +37,21 @@ fallbacks minimal.
 
 ## Verify changes
 
-Tests should tell the package's public usage stories: define an operation,
-authorize and query it, compose a view, or embed an app. Exercise published
-entries so build and export mistakes are observable. Test private logic in
-isolation only when its complexity warrants it, such as cancellation, streaming,
-SQL escaping, or authenticated bridge sessions. Avoid tests that repeat trivial
-helpers, file layout, or every component prop.
+Write high-level public API tests with Vitest in `tests/public-api`. Define an
+operation, authorize and query it, compose a view, or embed an app through
+`@altertable/data-app/<entry>`. Assert consumer-visible results and errors. Supply
+data and failures through public dependency injection; do not import private
+source, fabricate internal state, or assert implementation details. Prefer queries by role and accessible name, or by label for form fields. Scope
+content assertions to the relevant region, status, alert, or dialog; use text
+queries for prose with no meaningful role. Do not invent ARIA roles for tests.
+Group browser workflows by consumer capability in `apps-*.test.ts`; keep tests
+self-contained and setup local until repetition warrants sharing it.
+
+`bun run test` runs the complete suite against the built package. Browser
+workflows launch Chromium through Playwright from Vitest. They use public
+consumer fixtures, an isolated local server, and a fresh browser context per
+test. Build first; run one file with `bun run test tests/public-api/apps-export.test.ts`
+or one workflow with `bun run test -t "workflow name"`.
 
 Update the relevant guide when changing public behavior. In documentation prose,
 write functions as `functionName()` and components as `<ComponentName>`. Keep JSDoc for
@@ -56,16 +66,16 @@ checks. Build before running consumer tests individually.
 | Command                        | Purpose                                             |
 | ------------------------------ | --------------------------------------------------- |
 | `bun run build`                | Build JavaScript, declarations, and injected styles |
+| `bun run check:styles`         | Validate authored styling hooks                     |
 | `bun run typecheck`            | Check source, tests, and scripts                    |
 | `bun run lint`                 | Run type-aware lint checks                          |
 | `bun run lint:md`              | Check Markdown structure and syntax                 |
 | `bun run check:links`          | Validate local files, images, and heading links     |
 | `bun run check:links:external` | Check external URLs (requires network access)       |
 | `bun run format`               | Format source and docs                              |
-| `bun run test`                 | Verify public contracts and complex isolated logic  |
-| `bun run test:package`         | Verify the npm archive as a consumer                |
-| `bun run test:starter`         | Typecheck, lint, and build the starter              |
-| `bun run test:browser`         | Verify browser interactions in Chromium             |
+| `bun run test`                 | Verify high-level public API workflows with Vitest  |
+| `bun run check:package`        | Verify the npm archive as a consumer                |
+| `bun run check:starter`        | Typecheck, lint, and build the starter              |
 | `bun run check:workflows`      | Validate workflows and shell scripts                |
 
 Markdown checks cover all authored `.md` files, including `AGENTS.md` and the
@@ -78,10 +88,40 @@ It skips local development URLs and checks reachability without external heading
 validation. It stays outside required checks because third-party availability and
 rate limits can cause failures unrelated to a change.
 
-For browser changes, run `bash scripts/install-test-browser.sh` once, then
-`bun run test:browser`. Preview UI examples at `/gallery` with
-`bun browser-tests/server.ts`.
+Run `bun run dev` to preview UI examples at `http://127.0.0.1:27418/gallery`
+and a playground at `/playground` (`dev/playground.tsx`, querying the demo
+tables from `dev/seed.ts` that `scripts/dev.ts` seeds). It builds once, then rebuilds `dist` when `src`
+changes; open pages reload on package, fixture, and playground edits. Restart it after changing
+`dev/server.ts`; rerun `bun run build` to refresh declarations. Add `?delay=2000` to a host page URL
+to delay its SQL responses and inspect loading states. It needs Docker: SQL runs
+against a mocked Altertable API
+([altertable-mock](https://github.com/altertable-ai/altertable-mock), DuckDB)
+started with Testcontainers and stopped on exit. Public API tests use their own deterministic consumer fixtures.
+
+Open the **Widgets** tab (`/gallery?view=widgets`) for one ready example of each
+composable data display inside `<VisualizationWidget>`. The other tabs cover
+composed apps, variants, and request states.
 
 Use Conventional Commits and describe behavior changes and verification in PRs.
 Flag breaking API changes. Release Please owns `CHANGELOG.md`; see
-[Releasing](docs/releasing.md) for release setup and recovery.
+[Releasing](https://github.com/altertable-ai/data-app/blob/main/.github/RELEASING.md) for release setup and recovery.
+
+## Focused public API
+
+Keep exports and options focused on concrete app needs. Prefer defaults and
+derivation from existing state over new knobs; keep implementation details private.
+
+For public changes, update the relevant guide, migrate callers and starters,
+and verify published usage. Flag breaking changes in commits and PRs.
+
+Docs help agents generate data apps: show current usage and focused examples.
+Keep package architecture and contributor rules here.
+
+## Component CSS
+
+Keep defaults in authored CSS: inherited values in `tokens.css`, presets in
+`appearance.css`, and optional overrides in native `var()` fallbacks at use sites.
+Use the four layers (`atbl.tokens`, `atbl.base`, `atbl.components`,
+`atbl.interaction`) and shared focus/state rules rather than duplicate control
+paint. Keep geometry local. Document public variables beside declarations or
+consumption sites; update the name contract in `style-contract.ts` when adding hooks.

package/README.md

@@ -38,7 +38,7 @@ For integrating apps into a host, see [embedding](docs/embed.md).
 ## Development
 
 See [Contributing](CONTRIBUTING.md) for repository structure and focused checks.
-Releases use [Release Please and npm trusted publishing](docs/releasing.md).
+Releases use [Release Please and npm trusted publishing](https://github.com/altertable-ai/data-app/blob/main/.github/RELEASING.md).
 
 ## License
 

package/dist/chunks/index-23dktynd.js

@@ -0,0 +1,80 @@
+import {
+  executeDataOperation,
+  toDataOperationFailure
+} from "./index-x69p7cv7.js";
+import {
+  DataAppError2,
+  createHttpTransport2,
+  localFrameBridge,
+  getDataAppTransport2
+} from "./index-ktmvs916.js";
+import {
+  randomUuid
+} from "./index-f5cnbrjz.js";
+import {
+  MessageRoutingError2,
+  defineDataQueryRoute2
+} from "./index-qd5xgx6y.js";
+
+// src/client/data-client.ts
+var dataQueryRoute = defineDataQueryRoute2();
+function createDataClient2(options = {}) {
+  if (options.operations)
+    return createOperationClient({
+      operations: options.operations,
+      lakehouse: options.lakehouse
+    });
+  const http = createHttpTransport2(options);
+  const useHttp = options.endpoint !== undefined || options.fetch !== undefined;
+  return {
+    async query(name, input, { signal } = {}) {
+      const transport = options.transport ?? (useHttp ? http : localFrameBridge()?.transport ?? http);
+      const response = await transport(name, input, signal);
+      const ok = response.status >= 200 && response.status < 300;
+      let body;
+      try {
+        body = dataQueryRoute.output(response, { operation: name, input }).body;
+      } catch (error) {
+        if (signal?.aborted)
+          throw error;
+        if (error instanceof MessageRoutingError2)
+          throw new DataAppError2(error.message, error.code, error.requestId);
+        throw new DataAppError2(ok ? "The data response was invalid." : "Could not load data.", ok ? "invalid_response" : "request_failed");
+      }
+      return { ...body, input };
+    }
+  };
+}
+function createOperationClient(options) {
+  return {
+    async query(name, input, { signal } = {}) {
+      signal?.throwIfAborted();
+      const requestId = randomUuid();
+      if (!Object.hasOwn(options.operations, name))
+        throw new DataAppError2("Unknown data operation.", "not_found", requestId);
+      const lakehouse = options.lakehouse ?? (typeof window === "undefined" ? undefined : getDataAppTransport2()?.lakehouse);
+      if (!lakehouse)
+        throw new DataAppError2("An authorized SQL bridge must be installed first.", "bridge_unavailable", requestId);
+      try {
+        const { body } = await executeDataOperation(options.operations[name], input, {
+          lakehouse,
+          signal: signal ?? new AbortController().signal,
+          requestId,
+          operationName: name
+        });
+        return { ...body, input };
+      } catch (error) {
+        if (signal?.aborted)
+          throw signal.reason;
+        if (error instanceof DataAppError2)
+          throw error;
+        const failure = toDataOperationFailure(error);
+        throw new DataAppError2(failure.message, failure.code, requestId);
+      }
+    }
+  };
+}
+
+export { createDataClient2 };
+
+//# debugId=F1FFBCC98547BBCD64756E2164756E21

package/dist/chunks/index-23dktynd.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/client/data-client.ts"],
+  "sourcesContent": [
+    "import { randomUuid } from '@/src/core/uuid';\nimport { createHttpTransport, DataAppError } from '@/src/client/transport';\nimport { getDataAppTransport, localFrameBridge } from '@/src/client/iframe';\nimport {\n  executeDataOperation,\n  toDataOperationFailure,\n} from '@/src/core/operation';\nimport type { DataOperations, Lakehouse } from '@/src/core/contract';\nimport { defineDataQueryRoute, MessageRoutingError } from '@/src/core/messages';\nimport type { DataTransport } from '@/src/client/transport';\nimport type {\n  DataQueryBody,\n  InputOf,\n  OutputOf,\n} from '@/src/core/operation-types';\nexport type { InputOf, OutputOf } from '@/src/core/operation-types';\n\n/**\n * Parsed operation data and query evidence.\n */\nexport type DataResponse<Output, Input = unknown> = DataQueryBody<Output> & {\n  /** The exact browser input that produced this response. */\n  input: Input;\n};\n\nexport type DataClient<Operations extends DataOperations> = {\n  query<Name extends keyof Operations & string>(\n    name: Name,\n    input: InputOf<Operations[Name]>,\n    options?: { signal?: AbortSignal }\n  ): Promise<\n    DataResponse<OutputOf<Operations[Name]>, InputOf<Operations[Name]>>\n  >;\n};\n\n/** Browser operations and named-operation delivery are mutually exclusive configurations. */\nexport type DataClientOptions<Operations extends DataOperations> =\n  | {\n      operations: Operations;\n      lakehouse?: Lakehouse;\n      transport?: never;\n      endpoint?: never;\n      fetch?: never;\n    }\n  | {\n      operations?: never;\n      lakehouse?: never;\n      transport?: DataTransport;\n      endpoint?: string;\n      fetch?: typeof fetch;\n    };\n\nconst dataQueryRoute = defineDataQueryRoute();\n\n/** Named HTTP operations, or browser-owned operations executed through an authorized SQL bridge. */\nexport function createDataClient<Operations extends DataOperations>(\n  options: DataClientOptions<Operations> = {}\n): DataClient<Operations> {\n  if (options.operations)\n    return createOperationClient({\n      operations: options.operations,\n      lakehouse: options.lakehouse,\n    });\n  const http = createHttpTransport(options);\n  const useHttp = options.endpoint !== undefined || options.fetch !== undefined;\n\n  return {\n    async query(name, input, { signal } = {}) {\n      const transport =\n        options.transport ??\n        (useHttp ? http : (localFrameBridge()?.transport ?? http));\n      const response = await transport(name, input, signal);\n      const ok = response.status >= 200 && response.status < 300;\n      let body: Omit<DataResponse<OutputOf<Operations[typeof name]>>, 'input'>;\n      try {\n        body = dataQueryRoute.output(response, { operation: name, input })\n          .body as typeof body;\n      } catch (error) {\n        if (signal?.aborted) throw error;\n        if (error instanceof MessageRoutingError)\n          throw new DataAppError(error.message, error.code, error.requestId);\n        throw new DataAppError(\n          ok ? 'The data response was invalid.' : 'Could not load data.',\n          ok ? 'invalid_response' : 'request_failed'\n        );\n      }\n\n      return { ...body, input };\n    },\n  };\n}\n\nfunction createOperationClient<Operations extends DataOperations>(options: {\n  operations: Operations;\n  lakehouse?: Lakehouse;\n}): DataClient<Operations> {\n  return {\n    async query(name, input, { signal } = {}) {\n      signal?.throwIfAborted();\n      const requestId = randomUuid();\n      if (!Object.hasOwn(options.operations, name))\n        throw new DataAppError(\n          'Unknown data operation.',\n          'not_found',\n          requestId\n        );\n      const lakehouse =\n        options.lakehouse ??\n        (typeof window === 'undefined'\n          ? undefined\n          : getDataAppTransport()?.lakehouse);\n      if (!lakehouse)\n        throw new DataAppError(\n          'An authorized SQL bridge must be installed first.',\n          'bridge_unavailable',\n          requestId\n        );\n\n      try {\n        const { body } = await executeDataOperation(\n          options.operations[name]!,\n          input,\n          {\n            lakehouse,\n            signal: signal ?? new AbortController().signal,\n            requestId,\n            operationName: name,\n          }\n        );\n\n        return { ...body, input } as DataResponse<\n          OutputOf<Operations[typeof name]>,\n          InputOf<Operations[typeof name]>\n        >;\n      } catch (error) {\n        if (signal?.aborted) throw signal.reason;\n        if (error instanceof DataAppError) throw error;\n        const failure = toDataOperationFailure(error);\n        throw new DataAppError(failure.message, failure.code, requestId);\n      }\n    },\n  };\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAoDA,IAAM,iBAAiB,sBAAqB;AAGrC,SAAS,iBAAmD,CACjE,UAAyC,CAAC,GAClB;AAAA,EACxB,IAAI,QAAQ;AAAA,IACV,OAAO,sBAAsB;AAAA,MAC3B,YAAY,QAAQ;AAAA,MACpB,WAAW,QAAQ;AAAA,IACrB,CAAC;AAAA,EACH,MAAM,OAAO,qBAAoB,OAAO;AAAA,EACxC,MAAM,UAAU,QAAQ,aAAa,aAAa,QAAQ,UAAU;AAAA,EAEpE,OAAO;AAAA,SACC,MAAK,CAAC,MAAM,SAAS,WAAW,CAAC,GAAG;AAAA,MACxC,MAAM,YACJ,QAAQ,cACP,UAAU,OAAQ,iBAAiB,GAAG,aAAa;AAAA,MACtD,MAAM,WAAW,MAAM,UAAU,MAAM,OAAO,MAAM;AAAA,MACpD,MAAM,KAAK,SAAS,UAAU,OAAO,SAAS,SAAS;AAAA,MACvD,IAAI;AAAA,MACJ,IAAI;AAAA,QACF,OAAO,eAAe,OAAO,UAAU,EAAE,WAAW,MAAM,MAAM,CAAC,EAC9D;AAAA,QACH,OAAO,OAAO;AAAA,QACd,IAAI,QAAQ;AAAA,UAAS,MAAM;AAAA,QAC3B,IAAI,iBAAiB;AAAA,UACnB,MAAM,IAAI,cAAa,MAAM,SAAS,MAAM,MAAM,MAAM,SAAS;AAAA,QACnE,MAAM,IAAI,cACR,KAAK,mCAAmC,wBACxC,KAAK,qBAAqB,gBAC5B;AAAA;AAAA,MAGF,OAAO,KAAK,MAAM,MAAM;AAAA;AAAA,EAE5B;AAAA;AAGF,SAAS,qBAAwD,CAAC,SAGvC;AAAA,EACzB,OAAO;AAAA,SACC,MAAK,CAAC,MAAM,SAAS,WAAW,CAAC,GAAG;AAAA,MACxC,QAAQ,eAAe;AAAA,MACvB,MAAM,YAAY,WAAW;AAAA,MAC7B,IAAI,CAAC,OAAO,OAAO,QAAQ,YAAY,IAAI;AAAA,QACzC,MAAM,IAAI,cACR,2BACA,aACA,SACF;AAAA,MACF,MAAM,YACJ,QAAQ,cACP,OAAO,WAAW,cACf,YACA,qBAAoB,GAAG;AAAA,MAC7B,IAAI,CAAC;AAAA,QACH,MAAM,IAAI,cACR,qDACA,sBACA,SACF;AAAA,MAEF,IAAI;AAAA,QACF,QAAQ,SAAS,MAAM,qBACrB,QAAQ,WAAW,OACnB,OACA;AAAA,UACE;AAAA,UACA,QAAQ,UAAU,IAAI,gBAAgB,EAAE;AAAA,UACxC;AAAA,UACA,eAAe;AAAA,QACjB,CACF;AAAA,QAEA,OAAO,KAAK,MAAM,MAAM;AAAA,QAIxB,OAAO,OAAO;AAAA,QACd,IAAI,QAAQ;AAAA,UAAS,MAAM,OAAO;AAAA,QAClC,IAAI,iBAAiB;AAAA,UAAc,MAAM;AAAA,QACzC,MAAM,UAAU,uBAAuB,KAAK;AAAA,QAC5C,MAAM,IAAI,cAAa,QAAQ,SAAS,QAAQ,MAAM,SAAS;AAAA;AAAA;AAAA,EAGrE;AAAA;",
+  "debugId": "F1FFBCC98547BBCD64756E2164756E21",
+  "names": []
+}