@nestledjs/data-browser 0.1.0

package/src/lib/components/shared/AdminStatusDisplay.tsx

@@ -0,0 +1,292 @@
+import React from 'react'
+import { 
+  CheckCircleIcon, 
+  XCircleIcon, 
+  ExclamationTriangleIcon, 
+  ClockIcon,
+  QuestionMarkCircleIcon,
+  PauseCircleIcon,
+} from '@heroicons/react/24/solid'
+
+export type StatusType = 
+  | 'active' 
+  | 'inactive' 
+  | 'pending' 
+  | 'approved' 
+  | 'rejected' 
+  | 'warning' 
+  | 'error' 
+  | 'success' 
+  | 'paused' 
+  | 'unknown'
+
+export type StatusSize = 'small' | 'medium' | 'large'
+export type StatusVariant = 'badge' | 'pill' | 'dot' | 'full'
+
+export interface AdminStatusDisplayProps {
+  readonly status: StatusType
+  readonly label?: string
+  readonly size?: StatusSize
+  readonly variant?: StatusVariant
+  readonly showIcon?: boolean
+  readonly className?: string
+  readonly onClick?: () => void
+  readonly tooltip?: string
+}
+
+export interface AdminUserStatusProps {
+  readonly status: 'online' | 'offline' | 'away' | 'busy'
+  readonly showLabel?: boolean
+  readonly size?: StatusSize
+  readonly className?: string
+}
+
+interface StatusConfig {
+  icon: React.ComponentType<{ className?: string }>
+  bgColor: string
+  textColor: string
+  borderColor: string
+  defaultLabel: string
+}
+
+// Extract status configuration logic
+const getStatusConfig = (status: StatusType): StatusConfig => {
+  const configs: Record<StatusType, StatusConfig> = {
+    active: {
+      icon: CheckCircleIcon,
+      bgColor: 'bg-green-100',
+      textColor: 'text-green-800',
+      borderColor: 'border-green-200',
+      defaultLabel: 'Active',
+    },
+    inactive: {
+      icon: XCircleIcon,
+      bgColor: 'bg-gray-100',
+      textColor: 'text-gray-800',
+      borderColor: 'border-gray-200',
+      defaultLabel: 'Inactive',
+    },
+    pending: {
+      icon: ClockIcon,
+      bgColor: 'bg-yellow-100',
+      textColor: 'text-yellow-800',
+      borderColor: 'border-yellow-200',
+      defaultLabel: 'Pending',
+    },
+    approved: {
+      icon: CheckCircleIcon,
+      bgColor: 'bg-green-100',
+      textColor: 'text-green-800',
+      borderColor: 'border-green-200',
+      defaultLabel: 'Approved',
+    },
+    rejected: {
+      icon: XCircleIcon,
+      bgColor: 'bg-red-100',
+      textColor: 'text-red-800',
+      borderColor: 'border-red-200',
+      defaultLabel: 'Rejected',
+    },
+    warning: {
+      icon: ExclamationTriangleIcon,
+      bgColor: 'bg-yellow-100',
+      textColor: 'text-yellow-800',
+      borderColor: 'border-yellow-200',
+      defaultLabel: 'Warning',
+    },
+    error: {
+      icon: XCircleIcon,
+      bgColor: 'bg-red-100',
+      textColor: 'text-red-800',
+      borderColor: 'border-red-200',
+      defaultLabel: 'Error',
+    },
+    success: {
+      icon: CheckCircleIcon,
+      bgColor: 'bg-green-100',
+      textColor: 'text-green-800',
+      borderColor: 'border-green-200',
+      defaultLabel: 'Success',
+    },
+    paused: {
+      icon: PauseCircleIcon,
+      bgColor: 'bg-blue-100',
+      textColor: 'text-blue-800',
+      borderColor: 'border-blue-200',
+      defaultLabel: 'Paused',
+    },
+    unknown: {
+      icon: QuestionMarkCircleIcon,
+      bgColor: 'bg-gray-100',
+      textColor: 'text-gray-800',
+      borderColor: 'border-gray-200',
+      defaultLabel: 'Unknown',
+    },
+  }
+
+  return configs[status]
+}
+
+// Extract size configuration logic
+const getSizeClasses = (size: StatusSize) => {
+  const sizeClasses = {
+    small: {
+      text: 'text-xs',
+      padding: 'px-2 py-1',
+      icon: 'h-3 w-3',
+      dot: 'h-2 w-2',
+    },
+    medium: {
+      text: 'text-sm',
+      padding: 'px-2.5 py-1.5',
+      icon: 'h-4 w-4',
+      dot: 'h-3 w-3',
+    },
+    large: {
+      text: 'text-base',
+      padding: 'px-3 py-2',
+      icon: 'h-5 w-5',
+      dot: 'h-4 w-4',
+    },
+  }
+
+  return sizeClasses[size]
+}
+
+// Extract variant styling logic
+const getVariantClasses = (variant: StatusVariant) => {
+  const variantClasses = {
+    badge: 'inline-flex items-center rounded border font-medium',
+    pill: 'inline-flex items-center rounded-full border font-medium',
+    dot: 'inline-flex items-center font-medium',
+    full: 'flex items-center justify-center rounded border font-medium w-full',
+  }
+
+  return variantClasses[variant]
+}
+
+// Extract user status configuration logic
+const getUserStatusConfig = (status: AdminUserStatusProps['status']) => {
+  const configs = {
+    online: {
+      color: 'bg-green-400',
+      label: 'Online',
+    },
+    offline: {
+      color: 'bg-gray-400',
+      label: 'Offline',
+    },
+    away: {
+      color: 'bg-yellow-400',
+      label: 'Away',
+    },
+    busy: {
+      color: 'bg-red-400',
+      label: 'Busy',
+    },
+  }
+
+  return configs[status]
+}
+
+export function AdminStatusDisplay({
+  status,
+  label,
+  size = 'medium',
+  variant = 'badge',
+  showIcon = true,
+  className = '',
+  onClick,
+  tooltip,
+}: Readonly<AdminStatusDisplayProps>) {
+  const config = getStatusConfig(status)
+  const sizeClasses = getSizeClasses(size)
+  const variantClasses = getVariantClasses(variant)
+  const IconComponent = config.icon
+  
+  const displayLabel = label || config.defaultLabel
+  
+  const shouldShowDot = variant === 'dot'
+  const shouldShowIcon = showIcon && !shouldShowDot
+  const isClickable = !!onClick
+  
+  const baseClasses = `${variantClasses} ${sizeClasses.text} ${sizeClasses.padding} ${config.bgColor} ${config.textColor} ${config.borderColor}`
+  const interactiveClasses = isClickable ? 'cursor-pointer hover:opacity-80' : ''
+  const finalClasses = `${baseClasses} ${interactiveClasses} ${className}`.trim()
+
+  const renderDot = () => {
+    if (!shouldShowDot) return null
+    
+    return (
+      <span className={`inline-block rounded-full mr-2 ${config.bgColor.replace('bg-', 'bg-').replace('-100', '-400')} ${sizeClasses.dot}`} />
+    )
+  }
+
+  const renderIcon = () => {
+    if (!shouldShowIcon) return null
+    
+    return (
+      <IconComponent className={`${sizeClasses.icon} ${displayLabel ? 'mr-1.5' : ''}`} />
+    )
+  }
+
+  const content = (
+    <>
+      {renderDot()}
+      {renderIcon()}
+      {displayLabel}
+    </>
+  )
+
+  const handleClick = () => {
+    if (onClick) {
+      onClick()
+    }
+  }
+
+  if (isClickable) {
+    return (
+      <button
+        type="button"
+        onClick={handleClick}
+        className={finalClasses}
+        title={tooltip}
+      >
+        {content}
+      </button>
+    )
+  }
+
+  return (
+    <span className={finalClasses} title={tooltip}>
+      {content}
+    </span>
+  )
+}
+
+export function AdminUserStatus({
+  status,
+  showLabel = false,
+  size = 'medium',
+  className = '',
+}: Readonly<AdminUserStatusProps>) {
+  const config = getUserStatusConfig(status)
+  const sizeClasses = getSizeClasses(size)
+
+  const dotSizeClass = sizeClasses.dot
+  const textSizeClass = showLabel ? sizeClasses.text : ''
+  
+  return (
+    <div className={`inline-flex items-center ${className}`}>
+      <span 
+        className={`inline-block rounded-full ${config.color} ${dotSizeClass}`}
+        aria-label={config.label}
+      />
+      {showLabel && (
+        <span className={`ml-2 text-gray-700 ${textSizeClass}`}>
+          {config.label}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/lib/components/shared/index.ts

@@ -0,0 +1,3 @@
+export * from './AdminBreadcrumbs'
+export * from './AdminErrorStates'
+export * from './AdminStatusDisplay'

package/src/lib/context/AdminDataContext.tsx

@@ -0,0 +1,74 @@
+import { createContext, useContext, type ReactNode } from 'react'
+
+export interface AdminDataContextValue {
+  /** The SDK namespace for dynamic GraphQL document lookups */
+  sdk: any
+  /** Array of database models from Prisma schema */
+  databaseModels: any[]
+  /** Base path for admin data routes (e.g., "/admin/data") */
+  basePath?: string
+  /** Form theme configuration for @nestledjs/forms */
+  formTheme: any
+}
+
+const AdminDataContext = createContext<AdminDataContextValue | null>(null)
+
+export interface AdminDataProviderProps {
+  children: ReactNode
+  /** The entire SDK namespace (e.g., import * as Sdk from '@your-project/shared/sdk') */
+  sdk: any
+  /** DATABASE_MODELS array from your SDK */
+  databaseModels: any[]
+  /** Optional base path for routes (defaults to "/admin/data") */
+  basePath?: string
+  /** Form theme configuration for @nestledjs/forms */
+  formTheme: any
+}
+
+/**
+ * Provider component that supplies SDK and database models to admin data components
+ *
+ * @example
+ * ```tsx
+ * import * as Sdk from '@your-project/shared/sdk'
+ * import { DATABASE_MODELS } from '@your-project/shared/sdk'
+ * import { AdminDataProvider } from '@nestledjs/admin-data'
+ *
+ * <AdminDataProvider
+ *   sdk={Sdk}
+ *   databaseModels={DATABASE_MODELS}
+ *   formTheme={formTheme}
+ *   basePath="/admin/data"
+ * >
+ *   <AdminDataLayout />
+ * </AdminDataProvider>
+ * ```
+ */
+export function AdminDataProvider({
+  children,
+  sdk,
+  databaseModels,
+  basePath = '/admin/data',
+  formTheme
+}: AdminDataProviderProps) {
+  return (
+    <AdminDataContext.Provider value={{ sdk, databaseModels, basePath, formTheme }}>
+      {children}
+    </AdminDataContext.Provider>
+  )
+}
+
+/**
+ * Hook to access the admin data context
+ * @throws Error if used outside of AdminDataProvider
+ */
+export function useAdminDataContext() {
+  const context = useContext(AdminDataContext)
+  if (!context) {
+    throw new Error(
+      'useAdminDataContext must be used within AdminDataProvider. ' +
+      'Make sure to wrap your admin data routes with <AdminDataProvider>.'
+    )
+  }
+  return context
+}

package/src/lib/hooks/useAdminList.ts

@@ -0,0 +1,42 @@
+import { useReducer } from 'react'
+import { AdminListAction, AdminListState, initialState } from '../types'
+
+// State reducer for performance optimization
+function adminListReducer(state: AdminListState, action: AdminListAction): AdminListState {
+  switch (action.type) {
+    case 'SET_SEARCH':
+      return { ...state, search: action.payload }
+    case 'SET_DEBOUNCED_SEARCH':
+      return { ...state, debouncedSearch: action.payload }
+    case 'SET_SKIP':
+      return { ...state, skip: action.payload }
+    case 'SET_PAGE_SIZE':
+      return { ...state, pageSize: action.payload }
+    case 'SET_SORT':
+      return { ...state, sort: action.payload }
+    case 'SET_VISIBLE_COLUMNS':
+      return { ...state, visibleColumns: action.payload }
+    case 'TOGGLE_COLUMN_SELECTOR':
+      return { ...state, showColumnSelector: !state.showColumnSelector }
+    case 'SET_SEARCH_FIELDS':
+      return { ...state, searchFields: action.payload }
+    case 'TOGGLE_SEARCH_FIELD_SELECTOR':
+      return { ...state, showSearchFieldSelector: !state.showSearchFieldSelector }
+    case 'SET_FILTERS':
+      return { ...state, filters: action.payload }
+    case 'TOGGLE_FILTERS':
+      return { ...state, showFilters: !state.showFilters }
+    case 'RESET_PAGINATION':
+      return { ...state, skip: 0 }
+    case 'RESET_FILTERS':
+      return { ...state, filters: {} }
+    default:
+      return state
+  }
+}
+
+export function useAdminList() {
+  const [state, dispatch] = useReducer(adminListReducer, initialState)
+  
+  return { state, dispatch }
+}

package/src/lib/hooks/useClickOutside.ts

@@ -0,0 +1,21 @@
+import React, { useEffect } from 'react'
+
+// Custom hook for click outside detection
+export function useClickOutside(
+  ref: React.RefObject<HTMLDivElement | null>, 
+  handler: () => void, 
+  isActive = true
+) {
+  useEffect(() => {
+    if (!isActive) return
+
+    const handleClickOutside = (event: MouseEvent) => {
+      if (ref.current && !ref.current.contains(event.target as Node)) {
+        handler()
+      }
+    }
+
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [handler, isActive]) // Removed 'ref' from dependency array as refs are stable
+}

package/src/lib/hooks/useDebounce.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from 'react'
+
+// Custom hook for debouncing values
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value)
+    }, delay)
+
+    return () => clearTimeout(timer)
+  }, [value, delay])
+
+  return debouncedValue
+}

package/src/lib/hooks/useRelationData.ts

@@ -0,0 +1,114 @@
+import { useQuery } from '@apollo/client/react'
+import { useMemo } from 'react'
+import { useAdminDataContext } from '../context/AdminDataContext'
+import { getAdminDocuments } from '../utils/graphql-utils'
+import { getSmartSearchFields } from '../utils/string-utils'
+import { useDebounce } from './useDebounce'
+
+// Custom hook for relation data fetching and management
+export function useRelationData(relatedModelName: string, searchTerm: string, isOpen: boolean) {
+  const { sdk, databaseModels } = useAdminDataContext()
+  const debouncedSearchTerm = useDebounce(searchTerm, 300)
+
+  // Get the related model and its GraphQL documents
+  const relatedModel = useMemo(
+    () => databaseModels.find((m: any) => m.name === relatedModelName),
+    [databaseModels, relatedModelName],
+  )
+
+  const relatedDocuments = useMemo(
+    () => (relatedModel ? getAdminDocuments(sdk, relatedModel) : { listQuery: undefined }),
+    [sdk, relatedModel],
+  )
+
+  const relatedDataPath = useMemo(
+    () =>
+      relatedModel?.pluralModelPropertyName ||
+      relatedModelName.charAt(0).toLowerCase() + relatedModelName.slice(1) + 's',
+    [relatedModel, relatedModelName],
+  )
+
+  // Get searchable fields for the related model
+  const searchableFields = useMemo(() => {
+    if (!relatedModel) return []
+
+    return relatedModel.fields
+      .filter((f: any) => {
+        const fieldType = f.type.toLowerCase()
+        return (
+          !f.relationName &&
+          (fieldType === 'string' || fieldType.includes('text') || fieldType === 'boolean')
+        )
+      })
+      .map((f: any) => f.name)
+  }, [relatedModel])
+
+  const searchFields = useMemo(() => getSmartSearchFields(searchableFields), [searchableFields])
+
+  // Query variables for relation search
+  const queryVariables = useMemo(
+    () => ({
+      input: {
+        take: 20,
+        ...(debouncedSearchTerm.trim()
+          ? {
+              search: debouncedSearchTerm,
+              searchFields: searchFields.length > 0 ? searchFields : undefined,
+            }
+          : {}),
+      },
+    }),
+    [debouncedSearchTerm, searchFields],
+  )
+
+  // Query for related items with comprehensive error handling
+  const {
+    data: relatedData,
+    loading,
+    error: relationError,
+  } = useQuery(relatedDocuments.listQuery, {
+    variables: queryVariables,
+    skip: !relatedDocuments.listQuery || !isOpen,
+    errorPolicy: 'all', // Continue processing even if there are GraphQL errors
+    notifyOnNetworkStatusChange: true,
+    fetchPolicy: 'cache-first', // Use cache for better performance
+  })
+
+  // Validate and sanitize relation data
+  const relatedItems = useMemo(() => {
+    if (relationError) {
+      console.warn('[RelationData] GraphQL error:', relationError.message)
+      return []
+    }
+
+    if (!relatedData) return []
+
+    try {
+      const items = (relatedData as any)[relatedDataPath] || []
+
+      // Validate that items is an array
+      if (!Array.isArray(items)) {
+        console.warn('[RelationData] Expected array but got:', typeof items)
+        return []
+      }
+
+      // Validate each item has required properties
+      return items.filter(item => {
+        if (!item || typeof item !== 'object') return false
+        if (!item.id) return false // Require ID field
+        return true
+      })
+    } catch (error) {
+      console.error('[RelationData] Error processing relation data:', error)
+      return []
+    }
+  }, [relatedData, relatedDataPath, relationError])
+
+  return {
+    relatedModel,
+    relatedItems,
+    loading,
+    error: relationError,
+    hasDocument: !!relatedDocuments.listQuery,
+  }
+}