@xfilecom/front-core 0.2.24 → 0.2.25

package/README.md

@@ -0,0 +1,29 @@
+# @xfilecom/front-core
+
+Design tokens (`tokens.css`), atomic layout/CSS (`base.css`), and browser-only React atoms + overlays. **Nest / 서버 의존 없음.**
+
+## CSS import order
+
+1. `@xfilecom/front-core/tokens.css`
+2. `@xfilecom/front-core/base.css`
+3. (optional) 앱/공유 테마 — 예: `xfc-theme.css`에서 `--xfc-*` 덮어쓰기
+
+**Dark mode:** `tokens.css` 끝에 `html.dark` / `data-theme="dark"` 프리셋이 있다. 루트에 클래스 또는 속성만 켜면 동일 변수명으로 전환된다.
+
+## React
+
+- 루트 export 또는 `@xfilecom/front-core/atoms`, `@xfilecom/front-core/overlays`.
+- **기본 UI 문자열은 영어** (토스트 닫기 `Dismiss`, ConfirmDialog `OK` / `Cancel`). 한국어 등은 props로 넘긴다.
+
+## Accessibility
+
+- **Dialog / BottomSheet / ConfirmDialog:** body 스크롤 잠금, Escape, 초기 포커스·복귀, **Tab 포커스 트랩** (`useFocusTrap`).
+- **Toast:** `error`는 `role="alert"`, 그 외 `role="status"`. `ToastList`는 `ToastEntry.dismissible`로 행마다 닫기 버튼 on/off.
+
+## Version
+
+`XFRAME_FRONT_CORE_VERSION`은 `npm run build` 시 `package.json`의 `version`으로 `src/generatedVersion.ts`가 갱신된다.
+
+## Form atoms
+
+`Input`, `Textarea`, `Select`, `Checkbox`, `Field` — `Field`는 단일 자식 컨트롤에 `aria-describedby` / `aria-invalid` / `id`를 병합한다. 라벨 `htmlFor`와 컨트롤 `id`를 맞출 것.

package/dist/base.css

@@ -345,6 +345,66 @@ a:hover {
   color: var(--xfc-fg-muted);
 }
 
+.xfc-textarea {
+  min-height: 96px;
+  padding-top: var(--xfc-space-md);
+  padding-bottom: var(--xfc-space-md);
+  resize: vertical;
+}
+
+.xfc-select {
+  appearance: auto;
+  cursor: pointer;
+}
+
+.xfc-checkbox-row {
+  display: inline-flex;
+  align-items: flex-start;
+  gap: var(--xfc-space-sm);
+}
+
+.xfc-checkbox {
+  width: 1.125rem;
+  height: 1.125rem;
+  margin-top: 2px;
+  flex-shrink: 0;
+  accent-color: var(--xfc-accent);
+  cursor: pointer;
+}
+
+.xfc-checkbox:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.xfc-checkbox-label {
+  font-size: var(--xfc-text-body);
+  line-height: var(--xfc-leading-normal);
+  color: var(--xfc-fg-label);
+  cursor: pointer;
+}
+
+.xfc-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--xfc-space-xs);
+  align-items: stretch;
+}
+
+.xfc-field__label {
+  font-size: var(--xfc-text-small);
+  font-weight: 600;
+  color: var(--xfc-fg-label);
+  line-height: var(--xfc-leading-normal);
+}
+
+.xfc-field__error {
+  margin: 0;
+  font-size: var(--xfc-text-small);
+  line-height: var(--xfc-leading-normal);
+  color: var(--xfc-danger);
+}
+
 /* —— Badges —— */
 
 .xfc-badge {

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

@@ -0,0 +1,17 @@
+import { type InputHTMLAttributes, type ReactNode } from 'react';
+export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> & {
+    /** false 이면 disabled */
+    enabled?: boolean;
+    /** 라벨 텍스트(오른쪽). 있으면 `htmlFor` 연결 */
+    label?: ReactNode;
+    /** 행 래퍼 class */
+    rowClassName?: string;
+};
+export declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "type"> & {
+    /** false 이면 disabled */
+    enabled?: boolean;
+    /** 라벨 텍스트(오른쪽). 있으면 `htmlFor` 연결 */
+    label?: ReactNode;
+    /** 행 래퍼 class */
+    rowClassName?: string;
+} & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/atoms/Checkbox.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Checkbox = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+exports.Checkbox = (0, react_1.forwardRef)(function Checkbox({ className = '', enabled = true, label, rowClassName = '', disabled, id: idProp, ...rest }, ref) {
+    const genId = (0, react_1.useId)();
+    const inputId = idProp ?? genId;
+    const isDisabled = disabled === true || !enabled;
+    const rowCls = ['xfc-checkbox-row', rowClassName].filter(Boolean).join(' ');
+    const inputCls = ['xfc-checkbox', className].filter(Boolean).join(' ');
+    const input = ((0, jsx_runtime_1.jsx)("input", { ref: ref, type: "checkbox", id: inputId, className: inputCls, disabled: isDisabled, ...rest }));
+    if (label == null) {
+        return input;
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { className: rowCls, children: [input, (0, jsx_runtime_1.jsx)("label", { htmlFor: inputId, className: "xfc-checkbox-label", children: label })] }));
+});

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

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+export type FieldProps = {
+    /** `<label htmlFor>` — 자식 컨트롤의 `id`와 같아야 한다 */
+    htmlFor: string;
+    label: ReactNode;
+    /** 컨트롤과 라벨 사이에 삽입되는 단일 폼 컨트롤 (`Input`, `Select`, …) */
+    children: ReactNode;
+    hint?: ReactNode;
+    error?: ReactNode;
+    /** true면 자식에 `aria-invalid` 전달 */
+    invalid?: boolean;
+    className?: string;
+    labelClassName?: string;
+};
+/**
+ * 라벨 + 힌트 + 에러 문구 + 단일 컨트롤.
+ * 자식 하나에 `aria-describedby`·`aria-invalid`·`id`를 병합한다(단일 ReactElement일 때만).
+ */
+export declare function Field({ htmlFor, label, children, hint, error, invalid, className, labelClassName, }: FieldProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/atoms/Field.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Field = Field;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+/**
+ * 라벨 + 힌트 + 에러 문구 + 단일 컨트롤.
+ * 자식 하나에 `aria-describedby`·`aria-invalid`·`id`를 병합한다(단일 ReactElement일 때만).
+ */
+function Field({ htmlFor, label, children, hint, error, invalid = false, className = '', labelClassName = '', }) {
+    const hintId = `${htmlFor}-field-hint`;
+    const errId = `${htmlFor}-field-error`;
+    const hasHint = Boolean(hint);
+    const hasErr = Boolean(error);
+    const descIds = [hasHint ? hintId : null, hasErr ? errId : null].filter(Boolean);
+    let control = children;
+    if ((0, react_1.isValidElement)(children)) {
+        const child = react_1.Children.only(children);
+        const prevDesc = child.props['aria-describedby'] ?? '';
+        const mergedDesc = [...(prevDesc ? [prevDesc] : []), ...descIds].join(' ').trim() || undefined;
+        const childInvalid = child.props['aria-invalid'];
+        control = (0, react_1.cloneElement)(child, {
+            id: child.props.id ?? htmlFor,
+            'aria-describedby': mergedDesc,
+            'aria-invalid': invalid || hasErr || childInvalid || undefined,
+        });
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { className: ['xfc-field', className].filter(Boolean).join(' '), children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: htmlFor, className: ['xfc-field__label', labelClassName].filter(Boolean).join(' '), children: label }), control, hasHint ? ((0, jsx_runtime_1.jsx)("p", { id: hintId, className: "xfc-input-description", children: hint })) : null, hasErr ? ((0, jsx_runtime_1.jsx)("p", { id: errId, className: "xfc-field__error", role: "alert", children: error })) : null] }));
+}

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

@@ -0,0 +1,13 @@
+import { type ReactNode, type SelectHTMLAttributes } from 'react';
+export type SelectProps = SelectHTMLAttributes<HTMLSelectElement> & {
+    enabled?: boolean;
+    invalid?: boolean;
+    description?: ReactNode;
+    wrapperClassName?: string;
+};
+export declare const Select: import("react").ForwardRefExoticComponent<SelectHTMLAttributes<HTMLSelectElement> & {
+    enabled?: boolean;
+    invalid?: boolean;
+    description?: ReactNode;
+    wrapperClassName?: string;
+} & import("react").RefAttributes<HTMLSelectElement>>;

package/dist/components/atoms/Select.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Select = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+exports.Select = (0, react_1.forwardRef)(function Select({ className = '', enabled = true, invalid = false, description, wrapperClassName = '', disabled, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-invalid': ariaInvalidProp, children, ...rest }, ref) {
+    const genId = (0, react_1.useId)();
+    const selectId = idProp ?? genId;
+    const descId = `${selectId}-desc`;
+    const hasDesc = Boolean(description);
+    const cls = [
+        'xfc-input',
+        'xfc-select',
+        invalid ? 'xfc-input--invalid' : '',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const isDisabled = disabled === true || !enabled;
+    const ariaInvalid = ariaInvalidProp ?? invalid;
+    const ariaDescribedBy = [ariaDescribedByProp, hasDesc ? descId : null].filter(Boolean).join(' ') || undefined;
+    const el = ((0, jsx_runtime_1.jsx)("select", { ref: ref, id: selectId, className: cls, disabled: isDisabled, "aria-invalid": ariaInvalid || undefined, "aria-describedby": ariaDescribedBy, ...rest, children: children }));
+    if (!hasDesc) {
+        return el;
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { className: wrapperClassName || undefined, children: [el, (0, jsx_runtime_1.jsx)("p", { id: descId, className: "xfc-input-description", children: description })] }));
+});

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

@@ -0,0 +1,13 @@
+import { type ReactNode, type TextareaHTMLAttributes } from 'react';
+export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement> & {
+    enabled?: boolean;
+    invalid?: boolean;
+    description?: ReactNode;
+    wrapperClassName?: string;
+};
+export declare const Textarea: import("react").ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & {
+    enabled?: boolean;
+    invalid?: boolean;
+    description?: ReactNode;
+    wrapperClassName?: string;
+} & import("react").RefAttributes<HTMLTextAreaElement>>;

package/dist/components/atoms/Textarea.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Textarea = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+exports.Textarea = (0, react_1.forwardRef)(function Textarea({ className = '', enabled = true, invalid = false, description, wrapperClassName = '', disabled, id: idProp, 'aria-describedby': ariaDescribedByProp, 'aria-invalid': ariaInvalidProp, rows = 4, ...rest }, ref) {
+    const genId = (0, react_1.useId)();
+    const inputId = idProp ?? genId;
+    const descId = `${inputId}-desc`;
+    const hasDesc = Boolean(description);
+    const cls = [
+        'xfc-input',
+        'xfc-textarea',
+        invalid ? 'xfc-input--invalid' : '',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const isDisabled = disabled === true || !enabled;
+    const ariaInvalid = ariaInvalidProp ?? invalid;
+    const ariaDescribedBy = [ariaDescribedByProp, hasDesc ? descId : null].filter(Boolean).join(' ') || undefined;
+    const el = ((0, jsx_runtime_1.jsx)("textarea", { ref: ref, id: inputId, className: cls, disabled: isDisabled, rows: rows, "aria-invalid": ariaInvalid || undefined, "aria-describedby": ariaDescribedBy, ...rest }));
+    if (!hasDesc) {
+        return el;
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { className: wrapperClassName || undefined, children: [el, (0, jsx_runtime_1.jsx)("p", { id: descId, className: "xfc-input-description", children: description })] }));
+});

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

@@ -22,13 +22,16 @@ export type ToastEntry = {
     severity: ToastSeverity;
     message: ReactNode;
     icon?: ReactNode | null;
+    /** 행별 닫기 버튼. 생략 시 `ToastList`의 `dismissible`(기본 true)을 따름. */
+    dismissible?: boolean;
 };
 export type ToastListProps = {
     toasts: ToastEntry[];
     onDismiss: (id: string) => void;
     className?: string;
     dismissAriaLabel?: string;
+    /** 행에 `dismissible`이 없을 때 쓰는 기본값. 생략 시 각 토스트는 `dismissible` 기본 true. */
     dismissible?: boolean;
 };
 /** 하단 고정 토스트 스택 (business-promotion `ToastList` UI, 상태는 부모에서 주입). */
-export declare function ToastList({ toasts, onDismiss, className, dismissAriaLabel, dismissible, }: ToastListProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ToastList({ toasts, onDismiss, className, dismissAriaLabel, dismissible: listDismissible, }: ToastListProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/atoms/Toast.js

@@ -31,16 +31,21 @@ function ToastCloseIcon() {
     return ((0, jsx_runtime_1.jsx)("svg", { width: 20, height: 20, viewBox: "0 0 20 20", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": true, children: (0, jsx_runtime_1.jsx)("path", { d: "M5 5l10 10M15 5L5 15", stroke: "currentColor", strokeWidth: "1.33", strokeLinecap: "round" }) }));
 }
 /** 단일 토스트 행 (목록·커스텀 레이아웃용). */
-function Toast({ severity, message, onDismiss, className = '', icon, dismissAriaLabel = '닫기', dismissible = true, }) {
+function Toast({ severity, message, onDismiss, className = '', icon, dismissAriaLabel = 'Dismiss', dismissible = true, }) {
     const root = ['xfc-toast', `xfc-toast--${severity}`, className].filter(Boolean).join(' ');
     const showDismiss = dismissible && onDismiss;
     const iconContent = icon === null ? null : icon !== undefined ? (icon) : ((0, jsx_runtime_1.jsx)(ToastSeverityIcon, { severity: severity }));
-    return ((0, jsx_runtime_1.jsxs)("div", { className: root, role: "alert", children: [iconContent != null ? (0, jsx_runtime_1.jsx)("span", { className: "xfc-toast__icon", children: iconContent }) : null, (0, jsx_runtime_1.jsx)("div", { className: "xfc-toast__message", children: message }), showDismiss ? ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "xfc-toast-dismiss", onClick: onDismiss, "aria-label": dismissAriaLabel, children: (0, jsx_runtime_1.jsx)(ToastCloseIcon, {}) })) : null] }));
+    /** Errors use assertive alert; other severities use status (less disruptive for SR). */
+    const liveRole = severity === 'error' ? 'alert' : 'status';
+    return ((0, jsx_runtime_1.jsxs)("div", { className: root, role: liveRole, children: [iconContent != null ? (0, jsx_runtime_1.jsx)("span", { className: "xfc-toast__icon", children: iconContent }) : null, (0, jsx_runtime_1.jsx)("div", { className: "xfc-toast__message", children: message }), showDismiss ? ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "xfc-toast-dismiss", onClick: onDismiss, "aria-label": dismissAriaLabel, children: (0, jsx_runtime_1.jsx)(ToastCloseIcon, {}) })) : null] }));
 }
 /** 하단 고정 토스트 스택 (business-promotion `ToastList` UI, 상태는 부모에서 주입). */
-function ToastList({ toasts, onDismiss, className = '', dismissAriaLabel, dismissible, }) {
+function ToastList({ toasts, onDismiss, className = '', dismissAriaLabel, dismissible: listDismissible, }) {
     if (!toasts.length)
         return null;
     const listCls = ['xfc-toast-list', className].filter(Boolean).join(' ');
-    return ((0, jsx_runtime_1.jsx)("div", { className: listCls, "aria-live": "polite", children: toasts.map((t) => ((0, jsx_runtime_1.jsx)(Toast, { severity: t.severity, message: t.message, icon: t.icon, dismissAriaLabel: dismissAriaLabel, dismissible: dismissible, onDismiss: () => onDismiss(t.id) }, t.id))) }));
+    return ((0, jsx_runtime_1.jsx)("div", { className: listCls, "aria-live": "polite", "aria-relevant": "additions text", children: toasts.map((t) => {
+            const rowDismissible = t.dismissible ?? listDismissible ?? true;
+            return ((0, jsx_runtime_1.jsx)(Toast, { severity: t.severity, message: t.message, icon: t.icon, dismissAriaLabel: dismissAriaLabel, dismissible: rowDismissible, onDismiss: () => onDismiss(t.id) }, t.id));
+        }) }));
 }

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

@@ -6,7 +6,11 @@ export { Badge, type BadgeProps } from './Badge';
 export { Box, type BoxProps } from './Box';
 export { Button, type ButtonProps } from './Button';
 export { Card, type CardProps } from './Card';
+export { Checkbox, type CheckboxProps } from './Checkbox';
+export { Field, type FieldProps } from './Field';
 export { Input, type InputProps } from './Input';
+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 { Stack, type StackProps } from './Stack';

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.Input = exports.Card = exports.Button = exports.Box = exports.Badge = void 0;
+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;
 /**
  * Atomic UI — design tokens + base.css 의 `.xfc-*` 와 1:1.
  * 패키지 루트는 `components/index.ts` → 여기서 동일 심볼을 재export.
@@ -13,8 +13,16 @@ var Button_1 = require("./Button");
 Object.defineProperty(exports, "Button", { enumerable: true, get: function () { return Button_1.Button; } });
 var Card_1 = require("./Card");
 Object.defineProperty(exports, "Card", { enumerable: true, get: function () { return Card_1.Card; } });
+var Checkbox_1 = require("./Checkbox");
+Object.defineProperty(exports, "Checkbox", { enumerable: true, get: function () { return Checkbox_1.Checkbox; } });
+var Field_1 = require("./Field");
+Object.defineProperty(exports, "Field", { enumerable: true, get: function () { return Field_1.Field; } });
 var Input_1 = require("./Input");
 Object.defineProperty(exports, "Input", { enumerable: true, get: function () { return Input_1.Input; } });
+var Select_1 = require("./Select");
+Object.defineProperty(exports, "Select", { enumerable: true, get: function () { return Select_1.Select; } });
+var Textarea_1 = require("./Textarea");
+Object.defineProperty(exports, "Textarea", { enumerable: true, get: function () { return Textarea_1.Textarea; } });
 var InlineErrorList_1 = require("./InlineErrorList");
 Object.defineProperty(exports, "InlineErrorList", { enumerable: true, get: function () { return InlineErrorList_1.InlineErrorList; } });
 var LoadingOverlay_1 = require("./LoadingOverlay");

package/dist/components/overlays/BottomSheet.js

@@ -14,6 +14,7 @@ function BottomSheet({ open, onOpenChange, children, title, subtitle, headerExtr
     }, [onOpenChange]);
     (0, overlayHooks_1.useBodyScrollLock)(open);
     (0, overlayHooks_1.useEscapeKey)(open && closeOnEscape, requestClose);
+    (0, overlayHooks_1.useFocusTrap)(panelRef, open);
     (0, react_1.useEffect)(() => {
         if (!open || typeof document === 'undefined')
             return;

package/dist/components/overlays/ConfirmDialog.js

@@ -4,7 +4,7 @@ exports.ConfirmDialog = ConfirmDialog;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const Button_1 = require("../atoms/Button");
 const Dialog_1 = require("./Dialog");
-function ConfirmDialog({ open, onOpenChange, onConfirm, onCancel, title, message, confirmLabel = '확인', cancelLabel = '취소', destructive = false, confirmLoading = false, closeOnBackdropClick = true, panelClassName = '', confirmButtonProps, cancelButtonProps, }) {
+function ConfirmDialog({ open, onOpenChange, onConfirm, onCancel, title, message, confirmLabel = 'OK', cancelLabel = 'Cancel', destructive = false, confirmLoading = false, closeOnBackdropClick = true, panelClassName = '', confirmButtonProps, cancelButtonProps, }) {
     const { className: confirmClassName, onClick: confirmOnClick, disabled: confirmDisabled, ...confirmRest } = confirmButtonProps ?? {};
     const { className: cancelClassName, onClick: cancelOnClick, disabled: cancelDisabled, ...cancelRest } = cancelButtonProps ?? {};
     const handleCancel = (e) => {

package/dist/components/overlays/Dialog.js

@@ -15,6 +15,7 @@ function Dialog({ open, onOpenChange, children, title, titleAdornment, headerExt
     }, [onOpenChange]);
     (0, overlayHooks_1.useBodyScrollLock)(open);
     (0, overlayHooks_1.useEscapeKey)(open && closeOnEscape, requestClose);
+    (0, overlayHooks_1.useFocusTrap)(panelRef, open);
     (0, react_1.useEffect)(() => {
         if (!open || typeof document === 'undefined')
             return;

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

@@ -5,3 +5,4 @@
 export { BottomSheet, type BottomSheetProps } from './BottomSheet';
 export { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog';
 export { Dialog, type DialogProps } from './Dialog';
+export { useBodyScrollLock, useEscapeKey, useFocusTrap } from './overlayHooks';

package/dist/components/overlays/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Dialog = exports.ConfirmDialog = exports.BottomSheet = void 0;
+exports.useFocusTrap = exports.useEscapeKey = exports.useBodyScrollLock = exports.Dialog = exports.ConfirmDialog = exports.BottomSheet = void 0;
 /**
  * 오버레이·다이얼로그 — atoms 위 레벨. `base.css` 의 `.xfc-dialog-*` / `.xfc-bottom-sheet-*` 와 짝.
  * 패키지 루트 또는 `@xfilecom/front-core/overlays`.
@@ -11,3 +11,7 @@ var ConfirmDialog_1 = require("./ConfirmDialog");
 Object.defineProperty(exports, "ConfirmDialog", { enumerable: true, get: function () { return ConfirmDialog_1.ConfirmDialog; } });
 var Dialog_1 = require("./Dialog");
 Object.defineProperty(exports, "Dialog", { enumerable: true, get: function () { return Dialog_1.Dialog; } });
+var overlayHooks_1 = require("./overlayHooks");
+Object.defineProperty(exports, "useBodyScrollLock", { enumerable: true, get: function () { return overlayHooks_1.useBodyScrollLock; } });
+Object.defineProperty(exports, "useEscapeKey", { enumerable: true, get: function () { return overlayHooks_1.useEscapeKey; } });
+Object.defineProperty(exports, "useFocusTrap", { enumerable: true, get: function () { return overlayHooks_1.useFocusTrap; } });

package/dist/components/overlays/overlayHooks.d.ts

@@ -1,2 +1,8 @@
+import { type RefObject } from 'react';
+/**
+ * 열린 모달·시트 안에서 Tab / Shift+Tab 이 첫/끝 포커스 가능 요소에서 순환하도록 한다.
+ * 패널 루트(`tabIndex={-1}`)가 포커스를 받은 직후 Tab 도 첫 요소로 보낸다.
+ */
+export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean): void;
 export declare function useBodyScrollLock(active: boolean): void;
 export declare function useEscapeKey(active: boolean, onEscape: () => void): void;

package/dist/components/overlays/overlayHooks.js

@@ -1,8 +1,58 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFocusTrap = useFocusTrap;
 exports.useBodyScrollLock = useBodyScrollLock;
 exports.useEscapeKey = useEscapeKey;
 const react_1 = require("react");
+/** 포커스 가능한 대화형 요소 (패널 `tabIndex={-1}` 제외) */
+const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+function visibleFocusables(container) {
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => {
+        if (el.getAttribute('aria-hidden') === 'true')
+            return false;
+        const style = typeof window !== 'undefined' ? window.getComputedStyle(el) : null;
+        if (style && (style.visibility === 'hidden' || style.display === 'none'))
+            return false;
+        return true;
+    });
+}
+/**
+ * 열린 모달·시트 안에서 Tab / Shift+Tab 이 첫/끝 포커스 가능 요소에서 순환하도록 한다.
+ * 패널 루트(`tabIndex={-1}`)가 포커스를 받은 직후 Tab 도 첫 요소로 보낸다.
+ */
+function useFocusTrap(containerRef, active) {
+    (0, react_1.useEffect)(() => {
+        if (!active || typeof document === 'undefined')
+            return;
+        const root = containerRef.current;
+        if (!root)
+            return;
+        const onKeyDown = (e) => {
+            if (e.key !== 'Tab')
+                return;
+            const focusable = visibleFocusables(root);
+            if (focusable.length === 0)
+                return;
+            const first = focusable[0];
+            const last = focusable[focusable.length - 1];
+            const activeEl = document.activeElement;
+            if (!activeEl || !root.contains(activeEl))
+                return;
+            if (e.shiftKey) {
+                if (activeEl === first || activeEl === root) {
+                    e.preventDefault();
+                    last.focus();
+                }
+            }
+            else if (activeEl === last || activeEl === root) {
+                e.preventDefault();
+                first.focus();
+            }
+        };
+        document.addEventListener('keydown', onKeyDown, true);
+        return () => document.removeEventListener('keydown', onKeyDown, true);
+    }, [active, containerRef]);
+}
 function useBodyScrollLock(active) {
     (0, react_1.useEffect)(() => {
         if (!active || typeof document === 'undefined')

package/dist/generatedVersion.d.ts

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

package/dist/generatedVersion.js

@@ -0,0 +1,5 @@
+"use strict";
+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.25";

package/dist/index.d.ts

@@ -8,8 +8,11 @@
  *   import '<shared>/styles/app.css';         // 레이아웃 + 추가 오버라이드
  *
  * React: atoms `@xfilecom/front-core/atoms`, 오버레이 `@xfilecom/front-core/overlays` 또는 루트 export.
+ *
+ * 다크 모드: `tokens.css` — `html.dark` 또는 `data-theme="dark"`.
+ * 기본 UI 문자열(토스트 닫기, ConfirmDialog 버튼 등)은 영어; 앱에서 props로 한국어 등 덮어쓰기.
  */
-export declare const XFRAME_FRONT_CORE_VERSION = "0.2.4";
+export { XFRAME_FRONT_CORE_VERSION } from './generatedVersion';
 /** CSS 커스텀 프로퍼티 이름 (-- 제외 시 var()와 함께 사용) */
 export declare const tokenVars: {
     readonly colorBg: "--xfc-bg";
@@ -43,4 +46,6 @@ export declare const tokenVars: {
     readonly toastWarnBg: "--xfc-toast-warn-bg";
     readonly toastErrorBg: "--xfc-toast-error-bg";
 };
-export { Badge, BottomSheet, Box, Button, Card, ConfirmDialog, Dialog, InlineErrorList, Input, LoadingOverlay, Stack, Text, Toast, ToastList, ToastSeverityIcon, type BadgeProps, type BottomSheetProps, type BoxProps, type ButtonProps, type CardProps, type ConfirmDialogProps, type DialogProps, type InlineErrorEntry, type InlineErrorListProps, type InputProps, type LoadingOverlayProps, type StackProps, type TextProps, type TextVariant, 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, 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';
+/** 커스텀 오버레이용 — `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.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Text = exports.Stack = exports.LoadingOverlay = exports.Input = exports.InlineErrorList = exports.Dialog = exports.ConfirmDialog = 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.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).
  *
@@ -11,8 +11,12 @@ exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Text = e
  *   import '<shared>/styles/app.css';         // 레이아웃 + 추가 오버라이드
  *
  * React: atoms `@xfilecom/front-core/atoms`, 오버레이 `@xfilecom/front-core/overlays` 또는 루트 export.
+ *
+ * 다크 모드: `tokens.css` — `html.dark` 또는 `data-theme="dark"`.
+ * 기본 UI 문자열(토스트 닫기, ConfirmDialog 버튼 등)은 영어; 앱에서 props로 한국어 등 덮어쓰기.
  */
-exports.XFRAME_FRONT_CORE_VERSION = '0.2.4';
+var generatedVersion_1 = require("./generatedVersion");
+Object.defineProperty(exports, "XFRAME_FRONT_CORE_VERSION", { enumerable: true, get: function () { return generatedVersion_1.XFRAME_FRONT_CORE_VERSION; } });
 /** CSS 커스텀 프로퍼티 이름 (-- 제외 시 var()와 함께 사용) */
 exports.tokenVars = {
     colorBg: '--xfc-bg',
@@ -52,13 +56,22 @@ Object.defineProperty(exports, "BottomSheet", { enumerable: true, get: function
 Object.defineProperty(exports, "Box", { enumerable: true, get: function () { return components_1.Box; } });
 Object.defineProperty(exports, "Button", { enumerable: true, get: function () { return components_1.Button; } });
 Object.defineProperty(exports, "Card", { enumerable: true, get: function () { return components_1.Card; } });
+Object.defineProperty(exports, "Checkbox", { enumerable: true, get: function () { return components_1.Checkbox; } });
 Object.defineProperty(exports, "ConfirmDialog", { enumerable: true, get: function () { return components_1.ConfirmDialog; } });
 Object.defineProperty(exports, "Dialog", { enumerable: true, get: function () { return components_1.Dialog; } });
+Object.defineProperty(exports, "Field", { enumerable: true, get: function () { return components_1.Field; } });
 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, "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; } });
+Object.defineProperty(exports, "Textarea", { enumerable: true, get: function () { return components_1.Textarea; } });
 Object.defineProperty(exports, "Toast", { enumerable: true, get: function () { return components_1.Toast; } });
 Object.defineProperty(exports, "ToastList", { enumerable: true, get: function () { return components_1.ToastList; } });
 Object.defineProperty(exports, "ToastSeverityIcon", { enumerable: true, get: function () { return components_1.ToastSeverityIcon; } });
+/** 커스텀 오버레이용 — `Dialog`/`BottomSheet`와 동일한 훅 */
+var components_2 = require("./components");
+Object.defineProperty(exports, "useBodyScrollLock", { enumerable: true, get: function () { return components_2.useBodyScrollLock; } });
+Object.defineProperty(exports, "useEscapeKey", { enumerable: true, get: function () { return components_2.useEscapeKey; } });
+Object.defineProperty(exports, "useFocusTrap", { enumerable: true, get: function () { return components_2.useFocusTrap; } });

package/dist/tokens.css

@@ -81,3 +81,50 @@
   /* Focus */
   --xfc-focus-ring: 0 0 0 3px color-mix(in srgb, var(--xfc-accent) 35%, transparent);
 }
+
+/**
+ * Dark theme (opt-in): `<html class="dark">` or `data-theme="dark"` on `:root` / `html`.
+ * 동일한 변수 이름만 덮어쓴다 — 앱은 토큰 참조를 바꿀 필요 없음.
+ */
+html.dark,
+:root[data-theme='dark'],
+html[data-theme='dark'] {
+  color-scheme: dark;
+
+  --xfc-bg: #0f1419;
+  --xfc-bg-elevated: #1a222c;
+  --xfc-bg-muted: #141b22;
+  --xfc-bg-disabled: #2a3440;
+
+  --xfc-fg: #e8eef4;
+  --xfc-fg-strong: #ffffff;
+  --xfc-fg-label: #dce4ec;
+  --xfc-fg-muted: #8b9aab;
+  --xfc-fg-placeholder: #5c6b7a;
+  --xfc-fg-icon: #a8b8c8;
+
+  --xfc-border: #2a3440;
+  --xfc-border-strong: #3d4a5c;
+  --xfc-border-header: #2f3d4d;
+
+  --xfc-accent: #5b8aff;
+  --xfc-accent-hover: #7aa3ff;
+  --xfc-accent-fg: #0f1419;
+
+  --xfc-danger: #ff6b6b;
+  --xfc-success: #34d399;
+  --xfc-success-bg: #064e3b;
+  --xfc-warning: #fbbf24;
+  --xfc-warning-bg: #78350f;
+
+  --xfc-toast-info-bg: #1e293b;
+  --xfc-toast-success-bg: #047857;
+  --xfc-toast-warn-bg: #b45309;
+  --xfc-toast-error-bg: #dc2626;
+  --xfc-toast-shadow: 0 2px 12px rgba(0, 0, 0, 0.45);
+
+  --xfc-input-shadow: 0 4px 24px rgba(0, 0, 0, 0.25);
+  --xfc-card-shadow: 0 1px 3px rgba(0, 0, 0, 0.35);
+
+  --xfc-focus-ring: 0 0 0 3px color-mix(in srgb, var(--xfc-accent) 45%, transparent);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/front-core",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "Shared design tokens, base CSS, and atomic React components (browser-only; no Nest dependency)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "prepublishOnly": "npm run build",
-    "build": "npm run build:ts && npm run build:css",
+    "build": "node scripts/write-version.js && npm run build:ts && npm run build:css",
     "build:ts": "tsc",
     "build:css": "cp src/tokens.css dist/tokens.css && cp src/base.css dist/base.css"
   },