@altertable/data-app 0.59.1 → 0.62.0

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

@@ -1,13 +1,5 @@
-/**
- * Typed clients for HTTP and iframe delivery; safe to import in the browser.
- * @module @altertable/data-app/client
- * @see https://github.com/altertable-ai/data-app/blob/main/docs/client.md
- */
-import { type DataTransport } from './transport.js';
-export { createHttpTransport, DataAppError, type DataTransport, } from './transport.js';
-export { createIframeTransport, installDataAppTransport, getDataAppTransport, type IframeTransport, } from './iframe.js';
-export { createMessageClient } from './messages.js';
-import type { DataOperations, DisclosedQuery } from '../core/contract.js';
+import type { DataOperations, DisclosedQuery, Lakehouse } from '../core/contract.js';
+import type { DataTransport } from './transport.js';
 export type InputOf<T> = T extends {
     input: (value: unknown) => infer Input;
 } ? Input : never;
@@ -32,11 +24,25 @@ export type DataClient<Operations extends DataOperations> = {
         signal?: AbortSignal;
     }): Promise<DataResponse<OutputOf<Operations[Name]>, InputOf<Operations[Name]>>>;
 };
-/** Browser client for named operations; it sends inputs, never SQL or lakehouse credentials. */
-export declare function createDataClient<Operations extends DataOperations>(options?: {
+/** Browser operations and named-operation delivery are mutually exclusive configurations. */
+export type DataClientOptions<Operations extends DataOperations> = {
+    operations: Operations;
+    lakehouse?: Lakehouse;
+    transport?: never;
+    endpoint?: never;
+    fetch?: never;
+} | {
+    operations?: never;
+    lakehouse?: never;
     transport?: DataTransport;
     endpoint?: string;
     fetch?: typeof fetch;
-}): DataClient<Operations>;
+};
+/** Named HTTP operations, or browser-owned operations executed through an authorized SQL bridge. */
+export declare function createDataClient<Operations extends DataOperations>(options?: DataClientOptions<Operations>): DataClient<Operations>;
 export type { DataAppLocation, AppLocation } from './location.js';
 export { createDataAppNavigation, getDataAppNavigation, type DataAppNavigation, } from './navigation.js';
+export { createHttpTransport, DataAppError, type DataTransport, } from './transport.js';
+export { createIframeTransport, installDataAppTransport, getDataAppTransport, type IframeTransport, } from './iframe.js';
+export { createMessageClient } from './messages.js';
+export type { DataAppPresentation } from '../core/presentation.js';

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

@@ -1,5 +1,7 @@
+export type Theme = 'light' | 'dark';
+export type ThemePreference = Theme | 'system';
 export type AppearanceSettings = {
-    mode: 'light' | 'dark' | 'system';
+    theme: ThemePreference;
     baseColor: 'neutral' | 'slate' | 'warm';
     accentColor: string;
     darkAccentColor?: string;
@@ -12,10 +14,9 @@ export type AppearanceSettings = {
         heading: string;
     };
 };
-export type ThemeMode = AppearanceSettings['mode'];
 export type ThemeController = {
-    getMode: () => ThemeMode;
-    setMode: (mode: ThemeMode) => void;
+    getTheme: () => ThemePreference;
+    setTheme: (theme: ThemePreference) => void;
     subscribe: (listener: () => void) => () => void;
 };
 export declare function parseAppearance(value: unknown): AppearanceSettings;
@@ -24,5 +25,5 @@ export declare function parseAppearance(value: unknown): AppearanceSettings;
  * system-theme listening.
  */
 export declare function applyAppearance(value: unknown): () => void;
-/** Viewer color mode persists independently of app-authored brand tokens. */
-export declare function createThemeController(value: unknown): ThemeController;
+/** Persist a viewer theme preference. Applying appearance belongs to the UI owner. */
+export declare function createThemeController(initialTheme?: ThemePreference): ThemeController;

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

@@ -80,7 +80,7 @@ export declare class DataSourceError extends Error {
     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. */
+/** Query interface supplied by a server adapter or an authorized iframe bridge. */
 export type Lakehouse = {
     queryAll(statement: string, options: {
         limit: number;
@@ -93,8 +93,8 @@ export type OperationContext = {
     signal: AbortSignal;
 };
 /**
- * Both parsers run on the server before results cross the JSON boundary. Schema libraries can be
- * used inside either parser.
+ * Parsers run in the operation executor's runtime: server for HTTP apps, browser for bundle apps.
+ * Browser validation does not replace backend authorization or query limits.
  */
 export type DataOperation<Input, Output> = {
     input: (value: unknown) => Input;

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

@@ -1,5 +1,5 @@
 import type { TransportResponse } from './bridge.js';
-import type { DisclosedQuery } from './contract.js';
+import type { DisclosedQuery, QueryResult } from './contract.js';
 export type MessageContext = {
     signal: AbortSignal;
 };
@@ -70,8 +70,14 @@ export type NavigationUpdate = {
     title?: string;
 };
 export declare const navigationUpdateRoute: MessageRoute<NavigationUpdate, null>;
+export type SqlQueryInput = {
+    statement: string;
+    limit: number;
+};
+/** SQL delivery for browser-owned operations. Hosts must enforce backend access and resource limits. */
+export declare const sqlQueryRoute: MessageRoute<SqlQueryInput, QueryResult>;
 export declare const dataAppRoutes: {
-    'data.query': DataQueryRoute<OperationContracts>;
-    'navigation.update': MessageRoute<NavigationUpdate, null>;
+    'data:query': DataQueryRoute<OperationContracts>;
+    'navigation:update': MessageRoute<NavigationUpdate, null>;
 };
 export {};

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

@@ -0,0 +1,27 @@
+import { type DataOperations, type DisclosedQuery, type Lakehouse } from './contract.js';
+type Operation = DataOperations[string];
+type OperationExecutionOptions = {
+    operationName: string;
+    lakehouse: Lakehouse;
+    signal: AbortSignal;
+    /** Include query evidence in the response; this does not keep browser-owned SQL private. */
+    includeSql: boolean;
+    requestId: string;
+};
+/** Shared operation execution. Adapters own authorization, delivery, and public errors. */
+export declare function executeDataOperation(operation: Operation, value: unknown, { operationName, lakehouse, signal: requestSignal, includeSql, requestId, }: OperationExecutionOptions): Promise<{
+    body: {
+        data: unknown;
+        requestId: string;
+        queriedAt: string;
+        queryIds: string[];
+        queries?: DisclosedQuery[] | undefined;
+    };
+    serializedBody: string;
+}>;
+export declare function toDataOperationFailure(error: unknown, aborted?: boolean): {
+    status: number;
+    code: string;
+    message: string;
+};
+export {};

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

@@ -0,0 +1,7 @@
+import type { Theme } from './appearance.js';
+/** Presentation owned by the parent shell, delivered only over a trusted bridge. */
+export type DataAppPresentation = {
+    surface: 'embedded' | 'standalone';
+    theme: Theme;
+};
+export declare function isDataAppPresentation(value: unknown): value is DataAppPresentation;

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

@@ -0,0 +1,12 @@
+import { type DataAppConnectionOptions } from './host.js';
+import { type DataAppSourceOptions } from './source.js';
+export type DataAppBridgeOptions = (DataAppSourceOptions & {
+    connection?: never;
+    window?: never;
+    javascript?: never;
+}) | (DataAppConnectionOptions & {
+    source?: never;
+    startupTimeoutMs?: never;
+});
+/** Source mode configures and loads the iframe; connection mode attaches to a host-owned document. */
+export declare function attachDataAppBridge(options: DataAppBridgeOptions): import("./host.js").DataAppHost;

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

@@ -1,3 +1,4 @@
+import type { DataAppPresentation } from '../core/presentation.js';
 import { type MessageDispatcher } from '../core/messages.js';
 export type DataAppConnection = {
     type: 'origin';
@@ -11,13 +12,19 @@ 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, }: {
+export type DataAppHost = {
+    dispose: () => void;
+    setPresentation: (presentation?: DataAppPresentation) => void;
+};
+export type DataAppConnectionOptions = {
     iframe: HTMLIFrameElement;
     connection: DataAppConnection;
     javascript?: string;
+    presentation?: DataAppPresentation;
     onStatusChange?: (status: DataAppStatus) => void;
     onDiagnostic?: (event: DataAppDiagnostic) => void;
     onMessage: MessageDispatcher;
     window?: Window;
-}): () => void;
+};
+/** The bridge owns delivery and cancellation; the routed handler owns validation, authorization and execution. */
+export declare function attachDataAppConnection({ iframe, connection, javascript, presentation, onStatusChange, onDiagnostic, onMessage, window: host, }: DataAppConnectionOptions): DataAppHost;

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

@@ -3,9 +3,12 @@
  * @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 { attachDataAppBridge } from './bridge.js';
+export type { DataAppBridgeOptions } from './bridge.js';
+export type { DataAppHost, DataAppConnection, DataAppStatus, DataAppDiagnostic, } from './host.js';
+export type { DataAppSource } from './source.js';
 export { startDataAppBootstrap } from './bootstrap.js';
 export { createNavigationHandler } from './navigation.js';
+export { sqlQueryRoute, type SqlQueryInput } from '../core/messages.js';
+export { createSqlQueryHandler } from './sql.js';
+export type { DataAppPresentation } from '../core/presentation.js';

package/dist/types/embed/{shell.d.ts → source.d.ts}

@@ -1,5 +1,6 @@
+import type { DataAppPresentation } from '../core/presentation.js';
 import type { MessageDispatcher } from '../core/messages.js';
-import { type DataAppStatus, type DataAppDiagnostic } from './host.js';
+import { type DataAppStatus, type DataAppHost, type DataAppDiagnostic } from './host.js';
 export type DataAppSource = {
     type: 'url';
     url: string;
@@ -7,15 +8,15 @@ export type DataAppSource = {
     type: 'bundle';
     bootstrapUrl: string;
     javascript: string;
-    revision: string;
 };
-export type DataAppShellOptions = {
+export type DataAppSourceOptions = {
     iframe: HTMLIFrameElement;
     source: DataAppSource;
+    presentation?: DataAppPresentation;
     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;
+export declare function attachDataAppSource({ iframe, source, presentation, onMessage, onStatusChange, onDiagnostic, startupTimeoutMs, }: DataAppSourceOptions): DataAppHost;

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

@@ -0,0 +1,4 @@
+import type { Lakehouse } from '../core/contract.js';
+import { type MessageContext, type SqlQueryInput } from '../core/messages.js';
+/** Authorize every SQL request and supply a backend that independently enforces access and query limits. */
+export declare function createSqlQueryHandler(authorize: (query: SqlQueryInput, context: MessageContext) => Promise<Lakehouse>): (input: SqlQueryInput, context: MessageContext) => Promise<import("../core/contract.js").QueryResult>;

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

@@ -1,12 +1,21 @@
-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 = {
+import { type ComponentRef, type ComponentPropsWithoutRef } from 'react';
+import { type DataAppBridgeOptions } from '../../embed/bridge.js';
+import type { DataAppConnection } from '../../embed/host.js';
+import type { DataAppSource } from '../../embed/source.js';
+export type DataAppBridgeProps = Pick<DataAppBridgeOptions, 'onMessage' | 'onStatusChange' | 'onDiagnostic' | 'presentation'> & ({
+    source: DataAppSource;
+    title: string;
+    startupTimeoutMs?: number;
+    iframeProps?: Omit<ComponentPropsWithoutRef<'iframe'>, 'src' | 'srcDoc' | 'sandbox' | 'referrerPolicy' | 'loading' | 'children' | 'title'>;
+    iframe?: never;
+    connection?: never;
+} | {
     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;
+    source?: never;
+    title?: never;
+    startupTimeoutMs?: never;
+    iframeProps?: never;
+});
+/** Owns iframe setup and delivery. The consuming shell owns loading, error UI, and retries. */
+export declare function DataAppBridge(props: DataAppBridgeProps): import("react").JSX.Element;

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

@@ -5,5 +5,3 @@
  */
 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/ui/DataAppSkeleton.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+
+export type DataAppSkeletonProps = Omit<ComponentPropsWithRef<'output'>, 'children' | 'role' | 'aria-busy'> & {
+    header?: ReactNode;
+    footer?: ReactNode;
+};
+/** Host-side placeholder while a data app starts. Header and footer slots remain host-owned; widget placeholders are decorative. */
+export declare function DataAppSkeleton({ header, footer, className, ...props }: DataAppSkeletonProps): import("react").JSX.Element;

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

@@ -1,7 +1,7 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react';
 
 /** One search control surface for picker search and table/page search. */
-export declare function SearchInput({ size, endAction, loading, className, ...props }: Omit<ComponentPropsWithRef<'input'>, 'size' | 'children'> & {
+export declare function SearchInput({ size, endAction, loading, className, onKeyDown, ...props }: Omit<ComponentPropsWithRef<'input'>, 'size' | 'children'> & {
     size?: 'default' | 'compact';
     endAction?: ReactNode;
     /** Replaces the search glyph in its existing space; input and results remain usable. */

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

@@ -56,6 +56,8 @@ 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';

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

@@ -0,0 +1,3 @@
+import { type Theme } from '../../core/appearance.js';
+/** The parent theme takes precedence; only standalone viewers receive controls. */
+export declare function useAppAppearance(appearance: unknown, hostTheme?: Theme): import("../../core/appearance.js").ThemeController | undefined;

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

@@ -0,0 +1,3 @@
+import { type DataAppPresentation } from '../../core/presentation.js';
+/** Local preview verifies its parent before accepting presentation context. */
+export declare function useDataAppPresentation(): DataAppPresentation | undefined;

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

@@ -2,7 +2,7 @@ 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>): {
+export declare function useViewVariables<Variables extends VariableCollection>(definitions: Variables, clientScope: string, 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;