@carlonicora/nextjs-jsonapi 3.24.2 → 3.26.0

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

@@ -0,0 +1,97 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { RoundPageContainer } from "../../../components";
+import { Card, CardContent, CardHeader, CardTitle } from "../../../shadcnui";
+import { useAnalyticsAdmin } from "../contexts/AnalyticsAdminContext";
+import { AnalyticsAdminTiles } from "./AnalyticsAdminTiles";
+import { AnalyticsBreakdownTable } from "./AnalyticsBreakdownTable";
+import { AnalyticsSessionsTable } from "./AnalyticsSessionsTable";
+import { AnalyticsTimelineChart } from "./AnalyticsTimelineChart";
+
+/**
+ * Page body for the administrative analytics dashboard.
+ *
+ * Stateless by design — every value it renders comes from
+ * `useAnalyticsAdmin()`. The filter bar is deliberately NOT here: it belongs to
+ * the page title bar, which `RoundPageContainer` fills from `SharedContext`, so
+ * the provider publishes it (see AnalyticsAdminContext).
+ */
+export function AnalyticsAdminContainer() {
+  const t = useTranslations();
+  const {
+    summary,
+    timeline,
+    breakdowns,
+    sessions,
+    loadMoreSessions,
+    hasMoreSessions,
+    sessionPageUrl,
+    isLoading,
+    error,
+  } = useAnalyticsAdmin();
+
+  if (error) {
+    return (
+      <RoundPageContainer fullWidth forceHeader>
+        <div className="p-4">
+          <Card>
+            <CardContent>
+              <p className="text-destructive text-xs/relaxed">{error}</p>
+            </CardContent>
+          </Card>
+        </div>
+      </RoundPageContainer>
+    );
+  }
+
+  // Loading renders nothing in the body: the title bar (with the filter bar) is
+  // already mounted, so a spinner would only make the controls jump on arrival.
+  if (isLoading) return <RoundPageContainer fullWidth forceHeader />;
+
+  return (
+    <RoundPageContainer fullWidth forceHeader>
+      <div className="flex w-full flex-col gap-4 p-4">
+        <div className="flex flex-col gap-2">
+          <AnalyticsAdminTiles summary={summary} />
+          {/* Days past the raw-event retention are served from daily summaries.
+              Whether the window reaches them is the backend's knowledge, not the
+              client's, so the caption is always shown. */}
+          <p className="text-muted-foreground text-xs">{t("analytics.admin.tiles.summarised_note")}</p>
+        </div>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t("analytics.admin.panels.over_time")}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <AnalyticsTimelineChart rows={timeline} />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t("analytics.admin.panels.breakdown")}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <AnalyticsBreakdownTable breakdowns={breakdowns} />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>{t("analytics.admin.panels.sessions")}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <AnalyticsSessionsTable
+              rows={sessions}
+              sessionPageUrl={sessionPageUrl}
+              onLoadMore={loadMoreSessions}
+              hasMore={hasMoreSessions}
+            />
+          </CardContent>
+        </Card>
+      </div>
+    </RoundPageContainer>
+  );
+}

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

@@ -0,0 +1,120 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { DateRangeSelector } from "../../../components/forms/DateRangeSelector";
+import { Button } from "../../../shadcnui";
+import { cn } from "../../../utils";
+import {
+  ANALYTICS_GRANULARITIES,
+  ANALYTICS_SECTIONS,
+  type AnalyticsGranularity,
+  type AnalyticsSection,
+} from "../data/analytics.types";
+
+type FilterState = {
+  from: string;
+  to: string;
+  section: AnalyticsSection;
+  granularity: AnalyticsGranularity;
+};
+
+type Props = FilterState & {
+  /** Receives ONLY the keys that changed. */
+  onChange: (next: Partial<FilterState>) => void;
+};
+
+/**
+ * The single control row above the KPI tiles.
+ *
+ * It is deliberately stateless: every control reports the one key it changed and
+ * the owning context re-fetches. Keeping the whole filter state in one place is
+ * what lets the page issue a single coordinated batch of requests instead of one
+ * per control.
+ */
+export function AnalyticsAdminFilterBar({ section, granularity, onChange }: Props) {
+  const t = useTranslations();
+
+  const sectionLabels: Record<AnalyticsSection, string> = {
+    all: t("analytics.admin.filter.section_all"),
+    public: t("analytics.admin.filter.section_public"),
+    app: t("analytics.admin.filter.section_app"),
+  };
+
+  const granularityLabels: Record<AnalyticsGranularity, string> = {
+    day: t("analytics.admin.filter.granularity_day"),
+    week: t("analytics.admin.filter.granularity_week"),
+    month: t("analytics.admin.filter.granularity_month"),
+  };
+
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      {/* The date button is a fixed 300px; on a phone it takes the full row instead. */}
+      <div className="max-md:w-full max-md:[&_#date]:w-full">
+        <DateRangeSelector
+          onDateChange={(range) => {
+            if (!range?.from || !range?.to) return;
+            onChange({ from: range.from.toISOString(), to: range.to.toISOString() });
+          }}
+        />
+      </div>
+
+      <Segmented
+        ariaLabel={t("analytics.admin.filter.section")}
+        value={section}
+        options={ANALYTICS_SECTIONS.map((value) => ({ value, label: sectionLabels[value] }))}
+        onSelect={(value) => onChange({ section: value })}
+      />
+
+      <Segmented
+        ariaLabel={t("analytics.admin.filter.granularity")}
+        value={granularity}
+        options={ANALYTICS_GRANULARITIES.map((value) => ({ value, label: granularityLabels[value] }))}
+        onSelect={(value) => onChange({ granularity: value })}
+      />
+    </div>
+  );
+}
+
+/**
+ * A segmented control built from plain Buttons.
+ *
+ * The design system has no ToggleGroup primitive, and Base UI triggers may never
+ * wrap a Button, so the segmented look is composed from Buttons directly — the
+ * selected segment takes the solid variant, the rest stay ghosts.
+ */
+function Segmented<T extends string>({
+  ariaLabel,
+  value,
+  options,
+  onSelect,
+}: {
+  ariaLabel: string;
+  value: T;
+  options: { value: T; label: string }[];
+  onSelect: (value: T) => void;
+}) {
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel}
+      className="border-border inline-flex items-center gap-0.5 rounded-md border p-0.5"
+    >
+      {options.map((option) => {
+        const selected = option.value === value;
+        return (
+          <Button
+            key={option.value}
+            type="button"
+            size="sm"
+            variant={selected ? "default" : "ghost"}
+            aria-pressed={selected}
+            className={cn(!selected && "text-muted-foreground")}
+            onClick={() => onSelect(option.value)}
+          >
+            {option.label}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,25 @@
+"use client";
+
+import { AnalyticsAdminProvider } from "../contexts/AnalyticsAdminContext";
+import { AnalyticsAdminContainer } from "./AnalyticsAdminContainer";
+
+type Props = {
+  /** Route the breadcrumb links back to. Defaults to the provider's default. */
+  pageUrl?: string;
+  /** Base route of the journey page each session row links to. */
+  sessionPageUrl?: string;
+};
+
+/**
+ * The whole administrative analytics page as one client component, so a host
+ * app's server page renders a single element. `AnalyticsAdminContainer` owns
+ * the `RoundPageContainer`; the provider sits above it because it publishes the
+ * filter bar into the title bar.
+ */
+export function AnalyticsAdminPageContainer({ pageUrl, sessionPageUrl }: Props) {
+  return (
+    <AnalyticsAdminProvider pageUrl={pageUrl} sessionPageUrl={sessionPageUrl}>
+      <AnalyticsAdminContainer />
+    </AnalyticsAdminProvider>
+  );
+}

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

@@ -0,0 +1,191 @@
+"use client";
+
+import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { MicroLabel } from "../../../components";
+import { Card, CardContent } from "../../../shadcnui";
+import { cn } from "../../../utils";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import { percentageDelta } from "../../tokenusage/lib/metrics";
+import type { AnalyticsSummaryInterface } from "../data/analytics-summary.interface";
+
+type Props = {
+  /** The six summary rows: {public, app, total} × {current, previous}. */
+  summary: AnalyticsSummaryInterface[];
+};
+
+type SummaryMetrics = Pick<
+  AnalyticsSummaryInterface,
+  "visitors" | "sessions" | "pageViews" | "pagesPerSession" | "consentShare"
+>;
+
+const ZERO: SummaryMetrics = { visitors: 0, sessions: 0, pageViews: 0, pagesPerSession: 0, consentShare: 0 };
+
+/**
+ * The KPI header of the administrative analytics page.
+ *
+ * Three lead tiles carry the traffic volumes — visitors, sessions, page views —
+ * each with its delta against the equal-length preceding window. Two supporting
+ * tiles below carry the ratios that give those numbers context.
+ *
+ * The tiles read the `total` row: the backend already applies the section filter
+ * to it, so it is the figure for whatever the filter bar selected. The backend
+ * always returns both windows, which is why no tile has to branch on a missing
+ * row: an absent one is simply zero-filled here.
+ */
+export function AnalyticsAdminTiles({ summary }: Props) {
+  const t = useTranslations();
+  const { decimal } = useUsageFormatters();
+
+  const rowFor = (window: string): SummaryMetrics =>
+    summary.find((r) => r.section === "total" && r.window === window) ?? ZERO;
+
+  const current = rowFor("current");
+  const previous = rowFor("previous");
+
+  const previousLabel = t("analytics.admin.tiles.vs_previous");
+
+  return (
+    <div className="grid gap-3">
+      <div className="grid gap-3 sm:grid-cols-3">
+        <LeadTile
+          testId="analytics-tile-visitors"
+          label={t("analytics.admin.tiles.visitors")}
+          value={decimal(current.visitors, 0)}
+          delta={percentageDelta(current.visitors, previous.visitors)}
+          previousLabel={previousLabel}
+          decimal={decimal}
+        />
+        <LeadTile
+          testId="analytics-tile-sessions"
+          label={t("analytics.admin.tiles.sessions")}
+          value={decimal(current.sessions, 0)}
+          delta={percentageDelta(current.sessions, previous.sessions)}
+          previousLabel={previousLabel}
+          decimal={decimal}
+        />
+        <LeadTile
+          testId="analytics-tile-page-views"
+          label={t("analytics.admin.tiles.page_views")}
+          value={decimal(current.pageViews, 0)}
+          delta={percentageDelta(current.pageViews, previous.pageViews)}
+          previousLabel={previousLabel}
+          decimal={decimal}
+        />
+      </div>
+
+      <div className="grid gap-3 sm:grid-cols-2">
+        <SupportingTile
+          testId="analytics-tile-pages-per-session"
+          label={t("analytics.admin.tiles.pages_per_session")}
+          value={decimal(current.pagesPerSession, 1)}
+          delta={percentageDelta(current.pagesPerSession, previous.pagesPerSession)}
+          decimal={decimal}
+        />
+        <SupportingTile
+          testId="analytics-tile-consent-share"
+          label={t("analytics.admin.tiles.consent_share")}
+          // consentShare is a 0..1 ratio on the wire.
+          value={`${decimal(current.consentShare * 100, 0)}%`}
+          decimal={decimal}
+        />
+      </div>
+    </div>
+  );
+}
+
+function LeadTile({
+  testId,
+  label,
+  value,
+  delta,
+  previousLabel,
+  decimal,
+}: {
+  testId: string;
+  label: string;
+  value: string;
+  delta: number | undefined;
+  previousLabel: string;
+  /** Passed down because `Delta` is a plain function, not a component: it cannot call the hook itself. */
+  decimal: (value: number, decimals: number) => string;
+}) {
+  return (
+    <Card data-testid={testId}>
+      <CardContent className="grid gap-1">
+        <MicroLabel>{label}</MicroLabel>
+        <span className="text-primary text-xl font-semibold tabular-nums">{value}</span>
+        <span className="flex items-center gap-1">
+          <Delta testId={`${testId}-delta`} delta={delta} decimal={decimal} />
+          <span className="text-muted-foreground text-xs">{previousLabel}</span>
+        </span>
+      </CardContent>
+    </Card>
+  );
+}
+
+function SupportingTile({
+  testId,
+  label,
+  value,
+  delta,
+  decimal,
+}: {
+  testId: string;
+  label: string;
+  value: string;
+  delta?: number | undefined;
+  /** Passed down because `Delta` is a plain function, not a component: it cannot call the hook itself. */
+  decimal: (value: number, decimals: number) => string;
+}) {
+  return (
+    <Card data-testid={testId} size="sm">
+      <CardContent className="grid gap-1">
+        <MicroLabel>{label}</MicroLabel>
+        <span className="flex items-center gap-2">
+          <span className="text-sm font-medium tabular-nums">{value}</span>
+          {delta !== undefined && <Delta testId={`${testId}-delta`} delta={delta} decimal={decimal} />}
+        </span>
+      </CardContent>
+    </Card>
+  );
+}
+
+/**
+ * The delta slot. An undefined delta means the previous window was zero: an
+ * em dash says "not comparable" where a percentage would say "infinite growth".
+ */
+function Delta({
+  testId,
+  delta,
+  decimal,
+}: {
+  testId: string;
+  delta: number | undefined;
+  decimal: (value: number, decimals: number) => string;
+}) {
+  if (delta === undefined) {
+    return (
+      <span data-testid={testId} className="text-muted-foreground text-xs">
+        —
+      </span>
+    );
+  }
+
+  const increased = delta >= 0;
+  const Icon = increased ? ArrowUpIcon : ArrowDownIcon;
+  const sign = delta > 0 ? "+" : delta < 0 ? "-" : "";
+
+  return (
+    <span
+      data-testid={testId}
+      className={cn(
+        "inline-flex items-center gap-0.5 text-xs tabular-nums",
+        increased ? "text-success" : "text-destructive",
+      )}
+    >
+      <Icon aria-hidden className="size-3" />
+      {`${sign}${decimal(Math.abs(delta), 0)}%`}
+    </span>
+  );
+}

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

@@ -0,0 +1,105 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from "../../../shadcnui";
+import { useUsageFormatters } from "../../tokenusage/lib/formatters";
+import type { AnalyticsBreakdownInterface } from "../data/analytics-breakdown.interface";
+import { ANALYTICS_DIMENSIONS, type AnalyticsDimension } from "../data/analytics.types";
+
+type Props = {
+  breakdowns: Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>;
+};
+
+/** The key the repository folds the tail past the limit into. */
+const OTHER_KEY = "other";
+
+/**
+ * Attribution and content breakdowns, one tab per dimension.
+ *
+ * Each tab is the same four-column table — key, visitors, sessions, page views —
+ * sorted by visitors. Sorting is client-side because the whole ranked set is
+ * already in memory, so a round trip would buy nothing. Keys are data, not
+ * vocabulary: `(none)` and the routes are rendered as the backend wrote them;
+ * only the `other` rollup is translated.
+ */
+export function AnalyticsBreakdownTable({ breakdowns }: Props) {
+  const t = useTranslations();
+
+  const labels: Record<AnalyticsDimension, string> = {
+    source: t("analytics.admin.dimensions.source"),
+    medium: t("analytics.admin.dimensions.medium"),
+    campaign: t("analytics.admin.dimensions.campaign"),
+    referrer: t("analytics.admin.dimensions.referrer"),
+    route: t("analytics.admin.dimensions.route"),
+    landing: t("analytics.admin.dimensions.landing"),
+  };
+
+  return (
+    <Tabs defaultValue={ANALYTICS_DIMENSIONS[0]}>
+      {/* Six tabs are wider than a phone-width card: scroll them sideways there. */}
+      <TabsList className="max-md:w-full max-md:justify-start max-md:overflow-x-auto">
+        {ANALYTICS_DIMENSIONS.map((dimension) => (
+          <TabsTrigger key={dimension} value={dimension}>
+            {labels[dimension]}
+          </TabsTrigger>
+        ))}
+      </TabsList>
+      {ANALYTICS_DIMENSIONS.map((dimension) => (
+        <TabsContent key={dimension} value={dimension}>
+          <BreakdownRows rows={breakdowns[dimension] ?? []} />
+        </TabsContent>
+      ))}
+    </Tabs>
+  );
+}
+
+function BreakdownRows({ rows }: { rows: AnalyticsBreakdownInterface[] }) {
+  const t = useTranslations();
+  const { decimal } = useUsageFormatters();
+
+  const sortedRows = useMemo(() => [...rows].sort((a, b) => b.visitors - a.visitors), [rows]);
+
+  if (sortedRows.length === 0) {
+    return <p className="text-muted-foreground text-sm">{t("analytics.admin.no_data")}</p>;
+  }
+
+  return (
+    // The package's <Table> wraps itself in an `overflow-x-clip` container, which
+    // would swallow the overflow before this scroller ever saw it — hence the
+    // child override. Wide tables must scroll, never widen the page.
+    <div className="overflow-x-auto [&_[data-slot=table-container]]:overflow-x-visible">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead className="text-xs font-medium">{t("analytics.admin.columns.key")}</TableHead>
+            <TableHead className="text-end text-xs font-medium">{t("analytics.admin.columns.visitors")}</TableHead>
+            <TableHead className="text-end text-xs font-medium">{t("analytics.admin.columns.sessions")}</TableHead>
+            <TableHead className="text-end text-xs font-medium">{t("analytics.admin.columns.page_views")}</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {sortedRows.map((row) => (
+            <TableRow key={row.id} data-testid={`analytics-breakdown-row-${row.id}`}>
+              <TableCell className="text-xs">{row.key === OTHER_KEY ? t("analytics.admin.other") : row.key}</TableCell>
+              <TableCell className="text-end text-xs tabular-nums">{decimal(row.visitors, 0)}</TableCell>
+              <TableCell className="text-end text-xs tabular-nums">{decimal(row.sessions, 0)}</TableCell>
+              <TableCell className="text-end text-xs tabular-nums">{decimal(row.pageViews, 0)}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}