Composition modules

Five modules compute geometry. compose.py is the core and holds five composers; the other four modules each hold one composer and are re-exported by compose.py, so the binding loader can discover them by their compose_ names. All are deterministic, make no repository calls, and read and write no files.

What they take in and produce, in common. Plain lists or trees of named items go in, with EA element ids, plus an optional spec of sizes and spacing. Plain results come out: each item with its left, top, right and bottom, usually a container reference and an index, plus the containers' own rectangles and the overall bounds. Element ids are preserved exactly (pass them as the integers they are). Invalid input is refused with a message naming the offending field by the caller's own path (for example the third band's first item); a spec with an unknown key is refused, not ignored. No composer places connectors. The caller adds and routes them.

Limitations common to the modules. No connectors. No per-item sizing in the radial grammar (use the radial tree). A grammar's depth and radius limits refuse rather than warn, because the result has no channel a warning could travel down.

The spec: sizes and spacing. Values are whole EA units, roughly pixels at 100% zoom. A pitch is leading edge to leading edge (it includes the box); a gap is the space between boxes. A pitch smaller than the item it steps over is refused. The spec holds, in groups: the origin (default 20 across, 20 down), the item size (default 140 by 60), gaps and pitches (item gaps default 20, a row wraps at 900, items align left or center), label size, band padding and gap (band gap default 30), lane padding and gap, nested-grid padding, column count and depth limit (default 3), and radial radius, maximum radius, start angle, sweep and ring depth. A setting is read by the composer for its grammar and is inert for the others (nothing reports an inert setting).

The fit conflict. When a width asked for cannot hold the content, the engine returns a conflict record instead of deciding (see step 2 of ea-diagram-composition). Under "overlap" the conflict stays on the record and nothing is widened: a choice on the record.

How the modules behave.

• Layered bands and lanes. Items are sized uniformly within a band or lane. Rounding happens once, at the end, so a trigonometric ring comes out identically on every machine.
• Radial. The arithmetic derives clearance from the actual shape of the boxes (the drawn gap, not the center distance) and bounds its own widening.
• Containers. A container's rectangle includes its label area. Items nest inside their containers by design, so the item set and the container set are tested for disjointness separately (for nested grids, siblings are compared).
• Radial tree. Why it is not the radial composer: that one gives every branch the same slice of the circle, so a hub with twelve branches, one carrying eight children, came out at 1746 by 3399 units with the crowded branch shoved outward. The radial tree allocates wedges in proportion to leaf counts, places each node inside its own interval of bearings (so branches cannot interleave), and has no depth cap of two. It keeps the same meaning of radius (clear gap, not center distance) so the drawn spokes from one parent are equal. It then lays out, tests for collisions with a margin of half the item gap, and widens every clear gap by 1.15 up to 20 rounds; failing that, it refuses naming the two colliding ids. Its spec has its own settings (origin, item size, item gap, radius, start angle, sweep, depth limit 4, branch sweep limit 120) and refuses a setting that belongs to another grammar.
• Chevron stack. The renderer's chevron shape runs from the top-left to a point 20% of the width beyond the right edge and a notch the same proportion inside the left edge, so for interlocking each stage starts exactly one width after the last and the notch depth cancels. The numbers were measured from the value-chain example that ships with Sparx EA (five stages 80 wide at pitch 80, strips 400 wide and 50 tall). Abutting rectangles touch and do not overlap, so the overlap check is satisfied with no special pleading. The pitch is an equality, not a floor, so it cannot be widened. Every stage must be the same width. Declare the output as stacks to the checker.
• Matrix. The reverse of the nested grid on three counts: every cell is one size (the fullest cell's) with one pitch across and down; an empty cell keeps its slot and is returned; headers are always drawn. Clearance is exact: on two aligned lattices a positive gap on each axis is the whole condition, so both gaps must be positive. A caller wanting a table with no cell boxes skips every cell or only the empty ones; the geometry does not change. One crowded cell sizes every cell. The container set and the item set are each mutually disjoint (cells never nest).
• Treemap. Both reference pictures that motivated it (a cost-sized technology map and a department map) were measured and found to be irregular, area-proportional tilings, not heat-map grids. The split is a recursive squarified construction. Every split goes through one helper that rounds boundaries, not sizes, so adjacent tiles share one coordinate and sizes sum to the length exactly. Tiles partition the region by construction, so overlap-freedom needs no margin. A tile below the minimum side is raised to it and the area error is reported. Weights are exact fractions, so the result does not depend on the order the caller listed them in.