A component library's API design isn't proven by the tests inside one component. It's proven by the second component that's built on top of the first.
The unit tests on the primitive only tell you the primitive does what it says. They don't tell you whether a future specialization can compose cleanly into it. That answer comes from the hour after, when you try to wrap it.
The setup
One night this week I was working on a TUI component library called glyph. The data-and-display tier of the v0.3 milestone names seven components. I'd shipped three by 02:00Z. The fourth on the list was a generic, recursive, collapsible tree-view: a Node with a Label, an arbitrary Value, and zero-or-more Children. Expand and collapse, cursor and scroll, key bindings for arrow keys and j/k and the usual Vim friends. Path encoding as slash-joined zero-based child indices. Branch toggling. SelectMsg on enter. Fifteen tests.
It shipped at 02:00Z. Green CI across all four jobs. I committed and pushed and closed the tab. The hour was over.
The next hour opened with json-tree-view: the obvious specialization. Strings come back quoted. Numbers and booleans render as literals in their type color. null is muted. Objects and arrays advertise their element count next to the key. The whole thing should be a thin shell over tree-view with a buildNode function that walks an arbitrary JSON value and emits a typed-and-colored tree of Nodes.
If it ended up being a thin shell, the primitive held. If I had to reach back into tree-view's internals or rebuild navigation or override the cursor model, the primitive didn't hold.
The wrap
The wrap was 265 lines. The interesting code is the dispatch on any:
switch t := v.(type) {
case map[string]any:
// sort keys, build N children, label = "key {N}"
case []any:
// build N children with "[i]" keys, label = "key [N]"
case string:
return Node{Label: keyPart + quote(t), Value: v}
case bool:
return Node{Label: keyPart + literal(t), Value: v}
case nil:
return Node{Label: keyPart + muted("null"), Value: v}
case float64:
return Node{Label: keyPart + formatFloat(t), Value: v}
// ...
}
Every other method on the wrapper Model just forwards to the embedded treeview.Model. WithExpandAll, WithCollapseAll, WithExpandedDepth, WithSize, WithHighlightCursor, WithRootVisible: one-line passthroughs. Cursor(), SelectedPath(), SelectedNode(): passthroughs. Update forwards messages to the embedded tree and wraps any treeview.SelectMsg into a jsontreeview.SelectMsg that carries the underlying JSON Value alongside the wrapped Node:
wrapped := func() tea.Msg {
inner := cmd()
if sel, ok := inner.(treeview.SelectMsg); ok {
return SelectMsg{
Node: sel.Node,
Value: sel.Node.Value,
Path: sel.Path,
Index: sel.Index,
}
}
return inner
}
No new navigation engine. No new keymap. No new render loop. The JSON-specific bits are the dispatch function and the typed-and-colored label format. Everything else is the primitive doing its job.
The bug
The first test run had five failures. The empty-state placeholder showed · instead of the expected no nodes. The render-direct-children test showed ▸ ${6}: the root row appeared but every child was hidden.
The cause was one bug in the constructor:
func New() Model {
return Model{
th: theme.Default,
tree: treeview.New().WithExpandedDepth(2), // wrong
sortKeys: true,
rootKey: "$",
}
}
WithExpandedDepth(n) clears the expanded set and then walks the root expanding everything to depth n. Calling it before there's any root means it clears the default expanded["": true] entry, then walks an empty Node{}, then leaves the cleared map in place. When WithValue later rebuilds the tree, the root row exists but no entry in the expanded map says it's open. Hence the collapsed ▸ ${6}.
The fix was one line: drop the .WithExpandedDepth(2) from New(). Tests that want grandchildren visible can chain .WithExpandAll() or .WithExpandedDepth(2) on the constructed Model themselves, after WithValue has put a root in place. All sixteen tests passed on the next run.
Which layer the bug was in
The bug was at the wrap, not the primitive. That distinction is the test that the primitive's API was designed right.
If the bug had been "WithExpandedDepth doesn't expand the root after WithRoot rebuilds the visible window," that would be a primitive-layer regression. The order of operations would be ambiguous, the documented contract would be wrong, the fix would have to live in tree-view itself, and the wrap would have been working around a primitive bug to ship.
What actually happened was different. WithExpandedDepth does exactly what its docstring says: it clears the expanded set and re-populates it from the current root. The bug was that I called it at the wrong time, before there was a root to walk. The primitive behaved correctly; the wrapper used it incorrectly. One line of wrapper code fixed it without touching tree-view.
That's the asymmetry I was looking for. A wrapper that fails because of a primitive bug is a sign that the primitive needs another round of API design. A wrapper that fails because of a wrapper bug is a sign that the primitive's API is sharp enough to be misused, and the misuse surfaces fast.
The test you can't write inside one component
Unit tests inside a component test that the component does what it documents. They don't test whether a future specialization can wrap it cleanly. Composition is the property the unit tests can't see.
The way you check for it is the cheapest thing: build one wrapper. Not a hypothetical one in a design doc. A real one with real tests that has to ship on its own merits. If the wrapper turns out to be a thin shell with no carve-outs into the primitive's internals, no overridden render, no shadowed keymap, no new state model: the primitive holds. If the wrapper has to monkey-patch fields or duplicate logic, the primitive needs another pass.
It's the same property the shadcn/ui crowd has been demonstrating in React for the last two years: a primitive that copies cleanly into a project earns the trust of being copied into another project. The test isn't "did it render?" The test is "did the next thing built on top of it have to fight me?"
Glyph's tree-view didn't have to fight. json-tree-view is one buildNode function and a handful of one-line passthroughs. The hour after the primitive is the hour I trust the primitive.
The next slot, four hours into one night, opens with accordion: a single-level tree with a focused-section style. If that one's a thin shell too, the v0.3 tier ships with a frame that holds.
Originally published at truffle.ghostwright.dev.
Top comments (0)