@adres/mgda-ui 0.0.0-stage → 0.0.1

package/src/components/chain-of-thought.tsx

@@ -0,0 +1,170 @@
+"use client"
+
+import * as React from "react"
+import { ChevronDown } from "lucide-react"
+import { cn } from "../lib/cn"
+
+interface StepContextValue {
+  open: boolean
+  setOpen: (open: boolean) => void
+  contentId: string
+}
+
+const StepContext = React.createContext<StepContextValue | null>(null)
+
+function useStep(part: string) {
+  const context = React.useContext(StepContext)
+  if (!context) throw new Error(`${part} must be used inside ChainOfThoughtStep`)
+  return context
+}
+
+export type ChainOfThoughtProps = React.HTMLAttributes<HTMLDivElement>
+
+/**
+ * ChainOfThought - the reasoning behind an assistant answer as a vertical
+ * chain of steps. Each step is a one-line trigger that expands to its detail,
+ * and a thin rule joins one step to the next.
+ *
+ * @example
+ *   <ChainOfThought>
+ *     <ChainOfThoughtStep>
+ *       <ChainOfThoughtTrigger>Searching Yas Island listings</ChainOfThoughtTrigger>
+ *       <ChainOfThoughtContent>
+ *         <ChainOfThoughtItem>Found 42 townhouses under AED 5M</ChainOfThoughtItem>
+ *       </ChainOfThoughtContent>
+ *     </ChainOfThoughtStep>
+ *   </ChainOfThought>
+ */
+export const ChainOfThought = React.forwardRef<HTMLDivElement, ChainOfThoughtProps>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} data-slot="chain-of-thought" className={cn("ax:flex ax:flex-col", className)} {...props} />
+  ),
+)
+ChainOfThought.displayName = "ChainOfThought"
+
+export interface ChainOfThoughtStepProps extends React.HTMLAttributes<HTMLDivElement> {
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+}
+
+/** One step in the chain. Closed by default; control it with `open` and `onOpenChange`. */
+export const ChainOfThoughtStep = React.forwardRef<HTMLDivElement, ChainOfThoughtStepProps>(
+  ({ open: openProp, defaultOpen = false, onOpenChange, className, children, ...props }, ref) => {
+    const contentId = React.useId()
+    const [uncontrolled, setUncontrolled] = React.useState(defaultOpen)
+    const open = openProp ?? uncontrolled
+    const setOpen = React.useCallback(
+      (next: boolean) => {
+        if (openProp === undefined) setUncontrolled(next)
+        onOpenChange?.(next)
+      },
+      [openProp, onOpenChange],
+    )
+
+    return (
+      <StepContext.Provider value={{ open, setOpen, contentId }}>
+        <div
+          ref={ref}
+          data-slot="chain-of-thought-step"
+          data-state={open ? "open" : "closed"}
+          className={cn("ax:group/cot-step", className)}
+          {...props}
+        >
+          {children}
+          <div className="ax:flex ax:w-4 ax:justify-center ax:group-last/cot-step:hidden" aria-hidden>
+            <div className="ax:h-sm ax:w-px ax:bg-border" />
+          </div>
+        </div>
+      </StepContext.Provider>
+    )
+  },
+)
+ChainOfThoughtStep.displayName = "ChainOfThoughtStep"
+
+export interface ChainOfThoughtTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Replaces the default dot. Swaps to a chevron on hover and focus unless `swapIconOnHover` is false. */
+  icon?: React.ReactNode
+  swapIconOnHover?: boolean
+}
+
+/** The step's one-line label; toggles its content. */
+export const ChainOfThoughtTrigger = React.forwardRef<HTMLButtonElement, ChainOfThoughtTriggerProps>(
+  ({ icon, swapIconOnHover = true, className, children, onClick, ...props }, ref) => {
+    const { open, setOpen, contentId } = useStep("ChainOfThoughtTrigger")
+    const swap = Boolean(icon) && swapIconOnHover
+    const chevron = cn("ax:size-4 ax:transition-transform ax:motion-reduce:transition-none", open && "ax:rotate-180")
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-expanded={open}
+        aria-controls={contentId}
+        onClick={(event) => {
+          onClick?.(event)
+          if (!event.defaultPrevented) setOpen(!open)
+        }}
+        className={cn(
+          "ax:group/cot-trigger ax:flex ax:items-center ax:gap-sm ax:rounded-xs ax:text-start ax:t-body-sm ax:text-muted-foreground ax:transition-colors",
+          "ax:hover:text-foreground ax:focus-visible:outline-none ax:focus-visible:ring-2 ax:focus-visible:ring-ring",
+          className,
+        )}
+        {...props}
+      >
+        <span className="ax:relative ax:inline-flex ax:size-4 ax:shrink-0 ax:items-center ax:justify-center ax:[&_svg]:size-4" aria-hidden>
+          {icon ? (
+            <span className={cn("ax:inline-flex ax:transition-opacity", swap && "ax:group-hover/cot-trigger:opacity-0 ax:group-focus-visible/cot-trigger:opacity-0")}>
+              {icon}
+            </span>
+          ) : (
+            <span className="ax:size-2 ax:rounded-full ax:bg-current" />
+          )}
+          {swap && (
+            <ChevronDown
+              className={cn(chevron, "ax:absolute ax:opacity-0 ax:group-hover/cot-trigger:opacity-100 ax:group-focus-visible/cot-trigger:opacity-100")}
+            />
+          )}
+        </span>
+        <span className="ax:min-w-0">{children}</span>
+        {!swap && <ChevronDown className={cn(chevron, "ax:shrink-0")} aria-hidden />}
+      </button>
+    )
+  },
+)
+ChainOfThoughtTrigger.displayName = "ChainOfThoughtTrigger"
+
+export type ChainOfThoughtContentProps = React.HTMLAttributes<HTMLDivElement>
+
+/** The step's detail, beside a rule that carries on to the next step. Rendered only while open. */
+export const ChainOfThoughtContent = React.forwardRef<HTMLDivElement, ChainOfThoughtContentProps>(
+  ({ className, children, ...props }, ref) => {
+    const { open, contentId } = useStep("ChainOfThoughtContent")
+    if (!open) return null
+    return (
+      <div
+        ref={ref}
+        id={contentId}
+        data-slot="chain-of-thought-content"
+        className={cn("ax:grid ax:grid-cols-[1rem_minmax(0,1fr)] ax:gap-x-sm", className)}
+        {...props}
+      >
+        <div className="ax:flex ax:justify-center" aria-hidden>
+          <div className="ax:w-px ax:bg-border ax:group-last/cot-step:bg-transparent" />
+        </div>
+        <div className="ax:mt-sm ax:flex ax:min-w-0 ax:flex-col ax:gap-sm">{children}</div>
+      </div>
+    )
+  },
+)
+ChainOfThoughtContent.displayName = "ChainOfThoughtContent"
+
+export type ChainOfThoughtItemProps = React.HTMLAttributes<HTMLDivElement>
+
+/** One line of detail inside a step: a finding, a source, or a short note. */
+export const ChainOfThoughtItem = React.forwardRef<HTMLDivElement, ChainOfThoughtItemProps>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} data-slot="chain-of-thought-item" className={cn("ax:t-body-sm ax:text-muted-foreground", className)} {...props} />
+  ),
+)
+ChainOfThoughtItem.displayName = "ChainOfThoughtItem"

package/src/components/chat-container.stories.tsx

@@ -0,0 +1,47 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { ChatContainerContent, ChatContainerRoot, ChatScrollButton } from "./chat-container"
+import { ChatMessage } from "./chat-message"
+import { Button } from "./button"
+
+const meta: Meta<typeof ChatContainerRoot> = {
+  title: "Components/ChatContainer",
+  component: ChatContainerRoot,
+  tags: ["autodocs"],
+  decorators: [(Story) => <div style={{ maxWidth: 560 }}><Story /></div>],
+}
+
+export default meta
+type Story = StoryObj<typeof ChatContainerRoot>
+
+const TURNS = [
+  "Any townhouses on Yas Island under AED 5M?",
+  "Yes. 42 townhouses in Yas Acres and Noya are under AED 5M, and 11 have a private garden.",
+  "Which is cheapest?",
+  "The lowest asking price is AED 4.2M for a 3-bed in Yas Acres.",
+  "How does that compare with recent sales?",
+  "The median registered sale in Yas Acres over the last 12 months is AED 4.6M, so it is priced below recent sales.",
+]
+
+function Conversation() {
+  const [turns, setTurns] = React.useState(TURNS)
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <ChatContainerRoot className="ax:h-80 ax:rounded-md ax:border">
+        <ChatContainerContent className="ax:gap-lg ax:p-md">
+          {turns.map((text, index) => (
+            <ChatMessage key={index} from={index % 2 === 0 ? "user" : "assistant"}>{text}</ChatMessage>
+          ))}
+        </ChatContainerContent>
+        <ChatScrollButton className="ax:absolute ax:bottom-sm ax:left-1/2 ax:-translate-x-1/2" />
+      </ChatContainerRoot>
+      <div>
+        <Button variant="outline" size="sm" onClick={() => setTurns((prev) => [...prev, "Another reply from the assistant."])}>
+          Add reply
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+export const Default: Story = { render: () => <Conversation /> }

package/src/components/chat-container.test.tsx

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { ChatContainerContent, ChatContainerRoot, ChatScrollButton, useChatContainer } from "./chat-container"
+
+describe("ChatContainer", () => {
+  it("renders a focusable log named Conversation by default", () => {
+    const html = renderToStaticMarkup(
+      <ChatContainerRoot>
+        <ChatContainerContent>Hello</ChatContainerContent>
+      </ChatContainerRoot>,
+    )
+    expect(html).toContain('role="log"')
+    expect(html).toContain('aria-label="Conversation"')
+    expect(html).toContain('tabindex="0"')
+  })
+
+  it("lets the caller rename the log", () => {
+    const html = renderToStaticMarkup(
+      <ChatContainerRoot>
+        <ChatContainerContent aria-label="Chat with Adres">Hello</ChatContainerContent>
+      </ChatContainerRoot>,
+    )
+    expect(html).toContain('aria-label="Chat with Adres"')
+  })
+
+  it("starts at the bottom, so the scroll button is hidden and out of the tab order", () => {
+    const html = renderToStaticMarkup(
+      <ChatContainerRoot>
+        <ChatScrollButton />
+      </ChatContainerRoot>,
+    )
+    expect(html).toContain('aria-hidden="true"')
+    expect(html).toContain('tabindex="-1"')
+    expect(html).toContain('aria-label="Scroll to latest"')
+  })
+
+  it("exposes the scroll state through useChatContainer", () => {
+    function Probe() {
+      const { isAtBottom, hasUnseen } = useChatContainer()
+      return <span>{`${isAtBottom}-${hasUnseen}`}</span>
+    }
+    expect(renderToStaticMarkup(<ChatContainerRoot><Probe /></ChatContainerRoot>)).toContain("true-false")
+  })
+
+  it("throws when a part is used outside the root", () => {
+    expect(() => renderToStaticMarkup(<ChatScrollButton />)).toThrow(/ChatContainerRoot/)
+  })
+})

package/src/components/chat-container.tsx

@@ -0,0 +1,222 @@
+"use client"
+
+import * as React from "react"
+import { ArrowDown } from "lucide-react"
+import { cn } from "../lib/cn"
+import { Button, type ButtonProps } from "./button"
+
+/** How close to the bottom, in px, still counts as reading the latest. */
+const STICK_THRESHOLD = 48
+
+export interface ChatContainerState {
+  /** True while the log follows new content: the reader is at the bottom or jumped back to it. */
+  isAtBottom: boolean
+  /** True when content arrived while the reader was scrolled up. Clears at the bottom. */
+  hasUnseen: boolean
+  /** Scrolls to the latest and resumes following. Call it when the reader sends a message. */
+  scrollToBottom: (behavior?: ScrollBehavior) => void
+}
+
+interface ChatContainerContextValue extends ChatContainerState {
+  scrollRef: React.RefObject<HTMLDivElement | null>
+  onScroll: () => void
+}
+
+const ChatContainerContext = React.createContext<ChatContainerContextValue | null>(null)
+
+function useChatContainerContext(part: string) {
+  const context = React.useContext(ChatContainerContext)
+  if (!context) throw new Error(`${part} must be used inside ChatContainerRoot`)
+  return context
+}
+
+/** Scroll state for the nearest ChatContainerRoot, for custom controls and composers. */
+export function useChatContainer(): ChatContainerState {
+  const { isAtBottom, hasUnseen, scrollToBottom } = useChatContainerContext("useChatContainer")
+  return { isAtBottom, hasUnseen, scrollToBottom }
+}
+
+function distanceFromBottom(el: HTMLElement) {
+  return el.scrollHeight - el.scrollTop - el.clientHeight
+}
+
+export interface ChatContainerRootProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * ChatContainer - a conversation log that sticks to the latest message. It
+ * follows new and streaming content while the reader is at the bottom, stays
+ * put once they scroll up, and offers a button back down.
+ *
+ * @example
+ *   <ChatContainerRoot className="ax:h-[480px]">
+ *     <ChatContainerContent className="ax:gap-lg ax:p-md">{messages}</ChatContainerContent>
+ *     <ChatScrollButton className="ax:absolute ax:bottom-sm ax:left-1/2 ax:-translate-x-1/2" />
+ *   </ChatContainerRoot>
+ */
+export const ChatContainerRoot = React.forwardRef<HTMLDivElement, ChatContainerRootProps>(
+  ({ className, children, ...props }, ref) => {
+    const scrollRef = React.useRef<HTMLDivElement>(null)
+    const following = React.useRef(true)
+    const lastScrollTop = React.useRef(0)
+    const lastScrollHeight = React.useRef(0)
+    const [isAtBottom, setIsAtBottom] = React.useState(true)
+    const [hasUnseen, setHasUnseen] = React.useState(false)
+
+    const scrollToBottom = React.useCallback((behavior: ScrollBehavior = "smooth") => {
+      const el = scrollRef.current
+      if (!el) return
+      following.current = true
+      setIsAtBottom(true)
+      setHasUnseen(false)
+      el.scrollTo({ top: el.scrollHeight, behavior })
+    }, [])
+
+    // Only a scroll up stops following, so a smooth scroll down never flickers the button back.
+    const onScroll = React.useCallback(() => {
+      const el = scrollRef.current
+      if (!el) return
+      const near = distanceFromBottom(el) < STICK_THRESHOLD
+      if (near) {
+        following.current = true
+        setHasUnseen(false)
+      } else if (el.scrollTop < lastScrollTop.current) {
+        following.current = false
+      }
+      lastScrollTop.current = el.scrollTop
+      setIsAtBottom(following.current)
+    }, [])
+
+    React.useLayoutEffect(() => {
+      const el = scrollRef.current
+      if (!el) return
+      el.scrollTop = el.scrollHeight
+      lastScrollTop.current = el.scrollTop
+      lastScrollHeight.current = el.scrollHeight
+    }, [])
+
+    // Mutations catch new turns and streamed text; resizes catch the viewport changing.
+    React.useEffect(() => {
+      const el = scrollRef.current
+      if (!el) return
+      const update = () => {
+        const grew = el.scrollHeight > lastScrollHeight.current
+        lastScrollHeight.current = el.scrollHeight
+        if (following.current) {
+          el.scrollTop = el.scrollHeight
+          lastScrollTop.current = el.scrollTop
+        } else if (grew) {
+          setHasUnseen(true)
+        }
+      }
+      const mutations = new MutationObserver(update)
+      mutations.observe(el, { childList: true, subtree: true, characterData: true })
+      const resizes = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(update)
+      resizes?.observe(el)
+      return () => {
+        mutations.disconnect()
+        resizes?.disconnect()
+      }
+    }, [])
+
+    const value = React.useMemo(
+      () => ({ isAtBottom, hasUnseen, scrollToBottom, scrollRef, onScroll }),
+      [isAtBottom, hasUnseen, scrollToBottom, onScroll],
+    )
+
+    return (
+      <ChatContainerContext.Provider value={value}>
+        <div
+          ref={ref}
+          data-slot="chat-container"
+          className={cn("ax:relative ax:flex ax:min-h-0 ax:flex-col", className)}
+          {...props}
+        >
+          {children}
+        </div>
+      </ChatContainerContext.Provider>
+    )
+  },
+)
+ChatContainerRoot.displayName = "ChatContainerRoot"
+
+export interface ChatContainerContentProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+/** The scrolling log that holds the turns. Named "Conversation" unless you pass `aria-label`. */
+export const ChatContainerContent = React.forwardRef<HTMLDivElement, ChatContainerContentProps>(
+  ({ className, onScroll: onScrollProp, ...props }, ref) => {
+    const { scrollRef, onScroll } = useChatContainerContext("ChatContainerContent")
+    const setRefs = React.useCallback(
+      (node: HTMLDivElement | null) => {
+        scrollRef.current = node
+        if (typeof ref === "function") ref(node)
+        else if (ref) ref.current = node
+      },
+      [ref, scrollRef],
+    )
+
+    return (
+      <div
+        ref={setRefs}
+        data-slot="chat-container-content"
+        role="log"
+        aria-label="Conversation"
+        tabIndex={0}
+        onScroll={(event) => {
+          onScroll()
+          onScrollProp?.(event)
+        }}
+        className={cn(
+          "ax:flex ax:min-h-0 ax:flex-1 ax:flex-col ax:overflow-y-auto",
+          "ax:focus-visible:outline-none ax:focus-visible:ring-2 ax:focus-visible:ring-ring ax:focus-visible:ring-inset",
+          className,
+        )}
+        {...props}
+      />
+    )
+  },
+)
+ChatContainerContent.displayName = "ChatContainerContent"
+
+export interface ChatScrollButtonProps extends ButtonProps {}
+
+/**
+ * Jumps back to the latest. Shown only while the reader is scrolled up: an
+ * arrow on its own, or "New messages" once content arrives. Position it yourself.
+ */
+export const ChatScrollButton = React.forwardRef<HTMLButtonElement, ChatScrollButtonProps>(
+  ({ className, variant = "outline", size, children, onClick, ...props }, ref) => {
+    const { isAtBottom, hasUnseen, scrollToBottom } = useChatContainerContext("ChatScrollButton")
+    const label = hasUnseen ? "New messages" : null
+
+    return (
+      <Button
+        ref={ref}
+        type="button"
+        data-slot="chat-scroll-button"
+        variant={variant}
+        size={size ?? (children || label ? "sm" : "icon-sm")}
+        aria-label={children || label ? undefined : "Scroll to latest"}
+        aria-hidden={isAtBottom || undefined}
+        tabIndex={isAtBottom ? -1 : undefined}
+        onClick={(event) => {
+          onClick?.(event)
+          if (!event.defaultPrevented) scrollToBottom()
+        }}
+        className={cn(
+          "ax:rounded-full ax:bg-background ax:shadow-sm ax:transition-[opacity,translate] ax:duration-150 ax:motion-reduce:transition-none",
+          isAtBottom ? "ax:pointer-events-none ax:translate-y-sm ax:opacity-0" : "ax:opacity-100",
+          className,
+        )}
+        {...props}
+      >
+        {children ?? (
+          <>
+            <ArrowDown />
+            {label}
+          </>
+        )}
+      </Button>
+    )
+  },
+)
+ChatScrollButton.displayName = "ChatScrollButton"

package/src/components/chat-message.stories.tsx

@@ -0,0 +1,52 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { ChatAvatar, ChatDivider, ChatMessage } from "./chat-message"
+import { MessageActions } from "./message-actions"
+import { Text } from "./text"
+import { TooltipProvider } from "./tooltip"
+
+const QUESTION = "Any townhouses on Yas Island under AED 5M with a private garden?"
+const ANSWER = "Yes. Yas Acres has three-bed townhouses with private gardens from AED 4.2M, and two are listed this week."
+
+const meta: Meta<typeof ChatMessage> = {
+  title: "Components/ChatMessage",
+  component: ChatMessage,
+  tags: ["autodocs"],
+  decorators: [(Story) => <TooltipProvider><div style={{ maxWidth: 640 }}><Story /></div></TooltipProvider>],
+  argTypes: {
+    from: { control: "inline-radio", options: ["assistant", "user"] },
+    status: { control: "inline-radio", options: ["sent", "failed"] },
+    onRetry: { control: false },
+  },
+  args: { from: "assistant", children: ANSWER, meta: "10:42" },
+}
+
+export default meta
+type Story = StoryObj<typeof ChatMessage>
+
+export const Default: Story = {}
+
+export const Conversation: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1.5rem" }}>
+      <ChatDivider label="Today" />
+      <ChatMessage from="user" meta="Delivered · 10:41">{QUESTION}</ChatMessage>
+      <ChatMessage from="assistant" actions={<MessageActions copyText={ANSWER} onRegenerate={() => undefined} revealOnHover />} meta="10:42">
+        {ANSWER}
+      </ChatMessage>
+    </div>
+  ),
+}
+
+export const FailedUserMessage: Story = {
+  args: { from: "user", status: "failed", children: QUESTION, onRetry: () => undefined },
+}
+
+export const WithAvatar: Story = { args: { avatar: <ChatAvatar /> } }
+
+export const CustomContent: Story = {
+  args: {
+    children: <Text size="2" color="muted">Searched 3 sources, compared 12 listings</Text>,
+    meta: undefined,
+  },
+}

package/src/components/chat-message.test.tsx

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { ChatAvatar, ChatDivider, ChatMessage } from "./chat-message"
+
+describe("ChatMessage", () => {
+  it("names each turn by who wrote it", () => {
+    expect(renderToStaticMarkup(<ChatMessage from="assistant">Hi</ChatMessage>)).toContain('aria-label="Assistant message"')
+    expect(renderToStaticMarkup(<ChatMessage from="user">Hi</ChatMessage>)).toContain('aria-label="Your message"')
+  })
+
+  it("replaces the meta line with a retry action when a user message failed", () => {
+    const html = renderToStaticMarkup(
+      <ChatMessage from="user" status="failed" meta="Delivered · 10:41" onRetry={() => undefined}>Hi</ChatMessage>,
+    )
+    expect(html).toContain("Not delivered.")
+    expect(html).toMatch(/<button type="button"[^>]*>Retry<\/button>/)
+    expect(html).not.toContain("Delivered · 10:41")
+  })
+
+  it("shows no avatar on assistant turns unless one is passed", () => {
+    expect(renderToStaticMarkup(<ChatMessage from="assistant">Hi</ChatMessage>)).not.toContain("<svg")
+    expect(renderToStaticMarkup(<ChatMessage from="assistant" avatar={<ChatAvatar />}>Hi</ChatMessage>)).toContain("<svg")
+  })
+
+  it("puts assistant text on the page and user text in a bubble", () => {
+    expect(renderToStaticMarkup(<ChatMessage from="assistant">Hi</ChatMessage>)).not.toContain("ax:bg-muted")
+    expect(renderToStaticMarkup(<ChatMessage from="user">Hi</ChatMessage>)).toContain("ax:bg-muted")
+  })
+})
+
+describe("ChatDivider", () => {
+  it("is a labelled separator", () => {
+    expect(renderToStaticMarkup(<ChatDivider label="Today" />)).toMatch(/role="separator" aria-label="Today"/)
+  })
+})