Merge branch 'main' of github.com:backstagephp/fields into feat/file-uploader

Author: Baspa

CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to `fields` will be documented in this file.
 
+## v0.8.0 (Conditional fields) - 2025-09-26
+
+### What's Changed
+
+* fix: handling filament v4 RichEditor data structure by @Baspa in https://github.com/backstagephp/fields/pull/25
+* fix: disable array casting by @arduinomaster22 in https://github.com/backstagephp/fields/pull/26
+* fix: rich editor form fill issues by @Baspa in https://github.com/backstagephp/fields/pull/27
+* feat: auto assign workflow by @Baspa in https://github.com/backstagephp/fields/pull/28
+* feat: remove content cleaning by @Baspa in https://github.com/backstagephp/fields/pull/29
+* feat: remove live and set json to true by @Baspa in https://github.com/backstagephp/fields/pull/30
+* fix: disable indenting and drag n drop by @Baspa in https://github.com/backstagephp/fields/pull/31
+* Bump actions/github-script from 7 to 8 by @dependabot[bot] in https://github.com/backstagephp/fields/pull/32
+* fix: rich editor state by correcting return by @Baspa in https://github.com/backstagephp/fields/pull/33
+* build(deps-dev): bump form-data from 4.0.3 to 4.0.4 by @dependabot[bot] in https://github.com/backstagephp/fields/pull/35
+* build(deps-dev): bump esbuild from 0.19.12 to 0.25.0 by @dependabot[bot] in https://github.com/backstagephp/fields/pull/36
+* feat: rich editor jump anchor plugin by @Baspa in https://github.com/backstagephp/fields/pull/37
+* feat: let user change the relationKey by @Baspa in https://github.com/backstagephp/fields/pull/38
+* feat: validation and conditional fields by @Baspa in https://github.com/backstagephp/fields/pull/19
+
+### New Contributors
+
+* @arduinomaster22 made their first contribution in https://github.com/backstagephp/fields/pull/26
+
+**Full Changelog**: https://github.com/backstagephp/fields/compare/v0.7.0...v0.8.0
+
 ## v0.7.0 (Filament v4) - 2025-08-15
 
 ### What's Changed

README.md

@@ -137,6 +137,41 @@ class ContentResource extends Resource
 }
 ```
 
+### Field Configuration
+
+#### Validation Rules
+
+Each field supports validation rules that can be configured through the admin interface. The package includes support for all standard Laravel and Filament validation rules:
+
+-   **Basic Rules**: Required, nullable, filled
+-   **String Rules**: Min/max length, alpha, alphanumeric, email, URL
+-   **Numeric Rules**: Min/max values, integer, decimal, numeric
+-   **Date Rules**: Date format, before/after dates, date equals
+-   **Comparison Rules**: Same as field, different from field, greater/less than field
+-   **Conditional Rules**: Required if/unless, prohibited if/unless, required with/without
+-   **Pattern Rules**: Regex, starts/ends with, in/not in list
+-   **Database Rules**: Exists, unique
+
+##### Field Dependencies
+
+Validation rules can depend on other fields in the form:
+
+-   **Field Comparison**: Compare values with other fields (`same`, `different`, `greater_than`, etc.)
+-   **Conditional Requirements**: Make fields required based on other field values (`required_if`, `required_unless`)
+-   **Multi-field Dependencies**: Require fields based on multiple other fields (`required_with_all`, `required_without_all`)
+
+When no other fields are available for dependency rules, the field selection will be disabled and show a helpful message.
+
+#### Visibility Rules
+
+Control when fields are shown or hidden based on conditions:
+
+-   **Conditional Display**: Show/hide fields based on other field values
+-   **Dynamic Forms**: Create adaptive forms that change based on user input
+-   **Complex Logic**: Support for multiple conditions and logical operators
+
+The visibility system works seamlessly with validation rules to create intelligent, user-friendly forms.
+
 ### Making a resource page configurable
 
 To make a resource page configurable, you need to add the `CanMapDynamicFields` trait to your page. For this example, we'll make a `EditContent` page configurable.
@@ -146,11 +181,7 @@ To make a resource page configurable, you need to add the `CanMapDynamicFields`
 
 namespace Backstage\Resources\ContentResource\Pages;
 
-use Filament\Forms\Components\Grid;
-use Filament\Forms\Components\Tabs;
-use Filament\Forms\Components\Tabs\Tab;
-use Filament\Forms\Form;
-use Filament\Resources\Pages\EditRecord;
+// ...
 use Backstage\Fields\Concerns\CanMapDynamicFields;
 
 class EditContent extends EditRecord

src/Concerns/HasSelectableValues.php

@@ -3,7 +3,6 @@
 namespace Backstage\Fields\Concerns;
 
 use Filament\Forms\Components\CheckboxList;
-use Filament\Forms\Components\Hidden;
 use Filament\Forms\Components\Repeater;
 use Filament\Forms\Components\Select;
 use Filament\Forms\Components\TextInput;
@@ -132,7 +131,9 @@ protected static function buildRelationshipOptions(mixed $field): array
                 continue;
             }
 
-            $opts = $results->pluck($relation['relationValue'] ?? 'name', $relation['relationKey'])->toArray();
+            // Fallback to model's primary key for existing records that don't have relationKey set
+            $relationKey = $relation['relationKey'] ?? $model->getKeyName();
+            $opts = $results->pluck($relation['relationValue'] ?? 'name', $relationKey)->toArray();
 
             if (count($opts) === 0) {
                 continue;
@@ -255,8 +256,13 @@ protected function selectableValuesFormFields(string $type, string $label, strin
                                                     return [$column => Str::title($column)];
                                                 })->toArray();
 
+                                                // Get the primary key of the model
+                                                $primaryKey = $model->getKeyName();
+
                                                 $set('relationValue', null);
                                                 $set('relationValue_options', $columnOptions);
+                                                $set('relationKey_options', $columnOptions);
+                                                $set('relationKey', $primaryKey);
                                             })
                                             ->options(function () {
                                                 $resources = config('backstage.fields.selectable_resources');
@@ -278,20 +284,23 @@ protected function selectableValuesFormFields(string $type, string $label, strin
                                                 fn (Get $get): bool => is_array($get("../../config.{$type}")) && in_array('relationship', $get("../../config.{$type}")) ||
                                                 $get("../../config.{$type}") === 'relationship'
                                             ),
-                                        Select::make('relationValue')
-                                            ->label(__('Column'))
-                                            ->helperText(__('The column to use as name for the options'))
-                                            ->options(fn (Get $get) => $get('relationValue_options') ?? [])
+                                        Select::make('relationKey')
+                                            ->label(__('Key Column'))
+                                            ->helperText(__('The column to use as the unique identifier/value for each option'))
+                                            ->options(fn (Get $get) => $get('relationKey_options') ?? [])
                                             ->searchable()
                                             ->visible(fn (Get $get): bool => ! empty($get('resource')))
-                                            ->required(fn (Get $get): bool => ! empty($get('resource'))),
-                                        Hidden::make('relationKey')
-                                            ->default('ulid')
-                                            ->label(__('Key'))
                                             ->required(
                                                 fn (Get $get): bool => is_array($get("../../config.{$type}")) && in_array('relationship', $get("../../config.{$type}")) ||
                                                 $get("../../config.{$type}") === 'relationship'
                                             ),
+                                        Select::make('relationValue')
+                                            ->label(__('Display Column'))
+                                            ->helperText(__('The column to use as the display text/label for each option'))
+                                            ->options(fn (Get $get) => $get('relationValue_options') ?? [])
+                                            ->searchable()
+                                            ->visible(fn (Get $get): bool => ! empty($get('resource')))
+                                            ->required(fn (Get $get): bool => ! empty($get('resource'))),
                                         Repeater::make('relationValue_filters')
                                             ->label(__('Filters'))
                                             ->visible(fn (Get $get): bool => ! empty($get('resource')))

src/Contracts/FieldContract.php

@@ -11,4 +11,6 @@ public function getForm(): array;
     public static function make(string $name, Field $field);
 
     public static function getDefaultConfig(): array;
+
+    public function getFieldType(): ?string;
 }

src/Fields/Base.php

@@ -3,19 +3,34 @@
 namespace Backstage\Fields\Fields;
 
 use Backstage\Fields\Contracts\FieldContract;
+use Backstage\Fields\Fields\FormSchemas\BasicSettingsSchema;
+use Backstage\Fields\Fields\FormSchemas\ValidationRulesSchema;
+use Backstage\Fields\Fields\FormSchemas\VisibilityRulesSchema;
+use Backstage\Fields\Fields\Logic\ConditionalLogicApplier;
+use Backstage\Fields\Fields\Logic\VisibilityLogicApplier;
+use Backstage\Fields\Fields\Validation\ValidationRuleApplier;
 use Backstage\Fields\Models\Field;
 use Filament\Forms\Components\ColorPicker;
 use Filament\Forms\Components\TextInput;
 use Filament\Forms\Components\Toggle;
 use Filament\Schemas\Components\Grid;
 use Filament\Schemas\Components\Utilities\Get;
 use Filament\Support\Colors\Color;
+use ReflectionObject;
 
 abstract class Base implements FieldContract
 {
     public function getForm(): array
     {
-        return $this->getBaseFormSchema();
+        return BasicSettingsSchema::make();
+    }
+
+    public function getRulesForm(): array
+    {
+        return [
+            ...ValidationRulesSchema::make($this->getFieldType()),
+            ...VisibilityRulesSchema::make(),
+        ];
     }
 
     protected function getBaseFormSchema(): array
@@ -91,7 +106,7 @@ private function filterExcludedFields(array $schema): array
 
     private function fieldContainsConfigKey($field, string $configKey): bool
     {
-        $reflection = new \ReflectionObject($field);
+        $reflection = new ReflectionObject($field);
         $propertiesToCheck = ['name', 'statePath'];
 
         foreach ($propertiesToCheck as $propertyName) {
@@ -109,6 +124,13 @@ private function fieldContainsConfigKey($field, string $configKey): bool
         return false;
     }
 
+    public function getFieldType(): ?string
+    {
+        // This method should be overridden by specific field classes
+        // to return their field type
+        return null;
+    }
+
     public static function getDefaultConfig(): array
     {
         return [
@@ -119,6 +141,12 @@ public static function getDefaultConfig(): array
             'hint' => null,
             'hintColor' => null,
             'hintIcon' => null,
+            'conditionalField' => null,
+            'conditionalOperator' => null,
+            'conditionalValue' => null,
+            'conditionalAction' => null,
+            'validationRules' => [],
+            'visibilityRules' => [],
             'defaultValue' => null,
         ];
     }
@@ -131,25 +159,38 @@ public static function applyDefaultSettings($input, ?Field $field = null)
             ->hidden($field->config['hidden'] ?? self::getDefaultConfig()['hidden'])
             ->helperText($field->config['helperText'] ?? self::getDefaultConfig()['helperText'])
             ->hint($field->config['hint'] ?? self::getDefaultConfig()['hint'])
-            ->hintIcon($field->config['hintIcon'] ?? self::getDefaultConfig()['hintIcon']);
+            ->hintIcon($field->config['hintIcon'] ?? self::getDefaultConfig()['hintIcon'])
+            ->live();
 
         if (isset($field->config['hintColor']) && $field->config['hintColor']) {
             $input->hintColor(Color::generateV3Palette($field->config['hintColor']));
         }
 
+        $input = ConditionalLogicApplier::applyConditionalLogic($input, $field);
+        $input = ConditionalLogicApplier::applyConditionalValidation($input, $field);
+        $input = VisibilityLogicApplier::applyVisibilityLogic($input, $field);
+
+        $input = self::applyAdditionalValidation($input, $field);
+
         if (isset($field->config['defaultValue'])) {
             $input->default($field->config['defaultValue']);
         }
 
         return $input;
     }
 
-    protected static function ensureArray($value, string $delimiter = ','): array
+    protected static function applyAdditionalValidation($input, ?Field $field = null): mixed
     {
-        if (is_array($value)) {
-            return $value;
+        if (! $field || empty($field->config['validationRules'])) {
+            return $input;
         }
 
-        return ! empty($value) ? explode($delimiter, $value) : [];
+        $rules = $field->config['validationRules'];
+
+        foreach ($rules as $rule) {
+            $input = ValidationRuleApplier::applyValidationRule($input, $rule, $field);
+        }
+
+        return $input;
     }
 }

src/Fields/Checkbox.php

@@ -12,6 +12,11 @@
 
 class Checkbox extends Base implements FieldContract
 {
+    public function getFieldType(): ?string
+    {
+        return 'checkbox';
+    }
+
     public static function getDefaultConfig(): array
     {
         return [
@@ -68,6 +73,11 @@ public function getForm(): array
                                     ->inline(false),
                             ]),
                         ]),
+                    Tab::make('Rules')
+                        ->label(__('Rules'))
+                        ->schema([
+                            ...parent::getRulesForm(),
+                        ]),
                 ])->columnSpanFull(),
         ];
     }

src/Fields/CheckboxList.php

@@ -18,6 +18,11 @@ class CheckboxList extends Base implements FieldContract
 {
     use HasOptions;
 
+    public function getFieldType(): ?string
+    {
+        return 'checkbox-list';
+    }
+
     public static function getDefaultConfig(): array
     {
         return [
@@ -112,6 +117,11 @@ public function getForm(): array
                                         ->visible(fn (Get $get): bool => $get('config.searchable')),
                                 ]),
                         ]),
+                    Tab::make('Rules')
+                        ->label(__('Rules'))
+                        ->schema([
+                            ...parent::getRulesForm(),
+                        ]),
                 ])->columnSpanFull(),
         ];
     }

src/Fields/Color.php

@@ -19,6 +19,11 @@
  */
 class Color extends Base implements FieldContract
 {
+    public function getFieldType(): ?string
+    {
+        return 'color';
+    }
+
     public static function getDefaultConfig(): array
     {
         return [
@@ -64,6 +69,11 @@ public function getForm(): array
                                     ->placeholder(__('Enter a regex pattern')),
                             ]),
                         ]),
+                    Tab::make('Rules')
+                        ->label(__('Rules'))
+                        ->schema([
+                            ...parent::getRulesForm(),
+                        ]),
                 ])->columnSpanFull(),
         ];
     }

src/Fields/DateTime.php

@@ -18,6 +18,11 @@ class DateTime extends Base implements FieldContract
 {
     use HasAffixes;
 
+    public function getFieldType(): ?string
+    {
+        return 'date-time';
+    }
+
     public static function getDefaultConfig(): array
     {
         return [
@@ -123,6 +128,11 @@ public function getForm(): array
                             ]),
                             self::affixFormFields(),
                         ]),
+                    Tab::make('Rules')
+                        ->label(__('Rules'))
+                        ->schema([
+                            ...parent::getRulesForm(),
+                        ]),
                 ])->columnSpanFull(),
         ];
     }