@carlonicora/nextjs-jsonapi 6.19.0 → 6.20.1

package/src/core/factories/RehydrationFactory.ts

@@ -10,18 +10,58 @@ import { DataClassRegistry } from "../registry/DataClassRegistry";
  */
 const inProgress = new Set<string>();
 
+/**
+ * The included resources already rehydrated during the current top-level `rehydrate` /
+ * `rehydrateList` call, by model class and `type:id`, with the `included` array they were read from.
+ * A resource reached again through another relationship reuses that model instead of being built
+ * again: without it every distinct path through a densely linked `included` (a campaign, its PCs,
+ * their locations, the scenes there, back to the campaign...) is rehydrated, which grows
+ * exponentially with the number of linked resources. A reused model keeps what it read the first
+ * time, so a relationship back to a resource that was mid-rehydration then stays unset.
+ * The top-level resources are always rehydrated from scratch, so each one is complete.
+ */
+let built: Map<unknown, Map<string, { included: unknown; model: unknown }>> | undefined;
+let depth = 0;
+
 const keyOf = (data: JsonApiHydratedDataInterface): string | undefined => {
   const resource = data?.jsonApi;
   return resource?.type && resource?.id ? `${resource.type}:${resource.id}` : undefined;
 };
 
-function guarded<T>(data: JsonApiHydratedDataInterface, run: () => T): T {
+function session<T>(run: () => T): T {
+  const outermost = depth === 0;
+  if (outermost) built = new Map();
+  depth++;
+  try {
+    return run();
+  } finally {
+    depth--;
+    if (outermost) built = undefined;
+  }
+}
+
+function guarded<T>(factoryClass: unknown, data: JsonApiHydratedDataInterface, run: () => T): T {
   const key = keyOf(data);
   if (!key) return run();
   if (inProgress.has(key)) return undefined as T;
+
+  if (inProgress.size > 0) {
+    const previous = built?.get(factoryClass)?.get(key);
+    if (previous && previous.included === data.included) return previous.model as T;
+  }
+
   inProgress.add(key);
   try {
-    return run();
+    const model = run();
+    if (built) {
+      let byKey = built.get(factoryClass);
+      if (!byKey) {
+        byKey = new Map();
+        built.set(factoryClass, byKey);
+      }
+      byKey.set(key, { included: data.included, model });
+    }
+    return model;
   } finally {
     inProgress.delete(key);
   }
@@ -34,7 +74,7 @@ export class RehydrationFactory {
   ): T {
     const factoryClass = DataClassRegistry.get(classKey);
 
-    return guarded(data, () => new factoryClass().rehydrate(data) as T);
+    return session(() => guarded(factoryClass, data, () => new factoryClass().rehydrate(data) as T));
   }
 
   public static rehydrateList<T extends ApiDataInterface>(
@@ -43,8 +83,10 @@ export class RehydrationFactory {
   ): T[] {
     const factoryClass = DataClassRegistry.get(classKey);
 
-    return data.map((item: JsonApiHydratedDataInterface) =>
-      guarded(item, () => new factoryClass().rehydrate(item) as T),
+    return session(() =>
+      data.map((item: JsonApiHydratedDataInterface) =>
+        guarded(factoryClass, item, () => new factoryClass().rehydrate(item) as T),
+      ),
     );
   }
 }

package/src/core/factories/__tests__/RehydrationFactory.spec.ts

@@ -182,4 +182,82 @@ describe("RehydrationFactory", () => {
       );
     });
   });
+
+  describe("a resource reached through several relationships", () => {
+    // A model that reads every resource its "links" relationship points to from included.
+    let calls = 0;
+    class Node implements Partial<ApiDataInterface> {
+      id = "";
+      links: Node[] = [];
+      rehydrate(data: JsonApiHydratedDataInterface) {
+        calls++;
+        this.id = data.jsonApi.id;
+        for (const ref of data.jsonApi.relationships?.links?.data ?? []) {
+          const target = data.included.find((item: any) => item.type === ref.type && item.id === ref.id);
+          if (!target) continue;
+          const node = RehydrationFactory.rehydrate<any>(nodeModule as any, { jsonApi: target, included: data.included });
+          if (node) this.links.push(node);
+        }
+        return this;
+      }
+    }
+    const nodeModule = { name: "nodes", model: Node };
+    const node = (id: string, links: string[]) => ({
+      type: "nodes",
+      id,
+      relationships: { links: { data: links.map((link) => ({ type: "nodes", id: link })) } },
+    });
+
+    beforeEach(() => {
+      calls = 0;
+      DataClassRegistry.registerObjectClass(nodeModule as any, Node as any);
+    });
+
+    it("is rehydrated once and the same model is reused", () => {
+      // root -> left, right; left -> shared; right -> shared
+      const included = [node("left", ["shared"]), node("right", ["shared"]), node("shared", [])];
+      const result = RehydrationFactory.rehydrate<any>(nodeModule as any, {
+        jsonApi: node("root", ["left", "right"]),
+        included,
+      });
+
+      expect(result.links[0].links[0].id).toBe("shared");
+      expect(result.links[0].links[0]).toBe(result.links[1].links[0]);
+      expect(calls).toBe(4);
+    });
+
+    it("densely linked included data is rehydrated in linear, not exponential, work", () => {
+      // Twelve resources, each linked to every other one: every path through them would be 11! chains.
+      const ids = Array.from({ length: 12 }, (_, index) => `n${index}`);
+      const included = ids.map((id) => node(id, ids.filter((other) => other !== id)));
+
+      const result = RehydrationFactory.rehydrate<any>(nodeModule as any, { jsonApi: included[0], included });
+
+      expect(result.links).toHaveLength(11);
+      expect(calls).toBe(12);
+    });
+
+    it("every top-level resource of a list is rehydrated whole, even one already reached as a relationship", () => {
+      // a -> b, b -> a: inside a, b's link back to a is skipped; b as its own list entry has it.
+      const a = node("a", ["b"]);
+      const b = node("b", ["a"]);
+      const [first, second] = RehydrationFactory.rehydrateList<any>(nodeModule as any, [
+        { jsonApi: a, included: [a, b] },
+        { jsonApi: b, included: [a, b] },
+      ]);
+
+      expect(first.links[0].id).toBe("b");
+      expect(first.links[0].links).toHaveLength(0);
+      expect(second.links[0].id).toBe("a");
+      expect(second).not.toBe(first.links[0]);
+    });
+
+    it("nothing is reused across separate calls", () => {
+      const included = [node("shared", [])];
+      const one = RehydrationFactory.rehydrate<any>(nodeModule as any, { jsonApi: node("x", ["shared"]), included });
+      const two = RehydrationFactory.rehydrate<any>(nodeModule as any, { jsonApi: node("y", ["shared"]), included });
+
+      expect(one.links[0]).not.toBe(two.links[0]);
+    });
+  });
 });

package/src/core/registry/ModuleRegistry.ts

@@ -103,6 +103,7 @@ export interface FoundationModuleDefinitions {
   AnalyticsEvent: ModuleWithPermissions;
   AnalyticsSummary: ModuleWithPermissions;
   AnalyticsTimeline: ModuleWithPermissions;
+  AnalyticsDailyUniqueTimeline: ModuleWithPermissions;
   AnalyticsBreakdown: ModuleWithPermissions;
   AnalyticsSession: ModuleWithPermissions;
   AnalyticsPageView: ModuleWithPermissions;

package/src/features/analytics/analytics.modules.ts

@@ -1,6 +1,7 @@
 import { ChartNoAxesCombinedIcon } from "lucide-react";
 import { ModuleFactory, ModuleWithPermissions } from "../../permissions";
 import { AnalyticsBreakdown } from "./data/analytics-breakdown";
+import { AnalyticsDailyUniqueTimeline } from "./data/analytics-daily-unique-timeline";
 import { AnalyticsEvent } from "./data/analytics-event";
 import { AnalyticsPageView } from "./data/analytics-page-view";
 import { AnalyticsSession } from "./data/analytics-session";
@@ -33,6 +34,11 @@ export const analyticsModules = (factory: ModuleFactory) =>
       model: AnalyticsTimeline,
       icon: ChartNoAxesCombinedIcon,
     }),
+    AnalyticsDailyUniqueTimeline: factory({
+      name: "analytics/administration/daily-uniques",
+      model: AnalyticsDailyUniqueTimeline,
+      icon: ChartNoAxesCombinedIcon,
+    }),
     AnalyticsBreakdown: factory({
       name: "analytics/administration/breakdown",
       model: AnalyticsBreakdown,

package/src/features/analytics/components/AnalyticsAdminContainer.tsx

@@ -7,6 +7,7 @@ import { Card, CardContent, CardHeader, CardTitle } from "../../../shadcnui";
 import { useAnalyticsAdmin } from "../contexts/AnalyticsAdminContext";
 import { AnalyticsAdminTiles } from "./AnalyticsAdminTiles";
 import { AnalyticsBreakdownTable } from "./AnalyticsBreakdownTable";
+import { AnalyticsDailyUniquesChart } from "./AnalyticsDailyUniquesChart";
 import { AnalyticsSessionsTable } from "./AnalyticsSessionsTable";
 import { AnalyticsTimelineChart } from "./AnalyticsTimelineChart";
 
@@ -25,6 +26,7 @@ export function AnalyticsAdminContainer() {
     timeline,
     breakdowns,
     sessions,
+    dailyUniques,
     loadMoreSessions,
     hasMoreSessions,
     sessionPageUrl,
@@ -70,6 +72,24 @@ export function AnalyticsAdminContainer() {
           </CardContent>
         </Card>
 
+        <Card data-testid="analytics-daily-visitors-card">
+          <CardHeader>
+            <CardTitle>{t("analytics.admin.panels.daily_visitors")}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <AnalyticsDailyUniquesChart rows={dailyUniques} metric="visitors" />
+          </CardContent>
+        </Card>
+
+        <Card data-testid="analytics-daily-users-card">
+          <CardHeader>
+            <CardTitle>{t("analytics.admin.panels.daily_users")}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <AnalyticsDailyUniquesChart rows={dailyUniques} metric="users" />
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle>{t("analytics.admin.panels.breakdown")}</CardTitle>

package/src/features/analytics/components/AnalyticsDailyUniquesChart.tsx

@@ -0,0 +1,224 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useTheme } from "next-themes";
+import { useMemo } from "react";
+import { CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
+import { ChartConfig, ChartContainer, ChartTooltip, ChartTooltipContent } from "../../../shadcnui";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import { ChartMode, seriesColor } from "../../tokenusage/lib/palette";
+import type { AnalyticsDailyUniqueTimelineInterface } from "../data/analytics-daily-unique-timeline.interface";
+
+type DailyUniquesMetric = "visitors" | "users";
+
+type AnalyticsDailyUniquesChartProps = {
+  rows: AnalyticsDailyUniqueTimelineInterface[];
+  metric: DailyUniquesMetric;
+  className?: string;
+};
+
+/** One chart entry per row. */
+export type DailyUniquesEntry = {
+  day: string;
+  /** The row's value: null = unknown for that day. */
+  value: number | null;
+  /** The solid line. Null where the line has a gap or the dotted segment takes over. */
+  line: number | null;
+  /** The dotted yesterday-to-today segment; null everywhere else. */
+  todayLine: number | null;
+  isToday: boolean;
+};
+
+/**
+ * The palette slot of each metric: visitors keep the "Visitors" colour of the
+ * "Over time" chart (slot 0); users skip slot 1, which is page views there.
+ */
+const METRIC_SLOT: Record<DailyUniquesMetric, number> = { visitors: 0, users: 2 };
+
+/** Dot radius, solid and hollow alike. */
+const DOT_RADIUS = 4;
+
+/**
+ * The day key, derived with UTC getters — the same helper as
+ * `AnalyticsTimelineChart`. The backend field is `type: "date"`, which the model
+ * parses to UTC midnight, so local getters would shift it a day west of UTC.
+ */
+const bucketKey = (date: Date): string => {
+  const y = date.getUTCFullYear();
+  const m = `${date.getUTCMonth() + 1}`.padStart(2, "0");
+  const d = `${date.getUTCDate()}`.padStart(2, "0");
+  return `${y}-${m}-${d}`;
+};
+
+/**
+ * Splits the rows into the solid line and the dotted "today" segment.
+ *
+ * Today (UTC) is still counting, so when the last row is today and both today
+ * and yesterday have values, the last segment moves to `todayLine` (drawn
+ * dotted) and the solid line stops at yesterday. A null value stays null in
+ * both series, which recharts draws as a gap (`connectNulls={false}`).
+ */
+export function buildDailyUniquesSeries(
+  rows: AnalyticsDailyUniqueTimelineInterface[],
+  metric: DailyUniquesMetric,
+  todayKey: string,
+): DailyUniquesEntry[] {
+  const entries: DailyUniquesEntry[] = rows.map((row) => {
+    const day = bucketKey(row.day);
+    const value = row[metric] ?? null;
+    return { day, value, line: value, todayLine: null, isToday: day === todayKey };
+  });
+
+  const last = entries.length - 1;
+  if (last >= 1 && entries[last].isToday && entries[last].value !== null && entries[last - 1].value !== null) {
+    entries[last - 1].todayLine = entries[last - 1].value;
+    entries[last].todayLine = entries[last].value;
+    entries[last].line = null;
+  }
+
+  return entries;
+}
+
+type DotProps = { cx?: number | null; cy?: number | null; index?: number; payload?: DailyUniquesEntry };
+
+/**
+ * Unique visitors or unique users per day, as a line.
+ *
+ * Always daily and never filtered by section: one row per day of the picked
+ * range, as the backend returns it. One series, so no legend — the card title
+ * names it. Colour does an identity job (the same metric keeps the same colour
+ * as in the "Over time" chart); the tooltip carries the value as text.
+ */
+export function AnalyticsDailyUniquesChart({ rows, metric, className }: AnalyticsDailyUniquesChartProps) {
+  const t = useTranslations();
+  const { compact, bucketDate, decimal } = useUsageFormatters();
+  const { resolvedTheme } = useTheme();
+  const mode: ChartMode = resolvedTheme === "dark" ? "dark" : "light";
+  const color = seriesColor(METRIC_SLOT[metric], mode);
+
+  const chartData = useMemo(() => buildDailyUniquesSeries(rows, metric, bucketKey(new Date())), [rows, metric]);
+
+  const points = useMemo(() => chartData.map(({ day, value }) => ({ day, value })), [chartData]);
+
+  const seriesLabel = t(`analytics.admin.daily_uniques.${metric}`);
+
+  const chartConfig = useMemo(() => ({ line: { label: seriesLabel, color } }) as ChartConfig, [seriesLabel, color]);
+
+  if (chartData.length === 0) {
+    return (
+      <p className={className ? `text-muted-foreground text-xs ${className}` : "text-muted-foreground text-xs"}>
+        {t("analytics.admin.no_data")}
+      </p>
+    );
+  }
+
+  /** Small solid dots; today's point is hollow (still counting). */
+  const renderDot = ({ cx, cy, index, payload }: DotProps) => {
+    if (cx == null || cy == null || payload?.value == null) return <g key={`dot-${index}`} />;
+    return (
+      <circle
+        key={`dot-${index}`}
+        cx={cx}
+        cy={cy}
+        r={DOT_RADIUS}
+        fill={payload.isToday ? "var(--card)" : color}
+        stroke={payload.isToday ? color : "var(--card)"}
+        strokeWidth={2}
+      />
+    );
+  };
+
+  /** The dotted segment draws only today's hollow dot; yesterday's is on the solid line. */
+  const renderTodayDot = (props: DotProps) =>
+    props.payload?.isToday ? renderDot(props) : <g key={`today-dot-${props.index}`} />;
+
+  return (
+    // The chart is a coordinate system, not prose: it stays an LTR island.
+    // rtl-ok: deliberate LTR island (chart)
+    <div className={className} dir="ltr">
+      {/* The points, exposed for assertions and for screen readers that would
+          otherwise get nothing from the SVG. */}
+      <span className="sr-only" data-testid={`analytics-daily-${metric}-data`}>
+        {JSON.stringify(points)}
+      </span>
+
+      <ChartContainer config={chartConfig} className="aspect-auto h-72 w-full">
+        <LineChart accessibilityLayer data={chartData} margin={{ top: 8, right: 16, bottom: 0, left: 0 }}>
+          <CartesianGrid vertical={false} />
+          <XAxis
+            dataKey="day"
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            minTickGap={16}
+            tickFormatter={(value: string) => bucketDate(value, "day")}
+          />
+          <YAxis
+            domain={[0, "auto"]}
+            allowDecimals={false}
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            width={48}
+            tickFormatter={(value: number) => compact(value)}
+          />
+          <ChartTooltip
+            // Keep a null day in the payload so the tooltip can say "no data".
+            filterNull={false}
+            content={
+              <ChartTooltipContent
+                labelFormatter={(value, payload) => {
+                  const entry = payload?.[0]?.payload as DailyUniquesEntry | undefined;
+                  return (
+                    <>
+                      {bucketDate(String(value), "day")}
+                      {entry?.isToday && (
+                        <div className="text-muted-foreground text-xs">{t("analytics.admin.daily_uniques.today")}</div>
+                      )}
+                    </>
+                  );
+                }}
+                // The row's own value, not the hovered series': on today's
+                // point the solid line is null while the dotted one holds it.
+                formatter={(_value, _name, item) => {
+                  const entry = item.payload as DailyUniquesEntry;
+                  return (
+                    <div className="flex flex-1 justify-between gap-4 leading-none">
+                      <span className="text-muted-foreground">{seriesLabel}</span>
+                      <span className="text-xs tabular-nums text-end">
+                        {entry.value === null ? t("analytics.admin.daily_uniques.no_data") : decimal(entry.value, 0)}
+                      </span>
+                    </div>
+                  );
+                }}
+              />
+            }
+          />
+          <Line
+            dataKey="line"
+            type="linear"
+            stroke={color}
+            strokeWidth={2}
+            connectNulls={false}
+            dot={renderDot}
+            activeDot={{ r: DOT_RADIUS, strokeWidth: 2, stroke: "var(--card)" }}
+            isAnimationActive={false}
+          />
+          <Line
+            dataKey="todayLine"
+            type="linear"
+            stroke={color}
+            strokeWidth={2}
+            strokeDasharray="2 5"
+            connectNulls={false}
+            dot={renderTodayDot}
+            activeDot={false}
+            tooltipType="none"
+            legendType="none"
+            isAnimationActive={false}
+          />
+        </LineChart>
+      </ChartContainer>
+    </div>
+  );
+}

package/src/features/analytics/components/__tests__/AnalyticsDailyUniquesChart.spec.tsx

@@ -0,0 +1,88 @@
+import { render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AnalyticsDailyUniquesChart, buildDailyUniquesSeries } from "../AnalyticsDailyUniquesChart";
+
+const row = (day: string, visitors: number | null, users: number | null) =>
+  ({
+    id: day,
+    day: new Date(day),
+    visitors,
+    users,
+  }) as any;
+
+const ROWS = [row("2026-11-01", 5, 2), row("2026-11-02", 3, null), row("2026-11-03", 0, 0), row("2026-11-04", 4, 1)];
+
+describe("AnalyticsDailyUniquesChart", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ toFake: ["Date"] });
+    vi.setSystemTime(new Date("2026-11-04T10:00:00Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("exposes one visitors point per row, in order", () => {
+    render(<AnalyticsDailyUniquesChart rows={ROWS} metric="visitors" />);
+
+    const data = JSON.parse(screen.getByTestId("analytics-daily-visitors-data").textContent!);
+    expect(data).toEqual([
+      { day: "2026-11-01", value: 5 },
+      { day: "2026-11-02", value: 3 },
+      { day: "2026-11-03", value: 0 },
+      { day: "2026-11-04", value: 4 },
+    ]);
+  });
+
+  it("exposes one users point per row, keeping null as null and 0 as 0", () => {
+    render(<AnalyticsDailyUniquesChart rows={ROWS} metric="users" />);
+
+    const data = JSON.parse(screen.getByTestId("analytics-daily-users-data").textContent!);
+    expect(data).toEqual([
+      { day: "2026-11-01", value: 2 },
+      { day: "2026-11-02", value: null },
+      { day: "2026-11-03", value: 0 },
+      { day: "2026-11-04", value: 1 },
+    ]);
+  });
+
+  it("renders the empty state without a data node when there are no rows", () => {
+    render(<AnalyticsDailyUniquesChart rows={[]} metric="visitors" />);
+
+    expect(screen.queryByTestId("analytics-daily-visitors-data")).not.toBeInTheDocument();
+    expect(screen.getByText("analytics.admin.no_data")).toBeInTheDocument();
+  });
+
+  it("draws the chart, not the empty state, when every day is zero", () => {
+    render(<AnalyticsDailyUniquesChart rows={[row("2026-11-03", 0, 0), row("2026-11-04", 0, 0)]} metric="users" />);
+
+    expect(screen.getByTestId("analytics-daily-users-data")).toBeInTheDocument();
+    expect(screen.queryByText("analytics.admin.no_data")).not.toBeInTheDocument();
+  });
+});
+
+describe("buildDailyUniquesSeries", () => {
+  it("moves the yesterday-to-today segment onto the dotted series when both days have values", () => {
+    const series = buildDailyUniquesSeries(ROWS, "visitors", "2026-11-04");
+
+    expect(series.map((entry) => entry.line)).toEqual([5, 3, 0, null]);
+    expect(series.map((entry) => entry.todayLine)).toEqual([null, null, 0, 4]);
+    expect(series.map((entry) => entry.isToday)).toEqual([false, false, false, true]);
+  });
+
+  it("draws no dotted segment when yesterday is unknown, and leaves null days as gaps", () => {
+    const rows = [row("2026-11-03", 2, null), row("2026-11-04", 4, 1)];
+    const series = buildDailyUniquesSeries(rows, "users", "2026-11-04");
+
+    expect(series.map((entry) => entry.line)).toEqual([null, 1]);
+    expect(series.map((entry) => entry.todayLine)).toEqual([null, null]);
+    expect(series[1].isToday).toBe(true);
+  });
+
+  it("draws no dotted segment when the range ends before today", () => {
+    const series = buildDailyUniquesSeries(ROWS.slice(0, 3), "visitors", "2026-11-04");
+
+    expect(series.map((entry) => entry.line)).toEqual([5, 3, 0]);
+    expect(series.every((entry) => entry.todayLine === null && !entry.isToday)).toBe(true);
+  });
+});

package/src/features/analytics/components/__tests__/AnalyticsPageContainers.spec.tsx

@@ -11,6 +11,7 @@ vi.mock("../../data/AnalyticsAdminService", () => ({
     getTimeline: vi.fn(),
     getBreakdown: vi.fn(),
     getSessions: vi.fn(),
+    getDailyUniques: vi.fn(),
     getSession: vi.fn(),
     getSessionPageViews: vi.fn(),
     next: vi.fn(),
@@ -89,6 +90,27 @@ describe("AnalyticsAdminPageContainer", () => {
     vi.mocked(AnalyticsAdminService.getTimeline).mockResolvedValue([]);
     vi.mocked(AnalyticsAdminService.getBreakdown).mockResolvedValue([]);
     vi.mocked(AnalyticsAdminService.getSessions).mockResolvedValue([session("s1", "2026-10-01T10:00:00.000Z")]);
+    vi.mocked(AnalyticsAdminService.getDailyUniques).mockResolvedValue([]);
+  });
+
+  it("renders the daily visitors and users cards between Over time and Breakdown", async () => {
+    render(<AnalyticsAdminPageContainer />);
+
+    const visitorsCard = await screen.findByTestId("analytics-daily-visitors-card");
+    const usersCard = screen.getByTestId("analytics-daily-users-card");
+    expect(visitorsCard).toHaveTextContent("analytics.admin.panels.daily_visitors");
+    expect(usersCard).toHaveTextContent("analytics.admin.panels.daily_users");
+
+    const overTime = screen.getByText("analytics.admin.panels.over_time");
+    const breakdown = screen.getByText("analytics.admin.panels.breakdown");
+    const follows = (a: Node, b: Node) => Boolean(a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING);
+
+    expect(follows(overTime, visitorsCard)).toBe(true);
+    expect(follows(visitorsCard, usersCard)).toBe(true);
+    expect(follows(usersCard, breakdown)).toBe(true);
+    expect(overTime.closest('[data-slot="card"]')?.nextElementSibling).toBe(visitorsCard);
+    expect(visitorsCard.nextElementSibling).toBe(usersCard);
+    expect(usersCard.nextElementSibling).toBe(breakdown.closest('[data-slot="card"]'));
   });
 
   it("loads the dashboard and links each session under the given sessionPageUrl", async () => {

package/src/features/analytics/contexts/AnalyticsAdminContext.tsx

@@ -2,11 +2,12 @@
 
 import { useTranslations } from "next-intl";
 import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
-import { Modules, NextRef } from "../../../core";
+import { formatLocalDate, Modules, NextRef } from "../../../core";
 import { SharedProvider } from "../../../contexts";
 import { BreadcrumbItemData } from "../../../interfaces";
 import { AnalyticsAdminFilterBar } from "../components/AnalyticsAdminFilterBar";
 import type { AnalyticsBreakdownInterface } from "../data/analytics-breakdown.interface";
+import type { AnalyticsDailyUniqueTimelineInterface } from "../data/analytics-daily-unique-timeline.interface";
 import type { AnalyticsSessionInterface } from "../data/analytics-session.interface";
 import type { AnalyticsSummaryInterface } from "../data/analytics-summary.interface";
 import type { AnalyticsTimelineInterface } from "../data/analytics-timeline.interface";
@@ -51,6 +52,8 @@ export interface AnalyticsAdminContextType {
   timeline: AnalyticsTimelineInterface[];
   breakdowns: Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>;
   sessions: AnalyticsSessionInterface[];
+  /** One row per day of the range: unique visitors and users, never filtered by section. */
+  dailyUniques: AnalyticsDailyUniqueTimelineInterface[];
   filters: AnalyticsAdminFilterState;
   /** Merges a partial patch into the current filters; every key is optional. */
   setFilters: (next: Partial<AnalyticsAdminFilterState>) => void;
@@ -120,6 +123,7 @@ export const AnalyticsAdminProvider = ({
   const [breakdowns, setBreakdowns] =
     useState<Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>>(EMPTY_BREAKDOWNS);
   const [sessions, setSessions] = useState<AnalyticsSessionInterface[]>([]);
+  const [dailyUniques, setDailyUniques] = useState<AnalyticsDailyUniqueTimelineInterface[]>([]);
   /** The cursor URL of the next sessions page, as the API returned it. */
   const [sessionsNextPage, setSessionsNextPage] = useState<string | undefined>(undefined);
   const [isLoading, setIsLoading] = useState(true);
@@ -149,8 +153,14 @@ export const AnalyticsAdminProvider = ({
         ),
       ),
       AnalyticsAdminService.getSessions({ ...base, next: sessionsNext }),
+      // The local calendar days the admin picked: the picker emits local-midnight
+      // instants, so slicing the UTC instant would shift the range a day east of UTC.
+      AnalyticsAdminService.getDailyUniques({
+        fromDate: formatLocalDate(new Date(from)),
+        toDate: formatLocalDate(new Date(to)),
+      }),
     ])
-      .then(([nextSummary, nextTimeline, nextBreakdowns, nextSessions]) => {
+      .then(([nextSummary, nextTimeline, nextBreakdowns, nextSessions, nextDailyUniques]) => {
         if (cancelled) return;
         setSummary(nextSummary ?? []);
         setTimeline(nextTimeline ?? []);
@@ -161,6 +171,7 @@ export const AnalyticsAdminProvider = ({
         );
         setSessions(nextSessions ?? []);
         setSessionsNextPage(sessionsNext.next);
+        setDailyUniques(nextDailyUniques ?? []);
       })
       .catch((err) => {
         if (cancelled) return;
@@ -225,6 +236,7 @@ export const AnalyticsAdminProvider = ({
       timeline,
       breakdowns,
       sessions,
+      dailyUniques,
       filters,
       setFilters,
       loadMoreSessions,
@@ -238,6 +250,7 @@ export const AnalyticsAdminProvider = ({
       timeline,
       breakdowns,
       sessions,
+      dailyUniques,
       filters,
       setFilters,
       loadMoreSessions,