@appsoftwareltd/etherpk-extension-api 0.19.4 → 0.21.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 +6 -2
- package/dist/assets.d.ts +23 -0
- package/dist/editor.d.ts +49 -6
- package/dist/index.d.ts +2 -2
- package/dist/menus.d.ts +10 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -89,7 +89,11 @@ These are the Stable parts of the context.
|
|
|
89
89
|
|
|
90
90
|
`context.commands.register(id, handler)` adds a Command, whose id starts with the extension's id
|
|
91
91
|
(`hello.greet`). `context.commandMenu.register(item)` adds a row to the `/` menu that runs a Command.
|
|
92
|
-
A row can have a `detail` line, an `icon`, `keywords` that find it, a `group` and an `order`.
|
|
92
|
+
A row can have a `detail` line, an `icon`, `keywords` that find it, a `group` and an `order`. The
|
|
93
|
+
menu lists its rows under three headings, in this order: `Insert`, `Go to` and `Settings`. A row's
|
|
94
|
+
`group` names the one it belongs under, and its `order` places it among the other rows there, lower
|
|
95
|
+
first. A row with no `group`, or with any other text in it, is listed under `Insert` when it sets
|
|
96
|
+
`actsOnText` and under `Go to` otherwise. Its
|
|
93
97
|
`when(menu)` says whether it is offered at the caret, from what `menu` reports: `bodyWritable`,
|
|
94
98
|
`inTable` and `protectedDocument`. A row that only acts on the text at the caret, inserting or
|
|
95
99
|
formatting it, sets `actsOnText: true`; only such rows are offered in an editor that shows part of a
|
|
@@ -414,7 +418,7 @@ thumbnail.addEventListener('click', () => void context.assets.viewImages({ refs:
|
|
|
414
418
|
### Icons
|
|
415
419
|
|
|
416
420
|
`context.icons.svg(name)` draws one of the extension's own icons or one of the Client's, as markup the
|
|
417
|
-
Client trusts. The Client's icons, which every `icon` field may name too, are `alias`, `archive`, `backlinks`, `bold`, `bookmark`, `bullet`, `calendar`, `check`, `clock`, `close`, `code`, `copy`, `download`, `fit`, `flag`, `fold`, `frontmatter`, `globe`, `graph`, `grip`, `headless-client`, `highlight`, `image`, `import`, `indent`, `italic`, `list`, `lock`, `lock-open`, `more`, `move`, `move-down`, `move-up`, `new-page`, `open-external`, `outdent`, `page`, `pdf`, `pdf-eraser`, `pdf-hand`, `pdf-highlighter`, `pdf-note`, `pdf-page-next`, `pdf-page-previous`, `pdf-full-screen-exit`, `pdf-save`, `pdf-select`, `pdf-pen`, `pdf-print`, `pdf-signature`, `pageless`, `pane-below`, `pane-right`, `pin`, `redo`, `rename`, `reset`, `search`, `slash`, `spell-check`, `table`, `table-add-column`, `table-add-row`, `table-format`, `table-remove-column`, `table-remove-row`, `task`, `task-reference`, `template`, `text-lines`, `today`, `todays-journal`, `tomorrow`, `trash`, `undo`, `view-larger`, `wikilink-close`, `wikilink-open`, `yesterday`, `zoom-in`, `zoom-out`. An
|
|
421
|
+
Client trusts. The Client's icons, which every `icon` field may name too, are `alias`, `archive`, `backlinks`, `bold`, `book`, `bookmark`, `bullet`, `calendar`, `check`, `clock`, `close`, `code`, `copy`, `download`, `ebook-back`, `ebook-read-aloud`, `ebook-text-size`, `fit`, `flag`, `fold`, `frontmatter`, `globe`, `graph`, `grip`, `headless-client`, `highlight`, `hourglass`, `image`, `import`, `indent`, `italic`, `list`, `lock`, `lock-open`, `more`, `move`, `move-down`, `move-up`, `new-page`, `open-external`, `outdent`, `page`, `pdf`, `pdf-eraser`, `pdf-hand`, `pdf-highlighter`, `pdf-note`, `pdf-page-next`, `pdf-page-previous`, `pdf-full-screen-exit`, `pdf-save`, `pdf-select`, `pdf-pen`, `pdf-print`, `pdf-signature`, `pageless`, `pane-below`, `pane-right`, `pin`, `redo`, `rename`, `reset`, `search`, `slash`, `spell-check`, `table`, `table-add-column`, `table-add-row`, `table-format`, `table-remove-column`, `table-remove-row`, `tag`, `task`, `task-reference`, `template`, `text-lines`, `today`, `todays-journal`, `tomorrow`, `trash`, `undo`, `view-larger`, `wikilink-close`, `wikilink-open`, `yesterday`, `zoom-in`, `zoom-out`. An
|
|
418
422
|
icon may be added in a later release, never taken away. An unknown name draws a small dot.
|
|
419
423
|
|
|
420
424
|
### Settings sections
|
package/dist/assets.d.ts
CHANGED
|
@@ -33,6 +33,22 @@ export interface ViewImagesOptions {
|
|
|
33
33
|
/** The reference the Lightbox opens on. The first image when left out, or when it is not among them. */
|
|
34
34
|
start?: string;
|
|
35
35
|
}
|
|
36
|
+
/**
|
|
37
|
+
* What became of an image given to {@link ExtensionAssets.storeImage}.
|
|
38
|
+
*
|
|
39
|
+
* @beta
|
|
40
|
+
*/
|
|
41
|
+
export type StoredImage = {
|
|
42
|
+
stored: true;
|
|
43
|
+
/** The reference a document writes for the image, such as `../assets/plan.3f9a1c2e.webp`. */
|
|
44
|
+
ref: string;
|
|
45
|
+
/** The markdown that shows the image in a document, as {@link ExtensionAssets.saveImage} answers. */
|
|
46
|
+
markdown: string;
|
|
47
|
+
} | {
|
|
48
|
+
stored: false;
|
|
49
|
+
/** Why not, in words for the person, such as that the account's storage is full. */
|
|
50
|
+
reason: string;
|
|
51
|
+
};
|
|
36
52
|
/**
|
|
37
53
|
* The open graph's assets, as far as an extension may add to them.
|
|
38
54
|
*
|
|
@@ -54,6 +70,13 @@ export interface ExtensionAssets {
|
|
|
54
70
|
* where the graph keeps no assets here, or the image was refused.
|
|
55
71
|
*/
|
|
56
72
|
saveImage(image: Blob, name: string): Promise<string | null>;
|
|
73
|
+
/**
|
|
74
|
+
* Keep an image as {@link ExtensionAssets.saveImage} does, and answer its reference as well as its
|
|
75
|
+
* markdown, or why it was not kept. For an extension that holds the reference in data of its own.
|
|
76
|
+
*
|
|
77
|
+
* @beta
|
|
78
|
+
*/
|
|
79
|
+
storeImage(image: Blob, name: string): Promise<StoredImage>;
|
|
57
80
|
/**
|
|
58
81
|
* What the asset reference `ref` names, as a document writes it (`../assets/plan.3f9a1c2e.png`),
|
|
59
82
|
* or null when `ref` names no asset.
|
package/dist/editor.d.ts
CHANGED
|
@@ -233,6 +233,39 @@ export interface QuoteFenceRequest {
|
|
|
233
233
|
/** Whether the dark theme shows: a picture is drawn for it. */
|
|
234
234
|
readonly dark: boolean;
|
|
235
235
|
}
|
|
236
|
+
/**
|
|
237
|
+
* A fence to draw as an image a person keeps.
|
|
238
|
+
*
|
|
239
|
+
* @beta
|
|
240
|
+
*/
|
|
241
|
+
export interface FenceImageRequest {
|
|
242
|
+
/** The fence's info word. */
|
|
243
|
+
readonly info: string;
|
|
244
|
+
/** The fence's body lines. */
|
|
245
|
+
readonly body: readonly string[];
|
|
246
|
+
/** The document the fence is in, by its concept, or null outside a workspace. */
|
|
247
|
+
readonly document: string | null;
|
|
248
|
+
/** How many fences with this info word come before this one in the document. */
|
|
249
|
+
readonly ordinal: number;
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* A fence drawn as an image, or why it could not be.
|
|
253
|
+
*
|
|
254
|
+
* @beta
|
|
255
|
+
*/
|
|
256
|
+
export type FenceImage = {
|
|
257
|
+
readonly drawn: true;
|
|
258
|
+
/** A PNG's bytes: the one kind of image every browser's clipboard takes. */
|
|
259
|
+
readonly bytes: Uint8Array;
|
|
260
|
+
/** The file's name, without its extension. */
|
|
261
|
+
readonly name: string;
|
|
262
|
+
} | {
|
|
263
|
+
readonly drawn: false;
|
|
264
|
+
/** Why, as a sentence the person reads after what could not be done. */
|
|
265
|
+
readonly reason: string;
|
|
266
|
+
/** Whether pressing again may work, so the notice offers Try again. */
|
|
267
|
+
readonly tryAgain: boolean;
|
|
268
|
+
};
|
|
236
269
|
/**
|
|
237
270
|
* Options for a fence registration.
|
|
238
271
|
*
|
|
@@ -288,16 +321,26 @@ export interface FenceOptions {
|
|
|
288
321
|
/**
|
|
289
322
|
* `'editor'` asks the Client to draw the frame a drawing has in the document, so every fence
|
|
290
323
|
* edited this way looks and behaves the same. While the fence is not being edited, a "…" menu
|
|
291
|
-
* over the widget offers Edit as text and Delete
|
|
292
|
-
*
|
|
293
|
-
*
|
|
294
|
-
*
|
|
295
|
-
*
|
|
296
|
-
*
|
|
324
|
+
* over the widget offers Edit as text and Delete, after Copy as image and Save as image where the
|
|
325
|
+
* fence has `asImage`. While it is (`setEditing`), a toolbar above it offers Done, Full window,
|
|
326
|
+
* Open in tab, Edit as text and Delete. Full window and Open in tab need `identify`. Delete
|
|
327
|
+
* removes the fence as one change and says how to undo it, naming the fence by `title`. Only one
|
|
328
|
+
* framed fence is edited at a time, in all the documents open, and a press outside it stops
|
|
329
|
+
* editing it. In a tab or a window the Client draws no frame. Where the document cannot be
|
|
330
|
+
* written, the menu holds only Copy as image and Save as image, and there is no toolbar.
|
|
297
331
|
*
|
|
298
332
|
* @beta
|
|
299
333
|
*/
|
|
300
334
|
frame?: 'editor';
|
|
335
|
+
/**
|
|
336
|
+
* For a fence registered with `frame: 'editor'`: the fence as an image, for the frame's Copy as
|
|
337
|
+
* image and Save as image, which write nothing to the document. Called when one of them is
|
|
338
|
+
* pressed. The Client says it is busy, copies or downloads the image and says what went wrong.
|
|
339
|
+
* A rejection reads as a drawing that failed, with Try again.
|
|
340
|
+
*
|
|
341
|
+
* @beta
|
|
342
|
+
*/
|
|
343
|
+
asImage?(fence: FenceImageRequest): Promise<FenceImage>;
|
|
301
344
|
}
|
|
302
345
|
/**
|
|
303
346
|
* A panel an extension draws in a document, beneath one of its lines, which is not part of the
|
package/dist/index.d.ts
CHANGED
|
@@ -16,11 +16,11 @@
|
|
|
16
16
|
* @packageDocumentation
|
|
17
17
|
*/
|
|
18
18
|
export type { CommandHandler, ExtensionCommandBar, ExtensionCommandMenu, ExtensionCommands, ExtensionConcepts, ExtensionContext, ExtensionContextMenu, ExtensionContributions, ExtensionGraphSidebar, ExtensionIcons, ExtensionKeybindings, ActiveFile, ExtensionLayout, ExtensionModule, ExtensionPersonStorage, ExtensionSettings, ExtensionStorage, ExtensionTheme, ExtensionViews, IconMarkup, Keybinding, NoticeAction, NoticeOptions, } from './context';
|
|
19
|
-
export type { AssetDescription, ExtensionAssets, ViewImagesOptions } from './assets';
|
|
19
|
+
export type { AssetDescription, ExtensionAssets, StoredImage, ViewImagesOptions } from './assets';
|
|
20
20
|
export type { AuthorizeOptions, ExtensionAuth } from './auth';
|
|
21
21
|
export type { ChooseChoice, ChooseOptions, ExtensionDialogs, PickDateOptions, PromptOptions } from './dialogs';
|
|
22
22
|
export type { DocumentBacklink, DocumentSearchResult, DocumentSummary, DocumentTask, DocumentText, ExtensionDocuments } from './documents';
|
|
23
|
-
export type { ExtensionEditor, FenceContext, FenceEdit, FenceInfo, FenceOptions, FencePresentation, FenceWidget, InlinePanel, InlinePanelOptions, MountedFence, PublishedFence, PublishFenceRequest, QuoteFenceRequest, } from './editor';
|
|
23
|
+
export type { ExtensionEditor, FenceContext, FenceEdit, FenceImage, FenceImageRequest, FenceInfo, FenceOptions, FencePresentation, FenceWidget, InlinePanel, InlinePanelOptions, MountedFence, PublishedFence, PublishFenceRequest, QuoteFenceRequest, } from './editor';
|
|
24
24
|
export type { ExtensionEmbeds, FrameOptions } from './embeds';
|
|
25
25
|
export type { ExtensionEventName, ExtensionEventPayloads, ExtensionEvents } from './events';
|
|
26
26
|
export type { ConceptCandidate, ConceptKind, ExtensionIndex, IndexUpdate, LinkGraph, LinkGraphConcept, LinkGraphLink } from './graph-index';
|
package/dist/menus.d.ts
CHANGED
|
@@ -145,9 +145,17 @@ export interface CommandMenuItem {
|
|
|
145
145
|
detail?: string | ((context: CommandMenuContext) => string | undefined);
|
|
146
146
|
/** An icon drawn before the title: the extension's own or one of the Client's. */
|
|
147
147
|
icon?: string;
|
|
148
|
-
/**
|
|
148
|
+
/**
|
|
149
|
+
* The heading the row is listed under: `'Insert'` for a row that puts something in the document,
|
|
150
|
+
* `'Go to'` for one that opens a View or a panel or finds something, or `'Settings'` for one that
|
|
151
|
+
* changes how EtherPK behaves. The menu lists the three in that order. Absent, or any other
|
|
152
|
+
* text, the row is listed under Insert when it sets `actsOnText` and under Go to otherwise.
|
|
153
|
+
*/
|
|
149
154
|
group?: string;
|
|
150
|
-
/**
|
|
155
|
+
/**
|
|
156
|
+
* Lower sorts earlier within the group, among the Client's rows and other extensions'. Absent,
|
|
157
|
+
* the row comes after every row of its group that has one.
|
|
158
|
+
*/
|
|
151
159
|
order?: number;
|
|
152
160
|
/** More words the menu's filter matches. */
|
|
153
161
|
keywords?: string[];
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@appsoftwareltd/etherpk-extension-api",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.21.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"description": "The API an EtherPK extension is written against: the context it is started with, its manifest, and the contract its Views follow.",
|
|
6
6
|
"type": "module",
|