@turtleclub/org-leaderboard 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 0.1.0-beta.1 (2026-03-03)
+
+### Features
+
+- turtle leaderboard tools ([#271](https://github.com/turtle-dao/turtle-tools/issues/271)) ([6e484a6](https://github.com/turtle-dao/turtle-tools/commit/6e484a645f2ce2020084b850dadaa2e2fd1f4e87))

package/README.md

@@ -0,0 +1,87 @@
+# @turtleclub/org-leaderboard
+
+White-label **organization leaderboards** for Turtle. One config per org; one component for all.
+
+## Usage (in turtle-app)
+
+1. **Install**
+
+   ```bash
+   bun add @turtleclub/org-leaderboard @turtleclub/hooks
+   ```
+
+2. **Define config (or use preset)**
+
+   ```ts
+   import {
+     getOrgLeaderboardConfigBySlug,
+     KINTSU_ORG_LEADERBOARD_CONFIG,
+     type OrgLeaderboardConfig,
+   } from "@turtleclub/org-leaderboard";
+
+   export const ORG_LEADERBOARDS: OrgLeaderboardConfig[] = [
+     KINTSU_ORG_LEADERBOARD_CONFIG,
+     // { orgId: "...", slug: "other", name: "Other", columns: [...] },
+   ];
+   ```
+
+3. **Route: `/leaderboard/:orgSlug`**
+
+   ```tsx
+   import { OrgLeaderboardView, getOrgLeaderboardConfigBySlug } from "@turtleclub/org-leaderboard";
+   import { ORG_LEADERBOARDS } from "@/constants/orgLeaderboards";
+   import { useOrganizations } from "@turtleclub/hooks";
+
+   function OrgLeaderboardPage() {
+     const { orgSlug } = useParams();
+     const config = getOrgLeaderboardConfigBySlug(ORG_LEADERBOARDS, orgSlug);
+     const orgs = useOrganizations();
+     const org = config ? orgs?.getOrganizationById?.(config.orgId) : null;
+     const userId = useCurrentUserId(); // your auth
+
+     if (!config) return <NotFound />;
+
+     return (
+       <OrgLeaderboardView
+         config={config}
+         userId={userId}
+         overrides={{
+           logoUrl: org?.iconUrl ?? config.logoFallbackUrl,
+           displayName: org?.name ?? config.name,
+         }}
+         renderEligibleOpportunities={(productId) => (
+           <YourEligibleOpportunitiesDialog productId={productId} />
+         )}
+       />
+     );
+   }
+   ```
+
+4. **Nav**: add links to `/leaderboard/kintsu`, `/leaderboard/other`, etc. (e.g. from `ORG_LEADERBOARDS.map(c => ({ to: `/leaderboard/${c.slug}`, label: c.name }))`).
+
+## API (same for all orgs)
+
+- **List:** `GET /turtle/leaderboard/organization/:orgId` (query: `limit`, `offset`, `searchUsername`, `sortBy`, `sortOrder`, …)
+- **User:** `GET /turtle/leaderboard/organization/:orgId/user/:userId`
+
+Hooks: `useOrgLeaderboard({ orgId, params })`, `useOrgUserLeaderboard({ orgId, userId })` from `@turtleclub/hooks`.
+
+## Adding a new org
+
+Add one entry to `ORG_LEADERBOARDS` (orgId, slug, name, logoFallbackUrl, optional productId, pointsLabel, rewardPoolDescription, optional pointsDivisor, columns). No new page, hooks, or API.
+
+---
+
+## Exact parity checklist (turtle-app)
+
+Use this so the new generic leaderboard looks and behaves like the current Kintsu/Nunchi pages.
+
+| Item | turtle-tools | turtle-app |
+|------|--------------|------------|
+| **Nunchi points scaling** | Config supports `pointsDivisor` (e.g. `1e18`). Nunchi preset sets it. Table and user banner format points as `value / divisor`. | Use Nunchi preset as-is, or override `pointsDivisor` in your `ORG_LEADERBOARDS` entry. |
+| **Layout / wrappers** | `OrgLeaderboardView` renders content only; no AnimatedBackground, containerClass, or app-specific borders. | Wrap `<OrgLeaderboardView />` in the same layout you use today (e.g. `AnimatedBackground`, `containerClass`, `border-gradient-white`, `rounded-turtle`). |
+| **Referral block** | Optional `renderReferralBlock={() => <YourReferralUI />}`. Rendered inside the user stats banner when provided. | Pass it for Kintsu (code + copy / “Create referral”). Omit for Nunchi. |
+| **Document title** | View sets `document.title = "{name} Leaderboard"` on mount and restores on unmount (can disable with `setDocumentTitle={false}`). | Optional: set title yourself; otherwise leave default. |
+| **Avatar fallback** | Optional `overrides.avatarFallbackUrl`. Used when avatar fails or is missing (table + user banner). | Pass e.g. `overrides={{ ..., avatarFallbackUrl: "/images/leaderboard/turtle-avatar.png" }}` to match current app. |
+| **Mobile grid** | DataTable uses `grid: { displayAsGrid: true, headerSlot: "username", rightSlot: "totalPoints", excludeColumns: ["userId"] }`. | If your current tables differ (e.g. different slots or excluded columns), we can add a config override or you wrap/adjust in the app. |
+| **Eligible Opportunities** | Optional `renderEligibleOpportunities={(productId) => <Dialog />}`. | Pass your existing Kintsu dialog so behavior is unchanged. |

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@turtleclub/org-leaderboard",
+  "version": "0.1.0-beta.1",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.62.3",
+    "@tanstack/react-table": "^8.21.3",
+    "@turtleclub/hooks": "0.5.0-beta.88",
+    "@turtleclub/ui": "0.7.0-beta.31",
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.1",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "gitHead": "c703afeabcbd109768b06fd5c39cd43b24cfa1d1"
+}

package/src/OrgLeaderboardView.tsx

@@ -0,0 +1,279 @@
+import React, { useCallback, useEffect, useMemo, useState } from "react";
+import type { ColumnDef } from "@tanstack/react-table";
+import type { SortingState } from "@tanstack/react-table";
+import type { PaginationState } from "@tanstack/react-table";
+import {
+  useOrgLeaderboard,
+  useOrgUserLeaderboard,
+  type OrgLeaderboardConfig,
+  type OrgLeaderboardRow,
+  type OrgLeaderboardColumnId,
+  type OrgLeaderboardSortBy,
+  type OrgLeaderboardSortOrder,
+} from "@turtleclub/hooks";
+import {
+  DataTable,
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  Card,
+  CardContent,
+  Button,
+} from "@turtleclub/ui";
+import { columnIdToSortBy } from "./constants";
+
+export interface OrgLeaderboardViewOverrides {
+  /** Override logo URL (e.g. from organizations API) */
+  logoUrl?: string;
+  /** Override display name (e.g. from organizations API) */
+  displayName?: string;
+  /** Fallback image when user avatar fails to load (e.g. /images/leaderboard/turtle-avatar.png) */
+  avatarFallbackUrl?: string;
+}
+
+export interface OrgLeaderboardViewProps {
+  config: OrgLeaderboardConfig;
+  /** Logged-in user id; when set, the "your stats" banner is shown */
+  userId?: string;
+  overrides?: OrgLeaderboardViewOverrides;
+  /** Optional: custom content for "Eligible Opportunities" (e.g. dialog). If not set, a link to /earn/products/:productId is rendered. */
+  renderEligibleOpportunities?: (productId: string) => React.ReactNode;
+  /** Optional: referral block (code + copy / "Create referral"). Pass for Kintsu, omit for Nunchi. */
+  renderReferralBlock?: () => React.ReactNode;
+  /** Base path for product link when renderEligibleOpportunities is not used. Default "/earn/products" */
+  productLinkBase?: string;
+  /** Set document.title to "{name} Leaderboard" on mount. Default true. */
+  setDocumentTitle?: boolean;
+  className?: string;
+}
+
+const DEFAULT_PAGE_SIZE = 20;
+
+function formatNumber(value: number): string {
+  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(2)}M`;
+  if (value >= 1_000) return `${(value / 1_000).toFixed(2)}K`;
+  return value.toLocaleString();
+}
+
+/** Apply points divisor (e.g. 1e18 for Nunchi cHIPs) then format. */
+function formatPointsValue(value: number, divisor: number = 1): string {
+  const scaled = divisor !== 1 ? value / divisor : value;
+  return formatNumber(scaled);
+}
+
+function UserBannerStat({ label, display }: { label: string; display: string }) {
+  return (
+    <div className="text-sm">
+      <span className="text-muted-foreground">{label}:</span>{" "}
+      <span className="font-medium">{display}</span>
+    </div>
+  );
+}
+
+export function OrgLeaderboardView({
+  config,
+  userId,
+  overrides,
+  renderEligibleOpportunities,
+  renderReferralBlock,
+  productLinkBase = "/earn/products",
+  setDocumentTitle = true,
+  className,
+}: OrgLeaderboardViewProps) {
+  const displayName = overrides?.displayName ?? config.name;
+
+  useEffect(() => {
+    if (!setDocumentTitle) return;
+    const prev = document.title;
+    document.title = `${displayName} Leaderboard`;
+    return () => {
+      document.title = prev;
+    };
+  }, [displayName, setDocumentTitle]);
+
+  const [pagination, setPagination] = useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: DEFAULT_PAGE_SIZE,
+  });
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [searchUsername, setSearchUsername] = useState("");
+
+  const sortBy: OrgLeaderboardSortBy | undefined = sorting[0]
+    ? columnIdToSortBy(sorting[0].id)
+    : undefined;
+  const sortOrder: OrgLeaderboardSortOrder | undefined = sorting[0]
+    ? (sorting[0].desc ? "desc" : "asc")
+    : undefined;
+
+  const { rows, total, totalPages, isLoading } = useOrgLeaderboard({
+    orgId: config.orgId,
+    params: {
+      limit: pagination.pageSize,
+      offset: pagination.pageIndex * pagination.pageSize,
+      sortBy,
+      sortOrder,
+      searchUsername: searchUsername || undefined,
+    },
+  });
+
+  const { userInfo } = useOrgUserLeaderboard({
+    orgId: config.orgId,
+    userId: userId ?? "",
+    enabled: !!userId,
+  });
+
+  const logoUrl = overrides?.logoUrl ?? config.logoFallbackUrl;
+  const pointsLabel = config.pointsLabel ?? "Points";
+  const divisor = config.pointsDivisor ?? 1;
+
+  const tableColumns = useMemo(() => {
+    const cols: ColumnDef<OrgLeaderboardRow, unknown>[] = [];
+    for (const col of config.columns) {
+      if (col.showInTable === false) continue;
+      const id = col.id as OrgLeaderboardColumnId;
+      const isUsername = id === "username";
+      cols.push({
+        id,
+        accessorKey: id,
+        header: col.label,
+        enableSorting: true,
+        cell: ({ row }) => {
+          const value = row.getValue(id);
+          if (isUsername) {
+            const username = row.original.turtleUser?.username ?? row.original.userId?.slice(0, 8) ?? "—";
+            const avatarUrl = row.original.turtleUser?.avatarUrl;
+            const avatarFallbackUrl = overrides?.avatarFallbackUrl;
+            return (
+              <div className="flex items-center gap-2">
+                <Avatar className="size-8">
+                  {avatarUrl && <AvatarImage src={avatarUrl} alt={username} />}
+                  <AvatarFallback className="text-xs">
+                    {avatarFallbackUrl ? (
+                      <img src={avatarFallbackUrl} alt="" className="size-full object-cover rounded-full" />
+                    ) : (
+                      username.slice(0, 2).toUpperCase()
+                    )}
+                  </AvatarFallback>
+                </Avatar>
+                <span className="truncate">{username}</span>
+              </div>
+            );
+          }
+          if (typeof value === "number" && (id === "totalPoints" || id === "userTvl" || id === "dailyPoints" || id === "referredValue")) {
+            return formatPointsValue(value, divisor);
+          }
+          return value ?? "—";
+        },
+      });
+    }
+    return cols;
+  }, [config.columns, divisor, overrides?.avatarFallbackUrl]);
+
+  const onSortingChange = useCallback(
+    (updater: SortingState | ((prev: SortingState) => SortingState)) => {
+      setSorting(updater);
+    },
+    []
+  );
+
+  const pageCount = totalPages ?? (total != null ? Math.ceil(total / pagination.pageSize) : undefined);
+
+  return (
+    <div className={className}>
+      {/* Header */}
+      <div className="mb-6 flex items-center gap-3">
+        {logoUrl && (
+          <img
+            src={logoUrl}
+            alt={displayName}
+            className="size-10 rounded-full object-contain"
+          />
+        )}
+        <h1 className="text-2xl font-semibold">{displayName} Leaderboard</h1>
+      </div>
+
+      {/* User stats banner */}
+      {userId && userInfo && (
+        <Card className="mb-6" variant="border">
+          <CardContent className="flex flex-wrap items-center gap-4 pt-6">
+            <div className="flex items-center gap-2">
+              <Avatar className="size-8">
+                <AvatarFallback className="text-xs">
+                  {overrides?.avatarFallbackUrl ? (
+                    <img src={overrides.avatarFallbackUrl} alt="" className="size-full object-cover rounded-full" />
+                  ) : (
+                    (userInfo.username ?? userInfo.userId?.slice(0, 2) ?? "?").toUpperCase()
+                  )}
+                </AvatarFallback>
+              </Avatar>
+              <span className="font-medium">{userInfo.username ?? "You"}</span>
+            </div>
+            {config.columns
+              .filter((c) => c.showInUserBanner !== false)
+              .map((col) => {
+                const key = col.id;
+                const value = userInfo[key as keyof typeof userInfo];
+                if (value === undefined) return null;
+                const display =
+                  typeof value === "number" &&
+                  !["rank", "totalUsers"].includes(key as string)
+                    ? formatPointsValue(value, divisor)
+                    : String(value);
+                const label = key === "rank" ? `Rank #${value}/${userInfo.totalUsers}` : col.label;
+                return <UserBannerStat key={key} label={label} display={display} />;
+              })}
+            {renderReferralBlock?.()}
+          </CardContent>
+        </Card>
+      )}
+
+      {/* Eligible Opportunities */}
+      {config.productId && (
+        <div className="mb-6">
+          {renderEligibleOpportunities ? (
+            renderEligibleOpportunities(config.productId)
+          ) : (
+            <Button variant="outline" asChild>
+              <a href={`${productLinkBase}/${config.productId}`}>Eligible Opportunities</a>
+            </Button>
+          )}
+        </div>
+      )}
+
+      {/* Stats row */}
+      <div className="mb-4 flex flex-wrap items-center gap-6 text-sm text-muted-foreground">
+        {total != null && <span>Total Participants: {formatNumber(total)}</span>}
+        {config.rewardPoolDescription && (
+          <span title="Reward pool">{config.rewardPoolDescription}</span>
+        )}
+      </div>
+
+      {/* Table */}
+      <DataTable<OrgLeaderboardRow, unknown>
+        columns={tableColumns}
+        data={rows}
+        isLoading={isLoading}
+        enableSearch
+        enableSorting
+        enablePagination
+        manualPagination
+        manualSorting
+        manualFiltering
+        pagination={pagination}
+        onPaginationChange={setPagination}
+        sorting={sorting}
+        onSortingChange={onSortingChange}
+        pageCount={pageCount}
+        rowCount={total}
+        globalFilter={searchUsername}
+        onGlobalFilterChange={setSearchUsername}
+        grid={{
+          displayAsGrid: true,
+          headerSlot: "username",
+          rightSlot: "totalPoints",
+          excludeColumns: ["userId"],
+        }}
+      />
+    </div>
+  );
+}

package/src/constants.ts

@@ -0,0 +1,29 @@
+import {
+  orgLeaderboardSortBySchema,
+  type OrgLeaderboardColumnId,
+  type OrgLeaderboardSortBy,
+} from "@turtleclub/hooks";
+
+/**
+ * Maps table column id to API sortBy param.
+ * API uses "points" for total points; row field is totalPoints.
+ */
+export const COLUMN_ID_TO_API_SORT_BY: Partial<Record<OrgLeaderboardColumnId, OrgLeaderboardSortBy>> =
+  {
+    totalPoints: "points",
+    // rank, username, referredValue, userTvl, dailyPoints are 1:1 with API
+  };
+
+/**
+ * Maps a table column id to the API sortBy param. Validates with schema so invalid
+ * ids (e.g. from a misconfigured column) are not sent to the API.
+ * Note: We accept string, not keyof COLUMN_ID_TO_API_SORT_BY, because sortable
+ * columns include ids that are 1:1 with the API (rank, username, userTvl, etc.)
+ * and are not keys of the map—only totalPoints is mapped to "points".
+ */
+export function columnIdToSortBy(columnId: string): OrgLeaderboardSortBy | undefined {
+  const sortBy =
+    (COLUMN_ID_TO_API_SORT_BY as Record<string, OrgLeaderboardSortBy>)[columnId] ?? columnId;
+  const result = orgLeaderboardSortBySchema.safeParse(sortBy);
+  return result.success ? result.data : undefined;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { OrgLeaderboardView } from "./OrgLeaderboardView";
+export type { OrgLeaderboardViewProps, OrgLeaderboardViewOverrides } from "./OrgLeaderboardView";
+export { columnIdToSortBy } from "./constants";
+export { KINTSU_ORG_LEADERBOARD_CONFIG } from "./presets/kintsu";
+export { NUNCHI_ORG_LEADERBOARD_CONFIG } from "./presets/nunchi";
+
+// Re-export config type so app can type its registry without depending on hooks internals
+export type { OrgLeaderboardConfig, OrgLeaderboardColumnConfig } from "@turtleclub/hooks";
+
+/**
+ * Resolve org leaderboard config by slug from a registry.
+ * Use in the app: getOrgLeaderboardConfigBySlug(ORG_LEADERBOARDS, params.orgSlug)
+ */
+export function getOrgLeaderboardConfigBySlug<T extends { slug: string }>(
+  configs: T[],
+  slug: string
+): T | undefined {
+  return configs.find((c) => c.slug === slug);
+}

package/src/presets/kintsu.ts

@@ -0,0 +1,20 @@
+import type { OrgLeaderboardConfig } from "@turtleclub/hooks";
+
+/** Kintsu org leaderboard config. Use in app: ORG_LEADERBOARDS = [KINTSU_ORG_LEADERBOARD_CONFIG] */
+export const KINTSU_ORG_LEADERBOARD_CONFIG: OrgLeaderboardConfig = {
+  orgId: "c7c32b42-a823-43ac-80dd-c2e39fc54c22",
+  slug: "kintsu",
+  name: "Kintsu",
+  logoFallbackUrl: undefined,
+  productId: "ae0901a9-f0d5-48a1-9cdd-6dfaa651228a",
+  pointsLabel: "Kintsu Points",
+  rewardPoolDescription: "10,000 Kintsu Points/day",
+  columns: [
+    { id: "rank", label: "Rank", showInTable: true, showInUserBanner: true },
+    { id: "username", label: "User", showInTable: true },
+    { id: "userTvl", label: "Current TVL", showInTable: true, showInUserBanner: true },
+    { id: "referredValue", label: "Referred TVL", showInTable: true, showInUserBanner: true },
+    { id: "dailyPoints", label: "Daily Kintsu Points", showInTable: true, showInUserBanner: true },
+    { id: "totalPoints", label: "Points", showInTable: true, showInUserBanner: true },
+  ],
+};

package/src/presets/nunchi.ts

@@ -0,0 +1,24 @@
+import type { OrgLeaderboardConfig } from "@turtleclub/hooks";
+
+export const NUNCHI_ORG_LEADERBOARD_CONFIG: OrgLeaderboardConfig = {
+  orgId: "270ab015-0791-48b8-82a6-51bbb432651c",
+  slug: "nunchi",
+  name: "Nunchi",
+  logoFallbackUrl: undefined, // we rely on org.iconUrl
+  productId: undefined, // no “eligible opportunities” dialog today
+  pointsLabel: "Nunchi cHIPs",
+  rewardPoolDescription: "950 Nunchi cHIPs per $1k/day",
+  pointsDivisor: 1e18, // API returns raw wei; display as human-readable
+  columns: [
+    { id: "rank", label: "Rank", showInTable: true, showInUserBanner: true },
+    { id: "username", label: "User", showInTable: true },
+    { id: "userTvl", label: "TVL", showInTable: true, showInUserBanner: true },
+    {
+      id: "totalPoints",
+      label: "Nunchi cHIPs",
+      showInTable: true,
+      showInUserBanner: true,
+    },
+  ],
+};
+

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}