@actuate-media/cms-admin 0.9.0 → 0.11.0

package/src/layout/Header.tsx

@@ -24,100 +24,100 @@ export function Header({ onToggleSidebar, session, onNavigate }: HeaderProps) {
 
   return (
     <>
-      <header className="h-14 border-b border-border bg-background flex items-center justify-between px-4 gap-4">
+      <header className="border-border bg-background flex h-14 items-center justify-between gap-4 border-b px-4">
         <button
           onClick={onToggleSidebar}
-          className="lg:hidden p-2 hover:bg-accent rounded-lg transition-colors"
+          className="hover:bg-accent rounded-lg p-2 transition-colors md:hidden"
           aria-label="Toggle sidebar"
         >
-          <Menu className="w-5 h-5 text-foreground" strokeWidth={2} />
+          <Menu className="text-foreground h-5 w-5" strokeWidth={2} />
         </button>
 
-        <div className="flex items-center lg:hidden">
-          <span className="text-lg font-semibold text-foreground">Actuate</span>
+        <div className="flex items-center md:hidden">
+          <span className="text-foreground text-lg font-semibold">Actuate</span>
         </div>
 
         <div className="flex-1" />
 
         <div className="flex items-center gap-2 sm:gap-3">
-          <div className="hidden md:block relative">
-            <Search className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-muted-foreground pointer-events-none" />
+          <div className="relative hidden md:block">
+            <Search className="text-muted-foreground pointer-events-none absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2" />
             <input
               type="text"
               placeholder="Search... (⌘K)"
               value={searchQuery}
               onChange={(e) => setSearchQuery(e.target.value)}
               onFocus={() => setShowCommandPalette(true)}
-              className="w-64 pl-9 pr-3 py-1.5 text-sm border border-border rounded-lg bg-input-background text-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent"
+              className="border-border bg-input-background text-foreground focus:ring-ring w-64 rounded-lg border py-1.5 pr-3 pl-9 text-sm focus:border-transparent focus:ring-2 focus:outline-none"
             />
           </div>
 
           <button
             onClick={() => setShowCommandPalette(true)}
-            className="md:hidden p-2 hover:bg-accent rounded-lg transition-colors"
+            className="hover:bg-accent rounded-lg p-2 transition-colors md:hidden"
             aria-label="Search"
           >
-            <Search className="w-5 h-5 text-muted-foreground" />
+            <Search className="text-muted-foreground h-5 w-5" />
           </button>
 
           <LocaleSwitcher />
 
           <button
             onClick={toggleTheme}
-            className="p-2 hover:bg-accent rounded-lg transition-colors"
+            className="hover:bg-accent rounded-lg p-2 transition-colors"
             aria-label="Toggle theme"
           >
             {resolvedTheme === 'dark' ? (
-              <Sun className="w-5 h-5 text-muted-foreground" />
+              <Sun className="text-muted-foreground h-5 w-5" />
             ) : (
-              <Moon className="w-5 h-5 text-muted-foreground" />
+              <Moon className="text-muted-foreground h-5 w-5" />
             )}
           </button>
 
           <button
-            className="p-2 hover:bg-accent rounded-lg transition-colors relative"
+            className="hover:bg-accent relative rounded-lg p-2 transition-colors"
             aria-label="Notifications"
           >
-            <Bell className="w-5 h-5 text-muted-foreground" />
-            <span className="absolute top-1.5 right-1.5 w-2 h-2 bg-destructive rounded-full" />
+            <Bell className="text-muted-foreground h-5 w-5" />
+            <span className="bg-destructive absolute top-1.5 right-1.5 h-2 w-2 rounded-full" />
           </button>
 
           <DropdownMenu.Root>
             <DropdownMenu.Trigger asChild>
-              <button className="flex items-center gap-2 p-1.5 hover:bg-accent rounded-lg transition-colors">
-                <div className="w-8 h-8 bg-linear-to-br from-blue-500 to-purple-600 rounded-full flex items-center justify-center">
-                  <span className="text-white text-sm font-medium">
+              <button className="hover:bg-accent flex items-center gap-2 rounded-lg p-1.5 transition-colors">
+                <div className="flex h-8 w-8 items-center justify-center rounded-full bg-linear-to-br from-blue-500 to-purple-600">
+                  <span className="text-sm font-medium text-white">
                     {session?.user?.name?.charAt(0)?.toUpperCase() ?? 'A'}
                   </span>
                 </div>
-                <ChevronDown className="w-4 h-4 text-muted-foreground hidden sm:block" />
+                <ChevronDown className="text-muted-foreground hidden h-4 w-4 sm:block" />
               </button>
             </DropdownMenu.Trigger>
 
             <DropdownMenu.Portal>
               <DropdownMenu.Content
-                className="min-w-[200px] bg-popover text-popover-foreground rounded-lg border border-border shadow-lg p-1 z-50"
+                className="bg-popover text-popover-foreground border-border z-50 min-w-[200px] rounded-lg border p-1 shadow-lg"
                 align="end"
                 sideOffset={5}
               >
-                <div className="px-3 py-2 border-b border-border">
+                <div className="border-border border-b px-3 py-2">
                   <p className="text-sm font-medium">{session?.user?.name ?? 'Admin User'}</p>
-                  <p className="text-xs text-muted-foreground">
+                  <p className="text-muted-foreground text-xs">
                     {session?.user?.email ?? 'admin@example.com'}
                   </p>
                 </div>
-                <DropdownMenu.Item className="flex items-center gap-2 px-3 py-2 text-sm hover:bg-accent rounded cursor-pointer outline-none">
-                  <User className="w-4 h-4" />
+                <DropdownMenu.Item className="hover:bg-accent flex cursor-pointer items-center gap-2 rounded px-3 py-2 text-sm outline-none">
+                  <User className="h-4 w-4" />
                   Profile
                 </DropdownMenu.Item>
                 <DropdownMenu.Item
-                  className="flex items-center gap-2 px-3 py-2 text-sm hover:bg-accent rounded cursor-pointer outline-none"
+                  className="hover:bg-accent flex cursor-pointer items-center gap-2 rounded px-3 py-2 text-sm outline-none"
                   onSelect={() => onNavigate('/settings')}
                 >
                   Settings
                 </DropdownMenu.Item>
-                <DropdownMenu.Separator className="h-px bg-border my-1" />
-                <DropdownMenu.Item className="flex items-center gap-2 px-3 py-2 text-sm text-destructive hover:bg-accent rounded cursor-pointer outline-none">
+                <DropdownMenu.Separator className="bg-border my-1 h-px" />
+                <DropdownMenu.Item className="text-destructive hover:bg-accent flex cursor-pointer items-center gap-2 rounded px-3 py-2 text-sm outline-none">
                   Logout
                 </DropdownMenu.Item>
               </DropdownMenu.Content>

package/src/layout/Layout.tsx

@@ -4,6 +4,7 @@ import { useState, useEffect, type ReactNode } from 'react'
 import { Sidebar } from './Sidebar.js'
 import { Header } from './Header.js'
 import { Breadcrumbs } from '../components/Breadcrumbs.js'
+import { AdminShell } from './primitives/AdminShell.js'
 import { Toaster } from 'sonner'
 
 export interface LayoutProps {
@@ -14,6 +15,20 @@ export interface LayoutProps {
   children: ReactNode
 }
 
+/**
+ * Layout — thin shell that wires Sidebar/Header/Breadcrumbs into the
+ * `<AdminShell>` primitive.
+ *
+ * `AdminShell` (in `./primitives/AdminShell.tsx`) owns the actual layout
+ * algorithm (CSS Grid on desktop, fixed slide-in overlay on mobile,
+ * JS-driven `matchMedia` breakpoint) so that every layout decision lives
+ * in one place. Per-product chrome (Sidebar, Header, Breadcrumbs)
+ * composes on top of it.
+ *
+ * DO NOT re-implement layout logic in this file — extend `AdminShell`
+ * instead. The previous flex + `fixed`↔`static` toggle caused recurring
+ * sidebar-overlap bugs; the grid-based primitive is the contract.
+ */
 export function Layout({ config, session, currentPath, onNavigate, children }: LayoutProps) {
   const [sidebarCollapsed, setSidebarCollapsed] = useState(false)
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false)
@@ -22,54 +37,32 @@ export function Layout({ config, session, currentPath, onNavigate, children }: L
     setMobileSidebarOpen(false)
   }, [currentPath])
 
-  useEffect(() => {
-    const handleResize = () => {
-      if (window.innerWidth < 1024) {
-        setMobileSidebarOpen(false)
-      }
-    }
-    window.addEventListener('resize', handleResize)
-    return () => window.removeEventListener('resize', handleResize)
-  }, [])
-
   return (
-    <div className="h-screen flex overflow-hidden bg-background text-foreground">
+    <>
       <Toaster position="bottom-right" />
-
-      {mobileSidebarOpen && (
-        <div
-          className="fixed inset-0 bg-black/50 z-40 lg:hidden"
-          onClick={() => setMobileSidebarOpen(false)}
-        />
-      )}
-
-      <div
-        className={`fixed lg:static inset-y-0 left-0 z-50 transform transition-transform duration-300 lg:transform-none ${
-          mobileSidebarOpen ? 'translate-x-0' : '-translate-x-full lg:translate-x-0'
-        }`}
+      <AdminShell
+        mobileSidebarOpen={mobileSidebarOpen}
+        onMobileSidebarClose={() => setMobileSidebarOpen(false)}
+        sidebar={
+          <Sidebar
+            collapsed={sidebarCollapsed}
+            onToggleCollapse={() => setSidebarCollapsed(!sidebarCollapsed)}
+            currentPath={currentPath}
+            onNavigate={onNavigate}
+            config={config}
+          />
+        }
+        header={
+          <Header
+            onToggleSidebar={() => setMobileSidebarOpen(!mobileSidebarOpen)}
+            session={session}
+            onNavigate={onNavigate}
+          />
+        }
+        breadcrumbs={<Breadcrumbs currentPath={currentPath} onNavigate={onNavigate} />}
       >
-        <Sidebar
-          collapsed={sidebarCollapsed}
-          onToggleCollapse={() => setSidebarCollapsed(!sidebarCollapsed)}
-          currentPath={currentPath}
-          onNavigate={onNavigate}
-          config={config}
-        />
-      </div>
-
-      <div className="flex-1 flex flex-col overflow-hidden">
-        <Header
-          onToggleSidebar={() => setMobileSidebarOpen(!mobileSidebarOpen)}
-          session={session}
-          onNavigate={onNavigate}
-        />
-
-        <Breadcrumbs currentPath={currentPath} onNavigate={onNavigate} />
-
-        <main className="flex-1 overflow-auto bg-background">
-          <div className="h-full">{children}</div>
-        </main>
-      </div>
-    </div>
+        <div className="h-full">{children}</div>
+      </AdminShell>
+    </>
   )
 }

package/src/layout/Sidebar.tsx

@@ -25,8 +25,13 @@ import {
   KeyRound,
 } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
+import { ActuateBrandLogo } from '../assets/actuate-logo.js'
 
-function ActuateLogo({ className }: { className?: string }) {
+/**
+ * Compact mark used in the collapsed sidebar — just the "C" symbol from the
+ * full lockup, drawn as its own simple SVG so it stays crisp at 32×32.
+ */
+function ActuateMark({ className }: { className?: string }) {
   return (
     <svg
       viewBox="0 0 40 44"
@@ -35,53 +40,21 @@ function ActuateLogo({ className }: { className?: string }) {
       className={className}
       aria-hidden="true"
     >
-      {/* Upward arrow / chevron */}
-      <polygon points="20,2 6,18 12,18 20,8 28,18 34,18" fill="#E8646A" />
-      {/* Three vertical bars */}
-      <rect x="11" y="20" width="4" height="22" rx="1" fill="#E8646A" />
-      <rect x="18" y="20" width="4" height="22" rx="1" fill="#E8646A" />
-      <rect x="25" y="20" width="4" height="22" rx="1" fill="#E8646A" />
+      <polygon points="20,2 6,18 12,18 20,8 28,18 34,18" fill="#F05E65" />
+      <rect x="11" y="20" width="4" height="22" rx="1" fill="#F05E65" />
+      <rect x="18" y="20" width="4" height="22" rx="1" fill="#F05E65" />
+      <rect x="25" y="20" width="4" height="22" rx="1" fill="#F05E65" />
     </svg>
   )
 }
 
+/**
+ * Full Actuate Media lockup. Inline SVG with a transparent background so it
+ * sits naturally on whatever surface the sidebar uses (light or dark theme,
+ * custom branding background, etc.).
+ */
 function ActuateWordmark({ className }: { className?: string }) {
-  return (
-    <svg
-      viewBox="0 0 170 44"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
-      className={className}
-      aria-hidden="true"
-    >
-      <polygon points="20,2 6,18 12,18 20,8 28,18 34,18" fill="#E8646A" />
-      <rect x="11" y="20" width="4" height="22" rx="1" fill="#E8646A" />
-      <rect x="18" y="20" width="4" height="22" rx="1" fill="#E8646A" />
-      <rect x="25" y="20" width="4" height="22" rx="1" fill="#E8646A" />
-      <text
-        x="44"
-        y="25"
-        fontFamily="system-ui, sans-serif"
-        fontSize="17"
-        fontWeight="600"
-        letterSpacing="1.5"
-        fill="#E8646A"
-      >
-        ACTUATE
-      </text>
-      <text
-        x="44"
-        y="40"
-        fontFamily="system-ui, sans-serif"
-        fontSize="10"
-        fontWeight="500"
-        letterSpacing="4"
-        fill="#9CA3AF"
-      >
-        MEDIA
-      </text>
-    </svg>
-  )
+  return <ActuateBrandLogo className={className} />
 }
 
 const ICON_MAP: Record<string, LucideIcon> = {
@@ -104,21 +77,21 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
 
   if (collapsed) {
     if (customLogo) {
-      return <img src={customLogo} alt={brandName ?? 'Admin'} className="w-8 h-8 object-contain" />
+      return <img src={customLogo} alt={brandName ?? 'Admin'} className="h-8 w-8 object-contain" />
     }
-    return <ActuateLogo className="w-8 h-8" />
+    return <ActuateMark className="h-8 w-8" />
   }
 
   if (customLogo) {
     return (
-      <div className="flex items-center gap-2.5 min-w-0">
+      <div className="flex min-w-0 items-center gap-2.5">
         <img
           src={customLogo}
           alt={brandName ?? 'Admin'}
-          className="h-8 w-auto object-contain shrink-0"
+          className="h-8 w-auto shrink-0 object-contain"
         />
         {brandName && (
-          <span className="text-sm font-semibold text-sidebar-foreground truncate">
+          <span className="text-sidebar-foreground truncate text-sm font-semibold">
             {brandName}
           </span>
         )}
@@ -128,14 +101,14 @@ function BrandLogo({ config, collapsed }: { config?: any; collapsed: boolean })
 
   if (brandName) {
     return (
-      <div className="flex items-center gap-2.5 min-w-0">
-        <ActuateLogo className="w-7 h-7 shrink-0" />
-        <span className="text-sm font-semibold text-sidebar-foreground truncate">{brandName}</span>
+      <div className="flex min-w-0 items-center gap-2.5">
+        <ActuateMark className="h-7 w-7 shrink-0" />
+        <span className="text-sidebar-foreground truncate text-sm font-semibold">{brandName}</span>
       </div>
     )
   }
 
-  return <ActuateWordmark className="h-8 w-auto" />
+  return <ActuateWordmark className="h-9" />
 }
 
 const defaultNavItems = [
@@ -169,12 +142,12 @@ export function Sidebar({
 
   return (
     <aside
-      className={`h-full bg-sidebar border-r border-sidebar-border transition-all duration-200 ${
+      className={`bg-sidebar border-sidebar-border h-full border-r transition-all duration-200 ${
         collapsed ? 'w-20' : 'w-64'
       }`}
     >
       <div
-        className={`flex items-center h-14 border-b border-sidebar-border px-4 ${
+        className={`border-sidebar-border flex h-14 items-center border-b px-4 ${
           collapsed ? 'justify-center' : 'justify-between'
         }`}
       >
@@ -182,18 +155,18 @@ export function Sidebar({
         {collapsed && <BrandLogo config={config} collapsed={true} />}
         <button
           onClick={onToggleCollapse}
-          className="hidden lg:block p-2 hover:bg-sidebar-accent rounded-lg transition-colors shrink-0"
+          className="hover:bg-sidebar-accent hidden shrink-0 rounded-lg p-2 transition-colors md:block"
           aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
         >
           {collapsed ? (
-            <ChevronRight className="w-4 h-4 text-sidebar-foreground" />
+            <ChevronRight className="text-sidebar-foreground h-4 w-4" />
           ) : (
-            <ChevronLeft className="w-4 h-4 text-sidebar-foreground" />
+            <ChevronLeft className="text-sidebar-foreground h-4 w-4" />
           )}
         </button>
       </div>
 
-      <nav className="p-3 space-y-1">
+      <nav className="space-y-1 p-3">
         {navItems.map((item, idx) => {
           const Icon = item.icon
           const isActive =
@@ -205,27 +178,27 @@ export function Sidebar({
           return (
             <div key={item.path}>
               {showGroupLabel && !collapsed && (
-                <div className="pt-3 pb-1 px-3">
-                  <span className="text-[10px] font-semibold uppercase tracking-wider text-sidebar-foreground/50">
+                <div className="px-3 pt-3 pb-1">
+                  <span className="text-sidebar-foreground/50 text-[10px] font-semibold tracking-wider uppercase">
                     {item.group}
                   </span>
                 </div>
               )}
               {showGroupLabel && collapsed && (
-                <div className="pt-2 pb-1 flex justify-center">
-                  <span className="w-4 border-t border-sidebar-foreground/20" />
+                <div className="flex justify-center pt-2 pb-1">
+                  <span className="border-sidebar-foreground/20 w-4 border-t" />
                 </div>
               )}
               <button
                 onClick={() => onNavigate(item.path)}
-                className={`flex items-center gap-3 px-3 py-2.5 rounded-lg transition-colors w-full text-left ${
+                className={`flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left transition-colors ${
                   isActive
                     ? 'bg-sidebar-accent text-sidebar-primary'
                     : 'text-sidebar-foreground hover:bg-sidebar-accent'
                 } ${collapsed ? 'justify-center' : ''}`}
                 title={collapsed ? item.label : ''}
               >
-                <Icon className="w-5 h-5 shrink-0" />
+                <Icon className="h-5 w-5 shrink-0" />
                 {!collapsed && <span className="text-sm font-medium">{item.label}</span>}
               </button>
             </div>

package/src/layout/primitives/AdminShell.tsx

@@ -0,0 +1,118 @@
+import { useEffect, useState } from 'react'
+import type { ReactNode } from 'react'
+
+export interface AdminShellProps {
+  /** Sidebar/navigation slot. Rendered in the left column on desktop. */
+  sidebar: ReactNode
+  /** Top header slot. Rendered above the main content. */
+  header?: ReactNode
+  /** Optional breadcrumb / sub-header slot rendered below the header. */
+  breadcrumbs?: ReactNode
+  /** Main content. Scrolls independently of the sidebar. */
+  children: ReactNode
+  /**
+   * Whether the mobile sidebar overlay is currently open. Controlled.
+   * AdminShell renders the backdrop + slide transform; the consumer owns
+   * the open state and the hamburger button that toggles it.
+   */
+  mobileSidebarOpen?: boolean
+  onMobileSidebarClose?: () => void
+  /**
+   * Breakpoint above which the sidebar docks beside the content instead
+   * of overlaying on top of it. Mirrors Tailwind's `md` (768px) default.
+   */
+  desktopBreakpoint?: number
+}
+
+/**
+ * The canonical admin chrome. Owns the entire viewport, splits into
+ * `sidebar | (header + breadcrumbs + content)`, and handles the mobile
+ * overlay transition.
+ *
+ * Implementation notes:
+ *  - Desktop layout is CSS Grid with `gridTemplateColumns: 'auto minmax(0, 1fr)'`.
+ *    The `minmax(0, 1fr)` is load-bearing: it lets the content shrink
+ *    below its intrinsic width when the sidebar takes its share, which
+ *    is the one thing flex-based shells fail at.
+ *  - Mobile layout is a single block with the sidebar absolutely
+ *    positioned and slid in via `transform: translateX(…)`. We avoid
+ *    the brittle `fixed` ↔ `static` toggle that caused recurring sidebar
+ *    overlap bugs in the old layout.
+ *  - The desktop/mobile decision is made in JS via `matchMedia` so the
+ *    layout is independent of Tailwind's `md:` utility compilation. If
+ *    the CSS bundle is stale or partially loaded the layout still works.
+ */
+export function AdminShell({
+  sidebar,
+  header,
+  breadcrumbs,
+  children,
+  mobileSidebarOpen = false,
+  onMobileSidebarClose,
+  desktopBreakpoint = 768,
+}: AdminShellProps) {
+  const [isDesktop, setIsDesktop] = useState(false)
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const mq = window.matchMedia(`(min-width: ${desktopBreakpoint}px)`)
+    const handler = () => setIsDesktop(mq.matches)
+    handler()
+    mq.addEventListener('change', handler)
+    return () => mq.removeEventListener('change', handler)
+  }, [desktopBreakpoint])
+
+  return (
+    <div
+      className="bg-background text-foreground h-screen overflow-hidden"
+      style={
+        isDesktop
+          ? { display: 'grid', gridTemplateColumns: 'auto minmax(0, 1fr)' }
+          : { display: 'block', position: 'relative' }
+      }
+    >
+      {!isDesktop && mobileSidebarOpen && (
+        <div
+          aria-hidden
+          className="fixed inset-0 z-40 bg-black/30 backdrop-blur-sm"
+          onClick={onMobileSidebarClose}
+        />
+      )}
+
+      <div
+        className="z-50"
+        style={
+          isDesktop
+            ? {
+                gridColumn: '1 / 2',
+                height: '100vh',
+                overflow: 'hidden',
+              }
+            : {
+                position: 'fixed',
+                top: 0,
+                bottom: 0,
+                left: 0,
+                transform: mobileSidebarOpen ? 'translateX(0)' : 'translateX(-100%)',
+                transition: 'transform 300ms ease',
+              }
+        }
+      >
+        {sidebar}
+      </div>
+
+      <div
+        className="flex flex-col overflow-hidden"
+        style={
+          isDesktop
+            ? { gridColumn: '2 / 3', height: '100vh', minWidth: 0 }
+            : { height: '100vh', minWidth: 0 }
+        }
+      >
+        {header}
+        {breadcrumbs}
+        <main className="flex-1 overflow-y-auto">{children}</main>
+      </div>
+    </div>
+  )
+}

package/src/layout/primitives/Box.tsx

@@ -0,0 +1,30 @@
+import { forwardRef } from 'react'
+import type { HTMLAttributes, ReactNode, ElementType } from 'react'
+
+export interface BoxProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
+  /**
+   * The element to render. Defaults to `div`. Use semantic elements (`<section>`,
+   * `<article>`, etc.) for accessibility — Box is the lowest-level escape
+   * hatch and exists primarily so views don't reach for raw `<div>` with
+   * five Tailwind utilities.
+   */
+  as?: ElementType
+  children?: ReactNode
+}
+
+/**
+ * The lowest-level primitive — a forwardRef'd div (by default) that exists
+ * so consumers always have a stable, semantically-tagged container to
+ * compose around. Prefer Box over a bare `<div>` to keep the design system
+ * audit clean.
+ */
+export const Box = forwardRef<HTMLElement, BoxProps>(function Box(
+  { as: Component = 'div', children, ...rest },
+  ref,
+) {
+  return (
+    <Component ref={ref} {...rest}>
+      {children}
+    </Component>
+  )
+})

package/src/layout/primitives/Cluster.tsx

@@ -0,0 +1,74 @@
+import type { HTMLAttributes, ReactNode, ElementType } from 'react'
+import type { SpaceToken } from './tokens.js'
+
+export type ClusterAlign = 'start' | 'center' | 'end' | 'baseline' | 'stretch'
+export type ClusterJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'
+
+export interface ClusterProps extends HTMLAttributes<HTMLElement> {
+  /** Gap between children. Maps to Tailwind `gap-{space}`. */
+  space?: SpaceToken
+  /** Render as a different element. Defaults to `div`. */
+  as?: ElementType
+  /** Align items on the cross axis. */
+  align?: ClusterAlign
+  /** Distribute items along the main axis. */
+  justify?: ClusterJustify
+  /** Reverse the order of children. */
+  reverse?: boolean
+  /** Disable wrapping (default: true, items wrap on overflow). */
+  noWrap?: boolean
+  children?: ReactNode
+}
+
+const ALIGN_CLASS: Record<ClusterAlign, string> = {
+  start: 'items-start',
+  center: 'items-center',
+  end: 'items-end',
+  baseline: 'items-baseline',
+  stretch: 'items-stretch',
+}
+
+const JUSTIFY_CLASS: Record<ClusterJustify, string> = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+  between: 'justify-between',
+  around: 'justify-around',
+  evenly: 'justify-evenly',
+}
+
+/**
+ * Horizontal cluster of items with a consistent gap, wrapping by default.
+ * The canonical use case is action toolbars (`<Cluster justify="end">`),
+ * badge groups, breadcrumbs, etc. Never reach for `flex flex-wrap gap-2`
+ * directly — use Cluster.
+ */
+export function Cluster({
+  space = '2',
+  as: Component = 'div',
+  align = 'center',
+  justify = 'start',
+  reverse,
+  noWrap,
+  className = '',
+  children,
+  ...rest
+}: ClusterProps) {
+  const classes = [
+    'flex',
+    reverse ? 'flex-row-reverse' : 'flex-row',
+    noWrap ? 'flex-nowrap' : 'flex-wrap',
+    `gap-${space}`,
+    ALIGN_CLASS[align],
+    JUSTIFY_CLASS[justify],
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  return (
+    <Component className={classes} {...rest}>
+      {children}
+    </Component>
+  )
+}