Sea context

<sea-context> is the required outer provider for Sea widgets. It holds the API client, credential and shared metadata, including language, actor attribution and document access settings. It owns citation handling, source selection and widget interaction tracking.

Place a process inside it to select a run. All intake widgets must be descendants of the context. Host HTML and layout elements can sit between providers and widgets.

At a glance
Type	Required provider. It displays nothing itself
Element	sea-context
React	SeaContextProvider from @sea-dev/widget-lit/react/context
Without React	@sea-dev/widget-lit/context
Connection	Uses the page API host and shares credentials with descendant widgets
Configure	Attributes and properties

API host

Expose the deployment's API_PUBLIC_URL once in the page head before mounting any provider. Set it to the API host root, without /v2:

<meta name="sea-api-url" content="{API_HOST}" />

Your application supplies this value from its deployment environment at page startup. The same package works in each environment. No host URL is passed to a provider or widget.

An unset or invalid value prevents API requests. Use an absolute HTTP or HTTPS URL without credentials, a query or a fragment. For bundled fictional data, set the value to demo.

All providers in one page use the configured deployment. To change it, unmount the providers, replace the metadata, then mount them again. Credential changes on the existing providers remain supported.

getWidgetConfig() from @sea-dev/widget-lit/config returns the current page API host as apiUrl for host requests.

SeaContextProvider is the primary React wrapper name. SeaContext remains an alias.

Usage

Put the process and its widgets inside SeaContextProvider. The document intake example provides the complete React composition.

Attributes and properties

Property	Attribute	Type	Default	Description
clientFactory	—	ApiClientFactory or undefined	—	Supplies a host transport factory for the shared client.
apiUrl	api-url	string	""	Sets the shared API host, falling back to the enclosing context or page metadata.
apiKey	api-key	string	""	Authenticates with an API key when the bearer token is unset.
bearerToken	bearer-token	string	""	Authenticates API requests with a host-supplied bearer token, taking precedence over apiKey.
documentUrl	—	DocumentUrlResolver or undefined	—	Rewrites source document URLs before retrieval.
documentProxy	document-proxy	string	""	Prefixes source URLs with a proxy endpoint using its url query parameter.
formId	form-id	string or undefined	—	Scopes automatic selection to this form.
dealId	deal-id	string or undefined	—	Scopes automatic selection to this deal.
submissionId	submission-id	string or undefined	—	Selects an existing submission explicitly.
submissionSelection	submission-selection	SubmissionSelectionPolicy or undefined	—	Selects explicit, unique, latest or latest-final submission resolution.
dealRefId	deal-ref-id	string or undefined	—	Identifies the external deal for labelled child views. An empty value clears the inherited reference.
requestRefId	request-ref-id	string or undefined	—	Scopes labelled child views to an external document request. An empty value clears the inherited reference.
documentType	document-type	string or undefined	—	Selects the configured document type for labelled child views. An empty value clears inherited type and confidence fields.
actorId	actor-id	string	""	Identifies the actor recorded with corrections.
actorName	actor-name	string	""	Supplies the attributed actor display name when actorId is set.
actorEmail	actor-email	string	""	Supplies the attributed actor email when actorId is set.
trackCitations	track-citations	boolean	true	Citation tracking is always enabled. This input is ignored.
citationPopoverPlacement	citation-popover-placement	string	""	Sets the PDF citation popover placement to gutter, rail, below, above, beside or edge.
locale	locale	string	""	Sets the display language of descendant widgets using a BCP 47 locale tag.
selectedItemId	selected-item-id	string	""	Selects a submission item's citation in descendant viewers, taking precedence over selectedFieldName.
selectedFieldName	selected-field-name	string	""	Selects a citation by field name or translated display name when selectedItemId is unset.
value	—	SeaContextValue	—	Returns the current context value for programmatic access.

Events

Event	Type	Description
submission-selection-error	CustomEvent	{ code, message } when submission selection fails or mismatches its scope.

Submission selection

For run-based screens, the process owns output selection. Keep only connection and shared metadata on the outer context. The following selection settings apply to existing submission-based views.

Set submissionId for a known record. For automatic selection, supply formId, dealId and submissionSelection: unique, latest or latest-final. The default is explicit. Automatic selection stays pinned until refreshSelection() runs.

The provider renders its children through its default slot, without a visible panel. Call refreshSelection() on the element or React ref to resolve automatic selection again.

Nested contexts inherit unset credentials and scope. Set a nested submissionId to show a different submission with the inherited connection. Separate processes inside one context retain independent run and document selections.

Submission shell

Import the package entry, @sea-dev/widget-lit, to register <sea-widget>. It inherits the provider's connection and record scope. With formId, it lists that form's submissions. dealId narrows the list and enables creation. An unresolved dealRefId never opens an organisation-wide list. Automatic selection waits for the provider and shows its failure state; it never falls back to the list.

<sea-context api-key="{API_KEY}" form-id="{FORM_ID}" deal-id="{DEAL_ID}">
  <sea-widget hide-lang-toggle></sea-widget>
</sea-context>

Set submissionId on the provider to open a known record. That binding stays selected. Back applies only to a selection made from the shell list.

The shell accepts hideLangToggle (hide-lang-toggle) to hide its language control. Standard HTML styling applies. Connection, record and language settings belong on the provider. submission-created and submission-selected notify your application of the chosen detail.submissionId.

Language

Set locale to choose the language for this provider and its descendants. See Language and direction for inheritance, toggles and saved preferences.

Source selection and attribution

Set selectedItemId to select that item's source. selectedFieldName selects by field name when the item ID is unset. Clear both to clear host selection.

Set actorId for correction attribution; actorName and actorEmail provide display details. Sea context handles citation navigation and records interaction telemetry for its descendants.

What it needs from the API

The provider reads the selected submission and reloads when its inputs change or data is invalidated. It can also load related submissions that contain source documents. sea-api-url metadata set to demo with submissionId="sub-1" selects the bundled demonstration record.

Custom transports

Run-based composition also needs the process transport operations. The outer context supplies the same client to process and input widgets.

Loading related submissions from the selected submission's run, such as its data step and check outputs, needs deal.nav with { dealId }. It returns { rows } with the submission, form and run identities described by WidgetOperations["deal.nav"]. A configured transport handles it without a REST fallback.

Use the WidgetOperations types from @sea-dev/widget-lit/transport. The bundled tRPC adapter reports status 501 for pipeline.list and pipeline.runStatus. Use the REST client or implement these operations in the custom transport.

Common problems

Symptom	Action
Child has no values	Check submissionId, automatic selection scope and the provider's loading error
Panes show different submissions	Check the nearest context for each pane
Selection fails	Use submission-selection-error.detail.code to correct missing, ambiguous or mismatched scope