Skip to content
lazy-cuh

API Design

Calling this an API is appropriate. The API is the stable surface downstream apps use to build lazygit-style TUIs without copying framework internals.

Before a stable release, the API may still change. Pre-alpha releases should still keep the documented exports intentional: root and focused-package __all__ surfaces are snapshot-tested so additions and removals are reviewed instead of happening accidentally.

The public API is split into three surfaces:

  • lazy_cuh for commonly used pure models, renderers, controllers, and specs
  • focused subpackages such as lazy_cuh.input, lazy_cuh.view, lazy_cuh.keybar, lazy_cuh.modals, lazy_cuh.layout, and lazy_cuh.viewport when an app needs a narrower import
  • lazy_cuh.widgets for Textual adapter widgets and widget messages

The public API should expose:

  • plain models for items, panels, tabs, actions, events, commands, and selection
  • renderers for keybars, panel titles, line numbers, and item rows
  • navigation state machines that accept plain keys and return typed intentions
  • viewport helpers for visual-line mapping and scroll policy
  • Textual adapters that are thin wrappers over the pure models

For example, external apps should be able to build shell state and action metadata without importing Textual:

from lazy_cuh import ActionBinding, ActionMap, PanelSpec, ShellController, TabSpec

Textual should only enter at the adapter boundary:

from lazy_cuh.widgets import KeybarWidget, ListViewWidget, PanelWidgetSpec, ShellRuntime, ShellViewAdapter

The API should not expose:

  • app-specific domain state
  • app-specific profile, channel, or domain behavior
  • Textual lifecycle details as the primary programming model
  • raw widget subclasses as the only way to reuse behavior

Compatibility modules such as lazy_cuh.items and lazy_cuh.panels may remain as import conveniences, but new docs and examples should prefer either the root package or focused subpackages. New implementation code should live under focused packages such as core, input, layout, viewport, view, keybar, modals, and widgets.