@jogak/ui 0.1.0-alpha.1 → 0.1.0-alpha.10.3

package/src/components/Preview/IframeMount.tsx

@@ -0,0 +1,101 @@
+import { useEffect, useRef, useState } from 'react'
+import type { ReactElement } from 'react'
+import type { RegistryEntry } from '@jogak/core'
+
+export interface IframeMountProps {
+  readonly entry: RegistryEntry
+  readonly args: Readonly<Record<string, unknown>>
+  /**
+   * 알파.9: 어댑터 dev URL (예: `http://localhost:5174`).
+   * 빈 문자열 시 fallback (jogak SPA Vite scope의 `/preview-frame.html`).
+   */
+  readonly userPreviewUrl: string
+  /**
+   * 알파.9: iframe entry path (예: `/__jogak_preview__/index.html`).
+   * 어댑터의 `previewEntryMeta.devEntryPath`.
+   */
+  readonly previewEntryPath: string
+  readonly className?: string
+  readonly 'data-testid'?: string
+}
+
+/**
+ * 알파.8: previewIsolation='iframe' 모드의 mount 컴포넌트.
+ *
+ * 통신:
+ * - 사용자 vite spawn URL이 주어지면(`userViteUrl !== ''`) iframe src를
+ *   `${userViteUrl}/__jogak_preview__/index.html` (cross-origin)로 설정.
+ * - 동일 origin fallback 시 `/preview-frame.html` (jogak SPA Vite scope).
+ *
+ * 양쪽 모두 postMessage로 통신:
+ * - 부모 → iframe: `{ type: 'jogak:setProps', entryId, args }` | `{ type: 'jogak:unmount' }`
+ * - iframe → 부모: `{ type: 'jogak:ready' }` | `{ type: 'jogak:rendered', entryId }`
+ *
+ * `entry`는 객체가 아닌 **id만 전달** — iframe 안에서 `defaultRegistry.requestEntry(id)`로
+ * dynamic import. 사용자 vite scope의 entry 가상 모듈이 사용자 컴포넌트를 fetch하므로
+ * 사용자 plugins(@tailwindcss/vite, custom alias 등)이 정상 작동.
+ */
+export function IframeMount({
+  entry,
+  args,
+  userPreviewUrl,
+  previewEntryPath,
+  className,
+  'data-testid': dataTestId,
+}: IframeMountProps): ReactElement {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null)
+  const [ready, setReady] = useState(false)
+
+  const src =
+    userPreviewUrl !== ''
+      ? `${userPreviewUrl}${previewEntryPath}`
+      : '/preview-frame.html'
+
+  // postMessage 리스너 — iframe contentWindow 일치성 검증 후 처리.
+  useEffect(() => {
+    const handler = (event: MessageEvent): void => {
+      const iframe = iframeRef.current
+      if (iframe === null) return
+      if (event.source !== iframe.contentWindow) return
+      const data = event.data
+      if (data == null || typeof data !== 'object') return
+      if (data.type === 'jogak:ready') setReady(true)
+    }
+    window.addEventListener('message', handler)
+    return () => {
+      window.removeEventListener('message', handler)
+    }
+  }, [])
+
+  // iframe ready 또는 entry/args 변경 시 setProps.
+  useEffect(() => {
+    if (!ready) return
+    const iframe = iframeRef.current
+    if (iframe === null) return
+    iframe.contentWindow?.postMessage(
+      { type: 'jogak:setProps', entryId: entry.id, args },
+      '*',
+    )
+  }, [ready, entry, args])
+
+  // unmount 시 unmount 메시지 (race 회피 microtask defer).
+  useEffect(() => {
+    const iframe = iframeRef.current
+    return () => {
+      if (iframe === null) return
+      queueMicrotask(() => {
+        iframe.contentWindow?.postMessage({ type: 'jogak:unmount' }, '*')
+      })
+    }
+  }, [])
+
+  return (
+    <iframe
+      ref={iframeRef}
+      src={src}
+      title="Preview"
+      className={className}
+      data-testid={dataTestId}
+    />
+  )
+}

package/src/components/Preview/ShadowMount.tsx

@@ -0,0 +1,57 @@
+import { useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { ReactElement, ReactNode, CSSProperties } from 'react'
+
+export interface ShadowMountProps {
+  readonly children: ReactNode
+  readonly className?: string
+  readonly style?: CSSProperties
+  readonly 'data-testid'?: string
+}
+
+/**
+ * 알파.7.1: previewIsolation='shadow' 모드의 mount 컴포넌트.
+ *
+ * 책임: 양방향 격리만 제공 (Preview ↔ outer document 양방향 cascade 차단).
+ * - 사용자 globalCss는 main.tsx 가드로 outer document에 inject되지 않음.
+ * - shadow root 안에는 jogak chrome css도 사용자 css도 없음 (둘 다 외부에서 격리).
+ * - 사용자 컴포넌트의 utility class 컴파일은 결함 B (알파.8 사이클).
+ *
+ * 알파.7 결함 정정:
+ * - `syncStyleSheets`/`MutationObserver`/`adoptedStyleSheets` 흡수 로직 제거.
+ *   알파.7은 outer document에 사용자 css가 있는 한 chrome을 침범했고, shadow
+ *   안의 흡수 로직은 의미가 없었음. 알파.7.1: outer에 사용자 css 자체가 없음.
+ *
+ * Radix portal 한계 (사용자 인지 필요, README 명시):
+ * - default Portal target = document.body (shadow 외부). 사용자가 명시적으로
+ *   `<Portal container={shadowRootEl}>`을 전달해야 portal 내용도 격리됨.
+ */
+export function ShadowMount({
+  children,
+  className,
+  style,
+  'data-testid': dataTestId,
+}: ShadowMountProps): ReactElement {
+  const hostRef = useRef<HTMLDivElement | null>(null)
+  const [shadowRoot, setShadowRoot] = useState<ShadowRoot | null>(null)
+
+  useEffect(() => {
+    const host = hostRef.current
+    if (host === null) return
+    const sr = host.shadowRoot ?? host.attachShadow({ mode: 'open' })
+    setShadowRoot(sr)
+    // shadow root는 host element와 함께 GC — 명시 detach 불필요.
+  }, [])
+
+  return (
+    <div
+      ref={hostRef}
+      className={className}
+      data-testid={dataTestId}
+      // eslint-disable-next-line no-restricted-syntax -- jogak: ShadowMount caller-supplied style passthrough (host wrapper, content goes through ShadowRoot portal)
+      style={style}
+    >
+      {shadowRoot !== null ? createPortal(children, shadowRoot) : null}
+    </div>
+  )
+}

package/src/components/Preview/format-usage.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import type { RegistryEntry } from '@jogak/core'
+import { formatUsageCode } from './format-usage.js'
+
+function makeEntry(componentName: string, title = 'UI/Demo'): RegistryEntry {
+  function Demo(): null {
+    return null
+  }
+  Object.defineProperty(Demo, 'name', { value: componentName })
+  return {
+    id: title,
+    title,
+    jogaks: [],
+    meta: { title, component: Demo, argTypes: {} },
+    source: '',
+    filePath: '',
+  }
+}
+
+describe('formatUsageCode', () => {
+  it('children 문자열 → 단일 라인', () => {
+    const entry = makeEntry('Badge')
+    expect(formatUsageCode(entry, { children: 'New', variant: 'default' })).toBe(
+      '<Badge variant="default">New</Badge>',
+    )
+  })
+
+  it('children 없음 → self-closing', () => {
+    const entry = makeEntry('Card')
+    expect(formatUsageCode(entry, { title: 'Hello' })).toBe(
+      '<Card title="Hello" />',
+    )
+  })
+
+  it('boolean true → key only, false → key={false}', () => {
+    const entry = makeEntry('Toggle')
+    expect(formatUsageCode(entry, { disabled: true, checked: false })).toBe(
+      '<Toggle disabled checked={false} />',
+    )
+  })
+
+  it('number → 중괄호 표현', () => {
+    const entry = makeEntry('Counter')
+    expect(formatUsageCode(entry, { count: 42 })).toBe('<Counter count={42} />')
+  })
+
+  it('function → key={fn}', () => {
+    const entry = makeEntry('Button')
+    expect(
+      formatUsageCode(entry, { onClick: () => undefined, label: 'Go' }),
+    ).toBe('<Button onClick={fn} label="Go" />')
+  })
+
+  it('객체/배열 → JSON 표현', () => {
+    const entry = makeEntry('List')
+    expect(formatUsageCode(entry, { items: [1, 2, 3] })).toBe(
+      '<List items={[1,2,3]} />',
+    )
+  })
+
+  it('children에 number → JSX 표현', () => {
+    const entry = makeEntry('Counter')
+    expect(formatUsageCode(entry, { children: 7 })).toBe(
+      '<Counter>{7}</Counter>',
+    )
+  })
+
+  it('component name 없으면 title의 마지막 segment 사용', () => {
+    const entry: RegistryEntry = {
+      id: 'UI/Anonymous',
+      title: 'UI/Anonymous',
+      jogaks: [],
+      meta: {
+        title: 'UI/Anonymous',
+        component: undefined,
+        argTypes: {},
+      },
+      source: '',
+      filePath: '',
+    }
+    expect(formatUsageCode(entry, { children: 'X' })).toBe(
+      '<Anonymous>X</Anonymous>',
+    )
+  })
+
+  it('많은 props → multi-line 포맷', () => {
+    const entry = makeEntry('Form')
+    const out = formatUsageCode(entry, {
+      title: 'Long descriptive title',
+      description: 'Another lengthy text value',
+      disabled: false,
+      autoFocus: true,
+    })
+    expect(out).toContain('\n')
+    expect(out.startsWith('<Form\n  ')).toBe(true)
+    expect(out.endsWith('/>')).toBe(true)
+  })
+
+  it('따옴표 escape', () => {
+    const entry = makeEntry('Label')
+    expect(formatUsageCode(entry, { text: 'He said "hi"' })).toBe(
+      '<Label text="He said &quot;hi&quot;" />',
+    )
+  })
+
+  it('children + props 모두 multi-line으로 ', () => {
+    const entry = makeEntry('Card')
+    const out = formatUsageCode(entry, {
+      title: 'A long title',
+      description: 'A long description',
+      children: 'Body content',
+    })
+    expect(out).toMatch(/^<Card\n {2}title="A long title"\n {2}description="A long description"\n>\n {2}Body content\n<\/Card>$/u)
+  })
+})

package/src/components/Preview/format-usage.ts

@@ -0,0 +1,129 @@
+/**
+ * 알파.10.3: 컴포넌트 사용 코드 포매터.
+ *
+ * 코드 패널에는 `.jogak.tsx` 파일 전체가 아니라, 현재 args 기반의 사용 스니펫을 노출한다.
+ * 사용자가 Controls 패널에서 args를 바꾸면 즉시 갱신된다.
+ *
+ * 출력 예:
+ *   <Badge variant="default">New</Badge>
+ *
+ *   <Card
+ *     title="Hello"
+ *     disabled
+ *     onClick={fn}
+ *   />
+ */
+
+import type { RegistryEntry } from '@jogak/core'
+
+const SINGLE_LINE_THRESHOLD = 60
+
+/**
+ * `entry` + 현재 `args`로부터 JSX 사용 코드를 생성한다.
+ * children은 태그 본문에, 나머지 props는 attribute로.
+ */
+export function formatUsageCode(
+  entry: RegistryEntry,
+  args: Readonly<Record<string, unknown>>,
+): string {
+  const componentName = resolveComponentName(entry)
+  const { children, restProps } = splitChildren(args)
+
+  const propTokens = Object.entries(restProps)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => formatProp(k, v))
+
+  const childrenStr = formatChildren(children)
+  const hasChildren = childrenStr !== null
+
+  // single-line 시도
+  const inlineProps = propTokens.length === 0 ? '' : ' ' + propTokens.join(' ')
+  const singleLine = hasChildren
+    ? `<${componentName}${inlineProps}>${childrenStr ?? ''}</${componentName}>`
+    : `<${componentName}${inlineProps} />`
+
+  if (singleLine.length <= SINGLE_LINE_THRESHOLD && !singleLine.includes('\n')) {
+    return singleLine
+  }
+
+  // multi-line — 각 prop을 별도 줄에
+  const indentedProps =
+    propTokens.length === 0 ? '' : '\n  ' + propTokens.join('\n  ') + '\n'
+  if (hasChildren) {
+    const indentedChildren = (childrenStr ?? '')
+      .split('\n')
+      .map((line) => `  ${line}`)
+      .join('\n')
+    return `<${componentName}${indentedProps}>\n${indentedChildren}\n</${componentName}>`
+  }
+  return `<${componentName}${indentedProps}/>`
+}
+
+function resolveComponentName(entry: RegistryEntry): string {
+  const component = entry.meta.component as
+    | { displayName?: unknown; name?: unknown }
+    | undefined
+  if (component !== undefined) {
+    if (typeof component.displayName === 'string' && component.displayName.length > 0) {
+      return component.displayName
+    }
+    if (typeof component.name === 'string' && component.name.length > 0) {
+      return component.name
+    }
+  }
+  // fallback: title의 마지막 segment ("UI/Badge" → "Badge")
+  const lastSeg = entry.title.split('/').pop()
+  return lastSeg !== undefined && lastSeg.length > 0 ? lastSeg : 'Component'
+}
+
+interface SplitChildrenResult {
+  readonly children: unknown
+  readonly restProps: Readonly<Record<string, unknown>>
+}
+
+function splitChildren(args: Readonly<Record<string, unknown>>): SplitChildrenResult {
+  const { children, ...rest } = args as { children?: unknown } & Record<string, unknown>
+  return { children, restProps: rest }
+}
+
+function formatChildren(children: unknown): string | null {
+  if (children === undefined || children === null) return null
+  if (typeof children === 'string') {
+    if (children.length === 0) return null
+    return children
+  }
+  if (typeof children === 'number' || typeof children === 'bigint') {
+    return `{${children.toString()}}`
+  }
+  if (typeof children === 'boolean') {
+    return null
+  }
+  // 복합 타입(object/array/function): JSON 표현
+  return `{${stringifyValue(children)}}`
+}
+
+function formatProp(key: string, value: unknown): string {
+  if (value === true) return key
+  if (value === false) return `${key}={false}`
+  if (value === null) return `${key}={null}`
+  if (typeof value === 'string') {
+    // 따옴표 escape
+    const escaped = value.replace(/"/gu, '&quot;')
+    return `${key}="${escaped}"`
+  }
+  if (typeof value === 'number' || typeof value === 'bigint') {
+    return `${key}={${value.toString()}}`
+  }
+  if (typeof value === 'function') {
+    return `${key}={fn}`
+  }
+  return `${key}={${stringifyValue(value)}}`
+}
+
+function stringifyValue(value: unknown): string {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}