Bounded, allocation-free box-model layout for e-reader chrome. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_ui.h"

Include dependency graph for ra8_box.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_box_t
	One node in a box tree (caller-owned). More...
struct	ra8_box_tree_t
	Append-only builder over caller-owned node storage. More...

Enumerations
enum	ra8_box_const_t : int32_t { k_ra8_box_none = -1 , k_ra8_box_no_colour = (int32_t)0 }
	Box-tree sentinels and the "no colour" marker. More...
enum	ra8_box_kind_t : uint8_t { k_ra8_box_stack_v = 0U , k_ra8_box_stack_h = 1U , k_ra8_box_grid = 2U , k_ra8_box_leaf = 3U }
	Box layout kind. More...

Functions
ra8_err_t	ra8_box_tree_init (ra8_box_tree_t tree, ra8_box_t storage, uint16_t cap)
	Bind a tree builder to caller-owned node storage.
int16_t	ra8_box_add (ra8_box_tree_t tree, int16_t parent, const ra8_box_t node)
	Append a node and link it as a child of `parent`.
ra8_err_t	ra8_box_layout (ra8_box_tree_t tree, int16_t root, const ra8_ui_rect_t frame)
	Lay out the tree, filling every node's rect.

Detailed Description

Bounded, allocation-free box-model layout for e-reader chrome.

ra8_box is the minimal CSS-style box model the e-reader chrome needs (issue #80, #76). The full document engine (ra8_reflow) reflows arbitrary book XHTML; the chrome (library grid, reading bars, menus) is instead a small fixed box tree laid out once per screen. This is the only "web-like" layout compatible with the no-malloc / bounded / MC/DC bar: the screen is a caller-owned array of nodes, the layout is a single forward pass (no recursion, P10 Rule 1), and the engine produces only positioned rectangles – it never touches a font or a framebuffer, so the same layout runs on the host test harness and on the RA8D2, and the renderer (ra8_gfx) and hit-tester (ra8_ui) are layered on top.

Supported box kinds: a vertical stack (column), a horizontal stack (row), a fixed-column grid, and a leaf. Children size either to a fixed extent along the parent's main axis or to a flex weight that splits the leftover space. Padding insets a container's content; gap separates its children. Fill / border colours are carried on each node for the renderer to consume; the engine itself only computes geometry.

[Ring 5 / UI] {World: NS}

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_box.h.

Enumeration Type Documentation

◆ ra8_box_const_t

enum ra8_box_const_t : int32_t

Box-tree sentinels and the "no colour" marker.

Enumerator
k_ra8_box_none	No child / no sibling link.
k_ra8_box_no_colour	Carried fill/border: absent.

Definition at line 56 of file ra8_box.h.

◆ ra8_box_kind_t

enum ra8_box_kind_t : uint8_t

Box layout kind.

Enumerator
k_ra8_box_stack_v	Vertical stack: children stack top->bottom.
k_ra8_box_stack_h	Horizontal stack: children left->right.
k_ra8_box_grid	Fixed-column grid, row-major.
k_ra8_box_leaf	Terminal box (no children laid out).

Definition at line 65 of file ra8_box.h.

Function Documentation

◆ ra8_box_add()

int16_t ra8_box_add	(	ra8_box_tree_t *	tree,
		int16_t	parent,
		const ra8_box_t *	node )

nodiscard

Append a node and link it as a child of parent.

Copies node into storage, resets its tree links, and appends it to parent's child chain (or makes it a root when parent == k_ra8_box_none). Returns the new node's index for use as a parent in later calls.

Parameters

[in,out]	tree	Initialised tree.
[in]	parent	Parent index, or k_ra8_box_none for a root.
[in]	node	Node template (kind / sizing / colours).

Returns: New node index in [0, cap), or k_ra8_box_none on error.

Precondition: tree and node non-NULL; tree initialised.; parent is k_ra8_box_none or a valid earlier index.

Postcondition: On success tree->count grew by one and the node is linked.; On overflow / bad parent the tree is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 297 of file ra8_box.c.

References ra8_box_tree_t::cap, ra8_box_tree_t::count, ra8_box_t::first_child, internal_iter_live(), k_ra8_box_none, ra8_box_t::next, and ra8_box_tree_t::nodes.

Referenced by ch_build_chrome(), er_add_book_tile(), er_build_library(), er_build_nav(), er_build_toolbar(), internal_build_stack_tree(), and sh_layout_cards().

◆ ra8_box_layout()

ra8_err_t ra8_box_layout	(	ra8_box_tree_t *	tree,
		int16_t	root,
		const ra8_ui_rect_t *	frame )

nodiscard

Lay out the tree, filling every node's rect.

Sets nodes[root].rect = *frame, then makes one forward pass: each container distributes its content box (its rect inset by pad) across its children – fixed children take their fixed extent, the rest split the leftover by flex weight, separated by gap. Grids place children row-major across grid_cols. Because parents precede children in index order, a single in-order pass suffices (no recursion).

Parameters