pushinbr / pam-native-charts
Native charts for PAM Native: line, area, bar, donut, sparkline and progress ring drawn on pam-native-canvas.
Requires
- php: ^8.5
- pushinbr/pam-native: ^1.13
- pushinbr/pam-native-canvas: ^0.2
Requires (Dev)
- phpstan/phpstan: ^2.1
- pushinbr/pam-native-plugin-kit: ^0.2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-10 13:31:56 UTC
README
Native charts described once in PHP and painted by the platform.
Line, area, bar, donut, sparkline and progress ring, drawn as bounded display lists on pam-native-canvas: no per-frame PHP calls.
Install · Quick example · Platforms · Charts guide · Docs · Issues
Install
Inside a PAM Native project, add only this capability:
pam composer require pushinbr/pam-native-charts pam doctor --fix
New to PAM? Install the CLI and create a project first:
curl --proto '=https' --proto-redir '=https' --tlsv1.2 \ --connect-timeout 15 --max-time 60 --max-filesize 1048576 -fsSL \ https://github.com/push-in/pam/releases/latest/download/install.sh | sh pam init my-app --template native cd my-app
This package depends on pushinbr/pam-native-canvas, which Composer installs with it; pam doctor --fix regenerates the native integration.
Quick example
use Pam\Native\Charts\Curve; use Pam\Native\Charts\LineChart; use Pam\Native\Charts\Series; return LineChart::make(width: 328, height: 160) ->series(Series::make('Income', [120.5, 80, 140, 90, 200])) ->labels(['Mon', 'Tue', 'Wed', 'Thu', 'Fri']) ->curve(Curve::Monotone) ->area();
Every chart is an immutable, fluent builder and a Renderable: return it from a screen or component, or place the tag in a template. view() exposes the underlying CanvasView and scene() the raw display list for tests. Each chart type, its template tag and every option are in the charts guide.
Platform support
| Platform | Support | Notes |
|---|---|---|
| Android | API 26+ | Rendered by pam-native-canvas (Android Canvas) |
| iOS | 15.0+ | Rendered by pam-native-canvas (Core Graphics) |
| PAM Native | ^1.13 | From composer.json; pam-native-canvas ^0.2; PHP 8.5+ |
Requirements
This package is PHP-only (no pam-native.plugin.json, no native code, no permissions). Rendering and the Android API 26+ / iOS 15+ floor come from pam-native-canvas.
Design rules
The charts follow one small visual system so they read as a family and stay legible without color:
- Thin marks. Lines are 2 dp, bars have a 4 dp rounded far end anchored to the baseline with at least 2 dp between neighbours, markers are 8 dp, grid lines are 1 dp dashed at 12% ink.
- One value axis. Tick labels sit left of the plot; there is never a dual axis. Ticks use "nice" 1-2-5 steps and the domain always includes zero.
- One hue per job. Series take colors from a fixed-order categorical palette (or
ChartPalette::sequential()for magnitudes). Status colors (success, warning, danger) are never used for series identity. - Readable without color.
ChartThemecarriesinkandmutedcolors for labels; legends andvalueLabels()carry series identity in text. - Everything in dp. Charts receive an explicit
width/heightand emit a dp scene (CanvasView::dp()); pointer coordinates arrive in dp too. - Empty states. Charts without values draw the baseline and a muted "Sem dados" ("No data") label. Single points are drawn as markers.
Production checklist
- Give every chart an explicit
width/heightin dp that matches its layout slot. - Format values with
valueFormatter()so ticks and labels use the product's locale. - Keep status colors out of series; carry identity through labels and legends.
- Re-render with
highlight()fromonSelectinstead of mutating the chart. - Run
pam doctor,pam test, and a signed release build on every supported platform.
Troubleshooting
- Nothing is drawn: make sure
pushinbr/pam-native-canvas0.2+ is installed andpam doctor --fixregenerated the native integration. - Labels overlap: widen the chart, shorten
labels(), or lowergrid(). - The highlight does not move: store the index from
onSelectin component state and pass it back throughhighlight(). - Template props ignored: bind arrays with
:series="[...]"; plain attributes are strings and only scalars are coerced.
Security
Security vulnerabilities should be reported through the repository security policy or GitHub private vulnerability reporting, not a public issue.
Docs
- Charts guide: themes, every chart type, template tags, composition and the API table
- examples/WeeklyMovement.pam: a finance card with a grouped bar chart (tap highlight), a sparkline and a donut, written as a
.pamcomponent - examples/builder.php: the same charts from PHP builders, with a theme, a value formatter and a progress ring
- Plugin and native capability model
- Contributing
- PAM Native overview
- PAM introduction
- Changelog
- Report an issue
Part of the PAM ecosystem
PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.
| PAM | PAM Desktop | PAM Native | Ecosystem |
|---|---|---|---|
| the runtime and CLI | native desktop apps in PHP | native Android and iOS apps in PHP | every official package and plugin |
Docs: push-in.github.io/pam-docs · Issues
Apache License 2.0 · Made in Brazil by Pushin