@solapi/ui-kit 1.0.0

package/README.md

@@ -0,0 +1,153 @@
+# @solapi/ui-kit
+
+Solapi 공용 UI 컴포넌트 라이브러리.
+**Module Federation**(CDN) 우선 로드, CDN 장애 시 **npm 패키지**로 자동 fallback하는 구조입니다.
+
+## 설치
+
+```bash
+npm install @solapi/ui-kit
+```
+
+## Quick Start (Federation + npm Fallback)
+
+### 1. Remote 등록
+
+```js
+// vite.remotes.config.js
+const remoteApps = {
+  '@solapi-frontend/ui-kit': '/ui-kit/stable/assets/remote.entry.js'
+}
+```
+
+### 2. GlobalUIProvider 감싸기
+
+```tsx
+// src/RemoteEntry.tsx
+import { createSafeProviderLoader } from '@solapi/ui-kit/federation'
+
+const UI_KIT_PROVIDER = async () => {
+  try {
+    return await import('@solapi-frontend/ui-kit/provider')
+  } catch {
+    return await import('@solapi/ui-kit')
+  }
+}
+
+const GlobalUIProvider = createSafeProviderLoader<{
+  children?: React.ReactNode
+  portalContainer?: () => HTMLElement | null
+}>(
+  UI_KIT_PROVIDER,
+  'GlobalUIProvider',
+  { warningMessage: 'UI Kit CDN을 로드할 수 없습니다. npm 패키지로 대체되었습니다.' }
+)
+
+export default function RemoteEntry() {
+  return (
+    <GlobalUIProvider portalContainer={() => document.getElementById('root')}>
+      {/* 앱 컨텐츠 */}
+    </GlobalUIProvider>
+  )
+}
+```
+
+### 3. 컴포넌트 로더 정의
+
+```tsx
+// src/uiKit/safeCompLoader.tsx
+import { createSafeComponentLoader } from '@solapi/ui-kit/federation'
+
+const UI_KIT_COMP = async () => {
+  try {
+    return await import('@solapi-frontend/ui-kit/components')
+  } catch {
+    return await import('@solapi/ui-kit')
+  }
+}
+
+export const Tabs = createSafeComponentLoader(UI_KIT_COMP, 'Tabs')
+export const TextInput = createSafeComponentLoader(UI_KIT_COMP, 'TextInput')
+export const Button = createSafeComponentLoader(UI_KIT_COMP, 'Button')
+export const Box = createSafeComponentLoader(UI_KIT_COMP, 'Box')
+// ... 필요한 컴포넌트 추가
+```
+
+### 4. Hook 로더 정의
+
+```ts
+// src/uiKit/safeHookLoader.ts
+import { createSafeHookLoader } from '@solapi/ui-kit/federation'
+
+const UI_KIT_HOOKS = async () => {
+  try {
+    return await import('@solapi-frontend/ui-kit/hooks')
+  } catch {
+    return await import('@solapi/ui-kit')
+  }
+}
+
+export const useSnackbar = createSafeHookLoader(UI_KIT_HOOKS, 'useSnackbar', {
+  success: msg => console.log(`[snackbar] ${msg}`),
+  error: msg => console.error(`[snackbar] ${msg}`),
+  warning: msg => console.warn(`[snackbar] ${msg}`),
+  info: msg => console.info(`[snackbar] ${msg}`)
+})
+
+export const useModal = createSafeHookLoader(UI_KIT_HOOKS, 'useModal', {
+  modals: [],
+  openModal: async () => false,
+  closeModal: () => {},
+  closeAllModals: () => {}
+})
+
+export const useConfirm = createSafeHookLoader(UI_KIT_HOOKS, 'useConfirm', {
+  confirms: [],
+  confirm: ({ message }) => Promise.resolve(window.confirm(message)),
+  alert: ({ message }) => { window.alert(message); return Promise.resolve(true) },
+  close: () => {}
+})
+```
+
+### 5. 사용
+
+```tsx
+import { Tabs, TextInput, Button, Box } from 'uiKit/safeCompLoader'
+import { useSnackbar, useConfirm } from 'uiKit/safeHookLoader'
+
+function MyPage() {
+  const snackbar = useSnackbar()
+  const { confirm } = useConfirm()
+
+  const handleSave = async () => {
+    const ok = await confirm({ title: '저장', message: '저장하시겠습니까?' })
+    if (ok) snackbar.success('저장되었습니다!')
+  }
+
+  return (
+    <Box padding={16}>
+      <Tabs
+        items={[{ label: 'Tab 1', value: '1' }, { label: 'Tab 2', value: '2' }]}
+        value={tabValue}
+        onChange={setTabValue}
+      />
+      <TextInput label="이름" placeholder="이름을 입력하세요" />
+      <Button onClick={handleSave}>저장</Button>
+    </Box>
+  )
+}
+```
+
+> Federation이 정상이면 CDN에서 로드 (번들 크기 0), 장애 시 npm 패키지에서 자동 로드됩니다.
+
+## 문서
+
+| 문서 | 설명 |
+|------|------|
+| [시작하기](docs/getting-started.md) | 설치, 개발, 빌드 |
+| [아키텍처](docs/architecture.md) | 패키지/모듈/프로젝트 구조, Provider 계층 |
+| [사용 가이드](docs/usage-guide.md) | Federation + npm Fallback 상세 가이드, 마이그레이션 |
+| [Federation API](docs/federation-api.md) | createSafeProviderLoader, createSafeComponentLoader, createSafeHookLoader |
+| [GlobalUIProvider](docs/global-ui-provider.md) | Props, Portal, MFA, 로컬 개발 설정 |
+| [컴포넌트 추가](docs/contributing.md) | 새 UI 컴포넌트/Hook 추가 가이드 |
+| [안티패턴](docs/anti-patterns.md) | 흔한 실수와 올바른 대안 |