@vvedantb/ui 0.2.3 → 0.3.1

package/README.md

@@ -6,6 +6,7 @@ Shared React 19 web UI. Source-exported: no build step.
 | --- | --- |
 | `@vvedantb/ui` | Primitives (Radix-based), AI elements, `playChime` and `useReplyChime`. |
 | `@vvedantb/ui/sonner` | `SonnerToaster`, its helpers and `toast`. |
+| `@vvedantb/ui/composer` | `Composer`, `ComposerShell`, `ComposerGhostText`, `ComposerIconButton`, `useComposerPrediction` and the pure prediction helpers. |
 | `@vvedantb/ui/audio` | `playChime`, `useReplyChime`, `playTone` and the shared audio floor. |
 | `@vvedantb/ui/cn` | `cn` class helper (clsx + tailwind-merge). |
 | `@vvedantb/ui/shell` | Router-free `SidebarHeader`, `PillTabs` and `SessionsHoverCard`. |
@@ -36,6 +37,97 @@ useReplyChime({ enabled: soundOn, isStreaming, threadId });
 - These are also available from `@vvedantb/ui/audio`, which does not load the rest of the root barrel.
 - `useReplyChime`: chimes once when `isStreaming` goes from `true` to `false` for the same `threadId`. It is silent on the first sight of a thread, when `threadId` changes, and when `threadId` is null or undefined. While `enabled` is `false` it still tracks the edge, so enabling mid-turn does not replay a finish.
 
+## Composer
+
+Chat composer with an autosizing textarea, a footer with a plus-menu slot, action slots and a send or stop button. It also shows optional ghost-text predictions. It makes no network calls: the app supplies `getPrediction`.
+
+```tsx
+import { Composer, ComposerIconButton } from "@vvedantb/ui"; // or "@vvedantb/ui/composer"
+
+<Composer
+  value={draft}
+  onChange={setDraft}
+  onSubmit={(text) => send(text)}
+  streaming={isStreaming}
+  onStop={cancel}
+  plusMenu={<ComposerIconButton aria-label="Add">+</ComposerIconButton>}
+  attachments={chips}
+  getPrediction={(draft, { signal }) => fetchContinuation(draft, signal)}
+/>;
+```
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `value`, `defaultValue`, `onChange` | uncontrolled, `""` | Pass `value` to control it. When controlled, clear the value yourself after `onSubmit`. When uncontrolled, the composer clears after submit. |
+| `onSubmit(text)` | none | Called with the trimmed draft on Enter or the send button. Not called for an empty draft, or when `disabled` or `streaming`. If it returns a rejected promise, an uncontrolled composer restores the draft. |
+| `streaming`, `onStop` | `false` | The stop button replaces send and calls `onStop`. Typing stays on, Enter does not submit. |
+| `disabled` | `false` | Disables the textarea and send. |
+| `placeholder` | `"Message"` | Also the textarea `aria-label`. |
+| `layout` | `"stacked"` | `"stacked"`: input above, footer bar with `plusMenu` left and `trailingActions` plus send or stop right. `"inline"`: one row with `plusMenu`, the input and the actions. Attachments stay above the row. |
+| `renderInput(ctx)` | none | Supplies your own input instead of the textarea. See Building blocks. |
+| `maxHeight` | `200` (px) | The textarea grows to this height, then scrolls. |
+| `autoFocus`, `className`, `textareaClassName` | none | `className` is the outer shell. `textareaClassName` is also applied to the ghost text mirror, so put padding and font classes there, not on the shell. |
+| `plusMenu` | none | Node, or `({ disabled }) => node`. Left of the footer. |
+| `trailingActions` | none | Node, or `({ disabled, streaming }) => node`. Right of the footer, before send or stop. |
+| `attachments` | none | Node rendered in a row above the textarea. The app renders the chips and their remove buttons. |
+| `getPrediction(draft, { signal })` | none | Returns the continuation of `draft`. Pass `signal` to your request. Errors show no ghost text. |
+| `predictionDebounceMs` | `500` (ms) | Pause after the last edit before a request. |
+| `predictionMinLength` | `12` (characters) | Minimum trimmed draft length. |
+
+Keys: Enter sends, Shift+Enter adds a line, and nothing sends during IME composition. Tab accepts the ghost text, and Esc hides it for the current draft.
+
+Predictions skip drafts shorter than `predictionMinLength`, drafts whose last word starts with `@` or `/`, and drafts that match `/[.!?]\s*$/`. Each edit aborts the previous request, and a result for an older draft is dropped. Ghost text shows only while the caret is at the end of the draft, so Tab always appends. It does not insert at a caret in the middle of the text. A space joins the draft and the prediction when neither has whitespace at the join.
+
+The ref goes to the textarea. `ComposerIconButton` is a round icon-only ghost button for the slots. The pure helpers `shouldSkipComposerPrediction`, `joinComposerPrediction`, `nextComposerPredictionState`, `visibleComposerPrediction` and `acceptComposerPrediction`, and the `useComposerPrediction` hook, are exported for apps with their own input.
+
+### Building blocks
+
+`renderInput` swaps the textarea for your own input and keeps the shell, slots, send or stop and predictions. The context gives `value`, `onChange`, `onKeyDown`, `ghostText`, `acceptGhost`, `dismissGhost`, `inputRef`, `disabled`, `placeholder`, `streaming`, `maxHeight` and `textareaClassName`.
+
+```tsx
+<Composer
+  layout="inline"
+  getPrediction={getPrediction}
+  renderInput={(ctx) => (
+    <MyEditor
+      ref={ctx.inputRef}
+      data-composer-input=""
+      value={ctx.value}
+      onChange={ctx.onChange}
+      onKeyDown={ctx.onKeyDown}
+      ghostText={ctx.ghostText}
+    />
+  )}
+/>
+```
+
+Rules for a custom input:
+
+- `onKeyDown` handles Enter (calls `preventDefault`, then submits, never during IME composition), Tab (accepts the ghost text) and Esc (dismisses it). Shift+Enter is not handled: your editor decides what a newline does.
+- Autosize and the caret-at-end ghost gate apply to the default textarea only. With `renderInput`, predictions run whenever the composer is not disabled or streaming. You size the editor (use `maxHeight`) and decide when the caret allows ghost text, for example by ignoring `ghostText`.
+- Put the `data-composer-input` attribute on the editor so the shell shows the focus ring.
+- `ref` on `Composer` points at the default textarea only. Use `ctx.inputRef` for a custom input.
+
+To build without `Composer`, assemble the parts yourself. `useComposerPrediction` takes the draft string and reads no element. `ComposerGhostText` draws the draft invisibly, then the ghost text, so give it the same padding and font classes as your editor and place it under the editor.
+
+```tsx
+import { ComposerGhostText, ComposerShell, useComposerPrediction } from "@vvedantb/ui/composer";
+
+function MentionComposer({ draft, setDraft, send }: Props) {
+  const prediction = useComposerPrediction({ value: draft, enabled: true, getPrediction });
+  return (
+    <ComposerShell layout="inline" plusMenu={plus} canSend={draft.trim() !== ""} onSend={send}>
+      <ComposerGhostText value={draft} ghostText={prediction.ghost} className="px-2 py-1 text-sm leading-6" />
+      <Editor data-composer-input="" className="relative px-2 py-1 text-sm leading-6" onChange={setDraft} />
+    </ComposerShell>
+  );
+}
+```
+
+`ComposerShell` props: `layout`, `disabled`, `streaming`, `canSend`, `onSend`, `onStop`, `plusMenu`, `trailingActions`, `attachments`, `className` and `children` (the input region). In the shell the Enter, Tab and Esc keys are yours to wire when you do not use `Composer`.
+
+Fixture: `composer/examples/` (see its README). It has a `tokens.css` page and a `compat-shadcn-rgb.css` page, each with light and dark.
+
 ## Sessions hover card
 
 ```tsx
@@ -50,7 +142,7 @@ import { SessionsHoverCard } from "@vvedantb/ui/shell";
 </SessionsHoverCard>
 ```
 
-`children` is the trigger. It is rendered with `asChild` by default, so it keeps its own handlers (such as a context menu). Extra props and the ref go to it. Use `asChild={false}` for a default trigger element. The content portals to `document.body` by default, so `overflow:hidden` ancestors do not clip it. Pass `portal={false}` to opt out. `surface` is `"overlay"` (default), `"surface"` (`rounded-surface`) or `"glass"` (`glass-panel-strong`, `rounded-surface`). `className` merges over the surface without `!`. Defaults: `openDelay` 400 ms, `closeDelay` 150 ms, `side="right"`, `align="start"`, `sideOffset` 8, width and padding `w-64 p-3` (override with `className`). `body` is a node or a function of `{ open }`. `loadContent` runs only while the card is open. Control the state with `open`, `defaultOpen` and `onOpenChange`. Fixture: `shell/examples/sessions-hover-card/`.
+`children` is the trigger. It is rendered with `asChild` by default, so it keeps its own handlers (such as a context menu). Extra props and the ref go to it. Use `asChild={false}` for a default trigger element. The content portals to `document.body` by default, so `overflow:hidden` ancestors do not clip it. Pass `portal={false}` to opt out. `surface` is `"overlay"` (default), `"surface"` (`rounded-surface`) or `"glass"` (`glass-panel-strong`, `rounded-surface`). `className` merges over the surface without `!`. Defaults: `openDelay` 400 ms, `closeDelay` 150 ms, `side="right"`, `align="start"`, `sideOffset` 8, width and padding `w-64 p-3` (override with `className`). `body` is a node or a function of `{ open }`. `loadContent` runs only while the card is open. Control the state with `open`, `defaultOpen` and `onOpenChange`. The card opens on pointer hover and on keyboard focus (`:focus-visible`) only. Focus that follows a click or a context menu close does not open it. If pointer-driven focus left it stuck open, pointer leave force-closes it; otherwise Radix handles close (including moving onto the content). Fixture: `shell/examples/sessions-hover-card/`.
 
 ## Toaster
 
@@ -84,6 +176,11 @@ Opt-in props (all default to the current look):
 | `closeButtonStyle` | `"default"`, `"hoverChip"` | Text-style close button or a round chip at the top-right, shown on hover and always on small screens. It turns on `closeButton` unless you set it. |
 | `sonnerVars` | `false` (default), `true` | Sets `--normal-bg`, `--normal-border`, `--normal-text`, `--normal-bg-hover` and `--normal-border-hover` from `--color-card`, `--color-border`, `--color-foreground` and `--color-muted`, and `font-family: inherit`. |
 | `descriptionMuted` | `false` (default), `true` | Description uses `text-muted-foreground!`, which beats sonner's dark-theme rule. |
+| `titleLeading` | `"snug"` (default), `"5"` | Title `leading-snug` (19.25px at `text-sm`) or `leading-5` (20px). |
+| `loadingIcon` | node (default none) | Custom loading icon, merged into `icons`. A caller `icons.loading` wins. `icons={{ loading }}` works with both `toastIcons` values. |
+| `hideStackedContent` | `false` (default), `true` | Adds `[&[data-expanded=false][data-front=false]>*]:opacity-0` to the toast, so content behind the front toast is hidden while the stack is collapsed. `sonner.css` applies the same rule when imported. |
+
+With `closeButtonStyle="hoverChip"`, hover changes the text colour, and sonner may still change the background. The border stays `border-border` (pinned with `hover:border-border!` over sonner's dark hover border), so the ring does not brighten in dark mode.
 
 Helpers: `createToasterClassNames`, `mergeToastClassNames`, `mergeToastOptions`, `mergeToasterStyle`, `filledToastIcons`. Fixture: `tokens/examples/toaster/`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: primitives, shell pieces, app helpers, design tokens, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
@@ -29,6 +29,10 @@
       "types": "./src/audio/index.ts",
       "default": "./src/audio/index.ts"
     },
+    "./composer": {
+      "types": "./src/composer/index.ts",
+      "default": "./src/composer/index.ts"
+    },
     "./shell": {
       "types": "./shell/src/index.ts",
       "default": "./shell/src/index.ts"

package/shell/src/SessionsHoverCard.tsx

@@ -70,6 +70,15 @@ export type SessionsHoverCardProps = Omit<
   className?: string;
 };
 
+/** `:focus-visible` is true for keyboard focus only. Treat unsupported engines as keyboard. */
+function isFocusVisible(el: Element): boolean {
+  try {
+    return el.matches(":focus-visible");
+  } catch {
+    return true;
+  }
+}
+
 type LoadState = { status: "loading" } | { status: "ready"; node: ReactNode };
 
 /** Mounts only while the card is open, so `loadContent` never runs while closed. */
@@ -140,6 +149,8 @@ export const SessionsHoverCard = forwardRef<
   align = "start",
   sideOffset = 8,
   className,
+  onFocus,
+  onPointerLeave,
   ...triggerProps
 }, ref) {
   const [openState, setOpenState] = useState(defaultOpen);
@@ -150,6 +161,24 @@ export const SessionsHoverCard = forwardRef<
     onOpenChange?.(next);
   };
 
+  // Open on keyboard focus only. Focus that returns after a context menu or a
+  // click is pointer-driven, so it must not open the card.
+  const handleFocus = (event: React.FocusEvent<HTMLElement>) => {
+    onFocus?.(event as never);
+    if (event.defaultPrevented) return;
+    if (!isFocusVisible(event.currentTarget)) event.preventDefault();
+  };
+
+  // Radix handles hover close, including closeDelay and moving onto the
+  // content. Force-close only when the card is stuck open by pointer-driven
+  // focus on the trigger (focused, but not `:focus-visible`).
+  const handlePointerLeave = (event: React.PointerEvent<HTMLElement>) => {
+    onPointerLeave?.(event as never);
+    if (event.pointerType === "touch" || !open) return;
+    const el = event.currentTarget;
+    if (el.ownerDocument.activeElement === el && !isFocusVisible(el)) handleOpenChange(false);
+  };
+
   const bodyNode = loadContent ? (
     <LoadedBody loadContent={loadContent} fallback={loadingFallback} />
   ) : typeof body === "function" ? (
@@ -190,7 +219,13 @@ export const SessionsHoverCard = forwardRef<
       openDelay={openDelay}
       closeDelay={closeDelay}
     >
-      <HoverCardTrigger ref={ref} asChild={asChild} {...triggerProps}>
+      <HoverCardTrigger
+        ref={ref}
+        asChild={asChild}
+        {...triggerProps}
+        onFocus={handleFocus}
+        onPointerLeave={handlePointerLeave}
+      >
         {children}
       </HoverCardTrigger>
       {portal ? <HoverCardPrimitive.Portal>{content}</HoverCardPrimitive.Portal> : content}

package/src/composer/Composer.tsx

@@ -0,0 +1,469 @@
+"use client";
+
+import * as React from "react";
+import { IconArrowUp, IconPlayerStop } from "@tabler/icons-react";
+
+import { cn } from "../utils/cn";
+import { Button } from "../ui/button";
+import {
+  COMPOSER_PREDICTION_DEBOUNCE_MS,
+  COMPOSER_PREDICTION_MIN_LENGTH,
+  acceptComposerPrediction,
+} from "./prediction";
+import { useComposerPrediction } from "./useComposerPrediction";
+
+export type ComposerSlotContext = { disabled: boolean };
+export type ComposerTrailingContext = { disabled: boolean; streaming: boolean };
+export type ComposerLayout = "stacked" | "inline";
+
+export type ComposerInputRenderContext = {
+  value: string;
+  onChange: (value: string) => void;
+  /**
+   * Shared key handler. Enter submits (preventDefault, not while composing),
+   * Tab accepts the ghost text, Esc dismisses it. It ignores IME composition.
+   * Shift+Enter is not handled: the caller decides what a newline does.
+   */
+  onKeyDown: (event: React.KeyboardEvent) => void;
+  /** Visible ghost text including the joining space, or `""`. */
+  ghostText: string;
+  acceptGhost: () => void;
+  dismissGhost: () => void;
+  /** Attach to the input element (textarea or contenteditable root). */
+  inputRef: React.RefObject<HTMLElement | null>;
+  disabled: boolean;
+  placeholder: string;
+  streaming: boolean;
+  maxHeight: number;
+  textareaClassName?: string;
+};
+
+export type ComposerProps = {
+  /** Controlled value. Omit it for an uncontrolled composer. */
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+
+  /** Called with the trimmed draft on Enter or the send button. Never called for an empty draft. */
+  onSubmit?: (value: string) => void | Promise<void>;
+  onStop?: () => void;
+  /** Shows the stop button in place of send. Typing stays enabled. Enter does not submit. */
+  streaming?: boolean;
+  /** Disables the textarea and the send button. */
+  disabled?: boolean;
+
+  placeholder?: string;
+  /** Maximum textarea height in px. The textarea scrolls after it. Default 200. */
+  maxHeight?: number;
+  autoFocus?: boolean;
+  /** Classes for the outer shell. */
+  className?: string;
+  /** `"stacked"` (default): input above, footer bar below. `"inline"`: one row with plus, input and actions. */
+  layout?: ComposerLayout;
+  /**
+   * Supplies your own input (for example a contenteditable editor) in place of
+   * the textarea. The shell, slots, send/stop and predictions stay. Autosize
+   * and the caret-at-end gate apply to the default textarea only: the caller
+   * sizes the editor and decides when ghost text is valid.
+   */
+  renderInput?: (ctx: ComposerInputRenderContext) => React.ReactNode;
+  /** Classes for the textarea. Also applied to the ghost text mirror, so keep padding and font here. */
+  textareaClassName?: string;
+
+  /** Left of the footer. */
+  plusMenu?: React.ReactNode | ((ctx: ComposerSlotContext) => React.ReactNode);
+  /** Right of the footer, before send or stop. */
+  trailingActions?:
+    | React.ReactNode
+    | ((ctx: ComposerTrailingContext) => React.ReactNode);
+  /** Row above the textarea. The caller renders the chips and their remove buttons. */
+  attachments?: React.ReactNode;
+
+  /**
+   * Returns the continuation of a draft, shown as ghost text. The package makes
+   * no requests: the caller owns the network call and should pass `signal` to it.
+   */
+  getPrediction?: (draft: string, opts: { signal: AbortSignal }) => Promise<string>;
+  /** Default 500 ms. */
+  predictionDebounceMs?: number;
+  /** Default 12 characters (trimmed). */
+  predictionMinLength?: number;
+};
+
+const DEFAULT_MAX_HEIGHT = 200;
+
+// The textarea and its ghost text mirror must share these metrics.
+const TEXT_METRICS_BASE = "block w-full text-sm leading-6 break-words whitespace-pre-wrap";
+const textMetrics = (layout: ComposerLayout) =>
+  cn(TEXT_METRICS_BASE, layout === "inline" ? "px-2 py-1" : "px-4 pt-3.5 pb-1");
+
+function isCaretAtEnd(el: HTMLTextAreaElement): boolean {
+  return el.selectionStart === el.selectionEnd && el.selectionEnd === el.value.length;
+}
+
+/** Icon-only ghost button for the footer: `plusMenu` triggers, `trailingActions`. */
+const ComposerIconButton = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<typeof Button>
+>(({ className, variant = "ghost", size = "icon-sm", type = "button", ...props }, ref) => (
+  <Button
+    ref={ref}
+    type={type}
+    variant={variant}
+    size={size}
+    className={cn("rounded-full", className)}
+    {...props}
+  />
+));
+ComposerIconButton.displayName = "ComposerIconButton";
+
+
+type SlotNode<C> = React.ReactNode | ((ctx: C) => React.ReactNode);
+
+export type ComposerShellProps = {
+  layout?: ComposerLayout;
+  disabled?: boolean;
+  streaming?: boolean;
+  /** Enables the send button. */
+  canSend?: boolean;
+  onSend?: () => void;
+  onStop?: () => void;
+  plusMenu?: SlotNode<ComposerSlotContext>;
+  trailingActions?: SlotNode<ComposerTrailingContext>;
+  attachments?: React.ReactNode;
+  className?: string;
+  /** The input region: a textarea, a contenteditable, plus any ghost overlay. */
+  children?: React.ReactNode;
+};
+
+/**
+ * Outer chrome of the composer: border, field tokens, focus ring, attachments,
+ * plus-menu and trailing slots, and send or stop. Put your input in `children`.
+ * The focus ring follows any descendant with the `data-composer-input`
+ * attribute that matches `:focus-visible`.
+ */
+function ComposerShell({
+  layout = "stacked",
+  disabled = false,
+  streaming = false,
+  canSend = false,
+  onSend,
+  onStop,
+  plusMenu,
+  trailingActions,
+  attachments,
+  className,
+  children,
+}: ComposerShellProps) {
+  const plus = typeof plusMenu === "function" ? plusMenu({ disabled }) : plusMenu;
+  const trailing =
+    typeof trailingActions === "function"
+      ? trailingActions({ disabled, streaming })
+      : trailingActions;
+  const inline = layout === "inline";
+
+  const action = streaming ? (
+    <ComposerIconButton
+      variant="default"
+      aria-label="Stop generating"
+      data-slot="composer-stop"
+      onClick={() => onStop?.()}
+    >
+      <IconPlayerStop className="size-4" aria-hidden="true" />
+    </ComposerIconButton>
+  ) : (
+    <ComposerIconButton
+      variant="default"
+      aria-label="Send message"
+      data-slot="composer-send"
+      disabled={!canSend}
+      onClick={() => onSend?.()}
+    >
+      <IconArrowUp className="size-4" aria-hidden="true" />
+    </ComposerIconButton>
+  );
+
+  return (
+    <div
+      data-slot="composer"
+      data-layout={layout}
+      data-disabled={disabled || undefined}
+      data-streaming={streaming || undefined}
+      className={cn(
+        "group/composer relative flex w-full min-w-0 flex-col rounded-field border border-border bg-field-background text-sm transition-[border-color,box-shadow] duration-200 ease-smooth",
+        "has-[[data-composer-input]:focus-visible]:border-focus-border has-[[data-composer-input]:focus-visible]:ring-2 has-[[data-composer-input]:focus-visible]:ring-focus-ring",
+        disabled && "opacity-60",
+        className,
+      )}
+    >
+      {attachments ? (
+        <div data-slot="composer-attachments" className="flex flex-wrap items-center gap-2 px-3 pt-3">
+          {attachments}
+        </div>
+      ) : null}
+
+      {inline ? (
+        <div data-slot="composer-row" className="flex min-w-0 items-end gap-1 p-1.5">
+          {plus ? <div className="flex shrink-0 items-center gap-1">{plus}</div> : null}
+          <div data-slot="composer-input-region" className="relative min-w-0 flex-1">
+            {children}
+          </div>
+          <div className="flex shrink-0 items-center gap-1">
+            {trailing}
+            {action}
+          </div>
+        </div>
+      ) : (
+        <>
+          <div data-slot="composer-input-region" className="relative min-w-0">
+            {children}
+          </div>
+          <div data-slot="composer-footer" className="flex items-center gap-1 px-2 pt-1 pb-2">
+            {plus ? <div className="flex items-center gap-1">{plus}</div> : null}
+            <div className="ml-auto flex items-center gap-1">
+              {trailing}
+              {action}
+            </div>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+export type ComposerGhostTextProps = {
+  value: string;
+  ghostText: string;
+  className?: string;
+};
+
+/**
+ * Input-agnostic ghost overlay. It renders the draft invisibly, then the ghost
+ * text, so the ghost lands after the last character. Position it absolutely
+ * under (or over) your input and give it the same padding and font classes.
+ */
+const ComposerGhostText = React.forwardRef<HTMLDivElement, ComposerGhostTextProps>(
+  function ComposerGhostText({ value, ghostText, className }, ref) {
+    return (
+      <div
+        ref={ref}
+        aria-hidden="true"
+        data-slot="composer-ghost"
+        className={cn(
+          "pointer-events-none absolute inset-0 overflow-y-auto [scrollbar-color:transparent_transparent] [&::-webkit-scrollbar]:bg-transparent",
+          className,
+        )}
+      >
+        <span className="invisible">{value}</span>
+        {ghostText ? <span className="text-muted-foreground/50">{ghostText}</span> : null}
+      </div>
+    );
+  },
+);
+
+/**
+ * Chat composer: autosizing textarea, plus-menu and action slots, send/stop
+ * button and optional ghost-text predictions. The ref points at the textarea.
+ */
+const Composer = React.forwardRef<HTMLTextAreaElement, ComposerProps>(function Composer(
+  {
+    value: valueProp,
+    defaultValue = "",
+    onChange,
+    onSubmit,
+    onStop,
+    streaming = false,
+    disabled = false,
+    placeholder = "Message",
+    maxHeight = DEFAULT_MAX_HEIGHT,
+    autoFocus,
+    className,
+    textareaClassName,
+    layout = "stacked",
+    renderInput,
+    plusMenu,
+    trailingActions,
+    attachments,
+    getPrediction,
+    predictionDebounceMs = COMPOSER_PREDICTION_DEBOUNCE_MS,
+    predictionMinLength = COMPOSER_PREDICTION_MIN_LENGTH,
+  },
+  forwardedRef,
+) {
+  const isControlled = valueProp !== undefined;
+  const [inner, setInner] = React.useState(defaultValue);
+  const value = isControlled ? valueProp : inner;
+
+  const textareaRef = React.useRef<HTMLTextAreaElement | null>(null);
+  const mirrorRef = React.useRef<HTMLDivElement | null>(null);
+  const customInputRef = React.useRef<HTMLElement | null>(null);
+  const custom = renderInput !== undefined;
+  const setRefs = React.useCallback(
+    (node: HTMLTextAreaElement | null) => {
+      textareaRef.current = node;
+      if (typeof forwardedRef === "function") forwardedRef(node);
+      else if (forwardedRef) forwardedRef.current = node;
+    },
+    [forwardedRef],
+  );
+
+  const setValue = React.useCallback(
+    (next: string) => {
+      if (!isControlled) setInner(next);
+      onChange?.(next);
+    },
+    [isControlled, onChange],
+  );
+
+  // Ghost text shows only while the caret sits at the end of the draft.
+  const [caretAtEnd, setCaretAtEnd] = React.useState(true);
+  const prediction = useComposerPrediction({
+    value,
+    enabled: (custom || caretAtEnd) && !disabled && !streaming,
+    getPrediction,
+    debounceMs: predictionDebounceMs,
+    minLength: predictionMinLength,
+  });
+  const ghost = prediction.ghost;
+
+  // Autosize: grow with the content up to `maxHeight`, then scroll.
+  React.useLayoutEffect(() => {
+    const el = textareaRef.current;
+    if (custom || !el) return;
+    el.style.height = "auto";
+    const full = el.scrollHeight;
+    el.style.height = `${Math.min(full, maxHeight)}px`;
+    el.style.overflowY = full > maxHeight ? "auto" : "hidden";
+  }, [value, maxHeight, custom]);
+
+  const syncScroll = () => {
+    if (mirrorRef.current && textareaRef.current) {
+      mirrorRef.current.scrollTop = textareaRef.current.scrollTop;
+    }
+  };
+  React.useLayoutEffect(syncScroll, [value, ghost]);
+
+  const canSend = !disabled && !streaming && value.trim() !== "";
+
+  const submit = () => {
+    if (!canSend) return;
+    const draft = value.trim();
+    const result = onSubmit?.(draft);
+    if (!isControlled) setInner("");
+    if (!isControlled) onChange?.("");
+    prediction.clear();
+    if (result && typeof result.then === "function") {
+      // A failed async submit gives the draft back, unless the user already typed again.
+      result.then(undefined, () => {
+        if (!isControlled) setInner((current) => (current === "" ? draft : current));
+      });
+    }
+  };
+
+  const acceptGhost = () => {
+    if (!ghost) return;
+    prediction.clear();
+    setValue(acceptComposerPrediction(value, ghost));
+  };
+
+  const onKeyDown = (event: React.KeyboardEvent) => {
+    const el = event.currentTarget;
+    const native = event.nativeEvent;
+    if (native.isComposing || event.keyCode === 229) return;
+
+    if (event.key === "Tab" && !event.shiftKey && !event.altKey && !event.ctrlKey && !event.metaKey) {
+      // The caret gate applies to the default textarea only. A custom input owns it.
+      const atEnd = custom || !(el instanceof HTMLTextAreaElement) || isCaretAtEnd(el);
+      if (ghost && atEnd) {
+        event.preventDefault();
+        acceptGhost();
+      }
+      return;
+    }
+    if (event.key === "Escape") {
+      if (ghost) {
+        event.preventDefault();
+        prediction.dismiss();
+      }
+      return;
+    }
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault();
+      submit();
+    }
+  };
+
+  const updateCaret = (el: HTMLTextAreaElement) => setCaretAtEnd(isCaretAtEnd(el));
+
+  const metrics = textMetrics(layout);
+
+  const input = renderInput ? (
+    renderInput({
+      value,
+      onChange: setValue,
+      onKeyDown,
+      ghostText: ghost,
+      acceptGhost,
+      dismissGhost: prediction.dismiss,
+      inputRef: customInputRef,
+      disabled,
+      placeholder,
+      streaming,
+      maxHeight,
+      textareaClassName,
+    })
+  ) : (
+    <>
+      <ComposerGhostText
+        ref={mirrorRef}
+        value={value}
+        ghostText={ghost}
+        className={cn(metrics, textareaClassName)}
+      />
+      <textarea
+        ref={setRefs}
+        data-slot="composer-textarea"
+        data-composer-input=""
+        rows={1}
+        value={value}
+        placeholder={placeholder}
+        aria-label={placeholder}
+        disabled={disabled}
+        autoFocus={autoFocus}
+        onChange={(event) => {
+          setValue(event.target.value);
+          updateCaret(event.target);
+        }}
+        onKeyDown={onKeyDown}
+        onSelect={(event) => updateCaret(event.currentTarget)}
+        onKeyUp={(event) => updateCaret(event.currentTarget)}
+        onClick={(event) => updateCaret(event.currentTarget)}
+        onScroll={syncScroll}
+        className={cn(
+          metrics,
+          "relative resize-none overflow-y-hidden border-0 bg-transparent text-foreground outline-hidden placeholder:text-muted-foreground disabled:cursor-not-allowed",
+          textareaClassName,
+        )}
+      />
+    </>
+  );
+
+  return (
+    <ComposerShell
+      layout={layout}
+      disabled={disabled}
+      streaming={streaming}
+      canSend={canSend}
+      onSend={submit}
+      onStop={onStop}
+      plusMenu={plusMenu}
+      trailingActions={trailingActions}
+      attachments={attachments}
+      className={className}
+    >
+      {input}
+    </ComposerShell>
+  );
+});
+
+export { Composer, ComposerGhostText, ComposerIconButton, ComposerShell };

package/src/composer/index.ts

@@ -0,0 +1,23 @@
+export { Composer, ComposerGhostText, ComposerIconButton, ComposerShell } from "./Composer";
+export type {
+  ComposerGhostTextProps,
+  ComposerInputRenderContext,
+  ComposerLayout,
+  ComposerProps,
+  ComposerShellProps,
+  ComposerSlotContext,
+  ComposerTrailingContext,
+} from "./Composer";
+export { useComposerPrediction } from "./useComposerPrediction";
+export type { ComposerPrediction, UseComposerPredictionOptions } from "./useComposerPrediction";
+export {
+  COMPOSER_PREDICTION_DEBOUNCE_MS,
+  COMPOSER_PREDICTION_MIN_LENGTH,
+  acceptComposerPrediction,
+  initialComposerPredictionState,
+  joinComposerPrediction,
+  nextComposerPredictionState,
+  shouldSkipComposerPrediction,
+  visibleComposerPrediction,
+} from "./prediction";
+export type { ComposerPredictionAction, ComposerPredictionState } from "./prediction";

package/src/composer/prediction.ts

@@ -0,0 +1,94 @@
+/** Default trailing-edge debounce, in ms: how long the draft must sit before a prediction is requested. */
+export const COMPOSER_PREDICTION_DEBOUNCE_MS = 500;
+
+/** Default minimum draft length (trimmed characters) before a prediction is requested. */
+export const COMPOSER_PREDICTION_MIN_LENGTH = 12;
+
+/**
+ * True when no prediction should be requested for this draft.
+ *
+ * Skips drafts shorter than `minLength` (trimmed), drafts whose last word starts
+ * with `@` or `/` (an in-progress mention or command), and drafts that end a
+ * sentence (`.`, `!` or `?`, then optional whitespace).
+ */
+export function shouldSkipComposerPrediction(
+  value: string,
+  minLength: number = COMPOSER_PREDICTION_MIN_LENGTH,
+): boolean {
+  if (value.trim().length < minLength) return true;
+  const lastWord = value.split(/\s/).pop() ?? "";
+  if (lastWord.startsWith("@") || lastWord.startsWith("/")) return true;
+  if (/[.!?]\s*$/.test(value)) return true;
+  return false;
+}
+
+/**
+ * The ghost text for a draft: the bare continuation from the caller, with a
+ * joining space added when neither side has whitespace at the join.
+ */
+export function joinComposerPrediction(draft: string, prediction: string): string {
+  if (prediction === "") return "";
+  return /\s$/.test(draft) || /^\s/.test(prediction) ? prediction : ` ${prediction}`;
+}
+
+/** What `getPrediction` last returned, and the draft it was requested for. */
+export type ComposerPredictionState = {
+  /** Draft the stored `text` answers, or `null` when there is none. */
+  forValue: string | null;
+  /** Raw text from `getPrediction` (no joining space). */
+  text: string;
+  /** Draft for which the user pressed Esc. Suppresses requests until the draft changes. */
+  dismissedFor: string | null;
+};
+
+export type ComposerPredictionAction =
+  /** A request finished. `current` is the draft at the time it finished. */
+  | { type: "result"; forValue: string; text: string; current: string }
+  /** Esc: hide the prediction for this draft. */
+  | { type: "dismiss"; value: string }
+  /** Tab accepted the prediction, or the caller reset it. */
+  | { type: "clear" };
+
+export const initialComposerPredictionState: ComposerPredictionState = {
+  forValue: null,
+  text: "",
+  dismissedFor: null,
+};
+
+/**
+ * Pure reducer for prediction state. A result is dropped when the draft moved
+ * on while the request ran, or when it is empty.
+ */
+export function nextComposerPredictionState(
+  state: ComposerPredictionState,
+  action: ComposerPredictionAction,
+): ComposerPredictionState {
+  switch (action.type) {
+    case "result":
+      if (action.forValue !== action.current || action.text === "") return state;
+      return { ...state, forValue: action.forValue, text: action.text };
+    case "dismiss":
+      return { forValue: null, text: "", dismissedFor: action.value };
+    case "clear":
+      return { ...state, forValue: null, text: "" };
+  }
+}
+
+/**
+ * Ghost text to show for `value`, or `""`. It is empty when the state answers a
+ * different draft, the draft is dismissed or the draft is skipped.
+ */
+export function visibleComposerPrediction(
+  state: ComposerPredictionState,
+  value: string,
+  minLength: number = COMPOSER_PREDICTION_MIN_LENGTH,
+): string {
+  if (state.forValue !== value || state.dismissedFor === value) return "";
+  if (shouldSkipComposerPrediction(value, minLength)) return "";
+  return joinComposerPrediction(value, state.text);
+}
+
+/** The draft after Tab: the draft with the ghost text appended. */
+export function acceptComposerPrediction(value: string, ghost: string): string {
+  return value + ghost;
+}

package/src/composer/useComposerPrediction.ts

@@ -0,0 +1,86 @@
+import * as React from "react";
+
+import {
+  COMPOSER_PREDICTION_DEBOUNCE_MS,
+  COMPOSER_PREDICTION_MIN_LENGTH,
+  initialComposerPredictionState,
+  nextComposerPredictionState,
+  shouldSkipComposerPrediction,
+  visibleComposerPrediction,
+} from "./prediction";
+
+export type UseComposerPredictionOptions = {
+  value: string;
+  /** Off when there is no `getPrediction`, the composer is busy, or the caret is not at the end. */
+  enabled: boolean;
+  getPrediction?: (draft: string, opts: { signal: AbortSignal }) => Promise<string>;
+  debounceMs?: number;
+  minLength?: number;
+};
+
+export type ComposerPrediction = {
+  /** Ghost text to render after the draft, including any joining space. `""` when none. */
+  ghost: string;
+  dismiss: () => void;
+  clear: () => void;
+};
+
+/**
+ * Debounced ghost-text prediction for a draft. It does no I/O itself: the caller
+ * supplies `getPrediction`. Each draft change aborts the previous request. A
+ * result that arrives after its signal aborted, or after the draft changed, is
+ * dropped. Errors from `getPrediction` are swallowed: a failed prediction shows
+ * nothing.
+ */
+export function useComposerPrediction({
+  value,
+  enabled,
+  getPrediction,
+  debounceMs = COMPOSER_PREDICTION_DEBOUNCE_MS,
+  minLength = COMPOSER_PREDICTION_MIN_LENGTH,
+}: UseComposerPredictionOptions): ComposerPrediction {
+  const [state, dispatch] = React.useReducer(
+    nextComposerPredictionState,
+    initialComposerPredictionState,
+  );
+
+  const latestValue = React.useRef(value);
+  latestValue.current = value;
+  const getPredictionRef = React.useRef(getPrediction);
+  getPredictionRef.current = getPrediction;
+  const active = enabled && getPrediction !== undefined;
+
+  const skip = shouldSkipComposerPrediction(value, minLength);
+  const settled = state.forValue === value || state.dismissedFor === value;
+
+  React.useEffect(() => {
+    if (!active || skip || settled) return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      const request = getPredictionRef.current;
+      if (!request) return;
+      request(value, { signal: controller.signal }).then(
+        (text) => {
+          if (controller.signal.aborted) return;
+          dispatch({ type: "result", forValue: value, text, current: latestValue.current });
+        },
+        () => {},
+      );
+    }, debounceMs);
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [value, active, skip, settled, debounceMs]);
+
+  const ghost = active ? visibleComposerPrediction(state, value, minLength) : "";
+
+  return {
+    ghost,
+    dismiss: React.useCallback(
+      () => dispatch({ type: "dismiss", value: latestValue.current }),
+      [],
+    ),
+    clear: React.useCallback(() => dispatch({ type: "clear" }), []),
+  };
+}

package/src/index.ts

@@ -98,3 +98,5 @@ export * from "./ai-elements/speech-input";
 export * from "./ai-elements/suggestion";
 
 export * from "./audio";
+
+export * from "./composer";

package/src/ui/sonner.tsx

@@ -1,4 +1,4 @@
-import type { CSSProperties } from "react";
+import type { CSSProperties, ReactNode } from "react";
 import { Toaster, type ToasterProps } from "sonner";
 import { filledToastIcons } from "./sonner-icons";
 import "./sonner.css";
@@ -45,10 +45,22 @@ type SonnerToasterOptions = {
   sonnerVars?: boolean;
   /** When true, descriptions use `text-muted-foreground!` so sonner's dark rule cannot win. */
   descriptionMuted?: boolean;
+  /** `"snug"` (default) keeps `leading-snug`. `"5"` uses `leading-5` (20px at `text-sm`). */
+  titleLeading?: "snug" | "5";
+  /** Custom loading icon. Merged into `icons`. A caller `icons.loading` wins. */
+  loadingIcon?: ReactNode;
+  /**
+   * When true, adds a class that hides the content of toasts behind the front toast
+   * while the stack is collapsed. Default false. `sonner.css` has the same rule.
+   */
+  hideStackedContent?: boolean;
 };
 
+const hideStackedContentClassName =
+  "[&[data-expanded=false][data-front=false]>*]:opacity-0";
+
 const hoverChipCloseButtonClassName =
-  "pointer-events-none absolute -right-2 -top-2 z-10 flex h-6 w-6 items-center justify-center rounded-full border border-border bg-card/95 text-muted-foreground opacity-0 transition-opacity hover:text-foreground focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring group-hover:pointer-events-auto group-hover:opacity-100 max-sm:pointer-events-auto max-sm:opacity-100 max-sm:hit-target";
+  "pointer-events-none absolute -right-2 -top-2 z-10 flex h-6 w-6 items-center justify-center rounded-full border border-border bg-card/95 text-muted-foreground opacity-0 transition-opacity hover:border-border! hover:text-foreground focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring group-hover:pointer-events-auto group-hover:opacity-100 max-sm:pointer-events-auto max-sm:opacity-100 max-sm:hit-target";
 
 const defaultCloseButtonClassName =
   "rounded-lg bg-default px-2.5 py-1 text-xs font-medium text-foreground transition-colors hover:bg-default/78";
@@ -65,16 +77,23 @@ function createToasterClassNames({
   density = "default",
   closeButtonStyle = "default",
   descriptionMuted = false,
+  titleLeading = "snug",
+  hideStackedContent = false,
 }: Pick<
   SonnerToasterOptions,
-  "toastRadius" | "density" | "closeButtonStyle" | "descriptionMuted"
+  | "toastRadius"
+  | "density"
+  | "closeButtonStyle"
+  | "descriptionMuted"
+  | "titleLeading"
+  | "hideStackedContent"
 > = {}): ToastClassNames {
   const radius = toastRadiusClasses[toastRadius];
   const compact = density === "compact";
   const descriptionSize = compact ? "text-xs" : "text-[13px]";
   return {
-    toast: `group toast glass-panel-strong flex w-full items-center ${compact ? "gap-2" : "gap-3"} ${radius} ${compact ? "px-3 py-2 text-xs" : "px-4 py-3 text-sm"} text-foreground smooth-shadow-ring-md`,
-    title: "font-medium leading-snug",
+    toast: `group toast glass-panel-strong flex w-full items-center ${compact ? "gap-2" : "gap-3"} ${radius} ${compact ? "px-3 py-2 text-xs" : "px-4 py-3 text-sm"} text-foreground smooth-shadow-ring-md${hideStackedContent ? ` ${hideStackedContentClassName}` : ""}`,
+    title: titleLeading === "5" ? "font-medium leading-5" : "font-medium leading-snug",
     description: descriptionMuted
       ? `${descriptionSize} leading-snug text-muted-foreground!`
       : `${descriptionSize} leading-snug text-muted-foreground`,
@@ -148,6 +167,9 @@ function SonnerToaster({
   closeButtonStyle = "default",
   sonnerVars = false,
   descriptionMuted,
+  titleLeading,
+  loadingIcon,
+  hideStackedContent,
   toastOptions,
   icons,
   style,
@@ -155,8 +177,14 @@ function SonnerToaster({
   closeButton,
   ...props
 }: ToasterProps & SonnerToasterOptions) {
+  const loadingOverride =
+    loadingIcon != null ? { loading: loadingIcon } : undefined;
   const mergedIcons =
-    toastIcons === "filled24" ? { ...filledToastIcons, ...icons } : icons;
+    toastIcons === "filled24"
+      ? { ...filledToastIcons, ...loadingOverride, ...icons }
+      : loadingOverride
+        ? { ...loadingOverride, ...icons }
+        : icons;
   return (
     <Toaster
       expand={false}
@@ -175,6 +203,8 @@ function SonnerToaster({
             density,
             closeButtonStyle,
             descriptionMuted,
+            titleLeading,
+            hideStackedContent,
           }),
         },
         toastOptions,