@liquidcars/atlas-layout 0.1.3 → 0.1.7

package/README.md

@@ -24,6 +24,31 @@ Cada entrada del catálogo puede declarar `id`, `aliases` y `canonicalSize`.
 Una geometría externa desconocida conserva el tamaño de fallback de una caja,
 de modo que la compilación sigue siendo recuperable si falta un pack.
 
+Los grids bidimensionales aceptan `plane: "xz" | "xy" | "yz"`. El plano
+predeterminado sigue siendo `xz`; `xy` resulta útil para galerías concebidas
+para una vista frontal.
+
+Los layouts `row` aceptan `packing: "preserve" | "compact"`. El modo
+`compact` recompone las bandas creadas por constraints de alineación sobre el
+eje principal y elimina los huecos que dejan las posiciones iniciales.
+
+`layout.groups` permite declarar composiciones invisibles de hermanos inmediatos.
+Cada grupo tiene `id`, `members` y un `layout` interno. Las constraints del
+nivel padre pueden referenciar el id del grupo; tras calcular posiciones, el
+compilador elimina el grupo y emite únicamente las entidades reales.
+
+Un layout `row` puede distribuir el espacio asignado por un tamaño explícito
+o una constraint de igualdad mediante `justify: "start" | "center" | "end" |
+"space-between" | "space-around" | "space-evenly"`. `padding` define los límites
+interiores y `gap` actúa como separación mínima. Los grupos virtuales se
+recalculan después de recibir su tamaño definitivo.
+
+Las entidades con `children` deben declarar `type: container`. Las hojas pueden
+omitir `type` y se normalizan como items. `type: shell` se acepta únicamente
+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.
+
 Para compilar una fuente YAML durante el build:
 
 ```js
@@ -147,4 +172,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.
 
-Esta es una primera implementación del motor. `row`, `grid`/`masonry` y `volume` ya producen posiciones deterministas. El algoritmo `graph` está reservado en el contrato y, por ahora, emite `GRAPH_LAYOUT_FALLBACK` y usa `grid`; las restricciones espaciales y la proyección de relaciones entre contenedores se incorporarán en iteraciones posteriores.
+`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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidcars/atlas-layout",
-  "version": "0.1.3",
+  "version": "0.1.7",
   "description": "Declarative layout compiler for LiquidCars Atlas models",
   "type": "module",
   "main": "./src/index.js",
@@ -21,14 +21,31 @@
     "./vite": {
       "import": "./src/vite.js",
       "default": "./src/vite.js"
+    },
+    "./spec": {
+      "import": "./src/spec.js",
+      "default": "./src/spec.js"
     }
   },
   "scripts": {
-    "test": "node --test test/index.test.mjs"
+    "test": "node --test test/index.test.mjs",
+    "prepack": "npm test"
   },
-  "keywords": ["liquidcars", "atlas", "layout", "3d", "graph", "web-component"],
+  "keywords": [
+    "liquidcars",
+    "atlas",
+    "layout",
+    "3d",
+    "graph",
+    "web-component"
+  ],
   "license": "MIT",
   "dependencies": {
     "yaml": "^2.8.1"
-  }
+  },
+  "files": [
+    "README.md",
+    "src",
+    "spec"
+  ]
 }

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

@@ -0,0 +1,165 @@
+# ATLAS-LAYOUT-SPEC-v1
+
+This document defines the semantic YAML contract consumed by @liquidcars/atlas-layout.
+The executable projection of this contract is packages/atlas-layout/src/spec.js.
+
+## Root model
+
+A model may contain version, palette, theme, render, layout, entities and relations.
+Entities may be declared at the root or nested under children. The compiler normalizes
+nested entities to a flat list with parent references.
+
+## Model coordinate system
+
+Atlas model space is independent from the camera and from the host application's view.
+The coordinate convention is fixed:
+
+- x: left (-) to right (+)
+- y: bottom (-) to top (+)
+- z: back (-) to front (+)
+
+Positions, sizes, layout directions and future alignment rules are interpreted in this
+model space. Camera rotation, zoom, pan and projection never change the meaning of a
+model coordinate. The default front view places the camera on the positive z side,
+looking toward the origin.
+
+A container's local origin is the reference point for its children. The compiler resolves
+nested positions into model-space output while preserving the authored hierarchy. The
+authoring aliases left, right, bottom, top, back and front may be used for boundary
+terms; they correspond respectively to minX, maxX, minY, maxY, minZ and maxZ.
+
+## Layout units and intrinsic sizing
+
+All dimensions are expressed in Atlas world units: geometry dimensions, positions, layout
+gap, padding and explicit size values use the same unit. There is no universal 1 x 1 x 1
+item size. When a leaf has no explicit size, assisted layout uses the selected geometry's
+canonical size; an aspect style changes proportion, not the geometry's semantic identity.
+
+Containers are sized from their laid-out contents by default: child bounds plus gap and
+padding determine the required extent. padding: 1 reserves one world unit on every
+content-to-boundary side, so it contributes approximately two units to each occupied
+dimension. gap: 1.2 reserves 1.2 world units between adjacent siblings along the
+layout axis. Authored size is the exception: it is an explicit dimension constraint,
+subject to sizeMode and diagnostics.
+
+
+## Entity fields
+
+Required: id.
+
+Common fields: name, sub, text, 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`.
+A leaf entity may omit `type`, in which case it is normalized as an item. The
+legacy value `type: shell` remains accepted as a compatibility alias for
+`container`, but is not emitted by the compiler or suggested by the editor.
+
+Containers may omit geometry or use a built-in primitive such as `geo.box`.
+Custom geometry-pack geometries such as `infra.cloud` and `media.image-box` are
+leaf geometries and cannot be used on containers. The compiler reports these violations
+as fatal diagnostics instead of silently rendering a fallback box.
+
+`children` is the nested authoring form. In a flat model, an entity referenced by
+other entities through `parent` is also a container and follows the same rule.
+
+geometry is resolved against built-in primitives and registered geometry packs.
+geometryOptions and geometryPalette are namespaced by the selected geometry definition.
+size is an explicit dimension constraint. p and s are calculated layout output and are
+normally omitted from authored Markdown. sizeMode fixed preserves explicit dimensions;
+fit permits assisted layout to use the geometry's canonical size.
+
+## Assisted layout
+
+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.
+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
+minimum separation; padding defines the inner boundaries.
+For row layouts, packing accepts preserve (the default) or compact. Compact packing
+groups siblings connected by an alignment on the row axis, removes slots vacated by
+those alignments, and reapplies gap between the resulting bands.
+
+A layout may declare invisible groups under `layout.groups`. Each group has an `id`,
+a list of immediate sibling `members`, and its own nested `layout`. The compiler
+lays out the members as a temporary composite, permits sibling constraints to reference
+the group id, then removes the group and emits only the real entities. Members must be
+immediate siblings and may belong to only one group at that level. Group ids share the
+layout scope with sibling ids. Groups have no geometry, style, selection state or
+relation endpoints.
+
+```yaml
+layout:
+  algorithm: row
+  direction: y
+  packing: compact
+  groups:
+    - id: support-layer
+      members: [infrastructure, media]
+      layout:
+        algorithm: row
+        direction: x
+        justify: space-between
+        gap: 2
+constraints:
+  - align: [top, support-layer, bottom]
+    edges: [left, front]
+```
+
+An entity weight influences its relative allocation. span can explicitly occupy
+columns, rows and layers. A semantic style.aspect may be compact, wide, tall, deep or flat.
+
+## Sibling size and alignment constraints
+
+A root model or container may declare `constraints` for its immediate children. Constraint
+references must resolve to siblings in that group; references across parents produce a
+diagnostic and are not applied. Constraints may alternatively be nested under the
+corresponding `layout` object, but sibling-level `constraints` is the canonical form.
+
+An equal-size rule lists entity ids under `equal`. `dimensions` accepts one or more of
+`width`, `height` and `depth`; the compiler uses the largest intrinsic extent in the
+group for each requested dimension. The singular `dimension` form is accepted, and
+`edge: width|height|depth` is a compact alias.
+
+An alignment rule lists entity ids under `align`. `edge` or `edges` accepts
+`left`, `centerX`, `right`, `bottom`, `centerY`, `top`, `back`,
+`centerZ` and `front`. These names always use model coordinates, never camera
+coordinates. Alignment uses the first listed sibling as the reference.
+
+`strength` accepts `preferred` (the default) or `required`. Invalid preferred rules
+produce warnings; invalid required rules produce errors.
+
+```yaml
+constraints:
+  - equal: [layer-top, layer-middle, layer-bottom]
+    dimensions: [width, height, depth]
+    strength: preferred
+  - align: [layer-top, layer-middle, layer-bottom]
+    edges: [left, front]
+    strength: preferred
+```
+
+## Relations
+
+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.
+
+## 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.
+
+## Markdown blocks
+
+Atlas Markdown accepts a full atlas or atlas overview fenced block, and split
+atlas-model, atlas-layout, atlas-render and atlas-relations blocks. Named blocks
+use the block name as the model identifier. A document may contain more than one model.
+
+## Compatibility
+
+Unknown fields remain available to geometry packs and host applications, but the
+editor only suggests fields defined by this version of the contract.