@altertable/data-app 0.66.0 → 0.68.0

package/docs/app-authoring.md

@@ -7,6 +7,13 @@ queries, definitions, and evidence.
 
 ## Inspect the data
 
+Declare the query source of truth with `defineDataApp()`. Generate
+operations with `dataApp.defineOperation()` and execute queries by
+name with parameter values. When a query registry is supplied, use only its queries
+and preserve its SQL. Otherwise, inspect the data and declare the queries the app needs.
+Derive displays, exports, and findings from their results. See
+[named queries](contract.md#execute-named-queries).
+
 Inspect the relevant catalogs, tables, and fields, their time coverage, and
 existing definitions. Choose a question the available data can answer.
 
@@ -21,13 +28,20 @@ Choose the execution path:
 
 Lead with a supported finding and expose the relevant fields as filter variables. Use a date filter for questions worth exploring over time,
 or a fixed period snapshot for a deliberate historical analysis.
+
+Use relevant user-controlled query parameters as app filters. Map filter values to
+declared parameters through operation inputs, and reuse query defaults when they
+match the initial selection. One filter may supply several parameters, such as a
+date range supplying `start` and `end`. Keep protected parameters, such as `orgId`,
+and internal execution settings out of filter controls.
+
 Register inspected tables and fields with `defineDataIdentifiers()` and use
 `<DataIdentifier>` when naming sources. Register terms and query evidence so
 readers can inspect the source of each claim.
 
 Connect visualizations with introductions and explanations. Use `<TextWidget>`
 for a narrative panel with the standard widget frame, or `<TextContent>` for
-borderless prose. Render static titles, descriptions, and instructions immediately. Use metric and dataset
+borderless prose. Render the app title, description, and instructions immediately. Use metric and dataset
 bindings for dynamic values and `<DataValue>` for values within static prose.
 Skeletonize only the content that needs data. Reuse bindings and the displayed
 source in narrative so values, formatting, and evidence follow filter changes,

package/docs/client.md

@@ -15,8 +15,9 @@ const response = await client.query('activity', input, { signal });
 ```
 
 The app defines `operations`, `input`, and an optional cancellation `signal`.
-Operation input and output types are inferred from the server registry. Keep the
-registry import type-only so its SQL and implementation stay on the server.
+Operation input and output types are inferred from the server operation map. Keep the
+server operation map import type-only so its implementations stay on the server.
+The shared app declaration contains the query registry and is browser-safe.
 
 The default endpoint is `/api/data`. Override it with
 `createDataClient({ endpoint, fetch })` to change the base URL or supply a Fetch
@@ -24,8 +25,7 @@ implementation. Calls POST JSON to `/api/data/:operation`; the client sends
 operation inputs rather than SQL or credentials.
 
 `DataResponse` contains `data`, the exact request `input`, `requestId`,
-`queriedAt`, and `queryIds`. `queries` is present when the operation exposes SQL
-and the execution runtime permits disclosure. Use the returned input when labeling stale data during a refresh.
+`queriedAt`, `queryIds`, and executed `queries`. Use the returned input when labeling stale data during a refresh.
 HTTP and iframe delivery validate the same success envelope: data, request ID,
 query timestamp, query IDs, and optional query evidence. Malformed responses
 reject with `invalid_response`.
@@ -46,17 +46,17 @@ Bundle apps pass their operation registry as a value:
 import { connectionCheck } from '@altertable/data-app/contract';
 import { createDataClient } from '@altertable/data-app/client';
 
+// dataApp declares a connection query.
 const client = createDataClient({
-  operations: { connection: connectionCheck() },
+  operations: { connection: connectionCheck(dataApp.queries) },
 });
 const response = await client.query('connection', {});
 ```
 
 The client runs input parsing, operation logic, and output parsing in the browser.
-Operation policy bounds rows, duration, and response size and records query evidence. Each query sends `{ statement, limit }`
+Operation policy bounds rows, duration, and response size and records query evidence. Each query sends `{ statement, limit, params? }`
 to the installed iframe bridge's `data:sql` route; the host needs no operation
-registry. SQL is visible in the browser, even when `exposeSql` is false; that flag
-only controls evidence in the returned response. Credentials remain backend-owned.
+registry. Results include query evidence. Credentials remain backend-owned.
 
 The trusted bootstrap installs the bridge for bundle apps. A custom runtime must
 install it before querying. An explicit `lakehouse` can supply another authorized

package/docs/contract.md

@@ -2,35 +2,59 @@
 
 Import operation definitions, parsers, and shared types from
 `@altertable/data-app/contract`. This entry is safe to import in browser and server
-modules. For HTTP apps, keep SQL and operation implementations on the server; browser modules
-should import their operation types using `import type`.
+modules. The app declaration is browser-safe and includes its SQL registry. For HTTP apps,
+keep operation implementations, credentials, and authorization on the server; browser modules
+import operation types using `import type`.
 
 ## Execute named queries
 
-The app supplies `calendar`, `parseActivity()`, `checkInput`, `buildActivitySql()`,
-and `parseActivityRows()` in this example.
+Declare SQL once with `defineDataApp()` to preserve exact query and parameter
+names. Use stable `lowerCamelCase` IDs describing the result, such as `products`,
+`productsByCategory`, or `dailyRevenue`. Use plural names for row lists; keep parameter
+values in `params`. Every query must include `params`; use `{}` when it declares no
+parameters.
+The app owns an immutable registry snapshot. Define operations with
+`dataApp.defineOperation()`.
 
 ```ts
-import {
-  defineOperation,
-  defineQueryNames,
-} from '@altertable/data-app/contract';
+import { defineDataApp } from '@altertable/data-app';
+import { rowsAsRecords } from '@altertable/data-app/contract';
+
+const dataApp = defineDataApp({
+  title: 'Products',
+  description: 'Explore products for the selected organization.',
+  scope: { organization: 'demo', environment: 'production' },
+  appearance: { theme: 'system' },
+  queries: {
+    products: {
+      statement: 'SELECT * FROM products WHERE org_id = $orgId LIMIT $limit',
+      params: { orgId: {}, limit: { defaultValue: 10 } },
+    },
+  },
+});
 
-const queries = defineQueryNames({ activity: 'feature-activity' });
-const activity = defineOperation({
-  queryNames: queries,
-  input: calendar.parseRequest,
-  output: parseActivity,
-  checks: [checkInput],
-  policy: { maxQueryRows: 100, maxDurationMs: 15000, exposeSql: true },
+const products = dataApp.defineOperation({
+  input: parseProductInput,
+  output: parseProducts,
+  checks: [{}],
+  policy: { maxQueryRows: 100, maxDurationMs: 15000 },
   async run({ query }, input) {
-    const result = await query(queries.activity, buildActivitySql(input));
-    return parseActivityRows(result);
+    const result = await query('products', input);
+    return rowsAsRecords(result, ['org_id']);
   },
 });
 ```
 
-`query()` inherits the operation's limit and cancellation signal; `{ limit }` can lower a particular query's bound. Names are checked by TypeScript and at runtime. Responses include executed SQL and query IDs when disclosure is allowed. HTTP browser modules import operation types with `import type`. Bundle apps import their browser-owned operation registry as a value and use [browser execution](client.md#browser-owned-operations-for-bundle-apps). Never bundle credentials or server adapters.
+`parseProductInput()` and `parseProducts()` are app-owned example functions, not
+package exports. Validate
+filter values in the input parser. `{}` declares a required parameter; `{ defaultValue }` supplies
+a fallback. `query(name, params, { limit })` executes only registered queries and
+inherits the operation's row limit and cancellation signal.
+
+SQL and resolved parameter values pass unchanged to the backend. Results include
+query evidence; use `products.queryNames` with `createDataContext()` to bind it.
+For HTTP apps, authorization can supply protected `queryParams`, such as `orgId`.
+The host/backend enforces data access and limits.
 
 ## Shared date ranges
 
@@ -50,8 +74,7 @@ export const calendar = defineDateRangeContract({
 ```
 
 `parseEmptyInput()`, `parseTrue()`, `parseCount()`, and `parseDateRangeInput()` validate
-common inputs and results. `connectionCheck()` defines a bounded connectivity
-operation. A successful connectivity check confirms access; it is not an
+common inputs and results. `connectionCheck(dataApp.queries)` runs the registered `connection` query. A successful connectivity check confirms access; it is not an
 analysis result.
 
 See [server authorization](server.md) and [React views](react.md) for the two

package/docs/data-context.md

@@ -1,7 +1,8 @@
 # Data context and evidence
 
-Set `dataContext: context` in each view. The app and its sections inherit the
-view's description, glossary, and permitted query evidence. Render registered identifiers where `<DataIdentifier>` is used.
+Set `dataContext: context` in each view for source descriptions, glossary, and
+permitted query evidence. App inspection and the view's sections use that context.
+Render registered identifiers where `<DataIdentifier>` is used.
 
 Physical source identifiers name inspected tables and columns. Glossary entries
 explain business meaning. Query names link those definitions and displayed claims
@@ -38,8 +39,7 @@ registry.
 ## Bind evidence
 
 ```tsx
-const queries = defineQueryNames({ activity: 'feature-activity' });
-// In the server operation: queryNames: queries
+const queries = activity.queryNames;
 const context = createDataContext(queries)({
   identifiers: identifiers.definitions,
   description: (
@@ -69,7 +69,7 @@ const trackedIdentities = activityView.metric(
   {
     id: 'identities',
     glossaryId: 'identities',
-    format: { kind: 'count' },
+    format: { kind: 'count', compact: true },
   },
   data => ({ current: data.count })
 );
@@ -81,7 +81,9 @@ const finding = context.finding({
 });
 ```
 
-Import `defineQueryNames()` from `/contract` and the context/identifier factories from `/react`. Use the same registry in `defineOperation({ queryNames: queries, ... })`.
+Query inspection shows the executed SQL and resolved parameters; copy actions include both.
+
+Import context and identifier factories from `/react`. Use the operation’s derived `queryNames` for evidence.
 
 Use `view.metric(definition, select)` to register and bind a metric in one call.
 Declare dataset evidence references inside `view.dataset()`; the view registers

package/docs/embed.md

@@ -31,11 +31,18 @@ A bundle source has this shape:
 ```ts
 const source = {
   type: 'bundle' as const,
-  bootstrapUrl: 'https://my-report-app-1.apps.example.net/',
   javascript: bundle.javascript,
 };
 ```
 
+Omit `bootstrapUrl` to load the SDK's packaged bootstrap as a `data:` document.
+This supports MCP hosts that permit opaque child frames but block remote frame
+URLs. The SDK embeds the exact host origin and applies a CSP that prohibits
+direct network access. Data requests go through the host's dispatcher.
+
+Supply an HTTP(S) `bootstrapUrl` to use an externally served trusted bootstrap,
+such as the [Worker asset](worker.md).
+
 The host provides a self-contained JavaScript bundle. React bridges replace the
 iframe whenever its JavaScript content changes. Serve the bootstrap page with a CSP compatible with the bundle.
 Bundle mode uses `sandbox="allow-scripts"` and an opaque origin; it cannot read
@@ -129,7 +136,8 @@ as public `source_*` errors with request IDs. Authorization failures return
 public failures with `MessageRoutingError`.
 
 `SqlQueryInput` (exported from `/contract`) carries
-`{ statement: string, limit: number }`; responses are
+`{ statement: string, limit: number, params?: QueryParameters }`; the backend
+interprets the unchanged statement and parameter values. Responses are
 `{ columns: { name: string, type?: string }[], rows: unknown[][], queryId?: string }`.
 The route rejects empty statements, unsafe or nonpositive limits, malformed
 results, and results exceeding the requested limit. The bridge's existing payload

package/docs/formatting-and-appearance.md

@@ -16,10 +16,21 @@ Import formatting helpers from `@altertable/data-app/format`.
 | `formatDateRange()` | Inclusive calendar ranges                              |
 | `pluralize()`       | Count-dependent labels                                 |
 
-Missing values render distinctly from measured zero. Define metric formatting
-once with `view.metric()`; comparisons derive from its displayed source. Previous
-values, range labels, and favorable direction belong to that metric and displayed
-input; see [data context](data-context.md) and [views](views.md).
+Missing values render distinctly from measured zero. Declare formatting once on
+`view.metric()` so widgets, comparisons, and narrative share it; reuse the
+definition with `formatMetric()` in story headlines.
+
+Use compact counts for headline metrics and chart labels. Declare count metrics
+with `format: { kind: 'count', compact: true }`. Keep full counts in tables used
+for precise comparisons and raw numeric values in datasets for CSV export.
+
+```ts
+formatCount(2_200_000, { compact: true }); // "2.2M"
+formatCount(2_200_000); // "2,200,000"
+```
+
+For signed or fractional measures, use `formatNumber()` with
+`notation: 'compact'` and preserve the measure's units.
 
 Import `chartColor()` from `/react` to select colors from the configured palette.
 `<PeriodSummary>` describes reporting periods; `<UpdatedAt>` and
@@ -29,22 +40,27 @@ Import `chartColor()` from `/react` to select colors from the configured palette
 ## Configure identity and appearance
 
 ```ts
-import type { DataAppConfig } from '@altertable/data-app/config';
+import { defineDataApp } from '@altertable/data-app';
 
-const config = {
+const dataApp = defineDataApp({
   title: 'Product activity',
+  description: 'Explore product usage and trends.',
   scope: { organization: 'Acme', environment: 'Production' },
   appearance: {
     theme: 'system',
     accentColor: '#405d47',
     density: 'comfortable',
   },
-} satisfies DataAppConfig;
+  queries: {},
+});
 ```
 
 Scope labels describe the configured connection; they do not grant access.
 `dataAppTitle()` produces the scoped document title used by `mountDataApp()`.
 
+Title and description explain the app and can be revised when regenerating it.
+Omit appearance to use the standard defaults.
+
 Appearance controls the brand palette, typography, density, corner radius, and
 elevation. Those settings apply consistently to the app instead of tuning each
 widget. Theme preference is reader-owned in standalone apps. A trusted parent's

package/docs/hosted-apps.md

@@ -4,7 +4,14 @@ Follow the [shared authoring flow](app-authoring.md) using [index.tsx](../exampl
 one file with public package imports; omit server files, HTML, credentials, and
 relative or app-alias imports.
 
-Replace the sample SQL, parsers, filters, data context, CSV export, story, and configuration with
+Declare exactly one top-level const initialized with `defineDataApp({ ... })`, imported
+from `@altertable/data-app`. Keep executable composition outside its literal argument.
+For the future backend extractor, use schema-valid literals without spreads, computed keys,
+references, calls, or template interpolation. Extraction will read and validate the argument
+before bundling, without evaluating app code or parsing SQL. Import aliases and any variable
+name are allowed; export only for other modules. Static apps use `queries: {}`.
+
+Replace the sample app declaration, operations, filters, data context, CSV export, and story with
 an exploration of the source data you inspected. The starter uses two SQL
 `VALUES` rows, so it needs no production table.
 
@@ -13,7 +20,7 @@ For execution details, see [browser-owned operations](client.md#browser-owned-op
 ## Convert a local data app
 
 1. Combine the app's operations and parsers, data context, views, story,
-   CSV export, configuration, and browser entry into one `index.tsx`, following the
+   CSV export, app declaration, and browser entry into one `index.tsx`, following the
    [single-file starter](../examples/starter-data-app/index.tsx).
 2. Replace the HTTP client with `createDataClient({ operations })`, using the
    operation registry as a value. See [browser-owned operations](client.md#browser-owned-operations-for-bundle-apps)

package/docs/layout.md

@@ -7,7 +7,7 @@ external spacing. Keep widget customization inside the widget so its parent can
 spacing between sections and cards.
 
 By default, section and widget gaps use `--atbl-layout-gap`, with density configured once
-in `DataAppConfig.appearance`. The package owns wrapping and span collapse based
+in `app.appearance`. The package owns wrapping and span collapse based
 on the available container width and configured gap. Custom length values for
 `--atbl-layout-gap`, `--atbl-space-sm`, and `--atbl-space-md` also drive span
 collapse; a two-column span activates only when two minimum-width tracks fit.

package/docs/react-embed.md

@@ -45,10 +45,11 @@ The local URL must have a different origin from its shell. For hosted bundles,
 replace `source` with:
 
 ```tsx
-source={{ type: 'bundle', bootstrapUrl, javascript }}
+source={{ type: 'bundle', javascript }}
 ```
 
-The host supplies those bundle values. See [embedding](embed.md) for trust,
+The host supplies the JavaScript bundle. Omit `bootstrapUrl` for the packaged
+opaque bootstrap, or supply an HTTP(S) URL for an external bootstrap. See [embedding](embed.md) for trust,
 sandbox, CSP, and bootstrap setup.
 
 Source URL or JavaScript content changes replace the entire iframe. Change the

package/docs/react.md

@@ -5,14 +5,15 @@ React 19.2 or newer and React DOM 19.2 or newer are peer dependencies.
 
 ## Mount the app
 
-Use `mountDataApp({ config, component })` to mount into `#root`. When mounting
-through another framework, import `<DataAppProvider>` from `/react/ui`.
+Use `mountDataApp({ app, component })` to mount into `#root`. When mounting
+through another framework, wrap the root in `<DataAppProvider app={app}>` from `/react/ui`.
+`<DataApp>` inherits identity and appearance from that root. Mounting sets the document title before React renders.
 
 ```tsx
 import { injectDataAppStyles, mountDataApp } from '@altertable/data-app/react';
 
 injectDataAppStyles();
-mountDataApp({ config, component: App });
+mountDataApp({ app, component: App });
 ```
 
 Call `injectDataAppStyles()` before mounting; no separate stylesheet is needed.

package/docs/server-bun.md

@@ -24,6 +24,6 @@ server-only `ALTERTABLE_LAKEHOUSE_USERNAME` and
 `ALTERTABLE_LAKEHOUSE_PASSWORD`, with an optional `ALTERTABLE_API_BASE`.
 Missing credentials fail the query. Keep these variables out of browser code.
 
-Local serving permits SQL disclosure and does not authenticate hosted viewers.
+Local serving does not authenticate hosted viewers.
 Use [the portable server handler](server.md) with per-request authorization when
 hosting an app for other people.

package/docs/server.md

@@ -15,7 +15,7 @@ export const handleDataRequest = createDataHandler(
     const viewer = await authenticate(request);
     return {
       lakehouse: await lakehouseFor(viewer, operation),
-      canDiscloseSql: false,
+      queryParams: { orgId: viewer.organizationId },
     };
   }
 );
@@ -23,12 +23,12 @@ export const handleDataRequest = createDataHandler(
 
 The app supplies `authenticate()` and `lakehouseFor()`, then routes `/api/data/*`
 requests to the handler. Authorize every viewer and operation, and scope the
-returned lakehouse to the viewer's permitted data. Origin and Fetch Metadata
+returned lakehouse to the viewer's permitted data. Supply trusted registry
+parameters through `queryParams`; query callers cannot override these values. Origin and Fetch Metadata
 checks reject cross-site browser requests; they do not authenticate viewers.
 
 The handler validates operation input and output, enforces query row and duration
-bounds, propagates cancellation, and returns request IDs with errors. SQL is
-disclosed only when both the operation policy and `canDiscloseSql` allow it.
+bounds, propagates cancellation, and returns query evidence and request IDs.
 Keep credentials and operation implementations on the server.
 
 See [operation contracts](contract.md), the [client](client.md), and the

package/docs/styling.md

@@ -5,7 +5,7 @@ and `<TextContent>` for prose. Standard widgets use [views and bindings](widgets
 custom controls and direct widget shells use [`/react/ui`](ui.md).
 
 Configure theme, palette, accent, typography, density, radius, and elevation through
-`config.appearance`; see [appearance](formatting-and-appearance.md). Call
+`app.appearance`; see [appearance](formatting-and-appearance.md). Call
 `injectDataAppStyles()` before mounting. Use one `<DataApp>` per document.
 
 ## Customize
@@ -36,6 +36,12 @@ are consumed, so local colors, fonts, and spacing compose. Portals inherit from
 their actual DOM ancestors. Normal unlayered app CSS overrides package rules.
 `DataAppStyle` checks public inline custom-property names.
 
+`--atbl-control-text-size` controls editable text, including compact search fields,
+date segments, and annotation editors. It defaults to the body text size.
+Package controls and custom controls with `data-atbl-control="text"` enforce a
+16px minimum on narrow or touch viewports to prevent browser focus zoom. Keep
+that minimum when adding app-owned input styles.
+
 When overriding `--atbl-accent` directly, also choose `--atbl-on-accent` with
 sufficient contrast. Prefer appearance configuration for brand and chart colors.
 
@@ -51,5 +57,6 @@ Use package controls when possible. For a custom native control:
 
 These hooks provide cursor and focus styling; keep native semantics, accessible
 names, disabled state, and keyboard behavior. `DataAppStyleHooks` checks hook
-values. Use `inset` focus inside clipped surfaces and `group` when a wrapper owns
-an input's outline. See [UI quality](ui-quality.md) for rendered verification.
+values. Use `default` for tooltip targets that only reveal information on hover
+or tap, and `action` for controls that perform an action. Use `inset` focus inside
+clipped surfaces and `group` when a wrapper owns an input's outline. See [UI quality](ui-quality.md) for rendered verification.

package/docs/ui.md

@@ -13,22 +13,82 @@ request states to populate a shell.
 Direct `<DateRangePicker>`, `<DimensionPicker>`, and `useAppVariables()` support
 custom control ownership. The caller supplies values and change handlers.
 Custom tables use `<DataTable>` and its cell helpers; controls and overlays
-include `<SearchField>`, `<Combobox>`, `<Tabs>`, `<Sheet>`, and `<HelpPopover>`.
+include `<SearchField>`, `<ChoicePicker>`, `<Tabs>`, `<Sheet>`, and `<HelpPopover>`.
 
 Standalone `<AboutData>`, glossary components, and `<PresentStory>` support
 custom inspection and presentation. Supply registered context and evidence, and
 derive findings from the displayed data. Standard widgets and `<DataApp>`
 already own these experiences.
 
-For framework mounting, `<DataAppProvider>` supplies shared requests and one inspection sheet. Wrap custom shells in it.
+For framework mounting, `<DataAppProvider app={app}>` supplies app identity, shared requests and one inspection sheet. Wrap custom shells in it; app components inherit identity and appearance.
 Call `injectDataAppStyles()` before mounting either entry; imports do not install
 styles.
 
+## Keyboard actions
+
+Use `isPlainKeyEvent()` from `/react/ui` in custom key handlers so local actions
+leave shortcut modifiers and IME composition untouched:
+
+```tsx
+onKeyDown={event => {
+  if (event.key === 'Enter' && isPlainKeyEvent(event.nativeEvent)) {
+    event.preventDefault();
+    submit();
+  }
+}}
+```
+
+Pass `{ allowShift: true }` when the handler also supports Shift gestures.
+
+## Choose a selection control
+
+Use `<DimensionPicker>` for typed field filters and `<ChoicePicker>` for searchable
+values. A single value uses a checkmark and closes after selection; multiple
+values use checkbox indicators and keep the popup open. These pickers expose
+listbox options, including search and loading feedback.
+
+Use `<MenuTrigger>`, `<MenuButton>`, `<MenuPopover>`, `<Menu>`, and `<MenuItem>`
+for commands or short choice menus
+such as sort order or display mode. Actions use `onAction`. Set
+`selectionMode="single"` for mutually exclusive choices (radio menu items), or
+`selectionMode="multiple"` for independent toggles (checkbox menu items). Menus
+support arrow keys, typeahead, Escape, and focus return to their trigger. Keep
+search fields and other form inputs outside menus.
+
+```tsx
+<MenuTrigger>
+  <MenuButton>Sort order</MenuButton>
+  <MenuPopover>
+    <Menu
+      aria-label="Sort order"
+      selectionMode="single"
+      selectedKeys={[sortOrder]}
+      onSelectionChange={keys => {
+        if (keys !== 'all') setSortOrder(String([...keys][0]));
+      }}
+    >
+      <MenuItem id="highest">Highest first</MenuItem>
+      <MenuItem id="lowest">Lowest first</MenuItem>
+    </Menu>
+  </MenuPopover>
+</MenuTrigger>
+```
+
+`<MenuButton>` accepts text or icons; give icon-only buttons an accessible name.
+`<MenuPopover>` owns placement and popup styling.
+
+Use `<MenuSection>` to group choices with their own selection state and
+`<MenuSeparator>` between groups or commands. Menu selection closes the popup
+by default; set `shouldCloseOnSelect={false}` for repeated toggles. Selection
+indicators derive from the menu or section's selection mode; do not add checkbox
+markup to single-choice items.
+
 ## Charts
 
 Choose a chart using the [visualization guide](widgets.md#choose-a-visualization).
 Import `<BarChart>`, `<LineChart>`, `<AreaChart>`, `<PieChart>`, or `<ScatterChart>` from
-`/react/ui`. Compose the visual inside `<VisualizationWidget dataset={dataset} source={result}>`
+`/react/ui`; `<ComposedChart>` exposes the series primitives for custom plots.
+Compose the visual inside `<VisualizationWidget dataset={dataset} source={result}>`
 so rows, loading state, evidence, and inspection come from that dataset.
 Pass ordered items with unique, nonblank IDs and finite numbers. Bar and pie
 values must be nonnegative. Use `formatValue` for domain formatting.
@@ -39,3 +99,116 @@ intervals. Distinguish a missing observation from measured zero when preparing
 the samples. Pie slices represent mutually exclusive parts of one total; shares
 use the sum of supplied items, so include Other when showing a subset of the
 whole. Scatter points represent independent X/Y observations.
+
+Use `useSvgId()` for stable IDs when composing custom SVG definitions.
+
+### Product analytics charts
+
+Use `<FunnelChart>`, `<RetentionChart>`, and `<JourneyChart>` from `/react/ui`
+inside `<VisualizationWidget>`. Derive inputs from the displayed rows; the
+binding owns loading, evidence, CSV, and story content. Types and JSDoc describe
+input constraints; the gallery includes complete examples.
+
+- `<FunnelChart>` compares ordered step counts across populations. Each series
+  uses its first step as the baseline; hatching shows previous-step drop-off.
+- `<RetentionChart>` plots query-defined rates and retained counts by interval
+  offset. Use `null` for unobserved periods; `incomplete` produces a dotted tail.
+- `<JourneyChart>` derives expandable branches and outcomes from full paths.
+  Truncated paths stop at the last loaded event.
+
+### Composed charts
+
+Use `<ComposedChart>` from `/react/ui` for multiple series or mixed marks inside
+`<VisualizationWidget>`. Pass the displayed rows and select fields with `dataKey`.
+`<ComposedChart.Bar>`, `<ComposedChart.Line>`, and `<ComposedChart.Area>` share the
+standalone charts' themed series primitives; axes, scatter, tooltip, and reference
+primitives are also available.
+
+```tsx
+<VisualizationWidget dataset={revenue} source={result}>
+  {rows => (
+    <ComposedChart data={rows} ariaLabel="Monthly revenue and target in euros">
+      <ComposedChart.XAxis dataKey="month" />
+      <ComposedChart.YAxis />
+      <ComposedChart.Tooltip />
+      <ComposedChart.Legend />
+      <ComposedChart.Bar dataKey="revenue" name="Revenue (€)" />
+      <ComposedChart.Line
+        dataKey="target"
+        name="Target (€)"
+        stroke="var(--atbl-chart-2)"
+      />
+    </ComposedChart>
+  )}
+</VisualizationWidget>
+```
+
+Label series and units clearly. See component JSDoc and the
+[Recharts API](https://recharts.github.io/en-US/api/ComposedChart/) for options.
+The dataset owns loading, empty results, evidence, CSV, and story content; keep
+its columns aligned with the displayed measures.
+
+### Legends
+
+Include `<ComposedChart.Legend />` to derive labels and colored square markers from the series;
+omit it when no legend is needed. For any chart, compose `<ChartLegend>` with
+`<ChartLegend.Item>`, `<ChartLegend.Marker>`, and `<ChartLegend.Label>` using the
+same names and colors as the plot. Square markers are
+shared with chart tooltips and funnel summaries. Pass `kind="square"` explicitly
+when composing a marker.
+`<PieChart>` includes a legend by default; `showLegend={false}` omits it.
+
+Legends align cells in a container-responsive grid, truncate labels, and reserve
+an overflow cell for “+X more.” Use `maxVisibleItems` to choose the limit or
+`layout="vertical"` for a list. Legends describe series; authored toggles or a
+composed legend's `onClick` leave series visibility to the app.
+
+## Filter controls
+
+Direct controls own accessible input and call the supplied change handler;
+filter declarations own URL state, validation, and operation meaning.
+
+| Control                            | Use                                                               |
+| ---------------------------------- | ----------------------------------------------------------------- |
+| `<SearchField>`                    | Search text                                                       |
+| `<Select>`                         | One choice from a small fixed list                                |
+| `<ChoicePicker>`                   | Searchable choices with explicit `selectionMode`                  |
+| `<RadioGroup>` and `<Radio>`       | Visible exclusive choices                                         |
+| `<CheckboxGroup>` and `<Checkbox>` | Visible independent choices                                       |
+| `<SegmentedControl>`               | Compact radio choices                                             |
+| `<NumberField>`                    | Localized numeric input; empty is `null`                          |
+| `<NumberRangeField>`               | Exact, inclusive minimum/maximum; omitted bounds are unrestricted |
+| `<DateRangePicker>`                | Explicit or relative periods                                      |
+| `<DimensionPicker>`                | Typed categorical predicates with fixed or facet options          |
+
+```tsx
+<RadioGroup label="Metric" value={metric} onChange={setMetric}>
+  <Radio value="orders">Orders</Radio>
+  <Radio value="revenue">Revenue</Radio>
+</RadioGroup>
+
+<CheckboxGroup label="Statuses" values={statuses} onChange={setStatuses}>
+  <Checkbox value="paid" label="Paid" />
+  <Checkbox value="pending" label="Pending" />
+</CheckboxGroup>
+```
+
+A standalone `<Checkbox>` uses `checked` and `onChange`; a group item supplies
+`value`. `<SegmentedControl>` accepts the same labeled options as `<Select>` and
+keeps radio-group semantics. Numeric range controls retain invalid draft bounds
+and emit only valid intervals. Numeric input and compact selects respect the
+shared mobile text-size minimum.
+
+Use `<FilterBar>` to arrange predicates and `<VariableBar>` for mixed app
+parameters. Each filter shows its current value; categorical single selection includes All.
+`<FilterActions>` provides one Clear icon with a tooltip, plus optional paired
+Apply/Cancel actions for app-owned drafts. The caller owns those actions; the
+components do not infer query state.
+
+`<NumberFilterPicker>` composes numeric fields inside a dedicated popover. Edits
+remain local until Apply; Cancel and dismissal discard them. Use `<NumberField>`
+and `<NumberRangeField>` as inline input primitives when composing forms.
+
+Use `<Button variant="primary">` for the main committing action, such as Apply.
+Primary buttons use the theme foreground as their fill and the theme background
+for contrasting text. Use outline and ghost buttons for secondary actions.