@liquidcars/atlas-layout 0.1.9 → 0.1.10

package/README.md

@@ -134,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:
 
@@ -194,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.9",
+  "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,7 +148,10 @@ 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
 

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;

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 })
       })
     }),
@@ -169,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" }) }) }),