@exegia/corpora-ui 0.28.0 → 1.0.0

package/src/components/composed/action-bar/types.ts

@@ -0,0 +1,58 @@
+import type { ButtonProps } from "@/components/ui/button";
+import type { PopoverGlassProps } from "@/components/ui/popover-glass";
+import type { ToolbarSeparatorProps } from "@base-ui/react";
+import type { Emoji } from "frimousse";
+import type { LucideIcon } from "lucide-react";
+import type { FunctionComponent } from "react";
+
+
+export interface ActionButtonProps<T extends string> extends Omit<ButtonProps, "variant" | "glassVariant" | "size"> {
+  action: () => void;
+  tooltip?: string;
+  Icon: LucideIcon | Emoji;
+  id: T;
+}
+
+type ActionBarItemType = "action" | "separator";
+export type ActionKey<T extends string = string, Type extends ActionBarItemType = "action"> = `${Type}-${T}`;
+
+/**
+ * Insertion order is the contract: the bar groups positionally, so the order
+ * keys are written is the order they render. Safe because every `ActionKey`
+ * is a non-numeric `${type}-${name}` string, which `Object.entries` preserves
+ * — but a map built by spreading or `Object.fromEntries` must keep that order.
+ */
+export type ActionMap<T extends ActionKey> = Record<T, FunctionComponent<ActionButtonProps<T> | ToolbarSeparatorProps>>;
+
+export type ActionEntry = readonly [
+  key: string,
+  Item: FunctionComponent<ActionButtonProps<string> | ToolbarSeparatorProps>,
+];
+
+/** Actions between two separators, rendered inside one `ToolbarGroup`. */
+export type ActionItemsByGroup = Record<string, ActionEntry[]>;
+
+/**
+ * The bar as an ordered, render-ready list. A "group" is a run of consecutive
+ * actions; a "separator" is whatever component the map supplied for that key.
+ * Empty groups (leading, trailing or back-to-back separators) are dropped.
+ */
+export type ActionBarSegment =
+  | { type: "group"; key: string; items: ActionEntry[] }
+  | { type: "separator"; key: string; Separator: FunctionComponent<ToolbarSeparatorProps> };
+
+export interface ActionBarProps extends Omit<PopoverGlassProps, "variant" | "children"> {
+  id: string;
+  variant: "default" | "ghost" | "glass";
+  actions: ActionMap<ActionKey>;
+}
+
+
+export interface EmojiActionBarProps {
+  /** Fires for both a quick reaction and a pick from the full picker. */
+  onEmojiSelect?: (emoji: Emoji) => void
+  /** Quick row contents. Defaults to {@link QUICK_REACTIONS}. */
+  reactions?: readonly Emoji[]
+  /** Hides the trailing "More" action, leaving the quick row only. */
+  hideMore?: boolean
+}

package/src/components/composed/action-bar/utils.ts

@@ -0,0 +1,141 @@
+import { type ComponentType, useMemo, useState } from "react"
+import { Tooltip } from "@base-ui/react/tooltip"
+import { TooltipCreateHandle } from "@/components/ui/tooltip"
+import type {
+  ActionBarSegment,
+  ActionEntry,
+  ActionItemsByGroup,
+  ActionKey,
+  ActionMap,
+  EmojiActionBarProps,
+} from "./types"
+import type { Emoji } from "frimousse"
+
+// Annotated, not inferred: the emitted .d.ts cannot name base-ui's
+// `TooltipHandle` on its own (TS2883).
+export const tooltipHandle: Tooltip.Handle<ComponentType> =
+  TooltipCreateHandle<ComponentType>()
+
+export const isSeparator = (key: string): boolean => key.includes("separator")
+
+/**
+ * Splits `actions` into render-ready segments at every `separator-*` key.
+ *
+ * Order comes from the map's insertion order (see `ActionMap`) — the grouping
+ * is positional, so actions written before a separator group ahead of it.
+ * Empty groups are dropped, which is what keeps a leading, trailing or
+ * doubled separator from rendering a `ToolbarGroup` with nothing in it.
+ */
+export const useActionBar = ({
+  actions,
+}: {
+  actions: ActionMap<ActionKey>
+}) => {
+  return useMemo(() => {
+    const entries = Object.entries(actions) as ActionEntry[]
+    const segments: ActionBarSegment[] = []
+    let open: ActionEntry[] = []
+
+    const closeGroup = (): void => {
+      if (open.length === 0) return
+      segments.push({ type: "group", key: `group-${open[0][0]}`, items: open })
+      open = []
+    }
+
+    for (const entry of entries) {
+      const [key, Item] = entry
+      if (isSeparator(key)) {
+        closeGroup()
+        segments.push({ type: "separator", key, Separator: Item })
+        continue
+      }
+      open.push(entry)
+    }
+    closeGroup()
+
+    const groups = segments.filter((s) => s.type === "group")
+
+    // A bar with no separators renders flat — `ToolbarGroup` is only added
+    // once the caller has actually asked for grouping.
+    const hasGroups = segments.some((s) => s.type === "separator")
+
+    const actionItemsByGroup: ActionItemsByGroup = Object.fromEntries(
+      groups.map((group) => [group.key, group.items])
+    )
+
+    return {
+      segments,
+      entries,
+      hasGroups,
+      groupsCount: groups.length,
+      separatorCount: segments.length - groups.length,
+      actionItemsByGroup,
+    }
+  }, [actions])
+}
+
+/**
+ * The quick row. frimousse has no way to render a subset — `EmojiPicker.Root`
+ * takes `columns`/`skinTone`/`locale`/`emojiVersion`/`emojibaseUrl`/`sticky`
+ * and nothing else, and its list is virtualized on fixed-height rows, so a
+ * custom `Emoji` component that returns null leaves holes rather than a short
+ * row. A fixed list is the only way to show just these, and it costs no
+ * network request — the CDN fetch only happens if "More" is opened.
+ */
+export const QUICK_REACTIONS: readonly Emoji[] = [
+  { emoji: "❤️", label: "heart" },
+  { emoji: "👍", label: "thumbs up" },
+  { emoji: "😊", label: "smiling face" },
+  { emoji: "😂", label: "face with tears of joy" },
+  { emoji: "🎉", label: "party popper" },
+  { emoji: "🙏", label: "folded hands" },
+]
+
+/**
+ * Hook for managing the emoji picker state and actions.
+ *
+ * @param props - The emoji picker props.
+ * @returns The emoji picker state and actions.
+ *
+ * @example
+ * ```tsx
+ * const { isFullPicker, quickReactions, actions, togglePicker, selectEmoji } = useEmojiPicker({ onEmojiSelect });
+ * ```
+ */
+export const useEmojiPicker = ({
+  onEmojiSelect,
+  reactions,
+  hideMore,
+}: EmojiActionBarProps) => {
+  const [isFullPicker, setShowAll] = useState(false)
+
+  // Toggles the picker between quick reactions and the full picker.
+  const togglePicker = () => setShowAll((previous) => !previous)
+  /**
+   * Reports the pick and folds the full picker back to the quick row. The bar
+   * lives inside a `keepMounted` popover, so it is never unmounted on close —
+   * without this reset the next open would still show the full picker.
+   */
+  const selectEmoji = (emoji: Emoji): void => {
+    setShowAll(false)
+    onEmojiSelect?.(emoji)
+  }
+  // The quick reactions to display.
+  const quickReactions = reactions ?? QUICK_REACTIONS
+  const actions = useMemo(() => {
+    if (hideMore) return quickReactions
+    return [
+      ...quickReactions,
+      { emoji: "Separator", label: "separator" },
+      { emoji: "More", label: "More emoji" },
+    ]
+  }, [quickReactions, hideMore])
+
+  return {
+    isFullPicker,
+    quickReactions,
+    actions,
+    togglePicker,
+    selectEmoji,
+  }
+}

package/src/components/composed/ai/__tests__/ai.test.tsx

@@ -0,0 +1,67 @@
+import { describe, expect, mock, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+import { Message } from "../message"
+import type { AIContentProps } from "../types"
+
+describe("Message", () => {
+  test("renders the agent identity row and the body as a polite live region", () => {
+    const { container } = render(
+      <Message type="markdown">Hello reader</Message>
+    )
+
+    expect(screen.getByText("Exegia")).toBeDefined()
+    expect(screen.getByText("Agent")).toBeDefined()
+    expect(screen.getByText("AI Scholar")).toBeDefined()
+
+    const root = container.querySelector('[data-slot="ai-message"]')
+    expect(root).not.toBeNull()
+    expect(root!.getAttribute("data-variant")).toBe("ai")
+
+    const body = container.querySelector('[data-slot="ai-message-body"]')
+    expect(body).not.toBeNull()
+    expect(body!.getAttribute("aria-live")).toBe("polite")
+    expect(body!.textContent).toContain("Hello reader")
+  })
+
+  test("marks the root while streaming and drops the flag at rest", () => {
+    const { container, rerender } = render(
+      <Message isStreaming type="markdown" />
+    )
+    const root = container.querySelector('[data-slot="ai-message"]')!
+    expect(root.hasAttribute("data-streaming")).toBe(true)
+
+    rerender(<Message type="markdown" />)
+    expect(root.hasAttribute("data-streaming")).toBe(false)
+  })
+
+  test("hands AttachedContent the message type as `kind` plus contentProps", () => {
+    const seen = mock<(props: AIContentProps<"chart">) => void>(() => {})
+    const Attached = (props: AIContentProps<"chart">) => {
+      seen(props)
+      return <div data-testid="attached">chart goes here</div>
+    }
+
+    render(
+      <Message
+        AttachedContent={Attached}
+        contentProps={{ type: "bar", data: [], series: [] }}
+        type="chart"
+      />
+    )
+
+    expect(screen.getByTestId("attached")).toBeDefined()
+    expect(seen).toHaveBeenCalledTimes(1)
+    expect(seen.mock.calls[0]?.[0]).toMatchObject({
+      kind: "chart",
+      type: "bar",
+      data: [],
+      series: [],
+    })
+  })
+
+  test("renders no attachment slot when AttachedContent is omitted", () => {
+    const { container } = render(<Message type="markdown">Prose only</Message>)
+    const body = container.querySelector('[data-slot="ai-message-body"]')!
+    expect(body.textContent).toBe("Prose only")
+  })
+})

package/src/components/composed/ai/avatar.tsx

@@ -0,0 +1,20 @@
+import OWLImage from "@/assets/owl-avatar.png"
+import { Badge } from "@/components/ui/badge";
+import { Avatar as AvatarAtom } from "@/components/atoms";
+
+export const Avatar = () => {
+  return (
+    <div className="flex items-center gap-2">
+      <AvatarAtom size="default" className="bg-indigo-950 dark:bg-indigo-300 p-0.5 scale-110" user={{ avatarUrl: OWLImage }} />
+      <div className="flex flex-col">
+        <div className="flex items-center gap-1.5">
+          <span className="text-sm font-semibold">Exegia</span>
+          <Badge variant="default" size="xs">
+            Agent
+          </Badge>
+        </div>
+        <span className="text-xs text-muted-foreground">AI Scholar</span>
+      </div>
+    </div>
+  )
+}

package/src/components/composed/ai/index.ts

@@ -0,0 +1,36 @@
+import { Message } from "./message"
+import { StreamingText } from "./streaming-text"
+import { ResearchAnswer } from "./research-answer"
+import { SuggestedPrompt } from "./suggested-prompt"
+import { Avatar } from "./avatar"
+
+export type { SuggestedPromptProps } from "./suggested-prompt"
+
+export {
+  accentRing,
+  accentSolid,
+  accentText,
+  agentText,
+  ghostMuted,
+  glassCard,
+  mutedText,
+  surface,
+} from "./shared"
+export { type StreamingTextProps, type StreamingToken } from "./streaming-text"
+export type { ResearchAnswerProps } from "./research-answer"
+export type {
+  AISuggestionBase,
+  DiffRow,
+  ReferenceBase,
+  SuggestionState,
+} from "./types"
+
+const AI = {
+  Message,
+  Avatar,
+  StreamingText,
+  SuggestedPrompt,
+  ResearchAnswer,
+}
+
+export default AI

package/src/components/composed/ai/message.tsx

@@ -0,0 +1,49 @@
+import type { AIContentProps, AIMessageProps, AIMessageType } from "./types"
+import { Bubble } from "@/components/atoms"
+import { cn } from "@/lib/utils"
+import { Avatar } from "./avatar"
+
+/**
+ * An agent turn: author row, prose body and — when the model proposed
+ * changes — a "Suggestions" disclosure that fans the cards out below with a
+ * staggered spring.
+ */
+export function Message<T extends AIMessageType>({
+  children,
+  isStreaming = false,
+  className,
+  AttachedContent,
+  type,
+  contentProps,
+  ...props
+}: AIMessageProps<T>): React.ReactElement {
+  // TS can't relate `AIContentProps<T>` to JSX's IntrinsicAttributes while `T`
+  // is unresolved; widen to the full union for the render site only.
+  const Content = AttachedContent as
+    React.ComponentType<AIContentProps> | undefined
+
+  return (
+    <Bubble
+      className={cn(className)}
+      data-slot="ai-message"
+      data-streaming={isStreaming ? "" : undefined}
+      variant="ai"
+      {...props}
+    >
+      <Bubble.Header>
+        <Avatar />
+      </Bubble.Header>
+
+      <Bubble.Message
+        aria-atomic="false"
+        aria-live="polite"
+        data-slot="ai-message-body"
+      >
+        {children}
+        {Content && (
+          <Content {...({ kind: type, ...contentProps } as AIContentProps)} />
+        )}
+      </Bubble.Message>
+    </Bubble>
+  )
+}

package/src/components/composed/ai/research-answer.tsx

@@ -0,0 +1,157 @@
+"use client"
+
+import { BookOpen, Calendar, Copy, ListPlus, Share2, Users } from "lucide-react"
+import type * as React from "react"
+import { cn } from "@/lib/utils"
+import {
+  Card,
+  CardFrame,
+  CardFrameFooter,
+  CardFrameHeader,
+  CardPanel,
+} from "@/components/ui/card"
+import { Button } from "@/components/ui/button"
+import { IconTile, InlineSource } from "@/components/ui/chat"
+
+export interface ResearchReference {
+  /** Pill label, e.g. "Iliad · Homer corpus". */
+  label: React.ReactNode
+  /** Preview-card content shown on hover. */
+  favicon?: string
+  title?: React.ReactNode
+  description?: React.ReactNode
+  href?: string
+}
+
+export interface ResearchAnswerProps extends Omit<
+  React.ComponentPropsWithoutRef<"div">,
+  "content"
+> {
+  kicker?: React.ReactNode
+  /** "Answered from 3 passages · 0.8 s" */
+  kickerSub?: React.ReactNode
+  content: React.ReactNode
+  source?: React.ReactNode | ResearchReference
+  date?: React.ReactNode
+  authors?: React.ReactNode | ResearchReference
+  onCopyCitation?: () => void
+  onShare?: () => void
+  /** TODO(spec 003): the design shows the control only; behaviour is the caller's. */
+  onAddToList?: () => void
+  bare?: boolean
+}
+
+const GHOST =
+  "h-6 gap-1.5 rounded-md px-2 text-[11.5px] font-medium text-text-secondary hover:bg-surface-subtle hover:text-text-primary sm:h-6 [&_svg]:size-3.5! [&_svg]:opacity-100"
+
+/**
+ * Research answer card: kicker, content, Source / Date / Author(s) meta, actions.
+ *
+ * @sketch "Component / Research Answer"
+ */
+export function ResearchAnswer({
+  kicker = "Research answer",
+  kickerSub,
+  content,
+  source,
+  date,
+  authors,
+  onCopyCitation,
+  onShare,
+  onAddToList,
+  bare = false,
+  className,
+  ...props
+}: ResearchAnswerProps): React.ReactElement {
+  // A structured value renders as a reference pill with a hover preview;
+  // plain strings stay plain text.
+  const asPill = (
+    value: React.ReactNode | ResearchReference
+  ): React.ReactNode => {
+    if (value && typeof value === "object" && "label" in value) {
+      const { label, ...preview } = value as ResearchReference
+      return <InlineSource domain={label} {...preview} />
+    }
+    return value
+  }
+  const meta = [
+    { icon: <BookOpen />, label: "Source", value: source },
+    { icon: <Calendar />, label: "Date", value: date },
+    { icon: <Users />, label: "Author(s)", value: authors },
+  ].filter((m) => m.value !== undefined)
+
+  return (
+    <CardFrame
+      data-slot="research-answer"
+      className={cn(
+        "w-[380px] max-w-full [--frame-radius:var(--radius-md)]",
+        bare && "border-transparent shadow-none",
+        className
+      )}
+      {...props}
+    >
+      <CardFrameHeader className="flex flex-row items-start gap-2 px-3.5 py-3">
+        <IconTile size={28}>
+          <BookOpen />
+        </IconTile>
+        <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+          <span className="text-[13px] leading-4 font-semibold text-text-primary">
+            {kicker}
+          </span>
+          {kickerSub ? (
+            <span className="text-[11px] leading-3 text-text-secondary">
+              {kickerSub}
+            </span>
+          ) : null}
+        </div>
+      </CardFrameHeader>
+      <Card>
+        <CardPanel className="px-3.5 py-3.5 text-[13px] leading-[18px] text-text-primary">
+          {content}
+        </CardPanel>
+        {meta.length ? (
+          <>
+            <div className="mx-3.5 h-px bg-border-default" />
+            <dl className="flex flex-col gap-1.5 px-3.5 py-3">
+              {meta.map((m) => (
+                <div key={m.label} className="flex items-baseline gap-3">
+                  <dt className="flex w-20 shrink-0 items-center gap-1 text-[11px] leading-4 text-text-secondary [&_svg]:size-3 [&_svg]:self-center [&_svg]:text-icon">
+                    {m.icon}
+                    {m.label}
+                  </dt>
+                  <dd className="min-w-0 flex-1 text-[12px] leading-4 text-text-primary">
+                    {asPill(m.value)}
+                  </dd>
+                </div>
+              ))}
+            </dl>
+          </>
+        ) : null}
+      </Card>
+      <CardFrameFooter className="flex items-center gap-0.5 p-2">
+        <Button
+          variant="ghost"
+          size="xs"
+          className={GHOST}
+          onClick={onCopyCitation}
+        >
+          <Copy />
+          Copy
+        </Button>
+        <Button variant="ghost" size="xs" className={GHOST} onClick={onShare}>
+          <Share2 />
+          Share
+        </Button>
+        <Button
+          variant="ghost"
+          size="xs"
+          className={GHOST}
+          onClick={onAddToList}
+        >
+          <ListPlus />
+          Add to list
+        </Button>
+      </CardFrameFooter>
+    </CardFrame>
+  )
+}

package/src/components/composed/ai/shared.tsx

@@ -0,0 +1,94 @@
+import { Children, Fragment, isValidElement } from "react"
+import type * as React from "react"
+import { cn } from "@/lib/utils"
+import { EASE_IN_OUT, SPRING_PANEL } from "@/lib/ease"
+import type { Variants } from "motion"
+
+// The AI accent is a muted amber used sparingly — the ✦ icon, small labels
+// and the primary Apply action. Everything else reads from theme tokens so
+// these components inherit whatever surface hosts them (e.g. the shell
+// right panel).
+export const accentText = "text-amber-600 dark:text-amber-300/90"
+
+export const accentRing = "ring-offset-0 focus-visible:ring-amber-400/40"
+
+export const accentSolid = cn(
+  "border-amber-500/60 bg-amber-400/90 text-amber-950 shadow-none hover:bg-amber-400 disabled:opacity-35 data-pressed:bg-amber-400 *:data-[slot=button-loading-indicator]:text-amber-950",
+  accentRing
+)
+
+// The agent's own voice is violet: its badge, the suggestions disclosure and
+// the accepted mark on a suggestion card.
+export const agentText = "text-violet-600 dark:text-violet-400"
+
+export const ghostMuted = cn(
+  "text-muted-foreground hover:text-foreground",
+  accentRing
+)
+
+export const mutedText = "text-[13px] leading-5 text-muted-foreground"
+
+// Floating surfaces (scope picker list, selection popover) — theme tokens,
+// not a hard-coded dark panel.
+export const surface = "border bg-popover text-popover-foreground shadow-lg"
+
+/** The AI spark — the accent-coloured ✦ that marks every AI affordance. */
+export function AiIcon({
+  className,
+}: {
+  className?: string
+}): React.ReactElement {
+  return (
+    <span aria-hidden="true" className={cn(accentText, className)}>
+      ✦
+    </span>
+  )
+}
+
+export function CloseIcon(): React.ReactElement {
+  return (
+    <svg
+      aria-hidden="true"
+      className="size-4"
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
+      <path d="m6 6 12 12M18 6 6 18" />
+    </svg>
+  )
+}
+
+// Frosted card used by suggestion cards: a translucent field with a lit top
+// edge and a light backdrop blur so the thread reads through it.
+export const glassCard =
+  "rounded-md border-0 border-t-2 border-t-white/70 bg-neutral-200/45 shadow-none backdrop-blur-[3px] backdrop-saturate-125 before:hidden dark:border-t-neutral-700 dark:bg-neutral-800/50"
+
+// The suggestions fan-out: the list holds the stagger, each item springs up
+// into place. Shared by `AiMessage`'s disclosure and `SuggestedPrompts`, so
+// both fan out with the same rhythm.
+export const LIST_VARIANTS: Variants = {
+  hidden: { transition: { staggerChildren: 0.04, staggerDirection: -1 } },
+  visible: { transition: { staggerChildren: 0.07, delayChildren: 0.05 } },
+}
+
+export const ITEM_VARIANTS: Variants = {
+  hidden: {
+    opacity: 0,
+    y: 14,
+    scale: 0.97,
+    transition: { duration: 0.18, ease: EASE_IN_OUT },
+  },
+  visible: { opacity: 1, y: 0, scale: 1, transition: SPRING_PANEL },
+}
+
+/** Children.toArray, but looking through fragments so `<>{a}{b}</>` counts two. */
+export function flattenChildren(children: React.ReactNode): React.ReactNode[] {
+  return Children.toArray(children).flatMap((child) =>
+    isValidElement<{ children?: React.ReactNode }>(child) &&
+    child.type === Fragment
+      ? flattenChildren(child.props.children)
+      : [child]
+  )
+}