@type32/vertex-plugin 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -150,7 +150,8 @@
150
150
  }
151
151
 
152
152
  .dark {
153
- --color-submuted: oklch(var(--ui-bg-muted));
153
+
154
+ --color-submuted: color-mix(in oklab, var(--ui-bg) 98%, var(--ui-bg-inverted));
154
155
 
155
156
  --ncm-code-bg: var(--ui-bg-muted);
156
157
  --ncm-code-bg-hover: var(--ui-bg-elevated);
@@ -159,10 +160,6 @@
159
160
  --ncm-text-muted: var(--ui-text-muted);
160
161
  --ncm-text-xmuted: var(--ui-text-muted);
161
162
  --ncm-overlay-bg: rgba(var(--ui-bg), 0.98);
162
-
163
- .bg-submuted {
164
- @apply bg-inverted/2;
165
- }
166
163
  }
167
164
 
168
165
 
@@ -8,6 +8,8 @@ import type { UiSlot } from './contributions';
8
8
  /** One setting: label and description on the left, its control (the default slot) on the right. */
9
9
  export interface SettingsRowProps {
10
10
  label: string;
11
+ /** An Iconify name, drawn before the label (a plugin's row). */
12
+ icon?: string;
11
13
  description?: string;
12
14
  /** Replaces the description, in the error colour. */
13
15
  error?: string;
@@ -253,12 +253,13 @@ export interface ScopedConfig {
253
253
  /** The full setting path of `path` (`plugins.config.<id>.<path>`), for `SettingsRow`'s `setting`. */
254
254
  path(path: string): `plugins.config.${string}`;
255
255
  }
256
- /** A page in the Settings window, at `/settings/<id>/…`, listed in its nav after the kernel's. */
256
+ /** A page in the Settings window, at `/settings/<id>/…`, listed in its nav with its plugin's group. */
257
257
  export interface SettingsPageDef extends UiSlot<SettingsPageProps> {
258
258
  id: string;
259
259
  /** i18n key. */
260
260
  label: string;
261
- icon: string;
261
+ /** Default: its plugin's manifest's `icon`. */
262
+ icon?: string;
262
263
  /** Sub-entries in the nav (`path` below the page); a page with children is a group. */
263
264
  children?: {
264
265
  label: string;
package/dist/vite.js CHANGED
@@ -327,7 +327,7 @@ function vertex(options = {}) {
327
327
  tailwindcss(),
328
328
  {
329
329
  name: "vertex:package",
330
- config: () => ({
330
+ config: (config) => ({
331
331
  define: { "process.env.NODE_ENV": JSON.stringify("production") },
332
332
  build: {
333
333
  lib: {
@@ -336,7 +336,8 @@ function vertex(options = {}) {
336
336
  fileName: () => "main.js",
337
337
  cssFileName: "styles"
338
338
  },
339
- rolldownOptions: { output: { inlineDynamicImports: true } }
339
+ rolldownOptions: { output: { codeSplitting: false } },
340
+ ...config.build?.watch && { watch: { exclude: [`${resolve(config.root ?? process.cwd(), config.build.outDir ?? "dist")}/**`, resolve(config.root ?? process.cwd(), "plugin.zip")] } }
340
341
  }
341
342
  }),
342
343
  configResolved(config) {
package/docs/README.md ADDED
@@ -0,0 +1,24 @@
1
+ # Writing a Vertex plugin
2
+
3
+ A Vertex plugin is a folder: `plugin.json`, one `main.js`, maybe `styles.css`, its strings and its assets. Vertex
4
+ loads it at runtime in its windows, where it adds what it registers: panel views, tabs, file viewers, file types,
5
+ commands, editor syntax and widgets, settings pages. It's written in TypeScript and Vue against this package,
6
+ `@type32/vertex-plugin`, whose types are the contract and whose Vite preset builds the folder.
7
+
8
+ Vertex's own features are plugins on the same contract (Files, Canvas, Bases, Git, Chat…), so what they do, a plugin
9
+ can do.
10
+
11
+ | Page | What's in it |
12
+ | --- | --- |
13
+ | [Start](start.md) | A plugin from an empty folder to a panel running in Vertex; the development loop. |
14
+ | [The package](package.md) | `plugin.json` key by key; what the build makes; dependencies; strings; what can't be done. |
15
+ | [The plugin's context](context.md) | `ctx`, what `setup` gets: every contribution point, with an example. |
16
+ | [The session](session.md) | `session`, what views and `onSession` get: the workspace's index, files, tabs, editors. |
17
+ | [UI](ui.md) | Mounting, Vue and Nuxt UI, Vertex's own components, Tailwind, the theme. |
18
+ | [Config, data, secrets](config.md) | Settings drawn from the manifest, workspace overrides, stored documents, the keychain, the network, permissions. |
19
+ | [Trust](trust.md) | What a user is told and agrees to; a workspace's plugins; trust for programs a plugin runs. |
20
+ | [Publishing](publishing.md) | Releases with `plugin.zip`, a branch of built files, updates, pins. |
21
+ | [Versions](versions.md) | `apiVersion`, `minAppVersion`, this package's versions. |
22
+
23
+ The types say more than these pages: each member is documented where it's declared, so an editor shows it on hover.
24
+ A starting point: [`Type-32/vertex-plugin-template`](https://github.com/Type-32/vertex-plugin-template).
package/docs/config.md ADDED
@@ -0,0 +1,132 @@
1
+ # Config, data, secrets
2
+
3
+ | What | Where it lives | Use it for |
4
+ | --- | --- | --- |
5
+ | [Config](#ctxconfig) | The user's settings, `plugins.config.<id>`; a workspace's `.vertex/settings.json` for what it may override | What the user sets: options, filters, colours. |
6
+ | [Data](#ctxdataglobal-ctxdataworkspace) | A JSON document of the plugin's, for the app or for a workspace | What the plugin keeps: state, caches, per-folder notes. |
7
+ | [Secrets](#ctxsecretsget-ctxsecretsset-ctxsecretsdelete) | The system's keychain | Keys and tokens. |
8
+
9
+ ## Config
10
+
11
+ ### `ctx.config`
12
+
13
+ ```ts
14
+ import {definePlugin} from '@type32/vertex-plugin'
15
+ import {computed} from 'vue'
16
+
17
+ interface Config {
18
+ depth: number
19
+ showTags: boolean
20
+ }
21
+
22
+ export default definePlugin<Config>({
23
+ setup(ctx) {
24
+ const depth = computed(() => ctx.config.value.depth)
25
+ void ctx.config.set({depth: 3})
26
+ },
27
+ })
28
+ ```
29
+
30
+ - `value`: the config in this window, a workspace's overrides applied, every [schema](#the-schema) field checked and
31
+ defaulted. Reactive: it follows the Settings window, other windows and a change of workspace settings.
32
+ - `set(patch, scope)`: writes paths inside the config (`{depth: 3}`, `{'colors.tags': '#f00'}`), `null` removing one.
33
+ `scope` is `global` (default: the user's settings) or `workspace` (this window's workspace, for a path the manifest
34
+ lets it override; anything else is refused).
35
+ - `overridden(path)`: whether this window's workspace overrides the path.
36
+
37
+ ### The schema
38
+
39
+ Settings the Settings window draws from `plugin.json`, without running the plugin: the plugin needs no settings page
40
+ of its own. A field's `default` is the config's default, so `ctx.config.value` has it too.
41
+
42
+ ```json
43
+ "config": {
44
+ "overridable": {"showTags": "workspace", "folder": "trustedWorkspace"},
45
+ "schema": [
46
+ {"key": "depth", "type": "number", "label": "plugins.hello.depth", "description": "plugins.hello.depthHelp", "default": 2, "min": 1, "max": 5},
47
+ {"key": "showTags", "type": "switch", "label": "plugins.hello.showTags", "default": true},
48
+ {"key": "folder", "type": "path", "kind": "folder", "label": "plugins.hello.folder", "default": ""}
49
+ ]
50
+ }
51
+ ```
52
+
53
+ | `type` | Value | Extra keys |
54
+ | --- | --- | --- |
55
+ | `switch` | `true` / `false` | |
56
+ | `text` | a string | `placeholder` |
57
+ | `color` | a CSS colour | `placeholder` |
58
+ | `number` | a number | `min`, `max`, `step` |
59
+ | `select` | one of the options' `value`s | `options: [{value, label}]` (labels are i18n keys) |
60
+ | `list` | a list of strings | `placeholder` |
61
+ | `path` | a workspace-relative path | `kind`: `file` or `folder` (its picker shows while a workspace's settings are edited) |
62
+
63
+ Every field has `key` (a path in the config: `depth`, `colors.tags`), `type`, `label` and `default`; `description`
64
+ is optional. `label`, `description` and options' labels are i18n keys of the plugin's, which `en.json` must have.
65
+
66
+ ### Workspace overrides
67
+
68
+ A workspace can change some of the user's settings for itself, in its `.vertex/settings.json`, which travels with it.
69
+ `overridable` says which of the plugin's paths: `workspace` (any workspace) or `trustedWorkspace` (only once the user
70
+ trusts it: a path a stranger's vault shouldn't set, like a folder the plugin writes to). A path not listed is the
71
+ user's only. Settings shows the overridable ones while a workspace is edited, with Changed in this workspace and Use
72
+ global.
73
+
74
+ On a page of its own, a plugin edits its config through its `config` prop (`ScopedConfig`), which is the scope
75
+ Settings is editing ([a settings page](ui.md#vertexs-components)).
76
+
77
+ ## Data
78
+
79
+ ### `ctx.data.global`, `ctx.data.workspace`
80
+
81
+ A JSON document of the plugin's: `global` in Vertex's data folder, `workspace` in the window's workspace
82
+ (`.vertex/plugins-data/<id>.json`, which travels with it; `undefined` outside a workspace window).
83
+
84
+ ```ts
85
+ const store = ctx.data.workspace
86
+ if (store) {
87
+ const colours = (await store.get() ?? {}) as Record<string, string>
88
+ await store.set({...colours, projects: 'red'})
89
+ store.onChange(value => console.log(value))
90
+ }
91
+ ```
92
+
93
+ `get()` is `undefined` until something is set; `set(value)` replaces the document, atomically; `onChange` runs after
94
+ every write from any window. Keep it small: it's read and written whole.
95
+
96
+ ## Secrets
97
+
98
+ ### `ctx.secrets.get`, `ctx.secrets.set`, `ctx.secrets.delete`
99
+
100
+ Strings in the system's keychain (macOS Keychain, Windows Credential Manager), by name, the plugin's own: Vertex's
101
+ entries are `plugin:<id>:<name>`. `get` is `undefined` for a name with none. Needs the `secrets` permission.
102
+
103
+ ```ts
104
+ await ctx.secrets.set('token', 'abc')
105
+ const token = await ctx.secrets.get('token')
106
+ ```
107
+
108
+ ## The network
109
+
110
+ ### `ctx.http.fetch`
111
+
112
+ One GET from Vertex's native side, outside the webview's CORS rules, with the `Accept` header passed on. Redirects
113
+ come back unfollowed, the body stops past 2 MiB, and addresses on this computer or the local network are refused.
114
+ Needs the `network` permission.
115
+
116
+ ```ts
117
+ const response = await ctx.http.fetch('https://api.example.com/items', {headers: {Accept: 'application/json'}})
118
+ const items = await response.json()
119
+ ```
120
+
121
+ The webview's own `fetch` works too, under the web's rules: only from servers that allow it (CORS).
122
+
123
+ ## Permissions
124
+
125
+ What a plugin may do beyond any window's own, in `plugin.json`'s `permissions`. The install dialog lists them; a call
126
+ the plugin hasn't asked for is refused.
127
+
128
+ | Permission | Grants |
129
+ | --- | --- |
130
+ | `network` | `ctx.http.fetch`. |
131
+ | `secrets` | `ctx.secrets`. |
132
+ | `files-outside-workspace` | Every file on the computer, in each window it runs in. Without it, a window reaches its workspace, the files the user picks in a dialog there, and the clipboard's. |
@@ -0,0 +1,417 @@
1
+ # The plugin's context
2
+
3
+ `main.js` default-exports `definePlugin({setup})`. Vertex calls `setup(ctx)` once in each window the plugin runs in
4
+ (`plugin.json`'s `windows`), with `ctx: PluginContext`.
5
+
6
+ ```ts
7
+ import {definePlugin} from '@type32/vertex-plugin'
8
+
9
+ interface Config {
10
+ depth: number
11
+ }
12
+
13
+ export default definePlugin<Config>({
14
+ setup(ctx) {
15
+ ctx.commands.register({id: 'hello', label: 'plugins.hello.command', run: () => console.log(ctx.config.value.depth)})
16
+ },
17
+ })
18
+ ```
19
+
20
+ - **`setup` is synchronous.** What it registers belongs to the plugin and is removed when the plugin stops; an `await`
21
+ would leave that. Do async work inside what it registers (a command's `run`, `onSession`). A `setup` that throws, or
22
+ returns a promise, fails the plugin: it's stopped and the user is told "{name} couldn't start".
23
+ - **Every registration returns what removes it.** Rarely needed: everything goes when the plugin stops, and what's
24
+ registered in an `onSession` callback goes with the session.
25
+ - **Ids are global.** Panel views and tab kinds are saved in layouts and sessions by id, so start yours with the
26
+ plugin's id (`hello`, `hello-stats`). A command's id is the plugin's own (`<plugin id>:<id>`).
27
+ - **Labels are i18n keys** of the plugin's (`plugins.hello.view`) unless the type says "already translated"
28
+ ([strings](package.md#strings)).
29
+ - **UI** is a `component` (a lazily loaded Vue component that gets the props) or a `mount(el, props)` that draws into
30
+ `el` and returns what undoes it ([UI](ui.md)). Either draws inside an error boundary that names the plugin.
31
+ - `definePlugin<Config>` types [`ctx.config`](config.md#ctxconfig).
32
+
33
+ ## About the plugin and the window
34
+
35
+ ### `ctx.plugin.id`, `ctx.plugin.version`, `ctx.plugin.source`, `ctx.plugin.assetUrl`
36
+
37
+ Its id and version as its manifest says, and `source`: `global` (installed for every workspace), `workspace` (a
38
+ workspace's own) or `core`. `assetUrl(path)` is a URL for a file of the plugin's folder (`logo.svg`, `data/words.json`,
39
+ nothing outside it), for an `<img>`, `fetch` or `import()`; the build puts `public/` at the folder's top.
40
+
41
+ ### `ctx.window.kind`, `ctx.window.label`
42
+
43
+ The window it runs in: `main` (the start page), `session` (a workspace or a single file), `settings`; and the window's
44
+ label, unique among the open windows.
45
+
46
+ ### `ctx.i18n.t`, `ctx.i18n.locale`
47
+
48
+ `t(key, params?)` is a string in the window's language (`t('plugins.hello.count', {n: 3})`), the key itself when
49
+ there's none; `locale` is the language (`en`, `zh-CN`). Both are reactive: a template or a `computed` that reads them
50
+ follows a change of language.
51
+
52
+ ### `ctx.ui.theme.dark`, `ctx.ui.theme.value`
53
+
54
+ The window's theme, for what CSS can't reach (a `<canvas>`, a chart library). `dark` is whether it's dark; `value(name)`
55
+ reads a CSS custom property as the page resolves it now (`value('--ui-primary')`, `value('--ui-text-muted')`). Both
56
+ are reactive: a `watchEffect` that reads them runs again when the user changes light and dark, the colours, or a
57
+ workspace's theme. CSS and Tailwind classes follow the theme by themselves ([styles](ui.md#styles)).
58
+
59
+ ## Commands
60
+
61
+ ### `ctx.commands.register`
62
+
63
+ ```ts
64
+ ctx.commands.register({
65
+ id: 'open-graph',
66
+ label: 'plugins.hello.openGraph',
67
+ icon: 'i-lucide-waypoints',
68
+ accelerator: 'CmdOrCtrl+Shift+G',
69
+ menu: {section: 'view'},
70
+ palette: true,
71
+ enabled: () => true,
72
+ run: () => {},
73
+ })
74
+ ```
75
+
76
+ Registered as `<plugin id>:<id>`. `menu` puts it in the menu bar's section (`app`, `file`, `edit`, `view`, `help`),
77
+ after Vertex's items; `group` (default 100: the end) places it among Vertex's groups. `accelerator` is the menu item's
78
+ shortcut, so it works while the item is in the menu. `palette` lists it in the command palette's Commands. `enabled`
79
+ is asked whenever the menu or the palette is drawn.
80
+
81
+ ### `ctx.commands.paletteGroup`
82
+
83
+ A group of items in the command palette, computed when the palette opens: the open base's commands, each workflow.
84
+
85
+ ```ts
86
+ ctx.commands.paletteGroup({
87
+ id: 'hello-recent',
88
+ label: () => ctx.i18n.t('plugins.hello.recent'),
89
+ items: () => [{id: 'a', label: 'A note', icon: 'i-lucide-file', onSelect: () => {}}],
90
+ order: 40,
91
+ })
92
+ ```
93
+
94
+ `label()` and the items' labels are already translated. Groups sort by `order`: Vertex's Quick actions are 0,
95
+ Commands 10, Files 100; default 50.
96
+
97
+ ## Views
98
+
99
+ ### `ctx.views.panel`
100
+
101
+ A view in a sidebar or the bottom panel.
102
+
103
+ ```ts
104
+ ctx.views.panel({
105
+ id: 'hello',
106
+ label: 'plugins.hello.view',
107
+ icon: 'i-lucide-hand',
108
+ defaultArea: 'right',
109
+ tab: true,
110
+ component: () => import('./View.vue'),
111
+ })
112
+ ```
113
+
114
+ The component gets `PanelViewProps`: `session` (the window's [session](session.md)), `placement` (`panel`, or `tab`
115
+ when it's open in a tab) and `actions(list)`, which sets the buttons in the panel's header (refresh, collapse all):
116
+
117
+ ```ts
118
+ props.actions([{id: 'refresh', label: ctx.i18n.t('plugins.hello.refresh'), icon: 'i-lucide-refresh-cw', onSelect: () => {}}])
119
+ ```
120
+
121
+ - `defaultArea`: where it first goes (`left`, `right`, `bottom`, `hidden`) while the user's layout doesn't place it.
122
+ The user moves it from there.
123
+ - `tab: true`: it may also open in a tab ([`session.views.openInTab`](session.md#sessionviewsshow-sessionviewsopenintab)),
124
+ so it must work mounted twice at once.
125
+ - `when(context)`: whether it can show in this window (`context.isWorkspace`, `context.activeFile`, `context.settings`).
126
+ - `scroll: true` wraps it in the panel's fading scroll area, for a view that doesn't scroll by itself.
127
+ - `search(context)`: what the panel's Search button does while it's shown; `kbds(context)`: a shortcut hint.
128
+ - `action(context)` instead of a component: the view is a button that runs it (Search is one).
129
+
130
+ ### `ctx.views.tabKind`
131
+
132
+ A kind of tab that isn't a file's (a chat, a diff). Its tabs are opened with
133
+ [`session.tabs.open(id, kind)`](session.md#sessiontabsopen-sessiontabsclose-sessiontabsactive-sessiontabslist).
134
+
135
+ ```ts
136
+ ctx.views.tabKind({
137
+ kind: 'hello-report',
138
+ describe: id => ({label: ctx.i18n.t('plugins.hello.report', {id}), icon: 'i-lucide-file-chart-column'}),
139
+ persist: true,
140
+ exists: id => id !== '',
141
+ component: () => import('./Report.vue'),
142
+ })
143
+ ```
144
+
145
+ The component gets `TabProps`: `session` and `id`, the tab's id within the kind. `describe(id)` names the tab in the
146
+ tab bar (already translated), `undefined` when what it shows is gone. `persist` reopens it after a relaunch, once
147
+ `exists(id)` says it still has something to show.
148
+
149
+ ### `ctx.views.fileViewer`
150
+
151
+ What a tab of a file draws, for the extensions it matches.
152
+
153
+ ```ts
154
+ ctx.views.fileViewer({
155
+ id: 'board',
156
+ match: ext => ext === 'board',
157
+ loadsText: true,
158
+ component: () => import('./BoardViewer.vue'),
159
+ })
160
+ ```
161
+
162
+ The component gets `ViewerProps`. With `loadsText`, the tab reads the file as UTF-8 into `modelValue`, and a
163
+ `v-model` update autosaves it (undo, the unsaved dot and reloads on an outside change are the tab's). Without it, the
164
+ viewer reads the file itself, from `assetUrl` or through the session. `fileName` (`v-model:fileName`) is the editable
165
+ title; draw the header, title and status bar with `ViewerLayout` ([UI](ui.md#vertexs-components)), passing its
166
+ `on-rename` to `onRename`. `modes` limits it to `workspace` or `singlespace` windows; the highest `priority` wins when
167
+ several viewers match (default 0; Vertex's code editor, the fallback, is -100).
168
+
169
+ ### `ctx.views.statusItem`
170
+
171
+ Something a viewer shows besides its content: in its status bar (a counter), or over its right edge (`placement:
172
+ 'side'`).
173
+
174
+ ```ts
175
+ ctx.views.statusItem({
176
+ id: 'hello-chars',
177
+ viewers: ['markdown'],
178
+ mount(el, props) {
179
+ el.textContent = `${props.text.length}`
180
+ return () => el.replaceChildren()
181
+ },
182
+ })
183
+ ```
184
+
185
+ It gets `StatusItemProps`: the shown file's `text`, `filePath`, `fileId` and `session`. `viewers` lists the viewers it
186
+ shows for (Vertex's note editor is `markdown`); default every viewer that loads text.
187
+
188
+ ### `ctx.views.overlay`
189
+
190
+ UI drawn once in each session window, over everything (the command palette is one). It gets `{session}`; `when`
191
+ limits it to some windows.
192
+
193
+ ## Files
194
+
195
+ ### `ctx.files.type`
196
+
197
+ A kind of file: its icon in Files, and with `new`, a New item in File → New, Files' menus and the palette.
198
+
199
+ ```ts
200
+ ctx.files.type({
201
+ id: 'board',
202
+ extensions: ['board'],
203
+ icon: 'i-lucide-square-kanban',
204
+ label: 'plugins.board.fileType',
205
+ new: {label: 'plugins.board.new', command: 'plugins.board.newCommand', description: 'plugins.board.newDescription'},
206
+ })
207
+ ```
208
+
209
+ New asks for a name and makes an empty file, so the file's viewer reads empty text as a new one. Pair it with a
210
+ [viewer](#ctxviewsfileviewer) and, when the format holds links, a [link extractor](#ctxindexlinkextractor).
211
+
212
+ ### `ctx.files.menuItem`
213
+
214
+ A group of items in the right-click menu of a file or a selection, at the top.
215
+
216
+ ```ts
217
+ ctx.files.menuItem({
218
+ id: 'hello-count',
219
+ items: ({files}) => [{label: ctx.i18n.t('plugins.hello.count', {n: files.length}), icon: 'i-lucide-hash', onSelect: () => {}}],
220
+ })
221
+ ```
222
+
223
+ ## Settings and the start page
224
+
225
+ ### `ctx.settings.page`
226
+
227
+ A page of the Settings window, at `/settings/<id>`, in the nav under the plugin. The plugin must run in the Settings
228
+ window (`"windows": ["session", "settings"]`). A plugin with only a schema doesn't need one: Settings draws it from
229
+ the manifest ([Config](config.md#the-schema)).
230
+
231
+ ```ts
232
+ ctx.settings.page({
233
+ id: 'hello',
234
+ label: 'plugins.hello.settings',
235
+ component: () => import('./SettingsPage.vue'),
236
+ })
237
+ ```
238
+
239
+ The component gets `SettingsPageProps`: `path` (the route below the page: `/settings/hello/a/b` → `['a', 'b']`) and
240
+ `config` (`ScopedConfig`: the plugin's config in the scope Settings is editing, the user's or a workspace's). Draw it
241
+ with `SettingsScrollLayout`, `SettingsSection` and `SettingsRow` ([UI](ui.md#vertexs-components)) so it looks and
242
+ behaves like Vertex's pages. `children` adds sub-entries to the nav (`{label, icon, path}`); `icon` defaults to the
243
+ manifest's.
244
+
245
+ ### `ctx.settings.open`
246
+
247
+ Opens the Settings window (or brings it forward) at `/settings/<path>`, on the calling window's scope.
248
+
249
+ ### `ctx.home.action`
250
+
251
+ A button on the start page, after New Workspace (Clone Workspace… is one). The plugin must run in the main window
252
+ (`"windows": ["main"]`). `run(home)` gets `home.openWorkspace(path)`.
253
+
254
+ ## The editor
255
+
256
+ What's added to the note editor, Vertex's Markdown editor (CodeMirror 6, `@type32/codemirror-rich-obsidian-editor`).
257
+
258
+ ### `ctx.editor.extension`
259
+
260
+ A CodeMirror extension, in every note editor. `{nested: true}` puts it also in the editors inside callouts, table
261
+ cells and canvas cards.
262
+
263
+ ```ts
264
+ import {EditorView} from '@codemirror/view'
265
+
266
+ const theme = EditorView.theme({'.cm-line': {letterSpacing: '0.01em'}})
267
+ ctx.editor.extension(theme, {nested: true})
268
+ ```
269
+
270
+ A function `(host) => extension` gets each editor's `EditorHost` (`session`, `notePath`). What it returns must be the
271
+ same objects on every call (module constants; options through a facet), or CodeMirror remounts them.
272
+
273
+ ### `ctx.editor.codeBlock`
274
+
275
+ A fenced code block drawn as a widget, in notes, callouts, table cells and canvas cards.
276
+
277
+ ````ts
278
+ ctx.editor.codeBlock({
279
+ language: 'statblock',
280
+ mount(el, {codeContent, host}) {
281
+ el.textContent = `${host.notePath}: ${codeContent.length} characters`
282
+ return () => el.replaceChildren()
283
+ },
284
+ })
285
+ ````
286
+
287
+ It gets `codeContent` (the fence's text) and `host`.
288
+
289
+ ### `ctx.editor.embed`
290
+
291
+ How `![[file]]` draws the files it matches, in notes and canvas cards.
292
+
293
+ ```ts
294
+ ctx.editor.embed({
295
+ id: 'board',
296
+ match: ext => ext === 'board',
297
+ linkName: 'name',
298
+ component: () => import('./BoardEmbed.vue'),
299
+ })
300
+ ```
301
+
302
+ It gets `EmbedProps`: `filePath` (workspace-relative), `subpath` (after `#`), `display` (after `|`), `assetUrl`,
303
+ `host`, and `card: true` in a canvas card, where it fills the box.
304
+
305
+ ### `ctx.editor.markdown`
306
+
307
+ Syntax the editor's parser reads, in notes and everything nested in them: a Lezer `MarkdownConfig`
308
+ (`@lezer/markdown`).
309
+
310
+ ```ts
311
+ import type {MarkdownConfig} from '@lezer/markdown'
312
+
313
+ const roll: MarkdownConfig = {
314
+ defineNodes: [{name: 'DiceRoll'}],
315
+ parseInline: [{
316
+ name: 'DiceRoll',
317
+ parse(cx, next, pos) {
318
+ if (next !== 123 /* { */) return -1
319
+ const end = /^\{\d*d\d+(?:[+-]\d+)?\}/.exec(cx.slice(pos, cx.end))?.[0].length
320
+ return end ? cx.addElement(cx.elt('DiceRoll', pos, pos + end)) : -1
321
+ },
322
+ }],
323
+ }
324
+ ctx.editor.markdown(roll)
325
+ ```
326
+
327
+ Parsing gives the syntax a node; drawing it (a decoration, a widget) is an [extension](#ctxeditorextension)'s job,
328
+ which finds the nodes with `syntaxTree(state)` (`@codemirror/language`).
329
+
330
+ ### `ctx.editor.slashItem`, `ctx.editor.toolbarItem`
331
+
332
+ An item in the slash menu (`/` in a note), or in the toolbar over a selection: the editor's `EditorAction`.
333
+
334
+ ```ts
335
+ ctx.editor.slashItem({
336
+ id: 'hello-statblock',
337
+ label: 'plugins.hello.statblock',
338
+ icon: 'i-lucide-swords',
339
+ keywords: ['creature', 'monster'],
340
+ run: view => {
341
+ const at = view.state.selection.main.head
342
+ view.dispatch({changes: {from: at, insert: '```statblock\nname: Goblin\n```\n'}})
343
+ },
344
+ })
345
+ ```
346
+
347
+ ### `ctx.editor.noteMenuItem`
348
+
349
+ A group of items in a note's right-click menu, after Cut, Copy, Paste and Select all. `items({host, selection})` gets
350
+ the selected text; an item's `onSelect` runs once the menu has closed.
351
+
352
+ ## The index
353
+
354
+ ### `ctx.index.linkExtractor`
355
+
356
+ The links in a file format that isn't Markdown, so its files count in backlinks and the graph, and renames update
357
+ them.
358
+
359
+ ```ts
360
+ import {getInternalLinks, rewriteLinks} from '@type32/vertex-plugin/links'
361
+
362
+ ctx.index.linkExtractor({
363
+ id: 'board',
364
+ match: ext => ext === 'board',
365
+ targets: text => getInternalLinks(text).map(link => link.path),
366
+ rewrite: (text, rename) => rewriteLinks(text, rename),
367
+ })
368
+ ```
369
+
370
+ `targets(text)` returns the link targets as written (`target` of `[[target]]`). `rewrite(text, rename)` returns the
371
+ text with each renamed target replaced (`rename`: old target → new) and how many changed; without it, links in these
372
+ files aren't updated on a rename. For a format that holds Markdown inside JSON, read and rewrite the Markdown parts.
373
+
374
+ ## Sessions
375
+
376
+ ### `ctx.onSession`
377
+
378
+ ```ts
379
+ ctx.onSession(session => {
380
+ session.index.on(event => console.log(event.type))
381
+ })
382
+ ```
383
+
384
+ Runs in a session window once its workspace's index is built (at once, if it already is), with the
385
+ [session](session.md). What it registers and listens to ends with the session. Views, viewers and the rest get the
386
+ session as a prop; `onSession` is for work that isn't drawn (an index listener, a palette group of the workspace's).
387
+
388
+ ## Other plugins
389
+
390
+ ### `ctx.provide`, `ctx.use`, `ctx.whenPlugin`
391
+
392
+ `provide(api)` offers an object to other plugins. `use(id)` is a running plugin's API, `undefined` when it isn't
393
+ running in this window; `whenPlugin(id, fn)` runs `fn` with it now or once that plugin starts.
394
+
395
+ ```ts
396
+ ctx.whenPlugin('bases', bases => {
397
+ bases.registerView({type: 'calendar', label: 'plugins.hello.calendar', icon: 'i-lucide-calendar', component: () => import('./Calendar.vue')})
398
+ })
399
+ ```
400
+
401
+ Put the plugin you use in `requires` (`"requires": ["bases"]`, or `"bases?"` when it's optional). The SDK types the
402
+ APIs of Vertex's own plugins: `bases` (`registerView`, `Value`), `ai`, `chat`, `mermaid` (`Diagram`), `workflows`
403
+ (`run`, `dryRun`, `registerNodes`). A community plugin's API can be provided and used at run time, but it can't be
404
+ typed yet.
405
+
406
+ ## Dialogs
407
+
408
+ ### `ctx.dialogs.open`, `ctx.dialogs.save`
409
+
410
+ The system's Open and Save dialogs: an absolute path, `null` when cancelled. What's picked is this window's to read
411
+ (open) or write (save), even outside the workspace.
412
+
413
+ ```ts
414
+ const path = await ctx.dialogs.open({title: 'Import', filters: [{name: 'CSV', extensions: ['csv']}]})
415
+ ```
416
+
417
+ `directory: true` picks a folder. Files inside the workspace are the session's ([session](session.md#files)).