@useatlas/create 0.0.1

package/templates/docker/src/ui/components/atlas-chat.tsx

@@ -0,0 +1,370 @@
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport, isToolUIPart } from "ai";
+import { useState, useRef, useEffect, useMemo, useCallback } from "react";
+import { AUTH_MODES, type AuthMode } from "../lib/types";
+import { useAtlasConfig, ActionAuthProvider } from "../context";
+import { DarkModeContext } from "../hooks/use-dark-mode";
+import { useDarkMode } from "../hooks/use-dark-mode";
+import { useConversations } from "../hooks/use-conversations";
+import { ErrorBanner } from "./chat/error-banner";
+import { ApiKeyBar } from "./chat/api-key-bar";
+import { ManagedAuthCard } from "./chat/managed-auth-card";
+import { TypingIndicator } from "./chat/typing-indicator";
+import { ToolPart } from "./chat/tool-part";
+import { Markdown } from "./chat/markdown";
+import { STARTER_PROMPTS } from "./chat/starter-prompts";
+import { ConversationSidebar } from "./conversations/conversation-sidebar";
+
+const API_KEY_STORAGE_KEY = "atlas-api-key";
+
+export function AtlasChat() {
+  const { apiUrl, isCrossOrigin, authClient } = useAtlasConfig();
+  const dark = useDarkMode();
+  const [input, setInput] = useState("");
+  const [authMode, setAuthMode] = useState<AuthMode>("none");
+  const [healthWarning, setHealthWarning] = useState("");
+  const [apiKey, setApiKey] = useState("");
+  const [conversationId, setConversationId] = useState<string | null>(null);
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+  const [loadingConversation, setLoadingConversation] = useState(false);
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  const managedSession = authClient.useSession();
+  const isManaged = authMode === "managed";
+  const isSignedIn = isManaged && !!managedSession.data?.user;
+
+  const getHeaders = useCallback(() => {
+    const headers: Record<string, string> = {};
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+    return headers;
+  }, [apiKey]);
+
+  const getCredentials = useCallback((): RequestCredentials => {
+    return isCrossOrigin ? "include" : "same-origin";
+  }, [isCrossOrigin]);
+
+  const convos = useConversations({
+    apiUrl,
+    enabled: true,
+    getHeaders,
+    getCredentials,
+  });
+
+  const refreshConvosRef = useRef(convos.refresh);
+  refreshConvosRef.current = convos.refresh;
+
+  // Load API key from sessionStorage on mount + fetch auth mode + conversations
+  useEffect(() => {
+    try {
+      const stored = sessionStorage.getItem(API_KEY_STORAGE_KEY);
+      if (stored) setApiKey(stored);
+    } catch (err) {
+      console.warn("Cannot read API key from sessionStorage:", err);
+    }
+
+    async function fetchHealth(attempt: number): Promise<void> {
+      try {
+        const res = await fetch(`${apiUrl}/api/health`, {
+          credentials: isCrossOrigin ? "include" : "same-origin",
+        });
+        if (!res.ok) {
+          console.warn(`Health check returned ${res.status}`);
+          if (attempt < 2) {
+            await new Promise((r) => setTimeout(r, 2000));
+            return fetchHealth(attempt + 1);
+          }
+          setHealthWarning("Health check failed — check server logs. Try refreshing the page.");
+          return;
+        }
+        const data = await res.json();
+        const mode = data?.checks?.auth?.mode;
+        if (typeof mode === "string" && AUTH_MODES.includes(mode as AuthMode)) {
+          setAuthMode(mode as AuthMode);
+        }
+      } catch (err) {
+        console.warn("Health endpoint unavailable:", err);
+        if (attempt < 2) {
+          await new Promise((r) => setTimeout(r, 2000));
+          return fetchHealth(attempt + 1);
+        }
+        setHealthWarning("Unable to reach the API server. Try refreshing the page.");
+      }
+    }
+    fetchHealth(1);
+  }, [apiUrl]);
+
+  // Fetch conversation list after auth is resolved
+  useEffect(() => {
+    convos.fetchList();
+  }, [authMode, convos.fetchList]);
+
+  const handleSaveApiKey = useCallback((key: string) => {
+    setApiKey(key);
+    try {
+      sessionStorage.setItem(API_KEY_STORAGE_KEY, key);
+    } catch (err) {
+      console.warn("Could not persist API key to sessionStorage:", err);
+    }
+  }, []);
+
+  // Dynamic transport — captures x-conversation-id from response
+  const transport = useMemo(() => {
+    const headers: Record<string, string> = {};
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    return new DefaultChatTransport({
+      api: `${apiUrl}/api/chat`,
+      headers,
+      credentials: isCrossOrigin ? "include" : undefined,
+      body: conversationId ? { conversationId } : undefined,
+      fetch: (async (input, init) => {
+        const response = await globalThis.fetch(input, init);
+        const convId = response.headers.get("x-conversation-id");
+        if (convId && convId !== conversationId) {
+          setConversationId(convId);
+          setTimeout(() => {
+            refreshConvosRef.current().catch((err) => {
+              console.warn("Sidebar refresh failed:", err);
+            });
+          }, 500);
+        }
+        return response;
+      }) as typeof fetch,
+    });
+  }, [apiKey, authMode, apiUrl, isCrossOrigin, conversationId]);
+
+  const { messages, setMessages, sendMessage, status, error } = useChat({ transport });
+
+  const isLoading = status === "streaming" || status === "submitted";
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const isNearBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 100;
+    if (isNearBottom) el.scrollTop = el.scrollHeight;
+  }, [messages, status]);
+
+  function handleSend(text: string) {
+    if (!text.trim()) return;
+    const saved = text;
+    setInput("");
+    sendMessage({ text: saved }).catch((err) => {
+      console.error("Failed to send message:", err);
+      setInput(saved);
+      setHealthWarning("Failed to send message. Please try again.");
+      setTimeout(() => setHealthWarning(""), 5000);
+    });
+  }
+
+  async function handleSelectConversation(id: string) {
+    if (loadingConversation) return;
+    setLoadingConversation(true);
+    try {
+      const uiMessages = await convos.loadConversation(id);
+      if (uiMessages) {
+        setMessages(uiMessages);
+        setConversationId(id);
+        convos.setSelectedId(id);
+        setMobileMenuOpen(false);
+      } else {
+        setHealthWarning("Could not load conversation. It may have been deleted.");
+        setTimeout(() => setHealthWarning(""), 5000);
+      }
+    } finally {
+      setLoadingConversation(false);
+    }
+  }
+
+  function handleNewChat() {
+    setMessages([]);
+    setConversationId(null);
+    convos.setSelectedId(null);
+    setInput("");
+    setMobileMenuOpen(false);
+  }
+
+  return (
+    <DarkModeContext.Provider value={dark}>
+      <div className="flex h-dvh">
+        {convos.available && (
+          <ConversationSidebar
+            conversations={convos.conversations}
+            selectedId={convos.selectedId}
+            loading={convos.loading}
+            onSelect={handleSelectConversation}
+            onDelete={(id) => convos.deleteConversation(id)}
+            onStar={(id, starred) => convos.starConversation(id, starred)}
+            onNewChat={handleNewChat}
+            mobileOpen={mobileMenuOpen}
+            onMobileClose={() => setMobileMenuOpen(false)}
+          />
+        )}
+
+        <main className="flex flex-1 flex-col overflow-hidden">
+          <div className="mx-auto flex w-full max-w-4xl flex-1 flex-col p-4">
+            <header className="mb-4 flex-none border-b border-zinc-100 pb-3 dark:border-zinc-800">
+              <div className="flex items-center justify-between">
+                <div className="flex items-center gap-3">
+                  {convos.available && (
+                    <button
+                      onClick={() => setMobileMenuOpen(true)}
+                      className="rounded p-1 text-zinc-400 hover:text-zinc-700 md:hidden dark:hover:text-zinc-200"
+                      aria-label="Open conversation history"
+                    >
+                      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="h-5 w-5">
+                        <path fillRule="evenodd" d="M2 4.75A.75.75 0 0 1 2.75 4h14.5a.75.75 0 0 1 0 1.5H2.75A.75.75 0 0 1 2 4.75ZM2 10a.75.75 0 0 1 .75-.75h14.5a.75.75 0 0 1 0 1.5H2.75A.75.75 0 0 1 2 10Zm0 5.25a.75.75 0 0 1 .75-.75h14.5a.75.75 0 0 1 0 1.5H2.75a.75.75 0 0 1-.75-.75Z" clipRule="evenodd" />
+                      </svg>
+                    </button>
+                  )}
+                  <div className="flex items-center gap-2.5">
+                    <svg viewBox="0 0 256 256" fill="none" className="h-7 w-7 shrink-0" aria-hidden="true">
+                      <path d="M128 24 L232 208 L24 208 Z" stroke="#23CE9E" strokeWidth="14" fill="none" strokeLinejoin="round"/>
+                      <circle cx="128" cy="28" r="16" fill="#23CE9E"/>
+                    </svg>
+                    <div>
+                      <h1 className="text-xl font-semibold tracking-tight">Atlas</h1>
+                      <p className="text-sm text-zinc-500">Ask your data anything</p>
+                    </div>
+                  </div>
+                </div>
+                {isSignedIn && (
+                  <div className="flex items-center gap-3">
+                    <span className="text-xs text-zinc-500 dark:text-zinc-400">
+                      {managedSession.data?.user?.email}
+                    </span>
+                    <button
+                      onClick={() => {
+                        authClient.signOut().catch((err: unknown) => {
+                          console.error("Sign out failed:", err);
+                          setHealthWarning("Sign out failed. Please try again.");
+                          setTimeout(() => setHealthWarning(""), 5000);
+                        });
+                      }}
+                      className="rounded border border-zinc-200 px-2 py-1 text-xs text-zinc-500 transition-colors hover:border-zinc-400 hover:text-zinc-800 dark:border-zinc-700 dark:text-zinc-400 dark:hover:border-zinc-500 dark:hover:text-zinc-200"
+                    >
+                      Sign out
+                    </button>
+                  </div>
+                )}
+              </div>
+            </header>
+
+            {healthWarning && (
+              <p className="mb-2 text-xs text-zinc-400 dark:text-zinc-500">{healthWarning}</p>
+            )}
+
+            {isManaged && !isSignedIn ? (
+              <ManagedAuthCard />
+            ) : (
+              <ActionAuthProvider getHeaders={getHeaders} getCredentials={getCredentials}>
+                {authMode === "simple-key" && (
+                  <div className="mb-3 flex-none">
+                    <ApiKeyBar apiKey={apiKey} onSave={handleSaveApiKey} />
+                  </div>
+                )}
+
+                <div ref={scrollRef} className="flex-1 space-y-4 overflow-y-auto pb-4">
+                  {messages.length === 0 && !error && (
+                    <div className="flex h-full flex-col items-center justify-center gap-6">
+                      <div className="text-center">
+                        <p className="text-lg font-medium text-zinc-500 dark:text-zinc-400">
+                          What would you like to know?
+                        </p>
+                        <p className="mt-1 text-sm text-zinc-400 dark:text-zinc-600">
+                          Ask a question about your data to get started
+                        </p>
+                      </div>
+                      <div className="grid w-full max-w-lg grid-cols-2 gap-2">
+                        {STARTER_PROMPTS.map((prompt) => (
+                          <button
+                            key={prompt}
+                            onClick={() => handleSend(prompt)}
+                            className="rounded-lg border border-zinc-200 bg-zinc-50 px-3 py-2.5 text-left text-sm text-zinc-500 transition-colors hover:border-zinc-400 hover:bg-zinc-100 hover:text-zinc-800 dark:border-zinc-800 dark:bg-zinc-900 dark:text-zinc-400 dark:hover:border-zinc-600 dark:hover:bg-zinc-800 dark:hover:text-zinc-200"
+                          >
+                            {prompt}
+                          </button>
+                        ))}
+                      </div>
+                    </div>
+                  )}
+
+                  {messages.map((m) => {
+                    if (m.role === "user") {
+                      return (
+                        <div key={m.id} className="flex justify-end">
+                          <div className="max-w-[85%] rounded-xl bg-blue-600 px-4 py-3 text-sm text-white">
+                            {m.parts?.map((part, i) =>
+                              part.type === "text" ? (
+                                <p key={i} className="whitespace-pre-wrap">
+                                  {part.text}
+                                </p>
+                              ) : null,
+                            )}
+                          </div>
+                        </div>
+                      );
+                    }
+
+                    return (
+                      <div key={m.id} className="space-y-2">
+                        {m.parts?.map((part, i) => {
+                          if (part.type === "text" && part.text.trim()) {
+                            return (
+                              <div key={i} className="max-w-[90%]">
+                                <div className="rounded-xl bg-zinc-100 px-4 py-3 text-sm text-zinc-800 dark:bg-zinc-800 dark:text-zinc-200">
+                                  <Markdown content={part.text} />
+                                </div>
+                              </div>
+                            );
+                          }
+                          if (isToolUIPart(part)) {
+                            return (
+                              <div key={i} className="max-w-[95%]">
+                                <ToolPart part={part} />
+                              </div>
+                            );
+                          }
+                          return null;
+                        })}
+                      </div>
+                    );
+                  })}
+
+                  {isLoading && messages.length > 0 && <TypingIndicator />}
+                </div>
+
+                {error && <ErrorBanner error={error} authMode={authMode} />}
+
+                <form
+                  onSubmit={(e) => {
+                    e.preventDefault();
+                    handleSend(input);
+                  }}
+                  className="flex flex-none gap-2 border-t border-zinc-100 pt-4 dark:border-zinc-800"
+                >
+                  <input
+                    value={input}
+                    onChange={(e) => setInput(e.target.value)}
+                    placeholder="Ask a question about your data..."
+                    className="flex-1 rounded-lg border border-zinc-200 bg-zinc-50 px-4 py-3 text-sm text-zinc-900 placeholder-zinc-400 outline-none focus:border-blue-500 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-100 dark:placeholder-zinc-600"
+                    disabled={isLoading}
+                  />
+                  <button
+                    type="submit"
+                    disabled={isLoading || !input.trim()}
+                    className="rounded-lg bg-blue-600 px-5 py-3 text-sm font-medium text-white transition-colors hover:bg-blue-500 disabled:opacity-40"
+                  >
+                    Ask
+                  </button>
+                </form>
+              </ActionAuthProvider>
+            )}
+          </div>
+        </main>
+      </div>
+    </DarkModeContext.Provider>
+  );
+}

package/templates/docker/src/ui/components/chart/chart-detection.ts

@@ -0,0 +1,261 @@
+/* Chart detection — pure functions, zero React deps. Kept framework-agnostic for direct unit testing. */
+
+export type ColumnType = "numeric" | "date" | "categorical" | "unknown";
+
+export type ClassifiedColumn = {
+  index: number;
+  header: string;
+  type: ColumnType;
+  uniqueCount: number;
+};
+
+export type ChartType = "bar" | "line" | "pie";
+
+export type ChartRecommendation = {
+  type: ChartType;
+  categoryColumn: ClassifiedColumn;
+  valueColumns: [ClassifiedColumn, ...ClassifiedColumn[]];
+  reason: string;
+};
+
+export type RechartsRow = Record<string, string | number>;
+
+type NonChartableResult = {
+  chartable: false;
+  columns: ClassifiedColumn[];
+};
+
+type ChartableResult = {
+  chartable: true;
+  columns: ClassifiedColumn[];
+  recommendations: [ChartRecommendation, ...ChartRecommendation[]];
+  data: RechartsRow[];
+};
+
+export type ChartDetectionResult = NonChartableResult | ChartableResult;
+
+/* ------------------------------------------------------------------ */
+/*  Color palettes (Tailwind weights)                                   */
+/* ------------------------------------------------------------------ */
+
+export const CHART_COLORS_LIGHT = [
+  "#3b82f6", // blue-500
+  "#10b981", // emerald-500
+  "#f59e0b", // amber-500
+  "#ef4444", // red-500
+  "#8b5cf6", // violet-500
+  "#06b6d4", // cyan-500
+  "#f97316", // orange-500
+  "#ec4899", // pink-500
+];
+
+export const CHART_COLORS_DARK = [
+  "#60a5fa", // blue-400
+  "#34d399", // emerald-400
+  "#fbbf24", // amber-400
+  "#f87171", // red-400
+  "#a78bfa", // violet-400
+  "#22d3ee", // cyan-400
+  "#fb923c", // orange-400
+  "#f472b6", // pink-400
+];
+
+/* ------------------------------------------------------------------ */
+/*  Column classification                                               */
+/* ------------------------------------------------------------------ */
+
+const DATE_HEADER_HINTS = /^(date|month|year|quarter|week|day|period|time|timestamp)$/i;
+const CATEGORICAL_HEADER_HINTS = /^(name|type|category|status|region|country|industry|department|plan|tier|segment|group|label|source|channel)$/i;
+const SKIP_HEADER_HINTS = /^(id|uuid|_id|pk|key)$/i;
+
+const ISO_DATE_RE = /^\d{4}-\d{2}/;
+const MONTH_NAME_RE = /^(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)/i;
+const YEAR_ONLY_RE = /^(19|20)\d{2}$/;
+const QUARTER_RE = /^Q[1-4]\s*\d{4}$/i;
+
+export function classifyColumn(header: string, values: string[]): ColumnType {
+  const nonEmpty = values.filter((v) => v !== "" && v != null);
+  if (nonEmpty.length === 0) return "unknown";
+
+  // Header hint: skip ID-like columns
+  if (SKIP_HEADER_HINTS.test(header)) return "unknown";
+
+  // Numeric check: >80% parse as finite numbers (date check takes priority for overlapping values)
+  const numericCount = nonEmpty.filter((v) => {
+    const n = Number(v.replace(/,/g, ""));
+    return isFinite(n);
+  }).length;
+  const numericRatio = numericCount / nonEmpty.length;
+
+  // Date check: >70% match date patterns (>30% when header hints match)
+  const dateCount = nonEmpty.filter(
+    (v) => ISO_DATE_RE.test(v) || MONTH_NAME_RE.test(v) || YEAR_ONLY_RE.test(v) || QUARTER_RE.test(v),
+  ).length;
+  const dateRatio = dateCount / nonEmpty.length;
+
+  // Header hint tiebreaker: if header matches date keywords...
+  //   (a) ...and at least some values look date-like, trust the header
+  //   (b) ...and values aren't overwhelmingly numeric (catches year-only values)
+  if (DATE_HEADER_HINTS.test(header) && dateRatio > 0.3) return "date";
+  if (DATE_HEADER_HINTS.test(header) && numericRatio < 0.9) return "date";
+
+  if (dateRatio > 0.7) return "date";
+  if (numericRatio > 0.8) return "numeric";
+
+  // Categorical header hint
+  if (CATEGORICAL_HEADER_HINTS.test(header)) return "categorical";
+
+  // Categorical fallback: text values with <50 unique entries (higher cardinality suggests free-text or IDs)
+  const unique = new Set(nonEmpty);
+  if (unique.size < 50) return "categorical";
+
+  return "unknown";
+}
+
+/* ------------------------------------------------------------------ */
+/*  Chart recommendation engine                                         */
+/* ------------------------------------------------------------------ */
+
+export function detectCharts(headers: string[], rows: string[][]): ChartDetectionResult {
+  if (headers.length === 0 || rows.length < 2) {
+    return { chartable: false, columns: [] };
+  }
+
+  // Deduplicate headers so chart dataKey matches transformed data keys
+  const seen = new Map<string, number>();
+  const dedupedHeaders = headers.map((h) => {
+    const count = seen.get(h) ?? 0;
+    seen.set(h, count + 1);
+    return count > 0 ? `${h}_${count + 1}` : h;
+  });
+
+  const columns: ClassifiedColumn[] = dedupedHeaders.map((header, index) => {
+    const values = rows.map((r) => r[index] ?? "");
+    const type = classifyColumn(header, values);
+    const uniqueCount = new Set(values.filter((v) => v !== "")).size;
+    return { index, header, type, uniqueCount };
+  });
+
+  const dateColumns = columns.filter((c) => c.type === "date");
+  const numericColumns = columns.filter((c) => c.type === "numeric");
+  const categoricalColumns = columns.filter((c) => c.type === "categorical");
+
+  if (numericColumns.length === 0) {
+    return { chartable: false, columns };
+  }
+
+  const recommendations: ChartRecommendation[] = [];
+
+  // Line: date + numeric (time-series, highest priority)
+  if (dateColumns.length >= 1 && numericColumns.length >= 1) {
+    recommendations.push({
+      type: "line",
+      categoryColumn: dateColumns[0],
+      valueColumns: numericColumns as [ClassifiedColumn, ...ClassifiedColumn[]],
+      reason: `Time-series: ${dateColumns[0].header} vs ${numericColumns.map((c) => c.header).join(", ")}`,
+    });
+  }
+
+  // Bar: categorical + numeric
+  if (categoricalColumns.length >= 1 && numericColumns.length >= 1) {
+    recommendations.push({
+      type: "bar",
+      categoryColumn: categoricalColumns[0],
+      valueColumns: numericColumns as [ClassifiedColumn, ...ClassifiedColumn[]],
+      reason: `Comparison: ${numericColumns.map((c) => c.header).join(", ")} by ${categoricalColumns[0].header}`,
+    });
+  }
+
+  // Pie: first categorical column (2-7 unique values) + first numeric column
+  if (categoricalColumns.length >= 1 && numericColumns.length >= 1) {
+    const cat = categoricalColumns[0];
+    if (cat.uniqueCount >= 2 && cat.uniqueCount <= 7) {
+      recommendations.push({
+        type: "pie",
+        categoryColumn: cat,
+        valueColumns: [numericColumns[0]],
+        reason: `Distribution: ${numericColumns[0].header} by ${cat.header}`,
+      });
+    }
+  }
+
+  // Fallback: when all columns are numeric, treat first as category axis (often an index or bucket label)
+  if (recommendations.length === 0 && numericColumns.length >= 2) {
+    const first = columns[0];
+    const rest = numericColumns.filter((c) => c.index !== first.index);
+    if (rest.length >= 1) {
+      recommendations.push({
+        type: "bar",
+        categoryColumn: first,
+        valueColumns: rest as [ClassifiedColumn, ...ClassifiedColumn[]],
+        reason: `Fallback: ${rest.map((c) => c.header).join(", ")} by ${first.header}`,
+      });
+    }
+  }
+
+  // Also allow bar for date columns (as a secondary option after line)
+  if (dateColumns.length >= 1 && numericColumns.length >= 1 && !recommendations.some((r) => r.type === "bar")) {
+    recommendations.push({
+      type: "bar",
+      categoryColumn: dateColumns[0],
+      valueColumns: numericColumns as [ClassifiedColumn, ...ClassifiedColumn[]],
+      reason: `Comparison: ${numericColumns.map((c) => c.header).join(", ")} by ${dateColumns[0].header}`,
+    });
+  }
+
+  if (recommendations.length === 0) {
+    return { chartable: false, columns };
+  }
+
+  const data = transformData(rows, recommendations[0]);
+
+  return {
+    chartable: true,
+    columns,
+    recommendations: recommendations as [ChartRecommendation, ...ChartRecommendation[]],
+    data,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Data transform                                                      */
+/* ------------------------------------------------------------------ */
+
+function parseNumericValue(raw: string): number {
+  const cleaned = raw.replace(/[$%,\s]/g, "");
+  if (cleaned === "" || cleaned === "-") return 0;
+  const num = Number(cleaned);
+  return isFinite(num) ? num : 0;
+}
+
+export function transformData(
+  rows: string[][],
+  recommendation: ChartRecommendation,
+): RechartsRow[] {
+  const catIdx = recommendation.categoryColumn.index;
+  const catHeader = recommendation.categoryColumn.header;
+  const valIdxs = recommendation.valueColumns.map((c) => c.index);
+
+  // Cap rows for bar charts with many categories
+  let effectiveRows = rows;
+  if (recommendation.type === "bar" && rows.length > 30) {
+    // Sort by first value column descending, take top 20
+    const valIdx = valIdxs[0];
+    effectiveRows = [...rows]
+      .sort((a, b) => {
+        const av = parseNumericValue(a[valIdx] ?? "0");
+        const bv = parseNumericValue(b[valIdx] ?? "0");
+        return bv - av;
+      })
+      .slice(0, 20);
+  }
+
+  return effectiveRows.map((row) => {
+    const record: RechartsRow = {};
+    record[catHeader] = row[catIdx] ?? "";
+    for (const vc of recommendation.valueColumns) {
+      record[vc.header] = parseNumericValue(row[vc.index] ?? "0");
+    }
+    return record;
+  });
+}