@adres/mgda-ui 0.0.0-stage → 0.0.2

package/src/components/citations.tsx

@@ -0,0 +1,220 @@
+"use client"
+
+import * as React from "react"
+import { ExternalLink, FileText, TriangleAlert } from "lucide-react"
+import { cn } from "../lib/cn"
+import { Avatar, AvatarFallback } from "./avatar"
+import { Badge } from "./badge"
+import { Button } from "./button"
+import { Popover, PopoverContent, PopoverTrigger } from "./popover"
+import { Text } from "./text"
+import { TextLink } from "./text-link"
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip"
+
+/** What kind of source it is, e.g. `{ label: "Listing", icon: Home }`. */
+export interface CitationSourceKind {
+  label: string
+  icon: React.ElementType
+}
+
+export interface CitationSource {
+  /** The number shown in markers and the list. */
+  id: number
+  title: string
+  publisher: string
+  /** ISO date (YYYY-MM-DD) the source was published or last updated. */
+  date: string
+  url: string
+  /** The passage the answer relied on. */
+  excerpt: string
+  kind?: CitationSourceKind
+}
+
+const DAY_MS = 86_400_000
+const dateFormat = new Intl.DateTimeFormat("en-GB", { day: "numeric", month: "short", year: "numeric", timeZone: "UTC" })
+
+/** "6 Oct 2026", always in UTC so server and client render the same. */
+export const formatSourceDate = (iso: string) => dateFormat.format(new Date(`${iso}T00:00:00Z`))
+
+/** True when `date` is more than `days` before `asOf` (both ISO dates). */
+export const isStale = (date: string, asOf: string, days = 183) => (Date.parse(asOf) - Date.parse(date)) / DAY_MS > days
+
+export interface SourceAvatarProps {
+  kind?: CitationSourceKind
+  size?: "xs" | "sm"
+}
+
+/** The source kind's icon in a small muted avatar; stacks in an `AvatarStack`. */
+export function SourceAvatar({ kind, size = "sm" }: SourceAvatarProps) {
+  const Icon = kind?.icon ?? FileText
+  return (
+    <Avatar size={size}>
+      <AvatarFallback className="ax:bg-muted ax:text-muted-foreground">
+        <Icon className={size === "xs" ? "ax:size-3" : "ax:size-4"} aria-hidden />
+      </AvatarFallback>
+    </Avatar>
+  )
+}
+
+export interface CitationMarkerProps {
+  source: CitationSource
+  /** Adds "Show in sources" to the preview, e.g. to scroll to and highlight the source in a list. */
+  onShow?: (id: number) => void
+}
+
+const PILL = "ax:inline-flex ax:h-5 ax:items-center ax:gap-1 ax:rounded-full ax:bg-muted ax:px-1.5 ax:text-xs ax:tabular-nums ax:text-muted-foreground"
+
+/** A small numbered pill in running text; opens a preview of the source and the passage used. */
+export function CitationMarker({ source, onShow }: CitationMarkerProps) {
+  const Icon = source.kind?.icon
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          aria-label={`Source ${source.id}: ${source.title}`}
+          className={cn(
+            PILL,
+            "ax:mx-0.5 ax:align-text-top ax:transition-colors ax:hover:bg-muted-foreground/20 ax:hover:text-foreground",
+            "ax:focus-visible:outline-none ax:focus-visible:ring-2 ax:focus-visible:ring-ring",
+          )}
+        >
+          {Icon && <Icon className="ax:size-3" aria-hidden />}
+          {source.id}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent align="start" className="ax:w-80 ax:p-0 ax:shadow-xs">
+        <div className="ax:flex ax:flex-col ax:gap-xs ax:p-sm">
+          <div className="ax:flex ax:items-center ax:gap-1.5">
+            <SourceAvatar kind={source.kind} size="xs" />
+            <Text size="1" color="muted" truncate>{source.publisher} · {formatSourceDate(source.date)}</Text>
+          </div>
+          <Text as="p" size="2" weight="medium" className="ax:line-clamp-2">{source.title}</Text>
+          <Text as="p" size="2" color="muted" className="ax:line-clamp-3">{source.excerpt}</Text>
+        </div>
+        <div className="ax:flex ax:items-center ax:justify-between ax:gap-sm ax:border-t ax:border-border ax:px-sm ax:py-xs">
+          {onShow ? (
+            <TextLink asChild size="1">
+              <button type="button" onClick={() => onShow(source.id)}>Show in sources</button>
+            </TextLink>
+          ) : <span />}
+          <TextLink href={source.url} size="1" className="ax:inline-flex ax:items-center ax:gap-1">
+            Open <ExternalLink className="ax:size-3" aria-hidden />
+          </TextLink>
+        </div>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+export interface UnsupportedClaimProps {
+  children: React.ReactNode
+  /** Tooltip explaining the mark. */
+  note?: string
+}
+
+/**
+ * A claim no source backs: the text gets a dashed warning underline and a
+ * warning icon. The icon is a real button so keyboard users reach the note.
+ */
+export function UnsupportedClaim({ children, note = "Not backed by a source. Treat this as the assistant's estimate." }: UnsupportedClaimProps) {
+  return (
+    <>
+      <span className="ax:underline ax:decoration-warning ax:decoration-dashed ax:underline-offset-4">{children}</span>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <TextLink asChild underline="none" color="default" className="ax:ms-1 ax:align-text-top">
+            <button type="button" aria-label="Not backed by a source">
+              <TriangleAlert className="ax:size-3.5 ax:text-warning-foreground" aria-hidden />
+            </button>
+          </TextLink>
+        </TooltipTrigger>
+        <TooltipContent>{note}</TooltipContent>
+      </Tooltip>
+    </>
+  )
+}
+
+export interface SourceCardProps extends React.HTMLAttributes<HTMLDivElement> {
+  source: CitationSource
+  /** ISO "today" for the age check. Without it, no stale badge. Pass a fixed date to render the same on server and client. */
+  asOf?: string
+  /** Days after which the source is marked old. */
+  staleAfterDays?: number
+  staleLabel?: string
+  /** Rings the card, e.g. after "Show in sources". */
+  highlighted?: boolean
+}
+
+/** One numbered source: linked title, publisher, kind and date, an age warning, and the passage used. */
+export const SourceCard = React.forwardRef<HTMLDivElement, SourceCardProps>(
+  ({ source, asOf, staleAfterDays = 183, staleLabel = "Older than 6 months", highlighted, className, ...props }, ref) => {
+    const stale = asOf !== undefined && isStale(source.date, asOf, staleAfterDays)
+    return (
+      <div
+        ref={ref}
+        data-slot="source-card"
+        tabIndex={-1}
+        className={cn(
+          "ax:flex ax:items-start ax:gap-sm ax:rounded-md ax:border ax:border-border ax:bg-card ax:p-sm ax:transition-shadow ax:outline-none",
+          highlighted && "ax:ring-2 ax:ring-ring",
+          className,
+        )}
+        {...props}
+      >
+        <span className={cn(PILL, "ax:mt-0.5 ax:shrink-0")}><span className="ax:sr-only">Source </span>{source.id}</span>
+        <div className="ax:flex ax:min-w-0 ax:flex-1 ax:flex-col ax:gap-1">
+          <TextLink href={source.url} color="default" size="2" className="ax:inline-flex ax:items-center ax:gap-1">
+            <span className="ax:truncate">{source.title}</span>
+            <ExternalLink className="ax:size-3 ax:shrink-0" aria-hidden />
+          </TextLink>
+          <div className="ax:flex ax:flex-wrap ax:items-center ax:gap-x-sm ax:gap-y-1">
+            <Text size="1" color="muted">{source.publisher}</Text>
+            {source.kind && <Text size="1" color="muted">{source.kind.label}</Text>}
+            <Text size="1" color="muted">{formatSourceDate(source.date)}</Text>
+            {stale && <Badge variant="warning" size="sm">{staleLabel}</Badge>}
+          </div>
+          {/* The rule hangs in the gutter (-ms = border + ps) so the quote's text lines up with the title. */}
+          <Text as="p" size="2" color="muted" className="ax:mt-xs ax:-ms-2 ax:border-s-2 ax:border-muted ax:ps-1.5">{source.excerpt}</Text>
+        </div>
+      </div>
+    )
+  },
+)
+SourceCard.displayName = "SourceCard"
+
+export interface SourceListProps extends React.HTMLAttributes<HTMLDivElement> {
+  sources: CitationSource[]
+  asOf?: string
+  /** DOM id for each card, so a marker's "Show in sources" can scroll to and focus it. */
+  getSourceId?: (id: number) => string
+  /** The source id to ring. */
+  highlighted?: number | null
+  /** How many show before "Show N more". Defaults to all. */
+  initial?: number
+  onExpand?: () => void
+}
+
+/** Numbered sources; beyond `initial` they collapse behind "Show N more". */
+export const SourceList = React.forwardRef<HTMLDivElement, SourceListProps>(
+  ({ sources, asOf, getSourceId, highlighted, initial = sources.length, onExpand, className, ...props }, ref) => {
+    const hidden = sources.length - initial
+    return (
+      <div ref={ref} data-slot="source-list" className={cn("ax:flex ax:flex-col ax:gap-sm", className)} {...props}>
+        <ol className="ax:flex ax:flex-col ax:gap-sm" aria-label="Sources">
+          {sources.slice(0, initial).map((source) => (
+            <li key={source.id}>
+              <SourceCard source={source} asOf={asOf} id={getSourceId?.(source.id)} highlighted={highlighted === source.id} />
+            </li>
+          ))}
+        </ol>
+        {hidden > 0 && onExpand && (
+          <Button variant="ghost" size="sm" className="ax:self-start ax:rounded-full" onClick={onExpand}>
+            Show {hidden} more {hidden === 1 ? "source" : "sources"}
+          </Button>
+        )}
+      </div>
+    )
+  },
+)
+SourceList.displayName = "SourceList"

package/src/components/combobox.stories.tsx

@@ -0,0 +1,184 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { expect, userEvent, waitFor, within } from "@storybook/test"
+import { Clock, Home, MapPin } from "lucide-react"
+import { Combobox, type ComboboxItem } from "./combobox"
+import { Label } from "./input"
+
+const COMMUNITIES: ComboboxItem[] = [
+  { value: "al-maryah", label: "Al Maryah Island" },
+  { value: "al-reem", label: "Al Reem Island" },
+  { value: "saadiyat", label: "Al Saadiyat Island", keywords: "Saadiyat" },
+  { value: "khalifa-city", label: "Khalifa City" },
+  { value: "yas", label: "Yas Island" },
+  { value: "jubail", label: "Jubail Island", disabled: true, description: "Coming soon" },
+]
+
+const EVERYTHING: ComboboxItem[] = [
+  { value: "p-1316", label: "Saadiyat Lagoons, Apt 1316", group: "Properties", description: "AED 4,162,000", keywords: "Al Saadiyat Island", icon: <Home aria-hidden /> },
+  { value: "p-910", label: "Soho Square, Apt 910", group: "Properties", description: "AED 5,793,000", keywords: "Al Saadiyat Island", icon: <Home aria-hidden /> },
+  { value: "p-218", label: "Yas Acres, Townhouse 218", group: "Properties", description: "AED 4,478,000", keywords: "Yas Island", icon: <Home aria-hidden /> },
+  { value: "c-saadiyat", label: "Al Saadiyat Island", group: "Communities", description: "2 listings", icon: <MapPin aria-hidden /> },
+  { value: "c-yas", label: "Yas Island", group: "Communities", description: "1 listing", icon: <MapPin aria-hidden /> },
+]
+
+const meta: Meta<typeof Combobox> = {
+  title: "Components/Combobox",
+  component: Combobox,
+  tags: ["autodocs"],
+  args: { items: COMMUNITIES, placeholder: "Choose a community", "aria-label": "Community" },
+  decorators: [(Story) => <div style={{ maxWidth: 420, minHeight: 360 }}><Story /></div>],
+}
+
+export default meta
+type Story = StoryObj<typeof Combobox>
+
+/** Picker: the chosen label stays in the input. */
+export const Default: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState<string | null>(null)
+    return <Combobox {...args} value={value} onValueChange={setValue} />
+  },
+}
+
+export const WithLabel: Story = {
+  render: (args) => {
+    const [value, setValue] = React.useState<string | null>("yas")
+    return (
+      <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+        <Label htmlFor="community">Community</Label>
+        <Combobox {...args} id="community" aria-label={undefined} value={value} onValueChange={setValue} />
+      </div>
+    )
+  },
+}
+
+/** Search launcher: grouped results, recent searches while empty, the input clears after a pick. */
+export const SearchLauncher: Story = {
+  args: { items: EVERYTHING, placeholder: "Search properties or communities", "aria-label": "Search", size: "lg", maxPerGroup: 4 },
+  render: (args) => {
+    const [query, setQuery] = React.useState("")
+    const [last, setLast] = React.useState<string>()
+    return (
+      <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+        <Combobox
+          {...args}
+          query={query}
+          onQueryChange={setQuery}
+          onSelect={(item) => setLast(item.label)}
+          startContent={
+            <div style={{ display: "flex", flexDirection: "column", gap: 4, padding: 8 }}>
+              {["Saadiyat", "Yas"].map((term) => (
+                <button key={term} type="button" onClick={() => setQuery(term)} style={{ display: "flex", gap: 6, alignItems: "center" }}>
+                  <Clock size={14} aria-hidden /> {term}
+                </button>
+              ))}
+            </div>
+          }
+        />
+        <span data-testid="last-pick">{last ? `Opened ${last}` : ""}</span>
+      </div>
+    )
+  },
+}
+
+export const Loading: Story = {
+  args: { loading: true, query: "yas", loadingMessage: "Searching communities" },
+}
+
+export const Invalid: Story = {
+  args: { invalid: true },
+}
+
+/** Interaction test: type, move with the keyboard, pick with Enter. */
+export const KeyboardSelection: Story = {
+  ...Default,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const page = within(canvasElement.ownerDocument.body)
+    const input = canvas.getByRole("combobox", { name: "Community" })
+
+    await userEvent.click(input)
+    await userEvent.type(input, "island")
+    await waitFor(() => expect(page.getByRole("listbox")).toBeVisible())
+    await expect(input).toHaveAttribute("aria-expanded", "true")
+
+    // First match is highlighted; ArrowDown moves on; the disabled Jubail row is skipped.
+    await userEvent.keyboard("{ArrowDown}")
+    const activeId = input.getAttribute("aria-activedescendant")
+    await expect(canvasElement.ownerDocument.getElementById(activeId ?? "")).toHaveTextContent("Al Reem Island")
+
+    await userEvent.keyboard("{Enter}")
+    await expect(input).toHaveValue("Al Reem Island")
+    await expect(input).toHaveAttribute("aria-expanded", "false")
+
+    await userEvent.keyboard("{ArrowDown}")
+    await waitFor(() => expect(page.getByRole("listbox")).toBeVisible())
+    await userEvent.keyboard("{Escape}")
+    await expect(input).toHaveAttribute("aria-expanded", "false")
+    await expect(input).toHaveValue("Al Reem Island")
+  },
+}
+
+/** Interaction test: grouped results by mouse, then the input clears for the next search. */
+export const SearchSelection: Story = {
+  ...SearchLauncher,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const page = within(canvasElement.ownerDocument.body)
+    const input = canvas.getByRole("combobox", { name: "Search" })
+
+    await userEvent.type(input, "saadiyat")
+    await waitFor(() => expect(page.getAllByRole("group")).toHaveLength(2))
+    await expect(page.getAllByRole("option")).toHaveLength(3)
+
+    await userEvent.click(page.getByRole("option", { name: /Soho Square/ }))
+    await expect(canvas.getByTestId("last-pick")).toHaveTextContent("Opened Soho Square, Apt 910")
+    await expect(input).toHaveValue("")
+  },
+}
+
+const DEVELOPERS = ["Aldar Properties", "Bloom Holding", "Imkan", "Modon", "Reportage"]
+
+/** Remote picker: results arrive after a delay; the picked label survives the list emptying. */
+export const RemoteResults: Story = {
+  args: { "aria-label": "Developer", placeholder: "Search developers" },
+  render: (args) => {
+    const [query, setQuery] = React.useState("")
+    const [value, setValue] = React.useState<string | null>(null)
+    const [items, setItems] = React.useState<ComboboxItem[]>([])
+    const [loading, setLoading] = React.useState(false)
+    React.useEffect(() => {
+      const term = query.trim().toLowerCase()
+      if (!term) return setItems([])
+      setLoading(true)
+      const timer = setTimeout(() => {
+        setItems(DEVELOPERS.filter((name) => name.toLowerCase().includes(term)).map((name) => ({ value: name, label: name })))
+        setLoading(false)
+      }, 300)
+      return () => clearTimeout(timer)
+    }, [query])
+    return (
+      <Combobox
+        {...args}
+        items={items}
+        query={query}
+        onQueryChange={setQuery}
+        filter={() => true}
+        loading={loading}
+        value={value}
+        onValueChange={setValue}
+      />
+    )
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const page = within(canvasElement.ownerDocument.body)
+    const input = canvas.getByRole("combobox", { name: "Developer" })
+
+    await userEvent.type(input, "o")
+    await waitFor(() => expect(page.getAllByRole("option")).toHaveLength(4))
+    await userEvent.keyboard("{ArrowDown}{Enter}")
+    await expect(input).toHaveValue("Bloom Holding")
+  },
+}

package/src/components/combobox.test.tsx

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import {
+  Combobox, defaultComboboxFilter, groupComboboxItems, nextEnabledIndex, splitComboboxMatch,
+  type ComboboxItem,
+} from "./combobox"
+
+const ITEMS: ComboboxItem[] = [
+  { value: "yas", label: "Yas Island", group: "Communities", keywords: "Abu Dhabi" },
+  { value: "reem", label: "Al Reem Island", group: "Communities", disabled: true },
+  { value: "saadiyat", label: "Saadiyat Lagoons", group: "Projects", description: "AED 4.1M" },
+  { value: "soho", label: "Soho Square", group: "Projects" },
+]
+
+describe("defaultComboboxFilter", () => {
+  it("matches label, description and keywords without case", () => {
+    expect(defaultComboboxFilter(ITEMS[0]!, "ISLAND")).toBe(true)
+    expect(defaultComboboxFilter(ITEMS[0]!, "abu dhabi")).toBe(true)
+    expect(defaultComboboxFilter(ITEMS[2]!, "4.1m")).toBe(true)
+    expect(defaultComboboxFilter(ITEMS[3]!, "yas")).toBe(false)
+  })
+})
+
+describe("groupComboboxItems", () => {
+  it("keeps first-seen group order and caps each group", () => {
+    const groups = groupComboboxItems(ITEMS, 1)
+    expect(groups.map((group) => group.name)).toEqual(["Communities", "Projects"])
+    expect(groups.map((group) => group.items.map((item) => item.value))).toEqual([["yas"], ["saadiyat"]])
+  })
+
+  it("puts ungrouped items in one unnamed group", () => {
+    const groups = groupComboboxItems([{ value: "a", label: "A" }, { value: "b", label: "B" }])
+    expect(groups).toHaveLength(1)
+    expect(groups[0]?.name).toBeUndefined()
+  })
+})
+
+describe("splitComboboxMatch", () => {
+  it("splits around the first case-insensitive match, keeping the original casing", () => {
+    expect(splitComboboxMatch("Yas Island", "isl")).toEqual({ before: "Yas ", match: "Isl", after: "and" })
+  })
+
+  it("returns null without a match or query", () => {
+    expect(splitComboboxMatch("Yas Island", "reem")).toBeNull()
+    expect(splitComboboxMatch("Yas Island", "")).toBeNull()
+  })
+})
+
+describe("nextEnabledIndex", () => {
+  it("skips disabled items and wraps in both directions", () => {
+    expect(nextEnabledIndex(ITEMS, 0, 1)).toBe(2)
+    expect(nextEnabledIndex(ITEMS, 3, 1)).toBe(0)
+    expect(nextEnabledIndex(ITEMS, 0, -1)).toBe(3)
+    expect(nextEnabledIndex(ITEMS, -1, 1)).toBe(0)
+  })
+
+  it("returns -1 when every item is disabled", () => {
+    expect(nextEnabledIndex([{ value: "x", label: "X", disabled: true }], -1, 1)).toBe(-1)
+  })
+})
+
+describe("Combobox", () => {
+  it("renders a collapsed combobox input with an accessible name", () => {
+    const html = renderToStaticMarkup(<Combobox items={ITEMS} aria-label="Community" />)
+    expect(html).toContain('role="combobox"')
+    expect(html).toContain('aria-expanded="false"')
+    expect(html).toContain('aria-autocomplete="list"')
+    expect(html).toContain('aria-label="Community"')
+  })
+
+  it("leaves the name to a visible label when aria-label is not set", () => {
+    const html = renderToStaticMarkup(<Combobox items={ITEMS} id="community" />)
+    expect(html).toContain('id="community"')
+    expect(html).not.toContain("aria-label=")
+  })
+
+  it("shows the selected label in picker mode", () => {
+    const html = renderToStaticMarkup(<Combobox items={ITEMS} value="soho" onValueChange={() => {}} aria-label="Project" />)
+    expect(html).toContain('value="Soho Square"')
+  })
+})