@formicoidea/labre-core 0.32.0 → 0.34.1

package/dist/_pkgs/affine-shared/services/command-usage-service.js

@@ -0,0 +1,109 @@
+import { CommandUsageIdentifier, } from '../../std/index.js';
+/**
+ * Where `createLocalCommandUsageStore` persists. Namespaced like the rest of
+ * Labre's browser-local state, and versionless on purpose: the shape is two
+ * numbers per command, and a reader that does not recognise an entry drops it.
+ */
+export const COMMAND_USAGE_KEY = 'labre:command-usage';
+/**
+ * Enough for every command of every framework several times over (the registry
+ * holds 76 today), small enough that the JSON stays a few kilobytes. Overflow
+ * evicts the least recently used entry, so the measure a ranking cares about —
+ * what this user reached for lately — is the last thing lost.
+ */
+const MAX_ENTRIES = 200;
+/**
+ * `localStorage` throws outright in a few environments (private mode quotas,
+ * sandboxed frames, some test runners), and a usage measure is never important
+ * enough to take a command down with it — every access is therefore
+ * best-effort. Same rule and same shape as the icon picker's recent store.
+ */
+const storage = () => {
+    try {
+        return globalThis.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+const readUsage = () => {
+    try {
+        const raw = storage()?.getItem(COMMAND_USAGE_KEY);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return {};
+        // Entry by entry: one corrupted record must not discard the whole table.
+        const usage = {};
+        for (const [id, value] of Object.entries(parsed)) {
+            const { c, t } = (value ?? {});
+            if (typeof c === 'number' && typeof t === 'number')
+                usage[id] = { c, t };
+        }
+        return usage;
+    }
+    catch {
+        return {};
+    }
+};
+const writeUsage = (usage) => {
+    try {
+        storage()?.setItem(COMMAND_USAGE_KEY, JSON.stringify(usage));
+    }
+    catch {
+        // best-effort: this session keeps working, the measure just misses a run
+    }
+};
+/** Keeps the {@link MAX_ENTRIES} most recently used entries, nothing else. */
+const evictOverflow = (usage) => {
+    const ids = Object.keys(usage);
+    if (ids.length <= MAX_ENTRIES)
+        return usage;
+    const kept = ids
+        .sort((a, b) => usage[b].t - usage[a].t)
+        .slice(0, MAX_ENTRIES);
+    return Object.fromEntries(kept.map(id => [id, usage[id]]));
+};
+/**
+ * The default {@link CommandUsageStore}: recency and frequency in this
+ * browser's `localStorage`, per command id.
+ *
+ * It measures only. Nothing ranks anything here — PF6's "seven most-recent +
+ * six most-used" sub-menu reads these numbers, and a host that
+ * wants the measure to follow the user across devices replaces the whole store
+ * through {@link CommandUsageExtension}.
+ */
+export function createLocalCommandUsageStore() {
+    return {
+        record: (command) => {
+            const usage = readUsage();
+            const previous = usage[command.id];
+            usage[command.id] = { c: (previous?.c ?? 0) + 1, t: Date.now() };
+            writeUsage(evictOverflow(usage));
+        },
+        statsOf: (commandId) => {
+            const entry = readUsage()[commandId];
+            return entry ? { count: entry.c, lastUsedAt: entry.t } : undefined;
+        },
+    };
+}
+/**
+ * Host override seam: replace the browser-local measure with the host's own.
+ *
+ * This is where a host persists command usage in ITS database — so the ranking
+ * follows the user from laptop to browser to tablet instead of restarting at
+ * zero, which is exactly what a "most-used" sub-menu is judged on. The library
+ * ships the local store as the default (`CommandUsageViewExtension`) and never
+ * requires a host to care.
+ *
+ * Mirrors `EditorSettingExtension` / `KeymapOverrideExtension`: `di.override`,
+ * so a host registering after the library's own extensions always wins.
+ */
+export function CommandUsageExtension(store) {
+    return {
+        setup: di => {
+            di.override(CommandUsageIdentifier, () => store);
+        },
+    };
+}

package/dist/_pkgs/affine-shared/services/comment-service/block-comment-manager.js

@@ -1,6 +1,6 @@
 import { DividerBlockModel } from '../../../affine-model/index.js';
 import { DisposableGroup } from '../../../global/disposable/index.js';
-import { BlockSelection, LifeCycleWatcher, TextSelection, } from '../../../std/index.js';
+import { BlockSelection, LifeCycleWatcher, TextSelection } from '../../../std/index.js';
 import { signal } from '@preact/signals-core';
 import { getSelectedBlocksCommand } from '../../commands/index.js';
 import { ImageSelection } from '../../selection/index.js';

package/dist/_pkgs/affine-shared/services/doc-display-meta-service.js

@@ -1,5 +1,5 @@
 import { createIdentifier } from '../../global/di/index.js';
-import { disposeMember, } from '../../global/disposable/index.js';
+import { disposeMember } from '../../global/disposable/index.js';
 import { AliasIcon, BlockLinkIcon, DeleteIcon, EdgelessIcon, LinkedEdgelessIcon, LinkedPageIcon, PageIcon, } from '@blocksuite/icons/lit';
 import { LifeCycleWatcher, StdIdentifier } from '../../std/index.js';
 import { computed, signal, } from '@preact/signals-core';

package/dist/_pkgs/affine-shared/services/edit-props-store.d.ts

@@ -405,6 +405,17 @@ export declare class EditPropsStore extends LifeCycleWatcher {
     dispose(): void;
     getStorage<T extends StoragePropsKey>(key: T): StorageProps[T] | null;
     recordLastProps(key: LastPropsKey, props: Partial<LastProps[LastPropsKey]>): void;
+    /**
+     * Remember the edgeless viewport of the current editing session, so the next
+     * mount of this doc reopens where the user left it.
+     *
+     * The storage key is shared by every mount of the same doc, so a read-only
+     * mount — an embedded preview, a mini map — must not overwrite what the full
+     * editor remembered: a preview is not an editing session. Readonly is read
+     * here, at save time (the edgeless root block saves on unmount), so a
+     * session that turns read-only before unmounting stops writing too.
+     */
+    saveViewport(viewport: StorageProps['viewport']): void;
     setStorage<T extends StoragePropsKey>(key: T, value: StorageProps[T]): void;
     unmounted(): void;
 }

package/dist/_pkgs/affine-shared/services/edit-props-store.js

@@ -156,6 +156,21 @@ export class EditPropsStore extends LifeCycleWatcher {
         const nextProps = mergeWith(clonedeep(innerProps), { [key]: overrideProps }, customizer);
         this.innerProps$.value = OptionalPropsSchema.parse(nextProps);
     }
+    /**
+     * Remember the edgeless viewport of the current editing session, so the next
+     * mount of this doc reopens where the user left it.
+     *
+     * The storage key is shared by every mount of the same doc, so a read-only
+     * mount — an embedded preview, a mini map — must not overwrite what the full
+     * editor remembered: a preview is not an editing session. Readonly is read
+     * here, at save time (the edgeless root block saves on unmount), so a
+     * session that turns read-only before unmounting stops writing too.
+     */
+    saveViewport(viewport) {
+        if (this.std.store.readonly)
+            return;
+        this.setStorage('viewport', viewport);
+    }
     setStorage(key, value) {
         const oldValue = this.getStorage(key);
         this._getStorage(key).setItem(this._getStorageKey(key), JSON.stringify(value));

package/dist/_pkgs/affine-shared/services/embed-iframe/embed-iframe-config.js

@@ -1,4 +1,4 @@
-import { createIdentifier, } from '../../../global/di/index.js';
+import { createIdentifier } from '../../../global/di/index.js';
 export const EmbedIframeConfigIdentifier = createIdentifier('EmbedIframeConfig');
 export function EmbedIframeConfigExtension(config) {
     const identifier = EmbedIframeConfigIdentifier(config.name);

package/dist/_pkgs/affine-shared/services/index.d.ts

@@ -1,7 +1,9 @@
+export * from './artefact-catalogue-service.js';
 export * from './audit-service.js';
 export * from './auto-clear-selection-service.js';
 export * from './block-meta-service.js';
 export * from './citation-service/index.js';
+export * from './command-usage-service.js';
 export * from './comment-service/index.js';
 export * from './doc-display-meta-service.js';
 export * from './doc-mode-service.js';

package/dist/_pkgs/affine-shared/services/index.js

@@ -1,7 +1,9 @@
+export * from './artefact-catalogue-service.js';
 export * from './audit-service.js';
 export * from './auto-clear-selection-service.js';
 export * from './block-meta-service.js';
 export * from './citation-service/index.js';
+export * from './command-usage-service.js';
 export * from './comment-service/index.js';
 export * from './doc-display-meta-service.js';
 export * from './doc-mode-service.js';

package/dist/_pkgs/affine-shared/services/pivot-materiality-publisher.js

@@ -110,7 +110,8 @@ export class PivotMaterialityPublisher extends LifeCycleWatcher {
         // there is nobody to announce to, so nothing is subscribed and the whole
         // watcher costs one lookup. Binding and qualification keep working: they
         // are element-local writes and never needed the host.
-        if (!this.std.getOptional(PivotPropertiesProvider)?.publishOccurrenceMaterialities) {
+        if (!this.std.getOptional(PivotPropertiesProvider)
+            ?.publishOccurrenceMaterialities) {
             return;
         }
         // The surface is a SIGNAL, not a fact: it can legitimately be null at mount

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

@@ -34,7 +34,7 @@ export type BlockLifecycleEvents = {
  * manipulated ('background:classic', 'node:market', 'connector:link'…).
  */
 export interface FrameworkElementEvent extends TelemetryEvent {
-    framework: 'wardley' | 'edgy' | 'cynefin' | 'bpmn' | 'event-storming' | 'core-domain' | 'context-map';
+    framework: 'wardley' | 'edgy' | 'cynefin' | 'bpmn' | 'c4' | 'event-storming' | 'core-domain' | 'context-map';
     element: string;
 }
 /**
@@ -101,11 +101,83 @@ export interface EdgeDirectionEvent extends TelemetryEvent {
     /** How many edges the single gesture reversed. */
     elementCount: number;
 }
+/**
+ * A framework element became a NEARBY kind of itself — a task said more
+ * precisely as a user task, a start event as a timer start — from its own
+ * contextual toolbar, in one atomic write.
+ *
+ * **A new event name, for the reason {@link FrameworkPromotionEvent} gives.**
+ * ADR 0003 § 2 defines the creation event as UI intent emitted at INSERTION
+ * sites, and a morph inserts nothing: no element is created, destroyed or
+ * swapped, no id changes, no geometry moves and no connector is re-pointed.
+ * Reusing `FrameworkElementAdded` would count a drawn-then-refined artefact
+ * twice and inflate "elements added per framework" permanently.
+ *
+ * Worth measuring on its own, too. The set of reachable kinds is DATA a
+ * framework declares by hand, and the only evidence that a declared family is
+ * the right family is how often it is actually crossed — a pair nobody ever
+ * morphs between did not need to be offered, and a morph users reach for
+ * constantly says the palette led them to the wrong artefact first.
+ *
+ * Ids only: the two roles, and their framework. Never a kind's board content,
+ * never the element ids, never the label anybody typed.
+ */
+export interface FrameworkElementMorphedEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /**
+     * Owning framework — the declaration's own wire key, matching what
+     * `reportCommandTelemetry` sends for that framework's commands.
+     *
+     * OPTIONAL for the same reason it is on {@link FrameworkPromotionEvent}: the
+     * capability is generic, and an element type may one day declare a morph
+     * without belonging to a framework the union names. Absent rather than
+     * `'unknown'`, per the repo convention.
+     */
+    framework?: FrameworkId;
+    /** Role id the selection carried, when they all carried the same one. */
+    fromRole?: string;
+    /** Role id it now carries. */
+    toRole?: string;
+    /** How many elements the single gesture actually rewrote. */
+    elementCount: number;
+}
+/**
+ * A framework VIEW was told which level it draws — a C4 board set to Context,
+ * Container or Component, or put back to a free sketch.
+ *
+ * **A new event name, for the reason {@link FrameworkPromotionEvent} gives.**
+ * Nothing is inserted, nothing is morphed and no level of requirement changes:
+ * the author is stating what the sheet IS, which is a fact none of the existing
+ * events describes. Reusing one of them would corrupt the funnel it belongs to.
+ *
+ * Worth measuring on its own, and for the same reason a profile change is: this
+ * is an OPTIONAL declaration nothing forces, so how often it is made is the only
+ * evidence that asking for it was worth the toolbar entry — and a level users
+ * set and then clear is a rule pack that argued with a drawing they meant.
+ *
+ * Ids only: the framework and the level's own closed vocabulary. Never the
+ * board's title, never what is drawn on it.
+ */
+export interface FrameworkViewLevelEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    /** Owning framework of the view, e.g. `c4`. */
+    framework: FrameworkId;
+    /**
+     * The level now in force, from the framework's own closed vocabulary —
+     * `'none'` when the view has been put back to declaring nothing, which is a
+     * value the dashboard needs as much as the others.
+     */
+    level: string;
+    /** The one it replaces, when the view declared one. */
+    previousLevel?: string;
+}
 export type FrameworkDiagramEvents = {
     FrameworkElementAdded: FrameworkElementEvent;
     FrameworkToolPicked: FrameworkElementEvent;
     FrameworkLegendCreated: FrameworkElementEvent;
     FrameworkElementPromoted: FrameworkPromotionEvent;
+    FrameworkElementMorphed: FrameworkElementMorphedEvent;
+    FrameworkViewLevelSet: FrameworkViewLevelEvent;
     EdgeDirectionInverted: EdgeDirectionEvent;
 };
 /**

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

@@ -1,4 +1,6 @@
+import type { BlockStdScope } from '../../../std/index.js';
 import type { TemplateResult } from 'lit';
+import { type ChromeWording } from '../translation-service/index.js';
 import type { ToolbarContext } from './context.js';
 export declare enum ActionPlacement {
     Start = 0,
@@ -25,9 +27,28 @@ type ActionBase = {
 };
 export type ToolbarAction = ActionBase & {
     label?: string;
+    /**
+     * The same word as {@link label}, said as an i18n key with its English
+     * default — resolved against the host's catalogue when the row is built, and
+     * written over `label` there (`combine`, in the toolbar widget).
+     *
+     * It exists because `label` is a VALUE and the translation seam needs `std`:
+     * a literal here is the one wording a host cannot override, which is what
+     * left a fully translated editor saying "Duplicate" and "Card view" in
+     * English (#183). Declaring the pair keeps a call site one line — the shape a
+     * static label already had — instead of pushing every entry that has words
+     * into a `generate`.
+     *
+     * Wordings are declared once in `@labre/affine-shared/services`
+     * (`CHROME_WORDINGS`), which is also what the key manifest walks — a pair
+     * spelt inline at a call site would be a key no host is ever offered.
+     */
+    labelWording?: ChromeWording;
     showLabel?: boolean;
     icon?: TemplateResult;
     tooltip?: string | TemplateResult;
+    /** {@link labelWording}, for the tooltip. Written over `tooltip`. */
+    tooltipWording?: ChromeWording;
     variant?: 'destructive';
     disabled?: ((cx: ToolbarContext) => boolean) | boolean;
     content?: ((cx: ToolbarContext) => TemplateResult | null) | (TemplateResult | null);
@@ -45,4 +66,15 @@ export type ToolbarActionGroupGenerator = ActionBase & {
 };
 export type ToolbarGenericAction = ToolbarAction | ToolbarActionGenerator | ToolbarActionGroup | ToolbarActionGroupGenerator;
 export type ToolbarActions<T extends ActionBase = ToolbarGenericAction> = T[];
+/**
+ * What an entry SAYS, whether it declared a wording or a literal label.
+ *
+ * The row itself never needs this — `combine` resolves `labelWording` onto
+ * `label` before anything is drawn. It exists for the entries a widget renders
+ * ITSELF out of the raw declarations, which is exactly what the view switcher
+ * does: `content(ctx)` hands its own children to `affine-view-dropdown-menu`,
+ * so those never pass through `combine` and would otherwise be the one control
+ * in the editor left saying "Card view" in English (#183).
+ */
+export declare function toolbarActionLabel(std: BlockStdScope, action: ToolbarAction): string;
 export {};

package/dist/_pkgs/affine-shared/services/toolbar-service/action.js

@@ -1,3 +1,4 @@
+import { translateKey } from '../translation-service/index.js';
 export var ActionPlacement;
 (function (ActionPlacement) {
     ActionPlacement[ActionPlacement["Start"] = 0] = "Start";
@@ -5,3 +6,18 @@ export var ActionPlacement;
     ActionPlacement[ActionPlacement["End"] = 2] = "End";
     ActionPlacement[ActionPlacement["More"] = 4] = "More";
 })(ActionPlacement || (ActionPlacement = {}));
+/**
+ * What an entry SAYS, whether it declared a wording or a literal label.
+ *
+ * The row itself never needs this — `combine` resolves `labelWording` onto
+ * `label` before anything is drawn. It exists for the entries a widget renders
+ * ITSELF out of the raw declarations, which is exactly what the view switcher
+ * does: `content(ctx)` hands its own children to `affine-view-dropdown-menu`,
+ * so those never pass through `combine` and would otherwise be the one control
+ * in the editor left saying "Card view" in English (#183).
+ */
+export function toolbarActionLabel(std, action) {
+    return action.labelWording
+        ? translateKey(std, ...action.labelWording)
+        : (action.label ?? '');
+}

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

@@ -9,11 +9,21 @@ export declare enum Flag {
     Accepting = 64
 }
 export declare class Flags {
+    #private;
     value$: import("@preact/signals-core").Signal<Flag>;
+    get revision(): number;
+    get revision$(): import("@preact/signals-core").Signal<number>;
     get value(): Flag;
     toggle(flag: Flag, activated: boolean): void;
     check(flag: Flag, value?: Flag): boolean;
     contains(flag: number, value?: Flag): boolean;
+    /**
+     * Forces subscribers to re-run while keeping `flag` activated.
+     *
+     * The revision bump is what actually notifies; the batch keeps both writes
+     * in a single notification so the toolbar never sees a transient
+     * {@link Flag.None} frame.
+     */
     refresh(flag: Flag): void;
     reset(): void;
     hide(): void;

package/dist/_pkgs/affine-shared/services/toolbar-service/flags.js

@@ -16,6 +16,30 @@ export var Flag;
 export class Flags {
     constructor() {
         this.value$ = signal(Flag.None);
+        /**
+         * Bumped on every {@link Flags.refresh} call.
+         *
+         * `refresh` intentionally leaves `value$` unchanged, so it cannot be used as
+         * a repaint channel on its own: since `@preact/signals-core` 1.14 a `batch`
+         * that ends on its initial value notifies nobody. Subscribers that must
+         * re-run on a forced refresh have to read this revision counter as well.
+         */
+        this.#revision$ = signal(0);
+    }
+    /**
+     * Bumped on every {@link Flags.refresh} call.
+     *
+     * `refresh` intentionally leaves `value$` unchanged, so it cannot be used as
+     * a repaint channel on its own: since `@preact/signals-core` 1.14 a `batch`
+     * that ends on its initial value notifies nobody. Subscribers that must
+     * re-run on a forced refresh have to read this revision counter as well.
+     */
+    #revision$;
+    get revision() {
+        return this.#revision$.peek();
+    }
+    get revision$() {
+        return this.#revision$;
     }
     get value() {
         return this.value$.peek();
@@ -33,10 +57,17 @@ export class Flags {
     contains(flag, value = this.value) {
         return (flag & value) !== Flag.None;
     }
+    /**
+     * Forces subscribers to re-run while keeping `flag` activated.
+     *
+     * The revision bump is what actually notifies; the batch keeps both writes
+     * in a single notification so the toolbar never sees a transient
+     * {@link Flag.None} frame.
+     */
     refresh(flag) {
         batch(() => {
-            this.toggle(flag, false);
             this.toggle(flag, true);
+            this.#revision$.value++;
         });
     }
     reset() {

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

@@ -8,7 +8,19 @@ import type { ToolbarModule } from './module.js';
 export declare const ToolbarModuleIdentifier: import("../../../global/di/types.js").ServiceIdentifier<ToolbarModule> & (<U extends ToolbarModule = ToolbarModule>(variant: import("../../../global/di/types.js").ServiceVariant) => import("../../../global/di/types.js").ServiceIdentifier<U>);
 export declare const ToolbarRegistryIdentifier: import("../../../global/di/types.js").ServiceIdentifier<ToolbarRegistryExtension> & (<U extends ToolbarRegistryExtension = ToolbarRegistryExtension>(variant: import("../../../global/di/types.js").ServiceVariant) => import("../../../global/di/types.js").ServiceIdentifier<U>);
 export declare function ToolbarModuleExtension(module: ToolbarModule): ExtensionType;
+/** The flavour a DI variant speaks for, owner suffix and all. */
+export declare function toolbarModuleFlavour(variant: string): string;
+/**
+ * A second (or third) module on one flavour, named by who contributes it.
+ *
+ * The owner is never shown and never parsed back — it exists so two
+ * contributors cannot claim one DI variant. Use a stable, framework-scoped
+ * name (`c4-morph`), because it is the identity the container refuses
+ * duplicates on.
+ */
+export declare function toolbarModuleKey(flavour: string, owner: string): string;
 export declare class ToolbarRegistryExtension extends Extension {
+    #private;
     readonly std: BlockStdScope;
     flavour$: import("@preact/signals-core").Signal<string>;
     elementsMap$: import("@preact/signals-core").Signal<Map<string, GfxModel[]>>;
@@ -20,8 +32,40 @@ export declare class ToolbarRegistryExtension extends Extension {
     placement$: import("@preact/signals-core").Signal<ToolbarPlacement>;
     flags: Flags;
     constructor(std: BlockStdScope);
+    /**
+     * Every module of every flavour, keyed by the DI variant it was registered
+     * under — which for a shared flavour carries an owner suffix. Read
+     * {@link modulesFor} instead unless the variant itself is the question.
+     */
     get modules(): Map<string, ToolbarModule>;
+    /**
+     * Every module contributing to one flavour's row — the bare-key module
+     * first, then the owner-suffixed ones in registration order.
+     */
+    modulesFor(flavour: string): readonly ToolbarModule[];
+    /**
+     * The config registered under the flavour ITSELF, or `null`.
+     *
+     * Deliberately not "the first module of this flavour". The callers of this
+     * method ask a question about one identified registration — does this block
+     * flavour have a toolbar of its own, where does that toolbar sit — and an
+     * owner-suffixed contributor is an ADDITION to a row, not a stand-in for the
+     * module that defines it. Answering with a contributor would make the reply
+     * depend on which frameworks a host happened to switch on: with `wardley`
+     * off and `c4` on, `custom:affine:surface:group` has no bare module at all,
+     * and returning C4's morph there would let a placement (or a `has`-style
+     * probe) be decided by a menu that only some builds ship.
+     */
     getModuleBy(flavour: string): import("./config.js").ToolbarModuleConfig | null;
+    /**
+     * Where a flavour's row sits: the first module of it that actually SAYS.
+     *
+     * A row is one row however many modules contribute to it, so the placement
+     * is a property of the flavour and not of a registration — and a contributor
+     * that declares none must not be read as declaring the default. Scanning for
+     * the first module with a `placement` keeps the answer the same whether the
+     * framework that states it is registered first, last, or under an owner.
+     */
     getModulePlacement(flavour: string, fallback?: ToolbarPlacement): ToolbarPlacement;
     static setup(di: Container): void;
 }