Prepared Docs

Overview

@prepared911/ui-ai-elements provides conversation UI primitives built on @prepared911/ui-core and the AI SDK message model. Chat is the assembled block: one owner of spacing, in form factors selected by ChatVariant (Default for near-full-screen chat with a floating reflowing composer over the transcript, Annotation for the compact popover with flat turns and a stacked docked composer). Form factor is chosen explicitly — never inferred from width — so both form factors can share a width and still use different chrome.

Individual elements (Message, PromptInput, Conversation, Response, CodeBlock, …) compose inside Chat or stand alone. CodeBlock is the fenced-code surface: language label, optional copy control, and Shiki dual-theme highlighting (github-light / github-dark-dimmed). Response routes markdown fences through CodeBlock; Tool uses it for JSON input and output.

Conversation keeps a bottom-pinned transcript attached as content streams and reconciles its scroll-button state when viewport or content geometry changes. User scrolling still releases the pin. Response renders blockquote prose with body-small typography so quoted context remains visually subordinate to the surrounding body-large response.

When to use

Assembled chat surfaces — use Chat whenever you need a transcript plus composer with consistent gutters across products (annotation popover, full-page assistant).
Assistant or user messages that include fenced code in markdown streamed through Response.
Tool invocation panels that need readable JSON for input or output (Tool).
Standalone code samples in AI product surfaces where operators need copy-to-clipboard and language-aware coloring.

When not to use

Hand-rolling chat layout with raw Conversation / Message / PromptInput spacing — prefer Chat so form-factor chrome stays in one place (CHAT_VARIANT_CHROME).
Docs-site MDX fences — the docs app already uses its own ShikiCode path; do not mount CodeBlock there for MDX.
Editable code editors — CodeBlock is display-only; use a product editor for write paths.
Inline identifiers — use markdown inline `code` (styled by Response), not a full CodeBlock.

Use cases

Mounting an annotation-popover agent chat with ChatVariant.Annotation so the stacked docked PromptInput chrome fits the narrow popover.
Mounting a full-page assistant with ChatVariant.Default so the composer floats over scrolling turns with a scrim that matches the nearest opaque parent background.
Passing prompt.chips for pinned context (files, records, tagged elements) above the typed area, with prompt.attach driving the leading add control when uploads are needed.
Pinning the context a message applies to with prompt.chips — tagged page elements, files, records — so the chips persist across sends and never leak into the submitted text.
Passing prompt.onStop with status="streaming" so the trailing composer control becomes a Secondary stop button that aborts generation, matching Cursor / ChatGPT / Claude.
Streaming a TypeScript snippet in an assistant reply and letting the operator copy it.
Showing a tool’s JSON arguments and result under a collapsible Tool accordion.
Previewing bash or JSON payloads in Storybook light and dark themes with the same token colors as the design docs.

Audio Player / Accessibility

AI Elements / API and Development

Overview

When to use

Assembled chat surfaces — use Chat whenever you need a transcript plus composer with consistent gutters across products (annotation popover, full-page assistant).
Assistant or user messages that include fenced code in markdown streamed through Response.
Tool invocation panels that need readable JSON for input or output (Tool).
Standalone code samples in AI product surfaces where operators need copy-to-clipboard and language-aware coloring.

When not to use

Hand-rolling chat layout with raw Conversation / Message / PromptInput spacing — prefer Chat so form-factor chrome stays in one place (CHAT_VARIANT_CHROME).
Docs-site MDX fences — the docs app already uses its own ShikiCode path; do not mount CodeBlock there for MDX.
Editable code editors — CodeBlock is display-only; use a product editor for write paths.
Inline identifiers — use markdown inline `code` (styled by Response), not a full CodeBlock.

Use cases

Mounting an annotation-popover agent chat with ChatVariant.Annotation so the stacked docked PromptInput chrome fits the narrow popover.
Mounting a full-page assistant with ChatVariant.Default so the composer floats over scrolling turns with a scrim that matches the nearest opaque parent background.
Passing prompt.chips for pinned context (files, records, tagged elements) above the typed area, with prompt.attach driving the leading add control when uploads are needed.
Pinning the context a message applies to with prompt.chips — tagged page elements, files, records — so the chips persist across sends and never leak into the submitted text.
Passing prompt.onStop with status="streaming" so the trailing composer control becomes a Secondary stop button that aborts generation, matching Cursor / ChatGPT / Claude.
Streaming a TypeScript snippet in an assistant reply and letting the operator copy it.
Showing a tool’s JSON arguments and result under a collapsible Tool accordion.
Previewing bash or JSON payloads in Storybook light and dark themes with the same token colors as the design docs.

Audio Player / Accessibility

AI Elements / API and Development