Skip to content

feat!: run embedded page actions from the host - #151

Open
francoischalifour wants to merge 2 commits into
mainfrom
fc/embedded-app-apis-b989b9
Open

francoischalifour wants to merge 2 commits into
mainfrom
fc/embedded-app-apis-b989b9

Conversation

@francoischalifour

@francoischalifour francoischalifour commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Embedded data apps rendered their own page toolbar inside the iframe, next to the host's own page chrome. Hosts couldn't place, style or combine those controls, and the frame couldn't make a story fullscreen without a click of its own. This moves page actions to the host: the app tells the host what it offers, and the host renders the controls and runs them through the bridge.

Page actions

With presentation.surface: 'embedded', <DataApp> no longer renders a header, footer, toolbar, toolbarActions or footerActions. It offers its page actions over the bridge instead:

const host = attachDataAppBridge({
  iframe,
  source,
  presentation: { surface: 'embedded', theme: 'light' },
  onActionsChange: actions => render(actions),
  onMessage: router.dispatch,
});

button.onclick = () => host.runAction({ type: 'refresh' });
DataAppActions key State Actions
refresh refreshing, cancellable refresh, cancelRefresh
exportCsv enabled, tables exportCsv, with an optional table
presentStory enabled, presenting presentStory, closeStory
aboutData enabled aboutData
  • A missing key means the app doesn't offer that action. The app resends the full set on every change, and the set resets to {} while it reconnects.
  • React hosts pass onActionsChange to <DataAppBridge> and run actions through its ref (DataAppBridgeHandle).
  • The story, the data inspector and export errors still open inside the frame.
  • When runAction({ type: 'presentStory' }) is called from a click, the bridge shows the iframe fullscreen. It exits when the story closes, and leaving fullscreen closes the story, so it behaves like a standalone story.
  • presentStory and aboutData move focus into the frame. When a story the host ran closes, focus returns to the control that ran it, unless the reader has moved elsewhere. Stories opened from a saved link don't move focus.
  • Whenever there is no in-frame toolbar (embedded, or showToolbar={false}), the host owns annotation mode through annotations.active, where leaving it out means inactive. The in-frame Annotate button only appears inside a standalone toolbar.

Standalone apps are unchanged.

Repair banner

DataAppRepairBanner and DataAppRepairProgress are no longer exported from @altertable/data-app-embed/react. Hosts already build their own repair UI from createDataAppRepairSession. The altertable app dev preview can't send a repair request to an agent, so it keeps a private banner that only shows the error and lets you copy the diagnostics.

Breaking changes

  • Embedded hosts must render page actions from onActionsChange and drive annotations.active; otherwise embedded apps show no page actions.
  • Hosts importing DataAppRepairBanner must render their own repair UI.

Also in this PR

  • @altertable/data-app uses one shared isRecord guard instead of about 20 inline object checks.
  • The diagnostics tests now cover the repair session through a minimal host UI. Copying diagnostics is tested through the dev preview.

@albert20260301 albert20260301 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One keyboard regression at 6c5c4eb3 needs fixing before merge:

Restore focus to the host launcher when an embedded story closes. Moving the trigger out of the frame leaves PresentStory's trigger.current null, while the bridge's fullscreen-exit path does not restore host focus. In Chromium, focus the host “Present story” button → press Enter → press Escape in the story. The story and fullscreen close, but the parent’s active element is the iframe and the frame’s active element is BODY, not the launcher. Keyboard users lose their place in the host controls. The previous presentation test asserted focus restoration; that assertion is removed here.

Please retain the invoking host control and restore focus when this bridge’s presentation ends (without stealing focus for saved-link presentations or from a user who has moved elsewhere), with a keyboard regression test covering the host trigger.

I read the full diff and ran check:static plus 65 focused browser tests: all passed. The dev-preview diagnostics copy/fallback test also passed, and an independent probe confirmed the story still works with fullscreen unavailable. A separate focus-restoration assertion fails as described above. Required CI additionally remains red on the already-reported #149 heading-color assertion; that inherited failure is separate from this finding.

@albert20260301

Copy link
Copy Markdown

The focus finding is fixed at 690167b. The same independent Enter → Escape probe that failed on 6c5c4eb now returns focus to the host launcher. Local static checks and 32 presentation/embedding tests pass, including preserving another host control's focus and not restoring a launcher for saved-link presentations.

The remaining required-CI failure is still the inherited heading assertion (job). #152 addresses that assertion and is now reviewed with green CI. Keeping approval pending until this PR's required checks pass; no rerun requested.

Embedded apps no longer render a toolbar. They offer refresh, CSV export,
story, and inspection through onActionsChange, and the host runs them with
runAction(). Stories run from the host show the iframe fullscreen.

Stop exporting DataAppRepairBanner; hosts build their repair UI from
createDataAppRepairSession, and the dev preview keeps a private copy-only banner.
Host-run stories and inspection move focus into the frame, and a story run
from the host returns focus to the control that ran it once fullscreen exits,
unless the reader has moved elsewhere.
@francoischalifour
francoischalifour force-pushed the fc/embedded-app-apis-b989b9 branch from 690167b to 203299c Compare November 16, 2026 15:19

@albert20260301 albert20260301 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The verified focus fix and heading-test correction are now together at 203299c, with required CI green. The final delta from the previously verified runtime is only the reviewed #152 assertion correction; all five local date tests pass. The earlier static checks, 32 presentation/embedding tests and independent Enter → Escape regression probe cover the unchanged runtime. This resolves my earlier changes request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants