Skip to main content

Host implementation notes

This page complements the Integrator guide (public contract). Cubre el cableado interno del host UppKonvaFloorPlanHostComponent (upp-konva-floor-plan) con UppFloorPlanStageComponent.

UppKonvaComponent (upp-konva) no duplica el stage en otro sitio: su plantilla incrusta upp-konva-floor-plan pasando [model]="model.sceneModel" (el UppKonvaFloorPlanModel interno del UppKonvaModel) y reenvía onChange, onSelect, active y theme. El integrador que usa upp-konva no toca este detalle salvo depuración.

UppKonvaModule declara el stage y el host interno upp-konva-floor-plan para las plantillas de la librería y solo exporta UppKonvaComponent; UppFloorPlanStageComponent y UppKonvaFloorPlanHostComponent no son API de aplicación.

Wiring overview​

  1. [model] is required (UppKonvaFloorPlanModel). On first bind (or when the reference changes), UppKonvaFloorPlanHostComponent saves the integrator’s onModelChanged callback and replaces it with a wrapper that:
    • invokes the saved callback (if any);
    • emits (onChange) with uppKonvaAreaWire(model.area) on structural shapes changes.
  2. The internal uppKonvaSceneModelHost(model).onRefresh hook runs ChangeDetectorRef.markForCheck() and re-seeds the host’s geometry snapshot cache used for deduplication before forwarding geometry to UppKonvaShapeHandle.onUpdated (edit mode). uppKonvaSceneModelHost lives under libs/upp-konva/src/lib/stage/internal/ and is not exported from the public barrel.
  3. When ViewChild resolves the stage, bindUppKonvaStageFloor(model, floor) (internal bridge) registers the floor instance so lab/tests can call stageSelectOnly / stageClearSelection / stageGetSelection — not part of the public UppKonvaFloorPlanModel API.
  4. uppKonvaSceneModelHost(model).bindFloorRefresh syncs geometry snapshots and calls refreshFromModel() on the stage; bindExportToPng delegates raster export.
  5. The stage’s [preferences] input binds to uppKonvaSceneModelHost(model).presentationPreferences (effective merged prefs). Integrators do not use a presentationPreferences property on UppKonvaFloorPlanModel; they set framing via UppKonvaModel (marginPx, viewZoom, pixelRatioMax, DTO de sala) — ver la referencia TypeDoc en Public model API.

Structural vs presentation (UppKonvaFloorPlanModel)​

Assignment model.area = … runs _applyAreaFromDto. The model compares a JSON fingerprint of shapes before and after. If the list changes structurally, onModelChanged fires. Otherwise the scene updates without onModelChanged; the host still repaints via uppKonvaSceneModelHost(model).onRefresh (no public onPresentationChanged on the model).

Multi-selection (onGrouped)​

When the stage’s selection changes, the host calls uppKonvaSceneModelHost(model).notifyGrouped, which forwards to area.onGrouped en el wire del motor: UppKonvaFloorPlanGroup si ≥ 2 elementos, null si 0–1. UppKonvaModel enlaza eso al UppKonvaArea público vía onGrouped$ y UppKonvaGroup; las apps de producto se suscriben al stream, no al callback del DTO interno.

Lifecycle and cleanup​

  • ngOnDestroy: restores onModelChanged, clears onRefresh, bindFloorRefresh, bindExportToPng, and bindUppKonvaStageFloor(model, null). This avoids invoking a destroyed stage when the model is still mutated (e.g. uppKonvaSceneModelHost(model).setPresentationPreferences after the view is gone).
  • [model] reference change: the previous model is torn down the same way before wiring the new instance.

Caveat: If the integrator reassigns model.onModelChanged after the host has wrapped it, that replaces the wrapper. Prefer (onChange) in the template or set callbacks before the host mounts (see integrator guide).

Geometry and selection (host only)​

Stage selection / activate / geometry events invoke stageInvokeSelection (UUID list), stageInvokeActivate, stageInvokeGeometry on the internal bridge. Optional setUppKonvaStageHooks (lab/tests only) receives those notifications via onSelect on the hook object for selection; las apps de producto usan (onSelect) en upp-konva, onSelected$ / onUpdated$ en figuras vivas y onGrouped$ en el área. Geometry uses floorPlanPresentationGeometryPartition to avoid duplicate work when Konva sends redundant transform events. onUpdated on UppKonvaShapeHandle is invoked from the host only in EDIT mode when translate/rotate is considered new.

  • Integrator guide — public API and examples.
  • Public model API — referencia TypeDoc del modelo.
  • libs/upp-konva/src/lib/stage/presentation/upp-floor-plan-presentation.mdc — functional spec (Spanish).
  • upp-floor-plan.mdc — internal stage maintainer contract.