Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 35 additions & 1 deletion docs/reference/plugin-declarative-ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,7 @@ components panel against `mockHost()` and reports what the panel threw (with `fi
Orca would refuse, props it would drop, and host calls Orca would refuse (a warning even when the
panel caught the error). Repeated identical issues are reported once. Each result says what the
panel drew in a few lines (`summary`: headings, callouts, empty states, table and tree sizes, the
selected tab, loading placeholders, danger or warning text), and `--json` adds the whole drawn
selected tab, loading placeholders, danger or warning text and boxes), and `--json` adds the whole drawn
`tree`, so a scenario can be read without opening Orca. When the plugin has a worker
(`main`), check mounts it on the same host first, so the panel's `plugin.request` reaches its
`orca.panels.handle` handlers as in Orca; a worker that fails to activate is reported as an issue
Expand Down Expand Up @@ -397,6 +397,40 @@ Table cells (`ui.has('RelativeTime')`).
| `Skeleton` | `shape` (`text` `block` `circle`), `lines` (1–10, for `text`), `label` (its screen-reader name; default "Loading") | none |
| `RelativeTime` | `at` (required: ms since the epoch), `format` (`short` "5m ago", `long` "5 minutes ago", `duration` "5m"), `tone`, `muted`; Orca re-renders it as time passes, so the plugin never polls. Catalog 3; may sit inside `Text` | none |

### Added in Orca 1.4.248 (`ui.catalog` 4)

Check `ui.has('Box')` (or `ui.catalog >= 4`) when your `engines.orca` minimum is older.

| Component | Props | Children |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `Box` | `direction` (`column` default, `row`), `gap` `padding` `paddingX` `paddingY` `margin` (the gap scale), `align`, `justify` (`start` `center` `end` `between`), `wrap`, `grow`, `shrink`, `width` `height` `minWidth` `minHeight` `maxWidth` `maxHeight` (pixels 0–4096, or a whole percent such as `'50%'`), `columns` (1–6 equal grid columns), `scroll` (`x` `y` `both`), `border` (`true` or a tone), `radius` (`none` `sm` `md` `lg` `full`), `background` (`none` `muted` `card` or a tone's tint) | any |

**Box** is the general container for layouts the others don't cover, without raw elements or CSS: it
has no colours, fonts or styles of its own beyond theme surfaces and tones, so it follows light and
dark themes. `paddingX` and `paddingY` override `padding` on their sides. Unset, a column fills the
width (buttons keep theirs) and a row centres its children, as `Stack` and `Row` do. An invalid prop,
such as a hex colour, `'50px'` or `'120%'`, is dropped with a warning like any other.

```tsx
<Box
direction="row"
gap="md"
padding="sm"
border
radius="md"
background="muted"
width="50%"
minHeight={120}
align="center"
justify="between"
wrap
scroll="y"
>
<Text>Deploys</Text>
<Badge tone="success">Healthy</Badge>
</Box>
```

`maxHeight` (`sm` `md` `lg` `none`) gives long content its own scroll area: a `Table` and a `CodeView`
default to `md`, a `Tree` to `none`.

Expand Down
5 changes: 3 additions & 2 deletions examples/plugins/components-gallery/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@

One build-less TSX panel that uses every component in the components catalog: form controls
(`Textarea`, `Checkbox`, `RadioGroup`, `Slider`, `Field`), layout (`Tabs`, `Collapsible`, `Toolbar`,
`Grid`, tooltips), a paged and sortable `Table`, a lazily loaded `Tree`, `Markdown`, `CodeView`, a
plugin `Image`, `KeyValue`, `Callout` and `Skeleton`. It needs Orca 1.4.247 or newer.
`Grid`, `Box`, tooltips), a paged and sortable `Table`, a lazily loaded `Tree`, `Markdown`, `CodeView`, a
plugin `Image`, `KeyValue`, `Callout` and `Skeleton`. It needs Orca 1.4.248 or newer
(`Box` is catalog 4).

```sh
orca plugin dev load . # also writes .orca/types, the typings tsconfig.json extends
Expand Down
6 changes: 3 additions & 3 deletions examples/plugins/components-gallery/orca-plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
"execution": "sandboxed-ui",
"id": "components-gallery",
"name": "Components Gallery",
"version": "1.0.0",
"description": "Every components panel component in one build-less TSX panel: forms, layout, a paged Table, a lazy Tree, Markdown, code and images.",
"engines": { "orca": ">=1.4.247" },
"version": "1.1.0",
"description": "Every components panel component in one build-less TSX panel: forms, layout with Box, a paged Table, a lazy Tree, Markdown, code and images.",
"engines": { "orca": ">=1.4.248" },
"pluginApi": 1,
"contributes": {
"panels": [
Expand Down
75 changes: 75 additions & 0 deletions examples/plugins/components-gallery/src/layout.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
import { Badge, Box, Button, Heading, Text } from 'orca'

const SERVICES = [
{ name: 'api', state: 'Healthy', tone: 'success' },
{ name: 'worker', state: 'Degraded', tone: 'warning' },
{ name: 'billing', state: 'Down', tone: 'danger' }
] as const

// Box needs Orca 1.4.248 (ui.catalog 4), hence this plugin's engines floor.
export function LayoutTab() {
return (
<Box gap="md">
<Box
direction="row"
gap="sm"
padding="sm"
border
radius="md"
background="muted"
align="center"
justify="between"
>
<Heading level={3}>Services</Heading>
<Button size="sm" variant="outline" icon="refresh">
Refresh
</Button>
</Box>
<Box columns={3} gap="sm">
{SERVICES.map((service) => (
<Box
key={service.name}
gap="xs"
padding="sm"
border={service.tone}
radius="md"
background={service.tone}
>
<Text weight="semibold">{service.name}</Text>
<Badge tone={service.tone}>{service.state}</Badge>
</Box>
))}
</Box>
<Box direction="row" gap="sm" wrap>
<Box
width="50%"
minHeight={96}
padding="sm"
border
radius="md"
background="card"
scroll="y"
maxHeight={120}
>
<Text muted size="xs">
Half the width, at least 96px tall, and scrolls past 120px.
</Text>
{[
'Deploy started',
'Migrations ran',
'Health checks passed',
'Traffic shifted',
'Old pods drained'
].map((line) => (
<Text key={line} size="sm">
{line}
</Text>
))}
</Box>
<Box grow padding="sm" border="accent" radius="md" background="accent" justify="center">
<Text tone="accent">Grows into the rest of the row.</Text>
</Box>
</Box>
</Box>
)
}
9 changes: 9 additions & 0 deletions examples/plugins/components-gallery/src/panel.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -52,3 +52,12 @@ test('draws the content tab without warnings', async () => {
assert.deepEqual(panel.warnings, [])
assert.deepEqual(panel.errors, [])
})

test('lays out the layout tab with Box', async () => {
panel = await mount(gallery, { persisted: { plugin: { 'gallery.tab': 'layout' } } })
const card = panel.find({ type: 'Box', text: /^billing/ })
assert.equal(card?.props.background, 'danger')
assert.ok(panel.find({ role: 'heading', text: 'Services' }))
assert.deepEqual(panel.warnings, [])
assert.deepEqual(panel.errors, [])
})
4 changes: 4 additions & 0 deletions examples/plugins/components-gallery/src/panel.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { atom, read, set, Tab, Tabs } from 'orca'
import { ContentTab } from './content'
import { DataTab } from './data'
import { FormsTab } from './forms'
import { LayoutTab } from './layout'

export const tab = atom('gallery.tab', 'forms', { persist: 'plugin' })

Expand All @@ -18,6 +19,9 @@ export default function Gallery() {
<Tab value="content" label="Content" icon="file-text">
<ContentTab />
</Tab>
<Tab value="layout" label="Layout" icon="layers">
<LayoutTab />
</Tab>
</Tabs>
)
}
45 changes: 42 additions & 3 deletions resources/plugins/declarative/orca-components-layout.d.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
// Orca components panel catalog 2 (since Orca 1.4.247): layout and feedback components. Part of
// the `orca` module with orca.d.ts, orca-components.d.ts and orca-components-data.d.ts.
// Orca components panel catalog 2 (since Orca 1.4.247) and later: layout and feedback components.
// Part of the `orca` module with orca.d.ts, orca-components.d.ts and orca-components-data.d.ts.

declare module 'orca' {
import type { Gap, IconName, Leaf, OrcaComponent, Tone, WithChildren } from 'orca'
import type { Align, Gap, IconName, Leaf, OrcaComponent, Tone, WithChildren } from 'orca'

/** Holds only `Tab`; Orca draws the selected tab's children. */
export type TabsProps = WithChildren & {
Expand Down Expand Up @@ -41,11 +41,50 @@ declare module 'orca' {
label?: string
}

/** Pixels (0 to 4096) or a whole percent of the parent, such as `'50%'`. */
export type BoxLength = number | `${number}%`
/**
* Since 1.4.248 (`ui.catalog` 4): a general layout container that follows the theme. A column
* unless `direction="row"` or `columns` (equal grid columns) is set. Spacing uses the gap scale.
*/
export type BoxProps = WithChildren & {
direction?: 'row' | 'column'
gap?: Gap
padding?: Gap
/** Overrides `padding` left and right. */
paddingX?: Gap
/** Overrides `padding` top and bottom. */
paddingY?: Gap
margin?: Gap
align?: Align
justify?: 'start' | 'center' | 'end' | 'between'
wrap?: boolean
/** Takes the free space in a row or column. */
grow?: boolean
/** `false` keeps its size when space runs out. */
shrink?: boolean
width?: BoxLength
height?: BoxLength
minWidth?: BoxLength
minHeight?: BoxLength
maxWidth?: BoxLength
maxHeight?: BoxLength
columns?: 1 | 2 | 3 | 4 | 5 | 6
/** Scrolls its own content past its size (set `height` or `maxHeight` for `y`). */
scroll?: 'x' | 'y' | 'both'
/** `true` draws the hairline border; a tone colours it. */
border?: boolean | Tone
radius?: 'none' | 'sm' | 'md' | 'lg' | 'full'
/** A theme surface, or a tint of a tone. */
background?: 'none' | 'muted' | 'card' | Tone
}

export const Tabs: OrcaComponent<TabsProps>
export const Tab: OrcaComponent<TabProps>
export const Collapsible: OrcaComponent<CollapsibleProps>
export const Toolbar: OrcaComponent<ToolbarProps>
export const Grid: OrcaComponent<GridProps>
export const Callout: OrcaComponent<CalloutProps>
export const Skeleton: OrcaComponent<SkeletonProps>
export const Box: OrcaComponent<BoxProps>
}
1 change: 1 addition & 0 deletions resources/plugins/declarative/orca-components.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -295,4 +295,5 @@ declare module 'orca' {
| 'Callout'
| 'Skeleton'
| 'RelativeTime'
| 'Box'
}
31 changes: 29 additions & 2 deletions resources/plugins/declarative/orca-runtime.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -376,7 +376,7 @@ var PLUGIN_DECLARATIVE_MESSAGES = {
/** host → guest, `{ document }`: put the atoms back to the last `ui.snapshot`. */
restore: "ui.restore"
};
var PLUGIN_DECLARATIVE_CATALOG_VERSION = 3;
var PLUGIN_DECLARATIVE_CATALOG_VERSION = 4;
var PLUGIN_DECLARATIVE_COMPONENT_PROPS = {
Stack: ["gap", "align"],
Row: ["gap", "align", "justify", "wrap"],
Expand Down Expand Up @@ -497,7 +497,32 @@ var PLUGIN_DECLARATIVE_COMPONENT_PROPS = {
Callout: ["tone", "title", "icon"],
Skeleton: ["shape", "lines", "label"],
// Catalog 3 (also Orca 1.4.247).
RelativeTime: ["at", "format", "tone", "muted"]
RelativeTime: ["at", "format", "tone", "muted"],
// Catalog 4 (Orca 1.4.248).
Box: [
"direction",
"gap",
"padding",
"paddingX",
"paddingY",
"margin",
"align",
"justify",
"wrap",
"grow",
"shrink",
"width",
"height",
"minWidth",
"minHeight",
"maxWidth",
"maxHeight",
"columns",
"scroll",
"border",
"radius",
"background"
]
};
var PLUGIN_DECLARATIVE_VALUE_CONTROLS = {
Input: { value: "value", change: "onChange" },
Expand Down Expand Up @@ -1486,8 +1511,10 @@ var KeyValue = "KeyValue";
var Callout = "Callout";
var Skeleton = "Skeleton";
var RelativeTime = "RelativeTime";
var Box = "Box";
export {
Badge,
Box,
Button,
Callout,
Card,
Expand Down
50 changes: 25 additions & 25 deletions resources/plugins/declarative/orca-testing.mjs

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion resources/plugins/types/orca-testing.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ declare module 'orca/testing' {
/** The drawn tree as plain data, for snapshots; handlers show as `[handler]`. */
tree(): TreeSnapshot | string | null
/** One line per thing a person notices first: headings, callouts, empty states, table and
* tree sizes, the selected tab, loading placeholders, danger or warning text. */
* tree sizes, the selected tab, loading placeholders, danger or warning text and boxes. */
summary(): string[]
/** Each act grants one gesture (a press) and resolves once the panel has settled. */
press(target: Target): Promise<void>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ Everything a components panel (`"ui": "components"`) imports comes from `orca`.
- `Callout` (children: any): `tone?: Tone; title?: string; icon?: IconName`
- `Skeleton` (children: none): `shape?: 'text' | 'block' | 'circle'; lines?: number; label?: string`
- `RelativeTime` (children: none): `at: number; format?: RelativeTimeFormat; tone?: Tone; muted?: boolean`
- `Box` (children: any): `direction?: 'row' | 'column'; gap?: Gap; padding?: Gap; paddingX?: Gap; paddingY?: Gap; margin?: Gap; align?: Align; justify?: 'start' | 'center' | 'end' | 'between'; wrap?: boolean; grow?: boolean; shrink?: boolean; width?: BoxLength; height?: BoxLength; minWidth?: BoxLength; minHeight?: BoxLength; maxWidth?: BoxLength; maxHeight?: BoxLength; columns?: 1 | 2 | 3 | 4 | 5 | 6; scroll?: 'x' | 'y' | 'both'; border?: boolean | Tone; radius?: 'none' | 'sm' | 'md' | 'lg' | 'full'; background?: 'none' | 'muted' | 'card' | Tone`

## Runtime

Expand Down
2 changes: 1 addition & 1 deletion skill-guides/orca-plugin-authoring/references/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
- `find(query: TestQuery)`: The innermost match, or null.
- `findAll(query: TestQuery)`
- `tree()`: The drawn tree as plain data, for snapshots; handlers show as `[handler]`.
- `summary()`: One line per thing a person notices first: headings, callouts, empty states, table and tree sizes, the selected tab, loading placeholders, danger or warning text.
- `summary()`: One line per thing a person notices first: headings, callouts, empty states, table and tree sizes, the selected tab, loading placeholders, danger or warning text and boxes.
- `press(target: Target)`: Each act grants one gesture (a press) and resolves once the panel has settled.
- `type(target: Target, text: string, options?: { replace?: boolean; submit?: boolean })`: Types after what the field holds (`replace` clears it first); `submit` presses Enter.
- `submit(target: Target)`
Expand Down
3 changes: 2 additions & 1 deletion src/cli/bundled-skill-guides.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2792,6 +2792,7 @@ const ORCA_PLUGIN_AUTHORING_COMPONENTS_REFERENCE_MARKDOWN = [
"- `Callout` (children: any): `tone?: Tone; title?: string; icon?: IconName`",
"- `Skeleton` (children: none): `shape?: 'text' | 'block' | 'circle'; lines?: number; label?: string`",
"- `RelativeTime` (children: none): `at: number; format?: RelativeTimeFormat; tone?: Tone; muted?: boolean`",
"- `Box` (children: any): `direction?: 'row' | 'column'; gap?: Gap; padding?: Gap; paddingX?: Gap; paddingY?: Gap; margin?: Gap; align?: Align; justify?: 'start' | 'center' | 'end' | 'between'; wrap?: boolean; grow?: boolean; shrink?: boolean; width?: BoxLength; height?: BoxLength; minWidth?: BoxLength; minHeight?: BoxLength; maxWidth?: BoxLength; maxHeight?: BoxLength; columns?: 1 | 2 | 3 | 4 | 5 | 6; scroll?: 'x' | 'y' | 'both'; border?: boolean | Tone; radius?: 'none' | 'sm' | 'md' | 'lg' | 'full'; background?: 'none' | 'muted' | 'card' | Tone`",
"",
"## Runtime",
"",
Expand Down Expand Up @@ -3462,7 +3463,7 @@ const ORCA_PLUGIN_AUTHORING_TESTING_REFERENCE_MARKDOWN = [
"- `find(query: TestQuery)`: The innermost match, or null.",
"- `findAll(query: TestQuery)`",
"- `tree()`: The drawn tree as plain data, for snapshots; handlers show as `[handler]`.",
"- `summary()`: One line per thing a person notices first: headings, callouts, empty states, table and tree sizes, the selected tab, loading placeholders, danger or warning text.",
"- `summary()`: One line per thing a person notices first: headings, callouts, empty states, table and tree sizes, the selected tab, loading placeholders, danger or warning text and boxes.",
"- `press(target: Target)`: Each act grants one gesture (a press) and resolves once the panel has settled.",
"- `type(target: Target, text: string, options?: { replace?: boolean; submit?: boolean })`: Types after what the field holds (`replace` clears it first); `submit` presses Enter.",
"- `submit(target: Target)`",
Expand Down
Loading
Loading