Add DonutChart with patterns, useChart hook, and density support

   - Donut chart component with configurable patterns
   - useChart hook for density-aware chart properties
   - Fill patterns for accessibility
   - Updated documentation and examples

Author: tycup

.changeset/tasty-snakes-clean.md

@@ -0,0 +1,11 @@
+---
+"@salt-ds/highcharts-theme": patch
+---
+
+- `useChart` hook is density-aware. When Salt density changes, it triggers a `chart.redraw()` and returns a `legendIconSize` mapped to Salt size tokens, enabling responsive legend symbol sizing.
+- Salt theme defaults (styled mode): 20-color palette, vertical right-aligned legend with consistent spacing, larger title/axis-title margins, and line markers disabled by default.
+- Type compatibility: expose `HighchartsOptionsCompat` so newer fields (e.g. `plotOptions.pie.borderRadius`) type-check while staying assignable to upstream `Options` across Highcharts v10–v12.
+- CSS and usage guidance: import Salt base styles before the Highcharts theme, and wrap charts with `highcharts-theme-salt`; add `salt-fill-patterns` to opt into pattern fills.
+  Example: `import "@salt-ds/theme/index.css"; import "@salt-ds/highcharts-theme/index.css";`
+
+Includes a Donut chart example using `useDensity` + `useChart` to demonstrate density reactivity and optional pattern fills.

.storybook/preview.tsx

@@ -13,6 +13,8 @@ import "@fontsource/open-sans/800.css";
 import "@fontsource/pt-mono";
 import "@salt-ds/theme/css/theme-next.css";
 import "@salt-ds/theme/index.css";
+import "highcharts/css/highcharts.css";
+import "@salt-ds/highcharts-theme/index.css";
 import "./styles.css";
 
 import { SaltProvider, SaltProviderNext } from "@salt-ds/core";

packages/highcharts-theme/README.md

@@ -33,6 +33,7 @@ The Salt Highcharts theme overrides the default Highcharts CSS. To ensure the th
 > You can download the [Highcharts CSS
 > here](https://code.highcharts.com/10.2.0/css/highcharts.css), specifying the
 > required version via the URL.
+> For more information on loading Highcharts CSS, [visit the Highcharts docs](https://www.highcharts.com/docs/chart-design-and-style/style-by-css).
 
 ### Import Salt Highcharts theme
 
@@ -52,7 +53,7 @@ Then wrap your Highcharts with `highcharts-theme-salt` class name as shown below
 
 ### 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.
+Many Highchart stylistic properties can't 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";
@@ -68,9 +69,72 @@ For granular control, you can also use the `Highcharts.merge()` utility function
 
 To see which Options properties the Salt Highchart Theme package provides, see `src/highcharts-options-salt.ts`.
 
-### Patterns and Fills
+## Chart density
 
-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.
+Highcharts doesn't automatically respond to changes in CSS custom properties after the initial render. Use the `useChart` hook to trigger redraws when density changes and to retrieve density‑aware values for your chart options.
 
-Guidance on Fills TBA.
+The `useChart` hook takes a `chartRef` and reads the current Salt `density` internally.
+
+```jsx
+import { useRef, useMemo } from "react";
+import Highcharts from "highcharts";
+import HighchartsReact from "highcharts-react-official";
+import { useChart } from "@salt-ds/highcharts-theme";
+
+export const DensityAwareChart = () => {
+  const chartRef = useRef(null);
+
+  // Force a redraw and grab density-aware values (density is read internally)
+  const { legendIconSize } = useChart({ chartRef });
+
+  const options = useMemo(
+    () => ({
+      chart: { type: "pie" },
+      legend: {
+        symbolHeight: legendIconSize,
+        symbolWidth: legendIconSize,
+      },
+    }),
+    [legendIconSize],
+  );
+
+  return (
+    <div className="highcharts-theme-salt">
+      <HighchartsReact
+        ref={chartRef}
+        highcharts={Highcharts}
+        options={options}
+      />
+    </div>
+  );
+};
+```
+
+### Patterns and fills
+
+The Salt Highcharts theme provides patterns and fills to create visible contrast between series. This improves accessibility and readability, especially for users who rely on non‑color cues.
+
+#### Line patterns
+
+Apply line patterns to line‑type charts by adding `salt-line-patterns` to the chart container (alongside `highcharts-theme-salt`).
+
+```jsx
+<div className="highcharts-theme-salt salt-line-patterns">
+  <HighchartsReact highcharts={Highcharts} options={yourChartSpecificOptions} />
+</div>
+```
+
+#### Fill patterns
+
+Apply fill patterns (e.g., for donut/pie/bar) by adding `salt-fill-patterns` to the chart container.
+
+```jsx
+<div className="highcharts-theme-salt salt-fill-patterns">
+  <HighchartsReact highcharts={Highcharts} options={yourChartSpecificOptions} />
+</div>
+```
+
+Notes:
+
+- Make sure the chart is wrapped with `highcharts-theme-salt` so the Salt theme styles apply.
+- Patterns are purely CSS‑driven; Highcharts options don't need to be modified to enable them.

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

@@ -0,0 +1,80 @@
+/* Pattern fills for pie/donut charts */
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-0:not(.highcharts-data-label-connector) {
+  fill: url(#diagonal-up);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-1:not(.highcharts-data-label-connector) {
+  fill: url(#dot);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-2:not(.highcharts-data-label-connector) {
+  fill: url(#zigzag);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-3:not(.highcharts-data-label-connector) {
+  fill: url(#vertical-lines);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-4:not(.highcharts-data-label-connector) {
+  fill: url(#diagonal-down);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-5:not(.highcharts-data-label-connector) {
+  fill: url(#upward-point);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-6:not(.highcharts-data-label-connector) {
+  fill: url(#horizontal-lines);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-7:not(.highcharts-data-label-connector) {
+  fill: url(#crosshatch);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-8:not(.highcharts-data-label-connector) {
+  fill: url(#net);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-9:not(.highcharts-data-label-connector) {
+  fill: url(#steps);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-10:not(.highcharts-data-label-connector) {
+  fill: url(#pavement);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-11:not(.highcharts-data-label-connector) {
+  fill: url(#scallop);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-12:not(.highcharts-data-label-connector) {
+  fill: url(#vertical-wave);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-13:not(.highcharts-data-label-connector) {
+  fill: url(#metal);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-14:not(.highcharts-data-label-connector) {
+  fill: url(#scales);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-15:not(.highcharts-data-label-connector) {
+  fill: url(#triangle);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-16:not(.highcharts-data-label-connector) {
+  fill: url(#horizontal-wave);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-17:not(.highcharts-data-label-connector) {
+  fill: url(#cage);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-18:not(.highcharts-data-label-connector) {
+  fill: url(#line-dot);
+}
+
+.highcharts-theme-salt.salt-fill-patterns .highcharts-color-19:not(.highcharts-data-label-connector) {
+  fill: url(#squares);
+}

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

@@ -48,6 +48,60 @@
   stroke: var(--salt-category-10-subtle-borderColor);
 }
 
+.highcharts-theme-salt .highcharts-color-10 {
+  fill: var(--salt-category-11-bold-background);
+  stroke: var(--salt-category-11-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-11 {
+  fill: var(--salt-category-12-bold-background);
+  stroke: var(--salt-category-12-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-12 {
+  fill: var(--salt-category-13-bold-background);
+  stroke: var(--salt-category-13-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-13 {
+  fill: var(--salt-category-14-bold-background);
+  stroke: var(--salt-category-14-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-14 {
+  fill: var(--salt-category-15-bold-background);
+  stroke: var(--salt-category-15-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-15 {
+  fill: var(--salt-category-16-bold-background);
+  stroke: var(--salt-category-16-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-16 {
+  fill: var(--salt-category-17-bold-background);
+  stroke: var(--salt-category-17-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-17 {
+  fill: var(--salt-category-18-bold-background);
+  stroke: var(--salt-category-18-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-18 {
+  fill: var(--salt-category-19-bold-background);
+  stroke: var(--salt-category-19-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-color-19 {
+  fill: var(--salt-category-20-bold-background);
+  stroke: var(--salt-category-20-subtle-borderColor);
+}
+
+.highcharts-theme-salt .highcharts-container {
+  font-family: var(--salt-text-fontFamily);
+}
+
 .highcharts-theme-salt .highcharts-grid-line {
   stroke: var(--salt-separable-tertiary-borderColor);
 }
@@ -70,11 +124,21 @@
 
 /* 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;
 }
 
+/* Unset stroke for the path in a line series legend - specific to line chart and isolated as it adds incorrect stroke to pie chart legend */
+.highcharts-theme-salt .highcharts-line-series.highcharts-legend-item-hidden path {
+  stroke: revert !important;
+}
+
+/* Maintain full opacity on legend items during hover. Only reduce opacity when item is hidden */
+.highcharts-theme-salt .highcharts-legend-series-active .highcharts-legend-item:not(.highcharts-legend-item-hidden) *,
+.highcharts-theme-salt .highcharts-legend-point-active .highcharts-legend-item:not(.highcharts-legend-item-hidden) * {
+  opacity: 1;
+}
+
 .highcharts-theme-salt .highcharts-legend-item > text,
 .highcharts-theme-salt .highcharts-legend-item span {
   fill: var(--salt-content-secondary-foreground);
@@ -117,6 +181,11 @@
   fill: var(--salt-content-secondary-foreground-disabled);
 }
 
+.highcharts-theme-salt circle.highcharts-legend-nav-active,
+.highcharts-theme-salt circle.highcharts-legend-nav-inactive {
+  fill: transparent;
+}
+
 .highcharts-theme-salt text.highcharts-legend-navigation {
   fill: var(--salt-content-secondary-foreground);
   font-weight: var(--salt-text-label-fontWeight);
@@ -125,6 +194,27 @@
   font-family: var(--salt-text-label-fontFamily);
 }
 
+/* Override default stroke for line chart data series hover point circle */
 .highcharts-theme-salt .highcharts-point {
   stroke: var(--salt-color-white);
 }
+
+/* Override default stroke for pie chart segment border */
+.highcharts-theme-salt .highcharts-pie-series .highcharts-point {
+  stroke: var(--salt-container-primary-background);
+}
+
+/* Data connector line for Donut/Pie chart */
+.highcharts-theme-salt .highcharts-data-label-connector {
+  fill: none;
+}
+
+/* Removes extra hover style for Donut/Pie */
+.highcharts-theme-salt .highcharts-halo {
+  display: none;
+}
+
+/* Reduces opacity of deselected segments for Donut/Pie */
+.highcharts-theme-salt .highcharts-point-inactive {
+  opacity: 0.25;
+}

packages/highcharts-theme/index.css

@@ -1,3 +1,4 @@
 @import url(css/salt-highcharts-theme.css);
 @import url(css/salt-highcharts-v11.css);
 @import url(css/salt-line-patterns.css);
+@import url(css/salt-fill-patterns.css);

packages/highcharts-theme/package.json

@@ -26,7 +26,7 @@
   },
   "peerDependencies": {
     "@salt-ds/theme": "workspace:^",
-    "highcharts": "^10.2.0",
+    "highcharts": ">=10 <13",
     "highcharts-react-official": "^3.2.2"
   }
 }

packages/highcharts-theme/src/declarations.d.ts

@@ -0,0 +1,4 @@
+declare module "*.css" {
+  const content: string;
+  export default content;
+}