CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7Filament is a full-stack UI framework for Laravel built with Livewire. It provides admin panels, forms, tables, notifications, actions, infolists, and widgets as composable packages.
8 
9## Critical: Naming Conventions
10 
11### Variable Names
12 
13**Never use abbreviated variable names.** Use full descriptive names:
14 
15```php
16// GOOD
17$exception, $component, $response, $configuration, $record, $livewire
18 
19// BAD - never do this
20$e, $comp, $res, $cfg, $rec, $lw
21```
22 
23Only exception: universally understood abbreviations like `$id`, `$url`.
24 
25### Pest Test Names
26 
27**Always use backticks for code references. Add `()` for methods:**
28 
29```php
30// GOOD
31it('can use `aspectRatio()` to force image cropping')
32it('returns `null` for `getImageCropAspectRatio()` by default')
33it('validates `$record` is an instance of `Model`')
34 
35// BAD - missing backticks
36it('can use aspectRatio to force image cropping')
37it('returns null for getImageCropAspectRatio by default')
38```
39 
40### Code Comments
41 
42**Use backticks when referencing code in comments:**
43 
44```php
45// GOOD
46// Uses `evaluate()` to resolve the `Closure`
47// Returns `null` if the `$record` is not set
48 
49// BAD
50// Uses evaluate() to resolve the Closure
51```
52 
53## Development Commands
54 
55**Always update tests when making changes.** For UI components, add browser tests using Pest Browser with `visit()`. Always call `assertNoAccessibilityIssues()` in both light and dark modes (`->inDarkMode()`).
56 
57```bash
58composer test              # Run all tests (SQLite + commands + PHPStan)
59composer test:sqlite       # Run tests with SQLite
60composer test:mysql        # Run tests with MySQL
61composer test:pgsql        # Run tests with PostgreSQL
62composer test:phpstan      # Run PHPStan static analysis
63composer cs                # Run all code style fixes (Rector + Pint + Prettier)
64
65npm run build              # Build all JS and CSS
66npm run build-demo         # Build and publish to ../demo if it exists
67 
68# Run a single test file
69vendor/bin/pest tests/src/Forms/Components/FileUploadTest.php
70 
71# Run a single test by name
72vendor/bin/pest --filter="it can use \`aspectRatio\(\)\` to force image cropping"
73```
74 
75## Coding Patterns
76 
77### Fluent API
78 
79Components use `make()` constructor and fluent chainable methods. Nullable properties have nullable setters so they can be undone:
80 
81```php
82TextInput::make('name')
83    ->label('Full name')
84    ->icon('heroicon-o-user')
85 
86// Property and setter share the same name, nullable to allow unsetting
87protected string | Closure | null $icon = null;
88 
89public function icon(string | Closure | null $icon): static
90{
91    $this->icon = $icon;
92 
93    return $this;
94}
95 
96// Getter prefixed with `get`, uses `evaluate()` for `Closure` support
97public function getIcon(): ?string
98{
99    return $this->evaluate($this->icon);
100}
101```
102 
103### Boolean Methods
104 
105```php
106// Property - `is`/`should`/`can`/`has` prefix, defaults `false`, supports `Closure`
107protected bool | Closure $isDisabled = false;
108 
109// Setter - verb form, defaults `true`, pass `false` to undo
110public function disabled(bool | Closure $condition = true): static
111{
112    $this->isDisabled = $condition;
113 
114    return $this;
115}
116 
117// Getter - cast to `bool`
118public function isDisabled(): bool
119{
120    return (bool) $this->evaluate($this->isDisabled);
121}
122```
123 
124### Static Closures
125 
126Use `static fn` when the closure doesn't use `$this`:
127 
128```php
129->placeholder(static fn (Select $component): ?string => $component->isDisabled() ? null : 'Select...')
130->visible(fn (): bool => $this->canView()) // Uses `$this`, cannot be static
131```
132 
133### Container Resolution
134 
135Use `app()` instead of `new` to allow users to bind custom implementations:
136 
137```php
138app(RelationshipJoiner::class)->prepareQuery($relationship) // Good
139(new RelationshipJoiner())->prepareQuery($relationship)     // Avoid
140```
141 
142### Extensibility
143 
144Do not use `final` or `readonly` classes - users need to extend Filament classes.
145 
146### Concerns and Contracts
147 
148Traits in `Concerns/` directories: `Can*` (capabilities), `Has*` (properties).
149Interfaces in `Contracts/` directories.
150 
151## Coding Standards
152 
153### PHPDoc
154 
155Only add when providing type info beyond native PHP types:
156 
157```php
158/** @var array<string, array{label: string, icon: string}> */  // Good
159/** @param string $name The name */                            // Redundant
160```
161 
162### Deprecations
163 
164Keep old public methods used in docs, mark deprecated:
165 
166```php
167/** @deprecated Use `newMethod()` instead. */
168public function oldMethod(): void
169{
170    return $this->newMethod();
171}
172```
173 
174## Architecture
175 
176### Packages (`packages/`)
177 
178Core: **support** (base utilities) → **schemas** (UI layouts) → **forms**, **infolists**, **tables**, **actions**, **notifications**, **widgets** → **panels** (full admin framework)
179 
180Other: query-builder, upgrade, spatie-laravel-media-library-plugin, spatie-laravel-settings-plugin, spatie-laravel-tags-plugin, spatie-laravel-google-fonts-plugin, spark-billing-provider
181 
182### Key Classes
183 
184- **Resources** (`packages/panels/src/Resources/`): CRUD interfaces for Eloquent models
185- **Pages** (`packages/panels/src/Pages/`): Livewire page components
186- **Schema Components** (`packages/schemas/src/Components/`): Base UI components
187- **Actions** (`packages/actions/src/`): Modal-based operations
188- **Panel** (`packages/panels/src/Panel.php`): Admin panel configuration
189 
190### File Locations
191 
192- Tests: `tests/src/{Forms,Tables,Actions,Panels}/`
193- Docs: `docs/` and `packages/{package}/docs/`
194- Views: `packages/{package}/resources/views/`
195- CSS: `packages/{package}/resources/css/`
196- Translations: `packages/{package}/resources/lang/{locale}/`
197 
198### CSS Hook Classes
199 
200**Never use Tailwind classes directly in Blade views.** All Tailwind classes must be in CSS files using `@apply`:
201 
202```css
203.fi-fo-field {
204    @apply grid gap-y-2;
205}
206```
207 
208Hook class naming:
209- Prefix: `fi-` with package codes (`fi-fo-` forms, `fi-ta-` tables, `fi-ac-` actions, etc.)
210- Abbreviations: `btn`, `col`, `ctn`, `wrp`
211 
212## Writing Documentation
213 
214**Always update documentation for user-facing features** in `packages/{package}/docs/`.
215 
216- **Tone**: Direct, second person ("You may set...", "You can do this using...")
217- **Structure**: Start with `## Introduction`, show simplest code first
218- **Headings**: Use gerunds ("Setting the type" not "Type settings", "Enabling search" not "Search")
219- **Formatting**: Backticks for code (`method()`, `ClassName`), include `use` statements
220- **Asides**: `<Aside variant="tip|info|danger">...</Aside>`
221 
222### Documentation Screenshots
223 
224Screenshots are in `docs-assets/screenshots/`. To add new screenshots:
225 
2261. **Add component examples** to the appropriate Livewire component in `docs-assets/app/app/Livewire/` (e.g., `Schemas/LayoutDemo.php`). Give each example a unique `->id()` for the selector:
227```php
228   Group::make()
229       ->id('myComponent')
230       ->extraAttributes(['class' => 'p-16 max-w-2xl'])
231       ->schema([
232           // Your component here
233       ]),
234```
235 
2362. **Add screenshot definitions** to `docs-assets/screenshots/schema.js`:
237```js
238   'schemas/layout/my-component/simple': {
239       url: 'schemas/layout',
240       selector: '#myComponent',
241       viewport: { width: 1920, height: 640, deviceScaleFactor: 3 },
242   },
243```
244 
2453. **Build assets** if you changed any CSS or JS files. Two builds are required — the repo root compiles each package's dist output, and the docs app has its own Vite build that bundles those outputs into `docs-assets/app/public/build/`. Skipping the second step leaves the docs app serving stale CSS, and screenshots will render against pre-change styles:
246```bash
247   # Terminal 1: compile package dist output
248   npm run build
249 
250   # Terminal 2: bundle the docs app's CSS from the package output
251   cd docs-assets/app && npm run build
252```
253   If you also changed the Livewire demo or Blade views, clear caches afterwards: `cd docs-assets/app && php artisan optimize:clear`.
254 
2554. **Generate screenshots**:
256```bash
257   # Terminal 1: Start the app server (must use default port 8000)
258   cd docs-assets/app && php artisan serve
259 
260   # Terminal 2: Run from the screenshots directory
261   cd docs-assets/screenshots
262   export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
263   export PUPPETEER_EXECUTABLE_PATH=$(which chromium)
264   node script.js &quot;schemas/layout/my-component/*&quot;  # Filter pattern
265```
266 
267   **Important:** The script expects `http://127.0.0.1:8000`. Don't use a custom port.
268 
2695. **Use in docs** with `<AutoScreenshot name="schemas/layout/my-component/simple" alt="Description" version="4.x" />`
270 
271Screenshots are generated in `images/light/` and `images/dark/`. Use natural, realistic content - not test-like examples.
272