@altertable/data-app 0.66.0 → 0.67.0

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
@@ -63,10 +73,9 @@ checks. Build before running consumer tests individually.
 | `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
@@ -79,18 +88,15 @@ 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`.
-
 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 `scripts/dev.ts` seeds). It builds once, then rebuilds `dist` when `src`
+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
-`browser-tests/server.ts`; rerun `bun run build` to refresh declarations. Add `?delay=2000` to a host page URL
+`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. Browser tests keep fixtures.
+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

package/dist/chunks/{contract-19ckn3n7.js → index-23dktynd.js}

@@ -1,17 +1,20 @@
 import {
   executeDataOperation,
   toDataOperationFailure
-} from "./contract-pk603qj7.js";
+} from "./index-x69p7cv7.js";
 import {
   DataAppError2,
   createHttpTransport2,
   localFrameBridge,
   getDataAppTransport2
-} from "./contract-13j5zb3c.js";
+} from "./index-ktmvs916.js";
+import {
+  randomUuid
+} from "./index-f5cnbrjz.js";
 import {
   MessageRoutingError2,
   defineDataQueryRoute2
-} from "./contract-tf8c3qpv.js";
+} from "./index-qd5xgx6y.js";
 
 // src/client/data-client.ts
 var dataQueryRoute = defineDataQueryRoute2();
@@ -46,7 +49,7 @@ function createOperationClient(options) {
   return {
     async query(name, input, { signal } = {}) {
       signal?.throwIfAborted();
-      const requestId = crypto.randomUUID();
+      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);
@@ -56,7 +59,6 @@ function createOperationClient(options) {
         const { body } = await executeDataOperation(options.operations[name], input, {
           lakehouse,
           signal: signal ?? new AbortController().signal,
-          includeSql: true,
           requestId,
           operationName: name
         });
@@ -75,4 +77,4 @@ function createOperationClient(options) {
 
 export { createDataClient2 };
 
-//# debugId=64AFD24787CC437264756E2164756E21
+//# 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": []
+}