vitepress-plugin-filelist 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EduSprout contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# vitepress-plugin-filelist
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenList file browser for VitePress — tree view, batch ZIP download, folder password and token support.
+
+VitePress 的 OpenList 文件浏览组件：树形展开、勾选批量打包、目录密码、token，直接调用 OpenList 接口。
+
+## Features
+
+- 📁 Tree view with lazy-loaded folders
+- ✅ Checkbox selection, folder selects its loaded children
+- 📦 Batch download as ZIP (via `fflate`), with progress
+- ⬇️ Single file download and preview (`/d/`, `/p/`, `fs/get` raw URL)
+- 🔐 Folder password prompt, optional read-only token
+- 🔎 Filter current tree, sortable name / size / date
+- 🌐 Uses `/api/fs/list`, `/api/fs/get`, `/api/public/settings`
+- 🧪 Demo mode with built-in fake data when `base` is empty
+- SSR safe (network requests only run on the client)
+
+## Install
+
+```bash
+pnpm add -D vitepress-plugin-filelist
+# or: npm i -D vitepress-plugin-filelist
+```
+
+## Usage with vitepress-tuck
+
+```ts
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress-tuck'
+import fileList from 'vitepress-plugin-filelist'
+
+export default defineConfig({
+  plugins: [fileList()],
+})
+```
+
+```ts
+// .vitepress/theme/index.ts
+import type { Theme } from 'vitepress'
+import enhanceApp from 'virtual:enhance-app'
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp(ctx) {
+    enhanceApp(ctx)
+  },
+} satisfies Theme
+```
+
+```md
+<FileList base="https://pan.example.com" path="/课程资料" />
+```
+
+## Usage with plain VitePress
+
+```ts
+// .vitepress/theme/index.ts
+import DefaultTheme from 'vitepress/theme'
+import { enhanceAppWithFileList } from 'vitepress-plugin-filelist/client'
+import 'vitepress-plugin-filelist/style.css'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp(ctx) {
+    enhanceAppWithFileList(ctx)
+  },
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `base` | `string` | `''` | OpenList base URL. Empty = demo mode |
+| `path` | `string` | `'/'` | Initial directory |
+| `token` | `string` | `''` | Optional read-only token (guest when omitted) |
+| `password` | `string` | `''` | Folder password; can also be entered at runtime |
+| `title` | `string` | `''` | Toolbar title; falls back to OpenList `site_title` |
+| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | Built-in label preset |
+| `labels` | `Partial<FileListLabels>` | `undefined` | Per-key label overrides |
+
+Both `<FileList>` and `<VPFileList>` are registered.
+
+## i18n
+
+```md
+<FileList locale="en-US" base="https://pan.example.com" />
+```
+
+Override individual labels on top of the preset:
+
+```md
+<FileList
+  :labels="{ batch: '下载全部', loaded: '共 {count} 个文件' }"
+  base="https://pan.example.com"
+/>
+```
+
+Available presets: `zh-CN`, `en-US`. Placeholders use `{count}`, `{percent}`, `{message}`, `{name}` and are replaced by `formatLabel()`. The full key list is exported as `FileListLabels`:
+
+```ts
+import type { FileListLabels } from 'vitepress-plugin-filelist/client'
+import { fileListLocales, formatLabel, resolveLabels } from 'vitepress-plugin-filelist/client'
+```
+
+## OpenList requirements
+
+1. **Guest read access** — enable the guest user, or pass a read-only `token`.
+2. **CORS** — OpenList's `cors.allow_origins` must include your site origin (default `*`).
+3. **Same protocol** — an HTTPS page cannot call an HTTP OpenList (mixed content).
+4. **Token is public** — only ship a read-only token that can be revoked.
+
+The component calls:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `POST /api/fs/list` | Directory listing (`per_page: 0`) |
+| `POST /api/fs/get` | `raw_url` for download / preview / ZIP; falls back to `/d/...?sign=` |
+| `GET /api/public/settings` | `site_title` fallback |
+| `GET /d/...` `GET /p/...` | Download / preview links generated by OpenList |
+
+## Exports
+
+| Entry | Contents |
+| --- | --- |
+| `vitepress-plugin-filelist` | `fileList` plugin (default export) |
+| `vitepress-plugin-filelist/client` | `FileList`, `VPFileList`, `enhanceAppWithFileList`, types |
+| `vitepress-plugin-filelist/style.css` | Component styles |
+
+## Compatibility
+
+Peer dependency allows VitePress 1.x and 2.0 alpha: `^1.0.0 || ^2.0.0-alpha.0`.
+
+Tested locally against VitePress `2.0.0-alpha.21` on Node 22:
+
+| Package manager | Install | Build |
+| --- | --- | --- |
+| npm 10 | ✅ | ✅ |
+| pnpm 11.25 | ✅ | ✅ |
+| yarn 1.22 (classic) | ✅ | ✅ |
+| bun 1.4 | ✅ | ✅ |
+| deno 2.9 | ✅ `deno install` | ❌ fails while Vite/rolldown loads the config |
+
+Deno can install the npm dependency, but building a VitePress site with Deno currently fails inside rolldown (`stream did not contain valid UTF-8`). Use Node for builds.
+
+## Notes
+
+- Batch ZIP downloads files through `raw_url` (OpenList `/p/` proxy), which keeps CORS on the OpenList origin.
+- Select-all only counts already-loaded files; the footer reports how many folders are still collapsed.
+- Directory listings are requested with `per_page: 0` (all entries). Very large folders may be slow; pagination is not implemented yet.
+
+## Development
+
+```bash
+npm install
+npm run build       # dist/node, dist/client/ssr, dist/client/browser, style.css
+npm run typecheck
+npm test            # Vitest: utils + locale helpers
+npm run pack:check
+```
+
+The demo site in `demo/` installs the package through `file:..`:
+
+```bash
+cd demo
+npm install
+npm run build
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,179 @@
+import { EnhanceAppContext } from "vitepress/client";
+type FileListLocale = 'zh-CN' | 'en-US';
+interface FileListLabels {
+  allFiles: string;
+  demoBadge: string;
+  filter: string;
+  refresh: string;
+  batch: string;
+  batchCount: string;
+  batching: string;
+  passwordPrompt: string;
+  passwordPlaceholder: string;
+  open: string;
+  columnName: string;
+  columnSize: string;
+  columnDate: string;
+  loading: string;
+  loadFailed: string;
+  guestHint: string;
+  corsHint: string;
+  retry: string;
+  empty: string;
+  preview: string;
+  download: string;
+  loaded: string;
+  selected: string;
+  unloaded: string;
+  folderFailed: string;
+  demoDownload: string;
+  demoPreview: string;
+  demoBatch: string;
+  downloadFailed: string;
+  previewFailed: string;
+  batchFailed: string;
+  defaultZip: string;
+}
+interface FileListProps {
+  /** OpenList base URL, e.g. `https://pan.example.com`. Empty string enables demo mode. */
+  base?: string;
+  /** Initial directory, defaults to `/`. */
+  path?: string;
+  /** Optional read-only token. Guest access is used when omitted. */
+  token?: string;
+  /** Folder password. The component also asks at runtime when OpenList reports one. */
+  password?: string;
+  /** Toolbar title. Falls back to `site_title` from `/api/public/settings`. */
+  title?: string;
+  /** Built-in locale. Defaults to `zh-CN`. */
+  locale?: FileListLocale;
+  /** Per-key label overrides on top of the locale preset. */
+  labels?: Partial<FileListLabels>;
+}
+/** Shape of one entry returned by `POST /api/fs/list`. */
+interface OpenListEntry {
+  name: string;
+  size: number;
+  is_dir: boolean;
+  modified: string;
+  created?: string;
+  sign?: string;
+  thumb?: string;
+  type?: number;
+}
+declare const _default: import("vue").DefineComponent<FileListProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<FileListProps> & Readonly<{}>, {
+  base: string;
+  path: string;
+  token: string;
+  password: string;
+  title: string;
+  locale: FileListLocale;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare global {
+  const __VLS_intrinsicElements: __VLS_IntrinsicElements;
+  const __VLS_directiveBindingRestFields: {
+    instance: null;
+    oldValue: null;
+    modifiers: any;
+    dir: any;
+  };
+  const __VLS_unref: typeof import('vue').unref;
+  const __VLS_placeholder: any;
+  type __VLS_NativeElements = __VLS_SpreadMerge<SVGElementTagNameMap, HTMLElementTagNameMap>;
+  type __VLS_IntrinsicElements = import('vue/jsx-runtime').JSX.IntrinsicElements;
+  type __VLS_Element = import('vue/jsx-runtime').JSX.Element;
+  type __VLS_GlobalComponents = import('vue').GlobalComponents;
+  type __VLS_GlobalDirectives = import('vue').GlobalDirectives;
+  type __VLS_IsAny<T> = 0 extends 1 & T ? true : false;
+  type __VLS_PickNotAny<A, B> = __VLS_IsAny<A> extends true ? B : A;
+  type __VLS_SpreadMerge<A, B> = Omit<A, keyof B> & B;
+  type __VLS_WithComponent<N0 extends string, LocalComponents, Self, N1 extends string, N2 extends string, N3 extends string> = N1 extends keyof LocalComponents ? N1 extends N0 ? Pick<LocalComponents, N0 extends keyof LocalComponents ? N0 : never> : { [K in N0]: LocalComponents[N1]; } : N2 extends keyof LocalComponents ? N2 extends N0 ? Pick<LocalComponents, N0 extends keyof LocalComponents ? N0 : never> : { [K in N0]: LocalComponents[N2]; } : N3 extends keyof LocalComponents ? N3 extends N0 ? Pick<LocalComponents, N0 extends keyof LocalComponents ? N0 : never> : { [K in N0]: LocalComponents[N3]; } : Self extends object ? { [K in N0]: Self; } : N1 extends keyof __VLS_GlobalComponents ? N1 extends N0 ? Pick<__VLS_GlobalComponents, N0 extends keyof __VLS_GlobalComponents ? N0 : never> : { [K in N0]: __VLS_GlobalComponents[N1]; } : N2 extends keyof __VLS_GlobalComponents ? N2 extends N0 ? Pick<__VLS_GlobalComponents, N0 extends keyof __VLS_GlobalComponents ? N0 : never> : { [K in N0]: __VLS_GlobalComponents[N2]; } : N3 extends keyof __VLS_GlobalComponents ? N3 extends N0 ? Pick<__VLS_GlobalComponents, N0 extends keyof __VLS_GlobalComponents ? N0 : never> : { [K in N0]: __VLS_GlobalComponents[N3]; } : { [K in N0]: unknown; };
+  type __VLS_FunctionalComponentProps<T, K> = '__ctx' extends keyof __VLS_PickNotAny<K, {}> ? K extends {
+    __ctx?: {
+      props?: infer P;
+    };
+  } ? NonNullable<P> : never : T extends ((props: infer P, ...args: any) => any) ? P : {};
+  type __VLS_IsFunction<T, K> = K extends keyof T ? __VLS_IsAny<T[K]> extends false ? unknown extends T[K] ? false : true : false : false;
+  type __VLS_NormalizeComponentEvent<Props, Events, onEvent extends keyof Props, Event extends keyof Events, CamelizedEvent extends keyof Events> = (__VLS_IsFunction<Props, onEvent> extends true ? Props : __VLS_IsFunction<Events, Event> extends true ? { [K in onEvent]?: Events[Event]; } : __VLS_IsFunction<Events, CamelizedEvent> extends true ? { [K in onEvent]?: Events[CamelizedEvent]; } : Props) & Record<string, unknown>;
+  type __VLS_UnionToIntersection<U> = (U extends unknown ? (arg: U) => unknown : never) extends ((arg: infer P) => unknown) ? P : never;
+  type __VLS_OverloadUnionInner<T, U = unknown> = U & T extends ((...args: infer A) => infer R) ? U extends T ? never : __VLS_OverloadUnionInner<T, Pick<T, keyof T> & U & ((...args: A) => R)> | ((...args: A) => R) : never;
+  type __VLS_OverloadUnion<T> = Exclude<__VLS_OverloadUnionInner<(() => never) & T>, T extends (() => never) ? never : () => never>;
+  type __VLS_ConstructorOverloads<T> = __VLS_OverloadUnion<T> extends (infer F) ? F extends ((event: infer E, ...args: infer A) => any) ? { [K in E & string]: (...args: A) => void; } : never : never;
+  type __VLS_NormalizeEmits<T> = __VLS_PrettifyGlobal<__VLS_UnionToIntersection<__VLS_ConstructorOverloads<T> & { [K in keyof T]: T[K] extends any[] ? {
+    (...args: T[K]): void;
+  } : never; }>>;
+  type __VLS_PrettifyGlobal<T> = { [K in keyof T]: T[K]; } & {};
+  type __VLS_PickFunctionalComponentCtx<T, K> = NonNullable<__VLS_PickNotAny<'__ctx' extends keyof __VLS_PickNotAny<K, {}> ? K extends {
+    __ctx?: infer Ctx;
+  } ? Ctx : never : any, T extends ((props: any, ctx: infer Ctx) => any) ? Ctx : any>>;
+  type __VLS_UseTemplateRef<T> = Readonly<import('vue').ShallowRef<T | null>>;
+  function __VLS_getVForSourceType<T extends number | string | any[] | Iterable<any>>(source: T): [item: T extends number ? number : T extends string ? string : T extends any[] ? T[number] : T extends Iterable<infer T1> ? T1 : any, index: number][];
+  function __VLS_getVForSourceType<T>(source: T): [item: T[keyof T], key: keyof T, index: number][];
+  function __VLS_getSlotParams<T>(slot: T): Parameters<__VLS_PickNotAny<NonNullable<T>, (...args: any[]) => any>>;
+  function __VLS_getSlotParam<T>(slot: T): Parameters<__VLS_PickNotAny<NonNullable<T>, (...args: any[]) => any>>[0];
+  function __VLS_asFunctionalDirective<T>(dir: T): T extends import('vue').ObjectDirective ? NonNullable<T['created' | 'beforeMount' | 'mounted' | 'beforeUpdate' | 'updated' | 'beforeUnmount' | 'unmounted']> : T extends ((...args: any) => any) ? T : (arg1: unknown, arg2: unknown, arg3: unknown, arg4: unknown) => void;
+  function __VLS_makeOptional<T>(t: T): { [K in keyof T]?: T[K]; };
+  function __VLS_asFunctionalComponent<T, K = T extends (new (...args: any) => any) ? InstanceType<T> : unknown>(t: T, instance?: K): T extends (new (...args: any) => any) ? (props: (K extends {
+    $props: infer Props;
+  } ? Props : any) & Record<string, unknown>, ctx?: any) => __VLS_Element & {
+    __ctx?: {
+      attrs?: any;
+      slots?: K extends {
+        $slots: infer Slots;
+      } ? Slots : any;
+      emit?: K extends {
+        $emit: infer Emit;
+      } ? Emit : any;
+      expose?(exposed: K): void;
+      props?: (K extends {
+        $props: infer Props;
+      } ? Props : any) & Record<string, unknown>;
+    };
+  } : T extends (() => any) ? (props: {}, ctx?: any) => ReturnType<T> : T extends ((...args: any) => any) ? T : (_: {} & Record<string, unknown>, ctx?: any) => {
+    __ctx?: {
+      attrs?: any;
+      expose?: any;
+      slots?: any;
+      emit?: any;
+      props?: {} & Record<string, unknown>;
+    };
+  };
+  function __VLS_functionalComponentArgsRest<T extends (...args: any) => any>(t: T): 2 extends Parameters<T>['length'] ? [any] : [];
+  function __VLS_asFunctionalElement<T>(tag: T, endTag?: T): (attrs: T & Record<string, unknown>) => void;
+  function __VLS_asFunctionalSlot<S>(slot: S): S extends (() => infer R) ? (props: {}) => R : NonNullable<S>;
+  function __VLS_tryAsConstant<const T>(t: T): T;
+}
+export declare const fileListLocales: Record<FileListLocale, FileListLabels>;
+export declare function formatLabel(template: string, values?: Record<string, string | number>): string;
+export declare function resolveLabels(locale?: FileListLocale, overrides?: Partial<FileListLabels>): FileListLabels;
+export interface SortableNode {
+  name: string;
+  size: number;
+  is_dir: boolean;
+  modified: string;
+}
+export type SortKey = 'name' | 'size' | 'modified';
+export declare function joinPath(parent: string, name: string): string;
+export declare function encodePath(path: string): string;
+export declare function formatSize(size: number): string;
+export declare function formatDate(iso: string): string;
+export declare function extOf(name: string): string;
+export declare function compareNodes(a: SortableNode, b: SortableNode, key: SortKey, ascending?: boolean): number;
+/**
+ * Register `<FileList>` and `<VPFileList>` globally.
+ *
+ * ```ts
+ * // .vitepress/theme/index.ts
+ * import DefaultTheme from 'vitepress/theme'
+ * import { enhanceAppWithFileList } from 'vitepress-plugin-filelist/client'
+ *
+ * export default {
+ *   extends: DefaultTheme,
+ *   enhanceApp(ctx) {
+ *     enhanceAppWithFileList(ctx)
+ *   },
+ * }
+ * ```
+ */
+export declare function enhanceAppWithFileList({ app }: EnhanceAppContext): void;
+export { _default as FileList, _default as VPFileList, type FileListLabels, type FileListLocale, type FileListProps, type OpenListEntry };