Progress Stepper Laravel Package

Getting Started

• Install with composer require aureuserp/progress-stepper. If the package registers a Filament plugin, add it to your panel provider (->plugin(ProgressStepperPlugin::make())); otherwise the ProgressStepper component is available directly in form schemas — check the package README for the exact registration path for your Filament version.
• Look first at the form schema where you already define a Filament Wizard. The stepper is meant to sit in the same schema and mirror the wizard's steps, so that file is your primary integration point.
• First use case: a multi-step form header. Drop ProgressStepper::make() above your Wizard, label it with the same step names, and optionally set ->size(Size::Small) to keep it compact. That alone gives users a persistent "where am I" indicator across long forms.

Implementation Patterns

• Wizard header pattern. Define the stepper immediately before the Wizard component in the schema and keep step labels in a single array/property shared by both, so labels cannot drift when steps are added or reordered.
• Sizing as configuration, not hard-coding. Prefer ->size(Filament\Support\Enums\Size::Small) over string literals. As of v1.0.2, size() accepts the Size enum, null, or a string; unsupported values fall back to md instead of throwing.
• Centralise panel styling. If several resources use the stepper, wrap it in a small helper (e.g. App\Support\Forms\ProgressStepperHeader::make()) that applies your panel's default size and styling. That keeps a future Filament API change to one file.
• Reactive step binding. Where the component exposes current-step binding, pass a closure reading the wizard state rather than a static value, so the stepper updates as users navigate backwards and forwards.
• Version-gated rollout. If you support both older and newer Filament versions across apps, guard any Size:: enum usage behind a Filament version check, or standardise on string sizes that are valid on both.
• Integration tip. Treat the stepper as presentation only — keep validation and navigation in the Wizard. This avoids coupling your business logic to a UI component that tracks Filament's internal APIs.

Gotchas and Tips

• Upgrade if you're on Filament 5.9+. v1.0.2 fixes a fatal error caused by ProgressStepper::size() and its backing property being incompatible with the size() API ToggleButtons gained in Filament 5.9. Check your composer.lock for the Filament version before debugging anything else.
• Silent fallback hides typos. Unsupported sizes now fall back to md rather than erroring. A misspelled size string will render at medium and give you no warning — verify sizes visually or assert them in a test.
• null is valid and meaningful. ->size(null) is accepted; don't assume it means "unset/inherit from ToggleButtons" — it resolves through the component's own fallback path.
• Subclassing is the sharp edge. If you extended ProgressStepper and overrode size() or the backing property, your signature must stay compatible with the parent's new one. Re-check custom subclasses after upgrading, since a mismatched override reintroduces the fatal error the release fixed.
• Clear caches after upgrading. Run php artisan filament:clear-cached-components (or your panel's equivalent) and php artisan config:clear if the old component signature appears to persist.
• Debugging tip. A fatal error mentioning size() on Filament 5.9 is almost always a stale package version or a custom override — confirm the constraint resolves to ^1.0.2 before opening an issue.
• Extension points. Subclassing for custom rendering is supported, but keep the size() signature and property type aligned with the parent; prefer composition (wrapping the component in your own helper) over overriding core methods.