Download the PHP package aureuserp/progress-bar without Composer

Progress Bar for Filament v5

A feature-rich **Filament v5** table column & infolist entry that renders progress as a horizontal bar. Built for dashboards, task progress, capacity gauges, skill levels, and any numeric value that fits on a 0–100% (or custom min–max) scale. --- ## Table of contents - [Features](#features) - [Requirements](#requirements) - [Installation](#installation) - [Quick start](#quick-start) - [API reference](#api-reference) - [Value](#value) - [Display](#display) - [Color](#color) - [Icon](#icon) - [Accessibility](#accessibility) - [Enums](#enums) - [Real-world example](#real-world-example) - [Theming & customisation](#theming--customisation) - [Translations](#translations) - [Publishing resources](#publishing-resources) - [Testing](#testing) - [Troubleshooting](#troubleshooting) - [Security](#security) - [Contributing](#contributing) - [Credits](#credits) - [License](#license) --- ## Features - **Table column** — drop into any Filament table as a percentage/gauge column - **Infolist entry** — read-only progress visualisation for detail pages - **4 sizes** — Tiny, Small, Medium, Large - **3 shapes** — Rounded, Pill, Square - **6 colors** — primary / success / warning / danger / info / gray, plus custom panel colors - **Threshold-driven colors** — `->thresholds([90 => 'success', 50 => 'warning', 0 => 'danger'])` - **Warn above** — `->warnAbove(100)` auto-flags over-budget values - **Stripes + animation** — striped or scrolling diagonal pattern overlay - **Indeterminate** — looping animation when the progress is unknown - **Gradient fill** — smooth left→right colour transition - **Label anywhere** — inside, outside, or hidden; custom formatter with full control - **Icons** — start/end icon adjacent to the label - **ARIA-compliant** — always emits `role="progressbar"`, `aria-valuenow/min/max`, `aria-label` - **Type-safe enums** — `Size::Large`, `Shape::Pill`, `LabelPosition::Outside`, `IconPosition::End`; strings still work - **Self-contained CSS** — Tailwind-compiled, no dependency on Filament's button/badge classes - **Translations** — `en` and `ar` shipped --- ## Requirements - PHP 8.2+ - Laravel 11+ - Filament v5+ - Tailwind CSS (via a custom Filament theme if you use Panels) --- ## Installation Service provider is auto-discovered. CSS is registered via `FilamentAsset` and published automatically during `artisan filament:assets`. --- ## Quick start ### Table column ### Infolist entry Both components extend Filament base classes (`Column` and `Entry`), so every standard method (`->label()`, `->sortable()`, `->toggleable()`, `->visible()`) still works. --- ## API reference ### Value ### Display ### Color Resolution order: `warnAbove` → `thresholds` → `color()` → fallback `primary`. ### Icon ### Accessibility Every render emits: For indeterminate bars, `aria-valuenow` is omitted (per the WAI-ARIA spec). --- ## Enums | Enum | Cases → values | Default | |---|---|---| | `Size` | `Tiny` → `'xs'`, `Small` → `'sm'`, `Medium` → `'md'`, `Large` → `'lg'` | `Size::Medium` | | `Shape` | `Rounded`, `Pill`, `Square` | `Shape::Rounded` | | `LabelPosition` | `Inside`, `Outside`, `None` | `LabelPosition::Inside` | | `IconPosition` | `Start`, `End` | `IconPosition::Start` | Each exposes a `default()` static. Setters accept `Enum | string | Closure`; getters return the string value so Blade `data-pb-*` attributes and the CSS keep working unchanged. --- ## Real-world example Adapted from a skill-level table (the pattern that originally motivated the extraction): Task progress in a project dashboard: --- ## Theming & customisation The plugin ships a Tailwind-compiled CSS bundle keyed on stable data attributes you can target in your own theme: - `.pb-wrapper` — outer wrapper (flex column, used for outside-label layout) - `.pb-track` — the track - `.pb-fill` — the filled portion - `.pb-label` / `.pb-label-outside` — label text - `.pb-icon` — icon inside the label Data attributes on `.pb-track`: - `data-pb-size="xs|sm|md|lg"` — height - `data-pb-shape="rounded|pill|square"` — corner radius - `data-pb-color="primary|success|warning|danger|info|gray|…"` — drives `--pb-color-500/600` CSS variables - `data-pb-indeterminate="true|false"` — triggers the slide animation Data attributes on `.pb-fill`: - `data-pb-striped="true"` — adds diagonal stripes - `data-pb-animated="true"` — animates the stripes - `data-pb-gradient="true"` — left→right colour gradient - `data-pb-full="true"` — set when progress is 100% (used to switch label colour to white) ### Custom colors Register a panel color and reference it in the progress bar: --- ## Translations Ships with `en` and `ar` under the `progress-bar::` namespace for aria labels and enum display names. Publish to override: --- ## Publishing resources --- ## Testing The plugin ships a full Pest suite covering: | Area | Coverage | |---|---| | Architecture | Column extends `Filament\Tables\Columns\Column`, Entry extends `Filament\Infolists\Components\Entry`, shared trait used on both, Plugin implements `Filament\Contracts\Plugin`, no debug calls in shipped code | | Value API | `max`, `min`, `value`, `precision`, `formatLabel`, `getPercentage` edge cases (>100, <0, non-numeric, reversed min/max) | | Layout API | `size`, `shape`, `labelPosition`, `showLabel` — enum + string input, default fallback | | Behaviour | `striped`, `animated` (auto-enables striped), `indeterminate`, `gradient` | | Status / threshold | `thresholds()` + `warnAbove()` correctly map value → color | | Enum input | `Size::Large`, `Shape::Pill`, `LabelPosition::Outside`, `IconPosition::End` round-trip | | Content | `formatLabel` closure, `icon` + `iconPosition`, `precision` formatting | | Component instantiation | Base class, view paths, fluent chaining, Column-only `color()` / Infolist `color()` | Fixtures live at `tests/Feature/Fixtures/`. --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | `Target class not found` | Autoload cache stale | `composer dump-autoload && php artisan optimize:clear` | | View not found | Service provider not registered | `php artisan package:discover` | | Styles missing | Filament asset cache stale | `php artisan filament:assets` | | Bar stays empty | `max()` is smaller than current value, or `min()` equals `max()` | Verify `min < max` and the resolved state is numeric | --- ## Security Email `[email protected]` for security-related reports instead of opening a public issue. --- ## Contributing PRs welcome. Before submitting: When adding a new option: 1. Define a `BackedEnum` under `src/Enums/` if the option is one of a fixed set. 2. Accept both the enum and the raw string in the setter signature. 3. Add coverage under `tests/Feature/Unit/`. 4. Document the option in the [API reference](#api-reference) and [Enums](#enums) sections. --- ## Credits - [AureusERP](https://aureuserp.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).