feat(primitives): box and prose across five themes (#54)

[fsecada01]

Closes #54.

Tier 2 of the primitives layer: two container primitives, all five themes, both template sets. 22 new templates plus the class maps, docs and tests.

The two components

<Cf:Box> / <c-cf.box> — a plain bordered container. One element, no imposed header/body/footer, which is exactly what separates it from card. Takes variant.

<Cf:Prose> / <c-cf.prose> — a typographic reset for a block of server-rendered or user-supplied markup. Takes size.

Neither takes more than one axis, on purpose: a container's size is its content's business, and a typographic reset has no colour — giving it one would mean colouring every nested element.

Naming (acceptance criterion 2)

box, not surface — box is Bulma's own class name; surface is Material vocabulary that no shipped framework uses.

prose, not content — rejected twice over. content collides with Bulma's own .content class, which is the exact class this component maps to on that theme, and content is already the prop name every Jinja primitive uses for slot text.

Two framework facts that were verified, and would have shipped wrong

I checked the per-theme class claims against upstream documentation instead of asserting them. Two of ten came back refuted.

Fomantic's primary and secondary are not colours on a segment. They are its emphasis variation — .ui.primary.segment renders a subdued treatment, not a brand fill. So the variant maps to real hues (blue, grey, green, yellow, red, teal) instead. The one theme whose vocabulary appears to match cf-ui's by name is the one theme where matching it would have been wrong, and the failure would have been visual-only.

Fomantic's prose has a real gap, not merely an inert axis. It styles bare h1-h5 and p globally, so headings and paragraphs come out right — but it ships no bare ul, ol or table rule at all. That styling lives on .ui.list / .ui.table, on the element itself. So a list or table inside a prose block falls back to browser defaults, and no scoping class fixes it. Documented in docs/primitives.md as a gap with the workaround that does work (<c-cf.table> inside the block, ui list on lists), rather than papered over by cf-ui authoring its own Fomantic type scale — that would mean shipping component CSS this package has never shipped and guessing at a framework's scale.

Where prose deliberately does nothing

On Bootstrap and Foundation it emits no class at all, and that is the correct answer rather than a gap: both style bare h1-h6, p and ul globally, so the reset this component exists to scope is already in effect everywhere.

daisy and @tailwindcss/typography (acceptance criterion 4)

prose comes from the @tailwindcss/typography plugin — not from daisyUI, not from Tailwind core. It is now a declared requirement of that one component on that one theme, documented in docs/daisyui.md with the install and config lines. Without the plugin the class is unrecognised and the block renders unstyled, which is the benign class-valued failure mode rather than broken markup — the same principle AXIS_KINDS encodes.

Escaping (acceptance criterion 5)

prose is the first primitive whose entire purpose is wrapping caller-supplied markup. Mechanically nothing changed: it is still slot-based, and cf-ui's own output is still {% autoescape true %}-wrapped. What had never been written down anywhere, and now is, is that cf-ui does not sanitize. A caller reaching for Markup / mark_safe to get real markup into a prose block has taken that on, and if the HTML came from a user it must be sanitized first — docs/escaping.md names nh3 and bleach.

Two guards that could not fail

Both found by mutation, not by reading.

The theme-dispatch test was passing on whitespace. It compared raw rendered strings across the five themes and required all five to differ. A {% comment %} block leaves its own blank lines behind, so two partials emitting byte-identical markup still landed in different buckets on newline count alone. Proven: gutting a partial's entire class chain left the test green. It now compares collapsed markup, and permits a collision only when the component's entry in CLASSES proves those themes agree — so prose rendering alike on three themes passes for a stated, derived reason, while a partial that silently drops an axis still fails. Re-verified by mutation in both directions.

IMPLEMENTED was a hand-written tuple. Adding a primitive to PRIMITIVES and themes.COMPONENTS without also editing that one line shipped its templates with zero parity and guard coverage, and nothing failed to say so. It is now derived from the intersection of the two, which inverts the failure mode: a primitive registered without templates fails loudly instead of quietly going unchecked. This is the trap that would have hit this very PR.

Acceptance criteria

• box and prose as base + 5 cotton themes + 5 jinja themes each — 22 files.
• Names chosen and justified.
• No new axis was needed; both reuse variant / size, so AXIS_KINDS, VOCABULARIES and CLASS_VALUED are untouched and the existing parity and drift tests picked both components up without modification.
• The daisy prose decision documented in docs/primitives.md and docs/daisyui.md.
• The escaping contract stated explicitly in docs/escaping.md.
• Docs coverage matching the Tier 1 components, plus the stale ## Not yet implemented section corrected — it still claimed badge/heading/label/icon had no templates, false since feat(primitives): a primitives layer — button, badge, heading, label, icon (#52) #53.

Gate

2298 passed, 13 skipped (up from 2145) · ruff check clean · ruff format --check clean · 65 JS tests pass · mkdocs build --strict clean · prek run --all-files all 10 hooks pass.

Related: #55 (Tier 3, grid — a decision rather than a build) and #58 (the daisy CDN bug, independent).

🤖 Generated with Claude Code

https://claude.ai/code/session_01NhqNRBg83czKfr8L6FF5xf