@altertable/data-app 0.64.0 → 0.66.0

package/docs/data-context.md

@@ -0,0 +1,89 @@
+# 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.
+
+Physical source identifiers name inspected tables and columns. Glossary entries
+explain business meaning. Query names link those definitions and displayed claims
+to their execution evidence. Keep all three explicit.
+
+## 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" />;
+```
+
+Pass `identifiers.definitions` to `createDataContext()` to reuse the source
+registry.
+
+## 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],
+});
+// activityView is declared with dataContext: context.
+const trackedIdentities = activityView.metric(
+  {
+    id: 'identities',
+    glossaryId: 'identities',
+    format: { kind: 'count' },
+  },
+  data => ({ current: data.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, ... })`.
+
+Use `view.metric(definition, select)` to register and bind a metric in one call.
+Declare dataset evidence references inside `view.dataset()`; the view registers
+and validates them too.
+Widgets and stories share its values and evidence; see [datasets and metrics](widgets.md#declare-datasets-and-metrics).

package/docs/embed.md

@@ -73,7 +73,7 @@ app bundle; non-React apps use `createDataAppNavigation()` from `/client`.
 
 `attachDataAppBridge()` also supports connection mode for a host-owned iframe. Supply
 `connection: { type: 'origin', origin }` or `{ type: 'opaque', token }`, and an
-`onMessage` dispatcher. Both modes use the same transport. It returns `dispose()` and `setPresentation()` methods and owns source/origin checks, request
+`onMessage` dispatcher. Both modes use the same transport. It returns `dispose()`, `setPresentation()`, and `setLogger()` methods and owns source/origin checks, request
 correlation, cancellation, bounded pending requests, and reconnection. Use source mode for bundle loading and token rotation. The opaque destination requires
 wildcard delivery, but incoming messages still require the exact iframe window,
 null origin, token, document, and session to match.

package/docs/formatting-and-appearance.md

@@ -0,0 +1,52 @@
+# Formatting and appearance
+
+Use package helpers so a value has the same meaning in prose, tables, charts,
+and stories. TypeScript and JSDoc describe options and supported values.
+
+## Format values
+
+Import formatting helpers from `@altertable/data-app/format`.
+
+| Helper              | Use                                                    |
+| ------------------- | ------------------------------------------------------ |
+| `formatNumber()`    | General numerical values                               |
+| `formatCount()`     | Nonnegative integer counts, optionally compact         |
+| `formatPercent()`   | Ratios represented as a fraction, such as 0.12 for 12% |
+| `formatMetric()`    | A metric definition's count, ratio, or currency 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).
+
+Import `chartColor()` from `/react` to select colors from the configured palette.
+`<PeriodSummary>` describes reporting periods; `<UpdatedAt>` and
+`<DateTimeTooltip>` expose readable timestamps with exact-date details.
+`<DataTableTimestamp>` and `<DataTableShare>` format custom table cells.
+
+## Configure identity and appearance
+
+```ts
+import type { DataAppConfig } from '@altertable/data-app/config';
+
+const config = {
+  title: 'Product activity',
+  scope: { organization: 'Acme', environment: 'Production' },
+  appearance: {
+    theme: 'system',
+    accentColor: '#405d47',
+    density: 'comfortable',
+  },
+} satisfies DataAppConfig;
+```
+
+Scope labels describe the configured connection; they do not grant access.
+`dataAppTitle()` produces the scoped document title used by `mountDataApp()`.
+
+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
+resolved theme takes precedence and hides local theme controls; see
+[parent presentation](embed.md#parent-presentation).

package/docs/hosted-apps.md

@@ -4,7 +4,7 @@ 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, story, and configuration with
+Replace the sample SQL, parsers, filters, data context, CSV export, story, and configuration with
 an exploration of the source data you inspected. The starter uses two SQL
 `VALUES` rows, so it needs no production table.
 
@@ -13,7 +13,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,
-   configuration, and browser entry into one `index.tsx`, following the
+   CSV export, configuration, 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)
@@ -24,16 +24,3 @@ For execution details, see [browser-owned operations](client.md#browser-owned-op
 4. Confirm the host can query the same catalogs, tables, and fields.
    [Verify the app](app-authoring.md#verify-the-app) in the hosted runtime against
    the local version's filters and findings.
-
-## Preview in this repository
-
-```fish
-bun install --frozen-lockfile
-bun run build
-bun browser-tests/server.ts
-```
-
-Open [the starter preview](http://127.0.0.1:27418/starter-data-app).
-Its test host executes the sample SQL through the iframe bridge using SQLite.
-
-For checks, see [Contributing](../CONTRIBUTING.md).

package/docs/layout.md

@@ -0,0 +1,33 @@
+# Layout contract
+
+The shell owns page width, outer gutters, and header/body spacing. Use `<Stack>`
+for sections, `<Grid>` for peer widgets, and `<GridItem>` for spans. Use
+`<TextContent>` for prose. Widgets own their internal padding; their parents own
+external spacing. Keep widget customization inside the widget so its parent can maintain consistent
+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
+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.
+
+```tsx
+<Stack>
+  <TextContent>
+    <h2>Activity</h2>
+    <p>Explore the sources behind this finding.</p>
+  </TextContent>
+  <Grid columns={3}>
+    <GridItem span={2}>{activityChart}</GridItem>
+    <GridItem>{activityMetric}</GridItem>
+  </Grid>
+</Stack>
+```
+
+## Verify rendered layouts
+
+Check computed section/widget gaps, sibling alignment, outer gutters, and
+horizontal overflow at phone and desktop iframe widths. Check loading, empty,
+error, ready, and stale states. Loading placeholders should use the same grid as
+the ready content.

package/docs/local-data-apps.md

@@ -2,7 +2,7 @@
 
 Start from the CLI scaffold or the [local starter](https://github.com/altertable-ai/data-app/tree/main/examples/starter-local-data-app).
 Use the starter's README for setup and its AGENTS.md to find app-owned files.
-Replace the connectivity screen with the exploration and story from the
+Replace the connectivity screen with the exploration, CSV export, and story from the
 [shared authoring flow](app-authoring.md).
 
 | Task                                    | Documentation                            |

package/docs/react-embed.md

@@ -93,8 +93,8 @@ are mutually exclusive.
 
 ## Loading an embedded app
 
-Use `<DataAppSkeleton>` from `/react` while the host builds or starts an app.
-Call `injectDataAppShellStyles()` from `/react` before rendering the placeholder.
+Use `<DataAppSkeleton>` from `/react/ui` while the host builds or starts an app.
+Call `injectDataAppShellStyles()` from `/react/ui` before rendering the placeholder.
 The host owns when to show it and supplies any surrounding header or footer.
 `/react/embed` itself remains independent of UI components and styles.
 

package/docs/react.md

@@ -5,10 +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>`. 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';
@@ -17,257 +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}
-      {...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.
-
-## 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" />;
-```
-
-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
-
-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).
+## Choose a task
 
-Return one to four findings with a headline, a visual, and registered source
-evidence. Use `context.finding()` to bind the evidence.
+| 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)                             |
 
-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.
+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.