@xfilecom/front-core 0.2.27 → 0.2.29

package/docs/COMPONENTS.md

@@ -0,0 +1,137 @@
+# Components reference
+
+소스는 모두 `packages/front-core/src/` 기준. 빌드 산출물은 `dist/`에 동일 구조로 복사된다.
+
+## 레이아웃·표면
+
+| 컴포넌트 | 소스 | 요약 |
+|----------|------|------|
+| `Paper` | [atoms/Paper.tsx](../src/components/atoms/Paper.tsx) | `elevation` 0~4, `variant` filled \| outlined |
+| `Card` | [atoms/Card.tsx](../src/components/atoms/Card.tsx) | `title`, `footer`, `interactive` |
+| `Box` | [atoms/Box.tsx](../src/components/atoms/Box.tsx) | `as`, `padding` |
+| `Stack` | [atoms/Stack.tsx](../src/components/atoms/Stack.tsx) | flex gap·align·justify |
+
+### Paper
+
+```tsx
+import { Paper, Stack, Text } from '@xfilecom/front-core';
+
+<Paper elevation={2} style={{ padding: 'var(--xfc-space-lg)' }}>
+  <Text variant="body">Elevation 2 surface</Text>
+</Paper>
+
+<Paper variant="outlined" style={{ padding: 'var(--xfc-space-md)' }}>
+  Border only
+</Paper>
+```
+
+### Card
+
+```tsx
+import { Card, Button } from '@xfilecom/front-core';
+
+<Card
+  title="제목"
+  footer={<Button variant="primary">확인</Button>}
+>
+  본문
+</Card>
+```
+
+## 타이포
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Text` | [atoms/Text.tsx](../src/components/atoms/Text.tsx) |
+
+`variant`: `title` | `appbar` | `section` | `subtitle` | `lead` | `body` | `muted` | `small` | `label` | `labelBlock` | `accent`
+
+```tsx
+<Text variant="section">섹션 제목</Text>
+<Text variant="lead">리드 문단</Text>
+```
+
+## 액션
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Button` | [atoms/Button.tsx](../src/components/atoms/Button.tsx) |
+| `Badge` | [atoms/Badge.tsx](../src/components/atoms/Badge.tsx) |
+
+`Button` variants: `primary` | `secondary` | `outline` | `muted` | `ghost`  
+`Badge` tone: `neutral` | `accent` | `success` | `warn` | `danger`
+
+## 폼
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Input` | [atoms/Input.tsx](../src/components/atoms/Input.tsx) |
+| `Textarea` | [atoms/Textarea.tsx](../src/components/atoms/Textarea.tsx) |
+| `Select` | [atoms/Select.tsx](../src/components/atoms/Select.tsx) |
+| `Checkbox` | [atoms/Checkbox.tsx](../src/components/atoms/Checkbox.tsx) |
+| `Field` | [atoms/Field.tsx](../src/components/atoms/Field.tsx) |
+
+`Field`는 **단일** 자식에 `id` / `aria-describedby` / `aria-invalid`를 병합한다. `htmlFor`와 자식 `id`를 일치시킨다.
+
+## 피드백
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Toast` / `ToastList` | [atoms/Toast.tsx](../src/components/atoms/Toast.tsx) |
+| `ToastSeverityIcon` | 동일 파일 |
+| `InlineErrorList` | [atoms/InlineErrorList.tsx](../src/components/atoms/InlineErrorList.tsx) |
+| `LoadingOverlay` | [atoms/LoadingOverlay.tsx](../src/components/atoms/LoadingOverlay.tsx) |
+
+`ToastList`의 `ToastEntry`에 `dismissible?: boolean`으로 행마다 닫기 버튼을 제어한다.
+
+## 오버레이
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Dialog` | [overlays/Dialog.tsx](../src/components/overlays/Dialog.tsx) |
+| `ConfirmDialog` | [overlays/ConfirmDialog.tsx](../src/components/overlays/ConfirmDialog.tsx) |
+| `BottomSheet` | [overlays/BottomSheet.tsx](../src/components/overlays/BottomSheet.tsx) |
+
+커스텀 모달에 동일한 스크롤 잠금·포커스 트랩을 쓰려면 [overlayHooks.ts](../src/components/overlays/overlayHooks.ts)의 `useFocusTrap`, `useBodyScrollLock`, `useEscapeKey`를 루트에서 import 한다.
+
+## shadcn/ui 스타일 원자
+
+[SHADCN.md](./SHADCN.md)에 **전체 매핑표**(캘린더·콤보박스 등 앱 의존 항목 포함)가 있다. 아래는 패키지에 포함된 대응 컴포넌트 요약.
+
+| 이름 | 소스 |
+|------|------|
+| `Separator` | [atoms/Separator.tsx](../src/components/atoms/Separator.tsx) |
+| `Skeleton` | [atoms/Skeleton.tsx](../src/components/atoms/Skeleton.tsx) |
+| `Label` | [atoms/Label.tsx](../src/components/atoms/Label.tsx) |
+| `Switch` | [atoms/Switch.tsx](../src/components/atoms/Switch.tsx) |
+| `Progress` | [atoms/Progress.tsx](../src/components/atoms/Progress.tsx) |
+| `Tabs` · `TabsList` · `TabsTrigger` · `TabsContent` | [atoms/Tabs.tsx](../src/components/atoms/Tabs.tsx) |
+| `Accordion` · … | [atoms/Accordion.tsx](../src/components/atoms/Accordion.tsx) |
+| `Alert` · `AlertTitle` · `AlertDescription` | [atoms/Alert.tsx](../src/components/atoms/Alert.tsx) |
+| `Avatar` · `AvatarImage` · `AvatarFallback` · `AvatarAuto` | [atoms/Avatar.tsx](../src/components/atoms/Avatar.tsx) |
+| `Breadcrumb` · … | [atoms/Breadcrumb.tsx](../src/components/atoms/Breadcrumb.tsx) |
+| `Table` · … | [atoms/Table.tsx](../src/components/atoms/Table.tsx) |
+| `ScrollArea` | [atoms/ScrollArea.tsx](../src/components/atoms/ScrollArea.tsx) |
+| `Toggle` | [atoms/Toggle.tsx](../src/components/atoms/Toggle.tsx) |
+| `RadioGroup` · `RadioGroupItem` | [atoms/RadioGroup.tsx](../src/components/atoms/RadioGroup.tsx) |
+| `AspectRatio` | [atoms/AspectRatio.tsx](../src/components/atoms/AspectRatio.tsx) |
+| `Tooltip` | [atoms/Tooltip.tsx](../src/components/atoms/Tooltip.tsx) |
+| `Collapsible` · … | [atoms/Collapsible.tsx](../src/components/atoms/Collapsible.tsx) |
+| `Slider` | [atoms/Slider.tsx](../src/components/atoms/Slider.tsx) |
+| `Pagination` · … | [atoms/Pagination.tsx](../src/components/atoms/Pagination.tsx) |
+
+## CSS
+
+| 파일 | 용도 |
+|------|------|
+| [tokens.css](../src/tokens.css) | `:root` 변수, 다크 프리셋 |
+| [base.css](../src/base.css) | `.xfc-*` atoms 스타일 |
+
+## TypeScript
+
+`tokenVars`로 CSS 변수 이름을 문자열 상수로 참조할 수 있다. ([index.ts](../src/index.ts))
+
+```ts
+import { tokenVars } from '@xfilecom/front-core';
+document.body.style.setProperty(tokenVars.colorAccent, '#143c38');
+```

package/docs/DESIGN_SYSTEM.md

@@ -0,0 +1,32 @@
+# xframe design system vs Paper-style UI kits
+
+`@xfilecom/front-core`는 **브라우저 전용**이며 React Native(`react-native-paper`)나 MUI(`@mui/material`)와 동일한 패키지는 아니다. 대신 **같은 UX 패턴**(표면·높이·토큰)을 웹 CSS 변수 + 얇은 React atoms로 옮긴다.
+
+## 한눈에 비교
+
+| 개념 | MUI (`Paper`) | react-native-paper (`Surface`) | front-core |
+|------|---------------|---------------------------------|------------|
+| 표면/카드 | `Paper` + `elevation` | `Surface` + `elevation` | [`Paper`](../src/components/atoms/Paper.tsx) `elevation={0…4}` |
+| 구조형 카드 | `Card` | `Card` | [`Card`](../src/components/atoms/Card.tsx) (title/footer 슬롯) |
+| 버튼 | `Button` | `Button` | [`Button`](../src/components/atoms/Button.tsx) variants |
+| 다이얼로그 | `Dialog` | `Portal`+`Dialog` | [`Dialog`](../src/components/overlays/Dialog.tsx) |
+| 스낵바/토스트 | `Snackbar` | `Snackbar` | [`Toast`](../src/components/atoms/Toast.tsx) / [`ToastList`](../src/components/atoms/Toast.tsx) |
+| 테마 | `ThemeProvider` | `PaperProvider` | `:root` / `html.dark` **CSS 변수** + 선택적 `xfc-theme.css` |
+
+## Elevation (높이)
+
+- **MUI**: 그림자 깊이가 elevation 숫자에 대응.
+- **front-core**: `Paper`의 `elevation` 0~4가 `--xfc-shadow-xs` … `--xfc-shadow-lg`에 매핑된다. `variant="outlined"`는 그림자 없이 테두리만 (`outlined` variant).
+
+## 색 (Color roles)
+
+Material 3의 *primary / on-primary / surface* 같은 **역할 이름**은 npm 타입으로 강제하지 않고, `--xfc-accent`, `--xfc-bg-elevated`, `--xfc-fg` 등 **토큰 이름**으로 맞춘다. 다크 모드는 `html.dark` 또는 `data-theme="dark"` 한 번에 같은 변수를 덮어쓴다.
+
+## 언제 MUI / RN Paper를 쓰고 언제 front-core를 쓰나
+
+- **이미 MUI 생태계**를 쓰는 앱 → MUI 유지.
+- **xframe 스캐폴드**, 번들·의존성을 가볍게, Nest와 무관한 **순수 웹 atoms** → `front-core`.
+
+## 다음 문서
+
+- [COMPONENTS.md](./COMPONENTS.md) — 컴포넌트별 props·소스 경로·예제 코드

package/docs/SHADCN.md

@@ -0,0 +1,66 @@
+# shadcn/ui 대응표
+
+[shadcn/ui](https://ui.shadcn.com/)는 **Radix UI + Tailwind** 기반의 복사-붙여넣기 컴포넌트 모음이다. `@xfilecom/front-core`는 **Radix·Tailwind 없이** 동일한 **역할·이름에 가까운** API를 토큰(`--xfc-*`) + `base.css`로 제공한다. 고급 포지셔닝(드롭다운 앵커, 날짜 그리드 등)은 앱에서 전용 라이브러리를 쓰는 것을 권장한다.
+
+## 컴포넌트 매핑
+
+| shadcn | front-core | 비고 |
+|--------|------------|------|
+| Accordion | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | single 전용; multiple는 추후 확장 가능 |
+| Alert | `Alert`, `AlertTitle`, `AlertDescription` | |
+| Alert Dialog | `ConfirmDialog` | 문구·버튼 props로 조합 |
+| Aspect Ratio | `AspectRatio` | |
+| Avatar | `Avatar`, `AvatarImage`, `AvatarFallback`, `AvatarAuto` | 이미지+대체는 `AvatarAuto` 권장 |
+| Badge | `Badge` | tone API는 shadcn과 다름 |
+| Breadcrumb | `Breadcrumb`, `BreadcrumbList`, … | |
+| Button | `Button` | variant 이름 다름 (`primary` 등) |
+| Calendar | — | 앱에서 `react-day-picker` 등 |
+| Card | `Card`, `Paper` | `Card`는 헤더/푸터 패턴 |
+| Carousel | — | 앱에서 embla 등 |
+| Chart | — | 앱에서 recharts 등 |
+| Checkbox | `Checkbox` | |
+| Collapsible | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` | |
+| Combobox | — | `Select` + 앱 로직 또는 외부 라이브러리 |
+| Command | — | 앱에서 cmdk 등 |
+| Context Menu | — | 앱에서 Radix 등 |
+| Data Table | `Table` + 앱 | 정렬·페이지네이션은 앱 상태 |
+| Date Picker | — | 앱에서 date 라이브러리 |
+| Dialog | `Dialog` | |
+| Drawer | `BottomSheet` | 모바일 퍼스트 시트 |
+| Dropdown Menu | — | 앱에서 Radix Menu 등 |
+| Form | `Field` + 앱 검증 | react-hook-form 등과 조합 |
+| Hover Card | — | `Tooltip` 단순 버전 또는 Radix |
+| Input | `Input` | |
+| Input OTP | — | 앱 전용 |
+| Label | `Label` | `Field`와 병행 가능 |
+| Menubar | — | |
+| Navigation Menu | — | |
+| Pagination | `Pagination`, `PaginationContent`, `PaginationLink`, … | |
+| Popover | — | `Dialog` 소형 또는 Radix |
+| Progress | `Progress` | |
+| Radio Group | `RadioGroup`, `RadioGroupItem` | |
+| Resizable | — | |
+| Scroll Area | `ScrollArea` | 네이티브 스크롤 |
+| Select | `Select` | 네이티브 `<select>` 스타일 |
+| Separator | `Separator` | |
+| Sheet | `BottomSheet` / `Dialog` | |
+| Skeleton | `Skeleton` | |
+| Slider | `Slider` | 네이티브 `range` |
+| Sonner / Toast | `Toast`, `ToastList` | |
+| Switch | `Switch` | |
+| Table | `Table`, `TableHeader`, `TableBody`, … | |
+| Tabs | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | |
+| Textarea | `Textarea` | |
+| Toggle | `Toggle` | |
+| Toggle Group | — | `Toggle` 여러 개 + 앱 상태 |
+| Tooltip | `Tooltip` | 인라인 단순 툴팁 |
+
+## 스타일·접근성
+
+- 포커스 링: `base.css`의 `--xfc-focus-ring` 계열.
+- 다크: `tokens.css` — `html.dark` / `data-theme="dark"`.
+- shadcn과 **클래스 이름은 다름** — 마이그레이션 시 JSX만 교체하고 앱 `app.css`에서 보정한다.
+
+## 소스 위치
+
+신규 원자는 `src/components/atoms/*.tsx` (예: `Tabs.tsx`, `Table.tsx`). 스타일은 `src/base.css`의 **shadcn/ui-style primitives** 블록.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/front-core",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "description": "Shared design tokens, base CSS, and atomic React components (browser-only; no Nest dependency)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +21,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "README.md"
   ],
   "scripts": {
     "prepublishOnly": "npm run build",