09 - Component Redesign Catalog

TermRock must be a reusable Ratatui toolkit, not a relocated copy of the jackin❯ application framework. A consumer should be able to render one TermRock button, list, input, or panel without adopting an agent model, root message enum, Tokio runtime, terminal loop, Tailrocks theme, or any other component. This chapter turns that constraint into a file-by-file redesign plan for the 24 current donor component implementation files and their shared support modules.

Ratatui architecture evidence

Ratatui documents several valid application patterns rather than prescribing one framework:

• The Elm Architecture separates a model, messages, update logic, and a view. Events are mapped to messages, updates perform state transitions, and the view should remain side-effect free for a given state. Ratatui notes that Rust applications may mutate a model in place where appropriate and that stateful widgets sometimes require mutable presentation state while rendering.
• Component Architecture co-locates component initialization, event handling, update, and rendering. The published example uses application-specific event and action types. That is useful inside an application, but it is not an appropriate required trait for a cross-application widget library.
• Flux Architecture uses actions, a dispatcher, stores, and views/widgets in a unidirectional flow. TermRock widgets can render borrowed store projections and return typed outcomes without importing or implementing a dispatcher/store API.
• Ratatui recommends implementing new reusable widgets by reference, using stable Widget for &T or StatefulWidget for &T implementations. The WidgetRef and StatefulWidgetRef traits are still unstable in Ratatui 0.30.2. See the widget authoring guidance.
• Ratatui's Builder Lite pattern consumes and returns self for render configuration. TermRock should follow this familiar construction style while keeping public fields private.
• Ratatui recommends direct Buffer unit tests for focused widget behavior and TestBackend for application integration. See TestBackend.

The implication is not "put TEA into every widget." The implication is to preserve TEA-compatible boundaries without forcing one application architecture.

TermRock architecture decision

TermRock exposes composable rendering and interaction building blocks. It does not expose a mandatory root Application, Model, Message, Component, Subscription, or EffectExecutor trait. The executor-neutral base runtime module (dirty/update contracts, subscriptions with std-channel and closure adapters, component/view traits, and the drive_frame/drive_render frame drivers) is optional by use rather than feature-gated; it exists for consumers that want the donor's TEA conventions, no widget or other module references it, and nothing requires adopting it.

backend event
    |
    v
consumer adapter -> logical chord/pointer/resize
    |
    v
consumer keymap -> component action
    |
    v
pure component update(state, action) -> component outcome
    |
    v
consumer maps outcome -> product message/effect/domain mutation

borrowed render data + interaction state + theme
    |
    v
Widget / StatefulWidget -> Buffer

This design supports both common application styles:

• a direct immediate-mode consumer constructs borrowed widgets in its draw function and updates its own state in its event loop;
• a TEA consumer maps component outcomes into its root message enum and executes effects after its root update;
• a component-oriented consumer stores TermRock interaction state in its own component and calls the same update/render functions;
• a Flux consumer maps outcomes into actions handled by its own dispatcher and stores, then projects store state back into the same widgets.

Neither consumer is visible in the public TermRock API. The library never imports their event, action, model, error, telemetry, or runtime types.

Required architecture examples

The new repository must demonstrate architectural neutrality with executable, compile-checked examples rather than a prose claim:

examples/
|- direct.rs
|- tea.rs
|- component.rs
|- flux.rs
|- buffer_only.rs
|- crossterm_manual.rs
`- crossterm_managed.rs

All examples should present the same small neutral screen using the same public tabs, list, input, action, outcome, and theme types. Only application state ownership and message routing differ:

Examples depend only on public API and contain no #[cfg(test)] access to internals. CI checks the architecture/buffer examples without features and the two Crossterm examples with the declared feature. The Fumadocs site adds an "Application patterns" section that explains these integrations and links each component page to small direct/TEA snippets where interaction is relevant. Examples are compatibility tests, not a third TermRock runtime crate.

Standard component anatomy

Not every widget needs every type, but an interactive component should normally be decomposed into these roles:

The contracts follow these rules:

1. Domain records remain in the consumer. Render models contain only the text, styles, IDs, capabilities, and state required to paint and interact.
2. Stable caller-provided IDs cross selection, hover, activation, and hit-test boundaries. Collection indices stay internal and ephemeral.
3. Widget constructors borrow labels, rows, and theme data where practical. They do not clone a full product collection every frame.
4. Configuration uses private fields and Builder Lite methods. State mutation uses named methods or pure update functions, not public fields.
5. Rendering does not dispatch callbacks, emit terminal sequences, access the clipboard, open URLs, log, spawn, poll, sleep, or mutate domain state.
6. The function that calculates layout also returns the interactive regions. Mouse routing never reconstructs geometry independently from rendering.
7. Raw Crossterm events appear only in the optional integration module. Components accept logical actions so byte-decoded and test inputs use the same path.
8. Visible hints are consumer-provided or derived from the same keymap that dispatches actions. A widget does not hardcode save, agent, run, or other product wording.
9. Empty and tiny rectangles are valid inputs and must not panic. Content is clipped by display width, not byte length or scalar-value count.
10. Public components are useful independently. Rendering Tabs must not require a TermRock status bar, terminal session, or root runtime.
11. Enabling crossterm adds adapters and convenience only. It does not select different component implementations or change base rendering behavior.

Target module tree

termrock/src/
|- input/
|  |- action.rs
|  |- binding.rs
|  |- chord.rs
|  `- pointer.rs
|- interaction/
|  |- focus.rs
|  |- hover.rs
|  |- outcome.rs
|  `- overlay_stack.rs
|- layout/
|  |- dialog.rs
|  |- hit_region.rs
|  `- slots.rs
|- scroll/
|  |- state.rs
|  |- geometry.rs
|  `- viewport.rs
|- style/
|  |- role.rs
|  |- theme.rs
|  `- tailrocks_phosphor.rs
|- text/
|  |- display_width.rs
|  |- sanitize.rs
|  `- window.rs
|- osc/
|  |- request.rs
|  `- encode.rs
|- runtime/                  # executor-neutral; optional by use
|  |- contract.rs
|  |- subscription.rs
|  `- frame.rs
|- widgets/
|  |- action_bar.rs
|  |- detail_table.rs
|  |- dialog.rs
|  |- diff.rs
|  |- hint_bar.rs
|  |- list.rs
|  |- panel.rs
|  |- status_bar.rs
|  |- tabs.rs
|  |- text_input.rs
|  `- toast.rs
`- crossterm/                # optional `crossterm` feature
   |- event.rs
   |- backend.rs
   `- session.rs

This is an ownership map, not a requirement to create a file for every small type on day one. The important constraints are one canonical owner per primitive, no components.rs mega-facade, and no module named for a consumer workflow.

Foundation module decisions

Component-by-component disposition

Extract after bounded parameterization

Reimplement before extraction

Keep consumer-local unless reuse is proven

No component is copied unchanged merely to preserve its current Rust path. The new repository should preserve useful implementation history, but neutralizing commits establish the new ownership and API before any immutable consumer pin is advertised.

Required redesign contracts

Selection and list projection

The list API must not require TermRock to own arbitrary domain values or all rows. A suitable conceptual boundary is:

pub struct ListRow<'a, Id> {
    id: Id,
    label: Line<'a>,
    role: RowRole,
    enabled: bool,
}

pub struct ListState<Id> {
    selected: Option<Id>,
    hovered: Option<Id>,
    scroll: ViewportState,
}

pub enum ListOutcome<Id> {
    Ignored,
    Changed,
    Activated(Id),
}

The exact signature remains an implementation decision. The invariant is that the consumer can project only the visible/filter-matched domain records into borrowed render rows and recover the original stable ID from an outcome.

Text editing

TextInputState owns only text-editing mechanics: content, cursor boundary, selection if supported, and horizontal viewport. It does not own a list of forbidden project names or decide that Enter means "save." The consumer maps its chord to EditAction::Submit, evaluates its domain validation, and decides whether a Submitted(String) outcome changes application state or displays a validation message.

Cursor movement, backspace, delete, selection, and viewport boundaries operate on Unicode extended grapheme clusters, with cursor positions stored as byte offsets that are always valid grapheme boundaries. Painting measures unicode-width display columns over whole grapheme/string slices using the standard non-CJK width policy. Tests cover combining marks, emoji ZWJ sequences and modifiers, regional indicators, CJK wide characters, zero-width characters, and horizontal clipping. The rationale and dependency policy are closed in 05 - Decision record.

Layout and hit testing

Every interactive widget should expose or internally reuse one pure layout calculation:

layout(area, render data, state) -> visual areas + HitRegion<Id> values
render(layout, data, state, buffer)
pointer(position, regions) -> optional Id/action

This removes the current pattern where public *_rect, *_hit, render, and OSC-overlay helpers can drift. Layout results are frame-scoped values; widgets do not retain terminal coordinates across a resize.

Updates and effects

TermRock component updates may mutate their small interaction state in place, which Ratatui explicitly permits as a practical TEA adaptation. They return data-only outcomes. They do not return boxed futures, Tokio channels, commands that can execute themselves, or consumer messages.

component action -> update interaction state -> outcome
consumer outcome -> root TEA message -> domain update + effect request
consumer runtime -> execute effect -> new root message

This keeps clipboard writes, URL opening, command execution, terminal output, database calls, agent orchestration, CI operations, and telemetry completely outside TermRock while allowing every consumer to use the same testable interaction machinery.

API rejection checks

The generated public API report and extraction ledger should fail review when any public TermRock signature or documentation contains:

• a Tailrocks product domain noun such as agent, capsule, container, workspace, role, run, database, trace, job, credential, or connection;
• a dependency path from jackin-*, Holla, Velnor, Parallax, or a future consumer crate;
• tokio, tracing, filesystem, networking, process, clipboard, secrets, or application configuration in the base crate;
• Crossterm types outside the optional integration module;
• any component, state, theme, layout, action, or outcome hidden when the crossterm feature is disabled;
• public collection indices as durable selection/activation identity;
• raw terminal escape bytes as a widget outcome;
• hardcoded product action labels or key policy;
• rendering that requires &mut only because it performs hidden projection, layout caching, event dispatch, or effects;
• duplicated free-render and widget APIs without a documented compatibility reason;
• a component that can only be tested or rendered through the lookbook's private application state.

Use a denylist as an audit aid, not as the proof of neutrality. Generic words can still hide product assumptions, and a legitimate example may use one of these nouns in consumer documentation. Human API review, neutral stories, architecture examples, and jackin❯ parity remain required. Another product proof is explicitly outside this roadmap.

Per-component conformance

Every extracted public component needs, before the first consumer pin (extraction tier):

• direct buffer tests for default, focused, disabled, empty, overflow, tiny, and off-origin rectangles;
• update tests proving ignored actions do not mutate state and handled actions return the documented outcome;
• stable-ID tests across insertion, removal, sorting, and filtering;
• layout/hit-test agreement at minimum, normal, and wide sizes;
• a neutral lookbook story and deterministic SVG;
• rustdoc showing standalone use without the Crossterm integration or root runtime;
• at least one compile-only example using a non-Tailrocks domain ID type.

Before the first tag (quality tier, after jackin❯ parity):

• Unicode/display-width cases appropriate to its content, with the recorded character-count defects fixed;
• a non-color focus/selection/error cue.

The split exists because fixing width math or adding a non-color cue changes rendered bytes: those fixes land as reviewed post-parity changes with regenerated fixtures, per 08 - Migration evidence and gates.

The repository-level direct, TEA, component, Flux, buffer-only, manual Crossterm, and managed Crossterm examples must also compile against every advertised Ratatui/MSRV compatibility cell. Canonical component buffers must be identical with and without the feature.

Composite consumer screens remain covered in their own repositories. This roadmap proves TermRock primitives are neutral and correct and proves jackin❯ composition remains compatible. Every other product validates its composition and effects later as part of its own adoption work.