WebComponent

외부 React 컴포넌트를 Shadow DOM에 로드하여 렌더링하는 컴포넌트

개요

Cals WebComponent는 외부에서 빌드된 React 컴포넌트 번들을 Shadow DOM 내에 격리된 환경으로 로드·마운트합니다. 호스트 페이지의 CSS 스타일과 완전히 분리되며, 선언적으로 사용할 수 있습니다.

주요 특징

• ✅ Shadow DOM 격리: 외부 컴포넌트 스타일이 호스트 페이지에 영향 없음
• ✅ 동적 Props 동기화: componentProps 변경 시 재마운트 없이 re-render
• ✅ 자동 스타일 주입: 외부 번들의 config.js + assets/style.css 자동 로드
• ✅ 라이프사이클 관리: 마운트/언마운트 시 React root 자동 정리
• ✅ children 지원: Shadow DOM 컨테이너 바로 아래에 추가 UI 렌더링 가능

기본 사용

src로 외부 React 컴포넌트 번들 URL을 지정합니다.

import { WebComponent } from "@vortex/ui-cals"
 
<WebComponent
  src="https://cdn.example.com/extension/MyWidget.js"
  componentProps={{ theme: "light", lang: "ko" }}
  height={300}
/>

동적 Props 전달

componentProps가 변경되면 Vue 인스턴스를 재마운트하지 않고 내부 reactive ref만 동기화합니다.

const [theme, setTheme] = useState("light")
 
<WebComponent
  src="https://cdn.example.com/extension/Dashboard.js"
  componentProps={{ theme, screenId: "SCR-001", token: accessToken }}
  height={400}
/>

오버레이 (children)

children을 전달하면 Shadow DOM 컨테이너 바로 아래에 오버레이로 렌더링됩니다.

<WebComponent
  src="https://cdn.example.com/extension/Widget.js"
  height={250}
>
  <div className="absolute inset-0 flex items-center justify-center bg-black/20">
    <span className="text-white">로딩 중...</span>
  </div>
</WebComponent>

useWebComponent Hook

WebComponent 컴포넌트 대신 훅을 직접 사용할 수도 있습니다.

import { useWebComponent } from "@vortex/ui-cals"
import { useRef } from "react"
 
function CustomContainer() {
  const containerRef = useRef<HTMLDivElement>(null)
 
  useWebComponent(containerRef, {
    src: "/extension/MyWidget.js",
    componentProps: { theme: "dark" },
    shadowMode: "open",
  })
 
  return <div ref={containerRef} style={{ height: 400 }} />
}

API Reference

Props

useWebComponent Options

외부 번들 규약

WebComponent가 로드하는 외부 번들은 React 컴포넌트를 default export해야 합니다:

// 번들 파일 (예: MyWidget.js)
export default function MyWidget(props: Record<string, unknown>) {
  return <div>...</div>
}

선택적으로 동일 baseURL에 다음 파일을 배치할 수 있습니다:

접근성

권장 사항

• ✅ Shadow DOM 내부의 포커스 가능한 요소는 문서 순서에 자연스럽게 통합됩니다.
• ✅ 외부 컴포넌트 내에서 ARIA 속성을 적절히 사용하도록 번들 개발 시 고려합니다.
• ✅ 로딩 상태를 children 오버레이로 제공할 때 aria-live="polite"를 고려합니다.

관련 컴포넌트

• IFrame: 외부 웹 페이지를 iframe으로 임베드
• Dynamic: 동적 레이아웃 컨테이너