@formicoidea/labre-core 0.31.0 → 0.32.0

package/dist/_pkgs/std/extension/translation-manifest.js

@@ -0,0 +1,71 @@
+import { toCommandManifestEntry, } from './command-registry.js';
+const KEY_PREFIX = 'com.labre.';
+function walk(source, value, out, seen) {
+    if (typeof value !== 'object' || value === null)
+        return;
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walk(source, item, out, seen);
+        return;
+    }
+    const record = value;
+    for (const [prop, propValue] of Object.entries(record)) {
+        if (typeof propValue === 'string' &&
+            prop.endsWith('Key') &&
+            propValue.startsWith(KEY_PREFIX)) {
+            if (out.has(propValue))
+                continue;
+            const stem = prop.slice(0, -'Key'.length);
+            const fallback = record[`${stem}Fallback`] ??
+                (prop === 'labelKey' ? record.fallback : undefined);
+            out.set(propValue, {
+                key: propValue,
+                ...(typeof fallback === 'string' ? { fallback } : {}),
+                source,
+            });
+        }
+        else {
+            walk(source, propValue, out, seen);
+        }
+    }
+}
+/**
+ * Deep-walk a declaration and collect every `…Key` string property holding a
+ * `com.labre.*` key, paired with its fallback by the repo's own conventions:
+ * `<stem>Key` ↔ `<stem>Fallback` (roles, rules, commands, conventions), and
+ * `labelKey` ↔ `fallback` (profiles, nudges, criteria, background labels).
+ *
+ * This is what makes the manifest DERIVED rather than restated: a key added to
+ * a rule or a role shows up with no further work.
+ */
+export function collectTranslationKeys(source, value) {
+    const out = new Map();
+    walk(source, value, out, new WeakSet());
+    return [...out.values()];
+}
+/**
+ * A command group's contribution. Walks the SERIALIZABLE projection, not the
+ * descriptors: `run` and the zod schemas carry no keys and walking them would
+ * mean walking zod internals.
+ */
+export function commandTranslationEntries(commands) {
+    return collectTranslationKeys('command', commands.map(toCommandManifestEntry));
+}
+/**
+ * Compose contributions into one manifest: first occurrence of a key wins (so
+ * the caller's order decides which `source` a shared key reports), sorted by
+ * key so two hosts composing the same parts get the same list.
+ */
+export function mergeTranslationEntries(...groups) {
+    const out = new Map();
+    for (const group of groups) {
+        for (const entry of group) {
+            if (!out.has(entry.key))
+                out.set(entry.key, entry);
+        }
+    }
+    return [...out.values()].sort((a, b) => a.key.localeCompare(b.key));
+}

package/dist/_pkgs/std/gfx/index.d.ts

@@ -1,6 +1,6 @@
 export { generateKeyBetweenV2 } from '../utils/fractional-indexing.js';
 export { compare as compareLayer, renderableInEdgeless, SortOrder, } from '../utils/layer.js';
-export { canSafeAddToContainer, descendantElementsImpl, getTopElements, hasDescendantElementImpl, } from '../utils/tree.js';
+export { batchAddChildren, batchRemoveChildren, canSafeAddToContainer, descendantElementsImpl, getTopElements, hasDescendantElementImpl, } from '../utils/tree.js';
 export { GfxController } from './controller.js';
 export type { CursorType, StandardCursor } from './cursor.js';
 export { GfxExtension, GfxExtensionIdentifier } from './extension.js';
@@ -13,10 +13,14 @@ export type { GfxCompatibleInterface, GfxElementGeometry, GfxGroupCompatibleInte
 export { gfxGroupCompatibleSymbol, isGfxGroupCompatibleModel, } from './model/base.js';
 export { GfxBlockElementModel, type GfxCommonBlockProps, GfxCompatibleBlockModel as GfxCompatible, type GfxCompatibleProps, } from './model/gfx-block-model.js';
 export { type GfxModel, isPrimitiveModel } from './model/model.js';
-export { convert, convertProps, derive, field, getDerivedProps, getFieldPropsSet, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
-export { type BaseElementProps, GfxGroupLikeElementModel, GfxPrimitiveElementModel, type SerializedElement, } from './model/surface/element-model.js';
+export { convert, convertProps, derive, field, getDerivedProps, getFieldPropsSet, getLocalPropsSet, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
+export { type BaseElementProps, GfxGroupLikeElementModel, GfxPrimitiveElementModel, type SerializedElement, type ValidationException, } from './model/surface/element-model.js';
 export { GfxLocalElementModel, prop, } from './model/surface/local-element-model.js';
+export { collectPivotOccurrences, isPivotBound, type PivotBoundElement, type PivotOccurrence, } from './model/surface/pivot.js';
+export { type EdgeDirectionDef, findRoleDef, isTypedEdgeRole, type RoleDef, type RoleDefs, type RoleId, roleIsA, type RoleKind, RoleVocabularyExtension, RoleVocabularyIdentifier, } from './model/surface/role.js';
+export { ELEMENT_TAGS_FIELD, type ElementTags, elementTagValues, hasElementTagValue, readElementTags, setElementTag, tagsPropToY, } from './model/surface/tags.js';
 export { SURFACE_TEXT_UNIQ_IDENTIFIER, SURFACE_YMAP_UNIQ_IDENTIFIER, SurfaceBlockModel, type SurfaceBlockProps, type SurfaceMiddleware, } from './model/surface/surface-model.js';
+export { measureOperation } from './perf.js';
 export { GfxSelectionManager } from './selection.js';
 export { SurfaceMiddlewareBuilder, SurfaceMiddlewareExtension, } from './surface-middleware.js';
 export { BaseTool, type ToolOptions, type ToolOptionWithType, type ToolType, } from './tool/tool.js';

package/dist/_pkgs/std/gfx/index.js

@@ -1,6 +1,6 @@
 export { generateKeyBetweenV2 } from '../utils/fractional-indexing.js';
 export { compare as compareLayer, renderableInEdgeless, SortOrder, } from '../utils/layer.js';
-export { canSafeAddToContainer, descendantElementsImpl, getTopElements, hasDescendantElementImpl, } from '../utils/tree.js';
+export { batchAddChildren, batchRemoveChildren, canSafeAddToContainer, descendantElementsImpl, getTopElements, hasDescendantElementImpl, } from '../utils/tree.js';
 export { GfxController } from './controller.js';
 export { GfxExtension, GfxExtensionIdentifier } from './extension.js';
 export { GridManager } from './grid.js';
@@ -10,10 +10,14 @@ export { LayerManager } from './layer.js';
 export { gfxGroupCompatibleSymbol, isGfxGroupCompatibleModel, } from './model/base.js';
 export { GfxBlockElementModel, GfxCompatibleBlockModel as GfxCompatible, } from './model/gfx-block-model.js';
 export { isPrimitiveModel } from './model/model.js';
-export { convert, convertProps, derive, field, getDerivedProps, getFieldPropsSet, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
+export { convert, convertProps, derive, field, getDerivedProps, getFieldPropsSet, getLocalPropsSet, initializeObservers, initializeWatchers, local, observe, updateDerivedProps, watch, } from './model/surface/decorators/index.js';
 export { GfxGroupLikeElementModel, GfxPrimitiveElementModel, } from './model/surface/element-model.js';
 export { GfxLocalElementModel, prop, } from './model/surface/local-element-model.js';
+export { collectPivotOccurrences, isPivotBound, } from './model/surface/pivot.js';
+export { findRoleDef, isTypedEdgeRole, roleIsA, RoleVocabularyExtension, RoleVocabularyIdentifier, } from './model/surface/role.js';
+export { ELEMENT_TAGS_FIELD, elementTagValues, hasElementTagValue, readElementTags, setElementTag, tagsPropToY, } from './model/surface/tags.js';
 export { SURFACE_TEXT_UNIQ_IDENTIFIER, SURFACE_YMAP_UNIQ_IDENTIFIER, SurfaceBlockModel, } from './model/surface/surface-model.js';
+export { measureOperation } from './perf.js';
 export { GfxSelectionManager } from './selection.js';
 export { SurfaceMiddlewareBuilder, SurfaceMiddlewareExtension, } from './surface-middleware.js';
 export { BaseTool, } from './tool/tool.js';

package/dist/_pkgs/std/gfx/interactivity/gfx-view-event-handler.js

@@ -1,5 +1,6 @@
 import { Bound } from '../../../global/gfx/index.js';
 import last from 'lodash-es/last.js';
+import { compare } from '../../utils/layer.js';
 export class GfxViewEventManager {
     _callInReverseOrder(callback, arr = this._hoveredElementsStack) {
         for (let i = arr.length - 1; i >= 0; i--) {
@@ -61,7 +62,11 @@ export class GfxViewEventManager {
                 view && pre.push(view);
             }
             return pre;
-        }, []);
+        }, [])
+            // Sort by paint order (same convention as `getElementByPoint`) so the
+            // stack's last entry — the click/dblclick target — is the TOPMOST view,
+            // not whichever the grid returned last (e.g. a background under a node).
+            .sort((a, b) => compare(a.model, b.model));
         const currentStackedViews = new Set(this._hoveredElementsStack);
         const visited = new Set();
         this._callInReverseOrder(view => {

package/dist/_pkgs/std/gfx/interactivity/manager.d.ts

@@ -26,6 +26,14 @@ export declare class InteractivityManager extends GfxExtension {
     unmounted(): void;
     get interactExtensions(): Map<string, import("./index.js").InteractivityExtension>;
     get keyboard(): import("../keyboard.js").KeyboardController;
+    /**
+     * Move, resize, rotate and clone all commit through `@field()` accessors,
+     * i.e. raw `store.transact` calls that never pass by a crud layer and are
+     * therefore invisible to any guard placed there. Callers are expected to
+     * refuse first (`DefaultTool.dragStart`, `edgeless-selected-rect`); this is
+     * the backstop for the ones that forget.
+     */
+    private get _readonly();
     private _safeExecute;
     /**
      * Dispatch event to extensions and gfx view.

package/dist/_pkgs/std/gfx/interactivity/manager.js

@@ -39,6 +39,16 @@ export class InteractivityManager extends GfxExtension {
     get keyboard() {
         return this.gfx.keyboard;
     }
+    /**
+     * Move, resize, rotate and clone all commit through `@field()` accessors,
+     * i.e. raw `store.transact` calls that never pass by a crud layer and are
+     * therefore invisible to any guard placed there. Callers are expected to
+     * refuse first (`DefaultTool.dragStart`, `edgeless-selected-rect`); this is
+     * the backstop for the ones that forget.
+     */
+    get _readonly() {
+        return this.std.store.readonly;
+    }
     _safeExecute(fn, errorMessage) {
         try {
             fn();
@@ -219,6 +229,8 @@ export class InteractivityManager extends GfxExtension {
      * Note: Call this when mouse is already down.
      */
     handleElementMove(options) {
+        if (this._readonly)
+            return;
         let cancelledByExt = false;
         const context = {
             /**
@@ -346,6 +358,8 @@ export class InteractivityManager extends GfxExtension {
         dragStart();
     }
     handleElementRotate(options) {
+        if (this._readonly)
+            return;
         const { rotatable, viewConfigMap, initialRotate } = this._getViewRotateConfig(options.elements);
         if (!rotatable) {
             return;
@@ -624,6 +638,8 @@ export class InteractivityManager extends GfxExtension {
         return this._getViewResizeConfig(options.elements).allowedHandlers;
     }
     handleElementResize(options) {
+        if (this._readonly)
+            return;
         const { viewConfigMap, allowedHandlers } = this._getViewResizeConfig(options.elements);
         if (!allowedHandlers.includes(options.handle)) {
             return;
@@ -766,6 +782,8 @@ export class InteractivityManager extends GfxExtension {
         });
     }
     requestElementClone(options) {
+        if (this._readonly)
+            return Promise.resolve(undefined);
         const extensions = this.interactExtensions;
         for (let ext of extensions.values()) {
             const cloneData = ext.action.emit('elementsClone', options);

package/dist/_pkgs/std/gfx/layer.d.ts

@@ -28,7 +28,7 @@ export type BlockLayer = BaseLayer<GfxBlockElementModel> & {
 export type CanvasLayer = BaseLayer<GfxPrimitiveElementModel> & {
     type: 'canvas';
     /**
-     * The z-index of canvas layer.
+     * The z-index of the first element in this canvas layer.
      *
      * A canvas layer renders all the elements in a single canvas,
      *  this property is used to render the canvas with correct z-index.

package/dist/_pkgs/std/gfx/layer.js

@@ -73,8 +73,7 @@ export class LayerManager extends GfxExtension {
                 ];
                 curLayer.zIndex = currentCSSZindex;
                 layers.push(curLayer);
-                currentCSSZindex +=
-                    curLayer.type === 'block' ? curLayer.elements.length : 1;
+                currentCSSZindex += curLayer.elements.length;
             }
         };
         const addLayer = (type) => {

package/dist/_pkgs/std/gfx/model/surface/decorators/field.js

@@ -20,6 +20,15 @@ export function field(fallback) {
                 if (getDecoratorState(this.surface ?? Object.getPrototypeOf(this).constructor)?.skipField) {
                     return;
                 }
+                // An `undefined` default is written nowhere: an optional field stays
+                // ABSENT from the Y.Map until something actually assigns it (the getter
+                // falls back to `fallback` anyway). This keeps an element that does not
+                // use the field byte-identical to one created before the field existed
+                // — the property that lets optional fields ship without a schema
+                // version bump nor a migration.
+                if (v === undefined) {
+                    return v;
+                }
                 if (this.yMap) {
                     if (this.yMap.doc) {
                         this.surface.store.transact(() => {

package/dist/_pkgs/std/gfx/model/surface/decorators/index.d.ts

@@ -1,6 +1,6 @@
 export { convert, convertProps } from './convert.js';
 export { derive, getDerivedProps, updateDerivedProps } from './derive.js';
 export { field, getFieldPropsSet } from './field.js';
-export { local } from './local.js';
-export { initializeObservers, observe } from './observer.js';
+export { getLocalPropsSet, local } from './local.js';
+export { hasObserveMeta, initializeObservers, observe, startObserve, } from './observer.js';
 export { initializeWatchers, watch } from './watch.js';

package/dist/_pkgs/std/gfx/model/surface/decorators/index.js

@@ -1,6 +1,6 @@
 export { convert, convertProps } from './convert.js';
 export { derive, getDerivedProps, updateDerivedProps } from './derive.js';
 export { field, getFieldPropsSet } from './field.js';
-export { local } from './local.js';
-export { initializeObservers, observe } from './observer.js';
+export { getLocalPropsSet, local } from './local.js';
+export { hasObserveMeta, initializeObservers, observe, startObserve, } from './observer.js';
 export { initializeWatchers, watch } from './watch.js';

package/dist/_pkgs/std/gfx/model/surface/decorators/local.d.ts

@@ -1,4 +1,18 @@
 import type { GfxPrimitiveElementModel } from '../element-model.js';
+/**
+ * The set of prop names declared with `@local()` on an element class.
+ *
+ * Mirrors `getFieldPropsSet` (see `./field.js`) for the non-synced half of the
+ * accessor surface. Together the two sets are the only reliable answer to "does this
+ * element class declare an accessor for this key" — `key in element` is not:
+ * it also matches methods, getter-only derived props (`x`, `w`, `group`, …)
+ * and internal instance fields.
+ *
+ * The set is keyed on the most derived prototype and filled by the decorator's
+ * `init`, which runs for every accessor (base and derived) during the first
+ * construction of an element of that class.
+ */
+export declare function getLocalPropsSet(target: unknown): Set<string | symbol>;
 /**
  * A decorator to mark the property as a local property.
  *

package/dist/_pkgs/std/gfx/model/surface/decorators/local.js

@@ -1,6 +1,27 @@
 import { getDecoratorState } from './common.js';
 import { convertProps } from './convert.js';
 import { getDerivedProps, updateDerivedProps } from './derive.js';
+const localPropsSetSymbol = Symbol('localProps');
+/**
+ * The set of prop names declared with `@local()` on an element class.
+ *
+ * Mirrors `getFieldPropsSet` (see `./field.js`) for the non-synced half of the
+ * accessor surface. Together the two sets are the only reliable answer to "does this
+ * element class declare an accessor for this key" — `key in element` is not:
+ * it also matches methods, getter-only derived props (`x`, `w`, `group`, …)
+ * and internal instance fields.
+ *
+ * The set is keyed on the most derived prototype and filled by the decorator's
+ * `init`, which runs for every accessor (base and derived) during the first
+ * construction of an element of that class.
+ */
+export function getLocalPropsSet(target) {
+    const proto = Object.getPrototypeOf(target);
+    if (!Object.hasOwn(proto, localPropsSetSymbol)) {
+        proto[localPropsSetSymbol] = new Set();
+    }
+    return proto[localPropsSetSymbol];
+}
 /**
  * A decorator to mark the property as a local property.
  *
@@ -12,6 +33,7 @@ export function local() {
         const prop = context.name;
         return {
             init(v) {
+                getLocalPropsSet(this).add(prop);
                 this._local.set(prop, v);
                 return v;
             },

package/dist/_pkgs/std/gfx/model/surface/decorators/observer.d.ts

@@ -20,5 +20,7 @@ transaction: Y.Transaction | null) => void;
  */
 export declare function observe<V, E extends Y.YEvent<any>, T extends GfxPrimitiveElementModel>(fn: ObserveFn<E, T>): (_: unknown, context: ClassAccessorDecoratorContext) => ClassAccessorDecoratorResult<GfxPrimitiveElementModel, V>;
 export declare function startObserve(prop: string | symbol, receiver: GfxPrimitiveElementModel): void;
+/** Whether an `@observe`d nested Y type is declared for this prop. */
+export declare function hasObserveMeta(prop: string | symbol, receiver: GfxPrimitiveElementModel): boolean;
 export declare function initializeObservers(proto: unknown, receiver: GfxPrimitiveElementModel): void;
 export {};

package/dist/_pkgs/std/gfx/model/surface/decorators/observer.js

@@ -49,9 +49,48 @@ export function startObserve(prop, receiver) {
             value.unobserve(fn);
         };
     }
-    else {
+    else if (value != null && !isPlainObject(value)) {
         console.warn(`Failed to observe "${prop.toString()}" of ${receiver.type} element, make sure it's a Y type.`);
     }
+    // Two shapes are deliberately NOT warned about, because neither is the
+    // misconfiguration this warning exists to catch (`@observe` on a field that
+    // is not a Y type):
+    //
+    // - **Absent.** `GfxPrimitiveElementModel.tags` defaults to `undefined` and
+    //   stays absent until something qualifies the element, so every unqualified
+    //   element — i.e. almost all of them — would log once per mount.
+    // - **A PLAIN object.** That is the DEGRADED shape a client predating the
+    //   field writes through the unknown-key branch (see `../tags.ts`). It is a
+    //   document value of another vintage, not a programmer error, and nothing
+    //   the user can act on; reading it is handled, and the first write converts
+    //   it. Warning once per affected element per mount would be pure noise on a
+    //   board the user did nothing wrong to produce.
+    //
+    // The silence is kept exactly as narrow as the reason for it: an array, a
+    // `Map`, a class instance — anything that is not a bare JSON object — still
+    // warns, so an `@observe` put by mistake on a non-Y field is still caught.
+    //
+    // Either way the observer is re-attached the moment a real Y type lands on
+    // the key: `@field()`'s setter calls `startObserve`, and `syncElementFromY`
+    // calls it for the paths that never reach the setter (a remote peer, undo,
+    // redo).
+}
+/**
+ * A bare JSON object — `{}` or `Object.create(null)` — and nothing else.
+ *
+ * The test is the prototype rather than `typeof`, because `typeof x ===
+ * 'object'` is true of arrays, `Map`s, `Date`s and every class instance, none
+ * of which any client writes into a document field.
+ */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Whether an `@observe`d nested Y type is declared for this prop. */
+export function hasObserveMeta(prop, receiver) {
+    return getObserveMeta(Object.getPrototypeOf(receiver), prop) !== null;
 }
 export function initializeObservers(proto, receiver) {
     const observers = getObjectPropMeta(proto, observeSymbol);