@formicoidea/labre-core 0.45.0 → 0.46.0

package/dist/host-panels.d.ts

@@ -0,0 +1,90 @@
+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';
+/**
+ * `@labre/affine/host-panels` — the verbs a host's own panel calls (ADR 0034
+ * §4, docs/integrate/08-host-panels.md).
+ *
+ * A host that draws its own artefact catalogue, selection pane or slide list
+ * needs a handful of editor verbs: list a framework's artefacts, arm one, run
+ * a command, read the canvas stack, list the frames in presentation order,
+ * select a model, frame it in the viewport. They existed before this module,
+ * spread over four packages and three levels of abstraction (`armArtefact` in
+ * the edgeless toolbar widget, `selectionPaneTree` in the surface block, the
+ * command registry in `std`, the frame order in the frame block), and no page
+ * named them together. This module gathers them, so a host imports one entry
+ * and never a widget package.
+ *
+ * **Why a façade and not a seam.** A seam is the editor asking the host for
+ * something (show a panel, open a document); its absence needs a degraded
+ * behaviour and a row in the seams table. Here the direction is the other way:
+ * the host calls the editor, and nothing degrades — a host that draws no panel
+ * simply calls nothing. So: plain named functions over an `std`, no class, no
+ * object holding state, no registration. The library's own panels and a
+ * host's call the same functions and the same commands, which is what keeps
+ * their behaviour the same; every WRITE goes through a core command run by
+ * `runCommand` (`canvas.frame.reorder`, `canvas.element.reorder`, …), so the
+ * read-only refusal, the no-op check, the single undo step and the telemetry
+ * happen once whoever draws the pixels.
+ *
+ * **No Lit type is named here.** `lit` is only a dev dependency of
+ * `@labre/affine`, and a host that draws its panel in React must be able to
+ * type its calls without it (`host-panels-signature.unit.spec.ts` reads this
+ * file). `getCommandIcon` still returns what the icon tables hold; a host
+ * renders it with Lit's `render` or uses its own icons.
+ *
+ * **This module only widens.** A function, a parameter or a return type a
+ * host calls keeps its 0.46 shape in every minor: a new parameter is optional,
+ * a return never gains `null` (`host-panels-signature.unit.spec.ts`, which
+ * `yarn build` typechecks; docs/lessons.md 33). A verb a host panel needs and
+ * cannot find here is a gap in this module, not a reason to import a widget
+ * package.
+ *
+ * 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 { 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';
+/**
+ * The document's frames in presentation order, first slide first — the order
+ * `canvas.frame.reorder` writes and the presentation walks. Works in page mode
+ * too: the frame manager is registered with the frame block in both.
+ */
+export declare function frameList(std: BlockStdScope): FrameBlockModel[];
+/**
+ * Select `ids` on the canvas, the way a click on a panel row does: the
+ * selection replaces the current one and nothing enters text editing. Edgeless
+ * only — page mode shows no canvas selection.
+ */
+export declare function selectModels(std: BlockStdScope, ids: readonly string[]): void;
+/**
+ * Move the viewport, smoothly, so model `id` fills it within `padding`
+ * (top, right, bottom, left, in screen pixels) — the frame panel's "fit to
+ * frame". `false` when no canvas model has that id; nothing moves then.
+ *
+ * It never switches the editor's mode: the host knows which mode it shows, and
+ * a host in page mode switches first (`DocModeProvider`).
+ */
+export declare function fitToModel(std: BlockStdScope, id: string, padding?: [number, number, number, number]): boolean;
+/**
+ * The live preview of a frame the library's own frame panel draws on each
+ * card: a read-only mini editor clipped to the frame's bounds, repainted as
+ * the frame's content changes. Not a picture — a host that wants a static
+ * thumbnail renders one through `ExportManager` instead.
+ *
+ * Returns the element ready to be appended; `width` and `height` are the
+ * preview box in CSS pixels (the panel's card is 280 × 166), `fillScreen`
+ * covers the box instead of containing the frame. One mini editor per
+ * preview: mount only the cards on screen. The element is defined by the
+ * frame panel's view extension, so it renders nothing in an assembly where the
+ * `frame` flag is off (ADR 0009) — the same assembly where there is no frame
+ * to preview.
+ */
+export declare function createFramePreview(std: BlockStdScope, frame: FrameBlockModel, options?: {
+    width?: number;
+    height?: number;
+    fillScreen?: boolean;
+}): FramePreview;

package/dist/host-panels.js

@@ -0,0 +1,111 @@
+import { EdgelessFrameManagerIdentifier } from './_pkgs/affine-block-frame/index.js';
+import { AFFINE_FRAME_PREVIEW, } from './_pkgs/affine-fragment-frame-panel/index.js';
+import { GfxControllerIdentifier } from './_pkgs/std/gfx/index.js';
+/**
+ * `@labre/affine/host-panels` — the verbs a host's own panel calls (ADR 0034
+ * §4, docs/integrate/08-host-panels.md).
+ *
+ * A host that draws its own artefact catalogue, selection pane or slide list
+ * needs a handful of editor verbs: list a framework's artefacts, arm one, run
+ * a command, read the canvas stack, list the frames in presentation order,
+ * select a model, frame it in the viewport. They existed before this module,
+ * spread over four packages and three levels of abstraction (`armArtefact` in
+ * the edgeless toolbar widget, `selectionPaneTree` in the surface block, the
+ * command registry in `std`, the frame order in the frame block), and no page
+ * named them together. This module gathers them, so a host imports one entry
+ * and never a widget package.
+ *
+ * **Why a façade and not a seam.** A seam is the editor asking the host for
+ * something (show a panel, open a document); its absence needs a degraded
+ * behaviour and a row in the seams table. Here the direction is the other way:
+ * the host calls the editor, and nothing degrades — a host that draws no panel
+ * simply calls nothing. So: plain named functions over an `std`, no class, no
+ * object holding state, no registration. The library's own panels and a
+ * host's call the same functions and the same commands, which is what keeps
+ * their behaviour the same; every WRITE goes through a core command run by
+ * `runCommand` (`canvas.frame.reorder`, `canvas.element.reorder`, …), so the
+ * read-only refusal, the no-op check, the single undo step and the telemetry
+ * happen once whoever draws the pixels.
+ *
+ * **No Lit type is named here.** `lit` is only a dev dependency of
+ * `@labre/affine`, and a host that draws its panel in React must be able to
+ * type its calls without it (`host-panels-signature.unit.spec.ts` reads this
+ * file). `getCommandIcon` still returns what the icon tables hold; a host
+ * renders it with Lit's `render` or uses its own icons.
+ *
+ * **This module only widens.** A function, a parameter or a return type a
+ * host calls keeps its 0.46 shape in every minor: a new parameter is optional,
+ * a return never gains `null` (`host-panels-signature.unit.spec.ts`, which
+ * `yarn build` typechecks; docs/lessons.md 33). A verb a host panel needs and
+ * cannot find here is a gap in this module, not a reason to import a widget
+ * package.
+ *
+ * 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 { 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 document's frames in presentation order, first slide first — the order
+ * `canvas.frame.reorder` writes and the presentation walks. Works in page mode
+ * too: the frame manager is registered with the frame block in both.
+ */
+export function frameList(std) {
+    return std.get(EdgelessFrameManagerIdentifier).frames;
+}
+/**
+ * Select `ids` on the canvas, the way a click on a panel row does: the
+ * selection replaces the current one and nothing enters text editing. Edgeless
+ * only — page mode shows no canvas selection.
+ */
+export function selectModels(std, ids) {
+    std.get(GfxControllerIdentifier).selection.set({
+        elements: [...ids],
+        editing: false,
+    });
+}
+/**
+ * Move the viewport, smoothly, so model `id` fills it within `padding`
+ * (top, right, bottom, left, in screen pixels) — the frame panel's "fit to
+ * frame". `false` when no canvas model has that id; nothing moves then.
+ *
+ * It never switches the editor's mode: the host knows which mode it shows, and
+ * a host in page mode switches first (`DocModeProvider`).
+ */
+export function fitToModel(std, id, padding = [0, 0, 0, 0]) {
+    const gfx = std.get(GfxControllerIdentifier);
+    const model = gfx.getElementById(id);
+    if (!model?.elementBound)
+        return false;
+    gfx.viewport.setViewportByBound(model.elementBound, padding, true);
+    return true;
+}
+/**
+ * The live preview of a frame the library's own frame panel draws on each
+ * card: a read-only mini editor clipped to the frame's bounds, repainted as
+ * the frame's content changes. Not a picture — a host that wants a static
+ * thumbnail renders one through `ExportManager` instead.
+ *
+ * Returns the element ready to be appended; `width` and `height` are the
+ * preview box in CSS pixels (the panel's card is 280 × 166), `fillScreen`
+ * covers the box instead of containing the frame. One mini editor per
+ * preview: mount only the cards on screen. The element is defined by the
+ * frame panel's view extension, so it renders nothing in an assembly where the
+ * `frame` flag is off (ADR 0009) — the same assembly where there is no frame
+ * to preview.
+ */
+export function createFramePreview(std, frame, options = {}) {
+    const preview = document.createElement(AFFINE_FRAME_PREVIEW);
+    preview.std = std;
+    preview.frame = frame;
+    if (options.width !== undefined)
+        preview.surfaceWidth = options.width;
+    if (options.height !== undefined)
+        preview.surfaceHeight = options.height;
+    if (options.fillScreen !== undefined)
+        preview.fillScreen = options.fillScreen;
+    return preview;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-core",
   "description": "Labre editor — the full BlockSuite-derived editor as one package.",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",
@@ -818,6 +818,10 @@
       "types": "./dist/commands.d.ts",
       "import": "./dist/commands.js"
     },
+    "./host-panels": {
+      "types": "./dist/host-panels.d.ts",
+      "import": "./dist/host-panels.js"
+    },
     "./frameworks": {
       "types": "./dist/frameworks.d.ts",
       "import": "./dist/frameworks.js"

package/dist/_pkgs/affine-fragment-frame-panel/utils/drag.d.ts

@@ -1,27 +0,0 @@
-import type { FrameBlockModel } from '../../affine-model/index.js';
-import type { FramePanelBody } from '../body/frame-panel-body.js';
-import { FrameCard } from '../card/frame-card.js';
-/**
- * start drag frame cards
- * @param frames frames to drag
- */
-export declare function startDragging(frames: {
-    frame: FrameBlockModel;
-    element: FrameCard;
-    cardIndex: number;
-    frameIndex: string;
-}[], options: {
-    width: number;
-    onDragEnd?: (insertIndex?: number) => void;
-    onDragMove?: (insertIdx?: number, indicatorTranslateY?: number) => void;
-    framePanelBody: HTMLElement;
-    frameListContainer: HTMLElement;
-    frameElementHeight: number;
-    document: Document;
-    domHost: Document | HTMLElement;
-    container: FramePanelBody;
-    start: {
-        x: number;
-        y: number;
-    };
-}): void;

package/dist/_pkgs/affine-fragment-frame-panel/utils/drag.js

@@ -1,96 +0,0 @@
-import { on, once } from '../../affine-shared/utils/index.js';
-import { FrameCard } from '../card/frame-card.js';
-/**
- * start drag frame cards
- * @param frames frames to drag
- */
-export function startDragging(frames, options) {
-    const { document, domHost, container, onDragMove, onDragEnd, frameElementHeight, framePanelBody, frameListContainer, start, } = options;
-    const cardElements = frames
-        .slice(frames.length - 2, frames.length)
-        .map((frame, idx, arr) => {
-        const el = new FrameCard();
-        el.frame = frame.frame;
-        el.cardIndex = frame.cardIndex;
-        el.frameIndex = frame.frameIndex;
-        el.status = 'dragging';
-        el.stackOrder = arr.length - 1 - idx;
-        el.pos = start;
-        el.width = options.width;
-        el.std = container.editorHost.std;
-        if (frames.length > 1 && el.stackOrder === 0)
-            el.draggingCardNumber = frames.length;
-        return el;
-    });
-    const maskElement = createMaskElement(document);
-    const listContainerRect = framePanelBody.getBoundingClientRect();
-    const children = Array.from(frameListContainer.children);
-    const computedStyle = getComputedStyle(frameListContainer);
-    const frameListContainerGap = parseInt(computedStyle.getPropertyValue('gap')) ?? 16;
-    let idx;
-    let indicatorTranslateY;
-    container.renderRoot.append(maskElement);
-    container.renderRoot.append(...cardElements);
-    const insideListContainer = (e) => {
-        return (e.clientX >= listContainerRect.left &&
-            e.clientX <= listContainerRect.right &&
-            e.clientY >= listContainerRect.top &&
-            e.clientY <= listContainerRect.bottom);
-    };
-    const disposeMove = on(container, 'mousemove', e => {
-        cardElements.forEach(el => {
-            el.pos = {
-                x: e.clientX,
-                y: e.clientY,
-            };
-        });
-        if (!insideListContainer(e)) {
-            idx = undefined;
-            onDragMove?.(idx, 0);
-            return;
-        }
-        idx = 0;
-        for (const card of children) {
-            if (!card.frame)
-                break;
-            const topBoundary = listContainerRect.top +
-                card.offsetTop -
-                framePanelBody.scrollTop -
-                frameListContainerGap / 2;
-            const midBoundary = topBoundary + card.offsetHeight / 2;
-            const bottomBoundary = topBoundary + card.offsetHeight + frameListContainerGap;
-            if (e.clientY >= topBoundary && e.clientY <= bottomBoundary) {
-                idx = e.clientY > midBoundary ? idx + 1 : idx;
-                indicatorTranslateY =
-                    idx * (frameElementHeight + frameListContainerGap) -
-                        frameListContainerGap / 2;
-                onDragMove?.(idx, indicatorTranslateY);
-                return;
-            }
-            ++idx;
-        }
-        onDragMove?.(idx);
-    });
-    let ended = false;
-    const dragEnd = () => {
-        if (ended)
-            return;
-        ended = true;
-        cardElements.forEach(child => child.remove());
-        maskElement.remove();
-        disposeMove();
-        onDragEnd?.(idx);
-    };
-    once(domHost, 'mouseup', dragEnd);
-}
-function createMaskElement(doc) {
-    const mask = doc.createElement('div');
-    mask.style.height = '100vh';
-    mask.style.width = '100vw';
-    mask.style.position = 'fixed';
-    mask.style.left = '0';
-    mask.style.top = '0';
-    mask.style.zIndex = 'calc(var(--affine-z-index-popover, 0) + 3)';
-    mask.style.cursor = 'grabbing';
-    return mask;
-}

package/dist/_pkgs/affine-shared/services/sidebar-service.d.ts

@@ -1,8 +0,0 @@
-import type { ExtensionType } from '../../store/index.js';
-export interface SidebarService {
-    open: (tabId?: string) => void;
-    close: () => void;
-    getTabIds: () => string[];
-}
-export declare const SidebarExtensionIdentifier: import("../../global/di/types.js").ServiceIdentifier<SidebarService> & (<U extends SidebarService = SidebarService>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
-export declare const SidebarExtension: (service: SidebarService) => ExtensionType;

package/dist/_pkgs/affine-shared/services/sidebar-service.js

@@ -1,7 +0,0 @@
-import { createIdentifier } from '../../global/di/index.js';
-export const SidebarExtensionIdentifier = createIdentifier('AffineSidebarExtension');
-export const SidebarExtension = (service) => ({
-    setup: di => {
-        di.addImpl(SidebarExtensionIdentifier, () => service);
-    },
-});