@altertable/data-app 0.61.0 → 0.63.0

package/dist/react.css.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/embed/shell.d.ts

@@ -1,21 +0,0 @@
-import type { MessageDispatcher } from '../core/messages.js';
-import { type DataAppStatus, type DataAppDiagnostic } from './host.js';
-export type DataAppSource = {
-    type: 'url';
-    url: string;
-} | {
-    type: 'bundle';
-    bootstrapUrl: string;
-    javascript: string;
-    revision: string;
-};
-export type DataAppShellOptions = {
-    iframe: HTMLIFrameElement;
-    source: DataAppSource;
-    onMessage: MessageDispatcher;
-    onStatusChange?: (status: DataAppStatus) => void;
-    onDiagnostic?: (event: DataAppDiagnostic) => void;
-    startupTimeoutMs?: number;
-};
-/** Owns loading and sandbox policy. Dispose before replacing the source or retrying. */
-export declare function attachDataAppShell({ iframe, source, onMessage, onStatusChange, onDiagnostic, startupTimeoutMs, }: DataAppShellOptions): () => void;

package/dist/types/embed/standalone.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/react/embed/shell.d.ts

@@ -1,10 +0,0 @@
-import { type ReactNode } from 'react';
-import { type DataAppSource, type DataAppShellOptions } from '../../embed/shell.js';
-export type DataAppShellProps = Pick<DataAppShellOptions, 'onMessage' | 'onStatusChange' | 'onDiagnostic' | 'startupTimeoutMs'> & {
-    source: DataAppSource;
-    title: string;
-    loading?: ReactNode;
-    renderError?: (retry: () => void) => ReactNode;
-};
-/** Source changes and retries replace the entire frame; handler changes retain its session. */
-export declare function DataAppShell({ source, title, onMessage, onStatusChange, onDiagnostic, startupTimeoutMs, loading, renderError, }: DataAppShellProps): import("react").JSX.Element;

package/dist/types/react/ui/index.d.ts

@@ -1,129 +0,0 @@
-
-export { DataApp } from './DataApp.js';
-export type { DataAppProps, DataAppRequest } from './DataApp.js';
-export { GettingStarted } from './GettingStarted.js';
-export { AppLayout } from './AppLayout.js';
-export type { AppLayoutProps } from './AppLayout.js';
-export { AppHeader } from './AppHeader.js';
-export type { AppHeaderProps } from './AppHeader.js';
-export { AppScope } from './AppScope.js';
-export type { AppScopeProps } from './AppScope.js';
-export { AppToolbar } from './AppToolbar.js';
-export type { AppToolbarProps } from './AppToolbar.js';
-export { VariableBar } from './VariableBar.js';
-export type { VariableBarProps } from './VariableBar.js';
-export { AppFooter } from './AppFooter.js';
-export type { AppFooterProps } from './AppFooter.js';
-export { ThemeSelector, ThemeToggle } from './ThemeSelector.js';
-export type { ThemeSelectorProps } from './ThemeSelector.js';
-export { Stack } from './Stack.js';
-export type { StackProps } from './Stack.js';
-export { Grid } from './Grid.js';
-export type { GridProps } from './Grid.js';
-export { GridItem } from './GridItem.js';
-export type { GridItemProps } from './GridItem.js';
-export type { WidgetEvidence } from './WidgetEvidence.js';
-export { DataWidget } from './DataWidget.js';
-export type { WidgetStatus } from './RequestHint.js';
-export type { DataWidgetProps } from './DataWidget.js';
-export { VisualizationWidget } from './VisualizationWidget.js';
-export type { VisualizationWidgetProps, VisualizationWidgetView, } from './VisualizationWidget.js';
-export { TableWidget } from './TableWidget.js';
-export type { TableWidgetColumn, TableWidgetProps, TableWidgetSearch, } from './TableWidget.js';
-export { chartColor } from './chartColor.js';
-export { Breakdown } from './Breakdown.js';
-export type { BreakdownItem, BreakdownProps } from './Breakdown.js';
-export { Ranking } from './Ranking.js';
-export type { RankingItem, RankingProps } from './Ranking.js';
-export { WidgetDisclosure } from './WidgetDisclosure.js';
-export type { WidgetDisclosureProps } from './WidgetDisclosure.js';
-export { WidgetViewTabs } from './WidgetViewTabs.js';
-export type { WidgetView, WidgetViewTabsProps, } from './WidgetViewTabs.js';
-export { ComparisonVisual } from './ComparisonVisual.js';
-export type { ComparisonVisualProps } from './ComparisonVisual.js';
-export { calendarMetricComparison } from './comparison.js';
-export type { MetricComparison } from './comparison.js';
-export { DataTable, DataTableEmptyRow, DataTableTimestamp, DataTableShare, } from './DataTable.js';
-export type { DataTableProps, DataTableSearch, DataTableEmptyRowProps, DataTableTimestampProps, } from './DataTable.js';
-export { MetricWidget } from './MetricWidget.js';
-export type { MetricWidgetProps } from './MetricWidget.js';
-export { SelectableBarChart } from './SelectableBarChart.js';
-export type { SelectableBarChartProps, SelectableBarItem, } from './SelectableBarChart.js';
-export { DimensionPicker } from './DimensionPicker.js';
-export { dimensionFilter, parseDimensionSelection, parseFacetOptions, dimensionPredicate, } from '../../core/dimension.js';
-export type { DimensionSelection, DimensionMember, DimensionOption, DimensionVariable, DimensionFilterOptions, } from '../../core/dimension.js';
-export { EmptyState } from './EmptyState.js';
-export type { EmptyStateProps } from './EmptyState.js';
-export { Skeleton } from './Skeleton.js';
-export type { SkeletonProps } from './Skeleton.js';
-export { DataBoundary } from './DataBoundary.js';
-export { resolveDataView } from '../../core/data-view.js';
-export { displayedSnapshot } from '../../core/data-view.js';
-export type { DataView, DataSnapshot, DisplayedSnapshot, } from '../../core/data-view.js';
-export type { DataBoundaryProps } from './DataBoundary.js';
-export { RefreshRegion } from './RefreshRegion.js';
-export type { RefreshRegionProps } from './RefreshRegion.js';
-export { DataSection } from './DataSection.js';
-export type { DataSectionProps, SectionResult, } from './DataSection.js';
-export { StatusPanel } from './StatusPanel.js';
-export type { StatusPanelProps } from './StatusPanel.js';
-export { ContentSkeleton } from './ContentSkeleton.js';
-export type { ContentSkeletonProps } from './ContentSkeleton.js';
-export { DataViewToast } from './DataViewToast.js';
-export type { DataViewToastProps } from './DataViewToast.js';
-export { UpdatedAt } from './UpdatedAt.js';
-export type { UpdatedAtProps } from './UpdatedAt.js';
-export { DateTimeTooltip } from './DateTimeTooltip.js';
-export type { DateTimeTooltipProps } from './DateTimeTooltip.js';
-export { LiveControl } from './LiveControl.js';
-export type { LiveControlProps, LiveIntervalSeconds, } from './LiveControl.js';
-export { DateRangePicker } from './DateRangePicker.js';
-export type { DatePresetId, DateRange, DateRangePickerProps, } from './DateRangePicker.js';
-export { defineAppVariables, textVariable, selectVariable, dateRangeVariable, dateRangeControl, useAppVariables, } from './variables.js';
-export type { AppVariable, AppVariableValues, DateRangeSelection, DateRangeVariable, DateRangeVariableOptions, } from './variables.js';
-export { PeriodSummary } from './PeriodSummary.js';
-export type { ReportingPeriod, PeriodComparison, PeriodSummaryProps, } from './PeriodSummary.js';
-export { SearchField } from './SearchField.js';
-export type { SearchFieldProps } from './SearchField.js';
-export { searchItems } from './searchItems.js';
-export type { SearchAttribute, SearchHit, SearchItemsOptions, SearchMatchValue, SearchRange, } from './searchItems.js';
-export { SearchMatch } from './SearchMatch.js';
-export type { SearchMatchProps } from './SearchMatch.js';
-export { Combobox } from './Combobox.js';
-export type { ComboboxOption, ComboboxProps } from './Combobox.js';
-export { GradientScroll } from './GradientScroll.js';
-export type { GradientScrollProps } from './GradientScroll.js';
-export { searchParams, slug, subscribeSearch, writeSearch, } from './search.js';
-export { Tabs, TabList, Tab, TabPanels, TabPanel, useViewTab, } from './Tabs.js';
-export { createDataContext, defineDataContext, evidenceFor, } from './data-context.js';
-export type { DataContext, GlossaryEntry } from './data-context.js';
-export { defineDataIdentifiers } from './data-identifiers.js';
-export type { DataIdentifierDefinition, TableIdentifier, ColumnIdentifier, } from './data-identifiers.js';
-export type { DisclosedQuery } from '../../core/contract.js';
-export { GlossaryExplanation } from './GlossaryExplanation.js';
-export type { GlossaryExplanationProps } from './GlossaryExplanation.js';
-export { GlossaryDefinition } from './GlossaryDefinition.js';
-export type { GlossaryDefinitionProps } from './GlossaryDefinition.js';
-export { AboutData } from './AboutData.js';
-export type { AboutDataProps, AboutEmpty, AboutSubject, AboutTab, } from './AboutData.js';
-export { PresentStory } from './PresentStory.js';
-export type { PresentStoryProps } from './PresentStory.js';
-export type { StoryFinding, BoundStory } from './story.js';
-export { Checkbox } from './Checkbox.js';
-export type { CheckboxProps } from './Checkbox.js';
-export { AppIcon } from './icons.js';
-export type { AppIconName, AppIconProps } from './icons.js';
-export { IconButton } from './IconButton.js';
-export type { IconButtonProps } from './IconButton.js';
-export { Kbd } from './Kbd.js';
-export type { KbdProps } from './Kbd.js';
-export { Sheet } from './Sheet.js';
-export type { SheetDialogProps, SheetProps } from './Sheet.js';
-export { Tooltip, TooltipProvider } from './Tooltip.js';
-export type { TooltipProps, TooltipProviderProps, } from './Tooltip.js';
-export { Button } from './Button.js';
-export type { ButtonProps } from './Button.js';
-export { HelpPopover } from './HelpPopover.js';
-export type { HelpPopoverPanelProps, HelpPopoverProps, HelpPopoverTriggerProps, } from './HelpPopover.js';
-export type { MetricDefinition } from './metric.js';
-export type { DataReading, MetricReading, MetricValues, } from '../../core/reading.js';

package/docs/appearance.md

@@ -1,30 +0,0 @@
-# Appearance
-
-Import `parseAppearance`, `applyAppearance`, and `createThemeController` from
-`@altertable/data-app/appearance`. Parsing is safe on the server; applying tokens
-and controlling theme require a browser document.
-
-```ts
-import { parseAppearance } from '@altertable/data-app/appearance';
-
-const appearance = parseAppearance({
-  mode: 'system',
-  accentColor: '#405d47',
-  density: 'comfortable',
-});
-```
-
-`parseAppearance` fills omitted settings with defaults and rejects unknown keys
-or invalid values. Settings include light/dark/system mode, neutral/slate/warm
-base colors, accent colors, a chart palette, density, corner radius, elevation,
-and body/heading typography. Colors are six-digit hexadecimal values.
-
-`applyAppearance(appearance)` installs semantic CSS tokens on the document root
-and returns a cleanup function for system-theme listening.
-`createThemeController(appearance)` applies the initial theme and provides
-`getMode`, `setMode`, and `subscribe`. Viewer mode persists in local storage
-independently of app-authored brand settings. Storage failures do not prevent
-the selection from applying to the current page.
-
-The React `DataApp` shell manages appearance for normal app usage. See
-[configuration](config.md), [React](react.md), and [styles](react-styles.md).

package/docs/bootstrap.md

@@ -1,76 +0,0 @@
-# Standalone bootstrap
-
-`@altertable/data-app/bootstrap` resolves to a self-contained classic browser
-script. It has no imports, React dependencies, or app navigation behavior. The
-package builds it once; a backend can embed the published file without running a
-bundler.
-
-This entry is a script asset, not a module API. Resolve and read it on the server;
-do not import it for execution in Node.js or Bun. For a bootstrap you bundle
-yourself, use `startDataAppBootstrap` from [embedding](embed.md).
-
-## Generate the backend HTML
-
-Install an exact package version in the backend runtime's `package.json`, commit
-the lockfile, and run this generation step before building or deploying the worker:
-
-```js
-// scripts/build-runtime.mjs
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-
-const parentOrigin = 'https://app.altertable.ai';
-const path = import.meta.resolve('@altertable/data-app/bootstrap');
-const javascript = await readFile(new URL(path), 'utf8');
-const inline = javascript.replace(/<\/script/gi, '<\\/script');
-const originAttribute = parentOrigin
-  .replaceAll('&', '&amp;')
-  .replaceAll('"', '&quot;')
-  .replaceAll('<', '&lt;')
-  .replaceAll('>', '&gt;');
-
-const html = `<!doctype html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-  </head>
-  <body>
-    <div id="root"></div>
-    <script data-parent-origin="${originAttribute}">${inline}</script>
-  </body>
-</html>`;
-
-await mkdir('generated', { recursive: true });
-await writeFile(
-  'generated/runtime-html.js',
-  `export const RUNTIME_HTML = ${JSON.stringify(html)};\n`
-);
-```
-
-```fish
-node scripts/build-runtime.mjs
-```
-
-The worker imports `RUNTIME_HTML` and serves it as `text/html; charset=utf-8`.
-The resulting HTML needs no package imports or network fetches at runtime.
-
-## Configuration and security
-
-Use a regular inline `<script>` with `data-parent-origin` on that same element,
-after the app's mount element. The script reads `document.currentScript` and
-starts immediately. Do not use `type="module"`.
-
-The hosting service must supply an exact trusted origin, such as
-`https://app.altertable.ai`, through deployment configuration. Missing or invalid
-origins fail before installing a transport. Do not derive this value from an
-unverified query parameter, referrer, or incoming message.
-
-Serve the HTML with the [bootstrap CSP](embed.md#trusted-bootstrap), including a
-`frame-ancestors` header restricted to the trusted host. The script installs the
-authenticated transport, retains opaque host state, evaluates the app bundle
-sent by the host, and reports readiness or failure. The app attaches its own
-navigation adapter. Backend authorization still applies to every data request.
-
-Upgrade the host package and bootstrap artifact together when changing the bridge
-protocol. See [client navigation](client.md#app-navigation) and
-[embedding](embed.md) for the communication boundaries.

package/docs/config.md

@@ -1,21 +0,0 @@
-# App configuration
-
-Import `DataAppConfig` and `dataAppTitle` from `@altertable/data-app/config`.
-Configuration is shared by the app shell and browser mounting code.
-
-```ts
-import type { DataAppConfig } from '@altertable/data-app/config';
-
-export const config = {
-  title: 'Activity',
-  scope: { organization: 'example', environment: 'production' },
-  appearance: {},
-} satisfies DataAppConfig;
-```
-
-`title` names the exploration. `scope` identifies its organization and
-environment for display; it does not grant access to data.
-`appearance` is validated by the [appearance APIs](appearance.md).
-
-`dataAppTitle(config)` produces a document title containing the app title and
-scope. [React mounting](react.md) applies it automatically.

package/docs/format.md

@@ -1,29 +0,0 @@
-# Formatting
-
-Import number and date helpers from `@altertable/data-app/format`. They use
-JavaScript `Intl` APIs and can run in the browser or on the server.
-
-```ts
-import {
-  formatCount,
-  formatDateRange,
-  formatNumber,
-  formatPercent,
-} from '@altertable/data-app/format';
-
-formatCount(1200); // "1,200"
-formatPercent(0.116); // "11.6%"
-formatNumber(null); // "—"
-formatDateRange({ start: '2026-01-01', end: '2026-01-03' });
-```
-
-Percent values are ratios: `0.116` means 11.6%. Counts must be non-negative
-integers. Missing or non-finite numbers render as `—`, customizable with
-`missing`. Number formatting defaults to `en-US`; pass `locale` to override it.
-
-`formatMetric` accepts a `MetricFormat` with `kind: 'count'`, `'ratio'`, or
-`'currency'`; currency formats also require a currency code. `formatDateRange`
-formats ISO calendar dates in UTC and retains the year in its labels.
-`pluralize(count, singular, plural?)` selects a label for the count.
-
-See [React metric definitions](react.md#bound-views-and-widgets).

package/docs/react-styles.md

@@ -1,17 +0,0 @@
-# React styles
-
-Import the stylesheet once from the browser entry:
-
-```ts
-import '@altertable/data-app/react/styles.css';
-```
-
-This entry is a CSS asset, with a declaration for TypeScript side-effect imports.
-The app's bundler must process CSS imports. The React JavaScript entry does not
-load it automatically, so server rendering can import components without
-importing CSS into Node.
-
-Stylesheets live beside their components in `src/react/ui` and are combined into
-the published stylesheet during the build. Brand settings install semantic CSS
-variables through [appearance](appearance.md); the [React app shell](react.md)
-manages these for normal app usage.

package/docs/starter-agent-instructions.md

@@ -1,53 +0,0 @@
-# Starter agent instructions
-
-The package ships `AGENTS.md`, public documentation in `docs/`, and declarations
-referenced by its export map. Its agent guide describes package usage and includes
-a separate section for contributors working in the package source repository.
-
-A starter application's `AGENTS.md` owns its file paths, commands, and analysis
-context. Keep it in the consuming app and explicitly direct agents to the
-installed package guide. Dependency instructions are not guaranteed to be loaded
-automatically: for example, [Codex discovers project instructions along the path
-from the project root to its working directory](https://learn.chatgpt.com/docs/agent-configuration/agents-md),
-not by scanning every dependency.
-
-These installed docs replace references to the old vendored `.altertable/runtime`
-layout for apps using this package.
-
-Adapt this template to the starter's actual files and scripts:
-
-```markdown
-# Build this data app
-
-Inspect source data, time coverage, and existing definitions before choosing an
-exploration. Build conclusions from observed results; do not present association
-as cause. Keep copy concise and relevant to the reader.
-
-Read `node_modules/@altertable/data-app/AGENTS.md` first, then
-`node_modules/@altertable/data-app/docs/app-authoring.md`.
-
-| Task                                     | App-owned files                             | Package documentation                  |
-| ---------------------------------------- | ------------------------------------------- | -------------------------------------- |
-| Define queries and inputs                | `src/operations.ts`, shared input contracts | `docs/contract.md`, `docs/server.md`   |
-| Build views, filters, and request states | `src/App.tsx`                               | `docs/react.md`                        |
-| Explain terms and query evidence         | `src/data-context.ts` or `.tsx`             | `docs/react.md#bind-evidence`          |
-| Change identity and brand                | App configuration                           | `docs/config.md`, `docs/appearance.md` |
-| Configure local serving or hosting       | `src/server.ts`                             | `docs/server-bun.md`, `docs/server.md` |
-
-Package documentation paths above are relative to
-`node_modules/@altertable/data-app/`.
-
-Edit app-owned source and import public package entries. Keep SQL and credentials
-on the server, and import operation types with `import type` in browser code.
-Do not edit installed package files. The connectivity screen is scaffolding,
-not an example analysis.
-
-Run the app's typecheck, lint, and build scripts. Inspect its findings and
-interactions at phone and desktop widths, including loading, empty, error, and
-stale states. Verify that the exploration answers the user's question.
-```
-
-A runnable port of the CLI starter lives in
-[`examples/starter`](https://github.com/altertable-ai/data-app/tree/main/examples/starter). It consumes the built public
-package and keeps its own app instructions. Updating CLI scaffolding to consume
-the published package remains a separate migration.