@lovett/ui 0.2.6 → 0.2.8

package/dist/styles.css

@@ -27,6 +27,7 @@
  *   .scrollbar-hide                                    — ChipNav
  *   .ds-enter-pop, .ds-enter-rise                      — DropdownMenu,
  *                                                        FloatingStatusBar
+ *   .ds-sidebar-group-body                             — SidebarNav.Group
  *   prefers-reduced-motion block                       — accessibility
  *
  * Out of scope for Phase 1: .empty, .skel, .field*, .pg-header, .search-bar,
@@ -2298,3 +2299,25 @@
     outline-offset: 2px;
   }
 }
+
+/* ---- SIDEBAR GROUP COLLAPSE ---- */
+/**
+ * SidebarNav.Group's body collapses through `grid-template-rows` 1fr -> 0fr,
+ * NOT height: the content keeps its natural size for the whole transition
+ * and is clipped by the shrinking track, so nothing inside reflows or jumps
+ * while it closes. The inner element must be `min-height: 0; overflow: hidden`
+ * (a grid item otherwise refuses to shrink below its content).
+ */
+.ds-sidebar-group-body {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows var(--dur-fast) var(--ease-out);
+}
+.ds-sidebar-group-body[data-open='true'] {
+  grid-template-rows: 1fr;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ds-sidebar-group-body {
+    transition: none;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovett/ui",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "private": false,
   "type": "module",
   "description": "Design system primitives, tokens, layouts, and patterns for the Lovett portfolio.",

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

@@ -0,0 +1,162 @@
+/**
+ * SidebarNav — the contract a router-driven rail depends on.
+ *
+ * Active is the CALLER's (aria-current lands where they say, nowhere else);
+ * `asChild` makes the child the row without adding a wrapper; a group is a
+ * real disclosure (aria-expanded + aria-controls resolve, closed items are
+ * inert); a closed group that contains the location carries the active look
+ * so the location is never hidden; the collapsed rail turns a group into a
+ * flyout whose items render at full width.
+ */
+import { useState } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Gauge, Home, Upload } from 'lucide-react'
+import { SidebarNav } from '../sidebar-nav'
+
+function Rail({ collapsed = false, active = '/upload' }: { collapsed?: boolean; active?: string }) {
+  return (
+    <SidebarNav collapsed={collapsed} aria-label="Primary">
+      <SidebarNav.Item icon={Home} label="Dashboard" href="/" active={active === '/'} />
+      <SidebarNav.Group id="audit" icon={Gauge} label="Audit" active={active === '/upload'} defaultOpen>
+        <SidebarNav.Item icon={Upload} label="New audit" href="/upload" active={active === '/upload'} badge="Beta" />
+      </SidebarNav.Group>
+    </SidebarNav>
+  )
+}
+
+describe('SidebarNav', () => {
+  it('is a nav; the active item and only the active item is aria-current', () => {
+    render(<Rail />)
+    expect(screen.getByRole('navigation', { name: 'Primary' })).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: /New audit/ })).toHaveAttribute('aria-current', 'page')
+    expect(screen.getByRole('link', { name: 'Dashboard' })).not.toHaveAttribute('aria-current')
+  })
+
+  it('asChild makes the child the row - no wrapper, the row class on the child', () => {
+    render(
+      <SidebarNav>
+        <SidebarNav.Item asChild icon={Home} label="Dashboard" active>
+          <a href="/" data-testid="child" />
+        </SidebarNav.Item>
+      </SidebarNav>,
+    )
+    const child = screen.getByTestId('child')
+    expect(child.tagName).toBe('A')
+    expect(child).toHaveAttribute('aria-current', 'page')
+    expect(child).toHaveTextContent('Dashboard')
+    expect(child.parentElement?.tagName).toBe('NAV')
+  })
+
+  it('asChild refuses anything but a single element', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    expect(() =>
+      render(
+        <SidebarNav>
+          <SidebarNav.Item asChild icon={Home} label="Dashboard">
+            plain text
+          </SidebarNav.Item>
+        </SidebarNav>,
+      ),
+    ).toThrow(/exactly one element child/)
+    spy.mockRestore()
+  })
+
+  describe('Group', () => {
+    it('is a disclosure: aria-expanded, aria-controls resolves, toggles on click', async () => {
+      const user = userEvent.setup()
+      render(<Rail />)
+      const header = screen.getByRole('button', { name: 'Audit' })
+      expect(header).toHaveAttribute('aria-expanded', 'true')
+      const bodyId = header.getAttribute('aria-controls')
+      expect(bodyId).toBeTruthy()
+      const body = document.getElementById(bodyId as string)
+      expect(body).not.toBeNull()
+      expect(body).toHaveAttribute('role', 'group')
+      expect(within(body as HTMLElement).getByRole('link', { name: /New audit/ })).toBeInTheDocument()
+
+      await user.click(header)
+      expect(header).toHaveAttribute('aria-expanded', 'false')
+      // Closed items stay mounted (the collapse animates) but are inert.
+      expect(body).toHaveAttribute('inert')
+      expect(body).toHaveAttribute('aria-hidden', 'true')
+    })
+
+    it('controlled: onToggle reports the next state and open is the prop', async () => {
+      const user = userEvent.setup()
+      const onToggle = vi.fn()
+      function Controlled() {
+        const [open, setOpen] = useState(false)
+        return (
+          <SidebarNav>
+            <SidebarNav.Group
+              id="g"
+              icon={Gauge}
+              label="Audit"
+              open={open}
+              onToggle={(next) => {
+                onToggle(next)
+                setOpen(next)
+              }}
+            >
+              <SidebarNav.Item icon={Upload} label="New audit" href="/upload" />
+            </SidebarNav.Group>
+          </SidebarNav>
+        )
+      }
+      render(<Controlled />)
+      const header = screen.getByRole('button', { name: 'Audit' })
+      expect(header).toHaveAttribute('aria-expanded', 'false')
+      await user.click(header)
+      expect(onToggle).toHaveBeenCalledWith(true)
+      expect(header).toHaveAttribute('aria-expanded', 'true')
+    })
+
+    it('a CLOSED group that contains the location carries the active look; an open one does not', async () => {
+      const user = userEvent.setup()
+      render(<Rail />)
+      const header = screen.getByRole('button', { name: 'Audit' })
+      // Open: the child row is active, the header is quiet.
+      expect(header.className).not.toMatch(/sidebar-surface-active/)
+      await user.click(header)
+      // Closed: the header takes the active surface so the location is visible.
+      expect(header.className).toMatch(/sidebar-surface-active/)
+    })
+
+    it('a badge renders on the header and on a nested item', () => {
+      render(
+        <SidebarNav>
+          <SidebarNav.Group id="g" icon={Gauge} label="Audit" badge="3" defaultOpen>
+            <SidebarNav.Item icon={Upload} label="New audit" href="/upload" badge="Beta" />
+          </SidebarNav.Group>
+        </SidebarNav>,
+      )
+      expect(screen.getByRole('button', { name: /Audit 3/ })).toBeInTheDocument()
+      expect(screen.getByRole('link', { name: /New audit Beta/ })).toBeInTheDocument()
+    })
+  })
+
+  describe('collapsed rail', () => {
+    it('items keep their name through a title and drop the label text', () => {
+      render(<Rail collapsed active="/" />)
+      const home = screen.getByRole('link', { name: 'Dashboard' })
+      expect(home).toHaveAttribute('title', 'Dashboard')
+      expect(home.querySelector('span.truncate')).toBeNull()
+    })
+
+    it('a group is a tile that opens a flyout holding its items at full width', async () => {
+      const user = userEvent.setup()
+      render(<Rail collapsed />)
+      const tile = screen.getByRole('button', { name: 'Audit' })
+      expect(tile).toHaveAttribute('aria-haspopup', 'dialog')
+      expect(screen.queryByRole('link', { name: /New audit/ })).toBeNull()
+      await user.click(tile)
+      const flyout = await screen.findByRole('dialog', { name: 'Audit' })
+      const item = within(flyout).getByRole('link', { name: /New audit/ })
+      // Full width inside the flyout: the label is text, not a title.
+      expect(item).toHaveTextContent('New audit')
+      expect(item).not.toHaveAttribute('title')
+    })
+  })
+})

package/src/index.ts

@@ -23,6 +23,17 @@ export {
 export { default as BrandLogoTile, type BrandLogoTileProps, type BrandLogoTileSize } from './brand-logo-tile'
 export { default as ProfileSection, type ProfileSectionProps } from './profile-section'
 export { default as ChipNav, type ChipNavItem } from './chip-nav'
+// SidebarNav — a rail of destinations with collapsible groups (submenus) and
+// an icon-only mode whose groups open a Popover flyout. Router-agnostic:
+// `asChild` makes a NavLink the row. Promoted from meta-ads-audit-dashboard's
+// AppSidebar; the workspace context panel is the second consumer to migrate.
+export {
+  SidebarNav,
+  type SidebarNavProps,
+  type SidebarNavItemProps,
+  type SidebarNavGroupProps,
+  type SidebarIcon,
+} from './sidebar-nav'
 export { default as CompletionRing, type CompletionRingProps } from './completion-ring'
 export { default as MicrosoftLogo, type MicrosoftLogoProps } from './microsoft-logo'
 export {

package/src/sidebar-nav.tsx

@@ -0,0 +1,360 @@
+/**
+ * SidebarNav — a vertical rail of destinations with collapsible groups.
+ *
+ * Compound: `<SidebarNav>` (rail state) + `<SidebarNav.Item>` (one
+ * destination) + `<SidebarNav.Group>` (a labelled, collapsible set of items).
+ * Replaces the labelled-section rail — five tracked-out uppercase captions
+ * over flat lists — with submenus: a group is a row you open, and the rail
+ * reads as four or five things instead of eighteen.
+ *
+ * Router-agnostic. An Item renders an `<a href>` by default; pass `asChild`
+ * and the single child element (a react-router `NavLink`, a `Link`) becomes
+ * the row — it receives the className, the `aria-current` and the composed
+ * children. The ACTIVE state is the caller's, never inferred from a URL:
+ * the primitive does not own a router.
+ *
+ * Group is controlled (`open` + `onToggle`) or uncontrolled (`defaultOpen`).
+ * `active` marks a group that CONTAINS the current route, so the rail never
+ * loses the current location behind a closed group. Opening is a plain
+ * button (`aria-expanded`, `aria-controls`); the body collapses through
+ * `grid-template-rows` so its content keeps its size while it closes
+ * (`.ds-sidebar-group-body` in styles.css; honours reduced motion).
+ *
+ * Collapsed rail (`collapsed` on the root): Items become icon tiles with a
+ * `title`; a Group becomes an icon tile that opens a `Popover` flyout to its
+ * right holding the group's items at full width. Inside the flyout the rail
+ * is not collapsed, so the same Item markup renders both ways.
+ *
+ * Token discipline: reads the INTERNAL `--sidebar-*` set (sidebar surfaces,
+ * text, rail) — allowed in packages/ui, ESLint-enforced elsewhere — plus
+ * public `--accent`, `--radius-*`, `--ring-focus`, `--dur-fast`, `--ease-out`.
+ * Icons are the caller's Lucide components.
+ *
+ * Promoted from meta-ads-audit-dashboard's app-local `AppSidebar` (the
+ * consumer that needed groups); the workspace app's context panel is the
+ * second rail shaped like this and the migration target.
+ *
+ * Usage:
+ *
+ *   <SidebarNav collapsed={collapsed} aria-label="Primary">
+ *     <SidebarNav.Item asChild icon={LayoutDashboard} label="Dashboard" active={onHome}>
+ *       <NavLink to="/" end />
+ *     </SidebarNav.Item>
+ *     <SidebarNav.Group id="audit" icon={ClipboardCheck} label="Audit" active={inAudit}
+ *                       open={open === 'audit'} onToggle={() => setOpen(...)}>
+ *       <SidebarNav.Item asChild icon={Upload} label="New audit" active={…}>
+ *         <NavLink to="/upload" end />
+ *       </SidebarNav.Item>
+ *     </SidebarNav.Group>
+ *   </SidebarNav>
+ */
+
+import {
+  cloneElement,
+  createContext,
+  isValidElement,
+  useContext,
+  useId,
+  useState,
+  type AnchorHTMLAttributes,
+  type ComponentType,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+  type SVGProps,
+} from 'react'
+import { ChevronDown } from 'lucide-react'
+import { cn } from './lib/utils'
+import { Popover } from './popover'
+
+/** A Lucide icon, or anything with the same signature. */
+export type SidebarIcon = ComponentType<SVGProps<SVGSVGElement>>
+
+interface RailContext {
+  collapsed: boolean
+  /** True inside a Group's body — items indent and draw the connector rail. */
+  nested: boolean
+}
+
+const Ctx = createContext<RailContext>({ collapsed: false, nested: false })
+
+// ---------------------------------------------------------------------------
+// Root
+
+export interface SidebarNavProps extends HTMLAttributes<HTMLElement> {
+  /** Icon-only rail. Items show a title; groups open a flyout. */
+  collapsed?: boolean
+  children: ReactNode
+}
+
+function SidebarNavRoot({ collapsed = false, className, children, ...rest }: SidebarNavProps) {
+  return (
+    <Ctx.Provider value={{ collapsed, nested: false }}>
+      <nav className={cn('flex flex-col gap-0.5', className)} {...rest}>
+        {children}
+      </nav>
+    </Ctx.Provider>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Row chrome shared by Item and Group header
+
+const ROW_BASE =
+  'relative flex h-9 w-full items-center gap-3 rounded-[var(--radius-md)] px-2.5 text-left text-sm font-medium outline-none transition-colors ' +
+  'focus-visible:[box-shadow:var(--ring-focus)]'
+
+const ROW_REST =
+  'text-[rgb(var(--sidebar-text))] hover:bg-[rgb(var(--sidebar-surface-hover))] hover:text-[rgb(var(--sidebar-text-bright))]'
+
+const ROW_ACTIVE = 'bg-[rgb(var(--sidebar-surface-active))] text-[rgb(var(--sidebar-text-bright))]'
+
+/** The accent bar on the leading edge of the active row. */
+function ActiveBar() {
+  return (
+    <span
+      aria-hidden="true"
+      className="absolute left-0 top-1/2 h-5 w-0.5 -translate-y-1/2 rounded-full bg-[rgb(var(--accent))]"
+    />
+  )
+}
+
+function RowIcon({ icon: Icon }: { icon: SidebarIcon }) {
+  return <Icon className="h-4 w-4 shrink-0" aria-hidden="true" />
+}
+
+function RowBadge({ children }: { children: ReactNode }) {
+  return (
+    <span className="rounded-full bg-[rgb(var(--accent))]/15 px-1.5 py-0.5 text-[10px] font-semibold text-[rgb(var(--accent))]">
+      {children}
+    </span>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Item
+
+export interface SidebarNavItemProps
+  extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'children'> {
+  icon: SidebarIcon
+  label: string
+  /** The current destination. Rendered as `aria-current="page"`. */
+  active?: boolean
+  /** A small trailing tag — "Beta", a count. Hidden when collapsed. */
+  badge?: ReactNode
+  /**
+   * Render the single child element as the row instead of an `<a>`. The child
+   * receives the className, `aria-current` and the composed row content. It
+   * must be a link or keyboard-operable on its own.
+   */
+  asChild?: boolean
+  children?: ReactNode
+}
+
+type ItemChildProps = HTMLAttributes<HTMLElement> & {
+  'aria-current'?: 'page' | undefined
+  title?: string | undefined
+}
+
+function SidebarNavItem({
+  icon,
+  label,
+  active = false,
+  badge,
+  asChild,
+  className,
+  children,
+  ...rest
+}: SidebarNavItemProps) {
+  const { collapsed, nested } = useContext(Ctx)
+
+  const rowClass = cn(
+    ROW_BASE,
+    active ? ROW_ACTIVE : ROW_REST,
+    collapsed && 'justify-center px-0',
+    nested && !collapsed && 'h-8 pl-[2.375rem] text-[13px]',
+    className,
+  )
+  const content = (
+    <>
+      {active && !nested && <ActiveBar />}
+      {(!nested || collapsed) && <RowIcon icon={icon} />}
+      {nested && !collapsed && (
+        // The connector: a dot on the group's rail, filled when active.
+        <span
+          aria-hidden="true"
+          className={cn(
+            'absolute left-[1.0625rem] top-1/2 h-1.5 w-1.5 -translate-x-1/2 -translate-y-1/2 rounded-full transition-colors',
+            active ? 'bg-[rgb(var(--accent))]' : 'bg-[rgb(var(--sidebar-rail))]',
+          )}
+        />
+      )}
+      {!collapsed && <span className="flex-1 truncate">{label}</span>}
+      {/* The space is for the accessible name: "New audit Beta", not "New auditBeta".
+          A whitespace-only text node is invisible in a flex row. */}
+      {!collapsed && badge !== undefined && badge !== null && (
+        <>
+          {' '}
+          <RowBadge>{badge}</RowBadge>
+        </>
+      )}
+    </>
+  )
+  const shared: ItemChildProps = {
+    className: rowClass,
+    'aria-current': active ? 'page' : undefined,
+    title: collapsed ? label : undefined,
+  }
+
+  if (asChild) {
+    if (!isValidElement<ItemChildProps>(children)) {
+      throw new Error('SidebarNav.Item with `asChild` expects exactly one element child.')
+    }
+    const child = children as ReactElement<ItemChildProps>
+    return cloneElement(child, {
+      ...shared,
+      className: cn(child.props.className, rowClass),
+      children: content,
+    })
+  }
+
+  return (
+    <a {...rest} {...shared}>
+      {content}
+    </a>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Group
+
+export interface SidebarNavGroupProps {
+  /** Stable id — the body's DOM id derives from it. */
+  id: string
+  icon: SidebarIcon
+  label: string
+  /** True when a child is the current destination. */
+  active?: boolean
+  /** Controlled open state. Omit for internal state. */
+  open?: boolean
+  defaultOpen?: boolean
+  onToggle?: (open: boolean) => void
+  badge?: ReactNode
+  children: ReactNode
+}
+
+function SidebarNavGroup({
+  id,
+  icon,
+  label,
+  active = false,
+  open: controlledOpen,
+  defaultOpen = false,
+  onToggle,
+  badge,
+  children,
+}: SidebarNavGroupProps) {
+  const { collapsed } = useContext(Ctx)
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen)
+  const open = controlledOpen ?? uncontrolledOpen
+  const setOpen = (next: boolean) => {
+    if (controlledOpen === undefined) setUncontrolledOpen(next)
+    onToggle?.(next)
+  }
+  const reactId = useId()
+  const bodyId = `sidebar-group-${id}-${reactId}`
+  const labelId = `${bodyId}-label`
+
+  if (collapsed) {
+    // The flyout: the group's items at full width, to the right of the tile.
+    return (
+      <Popover>
+        <Popover.Trigger asChild>
+          <button
+            type="button"
+            title={label}
+            className={cn(ROW_BASE, 'justify-center px-0', active ? ROW_ACTIVE : ROW_REST)}
+          >
+            {active && <ActiveBar />}
+            <RowIcon icon={icon} />
+          </button>
+        </Popover.Trigger>
+        <Popover.Content side="right" align="start" offset={8} aria-label={label} className="min-w-[13rem] p-1.5">
+          <Ctx.Provider value={{ collapsed: false, nested: false }}>
+            <p
+              id={labelId}
+              className="px-2.5 pb-1 pt-1 text-[11px] font-semibold text-[rgb(var(--text-tertiary))]"
+            >
+              {label}
+            </p>
+            <div role="group" aria-labelledby={labelId} className="flex flex-col gap-0.5">
+              {children}
+            </div>
+          </Ctx.Provider>
+        </Popover.Content>
+      </Popover>
+    )
+  }
+
+  return (
+    <div className="flex flex-col">
+      <button
+        type="button"
+        onClick={() => setOpen(!open)}
+        aria-expanded={open}
+        aria-controls={bodyId}
+        id={labelId}
+        // Closed and containing the current route: the header carries the
+        // active look so the location is never hidden. Open, the child row
+        // carries it and the header stays quiet.
+        className={cn(ROW_BASE, active && !open ? ROW_ACTIVE : ROW_REST)}
+      >
+        {active && !open && <ActiveBar />}
+        <RowIcon icon={icon} />
+        <span id={`${labelId}-text`} className="flex-1 truncate">
+          {label}
+        </span>
+        {badge !== undefined && badge !== null && (
+          <>
+            {' '}
+            <RowBadge>{badge}</RowBadge>
+          </>
+        )}
+        <ChevronDown
+          aria-hidden="true"
+          className="h-3.5 w-3.5 shrink-0 text-[rgb(var(--sidebar-text-dim))] transition-transform duration-150 ease-out motion-reduce:transition-none"
+          style={{ transform: open ? 'rotate(180deg)' : 'rotate(0deg)' }}
+        />
+      </button>
+      <div className="ds-sidebar-group-body" data-open={open ? 'true' : 'false'}>
+        <div className="min-h-0 overflow-hidden">
+          <Ctx.Provider value={{ collapsed: false, nested: true }}>
+            <div
+              id={bodyId}
+              role="group"
+              aria-labelledby={`${labelId}-text`}
+              // The rail: one hairline under the icon column that the child
+              // connectors sit on. Its geometry derives from the icon centre
+              // (px-2.5 + half of h-4 = 1.0625rem).
+              className="relative flex flex-col gap-0.5 py-0.5 before:absolute before:bottom-1 before:left-[1.0625rem] before:top-1 before:w-px before:-translate-x-1/2 before:bg-[rgb(var(--sidebar-rail))]"
+              // Stays in the DOM while closed so the track has something to
+              // shrink over; `inert` keeps its links out of the tab ring and
+              // the accessibility tree until it is open again.
+              inert={!open}
+              aria-hidden={!open}
+            >
+              {children}
+            </div>
+          </Ctx.Provider>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+
+export const SidebarNav = Object.assign(SidebarNavRoot, {
+  Item: SidebarNavItem,
+  Group: SidebarNavGroup,
+})

package/src/styles.css

@@ -27,6 +27,7 @@
  *   .scrollbar-hide                                    — ChipNav
  *   .ds-enter-pop, .ds-enter-rise                      — DropdownMenu,
  *                                                        FloatingStatusBar
+ *   .ds-sidebar-group-body                             — SidebarNav.Group
  *   prefers-reduced-motion block                       — accessibility
  *
  * Out of scope for Phase 1: .empty, .skel, .field*, .pg-header, .search-bar,
@@ -2298,3 +2299,25 @@
     outline-offset: 2px;
   }
 }
+
+/* ---- SIDEBAR GROUP COLLAPSE ---- */
+/**
+ * SidebarNav.Group's body collapses through `grid-template-rows` 1fr -> 0fr,
+ * NOT height: the content keeps its natural size for the whole transition
+ * and is clipped by the shrinking track, so nothing inside reflows or jumps
+ * while it closes. The inner element must be `min-height: 0; overflow: hidden`
+ * (a grid item otherwise refuses to shrink below its content).
+ */
+.ds-sidebar-group-body {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows var(--dur-fast) var(--ease-out);
+}
+.ds-sidebar-group-body[data-open='true'] {
+  grid-template-rows: 1fr;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ds-sidebar-group-body {
+    transition: none;
+  }
+}