@zhaoxiangjun/base44-document 0.1.0

package/dist/types/document.d.ts

@@ -0,0 +1,59 @@
+import { ReactNode } from 'react';
+export type DocumentPreviewKind = "markdown" | "pdf" | "excel" | "docx" | "text" | "unsupported";
+export type DocumentSource = {
+    name: string;
+    url?: string;
+    file?: File | Blob;
+    mimeType?: string;
+    extension?: string;
+};
+export type DocumentViewerMessages = {
+    title: string;
+    loading: string;
+    emptyTitle: string;
+    emptyDescription: string;
+    errorTitle: string;
+    unsupportedTitle: string;
+    unsupportedDescription: string;
+    openExternal: string;
+    download: string;
+    sheetLabel: string;
+    rowsLabel: string;
+    columnsLabel: string;
+    docFallback: string;
+    pdfFallback: string;
+};
+export type DocumentLoadState = {
+    kind: DocumentPreviewKind;
+    objectUrl?: string;
+    html?: string;
+    text?: string;
+    sheets?: DocumentSheet[];
+    error?: string;
+};
+export type DocumentSheet = {
+    name: string;
+    rows: string[][];
+};
+export type DocumentViewerClassNames = {
+    root?: string;
+    toolbar?: string;
+    content?: string;
+    viewport?: string;
+};
+export type DocumentViewerProps = {
+    source?: DocumentSource | null;
+    className?: string;
+    classNames?: DocumentViewerClassNames;
+    height?: number | string;
+    maxRows?: number;
+    messages?: Partial<DocumentViewerMessages>;
+    actions?: ReactNode;
+    onOpenExternal?: (source: DocumentSource) => void;
+    onDownload?: (source: DocumentSource) => void;
+    onError?: (error: Error) => void;
+};
+export type DocumentPreviewDialogProps = DocumentViewerProps & {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+};

package/dist/utils/cn.d.ts

@@ -0,0 +1,2 @@
+import { ClassValue } from 'clsx';
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/utils/documentActions.d.ts

@@ -0,0 +1,4 @@
+import { DocumentSource } from '../types/document';
+export declare function createDocumentId(file: File): string;
+export declare function openDocumentExternal(source: DocumentSource): void;
+export declare function downloadDocumentSource(source: DocumentSource): void;

package/dist/utils/documentIcons.d.ts

@@ -0,0 +1,2 @@
+import { DocumentSource } from '../types/document';
+export declare function getDocumentIcon(source: DocumentSource): import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;

package/dist/utils/documentTypes.d.ts

@@ -0,0 +1,4 @@
+import { DocumentPreviewKind, DocumentSource } from '../types/document';
+export declare function getDocumentExtension(source: DocumentSource): string;
+export declare function resolveDocumentKind(source: DocumentSource): DocumentPreviewKind;
+export declare function canOpenDocumentExternally(source: DocumentSource | null | undefined): boolean;

package/dist/utils/excel.d.ts

@@ -0,0 +1,7 @@
+import { DocumentSheet } from '../types/document';
+import * as XLSX from "xlsx";
+export declare function getSheetStats(sheet: DocumentSheet): {
+    rowCount: number;
+    columnCount: number;
+};
+export declare function workbookToSheets(workbook: XLSX.WorkBook, maxRows: number): DocumentSheet[];

package/dist/utils/format.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveSizeValue(value: number | string | undefined): string | undefined;
+export declare function formatFileSize(size: number): string;

package/dist/utils/readDocumentSource.d.ts

@@ -0,0 +1,4 @@
+import { DocumentSource } from '../types/document';
+export declare function readDocumentArrayBuffer(source: DocumentSource): Promise<ArrayBuffer>;
+export declare function readDocumentText(source: DocumentSource): Promise<string>;
+export declare function createDocumentObjectUrl(source: DocumentSource): string | undefined;

package/docs/base44-usage.md

@@ -0,0 +1,200 @@
+# Base44 使用说明
+
+> 这份文档给 Base44 App、Base44 AI Controls 和开发者使用。  
+> Base44 使用 `@zhaoxiangjun/base44-document` 时，只需要优先阅读这一份文档。
+
+## 1. 包信息
+
+```text
+package: @zhaoxiangjun/base44-document
+current: 0.1.0
+```
+
+Base44 App 通过 npm registry 安装，不使用 git 依赖。
+
+```json
+{
+  "dependencies": {
+    "@zhaoxiangjun/base44-document": "^0.1.0"
+  }
+}
+```
+
+入口文件引入样式：
+
+```tsx
+import "@zhaoxiangjun/base44-ui/styles.css";
+import "@zhaoxiangjun/base44-document/styles.css";
+```
+
+组件引入：
+
+```tsx
+import { DocumentPreviewDialog, DocumentViewer } from "@zhaoxiangjun/base44-document";
+```
+
+## 2. 使用边界
+
+这个包只负责浏览器端文档预览 UI，不负责业务请求和 Base44 平台调用。
+
+```text
+可以做：接收 File、Blob、URL，识别文档类型，渲染预览界面。
+不可以做：调用 base44.entities、base44.auth、base44.functions.invoke、保存密钥、拼接业务接口。
+```
+
+业务请求必须留在当前 Base44 App 的 `src/api`、`src/hooks`、`src/lib`、页面容器或 Backend Functions 中。
+
+## 3. 支持格式
+
+| 格式 | 支持方式 |
+|------|----------|
+| `.md` / `.markdown` | `marked` 渲染 HTML |
+| `.pdf` | 浏览器 iframe/object URL 预览 |
+| `.xlsx` / `.xls` / `.csv` | `xlsx` 读取并展示 Sheet 表格 |
+| `.docx` | `mammoth` 转 HTML |
+| `.txt` / `.json` / `.xml` / `.log` | 纯文本预览 |
+| `.doc` | 浏览器端不解析，显示外部打开或下载提示 |
+
+说明：
+
+```text
+这里的 Word 预览支持 DOCX，不支持旧版二进制 DOC 解析。
+DOCX 转 HTML 适合正文预览，不保证完整还原 Word 页眉页脚、批注、复杂版式。
+```
+
+## 4. DocumentViewer
+
+```tsx
+<DocumentViewer
+  source={{
+    name: file.name,
+    file,
+    mimeType: file.type
+  }}
+  height={560}
+  maxRows={100}
+  messages={documentMessages}
+  onError={handlePreviewError}
+/>
+```
+
+关键 props：
+
+```text
+source?: DocumentSource | null
+height?: number | string
+maxRows?: number
+messages?: Partial<DocumentViewerMessages>
+actions?: ReactNode
+onOpenExternal?: (source: DocumentSource) => void
+onDownload?: (source: DocumentSource) => void
+onError?: (error: Error) => void
+```
+
+`DocumentSource`：
+
+```ts
+type DocumentSource = {
+  name: string;
+  url?: string;
+  file?: File | Blob;
+  mimeType?: string;
+  extension?: string;
+};
+```
+
+说明：
+
+```text
+file 优先用于用户本地选择文件、上传前预览和 Blob 预览。
+url 用于已经存在的远程文件，远程文件必须允许浏览器跨域读取。
+PDF 使用 url 或 object URL 交给浏览器渲染。
+Excel 默认最多渲染 100 行，可通过 maxRows 调整。
+```
+
+本地文件选择示例：
+
+```tsx
+function LocalDocumentPreview() {
+  const [source, setSource] = useState<DocumentSource | null>(null);
+
+  function handleFileChange(event: React.ChangeEvent<HTMLInputElement>) {
+    const file = event.target.files?.[0];
+    if (!file) return;
+
+    setSource({
+      name: file.name,
+      file,
+      mimeType: file.type
+    });
+  }
+
+  return (
+    <>
+      <input
+        type="file"
+        accept=".md,.markdown,.pdf,.csv,.xls,.xlsx,.doc,.docx,.txt,.json,.xml"
+        onChange={handleFileChange}
+      />
+      <DocumentViewer source={source} height={560} />
+    </>
+  );
+}
+```
+
+## 5. DocumentPreviewDialog
+
+```tsx
+<DocumentPreviewDialog
+  open={open}
+  onOpenChange={setOpen}
+  source={currentDocument}
+  height="min(70vh, 680px)"
+/>
+```
+
+弹窗使用 `@zhaoxiangjun/base44-ui` 的 `DialogFrame`，适合文件列表、任务结果和附件管理中的快速预览。
+
+## 6. 可复用导出
+
+除完整预览组件外，本包也导出内部拆分后的基础能力，便于后续项目按需组合。
+
+| 类型 | 导出 |
+|------|------|
+| 子组件 | `DocumentToolbar` / `DocumentContent` / `ExcelPreview` |
+| Hook | `useDocumentPreview` |
+| 常量 | `ACCEPTED_DOCUMENT_TYPES` / `DEFAULT_MAX_ROWS` |
+| 类型识别 | `resolveDocumentKind` / `getDocumentExtension` / `canOpenDocumentExternally` |
+| 文件动作 | `createDocumentId` / `openDocumentExternal` / `downloadDocumentSource` |
+| 格式化 | `formatFileSize` / `resolveSizeValue` |
+| Excel 工具 | `workbookToSheets` / `getSheetStats` |
+| 图标工具 | `getDocumentIcon` |
+
+推荐仍优先使用 `DocumentViewer`；只有需要自定义工具栏、内容区或文件列表时再组合这些基础能力。
+
+## 7. 文案和 i18n
+
+默认文案为英文。Base44 App 应从自己的 i18n / locale 层传入 `messages`。
+
+```tsx
+const documentMessages = {
+  title: t("document.preview.title"),
+  loading: t("document.preview.loading"),
+  emptyTitle: t("document.preview.emptyTitle"),
+  emptyDescription: t("document.preview.emptyDescription"),
+  errorTitle: t("document.preview.errorTitle"),
+  unsupportedTitle: t("document.preview.unsupportedTitle"),
+  unsupportedDescription: t("document.preview.unsupportedDescription"),
+  openExternal: t("common.open"),
+  download: t("common.download")
+};
+```
+
+## 8. 移动端要求
+
+```text
+预览容器必须给定稳定高度，例如 height={560} 或 height="70vh"。
+Excel 表格会横向滚动，不应强行压缩列宽到不可读。
+PDF 预览依赖移动浏览器能力，必要时展示打开按钮。
+弹窗宽度自适应 94vw，内容区滚动在组件内部处理。
+```

package/docs/fun/document-preview.md

@@ -0,0 +1,64 @@
+# 文档预览功能说明
+
+## 1. 设计目标
+
+本包聚合常见文档预览能力，让 Base44 App 只需要传入 `DocumentSource`，即可获得统一的预览容器和弹窗。
+
+## 2. 数据入口
+
+```ts
+type DocumentSource = {
+  name: string;
+  url?: string;
+  file?: File | Blob;
+  mimeType?: string;
+  extension?: string;
+};
+```
+
+优先级：
+
+```text
+mimeType 用于快速判断类型
+extension 用于无 MIME 的业务文件
+name 后缀作为兜底
+file 用于本地 Blob 读取
+url 用于远程文件读取或 PDF 打开
+```
+
+## 3. 渲染策略
+
+```text
+Markdown：读取 text 后通过 marked 转 HTML
+PDF：file 转 object URL，url 直接 iframe
+Excel/CSV：读取 ArrayBuffer 后通过 xlsx 解析 Sheet
+DOCX：读取 ArrayBuffer 后通过 mammoth 转 HTML
+Text：读取 text 后用 pre 展示
+Unsupported：展示不支持提示和外部打开/下载入口
+```
+
+## 4. 风险和边界
+
+```text
+远程 URL 读取受 CORS 限制。
+PDF 渲染依赖浏览器内置 PDF 能力。
+DOCX 转 HTML 不等于完整 Word 排版还原。
+旧版二进制 DOC 暂不做浏览器端解析。
+XLSX 大文件会消耗浏览器内存，默认限制展示行数。
+旧版 .doc 不做浏览器端解析。
+```
+
+## 5. 模块拆分
+
+```text
+DocumentViewer：组合预览状态、工具栏、内容区和事件回调。
+DocumentToolbar：文件名、外部打开、下载和自定义 actions。
+DocumentContent：加载、错误、空状态和不同文档类型渲染。
+ExcelPreview：Sheet 切换、表格渲染和行列统计。
+useDocumentPreview：读取 source 并输出标准 DocumentLoadState。
+utils/excel：Excel workbook 到 DocumentSheet 的转换。
+utils/documentActions：打开、下载、本地文件 id。
+utils/documentIcons：按文档类型选择 lucide 图标。
+utils/format：尺寸和文件大小格式化。
+constants/documentConstants：默认行数和 input accept 类型。
+```

package/docs/local-display.md

@@ -0,0 +1,36 @@
+# 本地展示说明
+
+本项目内置 Vite playground，用于验证 `DocumentViewer` 和 `DocumentPreviewDialog`。
+
+## 1. 启动
+
+```bash
+cd react_base44_document
+npm install
+npm run dev
+```
+
+打开 Vite 输出的本地地址。当前 playground 的第一入口是本地文件选择器。
+
+## 2. 覆盖场景
+
+```text
+本地 Markdown 文件预览
+本地 CSV / XLS / XLSX 文件预览
+本地 PDF 文件预览
+本地 DOCX 文件预览
+本地 DOC 不支持提示
+弹窗预览
+打开/下载按钮状态
+移动端窄屏布局
+```
+
+## 3. 同步要求
+
+组件新增 props、支持格式、样式依赖或使用边界变更时，必须同步更新：
+
+```text
+docs/base44-usage.md
+docs/project-status.md
+README.md
+```

package/docs/logs/2026-06-30-initial-document-package.md

@@ -0,0 +1,24 @@
+# 2026-06-30 初始化文档预览包
+
+## 内容
+
+```text
+创建 react_base44_document
+新增 @zhaoxiangjun/base44-document npm 包配置
+新增 DocumentViewer / DocumentPreviewDialog
+新增 useDocumentPreview Hook
+新增 Markdown、PDF、Excel/CSV、DOCX、文本预览策略
+新增本地文件选择 playground 和 npm 标准库文档
+```
+
+## 验证
+
+```text
+npm install：已通过，prepare 自动构建成功。
+npm run typecheck：已通过。
+npm run build：已通过。
+npm pack --dry-run：已通过。
+本地 playground：http://localhost:5191/ 已启动并通过浏览器检查，支持选择本机文件预览，控制台无 error/warn。
+PDF 预览高度：已修复 DocumentViewer 内容区被 flex-1 压缩的问题。
+公共复用重构：提取 DocumentToolbar、DocumentContent、ExcelPreview、documentActions、documentIcons、excel、format、documentConstants。
+```

package/docs/npm-package.md

@@ -0,0 +1,45 @@
+# npm 包维护说明
+
+## 1. 包信息
+
+```text
+package: @zhaoxiangjun/base44-document
+current: 0.1.0
+```
+
+## 2. 构建验证
+
+发布前必须运行：
+
+```bash
+npm run typecheck
+npm run build
+npm pack --dry-run
+```
+
+## 3. 版本规则
+
+```text
+修复内部实现且不改 API：patch
+新增兼容组件、Hook、props：minor
+移除或修改公开 API：major
+```
+
+## 4. 发布
+
+发布前设置 `NPM_TOKEN`：
+
+```bat
+set NPM_TOKEN=your_token
+publish-npm.bat
+```
+
+脚本会临时创建 `.npmrc`，发布结束后删除，并通过 `npm view` 校验 registry 上的版本。
+
+## 5. 发布后检查
+
+```bash
+npm view @zhaoxiangjun/base44-document@0.1.0 version --registry=https://registry.npmjs.org/
+```
+
+随后在 Base44 App 或本地展示项目中通过 npm 包名安装验证，不使用本地路径作为发布后验证方式。

package/docs/project-status.md

@@ -0,0 +1,66 @@
+# react_base44_document 项目状态
+
+## 1. 当前定位
+
+`react_base44_document` 是 npm 标准库项目，包名为 `@zhaoxiangjun/base44-document`。  
+它为 Base44 React App 和本地 React 项目提供浏览器端文档预览能力。
+
+## 2. 当前能力
+
+```text
+DocumentViewer：内嵌文档预览容器
+DocumentPreviewDialog：弹窗预览
+useDocumentPreview：文档读取和转换 Hook
+resolveDocumentKind：文档类型识别工具
+Markdown：marked 渲染
+PDF：iframe + object URL 预览
+Excel/CSV：xlsx 读取 Sheet 并展示表格
+DOCX：mammoth 转 HTML
+文本：pre 预览
+legacy .doc：外部打开/下载提示
+playground：本地文件选择后预览
+```
+
+## 3. 本轮修改
+
+```text
+创建 react_base44_document 项目
+建立 Vite library npm 包结构
+新增核心组件、Hook、类型和工具函数
+新增本地文件选择 playground
+新增 README 与 docs/base44-usage.md、local-display.md、npm-package.md、project-status.md
+新增 docs/fun 和 docs/logs 记录
+新增 publish-npm.bat
+提取 DocumentToolbar、DocumentContent、ExcelPreview 子组件
+提取 documentActions、documentIcons、format、excel、documentConstants 公共模块
+```
+
+## 4. 依赖
+
+```text
+react / react-dom：peer dependencies
+@zhaoxiangjun/base44-ui：公共 UI 复用
+lucide-react：图标
+marked：Markdown 渲染
+xlsx：Excel/CSV 读取
+mammoth：DOCX 转 HTML
+clsx / tailwind-merge：className 合并
+```
+
+## 5. 验证状态
+
+```text
+typecheck：已通过，npm run typecheck
+build：已通过，npm run build
+npm pack --dry-run：已通过，生成 zhaoxiangjun-base44-document-0.1.0.tgz 预检信息
+本地 playground：已通过，http://localhost:5191/ 可访问，支持从本机选择文件预览，浏览器控制台无 error/warn
+PDF 高度修复：DocumentViewer 内容区按 height 固定占位，避免 iframe 被 flex-1 压缩
+公共复用重构：已通过，DocumentViewer 仅保留状态组合和事件分发
+```
+
+## 6. 发布状态
+
+```text
+当前版本：0.1.0
+当前状态：本地初始化完成，尚未发布 npm
+```

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@zhaoxiangjun/base44-document",
+  "private": false,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "React document preview components for Base44 apps and local React projects.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./dist/base44-document.css"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "vite --host 0.0.0.0",
+    "build": "tsc -p ./tsconfig.build.json && vite build",
+    "typecheck": "tsc -p ./tsconfig.json --noEmit",
+    "preview": "vite preview --host 0.0.0.0",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@zhaoxiangjun/base44-ui": "^0.1.5",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.468.0",
+    "mammoth": "^1.8.0",
+    "marked": "^14.1.3",
+    "tailwind-merge": "^2.5.5",
+    "xlsx": "^0.18.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.5",
+    "vite-plugin-dts": "^4.4.0"
+  }
+}