348 lines
12 KiB
Markdown
348 lines
12 KiB
Markdown
# KRI UI Registry
|
|
|
|
KRI 공통 shadcn UI Registry 프로젝트입니다. `npm run build`로 생성되는 `dist/r` 정적 JSON 파일을 IIS 또는 Nginx에 배포해서 사용합니다.
|
|
|
|
## 빌드 및 검증
|
|
|
|
```powershell
|
|
npm ci
|
|
npm run build
|
|
npm run verify
|
|
npm run preview
|
|
```
|
|
|
|
배포 Registry 주소:
|
|
|
|
```text
|
|
https://ui-registry.kric.com/r/registry.json
|
|
```
|
|
|
|
로컬 preview 주소 (`npm run preview` 실행 후):
|
|
|
|
```text
|
|
http://localhost:4100/r/registry.json
|
|
```
|
|
|
|
## Registry 항목
|
|
|
|
```text
|
|
kri-chart
|
|
kri-select
|
|
kri-date-range-picker
|
|
kri-date-picker
|
|
kri-date-time-picker
|
|
kri-time-picker
|
|
kri-password
|
|
kri-auto-complete
|
|
kri-data-table
|
|
kri-loading-overlay
|
|
kri-editor
|
|
kri-layout
|
|
kri-dialog
|
|
kri-color-palette
|
|
```
|
|
|
|
`kri-data-table`은 TanStack Table v8 API를 사용하며 `@tanstack/react-table@^8.21.3` 범위를 지원합니다. KriUiRegistry에서 별도의 마이그레이션 버전을 제공하기 전에는 v9으로 올리지 않습니다.
|
|
|
|
개별 설치 예시:
|
|
|
|
```powershell
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-chart.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-select.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-password.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-date-range-picker.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-date-picker.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-date-time-picker.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-time-picker.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-auto-complete.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-data-table.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-loading-overlay.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-editor.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-layout.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-dialog.json
|
|
npx shadcn@latest add https://ui-registry.kric.com/r/kri-color-palette.json
|
|
```
|
|
|
|
## KriAutoComplete 검색 스크롤
|
|
|
|
`kri-auto-complete`의 `KriSingleSelect`, `KriMultiSelect`와 내부 `MultiSelect`는 `resetScrollOnSearch?: boolean`을 지원합니다. 기본값은 `false`로 기존 동작을 유지합니다.
|
|
|
|
`true`이면 검색어 변경(삭제 포함) 후 다음 프레임에 옵션 목록의 스크롤을 맨 위로 이동합니다. `searchMode="filter"`와 `searchMode="inputOnly"` 모두 적용되며, 비동기 결과 도착만으로 다시 초기화하지는 않습니다.
|
|
|
|
```tsx
|
|
<KriSingleSelect
|
|
items={items}
|
|
value={value}
|
|
onChange={setValue}
|
|
resetScrollOnSearch
|
|
/>
|
|
```
|
|
|
|
## KriAutoComplete 옵션 툴팁
|
|
|
|
`kri-auto-complete`의 `KriSingleSelect`, `KriMultiSelect`와 내부 `MultiSelect`는 `optionTooltip?: 'singleLine' | 'wrap'`과 `optionTooltipClassName?: string`을 지원합니다. 지정하지 않으면 툴팁을 표시하지 않아 기존 동작을 유지합니다.
|
|
|
|
지정하면 옵션에 마우스를 올렸을 때 말줄임 없이 전체 `label`을 오른쪽 툴팁으로 표시합니다. `singleLine`은 화면의 사용 가능한 폭까지 한 줄로, `wrap`은 28rem 폭에서 줄바꿈합니다. `optionTooltipClassName`으로 투명도 등 프로젝트별 스타일을 덧붙일 수 있습니다. 이 항목은 shadcn `tooltip` 컴포넌트에 의존하며 `TooltipProvider`를 내부에서 제공합니다.
|
|
|
|
```tsx
|
|
<KriSingleSelect
|
|
items={items}
|
|
value={value}
|
|
onChange={setValue}
|
|
optionTooltip="singleLine"
|
|
optionTooltipClassName="opacity-65"
|
|
/>
|
|
```
|
|
|
|
## KriAutoComplete 검색 일치 방식
|
|
|
|
`kri-auto-complete`의 `KriSingleSelect`, `KriMultiSelect`와 내부 `MultiSelect`는 `searchMatch?: 'fuzzy' | 'contains'`를 지원합니다. 기본값은 `fuzzy`(cmdk 기본 부분열 점수 방식)로 기존 동작을 유지합니다.
|
|
|
|
`contains`이면 검색어를 대소문자 구분 없이 그대로 포함하는 옵션(라벨 또는 값)만 원래 순서대로 표시합니다. 예를 들어 `건설`은 `건`과 `설`이 떨어져 있는 항목과 일치하지 않습니다. `searchMode="filter"`일 때만 적용됩니다.
|
|
|
|
```tsx
|
|
<KriSingleSelect
|
|
items={items}
|
|
value={value}
|
|
onChange={setValue}
|
|
searchMatch="contains"
|
|
/>
|
|
```
|
|
|
|
## KRI Chart
|
|
|
|
`kri-chart`는 `echarts`, `echarts-for-react` 기반 공통 차트 컴포넌트입니다. 내부적으로 `BaseEChart`를 사용하며, 모든 wrapper는 멀티 시리즈를 지원합니다.
|
|
|
|
제공 컴포넌트:
|
|
|
|
```ts
|
|
BaseEChart
|
|
KriLineChart
|
|
KriBarChart
|
|
KriStackedBarChart
|
|
KriPieChart
|
|
KriRadarChart
|
|
KriScatterChart
|
|
```
|
|
|
|
### Line
|
|
|
|
```tsx
|
|
import { KriLineChart } from '@/components/chart'
|
|
|
|
<KriLineChart
|
|
categories={['1월', '2월', '3월']}
|
|
series={[
|
|
{ name: '매출', data: [120, 180, 160] },
|
|
{ name: '영업이익', data: [30, 42, 38] },
|
|
]}
|
|
smooth
|
|
/>
|
|
```
|
|
|
|
### Bar / Horizontal Bar
|
|
|
|
```tsx
|
|
import { KriBarChart } from '@/components/chart'
|
|
|
|
<KriBarChart
|
|
categories={['A', 'B', 'C']}
|
|
series={[
|
|
{ name: '2025', data: [10, 20, 30] },
|
|
{ name: '2026', data: [15, 18, 35] },
|
|
]}
|
|
isHorizontal
|
|
/>
|
|
```
|
|
|
|
### Stacked Bar
|
|
|
|
```tsx
|
|
import { KriStackedBarChart } from '@/components/chart'
|
|
|
|
<KriStackedBarChart
|
|
categories={['A', 'B', 'C']}
|
|
series={[
|
|
{ name: '직접', data: [10, 20, 30] },
|
|
{ name: '간접', data: [5, 12, 18] },
|
|
]}
|
|
/>
|
|
```
|
|
|
|
### Pie
|
|
|
|
```tsx
|
|
import { KriPieChart } from '@/components/chart'
|
|
|
|
<KriPieChart
|
|
series={[
|
|
{
|
|
name: '접속 경로',
|
|
data: [
|
|
{ name: '검색', value: 45 },
|
|
{ name: '광고', value: 25 },
|
|
{ name: '직접', value: 30 },
|
|
],
|
|
},
|
|
]}
|
|
/>
|
|
```
|
|
|
|
### Radar
|
|
|
|
```tsx
|
|
import { KriRadarChart } from '@/components/chart'
|
|
|
|
<KriRadarChart
|
|
indicators={[
|
|
{ name: '품질', max: 100 },
|
|
{ name: '속도', max: 100 },
|
|
{ name: '안정성', max: 100 },
|
|
]}
|
|
series={[
|
|
{ name: '서비스 A', data: [90, 80, 85] },
|
|
{ name: '서비스 B', data: [70, 95, 78] },
|
|
]}
|
|
/>
|
|
```
|
|
|
|
### Scatter
|
|
|
|
```tsx
|
|
import { KriScatterChart } from '@/components/chart'
|
|
|
|
<KriScatterChart
|
|
series={[
|
|
{
|
|
name: '분포',
|
|
data: [
|
|
[10, 20],
|
|
[15, 35],
|
|
[25, 30],
|
|
],
|
|
},
|
|
]}
|
|
/>
|
|
```
|
|
|
|
공통 props:
|
|
|
|
- `height`: 차트 wrapper 높이, 기본값 `CHART_HEIGHTS.DEFAULT`
|
|
- `className`, `contentClassName`, `chartClassName`: wrapper className
|
|
- `notMerge`, `lazyUpdate`, `onEvents`: `echarts-for-react` 전달 옵션
|
|
- `option`: wrapper가 생성한 ECharts option을 덮어쓰는 override 옵션
|
|
- `normalizeValues`, `decimalPlaces`: 숫자 데이터 반올림 정규화 옵션
|
|
|
|
## KriDialog Footer 규칙
|
|
|
|
기본값은 닫기 버튼이 있는 Footer입니다.
|
|
|
|
```tsx
|
|
<KriDialog open={open} onOpenChange={setOpen} title="사용자 등록">
|
|
{/* Body */}
|
|
</KriDialog>
|
|
```
|
|
|
|
기본 Footer를 제거합니다.
|
|
|
|
```tsx
|
|
<KriDialog
|
|
open={open}
|
|
onOpenChange={setOpen}
|
|
title="사용자 등록"
|
|
showDefaultFooter={false}
|
|
>
|
|
{/* Body */}
|
|
</KriDialog>
|
|
```
|
|
|
|
사용자 정의 Footer를 전달합니다. `footer`가 지정되면 기본 Footer보다 우선합니다.
|
|
|
|
```tsx
|
|
<KriDialog
|
|
open={open}
|
|
onOpenChange={setOpen}
|
|
title="사용자 등록"
|
|
footer={
|
|
<>
|
|
<Button variant="outline" onClick={() => setOpen(false)}>취소</Button>
|
|
<Button onClick={handleSave}>저장</Button>
|
|
</>
|
|
}
|
|
>
|
|
{/* Body */}
|
|
</KriDialog>
|
|
```
|
|
|
|
`footer={null}`을 전달해도 Footer가 표시되지 않습니다.
|
|
|
|
## KriColorPalette
|
|
|
|
`kri-color-palette`는 팝오버형 색상 선택 컴포넌트입니다. 기본 색상 버튼, 색상 영역·색조 슬라이더, HEX 입력, 색상 제거를 제공하며 값은 대문자 `#RRGGBB`(투명도 포함 시 `#RRGGBBAA`) 또는 `null`입니다.
|
|
|
|
```tsx
|
|
<KriColorPalette
|
|
value={color}
|
|
onChange={setColor}
|
|
aria-label="헤더 색상"
|
|
/>
|
|
```
|
|
|
|
- `colors?: readonly string[]`: 기본 색상 버튼 목록. 기본값은 `KRI_COLOR_PALETTE_DEFAULT_COLORS`(16색)입니다.
|
|
- `allowCustom?: boolean`(기본 `true`): 색상 영역·색조 슬라이더·HEX 입력 노출 여부입니다.
|
|
- `allowAlpha?: boolean`(기본 `false`): 투명도 슬라이더와 `#RRGGBBAA` 입력을 허용합니다. `false`여도 전달받은 `#RRGGBBAA` 값은 투명도까지 표시·보존하며, 사용자가 색을 바꾸면 불투명한 `#RRGGBB`로 바뀝니다.
|
|
- `allowClear?: boolean`(기본 `true`), `disabled`, `placeholder`, `className`, `aria-label`을 지원합니다. `disabled`이면 팝오버가 열리지 않습니다.
|
|
- 색상 해석·정규화와 밝기 판단 함수(`parseHexColor`, `formatHexColor`, `normalizeHexColor`, `isLightHexColor`)는 `color-palette/color.ts`에서 함께 제공합니다.
|
|
|
|
색상 영역은 [Dice UI color-picker](https://www.diceui.com/docs/components/radix/color-picker)(Radix 버전, MIT License)를 `color-palette/` 아래에 포함한 것입니다. 별도 npm 패키지 없이 `radix-ui`, `class-variance-authority`, `lucide-react`와 shadcn `button`, `input`, `popover`, `select`에 의존합니다.
|
|
|
|
## Editor 주요 옵션
|
|
|
|
```tsx
|
|
<KriEditor
|
|
mode="both"
|
|
value={html}
|
|
onChange={setHtml}
|
|
onImageUpload={async (file) => upload(file)}
|
|
enableImageMap
|
|
htmlSanitizer={sanitizeForServerPolicy}
|
|
getWysiwygCompatibility={checkWysiwygCompatibility}
|
|
smsMaxBytes={90}
|
|
lmsMaxBytes={2000}
|
|
smsPreviewSuffix={verificationNotice}
|
|
toolbar={{ image: true, table: false, html: true }}
|
|
/>
|
|
```
|
|
|
|
- 편집 값은 HTML 문자열입니다.
|
|
- 이미지 업로드 함수는 URL 문자열 또는 `{ url }`을 반환할 수 있습니다.
|
|
- `toolbar={false}`로 toolbar 전체를 숨길 수 있습니다.
|
|
- SMS preview uses UTF-8 bytes: below 90 bytes is SMS, 90 bytes or more (or a title) is LMS. Attachments take priority and display MMS. LMS/MMS input limit defaults to 2,000 UTF-8 bytes.
|
|
- `changeSmsType` now reports `'SMS' | 'LMS' | 'MMS'`; update callbacks to handle MMS. Preview type is an estimate; use the saved `tmplatTy` and actual delivery `sendTy` from server responses.
|
|
- Regression check: `node --test tests/kri-editor-sms.test.mjs`.
|
|
- `enableImageMap`은 `map`, `area`, `img.usemap` 보존을 선택적으로 활성화합니다.
|
|
- `htmlSanitizer`로 서비스의 서버 정책에 맞는 정제 함수를 주입할 수 있습니다.
|
|
- `getWysiwygCompatibility`가 `compatible: false`를 반환하면 HTML 원문을 유지하고 WYSIWYG 전환을 비활성화합니다.
|
|
- `smsPreviewSuffix`는 저장 본문에는 포함하지 않고 SMS 미리보기와 바이트 계산에만 반영합니다.
|
|
- `enableImageMap`과 `showPreview`가 함께 켜지면, 미리보기에서 `<area>` 영역(rect/circle/poly)을 반투명 박스로 표시합니다. 이미지 크기 변경·로드에 맞춰 위치를 다시 계산합니다.
|
|
- `smsFrameClassName`으로 SMS 미리보기 휴대폰 프레임에 class를 덧붙일 수 있습니다(예: 기본 높이 `h-[600px]` 조정).
|
|
- `renderToolbarEnd`를 전달하면 툴바 끝에 구분선과 함께 표시합니다. 함수가 `null`을 반환해도 구분선은 표시되므로, 조건부로 숨기려면 `renderToolbarEnd` 자체를 전달하지 마세요.
|
|
|
|
### 알림톡(KKO) 미리보기
|
|
|
|
```tsx
|
|
<KriEditor
|
|
mode="kko"
|
|
value={templateBody}
|
|
onChange={() => {}}
|
|
kkoTitle={templateTitle}
|
|
kkoSenderName="코리아리서치"
|
|
/>
|
|
```
|
|
|
|
- 편집할 수 없는 읽기 전용 미리보기입니다. `onChange`는 타입상 필수라서 빈 함수를 전달합니다.
|
|
- 본문과 제목은 텍스트로만 렌더링하며 공백·개행을 유지합니다. HTML 문자열도 글자 그대로 표시합니다.
|
|
- `#{name}`, `[$name]` 같은 변수는 원문 그대로 표시합니다. 값으로 바꿔야 하면 치환한 문자열을 `value`로 전달합니다.
|
|
- `kkoHeaderLabel` 기본값은 `알림톡 도착`이고, 본문이 비어 있으면 `placeholder`(기본값 `미리볼 내용이 없습니다.`)를 표시합니다.
|
|
- 버튼, 바로연결, 이미지, 아이템 리스트는 표시하지 않습니다.
|