@liquidcars/atlas-layout 0.1.8 → 0.1.10

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.
@@ -127,13 +134,15 @@ relations:
     from: source
     to: rules
     label: feeds
+    text: Sends normalized source data to the rules engine.
+    url: https://example.com/relations/source-to-rules
     mode: bidirectional
   - from: rules
     to: output
     mode: broken
 ```
 
-`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`.
+`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`.
 
 En un documento Markdown dividido, el bloque de relaciones contiene una lista YAML:
 
@@ -187,4 +196,4 @@ El resultado mantiene `palette`, `theme`, `entities` y `relations`, con `p` y `s
 
 El espacio de una celda y el tamaño de la geometría son conceptos distintos. Cuando el layout asigna una celda rectangular a una geometría sin `size` explícito, la figura se centra y se escala uniformemente para caber en el menor volumen compatible; no se estira por separado en `x`, `y` y `z`. Por eso una esfera conserva `s[0] === s[1] === s[2]`, aunque su celda sea rectangular. Un `size` explícito sigue teniendo prioridad y permite al autor solicitar una proporción concreta.
 
-`row`, `grid`/`masonry` y `volume` producen posiciones deterministas. Las constraints de tamaño y alineación, el empaquetado compacto, los grupos virtuales y la distribución `justify` forman parte del contrato estable de autoría. El algoritmo `graph` sigue reservado: por ahora emite `GRAPH_LAYOUT_FALLBACK` y usa `grid`. La proyección y el enrutado avanzado de relaciones entre contenedores permanecen como líneas de desarrollo posteriores.
+`row`, `grid`/`masonry` y `volume` producen posiciones deterministas. `variant: masonry` desplaza las filas alternas media celda sin exigir una sección `stagger`; `stagger.offset` queda disponible como override explícito. Para conservar legibilidad frontal se recomienda `plane: xy`, y para una composición lateral, `plane: yz`. Las constraints de tamaño y alineación, el empaquetado compacto, los grupos virtuales y la distribución `justify` forman parte del contrato estable de autoría. El algoritmo `graph` sigue reservado: por ahora emite `GRAPH_LAYOUT_FALLBACK` y usa `grid`. La proyección y el enrutado avanzado de relaciones entre contenedores permanecen como líneas de desarrollo posteriores.

package/package.json

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

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

@@ -47,7 +47,7 @@ subject to sizeMode and diagnostics.
 
 Required: id.
 
-Common fields: name, sub, text, type, parent, children, geometry, geometryOptions,
+Common fields: name, sub, text, url, type, parent, children, geometry, geometryOptions,
 geometryPalette, style, layout, weight, span, size, sizeMode, p, s, c and radius.
 
 An entity with children is a container and must explicitly declare `type: container`.
@@ -73,7 +73,10 @@ fit permits assisted layout to use the geometry's canonical size.
 
 layout.algorithm accepts row, grid, volume or graph. direction accepts x, y or z.
 Grid layouts also accept variant uniform or masonry, optional columns and rows, and
-a plane of xz (the default), xy or yz. Volume layouts additionally accept layers.
+a plane of xz (the default), xy or yz. Masonry offsets alternate rows by half a cell
+unless `stagger.offset` explicitly overrides that distance. Use plane xy for layouts
+intended to remain legible from the natural frontal camera, or yz for a lateral view.
+Volume layouts additionally accept layers.
 gap and padding are absolute numbers. justify accepts start, center, end,
 space-between, space-around or space-evenly. These modes become distinct when a
 row receives an explicit or constrained size. Distributed modes treat gap as the
@@ -145,13 +148,21 @@ constraints:
 
 Relations require from and to entity ids. mode is directed, bidirectional or broken.
 The aliases visual, render, type and direction are accepted for compatibility.
-Optional fields include id, label, fromAnchor, toAnchor, priority and layout.
+Optional fields include id, label, text, url, fromAnchor, toAnchor, priority and layout.
+`label` is the compact caption associated with the connection; `text` is its longer
+description and `url` links to external documentation when the relation is selected
+in the information panel.
 
 ## 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,
-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

@@ -242,6 +242,8 @@ function normalizeRelations(input, validIds, diagnostics) {
       index
     };
     if (relation.id != null) normalized.id = String(relation.id);
+    if (relation.text != null) normalized.text = String(relation.text);
+    if (relation.url != null) normalized.url = String(relation.url);
     if (relation.fromAnchor != null || relation.from_anchor != null) normalized.fromAnchor = String(relation.fromAnchor ?? relation.from_anchor);
     if (relation.toAnchor != null || relation.to_anchor != null) normalized.toAnchor = String(relation.toAnchor ?? relation.to_anchor);
     return [normalized];
@@ -890,7 +892,12 @@ function packedGridLayout(items, spec, diagnostics, dimension = 2) {
     for (const item of placements) {
       const columnSize = item.span[0] * columnCell + (item.span[0] - 1) * gap;
       const rowSize = item.span[1] * rowCell + (item.span[1] - 1) * gap;
-      const offset = spec.variant === "masonry" && item.cell[1] % 2 === 1 ? (spec.stagger?.offset === "half-cell" ? (columnCell + gap) / 2 : scalar(spec.stagger?.offset, 0)) : 0;
+      const staggerOffset = spec.stagger?.offset;
+      const offset = spec.variant === "masonry" && item.cell[1] % 2 === 1
+        ? (staggerOffset == null || staggerOffset === "half-cell"
+            ? (columnCell + gap) / 2
+            : scalar(staggerOffset, 0))
+        : 0;
       const slotSize = [0, 0, 0];
       slotSize[columnAxis] = columnSize;
       slotSize[rowAxis] = rowSize;
@@ -964,6 +971,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

@@ -30,6 +30,7 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         name: field("Visible title.", null, { type: "string" }),
         sub: field("Visible subtitle.", null, { type: "string" }),
         text: field("Description shown by the inspector.", null, { type: "string" }),
+        url: field("External documentation opened from the inspector.", null, { type: "url" }),
         type: field("Structural role. Use container when declaring children; omit it for a leaf item.", ["container"]),
         parent: field("Parent entity id.", null, { type: "string", authoring: "absolute" }),
         children: field("Nested entities.", null, { context: "entity", sequence: true }),
@@ -56,6 +57,8 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         from: field("Source entity id.", null, { type: "string", required: true }),
         to: field("Target entity id.", null, { type: "string", required: true }),
         label: field("Text shown on the relation.", null, { type: "string" }),
+        text: field("Description shown by the inspector.", null, { type: "string" }),
+        url: field("External documentation opened from the inspector.", null, { type: "url" }),
         mode: field("Canonical visual relation mode.", ["directed", "bidirectional", "broken"]),
         visual: field("Historical alias for relation mode.", ["directed", "bidirectional", "broken"]),
         fromAnchor: field("Named source anchor.", null, { type: "string" }),
@@ -69,7 +72,7 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
       properties: freeze({
         algorithm: field("Spatial strategy.", ["row", "grid", "volume", "graph"]),
         direction: field("Primary semantic axis.", ["x", "y", "z"]),
-        variant: field("Regular or staggered grid cells.", ["uniform", "masonry"]),
+        variant: field("Regular cells or masonry rows staggered by half a cell by default.", ["uniform", "masonry"]),
         plane: field("Axes used by a two-dimensional grid.", ["xz", "xy", "yz"]),
         packing: field("Preserve initial slots or compact free space after constraints.", ["preserve", "compact"]),
         groups: field("Invisible sibling groups used only during layout.", null, { context: "layoutGroup", sequence: true }),
@@ -79,7 +82,7 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         gap: field("Spacing between children.", null, { type: "number" }),
         padding: field("Spacing to the container boundary.", null, { type: "number" }),
         justify: field("Row alignment or distribution within an assigned size.", ["start", "center", "end", "space-between", "space-around", "space-evenly"]),
-        stagger: field("Optional masonry offset.", null, { context: "stagger" }),
+        stagger: field("Optional override for the masonry row offset.", null, { context: "stagger" }),
         constraints: field("Equal-size and edge-alignment rules for this layout's siblings.", null, { context: "constraint", sequence: true })
       })
     }),
@@ -137,9 +140,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({
@@ -159,7 +172,7 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
     stagger: freeze({
       label: "Stagger",
       properties: freeze({
-        offset: field("Masonry row offset.", ["half-cell"], { type: "string" })
+        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" }) }) }),
@@ -186,6 +199,7 @@ export function atlasLayoutContextForPath(path = []) {
     ["palette", "palette"],
     ["theme", "theme"],
     ["render", "render"],
+    ["focus", "focus"],
     ["camera", "camera"],
     ["span", "span"],
     ["stagger", "stagger"],