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-态)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## 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.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

blocksuite/affine/blocks/attachment/src/adapters/extension.ts

@@ -0,0 +1,9 @@
+import type { ExtensionType } from '@blocksuite/store';
+
+import { AttachmentBlockMarkdownAdapterExtension } from './markdown.js';
+import { AttachmentBlockNotionHtmlAdapterExtension } from './notion-html.js';
+
+export const AttachmentBlockAdapterExtensions: ExtensionType[] = [
+  AttachmentBlockNotionHtmlAdapterExtension,
+  AttachmentBlockMarkdownAdapterExtension,
+];

blocksuite/affine/blocks/attachment/src/adapters/index.ts

@@ -0,0 +1,2 @@
+export * from './markdown.js';
+export * from './notion-html.js';

blocksuite/affine/blocks/attachment/src/adapters/markdown.ts

@@ -0,0 +1,93 @@
+import {
+  AttachmentBlockSchema,
+  FootNoteReferenceParamsSchema,
+} from '@blocksuite/affine-model';
+import {
+  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 isAttachmentFootnoteDefinitionNode = (node: MarkdownAST) => {
+  if (!isFootnoteDefinitionNode(node)) return false;
+  const footnoteDefinition = getFootnoteDefinitionText(node);
+  try {
+    const footnoteDefinitionJson = FootNoteReferenceParamsSchema.parse(
+      JSON.parse(footnoteDefinition)
+    );
+    return (
+      footnoteDefinitionJson.type === 'attachment' &&
+      !!footnoteDefinitionJson.blobId
+    );
+  } catch {
+    return false;
+  }
+};
+
+export const attachmentBlockMarkdownAdapterMatcher: BlockMarkdownAdapterMatcher =
+  {
+    flavour: AttachmentBlockSchema.model.flavour,
+    toMatch: o => isAttachmentFootnoteDefinitionNode(o.node),
+    fromMatch: o => o.node.flavour === AttachmentBlockSchema.model.flavour,
+    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 { blobId, fileName } = footnoteDefinitionJson;
+          if (!blobId || !fileName) {
+            return;
+          }
+          walkerContext
+            .openNode(
+              {
+                type: 'block',
+                id: nanoid(),
+                flavour: AttachmentBlockSchema.model.flavour,
+                props: {
+                  name: fileName,
+                  sourceId: blobId,
+                  footnoteIdentifier,
+                },
+                children: [],
+              },
+              'children'
+            )
+            .closeNode();
+          walkerContext.skipAllChildren();
+        } catch (err) {
+          console.warn('Failed to parse attachment footnote definition:', err);
+          return;
+        }
+      },
+    },
+    fromBlockSnapshot: {},
+  };
+
+export const AttachmentBlockMarkdownAdapterExtension =
+  BlockMarkdownAdapterExtension(attachmentBlockMarkdownAdapterMatcher);

blocksuite/affine/blocks/attachment/src/attachment-block.ts

@@ -53,6 +53,10 @@ export class AttachmentBlockComponent extends CaptionedBlockComponent<Attachment
     return this.std.store.get(FileSizeLimitService).maxFileSize;
   }
 
+  get isCitation() {
+    return !!this.model.props.footnoteIdentifier;
+  }
+
   convertTo = () => {
     return this.std
       .get(AttachmentEmbedProvider)
@@ -147,7 +151,7 @@ export class AttachmentBlockComponent extends CaptionedBlockComponent<Attachment
       })
     );
 
-    if (!this.model.props.style) {
+    if (!this.model.props.style && !this.doc.readonly) {
       this.doc.withoutTransact(() => {
         this.doc.updateBlock(this.model, {
           style: AttachmentBlockStyles[1],
@@ -322,6 +326,18 @@ export class AttachmentBlockComponent extends CaptionedBlockComponent<Attachment
     );
   };
 
+  private readonly _renderCitation = () => {
+    const { name, footnoteIdentifier } = this.model.props;
+    const fileType = name.split('.').pop() ?? '';
+    const fileTypeIcon = getAttachmentFileIcon(fileType);
+    return html`<affine-citation-card
+      .icon=${fileTypeIcon}
+      .citationTitle=${name}
+      .citationIdentifier=${footnoteIdentifier}
+      .active=${this.selected$.value}
+    ></affine-citation-card>`;
+  };
+
   override renderBlock() {
     return html`
       <div
@@ -332,12 +348,17 @@ export class AttachmentBlockComponent extends CaptionedBlockComponent<Attachment
         style=${this.containerStyleMap}
       >
         ${when(
-          this.embedView,
+          this.isCitation,
+          () => this._renderCitation(),
           () =>
-            html`<div class="affine-attachment-embed-container">
-              ${this.embedView}
-            </div>`,
-          this.renderCard
+            when(
+              this.embedView,
+              () =>
+                html`<div class="affine-attachment-embed-container">
+                  ${this.embedView}
+                </div>`,
+              this.renderCard
+            )
         )}
       </div>
     `;

blocksuite/affine/blocks/attachment/src/attachment-spec.ts

@@ -4,7 +4,7 @@ import { BlockViewExtension, FlavourExtension } from '@blocksuite/std';
 import type { ExtensionType } from '@blocksuite/store';
 import { literal } from 'lit/static-html.js';
 
-import { AttachmentBlockNotionHtmlAdapterExtension } from './adapters/notion-html.js';
+import { AttachmentBlockAdapterExtensions } from './adapters/extension.js';
 import { AttachmentDropOption } from './attachment-service.js';
 import { attachmentSlashMenuConfig } from './configs/slash-menu.js';
 import { createBuiltinToolbarConfigExtension } from './configs/toolbar';
@@ -25,7 +25,7 @@ export const AttachmentBlockSpec: ExtensionType[] = [
   AttachmentDropOption,
   AttachmentEmbedConfigExtension(),
   AttachmentEmbedService,
-  AttachmentBlockNotionHtmlAdapterExtension,
+  AttachmentBlockAdapterExtensions,
   createBuiltinToolbarConfigExtension(flavour),
   SlashMenuConfigExtension(flavour, attachmentSlashMenuConfig),
 ].flat();

blocksuite/affine/blocks/attachment/src/configs/toolbar.ts

@@ -139,6 +139,12 @@ const downloadAction = {
     const block = ctx.getCurrentBlockByType(AttachmentBlockComponent);
     block?.download();
   },
+  when: ctx => {
+    const model = ctx.getCurrentModelByType(AttachmentBlockModel);
+    if (!model) return false;
+    // Current citation attachment block does not support download
+    return model.props.style !== 'citation' && !model.props.footnoteIdentifier;
+  },
 } as const satisfies ToolbarAction;
 
 const captionAction = {
@@ -331,7 +337,6 @@ const builtinSurfaceToolbarConfig = {
       id: 'e.caption',
     },
   ],
-
   when: ctx => ctx.getSurfaceModelsByType(AttachmentBlockModel).length === 1,
 } as const satisfies ToolbarModuleConfig;
 

blocksuite/affine/blocks/attachment/src/index.ts

@@ -1,4 +1,4 @@
-export * from './adapters/notion-html';
+export * from './adapters';
 export * from './attachment-block';
 export * from './attachment-service';
 export * from './attachment-spec';

blocksuite/affine/blocks/attachment/src/store.ts

@@ -4,7 +4,7 @@ import {
 } from '@blocksuite/affine-ext-loader';
 import { AttachmentBlockSchemaExtension } from '@blocksuite/affine-model';
 
-import { AttachmentBlockNotionHtmlAdapterExtension } from './adapters/notion-html';
+import { AttachmentBlockAdapterExtensions } from './adapters/extension';
 
 export class AttachmentStoreExtension extends StoreExtensionProvider {
   override name = 'affine-attachment-block';
@@ -12,6 +12,6 @@ export class AttachmentStoreExtension extends StoreExtensionProvider {
   override setup(context: StoreExtensionContext) {
     super.setup(context);
     context.register(AttachmentBlockSchemaExtension);
-    context.register(AttachmentBlockNotionHtmlAdapterExtension);
+    context.register(AttachmentBlockAdapterExtensions);
   }
 }