@meltemi/diagrams-model 1.9.0 → 1.10.0

package/dist/flow.js

@@ -1,8 +1,9 @@
 import { isToken, } from "@meltemi/diagrams-language";
-import { DIRECTIONS, LAYOUT_MODES, ALIGN_EDGES, ANIMATION_EFFECT_PROPERTIES, AXES, ELEMENT_ONLY_PROPERTIES, FLOW_PROFILE, FREE_PROFILE, MAIN_LAYER, PORTS, PORT_SIDES, RELATION_ONLY_PROPERTIES, diagramStatements, profileTakesShape, takesShape, profileTakesRotation, takesRotation, } from "./schema.js";
+import { DIRECTIONS, LAYOUT_MODES, ALIGN_EDGES, ANIMATION_EFFECT_PROPERTIES, AXES, ELEMENT_ONLY_PROPERTIES, FLOW_PROFILE, FREE_PROFILE, MAIN_LAYER, PORTS, PORT_SIDES, RELATION_ARROWS, RELATION_ONLY_PROPERTIES, diagramStatements, profileTakesShape, takesShape, profileTakesRotation, takesRotation, } from "./schema.js";
 import { relationAllowed, } from "./diagram-types.js";
 import { messages } from "./messages/index.js";
 import { StyleDefinitions, checkArg, describeArg, headerHasError, readClasses, readPropertyBlock, readStatementValue, refuseFreeProperties, singleIdent, spanOf, targetHint, } from "./style-values.js";
+import { outlined } from "./outline.js";
 /** Element kinds drawn without an outline, which a moving dash cannot follow. */
 const NO_OUTLINE_KINDS = new Set([
     "note",
@@ -115,6 +116,10 @@ export class FlowAnalyzer {
     layerUses = [];
     layerRanges = new Map();
     animations = [];
+    /** Dashes on notes and texts, whose outline is checked once every style is read. */
+    pendingDashes = [];
+    /** The `on <element>` clauses of notes, resolved once every element is declared. */
+    attachments = [];
     references = [];
     entityReferences = [];
     placementBlocks = [];
@@ -198,6 +203,8 @@ export class FlowAnalyzer {
             this.declare(decl.stmt, decl.groupPath);
         for (const rel of classified.relations)
             this.relation(rel.stmt, rel.groupPath);
+        // After the relations, which may declare elements that only they mention.
+        this.resolveAttachments();
         this.assignKeys();
         this.afterRelations(classified);
         for (const stmt of classified.properties)
@@ -216,6 +223,7 @@ export class FlowAnalyzer {
                 this.styleOrAnimate(stmt, keyword);
         }
         this.checkLayers();
+        this.checkOutlinedDashes();
         this.finish();
         if (this.declared)
             this.checkDeclared(this.declared);
@@ -254,6 +262,26 @@ export class FlowAnalyzer {
             hasErrors: this.node.hasError || this.errors > 0,
         };
     }
+    /**
+     * A dash follows an outline: a note or a free text that no style statement, class or rule of the
+     * diagram gives a `fill`, `stroke` or `pattern` has none, and the dash is refused and dropped.
+     */
+    checkOutlinedDashes() {
+        const source = {
+            styles: this.styles,
+            classes: this.definitions.classes,
+            rules: this.definitions.rules,
+        };
+        for (const { name, token, stmt } of this.pendingDashes) {
+            const element = this.elementsById.get(name);
+            if (!element || outlined(source, element))
+                continue;
+            this.error("animate.invalid-target", messages().diagnostics.flow.dashNeedsOutline(name, element.kind), token, { hints: [messages().hints.flow.dashOutline] });
+            const at = this.animations.findIndex((a) => a.node === stmt && a.target === name && a.effect === "dash");
+            if (at >= 0)
+                this.animations.splice(at, 1);
+        }
+    }
     /** A declared type's rules: required properties, and the kinds relations may join. */
     checkDeclared(definition) {
         for (const element of this.elements) {
@@ -420,6 +448,9 @@ export class FlowAnalyzer {
                 technology: null,
                 external: false,
                 shape: data ? "cylinder" : null,
+                line: null,
+                attachedTo: null,
+                attachedToRange: null,
                 typeKind: null,
                 data: {},
                 groupPath,
@@ -435,19 +466,25 @@ export class FlowAnalyzer {
         const typeKind = declaredKind ? stmt.keyword.text : null;
         const kind = (declaredKind ? "box" : stmt.keyword.text);
         const sourced = kind === "text" || kind === "icon" || kind === "image";
+        const note = kind === "note" && !declaredKind;
         const second = { text: '"Text"', icon: '"<pack>:<name>"', image: '"<path>"' }[kind];
-        const form = sourced
-            ? `\`${kind} <id> ${second}\``
-            : `\`${kind} <id> ["Label"]${kind === "group" ? " { ... }" : ""}\``;
+        const form = note
+            ? '`note <id> "Text" [on <element>]`'
+            : sourced
+                ? `\`${kind} <id> ${second}\``
+                : `\`${kind} <id> ["Label"]${kind === "group" ? " { ... }" : ""}\``;
         const example = {
             text: 'text heading "Architecture"',
             icon: 'icon server "tabler:server"',
             image: 'image logo "logo.png"',
+            note: 'note limits "500 rps" on api',
         }[kind];
         if (stmt.chain) {
             this.invalid(messages().diagnostics.common.singleBlock(kind), stmt.chain.clauses[1].keyword);
             return;
         }
+        if (kind === "line" && !declaredKind)
+            return this.declareLine(stmt, groupPath);
         const [idArg, labelArg, ...extra] = stmt.args;
         const idToken = singleIdent(idArg);
         if (!idToken) {
@@ -491,15 +528,22 @@ export class FlowAnalyzer {
                 sourceRange = this.range(labelArg);
             }
         }
-        else if (sourced) {
+        else if (sourced || (note && this.notesNeedText)) {
             const m = messages();
             this.invalid(m.diagnostics.flow.needsSource(kind, idToken.text, form), stmt, [
                 m.hints.example(example),
             ]);
         }
+        // A note may end with `on <element>`; nothing else follows a label.
+        let attachment;
         if (extra.length > 0) {
-            this.invalid(messages().diagnostics.flow.valueAfter(sourced ? kind : "label", form), extra[0]);
-            return;
+            attachment = note ? this.attachmentOf(extra, form) : undefined;
+            if (!attachment) {
+                if (!note || !isWord(extra[0], "on")) {
+                    this.invalid(messages().diagnostics.flow.valueAfter(note ? "text" : sourced ? kind : "label", form), extra[0]);
+                }
+                return;
+            }
         }
         const block = kind === "group"
             ? { ...this.groupBlock(stmt.block, idToken), ports: [], values: {} }
@@ -520,6 +564,9 @@ export class FlowAnalyzer {
             technology: null,
             external: false,
             shape: null,
+            line: null,
+            attachedTo: attachment?.target ?? null,
+            attachedToRange: attachment ? this.range(attachment.arg) : null,
             typeKind,
             data: declaredKind ? dataOf(blockValues, declaredKind.properties) : {},
             groupPath,
@@ -528,6 +575,8 @@ export class FlowAnalyzer {
             idToken,
             node: stmt,
         });
+        if (added && attachment)
+            this.attachments.push({ note: idToken.text, ...attachment, stmt });
         if (!added || source === null || !sourceRange)
             return;
         if (kind === "icon")
@@ -535,6 +584,123 @@ export class FlowAnalyzer {
         else
             this.images.push({ element: idToken.text, path: source, range: sourceRange });
     }
+    /**
+     * `line <id> ["Label"] from (x, y) to (x, y) [via [(x, y), ...]] [{ ... }]`: a free line that
+     * joins no element, its points in the interior coordinates of its innermost group. The label is
+     * empty unless written: a line has no name to show.
+     */
+    declareLine(stmt, groupPath) {
+        const form = '`line <id> ["Label"] from (x, y) to (x, y) [via [(x, y), ...]]`';
+        const m = messages();
+        const [idArg, ...rest] = stmt.args;
+        const idToken = singleIdent(idArg);
+        if (!idToken) {
+            this.invalid(m.diagnostics.common.expected(form), idArg ?? stmt.keyword, [
+                m.hints.example("line divider from (40, 200) to (520, 200)"),
+            ]);
+            return;
+        }
+        const refuse = (at) => this.invalid(m.diagnostics.flow.linePoints, at ?? stmt, [m.hints.flow.form(form)]);
+        const labelArg = rest[0]?.kind === "StringLiteral" ? rest[0] : undefined;
+        const [fromWord, fromArg, toWord, toArg, viaWord, viaList, extra] = labelArg
+            ? rest.slice(1)
+            : rest;
+        if (!isWord(fromWord, "from"))
+            return refuse(fromWord);
+        const from = readPoint(fromArg);
+        if (!from)
+            return refuse(fromArg);
+        if (!isWord(toWord, "to"))
+            return refuse(toWord);
+        const to = readPoint(toArg);
+        if (!to)
+            return refuse(toArg);
+        const via = [];
+        if (viaWord) {
+            if (!isWord(viaWord, "via") || viaList?.kind !== "List")
+                return refuse(viaList ?? viaWord);
+            for (const item of viaList.items) {
+                const point = readPoint(item);
+                if (!point)
+                    return refuse(item);
+                via.push(point);
+            }
+            if (extra)
+                return refuse(extra);
+        }
+        const { values: _values, ...blockFields } = this.elementBlock(stmt.block, this.profile.elementProperties, "Element", idToken);
+        this.addElement({
+            id: idToken.text,
+            kind: "line",
+            label: labelArg?.kind === "StringLiteral" ? labelArg.value : "",
+            implicit: false,
+            ...blockFields,
+            source: null,
+            sourceRange: null,
+            labelWritten: labelArg !== undefined,
+            entity: null,
+            technology: null,
+            external: false,
+            shape: null,
+            line: { from, to, via },
+            attachedTo: null,
+            attachedToRange: null,
+            typeKind: null,
+            data: {},
+            groupPath,
+            range: this.range(stmt),
+            idRange: this.range(idToken),
+            idToken,
+            node: stmt,
+        });
+    }
+    /** Whether a note must write its text: free compositions and views, where a note is no node. */
+    get notesNeedText() {
+        return this.free;
+    }
+    /**
+     * The target of a note's `on <element>`: `extra` holds the word `on` and one identifier (C4
+     * views read an entity path), nothing else. Undefined when it does not; a lone `on` is reported
+     * here, as the form is wanted.
+     */
+    attachmentOf(extra, form) {
+        if (!isWord(extra[0], "on"))
+            return undefined;
+        const arg = extra[1];
+        const token = singleIdent(arg);
+        if (!token || extra.length > 2) {
+            this.invalid(messages().diagnostics.common.expected(form), extra[1] ?? extra[0]);
+            return undefined;
+        }
+        return { arg: arg, target: token.text };
+    }
+    /**
+     * Resolves the targets of the notes' `on <element>`: an element of the diagram other than the
+     * note itself, of any kind. Renames follow the reference this records.
+     */
+    resolveAttachments() {
+        const m = messages();
+        for (const { note, arg, target, stmt } of this.attachments) {
+            const token = singleIdent(arg);
+            if (target === note) {
+                this.invalid(m.diagnostics.flow.attachSelf(note), token);
+            }
+            else if (this.elementsById.has(target)) {
+                this.reference(token, target, "element", "attachment", stmt);
+            }
+            else {
+                this.error("ref.unknown-element", m.diagnostics.common.unknownElement(target), token, {
+                    hints: [m.hints.flow.attachTarget(note)],
+                    data: {
+                        ids: [target],
+                        candidates: this.elements
+                            .filter((e) => e.id !== note && e.kind !== "line")
+                            .map((e) => e.id),
+                    },
+                });
+            }
+        }
+    }
     addElement(element) {
         const existing = this.elementsById.get(element.id);
         if (existing) {
@@ -782,7 +948,8 @@ export class FlowAnalyzer {
             from,
             to,
             line: this.profile.arrows[stmt.arrow.text] ?? "solid",
-            twoWay: stmt.arrow.text.startsWith("<"),
+            heads: RELATION_ARROWS[stmt.arrow.text]?.heads ?? "end",
+            twoWay: RELATION_ARROWS[stmt.arrow.text]?.heads === "both",
             async: values.kind === "async",
             technology: null,
             sources: [],
@@ -841,6 +1008,9 @@ export class FlowAnalyzer {
             technology: null,
             external: false,
             shape: null,
+            line: null,
+            attachedTo: null,
+            attachedToRange: null,
             typeKind: null,
             data: {},
             groupPath,
@@ -1075,7 +1245,9 @@ export class FlowAnalyzer {
         if (extra)
             return this.shapeError(stmt, form, extra);
         const element = this.resolveElement(targetToken, "place", stmt);
-        if (!element || this.duplicatePlacement(stmt, element))
+        if (!element || this.lineRefused(element, "place", targetToken))
+            return;
+        if (this.duplicatePlacement(stmt, element))
             return;
         this.placement.push({
             statement: "place",
@@ -1102,7 +1274,9 @@ export class FlowAnalyzer {
         if (extra)
             return this.shapeError(stmt, form, extra);
         const element = this.resolveElement(targetToken, "size", stmt);
-        if (!element || this.duplicatePlacement(stmt, element))
+        if (!element || this.lineRefused(element, "size", targetToken))
+            return;
+        if (this.duplicatePlacement(stmt, element))
             return;
         this.placement.push({
             statement: "size",
@@ -1340,12 +1514,17 @@ export class FlowAnalyzer {
             if (extra)
                 return this.shapeError(stmt, form, extra);
         }
-        const relation = this.resolveRelation(targetToken, "label", stmt);
-        if (!relation || this.duplicatePlacement(stmt, relation.key))
+        // A free line's label pill moves as a relation's does.
+        const line = this.elementsById.get(targetToken.text);
+        if (line?.kind === "line")
+            this.reference(targetToken, line.id, "element", "label", stmt);
+        const relation = line?.kind === "line" ? undefined : this.resolveRelation(targetToken, "label", stmt);
+        const labelled = line?.kind === "line" ? line.id : relation?.key;
+        if (labelled === undefined || this.duplicatePlacement(stmt, labelled))
             return;
         this.placement.push({
             statement: "label",
-            target: relation.key,
+            target: labelled,
             at: at.value,
             offset: point,
             range: this.range(stmt),
@@ -1353,6 +1532,16 @@ export class FlowAnalyzer {
             node: stmt,
         });
     }
+    /** A free line takes no `place` or `size`: its points are in its statement. Reports it. */
+    lineRefused(id, statement, token) {
+        if (this.elementsById.get(id)?.kind !== "line")
+            return false;
+        const m = messages();
+        this.invalid(m.diagnostics.flow.lineHasPoints(id, statement), token, [
+            m.hints.flow.linePointsWritten,
+        ]);
+        return true;
+    }
     resolveElement(token, statement, stmt) {
         const name = token.text;
         if (this.elementsById.has(name)) {
@@ -1438,8 +1627,10 @@ export class FlowAnalyzer {
             const resolved = this.resolveStyleTarget(targetToken, kind, stmt);
             if (!resolved)
                 continue;
+            // A free line takes a relation's properties, and none of a box's.
+            const line = resolved.kind === "element" && this.elementsById.get(resolved.name)?.kind === "line";
             const misfit = kind === "style"
-                ? resolved.kind === "relation"
+                ? resolved.kind === "relation" || line
                     ? ELEMENT_ONLY_PROPERTIES
                     : RELATION_ONLY_PROPERTIES
                 : [];
@@ -1449,7 +1640,9 @@ export class FlowAnalyzer {
                 if (!token || name === "shape" || misplaced.has(name))
                     continue;
                 misplaced.add(name);
-                this.invalid(messages().diagnostics.flow.notForTargets(name, resolved.kind === "relation", resolved.name), token, [targetHint(name)]);
+                this.invalid(line
+                    ? messages().diagnostics.flow.notForLines(name, resolved.name)
+                    : messages().diagnostics.flow.notForTargets(name, resolved.kind === "relation", resolved.name), token, line ? [] : [targetHint(name)]);
             }
             // `shape` is refused per target: a block may list a node and a decision.
             const shapeless = kind === "style" && tokens.shape ? this.shapeRefusal(resolved) : null;
@@ -1473,7 +1666,7 @@ export class FlowAnalyzer {
             if (kind === "animate") {
                 // One effect per channel and target; different channels may share a target.
                 const effect = values.effect;
-                if (effect && !this.animationTargetFits(effect, resolved, targetToken))
+                if (effect && !this.animationTargetFits(effect, resolved, targetToken, stmt))
                     continue;
                 if (effect) {
                     const key = `${resolved.name}:${effect}`;
@@ -1597,19 +1790,27 @@ export class FlowAnalyzer {
         return { profile: false, kind: element.kind };
     }
     /** Whether an effect can run on a target; reports `animate.invalid-target` when not. */
-    animationTargetFits(effect, resolved, token) {
+    animationTargetFits(effect, resolved, token, stmt) {
         const element = resolved.kind === "element" ? this.elementsById.get(resolved.name) : undefined;
         const m = messages().diagnostics.flow;
         let reason = null;
-        if (effect === "flow" && resolved.kind !== "relation") {
+        // A free line runs effects as a relation does: it is a connector without ends.
+        const connector = resolved.kind === "relation" || element?.kind === "line";
+        if (effect === "flow" && !connector) {
             reason = m.flowTarget;
         }
-        else if (effect === "trace" && resolved.kind !== "relation") {
+        else if (effect === "trace" && !connector) {
             reason = m.traceTarget;
         }
         else if (effect === "dash") {
             if (resolved.kind === "event")
                 reason = m.dashOnEvent;
+            else if (element && (element.kind === "note" || element.kind === "text")) {
+                // A note or a text draws an outline when its styles say so, which a later statement may
+                // write: checked once every block is read (`checkOutlinedDashes`).
+                if (stmt)
+                    this.pendingDashes.push({ name: resolved.name, token, stmt });
+            }
             else if (element && NO_OUTLINE_KINDS.has(element.kind)) {
                 reason = m.dashWithoutOutline(resolved.name, element.kind);
             }
@@ -1648,7 +1849,15 @@ export class FlowAnalyzer {
 // -------------------------------------------------------------------- free helpers
 /** The declarations and statements of flow and free diagrams, as their hints list them. */
 const FLOW_DECLARATIONS = ["node", "decision", "data", "group", "note", "tag"];
-const FREE_DECLARATIONS = ["box", "text", "icon", "image", "group"];
+const FREE_DECLARATIONS = [
+    "box",
+    "text",
+    "icon",
+    "image",
+    "note",
+    "line",
+    "group",
+];
 const FLOW_STATEMENTS = [
     "direction",
     "layout",
@@ -1675,6 +1884,7 @@ const FREE_PROFILE_ONLY = {
     fontSize: true,
     fontWeight: true,
     textAlign: true,
+    verticalAlign: true,
 };
 function isWord(arg, word) {
     return singleIdent(arg)?.text === word;