@astryxdesign/core 0.0.0-bootstrap.0 → 0.0.15

package/src/Chat/ChatLayout.tsx

@@ -0,0 +1,377 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ChatLayout.tsx
+ * @input Uses React, StyleX, theme tokens, useChatStreamScroll, useChatNewMessages
+ * @output Exports ChatLayout component and ChatLayoutProps
+ * @position Layout shell for full chat interfaces — messages in page flow, composer fixed to bottom
+ *
+ * Structural layout only — scroll behavior is delegated to hooks.
+ * Provides the scroll container ref and content ref, renders the
+ * scroll-to-bottom button, frosted glass dock, and message area.
+ *
+ * Density (compact/balanced/spacious) is controlled via a prop with
+ * 'balanced' as the default. No JS measurement or ResizeObserver needed.
+ * The container-type on root enables container queries in child components.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Chat/index.ts (exports)
+ * - /apps/storybook/stories/ChatLayout.stories.tsx
+ * - /packages/cli/templates/blocks/components/ChatLayout/ (block examples)
+ */
+
+import {type ReactNode, useMemo, useRef} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {spacingVars} from '../theme/tokens.stylex';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps, mergeRefs} from '../utils';
+import {useChatStreamScroll} from './useChatStreamScroll';
+import {useChatNewMessages} from './useChatNewMessages';
+import {ChatLayoutScrollButton} from './ChatLayoutScrollButton';
+import {ChatLayoutContext} from './ChatContext';
+import {xdsThemeProps} from '../utils/xdsThemeProps';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+type Density = 'compact' | 'balanced' | 'spacious';
+
+/** Imperative handle for ChatLayout scroll controls. */
+export interface ChatLayoutHandle {
+  /** Scroll a message to the top and unlock for stream-in. */
+  /** Scroll to bottom and re-lock. */
+  scrollToBottom: () => void;
+  /** Navigate to a message, no lock change. */
+  scrollToMessage: (el: HTMLElement) => void;
+  /** Scroll to the last message. */
+  scrollToLastMessage: () => void;
+}
+
+export interface ChatLayoutProps extends BaseProps<HTMLDivElement> {
+  /** Ref forwarded to the root element. */
+  ref?: React.Ref<HTMLDivElement>;
+
+  /**
+   * Message content — flows naturally in the page, scrolls with the page.
+   * Typically ChatMessageList with ChatMessage children.
+   */
+  children: ReactNode;
+
+  /**
+   * Composer element — fixed to the bottom with a frosted glass dock.
+   * Typically ChatComposer.
+   */
+  composer: ReactNode;
+
+  /**
+   * Content shown when children is empty.
+   */
+  emptyState?: ReactNode;
+
+  /**
+   * Scroll-to-bottom button rendered above the composer in the dock.
+   * Defaults to ChatLayoutScrollButton with useChatStreamScroll.
+   * Pass a custom ReactNode to override, or `null` to hide.
+   */
+  scrollButton?: ReactNode | null;
+
+  /**
+   * External scroll container ref. When provided, auto-scroll and
+   * scroll-to-bottom target this element instead of the layout root.
+   *
+   * @example
+   * ```
+   * const scrollRef = useRef(document.documentElement);
+   * <ChatLayout scrollRef={scrollRef} composer={...}>...</ChatLayout>
+   * ```
+   *
+   * When omitted, the layout root itself is the scroll container.
+   */
+  scrollRef?: React.RefObject<HTMLElement | null>;
+
+  /**
+   * Layout density. Controls spacing, max-width, and blur layer sizing.
+   *
+   * @default 'balanced'
+   */
+  density?: Density;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+  root: {
+    position: 'relative',
+    containerType: 'inline-size',
+    minHeight: 0,
+    flex: 1,
+  },
+  rootScrollable: {
+    overflowY: 'auto',
+    overflowX: 'hidden',
+    // Hide scrollbar during programmatic scroll animation
+    // to prevent flash. Restored when animation settles.
+    scrollbarWidth: {
+      default: null,
+      ':is([data-astryx-scrolling])': 'none',
+    },
+  },
+
+  messageArea: {
+    display: 'flex',
+    flexDirection: 'column',
+    marginInline: 'auto',
+    minHeight: '100%',
+    paddingBlockEnd: spacingVars['--spacing-6'],
+    width: '100%',
+    maxWidth: '100%',
+    paddingInline: 0,
+  },
+
+  emptyState: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flex: 1,
+    minHeight: 200,
+  },
+
+  // --- Dock container ---
+  dockContainer: {
+    bottom: 0,
+    left: 0,
+    right: 0,
+    zIndex: 0,
+    isolation: 'isolate',
+    pointerEvents: 'none',
+  },
+  dockContainerFixed: {
+    position: 'fixed',
+  },
+  dockContainerSticky: {
+    position: 'sticky',
+  },
+
+  blurLayer: {
+    position: 'absolute',
+    bottom: 0,
+    left: 0,
+    right: 0,
+    pointerEvents: 'none',
+    backdropFilter: 'blur(12px)',
+    WebkitBackdropFilter: 'blur(12px)',
+    height: 100,
+    maskImage: 'linear-gradient(to bottom, transparent, black 36px)',
+    WebkitMaskImage: 'linear-gradient(to bottom, transparent, black 36px)',
+  },
+
+  dock: {
+    position: 'relative',
+    zIndex: 1,
+    pointerEvents: 'auto',
+    paddingInline: spacingVars['--spacing-3'],
+    paddingBlockEnd: spacingVars['--spacing-3'],
+  },
+
+  dockInner: {
+    marginInline: 'auto',
+    width: '100%',
+    maxWidth: '100%',
+  },
+
+  // --- Forced density overrides (disable container queries) ---
+  messageAreaCompact: {
+    maxWidth: '100%',
+    paddingInline: 0,
+  },
+  messageAreaBalanced: {
+    maxWidth: '100%',
+    paddingInline: 0,
+  },
+  messageAreaSpacious: {
+    maxWidth: 800,
+    paddingInline: spacingVars['--spacing-4'],
+  },
+
+  blurLayerCompact: {
+    height: 80,
+    maskImage: 'linear-gradient(to bottom, transparent, black 24px)',
+    WebkitMaskImage: 'linear-gradient(to bottom, transparent, black 24px)',
+  },
+  blurLayerBalanced: {
+    height: 100,
+    maskImage: 'linear-gradient(to bottom, transparent, black 36px)',
+    WebkitMaskImage: 'linear-gradient(to bottom, transparent, black 36px)',
+  },
+  blurLayerSpacious: {
+    height: 120,
+    maskImage: 'linear-gradient(to bottom, transparent, black 48px)',
+    WebkitMaskImage: 'linear-gradient(to bottom, transparent, black 48px)',
+  },
+
+  dockCompact: {
+    paddingInline: spacingVars['--spacing-2'],
+    paddingBlockEnd: spacingVars['--spacing-2'],
+  },
+  dockBalanced: {
+    paddingInline: spacingVars['--spacing-3'],
+    paddingBlockEnd: spacingVars['--spacing-3'],
+  },
+  dockSpacious: {
+    paddingInline: spacingVars['--spacing-4'],
+    paddingBlockEnd: spacingVars['--spacing-3'],
+  },
+
+  dockInnerCompact: {
+    maxWidth: '100%',
+  },
+  dockInnerBalanced: {
+    maxWidth: '100%',
+  },
+  dockInnerSpacious: {
+    maxWidth: 800,
+  },
+});
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function hasVisibleContent(children: ReactNode): boolean {
+  if (children == null || children === false) {
+    return false;
+  }
+  if (Array.isArray(children) && children.length === 0) {
+    return false;
+  }
+  return true;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function ChatLayout({
+  children,
+  composer,
+  density = 'balanced',
+  emptyState,
+  scrollButton,
+  scrollRef: externalScrollRef,
+  xstyle,
+  className,
+  style,
+  'data-testid': testId,
+  ref,
+}: ChatLayoutProps) {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  const scrollContainerRef = externalScrollRef ?? rootRef;
+  const isSelfScrolling = !externalScrollRef;
+
+  // --- Default scroll behavior ---
+  const scroll = useChatStreamScroll({scrollRef: scrollContainerRef});
+  const newMsgs = useChatNewMessages({
+    isLocked: scroll.isLocked,
+    onResize: scroll.scrollIfLocked,
+  });
+
+  const defaultScrollButton = (
+    <ChatLayoutScrollButton
+      isVisible={scroll.isScrolledUp || newMsgs.hasNewMessages}
+      label={newMsgs.hasNewMessages ? 'New messages' : undefined}
+      onClick={() => {
+        newMsgs.dismiss();
+        scroll.scrollToBottom();
+      }}
+    />
+  );
+
+  // --- Layout context ---
+  const layoutContext = useMemo(
+    () => ({scrollContainerRef, contentRef: newMsgs.contentRef}),
+    [scrollContainerRef, newMsgs.contentRef],
+  );
+
+  // --- Derived styles ---
+  const showEmpty = !hasVisibleContent(children);
+
+  const densityStyles = {
+    compact: {
+      messageArea: styles.messageAreaCompact,
+      blurLayer: styles.blurLayerCompact,
+      dock: styles.dockCompact,
+      dockInner: styles.dockInnerCompact,
+    },
+    balanced: {
+      messageArea: styles.messageAreaBalanced,
+      blurLayer: styles.blurLayerBalanced,
+      dock: styles.dockBalanced,
+      dockInner: styles.dockInnerBalanced,
+    },
+    spacious: {
+      messageArea: styles.messageAreaSpacious,
+      blurLayer: styles.blurLayerSpacious,
+      dock: styles.dockSpacious,
+      dockInner: styles.dockInnerSpacious,
+    },
+  } as const;
+
+  const currentDensity = densityStyles[density];
+
+  return (
+    <ChatLayoutContext value={layoutContext}>
+      <div
+        ref={mergeRefs(ref, rootRef)}
+        data-testid={testId}
+        {...mergeProps(
+          xdsThemeProps('chat-layout', {density}),
+          stylex.props(
+            styles.root,
+            isSelfScrolling && styles.rootScrollable,
+            xstyle,
+          ),
+          className,
+          style,
+        )}>
+        {/* Message area */}
+        <div {...stylex.props(styles.messageArea, currentDensity.messageArea)}>
+          {showEmpty && emptyState ? (
+            <div {...stylex.props(styles.emptyState)}>{emptyState}</div>
+          ) : (
+            children
+          )}
+        </div>
+
+        {/* Dock container — sticky/fixed, holds blur + scroll button + composer */}
+        <div
+          {...stylex.props(
+            styles.dockContainer,
+            isSelfScrolling
+              ? styles.dockContainerSticky
+              : styles.dockContainerFixed,
+          )}>
+          {/* Scroll-to-bottom button */}
+          {scrollButton === undefined ? defaultScrollButton : scrollButton}
+
+          {/* Frosted glass layer */}
+          <div {...stylex.props(styles.blurLayer, currentDensity.blurLayer)} />
+
+          {/* Composer */}
+          <div {...stylex.props(styles.dock, currentDensity.dock)}>
+            <div {...stylex.props(styles.dockInner, currentDensity.dockInner)}>
+              {composer}
+            </div>
+          </div>
+        </div>
+      </div>
+    </ChatLayoutContext>
+  );
+}
+
+ChatLayout.displayName = 'ChatLayout';

package/src/Chat/ChatLayoutScrollButton.doc.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'ChatLayoutScrollButton',
+  subComponentOf: 'Chat',
+  displayName: 'Chat Layout Scroll Button',
+  isHiddenFromOverview: true,
+  description: 'Floating scroll-to-bottom button that appears when the user scrolls away from the latest messages. It fades in as a compact icon button and expands to show a label when new messages arrive. ChatLayout renders this by default: pass a custom element to the scrollButton prop to override, or null to hide it entirely.',
+  props: [
+    {
+      name: 'isVisible',
+      type: 'boolean',
+      description: 'Whether the button is visible. Bind to a scroll-position check so the button only appears when the user has scrolled up.',
+      required: true,
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Optional label that expands the button (e.g. "New messages"). Use to signal unread content below the fold.',
+    },
+    {
+      name: 'onClick',
+      type: '() => void',
+      description: 'Click handler: typically scrolls to bottom and dismisses the new message indicator.',
+      required: true,
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'ChatLayoutScrollButton',
+  isHiddenFromOverview: true,
+  displayName: 'Chat Layout Scroll Button',
+  description: '可组合的滚动到底部按钮。可见时淡入，提供标签时展开。',
+  propDescriptions: {
+    isVisible: '按钮是否可见。',
+    label: '可选标签，展开按钮（如"新消息"）。',
+    onClick: '点击处理器。',
+  },
+};
+
+export const docsDense = {
+  name: 'ChatLayoutScrollButton',
+  isHiddenFromOverview: true,
+  displayName: 'Chat Layout Scroll Button',
+  description: 'floating scroll-to-bottom btn; fades in when scrolled up, expands w/ label for new msgs. Default in ChatLayout; override via scrollButton prop.',
+  propDescriptions: {
+    isVisible: 'btn visibility: bind to scroll-position check',
+    label: 'optional label; expands btn (e.g. "New messages")',
+    onClick: 'click handler',
+  },
+};

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ChatLayoutScrollButton.tsx
+ * @input Uses React, StyleX, Button, Icon, theme tokens
+ * @output Exports ChatLayoutScrollButton component
+ * @position Composable scroll-to-bottom button for use inside ChatLayout
+ *
+ * Renders inside the layout's dock container. Fades in when visible,
+ * expands to show a label when provided (e.g. "New messages").
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Chat/index.ts (exports)
+ * - /packages/cli/templates/blocks/components/ChatLayoutScrollButton/ (block examples)
+ */
+
+import React from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+  colorVars,
+  spacingVars,
+  radiusVars,
+  shadowVars,
+  durationVars,
+  easeVars,
+} from '../theme/tokens.stylex';
+import {Icon} from '../Icon';
+import {Button} from '../Button';
+import type {BaseProps} from '../BaseProps';
+import {mergeProps} from '../utils';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ChatLayoutScrollButtonProps extends Omit<
+  BaseProps<HTMLDivElement>,
+  'onClick'
+> {
+  ref?: React.Ref<HTMLDivElement>;
+  /** Whether the button is visible. */
+  isVisible: boolean;
+  /** Optional label — expands the button (e.g. "New messages"). */
+  label?: string;
+  /** Click handler. */
+  onClick: () => void;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+  wrapper: {
+    display: 'flex',
+    justifyContent: 'center',
+    paddingBlockEnd: spacingVars['--spacing-3'],
+  },
+  container: {
+    pointerEvents: 'auto',
+    contain: 'layout style',
+    overflow: 'hidden',
+    borderRadius: radiusVars['--radius-full'],
+    backgroundColor: colorVars['--color-background-popover'],
+    boxShadow: shadowVars['--shadow-med'],
+    height: '32px',
+    transitionProperty: 'opacity, transform, max-width',
+    transitionTimingFunction: easeVars['--ease-standard'],
+    transitionDuration: durationVars['--duration-fast-max'],
+  },
+  hidden: {
+    opacity: 0,
+    pointerEvents: 'none',
+    maxWidth: '32px',
+  },
+  visible: {
+    opacity: 1,
+    pointerEvents: 'auto',
+  },
+  collapsed: {
+    maxWidth: '32px',
+  },
+  expanded: {
+    maxWidth: '200px',
+  },
+  button: {
+    [radiusVars['--radius-element'] as string]: radiusVars['--radius-full'],
+    whiteSpace: 'nowrap',
+    paddingInline: spacingVars['--spacing-2'],
+  },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Floating scroll-to-bottom button for use inside ChatLayout.
+ *
+ * @example
+ * ```
+ * <ChatLayoutScrollButton isVisible={!isAtBottom} onClick={scrollToBottom} />
+ * ```
+ */
+export function ChatLayoutScrollButton({
+  ref,
+  isVisible,
+  label,
+  onClick,
+  xstyle,
+  className,
+  style,
+}: ChatLayoutScrollButtonProps) {
+  return (
+    <div
+      ref={ref}
+      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}>
+      <div
+        {...stylex.props(
+          styles.container,
+          isVisible ? styles.visible : styles.hidden,
+          label ? styles.expanded : styles.collapsed,
+        )}>
+        <Button
+          label={label ?? 'Scroll to bottom'}
+          aria-label={label ?? 'Scroll to bottom'}
+          icon={<Icon icon="chevronDown" size="md" />}
+          variant="ghost"
+          size="md"
+          onClick={onClick}
+          xstyle={styles.button}>
+          {label ?? undefined}
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+ChatLayoutScrollButton.displayName = 'ChatLayoutScrollButton';

package/src/Chat/ChatMessage.doc.mjs

@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'ChatMessage',
+  subComponentOf: 'Chat',
+  displayName: 'Chat Message',
+  description: 'Sender context wrapper: handles avatar, name, metadata, and alignment based on sender role.',
+  props: [
+    {
+      name: 'sender',
+      type: "'user' | 'assistant' | 'system'",
+      description: 'Who sent this message: controls alignment and layout.',
+      required: true,
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Free-form content: bubbles, asset lists, tool calls, images.',
+      required: true,
+    },
+    {
+      name: 'avatar',
+      type: 'ReactNode',
+      description: 'Avatar element rendered beside the message. Typically Avatar.',
+      slotElements: [
+        {
+          __element: 'Avatar',
+          props: {
+            name: 'User',
+            size: 'sm',
+          },
+        },
+      ],
+    },
+    {
+      name: 'name',
+      type: 'ReactNode',
+      description: "Sender name rendered above the message body. Use when the first child is raw content (not a bubble). If the first child is a bubble, put the name on the bubble's `name` prop instead.",
+    },
+    {
+      name: 'metadata',
+      type: 'ReactNode',
+      description: "Metadata rendered below the message body. Use when the last child is raw content (not a bubble). If the last child is a bubble, put metadata on the bubble's `metadata` prop instead.",
+      slotElements: [
+        {
+          __element: 'Text',
+          props: {
+            type: 'body',
+          },
+          children: 'Metadata',
+        },
+      ],
+    },
+    {
+      name: 'density',
+      type: "'compact' | 'balanced' | 'spacious'",
+      description: 'Visual density. Inherited from list context if not set.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'ChatMessage',
+  displayName: 'Chat Message',
+  description: '发送者上下文包装器，根据发送者角色处理头像、名称、元数据和对齐方式。',
+  propDescriptions: {
+    sender: '消息发送者，控制对齐和布局。',
+    children: '自由内容：气泡、资源列表、工具调用、图片。',
+    avatar: '消息旁边渲染的头像元素。通常是 Avatar。',
+    name: '消息正文上方渲染的发送者名称。当第一个子元素不是气泡时使用。',
+    metadata: '消息正文下方渲染的元数据。当最后一个子元素不是气泡时使用。',
+    density: '视觉密度。未设置时从列表上下文继承。',
+  },
+};
+
+export const docsDense = {
+  name: 'ChatMessage',
+  displayName: 'Chat Message',
+  description: 'sender context wrapper; handles avatar+name+metadata+alignment by sender role',
+  propDescriptions: {
+    sender: 'who sent; controls alignment+layout',
+    children: 'free-form: bubbles, assets, tool calls, images',
+    avatar: 'avatar element beside msg; typically Avatar',
+    name: 'sender name above body; use when first child is raw (not bubble)',
+    displayName: 'sender name above body; use when first child is raw (not bubble)',
+    metadata: 'metadata below body; use when last child is raw (not bubble)',
+    density: 'visual density; inherited from list context if unset',
+  },
+};