Bar Chart documentation

lib/src/bar-chart/types.ts

@@ -1,6 +1,6 @@
 type DataTypes = string | number;
 
-type BarChartThresholdSeries<X> = {
+type ThresholdSeries<X> = {
   /**
    * Title of the series.
    */
@@ -19,7 +19,7 @@ type BarChartThresholdSeries<X> = {
   x?: X;
 };
 
-type BarChartDataSeries<X> = {
+type BarDataSeries<X> = {
   /**
    * Title of the series.
    */
@@ -34,7 +34,7 @@ type BarChartDataSeries<X> = {
   data: { x: X; y: number }[];
 };
 
-type BarChartSeries<X> = BarChartThresholdSeries<X> | BarChartDataSeries<X>;
+type BarChartSeries<X> = ThresholdSeries<X> | BarDataSeries<X>;
 
 type BarChartProps<X extends DataTypes> = {
   /**
@@ -46,63 +46,82 @@ type BarChartProps<X extends DataTypes> = {
    */
   error?: string;
   /**
-   * If true, the chart will display horizontal bars.
+   * When set to true, the x and y axes are swapped, resulting in bars
+   * being displayed horizontally rather than vertically. This feature is
+   * applicable only when the chart contains exclusively bar series.
    */
   horizontalBars?: boolean;
   /**
-   * Legend title.
+   * Title of the chart legend.
    */
   legendTitle?: string;
   /**
-   * Activates the loading state.
+   * If true, activates the loading state of the component.
    */
   loading?: boolean;
   /**
-   * Event called when the bar chart filters are changed.
+   * This function will be called when the user changes the displayed
+   * data series with the default filter. This event is only triggered
+   * when 'showFilter' is set to 'true'.
    */
   onFilterChange?: (visibleSeries: string[]) => void;
   /**
-   * Event called when the highlighted series has changed because of user interaction.
+   * This function will be called when the user hovers over a data series
+   * through the chart legend. This event is only triggered when
+   * 'showLegend' is set to 'true'.
    */
   onHighlightChange?: (highlightedSeries?: string) => void;
   /**
-   * Event called when the user clicks on the retry action of the error state.
+   * This function will be called when the user clicks the retry action
+   * in the error state. A 'DxcButton' component will be
+   * displayed if this prop is defined to perform the action.
    */
   onRetry?: () => void;
   /**
-   * Array that represents the source of data for the displayed chart.
+   * An array of objects representing the data series to be displayed in
+   * the chart.
    */
   series: BarChartSeries<X>[];
   /**
-   * If true, the chart will display a filter to show/hide series.
+   * If true, the chart will display a filter to allow the user to change
+   * the displayed data series.
    */
   showFilter?: boolean;
   /**
-   * If true, the chart will display a legend with the corresponding data series.
+   * If true, the chart will display a legend with the data series
+   * information.
    */
   showLegend?: boolean;
   /**
-   * When set to true, bars in the same data point are stacked instead of being grouped next to each other.
+   * If true, bars in the same data point are stacked instead of being
+   * grouped next to each other.
    */
   stackedBars?: boolean;
   /**
-   * Determines the domain of the x axis, i.e. the range of values that will be visible in the chart
+   * Specifies the x-axis domain, defining the visible range. For
+   * numerical data, use a tuple: [minValue, maxValue]. For categorical
+   * data, use an array of category strings. Explicitly setting this is
+   * recommended. If not set, the component will auto-fit all data
+   * points.
    */
   xDomain?: X[];
   /**
-   * Formatter function for the x axis. It receives the x value and returns a string.
+   * Function to format the displayed label of an x-axis mark.
    */
   xFormatter?: (value: X) => string;
   /**
    * Title of the x axis.
    */
   xTitle?: string;
   /**
-   * Determines the domain of the y axis, i.e. the range of values that will be visible in the chart
+   * Specifies the y-axis domain, defining the visible range. The domain
+   * is defined by a tuple: [minValue, maxValue]. Explicitly setting this
+   * is recommended. If not set, the component will auto-fit all data
+   * points.
    */
   yDomain?: [number, number];
   /**
-   * Formatter function for the y axis. It receives the y value and returns a string.
+   * Function to format the displayed label of an y-axis mark.
    */
   yFormatter?: (value: number) => string;
   /**

website/pages/components/bar-chart/index.tsx

@@ -0,0 +1,21 @@
+import Head from "next/head";
+import type { ReactElement } from "react";
+import BarChartPageLayout from "../../../screens/components/bar-chart/BarChartPageLayout";
+import BarChartCodePage from "../../../screens/components/bar-chart/code/BarChartCodePage";
+
+const Index = () => {
+  return (
+    <>
+      <Head>
+        <title>Bar Chart — Halstack Design System</title>
+      </Head>
+      <BarChartCodePage></BarChartCodePage>
+    </>
+  );
+};
+
+Index.getLayout = function getLayout(page: ReactElement) {
+  return <BarChartPageLayout>{page}</BarChartPageLayout>;
+};
+
+export default Index;

website/pages/components/bar-chart/specifications.tsx

@@ -0,0 +1,21 @@
+import Head from "next/head";
+import type { ReactElement } from "react";
+import BarChartPageLayout from "../../../screens/components/bar-chart/BarChartPageLayout";
+import BarChartSpecsPage from "../../../screens/components/bar-chart/specs/BarChartSpecsPage";
+
+const Specifications = () => {
+  return (
+    <>
+      <Head>
+        <title>Bar Chart Specs — Halstack Design System</title>
+      </Head>
+      <BarChartSpecsPage></BarChartSpecsPage>
+    </>
+  );
+};
+
+Specifications.getLayout = function getLayout(page: ReactElement) {
+  return <BarChartPageLayout>{page}</BarChartPageLayout>;
+};
+
+export default Specifications;

website/pages/components/bar-chart/usage.tsx

@@ -0,0 +1,21 @@
+import Head from "next/head";
+import type { ReactElement } from "react";
+import BarChartPageLayout from "../../../screens/components/bar-chart/BarChartPageLayout";
+import BarChartUsagePage from "../../../screens/components/bar-chart/usage/BarChartUsagePage";
+
+const Usage = () => {
+  return (
+    <>
+      <Head>
+        <title>Bar Chart Usage — Halstack Design System</title>
+      </Head>
+      <BarChartUsagePage></BarChartUsagePage>
+    </>
+  );
+};
+
+Usage.getLayout = function getLayout(page: ReactElement) {
+  return <BarChartPageLayout>{page}</BarChartPageLayout>;
+};
+
+export default Usage;

website/screens/common/componentsList.json

@@ -11,6 +11,11 @@
     "path": "/components/badge",
     "status": "new"
   },
+  {
+    "label": "Bar Chart",
+    "path": "/components/bar-chart",
+    "status": "experimental"
+  },
   { "label": "Bleed", "path": "/components/bleed", "status": "stable" },
   { "label": "Box", "path": "/components/box", "status": "deprecated" },
   {

website/screens/components/badge/code/BadgeCodePage.tsx

@@ -137,7 +137,7 @@ const BadgeTableCodePage = () => {
           startHeadingLevel={2}
         ></QuickNavContainer>
       </QuickNavContainerLayout>
-      <DocFooter githubLink="https://github.com/dxc-technology/halstack-react/blob/master/website/screens/components/badge/TableCode/BadgeTableCodePage.tsx" />
+      <DocFooter githubLink="https://github.com/dxc-technology/halstack-react/blob/master/website/screens/components/badge/code/BadgeCodePage.tsx" />
     </DxcFlex>
   );
 };

website/screens/components/bar-chart/BarChartPageLayout.tsx

@@ -0,0 +1,33 @@
+import { DxcFlex, DxcParagraph } from "@dxc-technology/halstack-react";
+import PageHeading from "@/common/PageHeading";
+import TabsPageHeading from "@/common/TabsPageLayout";
+import ComponentHeading from "@/common/ComponentHeading";
+
+const BarChartPageHeading = ({ children }: { children: React.ReactNode }) => {
+  const tabs = [
+    { label: "Code", path: "/components/bar-chart" },
+    { label: "Usage", path: "/components/bar-chart/usage" },
+    { label: "Specifications", path: "/components/bar-chart/specifications" },
+  ];
+
+  return (
+    <DxcFlex direction="column" gap="3rem">
+      <PageHeading>
+        <DxcFlex direction="column" gap="2rem">
+          <ComponentHeading name="Bar Chart" />
+          <DxcParagraph>
+            A bar chart is a graphical representation that displays and compares
+            discrete data categories using rectangular bars. Each bar's length
+            or height is proportional to the frequency or value of its
+            corresponding category, allowing users to identify which groups are
+            the highest or most common and compare them with others.
+          </DxcParagraph>
+          <TabsPageHeading tabs={tabs}></TabsPageHeading>
+        </DxcFlex>
+      </PageHeading>
+      {children}
+    </DxcFlex>
+  );
+};
+
+export default BarChartPageHeading;