@formicoidea/labre-core 0.31.0 → 0.32.0

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

@@ -11,6 +11,28 @@ 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;
 };
 export type SerializedElement = Record<string, unknown> & {
     type: string;
@@ -90,6 +112,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 +166,191 @@ 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;
     accessor lockedBySelf: boolean | undefined;
     accessor opacity: number;
     accessor responseExtension: [number, number];
@@ -115,6 +359,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 +381,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.