Skip to Content
API Referencereferences-react

@stesura/references-react

React UI for footnotes, endnotes and cross-references. Most hosts only need referenceUiExtensions; the individual pieces are exported for hosts that build their own toolbar or layout.

See the references guide for how the feature behaves.

referenceUiExtensions

The whole feature as one UI extension: toolbar groups (References and View tabs), the cross-reference panel, context menu and preview, the anchor node views, and both note panels in the document overlay.

import { referenceUiExtensions } from '@stesura/references-react'
 
<StesuraEditor uiExtensions={[referenceUiExtensions]} />

The references feature as one UI extension: toolbar groups, the cross-reference panel and menus, the anchor node views, and both note panels in the document overlay.

NameTypeDefault
leftPanelsLeftPanelElement[]
rightPanelsRightPanelElement[]
bottomPanelsBottomPanelElement[]
contextMenuExtensionsContextMenuExtension[]
textMenuExtensionsTextMenuExtension<string>[]
toolbarDefaultTabsPartial<Record<ToolbarDefaultTabs, false>>
toolbarDefaultExtensionsToolbarDefaultExtension[]
toolbarGroupExtensionsToolbarGroupExtension[]
toolbarTabsToolbarExtensionTab[]

Whole tabs after the built-in ones, usually contextual.

floatingMenuExtensionsFloatingMenuExtension[]
slashMenuExtensionsMenuElement[]
StatusBarElementsStatusBarElement[]
nodeViewsNodeViews
nodeViewWrappersRecord<string, ComponentType<NodeViewWrapperComponentProps>>

DOM-less wrappers composed around whichever view wins for a node type. A wrapper must render {children} (the wrapped view) and add no DOM; it contributes via context, typically NodeViewSlotsProvider. Unlike a nodeViews entry, it survives the consumer’s nodeViews overrides.

nodeViewFallback(type: NodeType) => NodeView | undefined

The view for a block type core doesn’t define and nothing registered a view for by name (a host schema’s own node), or undefined to pass. The last extension answering wins; otherwise editor-react renders the type’s toDOM with its derived values and slots (DerivedSpecView).

nodeViewWrapperFallback(type: NodeType) => ComponentType<NodeViewWrapperComponentProps> | undefined

A nodeViewWrappers entry for a block type core doesn’t define, when this extension names no wrapper for it. Composed around whichever view wins, the host’s own included, so a host node gets the extension’s behaviour (pagination’s page-break lead) without being listed.

pdfPreviewPdfPreviewCapability

Renders PDF file nodes as page previews (@stesura/pdf-viewer-react). Declared on the extension rather than set from an effect so the file view, pagination and export know it before the first layout; an effect arrives a commit late and forced a second pagination pass.

calloutFrameComponentType<CalloutFrameProps>

Replaces the callout title bar’s content (icon + title). Rendered inside the non-editable bar above the body; pagination measures it as chrome, so give it padding, never margins.

documentOverlaySlotReact.ReactNode
ResizableLayoutBottomSlotReact.ReactNode
TopLeftSlotReact.ReactNode
CommentsSlotReact.ReactNode

Toolbar groups

For hand-built toolbars. Each renders a ready-made group of buttons; the buttons themselves stay internal.

ExportContents
FootnotesGroupInsert footnote, previous/next, open the panel
EndnotesGroupInsert endnote, previous/next, open the panel
CrossReferenceGroupOpen the cross-reference panel
OpenFootnotesGroupOpen the footnote panel (View tab)
OpenEndnotesGroupOpen the endnote panel (View tab)

Note panels

FootnotePanel and EndnotePanel take no props. Each renders the panel for its kind, plus the listener that opens it on a search match inside a note. Render them inside the editor (they read its context); they position themselves at the bottom of the nearest positioned ancestor.

referenceNodeViews

The footnote and endnote anchor node views, keyed by node name. Without them anchors fall back to the schema’s toDOM: they show their number but don’t open the panel.

Not exported separately

The cross-reference panel, its context-menu entries and the Ctrl/⌘ preview are only available through referenceUiExtensions.

Last updated on
referencestrack-changes