@formicoidea/labre-core 0.41.0 → 0.42.0

package/dist/_pkgs/affine-block-surface/extensions/reading-widget.js

@@ -40,7 +40,7 @@ import { css, html, nothing } from 'lit';
 import { state } from 'lit/decorators.js';
 import { literal, unsafeStatic } from 'lit/static-html.js';
 import { EditorAnchoredPanel, editorAnchoredPanelStyles, } from './editor-anchored-panel.js';
-import { PivotRecordPickerProvider, ReadingManager, readRecord, readValueFlows, } from './reading.js';
+import { PivotRecordPickerProvider, ReadingManager, readingRelationDefs, readRecord, readValueFlows, } from './reading.js';
 export const READING_PROPOSAL_WIDGET = 'affine-reading-proposal-widget';
 /** The two commands the confirmations drive. Spelled once. */
 const TAG_SET_ID = 'tag.set';
@@ -411,37 +411,59 @@ let ReadingProposalWidget = (() => {
                 : nothing}`);
         }
         /**
-         * The typed edges touching the subject, grouped by side and named with the
-         * FRAMEWORK's own two words (`ReadingRelationDef.sides`).
+         * The typed edges touching the subject, grouped by TABLE and then by side,
+         * and named with the FRAMEWORK's own two words
+         * (`ReadingRelationDef.sides`).
+         *
+         * One line per (table, side) rather than per side, since a profile may
+         * declare several tables (`ReadingProfile.alsoRelations`): a UML use case
+         * associated with an actor and including another use case has two sentences
+         * to say and they are not the same sentence. A framework declaring one table
+         * — which is every framework but UML — renders exactly what it did before.
          *
          * The `data-testid` keeps the shape it shipped with — `reading-consumers`,
          * `reading-suppliers` — because it names the SIDE, which is generic, and not
-         * the wording, which is now the framework's.
+         * the wording, which is the framework's. `data-relation-role` is what tells
+         * two lines of the same side apart.
+         *
+         * The FAR end's label rides with the name, in parentheses: a UML association
+         * writes its multiplicity there (ADR 0020) and "Associated with: OrderLine
+         * (1..*)" is the sentence an author drew. The subject's OWN end label is read
+         * too ({@link ReadingRelation.ownEndLabel}) and deliberately not printed —
+         * one line about the other end, not a transcription of the connector.
          */
         _renderRelations(reading, profile) {
-            const sides = profile.relation?.sides;
-            const line = (side) => {
-                const relations = reading.relations.filter(r => r.side === side);
-                const wording = sides?.[side];
+            const named = (relation) => {
+                const name = relation.otherName || relation.otherId;
+                return relation.otherEndLabel
+                    ? `${name} (${relation.otherEndLabel})`
+                    : name;
+            };
+            const line = (edgeRole, side) => {
+                const relations = reading.relations.filter(r => r.side === side && r.relationRole === edgeRole);
+                const wording = readingRelationDefs(profile).find(def => def.edgeRole === edgeRole)?.sides[side];
                 // No wording means the framework declared no relation at all, in which
                 // case there is nothing to list either. Silence rather than a heading
                 // this library would have had to invent.
                 if (!relations.length || !wording)
                     return nothing;
-                return html `<div class="reading-value" data-testid=${`reading-${side}s`}>
+                return html `<div
+        class="reading-value"
+        data-testid=${`reading-${side}s`}
+        data-relation-role=${edgeRole}
+      >
         ${translateKey(this.std, wording.labelKey, wording.labelFallback)}:
-        ${relations
-                    .map(relation => relation.otherName || relation.otherId)
-                    .join(', ')}
+        ${relations.map(named).join(', ')}
       </div>`;
             };
+            const lines = readingRelationDefs(profile).flatMap(def => RELATION_SIDES.map(side => line(def.edgeRole, side)));
             const contradictions = reading.relations.filter(r => r.contradictsGeometry);
             return this._field('reading-relations', translateKey(this.std, 'com.labre.reading.field.relations', 'Parent-child relations'), html `${reading.relations.length === 0
                 ? html `<div class="reading-empty">
             ${translateKey(this.std, 'com.labre.reading.relations.none', 'No typed link touches this component.')}
           </div>`
                 : nothing}
-      ${RELATION_SIDES.map(line)}
+      ${lines}
       ${contradictions.length
                 ? html `<div class="reading-note" data-testid="reading-contradiction">
             ${translateKey(this.std, 'com.labre.reading.relations.contradiction', 'A link states the opposite of what the positions show')}:

package/dist/_pkgs/affine-block-surface/extensions/reading.d.ts

@@ -155,8 +155,36 @@ export interface ReadingProfile {
         tagId: string;
         conventions: readonly ReadingNamingConvention[];
     };
-    /** The typed edge whose two ends the relation reading walks. */
+    /**
+     * The typed edge whose two ends the relation reading walks — the one the
+     * artefact is read THROUGH, and the one the panel lists first.
+     */
     relation?: ReadingRelationDef;
+    /**
+     * The OTHER typed edges the same artefact is read through, read after
+     * {@link relation} and listed under their own wordings.
+     *
+     * Absent for every framework whose artefacts carry one kind of line: a
+     * Wardley component has a dependency, a BPMN task a sequence flow, and a
+     * second table there would be a heading with nothing under it.
+     *
+     * It exists because UML's artefacts carry a DOZEN kinds of line, and the
+     * panel answering with one of them reads as an answer rather than as a
+     * selection: the PO's recette of 2026-09-14 (O8) opened the reading on a use
+     * case whose only link was an `«include»` and was told "No typed link touches
+     * this component", which the drawing plainly contradicted. One relation per
+     * profile was a deliberate narrowing (`gfx/uml/src/reading.ts` argued it and
+     * named what it left unread); what the recette established is that a reader
+     * cannot tell a narrowing from a failure, because the panel says the same
+     * thing in both cases.
+     *
+     * Every table is INDEPENDENT: its own `edgeRole`, its own two wordings, its
+     * own `geometry` claim. `roleIsA` still applies to each, so a table declared
+     * on a parent role reaches its children and two tables must not overlap — an
+     * edge matching both would be listed twice. Order is the order the panel
+     * reads them in, so the first is the question the artefact answers first.
+     */
+    alsoRelations?: readonly ReadingRelationDef[];
     /** The frame the phase is read from. */
     frame?: {
         backgroundRole: RoleId;
@@ -181,14 +209,46 @@ export interface ReadingProfile {
 }
 /** Where the other end of a typed edge sits, relative to the subject. */
 export type ReadingRelationSide = 'consumer' | 'supplier';
+/**
+ * Every relation table a profile declares, in reading order.
+ *
+ * One function so the engine and the panel cannot disagree about what a profile
+ * declares — the bug that shape of duplication always produces is a table read
+ * into {@link ElementReading.relations} and never drawn, or a heading drawn
+ * over nothing.
+ */
+export declare function readingRelationDefs(profile: ReadingProfile): readonly ReadingRelationDef[];
 /** One typed edge touching the subject, read with the ADR 0010 convention. */
 export interface ReadingRelation {
     /** The edge element. */
     edgeId: string;
+    /**
+     * The `edgeRole` of the TABLE that matched — the role the profile DECLARED,
+     * never the edge's own, which may be a specialisation of it (a UML
+     * composition read through `uml:association`, §11.5.4).
+     *
+     * It is what lets the panel put each relation under the wording it was read
+     * with once a profile declares several tables. One reading, one table, and
+     * the tables never overlap: {@link readingRelationDefs} documents that as the
+     * declaring framework's obligation.
+     */
+    relationRole: RoleId;
     /** The element at the other end. */
     otherId: string;
     /** Its name, when it has one — for the panel, which must not print ids. */
     otherName: string;
+    /**
+     * What the connector writes at the SUBJECT's end, and at the other end —
+     * `undefined` when the author wrote nothing there, which is the ordinary
+     * case (ADR 0020).
+     *
+     * Two spellings of the same fact rather than `sourceLabel`/`targetLabel`,
+     * because the reading is written from the subject outwards and a panel
+     * saying "Associated with: OrderLine (1..*)" must not have to work out which
+     * end of the arrow it is standing on.
+     */
+    ownEndLabel?: string;
+    otherEndLabel?: string;
     /**
      * What the OTHER element is to the subject. ADR 0010 § 2 tier 2: on a
      * `wardley:dependency`, `source` is the consumer and `target` is what it

package/dist/_pkgs/affine-block-surface/extensions/reading.js

@@ -9,6 +9,21 @@ import { effect, signal } from '@preact/signals-core';
 // canvas in.
 import { backgroundPlot, } from '../framework-background/def.js';
 import { backgroundTransitionBands, containingFrame, } from '../framework-background/facts.js';
+/**
+ * Every relation table a profile declares, in reading order.
+ *
+ * One function so the engine and the panel cannot disagree about what a profile
+ * declares — the bug that shape of duplication always produces is a table read
+ * into {@link ElementReading.relations} and never drawn, or a heading drawn
+ * over nothing.
+ */
+export function readingRelationDefs(profile) {
+    const first = profile.relation;
+    const rest = profile.alsoRelations ?? [];
+    if (!first)
+        return rest;
+    return rest.length === 0 ? [first] : [first, ...rest];
+}
 /** Deepest role chain reported by {@link ReadingNodeType.specialises}. */
 const MAX_ROLE_DEPTH = 32;
 /** Numeric slack on the two geometry comparisons. Model units. */
@@ -218,55 +233,86 @@ function endpointsOf(element) {
     return { source: source.id, target: target.id };
 }
 /**
- * Every typed edge touching the subject, read as a relation.
+ * What a connector writes at one of its two ends, when it writes anything.
+ *
+ * A UML multiplicity is the case this exists for (`0..*` on the far end of an
+ * association), and the shape is ADR 0020's: two optional `Y.Text` props on the
+ * connector, empty when the author never opened the editor. Read defensively —
+ * the reading is handed plain element models by unit tests as readily as live
+ * ones — and blank-trimmed, because a text the user emptied is not a label.
+ */
+function endLabelOf(edge, end) {
+    const raw = edge[end === 'source' ? 'sourceLabel' : 'targetLabel'];
+    if (raw === undefined || raw === null)
+        return undefined;
+    const text = String(raw).trim();
+    return text.length > 0 ? text : undefined;
+}
+/**
+ * Every typed edge touching the subject, read as a relation — one pass per
+ * table the profile declares ({@link readingRelationDefs}).
+ *
+ * The tables are walked in DECLARATION order rather than the elements being
+ * walked once and each edge matched against every table, so the panel's
+ * sections come out in the order their framework wrote them and an artefact
+ * read through four kinds of line reads its first kind first. The cost is one
+ * pass over the surface per table, which is what it already was when a profile
+ * could only declare one.
  *
  * An edge with an unbound end is skipped, exactly as ADR 0010 requires of W4:
  * releasing the link tool over empty canvas produces one, and a stroke that
  * links nothing states nothing.
  */
 function readRelations(element, elements, profile) {
-    const relation = profile.relation;
-    if (!relation)
+    const defs = readingRelationDefs(profile);
+    if (defs.length === 0)
         return [];
     const byId = new Map(elements.map(el => [el.id, el]));
     const [, subjectY] = centreOf(element.elementBound);
     const relations = [];
-    for (const edge of elements) {
-        if (edge.role === undefined)
-            continue;
-        if (!roleIsA(edge.role, relation.edgeRole, profile.roles))
-            continue;
-        const ends = endpointsOf(edge);
-        if (!ends)
-            continue;
-        const isSource = ends.source === element.id;
-        const isTarget = ends.target === element.id;
-        // A self-loop states nothing about an order and would report the subject as
-        // its own supplier.
-        if (isSource === isTarget)
-            continue;
-        const otherId = isSource ? ends.target : ends.source;
-        const other = byId.get(otherId);
-        if (!other)
-            continue;
-        const side = isSource ? 'supplier' : 'consumer';
-        const [, otherY] = centreOf(other.elementBound);
-        // `y` grows downwards, so "higher on the map" is a SMALLER y. A supplier is
-        // expected below the subject, a consumer above it — but only on a board
-        // whose framework CLAIMED that axis says something (`geometry`). Two BPMN
-        // tasks side by side contradict nothing.
-        const contradictsGeometry = relation.geometry !== 'vertical'
-            ? false
-            : side === 'supplier'
-                ? otherY < subjectY - GEOMETRY_EPSILON
-                : otherY > subjectY + GEOMETRY_EPSILON;
-        relations.push({
-            edgeId: edge.id,
-            otherId,
-            otherName: readName(other, profile),
-            side,
-            contradictsGeometry,
-        });
+    for (const relation of defs) {
+        for (const edge of elements) {
+            if (edge.role === undefined)
+                continue;
+            if (!roleIsA(edge.role, relation.edgeRole, profile.roles))
+                continue;
+            const ends = endpointsOf(edge);
+            if (!ends)
+                continue;
+            const isSource = ends.source === element.id;
+            const isTarget = ends.target === element.id;
+            // A self-loop states nothing about an order and would report the subject
+            // as its own supplier.
+            if (isSource === isTarget)
+                continue;
+            const otherId = isSource ? ends.target : ends.source;
+            const other = byId.get(otherId);
+            if (!other)
+                continue;
+            const side = isSource ? 'supplier' : 'consumer';
+            const [, otherY] = centreOf(other.elementBound);
+            // `y` grows downwards, so "higher on the map" is a SMALLER y. A supplier
+            // is expected below the subject, a consumer above it — but only on a
+            // board whose framework CLAIMED that axis says something (`geometry`).
+            // Two BPMN tasks side by side contradict nothing.
+            const contradictsGeometry = relation.geometry !== 'vertical'
+                ? false
+                : side === 'supplier'
+                    ? otherY < subjectY - GEOMETRY_EPSILON
+                    : otherY > subjectY + GEOMETRY_EPSILON;
+            const ownEndLabel = endLabelOf(edge, isSource ? 'source' : 'target');
+            const otherEndLabel = endLabelOf(edge, isSource ? 'target' : 'source');
+            relations.push({
+                edgeId: edge.id,
+                relationRole: relation.edgeRole,
+                otherId,
+                otherName: readName(other, profile),
+                side,
+                contradictsGeometry,
+                ...(ownEndLabel !== undefined ? { ownEndLabel } : {}),
+                ...(otherEndLabel !== undefined ? { otherEndLabel } : {}),
+            });
+        }
     }
     return relations;
 }

package/dist/_pkgs/affine-block-surface/extensions/record-action.d.ts

@@ -0,0 +1,66 @@
+import { Bound } from '../../global/gfx/index.js';
+import type { BlockStdScope } from '../../std/index.js';
+/** What {@link recordAction} saw a creation action ask the surface for. */
+export interface RecordedAction {
+    /**
+     * One plain record per element the action added, in creation order, holding
+     * the props it passed. `id` is the recording's own (`el-0`, `el-1`, …), not
+     * an id any document will ever carry.
+     */
+    records: Record<string, unknown>[];
+    /**
+     * The union of the records' `xywh`, relative to the fake viewport's centre —
+     * which sits at the ORIGIN, so this is the footprint the same action would
+     * draw around whatever centre a real viewport has. `null` when no record
+     * carries a box at all.
+     */
+    bound: Bound | null;
+    /**
+     * The name of the tool the action armed, other than the default one it may
+     * return to after placing — `connector` for a command that lets the user
+     * DRAW a relation. Such a command creates nothing on its own and must be
+     * declared `kind: 'tool'`, or the placement tool wraps it and cancels the
+     * drawing it armed. `null` when nothing was armed.
+     */
+    armedTool: string | null;
+    /**
+     * The OPTIONS the action armed that tool with — where a typed edge's `role`
+     * lives, since a command that arms the connector tool creates nothing and
+     * therefore stamps nothing on any record. `null` when nothing was armed.
+     */
+    armedToolOptions: Record<string, unknown> | null;
+}
+/** Hook applied to a finished record before it is kept. See {@link recordAction}. */
+export type RecordEncoder = (record: Record<string, unknown>) => void;
+export interface RecordActionOptions {
+    /**
+     * The editor the recording is being run FOR. Its `TranslationProvider`, and
+     * nothing else from it, is handed to the action, so the seeds the action
+     * writes come out in the user's language. Without one, the action writes its
+     * English fallbacks.
+     */
+    host?: BlockStdScope;
+    /**
+     * Last chance to rewrite a record before it is kept — how a caller that needs
+     * a SNAPSHOT converts the `Y.Text` / `Y.Map` props into their serialized
+     * form. A caller that only measures the drawing passes nothing.
+     */
+    encode?: RecordEncoder;
+}
+/**
+ * Run a creation action against a recording fake, and hand back what it asked
+ * the surface for — so a framework's artefact can be measured, previewed or
+ * serialized without ever touching a document.
+ *
+ * The `std` handed to `run` answers the members placement actions actually
+ * touch and THROWS on anything else, so an unsupported action fails loudly
+ * instead of yielding a half-empty drawing. Callers that can carry on without a
+ * measure catch it; callers that cannot (a template derived at build time) let
+ * it through.
+ *
+ * Extracted from `snapshotFromAction` (`@labre/affine-gfx-template`), which is
+ * still its first caller: the placement tool needs the same recording and lives
+ * in the toolbar widget, which the template package depends ON — so the
+ * recording had to move down here, where both can reach it.
+ */
+export declare function recordAction(run: (std: BlockStdScope) => void, { host, encode }?: RecordActionOptions): RecordedAction;

package/dist/_pkgs/affine-block-surface/extensions/record-action.js

@@ -0,0 +1,145 @@
+import { Bound } from '../../global/gfx/index.js';
+import { TranslationProvider } from '../../affine-shared/services/index.js';
+import { generateKeyBetween, GfxControllerIdentifier } from '../../std/gfx/index.js';
+import { EdgelessCRUDIdentifier } from './crud-extension.js';
+/**
+ * Run a creation action against a recording fake, and hand back what it asked
+ * the surface for — so a framework's artefact can be measured, previewed or
+ * serialized without ever touching a document.
+ *
+ * The `std` handed to `run` answers the members placement actions actually
+ * touch and THROWS on anything else, so an unsupported action fails loudly
+ * instead of yielding a half-empty drawing. Callers that can carry on without a
+ * measure catch it; callers that cannot (a template derived at build time) let
+ * it through.
+ *
+ * Extracted from `snapshotFromAction` (`@labre/affine-gfx-template`), which is
+ * still its first caller: the placement tool needs the same recording and lives
+ * in the toolbar widget, which the template package depends ON — so the
+ * recording had to move down here, where both can reach it.
+ */
+export function recordAction(run, { host, encode } = {}) {
+    const elements = new Map();
+    let n = 0;
+    let lastIndex = null;
+    const nextIndex = () => (lastIndex = generateKeyBetween(lastIndex, null));
+    const addElement = (props) => {
+        const id = `el-${n++}`;
+        const record = {};
+        for (const [key, value] of Object.entries(props)) {
+            if (value !== undefined)
+                record[key] = value;
+        }
+        record['id'] = id;
+        encode?.(record);
+        if (record['index'] === undefined)
+            record['index'] = nextIndex();
+        // The model members an action reads back off `getElementById`, kept
+        // non-enumerable so they never leak into a snapshot built from the record.
+        Object.defineProperties(record, {
+            group: { value: null },
+            deserializedXYWH: {
+                get: () => typeof record['xywh'] === 'string'
+                    ? Bound.deserialize(record['xywh'])
+                    : null,
+            },
+        });
+        elements.set(id, record);
+        return id;
+    };
+    const records = () => [...elements.values()];
+    let armedTool = null;
+    let armedToolOptions = null;
+    const setTool = (tool, options) => {
+        const name = typeof tool === 'string' ? tool : tool?.toolName;
+        if (name && name !== 'default') {
+            armedTool = name;
+            armedToolOptions = options ?? null;
+        }
+    };
+    const surface = {
+        addElement,
+        getElementById: (id) => elements.get(id) ?? null,
+        getElementsByType: (type) => records().filter(el => el['type'] === type),
+        get elementModels() {
+            return records();
+        },
+    };
+    const gfx = {
+        surface,
+        // The centre at the ORIGIN is what makes `bound` a footprint rather than a
+        // position: an action that creates "at the viewport centre" records a box
+        // around (0, 0), which is exactly the offset to re-apply around a real one.
+        viewport: { centerX: 0, centerY: 0, zoom: 1, center: { x: 0, y: 0 } },
+        doc: { captureSync: () => { } },
+        selection: { set: () => { }, selectedElements: [] },
+        tool: { setTool },
+        layer: {
+            generateIndex: () => nextIndex(),
+            getReorderedIndex: (_model, direction) => {
+                const sorted = records()
+                    .map(el => String(el['index']))
+                    .sort();
+                return direction === 'back'
+                    ? generateKeyBetween(null, sorted[0] ?? null)
+                    : generateKeyBetween(sorted[sorted.length - 1] ?? null, null);
+            },
+            get canvasElements() {
+                return records();
+            },
+        },
+        std: null,
+    };
+    const crud = {
+        addElement: (type, props) => addElement({ ...props, type }),
+    };
+    const std = {
+        get: (identifier) => {
+            if (identifier === GfxControllerIdentifier)
+                return gfx;
+            if (identifier === EdgelessCRUDIdentifier)
+                return crud;
+            throw new Error(`recordAction: unsupported service "${identifier?.identifierName ?? String(identifier)}"`);
+        },
+        getOptional: (identifier) => identifier === TranslationProvider
+            ? host?.getOptional(TranslationProvider)
+            : undefined,
+        command: {
+            // Really run the command, so a group built by `createGroupCommand` is
+            // whatever that command says a group is — no second definition here.
+            exec: (cmd, payload) => {
+                let out;
+                cmd({ std: gfx.std, ...payload }, r => {
+                    out = r;
+                });
+                return [{}, out ?? {}];
+            },
+        },
+        store: {
+            readonly: false,
+            captureSync: () => { },
+            id: 'doc:template',
+            workspace: { meta: { getDocMeta: () => undefined } },
+        },
+    };
+    gfx.std = std;
+    run(gfx.std);
+    return {
+        records: records(),
+        bound: uniteBounds(records()),
+        armedTool,
+        armedToolOptions,
+    };
+}
+/** The union of whatever boxes the records carry. */
+function uniteBounds(records) {
+    let union = null;
+    for (const record of records) {
+        const xywh = record['xywh'];
+        if (typeof xywh !== 'string')
+            continue;
+        const bound = Bound.deserialize(xywh);
+        union = union ? union.unite(bound) : bound;
+    }
+    return union;
+}