@adres/mgda-ui 0.0.0-stage → 0.0.1

package/src/components/media-gallery.tsx

@@ -0,0 +1,347 @@
+"use client"
+
+import * as React from "react"
+import * as DialogPrimitive from "@radix-ui/react-dialog"
+import { ChevronLeft, ChevronRight, Images, Play, Rotate3d, X, ZoomIn, ZoomOut } from "lucide-react"
+
+import { Button } from "./button"
+import { cn } from "../lib/cn"
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type MediaKind = "image" | "video" | "walkthrough"
+
+/** A single item in a media gallery. Images render in an <img>; video and
+ *  walkthrough render in an HTML5 <video> (a walkthrough is a labelled video:
+ *  point `src` at a clip or a 360°/tour capture). */
+export interface MediaItem {
+  type: MediaKind
+  /** Image URL, or video file URL for video/walkthrough. */
+  src: string
+  /** Poster frame for video/walkthrough (an image URL). */
+  poster?: string
+  /** Short label shown on the tile + in the lightbox (e.g. "Walkthrough"). */
+  label?: string
+}
+
+const clamp = (n: number, min: number, max: number) => Math.min(max, Math.max(min, n))
+const MIN_ZOOM = 1
+const MAX_ZOOM = 5
+
+/** Poster/thumbnail source for any item - the image itself, or the video poster. */
+const tileSrc = (m: MediaItem) => (m.type === "image" ? m.src : (m.poster ?? ""))
+
+// ─── MediaGallery ───────────────────────────────────────────────────────────
+
+export interface MediaGalleryProps {
+  /** Ordered media. The first item is the hero; the rest fill the thumbnails. */
+  media: MediaItem[]
+  /** Used for alt text and the lightbox's accessible title. */
+  title?: string
+  /** Thumbnails shown beside the hero (defaults to 4). */
+  thumbnailCount?: number
+  className?: string
+}
+
+/**
+ * A responsive media gallery: a hero + thumbnail grid that opens a fullscreen
+ * lightbox with a keyboard-navigable slideshow, image zoom/pan, and inline
+ * video/walkthrough playback. Framework-agnostic. Pass any `MediaItem[]`.
+ *
+ * @example
+ *   <MediaGallery media={[{ type: "image", src: "/a.jpg" }, …]} title="Unit 2304" />
+ */
+export function MediaGallery({ media, title = "", thumbnailCount = 4, className }: MediaGalleryProps) {
+  const [openIndex, setOpenIndex] = React.useState<number | null>(null)
+
+  const hero = media[0]
+  if (!hero) return null
+
+  const thumbs = media.slice(1, 1 + thumbnailCount)
+  const hiddenCount = media.length - (1 + thumbs.length)
+  const walkthroughIndex = media.findIndex((m) => m.type === "walkthrough")
+
+  return (
+    <>
+      <div className={cn("ax:grid ax:gap-xs ax:sm:grid-cols-4 ax:sm:grid-rows-2", className)}>
+        {/* Hero */}
+        <div className="ax:group ax:relative ax:aspect-[3/2] ax:overflow-hidden ax:rounded-md ax:bg-muted ax:sm:col-span-2 ax:sm:row-span-2 ax:sm:aspect-auto">
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img
+            src={tileSrc(hero)}
+            alt={title}
+            className="ax:h-full ax:w-full ax:object-cover ax:transition-transform ax:duration-300 ax:group-hover:scale-[1.03]"
+          />
+          <button
+            type="button"
+            aria-label="Open gallery"
+            onClick={() => setOpenIndex(0)}
+            className="ax:absolute ax:inset-0 ax:z-0"
+          />
+          {walkthroughIndex >= 0 ? (
+            <Button
+              size="sm"
+              onClick={() => setOpenIndex(walkthroughIndex)}
+              className="ax:absolute ax:bottom-3 ax:left-3 ax:z-10 ax:bg-background/90 ax:text-foreground ax:backdrop-blur-sm ax:hover:bg-background"
+            >
+              <Rotate3d className="ax:size-4" /> Walkthrough
+            </Button>
+          ) : null}
+        </div>
+
+        {/* Thumbnails */}
+        {thumbs.map((m, i) => {
+          const mediaIndex = i + 1
+          const showMore = i === thumbs.length - 1 && hiddenCount > 0
+          return (
+            <button
+              key={mediaIndex}
+              type="button"
+              aria-label={showMore ? `View all ${media.length} items` : `Open item ${mediaIndex + 1}`}
+              onClick={() => setOpenIndex(mediaIndex)}
+              className="ax:group ax:relative ax:hidden ax:aspect-[3/2] ax:overflow-hidden ax:rounded-md ax:bg-muted ax:sm:block"
+            >
+              {/* eslint-disable-next-line @next/next/no-img-element */}
+              <img
+                src={tileSrc(m)}
+                alt={`${title} - ${mediaIndex + 1}`}
+                className="ax:h-full ax:w-full ax:object-cover ax:transition-transform ax:duration-300 ax:group-hover:scale-[1.03]"
+              />
+              {m.type !== "image" && !showMore ? (
+                <span className="ax:absolute ax:inset-0 ax:grid ax:place-items-center ax:bg-black/25">
+                  <span className="ax:grid ax:size-10 ax:place-items-center ax:rounded-full ax:bg-background/90">
+                    <Play className="ax:size-5 ax:fill-foreground ax:text-foreground" />
+                  </span>
+                </span>
+              ) : null}
+              {showMore ? (
+                <span className="ax:absolute ax:inset-0 ax:grid ax:place-items-center ax:bg-black/55 ax:text-white">
+                  <span className="ax:inline-flex ax:items-center ax:gap-1.5 ax:t-label-sm">
+                    <Images className="ax:size-4" /> +{hiddenCount} Photos
+                  </span>
+                </span>
+              ) : null}
+            </button>
+          )
+        })}
+      </div>
+
+      {openIndex !== null ? (
+        <Lightbox
+          media={media}
+          index={openIndex}
+          onIndexChange={setOpenIndex}
+          onClose={() => setOpenIndex(null)}
+          title={title}
+        />
+      ) : null}
+    </>
+  )
+}
+
+// ─── Lightbox ─────────────────────────────────────────────────────────────────
+
+export interface LightboxProps {
+  media: MediaItem[]
+  index: number
+  onIndexChange: (index: number) => void
+  onClose: () => void
+  title?: string
+}
+
+/**
+ * Fullscreen media viewer: keyboard-navigable slideshow (←/→, Esc), image
+ * zoom/pan, and inline playback for video/walkthroughs. Built on the Radix
+ * Dialog primitive (focus trap, scroll lock) with a dark immersive surface.
+ * Usually driven by `MediaGallery`, but exported for standalone use.
+ */
+export function Lightbox({ media, index, onIndexChange, onClose, title = "" }: LightboxProps) {
+  const count = media.length
+  const go = React.useCallback(
+    (delta: number) => onIndexChange((index + delta + count) % count),
+    [index, count, onIndexChange],
+  )
+  const current = media[index]
+
+  return (
+    <DialogPrimitive.Root open onOpenChange={(open) => !open && onClose()}>
+      <DialogPrimitive.Portal>
+        <DialogPrimitive.Overlay className="ax:fixed ax:inset-0 ax:z-[1200] ax:bg-black/90 ax:backdrop-blur-sm ax:data-[state=open]:animate-in ax:data-[state=open]:fade-in-0" />
+        <DialogPrimitive.Content
+          aria-describedby={undefined}
+          onKeyDown={(e) => {
+            if (e.key === "ArrowRight") go(1)
+            else if (e.key === "ArrowLeft") go(-1)
+          }}
+          className="ax:fixed ax:inset-0 ax:z-[1200] ax:flex ax:flex-col ax:text-white ax:outline-none ax:data-[state=open]:animate-in ax:data-[state=open]:fade-in-0"
+        >
+          <DialogPrimitive.Title className="ax:sr-only">{title || "Media gallery"}</DialogPrimitive.Title>
+
+          {/* Top bar */}
+          <div className="ax:flex ax:shrink-0 ax:items-center ax:justify-between ax:gap-md ax:px-md ax:py-sm">
+            <span className="ax:t-label-sm ax:text-white/80">
+              {index + 1} / {count}
+              {current?.label ? <span className="ax:ml-2 ax:text-white/60">· {current.label}</span> : null}
+            </span>
+            <DialogPrimitive.Close asChild>
+              <IconButton label="Close">
+                <X className="ax:size-5" />
+              </IconButton>
+            </DialogPrimitive.Close>
+          </div>
+
+          {/* Stage */}
+          <div className="ax:relative ax:flex ax:min-h-0 ax:flex-1 ax:items-center ax:justify-center">
+            {count > 1 ? (
+              <IconButton label="Previous" onClick={() => go(-1)} className="ax:absolute ax:left-md ax:top-1/2 ax:z-10 ax:-translate-y-1/2">
+                <ChevronLeft className="ax:size-6" />
+              </IconButton>
+            ) : null}
+
+            {current?.type === "image" ? (
+              <ZoomableImage key={index} src={current.src} alt={`${title} - ${index + 1} of ${count}`} />
+            ) : current ? (
+              <video
+                key={index}
+                src={current.src}
+                poster={current.poster}
+                controls
+                autoPlay
+                playsInline
+                className="ax:max-h-full ax:max-w-full"
+              />
+            ) : null}
+
+            {count > 1 ? (
+              <IconButton label="Next" onClick={() => go(1)} className="ax:absolute ax:right-md ax:top-1/2 ax:z-10 ax:-translate-y-1/2">
+                <ChevronRight className="ax:size-6" />
+              </IconButton>
+            ) : null}
+          </div>
+
+          {/* Thumbnail strip */}
+          <div className="ax:shrink-0 ax:overflow-x-auto ax:px-md ax:py-md">
+            <div className="ax:mx-auto ax:flex ax:w-max ax:gap-xs">
+              {media.map((m, i) => (
+                <button
+                  key={i}
+                  type="button"
+                  aria-label={`Go to item ${i + 1}`}
+                  aria-current={i === index}
+                  onClick={() => onIndexChange(i)}
+                  className={cn(
+                    "ax:relative ax:h-14 ax:w-20 ax:shrink-0 ax:overflow-hidden ax:rounded-sm ax:ring-offset-2 ax:ring-offset-black ax:transition",
+                    i === index ? "ax:ring-2 ax:ring-white" : "ax:opacity-60 ax:hover:opacity-100",
+                  )}
+                >
+                  {/* eslint-disable-next-line @next/next/no-img-element */}
+                  <img src={tileSrc(m)} alt="" className="ax:h-full ax:w-full ax:object-cover" draggable={false} />
+                  {m.type !== "image" ? (
+                    <span className="ax:absolute ax:inset-0 ax:grid ax:place-items-center ax:bg-black/30">
+                      <Play className="ax:size-4 ax:fill-white ax:text-white" />
+                    </span>
+                  ) : null}
+                </button>
+              ))}
+            </div>
+          </div>
+        </DialogPrimitive.Content>
+      </DialogPrimitive.Portal>
+    </DialogPrimitive.Root>
+  )
+}
+
+// ─── Zoomable image ─────────────────────────────────────────────────────────
+
+function ZoomableImage({ src, alt }: { src: string; alt: string }) {
+  const [scale, setScale] = React.useState(1)
+  const [pos, setPos] = React.useState({ x: 0, y: 0 })
+  const dragging = React.useRef(false)
+  const last = React.useRef({ x: 0, y: 0 })
+
+  const reset = () => {
+    setScale(1)
+    setPos({ x: 0, y: 0 })
+  }
+  // Panning offset is only meaningful while zoomed in.
+  React.useEffect(() => {
+    if (scale === 1) setPos({ x: 0, y: 0 })
+  }, [scale])
+
+  const zoomBy = (factor: number) => setScale((s) => clamp(+(s * factor).toFixed(3), MIN_ZOOM, MAX_ZOOM))
+
+  const onPointerDown = (e: React.PointerEvent<HTMLImageElement>) => {
+    if (scale <= 1) return
+    dragging.current = true
+    last.current = { x: e.clientX, y: e.clientY }
+    e.currentTarget.setPointerCapture(e.pointerId)
+  }
+  const onPointerMove = (e: React.PointerEvent<HTMLImageElement>) => {
+    if (!dragging.current) return
+    setPos((p) => ({ x: p.x + (e.clientX - last.current.x), y: p.y + (e.clientY - last.current.y) }))
+    last.current = { x: e.clientX, y: e.clientY }
+  }
+  const endDrag = () => {
+    dragging.current = false
+  }
+
+  return (
+    <div
+      className="ax:relative ax:flex ax:h-full ax:w-full ax:items-center ax:justify-center ax:overflow-hidden"
+      onWheel={(e) => zoomBy(e.deltaY < 0 ? 1.15 : 1 / 1.15)}
+    >
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img
+        src={src}
+        alt={alt}
+        draggable={false}
+        onDoubleClick={() => (scale > 1 ? reset() : setScale(2.5))}
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={endDrag}
+        onPointerCancel={endDrag}
+        className={cn(
+          "ax:max-h-full ax:max-w-full ax:select-none ax:object-contain",
+          !dragging.current && "ax:transition-transform",
+          scale > 1 ? "ax:cursor-grab ax:active:cursor-grabbing" : "ax:cursor-zoom-in",
+        )}
+        style={{ transform: `translate(${pos.x}px, ${pos.y}px) scale(${scale})` }}
+      />
+
+      <div className="ax:absolute ax:bottom-4 ax:right-4 ax:flex ax:gap-xs">
+        <IconButton label="Zoom out" onClick={() => zoomBy(1 / 1.3)} disabled={scale <= MIN_ZOOM}>
+          <ZoomOut className="ax:size-5" />
+        </IconButton>
+        <IconButton label="Zoom in" onClick={() => zoomBy(1.3)} disabled={scale >= MAX_ZOOM}>
+          <ZoomIn className="ax:size-5" />
+        </IconButton>
+      </div>
+    </div>
+  )
+}
+
+// ─── Dark-surface icon button ───────────────────────────────────────────────
+
+function IconButton({
+  label,
+  className,
+  children,
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement> & { label: string }) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      className={cn(
+        "ax:grid ax:size-10 ax:place-items-center ax:rounded-full ax:bg-white/10 ax:text-white ax:backdrop-blur-sm ax:transition",
+        "ax:hover:bg-white/20 ax:focus-visible:outline-none ax:focus-visible:ring-2 ax:focus-visible:ring-white",
+        "ax:disabled:pointer-events-none ax:disabled:opacity-40",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  )
+}

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

@@ -0,0 +1,45 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { MoreHorizontal } from "lucide-react"
+import { MessageAction, MessageActions, type MessageRating } from "./message-actions"
+import { TooltipProvider } from "./tooltip"
+
+const ANSWER = "Yas Acres townhouses with a private garden start at AED 4.2M."
+
+const meta: Meta<typeof MessageActions> = {
+  title: "Components/MessageActions",
+  component: MessageActions,
+  tags: ["autodocs"],
+  decorators: [(Story) => <TooltipProvider><Story /></TooltipProvider>],
+  argTypes: { onRate: { control: false }, onRegenerate: { control: false }, onCopy: { control: false } },
+  args: { copyText: ANSWER },
+}
+
+export default meta
+type Story = StoryObj<typeof MessageActions>
+
+function RatingDemo(props: React.ComponentProps<typeof MessageActions>) {
+  const [rating, setRating] = React.useState<MessageRating | null>(null)
+  return (
+    <MessageActions
+      {...props}
+      rating={rating}
+      onRate={(next) => setRating((current) => (current === next ? null : next))}
+      onRegenerate={() => undefined}
+    />
+  )
+}
+
+export const Default: Story = { render: (args) => <RatingDemo {...args} /> }
+
+export const CopyOnly: Story = {}
+
+export const Regenerating: Story = { render: (args) => <RatingDemo {...args} regenerating /> }
+
+export const WithExtraAction: Story = {
+  render: (args) => (
+    <RatingDemo {...args} role="toolbar" aria-label="Answer actions">
+      <MessageAction label="More actions"><MoreHorizontal /></MessageAction>
+    </RatingDemo>
+  ),
+}

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

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { MessageActions } from "./message-actions"
+import { TooltipProvider } from "./tooltip"
+
+const render = (node: React.ReactNode) => renderToStaticMarkup(<TooltipProvider>{node}</TooltipProvider>)
+
+describe("MessageActions", () => {
+  it("shows only the actions it has handlers or text for", () => {
+    const html = render(<MessageActions copyText="Answer" />)
+    expect(html).toContain('aria-label="Copy"')
+    expect(html).not.toContain("Good response")
+    expect(html).not.toContain("Regenerate")
+  })
+
+  it("marks the current rating as pressed and the other as not", () => {
+    const html = render(<MessageActions rating="up" onRate={() => undefined} />)
+    expect(html).toMatch(/aria-label="Good response" aria-pressed="true"/)
+    expect(html).toMatch(/aria-label="Bad response" aria-pressed="false"/)
+  })
+
+  it("disables Regenerate while regenerating", () => {
+    const html = render(<MessageActions onRegenerate={() => undefined} regenerating />)
+    expect(html).toMatch(/<button[^>]*disabled=""[^>]*aria-label="Regenerate"|<button[^>]*aria-label="Regenerate"[^>]*disabled=""/)
+  })
+
+  it("hides until hover or focus only when asked", () => {
+    expect(render(<MessageActions copyText="Answer" />)).not.toContain("ax:opacity-0")
+    expect(render(<MessageActions copyText="Answer" revealOnHover />)).toContain("ax:group-hover/message:opacity-100")
+  })
+})

package/src/components/message-actions.tsx

@@ -0,0 +1,119 @@
+"use client"
+
+import * as React from "react"
+import { Check, Copy, RotateCcw, ThumbsDown, ThumbsUp } from "lucide-react"
+import { cn } from "../lib/cn"
+import { Button, type ButtonProps } from "./button"
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip"
+
+export type MessageRating = "up" | "down"
+
+export interface MessageActionProps extends Omit<ButtonProps, "variant" | "size" | "asChild"> {
+  /** Accessible name and tooltip text. */
+  label: string
+  /** Renders as a toggle: sets `aria-pressed` and tints the icon. */
+  pressed?: boolean
+}
+
+/** A round icon-only ghost button with a tooltip, sized for the action row under a message. */
+export const MessageAction = React.forwardRef<HTMLButtonElement, MessageActionProps>(
+  ({ label, pressed, className, ...props }, ref) => (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button
+          ref={ref}
+          variant="ghost"
+          size="icon-sm"
+          aria-label={label}
+          aria-pressed={pressed}
+          className={cn("ax:rounded-full ax:text-muted-foreground ax:hover:text-foreground", pressed && "ax:text-primary-foreground", className)}
+          {...props}
+        />
+      </TooltipTrigger>
+      <TooltipContent>{label}</TooltipContent>
+    </Tooltip>
+  ),
+)
+MessageAction.displayName = "MessageAction"
+
+const COPIED_MS = 1500
+
+export interface MessageActionsProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Text the Copy action writes to the clipboard. Omit to hide Copy. */
+  copyText?: string
+  onCopy?: () => void
+  rating?: MessageRating | null
+  /** Called with the clicked rating; the caller decides whether a second click clears it. Omit to hide rating. */
+  onRate?: (rating: MessageRating) => void
+  /** Omit to hide Regenerate. */
+  onRegenerate?: () => void
+  /** Spins the Regenerate icon and disables it. */
+  regenerating?: boolean
+  regenerateDisabled?: boolean
+  /**
+   * Hides the row until the message is hovered or the row holds focus. Needs a
+   * `group/message` ancestor (ChatMessage sets one); touch screens always show it.
+   */
+  revealOnHover?: boolean
+}
+
+/**
+ * MessageActions - the row of icon actions under an assistant message: copy,
+ * rate up or down, and regenerate. Extra actions (a version pager, a More
+ * menu) go in `children`, after the built-in ones.
+ *
+ * @example
+ *   <MessageActions copyText={answer} rating={rating} onRate={setRating} onRegenerate={regenerate} />
+ */
+export const MessageActions = React.forwardRef<HTMLDivElement, MessageActionsProps>(
+  ({ copyText, onCopy, rating = null, onRate, onRegenerate, regenerating, regenerateDisabled, revealOnHover, className, children, ...props }, ref) => {
+    const [copied, setCopied] = React.useState(false)
+    const timer = React.useRef<number | undefined>(undefined)
+    React.useEffect(() => () => window.clearTimeout(timer.current), [])
+
+    function copy() {
+      if (copyText === undefined) return
+      void navigator.clipboard?.writeText(copyText)
+      setCopied(true)
+      window.clearTimeout(timer.current)
+      timer.current = window.setTimeout(() => setCopied(false), COPIED_MS)
+      onCopy?.()
+    }
+
+    return (
+      <div
+        ref={ref}
+        data-slot="message-actions"
+        className={cn(
+          "ax:-ms-xs ax:flex ax:flex-wrap ax:items-center",
+          revealOnHover && "ax:opacity-0 ax:transition-opacity ax:duration-150 ax:focus-within:opacity-100 ax:group-hover/message:opacity-100 ax:pointer-coarse:opacity-100 ax:motion-reduce:transition-none",
+          className,
+        )}
+        {...props}
+      >
+        {copyText !== undefined && (
+          <MessageAction label={copied ? "Copied" : "Copy"} onClick={copy}>
+            {copied ? <Check /> : <Copy />}
+          </MessageAction>
+        )}
+        {onRate && (
+          <>
+            <MessageAction label="Good response" pressed={rating === "up"} onClick={() => onRate("up")}>
+              <ThumbsUp className={cn(rating === "up" && "ax:fill-current")} />
+            </MessageAction>
+            <MessageAction label="Bad response" pressed={rating === "down"} onClick={() => onRate("down")}>
+              <ThumbsDown className={cn(rating === "down" && "ax:fill-current")} />
+            </MessageAction>
+          </>
+        )}
+        {onRegenerate && (
+          <MessageAction label="Regenerate" disabled={regenerating || regenerateDisabled} onClick={onRegenerate}>
+            <RotateCcw className={cn(regenerating && "ax:animate-spin ax:motion-reduce:animate-none")} />
+          </MessageAction>
+        )}
+        {children}
+      </div>
+    )
+  },
+)
+MessageActions.displayName = "MessageActions"

package/src/components/nav-sidebar.stories.tsx

@@ -0,0 +1,58 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Bookmark, FilePen, Home, Radio, Settings } from "lucide-react"
+import { NavSidebar } from "./nav-sidebar"
+
+const meta: Meta<typeof NavSidebar> = {
+  title: "Components/NavSidebar",
+  component: NavSidebar,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof NavSidebar>
+
+export const Default: Story = {
+  render: () => (
+    <div className="ax:h-[320px] ax:border ax:border-border ax:rounded-md ax:overflow-hidden">
+      <NavSidebar
+        currentPath="/"
+        brand={<span className="ax:t-label-sm ax:font-medium">Adres</span>}
+        sections={[
+          {
+            items: [
+              { label: "Home", href: "/", icon: <Home className="ax:size-4" /> },
+              { label: "Settings", href: "/settings", icon: <Settings className="ax:size-4" /> },
+            ],
+          },
+        ]}
+      />
+    </div>
+  ),
+}
+
+/** Sections with labels and trailing counts; a count of 0 is hidden. */
+export const WithCounts: Story = {
+  render: () => (
+    <div className="ax:h-[420px] ax:border ax:border-border ax:rounded-md ax:overflow-hidden">
+      <NavSidebar
+        currentPath="/saved-properties"
+        brand={<span className="ax:t-label-sm ax:font-medium">Adres</span>}
+        sections={[
+          { items: [{ label: "Dashboard", href: "/dashboard", icon: <Home className="ax:size-4" /> }] },
+          {
+            label: "Discover",
+            items: [{ label: "Saved Properties", href: "/saved-properties", icon: <Bookmark className="ax:size-4" />, count: 3 }],
+          },
+          {
+            label: "My Properties",
+            items: [
+              { label: "Drafts", href: "/my-properties/drafts", icon: <FilePen className="ax:size-4" />, count: 4 },
+              { label: "Live", href: "/my-properties/live", icon: <Radio className="ax:size-4" />, count: 0 },
+            ],
+          },
+        ]}
+      />
+    </div>
+  ),
+}

package/src/components/nav-sidebar.test.tsx

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { NavSidebar, type NavSection } from "./nav-sidebar"
+
+const SECTIONS: NavSection[] = [
+  {
+    items: [
+      { href: "/saved", label: "Saved Properties", icon: <svg />, count: 3 },
+      { href: "/drafts", label: "Drafts", icon: <svg />, count: 0 },
+      { href: "/deals", label: "Deals", icon: <svg />, count: 5, children: [{ href: "/deals/open", label: "Open", count: 2 }] },
+    ],
+  },
+]
+
+describe("NavSidebar counts", () => {
+  it("renders a top-level item's count with an accessible label", () => {
+    const html = renderToStaticMarkup(<NavSidebar sections={SECTIONS} currentPath="/saved" />)
+    expect(html).toContain('aria-label="3 items"')
+  })
+
+  it("hides a zero count", () => {
+    const html = renderToStaticMarkup(<NavSidebar sections={SECTIONS} currentPath="/saved" />)
+    expect(html).not.toContain('aria-label="0 items"')
+  })
+
+  it("leaves the trailing space to the chevron on items with children", () => {
+    const html = renderToStaticMarkup(<NavSidebar sections={SECTIONS} currentPath="/saved" />)
+    expect(html).not.toContain('aria-label="5 items"')
+  })
+
+  it("still renders sub-item counts when the branch is open", () => {
+    const html = renderToStaticMarkup(<NavSidebar sections={SECTIONS} currentPath="/deals/open" />)
+    expect(html).toContain('aria-label="2 items"')
+  })
+
+  it("drops counts from collapsed icon-only rows", () => {
+    const html = renderToStaticMarkup(<NavSidebar sections={SECTIONS} currentPath="/saved" collapsed />)
+    expect(html).not.toContain('aria-label="3 items"')
+  })
+})
+
+describe("NavSidebar collapsed", () => {
+  it("names icon-only rows with their label and count", () => {
+    const html = renderToStaticMarkup(<NavSidebar sections={SECTIONS} currentPath="/saved" collapsed />)
+    expect(html).toContain('aria-label="Saved Properties, 3 items"')
+    expect(html).toContain('aria-label="Drafts"')
+  })
+
+  it("does not add an aria-label while expanded, where the visible label names the row", () => {
+    const html = renderToStaticMarkup(<NavSidebar sections={SECTIONS} currentPath="/saved" />)
+    expect(html).not.toContain('aria-label="Saved Properties')
+  })
+})