@prenta/admin 0.92.0

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="min-h-0 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,92 @@
+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">{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>
+  )
+}

package/src/layout/primitives/Split.tsx

@@ -0,0 +1,73 @@
+import type { HTMLAttributes, ReactNode, ElementType } from 'react'
+import type { SpaceToken } from './tokens.js'
+
+export interface SplitProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Fraction of the container the primary pane should take, expressed as
+   * a CSS fraction string. Defaults to `'2fr 1fr'` (primary 2x sidebar).
+   *
+   * @example
+   *   <Split fraction="3fr 1fr">         // 75% / 25%
+   *   <Split fraction="minmax(0, 1fr) 320px">  // fluid + fixed sidebar
+   */
+  fraction?: string
+  /** Gap between the two panes. */
+  space?: SpaceToken
+  /**
+   * Stack vertically at this breakpoint and below. Pass `false` to never
+   * stack. Defaults to `md` (stacks on screens narrower than 768px).
+   */
+  stackBelow?: 'sm' | 'md' | 'lg' | 'xl' | false
+  /** Reverse the order of children (sidebar first instead of second). */
+  reverse?: boolean
+  /** Render as a different element. */
+  as?: ElementType
+  children: [ReactNode, ReactNode]
+}
+
+const STACK_BELOW_CLASS = {
+  sm: 'sm:grid',
+  md: 'md:grid',
+  lg: 'lg:grid',
+  xl: 'xl:grid',
+} as const
+
+/**
+ * Two-pane split layout (primary + sidebar/aside) that collapses to a
+ * stacked layout below a configurable breakpoint. Use this for the
+ * document editor (`<Split fraction="minmax(0, 1fr) 320px">`), settings
+ * pages with a navigation rail, etc. — anywhere two panes need to live
+ * side-by-side at desktop widths and stack on mobile.
+ */
+export function Split({
+  fraction = '2fr 1fr',
+  space = '6',
+  stackBelow = 'md',
+  reverse,
+  as: Component = 'div',
+  className = '',
+  style,
+  children,
+  ...rest
+}: SplitProps) {
+  const stackClass =
+    stackBelow === false ? 'grid' : `flex flex-col ${STACK_BELOW_CLASS[stackBelow]}`
+  const classes = [stackClass, `gap-${space}`, reverse ? 'flex-col-reverse' : '', className]
+    .filter(Boolean)
+    .join(' ')
+
+  return (
+    <Component
+      className={classes}
+      style={{
+        ...(stackBelow === false
+          ? { gridTemplateColumns: fraction }
+          : { gridTemplateColumns: fraction }),
+        ...style,
+      }}
+      {...rest}
+    >
+      {children}
+    </Component>
+  )
+}

package/src/layout/primitives/Stack.tsx

@@ -0,0 +1,67 @@
+import type { HTMLAttributes, ReactNode, ElementType } from 'react'
+import type { SpaceToken } from './tokens.js'
+
+export type StackSpace = SpaceToken
+
+export interface StackProps extends HTMLAttributes<HTMLElement> {
+  /** Vertical gap between children. Maps to Tailwind `gap-{space}`. */
+  space?: StackSpace
+  /** Render as a different element (e.g. `<section>`, `<article>`). Defaults to `div`. */
+  as?: ElementType
+  /** Center children horizontally (sets `items-center`). */
+  align?: 'start' | 'center' | 'end' | 'stretch'
+  /** Distribute vertical space (sets `justify-{value}`). */
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'
+  /** Stretch the stack to fill its parent's height. */
+  fill?: boolean
+  children?: ReactNode
+}
+
+const ALIGN_CLASS: Record<NonNullable<StackProps['align']>, string> = {
+  start: 'items-start',
+  center: 'items-center',
+  end: 'items-end',
+  stretch: 'items-stretch',
+}
+
+const JUSTIFY_CLASS: Record<NonNullable<StackProps['justify']>, string> = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+  between: 'justify-between',
+  around: 'justify-around',
+  evenly: 'justify-evenly',
+}
+
+/**
+ * Vertical stack with a consistent gap between children. This is the
+ * single sanctioned way to space block-level elements in the admin —
+ * never reach for `space-y-*` directly.
+ */
+export function Stack({
+  space = '4',
+  as: Component = 'div',
+  align,
+  justify,
+  fill,
+  className = '',
+  children,
+  ...rest
+}: StackProps) {
+  const classes = [
+    'flex flex-col',
+    `gap-${space}`,
+    align ? ALIGN_CLASS[align] : '',
+    justify ? JUSTIFY_CLASS[justify] : '',
+    fill ? 'h-full' : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  return (
+    <Component className={classes} {...rest}>
+      {children}
+    </Component>
+  )
+}

package/src/layout/primitives/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Layout primitives for the Prenta admin.
+ *
+ * These exist so views never hand-roll their own flex/grid scaffolding.
+ * Every admin view should compose these primitives instead of writing raw
+ * Tailwind classes for spacing/alignment/structure. That contract is what
+ * keeps layout bugs (sidebar overlap, breakpoint mismatches, missing
+ * `min-w-0`) from recurring in new views.
+ *
+ * Naming follows the "Every Layout" canon
+ * (https://every-layout.dev/) plus our own `AdminShell` and
+ * `PageContainer` for the admin-specific outer chrome.
+ */
+export { AdminShell } from './AdminShell.js'
+export type { AdminShellProps } from './AdminShell.js'
+
+export { PageContainer } from './PageContainer.js'
+export type { PageContainerProps } from './PageContainer.js'
+
+export { Stack } from './Stack.js'
+export type { StackProps, StackSpace } from './Stack.js'
+
+export { Cluster } from './Cluster.js'
+export type { ClusterProps, ClusterAlign, ClusterJustify } from './Cluster.js'
+
+export { Grid } from './Grid.js'
+export type { GridProps, GridResponsive } from './Grid.js'
+
+export { Split } from './Split.js'
+export type { SplitProps } from './Split.js'
+
+export { Box } from './Box.js'
+export type { BoxProps } from './Box.js'
+
+export { tokens } from './tokens.js'
+export type { SpaceToken, RadiusToken } from './tokens.js'

package/src/layout/primitives/tokens.ts

@@ -0,0 +1,83 @@
+/**
+ * Design tokens — single source of truth for the admin design system.
+ *
+ * Tokens are surfaced both as TypeScript constants (for inline-style escape
+ * hatches) and via CSS custom properties in `styles/theme.css`. Always
+ * prefer the CSS variables in production code; the TS constants are for
+ * computed inline styles only (e.g. dynamic widths, computed grid sizes).
+ */
+
+export type SpaceToken =
+  | '0'
+  | 'px'
+  | '0.5'
+  | '1'
+  | '1.5'
+  | '2'
+  | '2.5'
+  | '3'
+  | '4'
+  | '5'
+  | '6'
+  | '8'
+  | '10'
+  | '12'
+  | '16'
+
+export type RadiusToken = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'
+
+/** Numeric pixel values for inline style escape hatches. */
+export const tokens = {
+  // Spacing scale matches Tailwind's default (--spacing = 0.25rem = 4px).
+  space: {
+    '0': 0,
+    px: 1,
+    '0.5': 2,
+    '1': 4,
+    '1.5': 6,
+    '2': 8,
+    '2.5': 10,
+    '3': 12,
+    '4': 16,
+    '5': 20,
+    '6': 24,
+    '8': 32,
+    '10': 40,
+    '12': 48,
+    '16': 64,
+  } as const satisfies Record<SpaceToken, number>,
+
+  radius: {
+    none: 0,
+    sm: 6,
+    md: 8,
+    lg: 10,
+    xl: 12,
+    full: 99,
+  } as const satisfies Record<RadiusToken, number>,
+
+  /** Layout dimensions from the design system (px). */
+  layout: {
+    sidebarWidth: 224,
+    sidebarWidthCollapsed: 60,
+    topbarHeight: 56,
+  } as const,
+
+  // Breakpoints mirror Tailwind defaults so primitives can compose with
+  // utility classes without surprises. Use `matchMedia(`(min-width: …`)` to
+  // sync JS-driven layout decisions with these values.
+  breakpoint: {
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    '2xl': 1536,
+  } as const,
+}
+
+/** Map a space token to the corresponding Tailwind `space-y-*` / `gap-*` value. */
+export function spaceToTw(t: SpaceToken): string {
+  // Tailwind's spacing utility already accepts the same scale, so we map
+  // 1:1. Centralizing here means callers don't repeat the string literal.
+  return t
+}