@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 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: source.i18n.metadata.name,
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": "Uppercase labels" },
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 `storage`; each authorizes all methods of that API. All fields shown under `nesso` and `i18n.metadata` are required. Add the `nesso-plugin` keyword for discovery in Settings → Plugins.
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 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.
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)` handlers. Use `ActionIconName` for supported icons.
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-BrWPGuBB.js";
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-C-k6OiHL.js";
1
+ export { x as PluginError, t as actionIconNames, b as createWriteCommands } from "./runtime-CJPU4o4h.js";
package/dist/package.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { o as PluginI18n, s as PluginManifest } from "./runtime-BrWPGuBB.js";
1
+ import { o as PluginI18n, s as PluginManifest } from "./runtime-D4jO7tbm.js";
2
2
  //#region src/package.d.ts
3
3
  export declare const packageLimits: {
4
4
  readonly entry: number;
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-C-k6OiHL.js";
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-BrWPGuBB.js";
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-C-k6OiHL.js";
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
- # Uppercase labels
1
+ # Plugin Example
2
2
 
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.
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 **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.
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 build typechecks `src/index.ts` and bundles it with the package metadata into a self-contained `dist/index.js`.
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 ID before publishing a derived plugin.
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
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@nesso-how/plugin-example",
3
- "version": "0.4.0",
4
- "description": "Uppercase concept labels in the invoked Nesso view",
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 && esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/index.js",
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.4.0",
25
- "esbuild": "^0.28.2",
26
- "typescript": "~7.0.2"
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": "Uppercase labels" },
38
- "description": { "en": "Uppercase concept labels in the invoked view." },
39
- "documentation": { "en": "Changes the labels of concepts in the invoked view in one undoable transaction. Concepts shared with other views change there too." }
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
+ }
@@ -1,10 +1,10 @@
1
1
  import type { ActionContribution, NessoOperation } from '@nesso-how/plugin'
2
- import source from '../package.json' with { type: 'json' }
2
+ import { Quiz } from './Quiz.js'
3
3
 
4
4
  export const create = (): readonly ActionContribution[] => {
5
- const action: ActionContribution = {
5
+ const uppercase: ActionContribution = {
6
6
  id: 'uppercase-labels',
7
- label: source.i18n.metadata.name,
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
- return [action]
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
  }
@@ -1,14 +1,16 @@
1
1
  {
2
2
  "compilerOptions": {
3
3
  "target": "ES2022",
4
- "lib": ["ES2022", "WebWorker"],
5
- "module": "NodeNext",
6
- "moduleResolution": "NodeNext",
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.4.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": {