@manta-eu/react 0.7.0 → 0.8.0

package/src/components/chart/ForecastChart.tsx

@@ -0,0 +1,383 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { Area, CartesianGrid, ComposedChart, Line, ReferenceDot, ReferenceLine, XAxis, YAxis } from "recharts";
+import { renderAnnotations } from "./annotations";
+import { ChartTooltip } from "./chart";
+import { ChartFrame } from "./ChartFrame";
+import {
+  forecastMargin,
+  forecastXAxisHeight,
+  formatCompact,
+  formatWhole,
+  nearestMetric,
+  partKey,
+  plotGeometry,
+  rangeKey,
+  valueAtY,
+  type ForecastEvent,
+  type ForecastPart,
+  type ForecastPlanShare,
+} from "./forecast";
+import {
+  betweenName,
+  buildForecastModel,
+  forecastParts as parts,
+  gainName,
+  metricColor,
+  withoutColor,
+  type ForecastBetween,
+  type ForecastMetric,
+} from "./forecast-model";
+import { ForecastEventCard, ForecastEventDot } from "./ForecastEventCard";
+import { ForecastHoverCard } from "./ForecastHoverCard";
+import { ForecastLegend } from "./ForecastLegend";
+import { Popover, PopoverAnchor } from "#components/popover/index";
+import { cn } from "#style";
+
+export type ForecastChartProps = {
+  /** One row per x value; each row carries `x` and a number per metric key. */
+  data: Record<string, unknown>[];
+  /** The x value of Today: lines are solid up to it and dotted after. Omit it for a history-only chart. */
+  today?: string | number;
+  metrics: ForecastMetric[];
+  /** Legend name of the shading between a metric and its `withoutPlans` line. */
+  gainLabel?: string;
+  /** A faint fill between two metrics, such as profit between revenue and costs. */
+  between?: ForecastBetween[];
+  goal?: { value: number; label: string };
+  events?: ForecastEvent[];
+  /** Called when an event's dot or its card link is chosen; without it, an event's `href` is a plain link. */
+  onEventSelect?: (event: ForecastEvent) => void;
+  /** The plans behind each projected point of a metric, shown in its hover card (the first two). */
+  planShares?: ForecastPlanShare[];
+  /** Formats axis ticks. */
+  formatValue?: (value: number) => string;
+  /** Formats the figures in the hover card. */
+  formatDetail?: (value: number) => string;
+  /** Follows the signed gap in the hover card: "+$2,664 with the plans". */
+  changeLabel?: string;
+  projectedLabel?: string;
+  /** The tag on the Today line. */
+  todayLabel?: string;
+  /** Legend names of the solid and dotted parts of a single metric. */
+  legendLabels?: { historic?: string; projected?: string };
+  title?: string;
+  height?: number;
+  className?: string;
+};
+
+const projectedDash = "0.5 6";
+const noBetween: ForecastBetween[] = [];
+const noEvents: ForecastEvent[] = [];
+const noPlanShares: ForecastPlanShare[] = [];
+
+function TodayTag(props: { text: string; viewBox?: { x?: number; y?: number } }) {
+  const { text, viewBox } = props;
+  if (viewBox?.x === undefined || viewBox.y === undefined) {
+    return null;
+  }
+  return (
+    <foreignObject
+      x={viewBox.x - 100}
+      y={viewBox.y}
+      width={200}
+      height={20}
+      className="pointer-events-none overflow-visible"
+    >
+      <div className="flex justify-center">
+        <span className="h-5 rounded-full border border-default-border bg-card px-2 typography-tiny-medium leading-5 text-default-foreground">
+          {text}
+        </span>
+      </div>
+    </foreignObject>
+  );
+}
+
+export function ForecastChart(props: ForecastChartProps) {
+  const {
+    data,
+    today,
+    metrics,
+    gainLabel = "Added by plans",
+    between = noBetween,
+    goal,
+    events = noEvents,
+    onEventSelect,
+    planShares = noPlanShares,
+    formatValue = formatCompact,
+    formatDetail = formatWhole,
+    changeLabel = "with the plans",
+    projectedLabel = "projected",
+    todayLabel = "Today",
+    legendLabels,
+    title,
+    height = 320,
+    className,
+  } = props;
+  const id = useId().replace(/:/g, "");
+  const fadeId = `forecast-fade-${id}`;
+  const cardId = `forecast-event-${id}`;
+  const plotRef = useRef<HTMLDivElement>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const [activeEvent, setActiveEvent] = useState<{ index: number; cx: number; cy: number }>();
+  const [focusKey, setFocusKey] = useState<string>();
+
+  const model = useMemo(
+    () =>
+      buildForecastModel({
+        data,
+        ...(today === undefined ? {} : { today }),
+        metrics,
+        between,
+        gainLabel,
+        ...(goal ? { goal } : {}),
+        ...(legendLabels ? { legendLabels } : {}),
+      }),
+    [data, today, metrics, between, goal, gainLabel, legendLabels],
+  );
+
+  const emptyKeys = model.emptyKeys.join(", ");
+  useEffect(() => {
+    if (isPresent(emptyKeys)) {
+      console.warn(`ForecastChart: no numbers in data for ${emptyKeys}; check the metric keys`);
+    }
+  }, [emptyKeys]);
+
+  const missingToday = model.todayMissing ? String(today) : "";
+  useEffect(() => {
+    if (isPresent(missingToday)) {
+      console.warn(
+        `ForecastChart: today "${missingToday}" matches no row's x; the Today line and projection are hidden`,
+      );
+    }
+  }, [missingToday]);
+
+  const { overlay, withPlans, rows, domain, ticks, firstColor } = model;
+  const gainOpacity: Record<ForecastPart, number> = overlay ? { past: 0.5, ahead: 0.34 } : { past: 0.24, ahead: 0.14 };
+  const betweenOpacity: Record<ForecastPart, number> = { past: 0.08, ahead: 0.05 };
+  const geometry = plotGeometry(height);
+  const focusedMetric = model.hoverMetrics.find((metric) => metric.key === focusKey) ?? model.hoverMetrics[0];
+
+  function followPointer(state: { chartY?: number; activePayload?: { payload?: Record<string, unknown> }[] }) {
+    const row = state.activePayload?.[0]?.payload;
+    if (state.chartY === undefined || row === undefined) {
+      return;
+    }
+    const nearest = nearestMetric(
+      row,
+      metrics.map((metric) => metric.key),
+      valueAtY(state.chartY, geometry.top, geometry.height, domain),
+    );
+    if (nearest !== focusKey) {
+      setFocusKey(nearest);
+    }
+  }
+
+  function cancelClose() {
+    clearTimeout(closeTimer.current);
+  }
+
+  function closeSoon() {
+    cancelClose();
+    closeTimer.current = setTimeout(() => setActiveEvent(undefined), 150);
+  }
+
+  function closeUnlessInside(next: EventTarget | null) {
+    const inside = [plotRef.current, document.getElementById(cardId)].some(
+      (container) => next instanceof Node && container?.contains(next),
+    );
+    if (!inside) {
+      setActiveEvent(undefined);
+    }
+  }
+
+  function showEvent(index: number, cx: number, cy: number) {
+    cancelClose();
+    setActiveEvent({ index, cx, cy });
+  }
+
+  function rangeArea(name: string, part: ForecastPart, color: string, opacity: number) {
+    return (
+      <Area
+        key={rangeKey(name, part)}
+        dataKey={rangeKey(name, part)}
+        type="monotone"
+        fill={color}
+        fillOpacity={opacity}
+        stroke="none"
+        tooltipType="none"
+        activeDot={false}
+        isAnimationActive={false}
+      />
+    );
+  }
+
+  function line(key: string, part: ForecastPart, color: string, width: number, withPlans: boolean) {
+    const activeDot = { r: 3.5, fill: color, stroke: "var(--color-card)", strokeWidth: 1.5 };
+    return (
+      <Line
+        key={partKey(key, part)}
+        dataKey={partKey(key, part)}
+        type="monotone"
+        stroke={color}
+        strokeWidth={width}
+        strokeLinejoin="round"
+        strokeLinecap="round"
+        strokeDasharray={part === "ahead" && withPlans ? projectedDash : undefined}
+        dot={false}
+        activeDot={activeEvent ? false : activeDot}
+        tooltipType="none"
+        isAnimationActive={false}
+      />
+    );
+  }
+
+  const shownEvent = activeEvent ? events[activeEvent.index] : undefined;
+
+  return (
+    <div className={cn("w-full", className)}>
+      {isPresent(title) ? (
+        <p className="typography-small-medium mb-2 text-center text-default-foreground">{title}</p>
+      ) : null}
+      <ForecastLegend items={model.legendItems} />
+      <div ref={plotRef} className="relative">
+        <ChartFrame config={model.config} height={height}>
+          <ComposedChart accessibilityLayer data={rows} margin={forecastMargin} onMouseMove={followPointer}>
+            <defs>
+              <linearGradient id={fadeId} x1="0" y1="0" x2="0" y2="1">
+                <stop offset="0%" stopColor={model.fadeColor} stopOpacity={overlay ? 0.3 : 0.34} />
+                <stop offset="100%" stopColor={model.fadeColor} stopOpacity={0} />
+              </linearGradient>
+            </defs>
+            <CartesianGrid vertical={false} strokeDasharray="2 3" />
+            <XAxis
+              dataKey="x"
+              height={forecastXAxisHeight}
+              tickLine={false}
+              axisLine={false}
+              tickMargin={12}
+              minTickGap={24}
+            />
+            <YAxis
+              tickLine={false}
+              axisLine={false}
+              width={56}
+              domain={domain}
+              ticks={ticks}
+              interval={0}
+              tickFormatter={formatValue}
+              allowDataOverflow
+            />
+            {model.fadeKeys.map(({ part, key }) => (
+              <Area
+                key={`fade-${part}`}
+                dataKey={partKey(key, part)}
+                baseValue="dataMin"
+                type="monotone"
+                stroke="none"
+                fill={`url(#${fadeId})`}
+                tooltipType="none"
+                activeDot={false}
+                isAnimationActive={false}
+              />
+            ))}
+            {between.flatMap((_, index) =>
+              parts.map((part) => rangeArea(betweenName(index), part, firstColor, betweenOpacity[part])),
+            )}
+            {withPlans.flatMap((entry) =>
+              parts.map((part) =>
+                rangeArea(gainName(entry.index), part, metricColor(entry.metric, entry.index), gainOpacity[part]),
+              ),
+            )}
+            {isPresent(goal)
+              ? renderAnnotations([
+                  { kind: "reference-line", axis: "y", value: goal.value, label: goal.label, tone: "neutral" },
+                ])
+              : null}
+            {model.todayIndex >= 0 && today !== undefined ? (
+              <ReferenceLine
+                x={today}
+                stroke="var(--color-default-foreground)"
+                strokeOpacity={0.4}
+                label={<TodayTag text={todayLabel} />}
+              />
+            ) : null}
+            <ChartTooltip
+              active={shownEvent ? false : undefined}
+              cursor={{ stroke: "var(--color-default-border)" }}
+              content={
+                <ForecastHoverCard
+                  metric={focusedMetric}
+                  formatDetail={formatDetail}
+                  changeLabel={changeLabel}
+                  projectedLabel={projectedLabel}
+                  planShares={planShares}
+                />
+              }
+            />
+            {withPlans.flatMap((entry) =>
+              parts.map((part) => line(entry.without.key, part, withoutColor, overlay ? 1.5 : 2, false)),
+            )}
+            {metrics.flatMap((metric, index) =>
+              (["ahead", "past"] as const).map((part) =>
+                line(metric.key, part, metricColor(metric, index), index === 0 ? 2.5 : 2.25, true),
+              ),
+            )}
+            {events.map((event, index) => {
+              const metricIndex = metrics.findIndex((metric) => metric.key === event.metric);
+              const metric = metrics[metricIndex];
+              const value = data.find((row) => row.x === event.x)?.[event.metric];
+              if (typeof value !== "number" || metric === undefined) {
+                return null;
+              }
+              return (
+                <ReferenceDot
+                  key={`${event.metric}-${event.x}-${event.title}`}
+                  x={event.x}
+                  y={value}
+                  shape={(dot: { cx?: number; cy?: number }) => (
+                    <ForecastEventDot
+                      event={event}
+                      color={metricColor(metric, metricIndex)}
+                      {...(dot.cx === undefined ? {} : { cx: dot.cx })}
+                      {...(dot.cy === undefined ? {} : { cy: dot.cy })}
+                      active={activeEvent?.index === index}
+                      cardId={cardId}
+                      {...(onEventSelect ? { onSelect: onEventSelect } : {})}
+                      onShow={(cx, cy) => showEvent(index, cx, cy)}
+                      onLeave={closeSoon}
+                      onBlur={closeUnlessInside}
+                    />
+                  )}
+                />
+              );
+            })}
+          </ComposedChart>
+        </ChartFrame>
+        <Popover
+          key={activeEvent?.index}
+          open={shownEvent !== undefined}
+          onOpenChange={(open) => !open && setActiveEvent(undefined)}
+        >
+          <PopoverAnchor asChild>
+            <span
+              aria-hidden="true"
+              className="pointer-events-none absolute size-0"
+              style={{ left: activeEvent?.cx ?? 0, top: activeEvent?.cy ?? 0 }}
+            />
+          </PopoverAnchor>
+          {shownEvent ? (
+            <ForecastEventCard
+              event={shownEvent}
+              id={cardId}
+              {...(onEventSelect ? { onSelect: onEventSelect } : {})}
+              onEnter={cancelClose}
+              onLeave={closeSoon}
+              onBlur={closeUnlessInside}
+            />
+          ) : null}
+        </Popover>
+      </div>
+    </div>
+  );
+}

package/src/components/chart/ForecastEventCard.tsx

@@ -0,0 +1,163 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { ArrowUpRight } from "lucide-react";
+import type { FocusEvent, KeyboardEvent, ReactNode } from "react";
+import type { ForecastEvent } from "./forecast";
+import { PopoverArrow, PopoverContent } from "#components/popover/index";
+import { cn } from "#style";
+
+const eventLabels: Record<ForecastEvent["status"], string> = {
+  applied: "Applied",
+  waiting: "Waiting for your approval",
+};
+
+export function eventLabel(event: ForecastEvent): string {
+  return event.label ?? eventLabels[event.status];
+}
+
+type ForecastEventDotProps = {
+  event: ForecastEvent;
+  color: string;
+  cx?: number;
+  cy?: number;
+  active: boolean;
+  cardId: string;
+  onSelect?: (event: ForecastEvent) => void;
+  onShow: (cx: number, cy: number) => void;
+  onLeave: () => void;
+  onBlur: (next: EventTarget | null) => void;
+};
+
+/** A dot on a metric's line. With `onSelect` it acts on click or Enter; otherwise an `href` makes it a plain link. */
+export function ForecastEventDot(props: ForecastEventDotProps) {
+  const { event, color, cx, cy, active, cardId, onSelect, onShow, onLeave, onBlur } = props;
+  if (cx === undefined || cy === undefined) {
+    return null;
+  }
+  const label = `${eventLabel(event)}: ${event.title}`;
+  const waiting = event.status === "waiting";
+  const circles = (
+    <>
+      <circle cx={cx} cy={cy} r={14} fill="transparent" />
+      <circle
+        cx={cx}
+        cy={cy}
+        r={10}
+        fill={color}
+        className={cn(
+          "opacity-0 transition-opacity group-hover/event:opacity-20 group-focus-visible/event:opacity-35",
+          active && "opacity-20",
+        )}
+      />
+      <circle
+        cx={cx}
+        cy={cy}
+        r={active ? 6.5 : 5}
+        fill={waiting ? "var(--color-card)" : color}
+        stroke={waiting ? color : "var(--color-card)"}
+        strokeWidth={2}
+      />
+    </>
+  );
+  const shared = {
+    "aria-label": label,
+    "aria-describedby": active ? cardId : undefined,
+    className: "group/event cursor-pointer outline-none",
+    onMouseEnter: () => onShow(cx, cy),
+    onMouseLeave: onLeave,
+    onFocus: () => onShow(cx, cy),
+    onBlur: (focusEvent: FocusEvent) => onBlur(focusEvent.relatedTarget),
+  };
+
+  if (onSelect === undefined && isPresent(event.href)) {
+    return (
+      <a href={event.href} {...shared}>
+        {circles}
+      </a>
+    );
+  }
+
+  if (onSelect === undefined) {
+    return (
+      <g role="img" tabIndex={0} {...shared} className="group/event outline-none">
+        {circles}
+      </g>
+    );
+  }
+
+  function handleKeyDown(keyEvent: KeyboardEvent<SVGGElement>) {
+    if (keyEvent.key === "Enter" || keyEvent.key === " ") {
+      keyEvent.preventDefault();
+      onSelect?.(event);
+    }
+  }
+
+  return (
+    <g role="button" tabIndex={0} {...shared} onClick={() => onSelect(event)} onKeyDown={handleKeyDown}>
+      {circles}
+    </g>
+  );
+}
+
+type ForecastEventCardProps = {
+  event: ForecastEvent;
+  id: string;
+  onSelect?: (event: ForecastEvent) => void;
+  onEnter: () => void;
+  onLeave: () => void;
+  onBlur: (next: EventTarget | null) => void;
+};
+
+/** The dark card over a dot: its label, title, value and, with an `href`, an "Open plan" link. */
+export function ForecastEventCard(props: ForecastEventCardProps) {
+  const { event, id, onSelect, onEnter, onLeave, onBlur } = props;
+  const link: ReactNode = isPresent(event.href) ? (
+    <a
+      href={event.href}
+      onClick={(clickEvent) => {
+        if (onSelect) {
+          clickEvent.preventDefault();
+          onSelect(event);
+        }
+      }}
+      className="mt-1 inline-flex items-center gap-1 self-start typography-small underline underline-offset-2"
+    >
+      {event.linkLabel ?? "Open plan"}
+      <ArrowUpRight className="size-3.5" aria-hidden="true" />
+    </a>
+  ) : null;
+  return (
+    <PopoverContent
+      id={id}
+      role={isPresent(event.href) ? undefined : "tooltip"}
+      side="top"
+      sideOffset={12}
+      collisionPadding={8}
+      onOpenAutoFocus={(focusEvent) => focusEvent.preventDefault()}
+      onCloseAutoFocus={(focusEvent) => focusEvent.preventDefault()}
+      className={cn(
+        "flex w-max min-w-50 max-w-65 flex-col gap-1 rounded-md-v4 border-0 px-3.5 pt-2.5 pb-3",
+        "bg-inverse text-inverse-foreground shadow-xl ring-1 ring-inverse-foreground/10",
+        !isPresent(event.href) && "pointer-events-none",
+      )}
+      onMouseEnter={onEnter}
+      onMouseLeave={onLeave}
+      onBlur={(focusEvent) => onBlur(focusEvent.relatedTarget)}
+    >
+      <span className="typography-tiny opacity-70">{eventLabel(event)}</span>
+      <strong className="typography-body-medium">{event.title}</strong>
+      {isPresent(event.value) ? (
+        <span
+          className="typography-small-semibold tabular-nums"
+          style={{ color: "color-mix(in srgb, var(--color-accent-foreground) 55%, var(--color-inverse-foreground))" }}
+        >
+          {event.value}
+          {isPresent(event.valueNote) ? (
+            <small className="ml-1 typography-tiny opacity-70">{event.valueNote}</small>
+          ) : null}
+        </span>
+      ) : null}
+      {link}
+      <PopoverArrow className="fill-inverse" width={12} height={6} />
+    </PopoverContent>
+  );
+}

package/src/components/chart/ForecastHoverCard.tsx

@@ -0,0 +1,73 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { plansAt, projectedKey, signedChange, type ForecastPlanShare } from "./forecast";
+import { cn } from "#style";
+
+export type ForecastHoverMetric = { key: string; label: string; withoutKey?: string; lowerIsBetter: boolean };
+
+type ForecastHoverCardProps = {
+  metric: ForecastHoverMetric | undefined;
+  formatDetail: (value: number) => string;
+  changeLabel: string;
+  projectedLabel: string;
+  planShares: readonly ForecastPlanShare[];
+  active?: boolean;
+  label?: string | number;
+  payload?: { payload?: Record<string, unknown> }[];
+};
+
+/** The card for the line under the pointer: its figure and, when projected, the gap and the plans behind it. */
+export function ForecastHoverCard(props: ForecastHoverCardProps) {
+  const { metric, formatDetail, changeLabel, projectedLabel, planShares, active, label, payload } = props;
+  const row = payload?.[0]?.payload;
+  const value = metric === undefined ? undefined : row?.[metric.key];
+  if (active !== true || row === undefined || metric === undefined || typeof value !== "number") {
+    return null;
+  }
+  const projected = row[projectedKey] === true;
+  const without = isPresent(metric.withoutKey) ? row[metric.withoutKey] : undefined;
+  const x = row.x;
+  function helps(change: number) {
+    return metric?.lowerIsBetter === true ? change <= 0 : change >= 0;
+  }
+  const plans =
+    projected && (typeof x === "string" || typeof x === "number") ? plansAt(planShares, x, metric.key).slice(0, 2) : [];
+  return (
+    <div className="min-w-50 max-w-75 rounded-md-v4 border border-default-border bg-card px-3 py-2.5 text-default-foreground shadow-xl">
+      <p className="mb-1.5 typography-tiny text-muted-foreground">
+        {label}
+        {projected ? ` · ${projectedLabel}` : ""}
+      </p>
+      <p className="flex items-baseline justify-between gap-4 typography-small text-muted-foreground">
+        <span>{metric.label}</span>
+        <strong className="typography-body-semibold tabular-nums text-default-foreground">{formatDetail(value)}</strong>
+      </p>
+      {projected && typeof without === "number" ? (
+        <p
+          className={cn(
+            "typography-small-medium tabular-nums",
+            helps(value - without) ? "text-accent-foreground" : "text-muted-foreground",
+          )}
+        >
+          {signedChange(value, without, formatDetail)} {changeLabel}
+        </p>
+      ) : null}
+      {isPresent(plans) ? (
+        <div className="mt-2 grid gap-0.5 border-t border-default-border pt-2">
+          {plans.map((plan) => (
+            <p key={plan.label} className="flex items-baseline justify-between gap-3 typography-tiny">
+              <span className="min-w-0">{plan.label}</span>
+              <strong
+                className={cn(
+                  "flex-none typography-tiny-semibold tabular-nums",
+                  helps(plan.value) ? "text-accent-foreground" : "text-muted-foreground",
+                )}
+              >
+                {signedChange(plan.value, 0, formatDetail)}
+              </strong>
+            </p>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}