@formicoidea/labre-framework-wardley 0.35.0 → 0.36.0

package/dist/node/consts.js

@@ -98,3 +98,125 @@ export const METHOD = {
     centerRatio: 0.5, // inner white component radius / R
 };
 export const METHOD_LABEL = 'Component';
+/**
+ * Porter's forces (composite): a large white circle carrying ONE letter, pushed
+ * on from the four cardinal directions by solid red arrows.
+ *
+ * Twice the market's diameter, at the PO's recette of #210: this is not a link
+ * in the value chain drawn a little differently, it is a pressure bearing on the
+ * whole map, and it has to read as one at the zoom an architect actually works
+ * at. Every other number here is proportional to it.
+ *
+ * The letter IS the notation — **R** relative competition, **L** struggle for
+ * survival, **E** struggle to establish — which is why it is written as the
+ * shape's own inner text rather than as a label beside it: a double-click opens
+ * the native shape editor on the circle, and typing another letter is the whole
+ * of the edit. It is also why this glyph carries no label at all: the three
+ * words behind the three letters are the map's vocabulary, not a name the
+ * author gives one force.
+ */
+export const PORTER_SIZE = 60;
+/**
+ * The four arrows, read by `wardleyPorterArrows`: each starts `gap` outside the
+ * circle's rim and runs `length` further out, a `width`-wide shaft carrying a
+ * head `headLength` long and `headWidth` across.
+ *
+ * They are drawn as filled POLYGONS rather than as connectors with a triangle
+ * endpoint, and the recette of #210 is why: a connector sizes its head off its
+ * STROKE WIDTH (`DEFAULT_ARROW_SIZE` × strokeWidth / 2), which is a number about
+ * a line rather than about this notation — the head came out longer than the
+ * arrow, swallowed the circle, the letter and the double-click, and the glyph
+ * rendered as a solid red star. A polygon's head is the number written here and
+ * nothing else, at any size.
+ */
+export const PORTER_ARROW = {
+    gap: 6,
+    length: 40,
+    /** Shaft width. */
+    width: 8,
+    headLength: 16,
+    headWidth: 24,
+};
+/** The letter, sized to sit inside the circle without touching the rim. */
+export const PORTER_LETTER_FONT_SIZE = 28;
+/** The letter a fresh glyph opens on: relative competition, the commonest read. */
+export const PORTER_DEFAULT_LETTER = 'R';
+/**
+ * Accelerators and decelerators — the climate annotations.
+ *
+ * A fat solid arrow with a flat grey fill and a thick dark border: as close as
+ * a native polygon gets to the reference's solid arrow, because this canvas has
+ * no gradient fill. The two are the same drawing mirrored — an accelerator
+ * points RIGHT, towards the commodity end of the evolution axis, a decelerator
+ * points LEFT, back towards genesis — and that direction IS the notation, which
+ * is why the outlines are written out below rather than expressed as one shape
+ * plus a `rotate`: a rotated element is one the selection, the resize handles
+ * and every bounding-box reader then have to de-rotate.
+ *
+ * Neither is a link in the value chain, so neither carries a component role
+ * (see `roles.ts`): they say something about the CLIMATE the map is drawn in.
+ */
+export const ACCELERATOR_SIZE = { w: 48, h: 40 };
+/** Flat grey: the arrow is a annotation, and must not out-shout the chain. */
+export const ACCELERATOR_FILL = '#bfbfbf';
+/** A thick dark border — `NODE_STROKE`, like every other artefact's rim. */
+export const ACCELERATOR_STROKE_WIDTH = 2;
+/**
+ * The accelerator's outline, normalized to its box, pointing RIGHT.
+ *
+ * Seven points: the shaft's two left corners, the head's upper barb, the tip,
+ * the head's lower barb, and back along the shaft. `0.55` is where the head
+ * starts, `0.28 / 0.72` the shaft's own edges.
+ */
+export const ACCELERATOR_VERTICES = [
+    [0, 0.28],
+    [0.55, 0.28],
+    [0.55, 0],
+    [1, 0.5],
+    [0.55, 1],
+    [0.55, 0.72],
+    [0, 0.72],
+];
+/** The decelerator: the same outline mirrored `x → 1 − x`, pointing LEFT. */
+export const DECELERATOR_VERTICES = ACCELERATOR_VERTICES.map(([x, y]) => [1 - x, y]);
+export const ACCELERATOR_LABEL = 'Accelerator';
+export const DECELERATOR_LABEL = 'Decelerator';
+/**
+ * Areas — the zones of the map.
+ *
+ * A ring you draw AROUND components to say "all of this is one thing": a
+ * business unit, a team's territory, a scope under discussion. It is not a link
+ * in the value chain and not an annotation of the climate either, which is why
+ * it carries a role with no parent and sits in a category of its own in the
+ * toolbox.
+ *
+ * Two shapes, one kind: a RECT for the common case and a POLYGON for a zone
+ * whose outline has to follow the components it groups (its corners are then
+ * moved from the shape toolbar's vertex editor). The `shapeType` is what says
+ * which, so nothing about an area is a second kind to keep in step.
+ *
+ * A zone is drawn OVER the map it groups, so the fill is the load-bearing
+ * number here: Peace light at ~25 % opacity, which is a wash the components
+ * underneath still read through. The border is the saturated Peace of the same
+ * swatch, thin like every other artefact's rim — the zone must frame the map,
+ * never compete with it.
+ */
+export const AREA_RECT_SIZE = { w: 240, h: 160 };
+/** The polygon is born square: its default outline is a regular pentagon. */
+export const AREA_POLYGON_SIZE = { w: 200, h: 200 };
+/** Peace light at ~25 % opacity — an 8-digit hex, exactly as `PIPELINE_FILL`. */
+export const AREA_FILL = '#c6dbfc40';
+/** Peace, the saturated shade of the same swatch. */
+export const AREA_STROKE = '#5b9cf6';
+export const AREA_STROKE_WIDTH = 1;
+/**
+ * The word the legend describes an area by.
+ *
+ * NOT written into the document: an area is created NAMELESS, so the editor
+ * that a double-click opens starts on an empty line and the first thing typed
+ * is the zone's own name. The other artefacts carry a placeholder because their
+ * name is a text element beside them and an empty one would be invisible; an
+ * area's name is its own inner text, and a placeholder there would be a word
+ * the author has to delete before writing theirs.
+ */
+export const AREA_LABEL = 'Area';

package/dist/node/node-view.d.ts

@@ -1,10 +1,88 @@
+import { ShapeElementView } from '@formicoidea/labre-core/gfx/shape';
 import type { WardleyNodeElementModel } from '@formicoidea/labre-core/model';
-import { GfxElementModelView } from '@formicoidea/labre-core/std/gfx';
 /**
  * View for a Wardley node. Registering it ensures `gfx.view.get(model)` returns
- * a view (required so move / select / connector interactions work). The label
- * is a separate native text element, so no custom editing is needed here.
+ * a view (required so move / select / connector interactions work).
+ *
+ * ## It extends `ShapeElementView`, and that is what makes "Edit vertices" work
+ *
+ * A Wardley node IS a `ShapeElementModel`, and the toolbar's vertex-editing
+ * action ends in `if (view instanceof ShapeElementView) view.enterVertexEditingMode()`.
+ * While this view extended `GfxElementModelView` directly, that check failed
+ * silently: the button was on the row, it was enabled, and clicking it did
+ * nothing at all — found by the recette of #213 on an area polygon, whose
+ * corners are the whole reason to draw one.
+ *
+ * Extending the shape view brings TWO wirings, and this framework wants exactly
+ * one of each. Both are hooks on the base rather than things to dodge by
+ * skipping `onCreated`, because skipping it would drop the wiring that is
+ * wanted along with the wiring that is not.
+ *
+ * ## Double-clicking edits the inner text — on the TWO kinds that have one
+ *
+ * Every other Wardley artefact wears its name as a SEPARATE canvas text element
+ * grouped beside it, so a double-click on the circle has nothing of its own to
+ * open: the words live next door and are edited by double-clicking them, which
+ * is `TextElementView`'s job and not this one's. Those kinds are deliberately
+ * left alone.
+ *
+ * The `porter` is the first exception, and it is the notation that makes it
+ * one. A Porter's-forces glyph carries a LETTER — R relative competition, L
+ * struggle for survival, E struggle to establish — and that letter is the
+ * shape's own inner text, because it is one character in the middle of the
+ * circle rather than a name written alongside it. So the gesture everybody in
+ * this editor already makes has to land: `mountShapeTextEditor`, the same call
+ * EDGY's and BPMN's node views make on their own inner text.
+ *
+ * Found by the recette of #210: the view had no handler at all and the node
+ * toolbar offers no "add text" action, which left the letter unreachable — a
+ * glyph whose whole meaning is one character nobody could change. The four
+ * arrows are polygons OUTSIDE the rim (`presets.ts`), so the double-click at
+ * the centre reaches this circle rather than a connector's oversized head.
+ *
+ * The `area` is the second, and for a different reason: a zone's name belongs
+ * INSIDE the zone rather than beside it — a label parked outside a boundary
+ * would name whatever else happens to be there. It is created with no text at
+ * all, so the double-click opens the editor on an empty line and the first
+ * thing typed is the zone's name (`mountShapeTextEditor` mints the `Y.Text`).
+ *
+ * ## …and only on the artefact, never on its wiring
+ *
+ * The four arrows are `wardleyNode`s too — `kind: 'porter'`, ROLE-LESS, the
+ * market's three inner dots exactly — so `kind` alone would hand each of them
+ * the same editor. The role is what separates the artefact the author placed
+ * from the glyph's own wiring, so it is the second half of the gate, and it is
+ * the half that also makes the gate safe to extend: a kind is admitted with the
+ * role that proves the element is the artefact rather than a part of one.
+ *
+ * That pair is also why they are `wardleyNode`s at all. Recette v2 found them
+ * as plain shapes, and `ShapeElementView` gives EVERY plain shape a
+ * double-click that mounts the inner-text editor: an arrow grew from 24 units
+ * high to 44 the moment one was opened, and the deformation survived Escape. An
+ * arrow is not a thing you write in, and this view is where that is said.
+ *
+ * ## Vertices move on the AREA and nowhere else
+ *
+ * The other wiring. Every other polygon this framework draws has an outline
+ * that IS the notation — an accelerator points right and a decelerator points
+ * left, and a porter's arrow is the glyph's own wiring — so a handle on one can
+ * only turn a statement into a blob. A zone's outline is the opposite: it
+ * exists to follow the components it groups. Declining the hook on every other
+ * kind skips the overlay, the pointer wiring and the toolbar entry together,
+ * which is the same answer the toolbar's own `when` gives.
  */
-export declare class WardleyNodeView extends GfxElementModelView<WardleyNodeElementModel> {
+export declare class WardleyNodeView extends ShapeElementView<WardleyNodeElementModel> {
     static type: string;
+    /**
+     * Only the porter CIRCLE and the area. The kind alone is not enough: the
+     * porter's four arrows share its kind and are told apart by carrying no role,
+     * exactly as the market's inner dots are — hence a table of kind → the role
+     * the ARTEFACT carries, and an element that fails to match is either a glyph's
+     * own wiring or a kind whose name is the text element beside it. Opening the
+     * shape's own editor on those would write a second, invisible name into a
+     * field that must stay empty.
+     */
+    protected editsTextOnDblClick(): boolean;
+    /** The zone, and nothing else this framework draws as a polygon. */
+    protected editsVerticesOnSelection(): boolean;
 }

package/dist/node/node-view.js

@@ -1,9 +1,113 @@
-import { GfxElementModelView } from '@formicoidea/labre-core/std/gfx';
+import { ShapeElementView } from '@formicoidea/labre-core/gfx/shape';
+import { WARDLEY_ROLE } from '../roles.js';
+/**
+ * The kinds whose NAME is the shape's own inner text, each paired with the role
+ * an element of that kind carries when it is the artefact itself.
+ *
+ * A pair and not a list, because `kind` alone admits too much: the porter's
+ * four arrows are `wardleyNode`s of kind `porter` carrying no role at all, and
+ * a gate on the kind would hand each of them an editor for text they must never
+ * have. Anything not in this table is a kind that wears its name as a text
+ * element beside it, and its own inner text must stay empty.
+ */
+const NAMES_ITSELF = {
+    porter: WARDLEY_ROLE.porter,
+    area: WARDLEY_ROLE.area,
+};
 /**
  * View for a Wardley node. Registering it ensures `gfx.view.get(model)` returns
- * a view (required so move / select / connector interactions work). The label
- * is a separate native text element, so no custom editing is needed here.
+ * a view (required so move / select / connector interactions work).
+ *
+ * ## It extends `ShapeElementView`, and that is what makes "Edit vertices" work
+ *
+ * A Wardley node IS a `ShapeElementModel`, and the toolbar's vertex-editing
+ * action ends in `if (view instanceof ShapeElementView) view.enterVertexEditingMode()`.
+ * While this view extended `GfxElementModelView` directly, that check failed
+ * silently: the button was on the row, it was enabled, and clicking it did
+ * nothing at all — found by the recette of #213 on an area polygon, whose
+ * corners are the whole reason to draw one.
+ *
+ * Extending the shape view brings TWO wirings, and this framework wants exactly
+ * one of each. Both are hooks on the base rather than things to dodge by
+ * skipping `onCreated`, because skipping it would drop the wiring that is
+ * wanted along with the wiring that is not.
+ *
+ * ## Double-clicking edits the inner text — on the TWO kinds that have one
+ *
+ * Every other Wardley artefact wears its name as a SEPARATE canvas text element
+ * grouped beside it, so a double-click on the circle has nothing of its own to
+ * open: the words live next door and are edited by double-clicking them, which
+ * is `TextElementView`'s job and not this one's. Those kinds are deliberately
+ * left alone.
+ *
+ * The `porter` is the first exception, and it is the notation that makes it
+ * one. A Porter's-forces glyph carries a LETTER — R relative competition, L
+ * struggle for survival, E struggle to establish — and that letter is the
+ * shape's own inner text, because it is one character in the middle of the
+ * circle rather than a name written alongside it. So the gesture everybody in
+ * this editor already makes has to land: `mountShapeTextEditor`, the same call
+ * EDGY's and BPMN's node views make on their own inner text.
+ *
+ * Found by the recette of #210: the view had no handler at all and the node
+ * toolbar offers no "add text" action, which left the letter unreachable — a
+ * glyph whose whole meaning is one character nobody could change. The four
+ * arrows are polygons OUTSIDE the rim (`presets.ts`), so the double-click at
+ * the centre reaches this circle rather than a connector's oversized head.
+ *
+ * The `area` is the second, and for a different reason: a zone's name belongs
+ * INSIDE the zone rather than beside it — a label parked outside a boundary
+ * would name whatever else happens to be there. It is created with no text at
+ * all, so the double-click opens the editor on an empty line and the first
+ * thing typed is the zone's name (`mountShapeTextEditor` mints the `Y.Text`).
+ *
+ * ## …and only on the artefact, never on its wiring
+ *
+ * The four arrows are `wardleyNode`s too — `kind: 'porter'`, ROLE-LESS, the
+ * market's three inner dots exactly — so `kind` alone would hand each of them
+ * the same editor. The role is what separates the artefact the author placed
+ * from the glyph's own wiring, so it is the second half of the gate, and it is
+ * the half that also makes the gate safe to extend: a kind is admitted with the
+ * role that proves the element is the artefact rather than a part of one.
+ *
+ * That pair is also why they are `wardleyNode`s at all. Recette v2 found them
+ * as plain shapes, and `ShapeElementView` gives EVERY plain shape a
+ * double-click that mounts the inner-text editor: an arrow grew from 24 units
+ * high to 44 the moment one was opened, and the deformation survived Escape. An
+ * arrow is not a thing you write in, and this view is where that is said.
+ *
+ * ## Vertices move on the AREA and nowhere else
+ *
+ * The other wiring. Every other polygon this framework draws has an outline
+ * that IS the notation — an accelerator points right and a decelerator points
+ * left, and a porter's arrow is the glyph's own wiring — so a handle on one can
+ * only turn a statement into a blob. A zone's outline is the opposite: it
+ * exists to follow the components it groups. Declining the hook on every other
+ * kind skips the overlay, the pointer wiring and the toolbar entry together,
+ * which is the same answer the toolbar's own `when` gives.
  */
-export class WardleyNodeView extends GfxElementModelView {
+export class WardleyNodeView extends ShapeElementView {
     static { this.type = 'wardleyNode'; }
+    /**
+     * Only the porter CIRCLE and the area. The kind alone is not enough: the
+     * porter's four arrows share its kind and are told apart by carrying no role,
+     * exactly as the market's inner dots are — hence a table of kind → the role
+     * the ARTEFACT carries, and an element that fails to match is either a glyph's
+     * own wiring or a kind whose name is the text element beside it. Opening the
+     * shape's own editor on those would write a second, invisible name into a
+     * field that must stay empty.
+     */
+    editsTextOnDblClick() {
+        // A read-only document is one nobody names anything on. The base view has
+        // no such check — a plain shape's editor is harmless there — but this gate
+        // is the whole of what a Wardley node offers, so it keeps the guard the
+        // hand-written handler carried.
+        if (this.std.store.readonly)
+            return false;
+        const named = NAMES_ITSELF[this.model.kind];
+        return named !== undefined && this.model.role === named;
+    }
+    /** The zone, and nothing else this framework draws as a polygon. */
+    editsVerticesOnSelection() {
+        return this.model.kind === 'area';
+    }
 }

package/dist/node/porter-watcher.d.ts

@@ -0,0 +1,119 @@
+import { InteractivityExtension } from '@formicoidea/labre-core/std/gfx';
+/**
+ * Keeps a Porter's-forces glyph saying ONE thing: the letter in the circle and
+ * the `wardley:competition` tag on it are two spellings of the same statement.
+ *
+ * ## Why there are two spellings at all
+ *
+ * The letter is the NOTATION — an architect reads `L` off the map and knows
+ * what it says, and typing another letter is the whole of the edit
+ * (`node-view.ts`). The tag is the FACT — the half a rule, a reading or a host
+ * report can query, because nothing can ask "which forces does this map name?"
+ * of a `Y.Text` holding one character. Dropping either would cost something
+ * real, so both exist.
+ *
+ * ## The invariant: the tag is DERIVED from the letter
+ *
+ * The two are not symmetric, and the recette of #211 is what made the asymmetry
+ * necessary. The letter is what the author writes; the tag is a reading of it,
+ * recomputed on EVERY local change of the text and written as a consequence of
+ * that change rather than as a step of its own. So `tag = f(text)` holds at
+ * every instant, including at every instant an undo or a redo passes through.
+ *
+ * That is the fix for the defect the recette found. Reconciling only when the
+ * editor closed left the two able to disagree: the inline editor writes a
+ * select-all-and-retype as several Yjs operations, each its own undo entry,
+ * while the tag was one further entry captured after all of them. Undoing then
+ * landed on an intermediate text — `RR` — carrying the tag of the text that
+ * came after it, and redoing past the tag's own entry re-ran the reconciliation
+ * against a text that had already moved on, so the document never returned to
+ * where it started.
+ *
+ * The reading is taken on a MICROTASK after the change, and written UNTRACKED
+ * (`Store.withoutTransact`, an origin the undo manager ignores). So the undo
+ * stack holds the author's keystrokes and nothing else, and whatever text a
+ * step lands on — `E`, the intermediate `RR`, the original `R` — the tag is
+ * recomputed from it a tick later. There is no entry to get out of order,
+ * because the qualification is not an entry.
+ *
+ * ## Tag → letter, and why it is the quiet direction
+ *
+ * A menu pick is the one gesture that starts from the tag, so it — and only it
+ * — redraws the letter. Two guards keep that from becoming a second author:
+ *
+ * - It compares the two SEMANTICALLY (`competitionOfPorterLetter(raw)`), never
+ *   character by character. A circle reading `e` already says "struggle to
+ *   establish", so a tag derived from it must not turn round and rewrite it to
+ *   `E`. Without this the two directions would trade writes on every keystroke.
+ * - It never runs while the id is in the EDITING set. That is C4's lesson
+ *   (`C4TypeLineWatcher`): rewriting the text an author has their caret in
+ *   throws that caret, and no letter is worth it.
+ *
+ * The one deliberate asymmetry: a CLEARED tag leaves the circle alone. Removing
+ * a value from the menu is a statement about the qualification — "I no longer
+ * claim which force this is" — and not about a map somebody is still reading.
+ * The tie is re-tied by the next edit of the letter, which is the only gesture
+ * that ever asserts one.
+ *
+ * ## `local`, and always-on
+ *
+ * Both directions are LOCAL-only, for `EdgyRelationResolver`'s reason: without
+ * it every peer on a shared board would derive the same tag the moment a letter
+ * synced, giving N−1 of them an entry for a gesture they did not make.
+ *
+ * Registered by the RENDER half rather than the flag-gated one
+ * (`docs/adr/0009`): this creates no element, offers no button and adds no
+ * artefact to any map. It keeps an element ALREADY in the document coherent
+ * with itself, which a force drawn while the Wardley button was on must stay
+ * when the button goes off.
+ */
+export declare class WardleyPorterWatcher extends InteractivityExtension {
+    static key: string;
+    private _selection;
+    private _updated;
+    private _disposeSurface;
+    private _editing;
+    private _pending;
+    private _scheduled;
+    private _mounted;
+    mounted(): void;
+    unmounted(): void;
+    /** The porter this id names, when it is one this peer may rewrite. */
+    private _porter;
+    /**
+     * Queue a re-reading of the letter, for the end of the current task.
+     *
+     * A MICROTASK, and it is load-bearing rather than cosmetic. `watchText` fires
+     * from inside the Yjs transaction that changed the text, and at that instant
+     * the element's own `Y.Map` observer may not have run yet — so `element.tags`
+     * can still resolve, through `_preserved`, to a nested map the very same
+     * transaction has just deleted. A tag written into that map goes nowhere at
+     * all: the recette of #211 saw exactly that, as an undo landing on a letter
+     * whose force had silently failed to follow it.
+     *
+     * Deferring past the transaction settles two things at once. The document is
+     * consistent when the reading is taken, and the write lands OUTSIDE any
+     * tracked transaction — so {@link Store.withoutTransact} really does keep it
+     * off the undo stack, and the tag becomes what it claims to be: a pure
+     * function of the text, recomputed after every change of it, in either
+     * direction of history, and never a step an author has to undo.
+     */
+    private _scheduleDerive;
+    /** The letter as it now stands, written down as the fact it states. */
+    private _deriveTagFromText;
+    /** The value just picked from the menu, drawn as the letter it stands for. */
+    private _drawLetterFromTag;
+}
+/**
+ * The ids currently being EDITED, out of a selection update.
+ *
+ * A pure function because it is the whole of what the watcher needs to know
+ * about the selection: a text editor holds an editing selection for as long as
+ * it is mounted and drops it when it closes, so this set is "whose caret is in
+ * something right now" and nothing else. Total over an empty selection, which
+ * is what arrives when an editor closes onto bare canvas.
+ */
+export declare function wardleyEditingIds(selections: readonly {
+    elements: readonly string[];
+    editing?: boolean;
+}[]): Set<string>;