fatcms-clipboard-parser 0.1.0 → 0.2.0

package/README.md

@@ -28,7 +28,7 @@ const grid = table ? parseTableGrid(table) : null;
 
 ## 范围与限制
 
-本包负责公共解析结构，不负责编辑器内容模型、公式计算、图片上传、粘贴命令、撤销历史或工作簿文件导入。电子表格的 Office 特殊格式预处理、行列尺寸测量、数据类型和样式转换由宿主适配器负责。
+本包负责公共解析结构，不负责编辑器内容模型、公式计算、图片上传、粘贴命令、撤销历史或工作簿文件导入。电子表格的 Office 特殊格式预处理、行列尺寸测量和 CSS 样式提取由 parseSpreadsheetHtml 负责；数据类型及编辑器样式字段由宿主适配器映射。
 
 HTML 节点解析可运行在 Node.js 中；表格解析需要 DOM 对象（浏览器，或调用方提供的 jsdom）。无文档级缓存、监听器或全局语言设置，每次调用返回独立结构。返回的 table element 属于调用者，使用完结果即可释放。
 
@@ -47,3 +47,16 @@ npm pack --dry-run
 ```
 
 发布包只包含 src、README 和 LICENSE；测试代码与开发依赖不进入发布文件。源码重新实现公共解析接口，编辑器恢复代码和业务配置不包含在包内。
+
+## 0.2：完整电子表格 HTML 解析
+
+```js
+import { parseSpreadsheetHtml } from 'fatcms-clipboard-parser';
+const result = parseSpreadsheetHtml(html, { document });
+```
+
+返回 rows（二维单元格数组）、merges、rowSizes、columnSizes 和 tableAttributes。单元格包括 text、可选 link/image、CSS 风格的 style、Office numberFormat 和原始 attributes。所有结果都是普通数据，不包含 DOM 或循环引用。data-* 属性仅传给适配器，本包不解释编辑器私有协议。
+
+此 API 要求浏览器文档；在屏幕外 Shadow DOM 中测量布局，始终 finally 清理，不加载剪贴板图片，不把来源样式表插入宿主。支持多表格拼接、合并单元格、隐藏行列、Office mso-xlrowspan / mso-ignore:colspan / mso-number-format。业务值、上传策略和保存仍由适配器处理。不导入工作簿 XML，不执行公式。
+
+限制：复杂 CSS 规则沿用 parseHtml 的支持范围；单元格包含多张图片时返回第一张，混合富文本按单元格整体样式表示。测量容器宽度固定为 1200px，默认行高至少 24px。

package/package.json

@@ -1,18 +1,46 @@
 {
   "name": "fatcms-clipboard-parser",
-  "version": "0.1.0",
+  "version": "0.2.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"],
+  "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"},
+  "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"]
+  "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/cell-content.js

@@ -0,0 +1,58 @@
+/** Read clipboard content without executing HTML or initiating image requests. */
+export function readCellContent(element, metadata)
+{
+  function textOf(node)
+  {
+    if (node.nodeType === 3) return node.textContent;
+    if (node.nodeName === 'BR') return '\n';
+    if (node.nodeName === 'RT') return '';
+    return Array.from(node.childNodes).map(textOf).join('');
+  }
+  const text = textOf(element).replace(/\u00a0/g, ' ').trim().replace(/ %$/, '%');
+  const imageElement = element.querySelector('img');
+  const imageSource = imageElement && metadata.get(imageElement)?.attrs.src;
+  const link = element.querySelector('a[href]');
+  return {
+    text,
+    image: imageSource ? { url: imageSource, name: imageElement.getAttribute('alt') || 'image' } : undefined,
+    link: link ? { url: link.getAttribute('href'), text: text.replace(/\n/g, '') } : undefined,
+    attributes: { ...metadata.get(element)?.attrs },
+    numberFormat: metadata.get(element)?.style['mso-number-format'] || '',
+  };
+}
+
+export function readCellStyle(element, window)
+{
+  const computed = window.getComputedStyle(element);
+  const properties = [
+    'font-size', 'font-weight', 'font-style', 'color', 'background-color',
+    'text-decoration', 'text-align', 'vertical-align', 'white-space',
+  ];
+  const result = {};
+  for (const property of properties) result[property] = computed.getPropertyValue(property);
+  // Excel/Word frequently put character formatting on a span inside the cell.
+  const inline = element.querySelector('span,b,strong,i,em,s,del,u,font');
+  if (inline)
+  {
+    const inlineStyle = window.getComputedStyle(inline);
+    for (const property of ['font-size', 'font-weight', 'font-style', 'color'])
+    {
+      const value = inlineStyle.getPropertyValue(property);
+      if (value) result[property] = value;
+    }
+    result['text-decoration'] += ` ${inlineStyle.textDecoration || ''}`;
+  }
+  if (element.querySelector('s,del')) result['text-decoration'] += ' line-through';
+  if (element.querySelector('u')) result['text-decoration'] += ' underline';
+  if (element.querySelector('b,strong')) result['font-weight'] = 'bold';
+  if (element.querySelector('i,em')) result['font-style'] = 'italic';
+  for (const side of ['left', 'right', 'top', 'bottom'])
+  {
+    for (const part of ['width', 'color', 'style'])
+    {
+      const property = `border-${side}-${part}`;
+      result[property] = computed.getPropertyValue(property);
+    }
+  }
+  return result;
+}

package/src/html.js

@@ -13,7 +13,7 @@ export function isSafeUrl(value, image = false)
 }
 
 /** Parse HTML without executing it or requiring window/document. */
-export function parseHtml(html, { maxLength = 20_000_000, normalizeWhitespace = true } = {})
+export function parseHtml(html, { maxLength = 20_000_000, normalizeWhitespace = true, preserveBreakElements = false } = {})
 {
   if (typeof html !== 'string') throw new TypeError('HTML must be a string');
   if (html.length > maxLength) throw new RangeError('Clipboard HTML exceeds maxLength');
@@ -38,7 +38,7 @@ export function parseHtml(html, { maxLength = 20_000_000, normalizeWhitespace =
     {
       if (ignoredDepth || excludedTags.has(name)) { ignoredDepth++; return; }
       if (name === 'style') { styleDepth++; styleText = ''; return; }
-      if (name === 'br') { appendText('\n'); return; }
+      if (name === 'br' && !preserveBreakElements) { appendText('\n'); return; }
       const attrs = Object.create(null);
       for (const [key, value] of Object.entries(attributes))
       {
@@ -66,7 +66,7 @@ export function parseHtml(html, { maxLength = 20_000_000, normalizeWhitespace =
     {
       if (ignoredDepth) { ignoredDepth--; return; }
       if (name === 'style') { stylesheets.push(styleText); styleDepth--; return; }
-      if (name === 'br') return;
+      if (name === 'br' && !preserveBreakElements) return;
       if (stack.length > 1 && stack[stack.length - 1].name === name)
       {
         stack.pop();

package/src/index.d.ts

@@ -19,8 +19,26 @@ export interface TableGrid {
   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 parseHtml(html: string, options?: { maxLength?: number; normalizeWhitespace?: boolean; preserveBreakElements?: 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;
+
+export interface SpreadsheetCell {
+  text: string;
+  image?: { url: string; name: string };
+  link?: { url: string; text: string };
+  attributes?: Record<string, string>;
+  style?: Record<string, string>;
+  numberFormat?: string;
+}
+export interface ClipboardDimension { size: number; hidden?: boolean; previousSize?: number }
+export interface SpreadsheetClipboard {
+  rows: (SpreadsheetCell | null)[][];
+  merges: TableGrid['merges'];
+  rowSizes: Record<number, ClipboardDimension>;
+  columnSizes: Record<number, ClipboardDimension>;
+  tableAttributes: { row: number; attributes: Record<string, string> }[];
+}
+export function parseSpreadsheetHtml(html: string, options?: { document?: Document; maxCells?: number; maxLength?: number }): SpreadsheetClipboard;

package/src/index.js

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

package/src/office-table.js

@@ -0,0 +1,60 @@
+/** Normalize the subset of Excel HTML extensions used by clipboard tables. */
+export function normalizeOfficeTable(table, maxCells)
+{
+  const rows = Array.from(table.rows);
+  let expandedRows = rows.length;
+  for (const row of rows)
+  {
+    const repetitions = Number(row.getAttribute('style')?.match(/mso-xlrowspan\s*:\s*(\d+)/i)?.[1] || 1);
+    expandedRows += repetitions - 1;
+    if (expandedRows > maxCells) throw new RangeError('Clipboard table exceeds maxCells');
+    if (repetitions > 1)
+    {
+      const height = parseFloat(row.getAttribute('height')) / repetitions || 24;
+      row.setAttribute('height', String(height));
+      row.style.height = `${height}px`;
+      for (let index = 1; index < repetitions; index++) row.before(row.cloneNode(false));
+    }
+    for (const cell of Array.from(row.cells))
+    {
+      if (cell.colSpan > 1 && /mso-ignore\s*:\s*colspan/i.test(cell.getAttribute('style') || ''))
+      {
+        const count = cell.colSpan;
+        cell.colSpan = 1;
+        for (let index = 1; index < count; index++) cell.after(cell.cloneNode(false));
+      }
+    }
+  }
+
+  // Excel can omit rows completely covered by a vertical merge.
+  // Only repair tables whose total area proves complete rows were omitted.
+  const currentRows = Array.from(table.rows);
+  const widths = currentRows.map(row => Array.from(row.cells).reduce((sum, cell) => sum + cell.colSpan, 0));
+  const width = widths.reduce((maximum, width) => Math.max(maximum, width), 0);
+  const area = currentRows.reduce((sum, row) => sum + Array.from(row.cells).reduce((total, cell) => total + cell.colSpan * cell.rowSpan, 0), 0);
+  const missing = width ? area / width - currentRows.length : 0;
+  if (widths[0] === width && Number.isInteger(missing) && missing > 0)
+  {
+    const coveredColumns = new Map();
+    let inserted = 0;
+    for (const [sourceIndex, row] of currentRows.entries())
+    {
+      let rowIndex = sourceIndex + inserted;
+      while (coveredColumns.get(rowIndex) === width && inserted < missing)
+      {
+        table.insertRow(rowIndex);
+        inserted++;
+        rowIndex++;
+      }
+      for (const cell of Array.from(row.cells))
+      {
+        if (cell.rowSpan * cell.colSpan > maxCells) throw new RangeError('Clipboard table exceeds maxCells');
+        for (let offset = 1; offset < cell.rowSpan; offset++)
+        {
+          const target = rowIndex + offset;
+          coveredColumns.set(target, (coveredColumns.get(target) || 0) + cell.colSpan);
+        }
+      }
+    }
+  }
+}

package/src/spreadsheet.js

@@ -0,0 +1,150 @@
+import { parseHtml } from './html.js';
+import { parseTableGrid } from './table.js';
+import { normalizeOfficeTable } from './office-table.js';
+import { readCellContent, readCellStyle } from './cell-content.js';
+
+const blockTags = new Set(['BODY', 'ARTICLE', 'ASIDE', 'ADDRESS', 'DD', 'DL', 'FIELDSET', 'FIGCAPTION', 'FIGURE', 'FOOTER', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'HEADER', 'P', 'DIV', 'PRE', 'BLOCKQUOTE', 'UL', 'OL', 'LI', 'SECTION']);
+const allowedTags = new Set('html head body br table thead tbody tfoot tr td th colgroup col caption div p pre code span b strong i em s del u a img font ul ol li h1 h2 h3 h4 h5 h6 blockquote sup sub ruby rt section article'.split(' '));
+const allowedStyles = /^(font(-[a-z-]+)?|color|background-color|text-align|text-decoration(-[a-z-]+)?|vertical-align|white-space|display|visibility|width|height|min-width|max-width|padding(-[a-z]+)?|border(-[a-z-]+)?|border-collapse|table-layout|line-height|mso-[a-z-]+)$/;
+
+/** Browser-only parsing. The returned values contain no DOM references. */
+export function parseSpreadsheetHtml(html, { document = globalThis.document, maxCells = 1_000_000, maxLength = 20_000_000 } = {})
+{
+  if (!document?.defaultView) throw new TypeError('A browser document is required');
+  const { nodes } = parseHtml(html.replace(/\\0022/g, ''), { maxLength, preserveBreakElements: true });
+  const metadata = new WeakMap();
+  const host = document.createElement('div');
+  host.setAttribute('data-clipboard-measurement', '');
+  host.style.cssText = 'position:fixed;left:-100000px;top:0;opacity:0;pointer-events:none;width:1200px;contain:layout style;';
+  const shadow = host.attachShadow({ mode: 'closed' });
+  const container = document.createElement('div');
+  container.style.cssText = 'font:16px Arial;color:rgb(0,0,0);';
+  shadow.append(container);
+
+  function appendNodes(parent, children)
+  {
+    for (const node of children)
+    {
+      if (node.type === 'text')
+      {
+        parent.append(document.createTextNode(node.data));
+        continue;
+      }
+      if (['html', 'head', 'body'].includes(node.name))
+      {
+        appendNodes(parent, node.children);
+        continue;
+      }
+      const element = document.createElement(allowedTags.has(node.name) ? node.name : 'span');
+      metadata.set(element, node);
+      for (const [name, value] of Object.entries(node.attrs))
+      {
+        if (['rowspan', 'colspan', 'span', 'width', 'height', 'align', 'valign', 'hidden', 'aria-hidden', 'alt', 'href'].includes(name))
+          element.setAttribute(name, value);
+      }
+      for (const [name, value] of Object.entries(node.style))
+      {
+        if (allowedStyles.test(name) && !/url\s*\(|expression\s*\(|[\\<>]/i.test(value)) element.style.setProperty(name, value);
+      }
+      // Preserve Office extensions for preprocessing without applying arbitrary CSS.
+      for (const name of ['mso-xlrowspan', 'mso-ignore'])
+      {
+        if (node.style[name]) element.setAttribute('style', `${element.getAttribute('style') || ''};${name}:${node.style[name]}`);
+      }
+      parent.append(element);
+      appendNodes(element, node.children);
+    }
+  }
+
+  const result = { rows: [], merges: [], rowSizes: {}, columnSizes: {}, tableAttributes: [] };
+  let appendInline = false;
+  function appendContent(content)
+  {
+    if (result.rows.length >= maxCells) throw new RangeError('Clipboard content exceeds maxCells');
+    result.rows.push([content]);
+  }
+  function readTable(table)
+  {
+    normalizeOfficeTable(table, maxCells);
+    const grid = parseTableGrid(table, { maxCells, alignFirstRow: 'right' });
+    const offset = result.rows.length;
+    if ((offset + grid.rowCount) * Math.max(1, grid.columnCount) > maxCells) throw new RangeError('Clipboard content exceeds maxCells');
+    result.tableAttributes.push({ row: offset, attributes: { ...metadata.get(table)?.attrs } });
+    for (const row of grid.rows)
+    {
+      result.rows.push(row.map(cell => cell?.element ? {
+        ...readCellContent(cell.element, metadata),
+        style: readCellStyle(cell.element, document.defaultView),
+      } : null));
+    }
+    for (const merge of grid.merges) result.merges.push({ ...merge, row: merge.row + offset });
+    for (const [index, row] of Array.from(table.rows).entries())
+    {
+      const style = document.defaultView.getComputedStyle(row);
+      const hidden = row.hidden || row.getAttribute('aria-hidden') === 'true' || style.display === 'none' || ['hidden', 'collapse'].includes(style.visibility);
+      const height = Math.max(24, row.offsetHeight || parseFloat(row.style.height) || parseFloat(row.getAttribute('height')) || 24);
+      result.rowSizes[index + offset] = hidden ? { size: 0, hidden: true, previousSize: height } : { size: height };
+    }
+    let column = 0;
+    for (const col of table.querySelectorAll('col'))
+    {
+      if (col.closest('table') !== table) continue;
+      const width = parseFloat(col.style.width || col.getAttribute('width'));
+      const style = document.defaultView.getComputedStyle(col);
+      const hidden = width === 0 || style.display === 'none';
+      for (let span = 0; span < Math.max(1, col.span) && column < grid.columnCount; span++, column++)
+      {
+        if (hidden) result.columnSizes[column] = { size: 0, hidden: true, previousSize: 120 };
+        else if (Number.isFinite(width)) result.columnSizes[column] = { size: width };
+      }
+    }
+    appendInline = false;
+  }
+  function walk(element)
+  {
+    if (element.nodeType === 3)
+    {
+      const text = element.textContent;
+      if (!text.trim() && !appendInline) return;
+      if (appendInline) result.rows.at(-1)[0].text += text;
+      else appendContent({ text });
+      appendInline = true;
+      return;
+    }
+    if (element.tagName === 'BR')
+    {
+      appendInline = false;
+      return;
+    }
+    if (element.tagName === 'TABLE') return readTable(element);
+    if (element.tagName === 'IMG')
+    {
+      const url = metadata.get(element)?.attrs.src;
+      if (url) appendContent({ text: '', image: { url, name: element.alt || '' } });
+      appendInline = false;
+      return;
+    }
+    if (element.tagName === 'A')
+    {
+      appendContent({ text: element.textContent, link: { url: element.getAttribute('href') || '', text: element.textContent } });
+      appendInline = false;
+      return;
+    }
+    if (metadata.get(element)?.style['mso-element']) return;
+    const block = blockTags.has(element.tagName);
+    if (block) appendInline = false;
+    for (const child of element.childNodes) walk(child);
+    if (block) appendInline = false;
+  }
+  try
+  {
+    appendNodes(container, nodes);
+    document.body.append(host);
+    for (const child of container.childNodes) walk(child);
+    return result;
+  }
+  finally
+  {
+    host.remove();
+  }
+}