CardList

卡片列表：布局、加载与多选手势一处收齐，每项由 #item 插槽给——写 Card 或整张自定义。插槽参数是 { item, index, itemKey, selected, active, selecting, toggle }（叫 itemKey 不叫 key：key 是 Vue 保留字，传进去会变成 vnode key）。

状态归列表、渲染归项：列表持有选中集合、高亮项与选择模式，经 provideListItemContext 逐项传下去，项组件用 useListItemContext 读本项状态、自己决定怎么画。XCard 是第一个接它的项组件，插槽里写 <XCard> 不必逐项绑定；hover 给列表统一的悬停效果，单张卡自己给了以卡片为准。容器 role=list，class / style 落在根上。

数据侧见 usePagedList，多选手势见 useCollectionSelect。

无限加载

has-more 时底部哨兵进视口发 load-more。没铺满且还有更多就接着要：列表变了、拉完一页、容器尺寸变了都主动量一次（IntersectionObserver 只在进出视口时回调，一页拉完哨兵仍在视口里不会再报）；要过一页而列表原样没变就停，防空页死循环；容器在 display: none 里不拉。数据可以是同步的本地切片，不必有 loading。

首次加载（loading 且没有项）出骨架（skeleton 块数，或 #skeleton 插槽）；error 独立于「没有更多」，显示重试、发 retry。

布局

• grid 纯 CSS 宫格：按 min-item-width 自动排列数，或 columns 固定列数。
• masonry 瀑布流：按 item-size（多是图的像素尺寸）的宽高比估高、放进最矮的一列，DOM 按列排，追加下一页时前面的不换列；卡片里固定高度的部分给 item-extra。
• columns CSS 多栏纵向流：先排满一栏再排下一栏。

gap 行列同一个数；min-columns 给列数下限，按实测的内容宽度（已扣滚动条）排，宿主不必按边线、内边距反推卡片宽度。

多选

selectable 打开，选中集合与选择模式是 v-model:selected（Set<string>）与 v-model:selecting。手势同 Finder 与 iOS 相册：点勾选圈或 ⌘ / Ctrl / Shift 点进入选择模式；模式里点一项加减、Shift 连选、按住一项划过去连成一段、从空白处拖框；⌘A 全选、Esc 退出。选择模式里卡片内的点击在捕获阶段拦下，宿主的「打开」不会触发。

批量操作栏由 #selection-bar 给（{ count, total, selectAll, invert, exit }），组件不认识业务动作。无限加载时给 selectable-keys（全部可选的键，含没加载的）：只按已加载的算，「全选」只选了一页，换筛选重新分页时后面几页的选中会被悄悄清掉。

分页

paginate 换成底部分页器（v-model:page、page-size、total），不再无限加载。行视图也是卡片：plain + hover="tint"，换视图时选中、高亮与加载状态不用换一套。scroll 关掉时列表随外层滚。

文案与边界

空态、到底、出错、重试、加载中与勾选圈名取 useUiLocale().cardList，props 可覆盖；空态与到底传空串即不显示。当前不做虚拟化，项全量渲染。布局判定的纯逻辑（columnCount / masonry / estimateHeight / wantsMore 等）已导出，宿主自写列表时复用同一套。

API