ce7e9fbab0
Follows the literate programming workflow: Overview → Contract → Tests → Implement → Tangle → Test (GREEN) render.org covers render.lisp + render-tests.lisp (component protocol, render dispatch, dirty propagation) theme.org covers theme.lisp + theme-tests.lisp (theme class, presets, color resolution) package.org covers package.lisp (cl-tty.box defpackage)
2.6 KiB
Base Component Package
Overview
The cl-tty.box package is the central namespace for the component
system. It aggregates all component-related symbols — box, text,
dirty tracking, render dispatch, theme engine — under one package.
Why box as the package name? Historically the package was created
for the box and text renderables, and the name stuck as the
package grew to encompass the entire component layer. The package
:use~s ~cl-tty.backend (for drawing primitives) and cl-tty.layout
(for layout nodes). All component code lives in this package.
This org file is documentation-only: it explains the package design
but the code itself is just a defpackage form.
Contract
The cl-tty.box package exports these symbol groups:
- Box:
box,make-box,render-box, border style/title accessors - Span:
span, span attribute readers - Text:
text,make-text,render-text, text accessors - Dirty:
dirty-mixin,dirty-p,mark-clean,mark-dirty - Render:
render,render-screen,render-node, tree navigation - Theme:
theme,make-theme,theme-color,load-preset,define-preset
Implementation
cl-tty.box uses cl-tty.backend for draw-text, draw-border,
etc., and cl-tty.layout for layout-node, compute-layout, and the
vbox~/~hbox macros.
The only direct dependencies are these two packages — no other application code is needed to define components.
(defpackage :cl-tty.box
(:use :cl :cl-tty.backend :cl-tty.layout)
(:export
;; Box
#:box #:make-box
#:box-layout-node
#:box-border-style #:box-title #:box-title-align
#:box-fg #:box-bg
#:render-box
;; Span
#:span
#:span-text #:span-bold #:span-italic #:span-underline
#:span-reverse #:span-dim #:span-fg #:span-bg
;; Text
#:text #:make-text
#:text-layout-node #:text-content #:text-spans
#:text-fg #:text-bg #:text-wrap-mode
#:render-text
;; Utilities (for tests)
#:word-wrap #:split-string
;; Dirty tracking
#:dirty-mixin #:dirty-p #:mark-clean #:mark-dirty
;; Rendering pipeline
#:render #:render-screen #:render-node
#:component-layout-node #:component-children #:component-parent
#:available-width #:available-height
#:propagate-dirty
;; Theme engine
#:theme #:make-theme #:theme-mode
#:theme-color #:load-preset #:define-preset))
(in-package :cl-tty.box)
The #:word-wrap and #:split-string exports are for tests only —
they're utility functions used internally by text rendering but
exposed so the test suite can unit-test them directly.