{"$schema":"https:\/\/ui.particle.academy\/schema\/registry-item.json","name":"referral-stats","type":"registry:ui","title":"ReferralStats","description":"Referral scans, unique visitors, signups and conversion per code, scope or member \u2014 a bar chart of one metric over a table of all four, fed the engines' stats() rows as-is. Fully controlled, with data-mlm-* handles.","package":"fancy-mlm-ui","dependencies":["@particle-academy\/react-fancy"],"registryDependencies":[],"files":[{"path":"components\/fancy\/referral-stats\/ReferralStats.tsx","content":"import { cn, Button, Card, Chart, DatePicker, MultiSwitch, Table, Text } from \"@particle-academy\/react-fancy\";\nimport { formatRate as defaultFormatRate, statsChartData, summarizeStats } from \".\/stats\";\nimport type { ReferralStatRow, ReferralStatsGroupBy, ReferralStatsMetric, ReferralStatsRange } from \".\/types\";\n\nexport interface ReferralStatsProps {\n  \/** Stats rows (controlled), as the engines' `stats()` returns them. *\/\n  rows: ReferralStatRow[];\n  \/** What the rows are grouped by (controlled). Shown as a switch only when `onGroupByChange` is set. *\/\n  groupBy?: ReferralStatsGroupBy;\n  onGroupByChange?: (groupBy: ReferralStatsGroupBy) => void;\n  \/** Which figure the chart plots (controlled). Default `signups`. *\/\n  metric?: ReferralStatsMetric;\n  onMetricChange?: (metric: ReferralStatsMetric) => void;\n  \/** The range the rows cover, `YYYY-MM-DD` (controlled). Shown as a picker only when `onRangeChange` is set. *\/\n  range?: ReferralStatsRange;\n  onRangeChange?: (range: ReferralStatsRange) => void;\n  \/** Highlighted row (controlled). *\/\n  selectedKey?: string | null;\n  onSelect?: (key: string, row: ReferralStatRow) => void;\n  \/**\n   * Ungrouped totals from the engine. Without them, scans and signups are\n   * summed and unique sessions and conversion are left blank, because they\n   * cannot be summed honestly.\n   *\/\n  totals?: Omit<ReferralStatRow, \"key\" | \"label\">;\n  \/** Column heading for the key. Default from `groupBy`. *\/\n  keyLabel?: string;\n  formatRate?: (rate: number) => string;\n  emptyLabel?: string;\n  className?: string;\n}\n\nconst GROUPS: Array<{ value: ReferralStatsGroupBy; label: string }> = [\n  { value: \"code\", label: \"Code\" },\n  { value: \"scope\", label: \"Scope\" },\n  { value: \"member\", label: \"Member\" },\n];\n\nconst METRICS: Array<{ value: ReferralStatsMetric; label: string }> = [\n  { value: \"scans\", label: \"Scans\" },\n  { value: \"uniqueSessions\", label: \"Visitors\" },\n  { value: \"signups\", label: \"Signups\" },\n  { value: \"conversionRate\", label: \"Conversion\" },\n];\n\nconst COLUMNS: Array<{ stat: ReferralStatsMetric; label: string }> = [\n  { stat: \"scans\", label: \"Scans\" },\n  { stat: \"uniqueSessions\", label: \"Visitors\" },\n  { stat: \"signups\", label: \"Signups\" },\n  { stat: \"conversionRate\", label: \"Conversion\" },\n];\n\n\/**\n * Referral conversion stats per code, scope or member: a bar chart of one\n * metric over a table of all four.\n *\n * Human+: every piece of state is a controlled prop, the state is mirrored on\n * the root as `data-mlm-*` attributes, every cell carries\n * `data-mlm-stat-key` + `data-mlm-stat`, and each control sits in a\n * `data-mlm-control` wrapper, so an agent reads and drives it without guessing\n * at the DOM.\n *\/\nexport function ReferralStats({\n  rows,\n  groupBy = \"code\",\n  onGroupByChange,\n  metric = \"signups\",\n  onMetricChange,\n  range,\n  onRangeChange,\n  selectedKey = null,\n  onSelect,\n  totals,\n  keyLabel,\n  formatRate = defaultFormatRate,\n  emptyLabel = \"No referral activity in this range.\",\n  className,\n}: ReferralStatsProps) {\n  const summed = summarizeStats(rows);\n  const show = (stat: ReferralStatsMetric, row: Pick<ReferralStatRow, ReferralStatsMetric>) =>\n    stat === \"conversionRate\" ? formatRate(row.conversionRate) : row[stat].toLocaleString();\n  const total = (stat: ReferralStatsMetric): string => {\n    if (totals) return show(stat, totals);\n    if (stat === \"scans\" || stat === \"signups\") return summed[stat].toLocaleString();\n    return \"\u2014\";\n  };\n\n  return (\n    <Card\n      variant=\"outlined\"\n      padding=\"md\"\n      data-fancy-mlm=\"referral-stats\"\n      data-mlm-group-by={groupBy}\n      data-mlm-metric={metric}\n      data-mlm-range-from={range?.from}\n      data-mlm-range-to={range?.to}\n      data-mlm-selected-key={selectedKey ?? undefined}\n      data-mlm-empty={rows.length === 0 ? \"true\" : undefined}\n      className={cn(\"fancy-mlm-stats\", className)}\n    >\n      {onGroupByChange || onMetricChange || onRangeChange ? (\n        <div className=\"fancy-mlm-stats__controls\">\n          {onGroupByChange ? (\n            <div data-mlm-control=\"group-by\">\n              <MultiSwitch<ReferralStatsGroupBy> label=\"Group by\" list={GROUPS} value={groupBy} onValueChange={onGroupByChange} \/>\n            <\/div>\n          ) : null}\n          {onMetricChange ? (\n            <div data-mlm-control=\"metric\">\n              <MultiSwitch<ReferralStatsMetric> label=\"Chart\" list={METRICS} value={metric} onValueChange={onMetricChange} \/>\n            <\/div>\n          ) : null}\n          {onRangeChange ? (\n            <div data-mlm-control=\"range\">\n              <DatePicker\n                range\n                label=\"Range\"\n                value={range ? [range.from, range.to] : undefined}\n                onValueChange={([from, to]) => onRangeChange({ from, to })}\n              \/>\n            <\/div>\n          ) : null}\n        <\/div>\n      ) : null}\n\n      {rows.length === 0 ? (\n        <Text className=\"fancy-mlm-stats__empty\">{emptyLabel}<\/Text>\n      ) : (\n        <>\n          <div data-mlm-chart={metric}>\n            <Chart.Bar data={statsChartData(rows, metric)} height={180} showValues \/>\n          <\/div>\n\n          <Table className=\"fancy-mlm-stats__table\">\n            <Table.Head>\n              <Table.Row>\n                <Table.Cell header>{keyLabel ?? GROUPS.find((g) => g.value === groupBy)?.label ?? \"Key\"}<\/Table.Cell>\n                {COLUMNS.map((c) => (\n                  <Table.Cell header key={c.stat} className=\"fancy-mlm-stats__num\">\n                    {c.label}\n                  <\/Table.Cell>\n                ))}\n              <\/Table.Row>\n            <\/Table.Head>\n            <Table.Body>\n              {rows.map((row) => {\n                const selected = row.key === selectedKey;\n                return (\n                  <Table.Row key={row.key} className={cn(selected && \"is-selected\")} onClick={onSelect ? () => onSelect(row.key, row) : undefined}>\n                    <Table.Cell data-mlm-stat-key={row.key} data-mlm-stat=\"key\" data-mlm-selected={selected ? \"true\" : undefined}>\n                      {onSelect ? (\n                        <Button\n                          variant=\"ghost\"\n                          size=\"sm\"\n                          data-mlm-select={row.key}\n                          aria-pressed={selected}\n                          onClick={(event) => {\n                            event.stopPropagation();\n                            onSelect(row.key, row);\n                          }}\n                        >\n                          {row.label ?? row.key}\n                        <\/Button>\n                      ) : (\n                        row.label ?? row.key\n                      )}\n                    <\/Table.Cell>\n                    {COLUMNS.map((c) => (\n                      <Table.Cell key={c.stat} data-mlm-stat-key={row.key} data-mlm-stat={c.stat} className=\"fancy-mlm-stats__num\">\n                        {show(c.stat, row)}\n                      <\/Table.Cell>\n                    ))}\n                  <\/Table.Row>\n                );\n              })}\n            <\/Table.Body>\n            {\/* A second body, not a raw <tfoot>: react-fancy's Table places\n                only Head and Body inside its <table>, so a <tfoot> child was\n                rendered after the table, outside it. *\/}\n            <Table.Body className=\"fancy-mlm-stats__totals\" data-mlm-totals=\"\">\n              <Table.Row>\n                <Table.Cell header>Total<\/Table.Cell>\n                {COLUMNS.map((c) => (\n                  <Table.Cell key={c.stat} data-mlm-total={c.stat} className=\"fancy-mlm-stats__num\">\n                    {total(c.stat)}\n                  <\/Table.Cell>\n                ))}\n              <\/Table.Row>\n            <\/Table.Body>\n          <\/Table>\n        <\/>\n      )}\n    <\/Card>\n  );\n}\n","type":"registry:ui","target":"components\/fancy\/referral-stats\/ReferralStats.tsx"},{"path":"components\/fancy\/referral-stats\/stats.ts","content":"import type { ReferralStatRow, ReferralStatsMetric } from \".\/types\";\n\n\/** Bar data for one metric; conversion is plotted as a percentage. *\/\nexport function statsChartData(rows: ReferralStatRow[], metric: ReferralStatsMetric): Array<{ label: string; value: number }> {\n  return rows.map((row) => ({\n    label: row.label ?? row.key,\n    value: metric === \"conversionRate\" ? Math.round(row.conversionRate * 1000) \/ 10 : row[metric],\n  }));\n}\n\n\/**\n * Totals that can honestly be summed. Unique sessions cannot: a visitor who\n * scanned two codes is one session in each row. Ask the engine for an\n * ungrouped figure and pass it as `totals` instead.\n *\/\nexport function summarizeStats(rows: ReferralStatRow[]): { scans: number; signups: number } {\n  return rows.reduce((sum, row) => ({ scans: sum.scans + row.scans, signups: sum.signups + row.signups }), { scans: 0, signups: 0 });\n}\n\n\/** A rate as a percentage with one decimal: 0.6667 -> \"66.7%\". *\/\nexport function formatRate(rate: number): string {\n  return `${(rate * 100).toFixed(1)}%`;\n}\n","type":"registry:ui","target":"components\/fancy\/referral-stats\/stats.ts"},{"path":"components\/fancy\/referral-stats\/types.ts","content":"\/** A network member as the UI consumes it \u2014 JSON-friendly, agent-emittable. *\/\nexport interface DownlineMember {\n  id: string;\n  \/** Enroller pointer \u2014 the edge a unilevel tree draws by. *\/\n  sponsorId?: string | null;\n  \/** Placement pointer \u2014 the edge binary \/ matrix trees draw by (falls back to `sponsorId`). *\/\n  placementId?: string | null;\n  label?: string;\n  tier?: string;\n  active?: boolean;\n  meta?: Record<string, unknown>;\n}\n\n\/**\n * Which parent pointer links the tree \u2014 `\"sponsor\"` (unilevel, the enroller tree)\n * or `\"placement\"` (binary \/ matrix, the placement tree, falling back to\n * `sponsorId`). Mirrors the engine's tree types.\n *\/\nexport type DownlineEdge = \"sponsor\" | \"placement\";\n\nexport type CommissionStatus = \"pending\" | \"paid\" | \"held\" | \"reversed\";\n\n\/** What referral stats are grouped by. Mirrors the engines' `stats(groupBy)`. *\/\nexport type ReferralStatsGroupBy = \"code\" | \"scope\" | \"member\";\n\n\/** Which figure the chart plots. *\/\nexport type ReferralStatsMetric = \"scans\" | \"uniqueSessions\" | \"signups\" | \"conversionRate\";\n\n\/**\n * One row of referral stats: the engines' `StatRow` (PHP `toArray()`, or the\n * Node object as-is), plus an optional display `label`. JSON-friendly.\n *\/\nexport interface ReferralStatRow {\n  \/** The code, scope key or member id the row is for. Also its stable handle. *\/\n  key: string;\n  label?: string;\n  scans: number;\n  \/** Distinct hashed sessions. Never summed across rows: one visitor can scan many codes. *\/\n  uniqueSessions: number;\n  signups: number;\n  \/** signups \/ uniqueSessions; 0 with no sessions; can exceed 1. *\/\n  conversionRate: number;\n}\n\n\/** A date range as `YYYY-MM-DD` strings, `from` inclusive, `to` exclusive. *\/\nexport interface ReferralStatsRange {\n  from: string;\n  to: string;\n}\n\n\/** One row of a commission statement \u2014 mirrors the engine's RewardComputation. *\/\nexport interface CommissionRow {\n  id?: string;\n  recipientMemberId?: string;\n  recipientLabel?: string;\n  level: number;\n  metric?: string;\n  tier?: string;\n  amount: number;\n  status?: CommissionStatus;\n}\n","type":"registry:ui","target":"components\/fancy\/referral-stats\/types.ts"}]}