draft: standalone legend component

Author: jsilll

pages/07-standalone-legend/standalone-legend.page.tsx

@@ -0,0 +1,47 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { StandaloneLegend } from "../../lib/components/internal-do-not-use/standalone-legend";
+import { PageSettingsForm } from "../common/page-settings";
+import { Page } from "../common/templates";
+
+const series: Highcharts.SeriesOptionsType[] = [
+  {
+    name: "A",
+    type: "line",
+    data: [],
+  },
+  {
+    name: "B",
+    type: "line",
+    data: [],
+  },
+  {
+    name: "C",
+    type: "line",
+    data: [],
+  },
+  {
+    name: "X",
+    type: "scatter",
+    data: [{ x: 1601012700000, y: 500000 }],
+    marker: { symbol: "square" },
+    showInLegend: false,
+  },
+];
+
+export default function () {
+  return (
+    <Page
+      title="Core chart demo"
+      subtitle="The page demonstrates the use of the core chart, including additional legend settings."
+      settings={
+        <PageSettingsForm
+          selectedSettings={["showLegend", "legendPosition", "showLegendTitle", "showLegendActions", "useFallback"]}
+        />
+      }
+    >
+      <StandaloneLegend position="bottom" series={series} />
+    </Page>
+  );
+}

src/core/utils.ts

@@ -29,7 +29,7 @@ export function getPointId(point: Highcharts.Point): string {
 export function getOptionsId(options: { id?: string; name?: string }): string {
   return options.id ?? options.name ?? noIdPlaceholder();
 }
-function noIdPlaceholder(): string {
+export function noIdPlaceholder(): string {
   const rand = (Math.random() * 1_000_000).toFixed(0).padStart(6, "0");
   return "awsui-no-id-placeholder-" + rand;
 }

src/internal-do-not-use/standalone-legend/index.tsx

@@ -0,0 +1,188 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { useState } from "react";
+
+import { useInternalI18n } from "@cloudscape-design/components/internal/do-not-use/i18n";
+
+import { BaseI18nStrings, CoreChartProps } from "../../core/interfaces";
+import { LegendItemSpec, noIdPlaceholder } from "../../core/utils";
+import { ChartLegend as ChartLegendComponent } from "../../internal/components/chart-legend";
+import { ChartSeriesMarker, ChartSeriesMarkerType } from "../../internal/components/series-marker";
+import { fireNonCancelableEvent } from "../../internal/events";
+import { isEqualArrays } from "../../internal/utils/utils";
+
+function isLegendItemsEqual(a: CoreChartProps.LegendItem, b: CoreChartProps.LegendItem) {
+  return (
+    a.id === b.id &&
+    a.name === b.name &&
+    a.marker === b.marker &&
+    a.visible === b.visible &&
+    a.highlighted === b.highlighted
+  );
+}
+
+export function getOptionsId(options: { id?: string; name?: string }): string {
+  return options.id ?? options.name ?? noIdPlaceholder();
+}
+export function getPointColor(point?: Highcharts.PointOptionsObject): string {
+  return typeof point?.color === "string" ? point.color : "black";
+}
+
+const markersCache = new Map<string, React.ReactNode>();
+function renderMarker(type: ChartSeriesMarkerType, color: string, visible = true): React.ReactNode {
+  const key = `${type}:${color}:${visible}`;
+  const marker = markersCache.get(key) ?? <ChartSeriesMarker type={type} color={color} visible={visible} />;
+  markersCache.set(key, marker);
+  return marker;
+}
+
+export function getSeriesMarkerType(series?: Highcharts.SeriesOptionsType): ChartSeriesMarkerType {
+  if (!series) {
+    return "large-square";
+  }
+  const seriesSymbol = "symbol" in series && typeof series.symbol === "string" ? series.symbol : "circle";
+  if ("dashStyle" in series && series.dashStyle) {
+    return "dashed";
+  }
+  switch (series.type) {
+    case "area":
+    case "areaspline":
+      return "hollow-square";
+    case "line":
+    case "spline":
+      return "line";
+    case "scatter":
+      switch (seriesSymbol) {
+        case "square":
+          return "square";
+        case "diamond":
+          return "diamond";
+        case "triangle":
+          return "triangle";
+        case "triangle-down":
+          return "triangle-down";
+        case "circle":
+        default:
+          return "circle";
+      }
+    case "column":
+    case "pie":
+      return "large-square";
+    case "errorbar":
+    default:
+      return "large-square";
+  }
+}
+
+export function getChartLegendItems(series: Highcharts.SeriesOptionsType[]): readonly LegendItemSpec[] {
+  const legendItems: LegendItemSpec[] = [];
+  const addSeriesItem = (series: Highcharts.SeriesOptionsType) => {
+    // The pie series is not shown in the legend. Instead, we show pie segments.
+    if (series.type === "pie") {
+      return;
+    }
+    // We only support errorbar series that are linked to other series. Those are not represented separately
+    // in the legend, but can be controlled from the outside, using controllable items visibility API.
+    if (series.type === "errorbar") {
+      return;
+    }
+    // We respect Highcharts showInLegend option to allow hiding certain series from the legend.
+    // The same is not supported for pie chart segments.
+    // if (series.options.showInLegend !== false) {
+    //   legendItems.push({
+    //     id: getSeriesId(series),
+    //     name: series.name,
+    //     markerType: getSeriesMarkerType(series),
+    //     color: getSeriesColor(series),
+    //     visible: series.visible,
+    //   });
+    // }
+  };
+  for (const s of series) {
+    addSeriesItem(s);
+    if ("data" in s && Array.isArray(s.data) && s.type === "pie") {
+      s.data?.forEach((p, idx) => {
+        if (p instanceof Object && !Array.isArray(p)) {
+          legendItems.push({
+            id: getOptionsId(p),
+            name: p.name ?? `P${idx}`,
+            markerType: getSeriesMarkerType(s),
+            color: getPointColor(p),
+            visible: true,
+            // visible: p.visible, TODO: Is it safe to always set to true?
+          });
+        }
+      });
+    }
+  }
+  return legendItems;
+}
+
+export function StandaloneLegend({
+  title,
+  series,
+  actions,
+  position,
+  i18nStrings,
+  onItemHighlight,
+  onVisibleItemsChange,
+  getLegendTooltipContent,
+}: {
+  title?: string;
+  actions?: React.ReactNode;
+  position: "bottom" | "side";
+  i18nStrings?: BaseI18nStrings;
+  series: Highcharts.SeriesOptionsType[];
+  onItemHighlight?: CoreChartProps["onLegendItemHighlight"];
+  onVisibleItemsChange?: CoreChartProps["onVisibleItemsChange"];
+  getLegendTooltipContent?: CoreChartProps["getLegendTooltipContent"];
+}) {
+  const i18n = useInternalI18n("[charts]");
+  const ariaLabel = i18n("i18nStrings.legendAriaLabel", i18nStrings?.legendAriaLabel);
+
+  const [items, setItems] = useState<CoreChartProps.LegendItem[]>(() => {
+    const itemSpecs = getChartLegendItems(series);
+    const legendItems = itemSpecs.map(({ id, name, color, markerType, visible }) => {
+      const marker = renderMarker(markerType, color, visible);
+      return { id, name, marker, visible, highlighted: false };
+    });
+    return legendItems;
+  });
+  const updateItems = (items: CoreChartProps.LegendItem[]) => {
+    setItems((prevItems) => {
+      if (isEqualArrays(prevItems, items, isLegendItemsEqual)) {
+        return prevItems;
+      }
+      return items;
+    });
+  };
+
+  if (items.length === 0) {
+    return null;
+  }
+  return (
+    <ChartLegendComponent
+      items={items}
+      ariaLabel={ariaLabel}
+      actions={actions}
+      legendTitle={title}
+      position={position}
+      onItemHighlightEnter={(item) => {
+        const newItems = items.map((i) => ({ ...i, visible: item.id === i.id }));
+        updateItems(newItems);
+        fireNonCancelableEvent(onItemHighlight, { item });
+      }}
+      onItemHighlightExit={() => {
+        const newItems = items.map(({ ...item }) => ({ ...item, highlighted: false }));
+        updateItems(newItems);
+      }}
+      onItemVisibilityChange={(visibleItems) => {
+        const newItems = items.map((i) => ({ ...i, visible: visibleItems.includes(i.id) }));
+        updateItems(newItems);
+        fireNonCancelableEvent(onVisibleItemsChange, { items: newItems, isApiCall: false });
+      }}
+      getTooltipContent={(props) => getLegendTooltipContent?.(props) ?? null}
+    />
+  );
+}