@altertable/data-app 0.62.0 → 0.64.0

package/dist/react.css.d.ts

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

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

@@ -1,131 +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 { DataAppSkeleton } from './DataAppSkeleton.js';
-export type { DataAppSkeletonProps } from './DataAppSkeleton.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,43 +0,0 @@
-# Appearance
-
-Import `parseAppearance`, `applyAppearance`, and `createThemeController` from
-`@altertable/data-app/appearance`. Parsing is safe on the server. Applying tokens requires a browser document;
-viewer preferences use browser storage.
-
-```ts
-import { parseAppearance } from '@altertable/data-app/appearance';
-
-const appearance = parseAppearance({
-  theme: 'system',
-  accentColor: '#405d47',
-  density: 'comfortable',
-});
-```
-
-`parseAppearance` fills omitted settings with defaults and rejects unknown keys
-or invalid values. Settings include light/dark/system theme, 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(initialTheme)` manages the viewer's preference through
-`getTheme`, `setTheme`, and `subscribe`. It reads and persists local storage
-when available. Apply the preference with `applyAppearance` in the UI owner;
-the controller itself does not modify the document.
-
-The React `DataApp` shell manages appearance for normal app usage. See
-[configuration](config.md), [React](react.md), and [styles](react-styles.md).
-
-`Theme` is the resolved `'light' | 'dark'` theme. `ThemePreference` additionally
-allows `'system'` for standalone viewers. A trusted host supplies a `theme: Theme`
-through [parent presentation](embed.md#parent-presentation). React applies that
-theme directly with app-owned brand tokens; standalone viewers use the preference
-controller. Appearance effect cleanup releases the system preference listener.
-
-When migrating theme controls, replace `getMode`/`setMode` with
-`getTheme`/`setTheme`, and initialize the controller with a `ThemePreference`
-rather than appearance settings. Subscribe to the controller and compose its
-preference with `applyAppearance` to update document tokens.
-
-Appearance configuration uses `theme` (formerly `mode`).

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.