@photon-ai/pho-ui 4.3.1 → 4.4.0

package/dist/src/components/chat/chat.d.ts

@@ -0,0 +1,301 @@
+import { AnchorHTMLAttributes, ButtonHTMLAttributes, ComponentProps, ReactNode, Ref } from 'react';
+import { InputProps } from '../input';
+import { StatusViewProps } from '../status-view';
+/**
+ * Chat — an inbox in one card: the conversations down the left, the open
+ * thread on the right with its messages scrolling up from the composer.
+ * It composes the smaller parts (`Message` rows of `Bubble`s in a
+ * `ScrollArea`, an `Input` for search, `Button`s to send and go back) the
+ * way `Sidebar` composes a rail: rows that press, one active, links
+ * through the host's `LinkProvider`.
+ *
+ * Two layouts. `default` seats both panes side by side — the divider
+ * between them drags so either pane can grow, each down to a min width.
+ * `compact` shows one at a time — the list, then the thread with a way
+ * back — for a narrow column or a phone. Opening a conversation pushes
+ * the thread in from the right; back pops the list in from the left, a
+ * short drift on `TRAVEL_LINEAR` with a `FADE_SWAP` fade. `auto` is
+ * compact only while the frame is narrower than 42rem (a container
+ * query, so it follows the card, not the viewport). Which pane is up is
+ * `pane`, controlled or not; opening a conversation moves to the thread,
+ * the header's back button returns.
+ *
+ * Presentational, like every Pho part: the page fetches, formats times,
+ * and decides who is who. The thread stays pinned to its newest message
+ * while the reader is at the bottom, and keeps its place when earlier
+ * pages arrive above.
+ */
+export type ChatLayout = "default" | "compact" | "auto";
+export type ChatPane = "list" | "thread";
+/** Push is 1 (thread from the right); pop is −1 (list from the left). */
+export type ChatPaneDirection = 1 | -1;
+/**
+ * The compact pane swap — incoming travels `PANE_TRAVEL_PX` on
+ * `TRAVEL_LINEAR`, fades and breathes `BLUR_PX` on `FADE_SWAP`; outgoing
+ * drifts `PANE_LEAVE_PX` the other way. Under reduced motion: opacity
+ * only, and instant.
+ */
+export declare function paneSwapMotion(direction: ChatPaneDirection, reduceMotion?: boolean | null): {
+    initial: {
+        opacity: number;
+        x?: undefined;
+        filter?: undefined;
+    };
+    animate: {
+        opacity: number;
+        x?: undefined;
+        filter?: undefined;
+    };
+    exit: {
+        opacity: number;
+        x?: undefined;
+        filter?: undefined;
+    };
+    transition: {
+        duration: number;
+        x?: undefined;
+        opacity?: undefined;
+        filter?: undefined;
+    };
+} | {
+    initial: {
+        x: number;
+        opacity: number;
+        filter: string;
+    };
+    animate: {
+        x: number;
+        opacity: number;
+        filter: string;
+    };
+    exit: {
+        x: number;
+        opacity: number;
+        filter: string;
+    };
+    transition: {
+        x: {
+            readonly duration: 0.2;
+            readonly ease: "linear";
+        };
+        opacity: {
+            readonly duration: 0.2;
+            readonly ease: "easeOut";
+        };
+        filter: {
+            readonly duration: 0.2;
+            readonly ease: "easeOut";
+        };
+        duration?: undefined;
+    };
+};
+/**
+ * DOM handlers whose React signatures clash with Motion's gesture props.
+ * Same omit list as `Button` — swap panes and conversation rows render
+ * through `motion.*`.
+ */
+type MotionHandlerConflicts = "onAnimationStart" | "onAnimationEnd" | "onAnimationIteration" | "onDrag" | "onDragStart" | "onDragEnd" | "onDragEnter" | "onDragExit" | "onDragLeave" | "onDragOver" | "onDrop";
+export interface ChatRootProps extends ComponentProps<"div"> {
+    /**
+     * `default` shows both panes; `compact` one at a time; `auto` is
+     * compact while the frame is narrower than 42rem.
+     * @default "default"
+     */
+    layout?: ChatLayout;
+    /** The pane that is up in a compact layout. Pair with `onPaneChange`. */
+    pane?: ChatPane;
+    /** Initial pane when uncontrolled. @default "list" */
+    defaultPane?: ChatPane;
+    /** Called with the next pane — a row opened a thread, back was pressed. */
+    onPaneChange?: (pane: ChatPane) => void;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * The card. Give it a height (`h-[32rem]`, or `min-h-0 flex-1` in a
+ * column that fills the page); the panes scroll inside it.
+ */
+declare function Root({ layout, pane: paneProp, defaultPane, onPaneChange, className, style, ref, ...props }: ChatRootProps): import("react").JSX.Element;
+/** The left pane — search above, conversations below, on the page wash. */
+declare function List({ className, children, id: idProp, ...props }: ComponentProps<"aside">): import("react").JSX.Element;
+export interface ChatSearchProps extends Omit<InputProps, "size" | "icon" | "label" | "hint" | "labelTrailing"> {
+}
+/** The search row pinned over the conversations — an `sm` `Input`. */
+declare function Search({ className, placeholder, ...props }: ChatSearchProps): import("react").JSX.Element;
+/**
+ * The scrolling part of the list. Put a `ConversationList` in it — or a
+ * `ConversationsLoading`, an `Empty` — and anything that belongs after
+ * the rows (a load-older button).
+ */
+declare function Conversations({ className, children, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/** The rows. */
+declare function ConversationList({ className, ...props }: ComponentProps<"ul">): import("react").JSX.Element;
+/**
+ * DOM handlers whose React signatures clash with Motion's gesture props.
+ * Same omit list as `Button` — rows render through `motion.*`.
+ */
+interface ConversationBaseProps {
+    /** Who — a number, a name, the members of a group. */
+    title: ReactNode;
+    /** When — the page's relative time (`2d ago`), trailing. */
+    time?: ReactNode;
+    /** The latest message, one truncated line. */
+    preview?: ReactNode;
+    /** Replace the default avatar (a person, or people for a `group`). */
+    avatar?: ReactNode;
+    /** A group conversation — the default avatar shows people. */
+    group?: boolean;
+    /** The open conversation. */
+    active?: boolean;
+    className?: string;
+}
+export interface ChatConversationLinkProps extends ConversationBaseProps, Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof ConversationBaseProps | MotionHandlerConflicts> {
+    /** Destination — rendered through the host's `LinkProvider`. */
+    href: string;
+}
+export interface ChatConversationButtonProps extends ConversationBaseProps, Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof ConversationBaseProps | MotionHandlerConflicts> {
+    href?: undefined;
+}
+export type ChatConversationProps = ChatConversationLinkProps | ChatConversationButtonProps;
+/**
+ * One conversation — a link when `href` is given (through the host's
+ * `LinkProvider`), otherwise a button. Opening it in a compact layout
+ * brings the thread up.
+ */
+declare function Conversation({ title, time, preview, avatar, group, active, className, href, onClick, ...rest }: ChatConversationProps): import("react").JSX.Element;
+/** The right pane — header, messages, and the docked footer, on the card. */
+declare function Thread({ className, children, ...props }: ComponentProps<"section">): import("react").JSX.Element;
+export interface ChatHeaderProps extends ComponentProps<"header"> {
+    /** The other side's avatar — an `Avatar.Root`. */
+    avatar?: ReactNode;
+    /** Controls at the trailing edge — a details button, a menu. */
+    actions?: ReactNode;
+    /** The back button's accessible name. @default "Back to conversations" */
+    backLabel?: string;
+}
+/**
+ * Who the thread is with. Children are a `Title` and a `Description`.
+ * In a compact layout a back button leads the row; `auto` shows it only
+ * while the frame is narrow.
+ */
+declare function Header({ avatar, actions, backLabel, className, children, ...props }: ChatHeaderProps): import("react").JSX.Element;
+/** The other side's name. Inline extras (a copy button, a badge) sit after it. */
+declare function Title({ className, children, ...props }: ComponentProps<"h2">): import("react").JSX.Element;
+/** One line under the title — from whom, a status. */
+declare function Description({ className, ...props }: ComponentProps<"p">): import("react").JSX.Element;
+export interface ChatMessagesProps extends ComponentProps<"div"> {
+    /** Earlier pages exist — a button at the top asks for them. */
+    hasEarlier?: boolean;
+    /** The earlier page is on its way. */
+    loadingEarlier?: boolean;
+    /** Ask for the page before the first message shown. */
+    onLoadEarlier?: () => void;
+    /** The button's label. @default "Load earlier messages" */
+    earlierLabel?: ReactNode;
+}
+/**
+ * The messages, oldest to newest, on the thread surface. The pane starts at
+ * the bottom and stays there as messages arrive unless the reader has
+ * scrolled up; an earlier page keeps what they were reading in place.
+ * Children are `Message` rows and `Divider`s.
+ */
+declare function Messages({ hasEarlier, loadingEarlier, onLoadEarlier, earlierLabel, className, children, ...props }: ChatMessagesProps): import("react").JSX.Element;
+/** A centered caption in the thread — the day, "Unread". */
+declare function Divider({ className, children, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/** The docked bar under the messages — usually a `Composer`. */
+declare function Footer({ className, ...props }: ComponentProps<"footer">): import("react").JSX.Element;
+export interface ChatComposerProps extends Omit<ComponentProps<"form">, "onSubmit" | "prefix" | "children"> {
+    /** The draft. */
+    value: string;
+    onValueChange: (value: string) => void;
+    /** Enter, or the send button. Not called while `sending` or with nothing to send. */
+    onSend: () => void;
+    placeholder?: string;
+    /** The send is in flight — the button spins, the box waits. */
+    sending?: boolean;
+    disabled?: boolean;
+    /**
+     * There is something to send besides text (an attachment). By default
+     * the send button wakes when the draft has a non-blank character.
+     */
+    canSend?: boolean;
+    /** Controls at the start of the bottom row — an add-attachment button. */
+    prefix?: ReactNode;
+    /** A quiet line between `prefix` and the send button — a count, a size. */
+    meta?: ReactNode;
+    /** The send button's accessible name. @default "Send" */
+    sendLabel?: string;
+    /** Above the text — attachment thumbnails. */
+    children?: ReactNode;
+    /** The `<textarea>`. */
+    textareaRef?: Ref<HTMLTextAreaElement>;
+}
+/**
+ * The message box: text that grows with the draft, Enter to send and
+ * Shift+Enter for a new line, one round send button. Attachments are the
+ * page's: put their thumbnails in `children`, the button that adds them
+ * in `prefix`, and flip `canSend` when they alone should send.
+ */
+declare function Composer({ value, onValueChange, onSend, placeholder, sending, disabled, canSend, prefix, meta, sendLabel, children, textareaRef, className, ...props }: ChatComposerProps): import("react").JSX.Element;
+export interface ChatEmptyProps extends StatusViewProps {
+}
+/**
+ * The standing-in view for either pane — no conversations, no thread
+ * chosen, nothing said yet. `StatusView` at card size, centered in
+ * whatever room the pane has.
+ */
+declare function Empty({ className, size, ...props }: ChatEmptyProps): import("react").JSX.Element;
+/** Bones in the shape of conversation rows — avatar, who, when, preview. */
+declare function ConversationsLoading({ rows }: {
+    rows?: number;
+}): import("react").JSX.Element;
+/** Bones in a thread's shape — theirs left, ours right. */
+declare function MessagesLoading(): import("react").JSX.Element;
+/**
+ * The composed inbox. Assemble the two panes and fill them:
+ *
+ * ```tsx
+ * <Chat.Root layout="auto" className="h-[32rem]">
+ *   <Chat.List>
+ *     <Chat.Search value={query} onChange={…} />
+ *     <Chat.Conversations>
+ *       <Chat.ConversationList>
+ *         <Chat.Conversation title="+1 (315) 997-8332" time="2d ago" preview="…" active />
+ *       </Chat.ConversationList>
+ *     </Chat.Conversations>
+ *   </Chat.List>
+ *   <Chat.Thread>
+ *     <Chat.Header avatar={<Avatar.Root size="md">…</Avatar.Root>}>
+ *       <Chat.Title>+1 (315) 997-8332</Chat.Title>
+ *       <Chat.Description>From …</Chat.Description>
+ *     </Chat.Header>
+ *     <Chat.Messages>
+ *       <Chat.Divider>September 12</Chat.Divider>
+ *       <Message.Root>…</Message.Root>
+ *     </Chat.Messages>
+ *     <Chat.Footer>
+ *       <Chat.Composer value={draft} onValueChange={setDraft} onSend={send} />
+ *     </Chat.Footer>
+ *   </Chat.Thread>
+ * </Chat.Root>
+ * ```
+ */
+export declare const Chat: {
+    Root: typeof Root;
+    List: typeof List;
+    Search: typeof Search;
+    Conversations: typeof Conversations;
+    ConversationList: typeof ConversationList;
+    Conversation: typeof Conversation;
+    Thread: typeof Thread;
+    Header: typeof Header;
+    Title: typeof Title;
+    Description: typeof Description;
+    Messages: typeof Messages;
+    Divider: typeof Divider;
+    Footer: typeof Footer;
+    Composer: typeof Composer;
+    Empty: typeof Empty;
+    ConversationsLoading: typeof ConversationsLoading;
+    MessagesLoading: typeof MessagesLoading;
+};
+export {};

package/dist/src/components/chat/index.d.ts

@@ -0,0 +1 @@
+export { Chat, type ChatComposerProps, type ChatConversationButtonProps, type ChatConversationLinkProps, type ChatConversationProps, type ChatEmptyProps, type ChatHeaderProps, type ChatLayout, type ChatMessagesProps, type ChatPane, type ChatRootProps, type ChatSearchProps, } from './chat';

package/dist/src/components/command/command.d.ts

@@ -18,6 +18,7 @@ declare function Group({ className, ...props }: ComponentProps<typeof CommandPri
  * - `result` — flat search hit (breadcrumb + trailing scope)
  */
 export type CommandItemLevel = "item" | "subitem" | "subsubitem" | "result";
+export type CommandItemSize = "sm" | "md";
 type ItemPrimitiveProps = ComponentProps<typeof CommandPrimitive.Item>;
 export interface CommandItemProps extends Omit<ItemPrimitiveProps, "children" | "title"> {
     /**
@@ -39,6 +40,12 @@ export interface CommandItemProps extends Omit<ItemPrimitiveProps, "children" |
      * has an icon; omit when the whole result set is icon-less.
      */
     iconSlot?: boolean;
+    /**
+     * Row density. `sm` tightens padding and type for chip popovers
+     * (Filter Bar options). Palette destinations stay `md`.
+     * @default "md"
+     */
+    size?: CommandItemSize;
     /** Primary label. Prefer this over free-form children for the shared layout. */
     title?: ReactNode;
     /**
@@ -58,13 +65,16 @@ export interface CommandItemProps extends Omit<ItemPrimitiveProps, "children" |
      */
     children?: ReactNode;
 }
-/** Leading icon column — `size-4`, secondary ink. */
-declare function ItemIcon({ className, ...props }: ComponentProps<"span">): import("react").JSX.Element;
+/** Leading icon column — `size-4` at `md`, tighter at `sm`. */
+declare function ItemIcon({ className, size, ...props }: ComponentProps<"span"> & {
+    size?: CommandItemSize;
+}): import("react").JSX.Element;
 /** Primary label — medium + primary ink on `item` rows. */
-declare function ItemTitle({ className, level, ...props }: ComponentProps<"span"> & {
+declare function ItemTitle({ className, level, size, ...props }: ComponentProps<"span"> & {
     level?: CommandItemLevel;
+    size?: CommandItemSize;
 }): import("react").JSX.Element;
-declare function Item({ className, level, icon, iconSlot, title, path, scope, external, children, value, ...props }: CommandItemProps): import("react").JSX.Element;
+declare function Item({ className, level, size, icon, iconSlot, title, path, scope, external, children, value, ...props }: CommandItemProps): import("react").JSX.Element;
 declare function Separator({ className, ...props }: ComponentProps<typeof CommandPrimitive.Separator>): import("react").JSX.Element;
 declare function Loading({ className, ...props }: ComponentProps<typeof CommandPrimitive.Loading>): import("react").JSX.Element;
 type DialogRootProps = ComponentProps<typeof PhoDialog.Root>;

package/dist/src/components/command/index.d.ts

@@ -1 +1 @@
-export { Command, useCommandState, type CommandItemLevel, type CommandItemProps, } from './command';
+export { Command, useCommandState, type CommandItemLevel, type CommandItemProps, type CommandItemSize, } from './command';

package/dist/src/components/filter-bar/filter-bar.d.ts

@@ -21,6 +21,11 @@ import { ComponentProps, ReactNode, Ref } from 'react';
 export interface FilterOption {
     value: string;
     label: string;
+    /**
+     * Rich option row (a badge, mono path). Search and the set chip still
+     * use `label` and `value` strings.
+     */
+    title?: ReactNode;
 }
 interface FilterDefinitionBase {
     /** The key in `filters` this chip reads and writes. */

package/dist/src/components/message/index.d.ts

@@ -0,0 +1,2 @@
+export { Message, type MessageAlign, type MessageRootProps } from './message';
+export { messageStatusKey, shouldShowMessageStatus, type MessageStatusItem, } from './message-status';

package/dist/src/components/message/message-status.d.ts

@@ -0,0 +1,22 @@
+/**
+ * One row in a thread, enough to decide whether its outbound status
+ * caption should show. Inbound rows leave `outbound` off.
+ */
+export interface MessageStatusItem {
+    outbound?: boolean;
+    /** Delivered, Sent, Failed — or a token like `delivered`. */
+    status?: string | null;
+}
+/**
+ * The coalesce key for a row: outbound status word, lowercased. Inbound
+ * and empty statuses are `null`, so they break a run. A failure keeps its
+ * whole text (`failed. 30007`) so two different error codes never
+ * collapse into one caption.
+ */
+export declare function messageStatusKey(outbound: boolean, status: string | null | undefined): string | null;
+/**
+ * Whether this row should render its outbound status (Delivered, Sent,
+ * Failed). Only the last message in a consecutive same-status run shows
+ * it. Inbound never does.
+ */
+export declare function shouldShowMessageStatus(messages: readonly MessageStatusItem[], index: number): boolean;

package/dist/src/components/message/message.d.ts

@@ -0,0 +1,78 @@
+import { ComponentProps } from 'react';
+/**
+ * Message — one turn in a thread: the row that seats an avatar beside a
+ * column of header, bubble, and footer, on the author's side. It owns the
+ * row layout and nothing else: the surface is `Bubble`'s, the scrolling
+ * and the composer are `Chat`'s.
+ *
+ * Design notes:
+ * - `align="end"` mirrors the row — avatar on the right, column
+ *   right-aligned — for the reader's own messages.
+ * - The avatar sits at the row's bottom, level with the bubble. When a
+ *   `Footer` (status) sits under the bubble, the avatar shifts up by one
+ *   line so it stays beside the surface.
+ * - `Time` sits beside the bubble, last-line aligned — right of inbound,
+ *   left of outbound — and is invisible until the row is hovered or
+ *   focused. `Footer` is the status caption under the bubble (Delivered,
+ *   Failed). Inbound has no status.
+ */
+export type MessageAlign = "start" | "end";
+/** Consecutive messages from one author, spaced as one turn. */
+declare function Group({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+export interface MessageRootProps extends ComponentProps<"div"> {
+    /** Which side the author sits on. @default "start" */
+    align?: MessageAlign;
+}
+/** The row: avatar beside the content column, mirrored for `end`. */
+declare function Root({ align, className, ...props }: MessageRootProps): import("react").JSX.Element;
+/**
+ * The avatar's seat — pass an `Avatar.Root`. Bottom-aligned with the
+ * bubble; lifts by one footer line when the message has a `Footer`.
+ */
+declare function Avatar({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/**
+ * Header over the bubble; time beside it; status under it. Inbound is
+ * `[bubble][time]`. Outbound is `[time][bubble]` with `Footer` below
+ * the bubble column.
+ */
+declare function Content({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/** Who — the sender's name over the bubble, secondary ink. */
+declare function Header({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/**
+ * Clock beside the bubble, last-line aligned. Description ink, tabular.
+ * Inbound sits to the right; outbound to the left. The slot stays in
+ * layout; the digits show when the row is hovered or focused.
+ */
+declare function Time({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/**
+ * Status under the bubble — Delivered, Failed. Inbound leaves it off.
+ * Description ink.
+ */
+declare function Footer({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/**
+ * A turn in a thread. `Root` takes `align`; `Avatar` seats an
+ * `Avatar.Root`; `Content` places `Header` over the bubble, `Time`
+ * beside it, and `Footer` under it.
+ *
+ * ```tsx
+ * <Message.Root align="end">
+ *   <Message.Content>
+ *     <Bubble.Root variant="inverse" align="end">
+ *       <Bubble.Content>On my way.</Bubble.Content>
+ *     </Bubble.Root>
+ *     <Message.Time>2:47 PM</Message.Time>
+ *     <Message.Footer>Delivered.</Message.Footer>
+ *   </Message.Content>
+ * </Message.Root>
+ * ```
+ */
+export declare const Message: {
+    Root: typeof Root;
+    Group: typeof Group;
+    Avatar: typeof Avatar;
+    Content: typeof Content;
+    Header: typeof Header;
+    Time: typeof Time;
+    Footer: typeof Footer;
+};
+export {};

package/dist/src/index.d.ts

@@ -28,3 +28,6 @@ export * from './components/log-list';
 export * from './components/description-list';
 export * from './components/code-block';
 export * from './components/trace';
+export * from './components/bubble';
+export * from './components/message';
+export * from './components/chat';

package/dist/src/sections/sidebar/sidebar.d.ts

@@ -126,6 +126,13 @@ interface ItemBaseProps {
     icon?: Slottable;
     /** Marks the row as the current destination (adds `aria-current="page"`). */
     active?: boolean;
+    /**
+     * Let the label break onto two lines instead of truncating. Default
+     * rows stay a single truncated line so the rail keeps even height.
+     * The row still uses `min-h-9`; wrap only grows it when the text
+     * actually breaks. Caps at two lines.
+     */
+    wrap?: boolean;
     children?: ReactNode;
     className?: string;
 }
@@ -149,8 +156,10 @@ export type SidebarItemProps = SidebarItemLinkProps | SidebarItemButtonProps;
  * A nav row — a link when `href` is given (rendered through the host's
  * `LinkProvider`), otherwise a button. `active` lifts the row onto the
  * primary surface; `external` opens a new tab and appends a ↗ cue.
+ * `wrap` drops the single-line truncate so a long product name can sit
+ * on two lines; other rows stay one line.
  */
-declare function Item({ icon, active, className, children, href, external, ...rest }: SidebarItemProps): import("react").JSX.Element;
+declare function Item({ icon, active, wrap, className, children, href, external, ...rest }: SidebarItemProps): import("react").JSX.Element;
 export interface SidebarSubmenuProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | MotionHandlerConflicts> {
     /** The parent row's label. */
     label: ReactNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photon-ai/pho-ui",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Pho Design System — Photon's React component library, built on Base UI",
   "license": "UNLICENSED",
   "repository": {
@@ -455,6 +455,18 @@
     "./components/date-picker": {
       "types": "./dist/src/components/date-picker/index.d.ts",
       "import": "./dist/components/date-picker.js"
+    },
+    "./components/bubble": {
+      "types": "./dist/src/components/bubble/index.d.ts",
+      "import": "./dist/components/bubble.js"
+    },
+    "./components/message": {
+      "types": "./dist/src/components/message/index.d.ts",
+      "import": "./dist/components/message.js"
+    },
+    "./components/chat": {
+      "types": "./dist/src/components/chat/index.d.ts",
+      "import": "./dist/components/chat.js"
     }
   },
   "peerDependencies": {