sciflow-reference-list (Web Component)

<sciflow-reference-list> renders a draggable, highlightable list of references. It is shipped by @sciflow/editor-start and registered when you import the bundle. No Lit knowledge is required—treat it like any other custom element: set properties, listen to events if needed.

Each reference must include id and rawReference. rawReference is the bibliography string — the full reference-list entry (not the short in-text citation). It can be any formatted bibliography string (including a handwritten entry) and may contain lightweight HTML such as <i> for italics. Set mimeType for non-CSL payloads; defaults to application/vnd.citationstyles.csl+json. Use application/vnd.openalex+json for OpenAlex or your own type if your integration understands it.

Naming in external systems

Some systems use a different field name for the bibliography string. OJS, for example, stores it as rawCitation — which in SciFlow terminology would be a raw citation (an in-text label like "(Author, 2024)"), not a reference-list entry. Map rawCitation → rawReference on import. See the OJS Integration Guide.

Usage

<sciflow-reference-list id="references"></sciflow-reference-list>

const referenceList = document.getElementById('references');
referenceList.references = latestReferences; // array of CSL-like objects
referenceList.highlight(['ref-1', 'ref-2']); // optional highlighted ids

Properties

• references: Array — list of references to render; supports rawReference, author, title, issued, etc. (id and rawReference are required; set mimeType for anything besides CSL JSON.)
• highlightedIds: string[] — IDs to highlight; can also be set via highlight(ids).
• cursorActive: boolean — when true, enables the Cite button on each row. Set this to true once the editor has an active cursor (e.g. on editor-selection-change), and reset it to false when a new document loads. See Cite button wiring.
• empty-text attribute — message when no references exist.

Drag payloads

Each item sets: - application/json: { type: 'reference', id, text, reference } - application/x-sciflow-reference: 'sidebar' - text/plain: "[id]" or the display text

Drop behavior in the editor

When you drag a reference into the editor, citation insertion supports two modes:

• Insert at caret/space: dropping into an empty insertion point creates a citation with default visible text (for example [reference-id]).
• Convert existing text: dropping onto existing text can convert that text into a citation while preserving what the reader sees.

For text conversion, the editor resolves the drop target as follows:

• If dropped inside (...), the full parenthesized expression is converted.
• If dropped inside [...], the full bracketed expression is converted.
• If dropped on plain prose (for example Muller in as seen in Muller 2022), only the word under the drop point is converted.

In all conversion cases:

• The dropped reference id is written to citation source metadata.
• The converted text remains the citation's visible content.
• Dropping another reference onto that citation appends metadata without rewriting the existing visible citation text.

Connecting to the editor

Listen to editor events and push data into the list:

const editor = document.querySelector('sciflow-editor');
const refList = document.querySelector('sciflow-reference-list');

editor.addEventListener('editor-change', (event) => {
  const { doc, references } = event.detail;
  refList.references = Array.isArray(references) ? references : collectReferencesFromDoc(doc);
});

editor.addEventListener('editor-selection-change', (event) => {
  const ids = extractCitationIds(event.detail); // derive citation ids from selection
  refList.highlight(ids);
});

This mirrors the demo wiring: editor-change updates the list contents, and editor-selection-change drives highlights.

Events

Event	When fired	detail
sciflow-insert-citation	User clicks the Cite button on a row	{ reference } — the full reference object

The event bubbles and is composed, so it crosses shadow DOM boundaries and can be caught on the host document.

Cite button wiring

Each reference row shows a Cite button that is enabled only when cursorActive is true. This prevents insertion into an unknown position.

The recommended wiring pattern using editor-selection-change and editor-ready:

const editor = document.querySelector('sciflow-editor');
const refList = document.querySelector('sciflow-reference-list');

// Enable the Cite button as soon as the editor has a cursor
editor.addEventListener('editor-selection-change', () => {
  refList.cursorActive = true;
});

// Reset when a new document loads (cursor position is no longer valid)
editor.addEventListener('editor-ready', () => {
  refList.cursorActive = false;
});

// Handle the button click
refList.addEventListener('sciflow-insert-citation', (event) => {
  const { reference } = event.detail;
  editor.commands?.commands?.insertCitation?.({
    items: [{ id: reference.id }],
    text: reference.rawReference,
  });
});

Ghost cursor

Because clicking a sidebar button would normally blur the editor (losing the cursor position), the Cite button calls event.preventDefault() on mousedown to keep editor focus alive. Pair this with ghostCursorFeature (exported from @sciflow/editor-start) so the user can always see where the citation will be inserted—even after they interact with the sidebar. See Reference Integration for setup details.

Styling

Basic styles are encapsulated; override with CSS variables in your host if desired.