@altertable/data-app 0.65.0 → 0.67.0

package/docs/ui.md

@@ -0,0 +1,196 @@
+# 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>`, `<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 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`; `<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.
+
+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.
+
+### 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 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.
+`<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.

package/docs/variables.md

@@ -0,0 +1,171 @@
+# 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 `searchVariable()`, `choiceVariable()`, 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: searchVariable({ 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',
+  selectionMode: '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',
+  selectionMode: 'multiple',
+  facet: {
+    operation: 'regions',
+    input: values => ({ period: values.period as DateRangeRequest }),
+  },
+});
+```
+
+The client's operation map defines `regions` 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.
+For the operation's input parser, use `parseDimensionSelection(value, region)` from `/contract`.
+A dimension without an explicit selection represents all members.
+Map parsed selections to the query's declared parameters; do not construct SQL
+from filter values. Choose selection modes supported by the registered query.
+
+Choose `selectionMode: 'single'` when one value replaces another. Its picker closes
+after choosing a value and shows a checkmark for the current choice. Use
+`selectionMode: 'multiple'` for independent values; checkbox indicators and an open
+popup allow repeated selections. `All` is an explicit choice for a single-value
+filter and the meaning of an empty selection for a multiple-value filter.
+
+## Fixed choices
+
+`choiceVariable()` requires labeled `options` and a valid `defaultValue`.
+`multiChoiceVariable()` stores unique option IDs with an optional selection limit.
+An empty fixed-choice collection means no choices; categorical filters use
+`dimensionFilter()` when an empty selection should mean all records.
+
+```ts
+const variables = {
+  search: searchVariable({ key: 'q', label: 'Search' }),
+  metric: choiceVariable({
+    key: 'metric',
+    label: 'Metric',
+    defaultValue: 'orders',
+    options: [
+      { id: 'orders', label: 'Orders' },
+      { id: 'revenue', label: 'Revenue' },
+    ],
+  }),
+};
+```
+
+Fixed single choices generate `<Select>`; multiple choices generate
+`<ChoicePicker selectionMode="multiple">`. Direct controls can present the same
+values as radio groups, checkbox groups, or segmented choices without changing
+URL state.
+
+## Numeric and boolean predicates
+
+Import `numberFilter()` and `booleanFilter()` from `/contract` and put their
+results in the view's `variables`. Both have an explicit `{ kind: 'all' }`
+unrestricted state. Numeric filters support inclusive, open-ended ranges and
+comparisons: `eq`, `ne`, `gt`, `gte`, `lt`, and `lte`. Boolean filters distinguish
+Any from `{ kind: 'is', value: true }` and `{ kind: 'is', value: false }`.
+
+```ts
+const amount = numberFilter({ key: 'amount', label: 'Amount', min: 0 });
+const active = booleanFilter({ key: 'active', label: 'Active' });
+```
+
+Use `parseNumberSelection()` and `parseBooleanSelection()` in the operation's
+input parser with the same filter declarations. Numeric predicates generate `<NumberFilterPicker>` panels. Draft edits reach
+operation input only after Apply; Cancel and dismissal preserve the applied
+value. Invalid ranges disable Apply.
+Input mappings and bindings must preserve these predicates unchanged, as with
+categorical filters. Map parsed operators and values to declared query parameters;
+offer only operators supported by the registered query.
+
+## Exclusion, clear, and reset
+
+Set `allowExclusion: true` on `dimensionFilter()` to support
+`{ kind: 'exclude', members }`. `<DimensionPicker>` then exposes Include/Exclude
+alongside selected members. Enable exclusion only when the registered query supports
+it, including the intended behavior for missing values.
+
+Generated controls show active values within each filter and one collective
+Clear icon with a tooltip. Clear removes restrictions from search and predicate filters.
+`resetAll()` restores all
+configured variable defaults, including fixed choices and periods. Nonempty
+default filters can therefore be active immediately after Reset.
+
+Direct `useAppVariables()` callers can use `clearAll()` and `resetAll()` for one
+atomic history update. `<FilterActions>` also supports app-owned draft state
+with paired Apply/Cancel handlers; derive queries and visible controls from applied
+values while a draft is being edited.

package/docs/views.md

@@ -0,0 +1,123 @@
+# Views and displayed results
+
+## Bind a view
+
+```tsx
+import { createDataClient } from '@altertable/data-app/client';
+import {
+  createDataHooks,
+  DataApp,
+  DataSection,
+} from '@altertable/data-app/react';
+import type { operations } from '#app/operations.ts';
+
+const client = createDataClient<typeof operations>();
+const { defineDataView } = createDataHooks(client);
+const activityView = defineDataView({
+  dataContext,
+  operation: 'activity',
+  describeInput: () => 'all activity',
+  isEmpty: data => data.rows.length === 0,
+  emptyFallback: { title: 'No activity' },
+});
+const content = activityView.content(result => (
+  <ActivityWidgets source={result} />
+));
+
+function App() {
+  return (
+    <DataApp view={activityView} story={story} datasets={[activityDataset]}>
+      <DataSection content={content} />
+    </DataApp>
+  );
+}
+```
+
+Omit `variables` when there are no controls. Omit `input` when the resolved
+variables match the operation input; nested or different inputs need a mapper.
+The operation and `ActivityWidgets` are app-owned. The bound widgets derive
+loading content from their source; see [widgets](widgets.md) and the
+[complete starter](../examples/starter-data-app/index.tsx). Define
+[filters](variables.md), [context and evidence](data-context.md), and
+[story and datasets](stories-and-export.md) for the app's question.
+
+Render static text immediately; skeletonize only dynamic content. Keep section
+introductions outside request boundaries so they remain visible on empty and
+error states.
+
+Use `<DataSection>` for each independently fetched subtree and `view.content()`
+to share its loading and ready layout. Refreshes retain displayed content.
+
+Use `<DataValue>` for a dynamic value within static prose:
+
+```tsx
+<p>
+  Orders in the last 7 days: <DataValue metric={weeklyOrders} source={result} />
+</p>
+```
+
+Bind the whole sentence with `<TextWidget>` when its wording depends on the result.
+Use `<DataValue scope={result.scope} />` for the displayed scope label.
+
+Use the same [date range contract](contract.md#shared-date-ranges) for the
+operation and its view. For nested inputs in `defineTimeView()`, use
+`bindings.period` to extract the selected period; see the
+[time-view example](variables.md#declare-controls-once).
+
+Use `result.scope` inside `view.content()` as a reading for scope text. In stories and exports,
+`view.scope(snapshot)` returns the same label from the displayed input, using
+`describeInput` or the view's date label.
+
+Declare standard controls in the view's [variables](variables.md). Keep
+local-only filters out of the operation's `input`.
+
+For large tables, use query-backed pagination with a stable sort and total
+count. Client pagination and search cover only the rows already returned.
+
+Declare evidence references on `view.dataset()` for charts and tables. `<MetricWidget>` uses
+its metric definition for the label, format, and evidence; keep view-specific
+descriptions on the widget.
+
+`<MetricWidget>` and `<Comparison>` share a metric reading. Comparisons
+follow the displayed result's range.
+
+Use the [format helpers](formatting-and-appearance.md) for metric formats and values in tables,
+charts, and custom views.
+
+## Preserve displayed results
+
+The callback in `view.content()` receives a displayed source with `loading`,
+`data`, `input`, and `scope`. Bind widgets to that source. Its input remains the
+one that produced the visible data during refreshes and failures.
+
+Keep the client stable across renders; create it outside the component.
+
+## Request ownership
+
+`<DataApp>` owns the toolbar, controls, inspection, and page feedback for its
+primary `view`. It always renders children, so introductions and static
+context remain visible while a section loads. It requires both
+[story and CSV export](stories-and-export.md) for a data request.
+
+Place `<DataSection content={content}>` around each independently fetched subtree.
+Declare its shared loading and ready layout with `view.content()`. The section
+inherits empty copy from its view, with an optional local override, and handles
+initial errors and retries. Primary content shares the app's displayed result;
+independent content uses its own context and executed queries.
+
+Keep related datasets in one view so export and story share a coherent snapshot.
+
+| State           | Display                                                   |
+| --------------- | --------------------------------------------------------- |
+| Initial loading | The authored loading fallback; selectors do not run       |
+| Initial error   | A source-aware error with retry when recovery is possible |
+| Empty result    | The authored empty fallback                               |
+| Ready           | Data and the input that produced it                       |
+| Updating        | The prior result and its original input, fully readable   |
+| Failed refresh  | The prior result and its evidence, with recovery feedback |
+
+`isEmpty` is app-owned. A measured zero is valid data unless the analysis explicitly
+says otherwise. Use the displayed input in content, export, and story callbacks for scope labels.
+
+`<DataApp>` owns request execution, refresh, and cancellation. Keep raw request
+state out of app code.

package/docs/widgets.md

@@ -0,0 +1,145 @@
+# Widgets and narrative
+
+## Choose a widget
+
+Metrics, tables, and visualizations from `/react` consume view bindings and a source. For static displays, use
+[direct UI composition](ui.md).
+Manage requests in the [view and section](views.md); show skeletons for loading
+readings without inventing values. Use `isEmpty` for the predicate and
+`emptyFallback` for empty-result copy.
+
+| Need                                             | Component               |
+| ------------------------------------------------ | ----------------------- |
+| Metric with formatting, comparison, and evidence | `<MetricWidget>`        |
+| Custom chart or alternate chart views            | `<VisualizationWidget>` |
+| Defined columns, local search, and pagination    | `<TableWidget>`         |
+| Narrative panel                                  | `<TextWidget>`          |
+| Borderless explanatory prose                     | `<TextContent>`         |
+| One data-dependent phrase within static prose    | `<DataValue>`           |
+
+Use [layout](layout.md) for `<Stack>`, `<Grid>`, and responsive `<GridItem>` spans.
+`<Skeleton>` supports custom fallback content; `/react/ui` supplies
+`<DataAppSkeleton>` for iframe startup.
+
+## Choose a visualization
+
+Choose the component by the reader's question. Compose dataset visuals inside
+`<VisualizationWidget>`; use `<MetricWidget>` for a headline value. Built-in
+charts come from `/react/ui`; `<Ranking>`, `<Breakdown>`, and `<Comparison>`
+are also available from `/react`.
+
+| Question or need                                          | Component         | Guidance                                                                                                           |
+| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
+| How do categories compare?                                | `<BarChart>`      | Compare nonnegative category values; order by value for rank or by a meaningful category order.                    |
+| Which items lead?                                         | `<Ranking>`       | Use a compact ordered list with values and optional detail. Tracks scale to the largest visible item, not a total. |
+| How does a measure change over time?                      | `<LineChart>`     | Use ordered, equally spaced samples to emphasize the trend.                                                        |
+| How large is the measure over time?                       | `<AreaChart>`     | Use the same samples as a line chart when filled magnitude relative to zero helps answer the question.             |
+| What makes up the whole?                                  | `<PieChart>`      | Use a few mutually exclusive parts of one total; include the remainder as Other.                                   |
+| What share of an observed total does each part represent? | `<Breakdown>`     | Use a compact display of values and shares with an explicit total, including when only some parts are shown.       |
+| How do several measures relate on one plot?               | `<ComposedChart>` | Compose bars, lines, areas, or scatter series; label units clearly and use separate axes for different units.      |
+| How are two numeric measures related?                     | `<ScatterChart>`  | Use independent X/Y observations to explore relationships, clusters, and outliers.                                 |
+| How did one metric change between periods?                | `<Comparison>`    | Use the metric reading and its displayed comparison period.                                                        |
+| What are the exact values or row details?                 | `<TableWidget>`   | Use a bound table for lookup, search, and precise comparisons.                                                     |
+
+Prefer bars or a ranking when readers need to compare similarly sized categories;
+use a pie for a simple composition question. Prefer a line when the trend is
+enough; use area when the fill adds meaning. Keep exact values available in a
+table when they matter. Follow the [chart input constraints](ui.md#charts). For multiple or mixed series,
+use the [composed chart primitives](ui.md#composed-charts) within the same bound
+visualization workflow.
+
+Use widget `views` when a chart and another representation answer the same
+question from the same dataset.
+
+## Declare datasets and metrics
+
+Bind reusable selections to the view. Declare evidence references directly;
+the view validates them against its own context. A dataset's columns supply both formatted
+table cells and raw CSV values. Widgets derive their readings, evidence, and empty fallback from the binding.
+
+```tsx
+const countries = activityView.dataset({
+  name: 'Countries',
+  select: data => data.countries,
+  rowKey: row => row.country,
+  evidence: { id: 'countries', glossaryIds: ['identities'] },
+  columns: {
+    country: { value: row => row.country },
+    count: { value: row => row.count, format: { kind: 'count' } },
+  },
+});
+const total = activityView.metric(
+  {
+    id: 'tracked-identities',
+    glossaryId: 'identities',
+    format: { kind: 'count', compact: true },
+  },
+  data => ({
+    current: data.count,
+    previous: data.previousCount,
+  })
+);
+const content = activityView.content(result => (
+  <Grid columns={2}>
+    <MetricWidget metric={total} source={result} />
+    <TableWidget dataset={countries} source={result} />
+    <VisualizationWidget dataset={countries} source={result}>
+      {rows => <CountryChart rows={rows} />}
+    </VisualizationWidget>
+  </Grid>
+));
+```
+
+Column keys supply unique IDs and readable default labels. Use `label` for a
+specific display/export header. Declare selectors, raw value accessors, and
+row-key callbacks explicitly; row keys must be stable and unique.
+Metric comparisons require a
+view date binding. `read()` returns a loading-aware value for custom prose.
+Pass the binding and `source={snapshot}` to reuse a widget in a story. Use the
+source supplied by that binding's own view; reconstructed or foreign sources
+are rejected before selection.
+Selectors do not run during loading. Table search, pagination, descriptions, and
+actions remain local choices. For custom cells, use `format: row => ...`; CSV
+still uses the raw `value` accessor. Datasets default to “No results”; supply
+`emptyFallback` for specific copy. See [export](stories-and-export.md).
+
+## 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.
+
+For data-dependent text, pass `metric` or `dataset` and `source` to `<TextWidget>`.
+It derives its title and evidence. A metric formats its current value by default;
+use a child renderer for authored prose. Dataset renderers receive displayed rows,
+including an empty selection, so they can explain zero activity.
+
+Use `<DataValue metric={total} source={result} />` for a formatted value inside
+static prose, or pass a dataset and row renderer. Its default loading fallback is
+an inline skeleton. Use `<DataValue scope={result.scope} />` for a scope label.
+All selectors use the displayed source; loading selectors do not run.
+Use `<TextContent>` for static instructions; local filters should feed the same
+filtered data to the text and its related visualization.
+
+## Custom visuals and controls
+
+`<Ranking>`, `<Breakdown>`, and `<Comparison>`
+compose inside authored widgets. Use [built-in charts](ui.md#charts) from `/react/ui`
+inside `<VisualizationWidget dataset={dataset} source={result}>` for displayed rows.
+The dataset owns evidence and empty copy; an empty row selection shows that fallback. A visualization's `views` declaration keeps
+alternate-view selection shared with its inspection sheet. Give views stable IDs
+and keep interactive state above the widget, since inspection may render it again.
+
+`<TableWidget>` searches and paginates only the supplied rows. Use query-backed
+pagination with a stable sort and total count for larger datasets. The `limit`
+mode shows a bounded preview without local pagination. Custom tables can use
+`<DataTable>`, `<DataTableEmptyRow>`, `<DataTableTimestamp>`, and `<DataTableShare>`.
+
+For custom controls, tables, and overlays, see [direct UI composition](ui.md).
+For embedded theme and chrome, see [parent presentation](embed.md#parent-presentation).
+
+`<TooltipProvider>` shares hover timing outside `<DataApp>`; the app already
+provides it.