Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
f351b78
chore(docs): replace the legacy static site foundation
donmanueldev Sep 18, 2026
c5a8be8
docs(getting-started): add installation and platform overview
donmanueldev Sep 18, 2026
667aa60
docs(charts): document cartesian chart components
donmanueldev Sep 18, 2026
bbb05e2
docs(charts): document radial and market charts
donmanueldev Sep 18, 2026
3d9f597
docs(charts): add progress and contribution guides
donmanueldev Sep 18, 2026
3f5ecc6
docs(guides): cover themes interactions and diagnostics
donmanueldev Sep 18, 2026
f2d465d
docs(landing): present developer docs and app showcase
donmanueldev Sep 18, 2026
4ca2a50
ci(docs): deploy the Astro documentation site
donmanueldev Sep 18, 2026
956ef23
feat(charts): add progress and contribution components
donmanueldev Sep 18, 2026
718f3dd
feat(themes): add semantic chart presets
donmanueldev Sep 18, 2026
01705d7
fix(charts): preserve payloads and readable candle domains
donmanueldev Sep 18, 2026
589b582
feat(android): render progress and contribution charts
donmanueldev Sep 18, 2026
700da38
perf(android): move chart payload work off the UI thread
donmanueldev Sep 18, 2026
e4543cc
feat(ios): add themed native chart rendering
donmanueldev Sep 18, 2026
de850d2
test(native): add Android and iOS behavior harnesses
donmanueldev Sep 18, 2026
082cca0
ci(release): automate native validation and performance evidence
donmanueldev Sep 18, 2026
11cbf34
docs(validation): state native coverage with confidence
donmanueldev Sep 18, 2026
d6f6d2f
fix(ci): pin the Java setup action to a valid revision
donmanueldev Sep 18, 2026
b4cfb09
chore(package): exclude validation sources from archives
donmanueldev Sep 18, 2026
f40779d
fix(ci): let XCTest launch the generated iOS shell
donmanueldev Sep 18, 2026
9bbc4d0
fix(ios): size generated shell harness content
donmanueldev Sep 19, 2026
c8b5eb6
fix(ci): run generated iOS tests on macOS 15
donmanueldev Sep 19, 2026
90cd432
chore(repo): remove local performance reports
donmanueldev Sep 19, 2026
d2c4850
chore(repo): remove embedded integration harnesses
donmanueldev Sep 19, 2026
00fdc31
fix(native): align themed chart behavior
donmanueldev Sep 19, 2026
7834f09
fix(formatting): localize contribution values
donmanueldev Sep 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,8 @@ body:
- DonutChart
- RadarChart
- CandlestickChart
- ProgressChart
- ContributionHeatmap
- Multiple components
validations:
required: true
Expand Down
19 changes: 18 additions & 1 deletion .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,30 @@ jobs:
with:
persist-credentials: false

- name: Set up Bun
uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
with:
bun-version: 1.3.14

- name: Install documentation dependencies
working-directory: docs
run: bun install --frozen-lockfile

- name: Check documentation
working-directory: docs
run: bun run check

- name: Build documentation
working-directory: docs
run: bun run build

- name: Configure GitHub Pages
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0

- name: Upload documentation artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: docs
path: docs/dist

- name: Deploy to GitHub Pages
id: deployment
Expand Down
5 changes: 4 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,7 @@
*.log
/.build/
resources/ios/.build/
android-harness/
.idea/
*.iml
.vscode/
.playwright-mcp
20 changes: 20 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,26 @@ All notable changes to NativePHP Charts are documented here. The project follows

## [Unreleased]

### Added

- Native progress and contribution heatmap charts with selection, reduced-motion behavior, empty/error states, and accessible summaries.
- Semantic `light`, `dark`, and `system` themes with built-in and application-defined presets.
- An Astro/Starlight documentation application.

### Changed

- Moved native payload reads and decoding off the UI thread while preserving the last valid snapshot during replacement loading.
- Reduced Android solid-linear HWUI geometry at sub-pixel density while preserving per-column extrema and the complete selection snapshot.
- Made explicit series, segment, and metric colors optional so semantic palettes can supply stable defaults.
- Extended the version 1 `PointSelection` contract with `progress` and `contribution_heatmap` chart types.

### Fixed

- Reject unknown contracts and corrupt native snapshots with a bounded diagnostic and visible error state.
- Keep new file-backed payloads for at least ten minutes and prune only expired entries beyond the retained 64.
- Ignore unrevealed Android geometry during animated hit testing.
- Preserve the full chart accessibility frame on iOS so VoiceOver focus and assistive hit testing cover the rendered plot.

## [1.1.0] - 2026-09-01

### Added
Expand Down
69 changes: 57 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/nativephp-charts-lockup-dark.svg">
<img src="docs/assets/brand/nativephp-charts-lockup.svg" width="420" alt="NativePHP Charts">
<source media="(prefers-color-scheme: dark)" srcset="docs/public/brand/nativephp-charts-lockup-dark.svg">
<img src="docs/public/brand/nativephp-charts-lockup.svg" width="420" alt="NativePHP Charts">
</picture>
</p>

Expand All @@ -13,9 +13,9 @@

**[Explore the documentation and native demos →](https://donmanueldev.github.io/nativephp-charts/)**

Start with the focused guides: [installation and your first chart](https://donmanueldev.github.io/nativephp-charts/guides/installation/), [line, area, bar, and scatter charts](https://donmanueldev.github.io/nativephp-charts/guides/cartesian-charts/), [pie and donut charts](https://donmanueldev.github.io/nativephp-charts/guides/radial-charts/), and [radar and candlestick charts](https://donmanueldev.github.io/nativephp-charts/guides/radar-candlestick/).
Start with [installation](https://donmanueldev.github.io/nativephp-charts/getting-started/installation/), choose from the chart guides beginning with [line](https://donmanueldev.github.io/nativephp-charts/charts/line/), then use the focused guides for [themes](https://donmanueldev.github.io/nativephp-charts/guides/themes/), [callbacks](https://donmanueldev.github.io/nativephp-charts/guides/callbacks-interactions/), and [troubleshooting](https://donmanueldev.github.io/nativephp-charts/guides/troubleshooting/).

Native line, area, bar, scatter, candlestick, radar, pie, and donut charts for [NativePHP Mobile](https://nativephp.com). iOS renders with Swift Charts and SwiftUI Canvas; Android renders with Jetpack Compose Canvas. Data stays on the device; there is no WebView, JavaScript chart library, network service, telemetry, or third-party native chart dependency.
Ten native chart types for [NativePHP Mobile](https://nativephp.com), including Cartesian, radial, progress, and contribution charts. iOS renders with Swift Charts and SwiftUI Canvas; Android renders with Jetpack Compose Canvas. Data stays on the device; there is no WebView, JavaScript chart library, network service, telemetry, or third-party native chart dependency.

> NativePHP Charts is an independent community plugin. It is not an official NativePHP package.

Expand Down Expand Up @@ -117,10 +117,10 @@ Create `resources/views/native/sales-dashboard.blade.php`. Give the chart an exp
</native:column>
```

The same `series` contract powers line, area, bar, and scatter charts. Every series needs a unique `id`, `name`, `color`, and ordered `points`. Give each point a stable `id` when the chart is interactive or updates frequently.
The same `series` contract powers line, area, bar, and scatter charts. Every series needs a unique `id`, `name`, and ordered `points`; `color` is optional and otherwise comes from the active preset. Give every interactive point a stable `id` so selection survives updates and reordering.

<p align="center">
<img src="docs/assets/screenshots/line-ios-320.webp" width="220" alt="Native line chart running in the iOS simulator">
<img src="docs/public/evidence/ios/line.webp" width="220" alt="Native line chart running in the iOS simulator">
</p>

<p align="center"><sub>Native line chart rendered in the installed iOS app.</sub></p>
Expand All @@ -137,6 +137,8 @@ The same `series` contract powers line, area, bar, and scatter charts. Every ser
| Radar | `<native:radar-chart>` | Ordered `axes`, `series`, and axis values | Grid levels and fill opacity |
| Pie | `<native:pie-chart>` | Ordered `segments` | Fixed inner radius of `0` |
| Donut | `<native:donut-chart>` | Ordered `segments` | `inner-radius-ratio` from `0.2` to `0.85` |
| Progress | `<native:progress-chart>` | Ordered `metrics` with values from `0` to `1` | Ring track, gap, cap, and center label styles |
| Contribution heatmap | `<native:contribution-heatmap>` | Unique ISO-dated `values` | Date window, week start, scale, and label visibility |

Every listed chart renders natively on iOS and Android and supports localized values, empty states, semantic styling, legends, selection callbacks, and accessible summaries.

Expand Down Expand Up @@ -316,7 +318,7 @@ Radar charts require 3 to 24 ordered axes. Each series must provide exactly one

### Pie and donut charts

Pie and donut charts use ordered `segments`. Every segment needs a unique `id`, a `label`, a non-negative finite `value`, and a `color`. A non-empty chart must contain at least one positive value.
Pie and donut charts use ordered `segments`. Every segment needs a unique `id`, a `label`, and a non-negative finite `value`; `color` is optional. A non-empty chart must contain at least one positive value.

```blade
<native:pie-chart
Expand Down Expand Up @@ -353,10 +355,52 @@ Pie and donut charts use ordered `segments`. Every segment needs a unique `id`,

Pie fixes the inner radius at `0`. Donut defaults to `0.6` and accepts `0.2` through `0.85`.

### Progress and contribution heatmap

Progress values are strict fractions from `0` to `1`. Contribution values use unique ISO dates and non-negative values.

```blade
<native:progress-chart
class="w-full h-72"
:metrics="[
['id' => 'delivery', 'label' => 'Delivery', 'value' => 0.82],
['id' => 'quality', 'label' => 'Quality', 'value' => 0.94],
]"
center-label="This sprint"
preset="spectrum"
:legend="['visible' => true]"
_select="metricSelected"
a11y-label="Sprint goals"
/>

<native:contribution-heatmap
class="w-full h-64"
:values="[
['id' => '2026-09-15', 'date' => '2026-09-15', 'value' => 3, 'label' => '3 commits'],
['id' => '2026-09-16', 'date' => '2026-09-16', 'value' => 7, 'label' => '7 commits'],
]"
end-date="2026-09-30"
:days="180"
:week-starts-on="1"
_select="daySelected"
a11y-label="Repository contributions"
/>
```

## API guide

Use this section after the first chart renders to add interaction, formatting, legends, and semantic styling.

### Themes and presets

Every chart accepts `theme="light|dark|system"`, `preset`, and `error-label`. Built-in presets are `default`, `spectrum`, and `contrast`. Publish the package config to register application presets:

```bash
php artisan vendor:publish --tag=nativephp-charts-config
```

Resolution is deterministic: built-in preset, application preset override, chart theme/style, then explicit series, segment, or metric color. The API stays renderer-neutral; it exposes no SwiftUI or Compose primitives.

### Selection and PHP callbacks

Bind `_select` to a public method on the surrounding `NativeComponent`. Native selection and tooltips update immediately; the PHP callback receives the selected identity and value as JSON.
Expand Down Expand Up @@ -504,21 +548,22 @@ Blade uses kebab case. The fluent PHP API uses camelCase methods such as `series
- Category x-axes do not accept an explicit numeric/date domain.
- Unknown axis, legend, style, series, point, and segment options are rejected instead of silently ignored.

### Accessibility and performance
### Accessibility

- Always provide a localized `a11y-label` describing the chart's purpose.
- Use stable IDs so selection remains deterministic across updates and reordering.
- Native renderers bound large accessibility summaries instead of reading an unbounded dataset.
- Native rendering is not a promise of unlimited data. Validate realistic and worst-case datasets on every target device.
- Simulator and host tests do not replace VoiceOver, TalkBack, text scaling, gesture, and performance checks on physical devices.
- Validate realistic and worst-case datasets on every target device.

### Testing and evidence
### Testing

```bash
composer test
swift test
```

PHP tests prove normalization, serialization, compatibility, and callback registration. Native compilation, simulator/emulator rendering, interaction, accessibility, and physical-device performance remain separate acceptance gates.
PHP tests cover normalization, serialization, compatibility, and callback registration. Swift tests cover the iOS renderer source.


## Platform and frontend scope

Expand Down
9 changes: 9 additions & 0 deletions config/nativephp-charts.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<?php

return [
/*
| Application presets are merged over the matching built-in preset. A custom
| name starts from `default`, so applications only need to publish overrides.
*/
'presets' => [],
];
26 changes: 26 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# build output
dist/
test-results/
playwright-report/

# generated types
.astro/

# dependencies
node_modules/

# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# environment variables
.env
.env.production

# macOS-specific files
.DS_Store

# jetbrains setting folder
.idea/
Binary file removed docs/assets/demos/android/bar-selection.mp4
Binary file not shown.
Binary file removed docs/assets/demos/android/line-update.mp4
Binary file not shown.
Binary file removed docs/assets/demos/android/radial-selection.mp4
Binary file not shown.
Binary file removed docs/assets/demos/ios/bar-selection.mp4
Binary file not shown.
Binary file removed docs/assets/demos/ios/line-update.mp4
Binary file not shown.
Binary file removed docs/assets/demos/ios/radial-selection.mp4
Binary file not shown.
Loading
Loading