Surface events

Internal contract

The current SumSheet shell emits these events. They’re not part of the public embedding kit and can change without notice: subscribing to them is fine in an internal build, but not as a long-term API. The public event contract is locked in separately.

All the names start with fastsheet: — a product prefix, not a brand one; renaming the product to SumSheet didn’t touch it.

What the shell emits

The surface sends three object events on itself, with bubbles: true — you can listen on the node itself, or on any of its ancestors.

Event	When it fires	What’s in detail
fastsheet:surface-object-selected	A graphic object on the sheet is selected	objectId, sheetKey, family, status; for charts, also chartLocalX, chartLocalY, chartTargetId
fastsheet:surface-object-dragging	An object is being dragged	objectId and bounds — and nothing else
fastsheet:surface-object-moved	Dragging is finished	objectId, sheetKey, family, status

Dragging has a different detail shape

fastsheet:surface-object-dragging carries only the identifier and bounds: sheetKey, family, and status are absent from it. A handler written after the pattern of the selection event will get undefined here — and won’t throw an error, it’ll just silently run on the wrong sheet.

The locale change arrives somewhere different from the rest

Event	Where to listen	What’s in detail
fastsheet:surface-locale-changed	on window	locale, direction

This is the only event the shell sends not to the surface but to window, and it doesn’t bubble. A listener attached to the surface node alongside the other four will never get the locale change.

fastsheet:surface-dispose goes the other way

The shell doesn’t emit this event — it listens for it. The embedding application sends it — that’s how it tells the surface its node is leaving the page; on receiving the event, the shell unregisters the surface, disconnects its own listeners, and clears temporary nodes.

// Remove the surface before deleting the node from the page.
surface.dispatchEvent(new CustomEvent("fastsheet:surface-dispose"));

Subscribing to it while waiting for a “surface closed” signal makes no sense: you send it, not the surface.

It’s not worth parsing detail directly

Wrap the events in a facade of your own, as shown in Runtime environments: the contents of detail are the shell’s internal business, and even today they already differ between neighboring events.