@liquidcars/atlas-layout 0.1.7 → 0.1.9

package/README.md

@@ -49,6 +49,28 @@ como alias de compatibilidad. Un contenedor puede no tener geometría o usar una
 primitiva `geo.*`; las geometrías personalizadas de los packs, como `infra.cloud`,
 sólo se permiten en entidades hoja.
 
+La presentación puede conservar una vista inicial sin introducir datos de
+cámara en el algoritmo de layout:
+
+```yaml
+render:
+  camera:
+    position: [12.4, 7.2, 18.6]
+    target: [0, 1.5, 0]
+    zoom: 1.35
+```
+
+## Filtered projections
+
+`compileAtlasProjection(source, visibleIds, options)` compiles a temporary model
+containing only the requested entities and their required ancestors. Relations,
+constraints and virtual layout groups are pruned consistently. The source object is
+never mutated, making the helper suitable for selection-driven `render.focus` reflow.
+
+Las coordenadas son coordenadas del modelo. `zoom` es un multiplicador de
+encuadre independiente del tamaño del viewport y se conserva al compilar YAML
+o Markdown.
+
 Para compilar una fuente YAML durante el build:
 
 ```js

package/package.json

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

package/spec/ATLAS-LAYOUT-SPEC-v1.md

@@ -150,8 +150,16 @@ Optional fields include id, label, fromAnchor, toAnchor, priority and layout.
 ## Rendering
 
 palette maps tokens to CSS colours. style.color or c can reference a token or direct
-CSS colour. render can additionally set relationMode, selectionMode, toolbar and
-shellLabels. theme contains background, lighting and ui settings.
+CSS colour. render can additionally set relationMode, selectionMode, toolbar,
+shellLabels (the text-label contrast outline), focus and camera. `render.focus`
+accepts `mode: all|connected`, `effect: dim|hide`, `layout: preserve|reflow`
+and an optional dim `opacity`. Connected focus retains the selection, its directly
+related entities and the ancestor containers required to preserve context. Preserve
+keeps spatial memory; reflow compiles a temporary projection and never mutates the
+source model. An initial camera snapshot contains model-space
+position and target vectors plus a positive, dimensionless zoom value. Position
+and target determine the viewing direction; zoom preserves the intended framing
+across viewport sizes. theme contains background, lighting and ui settings.
 
 ## Markdown blocks
 

package/src/index.js

@@ -964,6 +964,81 @@ function normalizeRoot(input) {
   return input || {};
 }
 
+function projectedAtlasSource(input, visibleIds) {
+  const source = structuredClone(normalizeRoot(input));
+  const requested = new Set(Array.from(visibleIds || []).filter(Boolean));
+  const records = new Map();
+
+  function collect(items, nestedParent = null) {
+    for (const entity of Array.isArray(items) ? items : []) {
+      if (!entity?.id) continue;
+      const parent = nestedParent ?? entity.parent ?? null;
+      records.set(entity.id, { entity, parent });
+      collect(entity.children, entity.id);
+    }
+  }
+  collect(source.entities);
+  for (const id of [...requested]) {
+    let parent = records.get(id)?.parent || null;
+    while (parent && !requested.has(parent)) {
+      requested.add(parent);
+      parent = records.get(parent)?.parent || null;
+    }
+  }
+
+  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);
+      return [copy];
+    });
+  }
+  source.entities = filterEntities(source.entities);
+  source.relations = (source.relations || []).filter(relation => requested.has(relation.from) && requested.has(relation.to));
+
+  const childrenByParent = new Map();
+  function index(items, nestedParent = null) {
+    for (const entity of items || []) {
+      const parent = nestedParent ?? entity.parent ?? null;
+      if (!childrenByParent.has(parent)) childrenByParent.set(parent, []);
+      childrenByParent.get(parent).push(entity.id);
+      index(entity.children, entity.id);
+    }
+  }
+  index(source.entities);
+
+  function pruneOwner(owner, ownerId = null) {
+    const siblingIds = new Set(childrenByParent.get(ownerId) || []);
+    const layout = owner.layout ? { ...owner.layout } : null;
+    if (layout?.groups) {
+      layout.groups = layout.groups.flatMap(group => {
+        const members = (group.members || []).filter(id => siblingIds.has(id));
+        return members.length ? [{ ...group, members }] : [];
+      });
+      if (!layout.groups.length) delete layout.groups;
+      owner.layout = layout;
+    }
+    const candidates = new Set([...siblingIds, ...(layout?.groups || []).map(group => group.id)]);
+    if (Array.isArray(owner.constraints)) {
+      owner.constraints = owner.constraints.flatMap(constraint => {
+        const key = Array.isArray(constraint.align) ? "align" : Array.isArray(constraint.equal) ? "equal" : null;
+        if (!key) return [constraint];
+        const ids = constraint[key].filter(id => candidates.has(id));
+        return ids.length >= 2 ? [{ ...constraint, [key]: ids }] : [];
+      });
+      if (!owner.constraints.length) delete owner.constraints;
+    }
+    for (const entity of ownerId === null ? source.entities : owner.children || []) pruneOwner(entity, entity.id);
+  }
+  pruneOwner(source, null);
+  return source;
+}
+
+export function compileAtlasProjection(input, visibleIds, options = {}) {
+  return compileAtlasModel(projectedAtlasSource(input, visibleIds), options);
+}
+
 export function compileAtlasModel(input, options = {}) {
   const diagnostics = [];
   const source = normalizeRoot(input);
@@ -1050,6 +1125,7 @@ export function compileAtlasModel(input, options = {}) {
     relations,
     layout: source.layout || undefined,
     constraints: source.constraints || undefined,
+    render: source.render || undefined,
     diagnostics
   };
   if (options.throwOnFatal && diagnostics.some(item => item.level === "fatal")) throw new Error(diagnostics.filter(item => item.level === "fatal").map(item => item.message).join("\n"));

package/src/spec.js

@@ -136,7 +136,26 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         relationMode: field("Visible relation set.", ["all", "selected", "none"]),
         selectionMode: field("Selection ownership.", ["internal", "event"]),
         toolbar: field("Built-in toolbar visibility.", [true, false]),
-        shellLabels: field("Container label visibility.", [true, false])
+        shellLabels: field("Text-label contrast outline.", [true, false]),
+        focus: field("Selection-driven visual filtering.", null, { context: "focus" }),
+        camera: field("Initial camera snapshot in model-space coordinates.", null, { context: "camera" })
+      })
+    }),
+    focus: freeze({
+      label: "Visual focus",
+      properties: freeze({
+        mode: field("Entity set retained by the visual filter.", ["all", "connected"]),
+        effect: field("Treatment of entities outside the focused set.", ["dim", "hide"]),
+        layout: field("Keep spatial memory or reflow the focused projection.", ["preserve", "reflow"]),
+        opacity: field("Opacity applied to dimmed entities.", null, { type: "number" })
+      })
+    }),
+    camera: freeze({
+      label: "Initial camera",
+      properties: freeze({
+        position: field("Camera position in model-space coordinates.", null, { type: "vector", required: true }),
+        target: field("Model-space point observed by the camera.", null, { type: "vector", required: true }),
+        zoom: field("Dimensionless framing multiplier.", null, { type: "number", required: true })
       })
     }),
     span: freeze({
@@ -177,6 +196,8 @@ export function atlasLayoutContextForPath(path = []) {
     ["palette", "palette"],
     ["theme", "theme"],
     ["render", "render"],
+    ["focus", "focus"],
+    ["camera", "camera"],
     ["span", "span"],
     ["stagger", "stagger"],
     ["label", "label"],