@nesso-how/plugin 0.2.0 → 0.3.0
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/README.md +152 -38
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/package.d.ts +1 -1
- package/dist/package.js +1 -1
- package/dist/{runtime-DEm2BYYI.js → runtime-Dl8Rcuy8.js} +57 -26
- package/dist/{runtime-Ciol8MqD.d.ts → runtime-NJhqaq_J.d.ts} +32 -16
- package/dist/runtime.d.ts +2 -2
- package/dist/runtime.js +1 -1
- package/example/LICENSE +21 -0
- package/example/README.md +19 -7
- package/example/package.json +15 -5
- package/example/src/index.ts +20 -11
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,64 +1,178 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Nesso Plugin SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Build Nesso plugins with TypeScript: **actions** read and edit graphs, **vocabularies** define relation types, and **themes** customize appearance.
|
|
4
4
|
|
|
5
5
|
## Create a plugin
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Copy the [standalone action example](example/) into a separate project. It includes the SDK, TypeScript configuration, and bundler setup:
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
```sh
|
|
10
|
+
npm install
|
|
11
|
+
npm run build
|
|
12
|
+
```
|
|
12
13
|
|
|
13
|
-
|
|
14
|
+
Choose your own package name and action ID, then edit `src/index.ts`:
|
|
14
15
|
|
|
15
|
-
|
|
16
|
+
```ts
|
|
17
|
+
import type { ActionContribution, NessoOperation } from '@nesso-how/plugin'
|
|
18
|
+
import source from '../package.json' with { type: 'json' }
|
|
16
19
|
|
|
17
|
-
|
|
20
|
+
export const create = (): readonly ActionContribution[] => {
|
|
21
|
+
const action: ActionContribution = {
|
|
22
|
+
id: 'uppercase-labels',
|
|
23
|
+
label: source.i18n.metadata.name,
|
|
24
|
+
run: async ({ store }) => {
|
|
25
|
+
const state = store.getState()
|
|
18
26
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
| `writes` | Document-content operation kinds, without duplicates |
|
|
25
|
-
| `capabilities` | Subset of `files.open`, `files.save`, `notifications.notify`, without duplicates |
|
|
27
|
+
const operations: readonly NessoOperation[] = state.viewGraph.concepts.map(({ id, label }) => ({
|
|
28
|
+
kind: 'concept.label',
|
|
29
|
+
id,
|
|
30
|
+
value: label.toUpperCase(),
|
|
31
|
+
}))
|
|
26
32
|
|
|
27
|
-
|
|
33
|
+
await store.applyOperations(operations)
|
|
34
|
+
},
|
|
35
|
+
}
|
|
28
36
|
|
|
29
|
-
|
|
37
|
+
return [action]
|
|
38
|
+
}
|
|
39
|
+
```
|
|
30
40
|
|
|
31
|
-
|
|
41
|
+
This changes labels in the invoked view in one undoable batch. Shared concepts change in every view containing them.
|
|
42
|
+
|
|
43
|
+
How the example works:
|
|
44
|
+
|
|
45
|
+
- `create()` defines the actions. Nesso supplies the execution context to `run`, where graph data is always available.
|
|
46
|
+
- `applyOperations` takes an array of edits. Here, `.map()` creates one `concept.label` edit per concept, with its ID and new label.
|
|
47
|
+
- Writes automatically check that the snapshot you read is still current. If it changed, the entire batch is rejected rather than overwriting newer edits.
|
|
48
|
+
|
|
49
|
+
### Package metadata and permissions
|
|
50
|
+
|
|
51
|
+
Keep the example's build configuration and set these fields in `package.json`:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"name": "nesso-plugin-my-action",
|
|
56
|
+
"version": "1.0.0",
|
|
57
|
+
"keywords": ["nesso-plugin"],
|
|
58
|
+
"nesso": {
|
|
59
|
+
"apiVersion": 1,
|
|
60
|
+
"kind": "actions",
|
|
61
|
+
"entry": "dist/index.js",
|
|
62
|
+
"writes": ["concept.label"],
|
|
63
|
+
"capabilities": []
|
|
64
|
+
},
|
|
65
|
+
"i18n": {
|
|
66
|
+
"metadata": {
|
|
67
|
+
"name": { "en": "Uppercase labels" },
|
|
68
|
+
"description": { "en": "Uppercase concept labels in a view." },
|
|
69
|
+
"documentation": { "en": "Updates labels in one undoable batch." }
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
32
74
|
|
|
33
|
-
|
|
75
|
+
Declare the operations your action uses in `writes` and file/notification access in `capabilities`. All fields shown under `nesso` and `i18n.metadata` are required. Add the `nesso-plugin` keyword for discovery in Settings → Plugins.
|
|
34
76
|
|
|
35
|
-
|
|
77
|
+
Labels and metadata use `{ en: string, it?: string, 'zh-CN'?: string }`, with English required as the fallback.
|
|
36
78
|
|
|
37
|
-
|
|
38
|
-
- Await write helpers such as `setConceptLabel`, `addConcept`, and `setViewMembership`. Use `applyOperations(operations, { atRevision })` for one atomic, revision-checked batch. Separate calls are separate transactions; never retry mutations automatically.
|
|
39
|
-
- Receiving the invoked view is not a write sandbox. Declared writes can affect the whole document.
|
|
40
|
-
- `run({ viewId })` keeps its invocation target despite navigation; `null` means All. Target deletion or document reset revokes the context. Use `refresh()` after deferred work and honor `signal`.
|
|
41
|
-
- `files.open()`/`save()` mediate UTF-8 text files up to 16 MiB through the host, returning `null`/`{ saved: false }` on cancellation. `notifications.notify()` posts internal `info`/`warning` messages. Each effect requires its declared capability and must be awaited before returning.
|
|
79
|
+
### Build and test
|
|
42
80
|
|
|
43
|
-
|
|
81
|
+
Run `npm run build`, then follow the example's [local testing instructions](example/README.md#test-an-unpublished-build).
|
|
44
82
|
|
|
45
|
-
|
|
83
|
+
Actions must ship one self-contained browser ES module with dependencies bundled; the example's build handles this. Test and install external plugins in the desktop app.
|
|
46
84
|
|
|
47
|
-
|
|
85
|
+
## Action API
|
|
48
86
|
|
|
49
|
-
|
|
87
|
+
Nesso passes `{ store, files, notifications, signal, viewId }` to `run` as `ActionContext`.
|
|
50
88
|
|
|
51
|
-
|
|
89
|
+
`create()` receives no arguments and returns an array of actions with unique lowercase kebab-case IDs, localized labels, optional icons, and `run(context)` handlers. Use `ActionIconName` for supported icons.
|
|
52
90
|
|
|
53
|
-
|
|
91
|
+
Keep graph reads and effects inside `run`. **Await every write, file dialog, and notification** before returning; the action ends when `run` finishes. Use `signal` to detect cancellation.
|
|
54
92
|
|
|
55
|
-
|
|
93
|
+
### Read the invoked view
|
|
56
94
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
95
|
+
- `store.getState()` returns the latest readonly local snapshot synchronously and makes it the basis for subsequent writes.
|
|
96
|
+
- `await store.refresh()` fetches and reads a fresh snapshot. Use it after deferred work, such as a file dialog, before computing edits.
|
|
97
|
+
- `store.subscribe(listener)` notifies you of snapshot changes and returns an unsubscribe function. Read the new state with `getState()`.
|
|
98
|
+
|
|
99
|
+
The graph snapshot provides:
|
|
100
|
+
|
|
101
|
+
- `viewGraph`: `{ concepts, relations, relationTypes }` for the invoked view.
|
|
102
|
+
- `selected`: the invoked view's selection.
|
|
103
|
+
- `targetViewId`: the invoked view's ID, or `null` for All; navigation does not change the target.
|
|
104
|
+
- `activeVocab`: the current vocabulary, or `null`.
|
|
105
|
+
|
|
106
|
+
Concept and relation-type IDs are absolute IRIs. Relations are `{ source, predicate, target }` triples; use `JSON.stringify([source, predicate, target])` as their selection/write ID.
|
|
107
|
+
|
|
108
|
+
### Write the graph
|
|
109
|
+
|
|
110
|
+
Call helpers on `store` and declare their operation kinds in `nesso.writes`:
|
|
111
|
+
|
|
112
|
+
| Helper | Required `writes` entry |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| `setConceptLabel(id, value)` | `concept.label` |
|
|
115
|
+
| `setConceptDescription(id, value)` | `concept.description` |
|
|
116
|
+
| `setConceptColor(id, value)` | `concept.color` |
|
|
117
|
+
| `setConceptBold(id, value)` | `concept.bold` |
|
|
118
|
+
| `setConceptItalic(id, value)` | `concept.italic` |
|
|
119
|
+
| `setConceptPosition(id, { x, y })` | `concept.position` |
|
|
120
|
+
| `setConceptPositions([{ id, position: { x, y } }])` | `concept.positions` |
|
|
121
|
+
| `addConcept(position?)` | `concept.add` |
|
|
122
|
+
| `removeConcept(id)` | `concept.remove` |
|
|
123
|
+
| `connect(source, target)` | `relation.connect` |
|
|
124
|
+
| `reconnectRelation(id, source, target)` | `relation.reconnect` |
|
|
125
|
+
| `setRelationType(id, typeId)` | `relation.type` |
|
|
126
|
+
| `createRelationType(id, label)` | `relation.type.create` |
|
|
127
|
+
| `removeRelation(id)` | `relation.remove` |
|
|
128
|
+
| `setSelection([{ kind, id }])` | `selection.set` |
|
|
129
|
+
| `setViewMembership(viewId, conceptId, included)` | `view.membership` |
|
|
130
|
+
|
|
131
|
+
`addConcept` returns the new IRI. New concepts join the active saved view and link to the single selected concept, if any. These links and `connect` use the vocabulary's default relation type. `createRelationType` creates and assigns a type to the given relation.
|
|
132
|
+
|
|
133
|
+
For related edits, use `store.applyOperations(operations)` as in the quickstart. The entire batch succeeds or changes nothing. Separate calls are separate transactions. Raw `concept.add` operations require an explicit new absolute IRI.
|
|
134
|
+
|
|
135
|
+
Every write checks against the last snapshot you read, or the initial snapshot if you haven't read one. Successful writes advance that baseline, so awaited sequential writes work normally. Incoming updates alone do not advance it. A conflict rejects with `stale-state`; let the failure propagate so Nesso can ask the user to run the action again. Never retry mutations automatically or read a new snapshot just to submit edits calculated from old data.
|
|
136
|
+
|
|
137
|
+
The invoked view is **not a write sandbox**: permitted writes can affect the whole document. Only the operations listed above are available to plugins.
|
|
138
|
+
|
|
139
|
+
### Files, notifications, and failures
|
|
140
|
+
|
|
141
|
+
| API | Required capability | Result |
|
|
142
|
+
| --- | --- | --- |
|
|
143
|
+
| `files.open({ extensions: ['json'], mimeTypes: ['application/json'] })` | `files.open` | `{ name, mediaType, text }`, or `null` on cancellation. Extensions omit the dot. |
|
|
144
|
+
| `files.save({ name: 'graph.json', mediaType: 'application/json', text })` | `files.save` | `{ saved: boolean }`; cancellation returns `false`. |
|
|
145
|
+
| `notifications.notify({ tone: 'info', title: { en: 'Done' }, description: { en: 'Labels updated' } })` | `notifications.notify` | A notification ID. Tone is `info` or `warning`; description is optional. |
|
|
146
|
+
|
|
147
|
+
Files use UTF-8 text. Plugins have no Node, host DOM, direct filesystem, clipboard, or network access.
|
|
148
|
+
|
|
149
|
+
Failures throw `PluginError` with `code` and `{ path, message }[]` issues. Let them propagate instead of reporting success. Files and notifications cannot be rolled back with graph edits.
|
|
150
|
+
|
|
151
|
+
## Vocabularies
|
|
152
|
+
|
|
153
|
+
Set `nesso.kind` to `"vocab"`, `entry` to a package-local JSON file such as `"dist/definition.json"`, and both `writes` and `capabilities` to `[]`. Keep the same package metadata structure. The entry contains a `VocabDefinition`:
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"id": "my-vocab",
|
|
158
|
+
"relationTypes": [
|
|
159
|
+
{ "id": "urn:my-vocab:depends-on", "label": "depends on" }
|
|
160
|
+
],
|
|
161
|
+
"defaultTypeId": "urn:my-vocab:depends-on"
|
|
162
|
+
}
|
|
60
163
|
```
|
|
61
164
|
|
|
62
|
-
Use
|
|
165
|
+
Use stable absolute IRIs for relation types and choose a default from your own list. See [Base Vocab](../../plugins/base-vocab/) for a larger example.
|
|
166
|
+
|
|
167
|
+
## Themes
|
|
168
|
+
|
|
169
|
+
Set `nesso.kind` to `"theme"`, point `entry` to your JSON definition, and use empty `writes` and `capabilities`. A `ThemeDefinition` contains:
|
|
170
|
+
|
|
171
|
+
- `id`: a lowercase kebab-case contribution ID.
|
|
172
|
+
- `colors`: every required token, using `#RRGGBB` or `#RRGGBBAA`. Start with [Paper's palette](../../plugins/paper-theme/src/index.ts) or [Kernel's](../../plugins/kernel-theme/src/index.ts).
|
|
173
|
+
- `metrics`: `radius-control` and `radius-object` in pixels, and `duration-state` in milliseconds.
|
|
174
|
+
- `fonts`: `sans` and `mono`, each with a `faces` array. Use `[]` for system fallbacks, or include local WOFF2 files with package-relative `path`, `weight: [min, max]`, and `style: "normal"` or `"italic"`.
|
|
175
|
+
|
|
176
|
+
Only light themes are supported. Use readable text contrast; arbitrary CSS and remote fonts are unsupported.
|
|
63
177
|
|
|
64
|
-
|
|
178
|
+
For the full API and validation rules, see [action types](src/runtime.ts), [graph operations](src/types.ts), and [theme/vocabulary schemas](src/definitions.ts).
|
package/dist/index.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export { type ActionContext, type ActionContribution, type ActionDescriptor, type ActionIconName, type ActionState, type
|
|
1
|
+
import { A as NessoState, B as Viewport, C as createWriteCommands, E as LocalizedText, F as PanelSizes, H as WorkspaceState, I as Preferences, L as SavedView, M as Notification, N as NotificationAction, O as GraphSnapshot, P as Notifications, R as SectionId, V as VocabDefinition, W as ThemeDefinition, a as ActionState, c as actionIconNames, i as ActionIconName, j as NessoStore, k as NessoOperation, n as ActionContribution, o as PluginI18n, r as ActionDescriptor, s as PluginManifest, t as ActionContext, w as PluginError, z as Selection } from "./runtime-NJhqaq_J.js";
|
|
2
|
+
export { type ActionContext, type ActionContribution, type ActionDescriptor, type ActionIconName, type ActionState, type GraphSnapshot, type LocalizedText, type NessoOperation, type NessoState, type NessoStore, type Notification, type NotificationAction, type Notifications, type PanelSizes, PluginError, type PluginI18n, type PluginManifest, type Preferences, type SavedView, type SectionId, type Selection, type ThemeDefinition, type Viewport, type VocabDefinition, type WorkspaceState, actionIconNames, createWriteCommands };
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { _ as PluginError, t as actionIconNames, g as createWriteCommands } from "./runtime-
|
|
1
|
+
export { _ as PluginError, t as actionIconNames, g as createWriteCommands } from "./runtime-Dl8Rcuy8.js";
|
package/dist/package.d.ts
CHANGED
package/dist/package.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { _ as PluginError, a as parsePluginI18n, l as sha256Hex, m as parseDefinition, n as checkMessageSize, o as parsePluginManifest, v as parseOrThrow } from "./runtime-
|
|
1
|
+
import { _ as PluginError, a as parsePluginI18n, l as sha256Hex, m as parseDefinition, n as checkMessageSize, o as parsePluginManifest, v as parseOrThrow } from "./runtime-Dl8Rcuy8.js";
|
|
2
2
|
import { z } from "zod";
|
|
3
3
|
import parseVersion from "semver/functions/parse.js";
|
|
4
4
|
import validateName from "validate-npm-package-name";
|
|
@@ -98,6 +98,16 @@ function createWriteCommands(applyOperations, created) {
|
|
|
98
98
|
id,
|
|
99
99
|
value
|
|
100
100
|
}], historyGroup ? { historyGroup } : void 0),
|
|
101
|
+
setConceptBold: (id, value, historyGroup) => applyOperations([{
|
|
102
|
+
kind: "concept.bold",
|
|
103
|
+
id,
|
|
104
|
+
value
|
|
105
|
+
}], historyGroup ? { historyGroup } : void 0),
|
|
106
|
+
setConceptItalic: (id, value, historyGroup) => applyOperations([{
|
|
107
|
+
kind: "concept.italic",
|
|
108
|
+
id,
|
|
109
|
+
value
|
|
110
|
+
}], historyGroup ? { historyGroup } : void 0),
|
|
101
111
|
addConcept: (position, historyGroup) => {
|
|
102
112
|
const id = newIri();
|
|
103
113
|
return created(id, applyOperations([{
|
|
@@ -217,6 +227,14 @@ function validateGraph(graph) {
|
|
|
217
227
|
path: `concepts[${index}].color`,
|
|
218
228
|
message: `Invalid color: ${concept.id}`
|
|
219
229
|
});
|
|
230
|
+
if (concept.bold !== void 0 && typeof concept.bold !== "boolean") issues.push({
|
|
231
|
+
path: `concepts[${index}].bold`,
|
|
232
|
+
message: "Expected a boolean"
|
|
233
|
+
});
|
|
234
|
+
if (concept.italic !== void 0 && typeof concept.italic !== "boolean") issues.push({
|
|
235
|
+
path: `concepts[${index}].italic`,
|
|
236
|
+
message: "Expected a boolean"
|
|
237
|
+
});
|
|
220
238
|
}
|
|
221
239
|
for (const [index, type] of graph.relationTypes.entries()) {
|
|
222
240
|
if (!isAbsoluteIri(type.id)) issues.push({
|
|
@@ -436,6 +454,16 @@ const operation = z.discriminatedUnion("kind", [
|
|
|
436
454
|
id,
|
|
437
455
|
value: z.string()
|
|
438
456
|
}),
|
|
457
|
+
z.strictObject({
|
|
458
|
+
kind: z.literal("concept.bold"),
|
|
459
|
+
id,
|
|
460
|
+
value: z.boolean()
|
|
461
|
+
}),
|
|
462
|
+
z.strictObject({
|
|
463
|
+
kind: z.literal("concept.italic"),
|
|
464
|
+
id,
|
|
465
|
+
value: z.boolean()
|
|
466
|
+
}),
|
|
439
467
|
z.strictObject({
|
|
440
468
|
kind: z.literal("concept.position"),
|
|
441
469
|
id,
|
|
@@ -553,10 +581,7 @@ const operation = z.discriminatedUnion("kind", [
|
|
|
553
581
|
open: z.boolean()
|
|
554
582
|
})
|
|
555
583
|
]);
|
|
556
|
-
const options = z.strictObject({
|
|
557
|
-
historyGroup: id.optional(),
|
|
558
|
-
atRevision: z.number().int().nonnegative().optional()
|
|
559
|
-
});
|
|
584
|
+
const options = z.strictObject({ historyGroup: id.optional() });
|
|
560
585
|
const metadata = z.strictObject({
|
|
561
586
|
name: localizedText(128),
|
|
562
587
|
description: localizedText(2048),
|
|
@@ -574,6 +599,8 @@ const operationDeclarations = z.array(z.enum([
|
|
|
574
599
|
"concept.label",
|
|
575
600
|
"concept.description",
|
|
576
601
|
"concept.color",
|
|
602
|
+
"concept.bold",
|
|
603
|
+
"concept.italic",
|
|
577
604
|
"concept.position",
|
|
578
605
|
"concept.positions",
|
|
579
606
|
"concept.add",
|
|
@@ -618,6 +645,7 @@ const request = z.discriminatedUnion("method", [
|
|
|
618
645
|
method: z.literal("store.applyOperations"),
|
|
619
646
|
params: z.strictObject({
|
|
620
647
|
operations: z.array(operation).max(5e4),
|
|
648
|
+
revision: z.number().int().nonnegative(),
|
|
621
649
|
options: options.optional()
|
|
622
650
|
})
|
|
623
651
|
}),
|
|
@@ -723,6 +751,8 @@ const graph = z.strictObject({
|
|
|
723
751
|
label: z.string(),
|
|
724
752
|
description: z.string().optional(),
|
|
725
753
|
color: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
|
|
754
|
+
bold: z.boolean().optional(),
|
|
755
|
+
italic: z.boolean().optional(),
|
|
726
756
|
position
|
|
727
757
|
})),
|
|
728
758
|
relationTypes: z.array(relationType),
|
|
@@ -732,14 +762,12 @@ const graph = z.strictObject({
|
|
|
732
762
|
target: id
|
|
733
763
|
}))
|
|
734
764
|
});
|
|
735
|
-
const
|
|
765
|
+
const actionStateSchema = z.strictObject({
|
|
736
766
|
revision: z.number().int().nonnegative(),
|
|
737
767
|
contextId: id,
|
|
738
768
|
locale,
|
|
739
769
|
theme: z.strictObject(Object.fromEntries(themeTokens.map((token) => [token, z.string().max(512).regex(/^[#\w\s.,()%/"'-]*$/)]))),
|
|
740
|
-
conceptPlacementOffset: position
|
|
741
|
-
});
|
|
742
|
-
const viewStateSchema = baseStateSchema.extend({
|
|
770
|
+
conceptPlacementOffset: position,
|
|
743
771
|
viewGraph: graph,
|
|
744
772
|
selected: selection,
|
|
745
773
|
targetViewId: id.nullable(),
|
|
@@ -757,15 +785,14 @@ const viewStateSchema = baseStateSchema.extend({
|
|
|
757
785
|
savedViews: z.array(z.strictObject({
|
|
758
786
|
id,
|
|
759
787
|
name: z.string(),
|
|
760
|
-
pinned: z.boolean()
|
|
761
|
-
conceptIds: z.array(id).optional()
|
|
788
|
+
pinned: z.boolean()
|
|
762
789
|
}))
|
|
763
790
|
})
|
|
764
791
|
});
|
|
765
|
-
const
|
|
792
|
+
const reply = z.union([
|
|
766
793
|
z.strictObject({
|
|
767
794
|
type: z.literal("state"),
|
|
768
|
-
state
|
|
795
|
+
state: actionStateSchema
|
|
769
796
|
}),
|
|
770
797
|
z.strictObject({
|
|
771
798
|
type: z.literal("response"),
|
|
@@ -779,11 +806,6 @@ const replies = (state) => z.union([
|
|
|
779
806
|
ok: z.literal(false),
|
|
780
807
|
error: wireError
|
|
781
808
|
}),
|
|
782
|
-
z.strictObject({
|
|
783
|
-
type: z.literal("invoke"),
|
|
784
|
-
actionId: id,
|
|
785
|
-
invocation: z.strictObject({ viewId: id.nullable() })
|
|
786
|
-
}),
|
|
787
809
|
z.strictObject({
|
|
788
810
|
type: z.literal("close"),
|
|
789
811
|
reason: z.string().max(2048)
|
|
@@ -837,9 +859,8 @@ function checkMessageSize(value, limit) {
|
|
|
837
859
|
}]);
|
|
838
860
|
}
|
|
839
861
|
function createPluginClient(port, initial) {
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
let state = parseOrThrow(schema, initial);
|
|
862
|
+
let state = parseOrThrow(actionStateSchema, initial);
|
|
863
|
+
let readRevision = state.revision;
|
|
843
864
|
let sequence = 0;
|
|
844
865
|
const listeners = /* @__PURE__ */ new Set();
|
|
845
866
|
const controller = new AbortController();
|
|
@@ -936,10 +957,19 @@ function createPluginClient(port, initial) {
|
|
|
936
957
|
};
|
|
937
958
|
port.onmessageerror = close;
|
|
938
959
|
port.start();
|
|
939
|
-
const
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
}
|
|
960
|
+
const getState = () => {
|
|
961
|
+
readRevision = state.revision;
|
|
962
|
+
return state;
|
|
963
|
+
};
|
|
964
|
+
const applyOperations = async (operations, options) => {
|
|
965
|
+
const result = await call("store.applyOperations", {
|
|
966
|
+
operations,
|
|
967
|
+
revision: readRevision,
|
|
968
|
+
...options ? { options } : {}
|
|
969
|
+
});
|
|
970
|
+
readRevision = Math.max(readRevision, result.revision);
|
|
971
|
+
return result;
|
|
972
|
+
};
|
|
943
973
|
const { undo: _undo, redo: _redo, setView: _view, setActiveVocab: _vocab, setActiveTheme: _theme, setLocale: _locale, setPanelSizes: _panels, setSectionOpen: _section, createView: _createView, renameView: _renameView, setViewPinned: _pin, deleteView: _deleteView, ...writes } = createWriteCommands(async (operations, options) => {
|
|
944
974
|
await applyOperations(operations, options);
|
|
945
975
|
}, async (id, committed) => {
|
|
@@ -948,16 +978,17 @@ function createPluginClient(port, initial) {
|
|
|
948
978
|
});
|
|
949
979
|
return {
|
|
950
980
|
context: {
|
|
981
|
+
viewId: state.targetViewId,
|
|
951
982
|
store: {
|
|
952
983
|
...writes,
|
|
953
|
-
getState
|
|
984
|
+
getState,
|
|
954
985
|
subscribe: (listener) => {
|
|
955
986
|
listeners.add(listener);
|
|
956
987
|
return () => listeners.delete(listener);
|
|
957
988
|
},
|
|
958
989
|
refresh: async () => {
|
|
959
990
|
await call("store.refresh", {});
|
|
960
|
-
return
|
|
991
|
+
return getState();
|
|
961
992
|
},
|
|
962
993
|
applyOperations
|
|
963
994
|
},
|
|
@@ -20,6 +20,8 @@ type Concept = {
|
|
|
20
20
|
label: string;
|
|
21
21
|
description?: string;
|
|
22
22
|
color?: string;
|
|
23
|
+
bold?: boolean;
|
|
24
|
+
italic?: boolean;
|
|
23
25
|
position: Position;
|
|
24
26
|
};
|
|
25
27
|
type RelationType = {
|
|
@@ -119,6 +121,14 @@ type NessoOperation = {
|
|
|
119
121
|
readonly kind: 'concept.color';
|
|
120
122
|
readonly id: string;
|
|
121
123
|
readonly value: string;
|
|
124
|
+
} | {
|
|
125
|
+
readonly kind: 'concept.bold';
|
|
126
|
+
readonly id: string;
|
|
127
|
+
readonly value: boolean;
|
|
128
|
+
} | {
|
|
129
|
+
readonly kind: 'concept.italic';
|
|
130
|
+
readonly id: string;
|
|
131
|
+
readonly value: boolean;
|
|
122
132
|
} | {
|
|
123
133
|
readonly kind: 'concept.position';
|
|
124
134
|
readonly id: string;
|
|
@@ -279,6 +289,8 @@ type NessoStore = {
|
|
|
279
289
|
readonly setConceptLabel: (id: string, label: string, historyGroup?: string) => void;
|
|
280
290
|
readonly setConceptDescription: (id: string, description: string, historyGroup?: string) => void;
|
|
281
291
|
readonly setConceptColor: (id: string, color: string, historyGroup?: string) => void;
|
|
292
|
+
readonly setConceptBold: (id: string, value: boolean, historyGroup?: string) => void;
|
|
293
|
+
readonly setConceptItalic: (id: string, value: boolean, historyGroup?: string) => void;
|
|
282
294
|
readonly addConcept: (position?: Readonly<Position>, historyGroup?: string) => string;
|
|
283
295
|
readonly connect: (source: string, target: string) => void;
|
|
284
296
|
readonly reconnectRelation: (id: string, source: string, target: string) => void;
|
|
@@ -403,8 +415,10 @@ declare const manifest: z.ZodDiscriminatedUnion<[z.ZodObject<{
|
|
|
403
415
|
entry: z.ZodString;
|
|
404
416
|
writes: z.ZodArray<z.ZodEnum<{
|
|
405
417
|
"concept.add": "concept.add";
|
|
418
|
+
"concept.bold": "concept.bold";
|
|
406
419
|
"concept.color": "concept.color";
|
|
407
420
|
"concept.description": "concept.description";
|
|
421
|
+
"concept.italic": "concept.italic";
|
|
408
422
|
"concept.label": "concept.label";
|
|
409
423
|
"concept.position": "concept.position";
|
|
410
424
|
"concept.positions": "concept.positions";
|
|
@@ -449,6 +463,14 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
|
|
|
449
463
|
kind: z.ZodLiteral<"concept.color">;
|
|
450
464
|
id: z.ZodString;
|
|
451
465
|
value: z.ZodString;
|
|
466
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
467
|
+
kind: z.ZodLiteral<"concept.bold">;
|
|
468
|
+
id: z.ZodString;
|
|
469
|
+
value: z.ZodBoolean;
|
|
470
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
471
|
+
kind: z.ZodLiteral<"concept.italic">;
|
|
472
|
+
id: z.ZodString;
|
|
473
|
+
value: z.ZodBoolean;
|
|
452
474
|
}, z.core.$strict>, z.ZodObject<{
|
|
453
475
|
kind: z.ZodLiteral<"concept.position">;
|
|
454
476
|
id: z.ZodString;
|
|
@@ -569,9 +591,9 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
|
|
|
569
591
|
}>;
|
|
570
592
|
open: z.ZodBoolean;
|
|
571
593
|
}, z.core.$strict>], "kind">>;
|
|
594
|
+
revision: z.ZodNumber;
|
|
572
595
|
options: z.ZodOptional<z.ZodObject<{
|
|
573
596
|
historyGroup: z.ZodOptional<z.ZodString>;
|
|
574
|
-
atRevision: z.ZodOptional<z.ZodNumber>;
|
|
575
597
|
}, z.core.$strict>>;
|
|
576
598
|
}, z.core.$strict>;
|
|
577
599
|
}, z.core.$strict>, z.ZodObject<{
|
|
@@ -668,13 +690,11 @@ declare const actionIconNames: readonly ['arrow-right', 'book-open', 'clipboard-
|
|
|
668
690
|
type ActionIconName = typeof actionIconNames[number];
|
|
669
691
|
type ActionDescriptor = DeepReadonly<z.infer<typeof actionDescriptor>>;
|
|
670
692
|
type ActionContribution = ActionDescriptor & {
|
|
671
|
-
readonly run: (
|
|
672
|
-
readonly viewId: string | null;
|
|
673
|
-
}) => void | Promise<void>;
|
|
693
|
+
readonly run: (context: ActionContext) => void | Promise<void>;
|
|
674
694
|
};
|
|
675
695
|
declare function parseContribution(kind: 'theme' | 'vocab', value: unknown): Definition;
|
|
676
696
|
declare function parseContribution(kind: 'actions', value: unknown): readonly ActionDescriptor[];
|
|
677
|
-
type
|
|
697
|
+
type ActionState = {
|
|
678
698
|
readonly revision: number;
|
|
679
699
|
readonly contextId: string;
|
|
680
700
|
readonly locale: Locale;
|
|
@@ -683,8 +703,6 @@ type BaseState = {
|
|
|
683
703
|
x: number;
|
|
684
704
|
y: number;
|
|
685
705
|
}>;
|
|
686
|
-
};
|
|
687
|
-
type ViewState = BaseState & {
|
|
688
706
|
readonly viewGraph: GraphSnapshot;
|
|
689
707
|
readonly selected: Selection;
|
|
690
708
|
readonly workspace: {
|
|
@@ -698,17 +716,16 @@ type ViewState = BaseState & {
|
|
|
698
716
|
readonly canRedo: boolean;
|
|
699
717
|
};
|
|
700
718
|
};
|
|
701
|
-
type ActionState = BaseState | ViewState;
|
|
702
719
|
type WriteOptions = {
|
|
703
720
|
readonly historyGroup?: string;
|
|
704
|
-
readonly atRevision?: number;
|
|
705
721
|
};
|
|
706
722
|
type PluginWrites = Omit<ReturnType<typeof createWriteCommands<Promise<void>, Promise<string>>>, 'undo' | 'redo' | 'setView' | 'setActiveVocab' | 'setActiveTheme' | 'setLocale' | 'setPanelSizes' | 'setSectionOpen' | 'createView' | 'renameView' | 'setViewPinned' | 'deleteView'>;
|
|
707
|
-
type
|
|
723
|
+
type ActionContext = {
|
|
724
|
+
readonly viewId: string | null;
|
|
708
725
|
readonly store: PluginWrites & {
|
|
709
|
-
readonly getState: () =>
|
|
726
|
+
readonly getState: () => ActionState;
|
|
710
727
|
readonly subscribe: (listener: () => void) => () => void;
|
|
711
|
-
readonly refresh: () => Promise<
|
|
728
|
+
readonly refresh: () => Promise<ActionState>;
|
|
712
729
|
readonly applyOperations: (operations: readonly NessoOperation[], options?: WriteOptions) => Promise<{
|
|
713
730
|
readonly revision: number;
|
|
714
731
|
readonly changed: boolean;
|
|
@@ -729,13 +746,12 @@ type PluginContext<S extends BaseState = BaseState> = {
|
|
|
729
746
|
};
|
|
730
747
|
readonly signal: AbortSignal;
|
|
731
748
|
};
|
|
732
|
-
type ActionContext = PluginContext<ActionState>;
|
|
733
749
|
declare function parsePluginMessage(value: unknown): z.infer<typeof message>;
|
|
734
750
|
declare function sha256Hex(bytes: Uint8Array): Promise<string>;
|
|
735
751
|
declare function checkMessageSize(value: unknown, limit: number): void;
|
|
736
|
-
declare function createPluginClient
|
|
737
|
-
context:
|
|
752
|
+
declare function createPluginClient(port: MessagePort, initial: unknown): {
|
|
753
|
+
context: ActionContext;
|
|
738
754
|
close: () => void;
|
|
739
755
|
};
|
|
740
756
|
//#endregion
|
|
741
|
-
export {
|
|
757
|
+
export { NessoState as A, Viewport as B, createWriteCommands as C, resolvePluginText as D, LocalizedText as E, PanelSizes as F, parseDefinition as G, WorkspaceState as H, Preferences as I, themeColors as K, SavedView as L, Notification as M, NotificationAction as N, GraphSnapshot as O, Notifications as P, SectionId as R, parseFileOptions as S, parseOrThrow as T, Definition as U, VocabDefinition as V, ThemeDefinition as W, themeTokens as _, ActionState as a, FileSaveOptions as b, actionIconNames as c, parseContribution as d, parsePluginI18n as f, sha256Hex as g, runtimeLimits as h, ActionIconName as i, NessoStore as j, NessoOperation as k, checkMessageSize as l, parsePluginMessage as m, ActionContribution as n, PluginI18n as o, parsePluginManifest as p, ActionDescriptor as r, PluginManifest as s, ActionContext as t, createPluginClient as u, FileOpenOptions as v, PluginError as w, fileTextLimit as x, FileOpenResult as y, Selection as z };
|
package/dist/runtime.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export { ActionContext, ActionContribution, ActionDescriptor, ActionIconName, ActionState,
|
|
1
|
+
import { D as resolvePluginText, E as LocalizedText, G as parseDefinition, K as themeColors, S as parseFileOptions, T as parseOrThrow, U as Definition, _ as themeTokens, a as ActionState, b as FileSaveOptions, c as actionIconNames, d as parseContribution, f as parsePluginI18n, g as sha256Hex, h as runtimeLimits, i as ActionIconName, l as checkMessageSize, m as parsePluginMessage, n as ActionContribution, o as PluginI18n, p as parsePluginManifest, r as ActionDescriptor, s as PluginManifest, t as ActionContext, u as createPluginClient, v as FileOpenOptions, w as PluginError, x as fileTextLimit, y as FileOpenResult } from "./runtime-NJhqaq_J.js";
|
|
2
|
+
export { ActionContext, ActionContribution, ActionDescriptor, ActionIconName, ActionState, type Definition, type FileOpenOptions, type FileOpenResult, type FileSaveOptions, type LocalizedText, PluginError, PluginI18n, PluginManifest, actionIconNames, checkMessageSize, createPluginClient, fileTextLimit, parseContribution, parseDefinition, parseFileOptions, parseOrThrow, parsePluginI18n, parsePluginManifest, parsePluginMessage, resolvePluginText, runtimeLimits, sha256Hex, themeColors, themeTokens };
|
package/dist/runtime.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { _ as PluginError, t as actionIconNames, n as checkMessageSize, r as createPluginClient, f as fileTextLimit, i as parseContribution, m as parseDefinition, p as parseFileOptions, v as parseOrThrow, a as parsePluginI18n, o as parsePluginManifest, s as parsePluginMessage, d as resolvePluginText, c as runtimeLimits, l as sha256Hex, h as themeColors, u as themeTokens } from "./runtime-
|
|
1
|
+
export { _ as PluginError, t as actionIconNames, n as checkMessageSize, r as createPluginClient, f as fileTextLimit, i as parseContribution, m as parseDefinition, p as parseFileOptions, v as parseOrThrow, a as parsePluginI18n, o as parsePluginManifest, s as parsePluginMessage, d as resolvePluginText, c as runtimeLimits, l as sha256Hex, h as themeColors, u as themeTokens } from "./runtime-Dl8Rcuy8.js";
|
package/example/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Omar Desogus and Paolo Manfredotti
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/example/README.md
CHANGED
|
@@ -1,24 +1,36 @@
|
|
|
1
1
|
# Uppercase labels
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The official Nesso action plugin example, published as [`@nesso-how/plugin-example`](https://www.npmjs.com/package/@nesso-how/plugin-example). It uppercases labels in the invoked view with one undoable batch. Shared concepts change in every view containing them.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Install and try
|
|
6
|
+
|
|
7
|
+
In the desktop app, open Settings → Plugins, search for `@nesso-how/plugin-example`, and install it. Approve its declared access to concept labels.
|
|
8
|
+
|
|
9
|
+
Run **Uppercase labels** from a view's context menu in the Explorer, or from the view's actions in the Inspector with no concepts or relations selected. Use Undo to restore the original labels.
|
|
10
|
+
|
|
11
|
+
## Build your own
|
|
12
|
+
|
|
13
|
+
Copy this example into a separate project, then install dependencies and build:
|
|
6
14
|
|
|
7
15
|
```sh
|
|
8
|
-
npm install
|
|
16
|
+
npm install
|
|
9
17
|
npm run build
|
|
10
18
|
```
|
|
11
19
|
|
|
12
|
-
The build typechecks
|
|
20
|
+
The build typechecks `src/index.ts` and bundles it with the package metadata into a self-contained `dist/index.js`.
|
|
21
|
+
|
|
22
|
+
Choose your own package name and action ID before publishing a derived plugin.
|
|
23
|
+
|
|
24
|
+
## Test an unpublished build
|
|
13
25
|
|
|
14
|
-
|
|
26
|
+
Open `package.json` and `dist/index.js` in a text editor. In desktop DevTools, set `manifest` to the parsed package JSON and `compiledCode` to the bundled JavaScript as a string:
|
|
15
27
|
|
|
16
28
|
```ts
|
|
17
|
-
await window.nessoPlugins.propose(
|
|
29
|
+
const result = await window.nessoPlugins.propose(
|
|
18
30
|
crypto.randomUUID(),
|
|
19
31
|
{ manifest, files: [{ path: manifest.nesso.entry, bytes: new TextEncoder().encode(compiledCode) }] },
|
|
20
32
|
'en'
|
|
21
33
|
)
|
|
22
34
|
```
|
|
23
35
|
|
|
24
|
-
Approve the Nesso access dialog. Installation persists
|
|
36
|
+
Approve the Nesso access dialog. Installation persists. On success, `result.value` contains the installed package; it is `null` if approval is declined. Failures return `result.issues`. To replace a build, pass the installed package's `contentId` as the fourth argument; development proposals require fresh approval.
|
package/example/package.json
CHANGED
|
@@ -1,17 +1,27 @@
|
|
|
1
1
|
{
|
|
2
|
-
"name": "nesso-plugin-
|
|
3
|
-
"version": "
|
|
2
|
+
"name": "@nesso-how/plugin-example",
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Uppercase concept labels in the invoked Nesso view",
|
|
5
5
|
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/nesso-how/nesso.git",
|
|
9
|
+
"directory": "packages/plugin/example"
|
|
10
|
+
},
|
|
6
11
|
"type": "module",
|
|
7
12
|
"keywords": ["nesso-plugin"],
|
|
8
|
-
"files": ["dist"],
|
|
13
|
+
"files": ["dist", "src", "tsconfig.json"],
|
|
9
14
|
"scripts": {
|
|
10
15
|
"check": "tsc",
|
|
11
|
-
"build": "npm run check && esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/index.js"
|
|
16
|
+
"build": "npm run check && esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/index.js",
|
|
17
|
+
"prepack": "npm run build"
|
|
18
|
+
},
|
|
19
|
+
"publishConfig": {
|
|
20
|
+
"access": "public",
|
|
21
|
+
"registry": "https://registry.npmjs.org/"
|
|
12
22
|
},
|
|
13
23
|
"devDependencies": {
|
|
14
|
-
"@nesso-how/plugin": "
|
|
24
|
+
"@nesso-how/plugin": "0.3.0",
|
|
15
25
|
"esbuild": "^0.28.2",
|
|
16
26
|
"typescript": "~7.0.2"
|
|
17
27
|
},
|
package/example/src/index.ts
CHANGED
|
@@ -1,13 +1,22 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type { ActionContribution, NessoOperation } from '@nesso-how/plugin'
|
|
2
2
|
import source from '../package.json' with { type: 'json' }
|
|
3
3
|
|
|
4
|
-
export const create = (
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
4
|
+
export const create = (): readonly ActionContribution[] => {
|
|
5
|
+
const action: ActionContribution = {
|
|
6
|
+
id: 'uppercase-labels',
|
|
7
|
+
label: source.i18n.metadata.name,
|
|
8
|
+
run: async ({ store }) => {
|
|
9
|
+
const state = store.getState()
|
|
10
|
+
|
|
11
|
+
const operations: readonly NessoOperation[] = state.viewGraph.concepts.map(({ id, label }) => ({
|
|
12
|
+
kind: 'concept.label',
|
|
13
|
+
id,
|
|
14
|
+
value: label.toUpperCase(),
|
|
15
|
+
}))
|
|
16
|
+
|
|
17
|
+
await store.applyOperations(operations)
|
|
18
|
+
},
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
return [action]
|
|
22
|
+
}
|