class= 或顏色；
macro 沒有具名的關鍵字一律變成 HTML 屬性，所以 hx_post="/tasks"
會渲染成 hx-post="/tasks"。
{% endset %}
{{ page_header("每個 macro，以及產生它的那行呼叫", intro) }}
{# ============================================================== 01 #}
{% set c02 %}一個元素、七種 variant、七種 size，而且呼叫端一個 class 都不寫。{% endset %}
{% call lesson("button", "01", "Button", c02) %}
{% call prose() %}
在 button 中，variant 與 size 是封閉查表，
href 會把元素換成 <a> 並拿掉 type，
icon_name 接受任何 Lucide 名稱，所以呼叫端不必 import icon。
未知的關鍵字會作為屬性傳遞，不會被拒絕；每一個 hx-* 都是這樣送到元素上。
button_group 依方向有不同的渲染方式。horizontal 是一個有間距的 row。
vertical 是 Basecoat 的 .button-group：按鈕併成一個控制項，共用邊框，沒有間距。
有控制項可調的四支 macro 排在前面，其餘各附一個渲染好的範例。
rows 為空時，table 會自行渲染 empty_state，
所以呼叫端不寫 if-rows-else 分支。
avatar 以 name 同時作為 alt 文字與退回時的縮寫。
圖片已承載名字時，縮寫對螢幕閱讀器隱藏，所以同一個人只會被唸一次。
collapsible 是原生的 <details>：開合狀態、鍵盤操作與 disclosure 角色
全部來自那個元素，Basecoat 用 CSS 替它加動畫。tooltip 完全畫自一個
data-tooltip 屬性，不存在第二個元素。
螢幕閱讀器不會讀 CSS content()，所以 tooltip 不能是控制項唯一的標籤。
tooltip 是控制項上唯一的文字時，請另外給控制項 aria_label。
alert 是留在頁面上的事實。spinner 與 skeleton
都表示「還沒好」：知道即將出現的內容形狀時用 skeleton，不知道時用 spinner。
dialog 會打斷操作。toast 的存在時間比觸發它的回應更長。
alert(variant="destructive") 會拿到
role="alert"，那會打斷螢幕閱讀器正在唸的句子；其餘每個 variant 都是
role="status"，會等到一個停頓。多行的 skeleton 是一個即時區域，
不是每行一個。
每一支欄位 macro 都收同樣的 name、label、hint、
error、id。error 取代 hint 而不是疊加，
同時把控制項標成 aria-invalid。底下的控制項會走過同一份表單的五種樣子：
htmx 版、有錯誤的欄位、比較長的控制項、radio 與 select 的取捨，以及放在
fieldset 裡的一組 switch。
target= 決定一份表單是不是 htmx 表單。拿掉它，同一支 macro 就吐出一份
沒有 JavaScript 也能用的普通 POST。
range_field 在伺服器端設定軌道已填滿的那一段。Basecoat 只在拖曳時更新它，
少了這一步，第一次繪製顯示的是預設位置，而不是實際的值。
icon("plus") 把 Lucide 的路徑當成 <svg> 內嵌進去。
它繼承 currentColor，所以放進 primary 按鈕裡的 icon 顏色直接就是對的，
而且不論尺寸都不需要一個網路請求。
大部分 macro 直接收 icon_name=：button、stat、
empty_state、brand、sidebar_link，
所以很少需要自己呼叫 icon。底下列出一部分，任何 Lucide 名稱都可以使用。
模板裡的 utility class（例如 grid gap-4）不在內附的 stylesheet 裡，
除非 kit 本身剛好用到它。stack、row 與 grid
以參數接受間距與欄數，每個值都對應到 stylesheet 內有的 class。
虛線方塊代表你的內容。調整控制項，底下那行原始碼會跟著變。
page_header 收一個 block，那個 block 就是它的動作區：
標題、說明與按鈕在任何寬度下都在同一行。這一頁最上方的 header 就是同一支 macro，沒有動作區。
centered 與 fill 各管一個軸。centered 限制寬度；
fill 接下 shell 已經配給 main 的高度，再把子元素放進去，
登入卡片因此落在畫面正中央。兩者都需要時將它們套疊，
fill 在外層。fill 在下方沒有預覽，因為卡片沒有固定高度可填滿。
這些是外殼頁首的零件，可以單獨 import。在這一頁上，側欄最上方的標記是
brand，頁首的切換鈕是 theme_toggle。
nav_links 收的是路由名稱而不是 URL，所以判斷目前在哪一頁是比對路由，
不是字串比對路徑，URL 多一段 query string 之後仍然正確。
目的地超過大約六個，一排頁首就不夠寬，那時改填外殼的 sidebar block。
breadcrumb 收 (label, href) 成對的清單。href 為 None
的一項代表當前頁，渲染成純文字，不會連回自己。
ui/overlay.html 裡的每一個都由 Basecoat 自己的 JavaScript 驅動，外殼已經載了它，
而且它會在 htmx:afterSwap 時重新掃描，所以由 swap 送進來的浮層不需要額外處理就能用。
觸發元素與面板靠四個相關的 id 互相找到對方。錯一個就會靜默失敗：面板打得開但不會被唸出來，
或者打不開。這裡每支 macro 只收一個 id，並推導其餘三個。
select_menu 與 combobox 把值放在伺服器端預先填好的隱藏欄位裡，
所以重繪這個片段的 swap 不會弄丟選取。select_field 夠用時優先使用它：
原生的 <select> 只有一個元素，也不需要腳本。
兩個都收 multiple=true，此時 selected 收的是一個
list，不再是單一值。隱藏欄位裡放的是 Basecoat 的 JSON 陣列，
multiselect_scripts() 由用到這種欄位的頁面載入，在送出時把它改寫成重複欄位：
labels=bug&labels=ui。路由宣告 labels: list[str] = Form([])。
沒有載入這支腳本時，欄位會送出一整串 JSON 字串，路由回應 422。
multiple 的 combobox 是為窄欄排版的：篩選框自己佔第一行，chips 在它下方換行，
控制項撐滿整欄，清單錨定在篩選框而不是 chips 的底部，所以連續選取幾個選項時，
游標下的選項不會移動。過長的標籤在清單裡換行，在 chip 裡截斷。
選項在十來個以內時，放在 fieldset 裡的一組 checkbox 送出相同的內容，而且不需要腳本。
shell.html 沒有 macro，也沒有預覽，因為預覽就是這一頁。
它擁有 <head>、深色模式的閃爍防護、資源連結、toaster，
以及 header／main／footer 骨架。它不擁有的部分——品牌、導覽、頁尾文字——都是 block。
填入 sidebar block 後，版面會變成側邊欄加頂列，外殼並在頁首加上
sidebar_trigger。不需要設定任何旗標。
頁面捲動時，頁首固定在視窗頂端。它使用 position: sticky 而不是 fixed，
所以頂列保留自己的空間，main 不需要額外的內距來避開它。
若填了 sidebar，頂列會橫跨整個寬度，側邊欄從頂列下方開始。
需要頁首留在一般文件流中的頁面（例如嵌入式或列印版面），請以自己的 <header>
覆寫 header block。
這一頁左邊的側欄就是這支 macro。它是 position: fixed，所以沒有預覽卡片；
產生它的呼叫印在下方。
連結接受路由名稱，圖示接受 Lucide 名稱。open 只設定寬螢幕上的起始狀態。
窄螢幕上側欄是整頁覆蓋的浮層，一律從關閉開始。
關掉 JavaScript 時，伺服器端渲染的 aria-hidden="false" 讓寬螢幕照樣可以導覽，
並在窄螢幕上把浮層藏起來。兩種情況下連結都留在 HTML 裡，爬蟲與閱讀模式仍然看得到。
columns 是一串 dict：label，需要時再加 align、
width、sort、sort_url 或 select。
rows 則決定這支 macro 要渲染你的內容還是空狀態。
它接受 rows 卻不迭代，原因就在此：呼叫端不寫 if-rows-else 分支。
請在迴圈裡以 macro 呼叫渲染每一列。在迴圈裡使用 {% raw %}{% include %}{% endraw %}
會對每一列做一次模板查找並建立新的 context，速度慢 20–30%
（jinja-performance.md）。
帶了 sort_url 的欄位會變成可排序表頭，pagination 則放在表格底下。
兩者都不自己組網址：query string 歸路由管，因為只有它知道現在開著哪些篩選。
兩者渲染的都是真的 href，再由 target= 疊上 htmx swap，
所以排序與換頁在關掉 JavaScript 時仍可運作，URL 也可以加入書籤。
{% raw %}{"select": true}{% endraw %} 會在最前面加一欄批次選取。
它送出的就是核取方塊欄位一直以來送出的那種重複欄位，
而 select_scripts() 負責讓表頭那一格勾選整欄。
resizable=true 會在每個有 label 的欄位右緣放一個把手。訪客可以拖曳它，
或是聚焦後按方向鍵；按 Home 或雙擊則把欄寬還原為自然寬度。
欄寬存在 localStorage，以表格的 id 為鍵，所以可調寬的表格必須有
id；重新載入或經過 htmx swap 後，欄寬都會還原。頁面要載入
resize_scripts()；沒有載入時把手不會出現，表格就是一般的表格。
CSS 做不到這件事：resize 只作用於帶 overflow 的區塊盒，而表格儲存格不是。
page_size 是一個 <form method="get">，因為單獨一個
<select> 沒有腳本就無法送出。它的 url 不能帶 query string：
GET 送出會以表單欄位取代整段 query，所以篩選要放進 keep。
不要保留頁碼；改變每頁筆數後，原本的頁碼就不再有效。
哪一個分頁被選取、roving tabindex 與方向鍵全部屬於 Basecoat，外殼已經載好了它。
這支 macro 提供那套行為要讀的 aria 契約：一個 [role="tab"]，
它的 aria-controls 指到同名 id 的 [role="tabpanel"]。
selected 指名一開始就打開的分頁。伺服器知道這次請求是為了哪一個，
所以它是一個參數，而不是繪製之後由腳本決定。
這一頁每個 playground 底下的程式碼分頁，用的就是這支 macro。
分頁放在另一個分頁的面板裡時（例如頁面某一區塊內的模式切換），內層那組請使用
variant="segmented"。它渲染成膠囊形分頁列，兩層因此外觀不同。
這裡的 variant 表示形狀，不是 button 或 badge
上那種顏色角色；可用值為 underline（預設）與 segmented，
其他值一律退回預設。