Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Hooks Reference
Shared custom React hooks used across the GrantMaster application. Each hook encapsulates data fetching, mutation, and state management for a specific domain.Quick Index
All hooks live insrc/hooks/ unless noted as context hooks.
| Hook | Source | Purpose |
|---|---|---|
useZodForm | src/hooks/useZodForm.ts | Standardized form handling (react-hook-form + Zod) |
useProjects | src/hooks/useProjects.ts | Project CRUD with optimistic updates |
useIntegrations | src/hooks/useIntegrations.ts | Integration surface (exports, API keys, webhooks) |
useGrantors | src/hooks/useGrantors.ts | Grantor taxonomy CRUD |
useKeyboardShortcuts | src/hooks/useKeyboardShortcuts.ts | Global keyboard shortcut registration |
useIntelligence | src/hooks/useIntelligence.ts | Intelligence module (benchmarks, funder data, trends) |
useJournals | src/hooks/useJournals.ts | Journal/journal entries |
useJournalSubmissions | src/hooks/useJournalSubmissions.ts | Monthly journal submissions |
useCompliance | src/hooks/useCompliance.ts | Compliance monitoring |
useAuditLog | src/hooks/useAuditLog.ts | Audit log querying |
useUserManagement | src/hooks/useUserManagement.ts | Team/user management |
useUsers | src/hooks/useUsers.ts | User data fetching |
useSubscriptionLimits | src/hooks/useSubscriptionLimits.ts | Subscription tier/quota checks |
useSettings | src/hooks/useSettings.ts | Organization settings |
usePartnerPermissions | src/hooks/usePartnerPermissions.ts | Partner portal permission checks |
useWidgets | src/hooks/useWidgets.ts | Widget system |
useWidgetDashboard | src/hooks/useWidgetDashboard.ts | Dashboard widget layout |
useConfirmDialog | src/hooks/useConfirmDialog.tsx | Confirm dialog state |
useUnsavedChanges | src/hooks/useUnsavedChanges.tsx | Unsaved changes prompt |
useDataFetch | src/hooks/useDataFetch.ts | Generic async data fetching |
useAsyncAction | src/hooks/useAsyncAction.ts | Async action with loading/error state |
useOptimisticUpdate | src/hooks/useOptimisticUpdate.ts | Optimistic update pattern |
usePaginatedData | src/hooks/usePaginatedData.ts | Paginated Firestore queries |
useFirestoreListener | src/hooks/useFirestoreListener.ts | Real-time Firestore subscription |
useBackupOperations | src/hooks/useBackupOperations.ts | Backup/restore job management and restore request approval |
useTablePreferences | src/hooks/useTablePreferences.ts | Table column/sort preferences |
useNetworkStatus | src/hooks/useNetworkStatus.ts | Online/offline detection |
useSessionTimeout | src/hooks/useSessionTimeout.tsx | Session idle timeout |
useErrorHandler | src/hooks/useErrorHandler.ts | Error boundary helper |
useI18n | src/hooks/useI18n.ts | i18n utilities |
useTRPC | src/hooks/useTRPC.ts | tRPC client helper |
useAccessibility | src/hooks/useAccessibility.ts | Accessibility utilities |
usePlatformFavicon | src/hooks/usePlatformFavicon.ts | Dynamic favicon |
useTouchGestures | src/hooks/useTouchGestures.ts | Mobile touch gestures |
useShareImpactTrigger | src/hooks/useShareImpactTrigger.ts | Impact sharing triggers |
useGrantorComplianceSync | src/hooks/useGrantorComplianceSync.ts | Grantor compliance sync |
src/features/*/hooks/):
| Hook | Source | Purpose |
|---|---|---|
useAgentRuns | features/agents/hooks/useAgentRuns.ts | Agent run list with filtering and computed summary stats (totalRuns, creditsConsumed, etc.) |
useGrantAssistantState | features/ai/hooks/useGrantAssistantState.ts | Grant Assistant panel UI state (open/close, input, loading, scroll) |
useAuditDashboard | features/auditor/hooks/useAuditDashboard.ts | Auditor dashboard summary and refresh state |
useAuditorReviewPanel | features/auditor/components/AuditorReviewPanel/AuditorReviewPanelContext.tsx | Auditor review panel selection and actions |
useCompliance | features/compliance/ComplianceContext.tsx | Project compliance workflow compatibility hook |
useCurrentFolderDocuments | features/documents/DocumentBrainContext.tsx | Current folder document list for Document Brain |
useDocumentBrainPageState | features/documents/hooks/useDocumentBrainPageState.ts | Document Brain page orchestration state |
useDashboardTemplateEditor | features/dashboard/components/DashboardTemplateEditor/DashboardTemplateEditorContext.tsx | Dashboard template editor context state |
useDashboardTemplateEditorModalState | features/dashboard/hooks/useDashboardTemplateEditorModalState.ts | Dashboard template modal open/close state |
useDocumentBrain | features/documents/DocumentBrainContext.tsx | Document Brain data/actions compatibility hook |
useDocumentStats | features/documents/DocumentBrainContext.tsx | Document Brain derived stats |
useEmailManagement | features/email/components/EmailManagement/EmailManagementContext.tsx | Email management data/actions |
useExpenses | features/expenses/hooks/useExpenses.ts | Expense list and mutation API |
useMarketplace | features/extensions/hooks/useExtensions.ts | Extension marketplace listings and actions |
useActiveGrant | features/grants/GrantContext.tsx | Select a single active grant from grants data |
useActiveGrantsList | features/grants/hooks/useGrants.ts | Query-backed active grants list |
useGrant | features/grants/hooks/useGrants.ts | Query-backed single grant lookup |
useGrantApplicationsList | features/grants/hooks/useGrants.ts | Query-backed grant applications list |
useGrantMutations | features/grants/hooks/useGrants.ts | Canonical grant mutation surface |
useGrantOperatingSnapshot | features/grants/useGrantOperatingSnapshot.ts | Cross-domain grant operating snapshot data |
useGrantOpportunity | features/grants/GrantContext.tsx | Select a single opportunity from grants data |
useGrantOpportunitiesList | features/grants/hooks/useGrants.ts | Query-backed grant opportunities list |
useGrantorAnalytics | features/grantors/hooks/useGrantorAnalytics.ts | Grantor analytics and portfolio metrics |
useGrantorInteractions | features/grantors/hooks/useGrantorInteractions.ts | Grantor interaction feed and mutations |
useGrantPipelineList | features/grants/hooks/useGrants.ts | Query-backed pipeline list |
useGrants | features/grants/GrantContext.tsx | Legacy grants compatibility hook backed by canonical query hooks |
useGrantsList | features/grants/hooks/useGrants.ts | Aggregate query-backed grants collections |
useOrgPortal | features/grantors/hooks/useOrgPortal.ts | Grantor portal data/actions |
usePipelineEntry | features/grants/GrantContext.tsx | Select a single pipeline entry from grants data |
useReportingDeadlines | features/grantors/hooks/useReportingDeadlines.ts | Reporting calendar and deadline utilities |
useApprovedJournals | features/journals/JournalGenerationContext.tsx | Filter approved journals |
useJournal | features/journals/hooks/useJournals.ts | Query-backed single journal entry |
useJournals | features/journals/hooks/useJournals.ts | Query-backed journals list and mutations |
useJournalsByDateRange | features/journals/JournalGenerationContext.tsx | Filter journals by date range |
useJournalsByMonth | features/journals/JournalGenerationContext.tsx | Filter journals by month |
useJournalsByProject | features/journals/JournalGenerationContext.tsx | Filter journals by project |
useJournalsByProjectIds | features/journals/JournalGenerationContext.tsx | Filter journals by project ids |
useJournalsByStatus | features/journals/JournalGenerationContext.tsx | Filter journals by status |
useJournalsByUser | features/journals/JournalGenerationContext.tsx | Filter journals by user |
useJournalsThisMonth | features/journals/JournalGenerationContext.tsx | Current month journals |
useJournalsThisWeek | features/journals/JournalGenerationContext.tsx | Current week journals |
useJournalsToday | features/journals/JournalGenerationContext.tsx | Today’s journals |
useLockedJournals | features/journals/JournalGenerationContext.tsx | Locked journals subset |
usePendingJournals | features/journals/JournalGenerationContext.tsx | Pending journals subset |
useActivityHistoryState | features/mission/hooks/useActivityHistoryState.ts | Mission activity history state |
useNotificationHistoryState | features/notifications/hooks/useNotificationHistoryState.ts | Notification history list/filter state |
useNotificationsTRPC | features/notifications/hooks/useNotificationsTRPC.ts | Notifications tRPC mutations |
usePartnershipsDashboardState | features/partnerships/hooks/usePartnershipsDashboardState.ts | Partnerships dashboard state |
usePortalAnalyticsState | features/impact-portal/hooks/usePortalAnalyticsState.ts | Impact portal analytics state |
useActiveProjects | features/projects/ProjectContext.tsx | Active projects selector |
useArchivedProjects | features/projects/ProjectContext.tsx | Archived projects selector |
useNonArchivedProjects | features/projects/ProjectContext.tsx | Non-archived projects selector |
useOutstandingTasksCount | features/projects/hooks/useOutstandingTasksCount.ts | Outstanding tasks count for the current user |
useProject | features/projects/ProjectContext.tsx | Single project lookup |
useProjects | features/projects/ProjectContext.tsx | Projects compatibility hook backed by canonical query hooks |
useProjectsByIds | features/projects/ProjectContext.tsx | Projects filtered by ids |
useProjectsByPhase | features/projects/ProjectContext.tsx | Projects filtered by phase |
useProjectsByStatus | features/projects/ProjectContext.tsx | Projects filtered by status |
useContactAnalytics | features/relations/hooks/useContactAnalytics.ts | Contact analytics hook |
useInteractionsFeed | features/relations/hooks/useInteractionsFeed.ts | Interactions feed hook |
useSegments | features/relations/hooks/useSegments.ts | Segments list and mutation hook |
useActiveUsers | features/users/UserContext.tsx | Active users selector |
useCurrentUser | features/users/UserContext.tsx | Current user profile selector |
useInvitedUsers | features/users/UserContext.tsx | Invited users selector |
useUser | features/users/UserContext.tsx | Single user lookup |
useUserByEmail | features/users/UserContext.tsx | User lookup by email |
useUsers | features/users/UserContext.tsx | Users compatibility hook |
useUsersByIds | features/users/UserContext.tsx | Users filtered by ids |
useUsersByManager | features/users/UserContext.tsx | Users filtered by manager |
useUsersByRole | features/users/UserContext.tsx | Users filtered by role |
useUsersByStatus | features/users/UserContext.tsx | Users filtered by status |
useUsersBySystemRole | features/users/UserContext.tsx | Users filtered by system role |
src/contexts/):
| Hook | Source | Purpose |
|---|---|---|
useTenant | TenantContext.tsx | Current organization context (org data + actions) |
useTenantData | TenantContext.tsx | Organization data only (fewer re-renders) |
useTenantActions | TenantContext.tsx | Stable action callbacks only |
useAuth | AuthContext.tsx | Authentication state |
useRoles | RoleContext.tsx | Role definitions and management |
useRole | RoleContext.tsx | Single role lookup by ID |
useRoleByName | RoleContext.tsx | Role lookup by name |
useModules | ExtensionContext.tsx | Extension/module system |
useZodForm
Source: src/hooks/useZodForm.ts
Standardized form handling combining react-hook-form with Zod schema validation. All new forms must use this hook — useValidatedForm is deprecated.
Options (UseZodFormOptions<TSchema>)
| Prop | Type | Default | Description |
|---|---|---|---|
schema | z.ZodType | required | Zod schema for validation |
defaultValues | DefaultValues<z.infer<TSchema>> | — | Initial form values |
onSubmit | (data) => Promise<void> | void | required | Success callback |
onError | (error: unknown) => void | — | Custom error handler |
successMessage | string | — | Toast shown on success |
errorMessagePrefix | string | 'Form submission failed' | Error toast prefix |
resetOnSuccess | boolean | false | Reset form after success |
mode | 'onBlur' | 'onChange' | 'onSubmit' | 'onTouched' | 'all' | 'onBlur' | Validation trigger mode |
Return Value (UseZodFormReturn<TSchema>)
| Field | Type | Description |
|---|---|---|
form | UseFormReturn | Underlying react-hook-form instance |
handleSubmit | (e?) => Promise<void> | Submit handler for <form onSubmit> |
isSubmitting | boolean | Currently submitting |
isDirty | boolean | Form has been modified |
isValid | boolean | Form passes validation |
reset | () => void | Reset to default values |
getFieldError | (name) => string | undefined | Error message for a field |
hasFieldError | (name) => boolean | Whether field has error |
register | UseFormReturn['register'] | Field registration |
control | UseFormReturn['control'] | Control object for Controller |
errors | FormState['errors'] | All validation errors |
setValue | UseFormReturn['setValue'] | Programmatic value setter |
watch | UseFormReturn['watch'] | Watch field values |
trigger | UseFormReturn['trigger'] | Trigger validation manually |
Behavior
- Validation: Runs Zod schema validation via
zodResolver. Default mode isonBlur. - Error handling: Errors are logged via
handleError()(Sentry + console) and shown as toast notifications. - Success toast: If
successMessageis provided, a success toast is shown automatically. - Reset: When
resetOnSuccessistrue, form resets todefaultValuesafter successful submission.
useGrantsList
Source: src/features/grants/hooks/useGrants.ts
Canonical grants read hook. It aggregates opportunities, pipeline entries, applications, and active grants behind one query-backed surface.
Return Value
| Field | Type | Description |
|---|---|---|
data.opportunities | GrantOpportunity[] | Discovery opportunities |
data.pipeline | GrantPipelineEntry[] | Pipeline entries |
data.applications | GrantApplication[] | Grant applications |
data.activeGrants | ActiveGrant[] | Post-award active grants |
isLoading | boolean | Combined loading state across all grant collections |
error | Error | null | First query error, if any |
refetch | () => Promise<void> | Refetch all grant collections |
status | object | Per-collection loading flags |
Behavior
- Uses feature services rather than Firebase imports in the hook.
- Acts as the default owner for grants feature collections.
- Replaces provider-owned canonical grant collection state.
useGrant
Source: src/features/grants/hooks/useGrants.ts
Query-backed lookup for a single active grant by id.
grantId is missing, data resolves to null.
useGrantMutations
Source: src/features/grants/hooks/useGrants.ts
Canonical grants write surface. All mutations delegate to GrantService and invalidate the grants query keys on success.
Included Mutations
addToPipeline(opportunity, initialData?)createOpportunity(opportunity)updatePipelineStage(entryId, newStage, reason?)updatePipelineEntry(entry)removePipelineEntry(entryId)saveApplication(application, isNew?)submitApplication(applicationId, confirmationNumber?)convertToActiveGrant(pipelineEntry, opportunity, applicationId, grantDetails)updateActiveGrant(grant)
useProjects
Source: src/hooks/useProjects.ts
CRUD operations for projects within a tenant organization. All mutations are optimistically applied, audit-logged, and trigger admin notifications.
Options
| Prop | Type | Description |
|---|---|---|
organizationId | string? | Tenant organization ID. When absent, returns empty project list. |
Return Value
| Field | Type | Description |
|---|---|---|
projects | Project[] | Current project list |
loading | boolean | true during initial fetch |
error | Error | null | Fetch error, if any |
addProject | (project: Project) => Promise<void> | Create a project (checks quota first) |
updateProject | (project: Project) => Promise<void> | Update a project (notifies admins of changes) |
deleteProject | (id: string) => Promise<void> | Delete a project |
Behavior
- Quota enforcement:
addProjectcallscheckQuotaCompliance()and blocks creation if the project limit is reached. - Optimistic updates: State is updated immediately; rolled back on error.
- Audit logging: All CRUD operations log
PROJECT_CREATED,PROJECT_UPDATED, orPROJECT_DELETEDevents. - Notifications:
addProjectandupdateProjectnotify organization admins.
useIntegrations
Source: src/hooks/useIntegrations.ts
Manages the organization’s integration surface: export records, API keys, webhooks, and audit logs. Scoped to the current tenant via useTenant().
Return Value
| Field | Type | Description |
|---|---|---|
loading | boolean | true during initial parallel fetch |
exports | IntegrationRecord[] | Data export records |
apiKeys | ApiKey[] | Organization API keys |
webhooks | WebhookConfig[] | Webhook endpoint configurations |
auditLogs | AuditLogEntry[] | Integration audit log entries |
addExport | (record) => Promise<void> | Create an export record |
removeExport | (id) => Promise<void> | Delete an export record |
addApiKey | (key) => Promise<void> | Create an API key |
revokeApiKey | (id) => Promise<void> | Revoke (soft-delete) an API key |
addWebhook | (webhook) => Promise<void> | Create a webhook endpoint |
editWebhook | (webhook) => Promise<void> | Update a webhook configuration |
toggleWebhook | (id) => Promise<void> | Toggle a webhook’s active/inactive state |
removeWebhook | (id) => Promise<void> | Delete a webhook |
getWebhookLogs | (webhookId) => Promise<WebhookLog[]> | Fetch delivery logs for a webhook |
refresh | () => Promise<void> | Reload all integration data |
useGrantors
Source: src/hooks/useGrantors.ts
CRUD for the global grantor (funder) taxonomy. Grantors are shared across all projects and used in grant applications, pipeline tracking, and compliance reporting.
Return Value
| Field | Type | Description |
|---|---|---|
grantors | TaxonomyItem[] | Grantor taxonomy items |
loading | boolean | true during initial fetch |
error | string | null | Error message, if any |
addGrantor | (grantor: TaxonomyItem) => Promise<boolean> | Create a grantor (returns true on success) |
editGrantor | (grantor: TaxonomyItem) => Promise<boolean> | Update a grantor |
removeGrantor | (id: string) => Promise<boolean> | Delete a grantor |
Behavior
- Requires authenticated user — waits for
useAuth()to resolve before fetching. - Stamps new grantors with
createdBy(UID) andcreatedAtfor Firestore security rules.
useKeyboardShortcuts
Source: src/hooks/useKeyboardShortcuts.ts
Registers global keyboard shortcuts on window. Automatically skips shortcuts when focus is inside <input>, <textarea>, or contentEditable elements (Cmd/Ctrl+K is always allowed).
useKeyboardShortcut
Convenience wrapper for a single shortcut:
Utility Functions
| Function | Signature | Description |
|---|---|---|
isMac() | () => boolean | Detect macOS platform |
getModifierLabel(modifier) | ('cmd' | 'ctrl' | 'alt' | 'shift') => string | Platform-appropriate modifier symbol (⌘ vs Ctrl) |
formatShortcut(shortcut) | (Partial<ShortcutConfig>) => string | Format shortcut for display (⌘K or Ctrl+K) |
Intelligence Hooks
Source: src/hooks/useIntelligence.ts
Composable hooks for the cross-organization Intelligence module. Available individually or combined.
useIntelligence (combined)
Aggregates all intelligence sub-hooks into a single return object. Also computes featureAccess based on the organization’s subscription tier.
useConsent
Manage the current organization’s intelligence data-sharing consent.
| Method | Signature | Description |
|---|---|---|
grantConsent | (categories?: IntelligenceDataCategory[]) => Promise<boolean> | Opt in to data sharing |
withdrawConsent | (reason?: string) => Promise<boolean> | Opt out of data sharing |
requestDeletion | () => Promise<boolean> | Request full data deletion |
useBenchmarks
Fetch anonymized sector benchmarks for the current organization.
| Field | Type | Description |
|---|---|---|
benchmarks | OrgBenchmarkPosition[] | Benchmark positions (grant success rate, budget utilization, etc.) |
cohortDescription | string | Human-readable cohort description |
useFunderIntelligence
Access funder profiles and organization-specific funder insights.
| Field | Type | Description |
|---|---|---|
profiles | FunderProfile[] | Aggregated public funder data |
insights | FunderInsight[] | Tailored recommendations for the current org |
useSectorTrends
Fetch aggregated sector-level funding trends.
| Param | Type | Description |
|---|---|---|
sectors | string[]? | Optional sector filter (e.g. ['healthcare', 'education']) |
Common Patterns
Optimistic Updates
Most mutation hooks follow this pattern:- Update local state immediately
- Call the service layer
- On error: rollback local state + show toast
Audit Logging
Hooks that modify data (useProjects) automatically log audit events with logAuditEvent(). Both success and failure outcomes are logged.
Tenant Scoping
All hooks scope data to the current organization via either:useTenant()→organization.id(automatic)organizationIdoption parameter (explicit)