Skip to content
lazy-cuh

Package Layout

lazy_cuh/
  core/           Plain framework models, events, and commands
  inputs/         Action IDs, key bindings, and navigation state
  keybar/         Keybar models and renderers
  layout/         Item-to-line rendering and wrapping
  modals/         Modal models, layout policy, and pure state transitions
  styles/         Terminal palette and theme helpers
  viewport/       Visual line mapping and scroll policy
  view/           Panel and tab specs plus title rendering
  widgets/        Textual adapters, including modal widgets
  examples/       Demo apps that consume lazy-cuh like downstream apps


  builders/       Typed declarations that derive primitive models and wiring
  presets/        Opinionated defaults for keys, themes, and shell behavior
  composition/    Helpers for assembling common app-shell layouts


  hints.py        Neutral key-hint projection from action metadata

The public package is intentionally small while the API is being designed, but the internal folders are split by responsibility from the start. Reusable logic should move into the focused packages, not into compatibility modules.

The current implementation mostly covers the primitive packages. As repeated example wiring is extracted, new code should follow the layered target documented in Package Layers:

  • repeated primitive construction belongs in builders
  • opinionated defaults belong in presets
  • complete shell wiring belongs in composition
  • Textual lifecycle code stays in widgets
  • app-specific state stays in downstream applications

Import Rule Of Thumb

Section titled “Import Rule Of Thumb”

Use import lazy_cuh as lc in full examples and app-like code so package domains stay visible:

import lazy_cuh as lc


registry = lc.builders.actions.registry(actions)
model = lc.view.ListViewModel(items=items)

Small snippets may still use direct imports for clarity, and deeper framework work may import focused subpackages directly. Prefer import lazy_cuh as lc for full examples because it keeps package domains visible at each call site.

The demo app in lazy_cuh.examples.demo should follow the same rule. If the demo has to reach into private modules to build a normal app, the public API is missing something.

For complexity limits and API ergonomics review, see Code Quality.