SurfaceConnection

The provider-side client an embedded surface (or a modal body) receives, returned by connectSurface. It is the surface-scoped counterpart to Platform: the surface reads its params, renders, reports its height, and re-renders on onParams — all brokered through the shell like any channel.

Properties

channelId

readonly channelId: string;

This surface’s channel id.

readonly modal: {
  open: Promise<T | null>;
};

Open a shell-brokered modal whose body is one of this app’s own surfaces.

open()

open<T>(opts): Promise<T | null>;

Open the modal; resolves with the body’s result, or null if dismissed.

Type Parameters

T

T = unknown

Parameters

opts

ModalOpenOptions

Returns

Promise<T | null>

params

readonly params: unknown;

The params the host (or modal opener) passed; re-read on SurfaceConnection.onParams.

session

readonly session: Session;

The current user snapshot. See Session.

state

readonly state: StateClient;

App-scoped shared state across this app’s frames (e.g. a modal body driving a draft the parent reflects). See StateClient.

surfaceName

readonly surfaceName: string;

The surface name this entrypoint was loaded as.

telemetry

readonly telemetry: {
  error: void;
  event: void;
  timing: void;
};

Structured telemetry, correlated to the active trace.

error()

error(name, data?): void;

Record a named error.

Parameters

name

string

data?

unknown

Returns

void

event()

event(name, data?): void;

Record a named event.

Parameters

name

string

data?

unknown

Returns

void

timing()

timing(name, data?): void;

Record a named timing measurement.

Parameters

name

string

data?

unknown

Returns

void

theme

readonly theme: ThemeInfo;

The active theme. See ThemeInfo.

Methods

activate()

activate(el): void;

Convenience for the standard surface bring-up: after one animation frame — so custom elements such as the <ds-*> design-system components have upgraded and the first measured height is the final one — SurfaceConnection.observe el and then call SurfaceConnection.ready. Call it once from your framework’s post-render hook (Angular afterNextRender, React useEffect) with the surface’s root element; it replaces the hand-rolled observe + ready (+ rAF) every surface otherwise repeats.

Parameters

el

HTMLElement

Returns

void

close()

close(result?): void;

When this surface IS a modal body, close it and resolve the opener with result.

Parameters

result?

unknown

Returns

void

disconnect()

disconnect(): void;

Detach all listeners and timers for this surface.

Returns

void

getRoles()

getRoles(): string[];

Advisory roles for show/hide; the surface’s backend is the real gate.

Returns

string[]

hasRole()

hasRole(role): boolean;

Whether the advisory roles include role; for affordances only, never enforcement.

Parameters

role

string

Returns

boolean

log()

log(
   level,
   message,
   fields?): void;

Emit a correlated log line.

Parameters

level

LogLevel

message

string

fields?

Record<string, unknown>

Returns

void

observe()

observe(el): void;

Track an element’s size so the shell keeps the surface’s iframe sized to its content.

Parameters

el

HTMLElement

Returns

void

onParams()

onParams(handler): () => void;

Subscribe to the host re-parameterising this surface; returns an unsubscribe function.

Parameters

handler

(params) => void

Returns

() => void

onRefresh()

onRefresh(handler): () => void;

React to a refresh nudge (e.g. a dashboard widget’s refresh button) — re-fetch with the CURRENT params, no param change. Returns an unsubscribe function.

Parameters

handler

() => void

Returns

() => void

onThemeChange()

onThemeChange(handler): () => void;

Subscribe to theme changes; returns an unsubscribe function.

Parameters

handler

(theme) => void

Returns

() => void

ready()

ready(): void;

Signal the surface has rendered + wired its handlers (releases the shell barrier); pair with SurfaceConnection.observe for correct sizing.

Returns

void

reportHeight()

reportHeight(height): void;

Report a one-off height in pixels (use instead of, or alongside, SurfaceConnection.observe).

Parameters

height

number

Returns

void

span()

span(name): SpanHandle;

Open a timing span. See SpanHandle.

Parameters

name

string

Returns

SpanHandle