@altertable/data-app 0.63.0 → 0.65.0

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

@@ -8,6 +8,7 @@ export declare function createIframeTransport({ parentOrigin, window: frame, tim
     mode?: 'url' | 'bundle';
     loadScript?: (javascript: string) => void;
 }): {
+    logger: import(".").DataAppLogger;
     request: (message: RoutedMessage, signal?: AbortSignal) => Promise<unknown>;
     transport: (operation: string, input: unknown, signal?: AbortSignal) => Promise<TransportResponse>;
     lakehouse: {
@@ -34,6 +35,7 @@ export declare function localFrameBridge(window?: Window): LocalBridge | undefin
 export declare function installDataAppTransport(bridge: ReturnType<typeof createIframeTransport>, frame?: Window): () => void;
 /** The bootstrap installs this before executing app code. URL apps can install an explicit connection. */
 export declare function getDataAppTransport(frame?: Window): {
+    logger: import(".").DataAppLogger;
     request: (message: RoutedMessage, signal?: AbortSignal) => Promise<unknown>;
     transport: (operation: string, input: unknown, signal?: AbortSignal) => Promise<TransportResponse>;
     lakehouse: {

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

@@ -10,3 +10,4 @@ export { createDataAppNavigation, getDataAppNavigation, type DataAppNavigation,
 export { createHttpTransport, DataAppError, type DataTransport, } from './transport.js';
 export { createIframeTransport, installDataAppTransport, getDataAppTransport, type IframeTransport, } from './iframe.js';
 export { createMessageClient } from './messages.js';
+export type { DataAppLogger } from '../core/logger.js';

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

@@ -0,0 +1,6 @@
+import type { BridgeMessage } from '../core/bridge.js';
+import { type DataAppLogger, type LogEntry } from '../core/logger.js';
+/** Lazy arguments run in the iframe; only resolved values cross the bridge. */
+export declare function createBridgeLogger(enabled: () => boolean, send: (entry: LogEntry) => void): DataAppLogger;
+/** Log only delivery metadata; payloads and session credentials stay private. */
+export declare function logBridgeMessage(logger: DataAppLogger, message: BridgeMessage): void;

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

@@ -1,3 +1,7 @@
+/**
+ * Brand settings; parsing is portable, while theme application requires the browser.
+ * @module @altertable/data-app/appearance
+ */
 export type Theme = 'light' | 'dark';
 export type ThemePreference = Theme | 'system';
 export type AppearanceSettings = {
@@ -14,16 +18,23 @@ export type AppearanceSettings = {
         heading: string;
     };
 };
+/** App-authored overrides; omitted fields use the package defaults. */
+export type AppearanceOptions = Partial<Omit<AppearanceSettings, 'typography'>> & {
+    typography?: Partial<AppearanceSettings['typography']>;
+};
 export type ThemeController = {
     getTheme: () => ThemePreference;
     setTheme: (theme: ThemePreference) => void;
     subscribe: (listener: () => void) => () => void;
 };
+/** Preserve supported external settings and use defaults for invalid fields. */
 export declare function parseAppearance(value: unknown): AppearanceSettings;
+/** Resolve typed app settings without repeating authoring checks at runtime. */
+export declare function normalizeAppearance(value?: AppearanceOptions): AppearanceSettings;
 /**
  * Install semantic tokens on the document root, including portaled UI. Returns a cleanup for
  * system-theme listening.
  */
-export declare function applyAppearance(value: unknown): () => void;
+export declare function applyAppearance(value?: AppearanceOptions): () => void;
 /** Persist a viewer theme preference. Applying appearance belongs to the UI owner. */
 export declare function createThemeController(initialTheme?: ThemePreference): ThemeController;

package/dist/types/core/bridge-endpoint.d.ts

@@ -0,0 +1,21 @@
+import { type BridgeMessage, type BridgeRole, type BridgeEventsFrom, type BridgePayload, type BridgeEnvelope, type BridgeHandlers } from './bridge.js';
+type ConnectionContext = Pick<BridgeEnvelope, 'sessionId' | 'token'> & {
+    documentId?: string;
+};
+/** The connection owns IDs and token rotation; callers can only supply event payloads. */
+export declare function createBridgeEndpoint<const Role extends BridgeRole>({ role, origin, source, opaque, context, post, diagnostic, invalidRequest, handlers, }: {
+    role: Role;
+    handlers: BridgeHandlers<NoInfer<Role>>;
+    origin: string;
+    source: () => MessageEventSource | null;
+    opaque: boolean;
+    context: () => ConnectionContext;
+    post: (message: BridgeMessage) => void;
+    diagnostic?: (direction: 'send' | 'receive', type: BridgeMessage['type']) => void;
+    invalidRequest?: (id: string) => void;
+}): {
+    send: <Name extends BridgeEventsFrom<Role>, const Payload extends BridgePayload<NoInfer<Name>>>(name: Name, payload: Payload & Record<Exclude<keyof Payload, keyof BridgePayload<NoInfer<Name>>>, never>) => void;
+    receive: (event: MessageEvent) => void;
+    dispose(): void;
+};
+export {};

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

@@ -6,24 +6,145 @@ export declare const PARENT_PARAM = "__altertable_parent";
 export declare const MAX_PENDING = 128;
 export declare const REQUEST_TIMEOUT_MS = 60000;
 export type { TransportResponse } from './operation-types.js';
-export type BridgeMessage = {
+export declare function validId(value: unknown): value is string;
+type Fields = Record<string, unknown>;
+export type BridgeRole = 'host' | 'app';
+/** Parsers project known fields; opaque values are validated by their owning route or adapter. */
+export declare const bridgeProtocol: {
+    readonly channel: "altertable:data-app";
+    readonly version: 1;
+    readonly events: {
+        readonly connect: {
+            wire: "bridge:connect";
+            from: "host";
+            session: "none";
+            parse: (fields: Fields) => {};
+        };
+        readonly ready: {
+            wire: "bridge:ready";
+            from: "app";
+            session: "none";
+            parse: (fields: Fields) => {};
+        };
+        readonly initialize: {
+            wire: "bridge:initialize";
+            from: "host";
+            session: "establish";
+            parse: (fields: Fields) => {
+                state: unknown;
+            };
+        };
+        readonly request: {
+            wire: "bridge:request";
+            from: "app";
+            session: "current";
+            parse: (fields: Fields) => {
+                id: string;
+                route: string;
+                payload: unknown;
+            };
+        };
+        readonly result: {
+            wire: "bridge:result";
+            from: "host";
+            session: "current";
+            parse: (fields: Fields) => {
+                id: string;
+                response: unknown;
+            };
+        };
+        readonly error: {
+            wire: "bridge:error";
+            from: "host";
+            session: "current";
+            parse: (fields: Fields) => {
+                id: string;
+                code: string;
+                message: string;
+                requestId?: string | undefined;
+            };
+        };
+        readonly cancel: {
+            wire: "bridge:cancel";
+            from: "app";
+            session: "current";
+            parse: (fields: Fields) => {
+                id: string;
+            };
+        };
+        readonly disconnect: {
+            wire: "bridge:disconnect";
+            from: "app";
+            session: "current";
+            parse: (fields: Fields) => {};
+        };
+        readonly scriptLoad: {
+            wire: "script:load";
+            from: "host";
+            session: "current";
+            parse: (fields: Fields) => {
+                javascript: string;
+            };
+        };
+        readonly stateUpdate: {
+            wire: "state:update";
+            from: "host";
+            session: "current";
+            parse: (fields: Fields) => {
+                state: unknown;
+            };
+        };
+        readonly runtimeLog: {
+            wire: "runtime:log";
+            from: "app";
+            session: "current";
+            parse: (fields: Fields) => {
+                payload: import("./logger.js").LogEntry;
+            };
+        };
+        readonly runtimeReady: {
+            wire: "runtime:ready";
+            from: "app";
+            session: "current";
+            parse: (fields: Fields) => {};
+        };
+        readonly runtimeError: {
+            wire: "runtime:error";
+            from: "app";
+            session: "current";
+            parse: (fields: Fields) => {};
+        };
+    };
+};
+type Events = typeof bridgeProtocol.events;
+export type BridgeEventName = keyof Events;
+export type BridgePayload<Name extends BridgeEventName> = ReturnType<Events[Name]['parse']>;
+export type BridgeEnvelope = {
     channel: typeof BRIDGE;
-    version: 1;
-    type: string;
+    version: typeof bridgeProtocol.version;
     documentId: string;
     sessionId?: string;
-    id?: string;
-    route?: string;
-    payload?: unknown;
-    response?: unknown;
-    code?: string;
-    message?: string;
-    /** Opaque host context, interpreted by optional app adapters. */
-    state?: unknown;
-    requestId?: string;
     token?: string;
-    javascript?: string;
 };
-export declare function isBridgeMessage(value: unknown): value is BridgeMessage;
-export declare function validId(value: unknown): value is string;
-export { validLocation } from './navigation.js';
+export type BridgeEventMessage<Name extends BridgeEventName> = Name extends BridgeEventName ? BridgeEnvelope & {
+    type: Events[Name]['wire'];
+} & (Events[Name]['session'] extends 'none' ? {} : {
+    sessionId: string;
+}) & BridgePayload<Name> : never;
+export type BridgeMessage = {
+    [Name in BridgeEventName]: BridgeEventMessage<Name>;
+}[BridgeEventName];
+export type BridgeEventsFrom<Role extends BridgeRole> = {
+    [Name in BridgeEventName]: Events[Name]['from'] extends Role ? Name : never;
+}[BridgeEventName];
+export type BridgeHandlers<Role extends BridgeRole> = {
+    [Name in BridgeEventsFrom<Role extends 'host' ? 'app' : 'host'>]: (message: BridgeEventMessage<Name>) => void;
+};
+export declare function bridgeEventName(wire: string): "cancel" | "connect" | "disconnect" | "error" | "initialize" | "ready" | "request" | "result" | "runtimeError" | "runtimeLog" | "runtimeReady" | "scriptLoad" | "stateUpdate" | undefined;
+/** Envelope parsing precedes authentication; event-specific fields remain untrusted. */
+export declare function parseBridgeEnvelope(value: unknown): (BridgeEnvelope & Fields & {
+    type: string;
+}) | undefined;
+/** Project event fields after the caller has checked envelope eligibility. */
+export declare function parseBridgePayload(envelope: NonNullable<ReturnType<typeof parseBridgeEnvelope>>, definition: Events[BridgeEventName]): BridgeMessage | undefined;
+export declare function parseBridgeMessage(value: unknown): BridgeMessage | undefined;

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

@@ -2,6 +2,7 @@
  * App identity and display scope shared by browser and server.
  * @module @altertable/data-app/config
  */
+import type { AppearanceOptions } from './appearance.js';
 export type DataAppConfig = {
     title: string;
     /** Display labels; scope does not grant data access. */
@@ -9,6 +10,6 @@ export type DataAppConfig = {
         organization: string;
         environment: string;
     };
-    appearance: unknown;
+    appearance: AppearanceOptions;
 };
 export declare function dataAppTitle(config: Pick<DataAppConfig, 'title' | 'scope'>): string;

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

@@ -0,0 +1,12 @@
+/** Host-owned log sink; compatible with console and frontend createLogger(). */
+export type DataAppLogger = {
+    log: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+export type LogEntry = {
+    method: keyof DataAppLogger;
+    args: unknown[];
+};
+export declare function isLogEntry(value: unknown): value is LogEntry;

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

@@ -1,4 +1,6 @@
 import type { DataAppPresentation } from '../core/presentation.js';
+import type { DataAppLogger } from '../core/logger.js';
+import { type BridgeMessage } from '../core/bridge.js';
 import { type MessageDispatcher } from '../core/messages.js';
 export type DataAppConnection = {
     type: 'origin';
@@ -10,15 +12,17 @@ export type DataAppConnection = {
 export type DataAppStatus = 'connecting' | 'connected' | 'ready' | 'failed' | 'disconnected';
 export type DataAppDiagnostic = {
     direction: 'send' | 'receive';
-    type: string;
+    type: BridgeMessage['type'];
 };
 export type DataAppHost = {
     dispose: () => void;
     setPresentation: (presentation?: DataAppPresentation) => void;
+    setLogger: (logger?: DataAppLogger) => void;
 };
 export type DataAppHostOptions = {
     iframe: HTMLIFrameElement;
     presentation?: DataAppPresentation;
+    logger?: DataAppLogger;
     onStatusChange?: (status: DataAppStatus) => void;
     onDiagnostic?: (event: DataAppDiagnostic) => void;
     onMessage: MessageDispatcher;
@@ -29,4 +33,4 @@ export type DataAppConnectionOptions = DataAppHostOptions & {
     window?: Window;
 };
 /** 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;
+export declare function attachDataAppConnection({ iframe, connection, javascript, presentation, logger, onStatusChange, onDiagnostic, onMessage, window: host, }: DataAppConnectionOptions): DataAppHost;

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

@@ -11,3 +11,4 @@ export { startDataAppBootstrap } from './bootstrap.js';
 export { createNavigationHandler } from './navigation.js';
 export { createSqlQueryHandler } from './sql.js';
 export type { DataAppPresentation } from '../core/presentation.js';
+export type { DataAppLogger } from '../core/logger.js';

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

@@ -12,4 +12,4 @@ export type DataAppSourceOptions = DataAppHostOptions & {
     startupTimeoutMs?: number;
 };
 /** Owns loading and sandbox policy. Dispose before replacing the source or retrying. */
-export declare function attachDataAppSource({ iframe, source, presentation, onMessage, onStatusChange, onDiagnostic, startupTimeoutMs, }: DataAppSourceOptions): DataAppHost;
+export declare function attachDataAppSource({ iframe, source, presentation, logger, onMessage, onStatusChange, onDiagnostic, startupTimeoutMs, }: DataAppSourceOptions): DataAppHost;

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

@@ -2,7 +2,7 @@ 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'> & ({
+export type DataAppBridgeProps = Pick<DataAppBridgeOptions, 'onMessage' | 'onStatusChange' | 'onDiagnostic' | 'presentation' | 'logger'> & ({
     source: DataAppSource;
     title: string;
     startupTimeoutMs?: number;

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

@@ -11,6 +11,7 @@ export { createDataHooks } from './hooks.js';
 export { defineDataContent } from './content.js';
 export type { DataContentState } from './content.js';
 export type { DataViewDefinition, ResolvedVariables, ViewBindings, } from './view.js';
+export type { CsvCell, CsvTable, CsvExport } from './ui/csv-export.js';
 export { DataApp } from './ui/DataApp.js';
 export type { DataAppProps, DataAppRequest } from './ui/DataApp.js';
 export { GettingStarted } from './ui/GettingStarted.js';

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

@@ -1,5 +1,6 @@
 import type { ComponentProps, ComponentPropsWithRef, ReactNode } from 'react';
 import type { DataView } from '../../core/data-view.js';
+import type { CsvExport } from './csv-export.js';
 import { type LiveControlProps } from './LiveControl.js';
 import { PresentStory } from './PresentStory.js';
 import { RefreshControl } from './RefreshControl.js';
@@ -22,10 +23,11 @@ export type AppToolbarProps = {
     live?: LiveControlProps;
     aboutData?: ReactNode;
     story?: ComponentProps<typeof PresentStory>;
+    csvExport?: CsvExport;
 } & Omit<ComponentPropsWithRef<'div'>, 'children'>;
 /** Header actions only. Put reader-controlled inputs in DataApp.variables below the header.
  * Observation time, or an initial loading status, sits before Refresh. Children prepend app controls in the right
  * cluster; end follows the built-in actions. Live sits beside Refresh when supplied. Refresh also
  * answers Alt/Option+R and uses the button to cancel a running request when onCancel is provided;
  * refresh.tooltip overrides its static label. All built-in controls are optional. */
-export declare function AppToolbar({ children, updatedAt, initialLoading, requestState, refresh, live, aboutData, story, end, controlsProps, className, role, 'aria-label': ariaLabel, ...props }: AppToolbarProps): import("react").JSX.Element;
+export declare function AppToolbar({ children, updatedAt, initialLoading, requestState, refresh, live, aboutData, story, csvExport, end, controlsProps, className, role, 'aria-label': ariaLabel, ...props }: AppToolbarProps): import("react").JSX.Element;

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

@@ -1,6 +1,8 @@
 import { type ComponentProps, type ReactNode } from 'react';
 import type { DisclosedQuery } from '../../core/contract.js';
 import type { DataAppConfig } from '../../core/config.js';
+import type { CsvExport } from './csv-export.js';
+import { type DisplayedSnapshot } from '../../core/data-view.js';
 import { type AboutEmpty } from './AboutData.js';
 import { AppLayout } from './AppLayout.js';
 import { type AppToolbarProps } from './AppToolbar.js';
@@ -31,7 +33,9 @@ export type DataAppRequest<Data, Input> = SectionResult<Data, Input> & {
 export type DataAppProps<Data = unknown, Input = unknown> = DataAppBaseProps & ({
     request: DataAppRequest<Data, Input>;
     /** Findings are always derived from the result currently visible to the reader. */
-    story?: BoundStory<Data, Input>;
+    story: BoundStory<Data, Input>;
+    /** Every analytical view exports every distinct dataset in its displayed result. */
+    csvExport: (snapshot: DisplayedSnapshot<Data, Input>) => CsvExport;
     children: (data: Data, displayedInput: Input) => ReactNode;
     loading?: ReactNode;
     label?: string;
@@ -41,6 +45,7 @@ export type DataAppProps<Data = unknown, Input = unknown> = DataAppBaseProps & (
 } | {
     request?: never;
     story?: never;
+    csvExport?: CsvExport;
     children: ReactNode;
     queries?: DisclosedQuery[];
     refresh?: AppToolbarProps['refresh'];

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

@@ -0,0 +1,4 @@
+import { type CsvExport } from './csv-export.js';
+export declare function ExportControl({ csv }: {
+    csv: CsvExport;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+/** Shared page-level feedback for requests and toolbar actions. */
+export declare function Toast({ state, children, onRetry, position, }: {
+    state: 'updating' | 'error' | 'notice';
+    children: ReactNode;
+    onRetry?: () => void;
+    position?: 'top' | 'bottom';
+}): import("react").JSX.Element;

package/dist/types/react/ui/csv-export.d.ts

@@ -0,0 +1,19 @@
+export type CsvCell = string | number | boolean | null | undefined;
+/** One named dataset with ordered columns and raw displayed values. */
+export type CsvTable = {
+    name: string;
+    columns: readonly string[];
+    rows: readonly (readonly CsvCell[])[];
+};
+/** All distinct datasets in the displayed result; filename names the download. */
+export type CsvExport = {
+    filename: string;
+    tables: readonly [CsvTable, ...CsvTable[]];
+};
+export declare function formatCsv({ columns, rows, }: Pick<CsvTable, 'columns' | 'rows'>): string;
+export declare function createCsvDownload(data: CsvExport, selectedTable?: CsvTable): {
+    filename: string;
+    blob: Blob;
+    route: 'export:csv' | 'export:zip';
+};
+export declare function exportCsv(data: CsvExport, table?: CsvTable): Promise<void>;

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

@@ -14,6 +14,7 @@ declare const brandedIcons: {
     readonly info: import("lucide-react").LucideIcon;
     readonly openDetails: import("lucide-react").LucideIcon;
     readonly present: import("lucide-react").LucideIcon;
+    readonly export: import("lucide-react").LucideIcon;
     readonly error: import("lucide-react").LucideIcon;
     readonly close: import("lucide-react").LucideIcon;
     readonly previous: import("lucide-react").LucideIcon;

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

@@ -1,3 +1,3 @@
-import { type Theme } from '../../core/appearance.js';
+import { type Theme, type AppearanceOptions } 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;
+export declare function useAppAppearance(appearance: AppearanceOptions, hostTheme?: Theme): import("../../core/appearance.js").ThemeController | undefined;