Highcharts Theme | LineChart (#5246)

Co-authored-by: origami-z <[email protected]>
Co-authored-by: Josh Wooding <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Liberty Curtis <[email protected]>
Co-authored-by: mark-tate <[email protected]>

Author: 7 people

.changeset/tidy-radios-watch.md

@@ -0,0 +1,72 @@
+---
+"@salt-ds/highcharts-theme": minor
+---
+
+### Summary
+
+Salt Highcharts theme is a package that supplies the Salt theme for Highcharts. It includes a CSS file for all CSS-based styles, and an options object for styles that are not CSS configurable. Together, they provide a complete theming solution for Highcharts version 10 to version 12.
+
+_Please note, this package is a WIP. Highcharts CSS files and Options object are not finalised._
+
+### Rationale
+
+A theme-only package for Highcharts offers a lightweight solution focused solely on styling, making it easier to maintain and update visual consistency across charts. Unlike a full React wrapper, it doesn't impose additional abstraction layers, allowing developers to leverage Highcharts' native capabilities directly. This approach minimizes overhead and complexity, providing flexibility to integrate with various frameworks or environments without being tied to a specific implementation.
+
+### Supported charts
+
+This package is a work in progress and represents a snapshot release focusing specifically on the LineChart.
+
+Our intent is to gather feedback on the provided solution, allowing us to refine and expand the theme to support additional chart types in future, incremental releases.
+
+### Usage
+
+Please see the package [README.md](https://github.com/jpmorganchase/salt-ds/blob/main/packages/highcharts-theme/README.md) for guidance on usage.
+
+### License
+
+A license is required to use Highcharts.
+
+### Migration
+
+The Salt Highcharts theme replaces previous approaches that bundled a chart wrapper with styling. Because this package contains **only** theme assets (CSS + Highcharts options), you can keep using any Highcharts integration you prefer and simply apply the theme.
+
+**Steps to migrate**
+
+1. **Install the package** (snapshot build, requires Highcharts 10 – 12):
+
+   ```bash
+   # npm
+   npm install @salt-ds/highcharts-theme
+
+   # yarn
+   yarn add @salt-ds/highcharts-theme
+   ```
+
+2. **Import the theme resources** at your application entry point:
+
+   ```ts
+   import "@salt-ds/highcharts-theme/index.css";
+
+   // Salt CSS overrides
+   import Highcharts from "highcharts";
+   import { highchartsOptionsSalt } from "@salt-ds/highcharts-theme";
+
+   // apply global theme options
+   Highcharts.setOptions(highchartsOptionsSalt);
+   ```
+
+3. **Continue using your existing chart code.** For React you might use `highcharts-react-official` (or any other wrapper):
+
+   ```jsx
+   <div className="highcharts-theme-salt">
+     <HighchartsReact highcharts={Highcharts} options={chartOptions} />
+   </div>
+   ```
+
+4. **Merge additional options as required.** Highcharts deep-merges subsequent calls to `Highcharts.setOptions`; you can also combine objects per-chart with `Highcharts.merge()`.
+
+**Things to watch for:**
+
+- This snapshot styles **LineChart** only; other chart types will fall back to default Highcharts styles until future releases.
+- Ensure the Salt CSS is loaded **after** the default Highcharts CSS to guarantee correct specificity.
+- If a previous wrapper injected theme styles automatically, you must now call `Highcharts.setOptions` yourself and add the `highcharts-theme-salt` class to chart containers.

.stylelintrc.json

@@ -57,6 +57,17 @@
           }
         ]
       }
+    },
+    {
+      "files": ["**/highcharts-theme/css/**/*.css"],
+      "rules": {
+        "salt/correct-theme-token-usage": [
+          false,
+          {
+            "severity": "warning"
+          }
+        ]
+      }
     }
   ]
 }

package.json

@@ -15,6 +15,7 @@
     "start": "yarn storybook",
     "build": "yarn workspaces foreach --exclude @salt-ds/site -Apt run build && yarn bundle:css",
     "build:ag-grid-theme": "yarn workspace @salt-ds/ag-grid-theme build",
+    "build:hc-theme": "yarn workspace @salt-ds/highcharts-theme build",
     "bundle:css": "yarn bundle:core:css && yarn bundle:lab:css && yarn bundle:embla-carousel:css && yarn copy:icon:css && yarn copy:countries:css",
     "bundle:core:css": "yarn workspace @salt-ds/core bundle:css",
     "bundle:lab:css": "yarn workspace @salt-ds/lab bundle:css",
@@ -29,12 +30,13 @@
     "lint": "biome check",
     "lint:fix": "biome check --fix",
     "lint:check:error": "biome check --diagnostic-level=error",
-    "lint:style": "yarn lint:style:core && yarn lint:style:icon && yarn lint:style:lab && yarn lint:style:ag-theme",
+    "lint:style": "yarn lint:style:core && yarn lint:style:icon && yarn lint:style:lab && yarn lint:style:ag-theme && yarn lint:style:hc-theme",
     "lint:style:core": "yarn stylelint -f verbose \"packages/core/src/**/*.css\"",
     "lint:style:icon": "yarn stylelint -f verbose \"packages/icons/src/**/*.css\"",
     "lint:style:lab": "yarn stylelint -f verbose \"packages/lab/src/**/*.css\"",
     "lint:style:embla-carousel": "yarn stylelint -f verbose \"packages/embla-carousel/src/**/*.css\"",
     "lint:style:ag-theme": "yarn stylelint -f verbose \"packages/ag-grid-theme/css/**/*.css\"",
+    "lint:style:hc-theme": "yarn stylelint -f verbose \"packages/highcharts-theme/css/**/*.css\"",
     "lint:style:theme": "yarn stylelint -f verbose \"packages/theme/css/**/*.css\"",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "yarn build:ag-grid-theme && yarn bundle:css && storybook build --stats-json",
@@ -78,6 +80,8 @@
     "cypress-real-events": "^1.13.0",
     "deepmerge": "^4.2.2",
     "dom-accessibility-api": "^0.7.0",
+    "highcharts": "^10.2.0",
+    "highcharts-react-official": "^3.2.2",
     "mockdate": "^3.0.5",
     "msw": "^2.7.0",
     "msw-storybook-addon": "^2.0.4",

packages/highcharts-theme/README.md

@@ -0,0 +1,76 @@
+# Salt Highcharts Theme
+
+Salt Highcharts Theme is a package that adds Salt theme styles to Highcharts. The package contains a CSS file and a Highcharts global options object necessary for positional property application.
+
+_Please note, this package is a WIP. Highcharts CSS files and Options object are not finalised._
+
+## Supported Highchart versions
+
+This package is compatible with version 10 to 12 of Highcharts.
+
+Within the package CSS folder, the default theme is considered to be v10.
+
+CSS changes from other major versions are isolated into their own file but feature in prior versions too.
+
+### License
+
+A license is required to use Highcharts.
+
+## Installation
+
+To install the Salt Highcharts theme package, ensure you have a supported version of Highcharts installed and add `@salt-ds/highcharts-theme` via your package manager
+
+```bash
+npm install @salt-ds/highcharts-theme
+# or
+yarn add @salt-ds/highcharts-theme
+```
+
+### Import Highcharts CSS
+
+The Salt Highcharts theme overrides the default Highcharts CSS. To ensure the theme is applied correctly, import the Highcharts CSS before the Salt Highcharts theme CSS.
+
+> You can download the [Highcharts CSS
+> here](https://code.highcharts.com/10.2.0/css/highcharts.css), specifying the
+> required version via the URL.
+
+### Import Salt Highcharts theme
+
+To import the Salt Highcharts theme, use:
+
+```js
+import "@salt-ds/highcharts-theme/index.css";
+```
+
+Then wrap your Highcharts with `highcharts-theme-salt` class name as shown below:
+
+```jsx
+<div className="highcharts-theme-salt">
+  <HighchartsReact highcharts={Highcharts} options={yourChartSpecificOptions} />
+</div>
+```
+
+### Set Highcharts Global options
+
+Many Highchart stylistic properties cannot be configured via CSS alone. To adhere to the Salt design system, import and set the [Highcharts global options](https://www.highcharts.com/docs/getting-started/how-to-set-options) at your entry point.
+
+```js
+import Highcharts from "highcharts";
+
+Highcharts.setOptions(highchartsOptionsSalt);
+```
+
+### Compatibility with existing Highcharts options
+
+If you already have a [Highcharts global options object](https://www.highcharts.com/docs/getting-started/how-to-set-options), you can call `Highcharts.setOptions` again with the `highchartsOptionsSalt` after your initial call. Any fields set by `highchartsOptionsSalt` will take precedence over any previously set fields.
+
+For granular control, you can also use the `Highcharts.merge()` utility function to deep merge the `highchartsOptionsSalt` with your existing options object, including at the chart level.
+
+To see which Options properties the Salt Highchart Theme package provides, see `src/highcharts-options-salt.ts`.
+
+### Patterns and Fills
+
+The Salt Highcharts theme also provides Salt patterns and fills that can be applied to create visible contrast between series. For example, the `salt-line-patterns` class applies
+a line pattern to each series in a Line Chart.
+
+Guidance on Fills TBA.

packages/highcharts-theme/css/salt-highcharts-theme.css

@@ -0,0 +1,130 @@
+.highcharts-theme-salt .highcharts-color-0 {
+  fill: var(--salt-category-1-bold-background);
+  stroke: var(--salt-category-1-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-1 {
+  fill: var(--salt-category-2-bold-background);
+  stroke: var(--salt-category-2-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-2 {
+  fill: var(--salt-category-3-bold-background);
+  stroke: var(--salt-category-3-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-3 {
+  fill: var(--salt-category-4-bold-background);
+  stroke: var(--salt-category-4-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-4 {
+  fill: var(--salt-category-5-bold-background);
+  stroke: var(--salt-category-5-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-5 {
+  fill: var(--salt-category-6-bold-background);
+  stroke: var(--salt-category-6-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-6 {
+  fill: var(--salt-category-7-bold-background);
+  stroke: var(--salt-category-7-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-7 {
+  fill: var(--salt-category-8-bold-background);
+  stroke: var(--salt-category-8-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-8 {
+  fill: var(--salt-category-9-bold-background);
+  stroke: var(--salt-category-9-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-9 {
+  fill: var(--salt-category-10-bold-background);
+  stroke: var(--salt-category-10-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-grid-line {
+  stroke: var(--salt-separable-tertiary-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-title {
+  fill: var(--salt-content-primary-foreground);
+  font-size: var(--salt-text-h4-fontSize);
+  font-weight: var(--salt-text-h4-fontWeight);
+  line-height: var(--salt-text-h4-lineHeight);
+  font-family: var(--salt-text-h4-fontFamily);
+}
+.highcharts-theme-salt .highcharts-subtitle,
+.highcharts-theme-salt .highcharts-axis-title,
+.highcharts-theme-salt .highcharts-axis-labels {
+  fill: var(--salt-content-secondary-foreground);
+  font-size: var(--salt-text-label-fontSize);
+  line-height: var(--salt-text-label-lineHeight);
+  font-family: var(--salt-text-label-fontFamily);
+}
+
+/* Deselected legend state, requires !important to override default styles, which also use !important */
+.highcharts-theme-salt .highcharts-legend-item-hidden * {
+  stroke: revert !important;
+  fill: revert !important;
+  opacity: 0.2;
+}
+
+.highcharts-theme-salt .highcharts-legend-item > text,
+.highcharts-theme-salt .highcharts-legend-item span {
+  fill: var(--salt-content-secondary-foreground);
+  font-size: var(--salt-text-label-fontSize);
+  font-weight: var(--salt-text-label-fontWeight);
+  line-height: var(--salt-text-label-lineHeight);
+  font-family: var(--salt-text-label-fontFamily);
+}
+.highcharts-theme-salt .highcharts-axis-line {
+  stroke: var(--salt-separable-primary-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-data-label text,
+.highcharts-theme-salt text.highcharts-data-label {
+  fill: var(--salt-content-primary-foreground);
+  font-weight: var(--salt-text-label-fontWeight);
+  font-size: var(--salt-text-label-fontSize);
+  line-height: var(--salt-text-label-lineHeight);
+  font-family: var(--salt-text-label-fontFamily);
+}
+
+.highcharts-theme-salt .highcharts-tooltip-box {
+  fill: var(--salt-container-primary-background);
+}
+
+.highcharts-theme-salt .highcharts-tooltip text,
+.highcharts-theme-salt .highcharts-tooltip foreignObject span {
+  fill: var(--salt-content-primary-foreground);
+}
+
+.highcharts-theme-salt .highcharts-background {
+  fill: var(--salt-container-primary-background);
+}
+
+.highcharts-theme-salt path.highcharts-legend-nav-active {
+  fill: var(--salt-content-secondary-foreground);
+}
+
+.highcharts-theme-salt path.highcharts-legend-nav-inactive {
+  fill: var(--salt-content-secondary-foreground-disabled);
+}
+
+.highcharts-theme-salt text.highcharts-legend-navigation {
+  fill: var(--salt-content-secondary-foreground);
+  font-weight: var(--salt-text-label-fontWeight);
+  font-size: var(--salt-text-label-fontSize);
+  line-height: var(--salt-text-label-lineHeight);
+  font-family: var(--salt-text-label-fontFamily);
+}
+
+.highcharts-theme-salt .highcharts-point {
+  stroke: var(--salt-color-white);
+}

packages/highcharts-theme/css/salt-highcharts-v11.css

@@ -0,0 +1,3 @@
+.highcharts-theme-salt .highcharts-legend-item:hover text {
+  fill: var(--salt-content-secondary-foreground);
+}