@appsoftwareltd/etherpk-extension-api 0.16.0 → 0.18.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
@@ -91,7 +91,9 @@ These are the Stable parts of the context.
91
91
  (`hello.greet`). `context.commandMenu.register(item)` adds a row to the `/` menu that runs a Command.
92
92
  A row can have a `detail` line, an `icon`, `keywords` that find it, a `group` and an `order`. Its
93
93
  `when(menu)` says whether it is offered at the caret, from what `menu` reports: `bodyWritable`,
94
- `inTable` and `protectedDocument`.
94
+ `inTable` and `protectedDocument`. A row that only acts on the text at the caret, inserting or
95
+ formatting it, sets `actsOnText: true`; only such rows are offered in an editor that shows part of a
96
+ document, such as a Kanban task's description in its dialog.
95
97
 
96
98
  `context.commands.execute(id, arg)` runs a Command, and `context.commands.has(id)` says whether there
97
99
  is one. An extension may run three kinds of Command, by `execute` or as the Command of a row or a
@@ -107,7 +109,15 @@ added as extensions need them.
107
109
 
108
110
  ### Notices
109
111
 
110
- `context.notify(text)` shows a short notice, as the Client's own notices do.
112
+ `context.notify(text)` shows a short notice, as the Client's own notices do. A notice can carry one
113
+ button, for what a person may want to do about what it says:
114
+
115
+ ```ts
116
+ context.notify('Deleted "Build the shed".', { action: { label: 'Undo', run: () => putItBack() } })
117
+ ```
118
+
119
+ The button is greyed while a promise `run` returns is pending. The notice is replaced by the next one,
120
+ so say what the action did with a notice of its own, which also takes the button away.
111
121
 
112
122
  ### Settings
113
123
 
@@ -309,6 +319,25 @@ be added, and when the Client stops raising a menu on one, the rows for it are n
309
319
  `when` answers false for any kind it does not check. A row that deletes or removes something for good
310
320
  sets `danger: true`, and is drawn in the danger colour.
311
321
 
322
+ A menu is also raised on a task: a row of the Tasks View, and a task's line in an editor (a
323
+ right-click on its checkbox or its words). `context.contextMenu.taskOf(target)` answers the task a
324
+ target stands on, as `{ document, line, label }` (`line` counted in the document's body from 0, as a
325
+ task reference counts it), or null for any other target, a task in a Protected Document included. A
326
+ row offered on every task asks it in its `when`, and its Command asks it of the target it is given:
327
+
328
+ ```ts
329
+ context.contextMenu.register({
330
+ id: 'hello.taskWords',
331
+ label: 'Show the words',
332
+ command: 'hello.taskWords',
333
+ when: (target) => context.contextMenu.taskOf(target) !== null,
334
+ })
335
+ context.commands.register('hello.taskWords', (target) => {
336
+ const task = context.contextMenu.taskOf(target as MenuTarget)
337
+ if (task) context.notify(task.label)
338
+ })
339
+ ```
340
+
312
341
  `context.commandBar.register({ id, title, icon, command, pinned })` adds a button to the row of
313
342
  buttons across the bottom of a phone's screen: after the editing buttons that scroll, or with
314
343
  `pinned`, at the bar's right end, where it never scrolls away.
@@ -357,10 +386,32 @@ that shows it, such as `![photo](assets/photo.3f9a1c2e.webp)`. The file's name e
357
386
  bytes, so two images never take the same name, and the same image kept twice is one file. An asset
358
387
  is part of the graph: it syncs, and every member of a shared graph can see it.
359
388
 
389
+ `context.assets.describe(ref)` names the asset a document's reference points at, such as
390
+ `../assets/plan.3f9a1c2e.png`: `name` is the file's name as a person reads it (`plan.png`),
391
+ `fileName` the whole name, and `image` says whether a document shows it as an image. It answers null
392
+ for a reference that names no asset. `context.assets.imageUrl(ref)` answers an address an `<img>`
393
+ shows that image at, read from the graph as the editor reads the images it draws, and decrypted in a
394
+ synced graph. The address lasts while the graph is open. It answers null for a file that is not an
395
+ image, and for an image that cannot be read just now.
396
+
397
+ `context.assets.viewImages({ refs, start })` shows the images that `refs` name in the Client's
398
+ Lightbox, the dialog a picture's **View larger** opens in a document. Each image is shown as large
399
+ as the window allows, under the name `describe` gives it, over whatever is open, a dialog of the
400
+ extension's own included. With more than one image, Previous and Next (and the arrow keys) step
401
+ through them in the order of `refs` and stop at either end. The Lightbox opens on `start`, or on the
402
+ first image when `start` is left out or is not among them. A reference that names no image is left
403
+ out, and nothing opens when none does. Esc, the close button or a click outside the picture closes
404
+ it, and the keyboard returns to the element that had it. It resolves once the Lightbox closes. One
405
+ Lightbox is open at a time.
406
+
407
+ ```ts
408
+ thumbnail.addEventListener('click', () => void context.assets.viewImages({ refs: taskAssets, start: ref }))
409
+ ```
410
+
360
411
  ### Icons
361
412
 
362
413
  `context.icons.svg(name)` draws one of the extension's own icons or one of the Client's, as markup the
363
- Client trusts. The Client's icons, which every `icon` field may name too, are `alias`, `backlinks`, `bold`, `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`, `pageless`, `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`, `template`, `text-lines`, `today`, `todays-journal`, `trash`, `undo`, `wikilink-close`, `wikilink-open`, `zoom-in`, `zoom-out`. An
414
+ 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`, `pageless`, `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
364
415
  icon may be added in a later release, never taken away. An unknown name draws a small dot.
365
416
 
366
417
  ### Settings sections
@@ -387,6 +438,25 @@ once a graph opens, so its sections are not drawn on the Graphs page.
387
438
  text kept. It resolves to the text, trimmed, or undefined when the person cancels. The dialog names
388
439
  the extension, and shows every string it is given as text.
389
440
 
441
+ `context.dialogs.choose(options)` asks for one of a list of `choices`, picked from a dropdown and
442
+ confirmed. `submitLabel` can be a function of the value picked, so the button says what confirming
443
+ will do. It resolves to the picked choice's `value`, or undefined when the person cancels.
444
+
445
+ `context.dialogs.pickDate({ anchor, value, label })` opens the calendar the document editor's Date
446
+ Picker shows, beside the element `anchor`, on the day `value` names (`YYYY-MM-DD`) or on today.
447
+ Arrow keys move a day or a week and Page Up and Page Down a month. Enter or a click picks a day.
448
+ Esc, Tab or a click elsewhere closes the calendar. It resolves to the day as `YYYY-MM-DD`, or
449
+ undefined when it was closed without one, and the keyboard returns to `anchor` after Enter or Esc.
450
+ `label` is what a screen reader announces for the calendar. One calendar is open at a time, and
451
+ asking again with the same `anchor` closes it, so the button that opens it also closes it.
452
+
453
+ ```ts
454
+ button.addEventListener('click', async () => {
455
+ const day = await context.dialogs.pickDate({ anchor: button, value: sowing, label: 'Sowing date' })
456
+ if (day) sowing = day
457
+ })
458
+ ```
459
+
390
460
  ### Frames
391
461
 
392
462
  `context.embeds.frame({ src, title })` builds a frame showing a page from a host the Client allows,
@@ -418,6 +488,12 @@ An `address` gives the View a URL. For an extension from the Extension Directory
418
488
  to it opens the View. On a device without the extension, it opens a page that names the extension
419
489
  and offers to install it, if the directory lists it.
420
490
 
491
+ `"favourite": true` lets a person add the View to their Favourites from its tab's menu, and open it
492
+ again from the graph sidebar, where its row shows the tab's title and icon. It needs `region`
493
+ `main`, an `address`, and either a fixed `target` or an address whose `target` is `concept`. A
494
+ favourite of a View about a concept follows the concept when it is renamed. An older Client ignores
495
+ the key.
496
+
421
497
  `context.layout.openView({ kind, target })` opens a View. `context.layout.isDesktop()` says whether
422
498
  the desktop layout is showing, which it is at 1024 pixels wide and more.
423
499
 
package/dist/assets.d.ts CHANGED
@@ -1,7 +1,38 @@
1
1
  /**
2
2
  * Images an extension hands to the open graph (ADR 0147): made smaller the way a pasted image is,
3
- * and kept as one of the graph's assets, so a document can show it.
3
+ * and kept as one of the graph's assets, so a document can show it. And the assets a document
4
+ * refers to, named and shown as the document's own editor names and shows them.
4
5
  */
6
+ /**
7
+ * What a document's reference to an asset names.
8
+ *
9
+ * @public
10
+ */
11
+ export interface AssetDescription {
12
+ /**
13
+ * The file's name as a person reads it, without the hash or id the graph adds to keep names
14
+ * apart: `plan.png` for `plan.3f9a1c2e.png`.
15
+ */
16
+ name: string;
17
+ /** The file's whole name, as the reference writes it: for a tooltip, or where two names read alike. */
18
+ fileName: string;
19
+ /** A document shows the asset as an image. */
20
+ image: boolean;
21
+ }
22
+ /**
23
+ * Images to show in the Client's Lightbox, the dialog a picture's View larger opens.
24
+ *
25
+ * @public
26
+ */
27
+ export interface ViewImagesOptions {
28
+ /**
29
+ * The images, as a document's references write them (`../assets/plan.3f9a1c2e.png`), in the
30
+ * order Previous and Next step through them. A reference that names no image asset is left out.
31
+ */
32
+ refs: readonly string[];
33
+ /** The reference the Lightbox opens on. The first image when left out, or when it is not among them. */
34
+ start?: string;
35
+ }
5
36
  /**
6
37
  * The open graph's assets, as far as an extension may add to them.
7
38
  *
@@ -23,4 +54,24 @@ export interface ExtensionAssets {
23
54
  * where the graph keeps no assets here, or the image was refused.
24
55
  */
25
56
  saveImage(image: Blob, name: string): Promise<string | null>;
57
+ /**
58
+ * What the asset reference `ref` names, as a document writes it (`../assets/plan.3f9a1c2e.png`),
59
+ * or null when `ref` names no asset.
60
+ */
61
+ describe(ref: string): AssetDescription | null;
62
+ /**
63
+ * An address an `<img>` shows the image `ref` names at, read from the graph as the editor reads
64
+ * an image it draws: decrypted, in a synced graph. It lasts while the graph is open. Null when
65
+ * `ref` names no image, the graph keeps no assets here, or the image cannot be read just now.
66
+ */
67
+ imageUrl(ref: string): Promise<string | null>;
68
+ /**
69
+ * Show the images `options.refs` name in the Client's Lightbox, over whatever is open, a dialog
70
+ * of the extension's own included: each as large as the window allows, under its name, with
71
+ * Previous and Next (and ← and →) when there is more than one. Esc, its close button or a
72
+ * click outside the picture closes it, and the keyboard returns to the element that had it.
73
+ * Resolves once it closes. One Lightbox is open at a time: showing others closes the first.
74
+ * Nothing opens when no reference names an image.
75
+ */
76
+ viewImages(options: ViewImagesOptions): Promise<void>;
26
77
  }
package/dist/assets.js CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
2
  * Images an extension hands to the open graph (ADR 0147): made smaller the way a pasted image is,
3
- * and kept as one of the graph's assets, so a document can show it.
3
+ * and kept as one of the graph's assets, so a document can show it. And the assets a document
4
+ * refers to, named and shown as the document's own editor names and shows them.
4
5
  */
5
6
  export {};
package/dist/context.d.ts CHANGED
@@ -17,7 +17,7 @@ import type { ExtensionEmbeds } from './embeds';
17
17
  import type { ExtensionEvents } from './events';
18
18
  import type { ExtensionIndex } from './graph-index';
19
19
  import type { ExtensionJournalPanels } from './journal';
20
- import type { CommandBarButton, CommandMenuItem, ContextMenuItem, GraphSidebarButton } from './menus';
20
+ import type { CommandBarButton, CommandMenuItem, ContextMenuItem, GraphSidebarButton, MenuTarget, MenuTask } from './menus';
21
21
  import type { ExtensionGraphRecords } from './records';
22
22
  import type { SettingsSection } from './settings-sections';
23
23
  import type { ViewContribution, ViewRef } from './views';
@@ -64,6 +64,38 @@ export interface ExtensionViews {
64
64
  export interface ExtensionContextMenu {
65
65
  /** Add a row, its id under the extension's id. */
66
66
  register(item: ContextMenuItem): () => void;
67
+ /**
68
+ * The task a menu was raised on, or null when it was raised on anything else: a row of the Tasks
69
+ * View, or a task's line in an editor (a right-click on its checkbox or its words, but not on a
70
+ * link or a misspelt word in them, whose menus are about the link or the word). A task in a
71
+ * Protected Document is none. What a row offered on every task asks in its `when`, and its
72
+ * Command asks of the target it is given.
73
+ */
74
+ taskOf(target: MenuTarget): MenuTask | null;
75
+ }
76
+ /**
77
+ * A button on a notice, such as Undo.
78
+ *
79
+ * @public
80
+ */
81
+ export interface NoticeAction {
82
+ /** The button's text: a word or two. */
83
+ label: string;
84
+ /** What pressing it does. The button is greyed while a promise it returns is pending. */
85
+ run(): void | Promise<void>;
86
+ }
87
+ /**
88
+ * What a notice carries besides its text.
89
+ *
90
+ * @public
91
+ */
92
+ export interface NoticeOptions {
93
+ /**
94
+ * One button on the notice, for what a person may want to do about what it says: Undo, say. The
95
+ * notice stays until it is read or the next notice replaces it, as the Client's own do, so the
96
+ * action's own outcome is said with a notice of its own.
97
+ */
98
+ action?: NoticeAction;
67
99
  }
68
100
  /**
69
101
  * Adding Command Menu rows.
@@ -425,8 +457,11 @@ export interface ExtensionContext {
425
457
  readonly dialogs: ExtensionDialogs;
426
458
  /** Frames showing content from the hosts the Client allows. */
427
459
  readonly embeds: ExtensionEmbeds;
428
- /** Say something in passing, as the Client's own notices do: "Coordinates copied." */
429
- notify(text: string): void;
460
+ /**
461
+ * Say something in passing, as the Client's own notices do: "Coordinates copied." With
462
+ * `options.action`, the notice carries a button, such as Undo.
463
+ */
464
+ notify(text: string, options?: NoticeOptions): void;
430
465
  }
431
466
  /**
432
467
  * What an extension's main module exports.
package/dist/dialogs.d.ts CHANGED
@@ -2,7 +2,8 @@
2
2
  * Dialogs the Client draws for an extension, so every extension's questions look and behave like the
3
3
  * Client's own: the keyboard stays inside while one is open, Enter answers, Esc cancels, and the
4
4
  * keyboard returns where it was when one closes. Each dialog names the extension that asks, and
5
- * shows every string it is given as plain text, never as markup.
5
+ * shows every string it is given as plain text, never as markup. The calendar `pickDate` opens is
6
+ * drawn beside the extension's own element rather than over the page, so it names nobody.
6
7
  */
7
8
  /**
8
9
  * A question with one line of text for an answer.
@@ -26,6 +27,57 @@ export interface PromptOptions {
26
27
  */
27
28
  validate?(value: string): string | undefined;
28
29
  }
30
+ /**
31
+ * One of the answers a {@link ChooseOptions} question offers.
32
+ *
33
+ * @public
34
+ */
35
+ export interface ChooseChoice {
36
+ /** What `choose` resolves to when this answer is picked. */
37
+ value: string;
38
+ /** What the dropdown shows for it. */
39
+ label: string;
40
+ }
41
+ /**
42
+ * A question answered by picking one of a list of answers from a dropdown and confirming it.
43
+ *
44
+ * @public
45
+ */
46
+ export interface ChooseOptions {
47
+ /** The dialog's heading. */
48
+ title: string;
49
+ /** A sentence above the dropdown saying what confirming will do. */
50
+ message?: string;
51
+ /** The dropdown's label. */
52
+ label: string;
53
+ /** The answers, in the order the dropdown lists them. At least one. */
54
+ choices: ChooseChoice[];
55
+ /** The value of the answer picked when the dialog opens. The first answer when left out. */
56
+ value?: string;
57
+ /**
58
+ * The button that confirms: its words, or a function giving its words for the answer picked,
59
+ * so it can say what it will do ("Move 3 tasks to Done"). "OK" when left out.
60
+ */
61
+ submitLabel?: string | ((value: string) => string);
62
+ }
63
+ /**
64
+ * A day to pick from the Client's calendar, the one the document editor's Date Picker shows.
65
+ *
66
+ * @public
67
+ */
68
+ export interface PickDateOptions {
69
+ /**
70
+ * The element the calendar opens beside: below it, or above it where there is no room below.
71
+ * The keyboard returns to it when a day is picked or the calendar is closed with Esc. The
72
+ * calendar closes when the element leaves the page. Asking again with the same element while
73
+ * its calendar is open closes the calendar, so a button that opens it also closes it.
74
+ */
75
+ anchor: HTMLElement;
76
+ /** The day the calendar opens on, `YYYY-MM-DD`. Today when left out, or when it names no day. */
77
+ value?: string;
78
+ /** What a screen reader announces for the calendar ("Due date"). "Choose a date" when left out. */
79
+ label?: string;
80
+ }
29
81
  /**
30
82
  * Dialogs.
31
83
  *
@@ -34,4 +86,13 @@ export interface PromptOptions {
34
86
  export interface ExtensionDialogs {
35
87
  /** Ask for one line of text. Resolves to the text, trimmed, or undefined when it was cancelled. */
36
88
  prompt(options: PromptOptions): Promise<string | undefined>;
89
+ /** Ask for one of a list of answers. Resolves to the value picked, or undefined when it was cancelled. */
90
+ choose(options: ChooseOptions): Promise<string | undefined>;
91
+ /**
92
+ * Ask for a day from the Client's calendar, opened beside `options.anchor`. Arrow keys move a
93
+ * day or a week, Page Up and Page Down a month, Enter or a click picks, and Esc, Tab or a click
94
+ * elsewhere closes it. Resolves to the day as `YYYY-MM-DD`, or undefined when it was closed
95
+ * without one. One calendar is open at a time: asking for another closes the first.
96
+ */
97
+ pickDate(options: PickDateOptions): Promise<string | undefined>;
37
98
  }
package/dist/dialogs.js CHANGED
@@ -2,6 +2,7 @@
2
2
  * Dialogs the Client draws for an extension, so every extension's questions look and behave like the
3
3
  * Client's own: the keyboard stays inside while one is open, Enter answers, Esc cancels, and the
4
4
  * keyboard returns where it was when one closes. Each dialog names the extension that asks, and
5
- * shows every string it is given as plain text, never as markup.
5
+ * shows every string it is given as plain text, never as markup. The calendar `pickDate` opens is
6
+ * drawn beside the extension's own element rather than over the page, so it names nobody.
6
7
  */
7
8
  export {};
@@ -79,7 +79,7 @@ export interface DocumentTask extends Omit<DocumentSummary, 'aliases'> {
79
79
  line: number;
80
80
  /** The task's words, without the checkbox. */
81
81
  text: string;
82
- status: 'open' | 'doing' | 'waiting' | 'done' | 'cancelled';
82
+ status: 'open' | 'doing' | 'waiting' | 'test' | 'done' | 'cancelled' | 'archived';
83
83
  /** 1 is the highest; null when the task has none. */
84
84
  priority: 1 | 2 | 3 | null;
85
85
  /** `YYYY-MM-DD`, or null. */
package/dist/editor.d.ts CHANGED
@@ -44,6 +44,14 @@ export interface FenceInfo {
44
44
  * is added or removed above, so it keys only what lasts a moment.
45
45
  */
46
46
  readonly ordinal: number;
47
+ /**
48
+ * For a fence registered with `frame: 'editor'`: whether it is being edited in the document,
49
+ * where the widget draws its editor rather than its picture. The Client adds its toolbar's height
50
+ * to the widget's own. Absent for any other fence.
51
+ *
52
+ * @beta
53
+ */
54
+ readonly editing?: boolean;
47
55
  }
48
56
  /**
49
57
  * Where a widget is drawn: in the document, in a tab of its own, or filling the EtherPK window.
@@ -97,6 +105,32 @@ export interface FenceContext extends FenceInfo {
97
105
  openWindow(): void;
98
106
  /** Close the window this widget fills. Does nothing for a widget drawn elsewhere. */
99
107
  closeWindow(): void;
108
+ /**
109
+ * For a fence registered with `frame: 'editor'`: start or stop editing it in the document. The
110
+ * widget starts when the person asks to edit (a press on its picture, or `takeFocus`); the
111
+ * Client stops it from its toolbar, when the person presses outside the widget, and when another
112
+ * framed fence starts. The widget hears the change in an `update`, as `editing`, and draws its
113
+ * editor or its picture. Does nothing where the fence cannot be written or outside the document.
114
+ * Absent for any other fence.
115
+ *
116
+ * @beta
117
+ */
118
+ setEditing?(editing: boolean): void;
119
+ /**
120
+ * Undo, as Mod+Z does where the widget is drawn: in the document, the document's last change;
121
+ * in a tab or a window, the widget's own last `edit` made there. False when there was nothing
122
+ * to undo, or its lines have changed since, and then nothing changed. For an Undo button in a
123
+ * widget that does not keep its own history.
124
+ *
125
+ * @beta
126
+ */
127
+ undo?(): boolean;
128
+ /**
129
+ * Redo what `undo` took back, as Mod+Y does. False when there was nothing to redo.
130
+ *
131
+ * @beta
132
+ */
133
+ redo?(): boolean;
100
134
  }
101
135
  /**
102
136
  * A widget the extension has drawn, as the Client drives it.
@@ -108,6 +142,22 @@ export interface MountedFence {
108
142
  update(context: FenceContext): void;
109
143
  /** The widget leaves: scrolled far away, its fence deleted, its tab or the editor closed. */
110
144
  destroy(): void;
145
+ /**
146
+ * Write to the fence whatever the widget holds that is not in it yet, such as strokes a drawing
147
+ * keeps until a pause. The Client calls it before it stops editing a framed fence and before each
148
+ * toolbar action, so Edit as text shows, and Mod+Z after Delete brings back, what was drawn.
149
+ *
150
+ * @beta
151
+ */
152
+ flush?(): void;
153
+ /**
154
+ * Whether a press on `node`, outside the widget's host, is the widget's own: a dialog or menu its
155
+ * library put in the page's body. The Client then keeps editing rather than stopping. Only asked
156
+ * for a fence registered with `frame: 'editor'`.
157
+ *
158
+ * @beta
159
+ */
160
+ owns?(node: Node): boolean;
111
161
  }
112
162
  /**
113
163
  * What an extension registers for one info word.
@@ -235,6 +285,19 @@ export interface FenceOptions {
235
285
  * than the editor's.
236
286
  */
237
287
  keepsHistory?: boolean;
288
+ /**
289
+ * `'editor'` asks the Client to draw the frame a drawing has in the document, so every fence
290
+ * 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. While it is (`setEditing`), a toolbar above it
292
+ * offers Done, Full window, Open in tab, Edit as text and Delete. Full window and Open in tab
293
+ * need `identify`. Delete removes the fence as one change and says how to undo it, naming the
294
+ * fence by `title`. Only one framed fence is edited at a time, in all the documents open, and a
295
+ * press outside it stops editing it. In a tab or a window the Client draws no frame. The menu
296
+ * and toolbar show only where the document can be written.
297
+ *
298
+ * @beta
299
+ */
300
+ frame?: 'editor';
238
301
  }
239
302
  /**
240
303
  * 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
@@ -15,10 +15,10 @@
15
15
  *
16
16
  * @packageDocumentation
17
17
  */
18
- export type { CommandHandler, ExtensionCommandBar, ExtensionCommandMenu, ExtensionCommands, ExtensionConcepts, ExtensionContext, ExtensionContextMenu, ExtensionContributions, ExtensionGraphSidebar, ExtensionIcons, ExtensionKeybindings, ExtensionLayout, ExtensionModule, ExtensionPersonStorage, ExtensionSettings, ExtensionStorage, ExtensionTheme, ExtensionViews, IconMarkup, Keybinding, } from './context';
19
- export type { ExtensionAssets } from './assets';
18
+ export type { CommandHandler, ExtensionCommandBar, ExtensionCommandMenu, ExtensionCommands, ExtensionConcepts, ExtensionContext, ExtensionContextMenu, ExtensionContributions, ExtensionGraphSidebar, ExtensionIcons, ExtensionKeybindings, ExtensionLayout, ExtensionModule, ExtensionPersonStorage, ExtensionSettings, ExtensionStorage, ExtensionTheme, ExtensionViews, IconMarkup, Keybinding, NoticeAction, NoticeOptions, } from './context';
19
+ export type { AssetDescription, ExtensionAssets, ViewImagesOptions } from './assets';
20
20
  export type { AuthorizeOptions, ExtensionAuth } from './auth';
21
- export type { ExtensionDialogs, PromptOptions } from './dialogs';
21
+ export type { ChooseChoice, ChooseOptions, ExtensionDialogs, PickDateOptions, PromptOptions } from './dialogs';
22
22
  export type { DocumentBacklink, DocumentSearchResult, DocumentSummary, DocumentTask, DocumentText, ExtensionDocuments } from './documents';
23
23
  export type { ExtensionEditor, FenceContext, FenceEdit, FenceInfo, FenceOptions, FencePresentation, FenceWidget, InlinePanel, InlinePanelOptions, MountedFence, PublishedFence, PublishFenceRequest, QuoteFenceRequest, } from './editor';
24
24
  export type { ExtensionEmbeds, FrameOptions } from './embeds';
@@ -28,7 +28,7 @@ export type { ExtensionJournalPanels, JournalPanel, JournalPanelProps, MountedJo
28
28
  export type { ExtensionIsolation, ExtensionManifest, ExtensionPackage, ReadExtensionPackageResult, SettingDeclaration, ViewDeclaration, ViewRegion, } from './manifest';
29
29
  export { readExtensionPackage } from './manifest';
30
30
  export { CLIENT_COMMANDS } from './client-commands';
31
- export type { CommandBarButton, CommandMenuContext, CommandMenuItem, ContextMenuItem, DocumentMenuTarget, ExtensionMenuTarget, GraphSidebarButton, MenuTarget, TabMenuTarget, WikilinkMenuTarget, } from './menus';
31
+ export type { CommandBarButton, CommandMenuContext, CommandMenuItem, ContextMenuItem, DocumentMenuTarget, ExtensionMenuTarget, GraphSidebarButton, MenuTarget, MenuTask, TabMenuTarget, WikilinkMenuTarget, } from './menus';
32
32
  export type { ExtensionGraphRecords } from './records';
33
33
  export type { MountedSettingsSection, SettingsSection, SettingsSectionContext, SettingsSectionTab } from './settings-sections';
34
34
  export type { MountedView, ViewContribution, ViewMountProps, ViewRef, ViewVisibility } from './views';
@@ -50,6 +50,13 @@ export interface ViewDeclaration {
50
50
  segment: string;
51
51
  target?: 'concept';
52
52
  };
53
+ /**
54
+ * The person can add the View to their Favourites from its tab's menu, and open it again from
55
+ * the Graph Sidebar. Only for a `main` View with an `address`, and either a `target` (the one View
56
+ * of its kind) or an address whose target is `concept` (one View per concept, which then
57
+ * follows the concept through a rename). An older Client ignores it.
58
+ */
59
+ favourite?: boolean;
53
60
  }
54
61
  /**
55
62
  * One thing an extension asks the person to set (ADR 0134). The Client draws it under the
package/dist/manifest.js CHANGED
@@ -170,6 +170,26 @@ function checkView(view, index, id, kinds, segments, errors) {
170
170
  if (isRecord(address) && address.target !== undefined && address.target !== 'concept')
171
171
  errors.push(`${where}.address.target may only be "concept".`);
172
172
  }
173
+ checkFavourite(view, where, errors);
174
+ }
175
+ /**
176
+ * A View kind that can be a Favourite must be one the Favourites list can open again by itself:
177
+ * a main-region View with an address, and a target it can name, the kind's one View or a concept.
178
+ */
179
+ function checkFavourite(view, where, errors) {
180
+ if (view.favourite === undefined || view.favourite === false)
181
+ return;
182
+ if (view.favourite !== true) {
183
+ errors.push(`${where}.favourite must be true or false.`);
184
+ return;
185
+ }
186
+ const address = isRecord(view.address) ? view.address : undefined;
187
+ if (!address)
188
+ errors.push(`${where}.favourite needs an address, so the Favourites list can open the View.`);
189
+ else if (view.region !== 'main')
190
+ errors.push(`${where}.favourite is only for a View that opens in the main region.`);
191
+ else if (view.target === undefined && address.target !== 'concept')
192
+ errors.push(`${where}.favourite needs a target, or an address whose target is "concept".`);
173
193
  }
174
194
  /**
175
195
  * A path that stays inside the package: relative, never climbing out of it, and never an address or
package/dist/menus.d.ts CHANGED
@@ -64,6 +64,20 @@ export interface ExtensionMenuTarget {
64
64
  * @public
65
65
  */
66
66
  export type MenuTarget = DocumentMenuTarget | TabMenuTarget | WikilinkMenuTarget | ExtensionMenuTarget;
67
+ /**
68
+ * A task a Context Menu was raised on, as {@link ExtensionContextMenu.taskOf} names it: where it is,
69
+ * as a task reference names a task.
70
+ *
71
+ * @public
72
+ */
73
+ export interface MenuTask {
74
+ /** The concept of the document the task is in. */
75
+ document: string;
76
+ /** Its line in the document's body, from 0, frontmatter left out: as the index counts lines. */
77
+ line: number;
78
+ /** The task line's text after the checkbox, its tags included. */
79
+ label: string;
80
+ }
67
81
  /**
68
82
  * One Context Menu row.
69
83
  *
@@ -139,6 +153,14 @@ export interface CommandMenuItem {
139
153
  keywords?: string[];
140
154
  /** Whether the row is offered here. Absent means everywhere. */
141
155
  when?: (context: CommandMenuContext) => boolean;
156
+ /**
157
+ * The row acts on the text at the cursor and nothing else: it inserts or formats text, or copies
158
+ * what the cursor's line holds. Only such rows are offered in an editor that shows part of a
159
+ * document, such as a Kanban task's description, where a row that acts on the tab, the document as
160
+ * a whole, a View or the graph would act on whatever is behind the dialog. Absent means the row
161
+ * is not offered there.
162
+ */
163
+ actsOnText?: boolean;
142
164
  /** The Command the row runs. */
143
165
  command: string;
144
166
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@appsoftwareltd/etherpk-extension-api",
3
- "version": "0.16.0",
3
+ "version": "0.18.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",
@@ -28,9 +28,9 @@
28
28
  },
29
29
  "devDependencies": {
30
30
  "@microsoft/api-extractor": "^7.59.2",
31
- "@vitest/coverage-v8": "^4.1.4",
31
+ "@vitest/coverage-v8": "^4.1.12",
32
32
  "typescript": "^6.0.2",
33
- "vitest": "^4.1.4"
33
+ "vitest": "^4.1.12"
34
34
  },
35
35
  "scripts": {
36
36
  "check": "tsc --noEmit && pnpm api:check",