@liquidcars/atlas 0.1.15 → 0.1.16

package/README.md

@@ -65,6 +65,21 @@ atlas.setTheme({
   ui: { breadcrumbs: true, panel: true, toolbar: true, hint: false }
 });
 atlas.setPalette({ channels: '#58b6ec', offers: '#48c8b0', connection: '#f4edba' });
+
+// El componente se puede modificar sin volver a crearlo.
+atlas.addEntity({ id: 'service', name: 'Service', geometry: 'cone', p: [4, 0, 0], s: [2, 2, 2] });
+atlas.updateEntity('service', { text: 'Servicio actualizado', c: '#ed8f98' });
+atlas.addRelation({ from: 'service', to: 'offers', label: 'publica', mode: 'bidirectional' });
+atlas.updateRelation(0, { mode: 'broken' });
+atlas.removeRelation(0);
+atlas.removeEntity('service');
+
+atlas.addEventListener('lc-select', event => {
+  console.log('Entidad seleccionada:', event.detail.id, event.detail.entity);
+});
+atlas.addEventListener('lc-model-change', event => {
+  console.log('Modelo actualizado:', event.detail.kind);
+});
 ```
 
 El mismo bloque `theme` puede formar parte del JSON del modelo. Los estilos
@@ -73,7 +88,12 @@ principales también están expuestos como variables CSS (`--lc-bg`,
 por lo que una aplicación puede adaptar la apariencia sin modificar el bundle.
 Las propiedades `atlas.theme` y `atlas.styles` son alias prácticos de esta configuración.
 
-Eventos disponibles: `lc-ready`, `lc-error`, `lc-select`, `lc-relation-mode` y `lc-disconnect`.
+Eventos disponibles: `lc-ready`, `lc-error`, `lc-select`, `lc-model-change`,
+`lc-relation-mode` y `lc-disconnect`. `lc-select` incluye `{ id, entity,
+source }` en `event.detail`; cuando se vuelve a la vista general emite `id:
+null`. Los eventos de selección y cambios de modelo son `bubbles` y
+`composed`, por lo que funcionan también al integrar el componente en otras
+capas de Web Components.
 
 ## Contrato de datos
 
@@ -83,6 +103,10 @@ Eventos disponibles: `lc-ready`, `lc-error`, `lc-select`, `lc-relation-mode` y `
 - `p` es la posición local respecto a `parent`; una entidad sin `parent` usa coordenadas de escena.
 - `s` son dimensiones absolutas locales `[x, y, z]`.
 - `relations` acepta objetos `{from, to, label}` o la forma corta `[from, to, label]`.
+  El campo visual opcional `mode` admite `directed` (por defecto),
+  `bidirectional` y `broken`. En modo bidireccional los indicadores animados
+  circulan en ambos sentidos por el mismo tubo; en modo broken el tubo aparece
+  interrumpido en su punto medio.
 
 Geometrías incluidas en esta primera versión: `box`, `cylinder`, `sphere`, `cone`, `frustum-cone`, `frustum-pyramid`, `frustum-triangle`, `prism`, `pyramid-square`, `pyramid-triangle`, `octahedron`, `dodecahedron` e `icosahedron`. Las variantes `frustum-*` son sólidos truncados con dos caras finitas paralelas; las dimensiones `s` se aplican sobre su caja final normalizada.
 
@@ -90,6 +114,13 @@ La paleta puede cambiarse después de cargar el modelo mediante `atlas.setPalett
 
 Las acciones de navegación y exploración de la toolbar también están disponibles para la página anfitriona: `zoomIn()`, `zoomOut()`, `fit()`, `frontView()`, `setShellLabels()`, `toggleShellLabels()`, `openAllContainers()` y `closeAllContainers()`. Así se puede construir una barra de controles propia sin depender de la toolbar interna.
 
+La escena también se puede editar en caliente. `updateModel(patch)` reemplaza
+las secciones indicadas; `addEntity`, `updateEntity` y `removeEntity` gestionan
+entidades, mientras `addRelation`, `updateRelation` y `removeRelation`
+gestionan relaciones. Cada operación reconstruye la geometría necesaria,
+conserva la cámara y la selección cuando sigue siendo válida, y emite
+`lc-model-change` con el tipo de operación y el modelo resultante.
+
 ## Distribución
 
 El archivo `dist/liquidcars-atlas.js` es un módulo ESM autocontenido: Three.js se incluye dentro del bundle, por lo que el consumidor no necesita instalar otra dependencia para probarlo. El bundle no contiene ningún modelo de negocio ni datos de LiquidCars Atlas; los modelos se suministran aparte mediante `model`, `src` o un `<script type="application/json">`. Para una distribución privada se puede servir ese archivo desde un CDN propio o desde el mismo sitio. Para publicar en npm, después de revisar el API estable:
@@ -108,4 +139,4 @@ npm install ./liquidcars-atlas-0.1.15.tgz
 
 ## Estado
 
-`0.1.15` mantiene la corrección del desplazamiento interno del texto y ancla las etiquetas a las dimensiones reales de las geometrías redondeadas. Además fija un margen superior absoluto para las etiquetas secundarias de contenedores abiertos, situado dentro del frontal del contenedor y sin depender de sus dimensiones. También corrige los sólidos truncados, normaliza sus dimensiones finales, refuerza la visibilidad de la toolbar con el atributo `toolbar="on"`/`"off"` y `setToolbarVisible()`, desacopla la paleta por defecto de nombres de dominio, añade actualización programática de la paleta con `setPalette`, expone las acciones de navegación para controles externos y mantiene siempre visibles las ayudas de interacción dentro del viewport.
+`0.1.16` mantiene la corrección del desplazamiento interno del texto y ancla las etiquetas a las dimensiones reales de las geometrías redondeadas. Además fija un margen superior absoluto para las etiquetas secundarias de contenedores abiertos, situado dentro del frontal del contenedor y sin depender de sus dimensiones. También corrige los sólidos truncados, normaliza sus dimensiones finales, refuerza la visibilidad de la toolbar con el atributo `toolbar="on"`/`"off"` y `setToolbarVisible()`, desacopla la paleta por defecto de nombres de dominio, añade actualización programática de la paleta con `setPalette`, expone las acciones de navegación para controles externos y mantiene siempre visibles las ayudas de interacción dentro del viewport. Esta versión añade edición en caliente de entidades y relaciones, eventos compuestos de selección y los modos de relación `directed`, `bidirectional` y `broken`.

package/dist/liquidcars-atlas.js

@@ -1,6 +1,11 @@
-/*! LiquidCars Atlas 0.1.15 | MIT */
+/*! LiquidCars Atlas 0.1.16 | MIT */
 
 // src/three.core.js
+/**
+ * @license
+ * Copyright 2010-2025 Three.js Authors
+ * SPDX-License-Identifier: MIT
+ */
 var REVISION = "180";
 var CullFaceNone = 0;
 var CullFaceBack = 1;
@@ -19224,6 +19229,11 @@ if (typeof window !== "undefined") {
 }
 
 // src/three.module.js
+/**
+ * @license
+ * Copyright 2010-2025 Three.js Authors
+ * SPDX-License-Identifier: MIT
+ */
 function WebGLAnimation() {
   let context = null;
   let isAnimating = false;
@@ -29371,6 +29381,13 @@ function normalizeModel(input) {
   const relations = Array.isArray(source.relations) ? source.relations.map((relation, index) => Array.isArray(relation) ? { from: relation[0], to: relation[1], label: relation[2] || "", index } : { ...relation, from: relation.from, to: relation.to, label: relation.label || "", index }) : [];
   return { ...source, palette: { ...DEFAULT_PALETTE, ...source.palette || {} }, theme: normalizeTheme(source.theme || source.styles), entities, relations };
 }
+function relationVisualMode(relation) {
+  if (!relation || typeof relation !== "object") return "directed";
+  const raw = String(relation.mode || relation.visual || relation.render || relation.type || relation.direction || "").toLowerCase();
+  if (relation.bidirectional === true || ["bidirectional", "both", "two-way", "two_way", "duplex"].includes(raw)) return "bidirectional";
+  if (relation.broken === true || ["broken", "interrupted", "\u65AD"].includes(raw)) return "broken";
+  return "directed";
+}
 function roundedBox(radius, segments, size = [1, 1, 1]) {
   const r = Math.min(Math.max(0, Number(radius) || 0), size[0] / 2, size[1] / 2, size[2] / 2);
   if (!r) return new BoxGeometry(1, 1, 1);
@@ -29629,6 +29646,119 @@ var LiquidCarsAtlas = class extends HTMLElement {
   set model(value) {
     this.load(value);
   }
+  get selectedId() {
+    return this.selected?.id || null;
+  }
+  _emit(type, detail = {}) {
+    this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+  }
+  _publicEntity(id) {
+    const entity = this.modelData?.entities?.find((item) => item.id === id);
+    return entity ? {
+      ...entity,
+      p: Array.isArray(entity.p) ? [...entity.p] : [0, 0, 0],
+      s: Array.isArray(entity.s) ? [...entity.s] : [1, 1, 1]
+    } : null;
+  }
+  _commitModelChange(kind, detail = {}, options = {}) {
+    const selectedId = options.preserveSelection === false ? null : this.selected?.id;
+    this.modelData = normalizeModel(this.modelData);
+    this._build({ preserveSelection: selectedId });
+    this._emit("lc-model-change", {
+      kind,
+      model: this.modelData,
+      ...detail
+    });
+    return this;
+  }
+  /** Replace selected parts of the model and rebuild the scene in place. */
+  updateModel(patch = {}, options = {}) {
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) throw new TypeError("El parche del modelo debe ser un objeto.");
+    const current = this.modelData || normalizeModel({});
+    const next = {
+      ...current,
+      ...patch,
+      palette: patch.palette ? { ...current.palette, ...patch.palette } : current.palette,
+      theme: patch.theme || patch.styles ? patch.theme || patch.styles : current.theme,
+      entities: Array.isArray(patch.entities) ? patch.entities : current.entities,
+      relations: Array.isArray(patch.relations) ? patch.relations : current.relations
+    };
+    this.modelData = normalizeModel(next);
+    this.theme = this.modelData.theme;
+    return this._commitModelChange("model-update", { patch }, options);
+  }
+  addEntity(entity, options = {}) {
+    if (!entity || typeof entity !== "object" || !entity.id) throw new TypeError("La entidad debe incluir un id.");
+    if (!this.modelData) this.modelData = normalizeModel({});
+    if (this.modelData.entities.some((item) => item.id === entity.id)) throw new Error(`Ya existe una entidad con id "${entity.id}".`);
+    if (entity.parent && !this.modelData.entities.some((item) => item.id === entity.parent)) throw new Error(`No existe el contenedor padre "${entity.parent}".`);
+    this.modelData.entities = [...this.modelData.entities, { ...entity }];
+    return this._commitModelChange("entity-add", { entity: this._publicEntity(entity.id) }, options);
+  }
+  updateEntity(id, patch = {}, options = {}) {
+    if (!this.modelData) throw new Error("No hay ning\xFAn modelo cargado.");
+    const index = this.modelData.entities.findIndex((item) => item.id === id);
+    if (index < 0) throw new Error(`No existe una entidad con id "${id}".`);
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) throw new TypeError("Los cambios de una entidad deben ser un objeto.");
+    if (patch.id && patch.id !== id) throw new Error("El id de una entidad no se puede modificar.");
+    if (patch.parent && patch.parent !== id && !this.modelData.entities.some((item) => item.id === patch.parent)) throw new Error(`No existe el contenedor padre "${patch.parent}".`);
+    this.modelData.entities = this.modelData.entities.map((item, itemIndex) => itemIndex === index ? { ...item, ...patch, id } : item);
+    return this._commitModelChange("entity-update", { id, patch, entity: this._publicEntity(id) }, options);
+  }
+  removeEntity(id, options = {}) {
+    if (!this.modelData) throw new Error("No hay ning\xFAn modelo cargado.");
+    const cascade = options.cascade !== false;
+    const removed = /* @__PURE__ */ new Set([id]);
+    if (cascade) {
+      let changed = true;
+      while (changed) {
+        changed = false;
+        for (const entity of this.modelData.entities) {
+          if (entity.parent && removed.has(entity.parent) && !removed.has(entity.id)) {
+            removed.add(entity.id);
+            changed = true;
+          }
+        }
+      }
+    }
+    if (!this.modelData.entities.some((item) => item.id === id)) throw new Error(`No existe una entidad con id "${id}".`);
+    this.modelData.entities = this.modelData.entities.filter((item) => !removed.has(item.id));
+    this.modelData.relations = this.modelData.relations.filter((relation) => !removed.has(relation.from) && !removed.has(relation.to));
+    for (const removedId of removed) this.open.delete(removedId);
+    if (this.selected && removed.has(this.selected.id)) this.selected = null;
+    return this._commitModelChange("entity-remove", { id, removed: [...removed] });
+  }
+  _relationIndex(reference) {
+    if (Number.isInteger(reference)) return reference;
+    if (typeof reference === "string") return this.modelData?.relations?.findIndex((relation) => relation.id === reference) ?? -1;
+    return -1;
+  }
+  addRelation(relation, options = {}) {
+    if (!relation || typeof relation !== "object" || !relation.from || !relation.to) throw new TypeError("La relaci\xF3n debe incluir from y to.");
+    if (!this.modelData) throw new Error("No hay ning\xFAn modelo cargado.");
+    const ids = new Set(this.modelData.entities.map((entity) => entity.id));
+    if (!ids.has(relation.from) || !ids.has(relation.to)) throw new Error("Los extremos de la relaci\xF3n deben existir en el modelo.");
+    this.modelData.relations = [...this.modelData.relations, { ...relation }];
+    return this._commitModelChange("relation-add", { relation: { ...relation } }, options);
+  }
+  updateRelation(reference, patch = {}, options = {}) {
+    if (!this.modelData) throw new Error("No hay ning\xFAn modelo cargado.");
+    const index = this._relationIndex(reference);
+    if (index < 0 || index >= this.modelData.relations.length) throw new Error("No existe la relaci\xF3n indicada.");
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) throw new TypeError("Los cambios de una relaci\xF3n deben ser un objeto.");
+    const next = { ...this.modelData.relations[index], ...patch };
+    const ids = new Set(this.modelData.entities.map((entity) => entity.id));
+    if (!ids.has(next.from) || !ids.has(next.to)) throw new Error("Los extremos de la relaci\xF3n deben existir en el modelo.");
+    this.modelData.relations = this.modelData.relations.map((item, itemIndex) => itemIndex === index ? next : item);
+    return this._commitModelChange("relation-update", { index, patch, relation: { ...next } }, options);
+  }
+  removeRelation(reference, options = {}) {
+    if (!this.modelData) throw new Error("No hay ning\xFAn modelo cargado.");
+    const index = this._relationIndex(reference);
+    if (index < 0 || index >= this.modelData.relations.length) throw new Error("No existe la relaci\xF3n indicada.");
+    const [relation] = this.modelData.relations.splice(index, 1);
+    return this._commitModelChange("relation-remove", { index, relation: { ...relation } }, options);
+  }
   get palette() {
     return this.modelData?.palette || { ...DEFAULT_PALETTE };
   }
@@ -29802,6 +29932,8 @@ var LiquidCarsAtlas = class extends HTMLElement {
     try {
       const data = typeof source === "string" ? await fetch(source).then((response) => response.json()) : source;
       this.modelData = normalizeModel(data);
+      this.open.clear();
+      this.selected = null;
       if (this._pendingPalette) {
         this.modelData.palette = { ...this.modelData.palette, ...this._pendingPalette };
         this._pendingPalette = null;
@@ -29861,6 +29993,14 @@ var LiquidCarsAtlas = class extends HTMLElement {
       this.scene.remove(node.group);
     }
     this.nodes.clear();
+    this._clearRelationGroup();
+  }
+  _clearRelationGroup() {
+    for (const object of this.relationGroup.children) {
+      object.geometry?.dispose();
+      if (Array.isArray(object.material)) object.material.forEach((material) => material.dispose());
+      else object.material?.dispose();
+    }
     this.relationGroup.clear();
   }
   _recolorNodes() {
@@ -29871,10 +30011,12 @@ var LiquidCarsAtlas = class extends HTMLElement {
       if (node.edge?.material) node.edge.material.color.set(color);
     }
   }
-  _build() {
+  _build(options = {}) {
     if (!this._ensureRenderer()) return;
+    const selectedId = options.preserveSelection || null;
     this._clearObjects();
     for (const entity of this.modelData.entities) this.nodes.set(entity.id, { ...entity });
+    this.open = new Set([...this.open].filter((id) => this.nodes.has(id)));
     for (const entity of this.modelData.entities) {
       const node = this.nodes.get(entity.id);
       node.group = new Group();
@@ -29906,6 +30048,7 @@ var LiquidCarsAtlas = class extends HTMLElement {
       node.group.add(node.label);
       this.scene.add(node.group);
     }
+    this.selected = selectedId && this.nodes.has(selectedId) ? this.nodes.get(selectedId) : null;
     this.relations = this.modelData.relations;
     this._renderPanel();
     this._rebuildRelations();
@@ -29945,7 +30088,7 @@ var LiquidCarsAtlas = class extends HTMLElement {
     return this.relations.map((relation, index) => relation.from === this.selected.id || relation.to === this.selected.id ? index : -1).filter((index) => index >= 0);
   }
   _rebuildRelations() {
-    this.relationGroup.clear();
+    this._clearRelationGroup();
     const active = this._activeRelationIndexes();
     const color = new Color(this.modelData?.palette.connection || DEFAULT_PALETTE.connection);
     for (const index of active) {
@@ -29957,14 +30100,28 @@ var LiquidCarsAtlas = class extends HTMLElement {
       const end = this._endpoint(to, from, false);
       const delta = end.clone().sub(start);
       if (delta.lengthSq() < 0.01) continue;
-      const tube = new Mesh(new TubeGeometry(new LineCurve3(start, end), 10, 0.045, 6, false), new MeshBasicMaterial({ color, transparent: true, opacity: 0.82 }));
-      this.relationGroup.add(tube);
+      const visualMode = relationVisualMode(relation);
+      const makeTube = (from2, to2, opacity = 0.82) => {
+        const tube = new Mesh(new TubeGeometry(new LineCurve3(from2, to2), 10, 0.045, 6, false), new MeshBasicMaterial({ color, transparent: true, opacity }));
+        tube.userData.relationIndex = index;
+        this.relationGroup.add(tube);
+      };
+      if (visualMode === "broken") {
+        const direction = delta.clone().normalize();
+        const midpoint = start.clone().lerp(end, 0.5);
+        const gap = Math.min(delta.length() * 0.16, 0.72);
+        makeTube(start, midpoint.clone().sub(direction.clone().multiplyScalar(gap / 2)), 0.55);
+        makeTube(midpoint.clone().add(direction.clone().multiplyScalar(gap / 2)), end, 0.55);
+        continue;
+      }
+      makeTube(start, end);
       for (let ringIndex = 0; ringIndex < 4; ringIndex++) {
         const ring = new Mesh(new TorusGeometry(0.068, 0.018, 8, 20), new MeshBasicMaterial({ color, transparent: true, opacity: 0.9 }));
         ring.userData.phase = ringIndex / 4;
+        ring.userData.direction = visualMode === "bidirectional" && ringIndex % 2 ? -1 : 1;
         ring.userData.start = start.clone();
         ring.userData.end = end.clone();
-        ring.quaternion.setFromUnitVectors(new Vector3(0, 0, 1), delta.normalize());
+        ring.quaternion.setFromUnitVectors(new Vector3(0, 0, 1), delta.clone().normalize());
         this.relationGroup.add(ring);
       }
     }
@@ -30012,7 +30169,7 @@ var LiquidCarsAtlas = class extends HTMLElement {
     });
     this._applyTheme();
   }
-  select(id) {
+  select(id, options = {}) {
     const node = this.nodes.get(id);
     if (!node) return;
     let parent = node.parent ? this.nodes.get(node.parent) : null;
@@ -30027,7 +30184,7 @@ var LiquidCarsAtlas = class extends HTMLElement {
     this._renderPanel();
     this._rebuildRelations();
     this.invalidate();
-    this.dispatchEvent(new CustomEvent("lc-select", { detail: { id, entity: node } }));
+    this._emit("lc-select", { id, entity: this._publicEntity(id), source: options.source || "api" });
   }
   setRelationMode(mode) {
     this.relationMode = ["all", "selected", "none"].includes(mode) ? mode : "selected";
@@ -30045,6 +30202,7 @@ var LiquidCarsAtlas = class extends HTMLElement {
     this.dispatchEvent(new CustomEvent("lc-relation-mode", { detail: { mode: this.relationMode } }));
   }
   reset() {
+    const previousId = this.selected?.id || null;
     this.selected = null;
     this.open.clear();
     this.relationMode = "selected";
@@ -30067,6 +30225,7 @@ var LiquidCarsAtlas = class extends HTMLElement {
     this._renderPanel();
     this._rebuildRelations();
     this.invalidate();
+    if (previousId) this._emit("lc-select", { id: null, entity: null, previousId, source: "reset" });
   }
   resize() {
     if (!this.renderer) return;
@@ -30125,7 +30284,10 @@ var LiquidCarsAtlas = class extends HTMLElement {
         top.visible = displayTransparentLabel && cameraAbove;
         const scale = displayTransparentLabel ? 0.52 : 1;
         front.scale.setScalar(scale);
-        front.position.x = displayTransparentLabel ? -labelSize.x / 2 + 0.18 + labelWidth * scale / 2 - textOffsetX * scale : 0;
+        back.scale.setScalar(scale);
+        const openLabelX = displayTransparentLabel ? -labelSize.x / 2 + 0.18 + labelWidth * scale / 2 - textOffsetX * scale : 0;
+        front.position.x = openLabelX;
+        back.position.x = displayTransparentLabel ? -openLabelX : 0;
         const shellFrontTopMargin = 0.18;
         front.position.y = displayTransparentLabel ? labelSize.y / 2 - shellFrontTopMargin - labelHeight * scale / 2 : labelSize.y / 2 - 0.09 - labelHeight / 2;
         front.position.z = displayTransparentLabel ? labelSize.z / 2 + 0.025 : labelSize.z / 2 + 0.012;
@@ -30145,16 +30307,23 @@ var LiquidCarsAtlas = class extends HTMLElement {
         back.visible = !cameraOnFront && !opened;
         top.visible = false;
         front.scale.setScalar(1);
+        back.scale.setScalar(1);
         front.position.x = 0;
+        back.position.x = 0;
         front.position.y = labelSize.y / 2 - 0.09 - labelHeight / 2;
+        back.position.y = front.position.y;
+        back.position.z = -labelSize.z / 2 - 0.012;
         front.material.color.set(15923964);
         front.material.opacity = 1;
+        back.material.color.set(15923964);
+        back.material.opacity = 1;
       }
     }
     for (const child of this.relationGroup.children) {
       if (!child.userData.start) continue;
       const phase = child.userData.phase || 0;
-      const factor = (time * 22e-5 + phase) % 1;
+      const direction = child.userData.direction || 1;
+      const factor = ((time * 22e-5 * direction + phase) % 1 + 1) % 1;
       child.position.lerpVectors(child.userData.start, child.userData.end, factor);
     }
     this.renderer.render(this.scene, this.camera);
@@ -30208,7 +30377,7 @@ var LiquidCarsAtlas = class extends HTMLElement {
       this.canvas.style.cursor = "grab";
       if (drag && !drag.moved) {
         const node = this._pick(event);
-        if (node) this.select(node.id);
+        if (node) this.select(node.id, { source: "pointer" });
       }
       this.invalidate();
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidcars/atlas",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Reusable 3D conceptual atlas Web Component for LiquidCars-style models",
   "type": "module",
   "main": "./dist/liquidcars-atlas.js",