#+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.