dock-spreadsheet 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AKS1st
+
+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.en.md

@@ -0,0 +1,108 @@
+# dock-spreadsheet
+
+[简体中文](README.md) · [English](README.en.md)
+
+[![npm version](https://img.shields.io/npm/v/dock-spreadsheet.svg)](https://www.npmjs.com/package/dock-spreadsheet) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![Node.js ≥20](https://img.shields.io/badge/Node.js-%E2%89%A520-43853d)
+
+**A read-only spreadsheet viewer for [dock-files](https://github.com/AKS1st/dock-files).** Open XLSX, XLS, ODS, CSV and TSV files inside the [dock](https://github.com/AKS1st/dock) workbench without uploading them to an external service. Parsing, virtual scrolling and grid interactions use [SheetJS CE](https://docs.sheetjs.com/), [Papa Parse](https://www.papaparse.com/) and [Tabulator](https://tabulator.info/). No runtime CDN requests are required.
+
+> **Scope: read-only preview.** The plugin does not edit or save files, evaluate formulas, run macros, or reproduce source fonts, colors, merged cells, charts or print layouts.
+
+## Screenshots
+
+These screenshots come from an actual isolated `dsh web` + Chromium run using a synthetic workbook. They show only the viewer, with the workspace and conversation UI cropped out.
+
+![Read-only spreadsheet viewer with sheet tabs, selected cell and data grid](assets/spreadsheet-viewer.png)
+
+<details>
+<summary>View column filtering</summary>
+
+![Filtered column with the matching row and visible-row count](assets/spreadsheet-filter.png)
+
+</details>
+
+<details>
+<summary>View the compact 360px window</summary>
+
+![Spreadsheet viewer in a narrow floating window](assets/spreadsheet-compact.png)
+
+</details>
+
+## Features
+
+- **Common file types:** dock-files dispatches `.xlsx`, `.xls`, `.ods`, `.csv` and `.tsv` to the viewer. Switch worksheets using bottom tabs, including arrow keys and Home/End.
+- **Familiar grid:** lettered columns, frozen actual row numbers, fine gridlines and a selected-cell outline. A read-only inspector displays the cell address and text; hover over truncated values to see the full text. The first row stays data; no header inference.
+- **Find and filter:** search across the current worksheet's data columns, click a column header to sort, and reveal per-column header filters on demand. Hiding the filter controls clears column filters so no invisible constraint remains. The footer displays visible / preview rows and column count.
+- **Link navigation:** recognise `http://`, `https://` and `www.` in cells. **Ctrl+click** (or **⌘+click** on macOS) opens a new tab; a plain click only selects the cell. Bare domains and email addresses are not auto-linked.
+- **Large-sheet preview:** Tabulator's virtual rendering limits DOM nodes to visible rows. Sheet tabs can scroll horizontally in a narrow floating window, where secondary toolbar hints are hidden.
+- **Coordinate fidelity:** keep the original column letters and row numbers for sheets starting at an offset such as `C3`; empty cells remain empty.
+
+## Installation
+
+Requires DSH Web, Node.js ≥20, and the enabled [`dock-base`](https://github.com/AKS1st/dock) and [`dock-files`](https://github.com/AKS1st/dock-files) plugins. **Install all three as top-level plugins in this order:** downloading a base package as a dependency alone does not mount its bundle.
+
+### npm (recommended)
+
+```sh
+dsh plugin --profile web add dock-base
+dsh plugin --profile web add dock-files
+dsh plugin --profile web add dock-spreadsheet
+```
+
+### GitHub (alternative)
+
+```sh
+dsh plugin --profile web add github:AKS1st/dock
+dsh plugin --profile web add github:AKS1st/dock-files
+dsh plugin --profile web add github:AKS1st/dock-spreadsheet
+```
+
+For local development, use `dsh plugin --profile web add link:/absolute/path/to/dock-spreadsheet`. **After installing or updating, restart dsh web yourself** to ensure the new bundle takes effect; the plugin never restarts your process. The Web profile's `node_modules/dock-spreadsheet` must resolve—merely listing its name as a bundle is not an installation. If the profile is on a read-only mount, make that directory writable before installing.
+
+## Usage
+
+1. Open a supported file in the dock-files explorer. The viewer appears in a dock floating window; it does not add a separate activity-bar item.
+2. Click a data cell to inspect its original worksheet coordinate and text (hover over a long value to see it in full). Ctrl/⌘+click a detected link to open it in a new tab.
+3. Search to filter the current worksheet; click a column header to sort; press the column-filter button to show or hide header inputs. Search and column filtering can be combined.
+4. Click a worksheet tab to switch sheets, or focus a tab and use ←/→ or Home/End. Switching clears the previous cell selection.
+
+## Formats, limits and security
+
+| Topic | Actual behavior |
+| --- | --- |
+| Excel / OpenDocument | SheetJS CE 0.20.3 reads `.xlsx`, `.xls` and `.ods`; cached/formatted cell text is displayed without recalculating formulas. |
+| Delimited text | Papa Parse reads `.csv` and `.tsv` using strict UTF-8 decoding; invalid encoding reports an error. The first row remains data. |
+| Preview window | At most **5,000 rows and 256 columns** from each worksheet's used range; the footer marks truncated previews. |
+| File access | The Host exposes only `POST /dock-spreadsheet/read` for raw bytes. It checks same-origin/trusted-host requests, absolute path, allowed extension, regular file and a **20 MiB** limit. There is no write API. |
+| Workspace boundary | Like other dock viewers, the Host may read an **absolute path outside the workspace** referenced by the session. Do not deploy this plugin on an untrusted or publicly reachable Host. |
+| Cell rendering | Treat workbook content as untrusted: render via DOM text nodes / `textContent`, never `innerHTML`; `<b>` in a cell stays text. Detected links use only HTTP(S) and open with `noopener,noreferrer`. |
+| Performance | Virtual scrolling reduces DOM work, but parsing still runs on the browser main thread; a complex workbook near the limits may briefly pause the UI. |
+
+This is not a full spreadsheet engine: no editing, saving, collaboration, formula evaluation, macro execution, chart rendering, source-style/merged-cell fidelity or automatic encoding detection for non-UTF-8 CSV.
+
+## Development and verification
+
+```sh
+pnpm install
+pnpm run check   # embed Tabulator styles and check TypeScript
+pnpm test        # build Host / Client and run 18 tests
+pnpm run build   # produce lib/ for GitHub/npm distribution
+```
+
+Unit/integration tests cover all five formats, coordinates and preview limits, Host read guards, browser bundle registration, and a real React + Tabulator mount exercising search, sort, sheet tabs, column-filter controls, cell selection and link interactions. A real `dsh web` on a random port in an isolated container, driven by Chromium, passed **29/29 checks**, including 360px layout, column filtering, HTML-as-text and Ctrl+click. This does not claim that your current GUI has hot-reloaded, or that npm publication succeeded.
+
+The client artifact bundles SheetJS, Papa Parse, Tabulator and their styles; only platform React remains external in the browser. GitHub consumers use committed `lib/` files, without a consumer build step or `prepare`/`postinstall` script.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| A workbook still opens in the default text viewer | Confirm dock-base, dock-files and dock-spreadsheet are enabled as Web-profile bundles and their packages resolve. Restart dsh web yourself, then reopen the file. |
+| Install fails with `EROFS` | The Web profile's `node_modules` is on a read-only filesystem. Make the directory writable and reinstall rather than editing only the manifest. |
+| CSV/TSV encoding error | Convert the file to UTF-8. The viewer will not silently display a different encoding as garbled text. |
+| File rejected or data seems incomplete | Files over 20 MiB are rejected; each sheet previews at most 5,000 rows/256 columns. Check the footer for a truncated-preview indicator. |
+| Ctrl+click does not open a link | The cell must contain an `http(s)://` or `www.` prefix; click the link itself and check whether the browser blocked a new tab. |
+
+## License and acknowledgements
+
+[MIT](LICENSE). Thanks to [SheetJS CE](https://docs.sheetjs.com/), [Papa Parse](https://www.papaparse.com/) and [Tabulator](https://tabulator.info/).

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# dock-spreadsheet
 
-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.
+[English](README.en.md) · [简体中文](README.md)
+
+[![npm version](https://img.shields.io/npm/v/dock-spreadsheet.svg)](https://www.npmjs.com/package/dock-spreadsheet) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![Node.js ≥20](https://img.shields.io/badge/Node.js-%E2%89%A520-43853d)
+
+**为 [dock-files](https://github.com/AKS1st/dock-files) 提供只读在线表格查看器。** 在 [dock](https://github.com/AKS1st/dock) 工作台内打开 XLSX、XLS、ODS、CSV 和 TSV 文件，无需将文件上传到外部服务。使用成熟的 [SheetJS CE](https://docs.sheetjs.com/)、[Papa Parse](https://www.papaparse.com/) 和 [Tabulator](https://tabulator.info/) 实现解析、虚拟滚动与交互；没有 CDN 运行时依赖。
+
+> **范围声明：只读预览。** 本插件不编辑/保存文件，不计算公式或运行宏，也不复刻源文件的字体、颜色、合并单元格、图表或打印布局。
+
+## 效果预览
+
+以下图片来自隔离 `dsh web` + Chromium 实际运行，工作簿内容是虚构测试数据；截图已裁去工作区和会话界面。
+
+![只读表格查看器：工作表标签、选中单元格和数据网格](assets/spreadsheet-viewer.png)
+
+<details>
+<summary>查看列筛选效果</summary>
+
+![列筛选后仅显示匹配行和状态栏计数](assets/spreadsheet-filter.png)
+
+</details>
+
+<details>
+<summary>查看 360px 窄浮窗效果</summary>
+
+![窄浮窗中的表格查看器](assets/spreadsheet-compact.png)
+
+</details>
+
+## 功能
+
+- **表格格式**：自动接管 dock-files 中的 `.xlsx`、`.xls`、`.ods`、`.csv`、`.tsv` 文件；多工作表通过底部标签切换，支持方向键、Home/End。
+- **熟悉的网格**：字母列头、冻结的真实行号、细网格线、单元格选中高亮；信息栏展示选中单元格的坐标和纯文本，过长时悬停可查看完整值。第一行始终是数据，不猜测表头。
+- **查找和筛选**：跨当前工作表的数据列搜索；点击列头排序；按需展开每列的筛选框。收起列筛选时自动清空对应条件，避免隐藏筛选。底部显示可见行数 / 预览行数和列数。
+- **链接导航**：识别单元格文本中的 `http://`、`https://` 和 `www.`；**Ctrl+点击**（macOS 为 **⌘+点击**）在新标签页打开，普通点击只选中单元格。裸域名和邮箱不自动识别。
+- **大表预览**：Tabulator 虚拟滚动，仅渲染可见行；窄浮窗下标签可横向滚动，工具栏自动收起辅助提示。
+- **坐标保真**：保留偏移起始工作表的列字母与行号（例如 `C3`）；空白单元格保持为空。
+
+## 安装
+
+需要 DSH Web、Node.js ≥20，以及已启用的 [`dock-base`](https://github.com/AKS1st/dock) 和 [`dock-files`](https://github.com/AKS1st/dock-files)。**按顺序安装这三个顶层插件**；基础插件仅作为依赖下载并不等于自动挂载。
+
+### npm（推荐）
+
+```sh
+dsh plugin --profile web add dock-base
+dsh plugin --profile web add dock-files
+dsh plugin --profile web add dock-spreadsheet
+```
+
+### GitHub（备选）
+
+```sh
+dsh plugin --profile web add github:AKS1st/dock
+dsh plugin --profile web add github:AKS1st/dock-files
+dsh plugin --profile web add github:AKS1st/dock-spreadsheet
+```
+
+本地开发可用 `dsh plugin --profile web add link:/absolute/path/to/dock-spreadsheet`。**安装或更新插件后由你重启 dsh web** 才能保证新 bundle 生效；本插件不会自行重启进程。profile 的 `node_modules/dock-spreadsheet` 必须能解析，仅把名字写进 bundle 列表不足以安装；若 profile 位于只读挂载，先解决文件系统可写性。
+
+## 使用方法
+
+1. 在 dock-files 文件浏览器中打开受支持的表格文件，查看器会以 dock 浮窗打开。无需另外寻找活动栏入口。
+2. 点击任意数据单元格，在上方信息栏查看原始表格坐标及文本（过长时悬停查看完整值）。对链接使用 Ctrl/⌘+点击打开新标签页。
+3. 在搜索框输入文本以筛选当前工作表；点击列头排序；点击“筛选列”显示/收起列头筛选输入框。搜索与列筛选可同时生效。
+4. 点击底部工作表标签切换；键盘聚焦标签时可使用 ←/→、Home/End。切表后旧单元格选中态会清空。
+
+## 格式、边界与安全
+
+| 项目 | 实际行为 |
+| --- | --- |
+| Excel / OpenDocument | SheetJS CE 0.20.3 读取 `.xlsx`、`.xls`、`.ods`；显示单元格的格式化/缓存文本，不重新计算公式。 |
+| 分隔文本 | Papa Parse 读取 `.csv`、`.tsv`；严格 UTF-8 解码，编码不符时明确报错。第一行是数据而非自动表头。 |
+| 预览范围 | 每张表从已使用区域起最多预览 **5000 行、256 列**；超出范围在状态栏标记“预览受限”。 |
+| 文件访问 | Host 只提供 `POST /dock-spreadsheet/read` 原始字节读取，检查同源/可信主机、绝对路径、允许扩展名、常规文件及 **20 MiB** 上限；没有写入 API。 |
+| 工作区边界 | 与其他 dock 查看器一致，允许读取会话指向的**工作区外绝对路径**；请勿将插件装入不可信或公开可访问的 Host。 |
+| 内容渲染 | 工作簿内容按不可信数据处理：文本通过 DOM `textContent`/文本节点输出，不使用 `innerHTML`；`<b>` 等输入不会成为 HTML。检测到的链接只允许 `http(s)`，以 `noopener,noreferrer` 打开。 |
+| 性能 | 虚拟滚动降低 DOM 开销，但解析仍在浏览器主线程进行；接近上限的复杂工作簿可能短暂卡顿。 |
+
+本插件不是完整电子表格引擎：不提供编辑、保存、协同、公式求值、宏执行、图表、合并单元格样式复刻或非 UTF-8 CSV 自动猜测。
+
+## 开发与验证
+
+```sh
+pnpm install
+pnpm run check   # 生成内嵌 Tabulator 样式并检查 TypeScript
+pnpm test        # 构建 Host / Client 并运行 18 项测试
+pnpm run build   # 生成需随 GitHub/npm 发布的 lib/
+```
+
+单元/集成测试覆盖五种文件格式、坐标和预览上限、Host 读取防线、浏览器 bundle 注册，以及真实 React + Tabulator 挂载后的搜索、排序、切表、筛选按钮、单元格选中和链接交互。在独立容器中，以随机端口启动真实 `dsh web` 并驱动 Chromium，**29/29 项检查通过**（包括 360px 浮窗、列筛选、HTML 作为文本和 Ctrl+点击）。这不是对用户当前 GUI 热更新或 npm 发布状态的保证。
+
+客户端产物内置 SheetJS、Papa Parse、Tabulator 和样式；浏览器端只将平台提供的 React 保留为外部依赖。GitHub 安装使用仓库已提交的 `lib/`，不需要消费者运行构建脚本，也不声明 `prepare`/`postinstall`。
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| 文件仍被默认文本查看器打开 | 检查 dock-base、dock-files、dock-spreadsheet 均在 Web profile 的 bundle 列表且依赖可解析；由你重启 dsh web 后再打开。 |
+| 安装时报 `EROFS` | Web profile 的 `node_modules` 位于只读文件系统；使该目录可写后重新安装，不要只改清单。 |
+| CSV/TSV 编码错误 | 将输入转为 UTF-8；查看器不会将其他编码静默显示为乱码。 |
+| 文件太大或未显示全部数据 | 单文件不能超过 20 MiB；每张表最多预览 5000 行/256 列，留意底部“预览受限”。 |
+| Ctrl+点击没打开网页 | 确认单元格文本具有 `http(s)://` 或 `www.` 前缀、点击链接本身，且浏览器没有拦截新标签页。 |
+
+## 许可与致谢
+
+[MIT](LICENSE)。感谢 [SheetJS CE](https://docs.sheetjs.com/)、[Papa Parse](https://www.papaparse.com/) 与 [Tabulator](https://tabulator.info/) 项目。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dock-spreadsheet
+      name: 'dock-spreadsheet'