Components

The SDK provides four Web Components. Each renders inside Shadow DOM, isolated from your host page styles.

`<hyphen-task-sidebar>`

A sidebar panel showing pending human-in-the-loop tasks from your workflows. Each task displays the workflow name, step context, urgency level, and approve/reject controls.

html

<hyphen-task-sidebar
  auto-refresh
  refresh-interval="10000"
  show-urgency>
</hyphen-task-sidebar>

Attributes

Attribute	Type	Default	Description
`auto-refresh`	flag	off	Automatically poll for new tasks
`refresh-interval`	ms	`15000`	Polling interval when auto-refresh is on
`show-urgency`	flag	off	Display urgency badges on tasks

Events

Event	Data	When
`task:decided`	`{ runId, stepId, approved, comment }`	User approves or rejects a task

How It Works

The sidebar fetches pending tasks scoped to your publishable key. When a user clicks approve or reject, the SDK sends the decision to the gateway, which forwards it to the workflow engine. The workflow resumes from the approval step with the decision in context (@__approved, @__comment).

Connected to workflows. The tasks shown are real PbotApproval steps paused in your workflows. Approving a task in the sidebar resumes the workflow — no additional API call required.

---

`<hyphen-data-grid>`

A sortable, paginated data table connected to Hyphen custom tables. Supports inline editing for operations teams.

html

<hyphen-data-grid
  table="invoices"
  page-size="25"
  editable
  highlight-agent>
</hyphen-data-grid>

Attributes

Attribute	Type	Default	Description
`table`	string	required	The custom table name to display
`page-size`	number	`20`	Rows per page
`editable`	flag	off	Allow inline row editing (double-click a cell to edit)
`highlight-agent`	flag	off	Highlight rows last modified by an AI agent

Events

Event	Data	When
`table:updated`	`{ table, rowId, changes }`	A row is created or modified

Inline Editing

When editable is set, users can double-click any cell to edit its value:

Enter saves the change
Escape cancels the edit
Blur (clicking away) saves automatically

Edits are sent as PATCH requests to the gateway, which updates the custom table and logs the change in the audit trail. The authenticated user's identity is attached to every edit.

Status Pill Detection

The data grid automatically detects status columns (by column name or known value patterns) and renders values as colored pills:

Status	Color
`paid`, `completed`, `approved`	Green
`pending`, `processing`, `in_progress`	Amber
`overdue`, `failed`, `rejected`	Red

`<hyphen-doc-feed>`

A document management surface with upload capabilities. Shows existing documents for the configured workflow, their processing status, and provides a compact upload bar for new files.

html

<hyphen-doc-feed
  workflow-id="wf_invoice_processing"
  accept=".pdf,.csv,.xlsx"
  max-size="52428800"
  multiple>
</hyphen-doc-feed>

Attributes

Attribute	Type	Default	Description
`workflow-id`	string	--	Workflow to trigger on upload
`accept`	string	`*`	Accepted file types (MIME or extensions)
`max-size`	bytes	`52428800`	Max file size (default 50 MB)
`multiple`	flag	on	Allow multiple files

Events

Event	Data	When
`run:status`	`{ runId, status, documentId }`	A triggered workflow run changes status

How It Works

User uploads a file via the upload bar
The SDK sends the file to the document storage API
If workflow-id is set, the SDK triggers the workflow with the document reference as input
The feed shows the document's processing status in real time (queued, processing, completed, failed)

Documents display with file type icons (PDF, CSV, XLSX) and their trigger status. Each document links to its associated workflow run.

`<hyphen-auth-modal>`

An OTP-based login modal for pre-registered team members. Handles the full email + 8-digit code verification flow.

html

<script>
  // Show the login modal
  sdk.login();
</script>

The auth modal is not placed in HTML directly — it's triggered programmatically via sdk.login(). The modal renders as a fullscreen overlay with three steps:

Email entry — user enters their registered email address
OTP verification — user enters the 8-digit code sent to their email
Success confirmation — brief confirmation before the modal auto-closes

Events

Event	Data	When
`authenticated`	`{ email, sessionId }`	OTP verification succeeds (bubbles, composed)

Session Upgrade

On successful authentication, the SDK upgrades the session from anonymous to authenticated. All components automatically reflect user-level permissions — the task sidebar may show additional tasks, and the data grid may enable editing that was previously restricted.

Users must be pre-registered. The SDK does not support self-registration. An org admin must add users to the publishable key's allowed user list before they can authenticate.

---

Combining Components

Components work together through the SDK's event system. When a document is uploaded via <hyphen-doc-feed>, the triggered workflow may create approval tasks that appear in <hyphen-task-sidebar>. Approved tasks may update rows in <hyphen-data-grid>.

html

<div style="display: flex; height: 100vh;">
  <hyphen-task-sidebar auto-refresh show-urgency
    style="width: 360px;">
  </hyphen-task-sidebar>

  <div style="flex: 1; padding: 24px;">
    <hyphen-data-grid table="invoices" editable>
    </hyphen-data-grid>

    <hyphen-doc-feed workflow-id="wf_invoice_processing"
      accept=".csv,.pdf" style="margin-top: 24px;">
    </hyphen-doc-feed>
  </div>
</div>

All components share the same SDK instance and session. Events from one component are visible to others via sdk.on().