@orion-studios/payload-admin-components 0.1.0 → 0.2.0-beta.1

package/src/helpers/configureAdmin.ts

@@ -0,0 +1,122 @@
+import type { CollectionConfig, GlobalConfig } from 'payload'
+import { themePreferenceField } from '../fields/themePreference'
+
+export interface AdminConfig {
+  brandName: string
+  brandPrimary?: string
+  brandSecondary?: string
+  logoUrl?: string
+}
+
+/**
+ * Generates Payload admin configuration with Orion Studios admin components.
+ *
+ * Usage:
+ * ```ts
+ * import { configureAdmin } from '@orion-studios/payload-admin-components'
+ *
+ * const adminConfig = configureAdmin({
+ *   brandName: 'My Site',
+ *   brandPrimary: '#2d5016',
+ *   brandSecondary: '#8B4513',
+ * })
+ *
+ * export default buildConfig({
+ *   admin: { ...adminConfig.admin },
+ *   collections: [adminConfig.wrapUsers(Users), Media, Pages],
+ *   globals: adminConfig.wrapGlobals([SiteSettings, Header, Footer]),
+ * })
+ * ```
+ */
+export function configureAdmin(config: AdminConfig) {
+  const { brandName, brandPrimary, brandSecondary } = config
+
+  // Build CSS string to inject brand colors
+  const brandCssVars = [
+    brandPrimary ? `--brand-primary: ${brandPrimary};` : '',
+    brandSecondary ? `--brand-secondary: ${brandSecondary};` : '',
+  ]
+    .filter(Boolean)
+    .join('\n  ')
+
+  return {
+    admin: {
+      components: {
+        graphics: {
+          Logo: {
+            exportName: 'Logo',
+            path: '@orion-studios/payload-admin-components',
+          },
+          Icon: {
+            exportName: 'Icon',
+            path: '@orion-studios/payload-admin-components',
+          },
+        },
+        views: {
+          dashboard: {
+            Component: {
+              exportName: 'Dashboard',
+              path: '@orion-studios/payload-admin-components',
+            },
+          },
+        },
+        providers: [
+          {
+            exportName: 'ThemeProvider',
+            path: '@orion-studios/payload-admin-components',
+          },
+        ],
+        afterNavLinks: [
+          {
+            exportName: 'ThemeSwitcher',
+            path: '@orion-studios/payload-admin-components',
+          },
+        ],
+      },
+      meta: {
+        titleSuffix: ` — ${brandName}`,
+      },
+    },
+
+    brandName,
+    brandPrimary: brandPrimary || '#3b82f6',
+    brandSecondary: brandSecondary || '#8b5cf6',
+    brandCssVars,
+
+    /**
+     * Wraps the Users collection to add theme preference field.
+     */
+    wrapUsers(usersCollection: CollectionConfig): CollectionConfig {
+      return {
+        ...usersCollection,
+        fields: [...(usersCollection.fields || []), themePreferenceField],
+      }
+    },
+
+    /**
+     * Wraps globals with intuitive group labels.
+     * Maps common global slugs to the "Site Design" group with user-friendly labels.
+     */
+    wrapGlobals(globals: GlobalConfig[]): GlobalConfig[] {
+      const labelMap: Record<string, { group: string; label: string }> = {
+        header: { group: 'Site Design', label: 'Header & Navigation' },
+        footer: { group: 'Site Design', label: 'Footer' },
+        'site-settings': { group: 'Site Design', label: 'Website Settings' },
+      }
+
+      return globals.map((global) => {
+        const mapping = labelMap[global.slug]
+        if (!mapping) return global
+
+        return {
+          ...global,
+          admin: {
+            ...global.admin,
+            group: mapping.group,
+          },
+          label: mapping.label,
+        }
+      })
+    },
+  }
+}

package/src/helpers/withTooltips.ts

@@ -0,0 +1,91 @@
+import type { Field } from 'payload'
+
+/**
+ * Default tooltip descriptions for common Payload CMS field names.
+ * These provide helpful context for non-technical users.
+ */
+const defaultTooltips: Record<string, string> = {
+  title: 'The main title displayed on this page.',
+  slug: 'The URL-friendly name for this page (e.g., "about-us"). This appears in the web address.',
+  template: 'Choose a layout template. This controls the overall structure of the page.',
+  parent: 'Select a parent page to nest this page under. This affects the URL path.',
+  path: 'The full URL path for this page. This is automatically generated from the slug and parent.',
+  layout: 'Add and arrange content sections on your page. Each section is a building block.',
+  metaTitle: 'The title shown in search engine results and browser tabs. Keep under 60 characters.',
+  metaDescription: 'A brief summary shown in search results. Keep under 160 characters for best results.',
+  canonicalUrl: 'The preferred URL for this page. Used to prevent duplicate content in search engines.',
+  ogImage: 'The image shown when this page is shared on social media (Facebook, LinkedIn, etc.).',
+  noIndex: 'When enabled, search engines will not list this page in results.',
+  noFollow: 'When enabled, search engines will not follow links on this page.',
+  publishedAt: 'The date and time this page was first published.',
+  alt: 'Describe this image for screen readers and search engines. Be specific and concise.',
+  navItems: 'The links shown in your website\'s navigation menu.',
+  copyright: 'The copyright text displayed in your website footer.',
+  contactEmail: 'The email address displayed in your footer and contact sections.',
+  contactPhone: 'The phone number displayed in your footer and contact sections.',
+  siteName: 'Your website\'s name. Appears in browser tabs and search results.',
+  tagline: 'A short phrase describing your business. Used in SEO and site metadata.',
+  canonicalBaseUrl: 'The base URL of your website (e.g., "https://example.com"). Used for generating canonical URLs.',
+}
+
+/**
+ * Adds tooltip descriptions to Payload fields by matching field names
+ * to a tooltip map. This enriches the admin UI with contextual help.
+ *
+ * Usage:
+ * ```ts
+ * const fields = withTooltips(myFields, {
+ *   // Optional: override or add custom tooltips
+ *   myCustomField: 'Explanation of what this field does',
+ * })
+ * ```
+ */
+export function withTooltips(
+  fields: Field[],
+  customTooltips?: Record<string, string>,
+): Field[] {
+  const tooltips = { ...defaultTooltips, ...customTooltips }
+
+  return fields.map((field) => addTooltipToField(field, tooltips))
+}
+
+function addTooltipToField(field: Field, tooltips: Record<string, string>): Field {
+  // Handle fields with a name property
+  if ('name' in field && field.name && tooltips[field.name]) {
+    const tooltip = tooltips[field.name]
+    const admin = (field as any).admin
+
+    // Only add description if one doesn't already exist
+    if (!admin?.description) {
+      return {
+        ...field,
+        admin: {
+          ...admin,
+          description: tooltip,
+        },
+      } as Field
+    }
+  }
+
+  // Recurse into nested field types
+  if ('fields' in field && Array.isArray((field as any).fields)) {
+    return {
+      ...field,
+      fields: (field as any).fields.map((f: Field) => addTooltipToField(f, tooltips)),
+    } as Field
+  }
+
+  if ('tabs' in field && Array.isArray((field as any).tabs)) {
+    return {
+      ...field,
+      tabs: (field as any).tabs.map((tab: any) => ({
+        ...tab,
+        fields: tab.fields
+          ? tab.fields.map((f: Field) => addTooltipToField(f, tooltips))
+          : tab.fields,
+      })),
+    } as Field
+  }
+
+  return field
+}

package/src/hooks/useTheme.ts

@@ -0,0 +1,128 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export type ThemeOption = 'light' | 'dark' | 'brand-light' | 'brand-dark'
+
+const STORAGE_KEY = 'orion-admin-theme'
+const DEFAULT_THEME: ThemeOption = 'light'
+
+function applyTheme(theme: ThemeOption) {
+  document.documentElement.setAttribute('data-theme', theme)
+}
+
+function getCachedTheme(): ThemeOption | null {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY)
+    if (stored && ['light', 'dark', 'brand-light', 'brand-dark'].includes(stored)) {
+      return stored as ThemeOption
+    }
+  } catch {
+    // localStorage not available
+  }
+  return null
+}
+
+function cacheTheme(theme: ThemeOption) {
+  try {
+    localStorage.setItem(STORAGE_KEY, theme)
+  } catch {
+    // localStorage not available
+  }
+}
+
+export function useTheme() {
+  const [theme, setThemeState] = useState<ThemeOption>(() => {
+    if (typeof window === 'undefined') return DEFAULT_THEME
+    return getCachedTheme() || DEFAULT_THEME
+  })
+  const [isLoading, setIsLoading] = useState(true)
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const userIdRef = useRef<string | null>(null)
+
+  // On mount: apply cached theme immediately, then sync from DB
+  useEffect(() => {
+    const cached = getCachedTheme()
+    if (cached) {
+      applyTheme(cached)
+      setThemeState(cached)
+    } else {
+      applyTheme(DEFAULT_THEME)
+    }
+
+    // Fetch user's preference from DB
+    fetch('/api/users/me', { credentials: 'include' })
+      .then((res) => res.json())
+      .then((data) => {
+        const user = data?.user || data
+        if (user?.id) {
+          userIdRef.current = user.id
+        }
+        if (user?.themePreference) {
+          const dbTheme = user.themePreference as ThemeOption
+          setThemeState(dbTheme)
+          applyTheme(dbTheme)
+          cacheTheme(dbTheme)
+        }
+      })
+      .catch(() => {
+        // Silently fail - use cached/default theme
+      })
+      .finally(() => {
+        setIsLoading(false)
+      })
+  }, [])
+
+  const setTheme = useCallback((newTheme: ThemeOption) => {
+    setThemeState(newTheme)
+    applyTheme(newTheme)
+    cacheTheme(newTheme)
+
+    // Debounced DB write
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current)
+    }
+    debounceRef.current = setTimeout(() => {
+      const userId = userIdRef.current
+      if (!userId) return
+
+      fetch(`/api/users/${userId}`, {
+        method: 'PATCH',
+        credentials: 'include',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ themePreference: newTheme }),
+      }).catch(() => {
+        // Silently fail - local state is already updated
+      })
+    }, 300)
+  }, [])
+
+  const isDark = theme === 'dark' || theme === 'brand-dark'
+  const isBrand = theme === 'brand-light' || theme === 'brand-dark'
+
+  const toggleDarkMode = useCallback(() => {
+    if (isBrand) {
+      setTheme(isDark ? 'brand-light' : 'brand-dark')
+    } else {
+      setTheme(isDark ? 'light' : 'dark')
+    }
+  }, [isDark, isBrand, setTheme])
+
+  const toggleBrandMode = useCallback(() => {
+    if (isBrand) {
+      setTheme(isDark ? 'dark' : 'light')
+    } else {
+      setTheme(isDark ? 'brand-dark' : 'brand-light')
+    }
+  }, [isDark, isBrand, setTheme])
+
+  return {
+    theme,
+    setTheme,
+    isDark,
+    isBrand,
+    isLoading,
+    toggleDarkMode,
+    toggleBrandMode,
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Components
+export { Logo } from './components/Logo'
+export { Icon } from './components/Icon'
+export { Dashboard } from './components/Dashboard'
+export { ThemeSwitcher, ThemeProvider } from './components/ThemeSwitcher'
+export { HelpTooltip } from './components/HelpTooltip'
+export { StatusBadge } from './components/StatusBadge'
+export { EmptyState } from './components/EmptyState'
+export { BlockPicker } from './components/BlockPicker'
+export { SectionTabs } from './components/SectionTabs'
+export { WelcomeHeader } from './components/WelcomeHeader'
+
+// Helpers
+export { configureAdmin } from './helpers/configureAdmin'
+export type { AdminConfig } from './helpers/configureAdmin'
+export { withTooltips } from './helpers/withTooltips'
+
+// Hooks
+export { useTheme } from './hooks/useTheme'
+export type { ThemeOption } from './hooks/useTheme'
+
+// Fields
+export { themePreferenceField } from './fields/themePreference'
+
+// CSS styles are exported via package.json exports map
+// Import in your payload.config.ts:
+// css: require.resolve('@orion-studios/payload-admin-components/dist/admin.css')

package/src/styles/admin.css

@@ -1,8 +1,7 @@
 /**
- * Custom admin panel styles
- *
- * Override Payload's default CSS variables to match your brand
+ * Orion Studios Admin Theme System
  *
+ * Import all theme files and overrides.
  * Usage in payload.config.ts:
  * export default buildConfig({
  *   admin: {
@@ -11,64 +10,76 @@
  * })
  */
 
+/* Default brand colors (overridden by configureAdmin) */
 :root {
-  /* Brand colors - customize these */
   --brand-primary: #3b82f6;
-  --brand-primary-dark: #2563eb;
-  --brand-primary-light: #60a5fa;
-
-  /* Override Payload theme colors */
-  --theme-bg: #ffffff;
-  --theme-elevation-50: #f9fafb;
-  --theme-elevation-100: #f3f4f6;
-  --theme-elevation-150: #e5e7eb;
-  --theme-elevation-200: #d1d5db;
-  --theme-elevation-300: #9ca3af;
-  --theme-elevation-400: #6b7280;
-  --theme-elevation-500: #4b5563;
-  --theme-elevation-600: #374151;
-  --theme-elevation-700: #1f2937;
-  --theme-elevation-800: #111827;
-  --theme-elevation-900: #030712;
-
-  /* Text colors */
-  --theme-text: #111827;
-  --theme-text-muted: #6b7280;
-
-  /* Success/warning/error colors */
-  --theme-success-50: #f0fdf4;
-  --theme-success-500: #22c55e;
-  --theme-success-600: #16a34a;
-
-  --theme-warning-50: #fffbeb;
-  --theme-warning-500: #f59e0b;
-  --theme-warning-600: #d97706;
-
-  --theme-error-50: #fef2f2;
-  --theme-error-500: #ef4444;
-  --theme-error-600: #dc2626;
-
-  /* Use brand color for primary actions */
-  --theme-input-border-color: var(--brand-primary);
+  --brand-secondary: #8b5cf6;
 }
 
-/* Make buttons use brand color */
-button[type="submit"],
-.btn--style-primary {
-  background-color: var(--brand-primary) !important;
-}
+/* Theme files */
+@import './themes/light.css';
+@import './themes/dark.css';
+@import './themes/brand-light.css';
+@import './themes/brand-dark.css';
 
-button[type="submit"]:hover,
-.btn--style-primary:hover {
-  background-color: var(--brand-primary-dark) !important;
-}
-
-/* Customize the sidebar */
-.nav {
-  background-color: var(--theme-elevation-50);
-}
+/* Payload UI overrides */
+@import './overrides.css';
 
-/* Add smooth transitions */
-* {
-  transition: background-color 0.15s ease, border-color 0.15s ease;
+/* Default to light theme when no data-theme attribute is set */
+:root:not([data-theme]) {
+  --admin-bg: #ffffff;
+  --admin-surface: #f9fafb;
+  --admin-surface-elevated: #ffffff;
+  --admin-border: #e5e7eb;
+  --admin-border-subtle: #f3f4f6;
+  --admin-text: #111827;
+  --admin-text-secondary: #4b5563;
+  --admin-text-muted: #9ca3af;
+  --admin-text-inverse: #ffffff;
+  --admin-accent: #3b82f6;
+  --admin-accent-hover: #2563eb;
+  --admin-accent-subtle: #eff6ff;
+  --admin-accent-secondary: #8b5cf6;
+  --admin-accent-secondary-hover: #7c3aed;
+  --admin-accent-secondary-subtle: #f5f3ff;
+  --admin-nav-bg: #f8fafc;
+  --admin-nav-text: #374151;
+  --admin-nav-text-active: #111827;
+  --admin-nav-item-hover: #f1f5f9;
+  --admin-nav-item-active: #e0e7ff;
+  --admin-nav-group-text: #6b7280;
+  --admin-nav-border: #e2e8f0;
+  --admin-input-bg: #ffffff;
+  --admin-input-border: #d1d5db;
+  --admin-input-border-focus: var(--admin-accent);
+  --admin-input-placeholder: #9ca3af;
+  --admin-card-bg: #ffffff;
+  --admin-card-border: #e5e7eb;
+  --admin-card-shadow: 0 1px 3px rgba(0, 0, 0, 0.06), 0 1px 2px rgba(0, 0, 0, 0.04);
+  --admin-card-shadow-hover: 0 4px 12px rgba(0, 0, 0, 0.08), 0 2px 4px rgba(0, 0, 0, 0.04);
+  --admin-success: #16a34a;
+  --admin-success-bg: #f0fdf4;
+  --admin-warning: #d97706;
+  --admin-warning-bg: #fffbeb;
+  --admin-error: #dc2626;
+  --admin-error-bg: #fef2f2;
+  --admin-info: #0284c7;
+  --admin-info-bg: #f0f9ff;
+  --admin-tooltip-bg: #1f2937;
+  --admin-tooltip-text: #f9fafb;
+  --admin-overlay: rgba(0, 0, 0, 0.3);
+  --admin-scrollbar-track: #f1f5f9;
+  --admin-scrollbar-thumb: #cbd5e1;
+  --admin-scrollbar-thumb-hover: #94a3b8;
+  --admin-focus-ring: 0 0 0 2px #eff6ff, 0 0 0 4px #3b82f6;
+  --admin-radius-sm: 6px;
+  --admin-radius-md: 8px;
+  --admin-radius-lg: 12px;
+  --admin-radius-xl: 16px;
+  --admin-badge-draft-bg: #fef3c7;
+  --admin-badge-draft-text: #92400e;
+  --admin-badge-published-bg: #dcfce7;
+  --admin-badge-published-text: #166534;
+  --admin-badge-changed-bg: #dbeafe;
+  --admin-badge-changed-text: #1e40af;
 }