@teriusu/rich-editor

TipTap v3 기반 리치 텍스트 에디터. Svelte 5 컴포넌트 라이브러리.

설치

npm install @teriusu/rich-editor

Tailwind CSS v4 사용 시 @source 추가:

@import "@teriusu/rich-editor/styles";
@source "../node_modules/@teriusu/rich-editor/dist";

기본 사용법

<script>
  import { TipTapEditor } from '@teriusu/rich-editor';
  import '@teriusu/rich-editor/styles';

  let html = $state('');
</script>

<TipTapEditor
  content={html}
  onChange={(h) => html = h}
  onUploadFile={async (file) => {
    const form = new FormData();
    form.append('file', file);
    const res = await fetch('/api/upload', { method: 'POST', body: form });
    const { url } = await res.json();
    return url;
  }}
/>

Props

Prop	타입	기본값	설명
content	string	""	HTML 콘텐츠
onChange	(html: string) => void	필수	콘텐츠 변경 콜백
placeholder	string	"'/'를 눌러..."	플레이스홀더
onUploadFile	(file: File) => Promise<string>	-	파일 업로드 핸들러 (URL 반환)
onResolveFile	(fileId: string) => Promise<{src, name?, size?}>	-	파일 ID → URL 변환
extensions	AnyExtension[]	[]	추가 TipTap 확장 주입
editable	boolean	true	읽기 전용 모드

파일 저장 방식

URL 직접 (기본)

onUploadFile만 제공하면 파일 URL이 HTML에 직접 저장됩니다.

<div data-file-src="/files/report.pdf" data-file-name="report.pdf" data-file-size="204800"></div>

ID 기반 (하이브리드)

onResolveFile을 추가하면 파일 ID + 캐시 URL이 함께 저장됩니다.

<TipTapEditor
  content={html}
  onChange={(h) => html = h}
  onUploadFile={async (file) => {
    const res = await fetch('/api/upload', { method: 'POST', body: file });
    return await res.json(); // { id, url, name, size }
  }}
  onResolveFile={async (fileId) => {
    const res = await fetch(`/api/files/${fileId}`);
    return await res.json(); // { src, name, size }
  }}
/>

<div data-file-id="abc123" data-file-src="/files/report.pdf" data-file-name="report.pdf"></div>

ID 기반은 URL이 변경되어도 대응 가능하고, 권한 제어(signed URL)에 활용할 수 있습니다.

기능

텍스트 서식

Bold, Italic, Underline, Strikethrough, Highlight, Superscript, Subscript, 텍스트 색상

구조

제목 (H1~H3), 글머리/번호 목록, 체크리스트, 인용문, 구분선, 접기/펼치기 (Details), 들여쓰기 (Tab/Shift-Tab)

미디어

이미지, PDF (PDF.js 캔버스 렌더링), 영상 파일 (mp4/webm), YouTube, 파일 첨부, 드래그 앤 드롭 업로드

레이아웃

2단/3단 컬럼, 텍스트 정렬 (좌/중/우)

테이블

삽입, 행/열 추가/삭제, 헤더 토글, 셀 병합/분할, 셀 배경색, 열 리사이즈

입력

/ 슬래시 커맨드, 고정 툴바, 테이블 버블 메뉴, Undo/Redo

레거시 HTML 호환

TipTap v2 커스텀 태그를 자동 변환합니다. 에디터 로드 시 transformLegacyHtml이 자동 호출됩니다.

레거시 태그	변환 결과
<tiptap-file id="X">	<div data-file-id="X">
<tiptap-midibus id="X">	iframe (play.mbus.tv)
<tiptap-collapsable title="X">	<details><summary>
<lite-youtube videoid="X">	YouTube iframe
<embed type="application/pdf">	<div data-pdf-src>
<div class="tiptap-columns">	<div data-type="columns">
margin-left: 40px	indent level 1 (em 출력)

게시물 조회 페이지(읽기 전용)에서도 적용:

import { transformLegacyHtml } from '@teriusu/rich-editor';

const html = transformLegacyHtml(post.content);

커스텀 확장 주입

extensions prop으로 호스트 앱 전용 확장을 주입할 수 있습니다.

<script>
  import { TipTapEditor } from '@teriusu/rich-editor';
  import { Node } from '@tiptap/core';

  const MyExtension = Node.create({ /* ... */ });
</script>

<TipTapEditor
  content={html}
  onChange={handleChange}
  extensions={[MyExtension]}
/>

Exports

컴포넌트

TipTapEditor, FixedToolbar, BubbleToolbar, SlashCommandMenu, TableBubbleMenu, InputModal, PdfViewer

확장

PdfBlock, FileAttachment, VideoBlock, Columns, Column, Indent, FixedDetails

유틸리티

transformLegacyHtml, sanitizeHtml, stripHtmlToExcerpt, configurePdfJs, getPdfJs, cn

타입

UploadHandler, FileResolver, FileResolveResult, TipTapEditorProps, SlashMenuItem

빌드 / 배포

npm run build          # svelte-package → dist/
npm test               # vitest

배포는 main 브랜치 push 시 GitHub Actions가 자동 수행 (.github/workflows/publish.yml). 수동 npm publish는 사용하지 않음.

버전 정책 (SemVer)

단계	조건	커밋 타입
patch (0.0.x)	버그 수정, 내부 리팩토링, 스타일 조정, 의존성 patch	fix:, chore:, refactor:, style:
minor (0.x.0)	하위 호환 기능 추가 (새 prop, 새 extension, 새 toolbar feature)	feat:
major (x.0.0)	깨는 변경 (prop 제거·rename, peer dep major bump, export 경로 변경)	feat!: / BREAKING CHANGE:

0.x대에서는 관행상 minor도 breaking일 수 있음. 호스트 앱은 ^0.5.3 대신 ~0.5.3 사용을 권장.

릴리스 플로우

1. patch만 필요한 변경: 소스 수정 후 main에 push → CI가 package.json의 버전이 이미 publish된 최신과 같으면 자동 patch bump 후 publish
2. minor / major 변경: push 전에 수동 bump

   npm version minor --no-git-tag-version   # 또는 major
   git add package.json package-lock.json
   git commit -m "chore: v$(node -p 'require(\"./package.json\").version')"
   git push

   CI가 "이미 bump됨"을 감지하고 그 버전으로 publish.

자동 전파

publish 성공 시 repository_dispatch (rich-editor-published) 이벤트가 다음 repo로 전송되고, 각 repo의 update-* 워크플로우가 package.json을 새 버전으로 업데이트 + 커밋:

• teriusu-ko/hancomac → @teriusu/rich-editor
• HancomAC/trinity → apps/jungol, apps/codepass의 @teriusu/rich-editor

teriusu-ko/teriusu는 현재 수동 업데이트 (hook 미설정 — GH_PAT secret 추가 시 연결 가능).

기술 스택

구분	기술
에디터 엔진	TipTap v3
UI	Svelte 5 (runes)
언어	TypeScript
빌드	svelte-package
아이콘	lucide-svelte
스타일	Tailwind CSS + CSS 변수