docs: color map documentation

.github/workflows/docs.yml

@@ -37,9 +37,9 @@ jobs:
 
       - uses: charmbracelet/vhs-action@v2
 
-      - name: Install vim
-        # This is used for the "cy/project" story
-        run: sudo apt-get install -qqy vim
+      - name: Install vim and htop
+        # For the "cy/project" story and "layout/dynamic/color-map" story
+        run: sudo apt-get install -qqy vim htop
 
       - name: Build
         run: >

docs/src/SUMMARY.md

@@ -58,6 +58,7 @@
 
     - [Bar](./layouts/nodes/bar.md)
     - [Borders](./layouts/nodes/borders.md)
+    - [Color map](./layouts/nodes/color-map.md)
     - [Margins](./layouts/nodes/margins.md)
     - [Pane](./layouts/nodes/pane.md)
     - [Split](./layouts/nodes/split.md)

docs/src/layouts/nodes.md

@@ -4,6 +4,7 @@
 
 - **[Bar](/layouts/nodes/bar.md)**: A node that adds a customizable status bar to the top or bottom of a node.
 - **[Borders](/layouts/nodes/borders.md)**: A node is enclosed in borders with an optional title on the top or bottom.
+- **[Color map](/layouts/nodes/color-map.md)**: A node that applies a [color map](/parameters/colors.md#color-maps) to its contents.
 - **[Margins](/layouts/nodes/margins.md)**: A margins mode constrains the size of its child node by adding transparent margins.
 - **[Pane](/layouts/nodes/pane.md)**: A pane node can be attached to panes that exist in [the node tree](/groups-and-panes.md).
 - **[Split](/layouts/nodes/split.md)**: A split node divides the screen space of its parent node in two and provides it to two other nodes, drawing a line on the screen between them.

docs/src/layouts/nodes/color-map.md

@@ -0,0 +1,54 @@
+# Color map
+
+{{story cast layout/dynamic/color-map}}
+
+A `:color-map` node applies a [color map](/parameters/colors.md#color-maps) to its contents.
+
+```janet
+{
+    :type :color-map
+    :map @{} # color map, dynamic
+    :node {} # a node
+}
+```
+
+`:map`
+
+A [color map](/api.md#color-map).
+
+`:node`
+
+A valid layout node.
+
+
+## Example
+
+The example at the top of the page was created with the following Janet code:
+
+```janet
+(def cmd1 (cmd/new :root :command "htop"))
+(def cmd2 (cmd/new :root :command "htop"))
+(def cmd3 (cmd/new :root :command "htop"))
+(defn
+  theme [layout]
+  (def node (layout/attach-id layout))
+  (if
+    # Apply one color scheme if the client is not attached to this node
+    (nil? node) ((color-maps/get :atelier-sulphurpool) :map)
+    # And a different one if they are
+    ((color-maps/get :atelier-sulphurpool-light) :map)))
+
+(layout/set (layout/new
+              (split
+	        (split
+		  (color-map
+		    theme
+		    (attach :id cmd1))
+		  (color-map
+		    theme
+		    (pane :id cmd2))
+		  :vertical true)
+                (color-map
+                  theme
+                  (pane :id cmd3)))))
+```

pkg/cy/stories.go

@@ -790,47 +790,41 @@ func init() {
 		return screen, err
 	}, stories.Config{})
 
-	stories.Register("layout/colormap", func(ctx context.Context) (
+	stories.Register("layout/dynamic/color-map", func(ctx context.Context) (
 		mux.Screen,
 		error,
 	) {
 		_, client, screen, err := createStory(ctx)
 		err = client.execute(`
-(def cmd1 (shell/new))
-(layout/set (layout/new
-              (color-map
-                (fn [layout]
-                  (def node (layout/attach-id layout))
-                  (if
-                    (nil? node) @{"0" "#ff0000"}
-                    @{"0" "#f00000"}))
-                (attach :id cmd1))))
-
-(def cmd1 (shell/new))
-(def cmd2 (shell/new))
+(def cmd1 (cmd/new :root :command "htop"))
+(def cmd2 (cmd/new :root :command "htop"))
+(def cmd3 (cmd/new :root :command "htop"))
 (defn
   theme [layout]
   (def node (layout/attach-id layout))
   (if
-    (nil? node) @{"0" "#ff0000"}
-    @{"0" "#0000ff"}))
+    (nil? node) ((color-maps/get :atelier-sulphurpool) :map)
+    ((color-maps/get :atelier-sulphurpool-light) :map)))
 
 (layout/set (layout/new
               (split
+	        (split
+		  (color-map
+		    theme
+		    (attach :id cmd1))
+		  (color-map
+		    theme
+		    (pane :id cmd2))
+		  :vertical true)
                 (color-map
                   theme
-                  (attach :id cmd1))
-                (color-map
-                  theme
-                  (pane :id cmd2)))))
+                  (pane :id cmd3)))))
 		`)
 		return screen, err
 	}, stories.Config{
 		Input: []interface{}{
 			stories.Wait(stories.Some),
-			stories.Type("ctrl+a", "L"),
-			stories.Wait(stories.Some),
-			stories.Type("ctrl+a", "H"),
+			stories.Type("ctrl+a", "J"),
 			stories.Wait(stories.Some),
 			stories.Type("ctrl+a", "L"),
 			stories.Wait(stories.Some),