Arranger Charts Docs

docs/charts/01-Overview.md

@@ -0,0 +1,23 @@
+# Overview
+
+**Arranger Charts** is a plugin for Arranger UIs for adding interactive aggregated data charts to React applications. It currently supports Bar and Sunburst charts. Arranger Charts also uses a React context provider to request data from Arranger Server for all charts on the page. Interacting with the charts can update the filters for data requested from Arranger Server.
+
+## Key Features
+
+- Leverages the [Nivo charts](https://github.com/plouc/nivo) library.
+- Integrates with Arranger theming for configuring colour schemes.
+- **ChartsProvider:** React context provider that requests all the data for all charts inside the provider.
+- **Bar chart:** Responsive, horizontal bar chart with configurable colours, tooltips, and sorting.
+- **Sunburst chart:** Responsive sunburst chart showing relationships between broad and specific categories.
+
+## Note About Arranger 3.1 and Multiple Catalogues/Indices
+
+Although Arranger 3.1 has been updated to support multiple catalogues (that is, Elasticsearch indices), currently the Arranger Charts library does not support this.
+
+Arranger Charts will only support one index/catalogue, with the document type `file`.
+
+[Arranger Charts issue for allowing multiple indices](https://github.com/overture-stack/arranger/issues/1084)
+
+## Dashboard Example
+
+![Dashboard with Arranger Charts](full-screenshot.png)

docs/charts/02-Setup.md

@@ -0,0 +1,53 @@
+# Setup
+
+For adding Arranger Charts in a React application.
+
+## Prerequisites
+
+- Node 24 or higher
+- React 18
+- Arranger Components 3 (for the data context provider)
+
+## Developer Setup
+
+This guide will walk you through installing Arranger Charts in your React application, and adding it to a page or component.
+
+### Installation
+
+```bash
+npm i @overture-stack/arranger-charts @overture-stack/arranger-components
+```
+
+### Quick Start
+
+Wrap a charts in required providers: `ArrangerDataProvider`,`ChartsProvider` and `ChartsThemeProvider`.
+
+Chart component is responsive to its parent container's dimensions.
+
+```jsx
+import { ChartsProvider, ChartsThemeProvider, BarChart, SunburstChart } from '@overture-stack/arranger-charts';
+import { ArrangerDataProvider } from '@overture-stack/arranger-components';
+
+function App() {
+	return (
+		<ArrangerDataProvider
+			apiUrl={YOUR_ARRANGER_API_URL}
+			documentType="file" // must be "file" for Arranger Charts
+		>
+			<ChartsProvider>
+				<ChartsThemeProvider>
+					<BarChart
+						fieldName="gender"
+						maxBars={10}
+						handlers={{ onClick: (data) => console.log(data) }}
+					/>
+				</ChartsThemeProvider>
+			</ChartsProvider>
+		</ArrangerDataProvider>
+	);
+}
+```
+
+### Dependencies
+
+Arranger Charts requires an `ArrangerDataProvider` from `@overture-stack/arranger-components` as a parent component to handle data fetching and SQON state management.

docs/charts/03-Guides/01-Usage.md

@@ -0,0 +1,174 @@
+# Usage
+
+This guide covers how to use Arranger Charts, what components are available, and React props for each component.
+
+## Components
+
+### ChartsProvider
+
+The main provider that manages chart registration and data fetching, and coordinates multiple charts.
+
+#### Props
+
+| Name                    | Type      | Required | Description                            |
+| ----------------------- | --------- | -------- | -------------------------------------- |
+| `debugMode`             | `boolean` | No       | Enable verbose logging for development |
+| `disableIncludeMissing` | `boolean` | No       | Hide properties with "No Data"         |
+| `loadingDelay`          | `number`  | No       | Delay network results by milliseconds  |
+
+#### Example
+
+```jsx
+<ChartsProvider
+	debugMode
+	disableIncludeMissing={false}
+	loadingDelay={250}
+>
+	{/* ChartsThemeProvider */}
+</ChartsProvider>
+```
+
+### ChartsThemeProvider
+
+Provides theme configuration and custom components to all child charts. You can nest multiple `<ChartsThemeProvider>` components under a single `<ChartsProvider>`.
+
+#### Props
+
+| Name                   | Type             | Required | Description                           |
+| ---------------------- | ---------------- | -------- | ------------------------------------- |
+| `colors`               | `string[]`       | No       | Array of hex colors for chart theming |
+| `components`           | `object`         | No       | Custom fallback components            |
+| `components.EmptyData` | `ReactComponent` | No       | Custom empty state component          |
+| `components.ErrorData` | `ReactComponent` | No       | Custom error component                |
+| `components.Loader`    | `ReactComponent` | No       | Custom loading component              |
+
+#### Example
+
+```jsx
+<ChartsThemeProvider
+	colors={['#ff6b6b', '#4ecdc4', '#45b7d1']}
+	components={{
+		EmptyData: NoDataMessage,
+		ErrorData: CustomError,
+		Loader: CustomSpinner,
+	}}
+>
+	{/* Charts */}
+</ChartsThemeProvider>
+```
+
+### BarChart
+
+Renders a horizontal bar chart for aggregation data.
+
+#### Props
+
+| Name                                   | Type       | Required | Description                                                                                         |
+| -------------------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `disableTopBarsCount`                  | `boolean`  | No       | Disables the "Top `bars` of `totalBars`" flag at the top right of charts.                           |
+| `fieldName`                            | `string`   | Yes      | GraphQL field name to visualize                                                                     |
+| `handlers`                             | `object`   | No       | Event handlers                                                                                      |
+| `handlers.onClick`                     | `function` | No       | Callback when clicking a bar segment                                                                |
+| `maxBars`                              | `number`   | Yes      | Maximum number of bars to display                                                                   |
+| `ranges`                               | `Range[]`  | No       | For numeric fields, specify value ranges. A `Range` is `{ key: string, from: number, to: number }`. |
+| `theme`                                | `object`   | Yes      | Chart configuration options                                                                         |
+| `theme.sortByKey`                      | `string[]` | No       | Array of keys to sort the data by.                                                                  |
+| `theme.axisBottom.customTickValueSize` | `number`   | `No`     | For setting a custom step size for the bottom (X) axis                                              |
+
+#### Example
+
+```jsx
+<ArrangerDataProvider
+	apiUrl={YOUR_ARRANGER_API_URL}
+	documentType="file" // must be "file" for Arranger Charts
+>
+	<ChartsProvider>
+		<ChartsThemeProvider>
+			<BarChart
+				fieldName="primary_site"
+				handlers={{
+					onClick: (data) => {
+						console.log('Clicked', data.label, data.value);
+					},
+				}}
+				maxBars={15}
+				theme={{
+					sortByKey: ['Brain', 'Lung', 'Breast', '__missing__'],
+				}}
+			/>
+		</ChartsThemeProvider>
+	</ChartsProvider>
+</ArrangerDataProvider>
+```
+
+#### Screenshot
+
+![Example of a bar chart](barchart.png)
+
+### SunburstChart
+
+Creates a sunburst chart showing relationships between broad and specific categories.
+
+#### Props
+
+| Name               | Type       | Required | Description                                     |
+| ------------------ | ---------- | -------- | ----------------------------------------------- |
+| `fieldName`        | `string`   | Yes      | GraphQL field name to visualize                 |
+| `maxSegments`      | `number`   | Yes      | Maximum number of segments to display           |
+| `mapper`           | `function` | Yes      | Maps outer ring values to inner ring categories |
+| `handlers`         | `object`   | No       | Event handlers                                  |
+| `handlers.onClick` | `function` | No       | Callback when clicking a segment                |
+| `theme`            | `object`   | No       | Chart configuration options                     |
+
+#### Example
+
+```jsx
+<ArrangerDataProvider
+	apiUrl={YOUR_ARRANGER_API_URL}
+	documentType="file" // must be "file" for Arranger Charts
+>
+	<ChartsProvider>
+		<ChartsThemeProvider>
+			<SunburstChart
+				fieldName="primary_diagnosis"
+				maxSegments={12}
+				mapper={(value) => {
+					if (value.startsWith('C78')) return 'Metastatic';
+					if (value.startsWith('C50')) return 'Breast Cancer';
+					return value;
+				}}
+				handlers={{
+					onClick: (data) => {
+						console.log('Selected category:', data);
+					},
+				}}
+			/>
+		</ChartsThemeProvider>
+	</ChartsProvider>
+</ArrangerDataProvider>
+```
+
+#### Screenshot
+
+![Example of a sunburst chart](sunburstchart.png)
+
+## Field Types
+
+Charts automatically detect field types from Arranger's extended mapping:
+
+- **Aggregations**: Categorical fields
+- **NumericAggregations**: Numeric fields that require range specifications
+
+For numeric fields, provide ranges:
+
+```jsx
+<BarChart
+	fieldName="age_at_diagnosis"
+	ranges={[
+		{ key: '0-18', from: 0, to: 18 },
+		{ key: '19-65', from: 19, to: 65 },
+		{ key: '65+', from: 65 },
+	]}
+	maxBars={10}
+/>
+```

docs/charts/03-Guides/02-Development.md

@@ -0,0 +1,46 @@
+# Development
+
+This guide covers how to develop or contribute to Arranger Charts. For using Arranger Charts in a React application, see [Guides/Usage](01-Usage.md).
+
+## Local Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build and watch for changes
+npm run dev
+```
+
+## Using Local Versions of Arranger Charts & Arranger Components
+
+To develop Arranger modules and see changes in your React app in real-time, you can use `npm link`:
+
+```bash
+# in your local Arranger folder
+cd modules/charts
+npm link
+cd ../..
+cd modules/components
+npm link
+```
+
+Then link these packages in your consumer React project:
+
+```bash
+# in your local React app
+npm link @overture-stack/arranger-charts
+npm link @overture-stack/arranger-components
+```
+
+To remove these links:
+
+```bash
+# in your local React app
+npm unlink @overture-stack/arranger-charts
+npm unlink @overture-stack/arranger-components
+```
+
+## Debug Mode
+
+Enable verbose logging by setting the `debugMode` prop on `ChartsProvider`.