fatcms-clipboard-parser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fatcms-clipboard-parser 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

@@ -0,0 +1,49 @@
+# fatcms-clipboard-parser
+
+编辑器无关的 HTML 剪贴板解析工具。MIT 许可，公开可读 ES Module 源码，附 TypeScript 声明。无需 React、编辑器实例或全局变量。
+
+```sh
+npm install fatcms-clipboard-parser
+```
+
+```js
+import { parseHtml, parseText, parseTableGrid } from 'fatcms-clipboard-parser';
+
+const { nodes } = parseHtml('<p><strong>你好</strong></p>');
+const values = parseText('姓名\t数量\n张三\t3');
+
+// 在浏览器中解析表格结构；不需要把 table 插入页面。
+const document = new DOMParser().parseFromString(html, 'text/html');
+const table = document.querySelector('table');
+const grid = table ? parseTableGrid(table) : null;
+```
+
+## API
+
+- `parseHtml(html, options?)`：返回 `{ nodes, warnings }`。节点包含 `name`、`type`、`attrs`、`style`、`children` 或 `data`。`parent` 为父节点引用，因此节点树不可直接 JSON.stringify；转换为业务数据时请忽略 parent。支持实体、br、pre/code 换行、简单标签/类/id/后代选择器及内联样式。默认最多 2000 万字符，可通过 `maxLength` 调整；`normalizeWhitespace: false` 保留源文本换行。
+- `parseStyle(text)`：解析 CSS 声明，保留引号、函数内部的分号及值的大小写。
+- `parseText(text)`：按制表符和换行拆成二维数组，保留空格、空单元格和末尾空行。
+- `parseTableGrid(table, options?)`：返回 `{ rows, rowCount, columnCount, merges }`。普通单元格包含原始 DOM `element`、`rowSpan`、`colSpan`；合并覆盖位置包含 `coveredBy: { row, col }`；缺失位置为 null。merge 为 `{ row, col, rowCount, colCount }`，索引从零开始。默认最多 100 万个网格位置，`maxCells` 可调整。`alignFirstRow: 'right'` 兼容省略前导空标题的导出格式，通常使用默认 left。不修改传入 DOM，不做布局测量。
+- `isSafeUrl(value, image?)`：基础 URL 协议检查，供剪贴板适配使用。
+
+## 范围与限制
+
+本包负责公共解析结构，不负责编辑器内容模型、公式计算、图片上传、粘贴命令、撤销历史或工作簿文件导入。电子表格的 Office 特殊格式预处理、行列尺寸测量、数据类型和样式转换由宿主适配器负责。
+
+HTML 节点解析可运行在 Node.js 中；表格解析需要 DOM 对象（浏览器，或调用方提供的 jsdom）。无文档级缓存、监听器或全局语言设置，每次调用返回独立结构。返回的 table element 属于调用者，使用完结果即可释放。
+
+样式解析仅支持扁平的简单规则，不实现完整 CSS cascade、继承、伪类、媒体查询或 `!important`。HTML 解析会忽略部分活动元素和事件属性，但**不是完整 HTML/CSS 安全净化器**；不要把未经专门净化的剪贴板 HTML 插入可信页面或直接执行。
+
+## FatCMS 接入
+
+`fatcms-doc-sdk` 正常 import 本包并挂载到 `window.fatcmsDocDependencies['fatcms-clipboard-parser']`；富文本读取公共节点树。`fatcms-ysheet-sdk` 使用同名 Webpack external，读取公共表格网格，再转换成工作表数据。先加载 doc-sdk，随后加载 ysheet-sdk。仅共享无状态函数，不共享文档数据。
+
+## 开发
+
+```sh
+npm ci
+npm test
+npm pack --dry-run
+```
+
+发布包只包含 src、README 和 LICENSE；测试代码与开发依赖不进入发布文件。源码重新实现公共解析接口，编辑器恢复代码和业务配置不包含在包内。

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "fatcms-clipboard-parser",
+  "version": "0.1.0",
+  "description": "Editor-independent HTML clipboard and table parsing with optional browser layout measurement",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {".": {"types": "./src/index.d.ts", "import": "./src/index.js", "default": "./src/index.js"}},
+  "files": ["src", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "scripts": {"test": "node --test test/*.test.js", "prepublishOnly": "npm test"},
+  "engines": {"node": ">=18"},
+  "license": "MIT",
+  "dependencies": {"htmlparser2": "^6.1.0"},
+  "devDependencies": {"jsdom": "^26.1.0"},
+  "publishConfig": {"registry": "https://registry.npmjs.org/", "access": "public"},
+  "keywords": ["clipboard", "html", "table", "paste", "spreadsheet"]
+}

package/src/html.js

@@ -0,0 +1,98 @@
+import { Parser } from 'htmlparser2';
+import { parseStyle, parseStyleRules, matchesSelector, selectorSpecificity } from './styles.js';
+
+const excludedTags = new Set(['script', 'noscript', 'svg', 'iframe', 'object', 'embed', 'link', 'meta', 'base']);
+
+export function isSafeUrl(value, image = false)
+{
+  const compact = String(value).replace(/[\u0000-\u0020\u007f]/g, '');
+  if (/^(https?:|blob:)/i.test(compact)) return true;
+  if (image && /^data:image\/(png|jpeg|gif|webp|avif|bmp);base64,/i.test(compact)) return true;
+  if (!image && /^(mailto:|tel:)/i.test(compact)) return true;
+  return !/^[a-z][a-z\d+.-]*:/i.test(compact);
+}
+
+/** Parse HTML without executing it or requiring window/document. */
+export function parseHtml(html, { maxLength = 20_000_000, normalizeWhitespace = true } = {})
+{
+  if (typeof html !== 'string') throw new TypeError('HTML must be a string');
+  if (html.length > maxLength) throw new RangeError('Clipboard HTML exceeds maxLength');
+  const root = { type: 'root', name: '#root', children: [] };
+  const stack = [root];
+  const stylesheets = [];
+  const warnings = [];
+  let ignoredDepth = 0;
+  let styleDepth = 0;
+  let styleText = '';
+  let preformattedDepth = 0;
+  function appendText(text)
+  {
+    if (!text) return;
+    const parent = stack[stack.length - 1];
+    const last = parent.children[parent.children.length - 1];
+    if (last?.type === 'text') last.data += text;
+    else parent.children.push({ type: 'text', name: '#text', data: text, parent });
+  }
+  const parser = new Parser({
+    onopentag(name, attributes)
+    {
+      if (ignoredDepth || excludedTags.has(name)) { ignoredDepth++; return; }
+      if (name === 'style') { styleDepth++; styleText = ''; return; }
+      if (name === 'br') { appendText('\n'); return; }
+      const attrs = Object.create(null);
+      for (const [key, value] of Object.entries(attributes))
+      {
+        if (/^on/i.test(key) || ['srcdoc', 'srcset'].includes(key)) continue;
+        if (['href', 'src'].includes(key) && !isSafeUrl(value, key === 'src')) continue;
+        attrs[key] = value;
+      }
+      const style = parseStyle(attrs.style);
+      delete attrs.style;
+      const parent = stack[stack.length - 1];
+      const node = { type: 'element', name, attrs, style, children: [], parent };
+      parent.children.push(node);
+      stack.push(node);
+      if (name === 'pre' || name === 'code') preformattedDepth++;
+    },
+    ontext(text)
+    {
+      if (ignoredDepth) return;
+      if (styleDepth) { styleText += text; return; }
+      let value = text.replace(/\u200b/g, '');
+      if (normalizeWhitespace && !preformattedDepth) value = value.replace(/\n+/g, ' ');
+      appendText(value);
+    },
+    onclosetag(name)
+    {
+      if (ignoredDepth) { ignoredDepth--; return; }
+      if (name === 'style') { stylesheets.push(styleText); styleDepth--; return; }
+      if (name === 'br') return;
+      if (stack.length > 1 && stack[stack.length - 1].name === name)
+      {
+        stack.pop();
+        if (name === 'pre' || name === 'code') preformattedDepth--;
+      }
+    }
+  }, { decodeEntities: true, lowerCaseTags: true, lowerCaseAttributeNames: true });
+  parser.end(html);
+  const rules = stylesheets.flatMap(parseStyleRules);
+  function applyStyles(parent)
+  {
+    parent.children = parent.children.filter(node =>
+    {
+      if (node.type !== 'element') return true;
+      const inheritedRules = rules.filter(rule => matchesSelector(node, rule.selector))
+        .sort((left, right) => selectorSpecificity(left.selector) - selectorSpecificity(right.selector));
+      node.style = Object.assign(Object.create(null), ...inheritedRules.map(rule => rule.style), node.style);
+      applyStyles(node);
+      return node.style.display !== 'none' || ['tr', 'td', 'th', 'col'].includes(node.name);
+    });
+  }
+  applyStyles(root);
+  return { nodes: root.children, warnings };
+}
+
+export function parseText(text)
+{
+  return String(text).replace(/\r\n?/g, '\n').split('\n').map(row => row.split('\t'));
+}

package/src/index.d.ts

@@ -0,0 +1,26 @@
+export interface HtmlNode {
+  type: 'root' | 'element' | 'text';
+  name: string;
+  attrs?: Record<string, string>;
+  style?: Record<string, string>;
+  data?: string;
+  children?: HtmlNode[];
+  parent?: HtmlNode;
+}
+export interface TableCell {
+  element?: HTMLTableCellElement;
+  rowSpan?: number;
+  colSpan?: number;
+  coveredBy?: { row: number; col: number };
+}
+export interface TableGrid {
+  rows: (TableCell | null)[][];
+  rowCount: number;
+  columnCount: number;
+  merges: { row: number; col: number; rowCount: number; colCount: number }[];
+}
+export function parseHtml(html: string, options?: { maxLength?: number; normalizeWhitespace?: boolean }): { nodes: HtmlNode[]; warnings: string[] };
+export function parseText(text: string): string[][];
+export function parseStyle(text?: string): Record<string, string>;
+export function isSafeUrl(value: string, image?: boolean): boolean;
+export function parseTableGrid(table: HTMLTableElement, options?: { maxCells?: number; alignFirstRow?: 'left' | 'right' }): TableGrid;

package/src/index.js

@@ -0,0 +1,3 @@
+export { parseHtml, parseText, isSafeUrl } from './html.js';
+export { parseStyle } from './styles.js';
+export { parseTableGrid } from './table.js';

package/src/styles.js

@@ -0,0 +1,87 @@
+/** Split CSS declarations without splitting quoted strings or function arguments. */
+function splitDeclarations(text)
+{
+  const declarations = [];
+  let quote = '';
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < text.length; index++)
+  {
+    const character = text[index];
+    if (character === '\\') { index++; continue; }
+    if (quote) { if (character === quote) quote = ''; continue; }
+    if (character === '"' || character === "'") quote = character;
+    else if (character === '(') depth++;
+    else if (character === ')') depth = Math.max(0, depth - 1);
+    else if (character === ';' && depth === 0)
+    {
+      declarations.push(text.slice(start, index));
+      start = index + 1;
+    }
+  }
+  declarations.push(text.slice(start));
+  return declarations;
+}
+
+export function parseStyle(text = '')
+{
+  const style = Object.create(null);
+  for (const declaration of splitDeclarations(text))
+  {
+    const separator = declaration.indexOf(':');
+    if (separator < 0) continue;
+    const name = declaration.slice(0, separator).trim().toLowerCase();
+    const value = declaration.slice(separator + 1).trim();
+    if (name && value) style[name] = value;
+  }
+  return style;
+}
+
+export function parseStyleRules(text)
+{
+  const rules = [];
+  // Clipboard stylesheets use flat rules; discard nested at-rules.
+  let clean = text.replace(/\/\*[\s\S]*?\*\//g, '');
+  clean = clean.replace(/@[^{};]+\{(?:[^{}]|\{[^{}]*\})*\}/g, '');
+  for (const match of clean.matchAll(/([^{}]+)\{([^{}]*)\}/g))
+  {
+    for (const selector of match[1].split(','))
+    {
+      if (/^[\w.# -]+$/.test(selector.trim()))
+        rules.push({ selector: selector.trim(), style: parseStyle(match[2]) });
+    }
+  }
+  return rules;
+}
+
+export function matchesSelector(node, selector)
+{
+  const parts = selector.trim().split(/\s+/);
+  let current = node;
+  for (let index = parts.length - 1; index >= 0; index--)
+  {
+    const part = parts[index];
+    const matches = candidate =>
+    {
+      if (candidate.type !== 'element') return false;
+      const tag = part.match(/^[\w-]+/)?.[0];
+      const id = part.match(/#([\w-]+)/)?.[1];
+      const classes = [...part.matchAll(/\.([\w-]+)/g)].map(match => match[1]);
+      return (!tag || tag === candidate.name) && (!id || id === candidate.attrs.id) &&
+        classes.every(name => (candidate.attrs.class || '').split(/\s+/).includes(name));
+    };
+    if (index === parts.length - 1 && !matches(current)) return false;
+    while (current && !matches(current)) current = current.parent;
+    if (!current) return false;
+    current = current.parent;
+  }
+  return true;
+}
+
+export function selectorSpecificity(selector)
+{
+  const ids = (selector.match(/#/g) || []).length;
+  const classes = (selector.match(/\./g) || []).length;
+  const tags = selector.split(/\s+/).filter(part => /^[a-z]/i.test(part)).length;
+  return ids * 10000 + classes * 100 + tags;
+}

package/src/table.js

@@ -0,0 +1,62 @@
+/** Expand merged cells into a rectangular grid without mutating the source table. */
+export function parseTableGrid(table, { maxCells = 1_000_000, alignFirstRow = 'left' } = {})
+{
+  const rows = [];
+  const merges = [];
+  let allocatedCells = 0;
+  let columnCount = 0;
+  const sourceRows = Array.from(table.rows);
+  for (const [rowIndex, sourceRow] of sourceRows.entries())
+  {
+    const row = rows[rowIndex] ||= [];
+    let columnIndex = 0;
+    for (const element of Array.from(sourceRow.cells))
+    {
+      while (row[columnIndex]) columnIndex++;
+      const rowSpan = element.rowSpan === 0 ? sourceRows.length - rowIndex : Math.max(1, element.rowSpan || 1);
+      const colSpan = Math.max(1, element.colSpan || 1);
+      allocatedCells += rowSpan * colSpan;
+      if (allocatedCells > maxCells) throw new RangeError('Clipboard table exceeds maxCells');
+      row[columnIndex] = { element, rowSpan, colSpan };
+      if (rowSpan > 1 || colSpan > 1)
+      {
+        merges.push({ row: rowIndex, col: columnIndex, rowCount: rowSpan, colCount: colSpan });
+        for (let rowOffset = 0; rowOffset < rowSpan; rowOffset++)
+        {
+          const targetRow = rows[rowIndex + rowOffset] ||= [];
+          for (let colOffset = 0; colOffset < colSpan; colOffset++)
+          {
+            if (rowOffset === 0 && colOffset === 0) continue;
+            targetRow[columnIndex + colOffset] = { coveredBy: { row: rowIndex, col: columnIndex } };
+          }
+        }
+      }
+      columnIndex += colSpan;
+      columnCount = Math.max(columnCount, columnIndex);
+    }
+  }
+  if (rows.length * columnCount > maxCells) throw new RangeError('Clipboard table exceeds maxCells');
+  // Some spreadsheet exports omit leading blank heading cells. Opt in explicitly.
+  const firstRow = rows[0];
+  if (alignFirstRow === 'right' && firstRow && firstRow.length < columnCount)
+  {
+    const offset = columnCount - firstRow.length;
+    firstRow.unshift(...Array(offset).fill(null));
+    for (const merge of merges)
+    {
+      if (merge.row === 0) merge.col += offset;
+    }
+    for (const row of rows)
+    {
+      for (const cell of row)
+      {
+        if (cell?.coveredBy?.row === 0) cell.coveredBy.col += offset;
+      }
+    }
+  }
+  for (const row of rows)
+  {
+    for (let column = 0; column < columnCount; column++) row[column] ||= null;
+  }
+  return { rows, rowCount: rows.length, columnCount, merges };
+}