@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/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.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
|
".": {
|