@formicoidea/labre-core 0.41.0 → 0.43.1

package/dist/_pkgs/affine-block-surface/extensions/legend-toolbar.js

@@ -0,0 +1,81 @@
+import { BOARD_LEGEND_NOTATION, TelemetryProvider, } from '../../affine-shared/services/index.js';
+import { html } from 'lit';
+import { createBoardLegend } from './legend.js';
+/**
+ * Contextual-toolbar glyph — "generate the legend of what is on this board".
+ * One icon because it is one gesture; the Core Domain chart has drawn this exact
+ * box-and-rows since its legend button shipped and the others borrowed it.
+ *
+ * `html` rather than `svg`: a toolbar action's `icon` is rendered as a
+ * standalone template, unlike the senior-button glyphs that are interpolated
+ * into an outer `<svg>`.
+ */
+export const legendIcon = html `<svg
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <rect
+    x="3"
+    y="4"
+    width="18"
+    height="16"
+    rx="2"
+    stroke="currentColor"
+    stroke-width="1.6"
+  />
+  <circle cx="7" cy="9" r="1.6" fill="currentColor" />
+  <circle cx="7" cy="14" r="1.6" fill="currentColor" />
+  <path d="M11 9 H18 M11 14 H18" stroke="currentColor" stroke-width="1.4" />
+</svg>`;
+/**
+ * The ONE `FrameworkLegendCreated` emission, with the wire values every
+ * framework's own button has been sending.
+ *
+ * `framework` is the HISTORICAL PostHog value (`FrameworkDescriptor.
+ * telemetryKey`): `context-map`, not `ddd-context-map`. It is a parameter and
+ * not derived from anything, because the two spellings differ for three of the
+ * eight frameworks and a prefix rule would quietly rename a metric.
+ */
+export function trackLegendCreated(std, framework, module) {
+    std.getOptional(TelemetryProvider)?.track('FrameworkLegendCreated', {
+        framework,
+        element: 'legend',
+        page: 'whiteboard editor',
+        segment: 'element toolbar',
+        module,
+    });
+}
+/**
+ * The shared legend entry of a board's contextual toolbar.
+ *
+ * Registered by each framework in its OWN flag-gated module
+ * (`custom:affine:surface:<board>`), merged with `validationToolbarConfig`'s
+ * actions: a flavour may carry exactly one toolbar module, and generating a
+ * legend is tooling a flag may take away. What the gesture already WROTE is
+ * document content and keeps being painted with the flag off — the box is made
+ * of plain shapes, text and the framework's own always-on renderers.
+ */
+export function legendToolbarAction({ id = 'b.legend', Model, owner, framework, module = `${framework} toolbar`, tooltipWording = BOARD_LEGEND_NOTATION, icon = legendIcon, }) {
+    const boardOf = (ctx) => ctx.getSurfaceModelsByType(Model)[0];
+    return {
+        id,
+        tooltipWording,
+        icon,
+        run(ctx) {
+            if (ctx.std.store.readonly)
+                return;
+            // The FIRST selected board and no other: a legend is placed relative to
+            // one board, and two of them would put two boxes on top of whatever sits
+            // in that corner.
+            const board = boardOf(ctx);
+            if (!board)
+                return;
+            createBoardLegend(ctx.std, board, owner);
+            trackLegendCreated(ctx.std, framework, module);
+        },
+        when: (ctx) => boardOf(ctx) !== undefined,
+    };
+}

package/dist/_pkgs/affine-block-surface/extensions/legend.d.ts

@@ -0,0 +1,144 @@
+import { Bound } from '../../global/gfx/index.js';
+import { type BlockStdScope, type CommandLegendExtra, type CommandLegendRow, type CommandOwner } from '../../std/index.js';
+import { type GfxController, type RoleId } from '../../std/gfx/index.js';
+/**
+ * The legend PLATFORM: one engine, one box, for every framework that documents
+ * itself.
+ *
+ * Two things it deliberately does not do, and they are the whole design:
+ *
+ * - **detection is by ROLE, never by `instanceof` or by fill colour.** A role is
+ *   the semantic identity of an artefact (`framework/std`'s `role.ts`); a shape
+ *   type is not, and a colour is a restyle away from lying. Reading roles also
+ *   means a legend and a validation rule agree on what is on the board, because
+ *   they read the same field;
+ * - **a framework writes no legend code.** {@link legendFromCommands} derives
+ *   the whole thing from the commands it already declares — their order, their
+ *   category, the role each stamps and the swatch each subscribes
+ *   (`CommandDescriptor.legend`). Scanning the perimeter, resolving
+ *   specialisations, dropping empty sections, placing and grouping the box all
+ *   happen here, once.
+ *
+ * It lives in the surface block rather than with any framework bundle for the
+ * reason `validation.ts` next door does: BPMN and Wardley must not take a
+ * dependency on a DDD bundle to draw their own legend.
+ *
+ * See `docs/adr/0026`.
+ */
+type Surface = NonNullable<GfxController['surface']>;
+/** A {@link CommandLegendRow} with the label the engine resolved for it. */
+export interface LegendRow extends CommandLegendRow {
+    label: string;
+}
+export interface LegendSection {
+    title?: string;
+    rows: LegendRow[];
+}
+/** How the box is laid out, for a legend whose swatches are not 16-unit chips. */
+export interface LegendLayout {
+    width?: number;
+    /** Row pitch; the swatch is drawn centred in it. Defaults to 28. */
+    rowHeight?: number;
+    /** Swatch box, defaults to a 16 × 16 chip. */
+    swatchWidth?: number;
+    swatchHeight?: number;
+}
+/** A block of the box that is not a row. See {@link CommandLegendBox.extras}. */
+export type LegendExtra = CommandLegendExtra;
+/**
+ * The ink and the type a notation writes its labels in: this box's rows, and
+ * the words the DDD prefabs set beside a dot or a marker.
+ *
+ * Declared HERE and re-exported by `@labre/affine-gfx-ddd-shared`, rather than
+ * the other way round, because that bundle depends on this one and a legend
+ * must not depend on a DDD bundle to be drawn.
+ */
+export declare const LABEL_COLOR: string;
+export declare const LABEL_FONT = "blocksuite:surface:Inter";
+export declare const LABEL_FONT_SIZE = 14;
+/**
+ * The role the legend's GROUP carries — the one thing on a generated legend
+ * that says what it is.
+ *
+ * Its glyphs deliberately carry none (see {@link addShape}), which is what
+ * keeps a legend out of the scan and out of every validation rule. But "made of
+ * nothing in particular" is unreadable to anything that has to tell a legend
+ * from a drawing, and something does: the `.bpmn` export counts what it left
+ * behind inside a pool, and a legend's fourteen glyphs would be reported as
+ * fourteen losses. The wrapper says so instead, once, structurally — no title
+ * to match on, no framework name, no geometry.
+ *
+ * `core:` because it belongs to no framework: no `RoleDefs` declares it, so
+ * `roleIsA` matches it against nothing, no rule evaluates it and no legend row
+ * lights because of it. Nothing is backfilled, as ever — a legend drawn before
+ * this shipped carries no role and is not recognised.
+ */
+export declare const LEGEND_ROLE = "core:legend";
+/**
+ * How big the box {@link addLegend} would draw for these sections is — without
+ * drawing it. The engine needs the height to drop the box bottom-left of a
+ * board, and measuring is the only honest way to get it: the box grows with the
+ * number of sub-titles, rows and extras, which is exactly what the detection
+ * pass decides.
+ */
+export declare function measureLegend(sections: readonly LegendSection[], layout?: LegendLayout, extras?: readonly LegendExtra[]): {
+    width: number;
+    height: number;
+};
+/**
+ * A boxed legend: a bordered container with a bold title and bold section
+ * sub-titles, each row a swatch + label, then whatever `extras` add below.
+ * Returns the grouped id.
+ */
+export declare function addLegend(surface: Surface, std: BlockStdScope, x: number, y: number, opts: {
+    title: string;
+    sections: LegendSection[];
+    extras?: readonly LegendExtra[];
+} & LegendLayout): string;
+/**
+ * Every role carried by an element inside `bound`.
+ *
+ * Neutral elements (no role) contribute nothing, which is the whole
+ * compatibility promise: a board drawn before the vocabularies existed produces
+ * an empty set and therefore a legend with no rows, exactly like an empty board.
+ * It is also why a legend never lists itself: nothing it draws carries a role.
+ */
+export declare function rolesInBound(gfx: GfxController, bound: Bound): Set<RoleId>;
+/**
+ * The legend of a board, derived from the commands of the framework that owns
+ * it: every subscribed row whose role is present (directly or through a
+ * specialisation, unless the entry asks for {@link CommandLegendEntry.exact}),
+ * in command order, grouped under the section each declares — or under its
+ * command's category — with empty sections dropped.
+ *
+ * The SUB-TITLES come out in the order the framework first declares them,
+ * walking every command whether its row lights or not: a legend is a key to a
+ * notation, so the same framework reads in the same order on every board, and
+ * only the rows change.
+ *
+ * Rows are de-duplicated BY ROLE, first declaration winning: two commands draw
+ * a Wardley area (a rectangle and a polygon) and the notation has one "Area".
+ *
+ * When nothing is recognised the result is an EMPTY array, and the caller still
+ * draws the box: a legend of a board with nothing on it lists nothing, rather
+ * than inventing the full notation the user has not used.
+ */
+export declare function legendFromCommands(std: BlockStdScope, owner: CommandOwner, present: ReadonlySet<RoleId>): LegendSection[];
+/**
+ * Build the legend of what is drawn inside `board` and drop it bottom-left of
+ * it, grouped and selected. THE gesture the shared toolbar button runs.
+ *
+ * REPLACES the board's own legend if it already has one, rather than stacking a
+ * second box on the first (issue #391): the placement is derived from the board
+ * alone, so every press landed at the same pixel and the copies were invisible
+ * — one box to the eye, N groups and N × ~15 elements in the document. The
+ * second press is therefore a REFRESH, which is what a user who has just added
+ * three artefacts is asking for; the cost is that hand retouching of the box is
+ * lost, and one undo brings it back (see {@link legendsOn} and ADR 0026).
+ *
+ * Returns the group id, or `undefined` when there is no surface to draw on.
+ */
+export declare function createBoardLegend(std: BlockStdScope, board: {
+    xywh: string;
+}, owner: CommandOwner): string | undefined;
+export {};