iter(g305): 新增瀑布流布局 masonry

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T16:31:56.843Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T16:34:08.281Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2524,6 +2524,32 @@ container.append(sort.el);
 
 现场演示：apps/docs/demo.html#sec-sortable
 
+### masonry — 瀑布流 Masonry
+
+参数：
+
+- items（必填）：unknown[] —— 每个卡片内容（字符串 / DOM / 响应式值）；数组顺序即铺放顺序，列高不等由内容自己决定
+- columns：number —— 固定列数；传了即不随容器宽度变化，与 minColumnWidth 互斥
+- minColumnWidth（默认 240）：number —— 自适应列宽下限（像素）；缺省 240，容器越宽列数越多
+- gap（默认 var(--ua-space-3)）：string —— 列间距与行间距（CSS 长度或令牌值）；缺省 var(--ua-space-3)
+
+示例：
+
+```
+masonry({ minColumnWidth: 220, items: shots.map((s) => card({ title: s.title }, image({ src: s.url }))) })
+```
+
+手把手：
+
+1. items 里直接放 card / image / 任意 DOM：每项由组件包一层 .ua-masonry-item，只有这一层带 break-inside: avoid，卡片才不会在列边界断成两截
+2. 不传 columns 就按 minColumnWidth 自适应：容器变宽自动加列、窄屏自动降到一列，不需要自己监听 window.resize
+3. 要固定几列（比如大屏看板恒 4 列）就传 columns，此时 minColumnWidth 不再生效——两者互斥，别同时传指望它俩协商
+4. 间距传一次就够：gap 同时给 column-gap 与每项的 margin-bottom，列间距和行间距天然一致；改间距只改这一处
+5. 列高不等才是瀑布流的价值所在（图片墙、评论流、看板）：等高内容请用 grid，瀑布流会把等高卡片铺成奇怪的错位
+6. 什么时候别用：需要严格的行对齐（表格化数据）、需要按列独立滚动（用 splitter / 多个 virtualList），以及首屏内容需要按阅读顺序严格横向（多列布局是竖向填充，读屏顺序与视觉列序一致但不等同于行序）
+
+现场演示：apps/docs/demo.html#sec-masonry
+
 API 速览：
 
 - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调
@@ -2616,6 +2642,7 @@ API 速览：
 - progressRing(props)：环形进度，SVG 双圆靠 dasharray 画弧 + 中心百分比，value 可传信号自动重绘
 - noticeBar(props)：单行通知条，语义色 + 左侧符号 + 可选跑马灯与关闭，适合页顶常驻播报
 - sortableList(props)：拖拽排序列表，整行可拖 + Alt+↑↓ 键盘搬位，返回 { el, move, order } 句柄
+- masonry(props)：瀑布流多列布局，列宽自适应或固定列数，卡片不被拆到两列
 
 一行用法：