Categories & defineElement

Every element belongs to one of three categories. The category determines how the element is placed on the board and which render functions you must provide.

Element Categories

inline

Renders within a scene alongside its siblings. Use this for elements that flow with narrative content — callouts, equations, cards, rich text blocks.

defineElement({
  kind: 'callout',
  category: 'inline',
  render(props, api) {
    return <p>{api.element.body}</p>
  },
})

hybrid

Has both an inline state and a full-board state. Which state is used depends on the element's mode attribute in Chalk — mode: inline (default) or mode: environment. The code editor and diagram elements are hybrid: they appear inline in a list of elements, but expand to take the full board when placed alone in a scene's detail zone.

You must provide both render (inline) and renderEnvironment (full-board):

defineElement({
  kind: 'my-chart',
  category: 'hybrid',
  render(props, api) {
    // Compact inline preview
    return <ChartThumbnail {...props} />
  },
  renderEnvironment(props, api) {
    // Full board interactive chart
    return <ChartFull {...props} api={api} />
  },
})

environment

Always takes the full board. Use this for elements that need the full visual space and toolbar integration — interactive simulations, IDEs, quiz environments.

defineElement({
  kind: 'simulation',
  category: 'environment',
  renderEnvironment(props, api) {
    return <Simulation {...props} api={api} />
  },
})

Environment elements can also contribute toolbar buttons:

let running = false

defineElement({
  kind: 'simulation',
  category: 'environment',
  toolbar(api, props) {
    return [
      {
        type: 'toggle',
        id: 'run',
        icon: running ? 'pause' : 'play',
        label: running ? 'Pause' : 'Run',
        active: running,
        onToggle: () => { running = !running },
      },
      { type: 'separator' },
      {
        type: 'button',
        id: 'reset',
        icon: 'restart',
        label: 'Reset',
        onClick: () => { running = false },
      },
    ]
  },
  renderEnvironment(props, api) {
    return <Simulation running={running} {...props} />
  },
})

defineElement

defineElement is the single authoring primitive. Pass it an object describing your element and it returns the same object after validation.

import { defineElement } from '@internote/element-sdk'

export default defineElement({
  kind: 'my-element',
  category: 'inline',
  render(props, api) {
    return <div>{api.element.body}</div>
  },
})

defineElement throws at startup if required fields are missing — for example, if you declare category: 'environment' without providing renderEnvironment. This makes authoring mistakes visible immediately rather than at render time.

ElementDefinition Fields

kind

The Chalk identifier(s) this element handles. Every element needs a unique kind. Pass an array to handle multiple identifiers with a single definition:

// Single identifier
defineElement({ kind: 'counter', category: 'inline', render })

// Multiple identifiers — same definition handles both
defineElement({ kind: ['counter', 'click-counter'], category: 'inline', render })

Later registrations for the same kind override earlier ones, so you can replace a definition without reloading the page.

render

The inline render function. Receives resolved props (from your declared schema) and an ElementApi. Must return a React element or null.

Required for inline and hybrid categories.

renderEnvironment

The full-board render function. Same signature as render. Required for environment and hybrid categories, ignored for inline.

schema

Optional declarative attribute schema. When declared, the SDK resolves your element's Chalk attributes into a typed props object before your render function runs — you read props.colour instead of parsing the raw attribute list manually. See Attribute Schemas.

animation

Declares which animation modes your element supports:

animation: {
  fade: true,   // supports cue{} fade in/out
  draw: true,   // supports cue.draw{} stroke/text/block reveal
  morph: true,  // supports cue.morph{} transitions
}

Declare only the modes you use. The runtime wires the appropriate hooks based on this declaration.

toolbar

Provides toolbar buttons, toggles, and separators for environment (and hybrid-environment) elements. See Toolbar.

displayName

Optional human-readable label shown in the plugin marketplace and developer debugging tools.

Hooks in Render Functions

Render functions are called as ordinary React function components. useState, useEffect, useRef, and any other hook all work:

defineElement({
  kind: 'counter',
  category: 'inline',
  render(props, api) {
    const [count, setCount] = React.useState(0)

    React.useEffect(() => {
      // Restore count from storage on mount
      api.storage.get('count').then((saved) => {
        if (saved != null) setCount(saved as number)
      })
    }, [])

    const increment = () => {
      const next = count + 1
      setCount(next)
      api.storage.set('count', next)
    }

    return <button onClick={increment}>{count}</button>
  },
})

ElementRegistry

Definitions must be registered before they can render. Call ElementRegistry.register once per definition, typically at application startup:

import { ElementRegistry } from '@internote/element-sdk'
import counterDef from './counter'
import chartDef from './chart'

ElementRegistry.register(counterDef)
ElementRegistry.register(chartDef)

Other registry methods:

ElementRegistry.resolve('counter')      // → ElementDefinition | undefined
ElementRegistry.has('counter')          // → boolean
ElementRegistry.registeredKinds()       // → string[]

If ElementRenderer encounters a kind that is not registered, it falls back to rendering the raw element JSON as a debug view rather than throwing. This lets you register definitions incrementally without breaking the renderer for already-registered elements.