diff --git a/.gitattributes b/.gitattributes index 1b761ef..affd2ae 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,5 +1,16 @@ -/Package.swift export-ignore +# Keep the Composer dist archive limited to runtime files: +# README, LICENSE, CHANGELOG, composer.json, nativephp.json, config, resources and src. /.build export-ignore +/.github export-ignore +/.gitattributes export-ignore +/.gitignore export-ignore +/CODE_OF_CONDUCT.md export-ignore +/CONTRIBUTING.md export-ignore +/docs export-ignore +/Package.swift export-ignore +/phpunit.xml export-ignore /resources/ios/.build export-ignore /resources/ios/Tests export-ignore /resources/ios/TestSupport export-ignore +/SECURITY.md export-ignore +/tests export-ignore diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 4366177..a56355c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -7,7 +7,7 @@ body: - type: markdown attributes: value: | - Thanks for helping improve NativePHP Charts. Do not report security vulnerabilities here; follow the private reporting instructions in the README instead. + Thanks for helping improve NativePHP Charts. Do not report security vulnerabilities here; follow the private reporting instructions in SECURITY.md instead. - type: textarea id: description @@ -146,5 +146,5 @@ body: required: true - label: I removed secrets, tokens, and private data from logs and examples. required: true - - label: This report is not a security vulnerability; security reports must follow the README instructions. + - label: This report is not a security vulnerability; security reports must follow SECURITY.md. required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index b6f06b3..0b34095 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ blank_issues_enabled: false contact_links: - name: Security vulnerability - url: https://github.com/donmanueldev/nativephp-charts#security-and-privacy - about: Follow the private reporting instructions in the security and privacy section. + url: https://github.com/donmanueldev/nativephp-charts/security/policy + about: Report vulnerabilities privately as described in the security policy. Do not open a public issue. + - name: Documentation + url: https://donmanueldev.github.io/nativephp-charts/ + about: Chart guides, the API reference, and troubleshooting steps. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..b37a9bc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,82 @@ +name: Feature request +description: Suggest a new chart type, option, or improvement for NativePHP Charts +title: "[Feature]: " +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement. Check the [documentation](https://donmanueldev.github.io/nativephp-charts/) and existing issues first; the option you need may already exist. + + - type: textarea + id: problem + attributes: + label: Problem + description: What are you trying to show or do in your app, and what stops you today? + placeholder: My budget screen needs to show... but the current charts cannot... + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the behavior you would like. If you have an API in mind, include the Blade attributes or fluent PHP methods you would expect. + render: blade + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Workarounds you tried, or other ways to solve the problem. + + - type: dropdown + id: chart + attributes: + label: Related chart component + options: + - LineChart + - AreaChart + - BarChart + - ScatterChart + - PieChart + - DonutChart + - RadarChart + - CandlestickChart + - ProgressChart + - ContributionHeatmap + - New chart type + - All charts + validations: + required: true + + - type: dropdown + id: platform + attributes: + label: Platform + description: Features should work on both platforms. Tell us if the need is specific to one. + options: + - Both platforms + - Android + - iOS + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional context + description: Screenshots, mockups, or links to similar charts in native apps. + + - type: checkboxes + id: checks + attributes: + label: Submission checklist + options: + - label: I searched existing issues and the documentation for this request. + required: true + - label: I would be willing to help test this feature on a device or simulator. + required: false diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7110936..3376a11 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -69,3 +69,31 @@ jobs: - name: Compile Swift renderers and run native tests run: swift test + + docs: + name: Documentation build + runs-on: ubuntu-latest + timeout-minutes: 10 + + steps: + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + 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 diff --git a/.gitignore b/.gitignore index 46b97df..31fb2fa 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,5 @@ resources/ios/.build/ *.iml .vscode/ .playwright-mcp +.claude/ +.remember/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 91554b1..398a367 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,45 @@ All notable changes to NativePHP Charts are documented here. The project follows ## [Unreleased] +## [1.3.0] - 2026-11-14 + +### Added + +- The Blade `a11y-hint` attribute now reaches the native renderers, matching the fluent `a11yHint()` method. +- Contributing guide, code of conduct, feature request template, and a documentation build check on pull requests. +- Social preview image, canonical and Open Graph metadata, structured data, and `llms.txt` for the documentation site. + +### Changed + +- The Composer dist archive no longer ships the documentation site, tests, or CI configuration, reducing it from about 3.3 MB to about 220 KB. +- An explicit `null` for an optional axis key (`title`, `visible`, `labelCount`, `minimum`, `maximum`, `baseline`, `interval`, `beginAtZero`) now clears that option instead of raising a PHP warning or keeping the earlier value. +- Changing the x-axis `type` drops a previously configured `minimum`, `maximum`, `baseline`, and `interval`. +- Fluent `annotations()` and `viewport()` may be called before `xAxis()`; x-type errors are then reported when the axis is configured or the chart is rendered. +- Progress charts format the selection `localized_value` and Android labels with the chart `locale` and fraction-digit settings on both platforms. +- Progress charts with many rings scale ring width so every ring stays visible and tappable on both platforms, metrics beyond the fourth use the preset palette on iOS, legends longer than six metrics scroll within a fixed height, and the center label is hidden when the innermost ring leaves no room for it. +- Android progress legends show a color marker per metric, and iOS progress legends use the chart locale and fraction digits. +- Contribution heatmap month and weekday labels follow the chart `locale`; Android intensity scales to the largest visible value. +- Contribution heatmap days with a value of `0` use the empty color on iOS, matching Android, and a partial first month drops its label when it would overlap the next month's. +- Declared `nativephp/mobile-ui` as a dependency, since the native renderers use its font resolver, node, and color types. +- Android draws at most 100 ticks for an explicit axis `interval`, thinning denser intervals across the full domain. +- Rewrote the README and Laravel Boost guideline to cover all ten chart types, and converted documentation captures to WebP. + +### Fixed + +- Android contribution heatmaps without an `end-date` end on the device's local day instead of the UTC day, matching iOS. +- iOS horizontal bar charts render every category in source order, with ticks, annotations, tooltips, selection, and viewport gestures aligned to the bars. +- Charts no longer show or announce the empty state before their first load on iOS, and keep their size while loading on Android. +- Candlestick charts reject more than one series when `series` and `x-axis` are supplied together in Blade. +- Date-axis viewport ranges and `minimumSpan` no longer depend on the PHP default time zone. +- An unwritable payload directory raises the documented exception instead of silently writing to the system temporary directory, and abandoned temporary payload files are pruned. +- Callback expressions accept parentheses inside string arguments and reject non-finite numbers. +- Android tap, scrub, and viewport callbacks report current values after chart props change. +- Android tooltips wider than the plot no longer crash the draw pass, and Cartesian legend markers match per-series line and point colors. +- iOS candlestick tooltips show all four OHLC values, and tooltips near plot edges are no longer clipped. +- iOS contribution heatmaps without an `end-date` end on the device's current day, and keep weekday labels when the grid starts with blank cells. +- Contribution heatmaps no longer outline every blank day as selected while nothing is selected, and the selection outline of edge cells is no longer clipped. +- iOS progress and contribution heatmap charts paint the theme background, and progress center labels and legends use the theme foreground color, matching Android. + ## [1.2.1] - 2026-10-01 ### Fixed @@ -95,7 +134,8 @@ All notable changes to NativePHP Charts are documented here. The project follows - Initial native line chart component for NativePHP Mobile. -[Unreleased]: https://github.com/donmanueldev/nativephp-charts/compare/v1.2.1...HEAD +[Unreleased]: https://github.com/donmanueldev/nativephp-charts/compare/v1.3.0...HEAD +[1.3.0]: https://github.com/donmanueldev/nativephp-charts/compare/v1.2.1...v1.3.0 [1.2.0]: https://github.com/donmanueldev/nativephp-charts/compare/v1.1.0...v1.2.0 [1.1.0]: https://github.com/donmanueldev/nativephp-charts/compare/v1.0.0...v1.1.0 [1.0.0]: https://github.com/donmanueldev/nativephp-charts/compare/v0.2.0...v1.0.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..037a932 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +donmanuel@momotombo.dev. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7c95ce4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Contributing to NativePHP Charts + +Thanks for helping improve NativePHP Charts. This guide covers local setup, tests, the documentation site, and how changes are proposed. + +By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). + +## Requirements + +- PHP 8.4 or newer and Composer 2 +- macOS with Xcode (Swift 6 toolchain) to run the Swift renderer tests +- [Bun](https://bun.sh/) 1.3 or newer to build the documentation site (the version CI uses is pinned in `.github/workflows/pages.yml`) +- A NativePHP Mobile 4 application with Android Studio and/or Xcode to try renderer changes on a device, emulator, or simulator + +## Setup + +```bash +git clone https://github.com/donmanueldev/nativephp-charts.git +cd nativephp-charts +composer install +``` + +## Running tests + +```bash +composer test # Pest: normalization, serialization, callbacks, and documentation examples +swift test # Compiles the iOS renderers and runs the Swift tests in resources/ios/Tests +``` + +CI also runs `composer validate --strict` and `vendor/bin/testbench native:plugin:validate . --no-interaction`. Run them before opening a pull request when you change `composer.json` or `nativephp.json`. + +The Kotlin renderers have no standalone test suite. Compile and check Android changes in a NativePHP Mobile application that has the package installed from your local checkout (for example through a Composer `path` repository), then rebuild the Android target. + +## Documentation site + +The documentation is an Astro and Starlight site in `docs/`. CI installs it with Bun, so `docs/bun.lock` is the lockfile that counts. + +```bash +cd docs +bun install --frozen-lockfile +bun run dev # local preview +bun run check # Astro type and content checks +bun run build # production build into docs/dist +``` + +The Blade examples in `docs/examples/` are rendered on the site and also exercised by `tests/DocumentationExamplesTest.php`, so keep them valid when you change a public attribute. + +## How the source is organized + +| Path | Contents | +| --- | --- | +| `src/Elements/` | Fluent element classes (`LineChart::make()`), attribute parsing, and the props sent to the renderers | +| `src/Components/` | Blade component classes behind the `` tags | +| `src/Support/` | Validation and normalization of series, axes, styles, themes, and callbacks | +| `src/PointSelection.php`, `src/ViewportChange.php` | Decoders for the versioned callback payloads | +| `config/nativephp-charts.php` | Application preset registry | +| `nativephp.json` | Plugin manifest that maps each element to its iOS and Android renderer | +| `resources/ios/Sources/` | SwiftUI and Swift Charts renderers: one file per chart, plus `Core/`, `Interaction/`, `Rendering/`, and `Radar/` | +| `resources/android/src/` | Jetpack Compose renderers: `entrypoints/` (one per chart), `core/`, `interaction/`, and `rendering/` | +| `resources/boost/guidelines/` | Laravel Boost guideline that coding agents read in consumer apps | +| `tests/` | Pest tests; `tests/Fixtures/chart_contract_fixtures.json` is shared with the Swift tests | + +A change to the public contract usually touches PHP validation, both native renderers, the shared fixtures, and the documentation. Keep iOS and Android behavior in parity. + +## Branches and commits + +- Branch from `main` with a prefix that matches the change: `feature/`, `bugfix/`, `docs/`, `chore/`, or `refactor/`. +- Write commit messages and pull request titles in English using [Conventional Commits](https://www.conventionalcommits.org/): `(): `, for example `fix(android): keep selection after data update` or `docs(guides): explain viewport callbacks`. +- Common types are `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `build`, `ci`, and `chore`. Mark breaking changes with `!` and explain them in the body. +- Keep one logical change per pull request, add or update tests, and update the documentation when a public attribute or behavior changes. +- Fill in the pull request template, including the platforms you tested. + +The project follows [Semantic Versioning](https://semver.org/). Changes that would break the 1.x contract described in the [migration guide](https://donmanueldev.github.io/nativephp-charts/guides/migration/) need discussion in an issue first. + +## Reporting bugs + +Open a [bug report](https://github.com/donmanueldev/nativephp-charts/issues/new/choose) with the smallest Blade or PHP example that reproduces the problem, the package, NativePHP Mobile, Laravel, and PHP versions, and the platform and OS version. Remove secrets and personal data from logs. + +Do not report security vulnerabilities in public issues. Follow [SECURITY.md](SECURITY.md) instead. diff --git a/README.md b/README.md index df63717..42bc09b 100644 --- a/README.md +++ b/README.md @@ -7,35 +7,60 @@ # NativePHP Charts +Native charts for NativePHP Mobile: give your Laravel-powered iOS and Android apps line, bar, area, scatter, pie, donut, candlestick, radar, progress, and heatmap charts rendered with Swift Charts and Jetpack Compose, configured from Blade or PHP, with no WebView or JavaScript. + [![Latest Version on Packagist](https://img.shields.io/packagist/v/donmanueldev/nativephp-charts.svg?style=flat-square)](https://packagist.org/packages/donmanueldev/nativephp-charts) +[![Total Downloads](https://img.shields.io/packagist/dt/donmanueldev/nativephp-charts.svg?style=flat-square)](https://packagist.org/packages/donmanueldev/nativephp-charts) +[![PHP Version](https://img.shields.io/packagist/php-v/donmanueldev/nativephp-charts.svg?style=flat-square)](https://packagist.org/packages/donmanueldev/nativephp-charts) [![Tests](https://github.com/donmanueldev/nativephp-charts/actions/workflows/ci.yml/badge.svg)](https://github.com/donmanueldev/nativephp-charts/actions/workflows/ci.yml) +[![Documentation](https://img.shields.io/badge/docs-online-0F766E.svg?style=flat-square)](https://donmanueldev.github.io/nativephp-charts/) [![License](https://img.shields.io/packagist/l/donmanueldev/nativephp-charts.svg?style=flat-square)](LICENSE.md) -**[Explore the documentation and native demos →](https://donmanueldev.github.io/nativephp-charts/)** +> NativePHP Charts is an independent community plugin. It is not an official NativePHP package. -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/). +

+ Line chart with a selected point on iOS + Donut chart on Android + Candlestick chart on iOS + Progress rings on Android +

-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. +

Screenshots from the native renderers: line and candlestick on iOS, donut and progress on Android.

-> NativePHP Charts is an independent community plugin. It is not an official NativePHP package. +## Install -## Apps using NativePHP Charts +```bash +composer require donmanueldev/nativephp-charts +php artisan vendor:publish --tag=nativephp-plugins-provider --no-interaction +php artisan native:plugin:register donmanueldev/nativephp-charts --no-interaction +php artisan native:plugin:list +php artisan native:plugin:validate +``` -- [Despertá](https://desperta.momotombo.dev/) — [Get it on Google Play](https://play.google.com/store/apps/details?id=dev.momotombo.desperta) +The renderers compile into the native app, so rebuild your iOS or Android target after installing or updating the package. -## Documentation +**[Read the documentation](https://donmanueldev.github.io/nativephp-charts/)** for chart guides, native previews, and the full API reference. -- [Apps using NativePHP Charts](#apps-using-nativephp-charts) +## Contents + +- [Why native instead of a WebView chart library](#why-native-instead-of-a-webview-chart-library) - [Requirements](#requirements) -- [Installation](#installation) - [Quick start](#quick-start) -- [Available chart types](#available-chart-types) -- [Chart examples](#chart-examples) -- [API guide](#api-guide) -- [Validation and quality](#validation-and-quality) -- [Platform and frontend scope](#platform-and-frontend-scope) +- [Chart types](#chart-types) +- [Shared options](#shared-options) +- [Selection callbacks](#selection-callbacks) +- [Apps using NativePHP Charts](#apps-using-nativephp-charts) +- [Contributing](#contributing) - [Support and security](#support-and-security) +## Why native instead of a WebView chart library + +- Each chart is drawn by the platform UI toolkit: Swift Charts and SwiftUI Canvas on iOS, Jetpack Compose Canvas on Android. It sits in the same native view hierarchy as the rest of your NativePHP screen. +- Charts expose native accessibility elements to VoiceOver and TalkBack, with localized value summaries and actions to move between points. +- Charts follow system settings: light and dark appearance with `theme="system"`, the reduced-motion preference, and the user's text size for axis and legend labels. +- Numbers, currencies, percentages, and dates are formatted by the platform formatters for the chart's `locale`. +- There is no JavaScript bundle, WebView, or chart service. Chart data goes from the PHP runtime on the device to the native renderer, and the package makes no network requests, so charts work offline. + ## Requirements | Requirement | Supported | @@ -46,21 +71,9 @@ Ten native chart types for [NativePHP Mobile](https://nativephp.com), including | iOS | 18.2 or newer | | NativePHP Desktop / WebView | Not supported | -## Installation - -```bash -composer require donmanueldev/nativephp-charts:^1.0 -php artisan vendor:publish --tag=nativephp-plugins-provider --no-interaction -php artisan native:plugin:register donmanueldev/nativephp-charts --no-interaction -php artisan native:plugin:list -php artisan native:plugin:validate -``` - -The chart renderers compile into the native shell. Rebuild the iOS or Android target after installing or updating the package. - ## Quick start -Charts are leaf elements inside a NativePHP `NativeComponent` screen. The complete path to a first chart is a component class, a native route, and an EDGE Blade view. +Charts are leaf elements inside a NativePHP `NativeComponent` screen. A first chart needs a component class, a native route, and an EDGE Blade view. Create `app/NativeComponents/SalesDashboard.php`: @@ -117,293 +130,43 @@ Create `resources/views/native/sales-dashboard.blade.php`. Give the chart an exp ``` -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. - -

- Native line chart running in the iOS simulator -

+The same `series` contract powers line, area, bar, scatter, and candlestick charts. Every series needs a unique `id`, a `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. -

Native line chart rendered in the installed iOS app.

+The same chart can be built in PHP with the fluent element API, for example `LineChart::make()->series($series)->a11yLabel('Monthly sales')`. See [Blade and PHP equivalence](https://donmanueldev.github.io/nativephp-charts/reference/blade-php/). -## Available chart types +## Chart types -| Chart | EDGE element | Data | Chart-specific option | +| Chart | Element | Data | Chart-specific options | | --- | --- | --- | --- | -| Line | `` | Ordered `series` and `points` | Line and point styles | -| Area | `` | Ordered `series` and `points` | `area-mode="overlay|stacked"` | -| Bar | `` | Ordered `series` and `points` | Grouped multi-series bars | -| Scatter | `` | Ordered `series` and numeric/date points | Numeric x-axis by default | -| Candlestick | `` | One ordered OHLC series | Rising, falling, neutral, and wick styles | -| Radar | `` | Ordered `axes`, `series`, and axis values | Grid levels and fill opacity | -| Pie | `` | Ordered `segments` | Fixed inner radius of `0` | -| Donut | `` | Ordered `segments` | `inner-radius-ratio` from `0.2` to `0.85` | -| Progress | `` | Ordered `metrics` with values from `0` to `1` | Ring track, gap, cap, and center label styles | -| 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. - -## Chart examples - -The following examples focus on the data and options that differ by chart. They use the same `NativeComponent` screen structure shown in the quick start. - -### Area chart - -Area charts support overlay and stacked multi-series fills. - -```blade - -``` - -### Bar chart +| [Line](https://donmanueldev.github.io/nativephp-charts/charts/line/) | `` | Ordered `series` and `points` | `fill_to` between series, line and point styles | +| [Area](https://donmanueldev.github.io/nativephp-charts/charts/area/) | `` | Ordered `series` and `points` | `area-mode="overlay\|stacked"`, gradient fill | +| [Bar](https://donmanueldev.github.io/nativephp-charts/charts/bar/) | `` | Ordered `series` and `points` | `mode="grouped\|stacked"`, `orientation="vertical\|horizontal"` | +| [Scatter](https://donmanueldev.github.io/nativephp-charts/charts/scatter/) | `` | Ordered `series` with numeric, date, or datetime `x` | Numeric x-axis by default | +| [Candlestick](https://donmanueldev.github.io/nativephp-charts/charts/candlestick/) | `` | One series of `open`, `high`, `low`, `close` points | Rising, falling, neutral, and wick styles | +| [Pie](https://donmanueldev.github.io/nativephp-charts/charts/pie/) | `` | Ordered `segments` | Segment gap, corner radius, and opacity | +| [Donut](https://donmanueldev.github.io/nativephp-charts/charts/donut/) | `` | Ordered `segments` | `inner-radius-ratio` from `0.2` to `0.85` | +| [Radar](https://donmanueldev.github.io/nativephp-charts/charts/radar/) | `` | 3 to 24 `axes`, plus `series` with one value per axis | `grid-levels`, `fill-opacity` | +| [Progress](https://donmanueldev.github.io/nativephp-charts/charts/progress/) | `` | Up to 24 `metrics` with values from `0` to `1` | `center-label`, ring track, gap, and cap styles | +| [Contribution heatmap](https://donmanueldev.github.io/nativephp-charts/charts/contribution-heatmap/) | `` | Daily `values` with unique ISO dates | `end-date`, `days`, `week-starts-on`, `colors`, `empty-color`, month and weekday labels | -Bar charts render multiple series as grouped bars. Use matching ordered x values when the series are meant to be compared. +Each chart page has a complete Blade example, iOS and Android screenshots, and its validation rules. -```blade - -``` +## Shared options -### Scatter chart +Every chart accepts: -Scatter points preserve the real spacing of numeric, date, or datetime x values. Unlike line and area charts, scatter defaults to a numeric x-axis. +- `a11y-label`, `empty-label`, and `error-label` for the accessible description, the empty state, and the message shown when the native renderer rejects a snapshot. +- `theme` (`light`, `dark`, or `system`) and `preset` (`default`, `spectrum`, `contrast`, or your own preset from `config/nativephp-charts.php`). +- `locale`, `value-format` (`number`, `currency`, or `percent`), `currency-code`, and `minimum-fraction-digits` / `maximum-fraction-digits`. +- `legend`, `style` (platform-neutral style sections), `animated`, and a `_select` callback. -```blade - -``` +Line, area, bar, scatter, and candlestick charts also accept `x-axis` and `y-axis` maps, `show-grid`, `show-points`, `begin-at-zero`, `annotations` (reference lines and bands), `interaction` (tap or scrub, crosshair, tooltip), `viewport` with `on-viewport-change` (pan and zoom on number, date, and datetime axes), and `sampling` (LTTB for dense line, area, and scatter series). On a date or datetime x-axis, set the IANA zone with `timeZone`; `timezone` is accepted as an alias. -Percentage values are fractions: `0.47` renders as `47%`. +The [API reference](https://donmanueldev.github.io/nativephp-charts/reference/api/) lists every attribute, accepted value, default, and style key. Invalid data or options throw `InvalidArgumentException` in PHP before anything is rendered. -### Candlestick chart +## Selection callbacks -Candlestick charts accept one ordered series. Every point defines `open`, `high`, `low`, and `close`; the high-low range must contain the candle body. Use a date or datetime x-axis for market data. - -```blade - -``` - -### Radar chart - -Radar charts require 3 to 24 ordered axes. Each series must provide exactly one value per axis, in the same order, and every value must be between zero and that axis's maximum. - -```blade - -``` - -### Pie and donut charts - -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 - -``` - -```blade - -``` - -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 - - - -``` - -## 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. +Bind `_select` to a public method on the surrounding `NativeComponent`. The method receives the selection as a JSON string; decode it with `PointSelection::fromJson()`. ```php use Donmanueldev\NativephpCharts\PointSelection; @@ -418,160 +181,24 @@ public function pointSelected(string $payload): void } ``` -The fluent element API uses `->onSelect('pointSelected')`. Callback payload version 1 contains: - -```json -{ - "version": 1, - "chart_type": "bar", - "series_id": "online", - "series_name": "Online", - "point_id": "online-q1", - "point_index": 0, - "x_type": "category", - "x": "Q1", - "label": "Q1", - "value": 42000, - "localized_value": "$42,000" -} -``` - -Treat `localized_value` as presentation text. Use `value`, IDs, and `x` for application logic. - -### Axes and formatting - -Cartesian charts accept structured `x-axis` and `y-axis` maps. Scalar formatting props remain supported; a structured y-axis value overrides the corresponding scalar value. - -```blade - -``` - -| X-axis type | Point `x` value | -| --- | --- | -| `category` | Optional string; defaults to `label` | -| `number` | Finite integer or float | -| `date` | Strict `YYYY-MM-DD` | -| `datetime` | RFC 3339 with `Z` or an explicit offset | - -`x-axis` accepts `type`, `title`, `minimum`, `maximum`, `baseline`, `interval`, `dateFormat`, `timezone`, `visible`, and `labelCount`. `y-axis` accepts `title`, `minimum`, `maximum`, `baseline`, `interval`, `valueFormat`, `currencyCode`, `minimumFractionDigits`, `maximumFractionDigits`, `visible`, `labelCount`, and `beginAtZero`. +Use `pointId`, `seriesId`, `x`, and `value` for application logic, and treat `localizedValue` as display text. The fluent API uses `->onSelect('pointSelected')`. See [callbacks and interactions](https://donmanueldev.github.io/nativephp-charts/guides/callbacks-interactions/) for the full payload and viewport callbacks. -Date formats are `short`, `medium`, `long`, and `full`; datetime axes also accept `time`. Timezones use IANA identifiers such as `America/Managua`. Currency uses a three-letter code such as `USD` or `NIO`. Axis `labelCount` must be between 2 and 12. - -### Legends and styles - -`legend` accepts `visible` (`true`, `false`, or automatic when omitted), `position` (`top`, `bottom`, `leading`, or `trailing`), `alignment` (`start`, `center`, or `end`), and a nested `style` map. - -```blade -:legend="[ - 'visible' => true, - 'position' => 'bottom', - 'alignment' => 'center', - 'style' => [ - 'font' => 'accent', - 'fontSize' => 12, - 'labelColor' => '#475569', - 'markerSize' => 9, - ], -]" -``` - -The platform-neutral `style` map supports: - -- `line`: `color`, `width`, `interpolation` (`linear`, `smooth`, `step_before`, `step_after`), and an even-length `dash` list. -- `area`: `opacity` and `gradient`. -- `bar`: `radius` and optional `width`. -- `candlestick`: `risingColor`, `fallingColor`, `neutralColor`, and `wickWidth`. -- `points`: `visible`, `color`, and `size`. -- `grid`: `visible`, `color`, and `width`. -- `axis`: `visible`, `color`, `labelColor`, `font`, `fontSize`, and `labelCount`. -- `segment`: `gap`, `cornerRadius`, and `opacity` for pie and donut charts. - -Colors accept `#RGB`, `#RRGGBB`, CSS-alpha `#RRGGBBAA`, `black`, `white`, and `transparent`. Axis and legend fonts accept bundled NativePHP font tokens or configured aliases and fall back to the system font when unresolved. +## Apps using NativePHP Charts -### Public properties +- [Despertá](https://desperta.momotombo.dev/) ([Google Play](https://play.google.com/store/apps/details?id=dev.momotombo.desperta)) -| Blade property | Default | Applies to | Description | -| --- | --- | --- | --- | -| `series` | `[]` | Cartesian, radar | Ordered series containing points or radar axis values. | -| `segments` | `[]` | Pie, donut | Ordered, uniquely identified radial segments. | -| `axes` | `[]` | Radar | Ordered axis definitions with unique IDs, labels, and positive maximums. | -| `show-grid` | `true` | Cartesian | Shows chart grid lines. | -| `show-points` | `true` | Line, area; legacy bar fallback | Shows point symbols; on bars it preserves the legacy axis fallback. | -| `begin-at-zero` | `true` | Line, bar | Includes zero in the y domain. Area retains zero as its fill baseline. | -| `animated` | `true` | All | Enables native reveal and update animation. | -| `empty-label` | `No data` | All | Visible and accessible empty state. | -| `a11y-label` | `Chart` | All | Purpose announced by assistive technology. Supply an application-specific label. | -| `locale` | Device locale | All | BCP-47 locale such as `es-NI` or `en-US`. | -| `value-format` | `number` | All | `number`, `currency`, or `percent`. | -| `currency-code` | None | All | Required three-letter code when the value format is currency. | -| `minimum-fraction-digits` | Formatter default | All | Integer from 0 to 8. | -| `maximum-fraction-digits` | Formatter default | All | Integer from 0 to 8. | -| `x-axis` | Category; number for scatter | Cartesian | Structured x-axis configuration. | -| `y-axis` | Scalar formatter props | Cartesian | Structured y-axis and value formatting. | -| `legend` | Visible for multiple items | All | Visibility, position, alignment, and semantic style. | -| `_select` | None | All | PHP method receiving selection JSON. | -| `style` | `[]` | All | Chart-specific, platform-neutral visual configuration. | -| `area-mode` | `overlay` | Area | `overlay` or `stacked`. | -| `inner-radius-ratio` | `0.6` | Donut | Cutout ratio from `0.2` through `0.85`. | -| `grid-levels` | `5` | Radar | Polygon grid level count from 2 through 10. | -| `fill-opacity` | `0.22` | Radar | Series fill opacity from 0 through 1. | - -Blade uses kebab case. The fluent PHP API uses camelCase methods such as `series()`, `segments()`, `axes()`, `showGrid()`, `xAxis()`, `yAxis()`, `legend()`, `style()`, `onSelect()`, `areaMode()`, `innerRadiusRatio()`, `gridLevels()`, and `fillOpacity()`. - -## Validation and quality - -### Validation rules - -- Collections must be ordered PHP lists, not associative maps. -- Series IDs must be unique within a chart; point IDs must be unique within their series. -- Numeric values must be finite. Exact cross-platform integers are limited to `±9,007,199,254,740,991`. -- Segment values must be non-negative, and a populated pie or donut needs at least one positive segment. -- Candlestick points require finite OHLC values and a valid high-low range; only one series is accepted. -- Radar charts require 3 to 24 ordered axes and one in-range value per axis for every series. -- `minimumFractionDigits` cannot exceed `maximumFractionDigits`; each accepts 0 through 8. -- Explicit axis minimums must not exceed maximums. Intervals must be positive. -- 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 - -- 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. -- Validate realistic and worst-case datasets on every target device. - -### Testing +## Contributing ```bash composer test swift test ``` -PHP tests cover normalization, serialization, compatibility, and callback registration. Swift tests cover the iOS renderer source. - - -## Platform and frontend scope - -This is a SuperNative EDGE UI component package. It intentionally has no JavaScript API, bridge functions, permissions, secrets, Livewire WebView integration, or Inertia wrapper. NativePHP Desktop, Electron, browser rendering, and Chart.js are outside scope. +PHP tests cover normalization, serialization, and callback decoding. Swift tests compile the iOS renderers and cover their behavior. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full setup, including the documentation site. ## Support and security -Use [GitHub Issues](https://github.com/donmanueldev/nativephp-charts/issues) for reproducible bugs and feature requests. Follow [SECURITY.md](SECURITY.md) for private vulnerability reports. +Use [GitHub Issues](https://github.com/donmanueldev/nativephp-charts/issues) for reproducible bugs and feature requests. Follow [SECURITY.md](SECURITY.md) to report vulnerabilities privately. ## License diff --git a/SECURITY.md b/SECURITY.md index 026346e..ef8f7e2 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,8 +2,21 @@ ## Supported versions -Security fixes are provided for the latest stable release. +| Version | Supported | +| --- | --- | +| Latest 1.x release | Yes | +| Earlier 1.x releases | No; update to the latest 1.x release | +| 0.x | No | + +Security fixes are released as a new 1.x version. After updating, rebuild your iOS and Android apps so the fixed native renderers are compiled in. ## Reporting a vulnerability -Do not open a public issue. Email `donmanuel@momotombo.dev` with a minimal reproduction, affected version, platform, and impact. Do not include production secrets or personal data. You should receive an acknowledgement within seven days. +Do not open a public issue, pull request, or discussion for a vulnerability. + +Report it privately in one of these ways: + +- **GitHub private vulnerability reporting:** open the repository's [Security tab](https://github.com/donmanueldev/nativephp-charts/security) and choose **Report a vulnerability**, or go directly to [the advisory form](https://github.com/donmanueldev/nativephp-charts/security/advisories/new). +- **Email:** `donmanuel@momotombo.dev`. + +Include a minimal reproduction, the affected package version, the platform (iOS, Android, or PHP), and the impact. Do not include production secrets or personal data. You should receive an acknowledgement within seven days. diff --git a/composer.json b/composer.json index 68909a3..45a5409 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "donmanueldev/nativephp-charts", - "description": "Native charts for NativePHP Mobile, rendered with Swift Charts and Jetpack Compose Canvas.", + "description": "Native iOS and Android charts for NativePHP Mobile and Laravel: line, bar, area, scatter, pie, donut, candlestick, radar, progress and heatmap, rendered with Swift Charts and Jetpack Compose.", "type": "nativephp-ui-plugin", "license": "MIT", "authors": [ @@ -11,19 +11,36 @@ ], "keywords": [ "nativephp", - "mobile", + "nativephp-mobile", + "nativephp-plugin", + "laravel", + "laravel-package", "charts", + "chart", + "mobile-charts", + "native-charts", + "swift-charts", "swiftui", - "jetpack-compose" + "jetpack-compose", + "android", + "ios", + "line-chart", + "bar-chart", + "pie-chart", + "candlestick", + "radar-chart", + "heatmap" ], "homepage": "https://donmanueldev.github.io/nativephp-charts/", "support": { "issues": "https://github.com/donmanueldev/nativephp-charts/issues", - "source": "https://github.com/donmanueldev/nativephp-charts" + "source": "https://github.com/donmanueldev/nativephp-charts", + "docs": "https://donmanueldev.github.io/nativephp-charts/" }, "require": { "php": "^8.4", - "nativephp/mobile": "^4.0" + "nativephp/mobile": "^4.0", + "nativephp/mobile-ui": "^0.4" }, "autoload": { "psr-4": { diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 3e444f4..48bdbcb 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -2,21 +2,33 @@ import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; +const site = 'https://donmanueldev.github.io'; const base = '/nativephp-charts'; +const ogImage = `${site}${base}/og.png`; +const ogImageAlt = 'NativePHP Charts: native charts for NativePHP Mobile, rendered with Swift Charts on iOS and Jetpack Compose on Android.'; export default defineConfig({ - site: 'https://donmanueldev.github.io', + site, base, integrations: [ starlight({ title: 'NativePHP Charts', - description: 'Compiled-native charts for NativePHP Mobile.', + description: 'Documentation for NativePHP Charts: native line, bar, area, scatter, pie, donut, candlestick, radar, progress and heatmap charts for NativePHP Mobile on iOS and Android.', disable404Route: true, logo: { src: './public/brand/nativephp-charts-mark.svg', replacesTitle: false }, favicon: "/brand/favicon.svg", social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/donmanueldev/nativephp-charts' }], customCss: ['./src/styles/docs.css'], - head: [{ tag: 'script', attrs: { src: `${base}/site.js`, defer: true } }], + head: [ + { tag: 'script', attrs: { src: `${base}/site.js`, defer: true } }, + { tag: 'meta', attrs: { property: 'og:image', content: ogImage } }, + { tag: 'meta', attrs: { property: 'og:image:alt', content: ogImageAlt } }, + { tag: 'meta', attrs: { property: 'og:image:width', content: '1200' } }, + { tag: 'meta', attrs: { property: 'og:image:height', content: '630' } }, + { tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } }, + { tag: 'meta', attrs: { name: 'twitter:image', content: ogImage } }, + { tag: 'meta', attrs: { name: 'twitter:image:alt', content: ogImageAlt } }, + ], editLink: { baseUrl: 'https://github.com/donmanueldev/nativephp-charts/edit/main/docs/' }, sidebar: [ { diff --git a/docs/public/brand/og.svg b/docs/public/brand/og.svg new file mode 100644 index 0000000..6569275 --- /dev/null +++ b/docs/public/brand/og.svg @@ -0,0 +1,60 @@ + + NativePHP Charts: native charts for NativePHP Mobile on iOS and Android + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + NativePHP Charts + + + + Native charts for + NativePHP Mobile + + Swift Charts on iOS. Jetpack Compose on Android. + + + + + 10 chart types + + Blade or PHP + + No WebView + + diff --git a/docs/public/evidence/android/area-selected.png b/docs/public/evidence/android/area-selected.png deleted file mode 100644 index 3da3a74..0000000 Binary files a/docs/public/evidence/android/area-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/area-selected.webp b/docs/public/evidence/android/area-selected.webp new file mode 100644 index 0000000..dcc7737 Binary files /dev/null and b/docs/public/evidence/android/area-selected.webp differ diff --git a/docs/public/evidence/android/area.png b/docs/public/evidence/android/area.png deleted file mode 100644 index 07763d3..0000000 Binary files a/docs/public/evidence/android/area.png and /dev/null differ diff --git a/docs/public/evidence/android/area.webp b/docs/public/evidence/android/area.webp new file mode 100644 index 0000000..7b61e2e Binary files /dev/null and b/docs/public/evidence/android/area.webp differ diff --git a/docs/public/evidence/android/bar-selected.png b/docs/public/evidence/android/bar-selected.png deleted file mode 100644 index 3a4f889..0000000 Binary files a/docs/public/evidence/android/bar-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/bar-selected.webp b/docs/public/evidence/android/bar-selected.webp new file mode 100644 index 0000000..0bce28a Binary files /dev/null and b/docs/public/evidence/android/bar-selected.webp differ diff --git a/docs/public/evidence/android/bar.png b/docs/public/evidence/android/bar.png deleted file mode 100644 index b5443ee..0000000 Binary files a/docs/public/evidence/android/bar.png and /dev/null differ diff --git a/docs/public/evidence/android/bar.webp b/docs/public/evidence/android/bar.webp index 867002a..1f5bc2c 100644 Binary files a/docs/public/evidence/android/bar.webp and b/docs/public/evidence/android/bar.webp differ diff --git a/docs/public/evidence/android/candlestick-selected.png b/docs/public/evidence/android/candlestick-selected.png deleted file mode 100644 index 7ecf03a..0000000 Binary files a/docs/public/evidence/android/candlestick-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/candlestick-selected.webp b/docs/public/evidence/android/candlestick-selected.webp new file mode 100644 index 0000000..37e5fc8 Binary files /dev/null and b/docs/public/evidence/android/candlestick-selected.webp differ diff --git a/docs/public/evidence/android/candlestick.png b/docs/public/evidence/android/candlestick.png deleted file mode 100644 index faabe06..0000000 Binary files a/docs/public/evidence/android/candlestick.png and /dev/null differ diff --git a/docs/public/evidence/android/candlestick.webp b/docs/public/evidence/android/candlestick.webp new file mode 100644 index 0000000..e61506a Binary files /dev/null and b/docs/public/evidence/android/candlestick.webp differ diff --git a/docs/public/evidence/android/contribution-heatmap-selected.png b/docs/public/evidence/android/contribution-heatmap-selected.png deleted file mode 100644 index 9045793..0000000 Binary files a/docs/public/evidence/android/contribution-heatmap-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/contribution-heatmap-selected.webp b/docs/public/evidence/android/contribution-heatmap-selected.webp new file mode 100644 index 0000000..53e99fe Binary files /dev/null and b/docs/public/evidence/android/contribution-heatmap-selected.webp differ diff --git a/docs/public/evidence/android/contribution-heatmap.png b/docs/public/evidence/android/contribution-heatmap.png deleted file mode 100644 index 362d714..0000000 Binary files a/docs/public/evidence/android/contribution-heatmap.png and /dev/null differ diff --git a/docs/public/evidence/android/contribution-heatmap.webp b/docs/public/evidence/android/contribution-heatmap.webp new file mode 100644 index 0000000..e6162f8 Binary files /dev/null and b/docs/public/evidence/android/contribution-heatmap.webp differ diff --git a/docs/public/evidence/android/donut-selected.png b/docs/public/evidence/android/donut-selected.png deleted file mode 100644 index 41d5d9a..0000000 Binary files a/docs/public/evidence/android/donut-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/donut-selected.webp b/docs/public/evidence/android/donut-selected.webp new file mode 100644 index 0000000..23aae05 Binary files /dev/null and b/docs/public/evidence/android/donut-selected.webp differ diff --git a/docs/public/evidence/android/donut.png b/docs/public/evidence/android/donut.png deleted file mode 100644 index ec9c135..0000000 Binary files a/docs/public/evidence/android/donut.png and /dev/null differ diff --git a/docs/public/evidence/android/donut.webp b/docs/public/evidence/android/donut.webp index 1142b2c..c21830c 100644 Binary files a/docs/public/evidence/android/donut.webp and b/docs/public/evidence/android/donut.webp differ diff --git a/docs/public/evidence/android/line-selected.png b/docs/public/evidence/android/line-selected.png deleted file mode 100644 index fc5fb4d..0000000 Binary files a/docs/public/evidence/android/line-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/line-selected.webp b/docs/public/evidence/android/line-selected.webp new file mode 100644 index 0000000..a2f882d Binary files /dev/null and b/docs/public/evidence/android/line-selected.webp differ diff --git a/docs/public/evidence/android/line.png b/docs/public/evidence/android/line.png deleted file mode 100644 index 0a3f92b..0000000 Binary files a/docs/public/evidence/android/line.png and /dev/null differ diff --git a/docs/public/evidence/android/line.webp b/docs/public/evidence/android/line.webp index 1cf5110..b24bef1 100644 Binary files a/docs/public/evidence/android/line.webp and b/docs/public/evidence/android/line.webp differ diff --git a/docs/public/evidence/android/native-shell-home.png b/docs/public/evidence/android/native-shell-home.png deleted file mode 100644 index 87a171e..0000000 Binary files a/docs/public/evidence/android/native-shell-home.png and /dev/null differ diff --git a/docs/public/evidence/android/native-shell-line-selected.png b/docs/public/evidence/android/native-shell-line-selected.png deleted file mode 100644 index 67bb79a..0000000 Binary files a/docs/public/evidence/android/native-shell-line-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/native-shell-line-selected.webp b/docs/public/evidence/android/native-shell-line-selected.webp new file mode 100644 index 0000000..170156e Binary files /dev/null and b/docs/public/evidence/android/native-shell-line-selected.webp differ diff --git a/docs/public/evidence/android/pie-selected.png b/docs/public/evidence/android/pie-selected.png deleted file mode 100644 index 161f07c..0000000 Binary files a/docs/public/evidence/android/pie-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/pie-selected.webp b/docs/public/evidence/android/pie-selected.webp new file mode 100644 index 0000000..f279d87 Binary files /dev/null and b/docs/public/evidence/android/pie-selected.webp differ diff --git a/docs/public/evidence/android/pie.png b/docs/public/evidence/android/pie.png deleted file mode 100644 index caf22a4..0000000 Binary files a/docs/public/evidence/android/pie.png and /dev/null differ diff --git a/docs/public/evidence/android/pie.webp b/docs/public/evidence/android/pie.webp new file mode 100644 index 0000000..d263e28 Binary files /dev/null and b/docs/public/evidence/android/pie.webp differ diff --git a/docs/public/evidence/android/progress-selected.png b/docs/public/evidence/android/progress-selected.png deleted file mode 100644 index 06e4c4b..0000000 Binary files a/docs/public/evidence/android/progress-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/progress-selected.webp b/docs/public/evidence/android/progress-selected.webp new file mode 100644 index 0000000..31f51d6 Binary files /dev/null and b/docs/public/evidence/android/progress-selected.webp differ diff --git a/docs/public/evidence/android/progress.png b/docs/public/evidence/android/progress.png deleted file mode 100644 index 25ed7de..0000000 Binary files a/docs/public/evidence/android/progress.png and /dev/null differ diff --git a/docs/public/evidence/android/progress.webp b/docs/public/evidence/android/progress.webp new file mode 100644 index 0000000..d65bc18 Binary files /dev/null and b/docs/public/evidence/android/progress.webp differ diff --git a/docs/public/evidence/android/radar-selected.png b/docs/public/evidence/android/radar-selected.png deleted file mode 100644 index cbfacfa..0000000 Binary files a/docs/public/evidence/android/radar-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/radar-selected.webp b/docs/public/evidence/android/radar-selected.webp new file mode 100644 index 0000000..6ad5241 Binary files /dev/null and b/docs/public/evidence/android/radar-selected.webp differ diff --git a/docs/public/evidence/android/radar.png b/docs/public/evidence/android/radar.png deleted file mode 100644 index 2c701f5..0000000 Binary files a/docs/public/evidence/android/radar.png and /dev/null differ diff --git a/docs/public/evidence/android/radar.webp b/docs/public/evidence/android/radar.webp new file mode 100644 index 0000000..906d74b Binary files /dev/null and b/docs/public/evidence/android/radar.webp differ diff --git a/docs/public/evidence/android/scatter-selected.png b/docs/public/evidence/android/scatter-selected.png deleted file mode 100644 index 51b7047..0000000 Binary files a/docs/public/evidence/android/scatter-selected.png and /dev/null differ diff --git a/docs/public/evidence/android/scatter-selected.webp b/docs/public/evidence/android/scatter-selected.webp new file mode 100644 index 0000000..dfd5ca0 Binary files /dev/null and b/docs/public/evidence/android/scatter-selected.webp differ diff --git a/docs/public/evidence/android/scatter.png b/docs/public/evidence/android/scatter.png deleted file mode 100644 index b3acc74..0000000 Binary files a/docs/public/evidence/android/scatter.png and /dev/null differ diff --git a/docs/public/evidence/android/scatter.webp b/docs/public/evidence/android/scatter.webp new file mode 100644 index 0000000..6033cb4 Binary files /dev/null and b/docs/public/evidence/android/scatter.webp differ diff --git a/docs/public/evidence/ios/area-selected.png b/docs/public/evidence/ios/area-selected.png deleted file mode 100644 index 491746d..0000000 Binary files a/docs/public/evidence/ios/area-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/area-selected.webp b/docs/public/evidence/ios/area-selected.webp new file mode 100644 index 0000000..7369512 Binary files /dev/null and b/docs/public/evidence/ios/area-selected.webp differ diff --git a/docs/public/evidence/ios/area.png b/docs/public/evidence/ios/area.png deleted file mode 100644 index 72b21ad..0000000 Binary files a/docs/public/evidence/ios/area.png and /dev/null differ diff --git a/docs/public/evidence/ios/area.webp b/docs/public/evidence/ios/area.webp new file mode 100644 index 0000000..0dbde7a Binary files /dev/null and b/docs/public/evidence/ios/area.webp differ diff --git a/docs/public/evidence/ios/bar-selected.png b/docs/public/evidence/ios/bar-selected.png deleted file mode 100644 index b5e3a9b..0000000 Binary files a/docs/public/evidence/ios/bar-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/bar-selected.webp b/docs/public/evidence/ios/bar-selected.webp new file mode 100644 index 0000000..295beb8 Binary files /dev/null and b/docs/public/evidence/ios/bar-selected.webp differ diff --git a/docs/public/evidence/ios/bar.png b/docs/public/evidence/ios/bar.png deleted file mode 100644 index 5313806..0000000 Binary files a/docs/public/evidence/ios/bar.png and /dev/null differ diff --git a/docs/public/evidence/ios/bar.webp b/docs/public/evidence/ios/bar.webp index 2a1fbf6..a8d3327 100644 Binary files a/docs/public/evidence/ios/bar.webp and b/docs/public/evidence/ios/bar.webp differ diff --git a/docs/public/evidence/ios/candlestick-selected.png b/docs/public/evidence/ios/candlestick-selected.png deleted file mode 100644 index c7d06e6..0000000 Binary files a/docs/public/evidence/ios/candlestick-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/candlestick-selected.webp b/docs/public/evidence/ios/candlestick-selected.webp new file mode 100644 index 0000000..9b3d8ba Binary files /dev/null and b/docs/public/evidence/ios/candlestick-selected.webp differ diff --git a/docs/public/evidence/ios/candlestick.png b/docs/public/evidence/ios/candlestick.png deleted file mode 100644 index 21cd54d..0000000 Binary files a/docs/public/evidence/ios/candlestick.png and /dev/null differ diff --git a/docs/public/evidence/ios/candlestick.webp b/docs/public/evidence/ios/candlestick.webp new file mode 100644 index 0000000..0dc67a7 Binary files /dev/null and b/docs/public/evidence/ios/candlestick.webp differ diff --git a/docs/public/evidence/ios/contribution-heatmap-selected.png b/docs/public/evidence/ios/contribution-heatmap-selected.png deleted file mode 100644 index f8b4cd2..0000000 Binary files a/docs/public/evidence/ios/contribution-heatmap-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/contribution-heatmap-selected.webp b/docs/public/evidence/ios/contribution-heatmap-selected.webp new file mode 100644 index 0000000..b68e33a Binary files /dev/null and b/docs/public/evidence/ios/contribution-heatmap-selected.webp differ diff --git a/docs/public/evidence/ios/contribution-heatmap.png b/docs/public/evidence/ios/contribution-heatmap.png deleted file mode 100644 index c18f8c2..0000000 Binary files a/docs/public/evidence/ios/contribution-heatmap.png and /dev/null differ diff --git a/docs/public/evidence/ios/contribution-heatmap.webp b/docs/public/evidence/ios/contribution-heatmap.webp new file mode 100644 index 0000000..c2854ad Binary files /dev/null and b/docs/public/evidence/ios/contribution-heatmap.webp differ diff --git a/docs/public/evidence/ios/donut-selected.png b/docs/public/evidence/ios/donut-selected.png deleted file mode 100644 index dcecf52..0000000 Binary files a/docs/public/evidence/ios/donut-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/donut-selected.webp b/docs/public/evidence/ios/donut-selected.webp new file mode 100644 index 0000000..47aa4ae Binary files /dev/null and b/docs/public/evidence/ios/donut-selected.webp differ diff --git a/docs/public/evidence/ios/donut.png b/docs/public/evidence/ios/donut.png deleted file mode 100644 index 4dd1653..0000000 Binary files a/docs/public/evidence/ios/donut.png and /dev/null differ diff --git a/docs/public/evidence/ios/donut.webp b/docs/public/evidence/ios/donut.webp index 238dcf6..0d865d9 100644 Binary files a/docs/public/evidence/ios/donut.webp and b/docs/public/evidence/ios/donut.webp differ diff --git a/docs/public/evidence/ios/line-selected.png b/docs/public/evidence/ios/line-selected.png deleted file mode 100644 index 3b80328..0000000 Binary files a/docs/public/evidence/ios/line-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/line-selected.webp b/docs/public/evidence/ios/line-selected.webp new file mode 100644 index 0000000..4ef277e Binary files /dev/null and b/docs/public/evidence/ios/line-selected.webp differ diff --git a/docs/public/evidence/ios/line.png b/docs/public/evidence/ios/line.png deleted file mode 100644 index 0f1ed8b..0000000 Binary files a/docs/public/evidence/ios/line.png and /dev/null differ diff --git a/docs/public/evidence/ios/line.webp b/docs/public/evidence/ios/line.webp index 8b6d928..3648396 100644 Binary files a/docs/public/evidence/ios/line.webp and b/docs/public/evidence/ios/line.webp differ diff --git a/docs/public/evidence/ios/pie-selected.png b/docs/public/evidence/ios/pie-selected.png deleted file mode 100644 index bf32095..0000000 Binary files a/docs/public/evidence/ios/pie-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/pie-selected.webp b/docs/public/evidence/ios/pie-selected.webp new file mode 100644 index 0000000..e39c648 Binary files /dev/null and b/docs/public/evidence/ios/pie-selected.webp differ diff --git a/docs/public/evidence/ios/pie.png b/docs/public/evidence/ios/pie.png deleted file mode 100644 index 59ffc99..0000000 Binary files a/docs/public/evidence/ios/pie.png and /dev/null differ diff --git a/docs/public/evidence/ios/pie.webp b/docs/public/evidence/ios/pie.webp new file mode 100644 index 0000000..7859c6a Binary files /dev/null and b/docs/public/evidence/ios/pie.webp differ diff --git a/docs/public/evidence/ios/progress-selected.png b/docs/public/evidence/ios/progress-selected.png deleted file mode 100644 index aed705e..0000000 Binary files a/docs/public/evidence/ios/progress-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/progress-selected.webp b/docs/public/evidence/ios/progress-selected.webp new file mode 100644 index 0000000..29e602a Binary files /dev/null and b/docs/public/evidence/ios/progress-selected.webp differ diff --git a/docs/public/evidence/ios/progress.png b/docs/public/evidence/ios/progress.png deleted file mode 100644 index 1bdb701..0000000 Binary files a/docs/public/evidence/ios/progress.png and /dev/null differ diff --git a/docs/public/evidence/ios/progress.webp b/docs/public/evidence/ios/progress.webp new file mode 100644 index 0000000..78d2687 Binary files /dev/null and b/docs/public/evidence/ios/progress.webp differ diff --git a/docs/public/evidence/ios/radar-selected.png b/docs/public/evidence/ios/radar-selected.png deleted file mode 100644 index 129422e..0000000 Binary files a/docs/public/evidence/ios/radar-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/radar-selected.webp b/docs/public/evidence/ios/radar-selected.webp new file mode 100644 index 0000000..eeda0fb Binary files /dev/null and b/docs/public/evidence/ios/radar-selected.webp differ diff --git a/docs/public/evidence/ios/radar.png b/docs/public/evidence/ios/radar.png deleted file mode 100644 index b212b3f..0000000 Binary files a/docs/public/evidence/ios/radar.png and /dev/null differ diff --git a/docs/public/evidence/ios/radar.webp b/docs/public/evidence/ios/radar.webp new file mode 100644 index 0000000..081be39 Binary files /dev/null and b/docs/public/evidence/ios/radar.webp differ diff --git a/docs/public/evidence/ios/scatter-selected.png b/docs/public/evidence/ios/scatter-selected.png deleted file mode 100644 index 4e3aa54..0000000 Binary files a/docs/public/evidence/ios/scatter-selected.png and /dev/null differ diff --git a/docs/public/evidence/ios/scatter-selected.webp b/docs/public/evidence/ios/scatter-selected.webp new file mode 100644 index 0000000..4de3979 Binary files /dev/null and b/docs/public/evidence/ios/scatter-selected.webp differ diff --git a/docs/public/evidence/ios/scatter.png b/docs/public/evidence/ios/scatter.png deleted file mode 100644 index 96401b3..0000000 Binary files a/docs/public/evidence/ios/scatter.png and /dev/null differ diff --git a/docs/public/evidence/ios/scatter.webp b/docs/public/evidence/ios/scatter.webp new file mode 100644 index 0000000..65afa1a Binary files /dev/null and b/docs/public/evidence/ios/scatter.webp differ diff --git a/docs/public/llms.txt b/docs/public/llms.txt new file mode 100644 index 0000000..df4fbf6 --- /dev/null +++ b/docs/public/llms.txt @@ -0,0 +1,76 @@ +# NativePHP Charts + +> Composer package (donmanueldev/nativephp-charts) that adds ten native chart types to NativePHP Mobile apps. Charts are declared in Blade or built with a fluent PHP API. iOS renders them with Swift Charts and SwiftUI Canvas; Android renders them with Jetpack Compose Canvas. There is no WebView, JavaScript chart library, or network service. It is an independent community plugin, not an official NativePHP package. MIT license. + +## Requirements + +- PHP ^8.4 +- NativePHP Mobile ^4.0 +- Android API 26 or newer +- iOS 18.2 or newer +- NativePHP Desktop and WebView rendering are not supported. + +## Install + +```bash +composer require donmanueldev/nativephp-charts +php artisan vendor:publish --tag=nativephp-plugins-provider --no-interaction +php artisan native:plugin:register donmanueldev/nativephp-charts --no-interaction +php artisan native:plugin:list +php artisan native:plugin:validate +``` + +Rebuild the iOS or Android app after installing or updating, because the renderers compile into the native shell. + +## Chart elements + +- ``: ordered `series` of points +- ``: ordered `series`; `area-mode` overlay or stacked +- ``: ordered `series`; `mode` grouped or stacked, `orientation` vertical or horizontal +- ``: ordered `series` with numeric, date, or datetime x values +- ``: zero or one series of open, high, low, close points +- ``: ordered `segments` +- ``: ordered `segments`; `inner-radius-ratio` 0.2 to 0.85 +- ``: `axes` (3 to 24) and `series` with one value per axis +- ``: up to 24 `metrics` with values from 0 to 1 +- ``: daily `values` keyed by ISO date + +Selection callbacks bind with `_select="method"` and are decoded with `Donmanueldev\NativephpCharts\PointSelection::fromJson()`. + +## Docs + +- [Overview](https://donmanueldev.github.io/nativephp-charts/getting-started/overview/): what the package does and how to pick a chart +- [Installation](https://donmanueldev.github.io/nativephp-charts/getting-started/installation/): install, register, and render a first chart +- [API reference](https://donmanueldev.github.io/nativephp-charts/reference/api/): every Blade attribute, data shape, style section, and validation rule +- [Blade and PHP equivalence](https://donmanueldev.github.io/nativephp-charts/reference/blade-php/): Blade attributes mapped to fluent PHP methods + +## Charts + +- [Line chart](https://donmanueldev.github.io/nativephp-charts/charts/line/) +- [Area chart](https://donmanueldev.github.io/nativephp-charts/charts/area/) +- [Bar chart](https://donmanueldev.github.io/nativephp-charts/charts/bar/) +- [Scatter chart](https://donmanueldev.github.io/nativephp-charts/charts/scatter/) +- [Pie chart](https://donmanueldev.github.io/nativephp-charts/charts/pie/) +- [Donut chart](https://donmanueldev.github.io/nativephp-charts/charts/donut/) +- [Radar chart](https://donmanueldev.github.io/nativephp-charts/charts/radar/) +- [Candlestick chart](https://donmanueldev.github.io/nativephp-charts/charts/candlestick/) +- [Progress chart](https://donmanueldev.github.io/nativephp-charts/charts/progress/) +- [Contribution heatmap](https://donmanueldev.github.io/nativephp-charts/charts/contribution-heatmap/) + +## Guides + +- [Themes and presets](https://donmanueldev.github.io/nativephp-charts/guides/themes/) +- [Callbacks and interactions](https://donmanueldev.github.io/nativephp-charts/guides/callbacks-interactions/) +- [Copy-paste examples](https://donmanueldev.github.io/nativephp-charts/guides/copy-paste/) +- [Application recipes](https://donmanueldev.github.io/nativephp-charts/guides/recipes/) +- [Viewport and gestures](https://donmanueldev.github.io/nativephp-charts/guides/viewport-gestures/) +- [Accessibility](https://donmanueldev.github.io/nativephp-charts/guides/accessibility/) +- [Performance and validation](https://donmanueldev.github.io/nativephp-charts/guides/performance-evidence/) +- [Troubleshooting](https://donmanueldev.github.io/nativephp-charts/guides/troubleshooting/) +- [Migration and versioning](https://donmanueldev.github.io/nativephp-charts/guides/migration/) + +## Optional + +- [Apps using NativePHP Charts](https://donmanueldev.github.io/nativephp-charts/apps/) +- [Source code](https://github.com/donmanueldev/nativephp-charts) +- [Packagist](https://packagist.org/packages/donmanueldev/nativephp-charts) diff --git a/docs/public/og.png b/docs/public/og.png new file mode 100644 index 0000000..afa2b26 Binary files /dev/null and b/docs/public/og.png differ diff --git a/docs/src/content/docs/apps.md b/docs/src/content/docs/apps.md index ab3cdd6..8e51f4f 100644 --- a/docs/src/content/docs/apps.md +++ b/docs/src/content/docs/apps.md @@ -1,6 +1,6 @@ --- title: Apps using NativePHP Charts -description: Apps built with NativePHP Mobile that use NativePHP Charts. +description: "See real iOS and Android apps built with NativePHP Mobile that render native charts with NativePHP Charts, and how to add the same charts to your app." --- ## Despertá diff --git a/docs/src/content/docs/charts/area.mdx b/docs/src/content/docs/charts/area.mdx index 0cd22c3..bf066e7 100644 --- a/docs/src/content/docs/charts/area.mdx +++ b/docs/src/content/docs/charts/area.mdx @@ -1,7 +1,7 @@ --- -title: Area chart -description: Emphasize magnitude or composition across an ordered domain. -sidebar: { order: 2 } +title: Area chart for NativePHP Mobile +description: "Build native overlay or stacked area charts in NativePHP Mobile with Swift Charts and Jetpack Compose: gradients, fill-between series, and selection." +sidebar: { order: 2, label: "Area chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -21,7 +21,7 @@ Add this element to a native Blade view after [installing the package](/nativeph ## Native preview -
Area chart rendered by NativePHP Charts on Android
Android
Area chart after selecting a point on Android
Android · Point selection
Area chart running on iOS
iOS
Area chart after selecting a point on iOS
iOS · Point selection
+
Area chart rendered by NativePHP Charts on Android
Android
Area chart after selecting a point on Android
Android · Point selection
Area chart running on iOS
iOS
Area chart after selecting a point on iOS
iOS · Point selection
## Variants diff --git a/docs/src/content/docs/charts/bar.mdx b/docs/src/content/docs/charts/bar.mdx index 6ae7b9b..9517217 100644 --- a/docs/src/content/docs/charts/bar.mdx +++ b/docs/src/content/docs/charts/bar.mdx @@ -1,7 +1,7 @@ --- -title: Bar chart -description: Compare categories with grouped or stacked bars. -sidebar: { order: 3 } +title: Bar chart for NativePHP Mobile +description: "Compare categories with native grouped or stacked bar charts in NativePHP Mobile, vertical or horizontal, with currency formatting and selection." +sidebar: { order: 3, label: "Bar chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -21,7 +21,7 @@ Add this element to a native Blade view after [installing the package](/nativeph ## Native preview -
Bar chart rendered by NativePHP Charts on Android
Android
Bar chart after selecting a bar on Android
Android · Bar selection
Bar chart running on iOS
iOS
Bar chart after selecting a bar on iOS
iOS · Bar selection
+
Bar chart rendered by NativePHP Charts on Android
Android
Bar chart after selecting a bar on Android
Android · Bar selection
Bar chart running on iOS
iOS
Bar chart after selecting a bar on iOS
iOS · Bar selection
## Variants diff --git a/docs/src/content/docs/charts/candlestick.mdx b/docs/src/content/docs/charts/candlestick.mdx index 3be77fa..3e9b572 100644 --- a/docs/src/content/docs/charts/candlestick.mdx +++ b/docs/src/content/docs/charts/candlestick.mdx @@ -1,7 +1,7 @@ --- -title: Candlestick chart -description: Render one ordered OHLC series without hiding price extremes. -sidebar: { order: 8 } +title: Candlestick chart for NativePHP Mobile +description: "Plot open, high, low, and close prices with a native candlestick chart in NativePHP Mobile, with rising and falling colors, date axes, and viewport zoom." +sidebar: { order: 8, label: "Candlestick chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -23,7 +23,7 @@ Each series contains a stable `id`, a `name`, and points with `id`, `label`, typ ## Native preview -
Candlestick chart rendered by NativePHP Charts on Android
Android
Candlestick chart with a selected session tooltip on Android
Android · Candle selection
Candlestick chart with a focused OHLC domain on iOS
iOS
Candlestick chart after selecting a candle on iOS
iOS · Candle selection
+
Candlestick chart rendered by NativePHP Charts on Android
Android
Candlestick chart with a selected session tooltip on Android
Android · Candle selection
Candlestick chart with a focused OHLC domain on iOS
iOS
Candlestick chart after selecting a candle on iOS
iOS · Candle selection
LTTB sampling is intentionally rejected because it can hide OHLC extremes. Selection reports close as the primary value while preserving the OHLC fields in the chart contract. diff --git a/docs/src/content/docs/charts/contribution-heatmap.mdx b/docs/src/content/docs/charts/contribution-heatmap.mdx index 3f14c04..0558b32 100644 --- a/docs/src/content/docs/charts/contribution-heatmap.mdx +++ b/docs/src/content/docs/charts/contribution-heatmap.mdx @@ -1,7 +1,7 @@ --- -title: Contribution heatmap -description: Show daily activity intensity across a bounded calendar window. -sidebar: { order: 10 } +title: Contribution heatmap for NativePHP Mobile +description: "Display daily activity as a native calendar contribution heatmap in NativePHP Mobile, with a 7 to 371 day window, custom color scale, and day selection." +sidebar: { order: 10, label: "Contribution heatmap" } --- import { Code } from "@astrojs/starlight/components"; @@ -23,13 +23,13 @@ Each value contains a stable `id`, ISO `date`, non-negative `value`, and optiona ## Native preview -
Contribution heatmap rendered by NativePHP Charts on Android
Android
Contribution heatmap after selecting a day on Android
Android · Day selection
Contribution heatmap running on iOS
iOS
Contribution heatmap after selecting a day on iOS
iOS · Day selection
+
Contribution heatmap rendered by NativePHP Charts on Android
Android
Contribution heatmap after selecting a day on Android
Android · Day selection
Contribution heatmap running on iOS
iOS
Contribution heatmap after selecting a day on iOS
iOS · Day selection
The native accessibility representation exposes each populated visible day as one selectable item. Duplicate dates, negative values, or invalid ISO dates reject the snapshot; valid dates outside the configured window remain outside the visible grid. ## Variants -Choose a 7–371 day window, Sunday or Monday week start, and independent month and weekday labels. +Choose a 7–371 day window, any week start day (`week-starts-on` `0` for Sunday through `6` for Saturday; Monday by default), and independent month and weekday labels. ## Customization @@ -84,6 +84,8 @@ Every populated day is a native selectable item. Provide labels that include eno Required `values` contain `id`, ISO `date`, non-negative `value`, and optional `label`. Specialized props are `end-date`, `days`, `week-starts-on`, `colors`, `empty-color`, `show-month-labels`, and `show-weekday-labels`. +Days with a value of `0` use `empty-color`, like days without data. Other values pick a scale color in proportion to the largest visible value, so only the maximum reaches the last color. + ## Troubleshooting If a day is missing, verify it falls within the inclusive window ending at `end-date` and uses `YYYY-MM-DD`. diff --git a/docs/src/content/docs/charts/donut.mdx b/docs/src/content/docs/charts/donut.mdx index bdad623..aba227c 100644 --- a/docs/src/content/docs/charts/donut.mdx +++ b/docs/src/content/docs/charts/donut.mdx @@ -1,7 +1,7 @@ --- -title: Donut chart -description: Show part-to-whole data with space for a central summary. -sidebar: { order: 6 } +title: Donut chart for NativePHP Mobile +description: "Render native donut charts in NativePHP Mobile with an adjustable inner radius, segment gaps and corner radius, localized currency values, and selection." +sidebar: { order: 6, label: "Donut chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -21,7 +21,7 @@ Add this element to a native Blade view after [installing the package](/nativeph ## Native preview -
Donut chart rendered by NativePHP Charts on Android
Android
Donut chart after selecting a segment on Android
Android · Segment selection
Donut chart running on iOS
iOS
Donut chart after selecting a segment on iOS
iOS · Segment selection
+
Donut chart rendered by NativePHP Charts on Android
Android
Donut chart after selecting a segment on Android
Android · Segment selection
Donut chart running on iOS
iOS
Donut chart after selecting a segment on iOS
iOS · Segment selection
Use stable segment IDs to retain selection after value updates. The center is visual context, not a replacement for an accessible label or legend. diff --git a/docs/src/content/docs/charts/line.mdx b/docs/src/content/docs/charts/line.mdx index e4a93b1..ef5eea4 100644 --- a/docs/src/content/docs/charts/line.mdx +++ b/docs/src/content/docs/charts/line.mdx @@ -1,7 +1,7 @@ --- -title: Line chart -description: Show change, trends, and multiple ordered series. -sidebar: { order: 1 } +title: Line chart for NativePHP Mobile +description: "Draw native line charts in NativePHP Mobile with Blade or PHP: multiple series, date and numeric axes, point selection, pan and zoom, and LTTB sampling." +sidebar: { order: 1, label: "Line chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -23,7 +23,7 @@ Add this element to a native Blade view after [installing the package](/nativeph ## Native preview -
Line chart rendered by NativePHP Charts on Android
Android
Line chart after selecting a point on Android
Android · Point selection
Line chart running on iOS
iOS
Line chart after selecting a point on iOS
iOS · Point selection
+
Line chart rendered by NativePHP Charts on Android
Android
Line chart after selecting a point on Android
Android · Point selection
Line chart running on iOS
iOS
Line chart after selecting a point on iOS
iOS · Point selection
## Variants diff --git a/docs/src/content/docs/charts/pie.mdx b/docs/src/content/docs/charts/pie.mdx index ef27337..5a9c3f4 100644 --- a/docs/src/content/docs/charts/pie.mdx +++ b/docs/src/content/docs/charts/pie.mdx @@ -1,7 +1,7 @@ --- -title: Pie chart -description: Show a small part-to-whole snapshot. -sidebar: { order: 5 } +title: Pie chart for NativePHP Mobile +description: "Show a small part-to-whole breakdown with a native pie chart in NativePHP Mobile: ordered segments, preset colors, segment styling, and tap selection." +sidebar: { order: 5, label: "Pie chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -23,7 +23,7 @@ Each segment requires a stable `id`, non-empty `label`, non-negative `value`, an ## Native preview -
Pie chart rendered by NativePHP Charts on Android
Android
Pie chart after selecting a segment on Android
Android · Segment selection
Pie chart running on iOS
iOS
Pie chart after selecting a segment on iOS
iOS · Segment selection
+
Pie chart rendered by NativePHP Charts on Android
Android
Pie chart after selecting a segment on Android
Android · Segment selection
Pie chart running on iOS
iOS
Pie chart after selecting a segment on iOS
iOS · Segment selection
Selection emits the segment ID, label, value, and index. Prefer bar charts when exact comparison matters or when the legend becomes long. diff --git a/docs/src/content/docs/charts/progress.mdx b/docs/src/content/docs/charts/progress.mdx index dfe1765..62d65d6 100644 --- a/docs/src/content/docs/charts/progress.mdx +++ b/docs/src/content/docs/charts/progress.mdx @@ -1,7 +1,7 @@ --- -title: Progress chart -description: Compare several bounded completion values as concentric rings. -sidebar: { order: 9 } +title: Progress chart for NativePHP Mobile +description: "Show up to 24 completion values as native concentric progress rings in NativePHP Mobile, with a center label, ring styling, and metric selection." +sidebar: { order: 9, label: "Progress chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -21,7 +21,7 @@ Add this element to a native Blade view after [installing the package](/nativeph ## Native preview -
Progress chart rendered by NativePHP Charts on Android
Android
Progress chart with a selected ring on Android
Android · Ring selection
Progress chart running on iOS
iOS
Progress chart after selecting a ring on iOS
iOS · Ring selection
+
Progress chart rendered by NativePHP Charts on Android
Android
Progress chart with a selected ring on Android
Android · Ring selection
Progress chart running on iOS
iOS
Progress chart after selecting a ring on iOS
iOS · Ring selection
## Variants diff --git a/docs/src/content/docs/charts/radar.mdx b/docs/src/content/docs/charts/radar.mdx index e6d9955..023b9d3 100644 --- a/docs/src/content/docs/charts/radar.mdx +++ b/docs/src/content/docs/charts/radar.mdx @@ -1,7 +1,7 @@ --- -title: Radar chart -description: Compare profiles across three or more declared axes. -sidebar: { order: 7 } +title: Radar chart for NativePHP Mobile +description: "Compare profiles across 3 to 24 axes with a native radar chart in NativePHP Mobile, with per-axis maximums, grid levels, fill opacity, and selection." +sidebar: { order: 7, label: "Radar chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -21,7 +21,7 @@ Add this element to a native Blade view after [installing the package](/nativeph ## Native preview -
Radar chart rendered by NativePHP Charts on Android
Android
Radar chart with a selected axis tooltip on Android
Android · Axis selection
Radar chart running on iOS
iOS
Radar chart after selecting an axis on iOS
iOS · Axis selection
+
Radar chart rendered by NativePHP Charts on Android
Android
Radar chart with a selected axis tooltip on Android
Android · Axis selection
Radar chart running on iOS
iOS
Radar chart after selecting an axis on iOS
iOS · Axis selection
## Variants diff --git a/docs/src/content/docs/charts/scatter.mdx b/docs/src/content/docs/charts/scatter.mdx index d119f8f..b5309a0 100644 --- a/docs/src/content/docs/charts/scatter.mdx +++ b/docs/src/content/docs/charts/scatter.mdx @@ -1,7 +1,7 @@ --- -title: Scatter chart -description: Show correlation, clustering, and outliers. -sidebar: { order: 4 } +title: Scatter chart for NativePHP Mobile +description: "Plot correlation, clusters, and outliers with a native scatter chart in NativePHP Mobile using numeric, date, or datetime x values and per-point selection." +sidebar: { order: 4, label: "Scatter chart" } --- import { Code } from "@astrojs/starlight/components"; @@ -21,7 +21,7 @@ Add this element to a native Blade view after [installing the package](/nativeph ## Native preview -
Scatter chart rendered by NativePHP Charts on Android
Android
Scatter chart after selecting a point on Android
Android · Point selection
Scatter chart running on iOS
iOS
Scatter chart after selecting a point on iOS
iOS · Point selection
+
Scatter chart rendered by NativePHP Charts on Android
Android
Scatter chart after selecting a point on Android
Android · Point selection
Scatter chart running on iOS
iOS
Scatter chart after selecting a point on iOS
iOS · Point selection
## Variants diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md index 8a66730..bee6026 100644 --- a/docs/src/content/docs/getting-started/installation.md +++ b/docs/src/content/docs/getting-started/installation.md @@ -1,8 +1,7 @@ --- -title: Installation -description: Install the plugin and render your first chart in a NativePHP Mobile screen. -sidebar: - order: 2 +title: Install NativePHP Charts +description: "Install NativePHP Charts with Composer, register the plugin in NativePHP Mobile, and render your first native chart in a Blade screen on iOS and Android." +sidebar: { order: 2 } --- ## Requirements diff --git a/docs/src/content/docs/getting-started/overview.md b/docs/src/content/docs/getting-started/overview.md index 3dce1cb..2e1a1a8 100644 --- a/docs/src/content/docs/getting-started/overview.md +++ b/docs/src/content/docs/getting-started/overview.md @@ -1,8 +1,7 @@ --- -title: Overview -description: Add native charts to NativePHP Mobile screens with Blade and PHP. -sidebar: - order: 1 +title: NativePHP Charts overview +description: "What NativePHP Charts does: ten native chart types for NativePHP Mobile, drawn with Swift Charts and Jetpack Compose and configured from Blade or PHP." +sidebar: { order: 1 } --- NativePHP Charts adds ten chart types to NativePHP Mobile. Declare charts in Blade, pass data from PHP, and handle selections in your `NativeComponent`. Rendering uses Swift Charts and SwiftUI on iOS, and Jetpack Compose Canvas on Android. diff --git a/docs/src/content/docs/guides/accessibility.md b/docs/src/content/docs/guides/accessibility.md index 3e1e11a..3da6457 100644 --- a/docs/src/content/docs/guides/accessibility.md +++ b/docs/src/content/docs/guides/accessibility.md @@ -1,7 +1,7 @@ --- -title: Accessibility -description: Build charts that remain understandable with assistive technology and reduced motion. -sidebar: { order: 4 } +title: Chart accessibility with VoiceOver and TalkBack +description: "Make NativePHP charts usable with VoiceOver and TalkBack: accessibility labels, error labels, reduced motion, larger text, and meaningful point labels." +sidebar: { order: 4, label: "Accessibility" } --- Charts expose native accessibility elements to VoiceOver and TalkBack. Provide context with `a11y-label` and an actionable failure with `error-label`. diff --git a/docs/src/content/docs/guides/callbacks-interactions.md b/docs/src/content/docs/guides/callbacks-interactions.md index 9cde46a..dddce99 100644 --- a/docs/src/content/docs/guides/callbacks-interactions.md +++ b/docs/src/content/docs/guides/callbacks-interactions.md @@ -1,7 +1,7 @@ --- -title: Callbacks and interactions -description: Handle chart selections in a NativeComponent and configure Cartesian chart gestures. -sidebar: { order: 2 } +title: Chart selection callbacks and interactions +description: "Handle chart point selection in a NativePHP NativeComponent with PointSelection, and configure tap or scrub interaction, crosshairs, and tooltips." +sidebar: { order: 2, label: "Callbacks and interactions" } --- Bind `_select` to a public method on the `NativeComponent` that renders the chart. The method receives the selection as a JSON string. Native selection and tooltip updates do not need to wait for PHP. diff --git a/docs/src/content/docs/guides/copy-paste.md b/docs/src/content/docs/guides/copy-paste.md index e9fc108..c223937 100644 --- a/docs/src/content/docs/guides/copy-paste.md +++ b/docs/src/content/docs/guides/copy-paste.md @@ -1,7 +1,7 @@ --- -title: Copy-paste examples -description: Complete Blade and NativeComponent examples for common chart screens. -sidebar: { order: 2 } +title: Copy-paste NativePHP chart examples +description: "Copy-ready NativePHP Mobile screens with Blade views and NativeComponent classes for revenue trends, store comparisons, goals, and habit heatmaps." +sidebar: { order: 2, label: "Copy-paste examples" } --- Each example has the data owned by the `NativeComponent`, the chart in Blade, and a concrete interaction outcome. Replace the query and labels, but preserve the data shape and stable IDs. diff --git a/docs/src/content/docs/guides/migration.md b/docs/src/content/docs/guides/migration.md index 0f190ba..32ba4c9 100644 --- a/docs/src/content/docs/guides/migration.md +++ b/docs/src/content/docs/guides/migration.md @@ -1,7 +1,7 @@ --- -title: Migration -description: Adopt stable identities, versioned callbacks, themes, and new chart families safely. -sidebar: { order: 7 } +title: Migration and versioning +description: "Upgrade NativePHP Charts within 1.x: stable IDs, versioned callback payloads, themes, new chart families, and what the SemVer contract covers." +sidebar: { order: 7, label: "Migration" } --- ## Existing 1.x charts @@ -21,3 +21,25 @@ Compatibility-generated point IDs remain available in 1.x, but selection retenti Progress and contribution heatmap use the same version 1 selection envelope as existing charts. Consumers can extend an exhaustive `chart_type` match with `progress` and `contribution_heatmap` without changing callback transport. Publish native plugin updates through the platform compilation and native runtime validation workflow. + +## Stability and versioning + +NativePHP Charts follows [Semantic Versioning](https://semver.org/). Minor and patch releases in the 1.x line add features and fixes without breaking code written against an earlier 1.x release. Breaking changes require a new major version. + +The 1.x contract covers: + +- The ten Blade tags, such as ``, and the attributes documented in the [API reference](/nativephp-charts/reference/api/). +- The fluent element API: the classes in `Donmanueldev\NativephpCharts\Elements` and their public methods, such as `LineChart::make()->series(...)->onSelect(...)`. +- Callback payloads with `version: 1`, decoded by `PointSelection::fromJson()` and `ViewportChange::fromJson()`. Both reject any other version. +- The `presets` structure in `config/nativephp-charts.php`. + +The JSON that PHP sends to the Swift and Kotlin renderers is an internal detail and is not part of this contract. + +After every package update, including patch releases, rebuild the iOS and Android apps. The renderers are Swift and Kotlin sources that compile into the native shell, so `composer update` alone does not change what runs on the device: + +```bash +composer update donmanueldev/nativephp-charts +php artisan native:plugin:validate +``` + +Then rebuild each native target you ship before testing. diff --git a/docs/src/content/docs/guides/performance-evidence.md b/docs/src/content/docs/guides/performance-evidence.md index 3d9ada8..0a6f071 100644 --- a/docs/src/content/docs/guides/performance-evidence.md +++ b/docs/src/content/docs/guides/performance-evidence.md @@ -1,7 +1,7 @@ --- -title: Performance and validation -description: Size datasets, profile native rendering, and validate interactions in your app. -sidebar: { order: 5 } +title: Chart performance and validation +description: "Size datasets for NativePHP charts, reduce dense series with LTTB sampling, profile native rendering, and validate on iOS and Android before release." +sidebar: { order: 5, label: "Performance and validation" } --- Chart performance depends on the device, number of points, labels, animation, and enabled gestures. Measure the chart inside your app's actual screen and scrolling layout. diff --git a/docs/src/content/docs/guides/recipes.md b/docs/src/content/docs/guides/recipes.md index b77f359..0b68f2d 100644 --- a/docs/src/content/docs/guides/recipes.md +++ b/docs/src/content/docs/guides/recipes.md @@ -1,7 +1,7 @@ --- -title: Application recipes -description: Build product screens with validated chart data, Blade, and selection state. -sidebar: { order: 3 } +title: NativePHP chart recipes for real screens +description: "Recipes for NativePHP Mobile charts: sales dashboards, budgets, habit tracking, service health, and market prices with validated data and selection." +sidebar: { order: 3, label: "Application recipes" } --- These recipes show the boundary between application data and the chart contract. Query and authorize data in your component or service, map it to the required shape, then bind the resulting array to Blade. diff --git a/docs/src/content/docs/guides/themes.md b/docs/src/content/docs/guides/themes.md index 5869c9d..b744edd 100644 --- a/docs/src/content/docs/guides/themes.md +++ b/docs/src/content/docs/guides/themes.md @@ -1,7 +1,7 @@ --- -title: Themes and presets -description: Choose light or dark appearance, use built-in palettes, and define application presets. -sidebar: { order: 1 } +title: Chart themes, dark mode, and presets +description: "Control light and dark appearance of NativePHP charts, use the default, spectrum, or contrast presets, and register app presets with your own palette." +sidebar: { order: 1, label: "Themes and presets" } --- Every chart accepts a `theme` and a `preset`: diff --git a/docs/src/content/docs/guides/troubleshooting.md b/docs/src/content/docs/guides/troubleshooting.md index 1810d53..6440cde 100644 --- a/docs/src/content/docs/guides/troubleshooting.md +++ b/docs/src/content/docs/guides/troubleshooting.md @@ -1,7 +1,7 @@ --- -title: Troubleshooting -description: Diagnose registration, validation, rendering, payload, and interaction problems. -sidebar: { order: 6 } +title: Troubleshooting NativePHP Charts +description: "Fix common NativePHP Charts problems: unregistered plugins, Chart unavailable errors, empty charts, shifting selections, blocked scrolling, theme colors." +sidebar: { order: 6, label: "Troubleshooting" } --- ## The component is missing diff --git a/docs/src/content/docs/guides/viewport-gestures.md b/docs/src/content/docs/guides/viewport-gestures.md index 8cf9f45..f6e2aba 100644 --- a/docs/src/content/docs/guides/viewport-gestures.md +++ b/docs/src/content/docs/guides/viewport-gestures.md @@ -1,7 +1,7 @@ --- -title: Viewport and gestures -description: Configure x-axis pan and zoom, range limits, and settled viewport callbacks. -sidebar: { order: 3 } +title: Chart pan, zoom, and viewport gestures +description: "Enable x-axis pan and zoom on NativePHP Cartesian charts, set the initial range and minimum span, and handle settled changes with ViewportChange callbacks." +sidebar: { order: 3, label: "Viewport and gestures" } --- Line, area, bar, scatter, and candlestick charts support an initial viewport on `number`, `date`, or `datetime` x axes. Category axes do not support viewports. diff --git a/docs/src/content/docs/reference/api.md b/docs/src/content/docs/reference/api.md index 42c144e..8ab4c60 100644 --- a/docs/src/content/docs/reference/api.md +++ b/docs/src/content/docs/reference/api.md @@ -1,6 +1,6 @@ --- -title: API reference -description: Blade attributes, data requirements, defaults, and chart-specific options. +title: NativePHP Charts API reference +description: "Blade attribute reference for NativePHP Charts: common props, Cartesian axes and series, radial and specialized data, style sections, and validation." --- Use self-closing `` elements inside a NativePHP Mobile view. Bind PHP arrays, numbers, and booleans with `:`; pass literal strings without it. diff --git a/docs/src/content/docs/reference/blade-php.md b/docs/src/content/docs/reference/blade-php.md index 3add041..96687a6 100644 --- a/docs/src/content/docs/reference/blade-php.md +++ b/docs/src/content/docs/reference/blade-php.md @@ -1,6 +1,6 @@ --- -title: Blade and PHP equivalence -description: Map public Blade attributes to the fluent PHP API. +title: Blade attributes and fluent PHP API +description: "Map common NativePHP Charts Blade attributes to their fluent PHP methods so you can build the same native chart from a Blade view or a PHP element class." sidebar: { order: 2 } --- diff --git a/docs/src/layouts/Layout.astro b/docs/src/layouts/Layout.astro index 18c6e38..94c95a9 100644 --- a/docs/src/layouts/Layout.astro +++ b/docs/src/layouts/Layout.astro @@ -1,5 +1,40 @@ --- +interface Props { + title?: string; + description?: string; + noindex?: boolean; + structuredData?: boolean; +} + +const { + title = "NativePHP Charts: native charts for NativePHP Mobile on iOS and Android", + description = "Add native line, bar, pie, radar, candlestick and five more chart types to NativePHP Mobile apps with Blade or PHP. Swift Charts on iOS, Jetpack Compose on Android.", + noindex = false, + structuredData = false, +} = Astro.props; + const base = import.meta.env.BASE_URL.replace(/\/$/, ""); +const site = Astro.site ?? new URL("https://donmanueldev.github.io"); +const canonical = new URL(Astro.url.pathname, site).href; +const homeUrl = new URL(`${base}/`, site).href; +const ogImage = new URL(`${base}/og.png`, site).href; +const ogImageAlt = "NativePHP Charts: native charts for NativePHP Mobile, rendered with Swift Charts on iOS and Jetpack Compose on Android."; +const repository = "https://github.com/donmanueldev/nativephp-charts"; + +const jsonLd = structuredData + ? JSON.stringify({ + "@context": "https://schema.org", + "@type": "SoftwareSourceCode", + name: "NativePHP Charts", + description, + codeRepository: repository, + url: homeUrl, + license: "https://opensource.org/licenses/MIT", + programmingLanguage: ["PHP", "Swift", "Kotlin"], + runtimePlatform: ["iOS", "Android"], + author: { "@type": "Person", name: "Manuel Duarte" }, + }) + : null; --- @@ -7,16 +42,33 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, ""); + {title} + + {noindex ? : } + - - NativePHP Charts — documentation and examples + + + + + + + + + + + + + + + + + + {jsonLd &&