@formicoidea/labre-core 0.30.1 → 0.32.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/surface-middleware.d.ts

@@ -1,5 +1,5 @@
 import type { ExtensionType } from '../../store/index.js';
-import type { SurfaceBlockModel } from '../surface-model';
+import type { SurfaceBlockModel } from '../surface-model.js';
 export type SurfaceMiddleware = (surface: SurfaceBlockModel) => () => void;
 export declare const surfaceMiddlewareIdentifier: import("../../global/di/types.js").ServiceIdentifier<{
     middleware: SurfaceMiddleware;

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

@@ -0,0 +1,10 @@
+import { type ToolbarModuleConfig } from '../../affine-shared/services/index.js';
+import type { RoleDefs } from '../../std/gfx/index.js';
+/**
+ * The toolbar module, parameterized by the framework's role vocabulary.
+ *
+ * @param roles The registrar's `RoleDefs`. Specialisation is resolved against
+ *   it, so a tag declared on `wardley:component` reaches `wardley:market` for
+ *   free.
+ */
+export declare function tagsToolbarConfig(roles: RoleDefs): ToolbarModuleConfig;

package/dist/_pkgs/affine-block-surface/extensions/tags-toolbar.js

@@ -0,0 +1,295 @@
+import { EditorChevronDown } from '../../affine-components/toolbar/index.js';
+import { getUniverseRegistry, translateKey, } from '../../affine-shared/services/index.js';
+import { getRegisteredCommands, runCommand } from '../../std/index.js';
+import { elementTagValues, GfxGroupLikeElementModel, GfxPrimitiveElementModel, } from '../../std/gfx/index.js';
+import { html, nothing } from 'lit';
+/** The command this module drives. Spelled once. */
+const TAG_SET_ID = 'tag.set';
+/**
+ * The **type-3 qualification** entry of an element's contextual toolbar
+ * (MF3, ADR 0007 § 6, rung "component → materialities").
+ *
+ * Select a Wardley component and its toolbar gains a dropdown naming the
+ * element's nature, and offering the others. Every tag whose `appliesTo`
+ * reaches the element's role gets its own titled section in the same dropdown —
+ * one more block in the menu, never another toolbar button competing for width.
+ *
+ * ## Generic in shape, Wardley-only in registration — and why
+ *
+ * Nothing in this file names a framework, a type or a role: the sections are
+ * built from whatever `UniverseTagDefsProvider` was seeded with, resolved
+ * against the role vocabulary the REGISTRAR supplies. That parameter is the
+ * whole reason this is not registered once for the whole editor: roles are
+ * lib-side data modules owned by the framework that renders them
+ * (`WARDLEY_ROLES`), and ADR 0007 § 2bis deliberately kept them OUT of the DI
+ * registry — so there is no way to ask "which role vocabulary governs this
+ * element" without a registry the ADR chose not to build.
+ *
+ * The honest consequence is stated rather than hidden: a second framework gets
+ * this dropdown by registering {@link tagsToolbarConfig} with its own
+ * `RoleDefs`, exactly as `validationToolbarConfig` is registered per framework
+ * with its own rules. Turning that parameter into a lookup is a change to ADR
+ * 0007, not to this file.
+ *
+ * ## Which element gets the entry
+ *
+ * The one that CARRIES the role. Framework artefacts on this canvas are
+ * composites — a Wardley component is an ellipse and a free text grouped
+ * together — so a single click selects the GROUP, which carries no role of its
+ * own. Rather than making the user enter the group to find the qualification,
+ * the target resolves through the group to its single role-bearing member. Two
+ * role-bearing members means the group is not one artefact, and no honest
+ * "current value" exists, so there is no entry.
+ *
+ * ## Gating
+ *
+ * Registered by a framework's FLAG-GATED view extension, like its rules and its
+ * profiles: qualifying is tooling. Flag off, there is no dropdown — and the tag
+ * ids already written on an element go unread until the flag comes back, which
+ * costs nothing, because they were never needed to load or paint anything.
+ */
+/** The tick on a selected value, drawn inline like the neighbouring modules'. */
+const CheckIcon = html `<svg
+  width="20"
+  height="20"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M5 12.5l4.5 4.5L19 7.5" />
+</svg>`;
+/**
+ * The elements one selection could possibly be about: the selected element
+ * itself, plus — when it is a canvas group — its direct members.
+ *
+ * One selected element only: a qualification is one decision about one thing,
+ * and a multi-selection spanning two roles has no honest current value to show.
+ *
+ * Descending ONE level into a group is deliberate. Framework artefacts on this
+ * canvas are composites — a Wardley component is an ellipse and a free text
+ * grouped together — so a single click selects the group, and making the user
+ * enter it to find the qualification would bury the affordance. Going deeper,
+ * through a group OF components, would ask a question with several right
+ * answers.
+ */
+function candidates(ctx) {
+    const models = ctx.getSurfaceModels();
+    if (models.length !== 1)
+        return [];
+    const [model] = models;
+    if (!(model instanceof GfxPrimitiveElementModel))
+        return [];
+    const found = model.role ? [model] : [];
+    if (model instanceof GfxGroupLikeElementModel) {
+        for (const child of model.childElements) {
+            if (child instanceof GfxPrimitiveElementModel && child.role) {
+                found.push(child);
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The selection, if there is exactly one thing in it to qualify.
+ *
+ * The discriminator is **applicability, not roledness**. A Wardley component's
+ * group holds two roled members — the node and its label — and only one of them
+ * is something a nature is a fact about; filtering on "carries a role" would
+ * make the entry vanish on the very artefact it exists for. So a candidate
+ * counts only when a seeded tag actually applies to its role, and two such
+ * candidates means the group is not one artefact and there is no entry.
+ *
+ * A role with no applicable tag — every role of a framework that seeded no pack
+ * — yields nothing either: a picker with nothing in it is chrome that decides
+ * nothing.
+ */
+function tagTarget(ctx, roles) {
+    const registry = getUniverseRegistry(ctx.std);
+    const qualifiable = candidates(ctx)
+        .map(element => ({
+        element,
+        role: element.role,
+        tags: registry
+            .tagsForRole(element.role, roles)
+            .filter(def => !def.deprecated),
+    }))
+        .filter(candidate => candidate.tags.length > 0);
+    return qualifiable.length === 1 ? qualifiable[0] : null;
+}
+/**
+ * The values offered for one tag: its defined ones, plus anything the element
+ * already carries that no def explains.
+ *
+ * The second half is the point. Defs are runtime configuration and are never
+ * persisted, so a document may carry a value whose pack was removed, renamed or
+ * never seeded in this deployment. Hiding it would make the element look
+ * unqualified and let the next click destroy a colleague's work silently; it is
+ * shown as its raw id instead, and stays removable. Deprecated values follow
+ * the same rule: out of the picker, still shown when present.
+ */
+function offeredValues(def, selected) {
+    const defined = def.values === 'open' ? [] : def.values;
+    const offered = defined.filter(value => !value.deprecated || selected.includes(value.id));
+    const known = new Set(defined.map(value => value.id));
+    const unknown = selected
+        .filter(id => !known.has(id))
+        .map(id => ({ id, label: id }));
+    return [...offered, ...unknown];
+}
+/**
+ * Toggle one value of one tag on the target, through the `tag.set` command.
+ *
+ * The command owns the write, the read-only guard, the undo checkpoint and the
+ * telemetry; this is the gesture and nothing else. Going through `runCommand`
+ * rather than calling the model directly is what keeps one gesture one event,
+ * and what makes the same operation reachable from the palette and the agent.
+ */
+function toggleValue(ctx, target, def, valueId) {
+    const current = elementTagValues(target.element, def.id);
+    const selected = current.includes(valueId);
+    const values = selected
+        ? current.filter(id => id !== valueId)
+        : def.cardinality === 'single'
+            ? // One tag, one answer: picking a nature replaces the previous one
+                // rather than accumulating. Where practitioners disagree, the
+                // disagreement is the finding — it must not hide inside the element.
+                [valueId]
+            : [...current, valueId];
+    runTagSet(ctx, target, def.id, values);
+}
+/**
+ * Invoke `tag.set` on the resolved target.
+ *
+ * Through the registry rather than by importing the command: this package is
+ * below `@labre/affine-block-root` in the dependency order, and going through
+ * `runCommand` is also what keeps one gesture one telemetry event whatever the
+ * surface. A build with the command unregistered simply has no working entry —
+ * never a throw on click.
+ *
+ * `elementIds` is passed EXPLICITLY rather than letting the command fall back
+ * to the live selection: the element being qualified is often a group member,
+ * not the group the user selected, and the command must write where the toolbar
+ * said, not where the canvas points.
+ */
+function runTagSet(ctx, target, tag, values) {
+    const command = getRegisteredCommands(ctx.std).find(c => c.id === TAG_SET_ID);
+    if (!command)
+        return;
+    runCommand(ctx.std, command, { surface: 'palette', source: 'toolbar:general' }, { tag, values, elementIds: [target.element.id] });
+}
+/** One titled block of the dropdown — one tag. */
+function renderSection(ctx, target, def) {
+    const selected = elementTagValues(target.element, def.id);
+    const label = def.label || def.id;
+    const options = offeredValues(def, selected).map(value => {
+        const on = selected.includes(value.id);
+        const valueLabel = value.label || value.id;
+        return html `<editor-menu-action
+      data-testid="element-tag-option"
+      data-tag-id=${def.id}
+      data-value-id=${value.id}
+      data-selected=${on ? 'true' : nothing}
+      aria-label=${valueLabel}
+      aria-pressed=${on}
+      @click=${() => toggleValue(ctx, target, def, value.id)}
+    >
+      ${on ? CheckIcon : html `<span style="width: 20px;"></span>`}
+      <span class="label">${valueLabel}</span>
+    </editor-menu-action>`;
+    });
+    return html `<div
+    role="group"
+    aria-label=${label}
+    data-testid="element-tag-section"
+    data-tag-id=${def.id}
+    style="display: flex; flex-direction: column;"
+  >
+    <div
+      style="padding: 4px 8px; font-size: 12px; color: var(--affine-text-secondary-color);"
+    >
+      ${label}
+    </div>
+    ${options}
+  </div>`;
+}
+/**
+ * The dropdown's trigger text: the values in force when there are any, so the
+ * qualification is readable without opening anything, and the generic label
+ * otherwise.
+ */
+function triggerLabel(ctx, target) {
+    const chosen = target.tags.flatMap(def => {
+        const selected = elementTagValues(target.element, def.id);
+        return offeredValues(def, selected)
+            .filter(value => selected.includes(value.id))
+            .map(value => value.label || value.id);
+    });
+    return chosen.length
+        ? chosen.join(', ')
+        : // One applicable tag names itself ("Nature"); several fall back to the
+            // neutral word, since no single tag name is the truth about the element.
+            target.tags.length === 1
+                ? target.tags[0].label || target.tags[0].id
+                : translateKey(ctx.std, 'com.labre.tags.toolbar.label', 'Qualify');
+}
+/**
+ * The toolbar module, parameterized by the framework's role vocabulary.
+ *
+ * @param roles The registrar's `RoleDefs`. Specialisation is resolved against
+ *   it, so a tag declared on `wardley:component` reaches `wardley:market` for
+ *   free.
+ */
+export function tagsToolbarConfig(roles) {
+    return {
+        actions: [
+            {
+                // After a framework's own per-instance toggles (`a.` … `d.`) and after
+                // the exception entry, before `z.validation`: what an element IS reads
+                // before how hard it is checked.
+                id: 'y.element-tags',
+                when: (ctx) => tagTarget(ctx, roles) !== null,
+                content(ctx) {
+                    const target = tagTarget(ctx, roles);
+                    if (!target)
+                        return null;
+                    const label = translateKey(ctx.std, 'com.labre.tags.toolbar.label', 'Qualify');
+                    // The testid sits on the HOST as well as on the trigger: the trigger
+                    // is handed to `editor-menu-button` as a property and rendered into
+                    // its shadow root, so the host is the only handle from the toolbar's
+                    // own DOM.
+                    return html `<editor-menu-button
+            data-testid="element-tags-entry"
+            .contentPadding=${'8px'}
+            .button=${html `
+              <editor-icon-button
+                data-testid="element-tags-button"
+                aria-label=${label}
+                .tooltip=${label}
+                .justify=${'space-between'}
+                .labelHeight=${'20px'}
+              >
+                <span class="label">${triggerLabel(ctx, target)}</span>
+                ${EditorChevronDown}
+              </editor-icon-button>
+            `}
+          >
+            <div
+              data-testid="element-tags-menu"
+              data-orientation="vertical"
+              data-size="large"
+            >
+              ${target.tags.map(def => renderSection(ctx, target, def))}
+            </div>
+          </editor-menu-button>`;
+                },
+            },
+        ],
+        // The whole module stands down unless the selection has something to be
+        // qualified with, so a framework registering it pays one resolution per
+        // selection change.
+        when: (ctx) => tagTarget(ctx, roles) !== null,
+    };
+}

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

@@ -0,0 +1,27 @@
+import { type ToolbarContext } from '../../affine-shared/services/index.js';
+import { type TemplateResult } from 'lit';
+/** Whether the dropdown has anything at all to offer for this selection. */
+declare function hasValidationMenu(ctx: ToolbarContext): boolean;
+export declare const validationToolbarConfig: {
+    readonly actions: [{
+        readonly id: "z.validation";
+        readonly when: typeof hasValidationMenu;
+        readonly content: (ctx: ToolbarContext) => TemplateResult<1> | null;
+    }];
+    readonly when: typeof hasValidationMenu;
+};
+export declare const validationExceptionToolbarConfig: {
+    readonly actions: [{
+        readonly id: "c.validation-revoke-exception";
+        readonly priority: -1;
+        readonly when: (ctx: ToolbarContext) => boolean;
+        readonly generate: (ctx: ToolbarContext) => {
+            label: string;
+            showLabel: true;
+            tooltip: string;
+            run: (runCtx: ToolbarContext) => void;
+        };
+    }];
+};
+export declare const validationExceptionToolbarExtension: import("../../store/index.js").ExtensionType;
+export {};