Skip to content

Commit 6393924

Browse files
jeffersongoncalvesclaude
jeffersongoncalves
and
claude
committed
Add Laravel Boost guidelines and skills
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 36476c4 commit 6393924

2 files changed

Lines changed: 254 additions & 0 deletions

File tree

‎resources/boost/guidelines/core.blade.php‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
## Filament Ace Editor Field
2+
3+
A Filament form field that integrates the Ace code editor, providing syntax-highlighted code editing with configurable modes, themes, and dark mode support. Requires Filament 5.0+ and PHP 8.2+.
4+
5+
### Installation
6+
7+
@verbatim
8+
<code-snippet name="Install the plugin" lang="bash">
9+
composer require jeffersongoncalves/filament-ace-editor-field:"^2.0"
10+
</code-snippet>
11+
@endverbatim
12+
13+
### Publish Config
14+
15+
@verbatim
16+
<code-snippet name="Publish config file" lang="bash">
17+
php artisan vendor:publish --tag=filament-ace-editor-field-config
18+
</code-snippet>
19+
@endverbatim
20+
21+
### Basic Usage
22+
23+
@verbatim
24+
<code-snippet name="Use AceEditorInput in a form" lang="php">
25+
use JeffersonGoncalves\Filament\AceEditorField\Forms\Components\AceEditorInput;
26+
27+
AceEditorInput::make('code')
28+
->mode('html')
29+
->theme('monokai')
30+
->height('16rem')
31+
->required();
32+
</code-snippet>
33+
@endverbatim
34+
35+
### Key Methods
36+
37+
- `mode(string $mode)` - Set Ace editor language mode (e.g., `'html'`, `'php'`, `'javascript'`, `'css'`)
38+
- `theme(string $theme)` - Set Ace editor theme (e.g., `'monokai'`, `'github'`, `'twilight'`)
39+
- `darkTheme(string $theme)` - Set a separate theme for dark mode
40+
- `disableDarkTheme()` - Disable automatic dark theme switching
41+
- `height(string $height)` - Set editor height (default: `'16rem'`)
42+
- `editorOptions(array $options)` - Merge custom Ace editor options
43+
- `editorConfig(array $config)` - Merge custom editor configuration
44+
- `addExtensions(array $extensions)` - Add Ace editor extensions
45+
- `autosize(bool $condition)` - Enable auto-sizing
46+
- `cols(int $cols)` / `rows(int $rows)` - Set columns/rows
47+
48+
### Architecture
49+
50+
- **Namespace**: `JeffersonGoncalves\Filament\AceEditorField`
51+
- **Component**: `AceEditorInput` extends `Filament\Forms\Components\Field`
52+
- **Service Provider**: `AceEditorFieldServiceProvider` (auto-discovered)
53+
- **Config**: `filament-ace-editor-field.php` (base_url, file, extensions, editor_config, editor_options, dark_mode)
54+
55+
### Best Practices
56+
57+
- Always set a `mode()` matching the content language for proper syntax highlighting
58+
- Use `darkTheme()` for consistent appearance across light/dark Filament themes
59+
- Configure extensions and editor options via the published config file for project-wide defaults
60+
- The component extends `Field`, not `TextInput` -- use `placeholder()` and `required()` as usual

‎resources/boost/skills/ace-editor-field-development/SKILL.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
name: ace-editor-field-development
3+
description: Build and work with the Filament Ace Editor Field plugin, including code editor forms, syntax highlighting modes, themes, dark mode support, and editor configuration.
4+
---
5+
6+
# Ace Editor Field Development
7+
8+
## When to use this skill
9+
10+
Use this skill when:
11+
- Adding a code editor field to a Filament form
12+
- Configuring syntax highlighting modes (HTML, PHP, JavaScript, CSS, etc.)
13+
- Customizing Ace editor themes and dark mode behavior
14+
- Setting editor dimensions, options, and extensions
15+
- Troubleshooting Ace editor rendering or asset loading issues
16+
17+
## Architecture
18+
19+
### Namespace
20+
```
21+
JeffersonGoncalves\Filament\AceEditorField
22+
```
23+
24+
### Key Classes
25+
26+
| Class | Path | Description |
27+
|-------|------|-------------|
28+
| `AceEditorInput` | `src/Forms/Components/AceEditorInput.php` | Main form field component extending `Filament\Forms\Components\Field` |
29+
| `AceEditorFieldServiceProvider` | `src/AceEditorFieldServiceProvider.php` | Service provider that registers views, config, and assets |
30+
31+
### Dependencies
32+
- `filament/filament: ^5.0`
33+
- `spatie/laravel-package-tools: ^1.14.0`
34+
35+
## Configuration
36+
37+
### Publish Config
38+
39+
```bash
40+
php artisan vendor:publish --tag=filament-ace-editor-field-config
41+
```
42+
43+
The config file `filament-ace-editor-field.php` contains:
44+
- `base_url` - Base URL for Ace editor CDN assets
45+
- `file` - Ace editor main JS file path
46+
- `extensions` - Available Ace extensions map
47+
- `enabled_extensions` - Extensions enabled by default
48+
- `editor_config` - Default editor configuration
49+
- `editor_options` - Default Ace editor options
50+
- `dark_mode.enable` - Whether dark mode theme switching is enabled
51+
- `dark_mode.theme` - Theme to use in dark mode
52+
53+
## Features
54+
55+
### Basic Code Editor
56+
57+
```php
58+
use JeffersonGoncalves\Filament\AceEditorField\Forms\Components\AceEditorInput;
59+
60+
AceEditorInput::make('code')
61+
->mode('php')
62+
->theme('monokai')
63+
->height('20rem')
64+
->required();
65+
```
66+
67+
### Setting Language Mode
68+
69+
The `mode()` method sets the Ace editor language mode. It automatically prepends `ace/mode/`:
70+
71+
```php
72+
AceEditorInput::make('content')
73+
->mode('html'); // Sets ace/mode/html
74+
75+
AceEditorInput::make('script')
76+
->mode('javascript'); // Sets ace/mode/javascript
77+
78+
AceEditorInput::make('styles')
79+
->mode('css'); // Sets ace/mode/css
80+
```
81+
82+
### Setting Themes
83+
84+
The `theme()` method sets the light mode theme. It automatically prepends `ace/theme/`:
85+
86+
```php
87+
AceEditorInput::make('code')
88+
->theme('github'); // Sets ace/theme/github
89+
```
90+
91+
### Dark Mode Support
92+
93+
Configure a separate theme for dark mode, or disable automatic dark mode switching:
94+
95+
```php
96+
// Set a dark mode theme
97+
AceEditorInput::make('code')
98+
->theme('chrome')
99+
->darkTheme('twilight');
100+
101+
// Disable dark mode theme switching entirely
102+
AceEditorInput::make('code')
103+
->theme('monokai')
104+
->disableDarkTheme();
105+
```
106+
107+
### Custom Editor Options
108+
109+
Merge additional Ace editor options (these are passed directly to the Ace API):
110+
111+
```php
112+
AceEditorInput::make('code')
113+
->mode('php')
114+
->editorOptions([
115+
'fontSize' => 14,
116+
'showGutter' => true,
117+
'showPrintMargin' => false,
118+
'tabSize' => 4,
119+
'useSoftTabs' => true,
120+
'wrap' => true,
121+
]);
122+
```
123+
124+
### Editor Configuration
125+
126+
```php
127+
AceEditorInput::make('code')
128+
->editorConfig([
129+
'basePath' => '/custom/ace/path',
130+
]);
131+
```
132+
133+
### Adding Extensions
134+
135+
```php
136+
AceEditorInput::make('code')
137+
->addExtensions(['emmet', 'language_tools']);
138+
139+
// With a custom callback
140+
AceEditorInput::make('code')
141+
->addExtensions(['emmet'], function ($existing, $new) {
142+
return $existing->merge($new)->unique();
143+
});
144+
```
145+
146+
### Sizing
147+
148+
```php
149+
AceEditorInput::make('code')
150+
->height('30rem') // Set height (default: '16rem')
151+
->cols(80) // Set columns
152+
->rows(20) // Set rows
153+
->autosize(); // Enable auto-sizing
154+
```
155+
156+
### Read-Only Mode
157+
158+
The editor automatically enters read-only mode when the field is disabled:
159+
160+
```php
161+
AceEditorInput::make('code')
162+
->mode('json')
163+
->disabled();
164+
```
165+
166+
## Internal Behavior
167+
168+
### State Management
169+
170+
- `afterStateHydrated`: Sets the component state from the model value
171+
- `afterStateUpdated`: Validates the field path on the Livewire component
172+
- `initializeConfigurations()`: Reads all defaults from the published config file on `setUp()`
173+
174+
### Editor Options Resolution
175+
176+
`getEditorOptions()` merges custom options with a `readOnly` flag derived from `$this->isDisabled()`.
177+
178+
## Troubleshooting
179+
180+
### Editor Not Rendering
181+
**Cause**: Assets not loaded or Alpine component not registered.
182+
**Solution**: Ensure the service provider is auto-discovered. Clear caches with `php artisan filament:assets` and `php artisan view:clear`.
183+
184+
### Syntax Highlighting Not Working
185+
**Cause**: Incorrect mode name.
186+
**Solution**: Use the Ace mode name without the `ace/mode/` prefix (e.g., `'php'` not `'ace/mode/php'`). The `mode()` method adds the prefix automatically.
187+
188+
### Dark Theme Not Switching
189+
**Cause**: Dark mode disabled in config or `disableDarkTheme()` called.
190+
**Solution**: Check `filament-ace-editor-field.dark_mode.enable` in config, or ensure `disableDarkTheme()` is not called on the component.
191+
192+
### Extensions Not Loading
193+
**Cause**: Extension not defined in config file.
194+
**Solution**: Publish the config and ensure the extension is listed in the `extensions` array with its CDN URL.

0 commit comments

Comments
 (0)