Merge branch 'main' of github.com:backstagephp/fields into release/1.x

Baspa · Baspa · commit cfbed9cd7efc · 2025-08-08T09:52:42.000+02:00
diff --git a/.github/workflows/fix-php-code-style-issues.yml b/.github/workflows/fix-php-code-style-issues.yml
@@ -19,7 +19,7 @@ jobs:
           ref: ${{ github.head_ref }}
 
       - name: Fix PHP code style issues
-        uses: aglipanci/laravel-pint-action@2.5
+        uses: aglipanci/laravel-pint-action@2.6
 
       - name: Commit changes
         uses: stefanzweifel/git-auto-commit-action@v6
diff --git a/README.md b/README.md
@@ -232,7 +232,105 @@ return [
 
 ### Creating your own fields
 
-...
+To create your own custom fields, you need to extend the `Base` field class and implement the required methods. Here's an example of a custom field:
+
+```php
+<?php
+
+namespace App\Fields;
+
+use Backstage\Fields\Fields\Base;
+use Filament\Forms\Components\TextInput;
+
+class CustomField extends Base
+{
+    public static function make(string $name, ?Field $field = null): TextInput
+    {
+        $input = self::applyDefaultSettings(TextInput::make($name), $field);
+        
+        // Add your custom field logic here
+        $input->placeholder('Custom placeholder');
+        
+        return $input;
+    }
+
+    public function getForm(): array
+    {
+        return [
+            // Your custom form configuration
+            TextInput::make('config.customOption')
+                ->label('Custom Option'),
+        ];
+    }
+
+    public static function getDefaultConfig(): array
+    {
+        return [
+            ...parent::getDefaultConfig(),
+            'customOption' => null,
+        ];
+    }
+}
+```
+
+#### Excluding base fields from custom fields
+
+When creating custom fields, you may want to exclude certain base fields that don't apply to your field type. For example, a Repeater field doesn't need a "Default value" field since it's a container for other fields.
+
+You can exclude base fields by overriding the `excludeFromBaseSchema()` method:
+
+```php
+<?php
+
+namespace App\Fields;
+
+use Backstage\Fields\Fields\Base;
+
+class RepeaterField extends Base
+{
+    // Exclude the default value field since it doesn't make sense for repeaters
+    protected function excludeFromBaseSchema(): array
+    {
+        return ['defaultValue'];
+    }
+
+    // Your field implementation...
+}
+```
+
+Available base fields that can be excluded:
+- `required` - Required field toggle
+- `disabled` - Disabled field toggle  
+- `hidden` - Hidden field toggle
+- `helperText` - Helper text input
+- `hint` - Hint text input
+- `hintColor` - Hint color picker
+- `hintIcon` - Hint icon input
+- `defaultValue` - Default value input
+
+#### Best practices for field exclusion
+
+- **Only exclude what doesn't apply**: Don't exclude fields just because you don't use them - only exclude fields that conceptually don't make sense for your field type
+- **Document your exclusions**: Add comments explaining why certain fields are excluded
+- **Test thoroughly**: Make sure your field still works correctly after excluding base fields
+- **Consider inheritance**: If your field extends another custom field, make sure to call `parent::excludeFromBaseSchema()` if you need to add more exclusions
+
+Example of a field that excludes multiple base fields:
+
+```php
+class ImageField extends Base
+{
+    protected function excludeFromBaseSchema(): array
+    {
+        return [
+            'defaultValue', // Images don't have default values
+            'hint',         // Image fields typically don't need hints
+            'hintColor',    // No hint means no hint color
+            'hintIcon',     // No hint means no hint icon
+        ];
+    }
+}
+```
 
 ### Registering your own fields
 
diff --git a/src/Concerns/CanMapDynamicFields.php b/src/Concerns/CanMapDynamicFields.php
@@ -10,6 +10,7 @@
 use Backstage\Fields\Fields\Color;
 use Backstage\Fields\Fields\DateTime;
 use Backstage\Fields\Fields\KeyValue;
+use Backstage\Fields\Fields\MarkdownEditor;
 use Backstage\Fields\Fields\Radio;
 use Backstage\Fields\Fields\Repeater;
 use Backstage\Fields\Fields\RichEditor;
@@ -41,6 +42,7 @@ trait CanMapDynamicFields
         'text' => Text::class,
         'textarea' => Textarea::class,
         'rich-editor' => RichEditor::class,
+        'markdown-editor' => MarkdownEditor::class,
         'repeater' => Repeater::class,
         'select' => Select::class,
         'checkbox' => Checkbox::class,
@@ -110,6 +112,7 @@ protected function mutateBeforeSave(array $data): array
         }
 
         $builderBlocks = $this->extractBuilderBlocks($values);
+
         $allFields = $this->getAllFieldsIncludingBuilderFields($builderBlocks);
 
         return $this->mutateFormData($data, $allFields, function ($field, $fieldConfig, $fieldInstance, $data) use ($builderBlocks) {
@@ -485,6 +488,8 @@ private function determineFieldLocation(Model $field, array $builderBlocks): arr
                         return [
                             'isInBuilder' => true,
                             'builderData' => $block['data'],
+                            'builderUlid' => $builderUlid,
+                            'blockIndex' => array_search($block, $builderBlocks),
                         ];
                     }
                 }
@@ -494,6 +499,8 @@ private function determineFieldLocation(Model $field, array $builderBlocks): arr
         return [
             'isInBuilder' => false,
             'builderData' => null,
+            'builderUlid' => null,
+            'blockIndex' => null,
         ];
     }
 
@@ -512,17 +519,25 @@ private function determineFieldLocation(Model $field, array $builderBlocks): arr
      */
     private function processBuilderFieldMutation(Model $field, object $fieldInstance, array $data, array $builderData, array $builderBlocks): array
     {
-        // Create a mock record with the builder data for the callback
-        $mockRecord = $this->createMockRecordForBuilder($builderData);
+        foreach ($builderBlocks as $builderUlid => &$blocks) {
+            if (is_array($blocks)) {
+                foreach ($blocks as &$block) {
+                    if (isset($block['data']) && is_array($block['data']) && isset($block['data'][$field->ulid])) {
+                        // Create a mock record with the block data for the callback
+                        $mockRecord = $this->createMockRecordForBuilder($block['data']);
 
-        // Create a temporary data structure for the callback
-        $tempData = [$this->record->valueColumn => $builderData];
-        $tempData = $fieldInstance->mutateBeforeSaveCallback($mockRecord, $field, $tempData);
+                        // Create a temporary data structure for the callback
+                        $tempData = [$this->record->valueColumn => $block['data']];
+                        $tempData = $fieldInstance->mutateBeforeSaveCallback($mockRecord, $field, $tempData);
 
-        // Update the original data structure with the mutated values
-        $this->updateBuilderBlocksWithMutatedData($builderBlocks, $field, $tempData);
+                        if (isset($tempData[$this->record->valueColumn][$field->ulid])) {
+                            $block['data'][$field->ulid] = $tempData[$this->record->valueColumn][$field->ulid];
+                        }
+                    }
+                }
+            }
+        }
 
-        // Update the main data structure
         $data[$this->record->valueColumn] = array_merge($data[$this->record->valueColumn], $builderBlocks);
 
         return $data;
diff --git a/src/Enums/Field.php b/src/Enums/Field.php
@@ -12,10 +12,10 @@ enum Field: string
     case CheckboxList = 'checkbox-list';
     case Color = 'color';
     case DateTime = 'date-time';
-    case File = 'file-upload';
-    case Hidden = 'hidden';
+    // case File = 'file-upload';
+    // case Hidden = 'hidden';
     case KeyValue = 'key-value';
-    case Link = 'link';
+    // case Link = 'link';
     case MarkdownEditor = 'markdown-editor';
     case Radio = 'radio';
     case Repeater = 'repeater';
@@ -25,5 +25,5 @@ enum Field: string
     case Text = 'text';
     case Textarea = 'textarea';
     case Toggle = 'toggle';
-    case ToggleButtons = 'toggle-buttons';
+    // case ToggleButtons = 'toggle-buttons';
 }
diff --git a/src/Fields/Base.php b/src/Fields/Base.php
@@ -15,7 +15,12 @@ abstract class Base implements FieldContract
 {
     public function getForm(): array
     {
-        return [
+        return $this->getBaseFormSchema();
+    }
+
+    protected function getBaseFormSchema(): array
+    {
+        $schema = [
             Grid::make(3)
                 ->schema([
                     Toggle::make('config.required')
@@ -52,7 +57,56 @@ public function getForm(): array
                             return ! empty(trim($hint));
                         }),
                 ]),
+            TextInput::make('config.defaultValue')
+                ->label(__('Default value'))
+                ->helperText(__('This value will be used when creating new records.')),
         ];
+
+        return $this->filterExcludedFields($schema);
+    }
+
+    protected function excludeFromBaseSchema(): array
+    {
+        return [];
+    }
+
+    private function filterExcludedFields(array $schema): array
+    {
+        $excluded = $this->excludeFromBaseSchema();
+
+        if (empty($excluded)) {
+            return $schema;
+        }
+
+        return array_filter($schema, function ($field) use ($excluded) {
+            foreach ($excluded as $excludedField) {
+                if ($this->fieldContainsConfigKey($field, $excludedField)) {
+                    return false;
+                }
+            }
+
+            return true;
+        });
+    }
+
+    private function fieldContainsConfigKey($field, string $configKey): bool
+    {
+        $reflection = new \ReflectionObject($field);
+        $propertiesToCheck = ['name', 'statePath'];
+
+        foreach ($propertiesToCheck as $propertyName) {
+            if ($reflection->hasProperty($propertyName)) {
+                $property = $reflection->getProperty($propertyName);
+                $property->setAccessible(true);
+                $value = $property->getValue($field);
+
+                if (str_contains($value, "config.{$configKey}")) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
     }
 
     public static function getDefaultConfig(): array
@@ -65,6 +119,7 @@ public static function getDefaultConfig(): array
             'hint' => null,
             'hintColor' => null,
             'hintIcon' => null,
+            'defaultValue' => null,
         ];
     }
 
@@ -82,6 +137,10 @@ public static function applyDefaultSettings($input, ?Field $field = null)
             $input->hintColor(Color::generateV3Palette($field->config['hintColor']));
         }
 
+        if (isset($field->config['defaultValue']) && $field->config['defaultValue'] !== null) {
+            $input->default($field->config['defaultValue']);
+        }
+
         return $input;
     }
 
diff --git a/src/Fields/MarkdownEditor.php b/src/Fields/MarkdownEditor.php
@@ -0,0 +1,78 @@
+<?php
+
+namespace Backstage\Fields\Fields;
+
+use Backstage\Fields\Contracts\FieldContract;
+use Backstage\Fields\Enums\ToolbarButton;
+use Backstage\Fields\Models\Field;
+use Filament\Forms;
+use Filament\Forms\Components\RichEditor as Input;
+
+class MarkdownEditor extends Base implements FieldContract
+{
+    public static function getDefaultConfig(): array
+    {
+        return [
+            ...parent::getDefaultConfig(),
+            'toolbarButtons' => ['attachFiles', 'blockquote', 'bold', 'bulletList', 'codeBlock', 'heading', 'italic', 'link', 'orderedList', 'redo', 'strike', 'table', 'undo'],
+            'disableToolbarButtons' => [],
+            'fileAttachmentsDisk' => 'public',
+            'fileAttachmentsDirectory' => 'attachments',
+            'fileAttachmentsVisibility' => 'public',
+        ];
+    }
+
+    public static function make(string $name, ?Field $field = null): Input
+    {
+        $input = self::applyDefaultSettings(Input::make($name), $field);
+
+        $input = $input->label($field->name ?? null)
+            ->toolbarButtons($field->config['toolbarButtons'] ?? self::getDefaultConfig()['toolbarButtons'])
+            ->disableToolbarButtons($field->config['disableToolbarButtons'] ?? self::getDefaultConfig()['disableToolbarButtons'])
+            ->fileAttachmentsDisk($field->config['fileAttachmentsDisk'] ?? self::getDefaultConfig()['fileAttachmentsDisk'])
+            ->fileAttachmentsDirectory($field->config['fileAttachmentsDirectory'] ?? self::getDefaultConfig()['fileAttachmentsDirectory'])
+            ->fileAttachmentsVisibility($field->config['fileAttachmentsVisibility'] ?? self::getDefaultConfig()['fileAttachmentsVisibility']);
+
+        return $input;
+    }
+
+    public function getForm(): array
+    {
+        return [
+            Forms\Components\Tabs::make()
+                ->schema([
+                    Forms\Components\Tabs\Tab::make('General')
+                        ->label(__('General'))
+                        ->schema([
+                            ...parent::getForm(),
+                        ]),
+                    Forms\Components\Tabs\Tab::make('Field specific')
+                        ->label(__('Field specific'))
+                        ->schema([
+                            Forms\Components\Grid::make(2)
+                                ->schema([
+                                    Forms\Components\Select::make('config.toolbarButtons')
+                                        ->label(__('Toolbar buttons'))
+                                        ->default(['attachFiles', 'blockquote', 'bold', 'bulletList', 'codeBlock', 'heading', 'italic', 'link', 'orderedList', 'redo', 'strike', 'table', 'undo'])
+                                        ->default(ToolbarButton::array()) // Not working in Filament yet.
+                                        ->multiple()
+                                        ->options(ToolbarButton::array())
+                                        ->columnSpanFull(),
+                                    Forms\Components\Grid::make(3)
+                                        ->schema([
+                                            Forms\Components\TextInput::make('config.fileAttachmentsDisk')
+                                                ->label(__('File attachments disk'))
+                                                ->default('public'),
+                                            Forms\Components\TextInput::make('config.fileAttachmentsDirectory')
+                                                ->label(__('File attachments directory'))
+                                                ->default('attachments'),
+                                            Forms\Components\TextInput::make('config.fileAttachmentsVisibility')
+                                                ->label(__('File attachments visibility'))
+                                                ->default('public'),
+                                        ]),
+                                ]),
+                        ]),
+                ])->columnSpanFull(),
+        ];
+    }
+}
diff --git a/src/Fields/Repeater.php b/src/Fields/Repeater.php
diff --git a/src/Fields/Select.php b/src/Fields/Select.php
