feat: add AttachmentGrid component

packages/@react-spectrum/ai/exports/index.ts

@@ -1,5 +1,6 @@
 export {Alert} from '../src/Alert';
 export {Attachment, AttachmentList, AttachmentPreview} from '../src/AttachmentList';
+export {AttachmentGrid, AttachmentGridItem} from '../src/AttachmentGrid';
 export {MessageFeedback} from '../src/MessageFeedback';
 export {MessageSource, SourceList, SourceListItem} from '../src/MessageSource';
 export {MessageSuggestion, MessageSuggestionList} from '../src/MessageSuggestion';
@@ -44,6 +45,7 @@ export type {
   AttachmentListProps,
   AttachmentPreviewProps
 } from '../src/AttachmentList';
+export type {AttachmentGridProps, AttachmentGridItemProps} from '../src/AttachmentGrid';
 export type {
   PromptFieldProps,
   PromptFieldSubmitButtonProps,

packages/@react-spectrum/ai/src/AttachmentGrid.tsx

@@ -0,0 +1,154 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {AriaLabelingProps, DOMProps, DOMRef, forwardRefType} from '@react-types/shared';
+import {
+  AttachmentCard,
+  AttachmentPreviewContext,
+  AttachmentRenderProps,
+  isAttachmentLoading
+} from './AttachmentList';
+import {css, focusRing, style} from '@react-spectrum/s2/style' with {type: 'macro'};
+import {forwardRef, ReactNode} from 'react';
+import {ListBox, ListBoxItem, ListBoxItemProps, ListBoxProps} from 'react-aria-components/ListBox';
+import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
+import {scrollFade} from './tokens.macro' with {type: 'macro'};
+import {StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
+import {useDOMRef} from './useDOMRef';
+
+export interface AttachmentGridProps<T>
+  extends
+    DOMProps,
+    AriaLabelingProps,
+    Pick<ListBoxProps<T>, 'items' | 'children' | 'dependencies'> {
+  /**
+   * Spectrum-defined styles, returned by the `style()` macro.
+   */
+  styles?: StyleString;
+}
+
+// Cards with title/description content (see AttachmentList.tsx's identical selector) need
+// room for text, so they get a much wider column track than bare thumbnails.
+const hasContent = ':has([data-slot=content])';
+
+const gridStyles = style({
+  display: 'grid',
+  gridTemplateColumns: {
+    default: 'repeat(auto-fill, minmax(64px, 1fr))',
+    [hasContent]: 'repeat(auto-fill, minmax(240px, 1fr))'
+  },
+  maxHeight: 240,
+  overflowY: 'auto',
+  overflowX: 'clip',
+  scrollbarWidth: {
+    '@supports (animation-timeline: scroll())': 'none'
+  },
+  boxSizing: 'border-box',
+  ...focusRing()
+});
+
+const gridGap = css('gap: 6px;');
+
+/**
+ * An AttachmentGrid displays file attachments as a wrapping, vertically-scrolling grid of
+ * thumbnails. Unlike AttachmentList, it is display-only and does not support selection or removal.
+ * Every attachment is disabled, so the grid itself becomes the sole tab stop, keeping the
+ * overflow area keyboard-scrollable without letting individual attachments be focused or actioned.
+ */
+export const AttachmentGrid = (forwardRef as forwardRefType)(function AttachmentGrid<T>(
+  props: AttachmentGridProps<T>,
+  ref: DOMRef<HTMLDivElement>
+) {
+  let {styles, items, children, dependencies, ...otherProps} = props;
+  let domRef = useDOMRef(ref);
+
+  return (
+    <ListBox
+      {...otherProps}
+      layout="grid"
+      items={items}
+      dependencies={dependencies}
+      ref={domRef}
+      className={renderProps =>
+        mergeStyles(gridStyles({...renderProps}), styles) +
+        ' ' +
+        gridGap +
+        ' ' +
+        scrollFade({y: 36})
+      }>
+      {children}
+    </ListBox>
+  );
+});
+
+export interface AttachmentGridItemProps
+  extends AriaLabelingProps, Pick<ListBoxItemProps, 'id' | 'textValue'> {
+  /** The size of the Card. */
+  size?: 'XS' | 'S' | 'M' | 'L' | 'XL';
+  /** Whether the attachment has an error. */
+  isInvalid?: boolean;
+  uploadProgress?: number;
+  /** The children of the AttachmentGridItem. */
+  children: ReactNode | ((renderProps: AttachmentRenderProps) => ReactNode);
+  /**
+   * Spectrum-defined styles, returned by the `style()` macro.
+   */
+  styles?: StyleString;
+}
+
+const itemStyles = style({
+  flexShrink: 0,
+  flexGrow: 0,
+  position: 'relative',
+  borderRadius: 'lg'
+});
+
+/**
+ * AttachmentGridItem displays an individual file attachment thumbnail within an AttachmentGrid.
+ */
+export const AttachmentGridItem = forwardRef(function AttachmentGridItem(
+  props: AttachmentGridItemProps,
+  ref: DOMRef<HTMLDivElement>
+) {
+  let {
+    id,
+    textValue,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
+    'aria-describedby': ariaDescribedby,
+    styles,
+    isInvalid,
+    children,
+    size = 'M'
+  } = props;
+  let domRef = useDOMRef(ref);
+  let isLoading = isAttachmentLoading(props.uploadProgress);
+
+  return (
+    <ListBoxItem
+      id={id}
+      textValue={textValue}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledby}
+      aria-describedby={ariaDescribedby}
+      isDisabled
+      ref={domRef}
+      className={mergeStyles(itemStyles, styles)}>
+      <AttachmentCard size={size} isInvalid={isInvalid} isLoading={isLoading}>
+        <AttachmentPreviewContext.Provider
+          value={{isInvalid: !!isInvalid, uploadProgress: props.uploadProgress ?? 100, size}}>
+          {typeof children === 'function' ? children({size}) : children}
+        </AttachmentPreviewContext.Provider>
+      </AttachmentCard>
+    </ListBoxItem>
+  );
+});

packages/@react-spectrum/ai/src/AttachmentList.tsx

@@ -60,11 +60,16 @@ import {useDOMRef} from './useDOMRef';
 import {useLocale} from 'react-aria/I18nProvider';
 import {useLocalizedStringFormatter} from 'react-aria/useLocalizedStringFormatter';
 
-interface AttachmentRenderProps {
+export interface AttachmentRenderProps {
   /** The size of the Card. */
   size: 'XS' | 'S' | 'M' | 'L' | 'XL';
 }
 
+/** Whether an attachment is still uploading, shared by Attachment and AttachmentGridItem. */
+export function isAttachmentLoading(uploadProgress?: number): boolean {
+  return uploadProgress != null && uploadProgress < 100;
+}
+
 const controlSizeM = {
   default: 32,
   size: {
@@ -545,7 +550,7 @@ interface AttachmentCardProps {
   children: ReactNode;
 }
 
-function AttachmentCard({
+export function AttachmentCard({
   size = 'M',
   isInvalid = false,
   isLoading = false,
@@ -625,7 +630,7 @@ export const Attachment = forwardRef(function Attachment(
     size = 'M'
   } = props;
   let domRef = useDOMRef(ref);
-  let isLoading = props.uploadProgress != null && props.uploadProgress < 100;
+  let isLoading = isAttachmentLoading(props.uploadProgress);
   return (
     <Tag
       id={id}
@@ -663,7 +668,7 @@ const attachmentPreviewWrapper = style({
   justifyContent: 'center'
 });
 
-const AttachmentPreviewContext = createContext({
+export const AttachmentPreviewContext = createContext({
   isInvalid: false,
   uploadProgress: 100,
   size: 'S' as 'XS' | 'S' | 'M' | 'L' | 'XL'

packages/@react-spectrum/ai/stories/AttachmentGrid.stories.tsx

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {AttachmentGrid, AttachmentGridItem, AttachmentGridItemProps} from '../src/AttachmentGrid';
+import {AttachmentPreview} from '../src/AttachmentList';
+import {Content} from '@react-spectrum/s2/Content';
+import type {Meta, StoryObj} from '@storybook/react';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+import {Text} from '@react-spectrum/s2/Text';
+
+interface AttachmentGridDemoProps extends Pick<
+  AttachmentGridItemProps,
+  'isInvalid' | 'uploadProgress' | 'size'
+> {
+  /** Number of demo attachments to render. */
+  count: number;
+  /** Whether to show title/description content below the thumbnail. */
+  showCardContent?: boolean;
+}
+
+function AttachmentGridDemo({
+  count,
+  isInvalid,
+  uploadProgress,
+  size,
+  showCardContent
+}: AttachmentGridDemoProps) {
+  return (
+    <AttachmentGrid aria-label="Uploaded files" styles={style({width: 'full'})}>
+      {Array.from({length: count}, (_, i) => (
+        <AttachmentGridItem
+          key={i}
+          uploadProgress={uploadProgress}
+          isInvalid={isInvalid}
+          size={size}
+          aria-label={`file-${i + 1}.pdf`}>
+          <AttachmentPreview
+            mimeType="application/pdf"
+            slot="thumbnail"
+            src={new URL('../../s2/stories/assets/placeholder.png', import.meta.url).toString()}
+          />
+          {showCardContent && (
+            <Content>
+              <Text slot="title">{`file-${i + 1}.pdf`}</Text>
+              <Text slot="description">PDF</Text>
+            </Content>
+          )}
+        </AttachmentGridItem>
+      ))}
+    </AttachmentGrid>
+  );
+}
+
+const meta: Meta<typeof AttachmentGridDemo> = {
+  component: AttachmentGridDemo,
+  parameters: {
+    layout: 'centered'
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    count: {table: {disable: true}},
+    isInvalid: {control: 'boolean'},
+    uploadProgress: {control: 'number', min: 0, max: 100},
+    size: {
+      control: 'radio',
+      options: ['XS', 'S', 'M', 'L', 'XL']
+    },
+    showCardContent: {control: 'boolean'}
+  },
+  args: {isInvalid: false, size: 'M', showCardContent: false},
+  title: 'AI/AttachmentGrid'
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AttachmentGridDemo>;
+
+export const AIAttachmentGrid: Story = {
+  render: args => (
+    <div style={{width: 320}}>
+      <AttachmentGridDemo {...args} count={5} />
+    </div>
+  )
+};
+
+export const Overflow: Story = {
+  name: 'Overflow (vertical scroll fade)',
+  render: args => (
+    <div style={{width: 320, resize: 'horizontal', overflow: 'hidden'}}>
+      <AttachmentGridDemo {...args} count={20} />
+    </div>
+  )
+};

packages/@react-spectrum/ai/stories/UserMessage.stories.tsx

@@ -11,6 +11,8 @@
  */
 
 import {ActionMenu} from '@react-spectrum/s2/ActionMenu';
+import {AttachmentGrid, AttachmentGridItem} from '../src/AttachmentGrid';
+import {AttachmentPreview} from '../src/AttachmentList';
 import {categorizeArgTypes} from '../../s2/stories/utils';
 import {Heading} from '@react-spectrum/s2/Heading';
 import {Image} from '@react-spectrum/s2/Image';
@@ -86,6 +88,26 @@ export const WithImage: Story = {
   )
 };
 
+export const WithAttachmentGrid: Story = {
+  render: args => (
+    <UserMessage {...args} styles={style({width: 518})}>
+      <div className={style({display: 'flex', flexDirection: 'column', gap: 8, width: 'full'})}>
+        <AttachmentGrid aria-label="Uploaded files" styles={style({width: 'full'})}>
+          {Array.from({length: 20}, (_, i) => (
+            <AttachmentGridItem key={i} aria-label={`file-${i + 1}.pdf`}>
+              <AttachmentPreview
+                mimeType="application/pdf"
+                slot="thumbnail"
+                src={new URL('../../s2/stories/assets/placeholder.png', import.meta.url).toString()}
+              />
+            </AttachmentGridItem>
+          ))}
+        </AttachmentGrid>
+      </div>
+    </UserMessage>
+  )
+};
+
 export const WithCard: Story = {
   render: args => (
     <div style={{width: 300}}>