@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/_pkgs/affine-widget-edgeless-toolbar/catalogue/artefact-catalogue-widget.js

@@ -0,0 +1,572 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { EDITOR_ANCHORED_PANEL_Z_INDEX } from '../../affine-block-surface/index.js';
+import { TOUCH_TARGET_MIN_PX } from '../../affine-shared/consts/index.js';
+import { translateKey } from '../../affine-shared/services/index.js';
+import { IS_MAC } from '../../global/env/index.js';
+import { getCommandIcon, CommandUsageIdentifier, getCommandsForSurface, isCommandAvailable, normalizeLegacyCombo, rankCommandsByUsage, runCommand, ShortcutOverrideIdentifier, WidgetComponent, WidgetViewExtension, } from '../../std/index.js';
+import { css, html, nothing, unsafeCSS } from 'lit';
+import { state } from 'lit/decorators.js';
+import { literal, unsafeStatic } from 'lit/static-html.js';
+import { CATALOGUE_CATEGORY_KEY_PREFIX, groupCommandsByCategory, humanizeCategory, } from './catalogue-groups.js';
+import { formatChord } from './chord-format.js';
+export const EDGELESS_ARTEFACT_CATALOGUE_WIDGET = 'edgeless-artefact-catalogue-widget';
+/** Wide enough for an icon, a label and a chord; never more than most of a phone. */
+const PANEL_WIDTH = 'min(320px, 85vw)';
+/**
+ * The **artefact catalogue** sidepanel (PF6).
+ *
+ * A framework's senior sub-menu is a row of icons, and a row of icons stops
+ * working somewhere around fourteen. The BPMN pack is the first framework to
+ * pass that line, so the sub-menu shows the thirteen the ranking put first and
+ * hands the rest to this panel: everything the owner declares on the
+ * `'catalogue'` surface, grouped by the categories the framework itself
+ * declared, with the label and the chord spelled out instead of guessed from a
+ * glyph.
+ *
+ * ## Left, full height, inside the editor
+ *
+ * Not a popover, not a modal. It is a column down the left edge of the editor
+ * host — the side no toolbar occupies — the canvas stays live to its right, and
+ * a click on the canvas puts it away. Twenty artefacts want a list you scroll,
+ * and a list you scroll wants height; a floating box would have had to choose
+ * between covering the board and showing four rows at a time.
+ *
+ * ## Not an `EditorAnchoredPanel`
+ *
+ * The shared base (ADR 0011) exists for panels pinned ABOVE the senior button
+ * bar and measured against it: its host is bottom-left and zero-sized, and
+ * `anchorBox()` returns a `bottom` and a width read off the bar. None of that
+ * is expressible for a full-height column, so the geometry is this file's own —
+ * but the WISDOM is not reinvented. The layer constant is imported from there
+ * rather than copied, and the host is zero-WIDTH for the same reason its host is
+ * zero-sized (`.widgets-container > * { pointer-events: auto }` is an outer-tree
+ * rule that beats `:host { pointer-events: none }`, so a host with a real box
+ * would swallow canvas clicks down the whole left side of the board). The
+ * click-away, the Escape-on-`std.host` scope and the disconnect cleanup are the
+ * same contracts, replicated in about thirty lines.
+ *
+ * ## What closing does, and does not
+ *
+ * X, Escape and click-away all close, on the FIRST gesture, and none of them
+ * touches the active senior tool: the panel is a way of reaching a command, not
+ * a mode. Invoking a row closes it too — the PO's default is one tap and back
+ * to the canvas.
+ *
+ * ## Who opens it
+ *
+ * `ArtefactCatalogueProvider`. This widget registers itself as the DEFAULT
+ * implementation ({@link artefactCatalogueDefaultExtension}); a host with its
+ * own sidebar registers `ArtefactCatalogueExtension(service)`, whose
+ * `di.override` wins, and this panel is then never asked to open.
+ */
+let EdgelessArtefactCatalogueWidget = (() => {
+    let _classSuper = WidgetComponent;
+    let __owner_decorators;
+    let __owner_initializers = [];
+    let __owner_extraInitializers = [];
+    return class EdgelessArtefactCatalogueWidget extends _classSuper {
+        constructor() {
+            super(...arguments);
+            this.#_owner_accessor_storage = __runInitializers(this, __owner_initializers, null);
+            /** The owner the body was last scrolled to the top for. */
+            this._scrolledFor = (__runInitializers(this, __owner_extraInitializers), null);
+            /**
+             * Put the panel away. Deliberately writes NOTHING but its own state: the
+             * senior tool the user armed before opening the catalogue is still armed
+             * after, whichever gesture closed it.
+             */
+            this.closePanel = () => {
+                this._owner = null;
+            };
+            /** Keep a gesture inside the panel from reaching the canvas behind it. */
+            this._swallow = (event) => {
+                event.stopPropagation();
+            };
+            this._onDocumentPointerDown = (event) => {
+                if (!this.catalogueOpen)
+                    return;
+                // Anything inside this widget keeps it open. The sub-menu entry that opened
+                // it is in another tree, and its own click already landed.
+                if (event.composedPath().includes(this))
+                    return;
+                this.closePanel();
+            };
+            /**
+             * Escape is listened for on the EDITOR HOST, not on `document`: a host
+             * application keeps its own global Escape, and with the catalogue open the
+             * key dismisses the catalogue rather than clearing the canvas selection
+             * behind it. Same scope and same reasoning as `EditorAnchoredPanel`.
+             */
+            this._onHostKeydown = (event) => {
+                if (!this.catalogueOpen || event.key !== 'Escape')
+                    return;
+                event.stopPropagation();
+                this.closePanel();
+            };
+            /**
+             * A wheel OVER THE PANEL scrolls the panel, never the board.
+             *
+             * Same bug and same fix as the violation bubble (PR #103, PO 02/08):
+             * `EdgelessRootBlock` takes `wheel` off the event dispatcher on the editor
+             * host and `preventDefault()`s unconditionally before panning — so a wheel
+             * over the catalogue's overflowing list panned the canvas instead of
+             * scrolling the twenty artefacts under the pointer (PO recette, 27/08/2026).
+             * One CAPTURE-phase listener on the host stops the event before the
+             * dispatcher sees it; no `preventDefault`, because the default action IS the
+             * panel scrolling.
+             *
+             * Narrower than the bubble's freeze, deliberately: the bubble owns the wheel
+             * everywhere while open (a reading gesture); the catalogue only claims the
+             * wheel over its own box — `composedPath` gate — and the canvas to its right
+             * keeps panning, because furnishing a diagram means looking around it.
+             */
+            this._onHostWheel = (event) => {
+                if (!this.catalogueOpen)
+                    return;
+                if (!event.composedPath().includes(this))
+                    return;
+                event.stopPropagation();
+            };
+        }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            __owner_decorators = [state()];
+            __esDecorate(this, null, __owner_decorators, { kind: "accessor", name: "_owner", static: false, private: false, access: { has: obj => "_owner" in obj, get: obj => obj._owner, set: (obj, value) => { obj._owner = value; } }, metadata: _metadata }, __owner_initializers, __owner_extraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static { this.styles = css `
+    /*
+      A zero-WIDTH host spanning the editor's full height. See the class
+      docstring: a host with a real box would take every pointer event down the
+      left edge of the canvas, open or not. The panel below carries the box.
+    */
+    :host {
+      position: absolute;
+      left: 0;
+      top: 0;
+      bottom: 0;
+      width: 0;
+      z-index: ${unsafeCSS(EDITOR_ANCHORED_PANEL_Z_INDEX)};
+      pointer-events: none;
+      font-family: var(--affine-font-family);
+    }
+
+    .artefact-catalogue-panel {
+      position: absolute;
+      left: 0;
+      top: 0;
+      bottom: 0;
+      width: ${unsafeCSS(PANEL_WIDTH)};
+      box-sizing: border-box;
+      display: flex;
+      flex-direction: column;
+      background: var(--affine-background-overlay-panel-color, #fff);
+      border-right: 1px solid var(--affine-border-color);
+      box-shadow: var(--affine-shadow-2);
+      color: var(--affine-text-primary-color);
+      font-size: 14px;
+      line-height: 1.4;
+      pointer-events: auto;
+    }
+
+    .artefact-catalogue-panel:focus-visible {
+      outline: 2px solid var(--affine-primary-color);
+      outline-offset: -2px;
+    }
+
+    .artefact-catalogue-head {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+      padding: 8px 8px 8px 16px;
+      border-bottom: 1px solid var(--affine-border-color);
+      font-weight: 600;
+    }
+
+    .artefact-catalogue-title {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    /*
+      A close button a finger can hit. Square at the touch minimum rather than
+      the 6px-padded × the anchored panels use: this one is the only way out of
+      a full-height surface on a tablet, where there is no Escape key.
+    */
+    .artefact-catalogue-close {
+      flex: none;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: ${unsafeCSS(TOUCH_TARGET_MIN_PX)}px;
+      height: ${unsafeCSS(TOUCH_TARGET_MIN_PX)}px;
+      border: none;
+      border-radius: 8px;
+      background: transparent;
+      color: var(--affine-text-secondary-color);
+      font-family: inherit;
+      font-size: 20px;
+      line-height: 1;
+      cursor: pointer;
+    }
+
+    .artefact-catalogue-close:hover,
+    .artefact-catalogue-close:focus-visible {
+      background: var(--affine-hover-color);
+      color: var(--affine-text-primary-color);
+    }
+
+    .artefact-catalogue-body {
+      flex: 1;
+      min-height: 0;
+      overflow-y: auto;
+      overflow-x: hidden;
+      /* The canvas behind must never scroll because this list bottomed out. */
+      overscroll-behavior: contain;
+      -webkit-overflow-scrolling: touch;
+      padding: 8px 0 16px;
+    }
+
+    .artefact-catalogue-group-label {
+      padding: 12px 16px 4px;
+      color: var(--affine-text-secondary-color);
+      font-size: 12px;
+      font-weight: 600;
+      letter-spacing: 0.04em;
+      text-transform: uppercase;
+    }
+
+    /*
+      Full-width rows, never narrower than a finger. A minimum and not a fixed
+      height: a long label in a translated catalogue wraps and the row grows,
+      which is the direction a touch target may move.
+    */
+    .artefact-catalogue-entry {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      width: 100%;
+      min-height: ${unsafeCSS(TOUCH_TARGET_MIN_PX)}px;
+      box-sizing: border-box;
+      padding: 6px 16px;
+      border: none;
+      background: transparent;
+      color: inherit;
+      font: inherit;
+      text-align: left;
+      cursor: pointer;
+    }
+
+    /*
+      Visible states, not hover-only affordances: a finger never hovers, so the
+      pressed state is what tells a tablet user the tap landed.
+    */
+    .artefact-catalogue-entry:hover {
+      background: var(--affine-hover-color);
+    }
+
+    .artefact-catalogue-entry:active {
+      background: var(--affine-hover-color);
+      filter: brightness(0.97);
+    }
+
+    .artefact-catalogue-entry:focus-visible {
+      outline: 2px solid var(--affine-primary-color);
+      outline-offset: -2px;
+    }
+
+    .artefact-catalogue-icon {
+      flex: none;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 24px;
+      height: 24px;
+      fill: var(--affine-icon-color);
+      color: var(--affine-icon-color);
+    }
+
+    .artefact-catalogue-icon svg {
+      width: 24px;
+      height: 24px;
+    }
+
+    .artefact-catalogue-label {
+      flex: 1;
+      min-width: 0;
+      overflow-wrap: anywhere;
+    }
+
+    .artefact-catalogue-chord {
+      flex: none;
+      color: var(--affine-text-secondary-color);
+      font-size: 12px;
+      white-space: nowrap;
+    }
+  `; }
+        #_owner_accessor_storage;
+        /** Which framework's catalogue is on screen, or `null` when it is away. */
+        get _owner() { return this.#_owner_accessor_storage; }
+        set _owner(value) { this.#_owner_accessor_storage = value; }
+        get catalogueOpen() {
+            return this._owner !== null;
+        }
+        /**
+         * Show `owner`'s catalogue. Called through `ArtefactCatalogueProvider`, never
+         * from another widget's DOM — the sub-menu that opens it lives in a different
+         * tree, and the seam is what keeps a host's own sidebar substitutable.
+         */
+        openFor(owner) {
+            this._owner = owner;
+        }
+        /**
+         * Idempotent, and called from both `firstUpdated` and a later
+         * `connectedCallback`: `WithDisposable` throws the group away on disconnect
+         * while lit runs `firstUpdated` exactly once.
+         */
+        _wire() {
+            document.addEventListener('pointerdown', this._onDocumentPointerDown, true);
+            const host = this.std.host;
+            host.addEventListener('keydown', this._onHostKeydown, true);
+            host.addEventListener('wheel', this._onHostWheel, true);
+            this._disposables.add(() => {
+                document.removeEventListener('pointerdown', this._onDocumentPointerDown, true);
+                host.removeEventListener('keydown', this._onHostKeydown, true);
+                host.removeEventListener('wheel', this._onHostWheel, true);
+            });
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            if (this.hasUpdated)
+                this._wire();
+        }
+        firstUpdated() {
+            this._wire();
+        }
+        /**
+         * On open: the panel takes the focus and the list starts at the top.
+         *
+         * The focus is what makes the panel reachable from a keyboard and audible to
+         * a screen reader — it carries the dialog's label, so the framework's name is
+         * read before the first artefact. `preventScroll` because the host is a
+         * zero-width box at the editor's origin and the browser would otherwise
+         * scroll the editor to "reveal" it.
+         *
+         * The scroll reset matters on the second open: a user who scrolled to the
+         * bottom of BPMN's twenty artefacts, closed, and opened the panel again for
+         * another framework would otherwise land mid-list with no idea what is above.
+         */
+        updated() {
+            const owner = this._owner;
+            if (owner === null || owner === this._scrolledFor) {
+                if (owner === null)
+                    this._scrolledFor = null;
+                return;
+            }
+            const panel = this.shadowRoot?.querySelector('[data-testid="artefact-catalogue-panel"]');
+            if (!panel)
+                return;
+            this._scrolledFor = owner;
+            const body = this.shadowRoot?.querySelector('[data-testid="artefact-catalogue-body"]');
+            if (body)
+                body.scrollTop = 0;
+            panel.focus({ preventScroll: true });
+        }
+        /**
+         * The commands this panel draws: the owner's `'catalogue'` surface, minus the
+         * ones whose preconditions do not hold.
+         *
+         * Unavailable commands are DROPPED, not greyed out. A disabled row in a list
+         * of twenty is noise a reader has to step over on every pass, and the panel
+         * has no room to say why it is disabled; a command that comes back when the
+         * selection changes simply reappears.
+         */
+        _commands(owner) {
+            const { std } = this;
+            return getCommandsForSurface(std, owner, 'catalogue').filter(command => isCommandAvailable(std, command) && (!command.when || command.when(std)));
+        }
+        /**
+         * The chord this command answers to on this platform, as the user would type
+         * it — or `null` for the many commands that ship keyless (and stay bindable).
+         *
+         * The host's override table is consulted, so a rebound command shows what it
+         * is actually bound to rather than what it shipped with, and a `'disabled'`
+         * entry shows nothing at all.
+         */
+        _chord(command) {
+            const overrides = this.std.getOptional(ShortcutOverrideIdentifier) ?? {};
+            const override = overrides[command.id];
+            if (override === 'disabled')
+                return null;
+            const keys = normalizeLegacyCombo(override ?? (IS_MAC ? command.defaultKeys.mac : command.defaultKeys.other));
+            return keys.length ? formatChord(keys, IS_MAC) : null;
+        }
+        /**
+         * Run the command. The panel STAYS OPEN.
+         *
+         * `runCommand` is the one bottleneck (ADR 0008): the telemetry and the usage
+         * measure are emitted there, and `surface: 'catalogue'` is what makes this
+         * panel distinguishable from the sub-menu in the numbers.
+         *
+         * Staying open is the PO's call (recette, 27/08/2026), reversing the first
+         * default: a catalogue is where a user furnishes a diagram, and furnishing is
+         * several artefacts in a row — closing after each one turned that into
+         * open-click-reopen. The exits are unchanged and all one gesture: ×, Escape,
+         * or a click on the canvas.
+         */
+        _invoke(command) {
+            runCommand(this.std, command, {
+                surface: 'catalogue',
+                source: 'toolbar:general',
+            });
+        }
+        _groupLabel(group) {
+            const { category } = group;
+            if (category === null) {
+                return translateKey(this.std, 'com.labre.catalogue.other', 'Other');
+            }
+            return translateKey(this.std, `${CATALOGUE_CATEGORY_KEY_PREFIX}${category}`, humanizeCategory(category));
+        }
+        _renderEntry(command) {
+            const icon = getCommandIcon(this.std, command.iconKey);
+            const label = translateKey(this.std, command.labelKey, command.labelFallback);
+            const chord = this._chord(command);
+            return html `<button
+      class="artefact-catalogue-entry"
+      type="button"
+      data-testid="artefact-catalogue-entry"
+      data-command-id=${command.id}
+      @click=${() => this._invoke(command)}
+    >
+      <span class="artefact-catalogue-icon">${icon ?? nothing}</span>
+      <span class="artefact-catalogue-label">${label}</span>
+      ${chord
+                ? html `<span class="artefact-catalogue-chord">${chord}</span>`
+                : nothing}
+    </button>`;
+        }
+        render() {
+            const owner = this._owner;
+            if (owner === null)
+                return nothing;
+            const commands = this._commands(owner);
+            const groups = groupCommandsByCategory(commands);
+            // The head section: what THIS user reaches for, latest first — the
+            // sub-menu's arbitration re-consumed whole (PO recette, 27/08/2026).
+            // Absent entirely until something has been used: a "recent" list padded
+            // with the never-used would be a label that lies. The rows repeat below in
+            // their categories on purpose, the way every launcher does it — the head
+            // is a shortcut, not a re-filing.
+            //
+            // `commands` here is the whole CATALOGUE, deliberately: the eligibility
+            // ruling of 2026-08-28 narrowed the SUB-MENU to commands that declare
+            // `'senior-menu'`, because that row is a row of things you draw. This panel
+            // is the full-catalogue surface, so a board action a user really does reach
+            // for — `bpmn.exportXml` — belongs at its head. See `rankCommandsByUsage`.
+            //
+            // Seven rows at most (`CATALOGUE_HEAD_RANKED_SLOTS`, 4 recent + 3 used),
+            // NOT the sub-menu's thirteen: at 44px a row, thirteen would be ~604px of
+            // duplicated shortcuts and would push every category below the fold on a
+            // laptop. Same arbitration, its own magnitude.
+            const usage = this.std.getOptional(CommandUsageIdentifier);
+            const ranked = usage
+                ? rankCommandsByUsage(commands, id => usage.statsOf(id))
+                : [];
+            const rankedLabel = translateKey(this.std, 'com.labre.catalogue.ranked', 'Recent & frequent');
+            // A framework's own name, through the same key the senior button uses. The
+            // fallback is the owner id respelled — the library invents no framework
+            // prose, and a host with a catalogue always wins.
+            const frameworkLabel = translateKey(this.std, `com.labre.framework.${owner}`, humanizeCategory(owner));
+            const catalogueTitle = translateKey(this.std, 'com.labre.catalogue.title', 'Artefacts');
+            return html `<div
+      class="artefact-catalogue-panel"
+      role="dialog"
+      tabindex="-1"
+      aria-label=${`${frameworkLabel} — ${catalogueTitle}`}
+      data-testid="artefact-catalogue-panel"
+      data-owner=${owner}
+      @pointerdown=${this._swallow}
+      @pointerup=${this._swallow}
+      @click=${this._swallow}
+    >
+      <div class="artefact-catalogue-head">
+        <span class="artefact-catalogue-title">${frameworkLabel}</span>
+        <button
+          class="artefact-catalogue-close"
+          type="button"
+          data-testid="artefact-catalogue-close"
+          aria-label=${translateKey(this.std, 'com.labre.catalogue.close', 'Close')}
+          @click=${this.closePanel}
+        >
+          ×
+        </button>
+      </div>
+      <div
+        class="artefact-catalogue-body"
+        data-testid="artefact-catalogue-body"
+      >
+        ${ranked.length
+                ? html `<div
+              class="artefact-catalogue-group"
+              data-testid="artefact-catalogue-ranked"
+              role="group"
+              aria-label=${rankedLabel}
+            >
+              <div class="artefact-catalogue-group-label">${rankedLabel}</div>
+              ${ranked.map(command => this._renderEntry(command))}
+            </div>`
+                : nothing}
+        ${groups.map(group => html `<div
+              class="artefact-catalogue-group"
+              data-testid="artefact-catalogue-group"
+              data-category=${group.category ?? ''}
+              role="group"
+              aria-label=${this._groupLabel(group)}
+            >
+              <div class="artefact-catalogue-group-label">
+                ${this._groupLabel(group)}
+              </div>
+              ${group.commands.map(command => this._renderEntry(command))}
+            </div>`)}
+      </div>
+    </div>`;
+        }
+    };
+})();
+export { EdgelessArtefactCatalogueWidget };
+export const edgelessArtefactCatalogueWidget = WidgetViewExtension('affine:page', EDGELESS_ARTEFACT_CATALOGUE_WIDGET, literal `${unsafeStatic(EDGELESS_ARTEFACT_CATALOGUE_WIDGET)}`);

package/dist/_pkgs/affine-widget-edgeless-toolbar/catalogue/catalogue-groups.d.ts

@@ -0,0 +1,46 @@
+import type { AnyCommandDescriptor } from '../../std/index.js';
+/** The i18n key prefix every catalogue group header is looked up under. */
+export declare const CATALOGUE_CATEGORY_KEY_PREFIX = "com.labre.catalogue.category.";
+/**
+ * One section of the catalogue: a category and the commands declaring it.
+ *
+ * `category` is `null` for the trailing group of commands that declare none —
+ * see {@link groupCommandsByCategory}.
+ */
+export interface CatalogueGroup {
+    category: string | null;
+    commands: AnyCommandDescriptor[];
+}
+/**
+ * Split a surface's commands into the sections the sidepanel draws.
+ *
+ * Two rules, and both exist to keep the panel's order the FRAMEWORK's order:
+ *
+ * - groups appear in the order their category is first met, not alphabetically.
+ *   `getCommandsForSurface` has already sorted by `CommandDescriptor.order`, so
+ *   a framework that declared backgrounds before nodes before connectors gets
+ *   exactly that reading, and sorting the headers by name would quietly
+ *   overrule it;
+ * - a command with no category joins ONE trailing group, and that group exists
+ *   only when something lands in it. An "Other" header over an empty section —
+ *   or over a framework whose commands are all uncategorised, where it would be
+ *   the only header — says nothing a reader can use.
+ *
+ * Pure on purpose: this is the half of the panel worth unit-testing, and it
+ * knows nothing about lit, the DOM or the editor.
+ */
+export declare function groupCommandsByCategory(commands: readonly AnyCommandDescriptor[]): CatalogueGroup[];
+/**
+ * The English default for a category header, derived from the category id.
+ *
+ * `'backgrounds'` → `'Backgrounds'`, `'value-flow'` → `'Value flow'`,
+ * `'boundedContext'` → `'Bounded context'`. Sentence case, not title case: a
+ * header is a phrase, and capitalising every word turns `'change arrows'` into
+ * a product name.
+ *
+ * It is a FALLBACK and nothing more. A host with a catalogue answers
+ * `com.labre.catalogue.category.<id>` and this is never seen; a standalone
+ * playground reads a word instead of a raw key. The library still invents no
+ * framework prose — a category id is the framework's own word, only respelled.
+ */
+export declare function humanizeCategory(category: string): string;

package/dist/_pkgs/affine-widget-edgeless-toolbar/catalogue/catalogue-groups.js

@@ -0,0 +1,66 @@
+/** The i18n key prefix every catalogue group header is looked up under. */
+export const CATALOGUE_CATEGORY_KEY_PREFIX = 'com.labre.catalogue.category.';
+/**
+ * Split a surface's commands into the sections the sidepanel draws.
+ *
+ * Two rules, and both exist to keep the panel's order the FRAMEWORK's order:
+ *
+ * - groups appear in the order their category is first met, not alphabetically.
+ *   `getCommandsForSurface` has already sorted by `CommandDescriptor.order`, so
+ *   a framework that declared backgrounds before nodes before connectors gets
+ *   exactly that reading, and sorting the headers by name would quietly
+ *   overrule it;
+ * - a command with no category joins ONE trailing group, and that group exists
+ *   only when something lands in it. An "Other" header over an empty section —
+ *   or over a framework whose commands are all uncategorised, where it would be
+ *   the only header — says nothing a reader can use.
+ *
+ * Pure on purpose: this is the half of the panel worth unit-testing, and it
+ * knows nothing about lit, the DOM or the editor.
+ */
+export function groupCommandsByCategory(commands) {
+    const byCategory = new Map();
+    const uncategorised = [];
+    for (const command of commands) {
+        const { category } = command;
+        if (!category) {
+            uncategorised.push(command);
+            continue;
+        }
+        const group = byCategory.get(category);
+        if (group)
+            group.push(command);
+        else
+            byCategory.set(category, [command]);
+    }
+    const groups = [...byCategory].map(([category, commands]) => ({ category, commands }));
+    if (uncategorised.length)
+        groups.push({ category: null, commands: uncategorised });
+    return groups;
+}
+/**
+ * The English default for a category header, derived from the category id.
+ *
+ * `'backgrounds'` → `'Backgrounds'`, `'value-flow'` → `'Value flow'`,
+ * `'boundedContext'` → `'Bounded context'`. Sentence case, not title case: a
+ * header is a phrase, and capitalising every word turns `'change arrows'` into
+ * a product name.
+ *
+ * It is a FALLBACK and nothing more. A host with a catalogue answers
+ * `com.labre.catalogue.category.<id>` and this is never seen; a standalone
+ * playground reads a word instead of a raw key. The library still invents no
+ * framework prose — a category id is the framework's own word, only respelled.
+ */
+export function humanizeCategory(category) {
+    const words = category
+        // camelCase and PascalCase boundaries, before the separators are split on:
+        // `'boundedContext'` has no separator to find otherwise.
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map(word => word.toLowerCase());
+    if (!words.length)
+        return category;
+    const [first, ...rest] = words;
+    return [first.charAt(0).toUpperCase() + first.slice(1), ...rest].join(' ');
+}