@formicoidea/labre-framework-wardley 0.31.0 → 0.33.0

package/dist/gradient.js

@@ -5,6 +5,11 @@
  * its own min and max — i.e. the gradient is strongest where the curve peaks and
  * fades to nothing at its minimum. Validated against the reference images at
  * `../wardley-mockups/gradient-backgrounds.html`.
+ *
+ * The curves are TABULATED ONCE, here, at module load: what the declaration
+ * ships — and what the primitive paints — is a table of `[offset, alpha]`
+ * stops, not a function. Nothing is evaluated at paint time, and the wash is
+ * data like the rest of the declaration (PF2.1).
  */
 const bell = (x, mu, s) => Math.exp(-0.5 * ((x - mu) / s) ** 2);
 const asym = (x, mu, sL, sR) => Math.exp(-0.5 * ((x - mu) / (x < mu ? sL : sR)) ** 2);
@@ -40,7 +45,7 @@ const RG = rangeOf(fDiff, DIFF_DOM[0], DIFF_DOM[1]);
 const RR = rangeOf(fOper, OPER_DOM[0], OPER_DOM[1]);
 const RB = rangeOf(fBen, 0, 1);
 const clamp01 = (v) => Math.max(0, Math.min(1, v));
-const norm = (v, lo, hi) => (hi > lo ? (v - lo) / (hi - lo) : 0);
+const norm = (v, lo, hi) => hi > lo ? (v - lo) / (hi - lo) : 0;
 export const GRADIENT_GREEN = '#1f9e4d';
 export const GRADIENT_RED = '#d6455d';
 const GRADIENT_GREY = '#7c8389';
@@ -48,62 +53,68 @@ const GRADIENT_GREY = '#7c8389';
 const GRADIENT_MAX_OPACITY = 0.45;
 /** Peak opacity for the grey evolution-gradient variant. */
 const GREY_MAX_OPACITY = 0.38;
-function rgba(hex, alpha) {
-    const r = parseInt(hex.slice(1, 3), 16);
-    const g = parseInt(hex.slice(3, 5), 16);
-    const b = parseInt(hex.slice(5, 7), 16);
-    return `rgba(${r},${g},${b},${alpha})`;
-}
 /**
- * Add stops to a horizontal gradient (offset 0..1 spanning the plot width) for
- * a function-driven opacity profile within [x0, x1] (zero outside).
+ * Tabulate one opacity profile as gradient stops spanning the plot width:
+ * 49 samples inside [x0, x1], bracketed by a zero stop wherever the profile
+ * does not reach the edge of the plot.
  */
-function addStops(grad, hex, opacityFn, x0, x1, maxOp = GRADIENT_MAX_OPACITY) {
+function stopTable(opacityFn, x0, x1, maxOp = GRADIENT_MAX_OPACITY) {
     const eps = 0.001;
+    const stops = [];
     if (x0 > eps)
-        grad.addColorStop(Math.max(0, x0 - eps), rgba(hex, 0));
+        stops.push([Math.max(0, x0 - eps), 0]);
     const N = 48;
     for (let i = 0; i <= N; i++) {
         const x = x0 + ((x1 - x0) * i) / N;
-        grad.addColorStop(clamp01(x), rgba(hex, clamp01(opacityFn(x)) * maxOp));
+        stops.push([clamp01(x), clamp01(opacityFn(x)) * maxOp]);
     }
     if (x1 < 1 - eps)
-        grad.addColorStop(Math.min(1, x1 + eps), rgba(hex, 0));
+        stops.push([Math.min(1, x1 + eps), 0]);
+    return stops;
 }
+// benefit: green where the curve is positive, red where negative.
+const BEN_MAX_POS = RB.hi;
+const BEN_MAX_NEG = -RB.lo;
 /**
- * Paint the curve-driven gradient over the plot rectangle [px0,px1]×[py0,py1]
- * in element-local coordinates. `classic` paints nothing.
+ * The washes the Wardley declaration ships, in painting order. Only those whose
+ * `variants` name the background's current `variant` are painted, and only
+ * while `showGradient` is on — so `classic` paints none of them and the frame
+ * stays plain white, exactly as before.
  */
-export function paintGradientBackground(ctx, variant, px0, px1, py0, py1) {
-    const w = px1 - px0;
-    const h = py1 - py0;
-    if (variant === 'evolution-gradient') {
-        const grey = ctx.createLinearGradient(px0, 0, px1, 0);
-        addStops(grey, GRADIENT_GREY, fGrey, 0, 1, GREY_MAX_OPACITY);
-        ctx.fillStyle = grey;
-        ctx.fillRect(px0, py0, w, h);
-        return;
-    }
-    if (variant === 'opportunity') {
-        const green = ctx.createLinearGradient(px0, 0, px1, 0);
-        addStops(green, GRADIENT_GREEN, x => norm(fDiff(x), RG.lo, RG.hi), DIFF_DOM[0], DIFF_DOM[1]);
-        ctx.fillStyle = green;
-        ctx.fillRect(px0, py0, w, h);
-        const red = ctx.createLinearGradient(px0, 0, px1, 0);
-        addStops(red, GRADIENT_RED, x => norm(fOper(x), RR.lo, RR.hi), OPER_DOM[0], OPER_DOM[1]);
-        ctx.fillStyle = red;
-        ctx.fillRect(px0, py0, w, h);
-        return;
-    }
-    // benefit: green where the curve is positive, red where negative.
-    const maxPos = RB.hi;
-    const maxNeg = -RB.lo;
-    const green = ctx.createLinearGradient(px0, 0, px1, 0);
-    addStops(green, GRADIENT_GREEN, x => Math.max(0, fBen(x)) / maxPos, 0, 1);
-    ctx.fillStyle = green;
-    ctx.fillRect(px0, py0, w, h);
-    const red = ctx.createLinearGradient(px0, 0, px1, 0);
-    addStops(red, GRADIENT_RED, x => Math.max(0, -fBen(x)) / maxNeg, 0, 1);
-    ctx.fillStyle = red;
-    ctx.fillRect(px0, py0, w, h);
-}
+export const WARDLEY_WASHES = [
+    {
+        id: 'evolution-grey',
+        variants: ['evolution-gradient'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_GREY,
+        stops: stopTable(fGrey, 0, 1, GREY_MAX_OPACITY),
+    },
+    {
+        id: 'opportunity-differential',
+        variants: ['opportunity'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_GREEN,
+        stops: stopTable(x => norm(fDiff(x), RG.lo, RG.hi), DIFF_DOM[0], DIFF_DOM[1]),
+    },
+    {
+        id: 'opportunity-operational',
+        variants: ['opportunity'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_RED,
+        stops: stopTable(x => norm(fOper(x), RR.lo, RR.hi), OPER_DOM[0], OPER_DOM[1]),
+    },
+    {
+        id: 'benefit-positive',
+        variants: ['benefit'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_GREEN,
+        stops: stopTable(x => Math.max(0, fBen(x)) / BEN_MAX_POS, 0, 1),
+    },
+    {
+        id: 'benefit-investment',
+        variants: ['benefit'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_RED,
+        stops: stopTable(x => Math.max(0, -fBen(x)) / BEN_MAX_NEG, 0, 1),
+    },
+];

package/dist/import.d.ts

@@ -0,0 +1,116 @@
+import type { InterchangeImportContext, InterchangeImportResult } from '@formicoidea/labre-core/blocks/surface';
+import { OWM_SCOPE, WARDLEY_OWM_FORMAT_ID } from './export.js';
+/**
+ * An OnlineWardleyMaps (OWM) DSL document, read as a Wardley map — the inverse
+ * of `export.ts` on the vocabulary Labre draws, and an honest accounting of
+ * everything else (`docs/adr/0012`, D1–D6).
+ *
+ * ADR 0012 calls this row **the reference Wardley import**, and says why: the
+ * OWM DSL is the one Wardley vocabulary that is settled, so it is what a user
+ * should be pointed at while mermaid's Wardley diagram type is still
+ * experimental upstream.
+ *
+ * ## Pure by construction, like its mirror
+ *
+ * A string in, element PROPS out. No `BlockStdScope`, no surface, no DOM, no
+ * clock, no randomness — and, unlike `.bpmn`, no parser either: the DSL is
+ * line-based, so this reads lines. The caller does the writing (P3).
+ *
+ * ## What the caller owes, and it is one thing
+ *
+ * **OWM has no ids: the NAME is the identity.** So every element below carries
+ * the name it was declared under, verbatim, in `interchange.owm.id`, and a link
+ * arrives with `source` / `target` naming those — which is exactly the map
+ * `materializeInterchangeImport` folds the returned array into (D3). Nothing
+ * else is needed to finish the import, and the same fold is what makes
+ * `boardFromProps` in the spec suite a bridge rather than a mock.
+ *
+ * A name declared twice is imported twice — nothing is dropped — and every link
+ * naming it means the FIRST, which is both the materializer's rule and OWM's
+ * own. The report says so by name.
+ *
+ * ## Where the coordinates come from, and where they do not (D4)
+ *
+ * A `[visibility, evolution]` pair IS the authoritative position — that is D4's
+ * "a format that carries coordinates but no pixels" — so the reader projects it
+ * onto the plot of the map it lays down and re-layouts nothing. A statement
+ * that carries NO pair inverts the same rule rather than contradicting it:
+ * there is nothing to be authoritative, so the reader lays one out and SAYS SO,
+ * with an `invented-layout` note naming the artefact. **An invented axis is
+ * never presented as read from the file.** That is the whole of D4 for a
+ * coordinate format, and it is the case `anchor Client` — one line of the
+ * tea-shop corpus, and the shape half the maps in the wild are written in.
+ *
+ * ## Three states, and the middle one is where the file survives
+ *
+ * **Mapped** is what the pack draws: `component`, `anchor`, `market`,
+ * `ecosystem`, `pipeline`, `note`, `evolve`, `title`, and the `->` links.
+ * **Carried** is every other statement — `style`, `annotation`, `attitudes`
+ * (`pioneers` / `settlers` / `townplanners`), `submap`, `url`, `size`,
+ * `accelerator`, the axis-label overrides, the flow links (`+>`, `+<`, `+<>`,
+ * `+'…'>`), a link carrying a `;` context, and every `//` comment — kept
+ * verbatim in `interchange.owm.children['@document']` on the map's background
+ * element (D6) and written back, in order, at the end of the next export.
+ * **Quarantined** is empty, and that is a finding rather than an omission: see
+ * the loss table.
+ *
+ * A mapped line keeps its own tail too — `label [12, -8]`, `(build)`,
+ * `inertia`, a trailing comment — under `attrs['@self'].tail` on the artefact
+ * it belongs to, so the modifiers this pack does not draw come back on the
+ * line they were written on rather than at the bottom of the file.
+ *
+ * ## The loss table
+ *
+ * Every semantic capability owes one (ADR 0012), and this is the OWM DSL's.
+ * INVISIBLE is not LOST, and the distinction is the deliverable.
+ *
+ * | what                                                                   | state       | after a round trip                                                                                                     |
+ * | ---------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+ * | `component` / `anchor` / `market` / `ecosystem` and their coordinates  | mapped      | drawn, and written back from the drawing, to two decimals                                                              |
+ * | the NAME, which in this format is the identity                        | mapped      | given back verbatim, quoted exactly as it needs to be — the fixed point                                                |
+ * | `pipeline Name [m1, m2]`                                              | mapped      | drawn as the body + handle composite; `[m1, m2]` written back from the body's two edges                                |
+ * | `note Text [v, e]`                                                    | mapped      | a free text on the map, written back from its centre                                                                   |
+ * | `evolve X [-> Y] m`                                                   | mapped      | an evolved twin at the same height plus a change arrow, written back from the arrow                                    |
+ * | `A->B` links                                                          | mapped      | a `wardley:dependency` connector, consumer → what it needs, never inverted                                             |
+ * | `title`                                                               | mapped      | consumed as the board's own name; written back from the board's name (see the two rows below)                          |
+ * | a mapped line's TAIL — `label [x, y]`, `(build)`, `inertia`, comments | carried     | invisible on the canvas, re-appended to the very line it came off                                                      |
+ * | `style`, `annotation(s)`, `attitudes`, `submap`, `url`, `size`, `accelerator`, the axis-label overrides | carried | invisible on the canvas, re-emitted verbatim at the end of the file          |
+ * | flow links (`+>`, `+<`, `+<>`, `+'…'>`) and a link with a `;` context | carried     | not drawn — a flow is not a dependency — and re-emitted verbatim                                                       |
+ * | a `pipeline` with a `{ … }` body                                      | carried     | the block is kept whole and written back whole; the pack draws no pipeline children                                    |
+ * | `//` comments                                                         | carried     | re-emitted verbatim, at the end                                                                                        |
+ * | anything else the reader does not recognise                           | carried     | re-emitted verbatim, at the end                                                                                        |
+ * | **nothing**                                                           | quarantined | every statement this format writes is a standalone sentence, so nothing carried can contradict the drawing (D5)        |
+ * | a statement with NO coordinates (`anchor Client`)                     | **lost**    | the reader places it at the reference default (0.9, 0.1) and says so; the export then writes the coordinates we invented, not the silence the file had |
+ * | a statement with MALFORMED coordinates                                | **lost**    | same, and the report carries a `warning` as well as the `invented-layout` note                                         |
+ * | a statement positioned on ONE axis (`[0.5]`, `[nonsense, 0.5]`)       | **half mapped, half lost** | the axis the file gave is read and kept exactly; the other takes the reference default and gets its own `invented-layout` note naming WHICH axis was invented. The statement counts as `mapped` — it was positioned — and the export writes a full pair, so the axis the file left silent comes back as a number |
+ * | the file's own line ORDER and its blank lines                         | **lost**    | the writer groups statements into sections. Nothing semantic depends on it, and carrying blank lines would make an untouched Labre file report a carried count |
+ * | a `pipeline`'s visibility                                             | **lost**    | OWM derives it from the component of the same name; the reader places the body under that component and the writer does not write it back |
+ * | an `evolve` twin drawn at a different height                          | **lost**    | `evolve` moves along the evolution axis only; the export warns                                                          |
+ * | a Labre `method` node (build / buy / outsource)                       | **lost**    | written as a plain component — OWM says a method with a decorator this writer cannot tell apart. The export warns       |
+ * | the file's `title`                                                    | **carried**, and it WINS | kept under `attrs['@document'].title` and written back in preference to the name the caller passes — D3's precedence, the same one `interchange.<fmt>.id` has on every element. A board renamed in Labre therefore still exports under the title its file carried, and the export warns that it did; the caller's name is used only when the file carried none (and is still what the DOWNLOAD is called either way) |
+ * | surface identity across a re-import                                   | **lost**    | a new map beside the old one, never a merge                                                                            |
+ * | a name whose whitespace matters (`Foo&nbsp;&nbsp;&nbsp;Bar`)          | **round-trips here, at risk elsewhere** | this reader keeps a name VERBATIM and this writer gives it back verbatim, so Labre → Labre is exact. onlinewardleymaps does not: `normalizeComponentName` collapses whitespace runs before it matches a link end to a component, so a map that goes Labre → OWM → Labre may come back with its links dangling. Not sanitized here, because sanitizing would lose the author's name to protect another tool's matcher |
+ * | a top-level `market` / `ecosystem` statement                          | **round-trips here, refused elsewhere** | Labre reads and writes both. The reference `Converter` registers no strategy for either keyword, so such a line reaches `LinksExtractionStrategy`, has no `->` in it and is recorded as a PARSE ERROR — onlinewardleymaps does not merely fail to draw it. The interoperable spelling is a component carrying the decorator (`component Suppliers [0.3, 0.7] (market)`), which this pair already round-trips through the carried tail |
+ *
+ * `sourceVersion` reports the DIALECT, because the DSL declares no version: the
+ * OnlineWardleyMaps frontend's own extraction strategies, which is what this
+ * reader was written against. It reads `DSL (Labre)` for a file holding nothing
+ * this library does not itself write — the honest form of "a file we wrote",
+ * since the format has no marker to claim one with.
+ */
+export { WARDLEY_OWM_FORMAT_ID, OWM_SCOPE };
+/**
+ * OWM's own defaults for an axis a statement did not give
+ * (`extractLocation`, `constants/extractionFunctions.ts`). Used rather than a
+ * layout of our own, so an artefact this reader places without coordinates
+ * lands where the tool that wrote the file would have drawn it.
+ */
+export declare const OWM_DEFAULT_VISIBILITY = 0.9;
+export declare const OWM_DEFAULT_EVOLUTION = 0.1;
+/**
+ * An OWM document as element props, plus what became of every line.
+ *
+ * @param source the file, verbatim.
+ * @param context the caller's name for it, used only if the file names nothing.
+ */
+export declare function importWardleyOwm(source: string, context?: InterchangeImportContext): InterchangeImportResult;