@formicoidea/labre-core 0.30.1 → 0.32.0

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

@@ -0,0 +1,494 @@
+import { type TagDef } from '../../affine-shared/services/index.js';
+import { LifeCycleWatcher, type BlockStdScope, type FrameworkId } from '../../std/index.js';
+import type { RoleDefs, RoleId } from '../../std/gfx/index.js';
+import { GfxPrimitiveElementModel } from '../../std/gfx/index.js';
+import type { ExtensionType } from '../../store/index.js';
+import { type FrameworkBackgroundDef } from '../framework-background/def.js';
+/**
+ * **The reversed reading** (MF3): what the tool can say about a component the
+ * user has drawn, as a PROPOSAL — never as a write.
+ *
+ * The five readings are all functions of data that is already in the document
+ * and already declared by a framework: the `role` vocabulary (PF1), the level-3
+ * tags (ADR 0007), the typed edges (ADR 0010), and the framework background's
+ * own zones and bands (PF5.15/16). Nothing here derives a value the user did not
+ * state — the whole point of the PO's arbitration of 01/08/2026 is that a
+ * reading is an OFFER:
+ *
+ * > the reversed reading is triggered on a click (never by automatic
+ * > validation) and writes nothing without confirmation.
+ *
+ * So this module is pure on the way in ({@link readElement} takes elements and a
+ * declaration, and returns a value object) and empty-handed on the way out: the
+ * only writes in the whole feature are the two EXISTING commands a user may
+ * choose to invoke from the panel — `tag.set` and `pivot.bind`.
+ *
+ * ## What is generic and what is declared
+ *
+ * Nothing in this file names Wardley, a nature, a phase or a dependency. A
+ * framework declares a {@link ReadingProfile} — the same shape of contract as a
+ * `ValidationRule`: data, comparable, reviewable, registered from the
+ * FLAG-GATED view extension, because reading a map is tooling and a board whose
+ * framework is switched off must simply stop being read (ADR 0009).
+ */
+/**
+ * How a name is expected to read, for ONE value of the nature tag.
+ *
+ * A convention is a MOTIF, not a grammar: one case-insensitive regular
+ * expression the name is expected to match, plus the sentence that says why.
+ * Deliberately small — the library has no business shipping a linguist, and a
+ * naming rule that a user cannot predict is worse than none.
+ *
+ * It is never blocking and never a violation: a reading says "this name does
+ * not read like an activity", offers the wording, and stops there.
+ */
+export interface ReadingNamingConvention {
+    /** The nature value id this convention describes, e.g. `wardley:nature/data`. */
+    valueId: string;
+    /**
+     * `RegExp` SOURCE (not a literal), compiled with `i`, `u` and `s` and matched
+     * against the element's name. A source string rather than a `RegExp` object so
+     * a profile stays plain, serialisable data like every other declaration in
+     * this repo.
+     *
+     * `s` (dotAll) is on because a canvas label is free text and wraps: without
+     * it, `.` stops at the newline and an anchored pattern fails on every
+     * two-line name whatever it says. A pattern that wants line semantics writes
+     * them itself.
+     */
+    pattern: string;
+    /**
+     * The LANGUAGE this motif is a motif of, as a BCP-47 primary subtag
+     * (`'en'`). A convention that declares one is applied only when the host says
+     * it is serving that language ({@link hostLanguage}); it is **silent**
+     * otherwise — including when the host says nothing at all.
+     *
+     * This is the field that stops an English gerund from judging a board named
+     * in French. "Facturation" on an activity is neither followed nor broken, it
+     * is out of scope, and a suggestion out of scope is worse than no suggestion:
+     * it is wrong in both directions at once (a French activity gets told to use
+     * a verb, a French datum called "Planning" gets told it reads as an action).
+     *
+     * Omitted, the convention is language-agnostic and always applies — for a
+     * motif that genuinely is (a prefix, a code, a forbidden character). A
+     * framework extends its coverage by shipping one more convention per language
+     * for the same `valueId`; the first one in scope wins.
+     */
+    lang?: string;
+    /** i18n key of the suggestion shown when the name does not match. */
+    hintKey: string;
+    /** English default, for a host that ships no catalogue. */
+    hintFallback: string;
+}
+/**
+ * One framework's reading contract. Every section is optional: a framework that
+ * declares only `appliesTo` gets the node-type line and nothing else, which is
+ * exactly what a framework with no tags, no typed edges and no background
+ * should get.
+ */
+export interface ReadingProfile {
+    /** Stable id; one profile per framework today. */
+    id: string;
+    framework: FrameworkId;
+    /** The framework's role vocabulary — hierarchy is resolved against it. */
+    roles: RoleDefs;
+    /**
+     * The subject role. An element carrying it, or a specialisation of it, can be
+     * read; anything else has no reading and the panel does not stand up.
+     */
+    appliesTo: RoleId;
+    /**
+     * The role of the element that NAMES the subject, when the name is a separate
+     * element grouped with it — which is what a Wardley component is (a circle
+     * and a free text). Absent, only the subject's own text is read.
+     */
+    labelRole?: RoleId;
+    /** The type-3 tag carrying the subject's nature, and its naming conventions. */
+    nature?: {
+        tagId: string;
+        conventions: readonly ReadingNamingConvention[];
+    };
+    /** The typed edge whose two ends the relation reading walks. */
+    relation?: {
+        edgeRole: RoleId;
+    };
+    /** The frame the phase is read from. */
+    frame?: {
+        backgroundRole: RoleId;
+        /** The declaration itself, carried as data exactly like `roles` is. */
+        background: FrameworkBackgroundDef;
+        /** Which plot axis the zones are laid along. */
+        axis: 'x' | 'y';
+    };
+    /**
+     * Which properties of the PIVOT RECORD the reading may compare itself
+     * against — the host's own keys, because the library does not name a
+     * property of somebody else's document.
+     *
+     * Absent, or absent from the host's `hoverFields`, means no comparison is
+     * possible: the panel shows the local reading and the drift trigger stays
+     * silent. Silence, never a guess.
+     */
+    recordKeys?: {
+        nature?: string;
+        phase?: string;
+    };
+}
+/** Where the other end of a typed edge sits, relative to the subject. */
+export type ReadingRelationSide = 'consumer' | 'supplier';
+/** One typed edge touching the subject, read with the ADR 0010 convention. */
+export interface ReadingRelation {
+    /** The edge element. */
+    edgeId: string;
+    /** 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 OTHER element is to the subject. ADR 0010 § 2 tier 2: on a
+     * `wardley:dependency`, `source` is the consumer and `target` is what it
+     * needs. So an edge leaving the subject names a SUPPLIER, and an edge
+     * arriving at it names a CONSUMER.
+     */
+    side: ReadingRelationSide;
+    /**
+     * The declaration and the drawing disagree.
+     *
+     * A consumer is drawn ABOVE what it needs — the visibility axis IS the
+     * statement of dependency order (ADR 0010 § 5). When the persisted direction
+     * says one thing and the two positions say the other, the reading says so
+     * rather than picking a winner: that is W4 seen from the record's side, and
+     * the user is the one who decides which of the two was the mistake.
+     */
+    contradictsGeometry: boolean;
+}
+/** Where the subject sits along the frame's phase axis. */
+export interface ReadingPhase {
+    /** The declared zone id, e.g. `product`. */
+    zoneId: string;
+    labelKey?: string;
+    labelFallback?: string;
+    /**
+     * The subject sits in the band around a zone transition — Wardley's zone of
+     * punctuated equilibrium, declared by the background as
+     * `transitionBandWidth`.
+     */
+    inTransitionBand: boolean;
+    /** Which frontier, `custom-built|product`. Present only inside a band. */
+    bandId?: string;
+}
+/** Whether the subject's name reads the way its nature says it should. */
+export interface ReadingNaming {
+    name: string;
+    conforms: boolean;
+    hintKey: string;
+    hintFallback: string;
+}
+/** The subject's semantic identity: its role, and the roles it specialises. */
+export interface ReadingNodeType {
+    roleId: RoleId;
+    labelKey?: string;
+    /** The `parent` chain, nearest first. Empty for a root role. */
+    specialises: RoleId[];
+}
+/**
+ * One element, as the tool reads it. A value object: no element references, no
+ * signals, nothing to dispose — and nothing that has been written anywhere.
+ */
+export interface ElementReading {
+    elementId: string;
+    /**
+     * What the subject is CALLED — its own text, or the text of the sibling
+     * carrying the label role. `''` when nothing on the board names it.
+     *
+     * The panel must never print an id at a human, and the value-flow sentences
+     * need both ends by name, so the subject's own name belongs in the reading
+     * rather than being re-derived by every renderer.
+     */
+    name: string;
+    nodeType: ReadingNodeType;
+    /**
+     * The type-3 values the element CARRIES. `undefined` when it carries none —
+     * and that is the whole of the reading: no nature is derived from the shape,
+     * from the name or from the position. An empty proposal is the honest one.
+     */
+    nature: {
+        tagId: string;
+        valueIds: string[];
+    } | undefined;
+    relations: readonly ReadingRelation[];
+    /** `undefined` off any frame: a component on a blank canvas has no phase. */
+    phase: ReadingPhase | undefined;
+    /** `undefined` with no nature, no convention for it, or no name to judge. */
+    naming: ReadingNaming | undefined;
+}
+/** What the reading needs to know that is not in the document. */
+export interface ReadingOptions {
+    /**
+     * The language the host is serving, as a primary subtag — from
+     * {@link hostLanguage}. It gates the naming conventions that declare a
+     * `lang`, and nothing else: no reading of the document depends on it.
+     *
+     * A parameter rather than a lookup, so {@link readElement} stays pure and one
+     * caller (the manager) owns the single `std` read.
+     */
+    lang?: string;
+}
+/**
+ * Read one element. Pure: same elements, same profile, same options, same
+ * answer, and no write anywhere on any path through this function.
+ *
+ * `null` when the element does not carry the profile's subject role — the
+ * caller has nothing to show, which is what keeps the panel off every neutral
+ * rectangle on the board.
+ */
+export declare function readElement(element: GfxPrimitiveElementModel, elements: readonly GfxPrimitiveElementModel[], profile: ReadingProfile, options?: ReadingOptions): ElementReading | null;
+/**
+ * One sentence of value flow: who it comes FROM, who it goes TO.
+ *
+ * Names, never ids — the two ends are meant to be read out loud.
+ */
+export interface ReadingValueFlow {
+    /** The typed edge the flow was read from. */
+    edgeId: string;
+    /** The supplier end — what is depended ON, drawn lower on the map. */
+    from: string;
+    /** The consumer end — what depends on it, drawn higher on the map. */
+    to: string;
+}
+/**
+ * **The value flow** — the same typed edges as {@link ElementReading.relations},
+ * said the way a value chain is read: from the bottom up.
+ *
+ * A Wardley map is an anchor at the top and everything the anchor needs
+ * underneath it, so the VALUE travels the other way round from the dependency
+ * arrow: a supplier hands its value up to the consumer that needs it. ADR 0010
+ * § 2 fixes which end is which — on a `wardley:dependency` the `source` is the
+ * consumer and the `target` is the supplier — so the flow is entirely a
+ * restatement of what {@link readRelations} already resolved:
+ *
+ * - the other end is a SUPPLIER (an edge leaving the subject) → value comes up
+ *   from it to the subject;
+ * - the other end is a CONSUMER (an edge arriving at the subject) → value goes
+ *   up from the subject to it.
+ *
+ * Derived, not stored: no second traversal of the board, no second convention
+ * to keep in step with ADR 0010, and an element with no typed edge yields an
+ * empty list — which the panel renders as no section at all.
+ */
+export declare function readValueFlows(reading: ElementReading): ReadingValueFlow[];
+/** The profile governing an element, or `null` — the first match wins. */
+export declare function readingProfileFor(element: GfxPrimitiveElementModel, profiles: readonly ReadingProfile[]): ReadingProfile | null;
+/**
+ * What the LINKED RECORD says about the two fields a reading can compare
+ * itself against. Bounded by construction: the profile names at most two host
+ * property keys, and the provider is asked for nothing else.
+ */
+export interface RecordReading {
+    pivotDocId: string;
+    /**
+     * The record's nature, as VALUE IDS the framework's tag def describes —
+     * resolved here, at the moment of reading, never at the moment of writing.
+     * See {@link resolveRecordNature}.
+     */
+    nature?: string[];
+    /**
+     * What the record carries under the same property that no def describes.
+     * Shown to the user as a sentence, offered for confirmation never, and
+     * compared never.
+     */
+    unknownNature?: string[];
+    /** The record's phase, as the host spells it. */
+    phase?: string;
+}
+/**
+ * The record's nature, split into what the FRAMEWORK describes and what it does
+ * not.
+ *
+ * The whole point of the split, and it is the one thing this module must not get
+ * wrong: a pivot record is the host's document, and its "nature" property holds
+ * whatever words the host's own vocabulary uses — `"Activity"`, `"activité"`,
+ * an internal code. A value id, on the element, is a namespaced id a tag def
+ * describes (`wardley:nature/activity`). They are not the same alphabet.
+ *
+ * `tag.set` deliberately does not police its values (a document must load
+ * whatever it carries), so the guard has to stand at the point of PROPOSAL: an
+ * unresolvable word is never offered for confirmation and never compared,
+ * because both outcomes corrupt something — writing it puts a value no def
+ * describes into the document (the naming line vanishes, the qualification
+ * dropdown shows a raw id, rules stop matching), and comparing it reports a
+ * permanent, false disagreement on an element that is correctly qualified.
+ */
+export interface ResolvedRecordNature {
+    /** Value ids a def describes. The only ones ever proposed or compared. */
+    resolved: string[];
+    /** Words no def describes. Reported to the user, written nowhere. */
+    unknown: string[];
+}
+/**
+ * Resolve the record's words against the tag def's own values.
+ *
+ * Three ways a word is accepted, in order: the value id itself, the id
+ * case-insensitively, then the value's LABEL case-insensitively — because a
+ * host storing the words a human picked from a multi-select is the ordinary
+ * case, not the exotic one. Anything else is `unknown`: this is a resolver, not
+ * a guesser, and there is no fuzzy match anywhere in it.
+ *
+ * Two deliberate edge cases:
+ *
+ * - **no def** (the framework's pack is not seeded in this deployment) — every
+ *   word is unknown. We cannot know the vocabulary, so proposing to write one of
+ *   its words would be inventing it;
+ * - **`values: 'open'`** — the def says any string is a value of this tag, so
+ *   everything resolves. That is the def's own claim, not ours.
+ */
+export declare function resolveRecordNature(def: TagDef | undefined, values: readonly string[]): ResolvedRecordNature;
+/** One field on which the drawing and the record disagree. */
+export interface ReadingDriftField {
+    field: 'nature' | 'phase';
+    /** What the board says. */
+    read: string;
+    /** What the record says. */
+    record: string;
+}
+/** A bound element whose drawing has moved away from its confirmed record. */
+export interface ReadingDrift {
+    elementId: string;
+    pivotDocId: string;
+    fields: readonly ReadingDriftField[];
+}
+/**
+ * The record's side of the comparison, read through the guarded seam.
+ *
+ * `undefined` on every degraded path — no binding, no provider, no configured
+ * fields, a dangling record, a still-loading one — and the caller shows the
+ * local reading alone. That is the `queryPivotProperties` contract: "this
+ * editor has no host data layer" is not an error to put in front of a user.
+ */
+export declare function readRecord(std: BlockStdScope, element: GfxPrimitiveElementModel, profile: ReadingProfile): RecordReading | undefined;
+/**
+ * Where the drawing and the record disagree.
+ *
+ * A field the record does not carry is never a disagreement: the record simply
+ * has not been filled in, and calling that "drift" would turn an empty property
+ * into a permanent complaint. A field the BOARD cannot read is not one either —
+ * a component dragged off the map has no phase to be in conflict with.
+ *
+ * Neither is a word the framework does not describe ({@link RecordReading.unknownNature}):
+ * comparing `wardley:nature/activity` against the host's `"Activity"` would
+ * report a permanent, false disagreement on an element that is correctly
+ * qualified — and would offer the user two ways out, both of which corrupt one
+ * side. `readRecord` has already resolved what CAN be compared; what could not
+ * is not a difference of opinion, it is a difference of alphabet.
+ *
+ * The phase comparison accepts either the zone id or the zone's own wording,
+ * because a host is free to store "Product" where the declaration says
+ * `product`, and neither spelling is more correct than the other.
+ */
+export declare function compareReading(reading: ElementReading, record: RecordReading): ReadingDriftField[];
+/** A framework registers its reading profile here; nothing else registers one. */
+export declare const ReadingProfileIdentifier: import("../../global/di/types.js").ServiceIdentifier<ReadingProfile> & (<U extends ReadingProfile = ReadingProfile>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Register a framework's reading profile. Call it from the FLAG-GATED view
+ * extension, beside the rules and the profiles: reading a map is tooling, and a
+ * board whose framework is switched off keeps every one of its elements and
+ * simply stops being read (ADR 0009).
+ *
+ * ```ts
+ * context.register(ReadingProfileExtension(WARDLEY_READING));
+ * ```
+ */
+export declare function ReadingProfileExtension(profile: ReadingProfile): ExtensionType;
+/**
+ * How the host picks a pivot record, for the ONE affordance that needs one: the
+ * panel's "link to a record" action.
+ *
+ * The library cannot choose a document — it does not know what a pivot record
+ * is (ADR 0005 § 3), which is why `pivot.bind` takes the id as a parameter. A
+ * host that runs a picker registers it here and the action appears; a host that
+ * does not gets no action at all, rather than a button that opens nothing.
+ * Same rule as `PivotPropertiesProvider`: **no noop default is registered**,
+ * because absence is a meaningful state and the degraded path has to stay
+ * honest.
+ *
+ * It lives beside the reading rather than in `affine-shared/services` because
+ * it exists for exactly one affordance in exactly one panel. The day a second
+ * consumer wants it, it moves next to the rest of the pivot seam.
+ */
+export interface PivotRecordPicker {
+    /**
+     * Resolve to a record id, or to `null` when the user cancels. MUST NOT
+     * throw; a rejection is swallowed by the caller and treated as a cancel.
+     */
+    pick(std: BlockStdScope, elementId: string): Promise<string | null>;
+}
+export declare const PivotRecordPickerProvider: import("../../global/di/types.js").ServiceIdentifier<PivotRecordPicker> & (<U extends PivotRecordPicker = PivotRecordPicker>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+export declare function PivotRecordPickerExtension(picker: PivotRecordPicker): ExtensionType;
+/**
+ * Debounce of the drift trigger, in ms.
+ *
+ * Comfortably above a frame: the trigger is the one part of this feature that
+ * runs without being asked, so it stays off the critical path by construction —
+ * a drag of a bound component emits dozens of updates and must cost one check,
+ * after the hand has stopped. Longer than the validation engine's 120 ms
+ * because nothing here is a verdict: a record that is out of date can wait a
+ * fifth of a second longer than a rule can.
+ */
+export declare const READING_DRIFT_DELAY_MS = 200;
+/**
+ * Owns the OPEN panel and the drift signal. It owns no reading: a reading is
+ * recomputed on demand from the document, so it can never be stale and can
+ * never be a second source of truth.
+ *
+ * Inert until a framework registers a {@link ReadingProfile} — a board with no
+ * framework enabled pays one empty-map check at mount and subscribes to
+ * nothing.
+ */
+export declare class ReadingManager extends LifeCycleWatcher {
+    static readonly key = "reading-manager";
+    /**
+     * The element whose proposal is open, or `null`. Session state, set by the
+     * `element.read` command and by nothing else: the panel NEVER opens itself,
+     * which is the whole of the PO's arbitration.
+     */
+    readonly open$: import("@preact/signals-core").Signal<string | null>;
+    /**
+     * The last drift observed, or `null`. Informative and non-blocking: nothing
+     * anywhere refuses a gesture because of it.
+     */
+    readonly drift$: import("@preact/signals-core").Signal<ReadingDrift | null>;
+    private _profiles;
+    private _subscriptions;
+    private _disposeSurfaceEffect;
+    private _pending;
+    private readonly _dirty;
+    /** Registered profiles, resolved once. Empty when every flag is off. */
+    get profiles(): readonly ReadingProfile[];
+    mounted(): void;
+    unmounted(): void;
+    /** Open the proposal for one element. Reads nothing yet, writes nothing ever. */
+    open(elementId: string): void;
+    close(): void;
+    /** The current surface, or `null` before one arrives. */
+    private get _surface();
+    /**
+     * The reading of one element, recomputed from the document every time it is
+     * asked for. Cheap enough to be called from a render: one pass over the
+     * surface for the relations, one containment test per frame.
+     */
+    reading(elementId: string): ElementReading | null;
+    /** The profile governing an element, for the panel's confirmation actions. */
+    profileOf(elementId: string): ReadingProfile | null;
+    private _unsubscribe;
+    private _resubscribe;
+    /**
+     * Never in the same tick, and never in the same frame.
+     *
+     * The whole trigger is one timer: a drag emits an update per pointer move,
+     * and each one pushes the single pending check further away, so the work
+     * happens once, after the hand has stopped, and the 16 ms budget of the drag
+     * itself is untouched by construction rather than by measurement.
+     */
+    private _schedule;
+    private _check;
+}