@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/_pkgs/affine-gfx-connector/connector-tool.d.ts

@@ -1,9 +1,34 @@
-import { ConnectorMode } from '../affine-model/index.js';
+import { type ConnectorElementProps, ConnectorMode } from '../affine-model/index.js';
 import type { IVec } from '../global/gfx/index.js';
 import type { PointerEventState } from '../std/index.js';
 import { BaseTool, type GfxModel } from '../std/gfx/index.js';
 export type ConnectorToolOptions = {
     mode: ConnectorMode;
+    /**
+     * Semantic role (`<framework>:<role>`) stamped on the connectors drawn while
+     * this activation lasts — a framework toolbox activates the tool for a typed
+     * edge (e.g. `wardley:dependency`). Left out for the plain connector tool:
+     * the edge then stays neutral and no `role` key is written.
+     */
+    role?: string;
+    /**
+     * The FIVE stroke-and-marker props a framework toolbox arms its flow with
+     * (e.g. solid + filled triangle for a BPMN sequence flow) — the ones the
+     * stencils actually distinguish each other by. Applied at creation only,
+     * where explicit props win over the user's last plain-connector props, and
+     * NEVER recorded into `EditPropsStore`: arming a typed flow must not restyle
+     * the plain connector tool (BPMN 2.0 p.40 — other connectors must not adopt
+     * a flow's line style). Left out for the plain tool, which keeps drawing
+     * with the user's own last props.
+     *
+     * Deliberately NOT the whole look: a connector's other styled props —
+     * `rough`, `labelStyle` and the rest — are outside this bag and still come
+     * from the user's last plain-connector props, exactly as they did before
+     * this option existed. No framework declares them today, so nothing is lost;
+     * a framework that needs one must widen this `Pick` rather than reach for
+     * the store.
+     */
+    style?: Partial<Pick<ConnectorElementProps, 'stroke' | 'strokeStyle' | 'strokeWidth' | 'frontEndpointStyle' | 'rearEndpointStyle'>>;
 };
 export declare class ConnectorTool extends BaseTool<ConnectorToolOptions> {
     static toolName: string;

package/dist/_pkgs/affine-gfx-connector/connector-tool.js

@@ -36,8 +36,13 @@ export class ConnectorTool extends BaseTool {
         this.doc.captureSync();
         const id = this.gfx.surface.addElement({
             type: CanvasElementType.CONNECTOR,
+            // The activation's own style, if any: explicit props win over the
+            // user's last plain-connector props in the edit-props middleware, so a
+            // framework look never passes through the shared store.
+            ...this.activatedOption.style,
             mode: this.activatedOption.mode,
-            controllers: [],
+            // `undefined` writes nothing: a neutral edge keeps no `role` key.
+            role: this.activatedOption.role,
             source: this._source,
             target: { position: this._startPoint },
         });
@@ -159,7 +164,9 @@ export class ConnectorTool extends BaseTool {
             }
             // Geometric centroid as a center anchor (gated on the global toggle),
             // mirroring the center anchor offered for other shape types.
-            const centerAnchorEnabled = this.std.getOptional(EditPropsStore)?.getStorage('connectorCenterAnchor') ?? true;
+            const centerAnchorEnabled = this.std
+                .getOptional(EditPropsStore)
+                ?.getStorage('connectorCenterAnchor') ?? true;
             if (centerAnchorEnabled) {
                 locations.push(polygonCentroid(verts));
             }
@@ -170,7 +177,9 @@ export class ConnectorTool extends BaseTool {
             this._sourceLocations = [[0.5, 0.5]];
         }
         else {
-            const centerAnchorEnabled = this.std.getOptional(EditPropsStore)?.getStorage('connectorCenterAnchor') ?? true;
+            const centerAnchorEnabled = this.std
+                .getOptional(EditPropsStore)
+                ?.getStorage('connectorCenterAnchor') ?? true;
             this._sourceLocations =
                 element instanceof ShapeElementModel &&
                     element.shapeType === ShapeType.Triangle

package/dist/_pkgs/affine-gfx-connector/connector-watcher.js

@@ -39,10 +39,7 @@ function reanchorConnectorsForPolygon(surface, polygonId, elementGetter) {
                 continue;
             // Convert the stored normalized [0-1] position to absolute model coords.
             const [nx, ny] = connection.position;
-            const absPos = [
-                bound.x + nx * bound.w,
-                bound.y + ny * bound.h,
-            ];
+            const absPos = [bound.x + nx * bound.w, bound.y + ny * bound.h];
             // Find the nearest anchor on the updated polygon boundary.
             let nearestCoord = connection.position;
             let minDist = Infinity;

package/dist/_pkgs/affine-gfx-connector/direction/direction-reveal.d.ts

@@ -0,0 +1,123 @@
+import type { ConnectorElementModel } from '../../affine-model/index.js';
+import type { IVec } from '../../global/gfx/index.js';
+import { InteractivityExtension } from '../../std/gfx/index.js';
+import { type TypedEdge } from './typed-edge.js';
+/**
+ * **M2 of `docs/adr/0010` — "show it".**
+ *
+ * A typed edge reveals its orientation on hover and on selection: ONE mark, the
+ * role's verb laid ALONG the link — `depends on` — in a box whose far end is a
+ * point aimed at the target. At rest the board keeps the canonical arrowless
+ * look, because on a Wardley map a permanent head already means something else
+ * (evolution movement), and two meanings on one glyph make both unreadable.
+ *
+ * ## The chevron is gone (PO acceptance of 02/08/2026, point 5)
+ *
+ * The first cut of M2 drew two marks: a canvas chevron at the target end, and
+ * a horizontal DOM tooltip holding the bare verb. Two things were wrong with
+ * it, and they had one cause between them.
+ *
+ * - The label was placed on `path[floor(length / 2)]`, the middle VERTEX. A
+ *   straight link has exactly two points, so the "middle" vertex IS the target
+ *   end — the tooltip landed on the tip of the link and covered the chevron it
+ *   was meant to complement.
+ * - Even placed correctly, a horizontal box across a diagonal link reads as a
+ *   sticker dropped on the map rather than as a statement about that link.
+ *
+ * The fix is one mark instead of two: the verb, rotated onto the line,
+ * ending in the point that used to be a separate chevron. So this file no
+ * longer owns a canvas overlay at all — {@link labelAnchorOf} says where the
+ * label goes and which way it turns, and the DOM widget draws it. Nothing can
+ * overlap something that no longer exists.
+ *
+ * ## Why a manager, and not the element renderer
+ *
+ * An `ElementRenderer` is `(model, ctx, matrix, renderer, rc)`: it knows the
+ * element and knows nothing about hover or selection, which are the two things
+ * this affordance is made of. So the state lives in an `InteractivityExtension`
+ * that owns two signals, and the widget reads them.
+ *
+ * Nothing here touches an element model: no CRDT write, no undo entry, not even
+ * a `@local()` field. The reveal is session state and leaves with the pointer.
+ */
+/**
+ * The one colour the reveal is drawn in — the house primary, i.e. the colour of
+ * an affordance rather than of ink. Deliberately NOT the framework's palette:
+ * the label is the tool talking about the drawing, not part of the drawing.
+ */
+export declare const EDGE_DIRECTION_COLOR = "#1e96eb";
+/**
+ * Where the label sits on a typed edge, and how it is turned.
+ *
+ * All of it in MODEL space: the widget projects `at` through the viewport and
+ * scales the box by the zoom, so the label is glued to its link the way a
+ * street name is glued to its street.
+ */
+export interface EdgeLabelAnchor {
+    /** The model point the label CENTRES on — the middle of the drawn path. */
+    at: IVec;
+    /**
+     * Rotation in radians, always within `[-π/2, π/2]`: the angle of the median
+     * segment, turned by 180° when that angle would stand the text on its head.
+     */
+    angle: number;
+    /**
+     * Whether that 180° turn happened. It is the whole reason the caller needs
+     * this flag: the point of the box must face the TARGET, so on a link running
+     * right-to-left — where the turn put the box's right end at the SOURCE — the
+     * point moves to the box's left end. The words themselves never reverse; a
+     * mirrored `depends on` would be a smudge, not a rotation.
+     */
+    flipped: boolean;
+}
+/**
+ * Where a typed edge's label goes and how it is turned — the whole geometry
+ * of M2 since the chevron was folded into the label.
+ *
+ * `null` for an edge with no direction to show: no routed path yet, or a path
+ * whose points all coincide. Silence, not a guess.
+ */
+export declare function labelAnchorOf(model: ConnectorElementModel): EdgeLabelAnchor | null;
+/**
+ * Owns "which typed edges are revealing their direction", and the hint the
+ * armed tool shows (M1). Both are session state, both are signals, and both are
+ * read by the overlay and by the widget — so the two halves of the affordance
+ * can never disagree about what is on screen.
+ *
+ * No-op until some framework registers a role vocabulary: on a board of
+ * generalist connectors this subscribes to nothing at all.
+ */
+export declare class EdgeDirectionManager extends InteractivityExtension {
+    static key: string;
+    /** Ids of the typed edges revealing their direction: hover ∪ selection. */
+    readonly revealed$: import("@preact/signals-core").Signal<readonly string[]>;
+    /**
+     * The gesture hint of the armed tool, when that tool draws a typed edge —
+     * M1's half of the affordance. `null` for every other tool, which is every
+     * tool whose gesture decides no persisted orientation.
+     */
+    readonly armedHint$: import("@preact/signals-core").Signal<{
+        key: string;
+        fallback?: string;
+    } | null>;
+    private _hovered;
+    private _subscriptions;
+    private _vocabularies;
+    private get _roles();
+    /**
+     * The revealed edges, resolved NOW rather than remembered.
+     *
+     * The same reasoning as the validation overlay's: the widget re-renders far
+     * more often than this state changes, and an edge can lose a binding or a
+     * role between two frames. A frozen snapshot would keep labelling a relation
+     * that no longer exists.
+     */
+    revealedEdges(): TypedEdge[];
+    mounted(): void;
+    unmounted(): void;
+    private _hover;
+    private _setHovered;
+    private _syncArmed;
+    /** Recompute hover ∪ selection, and publish only when it actually changed. */
+    private _sync;
+}

package/dist/_pkgs/affine-gfx-connector/direction/direction-reveal.js

@@ -0,0 +1,282 @@
+import { InteractivityExtension } from '../../std/gfx/index.js';
+import { effect, signal } from '@preact/signals-core';
+import { asTypedEdge, edgeIsBound, roleVocabularies, } from './typed-edge.js';
+/**
+ * **M2 of `docs/adr/0010` — "show it".**
+ *
+ * A typed edge reveals its orientation on hover and on selection: ONE mark, the
+ * role's verb laid ALONG the link — `depends on` — in a box whose far end is a
+ * point aimed at the target. At rest the board keeps the canonical arrowless
+ * look, because on a Wardley map a permanent head already means something else
+ * (evolution movement), and two meanings on one glyph make both unreadable.
+ *
+ * ## The chevron is gone (PO acceptance of 02/08/2026, point 5)
+ *
+ * The first cut of M2 drew two marks: a canvas chevron at the target end, and
+ * a horizontal DOM tooltip holding the bare verb. Two things were wrong with
+ * it, and they had one cause between them.
+ *
+ * - The label was placed on `path[floor(length / 2)]`, the middle VERTEX. A
+ *   straight link has exactly two points, so the "middle" vertex IS the target
+ *   end — the tooltip landed on the tip of the link and covered the chevron it
+ *   was meant to complement.
+ * - Even placed correctly, a horizontal box across a diagonal link reads as a
+ *   sticker dropped on the map rather than as a statement about that link.
+ *
+ * The fix is one mark instead of two: the verb, rotated onto the line,
+ * ending in the point that used to be a separate chevron. So this file no
+ * longer owns a canvas overlay at all — {@link labelAnchorOf} says where the
+ * label goes and which way it turns, and the DOM widget draws it. Nothing can
+ * overlap something that no longer exists.
+ *
+ * ## Why a manager, and not the element renderer
+ *
+ * An `ElementRenderer` is `(model, ctx, matrix, renderer, rc)`: it knows the
+ * element and knows nothing about hover or selection, which are the two things
+ * this affordance is made of. So the state lives in an `InteractivityExtension`
+ * that owns two signals, and the widget reads them.
+ *
+ * Nothing here touches an element model: no CRDT write, no undo entry, not even
+ * a `@local()` field. The reveal is session state and leaves with the pointer.
+ */
+/**
+ * The one colour the reveal is drawn in — the house primary, i.e. the colour of
+ * an affordance rather than of ink. Deliberately NOT the framework's palette:
+ * the label is the tool talking about the drawing, not part of the drawing.
+ */
+export const EDGE_DIRECTION_COLOR = '#1e96eb';
+const pathOf = (model) => {
+    const path = model.absolutePath;
+    return Array.isArray(path) && path.length >= 2 ? path : null;
+};
+/**
+ * The middle of the drawn path by ARC LENGTH, and the segment it falls in.
+ *
+ * Arc length rather than "the middle vertex": on a two-point path the middle
+ * vertex is the target endpoint, which is exactly where the label must not go,
+ * and on an elbowed path the vertex nearest the middle can sit far from it.
+ *
+ * When the middle lands exactly on a corner — two equal arms — the arm the path
+ * ARRIVES BY wins (`>=`). Both angles are true there and neither is better; what
+ * matters is that the same path always answers the same way, so the label
+ * cannot flicker between two rotations across repaints.
+ */
+function median(path) {
+    let total = 0;
+    for (let i = 1; i < path.length; i++) {
+        total += Math.hypot(path[i][0] - path[i - 1][0], path[i][1] - path[i - 1][1]);
+    }
+    // A path of zero length is a link drawn on a single point: no middle, no
+    // angle, nothing to say.
+    if (total === 0)
+        return null;
+    const half = total / 2;
+    let walked = 0;
+    for (let i = 1; i < path.length; i++) {
+        const from = path[i - 1];
+        const to = path[i];
+        const length = Math.hypot(to[0] - from[0], to[1] - from[1]);
+        if (length === 0)
+            continue;
+        if (walked + length >= half) {
+            const t = (half - walked) / length;
+            return {
+                at: [from[0] + (to[0] - from[0]) * t, from[1] + (to[1] - from[1]) * t],
+                from,
+                to,
+            };
+        }
+        walked += length;
+    }
+    return null;
+}
+/**
+ * Where a typed edge's label goes and how it is turned — the whole geometry
+ * of M2 since the chevron was folded into the label.
+ *
+ * `null` for an edge with no direction to show: no routed path yet, or a path
+ * whose points all coincide. Silence, not a guess.
+ */
+export function labelAnchorOf(model) {
+    const path = pathOf(model);
+    if (!path)
+        return null;
+    const middle = median(path);
+    if (!middle)
+        return null;
+    const { at, from, to } = middle;
+    // Canvas y grows downward and so does CSS's rotation sense, so this angle is
+    // handed to `rotate()` unchanged.
+    let angle = Math.atan2(to[1] - from[1], to[0] - from[0]);
+    let flipped = false;
+    if (angle > Math.PI / 2) {
+        angle -= Math.PI;
+        flipped = true;
+    }
+    else if (angle < -Math.PI / 2) {
+        angle += Math.PI;
+        flipped = true;
+    }
+    return { at, angle, flipped };
+}
+/** The `direction` declaration of a role id, when that role is an edge. */
+function directionOfRole(vocabularies, roleId) {
+    for (const defs of vocabularies) {
+        const def = defs[roleId];
+        if (def !== undefined)
+            return def.kind === 'edge' ? def.direction : undefined;
+    }
+    return undefined;
+}
+/**
+ * Owns "which typed edges are revealing their direction", and the hint the
+ * armed tool shows (M1). Both are session state, both are signals, and both are
+ * read by the overlay and by the widget — so the two halves of the affordance
+ * can never disagree about what is on screen.
+ *
+ * No-op until some framework registers a role vocabulary: on a board of
+ * generalist connectors this subscribes to nothing at all.
+ */
+export class EdgeDirectionManager extends InteractivityExtension {
+    constructor() {
+        super(...arguments);
+        /** Ids of the typed edges revealing their direction: hover ∪ selection. */
+        this.revealed$ = signal([]);
+        /**
+         * The gesture hint of the armed tool, when that tool draws a typed edge —
+         * M1's half of the affordance. `null` for every other tool, which is every
+         * tool whose gesture decides no persisted orientation.
+         */
+        this.armedHint$ = signal(null);
+        this._hovered = null;
+        this._subscriptions = [];
+        this._vocabularies = null;
+    }
+    static { this.key = 'edge-direction'; }
+    get _roles() {
+        this._vocabularies ??= roleVocabularies(this.std);
+        return this._vocabularies;
+    }
+    /**
+     * The revealed edges, resolved NOW rather than remembered.
+     *
+     * The same reasoning as the validation overlay's: the widget re-renders far
+     * more often than this state changes, and an edge can lose a binding or a
+     * role between two frames. A frozen snapshot would keep labelling a relation
+     * that no longer exists.
+     */
+    revealedEdges() {
+        const surface = this.gfx.surface;
+        if (!surface)
+            return [];
+        const edges = [];
+        for (const id of this.revealed$.peek()) {
+            const edge = asTypedEdge(this._roles, surface.getElementById(id));
+            // The ADR's guard: an edge bound to nothing relates nothing, so it says
+            // nothing at all.
+            if (edge && edgeIsBound(edge.model))
+                edges.push(edge);
+        }
+        return edges;
+    }
+    mounted() {
+        // No framework loaded => no vocabulary => no typed edge can exist. The
+        // cheapest possible exit, taken once.
+        if (this._roles.length === 0)
+            return;
+        this._subscriptions.push(this.event.on('pointermove', context => {
+            this._hover(context.event.x, context.event.y);
+        }), 
+        // Dragging is not reading: the mark would follow the pointer around and
+        // say nothing about the edge underneath it.
+        //
+        // No `pointerleave` handler, deliberately: nothing in this editor
+        // DISPATCHES that event to interactivity extensions (`DefaultTool` emits
+        // `pointerdown` and `pointermove`), so subscribing to it would be a line
+        // that reads like a guarantee and delivers nothing. Leaving the canvas
+        // with the pointer keeps the last hover until the next move or the next
+        // selection change, which is what the board already does with every other
+        // hover affordance.
+        this.event.on('dragstart', () => this._setHovered(null)));
+        const selection = this.gfx.selection.slots.updated.subscribe(() => this._sync());
+        this._subscriptions.push(() => selection.unsubscribe());
+        // An EFFECT over both signals rather than a subscription to the tool name:
+        // `setTool` writes the name BEFORE the options, and the two Wardley
+        // connector tools share one name ('connector') and differ only by their
+        // `role` option — so a name subscription would read a stale role, and would
+        // not fire at all when the user switches from the link tool to the arrow.
+        this._subscriptions.push(effect(() => {
+            const armed = this.gfx.tool.currentToolName$.value;
+            const option = this.gfx.tool.currentToolOption$.value;
+            this._syncArmed(armed === 'connector' ? option?.options?.role : undefined);
+        }));
+    }
+    unmounted() {
+        for (const dispose of this._subscriptions)
+            dispose();
+        this._subscriptions = [];
+        this._hovered = null;
+        this.revealed$.value = [];
+        this.armedHint$.value = null;
+        super.unmounted();
+    }
+    _hover(vx, vy) {
+        // Hovering is a READING gesture: while a tool is armed the user is drawing,
+        // and the hint (M1) is what speaks then.
+        if (this.gfx.tool.currentToolName$.peek() !== 'default') {
+            this._setHovered(null);
+            return;
+        }
+        const [x, y] = this.gfx.viewport.toModelCoord(vx, vy);
+        const hits = this.gfx.getElementByPoint(x, y, { all: true });
+        let found = null;
+        // Topmost first: the last hit is the element the pointer is aiming at.
+        for (let i = hits.length - 1; i >= 0; i--) {
+            const edge = asTypedEdge(this._roles, hits[i]);
+            if (edge && edgeIsBound(edge.model)) {
+                found = edge.model.id;
+                break;
+            }
+        }
+        this._setHovered(found);
+    }
+    _setHovered(id) {
+        if (this._hovered === id)
+            return;
+        this._hovered = id;
+        this._sync();
+    }
+    _syncArmed(role) {
+        const direction = role === undefined ? undefined : directionOfRole(this._roles, role);
+        const key = direction?.gestureHintKey;
+        const next = key === undefined
+            ? null
+            : {
+                key,
+                ...(direction?.gestureHintFallback !== undefined
+                    ? { fallback: direction.gestureHintFallback }
+                    : {}),
+            };
+        if ((this.armedHint$.peek()?.key ?? null) === (next?.key ?? null))
+            return;
+        this.armedHint$.value = next;
+    }
+    /** Recompute hover ∪ selection, and publish only when it actually changed. */
+    _sync() {
+        const ids = [];
+        if (this._hovered)
+            ids.push(this._hovered);
+        for (const element of this.gfx.selection.selectedElements) {
+            const edge = asTypedEdge(this._roles, element);
+            if (edge && edgeIsBound(edge.model) && !ids.includes(edge.model.id)) {
+                ids.push(edge.model.id);
+            }
+        }
+        const current = this.revealed$.peek();
+        if (ids.length === current.length &&
+            ids.every((id, i) => id === current[i])) {
+            return;
+        }
+        this.revealed$.value = ids;
+    }
+}

package/dist/_pkgs/affine-gfx-connector/direction/direction-widget.d.ts

@@ -0,0 +1,65 @@
+import type { RootBlockModel } from '../../affine-model/index.js';
+import { WidgetComponent } from '../../std/index.js';
+import { nothing } from 'lit';
+export declare const EDGE_DIRECTION_WIDGET = "affine-edge-direction-widget";
+/**
+ * The PROSE of `docs/adr/0010`'s M1 and M2, on the pattern
+ * `violation-detail-widget` established one directory away — and, since the
+ * chevron was folded into the label, the whole of what M2 draws.
+ *
+ * Two things, both of them WORDS and therefore both of them here rather than on
+ * the canvas (a tooltip rendered at a quarter size is not a smaller tooltip, it
+ * is an unreadable one):
+ *
+ * - **M2** — while a typed edge is hovered or selected, the role's VERB laid
+ *   along the link: `depends on`, in a box that ends in a point aimed at the
+ *   provider. Since the PO acceptance of 02/08/2026 this is the only mark the
+ *   reveal draws; the canvas chevron it used to sit on top of is folded into
+ *   that point (see `direction-reveal.ts`). Since the second pass of the same
+ *   recette it is the verb ALONE: the full sentence was longer than the links
+ *   it was laid on, so it covered the very components it named — and those
+ *   names are already drawn at both ends of the line.
+ * - **M1** — while a tool that draws a typed edge is armed, the sentence that
+ *   tells the user which way to drag. That is what turns the direction their
+ *   gesture writes into a statement they made.
+ *
+ * It knows no framework: the verb is a key declared by a ROLE
+ * (`EdgeDirectionDef`) and resolved through the host's catalogue.
+ */
+export declare class EdgeDirectionWidget extends WidgetComponent<RootBlockModel> {
+    static styles: import("lit").CSSResult;
+    private accessor _revealed;
+    private accessor _hint;
+    get gfx(): import("../../std/gfx/controller.js").GfxController;
+    private get _manager();
+    /**
+     * Idempotent wiring, called from both `firstUpdated` and a later
+     * `connectedCallback`: `WithDisposable` throws its group away on disconnect
+     * while lit runs `firstUpdated` once, so wiring done only there never comes
+     * back if the widget is detached and re-attached.
+     */
+    private _wire;
+    connectedCallback(): void;
+    firstUpdated(): void;
+    /**
+     * The word a revealed edge is labelled with, in the framework's own words —
+     * the role's verb, said in the host's language.
+     *
+     * `''` when the role declares neither verb nor label, in which case the
+     * caller draws nothing at all.
+     */
+    private _verbFor;
+    private _renderLabel;
+    /**
+     * The armed tool's hint, centred near the bottom of the EDITOR VIEWPORT —
+     * above the toolbar, where the user's eyes already are while they aim.
+     *
+     * The viewport rect is the only frame available to a widget host that is a
+     * zero-sized box at its origin, and it is the one the other canvas
+     * affordances measure against (`violation-detail-widget` flips its bubble
+     * against `viewport.width` / `viewport.height` the same way).
+     */
+    private _renderHint;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
+}
+export declare const edgeDirectionWidget: import("../../store/index.js").ExtensionType;