@jogak/ui 0.1.0-alpha.12 → 0.1.0-alpha.14.2

package/dist/lib/adapter-for.d.ts

@@ -0,0 +1,17 @@
+import { JogakAdapter } from '@jogak/core';
+/** RegistryEntryMeta.framework가 받을 수 있는 모든 값 (JogakAdapter.framework와 동일). */
+export type FrameworkKey = 'react' | 'next' | 'web-components' | 'vue' | 'svelte';
+/**
+ * framework 이름으로 어댑터를 가져온다. 첫 호출은 dynamic import, 이후는 캐시 반환.
+ *
+ * 동시에 같은 framework로 호출되는 경우(예: 여러 effect가 동시에 await)에도 단 한 번만
+ * import가 일어나도록 inflight Promise를 공유한다.
+ */
+export declare function adapterFor(framework: string): Promise<JogakAdapter>;
+/**
+ * @internal test-only. 어댑터 캐시를 초기화한다.
+ *
+ * cache hit/miss 테스트, framework lookup 격리 테스트에 사용. 프로덕션 코드에서는
+ * 호출하지 말 것 — dynamic import의 비용이 발생한다.
+ */
+export declare function __resetAdapterCacheForTesting(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jogak/ui",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14.2",
   "description": "Showcase viewer UI for Jogak — Sidebar / Preview / Controls / Actions and the JogakApp shell.",
   "keywords": [
     "jogak",
@@ -46,6 +46,7 @@
     "src/app",
     "src/components",
     "src/hooks",
+    "src/lib/adapter-for.ts",
     "src/styles",
     "src/index.ts",
     "src/vite-env.d.ts",
@@ -65,7 +66,7 @@
     "prism-react-renderer": "^2.4.1",
     "tailwindcss": "^4.0.0",
     "@tailwindcss/vite": "^4.0.0",
-    "@jogak/core": "0.1.0-alpha.12"
+    "@jogak/core": "0.1.0-alpha.14.2"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",

package/src/app/preview-frame.tsx

@@ -1,5 +1,6 @@
 /**
  * 알파.9: standalone-adapter 또는 fallback 시 사용되는 same-origin iframe entry.
+ * 알파.14.1: entry.meta.framework 기반 adapter dispatch (react/vue/svelte/wc 지원).
  *
  * `IframeMount`는 알파.9에서 postMessage 프로토콜로 통일됐다 (cross-origin 어댑터와 동일).
  * preview-frame.tsx도 같은 프로토콜을 따라야 한다 — 부모는 `jogak:setProps` 메시지를,
@@ -8,8 +9,9 @@
  * jogak host vite scope에서 동작하므로 `virtual:jogak` (registry metas + entry loader)와
  * `virtual:jogak/global-css` (사용자 globalCss) 가상 모듈을 그대로 사용한다.
  */
-import { reactAdapter } from '@jogak/core/renderers/react'
+import type { JogakAdapter } from '@jogak/core'
 import { defaultRegistry } from '@jogak/core'
+import { adapterFor } from '../lib/adapter-for.js'
 import 'virtual:jogak'
 import 'virtual:jogak/global-css'
 
@@ -17,23 +19,38 @@ const rootEl = document.getElementById('jogak-preview-root')
 if (rootEl === null) throw new Error('#jogak-preview-root not found')
 
 let currentContainer: HTMLDivElement | null = null
+let currentAdapter: JogakAdapter | null = null
 
 async function renderEntry(
   entryId: string,
   args: Readonly<Record<string, unknown>>,
 ): Promise<void> {
   const entry = await defaultRegistry.requestEntry(entryId)
+  const framework = entry.meta.framework ?? 'react'
+  const nextAdapter = await adapterFor(framework)
+
   if (currentContainer === null) {
     currentContainer = document.createElement('div')
     rootEl?.replaceChildren(currentContainer)
   }
-  reactAdapter.render(entry, args, currentContainer)
+  // entry framework가 바뀐 경우 이전 어댑터로 unmount 후 새 어댑터로 mount.
+  if (currentAdapter !== null && currentAdapter !== nextAdapter) {
+    currentAdapter.unmount(currentContainer)
+    // container 자체는 재사용 가능하지만 이전 어댑터가 남긴 root/component 상태가
+    // 섞이지 않도록 새 div로 교체.
+    const fresh = document.createElement('div')
+    rootEl?.replaceChildren(fresh)
+    currentContainer = fresh
+  }
+  currentAdapter = nextAdapter
+  await nextAdapter.render(entry, args, currentContainer)
 }
 
 function unmount(): void {
-  if (currentContainer !== null) {
-    reactAdapter.unmount(currentContainer)
+  if (currentContainer !== null && currentAdapter !== null) {
+    currentAdapter.unmount(currentContainer)
     currentContainer = null
+    currentAdapter = null
   }
 }
 

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

@@ -60,10 +60,13 @@ export function formatUsageCode(
 }
 
 function resolveComponentName(entry: RegistryEntry): string {
+  // 알파.14.1: iframe isolation 모드는 chrome scope에 component를 import하지 않으므로
+  // entry.meta.component가 `null`. fallback (title 마지막 segment)으로 직행한다.
   const component = entry.meta.component as
     | { displayName?: unknown; name?: unknown }
+    | null
     | undefined
-  if (component !== undefined) {
+  if (component !== null && component !== undefined) {
     if (typeof component.displayName === 'string' && component.displayName.length > 0) {
       return component.displayName
     }

package/src/components/Preview/index.tsx

@@ -3,9 +3,10 @@ import type { ReactElement, CSSProperties } from 'react'
 import clsx from 'clsx'
 import { Highlight, themes } from 'prism-react-renderer'
 import type { PrismTheme } from 'prism-react-renderer'
-import { reactAdapter, useEntry } from '@jogak/core/renderers/react'
+import { useEntry } from '@jogak/core/renderers/react'
 import type { UseEntryState } from '@jogak/core/renderers/react'
-import type { RegistryEntry, RegistryEntryMeta, ArgType } from '@jogak/core'
+import type { JogakAdapter, RegistryEntry, RegistryEntryMeta, ArgType } from '@jogak/core'
+import { adapterFor } from '../../lib/adapter-for.js'
 import { Controls } from '../Controls/index.js'
 import { Actions } from '../Actions/index.js'
 import { ShadowMount } from './ShadowMount.js'
@@ -134,7 +135,11 @@ export function Preview({
   userPreviewUrl = '',
   previewEntryPath = '/__jogak_preview__/index.html',
 }: PreviewProps): ReactElement {
-  const state = useEntry(entryId)
+  // 알파.14.1: iframe isolation 모드에서는 chrome 측에 component 모듈을 import하지 않는다
+  // (chrome vite scope에 .vue/.svelte가 들어오면 plugin-vue/svelte 부재로 transform 실패).
+  // skipHydrate=true → useEntry가 synthetic entry(component=null)로 ready를 노출하고,
+  // 실제 마운트는 IframeMount가 사용자 vite scope의 iframe entry에 위임한다.
+  const state = useEntry(entryId, { skipHydrate: previewIsolation === 'iframe' })
   const [viewport, setViewport] = useState<ViewportKey>('desktop')
   const [bgMode, setBgMode] = useState<BgMode>('white')
   const [bottomTab, setBottomTab] = useState<'controls' | 'actions'>('controls')
@@ -636,23 +641,50 @@ function PreviewMount({ entry, args, previewIsolation, userPreviewUrl, previewEn
 
 function NoneAdapterContent({ entry, args }: { entry: RegistryEntry; args: Readonly<Record<string, unknown>> }): ReactElement {
   const containerRef = useRef<HTMLDivElement>(null)
+  const adapterRef = useRef<JogakAdapter | null>(null)
 
+  // 알파.14.1: entry.meta.framework로 dispatch. async 적응을 위해 effect 내에서
+  // await adapterFor → 캡처된 adapter로 render. unmount는 같은 adapter ref 사용.
   useEffect(() => {
     const container = containerRef.current
     if (container === null) return
-    reactAdapter.render(entry, args, container)
+    let cancelled = false
+
+    const framework = entry.meta.framework ?? 'react'
+    void adapterFor(framework).then((adapter) => {
+      if (cancelled) return
+      adapterRef.current = adapter
+      void adapter.render(entry, args, container)
+    })
+
     return () => {
+      cancelled = true
+      const adapter = adapterRef.current
+      if (adapter === null) return
       // 알파.7.1: React 18 concurrent unmount race(`Attempted to synchronously unmount...`)
       // 회피 — fiber commit 끝난 직후로 defer.
-      queueMicrotask(() => { reactAdapter.unmount(container) })
+      queueMicrotask(() => { adapter.unmount(container) })
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [entry])
 
+  // args 갱신용 effect — adapter가 이미 캐시돼 있으면 동기 분기를 탄다.
   useEffect(() => {
     const container = containerRef.current
     if (container === null) return
-    reactAdapter.render(entry, args, container)
+    let cancelled = false
+    const adapter = adapterRef.current
+    if (adapter !== null) {
+      void adapter.render(entry, args, container)
+      return
+    }
+    const framework = entry.meta.framework ?? 'react'
+    void adapterFor(framework).then((resolved) => {
+      if (cancelled) return
+      adapterRef.current = resolved
+      void resolved.render(entry, args, container)
+    })
+    return () => { cancelled = true }
   }, [entry, args])
 
   return (
@@ -665,19 +697,31 @@ function NoneAdapterContent({ entry, args }: { entry: RegistryEntry; args: Reado
 }
 
 /**
- * Shadow 모드 — ShadowMount의 ShadowRoot 안에서 react-adapter.render를 호출하는
+ * Shadow 모드 — ShadowMount의 ShadowRoot 안에서 adapter.render를 호출하는
  * 작은 wrapper. ShadowMount 안 portal 내부에 위치하므로 useRef는 ShadowRoot scope.
  */
 function ShadowAdapterContent({ entry, args }: { entry: RegistryEntry; args: Readonly<Record<string, unknown>> }): ReactElement {
   const ref = useRef<HTMLDivElement>(null)
+  const adapterRef = useRef<JogakAdapter | null>(null)
 
   useEffect(() => {
     const c = ref.current
     if (c === null) return
-    reactAdapter.render(entry, args, c)
+    let cancelled = false
+
+    const framework = entry.meta.framework ?? 'react'
+    void adapterFor(framework).then((adapter) => {
+      if (cancelled) return
+      adapterRef.current = adapter
+      void adapter.render(entry, args, c)
+    })
+
     return () => {
+      cancelled = true
+      const adapter = adapterRef.current
+      if (adapter === null) return
       // 알파.7.1: unmount race 회피
-      queueMicrotask(() => { reactAdapter.unmount(c) })
+      queueMicrotask(() => { adapter.unmount(c) })
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [entry])
@@ -685,7 +729,19 @@ function ShadowAdapterContent({ entry, args }: { entry: RegistryEntry; args: Rea
   useEffect(() => {
     const c = ref.current
     if (c === null) return
-    reactAdapter.render(entry, args, c)
+    let cancelled = false
+    const adapter = adapterRef.current
+    if (adapter !== null) {
+      void adapter.render(entry, args, c)
+      return
+    }
+    const framework = entry.meta.framework ?? 'react'
+    void adapterFor(framework).then((resolved) => {
+      if (cancelled) return
+      adapterRef.current = resolved
+      void resolved.render(entry, args, c)
+    })
+    return () => { cancelled = true }
   }, [entry, args])
 
   return <div ref={ref} data-testid="preview-content-shadow" />

package/src/lib/adapter-for.ts

@@ -0,0 +1,173 @@
+/**
+ * 알파.14.1: framework별 renderer adapter dispatch router.
+ *
+ * `RegistryEntryMeta.framework` 필드를 보고 적절한 어댑터를 dynamic import한다.
+ * React-only 사용자가 Vue/Svelte 모듈을 로딩 받지 않도록 dynamic import + 모듈 캐시.
+ *
+ * 지원 framework:
+ *   - 'react' / 'next' → `@jogak/core/renderers/react#reactAdapter`
+ *   - 'vue'            → `@jogak/core/renderers/vue#vueAdapter`
+ *   - 'svelte'         → `@jogak/core/renderers/svelte#svelteAdapter`
+ *   - 'web-components' → 내부 wrapper (defineJogakElement 기반)
+ *
+ * 알 수 없는 framework는 명시적 에러 메시지로 throw한다.
+ */
+
+import type { JogakAdapter, RegistryEntry } from '@jogak/core'
+
+/** RegistryEntryMeta.framework가 받을 수 있는 모든 값 (JogakAdapter.framework와 동일). */
+export type FrameworkKey =
+  | 'react'
+  | 'next'
+  | 'web-components'
+  | 'vue'
+  | 'svelte'
+
+const cache = new Map<FrameworkKey, JogakAdapter>()
+const inflight = new Map<FrameworkKey, Promise<JogakAdapter>>()
+
+/**
+ * framework 이름으로 어댑터를 가져온다. 첫 호출은 dynamic import, 이후는 캐시 반환.
+ *
+ * 동시에 같은 framework로 호출되는 경우(예: 여러 effect가 동시에 await)에도 단 한 번만
+ * import가 일어나도록 inflight Promise를 공유한다.
+ */
+export async function adapterFor(framework: string): Promise<JogakAdapter> {
+  const key = framework as FrameworkKey
+  const cached = cache.get(key)
+  if (cached !== undefined) return cached
+
+  const pending = inflight.get(key)
+  if (pending !== undefined) return pending
+
+  const loader = loadAdapter(key)
+  inflight.set(key, loader)
+  try {
+    const adapter = await loader
+    cache.set(key, adapter)
+    return adapter
+  } finally {
+    inflight.delete(key)
+  }
+}
+
+async function loadAdapter(framework: FrameworkKey): Promise<JogakAdapter> {
+  switch (framework) {
+    case 'react':
+    case 'next': {
+      // Next.js의 client-side 렌더링도 React 18+ root API와 동일하므로 reactAdapter 재사용.
+      const mod = await import('@jogak/core/renderers/react')
+      return mod.reactAdapter
+    }
+    case 'vue': {
+      const mod = await import('@jogak/core/renderers/vue')
+      return mod.vueAdapter
+    }
+    case 'svelte': {
+      const mod = await import('@jogak/core/renderers/svelte')
+      return mod.svelteAdapter
+    }
+    case 'web-components': {
+      const mod = await import('@jogak/core/renderers/web-components')
+      return createWebComponentsAdapter(mod.defineJogakElement)
+    }
+    default: {
+      throw new Error(
+        `[jogak/ui] Unknown framework: '${framework as string}'. ` +
+          `Expected one of: 'react' | 'next' | 'vue' | 'svelte' | 'web-components'.`,
+      )
+    }
+  }
+}
+
+// ── web-components wrapper ────────────────────────────────
+//
+// web-components renderer는 `defineJogakElement(tagName, entry)`로 custom element를
+// 등록하는 형태로, `JogakAdapter` ABI(render/unmount(container))를 직접 제공하지 않는다.
+// UI 측 dispatch 통일을 위해 thin wrapper로 감싼다.
+
+type CustomElementHost = HTMLElement & {
+  setAttribute(name: string, value: string): void
+}
+
+type WCContainer = HTMLElement & {
+  _jogakWCElement?: HTMLElement
+  _jogakWCTagName?: string
+}
+
+function entryToTagName(entryId: string): string {
+  // entryId는 `Category/Subcategory/Name` 형태일 수 있다. custom element는 dash를
+  // 포함한 lowercase여야 하므로 안전한 문자만 남기고 'jogak-' prefix를 부여한다.
+  const safe = entryId
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+  return `jogak-${safe || 'entry'}`
+}
+
+function serializeAttribute(value: unknown): string | null {
+  if (value === undefined || value === null) return null
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  // 함수/객체는 attribute로 표현 불가 — null로 skip(어댑터가 injectActions 처리).
+  if (typeof value === 'function' || typeof value === 'object') return null
+  return String(value)
+}
+
+function createWebComponentsAdapter(
+  defineJogakElement: (tagName: string, entry: RegistryEntry) => void,
+): JogakAdapter {
+  return {
+    framework: 'web-components',
+    render(
+      entry: RegistryEntry,
+      args: Readonly<Record<string, unknown>>,
+      container: HTMLElement,
+    ): void {
+      const state = container as WCContainer
+      const tagName = entryToTagName(entry.id)
+      defineJogakElement(tagName, entry)
+
+      let el = state._jogakWCElement
+      if (el === undefined || state._jogakWCTagName !== tagName) {
+        // entry가 바뀐 경우(다른 tagName) 기존 element 제거 후 재생성.
+        if (el !== undefined) el.remove()
+        el = document.createElement(tagName) as CustomElementHost
+        container.replaceChildren(el)
+        state._jogakWCElement = el
+        state._jogakWCTagName = tagName
+      }
+
+      for (const [key, value] of Object.entries(args)) {
+        const serialized = serializeAttribute(value)
+        if (serialized === null) {
+          el.removeAttribute(key)
+        } else {
+          el.setAttribute(key, serialized)
+        }
+      }
+    },
+    unmount(container: HTMLElement): void {
+      const state = container as WCContainer
+      const el = state._jogakWCElement
+      if (el !== undefined) {
+        el.remove()
+      }
+      delete state._jogakWCElement
+      delete state._jogakWCTagName
+    },
+  }
+}
+
+// ── test-only helpers ─────────────────────────────────────
+
+/**
+ * @internal test-only. 어댑터 캐시를 초기화한다.
+ *
+ * cache hit/miss 테스트, framework lookup 격리 테스트에 사용. 프로덕션 코드에서는
+ * 호출하지 말 것 — dynamic import의 비용이 발생한다.
+ */
+export function __resetAdapterCacheForTesting(): void {
+  cache.clear()
+  inflight.clear()
+}