@zseven-w/pen-core 0.0.1

package/README.md

@@ -0,0 +1,80 @@
+# @zseven-w/pen-core
+
+Core document operations for [OpenPencil](https://github.com/nicepkg/openpencil) — tree manipulation, layout engine, design variables, boolean path operations, and more.
+
+## Install
+
+```bash
+npm install @zseven-w/pen-core
+```
+
+## Features
+
+### Document Tree Operations
+
+Create, query, and mutate the document tree:
+
+```ts
+import {
+  createEmptyDocument,
+  findNodeInTree,
+  insertNodeInTree,
+  removeNodeFromTree,
+  updateNodeInTree,
+  deepCloneNode,
+  flattenNodes,
+} from '@zseven-w/pen-core'
+
+const doc = createEmptyDocument()
+const node = findNodeInTree(doc.children, 'node-id')
+```
+
+### Multi-Page Support
+
+```ts
+import { getActivePage, getActivePageChildren, migrateToPages } from '@zseven-w/pen-core'
+```
+
+### Layout Engine
+
+Automatic layout computation with auto-sizing, padding, and gap support:
+
+```ts
+import { inferLayout, computeLayoutPositions, fitContentWidth, fitContentHeight } from '@zseven-w/pen-core'
+```
+
+### Design Variables
+
+Resolve `$variable` references against theme axes:
+
+```ts
+import { resolveVariableRef, resolveNodeForCanvas, replaceVariableRefsInTree } from '@zseven-w/pen-core'
+```
+
+### Boolean Path Operations
+
+Union, subtract, intersect, and exclude paths via Paper.js:
+
+```ts
+import { executeBooleanOp, BooleanOpType } from '@zseven-w/pen-core'
+```
+
+### Text Measurement
+
+Estimate text dimensions for layout without a browser:
+
+```ts
+import { estimateTextWidth, estimateTextHeight } from '@zseven-w/pen-core'
+```
+
+### Document Normalization
+
+Sanitize and fix documents imported from external sources:
+
+```ts
+import { normalizePenDocument } from '@zseven-w/pen-core'
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@zseven-w/pen-core",
+  "version": "0.0.1",
+  "description": "Core document operations, tree utils, variables, layout engine for OpenPencil",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zseven-w/pen-types": "0.0.1",
+    "nanoid": "^5.1.6",
+    "paper": "^0.12.18"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}

package/src/__tests__/arc-path.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest'
+import { buildEllipseArcPath, isArcEllipse } from '../arc-path'
+
+describe('arc-path', () => {
+  describe('isArcEllipse', () => {
+    it('returns false for full circle with no inner radius', () => {
+      expect(isArcEllipse(0, 360, 0)).toBe(false)
+    })
+
+    it('returns true for partial sweep', () => {
+      expect(isArcEllipse(0, 180, 0)).toBe(true)
+    })
+
+    it('returns true for inner radius (donut)', () => {
+      expect(isArcEllipse(0, 360, 0.5)).toBe(true)
+    })
+  })
+
+  describe('buildEllipseArcPath', () => {
+    it('builds a full circle path', () => {
+      const path = buildEllipseArcPath(100, 100, 0, 360, 0)
+      expect(path).toContain('M')
+      expect(path).toContain('A')
+      expect(path).toContain('Z')
+    })
+
+    it('builds a pie slice path', () => {
+      const path = buildEllipseArcPath(100, 100, 0, 90, 0)
+      expect(path).toContain('M50 50') // center point for pie
+      expect(path).toContain('Z')
+    })
+
+    it('builds a donut path with inner radius', () => {
+      const path = buildEllipseArcPath(100, 100, 0, 360, 0.5)
+      // Should have inner arc commands
+      expect(path.split('A').length).toBeGreaterThanOrEqual(3) // outer + inner arcs
+    })
+  })
+})

package/src/__tests__/font-utils.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { cssFontFamily } from '../font-utils'
+
+describe('cssFontFamily', () => {
+  it('quotes multi-word font names', () => {
+    expect(cssFontFamily('Noto Sans SC')).toBe('"Noto Sans SC"')
+  })
+
+  it('does not quote generic families', () => {
+    expect(cssFontFamily('sans-serif')).toBe('sans-serif')
+    expect(cssFontFamily('monospace')).toBe('monospace')
+    expect(cssFontFamily('system-ui')).toBe('system-ui')
+  })
+
+  it('handles comma-separated lists', () => {
+    expect(cssFontFamily('Inter, sans-serif')).toBe('"Inter", sans-serif')
+  })
+
+  it('preserves already-quoted names', () => {
+    expect(cssFontFamily('"Noto Sans SC"')).toBe('"Noto Sans SC"')
+  })
+
+  it('handles -apple-system', () => {
+    expect(cssFontFamily('-apple-system')).toBe('-apple-system')
+  })
+})

package/src/__tests__/layout-engine.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from 'vitest'
+import type { PenNode } from '@zseven-w/pen-types'
+import {
+  resolvePadding,
+  isNodeVisible,
+  inferLayout,
+  getNodeWidth,
+  getNodeHeight,
+  computeLayoutPositions,
+} from '../layout/engine'
+
+const frame = (props: Partial<PenNode> & { children?: PenNode[] }): PenNode => ({
+  id: 'f1', type: 'frame', x: 0, y: 0, ...props,
+} as PenNode)
+
+const rect = (id: string, w = 50, h = 30): PenNode => ({
+  id, type: 'rectangle', x: 0, y: 0, width: w, height: h,
+})
+
+describe('layout-engine', () => {
+  describe('resolvePadding', () => {
+    it('returns zero for undefined', () => {
+      expect(resolvePadding(undefined)).toEqual({ top: 0, right: 0, bottom: 0, left: 0 })
+    })
+
+    it('resolves uniform padding', () => {
+      expect(resolvePadding(10)).toEqual({ top: 10, right: 10, bottom: 10, left: 10 })
+    })
+
+    it('resolves [vertical, horizontal]', () => {
+      expect(resolvePadding([10, 20])).toEqual({ top: 10, right: 20, bottom: 10, left: 20 })
+    })
+
+    it('resolves [top, right, bottom, left]', () => {
+      expect(resolvePadding([1, 2, 3, 4])).toEqual({ top: 1, right: 2, bottom: 3, left: 4 })
+    })
+
+    it('returns zero for string (variable ref)', () => {
+      expect(resolvePadding('$spacing')).toEqual({ top: 0, right: 0, bottom: 0, left: 0 })
+    })
+  })
+
+  describe('isNodeVisible', () => {
+    it('returns true by default', () => {
+      expect(isNodeVisible(rect('a'))).toBe(true)
+    })
+
+    it('returns false when visible is false', () => {
+      expect(isNodeVisible({ ...rect('a'), visible: false })).toBe(false)
+    })
+  })
+
+  describe('inferLayout', () => {
+    it('returns undefined for non-frame nodes', () => {
+      expect(inferLayout(rect('a'))).toBeUndefined()
+    })
+
+    it('infers horizontal when gap is set', () => {
+      expect(inferLayout(frame({ gap: 10, children: [] }))).toBe('horizontal')
+    })
+
+    it('infers horizontal when padding is set', () => {
+      expect(inferLayout(frame({ padding: 10, children: [] }))).toBe('horizontal')
+    })
+
+    it('returns undefined when no layout hints', () => {
+      expect(inferLayout(frame({ children: [rect('a')] }))).toBeUndefined()
+    })
+  })
+
+  describe('getNodeWidth / getNodeHeight', () => {
+    it('returns explicit width', () => {
+      expect(getNodeWidth(rect('a', 200))).toBe(200)
+    })
+
+    it('returns explicit height', () => {
+      expect(getNodeHeight(rect('a', 50, 100))).toBe(100)
+    })
+
+    it('estimates text width', () => {
+      const text: PenNode = { id: 't', type: 'text', content: 'Hello World', fontSize: 16 }
+      expect(getNodeWidth(text)).toBeGreaterThan(0)
+    })
+  })
+
+  describe('computeLayoutPositions', () => {
+    it('positions children horizontally', () => {
+      const parent = frame({
+        width: 300, height: 100,
+        layout: 'horizontal', gap: 10,
+        children: [rect('a', 50, 30), rect('b', 50, 30)],
+      })
+      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
+      expect(result[0].x).toBe(0)
+      expect(result[0].y).toBe(0)
+      expect(result[1].x).toBe(60) // 50 + 10 gap
+    })
+
+    it('positions children vertically', () => {
+      const parent = frame({
+        width: 100, height: 300,
+        layout: 'vertical', gap: 10,
+        children: [rect('a', 50, 30), rect('b', 50, 30)],
+      })
+      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
+      expect(result[0].x).toBe(0)
+      expect(result[0].y).toBe(0)
+      expect(result[1].y).toBe(40) // 30 + 10 gap
+    })
+
+    it('applies padding', () => {
+      const parent = frame({
+        width: 300, height: 100,
+        layout: 'horizontal', padding: 20,
+        children: [rect('a', 50, 30)],
+      })
+      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
+      expect(result[0].x).toBe(20)
+      expect(result[0].y).toBe(20)
+    })
+
+    it('centers children on cross axis', () => {
+      const parent = frame({
+        width: 300, height: 100,
+        layout: 'horizontal', alignItems: 'center',
+        children: [rect('a', 50, 30)],
+      })
+      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
+      expect(result[0].y).toBe(35) // (100 - 30) / 2
+    })
+
+    it('filters invisible children', () => {
+      const parent = frame({
+        width: 300, height: 100,
+        layout: 'horizontal',
+        children: [rect('a', 50, 30), { ...rect('b', 50, 30), visible: false }],
+      })
+      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
+      expect(result).toHaveLength(1)
+    })
+
+    it('returns visible children as-is when layout is none', () => {
+      const parent = frame({
+        width: 300, height: 100,
+        layout: 'none',
+        children: [rect('a', 50, 30)],
+      })
+      const result = computeLayoutPositions(parent, (parent as PenNode & { children: PenNode[] }).children)
+      expect(result).toHaveLength(1)
+      expect(result[0].id).toBe('a')
+    })
+  })
+})

package/src/__tests__/node-helpers.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+import type { PenNode } from '@zseven-w/pen-types'
+import { isBadgeOverlayNode } from '../node-helpers'
+
+describe('isBadgeOverlayNode', () => {
+  it('returns true for badge role', () => {
+    const node: PenNode = { id: '1', type: 'rectangle', role: 'badge' }
+    expect(isBadgeOverlayNode(node)).toBe(true)
+  })
+
+  it('returns true for pill role', () => {
+    const node: PenNode = { id: '1', type: 'rectangle', role: 'pill' }
+    expect(isBadgeOverlayNode(node)).toBe(true)
+  })
+
+  it('returns true for name containing "badge"', () => {
+    const node: PenNode = { id: '1', type: 'rectangle', name: 'Notification Badge' }
+    expect(isBadgeOverlayNode(node)).toBe(true)
+  })
+
+  it('returns true for name containing "overlay"', () => {
+    const node: PenNode = { id: '1', type: 'rectangle', name: 'Image Overlay' }
+    expect(isBadgeOverlayNode(node)).toBe(true)
+  })
+
+  it('returns false for regular nodes', () => {
+    const node: PenNode = { id: '1', type: 'rectangle', name: 'Button' }
+    expect(isBadgeOverlayNode(node)).toBe(false)
+  })
+})

package/src/__tests__/normalize.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest'
+import type { PenDocument } from '@zseven-w/pen-types'
+import { normalizePenDocument } from '../normalize'
+
+describe('normalizePenDocument', () => {
+  it('normalizes "color" fill type to "solid"', () => {
+    const doc: PenDocument = {
+      version: '1.0.0',
+      children: [{
+        id: '1', type: 'rectangle', x: 0, y: 0,
+        fill: [{ type: 'color' as 'solid', color: '#ff0000' }],
+      }],
+    }
+    const result = normalizePenDocument(doc)
+    const fill = (result.children[0] as { fill: Array<{ type: string }> }).fill
+    expect(fill[0].type).toBe('solid')
+  })
+
+  it('normalizes string fill shorthand to solid fill array', () => {
+    const doc: PenDocument = {
+      version: '1.0.0',
+      children: [{
+        id: '1', type: 'rectangle', x: 0, y: 0,
+        fill: '#ff0000' as unknown as Array<{ type: 'solid'; color: string }>,
+      }],
+    }
+    const result = normalizePenDocument(doc)
+    const fill = (result.children[0] as { fill: Array<{ type: string; color: string }> }).fill
+    expect(fill).toHaveLength(1)
+    expect(fill[0]).toEqual({ type: 'solid', color: '#ff0000' })
+  })
+
+  it('normalizes fill_container sizing', () => {
+    const doc: PenDocument = {
+      version: '1.0.0',
+      children: [{
+        id: '1', type: 'frame', x: 0, y: 0,
+        width: 'fill_container(300)' as unknown as number,
+        height: 'fill_container' as unknown as number,
+        children: [],
+      }],
+    }
+    const result = normalizePenDocument(doc)
+    const node = result.children[0] as { width: unknown; height: unknown }
+    expect(node.width).toBe('fill_container')
+    expect(node.height).toBe('fill_container')
+  })
+
+  it('normalizes fit_content with hint to number', () => {
+    const doc: PenDocument = {
+      version: '1.0.0',
+      children: [{
+        id: '1', type: 'frame', x: 0, y: 0,
+        width: 'fit_content(250)' as unknown as number,
+        height: 'fit_content' as unknown as number,
+        children: [],
+      }],
+    }
+    const result = normalizePenDocument(doc)
+    const node = result.children[0] as { width: unknown; height: unknown }
+    expect(node.width).toBe(250)
+    expect(node.height).toBe('fit_content')
+  })
+
+  it('normalizes pages children too', () => {
+    const doc: PenDocument = {
+      version: '1.0.0',
+      pages: [{
+        id: 'p1', name: 'Page 1',
+        children: [{
+          id: '1', type: 'rectangle', x: 0, y: 0,
+          fill: [{ type: 'color' as 'solid', color: '#00ff00' }],
+        }],
+      }],
+      children: [],
+    }
+    const result = normalizePenDocument(doc)
+    const fill = (result.pages![0].children[0] as { fill: Array<{ type: string }> }).fill
+    expect(fill[0].type).toBe('solid')
+  })
+
+  it('normalizes string elements inside fill array', () => {
+    const doc: PenDocument = {
+      version: '1.0.0',
+      children: [{
+        id: '1', type: 'path', d: 'M0 0', x: 0, y: 0,
+        fill: ['#ff0000'] as unknown as Array<{ type: 'solid'; color: string }>,
+      }],
+    }
+    const result = normalizePenDocument(doc)
+    const fill = (result.children[0] as { fill: Array<{ type: string; color: string }> }).fill
+    expect(fill).toHaveLength(1)
+    expect(fill[0]).toEqual({ type: 'solid', color: '#ff0000' })
+  })
+
+  it('preserves $variable references', () => {
+    const doc: PenDocument = {
+      version: '1.0.0',
+      children: [{
+        id: '1', type: 'rectangle', x: 0, y: 0,
+        fill: [{ type: 'solid', color: '$primary' }],
+        opacity: '$opacity' as unknown as number,
+      }],
+    }
+    const result = normalizePenDocument(doc)
+    const node = result.children[0] as { fill: Array<{ color: string }>; opacity: unknown }
+    expect(node.fill[0].color).toBe('$primary')
+    expect(node.opacity).toBe('$opacity')
+  })
+})

package/src/__tests__/text-measure.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest'
+import type { PenNode } from '@zseven-w/pen-types'
+import {
+  parseSizing,
+  defaultLineHeight,
+  isCjkCodePoint,
+  hasCjkText,
+  estimateGlyphWidth,
+  estimateLineWidth,
+  estimateTextWidth,
+  resolveTextContent,
+  countExplicitTextLines,
+  estimateTextHeight,
+} from '../layout/text-measure'
+
+describe('text-measure', () => {
+  describe('parseSizing', () => {
+    it('returns number for number input', () => {
+      expect(parseSizing(100)).toBe(100)
+    })
+
+    it('returns "fill" for fill_container', () => {
+      expect(parseSizing('fill_container')).toBe('fill')
+    })
+
+    it('returns "fit" for fit_content', () => {
+      expect(parseSizing('fit_content')).toBe('fit')
+    })
+
+    it('parses numeric strings', () => {
+      expect(parseSizing('200')).toBe(200)
+    })
+
+    it('returns 0 for non-parseable', () => {
+      expect(parseSizing(undefined)).toBe(0)
+      expect(parseSizing('abc')).toBe(0)
+    })
+  })
+
+  describe('defaultLineHeight', () => {
+    it('returns tight leading for display text', () => {
+      expect(defaultLineHeight(48)).toBe(1.0)
+    })
+
+    it('returns comfortable leading for body text', () => {
+      expect(defaultLineHeight(14)).toBe(1.5)
+    })
+  })
+
+  describe('CJK detection', () => {
+    it('detects CJK code points', () => {
+      expect(isCjkCodePoint('中'.codePointAt(0)!)).toBe(true)
+      expect(isCjkCodePoint('あ'.codePointAt(0)!)).toBe(true)
+      expect(isCjkCodePoint('A'.codePointAt(0)!)).toBe(false)
+    })
+
+    it('hasCjkText detects CJK in strings', () => {
+      expect(hasCjkText('Hello 世界')).toBe(true)
+      expect(hasCjkText('Hello World')).toBe(false)
+    })
+  })
+
+  describe('estimateGlyphWidth', () => {
+    it('returns 0 for newline', () => {
+      expect(estimateGlyphWidth('\n', 16)).toBe(0)
+    })
+
+    it('estimates CJK wider than Latin', () => {
+      const cjk = estimateGlyphWidth('中', 16)
+      const latin = estimateGlyphWidth('a', 16)
+      expect(cjk).toBeGreaterThan(latin)
+    })
+
+    it('estimates uppercase wider than lowercase', () => {
+      const upper = estimateGlyphWidth('A', 16)
+      const lower = estimateGlyphWidth('a', 16)
+      expect(upper).toBeGreaterThan(lower)
+    })
+  })
+
+  describe('estimateLineWidth', () => {
+    it('estimates width of a line', () => {
+      const width = estimateLineWidth('Hello', 16)
+      expect(width).toBeGreaterThan(0)
+    })
+
+    it('adds letter spacing', () => {
+      const base = estimateLineWidth('AB', 16, 0)
+      const spaced = estimateLineWidth('AB', 16, 5)
+      expect(spaced).toBeGreaterThan(base)
+    })
+  })
+
+  describe('estimateTextWidth', () => {
+    it('returns the widest line', () => {
+      const width = estimateTextWidth('short\nmuch longer line', 16)
+      const singleWidth = estimateTextWidth('much longer line', 16)
+      // Multi-line should return width of longest line
+      expect(width).toBeCloseTo(singleWidth, 0)
+    })
+  })
+
+  describe('resolveTextContent', () => {
+    it('resolves string content', () => {
+      const node: PenNode = { id: '1', type: 'text', content: 'Hello' }
+      expect(resolveTextContent(node)).toBe('Hello')
+    })
+
+    it('resolves styled segment content', () => {
+      const node: PenNode = {
+        id: '1', type: 'text',
+        content: [{ text: 'Hello ' }, { text: 'World' }],
+      }
+      expect(resolveTextContent(node)).toBe('Hello World')
+    })
+
+    it('returns empty for non-text nodes', () => {
+      const node: PenNode = { id: '1', type: 'rectangle' }
+      expect(resolveTextContent(node)).toBe('')
+    })
+  })
+
+  describe('countExplicitTextLines', () => {
+    it('counts newlines', () => {
+      expect(countExplicitTextLines('a\nb\nc')).toBe(3)
+    })
+
+    it('returns 1 for empty string', () => {
+      expect(countExplicitTextLines('')).toBe(1)
+    })
+  })
+
+  describe('estimateTextHeight', () => {
+    it('estimates height for single-line text', () => {
+      const node: PenNode = { id: '1', type: 'text', content: 'Hello', fontSize: 16 }
+      const height = estimateTextHeight(node)
+      expect(height).toBeGreaterThan(0)
+      expect(height).toBeLessThan(50)
+    })
+
+    it('estimates taller for multi-line text', () => {
+      const single: PenNode = { id: '1', type: 'text', content: 'Hello', fontSize: 16 }
+      const multi: PenNode = { id: '2', type: 'text', content: 'Hello\nWorld', fontSize: 16 }
+      expect(estimateTextHeight(multi)).toBeGreaterThan(estimateTextHeight(single))
+    })
+  })
+})