canopycms 0.0.0

package/src/editor/group-manager/hooks/useGroupState.ts

@@ -0,0 +1,134 @@
+/**
+ * Hook for managing internal group state
+ */
+
+import { useState, useEffect, useCallback } from 'react'
+import type { InternalGroup, CanopyGroupId, CanopyUserId } from '../types'
+
+export interface UseGroupStateOptions {
+  initialGroups: InternalGroup[]
+  onSave?: (groups: InternalGroup[]) => Promise<void>
+}
+
+export interface UseGroupStateResult {
+  groups: InternalGroup[]
+  isDirty: boolean
+  isSaving: boolean
+  error: string | null
+  setError: (error: string | null) => void
+  createGroup: (name: string, description: string) => void
+  updateGroup: (groupId: CanopyGroupId, name: string, description: string) => void
+  deleteGroup: (groupId: CanopyGroupId) => void
+  addMember: (groupId: CanopyGroupId, userId: CanopyUserId) => void
+  removeMember: (groupId: CanopyGroupId, userId: CanopyUserId) => void
+  save: () => Promise<void>
+  discard: () => void
+}
+
+export function useGroupState({
+  initialGroups,
+  onSave,
+}: UseGroupStateOptions): UseGroupStateResult {
+  const [groups, setGroups] = useState<InternalGroup[]>(initialGroups)
+  const [isDirty, setIsDirty] = useState(false)
+  const [isSaving, setIsSaving] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  // Sync groups when prop changes
+  useEffect(() => {
+    setGroups(initialGroups)
+    setIsDirty(false)
+  }, [initialGroups])
+
+  const createGroup = useCallback((name: string, description: string) => {
+    const newGroup: InternalGroup = {
+      id: '' as CanopyGroupId,
+      name,
+      description,
+      members: [],
+    }
+    setGroups((prev) => [...prev, newGroup])
+    setIsDirty(true)
+  }, [])
+
+  const updateGroup = useCallback((groupId: CanopyGroupId, name: string, description: string) => {
+    setGroups((prev) => prev.map((g) => (g.id === groupId ? { ...g, name, description } : g)))
+    setIsDirty(true)
+  }, [])
+
+  const deleteGroup = useCallback((groupId: CanopyGroupId) => {
+    setGroups((prev) => prev.filter((g) => g.id !== groupId))
+    setIsDirty(true)
+  }, [])
+
+  const addMember = useCallback((groupId: CanopyGroupId, userId: CanopyUserId) => {
+    setGroups((prev) =>
+      prev.map((g) => {
+        if (g.id === groupId) {
+          const members = g.members || []
+          if (!members.includes(userId)) {
+            return { ...g, members: [...members, userId] }
+          }
+        }
+        return g
+      }),
+    )
+    setIsDirty(true)
+  }, [])
+
+  const removeMember = useCallback((groupId: CanopyGroupId, userId: CanopyUserId) => {
+    setGroups((prev) =>
+      prev.map((g) => {
+        if (g.id === groupId) {
+          const members = (g.members || []).filter((m) => m !== userId)
+          return { ...g, members }
+        }
+        return g
+      }),
+    )
+    setIsDirty(true)
+  }, [])
+
+  const save = useCallback(async () => {
+    if (!onSave) return
+
+    // Validate that Admins group is not empty
+    const adminsGroup = groups.find((g) => g.id === 'Admins')
+    if (!adminsGroup || !adminsGroup.members || adminsGroup.members.length === 0) {
+      setError('Cannot remove the last admin. At least one admin is required.')
+      return
+    }
+
+    setIsSaving(true)
+    setError(null)
+    try {
+      await onSave(groups)
+      setIsDirty(false)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to save groups')
+    } finally {
+      setIsSaving(false)
+    }
+  }, [onSave, groups])
+
+  const discard = useCallback(() => {
+    setGroups(initialGroups)
+    setIsDirty(false)
+    setError(null)
+  }, [initialGroups])
+
+  return {
+    groups,
+    isDirty,
+    isSaving,
+    error,
+    setError,
+    createGroup,
+    updateGroup,
+    deleteGroup,
+    addMember,
+    removeMember,
+    save,
+    discard,
+  }
+}

package/src/editor/group-manager/hooks/useUserSearch.ts

@@ -0,0 +1,84 @@
+/**
+ * Hook for user search functionality
+ */
+
+import { useState, useEffect, useCallback } from 'react'
+import type { UserSearchResult } from '../types'
+
+export interface UseUserSearchOptions {
+  onSearchUsers?: (query: string, limit?: number) => Promise<UserSearchResult[]>
+}
+
+export interface UseUserSearchResult {
+  searchQuery: string
+  searchResults: UserSearchResult[]
+  isSearching: boolean
+  searchError: string | null
+  activeGroupId: string | null
+  setSearchQuery: (query: string) => void
+  showSearch: (groupId: string) => void
+  hideSearch: () => void
+  clearSearch: () => void
+}
+
+export function useUserSearch({ onSearchUsers }: UseUserSearchOptions): UseUserSearchResult {
+  const [searchQuery, setSearchQuery] = useState('')
+  const [searchResults, setSearchResults] = useState<UserSearchResult[]>([])
+  const [isSearching, setIsSearching] = useState(false)
+  const [searchError, setSearchError] = useState<string | null>(null)
+  const [activeGroupId, setActiveGroupId] = useState<string | null>(null)
+
+  // Debounced user search
+  useEffect(() => {
+    if (!activeGroupId || !searchQuery.trim()) return
+
+    const timer = setTimeout(() => {
+      if (onSearchUsers) {
+        setIsSearching(true)
+        setSearchError(null)
+        onSearchUsers(searchQuery, 10)
+          .then((results) => {
+            setSearchResults(results)
+            setSearchError(null)
+          })
+          .catch((err) => {
+            console.error('User search failed:', err)
+            setSearchError('Failed to search users. Please try again.')
+            setSearchResults([])
+          })
+          .finally(() => setIsSearching(false))
+      }
+    }, 300)
+
+    return () => clearTimeout(timer)
+  }, [searchQuery, onSearchUsers, activeGroupId])
+
+  const showSearch = useCallback((groupId: string) => {
+    setActiveGroupId(groupId)
+  }, [])
+
+  const hideSearch = useCallback(() => {
+    setActiveGroupId(null)
+    setSearchQuery('')
+    setSearchResults([])
+    setSearchError(null)
+  }, [])
+
+  const clearSearch = useCallback(() => {
+    setSearchQuery('')
+    setSearchResults([])
+    setSearchError(null)
+  }, [])
+
+  return {
+    searchQuery,
+    searchResults,
+    isSearching,
+    searchError,
+    activeGroupId,
+    setSearchQuery,
+    showSearch,
+    hideSearch,
+    clearSearch,
+  }
+}

package/src/editor/group-manager/index.tsx

@@ -0,0 +1,210 @@
+'use client'
+
+/**
+ * GroupManager - Main component for managing internal and external groups.
+ *
+ * This component provides a tabbed UI for managing internal groups with
+ * member assignment, and browsing external groups from the organization.
+ */
+
+import React, { useState, useCallback } from 'react'
+import { Alert, Button, Group, Loader, Stack, Tabs, Text } from '@mantine/core'
+import { IconAlertCircle } from '@tabler/icons-react'
+import type { GroupManagerProps, InternalGroup, GroupFormData } from './types'
+import { useGroupState } from './hooks/useGroupState'
+import { useUserSearch } from './hooks/useUserSearch'
+import { useExternalGroupSearch } from './hooks/useExternalGroupSearch'
+import { InternalGroupsTab } from './InternalGroupsTab'
+import { ExternalGroupsTab } from './ExternalGroupsTab'
+import { GroupForm } from './GroupForm'
+
+export const GroupManager: React.FC<GroupManagerProps> = ({
+  internalGroups: initialInternalGroups,
+  loading = false,
+  canEdit,
+  onSave,
+  onSearchUsers,
+  onGetUserMetadata,
+  onSearchExternalGroups,
+  onClose: _,
+}) => {
+  // Group state management
+  const {
+    groups,
+    isDirty,
+    isSaving,
+    error,
+    setError,
+    createGroup,
+    updateGroup,
+    deleteGroup,
+    addMember,
+    removeMember,
+    save,
+    discard,
+  } = useGroupState({
+    initialGroups: initialInternalGroups,
+    onSave,
+  })
+
+  // User search for adding members
+  const userSearch = useUserSearch({ onSearchUsers })
+
+  // External group search
+  const externalGroupSearch = useExternalGroupSearch({ onSearchExternalGroups })
+
+  // Modal state for creating/editing groups
+  const [isModalOpen, setIsModalOpen] = useState(false)
+  const [editingGroup, setEditingGroup] = useState<InternalGroup | null>(null)
+  const [formData, setFormData] = useState<GroupFormData>({
+    name: '',
+    description: '',
+  })
+
+  const handleCreateGroup = useCallback(() => {
+    setEditingGroup(null)
+    setFormData({ name: '', description: '' })
+    setIsModalOpen(true)
+  }, [])
+
+  const handleEditGroup = useCallback((group: InternalGroup) => {
+    setEditingGroup(group)
+    setFormData({ name: group.name, description: group.description || '' })
+    setIsModalOpen(true)
+  }, [])
+
+  const handleSaveModal = useCallback(() => {
+    if (!formData.name.trim()) {
+      setError('Group name is required')
+      return
+    }
+
+    if (editingGroup) {
+      updateGroup(editingGroup.id, formData.name, formData.description)
+    } else {
+      createGroup(formData.name, formData.description)
+    }
+
+    setIsModalOpen(false)
+    setError(null)
+  }, [formData, editingGroup, updateGroup, createGroup, setError])
+
+  const handleFormChange = useCallback((data: Partial<GroupFormData>) => {
+    setFormData((prev) => ({ ...prev, ...data }))
+  }, [])
+
+  const handleAddMember = useCallback(
+    (groupId: string, userId: string) => {
+      addMember(
+        groupId as Parameters<typeof addMember>[0],
+        userId as Parameters<typeof addMember>[1],
+      )
+      userSearch.hideSearch()
+    },
+    [addMember, userSearch],
+  )
+
+  return (
+    <Stack h="100%" style={{ display: 'flex', flexDirection: 'column' }} gap={0}>
+      {!canEdit && (
+        <Alert icon={<IconAlertCircle size={16} />} color="yellow" mb="sm" title="Read-only">
+          You need admin access to manage groups.
+        </Alert>
+      )}
+
+      {error && (
+        <Alert
+          icon={<IconAlertCircle size={16} />}
+          color="red"
+          mb="sm"
+          title="Error"
+          withCloseButton
+          onClose={() => setError(null)}
+        >
+          {error}
+        </Alert>
+      )}
+
+      {loading ? (
+        <Group justify="center" py="xl">
+          <Loader size="md" />
+          <Text size="sm" c="dimmed">
+            Loading groups...
+          </Text>
+        </Group>
+      ) : (
+        <Tabs defaultValue="internal" style={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
+          <Tabs.List>
+            <Tabs.Tab value="internal">Internal Groups</Tabs.Tab>
+            <Tabs.Tab value="external">External Groups</Tabs.Tab>
+          </Tabs.List>
+
+          <Tabs.Panel value="internal" style={{ flex: 1, overflow: 'auto' }}>
+            <InternalGroupsTab
+              groups={groups}
+              canEdit={canEdit}
+              onCreateGroup={handleCreateGroup}
+              onEditGroup={handleEditGroup}
+              onDeleteGroup={deleteGroup}
+              onAddMember={handleAddMember}
+              onRemoveMember={removeMember}
+              onGetUserMetadata={onGetUserMetadata}
+              activeSearchGroupId={userSearch.activeGroupId}
+              searchQuery={userSearch.searchQuery}
+              searchResults={userSearch.searchResults}
+              isSearching={userSearch.isSearching}
+              searchError={userSearch.searchError}
+              onSearchQueryChange={userSearch.setSearchQuery}
+              onShowSearch={userSearch.showSearch}
+              onHideSearch={userSearch.hideSearch}
+              canSearch={!!onSearchUsers}
+            />
+          </Tabs.Panel>
+
+          <Tabs.Panel value="external" style={{ flex: 1, overflow: 'auto' }}>
+            <ExternalGroupsTab
+              canEdit={canEdit}
+              searchQuery={externalGroupSearch.searchQuery}
+              searchResults={externalGroupSearch.searchResults}
+              isSearching={externalGroupSearch.isSearching}
+              searchError={externalGroupSearch.searchError}
+              onSearchQueryChange={externalGroupSearch.setSearchQuery}
+              canSearch={!!onSearchExternalGroups}
+            />
+          </Tabs.Panel>
+        </Tabs>
+      )}
+
+      {canEdit && isDirty && (
+        <Group
+          justify="flex-end"
+          py="sm"
+          gap="sm"
+          style={{ borderTop: '1px solid var(--mantine-color-gray-3)' }}
+        >
+          <Button variant="subtle" color="neutral" onClick={discard} disabled={isSaving}>
+            Discard Changes
+          </Button>
+          <Button onClick={save} loading={isSaving} disabled={isSaving}>
+            Save Groups
+          </Button>
+        </Group>
+      )}
+
+      <GroupForm
+        isOpen={isModalOpen}
+        editingGroup={editingGroup}
+        formData={formData}
+        onFormChange={handleFormChange}
+        onSave={handleSaveModal}
+        onClose={() => setIsModalOpen(false)}
+      />
+    </Stack>
+  )
+}
+
+// Re-export types and hooks for external use
+export type { GroupManagerProps, InternalGroup } from './types'
+export { useGroupState } from './hooks/useGroupState'
+export { useUserSearch } from './hooks/useUserSearch'
+export { useExternalGroupSearch } from './hooks/useExternalGroupSearch'

package/src/editor/group-manager/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Type definitions for GroupManager module
+ */
+
+import type { UserSearchResult, GroupMetadata } from '../../auth/types'
+import type { CanopyGroupId, CanopyUserId } from '../../types'
+import type { InternalGroup } from '../../authorization'
+import type { ExternalGroup } from '../../api/groups'
+
+// Re-export commonly used types for convenience
+export type { UserSearchResult, GroupMetadata, InternalGroup, ExternalGroup }
+export type { CanopyGroupId, CanopyUserId }
+
+export interface GroupManagerProps {
+  internalGroups: InternalGroup[]
+  loading?: boolean
+  canEdit: boolean
+  onSave?: (groups: InternalGroup[]) => Promise<void>
+  onSearchUsers?: (query: string, limit?: number) => Promise<UserSearchResult[]>
+  onGetUserMetadata?: (userId: string) => Promise<UserSearchResult | null>
+  onSearchExternalGroups?: (query: string) => Promise<ExternalGroup[]>
+  onClose?: () => void
+}
+
+export interface GroupFormData {
+  name: string
+  description: string
+}

package/src/editor/hooks/README.md

@@ -0,0 +1,26 @@
+# Editor Hooks Architecture
+
+## Decoupled Reactive Pattern
+
+Hooks independently manage their data lifecycle using `useEffect` to watch `branchName`.
+
+### Principles
+
+- Each hook owns its data loading via `useEffect([branchName])`
+- No callback orchestration between hooks
+- State flows down from `useBranchManager.branchNameState`
+- Effects fire in parallel when `branchName` changes
+
+### Flow
+
+Branch switch → `branchName` state changes → 3 parallel effects:
+
+- `useBranchManager` → `loadBranches()`
+- `useEntryManager` → `refreshEntries()`
+- `useCommentSystem` → `loadComments()`
+
+### Benefits
+
+- Self-contained hooks (easier testing)
+- Parallel data loading (better performance)
+- No duplicate requests (each hook loads once)

package/src/editor/hooks/__test__/test-utils.tsx

@@ -0,0 +1,183 @@
+/**
+ * Shared test utilities for hook tests.
+ *
+ * This file provides common setup patterns and helpers to reduce duplication
+ * across hook test files.
+ */
+
+import React from 'react'
+import { vi } from 'vitest'
+import { createMockApiClient, type MockApiClient } from '../../../api/__test__/mock-client'
+import { ApiClientProvider } from '../../context'
+
+/**
+ * Setup mock API client for hook tests.
+ *
+ * This helper handles the common pattern of:
+ * 1. Creating a mock API client
+ * 2. Injecting it into the createApiClient factory
+ *
+ * @returns The mock API client instance
+ *
+ * @example
+ * ```ts
+ * let mockClient: MockApiClient
+ *
+ * beforeEach(async () => {
+ *   mockClient = await setupMockApiClient()
+ * })
+ * ```
+ */
+export async function setupMockApiClient(): Promise<MockApiClient> {
+  const { createApiClient } = await import('../../../api')
+  const mockClient = createMockApiClient()
+  vi.mocked(createApiClient).mockReturnValue(mockClient as any)
+  return mockClient
+}
+
+/**
+ * Create a wrapper component that provides the mock API client via context.
+ *
+ * Use this with renderHook to provide the ApiClientContext:
+ *
+ * @example
+ * ```ts
+ * const mockClient = await setupMockApiClient()
+ * const wrapper = createApiClientWrapper(mockClient)
+ * const { result } = renderHook(() => useSomeHook(), { wrapper })
+ * ```
+ */
+export function createApiClientWrapper(mockClient: MockApiClient) {
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return <ApiClientProvider client={mockClient as any}>{children}</ApiClientProvider>
+  }
+}
+
+/**
+ * Setup mock window.location for tests that need to manipulate browser location.
+ *
+ * Automatically restores the original location after the test.
+ *
+ * @param options - Initial location values
+ * @returns Cleanup function (called automatically in afterEach if used with setupTestEnvironment)
+ *
+ * @example
+ * ```ts
+ * beforeEach(() => {
+ *   setupMockLocation({ href: 'http://localhost/', search: '' })
+ * })
+ * ```
+ */
+export function setupMockLocation(options: { href?: string; search?: string } = {}) {
+  const originalLocation = window.location as Location
+
+  delete (window as any).location
+  ;(window as any).location = {
+    href: options.href ?? 'http://localhost/',
+    search: options.search ?? '',
+  }
+
+  return () => {
+    ;(window as any).location = originalLocation
+  }
+}
+
+/**
+ * Setup mock window.history.replaceState for tests.
+ *
+ * @returns The mock function
+ *
+ * @example
+ * ```ts
+ * beforeEach(() => {
+ *   setupMockHistory()
+ * })
+ * ```
+ */
+export function setupMockHistory() {
+  const mockReplaceState = vi.fn()
+  window.history.replaceState = mockReplaceState
+  return mockReplaceState
+}
+
+/**
+ * Setup mock console methods with automatic cleanup.
+ *
+ * @param methods - Console methods to mock ('error', 'warn', 'log', etc.)
+ * @returns Object with spy methods and restore function
+ *
+ * @example
+ * ```ts
+ * it('handles errors silently', async () => {
+ *   const { error, restore } = setupMockConsole(['error'])
+ *
+ *   // ... test code that logs errors
+ *
+ *   expect(error).toHaveBeenCalled()
+ *   restore()
+ * })
+ * ```
+ */
+export function setupMockConsole(
+  methods: Array<'error' | 'warn' | 'log' | 'info' | 'debug'> = ['error'],
+) {
+  const spies: any = {}
+
+  for (const method of methods) {
+    spies[method] = vi.spyOn(console, method).mockImplementation(() => {})
+  }
+
+  const restore = () => {
+    for (const spy of Object.values(spies)) {
+      ;(spy as any)?.mockRestore()
+    }
+  }
+
+  return {
+    ...spies,
+    restore,
+  } as Record<'error' | 'warn' | 'log' | 'info' | 'debug', ReturnType<typeof vi.spyOn>> & {
+    restore: () => void
+  }
+}
+
+/**
+ * Complete test environment setup for hook tests.
+ *
+ * Sets up:
+ * - Mock API client
+ * - Mock window.location
+ * - Mock window.history
+ *
+ * @param options - Configuration options
+ * @returns Object with mock client and cleanup functions
+ *
+ * @example
+ * ```ts
+ * let mockClient: MockApiClient
+ *
+ * beforeEach(async () => {
+ *   const setup = await setupTestEnvironment()
+ *   mockClient = setup.mockClient
+ * })
+ * ```
+ */
+export async function setupTestEnvironment(
+  options: {
+    location?: { href?: string; search?: string }
+    setupHistory?: boolean
+  } = {},
+) {
+  const mockClient = await setupMockApiClient()
+
+  const cleanupLocation = setupMockLocation(options.location)
+  const mockHistory = options.setupHistory !== false ? setupMockHistory() : undefined
+
+  return {
+    mockClient,
+    mockHistory,
+    cleanup: () => {
+      cleanupLocation()
+    },
+  }
+}

package/src/editor/hooks/index.ts

@@ -0,0 +1,23 @@
+// Barrel export for all custom hooks
+// Export hooks as they are created
+// Note: resetApiClient functions are not exported - they're test-only utilities
+
+export * from './useEditorLayout'
+export { useBranchManager, type UseBranchManagerOptions } from './useBranchManager'
+export { useEntryManager } from './useEntryManager'
+export * from './useDraftManager'
+export { useCommentSystem } from './useCommentSystem'
+export { useGroupManager } from './useGroupManager'
+export { usePermissionManager } from './usePermissionManager'
+export { useBranchActions } from './useBranchActions'
+export { useUserContext, type UseUserContextReturn } from './useUserContext'
+export {
+  useReferenceResolution,
+  type UseReferenceResolutionOptions,
+  type UseReferenceResolutionResult,
+} from './useReferenceResolution'
+export {
+  useSchemaManager,
+  type UseSchemaManagerOptions,
+  type UseSchemaManagerReturn,
+} from './useSchemaManager'