@altertable/data-app 0.59.1

package/dist/types/core/contract.d.ts

@@ -0,0 +1,139 @@
+export type QueryResult = {
+    columns: {
+        name: string;
+        type?: string;
+    }[];
+    rows: unknown[][];
+    queryId?: string;
+};
+export declare function parseEmptyInput(value: unknown): Record<string, never>;
+export declare function parseTrue(value: unknown): true;
+export type DateRangeInput = {
+    start: string;
+    end: string;
+};
+export type DateRangeRequest = {
+    range: DateRangeInput;
+    comparison: DateRangeInput | null;
+};
+/** The immediately preceding, equally long set of calendar days. */
+export declare function previousDateRange({ start, end, }: DateRangeInput): DateRangeInput;
+export type ReportingPeriod = {
+    kind: 'rolling';
+    amount: number;
+    unit: 'hour' | 'day';
+    end: string;
+} | {
+    kind: 'calendar';
+    start: string;
+    end: string;
+    timeZone: string;
+};
+export type DateRangeContractOptions = {
+    minDate?: string;
+    maxDate?: string | (() => string);
+    maxRangeDays: number;
+    timeZone: string;
+    completeDays?: boolean;
+};
+/** One source policy for the server parser, URL variable, and displayed reporting period. */
+export declare function defineDateRangeContract(options: DateRangeContractOptions): {
+    request: (value: unknown, compare?: boolean) => DateRangeRequest;
+    parseRequest: (value: unknown) => DateRangeRequest;
+    bounds: () => {
+        minDate: string | undefined;
+        maxDate: string;
+        maxRangeDays: number;
+        timeZone: string;
+    };
+    parse(value: unknown): DateRangeInput;
+    period: ({ start, end }: DateRangeInput) => ReportingPeriod;
+    comparison: (input: DateRangeInput) => DateRangeInput | null;
+    describeInput: (input: DateRangeInput) => string;
+    view: {
+        period: ({ start, end }: DateRangeInput) => ReportingPeriod;
+        describeInput: (input: DateRangeInput) => string;
+    };
+};
+export type DateRangeContract = ReturnType<typeof defineDateRangeContract>;
+/** Validate calendar dates and a bounded inclusive range on the server. */
+export declare function parseDateRangeInput(value: unknown, { minDate, maxDate, maxRangeDays, }: {
+    minDate?: string;
+    maxDate?: string;
+    maxRangeDays: number;
+}): DateRangeInput;
+/** Accepts numeric strings from DuckDB; rejects negative, fractional, and unsafe integers. */
+export declare function parseCount(value: unknown): number;
+export declare function parseLabel(value: unknown, maxLength?: number): string;
+/** Rejects missing or duplicate columns and rows whose width differs from the column list. */
+export declare function rowsAsRecords(result: QueryResult, requiredColumns: readonly string[]): Record<string, unknown>[];
+/** One named statement an operation ran. Returned only when SQL disclosure is allowed. */
+export type DisclosedQuery = {
+    name: string;
+    statement: string;
+    queryId?: string;
+};
+export declare function defineQueryNames<const Names extends Record<string, string>>(names: Names): Names;
+export declare class DataSourceError extends Error {
+    readonly reason: 'unauthorized' | 'forbidden' | 'rate_limited' | 'query_rejected' | 'unavailable';
+    readonly status?: number | undefined;
+    queryName?: string;
+    constructor(reason: 'unauthorized' | 'forbidden' | 'rate_limited' | 'query_rejected' | 'unavailable', status?: number | undefined);
+}
+/** Server-only query interface supplied by a local or hosted adapter. */
+export type Lakehouse = {
+    queryAll(statement: string, options: {
+        limit: number;
+        signal: AbortSignal;
+        name?: string;
+    }): Promise<QueryResult>;
+};
+export type OperationContext = {
+    lakehouse: Lakehouse;
+    signal: AbortSignal;
+};
+/**
+ * Both parsers run on the server before results cross the JSON boundary. Schema libraries can be
+ * used inside either parser.
+ */
+export type DataOperation<Input, Output> = {
+    input: (value: unknown) => Input;
+    output: (value: unknown) => Output;
+    run: (context: OperationContext, input: Input) => Promise<Output>;
+    checks: readonly Input[];
+    queryNames?: Readonly<Record<string, string>>;
+    policy: {
+        maxQueryRows: number;
+        maxDurationMs: number;
+        maxResponseBytes?: number;
+        exposeSql?: boolean;
+    };
+};
+export type OperationQuery<Names extends Readonly<Record<string, string>>> = (name: Names[keyof Names], statement: string, options?: {
+    limit?: number;
+}) => Promise<QueryResult>;
+export declare function defineOperation<Input, Output, const Names extends Readonly<Record<string, string>> = Record<string, never>>(operation: Omit<DataOperation<Input, Output>, 'run' | 'queryNames'> & {
+    queryNames?: Names;
+    run: (context: OperationContext & {
+        query: OperationQuery<NoInfer<Names>>;
+    }, input: Input) => Promise<Output>;
+}): DataOperation<Input, Output> & {
+    queryNames?: Names;
+};
+export declare const connectionQueryNames: {
+    readonly connection: "connection-check";
+};
+/** Success requires a bounded SQL query; it does not establish access to a particular dataset. */
+export declare function connectionCheck(): DataOperation<Record<string, never>, true>;
+export type DataOperations = Record<string, {
+    input: (value: unknown) => unknown;
+    output: (value: unknown) => unknown;
+    run: (context: OperationContext, input: never) => Promise<unknown>;
+    checks: readonly unknown[];
+    queryNames?: Readonly<Record<string, string>>;
+    policy: DataOperation<never, unknown>['policy'];
+}>;
+export { dimensionFilter, parseDimensionSelection, parseFacetOptions, dimensionPredicate, } from './dimension.js';
+export type { DimensionSelection, DimensionMember, DimensionOption, DimensionVariable, DimensionFilterOptions, } from './dimension.js';
+export * from './messages.js';
+export type { TransportResponse } from './bridge.js';

package/dist/types/core/data-view.d.ts

@@ -0,0 +1,46 @@
+export type DataView<T, Input = unknown> = {
+    kind: 'loading';
+} | {
+    kind: 'empty';
+    input: Input;
+} | {
+    kind: 'error';
+    error: Error;
+} | {
+    kind: 'ready';
+    data: T;
+    input: Input;
+} | {
+    kind: 'updating';
+    data: T;
+    requestedInput: Input;
+    displayedInput: Input;
+    message: string;
+} | {
+    kind: 'stale-error';
+    data: T;
+    requestedInput: Input;
+    displayedInput: Input;
+    error: Error;
+    message: string;
+};
+export type DataSnapshot<Data, Input> = {
+    data: Data;
+    input: Input;
+};
+export type DisplayedSnapshot<Data, Input> = DataSnapshot<Data, Input> & {
+    state: 'ready' | 'updating' | 'stale-error';
+};
+/** The result currently shown to the reader, including the input that produced it. */
+export declare function displayedSnapshot<Data, Input>(view: DataView<Data, Input>): DisplayedSnapshot<Data, Input> | undefined;
+/** Keep the requested input separate from the input that produced visible data. */
+export declare function resolveDataView<Data, Input>({ requestedInput, current, previous, pending, error, sameInput, describe, isEmpty, }: {
+    requestedInput: Input;
+    current?: DataSnapshot<Data, Input>;
+    previous?: DataSnapshot<Data, Input>;
+    pending: boolean;
+    error?: Error;
+    sameInput: (a: Input, b: Input) => boolean;
+    describe: (input: Input) => string;
+    isEmpty: (data: Data) => boolean;
+}): DataView<Data, Input>;

package/dist/types/core/date-range.d.ts

@@ -0,0 +1,20 @@
+/** ISO calendar dates; the app operation defines timezone and inclusive bounds. */
+export type DateRange = {
+    start: string;
+    end: string;
+};
+export type DatePresetId = 'day' | 'last-3' | 'last-7' | 'last-14' | 'last-30' | 'last-90' | 'this-week' | 'previous-week' | 'this-month' | 'previous-month';
+export type DatePreset = {
+    id: DatePresetId;
+    label: string;
+    range: DateRange;
+};
+export declare function inclusiveDays(range: DateRange): number;
+export declare function withinBounds(range: DateRange, minDate?: string, maxDate?: string, maxRangeDays?: number): boolean;
+/** Only offer ranges the app says it can query. Dates and range lengths are inclusive. */
+export declare function availableDatePresets({ minDate, maxDate, maxRangeDays, timeZone, }: {
+    minDate?: string;
+    maxDate?: string;
+    maxRangeDays?: number;
+    timeZone?: string;
+}): DatePreset[];

package/dist/types/core/dimension.d.ts

@@ -0,0 +1,60 @@
+import type { AppVariable, HistoryMode } from './variables.js';
+export type DimensionValue = string | number;
+export type DimensionMember<T extends DimensionValue = DimensionValue> = {
+    kind: 'value';
+    value: T;
+} | {
+    kind: 'missing';
+};
+export type DimensionSelection<T extends DimensionValue = DimensionValue> = {
+    kind: 'all';
+} | {
+    kind: 'include';
+    members: readonly DimensionMember<T>[];
+};
+export type DimensionOption<T extends DimensionValue = DimensionValue> = {
+    value: T;
+    label: string;
+    count?: number;
+};
+export type DimensionVariable<T extends DimensionValue = DimensionValue> = Omit<AppVariable<DimensionSelection<T>, 'dimension'>, 'options'> & {
+    label: string;
+    selection: 'single' | 'multiple';
+    valueType: 'string' | 'number';
+    allowMissing: boolean;
+    maxSelected: number;
+    options: readonly DimensionOption<T>[];
+    facet?: {
+        operation: string;
+        input: (values: Record<string, unknown>) => unknown;
+    };
+    describe: (selection: DimensionSelection<T>) => string;
+};
+export declare function dimensionMemberKey(member: DimensionMember): string;
+export type DimensionFilterOptions<T extends DimensionValue> = {
+    key: string;
+    label: string;
+    valueType: T extends number ? 'number' : 'string';
+    selection: 'single' | 'multiple';
+    allowMissing?: boolean;
+    maxSelected?: number;
+    history?: HistoryMode;
+} & ({
+    options: readonly DimensionOption<T>[];
+    facet?: never;
+} | {
+    /** A bounded operation supplies options and counts; input chooses other filters affecting counts. */
+    facet: {
+        operation: string;
+        input: (values: Record<string, unknown>) => unknown;
+    };
+    options?: never;
+});
+/** A bounded categorical filter. URL tags distinguish missing from literal "null". */
+export declare function dimensionFilter<const T extends DimensionValue>(config: DimensionFilterOptions<T>): DimensionVariable<T>;
+/** Server-side parser; call from the operation input parser before building SQL. */
+export declare function parseDimensionSelection<T extends DimensionValue>(value: unknown, filter: DimensionVariable<T>): DimensionSelection<T>;
+/** Validate bounded facet results before showing them in a picker. */
+export declare function parseFacetOptions<T extends DimensionValue>(value: unknown, filter: DimensionVariable<T>): DimensionOption<T>[];
+/** Central SQL literal encoding for transports without bound parameters. Column is an allowlisted identifier. */
+export declare function dimensionPredicate<T extends DimensionValue, const Columns extends readonly string[]>(column: Columns[number], selection: DimensionSelection<T>, allowedColumns: Columns): string;

package/dist/types/core/format.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Date and number formatting with explicit units and missing-value behavior.
+ * @module @altertable/data-app/format
+ * @see https://github.com/altertable-ai/data-app/blob/main/docs/format.md
+ */
+type CommonOptions = {
+    locale?: string;
+    missing?: string;
+};
+/** Compact, unambiguous calendar dates for labels and request status. */
+export declare function formatDateRange({ start, end, }: {
+    start: string;
+    end: string;
+}): string;
+export type MetricFormat = {
+    kind: 'count';
+    compact?: boolean;
+    locale?: string;
+} | {
+    kind: 'ratio';
+    maximumFractionDigits?: number;
+    locale?: string;
+} | {
+    kind: 'currency';
+    currency: string;
+    locale?: string;
+};
+export declare function formatMetric(value: number, format: MetricFormat): string;
+/** Missing and non-finite values use the `missing` label; negative zero renders as zero. */
+export declare function formatNumber(value: number | null | undefined, options?: CommonOptions & Intl.NumberFormatOptions): string;
+/** Negative and fractional counts render as missing. Compact notation is opt-in. */
+export declare function formatCount(value: number | null | undefined, options?: CommonOptions & {
+    compact?: boolean;
+}): string;
+export declare function pluralize(count: number, singular: string, plural?: string): string;
+/** Accepts a ratio (0.116), not a percentage (11.6). */
+export declare function formatPercent(ratio: number | null | undefined, options?: CommonOptions & {
+    maximumFractionDigits?: number;
+}): string;
+export {};

package/dist/types/core/invariant.d.ts

@@ -0,0 +1,2 @@
+/** Assert an author or data contract while preserving a useful failure message. */
+export declare function invariant(condition: unknown, message: string): asserts condition;

package/dist/types/core/messages.d.ts

@@ -0,0 +1,77 @@
+import type { TransportResponse } from './bridge.js';
+import type { DisclosedQuery } from './contract.js';
+export type MessageContext = {
+    signal: AbortSignal;
+};
+export type RoutedMessage = {
+    route: string;
+    payload: unknown;
+};
+export type MessageDispatcher = (message: unknown, context: MessageContext) => Promise<unknown>;
+export type MessageTransport = (message: RoutedMessage, signal?: AbortSignal) => Promise<unknown>;
+export type MessageRoute<Input, Output> = {
+    input: (value: unknown) => Input;
+    output: (value: unknown, input: Input) => Output;
+};
+export type MessageRoutes = Record<string, {
+    input: (value: unknown) => unknown;
+    output: (value: unknown, input: never) => unknown;
+}>;
+export type MessageInput<Route extends MessageRoutes[string]> = ReturnType<Route['input']>;
+export type MessageHandlers<Routes extends MessageRoutes> = {
+    [Name in keyof Routes]: (payload: MessageInput<Routes[Name]>, context: MessageContext) => ReturnType<Routes[Name]['output']> | Promise<ReturnType<Routes[Name]['output']>>;
+};
+declare const errorBrand: unique symbol;
+/** Only these deliberate, public failures cross the message boundary. Other errors stay private. */
+export declare class MessageRoutingError extends Error {
+    readonly code: string;
+    readonly requestId?: string | undefined;
+    readonly [errorBrand] = true;
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(code: string, message: string, requestId?: string | undefined);
+}
+export declare function defineMessageRoute<Input, Output>(route: MessageRoute<Input, Output>): MessageRoute<Input, Output>;
+/** Contracts are shared; handlers are supplied by the host and never belong in the app bundle. */
+export declare function createMessageRouter<const Routes extends MessageRoutes>(routes: Routes, handlers: MessageHandlers<NoInfer<Routes>>): {
+    dispatch: (value: unknown, context: MessageContext) => Promise<unknown>;
+};
+export type OperationContracts = Record<string, {
+    input: (value: unknown) => unknown;
+    output: (value: unknown) => unknown;
+}>;
+export type DataQueryInput<Operations extends OperationContracts> = {
+    [Name in keyof Operations & string]: {
+        operation: Name;
+        input: ReturnType<Operations[Name]['input']>;
+    };
+}[keyof Operations & string];
+export type DataQueryBody<Output> = {
+    data: Output;
+    requestId: string;
+    queriedAt: string;
+    queryIds: string[];
+    queries?: DisclosedQuery[];
+};
+export type DataQueryRoute<Operations extends OperationContracts> = MessageRoute<DataQueryInput<Operations>, TransportResponse> & {
+    operations: Operations | undefined;
+};
+export type MessageOutput<Route extends MessageRoutes[string], Input> = Route extends DataQueryRoute<infer Operations> ? Input extends {
+    operation: infer Name extends keyof Operations;
+} ? {
+    status: number;
+    body: DataQueryBody<ReturnType<Operations[Name]['output']>>;
+} : never : ReturnType<Route['output']>;
+/** Omit contracts only in generic hosts such as the CLI shell, where Bun validates operations. */
+export declare function defineDataQueryRoute<Operations extends OperationContracts = OperationContracts>(operations?: Operations): DataQueryRoute<Operations>;
+export type NavigationUpdate = {
+    search: string;
+    hash: string;
+    mode: 'push' | 'replace';
+    title?: string;
+};
+export declare const navigationUpdateRoute: MessageRoute<NavigationUpdate, null>;
+export declare const dataAppRoutes: {
+    'data.query': DataQueryRoute<OperationContracts>;
+    'navigation.update': MessageRoute<NavigationUpdate, null>;
+};
+export {};

package/dist/types/core/reading.d.ts

@@ -0,0 +1,17 @@
+import type { DateRangeRequest } from './contract.js';
+export type DataReading<Value> = {
+    loading: true;
+    value?: never;
+} | {
+    loading: false;
+    value: Value;
+};
+/** Zero is measured data. null or omitted means no previous measurement.
+ * Comparison activation belongs to the reading's period, not these values. */
+export type MetricValues = {
+    current: number;
+    previous?: number | null;
+};
+export type MetricReading = DataReading<MetricValues & {
+    period?: DateRangeRequest;
+}>;

package/dist/types/core/variables.d.ts

@@ -0,0 +1,82 @@
+import { type DatePresetId, type DateRange } from './date-range.js';
+import type { DateRangeContract, DateRangeRequest } from './contract.js';
+import type { DimensionSelection, DimensionVariable } from './dimension.js';
+export type HistoryMode = 'push' | 'replace';
+/** An app-owned value with one URL representation. Controls never parse or write routes. */
+export type AppVariable<Value, Kind extends string = Value extends string ? 'text' | 'select' : 'dateRange'> = {
+    kind: Kind;
+    label?: string;
+    options?: readonly {
+        id: string;
+        label: string;
+    }[];
+    urlKeys: readonly string[];
+    defaultValue: Value;
+    history: HistoryMode;
+    read: (params: URLSearchParams) => Value;
+    write: (value: Value) => Record<string, string | null>;
+    valid: (value: Value) => boolean;
+    same: (left: Value, right: Value) => boolean;
+};
+export type VariableCollection = Record<string, AppVariable<string> | DateRangeVariable | DimensionVariable<any>>;
+export type AppVariableValues<Variables> = {
+    [Key in keyof Variables]: Variables[Key] extends DimensionVariable<infer Value> ? DimensionSelection<Value> : Variables[Key] extends AppVariable<infer Value, string> ? Value : never;
+};
+/** Name variables once in the app. URL keys must be unique across its controls. */
+export declare function defineAppVariables<const Variables extends VariableCollection>(variables: Variables): Variables;
+type ScalarVariableOptions = {
+    label?: string;
+    key: string;
+    defaultValue?: string;
+    history?: HistoryMode;
+};
+/** A local text filter. Typing replaces the current history entry by default. */
+export declare function textVariable({ key, label, defaultValue, history, }: ScalarVariableOptions): AppVariable<string>;
+/** A single choice. Supply values when the option set is known before data loads. */
+export declare function selectVariable({ key, label, defaultValue, values, history, }: ScalarVariableOptions & {
+    defaultValue: string;
+    values?: readonly string[];
+}): AppVariable<string>;
+export type DateRangeSelection = {
+    kind: 'preset';
+    id: DatePresetId;
+    comparison?: 'previous';
+} | {
+    kind: 'dates';
+    start: string;
+    end: string;
+    comparison?: 'previous';
+};
+export type DateRangeVariableOptions = {
+    label?: string;
+    /** URL key for a relative preset; explicit dates use startKey and endKey. */
+    key: string;
+    startKey?: string;
+    endKey?: string;
+    defaultValue: DateRangeSelection & {
+        comparison?: never;
+    };
+    contract: DateRangeContract;
+    history?: HistoryMode;
+    /** Opt into a URL-backed comparison with the preceding equal-length range. */
+    comparison?: boolean;
+    comparisonKey?: string;
+};
+export type DateRangeVariable = AppVariable<DateRangeSelection> & {
+    kind: 'dateRange';
+    supportsComparison: boolean;
+    input: (selection: DateRangeSelection) => DateRangeRequest;
+    describeInput: (input: DateRangeRequest) => string;
+    bounds: () => {
+        minDate?: string;
+        maxDate: string;
+        maxRangeDays: number;
+        timeZone: string;
+    };
+    resolve: (selection: DateRangeSelection) => DateRange;
+    previous: (selection: DateRangeSelection) => DateRange | null;
+    comparisonRange: (selection: DateRangeSelection) => DateRange | null;
+};
+/** A date variable keeps relative presets relative and validates exact dates against source coverage. */
+export declare function dateRangeVariable({ key, label, startKey, endKey, defaultValue, contract, history, comparison, comparisonKey, }: DateRangeVariableOptions): DateRangeVariable;
+export {};

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

@@ -0,0 +1,5 @@
+/** Run from a trusted bootstrap page in an allow-scripts-only iframe. CSP can prohibit network access. */
+export declare function startDataAppBootstrap({ parentOrigin, window: frame, }: {
+    parentOrigin: string;
+    window?: Window;
+}): () => void;

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

@@ -0,0 +1,23 @@
+import { type MessageDispatcher } from '../core/messages.js';
+export type DataAppConnection = {
+    type: 'origin';
+    origin: string;
+} | {
+    type: 'opaque';
+    token: string;
+};
+export type DataAppStatus = 'connecting' | 'connected' | 'ready' | 'failed' | 'disconnected';
+export type DataAppDiagnostic = {
+    direction: 'send' | 'receive';
+    type: string;
+};
+/** The bridge owns delivery and cancellation; the routed handler owns validation, authorization and execution. */
+export declare function attachDataAppBridge({ iframe, connection, javascript, onStatusChange, onDiagnostic, onMessage, window: host, }: {
+    iframe: HTMLIFrameElement;
+    connection: DataAppConnection;
+    javascript?: string;
+    onStatusChange?: (status: DataAppStatus) => void;
+    onDiagnostic?: (event: DataAppDiagnostic) => void;
+    onMessage: MessageDispatcher;
+    window?: Window;
+}): () => void;

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

@@ -0,0 +1,11 @@
+/**
+ * Framework-neutral iframe hosting and sandboxed bundle initialization.
+ * @module @altertable/data-app/embed
+ * @see https://github.com/altertable-ai/data-app/blob/main/docs/embed.md
+ */
+export { attachDataAppBridge } from './host.js';
+export type { DataAppConnection, DataAppStatus, DataAppDiagnostic, } from './host.js';
+export { attachDataAppShell } from './shell.js';
+export type { DataAppSource, DataAppShellOptions } from './shell.js';
+export { startDataAppBootstrap } from './bootstrap.js';
+export { createNavigationHandler } from './navigation.js';

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

@@ -0,0 +1,6 @@
+import type { NavigationUpdate } from '../core/messages.js';
+/** Override this handler for framework routers. Reserved host parameters survive app navigation. */
+export declare function createNavigationHandler({ window: host, reservedSearchParams, }?: {
+    window?: Window;
+    reservedSearchParams?: readonly string[];
+}): (input: NavigationUpdate) => null;

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

@@ -0,0 +1,21 @@
+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

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

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

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import type { DataReading, MetricReading, MetricValues } from '../core/reading.js';
+import type { DateRangeRequest } from '../core/contract.js';
+export type DataContentHelpers<Data> = {
+    select: <Value>(select: (data: Data) => Value) => DataReading<Value>;
+    metric: (select: (data: Data) => MetricValues) => MetricReading;
+};
+export type DataContentState<Data, Input> = DataContentHelpers<Data> & ({
+    loading: true;
+    data?: never;
+    input?: never;
+} | {
+    loading: false;
+    data: Data;
+    input: Input;
+});
+/** Selectors run only for displayed data. Date comparisons inherit that result's input. */
+export declare function defineDataContent<Data, Input>(render: (state: DataContentState<Data, Input>) => ReactNode, options?: {
+    date?: (input: Input) => DateRangeRequest;
+}): {
+    loading: ReactNode;
+    children(data: Data, input: Input): ReactNode;
+};

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

@@ -0,0 +1,12 @@
+import { type ComponentRef } from 'react';
+import { type DataAppConnection, type DataAppStatus, type DataAppDiagnostic } from '../../embed/host.js';
+import type { MessageDispatcher } from '../../core/messages.js';
+export type DataAppBridgeProps = {
+    iframe: ComponentRef<'iframe'> | null;
+    connection: DataAppConnection;
+    onMessage: MessageDispatcher;
+    onStatusChange?: (status: DataAppStatus) => void;
+    onDiagnostic?: (event: DataAppDiagnostic) => void;
+};
+/** Delivery only; the host owns the iframe and route handlers, including navigation. */
+export declare function DataAppBridge({ iframe, connection, onMessage, onStatusChange, onDiagnostic, }: DataAppBridgeProps): null;

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

@@ -0,0 +1,9 @@
+/**
+ * React iframe hosts; independent of the app UI and its stylesheet.
+ * @module @altertable/data-app/react/embed
+ * @see https://github.com/altertable-ai/data-app/blob/main/docs/react-embed.md
+ */
+export { DataAppBridge } from './bridge.js';
+export type { DataAppBridgeProps } from './bridge.js';
+export { DataAppShell } from './shell.js';
+export type { DataAppShellProps } from './shell.js';

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

@@ -0,0 +1,10 @@
+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;