{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "branch-usage-table", "title": "BranchUsageTable", "description": "Per-branch consumption attribution: sortable metric columns, magnitude rules, an expandable tail, and a list layout for a single metric.", "registryDependencies": [ "utils", "https://ui.neon.com/r/neon-tokens.json", "https://ui.neon.com/r/skeleton.json" ], "files": [ { "path": "src/components/branch-usage-table/branch-usage-table.tsx", "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport type { ComponentProps, ReactNode } from \"react\";\n\nimport { Skeleton } from \"@/components/ui/skeleton\";\nimport { cn } from \"@/lib/utils\";\n\nexport interface BranchUsageColumn {\n /** Keys into each row's `metrics`, e.g. \"compute_unit_seconds\". */\n id: string;\n /** Column header, e.g. \"Compute\". */\n label: string;\n /** Unit suffix beside the header, e.g. \"CU-hrs\". */\n unit?: string;\n /** Per-column formatter; falls back to two decimals. */\n format?: (value: number) => string;\n}\n\nexport interface BranchUsageRow {\n /** Branch id, e.g. \"br-young-sky-a1b2c3d4\". */\n id: string;\n /** Branch name, e.g. \"main\" or \"ci/pr-4821\". */\n name: string;\n /** Column id -> value, already converted to the display unit. */\n metrics: Record;\n /** Marks the project's default branch. */\n isDefault?: boolean;\n /** Marks a protected branch. */\n isProtected?: boolean;\n /** Quiet second line, e.g. the parent branch or last-active time. */\n hint?: string;\n}\n\nexport type SortDirection = \"asc\" | \"desc\";\n\nexport interface BranchUsageSort {\n /** Column id to sort by. */\n columnId: string;\n direction: SortDirection;\n}\n\nexport type BranchUsageTableProps = Omit<\n ComponentProps<\"section\">,\n \"children\" | \"onSelect\"\n> & {\n /** One row per branch. */\n rows: BranchUsageRow[];\n /** Metric columns in display order; the first is the default sort. */\n columns: BranchUsageColumn[];\n /**\n * \"table\" compares branches across metrics; \"list\" reads as a ranking\n * of one. \"auto\" picks list for a single column, because one metric per\n * row is a list and a table shape only adds a header and an axis.\n */\n layout?: \"auto\" | \"table\" | \"list\";\n /** Panel heading. */\n title?: string;\n /** Controlled sort. */\n sort?: BranchUsageSort;\n /** Uncontrolled initial sort; defaults to the first column, descending. */\n defaultSort?: BranchUsageSort;\n onSortChange?: (sort: BranchUsageSort) => void;\n /**\n * Show only the top N rows and collapse the rest into one row that\n * expands. Branch fleets run to hundreds; a table that long answers\n * nothing.\n */\n topN?: number;\n /** Adds a muted totals row across every branch, collapsed ones included. */\n showTotals?: boolean;\n /** Makes rows clickable, e.g. to open the branch. */\n onSelectBranch?: (row: BranchUsageRow) => void;\n /** Right-side header slot, e.g. a project filter. */\n action?: ReactNode;\n isLoading?: boolean;\n error?: string | null;\n /** Shown when `rows` is empty. */\n empty?: ReactNode;\n /** Quiet footer, e.g. a metering-lag notice. */\n meteredThrough?: string;\n};\n\n/* ─────────────────────────────────────────────────────────\n * TABLE STORYBOARD\n *\n * shape a table earns its keep by comparing branches\n * across metrics. With one metric it degrades to\n * a list, because a lone column needs neither a\n * header row nor an alignment axis\n * rank the sorted column carries a hairline rule\n * along the bottom of its cell, left-anchored\n * and scaled to the largest row. A filled block\n * behind the digits reads as \"this cell is\n * selected\"; a rule reads as magnitude\n * sort every sortable header shows its caret, muted\n * until it's the active one. An affordance you\n * only see after using it isn't an affordance\n * tail past topN the rest collapse into one row that\n * says how many and opens on click. It sits\n * below a rule, outside the ranking, so its\n * value can't look like a broken sort\n * total a muted totals row across every branch, so one\n * row's share is readable without doing the\n * addition\n * narrow under 40rem the columns stack into label and\n * value pairs — one DOM, no horizontal scroll\n * ───────────────────────────────────────────────────────── */\n\nconst DEFAULT_FORMAT = new Intl.NumberFormat(\"en-US\", {\n maximumFractionDigits: 2,\n});\n\nconst TOTALS_ID = \"__totals__\";\nconst FULL_BAR = 100;\n/** Below this width the columns stack; matches the max-[40rem] variants. */\nconst STACK_AT = \"max-[40rem]\";\n\nconst formatCell = (column: BranchUsageColumn, value: number) =>\n column.format ? column.format(value) : DEFAULT_FORMAT.format(value);\n\n/** Sorted columns announce their direction; the rest announce \"none\". */\nconst ariaSortOf = (isActive: boolean, direction: SortDirection) => {\n if (!isActive) {\n return \"none\" as const;\n }\n\n return direction === \"desc\"\n ? (\"descending\" as const)\n : (\"ascending\" as const);\n};\n\nconst sumBy = (rows: BranchUsageRow[], columnId: string) => {\n let total = 0;\n\n for (const row of rows) {\n total += row.metrics[columnId] ?? 0;\n }\n\n return total;\n};\n\n/** Sorts, partitions past topN, and measures the ranked column. */\nconst shapeRows = (\n rows: BranchUsageRow[],\n activeSort: BranchUsageSort,\n topN: number | undefined,\n isTailOpen: boolean\n) => {\n const ranked = [...rows].toSorted((a, b) => {\n const left = a.metrics[activeSort.columnId] ?? 0;\n const right = b.metrics[activeSort.columnId] ?? 0;\n\n return activeSort.direction === \"desc\" ? right - left : left - right;\n });\n\n const isCollapsed = topN !== undefined && ranked.length > topN && !isTailOpen;\n const head = isCollapsed ? ranked.slice(0, topN) : ranked;\n\n return {\n head,\n peak: Math.max(\n ...head.map((row) => row.metrics[activeSort.columnId] ?? 0),\n 0\n ),\n ranked,\n tail: isCollapsed ? ranked.slice(topN) : [],\n };\n};\n\nconst SortCaret = ({\n direction,\n isActive,\n}: {\n direction: SortDirection;\n isActive: boolean;\n}) => (\n \n {isActive && direction === \"asc\" ? \"▲\" : \"▼\"}\n \n);\n\nconst BranchTag = ({ children }: { children: ReactNode }) => (\n \n {children}\n \n);\n\n/** Branch name, tags, and hint. Shared by both layouts. */\nconst BranchLabel = ({\n isInteractive,\n onSelect,\n row,\n}: {\n isInteractive: boolean;\n onSelect?: () => void;\n row: BranchUsageRow;\n}) => (\n <>\n \n {isInteractive ? (\n \n {row.name}\n \n ) : (\n \n {row.name}\n \n )}\n {row.isDefault ? default : null}\n {row.isProtected ? protected : null}\n \n {row.hint ? (\n \n {row.hint}\n \n ) : null}\n \n);\n\n/**\n * A metric cell. The share rule sits along the bottom edge rather than\n * behind the digits, so it can't be mistaken for a selection highlight.\n */\nconst MetricCell = ({\n column,\n isMuted,\n isSorted,\n share,\n value,\n}: {\n column: BranchUsageColumn;\n isMuted: boolean;\n isSorted: boolean;\n share: number;\n value: number;\n}) => (\n \n {formatCell(column, value)}\n {isSorted ? (\n \n ) : null}\n \n);\n\nconst SortableHeader = ({\n activeSort,\n column,\n onToggle,\n}: {\n activeSort: BranchUsageSort;\n column: BranchUsageColumn;\n onToggle: () => void;\n}) => {\n const isActive = activeSort.columnId === column.id;\n\n return (\n \n \n {column.label}\n {column.unit ? (\n \n {column.unit}\n \n ) : null}\n \n \n \n );\n};\n\n/** One metric: a ranked list, not a one-column table. */\nconst RankedList = ({\n column,\n isInteractive,\n onOpenTail,\n onSelectBranch,\n peak,\n rows,\n showTotals,\n tail,\n totalRows,\n}: {\n column: BranchUsageColumn;\n isInteractive: boolean;\n onOpenTail: () => void;\n onSelectBranch?: (row: BranchUsageRow) => void;\n peak: number;\n rows: BranchUsageRow[];\n showTotals: boolean;\n tail: BranchUsageRow[];\n totalRows: BranchUsageRow[];\n}) => (\n
    \n {rows.map((row) => {\n const value = row.metrics[column.id] ?? 0;\n\n return (\n \n
    \n \n onSelectBranch?.(row)}\n row={row}\n />\n \n \n {formatCell(column, value)}\n \n
    \n
    \n 0 ? value / peak : 0) * FULL_BAR}%` }}\n />\n
    \n \n );\n })}\n\n {/* The tail and the total belong in both layouts; a list that drops\n them answers a smaller question than the table does. */}\n {tail.length > 0 ? (\n
  • \n \n {`${tail.length} other branches`}\n \n show\n \n \n \n {formatCell(column, sumBy(tail, column.id))}\n \n
    • \n ) : null}\n\n {showTotals ? (\n
  • \n \n {`all ${totalRows.length} branches`}\n \n \n {formatCell(column, sumBy(totalRows, column.id))}\n \n
    • \n ) : null}\n
\n);\n\nconst TailRow = ({\n columns,\n onOpen,\n tail,\n}: {\n columns: BranchUsageColumn[];\n onOpen: () => void;\n tail: BranchUsageRow[];\n}) => (\n \n \n {/* Outside the ranking, so its value can't read as a sort gone wrong. */}\n \n {tail.length} other branches\n \n show\n \n \n \n {columns.map((column) => (\n \n ))}\n \n);\n\nconst TotalsRow = ({\n columns,\n rows,\n}: {\n columns: BranchUsageColumn[];\n rows: BranchUsageRow[];\n}) => (\n \n \n {`all ${rows.length} branches`}\n \n {columns.map((column) => (\n \n ))}\n \n);\n\n/** The comparison layout: one row per branch, one column per metric. */\nconst UsageTable = ({\n activeSort,\n columns,\n head,\n isInteractive,\n onOpenTail,\n onSelectBranch,\n onToggleSort,\n peak,\n showTotals,\n tail,\n totalRows,\n}: {\n activeSort: BranchUsageSort;\n columns: BranchUsageColumn[];\n head: BranchUsageRow[];\n isInteractive: boolean;\n onOpenTail: () => void;\n onSelectBranch?: (row: BranchUsageRow) => void;\n onToggleSort: (columnId: string) => void;\n peak: number;\n showTotals: boolean;\n tail: BranchUsageRow[];\n totalRows: BranchUsageRow[];\n}) => (\n \n \n \n \n Branch\n \n {columns.map((column) => (\n onToggleSort(column.id)}\n />\n ))}\n \n \n \n {head.map((row) => (\n \n \n onSelectBranch?.(row)}\n row={row}\n />\n \n {columns.map((column) => (\n 0 ? (row.metrics[column.id] ?? 0) / peak : 0}\n value={row.metrics[column.id] ?? 0}\n />\n ))}\n \n ))}\n \n\n {tail.length > 0 || showTotals ? (\n \n {tail.length > 0 ? (\n \n ) : null}\n {showTotals ? : null}\n \n ) : null}\n
\n);\n\n/** Empty, list, or table: one decision, made once. */\nconst UsageBody = ({\n activeSort,\n asList,\n columns,\n empty,\n head,\n isInteractive,\n onOpenTail,\n onSelectBranch,\n onToggleSort,\n peak,\n ranked,\n showTotals,\n tail,\n totalRows,\n}: {\n activeSort: BranchUsageSort;\n asList: boolean;\n columns: BranchUsageColumn[];\n empty?: ReactNode;\n head: BranchUsageRow[];\n isInteractive: boolean;\n onOpenTail: () => void;\n onSelectBranch?: (row: BranchUsageRow) => void;\n onToggleSort: (columnId: string) => void;\n peak: number;\n ranked: BranchUsageRow[];\n showTotals: boolean;\n tail: BranchUsageRow[];\n totalRows: BranchUsageRow[];\n}) => {\n const [firstColumn] = columns;\n\n if (ranked.length === 0) {\n return (\n
\n {empty ?? (\n

\n no branch consumption in this window\n

\n )}\n
\n );\n }\n\n if (asList && firstColumn) {\n return (\n \n );\n }\n\n return (\n \n );\n};\n\nconst LoadingCard = ({ className, ...props }: ComponentProps<\"section\">) => (\n \n \n
\n {Array.from({ length: 5 }, (_, index) => index).map((index) => (\n \n ))}\n
\n \n);\n\nexport const BranchUsageTable = ({\n action,\n className,\n columns,\n defaultSort,\n empty,\n error = null,\n isLoading = false,\n layout = \"auto\",\n meteredThrough,\n onSelectBranch,\n onSortChange,\n rows,\n showTotals = true,\n sort,\n title = \"usage by branch\",\n topN,\n ...props\n}: BranchUsageTableProps) => {\n const [firstColumn] = columns;\n const [internalSort, setInternalSort] = useState(\n defaultSort ?? { columnId: firstColumn?.id ?? \"\", direction: \"desc\" }\n );\n const [isTailOpen, setIsTailOpen] = useState(false);\n const activeSort = sort ?? internalSort;\n\n const toggleSort = (columnId: string) => {\n const isActive = activeSort.columnId === columnId;\n const next: BranchUsageSort = {\n columnId,\n direction: isActive && activeSort.direction === \"desc\" ? \"asc\" : \"desc\",\n };\n\n if (sort === undefined) {\n setInternalSort(next);\n }\n\n onSortChange?.(next);\n };\n\n const { head, peak, ranked, tail } = shapeRows(\n rows,\n activeSort,\n topN,\n isTailOpen\n );\n const isInteractive = Boolean(onSelectBranch);\n const asList =\n layout === \"list\" || (layout === \"auto\" && columns.length <= 1);\n\n if (isLoading) {\n return ;\n }\n\n return (\n \n
\n

{title}

\n {action}\n
\n\n {error ? (\n \n error\n {error}\n

\n ) : null}\n\n setIsTailOpen(true)}\n onSelectBranch={onSelectBranch}\n onToggleSort={toggleSort}\n peak={peak}\n ranked={ranked}\n showTotals={showTotals}\n tail={tail}\n totalRows={rows}\n />\n\n {meteredThrough ? (\n \n {meteredThrough}\n

\n ) : null}\n \n );\n};\n", "type": "registry:component" } ], "type": "registry:component" }