`@stesura/bibliography-react`

React UI for citations and bibliographies. Most hosts only need createBibliographyUiExtension; the pieces are exported for hosts that build their own toolbar, panels or dialogs. The plugins and commands are in @stesura/bibliography; setup and the adapter contract are in the citations guide.

UI extension


import { bibliographyPlugins } from '@stesura/bibliography'
import { createBibliographyUiExtension, withBundledStyles } from '@stesura/bibliography-react'
 
// One adapter for both: the plugin formats with it, the UI looks up and searches with it.
const adapter = withBundledStyles({ lookup, searchLibrary, enrich })
 
// Module scope: `uiExtensions` must be referentially stable.
const uiExtensions = [createBibliographyUiExtension({ adapter })]
const extraPlugins = () => [...bibliographyPlugins({ adapter })]

extraPlugins goes on the mount hook, uiExtensions on StesuraEditor.

`createBibliographyUiExtension`

The bibliography feature as one UI extension: the references-tab group, the sources panel, the citation and bibliography menus and node views, and the picker and source dialogs in the document overlay.

Parameters:

Name	Type	Default
`__0`	`BibliographyUiOptions`

Returns:

StesuraUIExtension

`BibliographyUiOptions`

Options for createBibliographyUiExtension.

Name	Type	Default
`adapter`	`Partial<BibliographyAdapter>` The same adapter as `bibliographyPlugins`; missing optional methods hide their affordances.
`fieldWidgets`	`Partial<Record<FieldKind, ComponentType<FieldWidgetProps>>>` Field widgets by kind for the source dialog, over the defaults.

`withBundledStyles`

The host’s adapter over the bundled styles and locales: what the host leaves out of the formatting half falls back to APA, MLA, Chicago, IEEE, Harvard and Vancouver. Pass the same object to bibliographyPlugins.

Parameters:

Name	Type	Default
`adapter`	`Partial<BibliographyAdapter>`

Returns:

BibliographyAdapter

`bibliographyNodeViews`

The citation and bibliography node views, keyed by node name, for wiring by hand. The UI extension already registers them. Without them both nodes fall back to the schema’s toDOM, which shows the cached text without the retraction warning or the click and keyboard behaviour.

Placing the pieces yourself

Each piece reads the adapter from BibliographyAdapterProvider, so wrap them in one. The dialogs are mounted once per root editor and opened through useCitationPicker and useSourceDialog.

Export	Contents
`BibliographyGroup`	References-tab group: insert a citation or a bibliography, open the sources panel
`SourcesPanel`	The document’s sources: usage, problems, signals, library updates, style, import
`BibliographyContextMenu`	Context menu entries for a selected citation or bibliography
`CitationPickerDialog`	The citation picker (library search, lookups, locators)
`SourceDialog`	The source form dialog; takes `widgets` to override field widgets
`SourceSignalsLoader`	Fetches `enrich` signals and library change reports; renders nothing

`BibliographyAdapterProvider`

Supplies the adapter to the bibliography components below it; createBibliographyUiExtension wraps its pieces in one.

Parameters:

Name	Type	Default
`__0`	`{ adapter: BibliographyAdapter; children: ReactNode; }`

Returns:

Element

`useBibliographyAdapter`

The host’s adapter. Optional methods it lacks hide their affordances.

Parameters:

This function does not accept any parameters.

Returns:

BibliographyAdapter

Hooks

`useDocBibliography`

The root document’s sources, style and locale (debounced). Stable while the attr is: bibliographyOf caches per attr object.

Parameters:

This function does not accept any parameters.

Returns:

BibliographyDocAttr

`useCitationPicker`

The root editor’s citation picker: request is what it’s open on (null when closed); open(view, { editPos?, asFootnote? }) inserts, or edits the citation at editPos. CitationPickerDialog renders it.

Parameters:

This function does not accept any parameters.

Returns:

{ request: PickerRequest | null; open: (view: EditorView, options?: { editPos?: number | null; asFootnote?: boolean; }) => void; close: () => void; }

`PickerRequest`

The citation picker, open on view: inserting, or editing the citation at editPos. editNode is that citation when the picker opened: the doc may change while it’s open, so submit re-finds the node rather than trusting the pos.

Name	Type	Default
`view`	`EditorView`
`editPos`	`number \| null`
`editNode`	`Node \| null`
`asFootnote`	`boolean`

`useSourceDialog`

The root editor’s source dialog: open a new source (sourceId: null) or an existing one. SourceDialog renders it.

Parameters:

This function does not accept any parameters.

Returns:

{ request: SourceDialogRequest | null; open: (next: SourceDialogRequest) => void; close: () => void; }

`SourceDialogRequest`

The source dialog: a new source (sourceId null) or an existing one.

Name	Type	Default
`sourceId`	`string \| null`
`initial`	`Partial<BibliographySource>` Prefills a new source (a lookup result).
`paste`	`string` Seeds a new source’s “Paste a reference” box (text dropped on the panel).
`onSaved`	`(sourceId: string) => void` Called with the saved source’s id.

`useSourceSignals`

The adapter’s enrich signals for a DOI (retraction, corrections, counts), once SourceSignalsLoader has fetched them.

Parameters:

Name	Type	Default
`doi`	`unknown`

Returns:

SourceSignals | undefined

Headless source form

For hosts building their own source dialog: useSourceForm loads the Zotero-derived field layout for the chosen type and validates the draft as it changes.

`useSourceForm`

The state behind the source dialog, without the dialog: the type’s field layout from the Zotero schema (lazy-loaded), the draft, contributor rows and inline validation. Hosts building their own form use this directly.

Parameters:

Name	Type	Default
`__0`	`{ initial?: SourceDraft; locale: string; }`

Returns:

{ ready: boolean; loadError: boolean; retryLoad: () => void; labels: ZoteroLabels | null; layout: FormLayout | null; types: { type: CslItemType; label: string; }[]; ... 20 more ...; toSource: (id: string) => BibliographySource | null; }

`SourceForm`

What useSourceForm returns.

Name	Type	Default
`ready`	`boolean`
`loadError`	`boolean` The schema or labels failed to load; `retryLoad` tries again.
`retryLoad`	`() => void`
`labels`	`ZoteroLabels \| null`
`layout`	`FormLayout \| null`
`types`	`{ type: CslItemType; label: string; }[]`
`draft`	`SourceDraft`
`setType`	`(type: CslItemType) => void`
`typeChosen`	`boolean` The user picked a type: a fill keeps it.
`setId`	`(id: string) => void`
`fill`	`(found: SourceDraft, { adoptType }?: { adoptType?: boolean; }) => string[]`
`attachments`	`SourceAttachment[]`
`addAttachment`	`(attachment: SourceAttachment) => void`
`removeAttachment`	`(index: number) => void`
`setField`	`(field: FormField, value: string \| number \| CslDate \| undefined) => void`
`creators`	`CreatorRow[]`
`addCreator`	`(role?: CslNameVariable \| undefined) => void`
`updateCreator`	`(index: number, patch: Partial<CreatorRow>) => void`
`removeCreator`	`(index: number) => void`
`moveCreator`	`(index: number, by: 1 \| -1) => void`
`problems`	`BibliographyProblem[]`
`problemsOf`	`(variable: string) => BibliographyProblem[]`
`revealProblems`	`() => void`
`isDirty`	`boolean`
`isUnverified`	`(variable: string) => boolean`
`toDraft`	`() => SourceDraft`
`toSource`	`(id: string) => BibliographySource \| null`

`SourceDraft`

A draft: a source without its id until saved, id kept when editing.

Name	Type	Default
`number`	`string \| number`
`editor`	`CslName[]`
`type`	`CslItemType`
`title`	`string \| number`
`part`	`string \| number`
`section`	`string \| number`
`abstract`	`string \| number`
`annote`	`string \| number`
`archive`	`string \| number`
`archive_collection`	`string \| number`
`archive_location`	`string \| number`
`archive-place`	`string \| number`
`authority`	`string \| number`
`call-number`	`string \| number`
`chapter-number`	`string \| number`
`citation-key`	`string \| number`
`citation-label`	`string \| number`
`collection-number`	`string \| number`
`collection-title`	`string \| number`
`container-title`	`string \| number`
`container-title-short`	`string \| number`
`dimensions`	`string \| number`
`division`	`string \| number`
`DOI`	`string \| number`
`edition`	`string \| number`
`event-place`	`string \| number`
`event-title`	`string \| number`
`genre`	`string \| number`
`ISBN`	`string \| number`
`ISSN`	`string \| number`
`issue`	`string \| number`
`jurisdiction`	`string \| number`
`keyword`	`string \| number`
`language`	`string \| number`
`license`	`string \| number`
`medium`	`string \| number`
`note`	`string \| number`
`number-of-pages`	`string \| number`
`number-of-volumes`	`string \| number`
`original-publisher`	`string \| number`
`original-publisher-place`	`string \| number`
`original-title`	`string \| number`
`page`	`string \| number`
`page-first`	`string \| number`
`part-title`	`string \| number`
`PMCID`	`string \| number`
`PMID`	`string \| number`
`printing`	`string \| number`
`publisher`	`string \| number`
`publisher-place`	`string \| number`
`references`	`string \| number`
`reviewed-genre`	`string \| number`
`reviewed-title`	`string \| number`
`scale`	`string \| number`
`source`	`string \| number`
`status`	`string \| number`
`supplement`	`string \| number`
`title-short`	`string \| number`
`URL`	`string \| number`
`version`	`string \| number`
`volume`	`string \| number`
`volume-title`	`string \| number`
`year-suffix`	`string \| number`
`author`	`CslName[]`
`chair`	`CslName[]`
`collection-editor`	`CslName[]`
`compiler`	`CslName[]`
`composer`	`CslName[]`
`container-author`	`CslName[]`
`contributor`	`CslName[]`
`curator`	`CslName[]`
`director`	`CslName[]`
`editorial-director`	`CslName[]`
`executive-producer`	`CslName[]`
`guest`	`CslName[]`
`host`	`CslName[]`
`illustrator`	`CslName[]`
`interviewer`	`CslName[]`
`narrator`	`CslName[]`
`organizer`	`CslName[]`
`original-author`	`CslName[]`
`performer`	`CslName[]`
`producer`	`CslName[]`
`recipient`	`CslName[]`
`reviewed-author`	`CslName[]`
`script-writer`	`CslName[]`
`series-creator`	`CslName[]`
`translator`	`CslName[]`
`accessed`	`CslDate`
`available-date`	`CslDate`
`event-date`	`CslDate`
`issued`	`CslDate`
`original-date`	`CslDate`
`submitted`	`CslDate`
`attachments`	`SourceAttachment[]`
`provenance`	`SourceProvenance`
`libraryRef`	`SourceLibraryRef`
`word`	`{ tag?: string; guid?: string; }` Word’s b:Tag and b:Guid, kept for lossless DOCX round-trip.
`id`	`string`

`CreatorRow`

A contributor row in the source form.

Name	Type	Default
`role`	`CslNameVariable`
`name`	`CslName`
`single`	`boolean` One field: an organisation or a mononym, kept as `literal`.

`FormLayout`

The source form for one CSL type, in Zotero’s field order.

Name	Type	Default
`zoteroType`	`string` The Zotero item type the layout follows, for its labels.
`fields`	`FormField[]`
`creatorRoles`	`{ role: CslNameVariable; zoteroCreatorType: string; }[]` Contributor roles the type offers, the primary one first.

`FormField`

One field of the source form: the CSL variable it fills and its Zotero counterpart.

Name	Type	Default
`kind`	`"date" \| "url" \| "text" \| "long" \| "identifier"`
`variable`	`CslStandardVariable \| CslDateVariable`
`zoteroField`	`string`

`FieldKind`


type FieldKind = "text" | "long" | "date" | "url" | "identifier"

What renders a field: the key into the field widget registry (defaultFieldWidgets, or fieldWidgets on createBibliographyUiExtension).

`defaultFieldWidgets`

Field widgets by kind. Override entries to change how a kind renders; the creators list and the type select are the dialog’s own.

Name	Type	Default
`date`	`ComponentType<FieldWidgetProps>`
`url`	`ComponentType<FieldWidgetProps>`
`text`	`ComponentType<FieldWidgetProps>`
`long`	`ComponentType<FieldWidgetProps>`
`identifier`	`ComponentType<FieldWidgetProps>`

`FieldWidgetProps`

What every field widget receives.

Name	Type	Default
`id`	`string`
`label`	`string`
`value`	`unknown`
`onChange`	`(value: string \| CslDate \| undefined) => void`
`problems`	`BibliographyProblem[]`
`unverified`	`boolean` A model filled it and nothing verified it.

`problemMessage`

A problem’s message in the UI language.

Parameters:

Name	Type	Default
`t`	`TranslationKeys`
`problem`	`BibliographyProblem`

Returns:

string