@actuate-media/cms-admin 0.10.0 → 0.11.0

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';