@things-factory/board-ai 10.0.0-beta.108

package/server/service/styling/clear-tools.test.ts

@@ -0,0 +1,164 @@
+/**
+ * clear-tools — clearStyle 의 aspect 별 reset 동작.
+ *
+ * preset 적용 전 / 데이터 바인딩 적용 전 깨끗한 상태로 돌리기 위한 helper.
+ *
+ * stroke / font 형식은 things-scene canonical 로 정정됨 (이전 stale 잔재 제거).
+ * shadow 는 `{ blur, color }` — drawer 가 blur 우선 + blurSize fallback 이라
+ * 둘 다 동작하지만 canonical 인 blur 사용.
+ */
+import { buildClearStyleOps } from './clear-tools'
+
+describe('buildClearStyleOps — 입력 검증', () => {
+  test('refids 비어있으면 에러', () => {
+    const r = buildClearStyleOps({ refids: [], aspects: ['fill'] })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/non-empty array/)
+  })
+
+  test('비-숫자 refids 필터링', () => {
+    const r = buildClearStyleOps({
+      refids: [1, NaN, 'x' as any, 2],
+      aspects: ['fill']
+    })
+    expect(r.ops).toHaveLength(2)
+  })
+
+  test('aspects 비어있으면 에러', () => {
+    const r = buildClearStyleOps({ refids: [1], aspects: [] })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/aspects must be a non-empty array/)
+  })
+
+  test('알 수 없는 aspect → 에러 + 유효 목록 제시', () => {
+    const r = buildClearStyleOps({
+      refids: [1],
+      aspects: ['glow' as any, 'fill']
+    })
+    expect(r.ops).toEqual([])
+    expect(r.errors[0]).toMatch(/Unknown aspect\(s\): glow/)
+    expect(r.errors[0]).toMatch(/fill/)
+  })
+})
+
+describe('buildClearStyleOps — aspect 별 reset patch (현재 동작)', () => {
+  test('fill → fillStyle: { type: none }', () => {
+    const r = buildClearStyleOps({ refids: [1], aspects: ['fill'] })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({ fillStyle: { type: 'none' } })
+  })
+
+  test('opacity → alpha: 1', () => {
+    const r = buildClearStyleOps({ refids: [1], aspects: ['opacity'] })
+    expect(r.ops[0].patch).toEqual({ alpha: 1 })
+  })
+
+  test('material → material3d: { preset: default }', () => {
+    const r = buildClearStyleOps({ refids: [1], aspects: ['material'] })
+    expect(r.ops[0].patch).toEqual({ material3d: { preset: 'default' } })
+  })
+
+  test('stroke → lineWidth: 0 (top-level)', () => {
+    const r = buildClearStyleOps({ refids: [1], aspects: ['stroke'] })
+    expect(r.ops[0].patch).toEqual({ lineWidth: 0 })
+  })
+
+  test('shadow → blur: 0, color: transparent', () => {
+    const r = buildClearStyleOps({ refids: [1], aspects: ['shadow'] })
+    expect(r.ops[0].patch).toEqual({ shadow: { blur: 0, color: 'transparent' } })
+  })
+
+  test('font → 핵심 폰트 키 null=delete', () => {
+    const r = buildClearStyleOps({ refids: [1], aspects: ['font'] })
+    expect(r.ops[0].patch).toEqual({
+      fontSize: null,
+      fontFamily: null,
+      fontColor: null,
+      fontWeight: null,
+      fontStyle: null
+    })
+  })
+
+  test('font + 다른 aspect 조합 — 양쪽 모두 효과 있음', () => {
+    const r = buildClearStyleOps({
+      refids: [1],
+      aspects: ['font', 'opacity']
+    })
+    expect(r.ops).toHaveLength(1)
+    expect(r.ops[0].patch).toEqual({
+      fontSize: null,
+      fontFamily: null,
+      fontColor: null,
+      fontWeight: null,
+      fontStyle: null,
+      alpha: 1
+    })
+  })
+})
+
+describe('buildClearStyleOps — 다중 aspect 병합', () => {
+  test('fill + opacity 한 번에', () => {
+    const r = buildClearStyleOps({
+      refids: [1],
+      aspects: ['fill', 'opacity']
+    })
+    expect(r.ops).toHaveLength(1)
+    // 두 aspect 의 patch 가 한 객체로 병합
+    expect(r.ops[0].patch).toEqual({
+      fillStyle: { type: 'none' },
+      alpha: 1
+    })
+  })
+
+  test('fill + material', () => {
+    const r = buildClearStyleOps({
+      refids: [1],
+      aspects: ['fill', 'material']
+    })
+    expect(r.ops[0].patch).toEqual({
+      fillStyle: { type: 'none' },
+      material3d: { preset: 'default' }
+    })
+  })
+
+  test('모든 aspect 한 번에 — 6개 모두 병합', () => {
+    const r = buildClearStyleOps({
+      refids: [1],
+      aspects: ['fill', 'stroke', 'shadow', 'material', 'font', 'opacity']
+    })
+    expect(r.ops).toHaveLength(1)
+    const p = r.ops[0].patch as any
+    expect(p.fillStyle).toEqual({ type: 'none' })
+    expect(p.lineWidth).toBe(0)
+    expect(p.shadow).toEqual({ blur: 0, color: 'transparent' })
+    expect(p.material3d).toEqual({ preset: 'default' })
+    expect(p.fontSize).toBeNull()
+    expect(p.alpha).toBe(1)
+  })
+})
+
+describe('buildClearStyleOps — multi-target', () => {
+  test('동일 reset patch 가 여러 refid 에 분배', () => {
+    const r = buildClearStyleOps({
+      refids: [10, 20, 30],
+      aspects: ['fill']
+    })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops.every(o => (o as any).patch.fillStyle.type === 'none')).toBe(true)
+  })
+})
+
+describe('buildClearStyleOps — 시나리오', () => {
+  test('preset 적용 전 cleanse — fill + stroke + material', () => {
+    const r = buildClearStyleOps({
+      refids: [1, 2, 3],
+      aspects: ['fill', 'material']
+    })
+    expect(r.ops).toHaveLength(3)
+    expect(r.ops[0].patch).toMatchObject({
+      fillStyle: { type: 'none' },
+      material3d: { preset: 'default' }
+    })
+  })
+})
+

package/server/service/styling/clear-tools.ts

@@ -0,0 +1,69 @@
+/**
+ * clearStyle — 특정 styling aspect 들을 초기화 (제거).
+ *
+ * preset 적용 전 / 데이터 바인딩 적용 전 깨끗한 상태로 돌리기 위한 helper.
+ */
+import type { BoardEditOp } from '../types'
+
+export interface ClearStyleInput {
+  refids: number[]
+  aspects: Array<'fill' | 'stroke' | 'shadow' | 'material' | 'font' | 'opacity'>
+}
+
+export interface OpsResult {
+  ops: BoardEditOp[]
+  errors: string[]
+}
+
+const ASPECT_TO_PATCH: Record<string, any> = {
+  fill: { fillStyle: { type: 'none' } },
+  // stroke: strokeStyle 는 색상 문자열 (top-level), 굵기는 lineWidth (top-level).
+  // 굵기 0 으로 윤곽선 시각 제거 (색은 유지). 완전 제거는 strokeStyle: null 동시 set.
+  stroke: { lineWidth: 0 },
+  shadow: { shadow: { blur: 0, color: 'transparent' } },
+  material: { material3d: { preset: 'default' } },
+  // font: null = delete 시맨틱 (apply-patch.ts:233-243). 핵심 폰트 키 모두 제거 →
+  // component 가 기본 폰트 동작으로 복귀. 보존이 의도라면 font aspect 미선택.
+  font: {
+    fontSize: null,
+    fontFamily: null,
+    fontColor: null,
+    fontWeight: null,
+    fontStyle: null
+  },
+  opacity: { alpha: 1 }
+}
+
+export function buildClearStyleOps(input: ClearStyleInput): OpsResult {
+  if (!Array.isArray(input.refids) || input.refids.length === 0) {
+    return { ops: [], errors: ['refids must be a non-empty array'] }
+  }
+  const refids = input.refids.filter(n => typeof n === 'number' && Number.isFinite(n))
+  if (refids.length === 0) return { ops: [], errors: ['No valid numeric refids'] }
+
+  if (!Array.isArray(input.aspects) || input.aspects.length === 0) {
+    return { ops: [], errors: ['aspects must be a non-empty array'] }
+  }
+  const valid = ['fill', 'stroke', 'shadow', 'material', 'font', 'opacity']
+  const unknown = input.aspects.filter(a => !valid.includes(a))
+  if (unknown.length > 0) {
+    return {
+      ops: [],
+      errors: [`Unknown aspect(s): ${unknown.join(', ')}. Valid: ${valid.join('/')}`]
+    }
+  }
+
+  // 모든 aspect 의 patch 를 하나로 병합 (한 refid 당 하나의 modify op)
+  const merged: any = {}
+  for (const a of input.aspects) {
+    Object.assign(merged, ASPECT_TO_PATCH[a])
+  }
+  if (Object.keys(merged).length === 0) {
+    return { ops: [], errors: ['No effective patch — try other aspects'] }
+  }
+
+  return {
+    ops: refids.map(refid => ({ op: 'modify', refid, patch: merged })),
+    errors: []
+  }
+}

package/server/service/styling/color-utils.test.ts

@@ -0,0 +1,130 @@
+/**
+ * color-utils — 다양한 색상 입력 → 정규 hex / alpha 분리.
+ *
+ * AI 가 다양한 자연어 / 형식으로 색상 표현 시 모두 안전 처리.
+ */
+import { parseColor, normalizeColor, validateColor } from './color-utils'
+
+describe('parseColor — hex', () => {
+  test('hex 6자리 정규화', () => {
+    expect(parseColor('#ff0000')).toEqual({ hex: '#ff0000', alpha: 1 })
+    expect(parseColor('#FF0000')).toEqual({ hex: '#ff0000', alpha: 1 })
+  })
+
+  test('hex 3자리 → 6자리 확장', () => {
+    expect(parseColor('#f00')).toEqual({ hex: '#ff0000', alpha: 1 })
+    expect(parseColor('#0Af')).toEqual({ hex: '#00aaff', alpha: 1 })
+  })
+
+  test('hex 8자리 → alpha 분리', () => {
+    expect(parseColor('#ff000080')).toEqual({ hex: '#ff0000', alpha: 0.502 })
+  })
+
+  test('hex 4자리 → 8자리 확장', () => {
+    expect(parseColor('#f00f')).toEqual({ hex: '#ff0000', alpha: 1 })
+  })
+
+  test('잘못된 hex → null', () => {
+    expect(parseColor('#zzz')).toBeNull()
+    expect(parseColor('#12345')).toBeNull()
+    expect(parseColor('##ff0000')).toBeNull()
+  })
+})
+
+describe('parseColor — rgb / rgba', () => {
+  test('rgb 정수', () => {
+    expect(parseColor('rgb(255, 0, 0)')).toEqual({ hex: '#ff0000', alpha: 1 })
+    expect(parseColor('rgb(0,128,255)')).toEqual({ hex: '#0080ff', alpha: 1 })
+  })
+
+  test('rgba 알파 포함', () => {
+    expect(parseColor('rgba(255, 0, 0, 0.5)')).toEqual({ hex: '#ff0000', alpha: 0.5 })
+    expect(parseColor('rgba(0,0,0,0)')).toEqual({ hex: '#000000', alpha: 0 })
+  })
+
+  test('범위 밖 — null', () => {
+    expect(parseColor('rgb(300, 0, 0)')).toBeNull()
+    expect(parseColor('rgba(0, 0, 0, 1.5)')).toBeNull()
+  })
+})
+
+describe('parseColor — named / semantic', () => {
+  test('CSS named — 기본', () => {
+    expect(parseColor('red')).toEqual({ hex: '#ff0000', alpha: 1 })
+    expect(parseColor('white')).toEqual({ hex: '#ffffff', alpha: 1 })
+    expect(parseColor('navy')).toEqual({ hex: '#000080', alpha: 1 })
+  })
+
+  test('CSS named — 대소문자 무관', () => {
+    expect(parseColor('RED')).toEqual({ hex: '#ff0000', alpha: 1 })
+    expect(parseColor('Red')).toEqual({ hex: '#ff0000', alpha: 1 })
+  })
+
+  test('semantic alias', () => {
+    expect(parseColor('warm-red')).toEqual({ hex: '#e74c3c', alpha: 1 })
+    expect(parseColor('forest-green')).toEqual({ hex: '#228b22', alpha: 1 })
+    expect(parseColor('success')).toEqual({ hex: '#22c55e', alpha: 1 })
+  })
+
+  test('알 수 없는 이름 → null', () => {
+    expect(parseColor('reddish')).toBeNull()
+    expect(parseColor('not-a-color')).toBeNull()
+  })
+})
+
+describe('parseColor — transparent / 특수', () => {
+  test('transparent', () => {
+    expect(parseColor('transparent')).toEqual({ hex: 'transparent', alpha: 0 })
+    expect(parseColor('none')).toEqual({ hex: 'transparent', alpha: 0 })
+  })
+
+  test('빈 문자열 / null / undefined', () => {
+    expect(parseColor('')).toBeNull()
+    expect(parseColor(null)).toBeNull()
+    expect(parseColor(undefined)).toBeNull()
+  })
+
+  test('공백 trim', () => {
+    expect(parseColor('  red  ')).toEqual({ hex: '#ff0000', alpha: 1 })
+    expect(parseColor('  #ff0000  ')).toEqual({ hex: '#ff0000', alpha: 1 })
+  })
+})
+
+describe('normalizeColor — 저장용 hex', () => {
+  test('정상 → 표준 hex', () => {
+    expect(normalizeColor('red')).toBe('#ff0000')
+    expect(normalizeColor('#F00')).toBe('#ff0000')
+    expect(normalizeColor('rgb(255,0,0)')).toBe('#ff0000')
+    expect(normalizeColor('warm-red')).toBe('#e74c3c')
+  })
+
+  test('실패 → null', () => {
+    expect(normalizeColor('invalid')).toBeNull()
+    expect(normalizeColor('')).toBeNull()
+  })
+})
+
+describe('validateColor — 정정 제안', () => {
+  test('정상 색상', () => {
+    expect(validateColor('red').valid).toBe(true)
+    expect(validateColor('#ff0000').valid).toBe(true)
+  })
+
+  test('잘못된 색상 — error 메시지 + suggestion', () => {
+    const r = validateColor('reddish')
+    expect(r.valid).toBe(false)
+    expect(r.error).toContain('Invalid color')
+    expect(r.suggestion).toBe('red')
+  })
+
+  test('완전 알 수 없는 색 — error 만', () => {
+    const r = validateColor('xyzabc')
+    expect(r.valid).toBe(false)
+    expect(r.error).toBeDefined()
+  })
+
+  test('null/undefined 안전', () => {
+    expect(validateColor(null).valid).toBe(false)
+    expect(validateColor(undefined).valid).toBe(false)
+  })
+})

package/server/service/styling/color-utils.ts

@@ -0,0 +1,226 @@
+/**
+ * Color 파싱 / 정규화 유틸 — styling tool 들이 공통으로 사용.
+ *
+ * AI 가 자연어로 색상 표현하는 다양한 형태를 받아 표준 hex 또는 rgba 로 변환.
+ *
+ * 지원 입력:
+ *   - hex 6자리:  '#ff0000', '#FF0000'
+ *   - hex 3자리:  '#f00'  (→ '#ff0000')
+ *   - hex 8자리:  '#ff0000ff' (alpha 포함)
+ *   - rgb / rgba: 'rgb(255,0,0)', 'rgba(255,0,0,0.5)'
+ *   - CSS named: 'red', 'transparent', ...
+ *   - 시맨틱 alias: 'warm-red', 'forest-green', ...
+ *
+ * 출력 형태:
+ *   - normalizeColor(): 표준 hex (#rrggbb), opacity 는 별개로 분리 반환
+ *   - validateColor():  유효성만 체크 (boolean + 에러 메시지)
+ */
+
+/** CSS named colors → hex (자주 쓰는 것만, 필요 시 확장) */
+const NAMED_COLORS: Record<string, string> = {
+  // 무채
+  white: '#ffffff',
+  black: '#000000',
+  gray: '#808080',
+  grey: '#808080',
+  silver: '#c0c0c0',
+  // 기본 컬러
+  red: '#ff0000',
+  green: '#008000',
+  blue: '#0000ff',
+  yellow: '#ffff00',
+  cyan: '#00ffff',
+  magenta: '#ff00ff',
+  orange: '#ffa500',
+  purple: '#800080',
+  pink: '#ffc0cb',
+  brown: '#a52a2a',
+  // 자주 쓰는 변형
+  navy: '#000080',
+  teal: '#008080',
+  lime: '#00ff00',
+  olive: '#808000',
+  maroon: '#800000',
+  // 투명
+  transparent: 'transparent'
+}
+
+/**
+ * 시맨틱 컬러 alias — AI 가 자연어 표현 사용 가능.
+ * Material 3 기반 톤 (brightness 적당, saturation 풍부).
+ */
+const SEMANTIC_COLORS: Record<string, string> = {
+  // warm reds
+  'warm-red': '#e74c3c',
+  'soft-red': '#ef4444',
+  'deep-red': '#b91c1c',
+  'dark-red': '#7f1d1d',
+  // greens
+  'forest-green': '#228b22',
+  'mint-green': '#10b981',
+  'olive-green': '#65a30d',
+  'lime-green': '#84cc16',
+  // blues
+  'sky-blue': '#0ea5e9',
+  'navy-blue': '#1e40af',
+  'royal-blue': '#3b82f6',
+  'powder-blue': '#bfdbfe',
+  // yellows / oranges
+  'amber': '#f59e0b',
+  'sunset-orange': '#f97316',
+  'gold': '#eab308',
+  'mustard': '#ca8a04',
+  // purples
+  'violet': '#7c3aed',
+  'lavender': '#c4b5fd',
+  // grays
+  'slate': '#64748b',
+  'charcoal': '#374151',
+  'cool-gray': '#6b7280',
+  'warm-gray': '#78716c',
+  // 시맨틱 의도
+  success: '#22c55e',
+  warning: '#f59e0b',
+  error: '#ef4444',
+  info: '#3b82f6'
+}
+
+/** Parse 결과 — color 와 alpha 분리. alpha 는 0..1. */
+export interface ParsedColor {
+  /** 표준 hex (#rrggbb, 소문자) 또는 'transparent' */
+  hex: string
+  /** Alpha 채널 0..1. transparent 면 0, 명시 alpha 없으면 1. */
+  alpha: number
+}
+
+/**
+ * 색상 입력을 정규 hex + alpha 로 변환.
+ * 잘못된 입력은 null — 호출자가 에러 처리.
+ */
+export function parseColor(input: string | null | undefined): ParsedColor | null {
+  if (typeof input !== 'string') return null
+  const s = input.trim().toLowerCase()
+  if (s.length === 0) return null
+
+  // transparent
+  if (s === 'transparent' || s === 'none') {
+    return { hex: 'transparent', alpha: 0 }
+  }
+
+  // hex
+  if (s.startsWith('#')) {
+    return parseHex(s)
+  }
+
+  // rgb / rgba
+  const rgbMatch = s.match(/^rgba?\s*\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/)
+  if (rgbMatch) {
+    const r = clampByte(rgbMatch[1])
+    const g = clampByte(rgbMatch[2])
+    const b = clampByte(rgbMatch[3])
+    const a = rgbMatch[4] !== undefined ? clampUnit(rgbMatch[4]) : 1
+    if (r === null || g === null || b === null || a === null) return null
+    return { hex: rgbToHex(r, g, b), alpha: a }
+  }
+
+  // CSS named
+  if (NAMED_COLORS[s]) {
+    return parseHex(NAMED_COLORS[s])
+  }
+
+  // 시맨틱 alias
+  if (SEMANTIC_COLORS[s]) {
+    return parseHex(SEMANTIC_COLORS[s])
+  }
+
+  return null
+}
+
+function parseHex(s: string): ParsedColor | null {
+  const hex = s.startsWith('#') ? s.slice(1) : s
+  if (hex === 'transparent') return { hex: 'transparent', alpha: 0 }
+
+  if (!/^[0-9a-f]+$/i.test(hex)) return null
+
+  if (hex.length === 3) {
+    // #abc → #aabbcc
+    const r = hex[0] + hex[0]
+    const g = hex[1] + hex[1]
+    const b = hex[2] + hex[2]
+    return { hex: `#${r}${g}${b}`.toLowerCase(), alpha: 1 }
+  }
+  if (hex.length === 4) {
+    // #abcd → #aabbccdd
+    const r = hex[0] + hex[0]
+    const g = hex[1] + hex[1]
+    const b = hex[2] + hex[2]
+    const a = parseInt(hex[3] + hex[3], 16) / 255
+    return { hex: `#${r}${g}${b}`.toLowerCase(), alpha: round3(a) }
+  }
+  if (hex.length === 6) {
+    return { hex: `#${hex}`.toLowerCase(), alpha: 1 }
+  }
+  if (hex.length === 8) {
+    const rgb = hex.slice(0, 6)
+    const a = parseInt(hex.slice(6, 8), 16) / 255
+    return { hex: `#${rgb}`.toLowerCase(), alpha: round3(a) }
+  }
+  return null
+}
+
+function clampByte(s: string): number | null {
+  const n = Number(s)
+  if (!Number.isFinite(n) || n < 0 || n > 255) return null
+  return Math.round(n)
+}
+
+function clampUnit(s: string): number | null {
+  const n = Number(s)
+  if (!Number.isFinite(n) || n < 0 || n > 1) return null
+  return n
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  const h = (n: number) => n.toString(16).padStart(2, '0')
+  return `#${h(r)}${h(g)}${h(b)}`
+}
+
+function round3(n: number): number {
+  return Math.round(n * 1000) / 1000
+}
+
+/**
+ * 단순 검증 — 정규화 가능 여부만.
+ * 에러 메시지에 정정 제안 포함 가능.
+ */
+export function validateColor(input: string | null | undefined): {
+  valid: boolean
+  error?: string
+  suggestion?: string
+} {
+  if (typeof input !== 'string') {
+    return { valid: false, error: 'Color must be a string.' }
+  }
+  const parsed = parseColor(input)
+  if (parsed) return { valid: true }
+
+  // 비슷한 named color 추천
+  const lower = input.trim().toLowerCase()
+  const allKnown = [...Object.keys(NAMED_COLORS), ...Object.keys(SEMANTIC_COLORS)]
+  const close = allKnown.find(k => k.includes(lower) || lower.includes(k))
+  return {
+    valid: false,
+    error: `Invalid color: '${input}'. Use hex (#ff0000), rgb(255,0,0), or named (red, warm-red, ...).`,
+    suggestion: close
+  }
+}
+
+/**
+ * 색상을 hex 문자열로 정규화 (저장용).
+ * 실패 시 null.
+ */
+export function normalizeColor(input: string | null | undefined): string | null {
+  const parsed = parseColor(input)
+  if (!parsed) return null
+  return parsed.hex
+}