Filament Clusters Laravel Package

Getting Started

• Install with composer require and, if the package ships a panel plugin, register it in your PanelProvider (->plugin(...)); otherwise the Cluster component is available immediately as a form layout component.
• First place to look is the README plus the new workbench demo and screenshots added in v1.0.1 — they show a realistic multi-column, multi-row cluster with spans, which is faster to copy than to derive from the API docs.
• Minimal first use case: a two-column cluster holding a start/end date pair.

use Guava\FilamentCluster\Components\Cluster; // adjust to the package namespace

Cluster::make()
    ->columns(2)
    ->schema([
        DatePicker::make('start_date')
            ->label('Start date')
            ->required(),
        DatePicker::make('end_date')
            ->label('End date')
            ->required()
            ->afterOrEqual('start_date'),
    ]);

• Confirm the visual result in both light and dark mode before rolling it out — the component's whole value is its cell borders, so a quick browser check is the fastest smoke test.

Implementation Patterns

• Reach for a cluster instead of a Section when the fields are peers, not a titled group. Clusters read as a single bordered block (address blocks, date ranges, currency + amount pairs) and cut down on stacked section chrome in long forms.
• Drive layout with columns() plus per-field columnSpan(). A typical pattern is columns(2) with a full-width field in the middle of the grid (->columnSpan(2)) and the remaining fields flowing into the next row. Keep spans summing to the column count per intended row.
• Set explicit labels on every field inside a cluster. Since v1.0.1 the docs deliberately label demo fields so server-side validation reads naturally: “The end date field must be a date after or equal to start date.” Without labels, messages fall back to the attribute name (end_date). If you need a friendly name that differs from the visible label, use ->validationAttribute().
• Pair with cross-field rules. Clusters are a natural home for afterOrEqual, gt, required_with-style rules because the related inputs are visually adjacent; keep the rule on the dependent field and the label on both.
• Nest shallowly. A cluster inside a Section, a Tab, or a repeater item schema works well; clusters inside clusters get noisy and make border/span math harder to reason about.
• Use it inside repeaters/builders for repeated structured rows (e.g. line items with description/qty/price) — just keep columns() small so mobile stacking stays readable.
• Keep visibility logic consistent. If you conditionally hide a field with ->visible(), expect the grid to reflow; either hide the whole cluster or make sure remaining spans still fill the row.

Gotchas and Tips

• Upgrade to v1.0.1 if you use multi-row clusters or spans. Before this patch, first-row cells rendered a stray hairline along the top edge and row-leading cells rendered one on the left. If your layout is a single row with no spans you likely never saw it; if you have columns(2) with four+ fields, you did. Re-check any custom CSS that was papering over those edges — it will now double up.
• Span arithmetic is the main source of “broken” layouts. A columnSpan(2) in a columns(3) grid leaves a gap, and an odd number of fields in a 2-column grid leaves a dangling cell. Verify with the field count, not by eyeballing one screen size.
• Hidden fields shift everything after them. Conditional visibility inside a cluster is the most common cause of “the borders look wrong” — reproduce with the workbench demo before filing anything upstream.
• Validation wording is a labeling problem, not a package problem. If a message names a raw column, add ->label() (and optionally ->validationAttribute()) rather than overriding the translation.
• Theme/border color comes from the Filament panel. If hairlines look too heavy or invisible, adjust your panel's gray palette or a custom theme rather than fighting the component; confirm dark mode separately since contrast issues only show there.
• Debugging tip: compare your markup against the shipped workbench demo when borders or spans misbehave — diffing a known-good cluster isolates whether the issue is your columns()/columnSpan() configuration or your own CSS overrides.
• Extension points: extraAttributes() / custom classes on the cluster and its children, and (if exposed) a publishable view for deeper border/markup changes. Prefer these over global CSS targeting Filament's generated classes, which are not part of the package's stability contract.
• Version pinning: v1.0.1 is a patch with no breaking changes or deprecations, so a straightforward composer update is safe; still re-run your form tests that assert validation messages, since the docs' labeling guidance may reveal messages you were unknowingly asserting against raw attribute names.