@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/_pkgs/std/gfx/model/surface/element-model.d.ts

@@ -11,6 +11,122 @@ export type BaseElementProps = {
     index: string;
     seed: number;
     lockedBySelf?: boolean;
+    /** See {@link GfxPrimitiveElementModel.pivotDocId}. */
+    pivotDocId?: string;
+    /** See {@link GfxPrimitiveElementModel.role}. */
+    role?: string;
+    /** See {@link GfxPrimitiveElementModel.tags}. */
+    tags?: Y.Map<string[]>;
+};
+/**
+ * One arbitration: "this element is excused from that rule".
+ *
+ * Document DATA, not session state — it records a decision the user made, so it
+ * outlives the tab, the framework flag and the client version that wrote it.
+ * Deliberately flat and rule-agnostic: the model stores it, the validation
+ * engine interprets it, and neither has to know what the other is up to.
+ */
+export type ValidationException = {
+    /** The rule being excused, e.g. `wardley.change-arrow-against-evolution`. */
+    ruleId: string;
+    /** Who granted it, when the host knows. Absent rather than empty. */
+    author?: string;
+    /** Epoch ms, taken at the moment of the gesture. */
+    at: number;
+};
+/**
+ * A SCOPE: which part of the source document a carried fragment came off.
+ *
+ * One Labre element routinely stands for several source elements — a BPMN pool
+ * is a `participant` AND its `process`, plus a `laneSet`, every `lane`, the
+ * `BPMNShape` that draws it, and (for the first pool of a document) the
+ * `collaboration` and `definitions` themselves. Everything they carry lands in
+ * ONE payload, so an unscoped `Record<name, value>` has two defects, and the
+ * first one destroys data: two lanes carrying the same foreign attribute
+ * overwrite each other silently, and nothing records which element an attribute
+ * belonged to, so no exporter can ever put it back where it came from.
+ *
+ * A scope is therefore either of exactly two things, and they cannot collide:
+ *
+ * - **the source element's id, verbatim** — the normal case, and the one that
+ *   lets an exporter put a fragment back on the element that had it;
+ * - **an `@`-prefixed ROLE key** for a source element with no id of its own, or
+ *   one whose identity is its relation to this element rather than a name:
+ *   `@self` (the element this payload is on), `@shape` (the diagram element
+ *   that draws it), and whatever else the format needs. **`@` is not an XML
+ *   NameStartChar**, so a role key can never be mistaken for an id, whatever a
+ *   file calls its elements.
+ *
+ * The role vocabulary past `@self` and `@shape` belongs to each format's
+ * importer, which is the only thing that knows what parts a document has;
+ * `.bpmn`'s is documented in `gfx/bpmn/src/import.ts`. The base model stores
+ * strings and never learns what any of them mean.
+ */
+export type InterchangeScope = string;
+/**
+ * Verbatim foreign matter one interchange import kept on one element, for one
+ * format (ADR 0012 § D2).
+ *
+ * Document DATA in the same sense {@link ValidationException} is: it records
+ * what a file actually said, so it outlives the tab, the framework flag and the
+ * client version that imported it. Deliberately format-agnostic — the base
+ * model stores fragments and attributes, and never learns what they mean.
+ *
+ * Every member is optional and absent rather than empty: an importer writes the
+ * ones it has, and a reader that finds none of them has an element that met an
+ * import and carried nothing.
+ *
+ * The three carrying members are keyed by {@link InterchangeScope}, so that
+ * what came off two different source elements stays apart. That shape is what
+ * makes the payload sufficient for re-emission, and it is the one thing here
+ * that could not be changed later: this value is persisted, so a document
+ * written under a shape that loses data cannot be repaired without the original
+ * file. One `Y.Map` entry all the same — the whole record is written once, as a
+ * blob, and never mutated.
+ */
+export type ForeignInterchange = {
+    /**
+     * The element's id in the SOURCE file, verbatim. The surface element keeps
+     * its own nanoid — surface identity is Labre's and never the file's — and an
+     * export prefers this id back when it is still usable, which is what makes
+     * the id map a fixed point after one cycle (ADR 0012 § D3).
+     */
+    id?: string;
+    /**
+     * The source element's name, when the element itself was CARRIED rather than
+     * mapped, e.g. `bpmn:boundaryEvent`.
+     */
+    element?: string;
+    /**
+     * Attributes the importer does not model — foreign-namespaced and standard
+     * alike — by {@link InterchangeScope}, then by attribute name.
+     *
+     * `{ 'Lane_1': { 'camunda:owner': 'alice' }, 'Lane_2': { 'camunda:owner':
+     * 'bob' } }`: two lanes of one pool, two owners, and both still here.
+     */
+    attrs?: Record<InterchangeScope, Record<string, string>>;
+    /**
+     * Child fragments, serialized — extension subtrees, unmodelled children, and
+     * whole carried elements — by the {@link InterchangeScope} of the element
+     * they were children OF. The scope is where an exporter has to put them back.
+     */
+    children?: Record<InterchangeScope, string[]>;
+    /**
+     * Diagram-interchange fragments, by the {@link InterchangeScope} of what they
+     * draw: `@shape` for the parts of this element's own diagram element that the
+     * importer did not model, a source id for the diagram of something carried.
+     */
+    di?: Record<InterchangeScope, string[]>;
+    /**
+     * Fragments kept but deliberately NOT re-emitted, each with the reason
+     * (ADR 0012 § D5). Preserved so a reader can see what was dropped and why;
+     * never a place the exporter reads for output — which is why this one is a
+     * flat list and needs no scope: nothing has to know where to put it back.
+     */
+    quarantined?: {
+        fragment: string;
+        reason: string;
+    }[];
 };
 export type SerializedElement = Record<string, unknown> & {
     type: string;
@@ -90,6 +206,43 @@ export declare abstract class GfxPrimitiveElementModel<Props extends BaseElement
     serialize(): SerializedElement;
     stash(prop: keyof Props | string): void;
     unlock(): void;
+    /**
+     * Remove an OPTIONAL `@field()` from the document entirely.
+     *
+     * The missing half of `@field()`. Its setter is unconditional — assigning
+     * `undefined` still calls `yMap.set(prop, undefined)` — so "clearing" an
+     * optional field through the accessor leaves the KEY behind. The getter reads
+     * `undefined` and nothing misbehaves, but the element is no longer
+     * byte-identical to one that never had the field: the phantom key syncs to
+     * every peer and ships in every snapshot. `init` is already careful to write
+     * nothing for an `undefined` default; this is how a field gets back to that
+     * state once it has been set.
+     *
+     * Emits a `delete` action rather than an `update`, so a consumer filtering on
+     * `props` will see an EMPTY payload and must inspect `oldValues` — the same
+     * shape an undo of the original write produces.
+     *
+     * ## What it refuses, and why that is load-bearing
+     *
+     * This is a direct write path into the element's Y.Map, on the class that
+     * carries the document format, exported by `@labre/std` and therefore
+     * callable by a host. `_assignElementProp` learned the same lesson in the
+     * unknown-props change (see `docs/spikes/us-1-8-unknown-props-preservation.md`,
+     * whose deny-list is explicitly security rather than hygiene); an unguarded
+     * delete re-opens the door from the other side. So:
+     *
+     * - a key the element class does not DECLARE as a `@field()` is refused. It
+     *   is either an unknown key preserved verbatim for a newer client — deleting
+     *   it is exactly the data loss that change exists to prevent — or not
+     *   document data at all;
+     * - a STRUCTURAL field is refused even though it is declared
+     *   ({@link UNCLEARABLE_ELEMENT_FIELDS}).
+     *
+     * Refusal is a no-op plus a `console.warn`, the same way an unencodable value
+     * is dropped rather than thrown: a misuse must not take the board down, and
+     * must not silently corrupt it either.
+     */
+    clearField(prop: string): void;
     accessor display: boolean;
     /**
      * In some cases, you need to draw something related to the element, but it does not belong to the element itself.
@@ -107,6 +260,257 @@ export declare abstract class GfxPrimitiveElementModel<Props extends BaseElement
      */
     accessor externalLink: string | undefined;
     accessor linkedDocId: string | undefined;
+    /**
+     * Identity binding to a host-owned **pivot record**: this element is an
+     * *occurrence* of the document `pivotDocId`. Many elements, across many
+     * boards, may carry the same `pivotDocId` — that is the point. A Wardley
+     * `component` drawn on three maps is the same component (MF1, ADR 0005).
+     *
+     * Opaque to the library: the framework never dereferences it, never fetches
+     * it, never renders it. Reading it is the host's job, through
+     * `PivotPropertiesProvider` (`@labre/affine-shared/services`, ADR 0006).
+     * No renderer, no hit-test, no layout and no exporter may read it; it
+     * participates in no `@derive`, `@convert` or `@watch` chain, so it cannot
+     * move, resize or restyle anything.
+     *
+     * Orthogonal to {@link linkedDocId} / {@link externalLink}, which are a
+     * *hyperlink* (navigation), not an identity. They differ on every axis that
+     * matters — cardinality (a hyperlink is one target per element and is
+     * exclusive with `externalLink`; a binding is many-elements-to-one-record),
+     * lifecycle (a hyperlink is picked from a search modal, a binding is created
+     * by promotion) and consumers (an arrow that navigates vs. a hover card and
+     * a rules engine). An element may legitimately carry both, and code reading
+     * one as a stand-in for the other is a bug.
+     *
+     * Declared on the BASE class for the same reason as {@link role}: an element
+     * re-created from props (paste, duplicate, alt-drag clone, template
+     * insertion) only reaches the Y.Map through keys that have a declared
+     * accessor, so a binding declared per subclass would be silently dropped on
+     * copy — and the loss would be invisible until the next reload.
+     *
+     * `undefined` = unbound, and no key is written for it, so an element that
+     * never binds stays byte-identical to one created before the field existed:
+     * optional field, no schema version bump, no migration. Clearing it goes
+     * through {@link clearField}, which removes the key rather than leaving a
+     * tombstone.
+     *
+     * A binding to a record that does not (yet) exist — or was deleted, or is
+     * invisible to this user — is a legal, persisted state: the library never
+     * validates it and never deletes host data. It resolves to `missing` at read
+     * time (ADR 0006).
+     */
+    accessor pivotDocId: string | undefined;
+    /**
+     * Semantic role of the element, `<framework>:<role>` (see `./role.ts`).
+     * `undefined` = neutral: generalist elements carry no role, and no key is
+     * written for them at creation.
+     *
+     * Declared on the BASE class on purpose, even though only framework modules
+     * set it: an element re-created from props (paste, duplicate, template
+     * insertion) only reaches the Y.Map through keys that have a declared
+     * accessor, so a role declared per subclass would be silently dropped on
+     * copy. Flat string on purpose — element serialization is one level deep.
+     */
+    accessor role: string | undefined;
+    /**
+     * Level 3 — **contextual qualification** (ADR 0007 § 4). Tag def id → the
+     * value ids selected for it, e.g. `{ 'wardley:nature': ['wardley:nature/data'] }`.
+     *
+     * Both halves of a key are namespaced by framework on purpose: two universes
+     * WILL collide on a word like `activity` — `edgy:activity` is already an EDGY
+     * base element while `activity` is one of Wardley's four natures — and
+     * namespacing is what makes that collision harmless rather than decorative.
+     *
+     * Absent and empty are equivalent (both mean "unqualified"), and the default
+     * is `undefined`, **never** `new Y.Map()`: `@field()`'s `init` writes nothing
+     * for an `undefined` default, so an element that is never qualified — every
+     * brush stroke, every connector — stays byte-identical to one created before
+     * the field existed. A non-`undefined` default on this base class would
+     * reinstate that cost on every element of every document. The qualification
+     * writer (`setElementTag`, `./tags.js`) creates the map on first use and
+     * removes the key again when the last tag goes.
+     *
+     * ## Why a NESTED `Y.Map` and not a plain object
+     *
+     * `@field()` writes straight into the element's `Y.Map` with no `native2Y` in
+     * the path, so a plain object here really would be ONE opaque value: two
+     * people qualifying the same element on two DIFFERENT tags would silently
+     * lose one of the two. A nested map merges per tag, which is what the shape
+     * has to do — there is no migration runner for surface elements, so it is
+     * chosen once. The `string[]` of a SINGLE tag stays last-write-wins, and that
+     * is correct: one tag's value set is one atomic choice.
+     *
+     * Exactly one level of Y-awareness, with plain arrays as values — shallower
+     * than `MindmapElementModel.children` (`Y.Map<NodeDetail>`), which already
+     * ships, and inside what `surface-transformer`'s `SURFACE_YMAP_UNIQ_IDENTIFIER`
+     * envelope round-trips generically.
+     *
+     * Declared on the BASE class for the same reason as {@link role} and
+     * {@link pivotDocId}: an element re-created from props (paste, duplicate,
+     * alt-drag clone, template insertion) only reaches the `Y.Map` through keys
+     * that have a declared accessor, and a qualification the user authored is
+     * exactly the kind of thing that must survive a copy. `SurfaceBlockModel`'s
+     * `_propsToY` rebuilds the map from the plain JSON `serialize()` produces, so
+     * a copy is a copy of the values and never a second reference to one map.
+     *
+     * Opaque to the framework: no renderer, no hit-test, no layout and no
+     * exporter reads it, and it participates in no `@derive` / `@convert` chain.
+     * Values whose def has vanished still load and are displayed as raw ids —
+     * defs are runtime configuration and are NEVER persisted.
+     */
+    accessor tags: Y.Map<string[]> | undefined;
+    /**
+     * Validation rules this element is excused from (PF8, "no rule is a wall").
+     *
+     * Declared on the BASE class for the same reason as {@link role}: an element
+     * re-created from props (paste, duplicate, template insertion) only reaches
+     * the Y.Map through keys that have a declared accessor, so an exception
+     * declared per subclass would be silently dropped on copy — and an arbitration
+     * the user made explicitly is exactly the kind of thing that must survive a
+     * copy.
+     *
+     * `undefined` = no exception, and no key is written for it, so an element that
+     * never got one stays byte-identical to one created before the field existed:
+     * optional field, no schema version bump, no migration.
+     *
+     * Flat JSON on purpose — element serialization is one level deep, and a value
+     * a Yjs update can encode is the contract enforced by `_assignElementProp`.
+     * The engine that reads it lives in `@labre/affine-block-surface`; the base
+     * model only carries the data, and knows nothing about rules.
+     */
+    accessor validationExceptions: ValidationException[] | undefined;
+    /**
+     * Id of the validation PROFILE this element's framework is checked against
+     * (PF9) — a set of enabled rules and their severities, declared as data by
+     * the framework.
+     *
+     * Carried by the framework's BACKGROUND element, i.e. the root instance, and
+     * not by the document: two maps on one canvas are two independent pieces of
+     * work, and a sketch has to be able to sit next to a deliverable without
+     * either of them dictating the other's requirements (PF9.1). The engine reads
+     * it off the background a finding was measured against, which it already
+     * names (`Violation.backgroundId`).
+     *
+     * Declared on the BASE class for the same reason as {@link role} and
+     * {@link validationExceptions}: an element re-created from props (paste,
+     * duplicate, template insertion) only reaches the Y.Map through keys that
+     * have a declared accessor, so a profile declared per subclass would be
+     * silently dropped on copy — and duplicating a strict map must give a strict
+     * map.
+     *
+     * `undefined` = "no explicit choice", which resolves to the framework's
+     * DEFAULT profile — the most permissive reasonable one, because the sketch
+     * wins. No key is written for it, so a document authored before this field
+     * existed stays byte-identical: optional field, no schema version bump, no
+     * migration. Choosing the default back again removes the key rather than
+     * writing it.
+     *
+     * Flat string on purpose — element serialization is one level deep. The
+     * engine that interprets it lives in `@labre/affine-block-surface`; the base
+     * model only carries the id, and knows nothing about profiles.
+     */
+    accessor validationProfile: string | undefined;
+    /**
+     * The map-quality NUDGES the user has ticked off on this instance (PF7.10) —
+     * ids of declarative reminders their framework ships, never rules the engine
+     * evaluates.
+     *
+     * A nudge is an expectation the tool cannot judge ("the map has a title that
+     * frames the study"): the content can exist without being good, so nothing
+     * here is ever computed. Ticking one is the same gesture as granting an
+     * exception — the user says "I have taken care of this" and the tool records
+     * it rather than pretending to check it.
+     *
+     * Carried by the framework's BACKGROUND element, i.e. the root instance, for
+     * the same reason {@link validationProfile} is: two maps on one canvas are two
+     * independent pieces of work, and a checklist ticked on one says nothing about
+     * the other.
+     *
+     * Declared on the BASE class for the same reason as {@link role} and
+     * {@link validationExceptions}: an element re-created from props (paste,
+     * duplicate, template insertion) only reaches the Y.Map through keys that have
+     * a declared accessor, so a checklist declared per subclass would be silently
+     * dropped on copy.
+     *
+     * `undefined` = nothing ticked, and no key is written for it, so a document
+     * authored before this field existed stays byte-identical: optional field, no
+     * schema version bump, no migration. Unticking the last one goes through
+     * {@link clearField}, which removes the key rather than leaving a tombstone.
+     *
+     * Flat JSON — an array of strings — on purpose: element serialization is one
+     * level deep, and a value a Yjs update can encode is the contract enforced by
+     * `_assignElementProp`. The library that interprets the ids lives in
+     * `@labre/affine-block-surface`; the base model only carries them, and knows
+     * nothing about nudges. Ids of nudges no framework declares any more are kept,
+     * not pruned: the tooling comes and goes with a flag, the decision does not.
+     */
+    accessor qualityChecklist: string[] | undefined;
+    /**
+     * Verbatim foreign matter from an interchange import, keyed by FORMAT id
+     * (`bpmn`, `owm`, …) — never by framework, because a `.bpmn` and an OWM file
+     * make different promises about the same element (ADR 0012 § D2).
+     *
+     * This field is dumb storage, and that is the whole design. ADR 0012 sorts
+     * every node of an imported file into three states — **mapped** (there is a
+     * Labre artefact, re-emitted from the drawing), **carried** (no artefact,
+     * kept verbatim here, re-emitted in place) and **quarantined** (kept, but
+     * re-emitting it would contradict the document, so it is not). That contract
+     * lives entirely in the importers and exporters; the base model neither
+     * classifies, validates, dereferences nor re-emits anything, and knows no
+     * format. No renderer, hit-test, layout or `@derive` / `@convert` chain reads
+     * it, so nothing here can move, resize or restyle an element.
+     *
+     * Declared on the BASE class for the same reason as {@link role} and
+     * {@link validationExceptions}, and for one more: a BPMN `sequenceFlow`
+     * carrying a `conditionExpression` is a plain **connector**, and
+     * `ConnectorElementModel` is shared plumbing that will never be a BPMN class.
+     * An element re-created from props (paste, duplicate, alt-drag clone,
+     * template insertion) only reaches the Y.Map through keys that have a
+     * declared accessor, so a payload declared per subclass would be silently
+     * dropped on copy — the exact loss `docs/spikes/us-1-8-unknown-props-preservation.md`
+     * exists to prevent. Declaring it, rather than leaning on that spike's
+     * verbatim fallback for undeclared keys, is what makes it a contract: a field
+     * nothing declares is a field nothing can test, strip or find.
+     *
+     * `undefined` = this element never met an import, and no key is written for
+     * it, so it stays byte-identical to one created before the field existed:
+     * optional field, no schema version bump, no migration. An import writes no
+     * key for a visual-tier capability, and none for an element that carried
+     * nothing. Clearing goes through {@link clearField}, which removes the key
+     * rather than leaving a tombstone.
+     *
+     * Flat JSON on purpose — a value a Yjs update can encode is the contract
+     * enforced by `_assignElementProp`, and the whole payload is ONE Y.Map entry,
+     * written once at import and never mutated afterwards. Two peers writing it
+     * concurrently therefore resolve last-write-wins on the whole blob, which is
+     * `lanes`' trade (ADR 0007): nobody edits this value, so the window is the
+     * import itself.
+     *
+     * ## Writing it, for the importer
+     *
+     * - **Write the whole blob in one assignment**, the way an import already
+     *   produces it. Never read-modify-write it key by key: the Y.Map entry is the
+     *   entire `Record`, so a partial update is still a last-write-wins overwrite
+     *   of everything, and two of them racing lose a whole format's payload rather
+     *   than merging.
+     * - **Key what you carry by its {@link InterchangeScope}.** One Labre element
+     *   stands for several source elements, and an unscoped map lets what came off
+     *   one overwrite what came off another — a silent loss, into a persisted
+     *   value, of exactly the data this field exists to keep. The scope is also
+     *   the only record of where a fragment has to be put back.
+     * - **Write no key at all** when there is nothing to carry — an element the
+     *   import mapped cleanly, or any visual-tier capability, which by contract
+     *   writes none (ADR 0012 P2). Absent and empty are NOT equivalent here:
+     *   `{}` costs every element a Y.Map entry and makes P2's "writes no
+     *   `interchange` key" untestable.
+     * - **Removing it is {@link clearField}**, never an assignment to `undefined`
+     *   — the former deletes the key, the latter can leave a tombstone.
+     * - **Nothing caps the size of this value** (ADR 0012, open question 3). A
+     *   pathological file would produce a document that is mostly foreign matter;
+     *   a cap that dropped data would contradict D2, so the only honest cap is a
+     *   refusal at import time. That is the importer's call, not the model's.
+     */
+    accessor interchange: Record<string, ForeignInterchange> | undefined;
     accessor lockedBySelf: boolean | undefined;
     accessor opacity: number;
     accessor responseExtension: [number, number];
@@ -115,6 +519,17 @@ export declare abstract class GfxPrimitiveElementModel<Props extends BaseElement
 export declare abstract class GfxGroupLikeElementModel<Props extends BaseElementProps = BaseElementProps> extends GfxPrimitiveElementModel<Props> implements GfxGroupCompatibleInterface {
     private _childIds;
     private readonly _mutex;
+    /**
+     * Whether the cached `xywh` must be recomputed from the children.
+     *
+     * The bound of a group is the union of its children bounds, which used to be
+     * recomputed on **every** read of `xywh` — and `xywh` is read many times per
+     * frame (renderer, hit test, toolbar anchor, selection rect…). It is now
+     * computed once per mutation: the surface marks the group dirty (or
+     * refreshes it eagerly) whenever a child changes, see
+     * {@link invalidateXYWH} / {@link refreshXYWH}.
+     */
+    private _xywhDirty;
     abstract children: Y.Map<any>;
     [gfxGroupCompatibleSymbol]: true;
     get childElements(): GfxModel[];
@@ -126,7 +541,34 @@ export declare abstract class GfxGroupLikeElementModel<Props extends BaseElement
     get descendantElements(): GfxModel[];
     get xywh(): `[${number},${number},${number},${number}]`;
     set xywh(_: `[${number},${number},${number},${number}]`);
+    /**
+     * Recompute the cached bound and notify the listeners when it moved.
+     *
+     * Always run it through {@link _mutex}: the notification re-enters the
+     * `xywh` getter (a parent group unites this bound again), and the mutex is
+     * what keeps that read from recomputing this very group a second time.
+     */
+    private _recomputeXYWH;
+    /**
+     * Pure: it only reads the children. The cache is written by
+     * {@link _recomputeXYWH}, which is the single place allowed to store it.
+     */
     protected _getXYWH(): Bound;
+    /**
+     * Mark the cached bound as stale without recomputing it. The next read of
+     * `xywh` pays for the recomputation, and notifies the listeners if the
+     * bound actually moved.
+     *
+     * Use it for the changes that only *may* move the bound (a custom prop a
+     * subclass folds into its own `elementBound`); use {@link refreshXYWH} for
+     * the changes that are known to move it.
+     */
+    invalidateXYWH(): void;
+    /**
+     * Recompute the cached bound right away, and notify the listeners when it
+     * moved. `local` is the origin of the mutation that moved it.
+     */
+    refreshXYWH(local: boolean): void;
     abstract addChild(element: GfxModel): void;
     /**
      * The actual field that stores the children of the group.