Files
orca/resources/plugins/declarative/orca-components-data.d.ts
T
Neil 8503ecda71 plugins: check runs the worker and scenarios; RelativeTime (#37047)
- orca plugin check mounts the plugin's worker (main) on the same mock host
  as each panel, so plugin.request reaches its orca.panels.handle handlers
  as in Orca; a worker that fails to activate or deactivate is an issue
  named after its file. In orca/testing, a worker mounted on a host answers
  that host's panel requests unless `requests` stubs the name.
- Check scenarios: <entry>.check.ts (e.g. src/panel.check.ts) exports
  defineCheck({ name: { ...mockHost options, persisted, theme, events } });
  check renders the panel once per scenario and labels each result.
- RelativeTime (catalog 3, since 1.4.247) and { type: 'relative', at } Table
  cells: Orca ticks them (each second under a minute, then less often), so
  plugins never poll. Inline inside Text; test kit reads them as drawn.
- Typings, docs, skill guide, generated references; gallery shows it.
2026-11-01 06:56:19 -08:00

118 lines
4.5 KiB
TypeScript

// Orca components panel catalog 2 (since Orca 1.4.247): data and content components. Part of the
// `orca` module with orca.d.ts, orca-components.d.ts and orca-components-layout.d.ts.
declare module 'orca' {
import type { IconName, Leaf, MaxHeight, OrcaComponent, Tone } from 'orca'
export type TableColumn = {
/** Names the cell in each row's `cells`. */
key: string
label: string
align?: 'start' | 'center' | 'end'
width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg'
sortable?: boolean
}
/** How a relative time reads: `long` "5 minutes ago", `short` "5m ago", `duration` "5m". */
export type RelativeTimeFormat = 'long' | 'short' | 'duration'
/** A cell Orca keeps current, e.g. `{ type: 'relative', at: agent.stateStartedAt }`. */
export type RelativeTimeCell = { type: 'relative'; at: number; format?: RelativeTimeFormat }
export type TableCell = string | number | boolean | null | RelativeTimeCell
export type TableRow = { key: string; cells: Record<string, TableCell>; disabled?: boolean }
export type TableSort = { column: string; direction: 'asc' | 'desc' }
/**
* Rows scroll inside the table and only those in view are drawn. Sorting is yours: Orca
* reports `onSortChange` and draws the rows in the order you give. With `hasMore`, scrolling
* near the last row calls `onLoadMore` once per length of `rows`.
*/
export type TableProps = Leaf & {
label: string
columns: readonly TableColumn[]
rows: readonly TableRow[]
sort?: TableSort
selectionMode?: 'none' | 'single' | 'multiple'
selected?: readonly string[]
defaultSelected?: readonly string[]
hasMore?: boolean
loading?: boolean
emptyText?: string
maxHeight?: MaxHeight
onSortChange?: (sort: TableSort) => void
onSelectionChange?: (selection: { keys: string[] }) => void
/** Enter or a double click on a row. */
onRowAction?: (row: { key: string }) => void
onLoadMore?: () => void
}
export type TreeItem = {
key: string
label: string
description?: string
icon?: IconName
disabled?: boolean
/** Children exist but are not loaded: expanding shows a loading row and calls `onToggle`. */
hasChildren?: boolean
children?: readonly TreeItem[]
}
/** Arrow keys move, expand and collapse; Enter calls `onAction`. Keys are unique across levels. */
export type TreeProps = Leaf & {
label: string
items: readonly TreeItem[]
selected?: string
defaultSelected?: string
/**
* Open items, when the plugin keeps them (update it from `onToggle`). Orca's own record is lost
* when the Tree unmounts, for example on a tab switch.
*/
expanded?: readonly string[]
defaultExpanded?: readonly string[]
maxHeight?: MaxHeight
onSelect?: (item: { key: string }) => void
onToggle?: (item: { key: string; expanded: boolean }) => void
onAction?: (item: { key: string }) => void
}
/** GitHub-flavoured Markdown, sanitized. Links open like `Link`; images must be plugin files. */
export type MarkdownProps = Leaf & { content: string }
/** Read-only code, highlighted when Orca knows `language` (built in or from a syntax plugin). */
export type CodeViewProps = Leaf & {
code: string
language?: string
label?: string
lineNumbers?: boolean
wrap?: boolean
maxHeight?: MaxHeight
}
/** An image file in the plugin (`assets/logo.png`); never a URL. `alt: ''` for decoration. */
export type ImageProps = Leaf & {
src: string
alt: string
size?: 'xs' | 'sm' | 'md' | 'lg' | 'full'
fit?: 'contain' | 'cover'
rounded?: boolean
}
export type KeyValueItem = {
label: string
value: string | number | boolean | null
tone?: Tone
code?: boolean
}
export type KeyValueProps = Leaf & { label?: string; items: readonly KeyValueItem[] }
/**
* Since 1.4.247 (`ui.catalog` 3): a time Orca keeps current ("5m ago") with no polling. Inline:
* it may sit inside `Text`.
*/
export type RelativeTimeProps = Leaf & {
/** Milliseconds since the epoch, e.g. `Date.now()` or an agent's `stateStartedAt`. */
at: number
format?: RelativeTimeFormat
tone?: Tone
muted?: boolean
}
export const RelativeTime: OrcaComponent<RelativeTimeProps>
export const Table: OrcaComponent<TableProps>
export const Tree: OrcaComponent<TreeProps>
export const Markdown: OrcaComponent<MarkdownProps>
export const CodeView: OrcaComponent<CodeViewProps>
export const Image: OrcaComponent<ImageProps>
export const KeyValue: OrcaComponent<KeyValueProps>
}