SugarCraft composability cookbook

SugarCraft asserts that its libraries compose, but that claim is mostly made in prose. This cookbook is a small set of runnable PHP scripts that show two or more libraries working together end-to-end.

Each example is non-interactive: it builds the model(s), feeds a scripted message or two through the normal update() contract, renders one frame, and exits. No event loop, no TTY required — so they run anywhere (including CI).

Running

cd docs/cookbook
composer install        # symlinks the sibling libs via path repositories
php spinner-in-table.php
php sparkline-in-table.php
php program-within-program.php

composer install wires up the libraries through path repositories (../../<lib>), so the examples always run against the current monorepo checkout. vendor/ is gitignored.

Examples

File Composition Shows
spinner-in-table.php sugar-forms Spinner + sugar-table Table A live spinner frame embedded in a StyledCell, used as a per-row job status.
sparkline-in-table.php sugar-charts Sparkline + sugar-table Table + sugar-forms Spinner One inline trend chart per table row, with a spinner as the panel's "refreshing" indicator.
program-within-program.php sugar-core Model + sugar-forms Spinner The MVC-style Model–Update–View "sub-program" pattern: a root model forwards messages to whichever child (a counter or a spinner) has focus.

The recurring trick

Most of these compositions rely on the same property: a SugarCraft component's view() returns a plain string of ANSI bytes. That means any component drops into any string slot — a sugar-table cell, a sugar-toast background, a parent model's frame — without a dedicated adapter. The "program-within-a-program" example shows the other half: sugar-core's Model::update() contract lets one model own and drive another as a sub-program.