@altertable/data-app 0.65.0 → 0.66.0

package/docs/react.md

@@ -5,11 +5,8 @@ React 19.2 or newer and React DOM 19.2 or newer are peer dependencies.
 
 ## Mount the app
 
-`mountDataApp({ config, component })` mounts into `#root`, sets the document
-title and language, attaches navigation to an available iframe transport, and
-installs `<DataAppProvider>`. Uncaught React rendering errors are logged and
-reported to the iframe host as fatal app failures. When mounting through another
-framework, wrap the app in `<DataAppProvider>` yourself.
+Use `mountDataApp({ config, component })` to mount into `#root`. When mounting
+through another framework, import `<DataAppProvider>` from `/react/ui`.
 
 ```tsx
 import { injectDataAppStyles, mountDataApp } from '@altertable/data-app/react';
@@ -18,318 +15,25 @@ injectDataAppStyles();
 mountDataApp({ config, component: App });
 ```
 
-Importing the package does not inject styles. For server rendering, call the
-injector on the client before mounting or hydrating. With a restrictive CSP,
-pass a permitted nonce; the first call sets it for the document. No CSS loader
-or separate stylesheet asset is needed.
+Call `injectDataAppStyles()` before mounting; no separate stylesheet is needed.
+For a restrictive CSP, pass the permitted nonce on the first call.
+See [Styling](styling.md) for appearance, CSS tokens, and overrides.
 
-## Bind a view
+Use `/react` for declared views, bound widgets, and layouts. Use
+[`/react/ui`](ui.md) for setup/static screens and direct UI composition.
 
-```tsx
-import { createDataClient } from '@altertable/data-app/client';
-import {
-  createDataHooks,
-  dateRangeVariable,
-  DataApp,
-  Grid,
-  MetricWidget,
-  VisualizationWidget,
-  Ranking,
-} from '@altertable/data-app/react';
-import type { operations } from '#app/operations.ts';
-import { calendar } from '#app/contracts.ts';
-import { dataContext, trackedIdentities } from '#app/data-context.tsx';
-import config from '#config';
-
-const period = dateRangeVariable({
-  key: 'period',
-  contract: calendar,
-  comparison: true,
-  defaultValue: { kind: 'preset', id: 'last-30' },
-});
-const { defineDataView, useView } =
-  createDataHooks(createDataClient<typeof operations>());
-const activityView = defineDataView({
-  operation: 'activity',
-  variables: { period },
-  input: ({ period }) => period,
-  date: { variable: 'period', input: input => input },
-  isEmpty: data => data.features.length === 0,
-  empty: { title: 'No activity in this range' },
-});
-const featureEvidence = dataContext.evidence({
-  id: 'feature-use',
-  queryNames: [dataContext.queryNames.activity],
-});
-const content = activityView.content(result => (
-  <Grid columns={2}>
-    <MetricWidget
-      metric={trackedIdentities}
-      reading={result.metric(data => ({
-        current: data.count,
-        previous: data.previousCount,
-      }))}
-    />
-    <VisualizationWidget
-      title="Feature use"
-      evidence={featureEvidence}
-      reading={result.select(data => data.features)}
-      isEmpty={features => features.length === 0}
-      empty={{ title: 'No features' }}
-      skeleton={{ variant: 'ranking', rows: 6 }}
-    >
-      {features => <Ranking items={features} />}
-    </VisualizationWidget>
-  </Grid>
-));
-function App() {
-  const activity = useView(activityView);
-  return (
-    <DataApp
-      config={config}
-      dataContext={dataContext}
-      request={activity}
-      csvExport={({ data }) => ({
-        filename: 'activity.csv',
-        tables: [
-          {
-            name: 'Tracked identities',
-            columns: ['Current count', 'Previous count'],
-            rows: [[data.count, data.previousCount]],
-          },
-          {
-            name: 'Feature use',
-            columns: ['Feature ID', 'Count'],
-            rows: data.features.map(feature => [feature.id, feature.value]),
-          },
-        ],
-      })}
-      story={({ data }) => [
-        dataContext.finding({
-          id: 'feature-use',
-          headline: 'Feature use in the selected period',
-          visual: <Ranking items={data.features} />,
-          evidence: featureEvidence,
-        }),
-      ]}
-      {...content}
-    />
-  );
-}
-```
-
-The `date` binding identifies the controlling variable and extracts its range from the operation input. Nested inputs use, for example, `input: (input) => input.period`. The runtime rejects mappings that silently change the selected range or comparison. Non-date views supply `describeInput`; date views can override it when other inputs also need describing.
-
-Share the [date range contract](contract.md#shared-date-ranges) between the
-operation parser and the view.
-
-`useView()` generates controls for date, text and fixed-option select variables; custom controls use `result.variables.bind(name)`. `input` chooses which variables reach the operation, so local search can stay local. Hooks belong in the enclosing component.
-
-For large tables, use query-backed pagination with a stable sort and total
-count. Client pagination and search cover only the rows already returned.
-
-Bound `<VisualizationWidget>` and `<TableWidget>` components require `evidence` from `context.evidence(...)`. A bound `<MetricWidget>` gets evidence from its metric definition. Evidence must name at least one glossary entry or query. Static widgets may omit it.
-
-`<MetricWidget>` and `<ComparisonVisual>` both accept the same `metric` and `reading`. The comparison is enabled by the displayed result's range. The definition supplies formatting and evidence; a reading cannot override those or provide a second value. `favorableDirection` is optional; changes are neutral until the author defines whether up or down is favorable.
-
-Use the [app helpers](#reuse-app-helpers) for metric formats and values in tables,
-charts, and custom views.
-
-`defineDataContent()` remains available for manually managed requests. Its optional `{ date: (input) => rangeRequest }` binds comparison readings. `<DataSection>` handles independent requests. Low-level widgets, tabs and layout components remain available for custom interfaces.
-
-## Layout
-
-Use `<Stack>` for sections, `<Grid>` for peer widgets, and `<GridItem>` for spans.
-They share the app layout gap and own responsive behavior. Follow the
-[layout contract](layout.md) for spacing ownership and composition guidance.
+## Choose a task
 
-## Narrative text
-
-Use `<TextContent>` for prose within a page or custom layout, and `<TextWidget>`
-when the explanation belongs in a titled panel alongside other widgets.
-
-Give text a purpose: frame the question, explain how to interpret a comparison,
-qualify a finding, or suggest what to explore next. Choose the content for the
-reader's question and the decisions the exploration supports.
-
-For data-dependent text, use `reading={result.select((data, input) => ...)}` and
-provide `evidence`. Derive both the explanation and its scope from those displayed
-values so it stays consistent with the visualizations while filters change.
-Static instructions can use ordinary children; local filters should feed the same
-filtered data to the text and its related visualization.
-
-## Reuse app helpers
-
-Use the shared helpers for common app tasks. Follow the entry points below to
-find their exports, types, and usage constraints.
-
-| Task                                                                                        | Entry point                                                                                       |
-| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| Format numbers, counts, percentages, currency, date ranges, and plural labels (`pluralize`) | [Format helpers](https://github.com/altertable-ai/data-app/blob/main/src/core/format.ts)          |
-| Choose chart colors                                                                         | [Chart colors](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/chartColor.ts)    |
-| Search items and highlight matches                                                          | [Search helpers](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/searchItems.ts) |
-| Read and synchronize URL query state                                                        | [URL state helpers](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/search.ts)   |
-| Render timestamps, freshness, table shares, periods, and metric comparisons                 | [React exports](https://github.com/altertable-ai/data-app/blob/main/src/react/index.ts)           |
-| Configure appearance and theme preferences                                                  | [Appearance helpers](https://github.com/altertable-ai/data-app/blob/main/src/core/appearance.ts)  |
-| Build the app's scoped document title                                                       | [Configuration helpers](https://github.com/altertable-ai/data-app/blob/main/src/core/config.ts)   |
-
-## Register source identifiers
-
-Use `defineDataIdentifiers()` from `/react` to register exact catalog, schema,
-table, and field names. Use `<DataIdentifier>` in descriptions and glossary
-entries to render those source references consistently.
-
-```tsx
-import { defineDataIdentifiers } from '@altertable/data-app/react';
-
-const identifiers = defineDataIdentifiers({
-  tables: {
-    events: {
-      catalog: 'product_analytics',
-      schema: 'analytics',
-      name: 'events',
-    },
-  },
-  columns: { identity: { table: 'events', name: 'identity_uuid' } },
-});
-const { DataIdentifier } = identifiers;
-
-<DataIdentifier id="tables.events" />;
-<DataIdentifier id="columns.events.identity" />;
-```
+| Task                                                     | Guide                                                     |
+| -------------------------------------------------------- | --------------------------------------------------------- |
+| Declare a view and handle loading, refresh, and failures | [Views](views.md)                                         |
+| Configure date, text, select, and dimension controls     | [Variables](variables.md)                                 |
+| Render metrics, charts, tables, and narrative            | [Widgets](widgets.md)                                     |
+| Compose sections and responsive grids                    | [Layout](layout.md)                                       |
+| Register sources, definitions, metrics, and evidence     | [Data context](data-context.md)                           |
+| Present findings and export displayed data               | [Stories and export](stories-and-export.md)               |
+| Format values and configure appearance                   | [Formatting and appearance](formatting-and-appearance.md) |
+| Host an iframe from React                                | [React embed](react-embed.md)                             |
 
-Pass `identifiers.definitions` to `createDataContext()` so the context carries the
-same source registry. Source identifiers name physical data; glossary entries
-explain its business meaning, and query evidence records how it was queried.
-
-## Bind evidence
-
-```tsx
-const queries = defineQueryNames({ activity: 'feature-activity' });
-// In the server operation: queryNames: queries
-const context = createDataContext(queries)({
-  identifiers: identifiers.definitions,
-  description: (
-    <>
-      Explore activity in <DataIdentifier id="tables.events" />.
-    </>
-  ),
-  glossary: {
-    identities: {
-      term: 'Tracked identities',
-      definition: (
-        <>
-          Distinct <DataIdentifier id="columns.events.identity" /> values.
-        </>
-      ),
-      queryNames: [queries.activity],
-    },
-  },
-});
-const evidence = context.evidence({
-  id: 'identities',
-  glossaryIds: ['identities'],
-  queryNames: [queries.activity],
-});
-const trackedIdentities = context.metric({
-  id: 'actions',
-  glossaryId: 'identities',
-  label: 'Tracked identities',
-  format: { kind: 'count' },
-});
-const finding = context.finding({
-  id: 'activity',
-  headline: 'What people do',
-  visual: <ActivityChart />,
-  evidence: { id: 'activity-evidence', queryNames: [queries.activity] },
-});
-```
-
-Import `defineQueryNames()` from `/contract` and the context/identifier factories from `/react`. Use the same registry in `defineOperation({ queryNames: queries, ... })`. Unknown glossary/query references fail type checks and registry validation; the server also validates returned query names.
-
-## Time views and field filters
-
-`createDataHooks(client).defineTimeView()` owns the `period` variable, calendar
-controls, and displayed-period label. Declare `time: { contract, defaultValue }`,
-an operation, `isEmpty`, and `empty`. With no additional variables, its default
-input is the calendar request. With additional variables, it is `{ period, ...variables }`.
-Supply an `input` mapper for a different operation shape and `bindings` to extract
-nested period or field-filter inputs. Mappings must preserve the selected values.
-
-`dimensionFilter()` from `/contract` requires exactly one option source: fixed `options` or a `facet`.
-Use `defineFacetFilter()` to bind a facet operation and its typed input. The generated
-`<DimensionPicker>` preserves cached options during refresh and failure, offers
-missing values separately, and retains selected values absent from a result with
-zero counts. `<SelectableBarChart>` can share controlled selection with the picker.
-
-## Preserve displayed results
-
-The callback in `view.content()` receives the displayed result and its original
-input during refreshes and failures. Use that input when labeling the data.
-
-Previous data and evidence are retained only when the input changes within the
-same operation. Switching to another operation shows its own cached response or
-an initial loading/error state; it never inherits another operation's result.
-
-Operation and facet caches are scoped to the `DataClient` instance. Hooks created
-from the same client share queries; separate clients do not share results, stale
-data, or cancellation even under one provider. Keep client instances stable
-across renders to preserve their cache.
-
-## Findings and inspection
-
-`<DataWidget>` composes a body, toolbar feedback, and footer. Widgets and their
-inspection sheets render the same visual and controls. Keep interactive state
-above both mounts when authoring custom children.
-
-When a trusted parent supplies [parent presentation](embed.md#parent-presentation),
-`<DataApp>` follows its resolved theme and suppresses local theme controls,
-including in presentations. On an embedded surface (`surface: 'embedded'`),
-only toolbar actions remain above the app body; the title, scope, description, and
-footer are omitted. Variables and request states remain available.
-
-## Present data with stories
-
-Include a story in every analytical app. Stories turn the exploration's findings
-into a presentation. Set the `story` prop on `<DataApp>`
-to enable **Present story** in the toolbar; use `<PresentStory>` directly for a
-custom shell. Start from the [data app starter](../examples/starter-data-app/index.tsx).
-
-Return one to four findings with a headline, a visual, and registered source
-evidence. Use `context.finding()` to bind the evidence.
-
-The callback receives the displayed data and its original input, including
-during refresh or failure. Derive the story from that snapshot so it agrees with
-the visible exploration. Initial loading, empty results, and initial errors have
-no story to present.
-
-## Export displayed data as CSV
-
-Every request-backed `<DataApp>` requires `story` and `csvExport`. Select all distinct named datasets
-from the displayed snapshot so the built-in **Export** action is available
-whenever analytical results are shown. Include this alongside the app's story;
-setup and static shells may omit it. One dataset downloads directly as CSV. Multiple
-datasets offer individual CSV downloads and **Export all** as a ZIP archive.
-
-Example:
-
-```tsx
-<DataApp
-  config={config}
-  dataContext={dataContext}
-  request={result}
-  story={story}
-  csvExport={({ data, input }) => ({
-    filename: `counts-${input.groupName || 'all'}.csv`,
-    tables: [
-      {
-        name: 'Sample counts',
-        columns: ['Group', 'Sample count'],
-        rows: data.map(row => [row.groupName, row.sampleCount]),
-      },
-    ],
-  })}
->
-  {(data, input) => <Results data={data} input={input} />}
-</DataApp>
-```
+Start with [app authoring](app-authoring.md) and the
+[single-file starter](../examples/starter-data-app/index.tsx).

package/docs/stories-and-export.md

@@ -0,0 +1,52 @@
+# Stories and CSV export
+
+Every `<DataApp>` from `/react` supplies both `story` and `datasets`, derived from
+the displayed snapshot. Story and export selectors do not run before a result is available.
+Setup and static screens use `<DataApp>` from `/react/ui`; they may omit both
+or pass a direct `CsvExport` object.
+
+## Present data with stories
+
+Set `story` on `<DataApp>` to enable **Present story** in the toolbar.
+For custom shells, `/react/ui` provides `<PresentStory>`; see [direct UI composition](ui.md). Start from the [data app starter](../examples/starter-data-app/index.tsx).
+
+Return one to four findings with a headline, a visual, and registered source
+evidence. Set `evidence` to the registered dataset or metric binding. The app
+validates that every finding belongs to its view.
+
+The callback receives the displayed source and its original input, including
+during refresh or failure. Derive the story from that snapshot so it agrees with
+the visible exploration. Initial loading, empty results, and initial errors have
+no story to present; the toolbar keeps its story action visible and disabled.
+
+## Export displayed data as CSV
+
+Select all distinct named datasets from the displayed snapshot. One dataset downloads directly as CSV. Multiple
+datasets offer individual CSV downloads and **Export all** as a ZIP archive.
+While no displayed snapshot is available, the export action stays visible and disabled.
+
+Declare [datasets](widgets.md#declare-datasets-and-metrics) once and pass
+`datasets={[countries, otherDataset]}` to `<DataApp>`. The toolbar
+exports those datasets with raw values and a safe filename derived from the
+displayed scope. List every distinct dataset the app shows.
+
+Reuse bound metrics in story visuals:
+
+```tsx
+story={snapshot => {
+  const totalReading = total.read(snapshot);
+  return [{
+    id: 'total',
+    headline: `Tracked identities: ${formatMetric(totalReading.value.current, total.definition.format)}`,
+    context: activityView.scope(snapshot),
+    visual: <MetricWidget metric={total} source={snapshot} />,
+    evidence: total,
+  }];
+}}
+```
+
+Use the [format helpers](formatting-and-appearance.md) for story prose.
+
+Dataset accessors return raw values; do not preformat numbers as display
+labels. Null and undefined become empty cells, while measured zero stays zero.
+The helpers handle quoting and spreadsheet formula protection.

package/docs/styling.md

@@ -0,0 +1,55 @@
+# Styling
+
+Use components and typed props first: `<Stack>` for sections, `<Grid>` for peers,
+and `<TextContent>` for prose. Standard widgets use [views and bindings](widgets.md);
+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
+`injectDataAppStyles()` before mounting. Use one `<DataApp>` per document.
+
+## Customize
+
+Add app-owned classes through `className`. Render package components rather than copying their classes onto markup;
+private descendants are not customization hooks. Public names and stable roots
+are listed in the [typed contract](https://github.com/altertable-ai/data-app/blob/main/src/react/style-contract.ts).
+CSS comments document [inherited defaults](https://github.com/altertable-ai/data-app/blob/main/src/react/tokens.css),
+[interaction overrides](https://github.com/altertable-ai/data-app/blob/main/src/react/interaction.css),
+and [focus overrides](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/Focus.css).
+Widget-specific overrides live beside their uses in
+[metrics](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/MetricWidget.css),
+[bar charts](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/BarChart.css),
+[code](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/QueryList.css),
+and [layout](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/Grid.css).
+The `--atbl-` prefix means Altertable.
+
+```css
+.app-action {
+  --atbl-control-height: 40px;
+  --atbl-focus-color: var(--atbl-accent);
+}
+```
+
+Set tokens on `:root` for the document or on a component for local overrides.
+Inherited tokens are usable in app CSS. Optional overrides fall back where they
+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.
+
+When overriding `--atbl-accent` directly, also choose `--atbl-on-accent` with
+sufficient contrast. Prefer appearance configuration for brand and chart colors.
+
+## Native controls
+
+Use package controls when possible. For a custom native control:
+
+```tsx
+<button type="button" data-atbl-control="action" data-atbl-focus="ring">
+  Run
+</button>
+```
+
+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.

package/docs/ui-quality.md

@@ -0,0 +1,20 @@
+# UI quality
+
+Lead with a supported finding and visible scope. Explain each chart's purpose,
+measures, units, and source evidence. Use package typography and formatters;
+keep primary values prominent and preserve exact values in records and exports.
+
+Compose with `<Stack>`, `<Grid>`, and `<TextContent>`; parents own spacing and
+widgets own padding. Let labels and values wrap, and keep tables and menus
+scrolling inside their frames. Use the [layout](layout.md) and [styling](styling.md)
+guides for customization.
+
+Keep static context visible during loading. Skeletonize only dynamic content;
+refresh, errors, and retry retain the displayed result and scope. Loading
+geometry should match ready content.
+
+Verify a real app at phone and desktop widths, including 320px, in both themes
+and with enlarged text. Exercise long labels, localized values, many filters,
+and loading, empty, refresh, and error states. Check containment, contrast,
+keyboard focus, date/menu navigation, modal dismissal, and reduced motion.
+Inspect rendered screenshots as well as computed styles.

package/docs/ui.md

@@ -0,0 +1,41 @@
+# Direct UI composition
+
+Import from `@altertable/data-app/react/ui` for setup/static screens, custom
+controls, or a deliberately custom shell. Standard data apps use declared views
+and bound widgets from `/react`.
+
+`<DataApp>` here renders a static screen and accepts optional direct CSV data.
+Direct widget forms accept local values or rows. `<DataWidget>` supplies a generic
+frame for deliberately custom content. Use `<GettingStarted>` for
+connection setup. Fetched data belongs to a declared view; avoid inventing
+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>`.
+
+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.
+Call `injectDataAppStyles()` before mounting either entry; imports do not install
+styles.
+
+## 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}>`
+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.
+
+Line and area charts show equally spaced samples; include missing periods in the
+input. These charts space items evenly, so they do not represent irregular time
+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.

package/docs/variables.md

@@ -0,0 +1,98 @@
+# Variables and filters
+
+## Time views and field filters
+
+`createDataHooks(client).defineTimeView()` owns the `period` variable, calendar
+controls, and displayed-period label. Declare `time: { contract, defaultValue }`,
+an operation, `isEmpty` (a predicate), and `emptyFallback` (a title and optional
+description for an empty result). With no additional variables, its default
+input is the calendar request. With additional variables, it is `{ period, ...variables }`.
+Supply an `input` mapper for a different operation shape and `bindings` to extract
+nested period or field-filter inputs. Mappings must preserve the selected values.
+
+`dimensionFilter()` from `/contract` requires exactly one option source: fixed `options` or a `facet`.
+Use `defineFacetFilter()` to bind a facet operation and its typed input. `<DimensionPicker>` offers missing values separately and keeps selected values
+available when they have zero matches.
+
+## Declare controls once
+
+Use `textVariable()`, `selectVariable()`, and `dateRangeVariable()` in a view's
+`variables`. `<DataApp view={view}>` generates their controls and keeps values in the URL.
+Keep local search out of the operation input when it only filters loaded rows.
+
+The [date range contract](contract.md#shared-date-ranges) owns source coverage,
+maximum range, time zone, and comparison rules. `defineTimeView()` is the compact
+path for a view whose primary input is a period. Use `defineDataView()` for fixed
+snapshots or other input shapes.
+
+```ts
+const activity = defineTimeView({
+  dataContext,
+  operation: 'activity',
+  time: { contract: calendar, defaultValue: { kind: 'preset', id: 'last-7' } },
+  variables: { region: textVariable({ key: 'region' }) },
+  input: values => ({
+    filters: { period: values.period, region: values.region },
+  }),
+  bindings: {
+    period: input => input.filters.period,
+    region: input => input.filters.region,
+  },
+  isEmpty: data => data.rows.length === 0,
+  emptyFallback: { title: 'No activity' },
+});
+```
+
+The operation, calendar, and row shape are app-owned. Bindings must extract
+selected values unchanged.
+
+## URL state and custom controls
+
+Relative date presets remain relative. Explicit dates use `start`, `end`, and
+`compare` for the `period` variable; other date variables derive these keys from
+their own key. Invalid URL values fall back to validated defaults. Do not use
+reserved inspection, presentation, or navigation keys for app variables.
+
+Choose push history for meaningful selections and replace history for typing.
+Back/Forward restores the same values and controls. Use generated controls for
+standard data apps. Direct pickers and standalone URL state belong to
+[direct UI composition](ui.md).
+
+## Fixed options and query-backed facets
+
+Declare fixed choices with `dimensionFilter()` from `/contract`:
+
+```ts
+const region = dimensionFilter({
+  key: 'region',
+  label: 'Region',
+  valueType: 'string',
+  selection: 'multiple',
+  options: [{ value: 'Europe', label: 'Europe' }],
+});
+```
+
+For query-backed choices use the hooks factory's `defineFacetFilter()`. The
+facet operation returns parsed dimension options. Its input mapper reads current
+resolved variables, including other filters:
+
+```ts
+const { defineFacetFilter, defineTimeView } = createDataHooks(client);
+const region = defineFacetFilter({
+  key: 'region',
+  label: 'Region',
+  valueType: 'string',
+  selection: 'multiple',
+  facet: {
+    operation: 'regions',
+    input: values => ({ period: values.period as DateRangeRequest }),
+  },
+});
+```
+
+The client registry defines the `regions` operation and its typed period input;
+import `DateRangeRequest` from `/contract`. Put `region` in the view's `variables`
+alongside its period. Use `parseFacetOptions()` to validate facet results, and
+`dimensionPredicate()` to build a bounded SQL filter from parsed selections.
+For the operation's input parser, use `parseDimensionSelection(value, region)` from `/contract`.
+A dimension without an explicit selection represents all members.