feat(editor): add experimental feature citation (#11984)

Closes: [BS-3122](https://linear.app/affine-design/issue/BS-3122/footnote-definition-adapter-适配) Closes: [BS-3123](https://linear.app/affine-design/issue/BS-3123/几个-block-card-view-适配-footnote-态)  ## Summary by CodeRabbit - **New Features** - Introduced a new citation card component and web element for displaying citations. - Added support for citation-style rendering in attachment, bookmark, and linked document blocks. - Enabled citation parsing from footnote definitions in markdown for attachments, bookmarks, and linked docs. - Added a feature flag to enable or disable citation features. - Provided new toolbar logic to disable downloads for citation-style attachments. - **Improvements** - Updated block models and properties to support citation identifiers. - Added localization and settings for the citation experimental feature. - Enhanced markdown adapters to recognize and process citation footnotes. - Included new constants and styles for citation card display. - **Bug Fixes** - Ensured readonly state is respected in block interactions and rendering for citation blocks. - **Documentation** - Added exports and effects for new citation components and features. - **Tests** - Updated snapshots to include citation-related properties in block data.
2026-02-15 05:37:32 +00:00 · 2025-04-29 06:59:27 +00:00
parent a326eac1bb
commit 83670ab335
58 changed files with 832 additions and 151 deletions
--- a/blocksuite/affine/blocks/embed/src/embed-linked-doc-block/adapters/markdown.ts
+++ b/blocksuite/affine/blocks/embed/src/embed-linked-doc-block/adapters/markdown.ts
@@ -1,16 +1,91 @@
-import { EmbedLinkedDocBlockSchema } from '@blocksuite/affine-model';
+import {
+  EmbedLinkedDocBlockSchema,
+  FootNoteReferenceParamsSchema,
+} from '@blocksuite/affine-model';
 import {
  AdapterTextUtils,
  BlockMarkdownAdapterExtension,
  type BlockMarkdownAdapterMatcher,
+  FOOTNOTE_DEFINITION_PREFIX,
+  getFootnoteDefinitionText,
+  isFootnoteDefinitionNode,
+  type MarkdownAST,
 } from '@blocksuite/affine-shared/adapters';
+import { FeatureFlagService } from '@blocksuite/affine-shared/services';
+import { nanoid } from '@blocksuite/store';
+
+const isLinkedDocFootnoteDefinitionNode = (node: MarkdownAST) => {
+  if (!isFootnoteDefinitionNode(node)) return false;
+  const footnoteDefinition = getFootnoteDefinitionText(node);
+  try {
+    const footnoteDefinitionJson = FootNoteReferenceParamsSchema.parse(
+      JSON.parse(footnoteDefinition)
+    );
+    return (
+      footnoteDefinitionJson.type === 'doc' && !!footnoteDefinitionJson.docId
+    );
+  } catch {
+    return false;
+  }
+};

 export const embedLinkedDocBlockMarkdownAdapterMatcher: BlockMarkdownAdapterMatcher =
  {
    flavour: EmbedLinkedDocBlockSchema.model.flavour,
-    toMatch: () => false,
+    toMatch: o => isLinkedDocFootnoteDefinitionNode(o.node),
    fromMatch: o => o.node.flavour === EmbedLinkedDocBlockSchema.model.flavour,
-    toBlockSnapshot: {},
+    toBlockSnapshot: {
+      enter: (o, context) => {
+        const { provider } = context;
+        let enableCitation = false;
+        try {
+          const featureFlagService = provider?.get(FeatureFlagService);
+          enableCitation = !!featureFlagService?.getFlag('enable_citation');
+        } catch {
+          enableCitation = false;
+        }
+        if (!isFootnoteDefinitionNode(o.node) || !enableCitation) {
+          return;
+        }
+
+        const { walkerContext, configs } = context;
+        const footnoteIdentifier = o.node.identifier;
+        const footnoteDefinitionKey = `${FOOTNOTE_DEFINITION_PREFIX}${footnoteIdentifier}`;
+        const footnoteDefinition = configs.get(footnoteDefinitionKey);
+        if (!footnoteDefinition) {
+          return;
+        }
+        try {
+          const footnoteDefinitionJson = FootNoteReferenceParamsSchema.parse(
+            JSON.parse(footnoteDefinition)
+          );
+          const { docId } = footnoteDefinitionJson;
+          if (!docId) {
+            return;
+          }
+          walkerContext
+            .openNode(
+              {
+                type: 'block',
+                id: nanoid(),
+                flavour: EmbedLinkedDocBlockSchema.model.flavour,
+                props: {
+                  pageId: docId,
+                  footnoteIdentifier,
+                  style: 'citation',
+                },
+                children: [],
+              },
+              'children'
+            )
+            .closeNode();
+          walkerContext.skipAllChildren();
+        } catch (err) {
+          console.warn('Failed to parse linked doc footnote definition:', err);
+          return;
+        }
+      },
+    },
    fromBlockSnapshot: {
      enter: (o, context) => {
        const { configs, walkerContext } = context;
--- a/blocksuite/affine/blocks/embed/src/embed-linked-doc-block/embed-edgeless-linked-doc-block.ts
+++ b/blocksuite/affine/blocks/embed/src/embed-linked-doc-block/embed-edgeless-linked-doc-block.ts
@@ -53,11 +53,11 @@ export class EmbedEdgelessLinkedDocBlockComponent extends toEdgelessEmbedBlock(
    doc.deleteBlock(this.model);
  };

-  protected override _handleClick(evt: MouseEvent): void {
+  protected override _handleClick = (evt: MouseEvent): void => {
    if (isNewTabTrigger(evt)) {
      this.open({ openMode: 'open-in-new-tab', event: evt });
    } else if (isNewViewTrigger(evt)) {
      this.open({ openMode: 'open-in-new-view', event: evt });
    }
-  }
+  };
 }
--- a/blocksuite/affine/blocks/embed/src/embed-linked-doc-block/embed-linked-doc-block.ts
+++ b/blocksuite/affine/blocks/embed/src/embed-linked-doc-block/embed-linked-doc-block.ts
@@ -55,6 +55,11 @@ export class EmbedLinkedDocBlockComponent extends EmbedBlockComponent<EmbedLinke
  static override styles = styles;

  private readonly _load = async () => {
+    // If this is a citation linked doc block, we don't need to load the linked doc and render linked doc content in card
+    if (this.isCitation) {
+      return;
+    }
+
    const {
      loading = true,
      isError = false,
@@ -243,6 +248,17 @@ export class EmbedLinkedDocBlockComponent extends EmbedBlockComponent<EmbedLinke
    return doc?.getStore({ id: this.model.props.pageId });
  }

+  get readonly() {
+    return this.doc.readonly;
+  }
+
+  get isCitation() {
+    return (
+      !!this.model.props.footnoteIdentifier &&
+      this.model.props.style === 'citation'
+    );
+  }
+
  private _handleDoubleClick(event: MouseEvent) {
    event.stopPropagation();
    const openDocService = this.std.get(OpenDocExtensionIdentifier);
@@ -264,105 +280,42 @@ export class EmbedLinkedDocBlockComponent extends EmbedBlockComponent<EmbedLinke
    return !!linkedDoc && this.isNoteContentEmpty && this.isBannerEmpty;
  }

-  protected _handleClick(event: MouseEvent) {
+  protected _handleClick = (event: MouseEvent) => {
    if (isNewTabTrigger(event)) {
      this.open({ openMode: 'open-in-new-tab', event });
    } else if (isNewViewTrigger(event)) {
      this.open({ openMode: 'open-in-new-view', event });
    }
-    this._selectBlock();
-  }

-  override connectedCallback() {
-    super.connectedCallback();
-
-    this._cardStyle = this.model.props.style;
-    this._referenceToNode = referenceToNode(this.model.props);
-
-    this._load().catch(e => {
-      console.error(e);
-      this.isError = true;
-    });
-
-    const linkedDoc = this.linkedDoc;
-    if (linkedDoc) {
-      this.disposables.add(
-        linkedDoc.workspace.slots.docListUpdated.subscribe(() => {
-          this._load().catch(e => {
-            console.error(e);
-            this.isError = true;
-          });
-        })
-      );
-      // Should throttle the blockUpdated event to avoid too many re-renders
-      // Because the blockUpdated event is triggered too frequently at some cases
-      this.disposables.add(
-        linkedDoc.slots.blockUpdated.subscribe(
-          throttle(payload => {
-            if (
-              payload.type === 'update' &&
-              ['', 'caption', 'xywh'].includes(payload.props.key)
-            ) {
-              return;
-            }
-
-            if (payload.type === 'add' && payload.init) {
-              return;
-            }
-
-            this._load().catch(e => {
-              console.error(e);
-              this.isError = true;
-            });
-          }, RENDER_CARD_THROTTLE_MS)
-        )
-      );
-
-      this._setDocUpdatedAt();
-      this.disposables.add(
-        this.doc.workspace.slots.docListUpdated.subscribe(() => {
-          this._setDocUpdatedAt();
-        })
-      );
-
-      if (this._referenceToNode) {
-        this._linkedDocMode = this.model.props.params?.mode ?? 'page';
-      } else {
-        const docMode = this.std.get(DocModeProvider);
-        this._linkedDocMode = docMode.getPrimaryMode(this.model.props.pageId);
-        this.disposables.add(
-          docMode.onPrimaryModeChange(mode => {
-            this._linkedDocMode = mode;
-          }, this.model.props.pageId)
-        );
-      }
+    if (this.readonly) {
+      return;
    }
+    this._selectBlock();
+  };

-    this.disposables.add(
-      this.model.propsUpdated.subscribe(({ key }) => {
-        if (key === 'style') {
-          this._cardStyle = this.model.props.style;
-        }
-        if (key === 'pageId' || key === 'style') {
-          this._load().catch(e => {
-            console.error(e);
-            this.isError = true;
-          });
-        }
-      })
-    );
-  }
+  private readonly _renderCitationView = () => {
+    const { footnoteIdentifier } = this.model.props;
+    return html`<div
+      draggable="${this.blockDraggable ? 'true' : 'false'}"
+      class=${classMap({
+        'embed-block-container': true,
+        ...this.selectedStyle$?.value,
+      })}
+      style=${styleMap({
+        ...this.embedContainerStyle,
+      })}
+    >
+      <affine-citation-card
+        .icon=${this.icon$.value}
+        .citationTitle=${this.title$.value}
+        .citationIdentifier=${footnoteIdentifier}
+        .active=${this.selected$.value}
+        .onClickCallback=${this._handleClick}
+      ></affine-citation-card>
+    </div> `;
+  };

-  getInitialState(): {
-    loading?: boolean;
-    isError?: boolean;
-    isNoteContentEmpty?: boolean;
-    isBannerEmpty?: boolean;
-  } {
-    return {};
-  }
-
-  override renderBlock() {
+  private readonly _renderEmbedView = () => {
    const linkedDoc = this.linkedDoc;
    const isDeleted = !linkedDoc;
    const isLoading = this._loading;
@@ -502,9 +455,107 @@ export class EmbedLinkedDocBlockComponent extends EmbedBlockComponent<EmbedLinke
        </div>
      `
    );
+  };
+
+  override connectedCallback() {
+    super.connectedCallback();
+
+    this._cardStyle = this.model.props.style;
+    this._referenceToNode = referenceToNode(this.model.props);
+
+    this._load().catch(e => {
+      console.error(e);
+      this.isError = true;
+    });
+
+    const linkedDoc = this.linkedDoc;
+    if (linkedDoc) {
+      this.disposables.add(
+        linkedDoc.workspace.slots.docListUpdated.subscribe(() => {
+          this._load().catch(e => {
+            console.error(e);
+            this.isError = true;
+          });
+        })
+      );
+      // Should throttle the blockUpdated event to avoid too many re-renders
+      // Because the blockUpdated event is triggered too frequently at some cases
+      this.disposables.add(
+        linkedDoc.slots.blockUpdated.subscribe(
+          throttle(payload => {
+            if (
+              payload.type === 'update' &&
+              ['', 'caption', 'xywh'].includes(payload.props.key)
+            ) {
+              return;
+            }
+
+            if (payload.type === 'add' && payload.init) {
+              return;
+            }
+
+            this._load().catch(e => {
+              console.error(e);
+              this.isError = true;
+            });
+          }, RENDER_CARD_THROTTLE_MS)
+        )
+      );
+
+      this._setDocUpdatedAt();
+      this.disposables.add(
+        this.doc.workspace.slots.docListUpdated.subscribe(() => {
+          this._setDocUpdatedAt();
+        })
+      );
+
+      if (this._referenceToNode) {
+        this._linkedDocMode = this.model.props.params?.mode ?? 'page';
+      } else {
+        const docMode = this.std.get(DocModeProvider);
+        this._linkedDocMode = docMode.getPrimaryMode(this.model.props.pageId);
+        this.disposables.add(
+          docMode.onPrimaryModeChange(mode => {
+            this._linkedDocMode = mode;
+          }, this.model.props.pageId)
+        );
+      }
+    }
+
+    this.disposables.add(
+      this.model.propsUpdated.subscribe(({ key }) => {
+        if (key === 'style') {
+          this._cardStyle = this.model.props.style;
+        }
+        if (key === 'pageId' || key === 'style') {
+          this._load().catch(e => {
+            console.error(e);
+            this.isError = true;
+          });
+        }
+      })
+    );
+  }
+
+  getInitialState(): {
+    loading?: boolean;
+    isError?: boolean;
+    isNoteContentEmpty?: boolean;
+    isBannerEmpty?: boolean;
+  } {
+    return {};
+  }
+
+  override renderBlock() {
+    return this.isCitation
+      ? this._renderCitationView()
+      : this._renderEmbedView();
  }

  override updated() {
+    if (this.readonly) {
+      return;
+    }
    // update card style when linked doc deleted
    const linkedDoc = this.linkedDoc;
    const { xywh, style } = this.model.props;