@appsoftwareltd/etherpk-extension-api 0.10.2 → 0.11.0

package/README.md

@@ -123,11 +123,101 @@ person sets it, and hears every change with `context.settings.subscribe`. A swit
 graph, the settings follow them to their other devices, encrypted so that only those devices can read
 them.
 
+`context.settings.set('api-key', value)` sets one of the manifest's settings, as the person would in
+Settings, or clears it with `null`. It is for a screen of the extension's own where the person types
+the value, such as a setup guide. It throws for a setting the manifest does not declare, and a switch
+takes only `'true'` or `'false'`.
+
 ### Storage
 
 `context.storage` keeps the extension's own values on the device, as JSON, with `get`, `set` and
 `remove`. It is for what the extension works out or caches, not for what the person sets.
 
+### Records kept with the person
+
+`context.personStorage` keeps the extension's own records with the person rather than on one
+device, such as what signing in to another service gave it. It has `get`, `set`, `remove` and
+`subscribe`, and keeps each record as JSON, at most 64 KB of it, under a key of letters, digits,
+`.`, `_` and `-`. Where the person's account syncs a graph, the records follow them to their other
+devices in the account's vault, encrypted so that only those devices can read them, and the later
+change to a record wins. The person never sees them, and uninstalling the extension clears them on
+every device.
+
+A record is no more private than a setting. Any code in EtherPK's page can read it on the device,
+and so can an agent the person gave an agent token for their account, so say in the extension what
+it keeps.
+
+### Signing in to another service
+
+`context.auth` runs an OAuth 2.0 sign-in in a popup. The service sends the popup back to the
+Client's one return page, `context.auth.redirectUri` (the Client's address followed by
+`/extension-sign-in`), which the person registers with the service once, for every extension.
+
+```ts
+const answer = await context.auth.authorize(`https://accounts.example.com/authorize?client_id=…&redirect_uri=${encodeURIComponent(context.auth.redirectUri)}&state=${state}&…`, { signal })
+if (answer.error) throw new Error(answer.error)
+// answer.code: exchange it at the service's token endpoint.
+```
+
+- The address must carry a `state`: only a return with the same `state` answers the call.
+- Call `authorize` inside the click that asked for it, with nothing awaited before it, because a
+  browser blocks a popup opened later. Work that takes time, such as a PKCE challenge, is done
+  before the click.
+- `authorize` resolves with the parameters the service sent back, `error` among them when the
+  person refused. It rejects when the browser blocks the popup, when `signal` aborts, or after ten
+  minutes. It does not reject when the person closes the popup, which the Client cannot always tell,
+  so offer a Cancel that aborts `signal`.
+- The extension builds the request and exchanges the code itself: the Client knows no service.
+
+### Journal Panels
+
+A Journal Panel draws beneath a journal entry's text, above its backlinks, about that day, such as
+the day's events from a calendar. It is outside the document, so nothing in it is synced with the
+graph, searched or published.
+
+```ts
+context.journalPanels.register({
+    id: 'weather.day',
+    mount(element, { day, visibility }) {
+        // `day` is YYYY-MM-DD. Load once `visibility.onScreen` is true.
+        element.textContent = `Forecast for ${day}`
+        return { destroy: () => element.replaceChildren() }
+    },
+})
+```
+
+The Client mounts a panel for each journal tab's own entry, a day with nothing written included, and
+never for the older days shown beneath it. A panel is as tall as what it draws, so one that draws
+nothing takes no space, and it draws its own heading and spacing. It mounts in a shadow root with the
+extension's stylesheets, as a View does.
+
+### Graph Sidebar buttons
+
+A button in the Graph Sidebar, below Search and today's date, runs a Command:
+`context.graphSidebar.register({ id, title, description, icon, order, when, command })`. These rules
+keep the buttons readable together:
+
+- **`title`** is short. Two buttons sit side by side in the sidebar at its default width of 304
+  pixels, and "Graph Kanban", with its icon, is about the widest that fits.
+- **`description`** says what the button does, such as "Open a map of every place and route in this
+  graph". The Client shows it as the button's help text. Don't write a keyboard shortcut in it: the
+  Client adds the key chords bound to the button's Command itself.
+- **`icon`** is clear on its own. On a phone the buttons show their icons only.
+- **`when`** hides the button where it does not apply. A button for the desktop alone passes
+  `when: () => context.layout.isDesktop()`. A `when` that throws hides the button too.
+- **`order`** places the button among the others. The Graph Map's is 20 and the Graph Kanban's is
+  30.
+
+### Opening documents, the theme and Events
+
+- `context.layout.openDocument(concept)` opens a document as following a wikilink does. A day's
+  name, `YYYY-MM-DD`, opens its journal entry.
+- `context.theme.isDark()` says whether the dark theme shows, and the `theme:changed` Event reports a
+  switch. EtherPK's `--gk-*` colour tokens reach into a shadow root and change with the theme by
+  themselves.
+- `context.events.on(name, listener)` hears the Client's Events: `document:active-changed`,
+  `concept:renamed`, `document:deleted`, `documents:changed` and `theme:changed`.
+
 ### Fence widgets
 
 A fence widget draws over a fenced block in a document, in place of its text. The extension
@@ -254,33 +344,15 @@ code runs under them.
 The Proposed parts are for the extensions that come with EtherPK, and may change in any release.
 They include:
 
-- Context Menu rows (`contextMenu`), key chords (`keybindings`) and Graph Sidebar buttons
-  (`graphSidebar`).
-- Events (`events`), questions to the graph's index (`index`) and the rules for naming a concept
-  (`concepts`).
-- The theme (`theme`), the Client's icons (`icons`) and a View that lives in a Sidebar (`resident`).
-- Running another extension's Commands (`commands.execute`) and opening documents
-  (`layout.openDocument`).
+- Context Menu rows (`contextMenu`) and key chords (`keybindings`).
+- Questions to the graph's index (`index`) and the rules for naming a concept (`concepts`).
+- The Client's icons (`icons`) and a View that lives in a Sidebar (`resident`).
+- Running another extension's Commands (`commands.execute`), and the document the person is working
+  in (`layout.activeDocument`).
 
 `contributions`, which reaches the Client's own registries, stays Proposed for good, since its
 shape is the Client's internals.
 
-### Graph Sidebar buttons
-
-A button in the Graph Sidebar, below Search and today's date, runs a Command. These rules keep the
-buttons readable together:
-
-- **`title`** is short. Two buttons sit side by side in the sidebar at its default width of 304
-  pixels, and "Graph Kanban", with its icon, is about the widest that fits.
-- **`description`** says what the button does, such as "Open a map of every place and route in this
-  graph". The Client shows it as the button's help text. Don't write a keyboard shortcut in it: the
-  Client adds the key chords bound to the button's Command itself.
-- **`icon`** is clear on its own. On a phone the buttons show their icons only.
-- **`when`** hides the button where it does not apply. A button for the desktop alone passes
-  `when: () => context.layout.isDesktop()`. A `when` that throws hides the button too.
-- **`order`** places the button among the others. The Graph Map's is 20 and the Graph Kanban's is
-  30.
-
 ## Trying an extension
 
 To try an extension, build it, and start a development copy of the EtherPK Client with the

package/dist/auth.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Signing in to another service from an extension (ADR 0140), such as a calendar, with OAuth 2.0 in
+ * a popup. Extensions cannot add pages to the Client, so the Client has one page every sign-in
+ * returns to, `redirectUri`, which passes what the service sent back to the window that opened the
+ * popup. The extension builds the sign-in request itself (its client id, scopes, PKCE and `state`),
+ * so nothing in the Client is tied to one service.
+ */
+/**
+ * How long a sign-in may take, and how to give up on it.
+ *
+ * @public
+ */
+export interface AuthorizeOptions {
+    /** Aborting it gives up on the sign-in: `authorize` rejects, and its popup is closed. */
+    signal?: AbortSignal;
+}
+/**
+ * Signing in to another service.
+ *
+ * @public
+ */
+export interface ExtensionAuth {
+    /**
+     * The address a sign-in returns to: this Client's origin followed by `/extension-sign-in`. It is
+     * the same for every extension and every graph, so the person registers it with the service
+     * once.
+     */
+    readonly redirectUri: string;
+    /**
+     * Open `url`, the service's sign-in address, in a popup, and wait for the service to send the
+     * popup back to `redirectUri`. Resolves with the parameters it came back with, from its query
+     * and its fragment, such as `code` and `state`, or `error` when the person refused. The popup is
+     * closed by then.
+     *
+     * `url` must carry a `state` parameter: only a return with the same `state` answers this call,
+     * so two sign-ins at once, in this tab or another, never take each other's answer. Call it from
+     * a click or a key press, because a browser blocks a popup opened at any other time. Rejects when
+     * the popup is blocked, when `options.signal` aborts, or after ten minutes. A person who closes
+     * the popup without finishing is not reported, since the Client cannot always tell, so the
+     * extension offers a way to give up (`options.signal`).
+     */
+    authorize(url: string, options?: AuthorizeOptions): Promise<Record<string, string>>;
+}

package/dist/auth.js

@@ -0,0 +1,8 @@
+/**
+ * Signing in to another service from an extension (ADR 0140), such as a calendar, with OAuth 2.0 in
+ * a popup. Extensions cannot add pages to the Client, so the Client has one page every sign-in
+ * returns to, `redirectUri`, which passes what the service sent back to the window that opened the
+ * popup. The extension builds the sign-in request itself (its client id, scopes, PKCE and `state`),
+ * so nothing in the Client is tied to one service.
+ */
+export {};

package/dist/context.d.ts

@@ -7,11 +7,13 @@
  * only through the index's answers and its own fences, and changes them only through its fences,
  * the blocks it puts at the caret and the Client's Commands.
  */
+import type { ExtensionAuth } from './auth';
 import type { ExtensionDialogs } from './dialogs';
 import type { ExtensionEditor } from './editor';
 import type { ExtensionEmbeds } from './embeds';
 import type { ExtensionEvents } from './events';
 import type { ExtensionIndex } from './graph-index';
+import type { ExtensionJournalPanels } from './journal';
 import type { CommandMenuItem, ContextMenuItem, GraphSidebarButton } from './menus';
 import type { ViewContribution, ViewRef } from './views';
 /**
@@ -74,7 +76,7 @@ export interface ExtensionCommandMenu {
 /**
  * Adding buttons to the Graph Sidebar's group of action buttons, after Search and today's date.
  *
- * @beta
+ * @public
  */
 export interface ExtensionGraphSidebar {
     /** Add a button, its id under the extension's id. */
@@ -128,9 +130,8 @@ export interface ExtensionLayout {
     /**
      * Open the document of a concept, under the name it resolves to, as following a wikilink
      * does. `line` scrolls to and selects that line, `inPaneOf` and `beside` place it as for
-     * {@link ExtensionLayout.openView}.
-     *
-     * @beta
+     * {@link ExtensionLayout.openView}. A day's name, `YYYY-MM-DD`, opens its Journal Entry, or a Draft
+     * of it when nothing is written for that day yet.
      */
     openDocument(concept: string, options?: {
         line?: number;
@@ -175,7 +176,8 @@ export interface ExtensionStorage {
  * The person's answers to the settings the extension's manifest declares (`settings`, ADR 0134).
  * The Client draws them under the extension's entry in Settings and Extensions → Extensions, and
  * keeps them with the person: on this device, and in their account where it syncs a graph, so they
- * follow the person to their other devices. The extension only reads them.
+ * follow the person to their other devices. The extension reads them, and may set them where it
+ * explains them itself, such as a setup screen asking for a key.
  *
  * @public
  */
@@ -191,11 +193,49 @@ export interface ExtensionSettings {
      * Returns the way to stop.
      */
     subscribe(listener: () => void): () => void;
+    /**
+     * Set one of the settings the manifest declares, as the person would in Settings and Extensions,
+     * or clear it with null or empty text. A `boolean` setting takes `'true'` or `'false'`. Throws
+     * for a setting the manifest does not declare. Call it only for what the person typed or chose:
+     * the setting is theirs.
+     */
+    set(id: string, value: string | null): void;
+}
+/**
+ * The extension's own records, kept with the person (ADR 0140): on this device, and where the
+ * person's account syncs a graph, in that account's vault too, encrypted on the device so only the
+ * person's own devices can read them. So a record follows the person to their other devices, as
+ * Extension Settings do, such as what signing in to another service gave the extension. The person
+ * never sees these records, and uninstalling the extension clears them on every device.
+ *
+ * Each record is kept as JSON, at most 64 KB of it. Between two devices the later change to a
+ * record wins, record by record. A record is readable on the device by any code in the page, as
+ * localStorage is, and by a Headless Client given an agent token for the same account, which opens
+ * the account's vault.
+ *
+ * @public
+ */
+export interface ExtensionPersonStorage {
+    /** The record under `key`, or undefined when there is none or it cannot be read. */
+    get<T>(key: string): T | undefined;
+    /**
+     * Keep a record under `key`: letters, digits, `.`, `_` and `-`, at most 100 of them. Setting
+     * undefined or null removes it. Throws when the key is not one of those, or the record's JSON is
+     * longer than 64 KB.
+     */
+    set(key: string, value: unknown): void;
+    /** Remove the record under `key`. */
+    remove(key: string): void;
+    /**
+     * Hear every change to the extension's records, made on this device or arriving from another.
+     * Returns the way to stop.
+     */
+    subscribe(listener: () => void): () => void;
 }
 /**
  * The Client's light or dark theme.
  *
- * @beta
+ * @public
  */
 export interface ExtensionTheme {
     /** True while the dark theme shows. The `theme:changed` Event reports a switch. */
@@ -293,12 +333,10 @@ export interface ExtensionContext {
     readonly contextMenu: ExtensionContextMenu;
     /** Adding Command Menu rows. */
     readonly commandMenu: ExtensionCommandMenu;
-    /**
-     * Adding buttons to the Graph Sidebar.
-     *
-     * @beta
-     */
+    /** Adding buttons to the Graph Sidebar. */
     readonly graphSidebar: ExtensionGraphSidebar;
+    /** Adding panels beneath each Journal Entry. */
+    readonly journalPanels: ExtensionJournalPanels;
     /**
      * Adding key chords.
      *
@@ -311,11 +349,7 @@ export interface ExtensionContext {
      * @beta
      */
     readonly contributions: ExtensionContributions;
-    /**
-     * Listening to Events.
-     *
-     * @beta
-     */
+    /** Listening to Events. */
     readonly events: ExtensionEvents;
     /**
      * Questions to the open graph's index.
@@ -335,11 +369,11 @@ export interface ExtensionContext {
     readonly storage: ExtensionStorage;
     /** The person's answers to the settings the manifest declares. */
     readonly settings: ExtensionSettings;
-    /**
-     * The Client's light or dark theme.
-     *
-     * @beta
-     */
+    /** The extension's own records, kept with the person and following them to their devices. */
+    readonly personStorage: ExtensionPersonStorage;
+    /** Signing in to another service. */
+    readonly auth: ExtensionAuth;
+    /** The Client's light or dark theme. */
     readonly theme: ExtensionTheme;
     /**
      * The Client's icons and the extension's own.

package/dist/events.d.ts

@@ -6,7 +6,7 @@
  * Each Event's name and what it carries. Every Event belongs to the open graph, named by
  * `graphId`.
  *
- * @beta
+ * @public
  */
 export interface ExtensionEventPayloads {
     /** The document the user is working in changed, or there is none (`documentId` is null). */
@@ -47,13 +47,13 @@ export interface ExtensionEventPayloads {
 /**
  * An Event's name.
  *
- * @beta
+ * @public
  */
 export type ExtensionEventName = keyof ExtensionEventPayloads;
 /**
  * Listening to Events.
  *
- * @beta
+ * @public
  */
 export interface ExtensionEvents {
     /** Listen to one Event until the returned function is called or the extension stops. */

package/dist/index.d.ts

@@ -14,12 +14,14 @@
  *
  * @packageDocumentation
  */
-export type { CommandHandler, ExtensionCommandMenu, ExtensionCommands, ExtensionConcepts, ExtensionContext, ExtensionContextMenu, ExtensionContributions, ExtensionGraphSidebar, ExtensionIcons, ExtensionKeybindings, ExtensionLayout, ExtensionModule, ExtensionSettings, ExtensionStorage, ExtensionTheme, ExtensionViews, IconMarkup, Keybinding, } from './context';
+export type { CommandHandler, ExtensionCommandMenu, ExtensionCommands, ExtensionConcepts, ExtensionContext, ExtensionContextMenu, ExtensionContributions, ExtensionGraphSidebar, ExtensionIcons, ExtensionKeybindings, ExtensionLayout, ExtensionModule, ExtensionPersonStorage, ExtensionSettings, ExtensionStorage, ExtensionTheme, ExtensionViews, IconMarkup, Keybinding, } from './context';
+export type { AuthorizeOptions, ExtensionAuth } from './auth';
 export type { ExtensionDialogs, PromptOptions } from './dialogs';
 export type { ExtensionEditor, FenceContext, FenceEdit, FenceInfo, FenceOptions, FencePresentation, FenceWidget, MountedFence, PublishedFence, PublishFenceRequest, } from './editor';
 export type { ExtensionEmbeds, FrameOptions } from './embeds';
 export type { ExtensionEventName, ExtensionEventPayloads, ExtensionEvents } from './events';
 export type { ConceptCandidate, ConceptKind, ExtensionIndex, IndexUpdate, LinkGraph, LinkGraphConcept, LinkGraphLink } from './graph-index';
+export type { ExtensionJournalPanels, JournalPanel, JournalPanelProps, MountedJournalPanel } from './journal';
 export type { ExtensionIsolation, ExtensionManifest, ExtensionPackage, ReadExtensionPackageResult, SettingDeclaration, ViewDeclaration, ViewRegion, } from './manifest';
 export { readExtensionPackage } from './manifest';
 export type { CommandMenuContext, CommandMenuItem, ContextMenuItem, DocumentMenuTarget, ExtensionMenuTarget, GraphSidebarButton, MenuTarget, TabMenuTarget, WikilinkMenuTarget, } from './menus';

package/dist/journal.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The [[Journal Panel]]: a strip an extension draws beneath a Journal Entry's text and above its
+ * Backlinks, about the entry's day, such as that day's events from a calendar. It is outside the
+ * document: nothing in it is part of the entry's text, so it is never synced with the graph,
+ * searched, exported or published.
+ */
+import type { ViewVisibility } from './views';
+/**
+ * What a Journal Panel is mounted with.
+ *
+ * @public
+ */
+export interface JournalPanelProps {
+    /** The Journal Entry's day, `YYYY-MM-DD`. */
+    day: string;
+    /**
+     * The id of the panel the entry's tab is open in, on a desktop: what a Layout call names to open
+     * something in the same Pane or beside it. A phone passes none. It is fixed for the panel's
+     * life: a tab moved to another Pane is drawn afresh there.
+     */
+    panelId?: string;
+    /**
+     * Whether the entry's tab can be seen right now, and when that changes. A panel that loads
+     * anything waits until it can be seen.
+     */
+    visibility: ViewVisibility;
+}
+/**
+ * A Journal Panel the extension has drawn, as the Client drives it.
+ *
+ * @public
+ */
+export interface MountedJournalPanel {
+    /** The tab closed, the graph closed, or the extension was switched off. */
+    destroy(): void;
+}
+/**
+ * A Journal Panel an extension registers.
+ *
+ * @public
+ */
+export interface JournalPanel {
+    /** Under the extension's id. */
+    id: string;
+    /**
+     * Draw the panel into `element`, which is empty and is the extension's alone. For a loaded
+     * extension it sits inside a shadow root that holds the extension's own stylesheets, as a View
+     * does, and it is as tall as what the extension draws in it: a panel that draws nothing takes no
+     * space. The Client calls it once for each journal tab, the tab's own entry only, a Draft
+     * included, and never for the older entries of the Journal Roll. A file dropped on the panel is
+     * added to the end of the entry, as one dropped below the text is, unless the panel's own drop
+     * handler calls `preventDefault`.
+     */
+    mount(element: HTMLElement, props: JournalPanelProps): MountedJournalPanel;
+}
+/**
+ * Adding Journal Panels.
+ *
+ * @public
+ */
+export interface ExtensionJournalPanels {
+    /**
+     * Add a panel beneath every journal tab's entry, those open already included. Panels from
+     * several extensions stack in the order they were added.
+     */
+    register(panel: JournalPanel): () => void;
+}

package/dist/journal.js

@@ -0,0 +1 @@
+export {};

package/dist/menus.d.ts

@@ -154,7 +154,7 @@ export interface CommandMenuItem {
  * to what the extension shows for the whole graph, such as the Graph Map. Pressing it runs
  * `command`.
  *
- * @beta
+ * @public
  */
 export interface GraphSidebarButton {
     /** Under the extension's id. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsoftwareltd/etherpk-extension-api",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "The API an EtherPK extension is written against: the context it is started with, its manifest, and the contract its Views follow.",
   "type": "module",