@astryxdesign/lab 0.7.2-canary.59c4ef7 → 0.7.2-canary.5c208f6

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.
Files changed (53) hide show
  1. package/blocks/CommentComposerShowcase.doc.mjs +15 -0
  2. package/blocks/CommentComposerShowcase.tsx +45 -0
  3. package/blocks/CommentPinInMargin.doc.mjs +14 -0
  4. package/blocks/CommentPinInMargin.tsx +77 -0
  5. package/blocks/CommentPinShowcase.doc.mjs +15 -0
  6. package/blocks/CommentPinShowcase.tsx +188 -0
  7. package/dist/CommentPin/CommentPin.d.ts +86 -0
  8. package/dist/CommentPin/CommentPin.d.ts.map +1 -0
  9. package/dist/CommentPin/CommentPin.js +260 -0
  10. package/dist/CommentPin/index.d.ts +9 -0
  11. package/dist/CommentPin/index.d.ts.map +1 -0
  12. package/dist/CommentPin/index.js +11 -0
  13. package/dist/Comments/CommentComposer.d.ts +108 -0
  14. package/dist/Comments/CommentComposer.d.ts.map +1 -0
  15. package/dist/Comments/CommentComposer.js +507 -0
  16. package/dist/Comments/CommentMarkdown.d.ts +15 -0
  17. package/dist/Comments/CommentMarkdown.d.ts.map +1 -0
  18. package/dist/Comments/CommentMarkdown.js +136 -0
  19. package/dist/Comments/CommentParts.d.ts +54 -0
  20. package/dist/Comments/CommentParts.d.ts.map +1 -0
  21. package/dist/Comments/CommentParts.js +171 -0
  22. package/dist/Comments/icons.d.ts +15 -0
  23. package/dist/Comments/icons.d.ts.map +1 -0
  24. package/dist/Comments/icons.js +57 -0
  25. package/dist/Comments/index.d.ts +10 -0
  26. package/dist/Comments/index.d.ts.map +1 -0
  27. package/dist/Comments/index.js +11 -0
  28. package/dist/Comments/types.d.ts +73 -0
  29. package/dist/Comments/types.d.ts.map +1 -0
  30. package/dist/Comments/types.js +1 -0
  31. package/dist/Comments/utils.d.ts +18 -0
  32. package/dist/Comments/utils.d.ts.map +1 -0
  33. package/dist/Comments/utils.js +37 -0
  34. package/dist/index.d.ts +2 -0
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +6 -0
  37. package/dist/lab.css +45 -0
  38. package/package.json +4 -4
  39. package/src/CommentPin/CommentPin.doc.mjs +328 -0
  40. package/src/CommentPin/CommentPin.spec.md +307 -0
  41. package/src/CommentPin/CommentPin.test.tsx +350 -0
  42. package/src/CommentPin/CommentPin.tsx +484 -0
  43. package/src/CommentPin/index.ts +13 -0
  44. package/src/Comments/CommentComposer.doc.mjs +177 -0
  45. package/src/Comments/CommentComposer.test.tsx +255 -0
  46. package/src/Comments/CommentComposer.tsx +680 -0
  47. package/src/Comments/CommentMarkdown.tsx +184 -0
  48. package/src/Comments/CommentParts.tsx +164 -0
  49. package/src/Comments/icons.tsx +77 -0
  50. package/src/Comments/index.ts +22 -0
  51. package/src/Comments/types.ts +90 -0
  52. package/src/Comments/utils.ts +55 -0
  53. package/src/index.ts +20 -0
@@ -0,0 +1,15 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
4
+ export default {
5
+ type: 'block',
6
+ name: 'New comment',
7
+ displayName: 'New comment',
8
+ description:
9
+ 'A comment composer quoting the passage it comments on: type, add an emoji, and post with Enter or Post.',
10
+ exampleFor: 'CommentComposer',
11
+ isReady: true,
12
+ isShowcase: true,
13
+ aspectRatio: 16 / 9,
14
+ componentsUsed: ['CommentComposer', 'VStack', 'Text'],
15
+ };
@@ -0,0 +1,45 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ /**
6
+ * @input A controlled draft and a list of posted comments
7
+ * @output A comment composer that posts into a short list above it
8
+ * @position Lab CommentComposer's docsite showcase and copyable CLI block
9
+ */
10
+
11
+ import {useState} from 'react';
12
+ import {VStack} from '@astryxdesign/core/Layout';
13
+ import {Text} from '@astryxdesign/core/Text';
14
+ import {CommentComposer} from '@astryxdesign/lab';
15
+
16
+ export default function CommentComposerShowcase() {
17
+ const [draft, setDraft] = useState('');
18
+ const [posted, setPosted] = useState<string[]>([]);
19
+
20
+ return (
21
+ <VStack gap={3} width={420}>
22
+ {posted.length === 0 ? (
23
+ <Text type="supporting" color="secondary">
24
+ Nothing posted yet.
25
+ </Text>
26
+ ) : (
27
+ posted.map((body, index) => (
28
+ <Text key={index} type="body">
29
+ {body}
30
+ </Text>
31
+ ))
32
+ )}
33
+ <CommentComposer
34
+ value={draft}
35
+ onChange={setDraft}
36
+ onSubmit={body => {
37
+ setPosted(current => [...current, body]);
38
+ setDraft('');
39
+ }}
40
+ anchor={{quote: 'Guardrail alerts page the release oncall.'}}
41
+ onAnchorDismiss={() => {}}
42
+ />
43
+ </VStack>
44
+ );
45
+ }
@@ -0,0 +1,14 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
4
+ export default {
5
+ type: 'block',
6
+ name: 'Host-owned placement',
7
+ displayName: 'Comment pin in a document margin',
8
+ description:
9
+ 'A caller-positioned CommentPin in a document margin. The host maps its anchor to the pin’s logical bottom-start corner and owns the surrounding layout; the pin owns its compact interactive surface. Activating the pin toggles its selected state.',
10
+ exampleFor: 'CommentPin',
11
+ isReady: true,
12
+ aspectRatio: 16 / 9,
13
+ componentsUsed: ['Card', 'CommentPin', 'Text', 'VStack'],
14
+ };
@@ -0,0 +1,77 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ /**
6
+ * @input A host-positioned CommentPin, its lead commenter, and local
7
+ * selected state
8
+ * @output A document passage with one comment pin in its margin; activating
9
+ * the pin toggles its selection and aria-pressed state
10
+ * @position Copyable Lab CommentPin placement example
11
+ */
12
+
13
+ import {useState} from 'react';
14
+ import * as stylex from '@stylexjs/stylex';
15
+ import {Card} from '@astryxdesign/core/Card';
16
+ import {Text} from '@astryxdesign/core/Text';
17
+ import {VStack} from '@astryxdesign/core/Stack';
18
+ import {colorVars, spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
19
+ import {CommentPin} from '@astryxdesign/lab';
20
+
21
+ const styles = stylex.create({
22
+ document: {
23
+ display: 'grid',
24
+ gridTemplateColumns: 'minmax(0, 1fr) 64px',
25
+ minHeight: 220,
26
+ },
27
+ content: {
28
+ padding: spacingVars['--spacing-5'],
29
+ },
30
+ margin: {
31
+ position: 'relative',
32
+ borderInlineStartWidth: 1,
33
+ borderInlineStartStyle: 'solid',
34
+ borderInlineStartColor: colorVars['--color-border'],
35
+ backgroundColor: colorVars['--color-background-muted'],
36
+ },
37
+ // Inset far enough from the clipped Card edges that the selected ring and
38
+ // the farther-out keyboard focus outline stay fully visible.
39
+ pin: {
40
+ position: 'absolute',
41
+ insetInlineStart: spacingVars['--spacing-3'],
42
+ insetBlockStart: spacingVars['--spacing-10'],
43
+ transform: 'translateY(-100%)',
44
+ },
45
+ });
46
+
47
+ export default function CommentPinInMargin() {
48
+ const [isSelected, setIsSelected] = useState(false);
49
+ return (
50
+ <Card padding={0} width={520}>
51
+ <div {...stylex.props(styles.document)}>
52
+ <VStack gap={3} xstyle={styles.content}>
53
+ <Text as="h2" type="display-3" weight="bold">
54
+ Review notes
55
+ </Text>
56
+ <Text type="body">
57
+ The host owns the document anchor and margin layout. The pin stays a
58
+ compact action that identifies the lead commenter.
59
+ </Text>
60
+ <Text type="supporting" color="secondary">
61
+ Selecting the pin can open a thread beside this passage or in a
62
+ shared comments panel.
63
+ </Text>
64
+ </VStack>
65
+ <div aria-label="Comment margin" {...stylex.props(styles.margin)}>
66
+ <CommentPin
67
+ label="Open comment from Maya"
68
+ participants={[{id: 'maya', name: 'Maya Chen'}]}
69
+ isSelected={isSelected}
70
+ onClick={() => setIsSelected(current => !current)}
71
+ xstyle={styles.pin}
72
+ />
73
+ </div>
74
+ </div>
75
+ </Card>
76
+ );
77
+ }
@@ -0,0 +1,15 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
4
+ export default {
5
+ type: 'block',
6
+ name: 'Avatar-first annotations',
7
+ displayName: 'Avatar-first annotations',
8
+ description:
9
+ 'Caller-positioned comment pins over media and in a content margin. Every coordinate maps to the pin’s logical bottom-start corner. The selected group caps its participants at three circles (two Avatars plus +3) and shows its unread count in an accent badge instead of the total; the unread margin pin shows the badge too. Other pins dim without becoming disabled, activating the selected pin again clears the selection, and no pin dims while nothing is selected.',
10
+ exampleFor: 'CommentPin',
11
+ isReady: true,
12
+ isShowcase: true,
13
+ aspectRatio: 16 / 9,
14
+ componentsUsed: ['CommentPin', 'Text', 'VStack'],
15
+ };
@@ -0,0 +1,188 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ /**
6
+ * @input Three caller-positioned comment pins, logical bottom-start anchors,
7
+ * participant/thread/unread counts, and controlled selected/dimmed state
8
+ * that may be empty
9
+ * @output A grouped pin with a three-circle participant cap and an unread
10
+ * badge, a resolved pin, and an unread margin pin; activating the selected
11
+ * pin clears the selection, and non-selected pins dim only while another pin
12
+ * is selected
13
+ * @position CommentPin docsite showcase and copyable Lab block
14
+ */
15
+
16
+ import {useState} from 'react';
17
+ import * as stylex from '@stylexjs/stylex';
18
+ import {CommentPin} from '@astryxdesign/lab';
19
+ import {Text} from '@astryxdesign/core/Text';
20
+ import {VStack} from '@astryxdesign/core/Stack';
21
+ import {
22
+ colorVars,
23
+ radiusVars,
24
+ shadowVars,
25
+ spacingVars,
26
+ } from '@astryxdesign/core/theme/tokens.stylex';
27
+
28
+ const PEOPLE = {
29
+ ada: {
30
+ id: 'ada',
31
+ name: 'Ada Lovelace',
32
+ avatarSrc: 'https://i.pravatar.cc/80?img=47',
33
+ },
34
+ lin: {
35
+ id: 'lin',
36
+ name: 'Lin Chen',
37
+ avatarSrc: 'https://i.pravatar.cc/80?img=32',
38
+ },
39
+ mira: {
40
+ id: 'mira',
41
+ name: 'Mira Patel',
42
+ avatarSrc: 'https://i.pravatar.cc/80?img=5',
43
+ },
44
+ noah: {
45
+ id: 'noah',
46
+ name: 'Noah Williams',
47
+ avatarSrc: 'https://i.pravatar.cc/80?img=12',
48
+ },
49
+ sam: {
50
+ id: 'sam',
51
+ name: 'Sam Rivera',
52
+ avatarSrc: 'https://i.pravatar.cc/80?img=15',
53
+ },
54
+ };
55
+
56
+ const styles = stylex.create({
57
+ root: {
58
+ width: '100%',
59
+ maxWidth: 720,
60
+ },
61
+ canvas: {
62
+ display: 'grid',
63
+ gridTemplateColumns: 'minmax(0, 1fr) 72px',
64
+ minHeight: 360,
65
+ overflow: 'hidden',
66
+ borderWidth: 1,
67
+ borderStyle: 'solid',
68
+ borderColor: colorVars['--color-border'],
69
+ borderRadius: radiusVars['--radius-container'],
70
+ backgroundColor: colorVars['--color-background-surface'],
71
+ boxShadow: shadowVars['--shadow-med'],
72
+ },
73
+ media: {
74
+ position: 'relative',
75
+ minWidth: 0,
76
+ minHeight: 360,
77
+ },
78
+ image: {
79
+ display: 'block',
80
+ width: '100%',
81
+ height: 360,
82
+ objectFit: 'cover',
83
+ },
84
+ groupedMarker: {
85
+ position: 'absolute',
86
+ insetInlineStart: '38%',
87
+ insetBlockStart: '30%',
88
+ transform: 'translateY(-100%)',
89
+ },
90
+ resolvedMarker: {
91
+ position: 'absolute',
92
+ insetInlineStart: '66%',
93
+ insetBlockStart: '69%',
94
+ transform: 'translateY(-100%)',
95
+ },
96
+ margin: {
97
+ position: 'relative',
98
+ minHeight: 360,
99
+ borderInlineStartWidth: 1,
100
+ borderInlineStartStyle: 'solid',
101
+ borderInlineStartColor: colorVars['--color-border'],
102
+ backgroundColor: colorVars['--color-background-muted'],
103
+ },
104
+ marginRule: {
105
+ position: 'absolute',
106
+ insetInlineStart: '50%',
107
+ insetBlock: spacingVars['--spacing-5'],
108
+ width: 1,
109
+ backgroundColor: colorVars['--color-border'],
110
+ },
111
+ marginMarker: {
112
+ position: 'absolute',
113
+ insetInlineStart: '50%',
114
+ insetBlockStart: '48%',
115
+ transform: 'translateY(-100%)',
116
+ },
117
+ });
118
+
119
+ type PinId = 'grouped' | 'margin' | 'resolved';
120
+
121
+ export default function CommentPinShowcase() {
122
+ const [selected, setSelected] = useState<PinId | null>('grouped');
123
+ // aria-pressed toggle semantics: activating the selected pin clears it.
124
+ const toggle = (id: PinId) =>
125
+ setSelected(current => (current === id ? null : id));
126
+
127
+ return (
128
+ <VStack gap={4} xstyle={styles.root}>
129
+ <VStack gap={1}>
130
+ <Text as="h3" type="display-3" weight="bold">
131
+ Annotations keep identity at the anchor
132
+ </Text>
133
+ <Text type="supporting" color="secondary">
134
+ The host positions and groups markers; each marker owns only its
135
+ compact interactive surface.
136
+ </Text>
137
+ </VStack>
138
+
139
+ <div {...stylex.props(styles.canvas)}>
140
+ <div {...stylex.props(styles.media)}>
141
+ <img
142
+ src="https://images.unsplash.com/photo-1558655146-d09347e92766?w=1296&h=720&fit=crop&auto=format"
143
+ alt="Design materials arranged on a desk"
144
+ {...stylex.props(styles.image)}
145
+ />
146
+ <CommentPin
147
+ label="Open 6 grouped annotations from Ada, Lin, and 3 others, 2 unread"
148
+ participants={[
149
+ PEOPLE.ada,
150
+ PEOPLE.lin,
151
+ PEOPLE.mira,
152
+ PEOPLE.noah,
153
+ PEOPLE.sam,
154
+ ]}
155
+ threadCount={6}
156
+ unreadCount={2}
157
+ isSelected={selected === 'grouped'}
158
+ isDimmed={selected != null && selected !== 'grouped'}
159
+ onClick={() => toggle('grouped')}
160
+ xstyle={styles.groupedMarker}
161
+ />
162
+ <CommentPin
163
+ label="Open resolved annotation from Mira"
164
+ participants={[PEOPLE.mira]}
165
+ isResolved
166
+ isSelected={selected === 'resolved'}
167
+ isDimmed={selected != null && selected !== 'resolved'}
168
+ onClick={() => toggle('resolved')}
169
+ xstyle={styles.resolvedMarker}
170
+ />
171
+ </div>
172
+
173
+ <div aria-label="Annotation margin" {...stylex.props(styles.margin)}>
174
+ <span aria-hidden="true" {...stylex.props(styles.marginRule)} />
175
+ <CommentPin
176
+ label="Open unread margin annotation from Mira"
177
+ participants={[PEOPLE.mira]}
178
+ unreadCount={1}
179
+ isSelected={selected === 'margin'}
180
+ isDimmed={selected != null && selected !== 'margin'}
181
+ onClick={() => toggle('margin')}
182
+ xstyle={styles.marginMarker}
183
+ />
184
+ </div>
185
+ </div>
186
+ </VStack>
187
+ );
188
+ }
@@ -0,0 +1,86 @@
1
+ import type { BaseProps } from '@astryxdesign/core';
2
+ /** Identity data for one representative shown inside a CommentPin. */
3
+ export interface CommentPinParticipant {
4
+ /** Stable identity used to remove duplicate representatives. */
5
+ id: string;
6
+ /** Display name used by Avatar for image fallback initials. */
7
+ name: string;
8
+ /** Optional image source passed to Avatar. */
9
+ avatarSrc?: string;
10
+ }
11
+ export interface CommentPinProps extends Omit<BaseProps<HTMLButtonElement>, 'children'> {
12
+ /** Ref forwarded to the marker button. */
13
+ ref?: React.Ref<HTMLButtonElement>;
14
+ /**
15
+ * Accessible action name and visual hover/focus tooltip.
16
+ * Include grouped, unread, or resolved context when it changes the action's
17
+ * meaning.
18
+ */
19
+ label: string;
20
+ /**
21
+ * Ordered participants, lead first. A single marker shows the first. A
22
+ * grouped marker shows distinct IDs as an AvatarGroup of at most three
23
+ * circles: every participant when three or fewer are distinct, otherwise the
24
+ * first two plus a `+N` overflow circle. Pass every distinct participant so
25
+ * the overflow count is accurate.
26
+ */
27
+ participants: readonly [CommentPinParticipant, ...CommentPinParticipant[]];
28
+ /**
29
+ * Total number of threads represented by this marker. Values above one use
30
+ * the grouped presentation and show the exact total.
31
+ * @default 1
32
+ */
33
+ threadCount?: number;
34
+ /**
35
+ * Number of represented threads with unread activity. When above zero, an
36
+ * accent badge shows this number in place of the thread total, on single
37
+ * and grouped pins alike. Values above `threadCount` are capped.
38
+ * @default 0
39
+ */
40
+ unreadCount?: number;
41
+ /** Whether this pin is the currently selected annotation target. */
42
+ isSelected?: boolean;
43
+ /**
44
+ * Whether another pin is selected in the host. Dims this pin without
45
+ * disabling it, so it remains available to switch selection.
46
+ */
47
+ isDimmed?: boolean;
48
+ /** Whether every thread represented by this pin is resolved. */
49
+ isResolved?: boolean;
50
+ /** Whether activation is unavailable. */
51
+ isDisabled?: boolean;
52
+ }
53
+ /**
54
+ * Avatar-first annotation anchor for one thread or a caller-defined group.
55
+ *
56
+ * The caller owns grouping, representative selection, coordinates, collision
57
+ * handling, and the content opened by activation. Absolute placement maps the
58
+ * host anchor to the pin's logical bottom-start corner. The pin only owns its
59
+ * compact button surface and controlled visual states.
60
+ *
61
+ * @example
62
+ * ```
63
+ * <CommentPin
64
+ * label="Open annotation from Ada"
65
+ * participants={[{id: 'ada', name: 'Ada Lovelace'}]}
66
+ * onClick={() => openThread('thread-1')}
67
+ * />
68
+ * ```
69
+ *
70
+ * @example
71
+ * ```
72
+ * <CommentPin
73
+ * label="Open 6 grouped annotations from Ada, Lin, and 3 others, 2 unread"
74
+ * participants={[ada, lin, mira, noah, sam]}
75
+ * threadCount={6}
76
+ * unreadCount={2}
77
+ * isSelected
78
+ * onClick={() => openCluster('cluster-1')}
79
+ * />
80
+ * ```
81
+ */
82
+ export declare function CommentPin({ label, participants, threadCount, unreadCount, isSelected, isDimmed, isResolved, isDisabled, ref, xstyle, className, style, ...rest }: CommentPinProps): React.ReactNode;
83
+ export declare namespace CommentPin {
84
+ var displayName: string;
85
+ }
86
+ //# sourceMappingURL=CommentPin.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"CommentPin.d.ts","sourceRoot":"","sources":["../../src/CommentPin/CommentPin.tsx"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AA2BlD,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAC3C,SAAS,CAAC,iBAAiB,CAAC,EAC5B,UAAU,CACX;IACC,0CAA0C;IAC1C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,YAAY,EAAE,SAAS,CAAC,qBAAqB,EAAE,GAAG,qBAAqB,EAAE,CAAC,CAAC;IAC3E;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yCAAyC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAqMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,YAAY,EACZ,WAAe,EACf,WAAe,EACf,UAAkB,EAClB,QAAgB,EAChB,UAAkB,EAClB,UAAkB,EAClB,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,eAAe,GAAG,KAAK,CAAC,SAAS,CAyInC;yBAvJe,UAAU"}