@formicoidea/labre-core 0.30.1 → 0.32.0

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

@@ -0,0 +1,109 @@
+import type { GfxPrimitiveElementModel } from '../../std/gfx/index.js';
+import type { ExtensionType } from '../../store/index.js';
+/**
+ * Map quality — the NUDGES half (PF7.10).
+ *
+ * A nudge is an expectation a framework holds and the tool cannot judge: "the
+ * map has a title that frames the study", "the map is legended". The content can
+ * exist without being good, so there is nothing to compute — and a rule that
+ * pretended to compute it would be the worst kind of validation, one that says
+ * "valid" about something it never looked at.
+ *
+ * So a nudge is declarative DATA, exactly like a rule, a role or a profile, and
+ * it is never evaluated by anything. It is presented as a CHECKLIST the user
+ * ticks, and ticking is the same gesture as granting an exception (PF8):
+ * **ticking is assuming**. The tool records that the user took responsibility;
+ * it never claims to have checked.
+ *
+ * ## Where the state lives
+ *
+ * On the framework's BACKGROUND element — `GfxPrimitiveElementModel.qualityChecklist`
+ * — for the same reason the validation profile does: two maps on one canvas are
+ * two independent pieces of work. It is one flat array of ids in a declared
+ * `@field()`, so it syncs, it undoes, it survives a copy and an export, and it
+ * needs no block schema change and no migration.
+ *
+ * It also survives the framework's flag going off and coming back, which is the
+ * whole point of storing it as document data rather than as tooling state: the
+ * flag takes the CHECKLIST away, never the decisions somebody recorded on it.
+ *
+ * ## Gating
+ *
+ * A framework registers its nudges from its FLAG-GATED view extension, beside
+ * its rules and its profiles: a checklist is tooling. Flag off, nothing is
+ * registered, the panel offers nothing, and the ids already written go unread
+ * until the flag comes back.
+ */
+/**
+ * One expectation, as data. Deliberately three fields: an id to persist, a key
+ * to translate, and the framework's own wording for a host that ships no
+ * catalogue for it — the same `labelKey` + `fallback` pair a profile and a
+ * background label already carry. The library never invents the wording of
+ * somebody else's expectation.
+ */
+export interface QualityNudge {
+    /** Stable id, namespaced by framework: `wardley.q1-title`. This is what is persisted. */
+    id: string;
+    /** Owning framework, `wardley`. A nudge never applies across frameworks. */
+    framework: string;
+    /** i18n key of the expectation, resolved by the host. */
+    labelKey: string;
+    /** The framework's own wording, when the host ships no catalogue for the key. */
+    fallback?: string;
+    /** Ascending rank in the checklist. Ties keep declaration order. */
+    order?: number;
+}
+/** A framework registers its nudges here; nothing else registers nudges. */
+export declare const QualityNudgeIdentifier: import("../../global/di/types.js").ServiceIdentifier<QualityNudge> & (<U extends QualityNudge = QualityNudge>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Register a framework's nudges. Call it from the FLAG-GATED view extension,
+ * beside {@link ValidationRuleExtension}.
+ *
+ * ```ts
+ * context.register(QualityNudgeExtension(WARDLEY_NUDGES));
+ * ```
+ */
+export declare function QualityNudgeExtension(nudges: readonly QualityNudge[]): ExtensionType;
+/**
+ * The nudge ids ticked on `element` — always an array, never a copy to keep.
+ *
+ * The value comes out of a Y.Map, so it is whatever a peer wrote: a client that
+ * got it wrong must not break the panel on this one. Non-string members are
+ * dropped rather than shown, for the same reason.
+ */
+export declare function checkedNudges(element: GfxPrimitiveElementModel): readonly string[];
+/** Whether `nudgeId` is ticked on `element`. */
+export declare function isNudgeChecked(element: GfxPrimitiveElementModel, nudgeId: string): boolean;
+/**
+ * Tick or untick `nudgeId` on `element`.
+ *
+ * The write goes through the declared `@field()` accessor, so it lands in the
+ * Y.Map, syncs to every peer, joins the undo stack and survives a copy — see the
+ * note on `GfxPrimitiveElementModel.qualityChecklist`.
+ *
+ * Unticking the LAST one removes the key rather than leaving an empty array
+ * behind: assigning `[]` through the accessor would keep a key in the Y.Map,
+ * invisible in the panel but synced to every peer and shipped in every snapshot.
+ * `clearField` removes it, so an element whose checklist was emptied really is
+ * indistinguishable from one that never had a nudge ticked — in the document,
+ * and not just in this tab. Exactly what `revokeException` does with the last
+ * exception (PF8).
+ *
+ * ## Read-only is enforced HERE, not only in the panel
+ *
+ * The house convention for these writes: the seam guards itself
+ * (`setProfile`, `setException`, `revokeExceptionsOn` all do). A `disabled`
+ * checkbox is a UI promise and covers exactly one caller; an agent, a host or a
+ * future surface reaching this function directly would have no net at all. And
+ * the failure is not a no-op: `clearField` goes through `Store.transact`, which
+ * — unlike `addBlock` / `updateBlock` / `deleteBlock` — carries no read-only
+ * guard of its own, so unticking would genuinely delete the key from a document
+ * the user cannot edit.
+ *
+ * The store is reached through the element's own surface. An element not yet
+ * attached to one carries no document to protect and is written normally, which
+ * is what a unit fixture is.
+ *
+ * @returns whether the document actually changed.
+ */
+export declare function setNudgeChecked(element: GfxPrimitiveElementModel, nudgeId: string, checked: boolean): boolean;

package/dist/_pkgs/affine-block-surface/extensions/map-quality.js

@@ -0,0 +1,84 @@
+import { createIdentifier } from '../../global/di/index.js';
+/** A framework registers its nudges here; nothing else registers nudges. */
+export const QualityNudgeIdentifier = createIdentifier('QualityNudge');
+/**
+ * Register a framework's nudges. Call it from the FLAG-GATED view extension,
+ * beside {@link ValidationRuleExtension}.
+ *
+ * ```ts
+ * context.register(QualityNudgeExtension(WARDLEY_NUDGES));
+ * ```
+ */
+export function QualityNudgeExtension(nudges) {
+    return {
+        setup: di => {
+            for (const nudge of nudges) {
+                di.addImpl(QualityNudgeIdentifier(nudge.id), () => nudge);
+            }
+        },
+    };
+}
+/**
+ * The nudge ids ticked on `element` — always an array, never a copy to keep.
+ *
+ * The value comes out of a Y.Map, so it is whatever a peer wrote: a client that
+ * got it wrong must not break the panel on this one. Non-string members are
+ * dropped rather than shown, for the same reason.
+ */
+export function checkedNudges(element) {
+    const stored = element.qualityChecklist;
+    if (!Array.isArray(stored))
+        return [];
+    return stored.filter((id) => typeof id === 'string');
+}
+/** Whether `nudgeId` is ticked on `element`. */
+export function isNudgeChecked(element, nudgeId) {
+    return checkedNudges(element).includes(nudgeId);
+}
+/**
+ * Tick or untick `nudgeId` on `element`.
+ *
+ * The write goes through the declared `@field()` accessor, so it lands in the
+ * Y.Map, syncs to every peer, joins the undo stack and survives a copy — see the
+ * note on `GfxPrimitiveElementModel.qualityChecklist`.
+ *
+ * Unticking the LAST one removes the key rather than leaving an empty array
+ * behind: assigning `[]` through the accessor would keep a key in the Y.Map,
+ * invisible in the panel but synced to every peer and shipped in every snapshot.
+ * `clearField` removes it, so an element whose checklist was emptied really is
+ * indistinguishable from one that never had a nudge ticked — in the document,
+ * and not just in this tab. Exactly what `revokeException` does with the last
+ * exception (PF8).
+ *
+ * ## Read-only is enforced HERE, not only in the panel
+ *
+ * The house convention for these writes: the seam guards itself
+ * (`setProfile`, `setException`, `revokeExceptionsOn` all do). A `disabled`
+ * checkbox is a UI promise and covers exactly one caller; an agent, a host or a
+ * future surface reaching this function directly would have no net at all. And
+ * the failure is not a no-op: `clearField` goes through `Store.transact`, which
+ * — unlike `addBlock` / `updateBlock` / `deleteBlock` — carries no read-only
+ * guard of its own, so unticking would genuinely delete the key from a document
+ * the user cannot edit.
+ *
+ * The store is reached through the element's own surface. An element not yet
+ * attached to one carries no document to protect and is written normally, which
+ * is what a unit fixture is.
+ *
+ * @returns whether the document actually changed.
+ */
+export function setNudgeChecked(element, nudgeId, checked) {
+    if (element.surface?.store?.readonly)
+        return false;
+    const current = checkedNudges(element);
+    if (current.includes(nudgeId) === checked)
+        return false;
+    const next = checked
+        ? [...current, nudgeId]
+        : current.filter(id => id !== nudgeId);
+    if (next.length === 0)
+        element.clearField('qualityChecklist');
+    else
+        element.qualityChecklist = next;
+    return true;
+}

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

@@ -0,0 +1,15 @@
+import { type ToolbarContext } from '../../affine-shared/services/index.js';
+export declare const readingToolbarConfig: {
+    readonly actions: [{
+        readonly id: "y1.element-reading";
+        readonly when: (ctx: ToolbarContext) => boolean;
+        readonly generate: (ctx: ToolbarContext) => {
+            label: string;
+            icon: import("lit-html").TemplateResult<1>;
+            showLabel: true;
+            tooltip: string;
+            run: (runCtx: ToolbarContext) => void;
+        };
+    }];
+};
+export declare const readingToolbarExtension: import("../../store/index.js").ExtensionType;

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

@@ -0,0 +1,158 @@
+import { ToolbarModuleExtension, translateKey, } from '../../affine-shared/services/index.js';
+import { BlockFlavourIdentifier, getRegisteredCommands, runCommand, } from '../../std/index.js';
+import { GfxGroupLikeElementModel, GfxPrimitiveElementModel, } from '../../std/gfx/index.js';
+import { html } from 'lit';
+import { ReadingManager, readingProfileFor } from './reading.js';
+/**
+ * **The click** — the entry on a selected component's contextual toolbar that
+ * asks the tool what it reads (MF3).
+ *
+ * The PO's arbitration of 01/08/2026 made the trigger a gesture: the reversed
+ * reading never runs by itself, never rides on validation, and never writes.
+ * This entry is that gesture, and it is deliberately as thin as
+ * `tags-toolbar.ts`'s — it resolves WHICH element the reading is about and
+ * invokes `element.read` through the registry. Everything else lives behind the
+ * command and the manager, so the palette and the agent get the same behaviour
+ * with no second implementation.
+ *
+ * ## Which element gets the entry
+ *
+ * The one that CARRIES a readable role — resolved through the group when a
+ * single click selected the composite, exactly as the qualification dropdown
+ * does. A Wardley component is a circle and a free text grouped together, and
+ * making the user enter the group to find the reading would bury it. Two
+ * readable members means the group is not one artefact, and a proposal about
+ * "one of these two" is not a proposal.
+ *
+ * ## Where it is registered
+ *
+ * `custom:affine:*` — the next free wildcard slot, one slot out from the
+ * `custom:affine:surface:*` the exception entry took (`validation-toolbar.ts`
+ * documents the collision rule: two modules on one key, and one of them is
+ * silently lost). Registered ONCE, by the surface itself rather than per
+ * framework: nothing in this file names a framework, and the entry is gated by
+ * whether a registered {@link ReadingProfile} can read the selection — which
+ * only a framework's FLAG-GATED view extension provides. Flag off, no profile,
+ * no entry, and every element still loads and paints (ADR 0009).
+ *
+ * The wildcard is merged into the toolbar of every block, canvas or not; on
+ * anything that is not a canvas selection `getSurfaceModels()` is empty and the
+ * module stands down before doing any work.
+ *
+ * Not read-only gated: reading a board one cannot edit is exactly as legitimate
+ * as reading one you can. What disappears in a read-only document is the
+ * panel's CONFIRMATIONS.
+ */
+const READ_LABEL_KEY = 'com.labre.reading.toolbar.label';
+const READ_LABEL_FALLBACK = 'Read this component';
+/**
+ * An eye: what the tool SEES of this element.
+ *
+ * Words were the right call for this entry and still are — it renders as
+ * "Read this component" whenever the row has the width for it. The icon is
+ * what the row falls back to when it does not: the toolbar drops the label and
+ * keeps it as the tooltip rather than pushing the whole entry into the "⋮"
+ * (PO arbitration of 02/08/2026, point 2). An entry with no icon has no such
+ * fallback, which is the only reason this glyph exists.
+ *
+ * Drawn inline like its neighbours: this package does not depend on
+ * `@blocksuite/icons` and one glyph is not worth a new dependency.
+ */
+const ReadIcon = 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="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6-10-6-10-6z" />
+  <circle cx="12" cy="12" r="3" />
+</svg>`;
+/** The command this module drives. Spelled once. */
+const ELEMENT_READ_ID = 'element.read';
+/** The single selected element a reading could be about, resolved through groups. */
+function readTarget(ctx) {
+    const manager = ctx.std.getOptional(ReadingManager);
+    if (!manager || manager.profiles.length === 0)
+        return null;
+    const models = ctx.getSurfaceModels();
+    if (models.length !== 1)
+        return null;
+    const [model] = models;
+    if (!(model instanceof GfxPrimitiveElementModel))
+        return null;
+    const candidates = [];
+    if (readingProfileFor(model, manager.profiles))
+        candidates.push(model);
+    if (model instanceof GfxGroupLikeElementModel) {
+        for (const child of model.childElements) {
+            if (!(child instanceof GfxPrimitiveElementModel))
+                continue;
+            if (readingProfileFor(child, manager.profiles))
+                candidates.push(child);
+        }
+    }
+    return candidates.length === 1 ? candidates[0] : null;
+}
+/**
+ * Invoke `element.read` on the resolved target, through the registry rather
+ * than by importing the command: this package sits below
+ * `@labre/affine-block-root` in the dependency order, and going through
+ * `runCommand` is what keeps one gesture one path whatever the surface. A build
+ * with the command unregistered simply has no working entry — never a throw.
+ *
+ * `elementId` is passed EXPLICITLY rather than letting the command fall back to
+ * the live selection: the element being read is often a group member, not the
+ * group the user clicked.
+ */
+function openReading(ctx, target) {
+    const command = getRegisteredCommands(ctx.std).find(c => c.id === ELEMENT_READ_ID);
+    if (!command)
+        return;
+    runCommand(ctx.std, command, 
+    // The surface the gesture really came from, as `connector/src/toolbar/
+    // config.ts` reports its own inversion: a reading triggered from the
+    // element's toolbar must not be counted as a palette invocation.
+    { surface: 'contextual-toolbar', source: 'toolbar:general' }, { elementId: target.id });
+}
+export const readingToolbarConfig = {
+    actions: [
+        {
+            // After the qualification dropdown (`y.element-tags`) and before
+            // `z.validation`: what the tool READS of an element comes after what the
+            // element says it is, and before how hard it is checked.
+            id: 'y1.element-reading',
+            when: (ctx) => readTarget(ctx) !== null,
+            // `label` is static on a ToolbarAction, so the i18n seam needs the
+            // generator form: it is the only shape that receives the context, and
+            // `translateKey` needs `std` to reach the host's catalogue.
+            generate: (ctx) => {
+                const label = translateKey(ctx.std, READ_LABEL_KEY, READ_LABEL_FALLBACK);
+                return {
+                    label,
+                    // Words, not a glyph: "what does the tool make of this?" is not a
+                    // question anyone should have to guess from an icon. The icon is the
+                    // fallback the toolbar uses when the row runs out of width, never the
+                    // default — declaring both is what buys this entry a step of grace
+                    // before it would be pushed into the "⋮".
+                    icon: ReadIcon,
+                    showLabel: true,
+                    tooltip: label,
+                    run: (runCtx) => {
+                        const target = readTarget(runCtx);
+                        if (!target)
+                            return;
+                        openReading(runCtx, target);
+                    },
+                };
+            },
+        },
+    ],
+};
+export const readingToolbarExtension = ToolbarModuleExtension({
+    id: BlockFlavourIdentifier('custom:affine:*'),
+    config: readingToolbarConfig,
+});

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

@@ -0,0 +1,145 @@
+import { nothing, type TemplateResult } from 'lit';
+import { EditorAnchoredPanel } from './editor-anchored-panel.js';
+export declare const READING_PROPOSAL_WIDGET = "affine-reading-proposal-widget";
+/**
+ * How the panel names each side of a parent-child relation, keyed under
+ * `com.labre.reading.relations.`. Chrome, and only chrome.
+ *
+ * Exported because it is DATA: the translation-key manifest walks it rather
+ * than restating the two wordings, which a source scan could not check — the
+ * key is built as a template literal and the fallback reaches `translateKey`
+ * through a local helper.
+ */
+export declare const RELATION_SIDE_FALLBACK: {
+    readonly consumers: "Consumers (above)";
+    readonly suppliers: "Suppliers (below)";
+};
+/**
+ * **The proposal panel** — what the tool reads of one component, offered for
+ * confirmation (MF3).
+ *
+ * It opens on a click and on nothing else: `ReadingManager.open$` is written by
+ * the `element.read` command, which the element's own toolbar and the palette
+ * invoke. Rendering it costs the document nothing — every line is a function of
+ * the board, recomputed at render time, and there is no code path from a render
+ * to a write. The invariant has a test of its own: opening and closing this
+ * panel a hundred times leaves the document byte-identical.
+ *
+ * ## What a confirmation is
+ *
+ * The two writes a user can ask for are the two EXISTING promotion commands:
+ * `tag.set` for a nature and `pivot.bind` for the link to a record. The panel
+ * owns neither — it invokes them through the registry, exactly as
+ * `tags-toolbar.ts` does, so one gesture stays one telemetry event, one undo
+ * step and one read-only guard, wherever it was triggered from.
+ *
+ * A confirmation appears only where there is something to confirm: a value the
+ * RECORD carries and the element does not. The library never proposes a nature
+ * of its own — no derivation, no inference from the name, from the shape or
+ * from the position. An unqualified component with no record simply reads as
+ * unqualified, and the panel says so.
+ *
+ * ## Drift
+ *
+ * A bound element whose drawing has moved away from its record gets one extra
+ * line, informative and non-blocking, with the way to bring the record up to
+ * date: the existing materiality publisher, fire-and-forget, host-side. Nothing
+ * is refused, nothing is blocked and nothing is written to the DOCUMENT — the
+ * board is always right about itself.
+ *
+ * ## Where it sits
+ *
+ * **Anchored to the EDITOR, above the senior button bar and at its width** —
+ * the PO's recette of 02/08/2026 and its second pass, now the shared contract
+ * of ADR 0011. It shipped as a bubble floating beside the element and came back
+ * with two faults: it rendered BEHIND the contextual toolbar, and a paragraph
+ * of prose is not a thing to read out of the corner of a shape. The first pass
+ * made it a bottom-centre panel at a fixed 480px; the second replaced that
+ * arbitrary measure with the toolbar's own, so the two boxes share their left
+ * and right edges. All of that geometry — and the layer above every toolbar
+ * that goes with it — lives in {@link EditorAnchoredPanel}; what is left here
+ * is the reading itself.
+ *
+ * The mechanics that are easy to get wrong are the base class's too: a
+ * zero-sized host so the canvas stays clickable, the pointer pair swallowed on
+ * the panel itself, Escape listened for on the EDITOR HOST rather than on
+ * `document`, and click-away that observes without swallowing.
+ */
+export declare class ReadingProposalWidget extends EditorAnchoredPanel {
+    static styles: import("lit").CSSResult[];
+    /** Bumped to force a re-render; the reading itself is never stored. */
+    private accessor _revision;
+    private _elementSubscription;
+    private get _manager();
+    protected get panelOpen(): boolean;
+    protected closePanel(): void;
+    private _wire;
+    connectedCallback(): void;
+    firstUpdated(): void;
+    /** The label a nature value id reads as, or the raw id when no def explains it. */
+    private _natureLabel;
+    private _field;
+    private _renderNodeType;
+    /**
+     * The nature the element CARRIES — and, when the record carries a different
+     * one, the record's, offered for confirmation. Never a derived one, and never
+     * a word the framework does not describe.
+     *
+     * `record.nature` has already been resolved against the tag def
+     * (`resolveRecordNature`), so what this button writes is always a value id the
+     * vocabulary knows. What could NOT be resolved is named in a sentence with no
+     * button beside it: the honest thing to say about `"Activity"` when the def
+     * describes `wardley:nature/activity` is that the record says something this
+     * framework does not recognise — not to offer a click that would put the
+     * host's word into the document.
+     */
+    private _renderNature;
+    private _renderRelations;
+    /**
+     * **Value flow** — the same typed edges as the relations above, said the way
+     * a value chain is read: from the bottom up.
+     *
+     * One sentence per typed edge, and no section at all when the element has
+     * none: an empty "Value flow" heading states nothing a user wants, and the
+     * relations field already says in its own words that no link touches this
+     * component.
+     *
+     * The sentence is assembled from two halves rather than interpolated, because
+     * `translateKey` returns a plain string and a host catalogue that returned
+     * markup would then be injected into the panel. The fallback reads
+     * "Value flows up from X to Y"; a host that translates
+     * `com.labre.reading.value-flow` gets the same two slots in its own order via
+     * the `.to` suffix key.
+     */
+    private _renderValueFlow;
+    private _renderPhase;
+    private _renderNaming;
+    /**
+     * The link to a pivot record, and the only place this panel can create one.
+     *
+     * The action exists only when the host registered a picker: the library
+     * cannot choose a document, so with no picker there is nothing to offer and
+     * the affordance is HIDDEN rather than disabled — the `QuickSearchProvider`
+     * precedent, and the same rule `queryPivotProperties` follows.
+     */
+    private _renderRecord;
+    /** The drift line: informative, never blocking, with one way to settle it. */
+    private _renderDrift;
+    /** Invoke a registered command; a build without it simply has no action. */
+    private _run;
+    private readonly _confirmNature;
+    private readonly _linkRecord;
+    /**
+     * Announce the occurrence's current materialities to the host — the existing
+     * fire-and-forget publisher, and no new channel.
+     *
+     * What crosses is what the seam carries: the occurrence's role and its
+     * type-3 tags (`OccurrenceMaterialityPatch`). A PHASE is a reading of the
+     * board, and the seam has no field for it: the drift line reports it so the
+     * user can settle it on whichever side is wrong, and the library does not
+     * invent a transport for a fact the host never agreed to receive.
+     */
+    private readonly _updateRecord;
+    render(): TemplateResult | typeof nothing;
+}
+export declare const readingProposalWidget: import("../../store/index.js").ExtensionType;