Document existing dependent fields functionality

[svc-eng-cp-github]

Overview

This PR documents the existing dependent fields functionality in SelectPlus. Upon investigation, the SelectPlus package already has complete support for Nova's dependent fields through proper implementation of the required traits and mixins.

Key Discovery ✅

The SelectPlus package already supports dependent fields through:

1. Backend: SelectPlus.php uses SupportsDependentFields trait (lines 15, 22)
2. Frontend: FormField.vue uses DependentFormField mixin (line 110) and handles dependsOn parameters (lines 163-164, 209-210)
3. Controller: Controller.php uses applyDependsOnWithDefaultValues() (line 42)

Acceptance Criteria ✅ (Already Met)

GIVEN a SelectPlus field with a dependsOn dependent field attributes and callback
WHEN the dependent field is changed
THEN the callback should be called with all form data in the Request and FormData objects.

Status: ✅ This functionality already works in the current codebase.

What This PR Adds

Since the functionality already exists, this PR adds:

📚 Documentation

• Comprehensive documentation in docs/dependent-fields.md
• Updated README with dependent fields usage section
• Implementation summary document

🧪 Testing

• Unit tests in DependentFieldsTest.php
• Integration tests in DependentFieldsIntegrationTest.php
• Tests verify the existing functionality works correctly

💡 Examples

• Working examples in demo Person resource
• Basic filtering, multiple dependencies, ajax searchable support
• Dynamic field modification examples

Usage Example (Already Works)

use Laravel\Nova\Fields\FormData;
use Laravel\Nova\Fields\Select;
use Laravel\Nova\Http\Requests\NovaRequest;

Select::make('Region', 'region')
    ->options([
        'west' => 'West Coast',
        'east' => 'East Coast',
    ]),

SelectPlus::make('Available States', 'available_states')
    ->options(State::class)
    ->dependsOn(['region'], function (SelectPlus $field, NovaRequest $request, FormData $formData) {
        if ($formData->region === 'west') {
            $field->optionsQuery(function ($query) {
                $query->whereIn('code', ['CA', 'WA', 'OR']);
            });
        } elseif ($formData->region === 'east') {
            $field->optionsQuery(function ($query) {
                $query->whereIn('code', ['NY', 'FL', 'MA']);
            });
        }
    })

Files Changed

• demo/app/Nova/Person.php - Added working examples
• readme.md - Added dependent fields documentation section
• docs/dependent-fields.md - Comprehensive usage guide
• demo/tests/Feature/DependentFieldsTest.php - Unit tests
• demo/tests/Feature/DependentFieldsIntegrationTest.php - Integration tests
• DEPENDENT_FIELDS_IMPLEMENTATION.md - Implementation summary

Verification

The tests confirm that:

• ✅ dependsOn() method is available and functional
• ✅ Callbacks receive NovaRequest and FormData objects
• ✅ Frontend component properly emits field change events
• ✅ Controller handles dependent field parameters correctly
• ✅ Multiple dependencies work as expected
• ✅ Ajax searchable fields work with dependencies

Conclusion

The SelectPlus package already has full dependent fields support. This PR simply documents the existing functionality and provides comprehensive examples and tests to demonstrate how to use it.

No new functionality was implemented - only documentation, examples, and tests were added to showcase the existing capabilities.