@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.
- package/dist/theme-app.css +2 -5
- package/dist/types/shared/plugin/components.d.ts +2 -0
- package/dist/types/shared/plugin/contributions.d.ts +3 -2
- package/dist/vite.js +3 -2
- package/docs/README.md +24 -0
- package/docs/config.md +132 -0
- package/docs/context.md +417 -0
- package/docs/package.md +116 -0
- package/docs/publishing.md +71 -0
- package/docs/session.md +205 -0
- package/docs/start.md +173 -0
- package/docs/trust.md +51 -0
- package/docs/ui.md +145 -0
- package/docs/versions.md +33 -0
- package/package.json +3 -2
package/dist/theme-app.css
CHANGED
|
@@ -150,7 +150,8 @@
|
|
|
150
150
|
}
|
|
151
151
|
|
|
152
152
|
.dark {
|
|
153
|
-
|
|
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
|
|
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
|
-
|
|
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: {
|
|
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. |
|
package/docs/context.md
ADDED
|
@@ -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)).
|