@liquidcars/atlas-layout 0.1.8 → 0.1.9

package/README.md

@@ -60,6 +60,13 @@ render:
     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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidcars/atlas-layout",
-  "version": "0.1.8",
+  "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

@@ -151,7 +151,12 @@ Optional fields include id, label, fromAnchor, toAnchor, priority and layout.
 
 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,
-shellLabels (the text-label contrast outline) and camera. An initial camera snapshot contains model-space
+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.

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);

package/src/spec.js

@@ -137,9 +137,19 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         selectionMode: field("Selection ownership.", ["internal", "event"]),
         toolbar: field("Built-in toolbar 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({
@@ -186,6 +196,7 @@ export function atlasLayoutContextForPath(path = []) {
     ["palette", "palette"],
     ["theme", "theme"],
     ["render", "render"],
+    ["focus", "focus"],
     ["camera", "camera"],
     ["span", "span"],
     ["stagger", "stagger"],