literate: create org/render.org, org/theme.org, org/package.org

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)
This commit is contained in:
Hermes Agent
2026-05-12 17:05:47 +00:00
parent ba5cb360db
commit ce7e9fbab0
3 changed files with 616 additions and 0 deletions

77
org/package.org Normal file
View File

@@ -0,0 +1,77 @@
#+TITLE: Base Component Package
#+STARTUP: content
#+FILETAGS: :cl-tty:components:
* 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.
#+BEGIN_SRC lisp :tangle ../src/components/package.lisp
(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)
#+END_SRC
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.