@altertable/data-app 0.59.1

package/dist/types/react/ui/data-context.d.ts

@@ -0,0 +1,65 @@
+import type { ReactNode } from 'react';
+import type { DataIdentifierDefinition } from './data-identifiers.js';
+import type { MetricFormat } from '../../core/format.js';
+import type { MetricDefinition } from './metric.js';
+import type { StoryFinding } from './story.js';
+import type { WidgetEvidence } from './WidgetEvidence.js';
+export type GlossaryEntry = {
+    term: string;
+    definition: ReactNode;
+    queryNames?: string[];
+};
+export type DataContext = {
+    description: ReactNode;
+    glossary: Record<string, GlossaryEntry>;
+    identifiers?: Readonly<Record<string, DataIdentifierDefinition>>;
+    queryNames?: Readonly<Record<string, string>>;
+};
+export declare function defineDataContext<const Context extends DataContext>(context: Context): Context;
+export declare function evidenceFor<const Context extends DataContext, const Names extends Record<string, string> = Record<string, string>>(context: Context, names?: Names): (evidence: {
+    id: string;
+    glossaryIds?: readonly (keyof Context['glossary'] & string)[];
+    queryNames?: readonly Names[keyof Names][];
+}) => {
+    id: string;
+    glossaryIds: (keyof Context["glossary"] & string)[] | undefined;
+    queryNames: Names[keyof Names][] | undefined;
+};
+/** Bind glossary query references and card evidence to the same registry. */
+export declare function createDataContext<const Names extends Record<string, string>>(queryNames: Names): <const Context extends Omit<DataContext, 'glossary'> & {
+    glossary: Record<string, Omit<GlossaryEntry, 'queryNames'> & {
+        queryNames?: Names[keyof Names][];
+    }>;
+}>(context: Context) => Context & {
+    queryNames: Names;
+    evidence: (input: {
+        id: string;
+    } & ({
+        glossaryIds: readonly [keyof Context["glossary"] & string, ...(keyof Context["glossary"] & string)[]];
+        queryNames?: readonly Names[keyof Names][];
+    } | {
+        queryNames: readonly [Names[keyof Names], ...Names[keyof Names][]];
+        glossaryIds?: readonly (keyof Context["glossary"] & string)[];
+    })) => WidgetEvidence;
+    finding: (input: Omit<StoryFinding, 'evidence'> & {
+        evidence: Parameters<(input: {
+            id: string;
+        } & ({
+            glossaryIds: readonly [keyof Context["glossary"] & string, ...(keyof Context["glossary"] & string)[]];
+            queryNames?: readonly Names[keyof Names][];
+        } | {
+            queryNames: readonly [Names[keyof Names], ...Names[keyof Names][]];
+            glossaryIds?: readonly (keyof Context["glossary"] & string)[];
+        })) => WidgetEvidence>[0];
+    }) => StoryFinding & {
+        evidence: WidgetEvidence;
+    };
+    metric: (definition: {
+        id: string;
+        glossaryId: keyof Context['glossary'] & string;
+        label?: string;
+        format: MetricFormat;
+        favorableDirection?: 'up' | 'down';
+        queryNames?: readonly Names[keyof Names][];
+    }) => MetricDefinition;
+};

package/dist/types/react/ui/data-identifiers.d.ts

@@ -0,0 +1,33 @@
+
+export type TableIdentifier = {
+    catalog: string;
+    schema: string;
+    name: string;
+};
+export type ColumnIdentifier<TableId extends string = string> = {
+    table: TableId;
+    name: string;
+};
+export type DataIdentifierDefinition = ({
+    kind: 'table';
+} & TableIdentifier) | {
+    kind: 'column';
+    tableId: `tables.${string}`;
+    table: TableIdentifier;
+    name: string;
+};
+type IdentifierId<Tables extends Record<string, TableIdentifier>, Columns extends Record<string, ColumnIdentifier<Extract<keyof Tables, string>>>> = `tables.${Extract<keyof Tables, string>}` | {
+    [Id in Extract<keyof Columns, string>]: `columns.${Columns[Id]['table']}.${Id}`;
+}[Extract<keyof Columns, string>];
+/** Register exact source names once; returned JSX IDs are checked against this registry. */
+export declare function defineDataIdentifiers<const Tables extends Record<string, TableIdentifier>, const Columns extends Record<string, ColumnIdentifier<Extract<keyof Tables, string>>>>({ tables, columns }: {
+    tables: Tables;
+    columns: Columns;
+}): {
+    definitions: Readonly<Record<IdentifierId<Tables, Columns>, DataIdentifierDefinition>>;
+    DataIdentifier: ({ id, display, }: {
+        id: IdentifierId<Tables, Columns>;
+        display?: 'short' | 'qualified';
+    }) => import("react").JSX.Element;
+};
+export {};

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

@@ -0,0 +1,42 @@
+import { type LucideProps } from 'lucide-react';
+/** Use semantic names to keep icon meaning and optical size consistent across controls. */
+declare const brandedIcons: {
+    readonly cancel: import("lucide-react").LucideIcon;
+    readonly calendar: import("lucide-react").LucideIcon;
+    readonly clock: import("lucide-react").LucideIcon;
+    readonly check: import("lucide-react").LucideIcon;
+    readonly disclosure: import("lucide-react").LucideIcon;
+    readonly previousMonth: import("lucide-react").LucideIcon;
+    readonly nextMonth: import("lucide-react").LucideIcon;
+    readonly explore: import("lucide-react").LucideIcon;
+    /** @deprecated Use openDetails for inspection triggers. */
+    readonly inspect: import("lucide-react").LucideIcon;
+    readonly info: import("lucide-react").LucideIcon;
+    readonly openDetails: import("lucide-react").LucideIcon;
+    readonly present: import("lucide-react").LucideIcon;
+    readonly error: import("lucide-react").LucideIcon;
+    readonly close: import("lucide-react").LucideIcon;
+    readonly previous: import("lucide-react").LucideIcon;
+    readonly next: import("lucide-react").LucideIcon;
+    readonly lightTheme: import("lucide-react").LucideIcon;
+    readonly darkTheme: import("lucide-react").LucideIcon;
+    readonly live: import("lucide-react").LucideIcon;
+    readonly loading: import("lucide-react").LucideIcon;
+    readonly refresh: import("lucide-react").LucideIcon;
+    readonly stop: import("lucide-react").LucideIcon;
+    readonly reset: import("lucide-react").LucideIcon;
+    readonly search: import("lucide-react").LucideIcon;
+    readonly copy: import("lucide-react").LucideIcon;
+    readonly sql: import("lucide-react").LucideIcon;
+    readonly wrap: import("lucide-react").LucideIcon;
+    readonly trendDown: import("lucide-react").LucideIcon;
+    readonly trendFlat: import("lucide-react").LucideIcon;
+    readonly trendUp: import("lucide-react").LucideIcon;
+};
+export type AppIconName = keyof typeof brandedIcons;
+export type AppIconProps = Omit<LucideProps, 'size'> & {
+    name: AppIconName;
+    size?: number;
+};
+export declare function AppIcon({ name, size, strokeWidth, style, ...props }: AppIconProps): import("react").FunctionComponentElement<Omit<LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+export {};

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

@@ -0,0 +1,129 @@
+
+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/dist/types/react/ui/metric.d.ts

@@ -0,0 +1,11 @@
+import type { MetricFormat } from '../../core/format.js';
+import type { WidgetEvidence } from './WidgetEvidence.js';
+import type { MetricReading } from '../../core/reading.js';
+export type MetricDefinition = {
+    id: string;
+    label: string;
+    format: MetricFormat;
+    favorableDirection?: 'up' | 'down';
+    evidence: WidgetEvidence;
+};
+export declare function metricComparison(metric: MetricDefinition, reading: MetricReading): import("./comparison.js").MetricComparison | undefined;

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

@@ -0,0 +1,6 @@
+export declare function searchParams(): URLSearchParams;
+/** Listen to Back/Forward and writes made by another runtime control. */
+export declare function subscribeSearch(listener: () => void): () => void;
+/** Write search keys. `null` removes a key. Skips the history write when nothing changed. */
+export declare function writeSearch(update: Record<string, string | null>, mode?: 'replace' | 'push'): void;
+export declare function slug(value: string): string;

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

@@ -0,0 +1,34 @@
+export type SearchRange = {
+    start: number;
+    end: number;
+};
+/** The exact displayed text and its offsets stay together for safe rendering. */
+export type SearchMatchValue = {
+    text: string;
+    ranges: readonly SearchRange[];
+};
+export type SearchAttribute<Item> = {
+    name: string;
+    getter: (item: Item) => string;
+    weight?: number;
+};
+export type SearchHit<Item> = {
+    item: Item;
+    score: number;
+    /** Render displayed fields with <SearchMatch match={hit.matches.fieldName} />. */
+    matches: Record<string, SearchMatchValue>;
+};
+export type SearchItemsOptions<Item> = {
+    attributes: readonly [SearchAttribute<Item>, ...SearchAttribute<Item>[]];
+    /** Literal filtering preserves source order; fuzzy search ranks discovery results. */
+    mode?: 'literal' | 'fuzzy';
+    limit?: number;
+    fuzzyThreshold?: number;
+};
+/**
+ * Search only a complete local collection. Empty queries retain every item.
+ * When a searched field is displayed, render its match with SearchMatch:
+ * `hits.map(hit => <SearchMatch match={hit.matches.name} />)`.
+ * Fields used only to find a row need no visible highlight.
+ */
+export declare function searchItems<Item>(items: readonly Item[], query: string, options: SearchItemsOptions<Item>): SearchHit<Item>[];

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

@@ -0,0 +1,32 @@
+/**
+ * `alt` is Alt/Option, leaving character keys and browser refresh untouched; `mod` is ⌘ on Apple
+ * platforms and Ctrl elsewhere.
+ */
+export type Shortcut = {
+    modifier: 'alt' | 'mod';
+    shift?: boolean;
+    code: string;
+    key: string;
+};
+export declare const shortcuts: {
+    readonly refresh: {
+        readonly modifier: 'alt';
+        readonly code: 'KeyR';
+        readonly key: 'R';
+    };
+    readonly aboutData: {
+        readonly modifier: 'alt';
+        readonly code: 'KeyI';
+        readonly key: 'I';
+    };
+    readonly playStory: {
+        readonly modifier: 'mod';
+        readonly code: 'Enter';
+        readonly key: 'Enter';
+    };
+};
+export declare function shortcutLabel({ modifier, shift, key }: Shortcut): string;
+export declare function ariaKeyShortcuts({ modifier, shift, key }: Shortcut): string;
+export declare function isEditingTarget(target: EventTarget | null): boolean;
+/** Bind a page-level shortcut. Ignored while typing or while a modal layer is open. */
+export declare function useShortcut(shortcut: Shortcut, action: () => void, enabled?: boolean): void;

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

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { DisplayedSnapshot } from '../../core/data-view.js';
+import type { MetricDefinition } from './metric.js';
+import type { StoryStep } from './PresentStory.js';
+import type { WidgetEvidence } from './WidgetEvidence.js';
+import type { DataContext } from './data-context.js';
+/** One consequential, inspectable finding from the displayed result. */
+export type StoryFinding = {
+    id: string;
+    headline: string;
+    context?: string;
+    visual: ReactNode;
+    visualKind?: 'metric' | 'chart';
+    evidence: WidgetEvidence | MetricDefinition;
+};
+/** One to four findings with unique, nonempty IDs and registered evidence.
+ * Receives the displayed result and its original input during refresh or failure. */
+export type BoundStory<Data, Input> = (snapshot: DisplayedSnapshot<Data, Input>) => readonly StoryFinding[];
+/** Validate the authored findings before handing them to the presentation UI. */
+export declare function storySteps(findings: readonly StoryFinding[], context: DataContext): StoryStep[];

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

@@ -0,0 +1,36 @@
+import type { DatePresetId, DateRange } from '../../core/date-range.js';
+import { type AppVariableValues, type DateRangeSelection, type DateRangeVariable, type HistoryMode, type VariableCollection } from '../../core/variables.js';
+export { defineAppVariables, textVariable, selectVariable, dateRangeVariable, } from '../../core/variables.js';
+export type { AppVariable, AppVariableValues, DateRangeSelection, DateRangeVariable, DateRangeVariableOptions, VariableCollection, } from '../../core/variables.js';
+/** Adapt one date variable to the controlled picker without giving the picker URL ownership. */
+export declare function dateRangeControl(variable: DateRangeVariable, selection: DateRangeSelection, onChange: (selection: DateRangeSelection) => void): {
+    minDate?: string;
+    maxDate: string;
+    maxRangeDays: number;
+    timeZone: string;
+    value: DateRange;
+    label: string | undefined;
+    onChange(range: DateRange | null): void;
+    onPresetChange(id: DatePresetId): void;
+    selectedPresetId: DatePresetId | null;
+    onReset(): void;
+    isDefault: boolean;
+    resetValue: DateRange;
+    comparison?: {
+        enabled: boolean;
+        range: DateRange | null;
+        onChange(enabled: boolean): void;
+    } | undefined;
+};
+/** URL is the source of truth for app variables; one update can change dependent values atomically. */
+export declare function useAppVariables<const Variables extends VariableCollection>(definitions: Variables): {
+    values: AppVariableValues<Variables>;
+    set: <Key extends keyof Variables & string>(name: Key, value: AppVariableValues<Variables>[Key]) => void;
+    reset: <Key extends keyof Variables & string>(name: Key) => void;
+    update: (next: Partial<AppVariableValues<Variables>>, history?: HistoryMode) => void;
+    bind: <Key extends keyof Variables & string>(name: Key) => {
+        value: AppVariableValues<Variables>[Key];
+        onChange(value: AppVariableValues<Variables>[Key]): void;
+        resetValue: AppVariableValues<Variables>[Key];
+    };
+};

package/dist/types/react/ui/widget-views.d.ts

@@ -0,0 +1,3 @@
+export declare function validateWidgetViews(views: readonly {
+    id: string;
+}[], selected: string): void;

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

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import { type AppVariableValues, type VariableCollection } from './ui/variables.js';
+import type { ResolvedVariables } from './view.js';
+/** URL values resolve before facets; facet keys include their dependent inputs for cached, bounded loading. */
+export declare function useViewVariables<Variables extends VariableCollection>(definitions: Variables, loadFacet: (operation: string, input: unknown, signal: AbortSignal) => Promise<unknown>): {
+    values: AppVariableValues<Variables>;
+    set: <Key extends keyof Variables & string>(name: Key, value: AppVariableValues<Variables>[Key]) => void;
+    reset: <Key extends keyof Variables & string>(name: Key) => void;
+    update: (next: Partial<AppVariableValues<Variables>>, history?: import("../core/variables.js").HistoryMode) => void;
+    bind: <Key extends keyof Variables & string>(name: Key) => {
+        value: AppVariableValues<Variables>[Key];
+        onChange(value: AppVariableValues<Variables>[Key]): void;
+        resetValue: AppVariableValues<Variables>[Key];
+    };
+    resolved: ResolvedVariables<Variables>;
+    controls: ReactNode[] | null;
+};

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

@@ -0,0 +1,49 @@
+import type { EmptyStateProps } from './ui/EmptyState.js';
+import type { AppVariableValues, DateRangeVariable, VariableCollection } from '../core/variables.js';
+import type { DateRangeRequest } from '../core/contract.js';
+export type ResolvedVariables<Variables extends VariableCollection> = {
+    [Key in keyof Variables]: Variables[Key] extends DateRangeVariable ? DateRangeRequest : AppVariableValues<Variables>[Key];
+};
+type DateVariableKey<Variables extends VariableCollection> = {
+    [Key in keyof Variables]: Variables[Key] extends DateRangeVariable ? Key : never;
+}[keyof Variables] & string;
+export type ViewDate<Variables extends VariableCollection, Input> = {
+    variable: DateVariableKey<Variables>;
+    /** Extract the selected range and comparison unchanged, including from nested inputs. */
+    input: (input: Input) => DateRangeRequest;
+};
+/** Read variable values from a custom operation input; omitted keys use top-level fields. */
+export type ViewBindings<Variables extends VariableCollection, Input> = Partial<{
+    [Key in keyof Variables]: (input: Input) => ResolvedVariables<Variables>[Key];
+}>;
+export type DataViewDefinition<Name extends string, Variables extends VariableCollection, Input, Data> = {
+    operation: Name;
+    variables: Variables;
+    input: (values: ResolvedVariables<Variables>) => Input;
+    bindings?: ViewBindings<Variables, Input>;
+    /** App-owned semantics: measured zero need not mean an empty result. */
+    isEmpty: (data: Data) => boolean;
+    empty: Pick<EmptyStateProps, 'title' | 'description'>;
+} & ({
+    date: ViewDate<Variables, Input>;
+    describeInput?: (input: Input) => string;
+} | {
+    date?: never;
+    describeInput: (input: Input) => string;
+});
+export declare function describeViewInput<Input>(definition: {
+    variables: VariableCollection;
+    bindings?: Partial<Record<string, (input: Input) => unknown>>;
+    date?: {
+        variable: string;
+        input: (input: Input) => DateRangeRequest;
+    };
+    describeInput?: (input: Input) => string;
+}): (input: Input) => string;
+export declare function resolveViewInput<Variables extends VariableCollection, Input>(definition: {
+    input: (values: ResolvedVariables<Variables>) => Input;
+    date?: ViewDate<Variables, Input>;
+    variables: Variables;
+    bindings?: ViewBindings<Variables, Input>;
+}, values: ResolvedVariables<Variables>): Input;
+export {};

package/dist/types/server/handler.d.ts

@@ -0,0 +1,13 @@
+import { type DataOperations, type Lakehouse } from '../core/contract.js';
+/** Authorization result for one viewer request. A hosted adapter must scope its lakehouse client. */
+export type RequestAccess = {
+    lakehouse: Lakehouse;
+    canDiscloseSql: boolean;
+};
+/**
+ * Execute named operations on the server. The app supplies operations and viewer authorization.
+ * JSON, Origin, and Fetch Metadata checks reject cross-site browser POSTs; they do not
+ * authenticate another local process. SQL is returned only when both the operation and
+ * authorization result permit disclosure.
+ */
+export declare function createDataHandler(operations: DataOperations, authorize: (request: Request, operation: string) => Promise<RequestAccess>): (request: Request) => Promise<Response>;

package/dist/types/server/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Portable request handling with app-supplied authorization.
+ * @module @altertable/data-app/server
+ * @see https://github.com/altertable-ai/data-app/blob/main/docs/server.md
+ */
+export { createDataHandler } from './handler.js';
+export type { RequestAccess } from './handler.js';

package/dist/types/server/local.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Bun local-development serving and server-only lakehouse access.
+ * @module @altertable/data-app/server/bun
+ * @see https://github.com/altertable-ai/data-app/blob/main/docs/server-bun.md
+ */
+import { type Lakehouse } from '../core/contract.js';
+import type { DataOperations } from '../core/contract.js';
+/** Serve one app on localhost through the CLI's lakehouse proxy during development.
+ * Hosted servers must authorize every viewer and must use `createDataHandler` directly. */
+export declare function serveLocalApp({ page, operations, title, port, }: {
+    page: Bun.HTMLBundle;
+    operations: DataOperations;
+    title: string;
+    port?: number;
+}): Bun.Server<undefined>;
+/** Server-only lakehouse adapter. Local development uses the selected CLI profile's proxy. */
+export declare function localLakehouse(environment?: Record<string, string | undefined>, request?: typeof fetch): Lakehouse;

package/docs/app-authoring.md

@@ -0,0 +1,26 @@
+# Author a data app
+
+An app owns its question, SQL, result parsing, business definitions, configuration,
+and presentation. The package supplies contracts, request handling, typed client
+calls, and reusable React UI.
+
+1. Inspect the source data, time coverage, and existing definitions before choosing
+   the exploration. Build findings from observed results and distinguish
+   association from cause.
+2. Define named, bounded [operations](contract.md) on the server. Put shared input
+   contracts in a browser-safe module and validate outputs before returning them.
+3. Use a [server handler](server.md) that authorizes each request, or the
+   [Bun adapter](server-bun.md) for local development.
+4. Create a typed [client](client.md) and compose [React views](react.md). Import
+   the operation registry with `import type` in browser code.
+5. Define glossary and query evidence, handle empty results, and preserve the
+   displayed input while a request refreshes or fails. A measured zero and an
+   unavailable value must remain distinct.
+6. Verify the app's findings and interactions against the original question.
+   Inspect loading, error, stale, and empty states at desktop and phone widths.
+
+Import through `@altertable/data-app/<entry>`. Installed package files are
+dependencies; customize the app's own source rather than editing `node_modules`.
+SQL, credentials, and viewer authorization belong on the server.
+
+For agent-assisted authoring, see the [starter AGENTS.md template](starter-agent-instructions.md).

package/docs/appearance.md

@@ -0,0 +1,30 @@
+# 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).