export const title = "Messaging components"
export const description = "Powerful and customizable React messaging components built for modern applications and websites. These messaging components are built using React Aria and styled with Tailwind CSS."

import * as Demos from "@/components/application/messaging/messaging.story.tsx";

<PreviewAndCode title="Messaging example" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">        
        <div className="scrollbar-hide h-full w-full overflow-auto py-10 px-4">
            <div className="sm:mx-auto w-full sm:max-w-md">
                <Demos.MessagesDefaultDemo />
            </div>
        </div>
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode className="scrollbar-hide max-h-[720px]" component="messaging/MessagesDefaultDemo" />
    </TabPanel>
</PreviewAndCode>

<Divider />

## Installation

Messaging component depends on other components to function properly. Before using them, make sure to add the required components via CLI.

Use the following command to install them:

<Tabs className="w-full mt-8">
    <TabList type="underline" items={[{ id:'cli', label:'CLI' }, { id:'manual', label:'Manual' }]} />

    <TabPanel id="cli" className="mt-8">
        ```bash
        npx untitledui@latest add messaging
        ```
    </TabPanel>

    <TabPanel id="manual">
        <Steps>
            <Step title="Copy component files">
                Copy the files below into your project:

                <ComponentCodeTabs component="application/messaging" />
            </Step>
            <Step title="Start using the components">
                Great! Now you can start using the messaging components in your project by just copy/pasting our examples below.
            </Step>
        </Steps>
    </TabPanel>
</Tabs>

<Divider />

## Message status

In order to display the message status separately, you can use the `MessageStatus` component. It accepts the `status` prop which can be one of the following:

- `sent`
- `read`
- `failed`

Optionally, you can also pass the `readAt` prop to display the date and time when the message was read.

<PreviewAndCode title="Message status" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageStatus />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageStatusDemo" />
    </TabPanel>
</PreviewAndCode>

<Divider />

## Message action examples

Below are examples and variations of this message action component:

### Message action minimal {{ tocOnly:true }}

<PreviewAndCode title="Message action minimal" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageActionMinimal />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="message-action/MessageActionMinimal" />
    </TabPanel>
</PreviewAndCode>

### Message action textarea {{ tocOnly:true }}

<PreviewAndCode title="Message action textarea" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageActionTextarea />
    </ResizablePreview> 
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="message-action/MessageActionTextarea" />
    </TabPanel>
</PreviewAndCode>

### Message action advanced {{ tocOnly:true }}

<PreviewAndCode title="Message action advanced" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageActionAdvanced />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="message-action/MessageActionAdvanced" />
    </TabPanel>
</PreviewAndCode>

<Divider />

## Message examples

Below are examples and variations of this message component:

### Message simple {{ tocOnly:true }}

<PreviewAndCode title="Message simple" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemSimpleDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemSimpleDemo" />
    </TabPanel>
</PreviewAndCode>

### Message reactions {{ tocOnly:true }}

<PreviewAndCode title="Message reactions" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemReactionsDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemReactionsDemo" />
    </TabPanel>
</PreviewAndCode>

### Message reply {{ tocOnly:true }}

<PreviewAndCode title="Message reply" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemReplyDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemReplyDemo" />
    </TabPanel>
</PreviewAndCode>

### Message attachment {{ tocOnly:true }}

<PreviewAndCode title="Message attachment" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemAttachmentDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemAttachmentDemo" />
    </TabPanel>
</PreviewAndCode>

### Message audio {{ tocOnly:true }}

<PreviewAndCode title="Message audio" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemAudioDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemAudioDemo" />
    </TabPanel>
</PreviewAndCode>

### Message image {{ tocOnly:true }}

<PreviewAndCode title="Message image" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemImageDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemImageDemo" />
    </TabPanel>
</PreviewAndCode>

### Message link preview {{ tocOnly:true }}

<PreviewAndCode title="Message link preview" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemLinkPreviewDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemLinkPreviewDemo" />
    </TabPanel>
</PreviewAndCode>

### Message link minimal {{ tocOnly:true }}

<PreviewAndCode title="Message link minimal" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemLinkMinimalDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemLinkMinimalDemo" />
    </TabPanel>
</PreviewAndCode>


### Message writing {{ tocOnly:true }}

<PreviewAndCode title="Message writing" isPublic={false}>
    <ResizablePreview id="preview" className="relative flex px-4 md:px-8 py-32 min-h-[320px] items-center justify-center gap-3 rounded-[20px] ring-1 ring-inset ring-secondary bg-primary">
        <Demos.MessageItemWritingDemo />
    </ResizablePreview>
    <TabPanel id="code" className="min-h-(--preview-height)">
        <ComponentCode component="messaging/MessageItemWritingDemo" />
    </TabPanel>
</PreviewAndCode>

<Divider />

## API reference

<ApiReference slug="messaging" />

<Divider />

<FAQ
    faqs={[
        {
            question: "What shape does a message object need?",
            answer: "`MessageItem` takes a single `msg` prop typed as `Message`. Only `id` is required; everything else is optional — `text`, `sentAt`, `readAt`, `status`, `typing`, a `user` object, and the content payloads `image`, `audio`, `attachment`, `reply`, `urlPreview` and `reactions`. `reply` and `urlPreview` only render on a message that also has `text`. Because `MessageItem` renders an `<li>`, map your messages inside your own `<ol>` or `<ul>` and give that list an `aria-label` such as `\"Conversation\"`.",
        },
        {
            question: "How do I show a message as sent by the current user?",
            answer: "Set `me: true` inside the message's `user` object. The bubble then aligns to the right with `self-end`, uses the primary background with a squared top-right corner, and the sender label reads \"You\" instead of `user.name`. Avatars are only rendered for messages from other people.",
        },
        {
            question: "How do I display sent and read receipts?",
            answer: "Set `status` on the message to `\"sent\"`, `\"read\"` or `\"failed\"` and the status icon renders next to the timestamp. Add `readAt` and it is appended to the tooltip on a read message. You can also render the indicator on its own with `<MessageStatus status=\"read\" readAt=\"2:20 PM\" />` — the message status example above renders all three states that way.",
        },
        {
            question: "Can messages contain images, files or voice notes?",
            answer: "Yes. Pass `image` as `{ src, alt, name, size }`, `attachment` as `{ name, size, type }` where `type` is one of `\"jpg\"`, `\"txt\"`, `\"pdf\"` or `\"mp4\"` (it selects the file icon), and `audio` as `{ duration }`, which renders a waveform with a play button. `size` and `duration` are display strings, not raw byte counts, and the audio playback button is a UI shell — wire up your own player.",
        },
        {
            question: "How do I show a typing indicator?",
            answer: "Add an entry with `typing: true` and no `text` or other content, since any content would still render above the dots. `MessageItem` renders the animated three-dot bubble and hides the timestamp and status for that entry; the sender label still shows unless you set `showUserLabel={false}`.",
        },
        {
            question: "How do I hide the repeated sender name on consecutive messages?",
            answer: "Pass `showUserLabel={false}` to `MessageItem`. It defaults to `true`, so a common pattern is to only show the label on the first message in a run from the same sender.",
        },
        {
            question: "How do I read what the user typed in the composer?",
            answer: "The composers are example code rather than exported components — `MessageActionMinimal`, `MessageActionTextarea` and `MessageActionAdvanced` live in `message-action.demo.tsx`, so copy the one you want into your own project rather than importing it as part of the API. All three are uncontrolled forms with a field named `message`: they accept an `onSubmit` callback that is called with the message string after the form's default submission is prevented, and `MessageActionMinimal` additionally accepts a `size` of `\"sm\"`, `\"md\"` or `\"lg\"`, defaulting to `\"lg\"`.",
        },
    ]}
/>