vitepress-plugin-filelist 0.2.2 → 0.3.0

package/README.md

@@ -5,11 +5,13 @@
 ## 功能
 
 - 📁 树形目录，文件夹按需加载
-- ✅ 勾选文件；选中文件夹会连带其已加载的子项
-- 📦 批量打包 ZIP（基于 `fflate`），带进度
+- ✅ 勾选文件；选中文件夹会自动加载并选中其下所有层级的文件
+- 📦 批量打包 ZIP（基于 `fflate`），带进度；保留目录结构，不同目录的同名文件不会互相覆盖
 - ⬇️ 单文件下载与预览（`/d/`、`/p/`、`fs/get` 的 `raw_url`）
 - 🔐 目录密码输入，可选只读 token
 - 🔎 当前树过滤，按名称 / 大小 / 日期排序
+- 🎨 紧凑表格：按文件类型着色的扩展名标签、层级引导线，跟随 VitePress 亮 / 暗主题
+- 📱 窄容器（< 560px）自动切换为双行列表与 44px 触控区，勾选后工具栏变为吸顶操作条
 - 🌐 使用 `/api/fs/list`、`/api/fs/get`、`/api/public/settings`
 - 🧪 `base` 为空时使用内置演示数据
 - SSR 安全（网络请求只在客户端执行）
@@ -99,8 +101,8 @@ export default {
 
 - 目录路径挂载为根文件夹，默认折叠；`expanded` 可为全局或单个 source 打开
 - 文件路径挂载为一条文件记录，直接预览/下载
-- 根目录复选框与勾选、全选效果一致：选中根目录会选中其已加载的子项
-- 每个 source 可单独设置 `title`、`password`
+- 勾选根目录会加载并选中其下所有文件；ZIP 内以根节点名称（`title` 或路径末段）作为顶层文件夹，文件根保留原文件名
+- 每个 source 可单独设置 `title`、`password`；未设置 `password` 的 source 使用组件的 `password` 或运行时输入的密码，遇到需要密码的目录会弹出密码输入框
 - 根节点顺序按 `sources` 顺序，子项仍按名称/大小/日期排序
 
 ```ts
@@ -112,6 +114,24 @@ interface FileListSource {
 }
 ```
 
+## 界面与布局
+
+- 宽容器：表格布局（勾选 / 名称 / 大小 / 修改日期 / 操作），行高 40px；勾选文件后，工具栏原地变为操作条（已选数量、总大小、清除、下载 ZIP）
+- 窄容器（组件宽度 < 560px，基于容器查询而非视口宽度，侧边栏挤压时同样生效）：
+  - 隐藏“修改日期”列，大小与日期显示在文件名下方
+  - 行高 56px，复选框、展开、预览、下载的触控区不小于 44px
+  - 表头排序改为下拉选择
+  - 勾选后操作条吸附在组件顶部，位于 VitePress 导航栏 / “On this page” 栏下方，只在本组件范围内吸附
+- 颜色全部取自 VitePress 主题变量，暗色模式自动适配
+
+吸顶偏移默认根据 `.VPNav`、`.VPLocalNav` 的实际高度自动计算；自定义主题可手动指定：
+
+```css
+.fl-root {
+  --fl-sticky-top: 56px;
+}
+```
+
 ## 国际化
 
 ```md
@@ -181,7 +201,7 @@ Deno 可以安装 npm 依赖，但目前用 Deno 构建 VitePress 会在 rolldow
 ## 说明
 
 - 批量 ZIP 通过 `raw_url`（OpenList `/p/` 代理）下载，CORS 保持在 OpenList 源上
-- 全选只统计已加载的文件；页脚会显示还有多少文件夹未展开
+- 表头全选只统计已加载的文件，页脚会显示还有多少文件夹未展开；勾选单个文件夹则会递归加载其全部子目录（目录很深或很多时会逐个请求，可能较慢）
 - 目录以 `per_page: 0` 请求全部条目；超大目录可能较慢，暂未实现分页
 
 ## 开发
@@ -190,7 +210,7 @@ Deno 可以安装 npm 依赖，但目前用 Deno 构建 VitePress 会在 rolldow
 pnpm install
 pnpm run build       # 生成 dist/node、dist/client/ssr、dist/client/browser、style.css
 pnpm run typecheck
-pnpm test            # Vitest：utils + locale helpers
+pnpm test            # Vitest：utils、locale helpers、FileList 组件
 pnpm run pack:check
 ```
 

package/dist/client/browser/index.d.ts

@@ -6,6 +6,7 @@ interface FileListLabels {
   filter: string;
   refresh: string;
   batch: string;
+  /** @deprecated No longer shown; the selection count lives in the toolbar. */
   batchCount: string;
   batching: string;
   passwordPrompt: string;
@@ -33,6 +34,23 @@ interface FileListLabels {
   previewFailed: string;
   batchFailed: string;
   defaultZip: string;
+  /** Text button that clears the selection (wide layout). */
+  clear: string;
+  /** Accessible name of the clear-selection button. */
+  clearSelection: string;
+  /** `{size}` total, used for the selection and the footer. */
+  totalSize: string;
+  /** `{count}` files inside a loaded folder. */
+  folderItems: string;
+  /** Label of the compact sort select shown in narrow containers. */
+  sortBy: string;
+  selectAll: string;
+  /** Accessible name of a row checkbox, `{name}`. */
+  selectItem: string;
+  /** Accessible name of the expand button, `{name}`. */
+  expand: string;
+  /** Accessible name of the collapse button, `{name}`. */
+  collapse: string;
 }
 interface FileListSource {
   /** OpenList path, directory or single file. */
@@ -171,9 +189,28 @@ export interface SortableNode {
 export type SortKey = 'name' | 'size' | 'modified';
 export declare function joinPath(parent: string, name: string): string;
 export declare function encodePath(path: string): string;
+/**
+ * Make one path segment safe as a ZIP entry segment: no separators,
+ * no `.` / `..` traversal, no empty names.
+ */
+export declare function zipSegment(name: string): string;
+/** Join path segments into a ZIP entry name, sanitising each segment. */
+export declare function zipEntryName(segments: string[]): string;
+/**
+ * Return `name`, or `name (2)`, `name (3)`... when it is already in `used`.
+ * The suffix goes before the extension of the last segment. Adds the result to `used`.
+ */
+export declare function uniqueEntryName(name: string, used: Set<string>): string;
 export declare function formatSize(size: number): string;
 export declare function formatDate(iso: string): string;
 export declare function extOf(name: string): string;
+export type FileKind = 'doc' | 'sheet' | 'slide' | 'pdf' | 'image' | 'media' | 'archive' | 'code' | 'other';
+/** Rough file family, used to colour the type badge. */
+export declare function fileKind(name: string): FileKind;
+/** Sum of the `size` of the given entries, ignoring missing or invalid sizes. */
+export declare function totalSize(items: Array<{
+  size?: number;
+}>): number;
 export declare function compareNodes(a: SortableNode, b: SortableNode, key: SortKey, ascending?: boolean): number;
 /**
  * Register `<FileList>` and `<VPFileList>` globally.