@actuate-media/cms-admin 0.10.0 → 0.11.0

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>
+  )
+}

package/src/layout/primitives/Grid.tsx

@@ -0,0 +1,120 @@
+import type { HTMLAttributes, ReactNode, ElementType } from 'react'
+import type { SpaceToken } from './tokens.js'
+
+/**
+ * Responsive column count. Pass a number for static grids, or a map to
+ * change column count at each breakpoint.
+ *
+ * @example
+ *   columns={3}                              // 3 cols at every breakpoint
+ *   columns={{ base: 1, md: 2, lg: 4 }}      // responsive
+ */
+export type GridResponsive =
+  | number
+  | { base?: number; sm?: number; md?: number; lg?: number; xl?: number; '2xl'?: number }
+
+export interface GridProps extends HTMLAttributes<HTMLElement> {
+  columns: GridResponsive
+  /** Gap between cells. */
+  space?: SpaceToken
+  /** Row gap (defaults to `space`). */
+  rowSpace?: SpaceToken
+  /** Render as a different element. Defaults to `div`. */
+  as?: ElementType
+  /**
+   * Use auto-fit instead of explicit column counts. When set, `minItemWidth`
+   * controls the minimum tile width before the grid reflows. Use this for
+   * card grids that should adapt to container width without specific
+   * breakpoints.
+   */
+  autoFit?: boolean
+  /** Min tile width when `autoFit` is true. Defaults to `16rem`. */
+  minItemWidth?: string
+  children?: ReactNode
+}
+
+const COL_CLASS: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-2',
+  3: 'grid-cols-3',
+  4: 'grid-cols-4',
+  5: 'grid-cols-5',
+  6: 'grid-cols-6',
+  7: 'grid-cols-7',
+  8: 'grid-cols-8',
+  9: 'grid-cols-9',
+  10: 'grid-cols-10',
+  11: 'grid-cols-11',
+  12: 'grid-cols-12',
+}
+
+const BP_PREFIX = ['', 'sm:', 'md:', 'lg:', 'xl:', '2xl:'] as const
+type BpKey = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+
+function columnsToClasses(columns: GridResponsive): string {
+  if (typeof columns === 'number') {
+    return COL_CLASS[columns] ?? 'grid-cols-1'
+  }
+  const order: BpKey[] = ['base', 'sm', 'md', 'lg', 'xl', '2xl']
+  return order
+    .map((bp, i) => {
+      const n = columns[bp]
+      if (!n) return ''
+      const base = COL_CLASS[n] ?? 'grid-cols-1'
+      return BP_PREFIX[i] + base
+    })
+    .filter(Boolean)
+    .join(' ')
+}
+
+/**
+ * Responsive CSS grid primitive. Pass either an explicit `columns` count
+ * (per-breakpoint or static) or set `autoFit` for a `repeat(auto-fit, …)`
+ * tile grid. Both modes share the same `space` / `rowSpace` knobs so
+ * usage is consistent across views.
+ */
+export function Grid({
+  columns,
+  space = '4',
+  rowSpace,
+  as: Component = 'div',
+  autoFit,
+  minItemWidth = '16rem',
+  className = '',
+  style,
+  children,
+  ...rest
+}: GridProps) {
+  if (autoFit) {
+    return (
+      <Component
+        className={['grid', `gap-${space}`, rowSpace ? `gap-y-${rowSpace}` : '', className]
+          .filter(Boolean)
+          .join(' ')}
+        style={{
+          gridTemplateColumns: `repeat(auto-fit, minmax(${minItemWidth}, 1fr))`,
+          ...style,
+        }}
+        {...rest}
+      >
+        {children}
+      </Component>
+    )
+  }
+
+  const classes = [
+    'grid',
+    columnsToClasses(columns),
+    `gap-${space}`,
+    rowSpace ? `gap-y-${rowSpace}` : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  return (
+    <Component className={classes} style={style} {...rest}>
+      {children}
+    </Component>
+  )
+}

package/src/layout/primitives/PageContainer.tsx

@@ -0,0 +1,96 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+import { Stack } from './Stack.js'
+
+export interface PageContainerProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  /** Page title rendered as an h1 inside the page header. */
+  title?: ReactNode
+  /** Optional sub-headline shown beneath the title. */
+  description?: ReactNode
+  /** Right-aligned action area (buttons, filters). Rendered in the header. */
+  actions?: ReactNode
+  /**
+   * Maximum width of the content. Defaults to `7xl` (Tailwind's max-w-7xl,
+   * ~1280px). Pass `'full'` for edge-to-edge content.
+   */
+  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' | '7xl' | 'full'
+  /** Horizontal padding token. Defaults to `6` (24px). */
+  paddingX?: '4' | '6' | '8'
+  /** Vertical padding token. Defaults to `6`. */
+  paddingY?: '4' | '6' | '8' | '10'
+  /** Vertical gap between the header and the body. Defaults to `6`. */
+  gap?: '4' | '6' | '8'
+  children?: ReactNode
+}
+
+const MAX_WIDTH_CLASS: Record<NonNullable<PageContainerProps['maxWidth']>, string> = {
+  sm: 'max-w-sm',
+  md: 'max-w-md',
+  lg: 'max-w-lg',
+  xl: 'max-w-xl',
+  '2xl': 'max-w-2xl',
+  '3xl': 'max-w-3xl',
+  '4xl': 'max-w-4xl',
+  '5xl': 'max-w-5xl',
+  '6xl': 'max-w-6xl',
+  '7xl': 'max-w-7xl',
+  full: 'max-w-none',
+}
+
+/**
+ * The single canonical wrapper for every admin page. PageContainer owns
+ * three responsibilities so individual views can stop redoing them:
+ *
+ *  1. Consistent max-width + horizontal padding (so dashboards, lists, and
+ *     forms all line up visually).
+ *  2. A standard header slot with title + description + actions.
+ *  3. A standard body slot rendered as a `<Stack>` so children stack with
+ *     consistent vertical rhythm.
+ *
+ * Use PageContainer at the top of every screen. Compose with `<Stack>` /
+ * `<Grid>` / `<Cluster>` inside. Never roll a per-screen wrapper.
+ */
+export function PageContainer({
+  title,
+  description,
+  actions,
+  maxWidth = '7xl',
+  paddingX = '6',
+  paddingY = '6',
+  gap = '6',
+  className = '',
+  children,
+  ...rest
+}: PageContainerProps) {
+  const outerClasses = [
+    'mx-auto w-full',
+    MAX_WIDTH_CLASS[maxWidth],
+    `px-${paddingX}`,
+    `py-${paddingY}`,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  return (
+    <section className={outerClasses} {...rest}>
+      <Stack space={gap}>
+        {(title || description || actions) && (
+          <header className="flex flex-col gap-3 md:flex-row md:items-start md:justify-between">
+            {(title || description) && (
+              <div className="min-w-0">
+                {title && (
+                  <h1 className="text-foreground truncate text-2xl font-semibold tracking-tight">
+                    {title}
+                  </h1>
+                )}
+                {description && <p className="text-muted-foreground mt-1 text-sm">{description}</p>}
+              </div>
+            )}
+            {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}
+          </header>
+        )}
+        {children}
+      </Stack>
+    </section>
+  )
+}