=== Pop3D Charts – 2D/3D Data Visualizer ===
Contributors: clausernst
Donate link: https://www.paypal.com/paypalme/ClausErnst
Tags: 3d, charts, chart block, data visualization, webgl
Requires at least: 6.7
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.7.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create interactive 2D and real WebGL 3D charts in the WordPress Block Editor — a native Gutenberg chart block with CSV, JSON, XLSX and XLS import.

== Description ==

**Pop3D Charts** is a native WordPress chart block for creating interactive 2D and real WebGL 3D charts directly in the Gutenberg editor. Build responsive column charts, stacked charts, pie and donut charts, line/area charts, pyramid charts, and 3D stairs donut charts without shortcodes or an external chart dashboard.

The free plugin is made for visual data storytelling in WordPress: editorial articles, landing pages, reports, comparisons, survey results, educational content, KPI sections, and data-driven pages. Add the block, enter your values, paste spreadsheet data, or import CSV, JSON, XLSX, or XLS files. Then choose a chart layout, adjust the design in the sidebar, and publish an interactive chart that visitors can explore.

Unlike flat chart plugins or CSS-based 3D effects, Pop3D Charts renders its charts in a real WebGL scene using three.js. Where supported by the selected layout, visitors can switch between 2D and 3D views, rotate the chart, inspect the legend, open a semantic data table, and export the chart as a PNG.

Try the free version in [WordPress Playground](https://playground.wordpress.net/?blueprint-url=https%3A%2F%2Fclausernst.com%2Fwp-content%2Fuploads%2F01-docs%2Ffree-charts-playground%2Fpop3d-charts-free-blueprint-editorial-cards-v9.json) — no install required.

= Free WordPress chart layouts included =

* **Straight column charts** for classic category comparisons.
* **Stacked column charts** for totals, grouped values, and composition.
* **Pie and donut charts** for simple shares of a whole.
* **Line / Area charts** for trends, sequences, multi-series data, annotations, point labels, and optional area fills.
* **Pyramid charts** for ranked, proportional, or funnel-like comparisons.
* **3D stairs pie/donut charts** where each segment rises to its own height and forms a stepped 3D ring.
* **2D and 3D chart views** where supported by the selected layout.
* **Interactive front-end controls** with optional legend, sorting, fullscreen view, data table modal, and PNG export.
* **Responsive chart sections** for desktop, tablet, and mobile layouts.

= Designed for the WordPress Block Editor =

Everything important happens inside the block sidebar. You can edit rows, import data, switch chart layouts, change palettes, adjust labels, configure captions, and preview the result while you work.

There is no shortcode workflow and no separate proprietary chart database. Chart settings and chart data are stored as normal block attributes inside the post content.

= Free version features =

* **Native Gutenberg chart block** for the WordPress Block Editor.
* **Real WebGL rendering** via three.js for 3D chart scenes.
* **Chart layouts:** straight columns, stacked columns, pie/donut, **Line / Area**, **Pyramid**, and **3D stairs pie/donut**.
* **Eleven built-in color palettes:** Vivid, Ocean Sunset, Purple Raindrops, Spectrum, Magenta Dream, Twilight, Accessible, Material, Corporate, Monochrome, and Diverging.
* **Per-row color overrides** using hex color values.
* **Live editor preview** while editing data, labels, appearance, captions, and chart settings.
* **Manual row editor** for adding, editing, duplicating, reordering, and deleting chart rows.
* **Flexible data input:** enter rows manually, paste from a spreadsheet, or import JSON, CSV, XLSX, or XLS files.
* **Chart data export** as CSV or JSON.
* Optional **front-end controls** such as legend, sorting, data table modal, fullscreen view, and PNG download where enabled and supported.
* **Lazy loading** for 3D scenes when charts scroll into view.
* **Built-in translations** for English, German, French, and Spanish.
* **Accessibility-minded output** with labelled chart regions, semantic data tables, keyboard-friendly dialogs, accessible toolbar labels, and live regions for loading and tooltip states.

= Bring your own chart data =

Start with a few manual rows, paste values from Excel or Google Sheets, or import a prepared file. The importer accepts familiar column names and turns your data into chart rows automatically.

For most charts, the most useful columns are:

* `value` — the number that drives the chart.
* `headline` — the main label, such as a product, country, month, or category.
* `unit` — an optional unit such as `%`, `€`, `kWh`, or `items`.
* `paragraph` — optional tooltip text.
* `smallPrint` — an optional source note or footnote.
* `color` — an optional custom row color such as `#ff8800`.
* `groupKey` — useful for stacked chart groups and multi-series charts.

A simple CSV can look like this:

`value;unit;headline;paragraph;smallPrint`
`42;%;North;Sales region Q1;Report 2024`
`31;%;South;Sales region Q1;Report 2024`

Tip: create one chart manually, then export it as CSV from the block settings. The exported file gives you a practical template for your own spreadsheet.

= Built for visual data storytelling =

**Pop3D Charts** is made for charts that feel like part of the page instead of external reports embedded into it. Use it when a standard flat chart feels too plain and you want a more visual, interactive, and slightly fancy way to present your data.

It works especially well for:

* editorial data stories
* annual reports
* landing page sections
* product and feature comparisons
* survey results
* educational content
* simple KPI and performance summaries
* interactive data sections in WordPress pages and posts

= Optional Pro add-on =

The free plugin is fully usable on its own. An optional Pro add-on is available separately outside the WordPress.org directory and extends the same Gutenberg chart block with additional layouts, palettes, styling options, and ready-made chart patterns.

The free version includes straight columns, stacked columns, pie/donut, line/area, pyramid, and 3D stairs pie/donut charts, plus import/export, built-in palettes, 2D/3D views where supported, and optional front-end controls.

Pro is only needed if you want more advanced chart layouts such as arc, grouped, wave, horizontal, radial, bubble, or surface/heatmap charts, plus extra design options and chart patterns.

Learn more about Pro: [Pop3D Charts Pro](https://clausernst.com/en/pop3d-charts-wordpress-plugin/)

For free plugin support, please use the **Support** tab on this plugin page. Commercial support for the Pro version is handled through the vendor support channel.

== Installation ==

1. Install **Pop3D Charts – 2D/3D Data Visualizer** from the WordPress Plugin Directory, or upload the plugin ZIP under **Plugins → Add New → Upload Plugin**.
2. Activate the plugin.
3. Open a post or page in the WordPress block editor.
4. Click the **+** button and search for **Pop3D Charts**.
5. Insert the chart block.
6. Add rows manually, paste spreadsheet data, or import JSON, CSV, XLSX, or XLS data in the block sidebar.
7. Choose a layout, adjust the appearance, configure optional visitor controls, and publish your page.

== Frequently Asked Questions ==

= Is this a native Gutenberg chart block? =

Yes. Pop3D Charts is built for the WordPress Block Editor. You insert one chart block, configure it in the sidebar, and save it as part of the post or page content.

= Is this real WebGL 3D or just a CSS perspective effect? =

It is real WebGL 3D. Pop3D Charts uses three.js to render charts in a full WebGL scene. You can rotate the camera freely, view charts from different angles, and switch between 2D and 3D where supported by the selected layout. This is different from plugins that simulate depth using CSS transforms or simple 3D-pie effects.

= How many data rows are practical? =

For most editorial use cases, up to around 1,000 rows work well. Spreadsheet paste is limited to approximately 500 KB; file imports accept up to around 5 MB for XLSX and XLS files. For charts displayed on a page, 10–50 rows typically produce the clearest visual result.

= Is my chart data sent to your servers? =

No. Chart data is stored as block attributes inside your post content in your own WordPress database. Imported spreadsheet files are parsed locally in the browser during the editor session and are not uploaded to any external server.

= Does Pop3D Charts really render charts in 3D? =

Yes. Pop3D Charts renders 3D chart scenes with three.js and WebGL. As far as we currently know, it is one of the few WordPress chart builders with real three.js/WebGL 3D rendering directly inside Gutenberg.

= Is the free version only a demo? =

No. The free version is a complete chart block with the layouts, palettes, import options, and display features listed above. It can be used on production websites within that feature set.

= What chart layouts are included in the free version? =

The free version includes straight columns, stacked columns, pie/donut charts, a 3D stairs pie/donut, Line / Area, and Pyramid.

= Does the free version include 3D charts? =

Yes. The free version includes 2D and 3D display options where supported by the selected chart layout. The 3D stairs pie/donut is 3D-only by design.

= Does it use shortcodes? =

No. Charts are created as native Gutenberg blocks. You insert the chart block, configure it in the sidebar, and save it as part of the post or page content.

= Where is chart data stored? =

Chart data is stored in the block attributes inside the post content, similar to other Gutenberg blocks. The plugin does not require a separate proprietary chart database table for your chart series.

= Can I import spreadsheet data? =

Yes. You can enter data manually, paste it from a spreadsheet, or import JSON, CSV, XLSX, or XLS files.

= Which CSV columns should I use? =

For most charts, start with `value` and `headline`. You can add `unit`, `paragraph`, `smallPrint`, `color`, and `groupKey` when you need units, tooltip text, sources, custom colors, or grouped data.

= Can visitors view the chart data as a table? =

Yes. You can enable a front-end data table modal so visitors can inspect the same numbers in a semantic HTML table.

= Can visitors download charts? =

You can enable PNG export in the block settings where supported.

= Can I switch layouts after entering data? =

Yes. Your data remains in the block, and you can try the included chart layouts from the sidebar.

= Is there a Pro version? =

Yes. The Pro version is sold separately outside WordPress.org. It adds more chart layouts, more palettes, a custom palette builder, additional styling options, and chart patterns.

Learn more about Pro: [Pop3D Charts Pro](https://clausernst.com/en/pop3d-charts-wordpress-plugin/)

= Is the Pro version required? =

No. The free plugin works on its own. Pro is optional and adds advanced chart types, design options, and ready-made patterns for users who need more flexibility.

= Do I use a different block for Pro? =

No. Pro extends the same chart block after activation. You keep working inside the same Gutenberg block.

= Does it work with any WordPress theme? =

The plugin is built for the WordPress block editor and standard content areas. It should work with most modern block-compatible themes. If a theme applies very aggressive CSS to content elements, chart styling may be affected.

= Does it work with page builders like Elementor, Divi, or WPBakery? =

**Pop3D Charts** is built for the WordPress block editor. It may appear inside page-builder content where Gutenberg blocks are supported, but native editing is focused on Gutenberg.

= Can I use it on multilingual websites? =

Yes. The plugin includes translations for English, German, French, and Spanish. Other languages fall back to English.

== Screenshots ==

1. Add an interactive chart directly in the WordPress block editor.
2. Configure chart type, appearance, labels, captions, and front-end options in the sidebar.
3. Create straight column charts with optional 2D and 3D display.
4. Build stacked column charts with legends and value labels.
5. Display pie or donut charts with labels and tooltips.
6. Create Line / Area charts for trends, sequences, and multi-series data.
7. Build Pyramid charts for ranked or proportional comparisons.
8. Enter data manually or import JSON, CSV, XLSX, or XLS files.
9. Show a 3D stairs pie/donut where each segment rises to its own height.

== Credits ==
Attributions required under Apache License 2.0 for bundled components are listed in the root file NOTICE; the full Apache-2.0 license text is in licenses/APACHE-2.0.txt.

Third-party libraries and assets are bundled with this plugin and served from your site. Runtime dependencies such as Three.js are not loaded from external CDNs.

* **three.js** — 3D rendering (MIT License). https://threejs.org/
* **three.js examples** (OrbitControls, RoundedBoxGeometry, Reflector, CSS2DRenderer) — Same license as three.js (MIT), included alongside the vendor build.
* **SheetJS Community build** (`xlsx`) — Parsing `.xlsx` / `.xls` files in the block editor for import (Apache License 2.0). https://sheetjs.com/
* **Troika 3D text** (`troika-three-text` and sibling modules under `vendor/troika`) — Rendering text in WebGL scenes (Troika: MIT License). The file `vendor/troika/troika-three-text.esm.js` embeds components whose upstream licenses are called out at the top of that bundle: **Typr.ts** (MIT), **fflate** (MIT), **woff2otf** WOFF unpacking (Apache-2.0), and **unicode-font-resolver** client (MIT). https://github.com/protectwise/troika
* **Barlow Semi Condensed** (Bold and Light `.ttf` under `assets/`) — Typography in 3D labels (SIL Open Font License 1.1). https://fonts.google.com/specimen/Barlow+Semi+Condensed

The plugin does not transmit imported spreadsheet files to your server as uploads; parsing runs in the editor in the visitor’s browser. Chart settings and data live in normal block attributes in post content.

== Changelog ==

The most recent releases are listed below. The complete version history is also kept in the bundled changelog.txt file.

= 1.7.0 =
* New free **Pyramid** chart layout: stacked trapezoid segments sized by your data values, with 2D and 3D view.
* Dedicated **Pyramid** section in the block sidebar: segment gap, segment opacity, inverted pyramid, labels inside segments (off, value + unit, headline, or value with leader-line callouts), auto-contrast text, and optional left/right annotations from each row's headline, paragraph, and small print.
* Legend, tooltips, and camera framing include pyramid labels and callouts so they stay visible when you rotate the chart.

= 1.6.5 =
* Readme: **Line / Area** added to the free feature overview on wordpress.org (no code changes).

= 1.6.4 =
* New free **Line / Area** chart layout (formerly in Pro as “Wave”): ribbon or line style, multi-series, optional area fill, point and floor labels, annotations, ruler, tooltips, and 2D/3D view — with German, French, and Spanish translations in the block editor and on the front end.
* Chart data import and row editing support `groupKey`, `annotation`, and `annotationDesc` for Line / Area charts.

= 1.6.3 =
* Editor sidebar UX: new **Import / Export** tab (import dialog plus JSON/CSV row export); **Chart Data** tab is for editing rows only.
* Reordered block sidebar panels (axis and appearance before title; export and camera positions unchanged relative to legend).
* With Pop3D Charts Pro, the **Animation** tab now appears directly after **Camera** when that tab is shown.
* German, French, and Spanish translations for the Import / Export tab intro texts.

= 1.6.2 =
* Redesigned the chart data import dialog: clearer help, separate Paste and File tabs, live row count and data preview while you type or upload, a collapsible column reference with copy-header buttons, and a one-click sample dataset.
* Wider import dialog for easier editing; file upload explicitly supports JSON as well as CSV and Excel.
* Sample import data and placeholders now include the usual columns (including groupKey), with a six-row example across three groups.
* Updated German translations for the new import dialog.

= 1.6.1 =
* Hardened row links: when a chart is published, only valid http and https URLs are kept. Unsafe or invalid links (for example javascript: or data:) are removed.
* Links that open in a new tab now use noopener and noreferrer for safer browsing.

= 1.6.0 =
* New "Theme colors" palette: color the chart with your active theme's color palette. The editor preview and the published chart use the same colors in the same order. Themes that define no palette of their own fall back to the WordPress default palette.
* New optional link per data row: add a URL (and an "Open in new tab" switch) to any bar or pie/donut segment, so a click or tap on that element opens the link on the website. Dragging to rotate never triggers navigation, and links never open inside the block editor.

= 1.5.1 =
* Added an "Ignore custom bar colors" option under Data colors: switch to a color scheme without first clearing the individual colors set on each row. Your per-row colors stay saved and come back when you turn the option off.
* Fixed the color picker: after clicking "Use default" to reset a color, the picker now closes correctly when you click elsewhere in the sidebar.

= 1.5.0 =
* The diagram type picker has been redesigned for easier selection: chart types are now grouped under clear category headings (Bars & columns, Circular & proportions, Trends & relationships, Infographics), the icons are larger, and each chart's name is shown below its icon.
* Internal: the free core no longer carries the add-on (Pro) chart names; add-ons now supply their own layout names and category through the neutral extension point. No changes to how charts look or behave.

= 1.4.2 =
* Bar charts now cast a real shadow on the floor for added depth, and a new "Bar opacity" option lets you render the bars semi-transparent.
* Pie and donut charts now cast a soft shadow on the floor that gently fades toward the back.
* Pie and donut segments now have subtly rounded (beveled) edges, including the 3D stairs pie/donut.
* Internal: added a neutral extension point so add-ons can supply their own fit-point silhouette for precise, rotation-independent camera framing. No changes to how charts look or behave.

= 1.4.1 =
* Internal architecture cleanup: the free core no longer references the add-on (Pro) chart-layout names directly and now communicates with add-ons only through neutral extension points. No changes to how charts look or behave.

= 1.4.0 =
* Added an additional sidebar extension point so add-ons can register their own appearance options.
* Internal rendering refinements that add-ons can build on: optional soft, self-shadowing shadows and more precise, label-aware camera framing so labels are no longer clipped.

= 1.3.2 =
* Fixed selecting the chart block in the editor: clicking the chart now selects the block and opens its settings right away, instead of the sidebar only appearing after clicking the small controls icon.

= 1.3.1 =
* Charts now fade in smoothly when loading finishes instead of popping into view abruptly.
* Added internal extension points for add-ons: a post-initialization scene hook, neutral camera-control helpers, and support for add-on sidebar panels. These enable optional add-on features such as an intro camera animation.

= 1.3.0 =
* Data import errors are now shown directly in the import dialog with a clear message, instead of the import silently doing nothing when the data could not be read.
* Collapsed data rows now show their label and value at a glance, so long lists stay easy to scan without expanding every row.
* Diagram type buttons now use translated names for their tooltips and accessible labels.
* New "Fit axis to data" button in the Axis section sets the Y-axis minimum and maximum from your current values with a single click.
* Sidebar settings now appear only where they have an effect: the axis section adapts to the selected layout (value fields are no longer shown where they have no influence, and it is renamed to "Values & units" for layouts without an axis), label color pickers appear only when the matching labels are switched on, and sorting controls are hidden for layouts where reordering does not apply.
* Fixed a translation issue so the "Label A–Z" sort option now appears translated on German, Spanish, and French sites.

= 1.2.2 =
* The 3D stairs pie/donut now casts a soft shadow on the floor, and taller steps cast a subtle shadow onto lower neighboring segments, giving the chart more depth.

= 1.2.1 =
* Fixed the framing of the 3D stairs pie/donut so the chart stays visually centered. The camera now fits to the actual round, stepped shape instead of a surrounding box, removing the empty space around the corners and above shorter steps that previously made the chart look off-center — especially noticeable with tall steps.

= 1.2.0 =
* Added a configurable initial zoom for each chart in the Camera section of the block sidebar, so charts can start zoomed in a little closer or further out.
* The 2D/3D view toggle now animates back to this configured initial zoom, even if a visitor zoomed in or out beforehand.
* The 3D stairs pie/donut no longer shows the unused 2D/3D options in the editor (it is always shown in 3D); its initial zoom remains adjustable.

= 1.1.1 =
* Fixed the stair step height control for the 3D stairs pie/donut: changing the value now updates the step heights in the editor preview and on the front end (previously the setting was ignored).

= 1.1.0 =
* New free chart layout: **3D stairs pie/donut** — each segment rises to its own height, forming a staircase ring that lies flat and is shown in 3D.
* Added a configurable step height for the stairs pie/donut in the block sidebar.
* Tuned the default 3D camera angle, orbit range, and responsive stage height so the new layout is framed cleanly in the editor and on the front end.

= 1.0.0 =
* First public release under the name **Pop3D Charts – 2D/3D Data Visualizer**.
* Includes three chart layouts: straight columns, stacked columns, and pie/donut charts.
* Adds 2D and 3D display options where supported by the selected chart layout.
* Supports manual data entry, spreadsheet paste, and import from CSV, JSON, XLSX, and XLS files.
* Includes five built-in color palettes, per-row color overrides, live editor preview, chart data export, and optional visitor controls.
* Adds accessibility-minded chart output, built-in translations, and bundled third-party libraries served from the local plugin files.

= 0.9.0 =
* Prepared the plugin for the WordPress.org free version.
* Updated the plugin name, description, and documentation for the Pop3D Charts release.
* Clarified which layouts, palettes, import options, and front-end features are included in the free plugin.
* Added clearer information about the optional Pro add-on.
