@teriusu/rich-editor 0.10.8 → 0.11.0

package/dist/components/FixedToolbar.svelte

@@ -41,6 +41,7 @@
   import ToggleHeadingIcon from "./icons/ToggleHeadingIcon.svelte";
   import InputModal from "./InputModal.svelte";
   import type { ToolbarFeature, PromptHandler } from "../types";
+  import { defaultTranslator, type EditorTranslator } from "../i18n";
 
   let {
     editor,
@@ -52,6 +53,7 @@
     onPromptMbus,
     onPromptVideo,
     toolbarEnd,
+    t = defaultTranslator,
   }: {
     editor: Editor;
     features: Set<ToolbarFeature>;
@@ -76,6 +78,8 @@
      * 여기에 넣으면 툴바의 flex 행에 그대로 얹혀 정렬이 저절로 맞는다.
      */
     toolbarEnd?: Snippet;
+    /** 에디터 UI 번역 함수. 미주입 시 ko. */
+    t?: EditorTranslator;
   } = $props();
 
   /*
@@ -171,21 +175,21 @@
   }
 
   const currentBlockLabel = $derived.by(() => {
-    if (isActive("heading", { level: 1 })) return "제목 1";
-    if (isActive("heading", { level: 2 })) return "제목 2";
-    if (isActive("heading", { level: 3 })) return "제목 3";
-    if (isActive("bulletList")) return "글머리 목록";
-    if (isActive("orderedList")) return "번호 목록";
-    if (isActive("taskList")) return "체크리스트";
-    if (isActive("blockquote")) return "인용문";
+    if (isActive("heading", { level: 1 })) return t("heading1");
+    if (isActive("heading", { level: 2 })) return t("heading2");
+    if (isActive("heading", { level: 3 })) return t("heading3");
+    if (isActive("bulletList")) return t("bulletList");
+    if (isActive("orderedList")) return t("orderedList");
+    if (isActive("taskList")) return t("taskList");
+    if (isActive("blockquote")) return t("blockquote");
     if (isActive("details")) {
       // 토글 제목이면 단계까지 보여 준다 — 그냥 "토글" 이면 무엇을 고른 건지 안 보인다.
       for (const lv of [1, 2, 3]) {
-        if (isActive("detailsSummary", { level: lv })) return `토글 제목 ${lv}`;
+        if (isActive("detailsSummary", { level: lv })) return t("toggleHeading", { level: lv });
       }
-      return "토글";
+      return t("toggle");
     }
-    return "본문";
+    return t("paragraph");
   });
 
   function runBlock(fn: () => void) {
@@ -238,7 +242,7 @@
       type="button"
       onclick={() => editor.chain().focus().undo().run()}
       disabled={!canDo((c) => c.undo())}
-      aria-label="실행 취소"
+      aria-label={t('undo')}
       class={cn(
         "p-1.5 rounded-md transition-colors text-muted-foreground hover:bg-muted hover:text-foreground",
         !canDo((c) => c.undo()) && "opacity-30 pointer-events-none",
@@ -252,7 +256,7 @@
       type="button"
       onclick={() => editor.chain().focus().redo().run()}
       disabled={!canDo((c) => c.redo())}
-      aria-label="다시 실행"
+      aria-label={t('redo')}
       class={cn(
         "p-1.5 rounded-md transition-colors text-muted-foreground hover:bg-muted hover:text-foreground",
         !canDo((c) => c.redo()) && "opacity-30 pointer-events-none",
@@ -271,7 +275,7 @@
       <button
         type="button"
         onclick={() => (blockMenuOpen = !blockMenuOpen)}
-        aria-label="블록 타입"
+        aria-label={t('blockType')}
         class="flex items-center gap-1 px-2 py-1.5 rounded-md transition-colors text-muted-foreground hover:bg-muted hover:text-foreground min-w-[96px]"
       >
         <span class="text-sm">{currentBlockLabel}</span>
@@ -301,7 +305,7 @@
             onclick={() =>
               runBlock(() => editor.chain().focus().setParagraph().run())}
           >
-            <Pilcrow size={14} /> 본문
+            <Pilcrow size={14} /> {t('paragraph')}
           </button>
           {#if has('h1')}
           <button
@@ -315,7 +319,7 @@
                 editor.chain().focus().toggleHeading({ level: 1 }).run(),
               )}
           >
-            <Heading1 size={14} /> 제목 1
+            <Heading1 size={14} /> {t('heading1')}
             <span class="hce-menu-shortcut"># </span>
           </button>
           {/if}
@@ -331,7 +335,7 @@
                 editor.chain().focus().toggleHeading({ level: 2 }).run(),
               )}
           >
-            <Heading2 size={14} /> 제목 2
+            <Heading2 size={14} /> {t('heading2')}
             <span class="hce-menu-shortcut">## </span>
           </button>
           {/if}
@@ -347,7 +351,7 @@
                 editor.chain().focus().toggleHeading({ level: 3 }).run(),
               )}
           >
-            <Heading3 size={14} /> 제목 3
+            <Heading3 size={14} /> {t('heading3')}
             <span class="hce-menu-shortcut">### </span>
           </button>
           {/if}
@@ -364,7 +368,7 @@
             onclick={() =>
               runBlock(() => editor.chain().focus().toggleBulletList().run())}
           >
-            <List size={14} /> 글머리 목록
+            <List size={14} /> {t('bulletList')}
             <span class="hce-menu-shortcut">- </span>
           </button>
           {/if}
@@ -378,7 +382,7 @@
             onclick={() =>
               runBlock(() => editor.chain().focus().toggleOrderedList().run())}
           >
-            <ListOrdered size={14} /> 번호 목록
+            <ListOrdered size={14} /> {t('orderedList')}
             <span class="hce-menu-shortcut">1. </span>
           </button>
           {/if}
@@ -392,7 +396,7 @@
             onclick={() =>
               runBlock(() => editor.chain().focus().toggleTaskList().run())}
           >
-            <CheckSquare size={14} /> 체크리스트
+            <CheckSquare size={14} /> {t('taskList')}
             <span class="hce-menu-shortcut">[] </span>
           </button>
           {/if}
@@ -409,7 +413,7 @@
             onclick={() =>
               runBlock(() => editor.chain().focus().toggleBlockquote().run())}
           >
-            <Quote size={14} /> 인용문
+            <Quote size={14} /> {t('blockquote')}
             <span class="hce-menu-shortcut">" </span>
           </button>
           {/if}
@@ -423,7 +427,7 @@
             onclick={() =>
               runBlock(() => editor.chain().focus().setDetails().run())}
           >
-            <ChevronRight size={14} /> 토글
+            <ChevronRight size={14} /> {t('toggle')}
             <span class="hce-menu-shortcut">> </span>
           </button>
           <!--
@@ -450,7 +454,7 @@
                     .run(),
                 )}
             >
-              <ToggleHeadingIcon size={14} level={level as 1 | 2 | 3} /> 토글 제목 {level}
+              <ToggleHeadingIcon size={14} level={level as 1 | 2 | 3} /> {t('toggleHeading', { level })}
               <span class="hce-menu-shortcut">{'#'.repeat(level)} &gt; </span>
             </button>
           {/each}
@@ -475,7 +479,7 @@
     <button
       type="button"
       onclick={() => editor.chain().focus().toggleBold().run()}
-      aria-label="굵게"
+      aria-label={t('bold')}
       class={cn(
         "p-1.5 rounded-md transition-colors",
         isActive("bold")
@@ -490,7 +494,7 @@
     <button
       type="button"
       onclick={() => editor.chain().focus().toggleItalic().run()}
-      aria-label="기울임"
+      aria-label={t('italic')}
       class={cn(
         "p-1.5 rounded-md transition-colors",
         isActive("italic")
@@ -505,7 +509,7 @@
     <button
       type="button"
       onclick={() => editor.chain().focus().toggleUnderline().run()}
-      aria-label="밑줄"
+      aria-label={t('underline')}
       class={cn(
         "p-1.5 rounded-md transition-colors",
         isActive("underline")
@@ -520,7 +524,7 @@
     <button
       type="button"
       onclick={() => editor.chain().focus().toggleStrike().run()}
-      aria-label="취소선"
+      aria-label={t('strike')}
       class={cn(
         "p-1.5 rounded-md transition-colors",
         isActive("strike")
@@ -552,7 +556,7 @@
     <button
       type="button"
       onclick={() => editor.chain().focus().setTextAlign('left').run()}
-      aria-label="왼쪽 정렬"
+      aria-label={t('alignLeft')}
       class={cn(
         "p-1.5 rounded-md transition-colors",
         isActive({ textAlign: 'left' })
@@ -567,7 +571,7 @@
     <button
       type="button"
       onclick={() => editor.chain().focus().setTextAlign('center').run()}
-      aria-label="가운데 정렬"
+      aria-label={t('alignCenter')}
       class={cn(
         "p-1.5 rounded-md transition-colors",
         isActive({ textAlign: 'center' })
@@ -582,7 +586,7 @@
     <button
       type="button"
       onclick={() => editor.chain().focus().setTextAlign('right').run()}
-      aria-label="오른쪽 정렬"
+      aria-label={t('alignRight')}
       class={cn(
         "p-1.5 rounded-md transition-colors",
         isActive({ textAlign: 'right' })
@@ -603,11 +607,11 @@
       <button
         type="button"
         onclick={() => (insertMenuOpen = !insertMenuOpen)}
-        aria-label="삽입"
+        aria-label={t('insert')}
         class="flex items-center gap-1 px-2 py-1.5 rounded-md transition-colors text-muted-foreground hover:bg-muted hover:text-foreground"
       >
         <Plus size={iconSize} />
-        <span class="text-sm">삽입</span>
+        <span class="text-sm">{t('insert')}</span>
         <ChevronDown size={12} />
       </button>
       {#if insertMenuOpen}
@@ -622,7 +626,7 @@
             onclick={() =>
               runInsert(() => editor.chain().focus().setCodeBlock().run())}
           >
-            <Code2 size={14} /> 코드 블록
+            <Code2 size={14} /> {t('codeBlock')}
             <span class="hce-menu-shortcut">```</span>
           </button>
           {/if}
@@ -633,7 +637,7 @@
             onclick={() =>
               runInsert(() => editor.chain().focus().promptMathDisplay().run())}
           >
-            <Sigma size={14} /> 수식 블록
+            <Sigma size={14} /> {t('mathBlock')}
             <span class="hce-menu-shortcut">$$</span>
           </button>
           <!--
@@ -648,7 +652,7 @@
             onclick={() =>
               runInsert(() => editor.chain().focus().promptMathInline().run())}
           >
-            <Sigma size={14} /> 인라인 수식
+            <Sigma size={14} /> {t('mathInline')}
             <span class="hce-menu-shortcut">$ $</span>
           </button>
           {/if}
@@ -667,7 +671,7 @@
             class="w-full text-left px-2.5 py-1.5 text-xs transition-colors flex items-center gap-2 hover:bg-muted"
             onclick={() => runInsert(onFileClick!)}
           >
-            <Paperclip size={14} /> 파일
+            <Paperclip size={14} /> {t('file')}
           </button>
           {/if}
           {#if has('table')}
@@ -679,7 +683,7 @@
                 insertTableSized(editor, { rows: 3, cols: 3, withHeaderRow: true }),
               )}
           >
-            <TableIcon size={14} /> 표 (3x3)
+            <TableIcon size={14} /> {t('table3x3')}
           </button>
           {/if}
 
@@ -695,7 +699,7 @@
                 editor.chain().focus().setHorizontalRule().run(),
               )}
           >
-            <Minus size={14} /> 구분선
+            <Minus size={14} /> {t('divider')}
             <span class="hce-menu-shortcut">---</span>
           </button>
           {/if}
@@ -706,7 +710,7 @@
             onclick={() =>
               runInsert(() => editor.chain().focus().setColumns(2).run())}
           >
-            <Columns2 size={14} /> 2단 컬럼
+            <Columns2 size={14} /> {t('columns2')}
           </button>
           {/if}
           {#if has('columns-3')}
@@ -716,7 +720,7 @@
             onclick={() =>
               runInsert(() => editor.chain().focus().setColumns(3).run())}
           >
-            <Columns3 size={14} /> 3단 컬럼
+            <Columns3 size={14} /> {t('columns3')}
           </button>
           {/if}
           {#if has('tabs')}
@@ -726,7 +730,7 @@
             onclick={() =>
               runInsert(() => editor.chain().focus().setTabs(3).run())}
           >
-            <PanelTop size={14} /> 탭
+            <PanelTop size={14} /> {t('tabs')}
           </button>
           {/if}
           {#if has('card')}
@@ -735,7 +739,7 @@
             class="w-full text-left px-2.5 py-1.5 text-xs transition-colors flex items-center gap-2 hover:bg-muted"
             onclick={() => runInsert(() => editor.chain().focus().setCard().run())}
           >
-            <SquareDashed size={14} /> 카드
+            <SquareDashed size={14} /> {t('card')}
           </button>
           {/if}
 
@@ -748,7 +752,7 @@
             class="w-full text-left px-2.5 py-1.5 text-xs transition-colors flex items-center gap-2 hover:bg-muted"
             onclick={addImage}
           >
-            <ImageIcon size={14} /> 이미지
+            <ImageIcon size={14} /> {t('image')}
           </button>
           {/if}
           {#if has('video')}
@@ -761,7 +765,7 @@
             class="w-full text-left px-2.5 py-1.5 text-xs transition-colors flex items-center gap-2 hover:bg-muted"
             onclick={addVideo}
           >
-            <Youtube size={14} /> 영상
+            <Youtube size={14} /> {t('video')}
           </button>
           {/if}
           {#if has('mbus')}
@@ -770,7 +774,7 @@
             class="w-full text-left px-2.5 py-1.5 text-xs transition-colors flex items-center gap-2 hover:bg-muted"
             onclick={addMbus}
           >
-            <Tv size={14} /> 미디버스 영상
+            <Tv size={14} /> {t('mbusVideo')}
           </button>
           {/if}
         </div>
@@ -783,24 +787,26 @@
   <!-- (이미지 모달은 없다 — 에디터가 업로드/링크 탭 모달을 띄운다. `onImageClick` 참고.) -->
   {#if modalState?.type === "video"}
     <InputModal
-      title="영상 URL"
+      title={t('videoUrl')}
       placeholder="https://www.youtube.com/watch?v=..."
       onConfirm={(url) => {
         editor.chain().focus().setVideoEmbed({ src: url }).run();
         modalState = null;
       }}
       onCancel={() => (modalState = null)}
+      {t}
     />
   {/if}
   {#if modalState?.type === "mbus"}
     <InputModal
-      title="미디버스 영상 URL"
+      title={t('mbusVideoUrl')}
       placeholder="https://play.mbus.tv/v1/hls/..."
       onConfirm={(url) => {
         editor.chain().focus().setMbusVideo({ src: url }).run();
         modalState = null;
       }}
       onCancel={() => (modalState = null)}
+      {t}
     />
   {/if}
 

package/dist/components/FixedToolbar.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { Editor } from "@tiptap/core";
 import type { Snippet } from "svelte";
 import type { ToolbarFeature, PromptHandler } from "../types";
+import { type EditorTranslator } from "../i18n";
 type $$ComponentProps = {
     editor: Editor;
     features: Set<ToolbarFeature>;
@@ -25,6 +26,8 @@ type $$ComponentProps = {
      * 여기에 넣으면 툴바의 flex 행에 그대로 얹혀 정렬이 저절로 맞는다.
      */
     toolbarEnd?: Snippet;
+    /** 에디터 UI 번역 함수. 미주입 시 ko. */
+    t?: EditorTranslator;
 };
 declare const FixedToolbar: import("svelte").Component<$$ComponentProps, {}, "">;
 type FixedToolbar = ReturnType<typeof FixedToolbar>;

package/dist/components/FixedToolbar.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FixedToolbar.svelte.d.ts","sourceRoot":"","sources":["../../src/components/FixedToolbar.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAwCtC,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE7D,KAAK,gBAAgB,GAAI;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAC9B,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,0CAA0C;IAC1C,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAuiBJ,QAAA,MAAM,YAAY,sDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"FixedToolbar.svelte.d.ts","sourceRoot":"","sources":["../../src/components/FixedToolbar.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAwCtC,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAElE,KAAK,gBAAgB,GAAI;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAC9B,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,0CAA0C;IAC1C,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,8BAA8B;IAC9B,CAAC,CAAC,EAAE,gBAAgB,CAAC;CACtB,CAAC;AAyiBJ,QAAA,MAAM,YAAY,sDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/FloatingHelper.svelte

@@ -0,0 +1,219 @@
+<script lang="ts">
+  import type { Editor } from "@tiptap/core";
+  import { Sigma, Code2 } from "lucide-svelte";
+  import type { ToolbarFeature } from "../types";
+  import {
+    floatingHelperVisible,
+    helperInsertMath,
+    helperInsertCodeBlock,
+    FLOATING_HELPER_ON_CLASS,
+  } from "../utils/floating-helper";
+  import { defaultTranslator, type EditorTranslator } from "../i18n";
+
+  /*
+   * 빈 줄 플로팅 헬퍼의 **화면 절반** — 판정·커맨드는 `utils/floating-helper.ts`.
+   *
+   * 포커스된 최상위 빈 문단 옆에 "/로 명령어 입력" 안내와 수식·코드 즉시 삽입 버튼을
+   * 띄운다(main 정올 `Floating.svelte` 의 직접 구현 이식). 에디터 컨테이너
+   * (`.hce-editor-wrapper`, `position:relative`) 안에 `position:absolute` 로 그린다 —
+   * 포털이 없고 문서 흐름의 자리도 차지하지 않는다.
+   *
+   * ⚠️ 위치 계산 셋이 main 사고 이력의 재발 방지다:
+   * - `.hce-floating-helper` 는 CSS 에서 **처음부터** `position:absolute; width:max-content`
+   *   다. 블록 폭으로 측정된 뒤에 좁히면 넘침 보정이 화면 밖(left:-437px)으로 민 전력이
+   *   있다(main floating-ui 시절).
+   * - 등장 애니메이션은 **안쪽 요소에만** 건다. 바깥(위치 담당)에 transform 을 걸면
+   *   위치가 애니메이션 프레임에 덮인다(main `79f64c18`→`c9840fdb`).
+   * - 슬래시·이모지 메뉴가 열리면 `suppressed` 로 끈다 — 그 둘은 `position:fixed`
+   *   뷰포트 좌표라 좌표계가 달라 서로 피해 갈 수 없다.
+   */
+  let {
+    editor,
+    features,
+    suppressed = false,
+    t = defaultTranslator,
+  }: {
+    editor: Editor;
+    features: Set<ToolbarFeature>;
+    suppressed?: boolean;
+    /** 에디터 UI 번역 함수. 미주입 시 ko. */
+    t?: EditorTranslator;
+  } = $props();
+
+  let visible = $state(false);
+  let pos = $state({ top: 0, left: 0 });
+  let helperEl = $state<HTMLDivElement>();
+  let focused = $state(false);
+
+  const showMath = $derived(features.has("math"));
+  const showCode = $derived(features.has("code-block"));
+  const hasButtons = $derived(showMath || showCode);
+
+  function updatePosition() {
+    const wrapper = editor.view.dom.closest(".hce-editor-wrapper") as HTMLElement | null;
+    if (!wrapper) return;
+    const { from } = editor.state.selection;
+    const caret = editor.view.coordsAtPos(from);
+    const box = wrapper.getBoundingClientRect();
+    let left = caret.right - box.left + 8;
+    let top = caret.top - box.top;
+    /*
+     * 요소가 이미 서 있으면 실측으로 보정한다 — 세로는 커서 줄에 가운데 맞춤,
+     * 가로는 래퍼 오른쪽을 넘으면 안으로 죈다(첫 프레임은 아래 `$effect` 가 재계산).
+     */
+    if (helperEl) {
+      const h = helperEl.offsetHeight;
+      if (h) top = caret.top - box.top + (caret.bottom - caret.top - h) / 2;
+      const w = helperEl.offsetWidth;
+      const maxLeft = wrapper.clientWidth - w - 4;
+      if (w && left > maxLeft) left = Math.max(4, maxLeft);
+    }
+    pos = { top, left };
+  }
+
+  function evaluate() {
+    const show = floatingHelperVisible(editor, { focused, suppressed });
+    if (show) updatePosition();
+    visible = show;
+    /* placeholder 겹침 방지 — 근거는 `FLOATING_HELPER_ON_CLASS` 주석. */
+    editor.view.dom.classList.toggle(FLOATING_HELPER_ON_CLASS, show);
+  }
+
+  $effect(() => {
+    focused = editor.view.hasFocus();
+    const onFocus = () => {
+      focused = true;
+    };
+    const onBlur = () => {
+      focused = false;
+    };
+    editor.on("transaction", evaluate);
+    editor.on("focus", onFocus);
+    editor.on("blur", onBlur);
+    return () => {
+      editor.off("transaction", evaluate);
+      editor.off("focus", onFocus);
+      editor.off("blur", onBlur);
+      editor.view.dom.classList.remove(FLOATING_HELPER_ON_CLASS);
+    };
+  });
+
+  /* 포커스·suppressed 가 바뀌면 재판정 (트랜잭션 없이 바뀌는 두 축). */
+  $effect(() => {
+    focused;
+    suppressed;
+    evaluate();
+  });
+
+  /* 마운트 직후 실측(폭·높이)으로 한 번 더 자리를 잡는다. */
+  $effect(() => {
+    if (visible && helperEl) updatePosition();
+  });
+
+  /* 래퍼 안쪽이 스크롤되는 호스트 대비 — 슬래시·이모지 메뉴와 같은 캡처 구독. */
+  $effect(() => {
+    if (!visible) return;
+    const onMove = () => updatePosition();
+    window.addEventListener("scroll", onMove, true);
+    window.addEventListener("resize", onMove);
+    return () => {
+      window.removeEventListener("scroll", onMove, true);
+      window.removeEventListener("resize", onMove);
+    };
+  });
+</script>
+
+{#if visible}
+  <!--
+    mousedown preventDefault: 버튼을 누르는 순간 에디터가 blur 되면 클릭이 닿기 전에
+    헬퍼가 사라진다(버튼과 함께). 포커스를 아예 뺏기지 않는 쪽이 main 의
+    `setTimeout(focus)` 복원보다 깔끔하다 — 툴바들이 쓰는 표준 수법.
+  -->
+  <div
+    bind:this={helperEl}
+    class="hce-floating-helper"
+    style="top: {pos.top}px; left: {pos.left}px"
+    role="toolbar"
+    tabindex="-1"
+    aria-label={t('emptyLineTools')}
+    onmousedown={(e) => e.preventDefault()}
+  >
+    <div class="hce-floating-helper-inner">
+      <span class="hce-floating-helper-hint">{t('floatingHint')}{hasButtons ? t('floatingHintOr') : ""}</span>
+      {#if showMath}
+        <button
+          type="button"
+          class="hce-floating-plus"
+          title={t('math')}
+          aria-label={t('insertMath')}
+          onclick={() => helperInsertMath(editor)}
+        >
+          <Sigma size={14} />
+        </button>
+      {/if}
+      {#if showCode}
+        <button
+          type="button"
+          class="hce-floating-plus"
+          title={t('codeBlock')}
+          aria-label={t('insertCodeBlock')}
+          onclick={() => helperInsertCodeBlock(editor)}
+        >
+          <Code2 size={14} />
+        </button>
+      {/if}
+    </div>
+  </div>
+{/if}
+
+<style>
+  /*
+   * ⚠️ `position:absolute` + `width:max-content` 는 **여기 고정**이다 — 위치·크기가
+   * 런타임 계산보다 먼저 서 있어야 실측 보정(`updatePosition`)이 옳은 폭을 잰다.
+   * z-index 100: 정올 sticky 브레드크럼(z:93)보다 위, 모달(z-50=50 계열 Tailwind 층과는
+   * 별개 스택) 아래를 노린 값.
+   */
+  .hce-floating-helper {
+    position: absolute;
+    width: -moz-max-content;
+    width: max-content;
+    z-index: 100;
+    pointer-events: auto;
+  }
+
+  /* 등장 애니메이션은 안쪽에만 — 바깥 transform 은 위치 계산과 충돌한다. */
+  .hce-floating-helper-inner {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    animation: hce-floating-helper-in 0.18s ease-out;
+  }
+
+  @keyframes hce-floating-helper-in {
+    from {
+      opacity: 0;
+      transform: translateX(-4px);
+    }
+    to {
+      opacity: 1;
+      transform: none;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .hce-floating-helper-inner {
+      animation: none;
+    }
+  }
+
+  .hce-floating-helper-hint {
+    font-size: 0.875rem;
+    color: var(--muted-foreground);
+    opacity: 0.6;
+    pointer-events: none;
+    -webkit-user-select: none;
+       -moz-user-select: none;
+            user-select: none;
+    white-space: nowrap;
+  }
+</style>

package/dist/components/FloatingHelper.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Editor } from "@tiptap/core";
+import type { ToolbarFeature } from "../types";
+import { type EditorTranslator } from "../i18n";
+type $$ComponentProps = {
+    editor: Editor;
+    features: Set<ToolbarFeature>;
+    suppressed?: boolean;
+    /** 에디터 UI 번역 함수. 미주입 시 ko. */
+    t?: EditorTranslator;
+};
+declare const FloatingHelper: import("svelte").Component<$$ComponentProps, {}, "">;
+type FloatingHelper = ReturnType<typeof FloatingHelper>;
+export default FloatingHelper;
+//# sourceMappingURL=FloatingHelper.svelte.d.ts.map

package/dist/components/FloatingHelper.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FloatingHelper.svelte.d.ts","sourceRoot":"","sources":["../../src/components/FloatingHelper.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAO/C,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAElE,KAAK,gBAAgB,GAAI;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,8BAA8B;IAC9B,CAAC,CAAC,EAAE,gBAAgB,CAAC;CACtB,CAAC;AA0IJ,QAAA,MAAM,cAAc,sDAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}