Build your own wing ​

A wing is one object. There is no class to extend and no registration ceremony — putting it in the wings array is the registration.

A wing you write runs on exactly the same terms as the built-in ones. Bold, tables and uploads are all made by filling in the very fields described here. There is a single door into core behaviour (the flower), and no back door that is open only on the inside.

The shortest wing ​

import { nabi, markIcon } from 'nabi-note'
import type { NabiWing } from 'nabi-note'

function highlight(): NabiWing {
  return {
    id: 'text-highlight',
    group: 'mark',
    names: { ko: '형광펜', en: 'Highlight' },
    icon: markIcon('<path d="M3 12h10"/>'),
    inline: {
      tag: 'mark',
      attributes: [],
      escapeKeys: ['Escape'],
      claims: (element) => element.tagName === 'MARK',
    },
  }
}

nabi.create('#editor', { wings: [highlight()] })

That gives you a toolbar button, an entry in the @ menu, and <mark> surviving in the document. Without registration <mark> is unwrapped and falls to plain text.

Export a factory function, not an instance ​

A wing is a function that returns a fresh object every time it is called, the way bold() does. A page can hold several editors, and two editors sharing one object would share whatever state lives inside it.

// ✅ an independent object per editor
export function highlight(): NabiWing { return { /* … */ } }

// ❌ one object per module — both editors use the same one
export const highlight: NabiWing = { /* … */ }

State belongs in the factory's closure. That is how the upload wing is built — the in-flight bookkeeping and the AbortController are all local variables inside createWing().

export function counter(): NabiWing {
  let editor: EditorHandle | null = null   // state for this editor only

  return {
    id: 'demo-counter',
    names: { ko: '글자 수', en: 'Count' },
    setup(handle) {
      editor = handle
      return () => { editor = null }
    },
  }
}

Wings that take options have the same shape — heading(1), link({ allowLocalUrls: true }) and code({ highlight }) are all factories with arguments.

Registration and order ​

nabi.create('#editor', {
  wings: [bold(), italic(), highlight()],
  html: '<p>Initial content</p>',
  onChange: (html) => console.log(html),
})

Array order is scan order. When core decides who owns a piece of markup it asks claims in this order, and the first wing to answer true takes it. If nobody takes it, the element is unwrapped.

Order decides the outcome in these places.

Every field you can fill ​

This is the whole of NabiWing. Only id and names are required; everything else is filled in when you need it.

id ​

A globally unique absolute identifier.

readonly id: string

It is also the key hosts write in their own code — editor.toggle('text-bold'), editor.runCommand('table-row-insert-above') and toolbar: [['text-bold', 'text-italic']] all use this value.

• Lowercase and hyphens only: text-bold · block-heading-1 · table-row-insert-above.
• By convention the kind comes first — text- for marks, block- for blocks, align- for the alignment family.
• Command ids inside commands follow the same rule, and prefixing them with the wing id is recommended (link-remove · code-language · details-toggle).

names ​

The per-locale display name used for the button tooltip, the @ menu entry and search.

interface WingNames {
  readonly ko: string
  readonly en: string
  readonly [locale: string]: string   // add more languages if you like
}

names: { ko: '굵게', en: 'Bold' }
names: { ko: '위에 행 추가', en: 'Insert row above' }

The lookup goes exact match → language code only → en → the first remaining value. With locale: 'ko-KR' the ko entry is used; if no language matches, it falls back to en.

• Always fill in ko and en. Other languages are optional.
• names.en starts with a capital letter. Several wings stand side by side in the toolbar and the @ menu, so mixed casing shows up immediately.
• The @ menu searches the current locale name, the other locale names and the id, so bold finds the wing even on a Korean screen.
• Messages with values baked in — upload errors, for instance — use {param} placeholders, which the flower's t() fills.

icon ​

What the toolbar button draws. An icon is a URL.

readonly icon?: string

Core accepts three shapes and tells them apart itself.

Three helpers freeze SVG into a URL.

import { svgIcon, markIcon, blockIcon } from 'nabi-note'

markIcon('<path d="M2 8h12"/>')   // stroke 1.6 — marks, alignment, lists
blockIcon('<rect x="1.75" y="2.75" width="12.5" height="10.5" rx="1.5"/>')  // stroke 1.4 — blocks
svgIcon('<path d="…"/>', 2)        // when you want to set the stroke yourself

• The wrapper (<svg>, viewBox, stroke colour) is added for you. Pass strokes and shapes only. The grid is 0 0 16 16.
• There are two presets so the weights match. Block icons carry more strokes and need to be thinner (1.4); mark icons carry fewer and need to be slightly heavier (1.6).
• Filled shapes need an opaque fill. The mask looks at alpha, not colour, so an unfilled shape becomes a hole. That is why YouTube's play triangle carries fill="#000".
• Do not put colour in the SVG. Following currentColor is what makes pressed, disabled and dark states come along for free.
• Sometimes a text label is the better answer — headings use icon: 'H1'.

group ​

The kind the toolbar uses to show only the buttons that make sense right now.

type WingGroup = 'mark' | 'block' | 'insert'   // defaults to 'insert'

Which kinds are visible is decided by where the caret is.

The @ menu reads the same table. There is no gap where the toolbar hides something the menu still inserts.

• Omitting the kind means insert — being visible everywhere is the safe default.
• This value governs visibility only. Whether the action actually applies is checked separately (drop cap's appliesTo, a command's isAvailable).

styles ​

The stylesheet this wing carries. One string.

readonly styles?: string

import { NOTE_SCOPE } from 'nabi-note'

const DIVIDER_STYLES = `
${NOTE_SCOPE} > hr {
  margin: 1.1em 0;
  border: none;
  border-top: 1px solid var(--nabi-border);
}
`

export function horizontalRule(): NabiWing {
  return { id: 'block-divider', styles: DIVIDER_STYLES, /* … */ }
}

The core sheet holds only what is needed with no wings at all — frame, colour tokens, buttons, floating boxes. Per-format rules travel with each wing. An editor without the heading wing never loads heading CSS.

• Injected after the core sheet on mount, so wings win at equal specificity.
• Identical strings are injected once per document. A family of wings sharing one constant never stacks copies — heading(1)…heading(6) share HEADING_STYLES, superscript and subscript share SUBSUP_STYLES, the three alignments share ALIGN_STYLES.
• The sheet is removed when the last editor holding it is destroyed.
• Pick the root by one question — should this rule also apply to getHtml() output? Yes → prefix with NOTE_SCOPE (document formatting: what stored HTML looks like). No → prefix with EDITOR_SCOPE (editing-screen only: caret hints, ephemeral markup). Boxes your wing draws itself get their own block class instead — .nabi-<name>, parts as .nabi-<name>__<part> (kebab-case), states as .nabi-<name>--<state>.
• If you declare your own tokens, declare them on TOKEN_SCOPE — otherwise stored HTML rendered outside the editor has no values for your var(--nabi-…) references.
• Colours, radii and shadows go through var(--nabi-*) tokens. If you declare your own colour token you must reproduce all three blocks — light, dark and explicit light. Miss one and the colour leaks in that theme.
• Do not put a backtick inside the string.

Do not rely on browser defaults. If the host ships a reset (say ol, ul { list-style: none }) your bullets and numbers vanish entirely. The rule is that a wing carrying a sheet owns the appearance of its own markup, which is why the list wing declares its markers itself.

Next ​

• Inline marks — all of InlineMarkSpec
• Blocks and attributes — BlockSpec · ContentSpec · blockAttribute
• UI and actions — picker · prompt · activate · commands · onClick
• Keys, rules, paste — keys · inputRules · paste · files
• setup and flower — the lifecycle hook and the door into core