mirror of
https://github.com/stablyai/orca.git
synced 2026-11-18 11:54:46 +00:00
docs(plugins): add a rich-editor recipe and list frame theme variables in the skill (#37306)
recipes.md gains "A rich editor with a library" beside the hooks and status bar recipes: an isolated-frame custom editor that vendors its library behind an import map, syncs through orca.document.session with a merge by id, and tests that sync with mockEditorHost. host-api.md lists every --orca-* frame variable and what it paints, generated from the frame token allowlist.
This commit is contained in:
@@ -43,7 +43,8 @@ function loadSources() {
|
||||
schema: 'src/shared/plugins/manifest/plugin-json-schema.ts',
|
||||
fieldDocs: 'src/shared/plugins/manifest/plugin-schema-field-docs.ts',
|
||||
cli: 'src/cli/specs/plugin.ts',
|
||||
cliView: 'src/cli/specs/plugin-view.ts'
|
||||
cliView: 'src/cli/specs/plugin-view.ts',
|
||||
themeTokens: 'src/shared/plugins/artifacts/plugin-theme-token-reference-doc.ts'
|
||||
})
|
||||
}
|
||||
|
||||
@@ -248,6 +249,18 @@ function renderHostApi(sources, { frame, worker }) {
|
||||
.map((m) => bullet({ ...m, text: `document.${m.text}` })),
|
||||
''
|
||||
],
|
||||
[
|
||||
'## Theme variables in frames',
|
||||
'',
|
||||
"HTML panels and custom editors get these CSS variables from Orca's active theme, plus a `light` or `dark` class on `<html>`. A theme change updates them in place and emits `theme` (`orca.on('theme', ...)`); the frame is not reloaded. Style from them, not fixed colours.",
|
||||
'',
|
||||
...sources.themeTokens.pluginFrameThemeVariables().map(({ variable, paints }) => {
|
||||
// Name the frame's own variables, not the app theme tokens behind them.
|
||||
const role = paints.replace(/`--([\w-]+)`/g, '`--orca-$1`')
|
||||
return `- ${code(variable)}${role ? `: ${role}` : ''}`
|
||||
}),
|
||||
''
|
||||
],
|
||||
['## Methods', '', ...methods, ''],
|
||||
[
|
||||
'## Hooks',
|
||||
|
||||
@@ -121,13 +121,13 @@ fingerprint Orca did not give you. New capabilities or changed commands print a
|
||||
Run `ORCA skills get orca-plugin-authoring --reference references/<file>.md` and read only what you
|
||||
need (`--references` lists them; `--full` if `--reference` is rejected).
|
||||
|
||||
| Read when | Reference |
|
||||
| -------------------------------------------------------------------- | -------------------------- |
|
||||
| Reading `dev watch` events; shots, `open`, `dev emit`; test examples | `references/workflow.md` |
|
||||
| The full test kit: `mount`, `mountWorker`, `mockHost`, every act | `references/testing.md` |
|
||||
| A worker panel, storage, settings; agent status; events; hooks | `references/recipes.md` |
|
||||
| Writing a components panel: components, props, atoms, `host` | `references/components.md` |
|
||||
| Calling the host from a worker, frame or panel; capabilities | `references/host-api.md` |
|
||||
| Subscribing to worker, frame or panel events and their payloads | `references/events.md` |
|
||||
| Writing or fixing `orca-plugin.json`, choosing `engines.orca` | `references/manifest.md` |
|
||||
| Running any `ORCA plugin` command you have not used in this task | `references/cli.md` |
|
||||
| Read when | Reference |
|
||||
| ------------------------------------------------------------------------------------ | -------------------------- |
|
||||
| Reading `dev watch` events; shots, `open`, `dev emit`; test examples | `references/workflow.md` |
|
||||
| The full test kit: `mount`, `mountWorker`, `mockHost`, every act | `references/testing.md` |
|
||||
| A worker panel, storage, settings; agent status; events; hooks; a rich custom editor | `references/recipes.md` |
|
||||
| Writing a components panel: components, props, atoms, `host` | `references/components.md` |
|
||||
| Calling the host from a worker, frame or panel; capabilities | `references/host-api.md` |
|
||||
| Subscribing to worker, frame or panel events and their payloads | `references/events.md` |
|
||||
| Writing or fixing `orca-plugin.json`, choosing `engines.orca` | `references/manifest.md` |
|
||||
| Running any `ORCA plugin` command you have not used in this task | `references/cli.md` |
|
||||
|
||||
@@ -42,6 +42,31 @@ Host API 1.2 (`"pluginApi": 1`). Call `host.call(method, params, { signal })`; a
|
||||
- `document.applyEdit(edit: EditorEdit)`: Rejects with `conflict`, `too_large` or `not_permitted` (read-only).
|
||||
- `document.session(options?: EditorSessionOptions<T>)`: Document sync in one call; resolves once theme, locale and the first document are in.
|
||||
|
||||
## Theme variables in frames
|
||||
|
||||
HTML panels and custom editors get these CSS variables from Orca's active theme, plus a `light` or `dark` class on `<html>`. A theme change updates them in place and emits `theme` (`orca.on('theme', ...)`); the frame is not reloaded. Style from them, not fixed colours.
|
||||
|
||||
- `--orca-background`: App canvas
|
||||
- `--orca-foreground`: Body text
|
||||
- `--orca-card`: Cards and panels
|
||||
- `--orca-card-foreground`: Text on `--orca-card`
|
||||
- `--orca-popover`: Menus, popovers and dialogs
|
||||
- `--orca-popover-foreground`: Text on `--orca-popover`
|
||||
- `--orca-primary`: Primary buttons
|
||||
- `--orca-primary-foreground`: Text on `--orca-primary`
|
||||
- `--orca-secondary`: Secondary buttons
|
||||
- `--orca-secondary-foreground`: Text on `--orca-secondary`
|
||||
- `--orca-muted`: Quiet fills
|
||||
- `--orca-muted-foreground`: Secondary text
|
||||
- `--orca-accent`: Hover and selected fills
|
||||
- `--orca-accent-foreground`: Text on `--orca-accent`
|
||||
- `--orca-destructive`
|
||||
- `--orca-destructive-foreground`
|
||||
- `--orca-border`: Borders and separators
|
||||
- `--orca-input`: Input borders
|
||||
- `--orca-ring`: Focus rings
|
||||
- `--orca-radius`: Corner radius of cards and controls
|
||||
|
||||
## Methods
|
||||
|
||||
- `workspace.readContext` (capability `workspace:read`; worker, panel, editor; since 1.0): Branch, name and terminal ids of the focused workspace, or null when none is focused.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Plugin recipes: panels, workers and data
|
||||
# Plugin recipes: panels, workers, editors and data
|
||||
|
||||
Hand-written companion to the `orca-plugin-authoring` guide.
|
||||
|
||||
@@ -98,3 +98,43 @@ let the action through, so count blocks after deciding (`void orca.host.call(...
|
||||
`(await mountWorker(worker)).hooks.fire('terminal.send', event)`, which returns
|
||||
`{ kind: 'continue', event }` or `{ kind: 'deny', reason }`; against the loaded dev plugin,
|
||||
`ORCA plugin dev hook . terminal.send --data '<json>'` prints the same decision.
|
||||
|
||||
## A rich editor with a library
|
||||
|
||||
A `sandboxed-ui` custom editor around a canvas or diagram library; start from
|
||||
`ORCA plugin create <dir> --template editor`. Set `"frame": "isolated"` on the editor
|
||||
(`engines.orca` `>=1.4.248`) so browser clients open the file in Source instead of a fallback.
|
||||
There is no bundler or network: copy the library's ESM build into the plugin and map it,
|
||||
`<script type="importmap">{ "imports": { "lib": "./vendor/lib.js" } }</script>` (16 MiB a script,
|
||||
1 MiB a `.ts` file; no `eval`). Style from the `--orca-*` variables in `references/host-api.md`
|
||||
and redo it on `orca.on('theme', ...)`. Orca keeps no undo for editors: the library's own undo
|
||||
gets Cmd/Ctrl+Z.
|
||||
|
||||
```ts
|
||||
// editor/sync.ts: the only code that talks to Orca; merge by id, never by array position.
|
||||
export const start = () =>
|
||||
orca.document.session<Scene>({
|
||||
decode: (content) => (content.kind === 'text' ? JSON.parse(content.text) : { elements: [] }),
|
||||
encode: (scene) => ({ kind: 'text', text: JSON.stringify(scene) }),
|
||||
merge: (base, outside, mine) => mergeById(base, outside, mine)
|
||||
})
|
||||
// editor/main.ts: `const doc = await start()`, then library.load(doc.value),
|
||||
// library.onChange((scene) => doc.change(scene)), doc.onReplace((scene) => library.load(scene)).
|
||||
|
||||
// editor/sync.test.ts, run by `ORCA plugin test`:
|
||||
import { assert, mockEditorHost, test } from 'orca/testing'
|
||||
test('merges an agent write that lands while an edit waits', async () => {
|
||||
const host = mockEditorHost({ text: '{"elements":[]}' })
|
||||
const doc = await (await import('./sync.ts')).start()
|
||||
doc.change({ elements: [{ id: 'b' }] })
|
||||
host.replace('{"elements":[{"id":"a"}]}') // the agent writes first
|
||||
await host.flush() // as a save: conflict, merge, resend
|
||||
assert.deepEqual(JSON.parse(host.text ?? '').elements, [{ id: 'a' }, { id: 'b' }])
|
||||
doc.dispose()
|
||||
host.dispose()
|
||||
})
|
||||
```
|
||||
|
||||
Without `merge` an outside write wins and the draft is dropped. `ORCA plugin check <dir> --json`
|
||||
then reads every file the entry loads without running it, and
|
||||
`ORCA plugin open <plugin-key> --editor <file>` shows it on a real file.
|
||||
|
||||
@@ -2686,16 +2686,16 @@ const ORCA_PLUGIN_AUTHORING_MARKDOWN = [
|
||||
"Run `ORCA skills get orca-plugin-authoring --reference references/<file>.md` and read only what you",
|
||||
"need (`--references` lists them; `--full` if `--reference` is rejected).",
|
||||
"",
|
||||
"| Read when | Reference |",
|
||||
"| -------------------------------------------------------------------- | -------------------------- |",
|
||||
"| Reading `dev watch` events; shots, `open`, `dev emit`; test examples | `references/workflow.md` |",
|
||||
"| The full test kit: `mount`, `mountWorker`, `mockHost`, every act | `references/testing.md` |",
|
||||
"| A worker panel, storage, settings; agent status; events; hooks | `references/recipes.md` |",
|
||||
"| Writing a components panel: components, props, atoms, `host` | `references/components.md` |",
|
||||
"| Calling the host from a worker, frame or panel; capabilities | `references/host-api.md` |",
|
||||
"| Subscribing to worker, frame or panel events and their payloads | `references/events.md` |",
|
||||
"| Writing or fixing `orca-plugin.json`, choosing `engines.orca` | `references/manifest.md` |",
|
||||
"| Running any `ORCA plugin` command you have not used in this task | `references/cli.md` |",
|
||||
"| Read when | Reference |",
|
||||
"| ------------------------------------------------------------------------------------ | -------------------------- |",
|
||||
"| Reading `dev watch` events; shots, `open`, `dev emit`; test examples | `references/workflow.md` |",
|
||||
"| The full test kit: `mount`, `mountWorker`, `mockHost`, every act | `references/testing.md` |",
|
||||
"| A worker panel, storage, settings; agent status; events; hooks; a rich custom editor | `references/recipes.md` |",
|
||||
"| Writing a components panel: components, props, atoms, `host` | `references/components.md` |",
|
||||
"| Calling the host from a worker, frame or panel; capabilities | `references/host-api.md` |",
|
||||
"| Subscribing to worker, frame or panel events and their payloads | `references/events.md` |",
|
||||
"| Writing or fixing `orca-plugin.json`, choosing `engines.orca` | `references/manifest.md` |",
|
||||
"| Running any `ORCA plugin` command you have not used in this task | `references/cli.md` |",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
@@ -2921,6 +2921,31 @@ const ORCA_PLUGIN_AUTHORING_HOST_API_REFERENCE_MARKDOWN = [
|
||||
"- `document.applyEdit(edit: EditorEdit)`: Rejects with `conflict`, `too_large` or `not_permitted` (read-only).",
|
||||
"- `document.session(options?: EditorSessionOptions<T>)`: Document sync in one call; resolves once theme, locale and the first document are in.",
|
||||
"",
|
||||
"## Theme variables in frames",
|
||||
"",
|
||||
"HTML panels and custom editors get these CSS variables from Orca's active theme, plus a `light` or `dark` class on `<html>`. A theme change updates them in place and emits `theme` (`orca.on('theme', ...)`); the frame is not reloaded. Style from them, not fixed colours.",
|
||||
"",
|
||||
"- `--orca-background`: App canvas",
|
||||
"- `--orca-foreground`: Body text",
|
||||
"- `--orca-card`: Cards and panels",
|
||||
"- `--orca-card-foreground`: Text on `--orca-card`",
|
||||
"- `--orca-popover`: Menus, popovers and dialogs",
|
||||
"- `--orca-popover-foreground`: Text on `--orca-popover`",
|
||||
"- `--orca-primary`: Primary buttons",
|
||||
"- `--orca-primary-foreground`: Text on `--orca-primary`",
|
||||
"- `--orca-secondary`: Secondary buttons",
|
||||
"- `--orca-secondary-foreground`: Text on `--orca-secondary`",
|
||||
"- `--orca-muted`: Quiet fills",
|
||||
"- `--orca-muted-foreground`: Secondary text",
|
||||
"- `--orca-accent`: Hover and selected fills",
|
||||
"- `--orca-accent-foreground`: Text on `--orca-accent`",
|
||||
"- `--orca-destructive`",
|
||||
"- `--orca-destructive-foreground`",
|
||||
"- `--orca-border`: Borders and separators",
|
||||
"- `--orca-input`: Input borders",
|
||||
"- `--orca-ring`: Focus rings",
|
||||
"- `--orca-radius`: Corner radius of cards and controls",
|
||||
"",
|
||||
"## Methods",
|
||||
"",
|
||||
"- `workspace.readContext` (capability `workspace:read`; worker, panel, editor; since 1.0): Branch, name and terminal ids of the focused workspace, or null when none is focused.",
|
||||
@@ -3211,7 +3236,7 @@ const ORCA_PLUGIN_AUTHORING_MANIFEST_REFERENCE_MARKDOWN = [
|
||||
|
||||
// oxfmt-ignore
|
||||
const ORCA_PLUGIN_AUTHORING_RECIPES_REFERENCE_MARKDOWN = [
|
||||
"# Plugin recipes: panels, workers and data",
|
||||
"# Plugin recipes: panels, workers, editors and data",
|
||||
"",
|
||||
"Hand-written companion to the `orca-plugin-authoring` guide.",
|
||||
"",
|
||||
@@ -3312,6 +3337,46 @@ const ORCA_PLUGIN_AUTHORING_RECIPES_REFERENCE_MARKDOWN = [
|
||||
"`{ kind: 'continue', event }` or `{ kind: 'deny', reason }`; against the loaded dev plugin,",
|
||||
"`ORCA plugin dev hook . terminal.send --data '<json>'` prints the same decision.",
|
||||
"",
|
||||
"## A rich editor with a library",
|
||||
"",
|
||||
"A `sandboxed-ui` custom editor around a canvas or diagram library; start from",
|
||||
"`ORCA plugin create <dir> --template editor`. Set `\"frame\": \"isolated\"` on the editor",
|
||||
"(`engines.orca` `>=1.4.248`) so browser clients open the file in Source instead of a fallback.",
|
||||
"There is no bundler or network: copy the library's ESM build into the plugin and map it,",
|
||||
"`<script type=\"importmap\">{ \"imports\": { \"lib\": \"./vendor/lib.js\" } }</script>` (16 MiB a script,",
|
||||
"1 MiB a `.ts` file; no `eval`). Style from the `--orca-*` variables in `references/host-api.md`",
|
||||
"and redo it on `orca.on('theme', ...)`. Orca keeps no undo for editors: the library's own undo",
|
||||
"gets Cmd/Ctrl+Z.",
|
||||
"",
|
||||
"```ts",
|
||||
"// editor/sync.ts: the only code that talks to Orca; merge by id, never by array position.",
|
||||
"export const start = () =>",
|
||||
" orca.document.session<Scene>({",
|
||||
" decode: (content) => (content.kind === 'text' ? JSON.parse(content.text) : { elements: [] }),",
|
||||
" encode: (scene) => ({ kind: 'text', text: JSON.stringify(scene) }),",
|
||||
" merge: (base, outside, mine) => mergeById(base, outside, mine)",
|
||||
" })",
|
||||
"// editor/main.ts: `const doc = await start()`, then library.load(doc.value),",
|
||||
"// library.onChange((scene) => doc.change(scene)), doc.onReplace((scene) => library.load(scene)).",
|
||||
"",
|
||||
"// editor/sync.test.ts, run by `ORCA plugin test`:",
|
||||
"import { assert, mockEditorHost, test } from 'orca/testing'",
|
||||
"test('merges an agent write that lands while an edit waits', async () => {",
|
||||
" const host = mockEditorHost({ text: '{\"elements\":[]}' })",
|
||||
" const doc = await (await import('./sync.ts')).start()",
|
||||
" doc.change({ elements: [{ id: 'b' }] })",
|
||||
" host.replace('{\"elements\":[{\"id\":\"a\"}]}') // the agent writes first",
|
||||
" await host.flush() // as a save: conflict, merge, resend",
|
||||
" assert.deepEqual(JSON.parse(host.text ?? '').elements, [{ id: 'a' }, { id: 'b' }])",
|
||||
" doc.dispose()",
|
||||
" host.dispose()",
|
||||
"})",
|
||||
"```",
|
||||
"",
|
||||
"Without `merge` an outside write wins and the draft is dropped. `ORCA plugin check <dir> --json`",
|
||||
"then reads every file the entry loads without running it, and",
|
||||
"`ORCA plugin open <plugin-key> --editor <file>` shows it on a real file.",
|
||||
"",
|
||||
].join('\n')
|
||||
|
||||
// oxfmt-ignore
|
||||
|
||||
@@ -122,6 +122,22 @@ function omittedValue(token: PluginAppThemeToken): string {
|
||||
return light === dark ? light : `light: ${light}; dark: ${dark}`
|
||||
}
|
||||
|
||||
const APP_THEME_TOKENS: ReadonlySet<string> = new Set(PLUGIN_APP_THEME_TOKENS)
|
||||
const isAppThemeToken = (token: string): token is PluginAppThemeToken => APP_THEME_TOKENS.has(token)
|
||||
// Frame variables that are not colours of an app theme.
|
||||
const FRAME_ONLY_ROLES: Record<string, string> = {
|
||||
'--radius': 'Corner radius of cards and controls'
|
||||
}
|
||||
|
||||
/** The `--orca-*` CSS variables panel and editor frames get, with what each paints. */
|
||||
export function pluginFrameThemeVariables(): { variable: string; token: string; paints: string }[] {
|
||||
return PANEL_DESIGN_TOKEN_ALLOWLIST.map((token) => ({
|
||||
variable: `--orca-${token.slice(2)}`,
|
||||
token,
|
||||
paints: isAppThemeToken(token) ? TOKEN_ROLES[token] : (FRAME_ONLY_ROLES[token] ?? '')
|
||||
}))
|
||||
}
|
||||
|
||||
/** Colour token list for theme authors, rendered from the public token set. */
|
||||
export function renderPluginThemeTokenReference(): string {
|
||||
const lines = [
|
||||
@@ -144,8 +160,8 @@ export function renderPluginThemeTokenReference(): string {
|
||||
'',
|
||||
'| Variable | Orca token |',
|
||||
'| --- | --- |',
|
||||
...PANEL_DESIGN_TOKEN_ALLOWLIST.map(
|
||||
(token) => `| \`--orca-${token.slice(2)}\` | \`${token}\` |`
|
||||
...pluginFrameThemeVariables().map(
|
||||
({ variable, token }) => `| \`${variable}\` | \`${token}\` |`
|
||||
)
|
||||
]
|
||||
return `${lines.join('\n')}\n`
|
||||
|
||||
Reference in New Issue
Block a user