@liquidcars/atlas-layout 0.1.15 → 0.1.17

package/README.md

@@ -173,6 +173,14 @@ relations:
 
 `label` es el título corto visible junto a la conexión, `text` permite documentar su significado y `url` enlaza documentación externa desde el panel de información. `mode` es la forma recomendada y el compilador siempre la emite normalizada. Para facilitar la migración se aceptan también `visual`, `render`, `type`, `direction`, `bidirectional: true` y `broken: true`, además de los alias `two-way`, `both` e `interrupted`. La forma abreviada puede incluir el modo como cuarto valor: `[from, to, label, mode]`. Un modo desconocido conserva la relación como `directed` y añade el diagnóstico `UNKNOWN_RELATION_MODE`.
 
+Las relaciones también pueden declararse en `relations` dentro de cualquier entidad
+`type: container`. El compilador aplana las relaciones raíz y anidadas en un único
+array de runtime. La exportación visual usa una forma canónica: cada relación se
+guarda en el contenedor común más profundo de sus dos extremos; si no existe un
+contenedor común, se guarda en `relations` en la raíz. Así, compilar, editar y
+volver a exportar no depende de dónde se declaró originalmente la conexión.
+
+
 En un documento Markdown dividido, el bloque de relaciones contiene una lista YAML:
 
 ````markdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidcars/atlas-layout",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Declarative layout compiler for LiquidCars Atlas models",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -127,6 +127,7 @@ function normalizeEntityTypes(flat, geometryCatalog, diagnostics) {
     const declared = typeof declaredValue === "string" ? declaredValue.trim().toLowerCase() : "";
     const childIds = flat.childrenById.get(entity.id) || [];
     const hasChildren = childIds.length > 0 || (Array.isArray(source.children) && source.children.length > 0);
+    const hasRelations = Array.isArray(source.relations) && source.relations.length > 0;
 
     if (declaredValue != null && typeof declaredValue !== "string") {
       diagnostic(diagnostics, "fatal", "UNKNOWN_ENTITY_TYPE",
@@ -140,6 +141,10 @@ function normalizeEntityTypes(flat, geometryCatalog, diagnostics) {
       diagnostic(diagnostics, "fatal", "CONTAINER_TYPE_REQUIRED_FOR_CHILDREN",
         "Entity '" + entity.id + "' declares children and must set type: container.",
         { entityId: entity.id });
+    } else if (hasRelations && !["container", "shell"].includes(declared)) {
+      diagnostic(diagnostics, "fatal", "CONTAINER_TYPE_REQUIRED_FOR_RELATIONS",
+        "Entity '" + entity.id + "' declares relations and must set type: container.",
+        { entityId: entity.id });
     }
 
     if (declared && !["item", "container", "shell"].includes(declared)) {
@@ -148,7 +153,7 @@ function normalizeEntityTypes(flat, geometryCatalog, diagnostics) {
         { entityId: entity.id, type: source.type });
     }
 
-    const type = hasChildren || declared === "container" || declared === "shell" ? "container" : "item";
+    const type = hasChildren || hasRelations || declared === "container" || declared === "shell" ? "container" : "item";
     entity.type = type;
 
     if (Object.hasOwn(source, "open") && typeof source.open !== "boolean") {
@@ -175,6 +180,7 @@ function flattenEntities(input, diagnostics) {
   const entities = [];
   const childrenById = new Map();
   const sourceById = new Map();
+  const relations = [];
   const seen = new Set();
 
   function visit(items, parent = null) {
@@ -193,6 +199,8 @@ function flattenEntities(input, diagnostics) {
       const entity = { ...raw };
       delete entity.children;
       delete entity.layout;
+      delete entity.relations;
+      if (Array.isArray(raw.relations)) relations.push(...raw.relations);
       entity.__atlasExplicitSize = Array.isArray(raw.size) && raw.size.length === 3;
       entity.parent = parent ?? raw.parent ?? null;
       entity.type = raw.type;
@@ -216,7 +224,7 @@ function flattenEntities(input, diagnostics) {
       if (!siblings.includes(entity.id)) siblings.push(entity.id);
     }
   }
-  return { entities, childrenById, sourceById };
+  return { entities, childrenById, sourceById, relations };
 }
 
 function normalizeRelationMode(relation, diagnostics, index, shorthandMode) {
@@ -1193,16 +1201,25 @@ function projectedAtlasSource(input, visibleIds) {
     }
   }
 
+  const relationIsVisible = relation => {
+    const from = Array.isArray(relation) ? relation[0] : relation?.from;
+    const to = Array.isArray(relation) ? relation[1] : relation?.to;
+    return requested.has(from) && requested.has(to);
+  };
   function filterEntities(items) {
     return (Array.isArray(items) ? items : []).flatMap(entity => {
       if (!entity?.id || !requested.has(entity.id)) return [];
       const copy = { ...entity };
       if (Array.isArray(entity.children)) copy.children = filterEntities(entity.children);
+      if (Array.isArray(entity.relations)) {
+        copy.relations = entity.relations.filter(relationIsVisible);
+        if (!copy.relations.length) delete copy.relations;
+      }
       return [copy];
     });
   }
   source.entities = filterEntities(source.entities);
-  source.relations = (source.relations || []).filter(relation => requested.has(relation.from) && requested.has(relation.to));
+  source.relations = (source.relations || []).filter(relationIsVisible);
 
   const childrenByParent = new Map();
   function index(items, nestedParent = null) {
@@ -1849,7 +1866,7 @@ function compileResolvedAtlasModel(input, options = {}) {
   normalizeEntityTypes(flat, options.geometryCatalog || [], diagnostics);
   if (!flat.entities.length) diagnostic(diagnostics, "fatal", "NO_VALID_ENTITIES", "The model does not contain any valid entities.");
   const validIds = new Set(flat.entities.map(entity => entity.id));
-  const relations = normalizeRelations(source.relations, validIds, diagnostics);
+  const relations = normalizeRelations([...(source.relations || []), ...flat.relations], validIds, diagnostics);
   const modelStyle = mergeStyle(DEFAULT_MODEL_STYLE, source.style || {});
   if (!Object.keys(modelStyle.edges || {}).length) delete modelStyle.edges;
   resolveStyles(flat.entities, flat.sourceById, flat.childrenById, palette, diagnostics, modelStyle);

package/src/spec.js

@@ -36,6 +36,7 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         open: field("Initial expansion state for a container; omitted means closed.", [true, false]),
         parent: field("Parent entity id.", null, { type: "string", authoring: "absolute" }),
         children: field("Nested entities.", null, { context: "entity", sequence: true }),
+        relations: field("Connections canonically owned by this container.", null, { context: "relation", sequence: true }),
         geometry: field("Geometry id supplied by Atlas or a registered pack.", null, { valueSource: "geometryCatalog" }),
         geometryOptions: field("Typed parameters supplied by the selected geometry.", null, { context: "geometryOptions" }),
         geometryPalette: field("Local palette overrides supplied by the selected geometry.", null, { context: "geometryPalette" }),
@@ -184,7 +185,14 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         offset: field("Masonry row offset; defaults to half-cell.", ["half-cell"], { type: "string" })
       })
     }),
-    label: freeze({ label: "Label appearance", properties: freeze({ color: field("Label colour.", null, { valueSource: "palette" }), opacity: field("Label opacity.", null, { type: "number" }) }) }),
+    label: freeze({
+      label: "Label appearance",
+      properties: freeze({
+        color: field("Label colour.", null, { valueSource: "palette" }),
+        opacity: field("Label opacity.", null, { type: "number" }),
+        anchor: field("Label placement relative to the geometry.", ["auto", "top", "bottom", "left", "right"])
+      })
+    }),
     edges: freeze({ label: "Edge appearance", properties: freeze({ color: field("Edge colour.", null, { valueSource: "palette" }), opacity: field("Edge opacity.", null, { type: "number" }) }) }),
     background: freeze({ label: "Background", properties: freeze({ color: field("Background colour.", null, { type: "color" }), glow: field("Background glow colour.", null, { type: "color" }) }) }),
     lighting: freeze({ label: "Lighting", properties: freeze({ ambient: field("Ambient intensity.", null, { type: "number" }), directional: field("Directional intensity.", null, { type: "number" }) }) }),