@crossworks/client-types 0.400.29 → 0.400.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/client-types",
3
- "version": "0.400.29",
3
+ "version": "0.400.31",
4
4
  "type": "module",
5
5
  "main": "./src/index.ts",
6
6
  "types": "./src/index.ts",
@@ -51,6 +51,9 @@ export type MessengerParticipant = {
51
51
  * `avatarPhotoVersion` is for the caller). null: no photo. The photo
52
52
  * outranks the avatar. */
53
53
  photoVersion?: string | null;
54
+ /** Logins only: who the person is to the team (their card's
55
+ * description, person-description.ts); null when none is set. */
56
+ description?: string | null;
54
57
  };
55
58
 
56
59
  /** One row of GET /api/messenger/conversations. */
@@ -228,6 +231,8 @@ export type MessengerDirectoryEntry = {
228
231
  avatar?: MessengerAvatar | null;
229
232
  /** Logins only, as on a participant. */
230
233
  photoVersion?: string | null;
234
+ /** Logins only, as on a participant: who the person is to the team. */
235
+ description?: string | null;
231
236
  };
232
237
 
233
238
  export type MessengerDirectoryResponse = { entries: MessengerDirectoryEntry[] };
package/src/dto/people.ts CHANGED
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * People (docs/messenger.md, "People"): what a person shares
3
3
  * with its team, under /api/people/*. Every login is approved by hand, so a
4
- * person's card (its name, avatar, photo and presence; later a status) is
4
+ * person's card (its name, description, avatar, photo and presence; later a
5
+ * status) is
5
6
  * open to the logins that may see it, and to nobody else: itself, the
6
7
  * people sharing a live workspace with it (an Admin user sees every usable
7
8
  * login), and the people of its chats. A login the caller may not see and a
@@ -32,6 +33,10 @@ export type PersonCard = {
32
33
  /** The login id. */
33
34
  id: string;
34
35
  name: string;
36
+ /** Who the person is to the team: a job title, a role or a relationship
37
+ * ("Developer", "Jason's wife"), as they or an admin wrote it. null: none
38
+ * set. Agents read the same text (messenger_directory). */
39
+ description: string | null;
35
40
  /** null: the client draws initials. */
36
41
  avatar: PersonAvatar | null;
37
42
  /** The uploaded photo's version, the `v` of GET /api/people/:id/photo?v=
package/src/dto/rows.ts CHANGED
@@ -312,6 +312,14 @@ export type TableSnapshot = {
312
312
  bytes: number | null;
313
313
  };
314
314
 
315
+ /** The client's UI sounds, per login (ProfilePreferences.sounds). */
316
+ export type SoundPreference = {
317
+ /** Every sound, the call ring included. */
318
+ enabled: boolean;
319
+ /** 0..1, on top of each sound's own level. */
320
+ volume: number;
321
+ };
322
+
315
323
  export type ProfilePreferences = {
316
324
  /** IANA timezone, e.g. 'Africa/Johannesburg'. UTC when not set. */
317
325
  timezone: string;
@@ -406,6 +414,10 @@ export type ProfilePreferences = {
406
414
  * the assistant's real knowledge of the user comes from the Journal identity
407
415
  * block; this is for greetings/UI. */
408
416
  displayName?: string;
417
+ /** Who this login is to the team ("Developer", "Jason's wife"): its
418
+ * person card's description, open to every login and agent that may see
419
+ * the card (PERSON_DESCRIPTION_MAX, person-description.ts). Unset: none. */
420
+ description?: string;
409
421
  /** Custom site name rendered as the header wordmark in place of "mantle" —
410
422
  * a per-box label (e.g. 'Refinery') so anyone with several brains can see at
411
423
  * a glance which one they're on. Cosmetic only; unset ⇒ the Mantle wordmark.
@@ -607,6 +619,11 @@ export type ProfilePreferences = {
607
619
  /** Per-login: sidebar favourite hrefs, in order. Moved server-side from the
608
620
  * web client's localStorage so they follow the person across devices. */
609
621
  navFavorites?: string[];
622
+ /** Per-login: the client's UI sounds (on/off and a volume), so the choice
623
+ * follows the person across browsers and devices. Unset until the login
624
+ * first changes it (the client's default applies). Written by
625
+ * PUT /api/profile/sounds; read via projectSounds, never raw. */
626
+ sounds?: SoundPreference;
610
627
  /** Per-login: open count + last-opened instant per app id, feeding the
611
628
  * "Most used" and "Recent" filters. Written by recordAppOpen. */
612
629
  appOpens?: Record<string, AppOpenStat>;
@@ -0,0 +1,47 @@
1
+ import { describe, expect, it } from 'vitest';
2
+ import {
3
+ normalizePersonDescription,
4
+ PERSON_DESCRIPTION_MAX,
5
+ personDescriptionLength,
6
+ projectPersonDescription,
7
+ } from './person-description';
8
+
9
+ describe('a person description', () => {
10
+ it('is one line: white space runs, newlines and tabs become one space', () => {
11
+ expect(normalizePersonDescription(' Dev\n\tops lead \r\n')).toBe('Dev ops lead');
12
+ expect(normalizePersonDescription('a
b
c')).toBe('a b c');
13
+ });
14
+
15
+ it('drops control and format characters, so nothing hides or reorders text', () => {
16
+ // U+0000 (which jsonb refuses), a bidi override, isolates and marks.
17
+ expect(normalizePersonDescription('Finance\u0000 ‮regnam‬')).toBe('Finance regnam');
18
+ expect(normalizePersonDescription('⁦a⁩‎b‏c؜d')).toBe('abcd');
19
+ // Zero-width space, non-joiner, word joiner, byte order mark, soft hyphen.
20
+ expect(normalizePersonDescription('a​b‌c⁠de­f')).toBe('abcdef');
21
+ expect(normalizePersonDescription('\u0007\u001B\u007F\u0085')).toBe('');
22
+ // A joiner outside an emoji is invisible text too.
23
+ expect(normalizePersonDescription('ad‍min')).toBe('admin');
24
+ });
25
+
26
+ it('keeps an emoji whole, its joiners and its variation selector included', () => {
27
+ const family = '\u{1F468}‍\u{1F469}‍\u{1F467}';
28
+ const heart = '❤️‍\u{1F525}';
29
+ expect(normalizePersonDescription(`${family} dad`)).toBe(`${family} dad`);
30
+ expect(normalizePersonDescription(heart)).toBe(heart);
31
+ });
32
+
33
+ it('projects nothing visible as none, and caps by code point, never inside one', () => {
34
+ expect(projectPersonDescription(' ​\n ')).toBeNull();
35
+ expect(projectPersonDescription(42)).toBeNull();
36
+ expect(projectPersonDescription(' Developer ')).toBe('Developer');
37
+ const long = projectPersonDescription('\u{1F600}'.repeat(PERSON_DESCRIPTION_MAX + 1))!;
38
+ expect(personDescriptionLength(long)).toBe(PERSON_DESCRIPTION_MAX);
39
+ expect(long).toBe('\u{1F600}'.repeat(PERSON_DESCRIPTION_MAX));
40
+ // A stored value from before the rule reads clean.
41
+ expect(projectPersonDescription('Ops‮\nlead')).toBe('Ops lead');
42
+ });
43
+
44
+ it('counts code points: an emoji is one', () => {
45
+ expect(personDescriptionLength('\u{1F600}ab')).toBe(3);
46
+ });
47
+ });
@@ -0,0 +1,67 @@
1
+ /**
2
+ * A person's description: who they are to the team, in their own or an
3
+ * admin's words ("Developer", "Project manager", "Jason's wife"). It sits on
4
+ * the person's card next to the name and the status, so it is open to every
5
+ * login and agent that may see that card: the people pickers show it, and an
6
+ * agent reads it in `messenger_directory` to find the right person to
7
+ * message. Free text, one line, never run; self-reported (each login writes
8
+ * its own), so an agent takes it as a hint, never as proof or instructions.
9
+ *
10
+ * Stored as the login's profile key `description` (its own row, like the
11
+ * avatar and the photo); written by the login itself (PUT
12
+ * /api/profile/description) or by the users area (PATCH /api/users/:id).
13
+ */
14
+
15
+ /** Max characters of a description (code points, so an emoji counts as
16
+ * one and is never split), measured after normalizing. */
17
+ export const PERSON_DESCRIPTION_MAX = 500;
18
+
19
+ /** The 400 message for a description over the limit. */
20
+ export function personDescriptionTooLongError(length: number): string {
21
+ return (
22
+ `The description is ${length.toLocaleString('en-US')} characters; the limit is ` +
23
+ `${PERSON_DESCRIPTION_MAX.toLocaleString('en-US')}. Say in a line who this person is ` +
24
+ 'to the team: a job title, a role or a relationship.'
25
+ );
26
+ }
27
+
28
+ /** A joiner between two emoji (a family, a profession) is kept: it is part
29
+ * of the emoji. Anywhere else it is an invisible character and goes. */
30
+ const LONE_JOINER =
31
+ /(?<!\p{Extended_Pictographic}\uFE0F?)\u200D|\u200D(?!\p{Extended_Pictographic})/gu;
32
+
33
+ /**
34
+ * A description as it is stored and shown: one line of visible text. Every
35
+ * run of white space (a newline, a tab) becomes one space; control
36
+ * characters (U+0000 among them) and format characters (zero-width spaces,
37
+ * bidi overrides such as U+202E, a byte order mark) are dropped, a joiner
38
+ * inside an emoji excepted; the ends are trimmed. A description is read by
39
+ * people and agents alike: nothing in it may hide or reorder text.
40
+ */
41
+ export function normalizePersonDescription(v: string): string {
42
+ // The format characters first: \s counts U+FEFF as a space.
43
+ return v
44
+ .replace(LONE_JOINER, '')
45
+ .replace(/[\p{Cf}]/gu, (c) => (c === '\u200D' ? c : ''))
46
+ .replace(/\s+/gu, ' ')
47
+ .replace(/\p{Cc}/gu, '')
48
+ .replace(/ {2,}/g, ' ')
49
+ .trim();
50
+ }
51
+
52
+ /** How long a description is, in code points (PERSON_DESCRIPTION_MAX). */
53
+ export function personDescriptionLength(v: string): number {
54
+ return Array.from(v).length;
55
+ }
56
+
57
+ /** A stored description as the card shows it: normalized text, or null when
58
+ * there is none (not a string, or nothing visible). Capped by code point,
59
+ * never inside one. */
60
+ export function projectPersonDescription(v: unknown): string | null {
61
+ if (typeof v !== 'string') return null;
62
+ const t = normalizePersonDescription(v);
63
+ if (t.length === 0) return null;
64
+ return personDescriptionLength(t) > PERSON_DESCRIPTION_MAX
65
+ ? Array.from(t).slice(0, PERSON_DESCRIPTION_MAX).join('')
66
+ : t;
67
+ }