@pharos-ds/core 0.1.9

package/src/Chat/ChatComposer.tsx

@@ -0,0 +1,498 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ChatComposer.tsx
+ * @input Uses React, StyleX, BaseProps
+ * @output Exports ChatComposer layout shell component
+ * @position Core implementation; consumed by index.ts
+ *
+ * Layout shell for a chat composer. Arranges slots (drawer, header,
+ * input, footer actions, send button, status) in a vertical stack with
+ * page-radius container, hover/focus shadows, and concentric inner radius.
+ *
+ * Component CSS vars (themeable via defineTheme):
+ * - `--_chat-composer-radius` (default: --radius-chat) — outer border radius
+ * - `--_chat-composer-padding` (default: --spacing-3) — body padding
+ * - Inner element radius = calc(--_chat-composer-radius - --_chat-composer-padding)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Chat/Chat.doc.mjs
+ * - /apps/storybook/stories/ChatComposer.stories.tsx
+ * - /packages/cli/templates/blocks/components/ChatComposer/ (block examples)
+ */
+
+import React, {
+  useState,
+  useCallback,
+  useRef,
+  useMemo,
+  type ReactNode,
+  type MouseEvent,
+} from 'react';
+import type {BaseProps} from '../BaseProps';
+import * as stylex from '@stylexjs/stylex';
+import {
+  colorVars,
+  spacingVars,
+  radiusVars,
+  shadowVars,
+  durationVars,
+  easeVars,
+  borderVars,
+  typeScaleVars,
+  typographyVars,
+} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import {Icon} from '../Icon';
+import {ChatComposerInput} from './ChatComposerInput';
+import {ChatComposerContext} from './ChatContext';
+import type {ChatComposerInputControl} from './ChatContext';
+import {ChatSendButton} from './ChatSendButton';
+import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type ChatComposerStatus = {
+  type: 'error' | 'warning';
+  message?: string;
+};
+
+export type ChatComposerDensity = 'compact' | 'balanced' | 'spacious';
+
+export interface ChatComposerProps extends Omit<
+  BaseProps<HTMLDivElement>,
+  'onChange' | 'onSubmit'
+> {
+  ref?: React.Ref<HTMLDivElement>;
+  /** Called when the user submits the message */
+  onSubmit: (value: string) => void;
+  /** Called when the user clicks the stop button */
+  onStop?: () => void;
+  /** Whether the stop button is shown instead of the send button. @default false */
+  isStopShown?: boolean;
+  /** Controlled value of the input */
+  value?: string;
+  /** Called when the input value changes */
+  onChange?: (value: string) => void;
+  /** Placeholder text for the input */
+  placeholder?: string;
+  /** Whether the composer is disabled */
+  isDisabled?: boolean;
+  /** Density variant */
+  density?: ChatComposerDensity;
+  /**
+   * Resting elevation of the composer body. `low` (the default) keeps today's
+   * raised look — low at rest, bumping to med on hover / focus. `none` flattens
+   * it and draws a border with the same rest / hover / focus treatment as a
+   * text input (emphasized border → accent on focus, with matching inset rings).
+   * @default 'low'
+   */
+  elevation?: 'none' | 'low';
+
+  // --- Slot props ---
+
+  /** Collapsible drawer rendered above the input — attachments, context chips, etc. Use ChatComposerDrawer. */
+  drawer?: ReactNode;
+  /** Actions rendered on the left side of the header (e.g. attach, mention buttons). Use icon-only `size="sm"` buttons. */
+  headerActions?: ReactNode;
+  /** Contextual info rendered on the right side of the header (e.g. context window usage, ProgressBar). */
+  headerContext?: ReactNode;
+  /** Custom input element — replaces the default textarea */
+  input?: ReactNode;
+  /** Actions rendered on the left side of the footer. Use `size="md"` buttons to match the send button height. */
+  footerActions?: ReactNode;
+  /** Actions rendered to the left of the send button. Use `size="md"` buttons to match the send button height. */
+  sendActions?: ReactNode;
+  /** Custom send button — replaces the default */
+  sendButton?: ReactNode;
+  /** Status message rendered below (or above) the composer body */
+  status?: ChatComposerStatus;
+  /** Where to render the status. @default 'bottom' */
+  statusPosition?: 'top' | 'bottom';
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+  root: {
+    position: 'relative',
+    zIndex: 0,
+    isolation: 'isolate',
+    display: 'flex',
+    flexDirection: 'column',
+    // Component CSS vars — themeable via defineTheme({ components: { 'chat-composer': { base: {...} } } })
+    // Uses the dedicated chat radius (28px) rather than --radius-page, so chat
+    // rounding is decoupled from page-level containers but unchanged today. #2072
+    '--_chat-composer-radius': radiusVars['--radius-chat'],
+    '--_chat-composer-padding': spacingVars['--spacing-3'],
+    // Concentric radius: buttons follow the outer shell's curvature.
+    // Sets --_button-radius (not --radius-element) so only buttons are
+    // affected — other components in slots keep their own radius.
+    // Default: 28px - 12px = 16px (fully rounds a 32px button).
+    '--_button-radius': `max(${radiusVars['--radius-element']}, calc(var(--_chat-composer-radius) - var(--_chat-composer-padding)))`,
+  },
+
+  rootDisabled: {
+    opacity: 0.6,
+    pointerEvents: 'none' as const,
+  },
+  body: {
+    position: 'relative',
+    zIndex: 2,
+    display: 'flex',
+    flexDirection: 'column',
+    padding: 'var(--_chat-composer-padding)',
+    gap: spacingVars['--spacing-2'],
+    borderRadius: 'var(--_chat-composer-radius)',
+    backgroundColor: colorVars['--color-background-popover'],
+    cursor: 'text',
+    transition: `box-shadow ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}, border-color ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,
+  },
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: spacingVars['--spacing-2'],
+    minHeight: '28px',
+  },
+  headerLeft: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+  },
+  headerRight: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    marginInlineStart: 'auto',
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    color: colorVars['--color-text-secondary'],
+  },
+  inputArea: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
+  textarea: {
+    all: 'unset',
+    width: '100%',
+    resize: 'none' as const,
+    fontSize: typeScaleVars['--text-body-size'],
+    lineHeight: typeScaleVars['--text-body-leading'],
+    fontFamily: typographyVars['--font-family-body'],
+    color: colorVars['--color-text-primary'],
+    backgroundColor: 'transparent',
+    caretColor: colorVars['--color-accent'],
+    overflowY: 'auto' as const,
+    maxHeight: '176px',
+    '::placeholder': {
+      color: colorVars['--color-text-disabled'],
+    },
+  },
+  footer: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: spacingVars['--spacing-2'],
+    // Footer buttons should use size="md" to match 32px send button height
+    minHeight: '32px',
+  },
+  footerLeft: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+  },
+  footerRight: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+  },
+  statusBar: {
+    position: 'relative',
+    zIndex: 0,
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    paddingInline: spacingVars['--spacing-4'],
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    fontFamily: typographyVars['--font-family-body'],
+  },
+  statusTop: {
+    paddingBlockStart: 'var(--_chat-composer-padding)',
+    paddingBlockEnd:
+      'calc(var(--_chat-composer-padding) + var(--_chat-composer-radius))',
+    marginBlockEnd: 'calc(-1 * var(--_chat-composer-radius))',
+    borderTopLeftRadius: 'var(--_chat-composer-radius)',
+    borderTopRightRadius: 'var(--_chat-composer-radius)',
+  },
+  statusBottom: {
+    paddingBlockStart:
+      'calc(var(--_chat-composer-padding) + var(--_chat-composer-radius))',
+    paddingBlockEnd: 'var(--_chat-composer-padding)',
+    marginBlockStart: 'calc(-1 * var(--_chat-composer-radius))',
+    borderBottomLeftRadius: 'var(--_chat-composer-radius)',
+    borderBottomRightRadius: 'var(--_chat-composer-radius)',
+  },
+  statusError: {
+    backgroundColor: colorVars['--color-error-muted'],
+    color: colorVars['--color-text-red'],
+  },
+  statusWarning: {
+    backgroundColor: colorVars['--color-warning-muted'],
+    color: colorVars['--color-text-yellow'],
+  },
+  compact: {
+    // Override the padding var (not the `padding` property) so both the base
+    // body padding and the border-inset calc in elevationStyles.none pick up
+    // the compact value. Scoped to the body element, so the status bar (which
+    // reads the var from root) keeps its own padding.
+    '--_chat-composer-padding': spacingVars['--spacing-2'],
+    gap: spacingVars['--spacing-1'],
+  },
+});
+
+// Resting elevation for the composer body, narrowed to two steps.
+// - `low` (default) preserves today's look: low at rest, bumping to med on
+//   hover / focus-within (a CSS-only interaction state the component owns).
+// - `none` is flat; depth comes from a border + inset rings instead. The
+//   border is drawn *inside* the padding — its width is subtracted from every
+//   side (like Card) so total inset (border + padding) equals the elevated
+//   case and content geometry is unchanged. Border color, hover, and focus
+//   states mirror TextInput (shared `inputWrapperStyles.base` treatment):
+//   emphasized border at rest → accent on focus-within, with the same inset
+//   shadow rings on hover and focus.
+const elevationStyles = stylex.create({
+  low: {
+    boxShadow: {
+      default: shadowVars['--shadow-low'],
+      ':hover': {'@media (hover: hover)': shadowVars['--shadow-med']},
+    },
+    ':focus-within': {
+      boxShadow: shadowVars['--shadow-med'],
+    },
+  },
+  none: {
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':focus-within': colorVars['--color-accent'],
+    },
+    // Draw the border *inside* the padding — subtract its width from the body
+    // padding (like Card's withBorder) so total inset (border + padding) equals
+    // the elevated case and content geometry is unchanged.
+    padding: `calc(var(--_chat-composer-padding) - ${borderVars['--border-width']})`,
+    boxShadow: {
+      default: 'none',
+      ':hover:not(:focus-within)': {
+        '@media (hover: hover)': `inset 0px 0px 0px 2px color-mix(in srgb, ${colorVars['--color-border-emphasized']} 30%, transparent)`,
+      },
+      ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Layout shell for a chat composer with slots for drawer, input,
+ * actions, and a send button.
+ *
+ * @example
+ * ```
+ * <ChatComposer
+ *   onSubmit={(value) => console.log(value)}
+ *   placeholder="Type a message..."
+ * />
+ * ```
+ */
+export function ChatComposer(props: ChatComposerProps) {
+  const t = useTranslator();
+  const {
+    ref,
+    onSubmit,
+    onStop,
+    isStopShown = false,
+    value: controlledValue,
+    onChange,
+    placeholder: placeholderFromProps,
+    isDisabled = false,
+    density = 'balanced',
+    elevation = 'low',
+    drawer,
+    headerActions,
+    headerContext,
+    input,
+    footerActions,
+    sendActions,
+    sendButton,
+    status,
+    statusPosition = 'bottom',
+    xstyle,
+    className,
+    style,
+    ...rest
+  } = props;
+  const placeholder =
+    placeholderFromProps ?? t('@pharos.chat.composer.placeholder');
+
+  const [internalValue, setInternalValue] = useState('');
+
+  const isControlled = controlledValue !== undefined;
+  const currentValue = isControlled ? controlledValue : internalValue;
+
+  const updateValue = useCallback(
+    (newValue: string) => {
+      if (!isControlled) {
+        setInternalValue(newValue);
+      }
+      onChange?.(newValue);
+    },
+    [isControlled, onChange],
+  );
+
+  const handleSubmit = useCallback(() => {
+    const trimmed = currentValue.trim();
+    if (!trimmed || isDisabled) {
+      return;
+    }
+    onSubmit(trimmed);
+    updateValue('');
+  }, [currentValue, isDisabled, onSubmit, updateValue]);
+
+  const canSend = currentValue.trim().length > 0 && !isDisabled;
+
+  const bodyRef = useRef<HTMLDivElement>(null);
+
+  // Input slot registers its focus (and future) control here so the shell can
+  // drive it without knowing its DOM shape. Stable ref — safe in the memoized
+  // context value.
+  const inputControlRef = useRef<ChatComposerInputControl | null>(null);
+
+  const handleBodyClick = useCallback((e: MouseEvent<HTMLDivElement>) => {
+    // Focus the input when clicking empty space in the body.
+    // Skip if the click target is a button, link, or interactive element.
+    const target = e.target as HTMLElement;
+    if (
+      target.closest(
+        'button, a, [role="button"], [contenteditable="true"], [data-pharos-token]',
+      )
+    ) {
+      return;
+    }
+    // Prefer the input's registered control (works for any input shape,
+    // including editors whose focusable node isn't a bare
+    // contenteditable/textarea). Fall back to a DOM query so uninstrumented
+    // custom inputs still get click-to-focus.
+    if (inputControlRef.current) {
+      inputControlRef.current.focus();
+      return;
+    }
+    const editable = bodyRef.current?.querySelector<HTMLElement>(
+      '[contenteditable="true"], textarea',
+    );
+    editable?.focus();
+  }, []);
+
+  const statusEl = status ? (
+    <div
+      role={status.type === 'error' ? 'alert' : 'status'}
+      {...stylex.props(
+        styles.statusBar,
+        statusPosition === 'top' ? styles.statusTop : styles.statusBottom,
+        status.type === 'error' && styles.statusError,
+        status.type === 'warning' && styles.statusWarning,
+      )}>
+      <Icon
+        icon={status.type === 'error' ? 'error' : 'warning'}
+        size="md"
+        color={status.type === 'error' ? 'error' : 'warning'}
+      />
+      {status.message}
+    </div>
+  ) : null;
+
+  const composerContext = useMemo(
+    () => ({
+      value: currentValue,
+      onChange: updateValue,
+      onSubmit: handleSubmit,
+      placeholder,
+      isDisabled,
+      isStopShown,
+      canSend,
+      onStop,
+      inputControlRef,
+    }),
+    [
+      currentValue,
+      updateValue,
+      handleSubmit,
+      placeholder,
+      isDisabled,
+      isStopShown,
+      canSend,
+      onStop,
+    ],
+  );
+
+  return (
+    <ChatComposerContext value={composerContext}>
+      <div
+        ref={ref}
+        {...mergeProps(
+          themeProps('chat-composer', {density}),
+          stylex.props(styles.root, isDisabled && styles.rootDisabled),
+          className,
+          style,
+        )}
+        {...rest}>
+        {statusPosition === 'top' && statusEl}
+        {drawer}
+
+        <div
+          ref={bodyRef}
+          onClick={handleBodyClick}
+          {...stylex.props(
+            styles.body,
+            elevationStyles[elevation],
+            density === 'compact' && styles.compact,
+            xstyle,
+          )}>
+          {(headerActions || headerContext) && (
+            <div {...stylex.props(styles.header)}>
+              <div {...stylex.props(styles.headerLeft)}>{headerActions}</div>
+              <div {...stylex.props(styles.headerRight)}>{headerContext}</div>
+            </div>
+          )}
+
+          <div {...stylex.props(styles.inputArea)}>
+            {input ?? <ChatComposerInput />}
+          </div>
+
+          <div {...stylex.props(styles.footer)}>
+            <div {...stylex.props(styles.footerLeft)}>{footerActions}</div>
+            <div {...stylex.props(styles.footerRight)}>
+              {sendActions}
+              {sendButton ?? <ChatSendButton />}
+            </div>
+          </div>
+        </div>
+
+        {statusPosition === 'bottom' && statusEl}
+      </div>
+    </ChatComposerContext>
+  );
+}
+
+ChatComposer.displayName = 'ChatComposer';

package/src/Chat/ChatComposerDrawer.doc.mjs

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'ChatComposerDrawer',
+  subComponentOf: 'Chat',
+  displayName: 'Chat Composer Drawer',
+  isHiddenFromOverview: true,
+  description: "Collapsible drawer panel that sits above the chat input inside ChatComposer. Pass it to the composer's `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle: collapsed state shows a badge and label, expanded state shows all children.",
+  playground: {
+    wrapper: {component: 'Stack', props: {width: 480}},
+    defaults: {
+      count: 3,
+      label: 'Attachments',
+      children: [
+        {__element: 'Token', props: {label: 'design-spec.pdf'}},
+        {__element: 'Token', props: {label: 'api-schema.json'}},
+        {__element: 'Token', props: {label: 'screenshot.png'}},
+      ],
+    },
+  },
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Content to render inside the drawer: tokens, chips, previews, or any React elements.',
+      required: true,
+    },
+    {
+      name: 'count',
+      type: 'number',
+      description: 'Total item count shown in the collapsed badge. When provided, the drawer gains a collapse/expand toggle.',
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Label shown next to the count in collapsed state.',
+      default: "'Items'",
+    },
+    {
+      name: 'isCollapsed',
+      type: 'boolean',
+      description: 'Controlled collapsed state. Use with `onCollapsedChange` for external control.',
+    },
+    {
+      name: 'defaultIsCollapsed',
+      type: 'boolean',
+      description: 'Initial collapsed state for uncontrolled usage.',
+      default: 'false',
+    },
+    {
+      name: 'onCollapsedChange',
+      type: '(isCollapsed: boolean) => void',
+      description: 'Callback fired when the user toggles the drawer.',
+    },
+  ],
+};
+
+export const docsZh = {
+  name: 'ChatComposerDrawer',
+  isHiddenFromOverview: true,
+  displayName: 'Chat Composer Drawer',
+  description: '位于聊天输入上方的可折叠抽屉面板。传入 ChatComposer 的 `drawer` 插槽，用于显示附件、上下文标签或预览内容。提供 `count` 时启用折叠切换。',
+  propDescriptions: {
+    children: '抽屉内渲染的内容——标记、标签、预览或任何 React 元素。',
+    count: '折叠徽章中显示的总数。提供时，抽屉获得折叠/展开切换。',
+    label: '折叠状态下显示在数量旁边的标签。',
+    isCollapsed: '受控折叠状态。与 onCollapsedChange 一起使用。',
+    defaultIsCollapsed: '非受控模式的初始折叠状态。',
+    onCollapsedChange: '用户切换抽屉时触发的回调。',
+  },
+};
+
+export const docsDense = {
+  name: 'ChatComposerDrawer',
+  isHiddenFromOverview: true,
+  displayName: 'Chat Composer Drawer',
+  description: 'collapsible drawer above chat input; pass to composer `drawer` slot for attachments, context chips, previews. `count` enables collapse toggle',
+  propDescriptions: {
+    children: 'drawer content: tokens, chips, previews, any React elements',
+    count: 'total count for collapsed badge; enables collapse/expand toggle',
+    label: 'collapsed label next to count badge',
+    isCollapsed: 'controlled collapsed state',
+    defaultIsCollapsed: 'initial collapsed state (uncontrolled)',
+    onCollapsedChange: 'callback on collapse toggle',
+  },
+};

package/src/Chat/ChatComposerDrawer.test.tsx

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {ChatComposerDrawer} from './ChatComposerDrawer';
+
+describe('ChatComposerDrawer', () => {
+  it('links the toggle to the drawer content via aria-controls', () => {
+    render(
+      <ChatComposerDrawer count={2} label="Attachments">
+        <span>Drawer content</span>
+      </ChatComposerDrawer>,
+    );
+
+    const toggle = screen.getByRole('button', {name: /Attachments/});
+    const controlsId = toggle.getAttribute('aria-controls');
+    // aria-controls must be present and point at the real content region.
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByText('Drawer content'));
+  });
+
+  it('keeps aria-controls resolvable while collapsed (content stays mounted)', () => {
+    render(
+      <ChatComposerDrawer count={2} label="Attachments" defaultIsCollapsed>
+        <span>Drawer content</span>
+      </ChatComposerDrawer>,
+    );
+
+    const toggle = screen.getByRole('button', {name: /Attachments/});
+    const controlsId = toggle.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByText('Drawer content'));
+  });
+
+  it('toggles aria-expanded when the toggle is activated', () => {
+    render(
+      <ChatComposerDrawer count={2} label="Attachments">
+        <span>Drawer content</span>
+      </ChatComposerDrawer>,
+    );
+
+    const toggle = screen.getByRole('button', {name: /Attachments/});
+    expect(toggle).toHaveAttribute('aria-expanded', 'true');
+
+    fireEvent.click(toggle);
+    expect(screen.getByRole('button', {name: /Attachments/})).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+
+    fireEvent.click(screen.getByRole('button', {name: /Attachments/}));
+    expect(screen.getByRole('button', {name: /Attachments/})).toHaveAttribute(
+      'aria-expanded',
+      'true',
+    );
+  });
+});