Explain this metric

MetricDefinition.tsxThe definition as four required fields behind an info affordance on the tile: counted, window, excluded, owner.Copy

import { useState } from "react";
import { Info } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";

/**
 * Four fields, all required. A definition is not a sentence; it is what is
 * counted, over what window, with what left out, and who to argue with. Leave
 * any one out and two honest readers of the tile will still disagree.
 */
export type Definition = {
  /** In the reader's words, not the column name. */
  counts: string;
  window: string;
  excludes: string;
  /** A team or a person. A definition nobody owns is one nobody can correct. */
  owner: string;
};

type Props = {
  label: string;
  value: string;
  /** The window the tile shows, which the definition should agree with. */
  range: string;
  definition: Definition;
  onOwnerClick: (owner: string) => void;
  /** Start with the definition showing, as when the tile is the exhibit. */
  defaultOpen?: boolean;
};

export function MetricDefinition({ label, value, range, definition, onOwnerClick, defaultOpen = false }: Props) {
  const [open, setOpen] = useState(defaultOpen);
  const rows: [string, string][] = [
    ["Counts", definition.counts],
    ["Window", definition.window],
    ["Excludes", definition.excludes],
  ];

  return (
    <Card className="w-[220px] p-4">
      {/* A div, not a p: the popover renders inline here in the preview, and
          block content inside a paragraph splits it. */}
      <div className="flex items-center gap-1.5 text-xs uppercase tracking-wide text-muted-foreground">
        {label}
        {/* Non-modal: a definition should not lock the dashboard behind it. */}
        <Popover open={open} onOpenChange={setOpen} modal={false}>
          <PopoverTrigger asChild>
            <Button variant="ghost" size="icon" className="size-5 rounded-full" aria-label={`What ${label} means`}>
              <Info className="size-3.5" />
            </Button>
          </PopoverTrigger>
          <PopoverContent side="right" align="start" className="w-[360px] normal-case tracking-normal">
            <p className="border-b pb-2 text-sm text-popover-foreground">{label}</p>
            <dl className="mt-3 grid grid-cols-[76px_1fr] gap-x-3 gap-y-3 text-xs">
              {rows.map(([k, v]) => (
                <div key={k} className="contents">
                  <dt className="text-muted-foreground">{k}</dt>
                  <dd className="m-0 text-popover-foreground">{v}</dd>
                </div>
              ))}
            </dl>
            <p className="mt-3 flex items-center gap-2 border-t pt-2.5 text-xs text-muted-foreground">
              Owned by
              <button type="button" onClick={() => onOwnerClick(definition.owner)}
                className="rounded-full border px-2 py-0.5 text-popover-foreground hover:bg-muted">
                {definition.owner}
              </button>
            </p>
          </PopoverContent>
        </Popover>
      </div>
      <p className="mt-3 text-3xl font-medium tabular-nums text-card-foreground">{value}</p>
      <p className="mt-2 text-xs text-muted-foreground">{range}</p>
    </Card>
  );
}

demo.tsxHow it is called: Active users over seven days, opened on arrival.Copy

import { MetricDefinition } from "./MetricDefinition";

/**
 * The tile with its definition already open, since the definition is the
 * thing being shown. The owner chip is where a disagreement goes.
 */
export default function Demo() {
  return (
    <div className="min-h-[240px]">
      <MetricDefinition
        label="Active users"
        value="42,109"
        range="Last 7 days"
        definition={{
          counts: "Anyone who made at least one authenticated request. Not sessions, not page views.",
          window: "A rolling seven days, recomputed hourly.",
          excludes: "Internal staff accounts, known bots, and anything from the test tenant.",
          owner: "growth-analytics",
        }}
        onOwnerClick={() => {}}
        defaultOpen
      />
    </div>
  );
}