@type32/vertex-plugin 1.0.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/api.d.ts +16 -0
- package/dist/types/shared/plugin/components.d.ts +109 -0
- package/dist/types/shared/plugin/contributions.d.ts +3 -2
- package/dist/types/shared/plugin/messages.d.ts +22 -0
- package/dist/types/ui.d.ts +26 -9
- package/dist/vite.js +75 -10
- 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/docs/session.md
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# The session
|
|
2
|
+
|
|
3
|
+
A session window shows a workspace (a folder) or a single file. Its `SessionContext` is what a plugin works with
|
|
4
|
+
there: the workspace's index and files, the tabs, the editors. Views, viewers, tabs, status items and overlays get it
|
|
5
|
+
as their `session` prop; [`ctx.onSession`](context.md#ctxonsession) gets it for work that isn't drawn.
|
|
6
|
+
|
|
7
|
+
Files are named three ways: by **uuid** (the index's id for a file, stable across renames while Vertex runs, also its
|
|
8
|
+
tab's id), by **absolute path**, and by **workspace-relative path** (`notes/a.md`; `''` is the top level). Each member
|
|
9
|
+
says which it takes. In a single-file window the index is empty.
|
|
10
|
+
|
|
11
|
+
### `session.session`
|
|
12
|
+
|
|
13
|
+
The window's session (`ActiveSession`): its `uuid`, whether it's a workspace's (`workspaceSession`), and the
|
|
14
|
+
workspace's `rootPath`.
|
|
15
|
+
|
|
16
|
+
## Views
|
|
17
|
+
|
|
18
|
+
### `session.views.show`, `session.views.openInTab`
|
|
19
|
+
|
|
20
|
+
`show(id)` shows a panel view in its pane (out of Hidden, its area expanded), `false` when no pane can show it.
|
|
21
|
+
`openInTab(id)` opens a view registered with `tab: true` in a tab.
|
|
22
|
+
|
|
23
|
+
## The index
|
|
24
|
+
|
|
25
|
+
The workspace's files and links, kept up to date as files change, by Vertex or outside it. Reactive: a `computed`
|
|
26
|
+
that reads it follows.
|
|
27
|
+
|
|
28
|
+
### `session.index.files`, `session.index.byPath`, `session.index.byUuid`
|
|
29
|
+
|
|
30
|
+
Every file and folder (`ActiveWorkspaceFileIndex`: `uuid`, `fullPath`, `relativePath`, `fileName`, `fileExt`,
|
|
31
|
+
`isFolder`, `size`, `properties` (a note's frontmatter), `forelinks`, `backlinks` (uuids), `meta` (a note's tags, link
|
|
32
|
+
texts, embeds), `createdTime`, `modifiedTime`), and one by absolute path or uuid.
|
|
33
|
+
|
|
34
|
+
### `session.index.tree`
|
|
35
|
+
|
|
36
|
+
Folders and files as Files shows them: the top level, each folder's `children`, sorted.
|
|
37
|
+
|
|
38
|
+
### `session.index.resolveLink`
|
|
39
|
+
|
|
40
|
+
The file a link target finds (`resolveLink('Some note')` for `[[Some note]]`), as the editor resolves it.
|
|
41
|
+
|
|
42
|
+
### `session.index.backlinks`, `session.index.forelinks`, `session.index.links`, `session.index.unresolved`
|
|
43
|
+
|
|
44
|
+
A file's backlinks and forelinks (uuids), every resolved link as `{from, to}` uuids (a graph's edges), and a file's
|
|
45
|
+
link targets that find no file.
|
|
46
|
+
|
|
47
|
+
### `session.index.on`
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
const off = session.index.on(event => {
|
|
51
|
+
if (event.type === 'rename') console.log(event.oldPath, '→', event.newPath)
|
|
52
|
+
})
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Files created (`create`), removed (`remove`, with every entry removed), renamed (`rename`), modified (`modify`), by
|
|
56
|
+
absolute path. Returns what stops listening; it stops with the session anyway.
|
|
57
|
+
|
|
58
|
+
### `session.index.search`
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
const {hits, more} = await session.index.search('todo', {folder: 'projects', context: 1, limit: 50})
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Notes (Markdown and text files) whose path or text matches, in path order, read from disk: each hit a workspace-relative
|
|
65
|
+
`path`, and for a line, its `line` and `snippet`. Plain text and case-insensitive unless `regex` or `caseSensitive`;
|
|
66
|
+
dot folders are skipped.
|
|
67
|
+
|
|
68
|
+
## Commands
|
|
69
|
+
|
|
70
|
+
### `session.commands.list`, `session.commands.paletteGroups`
|
|
71
|
+
|
|
72
|
+
Every registered command (with its plugin), and the palette's groups: what a command palette of one's own lists.
|
|
73
|
+
|
|
74
|
+
## Files
|
|
75
|
+
|
|
76
|
+
What Files does, for a plugin: notes written through the index, files created, moved, copied and deleted with Files'
|
|
77
|
+
undo, dialogs and toasts. What a file browser needs is all here (menus, New, drags, drops, the clipboard).
|
|
78
|
+
|
|
79
|
+
### `session.files.assetUrl`
|
|
80
|
+
|
|
81
|
+
A URL the webview can load an absolute path from (images, media).
|
|
82
|
+
|
|
83
|
+
### `session.files.write`
|
|
84
|
+
|
|
85
|
+
Writes a file's text, by uuid, and updates the index: a plugin's save.
|
|
86
|
+
|
|
87
|
+
### `session.files.create`
|
|
88
|
+
|
|
89
|
+
Creates an empty file `name` in a workspace-relative folder (made when missing) and indexes it; throws when the path
|
|
90
|
+
exists.
|
|
91
|
+
|
|
92
|
+
### `session.files.edit`
|
|
93
|
+
|
|
94
|
+
New text for notes (`[{uuid, text}]`) as one step of Files' undo history named `label`; open tabs of them reload.
|
|
95
|
+
|
|
96
|
+
### `session.files.move`, `session.files.relocate`, `session.files.duplicate`
|
|
97
|
+
|
|
98
|
+
`move(uuids, folder)` moves files into a folder, with Files' prompts when a name is taken, and undo. `relocate(items)`
|
|
99
|
+
moves and renames items to workspace-relative paths (`{uuid, to}`), and `duplicate(items)` copies them: one undo step
|
|
100
|
+
each, links to moved files updated as the user's setting says, nothing replaced (what can't go comes back in
|
|
101
|
+
`skipped` with why).
|
|
102
|
+
|
|
103
|
+
### `session.files.undo`, `session.files.redo`
|
|
104
|
+
|
|
105
|
+
Files' undo history: the last file operation undone, or redone.
|
|
106
|
+
|
|
107
|
+
### `session.files.remove`
|
|
108
|
+
|
|
109
|
+
Deletes files by uuid into the trash, with Undo; asks first when the user's deletes are for good.
|
|
110
|
+
|
|
111
|
+
### `session.files.copy`, `session.files.paste`
|
|
112
|
+
|
|
113
|
+
`copy(uuids)` puts files on the system clipboard as files (Finder and Explorer paste them). `paste(folder)` copies the
|
|
114
|
+
clipboard's files into a folder; their new uuids.
|
|
115
|
+
|
|
116
|
+
### `session.files.importAttachments`, `session.files.importDrop`, `session.files.outside`
|
|
117
|
+
|
|
118
|
+
Files from outside. `importAttachments(files)`: `File`s as workspace uuids, the workspace's own as they are, the rest
|
|
119
|
+
copied into the attachments folder. `importDrop(transfer, folder)`: a drop's OS files copied into a folder (moved when
|
|
120
|
+
they're the workspace's own; `{copy: true}` copies anyway); call it inside the `drop` event. `outside(source)` (a
|
|
121
|
+
drop, `'clipboard'`, or `File`s) describes them first (`own`, `items`, `folder`) and copies only what `import(chosen)`
|
|
122
|
+
is given, to ask the user before.
|
|
123
|
+
|
|
124
|
+
### `session.files.pick`
|
|
125
|
+
|
|
126
|
+
Vertex's picker of the workspace's files or folders: workspace-relative paths, `undefined` when it's closed.
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
const paths = await session.files.pick({title: 'Choose notes', kind: 'file', multiple: true, extensions: 'md'})
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### `session.files.vault`
|
|
133
|
+
|
|
134
|
+
The workspace as a `Vault` (`@type32/vertex-plugin/vault`), over workspace-relative paths: `entries`, `entry`,
|
|
135
|
+
`linksTo`, `linksFrom`, `read`, `write`, `create`, `createFolder`, `move`; what it writes goes through the index as
|
|
136
|
+
Vertex's own edits do. The same module writes frontmatter as Obsidian does (`setFrontmatterProperty`). Throws in a
|
|
137
|
+
single-file window.
|
|
138
|
+
|
|
139
|
+
### `session.files.iconFor`
|
|
140
|
+
|
|
141
|
+
The icon of a file name: its [file type's](context.md#ctxfilestype), or `undefined` for one Vertex draws itself.
|
|
142
|
+
|
|
143
|
+
### `session.files.openFolders`
|
|
144
|
+
|
|
145
|
+
The folders a file browser shows open (uuids), a `Ref` saved and restored with the session.
|
|
146
|
+
|
|
147
|
+
### `session.files.menuFor`, `session.files.newItems`
|
|
148
|
+
|
|
149
|
+
`menuFor(uuids, {added})` is Files' right-click menu for rows (one, a selection, or `[]` for the empty space), as
|
|
150
|
+
groups of `PluginMenuItem`s for a `UContextMenu`; plugins' items come first, and `added` gets the uuids Paste and
|
|
151
|
+
Duplicate made. `newItems(folder)` is New note, New folder and each file type's New, each asking for a name.
|
|
152
|
+
|
|
153
|
+
### `session.files.drag.start`, `session.files.drag.rows`, `session.files.drag.carries`
|
|
154
|
+
|
|
155
|
+
`start(event, uuids, grab, ended)` inside a `dragstart` makes it Files' drag: its drag image, what the editor and chat
|
|
156
|
+
accept, and in Vertex a drag Finder and Explorer copy from; `ended` runs when it's over. `rows(transfer)` is the
|
|
157
|
+
workspace-relative paths of rows dragged from Files (a folder's ends with `/`), `undefined` for another drag;
|
|
158
|
+
`carries(transfer)` whether a drag carries files at all.
|
|
159
|
+
|
|
160
|
+
### `session.files.openWithDefaultApp`, `session.files.reveal`
|
|
161
|
+
|
|
162
|
+
Opens a file in the app the system gives its kind; shows files in Finder or Explorer.
|
|
163
|
+
|
|
164
|
+
## Properties
|
|
165
|
+
|
|
166
|
+
### `session.properties.types`, `session.properties.setType`
|
|
167
|
+
|
|
168
|
+
The vault's property types (Obsidian's `types.json`: key → `text`, `multitext`, `number`, `checkbox`, `date`,
|
|
169
|
+
`datetime`…), reactive; `setType(key, type)` sets one, `null` back to Automatic.
|
|
170
|
+
|
|
171
|
+
## Tabs
|
|
172
|
+
|
|
173
|
+
### `session.tabs.open`, `session.tabs.close`, `session.tabs.active`, `session.tabs.list`
|
|
174
|
+
|
|
175
|
+
`open(uuid)` opens a file in a tab and shows it; `open(id, kind)` a tab of a [kind](context.md#ctxviewstabkind).
|
|
176
|
+
`active()` is the shown tab's id; `list()` every tab's `{kind, id}` (no `kind` for a file's).
|
|
177
|
+
|
|
178
|
+
## Editors
|
|
179
|
+
|
|
180
|
+
### `session.editor.viewOf`
|
|
181
|
+
|
|
182
|
+
The CodeMirror `EditorView` of a note's tab while it's shown (by the tab's id, the file's uuid), to read the cursor or
|
|
183
|
+
dispatch a change.
|
|
184
|
+
|
|
185
|
+
### `session.editor.content`
|
|
186
|
+
|
|
187
|
+
A text tab's buffer as it is now, saved or not.
|
|
188
|
+
|
|
189
|
+
### `session.editor.lastShownNote`
|
|
190
|
+
|
|
191
|
+
The note tab shown last: where an action from elsewhere (a chat) should go.
|
|
192
|
+
|
|
193
|
+
### `session.editor.embedFor`
|
|
194
|
+
|
|
195
|
+
The embed registered for an extension: draw another plugin's `![[file]]` with `PluginMount` ([UI](ui.md)).
|
|
196
|
+
|
|
197
|
+
## Outside the index
|
|
198
|
+
|
|
199
|
+
### `session.watch`
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
session.watch('.hello', paths => console.log(paths))
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Changes under a workspace-relative folder the index ignores (a dot folder), as absolute paths, a batch at a time.
|
package/docs/start.md
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# Start
|
|
2
|
+
|
|
3
|
+
From an empty folder to a panel view running in Vertex. You need [Bun](https://bun.sh) (or Node with npm) and Vertex.
|
|
4
|
+
|
|
5
|
+
The quick way is the template, which holds the files below: **Use this template** on
|
|
6
|
+
[`Type-32/vertex-plugin-template`](https://github.com/Type-32/vertex-plugin-template) and skip to [Build](#build). By
|
|
7
|
+
hand:
|
|
8
|
+
|
|
9
|
+
## The files
|
|
10
|
+
|
|
11
|
+
The plugin's id is `hello` here. An id is lowercase letters, digits and inner hyphens; it names the plugin's strings,
|
|
12
|
+
settings, data and secrets, so it doesn't change once people use the plugin.
|
|
13
|
+
|
|
14
|
+
`plugin.json`, what Vertex knows without running the plugin ([every key](package.md#pluginjson)):
|
|
15
|
+
|
|
16
|
+
```json
|
|
17
|
+
{
|
|
18
|
+
"id": "hello",
|
|
19
|
+
"name": "Hello",
|
|
20
|
+
"version": "0.1.0",
|
|
21
|
+
"description": "Says hello.",
|
|
22
|
+
"icon": "i-lucide-hand",
|
|
23
|
+
"apiVersion": 1
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`package.json`:
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"name": "hello",
|
|
32
|
+
"private": true,
|
|
33
|
+
"type": "module",
|
|
34
|
+
"scripts": {
|
|
35
|
+
"build": "vite build",
|
|
36
|
+
"typecheck": "vue-tsc -p ."
|
|
37
|
+
},
|
|
38
|
+
"devDependencies": {
|
|
39
|
+
"@type32/vertex-plugin": "^1.1.0",
|
|
40
|
+
"@vitejs/plugin-vue": "^6.0.0",
|
|
41
|
+
"typescript": "^6.0.3",
|
|
42
|
+
"vite": "^8.3.8",
|
|
43
|
+
"vue-tsc": "^3.3.14"
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`vite.config.ts`: `vertex()` builds `src/main.ts`, `plugin.json`, `locales/` and `public/` into `dist/`
|
|
49
|
+
([what it does](package.md#the-build)):
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
import vue from '@vitejs/plugin-vue'
|
|
53
|
+
import {vertex} from '@type32/vertex-plugin/vite'
|
|
54
|
+
import {defineConfig} from 'vite'
|
|
55
|
+
|
|
56
|
+
export default defineConfig({plugins: [vue(), vertex()]})
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`tsconfig.json`; the SDK's types include Nuxt UI's components, so `vue-tsc` checks `<UButton>` in a template:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"compilerOptions": {
|
|
64
|
+
"target": "ES2022",
|
|
65
|
+
"lib": ["ES2023", "DOM", "DOM.Iterable"],
|
|
66
|
+
"module": "ESNext",
|
|
67
|
+
"moduleResolution": "Bundler",
|
|
68
|
+
"strict": true,
|
|
69
|
+
"skipLibCheck": true,
|
|
70
|
+
"noEmit": true,
|
|
71
|
+
"types": ["vite/client", "@type32/vertex-plugin"]
|
|
72
|
+
},
|
|
73
|
+
"include": ["src"]
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`locales/en.json`, the plugin's strings, all under `plugins.<id>` ([strings](package.md#strings)). Add
|
|
78
|
+
`locales/zh-CN.json` with the same keys for Chinese:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"plugins": {
|
|
83
|
+
"hello": {
|
|
84
|
+
"view": "Hello",
|
|
85
|
+
"greeting": "Hello, {name}"
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`src/main.ts`, the entry. `setup` runs once in each window the plugin runs in and registers what it adds
|
|
92
|
+
([`ctx`](context.md)):
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
import {definePlugin} from '@type32/vertex-plugin'
|
|
96
|
+
import {h} from 'vue'
|
|
97
|
+
import View from './View.vue'
|
|
98
|
+
import './style.css'
|
|
99
|
+
|
|
100
|
+
export default definePlugin({
|
|
101
|
+
setup(ctx) {
|
|
102
|
+
ctx.views.panel({
|
|
103
|
+
id: 'hello',
|
|
104
|
+
label: 'plugins.hello.view',
|
|
105
|
+
icon: 'i-lucide-hand',
|
|
106
|
+
defaultArea: 'right',
|
|
107
|
+
component: async () => ({render: () => h(View, {ctx})}),
|
|
108
|
+
})
|
|
109
|
+
},
|
|
110
|
+
})
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`src/View.vue`, the panel. Nuxt UI's components are there by name, as in Vertex's own templates ([UI](ui.md)):
|
|
114
|
+
|
|
115
|
+
```vue
|
|
116
|
+
<script setup lang="ts">
|
|
117
|
+
import type {PluginContext} from '@type32/vertex-plugin'
|
|
118
|
+
|
|
119
|
+
const props = defineProps<{ ctx: PluginContext }>()
|
|
120
|
+
const {t} = props.ctx.i18n
|
|
121
|
+
</script>
|
|
122
|
+
|
|
123
|
+
<template>
|
|
124
|
+
<div class="flex items-center gap-2 p-3 text-sm text-muted">
|
|
125
|
+
<span>{{ t('plugins.hello.greeting', {name: 'Vertex'}) }}</span>
|
|
126
|
+
<UButton size="xs" icon="i-lucide-sparkles" variant="soft"/>
|
|
127
|
+
</div>
|
|
128
|
+
</template>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`src/style.css`, Tailwind's utilities against Vertex's theme ([styles](ui.md#styles)):
|
|
132
|
+
|
|
133
|
+
```css
|
|
134
|
+
@import "@type32/vertex-plugin/tailwind.css";
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Build
|
|
138
|
+
|
|
139
|
+
```sh
|
|
140
|
+
bun install
|
|
141
|
+
bun run build
|
|
142
|
+
bun run typecheck
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`dist/` now holds `plugin.json`, `main.js`, `styles.css` and `locales/`: the plugin as Vertex installs it. The build
|
|
146
|
+
fails with what's wrong when `plugin.json` or a locale file breaks a rule.
|
|
147
|
+
|
|
148
|
+
> If the build finds none of your Tailwind classes (`styles.css` nearly empty), a `.gitignore` in a folder above the
|
|
149
|
+
> project probably ignores it: Tailwind skips ignored files until the project is a Git repository of its own. Run
|
|
150
|
+
> `git init` in it.
|
|
151
|
+
|
|
152
|
+
## Run it in Vertex
|
|
153
|
+
|
|
154
|
+
Settings → Plugins → the arrow beside **Install…** → **From a folder (development)…**, and pick `dist/`. The dialog
|
|
155
|
+
shows what the plugin is and asks; **Install** turns it on. In a workspace window, open the right sidebar (the button
|
|
156
|
+
at the window's top right): its header has the view's icon, the hand, and a click on it shows "Hello, Vertex".
|
|
157
|
+
|
|
158
|
+
Pick `dist/`, not the project: the folder you pick is copied as it is and watched.
|
|
159
|
+
|
|
160
|
+
## The development loop
|
|
161
|
+
|
|
162
|
+
A plugin installed from a folder stays watched while that folder is its source: when its files change, Vertex copies
|
|
163
|
+
them again, and each window running the plugin saves its session and reloads. So keep a build running:
|
|
164
|
+
|
|
165
|
+
```sh
|
|
166
|
+
bunx vite build --watch
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
and each save of a source file shows in Vertex a moment later. An error in `setup` or in what the plugin draws shows
|
|
170
|
+
in Vertex as "Hello couldn't start" or in place of the view; the window's web inspector has the stack and the
|
|
171
|
+
console (on macOS, Safari → Develop → your Mac's name → the Vertex window).
|
|
172
|
+
|
|
173
|
+
To ship it, see [Publishing](publishing.md).
|
package/docs/trust.md
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Trust
|
|
2
|
+
|
|
3
|
+
A plugin runs as Vertex does: it can read and change the user's notes and files, and nothing sandboxes it. Users are
|
|
4
|
+
told so, and decide.
|
|
5
|
+
|
|
6
|
+
## Installing
|
|
7
|
+
|
|
8
|
+
The install dialog shows what the plugin says of itself (`name`, `version`, `author`, `description`), where it was
|
|
9
|
+
fetched from (and where it says it's from, when that differs), the [permissions](config.md#permissions) it asks for,
|
|
10
|
+
and that it runs as Vertex does. An update shows what changed in its version, permissions, requirements and
|
|
11
|
+
`apiVersion`. A plugin from another repository than the copy it would replace (which would get that one's settings,
|
|
12
|
+
data and secrets) needs its own confirmation.
|
|
13
|
+
|
|
14
|
+
So: ask only for the permissions the plugin uses, name its `repository`, and release from that repository
|
|
15
|
+
([Publishing](publishing.md)).
|
|
16
|
+
|
|
17
|
+
## A workspace's plugins
|
|
18
|
+
|
|
19
|
+
A workspace can carry plugins in its `.vertex/plugins/<id>/`, which travel with it (sync, Git). They run only in that
|
|
20
|
+
workspace's windows, once its folder is trusted and each plugin is accepted: trusting the folder lists them first,
|
|
21
|
+
with what each asks for. Acceptance pins the plugin's `plugin.json`, `main.js`, `styles.css` and strings: when any of
|
|
22
|
+
them changes (an update on another device, a pull), the plugin is off there until the user accepts it again. A
|
|
23
|
+
workspace's copy replaces an installed plugin with its id in that workspace.
|
|
24
|
+
|
|
25
|
+
A workspace also names where its plugins come from (`plugins.sources` in its settings), so another device can install
|
|
26
|
+
the ones it lacks.
|
|
27
|
+
|
|
28
|
+
## Programs in a vault
|
|
29
|
+
|
|
30
|
+
### `ctx.trust.allows`, `ctx.trust.trustFile`, `ctx.trust.trustFolder`, `ctx.trust.followEdit`, `ctx.trust.format`
|
|
31
|
+
|
|
32
|
+
For a plugin that runs programs from the vault (a workflow, a script), so every such plugin asks the same way and the
|
|
33
|
+
user manages them in one place, Settings → Trust. Paths are absolute; `hash` names a program's content.
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
ctx.trust.format({extensions: ['macro'], hash: async text => (await sha256(text))})
|
|
37
|
+
|
|
38
|
+
if (!await ctx.trust.allows(path, hash)) {
|
|
39
|
+
// Ask the user, then:
|
|
40
|
+
await ctx.trust.trustFile(path, hash)
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
- `allows(path, hash)`: whether it may run without asking: the file is trusted, or a folder covering it is (with this
|
|
45
|
+
program, when trust remembers content).
|
|
46
|
+
- `trustFile(path, hash)`; `trustFolder(path, nested, pin?)`, its subfolders too with `nested`, `false` when the user
|
|
47
|
+
declines (a folder whose workspace has plugins asks about them first).
|
|
48
|
+
- `followEdit(path, before, after)`: an edit made in Vertex keeps the file's trust with its new program.
|
|
49
|
+
- `format({extensions, hash})`: the files whose programs a folder's trust pins.
|
|
50
|
+
|
|
51
|
+
(`sha256` stands for the plugin's own hashing, `crypto.subtle.digest` for one.)
|
package/docs/ui.md
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# UI
|
|
2
|
+
|
|
3
|
+
Everything a plugin draws (a view, a viewer, a tab, a code block, a settings page) is a `UiSlot`, given one of two
|
|
4
|
+
ways:
|
|
5
|
+
|
|
6
|
+
| | `mount(el, props)` | `component` |
|
|
7
|
+
| --- | --- | --- |
|
|
8
|
+
| What it is | A function that draws into `el` and returns what undoes it. | A lazily loaded Vue component that gets the props. |
|
|
9
|
+
| With | Anything: the DOM, a canvas, another framework, a library that wants an element. | Vue, Nuxt UI's components, Vertex's own (`/ui`). |
|
|
10
|
+
| Promise | Stable: the props are the contract's, and nothing else of Vertex's is involved. | Follows Vertex's Vue and Nuxt UI: a new major of Nuxt UI can break a template. |
|
|
11
|
+
| On a change of props | `mount` runs again, after what it returned has run. | Vue updates the component. |
|
|
12
|
+
|
|
13
|
+
Either way it draws inside an error boundary: what throws shows "{name} couldn't draw this" in its place, with the
|
|
14
|
+
error, and the rest of Vertex goes on.
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
ctx.views.panel({
|
|
18
|
+
id: 'hello-canvas',
|
|
19
|
+
label: 'plugins.hello.canvas',
|
|
20
|
+
icon: 'i-lucide-chart-scatter',
|
|
21
|
+
defaultArea: 'bottom',
|
|
22
|
+
mount(el, {session}) {
|
|
23
|
+
const canvas = el.appendChild(document.createElement('canvas'))
|
|
24
|
+
canvas.dataset.files = String(session.index.files().length)
|
|
25
|
+
return () => canvas.remove()
|
|
26
|
+
},
|
|
27
|
+
})
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Vue
|
|
31
|
+
|
|
32
|
+
A component loader is `() => import('./View.vue')`, or a component made on the spot when it needs `ctx`:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import {h} from 'vue'
|
|
36
|
+
import View from './View.vue'
|
|
37
|
+
|
|
38
|
+
ctx.views.panel({
|
|
39
|
+
id: 'hello',
|
|
40
|
+
label: 'plugins.hello.view',
|
|
41
|
+
icon: 'i-lucide-hand',
|
|
42
|
+
defaultArea: 'right',
|
|
43
|
+
component: async () => ({render: () => h(View, {ctx})}),
|
|
44
|
+
})
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
A view's component gets the point's props (`PanelViewProps`, `ViewerProps`…) as props; one made with `h` gets what it
|
|
48
|
+
passes. `vue` is Vertex's own copy, so `ref`, `computed`, `watch`, `provide` and `inject` work with Vertex's, and
|
|
49
|
+
what's reactive in the contract (`ctx.i18n`, `ctx.config.value`, `session.index`) is reactive in a template.
|
|
50
|
+
|
|
51
|
+
## Nuxt UI
|
|
52
|
+
|
|
53
|
+
Vertex is drawn with [Nuxt UI](https://ui.nuxt.com) v4, and a plugin's templates have every one of its components by
|
|
54
|
+
name, as Vertex's do:
|
|
55
|
+
|
|
56
|
+
```vue
|
|
57
|
+
<script setup lang="ts">
|
|
58
|
+
import {ref} from 'vue'
|
|
59
|
+
|
|
60
|
+
const query = ref('')
|
|
61
|
+
const refresh = () => {}
|
|
62
|
+
</script>
|
|
63
|
+
|
|
64
|
+
<template>
|
|
65
|
+
<UButton label="Refresh" icon="i-lucide-refresh-cw" variant="soft" @click="refresh"/>
|
|
66
|
+
<UInput v-model="query" placeholder="Filter"/>
|
|
67
|
+
</template>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
In a render function, `resolveComponent('UButton')` (from `vue`). The composables come from `@nuxt/ui/composables`
|
|
71
|
+
(`useToast`, `useOverlay`), so a plugin's toast is Vertex's:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import {useToast} from '@nuxt/ui/composables'
|
|
75
|
+
|
|
76
|
+
useToast().add({title: ctx.i18n.t('plugins.hello.done'), color: 'success'})
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Nothing else may be imported from `@nuxt/ui`: it would be a second Nuxt UI beside Vertex's, and the build refuses it.
|
|
80
|
+
The SDK types the components, so `vue-tsc` checks their props.
|
|
81
|
+
|
|
82
|
+
### Icons
|
|
83
|
+
|
|
84
|
+
An icon is an Iconify name: `i-lucide-hand`, in an `icon` prop or `<UIcon name="i-lucide-hand"/>`. Lucide
|
|
85
|
+
(`i-lucide-*`, Vertex's own set) and Simple Icons (`i-simple-icons-*`, brands) draw offline. The `i-…` classes of
|
|
86
|
+
Nuxt's icon CSS aren't in a plugin's Tailwind: draw an icon with `UIcon`.
|
|
87
|
+
|
|
88
|
+
## Vertex's components
|
|
89
|
+
|
|
90
|
+
From `@type32/vertex-plugin/ui`, so a plugin's UI looks and behaves as Vertex's. Their props are the contract's
|
|
91
|
+
(`SettingsRowProps`, `ViewerLayoutProps`… in `@type32/vertex-plugin`), and `vue-tsc` checks them.
|
|
92
|
+
|
|
93
|
+
| Component | |
|
|
94
|
+
| --- | --- |
|
|
95
|
+
| `SettingsScrollLayout` | A settings page: the title (`title`) in a header over the scrolling content. `globalOnly` marks a page none of whose settings a workspace may change. |
|
|
96
|
+
| `SettingsSection` | A group of rows under a title, with a reset button while `dirty` (emits `reset`). |
|
|
97
|
+
| `SettingsRow` | One setting: `label`, `description`, `icon`, `error`; the control is the default slot. `setting` (`config.path('depth')`) makes it follow the scope Settings edits: Global only, Changed in this workspace, Use global. |
|
|
98
|
+
| `ViewerLayout` | A file viewer's frame: the editable title (`v-model:fileName`, `@on-rename`), the content (the default slot), the status bar with the registered status items. |
|
|
99
|
+
| `NoteEditor` | A Markdown editor inside something else (a card, a form): `text`, `notePath`; emits `update`, `done` (Esc), `openLink`. |
|
|
100
|
+
| `PluginMount` | Draws a contribution's UI with props (another plugin's embed, from `session.editor.embedFor`). |
|
|
101
|
+
| `VaultPicker` | The workspace's files or folders, inline (`v-model`: workspace-relative paths). |
|
|
102
|
+
| `TextDiff` | Two texts line by line, numbered and folded (`sides: {before, after}`). |
|
|
103
|
+
|
|
104
|
+
And two functions: `openExternal(url)` opens a web or mail link in the default browser or mail app (anything else is
|
|
105
|
+
refused), and `useScrollFade(element)`, the classes that fade a scroll area's edges as Vertex's panels do.
|
|
106
|
+
|
|
107
|
+
A settings page, all three Settings components together:
|
|
108
|
+
|
|
109
|
+
```vue
|
|
110
|
+
<script setup lang="ts">
|
|
111
|
+
import type {SettingsPageProps} from '@type32/vertex-plugin'
|
|
112
|
+
import {SettingsRow, SettingsScrollLayout, SettingsSection} from '@type32/vertex-plugin/ui'
|
|
113
|
+
|
|
114
|
+
defineProps<SettingsPageProps>()
|
|
115
|
+
const defaults = {depth: 2}
|
|
116
|
+
</script>
|
|
117
|
+
|
|
118
|
+
<template>
|
|
119
|
+
<SettingsScrollLayout title="Hello">
|
|
120
|
+
<SettingsSection title="Graph" :dirty="config.isDirty(['depth'], defaults)" @reset="config.reset(['depth'], defaults)">
|
|
121
|
+
<SettingsRow label="Depth" :setting="config.path('depth')">
|
|
122
|
+
<UInputNumber :model-value="config.value('depth') as number" :min="1" :max="5" @update:model-value="v => config.set({depth: v})"/>
|
|
123
|
+
</SettingsRow>
|
|
124
|
+
</SettingsSection>
|
|
125
|
+
</SettingsScrollLayout>
|
|
126
|
+
</template>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
(Labels are text here to keep it short; a plugin's come from `ctx.i18n.t`.)
|
|
130
|
+
|
|
131
|
+
## Styles
|
|
132
|
+
|
|
133
|
+
`@import "@type32/vertex-plugin/tailwind.css";` at the top of the plugin's CSS gives it Tailwind's utilities against
|
|
134
|
+
Vertex's theme: `text-muted`, `bg-elevated`, `border-default`, `text-primary` and the other Nuxt UI colours, Tailwind's
|
|
135
|
+
palette and spacing, Vertex's fonts. The build writes the classes the plugin uses into its `styles.css`.
|
|
136
|
+
|
|
137
|
+
- **No preflight, nothing on `:root`:** the plugin's CSS can't restyle Vertex. Scope any plain CSS to the plugin's own
|
|
138
|
+
elements (a class of the plugin's id).
|
|
139
|
+
- **The theme follows by itself:** Nuxt UI's colours are CSS variables, so `text-primary` changes with the user's
|
|
140
|
+
colour and light or dark. For what CSS can't reach (a canvas), read
|
|
141
|
+
[`ctx.ui.theme`](context.md#ctxuithemedark-ctxuithemevalue).
|
|
142
|
+
- **Dark mode:** `dark:` variants work (Vertex puts `dark` on `<html>`), though the semantic colours (`text-muted`,
|
|
143
|
+
`bg-default`) already switch.
|
|
144
|
+
- Tailwind finds the classes in the project's files, skipping what Git ignores. A `.gitignore` in a folder above the
|
|
145
|
+
project that ignores it hides them until the project is a Git repository of its own (`git init`).
|
package/docs/versions.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Versions
|
|
2
|
+
|
|
3
|
+
Three numbers, each with its own job:
|
|
4
|
+
|
|
5
|
+
| | Where | Says |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| `apiVersion` | `plugin.json` | The plugin contract the plugin is written against. `1` today. |
|
|
8
|
+
| `minAppVersion` | `plugin.json`, optional | The oldest Vertex that has what the plugin uses (`0.9.2`). |
|
|
9
|
+
| The SDK's version | `package.json`, `@type32/vertex-plugin` | The contract's types, the shared modules' versions, the preset. |
|
|
10
|
+
|
|
11
|
+
## `apiVersion`
|
|
12
|
+
|
|
13
|
+
What Vertex promises a plugin: the contract (`ctx`, `session`, the contribution points and their props) and the
|
|
14
|
+
versions of the [modules it shares](package.md#what-the-plugin-shares-with-vertex). Within one `apiVersion`, Vertex
|
|
15
|
+
only adds to the contract, so a plugin built for it keeps working in later Vertex releases. A change that breaks one
|
|
16
|
+
(a member removed, a shared package's new major: Vue 4, CodeMirror 7) is a new `apiVersion`; Vertex refuses a plugin
|
|
17
|
+
that asks for a newer one than it has.
|
|
18
|
+
|
|
19
|
+
## `minAppVersion`
|
|
20
|
+
|
|
21
|
+
An addition within an `apiVersion` (a new member of `ctx`) exists only in the Vertex releases since it was added. A
|
|
22
|
+
plugin that uses one sets `minAppVersion` to that release; an older Vertex keeps the plugin off and says why, instead
|
|
23
|
+
of failing when it calls what isn't there.
|
|
24
|
+
|
|
25
|
+
## The SDK
|
|
26
|
+
|
|
27
|
+
`@type32/vertex-plugin`'s major is the `apiVersion` it types (`1.x` is `apiVersion` 1); a minor adds to the contract;
|
|
28
|
+
its dependencies are the shared modules at Vertex's versions. Depend on it with `^` (`^1.1.0`), and update it to use
|
|
29
|
+
what a newer Vertex adds, with `minAppVersion` to match.
|
|
30
|
+
|
|
31
|
+
The contract's `/ui` components are Vue components drawn with Nuxt UI, so they follow those packages: a plugin that
|
|
32
|
+
draws with them may need changes when Vertex moves to Nuxt UI's next major. One drawn through `mount` doesn't
|
|
33
|
+
([UI](ui.md)).
|
package/package.json
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@type32/vertex-plugin",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.1",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Vertex SDK - Types, the host's shared modules and a Vite preset for Vertex community plugins.",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"files": [
|
|
8
|
-
"dist"
|
|
8
|
+
"dist",
|
|
9
|
+
"docs"
|
|
9
10
|
],
|
|
10
11
|
"exports": {
|
|
11
12
|
".": {
|