@nesso-how/plugin 0.5.0 → 0.6.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 +77 -46
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/node/data.d.ts +1 -0
- package/dist/node/data.js +28 -0
- package/dist/node/definitions.d.ts +69 -0
- package/dist/node/definitions.js +124 -0
- package/dist/node/errors.d.ts +10 -0
- package/dist/node/errors.js +45 -0
- package/dist/node/files.d.ts +20 -0
- package/dist/node/files.js +36 -0
- package/dist/node/i18n.d.ts +12 -0
- package/dist/node/i18n.js +11 -0
- package/dist/node/index.d.ts +6 -0
- package/dist/node/index.js +2 -0
- package/dist/node/package.d.ts +34 -0
- package/dist/node/package.js +224 -0
- package/dist/node/runtime.d.ts +555 -0
- package/dist/node/runtime.js +513 -0
- package/dist/node/storage.d.ts +46 -0
- package/dist/node/storage.js +67 -0
- package/dist/node/theme-fonts.d.ts +2 -0
- package/dist/node/theme-fonts.js +11 -0
- package/dist/package.d.ts +1 -1
- package/dist/package.js +1 -1
- package/dist/{runtime-CJPU4o4h.js → runtime-BM45o1qi.js} +281 -216
- package/dist/{runtime-D4jO7tbm.d.ts → runtime-BxtTAcko.d.ts} +144 -122
- package/dist/runtime.d.ts +2 -2
- package/dist/runtime.js +1 -1
- package/example/README.md +5 -2
- package/example/package.json +36 -18
- package/example/src/Quiz.css +50 -8
- package/example/src/Quiz.tsx +29 -8
- package/example/src/index.ts +7 -5
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -33,11 +33,13 @@ export const create = (): readonly ActionContribution[] => {
|
|
|
33
33
|
run: async ({ document }) => {
|
|
34
34
|
const state = document.getState()
|
|
35
35
|
|
|
36
|
-
const operations: readonly NessoOperation[] = state.viewGraph.concepts.map(
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
36
|
+
const operations: readonly NessoOperation[] = state.viewGraph.concepts.map(
|
|
37
|
+
({ id, label }) => ({
|
|
38
|
+
kind: 'concept.label',
|
|
39
|
+
id,
|
|
40
|
+
value: label.toUpperCase(),
|
|
41
|
+
}),
|
|
42
|
+
)
|
|
41
43
|
|
|
42
44
|
await document.applyOperations(operations)
|
|
43
45
|
},
|
|
@@ -109,7 +111,13 @@ import type { ActionContext, ActionContribution } from '@nesso-how/plugin'
|
|
|
109
111
|
|
|
110
112
|
function Browse({ document }: ActionContext) {
|
|
111
113
|
const state = useSyncExternalStore(document.subscribe, document.getState)
|
|
112
|
-
return
|
|
114
|
+
return (
|
|
115
|
+
<ul>
|
|
116
|
+
{state.viewGraph.concepts.map(({ id, label }) => (
|
|
117
|
+
<li key={id}>{label}</li>
|
|
118
|
+
))}
|
|
119
|
+
</ul>
|
|
120
|
+
)
|
|
113
121
|
}
|
|
114
122
|
|
|
115
123
|
export const create = (): readonly ActionContribution[] => [
|
|
@@ -127,7 +135,23 @@ Nesso supplies React, the `@nesso-how/ui` component stylesheet, and theme CSS va
|
|
|
127
135
|
|
|
128
136
|
#### Lifecycle
|
|
129
137
|
|
|
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.
|
|
138
|
+
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. Changing the active view revokes the current panel instance and mounts the same action in a new instance for the selected view, including All. Closing or replacing a panel discards its React state: save progress through `storage` during use, not during cleanup, which is best effort.
|
|
139
|
+
|
|
140
|
+
### Action badges
|
|
141
|
+
|
|
142
|
+
Add optional `badge(input)` to a `run` or `ui` action. It may return synchronously or asynchronously:
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
badge: ({ viewGraph }) => ({
|
|
146
|
+
value: viewGraph.concepts.length,
|
|
147
|
+
})
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- `input`: readonly `viewId` (`null` for All), target `viewGraph`, private document storage `records` (requires `storage`; otherwise empty), and `now` in Unix milliseconds.
|
|
151
|
+
- Return `{ value: number | null, refreshAt?: number }`. `value` is an integer from 0 to 999,999; zero and `null` hide the badge.
|
|
152
|
+
- For time-dependent counts, calculate from `now` and return `refreshAt` as an absolute Unix-millisecond timestamp. Omit it otherwise. Timed refreshes run no more often than every 15 seconds.
|
|
153
|
+
|
|
154
|
+
Runs in an isolated Worker with no action APIs and a 2-second calculation limit. Nesso calculates only visible badges and refreshes them after graph, saved-view, or plugin storage changes. Results are not persisted; failures hide the badge.
|
|
131
155
|
|
|
132
156
|
### Read the invoked view
|
|
133
157
|
|
|
@@ -139,7 +163,7 @@ The graph snapshot provides:
|
|
|
139
163
|
|
|
140
164
|
- `viewGraph`: `{ concepts, relations, relationTypes }` for the invoked view.
|
|
141
165
|
- `selected`: the invoked view's selection.
|
|
142
|
-
- `targetViewId`: the invoked view's ID, or `null` for All; navigation
|
|
166
|
+
- `targetViewId`: the invoked view's ID, or `null` for All; fixed for each invocation. Headless actions keep their target during navigation; panels restart with a new invocation when the active view changes.
|
|
143
167
|
- `activeVocab`: the current vocabulary, or `null`.
|
|
144
168
|
|
|
145
169
|
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.
|
|
@@ -148,24 +172,24 @@ Concept and relation-type IDs are absolute IRIs. Relations are `{ source, predic
|
|
|
148
172
|
|
|
149
173
|
Call helpers on `document` and declare their operation kinds in `nesso.writes`:
|
|
150
174
|
|
|
151
|
-
| Helper
|
|
152
|
-
|
|
|
153
|
-
| `setConceptLabel(id, value)`
|
|
154
|
-
| `
|
|
155
|
-
| `setConceptColor(id, value)`
|
|
156
|
-
| `setConceptBold(id, value)`
|
|
157
|
-
| `setConceptItalic(id, value)`
|
|
158
|
-
| `setConceptPosition(id, { x, y })`
|
|
159
|
-
| `setConceptPositions([{ id, position: { x, y } }])` | `concept.positions`
|
|
160
|
-
| `addConcept(position?)`
|
|
161
|
-
| `removeConcept(id)`
|
|
162
|
-
| `connect(source, target)`
|
|
163
|
-
| `reconnectRelation(id, source, target)`
|
|
164
|
-
| `setRelationType(id, typeId)`
|
|
165
|
-
| `createRelationType(id, label)`
|
|
166
|
-
| `removeRelation(id)`
|
|
167
|
-
| `setSelection([{ kind, id }])`
|
|
168
|
-
| `setViewMembership(viewId, conceptId, included)`
|
|
175
|
+
| Helper | Required `writes` entry |
|
|
176
|
+
| --------------------------------------------------- | ----------------------- |
|
|
177
|
+
| `setConceptLabel(id, value)` | `concept.label` |
|
|
178
|
+
| `setConceptNotes(id, value)` | `concept.notes` |
|
|
179
|
+
| `setConceptColor(id, value)` | `concept.color` |
|
|
180
|
+
| `setConceptBold(id, value)` | `concept.bold` |
|
|
181
|
+
| `setConceptItalic(id, value)` | `concept.italic` |
|
|
182
|
+
| `setConceptPosition(id, { x, y })` | `concept.position` |
|
|
183
|
+
| `setConceptPositions([{ id, position: { x, y } }])` | `concept.positions` |
|
|
184
|
+
| `addConcept(position?)` | `concept.add` |
|
|
185
|
+
| `removeConcept(id)` | `concept.remove` |
|
|
186
|
+
| `connect(source, target)` | `relation.connect` |
|
|
187
|
+
| `reconnectRelation(id, source, target)` | `relation.reconnect` |
|
|
188
|
+
| `setRelationType(id, typeId)` | `relation.type` |
|
|
189
|
+
| `createRelationType(id, label)` | `relation.type.create` |
|
|
190
|
+
| `removeRelation(id)` | `relation.remove` |
|
|
191
|
+
| `setSelection([{ kind, id }])` | `selection.set` |
|
|
192
|
+
| `setViewMembership(viewId, conceptId, included)` | `view.membership` |
|
|
169
193
|
|
|
170
194
|
`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.
|
|
171
195
|
|
|
@@ -177,11 +201,11 @@ The invoked view is **not a write sandbox**: permitted writes can affect the who
|
|
|
177
201
|
|
|
178
202
|
### Files, notifications, and failures
|
|
179
203
|
|
|
180
|
-
| API
|
|
181
|
-
|
|
|
182
|
-
| `files.open({ extensions: ['json'], mimeTypes: ['application/json'] })`
|
|
183
|
-
| `files.save({ name: 'graph.json', mediaType: 'application/json', text })`
|
|
184
|
-
| `notifications.notify({ tone: 'info', title: { en: 'Done' }, description: { en: 'Labels updated' } })` | `notifications`
|
|
204
|
+
| API | Required capability | Result |
|
|
205
|
+
| ------------------------------------------------------------------------------------------------------ | ------------------- | -------------------------------------------------------------------------------- |
|
|
206
|
+
| `files.open({ extensions: ['json'], mimeTypes: ['application/json'] })` | `files` | `{ name, mediaType, text }`, or `null` on cancellation. Extensions omit the dot. |
|
|
207
|
+
| `files.save({ name: 'graph.json', mediaType: 'application/json', text })` | `files` | `{ saved: boolean }`; cancellation returns `false`. |
|
|
208
|
+
| `notifications.notify({ tone: 'info', title: { en: 'Done' }, description: { en: 'Labels updated' } })` | `notifications` | A notification ID. Tone is `info` or `warning`; description is optional. |
|
|
185
209
|
|
|
186
210
|
Files use UTF-8 text and host-managed dialogs or browser downloads; `files` grants no unrestricted filesystem access. Plugins have no Node, host DOM, direct filesystem, clipboard, or network access.
|
|
187
211
|
|
|
@@ -216,24 +240,23 @@ Await all storage calls before the action returns. Success means the validated c
|
|
|
216
240
|
|
|
217
241
|
- A document has a persistent identity outside graph JSON-LD. Resetting it creates a new identity and empty plugin storage; a mismatched saved identity is reported and protected, never silently attached to another document.
|
|
218
242
|
- Removing a view or changing membership does not delete concept data.
|
|
219
|
-
- Deleting a concept retains its records
|
|
220
|
-
-
|
|
221
|
-
-
|
|
222
|
-
- Disabling, uninstalling, replacing, or crashing a plugin does not delete its stored data. Startup reference cleanup still applies even when the plugin is absent.
|
|
243
|
+
- Deleting a concept retains its records, including across restart and backup restoration. Document Undo/Redo can recover the concept during the current app session; private storage changes themselves do not enter graph history.
|
|
244
|
+
- Use concept-associated records to identify a concept's data, including its logs. Plugins may explicitly delete records no longer needed; IDs embedded in arbitrary payloads remain opaque to the host.
|
|
245
|
+
- Disabling, uninstalling, replacing, or crashing a plugin does not delete its stored data.
|
|
223
246
|
|
|
224
247
|
#### Limits
|
|
225
248
|
|
|
226
249
|
Storage accepts finite JSON primitives, dense arrays, and plain objects, including `null`; not `undefined`, dates, maps, functions, cyclic data, or custom prototypes. Returned snapshots and stored payloads are independent copies.
|
|
227
250
|
|
|
228
|
-
| Budget
|
|
229
|
-
|
|
|
230
|
-
| Record, encoded as UTF-8 JSON
|
|
231
|
-
| Namespace snapshot
|
|
232
|
-
| Total plugin storage per document | 64 MiB
|
|
233
|
-
| Records per plugin
|
|
234
|
-
| Plugin namespaces per document
|
|
235
|
-
| Record nesting
|
|
236
|
-
| Record key
|
|
251
|
+
| Budget | Limit |
|
|
252
|
+
| --------------------------------- | ---------------- |
|
|
253
|
+
| Record, encoded as UTF-8 JSON | 256 KiB |
|
|
254
|
+
| Namespace snapshot | 8 MiB |
|
|
255
|
+
| Total plugin storage per document | 64 MiB |
|
|
256
|
+
| Records per plugin | 10,000 |
|
|
257
|
+
| Plugin namespaces per document | 128 |
|
|
258
|
+
| Record nesting | 24 levels |
|
|
259
|
+
| Record key | 1–128 characters |
|
|
237
260
|
|
|
238
261
|
Concept IDs must be absolute IRIs and refer to an existing document concept when writing. Deletes may remove retained orphan records. Keys are logical identifiers, not paths. Normal action channel request, deadline, rate, and cancellation limits also apply.
|
|
239
262
|
|
|
@@ -245,7 +268,11 @@ Set `nesso.kind` to `"vocab"`, `entry` to a package-local JSON file such as `"di
|
|
|
245
268
|
{
|
|
246
269
|
"id": "my-vocab",
|
|
247
270
|
"relationTypes": [
|
|
248
|
-
{
|
|
271
|
+
{
|
|
272
|
+
"id": "urn:my-vocab:depends-on",
|
|
273
|
+
"label": "depends on",
|
|
274
|
+
"translations": { "en": "depends on", "it": "dipende da", "zh-CN": "依赖于" }
|
|
275
|
+
}
|
|
249
276
|
],
|
|
250
277
|
"defaultTypeId": "urn:my-vocab:depends-on"
|
|
251
278
|
}
|
|
@@ -253,6 +280,8 @@ Set `nesso.kind` to `"vocab"`, `entry` to a package-local JSON file such as `"di
|
|
|
253
280
|
|
|
254
281
|
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.
|
|
255
282
|
|
|
283
|
+
`label` is the canonical label saved in the graph. Optional `translations` provides display labels for `en`, `it`, and `zh-CN`, each nonempty and at most 30 characters. The app resolves the current locale, then English, then `label`, without changing document data. Translations apply only when the type's IRI and canonical label match an installed vocabulary; custom labels remain unchanged. Missing or disabled vocabularies fall back to the stored label.
|
|
284
|
+
|
|
256
285
|
## Themes
|
|
257
286
|
|
|
258
287
|
Set `nesso.kind` to `"theme"`, point `entry` to your JSON definition, and use empty `writes` and `capabilities`. A `ThemeDefinition` contains:
|
|
@@ -264,4 +293,6 @@ Set `nesso.kind` to `"theme"`, point `entry` to your JSON definition, and use em
|
|
|
264
293
|
|
|
265
294
|
Only light themes are supported. Use readable text contrast; arbitrary CSS and remote fonts are unsupported.
|
|
266
295
|
|
|
267
|
-
|
|
296
|
+
The SDK exposes shared graph and operation types from the internal [`@nesso-how/core`](../core/) package. Trusted renderers use its synchronous store contract; plugins use only the permission-limited asynchronous `ActionContext` above. The published SDK bundles these shared contracts and helpers, so plugin projects need no separate core dependency.
|
|
297
|
+
|
|
298
|
+
For the full API and validation rules, see [action types](src/runtime.ts), [graph operations](../core/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 GraphSnapshot, type LocalizedText, type NessoOperation,
|
|
1
|
+
import { B as ThemeDefinition, C as PluginStorage, F as PluginError, G as SavedView, K as Selection, L as LocalizedText, T as PluginStorageRecord, U as GraphSnapshot, W as NessoOperation, a as ActionDescriptor, c as PluginI18n, i as ActionContribution, l as PluginManifest, n as ActionBadgeResult, o as ActionIconName, q as VocabDefinition, r as ActionContext, s as ActionState, t as ActionBadgeInput, u as actionIconNames, w as PluginStorageKey } from "./runtime-BxtTAcko.js";
|
|
2
|
+
export { type ActionBadgeInput, type ActionBadgeResult, type ActionContext, type ActionContribution, type ActionDescriptor, type ActionIconName, type ActionState, type GraphSnapshot, type LocalizedText, type NessoOperation, PluginError, type PluginI18n, type PluginManifest, type PluginStorage, type PluginStorageKey, type PluginStorageRecord, type SavedView, type Selection, type ThemeDefinition, type VocabDefinition, actionIconNames };
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export {
|
|
1
|
+
export { C as PluginError, t as actionIconNames } from "./runtime-BM45o1qi.js";
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function checkMessageSize(value: unknown, limit: number, maximumDepth?: number): void;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { PluginError } from './errors.js';
|
|
2
|
+
export function checkMessageSize(value, limit, maximumDepth = 32) {
|
|
3
|
+
const visit = (value, depth) => {
|
|
4
|
+
if (depth > maximumDepth)
|
|
5
|
+
throw new PluginError('invalid-input', [
|
|
6
|
+
{ path: 'message', message: 'Nesting limit exceeded' },
|
|
7
|
+
]);
|
|
8
|
+
if (value === null)
|
|
9
|
+
return;
|
|
10
|
+
if (typeof value === 'object') {
|
|
11
|
+
if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype)
|
|
12
|
+
throw new PluginError('invalid-input', [
|
|
13
|
+
{ path: 'message', message: 'Expected plain data' },
|
|
14
|
+
]);
|
|
15
|
+
for (const item of Object.values(value))
|
|
16
|
+
visit(item, depth + 1);
|
|
17
|
+
}
|
|
18
|
+
else if (!['string', 'number', 'boolean', 'undefined'].includes(typeof value) ||
|
|
19
|
+
(typeof value === 'number' && !Number.isFinite(value))) {
|
|
20
|
+
throw new PluginError('invalid-input', [
|
|
21
|
+
{ path: 'message', message: 'Expected serializable data' },
|
|
22
|
+
]);
|
|
23
|
+
}
|
|
24
|
+
};
|
|
25
|
+
visit(value, 0);
|
|
26
|
+
if (new TextEncoder().encode(JSON.stringify(value)).byteLength > limit)
|
|
27
|
+
throw new PluginError('invalid-input', [{ path: 'message', message: 'Message limit exceeded' }]);
|
|
28
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import type { DeepReadonly, VocabDefinition } from '@nesso-how/core';
|
|
3
|
+
export declare const themeColors: readonly ['background', 'foreground', 'canvas', 'sidebar', 'primary', 'primary-hover', 'primary-foreground', 'muted', 'muted-foreground', 'hover', 'pressed', 'border', 'ring', 'selection-halo', 'node-border', 'edge', 'handle'];
|
|
4
|
+
declare const themeDefinition: z.ZodObject<{
|
|
5
|
+
id: z.ZodString;
|
|
6
|
+
colors: z.ZodObject<{
|
|
7
|
+
background: z.ZodString;
|
|
8
|
+
border: z.ZodString;
|
|
9
|
+
canvas: z.ZodString;
|
|
10
|
+
edge: z.ZodString;
|
|
11
|
+
foreground: z.ZodString;
|
|
12
|
+
handle: z.ZodString;
|
|
13
|
+
hover: z.ZodString;
|
|
14
|
+
muted: z.ZodString;
|
|
15
|
+
"muted-foreground": z.ZodString;
|
|
16
|
+
"node-border": z.ZodString;
|
|
17
|
+
pressed: z.ZodString;
|
|
18
|
+
primary: z.ZodString;
|
|
19
|
+
"primary-foreground": z.ZodString;
|
|
20
|
+
"primary-hover": z.ZodString;
|
|
21
|
+
ring: z.ZodString;
|
|
22
|
+
"selection-halo": z.ZodString;
|
|
23
|
+
sidebar: z.ZodString;
|
|
24
|
+
}, z.core.$strict>;
|
|
25
|
+
metrics: z.ZodObject<{
|
|
26
|
+
'radius-control': z.ZodNumber;
|
|
27
|
+
'radius-object': z.ZodNumber;
|
|
28
|
+
'duration-state': z.ZodNumber;
|
|
29
|
+
}, z.core.$strict>;
|
|
30
|
+
fonts: z.ZodObject<{
|
|
31
|
+
sans: z.ZodObject<{
|
|
32
|
+
faces: z.ZodArray<z.ZodObject<{
|
|
33
|
+
path: z.ZodString;
|
|
34
|
+
weight: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
|
|
35
|
+
style: z.ZodEnum<{
|
|
36
|
+
italic: "italic";
|
|
37
|
+
normal: "normal";
|
|
38
|
+
}>;
|
|
39
|
+
unicodeRange: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
|
|
40
|
+
}, z.core.$strict>>;
|
|
41
|
+
}, z.core.$strict>;
|
|
42
|
+
mono: z.ZodObject<{
|
|
43
|
+
faces: z.ZodArray<z.ZodObject<{
|
|
44
|
+
path: z.ZodString;
|
|
45
|
+
weight: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
|
|
46
|
+
style: z.ZodEnum<{
|
|
47
|
+
italic: "italic";
|
|
48
|
+
normal: "normal";
|
|
49
|
+
}>;
|
|
50
|
+
unicodeRange: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
|
|
51
|
+
}, z.core.$strict>>;
|
|
52
|
+
}, z.core.$strict>;
|
|
53
|
+
}, z.core.$strict>;
|
|
54
|
+
}, z.core.$strict>;
|
|
55
|
+
export declare const vocabRelationType: z.ZodObject<{
|
|
56
|
+
id: z.ZodString;
|
|
57
|
+
label: z.ZodString;
|
|
58
|
+
translations: z.ZodOptional<z.ZodObject<{
|
|
59
|
+
en: z.ZodOptional<z.ZodString>;
|
|
60
|
+
it: z.ZodOptional<z.ZodString>;
|
|
61
|
+
'zh-CN': z.ZodOptional<z.ZodString>;
|
|
62
|
+
}, z.core.$strict>>;
|
|
63
|
+
}, z.core.$strict>;
|
|
64
|
+
export type ThemeDefinition = DeepReadonly<z.infer<typeof themeDefinition>>;
|
|
65
|
+
export type Definition = ThemeDefinition | VocabDefinition;
|
|
66
|
+
export declare function parseDefinition(kind: 'theme', value: unknown): ThemeDefinition;
|
|
67
|
+
export declare function parseDefinition(kind: 'vocab', value: unknown): VocabDefinition;
|
|
68
|
+
export declare function parseDefinition(kind: 'theme' | 'vocab', value: unknown): Definition;
|
|
69
|
+
export {};
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { validateGraph } from '@nesso-how/schema';
|
|
3
|
+
import { parseOrThrow } from './errors.js';
|
|
4
|
+
export const themeColors = [
|
|
5
|
+
'background',
|
|
6
|
+
'foreground',
|
|
7
|
+
'canvas',
|
|
8
|
+
'sidebar',
|
|
9
|
+
'primary',
|
|
10
|
+
'primary-hover',
|
|
11
|
+
'primary-foreground',
|
|
12
|
+
'muted',
|
|
13
|
+
'muted-foreground',
|
|
14
|
+
'hover',
|
|
15
|
+
'pressed',
|
|
16
|
+
'border',
|
|
17
|
+
'ring',
|
|
18
|
+
'selection-halo',
|
|
19
|
+
'node-border',
|
|
20
|
+
'edge',
|
|
21
|
+
'handle',
|
|
22
|
+
];
|
|
23
|
+
const contributionId = z
|
|
24
|
+
.string()
|
|
25
|
+
.max(64)
|
|
26
|
+
.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
|
|
27
|
+
const color = z.string().regex(/^#[\da-fA-F]{6}([\da-fA-F]{2})?$/);
|
|
28
|
+
const fontFace = z.strictObject({
|
|
29
|
+
path: z
|
|
30
|
+
.string()
|
|
31
|
+
.max(240)
|
|
32
|
+
.regex(/^(?:[\w-]+\/)*[\w-]+\.woff2$/),
|
|
33
|
+
weight: z
|
|
34
|
+
.tuple([z.number().int().min(1).max(1000), z.number().int().min(1).max(1000)])
|
|
35
|
+
.refine(([min, max]) => min <= max),
|
|
36
|
+
style: z.enum(['normal', 'italic']),
|
|
37
|
+
unicodeRange: z
|
|
38
|
+
.array(z
|
|
39
|
+
.tuple([z.number().int().min(0).max(0x10ffff), z.number().int().min(0).max(0x10ffff)])
|
|
40
|
+
.refine(([min, max]) => min <= max))
|
|
41
|
+
.min(1)
|
|
42
|
+
.max(64)
|
|
43
|
+
.optional(),
|
|
44
|
+
});
|
|
45
|
+
const font = z.strictObject({ faces: z.array(fontFace).max(32) });
|
|
46
|
+
const luminance = (value) => {
|
|
47
|
+
const channels = [1, 3, 5].map((offset) => parseInt(value.slice(offset, offset + 2), 16) / 255);
|
|
48
|
+
const linear = channels.map((value) => value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4);
|
|
49
|
+
return linear[0] * 0.2126 + linear[1] * 0.7152 + linear[2] * 0.0722;
|
|
50
|
+
};
|
|
51
|
+
const opaque = (value) => value.length === 7 || value.slice(7).toLowerCase() === 'ff';
|
|
52
|
+
const contrast = (left, right) => (Math.max(luminance(left), luminance(right)) + 0.05) /
|
|
53
|
+
(Math.min(luminance(left), luminance(right)) + 0.05);
|
|
54
|
+
const themeDefinition = z
|
|
55
|
+
.strictObject({
|
|
56
|
+
id: contributionId,
|
|
57
|
+
colors: z.strictObject(Object.fromEntries(themeColors.map((key) => [key, color]))),
|
|
58
|
+
metrics: z.strictObject({
|
|
59
|
+
'radius-control': z.number().min(0).max(16),
|
|
60
|
+
'radius-object': z.number().min(0).max(16),
|
|
61
|
+
'duration-state': z.number().int().min(0).max(300),
|
|
62
|
+
}),
|
|
63
|
+
fonts: z.strictObject({ sans: font, mono: font }),
|
|
64
|
+
})
|
|
65
|
+
.superRefine(({ colors, fonts }, context) => {
|
|
66
|
+
for (const key of ['background', 'canvas', 'sidebar']) {
|
|
67
|
+
if (!opaque(colors[key]) || luminance(colors[key]) < 0.8)
|
|
68
|
+
context.addIssue({
|
|
69
|
+
code: 'custom',
|
|
70
|
+
path: ['colors', key],
|
|
71
|
+
message: 'Expected an opaque light surface',
|
|
72
|
+
});
|
|
73
|
+
if (!opaque(colors.foreground) || contrast(colors.foreground, colors[key]) < 4.5)
|
|
74
|
+
context.addIssue({
|
|
75
|
+
code: 'custom',
|
|
76
|
+
path: ['colors', 'foreground'],
|
|
77
|
+
message: 'Insufficient foreground contrast',
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
if (!opaque(colors.primary) ||
|
|
81
|
+
!opaque(colors['primary-foreground']) ||
|
|
82
|
+
contrast(colors.primary, colors['primary-foreground']) < 4.5)
|
|
83
|
+
context.addIssue({
|
|
84
|
+
code: 'custom',
|
|
85
|
+
path: ['colors', 'primary-foreground'],
|
|
86
|
+
message: 'Insufficient primary contrast',
|
|
87
|
+
});
|
|
88
|
+
if (fonts.sans.faces.length + fonts.mono.faces.length > 32)
|
|
89
|
+
context.addIssue({ code: 'custom', path: ['fonts'], message: 'Font face limit exceeded' });
|
|
90
|
+
});
|
|
91
|
+
export const vocabRelationType = z.strictObject({
|
|
92
|
+
id: z.string().min(1).max(2048),
|
|
93
|
+
label: z.string().max(30),
|
|
94
|
+
translations: z
|
|
95
|
+
.strictObject({
|
|
96
|
+
en: z.string().trim().min(1).max(30).optional(),
|
|
97
|
+
it: z.string().trim().min(1).max(30).optional(),
|
|
98
|
+
'zh-CN': z.string().trim().min(1).max(30).optional(),
|
|
99
|
+
})
|
|
100
|
+
.optional(),
|
|
101
|
+
});
|
|
102
|
+
const vocabDefinition = z
|
|
103
|
+
.strictObject({
|
|
104
|
+
id: contributionId,
|
|
105
|
+
relationTypes: z.array(vocabRelationType).min(1),
|
|
106
|
+
defaultTypeId: z.string().min(1).max(2048),
|
|
107
|
+
})
|
|
108
|
+
.superRefine(({ relationTypes, defaultTypeId }, context) => {
|
|
109
|
+
for (const issue of validateGraph({
|
|
110
|
+
concepts: [],
|
|
111
|
+
relations: [],
|
|
112
|
+
relationTypes: relationTypes.map(({ id, label }) => ({ id, label })),
|
|
113
|
+
}))
|
|
114
|
+
context.addIssue({ code: 'custom', path: ['relationTypes'], message: issue.message });
|
|
115
|
+
if (!relationTypes.some(({ id }) => id === defaultTypeId))
|
|
116
|
+
context.addIssue({
|
|
117
|
+
code: 'custom',
|
|
118
|
+
path: ['defaultTypeId'],
|
|
119
|
+
message: 'Default type must be offered by the vocabulary',
|
|
120
|
+
});
|
|
121
|
+
});
|
|
122
|
+
export function parseDefinition(kind, value) {
|
|
123
|
+
return parseOrThrow(kind === 'theme' ? themeDefinition : vocabDefinition, value);
|
|
124
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { NessoError, type ErrorIssue } from '@nesso-how/errors';
|
|
2
|
+
import type { ZodType } from 'zod';
|
|
3
|
+
import type { LocalizedText } from './i18n.ts';
|
|
4
|
+
export declare class PluginError extends NessoError {
|
|
5
|
+
name: string;
|
|
6
|
+
readonly code: string;
|
|
7
|
+
readonly displayMessage?: LocalizedText;
|
|
8
|
+
constructor(code: string, issues: ErrorIssue[], displayMessage?: LocalizedText);
|
|
9
|
+
}
|
|
10
|
+
export declare function parseOrThrow(schema: ZodType, value: unknown, prefix?: string): any;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { NessoError } from '@nesso-how/errors';
|
|
2
|
+
const boundText = (text, limit) => {
|
|
3
|
+
let result = '';
|
|
4
|
+
let bytes = 0;
|
|
5
|
+
const encoder = new TextEncoder();
|
|
6
|
+
for (const character of text) {
|
|
7
|
+
bytes += encoder.encode(character).byteLength;
|
|
8
|
+
if (bytes > limit)
|
|
9
|
+
break;
|
|
10
|
+
result += character;
|
|
11
|
+
}
|
|
12
|
+
return result;
|
|
13
|
+
};
|
|
14
|
+
export class PluginError extends NessoError {
|
|
15
|
+
name = 'PluginError';
|
|
16
|
+
code;
|
|
17
|
+
displayMessage;
|
|
18
|
+
constructor(code, issues, displayMessage) {
|
|
19
|
+
const bounded = issues.slice(0, 32).map(({ path, message }) => ({
|
|
20
|
+
path: boundText(path, 256),
|
|
21
|
+
message: boundText(message, 2048),
|
|
22
|
+
}));
|
|
23
|
+
if (!bounded.length)
|
|
24
|
+
bounded.push({ path: 'plugin', message: 'Plugin request failed' });
|
|
25
|
+
super(bounded);
|
|
26
|
+
this.code = code;
|
|
27
|
+
if (displayMessage)
|
|
28
|
+
this.displayMessage = {
|
|
29
|
+
en: boundText(displayMessage.en, 2048),
|
|
30
|
+
...(displayMessage.it !== undefined ? { it: boundText(displayMessage.it, 2048) } : {}),
|
|
31
|
+
...(displayMessage['zh-CN'] !== undefined
|
|
32
|
+
? { 'zh-CN': boundText(displayMessage['zh-CN'], 2048) }
|
|
33
|
+
: {}),
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
export function parseOrThrow(schema, value, prefix = '') {
|
|
38
|
+
const parsed = schema.safeParse(value);
|
|
39
|
+
if (!parsed.success)
|
|
40
|
+
throw new PluginError('invalid-input', parsed.error.issues.map((issue) => ({
|
|
41
|
+
path: `${prefix}${issue.path.join('.')}`,
|
|
42
|
+
message: issue.message,
|
|
43
|
+
})));
|
|
44
|
+
return parsed.data;
|
|
45
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export declare const fileTextLimit: number;
|
|
3
|
+
export declare const fileOpenOptions: z.ZodObject<{
|
|
4
|
+
extensions: z.ZodArray<z.ZodString>;
|
|
5
|
+
mimeTypes: z.ZodArray<z.ZodString>;
|
|
6
|
+
}, z.core.$strict>;
|
|
7
|
+
export declare const fileSaveOptions: z.ZodObject<{
|
|
8
|
+
name: z.ZodString;
|
|
9
|
+
mediaType: z.ZodString;
|
|
10
|
+
text: z.ZodString;
|
|
11
|
+
}, z.core.$strict>;
|
|
12
|
+
export declare const fileOpenResult: z.ZodNullable<z.ZodObject<{
|
|
13
|
+
name: z.ZodString;
|
|
14
|
+
mediaType: z.ZodString;
|
|
15
|
+
text: z.ZodString;
|
|
16
|
+
}, z.core.$strict>>;
|
|
17
|
+
export type FileOpenOptions = z.infer<typeof fileOpenOptions>;
|
|
18
|
+
export type FileSaveOptions = z.infer<typeof fileSaveOptions>;
|
|
19
|
+
export type FileOpenResult = z.infer<typeof fileOpenResult>;
|
|
20
|
+
export declare function parseFileOptions<K extends 'open' | 'save'>(kind: K, value: unknown): K extends 'open' ? FileOpenOptions : FileSaveOptions;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { parseOrThrow } from './errors.js';
|
|
3
|
+
export const fileTextLimit = 16 * 1024 * 1024;
|
|
4
|
+
const mediaType = z
|
|
5
|
+
.string()
|
|
6
|
+
.max(128)
|
|
7
|
+
.regex(/^[\w!#$&^.+-]+\/[\w!#$&^.+-]+$/);
|
|
8
|
+
export const fileOpenOptions = z.strictObject({
|
|
9
|
+
extensions: z
|
|
10
|
+
.array(z.string().regex(/^[a-zA-Z0-9]{1,16}$/))
|
|
11
|
+
.min(1)
|
|
12
|
+
.max(16),
|
|
13
|
+
mimeTypes: z.array(mediaType).max(16),
|
|
14
|
+
});
|
|
15
|
+
export const fileSaveOptions = z.strictObject({
|
|
16
|
+
name: z
|
|
17
|
+
.string()
|
|
18
|
+
.trim()
|
|
19
|
+
.min(1)
|
|
20
|
+
.max(240)
|
|
21
|
+
.regex(/^[^/\\]+$/)
|
|
22
|
+
.refine((value) => value !== '.' &&
|
|
23
|
+
value !== '..' &&
|
|
24
|
+
[...value].every((character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127)),
|
|
25
|
+
mediaType,
|
|
26
|
+
text: z
|
|
27
|
+
.string()
|
|
28
|
+
.max(fileTextLimit)
|
|
29
|
+
.refine((value) => new TextEncoder().encode(value).byteLength <= fileTextLimit, 'File text byte limit exceeded'),
|
|
30
|
+
});
|
|
31
|
+
export const fileOpenResult = z
|
|
32
|
+
.strictObject({ name: z.string().min(1).max(240), mediaType, text: fileSaveOptions.shape.text })
|
|
33
|
+
.nullable();
|
|
34
|
+
export function parseFileOptions(kind, value) {
|
|
35
|
+
return parseOrThrow(kind === 'open' ? fileOpenOptions : fileSaveOptions, value);
|
|
36
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import type { Locale } from '@nesso-how/i18n';
|
|
3
|
+
export type LocalizedText = Readonly<{
|
|
4
|
+
en: string;
|
|
5
|
+
} & Partial<Record<Locale, string>>>;
|
|
6
|
+
export declare const text: (limit: number) => z.ZodString;
|
|
7
|
+
export declare const localizedText: (limit: number) => z.ZodObject<{
|
|
8
|
+
en: z.ZodString;
|
|
9
|
+
it: z.ZodOptional<z.ZodString>;
|
|
10
|
+
'zh-CN': z.ZodOptional<z.ZodString>;
|
|
11
|
+
}, z.core.$strict>;
|
|
12
|
+
export declare const resolvePluginText: (value: LocalizedText, locale: Locale) => string;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export const text = (limit) => z
|
|
3
|
+
.string()
|
|
4
|
+
.max(limit)
|
|
5
|
+
.refine((value) => new TextEncoder().encode(value).byteLength <= limit, 'Text byte limit exceeded');
|
|
6
|
+
export const localizedText = (limit) => z.strictObject({
|
|
7
|
+
en: text(limit).min(1),
|
|
8
|
+
it: text(limit).min(1).optional(),
|
|
9
|
+
'zh-CN': text(limit).min(1).optional(),
|
|
10
|
+
});
|
|
11
|
+
export const resolvePluginText = (value, locale) => value[locale] ?? value.en;
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export type { GraphSnapshot, NessoOperation, SavedView, Selection, VocabDefinition, } from '@nesso-how/core';
|
|
2
|
+
export type { ThemeDefinition } from './definitions.ts';
|
|
3
|
+
export { PluginError } from './errors.ts';
|
|
4
|
+
export type { ActionContext, ActionBadgeInput, ActionBadgeResult, ActionContribution, ActionDescriptor, ActionIconName, ActionState, LocalizedText, PluginI18n, PluginManifest, } from './runtime.ts';
|
|
5
|
+
export { actionIconNames } from './runtime.ts';
|
|
6
|
+
export type { PluginStorage, PluginStorageKey, PluginStorageRecord } from './storage.ts';
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { type PluginI18n, type PluginManifest } from './runtime.ts';
|
|
2
|
+
export declare const packageLimits: {
|
|
3
|
+
readonly entry: number;
|
|
4
|
+
readonly font: number;
|
|
5
|
+
readonly fonts: 32;
|
|
6
|
+
readonly record: number;
|
|
7
|
+
readonly installed: 32;
|
|
8
|
+
readonly total: number;
|
|
9
|
+
};
|
|
10
|
+
export type PluginPackageInput = {
|
|
11
|
+
readonly manifest: unknown;
|
|
12
|
+
readonly files: readonly {
|
|
13
|
+
readonly path: string;
|
|
14
|
+
readonly bytes: Uint8Array;
|
|
15
|
+
}[];
|
|
16
|
+
};
|
|
17
|
+
export type PreparedPlugin = {
|
|
18
|
+
readonly name: string;
|
|
19
|
+
readonly version: string;
|
|
20
|
+
readonly author?: string;
|
|
21
|
+
readonly repository?: string;
|
|
22
|
+
readonly nesso: PluginManifest;
|
|
23
|
+
readonly i18n: PluginI18n;
|
|
24
|
+
readonly code: string;
|
|
25
|
+
readonly fonts: readonly {
|
|
26
|
+
readonly path: string;
|
|
27
|
+
readonly data: string;
|
|
28
|
+
}[];
|
|
29
|
+
readonly contentId: string;
|
|
30
|
+
};
|
|
31
|
+
export declare function parsePackageIdentity(value: unknown): any;
|
|
32
|
+
export declare function preparePluginPackage(input: PluginPackageInput): Promise<PreparedPlugin>;
|
|
33
|
+
export declare function packageFonts(value: PreparedPlugin): ReadonlyMap<string, Uint8Array>;
|
|
34
|
+
export declare function verifyPluginPackage(value: PreparedPlugin): Promise<PreparedPlugin>;
|