=== EasyVizi Sunburst ===
Contributors: easyvizi
Tags: chart, sunburst, pie chart, hierarchy, svg chart
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Hierarchical data as a sunburst (multi-level pie) chart: a block, a shortcode and a template function. No build step, works offline.

== Description ==

EasyVizi Sunburst turns hierarchical data - categories, sub-categories and values - into a multi-level pie chart where every ring is one level of the hierarchy. Each segment is sized by its share of its parent, so the outermost ring shows the finest breakdown.

**Three ways to add a chart**

1. **Block** - search for "EasyVizi Sunburst" in the block inserter. The sidebar gives you a live preview while you type, plus controls for height, number of rings, colors, legend and zoom. Paste JSON, or import a CSV straight from the sidebar.
2. **Shortcode** - `[easyvizi_sunburst title="Revenue" height="420"] ...JSON... [/easyvizi_sunburst]`, or point it at a JSON file with `src="https://example.com/data.json"`. Settings → EasyVizi Sunburst has a builder that turns pasted JSON or CSV into a ready-to-paste shortcode (and the matching PHP call).
3. **Template function** - `echo easyvizi_sunburst( $data, array( 'title' => 'Revenue' ) );` in any theme file.

**Two data formats**

A nested tree:

```
[
  { "name": "Acquisition", "children": [
      { "name": "Search", "value": 4100 },
      { "name": "Social", "value": 1750 }
  ] },
  { "name": "Revenue", "value": 5200 }
]
```

Or a flat list of rows, which is easier to produce from a spreadsheet. Leave `parent` empty for a top level row and give parent rows a value of `0` so their children are added up:

```
[
  { "id": "search", "parent": "", "label": "Search", "value": 0 },
  { "id": "search-organic", "parent": "search", "label": "Organic", "value": 4100 },
  { "id": "search-paid", "parent": "search", "label": "Paid", "value": 2300 }
]
```

A CSV export works too: import it in the block sidebar, or paste it into the builder on the settings screen. The first row names the columns - `id`, `parent`, `label`, `value` - in any order and with the usual aliases (`key`, `name`, `size`). Parent rows take a value of `0` so their children are added up.

**Highlights**

* Interactive: click a segment to zoom into it, click the center or a breadcrumb to zoom back out. Every segment is focusable and activates with Enter or Space.
* Labels: write each segment's name inside it, curved along the ring or in a straight line, or let the chart choose one style for the whole thing. A name that cannot reach the minimum size on its segment is left out rather than squeezed, and the minimum is a setting (14 pixels by default).
* Size: 560 pixels square by default, up to 2000, and everything scales with it.
* Center: an open hole, a solid circle standing for the whole chart, or a circle divided by the first level, all exactly one ring wide.
* Legend: below the chart, or beside it on either side.
* Colors: one hue per branch (shaded by ring), or a single hue shaded by ring. Bring your own hex palette with the `colors` attribute.
* Accessible: an off-screen table with every leaf value and its full path is rendered for screen readers, and the chart scales with the theme's font size and container.
* Private by default: the SVG is drawn in the browser from data already on the page. No requests to third-party chart services, no tracking, no cookies.
* Translators can start from the bundled `languages/easyvizi-sunburst.pot`.

The plugin was renamed from "Sunburst Chart" to EasyVizi Sunburst; `[sunburst_chart]` and older saved block markup still work.

**Shortcode attributes**

There are sixteen, covering size, rings, labels, the center, the legend and your own hex palette. The complete list, with values and defaults, is in `docs/SHORTCODE.md`.

The five you are most likely to reach for:

* `title` - caption above the chart.
* `height` - pixels, 120 to 2000, default 560. The chart is square, so the column caps the width.
* `arc_labels` - `off` (default), `auto`, `curved`, `radial`, `tangential` or `horizontal`.
* `colors` - comma separated hex colors, e.g. `colors="#4e79a7,#f28e2b"`. Hex only.
* `src` - URL returning JSON, used instead of inline data. Cached for one hour.

== Installation ==

1. Upload the `easyvizi-sunburst` folder to `/wp-content/plugins/`, or install the zip through Plugins → Add New → Upload Plugin.
2. Activate the plugin through the Plugins screen.
3. Open Settings → EasyVizi Sunburst to set the defaults and see examples.
4. Edit a post or page, insert the "EasyVizi Sunburst" block, and paste your JSON.

== Frequently Asked Questions ==

= Does it call an external service? =

No. The chart is drawn in the visitor's browser from data that is already in the page. The only outbound request the plugin can make is when you use the `src` attribute to load JSON from your own URL.

= How large can the data be? =

The renderer is comfortable with a few thousand segments. The PHP parser caps a chart at 20000 nodes and 16 levels, and silently ignores anything deeper. If a chart feels slow, lower the number of rings with `max_depth`.

= What happens without JavaScript? =

The chart's figures are always rendered into an off-screen table, which is announced to screen readers and visible if a visitor's browser blocks scripts. The chart itself needs JavaScript.

= Can I use my own colors? =

Yes - set the `colors` attribute, or the palette setting, to a comma separated list of six digit hex values, for example `colors="#4e79a7,#f28e2b"`. Values are validated server side and fall back to the built-in palette when nothing usable is supplied.

Only hex is read. An entry the renderer cannot parse is passed over, and that branch keeps an automatically chosen hue, so a color name or an `rgb()` value changes the chart without ever being painted.

= Can I import a spreadsheet? =

Yes, as CSV. Export your sheet with columns named `id`, `parent`, `label` and `value`, then use **Import CSV** in the block sidebar or paste it into the shortcode builder on the settings screen. Leave `parent` empty for a top level row and give parent rows a value of `0` so their children are added up.

= How do I put the names inside the chart? =

Set `arc_labels` (the "Labels on the segments" setting, or the block's Appearance panel): `auto` picks one style for the whole chart, and `curved`, `radial`, `tangential` or `horizontal` force one.

A name that cannot reach the minimum size is left blank rather than squeezed - hovering the segment still shows it, and the off-screen table always carries every figure. A percentage goes on its own line under the name, which is what lets a long name fit a narrow segment. The minimum is `label_min_size`, 14 pixels by default.

= How big should the chart be? =

`height` sets it - the chart is square, so it is the width too, and the column caps the width. The default is 560 pixels.

The whole chart scales with it, so a larger chart makes every label larger and lets more of them fit at the same minimum size.

= What can go in the middle? =

The center is always exactly one ring wide. `hub="hole"` leaves it open, `hub="disc"` fills it with a circle standing for the whole chart (with the total written on it, unless values are off), and `hub="split"` divides that circle by the first level of the hierarchy, so the rings start one level in.

= Can I translate it? =

Yes. The plugin text domain is `easyvizi-sunburst` and `languages/easyvizi-sunburst.pot` lists every string. Drop a `.po`/`.mo` pair into `languages/` or into `wp-content/languages/plugins/`.

= Does it work with RTL languages and dark themes? =

Yes. The layout is driven by CSS custom properties and logical properties, and the labels use the theme's text color.

== Screenshots ==

1. Three levels of hierarchy on a page, with the segment labels and the legend.
2. The same chart zoomed two levels in, with the heading naming the path back up.
3. The block in the editor: the live preview, and the inspector's layout and appearance controls.

== Changelog ==

= 1.0.1 =

* Renamed the plugin to EasyVizi Sunburst (display name and slug `easyvizi-sunburst`), to avoid confusion with an existing block of the same name. `[sunburst_chart]` and older saved block markup still work.
* Moved the developer notes out of the plugin root, and added `docs/SHORTCODE.md` with the full list of shortcode attributes.

= 1.0.0 =

* First release: sunburst block, `[easyvizi_sunburst]` shortcode, `easyvizi_sunburst()` template function, settings page, nested and flat-row data, branch and level color modes, zoom with breadcrumbs, keyboard support and an accessible data table.
* CSV import in the block sidebar, and a shortcode builder on the settings screen that turns pasted JSON or CSV into a shortcode or a PHP call.
* Segment labels inside the chart with a configurable minimum size, and a center exactly one ring wide.
* A `languages/` folder with a `.pot`, so translations can start.
* Renamed from Sunburst Chart to EasyVizi Sunburst; `[sunburst_chart]` and older saved block markup still work.
