@formicoidea/labre-framework-wardley 0.32.0 → 0.34.1

package/dist/element-view.js

@@ -18,11 +18,15 @@ export class WardleyView extends GfxElementModelView {
         this._closeLabelEditor();
         super.onDestroyed();
     }
-    /** Double-click on a label → edit its text in place. */
-    _onDblClick(e) {
-        if (this.model.isLocked())
-            return;
-        const [mx, my] = this.gfx.viewport.toModelCoord(e.x, e.y);
+    /**
+     * The editable label under a MODEL-space point, or null.
+     *
+     * Which labels exist, where they sit, what they SAY and which are editable
+     * all come from the declaration the renderer paints — one source, resolved
+     * through the same catalogue, so a label can never be drawn in one place
+     * and clicked in another, nor read one thing and open on another.
+     */
+    _labelAt(mx, my) {
         const [bx, by, w, h] = this.model.deserializedXYWH;
         // Convert the model-space point into element-local coordinates, undoing the
         // element rotation around its center.
@@ -35,15 +39,34 @@ export class WardleyView extends GfxElementModelView {
             lx = ux - bx;
             ly = uy - by;
         }
-        // Which labels exist, where they sit, what they SAY and which are editable
-        // all come from the declaration the renderer paints — one source, resolved
-        // through the same catalogue, so a label can never be drawn in one place
-        // and clicked in another, nor read one thing and open on another.
         const hit = hitTestBackgroundLabel(backgroundLabelHits(WARDLEY_BACKGROUND, this.model, w, h, this.gfx.std.getOptional(TranslationProvider)), lx, ly);
-        if (!hit)
-            return;
         // The declaration names the prop; this decides whether it may be written.
-        if (!isWardleyLabelProp(hit.prop))
+        if (!hit || !isWardleyLabelProp(hit.prop))
+            return null;
+        return { prop: hit.prop, text: hit.text };
+    }
+    /**
+     * The map is SELECTED by its border (`WardleyBackgroundElementModel`), but
+     * its axis labels must still receive the double-click that renames them.
+     *
+     * So the two areas differ, and this is where they are allowed to: the pointer
+     * router asks the VIEW (`GfxViewEventManager`), and the view adds the zones
+     * the declaration draws its labels in. Picking is unaffected —
+     * `getElementByPoint` still asks the model, so a click in the middle of the
+     * map still goes to whatever the user put there.
+     */
+    includesPoint(x, y, options, host) {
+        if (super.includesPoint(x, y, options, host))
+            return true;
+        return this._labelAt(x, y) !== null;
+    }
+    /** Double-click on a label → edit its text in place. */
+    _onDblClick(e) {
+        if (this.model.isLocked())
+            return;
+        const [mx, my] = this.gfx.viewport.toModelCoord(e.x, e.y);
+        const hit = this._labelAt(mx, my);
+        if (!hit)
             return;
         this._openLabelEditor(hit.prop, hit.text, e);
     }

package/dist/export.d.ts

@@ -0,0 +1,211 @@
+import { ConnectorElementModel, TextElementModel, WardleyBackgroundElementModel, WardleyNodeElementModel } from '@formicoidea/labre-core/model';
+import type { GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+/**
+ * A Wardley map as an OnlineWardleyMaps (OWM) DSL document — models in, text
+ * out (`docs/adr/0012`, P3).
+ *
+ * This is the function ADR 0012 records as owed: the Wardley serializer that
+ * exists today in **labre-mcp**, outside this repo, and is the ADR's one named
+ * violation of P3. It lands here so that both consumers — the editor command
+ * and the MCP tool — call one implementation, tested once, and so that the
+ * reader next door (`import.ts`) has a writer it agrees with about every
+ * coordinate, name and carried line.
+ *
+ * ## Pure, like its BPMN sibling
+ *
+ * Element models in, a string out. No `BlockStdScope`, no surface, no DOM, no
+ * clock, no randomness. `interchange.ts` is the thin adapter that names the
+ * file; `actions.ts` is the thinner one that downloads it.
+ *
+ * ## The plot IS the coordinate
+ *
+ * A Wardley node carries **no** `visibility` and **no** `evolution` prop — its
+ * position on the map's plot is the whole of what the map says about it. So the
+ * writer inverts the projection the reader applied: a node's centre, measured
+ * against the plot of the background it sits on, is the `[visibility,
+ * evolution]` pair OWM spells. Both numbers are written to exactly **two
+ * decimals**, and that stability is load-bearing rather than cosmetic: the
+ * fixed point `export(import(export(board)))` is byte-identical only because a
+ * value that survives one rounding survives every one after it. The reader
+ * tolerates any precision a foreign file happens to use.
+ *
+ * ## A name is a separate element, so it has to be found
+ *
+ * On this canvas the name of an artefact is a free text element beside it, not
+ * a prop on it (`roles.ts`, `WARDLEY_ROLE.label`). The writer therefore matches
+ * each label to the node it names by comparing where the label IS with where a
+ * label for that node WOULD be — see {@link matchLabels}, which is the one
+ * heuristic in this module and is documented as one.
+ *
+ * ## v1 reads one map
+ *
+ * An OWM document is one map. A surface holding several Wardley backgrounds is
+ * serialized against the FIRST in document order, and the export warns; the
+ * other maps' artefacts are written against that first plot, which is the
+ * honest behaviour (nothing is dropped) and is named in the warning so nobody
+ * discovers it from a file.
+ */
+/**
+ * The format id, and therefore THE KEY foreign matter rides under on an element
+ * (ADR 0012, D2) — `interchange.owm`. Declared here and re-exported by
+ * `import.ts`, so a reader filing a fragment and a writer looking one up cannot
+ * disagree about where it went.
+ */
+export declare const WARDLEY_OWM_FORMAT_ID = "owm";
+/**
+ * OWM's scope vocabulary — where a carried line came off (D2).
+ *
+ * The DSL is a flat list of statements with no nesting and no ids, so it needs
+ * exactly two `@`-prefixed role keys and never an element id:
+ *
+ * - `@document` — the whole file: the lines this reader has no artefact for,
+ *   and the `title` it consumed. They ride on the map's background element,
+ *   which is D6's stated asymmetry (delete the map and the residue goes with
+ *   it) and is where `profileId` already lives for the same reason.
+ * - `@self` — the line an element WAS. Used for the verbatim tail of a mapped
+ *   line, i.e. everything the writer would otherwise drop: `label [x, y]`,
+ *   `(build)`, `inertia`, a trailing comment.
+ */
+export declare const OWM_SCOPE: {
+    readonly document: "@document";
+    readonly self: "@self";
+};
+/** Where a mapped line's un-modelled tail is filed, under `attrs['@self']`. */
+export declare const OWM_TAIL_ATTR = "tail";
+/** Where the file's own `title` is filed, under `attrs['@document']`. */
+export declare const OWM_TITLE_ATTR = "title";
+/**
+ * Keywords a line may open on, none of which can be a bare component name.
+ *
+ * Two different parsers care. `BaseStrategyRunner` claims a line for a keyword
+ * when the TRIMMED line opens on `"<keyword> "`, and `LinksExtractionStrategy`
+ * refuses to read a line as a link when it opens on any of these — so a
+ * component genuinely called `style` would silently stop being linkable. The
+ * writer quotes such a name rather than betting nobody ever picks one.
+ */
+export declare const OWM_KEYWORDS: Set<string>;
+/**
+ * A name as the DSL spells it — bare when it can be, quoted and escaped
+ * otherwise.
+ *
+ * The escaping mirrors OWM's own `escapeComponentNameForMapText` /
+ * `unescapeComponentNameFromMapText` pair character for character, which is
+ * what makes `"Vente retail thés, accessoires, coffrets"` come back with its
+ * commas and its accents intact.
+ */
+export declare function owmName(raw: string): string;
+/** A name in quotes, escaped as OWM's `escapeComponentNameForMapText` does. */
+export declare function owmQuote(raw: string): string;
+/**
+ * A coordinate, to exactly two decimals — the whole of the fixed point's
+ * arithmetic.
+ *
+ * `-0` is written as `0.00`, because `(-0).toFixed(2)` is `"-0.00"` and a
+ * node dropped one pixel above the plot's top edge would otherwise produce a
+ * file whose bytes depend on which side of zero a float landed on. A
+ * non-finite value (an element with no geometry) is written as `0.00` rather
+ * than as `NaN`, which no parser reads.
+ */
+export declare function owmNumber(value: number): string;
+/** The plot of a map, in ABSOLUTE surface units. */
+export interface OwmPlot {
+    /** Surface x of evolution `0`, and y of visibility `1`. */
+    x0: number;
+    y0: number;
+    width: number;
+    height: number;
+}
+/** The reference map an import lays out on, and an export falls back to. */
+export declare const OWM_DEFAULT_MAP_WIDTH: number;
+export declare const OWM_DEFAULT_MAP_HEIGHT: number;
+/**
+ * The plot of a background element, in absolute units — the declaration's
+ * margins, never a hand-written inset.
+ *
+ * `templates/maps.ts` learned this the hard way: a plot copied as four numbers
+ * drifted from the drawn one, and a rule measuring against the declaration then
+ * judged nodes laid out against the copy. Both directions of this format read
+ * the same function for the same reason.
+ */
+export declare function owmPlotOf(bound: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}): OwmPlot;
+/** The default plot: a reference map at the origin. */
+export declare function owmDefaultPlot(): OwmPlot;
+/**
+ * `[visibility, evolution]` → a surface point.
+ *
+ * Mind the inversion, which is the one thing about these axes that is easy to
+ * get backwards and impossible to see in a test that only round-trips: OWM's
+ * visibility `1.0` is the TOP of the value chain, and a canvas' y grows
+ * downwards.
+ */
+export declare function owmPointOf(plot: OwmPlot, visibility: number, evolution: number): [number, number];
+/** A surface point → `[visibility, evolution]`. The exact inverse. */
+export declare function owmCoordsOf(plot: OwmPlot, x: number, y: number): {
+    visibility: number;
+    evolution: number;
+};
+/**
+ * The artefacts the writer speaks about, picked out of a surface's elements and
+ * kept in the order they were given.
+ *
+ * Document order matters for the same reason it does in BPMN: it decides which
+ * map is THE map when a board holds several, and it is the order every section
+ * of the produced file is written in — so a file exported twice from an
+ * untouched board is the same file, byte for byte.
+ *
+ * `notes` is every text element with NO role. That is a deliberate reading and
+ * not a leak: an OWM `note` IS a free text at a position, so a text somebody
+ * dropped on the map is written as one. Only a text carrying the `label` role
+ * is a name, and only a name is resolved onto a node.
+ */
+export interface WardleyExportBoard {
+    maps: WardleyBackgroundElementModel[];
+    nodes: WardleyNodeElementModel[];
+    labels: TextElementModel[];
+    notes: TextElementModel[];
+    connectors: ConnectorElementModel[];
+}
+export declare function wardleyBoardFrom(elements: readonly GfxPrimitiveElementModel[]): WardleyExportBoard;
+/**
+ * A name a file system will accept, minus the extension. BPMN's sanitizer,
+ * verbatim in behaviour and different only in its fallback — `map`, because
+ * that is what an OWM document is.
+ */
+export declare function wardleySafeFilename(raw: string | undefined): string;
+/** The label box an import writes, and the width a prediction assumes. */
+export declare const OWM_LABEL_WIDTH = 200;
+export declare const OWM_LABEL_HEIGHT: number;
+/** A text element's string, whether it is a `Y.Text` or a test's plain one. */
+export declare function textOf(element: {
+    text?: unknown;
+}): string;
+export interface WardleyOwmExportOptions {
+    /** The board's own title, already sanitized by the caller. */
+    name?: string;
+}
+/**
+ * The board as an OWM document, plus what the format could not say.
+ *
+ * Sections in a fixed order — title, nodes, pipelines, notes, evolutions,
+ * links, carried lines — and DOCUMENT order inside each. That pairing is what
+ * makes the fixed point hold: the reader creates elements in the order it meets
+ * them, so a file's sections come back as a document whose order re-sections
+ * identically.
+ */
+export declare function exportWardleyOwmWithWarnings(board: WardleyExportBoard, options?: WardleyOwmExportOptions): {
+    text: string;
+    warnings: string[];
+};
+/**
+ * The board as an OWM document — models in, text out, and nothing else.
+ *
+ * The signature P3 names: exported from this package's index so that labre-mcp
+ * calls THIS function rather than keeping the copy ADR 0012 records as the one
+ * violation of it.
+ */
+export declare function exportWardleyOwm(board: WardleyExportBoard, options?: WardleyOwmExportOptions): string;