Filament Flexbox Laravel Package

Getting Started

• Install with composer require zvizvi/filament-flexbox and note the version constraint: v0.0.1 is the first tagged release, so pin explicitly ("zvizvi/filament-flexbox": "^0.0.1") and expect the public API to move before 1.0.
• The release notes for v0.0.1 are effectively empty (only the changelog link), so the README and the src/ tree are your real specification. Read in this order: composer.json (supported Filament/PHP versions), the service provider (what gets registered), then the component class (what fluent methods actually exist).
• Verify panel compatibility first. Open composer.json and check whether the constraint targets Filament v3 (^3.0) or v4 (^4.0); a brand-new 0.0.1 package is usually built against a single major.
• First use case: a row of form fields that should share horizontal space with a fixed gap, where Grid::make() feels heavy. Drop the component into a resource form schema and confirm it renders before investing further:

use Zvizvi\FilamentFlexbox\Components\Flexbox; // confirm namespace from src/

Flexbox::make([
    TextInput::make('first_name'),
    TextInput::make('last_name'),
])

• Because there is no migration path to assess yet, treat v0.0.1 as a spike: build one throwaway form with it, screenshot the result at sm/md/lg, and only then roll it into real resources.

Implementation Patterns

• Read the component signature before writing schemas. In a 0.0.1 package the fluent API is the author's first draft. Dump the public methods (->direction(), ->wrap(), ->gap(), ->align(), ->justify() and friends are the conventional set, but do not assume names) and build a single internal cheat sheet your team codes against.
• Use it as a layout container, not a field. Treat it like Section/Grid: it holds Component children and contributes no state of its own. That means ->statePath() and ->relationship() belong on the children, never on the flexbox.
• Responsive rows. The pattern that justifies the dependency is a desktop row collapsing to a stack on mobile. Express it once in a shared schema method and reuse across resources rather than repeating inline flex configuration:

Flexbox::make([
    TextInput::make('city')->columnSpan(1),
    Select::make('country')->options(...)->columnSpan(1),
])->gap(4)   // verify method names against src/

• Nest deliberately. A flexbox inside a flexbox is the natural way to get a "field + trailing action" pair (input plus a ->suffixAction()-style button or a Placeholder). Keep nesting to two levels; beyond that the generated classes become impossible to reason about and you should reach for Grid with explicit columnSpan.
• Mix with native components at the boundaries. Flexbox composes cleanly inside Section, Tabs, and Wizard steps because it implements the same contract as any other schema component. Prefer Section for grouping-with-heading and Flexbox only for the alignment problem.
• Infolists and custom pages. If the component is registered on the generic schema container, the same class works in Infolist schemas and in Filament\Pages form definitions — confirm by grep for the registration call in the service provider rather than assuming.
• Lock the look in your own theme. Add overrides to your panel's custom CSS against the component's emitted wrapper class instead of passing long class strings through every call site; one place to fix when the package's markup changes between 0.x tags.

Gotchas and Tips

• 0.0.1 means no BC promise. Anything you learn from the source today can change in 0.0.2 without a deprecation. Constrain the version, and if the layout is load-bearing for your UI, vendor-copy the component class into your app so a package bump can't silently break production forms.
• Empty release notes are a signal, not an accident. There is no documented feature list, no upgrade guide, and no stated minimum Filament version beyond composer.json. Cross-check the constraint against your panel's installed version with composer why-not zvizvi/filament-flexbox if install fails on dependency resolution.
• Assets and registration. If the package ships views only, you need php artisan filament:assets (or a Vite build) after install; if it registers via a panel plugin, remember ->plugin(FlexboxPlugin::make()) in your PanelProvider — a missing registration typically means Class not found on the component rather than a render error.
• Debugging layout is CSS, not PHP. Inspect the rendered DOM in the browser and read the actual display:flex/gap output. Filament's own wrapper divs (fi-fo-component-ctn, grid containers) impose widths that fight flex children; if a field refuses to shrink, the culprit is usually a parent Grid column span, not the flexbox.
• Reactive fields break silently. Fields whose visibility depends on ->live() + ->visible() still occupy their flex slot unless hidden is applied. Verify with a conditional field; wrap conditionals in their own container if the space collapse misbehaves.
• Prefer Grid when you can. If you only need even columns, Filament's built-in Grid::make(2) is maintained upstream and gets new features first. Reserve this package for genuine alignment/justification needs — trailing buttons, baseline-aligned input rows, wrapping tag lists.
• Extension point to watch. The component's view is the cheapest place to add your own behaviour. Publish it (check the provider's loadViewsFrom/publishes calls) and override in resources/views/vendor/... so upstream updates to PHP logic don't clobber your tweaks.
• Track the changelog manually. With no release notes, subscribe to the repo's commits (https://github.com/zvizvi/filament-flexbox/commits/) — until 0.1.0 lands, review each diff before bumping.