sellmate-design-system-react 9.0.0-beta.2 → 9.0.0-beta.21

package/dist/components/SEditor/README.md

@@ -0,0 +1,230 @@
+# SEditor
+
+> 자동 생성 문서 — `npm run docs:gen`. 소스: 각 컴포넌트의 Props/Handle 인터페이스 + import 의존성.
+
+### EditorBody
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `api` | `TiptapApi` | — | 다 불러온 tiptap — 이 컴포넌트는 준비된 뒤에만 마운트된다 |
+| `value?` | `string` | — |  |
+| `defaultValue?` | `string` | — |  |
+| `htmlRef` | `RefObject<string>` | — | 지금 화면에 있는 HTML. 껍데기(SEditor)가 규칙 검증·폼 제출에 쓴다 |
+| `placeholder` | `string` | — |  |
+| `typography` | `boolean` | — |  |
+| `editable` | `boolean` | — |  |
+| `disabled` | `boolean` | — |  |
+| `minHeight?` | `number \| string` | — |  |
+| `maxHeight?` | `number \| string` | — |  |
+| `toolbar` | `SEditorToolbarItem[] \| false` | — |  |
+| `bubbleMenu` | `SEditorToolbarItem[] \| false` | — | 선택 영역 위에 뜨는 서식 판. `false` 면 그리지 않는다 |
+| `fontSizes` | `number[]` | — |  |
+| `colors` | `SEditorColorOption[]` | — |  |
+| `highlights` | `SEditorColorOption[]` | — |  |
+| `editorClass?` | `string` | — |  |
+| `editorStyle?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onInput` | `(html: string) => void` | 사용자가 고쳐서 값이 바뀌었다 (setHTML·clear 같은 프로그램 조작은 제외) |
+| `onFocusChange` | `(focused: boolean) => void` |  |
+| `onReady` | `() => void` | 에디터 인스턴스가 생겼다 — 껍데기가 밀린 focus() 를 흘려보낸다 |
+| `onImageUpload` | `(file: File) => Promise<string>` |  |
+
+### EditorToolbarBar
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `state` | `EditorToolbarState` | — | 눌림 표시 — 에디터가 아직 없으면 `IDLE_TOOLBAR_STATE` |
+| `editor` | `Editor \| null` | — | 없으면 버튼을 눌러도 아무 일도 하지 않는다 (그때는 disabled 로 함께 잠근다) |
+| `items` | `SEditorToolbarItem[]` | — |  |
+| `fontSizes` | `readonly number[]` | — |  |
+| `colors` | `SEditorColorOption[]` | — |  |
+| `highlights` | `SEditorColorOption[]` | — |  |
+| `disabled` | `boolean` | — | 편집 불가(비활성·읽기전용·엔진 로딩 중) — 모든 버튼을 잠근다 |
+| `variant?` | `'bar' \| 'bubble'` | `'bar'` | `'bar'` 는 편집 영역 위에 붙는 막대, `'bubble'` 은 선택 영역 위에 뜨는 판이다. 그리는 버튼은 같고 담는 상자와 줄바꿈만 다르다. |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onImageUpload` | `(file: File) => Promise<string>` | 이미지 업로드 훅. 없으면 `image` 항목을 그리지 않는다 |
+
+### SEditor
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value?` | `string` | — | 값 (제어) — HTML 문자열 |
+| `defaultValue?` | `string` | — | 초기값 (비제어) — HTML 문자열 |
+| `placeholder?` | `string` | `'내용을 입력해 주세요.'` | 빈 문서에 보일 안내 문구 |
+| `minHeight?` | `number \| string` | `200` | 편집 영역 최소 높이 (숫자=px) |
+| `maxHeight?` | `number \| string` | — | 편집 영역 최대 높이 (숫자=px). 넘으면 편집 영역 안에서만 스크롤한다 |
+| `toolbar?` | `SEditorToolbarItem[] \| false` | `SEDITOR_DEFAULT_TOOLBAR` | 툴바 구성. `false` 면 툴바 없이 본문만 (읽기 화면·간단 메모용) |
+| `bubbleMenu?` | `SEditorToolbarItem[] \| false` | `SEDITOR_DEFAULT_BUBBLE_MENU` | 글을 선택했을 때 그 위에 뜨는 서식 판의 구성. `false` 면 뜨지 않는다. 읽기 전용·비활성일 때는 어차피 뜨지 않는다. 좁은 칸에 놓인 에디터라면 판이 필드 밖으로 넘칠 수 있으니 항목을 줄이거나 `false` 로 끈다. |
+| `fontSizes?` | `number[]` | `[...SEDITOR_FONT_SIZES]` | 글자 크기 드롭다운 선택지 (px) |
+| `colors?` | `SEditorColorOption[]` | `SEDITOR_DEFAULT_COLORS` | 글자색 팔레트 |
+| `highlights?` | `SEditorColorOption[]` | `SEDITOR_DEFAULT_HIGHLIGHTS` | 형광펜(배경색) 팔레트 |
+| `typography?` | `boolean` | `false` | 따옴표·하이픈·화살표 자동 치환 (`"` → `“”`, `--` → `—`, `->` → `→`). 상품 코드·규격 문자열이 입력한 그대로 남아야 하는 화면이 많아 기본은 끔이다. **마운트 시점에만 반영된다** — 값이 바뀌어도 이미 만들어진 에디터에는 적용되지 않는다. |
+| `rules?` | `Rule[]` | — | 유효성 규칙 — blur 시 자동 검증 |
+| `status?` | `SFieldStatus` | — | 필드 상태 ('default' | 'pass' | 'error') |
+| `focused?` | `boolean` | — | 포커스 상태 (제어/반영) |
+| `hovered?` | `boolean` | — | 호버 상태 (제어/반영) |
+| `name?` | `string` | — | 폼 전송용 name |
+| `editorClass?` | `string` | — | 편집 영역 className |
+| `editorStyle?` | `CSSProperties` | — | 편집 영역 style |
+| `label?` | `string` | — |  |
+| `labelWidth?` | `number \| string` | — |  |
+| `icon?` | `SIconName` | — | 레이블 영역 아이콘 |
+| `iconColor?` | `SColor` | — |  |
+| `labelTooltip?` | `string` | — | 레이블 툴팁 텍스트 |
+| `labelTooltipProps?` | `Partial<STooltipProps>` | — | 레이블 툴팁 상세 옵션 |
+| `addonLabel?` | `string` | — | 우측 어드온 레이블 |
+| `addonAlign?` | `SFieldAddonAlign` | — | 어드온 정렬 |
+| `hint?` | `string` | — |  |
+| `error?` | `boolean` | — |  |
+| `errorMessage?` | `string` | — |  |
+| `width?` | `SFieldWidth` | `'100%'` | 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이. 본문 길이에 상한이 없으므로 기본은 `"100%"`(행 전체)다. |
+| `disabled?` | `boolean` | `false` |  |
+| `readOnly?` | `boolean` | `false` |  |
+| `className?` | `string` | — |  |
+| `style?` | `CSSProperties` | — |  |
+
+#### Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onValueChange` | `(html: string) => void` | 값 변경 (sdUpdate) — 빈 문서면 빈 문자열을 준다 |
+| `onImageUpload` | `(file: File) => Promise<string>` | 이미지 업로드 — 고른 파일을 저장하고 **표시할 URL 을 돌려준다.** 저장 위치는 앱마다 다르므로 DS 가 정하지 않는다. 이 훅이 없으면 툴바에서 이미지 항목이 빠진다 (본문에 base64 를 박지 않는다 — HTML 이 그대로 DB 로 실려 간다). |
+| `onFocus` | `() => void` | 포커스 진입 |
+| `onBlur` | `() => void` | 포커스 이탈 |
+
+#### Methods (ref)
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `focus` | `() => void` | 편집 영역에 포커스 |
+| `blur` | `() => void` | 포커스 해제 |
+| `getHTML` | `() => string` | 현재 내용을 HTML 로 반환 (빈 문서면 빈 문자열) |
+| `getText` | `() => string` | 현재 내용을 서식 없는 텍스트로 반환 |
+| `setHTML` | `(html: string) => void` | 내용을 HTML 로 교체 (onValueChange 를 발생시키지 않는다) |
+| `clear` | `() => void` | 내용을 비운다 |
+| `editor` | `Editor \| null` | tiptap 에디터 인스턴스 — 확장 명령이 필요할 때만 쓴다 |
+
+## Types
+
+### TiptapApi
+
+```ts
+/** 동적으로 불러온 tiptap — 이 객체를 거치지 않고는 에디터 코드가 tiptap 을 만지지 않는다. */
+export interface TiptapApi {
+  useEditor: TiptapReact['useEditor'];
+  useEditorState: TiptapReact['useEditorState'];
+  EditorContent: TiptapReact['EditorContent'];
+  /** 선택 영역 위에 뜨는 판 — 자리는 floating-ui 가 잡는다 */
+  BubbleMenu: TiptapMenus['BubbleMenu'];
+  /** tiptap 확장 구성 — 아래 createExtensions 주석 참고 */
+  createExtensions: (options: SEditorExtensionOptions) => AnyExtension[];
+}
+```
+
+### SEditorToolbarItem
+
+```ts
+export type SEditorToolbarItem = SEditorToolbarAction | '|';
+```
+
+### SEditorColorOption
+
+```ts
+export interface SEditorColorOption {
+  /** 팔레트 칸의 접근성 레이블·툴팁 */
+  label: string;
+  /** 팔레트 키(`red_75` …) 또는 CSS 색상 문자열 */
+  color: SColor;
+}
+```
+
+### EditorToolbarState
+
+```ts
+export type EditorToolbarState = ReturnType<typeof readEditorState>;
+```
+
+### SEditorExtensionOptions
+
+```ts
+export interface SEditorExtensionOptions {
+  /** 빈 문서에 보일 문구를 그때그때 읽어 오는 게터 */
+  getPlaceholder: () => string;
+  /** 따옴표·하이픈·화살표 자동 치환 (Typography) */
+  typography: boolean;
+}
+```
+
+### SEditorToolbarAction
+
+```ts
+export type SEditorToolbarAction = (typeof SEDITOR_TOOLBAR_ITEMS)[number];
+```
+
+### SEDITOR_TOOLBAR_ITEMS
+
+```ts
+/** 툴바에 놓을 수 있는 항목. `'|'` 는 구분선이다. */
+export const SEDITOR_TOOLBAR_ITEMS = [
+  'heading',
+  'fontSize',
+  'bold',
+  'italic',
+  'underline',
+  'strike',
+  'code',
+  'color',
+  'highlight',
+  'superscript',
+  'subscript',
+  'alignLeft',
+  'alignCenter',
+  'alignRight',
+  'alignJustify',
+  'bulletList',
+  'orderedList',
+  'taskList',
+  'list',
+  'blockquote',
+  'codeBlock',
+  'horizontalRule',
+  'link',
+  'image',
+  'undo',
+  'redo',
+] as const;
+```
+
+## Dependencies
+
+### Depends on
+
+- [SButton](../SButton)
+- [SField](../SField)
+- [SIcon](../SIcon)
+- [SInput](../SInput)
+
+### Graph
+
+```mermaid
+graph TD;
+  SEditor --> SButton
+  SEditor --> SField
+  SEditor --> SIcon
+  SEditor --> SInput
+  style SEditor fill:#f9f,stroke:#333,stroke-width:4px
+```

package/dist/components/SEditor/SEditor.d.ts

@@ -0,0 +1,124 @@
+import { type CSSProperties } from 'react';
+import type { Editor } from '@tiptap/core';
+import { type SColor } from '../../lib/color';
+import { type SFieldWidth } from '../../lib/field-width';
+import { type Rule } from '../../lib/form';
+import { type SFieldAddonAlign, type SFieldStatus } from '../SField';
+import { type SIconName } from '../SIcon';
+import { type STooltipProps } from '../STooltip';
+import { type SEditorColorOption, type SEditorToolbarItem } from './editor.config';
+/** ref 로 노출되는 조작 메서드 */
+export interface SEditorHandle {
+    /** 편집 영역에 포커스 */
+    focus: () => void;
+    /** 포커스 해제 */
+    blur: () => void;
+    /** 현재 내용을 HTML 로 반환 (빈 문서면 빈 문자열) */
+    getHTML: () => string;
+    /** 현재 내용을 서식 없는 텍스트로 반환 */
+    getText: () => string;
+    /** 내용을 HTML 로 교체 (onValueChange 를 발생시키지 않는다) */
+    setHTML: (html: string) => void;
+    /** 내용을 비운다 */
+    clear: () => void;
+    /** tiptap 에디터 인스턴스 — 확장 명령이 필요할 때만 쓴다 */
+    editor: Editor | null;
+}
+export interface SEditorProps {
+    /** 값 (제어) — HTML 문자열 */
+    value?: string;
+    /** 초기값 (비제어) — HTML 문자열 */
+    defaultValue?: string;
+    /** 값 변경 (sdUpdate) — 빈 문서면 빈 문자열을 준다 */
+    onValueChange?: (html: string) => void;
+    /** 빈 문서에 보일 안내 문구 */
+    placeholder?: string;
+    /** 편집 영역 최소 높이 (숫자=px) */
+    minHeight?: number | string;
+    /** 편집 영역 최대 높이 (숫자=px). 넘으면 편집 영역 안에서만 스크롤한다 */
+    maxHeight?: number | string;
+    /** 툴바 구성. `false` 면 툴바 없이 본문만 (읽기 화면·간단 메모용) */
+    toolbar?: SEditorToolbarItem[] | false;
+    /**
+     * 글을 선택했을 때 그 위에 뜨는 서식 판의 구성. `false` 면 뜨지 않는다.
+     *
+     * 읽기 전용·비활성일 때는 어차피 뜨지 않는다. 좁은 칸에 놓인 에디터라면 판이 필드 밖으로
+     * 넘칠 수 있으니 항목을 줄이거나 `false` 로 끈다.
+     */
+    bubbleMenu?: SEditorToolbarItem[] | false;
+    /** 글자 크기 드롭다운 선택지 (px) */
+    fontSizes?: number[];
+    /** 글자색 팔레트 */
+    colors?: SEditorColorOption[];
+    /** 형광펜(배경색) 팔레트 */
+    highlights?: SEditorColorOption[];
+    /**
+     * 이미지 업로드 — 고른 파일을 저장하고 **표시할 URL 을 돌려준다.**
+     * 저장 위치는 앱마다 다르므로 DS 가 정하지 않는다. 이 훅이 없으면 툴바에서
+     * 이미지 항목이 빠진다 (본문에 base64 를 박지 않는다 — HTML 이 그대로 DB 로 실려 간다).
+     */
+    onImageUpload?: (file: File) => Promise<string>;
+    /**
+     * 따옴표·하이픈·화살표 자동 치환 (`"` → `“”`, `--` → `—`, `->` → `→`).
+     * 상품 코드·규격 문자열이 입력한 그대로 남아야 하는 화면이 많아 기본은 끔이다.
+     * **마운트 시점에만 반영된다** — 값이 바뀌어도 이미 만들어진 에디터에는 적용되지 않는다.
+     */
+    typography?: boolean;
+    /** 유효성 규칙 — blur 시 자동 검증 */
+    rules?: Rule[];
+    /** 필드 상태 ('default' | 'pass' | 'error') */
+    status?: SFieldStatus;
+    /** 포커스 상태 (제어/반영) */
+    focused?: boolean;
+    /** 호버 상태 (제어/반영) */
+    hovered?: boolean;
+    /** 폼 전송용 name */
+    name?: string;
+    /** 편집 영역 className */
+    editorClass?: string;
+    /** 편집 영역 style */
+    editorStyle?: CSSProperties;
+    /** 포커스 진입 */
+    onFocus?: () => void;
+    /** 포커스 이탈 */
+    onBlur?: () => void;
+    label?: string;
+    labelWidth?: number | string;
+    /** 레이블 영역 아이콘 */
+    icon?: SIconName;
+    iconColor?: SColor;
+    /** 레이블 툴팁 텍스트 */
+    labelTooltip?: string;
+    /** 레이블 툴팁 상세 옵션 */
+    labelTooltipProps?: Partial<STooltipProps>;
+    /** 우측 어드온 레이블 */
+    addonLabel?: string;
+    /** 어드온 정렬 */
+    addonAlign?: SFieldAddonAlign;
+    hint?: string;
+    error?: boolean;
+    errorMessage?: string;
+    /**
+     * 컨트롤 너비 — 폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) · 숫자=px · CSS 길이.
+     * 본문 길이에 상한이 없으므로 기본은 `"100%"`(행 전체)다.
+     */
+    width?: SFieldWidth;
+    disabled?: boolean;
+    readOnly?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * SEditor — tiptap 기반 리치 텍스트 에디터.
+ *
+ * 값은 **HTML 문자열**로 주고받는다. 들어온 HTML 은 tiptap 스키마가 파싱하므로 스키마에 없는
+ * 태그·속성(script·onerror …)은 그 자리에서 떨어져 나간다 — 별도 살균기를 거치지 않는다.
+ * 테두리 박스·라벨·에러 표시는 `SField`(multiline) 가 소유하고, 이 컴포넌트는 그 안에
+ * 툴바와 편집 영역만 세로로 쌓는다.
+ *
+ * tiptap 은 **마운트한 뒤에 불러온다** — 정적으로 묶으면 SEditor 를 한 번도 쓰지 않는 소비
+ * 앱까지 tiptap·prosemirror 를 번들에 지고 간다 (`tiptap-api.ts` 주석 참고). 불러오는 동안은
+ * 같은 크기의 빈 편집 영역이 자리를 지키므로 화면이 튀지 않고, 그 사이 `ref` 의 메서드는
+ * 아무 일도 하지 않는다 — `focus()` 만은 기억해 두었다가 준비되는 순간 흘려보낸다.
+ */
+export declare const SEditor: import("react").ForwardRefExoticComponent<SEditorProps & import("react").RefAttributes<SEditorHandle>>;

package/dist/components/SEditor/editor-icons.d.ts

@@ -0,0 +1,59 @@
+import type { SVGProps } from 'react';
+/**
+ * SEditor 서식 툴바 아이콘 (로컬 전용).
+ *
+ * 공용 아이콘 셋(`SIcon` / `icons.gen.tsx`)은 디자인팀 소유이고 서식(bold·italic·정렬·목록 …)
+ * 아이콘이 아직 없다. 여기 있는 것들은 그 자리를 메우는 임시 도형이며, 정식 아이콘이 셋에
+ * 들어오면 이 파일을 지우고 `SIcon` 으로 교체한다. **다른 컴포넌트에서 import 하지 않는다.**
+ *
+ * 도형은 tiptap Simple Editor 템플릿의 아이콘 셋을 그대로 옮겼다
+ * (ueberdosis/tiptap-ui-components, MIT © 2025 Tiptap — `apps/web/src/components/tiptap-icons`).
+ * 24×24 격자에 획 굵기 2 의 면(fill) 도형이고 색은 전부 `currentColor` 를 따른다 — 버튼이
+ * 토큰으로 정한 색이 그대로 내려온다. 새 아이콘을 더할 때도 이 격자·굵기를 지킨다.
+ *
+ * 템플릿에 없어 직접 그린 것은 `IconTextColor`·`IconHorizontalRule` 둘뿐이다 (아래 주석 참고).
+ */
+export type SEditorIconProps = {
+    size?: number | string;
+} & SVGProps<SVGSVGElement>;
+/** 제목 — 지금 단계의 도형을 보여 준다 (본문이면 단계 없는 H) */
+export declare const IconHeading: ({ level, ...p }: SEditorIconProps & {
+    level?: 0 | 1 | 2 | 3;
+}) => import("react").JSX.Element;
+export declare const IconBold: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconItalic: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconUnderline: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconStrike: (p: SEditorIconProps) => import("react").JSX.Element;
+/** 인라인 코드 */
+export declare const IconCode: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconCodeBlock: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconBlockquote: (p: SEditorIconProps) => import("react").JSX.Element;
+/** 형광펜 — 지금 고른 색은 툴바 버튼이 아이콘 아래 막대로 따로 보여 준다 */
+export declare const IconHighlight: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconSuperscript: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconSubscript: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconAlignLeft: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconAlignCenter: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconAlignRight: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconAlignJustify: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconBulletList: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconOrderedList: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconTaskList: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconLink: (p: SEditorIconProps) => import("react").JSX.Element;
+/** 좁은 화면 툴바의 하위 뷰에서 되돌아가기 */
+export declare const IconArrowLeft: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconUndo: (p: SEditorIconProps) => import("react").JSX.Element;
+export declare const IconRedo: (p: SEditorIconProps) => import("react").JSX.Element;
+/**
+ * 글자색 — 템플릿에 없어 직접 그렸다 (Simple Editor 에는 글자색 항목이 없다).
+ *
+ * 나머지 아이콘이 면 도형이라 A 도 같은 굵기(2)로 보이도록 획으로 긋고 끝을 둥글렸다 —
+ * 템플릿의 막대(`rx=1` 인 2px 사각형)와 같은 인상이다. 지금 고른 색은 형광펜과 마찬가지로
+ * 툴바 버튼이 아이콘 아래 막대로 보여 준다.
+ */
+export declare const IconTextColor: (p: SEditorIconProps) => import("react").JSX.Element;
+/**
+ * 구분선 — 템플릿에 없어 직접 그렸다 (Simple Editor 는 구분선 노드는 있지만 툴바 항목이 없다).
+ * 막대는 템플릿의 정렬 아이콘과 같은 규격(높이 2, `rx=1`)이다.
+ */
+export declare const IconHorizontalRule: (p: SEditorIconProps) => import("react").JSX.Element;

package/dist/components/SEditor/editor.config.d.ts

@@ -0,0 +1,85 @@
+import type { CSSProperties } from 'react';
+import type { SColor } from '../../lib/color';
+/** 툴바에 놓을 수 있는 항목. `'|'` 는 구분선이다. */
+export declare const SEDITOR_TOOLBAR_ITEMS: readonly ["heading", "fontSize", "bold", "italic", "underline", "strike", "code", "color", "highlight", "superscript", "subscript", "alignLeft", "alignCenter", "alignRight", "alignJustify", "bulletList", "orderedList", "taskList", "list", "blockquote", "codeBlock", "horizontalRule", "link", "image", "undo", "redo"];
+export type SEditorToolbarAction = (typeof SEDITOR_TOOLBAR_ITEMS)[number];
+export type SEditorToolbarItem = SEditorToolbarAction | '|';
+/**
+ * 기본 툴바 — tiptap Simple Editor 템플릿과 같은 순서다.
+ *
+ * 이력 → 블록(제목·목록·인용·코드블록) → 서식 → 첨자 → 정렬 → 삽입. 목록 셋은 `list`
+ * 드롭다운 하나로 묶여 있다(개별 버튼으로 펼치려면 `bulletList`·`orderedList`·`taskList`).
+ *
+ * 전체 항목(`SEDITOR_TOOLBAR_ITEMS`) 중 `fontSize`·`horizontalRule` 만 기본에서 빠져 있다 —
+ * 필요한 화면에서 `toolbar` 로 켠다. 글자색(`color`)은 템플릿에 없지만 공지·안내문에서
+ * 자주 쓰여 형광펜 옆에 함께 둔다.
+ *
+ * `image` 는 `onImageUpload` 를 받았을 때만 그려진다 (훅이 없으면 저장할 곳이 없다).
+ */
+export declare const SEDITOR_DEFAULT_TOOLBAR: SEditorToolbarItem[];
+/**
+ * 기본 버블 메뉴 — 글을 선택했을 때 그 위에 뜨는 판의 구성.
+ *
+ * tiptap Simple Editor 에는 버블 메뉴가 없다. 그래서 구성은 템플릿 툴바의 **서식 묶음**을
+ * 그대로 가져왔다 — 선택한 글에 바로 걸 수 있는 것만 남기고 블록(제목·목록·인용)·정렬·
+ * 삽입은 뺐다. 그것들은 커서만 있어도 되므로 막대에서 누르는 편이 낫다.
+ *
+ * 판은 선택 영역 위에 뜨는 한 줄이라 줄바꿈하지 않는다 — 항목을 늘릴 때 폭을 함께 본다.
+ */
+export declare const SEDITOR_DEFAULT_BUBBLE_MENU: SEditorToolbarItem[];
+/** 제목 단계 — 본문 12px 위로 14 / 16 / 18 (DS 타이포 heading sm·md·lg) */
+export declare const SEDITOR_HEADING_LEVELS: readonly [1, 2, 3];
+export type SEditorHeadingLevel = (typeof SEDITOR_HEADING_LEVELS)[number];
+export declare const SEDITOR_HEADING_LABELS: Record<SEditorHeadingLevel | 0, string>;
+/**
+ * 글자 크기 선택지 (px). DS 타이포 스케일(`--text-*`)에서 본문에 쓰이는 단계만 추렸다.
+ * 이 서비스는 정보 밀도가 높아 본문이 12px 다 (AGENTS.md §2-1).
+ */
+export declare const SEDITOR_FONT_SIZES: readonly [11, 12, 14, 16, 18];
+/** 크기를 지정하지 않은 문단이 실제로 보이는 크기 — 드롭다운의 선택 표시 기준이다. */
+export declare const SEDITOR_DEFAULT_FONT_SIZE = 12;
+export interface SEditorColorOption {
+    /** 팔레트 칸의 접근성 레이블·툴팁 */
+    label: string;
+    /** 팔레트 키(`red_75` …) 또는 CSS 색상 문자열 */
+    color: SColor;
+}
+/**
+ * 기본 글자색 팔레트 — 역할 토큰(`--color-fg-*`)을 그대로 쓴다.
+ *
+ * 저장되는 HTML 에 `style="color: var(--color-fg-danger)"` 형태로 남으므로 토큰이 바뀌면
+ * 이미 저장된 글도 따라간다. 대신 **DS `theme.css` 가 없는 환경(메일 본문 등)으로 그대로
+ * 내보내면 색이 풀린다** — 그런 용도라면 `colors` 에 hex 를 직접 넘긴다.
+ */
+export declare const SEDITOR_DEFAULT_COLORS: SEditorColorOption[];
+/** 기본 형광펜 팔레트 — 글자가 그 위에서 읽혀야 하므로 팔레트의 밝은 단계만 쓴다. */
+export declare const SEDITOR_DEFAULT_HIGHLIGHTS: SEditorColorOption[];
+/** ProseMirror 가 만드는 요소에 붙는 클래스 — 자식 선택자의 기준점이 된다. */
+export declare const TASK_LIST_CLASS = "sd-editor-task-list";
+export declare const TASK_ITEM_CLASS = "sd-editor-task-item";
+export declare const IMAGE_CLASS = "sd-editor-image";
+export interface SEditorExtensionOptions {
+    /** 빈 문서에 보일 문구를 그때그때 읽어 오는 게터 */
+    getPlaceholder: () => string;
+    /** 따옴표·하이픈·화살표 자동 치환 (Typography) */
+    typography: boolean;
+}
+/**
+ * 편집 영역 안쪽 서식 스타일.
+ *
+ * ProseMirror 가 만드는 자식 요소(h1·ul·blockquote …)는 JSX 에 없어 클래스를 달 수 없고,
+ * Tailwind preflight 가 목록·제목의 기본 스타일을 지워 버린다. 이 패키지에는 컴포넌트 CSS
+ * 파일이 없으므로 arbitrary variant 로 자식 선택자를 직접 쓴다.
+ */
+export declare const SEDITOR_CONTENT_CLASS: string;
+export interface SEditorContentStyleOptions {
+    minHeight?: number | string;
+    maxHeight?: number | string;
+    disabled?: boolean;
+}
+/**
+ * 편집 영역(그리고 엔진을 불러오는 동안 그 자리를 대신하는 빈 영역)의 상자·타이포.
+ *
+ * 두 곳이 같은 값을 써야 로딩이 끝나는 순간 글이 튀지 않는다.
+ */
+export declare const editorContentStyle: ({ minHeight, maxHeight, disabled, }: SEditorContentStyleOptions) => CSSProperties;

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

@@ -0,0 +1,2 @@
+export { SEditor, type SEditorProps, type SEditorHandle } from './SEditor';
+export { SEDITOR_TOOLBAR_ITEMS, SEDITOR_DEFAULT_TOOLBAR, SEDITOR_DEFAULT_BUBBLE_MENU, SEDITOR_HEADING_LEVELS, SEDITOR_HEADING_LABELS, SEDITOR_FONT_SIZES, SEDITOR_DEFAULT_FONT_SIZE, SEDITOR_DEFAULT_COLORS, SEDITOR_DEFAULT_HIGHLIGHTS, type SEditorToolbarAction, type SEditorToolbarItem, type SEditorHeadingLevel, type SEditorColorOption, } from './editor.config';

package/dist/components/SEditor/tiptap-api.d.ts

@@ -0,0 +1,29 @@
+import type { AnyExtension } from '@tiptap/core';
+import { type SEditorExtensionOptions } from './editor.config';
+type TiptapReact = typeof import('@tiptap/react');
+type TiptapMenus = typeof import('@tiptap/react/menus');
+/** 동적으로 불러온 tiptap — 이 객체를 거치지 않고는 에디터 코드가 tiptap 을 만지지 않는다. */
+export interface TiptapApi {
+    useEditor: TiptapReact['useEditor'];
+    useEditorState: TiptapReact['useEditorState'];
+    EditorContent: TiptapReact['EditorContent'];
+    /** 선택 영역 위에 뜨는 판 — 자리는 floating-ui 가 잡는다 */
+    BubbleMenu: TiptapMenus['BubbleMenu'];
+    /** tiptap 확장 구성 — 아래 createExtensions 주석 참고 */
+    createExtensions: (options: SEditorExtensionOptions) => AnyExtension[];
+}
+/**
+ * tiptap 을 불러온다 (이미 불러왔으면 같은 약속을 돌려준다).
+ *
+ * 실패하면 캐시를 비워 다음 마운트가 다시 시도하게 한다 — 잠깐의 네트워크 문제로
+ * 그 세션 내내 에디터가 뜨지 않는 일을 막는다.
+ */
+export declare const loadTiptapApi: () => Promise<TiptapApi>;
+/**
+ * 불러온 tiptap. 아직 준비되지 않았으면 `null`.
+ *
+ * 두 번째 마운트부터는 첫 렌더에 바로 값이 있어 빈 자리가 보이지 않는다.
+ * 서버 렌더에서는 언제나 `null` 이라 하이드레이션이 어긋나지 않는다.
+ */
+export declare const useTiptapApi: () => TiptapApi | null;
+export {};

package/dist/components/SEditor/use-is-mobile.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 좁은 화면인가 (SEditor 전용 — 다른 컴포넌트에서 import 하지 않는다).
+ *
+ * 이 DS 에는 브레이크포인트 개념이 없다. 여기에 필요한 이유는 하나뿐이라서 — 손가락으로
+ * 쓰는 좁은 화면에서는 툴바 위에 뜨는 팝오버(형광펜 팔레트·링크 입력)가 화면 밖으로
+ * 밀리거나 소프트 키보드에 가린다 — 공용 `lib/` 로 올리지 않고 이 폴더에 둔다. 나중에
+ * DS 차원의 브레이크포인트가 생기면 그걸로 갈아끼운다.
+ *
+ * **뷰포트 폭**을 본다. 필드 자신의 폭이 아니다 — 넓은 화면에서 좁은 칸에 놓인 에디터는
+ * 팝오버를 띄울 자리가 옆에 얼마든지 있으므로 하위 뷰로 바꿀 이유가 없다.
+ *
+ * 서버 렌더와 첫 렌더에서는 언제나 `false` 다 (하이드레이션이 어긋나지 않게).
+ */
+export declare const useIsMobile: () => boolean;

package/dist/components/SExpansionItem/README.md

@@ -31,6 +31,42 @@
 |-------|------|-------------|
 | `onToggle` | `(expanded: boolean, event: MouseEvent<HTMLButtonElement>) => void` |  |
 
+## Types
+
+### SExpansionItemSupportingTextPosition
+
+```ts
+export type SExpansionItemSupportingTextPosition = 'right' | 'bottom';
+```
+
+### SExpansionItemRenderProp
+
+```ts
+export type SExpansionItemRenderProp = (state: SExpansionItemRenderState) => ReactNode;
+```
+
+### SExpansionItemInteraction
+
+```ts
+export type SExpansionItemInteraction = 'chevron';
+```
+
+### SExpansionItemSize
+
+```ts
+export type SExpansionItemSize = 'sm' | 'md';
+```
+
+### SExpansionItemRenderState
+
+```ts
+export interface SExpansionItemRenderState {
+  expanded: boolean;
+  selected: boolean;
+  disabled: boolean;
+}
+```
+
 ## Dependencies
 
 ### Used by

package/dist/components/SField/README.md

@@ -28,8 +28,9 @@
 | `hint?` | `string` | `''` | 하단 힌트 |
 | `disabled?` | `boolean` | `false` | 비활성 |
 | `readOnly?` | `boolean` | `false` | 읽기 전용 (회색 배경) |
-| `width?` | `number \| string` | — | 컨트롤 너비 (숫자=px). 지정하면 필드가 부모 폭을 다 먹지 않고 (레이블 + width) 만큼만 차지한다. 다른 요소와 나란히 놓으려면 부모를 flex 로 두면 된다. |
-| `minWidth?` | `number \| string` | — | 컨트롤 최소 너비 (숫자=px). 하한선만 지정하며 필드는 계속 부모 폭을 채운다 |
+| `width?` | `SFieldWidth` | — | 컨트롤 너비. 지정하면 필드가 부모 폭을 다 먹지 않고 (레이블 + width) 만큼만 차지한다. 다른 요소와 나란히 놓으려면 부모를 flex 로 두면 된다. **폭 등급(`'xs' | 'sm' | 'md' | 'lg' | 'xl'`)으로 준다** — `--cmp-field-width-*` 토큰으로 풀리므로 토큰이 바뀌면 화면이 따라간다. 등급은 `maxLength`(= 스키마 상한)로 고르고, 상한이 `xl` 을 넘거나 상한이 없으면 `"100%"` 로 둔다. (`sellmate/field-width-grade` 가 검사한다) 숫자는 px, 그 밖의 문자열은 CSS 길이 그대로다. |
+| `minWidth?` | `SFieldWidth` | — | 컨트롤 최소 너비 (등급 · 숫자=px · CSS 길이). 하한선만 지정하며 필드는 계속 부모 폭을 채운다 |
+| `maxWidth?` | `SFieldWidth` | — | 컨트롤 최대 너비 (등급 · 숫자=px · CSS 길이). 상한선만 지정하며 필드는 그 아래에서 부모 폭을 채운다. `width` 와 달리 hug 로 전환하지 않는다 — 부모가 좁으면 같이 좁아지고, 넓어도 여기서 멈춘다. 값 길이가 정해진 컨트롤(날짜·시간)이 `width="100%"` 를 받아 행 전체로 늘어나는 것을 막는 데 쓴다. **라벨은 상한에 들어가지 않는다** — 라벨은 컨트롤의 형제라 이 상한 밖이다. `addonLabel` 은 테두리 박스 안이라 상한을 나눠 먹으므로, `labelWidth`(= addon 폭)만큼 상한을 자동으로 늘린다. addon 이 있는데 `labelWidth` 가 없으면 폭을 알 수 없어 상한을 걸지 않는다 — 컨트롤이 잘리는 것보다 넓은 편이 낫다. |
 | `multiline?` | `boolean` | `false` | 멀티라인(textarea) — 컨트롤 높이를 고정하지 않고 min-height만 적용 |
 | `borderless?` | `boolean` | `false` | 테두리 박스 제거 (inline 컨트롤용) — border/배경/hover·focus 강조만 사라지고 label·hint·errorMessage 등 나머지 필드 구성은 그대로 동작한다. |
 | `children?` | `ReactNode` | — | 실제 컨트롤 (input/select 등) — 테두리 없이 렌더, 테두리는 SField가 제공 |
@@ -49,6 +50,26 @@
 |--------|------|-------------|
 | `focus` | `() => void` | 내부 컨트롤에 포커스하고 필드를 화면에 스크롤합니다. |
 
+## Types
+
+### SFieldSize
+
+```ts
+export type SFieldSize = 'sm' | 'md';
+```
+
+### SFieldAddonAlign
+
+```ts
+export type SFieldAddonAlign = 'start' | 'center' | 'end';
+```
+
+### SFieldStatus
+
+```ts
+export type SFieldStatus = 'default' | 'pass' | 'error';
+```
+
 ## Dependencies
 
 ### Used by
@@ -57,9 +78,11 @@
  - [SChipInput](../SChipInput)
  - [SDatePicker](../SDatePicker)
  - [SDateRangePicker](../SDateRangePicker)
+ - [SEditor](../SEditor)
  - [SFilePicker](../SFilePicker)
  - [SInput](../SInput)
  - [SNumberInput](../SNumberInput)
+ - [SSearchInput](../SSearchInput)
  - [SSelect](../SSelect)
  - [STextarea](../STextarea)
  - [STimePicker](../STimePicker)
@@ -80,9 +103,11 @@ graph TD;
   SChipInput --> SField
   SDatePicker --> SField
   SDateRangePicker --> SField
+  SEditor --> SField
   SFilePicker --> SField
   SInput --> SField
   SNumberInput --> SField
+  SSearchInput --> SField
   SSelect --> SField
   STextarea --> SField
   STimePicker --> SField