`@stesura/references`

Framework-free footnotes, endnotes and cross-references: plugins, commands, helpers and the note-panel store. The UI is in @stesura/references-react; the nodes are in the core schema. See the references guide for how the feature behaves.

Plugins

`referencesPlugins`

Every plugin the feature needs, in order. Place them after the core numbering plugins, so cross-references see counters updated in the same transaction.


import { referencesPlugins } from '@stesura/references/plugins'
 
const plugins = [...stesuraPlugins(schema, editorId), ...referencesPlugins()]

The cross-reference and note-panel binding plugins are only available through referencesPlugins(), which keeps their order right.

`notesPlugin`

Note numbering on its own, for hosts that want neither cross-references nor the note panels. Takes an optional list of NoteKindConfigs; the default is footnotes and endnotes.

Parameters:

Name	Type	Default
`kinds`	`NoteKindConfig[]`

Returns:

Plugin<NotesPluginState>

`getFootnotes` / `getEndnotes`

Parameters:

Name	Type	Default
`state`	`EditorState`

Returns:

FootnoteItem[]

Parameters:

Name	Type	Default
`state`	`EditorState`

Returns:

EndnoteItem[]

Commands

`insertCrossReference`

Parameters:

Name	Type	Default
`__0`	`{ targetId: string; text: string; refTo: CrossRefType; separator: string \| null; }` Inserted between levels of a `fullContext` reference.

Returns:

Command

`canInsertCrossReference`

Parameters:

Name	Type	Default
`state`	`EditorState`
`dispatch`	`(tr: Transaction) => void`
`view`	`EditorView`

Returns:

boolean

`goToCrossRefTarget`

Parameters:

Name	Type	Default
`reference`	`CrossRefLink`

Returns:

Command

`insertFootnote`

Parameters:

Name	Type	Default
`ref`	`string`
`onSuccess`	`(ref: string) => void`

Returns:

Command

`insertEndnote`

Parameters:

Name	Type	Default
`ref`	`string`
`onSuccess`	`(ref: string) => void`

Returns:

Command

`deleteFootnote` / `deleteEndnote`

Parameters:

Name	Type	Default
`ref`	`string`

Returns:

Command

Parameters:

Name	Type	Default
`ref`	`string`

Returns:

Command

`navigateFootnote` / `navigateEndnote`

Parameters:

Name	Type	Default
`noteRef`	`string`
`direction`	`1 \| -1`
`onNavigate`	`(ref: string) => void`

Returns:

Command

Parameters:

Name	Type	Default
`noteRef`	`string`
`direction`	`1 \| -1`
`onNavigate`	`(ref: string) => void`

Returns:

Command

`nextFootnote` / `previousFootnote` / `nextEndnote` / `previousEndnote`

Parameters:

Name	Type	Default
`onSuccess`	`(ref: string) => void`

Returns:

Command

Parameters:

Name	Type	Default
`onSuccess`	`(ref: string) => void`

Returns:

Command

Parameters:

Name	Type	Default
`onSuccess`	`(ref: string) => void`

Returns:

Command

Parameters:

Name	Type	Default
`onSuccess`	`(ref: string) => void`

Returns:

Command

Helpers

`isCrossRefSelected`

Parameters:

Name	Type	Default
`state`	`EditorState`

Returns:

boolean

`getCrossRef`

Parameters:

Name	Type	Default
`state`	`EditorState`

Returns:

Node | null

`findCrossRefTargetWithPos`

Parameters:

Name	Type	Default
`doc`	`Node`
`targetId`	`string`

Returns:

NodeWithPos | undefined

`computeFullContext`

Parameters:

Name	Type	Default
`state`	`EditorState`
`listRef`	`string` List whose level configs format the path.
`path`	`string` Dot-separated counter path, e.g. `"1.2.3"`.
`language`	`string` BCP 47 tag for localized formats; falls back to en-GB.
`separator`	`string` Inserted between levels. Defaults to `""`.

Returns:

string

E.g. "1.2.a", or "" when nothing resolves.

`getAboveBelowText`

Parameters:

Name	Type	Default
`language`	`string` BCP 47 tag of the target; unknown languages fall back to English.
`isAbove`	`boolean` Whether the target precedes the reference.

Returns:

string

`findFootnotes` / `findEndnotes`

Parameters:

Name	Type	Default
`doc`	`Node`

Returns:

NodeWithPos | undefined

Parameters:

Name	Type	Default
`doc`	`Node`

Returns:

NodeWithPos | undefined

Also exported from @stesura/references/helpers: findFootnoteAnchor, findFootnoteBodyPos, findEndnoteBodyPos, the kind-generic findNoteAnchor / findNoteBodyPos / findNoteContainer, and isHeaderFooterRegion / isSkippedNoteRegion.

Note-panel store

Exported from the package root. Which note is open is tracked per editor and per kind ("footnote" | "endnote").

Export	Purpose
`openNotePanel(editorId, kind, ref, options?)`	Opens the panel on `ref` and closes the other kind’s. `{ focusOnOpen: false }` leaves focus where it is.
`closeNotePanel(editorId, kind)`	Closes the panel.
`activeNoteRefAtom(editorId, kind)`	Atom holding the open note’s ref, or `null`. Stable per editor and kind.
`noteFocusRequestAtom(editorId, kind)`	`{ id, focus }`, with a new `id` on every open and close. Consumed by `<FocusOnRequest>`.
`shouldFocusNoteOnOpen(editorId, kind)`	Whether the current open asked for focus.
`disposeNotePanelState(editorId, kind?)`	Releases an editor’s atoms. The panels call it on unmount.
`footnoteEditorRegistry` / `endnoteEditorRegistry`	Mounted note sub-editors.
`footnoteKind` / `endnoteKind`	Sub-editor kind configs, for `useSubEditor` in a custom panel.

@stesura/references

Plugins

referencesPlugins

notesPlugin

getFootnotes / getEndnotes

Commands

insertCrossReference

canInsertCrossReference

goToCrossRefTarget

insertFootnote

insertEndnote

deleteFootnote / deleteEndnote

navigateFootnote / navigateEndnote

nextFootnote / previousFootnote / nextEndnote / previousEndnote

Helpers

isCrossRefSelected

getCrossRef

findCrossRefTargetWithPos

computeFullContext

getAboveBelowText

findFootnotes / findEndnotes

Note-panel store

`@stesura/references`

`referencesPlugins`

`notesPlugin`

`getFootnotes` / `getEndnotes`

`insertCrossReference`

`canInsertCrossReference`

`goToCrossRefTarget`

`insertFootnote`

`insertEndnote`

`deleteFootnote` / `deleteEndnote`

`navigateFootnote` / `navigateEndnote`

`nextFootnote` / `previousFootnote` / `nextEndnote` / `previousEndnote`

`isCrossRefSelected`

`getCrossRef`

`findCrossRefTargetWithPos`

`computeFullContext`

`getAboveBelowText`

`findFootnotes` / `findEndnotes`