Files
Tom MoorandClaude f680d5dec9 feat: Display links, documents and collections as preview cards (#14511)
* feat: Display links as preview cards

Adds a display attribute to mentions so a link can render either inline
or as a card with image, title and description from its unfurl. Pasting
a URL offers a "Card" option, and selecting a link mention shows a
toolbar to switch between the two displays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016MJXFgeTUqKhSTriUHfG3z

* feat: Arrow key selection, full width and Return for link cards

Cards fill the document width, hide the blank line below them, are selected
by the up and down arrow keys like images, and Return on a selected card
adds a paragraph below it.

* feat: Display document and collection mentions as cards

Document and collection mentions can be switched to a card from the
selection toolbar. Document cards show the summary, collection and the
first image larger than 100x100. Collection cards show the first line of
the description. On public shares the preview image is signed, as the
share page already signs the attachments of that document. Card images
are hidden until they load and removed if they fail.

* feat: Keep mention cards through Markdown

The card display is written as the link title, so URLs are not changed.
Document and collection cards are written as @ links to their id and
parsed back into mentions.

* refactor: Move mention cards to their own file

Document cards show the collection after the title instead of below it.

* fix: Address review feedback on mention cards

- Include the share id in the document card unfurl URL for root shares.
- Return on a card in a heading adds a paragraph.
- URL cards keep their URL in Markdown, and the server does not narrow
  their type.
- Unfurl results apply to the current node, not the node at first render.
- Collection card descriptions stop at the first line break.

* refactor: Reuse existing helpers for mention cards

- Sign the preview image with TextHelper.attachmentsToSignedUrls.
- Check document and collection ids with isUUID.
- Return lines from getFirstText without changing an input array.

* fix: Preserve JSON output for inline mentions

* refactor: Centralize mention selection classes

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-11-08 08:11:31 -05:00

232 lines
7.8 KiB
TypeScript

import type MarkdownIt from "markdown-it";
import type StateCore from "markdown-it/lib/rules_core/state_core.mjs";
import type Token from "markdown-it/lib/token.mjs";
import { v4 as uuidv4 } from "uuid";
import isUUID from "validator/lib/isUUID";
import { MentionDisplay, MentionType } from "../../types";
import parseMentionUrl from "@shared/utils/parseMentionUrl";
import { sanitizeUrl } from "@shared/utils/urls";
/**
* Check whether a URL is a valid mention:// href.
*
* @param href the URL string to test.
* @returns true when the href is a recognised mention URL.
*/
function isMentionHref(href: string) {
const { mentionType, modelId } = parseMentionUrl(href);
return mentionType !== undefined && modelId !== undefined;
}
/**
* Parse an href that points at an external resource that can be represented as
* a mention.
*
* @param href the URL string to parse.
* @returns the parsed URL, or undefined when the href cannot be mentioned.
*/
function parseExternalHref(href: string): URL | undefined {
try {
const url = new URL(href);
return url.protocol === "http:" || url.protocol === "https:"
? url
: undefined;
} catch {
return undefined;
}
}
/** Matches the links that document and collection mentions are written as. */
const internalHrefRegex = /^\/(doc|collection)\/([^/#?]+)(?:#(.+))?$/;
/**
* Parse an href that points at a document or collection by id.
*
* @param href the URL string to parse.
* @returns the mention type, model id and anchor, or undefined when the href
* does not point at a document or collection by id.
*/
function parseInternalHref(
href: string
): { type: MentionType; modelId: string; anchorId?: string } | undefined {
const match = internalHrefRegex.exec(href);
if (!match) {
return undefined;
}
const [, kind, modelId, anchorId] = match;
if (!isUUID(modelId)) {
return undefined;
}
if (kind === "collection") {
return anchorId ? undefined : { type: MentionType.Collection, modelId };
}
return { type: MentionType.Document, modelId, anchorId };
}
/**
* Parse a mention:// href into the id, type and modelId needed by the editor.
* For 2-segment URLs (no instance id) a fresh UUID is generated.
*
* @param href the mention URL to parse.
* @returns the parsed components.
* @throws when the href is not a valid mention URL.
*/
function parseMentionHref(href: string): {
id: string;
type: string;
modelId: string;
} {
const { id, mentionType, modelId } = parseMentionUrl(href);
if (!mentionType || !modelId) {
throw new Error(`Invalid mention href: ${href}`);
}
return { id: id ?? uuidv4(), type: mentionType, modelId };
}
const renderMention = (md: MarkdownIt) => (tokens: Token[], idx: number) => {
// The label and attributes originate in the document, and markdown-it leaves
// any markup in them intact when `html` is disabled, so everything written
// into the tag is escaped here.
const esc = (value: string | null) => md.utils.escapeHtml(value ?? "");
const id = esc(tokens[idx].attrGet("id"));
const mType = esc(tokens[idx].attrGet("type"));
const mId = esc(tokens[idx].attrGet("modelId"));
const href = tokens[idx].attrGet("href");
const label = esc(tokens[idx].content);
const display =
tokens[idx].attrGet("display") === MentionDisplay.Card
? ` data-display="${MentionDisplay.Card}"`
: "";
return href
? `<a id="${id}" class="mention" href="${esc(sanitizeUrl(href) ?? "")}" data-type="${mType}" data-id="${mId}"${display}>${label}</a>`
: `<span id="${id}" class="mention" data-type="${mType}" data-id="${mId}"${display}>${label}</span>`;
};
function parseMentions(state: StateCore) {
for (let i = 0; i < state.tokens.length; i++) {
const tok = state.tokens[i];
if (!(tok.type === "inline" && tok.children)) {
continue;
}
const canChunkComposeMentionToken = (chunk: Token[]) => {
// no group of tokens of size less than 4 can compose a mention token
if (chunk.length < 4) {
return false;
}
const [precToken, openToken, textToken, closeToken] = chunk;
// check for the valid order of tokens required to compose a mention token
if (
!(
precToken.type === "text" &&
precToken.content &&
precToken.content.endsWith("@") &&
openToken.type === "link_open" &&
textToken.content &&
closeToken.type === "link_close"
)
) {
return false;
}
// "link_open" token should have a mention:// href, or an external href
// that can be represented as a mention.
const attr = openToken.attrs?.[0];
if (
!(
attr &&
attr[0] === "href" &&
(isMentionHref(attr[1]) ||
parseExternalHref(attr[1]) ||
parseInternalHref(attr[1]))
)
) {
return false;
}
// can probably compose a mention token if arrived here
return true;
};
const chunkWithMentionToken = (chunk: Token[]) => {
const [precToken, openToken, textToken] = chunk;
// remove "@" from preceding token
precToken.content = precToken.content.slice(0, -1);
// href must be present, otherwise the href test would've failed
const href = openToken.attrs![0][1];
const mentionToken = new state.Token("mention", "", 0);
const isMention = isMentionHref(href);
const internal = isMention ? undefined : parseInternalHref(href);
const externalUrl =
isMention || internal ? undefined : parseExternalHref(href);
if (internal) {
mentionToken.attrSet("id", uuidv4());
mentionToken.attrSet("type", internal.type);
mentionToken.attrSet("modelId", internal.modelId);
if (internal.anchorId) {
mentionToken.attrSet("anchorId", internal.anchorId);
}
} else if (externalUrl) {
// External links carry their identity in the href, so the ids are
// generated the same way a paste in the editor would. The mention is
// generic here and is narrowed to the resource it points at by the
// service that recognizes the URL.
mentionToken.attrSet("id", uuidv4());
mentionToken.attrSet("type", MentionType.URL);
mentionToken.attrSet("modelId", uuidv4());
mentionToken.attrSet("href", href);
} else {
const { id, type: mType, modelId: mId } = parseMentionHref(href);
mentionToken.attrSet("id", id);
mentionToken.attrSet("type", mType);
mentionToken.attrSet("modelId", mId);
}
mentionToken.content = textToken.content;
// The link title stores the display, so the URL is not changed.
if (openToken.attrGet("title") === MentionDisplay.Card) {
mentionToken.attrSet("display", MentionDisplay.Card);
}
// "link_open", followed by "text" and "link_close" tokens are coalesced
// into "mention" token, hence removed
return [precToken, mentionToken];
};
let newChildren: Token[] = [];
let j = 0;
while (j < tok.children.length) {
// attempt to grab next four tokens that could potentially construct a mention token
const chunk = tok.children.slice(j, j + 4);
if (canChunkComposeMentionToken(chunk)) {
newChildren = newChildren.concat(chunkWithMentionToken(chunk));
// skip by 4 since mention token for this group of tokens has been composed
// and the group cannot compose mention tokens any further
j += 4;
} else {
// push the tokens which do not participate in composing a mention token as it is
newChildren.push(tok.children[j]);
j++;
}
}
state.tokens[i].children = newChildren;
}
}
export default function mention(md: MarkdownIt) {
md.renderer.rules.mention = renderMention(md);
md.core.ruler.after("inline", "mention", parseMentions);
}