@jbpark/ui-kit 10.3.0 → 10.4.0

package/README.ko.md

@@ -25,7 +25,7 @@ src/
 │   ├── molecules/    # 🔬 분자 - 원자들의 조합
 │   ├── organisms/    # 🦠 유기체 - 복잡한 UI 블록
 │   └── templates/    # 📄 템플릿 - 페이지 레이아웃
-├── core/             # ⚙️ 핵심 UI 로직 (Base UI 기반)
+├── core/             # ⚙️ 내부 Base UI 프리미티브 (export 안 됨)
 ├── lib/
 │   ├── utils/        # 🛠 유틸리티 함수
 │   ├── colors.ts     # 🎨 색상 토큰 해석
@@ -37,70 +37,105 @@ src/
 
 ## 🧬 Atoms (원자)
 
-기본적인 UI 구성 요소들
-
-| 컴포넌트        | 설명                      | 하위 컴포넌트                        |
-| --------------- | ------------------------- | ------------------------------------ |
-| **Button**      | 다양한 스타일의 버튼      | -                                    |
-| **Checkbox**    | 체크박스 및 그룹 체크박스 | `Group`                              |
-| **ColorPicker** | 색상 선택 컴포넌트        | -                                    |
-| **FloatButton** | 플로팅 버튼               | `BackTop`                            |
-| **Input**       | 입력 필드 컴포넌트        | `Search`, `TextArea`                 |
-| **Popover**     | 팝오버 툴팁 컴포넌트      | -                                    |
-| **Progress**    | 진행률 표시 컴포넌트      | -                                    |
-| **Radio**       | 라디오 버튼 컴포넌트      | -                                    |
-| **Select**      | 드롭다운 선택 컴포넌트    | -                                    |
-| **Skeleton**    | 로딩 스켈레톤             | `Button`, `Node`                     |
-| **Spin**        | 로딩 스피너               | -                                    |
-| **Switch**      | 토글 스위치               | -                                    |
-| **Tag**         | 알약 모양의 라벨/태그     | -                                    |
-| **Typography**  | 텍스트 컴포넌트           | `Link`, `Paragraph`, `Text`, `Title` |
+기본 UI 구성 요소
+
+| 컴포넌트           | 설명                                               | 하위 컴포넌트                         |
+| ------------------ | -------------------------------------------------- | ------------------------------------- |
+| **AutoComplete**   | 입력하는 동안 일치하는 옵션을 제안하는 텍스트 입력 | -                                     |
+| **Avatar**         | 이니셜·아이콘 대체 표시를 지원하는 프로필 이미지   | -                                     |
+| **Badge**          | 다른 요소에 붙는 개수 또는 상태 점                 | -                                     |
+| **Button**         | type, variant, size, 로딩 상태를 지원하는 버튼     | -                                     |
+| **Cascader**       | 여러 단계로 중첩된 옵션에서 하나를 선택            | -                                     |
+| **Checkbox**       | 단일 체크박스 또는 값 하나를 공유하는 그룹         | `Group`                               |
+| **CodeEditor**     | CodeMirror 6 편집기 (개별 경로 전용, 아래 참고)    | -                                     |
+| **ColorPicker**    | 팝오버에서 hex 색상을 고르는 스와치                | -                                     |
+| **DatePicker**     | 단일 날짜를 고르는 캘린더 팝오버 버튼              | -                                     |
+| **Divider**        | 가로·세로 구분선, 라벨 선택 가능                   | -                                     |
+| **FloatButton**    | 뷰포트 모서리에 고정된 원형 버튼                   | `BackTop`                             |
+| **Input**          | 텍스트 입력과 검색·숫자·OTP·여러 줄 변형           | `Search`, `Number`, `OTP`, `TextArea` |
+| **Mentions**       | `@` 접두 토큰을 자동 완성하는 텍스트 영역          | -                                     |
+| **Popover**        | 트리거에 붙어 뜨는 플로팅 패널                     | -                                     |
+| **Progress**       | 퍼센트만큼 채워지는 가로·세로 막대                 | -                                     |
+| **Radio**          | 단일 라디오 또는 상호 배타적 옵션 그룹             | `Group`                               |
+| **Rate**           | 별점 입력                                          | -                                     |
+| **RichTextEditor** | HTML 문자열을 다루는 TipTap 기반 편집기            | -                                     |
+| **Segmented**      | 보기 전환용 단일 선택 컨트롤                       | -                                     |
+| **Select**         | 하나 이상의 값을 고르는 드롭다운, 검색 지원        | -                                     |
+| **Skeleton**       | 로딩 중 콘텐츠 모양을 흉내 내는 자리 표시          | `Button`, `Node`                      |
+| **Slider**         | 드래그로 숫자 값이나 범위를 조절                   | -                                     |
+| **Spin**           | 단독 또는 오버레이로 쓰는 로딩 표시                | -                                     |
+| **Switch**         | 켜기/끄기 토글                                     | -                                     |
+| **Tag**            | 콘텐츠 분류용 작은 라벨                            | -                                     |
+| **TimePicker**     | 시간을 고르는 팝오버 버튼                          | -                                     |
+| **ToggleGroup**    | 각각 독립적으로 눌리는 액션 버튼 그룹              | -                                     |
+| **Tooltip**        | 호버·포커스 시 보이는 짧은 텍스트 힌트             | -                                     |
+| **Typography**     | 제목, 본문, 문단, 링크                             | `Link`, `Paragraph`, `Text`, `Title`  |
 
 ## 🔬 Molecules (분자)
 
-여러 원자들이 결합된 복합 컴포넌트들
-
-| 컴포넌트     | 설명                     | 하위 컴포넌트 |
-| ------------ | ------------------------ | ------------- |
-| **Collapse** | 접을 수 있는 컨텐츠 영역 | -             |
-| **Dropdown** | 드롭다운 메뉴            | -             |
-| **Marquees** | 무한 스크롤 마키         | `Item`        |
-| **Menu**     | 네비게이션 메뉴          | -             |
-| **Reveals**  | 애니메이션 리빌          | `Item`        |
-| **Space**    | 간격 조정 컴포넌트       | -             |
+여러 원자를 조합한 컴포넌트
+
+| 컴포넌트         | 설명                                            | 하위 컴포넌트 |
+| ---------------- | ----------------------------------------------- | ------------- |
+| **Alert**        | 상태 색상과 선택적 액션이 있는 인라인 메시지    | -             |
+| **Anchor**       | 현재 섹션을 강조하는 페이지 내 내비게이션       | -             |
+| **Breadcrumb**   | 현재 페이지까지의 경로                          | -             |
+| **Card**         | 제목을 선택할 수 있는 콘텐츠 컨테이너           | -             |
+| **Collapse**     | 펼칠 수 있는 패널, 아코디언 모드 지원           | -             |
+| **ContextMenu**  | 영역을 우클릭해 여는 메뉴                       | -             |
+| **Descriptions** | 반응형 그리드로 표시하는 라벨-값 상세 정보      | -             |
+| **Dropdown**     | 트리거에서 플로팅 `Menu`를 표시                 | -             |
+| **Empty**        | "로드됐지만 비어 있음" 상태의 인라인 자리 표시  | -             |
+| **Marquees**     | 계속 반복해 흐르는 콘텐츠 행                    | `Item`        |
+| **Menu**         | 중첩 서브메뉴를 지원하는 내비게이션 메뉴        | -             |
+| **Pagination**   | 긴 목록의 페이지 이동                           | -             |
+| **Popconfirm**   | 동작 전에 확인을 묻는 팝오버                    | -             |
+| **Reveals**      | 자식을 순차적으로 나타나게 하는 애니메이션      | `Item`        |
+| **ScrollArea**   | 스타일된 스크롤바가 있는 스크롤 컨테이너        | -             |
+| **Space**        | 자식을 가로·세로로 간격을 두고 배치             | -             |
+| **Splitter**     | 드래그 핸들로 크기를 조절하는 패널              | `Panel`       |
+| **Statistic**    | 제목과 단위가 있는 형식화된 지표                | -             |
+| **Steps**        | 순서가 있는 작업 흐름의 단계                    | -             |
+| **Tabs**         | 관련 콘텐츠 패널 사이를 전환                    | -             |
+| **Timeline**     | 타임스탬프가 있는 순서형 이벤트                 | -             |
+| **Transfer**     | 두 목록 사이로 항목 이동                        | -             |
+| **Upload**       | 클릭·드래그 업로드 영역과 삭제 가능한 파일 목록 | -             |
 
 ## 🦠 Organisms (유기체)
 
-복잡한 UI 섹션들
-
-| 컴포넌트   | 설명                     | 하위 컴포넌트 |
-| ---------- | ------------------------ | ------------- |
-| **Drawer** | 사이드 드로어            | -             |
-| **List**   | 리스트 및 리스트 아이템  | `Item`        |
-| **Modal**  | 모달 다이얼로그          | -             |
-| **Swiper** | 슬라이더/캐러셀 컴포넌트 | `Slide`       |
+복잡한 UI 섹션
+
+| 컴포넌트       | 설명                                                                  | 하위 컴포넌트                                                                               |
+| -------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **Calendar**   | 날짜 선택이나 날짜별 콘텐츠 표시용 월간 보기                          | -                                                                                           |
+| **Drawer**     | 화면 가장자리에서 밀려 나오는 제어형 패널                             | -                                                                                           |
+| **Form**       | 라벨, 설명, 오류 메시지가 있는 필드로 구성된 폼 레이아웃              | `Field`, `Control`                                                                          |
+| **List**       | 로딩·빈 상태·무한 스크롤을 지원하는 목록                              | `Item`                                                                                      |
+| **Modal**      | 제어형 또는 명령형으로 여는 다이얼로그                                | `confirm`, `info`, `success`, `warning`, `error`, `destroy`, `destroyAll`                   |
+| **Swiper**     | Swiper.js 기반의 터치 캐러셀                                          | `Slide`                                                                                     |
+| **Table**      | 셀 렌더링, 로딩·빈 상태, 선택적 페이지네이션을 지원하는 데이터 테이블 | -                                                                                           |
+| **Toast**      | 자동으로 사라지는 명령형 알림                                         | `open`, `info`, `success`, `warning`, `error`, `loading`, `config`, `destroy`, `destroyAll` |
+| **Tour**       | 요소에 붙어 단계별로 안내하는 가이드                                  | -                                                                                           |
+| **Tree**       | 펼치기, 선택, 지연 로딩을 지원하는 계층 목록                          | -                                                                                           |
+| **TreeSelect** | 옵션이 트리인 셀렉트                                                  | -                                                                                           |
 
 ## 📄 Templates (템플릿)
 
 페이지 레이아웃 템플릿
 
-| 컴포넌트   | 설명                 | 하위 컴포넌트                          |
-| ---------- | -------------------- | -------------------------------------- |
-| **Layout** | 전체 페이지 레이아웃 | `Header`, `Sider`, `Content`, `Footer` |
+| 컴포넌트       | 설명                                           | 하위 컴포넌트                          |
+| -------------- | ---------------------------------------------- | -------------------------------------- |
+| **Container**  | 최대 폭과 여백으로 페이지 콘텐츠를 가운데 정렬 | -                                      |
+| **Grid**       | 24열 반응형 그리드 (`Row`, `Col` export)       | -                                      |
+| **Layout**     | 헤더, 사이더, 콘텐츠, 푸터로 된 페이지 골격    | `Header`, `Sider`, `Content`, `Footer` |
+| **PageHeader** | 뒤로 가기 버튼과 액션이 있는 페이지 제목 블록  | -                                      |
+| **Result**     | 작업 결과를 보여주는 전체 화면                 | -                                      |
 
 ## 🛠 핵심 기능
 
-### Core 모듈
-
-Base UI 기반의 접근성 우선 핵심 컴포넌트들:
+### Base UI 기반
 
-- `accordion.tsx` - 아코디언 컴포넌트 (Base UI 기반)
-- `button.tsx` - 버튼 컴포넌트 (class-variance-authority로 variants 관리)
-- `dialog.tsx` - 다이얼로그 컴포넌트 (Base UI 기반)
-- `drawer.tsx` - 드로어 컴포넌트 (Base UI dialog 기반)
-- `progress.tsx` - 진행률 컴포넌트 (Base UI 기반)
-- `skeleton.tsx` - 스켈레톤 컴포넌트
-- `switch.tsx` - 스위치 컴포넌트 (Base UI 기반)
+컴포넌트는 [Base UI](https://base-ui.com) 프리미티브 위에 만들어져 포커스 관리, 포털, `aria-*` 배선, 팝업 위치 계산을 Base UI에 맡깁니다. 내부 프리미티브 계층(`src/core`)은 공개 API가 아니며 import할 수 없습니다.
 
 ### 유틸리티
 
@@ -154,22 +189,12 @@ Dropdown 메뉴)는 모두 `z-index: 1000`을 씁니다. 루트를 격리하지
 
 ### 개별 컴포넌트 import
 
+모든 컴포넌트는 export 이름과 같은 개별 경로로도 import할 수 있습니다(`Row`/`Col`과 `CodeEditor`는 아래 참고).
+
 ```tsx
-// Typography 컴포넌트
-// Button 컴포넌트
 import Button from '@jbpark/ui-kit/Button';
-// Card 컴포넌트
-import Card from '@jbpark/ui-kit/Card';
-// Layout 컴포넌트
-import Layout from '@jbpark/ui-kit/Layout';
-// Menu 컴포넌트
-import Menu from '@jbpark/ui-kit/Menu';
-// Reveals 컴포넌트
-import Reveals from '@jbpark/ui-kit/Reveals';
-// Space 컴포넌트
-import Space from '@jbpark/ui-kit/Space';
-// Tag 컴포넌트
-import Tag from '@jbpark/ui-kit/Tag';
+import Input from '@jbpark/ui-kit/Input';
+import Modal from '@jbpark/ui-kit/Modal';
 import Typography from '@jbpark/ui-kit/Typography';
 ```
 
@@ -180,6 +205,10 @@ import Typography from '@jbpark/ui-kit/Typography';
 > 이펙트로 불러오기 때문에 Node/SSR 빌드(예: Astro static build)에서 순수
 > `.css` import를 처리 못 해 빌드가 깨질 수 있습니다.
 
+- `Row`/`Col`은 named export라 개별 경로가 없습니다. 루트에서 `import { Row, Col } from '@jbpark/ui-kit'`로 가져옵니다.
+- `CodeEditor`는 반대로 **개별 경로 전용**입니다(`@jbpark/ui-kit/CodeEditor`). CodeMirror가 선택적 peer 의존성이라 루트 진입점에는 포함되지 않습니다.
+- 타입은 루트 진입점에서 가져옵니다: `import type { ButtonProps } from '@jbpark/ui-kit'`.
+
 ### 유틸리티 및 프로바이더 import
 
 ```tsx
@@ -272,22 +301,14 @@ pnpm run generate:component
 
 ## 📦 패키지 Exports
 
-이 패키지는 다음과 같은 모듈들을 export합니다:
-
-- `@jbpark/ui-kit` - 메인 패키지 (모든 컴포넌트)
-- `@jbpark/ui-kit/Typography` - Typography 컴포넌트
-- `@jbpark/ui-kit/Button` - Button 컴포넌트
-- `@jbpark/ui-kit/Tag` - Tag 컴포넌트
-- `@jbpark/ui-kit/Card` - Card 컴포넌트
-- `@jbpark/ui-kit/Space` - Space 컴포넌트
-- `@jbpark/ui-kit/Menu` - Menu 컴포넌트
-- `@jbpark/ui-kit/Reveals` - Reveals 컴포넌트
-- `@jbpark/ui-kit/CodeEditor` - CodeEditor 컴포넌트
-- `@jbpark/ui-kit/Layout` - Layout 템플릿
+- `@jbpark/ui-kit` - 메인 진입점 (`CodeEditor`를 제외한 모든 컴포넌트와 타입, `Config` 등 `providers` export)
+- `@jbpark/ui-kit/<ComponentName>` - 컴포넌트별 개별 경로 (default export만, 위 표의 컴포넌트 이름과 같음)
 - `@jbpark/ui-kit/utils` - 유틸리티 함수 (`cn`, `renderConditional`)
 - `@jbpark/ui-kit/providers` - Config 프로바이더 및 테마
 - `@jbpark/ui-kit/style.css` - 전역 스타일 (필수)
 
+전체 목록은 패키지 `package.json`의 `exports` 필드가 기준입니다.
+
 ## 🤝 기여하기
 
 1. 이 저장소를 포크합니다

package/README.md

@@ -25,7 +25,7 @@ src/
 │   ├── molecules/    # 🔬 Molecules - Combinations of atoms
 │   ├── organisms/    # 🦠 Organisms - Complex UI blocks
 │   └── templates/    # 📄 Templates - Page layouts
-├── core/             # ⚙️ Core UI logic (Base UI based)
+├── core/             # ⚙️ Internal Base UI primitives (not exported)
 ├── lib/
 │   ├── utils/        # 🛠 Utility functions
 │   ├── colors.ts     # 🎨 Colour token resolution
@@ -39,68 +39,103 @@ src/
 
 Basic UI building blocks
 
-| Component       | Description                  | Sub-components                       |
-| --------------- | ---------------------------- | ------------------------------------ |
-| **Button**      | Various button styles        | -                                    |
-| **Checkbox**    | Checkbox and checkbox groups | `Group`                              |
-| **ColorPicker** | Color selection component    | -                                    |
-| **FloatButton** | Floating action button       | `BackTop`                            |
-| **Input**       | Input field component        | `Search`, `TextArea`                 |
-| **Popover**     | Popover tooltip component    | -                                    |
-| **Progress**    | Progress indicator component | -                                    |
-| **Radio**       | Radio button component       | -                                    |
-| **Select**      | Select dropdown component    | -                                    |
-| **Skeleton**    | Loading skeleton             | `Button`, `Node`                     |
-| **Spin**        | Loading spinner              | -                                    |
-| **Switch**      | Toggle switch component      | -                                    |
-| **Tag**         | Pill-style label/tag         | -                                    |
-| **Typography**  | Text components              | `Link`, `Paragraph`, `Text`, `Title` |
+| Component          | Description                                                   | Sub-components                        |
+| ------------------ | ------------------------------------------------------------- | ------------------------------------- |
+| **AutoComplete**   | A text input that suggests matching options as you type       | -                                     |
+| **Avatar**         | A profile image with initials or icon fallback                | -                                     |
+| **Badge**          | A count or status dot attached to another element             | -                                     |
+| **Button**         | Buttons with type, variant, size and loading states           | -                                     |
+| **Cascader**       | Picks one value from nested option levels                     | -                                     |
+| **Checkbox**       | A single checkbox, or a group sharing one value               | `Group`                               |
+| **CodeEditor**     | CodeMirror 6 editing surface (subpath-only, see below)        | -                                     |
+| **ColorPicker**    | A swatch that opens a popover for picking a hex colour        | -                                     |
+| **DatePicker**     | A button that opens a calendar popover for a single date      | -                                     |
+| **Divider**        | A horizontal or vertical separator, optionally labeled        | -                                     |
+| **FloatButton**    | A circular button fixed to a corner of the viewport           | `BackTop`                             |
+| **Input**          | A text input, with search, number, OTP and multiline variants | `Search`, `Number`, `OTP`, `TextArea` |
+| **Mentions**       | A text area that completes `@`-prefixed tokens                | -                                     |
+| **Popover**        | A floating panel anchored to a trigger element                | -                                     |
+| **Progress**       | A bar that fills to a percentage, horizontal or vertical      | -                                     |
+| **Radio**          | A single radio, or a group for mutually-exclusive options     | `Group`                               |
+| **Rate**           | A star rating input                                           | -                                     |
+| **RichTextEditor** | A TipTap-based editor over an HTML string                     | -                                     |
+| **Segmented**      | A single-choice control for switching views                   | -                                     |
+| **Select**         | A dropdown for choosing one or more values, with search       | -                                     |
+| **Skeleton**       | A placeholder that mimics content while it loads              | `Button`, `Node`                      |
+| **Slider**         | A draggable numeric value or range control                    | -                                     |
+| **Spin**           | A loading indicator, standalone or as an overlay              | -                                     |
+| **Switch**         | A boolean on/off toggle                                       | -                                     |
+| **Tag**            | A small labeled badge for categorising content                | -                                     |
+| **TimePicker**     | A button that opens a popover for picking a time              | -                                     |
+| **ToggleGroup**    | A group of independently pressed action buttons               | -                                     |
+| **Tooltip**        | A short text hint shown on hover or focus                     | -                                     |
+| **Typography**     | Headings, body text, paragraphs and links                     | `Link`, `Paragraph`, `Text`, `Title`  |
 
 ## 🔬 Molecules
 
 Composite components combining multiple atoms
 
-| Component    | Description                | Sub-components |
-| ------------ | -------------------------- | -------------- |
-| **Collapse** | Collapsible content area   | -              |
-| **Dropdown** | Dropdown menu              | -              |
-| **Marquees** | Infinite scrolling marquee | `Item`         |
-| **Menu**     | Navigation menu            | -              |
-| **Reveals**  | Animation reveal component | `Item`         |
-| **Space**    | Spacing adjustment         | -              |
+| Component        | Description                                                | Sub-components |
+| ---------------- | ---------------------------------------------------------- | -------------- |
+| **Alert**        | An inline message with a status colour and optional action | -              |
+| **Anchor**       | In-page navigation that highlights the current section     | -              |
+| **Breadcrumb**   | The path to the current page                               | -              |
+| **Card**         | A content container with an optional title                 | -              |
+| **Collapse**     | Expandable panels, with an optional accordion mode         | -              |
+| **ContextMenu**  | A menu opened by right-clicking an area                    | -              |
+| **Descriptions** | Labeled record details in a responsive grid                | -              |
+| **Dropdown**     | Reveals a floating `Menu` from a trigger                   | -              |
+| **Empty**        | An inline placeholder for the "loaded, but empty" state    | -              |
+| **Marquees**     | Rows of content scrolling in a continuous loop             | `Item`         |
+| **Menu**         | Navigation menu with nested submenus                       | -              |
+| **Pagination**   | Page navigation for long lists                             | -              |
+| **Popconfirm**   | A popover that asks for confirmation before an action      | -              |
+| **Reveals**      | Animates children into view with a staggered cascade       | `Item`         |
+| **ScrollArea**   | A scroll container with styled scrollbars                  | -              |
+| **Space**        | Lays out children in a row or column with gaps             | -              |
+| **Splitter**     | Resizable panels with a draggable handle between them      | `Panel`        |
+| **Statistic**    | A formatted metric with a title and unit                   | -              |
+| **Steps**        | The stages of an ordered workflow                          | -              |
+| **Tabs**         | Switches between panels of related content                 | -              |
+| **Timeline**     | Ordered events with timestamps                             | -              |
+| **Transfer**     | Moves items between two lists                              | -              |
+| **Upload**       | A click-or-drag dropzone with a removable file list        | -              |
 
 ## 🦠 Organisms
 
 Complex UI sections
 
-| Component  | Description               | Sub-components |
-| ---------- | ------------------------- | -------------- |
-| **Drawer** | Side drawer panel         | -              |
-| **List**   | List and list items       | `Item`         |
-| **Modal**  | Modal dialog              | -              |
-| **Swiper** | Slider/carousel component | `Slide`        |
+| Component      | Description                                                                       | Sub-components                                                                              |
+| -------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **Calendar**   | A month view for picking dates or showing date content                            | -                                                                                           |
+| **Drawer**     | A controlled panel that slides in from any edge                                   | -                                                                                           |
+| **Form**       | Form layout with labeled fields, descriptions and error messages                  | `Field`, `Control`                                                                          |
+| **List**       | A collection with loading, empty and infinite-scroll states                       | `Item`                                                                                      |
+| **Modal**      | A dialog, controlled or fired imperatively                                        | `confirm`, `info`, `success`, `warning`, `error`, `destroy`, `destroyAll`                   |
+| **Swiper**     | A touch-friendly carousel over Swiper.js                                          | `Slide`                                                                                     |
+| **Table**      | A data table with custom cells, loading and empty states, and optional pagination | -                                                                                           |
+| **Toast**      | Imperative, auto-dismissing notifications                                         | `open`, `info`, `success`, `warning`, `error`, `loading`, `config`, `destroy`, `destroyAll` |
+| **Tour**       | A guided walkthrough of steps anchored to elements                                | -                                                                                           |
+| **Tree**       | A hierarchical list with expand, select and lazy loading                          | -                                                                                           |
+| **TreeSelect** | A select whose options are a tree                                                 | -                                                                                           |
 
 ## 📄 Templates
 
 Page layout templates
 
-| Component  | Description      | Sub-components                         |
-| ---------- | ---------------- | -------------------------------------- |
-| **Layout** | Full page layout | `Header`, `Sider`, `Content`, `Footer` |
+| Component      | Description                                           | Sub-components                         |
+| -------------- | ----------------------------------------------------- | -------------------------------------- |
+| **Container**  | Centres page content at a capped width with gutters   | -                                      |
+| **Grid**       | A 24-column responsive grid (`Row` and `Col` exports) | -                                      |
+| **Layout**     | The page scaffold: header, sider, content and footer  | `Header`, `Sider`, `Content`, `Footer` |
+| **PageHeader** | A page title block with back button and actions       | -                                      |
+| **Result**     | A full-page screen for an operation's outcome         | -                                      |
 
 ## 🛠 Core Features
 
-### Core Module
+### Built on Base UI
 
-Accessibility-first core components based on Base UI:
-
-- `accordion.tsx` - Accordion component (Base UI based)
-- `button.tsx` - Button component (variants managed with class-variance-authority)
-- `dialog.tsx` - Dialog component (Base UI based)
-- `drawer.tsx` - Drawer component (Base UI dialog based)
-- `progress.tsx` - Progress component (Base UI based)
-- `skeleton.tsx` - Skeleton component
-- `switch.tsx` - Switch component (Base UI based)
+Components are built on [Base UI](https://base-ui.com) primitives, which handle focus management, portals, `aria-*` wiring and popup positioning. The internal primitive layer (`src/core`) is not part of the public API and cannot be imported.
 
 ### Utilities
 
@@ -154,22 +189,12 @@ covers the whole app, including this chrome.
 
 ### Import Individual Components
 
+Every component can also be imported from a subpath named after its export (see below for `Row`/`Col` and `CodeEditor`).
+
 ```tsx
-// Typography component
-// Button component
 import Button from '@jbpark/ui-kit/Button';
-// Card component
-import Card from '@jbpark/ui-kit/Card';
-// Layout component
-import Layout from '@jbpark/ui-kit/Layout';
-// Menu component
-import Menu from '@jbpark/ui-kit/Menu';
-// Reveals component
-import Reveals from '@jbpark/ui-kit/Reveals';
-// Space component
-import Space from '@jbpark/ui-kit/Space';
-// Tag component
-import Tag from '@jbpark/ui-kit/Tag';
+import Input from '@jbpark/ui-kit/Input';
+import Modal from '@jbpark/ui-kit/Modal';
 import Typography from '@jbpark/ui-kit/Typography';
 ```
 
@@ -180,6 +205,10 @@ import Typography from '@jbpark/ui-kit/Typography';
 > `swiper`'s CSS as a side effect and can break Node/SSR builds (e.g. an
 > Astro static build) that don't expect a bare `.css` import.
 
+- `Row`/`Col` are named exports and have no subpath. Import them from the root: `import { Row, Col } from '@jbpark/ui-kit'`.
+- `CodeEditor` is the opposite: it is **subpath-only** (`@jbpark/ui-kit/CodeEditor`). CodeMirror is an optional peer dependency, so the root entry does not include it.
+- Import types from the root entry: `import type { ButtonProps } from '@jbpark/ui-kit'`.
+
 ### Import Utilities and Providers
 
 ```tsx
@@ -272,22 +301,14 @@ pnpm run generate:component
 
 ## 📦 Package Exports
 
-This package exports the following modules:
-
-- `@jbpark/ui-kit` - Main package (all components)
-- `@jbpark/ui-kit/Typography` - Typography component
-- `@jbpark/ui-kit/Button` - Button component
-- `@jbpark/ui-kit/Tag` - Tag component
-- `@jbpark/ui-kit/Card` - Card component
-- `@jbpark/ui-kit/Space` - Space component
-- `@jbpark/ui-kit/Menu` - Menu component
-- `@jbpark/ui-kit/Reveals` - Reveals component
-- `@jbpark/ui-kit/CodeEditor` - CodeEditor component
-- `@jbpark/ui-kit/Layout` - Layout template
+- `@jbpark/ui-kit` - Main entry (every component except `CodeEditor`, their types, and the `providers` exports such as `Config`)
+- `@jbpark/ui-kit/<ComponentName>` - One subpath per component (default export only), named as in the tables above
 - `@jbpark/ui-kit/utils` - Utility functions (`cn`, `renderConditional`)
 - `@jbpark/ui-kit/providers` - Config provider and theming
 - `@jbpark/ui-kit/style.css` - Global styles (required)
 
+The `exports` field of the package's `package.json` is the full, authoritative list.
+
 ## 🤝 Contributing
 
 1. Fork this repository

package/dist/AutoComplete.mjs

@@ -3,7 +3,7 @@ import { cn } from "./utils.mjs";
 import { DEFAULT_LOCALE, useConfig } from "./providers/config/context.mjs";
 import Button from "./Button.mjs";
 import { autocomplete_exports } from "./core/autocomplete.mjs";
-import Input from "./components/atoms/input/index.mjs";
+import Input from "./Input.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { XIcon } from "lucide-react";
 //#region src/components/atoms/auto-complete.tsx

package/dist/Breadcrumb.mjs

@@ -2,7 +2,7 @@
 import { cn } from "./utils.mjs";
 import { useConfig } from "./providers/config/context.mjs";
 import Button from "./Button.mjs";
-import Popover from "./components/atoms/popover.mjs";
+import Popover from "./Popover.mjs";
 import { Fragment } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/molecules/breadcrumb.tsx

package/dist/Cascader.mjs

@@ -2,8 +2,8 @@
 import { cn } from "./utils.mjs";
 import { useConfig } from "./providers/config/context.mjs";
 import Button from "./Button.mjs";
-import Popover from "./components/atoms/popover.mjs";
-import Select from "./components/atoms/select.mjs";
+import Popover from "./Popover.mjs";
+import Select from "./Select.mjs";
 import { useId, useState } from "react";
 import { DirectionProvider } from "@base-ui/react/direction-provider";
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/Checkbox.d.mts

@@ -0,0 +1,10 @@
+import Group from "./components/atoms/checkbox/group.mjs";
+import Checkbox$1, { Props } from "./components/atoms/checkbox/checkbox.mjs";
+//#region src/components/atoms/checkbox/index.d.ts
+type CheckboxComponent = typeof Checkbox$1 & {
+  Group: typeof Group;
+};
+declare const Checkbox: CheckboxComponent;
+//#endregion
+export { type Props, Checkbox as default };
+//# sourceMappingURL=Checkbox.d.mts.map

package/dist/Checkbox.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Checkbox.d.mts","names":["CheckboxImpl"],"sources":["../src/components/atoms/checkbox/index.ts"],"mappings":";;;KAGK,2BAA2BA;EAAiB,cAAc;;cAEzD,UAA2B"}

package/dist/Checkbox.mjs

@@ -0,0 +1,9 @@
+import Checkbox$1 from "./components/atoms/checkbox/checkbox.mjs";
+import Group from "./components/atoms/checkbox/group.mjs";
+//#region src/components/atoms/checkbox/index.ts
+const Checkbox = Checkbox$1;
+Checkbox.Group = Group;
+//#endregion
+export { Checkbox as default };
+
+//# sourceMappingURL=Checkbox.mjs.map

package/dist/Checkbox.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Checkbox.mjs","names":["CheckboxImpl"],"sources":["../src/components/atoms/checkbox/index.ts"],"sourcesContent":["import CheckboxImpl, { type Props } from './checkbox';\nimport Group from './group';\n\ntype CheckboxComponent = typeof CheckboxImpl & { Group: typeof Group };\n\nconst Checkbox = CheckboxImpl as CheckboxComponent;\n\nCheckbox.Group = Group;\n\nexport default Checkbox;\nexport type { Props };\n"],"mappings":";;;AAKA,MAAM,WAAWA;AAEjB,SAAS,QAAQ"}

package/dist/CodeEditor.d.mts

@@ -15,7 +15,13 @@ export interface Props extends Omit<React.ComponentProps<typeof CodeMirror>, 'va
    * still means what it does upstream: no theme extension, style it yourself.
    */
   theme?: 'light' | 'dark' | 'auto' | 'none' | Extension;
-  /** Appended after the built-in JS/TS + line-wrapping extensions. */
+  /**
+   * The language extension. Omitted, it is the built-in JS/TS/JSX mode; an
+   * `Extension` replaces it (e.g. `json()` from `@codemirror/lang-json`, which
+   * the caller installs), and `null` leaves the document as plain text.
+   */
+  language?: Extension | null;
+  /** Appended after the language and line-wrapping extensions. */
   extensions?: Extension[];
   /**
    * Renders a read-through unified diff against `original` instead of a plain
@@ -45,7 +51,7 @@ export interface Props extends Omit<React.ComponentProps<typeof CodeMirror>, 'va
    */
   onFormatError?: (error: string | null) => void;
 }
-declare const CodeEditor: ({ value, theme, height, className, extensions: extraExtensions, diff, formatCode, onChange, onSave, onFormatError, ...props }: Props) => import("react").JSX.Element;
+declare const CodeEditor: ({ value, theme, height, className, language, extensions: extraExtensions, diff, formatCode, onChange, onSave, onFormatError, ...props }: Props) => import("react").JSX.Element;
 //#endregion
 export { CodeEditor as default };
 //# sourceMappingURL=CodeEditor.d.mts.map

package/dist/CodeEditor.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeEditor.d.mts","names":[],"sources":["../src/components/atoms/code-editor.tsx"],"mappings":";;iBA2BiB,cAAc,KAC7B,MAAM,sBAAsB;EAG5B;;EAEA;;;;;;;;;;;EAWA,6CAA6C;;EAE7C,aAAa;;;;;;EAMb;IACE;IACA;;;;;;;;EAQF,cAAc,iBAAiB;EAC/B;EACA,YAAY;;EAEZ,UAAU;;;;;;;EAOV,iBAAiB;;cAGb,eAAc,OAAA,OAAA,QAAA,WAAA,YAAA,iBAAA,MAAA,YAAA,UAAA,QAAA,kBAAA,SAYjB,0BAAK,IAAA"}
+{"version":3,"file":"CodeEditor.d.mts","names":[],"sources":["../src/components/atoms/code-editor.tsx"],"mappings":";;iBA2BiB,cAAc,KAC7B,MAAM,sBAAsB;EAG5B;;EAEA;;;;;;;;;;;EAWA,6CAA6C;;;;;;EAM7C,WAAW;;EAEX,aAAa;;;;;;EAMb;IACE;IACA;;;;;;;;EAQF,cAAc,iBAAiB;EAC/B;EACA,YAAY;;EAEZ,UAAU;;;;;;;EAOV,iBAAiB;;cAGb,eAAc,OAAA,OAAA,QAAA,WAAA,UAAA,YAAA,iBAAA,MAAA,YAAA,UAAA,QAAA,kBAAA,SAajB,0BAAK,IAAA"}

package/dist/CodeEditor.mjs

@@ -9,7 +9,7 @@ import { vscodeDark, vscodeLight } from "@uiw/codemirror-theme-vscode";
 import CodeMirror from "@uiw/react-codemirror";
 import { EditorView } from "codemirror";
 //#region src/components/atoms/code-editor.tsx
-const CodeEditor = ({ value, theme = "auto", height, className, extensions: extraExtensions, diff, formatCode, onChange, onSave, onFormatError, ...props }) => {
+const CodeEditor = ({ value, theme = "auto", height, className, language, extensions: extraExtensions, diff, formatCode, onChange, onSave, onFormatError, ...props }) => {
 	const editorRef = useRef(null);
 	const isDarkActive = useIsDarkActive();
 	const resolvedTheme = useMemo(() => {
@@ -19,16 +19,21 @@ const CodeEditor = ({ value, theme = "auto", height, className, extensions: extr
 		return theme;
 	}, [theme, isDarkActive]);
 	const extensions = useMemo(() => {
-		const base = [javascript({
+		const languageExtension = language === void 0 ? javascript({
 			jsx: true,
 			typescript: true
-		}), EditorView.lineWrapping];
+		}) : language;
+		const base = languageExtension ? [languageExtension, EditorView.lineWrapping] : [EditorView.lineWrapping];
 		if (diff) base.push(unifiedMergeView({
 			original: diff.original,
 			mergeControls: diff.mergeControls ?? false
 		}));
 		return [...base, ...extraExtensions ?? []];
-	}, [diff, extraExtensions]);
+	}, [
+		language,
+		diff,
+		extraExtensions
+	]);
 	const save = useCallback(async (val) => {
 		const view = editorRef.current?.view;
 		if (!view) return;