@actuate-media/cms-admin 0.9.0 → 0.11.0

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

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 Actuate 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,76 @@
+/**
+ * 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: 2,
+    md: 6,
+    lg: 8,
+    xl: 12,
+    full: 9999,
+  } as const satisfies Record<RadiusToken, number>,
+
+  // 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
+}

package/src/lib/cv.ts

@@ -0,0 +1,96 @@
+import clsx from 'clsx'
+
+/**
+ * Tiny in-house implementation of the `class-variance-authority` pattern
+ * (a.k.a. `cva` / `tailwind-variants`). We roll our own to avoid a runtime
+ * dependency while keeping the API surface compatible with the shadcn /
+ * cva ecosystem — anyone familiar with cva can read these calls.
+ *
+ * @example
+ *   const button = cv('inline-flex items-center', {
+ *     variants: {
+ *       intent: {
+ *         primary: 'bg-primary text-white',
+ *         secondary: 'bg-secondary text-foreground',
+ *       },
+ *       size: {
+ *         sm: 'px-2 py-1 text-xs',
+ *         md: 'px-4 py-2 text-sm',
+ *       },
+ *     },
+ *     defaultVariants: { intent: 'primary', size: 'md' },
+ *   })
+ *
+ *   button({ intent: 'secondary' })           // -> "inline-flex … bg-secondary …"
+ *   button({ intent: 'secondary', class: 'shadow' })  // append extras
+ */
+
+type ClassValue = string | undefined | false | null
+
+export type VariantsConfig = Record<string, Record<string, ClassValue>>
+
+type VariantSelection<V extends VariantsConfig> = {
+  [K in keyof V]?: keyof V[K]
+}
+
+interface CompoundVariant<V extends VariantsConfig> {
+  // Subset of variants that must match for the compound classes to apply.
+  // Use string values from each variant key (or arrays for "match any").
+  [key: string]: keyof V[keyof V] | Array<keyof V[keyof V]> | ClassValue
+  class?: ClassValue
+}
+
+export interface CvConfig<V extends VariantsConfig> {
+  variants: V
+  defaultVariants?: VariantSelection<V>
+  compoundVariants?: Array<CompoundVariant<V>>
+}
+
+export type VariantProps<F extends (...args: any) => any> = Omit<
+  NonNullable<Parameters<F>[0]>,
+  'class' | 'className'
+>
+
+/**
+ * Build a variant-aware class generator.
+ *
+ * The returned function accepts the variant selection plus an optional
+ * `class` / `className` escape hatch and returns the combined Tailwind
+ * class string. Compound variants run after the base + per-variant
+ * classes, so they take precedence when the Tailwind ordering matters.
+ */
+export function cv<V extends VariantsConfig>(base: ClassValue, config: CvConfig<V>) {
+  return function variantClass(
+    props?: VariantSelection<V> & { class?: ClassValue; className?: ClassValue },
+  ): string {
+    const selected = { ...config.defaultVariants, ...props } as Record<string, unknown>
+
+    const variantClasses: ClassValue[] = []
+    for (const [key, valuesMap] of Object.entries(config.variants)) {
+      const value = selected[key]
+      if (value === undefined || value === null) continue
+      const cls = valuesMap[value as string]
+      if (cls) variantClasses.push(cls)
+    }
+
+    const compoundClasses: ClassValue[] = []
+    if (config.compoundVariants) {
+      for (const compound of config.compoundVariants) {
+        const { class: cClass, className: _cn, ...match } = compound as any
+        const matches = Object.entries(match).every(([k, v]) => {
+          const current = selected[k]
+          if (Array.isArray(v)) return (v as unknown[]).includes(current)
+          return current === v
+        })
+        if (matches && cClass) compoundClasses.push(cClass as ClassValue)
+      }
+    }
+
+    return clsx(
+      base,
+      ...variantClasses,
+      ...compoundClasses,
+      (props?.class ?? props?.className) as ClassValue,
+    )
+  }
+}

package/src/styles/build-input.css

@@ -7,5 +7,5 @@
  *   import '@actuate-media/cms-admin/styles/precompiled.css'
  */
 @import 'tailwindcss';
-@source "../../src/**/*.{ts,tsx}";
+@source '../../src/**/*.{ts,tsx}';
 @import './theme.css';