@formicoidea/labre-ddd-shared 0.32.0 → 0.33.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './shared/consts.js';
+export * from './shared/legend-auto.js';
 export * from './shared/prefabs.js';
 export * from './shared/utils.js';
 export * from './toolbar/icons.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './shared/consts.js';
+export * from './shared/legend-auto.js';
 export * from './shared/prefabs.js';
 export * from './shared/utils.js';
 export * from './toolbar/icons.js';

package/dist/shared/consts.d.ts

@@ -13,7 +13,31 @@ export declare const SHADOW_COLOR = "#0000002e";
 export declare const STICKY_FONT = "blocksuite:surface:Kalam";
 export declare const STICKY_FONT_SIZE = 20;
 export declare const STICKY_RADIUS = 6;
-/** Event Storming sticky palette — DDD Crew / Brandolini colour code. */
+/**
+ * Event Storming sticky palette — DDD Crew / Brandolini colour code.
+ *
+ * ## The aggregate (WS5)
+ *
+ * Brandolini's notation has a pale-yellow sticky for the AGGREGATE — the thing a
+ * command lands on and the thing that raises the event — and without it the
+ * canonical sentence `Command → Aggregate → Domain event` cannot be drawn at
+ * all, let alone checked. It was missing here until WS5.
+ *
+ * Its colour is the one judgement call in this table. The plan's indicative
+ * `#FDF0A0` measures **ΔE 3.5** from the actor's `#FFF1A8` — two stickies
+ * nobody could tell apart on a wall, which is exactly the failure the notation
+ * already has and the tool should not inherit. `#FAF2C9` is the same pale
+ * yellow taken two steps towards cream: ΔE 16.3 from the actor, 50.2 from the
+ * constraint, and still 21.7 from the white board it sits on, so it reads as
+ * "pale" rather than as "blank". The three yellows are then a LADDER — the
+ * constraint saturated, the actor light, the aggregate palest — which is how a
+ * reader tells them apart at a glance without a legend.
+ *
+ * Size carries the rest of the distinction, as it does on a real wall: the
+ * aggregate is created at 160 against the standard 120 (see
+ * `ddd-event-storming/src/commands.ts`). The palette says which; the format
+ * says how big.
+ */
 export declare const ES_STICKIES: readonly [{
     readonly kind: "domainEvent";
     readonly label: "Domain event";
@@ -24,6 +48,11 @@ export declare const ES_STICKIES: readonly [{
     readonly label: "Command";
     readonly fill: "#5BA3DB";
     readonly text: "#06304d";
+}, {
+    readonly kind: "aggregate";
+    readonly label: "Aggregate";
+    readonly fill: "#FAF2C9";
+    readonly text: "#5a4b00";
 }, {
     readonly kind: "actor";
     readonly label: "Actor";

package/dist/shared/consts.js

@@ -13,18 +13,59 @@ export const SHADOW_COLOR = '#0000002e';
 export const STICKY_FONT = 'blocksuite:surface:Kalam';
 export const STICKY_FONT_SIZE = 20;
 export const STICKY_RADIUS = 6;
-/** Event Storming sticky palette — DDD Crew / Brandolini colour code. */
+/**
+ * Event Storming sticky palette — DDD Crew / Brandolini colour code.
+ *
+ * ## The aggregate (WS5)
+ *
+ * Brandolini's notation has a pale-yellow sticky for the AGGREGATE — the thing a
+ * command lands on and the thing that raises the event — and without it the
+ * canonical sentence `Command → Aggregate → Domain event` cannot be drawn at
+ * all, let alone checked. It was missing here until WS5.
+ *
+ * Its colour is the one judgement call in this table. The plan's indicative
+ * `#FDF0A0` measures **ΔE 3.5** from the actor's `#FFF1A8` — two stickies
+ * nobody could tell apart on a wall, which is exactly the failure the notation
+ * already has and the tool should not inherit. `#FAF2C9` is the same pale
+ * yellow taken two steps towards cream: ΔE 16.3 from the actor, 50.2 from the
+ * constraint, and still 21.7 from the white board it sits on, so it reads as
+ * "pale" rather than as "blank". The three yellows are then a LADDER — the
+ * constraint saturated, the actor light, the aggregate palest — which is how a
+ * reader tells them apart at a glance without a legend.
+ *
+ * Size carries the rest of the distinction, as it does on a real wall: the
+ * aggregate is created at 160 against the standard 120 (see
+ * `ddd-event-storming/src/commands.ts`). The palette says which; the format
+ * says how big.
+ */
 export const ES_STICKIES = [
-    { kind: 'domainEvent', label: 'Domain event', fill: '#F5963B', text: '#5a3000' },
+    {
+        kind: 'domainEvent',
+        label: 'Domain event',
+        fill: '#F5963B',
+        text: '#5a3000',
+    },
     { kind: 'command', label: 'Command', fill: '#5BA3DB', text: '#06304d' },
+    // Placed after the command, in the order the grammar reads: an actor issues a
+    // command, a command lands on an aggregate, an aggregate raises an event.
+    { kind: 'aggregate', label: 'Aggregate', fill: '#FAF2C9', text: '#5a4b00' },
     { kind: 'actor', label: 'Actor', fill: '#FFF1A8', text: '#5a4b00' },
     { kind: 'constraint', label: 'Constraint', fill: '#FFD84D', text: '#5a4b00' },
     { kind: 'policy', label: 'Policy', fill: '#C9A8E0', text: '#3d1f57' },
     { kind: 'readModel', label: 'Read model', fill: '#7ED38A', text: '#14502a' },
-    { kind: 'system', label: 'External system', fill: '#F6A6C0', text: '#5e1230' },
+    {
+        kind: 'system',
+        label: 'External system',
+        fill: '#F6A6C0',
+        text: '#5e1230',
+    },
 ];
 /** Hotspot — neon-pink diamond. */
-export const ES_HOTSPOT = { label: 'Hotspot', fill: '#FF1E8E', text: '#ffffff' };
+export const ES_HOTSPOT = {
+    label: 'Hotspot',
+    fill: '#FF1E8E',
+    text: '#ffffff',
+};
 /** Context Map bounded-context bubble. */
 export const CM_BUBBLE = {
     fill: '#e6f0fa',
@@ -41,15 +82,69 @@ export const CM_BUBBLE = {
  * Ways, Big Ball of Mud).
  */
 export const CM_RELATIONSHIPS = [
-    { kind: 'partnership', label: 'Partnership', abbrev: 'PS', upDown: false, dashed: false },
-    { kind: 'sharedKernel', label: 'Shared Kernel', abbrev: 'SK', upDown: false, dashed: false },
-    { kind: 'customerSupplier', label: 'Customer / Supplier', abbrev: 'C/S', upDown: true, dashed: false },
-    { kind: 'conformist', label: 'Conformist', abbrev: 'CF', upDown: true, dashed: false },
-    { kind: 'acl', label: 'Anticorruption Layer', abbrev: 'ACL', upDown: true, dashed: false },
-    { kind: 'ohs', label: 'Open Host Service', abbrev: 'OHS', upDown: true, dashed: false },
-    { kind: 'publishedLanguage', label: 'Published Language', abbrev: 'PL', upDown: true, dashed: false },
-    { kind: 'separateWays', label: 'Separate Ways', abbrev: 'SW', upDown: false, dashed: true },
-    { kind: 'bbom', label: 'Big Ball of Mud', abbrev: 'BBoM', upDown: false, dashed: true },
+    {
+        kind: 'partnership',
+        label: 'Partnership',
+        abbrev: 'PS',
+        upDown: false,
+        dashed: false,
+    },
+    {
+        kind: 'sharedKernel',
+        label: 'Shared Kernel',
+        abbrev: 'SK',
+        upDown: false,
+        dashed: false,
+    },
+    {
+        kind: 'customerSupplier',
+        label: 'Customer / Supplier',
+        abbrev: 'C/S',
+        upDown: true,
+        dashed: false,
+    },
+    {
+        kind: 'conformist',
+        label: 'Conformist',
+        abbrev: 'CF',
+        upDown: true,
+        dashed: false,
+    },
+    {
+        kind: 'acl',
+        label: 'Anticorruption Layer',
+        abbrev: 'ACL',
+        upDown: true,
+        dashed: false,
+    },
+    {
+        kind: 'ohs',
+        label: 'Open Host Service',
+        abbrev: 'OHS',
+        upDown: true,
+        dashed: false,
+    },
+    {
+        kind: 'publishedLanguage',
+        label: 'Published Language',
+        abbrev: 'PL',
+        upDown: true,
+        dashed: false,
+    },
+    {
+        kind: 'separateWays',
+        label: 'Separate Ways',
+        abbrev: 'SW',
+        upDown: false,
+        dashed: true,
+    },
+    {
+        kind: 'bbom',
+        label: 'Big Ball of Mud',
+        abbrev: 'BBoM',
+        upDown: false,
+        dashed: true,
+    },
 ];
 /**
  * Context Map cloud (Big Ball of Mud / general-purpose boundary). The canvas
@@ -64,7 +159,10 @@ function buildCloud() {
     for (let i = 0; i < N; i++) {
         const t = (i / N) * Math.PI * 2;
         const r = 0.4 + 0.05 * Math.sin(6 * t) + 0.03 * Math.sin(3 * t + 0.8);
-        pts.push([clamp(0.5 + r * Math.cos(t)), clamp(0.5 + r * 0.6 * Math.sin(t))]);
+        pts.push([
+            clamp(0.5 + r * Math.cos(t)),
+            clamp(0.5 + r * 0.6 * Math.sin(t)),
+        ]);
     }
     return pts;
 }
@@ -72,7 +170,12 @@ export const CLOUD_VERTICES = buildCloud();
 export const CLOUD = { w: 180, h: 120, fill: '#f0eef6', stroke: '#6d6e71' };
 /** Team Topologies interaction modes (placeable markers + Notation legend). */
 export const TEAM_TOPOLOGIES = [
-    { kind: 'collaboration', label: 'Collaboration', letter: 'C', fill: '#99ff99' },
+    {
+        kind: 'collaboration',
+        label: 'Collaboration',
+        letter: 'C',
+        fill: '#99ff99',
+    },
     { kind: 'xaas', label: 'X-as-a-Service', letter: 'X', fill: '#66b2ff' },
     { kind: 'facilitating', label: 'Facilitating', letter: 'F', fill: '#ffd84d' },
 ];

package/dist/shared/legend-auto.d.ts

@@ -0,0 +1,118 @@
+import { Bound } from '@formicoidea/labre-core/global/gfx';
+import type { BlockStdScope } from '@formicoidea/labre-core/std';
+import { type GfxController, type RoleDefs, type RoleId } from '@formicoidea/labre-core/std/gfx';
+import { type LegendRow, type LegendSection } from './prefabs.js';
+/**
+ * The AUTOMATIC legend, shared by the three DDD backgrounds.
+ *
+ * Wardley's `createWardleyLegend` is the gesture this replicates — select the
+ * background, press one button, get a legend of what is actually drawn on it,
+ * dropped bottom-left and grouped so it can be moved and edited like anything
+ * else. Two things are deliberately NOT replicated:
+ *
+ * - **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;
+ * - **the glyphs are the DDD house prefab** ({@link addLegend}), not hand-drawn
+ *   element-by-element replicas of the artefacts. The three DDD frameworks
+ *   already document themselves with swatch rows, and a second visual language
+ *   for the same job would be one too many.
+ *
+ * A framework contributes nothing but a TABLE: which role puts which row in the
+ * legend. Everything else — scanning the perimeter, resolving specialisations,
+ * dropping empty sections, placing and grouping the box — happens here once.
+ */
+/**
+ * One candidate row: `row` is listed only when `role` — or a role that
+ * specialises it — is carried by an element inside the background's perimeter.
+ */
+export interface AutoLegendEntry {
+    role: RoleId;
+    row: LegendRow;
+    /**
+     * Match `role` and `role` ALONE, without the specialisation walk.
+     *
+     * The default — an entry lights up for any of its children — is what a legend
+     * usually wants: one "Relation" row covers the twenty-two verbs, one
+     * "Sub-domain" row would cover the five kinds. It is also what a validation
+     * rule wants, and for the same reason: a statement about a family is a
+     * statement about every member of it.
+     *
+     * A legend sometimes wants the opposite, because it documents what is DRAWN
+     * rather than what is meant. EDGY's four base kinds are the case: Content
+     * specialises Object, so an entry on `edgy:object` would put an "Object" row
+     * on a board where nobody ever dropped a bare Object — the row would name a
+     * white square that is nowhere on the diagram. `exact` makes the base and its
+     * specialisations two separate statements, so each is listed when, and only
+     * when, it is the thing the user actually put down.
+     *
+     * Reach for it when a row's swatch would be a lie on a board carrying only
+     * children — a distinct colour, a distinct shape, a distinct wording. Leave it
+     * off when the parent row is a fair summary of the whole family.
+     */
+    exact?: boolean;
+}
+export interface AutoLegendSectionSpec {
+    /** Sub-title, dropped along with the section when none of its rows appear. */
+    title?: string;
+    entries: readonly AutoLegendEntry[];
+}
+export interface AutoLegendSpec {
+    /**
+     * Box title. The three DDD tools all say "Legend" (PO recette, 26/08/2026:
+     * the boxes used to be titled in French, which was the one label in the
+     * library that was — identifiers and fallback wordings are English here, and
+     * the day a host ships a locale pack it translates a key, not a leftover).
+     */
+    title: string;
+    width?: number;
+    /**
+     * The framework's role vocabulary, so a present role is matched against an
+     * entry's role THROUGH the specialisation chain: an entry written on a parent
+     * role lists itself as soon as any of its children is on the board — unless
+     * it asks for {@link AutoLegendEntry.exact}, which is the whole of the
+     * exception.
+     */
+    roles: RoleDefs;
+    sections: readonly AutoLegendSectionSpec[];
+}
+/**
+ * The framework's OWN wording for a role, from the vocabulary that declares it.
+ *
+ * A legend row about `es:flow` says "Flow" because that is what the role def
+ * says it is called — the table below never restates a label the vocabulary
+ * already owns, so renaming a role renames its legend row.
+ */
+export declare function roleLabel(roles: RoleDefs, id: RoleId): 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.
+ */
+export declare function rolesInBound(gfx: GfxController, bound: Bound): Set<RoleId>;
+/**
+ * The sections to draw for a given set of present roles: every entry whose role
+ * is present (directly or through a specialisation, unless the entry asks for
+ * {@link AutoLegendEntry.exact}), in declaration order, with empty sections —
+ * sub-title included — dropped.
+ *
+ * When nothing is recognised the result is an EMPTY array, and the caller still
+ * draws the box: that is Wardley's behaviour (an empty map yields a framed
+ * "Legend" title and no rows), and it is the honest one — 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 autoLegendSections(present: ReadonlySet<RoleId>, spec: AutoLegendSpec): LegendSection[];
+/**
+ * Build the legend of what is drawn inside `background` and drop it bottom-left
+ * of it, grouped and selected.
+ *
+ * Returns the group id, or `undefined` when there is no surface to draw on.
+ */
+export declare function createAutoLegend(std: BlockStdScope, background: {
+    xywh: string;
+}, spec: AutoLegendSpec): string | undefined;

package/dist/shared/legend-auto.js

@@ -0,0 +1,79 @@
+import { Bound } from '@formicoidea/labre-core/global/gfx';
+import { GfxControllerIdentifier, roleIsA, } from '@formicoidea/labre-core/std/gfx';
+import { addLegend, measureLegend, } from './prefabs.js';
+/**
+ * The framework's OWN wording for a role, from the vocabulary that declares it.
+ *
+ * A legend row about `es:flow` says "Flow" because that is what the role def
+ * says it is called — the table below never restates a label the vocabulary
+ * already owns, so renaming a role renames its legend row.
+ */
+export function roleLabel(roles, id) {
+    return roles[id]?.labelFallback ?? id;
+}
+/**
+ * Distance from the background's left edge / bottom edge, in model units.
+ * Wardley's numbers, kept identical so the two gestures put the box in the same
+ * place relative to their backgrounds.
+ */
+const INSET_X = 50;
+const INSET_BOTTOM = 56;
+/**
+ * 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.
+ */
+export function rolesInBound(gfx, bound) {
+    const present = new Set();
+    for (const el of gfx.getElementsByBound(bound, { type: 'canvas' })) {
+        if (el.role !== undefined)
+            present.add(el.role);
+    }
+    return present;
+}
+/**
+ * The sections to draw for a given set of present roles: every entry whose role
+ * is present (directly or through a specialisation, unless the entry asks for
+ * {@link AutoLegendEntry.exact}), in declaration order, with empty sections —
+ * sub-title included — dropped.
+ *
+ * When nothing is recognised the result is an EMPTY array, and the caller still
+ * draws the box: that is Wardley's behaviour (an empty map yields a framed
+ * "Legend" title and no rows), and it is the honest one — a legend of a board
+ * with nothing on it lists nothing, rather than inventing the full notation the
+ * user has not used.
+ */
+export function autoLegendSections(present, spec) {
+    const sections = [];
+    for (const section of spec.sections) {
+        const rows = section.entries
+            .filter(entry => entry.exact
+            ? present.has(entry.role)
+            : [...present].some(role => roleIsA(role, entry.role, spec.roles)))
+            .map(entry => entry.row);
+        if (rows.length)
+            sections.push({ title: section.title, rows });
+    }
+    return sections;
+}
+/**
+ * Build the legend of what is drawn inside `background` and drop it bottom-left
+ * of it, grouped and selected.
+ *
+ * Returns the group id, or `undefined` when there is no surface to draw on.
+ */
+export function createAutoLegend(std, background, spec) {
+    const gfx = std.get(GfxControllerIdentifier);
+    const surface = gfx.surface;
+    if (!surface)
+        return undefined;
+    const bound = Bound.deserialize(background.xywh);
+    const sections = autoLegendSections(rolesInBound(gfx, bound), spec);
+    const { height } = measureLegend(sections, spec.width);
+    std.store.captureSync();
+    const id = addLegend(surface, std, bound.x + INSET_X, bound.y + bound.h - INSET_BOTTOM - height, { title: spec.title, sections, width: spec.width });
+    gfx.selection.set({ elements: [id], editing: false });
+    return id;
+}

package/dist/shared/prefabs.d.ts

@@ -30,15 +30,23 @@ export declare function addSticky(surface: Surface, std: BlockStdScope, cx: numb
     label: string;
     shapeType?: 'rect' | 'diamond';
     size?: number;
+    /**
+     * Stamped on the FACE, never on the shadow: the face is the artefact — it
+     * is what carries the words, what a connector attaches to and what the
+     * grammar rules read. The shadow is ink.
+     */
+    role?: string;
 }): string;
 /**
  * A Context Map bounded-context bubble: a rounded pill whose label is the
  * pill's own shape text in `overflow` fit mode (fixed pill, fixed font — a
  * long context name may spill out rather than deform the map).
  */
-export declare function addBubble(surface: Surface, cx: number, cy: number, label: string): string;
+export declare function addBubble(surface: Surface, cx: number, cy: number, label: string, role?: string): string;
 /** A Core Domain dot (sub-domain / bounded context); optional label to its right. */
-export declare function addDot(surface: Surface, std: BlockStdScope, cx: number, cy: number, fill: string, label?: string): string;
+export declare function addDot(surface: Surface, std: BlockStdScope, cx: number, cy: number, fill: string, label?: string, 
+/** Stamped on the ELLIPSE, never on the group: the dot is the artefact. */
+role?: string): string;
 /** A free-floating label. */
 export declare function addLabel(surface: Surface, cx: number, cy: number, label: string, align?: 'left' | 'center', color?: string): string;
 /** A relationship connector (the single connector unit reused for all patterns). */
@@ -47,12 +55,22 @@ export declare function addConnector(surface: Surface, x1: number, y1: number, x
     dashed?: boolean;
     stroke?: string;
     strokeWidth?: number;
+    /** Edge role; `undefined` leaves the connector a neutral line. */
+    role?: string;
 }): string;
-/** A Team Topologies interaction-mode marker: a coloured square + centred letter. */
+/**
+ * A Team Topologies interaction-mode marker: a coloured square + centred letter.
+ *
+ * The role rides on the SQUARE, never on the group — the same call as
+ * {@link addDot}: the square is the artefact, the letter is its glyph and the
+ * word beside it is a caption. `undefined` writes nothing, so a caller that
+ * passes none keeps producing the neutral drawing it always did.
+ */
 export declare function addMarker(surface: Surface, std: BlockStdScope, cx: number, cy: number, opts: {
     fill: string;
     letter: string;
     label?: string;
+    role?: string;
 }): string;
 /** A cloud (Big Ball of Mud / general-purpose boundary): a smoothed closed bezier polygon. */
 export declare function addCloud(surface: Surface, std: BlockStdScope, cx: number, cy: number, label?: string): string;
@@ -71,13 +89,32 @@ export interface LegendRow {
     color: string;
     letter?: string;
     label: string;
+    /**
+     * `line` swatches only: draw the sample as two short segments rather than one
+     * bar, so a dashed pattern (Separate Ways, Big Ball of Mud, a Core Domain
+     * movement) reads in the legend the way it reads on the board. A legend that
+     * showed a solid bar for a dashed link would be telling a small lie about the
+     * notation it documents.
+     */
+    dashed?: boolean;
 }
 export interface LegendSection {
     title?: string;
     rows: LegendRow[];
 }
 /**
- * A boxed legend: a bordered container with a bold "Légende" title and bold
+ * How big the box {@link addLegend} would draw for these sections is — without
+ * drawing it. The auto-legend needs the height to drop the box bottom-left of a
+ * background, and measuring is the only honest way to get it: the box grows with
+ * the number of sub-titles and rows, which is exactly what the detection pass
+ * decides.
+ */
+export declare function measureLegend(sections: readonly LegendSection[], width?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * A boxed legend: a bordered container with a bold "Legend" title and bold
  * section sub-titles, each row a swatch (dot / square+letter / line) + label.
  * Shared by the Core Domain and Context Map tools. Returns the grouped id.
  */

package/dist/shared/prefabs.js

@@ -30,9 +30,11 @@ export function groupIds(std, ids) {
     return result.groupId || ids[0];
 }
 function addShape(surface, x, y, w, h, opts) {
-    const { shapeType = 'rect', fill, stroke = NO_STROKE, strokeWidth = 0, radius = 0, label } = opts;
+    const { shapeType = 'rect', fill, stroke = NO_STROKE, strokeWidth = 0, radius = 0, label, role, } = opts;
     return surface.addElement({
         type: 'shape',
+        // `undefined` writes nothing: a neutral artefact keeps no `role` key.
+        role,
         shapeType,
         filled: true,
         fillColor: fill,
@@ -74,7 +76,7 @@ function addText(surface, x, y, w, text, color, fontFamily, fontSize, textAlign
  * text element; they keep working untouched.)
  */
 export function addSticky(surface, std, cx, cy, opts) {
-    const { fill, text, label, shapeType = 'rect', size = STICKY_SIZE } = opts;
+    const { fill, text, label, shapeType = 'rect', size = STICKY_SIZE, role, } = opts;
     const half = size / 2;
     const radius = shapeType === 'rect' ? STICKY_RADIUS : 0;
     const shadow = addShape(surface, cx - half + SHADOW_OFFSET, cy - half + SHADOW_OFFSET, size, size, {
@@ -86,6 +88,7 @@ export function addSticky(surface, std, cx, cy, opts) {
         shapeType,
         fill,
         radius,
+        role,
         label: {
             text: label,
             color: text,
@@ -101,13 +104,14 @@ export function addSticky(surface, std, cx, cy, opts) {
  * pill's own shape text in `overflow` fit mode (fixed pill, fixed font — a
  * long context name may spill out rather than deform the map).
  */
-export function addBubble(surface, cx, cy, label) {
+export function addBubble(surface, cx, cy, label, role) {
     const { w, h, radius, fill, stroke, text } = CM_BUBBLE;
     return addShape(surface, cx - w / 2, cy - h / 2, w, h, {
         fill,
         stroke,
         strokeWidth: 1.5,
         radius,
+        role,
         label: {
             text: label,
             color: text,
@@ -118,13 +122,16 @@ export function addBubble(surface, cx, cy, label) {
     });
 }
 /** A Core Domain dot (sub-domain / bounded context); optional label to its right. */
-export function addDot(surface, std, cx, cy, fill, label) {
+export function addDot(surface, std, cx, cy, fill, label, 
+/** Stamped on the ELLIPSE, never on the group: the dot is the artefact. */
+role) {
     const d = DOT_SIZE;
     const dot = addShape(surface, cx - d / 2, cy - d / 2, d, d, {
         shapeType: 'ellipse',
         fill,
         stroke: '#1f2328',
         strokeWidth: 1.5,
+        role,
     });
     if (!label)
         return dot;
@@ -137,9 +144,10 @@ export function addLabel(surface, cx, cy, label, align = 'center', color = LABEL
 }
 /** A relationship connector (the single connector unit reused for all patterns). */
 export function addConnector(surface, x1, y1, x2, y2, opts = {}) {
-    const { rearArrow = false, dashed = false, stroke = LABEL_COLOR, strokeWidth = 2 } = opts;
+    const { rearArrow = false, dashed = false, stroke = LABEL_COLOR, strokeWidth = 2, role, } = opts;
     return surface.addElement({
         type: 'connector',
+        role,
         mode: ConnectorMode.Straight,
         stroke,
         strokeWidth,
@@ -150,15 +158,23 @@ export function addConnector(surface, x1, y1, x2, y2, opts = {}) {
         target: { position: [x2, y2] },
     });
 }
-/** A Team Topologies interaction-mode marker: a coloured square + centred letter. */
+/**
+ * A Team Topologies interaction-mode marker: a coloured square + centred letter.
+ *
+ * The role rides on the SQUARE, never on the group — the same call as
+ * {@link addDot}: the square is the artefact, the letter is its glyph and the
+ * word beside it is a caption. `undefined` writes nothing, so a caller that
+ * passes none keeps producing the neutral drawing it always did.
+ */
 export function addMarker(surface, std, cx, cy, opts) {
-    const { fill, letter, label } = opts;
+    const { fill, letter, label, role } = opts;
     const s = MARKER_SIZE;
     const box = addShape(surface, cx - s / 2, cy - s / 2, s, s, {
         fill,
         stroke: '#1f2328',
         strokeWidth: 1.5,
         radius: 4,
+        role,
     });
     const glyph = addText(surface, cx - s / 2, cy - 9, s, letter, '#1f2328', LABEL_FONT, 15);
     const ids = [box, glyph];
@@ -213,25 +229,48 @@ export function addRelationship(surface, std, cx, cy, preset) {
     return groupIds(std, ids);
 }
 /**
- * A boxed legend: a bordered container with a bold "Légende" title and bold
- * section sub-titles, each row a swatch (dot / square+letter / line) + label.
- * Shared by the Core Domain and Context Map tools. Returns the grouped id.
+ * The legend box's geometry, in one place because two callers need it: the one
+ * that DRAWS the box and the one that has to know how tall it will be before
+ * drawing it (see {@link measureLegend}).
  */
-export function addLegend(surface, std, x, y, opts) {
-    const W = opts.width ?? 260;
-    const PAD = 16;
-    const TITLE_H = 32;
-    const SUB_H = 26;
-    const ROW_H = 28;
-    const SW = 16;
+const LEGEND_METRICS = {
+    DEFAULT_W: 260,
+    PAD: 16,
+    TITLE_H: 32,
+    SUB_H: 26,
+    ROW_H: 28,
+    /** Swatch side (a `line` swatch is this long). */
+    SW: 16,
+};
+/**
+ * How big the box {@link addLegend} would draw for these sections is — without
+ * drawing it. The auto-legend needs the height to drop the box bottom-left of a
+ * background, and measuring is the only honest way to get it: the box grows with
+ * the number of sub-titles and rows, which is exactly what the detection pass
+ * decides.
+ */
+export function measureLegend(sections, width) {
+    const { DEFAULT_W, PAD, TITLE_H, SUB_H, ROW_H } = LEGEND_METRICS;
     let subs = 0;
     let rows = 0;
-    for (const s of opts.sections) {
+    for (const s of sections) {
         if (s.title)
             subs++;
         rows += s.rows.length;
     }
-    const H = PAD * 2 + TITLE_H + subs * SUB_H + rows * ROW_H;
+    return {
+        width: width ?? DEFAULT_W,
+        height: PAD * 2 + TITLE_H + subs * SUB_H + rows * ROW_H,
+    };
+}
+/**
+ * A boxed legend: a bordered container with a bold "Legend" title and bold
+ * section sub-titles, each row a swatch (dot / square+letter / line) + label.
+ * Shared by the Core Domain and Context Map tools. Returns the grouped id.
+ */
+export function addLegend(surface, std, x, y, opts) {
+    const { PAD, TITLE_H, SUB_H, ROW_H, SW } = LEGEND_METRICS;
+    const { width: W, height: H } = measureLegend(opts.sections, opts.width);
     const ids = [
         addShape(surface, x, y, W, H, {
             fill: '#ffffff',
@@ -252,13 +291,36 @@ export function addLegend(surface, std, x, y, opts) {
             const sx = x + PAD;
             const midY = cy + ROW_H / 2;
             if (row.swatch === 'dot') {
-                ids.push(addShape(surface, sx, midY - SW / 2, SW, SW, { shapeType: 'ellipse', fill: row.color, stroke: '#1f2328', strokeWidth: 1 }));
+                ids.push(addShape(surface, sx, midY - SW / 2, SW, SW, {
+                    shapeType: 'ellipse',
+                    fill: row.color,
+                    stroke: '#1f2328',
+                    strokeWidth: 1,
+                }));
             }
             else if (row.swatch === 'square') {
-                ids.push(addShape(surface, sx, midY - SW / 2, SW, SW, { fill: row.color, stroke: '#1f2328', strokeWidth: 1, radius: 3 }));
+                ids.push(addShape(surface, sx, midY - SW / 2, SW, SW, {
+                    fill: row.color,
+                    stroke: '#1f2328',
+                    strokeWidth: 1,
+                    radius: 3,
+                }));
                 if (row.letter)
                     ids.push(addText(surface, sx, midY - 8, SW, row.letter, '#1f2328', LABEL_FONT, 11));
             }
+            else if (row.dashed) {
+                // Two 6-unit segments with a 4-unit gap: the same 16 units as a solid
+                // bar, read as a dash.
+                const seg = 6;
+                ids.push(addShape(surface, sx, midY - 2, seg, 4, {
+                    fill: row.color,
+                    radius: 1,
+                }));
+                ids.push(addShape(surface, sx + SW - seg, midY - 2, seg, 4, {
+                    fill: row.color,
+                    radius: 1,
+                }));
+            }
             else {
                 ids.push(addShape(surface, sx, midY - 2, SW, 4, { fill: row.color, radius: 1 }));
             }

package/dist/templates/components.js

@@ -10,7 +10,12 @@ import { CD_SUBDOMAINS, CLOUD, CLOUD_VERTICES, CM_BUBBLE, CM_RELATIONSHIPS, ES_H
 const ATTRS = 'width="100%" height="100%" viewBox="0 0 135 80" xmlns="http://www.w3.org/2000/svg"';
 const NO_STROKE = '#00000000';
 function tpl(name, preview, elements) {
-    return { name, type: 'template', preview, content: makeTemplateSnapshot(elements, name) };
+    return {
+        name,
+        type: 'template',
+        preview,
+        content: makeTemplateSnapshot(elements, name),
+    };
 }
 function stickyEl(fill, text, label, shapeType) {
     return {
@@ -38,7 +43,9 @@ const mk = (c, l) => `<svg ${ATTRS}><rect x="48" y="20" width="40" height="40" r
 const line = (dashed, arrow) => `<svg ${ATTRS} fill="none"><path d="M20 40 H${arrow ? 100 : 115}" stroke="#1f2328" stroke-width="2" stroke-dasharray="${dashed ? '5 4' : '0'}"/>${arrow ? '<path d="M98 32 L114 40 L98 48" stroke="#1f2328" stroke-width="2"/>' : ''}</svg>`;
 /** Event Storming: one template per sticky kind + the hotspot. */
 export const ES_TEMPLATES = [
-    ...ES_STICKIES.map(p => tpl(`Event Storming — ${p.label}`, sq(p.fill), { s: stickyEl(p.fill, p.text, p.label, 'rect') })),
+    ...ES_STICKIES.map(p => tpl(`Event Storming — ${p.label}`, sq(p.fill), {
+        s: stickyEl(p.fill, p.text, p.label, 'rect'),
+    })),
     tpl('Event Storming — Hotspot', dia(ES_HOTSPOT.fill), {
         s: stickyEl(ES_HOTSPOT.fill, ES_HOTSPOT.text, ES_HOTSPOT.label, 'diamond'),
     }),

package/dist/toolbar/icons.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Contextual-toolbar glyph — "generate the legend of what is on this
+ * background". One icon for the three DDD backgrounds because it is one
+ * gesture; the Core Domain chart has drawn this exact box-and-rows since its
+ * legend button shipped, and the two boards now borrow it rather than each
+ * redrawing a lookalike.
+ *
+ * `html` rather than `svg`: a toolbar action's `icon` is rendered as a standalone
+ * template, unlike the senior-button glyphs above which are interpolated into an
+ * outer `<svg>`.
+ */
+export declare const dddLegendIcon: import("lit-html").TemplateResult<1>;
 /** Senior-button glyph — Event Storming (overlapping stickies). */
 export declare const eventStormingToolbarIcon: import("lit-html").TemplateResult<2>;
 /** Senior-button glyph — Core Domain Chart (axes + bands). */

package/dist/toolbar/icons.js

@@ -1,4 +1,35 @@
-import { svg } from 'lit';
+import { html, svg } from 'lit';
+/**
+ * Contextual-toolbar glyph — "generate the legend of what is on this
+ * background". One icon for the three DDD backgrounds because it is one
+ * gesture; the Core Domain chart has drawn this exact box-and-rows since its
+ * legend button shipped, and the two boards now borrow it rather than each
+ * redrawing a lookalike.
+ *
+ * `html` rather than `svg`: a toolbar action's `icon` is rendered as a standalone
+ * template, unlike the senior-button glyphs above which are interpolated into an
+ * outer `<svg>`.
+ */
+export const dddLegendIcon = 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>`;
 /** Senior-button glyph — Event Storming (overlapping stickies). */
 export const eventStormingToolbarIcon = svg `<svg width="100%" height="100%" viewBox="0 0 56 56" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect x="10" y="14" width="22" height="22" rx="2" transform="rotate(-6 21 25)" fill="#F5963B"/>

package/dist/toolbar/senior-buttons.d.ts

@@ -13,6 +13,8 @@ export declare abstract class DddSeniorButtonBase extends DddSeniorButtonBase_ba
     type: typeof EmptyTool;
     protected abstract menuTag: keyof HTMLElementTagNameMap;
     protected abstract label: string;
+    /** i18n key resolved through the host catalogue; `label` is the fallback. */
+    protected abstract labelKey: string;
     protected abstract icon: TemplateResult;
     private _toggleMenu;
     render(): TemplateResult<1>;

package/dist/toolbar/senior-buttons.js

@@ -1,5 +1,6 @@
 import { DefaultTool } from '@formicoidea/labre-core/blocks/surface';
 import { EmptyTool } from '@formicoidea/labre-core/gfx/pointer';
+import { translateKey } from '@formicoidea/labre-core/shared/services';
 import { EdgelessToolbarToolMixin } from '@formicoidea/labre-core/widgets/edgeless-toolbar';
 import { SignalWatcher } from '@formicoidea/labre-core/global/lit';
 import { css, html, LitElement } from 'lit';
@@ -65,7 +66,9 @@ export class DddSeniorButtonBase extends EdgelessToolbarToolMixin(SignalWatcher(
     render() {
         return html `<edgeless-toolbar-button
       class="ddd-button"
-      .tooltip=${this.popper ? '' : this.label}
+      .tooltip=${this.popper
+            ? ''
+            : translateKey(this.edgeless.std, this.labelKey, this.label)}
       .tooltipOffset=${4}
       .active=${!!this.popper}
       @click=${this._toggleMenu}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-ddd-shared",
   "description": "Labre ddd-shared — shared building blocks for @formicoidea/labre-core frameworks.",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",
@@ -19,7 +19,7 @@
     "dist"
   ],
   "dependencies": {
-    "@formicoidea/labre-core": "0.32.0",
+    "@formicoidea/labre-core": "0.33.0",
     "lit": "^3.2.0"
   }
 }