@formicoidea/labre-ddd-shared 0.58.0 → 0.60.0

package/dist/headless.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@labre/affine-gfx-ddd-shared/headless` — the DDD tables and the pure
+ * element builders, with no editor behind them (`docs/adr/0045`): what a
+ * board's `./interchange` toolbox builds a sticky, a bubble, a dot, a marker,
+ * a cloud or a relationship from. The package index re-exports every one of
+ * these unchanged.
+ *
+ * Held by `interchange-headless.unit.spec.ts` in `packages/affine/all`: add
+ * only from files that import nothing but the headless entries of core
+ * (`@labre/global`, `@labre/affine-model/headless`,
+ * `@labre/affine-shared/headless`, `@labre/affine-block-surface/interchange`).
+ */
+export * from './shared/consts.js';
+export * from './shared/elements.js';

package/dist/headless.js

@@ -0,0 +1,14 @@
+/**
+ * `@labre/affine-gfx-ddd-shared/headless` — the DDD tables and the pure
+ * element builders, with no editor behind them (`docs/adr/0045`): what a
+ * board's `./interchange` toolbox builds a sticky, a bubble, a dot, a marker,
+ * a cloud or a relationship from. The package index re-exports every one of
+ * these unchanged.
+ *
+ * Held by `interchange-headless.unit.spec.ts` in `packages/affine/all`: add
+ * only from files that import nothing but the headless entries of core
+ * (`@labre/global`, `@labre/affine-model/headless`,
+ * `@labre/affine-shared/headless`, `@labre/affine-block-surface/interchange`).
+ */
+export * from './shared/consts.js';
+export * from './shared/elements.js';

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './shared/consts.js';
+export * from './shared/elements.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/elements.js';
 export * from './shared/prefabs.js';
 export * from './shared/utils.js';
 export * from './toolbar/icons.js';

package/dist/shared/consts.d.ts

@@ -18,6 +18,12 @@
  * second key here for the same English word would only be the drift the
  * manifest guard exists to catch.
  */
+/**
+ * The boards' chrome font. Declared here rather than in `utils.ts`, which
+ * re-exports the editor's `refScale`, so the editor-free entry (`headless.ts`)
+ * can carry it to a board's declaration.
+ */
+export declare const FONT_FAMILY = "Inter, sans-serif";
 /** Square sticky side (px, canvas reference). */
 export declare const STICKY_SIZE = 120;
 /** Faux drop-shadow offset + colour (a plain offset rect behind the sticky). */
@@ -229,4 +235,4 @@ export declare const MOVEMENT_COLOR = "#ff3333";
  * three values — one declaration, so a DDD caption and the legend line that
  * explains it cannot drift apart.
  */
-export { LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, } from '@formicoidea/labre-core/blocks/surface';
+export { LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, } from '@formicoidea/labre-core/interchange';

package/dist/shared/consts.js

@@ -1,4 +1,4 @@
-import { NOTATION_NEUTRALS } from '@formicoidea/labre-core/shared/consts';
+import { NOTATION_NEUTRALS } from '@formicoidea/labre-core/shared/headless';
 /**
  * Shared DDD palette and sizes. Every tool composes the same irreducible units
  * (sticky, dot, bubble, connector, label) from these presets — no duplicated
@@ -19,6 +19,12 @@ import { NOTATION_NEUTRALS } from '@formicoidea/labre-core/shared/consts';
  * second key here for the same English word would only be the drift the
  * manifest guard exists to catch.
  */
+/**
+ * The boards' chrome font. Declared here rather than in `utils.ts`, which
+ * re-exports the editor's `refScale`, so the editor-free entry (`headless.ts`)
+ * can carry it to a board's declaration.
+ */
+export const FONT_FAMILY = 'Inter, sans-serif';
 /** Square sticky side (px, canvas reference). */
 export const STICKY_SIZE = 120;
 /** Faux drop-shadow offset + colour (a plain offset rect behind the sticky). */
@@ -221,4 +227,4 @@ export const MOVEMENT_COLOR = '#ff3333';
  * three values — one declaration, so a DDD caption and the legend line that
  * explains it cannot drift apart.
  */
-export { LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, } from '@formicoidea/labre-core/blocks/surface';
+export { LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, } from '@formicoidea/labre-core/interchange';

package/dist/shared/elements.d.ts

@@ -0,0 +1,109 @@
+import type { SerializedElementProps, ToolboxPoint } from '@formicoidea/labre-core/interchange';
+import { TextFitMode } from '@formicoidea/labre-core/model/headless';
+export interface ShapeOpts {
+    shapeType?: 'rect' | 'ellipse' | 'diamond';
+    fill: string;
+    /**
+     * Semantic role (`<framework>:<role>`) stamped on the shape, so a validation
+     * rule can recognise it. `undefined` writes NOTHING — no `role` key is
+     * persisted and the artefact stays a neutral drawing, which is what every
+     * caller that does not pass one keeps getting and what every DDD artefact
+     * created before this parameter existed already is.
+     */
+    role?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    radius?: number;
+    /**
+     * Shape-owned centred label. The text belongs to the shape itself (edited
+     * by double-click, moves/resizes with it) with the given text-fit mode —
+     * `contained` mimics a physical post-it.
+     */
+    label?: {
+        text: string;
+        color: string;
+        fontFamily: string;
+        fontSize: number;
+        fit: TextFitMode;
+    };
+}
+/**
+ * The props a DDD shape is CREATED with, its label's text as a string. The
+ * prefabs' `dddShapeProps` is this with the text as a `Y.Text`.
+ */
+export declare function dddShapeElement(x: number, y: number, w: number, h: number, opts: ShapeOpts): SerializedElementProps;
+/**
+ * What a Core Domain DOT is, as shape options — read by the builder below and
+ * by the morph, so the two can never disagree about what a platform
+ * sub-domain looks like.
+ */
+export declare function dotShapeOpts(fill: string, role?: string): ShapeOpts;
+/** What a Team Topologies MARKER square is, the same way. */
+export declare function markerShapeOpts(fill: string, role?: string): ShapeOpts;
+export interface StickyOpts {
+    fill: string;
+    text: string;
+    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;
+}
+/**
+ * A post-it whose face is at `at`: the faux-shadow rect, the coloured face
+ * whose label is its OWN shape text in `contained` fit mode, and their group.
+ */
+export declare function stickyElements(at: ToolboxPoint, opts: StickyOpts, local?: string): SerializedElementProps[];
+/**
+ * A Context Map bounded-context bubble at `at`: 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 bubbleElement(at: ToolboxPoint, label: string, role?: string, local?: string): SerializedElementProps;
+/**
+ * A Core Domain dot at `at`; with a label, the caption to its right and the
+ * group of the two. The role rides on the ELLIPSE, never on the group.
+ */
+export declare function dotElements(at: ToolboxPoint, fill: string, label?: string, role?: string, local?: string): SerializedElementProps[];
+export interface MarkerOpts {
+    fill: string;
+    letter: string;
+    label?: string;
+    role?: string;
+}
+/**
+ * A Team Topologies interaction-mode marker whose square is at `at`: the
+ * square, its centred letter, the caption beside it when given, and the group.
+ * The role rides on the SQUARE: the letter is its glyph and the word beside it
+ * is a caption.
+ */
+export declare function markerElements(at: ToolboxPoint, opts: MarkerOpts, local?: string): SerializedElementProps[];
+/**
+ * A cloud (Big Ball of Mud / general-purpose boundary) at `at`: a dense
+ * closed polygon; with a label, the text across it and the group of the two.
+ * The role rides on the POLYGON, never on the group: the polygon is what a
+ * relationship binds to and what the legend scan meets.
+ */
+export declare function cloudElements(at: ToolboxPoint, label?: string, role?: string, local?: string): SerializedElementProps[];
+/** A connector end: an element (or local) id, or a free point. */
+export type DddConnectorEnd = {
+    id: string;
+} | {
+    position: [number, number];
+};
+export interface DddConnectorOpts {
+    rearArrow?: boolean;
+    dashed?: boolean;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Edge role; `undefined` leaves the connector a neutral line. */
+    role?: string;
+    /** The words riding on the line; none when absent or blank. */
+    label?: string;
+}
+/** A relationship connector (the single connector unit reused for all patterns). */
+export declare function dddConnectorElement(source: DddConnectorEnd, target: DddConnectorEnd, opts?: DddConnectorOpts): SerializedElementProps;

package/dist/shared/elements.js

@@ -0,0 +1,240 @@
+import { ConnectorMode, FontWeight, PointStyle, ShapeStyle, StrokeStyle, TextFitMode, } from '@formicoidea/labre-core/model/headless';
+import { NOTATION_NEUTRALS } from '@formicoidea/labre-core/shared/headless';
+import { Bound } from '@formicoidea/labre-core/global/gfx';
+import { CLOUD, CLOUD_VERTICES, CM_BUBBLE, DOT_SIZE, LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, MARKER_SIZE, SHADOW_COLOR, SHADOW_OFFSET, STICKY_FONT, STICKY_FONT_SIZE, STICKY_RADIUS, STICKY_SIZE, } from './consts.js';
+/**
+ * The DDD artefacts as PURE builders (`docs/adr/0045`): the elements a
+ * sticky, a bubble, a dot, a marker, a cloud or a relationship is made of, as
+ * serialized props, with no editor behind them. The prefabs (`prefabs.ts`)
+ * write these through `surface.addElement`, and each board's toolbox (its
+ * `./interchange` entry) hands them to a host with no editor — one assembly
+ * per artefact, shared by the three boards, which is what this package is for.
+ *
+ * The contract is a reader's (ADR 0012 D3): painting order, LOCAL ids, each
+ * composite's members before the group that holds them, the group last. `at`
+ * is the top-left of the artefact's own box (the sticky's face, the dot, the
+ * marker's square); a caption written beside it lies outside that box.
+ *
+ * A builder writes the text it is given and never translates it: the seed in
+ * the host's language is resolved by the editor's creation site (ADR 0023).
+ * A shape's text is a plain string here; the shape model turns it into a
+ * `Y.Text` on `addElement` (`ShapeElementModel.propsToY`), so the stored
+ * element is the same whichever side built it.
+ */
+const NO_STROKE = '#00000000';
+/** The ink every Core Domain artefact is outlined with: the shared scale's. */
+const ARTEFACT_STROKE = NOTATION_NEUTRALS.ink;
+/**
+ * The props a DDD shape is CREATED with, its label's text as a string. The
+ * prefabs' `dddShapeProps` is this with the text as a `Y.Text`.
+ */
+export function dddShapeElement(x, y, w, h, opts) {
+    const { shapeType = 'rect', fill, stroke = NO_STROKE, strokeWidth = 0, radius = 0, label, role, } = opts;
+    return {
+        type: 'shape',
+        // `undefined` writes nothing: a neutral artefact keeps no `role` key.
+        role,
+        shapeType,
+        filled: true,
+        fillColor: fill,
+        strokeColor: stroke,
+        strokeWidth,
+        shapeStyle: ShapeStyle.General,
+        roughness: 0,
+        radius,
+        xywh: new Bound(x, y, w, h).serialize(),
+        ...(label
+            ? {
+                text: label.text,
+                color: label.color,
+                fontFamily: label.fontFamily,
+                fontSize: label.fontSize,
+                textAlign: 'center',
+                textFitMode: label.fit,
+            }
+            : {}),
+    };
+}
+/** A canvas TEXT element: a caption beside an artefact, or a marker's letter. */
+function textElement(id, x, y, w, text, color, fontFamily, fontSize, textAlign = 'center') {
+    return {
+        type: 'text',
+        id,
+        text,
+        color,
+        fontFamily,
+        fontSize,
+        textAlign,
+        fontWeight: FontWeight.Regular,
+        xywh: new Bound(x, y, w, fontSize + 10).serialize(),
+    };
+}
+/** The group holding `members`, written after them. */
+function groupOf(id, members) {
+    return {
+        type: 'group',
+        id,
+        children: Object.fromEntries(members.map(m => [m.id, true])),
+    };
+}
+/**
+ * What a Core Domain DOT is, as shape options — read by the builder below and
+ * by the morph, so the two can never disagree about what a platform
+ * sub-domain looks like.
+ */
+export function dotShapeOpts(fill, role) {
+    return {
+        shapeType: 'ellipse',
+        fill,
+        stroke: ARTEFACT_STROKE,
+        strokeWidth: 1.5,
+        role,
+    };
+}
+/** What a Team Topologies MARKER square is, the same way. */
+export function markerShapeOpts(fill, role) {
+    return {
+        fill,
+        stroke: ARTEFACT_STROKE,
+        strokeWidth: 1.5,
+        radius: 4,
+        role,
+    };
+}
+/**
+ * A post-it whose face is at `at`: the faux-shadow rect, the coloured face
+ * whose label is its OWN shape text in `contained` fit mode, and their group.
+ */
+export function stickyElements(at, opts, local = 'sticky') {
+    const { fill, text, label, shapeType = 'rect', size = STICKY_SIZE, role, } = opts;
+    const radius = shapeType === 'rect' ? STICKY_RADIUS : 0;
+    const members = [
+        {
+            ...dddShapeElement(at.x + SHADOW_OFFSET, at.y + SHADOW_OFFSET, size, size, { shapeType, fill: SHADOW_COLOR, radius }),
+            id: `${local}:shadow`,
+        },
+        {
+            ...dddShapeElement(at.x, at.y, size, size, {
+                shapeType,
+                fill,
+                radius,
+                role,
+                label: {
+                    text: label,
+                    color: text,
+                    fontFamily: STICKY_FONT,
+                    fontSize: STICKY_FONT_SIZE,
+                    fit: TextFitMode.Contained,
+                },
+            }),
+            id: `${local}:face`,
+        },
+    ];
+    return [...members, groupOf(`${local}:group`, members)];
+}
+/**
+ * A Context Map bounded-context bubble at `at`: 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 function bubbleElement(at, label, role, local = 'bubble') {
+    const { w, h, radius, fill, stroke, text } = CM_BUBBLE;
+    return {
+        ...dddShapeElement(at.x, at.y, w, h, {
+            fill,
+            stroke,
+            strokeWidth: 1.5,
+            radius,
+            role,
+            label: {
+                text: label,
+                color: text,
+                fontFamily: LABEL_FONT,
+                fontSize: LABEL_FONT_SIZE,
+                fit: TextFitMode.Overflow,
+            },
+        }),
+        id: local,
+    };
+}
+/**
+ * A Core Domain dot at `at`; with a label, the caption to its right and the
+ * group of the two. The role rides on the ELLIPSE, never on the group.
+ */
+export function dotElements(at, fill, label, role, local = 'dot') {
+    const d = DOT_SIZE;
+    const dot = {
+        ...dddShapeElement(at.x, at.y, d, d, dotShapeOpts(fill, role)),
+        id: `${local}:dot`,
+    };
+    if (!label)
+        return [dot];
+    const caption = textElement(`${local}:caption`, at.x + d + 6, at.y + d / 2 - LABEL_FONT_SIZE / 2, 170, label, LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, 'left');
+    return [dot, caption, groupOf(`${local}:group`, [dot, caption])];
+}
+/**
+ * A Team Topologies interaction-mode marker whose square is at `at`: the
+ * square, its centred letter, the caption beside it when given, and the group.
+ * The role rides on the SQUARE: the letter is its glyph and the word beside it
+ * is a caption.
+ */
+export function markerElements(at, opts, local = 'marker') {
+    const { fill, letter, label, role } = opts;
+    const s = MARKER_SIZE;
+    const members = [
+        {
+            ...dddShapeElement(at.x, at.y, s, s, markerShapeOpts(fill, role)),
+            id: `${local}:square`,
+        },
+        textElement(`${local}:letter`, at.x, at.y + s / 2 - 9, s, letter, NOTATION_NEUTRALS.ink, LABEL_FONT, 15),
+    ];
+    if (label) {
+        members.push(textElement(`${local}:caption`, at.x + s + 6, at.y + s / 2 - LABEL_FONT_SIZE / 2, 150, label, LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, 'left'));
+    }
+    return [...members, groupOf(`${local}:group`, members)];
+}
+/**
+ * A cloud (Big Ball of Mud / general-purpose boundary) at `at`: a dense
+ * closed polygon; with a label, the text across it and the group of the two.
+ * The role rides on the POLYGON, never on the group: the polygon is what a
+ * relationship binds to and what the legend scan meets.
+ */
+export function cloudElements(at, label, role, local = 'cloud') {
+    const { w, h, fill, stroke } = CLOUD;
+    const cloud = {
+        type: 'shape',
+        id: `${local}:cloud`,
+        shapeType: 'polygon',
+        vertices: CLOUD_VERTICES,
+        isClosed: true,
+        filled: true,
+        fillColor: fill,
+        strokeColor: stroke,
+        strokeWidth: 1.5,
+        shapeStyle: ShapeStyle.General,
+        roughness: 0,
+        xywh: new Bound(at.x, at.y, w, h).serialize(),
+        ...(role ? { role } : {}),
+    };
+    if (!label)
+        return [cloud];
+    const caption = textElement(`${local}:caption`, at.x + 12, at.y + h / 2 - LABEL_FONT_SIZE / 2, w - 24, label, NOTATION_NEUTRALS.ink, LABEL_FONT, LABEL_FONT_SIZE);
+    return [cloud, caption, groupOf(`${local}:group`, [cloud, caption])];
+}
+/** A relationship connector (the single connector unit reused for all patterns). */
+export function dddConnectorElement(source, target, opts = {}) {
+    const { rearArrow = false, dashed = false, stroke = LABEL_COLOR, strokeWidth = 2, role, label, } = opts;
+    return {
+        type: 'connector',
+        role,
+        mode: ConnectorMode.Straight,
+        stroke,
+        strokeWidth,
+        strokeStyle: dashed ? StrokeStyle.Dash : StrokeStyle.Solid,
+        frontEndpointStyle: PointStyle.None,
+        rearEndpointStyle: rearArrow ? PointStyle.Arrow : PointStyle.None,
+        source,
+        target,
+        ...(label?.trim() ? { text: label.trim() } : {}),
+    };
+}

package/dist/shared/prefabs.d.ts

@@ -1,11 +1,18 @@
-import { TextFitMode } from '@formicoidea/labre-core/model';
 import type { BlockStdScope } from '@formicoidea/labre-core/std';
 import { type GfxController } from '@formicoidea/labre-core/std/gfx';
+import { type ShapeOpts } from './elements.js';
 /**
  * Irreducible reusable units composed by all three DDD sub-menus. Each helper
- * wraps native `surface.addElement` (shape / text / connector / group); nothing
- * here defines a new element type, so the same builders back Event Storming
- * stickies, Context Map bubbles + relationships and Core Domain dots + arrows.
+ * writes the elements its pure builder returns (`elements.ts`,
+ * `docs/adr/0045`) through native `surface.addElement` (shape / text /
+ * connector) and the group command; nothing here defines a new element type,
+ * so the same builders back Event Storming stickies, Context Map bubbles +
+ * relationships and Core Domain dots + arrows, here and on a host with no
+ * editor.
+ *
+ * What stays here is what only an editor has: the viewport centre the
+ * prefabs are placed around, and the group command, which names the group
+ * ("Group N", resolved in the host's language) and stamps its user layer.
  */
 type Surface = NonNullable<GfxController['surface']>;
 /**
@@ -18,36 +25,9 @@ type Surface = NonNullable<GfxController['surface']>;
 export declare function placeDddElement(std: BlockStdScope, build: (surface: Surface, cx: number, cy: number) => string): void;
 /** Group several element ids; returns the group id (or the first id on failure). */
 export declare function groupIds(std: BlockStdScope, ids: string[]): string;
-export interface ShapeOpts {
-    shapeType?: 'rect' | 'ellipse' | 'diamond';
-    fill: string;
-    /**
-     * Semantic role (`<framework>:<role>`) stamped on the shape, so a validation
-     * rule can recognise it. `undefined` writes NOTHING — no `role` key is
-     * persisted and the artefact stays a neutral drawing, which is what every
-     * caller that does not pass one keeps getting and what every DDD artefact
-     * created before this parameter existed already is.
-     */
-    role?: string;
-    stroke?: string;
-    strokeWidth?: number;
-    radius?: number;
-    /**
-     * Shape-owned centred label. The text belongs to the shape itself (edited
-     * by double-click, moves/resizes with it) with the given text-fit mode —
-     * `contained` mimics a physical post-it.
-     */
-    label?: {
-        text: string;
-        color: string;
-        fontFamily: string;
-        fontSize: number;
-        fit: TextFitMode;
-    };
-}
 /**
- * The props a DDD shape is CREATED with, as a record — the write of
- * {@link addShape}, minus the write.
+ * The props a DDD shape is CREATED with, as a record — the write of the
+ * prefabs, minus the write.
  *
  * Split out for the Core Domain morph, and for the reason C4's `presets.ts`
  * gives: a kind's appearance is written by the preset of the kind it was created
@@ -85,14 +65,6 @@ export declare function addSticky(surface: Surface, std: BlockStdScope, cx: numb
  * long context name may spill out rather than deform the map).
  */
 export declare function addBubble(surface: Surface, cx: number, cy: number, label: string, role?: string): string;
-/**
- * What a Core Domain DOT is, as shape options — read by the creation site below
- * and by the morph, so the two can never disagree about what a platform
- * sub-domain looks like. See {@link dddShapeProps}.
- */
-export declare function dotShapeOpts(fill: string, role?: string): ShapeOpts;
-/** What a Team Topologies MARKER square is, the same way. */
-export declare function markerShapeOpts(fill: string, role?: string): ShapeOpts;
 /** 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, 
 /** Stamped on the ELLIPSE, never on the group: the dot is the artefact. */

package/dist/shared/prefabs.js

@@ -1,12 +1,9 @@
-import { DefaultTool } from '@formicoidea/labre-core/blocks/surface';
+import { DefaultTool, } from '@formicoidea/labre-core/blocks/surface';
 import { createGroupCommand } from '@formicoidea/labre-core/gfx/group';
-import { ConnectorMode, FontWeight, PointStyle, ShapeStyle, StrokeStyle, TextFitMode, } from '@formicoidea/labre-core/model';
-import { NOTATION_NEUTRALS } from '@formicoidea/labre-core/shared/consts';
-import { Bound } from '@formicoidea/labre-core/global/gfx';
 import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
 import * as Y from 'yjs';
-import { CLOUD, CLOUD_VERTICES, CM_BUBBLE, DOT_SIZE, LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, MARKER_SIZE, SHADOW_COLOR, SHADOW_OFFSET, STICKY_FONT, STICKY_FONT_SIZE, STICKY_RADIUS, STICKY_SIZE, } from './consts.js';
-const NO_STROKE = '#00000000';
+import { CLOUD, CM_BUBBLE, DOT_SIZE, MARKER_SIZE, STICKY_SIZE, } from './consts.js';
+import { bubbleElement, cloudElements, dddConnectorElement, dddShapeElement, dotElements, markerElements, stickyElements, } from './elements.js';
 /**
  * Build one DDD artefact at the viewport centre and select it, leaving the
  * palette open so several can be added in a row. This is the old
@@ -31,8 +28,41 @@ export function groupIds(std, ids) {
     return result.groupId || ids[0];
 }
 /**
- * The props a DDD shape is CREATED with, as a record — the write of
- * {@link addShape}, minus the write.
+ * A shape's label as the `Y.Text` the prefabs have always written. The shape
+ * model's `propsToY` makes the same `Y.Text` of a string, so this changes
+ * nothing stored; it keeps what `addElement` receives from a prefab what it
+ * was before the builders existed.
+ */
+function withYText(props) {
+    return props.type === 'shape' && typeof props.text === 'string'
+        ? { ...props, text: new Y.Text(props.text) }
+        : props;
+}
+/**
+ * Write a builder's elements in order, minting real ids for the local ones;
+ * a group goes through the group command with its members' minted ids.
+ * Returns the id of the last element: the group of a composite, the element
+ * itself otherwise.
+ */
+function addElements(surface, std, elements) {
+    const minted = new Map();
+    let last = '';
+    for (const { id: local, ...props } of elements) {
+        if (props.type === 'group' && std) {
+            const children = Object.keys(props.children);
+            last = groupIds(std, children.map(child => minted.get(child) ?? child));
+        }
+        else {
+            last = surface.addElement(withYText(props));
+        }
+        if (typeof local === 'string')
+            minted.set(local, last);
+    }
+    return last;
+}
+/**
+ * The props a DDD shape is CREATED with, as a record — the write of the
+ * prefabs, minus the write.
  *
  * Split out for the Core Domain morph, and for the reason C4's `presets.ts`
  * gives: a kind's appearance is written by the preset of the kind it was created
@@ -42,46 +72,7 @@ export function groupIds(std, ids) {
  * element.
  */
 export function dddShapeProps(x, y, w, h, opts) {
-    const { shapeType = 'rect', fill, stroke = NO_STROKE, strokeWidth = 0, radius = 0, label, role, } = opts;
-    return {
-        type: 'shape',
-        // `undefined` writes nothing: a neutral artefact keeps no `role` key.
-        role,
-        shapeType,
-        filled: true,
-        fillColor: fill,
-        strokeColor: stroke,
-        strokeWidth,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        radius,
-        xywh: new Bound(x, y, w, h).serialize(),
-        ...(label
-            ? {
-                text: new Y.Text(label.text),
-                color: label.color,
-                fontFamily: label.fontFamily,
-                fontSize: label.fontSize,
-                textAlign: 'center',
-                textFitMode: label.fit,
-            }
-            : {}),
-    };
-}
-function addShape(surface, x, y, w, h, opts) {
-    return surface.addElement(dddShapeProps(x, y, w, h, opts));
-}
-function addText(surface, x, y, w, text, color, fontFamily, fontSize, textAlign = 'center', bold = false) {
-    return surface.addElement({
-        type: 'text',
-        text,
-        color,
-        fontFamily,
-        fontSize,
-        textAlign,
-        fontWeight: bold ? FontWeight.SemiBold : FontWeight.Regular,
-        xywh: new Bound(x, y, w, fontSize + 10).serialize(),
-    });
+    return withYText(dddShapeElement(x, y, w, h, opts));
 }
 /**
  * A post-it: faux-shadow rect + coloured face whose label is the face's OWN
@@ -91,28 +82,8 @@ 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, 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, {
-        shapeType,
-        fill: SHADOW_COLOR,
-        radius,
-    });
-    const face = addShape(surface, cx - half, cy - half, size, size, {
-        shapeType,
-        fill,
-        radius,
-        role,
-        label: {
-            text: label,
-            color: text,
-            fontFamily: STICKY_FONT,
-            fontSize: STICKY_FONT_SIZE,
-            fit: TextFitMode.Contained,
-        },
-    });
-    return groupIds(std, [shadow, face]);
+    const half = (opts.size ?? STICKY_SIZE) / 2;
+    return addElements(surface, std, stickyElements({ x: cx - half, y: cy - half }, opts));
 }
 /**
  * A Context Map bounded-context bubble: a rounded pill whose label is the
@@ -120,74 +91,21 @@ export function addSticky(surface, std, cx, cy, opts) {
  * long context name may spill out rather than deform the map).
  */
 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,
-            fontFamily: LABEL_FONT,
-            fontSize: LABEL_FONT_SIZE,
-            fit: TextFitMode.Overflow,
-        },
-    });
-}
-/** The ink every Core Domain artefact is outlined with: the shared scale's. */
-const ARTEFACT_STROKE = NOTATION_NEUTRALS.ink;
-/**
- * What a Core Domain DOT is, as shape options — read by the creation site below
- * and by the morph, so the two can never disagree about what a platform
- * sub-domain looks like. See {@link dddShapeProps}.
- */
-export function dotShapeOpts(fill, role) {
-    return {
-        shapeType: 'ellipse',
-        fill,
-        stroke: ARTEFACT_STROKE,
-        strokeWidth: 1.5,
-        role,
-    };
-}
-/** What a Team Topologies MARKER square is, the same way. */
-export function markerShapeOpts(fill, role) {
-    return {
-        fill,
-        stroke: ARTEFACT_STROKE,
-        strokeWidth: 1.5,
-        radius: 4,
-        role,
-    };
+    const { w, h } = CM_BUBBLE;
+    return addElements(surface, undefined, [
+        bubbleElement({ x: cx - w / 2, y: cy - h / 2 }, label, role),
+    ]);
 }
 /** A Core Domain dot (sub-domain / bounded context); optional label to its right. */
 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, dotShapeOpts(fill, role));
-    if (!label)
-        return dot;
-    const lbl = addText(surface, cx + d / 2 + 6, cy - LABEL_FONT_SIZE / 2, 170, label, LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, 'left');
-    return groupIds(std, [dot, lbl]);
+    return addElements(surface, std, dotElements({ x: cx - d / 2, y: cy - d / 2 }, fill, label, role));
 }
 /** 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, role, } = opts;
-    return surface.addElement({
-        type: 'connector',
-        role,
-        mode: ConnectorMode.Straight,
-        stroke,
-        strokeWidth,
-        strokeStyle: dashed ? StrokeStyle.Dash : StrokeStyle.Solid,
-        frontEndpointStyle: PointStyle.None,
-        rearEndpointStyle: rearArrow ? PointStyle.Arrow : PointStyle.None,
-        source: { position: [x1, y1] },
-        target: { position: [x2, y2] },
-    });
+    return surface.addElement(dddConnectorElement({ position: [x1, y1] }, { position: [x2, y2] }, opts));
 }
 /**
  * A Team Topologies interaction-mode marker: a coloured square + centred letter.
@@ -198,37 +116,11 @@ export function addConnector(surface, x1, y1, x2, y2, opts = {}) {
  * passes none keeps producing the neutral drawing it always did.
  */
 export function addMarker(surface, std, cx, cy, opts) {
-    const { fill, letter, label, role } = opts;
     const s = MARKER_SIZE;
-    const box = addShape(surface, cx - s / 2, cy - s / 2, s, s, markerShapeOpts(fill, role));
-    const glyph = addText(surface, cx - s / 2, cy - 9, s, letter, NOTATION_NEUTRALS.ink, LABEL_FONT, 15);
-    const ids = [box, glyph];
-    if (label) {
-        ids.push(addText(surface, cx + s / 2 + 6, cy - LABEL_FONT_SIZE / 2, 150, label, LABEL_COLOR, LABEL_FONT, LABEL_FONT_SIZE, 'left'));
-    }
-    return groupIds(std, ids);
+    return addElements(surface, std, markerElements({ x: cx - s / 2, y: cy - s / 2 }, opts));
 }
 /** A cloud (Big Ball of Mud / general-purpose boundary): a smoothed closed bezier polygon. */
 export function addCloud(surface, std, cx, cy, label, role) {
-    const { w, h, fill, stroke } = CLOUD;
-    const cloud = surface.addElement({
-        type: 'shape',
-        shapeType: 'polygon',
-        vertices: CLOUD_VERTICES,
-        isClosed: true,
-        filled: true,
-        fillColor: fill,
-        strokeColor: stroke,
-        strokeWidth: 1.5,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        xywh: new Bound(cx - w / 2, cy - h / 2, w, h).serialize(),
-        // On the POLYGON, never on the group: the polygon is what a relationship
-        // binds to and what the legend scan meets.
-        ...(role ? { role } : {}),
-    });
-    if (!label)
-        return cloud;
-    const lbl = addText(surface, cx - w / 2 + 12, cy - LABEL_FONT_SIZE / 2, w - 24, label, NOTATION_NEUTRALS.ink, LABEL_FONT, LABEL_FONT_SIZE);
-    return groupIds(std, [cloud, lbl]);
+    const { w, h } = CLOUD;
+    return addElements(surface, std, cloudElements({ x: cx - w / 2, y: cy - h / 2 }, label, role));
 }

package/dist/shared/utils.d.ts

@@ -5,4 +5,3 @@
  * copied here, and in two other packages besides (R37, one source of truth).
  */
 export { refScale } from '@formicoidea/labre-core/blocks/surface';
-export declare const FONT_FAMILY = "Inter, sans-serif";

package/dist/shared/utils.js

@@ -5,4 +5,3 @@
  * copied here, and in two other packages besides (R37, one source of truth).
  */
 export { refScale } from '@formicoidea/labre-core/blocks/surface';
-export const FONT_FAMILY = 'Inter, sans-serif';

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.58.0",
+  "version": "0.60.0",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",
@@ -13,13 +13,17 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./headless": {
+      "types": "./dist/headless.d.ts",
+      "import": "./dist/headless.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@formicoidea/labre-core": "0.58.0",
+    "@formicoidea/labre-core": "0.60.0",
     "lit": "^3.2.0",
     "yjs": "^13.6.21"
   }