Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -350,9 +350,9 @@ CsvTable.rows: readonly (readonly CsvCell[])[]
DataApp (component, @altertable/data-app-react): <Data, Input, const SummaryViews extends readonly AnyView[] = [ ]>(props: DataAppProps<Data, Input, SummaryViews>) — Executes the primary view and its summary views, and owns controls, inspection, exports, and stories.
DataApp.children: ReactNode
DataApp.description?: ReactNode — Override the declared subtitle; null hides it.
DataApp.showToolbar?: boolean — Show page actions. Defaults to true; does not hide filters or data states.
DataApp.toolbarActions?: ReactNode
DataApp.footerActions?: ReactNode
DataApp.showToolbar?: boolean — Show page actions. Defaults to true; does not hide filters or data states. Embedded surfaces have no toolbar: the host runs page actions through its bridge.
DataApp.toolbarActions?: ReactNode — Standalone toolbar controls; embedded surfaces omit them.
DataApp.footerActions?: ReactNode — Standalone footer controls; embedded surfaces omit them.
DataApp.footer?: ReactNode — Optional source, coverage, or methodology note below the app content. Compose prose and inline components; typography and spacing are provided.
DataApp.showSearch?: boolean — Show declared search controls. Defaults to true; hiding preserves their values.
DataApp.showFilters?: boolean — Show declared filter controls, including display options. Defaults to true; hiding preserves their values.
Expand All @@ -366,9 +366,9 @@ DataApp (component, @altertable/data-app-react/ui): (props: DataAppProps) — Se
DataApp.children: ReactNode
DataApp.dataContext: DataContext
DataApp.description?: ReactNode — Override the declared subtitle; null hides it.
DataApp.showToolbar?: boolean — Show page actions. Defaults to true; does not hide filters or data states.
DataApp.toolbarActions?: ReactNode
DataApp.footerActions?: ReactNode
DataApp.showToolbar?: boolean — Show page actions. Defaults to true; does not hide filters or data states. Embedded surfaces have no toolbar: the host runs page actions through its bridge.
DataApp.toolbarActions?: ReactNode — Standalone toolbar controls; embedded surfaces omit them.
DataApp.footerActions?: ReactNode — Standalone footer controls; embedded surfaces omit them.
DataApp.footer?: ReactNode — Optional source, coverage, or methodology note below the app content. Compose prose and inline components; typography and spacing are provided.
DataApp.csvExport?: CsvExport
DataApp.queries?: DisclosedQuery[]
Expand Down Expand Up @@ -398,9 +398,9 @@ DataAppProps (type, @altertable/data-app-react/ui)
DataAppProps.children: ReactNode
DataAppProps.dataContext: DataContext
DataAppProps.description?: ReactNode — Override the declared subtitle; null hides it.
DataAppProps.showToolbar?: boolean — Show page actions. Defaults to true; does not hide filters or data states.
DataAppProps.toolbarActions?: ReactNode
DataAppProps.footerActions?: ReactNode
DataAppProps.showToolbar?: boolean — Show page actions. Defaults to true; does not hide filters or data states. Embedded surfaces have no toolbar: the host runs page actions through its bridge.
DataAppProps.toolbarActions?: ReactNode — Standalone toolbar controls; embedded surfaces omit them.
DataAppProps.footerActions?: ReactNode — Standalone footer controls; embedded surfaces omit them.
DataAppProps.footer?: ReactNode — Optional source, coverage, or methodology note below the app content. Compose prose and inline components; typography and spacing are provided.
DataAppProps.csvExport?: CsvExport
DataAppProps.queries?: DisclosedQuery[]
Expand Down Expand Up @@ -1311,6 +1311,7 @@ PresentStory.dataContext: DataContext
PresentStory.theme?: ThemeController
PresentStory.headerActions?: ReactNode
PresentStory.footer?: ReactNode
PresentStory.trigger?: boolean — False renders only the presentation, which `?present=1&step=` opens.
PresentStory.…: plus props inherited from React
PresentStoryProps (type, @altertable/data-app-react/ui): = props listed as PresentStory.*
QueryDefinitions (type, @altertable/data-app, @altertable/data-app/config, @altertable/data-app/contract): <Record<string, QueryDefinition>> = { readonly [x: string]: QueryDefinition; }
Expand Down
13 changes: 2 additions & 11 deletions dev/fixtures/annotation-state-app.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ const client = createDataClient<typeof operations>({
return Promise.resolve({
status: 200,
body: {
data: period === 'last-365' ? 84 : 42,
data: 42,
requestId: period,
queriedAt: '2026-10-07T00:00:00Z',
queryIds: [],
Expand Down Expand Up @@ -105,16 +105,7 @@ const content = view.content(source => (
));
function App() {
return (
<DataApp
view={view}
story={() => []}
datasets={[dataset]}
toolbarActions={
<button onClick={() => changePeriod('last-365')}>
Change displayed period
</button>
}
>
<DataApp view={view} story={() => []} datasets={[dataset]}>
<DataSection content={content} />
</DataApp>
);
Expand Down
115 changes: 110 additions & 5 deletions dev/fixtures/bundle-host.tsx
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
import {
type DataAppActions,
type DataAppLogger,
type DataAppStatus,
createNavigationHandler,
createExternalLinkHandler,
createSqlQueryHandler,
} from '@altertable/data-app-embed';
import { DataAppBridge } from '@altertable/data-app-embed/react';
import {
DataAppBridge,
type DataAppBridgeHandle,
} from '@altertable/data-app-embed/react';
import {
AnnotationBar,
type AnnotationBarHandle,
Expand Down Expand Up @@ -34,14 +38,25 @@ import { KEY_SEPARATOR } from '@altertable/data-app/internal';
import '@/packages/data-app-react/src/ui/Tooltip.css';
import '@/packages/data-app-react/src/ui/Kbd.css';

import { Moon, Sun, PanelsTopLeft, AppWindow } from 'lucide-react';
import {
Moon,
Sun,
PanelsTopLeft,
AppWindow,
RefreshCw,
Square,
Download,
Presentation,
Info,
} from 'lucide-react';
import {
StrictMode,
useEffectEvent,
useReducer,
useRef,
useState,
type ComponentRef,
type RefObject,
} from 'react';
import { createRoot } from 'react-dom/client';

Expand Down Expand Up @@ -107,7 +122,72 @@ const previewLabels = {
standalone: 'Preview embedded app',
};

/** Page actions the embedded app offers, rendered by the host instead of an in-app toolbar. */
function HostPageActions({
actions,
run,
portalRoot,
}: {
actions: DataAppActions;
run: DataAppBridgeHandle['runAction'];
portalRoot: RefObject<HTMLElement | null>;
}) {
const { refresh, exportCsv, presentStory, aboutData } = actions;
const items = [
refresh && {
label: refresh.refreshing
? refresh.cancellable
? 'Cancel refresh'
: 'Refreshing data'
: 'Refresh data',
icon: refresh.refreshing && refresh.cancellable ? Square : RefreshCw,
disabled: refresh.refreshing && !refresh.cancellable,
busy: refresh.refreshing,
run: () =>
run({ type: refresh.refreshing ? 'cancelRefresh' : 'refresh' }),
},
exportCsv && {
label:
exportCsv.tables.length > 1 ? 'Export all data (ZIP)' : 'Export CSV',
icon: Download,
disabled: !exportCsv.enabled,
run: () => run({ type: 'exportCsv' }),
},
presentStory && {
label: 'Present story',
icon: Presentation,
disabled: !presentStory.enabled,
run: () => run({ type: 'presentStory' }),
},
aboutData && {
label: 'Explore data',
icon: Info,
disabled: !aboutData.enabled,
run: () => run({ type: 'aboutData' }),
},
].filter(item => !!item);
return items.map(item => (
<Tooltip
key={item.label}
content={item.label}
placement="bottom"
portalRoot={portalRoot}
>
<button
aria-label={item.label}
aria-busy={item.busy}
disabled={item.disabled}
onClick={item.run}
>
<item.icon size={16} aria-hidden="true" />
</button>
</Tooltip>
));
}

function Host() {
const bridge = useRef<DataAppBridgeHandle>(null);
const [actions, setActions] = useState<DataAppActions>({});
const [annotationFailure, setAnnotationFailure] = useState(
hostOptions.has('annotation-error')
);
Expand Down Expand Up @@ -177,9 +257,10 @@ function Host() {
? {
annotations: {
enabled: true,
// Without an in-frame toolbar, the host always owns annotation mode.
active: annotating,
...(isPlayground
? {
active: annotating,
pinsVisible,
showHint: annotations.length === 0,
readOnly: sending || !annotationsHost.ready,
Expand Down Expand Up @@ -336,6 +417,14 @@ function Host() {
>
Change surface
</button>
{hostOptions.has('annotations') && (
<button
aria-pressed={annotating}
onClick={() => setAnnotating(value => !value)}
>
Annotate
</button>
)}
</>
);
const testControls = (
Expand Down Expand Up @@ -379,6 +468,11 @@ function Host() {
aria-label="Playground controls"
className="playground-controls"
>
<HostPageActions
actions={actions}
run={action => bridge.current?.runAction(action)}
portalRoot={hostRef}
/>
{showSizingControls && (
<>
<button
Expand Down Expand Up @@ -468,6 +562,15 @@ function Host() {
<>
{presentationControls}
{testControls}
<TooltipProvider>
<fieldset aria-label="Host page actions">
<HostPageActions
actions={actions}
run={action => bridge.current?.runAction(action)}
portalRoot={hostRef}
/>
</fieldset>
</TooltipProvider>
</>
)}
{isPlayground && (annotating || annotationsHost.deletedAnnotationId) && (
Expand Down Expand Up @@ -534,8 +637,8 @@ function Host() {
>
<h1>An app inside a page</h1>
<p>
Scroll the report, open its data inspector or story, and resize
the compact panel. The app toolbar stays available in both modes.
Scroll the report, open its data inspector or story from the page
actions above, and resize the compact panel.
</p>
<output aria-label="Scroll owner">
{sizesToContent
Expand All @@ -560,6 +663,8 @@ function Host() {
)}
<DataAppBridge
key={attempt}
ref={bridge}
onActionsChange={setActions}
onStatusChange={nextStatus => {
setStatus(nextStatus);
if (nextStatus === 'failed' || nextStatus === 'disconnected')
Expand Down
39 changes: 16 additions & 23 deletions docs/diagnostics.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,7 @@ Change the revision identifier when app source changes.

```tsx
import { createDataAppRepairSession } from '@altertable/data-app-embed';
import {
DataAppBridge,
DataAppRepairBanner,
} from '@altertable/data-app-embed/react';
import { DataAppBridge } from '@altertable/data-app-embed/react';

const session = createDataAppRepairSession({
state: restoredState, // New app: { automaticRequests: 0, attemptedRevisions: [] }
Expand All @@ -24,34 +21,31 @@ const session = createDataAppRepairSession({
});

const viewer = (
<>
<DataAppRepairBanner session={session} />
<DataAppBridge
source={{ type: 'bundle', javascript }}
title="Data app"
repair={{ session, revision }}
onMessage={onMessage}
/>
</>
<DataAppBridge
source={{ type: 'bundle', javascript }}
title="Data app"
repair={{ session, revision }}
onMessage={onMessage}
/>
);
```

The host owns authorization, delivery, and state retention. `onStateChange` is
awaited before automatic delivery; reject if state cannot be retained. Three automatic
requests are allowed per session; manual requests and healthy revisions do not
reset the allowance. Callback resolution means acceptance, not agent execution.
Omit `onRepairRequest` when delivery or reliable state retention is unavailable;
the banner offers diagnostics to copy instead. Avoid sensitive values in errors.
Omit `onRepairRequest` when delivery or reliable state retention is unavailable,
and offer the diagnostics to copy instead. Avoid sensitive values in errors.
Source locations use generated filenames and positions.

## Custom banners
## Repair UI

Use `session.snapshot()` to read diagnostics, delivery status, the automatic
request count, and the latest request's start time. Subscribe with
`session.subscribe()` and request a fix with `session.requestRepair()`. These APIs
work without React or the default banner.
The host renders its own repair UI. Use `session.snapshot()` to read diagnostics,
delivery status, the automatic request count, and the latest request's start
time. Subscribe with `session.subscribe()` and request a fix with
`session.requestRepair()`. These APIs work without React.

In React, pass the snapshot to your own banner:
In React, pass the snapshot to your banner:

```tsx
import type { DataAppRepairSession } from '@altertable/data-app-embed';
Expand All @@ -78,5 +72,4 @@ function AppRepair({ session }: { session: DataAppRepairSession }) {
The host owns agent activity and revision loading. Request acceptance does not
mean the agent has started or finished. Clear the previous attempt's activity
when requesting another fix, and clear progress when the updated revision's
diagnostics settle. Custom banners choose their own presentation; the default
`<DataAppRepairBanner>` accepts observed host activity through `progress`.
diagnostics settle.
46 changes: 45 additions & 1 deletion docs/embed.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,9 +230,53 @@ host.setPresentation({ surface: 'embedded', theme: 'light' });
Use `surface: 'embedded'` when the parent supplies page chrome and
`'standalone'` when the app supplies it. Resolve the parent theme to `'light'` or
`'dark'`. React `<DataApp>` applies presentation automatically: embedded surfaces
keep toolbar actions and hide header/footer. Updates do not reload the iframe.
hide the header, footer, and page toolbar, and offer its actions to the parent
through [page actions](#page-actions). Updates do not reload the iframe.
Call `host.setPresentation(undefined)` to restore standalone defaults.

The parent also owns annotation mode whenever the app shows no toolbar, as on
embedded surfaces: set `annotations.active` (omitted means inactive) and handle
the `annotation:mode` route.

### Page actions

An embedded app shows no toolbar. It offers its page actions to the parent,
which renders the controls and runs them through the bridge:

```ts
// ... iframe, authorized router, and refreshButton
const host = attachDataAppBridge({
iframe,
source: { type: 'url', url: 'https://apps.example.com/report' },
presentation: { surface: 'embedded', theme: 'light' },
onActionsChange(actions) {
refreshButton.hidden = !actions.refresh;
refreshButton.disabled = actions.refresh?.refreshing ?? true;
},
onMessage: router.dispatch,
});

refreshButton.onclick = () => host.runAction({ type: 'refresh' });
```

`onActionsChange` receives the complete `DataAppActions` on every change. Render
only the keys present:

| Offered state | Run | Notes |
| --------------------------------------- | --------------------------------- | ---------------------------------------------------------------------- |
| `refresh: { refreshing, cancellable }` | `refresh`, `cancelRefresh` | Cancel only while `refreshing` and `cancellable`. |
| `exportCsv: { enabled, tables }` | `exportCsv` with optional `table` | Omit `table` to export every dataset, as a ZIP when there are several. |
| `presentStory: { enabled, presenting }` | `presentStory`, `closeStory` | Shows the iframe fullscreen while presenting. |
| `aboutData: { enabled }` | `aboutData` | Opens the data inspector in the frame. |

Call `runAction()` from the user's click: the bridge needs that gesture to show
a story fullscreen. It exits fullscreen when the story closes, and leaving
fullscreen closes the story. `presentStory` and `aboutData` move focus into the
frame; when that story closes, focus returns to the control that ran it unless
the reader has moved elsewhere. The app ignores actions it does not currently
offer. While the app reconnects, actions reset to `{}` and `runAction()` does
nothing.

### Content sizing

By default the parent sizes the iframe and the app scrolls inside it. Set
Expand Down
4 changes: 4 additions & 0 deletions docs/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ Compose paragraphs, links, and inline components directly; no `<TextContent>`
wrapper is needed. Keep headings and widgets in the body and controls in
`footerActions`.

Embedded hosts supply the page chrome, so `<DataApp>` omits its header, footer,
`toolbarActions`, and `footerActions` there; the host runs refresh, export,
story, and inspection. Keep controls readers need in the body.

## Verify rendered layouts

Review authored composition with realistic labels and values. For custom layout
Expand Down
Loading