@neynar/ui 0.1.1

package/src/components/ui/chart.tsx

@@ -0,0 +1,802 @@
+import * as React from "react";
+import * as RechartsPrimitive from "recharts";
+
+import { cn } from "@/lib/utils";
+
+// Format: { THEME_NAME: CSS_SELECTOR }
+const THEMES = { light: "", dark: ".dark" } as const;
+
+/**
+ * Configuration object for chart data series
+ *
+ * Defines labels, colors, and icons for chart data series with support for
+ * both static colors and theme-aware color definitions. Each series can have
+ * either a static color or theme-specific colors for light/dark modes.
+ * This configuration drives both visual styling and accessibility features
+ * throughout the chart ecosystem.
+ *
+ * @example
+ * ```tsx
+ * // Static color configuration with icon
+ * const chartConfig = {
+ *   revenue: {
+ *     label: "Revenue",
+ *     color: "hsl(var(--chart-1))",
+ *     icon: DollarSignIcon,
+ *   },
+ * } satisfies ChartConfig
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Theme-aware color configuration for dark/light modes
+ * const chartConfig = {
+ *   users: {
+ *     label: "Active Users",
+ *     theme: {
+ *       light: "#0ea5e9",
+ *       dark: "#0284c7",
+ *     },
+ *   },
+ * } satisfies ChartConfig
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex configuration with multiple series
+ * const chartConfig = {
+ *   desktop: {
+ *     label: "Desktop Users",
+ *     color: "var(--chart-1)",
+ *     icon: MonitorIcon,
+ *   },
+ *   mobile: {
+ *     label: "Mobile Users",
+ *     color: "var(--chart-2)",
+ *     icon: SmartphoneIcon,
+ *   },
+ *   revenue: {
+ *     label: "Revenue ($)",
+ *     theme: {
+ *       light: "#059669",
+ *       dark: "#10b981",
+ *     },
+ *   },
+ * } satisfies ChartConfig
+ * ```
+ *
+ * @since 1.0.0
+ */
+export type ChartConfig = {
+  [k in string]: {
+    label?: React.ReactNode;
+    icon?: React.ComponentType;
+  } & (
+    | { color?: string; theme?: never }
+    | { color?: never; theme: Record<keyof typeof THEMES, string> }
+  );
+};
+
+type ChartContextProps = {
+  config: ChartConfig;
+};
+
+const ChartContext = React.createContext<ChartContextProps | null>(null);
+
+/**
+ * Hook to access chart configuration context
+ *
+ * Provides access to the chart configuration within chart components.
+ * Must be used within a ChartContainer component to access the chart config.
+ *
+ * @returns Chart configuration context containing config object
+ * @throws Error when used outside of ChartContainer
+ *
+ * @example
+ * ```tsx
+ * function CustomTooltip() {
+ *   const { config } = useChart()
+ *
+ *   return (
+ *     <div>
+ *       {Object.entries(config).map(([key, series]) => (
+ *         <div key={key} style={{ color: series.color }}>
+ *           {series.label}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function CustomChartComponent() {
+ *   const { config } = useChart()
+ *   const seriesConfig = config.revenue
+ *
+ *   return (
+ *     <div>
+ *       <seriesConfig.icon />
+ *       <span>{seriesConfig.label}</span>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+function useChart() {
+  const context = React.useContext(ChartContext);
+
+  if (!context) {
+    throw new Error("useChart must be used within a <ChartContainer />");
+  }
+
+  return context;
+}
+
+/**
+ * Container component for Recharts charts with theming and configuration
+ *
+ * The ChartContainer provides a responsive wrapper for Recharts components with
+ * automatic theming, color management, and configuration. It generates CSS custom
+ * properties for chart colors, handles dark mode support, and applies consistent
+ * styling across all chart types. Built on the shadcn/ui design system with
+ * Recharts as the underlying charting library.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic line chart with accessibility and tooltips
+ * const chartData = [
+ *   { month: "Jan", revenue: 2000, profit: 400 },
+ *   { month: "Feb", revenue: 2400, profit: 600 },
+ *   { month: "Mar", revenue: 3200, profit: 900 },
+ * ]
+ *
+ * const chartConfig = {
+ *   revenue: {
+ *     label: "Revenue",
+ *     color: "hsl(var(--chart-1))",
+ *   },
+ *   profit: {
+ *     label: "Profit",
+ *     color: "hsl(var(--chart-2))",
+ *   },
+ * } satisfies ChartConfig
+ *
+ * <ChartContainer config={chartConfig} className="min-h-[300px]">
+ *   <LineChart data={chartData} accessibilityLayer>
+ *     <CartesianGrid strokeDasharray="3 3" />
+ *     <XAxis dataKey="month" />
+ *     <YAxis />
+ *     <ChartTooltip content={<ChartTooltipContent />} />
+ *     <Line
+ *       type="monotone"
+ *       dataKey="revenue"
+ *       stroke="var(--color-revenue)"
+ *       strokeWidth={2}
+ *     />
+ *     <Line
+ *       type="monotone"
+ *       dataKey="profit"
+ *       stroke="var(--color-profit)"
+ *       strokeWidth={2}
+ *     />
+ *   </LineChart>
+ * </ChartContainer>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Bar chart with theme-aware colors and custom formatting
+ * <ChartContainer
+ *   config={{
+ *     sales: {
+ *       label: "Sales",
+ *       theme: {
+ *         light: "#0ea5e9",
+ *         dark: "#0284c7",
+ *       },
+ *     },
+ *   }}
+ *   className="h-[400px]"
+ * >
+ *   <BarChart data={data} accessibilityLayer>
+ *     <XAxis dataKey="month" />
+ *     <YAxis tickFormatter={(value) => `$${value.toLocaleString()}`} />
+ *     <ChartTooltip content={<ChartTooltipContent />} />
+ *     <Bar dataKey="sales" fill="var(--color-sales)" radius={4} />
+ *   </BarChart>
+ * </ChartContainer>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Pie chart with legend and icons for device breakdown
+ * <ChartContainer config={{
+ *   desktop: {
+ *     label: "Desktop",
+ *     color: "var(--chart-1)",
+ *     icon: MonitorIcon,
+ *   },
+ *   mobile: {
+ *     label: "Mobile",
+ *     color: "var(--chart-2)",
+ *     icon: SmartphoneIcon,
+ *   },
+ * }}>
+ *   <PieChart>
+ *     <Pie data={data} dataKey="value" nameKey="device" />
+ *     <ChartTooltip content={<ChartTooltipContent />} />
+ *     <ChartLegend content={<ChartLegendContent />} />
+ *   </PieChart>
+ * </ChartContainer>
+ * ```
+ *
+ * @accessibility
+ * **Core Accessibility Features:**
+ * - Responsive container adapts to screen size automatically
+ * - Theme-aware color system designed for WCAG contrast compliance
+ * - Supports Recharts' `accessibilityLayer` prop for keyboard navigation
+ * - High contrast colors available in both light and dark themes
+ * - Semantic HTML structure for screen reader compatibility
+ *
+ * **Important Accessibility Notes:**
+ * - Always include `accessibilityLayer` prop on Recharts components for keyboard access
+ * - Consider adding `aria-label` or `title` attributes for chart context
+ * - Ensure color is not the only way to distinguish data (use patterns, labels, or icons)
+ * - Test with screen readers as automatic data announcement may be limited
+ * - Provide alternative data representations (tables, text summaries) for complex charts
+ *
+ * **Keyboard Navigation:**
+ * - Arrow keys navigate between data points when `accessibilityLayer` is enabled
+ * - Tab key moves focus to interactive chart elements
+ * - Screen reader users should be provided with data summaries or alternative formats
+ *
+ * @performance
+ * - Use appropriate chart types for data size (avoid complex charts with large datasets)
+ * - Consider virtualization for charts with many data points
+ * - CSS variables are generated only for configured colors to minimize style overhead
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/chart} shadcn/ui Chart documentation
+ * @see {@link https://recharts.org/en-US/api} Recharts API documentation
+ * @see {@link ChartTooltip} Tooltip component for interactive data display
+ * @see {@link ChartLegend} Legend component for series identification
+ * @see {@link useChart} Hook to access chart configuration
+ * @since 1.0.0
+ */
+function ChartContainer({
+  id,
+  className,
+  children,
+  config,
+  ...props
+}: React.ComponentProps<"div"> & {
+  /**
+   * Chart configuration defining series labels and colors
+   */
+  config: ChartConfig;
+  /**
+   * Recharts component(s) to render
+   */
+  children: React.ComponentProps<
+    typeof RechartsPrimitive.ResponsiveContainer
+  >["children"];
+}) {
+  const uniqueId = React.useId();
+  const chartId = `chart-${id || uniqueId.replace(/:/g, "")}`;
+
+  return (
+    <ChartContext.Provider value={{ config }}>
+      <div
+        data-slot="chart"
+        data-chart={chartId}
+        className={cn(
+          "[&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground [&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-border/50 [&_.recharts-curve.recharts-tooltip-cursor]:stroke-border [&_.recharts-polar-grid_[stroke='#ccc']]:stroke-border [&_.recharts-radial-bar-background-sector]:fill-muted [&_.recharts-rectangle.recharts-tooltip-cursor]:fill-muted [&_.recharts-reference-line_[stroke='#ccc']]:stroke-border flex aspect-video justify-center text-xs [&_.recharts-dot[stroke='#fff']]:stroke-transparent [&_.recharts-layer]:outline-hidden [&_.recharts-sector]:outline-hidden [&_.recharts-sector[stroke='#fff']]:stroke-transparent [&_.recharts-surface]:outline-hidden",
+          className,
+        )}
+        {...props}
+      >
+        <ChartStyle id={chartId} config={config} />
+        <RechartsPrimitive.ResponsiveContainer>
+          {children}
+        </RechartsPrimitive.ResponsiveContainer>
+      </div>
+    </ChartContext.Provider>
+  );
+}
+
+/**
+ * Internal component that generates CSS custom properties for chart colors
+ *
+ * Creates CSS variables based on the chart configuration to enable theme-aware
+ * coloring. Generates variables for both light and dark themes when theme
+ * configurations are provided, or uses static colors when available.
+ *
+ * @component
+ * @internal
+ * @param id - Unique identifier for the chart instance
+ * @param config - Chart configuration with color definitions
+ * @since 1.0.0
+ */
+function ChartStyle({ id, config }: { id: string; config: ChartConfig }) {
+  const colorConfig = Object.entries(config).filter(
+    ([, config]) => config.theme || config.color,
+  );
+
+  if (!colorConfig.length) {
+    return null;
+  }
+
+  return (
+    <style
+      dangerouslySetInnerHTML={{
+        __html: Object.entries(THEMES)
+          .map(
+            ([theme, prefix]) => `
+${prefix} [data-chart=${id}] {
+${colorConfig
+  .map(([key, itemConfig]) => {
+    const color =
+      itemConfig.theme?.[theme as keyof typeof itemConfig.theme] ||
+      itemConfig.color;
+    return color ? `  --color-${key}: ${color};` : null;
+  })
+  .join("\n")}
+}
+`,
+          )
+          .join("\n"),
+      }}
+    />
+  );
+}
+
+/**
+ * Tooltip component for charts
+ *
+ * Re-export of Recharts Tooltip component with support for custom content.
+ * Use with ChartTooltipContent for consistent styling and theming integration.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic tooltip
+ * <ChartTooltip content={<ChartTooltipContent />} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tooltip with custom positioning
+ * <ChartTooltip
+ *   content={<ChartTooltipContent />}
+ *   cursor={false}
+ *   position={{ x: 10, y: 10 }}
+ * />
+ * ```
+ *
+ * @see {@link ChartTooltipContent} Custom tooltip content component
+ * @since 1.0.0
+ */
+const ChartTooltip = RechartsPrimitive.Tooltip;
+
+/**
+ * Custom tooltip content component for charts
+ *
+ * Provides a styled tooltip that displays chart data with proper formatting,
+ * colors, and labels from the chart configuration. Supports multiple indicator
+ * styles, custom formatters, and automatic theming integration.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic tooltip with default styling
+ * <ChartTooltip content={<ChartTooltipContent />} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tooltip with custom value formatter
+ * <ChartTooltip
+ *   content={
+ *     <ChartTooltipContent
+ *       formatter={(value, name) => [
+ *         `$${value.toLocaleString()}`,
+ *         name.toUpperCase()
+ *       ]}
+ *     />
+ *   }
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tooltip with line indicator and custom label
+ * <ChartTooltip
+ *   content={
+ *     <ChartTooltipContent
+ *       indicator="line"
+ *       labelFormatter={(label) => `Week of ${label}`}
+ *       hideLabel={false}
+ *     />
+ *   }
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tooltip with dashed indicator and no icons
+ * <ChartTooltip
+ *   content={
+ *     <ChartTooltipContent
+ *       indicator="dashed"
+ *       hideIndicator={false}
+ *       nameKey="category"
+ *     />
+ *   }
+ * />
+ * ```
+ *
+ * @accessibility
+ * - High contrast colors for visibility in both themes
+ * - Proper semantic markup for screen readers
+ * - Formatted numbers with locale-aware display
+ * - Clear visual indicators for data series
+ *
+ * @since 1.0.0
+ */
+function ChartTooltipContent({
+  active,
+  payload,
+  className,
+  indicator = "dot",
+  hideLabel = false,
+  hideIndicator = false,
+  label,
+  labelFormatter,
+  labelClassName,
+  formatter,
+  color,
+  nameKey,
+  labelKey,
+}: React.ComponentProps<typeof RechartsPrimitive.Tooltip> &
+  React.ComponentProps<"div"> & {
+    /**
+     * Whether to hide the label
+     * @default false
+     */
+    hideLabel?: boolean;
+    /**
+     * Whether to hide the color indicator
+     * @default false
+     */
+    hideIndicator?: boolean;
+    /**
+     * Style of the color indicator
+     * @default "dot"
+     */
+    indicator?: "line" | "dot" | "dashed";
+    /**
+     * Key to use for the name in payload
+     */
+    nameKey?: string;
+    /**
+     * Key to use for the label in payload
+     */
+    labelKey?: string;
+  }) {
+  const { config } = useChart();
+
+  const getTooltipLabel = () => {
+    if (hideLabel || !payload?.length) {
+      return null;
+    }
+
+    const [item] = payload;
+    const key = `${labelKey || item?.dataKey || item?.name || "value"}`;
+    const itemConfig = getPayloadConfigFromPayload(config, item, key);
+    const value =
+      !labelKey && typeof label === "string"
+        ? config[label as keyof typeof config]?.label || label
+        : itemConfig?.label;
+
+    if (labelFormatter) {
+      return (
+        <div className={cn("font-medium", labelClassName)}>
+          {labelFormatter(value, payload)}
+        </div>
+      );
+    }
+
+    if (!value) {
+      return null;
+    }
+
+    return <div className={cn("font-medium", labelClassName)}>{value}</div>;
+  };
+
+  const tooltipLabel = getTooltipLabel();
+
+  if (!active || !payload?.length) {
+    return null;
+  }
+
+  const nestLabel = payload.length === 1 && indicator !== "dot";
+
+  return (
+    <div
+      className={cn(
+        "border-border/50 bg-background grid min-w-[8rem] items-start gap-1.5 rounded-lg border px-2.5 py-1.5 text-xs shadow-xl",
+        className,
+      )}
+    >
+      {!nestLabel ? tooltipLabel : null}
+      <div className="grid gap-1.5">
+        {payload.map((item, index) => {
+          const key = `${nameKey || item.name || item.dataKey || "value"}`;
+          const itemConfig = getPayloadConfigFromPayload(config, item, key);
+          const indicatorColor = color || item.payload.fill || item.color;
+
+          return (
+            <div
+              key={item.dataKey}
+              className={cn(
+                "[&>svg]:text-muted-foreground flex w-full flex-wrap items-stretch gap-2 [&>svg]:h-2.5 [&>svg]:w-2.5",
+                indicator === "dot" && "items-center",
+              )}
+            >
+              {formatter && item?.value !== undefined && item.name ? (
+                formatter(item.value, item.name, item, index, item.payload)
+              ) : (
+                <>
+                  {itemConfig?.icon ? (
+                    <itemConfig.icon />
+                  ) : (
+                    !hideIndicator && (
+                      <div
+                        className={cn(
+                          "shrink-0 rounded-[2px] border-(--color-border) bg-(--color-bg)",
+                          {
+                            "h-2.5 w-2.5": indicator === "dot",
+                            "w-1": indicator === "line",
+                            "w-0 border-[1.5px] border-dashed bg-transparent":
+                              indicator === "dashed",
+                            "my-0.5": nestLabel && indicator === "dashed",
+                          },
+                        )}
+                        style={
+                          {
+                            "--color-bg": indicatorColor,
+                            "--color-border": indicatorColor,
+                          } as React.CSSProperties
+                        }
+                      />
+                    )
+                  )}
+                  <div
+                    className={cn(
+                      "flex flex-1 justify-between leading-none",
+                      nestLabel ? "items-end" : "items-center",
+                    )}
+                  >
+                    <div className="grid gap-1.5">
+                      {nestLabel ? tooltipLabel : null}
+                      <span className="text-muted-foreground">
+                        {itemConfig?.label || item.name}
+                      </span>
+                    </div>
+                    {item.value && (
+                      <span className="text-foreground font-mono font-medium tabular-nums">
+                        {item.value.toLocaleString()}
+                      </span>
+                    )}
+                  </div>
+                </>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Legend component for charts
+ *
+ * Re-export of Recharts Legend component with support for custom content.
+ * Use with ChartLegendContent for consistent styling and theming integration.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic legend
+ * <ChartLegend content={<ChartLegendContent />} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Legend positioned at top
+ * <ChartLegend
+ *   content={<ChartLegendContent />}
+ *   verticalAlign="top"
+ *   height={36}
+ * />
+ * ```
+ *
+ * @see {@link ChartLegendContent} Custom legend content component
+ * @since 1.0.0
+ */
+const ChartLegend = RechartsPrimitive.Legend;
+
+/**
+ * Custom legend content component for charts
+ *
+ * Provides a styled legend that displays chart series with colors and labels
+ * from the chart configuration. Supports icon display, custom positioning,
+ * and automatic theming integration.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic legend with default settings
+ * <ChartLegend content={<ChartLegendContent />} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Legend positioned at top without icons
+ * <ChartLegend
+ *   content={
+ *     <ChartLegendContent
+ *       verticalAlign="top"
+ *       hideIcon={true}
+ *     />
+ *   }
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Legend with custom name key
+ * <ChartLegend
+ *   content={
+ *     <ChartLegendContent
+ *       nameKey="category"
+ *       className="justify-start"
+ *     />
+ *   }
+ * />
+ * ```
+ *
+ * @accessibility
+ * - Semantic markup for screen readers
+ * - Color indicators with clear labels
+ * - Proper contrast ratios for visibility
+ * - Logical tab order for keyboard navigation
+ *
+ * @since 1.0.0
+ */
+function ChartLegendContent({
+  className,
+  hideIcon = false,
+  payload,
+  verticalAlign = "bottom",
+  nameKey,
+}: React.ComponentProps<"div"> &
+  Pick<RechartsPrimitive.LegendProps, "payload" | "verticalAlign"> & {
+    /**
+     * Whether to hide series icons
+     * @default false
+     */
+    hideIcon?: boolean;
+    /**
+     * Key to use for the name in payload
+     */
+    nameKey?: string;
+  }) {
+  const { config } = useChart();
+
+  if (!payload?.length) {
+    return null;
+  }
+
+  return (
+    <div
+      className={cn(
+        "flex items-center justify-center gap-4",
+        verticalAlign === "top" ? "pb-3" : "pt-3",
+        className,
+      )}
+    >
+      {payload.map((item) => {
+        const key = `${nameKey || item.dataKey || "value"}`;
+        const itemConfig = getPayloadConfigFromPayload(config, item, key);
+
+        return (
+          <div
+            key={item.value}
+            className={cn(
+              "[&>svg]:text-muted-foreground flex items-center gap-1.5 [&>svg]:h-3 [&>svg]:w-3",
+            )}
+          >
+            {itemConfig?.icon && !hideIcon ? (
+              <itemConfig.icon />
+            ) : (
+              <div
+                className="h-2 w-2 shrink-0 rounded-[2px]"
+                style={{
+                  backgroundColor: item.color,
+                }}
+              />
+            )}
+            {itemConfig?.label}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * Internal helper to extract chart configuration from payload data
+ *
+ * Retrieves the appropriate configuration for a data series from the chart
+ * config based on the payload data structure. Handles nested payload objects
+ * and fallback key resolution.
+ *
+ * @internal
+ * @param config - The chart configuration object
+ * @param payload - The data payload from Recharts
+ * @param key - The key to look up in the configuration
+ * @returns The configuration for the data series, or undefined if not found
+ * @since 1.0.0
+ */
+function getPayloadConfigFromPayload(
+  config: ChartConfig,
+  payload: unknown,
+  key: string,
+) {
+  if (typeof payload !== "object" || payload === null) {
+    return undefined;
+  }
+
+  const payloadPayload =
+    "payload" in payload &&
+    typeof payload.payload === "object" &&
+    payload.payload !== null
+      ? payload.payload
+      : undefined;
+
+  let configLabelKey: string = key;
+
+  if (
+    key in payload &&
+    typeof payload[key as keyof typeof payload] === "string"
+  ) {
+    configLabelKey = payload[key as keyof typeof payload] as string;
+  } else if (
+    payloadPayload &&
+    key in payloadPayload &&
+    typeof payloadPayload[key as keyof typeof payloadPayload] === "string"
+  ) {
+    configLabelKey = payloadPayload[
+      key as keyof typeof payloadPayload
+    ] as string;
+  }
+
+  return configLabelKey in config
+    ? config[configLabelKey]
+    : config[key as keyof typeof config];
+}
+
+export {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
+  ChartStyle,
+};