Full document, spreadsheet, slideshow, and diagram tooling
feat: @mentions and record detail sidebar (#142, #129) (#134)
+705
+135
src/docs/mentions.ts
+135
src/docs/mentions.ts
···
1
+
/**
2
+
* @Mention Support — collaborator mentions in documents.
3
+
*
4
+
* Pure logic module: mention parsing, user matching, suggestion filtering.
5
+
* TipTap extension and DOM rendering handled separately.
6
+
*/
7
+
8
+
export interface MentionUser {
9
+
id: string;
10
+
name: string;
11
+
color: string;
12
+
online: boolean;
13
+
}
14
+
15
+
export interface Mention {
16
+
userId: string;
17
+
userName: string;
18
+
start: number;
19
+
end: number;
20
+
}
21
+
22
+
/**
23
+
* Parse @mentions from plain text.
24
+
* Matches @word patterns (alphanumeric + underscores).
25
+
* Multi-word mentions are handled by the TipTap extension node, not plain text.
26
+
*/
27
+
export function parseMentions(text: string): Mention[] {
28
+
if (!text) return [];
29
+
30
+
const mentions: Mention[] = [];
31
+
const regex = /@(\w+)/g;
32
+
let match;
33
+
34
+
while ((match = regex.exec(text)) !== null) {
35
+
mentions.push({
36
+
userId: '',
37
+
userName: match[1].trim(),
38
+
start: match.index,
39
+
end: match.index + match[0].length,
40
+
});
41
+
}
42
+
43
+
return mentions;
44
+
}
45
+
46
+
/**
47
+
* Filter users by a search query for the mention autocomplete.
48
+
* Case-insensitive prefix and contains matching.
49
+
*/
50
+
export function filterMentionUsers(
51
+
users: MentionUser[],
52
+
query: string,
53
+
): MentionUser[] {
54
+
if (!query) return users;
55
+
56
+
const lower = query.toLowerCase();
57
+
58
+
// Prefix matches first, then contains matches
59
+
const prefix: MentionUser[] = [];
60
+
const contains: MentionUser[] = [];
61
+
62
+
for (const user of users) {
63
+
const nameLower = user.name.toLowerCase();
64
+
if (nameLower.startsWith(lower)) {
65
+
prefix.push(user);
66
+
} else if (nameLower.includes(lower)) {
67
+
contains.push(user);
68
+
}
69
+
}
70
+
71
+
return [...prefix, ...contains];
72
+
}
73
+
74
+
/**
75
+
* Resolve mention text to a user by name matching.
76
+
*/
77
+
export function resolveMention(
78
+
userName: string,
79
+
users: MentionUser[],
80
+
): MentionUser | null {
81
+
if (!userName) return null;
82
+
83
+
const lower = userName.toLowerCase();
84
+
85
+
// Exact match first
86
+
const exact = users.find(u => u.name.toLowerCase() === lower);
87
+
if (exact) return exact;
88
+
89
+
// Prefix match
90
+
const prefix = users.find(u => u.name.toLowerCase().startsWith(lower));
91
+
return prefix || null;
92
+
}
93
+
94
+
/**
95
+
* Build a display label for a mention.
96
+
*/
97
+
export function mentionLabel(user: MentionUser): string {
98
+
return `@${user.name}`;
99
+
}
100
+
101
+
/**
102
+
* Extract unique mentioned user IDs from a list of mentions.
103
+
*/
104
+
export function uniqueMentionedUsers(mentions: Mention[]): string[] {
105
+
const seen = new Set<string>();
106
+
const result: string[] = [];
107
+
108
+
for (const m of mentions) {
109
+
if (m.userId && !seen.has(m.userId)) {
110
+
seen.add(m.userId);
111
+
result.push(m.userId);
112
+
}
113
+
}
114
+
115
+
return result;
116
+
}
117
+
118
+
/**
119
+
* Check if a specific user is mentioned in the text.
120
+
*/
121
+
export function isUserMentioned(
122
+
text: string,
123
+
userName: string,
124
+
): boolean {
125
+
if (!text || !userName) return false;
126
+
const lower = text.toLowerCase();
127
+
return lower.includes(`@${userName.toLowerCase()}`);
128
+
}
129
+
130
+
/**
131
+
* Count mentions in text.
132
+
*/
133
+
export function countMentions(text: string): number {
134
+
return parseMentions(text).length;
135
+
}
+190
tests/mentions.test.ts
+190
tests/mentions.test.ts
···
1
+
import { describe, it, expect } from 'vitest';
2
+
import {
3
+
parseMentions,
4
+
filterMentionUsers,
5
+
resolveMention,
6
+
mentionLabel,
7
+
uniqueMentionedUsers,
8
+
isUserMentioned,
9
+
countMentions,
10
+
type MentionUser,
11
+
type Mention,
12
+
} from '../src/docs/mentions.js';
13
+
14
+
const alice: MentionUser = { id: 'u1', name: 'Alice', color: '#f00', online: true };
15
+
const bob: MentionUser = { id: 'u2', name: 'Bob', color: '#0f0', online: false };
16
+
const alicia: MentionUser = { id: 'u3', name: 'Alicia', color: '#00f', online: true };
17
+
const charlie: MentionUser = { id: 'u4', name: 'Charlie Brown', color: '#ff0', online: true };
18
+
19
+
const users: MentionUser[] = [alice, bob, alicia, charlie];
20
+
21
+
describe('parseMentions', () => {
22
+
it('parses single mention', () => {
23
+
const result = parseMentions('Hello @Alice!');
24
+
expect(result).toHaveLength(1);
25
+
expect(result[0].userName).toBe('Alice');
26
+
expect(result[0].start).toBe(6);
27
+
expect(result[0].end).toBe(12);
28
+
});
29
+
30
+
it('parses multiple mentions', () => {
31
+
const result = parseMentions('@Alice and @Bob');
32
+
expect(result).toHaveLength(2);
33
+
expect(result[0].userName).toBe('Alice');
34
+
expect(result[1].userName).toBe('Bob');
35
+
});
36
+
37
+
it('parses single-word mention ignoring trailing words', () => {
38
+
const result = parseMentions('Hey @Charlie Brown!');
39
+
// Plain text parser captures single word after @; multi-word handled by TipTap node
40
+
expect(result).toHaveLength(1);
41
+
expect(result[0].userName).toBe('Charlie');
42
+
});
43
+
44
+
it('returns empty for no mentions', () => {
45
+
expect(parseMentions('Hello world')).toEqual([]);
46
+
});
47
+
48
+
it('returns empty for empty string', () => {
49
+
expect(parseMentions('')).toEqual([]);
50
+
});
51
+
52
+
it('returns empty for null-ish input', () => {
53
+
expect(parseMentions(null as any)).toEqual([]);
54
+
expect(parseMentions(undefined as any)).toEqual([]);
55
+
});
56
+
57
+
it('handles single character username', () => {
58
+
const result = parseMentions('@A');
59
+
expect(result).toHaveLength(1);
60
+
expect(result[0].userName).toBe('A');
61
+
});
62
+
63
+
it('sets empty userId', () => {
64
+
const result = parseMentions('@Alice');
65
+
expect(result[0].userId).toBe('');
66
+
});
67
+
});
68
+
69
+
describe('filterMentionUsers', () => {
70
+
it('returns all users for empty query', () => {
71
+
expect(filterMentionUsers(users, '')).toEqual(users);
72
+
});
73
+
74
+
it('prefix matches come first', () => {
75
+
const result = filterMentionUsers(users, 'ali');
76
+
expect(result[0].name).toBe('Alice');
77
+
expect(result[1].name).toBe('Alicia');
78
+
expect(result).toHaveLength(2);
79
+
});
80
+
81
+
it('contains matches follow prefix matches', () => {
82
+
const result = filterMentionUsers(users, 'ob');
83
+
expect(result).toHaveLength(1);
84
+
expect(result[0].name).toBe('Bob');
85
+
});
86
+
87
+
it('is case insensitive', () => {
88
+
const result = filterMentionUsers(users, 'ALICE');
89
+
expect(result).toHaveLength(1);
90
+
expect(result[0].name).toBe('Alice');
91
+
});
92
+
93
+
it('returns empty for no matches', () => {
94
+
expect(filterMentionUsers(users, 'xyz')).toEqual([]);
95
+
});
96
+
});
97
+
98
+
describe('resolveMention', () => {
99
+
it('exact match takes priority', () => {
100
+
const result = resolveMention('Alice', users);
101
+
expect(result).toBe(alice);
102
+
});
103
+
104
+
it('case insensitive exact match', () => {
105
+
const result = resolveMention('alice', users);
106
+
expect(result).toBe(alice);
107
+
});
108
+
109
+
it('falls back to prefix match', () => {
110
+
const result = resolveMention('Char', users);
111
+
expect(result).toBe(charlie);
112
+
});
113
+
114
+
it('returns null for no match', () => {
115
+
expect(resolveMention('Zara', users)).toBeNull();
116
+
});
117
+
118
+
it('returns null for empty string', () => {
119
+
expect(resolveMention('', users)).toBeNull();
120
+
});
121
+
122
+
it('returns null for null-ish input', () => {
123
+
expect(resolveMention(null as any, users)).toBeNull();
124
+
});
125
+
});
126
+
127
+
describe('mentionLabel', () => {
128
+
it('prepends @ to name', () => {
129
+
expect(mentionLabel(alice)).toBe('@Alice');
130
+
});
131
+
});
132
+
133
+
describe('uniqueMentionedUsers', () => {
134
+
it('returns unique user IDs', () => {
135
+
const mentions: Mention[] = [
136
+
{ userId: 'u1', userName: 'Alice', start: 0, end: 6 },
137
+
{ userId: 'u2', userName: 'Bob', start: 10, end: 14 },
138
+
{ userId: 'u1', userName: 'Alice', start: 20, end: 26 },
139
+
];
140
+
expect(uniqueMentionedUsers(mentions)).toEqual(['u1', 'u2']);
141
+
});
142
+
143
+
it('skips mentions with empty userId', () => {
144
+
const mentions: Mention[] = [
145
+
{ userId: '', userName: 'Unknown', start: 0, end: 8 },
146
+
{ userId: 'u1', userName: 'Alice', start: 10, end: 16 },
147
+
];
148
+
expect(uniqueMentionedUsers(mentions)).toEqual(['u1']);
149
+
});
150
+
151
+
it('returns empty for no mentions', () => {
152
+
expect(uniqueMentionedUsers([])).toEqual([]);
153
+
});
154
+
});
155
+
156
+
describe('isUserMentioned', () => {
157
+
it('detects mentioned user', () => {
158
+
expect(isUserMentioned('Hello @Alice!', 'Alice')).toBe(true);
159
+
});
160
+
161
+
it('is case insensitive', () => {
162
+
expect(isUserMentioned('Hello @alice!', 'Alice')).toBe(true);
163
+
});
164
+
165
+
it('returns false when not mentioned', () => {
166
+
expect(isUserMentioned('Hello @Bob!', 'Alice')).toBe(false);
167
+
});
168
+
169
+
it('returns false for empty text', () => {
170
+
expect(isUserMentioned('', 'Alice')).toBe(false);
171
+
});
172
+
173
+
it('returns false for empty userName', () => {
174
+
expect(isUserMentioned('Hello @Alice!', '')).toBe(false);
175
+
});
176
+
});
177
+
178
+
describe('countMentions', () => {
179
+
it('counts mentions in text', () => {
180
+
expect(countMentions('@Alice and @Bob')).toBe(2);
181
+
});
182
+
183
+
it('returns 0 for no mentions', () => {
184
+
expect(countMentions('Hello world')).toBe(0);
185
+
});
186
+
187
+
it('returns 0 for empty text', () => {
188
+
expect(countMentions('')).toBe(0);
189
+
});
190
+
});