@kinetixui/ui 0.10.0 → 0.12.0

package/src/components/kanban-board.tsx

@@ -0,0 +1,246 @@
+"use client";
+
+import * as React from "react";
+import {
+  DndContext,
+  DragOverlay,
+  KeyboardSensor,
+  PointerSensor,
+  closestCenter,
+  getFirstCollision,
+  pointerWithin,
+  rectIntersection,
+  useDroppable,
+  useSensor,
+  useSensors,
+  type CollisionDetection,
+  type DragEndEvent,
+  type DragOverEvent,
+  type DragStartEvent,
+} from "@dnd-kit/core";
+import {
+  SortableContext,
+  arrayMove,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { cn } from "../lib/utils";
+
+export interface KanbanCard {
+  id: string;
+  content: React.ReactNode;
+}
+
+export interface KanbanColumn {
+  id: string;
+  title: string;
+  cards: KanbanCard[];
+}
+
+export interface KanbanBoardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  columns: KanbanColumn[];
+  onColumnsChange: (columns: KanbanColumn[]) => void;
+}
+
+/**
+ * KanbanBoard — draggable cards across columns, with keyboard DnD. No DnD
+ * primitive existed in this package at all, and hand-rolling accessible
+ * drag-and-drop (pointer + touch + keyboard, collision detection, live
+ * screen-reader announcements) from scratch would both take far longer
+ * than this component's own logic and likely be worse than a battle-tested
+ * library — unlike `DiffViewer`'s hand-rolled LCS diff, there's no
+ * cross-platform-identical-algorithm argument here, since each native
+ * platform reaches for its own idiomatic drag primitive anyway (Compose's
+ * drag gestures, SwiftUI's `.draggable`/`.dropDestination`, Flutter's
+ * `Draggable`/`DragTarget`). `@dnd-kit` is the dependency: no runtime CSS,
+ * accessible by default, and this is exactly its documented "multiple
+ * containers" sortable pattern — `onDragOver` re-parents a card into the
+ * hovered column live (the standard approach; a little re-render churn
+ * mid-drag is expected/upstream-documented), `onDragEnd` commits the
+ * final within-column reorder. Column order itself isn't draggable — the
+ * `COMPONENT-ADDITIONS.md` entry only asked for card dragging.
+ *
+ * `collisionDetectionStrategy` below is dnd-kit's own documented fix for a
+ * specific multi-container gotcha: each column is both a `useDroppable`
+ * (so an empty column, or the space below its last card, is still a valid
+ * drop target) and wraps a `SortableContext` of its cards. A column's rect
+ * is a strict superset of its cards' rects, so plain `closestCorners` (or
+ * `closestCenter`/`rectIntersection` alone) almost always reports the
+ * column itself as the collision, never a specific card underneath — over
+ * gets stuck on the column id and item-level reordering never fires. The
+ * fix (lifted from dnd-kit's own multiple-containers example): try
+ * `pointerWithin` first, fall back to `rectIntersection`, and if the
+ * winning id is a column, re-run `closestCenter` scoped to just that
+ * column's cards to find the specific one under the pointer.
+ */
+const KanbanBoard = React.forwardRef<HTMLDivElement, KanbanBoardProps>(
+  ({ columns, onColumnsChange, className, ...props }, ref) => {
+    const sensors = useSensors(
+      useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
+      useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+    );
+    const [activeCard, setActiveCard] = React.useState<KanbanCard | null>(null);
+    const lastOverId = React.useRef<string | null>(null);
+
+    const findColumn = React.useCallback(
+      (id: string) => columns.find((col) => col.id === id || col.cards.some((c) => c.id === id)),
+      [columns],
+    );
+
+    const collisionDetectionStrategy: CollisionDetection = React.useCallback(
+      (args) => {
+        const pointerIntersections = pointerWithin(args);
+        const intersections = pointerIntersections.length > 0 ? pointerIntersections : rectIntersection(args);
+        let overId = getFirstCollision(intersections, "id");
+
+        if (overId != null) {
+          const overColumn = columns.find((col) => col.id === overId);
+          if (overColumn && overColumn.cards.length > 0) {
+            const cardIds = new Set(overColumn.cards.map((c) => c.id));
+            const cardCollision = getFirstCollision(
+              closestCenter({
+                ...args,
+                droppableContainers: args.droppableContainers.filter((c) => cardIds.has(String(c.id))),
+              }),
+              "id",
+            );
+            if (cardCollision != null) overId = cardCollision;
+          }
+          lastOverId.current = String(overId);
+          return [{ id: overId }];
+        }
+
+        return lastOverId.current ? [{ id: lastOverId.current }] : [];
+      },
+      [columns],
+    );
+
+    function handleDragStart(event: DragStartEvent) {
+      lastOverId.current = String(event.active.id);
+      const column = findColumn(String(event.active.id));
+      const card = column?.cards.find((c) => c.id === event.active.id);
+      setActiveCard(card ?? null);
+    }
+
+    function handleDragOver(event: DragOverEvent) {
+      const { active, over } = event;
+      if (!over) return;
+      const activeId = String(active.id);
+      const overId = String(over.id);
+      if (activeId === overId) return;
+
+      const activeColumn = findColumn(activeId);
+      const overColumn = findColumn(overId);
+      if (!activeColumn || !overColumn || activeColumn.id === overColumn.id) return;
+
+      onColumnsChange(
+        columns.map((col) => {
+          if (col.id === activeColumn.id) {
+            return { ...col, cards: col.cards.filter((c) => c.id !== activeId) };
+          }
+          if (col.id === overColumn.id) {
+            const movedCard = activeColumn.cards.find((c) => c.id === activeId);
+            if (!movedCard) return col;
+            const overIndex = col.cards.findIndex((c) => c.id === overId);
+            const insertAt = overIndex >= 0 ? overIndex : col.cards.length;
+            const nextCards = [...col.cards];
+            nextCards.splice(insertAt, 0, movedCard);
+            return { ...col, cards: nextCards };
+          }
+          return col;
+        }),
+      );
+    }
+
+    function handleDragEnd(event: DragEndEvent) {
+      setActiveCard(null);
+      lastOverId.current = null;
+      const { active, over } = event;
+      if (!over) return;
+      const activeId = String(active.id);
+      const overId = String(over.id);
+      const activeColumn = findColumn(activeId);
+      // overId may be the column itself (dropped in empty space / an empty column)
+      const overColumn = columns.find((col) => col.id === overId) ?? findColumn(overId);
+      if (!activeColumn || !overColumn || activeColumn.id !== overColumn.id) return;
+
+      const activeIndex = activeColumn.cards.findIndex((c) => c.id === activeId);
+      const rawOverIndex = overColumn.cards.findIndex((c) => c.id === overId);
+      const overIndex = rawOverIndex >= 0 ? rawOverIndex : overColumn.cards.length - 1;
+      if (activeIndex === -1 || overIndex === -1 || activeIndex === overIndex) return;
+
+      onColumnsChange(
+        columns.map((col) =>
+          col.id === activeColumn.id ? { ...col, cards: arrayMove(col.cards, activeIndex, overIndex) } : col,
+        ),
+      );
+    }
+
+    return (
+      <DndContext
+        sensors={sensors}
+        collisionDetection={collisionDetectionStrategy}
+        onDragStart={handleDragStart}
+        onDragOver={handleDragOver}
+        onDragEnd={handleDragEnd}
+        onDragCancel={() => {
+          setActiveCard(null);
+          lastOverId.current = null;
+        }}
+      >
+        <div ref={ref} role="group" className={cn("flex items-start gap-4 overflow-x-auto font-sans", className)} {...props}>
+          {columns.map((column) => (
+            <KanbanColumnView key={column.id} column={column} />
+          ))}
+        </div>
+        <DragOverlay>{activeCard ? <KanbanCardView card={activeCard} /> : null}</DragOverlay>
+      </DndContext>
+    );
+  },
+);
+KanbanBoard.displayName = "KanbanBoard";
+
+function KanbanColumnView({ column }: { column: KanbanColumn }) {
+  const { setNodeRef } = useDroppable({ id: column.id });
+  return (
+    <div className="flex w-64 shrink-0 flex-col gap-2 rounded-md border bg-muted/30 p-2">
+      <div className="flex items-center justify-between px-1 py-1">
+        <span className="text-sm font-medium text-foreground">{column.title}</span>
+        <span className="text-xs text-muted-foreground">{column.cards.length}</span>
+      </div>
+      <SortableContext items={column.cards.map((c) => c.id)} strategy={verticalListSortingStrategy}>
+        <div ref={setNodeRef} className="flex min-h-10 flex-col gap-2">
+          {column.cards.map((card) => (
+            <SortableKanbanCard key={card.id} card={card} />
+          ))}
+        </div>
+      </SortableContext>
+    </div>
+  );
+}
+
+function SortableKanbanCard({ card }: { card: KanbanCard }) {
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id: card.id });
+  const style: React.CSSProperties = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+    opacity: isDragging ? 0.4 : 1,
+  };
+  return (
+    <div ref={setNodeRef} style={style} {...attributes} {...listeners}>
+      <KanbanCardView card={card} />
+    </div>
+  );
+}
+
+function KanbanCardView({ card }: { card: KanbanCard }) {
+  return (
+    <div className="cursor-grab touch-none rounded-md border bg-background p-3 text-sm text-foreground shadow-sm outline-none active:cursor-grabbing focus-visible:ring-1 focus-visible:ring-ring">
+      {card.content}
+    </div>
+  );
+}
+
+export { KanbanBoard };

package/src/components/markdown-editor.tsx

@@ -0,0 +1,288 @@
+"use client";
+
+import * as React from "react";
+import { Bold, Code, Eye, EyeOff, Heading2, Italic, Link as LinkIcon, List, ListOrdered, Quote } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Textarea } from "./textarea";
+
+export interface MarkdownEditorProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "onChange"> {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  rows?: number;
+}
+
+function wrapSelection(text: string, start: number, end: number, before: string, after: string, placeholder: string) {
+  const selected = text.slice(start, end) || placeholder;
+  const next = text.slice(0, start) + before + selected + after + text.slice(end);
+  return { text: next, selectionStart: start + before.length, selectionEnd: start + before.length + selected.length };
+}
+
+function prefixLines(text: string, start: number, end: number, prefix: (lineIndex: number) => string) {
+  const lineStart = text.lastIndexOf("\n", Math.max(start - 1, 0)) + 1;
+  let lineEnd = text.indexOf("\n", Math.max(end, lineStart));
+  if (lineEnd === -1) lineEnd = text.length;
+  const block = text.slice(lineStart, lineEnd);
+  const lines = block.split("\n");
+  const prefixed = lines.map((line, i) => prefix(i) + line).join("\n");
+  return {
+    text: text.slice(0, lineStart) + prefixed + text.slice(lineEnd),
+    selectionStart: start + prefix(0).length,
+    selectionEnd: end + (prefixed.length - block.length),
+  };
+}
+
+/** HTML-escapes source text before any markup is inserted — see the render call below. */
+function escapeHtml(s: string) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function renderInline(escaped: string): string {
+  return escaped
+    .replace(/`([^`]+)`/g, "<code>$1</code>")
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/\*([^*]+)\*/g, "<em>$1</em>")
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (match, label: string, url: string) => {
+      const safe = /^(https?:|mailto:|\/|#)/i.test(url.trim());
+      return safe ? `<a href="${url}" target="_blank" rel="noopener noreferrer">${label}</a>` : match;
+    });
+}
+
+/**
+ * A small hand-rolled Markdown → HTML renderer covering exactly the syntax
+ * the toolbar below produces (headings, bold, italic, links, inline/block
+ * code, bullet/numbered lists, blockquotes, paragraphs) — not a full
+ * CommonMark implementation. Kept dependency-free and simple enough to
+ * port identically to Compose/SwiftUI/Flutter, the same reasoning as
+ * `DiffViewer`'s hand-rolled LCS diff.
+ */
+
+/**
+ * Matches `markerRe` at the start of `line`, then requires at least one
+ * space/tab before returning the rest as `content`. Deliberately not a
+ * single `markerRe` + `\s+(.*)$` regex: two adjacent unbounded quantifiers
+ * over overlapping character classes (`\s` and `.` both match a space) is
+ * a catastrophic-backtracking shape CodeQL flags as a ReDoS — walking the
+ * whitespace run by hand is linear and can't backtrack.
+ */
+function matchMarker(line: string, markerRe: RegExp): { marker: string; content: string } | null {
+  const m = markerRe.exec(line);
+  if (!m) return null;
+  let i = m[0].length;
+  if (line[i] !== " " && line[i] !== "\t") return null;
+  while (line[i] === " " || line[i] === "\t") i++;
+  return { marker: m[0], content: line.slice(i) };
+}
+
+function renderMarkdown(source: string): string {
+  const lines = source.split("\n");
+  const out: string[] = [];
+  let inCode = false;
+  let codeLines: string[] = [];
+  let listType: "ul" | "ol" | null = null;
+
+  const closeList = () => {
+    if (listType) {
+      out.push(`</${listType}>`);
+      listType = null;
+    }
+  };
+
+  for (const line of lines) {
+    if (line.trim().startsWith("```")) {
+      if (inCode) {
+        out.push(`<pre><code>${escapeHtml(codeLines.join("\n"))}</code></pre>`);
+        codeLines = [];
+        inCode = false;
+      } else {
+        closeList();
+        inCode = true;
+      }
+      continue;
+    }
+    if (inCode) {
+      codeLines.push(line);
+      continue;
+    }
+
+    const heading = matchMarker(line, /^#{1,6}/);
+    if (heading) {
+      closeList();
+      const level = heading.marker.length;
+      out.push(`<h${level}>${renderInline(escapeHtml(heading.content))}</h${level}>`);
+      continue;
+    }
+
+    const quote = line.match(/^>\s?(.*)$/);
+    if (quote) {
+      closeList();
+      out.push(`<blockquote>${renderInline(escapeHtml(quote[1]!))}</blockquote>`);
+      continue;
+    }
+
+    const bullet = matchMarker(line, /^[-*]/);
+    if (bullet) {
+      if (listType !== "ul") {
+        closeList();
+        out.push("<ul>");
+        listType = "ul";
+      }
+      out.push(`<li>${renderInline(escapeHtml(bullet.content))}</li>`);
+      continue;
+    }
+
+    const numbered = matchMarker(line, /^\d+\./);
+    if (numbered) {
+      if (listType !== "ol") {
+        closeList();
+        out.push("<ol>");
+        listType = "ol";
+      }
+      out.push(`<li>${renderInline(escapeHtml(numbered.content))}</li>`);
+      continue;
+    }
+
+    closeList();
+    if (line.trim() === "") continue;
+    out.push(`<p>${renderInline(escapeHtml(line))}</p>`);
+  }
+  closeList();
+  if (inCode) out.push(`<pre><code>${escapeHtml(codeLines.join("\n"))}</code></pre>`);
+
+  return out.join("\n");
+}
+
+/**
+ * MarkdownEditor — toolbar + a plain `Textarea` (the markdown source) with
+ * an optional rendered preview pane. Deliberately *not* `contenteditable`
+ * (no Tiptap/Lexical): `contenteditable` has no native-platform analogue,
+ * so a WYSIWYG rich-text editor would be a web-only, eighth standing
+ * non-port. A markdown textarea is just a text buffer the toolbar inserts
+ * syntax into — SwiftUI's `TextEditor`, Compose's `BasicTextField`, and
+ * Flutter's `TextField` all support the same selection-based insertion, so
+ * this ports cleanly to all four platforms instead.
+ */
+const MarkdownEditor = React.forwardRef<HTMLDivElement, MarkdownEditorProps>(
+  ({ value, onChange, placeholder, rows = 10, className, ...props }, ref) => {
+    const textareaRef = React.useRef<HTMLTextAreaElement>(null);
+    const [showPreview, setShowPreview] = React.useState(false);
+    const pendingSelection = React.useRef<{ start: number; end: number } | null>(null);
+
+    React.useEffect(() => {
+      if (pendingSelection.current && textareaRef.current) {
+        const { start, end } = pendingSelection.current;
+        textareaRef.current.focus();
+        textareaRef.current.setSelectionRange(start, end);
+        pendingSelection.current = null;
+      }
+    }, [value]);
+
+    const applyInline = (before: string, after: string, placeholder: string) => {
+      const el = textareaRef.current;
+      if (!el) return;
+      const result = wrapSelection(value, el.selectionStart, el.selectionEnd, before, after, placeholder);
+      pendingSelection.current = { start: result.selectionStart, end: result.selectionEnd };
+      onChange(result.text);
+    };
+
+    const applyLinePrefix = (prefix: (lineIndex: number) => string) => {
+      const el = textareaRef.current;
+      if (!el) return;
+      const result = prefixLines(value, el.selectionStart, el.selectionEnd, prefix);
+      pendingSelection.current = { start: result.selectionStart, end: result.selectionEnd };
+      onChange(result.text);
+    };
+
+    return (
+      <div ref={ref} className={cn("overflow-hidden rounded-md border font-sans", className)} {...props}>
+        <div role="toolbar" aria-label="Formatting" className="flex items-center gap-0.5 border-b bg-muted/40 p-1">
+          <ToolbarButton label="Bold" onClick={() => applyInline("**", "**", "bold text")}>
+            <Bold className="size-4" />
+          </ToolbarButton>
+          <ToolbarButton label="Italic" onClick={() => applyInline("*", "*", "italic text")}>
+            <Italic className="size-4" />
+          </ToolbarButton>
+          <ToolbarButton label="Heading" onClick={() => applyLinePrefix(() => "## ")}>
+            <Heading2 className="size-4" />
+          </ToolbarButton>
+          <ToolbarButton label="Link" onClick={() => applyInline("[", "](https://)", "link text")}>
+            <LinkIcon className="size-4" />
+          </ToolbarButton>
+          <ToolbarButton label="Bulleted list" onClick={() => applyLinePrefix(() => "- ")}>
+            <List className="size-4" />
+          </ToolbarButton>
+          <ToolbarButton label="Numbered list" onClick={() => applyLinePrefix((i) => `${i + 1}. `)}>
+            <ListOrdered className="size-4" />
+          </ToolbarButton>
+          <ToolbarButton label="Code" onClick={() => applyInline("`", "`", "code")}>
+            <Code className="size-4" />
+          </ToolbarButton>
+          <ToolbarButton label="Quote" onClick={() => applyLinePrefix(() => "> ")}>
+            <Quote className="size-4" />
+          </ToolbarButton>
+          <ToolbarButton
+            label={showPreview ? "Hide preview" : "Show preview"}
+            onClick={() => setShowPreview((v) => !v)}
+            active={showPreview}
+            className="ml-auto"
+          >
+            {showPreview ? <EyeOff className="size-4" /> : <Eye className="size-4" />}
+          </ToolbarButton>
+        </div>
+        <div className={cn("grid", showPreview && "grid-cols-2 divide-x")}>
+          <Textarea
+            ref={textareaRef}
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+            placeholder={placeholder}
+            rows={rows}
+            className="resize-none rounded-none border-0 font-mono text-[13px] focus-visible:border-transparent focus-visible:shadow-none"
+          />
+          {showPreview && (
+            <div
+              className="overflow-auto p-3 text-sm [&_a]:text-primary [&_a]:underline [&_blockquote]:border-l-2 [&_blockquote]:border-border [&_blockquote]:pl-3 [&_blockquote]:text-muted-foreground [&_code]:rounded-sm [&_code]:bg-muted [&_code]:px-1 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em] [&_h1]:text-xl [&_h1]:font-semibold [&_h2]:text-lg [&_h2]:font-semibold [&_h3]:font-semibold [&_li]:ml-5 [&_ol]:list-decimal [&_p]:mb-2 [&_pre]:overflow-auto [&_pre]:rounded-sm [&_pre]:bg-muted [&_pre]:p-2 [&_ul]:list-disc"
+              // Rendered from renderMarkdown above, which HTML-escapes all
+              // source text before inserting any markup — safe from
+              // injection, same trust boundary as any other self-generated
+              // innerHTML (not raw user HTML).
+              dangerouslySetInnerHTML={{ __html: renderMarkdown(value) }}
+            />
+          )}
+        </div>
+      </div>
+    );
+  },
+);
+MarkdownEditor.displayName = "MarkdownEditor";
+
+function ToolbarButton({
+  label,
+  onClick,
+  active,
+  className,
+  children,
+}: {
+  label: string;
+  onClick: () => void;
+  active?: boolean;
+  className?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label={label}
+      aria-pressed={active}
+      className={cn(
+        "inline-flex size-7 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground",
+        active && "bg-accent text-foreground",
+        className,
+      )}
+    >
+      {children}
+    </button>
+  );
+}
+
+export { MarkdownEditor };

package/src/components/marquee.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * Marquee — an auto-scrolling horizontal ticker (logo strip, testimonials),
+ * pausing on hover and respecting `prefers-reduced-motion`. Lifted out of
+ * the marketing site's `reveal.tsx` (`.kx-marquee`/`.kx-marquee-track` in
+ * its `globals.css`) into a portable component: the site version leaned on
+ * a hand-written CSS file a CLI-installed app wouldn't have, so this port
+ * moves the keyframe onto the shared Tailwind preset (`animate-marquee`,
+ * `motion-reduce:animate-none`) instead. Also fixes an accessibility gap
+ * in the site version, which marked *both* content copies `aria-hidden`
+ * (hiding the marquee from screen readers entirely) — only the duplicate
+ * copy needed for the seamless loop is hidden here; the first copy stays
+ * in the accessible DOM flow. Gap-fill addition (not in the original
+ * Figma source).
+ */
+export interface MarqueeProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** seconds for one full loop */
+  durationSeconds?: number;
+  pauseOnHover?: boolean;
+}
+
+const Marquee = React.forwardRef<HTMLDivElement, MarqueeProps>(
+  ({ className, children, durationSeconds = 32, pauseOnHover = true, style, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        "group relative flex overflow-hidden",
+        "[mask-image:linear-gradient(90deg,transparent,black_8%,black_92%,transparent)]",
+        className,
+      )}
+      style={{ ["--marquee-duration" as string]: `${durationSeconds}s`, ...style }}
+      {...props}
+    >
+      {/* the track is 2x content width (two copies side by side); animating it
+          exactly -50% of its own width moves it one content-width, which is
+          what makes the loop seamless when it snaps back to 0. */}
+      <div
+        className={cn(
+          "flex w-max animate-marquee motion-reduce:animate-none",
+          pauseOnHover && "group-hover:[animation-play-state:paused]",
+        )}
+      >
+        <div className="flex shrink-0 items-center">{children}</div>
+        <div aria-hidden="true" className="flex shrink-0 items-center">
+          {children}
+        </div>
+      </div>
+    </div>
+  ),
+);
+Marquee.displayName = "Marquee";
+
+export { Marquee };

package/src/components/message-bubble.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import * as React from "react";
+import { Check, CheckCheck } from "lucide-react";
+import { cn } from "../lib/utils";
+
+/**
+ * MessageBubble — a sent/received chat bubble with grouping, timestamp,
+ * and a status tick. `grouped` is a lightweight consecutive-run cue
+ * (reduces the outer top corner's radius, the side that would otherwise
+ * repeat the previous bubble's rounding) rather than full first/middle/
+ * last position tracking — the caller already knows which messages are
+ * consecutive, so it stays a single boolean rather than the component
+ * inferring group position itself. Gap-fill addition (not in the
+ * original Figma source), the last pick from the `COMPONENT-ADDITIONS.md`
+ * Tier 2 backlog.
+ */
+export interface MessageBubbleProps extends React.HTMLAttributes<HTMLDivElement> {
+  variant?: "sent" | "received";
+  timestamp?: React.ReactNode;
+  status?: "sent" | "delivered" | "read";
+  /** part of a consecutive run of bubbles from the same sender */
+  grouped?: boolean;
+  avatar?: React.ReactNode;
+}
+
+const MessageBubble = React.forwardRef<HTMLDivElement, MessageBubbleProps>(
+  ({ className, variant = "received", timestamp, status, grouped = false, avatar, children, ...props }, ref) => {
+    const sent = variant === "sent";
+    return (
+      <div ref={ref} className={cn("flex items-end gap-2 font-sans", sent && "flex-row-reverse", className)} {...props}>
+        {avatar && !sent && <div className="shrink-0 self-end">{avatar}</div>}
+        <div className={cn("flex max-w-[75%] flex-col gap-1", sent ? "items-end" : "items-start")}>
+          <div
+            className={cn(
+              "min-w-0 rounded-2xl px-3.5 py-2 text-body-sm",
+              sent ? "bg-primary text-primary-foreground" : "bg-muted text-foreground",
+              sent && grouped && "rounded-tr-md",
+              !sent && grouped && "rounded-tl-md",
+            )}
+          >
+            {children}
+          </div>
+          {(timestamp || (sent && status)) && (
+            <div className="flex items-center gap-1 px-1 text-label-sm text-muted-foreground">
+              {timestamp}
+              {sent && status && (
+                <span className={cn(status === "read" && "text-primary")}>
+                  {status === "sent" ? <Check className="size-3.5" /> : <CheckCheck className="size-3.5" />}
+                </span>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  },
+);
+MessageBubble.displayName = "MessageBubble";
+
+const TypingIndicator = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div
+      ref={ref}
+      role="status"
+      aria-label="Typing"
+      className={cn("flex w-fit items-center gap-1 rounded-2xl bg-muted px-3.5 py-2.5", className)}
+      {...props}
+    >
+      {[0, 1, 2].map((i) => (
+        <span
+          key={i}
+          aria-hidden
+          className="size-1.5 animate-typing-dot rounded-full bg-muted-foreground"
+          style={{ animationDelay: `${i * 150}ms` }}
+        />
+      ))}
+    </div>
+  ),
+);
+TypingIndicator.displayName = "TypingIndicator";
+
+export { MessageBubble, TypingIndicator };