@formicoidea/labre-core 0.43.1 → 0.46.0

package/dist/_pkgs/affine-block-surface/extensions/selection-pane/commands.js

@@ -0,0 +1,355 @@
+import { CanvasLocalVisibility, SelectionPaneProvider, TelemetryProvider, } from '../../../affine-shared/services/index.js';
+import { GfxControllerIdentifier } from '../../../std/gfx/index.js';
+import { z } from 'zod';
+import { renamePaneFrame, renamePaneGroup, reorderPaneElements, setPaneElementsHiddenForEveryone, setPaneElementsLocked, } from './actions.js';
+import { setUserLayersHiddenForEveryone } from '../user-layers/actions.js';
+import { SelectionPaneModel } from './tree.js';
+/**
+ * The selection pane's commands (ADR 0031, stage 2), `owner: 'core'`: the pane
+ * belongs to no framework, and `'core'` owners are exempt from the id-prefix
+ * rule (ADR 0008).
+ *
+ * The pane's own rows invoke the parameterised ones through `runCommand`, and
+ * so does a host's pane: the read-only refusal lives in the action, once.
+ */
+/** How the user reached the pane, as `SelectionPaneOpened` reports it. */
+function openedFrom(invocation) {
+    if (invocation.surface === 'shortcut')
+        return 'shortcut';
+    if (invocation.source === 'toolbar:general')
+        return 'toolbar';
+    // The palette and the agent both invoke the command by name.
+    return 'palette';
+}
+const paneService = (std) => std.getOptional(SelectionPaneProvider);
+/**
+ * Open the pane, or put the library's own panel away when it is the one on
+ * screen.
+ *
+ * Toggling needs a state the two-verb seam does not carry, so it reads the
+ * library panel's own (`SelectionPaneModel.open$`). A host that replaced the
+ * panel keeps its open state to itself: for it, the toggle always opens, and
+ * closing is the host's own control.
+ *
+ * Emits `SelectionPaneOpened` from its body, and only when it opens — see the
+ * telemetry README for why this command self-emits like `doc.copyLink`.
+ *
+ * Opening writes nothing, so no read-only guard: the pane is how a reader finds
+ * what is on a canvas they cannot edit.
+ */
+const toggleSelectionPane = {
+    id: 'canvas.selectionPane.toggle',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.selection-pane.toggle',
+    labelFallback: 'Selection pane',
+    descriptionKey: 'com.labre.command.canvas.selection-pane.toggle.description',
+    descriptionFallback: 'List the elements of the canvas by stacking order, to select, lock, rename or reorder them.',
+    keywords: ['layers', 'objects', 'z-order', 'stack'],
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    // `null` from `SelectionPaneExtension(null)` switches the pane off; the
+    // command then disappears rather than opening nothing.
+    when: std => !!paneService(std),
+    run: (std, invocation) => {
+        const service = paneService(std);
+        if (!service)
+            return;
+        const model = std.getOptional(SelectionPaneModel);
+        if (model?.open$.peek()) {
+            service.close();
+            return;
+        }
+        service.open();
+        std.getOptional(TelemetryProvider)?.track('SelectionPaneOpened', {
+            page: 'whiteboard editor',
+            source: openedFrom(invocation),
+        });
+    },
+};
+/*
+ * "An `id` or a non-empty `ids`" is checked in `run`, not with a zod `refine`:
+ * a refined schema is a `ZodEffects`, which `describeCommandParams` cannot
+ * project, so the agent manifest would lose the whole parameter contract.
+ */
+export const reorderElementParams = z.object({
+    // The element or gfx block to move.
+    id: z.string().min(1).optional(),
+    // Several models of ONE stack, moved as a block in their current relative
+    // order (the selection pane's multi-row drag, ADR 0034). Added beside `id`,
+    // which stays: a caller passing `id` alone is unchanged.
+    ids: z.array(z.string().min(1)).optional(),
+    // The model they land directly ABOVE, stacked with them; `null` puts them
+    // at the bottom of their stack.
+    above: z.string().min(1).nullable(),
+});
+const reorderElement = {
+    id: 'canvas.element.reorder',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.element.reorder',
+    labelFallback: 'Move in the stack',
+    descriptionKey: 'com.labre.command.canvas.element.reorder.description',
+    descriptionFallback: 'Place an element directly above another one in the stacking order.',
+    // Agent only: without an explicit target there is nothing to say where.
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: reorderElementParams,
+    run: (std, _invocation, params) => {
+        const parsed = reorderElementParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.element.reorder: invalid params', parsed.error);
+            return;
+        }
+        const { id, ids = [], above } = parsed.data;
+        const moving = id === undefined ? ids : [id, ...ids];
+        if (!moving.length) {
+            console.error('canvas.element.reorder: needs an id or ids');
+            return;
+        }
+        reorderPaneElements(std, moving, above);
+    },
+};
+export const lockElementsParams = z.object({
+    /**
+     * The models to act on. Omitted: the current canvas selection. Each one is
+     * locked ON ITS OWN — never wrapped into a group.
+     */
+    ids: z.array(z.string()).optional(),
+});
+function lockTargets(std, params) {
+    const parsed = lockElementsParams.safeParse(params ?? {});
+    if (!parsed.success)
+        return [];
+    return (parsed.data.ids ?? std.get(GfxControllerIdentifier).selection.selectedIds);
+}
+function lockCommand(locked) {
+    const verb = locked ? 'lock' : 'unlock';
+    return {
+        id: `canvas.element.${verb}`,
+        owner: 'core',
+        kind: 'action',
+        labelKey: `com.labre.command.canvas.element.${verb}`,
+        labelFallback: locked ? 'Lock each element' : 'Unlock each element',
+        descriptionKey: `com.labre.command.canvas.element.${verb}.description`,
+        descriptionFallback: locked
+            ? 'Lock every selected element on its own, without grouping them.'
+            : 'Unlock every selected element on its own.',
+        surfaces: ['palette', 'agent'],
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+        availability: 'editable',
+        when: std => std.get(GfxControllerIdentifier).selection.selectedIds.length > 0,
+        params: lockElementsParams,
+        run: (std, _invocation, params) => {
+            setPaneElementsLocked(std, lockTargets(std, params), locked);
+        },
+    };
+}
+export const renameGroupParams = z.object({
+    id: z.string().min(1),
+    title: z.string(),
+});
+const renameGroup = {
+    id: 'canvas.group.rename',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.group.rename',
+    labelFallback: 'Rename group',
+    descriptionKey: 'com.labre.command.canvas.group.rename.description',
+    descriptionFallback: 'Give a group a new title.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: renameGroupParams,
+    run: (std, _invocation, params) => {
+        const parsed = renameGroupParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.group.rename: invalid params', parsed.error);
+            return;
+        }
+        renamePaneGroup(std, parsed.data.id, parsed.data.title);
+    },
+};
+/**
+ * A frame's row is renamed in place like a group's (ADR 0031, amendments:
+ * frames are rows). Its own command rather than `canvas.group.rename` widened:
+ * the agent reads a command's wording, and a frame is not a group.
+ */
+const renameFrame = {
+    id: 'canvas.frame.rename',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.frame.rename',
+    labelFallback: 'Rename frame',
+    descriptionKey: 'com.labre.command.canvas.frame.rename.description',
+    descriptionFallback: 'Give a frame a new title.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: renameGroupParams,
+    run: (std, _invocation, params) => {
+        const parsed = renameGroupParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.frame.rename: invalid params', parsed.error);
+            return;
+        }
+        renamePaneFrame(std, parsed.data.id, parsed.data.title);
+    },
+};
+export const hideLocalParams = z.object({
+    /** The models to act on. Omitted: the current canvas selection. */
+    ids: z.array(z.string()).optional(),
+    /**
+     * Whole user layers to act on instead (ADR 0031 stage 7). When given,
+     * `ids` and the selection are ignored.
+     */
+    layerIds: z.array(z.string()).optional(),
+    /** `false` shows them again. Omitted: hide. */
+    hidden: z.boolean().optional(),
+});
+function reportVisibility(std, hidden, count, scope = 'local', target = 'element') {
+    if (!count)
+        return;
+    std.getOptional(TelemetryProvider)?.track('CanvasVisibilityChanged', {
+        page: 'whiteboard editor',
+        target,
+        scope,
+        hidden,
+        count,
+    });
+}
+/**
+ * Hide elements for THIS viewer only (ADR 0031 §8) — or, with
+ * `hidden: false`, show them again; the pane's eye is both.
+ *
+ * Nothing is written to the document, so there is no read-only guard: a
+ * reader may hide what is in their way. Self-emits `CanvasVisibilityChanged`
+ * with the number of elements the gesture actually changed.
+ */
+const hideLocal = {
+    id: 'canvas.visibility.hideLocal',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.visibility.hide-local',
+    labelFallback: 'Hide for me',
+    descriptionKey: 'com.labre.command.canvas.visibility.hide-local.description',
+    descriptionFallback: 'Hide the selected elements on your screen only. Nothing changes for anyone else.',
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'selection',
+    when: std => !!std.getOptional(CanvasLocalVisibility),
+    params: hideLocalParams,
+    run: (std, _invocation, params) => {
+        const visibility = std.getOptional(CanvasLocalVisibility);
+        const parsed = hideLocalParams.safeParse(params ?? {});
+        if (!visibility || !parsed.success)
+            return;
+        if (parsed.data.layerIds) {
+            const hidden = parsed.data.hidden ?? true;
+            const layers = parsed.data.layerIds;
+            const count = hidden
+                ? visibility.hideLayers(layers)
+                : visibility.showLayers(layers);
+            reportVisibility(std, hidden, count, 'local', 'layer');
+            return;
+        }
+        const ids = parsed.data.ids ?? std.get(GfxControllerIdentifier).selection.selectedIds;
+        const hidden = parsed.data.hidden ?? true;
+        const count = hidden ? visibility.hide(ids) : visibility.show(ids);
+        reportVisibility(std, hidden, count);
+    },
+};
+export const hideForEveryoneParams = z.object({
+    /** The models to act on. Omitted: the current canvas selection. */
+    ids: z.array(z.string()).optional(),
+    /**
+     * Whole user layers to act on instead: `hidden: true` on each record, one
+     * write per layer, never one per member (ADR 0031 §7).
+     */
+    layerIds: z.array(z.string()).optional(),
+    /** `false` shows them again, for everyone. Omitted: hide. */
+    hidden: z.boolean().optional(),
+});
+/**
+ * Hide elements for EVERYONE (ADR 0031 §7) — or, with `hidden: false`, show
+ * them again for everyone. Written to the document and synced: every viewer,
+ * every peer, stops painting and picking them, while rules, legends and
+ * semantic exports keep counting them (§9). Refused on a read-only document
+ * (`availability`, and again in the action). Self-emits
+ * `CanvasVisibilityChanged` with `scope: 'everyone'` and the count actually
+ * written.
+ */
+const hideForEveryone = {
+    id: 'canvas.visibility.hideForEveryone',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.visibility.hide-for-everyone',
+    labelFallback: 'Hide for everyone',
+    descriptionKey: 'com.labre.command.canvas.visibility.hide-for-everyone.description',
+    descriptionFallback: 'Hide the selected elements for everyone who opens this document. They stay in the document and in the selection pane.',
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    when: std => std.get(GfxControllerIdentifier).selection.selectedIds.length > 0,
+    params: hideForEveryoneParams,
+    run: (std, _invocation, params) => {
+        const parsed = hideForEveryoneParams.safeParse(params ?? {});
+        if (!parsed.success)
+            return;
+        if (parsed.data.layerIds) {
+            const hidden = parsed.data.hidden ?? true;
+            const count = setUserLayersHiddenForEveryone(std, parsed.data.layerIds, hidden);
+            reportVisibility(std, hidden, count, 'everyone', 'layer');
+            return;
+        }
+        const ids = parsed.data.ids ?? std.get(GfxControllerIdentifier).selection.selectedIds;
+        const hidden = parsed.data.hidden ?? true;
+        const count = setPaneElementsHiddenForEveryone(std, ids, hidden);
+        reportVisibility(std, hidden, count, 'everyone');
+    },
+};
+/**
+ * Show everything this viewer hid. Stays in the palette whatever the pane
+ * seam says: with `SelectionPaneExtension(null)` it is the one way back.
+ */
+const showAll = {
+    id: 'canvas.visibility.showAll',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.visibility.show-all',
+    labelFallback: 'Show hidden elements',
+    descriptionKey: 'com.labre.command.canvas.visibility.show-all.description',
+    descriptionFallback: 'Show again every element and layer you hid on your screen.',
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    when: std => {
+        const visibility = std.getOptional(CanvasLocalVisibility);
+        return ((visibility?.hiddenIds$.peek().size ?? 0) > 0 ||
+            (visibility?.hiddenLayerIds$.peek().size ?? 0) > 0);
+    },
+    run: std => {
+        const visibility = std.getOptional(CanvasLocalVisibility);
+        reportVisibility(std, false, visibility?.showAll() ?? 0);
+        reportVisibility(std, false, visibility?.showAllLayers() ?? 0, 'local', 'layer');
+    },
+};
+export const selectionPaneCommands = [
+    toggleSelectionPane,
+    reorderElement,
+    lockCommand(true),
+    lockCommand(false),
+    renameGroup,
+    renameFrame,
+    hideLocal,
+    hideForEveryone,
+    showAll,
+];

package/dist/_pkgs/affine-block-surface/extensions/selection-pane/index.d.ts

@@ -0,0 +1,3 @@
+export { filterSelectionPaneTree, renamePaneFrame, renamePaneGroup, reorderPaneElement, reorderPaneElements, type SelectionPaneFilterTarget, selectionPaneFilterMembers, selectionPaneFilterTargets, setPaneElementsHiddenForEveryone, setPaneElementsLocked, } from './actions.js';
+export { type HideForEveryoneParams, hideForEveryoneParams, type HideLocalParams, hideLocalParams, type LockElementsParams, lockElementsParams, type RenameGroupParams, renameGroupParams, type ReorderElementParams, reorderElementParams, selectionPaneCommands, } from './commands.js';
+export { buildSelectionPaneTree, DEFAULT_LAYER_ID, paneContainerOf, paneLayersOf, type SelectionPaneLayers, type SelectionPaneNode, SelectionPaneModel, selectionPaneTree, } from './tree.js';

package/dist/_pkgs/affine-block-surface/extensions/selection-pane/index.js

@@ -0,0 +1,3 @@
+export { filterSelectionPaneTree, renamePaneFrame, renamePaneGroup, reorderPaneElement, reorderPaneElements, selectionPaneFilterMembers, selectionPaneFilterTargets, setPaneElementsHiddenForEveryone, setPaneElementsLocked, } from './actions.js';
+export { hideForEveryoneParams, hideLocalParams, lockElementsParams, renameGroupParams, reorderElementParams, selectionPaneCommands, } from './commands.js';
+export { buildSelectionPaneTree, DEFAULT_LAYER_ID, paneContainerOf, paneLayersOf, SelectionPaneModel, selectionPaneTree, } from './tree.js';

package/dist/_pkgs/affine-block-surface/extensions/selection-pane/tree.d.ts

@@ -0,0 +1,137 @@
+import { type BlockStdScope, LifeCycleWatcher } from '../../../std/index.js';
+import { GfxGroupLikeElementModel, type GfxModel, DEFAULT_LAYER_ID, type SurfaceBlockModel } from '../../../std/gfx/index.js';
+import { type ReadonlySignal } from '@preact/signals-core';
+/** The default layer's reserved id (ADR 0031 §2), re-exported from std. */
+export { DEFAULT_LAYER_ID };
+/**
+ * One row of the selection pane, as the HEADLESS API hands it out (ADR 0031
+ * §12): ids and states only, never a wording. Whoever draws the row reads the
+ * label off the element at render time — its own text, its label sibling, its
+ * role's wording — so a rename on the canvas never has to invalidate this
+ * tree, and no element text ever crosses the seam in a payload a host might
+ * log.
+ */
+export interface SelectionPaneNode {
+    id: string;
+    /**
+     * `'layer'` is a user layer's row (ADR 0031 §2). The top-level rows are
+     * always the layers, top first, and every element row sits under its
+     * effective layer. A surface with no `layers` has one, the default layer
+     * ({@link DEFAULT_LAYER_ID}), shown although it has no record yet (ADR 0031
+     * amendments); its name is `userLayerName`'s, the first-layer seed.
+     */
+    kind: 'element' | 'block' | 'layer';
+    /** The element `type` (`shape`, `group`…) or the block flavour. */
+    type: string;
+    /** The element's role, when it carries one. Blocks carry none. */
+    role?: string;
+    /** The group-like ELEMENT (group, mindmap) this row is listed under. */
+    groupId?: string;
+    /**
+     * The effective layer (ADR 0031 §4): the outermost group's, a dangling id
+     * read as {@link DEFAULT_LAYER_ID}. A layer row carries its own id.
+     */
+    layerId: string;
+    /** Locked by itself — what the row's lock toggle shows and flips. */
+    locked: boolean;
+    /**
+     * Hidden for this viewer only (`CanvasLocalVisibility`): still listed, still
+     * selectable from the pane, just not painted or picked on the canvas.
+     */
+    hiddenLocal: boolean;
+    /**
+     * Hidden for everyone (the stored `hiddenForEveryone`, ADR 0031 §7): listed
+     * and selectable like a local hide, but no viewer paints or picks it.
+     */
+    hiddenForEveryone: boolean;
+    /** Present on a group, a mindmap or a layer: its members, top first. */
+    children?: SelectionPaneNode[];
+}
+/** The user layers a tree is built against (ADR 0031 §4). */
+export interface SelectionPaneLayers {
+    /** Every layer id, TOP first. */
+    readonly order: readonly string[];
+    /** Each id's rank key, as `compare` reads it. */
+    readonly ranks: ReadonlyMap<string, string>;
+    effectiveLayerOf(model: GfxModel): string;
+    /** The layers this viewer hid (stage 7). */
+    readonly hiddenLocally?: ReadonlySet<string>;
+    /** The layers whose record says `hidden: true` (stage 7). */
+    readonly hiddenForEveryone?: ReadonlySet<string>;
+}
+/**
+ * The group-like ELEMENT a model is listed under, or `null` for a top-level
+ * row.
+ *
+ * Frames are deliberately not containers here, although they are
+ * group-compatible for z-order: a frame is a slide, and the pane filters BY
+ * frame rather than nesting under one — exactly the line ADR 0031 §4 draws for
+ * layers. `group` walks the model's surface, which throws on a model that is
+ * not attached to one; such a model is simply a top-level row.
+ */
+export declare function paneContainerOf(model: GfxModel): GfxGroupLikeElementModel | null;
+/**
+ * The pane's rows, built from the canvas' models: one pass to bucket every
+ * model under its container, one sort per sibling list, top first.
+ *
+ * Pure, so the budget test can time exactly what a live pane pays. The order
+ * is the canvas' own comparator (`compareLayer`) reversed — the paint order,
+ * never a second opinion of it — with one shortcut that is exact: two models
+ * under the same group-like ancestor are ordered by `compareLayer` on their
+ * `index` alone (its ancestor walk finds no difference and falls through to
+ * `compareIndex`). So that case reads two cached strings instead of walking
+ * two ancestor chains per comparison, and only models stacked under different
+ * ancestors (a frame's members beside loose elements) walk their chains, read
+ * once per model rather than once per comparison.
+ *
+ * The top-level rows are the layers; with no `layers` given, the default
+ * layer alone, unrecorded — what a canvas without layers shows.
+ */
+export declare function buildSelectionPaneTree(models: readonly GfxModel[], hiddenLocally?: ReadonlySet<string>, layers?: SelectionPaneLayers): SelectionPaneNode[];
+/**
+ * The surface's user layers as the tree builder takes them; while there is no
+ * record, the default layer alone, unrecorded (nothing is written to show it).
+ * Reads `layers$`, so a `computed` calling it re-derives on a create, a
+ * rename, a reorder — local or a peer's.
+ */
+export declare function paneLayersOf(surface: SurfaceBlockModel, hiddenLocally?: ReadonlySet<string>): SelectionPaneLayers;
+/**
+ * The live tree behind {@link selectionPaneTree}, one per editor.
+ *
+ * The tree is a `computed` over a revision counter, bumped by the few events
+ * that can change a row (an element or block added or removed, a reorder, a
+ * regroup, a lock) — never by geometry. A `computed` is lazy, so an editor
+ * whose pane is closed and whose host never reads the tree pays the counter
+ * bump and nothing else; an open pane pays one rebuild per relevant change,
+ * not one per frame.
+ *
+ * It also holds whether the LIBRARY's own panel is open (`open$`), which is
+ * what the toggle command reads. A host that replaced the panel through
+ * `SelectionPaneExtension` owns its own open state; `open$` then stays false
+ * and the toggle always opens.
+ */
+export declare class SelectionPaneModel extends LifeCycleWatcher {
+    static key: string;
+    private readonly _revision$;
+    private _disposeSurfaceEffect;
+    private _subscriptions;
+    /** Whether the library's own panel is on screen. Written by that panel. */
+    readonly open$: import("@preact/signals-core").Signal<boolean>;
+    readonly tree$: ReadonlySignal<SelectionPaneNode[]>;
+    /** Force a rebuild; for a change no subscribed event reports. */
+    invalidate(): void;
+    mounted(): void;
+    private _surfaceSubscriptions;
+    private _watchSurface;
+    unmounted(): void;
+}
+/**
+ * The headless data API of the selection pane (ADR 0031 §12): a signal of
+ * rows, z-order, top first, ids only.
+ *
+ * What a host's own pane renders from, and what the library's panel renders
+ * from — one tree, so the two cannot disagree about the order of a canvas.
+ * Edgeless editors only: the model is registered by the surface's edgeless
+ * view extension.
+ */
+export declare function selectionPaneTree(std: BlockStdScope): ReadonlySignal<SelectionPaneNode[]>;