@formicoidea/labre-core 0.46.1 → 0.47.0

package/dist/host-panels.d.ts

@@ -1,6 +1,6 @@
 import { type FramePreview } from './_pkgs/affine-fragment-frame-panel/index.js';
 import type { FrameBlockModel } from './_pkgs/affine-model/index.js';
-import type { BlockStdScope } from './_pkgs/std/index.js';
+import { type BlockStdScope, type CommandFile } from './_pkgs/std/index.js';
 /**
  * `@labre/affine/host-panels` — the verbs a host's own panel calls (ADR 0034
  * §4, docs/integrate/08-host-panels.md).
@@ -40,14 +40,23 @@ import type { BlockStdScope } from './_pkgs/std/index.js';
  * cannot find here is a gap in this module, not a reason to import a widget
  * package.
  *
+ * **The view actions** (amendment of 2026-10-13) are the same idea for a
+ * host's MENU rather than its panel: `getViewActions` projects the commands
+ * on the `'view-menu'` surface — the grid, the PNG and PDF export, Present —
+ * into rows of data (label, icon key, check, disabled), and `runViewAction`
+ * runs one and hands back the file an export produced. The host draws the
+ * rows (Labre's header ⋯, section "This view"); nothing here renders.
+ *
  * ponytail: `frameList` is a plain read, not a signal of the frame list; a
  * host follows reorders through `std.store.slots.blockUpdated` (08 says how).
  * A signal of the frame list is the upgrade path if two hosts ask.
  */
-export { type AnyCommandDescriptor, type CommandInvocation, type CommandOwner, type CommandSurface, getCommandIcon, getCommandsForSurface, getRegisteredCommands, runCommand, } from './_pkgs/std/index.js';
+export { type AnyCommandDescriptor, type CommandFile, type CommandInvocation, type CommandOwner, type CommandSurface, getCommandIcon, getCommandsForSurface, getRegisteredCommands, runCommand, runCommandAsync, } from './_pkgs/std/index.js';
 export { armArtefact } from './_pkgs/affine-widget-edgeless-toolbar/index.js';
 export { type SelectionPaneNode, selectionPaneTree, } from './_pkgs/affine-block-surface/index.js';
 export { frameCommands, type ReorderFramesParams, reorderFramesParams, } from './_pkgs/affine-block-frame/index.js';
+export { formatPropertyValue, isPropertyValueEmpty, } from './_pkgs/affine-fragment-doc-title/index.js';
+export type { PropertiesPanelRequest, PropertiesPanelService, TitleBandNotShownPage, TitleBandProperty, TitleBandService, TitleBandSheetState, } from './_pkgs/affine-shared/services/index.js';
 /**
  * The document's frames in presentation order, first slide first — the order
  * `canvas.frame.reorder` writes and the presentation walks. Works in page mode
@@ -88,3 +97,75 @@ export declare function createFramePreview(std: BlockStdScope, frame: FrameBlock
     height?: number;
     fillScreen?: boolean;
 }): FramePreview;
+/**
+ * One entry of the current view's own actions — what a host draws in the
+ * "This view" section of its menu (ADR 0034, amendment of 2026-10-13). Data
+ * only: the host owns the menu, the row, the spinner and the toast; the
+ * library owns what the entry does.
+ */
+export interface ViewAction {
+    /**
+     * The command id, stable across versions (`canvas.grid.toggle`): the key a
+     * host maps its own icon, test id or placement to, and what it passes back
+     * to {@link runViewAction}.
+     */
+    id: string;
+    /**
+     * The group the entry belongs to, from the command's `category`:
+     * `'display'` (the grid), `'export'` (PNG, PDF), `'present'`. A host draws
+     * a separator between groups, or places a group elsewhere (Labre keeps
+     * "Present" in its header). Open: a later minor may add a group.
+     */
+    section: string;
+    /** Resolved through the host's `TranslationExtension`, else English. */
+    label: string;
+    /** The `com.labre.*` key behind {@link label}, for a host that translates itself. */
+    labelKey: string;
+    /** Stable asset key; `getCommandIcon(std, iconKey)` is the library's icon. */
+    iconKey?: string;
+    /** Present only on a toggle: the state a check mark shows. */
+    checked?: boolean;
+    /**
+     * Listed but refused now (a write on a read-only document): draw it
+     * disabled. An entry that does not apply at all is not listed.
+     */
+    disabled: boolean;
+}
+/** What {@link runViewAction} hands back. */
+export interface ViewActionResult {
+    /**
+     * The file an export produced — the host downloads it, shares it, uploads
+     * it. Absent for an action that makes none, and for an export that found
+     * nothing to draw.
+     */
+    file?: CommandFile;
+}
+/**
+ * The actions proper to the view the editor shows now, in their declared
+ * order: the commands registered on the `'view-menu'` surface whose `scope`
+ * is this mode (or `'global'`) and whose `when` holds.
+ *
+ * `mode` is the view the host shows; omitted, it is read from
+ * `DocModeProvider`, and a provider that does not know (the library default
+ * answers `null`) leaves the choice to registration — the canvas commands are
+ * registered on the edgeless scope only. Flags apply by construction: a
+ * `frame: false` assembly registers no "Present", so it is not listed.
+ *
+ * Reactive when read inside an `effect` or a `computed`: `checked`, `when`
+ * and the read-only refusal read signals, so the list follows the grid, a
+ * toggle, a peer's save or a document turning read-only. Read it again after a
+ * mode switch: the `std` is rebuilt.
+ */
+export declare function getViewActions(std: BlockStdScope, mode?: 'page' | 'edgeless'): ViewAction[];
+/**
+ * Run one entry of {@link getViewActions} by its id, through `runCommand`'s
+ * bottleneck (usage and telemetry recorded once), and wait for it.
+ *
+ * Resolves when the action is done — after the export has rendered — with the
+ * file it produced, if any: the library renders, the host decides where the
+ * bytes go, and nothing is downloaded behind its back. Rejects when the action
+ * fails, so the host can say so. An id that is not a view action here, an
+ * entry that no longer applies or a refused one runs nothing and resolves
+ * with no file.
+ */
+export declare function runViewAction(std: BlockStdScope, id: string): Promise<ViewActionResult>;

package/dist/host-panels.js

@@ -1,5 +1,7 @@
 import { EdgelessFrameManagerIdentifier } from './_pkgs/affine-block-frame/index.js';
 import { AFFINE_FRAME_PREVIEW, } from './_pkgs/affine-fragment-frame-panel/index.js';
+import { DocModeProvider, translateKey } from './_pkgs/affine-shared/services/index.js';
+import { getRegisteredCommands, isCommandAvailable, runCommandAsync, } from './_pkgs/std/index.js';
 import { GfxControllerIdentifier } from './_pkgs/std/gfx/index.js';
 /**
  * `@labre/affine/host-panels` — the verbs a host's own panel calls (ADR 0034
@@ -40,14 +42,32 @@ import { GfxControllerIdentifier } from './_pkgs/std/gfx/index.js';
  * cannot find here is a gap in this module, not a reason to import a widget
  * package.
  *
+ * **The view actions** (amendment of 2026-10-13) are the same idea for a
+ * host's MENU rather than its panel: `getViewActions` projects the commands
+ * on the `'view-menu'` surface — the grid, the PNG and PDF export, Present —
+ * into rows of data (label, icon key, check, disabled), and `runViewAction`
+ * runs one and hands back the file an export produced. The host draws the
+ * rows (Labre's header ⋯, section "This view"); nothing here renders.
+ *
  * ponytail: `frameList` is a plain read, not a signal of the frame list; a
  * host follows reorders through `std.store.slots.blockUpdated` (08 says how).
  * A signal of the frame list is the upgrade path if two hosts ask.
  */
-export { getCommandIcon, getCommandsForSurface, getRegisteredCommands, runCommand, } from './_pkgs/std/index.js';
+export { getCommandIcon, getCommandsForSurface, getRegisteredCommands, runCommand, runCommandAsync, } from './_pkgs/std/index.js';
 export { armArtefact } from './_pkgs/affine-widget-edgeless-toolbar/index.js';
 export { selectionPaneTree, } from './_pkgs/affine-block-surface/index.js';
 export { frameCommands, reorderFramesParams, } from './_pkgs/affine-block-frame/index.js';
+/*
+ * The properties panel (ADR 0035 §9b and §11). The editor asks the host to
+ * show it through `PropertiesPanelExtension` and feeds the title band through
+ * `TitleBandExtension` (both registered from `@labre/affine/shared/services`,
+ * docs/integrate/04-host-seams.md); a host's own panel reads and writes the
+ * same sheet it hands the band, from its own store. What it takes from here
+ * is the band's vocabulary, so the panel and the chips read the same: the
+ * types of a sheet and of a panel request, and the text a chip draws for a
+ * value.
+ */
+export { formatPropertyValue, isPropertyValueEmpty, } from './_pkgs/affine-fragment-doc-title/index.js';
 /**
  * The document's frames in presentation order, first slide first — the order
  * `canvas.frame.reorder` writes and the presentation walks. Works in page mode
@@ -109,3 +129,64 @@ export function createFramePreview(std, frame, options = {}) {
         preview.fillScreen = options.fillScreen;
     return preview;
 }
+/**
+ * The actions proper to the view the editor shows now, in their declared
+ * order: the commands registered on the `'view-menu'` surface whose `scope`
+ * is this mode (or `'global'`) and whose `when` holds.
+ *
+ * `mode` is the view the host shows; omitted, it is read from
+ * `DocModeProvider`, and a provider that does not know (the library default
+ * answers `null`) leaves the choice to registration — the canvas commands are
+ * registered on the edgeless scope only. Flags apply by construction: a
+ * `frame: false` assembly registers no "Present", so it is not listed.
+ *
+ * Reactive when read inside an `effect` or a `computed`: `checked`, `when`
+ * and the read-only refusal read signals, so the list follows the grid, a
+ * toggle, a peer's save or a document turning read-only. Read it again after a
+ * mode switch: the `std` is rebuilt.
+ */
+export function getViewActions(std, mode) {
+    const view = mode ?? std.getOptional(DocModeProvider)?.getEditorMode();
+    return getRegisteredCommands(std)
+        .filter(command => command.surfaces.includes('view-menu'))
+        .filter(command => command.scope === 'global' || !view || command.scope === view)
+        .filter(command => !command.when || command.when(std))
+        .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+        .map(command => ({
+        id: command.id,
+        section: command.category ?? 'display',
+        label: translateKey(std, command.labelKey, command.labelFallback),
+        labelKey: command.labelKey,
+        ...(command.iconKey ? { iconKey: command.iconKey } : {}),
+        ...(command.checked ? { checked: command.checked(std) } : {}),
+        disabled: !isCommandAvailable(std, command),
+    }));
+}
+/**
+ * Run one entry of {@link getViewActions} by its id, through `runCommand`'s
+ * bottleneck (usage and telemetry recorded once), and wait for it.
+ *
+ * Resolves when the action is done — after the export has rendered — with the
+ * file it produced, if any: the library renders, the host decides where the
+ * bytes go, and nothing is downloaded behind its back. Rejects when the action
+ * fails, so the host can say so. An id that is not a view action here, an
+ * entry that no longer applies or a refused one runs nothing and resolves
+ * with no file.
+ */
+export async function runViewAction(std, id) {
+    const command = getRegisteredCommands(std).find(candidate => candidate.id === id && candidate.surfaces.includes('view-menu'));
+    if (!command)
+        return {};
+    if (command.when && !command.when(std))
+        return {};
+    if (!isCommandAvailable(std, command))
+        return {};
+    const result = {};
+    const params = {
+        deliver: file => {
+            result.file = file;
+        },
+    };
+    await runCommandAsync(std, command, { surface: 'view-menu', source: 'context-menu' }, params);
+    return result;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-core",
   "description": "Labre editor — the full BlockSuite-derived editor as one package.",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",

package/dist/_pkgs/affine-block-surface/extensions/export-manager/file-exporter.d.ts

@@ -1,26 +0,0 @@
-/** Tools for exporting files to device. For example, via browser download. */
-export declare const FileExporter: {
-    /**
-     * Create a download for the user's browser.
-     *
-     * @param filename
-     * @param text
-     * @param mimeType like `"text/plain"`, `"text/html"`, `"application/javascript"`, etc. See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types mdn docs List of MIME types}.
-     *
-     * @remarks
-     * Only accepts data in utf-8 encoding (html files, javascript source, text files, etc).
-     *
-     * @example
-     * const todoMDText = `# Todo items
-     * [ ] Item 1
-     * [ ] Item 2
-     * `
-     * FileExporter.exportFile("Todo list.md", todoMDText, "text/plain")
-     *
-     * @example
-     * const stateJsonContent = JSON.stringify({ a: 1, b: 2, c: 3 })
-     * FileExporter.exportFile("state.json", jsonContent, "application/json")
-     */
-    exportFile(filename: string, dataURL: string): void;
-    exportPng(docTitle: string | undefined, dataURL: string): void;
-};

package/dist/_pkgs/affine-block-surface/extensions/export-manager/file-exporter.js

@@ -1,73 +0,0 @@
-/* oxlint-disable no-control-regex */
-// Context: Lean towards breaking out any localizable content into constants so it's
-// easier to track content we may need to localize in the future. (i18n)
-const UNTITLED_PAGE_NAME = 'Untitled';
-/** Tools for exporting files to device. For example, via browser download. */
-export const FileExporter = {
-    /**
-     * Create a download for the user's browser.
-     *
-     * @param filename
-     * @param text
-     * @param mimeType like `"text/plain"`, `"text/html"`, `"application/javascript"`, etc. See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types mdn docs List of MIME types}.
-     *
-     * @remarks
-     * Only accepts data in utf-8 encoding (html files, javascript source, text files, etc).
-     *
-     * @example
-     * const todoMDText = `# Todo items
-     * [ ] Item 1
-     * [ ] Item 2
-     * `
-     * FileExporter.exportFile("Todo list.md", todoMDText, "text/plain")
-     *
-     * @example
-     * const stateJsonContent = JSON.stringify({ a: 1, b: 2, c: 3 })
-     * FileExporter.exportFile("state.json", jsonContent, "application/json")
-     */
-    exportFile(filename, dataURL) {
-        const element = document.createElement('a');
-        element.setAttribute('href', dataURL);
-        const safeFilename = getSafeFileName(filename);
-        element.setAttribute('download', safeFilename);
-        element.style.display = 'none';
-        document.body.append(element);
-        element.click();
-        element.remove();
-    },
-    exportPng(docTitle, dataURL) {
-        const title = docTitle?.trim() || UNTITLED_PAGE_NAME;
-        FileExporter.exportFile(title + '.png', dataURL);
-    },
-};
-function getSafeFileName(string) {
-    const replacement = ' ';
-    const filenameReservedRegex = /[<>:"/\\|?*\u0000-\u001F]/g;
-    const windowsReservedNameRegex = /^(con|prn|aux|nul|com\d|lpt\d)$/i;
-    const reControlChars = /[\u0000-\u001F\u0080-\u009F]/g;
-    const reTrailingPeriods = /\.+$/;
-    const allowedLength = 50;
-    function trimRepeated(string, target) {
-        const escapeStringRegexp = target
-            .replace(/[|\\{}()[\]^$+*?.]/g, '\\$&')
-            .replace(/-/g, '\\x2d');
-        const regex = new RegExp(`(?:${escapeStringRegexp}){2,}`, 'g');
-        return string.replace(regex, target);
-    }
-    string = string
-        .normalize('NFD')
-        .replace(filenameReservedRegex, replacement)
-        .replace(reControlChars, replacement)
-        .replace(reTrailingPeriods, '');
-    string = trimRepeated(string, replacement);
-    string = windowsReservedNameRegex.test(string)
-        ? string + replacement
-        : string;
-    const extIndex = string.lastIndexOf('.');
-    const filename = string.slice(0, extIndex).trim();
-    const extension = string.slice(extIndex);
-    string =
-        filename.slice(0, Math.max(1, allowedLength - extension.length)) +
-            extension;
-    return string;
-}