@carbon/charts-angular 1.8.0 → 1.9.0-rc.3

package/src/stories/1-color-palette.stories.mdx

@@ -0,0 +1,73 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Docs/Tutorials/Color palette" />
+# Color palette
+> This version relies on <b>Carbon v11</b>. If you're using Carbon v10, <a href="https://carbon-charts-0x.netlify.app" target="_blank" rel="noreferrer">see the legacy demo site</a>.
+
+Carbon charts recently updated the default color palettes for `@carbon/charts` to follow the new IBM Design Language data vizualization palette.
+This means more accessibility and usability in terms of the color variants provided by the library.
+
+> For more guidance on using the IBM Design Language dataviz palette, see [here](https://www.carbondesignsystem.com/data-visualization/color-palettes/)
+
+<br/>
+## Using a default palette
+You can add the following chart options if you want to choose a color palette option from the Carbon dataviz palette.
+By default, carbon-charts will assign the first color option for the appropriate amount of data groups (ex. charts with 4 data groups will get the first option for the 4-color palettes).
+
+```ts
+const verySimpleBarData = [
+  { group: "Qty", value: 65000 },
+  { group: "More", value: 29123 }
+] // bar chart with 2 data groups "Qty" and "More"
+
+const verySimpleBarOptions = {
+  color: {
+    pairing: {
+      option: 2 // use the second color palette option for 2-group charts
+    }
+  }
+}
+```
+> Refer to the Carbon Design Website for the full index of color palette options (by group size).
+
+<br/>
+## Using a different size color palette
+
+> Note: It is not suggested to use a color palette designed for a different number of data groups than the chart is rendering.
+
+```ts
+// line chart with 2 data groups "Saturday" and "Sunday" initially but expecting
+// 3 data groups on some data loads when long weekend "Friday" or "Monday" is included
+const lineData = [
+  { group: "Saturday", sales: 65000 },
+  { group: "Sunday", sales: 29123 }
+]
+
+const lineOptions = {
+  color: {
+    pairing: {
+      numberOfVariants: 3, // use a palette with 3 color variants
+      option: 2 // use the 2nd option of 3 color charts
+    }
+  }
+}
+```
+
+<br/>
+## Using a custom color scale
+
+You're also able to provide a custom
+`color range` to be used within the color scale.
+You are expected to define values for _all the data groups_ in your chart. If less data groups are provided than the chart contains, it will
+default to using the IBM Design Language dataviz palette.
+
+```ts
+const simpleBarOptions = {
+  color: {
+    scale: {
+      "Dataset 1": "blue",
+      "Dataset 2": "red"
+    } // chart only has 2 data groups
+  }
+}
+```

package/src/stories/2-combo-charts.stories.mdx

@@ -0,0 +1,107 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Docs/Tutorials/Combo charts" />
+
+# Combo charts
+> This version relies on <b>Carbon v11</b>. If you're using Carbon v10, <a href="https://carbon-charts-0x.netlify.app" target="_blank" rel="noreferrer">see the legacy demo site</a>.
+
+Combo charts allow users to visually compare complex datasets by superimposing different graphing components within one chart.
+Combination charts **may or may not** use dual axes although it is common that they do. For more information on dual axes with **carbon-charts**, please see the [dual axes tutorial](/?path=/story/docs-tutorials--dual-axes-charts).
+
+> Note: `ComboChart` extends axis chart functionality and should only comprise of graphs/components that use axes.
+
+<br/>
+### Using the carbon-charts defaults
+
+There is support for using pre-existing carbon-charts graphs and combining them together within a `ComboChart`.
+The charts that can be seamlessly combined are all different **axis charts only**. This is the **recommended way to use `ComboCharts`**.
+
+Supported `ChartTypes` to combine:
+- `LineChart`
+- `ScatterChart`
+- `StackedScatterChart`
+- `AreaChart`
+- `StackedAreaChart`
+- `BarChart`
+- `GroupedBarChart`
+- `StackedBarChart`
+
+Below is an example of combining a carbon-charts `AreaChart` with a `LineChart`.
+
+```ts
+import { ChartTypes } from "@carbon/charts"
+const verySimpleComboData = [
+  { group: "Dataset 1", value: 650, date: "Tuesday" },
+  { group: "Dataset 2", value: 296, date: "Tuesday" },
+  // ...more data
+]
+
+const comboOptions = {
+  ...otherOptions, // global options apply to all the charts listed in chartTypes (where relevant)
+  axes: {...},
+  comboChartTypes: [ // takes an array of objects
+    {
+      type: ChartTypes.AREA // use a valid ChartType from enums
+      options: {}, // component specific options (i.e, turn on the scatter points, adjust scatter radius)
+      correspondingDatasets: ["Dataset 1"] // the datasets that we want to map with this type of chart
+    },
+    {
+      type: ChartTypes.LINE, // use a valid ChartType from enums
+      options: {
+        points: {
+          enabled: false // disabling the scatter points on the LineChart here won't affect the points in the AreaChart
+        }
+      }, // component specific options
+      correspondingDatasets: ["Dataset 2"]
+    }
+  ]
+}
+```
+> See the storybook demos for more combinations of charts and configurations.
+
+<br/>
+### Using custom graphs & components
+Custom components and **independent** carbon-charts components can also be rendered into a `ComboChart`. This allows
+users to create their own components and combine them with the pre-existing componentry offered.
+
+Below is an example of combining a carbon-charts `AreaChart` with a standalone `Line` class constructor.
+
+> Reminder: `ComboChart` extends axis chart functionality and should only comprise of graphs/components that use axes.
+
+```ts
+import { ChartTypes, Configuration, Component } from "@carbon/charts"
+
+const verySimpleComboData = [
+  { group: "Dataset 1", value: 650, date: "Tuesday" },
+  { group: "Dataset 2", value: 296, date: "Tuesday" },
+	// ...more data
+]
+
+const comboOptions = {
+  ...otherOptions, // global options apply to all the charts listed in chartTypes (where relevant)
+  axes: {...},
+  comboChartTypes: [ // takes an array of objects
+    {
+      type: ChartTypes.AREA // use a valid ChartType from enums
+      options: {},
+      correspondingDatasets: ["Dataset 1"] // the datasets that we want to map with this type of chart
+    },
+    {
+      type: Component.Line // using an imported class constructor
+			// add the base options for that type of chart if it is in the carbon-charts library and any additional configurations needed
+      options: Object.assign({}, Configuration.options.lineChart,  {
+        points: {
+          enabled: false // disabling the scatter points on the LineChart here won't affect the points in the AreaChart
+        }
+      }), // component specific options
+      correspondingDatasets: ["Dataset 2"]
+    }
+  ]
+}
+```
+
+Users can omit using any defaults (chartTypes) and build up the charts with independent class contructors if they choose. In the case where all the types are constructors,
+ComboChart **will still render some additional componetry for axis-charts** in addition to the custom/standalone components in the options.
+
+Keep in mind that when using components/graphs independently, the library will not enforce any type checking.
+This enables the user to extend `ComboChart` to cover complex cases but also leaves responsibility on the developers to use the right chart combinations.

package/src/stories/3-dual-axes-charts.stories.mdx

@@ -0,0 +1,51 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Docs/Tutorials/Dual axes charts" />
+
+# Dual Axes Charts
+> This version relies on <b>Carbon v11</b>. If you're using Carbon v10, <a href="https://carbon-charts-0x.netlify.app" target="_blank" rel="noreferrer">see the legacy demo site</a>.
+
+If a chart is considered to be a **dual axes** chart, it means that the chart uses 2 **different** axes for visually mapping [ranges](https://www.mathsisfun.com/sets/domain-range-codomain.html) for the data.
+Careful consideration should be taken when using dual axes charts because they can more often misrepresent the data.
+
+Please refer to dataviz guidelines [here](https://www.carbondesignsystem.com/data-visualization/getting-started) for more information on IBM's best practices.
+
+<br/>
+## Setting up a dual axes chart
+
+When using multiple Y or X axes, it is best to specify which axes will be primary (used for ranges or domain).
+Below we define options for an axis chart with **two dual axes (both vertical)** and one horizontal axis (bottom). In this case, we want to
+set up the horizontal axis (bottom) as the domain, and have the datasets' ranges mapped to the different vertical axes - "Temperature" on the left axis and "Products sold" on the right.
+
+Use the `main` option to define the `left` axis as the primary axis. The axis defined as `main` will be used to map **all datasets** until we set the
+`correspondingDatasets` on the non-primary (secondary) axis. If `correspondingDatasets` isn't set on the secondary axis, then the chart will render
+a read-only axis (without datasets mapped to it).
+
+```ts
+const dualAxesOptions = {
+  ...otherOptions,
+  axes: {
+    bottom: {
+      mapsTo: date,
+      scaleType: time
+    },
+    left: {
+      mapsTo: temperature,
+      scaleType: linear,
+      main: true // this will be the primary axis
+    },
+    right: {
+      mapsTo: value,
+      scaleType: linear,
+      // the dataset "Products sold" will map to this axis instead
+      correspondingDatasets: [
+        "Products sold"
+      ]
+    }
+  }
+}
+```
+
+Note: The library tries to determine the orientation/primary axes **without the use of `main`**,
+however it is best to be explicit when working with dual axes charts. If `main` is not specified, the library
+will try to determine the best primary/secondary assignments to make which could result in some confusion down the road.

package/src/stories/4-event-listeners.stories.mdx

@@ -0,0 +1,26 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Docs/Tutorials/Event listeners" />
+
+# Events in Carbon Charts
+> This version relies on <b>Carbon v11</b>. If you're using Carbon v10, <a href="https://carbon-charts-0x.netlify.app" target="_blank" rel="noreferrer">see the legacy demo site</a>.
+
+Event dispatching for chart elements allows applications to trigger custom UI actions and states when users interact with the charts.
+
+You can see the current dispatched events [here](https://carbon-design-system.github.io/carbon-charts/documentation/modules/_interfaces_events_.html).
+
+<br/>
+### Listening for events
+To listen for event just use a reference to the chart to add an event listener for one of the dispatched events above.
+This is an example for adding an event listener for a mouseover event on bar chart `rect`s.
+
+```ts
+barChart.services.events.addEventListener("bar-mouseover", e => console.log(e.detail))
+```
+
+<br/>
+### Code examples
+Here are some possible solutions for event binding:
+
+- [Vanilla JavaScript](https://codesandbox.io/p/sandbox/carbon-charts-vanilla-event-binding-9b1i5?file=/src/index.js)
+- [React](https://codesandbox.io/p/sandbox/carbon-charts-react-event-binding-contributed-by-eric-lowry-upztp?file=/src/App.js)

package/src/stories/5-tabular-data-format.stories.mdx

@@ -0,0 +1,132 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Docs/Tutorials/Tabular data format" />
+
+# Tabular data format
+> This version relies on <b>Carbon v11</b>. If you're using Carbon v10, <a href="https://carbon-charts-0x.netlify.app" target="_blank" rel="noreferrer">see the legacy demo site</a>.
+
+The default data format in Carbon Charts has a tabular nature.
+
+This means more flexibility for our users in terms of the shape
+of the data they can provide to the library.
+
+```ts
+const simpleBarData = [
+  { group: "Qty", value: 65000 },
+  { group: "More", value: 29123 },
+  { group: "Sold", value: 35213 },
+  { group: "Restocking", value: 51213 },
+  { group: "Misc", value: 16932 }
+]
+```
+
+Imagine an **array where each element is a datapoint.**
+
+Now we need to introduce some new fields into our `axes`
+options in order to map keys within our datapoints to axis values.
+
+<br/>
+##### Additions to charting options:
+*Note:* **This section does not apply to any
+non-axis charting components (e.g. pie & donut)**
+
+We'd still need a way to know which keys map to
+your values (`rangeIdentifier`) and which map to
+the labels you'd be showing on an axis (`domainIdentifier`).
+
+These identifiers can be set through the `mapsTo`
+option within each axis, and are defeaulted to `value`
+& (`key` or `date` - depending on whether your datapoints
+include dates).
+
+> Although the library will set fallback `mapsTo` defaults, you should always set your own.
+
+```ts
+const simpleBarOptions = {
+  title: "Simple bar (discrete)",
+  axes: {
+    left: {
+      mapsTo: "value"
+    },
+    bottom: {
+      mapsTo: "group",
+      scaleType: "labels"
+    }
+  }
+}
+```
+<br/>
+##### Non-axis chart types:
+
+In the case of pie and donut, the library will
+always look for the `value` key within your datapoints:
+
+```ts
+export const pieData = [
+  { group: "2V2N 9KYPM version 1", value: 20000 },
+  { group: "L22I P66EP L22I P66EP L22I P66EP", value: 65000 },
+  { group: "JQAI 2M4L1", value: 75000 },
+  { group: "J9DZ F37AP", value: 1200 },
+  { group: "YEL48 Q6XK YEL48", value: 10000 },
+  { group: "Misc", value: 25000 }
+]
+```
+<br/>
+##### Customizable options:
+
+You're able to customize the `groupMapsTo`
+which is used to determine the key within your data that
+identifies the grouping of the datapoints.
+
+```ts
+const simpleBarOptions = {
+  data: {
+    groupMapsTo: "category"
+  }
+}
+
+const simpleBarData = [
+  { category: "Qty", value: 65000 },
+  { category: "More", value: 29123 },
+  { category: "Sold", value: 35213 },
+  { category: "Restocking", value: 51213 },
+  { category: "Misc", value: 16932 }
+]
+```
+
+For bubble charts, you're able to customize the "radius" identifier:
+```ts
+export const bubbleDoubleLinearOptions = {
+  title: "Bubble (linear)",
+  axes: {
+    bottom: {
+      title: "No. of employees",
+      mapsTo: "sales",
+      includeZero: false
+    },
+    left: {
+      title: "Annual sales",
+      mapsTo: "profit",
+      includeZero: false
+    }
+  },
+  bubble: {
+    radiusMapsTo: "surplus"
+  }
+}
+
+const bubbleDoubleLinearData = [
+  { group: "Dataset 1", sales: 10000, profit: 32100, surplus: 50000 },
+  { group: "Dataset 1", sales: 12000, profit: 23500, surplus: 34000 },
+  { group: "Dataset 1", sales: 14000, profit: 53100, surplus: 63000 },
+  { group: "Dataset 1", sales: 15000, profit: 42300, surplus: 43000 },
+  { group: "Dataset 1", sales: 16000, profit: 12300, surplus: 55000 },
+  { group: "Dataset 2", sales: 11000, profit: 12400, surplus: 25000 },
+  { group: "Dataset 2", sales: 13000, profit: 34500, surplus: 35000 },
+  { group: "Dataset 2", sales: 13500, profit: 23100, surplus: 55000 },
+  { group: "Dataset 2", sales: 15500, profit: 63200, surplus: 35000 },
+  { group: "Dataset 2", sales: 15750, profit: 24300, surplus: 64000 }
+]
+```
+
+> Default value for `radiusMapsTo` is `radius`

package/src/stories/6-themes.stories.mdx

@@ -0,0 +1,50 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Docs/Tutorials/Themes" />
+
+# Themes
+> This version relies on <b>Carbon v11</b>. If you're using Carbon v10, <a href="https://carbon-charts-0x.netlify.app" target="_blank" rel="noreferrer">see the legacy demo site</a>.
+
+We support all 4 Carbon themes (white, g10, g90 & g100), which are all included inside the main CSS bundle.
+After importing the carbon styles, pass in one of the four Carbon themes in options like in the examples below.
+
+**If using CSS:**
+
+You'd need to import our **CSS bundle** `@carbon/charts/styles.css`
+
+e.g.
+
+```html
+<div id="my-sample-chart"></div>
+```
+
+```ts
+const chartHolder = document.getElementById("my-sample-chart")
+new SimpleBarChart(chartHolder, {
+  data,
+  options: {
+    ...myChartOptions,
+    theme: "g100", // Pass theme in options
+  }
+})
+```
+
+**If using SCSS:**
+
+```scss
+@import "@carbon/charts/styles/styles.scss";
+```
+
+```ts
+const chartHolder = document.getElementById("my-sample-chart")
+new SimpleBarChart(chartHolder, {
+  data,
+  options: {
+    ...myChartOptions,
+    theme: "g100", // Pass theme in options
+  }
+})
+```
+<br/>
+## Color palette
+- Our color palette udpates automatically on theme switches

package/src/stories/all.stories.ts

@@ -0,0 +1,104 @@
+import { storiesOf, type Args, type StoryFn } from '@storybook/angular'
+import sdk from '@stackblitz/sdk'
+import { ChartTheme } from '@carbon/charts'
+import { type Demo, type DemoGroup, storybookDemoGroups } from '@carbon/charts/demo'
+import { ChartsModule } from '../'
+
+const DEFAULT_THEME = ChartTheme.G100
+
+storiesOf('Docs', module).add(
+	'Welcome',
+	() => ({
+		template: `
+		<div class="container intro">
+			<div
+			class="welcome__container"
+			style="background: url(./welcome.png) no-repeat center center fixed; background-size: cover;">
+				<div class="welcome__content">
+					<h2 class="welcome__heading">Carbon Charts</h2>
+					<h4 class="welcome__heading welcome__heading--subtitle">(Angular)</h4>
+					<h5 class="welcome__heading welcome__heading--other">Other versions</h5>
+					<ul>
+						<li><a href="https://charts.carbondesignsystem.com" class="welcome__heading welcome__heading--other">Vanilla JavaScript</a></li>
+						<li><a href="https://charts.carbondesignsystem.com/react" class="welcome__heading welcome__heading--other">React</a></li>
+						<li><a href="https://charts.carbondesignsystem.com/vue" class="welcome__heading welcome__heading--other">Vue</a></li>
+						<li><a href="https://charts.carbondesignsystem.com/svelte" class="welcome__heading welcome__heading--other">Svelte</a></li>
+					</ul>
+					<span class="netlify">Deploys by <a href="https://netlify.com" target="_blank">Netlify</a></span>
+				</div>
+			</div>
+		</div>`
+	}),
+	{
+		controls: {
+			hideNoControlsWarning: true
+		}
+	}
+)
+
+const getTemplate = (componentSelector: string) => `
+	<div class="container">
+		<div class="v10-banner">
+			This version relies on <b>Carbon v11</b>. If you're using Carbon v10, <a href="https://carbon-charts-0x.netlify.app" target="_blank" rel="noreferrer">see the legacy demo site</a>
+		</div>
+		<h3>
+			<b>Component:</b>
+			<span class="cds--tag cds--tag--green component-name">${componentSelector}</span>
+		</h3>
+		<p class="props">
+		  <b>Props:</b> data, <a href="https://carbon-design-system.github.io/carbon-charts/documentation/modules/_interfaces_charts_.html" target="_blank">options</a>
+		</p>
+		<div class="marginTop-30" id="chart-demo">
+			<${componentSelector} [data]="data" [options]="options"></${componentSelector}>
+		</div>
+		<h3 class="marginTop-30">Code sample</h3>
+		<p>Opens in a new tab. Please ensure pop-up blocker is not on.</p><br/>
+		<a href="#" (click)="openSandbox($event)">
+			<img
+				src="https://developer.stackblitz.com/img/open_in_stackblitz.svg"
+				className="marginTop"
+				alt="Edit on StackBlitz"
+			/>
+		</a>
+	</div>`
+
+// Loop through demo groups array
+storybookDemoGroups.forEach((demoGroup: DemoGroup) => {
+	// Create story group
+	const groupStories = storiesOf(`${demoGroup.storyGroupTitle}/${demoGroup.title}`, module)
+
+	// Create stories within story group
+	demoGroup.demos.forEach((demo: Demo) => {
+		demo.options.theme = DEFAULT_THEME
+		document.documentElement.setAttribute('data-carbon-theme', DEFAULT_THEME)
+		const demoStory: StoryFn = (args: Args) => ({
+			template: getTemplate(demo.chartType.angular as string),
+			moduleMetadata: {
+				imports: [ChartsModule]
+			},
+			props: {
+				data: args['data'],
+				options: args['options'],
+				// StackBlitz
+				openSandbox: (event: Event) => {
+					event.preventDefault()
+					sdk.openProject(demo.code.angular, { newWindow: true })
+				}
+			}
+		})
+		groupStories.add(demo.title, demoStory, {
+			args: {
+				data: demo.data,
+				options: demo.options
+			},
+			argTypes: {
+				data: {
+					control: { type: 'object' }
+				},
+				options: {
+					control: { type: 'object' }
+				}
+			}
+		})
+	})
+})

package/src/stories/angular.stories.mdx

@@ -0,0 +1,136 @@
+import { Meta } from '@storybook/blocks'
+
+<Meta title="Docs/Getting Started/Angular" />
+
+# Carbon Charts - Angular
+
+The Carbon Charts Angular library provides a collection of reusable charting components to build websites
+and user interfaces.
+
+Adopting the library enables developers to use consistent markup, styles, and behavior
+in prototype and production work.
+
+[Angular wrappers - storybook](https://carbon-design-system.github.io/carbon-charts/angular)
+
+<br/>
+## Install
+
+**with yarn (preferred):**
+```bash
+yarn add @carbon/charts-angular @carbon/styles d3
+```
+
+**with npm:**
+```bash
+npm install --save @carbon/charts-angular @carbon/styles  d3
+```
+
+## Getting started
+
+To start using the `StackedBarChart` component, try the example below:
+
+
+<br/>
+###### app.module.ts
+```ts
+import { NgModule } from '@angular/core'
+import { BrowserModule } from '@angular/platform-browser'
+
+import { ChartsModule } from '@carbon/charts-angular'
+
+import { AppComponent } from './app.component'
+
+@NgModule({
+  imports: [BrowserModule, ChartsModule],
+  declarations: [AppComponent],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```
+
+###### app.component.html
+```html
+<ibm-stacked-bar-chart
+  class="n-chart"
+  [data]="stackedBarData"
+  [options]="stackedBarOptions"
+  #stackedBarChart
+></ibm-bar-chart>
+```
+
+###### app.component.ts
+```ts
+import { Component } from '@angular/core'
+
+import '@carbon/styles/css/styles.css'  // may affect global styles
+import '@carbon/charts-angular/styles.css'
+
+@Component({
+  selector: 'my-app',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.css'],
+})
+export class AppComponent {
+  stackedBarData = [
+    // refer to tabular data format tutorial
+  ]
+
+  stackedBarOptions = {
+    // refer to chart specific options
+  }
+}
+```
+
+<br/>
+## Data
+Data follows the same model in all charts.
+See tutorial on tabular data format for more information on chart data.
+
+<br/>
+## Options
+
+You can see the default options for all charts
+[here](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/core/src/configuration.ts).
+
+<br/>
+## Demos and Examples
++ **[Storybook - Demos](https://carbon-design-system.github.io/carbon-charts/angular)**
++ **[Storybook - Story Sources](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/angular/stories)**
++ **[Storybook - Data & options used](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/core/demo/data)**
+
+<br/>
+## Guidance
+
+Please refer to the
+[Carbon Design Systems guidance](https://www.carbondesignsystem.com/data-visualization/chart-types)
+on using the different charts available in this library.
+
+<br/>
+## Development
+Please refer to the
+[Contribution Guidelines](https://github.com/carbon-design-system/carbon-charts/blob/master/CONTRIBUTING.md)
+before starting any work.
+
+#### Using the server
+We recommend the use of [Angular Storybook](https://github.com/storybookjs/storybook/tree/next/app/angular)
+for developing components.
+
+**Start the server:**
+```bash
+cd packages/angular
+yarn storybook
+```
+
+Open browser to `http://localhost:9005`
+
+<br/>
+## List of available components
+View available components [here](https://github.com/carbon-design-system/carbon-charts#component-status)
+
+<br/>
+## Troubleshoot
+
+If you experience any issues while getting set up with Carbon Charts, please head over to the
+[GitHub repo](https://github.com/carbon-design-system/carbon-charts) for more guidelines and support.
+Please [create an issue](https://github.com/carbon-design-system/carbon-charts/issues) if your issue
+does not already exist.