@appsoftwareltd/etherpk-extension-api 0.16.0 → 0.17.1

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
@@ -360,7 +360,7 @@ is part of the graph: it syncs, and every member of a shared graph can see it.
360
360
  ### Icons
361
361
 
362
362
  `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
363
+ Client trusts. The Client's icons, which every `icon` field may name too, are `alias`, `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`, `wikilink-close`, `wikilink-open`, `yesterday`, `zoom-in`, `zoom-out`. An
364
364
  icon may be added in a later release, never taken away. An unknown name draws a small dot.
365
365
 
366
366
  ### Settings sections
@@ -387,6 +387,10 @@ once a graph opens, so its sections are not drawn on the Graphs page.
387
387
  text kept. It resolves to the text, trimmed, or undefined when the person cancels. The dialog names
388
388
  the extension, and shows every string it is given as text.
389
389
 
390
+ `context.dialogs.choose(options)` asks for one of a list of `choices`, picked from a dropdown and
391
+ confirmed. `submitLabel` can be a function of the value picked, so the button says what confirming
392
+ will do. It resolves to the picked choice's `value`, or undefined when the person cancels.
393
+
390
394
  ### Frames
391
395
 
392
396
  `context.embeds.frame({ src, title })` builds a frame showing a page from a host the Client allows,
@@ -418,6 +422,12 @@ An `address` gives the View a URL. For an extension from the Extension Directory
418
422
  to it opens the View. On a device without the extension, it opens a page that names the extension
419
423
  and offers to install it, if the directory lists it.
420
424
 
425
+ `"favourite": true` lets a person add the View to their Favourites from its tab's menu, and open it
426
+ again from the graph sidebar, where its row shows the tab's title and icon. It needs `region`
427
+ `main`, an `address`, and either a fixed `target` or an address whose `target` is `concept`. A
428
+ favourite of a View about a concept follows the concept when it is renamed. An older Client ignores
429
+ the key.
430
+
421
431
  `context.layout.openView({ kind, target })` opens a View. `context.layout.isDesktop()` says whether
422
432
  the desktop layout is showing, which it is at 1024 pixels wide and more.
423
433
 
package/dist/dialogs.d.ts CHANGED
@@ -26,6 +26,39 @@ export interface PromptOptions {
26
26
  */
27
27
  validate?(value: string): string | undefined;
28
28
  }
29
+ /**
30
+ * One of the answers a {@link ChooseOptions} question offers.
31
+ *
32
+ * @public
33
+ */
34
+ export interface ChooseChoice {
35
+ /** What `choose` resolves to when this answer is picked. */
36
+ value: string;
37
+ /** What the dropdown shows for it. */
38
+ label: string;
39
+ }
40
+ /**
41
+ * A question answered by picking one of a list of answers from a dropdown and confirming it.
42
+ *
43
+ * @public
44
+ */
45
+ export interface ChooseOptions {
46
+ /** The dialog's heading. */
47
+ title: string;
48
+ /** A sentence above the dropdown saying what confirming will do. */
49
+ message?: string;
50
+ /** The dropdown's label. */
51
+ label: string;
52
+ /** The answers, in the order the dropdown lists them. At least one. */
53
+ choices: ChooseChoice[];
54
+ /** The value of the answer picked when the dialog opens. The first answer when left out. */
55
+ value?: string;
56
+ /**
57
+ * The button that confirms: its words, or a function giving its words for the answer picked,
58
+ * so it can say what it will do ("Move 3 tasks to Done"). "OK" when left out.
59
+ */
60
+ submitLabel?: string | ((value: string) => string);
61
+ }
29
62
  /**
30
63
  * Dialogs.
31
64
  *
@@ -34,4 +67,6 @@ export interface PromptOptions {
34
67
  export interface ExtensionDialogs {
35
68
  /** Ask for one line of text. Resolves to the text, trimmed, or undefined when it was cancelled. */
36
69
  prompt(options: PromptOptions): Promise<string | undefined>;
70
+ /** Ask for one of a list of answers. Resolves to the value picked, or undefined when it was cancelled. */
71
+ choose(options: ChooseOptions): Promise<string | undefined>;
37
72
  }
@@ -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/index.d.ts CHANGED
@@ -18,7 +18,7 @@
18
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
19
  export type { ExtensionAssets } from './assets';
20
20
  export type { AuthorizeOptions, ExtensionAuth } from './auth';
21
- export type { ExtensionDialogs, PromptOptions } from './dialogs';
21
+ export type { ChooseChoice, ChooseOptions, ExtensionDialogs, 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';
@@ -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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@appsoftwareltd/etherpk-extension-api",
3
- "version": "0.16.0",
3
+ "version": "0.17.1",
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",