@formicoidea/labre-core 0.31.0 → 0.33.0

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

@@ -0,0 +1,45 @@
+import type { ConnectorElementModel } from '../../affine-model/index.js';
+import type { GfxModel } from '../../std/gfx/index.js';
+import { InteractivityExtension } from '../../std/gfx/index.js';
+import type { ExtensionType } from '../../store/index.js';
+/**
+ * Spotlight-on-hover: a framework background element ("host") grants the
+ * elements laid inside its bounds a dependency-reading behavior — hovering a
+ * node (or a connector) spotlights it together with its connected elements and
+ * fades everything else inside the host.
+ *
+ * Any framework can opt in by registering its background element type:
+ *
+ * ```ts
+ * context.register(SpotlightHostExtension('edgy'));
+ * ```
+ *
+ * The fading uses `element.opacity`, a `@local()` field — no CRDT write, no
+ * undo entry, no sync.
+ */
+export declare const SpotlightHostIdentifier: import("../../global/di/types.js").ServiceIdentifier<string> & (<U extends string = string>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+export declare function SpotlightHostExtension(elementType: string): ExtensionType;
+/**
+ * The ids to keep at full opacity when `target` is hovered: the target, its
+ * connectors and their opposite endpoints (or, for a hovered connector, its
+ * two endpoints). Pure — exported for unit tests.
+ */
+export declare function spotlightSet(target: GfxModel, getConnectors: (id: string) => ConnectorElementModel[]): Set<string>;
+export declare class SpotlightManager extends InteractivityExtension {
+    static key: string;
+    /** Elements currently faded, restored on leave. */
+    private _dimmed;
+    private _lastTargetId;
+    /** Pending debounced transition (apply or restore). */
+    private _pending;
+    private _schedule;
+    private _cancelPending;
+    private get _hostTypes();
+    private get _surface();
+    mounted(): void;
+    unmounted(): void;
+    private _update;
+    private _apply;
+    private _restoreDim;
+    private _restoreNow;
+}

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

@@ -0,0 +1,177 @@
+import { createIdentifier } from '../../global/di/index.js';
+import { GfxPrimitiveElementModel, InteractivityExtension, } from '../../std/gfx/index.js';
+/**
+ * Spotlight-on-hover: a framework background element ("host") grants the
+ * elements laid inside its bounds a dependency-reading behavior — hovering a
+ * node (or a connector) spotlights it together with its connected elements and
+ * fades everything else inside the host.
+ *
+ * Any framework can opt in by registering its background element type:
+ *
+ * ```ts
+ * context.register(SpotlightHostExtension('edgy'));
+ * ```
+ *
+ * The fading uses `element.opacity`, a `@local()` field — no CRDT write, no
+ * undo entry, no sync.
+ */
+export const SpotlightHostIdentifier = createIdentifier('SpotlightHost');
+export function SpotlightHostExtension(elementType) {
+    return {
+        setup: di => {
+            di.addImpl(SpotlightHostIdentifier(elementType), () => elementType);
+        },
+    };
+}
+const isConnector = (el) => 'type' in el && el.type === 'connector';
+/**
+ * The ids to keep at full opacity when `target` is hovered: the target, its
+ * connectors and their opposite endpoints (or, for a hovered connector, its
+ * two endpoints). Pure — exported for unit tests.
+ */
+export function spotlightSet(target, getConnectors) {
+    const keep = new Set([target.id]);
+    if (isConnector(target)) {
+        if (target.source?.id)
+            keep.add(target.source.id);
+        if (target.target?.id)
+            keep.add(target.target.id);
+        return keep;
+    }
+    for (const connector of getConnectors(target.id)) {
+        keep.add(connector.id);
+        if (connector.source?.id)
+            keep.add(connector.source.id);
+        if (connector.target?.id)
+            keep.add(connector.target.id);
+    }
+    return keep;
+}
+/** Delay before a new spotlight is applied / cleared, so brushing across
+ * elements doesn't flash the fade on and off. */
+const SPOTLIGHT_DELAY_MS = 140;
+export class SpotlightManager extends InteractivityExtension {
+    constructor() {
+        super(...arguments);
+        /** Elements currently faded, restored on leave. */
+        this._dimmed = [];
+        this._lastTargetId = null;
+        /** Pending debounced transition (apply or restore). */
+        this._pending = null;
+    }
+    static { this.key = 'spotlight-manager'; }
+    _schedule(action) {
+        if (this._pending)
+            clearTimeout(this._pending);
+        this._pending = setTimeout(() => {
+            this._pending = null;
+            action();
+        }, SPOTLIGHT_DELAY_MS);
+    }
+    _cancelPending() {
+        if (this._pending) {
+            clearTimeout(this._pending);
+            this._pending = null;
+        }
+    }
+    get _hostTypes() {
+        return Array.from(this.std.provider.getAll(SpotlightHostIdentifier).values());
+    }
+    get _surface() {
+        return this.gfx.surface;
+    }
+    mounted() {
+        this.event.on('pointermove', context => {
+            this._update(context.event.x, context.event.y);
+        });
+        this.event.on('pointerleave', () => this._restoreNow());
+        this.event.on('dragstart', () => this._restoreNow());
+    }
+    unmounted() {
+        this._restoreNow();
+        super.unmounted();
+    }
+    _update(vx, vy) {
+        const hostTypes = this._hostTypes;
+        const surface = this._surface;
+        if (!hostTypes.length || !surface)
+            return;
+        if (this.gfx.tool.currentToolName$.peek() !== 'default') {
+            this._restoreNow();
+            return;
+        }
+        const [x, y] = this.gfx.viewport.toModelCoord(vx, vy);
+        // Connectors sit above the nodes they link (inserted later): when both are
+        // under the pointer, the user is aiming at the node — prefer it.
+        const hits = this.gfx
+            .getElementByPoint(x, y, { all: true })
+            .filter((el) => el instanceof GfxPrimitiveElementModel &&
+            !hostTypes.includes(el.type) &&
+            (el.connectable || isConnector(el)));
+        let target = null;
+        for (let i = hits.length - 1; i >= 0; i--) {
+            if (!isConnector(hits[i])) {
+                target = hits[i];
+                break;
+            }
+        }
+        if (!target && hits.length)
+            target = hits[hits.length - 1];
+        // The behavior is granted by a host whose bounds contain the target —
+        // unless that host opted out (`spotlightEnabled: false`, toolbar toggle).
+        const host = target
+            ? surface.elementModels.find(el => hostTypes.includes(el.type) &&
+                el.spotlightEnabled !== false &&
+                el.elementBound.contains(target.elementBound))
+            : null;
+        if (!target || !host) {
+            // Debounced restore: brushing across the gaps between elements must not
+            // flash the fade off and on.
+            if (this._lastTargetId !== null)
+                this._schedule(() => this._apply(null));
+            else
+                this._cancelPending();
+            return;
+        }
+        if (target.id === this._lastTargetId) {
+            // Still on the applied target: keep the spotlight steady.
+            this._cancelPending();
+            return;
+        }
+        const finalTarget = target;
+        const finalHost = host;
+        this._schedule(() => this._apply(finalTarget, finalHost));
+    }
+    _apply(target, host) {
+        const surface = this._surface;
+        this._restoreDim();
+        if (!target || !host || !surface) {
+            this._lastTargetId = null;
+            return;
+        }
+        this._lastTargetId = target.id;
+        const hostTypes = this._hostTypes;
+        const keep = spotlightSet(target, id => surface.getConnectors(id));
+        for (const el of surface.elementModels) {
+            if (el === host || hostTypes.includes(el.type) || keep.has(el.id)) {
+                continue;
+            }
+            if (host.elementBound.contains(el.elementBound)) {
+                el.opacity = 0.2;
+                this._dimmed.push(el);
+            }
+        }
+    }
+    _restoreDim() {
+        if (!this._dimmed.length)
+            return;
+        for (const el of this._dimmed)
+            el.opacity = 1;
+        this._dimmed = [];
+    }
+    _restoreNow() {
+        this._cancelPending();
+        this._lastTargetId = null;
+        this._restoreDim();
+    }
+}

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

@@ -0,0 +1,107 @@
+import type { InterchangeImportContext, InterchangeImportResult } from './interchange.js';
+/**
+ * **SVG → a canvas sketch.** The platform's VISUAL-tier importer, shared by
+ * every framework that declares it (`docs/adr/0012`, P2).
+ *
+ * ## The heuristics statement, and its known failure modes
+ *
+ * _This paragraph is ADR 0012's open question 2 — "each visual capability owes
+ * a one-paragraph statement of its heuristics and its known failure modes" —
+ * answered ONCE, here, because every framework that declares `…:svg:import`
+ * wraps this one function and therefore owes the same statement. It is
+ * referenced by `bpmn:svg:import` and by `wardley:svg:import`; a framework that
+ * ever wants a narrower or wider guess writes its own parser and its own
+ * paragraph beside it._
+ *
+ * **What it guesses.** An SVG carries a rendering, not a model, so this reader
+ * recognises GEOMETRY and nothing else: `<rect>` becomes a rectangle,
+ * `<circle>` and `<ellipse>` an ellipse, `<polygon>` a polygon, `<line>`,
+ * `<polyline>` and `<path>` a brush stroke sampled at its vertices, and
+ * `<text>` an editable free-text element. Fill, stroke, stroke width, font size
+ * and text anchor are carried across where the shape model has a direct
+ * equivalent, with CSS inheritance down `<g>` honoured and colours passed
+ * through verbatim. Coordinates are user units placed by the outermost
+ * viewport: the `viewBox` origin is subtracted and the `viewBox`-to-`width`
+ * scale is applied uniformly (`min(width / viewBox width, height / viewBox
+ * height)`, which is what the default `preserveAspectRatio` means), then every
+ * `translate(…)` on the way down. Everything it emits is an ADR 0007 **level 1**
+ * element — a plain shape on the free surface, which the author then PROMOTES.
+ * It recognises no role, no relation and no framework vocabulary, and it never
+ * claims to: a Wardley component and a text box are both `<rect>` plus
+ * `<text>`, and deciding which is which is the one question only the author can
+ * answer.
+ *
+ * **Where it is known to be wrong, and the list is meant to be complete.** A
+ * `scale`, `rotate`, `matrix` or `skew` transform is IGNORED rather than
+ * applied, so anything under one lands at its untransformed position and size.
+ * Curves (`C`, `S`, `Q`, `T`, `A`) are flattened to their endpoints, so a
+ * rounded connector arrives as a polyline through its anchor points and an arc
+ * that doubles back arrives as a straight line. A `<path>` that outlines a
+ * filled region (an arrowhead, an icon glyph) arrives as an open stroke, not as
+ * a filled shape. `<image>`, `<defs>`, `<marker>`, gradients, filters,
+ * `<clipPath>` and `<mask>` are skipped by the reader, and `<use>` and
+ * `<foreignObject>` never reach it at all — the SANITIZER removes them, because
+ * they are two of the constructs an SVG can carry code in. A `<style>` sheet is
+ * skipped, and that one is worth naming twice: mermaid paints almost entirely
+ * through CSS classes, so a mermaid SVG arrives in the initial colours — mostly
+ * black — with only the note to say why. `<title>`, `<desc>` and `<metadata>`
+ * are dropped in silence, deliberately and as the only exception to the rule
+ * below: they render nothing, so there is nothing to have lost.
+ *
+ * **What this reader alters without a note, because a note could not help.**
+ * Text width and height are ESTIMATED from the font size and the character
+ * count, because measuring text needs a font a pure function of a string is not
+ * allowed to have, so a label box is approximately and not exactly the size it
+ * was. Whitespace inside a label is collapsed to single spaces and trimmed
+ * (`xml:space="preserve"` is not honoured). A `<tspan>`'s own `x`/`y`, its `dx`
+ * / `dy` offsets and `dominant-baseline` are ignored, so a label laid out span
+ * by span arrives as plain stacked lines in document order. `stroke-dasharray`
+ * is not read, so a dashed line arrives solid. `em` font sizes are resolved
+ * against the inherited size only, with no font-relative refinement.
+ *
+ * **Everything else is reported.** Every OTHER construct this reader ignores,
+ * alters or cannot resolve produces exactly one `warning` note per KIND — never
+ * one per instance — so a result that looks empty always says why.
+ *
+ * ## What it never does
+ *
+ * **It writes no `interchange` payload, on any element, ever** — P2's hard
+ * rule, pinned by an anti-decay test in this package's own spec. There is
+ * nothing to preserve that the elements do not already carry: an SVG round-trip
+ * would be a re-render rather than a round-trip, and a payload would advertise
+ * a promise this tier deliberately does not make. `carried` and `quarantined`
+ * are therefore `0` in every report it returns, and the surface that offers the
+ * import must say all of this BEFORE the file is read.
+ *
+ * ## Pure, and framework-agnostic
+ *
+ * Text in, serialized element props out (P3): no `std`, no surface, no DI, so
+ * labre-mcp calls the very same function the editor commands call. It produces
+ * only generic `shape` / `text` / `brush` props and knows the name of no
+ * framework — which is exactly why several frameworks can declare it. ADR 0012
+ * explicitly rejects inferring one framework from a `.svg`, so the capability
+ * is declared per framework and this parser is what each of them wraps.
+ */
+/**
+ * The format id. Never used as a payload key, unlike every semantic format's —
+ * a visual import writes no payload at all — but it is what the report's
+ * headline calls itself ("SVG imported"), and what the registry's triple is
+ * built from.
+ */
+export declare const SVG_SKETCH_FORMAT_ID = "svg";
+export declare const SVG_SKETCH_EXTENSION = ".svg";
+export declare const SVG_SKETCH_MIME = "image/svg+xml";
+/**
+ * An SVG file as a canvas sketch — the shared VISUAL-tier importer.
+ *
+ * See this module's own documentation for the heuristics statement and the
+ * known failure modes (ADR 0012, open question 2). The contract in one
+ * sentence: the picture arrives as editable elements, and nothing else is
+ * promised.
+ *
+ * A blank or unrecognisable drawing is `0` elements and a note, NOT an
+ * exception: the file was read, it simply held nothing this reader draws, and a
+ * throw would show the user an error toast where the truth is a remark.
+ * Malformed XML is the exception, because then the file was not read at all.
+ */
+export declare function parseSvgSketch(source: string, context?: InterchangeImportContext): InterchangeImportResult;