@appsoftwareltd/etherpk-extension-api 0.11.0 → 0.12.0

package/README.md

@@ -259,6 +259,10 @@ The third argument to `registerFence` adds options:
   that would end the fence is changed so it can't.
 - `publish`, which says how a published site shows the fence, as a picture or a link card. An SVG
   picture is cleaned of scripts, event handlers and links that run code before the site gets it.
+- `quote`, which says how the Backlinks panel shows the fence where a reference's block holds it,
+  in the same shapes as `publish`, with the theme to draw a picture in. The widget is never mounted
+  there. Without `quote`, an ordinary fence shows as code and an Extension Fence as a note. A link's
+  picture is loaded from the web as the panel shows it, so give one only where the person agreed.
 - `identify`, which finds a fence again by an id in its body, so it can open in a tab.
 - `keepsHistory`, which leaves Mod+Z to the widget while it has the keyboard.
 

package/dist/editor.d.ts

@@ -167,6 +167,22 @@ export type PublishedFence = {
         height?: number;
     };
 };
+/**
+ * A fence as the Client hands it to the extension to quote it read-only: in the Backlinks panel and in
+ * the backlinks under a document, where a reference's block holds the fence.
+ *
+ * @public
+ */
+export interface QuoteFenceRequest {
+    /** The fence's info word. */
+    readonly info: string;
+    /** The fence's body lines. */
+    readonly body: readonly string[];
+    /** The document the fence is in, by its concept. */
+    readonly document: string;
+    /** Whether the dark theme shows: a picture is drawn for it. */
+    readonly dark: boolean;
+}
 /**
  * Options for a fence registration.
  *
@@ -195,6 +211,20 @@ export interface FenceOptions {
      * off), an Extension Fence is left out and an ordinary fence is published as code.
      */
     publish?(fence: PublishFenceRequest): PublishedFence | null | Promise<PublishedFence | null>;
+    /**
+     * How a read-only quote of the fence shows it, such as a reference in the Backlinks panel: a
+     * picture, drawn in the theme asked for, or a link. Null, or no `quote`, shows what the quote
+     * shows without the extension: an ordinary fence's text as code, and for an Extension Fence a note
+     * naming the extension. The Client never mounts the widget in a quote.
+     *
+     * Called as a quote shows the fence, and again when its text, the theme or one of the extension's
+     * own settings changes. The Client keeps the last answers it was given, so a reference shown
+     * again does not ask again, and it treats an answer that takes more than 30 seconds as a failure.
+     * A link's picture is loaded from the web as the quote shows it, so give one only where the
+     * person has agreed to that, as a setting for thumbnails does. An SVG picture is cleaned first, as
+     * one for a published site is.
+     */
+    quote?(fence: QuoteFenceRequest): PublishedFence | null | Promise<PublishedFence | null>;
     /**
      * The fence's own id, read from its body, or null. A fence with an id can be opened in a tab or a
      * window, where the Client finds it again by the id after every change.

package/dist/index.d.ts

@@ -17,7 +17,7 @@
 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 { ExtensionEditor, FenceContext, FenceEdit, FenceInfo, FenceOptions, FencePresentation, FenceWidget, MountedFence, PublishedFence, PublishFenceRequest, QuoteFenceRequest, } 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsoftwareltd/etherpk-extension-api",
-  "version": "0.11.0",
+  "version": "0.12.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",