Skip to content

Preview footnote definitions from references #127

Description

@Azganoth

Summary

Footnote references currently expose their editable [^label] source but provide no way to inspect the corresponding definition without finding it elsewhere in the document.

Allow a footnote reference to reveal an accessible, bounded preview of its resolved definition and provide an explicit way to navigate to that definition. Missing definitions should produce a clear missing-definition state rather than an empty or broken preview.

This issue covers preview and navigation only. It does not change the established rule that directly editing a reference label does not rename or modify definitions.

Expected behavior

  • A reference with a matching definition can reveal a delayed preview through pointer interaction.
  • The same preview is available through a keyboard-accessible interaction; it is not hover-only.
  • The preview presents a bounded, non-editable representation of the definition content and truncates its presentation when necessary without modifying the document.
  • A reference without a matching definition presents an explicit missing-definition state.
  • The user can navigate from the reference or preview to the matching definition, moving editor focus and selection to that definition.
  • Preview and navigation behavior do not prevent the reference's existing editable source-projection interaction.
  • Multiple references with the same label resolve to the same definition.
  • Showing, hiding, or navigating from the preview does not modify Markdown, dirty state, or undo history.
  • Directly editing [^label] continues to affect only the edited reference and does not silently rename related references or definitions.

Related context

Done when

  • Reference labels resolve against footnote definitions in the active ProseMirror document.
  • Existing definitions produce a bounded preview and unresolved labels produce an explicit missing-definition state.
  • The preview is available through both pointer and keyboard interaction.
  • An explicit navigation action focuses the matching definition without replacing the existing reference-editing gesture.
  • Opening, closing, and navigating from a preview preserve document content, dirty state, undo history, and source-projection behavior.
  • Focused tests cover resolved and missing definitions, repeated references, pointer and keyboard access, navigation, and source-projection compatibility.
  • The specification and Unreleased changelog describe the accepted interaction.

Notes

Interaction decision before Ready

A normal interaction with a footnote reference currently activates its editable source projection. The preview and navigation interaction must not take that gesture away.

Before moving this issue to Ready, decide:

  • which gesture performs navigation;
  • whether keyboard and pointer users reach the same control;
  • whether the preview contains an interactive navigation action.

If the preview contains a focusable navigation action, it should use popover semantics rather than presenting interactive content inside a semantic tooltip.

Out of scope

  • Renaming a definition and all of its references.
  • Inserting new references or definitions.
  • Redesigning the footnote-definition block.
  • Changing footnote serialization or source-projection behavior.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

FeatureNew feature or request

Projects

  • Status
    Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions