@formicoidea/labre-framework-wardley 0.34.2 → 0.36.0

package/dist/legend.js

@@ -3,7 +3,8 @@ import { ConnectorElementModel, ConnectorMode, FontFamily, PointStyle, ShapeElem
 import { Bound } from '@formicoidea/labre-core/global/gfx';
 import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
 import { GRADIENT_GREEN, GRADIENT_RED } from './gradient.js';
-import { INERTIA_COLOR, LINK_GREY, LINK_STROKE_WIDTH, MARKET_DOT_STROKE_WIDTH, MARKET_LINK_COLOR, MARKET_LINK_WIDTH, METHOD_FILL, NODE_FILL, NODE_STROKE, NODE_STROKE_WIDTH, PIPELINE_FILL, WARDLEY_RED, } from './node/consts.js';
+import { ACCELERATOR_FILL, ACCELERATOR_STROKE_WIDTH, ACCELERATOR_VERTICES, AREA_FILL, AREA_STROKE, AREA_STROKE_WIDTH, DECELERATOR_VERTICES, INERTIA_COLOR, LINK_GREY, LINK_STROKE_WIDTH, MARKET_DOT_STROKE_WIDTH, MARKET_LINK_COLOR, MARKET_LINK_WIDTH, METHOD_FILL, NODE_FILL, NODE_STROKE, NODE_STROKE_WIDTH, PIPELINE_FILL, PORTER_DEFAULT_LETTER, WARDLEY_RED, } from './node/consts.js';
+import { wardleyPorterArrowProps, wardleyPorterArrows } from './presets.js';
 const LEGEND_ORDER = [
     'component',
     'anchor',
@@ -14,6 +15,10 @@ const LEGEND_ORDER = [
     'link',
     'arrow',
     'inertia',
+    'porter',
+    'accelerator',
+    'decelerator',
+    'area',
 ];
 /** Default (editable) descriptions for each legend row. */
 const LEGEND_DESC = {
@@ -26,6 +31,10 @@ const LEGEND_DESC = {
     link: 'Need relation (parent → child)',
     arrow: 'Evolution / movement (red = future)',
     inertia: 'Inertia to change',
+    porter: "Porter's forces (external competition: R relative, L survival, E establish)",
+    accelerator: 'Accelerator (speeds evolution up)',
+    decelerator: 'Decelerator (slows evolution down)',
+    area: 'Area (zone of the map)',
 };
 /** Gradient-meaning block, keyed by variant (caption + 2-colour swatch). */
 const LEGEND_GRADIENT = {
@@ -42,11 +51,105 @@ const LEGEND_GRADIENT = {
         swatch: ['#9aa0a6', '#cfd2d6'],
     },
 };
+/* ── Porter's five forces: the panel under the rows ───────────────────── */
+/** The panel's own numbers. Model units, like every other measure here. */
+const PORTER_PANEL = {
+    pad: 12,
+    titleFs: 16,
+    titleH: 22,
+    /** Between the title and the diagram, and between the diagram and caption. */
+    gapAfterTitle: 8,
+    gapBeforeCaption: 10,
+    /** The glyph's radius — half the map's, so the panel reads as a diagram. */
+    radius: 15,
+    /** Clearance between the arrow tips and the boxes they point at. */
+    clearance: 4,
+    /** The three letters, drawn on the glyph's centre as a free text. */
+    letterFs: 9,
+    boxFs: 12,
+    sideW: 150,
+    sideH: 34,
+    endW: 170,
+    endH: 24,
+    captionFs: 13,
+    captionH: 21,
+    backing: '#e5e7eb',
+    backingStroke: '#9aa0a6',
+};
+/** The four forces the boxes name, north first and then clockwise. */
+const PORTER_FORCES = [
+    'Threat of new entrants',
+    'Bargaining power of customers',
+    'Threat of substitutes',
+    'Bargaining power of suppliers',
+];
+/** What the panel's own glyph reads: the notation, not one force. */
+const PORTER_PANEL_LETTERS = 'R/L/E';
+/** What the letters mean, spelled out under the diagram. */
+const PORTER_CAPTION = 'R/L/E = Relative competition, or struggLe for survival, or struggle to Establish';
+/**
+ * How far a porter glyph of the given radius reaches, arrow tips included.
+ *
+ * DERIVED from the shared geometry rather than written down: the boxes must
+ * stand clear of the arrows, and the day somebody lengthens `PORTER_ARROW` a
+ * hard-coded 38 here would silently let a tip enter a box.
+ */
+function porterReach(radius) {
+    return Math.max(...wardleyPorterArrows(0, 0, radius).flatMap(arrow => {
+        const [x, y, w, h] = Bound.deserialize(arrow.xywh).toXYWH();
+        return [Math.abs(x), Math.abs(y), Math.abs(x + w), Math.abs(y + h)];
+    }));
+}
+/**
+ * The panel's geometry for a given width — the PO's reference drawing, as
+ * numbers.
+ *
+ * A pure function so the layout can be asserted without a surface, and so the
+ * one thing that must hold — that none of the four boxes overlaps the glyph
+ * they surround — is checkable rather than eyeballed.
+ */
+export function porterPanelLayout(w) {
+    const p = PORTER_PANEL;
+    const inner = w - p.pad * 2;
+    // Where a box's near edge sits: past the arrow tips, never on them.
+    const clear = porterReach(p.radius) + p.clearance;
+    const diagramH = (clear + p.endH) * 2;
+    const cx = w / 2;
+    const cy = p.pad + p.titleH + p.gapAfterTitle + diagramH / 2;
+    const captionY = cy + diagramH / 2 + p.gapBeforeCaption;
+    return {
+        w,
+        h: captionY + p.captionH + p.pad,
+        title: [p.pad, p.pad, inner, p.titleH],
+        center: [cx, cy],
+        radius: p.radius,
+        boxes: [
+            {
+                xywh: [cx - p.endW / 2, cy - clear - p.endH, p.endW, p.endH],
+                label: PORTER_FORCES[0],
+            },
+            {
+                xywh: [cx + clear, cy - p.sideH / 2, p.sideW, p.sideH],
+                label: PORTER_FORCES[1],
+            },
+            {
+                xywh: [cx - p.endW / 2, cy + clear, p.endW, p.endH],
+                label: PORTER_FORCES[2],
+            },
+            {
+                xywh: [cx - clear - p.sideW, cy - p.sideH / 2, p.sideW, p.sideH],
+                label: PORTER_FORCES[3],
+            },
+        ],
+        caption: [p.pad, captionY, inner, p.captionH],
+    };
+}
 /**
  * Build a "Legend" group from real, editable elements (white rect frame +
  * "Legend" text + one row of [real component glyph + description text] per
  * Wardley component TYPE present inside the background's perimeter + a
- * gradient-meaning block when the background is a gradient variant). A snapshot
+ * gradient-meaning block when the background is a gradient variant + the
+ * five-forces panel when a Porter's-forces glyph is on the map). A snapshot
  * is created on each call; everything is grouped so it can be moved / resized /
  * edited and is dropped bottom-left of the background.
  */
@@ -77,6 +180,13 @@ export function createWardleyLegend(std, bg) {
             // market triangle connectors (NODE_STROKE) are ignored.
         }
         else if (el instanceof ShapeElementModel) {
+            // The inertia bar is the only plain shape this legend describes, and it
+            // is recognised by its FILL. A Porter's-forces arrow is a plain shape too
+            // — a filled red polygon, the glyph's own wiring — and it is `WARDLEY_RED`
+            // rather than `INERTIA_COLOR`, so it falls through here and is described
+            // by the porter circle it belongs to. Asserted in `porter.unit.spec.ts`:
+            // an arrow that started answering this test would put an "Inertia to
+            // change" row in the legend of a map with no inertia bar on it.
             if (el.fillColor === INERTIA_COLOR)
                 present.add('inertia');
         }
@@ -97,7 +207,13 @@ export function createWardleyLegend(std, bg) {
     const variant = bg.variant;
     const grad = variant !== 'classic' ? LEGEND_GRADIENT[variant] : null;
     const gradH = grad ? 12 + GRAD_ROW_H : 0;
-    const H = PAD * 2 + TITLE_H + rows.length * ROW_H + gradH;
+    // The five-forces panel, and ONLY when a force is actually on the map: a
+    // legend of a map with no porter on it has to come out byte-identical to the
+    // one it came out as before this panel existed. Pinned in
+    // `porter.unit.spec.ts`.
+    const panel = present.has('porter') ? porterPanelLayout(W - PAD * 2) : null;
+    const panelH = panel ? 12 + panel.h : 0;
+    const H = PAD * 2 + TITLE_H + rows.length * ROW_H + gradH + panelH;
     const x0 = bx + 50;
     const y0 = by + bh - 56 - H;
     const text = (t, x, y, w, h, fontSize, align = 'left') => surface.addElement({
@@ -240,6 +356,94 @@ export function createWardleyLegend(std, bg) {
                 }));
                 return [circle, ...dots, ...conns];
             }
+            case 'porter': {
+                // The same drawing as the map's, at the row's scale: the helper scales
+                // the gap, the shaft and the head with the radius, so what a reader
+                // sees here is a small Porter and not a circle with four map-sized
+                // spikes through it.
+                //
+                // 6 and not the 8 the other circles get, because this glyph is the only
+                // one wider than its own circle: arrows included it spans
+                // `2 * (R + (gap + length) * R / 30)`, which at 8 would overrun a row
+                // 30 units tall. At 6 it comes to just over `ROW_H` and sits inside its
+                // line — and it is a RATIO, so the PO's doubling of the map glyph left
+                // this row exactly where it was.
+                const R = 6;
+                const FS = 8;
+                const circle = surface.addElement({
+                    type: 'wardleyNode',
+                    kind: 'porter',
+                    shapeType: 'ellipse',
+                    filled: true,
+                    fillColor: NODE_FILL,
+                    strokeColor: NODE_STROKE,
+                    strokeWidth: NODE_STROKE_WIDTH,
+                    shapeStyle: ShapeStyle.General,
+                    roughness: 0,
+                    xywh: new Bound(cx - R, cy - R, R * 2, R * 2).serialize(),
+                });
+                const arrows = wardleyPorterArrows(cx, cy, R).map(arrow => surface.addElement(wardleyPorterArrowProps(arrow)));
+                // The letter is the notation, so a legend that dropped it would be
+                // describing a circle rather than the glyph it stands for — but here it
+                // is a SEPARATE text element rather than the circle's inner text, which
+                // is what the map glyph uses. A shape lays its text out inside padding
+                // (`SHAPE_TEXT_VERTICAL_PADDING`) larger than this 12-unit box, so at
+                // font size 8 the character was pushed out under the circle (recette
+                // v2). A free text has no padding to overflow, and its box is placed on
+                // the circle's own centre. Role-less like every other legend glyph.
+                const letter = text(PORTER_DEFAULT_LETTER, cx - R, cy - FS / 2 - 1, R * 2, FS + 2, FS, 'center');
+                return [circle, ...arrows, letter];
+            }
+            case 'accelerator':
+            case 'decelerator': {
+                // The map's own outline, at the row's scale: `vertices` are normalized
+                // to the box, so the SAME seven points draw a 30 × 18 legend arrow and
+                // a 48 × 40 canvas one. Role-less like every glyph in this box — a
+                // legend documents the map, it is not part of it.
+                const gw = 30;
+                const gh = 18;
+                return [
+                    surface.addElement({
+                        type: 'wardleyNode',
+                        kind: type,
+                        shapeType: 'polygon',
+                        vertices: (type === 'accelerator'
+                            ? ACCELERATOR_VERTICES
+                            : DECELERATOR_VERTICES).map(([vx, vy]) => [vx, vy]),
+                        isClosed: true,
+                        filled: true,
+                        fillColor: ACCELERATOR_FILL,
+                        strokeColor: NODE_STROKE,
+                        strokeWidth: ACCELERATOR_STROKE_WIDTH,
+                        shapeStyle: ShapeStyle.General,
+                        roughness: 0,
+                        xywh: new Bound(cx - gw / 2, cy - gh / 2, gw, gh).serialize(),
+                    }),
+                ];
+            }
+            case 'area': {
+                // A small translucent rect, and the rect even when the map's zones are
+                // polygons: the row says what a ZONE is, and the number of corners is
+                // the author's choice rather than part of the notation. Same wash and
+                // same rim as the canvas draws, so the swatch is recognisable.
+                const gw = 34;
+                const gh = 20;
+                return [
+                    surface.addElement({
+                        type: 'wardleyNode',
+                        kind: 'area',
+                        shapeType: 'rect',
+                        filled: true,
+                        fillColor: AREA_FILL,
+                        strokeColor: AREA_STROKE,
+                        strokeWidth: AREA_STROKE_WIDTH,
+                        shapeStyle: ShapeStyle.General,
+                        roughness: 0,
+                        radius: 0,
+                        xywh: new Bound(cx - gw / 2, cy - gh / 2, gw, gh).serialize(),
+                    }),
+                ];
+            }
             case 'link':
                 return [
                     surface.addElement({
@@ -331,6 +535,76 @@ export function createWardleyLegend(std, bg) {
         });
         ids.push(text(grad.caption, x0 + PAD + GLYPH_W + GAP, cyRow - GRAD_ROW_H / 2, TEXT_W, GRAD_ROW_H, TEXT_FS));
     }
+    // Porter's five forces: the panel the PO's reference draws, under everything
+    // else. It is not a row — a row says what a glyph IS, and this says what the
+    // notation MEANS: four named pressures around one circle, and the three
+    // letters spelled out. Only drawn when a force is on the map, so a legend
+    // without one is the legend it always was.
+    if (panel) {
+        const px = x0 + PAD;
+        const py = ry + gradH + 12;
+        const p = PORTER_PANEL;
+        // The backing: square-cornered and grey, so the panel reads as a figure
+        // set into the legend rather than as one more entry in it.
+        ids.push(surface.addElement({
+            type: 'shape',
+            shapeType: 'rect',
+            filled: true,
+            fillColor: p.backing,
+            strokeColor: p.backingStroke,
+            strokeWidth: 1,
+            shapeStyle: ShapeStyle.General,
+            roughness: 0,
+            radius: 0,
+            xywh: new Bound(px, py, panel.w, panel.h).serialize(),
+        }));
+        const [tx, ty, tw, th] = panel.title;
+        ids.push(text("Porter's five forces", px + tx, py + ty, tw, th, p.titleFs));
+        const [cx, cy] = panel.center;
+        ids.push(surface.addElement({
+            type: 'wardleyNode',
+            kind: 'porter',
+            shapeType: 'ellipse',
+            filled: true,
+            fillColor: NODE_FILL,
+            strokeColor: NODE_STROKE,
+            strokeWidth: NODE_STROKE_WIDTH,
+            shapeStyle: ShapeStyle.General,
+            roughness: 0,
+            xywh: new Bound(px + cx - panel.radius, py + cy - panel.radius, panel.radius * 2, panel.radius * 2).serialize(),
+        }));
+        for (const arrow of wardleyPorterArrows(px + cx, py + cy, panel.radius)) {
+            ids.push(surface.addElement(wardleyPorterArrowProps(arrow)));
+        }
+        // All three letters at once: this circle stands for the NOTATION rather
+        // than for one force, so picking one of them would make the panel say that
+        // a Porter is an R.
+        //
+        // A SEPARATE text element, like the porter row above and for the same
+        // reason (recette v2): a shape lays its text out inside a padding
+        // (`SHAPE_TEXT_PADDING`) wider than this 30-unit circle, so the characters
+        // would be pushed outside it. A free text has no padding to overflow, and
+        // its box is placed on the circle's own centre.
+        ids.push(text(PORTER_PANEL_LETTERS, px + cx - panel.radius, py + cy - p.letterFs / 2 - 1, panel.radius * 2, p.letterFs + 2, p.letterFs, 'center'));
+        for (const box of panel.boxes) {
+            const [bx, by, bw, bh] = box.xywh;
+            ids.push(surface.addElement({
+                type: 'shape',
+                shapeType: 'rect',
+                filled: true,
+                fillColor: '#ffffff',
+                strokeColor: NODE_STROKE,
+                strokeWidth: 1,
+                shapeStyle: ShapeStyle.General,
+                roughness: 0,
+                radius: 0,
+                xywh: new Bound(px + bx, py + by, bw, bh).serialize(),
+            }));
+            ids.push(text(box.label, px + bx + 4, py + by + 3, bw - 8, bh - 6, p.boxFs, 'center'));
+        }
+        const [capX, capY, capW, capH] = panel.caption;
+        ids.push(text(PORTER_CAPTION, px + capX, py + capY, capW, capH, p.captionFs, 'center'));
+    }
     // 4. Group everything and select it.
     const [, result] = std.command.exec(createGroupCommand, { elements: ids });
     gfx.selection.set({

package/dist/morph.d.ts

@@ -0,0 +1,129 @@
+import { type MorphSpec } from '@formicoidea/labre-core/blocks/surface';
+import { WardleyNodeElementModel } from '@formicoidea/labre-core/model';
+import type { GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+/**
+ * What a Wardley artefact may BECOME — the declaration behind the "Change type"
+ * dropdown on a selected component's contextual toolbar.
+ *
+ * ## One family, and why it is exactly these four
+ *
+ * A component, a market, an ecosystem and a pipeline are four ways of saying
+ * the SAME thing: something the value chain depends on. The map's own reading
+ * agrees — `roles.ts` makes `market` and `ecosystem` children of `component` in
+ * the role tree — and the modelling gesture the morph exists for is the one
+ * every mapper makes: you draw a component, you look at the map, and you
+ * realise that what you drew is a market of many suppliers, or a whole
+ * ecosystem, or a pipeline of choices. Today that costs a delete, a re-draw,
+ * every dependency re-attached and the name typed again.
+ *
+ * The family is DATA and nothing derives it — the same call BPMN and C4 make.
+ * Deriving it from `roleIsA` would have been wrong in both directions here: it
+ * would reach from market to component and not back, and it would say nothing
+ * at all about the pipeline, which is not a specialisation of anything and is
+ * still the fourth way of drawing the same claim.
+ *
+ * ## The two kinds deliberately left out
+ *
+ * - **`anchor`** is the user, and the need they have. It is a role of its own
+ *   precisely because it is NOT a component (`roles.ts`): it is what the value
+ *   chain hangs from, not a link in it. A menu offering "turn this user into a
+ *   pipeline" would invite a map with no anchor at all — the one thing a
+ *   Wardley map cannot be read without.
+ * - **`method`** is not an artefact but an annotation ON one: the coloured ring
+ *   says how a component is being BUILT (buy / build / outsource), and its fill
+ *   encodes the choice. Morphing it away would silently discard that decision,
+ *   and morphing into it would have to invent one.
+ *
+ * `handle` is in no family either, and does not need excluding by name: it is
+ * not an artefact at all, so nothing selects it and {@link wardleyNodeOfComponent}
+ * never resolves to one.
+ */
+export declare const WARDLEY_MORPH_FAMILIES: readonly (readonly WardleyMorphKind[])[];
+/** The kinds this framework offers as morph targets. */
+export type WardleyMorphKind = 'component' | 'market' | 'ecosystem' | 'pipeline';
+/**
+ * The `wardleyNode` a selected GROUP is the artefact of — `undefined` when the
+ * group is not one.
+ *
+ * Every Wardley artefact in this family is a composite: a component is a circle
+ * and its label, a market adds three dots and a triangle, and a pipeline is a
+ * body plus a handle plus a label in a nested group. So what a click selects is
+ * the outer group, and what carries `kind` is one node inside it — RECURSIVELY
+ * inside it, because the pipeline's own creation nests.
+ *
+ * Three conditions, and each one excludes a piece of the notation rather than
+ * an accident:
+ *
+ * - a `WardleyNodeElementModel`, which leaves out the labels and the connectors;
+ * - with a ROLE, which leaves out the market's three neutral dots — they are the
+ *   glyph's wiring and carry none by construction (`presets.ts`);
+ * - whose kind is in the family, which leaves out the pipeline's `handle` and
+ *   any `anchor` or `method` somebody grouped in beside the artefact.
+ *
+ * TWO candidates is a REFUSAL rather than a first-wins pick, exactly as C4's
+ * resolution refuses a group of two components: morphing "it" would mean
+ * picking one by document order, and the honest answer to an ambiguous
+ * selection is nothing at all. A plain lasso round three shapes, a C4 component
+ * and a group of two Wardley components all answer `undefined`, so none of them
+ * is ever offered the menu.
+ */
+export declare function wardleyNodeOfComponent(model: GfxPrimitiveElementModel): WardleyNodeElementModel | undefined;
+/**
+ * The name an artefact should carry once it has morphed — or `null` when the
+ * name is the AUTHOR's and must not be touched.
+ *
+ * Exactly one case rewrites: the label is the source kind's own creation
+ * prompt, letter for letter, which is what an artefact nobody has named still
+ * says. Everything else — a name typed over it, the prompt with a word added, a
+ * cleared label, another kind's prompt — is content, and content survives a
+ * morph untouched. The same timid rule `c4MorphedTitle` states, and for the same
+ * reason: a morph may not take away words somebody put on the picture.
+ *
+ * Pure and total over every string: the input is a canvas text element somebody
+ * may have typed anything into.
+ */
+export declare function wardleyMorphedLabel(from: WardleyMorphKind, to: WardleyMorphKind, rawText: string | null | undefined): string | null;
+/**
+ * Everything the morph owes a Wardley composite beyond the props patch — the
+ * `afterMorph` half of the spec, run inside the generic module's one
+ * `captureSync` so all of it is a single ctrl+z.
+ *
+ * ## The geometry, and why this framework writes it
+ *
+ * A DEVIATION from BPMN and C4, decided by the PO: those two keep the box the
+ * user gave the element, because there a size is a preference. Here it is the
+ * NOTATION. A market is drawn bigger than a component so a reader can tell them
+ * apart at a glance, an ecosystem bigger again, and a pipeline is a 120-wide bar
+ * — a market left at a component's 18 pixels is an unreadable smudge with three
+ * dots crammed into it. So the target's canonical size is applied, CENTRED on
+ * where the artefact already stands: the thing does not move, it becomes the
+ * size its notation says it is. The label keeps its own place, which is the
+ * user's.
+ *
+ * ## And why the rest is here rather than in the patch
+ *
+ * Because a market IS its three dots and a pipeline IS its handle. A patch can
+ * write `kind: 'market'` onto a circle and the result is a circle that claims to
+ * be a market and does not look like one; a patch cannot create an element, nor
+ * move a connector somebody drew. That is exactly what `afterMorph` is for, and
+ * the ORDER below is the whole of the care it needs: the glyph the artefact is
+ * LEAVING comes apart before the one it is arriving at is built, so a
+ * market → pipeline never has three dots and a handle at once.
+ */
+export declare function wardleyMorphComposite(selected: GfxPrimitiveElementModel, from: WardleyMorphKind, to: WardleyMorphKind): void;
+/**
+ * Wardley's morph declaration, handed to the generic `morphToolbarConfig`.
+ *
+ * `modelType` is the native `GroupElementModel` and not
+ * `WardleyNodeElementModel`, because every artefact in this family is a
+ * composite and the group is what a click on one selects. Everything that makes
+ * that safe is in {@link wardleyNodeOfComponent}: the toolbar's own homogeneity
+ * test only proves that each selected element is A group, and the resolution
+ * proves that each one is one of OURS.
+ *
+ * `propsOf` is the shipped creation builder minus `type` / `xywh` / `text`
+ * ({@link wardleyMorphProps}), so the palette and the morph cannot disagree
+ * about what a pipeline looks like, and `clearOf` removes the keys the target
+ * does not write — `radius`, which only the pipeline has.
+ */
+export declare const WARDLEY_MORPH_SPEC: MorphSpec<WardleyMorphKind>;