[Reports]: Custom field support in Report Builder

[cghsnl]

Affected Area or Module

Custom field in template editor

Problem Statement

No response

Proposed Solution

Goal
Integrate Custom Fields as a data source and variable within the Template Editor (for documents/emails) and the Report Builder (for custom reporting).

🌟 Value Proposition (The "Why")
This feature allows users to utilize dynamic, user-defined data points (Custom Fields) in their standardized output formats. This enables deep personalization of templates and more granular data analysis in reports, reducing the need for manual data input.

Custom Fields available for querying, sorting, and display.

Field Selector (Columns):

Custom Fields should appear in the list of available columns to display on the report output.

Filter/Condition Builder:

Custom Fields should be selectable as the criteria for filtering the report data.

The available Operators for filtering must adapt to the Custom Field's data type (e.g., a Date Field must offer is before, is after; a Text Field must offer contains, is).

Example Filter: Custom Field: 'Client Tier' | Operator: 'is' | Value: 'Platinum'

Field Deletion: What happens to a template/report if a Custom Field used within it is deleted?

Suggested behavior: Template merge tag should render empty/a default value. Report Builder should automatically remove the field from columns/filters.

Permissions: Custom Fields are subject to user permissions. A user building a report should only see/use Custom Fields they have read access to.

Data Integrity: Ensure that the Custom Field value is correctly associated with the parent entity (e.g., a Project's custom field value is pulled when generating a Project Template).

Notes or context

No response

[nielsdrost7]

---

Test Suggestions

Added to support future implementation of this request. The issue body is unchanged.

Modules\Core\Models\CustomField already exists as a generic, company-scoped model (fieldable_type, custom_field_label, field_type cast to Modules\Core\Enums\CustomFieldType, which already has exactly the four data types this request needs — TEXT, NUMBER, DATE, BOOLEAN — so operator-set-adapts-to-type is a realistic ask against real code). What's missing is the integration: Modules\Core\Services\ReportFieldService::getFieldsBySource() only reads a static config/report-fields.php array and never merges in a company's CustomField records, and — per the grounding on #130 — there is currently no working Report Builder at all on develop to plug a filter/condition UI into (the real work for that sits in an unmerged PR, #608). So this request layers two things: (1) surfacing CustomField in the available field list, which can be built independently of the builder, and (2) filter/operator UI inside a builder that doesn't exist yet.

• PHPUnit: it_includes_a_companys_custom_fields_in_the_available_report_fields()

#[Test]
public function it_includes_a_companys_custom_fields_in_the_available_report_fields(): void
{
    /* Arrange */
    CustomField::factory()->for($this->company)->create([
        'fieldable_type'     => Relation::class,
        'custom_field_label' => 'Client Tier',
        'field_type'         => CustomFieldType::TEXT,
    ]);

    /* Act */
    $fields = app(ReportFieldService::class)->getAvailableFields();

    /* Assert */
    $this->assertTrue(collect($fields)->contains(fn ($f) => $f['label'] === 'Client Tier'));
}

• PHPUnit: it_scopes_custom_fields_in_the_field_list_to_the_current_company()

#[Test]
public function it_scopes_custom_fields_in_the_field_list_to_the_current_company(): void
{
    /* Arrange */
    $otherCompany = Company::factory()->create();
    CustomField::factory()->for($otherCompany)->create(['custom_field_label' => 'Other Co Field']);

    /* Act */
    $fields = app(ReportFieldService::class)->getAvailableFields();

    /* Assert */
    $this->assertFalse(collect($fields)->contains(fn ($f) => $f['label'] === 'Other Co Field'));
}

• PHPUnit: it_offers_date_specific_operators_for_a_date_type_custom_field()

#[Test]
public function it_offers_date_specific_operators_for_a_date_type_custom_field(): void
{
    /* Arrange */
    $field = CustomField::factory()->for($this->company)->create(['field_type' => CustomFieldType::DATE]);

    /* Act */
    $operators = app(ReportFieldService::class)->getOperatorsForField($field);

    /* Assert */
    $this->assertContains('is_before', $operators);
    $this->assertContains('is_after', $operators);
}

Edge cases worth covering: a CustomField deleted after being referenced in a saved report/template configuration (the issue proposes rendering empty and auto-removing it from columns/filters — neither behaviour exists today since no report configuration persistence exists yet either), and a user who lacks read access to a given custom field seeing it excluded from the field picker entirely rather than merely disabled.