@xfilecom/front-core 0.2.27 → 0.2.28

package/README.md

@@ -1,33 +1,62 @@
 # @xfilecom/front-core
 
-Design tokens (`tokens.css`), atomic layout/CSS (`base.css`), and browser-only React atoms + overlays. **Nest / 서버 의존 없음.**
+Design tokens (`tokens.css`), atomic layout (`base.css`), browser-only React components. **Nest / 서버 의존 없음.**
 
-## CSS import order
+## 문서 (상세)
+
+| 문서 | 내용 |
+|------|------|
+| [docs/DESIGN_SYSTEM.md](./docs/DESIGN_SYSTEM.md) | MUI Paper / react-native-paper 등과 **개념 매핑**, elevation·역할 색 |
+| [docs/COMPONENTS.md](./docs/COMPONENTS.md) | 컴포넌트별 **소스 경로**, props 요약, **복붙 예제 코드** |
+
+npm 패키지에 `docs/`가 포함되므로, 설치 후 `node_modules/@xfilecom/front-core/docs/`에서도 동일 파일을 볼 수 있다.
+
+## CSS 로드 순서
 
 1. `@xfilecom/front-core/tokens.css`
 2. `@xfilecom/front-core/base.css`
-3. (optional) 앱/공유 테마 — 예: `xfc-theme.css`에서 `--xfc-*` 덮어쓰기
+3. (선택) 앱 `xfc-theme.css`에서 `--xfc-*` 덮어쓰기
+4. (선택) 레이아웃 `app.css`
+
+**다크:** `tokens.css` — `html.dark` / `data-theme="dark"`.
+
+**배경:** `body` 기본은 옅은 액센트 그라데이션. 단색만 쓰려면 `body { background-image: none; }`.
+
+## React import
 
-**Dark mode:** `tokens.css` 끝에 `html.dark` / `data-theme="dark"` 프리셋이 있다. 루트에 클래스 또는 속성만 켜면 동일 변수명으로 전환된다.
+```tsx
+import {
+  Paper,
+  Card,
+  Button,
+  Text,
+  Dialog,
+} from '@xfilecom/front-core';
+```
 
-**토큰:** `--xfc-shadow-xs|sm|md|lg`, `--xfc-accent-soft` 등 계층·글로우용 변수가 있다. `tokenVars`에서 TS로 참조 가능.
+서브패스: `@xfilecom/front-core/atoms`, `@xfilecom/front-core/overlays`.
 
-**배경:** `base.css`의 `body`는 아주 옅은 액센트 그라데이션을 쓴다. 단색만 원하면 앱 CSS에서 `body { background-image: none; }` 로 끈다.
+## Paper (표면)
 
-## React
+MUI `Paper` / RN `Surface`에 대응하는 얇은 래퍼:
 
-- 루트 export 또는 `@xfilecom/front-core/atoms`, `@xfilecom/front-core/overlays`.
-- **기본 UI 문자열은 영어** (토스트 닫기 `Dismiss`, ConfirmDialog `OK` / `Cancel`). 한국어 등은 props로 넘긴다.
+```tsx
+<Paper elevation={2} style={{ padding: 'var(--xfc-space-lg)' }}>
+  …
+</Paper>
+<Paper variant="outlined" style={{ padding: 16 }}>…</Paper>
+```
 
-## Accessibility
+## 기본 문자열·a11y
 
-- **Dialog / BottomSheet / ConfirmDialog:** body 스크롤 잠금, Escape, 초기 포커스·복귀, **Tab 포커스 트랩** (`useFocusTrap`).
-- **Toast:** `error`는 `role="alert"`, 그 외 `role="status"`. `ToastList`는 `ToastEntry.dismissible`로 행마다 닫기 버튼 on/off.
+- 기본 UI 문구는 **영어** (토스트 Dismiss, Confirm OK/Cancel). 한국어는 props로 덮어쓴다.
+- Dialog / BottomSheet: 스크롤 잠금, Escape, 포커스 트랩 (`useFocusTrap`).
+- Toast: `error` → `role="alert"`, 그 외 `role="status"`.
 
 ## Version
 
-`XFRAME_FRONT_CORE_VERSION`은 `npm run build` 시 `package.json`의 `version`으로 `src/generatedVersion.ts`가 갱신된다.
+`npm run build` 시 `package.json`의 `version`이 `src/generatedVersion.ts`에 반영된다.
 
-## Form atoms
+## 폼
 
-`Input`, `Textarea`, `Select`, `Checkbox`, `Field` — `Field`는 단일 자식 컨트롤에 `aria-describedby` / `aria-invalid` / `id`를 병합한다. 라벨 `htmlFor`와 컨트롤 `id`를 맞출 것.
+`Input`, `Textarea`, `Select`, `Checkbox`, `Field` — 자세한 예는 [COMPONENTS.md](./docs/COMPONENTS.md).

package/dist/base.css

@@ -234,6 +234,45 @@ a:hover {
   padding-top: var(--xfc-space-md);
 }
 
+/* —— Paper / Surface (MUI Paper · RN Paper Surface 스타일 elevation) —— */
+
+.xfc-paper {
+  box-sizing: border-box;
+  background: var(--xfc-bg-elevated);
+  color: var(--xfc-fg);
+  border-radius: var(--xfc-radius-md);
+  border: 1px solid transparent;
+  transition:
+    box-shadow 0.2s ease,
+    border-color 0.2s ease;
+}
+
+.xfc-paper--elevation-0 {
+  box-shadow: none;
+  border-color: var(--xfc-border);
+}
+
+.xfc-paper--elevation-1 {
+  box-shadow: var(--xfc-shadow-xs);
+}
+
+.xfc-paper--elevation-2 {
+  box-shadow: var(--xfc-shadow-sm);
+}
+
+.xfc-paper--elevation-3 {
+  box-shadow: var(--xfc-shadow-md);
+}
+
+.xfc-paper--elevation-4 {
+  box-shadow: var(--xfc-shadow-lg);
+}
+
+.xfc-paper--outlined {
+  box-shadow: none;
+  border-color: var(--xfc-border-strong);
+}
+
 /* —— Buttons —— */
 
 .xfc-btn {

package/dist/components/atoms/Paper.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export type PaperProps = HTMLAttributes<HTMLDivElement> & {
+    children?: ReactNode;
+    /**
+     * Material-style elevation: 0은 평면+보더, 1…4는 섀도 강도 증가.
+     * `variant="outlined"`일 때는 무시되고 보더만 씀.
+     */
+    elevation?: 0 | 1 | 2 | 3 | 4;
+    /** filled = elevation 섀도, outlined = 보더만 */
+    variant?: 'filled' | 'outlined';
+};
+/**
+ * 콘텐츠를 올려놓는 표면 컴포넌트 (MUI `Paper` / RN Paper `Surface`에 가깝게).
+ * 스타일은 `base.css`의 `.xfc-paper*` — 토큰 `--xfc-shadow-*`와 연동.
+ */
+export declare function Paper({ elevation, variant, className, children, ...rest }: PaperProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/atoms/Paper.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Paper = Paper;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * 콘텐츠를 올려놓는 표면 컴포넌트 (MUI `Paper` / RN Paper `Surface`에 가깝게).
+ * 스타일은 `base.css`의 `.xfc-paper*` — 토큰 `--xfc-shadow-*`와 연동.
+ */
+function Paper({ elevation = 1, variant = 'filled', className = '', children, ...rest }) {
+    const elevClass = variant === 'outlined' ? 'xfc-paper--outlined' : `xfc-paper--elevation-${elevation}`;
+    const cls = ['xfc-paper', elevClass, className].filter(Boolean).join(' ');
+    return ((0, jsx_runtime_1.jsx)("div", { className: cls, ...rest, children: children }));
+}

package/dist/components/atoms/index.d.ts

@@ -13,6 +13,7 @@ export { Select, type SelectProps } from './Select';
 export { Textarea, type TextareaProps } from './Textarea';
 export { InlineErrorList, type InlineErrorEntry, type InlineErrorListProps, } from './InlineErrorList';
 export { LoadingOverlay, type LoadingOverlayProps } from './LoadingOverlay';
+export { Paper, type PaperProps } from './Paper';
 export { Stack, type StackProps } from './Stack';
 export { Toast, ToastList, ToastSeverityIcon, type ToastEntry, type ToastListProps, type ToastProps, type ToastSeverity, type ToastSeverityIconProps, } from './Toast';
 export { Text, type TextProps, type TextVariant } from './Text';

package/dist/components/atoms/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Text = exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Stack = exports.LoadingOverlay = exports.InlineErrorList = exports.Textarea = exports.Select = exports.Input = exports.Field = exports.Checkbox = exports.Card = exports.Button = exports.Box = exports.Badge = void 0;
+exports.Text = exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Stack = exports.Paper = exports.LoadingOverlay = exports.InlineErrorList = exports.Textarea = exports.Select = exports.Input = exports.Field = exports.Checkbox = exports.Card = exports.Button = exports.Box = exports.Badge = void 0;
 /**
  * Atomic UI — design tokens + base.css 의 `.xfc-*` 와 1:1.
  * 패키지 루트는 `components/index.ts` → 여기서 동일 심볼을 재export.
@@ -27,6 +27,8 @@ var InlineErrorList_1 = require("./InlineErrorList");
 Object.defineProperty(exports, "InlineErrorList", { enumerable: true, get: function () { return InlineErrorList_1.InlineErrorList; } });
 var LoadingOverlay_1 = require("./LoadingOverlay");
 Object.defineProperty(exports, "LoadingOverlay", { enumerable: true, get: function () { return LoadingOverlay_1.LoadingOverlay; } });
+var Paper_1 = require("./Paper");
+Object.defineProperty(exports, "Paper", { enumerable: true, get: function () { return Paper_1.Paper; } });
 var Stack_1 = require("./Stack");
 Object.defineProperty(exports, "Stack", { enumerable: true, get: function () { return Stack_1.Stack; } });
 var Toast_1 = require("./Toast");

package/dist/generatedVersion.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated by scripts/write-version.js — do not edit by hand */
-export declare const XFRAME_FRONT_CORE_VERSION: "0.2.27";
+export declare const XFRAME_FRONT_CORE_VERSION: "0.2.28";

package/dist/generatedVersion.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.XFRAME_FRONT_CORE_VERSION = void 0;
 /** Auto-generated by scripts/write-version.js — do not edit by hand */
-exports.XFRAME_FRONT_CORE_VERSION = "0.2.27";
+exports.XFRAME_FRONT_CORE_VERSION = "0.2.28";

package/dist/index.d.ts

@@ -51,6 +51,6 @@ export declare const tokenVars: {
     readonly toastWarnBg: "--xfc-toast-warn-bg";
     readonly toastErrorBg: "--xfc-toast-error-bg";
 };
-export { Badge, BottomSheet, Box, Button, Card, Checkbox, ConfirmDialog, Dialog, Field, InlineErrorList, Input, LoadingOverlay, Select, Stack, Text, Textarea, Toast, ToastList, ToastSeverityIcon, type BadgeProps, type BottomSheetProps, type BoxProps, type ButtonProps, type CardProps, type CheckboxProps, type ConfirmDialogProps, type DialogProps, type FieldProps, type InlineErrorEntry, type InlineErrorListProps, type InputProps, type LoadingOverlayProps, type SelectProps, type StackProps, type TextProps, type TextVariant, type TextareaProps, type ToastEntry, type ToastListProps, type ToastProps, type ToastSeverity, type ToastSeverityIconProps, } from './components';
+export { Badge, BottomSheet, Box, Button, Card, Checkbox, ConfirmDialog, Dialog, Field, InlineErrorList, Input, LoadingOverlay, Paper, Select, Stack, Text, Textarea, Toast, ToastList, ToastSeverityIcon, type BadgeProps, type BottomSheetProps, type BoxProps, type ButtonProps, type CardProps, type CheckboxProps, type ConfirmDialogProps, type DialogProps, type FieldProps, type InlineErrorEntry, type InlineErrorListProps, type InputProps, type LoadingOverlayProps, type PaperProps, type SelectProps, type StackProps, type TextProps, type TextVariant, type TextareaProps, type ToastEntry, type ToastListProps, type ToastProps, type ToastSeverity, type ToastSeverityIconProps, } from './components';
 /** 커스텀 오버레이용 — `Dialog`/`BottomSheet`와 동일한 훅 */
 export { useBodyScrollLock, useEscapeKey, useFocusTrap } from './components';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useFocusTrap = exports.useEscapeKey = exports.useBodyScrollLock = exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Textarea = exports.Text = exports.Stack = exports.Select = exports.LoadingOverlay = exports.Input = exports.InlineErrorList = exports.Field = exports.Dialog = exports.ConfirmDialog = exports.Checkbox = exports.Card = exports.Button = exports.Box = exports.BottomSheet = exports.Badge = exports.tokenVars = exports.XFRAME_FRONT_CORE_VERSION = void 0;
+exports.useFocusTrap = exports.useEscapeKey = exports.useBodyScrollLock = exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Textarea = exports.Text = exports.Stack = exports.Select = exports.Paper = exports.LoadingOverlay = exports.Input = exports.InlineErrorList = exports.Field = exports.Dialog = exports.ConfirmDialog = exports.Checkbox = exports.Card = exports.Button = exports.Box = exports.BottomSheet = exports.Badge = exports.tokenVars = exports.XFRAME_FRONT_CORE_VERSION = void 0;
 /**
  * @xfilecom/front-core — design tokens + atomic React components (browser-only).
  *
@@ -68,6 +68,7 @@ Object.defineProperty(exports, "Field", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "InlineErrorList", { enumerable: true, get: function () { return components_1.InlineErrorList; } });
 Object.defineProperty(exports, "Input", { enumerable: true, get: function () { return components_1.Input; } });
 Object.defineProperty(exports, "LoadingOverlay", { enumerable: true, get: function () { return components_1.LoadingOverlay; } });
+Object.defineProperty(exports, "Paper", { enumerable: true, get: function () { return components_1.Paper; } });
 Object.defineProperty(exports, "Select", { enumerable: true, get: function () { return components_1.Select; } });
 Object.defineProperty(exports, "Stack", { enumerable: true, get: function () { return components_1.Stack; } });
 Object.defineProperty(exports, "Text", { enumerable: true, get: function () { return components_1.Text; } });

package/dist/tokens.css

@@ -1,6 +1,12 @@
 /**
  * Design tokens — 기본 테마 (라이트).
  * 슬레이트 뉴트럴 + 인디고 액센트, 계층형 섀도·라디우스.
+ *
+ * Material 3 / MUI Paper / react-native-paper 와의 대응(개념):
+ * - 페이지 바탕: `--xfc-bg` ≈ surface / screen background
+ * - 카드·시트: `--xfc-bg-elevated` + `--xfc-shadow-*` ≈ elevated surface
+ * - `<Paper elevation={n}>` → `.xfc-paper--elevation-n` → `--xfc-shadow-xs|sm|md|lg`
+ * 자세한 비교: 패키지 `docs/DESIGN_SYSTEM.md`
  */
 :root {
   /* Surfaces */

package/docs/COMPONENTS.md

@@ -0,0 +1,111 @@
+# 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 한다.
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/front-core",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "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",