docs: improved file browser

TimoKramer · TimoKramer · commit a6657a856775 · 2026-02-17T14:41:23.000+01:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -19,6 +19,14 @@ Always use `:reload` when requiring namespaces to pick up changes.
 
 # Code Style
 
+## Keep it simple
+
+Always pick the simple solution and don't overthink. Later requirements are to be solved later. Don't optimize early.
+
+## Avoid duplication
+
+Prefer a solution that has logic just once and references this solution before you duplicate logic.
+
 ## Namespace Requires and Imports
 
 Always use proper `:require` and `:import` declarations in the `ns` form instead of fully qualified names in code.
@@ -49,6 +57,13 @@ Types: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `chore`
 
 # Testing
 
+## Running examples
+
+You can run examples like the file-browser with this command
+```bash
+clojure -M -m examples.file-browser
+```
+
 ## Running Tests via REPL
 
 See [ADR 003: Testing Strategy](docs/adr/003-testing-strategy.md) for the full decision record.
diff --git a/docs/adr/adr-005-draft.md b/docs/adr/adr-005-draft.md
@@ -0,0 +1,118 @@
+# ADR 005: Layout Primitives
+
+## Status
+
+Proposed
+
+## Context
+
+Building panel-based layouts (e.g., a file browser with a list on the left and details box on the right) exposed three problems in the current layout system:
+
+### 1. `split-lines` is duplicated and drops trailing empty lines
+
+Three private `split-lines` functions exist in `layout.clj`, `border.clj`, and `overlay.clj`. All use `clojure.string/split-lines`, which drops trailing empty strings. This breaks the rendering pipeline when `:height` is used with borders:
+
+```
+align-vertical "a\nb" height=5  →  "a\nb\n\n\n"  (correct, 5 lines)
+align-horizontal processes it   →  "a\nb"          (3 trailing lines lost)
+apply-border wraps it           →  only 4 lines instead of 7
+```
+
+The `:height` style option is effectively broken when combined with `:border`.
+
+### 2. No column layout primitive
+
+`join-horizontal` concatenates text blocks side-by-side but doesn't guarantee the total width equals the terminal width. There's no way to say "left column gets the remaining space, right column is 36 chars wide." Building a two-panel layout requires manual line-by-line concatenation with `pad-right`:
+
+```clojure
+;; What you have to write today
+(defn- two-columns [left right left-width height]
+  (let [left-lines (str/split-lines left)
+        right-lines (str/split-lines right)]
+    (str/join "\n" (map (fn [i]
+                          (str (w/pad-right (nth left-lines i "") left-width)
+                               (nth right-lines i "")))
+                        (range height)))))
+```
+
+### 3. No word-wrap utility
+
+Text that exceeds a column width can only be truncated (`charm.ansi.width/truncate`). There's no way to wrap text to fit within a width, which is needed for content panes and description text.
+
+## Decision
+
+Add three focused primitives rather than a full layout engine.
+
+### 1. Shared `split-lines` in `charm.ansi.width`
+
+Move `split-lines` to `charm.ansi.width` as a public function. Use `(str/split text #"\n" -1)` to preserve trailing empty lines. Update `layout.clj`, `border.clj`, and `overlay.clj` to use it.
+
+```clojure
+(defn split-lines
+  "Split text into lines, preserving trailing empty lines.
+   Unlike clojure.string/split-lines, this is a true inverse of
+   (clojure.string/join \"\\n\" lines)."
+  [s]
+  (if (or (nil? s) (empty? s))
+    [""]
+    (str/split s #"\n" -1)))
+```
+
+### 2. `columns` function in `charm.style.layout`
+
+A function that joins pre-rendered text blocks into a fixed-width, fixed-height grid. Each column has a fixed width. Rows are padded/truncated to the specified height.
+
+```clojure
+(defn columns
+  "Join text blocks into a fixed-width row layout.
+
+   Each column is a map with :content (string) and :width (int).
+   The last column's width is optional — it takes whatever space it has.
+
+   Options:
+     :height - Total height in lines (default: tallest column)"
+  [cols & {:keys [height]}]
+  ...)
+```
+
+Usage:
+
+```clojure
+(columns [{:content file-list-view :width 44}
+          {:content details-view}]
+         :height 20)
+```
+
+This operates at the line level: split each column's content into lines, pad each line to the column's width with `pad-right`, concatenate row by row.
+
+### 3. `word-wrap` in `charm.ansi.width`
+
+Wrap text to fit within a display width, breaking at word boundaries.
+
+```clojure
+(defn word-wrap
+  "Wrap text to fit within a display width, breaking at spaces.
+   Preserves existing line breaks."
+  [s width]
+  ...)
+```
+
+## Consequences
+
+### Pros
+
+- `split-lines` duplication eliminated — single source of truth in `charm.ansi.width`
+- `:height` + `:border` works correctly in the style pipeline
+- Panel layouts (file browser, split views) become trivial with `columns`
+- `word-wrap` enables content-aware text display in fixed-width panes
+
+### Cons
+
+- Changing `split-lines` to preserve trailing empty lines changes behavior for all layout functions — needs careful testing
+- `columns` is intentionally simple (fixed widths only) — proportional/flex sizing is left for later if needed
+
+## Notes
+
+- `columns` is not a component — it's a pure layout function that works on pre-rendered strings
+- The existing `join-horizontal`/`join-vertical` remain useful for simpler cases where exact width control isn't needed
+- A future ADR could propose flex-based sizing if fixed-width columns prove insufficient
diff --git a/docs/examples/src/examples/file_browser.clj b/docs/examples/src/examples/file_browser.clj
@@ -1,22 +1,29 @@
 (ns examples.file-browser
   "File browser demonstrating list component with a details pane."
-  (:require [charm.core :as charm]
-            [clojure.java.io :as io])
-  (:import [java.io File]
-           [java.text SimpleDateFormat]
-           [java.util Date]))
+  (:require
+    [charm.ansi.width :as w]
+    [charm.components.help :as help]
+    [charm.core :as charm]
+    [charm.style.border :as border]
+    [charm.style.core :as style]
+    [clojure.java.io :as io]
+    [clojure.string :as str])
+  (:import
+    [java.io File]
+    [java.text SimpleDateFormat]
+    [java.util Date]))
 
 (def title-style
-  (charm/style :fg charm/magenta :bold true))
+  (style/style :fg charm/magenta :bold true))
 
 (def path-style
-  (charm/style :fg 240))
+  (style/style :fg 240))
 
 (def detail-label-style
-  (charm/style :fg 240))
+  (style/style :fg 240))
 
 (def detail-value-style
-  (charm/style :fg charm/cyan))
+  (style/style :fg charm/cyan))
 
 (def help-bindings
   (charm/help-from-pairs
@@ -25,7 +32,10 @@
    "Backspace/h" "back"
    "q" "quit"))
 
-(def ^:private details-width 34)
+(def ^:private details-width 36)
+
+;; Header (title + path + blank line) + blank line before help + help line
+(def ^:private chrome-height 5)
 
 (defn format-size
   "Format file size in human-readable format."
@@ -74,16 +84,21 @@
                     (format-size (:size info)))
      :data info}))
 
-(defn- make-file-list [items width]
+(defn- list-width [term-width]
+  (max 20 (- term-width details-width)))
+
+(defn- list-height
+  "Number of list items visible. Each item takes 2 lines (title + description)."
+  [term-height]
+  (max 3 (quot (- term-height chrome-height) 2)))
+
+(defn- make-file-list [items term-width term-height]
   (charm/item-list items
-                   :height 15
-                   :width width
+                   :height (list-height term-height)
+                   :width (list-width term-width)
                    :show-descriptions true
                    :cursor-style (charm/style :fg charm/cyan :bold true)))
 
-(defn- list-width [term-width]
-  (max 20 (- term-width details-width 2)))
-
 (defn init []
   (let [start-path (System/getProperty "user.dir")
         files (list-directory start-path)
@@ -92,7 +107,8 @@
       :files files
       :items items
       :term-width 80
-      :file-list (make-file-list items (list-width 80))
+      :term-height 24
+      :file-list (make-file-list items 80 24)
       :help (charm/help help-bindings :width 60)}
      nil]))
 
@@ -106,7 +122,7 @@
                :current-path path
                :files files
                :items items
-               :file-list (make-file-list items (list-width (:term-width state)))))
+               :file-list (make-file-list items (:term-width state) (:term-height state))))
       state)))
 
 (defn go-up
@@ -136,10 +152,12 @@
 
     ;; Window resize
     (charm/window-size? msg)
-    (let [w (:width msg)]
+    (let [w (:width msg)
+          h (:height msg)]
       [(assoc state
               :term-width w
-              :file-list (make-file-list (:items state) (list-width w)))
+              :term-height h
+              :file-list (make-file-list (:items state) w h))
        nil])
 
     ;; Go up directory
@@ -164,36 +182,49 @@
   [state]
   (if-let [selected (charm/list-selected-item (:file-list state))]
     (let [info (:data selected)]
-      (str (charm/render detail-label-style "Name     ")
-           (charm/render detail-value-style (:name info)) "\n"
-           (charm/render detail-label-style "Type     ")
-           (charm/render detail-value-style (if (:directory? info) "Directory" "File")) "\n"
-           (charm/render detail-label-style "Size     ")
-           (charm/render detail-value-style (format-size (:size info))) "\n"
-           (charm/render detail-label-style "Modified ")
-           (charm/render detail-value-style (format-date (:modified info))) "\n"
-           (charm/render detail-label-style "Access   ")
-           (charm/render detail-value-style
+      (str (style/render detail-label-style "Name     ")
+           (style/render detail-value-style (:name info)) "\n"
+           (style/render detail-label-style "Type     ")
+           (style/render detail-value-style (if (:directory? info) "Directory" "File")) "\n"
+           (style/render detail-label-style "Size     ")
+           (style/render detail-value-style (format-size (:size info))) "\n"
+           (style/render detail-label-style "Modified ")
+           (style/render detail-value-style (format-date (:modified info))) "\n"
+           (style/render detail-label-style "Access   ")
+           (style/render detail-value-style
                          (str (when (:readable? info) "r")
                               (when (:writable? info) "w")
                               (when (:hidden? info) " (hidden)")))))
-    (charm/render detail-label-style "No file selected")))
+    (style/render detail-label-style "No file selected")))
+
+(defn- two-columns
+  "Join left and right text blocks into a fixed-width, fixed-height grid.
+   Each row is: left padded to left-width, then right. Rows are filled to height."
+  [left right left-width height]
+  (let [left-lines (str/split-lines left)
+        right-lines (str/split-lines right)
+        render-row (fn [i]
+                     (str (w/pad-right (nth left-lines i "") left-width)
+                          (nth right-lines i "")))]
+    (str/join "\n" (map render-row (range height)))))
 
 (defn view [state]
   (let [file-list-view (charm/list-view (:file-list state))
         details-view (render-details state)
-        details-style (charm/style :border charm/rounded-border
+        details-style (style/style :border border/rounded
                                    :border-fg 240
                                    :padding [0 1]
-                                   :width (- details-width 4))]
-    (str (charm/render title-style "File Browser") "\n"
-         (charm/render path-style (:current-path state)) "\n\n"
-         (charm/join-horizontal :top
-                                file-list-view
-                                "  "
-                                (charm/render details-style details-view))
-         "\n\n"
-         (charm/help-view (:help state)))))
+                                   :width (- details-width 2))
+        content-height (* (list-height (:term-height state)) 2)
+        left-w (list-width (:term-width state))]
+    (str (style/render title-style "File Browser") "\n"
+         (style/render path-style (:current-path state)) "\n\n"
+         (two-columns file-list-view
+                      (style/render details-style details-view)
+                      left-w
+                      content-height)
+         "\n"
+         (help/short-help-view (:help state)))))
 
 (defn -main [& _args]
   (charm/run {:init init
diff --git a/src/charm/core.clj b/src/charm/core.clj
