setup 훅과 꽃 (flower) ​

선언 칸으로 표현되지 않는 것은 setup 에서 직접 만듭니다. 그리고 그때 쓰는 코어 기능은 꽃(flower) 이라는 문 하나로만 들어옵니다.

이름의 뜻 — 꽃은 몸통이 날개를 위해 피워 둔 자리입니다. 외부 라이브러리가 아니라 코어가 골라 내준 자기 표면입니다. 날개는 꽃에서만 꿀을 얻습니다.

setup ​

setup?(editor: EditorHandle): (() => void) | void

mount 직후 한 번 불립니다. 돌려준 함수는 destroy() 때 불립니다 — 만든 것은 반드시 여기서 되돌립니다.

setup(editor) {
  const off = editor.on('change', sync)
  return () => off()
}

업로드 날개는 여기서 인스턴스 상태를 붙들고 정리합니다.

setup(handle) {
  editor = handle
  controller = new AbortController()

  return () => {
    // 진행 중인 업로드에 그만두라고 알립니다. 잠금은 코어가 destroy 때 걷어갑니다
    controller.abort()
    // 아직 걷히지 않은 자리표시자의 미리보기 주소를 전부 되돌립니다
    for (const record of active) releasePreview(record)
    active.clear()
    editor = null
  }
},

코드 하이라이팅도 같은 모양입니다 — change 를 듣고 한 프레임에 한 번만 칠하며, 정리 함수가 구독과 예약된 프레임을 함께 걷습니다.

function startHighlighting(editor: EditorHandle, options: CodeOptions): () => void {
  let frame = 0

  const paintAll = () => {
    frame = 0
    // 조합 중에는 DOM 을 갈아엎지 않습니다 — 판정은 코어의 것 하나만 믿습니다
    if (editor.composing) return
    /* … 코드 블록마다 칠하기 … */
  }

  const schedule = () => {
    if (editor.composing || frame !== 0) return
    frame = editor.document.defaultView?.requestAnimationFrame(paintAll) ?? 0
    if (frame === 0) paintAll()
  }

  const off = editor.on('change', schedule)
  paintAll()                        // 처음 한 번

  return () => {
    off()
    if (frame !== 0) editor.document.defaultView?.cancelAnimationFrame?.(frame)
  }
}

setup 이 던져도 에디터는 계속 돕니다. 스캔·키·클릭·pasteText·pasteHtml 도 마찬가지로 예외를 삼킵니다 — 날개 하나가 에디터 전체를 세우지 않습니다.

EditorHandle — setup 이 받는 것 ​

Nabi 전체가 아니라 날개에게 필요한 표면만 받습니다. 전체 인스턴스를 넘기면 날개가 내부 구현에 기대게 되고, 그 순간 코어를 고칠 수 없게 됩니다.

들을 수 있는 이벤트는 change · selectionchange · markschange · menuchange · historychange · lockchange · fullscreenchange · focus · blur · destroy 입니다.

꽃이 주는 것 ​

nabi-note 가 내보내는 것 중 날개를 만들 때 쓰는 것들입니다. 번들 날개와 서드파티 날개가 같은 문을 씁니다 — 안쪽에만 열려 있는 지름길은 없습니다.

import {
  insertBlockAt,
  findAdjacentBlock,
  deleteBlockCommand,
  caretToStart,
  clearFormatAt,
  clearMarksInRange,
  isPlainBlock,
  safeUrl,
  markIcon,
  blockIcon,
  svgIcon,
  TRASH_ICON,
} from 'nabi-note'

블록 넣기·찾기·지우기 ​

insertBlockAt 이 캐럿이 아니라 context.block 을 기준으로 삼는 것이 요점입니다 — 입력 상자로 포커스가 옮겨간 뒤에도 상자를 열던 순간의 자리에 넣을 수 있어야 하기 때문입니다.

마크 ​

자리 술어 ​

검증·아이콘·해시 ​

safeUrl 의 allowLocal 은 업로드 미리보기와 데모에서만 켜세요. blob:·data: 주소는 그 페이지를 벗어나면 의미가 없습니다. data: 는 그림만 통과합니다 — data:text/html 은 그림이 아니라 문서를 실어 나릅니다.

그 밖에 함께 나오는 것 ​

import type {
  NabiWing, InlineMarkSpec, BlockSpec, ContentSpec, BlockAttributeSpec,
  CommandContext, CaretBlock, WingCommand, WingNames, WingGroup,
  KeyBinding, KeyRunResult, InputRule, GridPickerSpec, PromptSpec,
  EditorHandle, EditorLock, FileDrop, UIService, UIPopupHandle, NoticeTone, Locale,
} from 'nabi-note'

WingRegistry 와 NABI_CSS·NABI_STYLE_ID 도 나옵니다 — 시트를 직접 다루거나 빌드 시점에 뽑아 쓸 때입니다.

viewer — 에디터 밖에서 도는 동작 ​

viewer?(handle: ViewerHandle): (() => void) | void

setup 이 편집 중의 훅이라면 viewer 는 저장된 HTML 을 그리는 쪽의 훅입니다. 나가는 값은 자바스크립트 없이 그대로 읽히는 HTML 이고 그것이 원칙이지만, 표 정렬이나 이미지 클릭 확대처럼 보는 쪽에서만 뜻이 있는 상호작용은 그 자리에 남길 것이 없습니다. 이 훅이 그 예외이고, 호스트가 nabiViewer 로 등록한 날개에 한해 돕니다 — "등록하지 않은 것은 존재하지 않는다" 가 보는 쪽에도 그대로 섭니다.

받는 손잡이는 EditorHandle 이 아니라 ViewerHandle 입니다. 편집기가 없는 페이지라 캐럿도 편집 관문도 없습니다.

viewer(handle) {
  const detachers = [...handle.root.querySelectorAll('table[data-nabi-sortable]')]
    .map((table) => attachSort(table as HTMLTableElement, handle))

  return () => { for (const detach of detachers) detach() }
}

• 붙인 것은 해제 함수가 전부 되돌립니다 — 꽂은 버튼, 바꾼 행 순서, 단 속성까지. 해제한 뒤의 DOM 이 붙이기 전과 같아야 합니다.
• 저장값에는 한 글자도 남기지 않습니다. 문서에 남는 것은 표식 속성 (data-nabi-sortable)뿐이고, 버튼도 정렬 상태도 보는 쪽의 순간 상태입니다.
• 던져도 그 날개만 건너뜁니다. 한 날개의 오류가 페이지를 죽이지 않습니다.
• 에디터에서는 불리지 않습니다. 미리보기는 보는 쪽이므로 불립니다.

안쪽 날개들이 더 쓰는 것 ​

번들 날개는 꽃의 더 넓은 표면을 씁니다 — 블록 전환(setBlockType), 리스트 토글· 들여쓰기(toggleContainer·indentListItems), 표 커맨드 일습, 캐럿 읽기(caretBlock· caretAtBlockStart), 블록 벗어나기(leaveBlock), 값을 가진 마크 걸기 (applyMarkWithValue·markAtCaret), 로케일 보간(t·resolveName) 같은 것들입니다.

이 중 일부는 아직 패키지 진입점(nabi-note)으로 나오지 않습니다. 다음 문단이 그때 할 일입니다.

계약이 부족하면 — 어디를 넓힙니까 ​

날개를 만들다가 "이건 코어만 할 수 있는데" 싶은 순간이 옵니다. 그때 몰래 우회하지 마세요. 계약에 없는 것을 억지로 뚫으면 다음 버전에서 조용히 깨집니다.

넓혀야 할 자리는 무엇이 부족한가에 따라 다릅니다.

지금 있는 훅들 상당수가 그렇게 생겼습니다.

• 체크박스를 누르는 길이 없어서 → onClick 이 생겼습니다.
• 파일 드롭을 받을 길이 없어서 → handleFiles 가 생겼습니다.
• 유튜브 주소 상자를 직접 그리고 있어서 → prompt.validate 와 preview 가 생겼습니다.
• 캐럿 진입점을 content·empty 로 추론하다 어긋나서 → caretEntry 가 생겼습니다.
• 정렬 버튼이 "보이는데 눌러도 아무 일이 없어서" → appliesTo 를 노출 판정도 함께 보게 됐습니다.

전부 코어를 고친 것이 아니라 계약을 넓힌 것입니다. 그래서 서드파티 날개도 같은 날 같은 능력을 얻었습니다.

새 날개를 만들 때의 확인 목록 ​

1. 팩토리 함수로 만들었습니까. 상태는 클로저 안에 있습니까.
2. id 는 소문자와 하이픈뿐입니까. names.en 은 대문자로 시작합니까.
3. 스캔이 맞는 태그를 잡습니까. 출력이 정규 태그입니까.
4. 등록하지 않았을 때 평문으로 떨어집니까.
5. 필터를 두 번 지나도 결과가 같습니까 (filter(filter(x)) === filter(x)).
6. 내보냈다 되읽었을 때 값이 그대로입니까 (fromSourceHtml(toOutputHtml(x)) === x).
7. 키·클릭 계약이 그 키의 본래 동작을 제대로 막거나 넘깁니까.
8. setup 이 만든 것을 정리 함수가 전부 되돌립니까.
9. 문서를 바꾼 자리마다 commit() 이나 true/'changed' 가 있습니까.

다음 문서 ​

• 시작하기 — 날개의 기본 칸들
• 용어 — wing · flutter · soul · sourceHtml · outputHtml