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)
78 lines
2.6 KiB
Org Mode
78 lines
2.6 KiB
Org Mode
#+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.
|