@things-factory/ai-assistant 10.1.6

package/client/components/mention-popup-helpers.ts

@@ -0,0 +1,433 @@
+/**
+ * Mention popup pure helpers — Lit / DOM 의존 없음. 단위 테스트 가능.
+ *
+ * Lit 엘리먼트 (ox-mention-popup) 와 분리 — jest 의 node 환경에서 'lit' import 가
+ * ESM 변환 없이 실패하므로 chat-input-builder 패턴과 동일하게 helper 분리.
+ */
+
+export interface MentionCandidate {
+  /** popup 에 보일 1차 식별 라벨 */
+  label: string
+  /** 카테고리 — 컴포넌트 type / 카탈로그 kind ('prefab'/'palette'/'layout') / 'template' / 'user' */
+  type: string
+  /** 컴포넌트 후보 — things-scene refid (popup 표시 안 함, AI 내부 reference) */
+  refid?: number
+  /** 사용자 멘션 후보 — 도메인 사용자 id (UUID). popup 표시 안 함. */
+  userId?: string
+  /** 사용자 멘션 후보 — 이메일 (라벨 부가 정보 / 검색 대상) */
+  email?: string
+  /** 선택 시 trigger+label 대신 삽입할 전체 텍스트 (slash template 용) */
+  replacementText?: string
+  /** F-Finder 검색 필드 — things-scene 컴포넌트의 실제 키. 'name' 없음. */
+  id?: string
+  tag?: string
+  class?: string
+  text?: string
+  /** 카탈로그/슬래시 후보용 — description 도 검색 대상 */
+  description?: string
+}
+
+/** filter 결과 — 매칭됐을 때만 matchType + matchValue 동봉.
+ *  matchType union 은 things-scene SearchResult 와 동일 (id/name/tag/type/class/
+ *  text/data/property) + 자체 'description' (catalog/slash). */
+export interface FilterResult {
+  candidate: MentionCandidate
+  matchType?:
+    | 'id'
+    | 'name'
+    | 'tag'
+    | 'type'
+    | 'class'
+    | 'text'
+    | 'data'
+    | 'property'
+    | 'description'
+  matchValue?: string
+}
+
+/** 검색 시 시도할 field 순서.
+ *   - 컴포넌트: id 우선 (F-Finder 와 동일 — id/tag/type/class/text)
+ *   - user 후보: id 없으니 label/email 로 매칭
+ *   - catalog/slash: label/description 로 매칭
+ *
+ * 'label' 이 fallback 으로 들어있어 모든 candidate 가 최소 1개 매칭 가능. */
+const SEARCH_FIELDS: Array<{
+  key: keyof MentionCandidate
+  type: NonNullable<FilterResult['matchType']>
+}> = [
+  { key: 'id', type: 'id' },
+  { key: 'label', type: 'name' },
+  { key: 'email', type: 'data' },
+  { key: 'tag', type: 'tag' },
+  { key: 'type', type: 'type' },
+  { key: 'class', type: 'class' },
+  { key: 'text', type: 'text' },
+  { key: 'description', type: 'description' }
+]
+
+/**
+ * 보드의 컴포넌트를 popup 후보로 변환. things-scene 컴포넌트 state 키만 사용:
+ * id / type / tag / class / text. 'name' 같은 별도 개념 도입 안 함.
+ *
+ * Label: id 있으면 id, 없으면 type. refid 는 popup 에 표시 안 함 (시스템 핸들).
+ */
+export function buildMentionCandidates(components: any): MentionCandidate[] {
+  const list = Array.isArray(components) ? components : []
+  const out: MentionCandidate[] = []
+  for (const c of list) {
+    if (!c || typeof (c as any).refid !== 'number') continue
+    const refid = (c as any).refid
+    const id = strField(c, 'id')
+    const type = typeof (c as any).type === 'string' ? (c as any).type : 'unknown'
+    const tag = strField(c, 'tag')
+    const cls = strField(c, 'class')
+    const text = strField(c, 'text')
+    const label = id || type
+    out.push({ refid, label, type, id, tag, class: cls, text })
+  }
+  return out
+}
+
+function strField(c: any, key: string): string | undefined {
+  const v = c[key]
+  return typeof v === 'string' && v.length > 0 ? v : undefined
+}
+
+// ── User (`@`) 후보 ─────────────────────────────────────────────────
+
+/**
+ * 도메인 사용자 → MentionCandidate. server `domainUsersForMention` 결과를 popup 표시용
+ * 으로 변환.
+ *   - label   : 화면 표시 + textarea 삽입 토큰 (공백 / 비-단어 문자 불가 → 이메일 username 으로
+ *               fallback 또는 underscore 치환)
+ *   - userId  : 영속용 UUID (inline marker `{userId:UUID}` 로 박힘)
+ *
+ * mention 토큰 정규식은 word char 만 허용하므로 공백 / 점 / 하이픈 같은 문자 들어간 name 은
+ * 그대로 쓰면 토큰이 첫 단어에서 끊김. 안전한 토큰 우선순위:
+ *   1. name (공백 / 비-단어 문자 없음)
+ *   2. email 의 username (공백 / 비-단어 문자 없음)
+ *   3. name 의 공백을 underscore 로 치환
+ *   4. id (UUID — 마지막 폴백)
+ */
+export function buildUserCandidates(
+  users: ReadonlyArray<{ id: string; name?: string | null; email?: string | null }>
+): MentionCandidate[] {
+  const out: MentionCandidate[] = []
+  for (const u of users) {
+    if (!u || typeof u.id !== 'string') continue
+    const name = typeof u.name === 'string' && u.name.trim() ? u.name.trim() : undefined
+    const email = typeof u.email === 'string' && u.email.trim() ? u.email.trim() : undefined
+    out.push({
+      label: deriveUserToken(u.id, name, email),
+      type: 'user',
+      userId: u.id,
+      email
+    })
+  }
+  return out
+}
+
+/** 토큰 안전 검사 — mention 정규식 (word char + 한/일/중) 으로만 구성됐는지. */
+function isSafeMentionToken(s: string): boolean {
+  return /^[\w\p{Script=Hangul}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}-]+$/u.test(s)
+}
+
+function deriveUserToken(id: string, name?: string, email?: string): string {
+  if (name && isSafeMentionToken(name)) return name
+  if (email) {
+    const local = email.split('@')[0]
+    if (local && isSafeMentionToken(local)) return local
+  }
+  if (name) {
+    // 공백 / 비-단어 문자 underscore 치환 — 시각적 우선순위 유지
+    const sanitized = name.replace(/[^\w\p{Script=Hangul}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}-]+/gu, '_')
+    if (sanitized.length > 0) return sanitized
+  }
+  return id
+}
+
+// ── Catalog (`/` 와 함께) 후보 ──────────────────────────────────────
+
+export interface CatalogEntry {
+  /** 카탈로그 식별자 — '@token' 으로 사용 + addPrefab/modifyBoard 인자에 전달 */
+  name: string
+  /** 종류 — UI 표시 + server-side disambiguation 과 일치 */
+  kind: 'prefab' | 'palette' | 'layout'
+  /** 한 줄 설명 (사용자 popup 에 보임) */
+  description?: string
+}
+
+/**
+ * 카탈로그 항목 묶음 → MentionCandidate[]. 클라이언트가 chat panel mount 시 1회만
+ * 빌드 후 캐시. 이름 + kind 가 unique 여야 함 — 동일 name 다른 kind 는 카탈로그
+ * resolver 가 disambiguation 처리.
+ *
+ * 정렬: kind 우선 (prefab → palette → layout), 그 안에서 name asc.
+ */
+export function buildCatalogCandidates(entries: CatalogEntry[]): MentionCandidate[] {
+  const KIND_ORDER: Record<string, number> = { prefab: 0, palette: 1, layout: 2 }
+  const sorted = entries.slice().sort((a, b) => {
+    const ka = KIND_ORDER[a.kind] ?? 99
+    const kb = KIND_ORDER[b.kind] ?? 99
+    if (ka !== kb) return ka - kb
+    return a.name.localeCompare(b.name)
+  })
+  return sorted.map(e => ({
+    label: e.name,
+    type: e.kind,
+    description: e.description
+  }))
+}
+
+// ── Slash (`/`) 템플릿 ──────────────────────────────────────────────
+
+export interface SlashTemplate {
+  /** 식별자 — '/grid' 의 'grid'. trigger 빠진 형태 */
+  name: string
+  /** 사용자에게 보일 한 줄 설명 */
+  description?: string
+  /** 선택 시 textarea 에 삽입될 전체 자연어 텍스트 (trigger+name 영역 교체) */
+  template: string
+}
+
+/**
+ * Slash template 묶음 → MentionCandidate[] (replacementText 사용).
+ *
+ * 정렬: name asc.
+ *
+ * Slash 는 component/catalog 와 달리 LLM 우회 명령이 아니라 사용자에게 미리 작성된
+ * 자연어 prompt 를 빠르게 끼워넣는 용도. AI 는 변환 결과를 그대로 자연어로 처리.
+ */
+export function buildSlashCandidates(templates: SlashTemplate[]): MentionCandidate[] {
+  const sorted = templates.slice().sort((a, b) => a.name.localeCompare(b.name))
+  return sorted.map(t => ({
+    label: t.name,
+    type: 'template',
+    description: t.description,
+    replacementText: t.template
+  }))
+}
+
+/**
+ * cursor 직전의 trigger char (`#` or `@`) + token 추출. popup 활성 여부 판단.
+ *
+ * 활성 조건:
+ *   - cursor 이전에 trigger 가 존재
+ *   - trigger 와 cursor 사이에 공백 / 줄바꿈 / 동일 trigger 없음
+ *   - trigger 직전이 문자열 시작 또는 공백/줄바꿈/구두점 (단어 중간 trigger 무시)
+ *
+ * 반환 — 활성 시 { hashPos, query } (hashPos 는 trigger 위치 — # 또는 @) /
+ * 비활성 시 null.
+ *
+ * trigger default '#' — 기존 호출자 호환.
+ */
+export function extractMentionContext(
+  text: string,
+  cursorPos: number,
+  trigger: string = '#'
+): { hashPos: number; query: string } | null {
+  if (!text || cursorPos < 0 || cursorPos > text.length) return null
+  if (!trigger || trigger.length !== 1) return null
+  // cursor 에서 뒤로 이동하며 trigger 찾기 — 공백/줄바꿈 만나면 중단
+  let i = cursorPos - 1
+  while (i >= 0) {
+    const ch = text.charAt(i)
+    if (ch === trigger) break
+    if (ch === ' ' || ch === '\n' || ch === '\t') return null
+    i--
+  }
+  if (i < 0) return null
+  // i 가 trigger 위치. 직전 글자 검사 (단어 중간 trigger 거부)
+  if (i > 0) {
+    const prev = text.charAt(i - 1)
+    // 알파벳/숫자/한글 같은 word char 직후는 mention 으로 안 봄 (예: 'foo#bar', 'user@host')
+    if (!/[\s\n\t.,!?;:()[\]{}'"`]/.test(prev)) return null
+  }
+  return { hashPos: i, query: text.slice(i + 1, cursorPos) }
+}
+
+/**
+ * query 로 후보 필터 — F-Finder 스타일 multi-field.
+ *
+ * 검색 문법:
+ *   - 빈 query → 전체 반환 (cap 까지). matchType: 'label', matchValue: candidate.label
+ *   - 자유 substring → 우선순위 (id > name > tag > type > class > text > label > description)
+ *     로 첫 매치 필드 발견. matchType + matchValue 동봉
+ *   - field:value → 해당 field 만 매칭
+ *     * `id:` / `i:` — id
+ *     * `name:` / `n:` — name
+ *     * `type:` / `t:` — type
+ *     * `tag:` — tag (신규)
+ *     * `class:` / `c:` — class (신규)
+ *     * `text:` — text (신규)
+ *
+ * cap default 50 (F-Finder 표준). label 길이 짧은 순 정렬.
+ */
+export function filterMentionCandidates(
+  candidates: MentionCandidate[],
+  query: string,
+  cap = 50
+): FilterResult[] {
+  // Empty query / 'type:' 같은 빈 needle 도 일반 매칭 경로와 동일 로직.
+  // 각 candidate 의 가장 prominent 한 field 를 default match 로 — 모든 행이
+  // 항상 동일 layout (badge + label + value 가능 시) 으로 일관 표시.
+  if (!query) {
+    return candidates.slice(0, cap).map(c => defaultMatchFor(c))
+  }
+  const parsed = parseQuery(query)
+  if (parsed.field && !parsed.needle) {
+    // 'type:' 만 입력 — 전체 반환, 일반 default
+    return candidates.slice(0, cap).map(c => defaultMatchFor(c))
+  }
+
+  const out: FilterResult[] = []
+  if (parsed.field) {
+    const fieldKey = parsed.field
+    for (const c of candidates) {
+      const v = c[fieldKey]
+      if (typeof v === 'string' && v.toLowerCase().includes(parsed.needle)) {
+        out.push({ candidate: c, matchType: parsed.field, matchValue: v })
+      }
+    }
+  } else {
+    // 자유 검색 — 우선순위 필드 순회, 첫 매치 찾으면 break
+    const q = parsed.needle
+    for (const c of candidates) {
+      for (const f of SEARCH_FIELDS) {
+        const v = c[f.key]
+        if (typeof v === 'string' && v.toLowerCase().includes(q)) {
+          out.push({ candidate: c, matchType: f.type, matchValue: v })
+          break
+        }
+      }
+    }
+  }
+  out.sort((a, b) => a.candidate.label.length - b.candidate.label.length)
+  return out.slice(0, cap)
+}
+
+/**
+ * Candidate 의 default match — 우선순위 (id → name → tag → type → ...) 로 첫 non-empty
+ * field 를 matchType + matchValue 로 사용. Empty query 시 popup row 가 filter 시와
+ * 같은 layout 으로 보이도록 (badge + label + value).
+ */
+function defaultMatchFor(c: MentionCandidate): FilterResult {
+  for (const f of SEARCH_FIELDS) {
+    const v = c[f.key]
+    if (typeof v === 'string' && v.length > 0) {
+      return { candidate: c, matchType: f.type, matchValue: v }
+    }
+  }
+  // 모든 field 비어있는 희귀 케이스 — matchType 없이 그냥 candidate
+  return { candidate: c }
+}
+
+/**
+ * query 를 'field:value' 형태로 파싱.
+ * field 가 인식되지 않으면 자유 검색 (field=undefined).
+ */
+function parseQuery(query: string): {
+  field?: 'id' | 'type' | 'tag' | 'class' | 'text'
+  needle: string
+} {
+  const m = /^([a-zA-Z]+):(.*)$/.exec(query)
+  if (m) {
+    const f = m[1].toLowerCase()
+    const map: Record<string, 'id' | 'type' | 'tag' | 'class' | 'text'> = {
+      i: 'id',
+      id: 'id',
+      t: 'type',
+      type: 'type',
+      tag: 'tag',
+      c: 'class',
+      class: 'class',
+      text: 'text'
+    }
+    if (map[f]) {
+      return { field: map[f], needle: m[2].toLowerCase() }
+    }
+  }
+  return { needle: query.toLowerCase() }
+}
+
+// ── Click resolve (메시지 버블의 #token 클릭 → refid) ──────────────
+
+export interface ResolveMentionTokenOptions {
+  /** 메시지 버블의 `<span data-refid>` 값. 작성 시점에 박제된 refid (가장 정확). */
+  persistedRefid?: string | null
+  /** 호스트의 SceneSearchEngine 위임 — 작성 시점 refid 없거나 stale 일 때 fallback. */
+  searchProvider?: (query: string) => FilterResult[]
+  /** 보드 모델 — components.find(id) 직접 매칭 최후 fallback. */
+  board?: { components?: any[] } | null
+}
+
+/**
+ * `#token` 클릭 시 token → refid resolve. 우선순위:
+ *   1. `persistedRefid` (data-refid 속성, 작성 시점 박제)
+ *   2. `searchProvider` — 'id' 정확 일치 → 첫 결과
+ *   3. `board.components.find(c => c.id === token)` — id 직접 매칭
+ *
+ * 모두 실패하면 `undefined`. UI 측에서 not-found 처리 (toast 등).
+ *
+ * Pure 함수 — DOM/Lit 의존 없음, 단위 테스트 가능.
+ */
+export function resolveMentionToken(
+  token: string,
+  opts: ResolveMentionTokenOptions
+): number | undefined {
+  if (!token) return undefined
+
+  // 1. 작성 시점 박제 refid
+  if (opts.persistedRefid) {
+    const n = Number(opts.persistedRefid)
+    if (Number.isFinite(n)) return n
+  }
+
+  // 2. searchProvider — 'id' 정확 일치 우선
+  if (opts.searchProvider) {
+    const results = opts.searchProvider(token)
+    const exact = results.find(
+      r => r.matchType === 'id' && r.matchValue === token
+    )
+    const hit = (exact ?? results[0])?.candidate.refid
+    if (typeof hit === 'number' && Number.isFinite(hit)) return hit
+  }
+
+  // 3. board.components — id 직접 매칭
+  const components = opts.board?.components
+  if (Array.isArray(components)) {
+    const hit = components.find((c: any) => c?.id === token)
+    if (hit && typeof hit.refid === 'number' && Number.isFinite(hit.refid)) {
+      return hit.refid
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * 선택된 후보로 textarea text 갱신 — trigger + query 영역을 교체.
+ *
+ * 두 모드:
+ *   - 일반 (component / catalog): trigger + label + 공백 으로 교체
+ *   - slash template: candidate.replacementText 가 있으면 그걸로 통째 교체
+ *
+ * 새 cursor 위치도 같이 반환.
+ *
+ * trigger default '#' — 기존 호출자 호환.
+ */
+export function applyMentionSelection(
+  text: string,
+  cursorPos: number,
+  hashPos: number,
+  candidate: MentionCandidate,
+  trigger: string = '#'
+): { text: string; cursorPos: number } {
+  const before = text.slice(0, hashPos)
+  const after = text.slice(cursorPos)
+  const insert = candidate.replacementText ?? `${trigger}${candidate.label} `
+  return {
+    text: before + insert + after,
+    cursorPos: before.length + insert.length
+  }
+}