feat: AttachmentPrimitive (#838)

.changeset/hip-trainers-draw.md

@@ -0,0 +1,5 @@
+---
+"@assistant-ui/react": patch
+---
+
+feat: AttachmentPrimitive

apps/docs/content/docs/ui/primitives/Attachment.mdx

@@ -0,0 +1,113 @@
+---
+title: ActionBar
+---
+
+Buttons to interact with attachments.
+
+import { ParametersTable, DataAttributesTable } from "@/components/docs";
+import { Code } from "@radix-ui/themes";
+import { Callout } from "fumadocs-ui/components/callout";
+
+<Callout>
+  **Dual Use!** Attachments can appear in both messages and composers.
+</Callout>
+
+## Anatomy
+
+```tsx
+import { AttachmentPrimitive } from "@assistant-ui/react";
+
+const MyMessageAttachment = () => (
+  <AttachmentPrimitive.Root>
+    <AttachmentPrimitive.Thumbnail />
+    <AttachmentPrimitive.Name />
+  </AttachmentPrimitive.Root>
+);
+
+const MyComposerAttachment = () => (
+  <AttachmentPrimitive.Root>
+    <AttachmentPrimitive.Thumbnail />
+    <AttachmentPrimitive.Name />
+    <AttachmentPrimitive.Remove />
+  </AttachmentPrimitive.Root>
+);
+```
+
+## API Reference
+
+### Container
+
+Containts all parts of the attachment.
+
+This primitive renders a `<div>` element unless `asChild` is set.
+
+<ParametersTable
+  type="AttachmentPrimitiveRootProps"
+  parameters={[
+    {
+      name: "asChild",
+    },
+  ]}
+/>
+
+### Thumbnail
+
+The thumbnail of the attachment.
+
+This primitive renders a `<div>` element unless `asChild` is set.
+
+<ParametersTable
+  type="AttachmentPrimitiveThumbnailProps"
+  parameters={[
+    {
+      name: "asChild",
+    },
+  ]}
+/>
+
+### Name
+
+The name of the attachment.
+
+This primitive renders a `<div>` element unless `asChild` is set.
+
+<ParametersTable
+  type="AttachmentPrimitiveNameProps"
+  parameters={[
+    {
+      name: "asChild",
+    },
+  ]}
+/>
+
+### Remove
+
+Removes the attachment.
+
+This primitive renders a `<button>` element unless `asChild` is set.
+
+<ParametersTable
+  type="AttachmentPrimitiveRemoveProps"
+  parameters={[
+    {
+      name: "asChild",
+    },
+  ]}
+/>
+
+#### `useAttachmentRemove`
+
+Provides the `Remove` functionality as a hook.
+
+```tsx
+import { useAttachmentRemove } from "@assistant-ui/react";
+
+const Remove = () => {
+  const remove = useAttachmentRemove();
+
+  // remove action is not available
+  if (!remove) return null;
+
+  return <button onClick={remove}>Remove</button>;
+};
+```

packages/react/src/primitive-hooks/attachment/useAttachmentRemove.ts

@@ -0,0 +1,12 @@
+import { useCallback } from "react";
+import { useAttachmentRuntime } from "../../context/react/AttachmentContext";
+
+export const useAttachmentRemove = () => {
+  const attachmentRuntime = useAttachmentRuntime();
+
+  const handleRemoveAttachment = useCallback(() => {
+    attachmentRuntime.remove();
+  }, [attachmentRuntime]);
+
+  return handleRemoveAttachment;
+};

packages/react/src/primitives/attachment/AttachmentName.tsx

@@ -0,0 +1,17 @@
+"use client";
+
+import type { FC } from "react";
+import { useAttachment } from "../../context/react/AttachmentContext";
+
+export namespace AttachmentPrimitiveName {
+  export type Props = Record<string, never>;
+}
+
+export const AttachmentPrimitiveName: FC<
+  AttachmentPrimitiveName.Props
+> = () => {
+  const name = useAttachment((a) => a.name);
+  return <>{name}</>;
+};
+
+AttachmentPrimitiveName.displayName = "AttachmentPrimitive.Name";

packages/react/src/primitives/attachment/AttachmentRemove.tsx

@@ -0,0 +1,16 @@
+"use client";
+
+import { useAttachmentRemove } from "../../primitive-hooks/attachment/useAttachmentRemove";
+import {
+  ActionButtonProps,
+  createActionButton,
+} from "../../utils/createActionButton";
+
+export namespace AttachmentPrimitiveRemove {
+  export type Props = ActionButtonProps<typeof useAttachmentRemove>;
+}
+
+export const AttachmentPrimitiveRemove = createActionButton(
+  "AttachmentPrimitive.Remove",
+  useAttachmentRemove,
+);

packages/react/src/primitives/attachment/AttachmentRoot.tsx

@@ -0,0 +1,18 @@
+import { Primitive } from "@radix-ui/react-primitive";
+import { ComponentPropsWithoutRef, ElementRef, forwardRef } from "react";
+
+type PrimitiveDivProps = ComponentPropsWithoutRef<typeof Primitive.div>;
+type AttachmentPrimitiveRootElement = ElementRef<typeof Primitive.div>;
+
+export namespace AttachmentPrimitiveRoot {
+  export type Props = PrimitiveDivProps;
+}
+
+export const AttachmentPrimitiveRoot = forwardRef<
+  AttachmentPrimitiveRootElement,
+  AttachmentPrimitiveRoot.Props
+>((props, ref) => {
+  return <Primitive.div {...props} ref={ref} />;
+});
+
+AttachmentPrimitiveRoot.displayName = "AttachmentPrimitive.Root";

packages/react/src/primitives/attachment/AttachmentThumb.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import { ComponentPropsWithoutRef, forwardRef, type ElementRef } from "react";
+import { useAttachment } from "../../context/react/AttachmentContext";
+import { Primitive } from "@radix-ui/react-primitive";
+
+type AttachmentPrimitiveThumbElement = ElementRef<typeof Primitive.div>;
+type PrimitiveDivProps = ComponentPropsWithoutRef<typeof Primitive.div>;
+
+export namespace AttachmentPrimitiveThumb {
+  export type Props = PrimitiveDivProps;
+}
+
+export const AttachmentPrimitiveThumb = forwardRef<
+  AttachmentPrimitiveThumbElement,
+  AttachmentPrimitiveThumb.Props
+>(() => {
+  const ext = useAttachment((a) => a.name.split(".").pop());
+  return <Primitive.div>.{ext}</Primitive.div>;
+});
+
+AttachmentPrimitiveThumb.displayName = "AttachmentPrimitive.Thumb";

packages/react/src/primitives/attachment/index.ts

@@ -0,0 +1,4 @@
+export { AttachmentPrimitiveRoot as Root } from "./AttachmentRoot";
+export { AttachmentPrimitiveThumb as unstable_Thumb } from "./AttachmentThumb";
+export { AttachmentPrimitiveName as Name } from "./AttachmentName";
+export { AttachmentPrimitiveRemove as Remove } from "./AttachmentRemove";

packages/react/src/primitives/index.ts

@@ -1,5 +1,6 @@
 export * as ActionBarPrimitive from "./actionBar";
 export * as AssistantModalPrimitive from "./assistantModal";
+export * as AttachmentPrimitive from "./attachment";
 export * as BranchPickerPrimitive from "./branchPicker";
 export * as ComposerPrimitive from "./composer";
 export * as ContentPartPrimitive from "./contentPart";

packages/react/src/ui/composer-attachment.tsx

@@ -8,23 +8,18 @@ import {
   TooltipIconButton,
   TooltipIconButtonProps,
 } from "./base/tooltip-icon-button";
-import {
-  useAttachmentRuntime,
-  useThreadComposerAttachment,
-} from "../context/react/AttachmentContext";
+import { AttachmentPrimitive } from "../primitives";
 
-const ComposerAttachmentRoot = withDefaults("div", {
+const ComposerAttachmentRoot = withDefaults(AttachmentPrimitive.Root, {
   className: "aui-composer-attachment-root",
 });
 
 ComposerAttachmentRoot.displayName = "ComposerAttachmentRoot";
 
 const ComposerAttachment: FC = () => {
-  const attachment = useThreadComposerAttachment((a) => a.attachment);
-
   return (
     <ComposerAttachmentRoot>
-      .{attachment.name.split(".").pop()}
+      <AttachmentPrimitive.unstable_Thumb />
       <ComposerAttachmentRemove />
     </ComposerAttachmentRoot>
   );
@@ -42,22 +37,18 @@ const ComposerAttachmentRemove = forwardRef<
     } = {},
   } = useThreadConfig();
 
-  const attachmentRuntime = useAttachmentRuntime();
-  const handleRemoveAttachment = () => {
-    attachmentRuntime.remove();
-  };
-
   return (
-    <TooltipIconButton
-      tooltip={tooltip}
-      className="aui-composer-attachment-remove"
-      side="top"
-      {...props}
-      onClick={handleRemoveAttachment}
-      ref={ref}
-    >
-      {props.children ?? <CircleXIcon />}
-    </TooltipIconButton>
+    <AttachmentPrimitive.Remove asChild>
+      <TooltipIconButton
+        tooltip={tooltip}
+        className="aui-composer-attachment-remove"
+        side="top"
+        {...props}
+        ref={ref}
+      >
+        {props.children ?? <CircleXIcon />}
+      </TooltipIconButton>
+    </AttachmentPrimitive.Remove>
   );
 });
 

packages/react/src/ui/user-message-attachment.tsx

@@ -3,20 +3,18 @@
 import { type FC } from "react";
 
 import { withDefaults } from "./utils/withDefaults";
-import { useAttachment } from "../context/react/AttachmentContext";
+import { AttachmentPrimitive } from "../primitives";
 
-const UserMessageAttachmentRoot = withDefaults("div", {
+const UserMessageAttachmentRoot = withDefaults(AttachmentPrimitive.Root, {
   className: "aui-user-message-attachment-root",
 });
 
 UserMessageAttachmentRoot.displayName = "UserMessageAttachmentRoot";
 
 const UserMessageAttachment: FC = () => {
-  const attachment = useAttachment((a) => a.attachment);
-
   return (
     <UserMessageAttachmentRoot>
-      .{attachment.name.split(".").pop()}
+      <AttachmentPrimitive.unstable_Thumb />
     </UserMessageAttachmentRoot>
   );
 };