@appsoftwareltd/etherpk-extension-api 0.12.0 → 0.14.0

package/dist/manifest.d.ts

@@ -35,8 +35,6 @@ export interface ViewDeclaration {
     /**
      * The View lives in a Sidebar from the moment a graph opens, beside the Client's own residents,
      * and the Sidebar's toggle brings it back if it was closed. `desktopOnly` keeps it off a phone.
-     *
-     * @beta
      */
     resident?: {
         side: 'left' | 'right';
@@ -132,7 +130,7 @@ export interface ExtensionManifest {
  * An extension's package as the Client reads it: the standard package.json fields it uses and the
  * manifest.
  *
- * @beta
+ * @public
  */
 export interface ExtensionPackage {
     /** The npm package name. */
@@ -149,7 +147,7 @@ export interface ExtensionPackage {
 /**
  * The answer of {@link readExtensionPackage}: the package, or every way its manifest is wrong.
  *
- * @beta
+ * @public
  */
 export type ReadExtensionPackageResult = {
     ok: true;
@@ -164,6 +162,6 @@ export type ReadExtensionPackageResult = {
  * Checks what the Client depends on: names it uses as keys, paths it resolves, and declarations
  * it registers before any of the extension's code runs. It does not check that files exist.
  *
- * @beta
+ * @public
  */
 export declare function readExtensionPackage(packageJson: unknown): ReadExtensionPackageResult;

package/dist/manifest.js

@@ -14,7 +14,7 @@ const ICON_MARKUP_LIMIT = 4096;
  * Checks what the Client depends on: names it uses as keys, paths it resolves, and declarations
  * it registers before any of the extension's code runs. It does not check that files exist.
  *
- * @beta
+ * @public
  */
 export function readExtensionPackage(packageJson) {
     const errors = [];

package/dist/menus.d.ts

@@ -5,7 +5,7 @@
 /**
  * A document, reached from its tab, a Favourite, Recents or an All Documents row.
  *
- * @beta
+ * @public
  */
 export interface DocumentMenuTarget {
     /** Where the menu was raised: the document's tab, or a row naming it. */
@@ -20,7 +20,7 @@ export interface DocumentMenuTarget {
 /**
  * A tab that is not a document's.
  *
- * @beta
+ * @public
  */
 export interface TabMenuTarget {
     /** Any tab that is not a document's. */
@@ -33,7 +33,7 @@ export interface TabMenuTarget {
 /**
  * A wikilink in an editor.
  *
- * @beta
+ * @public
  */
 export interface WikilinkMenuTarget {
     /** A wikilink in an editor. */
@@ -47,7 +47,7 @@ export interface WikilinkMenuTarget {
  * A thing an extension raises a menu on, of a kind the extension names under its own id
  * (`kanban.card`). Only rows that check for that kind apply to it.
  *
- * @beta
+ * @public
  */
 export interface ExtensionMenuTarget {
     /** `<extension id>.<name>`. */
@@ -58,15 +58,16 @@ export interface ExtensionMenuTarget {
 /**
  * What a Context Menu can be raised on that an extension may add rows to. The Client also raises
  * menus on things this list does not name, an Asset or a misspelt word, so a row's `when` answers
- * false for any kind it does not check for.
+ * false for any kind it does not check for. Kinds are only ever added to the list: when the Client
+ * no longer raises a menu on one, its rows are simply not shown.
  *
- * @beta
+ * @public
  */
 export type MenuTarget = DocumentMenuTarget | TabMenuTarget | WikilinkMenuTarget | ExtensionMenuTarget;
 /**
  * One Context Menu row.
  *
- * @beta
+ * @public
  */
 export interface ContextMenuItem {
     /** Under the extension's id: `graph-view.showConcept`. */
@@ -81,6 +82,8 @@ export interface ContextMenuItem {
     icon?: string;
     /** A separator above the row. */
     separatorBefore?: boolean | ((target: MenuTarget) => boolean);
+    /** The row deletes or removes something for good, so it is drawn in the danger colour, as the Client's own Delete rows are. */
+    danger?: boolean;
     /** Whether the row applies to a target. Absent means every target. */
     when?: (target: MenuTarget) => boolean;
 }
@@ -94,8 +97,6 @@ export interface CommandMenuContext {
     inTable: boolean;
     /**
      * A table may be inserted at the caret.
-     *
-     * @beta
      */
     tableInsertable: boolean;
     /** The document's body may be written: false in a locked Protected Document. */
@@ -110,8 +111,6 @@ export interface CommandMenuContext {
      * caret line's links, the links above it in the outline, the document's own concept, then the
      * scopes in its name. Names are as written, an alias as the alias. Worked out only when a row
      * reads it. Absent reads as none.
-     *
-     * @beta
      */
     readonly conceptsAtCaret?: readonly string[];
 }
@@ -144,11 +143,33 @@ export interface CommandMenuItem {
     command: string;
     /**
      * What the Command is given.
-     *
-     * @beta
      */
     args?: unknown;
 }
+/**
+ * A button on the Command Bar, the row of buttons across the bottom of a phone's screen. Pressing
+ * it runs `command` and leaves the keyboard where it was, so a Command can tell whether the caret
+ * is in the document.
+ *
+ * @public
+ */
+export interface CommandBarButton {
+    /** Under the extension's id. */
+    id: string;
+    /** The button's name, said to a screen reader and shown as its tooltip: the bar shows icons only. */
+    title: string;
+    /** Its icon: the extension's own or one of the Client's. */
+    icon: string;
+    /**
+     * In the bar's pinned group at its right end, which never scrolls away, rather than after the
+     * editing buttons that scroll. For an action a person reaches for often.
+     */
+    pinned?: boolean;
+    /** The Command the button runs. */
+    command: string;
+    /** What the Command is given. */
+    args?: unknown;
+}
 /**
  * A button in the Graph Sidebar's group of action buttons, after Search and today's date: a way in
  * to what the extension shows for the whole graph, such as the Graph Map. Pressing it runs

package/dist/records.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Records an extension keeps on this device for the open graph alone (ADR 0147): never synced,
+ * never seen by another device or another member, and deleted when the graph's data is removed
+ * from the device. For what is the person's work on this device, such as a chat they have not
+ * saved, rather than a preference that should follow them (`personStorage`).
+ */
+/**
+ * The extension's records for the open graph on this device.
+ *
+ * Each record is stored as the browser's structured clone of the value, so it may hold a `Blob`,
+ * an `ArrayBuffer`, a `Date` or plain data, but no function. A record holds at most 4 MB: its text
+ * and the bytes of every `Blob` and buffer in it. A larger one is refused. Records live in the browser's
+ * IndexedDB, which a private window or a full disk may refuse: a refused write rejects, and a
+ * refused read answers as if there were nothing.
+ *
+ * @public
+ */
+export interface ExtensionGraphRecords {
+    /** The record under `key`, or undefined when there is none. */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Keep a record under `key`: letters, digits, `.`, `_`, `:` and `-`, at most 200 of them.
+     * Rejects when the key is not one of those, the record is over 4 MB, or the browser refuses
+     * the write (a full disk, a private window).
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /** Remove the record under `key`. */
+    remove(key: string): Promise<void>;
+    /** The keys of every record the extension keeps for the open graph, sorted. */
+    keys(): Promise<string[]>;
+}

package/dist/records.js

@@ -0,0 +1,7 @@
+/**
+ * Records an extension keeps on this device for the open graph alone (ADR 0147): never synced,
+ * never seen by another device or another member, and deleted when the graph's data is removed
+ * from the device. For what is the person's work on this device, such as a chat they have not
+ * saved, rather than a preference that should follow them (`personStorage`).
+ */
+export {};

package/dist/settings-sections.d.ts

@@ -0,0 +1,62 @@
+/**
+ * An extension's own section in the Client's settings (ADR 0134, amended 2026-10-15 and
+ * 2026-10-17), for settings that belong to the person and need more than the fields a manifest
+ * can declare, such as a list of accounts with a button that connects one. The main module exports
+ * them as `settingsSections`.
+ *
+ * The Client draws an extension's sections in a graph's Settings and Extensions while the extension
+ * runs there. An extension that comes with EtherPK is loaded with the Client, so its sections are
+ * drawn on the Graphs page too, with no graph open. Any other extension's code is loaded only once
+ * a graph opens, so its sections are not drawn on the Graphs page.
+ */
+import type { ExtensionAuth } from './auth';
+import type { ExtensionPersonStorage, ExtensionSettings, ExtensionTheme } from './context';
+/**
+ * Where an extension's settings section is drawn: `extension`, under the extension's own entry in
+ * the Extensions area, beside the settings its manifest declares; or `agents`, in the Agents tab.
+ *
+ * @public
+ */
+export type SettingsSectionTab = 'extension' | 'agents';
+/**
+ * What a settings section is mounted with: what belongs to the person, and nothing from a graph,
+ * since there may be no graph open.
+ *
+ * @public
+ */
+export interface SettingsSectionContext {
+    /** The extension's id, from its manifest. */
+    readonly extensionId: string;
+    /** The person's answers to the settings the manifest declares. */
+    readonly settings: ExtensionSettings;
+    /** The extension's records kept with the person. */
+    readonly personStorage: ExtensionPersonStorage;
+    /** Signing in to another service. */
+    readonly auth: ExtensionAuth;
+    /** The Client's light or dark theme. */
+    readonly theme: ExtensionTheme;
+    /** Say something in passing, as the Client's own notices do. */
+    notify(text: string): void;
+}
+/**
+ * A section the section's host element shows, as the Client drives it.
+ *
+ * @public
+ */
+export interface MountedSettingsSection {
+    /** The tab closed, or the extension was switched off. */
+    destroy(): void;
+}
+/**
+ * One settings section an extension adds.
+ *
+ * @public
+ */
+export interface SettingsSection {
+    /** Unique within the extension. */
+    id: string;
+    /** The tab it goes in. */
+    tab: SettingsSectionTab;
+    /** Draw the section into `element`, which is empty and is the extension's alone. */
+    mount(element: HTMLElement, context: SettingsSectionContext): MountedSettingsSection;
+}

package/dist/settings-sections.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsoftwareltd/etherpk-extension-api",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -9,13 +9,15 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./controls.css": "./controls.css"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
     "dist",
+    "controls.css",
     "LICENSE",
     "README.md"
   ],