@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.
@@ -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`).
@@ -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.0.0",
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
  ".": {