편집기 연동

@newtil/editor(0.10.12 이상)는 그림판을 직접 갖지 않고 @newtil/drawing 을 연다. 편집기는 열고·넣고·고치는 것 만 하고, PNG 와 도형 데이터의 저장은 호스트 훅에 맡긴다. 이 페이지는 편집기가 이 패키지를 어떻게 쓰는지와 호스트가 붙여야 할 훅을 설명한다.

흐름

편집기 동작	그림판 호출	완료 후
슬래시 /그림판, 툴바 그림판 버튼	openDrawing({ lang, save }) — 빈 판	돌아온 saved 주소로  이미지 삽입
문서 속 이미지 선택 → "그림 고치기"	onDrawingLoad(src) 가 Drawing 을 주면 openDrawing({ initial, lang, save }), 없으면 openDrawing({ background: src, lang, save, notice })	그 이미지 노드의 src 를 saved 로 바꾼다

• 마크다운에는 ![](png) 만 남는다. 도형 데이터(Drawing)는 호스트가 PNG 옆에 곁파일로 맡아 둔다.
• 그림판은 한 번에 하나만 뜬다(버튼 연타·더블클릭 중복 방지).
• save 훅이 실패하면 그림판이 열린 채 이유를 보인다 — 저장 훅 과 같은 규칙.

호스트 훅 두 개

interface DrawingSaveInput { png: Blob; data: Drawing; previousSrc: string | null }
type DrawingSaveHandler = (input: DrawingSaveInput) => Promise<string>;
type DrawingLoadHandler = (src: string) => Promise<Drawing | null>;

훅	역할
onDrawingSave({ png, data, previousSrc })	구운 PNG 와 도형 데이터를 저장하고 문서에 넣을 주소 를 돌려준다. previousSrc 는 "그림 고치기" 일 때 원래 이미지 주소, 새 그림이면 null — 덮어쓸지 새로 만들지 판단하는 데 쓴다
onDrawingLoad(src)	그 이미지 주소의 도형 데이터가 있으면 Drawing, 없으면 null. 던지면 null 로 취급한다

편집기는 onDrawingSave 를 이 패키지의 save(png, data) 로 감싸 넘긴다. 훅이 없으면 PNG 를 data URL 로 문서에 넣는다(도형은 잃는다). onDrawingLoad 가 없으면 "그림 고치기" 는 항상 PNG 를 배경으로만 연다.

DrawingData(= Drawing)·DrawingShape(= Shape)·DrawingSaveHandler·DrawingLoadHandler·DrawingSaveInput 타입은 @newtil/editor 에서도 다시 export 한다.

붙이는 방법

웹 컴포넌트

엘리먼트의 프로퍼티로 넣는다(속성이 아니라 프로퍼티).

const editor = document.querySelector("newtil-editor");
editor.onDrawingSave = async ({ png, data, previousSrc }) => {
  const url = await uploadDrawing(png, data, previousSrc);
  return url;
};
editor.onDrawingLoad = async (src) => fetchDrawingSidecar(src);   // Drawing | null

React

<NewtilEditor
  onDrawingSave={async ({ png, data, previousSrc }) => uploadDrawing(png, data, previousSrc)}
  onDrawingLoad={async (src) => fetchDrawingSidecar(src)}
/>

Vue

<NewtilEditor :on-drawing-save="save" :on-drawing-load="load" />

두 래퍼 모두 prop 을 받아 엘리먼트 프로퍼티에 그대로 넘긴다.

곁파일 설계 힌트

• PNG 주소를 키로 Drawing JSON 을 찾을 수 있게 저장한다(예: x.png ↔ x.png.json, 또는 DB 컬럼).
• Drawing.background 가 data URL 이라 JSON 이 클 수 있다. PNG 와 같은 저장소에 두면 된다.
• previousSrc 가 있을 때 같은 주소로 덮어쓰면 문서를 고칠 필요가 없지만, 캐시 때문에 바뀐 그림이 안 보일 수 있다. 새 주소를 돌려주면 편집기가 src 를 갈아 끼운다.