From 1d6484084edab9e1a3bfebbdb142704e282688e5 Mon Sep 17 00:00:00 2001
From: Marcus Kammer <marcus.kammer@mailbox.org>
Date: Sat, 3 Aug 2024 12:48:08 +0200
Subject: [PATCH] Update docstrings

---
 src/section.lisp | 42 ++++++++++++++++++++++++++----------------
 1 file changed, 26 insertions(+), 16 deletions(-)

diff --git a/src/section.lisp b/src/section.lisp
index 9973c4a..2cbf5d0 100644
--- a/src/section.lisp
+++ b/src/section.lisp
@@ -2,29 +2,39 @@
 
 (defpackage ml-sbt/section
   (:use :cl)
-  (:export :with-section))
+  (:export :with-section
+   :with-title-bar))
 
 (in-package :ml-sbt/section)
 
-(defmacro with-section ((headline &optional functions) &body body)
-  "Creates a Bootstrap-styled section with a headline and optional function buttons.
+(defmacro with-title-bar (head &rest items)
+  "Creates a Bootstrap-styled title bar with an optional set of action buttons.
 
-HEADLINE: The text for the section's headline.
+HEAD: The text for the title bar's heading.
 
-FUNCTIONS: An optional list of alternating label and URL pairs for function buttons.
-
-BODY: The content of the section.
+ITEMS: An optional list of alternating label and URL pairs for action buttons.
 
 Example:
-  (with-section (\"My Section\" (\"Add\" \"/add\" \"Save\" \"/save\"))
-    \"Section content goes here\")"
+  (with-title-bar \"My Section\" \"Add\" \"/add\" \"Save\" \"/save\")"
+  `(spinneret:with-html
+     (:div :class "d-flex justify-content-between flex-wrap flex-md-nowrap align-items-center pt-3 pb-2 mb-3 border-bottom"
+           (:h* ,head)
+           ,@(when items
+               `(:div :class "btn-group" :role "group"
+                      ,@(loop for (label url) on items by #'cddr
+                              collect `(:a :class "btn btn-outline-primary"
+                                           :href ,url
+                                           ,label)))))))
+
+(defmacro with-section (&body body)
+  "Creates a Bootstrap-styled section.
+
+BODY: The content of the section, typically including a call to with-title-bar.
+
+Example:
+  (with-section
+    (with-title-bar \"My Section\" \"Add\" \"/add\" \"Save\" \"/save\")
+    (:p \"Section content goes here\"))"
   `(spinneret:with-html
      (:section :class "mb-3"
-               (:div :class "d-flex justify-content-between flex-wrap flex-md-nowrap align-items-center pt-3 pb-2 mb-3 border-bottom"
-                     (:h* ,headline)
-                     ,@(loop for (label url) on functions by #'cddr
-                             when functions
-                               collect `(:a :class "btn btn-outline-primary"
-                                            :href ,url
-                                            ,label)))
                ,@body)))