Download the PHP package batistackapp/progress-stepper without Composer

Progress Stepper for Filament v5

A feature-rich Filament v5 plugin that renders workflow state as an interactive arrow-stepper (form) or a read-only status bar (infolist). Built for business apps where orders, applications, or projects move through named states and you want every screen to show that progress visually.

--- ## Table of contents - [Features](#features) - [Requirements](#requirements) - [Installation](#installation) - [Quick start](#quick-start) - [API reference](#api-reference) - [Options](#options) - [State behaviour](#state-behaviour) - [State colors](#state-colors) - [Layout](#layout) - [Per-step enrichment](#per-step-enrichment) - [Icons](#icons) - [Enums](#enums) - [Real-world example](#real-world-example) - [Theming & customisation](#theming--customisation) - [Overridable icons](#overridable-icons) - [Translations](#translations) - [Publishing resources](#publishing-resources) - [Testing](#testing) - [Troubleshooting](#troubleshooting) - [Naming notes](#naming-notes) - [Security](#security) - [Contributing](#contributing) - [Credits](#credits) - [License](#license) --- ## Features - **Form component** (extends `ToggleButtons`) — interactive radio/checkbox stepper - **Infolist entry** — read-only status visualisation - **4 state colors** — completed, current, upcoming, error — each overridable - **Auto-mark completed** — `markCompletedUpToCurrent()` paints every step before the active one - **Error states** — flag any states as danger via `errorStates([…])` - **Hide states conditionally** — `hideStatesFor(fn)` based on the current record - **BackedEnum integration** — `optionsFromEnum(MyStatus::class)` auto-derives labels / icons / colors - **Type-safe enums** — `Size::Large`, `Direction::Vertical`, `Theme::Outlined`, `ConnectorShape::Chevron`, `StepStatus::Completed` — strings still work for backwards compatibility - **3 sizes** — sm / md / lg - **2 directions** — horizontal / vertical - **4 connector shapes** — arrow / chevron / dot / line - **3 themes** — filled / outlined / minimal - **Step numbering** — `showIndex()` prepends 1., 2., 3. - **Icon-only (compact)** mode for tight navigation bars - **Per-step content** — descriptions, tooltips, badges, icons - **Overridable icons** via `FilamentIcon::register()` - **Translations** shipped for `en` and `ar` - **Full Pest test coverage** — 74 tests across architecture, API, status resolver, enum input, and component instantiation --- ## Requirements - PHP 8.2+ - Laravel 11+ - Filament v5+ - Tailwind CSS (via a custom Filament theme if you use Panels) --- ## Installation The service provider is auto-discovered. The component CSS is registered via `FilamentAsset` and published automatically during `artisan filament:assets`. --- ## Quick start ### Form component ### Infolist entry Both components extend normal Filament base classes (`ToggleButtons` and `Entry`), so all standard Filament methods — `->label()`, `->helperText()`, `->visible()`, `->columnSpanFull()`, `->state()` — still work. --- ## API reference All methods return `static` so they chain. Each accepts either a scalar value or a `Closure` where applicable (per Filament's standard pattern). ### Options #### BackedEnum integration Implement `HasLabel`, `HasColor`, `HasIcon` on your enum and every case's label / icon / color is picked up automatically: ### State behaviour ### State colors Each slot accepts any Filament color token (`primary`, `success`, `warning`, `danger`, `info`, `gray`, custom) or a `Closure`. ### Layout Each layout setter accepts either the dedicated **enum** (recommended — IDE autocomplete, compile-time checked) or the raw **string** (quick one-offs, backward compatible): Unknown values silently fall back to the enum's `default()` case, so misspellings never crash a page. ### Per-step enrichment Each accepts an `array` OR a `Closure($value, $label, $state)`: Example: ### Icons The form component inherits `icons()` from `ToggleButtons`; the infolist component declares its own. --- ## Enums The plugin ships five `BackedEnum`s under `Webkul\ProgressStepper\Enums` so you can use symbolic constants instead of magic strings. Every string value matches what the CSS `data-ps-*` attributes expect, so passing an enum produces the same rendered output as the equivalent string. | Enum | Cases → values | Default | |---|---|---| | `Size` | `Small` → `'sm'`, `Medium` → `'md'`, `Large` → `'lg'` | `Size::Medium` | | `Direction` | `Horizontal`, `Vertical` | `Direction::Horizontal` | | `Theme` | `Filled`, `Outlined`, `Minimal` | `Theme::Filled` | | `ConnectorShape` | `Arrow`, `Chevron`, `Dot`, `Line` | `ConnectorShape::Arrow` | | `StepStatus` | `Completed`, `Current`, `Upcoming`, `Error` | (internal; returned by `getStepStatus()`) | Each of the first four exposes a `default()` static method that returns the case used when no explicit value is set or when an unknown value falls through — useful for building resilient defaults in custom code. ### Enum usage ### Interop with `getStepStatus()` Need to inspect the classification of a step programmatically? Round-trip through `StepStatus::from(...)`: --- ## Real-world example Adapted from a Sales Order Resource — mirrors the aureuserp pattern, mixing the `Size` / `ConnectorShape` enums with a domain `OrderStatus` enum: --- ## Theming & customisation ### Custom colors Any color registered on your panel flows through automatically. Just reference its key: ### Extending the CSS The plugin styles ship at `vendor/aureuserp/progress-stepper/resources/dist/progress-stepper.css`. Publish it if you want to fork it: Or override selectors in your own theme CSS — the stable hooks are: - `.ps-container` — outer wrapper - `.ps-step` — each step wrapper - `.ps-button` — the rendered stepper segment - `.ps-label`, `.ps-label-text`, `.ps-index`, `.ps-description`, `.ps-badge` — inner label parts - `data-ps-direction | data-ps-size | data-ps-theme | data-ps-separator | data-ps-compact | data-ps-inline` on `.ps-container` — values match the `Direction`, `Size`, `Theme`, `ConnectorShape` enum values - `data-ps-status="completed | current | upcoming | error"` — values match `StepStatus` enum values - `data-ps-color="primary | success | warning | danger | info | gray | "` — drives the `--ps-color-500` / `--ps-color-600` CSS variables that the filled / outlined / minimal themes consume --- ## Overridable icons The plugin registers three aliases you can override globally: | Alias | Default | |---|---| | `progress-stepper::step-completed` | `heroicon-m-check` | | `progress-stepper::step-current` | `heroicon-m-arrow-right` | | `progress-stepper::step-error` | `heroicon-m-x-mark` | --- ## Translations The plugin ships `en` and `ar` translations under the `progress-stepper::` namespace for status / separator / theme labels used internally. Publish them to customise: Files appear in `lang/vendor/progress-stepper/{locale}/progress-stepper.php`. --- ## Publishing resources --- ## Testing The plugin ships with a full Pest test suite covering every public API surface. **74 tests** (148 assertions) across: | Area | Coverage | |---|---| | Architecture | Components extend `ToggleButtons` / `Entry`, shared trait used on both, Plugin implements `Filament\Contracts\Plugin`, ServiceProvider extends Spatie `PackageServiceProvider`, no debug calls (`dd`, `dump`, `var_dump`, `ray`, `die`, `exit`) in shipped code | | State colors | Defaults, scalar setters, closure setters, chaining | | State behaviour | `markCompletedUpToCurrent`, `errorStates`, `hideStatesFor` | | Layout API | `size`, `direction`, `theme`, `connectorShape`, `showIndex`, `iconOnly` — value acceptance and default-fallback | | Content enrichment | `stepDescription`, `stepTooltip`, `stepBadge` — arrays, closures, empty-value coercion | | Status resolver | `getStepStatus` / `getStepColor` across completed / current / upcoming / error; `errorStates` overrides; custom color overrides | | Enum input | `Size::Large`, `Direction::Vertical` etc. produce the same strings as raw equivalents; string inputs still work; closures returning enums work | | `optionsFromEnum` | Derives labels from `HasLabel`, icons from `HasIcon`, colors from `HasColor`; safely ignores non-enum classes | | Component instantiation | Base class assertions, view paths, chainable API, `inline()`, `getColor()` delegation | Fixtures live at `tests/Feature/Fixtures/` (only a `SampleStatus` BackedEnum). --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | `Target class [Webkul\ProgressStepper\Forms\…] not found` | Autoload cache is stale | `composer dump-autoload && php artisan optimize:clear` | | View `progress-stepper::forms.progress-stepper` not found | Service provider not registered | Check the provider is in `bootstrap/providers.php` or that package discovery ran (`php artisan package:discover`) | | Steps render without arrows / colors | Filament asset cache stale | `php artisan filament:assets` | | Form component throws `Declaration of … must be compatible with Filament\Schemas\Components\Component::…` | You called one of the legacy methods (`separator()`, `compact()`, `description()`, `tooltip()`, `badge()`) which collide with Filament base traits | Use the prefixed names: `connectorShape()`, `iconOnly()`, `stepDescription()`, `stepTooltip()`, `stepBadge()` | --- ## Naming notes Five method names on this plugin intentionally **differ** from the natural English word to avoid collisions with Filament's base traits: | Natural name | Use this instead | Why | |---|---|---| | `separator()` | `connectorShape()` | `Component::separator()` takes `string\|null = ','` | | `compact()` | `iconOnly()` | `CanBeCompact::compact()` exists | | `description()` | `stepDescription()` | `HasDescription::description()` exists | | `tooltip()` | `stepTooltip()` | `HasTooltip::tooltip()` exists | | `badge()` | `stepBadge()` | `HasBadge::badge()` exists | --- ## Security If you discover a security vulnerability, email `[email protected]` rather than opening a public issue. --- ## Contributing PRs welcome. Please run the test suite before submitting: When adding a new configuration option, please: 1. Define (or extend) a `BackedEnum` under `src/Enums/` if the option is one of a fixed set of values. 2. Accept both the enum and the raw string in the setter signature for backward compatibility. 3. Add coverage to the relevant test file under `tests/Feature/Unit/`. 4. Document the option in the [API reference](#api-reference) and [Enums](#enums) sections as appropriate. --- ## Credits - [Webkul](https://webkul.com) — plugin author - [Filament team](https://filamentphp.com) — the excellent admin framework - [filamentphp/plugin-skeleton](https://github.com/filamentphp/plugin-skeleton) — structural template --- ## License MIT. See [LICENSE.md](LICENSE.md).