@hexclave/dashboard-ui-components 1.0.2 → 1.0.5

package/src/components/card.tsx

@@ -0,0 +1,263 @@
+"use client";
+
+import { Card } from "@hexclave/ui";
+import { cn } from "@hexclave/ui";
+import React from "react";
+
+// ─── Card nesting context ────────────────────────────────────────────────────
+// Components with a `glassmorphic` prop use this to auto-detect whether they
+// sit inside a DesignCard.  When they do, glassmorphic defaults to `true`;
+// when they don't, it defaults to `false`.
+
+const DesignCardNestingContext = React.createContext(false);
+
+/**
+ * Returns `true` when the calling component is rendered inside a DesignCard.
+ * Useful for deriving a glassmorphic default.
+ */
+export function useInsideDesignCard(): boolean {
+  return React.useContext(DesignCardNestingContext);
+}
+
+/**
+ * Resolve the effective glassmorphic value.
+ * - If the caller passed an explicit boolean → honour it.
+ * - Otherwise → fall back to whether we're inside a DesignCard.
+ */
+export function useGlassmorphicDefault(explicit: boolean | undefined): boolean {
+  const insideCard = useInsideDesignCard();
+  return explicit ?? insideCard;
+}
+
+type DesignCardGradient = "blue" | "cyan" | "purple" | "green" | "orange" | "default";
+
+const hoverTintClasses = new Map<DesignCardGradient, string>([
+  ["blue", "group-hover:bg-blue-500/[0.03]"],
+  ["purple", "group-hover:bg-purple-500/[0.03]"],
+  ["green", "group-hover:bg-emerald-500/[0.03]"],
+  ["orange", "group-hover:bg-orange-500/[0.03]"],
+  ["default", "group-hover:bg-slate-500/[0.02]"],
+  ["cyan", "group-hover:bg-cyan-500/[0.03]"],
+]);
+
+const demoTintClasses = new Map<DesignCardGradient, string>([
+  ["blue", "group-hover/tint:bg-blue-500/[0.02]"],
+  ["purple", "group-hover/tint:bg-purple-500/[0.02]"],
+  ["green", "group-hover/tint:bg-emerald-500/[0.02]"],
+  ["orange", "group-hover/tint:bg-orange-500/[0.02]"],
+  ["default", "group-hover/tint:bg-slate-500/[0.015]"],
+  ["cyan", "group-hover/tint:bg-cyan-500/[0.02]"],
+]);
+
+const bodyPaddingClass = "p-5";
+
+// ─── Discriminated props ──────────────────────────────────────────────────
+// - If title is given, icon is required.
+// - The layout is derived automatically:
+//     title + subtitle → "header"   (full header block with subtitle)
+//     title only       → "compact"  (slim bar with border-b)
+//     no title         → "bodyOnly" (just the body)
+
+type DesignCardBaseProps = {
+  glassmorphic?: boolean,
+  gradient?: DesignCardGradient,
+  contentClassName?: string,
+} & Omit<React.ComponentProps<typeof Card>, "title">;
+
+type WithTitleProps = {
+  title: React.ReactNode,
+  subtitle?: React.ReactNode,
+  icon: React.ElementType,
+  actions?: React.ReactNode,
+};
+
+type WithoutTitleProps = {
+  title?: never,
+  subtitle?: never,
+  icon?: never,
+  actions?: never,
+};
+
+export type DesignCardProps = DesignCardBaseProps & (WithTitleProps | WithoutTitleProps);
+
+/**
+ * General-purpose card for grouping related content: section headers,
+ * description blocks, chart-less panels, etc. If the content is a
+ * big-number metric, use `DesignMetricCard` instead. If it contains a
+ * chart, wrap it in `DesignChartCard`.
+ *
+ * Two shapes, picked automatically by the props you pass:
+ *
+ * ```tsx
+ * // With a header (title requires icon):
+ * <DesignCard title="Recent activity" icon={ActivityIcon}>
+ *   ...body...
+ * </DesignCard>
+ *
+ * // Body-only (no header):
+ * <DesignCard>
+ *   <h2 className="text-2xl font-semibold">Dashboard</h2>
+ *   <p className="text-muted-foreground">Overview of your user base</p>
+ * </DesignCard>
+ * ```
+ *
+ * Rules:
+ * - DO NOT add padding classes (`p-6`, `p-5`, etc.) to `className` — the
+ *   component already has built-in padding and extra padding will look wrong.
+ * - If you set `title`, you MUST also set `icon`. The TS types enforce this,
+ *   but writing `title` without `icon` will fail.
+ * - Body-only cards (no `title`) automatically go transparent in dark mode.
+ */
+export function DesignCard({
+  title,
+  subtitle,
+  icon: Icon,
+  actions,
+  glassmorphic: glassmorphicProp,
+  gradient = "default",
+  children,
+  className,
+  contentClassName,
+  ...props
+}: DesignCardProps) {
+  const glassmorphic = glassmorphicProp ?? true;
+  const hoverTintClass = hoverTintClasses.get(gradient) ?? "group-hover:bg-slate-500/[0.02]";
+  const hasContent = React.Children.count(children) > 0;
+
+  // Derive layout from which props were provided
+  const variant = title != null
+    ? (subtitle != null ? "header" : "compact")
+    : "bodyOnly";
+
+  return (
+    <DesignCardNestingContext.Provider value={true}>
+      <Card
+        className={cn(
+          "group relative rounded-2xl overflow-hidden",
+          glassmorphic && [
+            "bg-white/90 dark:bg-background/60 dark:backdrop-blur-xl border-0 transition-all duration-150 hover:transition-none",
+            "ring-1 ring-black/[0.06] hover:ring-black/[0.1] dark:ring-white/[0.06] dark:hover:ring-white/[0.1]",
+            "shadow-none",
+          ],
+          glassmorphic && variant === "bodyOnly" && "dark:bg-transparent dark:ring-0 dark:shadow-none",
+          className
+        )}
+        {...props}
+      >
+        {glassmorphic && (
+          <>
+            <div className={cn(
+              "absolute inset-0 bg-gradient-to-br from-foreground/[0.04] dark:from-foreground/[0.02] to-transparent pointer-events-none rounded-2xl",
+              variant === "bodyOnly" && "dark:hidden"
+            )} />
+            {variant !== "bodyOnly" && (
+              <div
+                className={cn(
+                  "absolute inset-0 transition-colors duration-150 group-hover:transition-none pointer-events-none rounded-2xl",
+                  hoverTintClass
+                )}
+              />
+            )}
+          </>
+        )}
+        <div className="relative">
+          {variant === "header" && (
+            <div className={bodyPaddingClass}>
+              <div className="flex items-start justify-between gap-4">
+                <div className="flex-1 min-w-0">
+                  <div className="flex items-center gap-2">
+                    {Icon && (
+                      <div className="p-1.5 rounded-lg bg-foreground/[0.06] dark:bg-foreground/[0.04]">
+                        <Icon className="h-3.5 w-3.5 text-foreground/70 dark:text-muted-foreground" />
+                      </div>
+                    )}
+                    <span className="text-xs font-semibold text-foreground uppercase tracking-wider">
+                      {title}
+                    </span>
+                  </div>
+                  {subtitle && (
+                    <p className="text-sm text-muted-foreground mt-1">
+                      {subtitle}
+                    </p>
+                  )}
+                </div>
+                {actions && (
+                  <div className="flex-shrink-0">
+                    {actions}
+                  </div>
+                )}
+              </div>
+            </div>
+          )}
+          {variant === "compact" && (
+            <div className="p-5 flex items-center justify-between gap-4 border-b border-black/[0.12] dark:border-white/[0.06]">
+              <div className="flex items-center gap-2 min-w-0">
+                {Icon && (
+                  <div className="p-1.5 rounded-lg bg-foreground/[0.04]">
+                    <Icon className="h-3.5 w-3.5 text-muted-foreground" />
+                  </div>
+                )}
+                <span className="text-xs font-semibold text-foreground uppercase tracking-wider">
+                  {title}
+                </span>
+              </div>
+              {actions && (
+                <div className="flex-shrink-0">
+                  {actions}
+                </div>
+              )}
+            </div>
+          )}
+          {hasContent && (
+            <div
+              className={cn(
+                variant === "header" ? "border-t border-black/[0.12] dark:border-white/[0.06]" : "",
+                variant === "compact" ? "px-5 py-4" : "",
+                variant === "bodyOnly" || variant === "header" ? bodyPaddingClass : "",
+                contentClassName
+              )}
+            >
+              {children}
+            </div>
+          )}
+        </div>
+      </Card>
+    </DesignCardNestingContext.Provider>
+  );
+}
+
+export type DesignCardTintProps = {
+  gradient: DesignCardGradient,
+} & React.ComponentProps<"div">
+
+export function DesignCardTint({
+  gradient,
+  className,
+  children,
+  ...props
+}: DesignCardTintProps) {
+  const tintClass = demoTintClasses.get(gradient) ?? "group-hover/tint:bg-slate-500/[0.015]";
+
+  return (
+    <div
+      className={cn(
+        "group/tint relative rounded-2xl bg-white/90 dark:bg-background/60 dark:backdrop-blur-xl transition-all duration-150 hover:transition-none",
+        "ring-1 ring-black/[0.06] hover:ring-black/[0.1] dark:ring-white/[0.06] dark:hover:ring-white/[0.1]",
+        "shadow-none overflow-hidden",
+        className
+      )}
+      {...props}
+    >
+      <div className="absolute inset-0 bg-gradient-to-br from-foreground/[0.04] dark:from-foreground/[0.02] to-transparent pointer-events-none rounded-2xl" />
+      <div
+        className={cn(
+          "absolute inset-0 transition-colors duration-150 group-hover/tint:transition-none pointer-events-none rounded-2xl",
+          tintClass
+        )}
+      />
+      <div className="relative">
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/components/chart-card.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+import { cn } from "@hexclave/ui";
+import React from "react";
+
+type DesignChartCardGradient = "blue" | "cyan" | "purple" | "green" | "orange" | "default";
+
+const hoverTintClasses = new Map<DesignChartCardGradient, string>([
+  ["blue", "group-hover:bg-blue-500/[0.03]"],
+  ["cyan", "group-hover:bg-cyan-500/[0.03]"],
+  ["purple", "group-hover:bg-purple-500/[0.03]"],
+  ["green", "group-hover:bg-emerald-500/[0.03]"],
+  ["orange", "group-hover:bg-orange-500/[0.03]"],
+  ["default", "group-hover:bg-slate-500/[0.02]"],
+]);
+
+export type DesignChartCardProps = {
+  gradient?: DesignChartCardGradient,
+  title?: React.ReactNode,
+  description?: React.ReactNode,
+} & Omit<React.ComponentProps<"div">, "title">;
+
+/**
+ * Card chrome (title + description + border) for a chart. Wrap every
+ * `AnalyticsChart` in this so the chart has context. Also used around raw
+ * Recharts components paired with `DesignChartContainer` for non-time-series
+ * fallbacks.
+ *
+ * ```tsx
+ * // Time-series chart (preferred):
+ * <DesignChartCard title="Signups" description="Last 30 days">
+ *   <AnalyticsChart data={data} state={state} onChange={setState} />
+ * </DesignChartCard>
+ *
+ * // Non-time-series fallback (static ranking, distribution, etc.):
+ * <DesignChartCard title="Top referrers" description="This month">
+ *   <DesignChartContainer config={chartConfig} maxHeight={300}>
+ *     <Recharts.BarChart data={data}>
+ *       <Recharts.CartesianGrid strokeDasharray="3 3" stroke="hsl(var(--border))" />
+ *       <Recharts.XAxis dataKey="name" tick={{ fill: 'hsl(var(--muted-foreground))', fontSize: 12 }} />
+ *       <Recharts.YAxis tick={{ fill: 'hsl(var(--muted-foreground))', fontSize: 12 }} />
+ *       <Recharts.Tooltip content={<DesignChartTooltipContent />} />
+ *       <Recharts.Bar dataKey="count" fill={getDesignChartColor(0)} radius={[4, 4, 0, 0]} />
+ *     </Recharts.BarChart>
+ *   </DesignChartContainer>
+ * </DesignChartCard>
+ * ```
+ *
+ * `chartConfig` for `DesignChartContainer` maps each `dataKey` to its label and color:
+ * `{ count: { label: "Count", color: getDesignChartColor(0) } }`.
+ */
+export function DesignChartCard({
+  gradient = "default",
+  title,
+  description,
+  className,
+  children,
+  ...props
+}: DesignChartCardProps) {
+  const hoverTintClass = hoverTintClasses.get(gradient) ?? "group-hover:bg-slate-500/[0.02]";
+
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: `
+        .design-chart-card-tooltip-escape .recharts-tooltip-wrapper {
+          z-index: 9999 !important;
+          overflow: visible !important;
+        }
+        .design-chart-card-tooltip-escape .recharts-tooltip-wrapper > * {
+          overflow: visible !important;
+        }
+      ` }} />
+      <div
+        className={cn(
+          "group relative rounded-2xl bg-white/90 dark:bg-background/60 backdrop-blur-xl transition-all duration-150 hover:transition-none design-chart-card-tooltip-escape",
+          "ring-1 ring-black/[0.06] hover:ring-black/[0.1] dark:ring-white/[0.06] dark:hover:ring-white/[0.1]",
+          "shadow-sm hover:shadow-md hover:z-10",
+          className
+        )}
+        {...props}
+      >
+        <div className="absolute inset-0 bg-gradient-to-br from-foreground/[0.04] dark:from-foreground/[0.02] to-transparent pointer-events-none rounded-2xl overflow-hidden" />
+        <div
+          className={cn(
+            "absolute inset-0 transition-colors duration-150 group-hover:transition-none pointer-events-none rounded-2xl overflow-hidden",
+            hoverTintClass
+          )}
+        />
+        <div className="relative h-full flex flex-col p-4">
+          {(title || description) && (
+            <div className="mb-3">
+              {title && <h3 className="text-sm font-semibold text-foreground">{title}</h3>}
+              {description && <p className="text-xs text-muted-foreground mt-0.5">{description}</p>}
+            </div>
+          )}
+          {children}
+        </div>
+      </div>
+    </>
+  );
+}

package/src/components/chart-container.tsx

@@ -0,0 +1,155 @@
+"use client";
+
+import * as React from "react";
+import * as RechartsPrimitive from "recharts";
+import { cn } from "@hexclave/ui";
+
+const THEMES = { light: "", dark: ".dark" } as const;
+
+export type DesignChartConfig = {
+  [k in string]: {
+    label?: React.ReactNode,
+    icon?: React.ComponentType,
+  } & (
+    | { color?: string, theme?: never }
+    | { color?: never, theme: Record<keyof typeof THEMES, string> }
+  )
+};
+
+type ChartContextProps = {
+  config: DesignChartConfig,
+};
+
+const ChartContext = React.createContext<ChartContextProps | null>(null);
+
+export function useDesignChart() {
+  const context = React.useContext(ChartContext);
+  if (!context) {
+    throw new Error("useDesignChart must be used within a <DesignChartContainer />");
+  }
+  return context;
+}
+
+export function DesignChartStyle({ id, config }: { id: string, config: DesignChartConfig }) {
+  const colorConfig = Object.entries(config).filter(
+    ([_, cfg]) => cfg.theme || cfg.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"),
+      }}
+    />
+  );
+}
+
+export const DesignChartContainer = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<"div"> & {
+    maxHeight?: number,
+    config: DesignChartConfig,
+    children: React.ComponentProps<
+      typeof RechartsPrimitive.ResponsiveContainer
+    >["children"],
+  }
+>(({ id, className, children, config, maxHeight, ...props }, ref) => {
+  const uniqueId = React.useId();
+  const chartId = `chart-${id || uniqueId.replace(/:/g, "")}`;
+
+  return (
+    <ChartContext.Provider value={{ config }}>
+      <div
+        data-chart={chartId}
+        ref={ref}
+        className={cn(
+          "flex aspect-video justify-center text-xs",
+          "[&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground",
+          "[&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-black/[0.06] dark:[&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-white/[0.06]",
+          "[&_.recharts-curve.recharts-tooltip-cursor]:stroke-black/[0.12] dark:[&_.recharts-curve.recharts-tooltip-cursor]:stroke-white/[0.12]",
+          "[&_.recharts-dot[stroke='#fff']]:stroke-transparent",
+          "[&_.recharts-layer]:outline-none",
+          "[&_.recharts-polar-grid_[stroke='#ccc']]:stroke-black/[0.06] dark:[&_.recharts-polar-grid_[stroke='#ccc']]:stroke-white/[0.06]",
+          "[&_.recharts-radial-bar-background-sector]:fill-black/[0.04] dark:[&_.recharts-radial-bar-background-sector]:fill-white/[0.04]",
+          "[&_.recharts-rectangle.recharts-tooltip-cursor]:fill-black/[0.04] dark:[&_.recharts-rectangle.recharts-tooltip-cursor]:fill-white/[0.04]",
+          "[&_.recharts-reference-line_[stroke='#ccc']]:stroke-black/[0.06] dark:[&_.recharts-reference-line_[stroke='#ccc']]:stroke-white/[0.06]",
+          "[&_.recharts-sector[stroke='#fff']]:stroke-transparent",
+          "[&_.recharts-sector]:outline-none",
+          "[&_.recharts-surface]:outline-none",
+          className
+        )}
+        {...props}
+        style={{
+          ...props.style,
+          maxHeight,
+        }}
+      >
+        <DesignChartStyle id={chartId} config={config} />
+        <RechartsPrimitive.ResponsiveContainer maxHeight={maxHeight}>
+          {children}
+        </RechartsPrimitive.ResponsiveContainer>
+      </div>
+    </ChartContext.Provider>
+  );
+});
+DesignChartContainer.displayName = "DesignChartContainer";
+
+/**
+ * Helper to extract item config from a Recharts payload object.
+ */
+export function getPayloadConfigFromPayload(
+  config: DesignChartConfig,
+  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];
+}

package/src/components/chart-legend.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import * as React from "react";
+import * as RechartsPrimitive from "recharts";
+import { cn } from "@hexclave/ui";
+import { useDesignChart, getPayloadConfigFromPayload } from "./chart-container";
+
+export const DesignChartLegendContent = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<"div"> &
+    Pick<RechartsPrimitive.LegendProps, "payload" | "verticalAlign"> & {
+      hideIcon?: boolean,
+      nameKey?: string,
+    }
+>(
+  (
+    { className, hideIcon = false, payload, verticalAlign = "bottom", nameKey },
+    ref
+  ) => {
+    const { config } = useDesignChart();
+
+    if (!payload?.length) {
+      return null;
+    }
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "flex flex-wrap items-center justify-center gap-2",
+          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(
+                "flex items-center gap-1.5 rounded-full bg-foreground/[0.03] ring-1 ring-foreground/[0.06] px-3 py-1.5 text-xs",
+                "transition-colors duration-150 hover:transition-none hover:bg-foreground/[0.05]"
+              )}
+            >
+              {itemConfig?.icon && !hideIcon ? (
+                <itemConfig.icon />
+              ) : (
+                <span
+                  className="h-2 w-2 shrink-0 rounded-full"
+                  style={{ backgroundColor: item.color }}
+                />
+              )}
+              <span className="font-medium text-foreground">
+                {itemConfig?.label || item.value}
+              </span>
+            </div>
+          );
+        })}
+      </div>
+    );
+  }
+);
+DesignChartLegendContent.displayName = "DesignChartLegendContent";

package/src/components/chart-theme.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+export type DesignChartColorEntry = {
+  light: string,
+  dark: string,
+};
+
+/**
+ * Design-system-consistent chart colors that work in light and dark mode.
+ * Maps to the gradient system used across the dashboard design components.
+ */
+export const DESIGN_CHART_COLORS: readonly DesignChartColorEntry[] = [
+  { light: "hsl(221, 83%, 53%)", dark: "hsl(217, 91%, 60%)" },   // blue
+  { light: "hsl(192, 91%, 36%)", dark: "hsl(188, 94%, 43%)" },   // cyan
+  { light: "hsl(271, 91%, 65%)", dark: "hsl(270, 95%, 75%)" },   // purple
+  { light: "hsl(160, 84%, 39%)", dark: "hsl(160, 84%, 45%)" },   // emerald/green
+  { light: "hsl(38, 92%, 50%)",  dark: "hsl(38, 92%, 50%)" },    // amber/orange
+  { light: "hsl(0, 84%, 60%)",   dark: "hsl(0, 84%, 65%)" },     // red
+] as const;
+
+export type DesignChartColorName = "blue" | "cyan" | "purple" | "green" | "orange" | "red";
+
+const colorNameIndexMap = new Map<DesignChartColorName, number>([
+  ["blue", 0],
+  ["cyan", 1],
+  ["purple", 2],
+  ["green", 3],
+  ["orange", 4],
+  ["red", 5],
+]);
+
+/**
+ * Get a chart color by index (wraps around) or by name.
+ */
+export function getDesignChartColor(
+  indexOrName: number | DesignChartColorName,
+  mode: "light" | "dark" = "dark",
+): string {
+  const index = typeof indexOrName === "string"
+    ? colorNameIndexMap.get(indexOrName) ?? 0
+    : indexOrName % DESIGN_CHART_COLORS.length;
+  return DESIGN_CHART_COLORS[index][mode];
+}
+
+/**
+ * Recharts-compatible grid/axis styling constants that match the design system.
+ */
+export const DESIGN_CHART_GRID_COLOR = "hsl(0 0% 50% / 0.12)";
+export const DESIGN_CHART_AXIS_TICK_STYLE = {
+  fill: "hsl(0 0% 50% / 0.5)",
+  fontSize: 11,
+} as const;