feat: set the legend horizontal alignment

Author: Pixselve

pages/03-core/core-line-chart.page.tsx

@@ -91,7 +91,14 @@ export default function () {
       subtitle="The page demonstrates the use of the core chart, including additional legend settings."
       settings={
         <PageSettingsForm
-          selectedSettings={["showLegend", "legendPosition", "showLegendTitle", "showLegendActions", "useFallback"]}
+          selectedSettings={[
+            "showLegend",
+            "legendPosition",
+            "legendHorizontalAlign",
+            "showLegendTitle",
+            "showLegendActions",
+            "useFallback",
+          ]}
         />
       }
     >

pages/03-core/dual-axis-chart.page.tsx

@@ -0,0 +1,142 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import Highcharts from "highcharts";
+import { omit } from "lodash";
+
+import CoreChart from "../../lib/components/internal-do-not-use/core-chart";
+import { dateFormatter, numberFormatter } from "../common/formatters";
+import { PageSettingsForm, useChartSettings } from "../common/page-settings";
+import { Page } from "../common/templates";
+
+const baseline = [
+  { x: 1600984800000, y1: 58020, y2: 45 },
+  { x: 1600985700000, y1: 102402, y2: 52 },
+  { x: 1600986600000, y1: 104920, y2: 48 },
+  { x: 1600987500000, y1: 94031, y2: 55 },
+  { x: 1600988400000, y1: 125021, y2: 62 },
+  { x: 1600989300000, y1: 159219, y2: 58 },
+  { x: 1600990200000, y1: 193082, y2: 71 },
+  { x: 1600991100000, y1: 162592, y2: 65 },
+  { x: 1600992000000, y1: 274021, y2: 78 },
+  { x: 1600992900000, y1: 264286, y2: 82 },
+  { x: 1600993800000, y1: 289210, y2: 75 },
+  { x: 1600994700000, y1: 256362, y2: 68 },
+  { x: 1600995600000, y1: 257306, y2: 72 },
+  { x: 1600996500000, y1: 186776, y2: 58 },
+  { x: 1600997400000, y1: 294020, y2: 85 },
+  { x: 1600998300000, y1: 385975, y2: 92 },
+  { x: 1600999200000, y1: 486039, y2: 88 },
+  { x: 1601000100000, y1: 490447, y2: 95 },
+  { x: 1601001000000, y1: 361845, y2: 78 },
+  { x: 1601001900000, y1: 339058, y2: 72 },
+  { x: 1601002800000, y1: 298028, y2: 65 },
+  { x: 1601003400000, y1: 255555, y2: 58 },
+  { x: 1601003700000, y1: 231902, y2: 52 },
+  { x: 1601004600000, y1: 224558, y2: 48 },
+  { x: 1601005500000, y1: 253901, y2: 55 },
+  { x: 1601006400000, y1: 102839, y2: 42 },
+  { x: 1601007300000, y1: 234943, y2: 62 },
+  { x: 1601008200000, y1: 204405, y2: 58 },
+  { x: 1601009100000, y1: 190391, y2: 52 },
+  { x: 1601010000000, y1: 183570, y2: 48 },
+  { x: 1601010900000, y1: 162592, y2: 45 },
+  { x: 1601011800000, y1: 148910, y2: 38 },
+  { x: 1601012700000, y1: null, y2: null },
+  { x: 1601013600000, y1: 293910, y2: 72 },
+];
+
+const series: Highcharts.SeriesOptionsType[] = [
+  {
+    name: "Network Traffic",
+    type: "line",
+    data: baseline.map(({ x, y1 }) => ({ x, y: y1 })),
+    yAxis: "events",
+  },
+  {
+    name: "Request Count",
+    type: "line",
+    data: baseline.map(({ x, y1 }) => ({ x, y: y1 === null ? null : y1 * 0.8 })),
+    yAxis: "events",
+  },
+  {
+    name: "CPU Usage",
+    type: "line",
+    data: baseline.map(({ x, y2 }) => ({ x, y: y2 })),
+    yAxis: "percentage",
+  },
+  {
+    name: "Memory Usage",
+    type: "line",
+    data: baseline.map(({ x, y2 }) => ({ x, y: y2 === null ? null : y2 * 0.9 })),
+    yAxis: "percentage",
+  },
+];
+
+export default function () {
+  const { chartProps } = useChartSettings();
+  return (
+    <Page
+      title="Dual axis chart demo"
+      subtitle="Chart with multiple legends and two y-axes."
+      settings={
+        <PageSettingsForm
+          selectedSettings={[
+            "showLegend",
+            "legendPosition",
+            "legendHorizontalAlign",
+            "showLegendTitle",
+            "showLegendActions",
+            "useFallback",
+          ]}
+        />
+      }
+    >
+      <CoreChart
+        {...omit(chartProps.cartesian, "ref")}
+        highcharts={Highcharts}
+        options={{
+          lang: {
+            accessibility: {
+              chartContainerLabel: "Dual axis line chart",
+            },
+          },
+          series: series,
+          xAxis: [
+            {
+              type: "datetime",
+              title: { text: "Time (UTC)" },
+              valueFormatter: dateFormatter,
+            },
+          ],
+          yAxis: [
+            {
+              title: { text: "Events" },
+              id: "events",
+            },
+            {
+              title: { text: "Percentage (%)" },
+              opposite: true,
+              id: "percentage",
+            },
+          ],
+          chart: {
+            zooming: {
+              type: "x",
+            },
+          },
+        }}
+        chartHeight={400}
+        tooltip={{ placement: "outside" }}
+        getTooltipContent={() => ({
+          point({ item }) {
+            const value = item ? (item.point.y ?? null) : null;
+            return {
+              value: <div>{numberFormatter(value)}</div>,
+            };
+          },
+        })}
+      />
+    </Page>
+  );
+}

pages/03-core/pie.page.tsx

@@ -0,0 +1,68 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { omit } from "lodash";
+
+import CoreChart from "../../lib/components/internal-do-not-use/core-chart";
+import { PageSettingsForm, useChartSettings } from "../common/page-settings";
+import { Page } from "../common/templates";
+import pseudoRandom from "../utils/pseudo-random";
+
+function randomInt(min: number, max: number) {
+  return min + Math.floor(pseudoRandom() * (max - min));
+}
+
+const series: Highcharts.SeriesOptionsType[] = [
+  {
+    name: "Storage Distribution",
+    type: "pie",
+    data: [
+      { y: randomInt(30, 40), name: "Documents" },
+      { y: randomInt(20, 30), name: "Images" },
+      { y: randomInt(15, 25), name: "Videos" },
+      { y: randomInt(10, 15), name: "Other" },
+    ],
+  },
+];
+
+export default function () {
+  const { chartProps } = useChartSettings({ solidgauge: true });
+  return (
+    <Page
+      title="Core Pie Chart Demo"
+      subtitle="This page demonstrates the use of pie charts."
+      settings={
+        <PageSettingsForm
+          selectedSettings={[
+            "showLegend",
+            "legendPosition",
+            "legendHorizontalAlign",
+            "showLegendTitle",
+            "showLegendActions",
+            "useFallback",
+          ]}
+        />
+      }
+    >
+      <CoreChart
+        {...omit(chartProps.cartesian, "ref")}
+        options={{
+          series,
+          chart: {
+            type: "pie",
+          },
+          title: {
+            text: "Storage Distribution by Type",
+          },
+          yAxis: {
+            min: 0,
+            max: 100,
+            title: {
+              text: "Usage",
+            },
+          },
+        }}
+      />
+    </Page>
+  );
+}

pages/common/page-settings.tsx

@@ -15,6 +15,7 @@ import Select from "@cloudscape-design/components/select";
 import SpaceBetween from "@cloudscape-design/components/space-between";
 
 import { CartesianChartProps, PieChartProps } from "../../lib/components";
+import { CoreChartProps } from "../../src/core/interfaces";
 import AppContext, { AppContextType } from "../app/app-context";
 import { useHighcharts } from "./use-highcharts";
 
@@ -36,6 +37,7 @@ export interface PageSettings {
   showLegendActions: boolean;
   legendBottomMaxHeight?: number;
   legendPosition: "bottom" | "side";
+  legendHorizontalAlign: CoreChartProps.LegendOptionsHorizontalAlignment;
   showCustomHeader: boolean;
   showHeaderFilter: boolean;
   showCustomFooter: boolean;
@@ -60,6 +62,7 @@ const DEFAULT_SETTINGS: PageSettings = {
   showLegend: true,
   showLegendTitle: false,
   legendPosition: "bottom",
+  legendHorizontalAlign: "start",
   showLegendActions: false,
   showCustomHeader: false,
   showHeaderFilter: false,
@@ -149,7 +152,8 @@ export function useChartSettings<SettingsType extends PageSettings = PageSetting
     actions: settings.showLegendActions ? <Button variant="icon" iconName="search" /> : undefined,
     position: settings.legendPosition,
     bottomMaxHeight: settings.legendBottomMaxHeight,
-  };
+    horizontalAlignment: settings.legendHorizontalAlign,
+  } satisfies CoreChartProps.LegendOptions;
   return {
     settings,
     setSettings,
@@ -387,6 +391,32 @@ export function PageSettingsForm({
                   }
                 />
               );
+            case "legendHorizontalAlign":
+              return (
+                <SegmentedControl
+                  label="Legend Horizontal Align"
+                  selectedId={
+                    settings.showLegend && settings.legendPosition === "bottom" ? settings.legendHorizontalAlign : null
+                  }
+                  options={[
+                    {
+                      text: "Start",
+                      id: "start",
+                      disabled: !settings.showLegend || settings.legendPosition !== "bottom",
+                    },
+                    {
+                      text: "Center",
+                      id: "center",
+                      disabled: !settings.showLegend || settings.legendPosition !== "bottom",
+                    },
+                  ]}
+                  onChange={({ detail }) =>
+                    setSettings({
+                      legendHorizontalAlign: detail.selectedId as CoreChartProps.LegendOptionsHorizontalAlignment,
+                    })
+                  }
+                />
+              );
             case "showCustomHeader":
               return (
                 <Checkbox

src/__tests__/__snapshots__/documenter.test.ts.snap

@@ -1573,43 +1573,12 @@ Supported Highcharts versions: 12.",
         "i18nTag": undefined,
         "inlineType": {
           "name": "CoreChartProps.LegendOptions",
-          "properties": [
-            {
-              "name": "actions",
-              "optional": true,
-              "type": "React.ReactNode",
-            },
-            {
-              "name": "bottomMaxHeight",
-              "optional": true,
-              "type": "number",
-            },
-            {
-              "name": "enabled",
-              "optional": true,
-              "type": "boolean",
-            },
-            {
-              "inlineType": {
-                "name": ""side" | "bottom"",
-                "type": "union",
-                "valueDescriptions": undefined,
-                "values": [
-                  "side",
-                  "bottom",
-                ],
-              },
-              "name": "position",
-              "optional": true,
-              "type": "string",
-            },
-            {
-              "name": "title",
-              "optional": true,
-              "type": "string",
-            },
+          "type": "union",
+          "valueDescriptions": undefined,
+          "values": [
+            "BaseLegendOptions & { bottomMaxHeight?: number | undefined; } & CoreChartProps.LegendOptionsBottom",
+            "BaseLegendOptions & { bottomMaxHeight?: number | undefined; } & CoreChartProps.LegendOptionsSide",
           ],
-          "type": "object",
         },
         "name": "legend",
         "optional": true,

src/core/components/core-legend.tsx

@@ -17,11 +17,13 @@ export function ChartLegend({
   i18nStrings,
   onItemHighlight,
   getLegendTooltipContent,
+  horizontalAlignment,
 }: {
   api: ChartAPI;
   title?: string;
   actions?: React.ReactNode;
   position: "bottom" | "side";
+  horizontalAlignment?: CoreChartProps.LegendOptionsHorizontalAlignment;
   i18nStrings?: BaseI18nStrings;
   onItemHighlight?: NonCancelableEventHandler<CoreChartProps.LegendItemHighlightDetail>;
   getLegendTooltipContent?: CoreChartProps.GetLegendTooltipContent;
@@ -39,6 +41,7 @@ export function ChartLegend({
       ariaLabel={ariaLabel}
       legendTitle={title}
       items={legendItems}
+      horizontalAlignment={horizontalAlignment}
       actions={actions}
       position={position}
       onItemVisibilityChange={api.onItemVisibilityChange}

src/core/interfaces.ts

@@ -411,10 +411,24 @@ export namespace CoreChartProps {
     content: React.ReactNode;
   }
 
-  export interface LegendOptions extends BaseLegendOptions {
+  export type LegendOptions = BaseLegendOptions & {
     bottomMaxHeight?: number;
-    position?: "bottom" | "side";
+  } & (LegendOptionsBottom | LegendOptionsSide);
+
+  export interface LegendOptionsSide {
+    position?: "side";
+  }
+  export interface LegendOptionsBottom {
+    position: "bottom";
+    /**
+     * When {@link position} is set to "bottom", horizontalAlignment sets the legend horizontal alignment.
+     */
+    horizontalAlignment?: LegendOptionsHorizontalAlignment;
   }
+
+  export const LegendOptionsAlignments = ["start", "center"] as const;
+  export type LegendOptionsHorizontalAlignment = (typeof LegendOptionsAlignments)[number];
+
   export type LegendItem = InternalComponentTypes.LegendItem;
   export type LegendTooltipContent = InternalComponentTypes.LegendTooltipContent;
   export type GetLegendTooltipContent = InternalComponentTypes.GetLegendTooltipContent;