goravel-crud-search

name: goravel-crud-search description: Add a new entity to the global search (CMD+K) system. Updates backend search controller with permission-gated search and frontend search config with entity type, icon, and colors. argument-hint: "[EntityName] [icon-name]" allowed-tools: Read, Write, Edit, Grep, Glob

Goravel Global Search Integration (CMD+K)

Add $ARGUMENTS to global search.

Architecture Overview

The global search (CMD+K) has three layers:

1. Backend: search_controller.go — permission-gated search methods per entity
2. Frontend config: search_config.tsx — entity type, icon, colors, permissions
3. Frontend UI: GlobalSearch.tsx — command palette (rarely needs changes)

Adding a new entity only requires changes to layers 1 and 2.

File 1: Backend Search — app/http/controllers/search_controller.go

Step 1: Add Permission Check in GlobalSearch()

Find the results := []SearchResult{} line and add a permission-gated search block:

// Search Entities if user has permission
if permHelper.CheckServicePermission(ctx, auth.ServiceEntity, auth.PermissionRead) {
    entityResults := c.searchEntities(query)
    results = append(results, entityResults...)
}

Important: auth.ServiceEntity must match the constant registered in app/auth/permission_constants.go.

Step 2: Add Search Method

Add a new method to SearchController. Follow the existing pattern:

// searchEntities performs fuzzy search on entities using the EntityService
func (c *SearchController) searchEntities(query string) []SearchResult {
    results := []SearchResult{}

    entityService := services.NewEntityService()

    // Use the service's search functionality
    paginatedResult, err := entityService.Search(query, contracts.ListRequest{
        Page:     1,
        PageSize: 10,
    })

    if err != nil || paginatedResult == nil {
        return results
    }

    // Convert service results to search results
    for _, item := range paginatedResult.Data {
        if entity, ok := item.(models.Entity); ok {
            results = append(results, SearchResult{
                ID:       entity.ID,
                Title:    entity.Name,           // Primary display field
                Subtitle: entity.Description,     // Secondary display field (optional)
                Type:     "entity",               // Must match frontend SearchEntityType
                URL:      fmt.Sprintf("/admin/entity-names?search=%s", url.QueryEscape(entity.Name)),
            })
        }
    }

    return results
}

Field Selection Guide

Subtitle Composition Pattern

For entities with multiple display fields, compose subtitles:

subtitle := entity.Status
if entity.Category != "" {
    subtitle = fmt.Sprintf("%s • %s", entity.Category, entity.Status)
}

For entities with nullable fields:

subtitle := entity.Type
if entity.Description != nil && *entity.Description != "" {
    subtitle = fmt.Sprintf("%s • %s", entity.Type, *entity.Description)
}

Step 3: Verify Imports

Ensure these are imported in search_controller.go:

import (
    "books-database/app/models"
    "books-database/app/services"
)

The fmt, net/url, strings imports and auth, contracts imports should already be present.

File 2: Frontend Search Config — resources/js/config/search_config.tsx

Step 1: Add Entity to SearchEntityType Union

export type SearchEntityType = 'user' | 'config' | 'application' | 'entity';

Step 2: Add Icon Import

import {
    Users,
    FileText,
    Settings,
    YourIcon,  // Add from lucide-react
} from 'lucide-react';

Browse icons at https://lucide.dev/icons

Step 3: Add Entity Config to SEARCH_ENTITIES Array

{
    type: 'entity',
    label: 'Entities',
    icon: <YourIcon className="h-4 w-4" />,
    permissionService: 'entities',      // Must match ServiceRegistry in permission_constants.go
    permissionAction: 'read',
    colors: {
        light: 'bg-blue-100 text-blue-800',
        dark: 'dark:bg-blue-900/30 dark:text-blue-400',
    },
    urlPrefix: '/admin/entity-names',
},

SearchEntityConfig Fields

Available Color Palettes

Already used:

• cyan: Users — bg-cyan-100 text-cyan-800
• gray: Configs — bg-gray-100 text-gray-800
• amber: Applications — bg-amber-100 text-amber-800

Pick from unused colors:

• blue: bg-blue-100 text-blue-800 / dark:bg-blue-900/30 dark:text-blue-400
• green: bg-green-100 text-green-800 / dark:bg-green-900/30 dark:text-green-400
• purple: bg-purple-100 text-purple-800 / dark:bg-purple-900/30 dark:text-purple-400
• rose: bg-rose-100 text-rose-800 / dark:bg-rose-900/30 dark:text-rose-400
• indigo: bg-indigo-100 text-indigo-800 / dark:bg-indigo-900/30 dark:text-indigo-400
• emerald: bg-emerald-100 text-emerald-800 / dark:bg-emerald-900/30 dark:text-emerald-400
• orange: bg-orange-100 text-orange-800 / dark:bg-orange-900/30 dark:text-orange-400
• teal: bg-teal-100 text-teal-800 / dark:bg-teal-900/30 dark:text-teal-400
• violet: bg-violet-100 text-violet-800 / dark:bg-violet-900/30 dark:text-violet-400
• pink: bg-pink-100 text-pink-800 / dark:bg-pink-900/30 dark:text-pink-400

How Search Works (Reference)

1. User presses CMD+K (or CTRL+K) → GlobalSearch dialog opens
2. User types query → debounced (300ms) → GET /api/search?q=<query>
3. Backend GlobalSearch() checks permissions per entity, calls searchEntities() for each
4. Each searchEntities() uses the entity's service Search() method (ILIKE with %query% wildcards)
5. Results returned as SearchResult[] → frontend renders with icons, badges, keyboard nav
6. Frontend filters SEARCH_ENTITIES by user permissions for quick access section
7. Clicking a result or pressing Enter navigates to result.url

Service Search Requirements

For the backend search to work, the entity's service must have search fields configured:

// In the service builder (e.g., NewEntityService)
func NewEntityService() *EntityService {
    return &EntityService{
        GenericCrudService: contracts.NewServiceBuilder[models.Entity]("entities", "id").
            WithSearchFields([]string{"name", "description", "status"}).  // Required for search!
            // ... other config
            Build(),
    }
}

Without WithSearchFields, the service Search() method won't match any results.

Verification

1. Backend compiles: go build ./...
2. Type in SearchEntityType matches SearchResult.Type from backend
3. Permission service name matches ServiceRegistry in permission_constants.go
4. Test CMD+K search: type a query, verify new entity results appear
5. Test quick access: open CMD+K without typing, verify entity shows in quick access
6. Test permissions: log in as user without permission, verify entity is hidden

Reference

See existing search implementations in search_controller.go:

• searchUsers() — simple title + subtitle
• searchConfigs() — nullable field handling in subtitle
• searchApplications() — composed subtitle with multiple fields