@astryxdesign/lab 0.7.2-canary.9fa2213 → 0.7.2-canary.a2f0c93

package/blocks/CommentComposerShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'New comment',
+  displayName: 'New comment',
+  description:
+    'A comment composer quoting the passage it comments on: type, add an emoji, and post with Enter or Post.',
+  exampleFor: 'CommentComposer',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['CommentComposer', 'VStack', 'Text'],
+};

package/blocks/CommentComposerShowcase.tsx

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input A controlled draft and a list of posted comments
+ * @output A comment composer that posts into a short list above it
+ * @position Lab CommentComposer's docsite showcase and copyable CLI block
+ */
+
+import {useState} from 'react';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {CommentComposer} from '@astryxdesign/lab';
+
+export default function CommentComposerShowcase() {
+  const [draft, setDraft] = useState('');
+  const [posted, setPosted] = useState<string[]>([]);
+
+  return (
+    <VStack gap={3} width={420}>
+      {posted.length === 0 ? (
+        <Text type="supporting" color="secondary">
+          Nothing posted yet.
+        </Text>
+      ) : (
+        posted.map((body, index) => (
+          <Text key={index} type="body">
+            {body}
+          </Text>
+        ))
+      )}
+      <CommentComposer
+        value={draft}
+        onChange={setDraft}
+        onSubmit={body => {
+          setPosted(current => [...current, body]);
+          setDraft('');
+        }}
+        anchor={{quote: 'Guardrail alerts page the release oncall.'}}
+        onAnchorDismiss={() => {}}
+      />
+    </VStack>
+  );
+}

package/blocks/CommentPinInMargin.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'Host-owned placement',
+  displayName: 'Comment pin in a document margin',
+  description:
+    '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.',
+  exampleFor: 'CommentPin',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Card', 'CommentPin', 'Text', 'VStack'],
+};

package/blocks/CommentPinInMargin.tsx

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input A host-positioned CommentPin, its lead commenter, and local
+ *   selected state
+ * @output A document passage with one comment pin in its margin; activating
+ *   the pin toggles its selection and aria-pressed state
+ * @position Copyable Lab CommentPin placement example
+ */
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Card} from '@astryxdesign/core/Card';
+import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Stack';
+import {colorVars, spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
+import {CommentPin} from '@astryxdesign/lab';
+
+const styles = stylex.create({
+  document: {
+    display: 'grid',
+    gridTemplateColumns: 'minmax(0, 1fr) 64px',
+    minHeight: 220,
+  },
+  content: {
+    padding: spacingVars['--spacing-5'],
+  },
+  margin: {
+    position: 'relative',
+    borderInlineStartWidth: 1,
+    borderInlineStartStyle: 'solid',
+    borderInlineStartColor: colorVars['--color-border'],
+    backgroundColor: colorVars['--color-background-muted'],
+  },
+  // Inset far enough from the clipped Card edges that the selected ring and
+  // the farther-out keyboard focus outline stay fully visible.
+  pin: {
+    position: 'absolute',
+    insetInlineStart: spacingVars['--spacing-3'],
+    insetBlockStart: spacingVars['--spacing-10'],
+    transform: 'translateY(-100%)',
+  },
+});
+
+export default function CommentPinInMargin() {
+  const [isSelected, setIsSelected] = useState(false);
+  return (
+    <Card padding={0} width={520}>
+      <div {...stylex.props(styles.document)}>
+        <VStack gap={3} xstyle={styles.content}>
+          <Text as="h2" type="display-3" weight="bold">
+            Review notes
+          </Text>
+          <Text type="body">
+            The host owns the document anchor and margin layout. The pin stays a
+            compact action that identifies the lead commenter.
+          </Text>
+          <Text type="supporting" color="secondary">
+            Selecting the pin can open a thread beside this passage or in a
+            shared comments panel.
+          </Text>
+        </VStack>
+        <div aria-label="Comment margin" {...stylex.props(styles.margin)}>
+          <CommentPin
+            label="Open comment from Maya"
+            participants={[{id: 'maya', name: 'Maya Chen'}]}
+            isSelected={isSelected}
+            onClick={() => setIsSelected(current => !current)}
+            xstyle={styles.pin}
+          />
+        </div>
+      </div>
+    </Card>
+  );
+}

package/blocks/CommentPinShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'Avatar-first annotations',
+  displayName: 'Avatar-first annotations',
+  description:
+    '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.',
+  exampleFor: 'CommentPin',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['CommentPin', 'Text', 'VStack'],
+};

package/blocks/CommentPinShowcase.tsx

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Three caller-positioned comment pins, logical bottom-start anchors,
+ *   participant/thread/unread counts, and controlled selected/dimmed state
+ *   that may be empty
+ * @output A grouped pin with a three-circle participant cap and an unread
+ *   badge, a resolved pin, and an unread margin pin; activating the selected
+ *   pin clears the selection, and non-selected pins dim only while another pin
+ *   is selected
+ * @position CommentPin docsite showcase and copyable Lab block
+ */
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {CommentPin} from '@astryxdesign/lab';
+import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Stack';
+import {
+  colorVars,
+  radiusVars,
+  shadowVars,
+  spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+
+const PEOPLE = {
+  ada: {
+    id: 'ada',
+    name: 'Ada Lovelace',
+    avatarSrc: 'https://i.pravatar.cc/80?img=47',
+  },
+  lin: {
+    id: 'lin',
+    name: 'Lin Chen',
+    avatarSrc: 'https://i.pravatar.cc/80?img=32',
+  },
+  mira: {
+    id: 'mira',
+    name: 'Mira Patel',
+    avatarSrc: 'https://i.pravatar.cc/80?img=5',
+  },
+  noah: {
+    id: 'noah',
+    name: 'Noah Williams',
+    avatarSrc: 'https://i.pravatar.cc/80?img=12',
+  },
+  sam: {
+    id: 'sam',
+    name: 'Sam Rivera',
+    avatarSrc: 'https://i.pravatar.cc/80?img=15',
+  },
+};
+
+const styles = stylex.create({
+  root: {
+    width: '100%',
+    maxWidth: 720,
+  },
+  canvas: {
+    display: 'grid',
+    gridTemplateColumns: 'minmax(0, 1fr) 72px',
+    minHeight: 360,
+    overflow: 'hidden',
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colorVars['--color-border'],
+    borderRadius: radiusVars['--radius-container'],
+    backgroundColor: colorVars['--color-background-surface'],
+    boxShadow: shadowVars['--shadow-med'],
+  },
+  media: {
+    position: 'relative',
+    minWidth: 0,
+    minHeight: 360,
+  },
+  image: {
+    display: 'block',
+    width: '100%',
+    height: 360,
+    objectFit: 'cover',
+  },
+  groupedMarker: {
+    position: 'absolute',
+    insetInlineStart: '38%',
+    insetBlockStart: '30%',
+    transform: 'translateY(-100%)',
+  },
+  resolvedMarker: {
+    position: 'absolute',
+    insetInlineStart: '66%',
+    insetBlockStart: '69%',
+    transform: 'translateY(-100%)',
+  },
+  margin: {
+    position: 'relative',
+    minHeight: 360,
+    borderInlineStartWidth: 1,
+    borderInlineStartStyle: 'solid',
+    borderInlineStartColor: colorVars['--color-border'],
+    backgroundColor: colorVars['--color-background-muted'],
+  },
+  marginRule: {
+    position: 'absolute',
+    insetInlineStart: '50%',
+    insetBlock: spacingVars['--spacing-5'],
+    width: 1,
+    backgroundColor: colorVars['--color-border'],
+  },
+  marginMarker: {
+    position: 'absolute',
+    insetInlineStart: '50%',
+    insetBlockStart: '48%',
+    transform: 'translateY(-100%)',
+  },
+});
+
+type PinId = 'grouped' | 'margin' | 'resolved';
+
+export default function CommentPinShowcase() {
+  const [selected, setSelected] = useState<PinId | null>('grouped');
+  // aria-pressed toggle semantics: activating the selected pin clears it.
+  const toggle = (id: PinId) =>
+    setSelected(current => (current === id ? null : id));
+
+  return (
+    <VStack gap={4} xstyle={styles.root}>
+      <VStack gap={1}>
+        <Text as="h3" type="display-3" weight="bold">
+          Annotations keep identity at the anchor
+        </Text>
+        <Text type="supporting" color="secondary">
+          The host positions and groups markers; each marker owns only its
+          compact interactive surface.
+        </Text>
+      </VStack>
+
+      <div {...stylex.props(styles.canvas)}>
+        <div {...stylex.props(styles.media)}>
+          <img
+            src="https://images.unsplash.com/photo-1558655146-d09347e92766?w=1296&h=720&fit=crop&auto=format"
+            alt="Design materials arranged on a desk"
+            {...stylex.props(styles.image)}
+          />
+          <CommentPin
+            label="Open 6 grouped annotations from Ada, Lin, and 3 others, 2 unread"
+            participants={[
+              PEOPLE.ada,
+              PEOPLE.lin,
+              PEOPLE.mira,
+              PEOPLE.noah,
+              PEOPLE.sam,
+            ]}
+            threadCount={6}
+            unreadCount={2}
+            isSelected={selected === 'grouped'}
+            isDimmed={selected != null && selected !== 'grouped'}
+            onClick={() => toggle('grouped')}
+            xstyle={styles.groupedMarker}
+          />
+          <CommentPin
+            label="Open resolved annotation from Mira"
+            participants={[PEOPLE.mira]}
+            isResolved
+            isSelected={selected === 'resolved'}
+            isDimmed={selected != null && selected !== 'resolved'}
+            onClick={() => toggle('resolved')}
+            xstyle={styles.resolvedMarker}
+          />
+        </div>
+
+        <div aria-label="Annotation margin" {...stylex.props(styles.margin)}>
+          <span aria-hidden="true" {...stylex.props(styles.marginRule)} />
+          <CommentPin
+            label="Open unread margin annotation from Mira"
+            participants={[PEOPLE.mira]}
+            unreadCount={1}
+            isSelected={selected === 'margin'}
+            isDimmed={selected != null && selected !== 'margin'}
+            onClick={() => toggle('margin')}
+            xstyle={styles.marginMarker}
+          />
+        </div>
+      </div>
+    </VStack>
+  );
+}

package/blocks/CommentThreadInPopover.doc.mjs

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'In a popover',
+  displayName: 'In a popover',
+  description:
+    'Open one thread from a passage in a Popover with no padding. The thread owns the Popover’s dismissal through `onDismiss`, so turn the Popover’s light and Escape dismissal off: a press outside or Escape closes the thread, but the first one over an unsaved reply shakes it and keeps the draft.',
+  exampleFor: 'CommentThread',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: [
+    'CommentThread',
+    'Popover',
+    'Button',
+    'Card',
+    'Text',
+    'VStack',
+  ],
+};

package/blocks/CommentThreadInPopover.tsx

@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled popover state, a controlled comment thread, and its reply
+ *   callback
+ * @output A passage whose comment button opens one thread in a Popover; the
+ *   thread owns the Popover's dismissal and keeps an unsaved reply on the
+ *   first press outside or Escape
+ * @position Copyable Lab CommentThread example
+ */
+
+import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Popover} from '@astryxdesign/core/Popover';
+import {Text} from '@astryxdesign/core/Text';
+import {
+  CommentThread,
+  type CommentThreadData,
+  type CommentUser,
+} from '@astryxdesign/lab';
+
+const VIEWER: CommentUser = {id: 'avery', name: 'Avery Kim'};
+
+export default function CommentThreadInPopover() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [thread, setThread] = useState<CommentThreadData>({
+    id: 'passage',
+    author: {id: 'maya', name: 'Maya Chen'},
+    body: 'Should this say three days? The dry run adds one.',
+    createdAt: '2026-09-30T19:00:00Z',
+    anchor: {quote: 'The final cohort completes rollout in two days.'},
+  });
+  const replyCount = thread.replies?.length ?? 0;
+
+  return (
+    <Card padding={4} width={420}>
+      <VStack gap={3} align="start">
+        <Text>
+          Every region moves to the new build in three cohorts. The final cohort
+          completes rollout in two days.
+        </Text>
+        <Popover
+          isOpen={isOpen}
+          onOpenChange={setIsOpen}
+          // The thread owns dismissal: it keeps an unsaved reply on the first
+          // press outside or Escape, which native light dismiss cannot.
+          hasLightDismiss={false}
+          hasEscapeDismiss={false}
+          label="Comment thread"
+          padding={0}
+          width={340}
+          content={
+            <CommentThread
+              comment={thread}
+              currentUser={VIEWER}
+              container="card"
+              onDismiss={() => setIsOpen(false)}
+              onSubmit={body =>
+                setThread(current => ({
+                  ...current,
+                  replies: [
+                    ...(current.replies ?? []),
+                    {
+                      id: `reply-${Date.now()}`,
+                      author: VIEWER,
+                      body,
+                      createdAt: new Date().toISOString(),
+                    },
+                  ],
+                }))
+              }
+            />
+          }>
+          <Button
+            label={
+              replyCount === 0 ? '1 comment' : `${replyCount + 1} comments`
+            }
+            variant="secondary"
+            size="sm"
+          />
+        </Popover>
+      </VStack>
+    </Card>
+  );
+}

package/blocks/CommentThreadShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'Margin comment',
+  displayName: 'Margin comment',
+  description:
+    'One comment thread in a Card beside a document: it quotes its passage, opens on a press into its replies and reply composer, and resolves.',
+  exampleFor: 'CommentThread',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['CommentThread', 'Card'],
+};

package/blocks/CommentThreadShowcase.tsx

@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input A controlled inline comment thread and its reply callback
+ * @output A margin comment: one thread quoting its passage, inside a Card
+ * @position Lab CommentThread's docsite showcase and copyable CLI block
+ */
+
+import {useState} from 'react';
+import {Card} from '@astryxdesign/core/Card';
+import {
+  CommentThread,
+  type CommentThreadData,
+  type CommentUser,
+} from '@astryxdesign/lab';
+
+const VIEWER: CommentUser = {id: 'avery', name: 'Avery Kim'};
+
+export default function CommentThreadShowcase() {
+  const [thread, setThread] = useState<CommentThreadData>({
+    id: 'margin',
+    author: {id: 'maya', name: 'Maya Chen'},
+    body: 'Should this say three days? The dry run adds one.',
+    createdAt: '2026-09-30T19:00:00Z',
+    anchor: {quote: 'The final cohort completes rollout in two days.'},
+    replies: [
+      {
+        id: 'margin-reply',
+        author: VIEWER,
+        body: 'Good catch, updating it.',
+        createdAt: '2026-09-30T19:20:00Z',
+      },
+    ],
+  });
+
+  return (
+    <Card padding={0} width={340}>
+      <CommentThread
+        comment={thread}
+        currentUser={VIEWER}
+        container="card"
+        onSubmit={body =>
+          setThread(current => ({
+            ...current,
+            replies: [
+              ...(current.replies ?? []),
+              {
+                id: `reply-${Date.now()}`,
+                author: VIEWER,
+                body,
+                createdAt: new Date().toISOString(),
+              },
+            ],
+          }))
+        }
+        onResolveThread={() =>
+          setThread(current => ({...current, isResolved: true}))
+        }
+        onReopenThread={() =>
+          setThread(current => ({...current, isResolved: false}))
+        }
+      />
+    </Card>
+  );
+}

package/blocks/CommentsInCard.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'Inside a card',
+  displayName: 'Inside a card',
+  description:
+    'Set container="card" on a card parent: threads become divider-bounded Sections, so cards never nest, and the composer docks at the bottom of the card.',
+  exampleFor: 'Comments',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: ['Comments', 'Card'],
+};

package/blocks/CommentsInCard.tsx

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input Controlled comments and a post callback
+ * @output A compact Comments panel filling a Card, its threads divider-bounded
+ *   Sections so cards never nest
+ * @position Copyable Lab Comments example
+ */
+
+import {useState} from 'react';
+import {Card} from '@astryxdesign/core/Card';
+import {
+  Comments,
+  type CommentThreadData,
+  type CommentUser,
+} from '@astryxdesign/lab';
+
+const VIEWER: CommentUser = {id: 'avery', name: 'Avery Kim'};
+const MAYA: CommentUser = {id: 'maya', name: 'Maya Chen'};
+
+const INITIAL_COMMENTS: readonly CommentThreadData[] = [
+  {
+    id: 'kickoff',
+    author: MAYA,
+    body: 'Can you review the rollout plan before Friday?',
+    createdAt: '2026-09-30T19:00:00Z',
+    replies: [
+      {
+        id: 'kickoff-reply',
+        author: VIEWER,
+        body: 'On it. I will leave notes on the final cohort.',
+        createdAt: '2026-09-30T19:12:00Z',
+      },
+    ],
+  },
+  {
+    id: 'dashboard',
+    author: VIEWER,
+    body: 'I added the guardrail dashboard to the summary.',
+    createdAt: '2026-09-30T19:20:00Z',
+  },
+];
+
+export default function CommentsInCard() {
+  const [comments, setComments] = useState(INITIAL_COMMENTS);
+  const post = (body: string, parentId?: string) => {
+    const comment = {
+      id: `comment-${Date.now()}`,
+      author: VIEWER,
+      body,
+      createdAt: new Date().toISOString(),
+    };
+    setComments(current =>
+      parentId == null
+        ? [...current, comment]
+        : current.map(root =>
+            root.id === parentId
+              ? {...root, replies: [...(root.replies ?? []), comment]}
+              : root,
+          ),
+    );
+  };
+
+  return (
+    <Card padding={0} width={380} height={460}>
+      <Comments
+        label="Rollout plan"
+        comments={comments}
+        currentUser={VIEWER}
+        container="card"
+        density="compact"
+        onSubmit={post}
+      />
+    </Card>
+  );
+}

package/blocks/CommentsInline.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'Inline comments',
+  displayName: 'Inline comments',
+  description:
+    'A realistic Markdown document review with highlighted passages synchronized to a Comments side panel. Selecting an unannotated passage starts a quoted thread; replies and resolution update host-owned data.',
+  exampleFor: 'Comments',
+  isReady: true,
+  aspectRatio: 3 / 2,
+  componentsUsed: ['Button', 'Card', 'Comments', 'HStack', 'Text', 'VStack'],
+};