@astryxdesign/lab 0.7.2-canary.4284442 → 0.7.2-canary.4d200b2

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/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'],
+};

package/blocks/CommentsInline.tsx

@@ -0,0 +1,297 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @input A Markdown-like document, its anchored threads, and controlled
+ *   document/thread selection
+ * @output A realistic document review: highlighted passages stay synchronized
+ *   with a Comments side panel, and a selected passage starts a quoted thread
+ * @position Copyable Lab Comments inline-comments example
+ */
+
+import {useRef, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {
+  borderVars,
+  colorVars,
+  focusVars,
+  radiusVars,
+  spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+import {
+  Comments,
+  type CommentAnchor,
+  type CommentData,
+  type CommentThreadData,
+  type CommentUser,
+} from '@astryxdesign/lab';
+
+const VIEWER: CommentUser = {id: 'avery', name: 'Avery Kim'};
+const MAYA: CommentUser = {id: 'maya', name: 'Maya Chen'};
+const JORDAN: CommentUser = {id: 'jordan', name: 'Jordan Lee'};
+
+const ROLLOUT_PASSAGE =
+  'The final cohort completes rollout in three days after the dry run.';
+const GUARDRAIL_PASSAGE =
+  'Pause if the 95th percentile exceeds 420 ms for two consecutive checks.';
+const REVIEW_PASSAGE =
+  'Publish the review note after the final cohort is complete.';
+
+const INITIAL_COMMENTS: readonly CommentThreadData[] = [
+  {
+    id: 'rollout-window',
+    author: MAYA,
+    body: 'Can we make the dry-run dependency explicit? It explains the extra day.',
+    createdAt: '2026-10-14T17:18:00Z',
+    anchor: {quote: ROLLOUT_PASSAGE},
+    replies: [
+      {
+        id: 'rollout-reply',
+        author: VIEWER,
+        body: 'Updated. The window now starts after the dry run finishes.',
+        createdAt: '2026-10-14T17:31:00Z',
+      },
+    ],
+  },
+  {
+    id: 'latency-threshold',
+    author: JORDAN,
+    body: 'This matches the alert. I would keep the two-check window to avoid pausing on a single spike.',
+    createdAt: '2026-10-14T18:04:00Z',
+    anchor: {quote: GUARDRAIL_PASSAGE},
+    isUnread: true,
+  },
+];
+
+const styles = stylex.create({
+  passage: {
+    appearance: 'none',
+    backgroundColor: colorVars['--color-background-yellow'],
+    borderStyle: 'solid',
+    borderWidth: 0,
+    borderBlockEndWidth: borderVars['--border-width'],
+    borderBlockEndColor: 'transparent',
+    borderRadius: radiusVars['--radius-inner'],
+    color: 'inherit',
+    cursor: 'pointer',
+    font: 'inherit',
+    lineHeight: 'inherit',
+    marginInline: spacingVars['--spacing-0-5'],
+    paddingBlock: 0,
+    paddingInline: spacingVars['--spacing-0-5'],
+    textAlign: 'start',
+    outlineStyle: {
+      default: 'none',
+      ':focus-visible': focusVars['--focus-outline-style'],
+    },
+    outlineWidth: focusVars['--focus-outline-width'],
+    outlineColor: focusVars['--focus-outline-color'],
+    outlineOffset: focusVars['--focus-outline-offset'],
+  },
+  selectedPassage: {
+    borderBlockEndColor: colorVars['--color-border-yellow'],
+  },
+  selectablePassage: {
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colorVars['--color-background-yellow'],
+    },
+    borderBlockEndStyle: 'dashed',
+    borderBlockEndColor: colorVars['--color-border-emphasized'],
+  },
+  document: {
+    overflowY: 'auto',
+  },
+});
+
+function updateComment(
+  comments: readonly CommentThreadData[],
+  id: string,
+  update: (comment: CommentData) => CommentData,
+): CommentThreadData[] {
+  return comments.map(comment =>
+    comment.id === id
+      ? {...comment, ...update(comment)}
+      : {
+          ...comment,
+          replies: comment.replies?.map(reply =>
+            reply.id === id ? update(reply) : reply,
+          ),
+        },
+  );
+}
+
+export default function CommentsInline() {
+  const [comments, setComments] = useState<CommentThreadData[]>(() => [
+    ...INITIAL_COMMENTS,
+  ]);
+  const [selectedThreadId, setSelectedThreadId] = useState<string | null>(
+    'rollout-window',
+  );
+  const [selectedPassage, setSelectedPassage] = useState<string | null>(null);
+  const [composerAnchor, setComposerAnchor] = useState<CommentAnchor>();
+  const nextId = useRef(1);
+
+  const post = (body: string, parentCommentId?: string) => {
+    const id = `review-comment-${nextId.current++}`;
+    const comment: CommentData = {
+      id,
+      author: VIEWER,
+      body,
+      createdAt: new Date().toISOString(),
+    };
+    if (parentCommentId != null) {
+      setComments(current =>
+        current.map(thread =>
+          thread.id === parentCommentId
+            ? {...thread, replies: [...(thread.replies ?? []), comment]}
+            : thread,
+        ),
+      );
+      return;
+    }
+    setComments(current => [...current, {...comment, anchor: composerAnchor}]);
+    setComposerAnchor(undefined);
+    setSelectedPassage(null);
+    setSelectedThreadId(id);
+  };
+
+  return (
+    <HStack gap={3} align="start">
+      <Card width={520} height={620} padding={4}>
+        <VStack gap={4} width="100%" xstyle={styles.document}>
+          <VStack gap={1}>
+            <Text as="h1" type="display-3" weight="bold">
+              Launch plan
+            </Text>
+            <Text type="supporting" color="secondary">
+              Draft · updated today
+            </Text>
+          </VStack>
+
+          <VStack gap={2}>
+            <Text as="h2" type="body" weight="bold">
+              Rollout
+            </Text>
+            <Text type="body">
+              Begin with the internal cohort, then expand by region.
+              <button
+                type="button"
+                {...stylex.props(
+                  styles.passage,
+                  selectedThreadId === 'rollout-window' &&
+                    styles.selectedPassage,
+                )}
+                aria-label={`Open comments on “${ROLLOUT_PASSAGE}”`}
+                onClick={() => {
+                  setSelectedPassage(null);
+                  setComposerAnchor(undefined);
+                  setSelectedThreadId('rollout-window');
+                }}>
+                {ROLLOUT_PASSAGE}
+              </button>
+              Owners confirm each step before the next begins.
+            </Text>
+          </VStack>
+
+          <VStack gap={2}>
+            <Text as="h2" type="body" weight="bold">
+              Guardrails
+            </Text>
+            <Text type="body">
+              Watch latency and error rate throughout the rollout.
+              <button
+                type="button"
+                {...stylex.props(
+                  styles.passage,
+                  selectedThreadId === 'latency-threshold' &&
+                    styles.selectedPassage,
+                )}
+                aria-label={`Open comments on “${GUARDRAIL_PASSAGE}”`}
+                onClick={() => {
+                  setSelectedPassage(null);
+                  setComposerAnchor(undefined);
+                  setSelectedThreadId('latency-threshold');
+                }}>
+                {GUARDRAIL_PASSAGE}
+              </button>
+              Resume only after the metric returns to baseline.
+            </Text>
+          </VStack>
+
+          <VStack gap={2} align="start">
+            <Text as="h2" type="body" weight="bold">
+              Review
+            </Text>
+            <Text type="body">
+              <button
+                type="button"
+                {...stylex.props(
+                  styles.passage,
+                  styles.selectablePassage,
+                  selectedPassage === REVIEW_PASSAGE && styles.selectedPassage,
+                )}
+                aria-label={`Select “${REVIEW_PASSAGE}” for a comment`}
+                onClick={() => {
+                  setSelectedThreadId(null);
+                  setComposerAnchor(undefined);
+                  setSelectedPassage(REVIEW_PASSAGE);
+                }}>
+                {REVIEW_PASSAGE}
+              </button>
+            </Text>
+            {selectedPassage === REVIEW_PASSAGE && (
+              <Button
+                label="Comment on selection"
+                variant="secondary"
+                size="sm"
+                onClick={() => {
+                  setComposerAnchor({quote: REVIEW_PASSAGE});
+                  setSelectedPassage(null);
+                }}
+              />
+            )}
+          </VStack>
+        </VStack>
+      </Card>
+
+      <Card width={360} height={620} padding={0}>
+        <Comments
+          label="Comments on Launch plan"
+          comments={comments}
+          currentUser={VIEWER}
+          container="card"
+          density="compact"
+          selectedThreadId={selectedThreadId}
+          onSelectedThreadChange={setSelectedThreadId}
+          composerAnchor={composerAnchor}
+          onComposerAnchorDismiss={() => setComposerAnchor(undefined)}
+          onSubmit={post}
+          onResolveThread={commentId =>
+            setComments(current =>
+              updateComment(current, commentId, comment => ({
+                ...comment,
+                isResolved: true,
+                resolvedBy: VIEWER,
+              })),
+            )
+          }
+          onReopenThread={commentId =>
+            setComments(current =>
+              updateComment(current, commentId, comment => ({
+                ...comment,
+                isResolved: false,
+                resolvedBy: undefined,
+              })),
+            )
+          }
+        />
+      </Card>
+    </HStack>
+  );
+}

package/blocks/CommentsShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'block',
+  name: 'Comments panel',
+  displayName: 'Comments panel',
+  description:
+    'A working Comments panel: threads with replies, reactions, edit history, controlled typing with hidden seen metadata, inline comments, a non-interrupting unread-reply reveal, an agent reply still being written, a resolved thread, a comment that failed to send, activity events, and earlier comments to load. Post, reply, react, edit, delete, and resolve; the host updates the controlled comments.',
+  exampleFor: 'Comments',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: ['Comments', 'VStack'],
+};