Extension component library

Extension UI is declarative. Extension code sends a serializable component tree, and the console displays it through a sandboxed iframe running the GlobalStacks extension renderer. Use these components instead of custom HTML so extension UI stays consistent, accessible, and safe inside host viewports.

Each component is a versioned contract. The library records the component name, stability, introduced version, properties, supported examples, and compatibility notes so extension authors can build against a stable UI surface.

Render model

GlobalStacks extensions use the same basic shape as sandboxed app views: the console owns the viewport, embeds a sandboxed iframe for extension UI, and passes context to the extension runtime. The extension returns a serializable GlobalStacks component tree that the iframe renderer displays with approved components.

The extension does not mount arbitrary React into the parent console, inject parent-page HTML, or access the console DOM. It runs inside the extension iframe, receives host-provided context, renders supported component contracts, and sends user actions back through brokered async events.

Console viewport -> sandboxed iframe -> extension context -> extension runtime
Iframe renderer <- component tree <- extension view function
Iframe events -> parent bridge -> broker operation -> extension handler

This keeps extension UI isolated from the parent console while still letting GlobalStacks own the component renderer, theme bridge, viewport sizing, provider permissions, and operation broker.

Principles

• Start every view with ContextView, SettingsView, FocusView, SignInView, or FullPageView.
• Prefer compact, scannable layouts over marketing-style panels.
• Use DataGrid for operational tables and Table for simple static rows.
• Keep text short; extension panes are often embedded in dense console pages.
• Use status, badge, and progress cells instead of inventing custom color systems.
• Put side effects behind explicit actions and bridge events.

Component registry

Components are published as registry entries instead of untracked renderer internals. A registry entry includes:

Component versions follow semantic versioning:

• Patch releases clarify docs, examples, or renderer bugs without changing the accepted contract.
• Minor releases add optional properties, examples, or supported enum values.
• Major releases remove properties, change default behavior, or make previously optional properties required.
• Deprecated components and properties remain documented with replacement guidance until the next major extension UI protocol.

Example registry entry:

{
  "name": "Badge",
  "version": "1.0.0",
  "status": "stable",
  "introduced": "[email protected]",
  "props": {
    "tone": {
      "type": "enum",
      "values": ["default", "muted", "info", "success", "warning", "danger"],
      "default": "default"
    },
    "children": {
      "type": "text",
      "required": true
    }
  },
  "examples": ["default", "status-tones", "metadata"]
}

Reference format

Every component reference should include:

Root views

<ContextView title="RushFS">
  <Stack gap="md">
    <Text tone="muted">Storage status and connection details.</Text>
    <Badge tone="success">ready</Badge>
  </Stack>
</ContextView>

ContextView

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Examples: extension-summary, status-panel, resource-details.

SettingsView

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<SettingsView title="Connection settings" description="Configure the RushFS endpoint.">
  <Form operation="rushfs.storage.configure">
    <Stack gap="sm">
      <TextInput name="endpoint" label="Endpoint" defaultValue={endpoint} />
      <Button type="submit">Save settings</Button>
    </Stack>
  </Form>
</SettingsView>

Examples: connection-settings, install-follow-up.

FocusView

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<FocusView title="Import storage backend" primaryAction={{ id: "start-import", label: "Start import" }}>
  <Alert tone="warning">Existing bucket policy will be verified before import.</Alert>
</FocusView>

Examples: guided-import, review-before-submit.

SignInView

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<SignInView
  title="Connect RushFS"
  provider="RushFS"
  action={{ id: "connect", label: "Connect account" }}
>
  <Text tone="muted">GlobalStacks will request storage metadata access.</Text>
</SignInView>

Examples: connect-provider, reauthorize-provider.

FullPageView

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<FullPageView title="RushFS volumes" actions={[{ id: "refresh", label: "Refresh" }]}>
  <DataGrid columns={columns} rows={rows} pagination={pagination} />
</FullPageView>

Examples: resource-index, operational-dashboard.

Layout and text

Use Stack for vertical rhythm and Text for host-owned typography. Available text variants are body, heading, caption, and mono; tones are default, muted, info, success, warning, and danger.

<Stack gap="sm">
  <Text variant="heading">Volume import</Text>
  <Text tone="muted">Import state is synchronized through a brokered operation.</Text>
  <Text variant="mono">rushfs.storage.configure</Text>
</Stack>

Stack

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Examples: basic-stack, settings-group, status-summary.

Text

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Examples: heading-with-caption, mono-operation, muted-help-text.

Status and feedback

Use Badge, Alert, and Progress for status. The renderer owns the color mapping so success, warning, danger, and muted states stay consistent with the console.

<Alert tone="info">Settings are applied through a brokered extension operation.</Alert>
<Badge tone="success">healthy</Badge>
<Progress value={68} />

Badge

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Examples: status-tones, metadata-badge, provider-state.

Alert

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Examples: info-alert, recoverable-warning, permission-error.

Progress

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Examples: bounded-progress, sync-progress.

Forms and actions

Use Form, TextInput, Select, Checkbox, and Button. Form submits should dispatch an operation or bridge event; extensions should not mutate host state directly.

<Form operation="rushfs.storage.configure">
  <Stack gap="sm">
    <TextInput name="endpoint" label="Endpoint" value={endpoint} />
    <Checkbox name="health" label="Enable health checks" checked />
    <Button type="submit">Save settings</Button>
  </Stack>
</Form>

Form

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Events: emits a broker operation submit event.

Examples: settings-submit, connection-test.

TextInput

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<TextInput
  name="endpoint"
  label="Endpoint"
  defaultValue="https://rushfs.example.com"
  helpText="Use the provider API endpoint for this tenant."
  required
/>

Examples: endpoint-field, secret-name-field.

Select

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<Select
  name="region"
  label="Region"
  defaultValue="auto"
  options={[
    { label: "Automatic", value: "auto" },
    { label: "Europe", value: "eu" },
  ]}
/>

Examples: region-select, provider-account-select.

Checkbox

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<Checkbox
  name="healthChecks"
  label="Enable health checks"
  defaultChecked
  helpText="Run a brokered provider check after settings are saved."
/>

Examples: health-check-toggle, confirm-destructive-action.

Button

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Examples: primary-submit, secondary-test, danger-disconnect.

DataGrid

Use DataGrid for operational resources. It accepts serializable columns, rows, pagination, selection, sorting, row actions, loading, and empty states. The iframe renderer owns the internal table engine.

<DataGrid
  columns={[
    { id: "name", header: "Name", sortable: true, minWidth: 180 },
    { id: "provider", header: "Provider" },
    { id: "status", header: "Status", type: "status", pinned: "right" },
    { id: "used", header: "Used", type: "number", align: "right" },
  ]}
  rows={[
    { id: "primary", name: "rushfs-primary", provider: "RushFS", status: "ready", used: 68 },
    { id: "archive", name: "rushfs-archive", provider: "RushFS", status: "syncing", used: 41 },
  ]}
  pagination={{ page: 1, pageSize: 25, totalRows: 2 }}
  selection={{ mode: "multiple", selectedRowIds: [] }}
  rowActions={[{ id: "open", label: "Open", variant: "secondary" }]}
  onAction={() => undefined}
  onSortChange={() => undefined}
  onPageChange={() => undefined}
  onSelectionChange={() => undefined}
/>

DataGrid

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Events: emits sort, page, selection, and row-action bridge events.

Examples: resource-list, paginated-volumes, selectable-buckets, empty-results.

Table

Use Table when the rows are static and do not need selection, row actions, or pagination.

<Table
  columns={[
    { id: "key", header: "Property" },
    { id: "value", header: "Value" },
  ]}
  rows={[
    { key: "Runtime", value: "sandbox" },
    { key: "Distribution", value: "private" },
  ]}
/>

Table

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

Examples: key-value-table, static-provider-summary.

Empty and navigation states

Use EmptyState when a supported surface has no records yet. Use Link for host-approved navigation or external documentation.

EmptyState

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<EmptyState
  title="No buckets found"
  description="Create a bucket in RushFS or refresh provider metadata."
  action={{ id: "refresh", label: "Refresh" }}
/>

Examples: empty-resource-list, unsupported-provider-state.

Link

• Version: 1.0.0
• Status: stable
• Introduced: [email protected]

<Link href="https://rushfs.example.com/docs" external>
  RushFS provider documentation
</Link>

Examples: external-docs-link, internal-resource-link.

Current component surface

Style rules

• Keep root views narrow unless the viewport is globalstacks.console.full_page.
• Prefer one primary action per view.
• Use action buttons for commands and links for navigation.
• Use DataGrid row actions instead of embedding multiple buttons in plain text.
• Avoid custom color names, gradients, and decorative elements.
• Keep column headers short and make status columns use type: "status".
• Use the style extension UI page for supported style tokens, layout props, spacing, sizing, and preset component style controls.