@aeriz/wysiwyg 1.0.2 → 1.0.3

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

@@ -0,0 +1,368 @@
+export type BlockKind = 'paragraph' | 'heading' | 'bulletList' | 'orderedList' | 'blockquote' | 'codeBlock' | 'image' | 'table' | 'hr' | 'linkCard' | 'youtube' | 'file' | 'importedHtml' | 'unknown';
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** 단락 — 메타데이터 없음. */
+export interface ParagraphAttrs {
+}
+/** 제목 — 1~6 의 level 만 가짐. */
+export interface HeadingAttrs {
+    level: HeadingLevel;
+}
+/** 글머리 목록(unordered) — kind 자체가 ordered=false 를 의미. 추가 메타 없음. */
+export interface BulletListAttrs {
+}
+/** 번호 목록(ordered) — kind 자체가 ordered=true 를 의미. 추가 메타 없음. */
+export interface OrderedListAttrs {
+}
+/** 인용구 — 메타데이터 없음. */
+export interface BlockquoteAttrs {
+}
+/** 코드 블록 — 언어 식별자(syntax highlight 에 사용). */
+export interface CodeBlockAttrs {
+    /** 'javascript' / 'python' 등의 언어 식별자. 없으면 plaintext. */
+    language?: string;
+}
+/** 이미지 블록(<figure><img>). */
+export interface ImageAttrs {
+    src?: string;
+    alt?: string;
+    /** wrapper(figure) 의 인라인 style — width / margin 등 outer 스타일 보존. */
+    wrapperStyle?: string;
+}
+/** 표 블록. 서버 저장 시 행/열 수만 기록 — 실제 cell 컨텐츠는 html 에 담김. */
+export interface TableAttrs {
+    rows: number;
+    cols: number;
+}
+/** 구분선 — 메타데이터 없음. */
+export interface HrAttrs {
+}
+/** 링크 카드 블록. */
+export interface LinkCardAttrs {
+    href?: string;
+    /** 제목 / 표시 텍스트. 없으면 href 의 호스트명 사용. */
+    text?: string;
+    /** 부제 / 설명 (Open Graph description 등). 없으면 표시 안 함. */
+    description?: string;
+    /** 미리보기 이미지 (og:image 등). data: URL 또는 https URL. */
+    image?: string;
+    /** 파비콘 URL — 미설정 시 href 의 도메인으로부터 자동 추론. */
+    favicon?: string;
+}
+/** 유튜브 임베드 블록. */
+export interface YoutubeAttrs {
+    /** YouTube 영상 ID (예: 'dQw4w9WgXcQ'). */
+    videoId?: string;
+    /** wrapper(div.aw-youtube-embed) 의 인라인 style — width / margin 등. */
+    wrapperStyle?: string;
+}
+/** 파일 첨부 블록. */
+export interface FileAttrs {
+    /** 다운로드 URL — 외부 URL 또는 업로드 API 응답. */
+    fileSrc?: string;
+    /** 표시 / download attribute 에 사용할 원본 파일명. */
+    fileName?: string;
+    /** 바이트 크기. */
+    fileSize?: number;
+    /** MIME 타입 — 파일명 확장자가 없을 때 메타로 사용. */
+    fileType?: string;
+}
+/** 외부 HTML 가져오기로 만들어진 wrapper 블록. */
+export interface ImportedHtmlAttrs {
+    /** body 의 computed style 이 베이크된 wrapper 의 인라인 style. */
+    importedStyle?: string;
+    /** body 에서 복사한 wrapper 의 class 문자열. */
+    importedClass?: string;
+}
+/** 어떤 BlockType 에도 매칭되지 않은 element. */
+export interface UnknownAttrs {
+}
+/** BlockKind → 해당 블록의 attrs 타입 매핑. discriminated union 의 기반. */
+export interface BlockAttrsByKind {
+    paragraph: ParagraphAttrs;
+    heading: HeadingAttrs;
+    bulletList: BulletListAttrs;
+    orderedList: OrderedListAttrs;
+    blockquote: BlockquoteAttrs;
+    codeBlock: CodeBlockAttrs;
+    image: ImageAttrs;
+    table: TableAttrs;
+    hr: HrAttrs;
+    linkCard: LinkCardAttrs;
+    youtube: YoutubeAttrs;
+    file: FileAttrs;
+    importedHtml: ImportedHtmlAttrs;
+    unknown: UnknownAttrs;
+}
+/**
+ * 모든 블록 종류의 attrs 를 합친 "느슨한" 인터페이스. 모든 필드가 optional
+ * 이라 BlockType.create 같이 kind 를 모르는 시점의 코드도 받을 수 있다.
+ * 외부에서 직렬화된 BlockSnapshot 의 attrs 는 BlockAttrsByKind[kind] 로 더
+ * 구체적으로 타입이 잡힌다 — 아래 BlockSnapshot 의 discriminated union 참고.
+ */
+export interface BlockAttrs extends Partial<HeadingAttrs>, Partial<BulletListAttrs>, Partial<OrderedListAttrs>, Partial<CodeBlockAttrs>, Partial<ImageAttrs>, Partial<TableAttrs>, Partial<LinkCardAttrs>, Partial<YoutubeAttrs>, Partial<FileAttrs>, Partial<ImportedHtmlAttrs> {
+}
+/**
+ * BlockType.matches() 의 반환 타입. 내부 사용은 느슨한 BlockAttrs 로 두고,
+ * 외부에서 narrow 하고 싶으면 `MatchOf<'image'>` 같은 별칭 사용.
+ */
+export interface BlockMatch {
+    kind: BlockKind;
+    attrs: BlockAttrs;
+}
+/** 본문에서 발견된 블록의 런타임 표현. element 참조를 포함. */
+export interface Block {
+    id: string;
+    kind: BlockKind;
+    attrs: BlockAttrs;
+    element: HTMLElement;
+}
+/** 인라인 서식 마크 식별자. */
+export type InlineMarkName = 'bold' | 'italic' | 'underline' | 'strike';
+export declare const ALL_INLINE_MARKS: ReadonlyArray<InlineMarkName>;
+/**
+ * 블록 정의. 같은 kind 의 BlockType 은 1개만 등록한다.
+ */
+export interface BlockType {
+    readonly kind: BlockKind;
+    readonly label: string;
+    /** 인라인 서식(굵게/기울임/...)이 허용되는 블록인지. UI 활성/비활성 판단에 사용. */
+    readonly allowsInlineFormat: boolean;
+    /**
+     * 이 블록 안에서 허용되는 인라인 마크의 화이트리스트.
+     * - 빈 배열 = 어떤 인라인 마크도 적용 불가 (codeBlock / image / hr)
+     * - allowsInlineFormat=false 인 블록은 [] 가 기본
+     */
+    readonly allowedMarks: ReadonlyArray<InlineMarkName>;
+    /** 글자색 / 배경색 적용을 허용하는지. heading / blockquote 는 톤 보존을
+     *  위해 false. allowsInlineFormat=false 면 의미 없음 — false 로 둘 것. */
+    readonly allowsColor: boolean;
+    /** 글자 크기 적용을 허용하는지. heading 은 level 로 결정되므로 false.
+     *  allowsInlineFormat=false 면 의미 없음 — false 로 둘 것. */
+    readonly allowsFontSize: boolean;
+    /** 본문 직계 자식 element 가 이 type 인지 판별한다. */
+    matches(el: HTMLElement): BlockMatch | null;
+    /** 빈 인스턴스 element 를 새로 생성한다. */
+    create(attrs?: BlockAttrs): HTMLElement;
+    /** "비어 있는" 상태인지. 백스페이스 / 포커스 / placeholder 처리에 사용. */
+    isEmpty(el: HTMLElement): boolean;
+}
+/**
+ * 본문 직계 자식 element 를 분류할 때 시도되는 순서.
+ * 위에서부터 첫 번째로 매칭되는 BlockType 이 채택된다.
+ */
+export declare const BLOCK_TYPES: ReadonlyArray<BlockType>;
+export declare const BLOCK_TYPE_BY_KIND: Readonly<Record<BlockKind, BlockType>>;
+export interface ClassifyResult {
+    type: BlockType;
+    match: BlockMatch;
+}
+/**
+ * 본문 직계 자식 element 를 BLOCK_TYPES 와 순차 매칭해 분류한다.
+ * 어디에도 일치하지 않으면 unknown 으로 본다.
+ */
+export declare function classifyBlockElement(el: HTMLElement): ClassifyResult;
+export { BLOCK_ID_ATTR } from './block-meta.cjs';
+export declare class BlockIdRegistry {
+    private counter;
+    private readonly seen;
+    /** 외부에서 관측된 id (HTML 에 이미 있던 값 등) 를 이후 발급 시 회피하도록 등록. */
+    observe(id: string): void;
+    /** seen 과 충돌하지 않는 새 id 를 발급해 반환. */
+    generate(): string;
+    /**
+     * 단일 element 발급기. data-block-id 가 있으면 등록 후 그대로 반환,
+     * 없으면 신규 발급 후 element 에 기록한다. 같은 id 의 중복 element 처리는
+     * 이 함수 단독으로는 못 하므로, 본문 전체 정규화는 {@link assignMissingIds}
+     * 를 사용해야 한다.
+     */
+    ensure(el: HTMLElement): string;
+    get(el: HTMLElement): string | null;
+}
+/**
+ * `root` 의 직계 자식 element 들에 고유한 data-block-id 를 보장한다.
+ *
+ * - id 가 없는 자식 → 신규 발급
+ * - 같은 root 안에서 같은 id 가 두 번 이상 나타나면(예: Enter 키로 단락이
+ *   분할되며 브라우저가 attribute 를 클론한 경우) 첫 번째 element 만 기존
+ *   id 를 유지하고, 그 이후에 등장한 element 는 새 id 로 재발급한다.
+ *
+ * 호출 후 모든 직계 자식이 root 안에서 unique 한 id 를 갖는다.
+ */
+export declare function assignMissingIds(root: HTMLElement, ids: BlockIdRegistry): void;
+/**
+ * `root` 의 직계 자식 중 어떤 블록 element 에도 속하지 않은 텍스트 노드를
+ * paragraph 블록으로 감싼다. 비어 있는(공백뿐) 텍스트 노드는 제거한다.
+ *
+ * contentEditable 동작 중 li 분리 / 백스페이스 처리 등으로 본문 직계에
+ * "homeless" 텍스트가 생길 수 있는데, 이를 정규화하여 모든 본문 자식이
+ * 항상 유효한 블록 element 가 되도록 보장한다.
+ */
+export declare function normalizeContent(root: HTMLElement): void;
+/**
+ * 사람이 읽을 수 있는 한국어 라벨. 포커스된 블록 위 태그 표시 등에 사용.
+ */
+export declare function getBlockLabel(match: BlockMatch): string;
+export type BlockIdResolver = (el: HTMLElement) => string;
+/**
+ * 직렬화된 Block 상태. Live element 참조 없이 JSON 으로 저장/전송 가능하다.
+ *
+ * - version : 스키마 버전. 직렬화 시 항상 {@link SNAPSHOT_VERSION} 이 기록된다.
+ *             optional 인 이유는 버전 필드 도입(1.0.3) 이전에 저장된 데이터를
+ *             그대로 읽을 수 있어야 하기 때문 — 없으면 1 로 간주한다.
+ *             변경 정책은 `src/core/snapshot.ts` 의 SNAPSHOT_VERSION 문서 참고.
+ * - id      : 원본 Block 의 안정 식별자
+ * - kind    : 블록 유형 (BlockKind 의 string literal)
+ * - attrs   : kind 에 대응하는 유형별 메타데이터 (BlockAttrsByKind[kind])
+ * - html    : 블록 element 내부 HTML (인라인 컨텐츠 전체 직렬화)
+ * - style   : 블록 element **자신**의 인라인 style. `html` 은 내부만 담으므로
+ *             정렬(text-align) 처럼 블록에 직접 걸리는 서식은 이 필드가 없으면
+ *             스냅샷 왕복에서 사라진다.
+ *
+ * 서버 라운드트립을 위한 핵심 직렬화 형태. discriminated union 이라
+ * `if (snap.kind === 'heading')` 후 `snap.attrs.level` 처럼 바로 narrow 가능.
+ */
+export type BlockSnapshot = {
+    [K in BlockKind]: {
+        version?: number;
+        id: string;
+        kind: K;
+        attrs: BlockAttrsByKind[K];
+        html: string;
+        style?: string;
+    };
+}[BlockKind];
+/** 특정 BlockKind 에 한정된 BlockSnapshot 의 별칭. 외부에서 narrow 한
+ *  타입을 명시할 때 유용 (예: `Snapshot<'image'>`). */
+export type Snapshot<K extends BlockKind> = Extract<BlockSnapshot, {
+    kind: K;
+}>;
+/** 단일 Block 을 직렬화 가능한 BlockSnapshot 으로 변환. */
+export declare function serializeBlock(block: Block): BlockSnapshot;
+/** Block 배열을 BlockSnapshot 배열로 직렬화. */
+export declare function serializeBlocks(blocks: Block[]): BlockSnapshot[];
+/**
+ * BlockSnapshot 을 새 element 로 렌더한다.
+ * BlockType.create(attrs) 로 골격을 만든 뒤 snapshot.html 로 인라인 컨텐츠를 채운다.
+ * 결과 element 는 data-block-id 가 snapshot.id 로 세팅되어 있다.
+ */
+export declare function renderBlock(snapshot: BlockSnapshot): HTMLElement;
+/**
+ * BlockSnapshot 배열을 root 의 자식으로 렌더 (root 의 기존 자식은 모두 제거).
+ *
+ * 저장소에서 바로 읽은 데이터가 들어올 수 있으므로 {@link upgradeSnapshots} 로
+ * 스키마를 정규화한 뒤 렌더한다.
+ */
+export declare function renderBlocks(root: HTMLElement, snapshots: readonly BlockSnapshot[]): void;
+/**
+ * 본문(`root`) 의 직계 자식 element 들을 순서대로 Block 리스트로 반환한다.
+ */
+export declare function listBlocks(root: HTMLElement, idFor: BlockIdResolver): Block[];
+/**
+ * 임의의 노드를 받아 본문(`root`) 직계 자식 element 까지 거슬러 올라간 뒤
+ * 해당 element 를 Block 으로 분류해 반환한다. 본문 밖이면 null.
+ */
+export declare function findBlockFrom(node: Node, root: HTMLElement, idFor: BlockIdResolver): Block | null;
+/**
+ * 블록의 인라인 컨텐츠(텍스트와 인라인 element 들)를 추출해 반환한다.
+ * 블록 유형 변경 시 기존 컨텐츠를 새 블록으로 옮길 때 사용.
+ *
+ * - paragraph / heading      : 직계 자식 노드 전체
+ * - bulletList / orderedList : 첫 li 의 자식 노드들
+ * - blockquote               : 첫 p 의 자식 노드들 (없으면 자기 자식)
+ * - codeBlock                : 첫 code 의 자식 노드들 (없으면 자기 자식)
+ * - image / table / hr / unknown : []
+ */
+export declare function extractInlineContent(block: Block): Node[];
+/**
+ * 새로 생성한 블록 element 의 인라인 컨테이너에 노드를 채워 넣는다.
+ * 컨텐츠가 비어있으면 기본 placeholder(br)를 그대로 둔다.
+ *
+ * 새 블록의 `allowedMarks` 에 없는 인라인 마크(bold/italic/underline/strike)
+ * 와 — `allowsInlineFormat=false` 인 블록(예: codeBlock)에서는 font/색상까지 —
+ * 제거해 "허용된 서식만 유지" 되도록 한다.
+ */
+export declare function fillInlineContent(newEl: HTMLElement, kind: BlockKind, content: Node[]): void;
+/**
+ * `getHTML()` 호출 시점에 에디터의 현재 테마(Css 변수)를 읽어 인라인 스타일에
+ * 그대로 베이크하기 위한 색 팔레트.
+ *
+ * 누락된 값은 안전한 기본값(에디터 다크 테마와 동일한 cyan 계열) 으로 폴백한다.
+ */
+export interface BlockStyleTheme {
+    primary?: string;
+    fg?: string;
+    bg?: string;
+    border?: string;
+    fgMuted?: string;
+    /** 'light' / 'dark'. 명시 시 syntax highlight token 색을 그 모드 팔레트로
+     *  베이크. 미지정 시 fg/bg lightness 로 자동 추정. */
+    mode?: 'light' | 'dark';
+}
+/**
+ * `getComputedStyle(host)` 에서 에디터 테마 변수(--aw-primary 등) 를 읽어
+ * BlockStyleTheme 객체로 반환한다. host 가 DOM 에 붙어 있어야 의미 있는 값.
+ */
+export declare function readBlockStyleTheme(host: Element): BlockStyleTheme;
+/**
+ * `root` 트리에 인라인 스타일을 입힌다. (clone 트리에 사용)
+ *
+ * - 에디터의 현재 테마 색을 `theme` 으로 받아 baked 인라인으로 출력 → 에디터에서
+ *   보이는 그대로 외부 컨텍스트에서도 동일하게 보인다.
+ * - theme 미지정 시 cyan 계열 기본값으로 폴백.
+ */
+export declare function applyBlockInlineStyles(root: HTMLElement, theme?: BlockStyleTheme): void;
+/** 정렬 값 → 클래스명. `styles: 'class'` 출력에서 text-align 을 대체한다. */
+export declare const ALIGN_CLASS_BY_VALUE: Readonly<Record<string, string>>;
+/**
+ * 클래스 기반 출력용 정규화. (`getHTML({ styles: 'class' })` 에서 사용)
+ *
+ * `style` 속성을 지우는 서버 sanitizer 아래에서도 서식이 살아남게 하는 것이
+ * 목적이다. 두 가지를 한다.
+ *
+ * 1. 본문 직계 블록에 `aw-block` + `aw-block-{kind}` 클래스를 붙인다 — 배포된
+ *    `aeriz-wysiwyg.min.css` 없이 자체 스타일을 입히려는 소비자의 훅.
+ * 2. `text-align` 인라인 선언을 `aw-align-*` 클래스로 옮긴다. 정렬은 값의
+ *    가짓수가 네 개로 한정돼 클래스로 완전히 표현되는 유일한 서식이다.
+ *
+ * 색 · 글자 크기 · 글꼴 · 표 셀 배경은 임의의 값을 갖기 때문에 클래스로 옮길 수
+ * 없고 `style` 속성에 남는다. sanitizer 는 `style` 을 통째로 지우는 대신
+ * 프로퍼티 단위 허용목록을 쓰면 된다 — 실제로 나오는 프로퍼티 목록은
+ * SPEC.md 의 "출력 HTML 허용목록" 절에 확정 명세로 정리돼 있다.
+ */
+export declare function applyBlockClassNames(root: HTMLElement): void;
+/**
+ * `aw-align-*` 클래스를 인라인 `text-align` 으로 되돌린다.
+ *
+ * 정렬의 **내부 표현은 언제나 인라인 style** 이고 클래스는 출력 인코딩일
+ * 뿐이라는 불변식을 유지한다. 이 되돌리기가 없으면 class 모드로 저장한 문서를
+ * 다시 불러왔을 때
+ * - 툴바가 현재 정렬을 알아보지 못하고,
+ * - 기본 inline 전략으로 내보낼 때 정렬이 통째로 사라진다
+ *   (applyBlockInlineStyles 는 클래스를 모른다).
+ *
+ * 이미 인라인 값이 있으면 그쪽을 우선한다 — 더 구체적인 지정이다.
+ */
+export declare function restoreAlignFromClasses(root: HTMLElement): void;
+/**
+ * `getHTML()` 출력에서 편집 보조 element / 속성을 제거한다.
+ *
+ * 이미지·유튜브 블록의 리사이즈 핸들과 정렬 컨트롤은 에디터 안에서만 의미가
+ * 있는 UI 이고, `contenteditable` 도 발행된 문서에서는 불필요하다. 둘 다
+ * `normalizeContent()` 가 다시 만들어 주므로 `setHTML(getHTML())` 라운드트립은
+ * 그대로 성립한다.
+ */
+export declare function stripEditorOnlyNodes(root: HTMLElement): void;
+/**
+ * `getHTML()` 출력에서 에디터 전용 메타데이터 속성을 제거한다.
+ * data-block-id 만 보존(외부 반입 시 동일 id 유지에 유용).
+ */
+export declare function stripEditorOnlyAttrs(root: HTMLElement): void;
+/**
+ * `el` 시작 위치에 캐럿을 둔다. 컨테이너 블록(UL/OL/BLOCKQUOTE/PRE/TABLE)의
+ * 경우 안쪽의 텍스트 컨테이너(li/p/code/td)까지 파고 들어가, 다음 키 입력이
+ * 컨테이너 자체가 아닌 안쪽에서 일어나도록 한다. hr 은 컨텐츠가 없으므로 그
+ * 뒤에 둔다.
+ */
+export declare function placeCaretAtStart(el: HTMLElement): void;
+export declare function isElementBlank(el: HTMLElement): boolean;
+// (소스맵은 CJS 선언 사본에서 제외됨 — scripts/finalize-types.mjs)

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

@@ -0,0 +1,60 @@
+/**
+ * 글꼴 라이브러리 — 한국어 본문에 친화적인 무료 / 상용 가능 글꼴만 큐레이션.
+ * 모두 SIL Open Font License 또는 자체 무제한 상용 라이선스.
+ *
+ * 로딩 정책:
+ *  - 모든 글꼴은 글꼴 드롭다운이 처음 열릴 때 1회 일괄 lazy 로드.
+ *  - Google Fonts CSS2 endpoint 한 번 + 외부 CDN(Pretendard) 별도 1 회.
+ *  - 실패해도 stack 의 fallback 글꼴이 자동 적용되므로 graceful degradation.
+ */
+export interface FontFamily {
+    /** 안정 식별자 — 직렬화 / 다음 선택 비교에 사용. */
+    id: string;
+    /** 드롭다운에 표시되는 한국어 라벨. */
+    label: string;
+    /** CSS font-family 스택 — execCommand fontName 의 인자로 들어간다. */
+    stack: string;
+    /** Google Fonts CSS2 family 파라미터 (예: "Noto+Sans+KR:wght@400;700"). */
+    googleFonts?: string;
+    /** 외부 CDN 의 전체 CSS URL (Google Fonts 가 아닌 글꼴용). */
+    cssUrl?: string;
+}
+/** "시스템 기본" 항목의 id. clearFormat / 초기화 분기에 사용. */
+export declare const SYSTEM_FONT_ID = "system";
+export declare const FONT_FAMILIES: ReadonlyArray<FontFamily>;
+/** id → FontFamily lookup. */
+export declare const FONT_FAMILY_BY_ID: Readonly<Record<string, FontFamily>>;
+/**
+ * 글자 크기 프리셋 (px). 본문 기본은 16px.
+ * 12 ~ 48px 범위에서 자주 쓰이는 단계만 큐레이션.
+ */
+export declare const FONT_SIZES: ReadonlyArray<number>;
+/**
+ * Computed CSS font-size 문자열(예: "16px", "1.125rem")을 px 정수로 변환.
+ * 매칭 실패 시 null. 활성 toolbar 크기 표시에 사용.
+ */
+export declare function pxFromCss(css: string | null | undefined): number | null;
+/**
+ * 현재 실제로 쓸 수 있는 글꼴만 반환한다. 드롭다운은 이 목록으로 그린다.
+ *
+ * `FONT_FAMILIES` 전체는 그대로 남겨 둔다 — 이미 그 글꼴로 저장된 본문의
+ * 라벨을 표시하려면(`findFontIdFromCss`) 실패한 항목도 알고 있어야 한다.
+ */
+export declare function getAvailableFontFamilies(): ReadonlyArray<FontFamily>;
+/** 사용 가능 목록이 바뀌면 호출된다. 반환값을 부르면 구독이 해제된다. */
+export declare function subscribeFontAvailability(listener: () => void): () => void;
+/**
+ * 모든 글꼴의 CSS 를 1 회만 lazy 로드한다. 글꼴 드롭다운이 열릴 때 호출.
+ * 두 번째 이후 호출은 즉시 반환.
+ *
+ * 실패는 조용히 넘어가지 않는다 — 받지 못한 글꼴은 목록에서 빠진다.
+ */
+export declare function ensureFontFamiliesLoaded(): void;
+/**
+ * 임의의 CSS font-family 문자열에 대해 FONT_FAMILIES 중 가장 비슷한 항목을
+ * 찾아 id 를 반환. 매칭 실패 시 null. 활성 toolbar 표시에 사용.
+ *
+ * 비교는 stack 의 첫 family 토큰을 추출해 case-insensitive 비교.
+ */
+export declare function findFontIdFromCss(css: string | null | undefined): string | null;
+// (소스맵은 CJS 선언 사본에서 제외됨 — scripts/finalize-types.mjs)

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

@@ -0,0 +1,44 @@
+/**
+ * 가벼운 자체 syntax highlighter — 외부 의존성 없음.
+ *
+ * 단일 generic tokenizer 가 LanguageDef 의 룰(keywords / comments / strings /
+ * builtins) 을 받아 동작. 결과는 `<span class="hl-…">` 으로 wrap 된 HTML
+ * 문자열로 반환되며, AerizEditor 가 codeBlock 의 innerHTML 로 적용한다.
+ *
+ * 지원 언어: 15 종 — JavaScript / TypeScript / Python / JSON / HTML / CSS /
+ * Bash / SQL / Markdown / C / C++ / C# / Java / Kotlin / Go / Rust.
+ *
+ * 정확도 목표: 일반적인 코드 80% 케이스. 100% 정확한 파서가 아니므로 corner
+ * case (예: regex 리터럴 vs 나누기 연산자, 템플릿 문자열의 ${…} 내부 표현식)
+ * 는 단순화되어 있다.
+ */
+export interface LanguageDef {
+    /** 안정 식별자 — `data-language` 속성에 저장되는 값. */
+    id: string;
+    /** UI 드롭다운에 표시되는 라벨. */
+    label: string;
+    /** 키워드 집합. 이 단어로 매칭되면 hl-keyword 로 wrap. */
+    keywords: ReadonlySet<string>;
+    /** 빌트인 / 라이브러리 함수. hl-builtin. */
+    builtins?: ReadonlySet<string>;
+    /** 라인 주석 prefix (예: '//'). */
+    lineComment?: string;
+    /** 블록 주석. */
+    blockComment?: {
+        start: string;
+        end: string;
+    };
+    /** 문자열 구분자 목록. 일반적으로 ['"', "'"], JS 는 백틱 추가. */
+    stringDelims?: ReadonlyArray<string>;
+    /** 키워드 매칭 시 case-insensitive (SQL 용). */
+    caseInsensitiveKeywords?: boolean;
+    /** HTML / CSS 등 특수 처리가 필요한 언어. 자체 토크나이저 사용. */
+    custom?: (code: string) => string;
+}
+export declare const LANGUAGES: ReadonlyArray<LanguageDef>;
+/**
+ * 코드 문자열을 언어 식별자에 따라 highlight HTML 로 변환.
+ * 알 수 없는 언어 또는 'plaintext' 면 escape 만 적용.
+ */
+export declare function highlightCode(code: string, langId: string | undefined): string;
+// (소스맵은 CJS 선언 사본에서 제외됨 — scripts/finalize-types.mjs)

package/dist-types/cjs/core/html-mini.d.cts

@@ -0,0 +1,65 @@
+/**
+ * DOM 없이 동작하는 최소 HTML 파서.
+ *
+ * `blocksToMarkdown` / `blocksToPlainText` 가 `snapshot.html` 의 인라인
+ * 컨텐츠를 해석하기 위해 쓴다. `document` 를 쓸 수 없는 런타임(workerd, Node,
+ * Deno) 에서 돌아야 하므로 브라우저 파서를 쓸 수 없다.
+ *
+ * 범위를 의도적으로 좁게 잡았다 — 에디터가 만든 인라인 마크업과, HTML 가져오기
+ * 로 들어온 정도의 일반적인 마크업을 다루는 것이 목표이며, 브라우저 HTML5
+ * 파싱 알고리즘의 완전한 재현은 목표가 아니다. 아래 두 가지만 보장한다.
+ *
+ * 1. 어떤 입력에도 예외를 던지지 않는다 (깨진 마크업은 최선 해석 후 통과).
+ * 2. `<script>` / `<style>` 의 내용은 결과 트리에 남기지 않는다.
+ */
+export interface HtmlText {
+    type: 'text';
+    value: string;
+}
+export interface HtmlElementNode {
+    type: 'element';
+    /** 소문자 태그명. */
+    tag: string;
+    /** 소문자 속성명 → 값. 엔티티가 해제된 상태. */
+    attrs: Readonly<Record<string, string>>;
+    children: HtmlNode[];
+}
+export type HtmlNode = HtmlText | HtmlElementNode;
+/** HTML 엔티티를 문자로 되돌린다. 해석할 수 없는 참조는 원문 유지. */
+export declare function decodeEntities(input: string): string;
+/** 텍스트를 HTML 본문에 넣을 수 있게 이스케이프한다. */
+export declare function escapeHtml(input: string): string;
+/** 텍스트를 큰따옴표 속성값으로 넣을 수 있게 이스케이프한다. */
+export declare function escapeAttr(input: string): string;
+/**
+ * HTML 조각을 노드 트리로 파싱한다.
+ *
+ * 텍스트 노드의 값은 엔티티가 해제된 상태로 들어온다.
+ */
+export declare function parseHtmlFragment(html: string): HtmlNode[];
+/** 노드 트리를 HTML 문자열로 되돌린다. 파싱 → 직렬화는 정규화 역할을 한다. */
+export declare function serializeNodes(nodes: readonly HtmlNode[]): string;
+/**
+ * 노드 트리의 텍스트만 이어붙인다. `<br>` 은 개행으로 바꾼다.
+ *
+ * 블록 경계는 무시한다 — 코드 블록처럼 원문 그대로가 필요한 곳에서 쓴다.
+ * 사람이 읽는 텍스트를 뽑을 때는 {@link textWithBlockBreaks} 를 쓸 것.
+ */
+export declare function textOf(nodes: readonly HtmlNode[]): string;
+/**
+ * 텍스트를 뽑되 블록 경계에 개행을 넣는다.
+ *
+ * `textOf` 만으로는 `<p>첫 문장</p><p>둘째 문장</p>` 이
+ * `"첫 문장둘째 문장"` 이 되어 버린다. 전문 검색 색인에 그대로 들어가면 두
+ * 단어가 한 토큰으로 붙어 어느 쪽으로도 검색되지 않고, 미리보기 스니펫도
+ * 문장이 뭉개진 채 나온다.
+ */
+export declare function textWithBlockBreaks(nodes: readonly HtmlNode[]): string;
+/** 트리에서 주어진 태그의 직계 자식들만 모은다. */
+export declare function childElements(nodes: readonly HtmlNode[], tag: string): HtmlElementNode[];
+/**
+ * 트리를 깊이 우선으로 훑어 주어진 태그의 첫 노드를 찾는다.
+ * 없으면 `null`.
+ */
+export declare function findElement(nodes: readonly HtmlNode[], tag: string): HtmlElementNode | null;
+// (소스맵은 CJS 선언 사본에서 제외됨 — scripts/finalize-types.mjs)