@commercetools/nimbus 3.2.0 → 3.4.0

package/dist/components/chat-message/chat-message.recipe.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Recipe configuration for the ChatMessage compound component.
+ *
+ * Layout uses CSS Grid rather than a single flex row. The design places the
+ * avatar beside the body on the first row, with the (optional) meta row
+ * indented directly beneath the body — i.e. the avatar occupies only the
+ * first row while the body and meta stack in the same column. A flat flex
+ * row of `[avatar, body, meta]` cannot express that "meta aligns under
+ * the body" relationship, so we place each slot into an explicit grid cell.
+ * The `sender` variant swaps the columns (avatar leading vs. trailing), which
+ * is what "layout direction" resolves to for this component.
+ *
+ * `sender` and `tone` are orthogonal: `sender` (`user`/`agent`) owns the
+ * participant, layout direction and surface; `tone` (`neutral`/`error`) is a
+ * status overlay applied on top of whatever `sender` selected — an *agent*
+ * message can still *fail*, so error is a tone, not a sender. `tone` is
+ * declared after `sender` so its body bg/border win the merge.
+ *
+ * `sender` denotes only *which participant* sent the message. System notices
+ * are out of scope here — a system notice isn't a message, and it isn't a
+ * standardized component either; consumers render their own content (e.g. inside
+ * a `ChatMessageList.Item`). Tool/function output is content inside an
+ * `agent` message. Neither is a `sender` value.
+ *
+ * Token parity: the Figma variables (`spacing/600`, `border-radius/300`, …) map
+ * 1:1 onto the Nimbus design tokens (`spacing.600`, `radii.300`, …), so the
+ * values below mirror the design exactly.
+ */
+export declare const chatMessageSlotRecipe: import('@chakra-ui/react').SlotRecipeDefinition<"root" | "body" | "meta" | "actions" | "avatar" | "typing", {
+    sender: {
+        user: {
+            root: {
+                justifyContent: "end";
+            };
+            body: {
+                gridColumn: number;
+                justifySelf: "end";
+                maxWidth: "480px";
+                backgroundColor: "colorPalette.2";
+            };
+            avatar: {
+                gridColumn: number;
+                marginInlineStart: "200";
+            };
+            meta: {
+                gridColumn: number;
+            };
+        };
+        agent: {
+            root: {
+                justifyContent: "start";
+            };
+            body: {
+                gridColumn: number;
+                justifySelf: "start";
+                maxWidth: "632px";
+                backgroundColor: "bg";
+            };
+            avatar: {
+                gridColumn: number;
+                marginInlineEnd: "200";
+            };
+            meta: {
+                gridColumn: number;
+            };
+        };
+    };
+    tone: {
+        neutral: {};
+        error: {
+            body: {
+                backgroundColor: "critical.2";
+                borderColor: "critical.6";
+            };
+        };
+    };
+}>;

package/dist/components/chat-message/chat-message.slots.d.ts

@@ -0,0 +1,30 @@
+import { SlotComponent } from '../../type-utils/slot-types.js';
+import { ChatMessageRootSlotProps, ChatMessageAvatarSlotProps, ChatMessageBodySlotProps, ChatMessageActionsSlotProps, ChatMessageMetaSlotProps, ChatMessageTypingSlotProps } from './chat-message.types.js';
+/**
+ * Root slot — establishes the recipe context and owns the grid layout. The
+ * component defaults its rendered element to `<article>` (a feed item, per the
+ * ARIA APG); consumers can override via `as`.
+ */
+export declare const ChatMessageRootSlot: SlotComponent<HTMLDivElement, ChatMessageRootSlotProps>;
+/**
+ * Avatar slot — a layout wrapper for the interior Nimbus `Avatar`. The nested
+ * avatar's background/color are set per `sender` from the recipe.
+ */
+export declare const ChatMessageAvatarSlot: SlotComponent<HTMLDivElement, ChatMessageAvatarSlotProps>;
+/**
+ * Body slot — the rounded card that holds the message payload.
+ */
+export declare const ChatMessageBodySlot: SlotComponent<HTMLDivElement, ChatMessageBodySlotProps>;
+/**
+ * Actions slot — layout-only row for buttons, rendered inside the body.
+ */
+export declare const ChatMessageActionsSlot: SlotComponent<HTMLDivElement, ChatMessageActionsSlotProps>;
+/**
+ * Meta slot — layout-only row rendered below the body.
+ */
+export declare const ChatMessageMetaSlot: SlotComponent<HTMLDivElement, ChatMessageMetaSlotProps>;
+/**
+ * Typing slot — layout wrapper for the animated typing indicator (and an
+ * optional visible label), rendered inside the body while a reply streams.
+ */
+export declare const ChatMessageTypingSlot: SlotComponent<HTMLDivElement, ChatMessageTypingSlotProps>;

package/dist/components/chat-message/chat-message.types.d.ts

@@ -0,0 +1,116 @@
+import { OmitInternalProps } from '../../type-utils/omit-props.js';
+import { HTMLChakraProps, SlotRecipeProps, UnstyledProp } from '@chakra-ui/react/styled-system';
+import { AvatarProps } from '../avatar/avatar.types.js';
+import { ChatMessageSender } from './chat-message.context.js';
+type ChatMessageRecipeProps = {
+    /**
+     * Which participant sent the message. Controls layout direction (avatar side)
+     * and the sender-specific body/avatar styling:
+     *
+     * - `"agent"` (default) — agent voice, avatar leading.
+     * - `"user"` — the human, avatar trailing, `colorPalette.2` surface
+     *   (`primary` by default).
+     *
+     * `sender` denotes only *who* sent the message. System notices are out of
+     * scope — a system notice isn't a message, and it isn't a standardized
+     * component either; consumers render their own content (e.g. inside a
+     * `ChatMessageList.Item`). Tool/function output is content inside an
+     * `agent` message. Neither is a `sender` value.
+     *
+     * @default "agent"
+     */
+    sender?: SlotRecipeProps<"nimbusChatMessage">["sender"];
+    /**
+     * Status overlay, orthogonal to `sender`. `"error"` tints the body with the
+     * critical palette to flag a failed generation — an *agent* message can fail,
+     * so error is a tone rather than a sender.
+     * @default "neutral"
+     */
+    tone?: SlotRecipeProps<"nimbusChatMessage">["tone"];
+} & UnstyledProp;
+export type ChatMessageRootSlotProps = HTMLChakraProps<"div", ChatMessageRecipeProps>;
+export type ChatMessageAvatarSlotProps = HTMLChakraProps<"div">;
+export type ChatMessageBodySlotProps = HTMLChakraProps<"div">;
+export type ChatMessageActionsSlotProps = HTMLChakraProps<"div">;
+export type ChatMessageMetaSlotProps = HTMLChakraProps<"div">;
+export type ChatMessageTypingSlotProps = HTMLChakraProps<"div">;
+/** Props for the ChatMessage.Root component. */
+export type ChatMessageProps = Omit<OmitInternalProps<ChatMessageRootSlotProps>, "sender"> & {
+    children?: React.ReactNode;
+    /**
+     * Which participant sent the message — drives the layout direction and the
+     * per-sender styling. A single value only: a message's sender is fixed, so
+     * responsive/conditional values are intentionally not accepted (they would
+     * style the body per breakpoint while the avatar defaults could not follow).
+     * @default "agent"
+     */
+    sender?: ChatMessageSender;
+    /**
+     * Override the rendered element. Defaults to `"article"` (a feed item, per
+     * the ARIA APG); set e.g. `as="li"` when composing the message into a list.
+     */
+    as?: React.ElementType;
+    /**
+     * Marks the message as still being generated. Sets `aria-busy` on the root so
+     * assistive tech knows the content is in flux. The live-region announcement
+     * (e.g. wrapping the feed in `role="log" aria-live="polite"`) stays the
+     * consumer's responsibility — see the accessibility docs.
+     */
+    isStreaming?: boolean;
+    ref?: React.Ref<HTMLDivElement>;
+    [key: `data-${string}`]: unknown;
+};
+/**
+ * Props for the ChatMessage.Avatar component.
+ *
+ * Wraps the Nimbus {@link AvatarProps | Avatar}. Unless `variant` is set
+ * explicitly, it defaults per `sender` — `solid` for the `agent`, `subtle` for
+ * the `user`. The color palette comes from the recipe (`primary`), so consumers
+ * only provide the avatar content (initials, `src`, or an icon via `children`);
+ * an unconfigured avatar shows a generic person icon. Defaults to `size="xs"`
+ * (a 32px box per the Figma spec).
+ *
+ * The avatar is **decorative by default** (`aria-hidden`) — the sender is better
+ * conveyed by the message's accessible name and position than by a repeated
+ * "avatar" node. Provide `firstName`/`lastName` or an explicit `aria-label` to
+ * opt the avatar back into the accessibility tree with a meaningful name.
+ */
+export type ChatMessageAvatarProps = AvatarProps;
+/** Props for the ChatMessage.Body component. */
+export type ChatMessageBodyProps = OmitInternalProps<ChatMessageBodySlotProps> & {
+    /** Override the rendered element (e.g. `as="section"`). Defaults to a `div`. */
+    as?: React.ElementType;
+    children?: React.ReactNode;
+    ref?: React.Ref<HTMLDivElement>;
+    [key: `data-${string}`]: unknown;
+};
+/** Props for the ChatMessage.Actions component. */
+export type ChatMessageActionsProps = OmitInternalProps<ChatMessageActionsSlotProps> & {
+    /** Override the rendered element. Defaults to a `div`. */
+    as?: React.ElementType;
+    children?: React.ReactNode;
+    ref?: React.Ref<HTMLDivElement>;
+    [key: `data-${string}`]: unknown;
+};
+/** Props for the ChatMessage.Meta component. */
+export type ChatMessageMetaProps = OmitInternalProps<ChatMessageMetaSlotProps> & {
+    /** Override the rendered element (e.g. `as="footer"`). Defaults to a `div`. */
+    as?: React.ElementType;
+    children?: React.ReactNode;
+    ref?: React.Ref<HTMLDivElement>;
+    [key: `data-${string}`]: unknown;
+};
+/** Props for the ChatMessage.Typing component. */
+export type ChatMessageTypingProps = OmitInternalProps<ChatMessageTypingSlotProps> & {
+    /** Override the rendered element. Defaults to a `div`. */
+    as?: React.ElementType;
+    /**
+     * Optional visible label rendered beside the animated dots (e.g.
+     * "Agent is typing…"). The dots themselves are decorative
+     * (`aria-hidden`); any text you pass here is the accessible affordance.
+     */
+    children?: React.ReactNode;
+    ref?: React.Ref<HTMLDivElement>;
+    [key: `data-${string}`]: unknown;
+};
+export {};

package/dist/components/chat-message/components/chat-message.actions.d.ts

@@ -0,0 +1,12 @@
+import { ChatMessageActionsProps } from '../chat-message.types.js';
+/**
+ * ChatMessage.Actions - Layout-only row for action buttons inside the body.
+ *
+ * Renders a right-aligned, wrapping flex row. Consumers provide the buttons.
+ *
+ * @supportsStyleProps
+ */
+export declare const ChatMessageActions: {
+    ({ ref, children, ...props }: ChatMessageActionsProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/chat-message/components/chat-message.avatar.d.ts

@@ -0,0 +1,31 @@
+import { ChatMessageAvatarProps } from '../chat-message.types.js';
+/**
+ * ChatMessage.Avatar - The sender's avatar.
+ *
+ * Wraps the Nimbus `Avatar` (defaulting to `size="xs"`, a 32px box per the
+ * Figma spec). Unless the consumer sets `variant` explicitly, the variant
+ * defaults per `sender`: `solid` for the `agent` (a strong branded glyph) and
+ * `subtle` for the `user` (a softer surface that matches the user body's tint).
+ * The color *palette* comes from the ChatMessage recipe (`primary`), so
+ * consumers only supply the avatar content (initials via `firstName`/
+ * `lastName`, an image `src`, or a custom icon via `children`).
+ *
+ * An **unconfigured** avatar (no content supplied) falls back to a
+ * sender-appropriate generic glyph: the AI `AutoAwesome` sparkle for the
+ * `agent`, and the `Avatar`'s built-in person icon for the `user`.
+ *
+ * Props flow to the **inner `Avatar`**, not to the grid-cell wrapper — the
+ * wrapper only exists to occupy the avatar column.
+ *
+ * Accessibility: the avatar is **decorative by default** (`aria-hidden`). A
+ * sender glyph duplicates information better conveyed by the message's
+ * accessible name and column, and a nameless `Avatar` would otherwise announce
+ * a misleading generic label. Passing `firstName`/`lastName` or an explicit
+ * `aria-label` opts it back into the accessibility tree with a real name.
+ *
+ * @supportsStyleProps
+ */
+export declare const ChatMessageAvatar: {
+    ({ ref, size, variant, children, ...props }: ChatMessageAvatarProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/chat-message/components/chat-message.body.d.ts

@@ -0,0 +1,14 @@
+import { ChatMessageBodyProps } from '../chat-message.types.js';
+/**
+ * ChatMessage.Body - The rounded card that holds the message payload.
+ *
+ * Stacks its children vertically; place `ChatMessage.Actions` as the last child
+ * to pin action buttons to the bottom of the body. Background, padding,
+ * border-radius and max-width are set per `sender` by the recipe.
+ *
+ * @supportsStyleProps
+ */
+export declare const ChatMessageBody: {
+    ({ ref, children, ...props }: ChatMessageBodyProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/chat-message/components/chat-message.meta.d.ts

@@ -0,0 +1,15 @@
+import { ChatMessageMetaProps } from '../chat-message.types.js';
+/**
+ * ChatMessage.Meta - Layout-only row rendered below the body.
+ *
+ * Renders a `space-between` flex row aligned with the body. Consumers provide
+ * the content (timestamp, provenance/trust links, reaction icons). With a
+ * single child, `space-between` leaves it at the start of the row — pair it
+ * with a spacer or a second element to push content to the end.
+ *
+ * @supportsStyleProps
+ */
+export declare const ChatMessageMeta: {
+    ({ ref, children, ...props }: ChatMessageMetaProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/chat-message/components/chat-message.root.d.ts

@@ -0,0 +1,22 @@
+import { ChatMessageProps } from '../chat-message.types.js';
+/**
+ * ChatMessage.Root - The grid container for a single chat message.
+ *
+ * Establishes the styling context and lays out the avatar, body and optional
+ * meta row. The `sender` prop selects the layout direction (avatar leading for
+ * `"agent"`, trailing for `"user"`) and the sender-specific styling;
+ * `tone="error"` tints the body for a failed generation.
+ *
+ * Renders a semantic `<article>` by default (a feed item, per the ARIA APG) so
+ * a message is a discrete node in the accessibility tree. This is a *default*,
+ * not a mandate: override the element with `as` (e.g. `as="li"` inside a list)
+ * and name the message for assistive tech with `aria-label`/`aria-labelledby`.
+ * The surrounding feed / live region is the consumer's to compose — see the
+ * accessibility docs.
+ *
+ * @supportsStyleProps
+ */
+export declare const ChatMessageRoot: {
+    (props: ChatMessageProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/chat-message/components/chat-message.typing.d.ts

@@ -0,0 +1,20 @@
+import { ChatMessageTypingProps } from '../chat-message.types.js';
+/**
+ * ChatMessage.Typing - Animated "generating…" indicator for a streaming reply.
+ *
+ * Renders the Nimbus `ActivityIndicator` (three bouncing dots) inside the
+ * body while a response streams. Place it as the body's payload and swap it
+ * for the real content once the stream settles.
+ *
+ * Accessibility: the dots are decorative (`ActivityIndicator` is always
+ * `aria-hidden`). Pass a visible label as `children` (e.g. "Agent is
+ * typing…") for a per-message affordance, and/or set `isStreaming` on
+ * `ChatMessage.Root` (which sets `aria-busy`) — the coalesced live-region
+ * announcement stays with the consumer's feed/turn container.
+ *
+ * @supportsStyleProps
+ */
+export declare const ChatMessageTyping: {
+    ({ ref, children, ...props }: ChatMessageTypingProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/chat-message/components/index.d.ts

@@ -0,0 +1,6 @@
+export { ChatMessageRoot } from './chat-message.root.js';
+export { ChatMessageAvatar } from './chat-message.avatar.js';
+export { ChatMessageBody } from './chat-message.body.js';
+export { ChatMessageActions } from './chat-message.actions.js';
+export { ChatMessageMeta } from './chat-message.meta.js';
+export { ChatMessageTyping } from './chat-message.typing.js';

package/dist/components/chat-message/index.d.ts

@@ -0,0 +1,2 @@
+export * from './chat-message.js';
+export * from './chat-message.types.js';

package/dist/components/chat-message-list/chat-message-list.d.ts

@@ -0,0 +1,79 @@
+import { ChatMessageListRoot, ChatMessageListItem } from './components/index.js';
+/**
+ * ChatMessageList
+ * ============================================================
+ * A compound component that presents a **scrollable sequence of chat messages**
+ * and owns transcript-level scroll and announcement behavior. It is the second
+ * primitive in the `Chat*` family: `ChatMessage` renders one message,
+ * `ChatMessageList` arranges many into a conversation.
+ *
+ * A list is defined by its items, so `ChatMessageList` is a compound of a
+ * `Root` and its `Item`s — not a box that happens to contain children. The
+ * `Item` is the list-membership socket; a `ChatMessage` (or any other content)
+ * is what plugs into it.
+ *
+ * `Root` wraps the Nimbus `ScrollArea`, owns autoscroll / stick-to-bottom and
+ * the "jump to latest" affordance, and is the single persistent
+ * `role="log"` `aria-live="polite"` region that announces appended and streamed
+ * replies — the counterpart to `ChatMessage`'s `isStreaming` busy flag.
+ *
+ * @see {@link https://nimbus-documentation.vercel.app/components/feedback/chat-message-list}
+ *
+ * @example
+ * ```tsx
+ * <ChatMessageList.Root aria-label="Conversation with the agent">
+ *   <ChatMessageList.Item>
+ *     <ChatMessage.Root sender="user">
+ *       <ChatMessage.Body><Text>Summarise last week's orders?</Text></ChatMessage.Body>
+ *     </ChatMessage.Root>
+ *   </ChatMessageList.Item>
+ *   <ChatMessageList.Item>
+ *     <Box mx="auto" textAlign="center" color="neutral.11" textStyle="sm">
+ *       Conversation history was cleared.
+ *     </Box>
+ *   </ChatMessageList.Item>
+ * </ChatMessageList.Root>
+ * ```
+ */
+export declare const ChatMessageList: {
+    /**
+     * # ChatMessageList.Root
+     *
+     * The scrollable transcript container. Wraps `ScrollArea`, owns autoscroll /
+     * stick-to-bottom, the scroll-to-bottom control, and the transcript's single
+     * `role="log"` `aria-live="polite"` region. Renders `emptyState` when there
+     * are no items. Accepts `autoScroll` (default `true`) and exposes an
+     * imperative `scrollToBottom()` via `ref`.
+     *
+     * @example
+     * ```tsx
+     * <ChatMessageList.Root aria-label="Conversation" autoScroll>
+     *   <ChatMessageList.Item>…</ChatMessageList.Item>
+     * </ChatMessageList.Root>
+     * ```
+     */
+    Root: {
+        (props: import('./chat-message-list.types.js').ChatMessageListRootProps): import("react").JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # ChatMessageList.Item
+     *
+     * One member of the transcript — the socket that owns inter-item placement
+     * and entry presentation. Content-agnostic: it holds a `ChatMessage` or any
+     * other content. Does not assert `role="listitem"` (which would conflict with
+     * the `log` container).
+     *
+     * @example
+     * ```tsx
+     * <ChatMessageList.Item>
+     *   <ChatMessage.Root sender="agent">…</ChatMessage.Root>
+     * </ChatMessageList.Item>
+     * ```
+     */
+    Item: {
+        ({ ref, children, ...props }: import('./chat-message-list.types.js').ChatMessageListItemProps): import("react").JSX.Element;
+        displayName: string;
+    };
+};
+export { ChatMessageListRoot as _ChatMessageListRoot, ChatMessageListItem as _ChatMessageListItem, };

package/dist/components/chat-message-list/chat-message-list.i18n.d.ts

@@ -0,0 +1,12 @@
+export declare const messages: {
+    scrollToBottom: {
+        id: string;
+        description: string;
+        defaultMessage: string;
+    };
+    conversationLabel: {
+        id: string;
+        description: string;
+        defaultMessage: string;
+    };
+};

package/dist/components/chat-message-list/chat-message-list.messages.d.ts

@@ -0,0 +1,6 @@
+import { LocalizedString, LocalizedStrings } from '@internationalized/string';
+export declare const chatMessageListMessagesStrings: LocalizedStrings<string, LocalizedString>;
+/**
+ * Available message keys for ChatMessageList component
+ */
+export type ChatMessageListMessageKey = "conversationLabel" | "scrollToBottom";

package/dist/components/chat-message-list/chat-message-list.recipe.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Recipe configuration for the ChatMessageList compound component.
+ *
+ * `ChatMessageList` presents a scrollable sequence of chat messages. The slots
+ * mirror the component's seams:
+ *
+ * - `root` — the positioned container. It is the anchor for the floating
+ *   "jump to latest" control (`position: relative`) and establishes the height
+ *   context the interior `ScrollArea` scrolls within.
+ * - `viewport` — the vertical flow that holds the items. It owns the transcript
+ *   rhythm (the inter-item gap) and horizontal padding; it is rendered *inside*
+ *   the `ScrollArea`, so it is the content that scrolls.
+ * - `item` — one list member (the socket that holds a `ChatMessage` or any
+ *   other content).
+ * - `scrollToBottom` — the absolutely-positioned control shown while the
+ *   stick-to-bottom pin is released.
+ * - `empty` — the centered empty-state shown when there are no items.
+ *
+ * The `ScrollArea` (an already-registered Nimbus component) owns the scrollbar
+ * styling, so this recipe deliberately does not re-style scrollbars.
+ */
+export declare const chatMessageListSlotRecipe: import('@chakra-ui/react').SlotRecipeDefinition<"root" | "viewport" | "empty" | "item" | "scrollToBottom", import('@chakra-ui/react').SlotRecipeVariantRecord<"root" | "viewport" | "empty" | "item" | "scrollToBottom">>;

package/dist/components/chat-message-list/chat-message-list.slots.d.ts

@@ -0,0 +1,27 @@
+import { SlotComponent } from '../../type-utils/slot-types.js';
+import { ChatMessageListRootSlotProps, ChatMessageListViewportSlotProps, ChatMessageListItemSlotProps, ChatMessageListScrollToBottomSlotProps, ChatMessageListEmptySlotProps } from './chat-message-list.types.js';
+/**
+ * Root slot — establishes the recipe context and is the positioned anchor for
+ * the floating scroll-to-bottom control.
+ */
+export declare const ChatMessageListRootSlot: SlotComponent<HTMLDivElement, ChatMessageListRootSlotProps>;
+/**
+ * Viewport slot — the vertical flow that holds the items and owns the
+ * transcript rhythm. Rendered inside the interior `ScrollArea`, so it is the
+ * content that scrolls.
+ */
+export declare const ChatMessageListViewportSlot: SlotComponent<HTMLDivElement, ChatMessageListViewportSlotProps>;
+/**
+ * Item slot — one list member. A plain block in the scroll flow; it does not
+ * assert `role="listitem"` (which would conflict with the `log` container).
+ */
+export declare const ChatMessageListItemSlot: SlotComponent<HTMLDivElement, ChatMessageListItemSlotProps>;
+/**
+ * Scroll-to-bottom slot — the layout wrapper that positions the "jump to
+ * latest" control over the bottom of the transcript.
+ */
+export declare const ChatMessageListScrollToBottomSlot: SlotComponent<HTMLDivElement, ChatMessageListScrollToBottomSlotProps>;
+/**
+ * Empty slot — the centered container shown when there are no items.
+ */
+export declare const ChatMessageListEmptySlot: SlotComponent<HTMLDivElement, ChatMessageListEmptySlotProps>;

package/dist/components/chat-message-list/chat-message-list.types.d.ts

@@ -0,0 +1,80 @@
+import { OmitInternalProps } from '../../type-utils/omit-props.js';
+import { HTMLChakraProps, UnstyledProp } from '@chakra-ui/react/styled-system';
+export type ChatMessageListRootSlotProps = HTMLChakraProps<"div", UnstyledProp>;
+export type ChatMessageListViewportSlotProps = HTMLChakraProps<"div">;
+export type ChatMessageListItemSlotProps = HTMLChakraProps<"div">;
+export type ChatMessageListScrollToBottomSlotProps = HTMLChakraProps<"div">;
+export type ChatMessageListEmptySlotProps = HTMLChakraProps<"div">;
+/**
+ * The imperative handle exposed on `ChatMessageList.Root`'s `ref`. Lets a
+ * consumer drive the transcript's scroll programmatically — e.g. after
+ * prepending history, or to jump to the newest message from a keyboard shortcut.
+ */
+export type ChatMessageListHandle = {
+    /**
+     * Scroll to the newest item and re-engage stick-to-bottom. Honors
+     * `prefers-reduced-motion` (a `"smooth"` request degrades to an instant jump
+     * when the user asks for reduced motion).
+     * @param behavior - scroll behavior; defaults to `"auto"` (instant).
+     */
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+};
+/**
+ * Props for the `ChatMessageList.Root` component — the scrollable transcript.
+ *
+ * `Root` wraps the Nimbus `ScrollArea`, owns autoscroll / stick-to-bottom, and
+ * is the single persistent `role="log"` `aria-live="polite"` region for the
+ * conversation. It renders `ChatMessageList.Item`s as `children`, or the
+ * `emptyState` when there are none.
+ */
+export type ChatMessageListRootProps = OmitInternalProps<ChatMessageListRootSlotProps> & {
+    /** The `ChatMessageList.Item` children that make up the transcript. */
+    children?: React.ReactNode;
+    /**
+     * Keep the viewport pinned to the newest item while the user is at the
+     * bottom (including while a reply streams and grows), releasing the pin
+     * when the user scrolls up to read history. Set to `false` to disable
+     * automatic scrolling entirely and drive it yourself via the ref handle.
+     * @default true
+     */
+    autoScroll?: boolean;
+    /**
+     * Content rendered when the list has no `Item` children — an onboarding
+     * prompt, suggested questions, or a simple "No messages yet" line.
+     */
+    emptyState?: React.ReactNode;
+    /**
+     * The accessible name of the transcript's live region. Defaults to a
+     * localized "Conversation" when neither `aria-label` nor `aria-labelledby`
+     * is provided, so the `role="log"` region is always named.
+     */
+    "aria-label"?: string;
+    /** Reference an external element as the live region's accessible name. */
+    "aria-labelledby"?: string;
+    /** Imperative handle for programmatic scroll control. */
+    ref?: React.Ref<ChatMessageListHandle>;
+    [key: `data-${string}`]: unknown;
+};
+/**
+ * Props for the `ChatMessageList.Item` component — one list member.
+ *
+ * `Item` is the list-membership socket: it owns inter-item placement and the
+ * entry presentation of a newly appended member, and is content-agnostic — it
+ * holds a `ChatMessage` or any other content without reaching into
+ * it. It deliberately does not assert `role="listitem"`, which would conflict
+ * with the `log` container's live-region semantics.
+ */
+export type ChatMessageListItemProps = OmitInternalProps<ChatMessageListItemSlotProps> & {
+    /**
+     * Override the rendered element. Defaults to a `div`. Note: `Item`
+     * deliberately does not assert `role="listitem"` (it would conflict with the
+     * `log` container). `as="li"` only yields real list semantics inside an
+     * actual `list`/`role="list"` ancestor, which the transcript is not.
+     */
+    as?: React.ElementType;
+    /** Exactly one transcript member (a `ChatMessage` or any other content). */
+    children?: React.ReactNode;
+    /** Ref forwarding to the item element. */
+    ref?: React.Ref<HTMLDivElement>;
+    [key: `data-${string}`]: unknown;
+};

package/dist/components/chat-message-list/components/chat-message-list.item.d.ts

@@ -0,0 +1,20 @@
+import { ChatMessageListItemProps } from '../chat-message-list.types.js';
+/**
+ * ChatMessageList.Item - One member of the transcript.
+ *
+ * The list-membership socket: it owns inter-item placement and the entry
+ * presentation of a newly appended member, and is content-agnostic — it holds a
+ * `ChatMessage` or any other content without reaching into it.
+ * That child-agnosticism is what lets a system notice be a peer of a message
+ * rather than a message variant.
+ *
+ * It deliberately does **not** assert `role="listitem"`, which would conflict
+ * with the `log` live-region semantics of `ChatMessageList.Root`; it provides
+ * DOM order and a structural styling hook only.
+ *
+ * @supportsStyleProps
+ */
+export declare const ChatMessageListItem: {
+    ({ ref, children, ...props }: ChatMessageListItemProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/chat-message-list/components/chat-message-list.root.d.ts

@@ -0,0 +1,22 @@
+import { ChatMessageListRootProps } from '../chat-message-list.types.js';
+/**
+ * ChatMessageList.Root - The scrollable transcript container.
+ *
+ * Wraps the Nimbus `ScrollArea` for the viewport and owns transcript-level
+ * behavior: autoscroll / stick-to-bottom (pins to the newest item while the
+ * user is at the bottom, including during streaming, and releases when they
+ * scroll up), the "jump to latest" affordance, and the single persistent
+ * `role="log"` `aria-live="polite"` region that announces appended and streamed
+ * messages. When there are no items it renders `emptyState`.
+ *
+ * The list is content-agnostic: its `Item`s hold a `ChatMessage` or any other
+ * content and it never reaches into them. It renders one message's
+ * announcement at the transcript level; the message itself only flags
+ * `aria-busy` while streaming (see `ChatMessage`).
+ *
+ * @supportsStyleProps
+ */
+export declare const ChatMessageListRoot: {
+    (props: ChatMessageListRootProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/chat-message-list/components/index.d.ts

@@ -0,0 +1,2 @@
+export { ChatMessageListRoot } from './chat-message-list.root.js';
+export { ChatMessageListItem } from './chat-message-list.item.js';

package/dist/components/chat-message-list/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useStickToBottom } from './use-stick-to-bottom.js';
+export type { UseStickToBottomOptions, UseStickToBottomReturn, } from './use-stick-to-bottom.js';