kku-ui 0.9.9981 → 0.9.9983

package/README.md

@@ -1,84 +1,210 @@
-# ✨ KKU-UI ✨
-### React Component Library for Modern UI Development<br>
-
-### 🎨 스토리북
-
- 🔗 [Link](https://macjjuni.github.io/kku-ui)
-
-### 소개
-
-kku-ui는 React 기반의 컴포넌트 라이브러리로, 컴포넌트 간 유연한 조합을 위해 컴파운드 패턴과 동적인 UI 구성을 위한 Render Props 패턴이 적용되어 있습니다. 
-이를 통해 재사용성과 확장성을 높이며, 가볍게 사용할 수 있도록 만들어졌습니다.
-
-### 컴포넌트 구조
-
-프로젝트 내 컴포넌트는 크게 **Main 컴포넌트**와 **Core 컴포넌트**로 분리되어 있습니다.
-
-#### **Main 컴포넌트**
-  다지안이 적용된 최종 UI 컴포넌트입니다.
-
-| 컴포넌트               | 기능 | 스토리북 | a11y |
-|:-------------------|:----:|:--------:|:----:|
-| `<KSwitch/>`       | ✅   | ✅       | ✅   |
-| `<KButtonGroup/>`  | ✅   | ✅       | ✅   |
-| `<KToggleButton/>` | ✅   | ✅       | ✅   |
-| `<KSwitch/>`       | ✅   | ✅       | ✅   |
-| `<KSelect/>`    | ✅   | ✅       | ✅   |
-| `<KSelect/>`       | ✅   | ✅       | ✅   |
-| `<KAccordion/>`    | ✅   | ✅       | ✅   |
-| `<KMenu/>`         | ✅   | ✅       | ✅   |
-| `<KDropdown/>`     | ✅   | ✅       | ✅   |
-| `<KBackdrop/>`     | ✅   | ✅       | ✅   |
-| `<KModal/>`        | ✅   | ✅       | ✅   |
-| `<KSpinner/>`      | ✅   | ✅       | ✅   |
-| `<KIcon/>`         | ✅   | ✅       | ✅   |
-| 🏃🏻‍♂             
-
-#### **Core 컴포넌트**  
-  디자인 없이 기본 로직과 접근성(A11y) 처리만 포함된 단일 컴포넌트입니다.  
-  Main 컴포넌트 내부에서 재사용되며, 재사용성과 별도의 디자인을 적용하기 위해 만들어 졌습니다.
-
-| 컴포넌트                    | 기능 | 스토리북 | a11y |
-|:------------------------|:----:|:--------:|:----:|
-| `<KSwitch/>`            | ✅   | ✅       | ✅   |
-| `<TextField/>`         | ✅  | ✅       | ✅   |
-| `<Switch/>`            | ✅   | ✅       | ✅   |
-| `<Menu/>`              | ✅   | ✅       | ✅   |
-| `<MenuItem/>`          | ✅   | ✅       | ✅   |
-| `<KAccordion/>`         | ✅  | ✅       | ✅   |
-| `<KAccordion.Summary/>` | ✅  | ✅       | ✅   |
-| `<KAccordion.Content/>` | ✅  | ✅       | ✅   |
-
-
-## 📦 Install
+# KKU-UI
+
+[![npm version](https://img.shields.io/npm/v/kku-ui.svg)](https://www.npmjs.com/package/kku-ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+개인적으로 사용하려고 만든 Radix UI 기반 커스텀 컴포넌트 라이브러리입니다.
+
+### 🎨 Storybook
+
+**[Link](https://macjjuni.github.io/kku-ui)**
+
+---
+
+## 설치
+
+```bash
+npm install kku-ui react react-dom lucide-react
+# or
+pnpm add kku-ui react react-dom lucide-react
 ```
-npm install kku-ui
+
+`react`, `react-dom`(19 이상)과 `lucide-react`는 peerDependency이므로 앱에 직접 설치해야 합니다.
+
+## 사용법
+
+### 1. 스타일 불러오기
+
+```tsx
+// Tailwind를 쓰지 않는 앱: 전역 리셋(preflight) + 컴포넌트 스타일
+import 'kku-ui/base.css'
+import 'kku-ui/index.css'
+
+// Tailwind를 쓰는 앱: 앱의 preflight를 그대로 쓰고 컴포넌트 스타일만
+import 'kku-ui/index.css'
 ```
+
+| 파일 | 내용 |
+|---|---|
+| `kku-ui/index.css` | 디자인 토큰(CSS 변수), 폰트, 컴포넌트 스타일, 기본 border 색상, `body` 배경·글자색(라이트/다크) |
+| `kku-ui/base.css` | Tailwind preflight (선택, Tailwind를 쓰지 않는 앱용) |
+
+### 2. 컴포넌트 사용
+
+```tsx
+import { KButton, KSwitch, KAccordion } from 'kku-ui'
+
+function App() {
+  return (
+    <div>
+      <KButton>Click me</KButton>
+      <KSwitch />
+    </div>
+  )
+}
 ```
-yarn add kku-ui
+
+### 3. 커스텀 훅 사용
+
+```tsx
+import { useClickOutside, useStableId } from 'kku-ui/hooks'
+
+function MyComponent() {
+  const id = useStableId('my-component')
+  // ...
+}
+```
+
+---
+
+## 컴포넌트
+
+### Actions
+
+- `KButton` - 버튼
+- `KButtonGroup` - 버튼 그룹
+- `KSwitch` - 스위치 토글
+
+### Data Display
+
+- `KAccordion` - 아코디언
+- `KDropdownMenu` - 드롭다운 메뉴
+- `KBottomSheet` - 바텀시트
+
+### Feedback
+
+- `KDialog` - 다이얼로그
+- `KPopover` - 팝오버
+- `KSpinner` - 로딩 스피너
+- `KSkeleton` - 스켈레톤 UI
+- `KToast` - 토스트 알림
+
+### Input
+
+- `KInput` - 기본 입력
+- `KTextField` - 텍스트 필드
+- `KTextarea` - 텍스트 영역
+- `KSelect` - 셀렉트
+- `KInputGroup` - 입력 그룹
+- `KNumberStepper` - 숫자 증감
+
+### Layout
+
+- `KCard` - 카드
+- `KListRow` - 리스트 행
+- `KAspectRatio` - 종횡비 컨테이너
+
+### Foundation
+
+- `KIcon` - 아이콘 (Lucide React)
+
+---
+
+## 컴파운드 패턴
+
+```tsx
+import { KAccordion, KAccordionItem, KAccordionTrigger, KAccordionContent } from 'kku-ui'
+
+function Example() {
+  return (
+    <KAccordion type="single" collapsible>
+      <KAccordionItem value="item-1">
+        <KAccordionTrigger>제목</KAccordionTrigger>
+        <KAccordionContent>컨텐츠 내용</KAccordionContent>
+      </KAccordionItem>
+    </KAccordion>
+  )
+}
 ```
+
+## 스타일 커스터마이징
+
+CSS 변수로 테마를 덮어쓸 수 있습니다:
+
+```css
+:root {
+  --primary: 220 90% 56%;
+  --primary-foreground: 0 0% 100%;
+  --radius: 0.5rem;
+}
 ```
-pnpm add kku-ui
+
+모든 컴포넌트는 `className` prop으로 Tailwind 클래스를 추가할 수 있습니다.
+
+### 폰트
+
+`kku-ui/index.css`를 import하면 기본 폰트로 **Pretendard**(Regular/Medium/Bold)가 `body`에 자동 적용됩니다. 별도 폰트 설정이 필요 없습니다.
+
+다른 폰트를 쓰려면 `--font-sans` 변수를 덮어쓰면 됩니다. Portal로 렌더링되는 Dialog, Dropdown, Toast 등에도 함께 적용됩니다 CSS import 순서나 다크모드와 관계없이 앱의 `:root` 선언이 우선 적용됩니다.
+
+```css
+:root {
+  --font-sans: 'Noto Sans KR', sans-serif;
+}
 ```
 
-## ⚙️ Initial Setting
-```typescript
-// Entry Point 🏃🏻‍♂️
+Next.js의 `next/font`를 쓰는 경우 `body`에 폰트 클래스를 지정하거나 변수로 연결합니다.
 
-import 'kku-ui/lib/index.css'
+```tsx
+const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+// <html className={inter.variable}>
 ```
 
-## 🧑🏻‍💻 Use Examples
+```css
+:root {
+  --font-sans: var(--font-inter), sans-serif;
+}
+```
 
-```typescript
-import { KSwitch } from 'kku-ui'
+다른 폰트로 덮어쓰면 Pretendard 파일은 다운로드되지 않습니다.
 
-export default function Component() {
-  return (
-    <KSwitch label="Hello World!"/>
-  );
-} 
+---
+
+## 개발
+
+```bash
+pnpm install
+
+pnpm sb        # Storybook
+pnpm test      # 유닛 테스트
+pnpm e2e       # E2E 테스트
+pnpm build     # 빌드
 ```
 
+### 프로젝트 구조
+
+```
+src/
+├── components/ui/
+│   ├── actions/
+│   ├── data-display/
+│   ├── feedback/
+│   ├── input/
+│   ├── layout/
+│   └── foundation/
+├── common/hooks/
+└── styles/
+
+__tests__/         # 유닛 테스트
+e2e/               # E2E 테스트 (Playwright)
+```
+
+## 기술 스택
+
+- React 19 + TypeScript
+- Radix UI + Tailwind CSS
+- Vite / Vitest / Storybook / Playwright
 
+## 라이선스
 
+MIT © [macjjuni](https://github.com/macjjuni/kku-ui)

package/lib/base.css

@@ -0,0 +1,3 @@
+*,:after,:before{--tw-border-spacing-x:0;--tw-border-spacing-y:0;--tw-translate-x:0;--tw-translate-y:0;--tw-rotate:0;--tw-skew-x:0;--tw-skew-y:0;--tw-scale-x:1;--tw-scale-y:1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness:proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:rgba(59,130,246,.5);--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }::backdrop{--tw-border-spacing-x:0;--tw-border-spacing-y:0;--tw-translate-x:0;--tw-translate-y:0;--tw-rotate:0;--tw-skew-x:0;--tw-skew-y:0;--tw-scale-x:1;--tw-scale-y:1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness:proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-color:rgba(59,130,246,.5);--tw-ring-offset-shadow:0 0 #0000;--tw-ring-shadow:0 0 #0000;--tw-shadow:0 0 #0000;--tw-shadow-colored:0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }
+
+/*! tailwindcss v3.4.19 | MIT License | https://tailwindcss.com*/*,:after,:before{box-sizing:border-box;border:0 solid #e5e7eb}:after,:before{--tw-content:""}:host,html{line-height:1.5;-webkit-text-size-adjust:100%;-moz-tab-size:4;-o-tab-size:4;tab-size:4;font-family:var(--font-sans);font-feature-settings:normal;font-variation-settings:normal;-webkit-tap-highlight-color:transparent}body{margin:0;line-height:inherit}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,pre,samp{font-family:var(--font-mono);font-feature-settings:normal;font-variation-settings:normal;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}button,input,optgroup,select,textarea{font-family:inherit;font-feature-settings:inherit;font-variation-settings:inherit;font-size:100%;font-weight:inherit;line-height:inherit;letter-spacing:inherit;color:inherit;margin:0;padding:0}button,select{text-transform:none}button,input:where([type=button]),input:where([type=reset]),input:where([type=submit]){-webkit-appearance:button;background-color:transparent;background-image:none}:-moz-focusring{outline:auto}:-moz-ui-invalid{box-shadow:none}progress{vertical-align:baseline}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}summary{display:list-item}blockquote,dd,dl,figure,h1,h2,h3,h4,h5,h6,hr,p,pre{margin:0}fieldset{margin:0}fieldset,legend{padding:0}menu,ol,ul{list-style:none;margin:0;padding:0}dialog{padding:0}textarea{resize:vertical}input::-moz-placeholder,textarea::-moz-placeholder{opacity:1;color:#9ca3af}input::placeholder,textarea::placeholder{opacity:1;color:#9ca3af}[role=button],button{cursor:pointer}:disabled{cursor:default}audio,canvas,embed,iframe,img,object,svg,video{display:block;vertical-align:middle}img,video{max-width:100%;height:auto}[hidden]:where(:not([hidden=until-found])){display:none}*{border-color:hsl(var(--border))}body{background-color:hsl(var(--background));color:hsl(var(--foreground))}

package/lib/es/components/ui/actions/button/KButton.d.ts

@@ -1,7 +1,7 @@
 import { ButtonHTMLAttributes } from 'react';
 import { VariantProps } from 'class-variance-authority';
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "outline" | "primary" | "danger" | "ghost" | "link" | null | undefined;
+    variant?: "default" | "outline" | "primary" | "destructive" | "ghost" | "link" | null | undefined;
     size?: "sm" | "md" | "lg" | "icon" | null | undefined;
     width?: "default" | "full" | null | undefined;
 } & import('class-variance-authority/dist/types').ClassProp) | undefined) => string;

package/lib/es/components/ui/feedback/dialog/KDialog.d.ts

@@ -1,5 +1,5 @@
 import { HTMLAttributes } from 'react';
-import * as DialogPrimitive from "@radix-ui/react-dialog";
+import * as DialogPrimitive from '@radix-ui/react-dialog';
 export interface KDialogContextType {
     size?: 'sm' | 'md';
     opacity?: number;

package/lib/es/components/ui/feedback/popover/KPopover.d.ts

@@ -1,4 +1,4 @@
-import * as PopoverPrimitive from "@radix-ui/react-popover";
+import * as PopoverPrimitive from '@radix-ui/react-popover';
 export type KPopoverProps = React.ComponentPropsWithRef<typeof PopoverPrimitive.Root>;
 export type KPopoverTriggerProps = React.ComponentPropsWithRef<typeof PopoverPrimitive.Trigger>;
 export type KPopoverAnchorProps = React.ComponentPropsWithRef<typeof PopoverPrimitive.Anchor>;

package/lib/es/components/ui/feedback/toast/KToast.d.ts

@@ -4,7 +4,7 @@ export interface KToasterProps extends ComponentProps<typeof Sonner> {
     size?: 'sm' | 'md' | 'lg' | 'full';
 }
 declare const KToast: {
-    ({ size, position, ...props }: KToasterProps): import("react/jsx-runtime").JSX.Element;
+    (props: KToasterProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
 export { KToast, toast as kToast };

package/lib/es/components/ui/foundation/icon/KIcon.d.ts

@@ -4,7 +4,7 @@ export type KIconSize = (typeof ICON_SIZES)[number];
 export interface KIconRefs {
     click: () => void;
 }
-export type KIconProps = ComponentPropsWithRef<'span'> & {
+export type KIconProps = Omit<ComponentPropsWithRef<'span'>, 'ref'> & {
     icon: string;
     size?: KIconSize | number;
     disabled?: boolean;

package/lib/es/components/ui/input/input/KInput.d.ts

@@ -4,7 +4,7 @@ export type KInputSizeType = 'sm' | 'md' | 'lg';
 declare const inputVariants: (props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
 } & import('class-variance-authority/dist/types').ClassProp) | undefined) => string;
-export interface KInputProps extends Omit<ComponentProps<"input">, 'size'>, VariantProps<typeof inputVariants> {
+export interface KInputProps extends Omit<ComponentProps<'input'>, 'size'>, VariantProps<typeof inputVariants> {
 }
 declare const KInput: import('react').ForwardRefExoticComponent<Omit<KInputProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;
 export { KInput, inputVariants };

package/lib/es/components/ui/input/input-group/KInputGroup.d.ts

@@ -32,4 +32,4 @@ declare function KInputGroupTextarea({ className, ...props }: ComponentProps<'te
 declare namespace KInputGroupTextarea {
     var displayName: string;
 }
-export { KInputGroup, KInputGroupAddon, KInputGroupText, KInputGroupButton, KInputGroupInput, KInputGroupTextarea, };
+export { KInputGroup, KInputGroupAddon, KInputGroupText, KInputGroupButton, KInputGroupInput, KInputGroupTextarea };

package/lib/es/components/ui/input/textarea/KTextarea.d.ts

@@ -1,5 +1,5 @@
 import { ComponentProps, Ref } from 'react';
-export interface KTextareaProps extends Omit<ComponentProps<"textarea">, "ref"> {
+export interface KTextareaProps extends Omit<ComponentProps<'textarea'>, 'ref'> {
     ref?: Ref<HTMLTextAreaElement>;
 }
 declare const KTextarea: (props: KTextareaProps) => import("react/jsx-runtime").JSX.Element;

package/lib/es/components/ui/input/textfield/KTextField.d.ts

@@ -12,6 +12,7 @@ export interface KTextFieldRefs {
 }
 export interface KTextFieldProps extends Omit<ComponentProps<'input'>, 'size' | 'width' | 'ref'> {
     label?: string;
+    inputClassName?: string;
     helperText?: string;
     rules?: KValidationRule[];
     width?: VariantProps<typeof textFieldVariants>['width'] | number;

package/lib/es/hooks.js

@@ -1,36 +1,39 @@
-import { useEffect as i, useRef as c, useCallback as o } from "react";
-import { u as l } from "./chunks/useStableId-CvSXOC4i.js";
-function f(e, n, t) {
-  i(() => {
-    const r = (u) => {
-      if (e.current && !e.current.contains(u.target)) {
+import { useRef as c, useEffect as o, useCallback as a } from "react";
+import { u as p } from "./chunks/useStableId-CvSXOC4i.js";
+function f(e, r, t) {
+  const n = c(r);
+  o(() => {
+    n.current = r;
+  }), o(() => {
+    const u = (i) => {
+      if (e.current && !e.current.contains(i.target)) {
         if (!t) {
-          n();
+          n.current();
           return;
         }
-        t.current && !t.current.contains(u.target) && n();
+        t.current && !t.current.contains(i.target) && n.current();
       }
+    }, s = setTimeout(() => {
+      window.addEventListener("mousedown", u);
+    }, 0);
+    return () => {
+      clearTimeout(s), window.removeEventListener("mousedown", u);
     };
-    return setTimeout(() => {
-      window.addEventListener("mousedown", r);
-    }, 0), () => {
-      window.removeEventListener("mousedown", r);
-    };
-  }, [e]);
+  }, [e, t]);
 }
-function a() {
-  const e = c([]), n = c([]), t = o((r) => (u) => {
-    const s = n.current.indexOf(r);
+function m() {
+  const e = c([]), r = c([]), t = a((n) => (u) => {
+    const s = r.current.indexOf(n);
     if (s !== -1) {
       e.current[s] = u;
       return;
     }
-    n.current.push(r), e.current.push(u);
+    r.current.push(n), e.current.push(u);
   }, []);
   return { refs: e.current, handleRef: t };
 }
 export {
   f as useClickOutside,
-  a as useDynamicRefs,
-  l as useStableId
+  m as useDynamicRefs,
+  p as useStableId
 };