@aeriz/wysiwyg 1.0.2 → 1.0.3

package/dist-types/cjs/core/AerizEditor.d.cts

@@ -0,0 +1,357 @@
+import type { EditorOptions, SerializeHtmlOptions } from '../types/index.cjs';
+import { Toolbar } from '../ui/Toolbar.cjs';
+import type { Block, BlockAttrs, BlockKind, BlockSnapshot } from './blocks.cjs';
+export type { Block, BlockAttrs, BlockKind, BlockMatch, BlockSnapshot, BlockType, ClassifyResult, HeadingLevel, } from './blocks.cjs';
+export interface InlineState {
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    strike: boolean;
+}
+export interface EditorState {
+    blocks: Block[];
+    activeBlockId: string | null;
+    inline: InlineState;
+}
+export type EditorStateListener = (state: EditorState) => void;
+export declare class AerizEditor {
+    readonly root: HTMLDivElement;
+    readonly content: HTMLDivElement;
+    readonly toolbar: Toolbar | null;
+    private readonly contentWrap;
+    private readonly handlesLayer;
+    private readonly dropIndicator;
+    private readonly handles;
+    private readonly blockLabelPill;
+    private readonly statusBar;
+    private readonly statusBlockEl;
+    private readonly statusBlocksEl;
+    private readonly statusCharsEl;
+    private readonly statusSourceEl;
+    private readonly options;
+    private readonly observer;
+    private readonly blockIds;
+    private readonly idFor;
+    private readonly listeners;
+    private readonly handleSelectionChange;
+    private readonly handleResize;
+    private state;
+    private destroyed;
+    private syncQueued;
+    private lastSerialized;
+    /** 사용자가 색 다이얼로그에서 직접 고른 색상의 LRU. 에디터 인스턴스 메모리에만 유지. */
+    private recentCustomColors;
+    constructor(options: EditorOptions);
+    /**
+     * 본문 HTML 을 반환한다.
+     *
+     * 두 가지 스타일 전략을 지원한다 (`options.styles`, 기본값은 생성 시
+     * `EditorOptions.htmlStyles`, 그것도 없으면 `'inline'`).
+     *
+     * - `'inline'` — 호출 시점의 테마 변수(--aw-primary 등) 를 읽어 블록 단위
+     *   인라인 스타일에 베이크한다. 스타일시트 없이 어디에 붙여도(이메일 본문,
+     *   다른 페이지) 에디터에서 보이는 그대로 렌더된다.
+     * - `'class'` — 테마 스타일을 베이크하지 않고 `aw-block-*` / `aw-align-*`
+     *   클래스만 남긴다. `style` 속성을 지우는 서버 sanitizer 아래에서 서식을
+     *   보존해야 할 때 쓴다. 출력은 `aeriz-wysiwyg.min.css` 를 로드한 페이지의
+     *   `.aeriz-wysiwyg > .aw-content` 안에 넣는 것을 전제로 한다.
+     *
+     * 어느 쪽이든 에디터 내부 DOM 은 변형되지 않으며(clone 트리에 적용),
+     * data-block-kind / data-block-focused 같은 에디터 전용 속성과 리사이즈
+     * 핸들 · 정렬 컨트롤 같은 편집 보조 마크업은 출력에서 제거된다.
+     * data-block-id 는 보존.
+     */
+    getHTML(options?: SerializeHtmlOptions): string;
+    /** 가공 없는 원본 innerHTML. 직렬화 검증/디버그 용도. */
+    getRawHTML(): string;
+    setHTML(html: string): void;
+    focus(): void;
+    setTheme(theme: 'light' | 'dark'): void;
+    getState(): EditorState;
+    getBlocks(): Block[];
+    /**
+     * 본문 블록들을 직렬화 가능한 BlockSnapshot 배열로 반환한다.
+     * AerizViewer.setBlocks(snapshots) 가 받아 동일한 트리를 렌더할 수 있다.
+     */
+    serialize(): BlockSnapshot[];
+    /**
+     * data-block-id 로 본문에서 블록을 찾아 반환. 없으면 null.
+     */
+    findBlockById(id: string): Block | null;
+    getActiveBlock(): Block | null;
+    /**
+     * 블록 유형을 변경/추가한다.
+     * - `targetBlockId` 지정 시 그 id 의 블록을 강제 대상으로 한다 (다이얼로그
+     *   확인 등으로 선택이 다른 곳으로 넘어간 뒤에도 원래 블록을 정확히 변환).
+     * - 미지정 시 현재 active block 사용. 둘 다 없으면 본문 끝에 새 블록 추가.
+     */
+    setBlockType(kind: BlockKind, attrs?: BlockAttrs, targetBlockId?: string): void;
+    private replaceBlock;
+    private appendBlock;
+    onStateChange(listener: EditorStateListener): () => void;
+    destroy(): void;
+    /**
+     * DOM 변화 후 호출되는 reconcile 진입점.
+     * 누락된 data-block-id 를 채우고, 자기 쓰기로 발생한 옵저버 레코드를
+     * takeRecords 로 흡수한 뒤 onChange + queueSync.
+     */
+    private flush;
+    private handleToolbarAction;
+    /**
+     * 인라인 마크(bold/italic/underline/strike) 토글. 활성 블록의 allowedMarks
+     * 에 포함되지 않은 마크면 무시. styleWithCSS=true 모드로 deprecated 태그
+     * (<b>/<i>/<u>) 대신 `<span style="font-weight:bold">` 형태가 만들어진다.
+     *
+     * 'strike' 는 execCommand 표준 명령명이 'strikeThrough'.
+     */
+    private applyMark;
+    /**
+     * 색상 선택기에서 받은 색을 LRU 에 누적하고 selection 에 적용한다.
+     * `command` 가 'foreColor' 면 글자색, 'hiliteColor' 면 글 배경색.
+     */
+    private handleColorPick;
+    /**
+     * selection 에 색상을 적용. styleWithCSS=true 모드로 `<span style="color:…">`
+     * 또는 `<span style="background-color:…">` 형태가 만들어진다.
+     * `null` 은 '기본색' — 'inherit' 으로 부모 색을 따라가도록.
+     */
+    private applyColor;
+    /**
+     * 정렬을 활성 블록(또는 표 셀) 에 적용한다.
+     *
+     * execCommand('justify*') 는 일부 브라우저에서 blockquote 안의 <p> 에 적용
+     * 시 blockquote 를 <div style="text-align:..."> 로 바꿔버리는 잘 알려진
+     * 버그가 있어 직접 DOM 조작으로 대체한다.
+     *
+     * 적용 대상:
+     *   paragraph / heading → element 자체
+     *   blockquote          → 안의 <p> (없으면 자기 자신)
+     *   table 단일 셀       → 캐럿이 들어 있는 td/th
+     *   table 다중 셀 마킹  → 각 cell.style.textAlign 일괄
+     */
+    private applyAlign;
+    /** 캐럿이 들어 있는 표 셀(td/th) 반환. 표 밖이면 null. */
+    private getActiveTableCell;
+    /**
+     * 현재 활성 셀(들) 을 반환한다.
+     *  1순위: 커스텀 드래그-셀렉션으로 마킹된 `.aw-cell-selected` 셀들
+     *  2순위: 브라우저 selection range 가 가리키는 표 셀(들)
+     *  3순위: 캐럿이 들어 있는 단일 셀
+     */
+    private getSelectedTableCells;
+    private cellSelStart;
+    private cellSelDrag;
+    private handleCellSelStart;
+    private handleCellSelMove;
+    private handleCellSelEnd;
+    /** `.aw-cell-selected` 마킹을 모두 제거. */
+    private clearCellSelection;
+    /**
+     * 표 셀 배열 각각에 `cell.style.fontSize` 를 직접 설정. Range API 의 wrap
+     * 경로(셀 중첩 버그 발생) 를 우회하기 위한 안전한 다중 셀 적용 경로.
+     */
+    private applyFontSizeToCells;
+    /**
+     * 캡처해 둔 셀(들) 에 배경색을 일괄 적용. null 이면 inline background-color
+     * 제거. `<th>` 의 stylesheet 배경(0,1,2 specificity) 보다 inline + !important
+     * 가 항상 우선하도록 setProperty('important') 로 박는다.
+     */
+    private applyCellBgToCells;
+    /** 표 편집 드롭다운에서 받은 액션을 분기 실행. */
+    private runTableMenu;
+    /** 활성 셀의 행 위/아래에 새 행 삽입. 같은 열 수, 빈 td 로 채움. */
+    private insertRow;
+    /** 활성 셀이 속한 열의 좌/우에 새 열 삽입. 모든 행에 빈 td 추가. */
+    private insertColumn;
+    /** 활성 셀의 행 전체 삭제. 마지막 행이면 보존(빈 표 회피). */
+    private deleteRow;
+    /**
+     * 코드 블록 input 마다 호출되는 debounced rehighlight. 활성 블록이 codeBlock
+     * 이고 data-language 가 설정돼 있을 때만 동작 — 타이핑 멈춘 뒤 300ms 후 1 회.
+     */
+    private codeHighlightTimer;
+    private scheduleCodeHighlight;
+    /**
+     * code 블록의 언어를 변경하고 즉시 highlight 를 다시 적용. 캐럿 위치는
+     * 텍스트 offset 으로 보존.
+     */
+    private applyCodeLanguage;
+    /**
+     * `<code>` element 의 텍스트를 highlight 후 innerHTML 로 갱신. 셀렉션이
+     * code 안에 있다면 textContent offset 으로 caret 위치 보존.
+     */
+    private rehighlightCode;
+    /**
+     * 본문에서 모든 codeBlock 을 순회하며 highlight 적용. setHTML / 초기 로드
+     * / 외부 import 후 호출.
+     */
+    private rehighlightAllCodeBlocks;
+    /** 활성 셀의 열 전체 삭제. 마지막 열이면 보존(빈 표 회피). */
+    private deleteColumn;
+    /**
+     * 마우스 이동 시 셀 우/하 가장자리에서 col-resize / row-resize 커서 표시.
+     * 드래그 진행 중에는 별도 핸들러가 cursor 를 관리하므로 skip.
+     */
+    private handleTableCursor;
+    private tableResize;
+    /**
+     * 셀 가장자리 / 이미지·유튜브 리사이즈 핸들 mousedown 진입점.
+     * - 셀: 우(col-resize) / 하(row-resize) 가장자리 6px 영역
+     * - 이미지·유튜브: 우하단 `.aw-resize-handle` element (corner resize)
+     */
+    private handleTableResizeStart;
+    private handleTableResizeMove;
+    /**
+     * 이미지/유튜브 좌상단 정렬 컨트롤 클릭 핸들러. data-align 에 따라 wrapper
+     * 의 marginLeft / marginRight 를 조정 — left/center/right.
+     */
+    private handleBlockAlignClick;
+    /**
+     * 이미지 / 유튜브 wrapper 의 너비를 드래그로 조정. 높이는 자동 (이미지는
+     * 종횡비 유지, 유튜브는 CSS aspect-ratio 16/9). mouseup 에서 cursor 복귀
+     * + flush.
+     *
+     * 너비는 본문 안쪽 폭을 상한으로 한다. 상한이 없으면 오른쪽으로 계속 끌 때
+     * wrapper 가 본문보다 넓어지고, 그만큼 에디터 전체가 가로로 늘어난다
+     * (드래그를 멈춰도 늘어난 상태가 남는다).
+     */
+    private startBlockResize;
+    /**
+     * 본문의 padding 을 제외한 실제 컨텐츠 폭. 블록 리사이즈의 상한이다.
+     * 에디터가 아주 좁을 때도 최소 폭은 확보되도록 하한을 둔다.
+     */
+    private contentInnerWidth;
+    private currentTheme;
+    /**
+     * 선택 영역에 글꼴을 적용한다.
+     * `styleWithCSS=true` 모드의 execCommand('fontName') 가 `<font face=…>` 대신
+     * `<span style="font-family: …">` 를 생성하도록 강제한다. selection 이
+     * 비어 있으면(캐럿만) 다음 입력 글꼴이 결정된다(브라우저 기본 동작).
+     */
+    private applyFontFamily;
+    /**
+     * 현재 selection 의 anchor 노드 기준 computed font-family 를 읽어 알려진
+     * FONT_FAMILIES id 와 매칭. 글꼴 드롭다운의 active 표시에 사용.
+     */
+    private detectActiveFontId;
+    /**
+     * 선택 영역에 글자 크기를 적용한다. execCommand('fontSize') 는 1~7 만 받기
+     * 때문에 px 적용을 위해 Range API 로 직접 `<span style="font-size: Xpx">`
+     * wrap 한다.
+     *
+     * **다중 셀 선택**(커스텀 마킹 또는 셀 경계를 넘는 browser range) 의 경우엔
+     * Range.extractContents 가 셀들을 묶어 한 셀 안에 끼워넣는 셀 중첩 버그가
+     * 있어 — 셀별로 `cell.style.fontSize` 를 직접 설정하는 안전한 경로를 사용.
+     */
+    private applyFontSize;
+    /**
+     * 현재 selection 의 anchor 노드 기준 computed font-size 를 px 정수로 읽어
+     * FONT_SIZES 의 값과 일치할 때만 반환. 글자 크기 드롭다운의 active 표시에
+     * 사용.
+     */
+    private detectActiveFontSize;
+    /**
+     * 블록 유형 드롭다운을 열어 사용자 선택 결과를 처리한다.
+     * 툴바의 blockType 버튼 / 활성 블록 라벨 pill 양쪽 진입점이 동일한 분기
+     * 로직(리치 블록 다이얼로그 분기 + targetId 보존) 을 공유한다.
+     */
+    private openBlockTypeMenu;
+    /**
+     * 링크 다이얼로그를 열어 URL/텍스트를 받은 뒤 linkCard 블록으로 변환/추가.
+     * 표시 텍스트가 비어 있으면 URL 을 텍스트로 사용. `targetId` 가 있으면
+     * 그 id 의 블록을 정확히 변환 대상으로 삼는다.
+     */
+    private openLinkDialogAndApply;
+    /**
+     * 이미지 다이얼로그(임베드/URL/업로드)를 열어 src 를 받은 뒤 image 블록으로
+     * 변환/추가.
+     */
+    private openImageDialogAndApply;
+    /**
+     * 유튜브 다이얼로그를 열어 URL 을 받고, 영상 ID 를 추출해 youtube 블록으로
+     * 변환/추가. 잘못된 URL 이면 무시.
+     */
+    private openYouTubeDialogAndApply;
+    /**
+     * HTML 가져오기 다이얼로그를 열어 사용자가 고른 HTML 을 iframe 으로 로드/
+     * 처리한 뒤 본문에 element 들을 삽입한다.
+     *
+     * - `targetId` 가 있으면 그 블록 바로 뒤에 삽입, 없으면 본문 끝에 append.
+     * - 삽입된 element 는 MutationObserver flush 가 새 data-block-id 를 발급.
+     */
+    private openImportHtmlDialogAndApply;
+    /**
+     * Markdown 가져오기 다이얼로그를 열어 사용자가 입력한 markdown 을 파싱해
+     * 본문에 element 들을 삽입한다. importHtml 과 동일한 삽입 정책을 따른다.
+     */
+    private openMarkdownImportDialogAndApply;
+    /**
+     * 파일 첨부 다이얼로그(URL/업로드)를 열어 src 를 받은 뒤 file 블록으로
+     * 변환/추가. src 가 비어 있으면 무시. 파일명이 없으면 URL 의 마지막
+     * segment 를 fallback 으로 사용.
+     */
+    private openFileAttachmentDialogAndApply;
+    /**
+     * 파일 업로드 핸들러를 결정. onFileUpload 가 우선, 없으면 fileUploadUrl 에
+     * multipart/form-data POST 후 응답 JSON 의 `url` 필드를 사용. 둘 다 없으면
+     * undefined → 다이얼로그 업로드 탭 비활성.
+     */
+    private resolveFileUploadFn;
+    /**
+     * 이미지 업로드 핸들러를 결정. options.onImageUpload 가 우선이며, 없으면
+     * options.imageUploadUrl 로 multipart/form-data POST 후 응답 JSON 의
+     * `url` 필드를 사용. 둘 다 없으면 undefined → 다이얼로그 업로드 탭 비활성.
+     */
+    private resolveImageUploadFn;
+    /**
+     * `src` 의 이미지를 figure>img 블록으로 본문에 삽입.
+     * 활성 블록이 있으면 그 블록을 image 로 변환, 없으면 본문 끝에 추가.
+     */
+    private insertImageBlock;
+    private queueSync;
+    private sync;
+    private handleKeyDown;
+    /**
+     * 활성 블록 뒤에 새 빈 단락을 만들고 캐럿을 그 안에 둔다.
+     * 인용구 / 코드 블록의 Enter 탈출 동작에 사용.
+     */
+    private exitBlockOnEnter;
+    private syncBlockHandles;
+    private repositionHandles;
+    private positionHandle;
+    private createBlockHandle;
+    /**
+     * `blockId` 의 블록 뒤에 빈 단락을 삽입하고 캐럿을 그 단락으로 이동.
+     * MutationObserver flush 가 새 단락에 신규 data-block-id 를 발급한다.
+     */
+    private insertParagraphAfter;
+    private handleDragOver;
+    private handleDrop;
+    private handleDragLeave;
+    private findDropTarget;
+    private showDropIndicator;
+    private hideDropIndicator;
+    /**
+     * 본문 블록들에 data-block-kind / data-block-label 을 갱신하고,
+     * 활성 블록에 data-block-focused 를 표기한다. CSS 가 이 속성을 읽어
+     * 포커스 인디케이터와 라벨 태그를 그린다.
+     *
+     * 자기 쓰기로 발생한 attributes 레코드는 takeRecords 로 흡수.
+     */
+    /**
+     * 활성 블록 위쪽에 떠 있는 인터랙티브 라벨 pill 갱신.
+     * - 활성 블록이 없으면 숨김
+     * - 활성 블록의 라벨 텍스트로 갱신, 위치를 블록 상단에 맞춤
+     * - 클릭 시 openBlockTypeDropdown 가 열려 블록 유형을 즉시 변경 가능
+     */
+    private syncBlockLabelPill;
+    /**
+     * 하단 Status Bar 갱신.
+     * - 좌측: 활성 블록 라벨 + id (없으면 — )
+     * - 우측: 총 블록 수, 본문 글자 수(공백 제외)
+     */
+    private syncStatusBar;
+    private syncBlockMarkers;
+    private applyToolbarState;
+}
+// (소스맵은 CJS 선언 사본에서 제외됨 — scripts/finalize-types.mjs)

package/dist-types/cjs/core/AerizViewer.d.cts

@@ -0,0 +1,61 @@
+import type { HtmlStyleMode, SerializeHtmlOptions } from '../types/index.cjs';
+import type { Block, BlockSnapshot } from './blocks.cjs';
+export interface ViewerOptions {
+    /** 마운트할 호스트 element */
+    element: HTMLElement;
+    /** 초기 블록 상태 (1차 입력 경로). HTML 이 아닌 상태 모델을 사용. */
+    initialBlocks?: BlockSnapshot[];
+    /** 초기 테마 */
+    theme?: 'light' | 'dark';
+    /** `getHTML()` 의 스타일 전략. 기본 `'inline'`. */
+    htmlStyles?: HtmlStyleMode;
+}
+/**
+ * 편집 불가 모드의 읽기 전용 뷰어.
+ *
+ * 입력은 HTML 문자열이 아닌 BlockSnapshot 배열(상태 모델)이다.
+ * 각 snapshot 은 BlockType 레지스트리를 통해 새 element 로 렌더되며, 결과는
+ * AerizEditor 와 같은 `.aeriz-wysiwyg .aw-content` 트리에 들어가 동일한
+ * CSS 규칙(테마 변수 포함)이 그대로 적용된다.
+ *
+ * @example
+ *   const editor = new AerizEditor({ element: editorMount });
+ *   const viewer = new AerizViewer({ element: viewerMount });
+ *   editor.onStateChange(() => viewer.setBlocks(editor.serialize()));
+ */
+export declare class AerizViewer {
+    readonly root: HTMLDivElement;
+    readonly content: HTMLDivElement;
+    private readonly blockIds;
+    private readonly idFor;
+    /**
+     * 생성 시 받은 options 객체를 그대로 들고 있는다. `htmlStyles` 를 여기서
+     * 매번 다시 읽으므로, 호출자가 이 객체를 갱신하면 재생성 없이 출력 전략이
+     * 바뀐다 (AerizEditor 와 같은 규약).
+     */
+    private readonly options;
+    private destroyed;
+    constructor(options: ViewerOptions);
+    /**
+     * BlockSnapshot 배열로부터 본문을 다시 렌더한다.
+     * 동일한 BlockType 레지스트리로 element 를 만들어 채우므로 외부 HTML 파싱
+     * 경로를 거치지 않는다.
+     */
+    setBlocks(blocks: BlockSnapshot[]): void;
+    /** 현재 본문의 BlockSnapshot 배열을 반환한다. */
+    getBlocks(): BlockSnapshot[];
+    /** 임의의 노드를 받아 그 노드가 속한 블록을 반환한다. 본문 밖이면 null. */
+    getBlockOf(node: Node): Block | null;
+    /**
+     * 본문 HTML 을 반환한다. 전략은 `AerizEditor.getHTML()` 과 동일하다.
+     *
+     * - `'inline'` (기본) — 외부 컨텍스트(이메일, 다른 페이지의 HTML 영역 등)
+     *   에서도 동일한 시각으로 보이도록 portable 인라인 스타일을 베이크한다.
+     * - `'class'` — 클래스만 남긴다. `style` 속성을 지우는 sanitizer 대응.
+     */
+    getHTML(options?: SerializeHtmlOptions): string;
+    setTheme(theme: 'light' | 'dark'): void;
+    destroy(): void;
+    private listBlocksInternal;
+}
+// (소스맵은 CJS 선언 사본에서 제외됨 — scripts/finalize-types.mjs)

package/dist-types/cjs/core/block-meta.d.cts

@@ -0,0 +1,32 @@
+/**
+ * 블록 렌더링에 쓰이는 순수 헬퍼와 상수.
+ *
+ * DOM 을 참조하지 않는다. 브라우저 렌더 경로(`blocks.ts`) 와 DOM 없는 문자열
+ * 렌더 경로(`render-string.ts`) 가 **같은** 값을 쓰도록 여기 한 곳에 둔다.
+ * 두 경로가 갈라지면 서버 재렌더 결과와 에디터 출력이 미묘하게 달라지므로,
+ * 양쪽이 공유해야 하는 것은 반드시 이 모듈로 올린다.
+ */
+/** 바이트 수를 사람이 읽는 크기 문자열로. */
+export declare function formatBytes(bytes: number): string;
+/** 표시용 짧은 타입 라벨. 파일명 확장자 우선, 없으면 MIME subtype. */
+export declare function fileExtensionLabel(name?: string, mime?: string): string;
+/** URL 의 hostname (subdomain 포함) 만 추출. 실패 시 빈 문자열. */
+export declare function hostnameFromUrl(url: string): string;
+/**
+ * Google 의 무료 favicon 서비스 URL 을 반환. CORS / 인증 불필요. URL 파싱
+ * 실패 시 빈 문자열.
+ */
+export declare function defaultFaviconUrl(url: string): string;
+/** 파일 첨부 카드 좌측 문서 아이콘. */
+export declare const FILE_ICON_SVG: string;
+/** 파일 첨부 카드 우측 다운로드 아이콘. */
+export declare const FILE_ACTION_SVG: string;
+/** 유튜브 iframe 의 `allow` 목록. */
+export declare const YOUTUBE_IFRAME_ALLOW = "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture";
+/** 유튜브 임베드 base URL. 쿠키를 덜 쓰는 nocookie 도메인을 사용한다. */
+export declare const YOUTUBE_EMBED_BASE = "https://www.youtube-nocookie.com/embed/";
+/** 파일명이 없는 첨부의 기본 표시 이름. */
+export declare const FILE_FALLBACK_NAME = "\uD30C\uC77C";
+/** 블록의 안정 식별자를 담는 속성명. */
+export declare const BLOCK_ID_ATTR = "data-block-id";
+// (소스맵은 CJS 선언 사본에서 제외됨 — scripts/finalize-types.mjs)