Progress Stepper Laravel Package

Product Decisions This Supports

• Multi-step flow UX in Filament admin panels. This package supplies a progress-stepper UI primitive, so it directly supports decisions about how we present wizards, onboarding sequences, checkout/order flows, approval chains, and import/export pipelines inside our Filament-based admin surface. It is a presentation-layer component, not a workflow engine — adopting it does not decide whether we model steps in the backend, only how those steps are surfaced.
• Build vs. buy for UI primitives. A stepper is a small, well-understood component. The realistic comparison is a few days of internal design/dev work (plus ongoing upkeep against Filament's design system) versus adopting a tiny third-party package. This tilts toward "adopt" for internal tooling and toward "build/inline" only where the stepper is a customer-facing brand surface.
• Standardizing on Filament's design system. The v1.0.2 fix shows the component is tracking Filament's own component APIs (ToggleButtons, Size enum). If we have committed to Filament as our admin stack, a stepper that follows Filament's sizing conventions keeps our UI consistent and reduces bespoke CSS/design debt.
• Roadmap sequencing for admin UX work. Because the component is cheap to adopt, step-based flows can be scheduled as incremental improvements to existing screens rather than as a dedicated design-system initiative.
• Maintenance/dependency posture. This release is a compatibility patch, not a capability release — it does not open new product use cases, but it does confirm the maintainer is responsive to upstream breakage, which is a relevant input to the "is this safe to depend on" decision.

When to Consider This Package

Consider adoption when:

• We are already running Filament for the admin/back-office and want step indicators that match the surrounding UI rather than a custom component.
• The need is a visual progress indicator for a linear, small-to-medium step count (roughly 3–7 steps) — forms, wizards, setup flows, order/fulfillment stages.
• We want low integration cost: this is a UI component, so it can be dropped into an existing page without backend or data-model changes.
• We can pin the Filament version and re-test on Filament upgrades. The v1.0.2 bug is instructive: ProgressStepper::size() collided with ToggleButtons::size() introduced in Filament 5.9, producing a fatal error. That is not a cosmetic regression — it's a hard break triggered by an upstream minor release. Treat Filament upgrades as requiring a stepper smoke test.
• The project tolerates a young dependency. At v1.0.x with a small issue count, the package is early-stage; API surface and upstream-coupling risk are real.

Look elsewhere (or build in-house) when:

• The stepper is customer-facing and brand-critical, where owning the markup/accessibility contract matters more than saving a few days.
• We need branching, non-linear, or stateful workflow logic (conditional steps, resumable drafts, per-step validation orchestration). This package renders progress; it does not manage workflow state — that remains ours to build.
• We are not on Filament, or are on a materially different Filament major version than the one this release targets (5.9+). Compatibility is narrow and actively moving.
• We need guaranteed long-term support, SLAs, or an accessibility audit trail — a single-maintainer package is unlikely to clear that bar.
• Our strict dependency/security policy (e.g., required CVE monitoring, signed releases, vendor review) can't accommodate a low-adoption third-party UI package.

How to Pitch It (Stakeholders)

For executives (one paragraph): We're evaluating a small open-source UI component that adds step-by-step progress indicators to our Filament admin interface. It's a low-cost, low-risk convenience — it saves design and engineering time on multi-step screens like setup wizards and order stages — rather than a platform decision. The newly released v1.0.2 is a maintenance fix: it resolves a crash that occurred when our version of Filament introduced a conflicting size() method, and it makes the component more tolerant of invalid size inputs by falling back to a default. No new functionality and no breaking changes. The takeaway for planning is that this is a young, tightly-coupled dependency: cheap to adopt, but it requires us to pin versions and re-test on Filament upgrades. We recommend adopting it for internal admin UI only, and not for customer-facing brand surfaces.

For engineering:

• What shipped in v1.0.2: two fixes, no features, no deprecations. (1) A fatal error on Filament 5.9+ caused by ProgressStepper::size() and its backing property colliding with the size() API newly added to ToggleButtons (issue #6) — the method/property are now kept compatible with the upstream signature. (2) size() now accepts Filament\Support\Enums\Size and null, with unsupported sizes falling back to md instead of failing.
• Why it matters: fix (1) is a hard-break repair, which tells us the component extends or mirrors Filament internals closely enough that a Filament minor release can take down a page. Budget for a stepper regression check in your Filament upgrade runbook, and pin filament/filament to a tested minor.
• Why it's low-risk to adopt now: fix (2) is a defensive loosening of the input contract — callers passing an enum or null (including config-driven or user-controlled sizes) no longer throw. That's a backward-compatible widening; existing integer/string call sites are unaffected.
• What it does not do: no branching logic, no step-state persistence, no validation orchestration. We still own the workflow model; this only renders it.
• Suggested guardrails: pin the Filament minor version, add one smoke test that renders the stepper on our Filament version, and wrap the component in a thin internal adapter so a future upstream collision can be patched in one place rather than across every screen.