@nesso-how/plugin 0.4.0 → 0.5.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 +46 -7
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/package.d.ts +1 -1
- package/dist/package.js +1 -1
- package/dist/{runtime-C-k6OiHL.js → runtime-CJPU4o4h.js} +27 -4
- package/dist/{runtime-BrWPGuBB.d.ts → runtime-D4jO7tbm.d.ts} +16 -2
- package/dist/runtime.d.ts +1 -1
- package/dist/runtime.js +1 -1
- package/example/README.md +6 -6
- package/example/package.json +19 -11
- package/example/src/Quiz.css +8 -0
- package/example/src/Quiz.tsx +49 -0
- package/example/src/index.ts +11 -4
- package/example/tsconfig.json +6 -4
- package/example/vite.config.ts +14 -0
- package/package.json +6 -1
package/README.md
CHANGED
|
@@ -2,6 +2,16 @@
|
|
|
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
|
+
## Install
|
|
6
|
+
|
|
7
|
+
With Node.js and npm installed, add the SDK to your TypeScript project:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --save-dev @nesso-how/plugin
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
This installs the development SDK, not a plugin in Nesso. If you are starting a new plugin, use the example below for TypeScript and bundler configuration, including React UI support. To install and try your built plugin in the desktop app, follow the [local testing instructions](example/README.md#test-an-unpublished-build).
|
|
14
|
+
|
|
5
15
|
## Create a plugin
|
|
6
16
|
|
|
7
17
|
Copy the [standalone action example](example/) into a separate project. It includes the SDK, TypeScript configuration, and bundler setup:
|
|
@@ -15,12 +25,11 @@ Choose your own package name and action ID, then edit `src/index.ts`:
|
|
|
15
25
|
|
|
16
26
|
```ts
|
|
17
27
|
import type { ActionContribution, NessoOperation } from '@nesso-how/plugin'
|
|
18
|
-
import source from '../package.json' with { type: 'json' }
|
|
19
28
|
|
|
20
29
|
export const create = (): readonly ActionContribution[] => {
|
|
21
30
|
const action: ActionContribution = {
|
|
22
31
|
id: 'uppercase-labels',
|
|
23
|
-
label:
|
|
32
|
+
label: { en: 'Uppercase labels' },
|
|
24
33
|
run: async ({ document }) => {
|
|
25
34
|
const state = document.getState()
|
|
26
35
|
|
|
@@ -64,7 +73,7 @@ Keep the example's build configuration and set these fields in `package.json`:
|
|
|
64
73
|
},
|
|
65
74
|
"i18n": {
|
|
66
75
|
"metadata": {
|
|
67
|
-
"name": { "en": "
|
|
76
|
+
"name": { "en": "Label tools" },
|
|
68
77
|
"description": { "en": "Uppercase concept labels in a view." },
|
|
69
78
|
"documentation": { "en": "Updates labels in one undoable batch." }
|
|
70
79
|
}
|
|
@@ -72,24 +81,54 @@ Keep the example's build configuration and set these fields in `package.json`:
|
|
|
72
81
|
}
|
|
73
82
|
```
|
|
74
83
|
|
|
75
|
-
Declare the operations your action uses in `writes`. The optional permissions listed in `capabilities` are `files`, `notifications`, and `
|
|
84
|
+
Declare the operations your action uses in `writes`. The optional permissions listed in `capabilities` are `files`, `notifications`, `storage`, and `ui`. The first three authorize their APIs; `ui` authorizes interactive UI contributions. All fields shown under `nesso` and `i18n.metadata` are required. Add the `nesso-plugin` keyword for discovery in Settings → Plugins.
|
|
76
85
|
|
|
77
|
-
Labels and metadata use `{ en: string, it?: string, 'zh-CN'?: string }`, with English required as the fallback.
|
|
86
|
+
`i18n.metadata.name` names the plugin in Settings. Each action defines its own `label` for menus, independently of the plugin name. Labels and metadata use `{ en: string, it?: string, 'zh-CN'?: string }`, with English required as the fallback.
|
|
78
87
|
|
|
79
88
|
### Build and test
|
|
80
89
|
|
|
81
90
|
Run `npm run build`, then follow the example's [local testing instructions](example/README.md#test-an-unpublished-build).
|
|
82
91
|
|
|
83
|
-
Actions
|
|
92
|
+
Actions ship one browser ES module with dependencies bundled except React and React DOM, which Nesso supplies inside the sandbox. Keep `react`, `react/*`, `react-dom`, and `react-dom/*` external in your bundler; the example's build handles this. The runtime supports React 19. Test and install external plugins in the desktop app.
|
|
84
93
|
|
|
85
94
|
## Action API
|
|
86
95
|
|
|
87
96
|
Nesso passes `{ document, storage, files, notifications, signal, viewId }` to `run` as `ActionContext`. `document` exposes the shared graph, view membership, and transient selection; `storage` holds the plugin's private data for that document.
|
|
88
97
|
|
|
89
|
-
`create()` receives no arguments and returns an array of actions with unique lowercase kebab-case IDs, localized labels, optional icons, and `run(context)`
|
|
98
|
+
`create()` receives no arguments and returns an array of actions with unique lowercase kebab-case IDs, localized labels, optional icons, and either a `run(context)` handler or a React component in `ui`. The two forms are mutually exclusive. Use `ActionIconName` for supported icons.
|
|
90
99
|
|
|
91
100
|
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.
|
|
92
101
|
|
|
102
|
+
### Action UI
|
|
103
|
+
|
|
104
|
+
Declare the `ui` capability and set the action's `ui` property to a React component instead of a `run` handler. Nesso mounts it in an isolated central panel and unmounts it when the session ends.
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
import { useSyncExternalStore } from 'react'
|
|
108
|
+
import type { ActionContext, ActionContribution } from '@nesso-how/plugin'
|
|
109
|
+
|
|
110
|
+
function Browse({ document }: ActionContext) {
|
|
111
|
+
const state = useSyncExternalStore(document.subscribe, document.getState)
|
|
112
|
+
return <ul>{state.viewGraph.concepts.map(({ id, label }) => <li key={id}>{label}</li>)}</ul>
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
export const create = (): readonly ActionContribution[] => [
|
|
116
|
+
{ id: 'browse', label: { en: 'Browse concepts' }, ui: Browse },
|
|
117
|
+
]
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
#### Context
|
|
121
|
+
|
|
122
|
+
Components receive `ActionContext` directly as props, with the same APIs and permissions as `run`. `viewId` and the supplied `viewGraph` refer to the invoked view. Subscribe with `useSyncExternalStore` when rendering snapshot data. Discovery runs `create()` in a Worker, so keep DOM access and effects inside components or `run`, not at module scope or in `create()`. The panel can access its own DOM, but not the host DOM, native bridge, network, or direct persistent storage; use the injected APIs for files and storage.
|
|
123
|
+
|
|
124
|
+
#### Styling
|
|
125
|
+
|
|
126
|
+
Nesso supplies React, the `@nesso-how/ui` component stylesheet, and theme CSS variables such as `var(--background)` and `var(--foreground)`. Import your own CSS normally; the [standalone example](example/) bundles and injects it. Bundle dependencies other than React/React DOM and inline assets; remote or separate assets are not supported. The host does not compile plugin Tailwind classes. Read `locale` from `document.getState()` for translated content. Label inputs and preserve Tab/Shift+Tab navigation.
|
|
127
|
+
|
|
128
|
+
#### Lifecycle
|
|
129
|
+
|
|
130
|
+
Use React effects to clean up subscriptions and resources. Panels have no action execution timeout, but initialization and API requests have deadlines. Uncaught errors or rejected promises fail the session; handle expected errors in your UI. Nesso provides the title, close control, and loading/failure screens. Closing or replacing a panel discards its React state: save progress through `storage` during use, not during cleanup, which is best effort.
|
|
131
|
+
|
|
93
132
|
### Read the invoked view
|
|
94
133
|
|
|
95
134
|
- `document.getState()` returns the latest readonly local snapshot synchronously and makes it the basis for subsequent writes.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { A as createWriteCommands, B as NotificationAction, F as GraphSnapshot, G as SectionId, H as PanelSizes, I as NessoOperation, J as VocabDefinition, K as Selection, L as NessoState, N as LocalizedText, R as NessoStore, U as Preferences, V as Notifications, W as SavedView, Y as WorkspaceState, Z as ThemeDefinition, a as ActionState, b as PluginStorageRecord, c as actionIconNames, i as ActionIconName, j as PluginError, n as ActionContribution, o as PluginI18n, q as Viewport, r as ActionDescriptor, s as PluginManifest, t as ActionContext, v as PluginStorage, y as PluginStorageKey, z as Notification } from "./runtime-
|
|
1
|
+
import { A as createWriteCommands, B as NotificationAction, F as GraphSnapshot, G as SectionId, H as PanelSizes, I as NessoOperation, J as VocabDefinition, K as Selection, L as NessoState, N as LocalizedText, R as NessoStore, U as Preferences, V as Notifications, W as SavedView, Y as WorkspaceState, Z as ThemeDefinition, a as ActionState, b as PluginStorageRecord, c as actionIconNames, i as ActionIconName, j as PluginError, n as ActionContribution, o as PluginI18n, q as Viewport, r as ActionDescriptor, s as PluginManifest, t as ActionContext, v as PluginStorage, y as PluginStorageKey, z as Notification } from "./runtime-D4jO7tbm.js";
|
|
2
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 PluginStorage, type PluginStorageKey, type PluginStorageRecord, 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 { x as PluginError, t as actionIconNames, b as createWriteCommands } from "./runtime-
|
|
1
|
+
export { x as PluginError, t as actionIconNames, b as createWriteCommands } from "./runtime-CJPU4o4h.js";
|
package/dist/package.d.ts
CHANGED
package/dist/package.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { S as parseOrThrow, a as parsePluginManifest, c as sha256Hex, i as parsePluginI18n, m as checkMessageSize, v as parseDefinition, x as PluginError } from "./runtime-
|
|
1
|
+
import { S as parseOrThrow, a as parsePluginManifest, c as sha256Hex, i as parsePluginI18n, m as checkMessageSize, v as parseDefinition, x as PluginError } from "./runtime-CJPU4o4h.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";
|
|
@@ -494,7 +494,8 @@ const runtimeLimits = {
|
|
|
494
494
|
deadline: 3e4,
|
|
495
495
|
interaction: 3e5,
|
|
496
496
|
initialization: 1e4,
|
|
497
|
-
action: 12e4
|
|
497
|
+
action: 12e4,
|
|
498
|
+
heartbeat: 15e3
|
|
498
499
|
};
|
|
499
500
|
const themeTokens = [
|
|
500
501
|
...themeColors,
|
|
@@ -705,7 +706,8 @@ const manifest = z.discriminatedUnion("kind", [z.strictObject({
|
|
|
705
706
|
capabilities: z.array(z.enum([
|
|
706
707
|
"files",
|
|
707
708
|
"notifications",
|
|
708
|
-
"storage"
|
|
709
|
+
"storage",
|
|
710
|
+
"ui"
|
|
709
711
|
]))
|
|
710
712
|
}), ...["theme", "vocab"].map((kind) => z.strictObject({
|
|
711
713
|
...manifestFields,
|
|
@@ -793,6 +795,11 @@ const wireError = z.strictObject({
|
|
|
793
795
|
});
|
|
794
796
|
const message = z.union([
|
|
795
797
|
request,
|
|
798
|
+
z.strictObject({ type: z.literal("panel-ready") }),
|
|
799
|
+
z.strictObject({
|
|
800
|
+
type: z.literal("pong"),
|
|
801
|
+
id: z.number().int().positive()
|
|
802
|
+
}),
|
|
796
803
|
z.strictObject({
|
|
797
804
|
type: z.literal("contribution"),
|
|
798
805
|
value: z.unknown()
|
|
@@ -814,7 +821,8 @@ const message = z.union([
|
|
|
814
821
|
const actionDescriptor = z.strictObject({
|
|
815
822
|
id: z.string().max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
|
|
816
823
|
label: localizedText(128),
|
|
817
|
-
icon: z.string().min(1).max(32).regex(/^[a-z]+(?:-[a-z]+)*$/).optional()
|
|
824
|
+
icon: z.string().min(1).max(32).regex(/^[a-z]+(?:-[a-z]+)*$/).optional(),
|
|
825
|
+
ui: z.literal(true).optional()
|
|
818
826
|
});
|
|
819
827
|
const actionIconNames = [
|
|
820
828
|
"arrow-right",
|
|
@@ -889,6 +897,10 @@ const actionStateSchema = z.strictObject({
|
|
|
889
897
|
})
|
|
890
898
|
});
|
|
891
899
|
const reply = z.union([
|
|
900
|
+
z.strictObject({
|
|
901
|
+
type: z.literal("ping"),
|
|
902
|
+
id: z.number().int().positive()
|
|
903
|
+
}),
|
|
892
904
|
z.strictObject({
|
|
893
905
|
type: z.literal("state"),
|
|
894
906
|
state: actionStateSchema
|
|
@@ -1008,6 +1020,13 @@ function createPluginClient(port, initial) {
|
|
|
1008
1020
|
return;
|
|
1009
1021
|
}
|
|
1010
1022
|
const data = parsed.data;
|
|
1023
|
+
if (data.type === "ping") {
|
|
1024
|
+
port.postMessage({
|
|
1025
|
+
type: "pong",
|
|
1026
|
+
id: data.id
|
|
1027
|
+
});
|
|
1028
|
+
return;
|
|
1029
|
+
}
|
|
1011
1030
|
if (data.type === "close") {
|
|
1012
1031
|
close();
|
|
1013
1032
|
return;
|
|
@@ -1108,7 +1127,11 @@ function createPluginClient(port, initial) {
|
|
|
1108
1127
|
},
|
|
1109
1128
|
signal: controller.signal
|
|
1110
1129
|
},
|
|
1111
|
-
close
|
|
1130
|
+
close,
|
|
1131
|
+
getPresentation: () => ({
|
|
1132
|
+
theme: state.theme,
|
|
1133
|
+
locale: state.locale
|
|
1134
|
+
})
|
|
1112
1135
|
};
|
|
1113
1136
|
}
|
|
1114
1137
|
//#endregion
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { ZodType, z } from "zod";
|
|
2
|
+
import { ComponentType } from "react";
|
|
2
3
|
//#region ../errors/src/index.d.ts
|
|
3
4
|
type ErrorIssue = {
|
|
4
5
|
path: string;
|
|
@@ -432,6 +433,7 @@ declare const runtimeLimits: {
|
|
|
432
433
|
readonly interaction: 300000;
|
|
433
434
|
readonly initialization: 10000;
|
|
434
435
|
readonly action: 120000;
|
|
436
|
+
readonly heartbeat: 15000;
|
|
435
437
|
};
|
|
436
438
|
declare const themeTokens: readonly ["background", "foreground", "canvas", "sidebar", "primary", "primary-hover", "primary-foreground", "muted", "muted-foreground", "hover", "pressed", "border", "ring", "selection-halo", "node-border", "edge", "handle", "font-sans", "font-mono", "radius-control", "radius-object", "duration-state"];
|
|
437
439
|
declare const metadata: z.ZodObject<{
|
|
@@ -482,6 +484,7 @@ declare const manifest: z.ZodDiscriminatedUnion<[z.ZodObject<{
|
|
|
482
484
|
files: "files";
|
|
483
485
|
notifications: "notifications";
|
|
484
486
|
storage: "storage";
|
|
487
|
+
ui: "ui";
|
|
485
488
|
}>>;
|
|
486
489
|
}, z.core.$strict>, ...z.ZodObject<{
|
|
487
490
|
apiVersion: z.ZodLiteral<1>;
|
|
@@ -813,6 +816,11 @@ declare const message: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject
|
|
|
813
816
|
text: z.ZodString;
|
|
814
817
|
}, z.core.$strict>;
|
|
815
818
|
}, z.core.$strict>], "method">, z.ZodObject<{
|
|
819
|
+
type: z.ZodLiteral<"panel-ready">;
|
|
820
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
821
|
+
type: z.ZodLiteral<"pong">;
|
|
822
|
+
id: z.ZodNumber;
|
|
823
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
816
824
|
type: z.ZodLiteral<"contribution">;
|
|
817
825
|
value: z.ZodUnknown;
|
|
818
826
|
}, z.core.$strict>, z.ZodObject<{
|
|
@@ -855,13 +863,18 @@ declare const actionDescriptor: z.ZodObject<{
|
|
|
855
863
|
'zh-CN': z.ZodOptional<z.ZodString>;
|
|
856
864
|
}, z.core.$strict>;
|
|
857
865
|
icon: z.ZodOptional<z.ZodString>;
|
|
866
|
+
ui: z.ZodOptional<z.ZodLiteral<true>>;
|
|
858
867
|
}, z.core.$strict>;
|
|
859
868
|
declare const actionIconNames: readonly ['arrow-right', 'book-open', 'clipboard-paste', 'copy', 'download', 'file-down', 'file-up', 'folder', 'globe', 'layers', 'pencil', 'play', 'plus', 'refresh', 'scissors', 'search', 'share', 'sparkles', 'upload', 'zap'];
|
|
860
869
|
type ActionIconName = typeof actionIconNames[number];
|
|
861
870
|
type ActionDescriptor = DeepReadonly<z.infer<typeof actionDescriptor>>;
|
|
862
|
-
type ActionContribution = ActionDescriptor & {
|
|
871
|
+
type ActionContribution = Omit<ActionDescriptor, 'ui'> & ({
|
|
872
|
+
readonly ui: ComponentType<ActionContext>;
|
|
873
|
+
readonly run?: never;
|
|
874
|
+
} | {
|
|
875
|
+
readonly ui?: never;
|
|
863
876
|
readonly run: (context: ActionContext) => void | Promise<void>;
|
|
864
|
-
};
|
|
877
|
+
});
|
|
865
878
|
declare function parseContribution(kind: 'theme' | 'vocab', value: unknown): Definition;
|
|
866
879
|
declare function parseContribution(kind: 'actions', value: unknown): readonly ActionDescriptor[];
|
|
867
880
|
type ActionState = {
|
|
@@ -922,6 +935,7 @@ declare function sha256Hex(bytes: Uint8Array): Promise<string>;
|
|
|
922
935
|
declare function createPluginClient(port: MessagePort, initial: unknown): {
|
|
923
936
|
context: ActionContext;
|
|
924
937
|
close: () => void;
|
|
938
|
+
getPresentation: () => Pick<ActionState, 'theme' | 'locale'>;
|
|
925
939
|
};
|
|
926
940
|
//#endregion
|
|
927
941
|
export { themeColors as $, createWriteCommands as A, NotificationAction as B, parsePluginStorageSnapshot as C, FileSaveOptions as D, FileOpenResult as E, GraphSnapshot as F, SectionId as G, PanelSizes as H, NessoOperation as I, VocabDefinition as J, Selection as K, NessoState as L, parseOrThrow as M, LocalizedText as N, fileTextLimit as O, resolvePluginText as P, parseDefinition as Q, NessoStore as R, parsePluginStorageRecord as S, FileOpenOptions as T, Preferences as U, Notifications as V, SavedView as W, Definition as X, WorkspaceState as Y, ThemeDefinition as Z, checkMessageSize as _, ActionState as a, PluginStorageRecord as b, actionIconNames as c, parsePluginI18n as d, parsePluginManifest as f, themeTokens as g, sha256Hex as h, ActionIconName as i, PluginError as j, parseFileOptions as k, createPluginClient as l, runtimeLimits as m, ActionContribution as n, PluginI18n as o, parsePluginMessage as p, Viewport as q, ActionDescriptor as r, PluginManifest as s, ActionContext as t, parseContribution as u, PluginStorage as v, pluginStorageLimits as w, parsePluginStorageKey as x, PluginStorageKey as y, Notification as z };
|
package/dist/runtime.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { $ as themeColors, C as parsePluginStorageSnapshot, D as FileSaveOptions, E as FileOpenResult, M as parseOrThrow, N as LocalizedText, O as fileTextLimit, P as resolvePluginText, Q as parseDefinition, S as parsePluginStorageRecord, T as FileOpenOptions, X as Definition, _ as checkMessageSize, a as ActionState, c as actionIconNames, d as parsePluginI18n, f as parsePluginManifest, g as themeTokens, h as sha256Hex, i as ActionIconName, j as PluginError, k as parseFileOptions, l as createPluginClient, m as runtimeLimits, n as ActionContribution, o as PluginI18n, p as parsePluginMessage, r as ActionDescriptor, s as PluginManifest, t as ActionContext, u as parseContribution, w as pluginStorageLimits, x as parsePluginStorageKey } from "./runtime-
|
|
1
|
+
import { $ as themeColors, C as parsePluginStorageSnapshot, D as FileSaveOptions, E as FileOpenResult, M as parseOrThrow, N as LocalizedText, O as fileTextLimit, P as resolvePluginText, Q as parseDefinition, S as parsePluginStorageRecord, T as FileOpenOptions, X as Definition, _ as checkMessageSize, a as ActionState, c as actionIconNames, d as parsePluginI18n, f as parsePluginManifest, g as themeTokens, h as sha256Hex, i as ActionIconName, j as PluginError, k as parseFileOptions, l as createPluginClient, m as runtimeLimits, n as ActionContribution, o as PluginI18n, p as parsePluginMessage, r as ActionDescriptor, s as PluginManifest, t as ActionContext, u as parseContribution, w as pluginStorageLimits, x as parsePluginStorageKey } from "./runtime-D4jO7tbm.js";
|
|
2
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, parsePluginStorageKey, parsePluginStorageRecord, parsePluginStorageSnapshot, pluginStorageLimits, resolvePluginText, runtimeLimits, sha256Hex, themeColors, themeTokens };
|
package/dist/runtime.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { x as PluginError, t as actionIconNames, m as checkMessageSize, n as createPluginClient, g as fileTextLimit, r as parseContribution, v as parseDefinition, _ as parseFileOptions, S as parseOrThrow, i as parsePluginI18n, a as parsePluginManifest, o as parsePluginMessage, u as parsePluginStorageKey, d as parsePluginStorageRecord, f as parsePluginStorageSnapshot, p as pluginStorageLimits, h as resolvePluginText, s as runtimeLimits, c as sha256Hex, y as themeColors, l as themeTokens } from "./runtime-
|
|
1
|
+
export { x as PluginError, t as actionIconNames, m as checkMessageSize, n as createPluginClient, g as fileTextLimit, r as parseContribution, v as parseDefinition, _ as parseFileOptions, S as parseOrThrow, i as parsePluginI18n, a as parsePluginManifest, o as parsePluginMessage, u as parsePluginStorageKey, d as parsePluginStorageRecord, f as parsePluginStorageSnapshot, p as pluginStorageLimits, h as resolvePluginText, s as runtimeLimits, c as sha256Hex, y as themeColors, l as themeTokens } from "./runtime-CJPU4o4h.js";
|
package/example/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Plugin Example
|
|
2
2
|
|
|
3
|
-
The official Nesso
|
|
3
|
+
The official Nesso plugin example: an **Uppercase labels** action and a React **Concept Quiz** with persistent progress. See [`src/index.ts`](src/index.ts) and [`src/Quiz.tsx`](src/Quiz.tsx).
|
|
4
4
|
|
|
5
5
|
## Install and try
|
|
6
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.
|
|
7
|
+
In the desktop app, open Settings → Plugins, search for `@nesso-how/plugin-example`, and install it. Approve its declared access to concept labels, interactive panels, and private storage. The panel example requires the SDK and app versions containing central-panel support; build from this checkout until that SDK release is published.
|
|
8
8
|
|
|
9
|
-
Run
|
|
9
|
+
Run either action from a view's context menu in the Explorer, or from its actions in the Inspector with nothing selected.
|
|
10
10
|
|
|
11
11
|
## Build your own
|
|
12
12
|
|
|
@@ -17,9 +17,9 @@ npm install
|
|
|
17
17
|
npm run build
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
The
|
|
20
|
+
The Vite configuration bundles code and imported CSS into `dist/index.js`, leaving React and React DOM to Nesso. See the [UI contract](../README.md#action-ui) for runtime requirements.
|
|
21
21
|
|
|
22
|
-
Choose your own package name and action
|
|
22
|
+
Choose your own package name, plugin metadata, and action IDs and labels before publishing.
|
|
23
23
|
|
|
24
24
|
## Test an unpublished build
|
|
25
25
|
|
package/example/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nesso-how/plugin-example",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.5.0",
|
|
4
|
+
"description": "Official example showing how to build Nesso plugins with the SDK and plugin APIs",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -10,33 +10,41 @@
|
|
|
10
10
|
},
|
|
11
11
|
"type": "module",
|
|
12
12
|
"keywords": ["nesso-plugin"],
|
|
13
|
-
"files": ["dist", "src", "tsconfig.json"],
|
|
13
|
+
"files": ["dist", "src", "tsconfig.json", "vite.config.ts"],
|
|
14
14
|
"scripts": {
|
|
15
15
|
"check": "tsc",
|
|
16
|
-
"build": "npm run check &&
|
|
16
|
+
"build": "npm run check && vite build",
|
|
17
17
|
"prepack": "npm run build"
|
|
18
18
|
},
|
|
19
19
|
"publishConfig": {
|
|
20
20
|
"access": "public",
|
|
21
21
|
"registry": "https://registry.npmjs.org/"
|
|
22
22
|
},
|
|
23
|
+
"dependencies": {
|
|
24
|
+
"@nesso-how/ui": "1.0.0-alpha.31",
|
|
25
|
+
"react": "^19.2.8",
|
|
26
|
+
"react-dom": "^19.2.8"
|
|
27
|
+
},
|
|
23
28
|
"devDependencies": {
|
|
24
|
-
"@nesso-how/plugin": "0.
|
|
25
|
-
"
|
|
26
|
-
"
|
|
29
|
+
"@nesso-how/plugin": "0.5.0",
|
|
30
|
+
"@types/react": "^19.2.18",
|
|
31
|
+
"@types/react-dom": "^19.2.7",
|
|
32
|
+
"typescript": "~7.0.2",
|
|
33
|
+
"vite": "^8.3.0",
|
|
34
|
+
"vite-plugin-css-injected-by-js": "^5.0.3"
|
|
27
35
|
},
|
|
28
36
|
"nesso": {
|
|
29
37
|
"apiVersion": 1,
|
|
30
38
|
"kind": "actions",
|
|
31
39
|
"entry": "dist/index.js",
|
|
32
40
|
"writes": ["concept.label"],
|
|
33
|
-
"capabilities": []
|
|
41
|
+
"capabilities": ["ui", "storage"]
|
|
34
42
|
},
|
|
35
43
|
"i18n": {
|
|
36
44
|
"metadata": {
|
|
37
|
-
"name": { "en": "
|
|
38
|
-
"description": { "en": "
|
|
39
|
-
"documentation": { "en": "
|
|
45
|
+
"name": { "en": "Plugin Example" },
|
|
46
|
+
"description": { "en": "Learn how to build Nesso plugins with the SDK and plugin APIs." },
|
|
47
|
+
"documentation": { "en": "A reference plugin for developers, with practical examples of using Nesso's SDK and plugin APIs to define actions, interact with graph data, and build custom interfaces." }
|
|
40
48
|
}
|
|
41
49
|
}
|
|
42
50
|
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
.quiz { display: grid; min-height: 100dvh; place-items: center; padding: 24px; color: var(--foreground); font: 13px/1.5 var(--font-sans), system-ui, sans-serif; }
|
|
2
|
+
.quiz-card { width: 100%; max-width: 560px; overflow-wrap: anywhere; text-align: center; }
|
|
3
|
+
.quiz h1 { margin: 0 0 4px; font-size: 20px; font-weight: 500; }
|
|
4
|
+
.quiz [data-step] { margin: 0 0 16px; color: var(--muted-foreground); }
|
|
5
|
+
.quiz [data-question] { margin: 0; color: var(--muted-foreground); }
|
|
6
|
+
.quiz [data-answer] { min-height: 1.5em; margin: 16px 0; font-size: 18px; }
|
|
7
|
+
.quiz [data-result] { width: fit-content; margin: 8px auto 24px; padding: 16px 24px; border: 1px solid var(--border); border-radius: 12px; background: var(--muted); font-size: 18px; font-weight: 500; }
|
|
8
|
+
.quiz footer { display: flex; justify-content: center; gap: 8px; }
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { useEffect, useState } from 'react'
|
|
2
|
+
import { Button } from '@nesso-how/ui'
|
|
3
|
+
import type { ActionContext } from '@nesso-how/plugin'
|
|
4
|
+
import './Quiz.css'
|
|
5
|
+
|
|
6
|
+
export function Quiz({ document, storage, viewId }: ActionContext) {
|
|
7
|
+
const [step, setStep] = useState<number | null>(null)
|
|
8
|
+
const [revealed, setRevealed] = useState(false)
|
|
9
|
+
const key = `quiz:${viewId ?? 'all'}`
|
|
10
|
+
|
|
11
|
+
useEffect(() => {
|
|
12
|
+
void storage.list().then((records) => {
|
|
13
|
+
const value = records.find((record) => record.key === key && record.conceptId === undefined)?.value
|
|
14
|
+
setStep(typeof value === 'number' ? value : 0)
|
|
15
|
+
})
|
|
16
|
+
}, [storage, key])
|
|
17
|
+
|
|
18
|
+
async function saveStep(next: number) {
|
|
19
|
+
setStep(null)
|
|
20
|
+
await storage.set(key, next)
|
|
21
|
+
setRevealed(false)
|
|
22
|
+
setStep(next)
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
if (step === null) return null
|
|
26
|
+
|
|
27
|
+
const { concepts, relations, relationTypes } = document.getState().viewGraph
|
|
28
|
+
const relation = relations[step]
|
|
29
|
+
const relationType = relationTypes.find(({ id }) => id === relation?.predicate)
|
|
30
|
+
const conceptLabel = (id: string) => concepts.find((item) => item.id === id)?.label || id
|
|
31
|
+
const buttonLabel = !relation ? 'Completed' : revealed ? 'Next' : 'Show concept'
|
|
32
|
+
|
|
33
|
+
return (
|
|
34
|
+
<section className="quiz">
|
|
35
|
+
<div className="quiz-card">
|
|
36
|
+
<h1>Concept Quiz</h1>
|
|
37
|
+
<p data-step>Step {Math.min(step + 1, relations.length)} / {relations.length}</p>
|
|
38
|
+
{relation ? <>
|
|
39
|
+
<p data-question>{conceptLabel(relation.source)} — {relationType?.label || relation.predicate} → ?</p>
|
|
40
|
+
<p data-answer role="status">{revealed ? conceptLabel(relation.target) : ''}</p>
|
|
41
|
+
</> : <p data-result role="status">{relations.length ? 'Quiz complete!' : 'This view has no relations.'}</p>}
|
|
42
|
+
<footer>
|
|
43
|
+
<Button variant="outline" onClick={() => void saveStep(0)}>Reset</Button>
|
|
44
|
+
<Button disabled={!relation} onClick={() => revealed ? void saveStep(step + 1) : setRevealed(true)}>{buttonLabel}</Button>
|
|
45
|
+
</footer>
|
|
46
|
+
</div>
|
|
47
|
+
</section>
|
|
48
|
+
)
|
|
49
|
+
}
|
package/example/src/index.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
import type { ActionContribution, NessoOperation } from '@nesso-how/plugin'
|
|
2
|
-
import
|
|
2
|
+
import { Quiz } from './Quiz.js'
|
|
3
3
|
|
|
4
4
|
export const create = (): readonly ActionContribution[] => {
|
|
5
|
-
const
|
|
5
|
+
const uppercase: ActionContribution = {
|
|
6
6
|
id: 'uppercase-labels',
|
|
7
|
-
label:
|
|
7
|
+
label: { en: 'Uppercase labels' },
|
|
8
8
|
run: async ({ document }) => {
|
|
9
9
|
const state = document.getState()
|
|
10
10
|
|
|
@@ -18,5 +18,12 @@ export const create = (): readonly ActionContribution[] => {
|
|
|
18
18
|
},
|
|
19
19
|
}
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
const quiz: ActionContribution = {
|
|
22
|
+
id: 'concept-quiz',
|
|
23
|
+
label: { en: 'Concept Quiz' },
|
|
24
|
+
ui: Quiz,
|
|
25
|
+
icon: 'play',
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
return [uppercase, quiz]
|
|
22
29
|
}
|
package/example/tsconfig.json
CHANGED
|
@@ -1,14 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"compilerOptions": {
|
|
3
3
|
"target": "ES2022",
|
|
4
|
-
"lib": ["ES2022", "
|
|
5
|
-
"module": "
|
|
6
|
-
"moduleResolution": "
|
|
4
|
+
"lib": ["ES2022", "DOM", "DOM.Iterable"],
|
|
5
|
+
"module": "ESNext",
|
|
6
|
+
"moduleResolution": "Bundler",
|
|
7
|
+
"jsx": "react-jsx",
|
|
7
8
|
"resolveJsonModule": true,
|
|
9
|
+
"allowImportingTsExtensions": true,
|
|
8
10
|
"strict": true,
|
|
9
11
|
"verbatimModuleSyntax": true,
|
|
10
12
|
"noEmit": true,
|
|
11
|
-
"types": []
|
|
13
|
+
"types": ["vite/client"]
|
|
12
14
|
},
|
|
13
15
|
"include": ["src"]
|
|
14
16
|
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { defineConfig } from 'vite'
|
|
2
|
+
import cssInjectedByJs from 'vite-plugin-css-injected-by-js'
|
|
3
|
+
|
|
4
|
+
export default defineConfig({
|
|
5
|
+
root: import.meta.dirname,
|
|
6
|
+
publicDir: false,
|
|
7
|
+
plugins: [cssInjectedByJs()],
|
|
8
|
+
define: { 'process.env.NODE_ENV': '"production"' },
|
|
9
|
+
build: {
|
|
10
|
+
target: 'es2022',
|
|
11
|
+
lib: { entry: 'src/index.ts', formats: ['es'], fileName: () => 'index.js' },
|
|
12
|
+
rolldownOptions: { external: /^react(?:-dom)?(?:\/|$)/ },
|
|
13
|
+
},
|
|
14
|
+
})
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nesso-how/plugin",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Types, validation, and asynchronous clients for isolated Nesso plugins",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -32,6 +32,7 @@
|
|
|
32
32
|
"access": "public"
|
|
33
33
|
},
|
|
34
34
|
"dependencies": {
|
|
35
|
+
"@types/react": "^19.3.0",
|
|
35
36
|
"semver": "^7.8.5",
|
|
36
37
|
"validate-npm-package-name": "^8.0.0",
|
|
37
38
|
"zod": "^4.6.5"
|
|
@@ -40,8 +41,12 @@
|
|
|
40
41
|
"@nesso-how/errors": "0.0.0",
|
|
41
42
|
"@nesso-how/i18n": "0.0.0",
|
|
42
43
|
"@nesso-how/schema": "0.0.0",
|
|
44
|
+
"@types/react-dom": "^19.3.0",
|
|
43
45
|
"@types/semver": "^7.8.0",
|
|
44
46
|
"@types/validate-npm-package-name": "^4.0.2",
|
|
47
|
+
"es-module-lexer": "^3.0.4",
|
|
48
|
+
"react": "^19.3.0",
|
|
49
|
+
"react-dom": "^19.3.0",
|
|
45
50
|
"tsdown": "^0.23.1"
|
|
46
51
|
},
|
|
47
52
|
"scripts": {
|