Skip to content
OpenWaggle
Applies to @openwaggle/[email protected]

Extension React component catalogue

Visual reference for every @openwaggle/extension-react 0.2 component, variant, tone, and form state.

This catalogue renders the same class names, attributes, and stylesheet shipped by @openwaggle/extension-react. The examples are interactive HTML equivalents of the React components, so you can inspect disabled, validation, and control states directly. This page supplies the SDK’s default dark theme on each example root, the way the OpenWaggle host supplies the active theme to a mounted extension.

Import the package stylesheet and render the components beneath the host-provided .ow-extension-root element.

import '@openwaggle/extension-react/styles.css'
import { Button, Field, Input, Panel, Stack } from '@openwaggle/extension-react'

Composed settings surface

Issue tracker

A settings surface composed from Panel, Stack, Field, Input, Select, Checkbox, Badge, Alert, and Button.

Connected
Owner and repository name used for issue queries.
Configuration is stored through the brokered project settings capability.

Layout

Panel provides the themed surface. Stack lays out children vertically and accepts any CSS gap. Use them together for extension-owned composition rather than importing private OpenWaggle renderer layouts. Use ordinary extension-owned markup for layouts that do not need a package component.

<Panel>
  <Stack gap="0.75rem">
    <Heading />
    <Content />
  </Stack>
</Panel>

Button

Button forwards native button props and supports primary, secondary, and ghost variants. secondary is the default. Use a real button type and keep native disabled semantics.

Badge and Alert tones

Badge provides compact metadata. Alert provides status, note, or urgent feedback through its role, which is status by default. Both support neutral, accent, success, warning, danger, and info tones. Use semantic tones only for their stated meaning. Do not use danger or warning merely for visual emphasis.

Neutral Accent Success Warning Danger Info
No extension status has been reported yet.
This extension can add a project-specific view.
The extension settings were saved.
The next refresh may use cached data.
The extension will refresh when the active project changes.
<Stack>
  <Badge tone="success">Connected</Badge>
  <Alert tone="warning" role="note">Review the configuration before continuing.</Alert>
</Stack>

Input, Textarea, Select, Checkbox, and Field

Field groups a label, optional description, control, and error. Set its htmlFor to the control’s id to connect the label. It does not assign IDs or connect descriptions and errors automatically. Add aria-describedby and aria-invalid to the control when needed, and give the referenced description or error element an ID. Input, Textarea, Select, and Checkbox forward native attributes and refs.

Comma-separated GitHub labels.
Choose a project before saving.
<Field
  htmlFor="provider"
  label="Provider"
  description="Choose the provider used by this extension."
>
  <Select id="provider" defaultValue="openai">
    <option value="openai">OpenAI</option>
    <option value="anthropic">Anthropic</option>
  </Select>
</Field>

Keep labels visible, preserve keyboard interaction, and use native disabled and validation states. Package focus styles use the host-projected focus ring and shadow variables. The default theme sets both to transparent and none, so it draws no focus ring.

Source and syntax

SyntaxBlock renders host-produced token lines. Both it and SourceView accept a syntax capability from the mount context, source text, and either a canonical language or a path.

<SourceView
  syntax={context.sdk.surface.syntax}
  source={configurationSource}
  path="openwaggle.extension.json"
  ariaLabel="Extension manifest"
/>

SourceView shows line numbers by default and has a fixed height of up to 320 pixels. It renders only the lines in view, so long files stay fast. It asks the host to highlight a source only up to 64 KiB (65,536 UTF-16 code units) and 2,000 lines, and shows larger sources as plain text. It ignores wrap. Use SyntaxBlock with wrap for short snippets that should wrap.

Both components begin with safe plain text, then apply the latest host result. They ignore an obsolete async result after the source changes. The host owns theme selection, language aliases, scheduling, caching, input limits, and fallback diagnostics. The extension never receives highlighted HTML.

This static example shows the plain-text markup a SyntaxBlock with showLineNumbers renders before the host result arrives:

{
  "id": "issue-tracker",
  "name": "Issue tracker",
  "version": "0.2.0"
}

Theme contract

The stylesheet uses the complete @openwaggle/extension-sdk 0.2 appearance projection. OpenWaggle supplies it on the extension root. A standalone preview must apply .ow-extension-root and provide the same variables, for example from extensionThemeCssVariableDeclarations() in @openwaggle/extension-sdk. The stylesheet has no fallback theme of its own.

See the API reference for the exported components and prop type names.