@altertable/data-app 0.65.0 → 0.66.0

package/dist/types/react/view-runtime.d.ts

@@ -0,0 +1,29 @@
+import type { DataContext } from './ui/data-context.js';
+import type { ReactNode } from 'react';
+import type { DataView, DisplayedSnapshot } from '../core/data-view.js';
+import type { DisclosedQuery } from '../core/contract.js';
+import type { EmptyContent } from './ui/presentation.js';
+export type ViewResult<Data, Input> = {
+    dataContext: DataContext;
+    view: DataView<Data, Input>;
+    snapshot?: DisplayedSnapshot<Data, Input>;
+    refetch: () => unknown;
+    cancel: () => unknown;
+    refreshing: boolean;
+    queries?: DisclosedQuery[];
+    controls?: ReactNode;
+    emptyFallback: EmptyContent;
+};
+/** The executor is private; declarations expose data composition, not subscription hooks. */
+export declare class DeclaredView<Data, Input, Definition = unknown> {
+    #private;
+    constructor(useResult: () => ViewResult<Data, Input>, definition?: Definition);
+    static definition<Data, Input, Definition>(view: DeclaredView<Data, Input, Definition>): Definition;
+    static useResult<Data, Input>(view: DeclaredView<Data, Input>): ViewResult<Data, Input>;
+}
+export declare function useDeclaredResult<Data, Input>(view: DeclaredView<Data, Input>): ViewResult<Data, Input>;
+export declare const PrimaryViewContext: import("react").Context<{
+    declaration: object;
+    result: ViewResult<unknown, unknown>;
+} | null>;
+export declare function getViewDefinition<Data, Input, Definition>(view: DeclaredView<Data, Input, Definition>): Definition;

package/dist/types/react/view.d.ts

@@ -1,3 +1,4 @@
+import type { DataContext } from './ui/data-context.js';
 import type { EmptyContent } from './ui/presentation.js';
 import type { AppVariableValues, DateRangeVariable, VariableCollection } from '../core/variables.js';
 import type { DateRangeRequest } from '../core/contract.js';
@@ -16,21 +17,37 @@ export type ViewDate<Variables extends VariableCollection, Input> = {
 export type ViewBindings<Variables extends VariableCollection, Input> = Partial<{
     [Key in keyof Variables]: (input: Input) => ResolvedVariables<Variables>[Key];
 }>;
+type SameViewInput<Variables extends VariableCollection, Input> = [
+    ResolvedVariables<Variables>
+] extends [Input] ? [Input] extends [ResolvedVariables<Variables>] ? [Input] extends [Record<string, never>] ? true : [keyof Input] extends [keyof Variables] ? true : false : false : false;
+type ViewInputMapping<Variables extends VariableCollection, Input> = SameViewInput<Variables, Input> extends true ? {
+    input?: (values: ResolvedVariables<Variables>) => Input;
+} : {
+    input: (values: ResolvedVariables<Variables>) => Input;
+};
 export type DataViewDefinition<Name extends string, Variables extends VariableCollection, Input, Data> = {
     operation: Name;
-    variables: Variables;
-    input: (values: ResolvedVariables<Variables>) => Input;
+    dataContext: DataContext;
     bindings?: ViewBindings<Variables, Input>;
     /** App-owned semantics: measured zero need not mean an empty result. */
     isEmpty: (data: Data) => boolean;
-    empty: EmptyContent;
-} & ({
+    /** Inherited by DataSection unless it supplies its own copy. */
+    emptyFallback: EmptyContent;
+} & (keyof Variables extends never ? {
+    variables?: Variables;
+} : {
+    variables: Variables;
+}) & ViewInputMapping<NoInfer<Variables>, Input> & ({
     date: ViewDate<Variables, Input>;
     describeInput?: (input: Input) => string;
 } | {
     date?: never;
     describeInput: (input: Input) => string;
 });
+export type ResolvedDataViewDefinition<Name extends string, Variables extends VariableCollection, Input, Data> = Omit<DataViewDefinition<Name, Variables, Input, Data>, 'variables' | 'input'> & {
+    variables: Variables;
+    input: (values: ResolvedVariables<Variables>) => Input;
+};
 export declare function describeViewInput<Input>(definition: {
     variables: VariableCollection;
     bindings?: Partial<Record<string, (input: Input) => unknown>>;

package/dist/types/react/widgets.d.ts

@@ -0,0 +1,79 @@
+import { type Dataset, type Metric, type ViewSource } from './bindings.js';
+import { type MetricWidgetProps as DisplayMetricProps } from './ui/MetricWidget.js';
+import { type TableWidgetProps as DisplayTableProps, type TableDisplayMode } from './ui/TableWidget.js';
+import { type VisualizationWidgetProps as DisplayVisualProps, type VisualizationWidgetView as DisplayVisualizationView } from './ui/VisualizationWidget.js';
+import { type TextWidgetProps as DisplayTextProps } from './ui/TextWidget.js';
+import { type DataValueProps as DisplayValueProps } from './ui/DataValue.js';
+import type { MetricValues } from '../core/reading.js';
+import type { MetricDefinition } from './ui/metric.js';
+import type { ReactNode } from 'react';
+import type { DataReading } from '../core/reading.js';
+export type MetricWidgetProps<Data = unknown, Input = unknown> = Omit<Extract<DisplayMetricProps, {
+    metric: MetricDefinition;
+}>, 'metric' | 'reading'> & {
+    metric: Metric<Data, Input>;
+    source: ViewSource<Data, Input>;
+};
+export declare function MetricWidget<Data, Input>({ metric, source, ...presentation }: MetricWidgetProps<Data, Input>): import("react").JSX.Element;
+type BoundTableProps<Row> = Extract<DisplayTableProps<Row>, {
+    reading: DataReading<readonly Row[]>;
+}>;
+type TablePresentation<Row> = Pick<BoundTableProps<Row>, 'title' | 'columns' | 'rowKey' | 'reading' | 'evidence' | 'emptyFallback'>;
+export type TableWidgetProps<Row, Data = unknown, Input = unknown> = Omit<BoundTableProps<Row>, keyof TablePresentation<Row> | 'limit' | 'pagination'> & TableDisplayMode & {
+    dataset: Dataset<Data, Input, Row>;
+    source: ViewSource<Data, Input>;
+    title?: ReactNode;
+};
+export declare function TableWidget<Row, Data, Input>({ dataset, source, title, ...presentation }: TableWidgetProps<Row, Data, Input>): import("react").JSX.Element;
+type BoundVisual<Row> = Extract<DisplayVisualProps<readonly Row[]>, {
+    reading: DataReading<readonly Row[]>;
+}>;
+export type VisualizationWidgetView<Row> = DisplayVisualizationView<readonly Row[]>;
+type VisualContent<Row> = {
+    children: (rows: readonly Row[]) => ReactNode;
+    views?: never;
+    viewLabel?: never;
+    initialView?: never;
+} | {
+    children?: never;
+    views: readonly VisualizationWidgetView<Row>[];
+    viewLabel: string;
+    initialView?: string;
+};
+export type VisualizationWidgetProps<Row, Data = unknown, Input = unknown> = Omit<BoundVisual<Row>, 'reading' | 'isEmpty' | 'emptyFallback' | 'evidence' | 'title' | 'children' | 'views' | 'viewLabel' | 'initialView'> & VisualContent<Row> & {
+    dataset: Dataset<Data, Input, Row>;
+    source: ViewSource<Data, Input>;
+    title?: ReactNode;
+};
+export declare function VisualizationWidget<Row, Data, Input>({ dataset, source, title, ...presentation }: VisualizationWidgetProps<Row, Data, Input>): import("react").JSX.Element;
+type NarrativeBinding<Data, Input, Row> = {
+    metric: Metric<Data, Input>;
+    dataset?: never;
+    source: ViewSource<Data, Input>;
+    children?: (values: MetricValues) => ReactNode;
+} | {
+    metric?: never;
+    dataset: Dataset<Data, Input, Row>;
+    source: ViewSource<Data, Input>;
+    children: (rows: readonly Row[]) => ReactNode;
+};
+export type TextWidgetProps<Data = unknown, Input = unknown, Row = never> = Omit<Extract<DisplayTextProps<unknown>, {
+    reading: DataReading<unknown>;
+}>, 'reading' | 'evidence' | 'children' | 'title' | 'emptyFallback'> & NarrativeBinding<Data, Input, Row> & {
+    title?: ReactNode;
+};
+export declare function TextWidget<Data, Input, Row>(props: TextWidgetProps<Data, Input, Row>): import("react").JSX.Element;
+type InlinePresentation = Omit<DisplayValueProps<unknown>, 'reading' | 'children' | 'loadingFallback'> & {
+    loadingFallback?: ReactNode;
+};
+export type DataValueProps<Data = unknown, Input = unknown, Row = never> = InlinePresentation & ((NarrativeBinding<Data, Input, Row> & {
+    scope?: never;
+}) | {
+    metric?: never;
+    dataset?: never;
+    source?: never;
+    scope: DataReading<string>;
+    children?: (scope: string) => ReactNode;
+});
+export declare function DataValue<Data, Input, Row>(props: DataValueProps<Data, Input, Row>): import("react").JSX.Element;
+export {};

package/docs/app-authoring.md

@@ -27,63 +27,71 @@ readers can inspect the source of each claim.
 
 Connect visualizations with introductions and explanations. Use `<TextWidget>`
 for a narrative panel with the standard widget frame, or `<TextContent>` for
-borderless prose. Bind claims to `result.select((data, input) => ...)` so their
-values and scope follow the displayed results through filter changes, refresh,
-and failure.
-
-| Task                                       | Documentation                                              |
-| ------------------------------------------ | ---------------------------------------------------------- |
-| Define queries, inputs, and result parsing | [Operations](contract.md)                                  |
-| Build views, filters, and request states   | [React](react.md)                                          |
-| Introduce and explain visualizations       | [Narrative text](react.md#narrative-text)                  |
-| Find formatters and presentation helpers   | [App helpers](react.md#reuse-app-helpers)                  |
-| Register source names                      | [Source identifiers](react.md#register-source-identifiers) |
-| Choose date and field filters              | [Filter variables](react.md#time-views-and-field-filters)  |
-| Handle refresh and stale results           | [Displayed results](react.md#preserve-displayed-results)   |
-| Export displayed data as CSV               | [CSV export](react.md#export-displayed-data-as-csv)        |
-| Bind definitions and source evidence       | [Data context](react.md#bind-evidence)                     |
-
-Use the exported types for configuration, appearance, formatting, and component
-options. Declare configuration with `satisfies DataAppConfig` so appearance
-fields and values are checked before bundling.
-
-## Compose the layout
-
-See the [layout contract](layout.md).
-
-## Export the displayed results
-
-Provide `DataApp.csvExport` in every analytical app. The request-backed API
-requires a callback that selects an explicit filename and named datasets with ordered columns and raw
-rows from the displayed snapshot. Follow [CSV export](react.md#export-displayed-data-as-csv)
-and the [starter](../examples/starter-data-app/index.tsx); use the built-in toolbar
-action rather than adding a custom download button.
-
-Export every distinct analytical dataset at its displayed grain, including relevant
-dimensions and measures. Reuse one dataset for charts or metrics derived from the
-same rows. One dataset downloads as CSV; multiple datasets offer individual CSVs
-and **Export all** as a ZIP archive. Use the displayed input for scope labels and filenames. Export the
-bounded result the app already has; do not issue a different query or mix pending
-filters into the visible result. Setup and static screens may omit export.
-
-## Present the findings
-
-Compose a [story](react.md#present-data-with-stories) from the exploration's
-findings. Lead with the answer, then show the evidence and comparisons that
-explain it. Select the findings that matter to the audience; do not turn every
-row or chart into a step.
+borderless prose. Render static titles, descriptions, and instructions immediately. Use metric and dataset
+bindings for dynamic values and `<DataValue>` for values within static prose.
+Skeletonize only the content that needs data. Reuse bindings and the displayed
+source in narrative so values, formatting, and evidence follow filter changes,
+refresh, and failure.
+
+| Task                                             | Documentation                                                     |
+| ------------------------------------------------ | ----------------------------------------------------------------- |
+| Choose components, CSS tokens, and styling hooks | [Styling](styling.md)                                             |
+| Define queries, inputs, and result parsing       | [Operations](contract.md)                                         |
+| Build views, filters, and request states         | [Views](views.md)                                                 |
+| Introduce and explain visualizations             | [Narrative text](widgets.md#narrative-text)                       |
+| Find formatters and presentation helpers         | [App helpers](formatting-and-appearance.md)                       |
+| Register source names                            | [Source identifiers](data-context.md#register-source-identifiers) |
+| Choose date and field filters                    | [Filter variables](variables.md)                                  |
+| Handle refresh and stale results                 | [Displayed results](views.md#preserve-displayed-results)          |
+| Export displayed data as CSV                     | [CSV export](stories-and-export.md#export-displayed-data-as-csv)  |
+| Render widgets and custom visuals                | [Widgets](widgets.md)                                             |
+| Bind definitions and source evidence             | [Data context](data-context.md#bind-evidence)                     |
+
+Declare reusable [datasets and metrics](widgets.md#declare-datasets-and-metrics)
+on the view so tables, exports, and stories share values and evidence.
+
+Every data app supplies a [story and CSV export](stories-and-export.md)
+from the displayed result. Export all distinct datasets at their displayed grain;
+reuse a dataset when several visuals derive from the same rows. Present the
+findings that answer the reader's question, rather than every row or chart.
+Use the [standard layout](layout.md) and built-in toolbar actions.
+
+### Organize the exploration
+
+Use sections for a focused question and for findings readers should compare
+side by side. Add app-level `<Tabs>` from `/react/ui` when the exploration has
+distinct analytical questions, such as Overview, Retention, and Segments, each
+with its own context and group of widgets. Lead with the most useful overview
+and label tabs by the question or subject they explore.
+
+Use `<VisualizationWidget>`'s `views` for alternate representations of the same
+dataset, such as a chart and its rows. Keep these choices within the widget;
+use filter variables when the reader is changing the data scope.
+
+Navigation tabs, widget views, and declared data views have different roles.
+A declared view owns inputs, requests, and displayed results; a tab does not
+require a separate data view. Keep related datasets in one view for a coherent
+snapshot. Use independent views and `<DataSection>` boundaries when content
+needs separate requests. Keep filter placement consistent across tabs and make
+each filter's scope clear. Derive findings, story, and export from the displayed
+results and their inputs.
+
+Choose each visual for the question it answers; see
+[visualization selection](widgets.md#choose-a-visualization).
 
 ## Verify the app
 
+Follow the [UI quality contract](ui-quality.md) for hierarchy, responsive
+composition, typography, and control states.
+
 Verify findings against the source and the user's question. Distinguish measured
 zero, unavailable values, and empty results. Check filters, refresh, loading,
 empty, error, and stale states, then present the story. Download CSV from the
 standalone and embedded toolbar and verify its filename, columns, raw values,
 and filter scope against the displayed result. Export and Present story must be
-available once analytical results are shown; initial loading, empty, and initial
-errors have neither action. Inspect both experiences
+available once results are shown; initial loading, empty, and initial
+errors keep both actions visible and disabled. Inspect both experiences
 at phone and desktop widths in light and dark themes.
 
-The app owns its queries, result parsing, business definitions, configuration,
-and presentation. Credentials, authorization, and enforced access/query limits
-stay backend-owned. Edit app-owned files; installed package files are dependencies.
+Keep credentials, authorization, and enforced query limits in the host/backend.
+Edit app-owned files; installed package files are dependencies.

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/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

@@ -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

@@ -6,9 +6,11 @@ for sections, `<Grid>` for peer widgets, and `<GridItem>` for spans. Use
 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 `--at-layout-gap`, with density configured once
+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.
+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>

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.