@schandlergarcia/sf-web-components 1.7.0 → 1.9.0

package/src/components/library/charts/{D3Chart.jsx → D3Chart.tsx}

@@ -1,5 +1,27 @@
 import React from "react";
 
+interface Dimensions {
+  width: number;
+  height: number;
+}
+
+export interface D3ChartProps {
+  data: unknown;
+  renderChart?: (svg: SVGSVGElement, data: unknown, dims: Dimensions, options: Record<string, unknown>) => void;
+  options?: Record<string, unknown>;
+  width?: number;
+  height?: number;
+  responsive?: boolean;
+  aspectRatio?: number;
+  className?: string;
+  style?: React.CSSProperties;
+  containerStyle?: React.CSSProperties;
+  svgStyle?: React.CSSProperties;
+  loading?: boolean;
+  error?: string | Error;
+  ariaLabel?: string;
+}
+
 /**
  * Minimal D3 chart host:
  * - Owns the <svg> element
@@ -21,10 +43,10 @@ export default function D3Chart({
   loading = false,
   error,
   ariaLabel = "Chart"
-}) {
-  const containerRef = React.useRef(null);
-  const svgRef = React.useRef(null);
-  const [containerWidth, setContainerWidth] = React.useState(null);
+}: D3ChartProps): React.ReactElement {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const svgRef = React.useRef<SVGSVGElement>(null);
+  const [containerWidth, setContainerWidth] = React.useState<number | null>(null);
 
   React.useEffect(() => {
     if (!responsive) return;
@@ -53,7 +75,7 @@ export default function D3Chart({
     const svgEl = svgRef.current;
     if (!svgEl) return;
 
-    const dims = {
+    const dims: Dimensions = {
       width: computedWidth ?? 0,
       height: computedHeight ?? 0
     };
@@ -105,5 +127,3 @@ export default function D3Chart({
     </div>
   );
 }
-
-

package/src/components/library/charts/{D3ChartTemplates.jsx → D3ChartTemplates.tsx}

@@ -1,11 +1,45 @@
 import * as d3 from "d3";
 
-function clear(svg) {
+interface Dimensions {
+  width: number;
+  height: number;
+}
+
+interface Margin {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+interface LineChartOptions {
+  xKey?: string;
+  yKey?: string;
+  margin?: Margin;
+  stroke?: string;
+  strokeWidth?: number;
+  showAxes?: boolean;
+  showGrid?: boolean;
+}
+
+interface GroupedBarChartOptions {
+  groups?: string[];
+  margin?: Margin;
+  xKey?: string;
+  colors?: string[];
+  barRadius?: number;
+  yFormat?: string;
+  showGrid?: boolean;
+}
+
+type DataPoint = Record<string, unknown>;
+
+function clear(svg: SVGSVGElement): void {
   d3.select(svg).selectAll("*").remove();
 }
 
 export const D3ChartTemplates = {
-  lineChart(svg, data, dims, opts = {}) {
+  lineChart(svg: SVGSVGElement, data: DataPoint[], dims: Dimensions, opts: LineChartOptions = {}): void {
     const {
       xKey = "x",
       yKey = "y",
@@ -25,11 +59,11 @@ export const D3ChartTemplates = {
 
     const g = d3.select(svg).attr("viewBox", `0 0 ${width} ${height}`).append("g").attr("transform", `translate(${margin.left},${margin.top})`);
 
-    const xs = data.map((d) => d?.[xKey]).filter((v) => v != null);
-    const ys = data.map((d) => d?.[yKey]).filter((v) => v != null);
+    const xs = data.map((d) => d?.[xKey]).filter((v) => v != null) as number[];
+    const ys = data.map((d) => d?.[yKey]).filter((v) => v != null) as number[];
 
-    const xDomain = d3.extent(xs);
-    const yDomain = d3.extent(ys);
+    const xDomain = d3.extent(xs) as [number, number];
+    const yDomain = d3.extent(ys) as [number, number];
 
     const x = d3.scaleLinear().domain(xDomain).nice().range([0, innerW]);
     const y = d3.scaleLinear().domain(yDomain).nice().range([innerH, 0]);
@@ -37,15 +71,15 @@ export const D3ChartTemplates = {
     if (showGrid) {
       g.append("g")
         .attr("class", "grid")
-        .call(d3.axisLeft(y).ticks(5).tickSize(-innerW).tickFormat(""))
-        .call((grid) => grid.selectAll("line").attr("stroke", "currentColor").attr("opacity", 0.12))
-        .call((grid) => grid.selectAll("path").attr("stroke", "none"));
+        .call(d3.axisLeft(y).ticks(5).tickSize(-innerW).tickFormat(() => ""))
+        .call((grid: d3.Selection<SVGGElement, unknown, null, undefined>) => grid.selectAll("line").attr("stroke", "currentColor").attr("opacity", 0.12))
+        .call((grid: d3.Selection<SVGGElement, unknown, null, undefined>) => grid.selectAll("path").attr("stroke", "none"));
     }
 
     const line = d3
-      .line()
-      .x((d) => x(d[xKey]))
-      .y((d) => y(d[yKey]))
+      .line<DataPoint>()
+      .x((d) => x(d[xKey] as number))
+      .y((d) => y(d[yKey] as number))
       .defined((d) => d?.[xKey] != null && d?.[yKey] != null);
 
     g.append("path")
@@ -59,15 +93,15 @@ export const D3ChartTemplates = {
       g.append("g")
         .attr("transform", `translate(0,${innerH})`)
         .call(d3.axisBottom(x).ticks(6))
-        .call((ax) => ax.selectAll("text").attr("font-size", 10));
+        .call((ax: d3.Selection<SVGGElement, unknown, null, undefined>) => ax.selectAll("text").attr("font-size", 10));
 
       g.append("g")
         .call(d3.axisLeft(y).ticks(5))
-        .call((ax) => ax.selectAll("text").attr("font-size", 10));
+        .call((ax: d3.Selection<SVGGElement, unknown, null, undefined>) => ax.selectAll("text").attr("font-size", 10));
     }
   },
 
-  groupedBarChart(svg, data, dims, opts = {}) {
+  groupedBarChart(svg: SVGSVGElement, data: DataPoint[], dims: Dimensions, opts: GroupedBarChartOptions = {}): void {
     const {
       groups = [],
       margin = { top: 20, right: 20, bottom: 40, left: 55 },
@@ -90,37 +124,35 @@ export const D3ChartTemplates = {
 
     const groupKeys = groups.length ? groups : Object.keys(data[0] || {}).filter((k) => k !== xKey);
 
-    const x0 = d3.scaleBand().domain(data.map((d) => d[xKey])).range([0, innerW]).padding(0.3);
+    const x0 = d3.scaleBand().domain(data.map((d: DataPoint) => String(d[xKey]))).range([0, innerW]).padding(0.3);
     const x1 = d3.scaleBand().domain(groupKeys).range([0, x0.bandwidth()]).padding(0.05);
-    const yMax = d3.max(data, (d) => d3.max(groupKeys, (k) => d[k])) * 1.15;
+    const yMax = (d3.max(data, (d: DataPoint) => d3.max(groupKeys, (k: string) => d[k] as number)) ?? 0) * 1.15;
     const y = d3.scaleLinear().domain([0, yMax]).range([innerH, 0]);
 
     g.append("g")
       .attr("transform", `translate(0,${innerH})`)
       .call(d3.axisBottom(x0).tickSize(0))
-      .call((ax) => ax.selectAll("text").attr("fill", "#94a3b8").attr("font-size", "11px"))
-      .call((ax) => ax.select(".domain").remove());
+      .call((ax: d3.Selection<SVGGElement, unknown, null, undefined>) => ax.selectAll("text").attr("fill", "#94a3b8").attr("font-size", "11px"))
+      .call((ax: d3.Selection<SVGGElement, unknown, null, undefined>) => ax.select(".domain").remove());
 
     g.append("g")
       .call(d3.axisLeft(y).ticks(5).tickFormat(d3.format(yFormat)).tickSize(showGrid ? -innerW : 0))
-      .call((ax) => ax.selectAll("text").attr("fill", "#94a3b8").attr("font-size", "10px"))
-      .call((ax) => ax.selectAll(".tick line").attr("stroke", "#e2e8f0").attr("stroke-dasharray", "2,2"))
-      .call((ax) => ax.select(".domain").remove());
+      .call((ax: d3.Selection<SVGGElement, unknown, null, undefined>) => ax.selectAll("text").attr("fill", "#94a3b8").attr("font-size", "10px"))
+      .call((ax: d3.Selection<SVGGElement, unknown, null, undefined>) => ax.selectAll(".tick line").attr("stroke", "#e2e8f0").attr("stroke-dasharray", "2,2"))
+      .call((ax: d3.Selection<SVGGElement, unknown, null, undefined>) => ax.select(".domain").remove());
 
     const rows = g.selectAll(".bar-group").data(data).join("g")
       .attr("class", "bar-group")
-      .attr("transform", (d) => `translate(${x0(d[xKey])},0)`);
+      .attr("transform", (d: DataPoint) => `translate(${x0(String(d[xKey]))},0)`);
 
     groupKeys.forEach((key, i) => {
       rows.append("rect")
-        .attr("x", x1(key))
-        .attr("y", (d) => y(d[key]))
+        .attr("x", x1(key) ?? 0)
+        .attr("y", (d: DataPoint) => y(d[key] as number))
         .attr("width", x1.bandwidth())
-        .attr("height", (d) => innerH - y(d[key]))
+        .attr("height", (d: DataPoint) => innerH - y(d[key] as number))
         .attr("rx", barRadius)
         .attr("fill", colors[i % colors.length]);
     });
   },
 };
-
-

package/src/components/library/charts/{GeoMap.jsx → GeoMap.tsx}

@@ -1,9 +1,12 @@
 import React, { useMemo, useRef, useEffect, useState, useCallback } from "react";
 import * as d3 from "d3";
 import { feature } from "topojson-client";
+import type { Topology, GeometryCollection } from "topojson-specification";
 import world from "world-atlas/land-110m.json";
 
-const land = feature(world, world.objects.land);
+const land = feature(world as unknown as Topology<{ land: GeometryCollection }>, (world.objects.land as unknown) as GeometryCollection);
+
+type ProjectionType = "naturalEarth" | "mercator" | "equirectangular";
 
 const PROJECTIONS = {
   naturalEarth: d3.geoNaturalEarth1,
@@ -11,7 +14,30 @@ const PROJECTIONS = {
   equirectangular: d3.geoEquirectangular,
 };
 
-const THEMES = {
+interface Theme {
+  bg: string;
+  bgGradient: [string, string];
+  land: string;
+  landStroke: string;
+  sphere: string;
+  graticule: string;
+  graticuleOpacity: number;
+  markerActive: string;
+  markerInactive: string;
+  label: string;
+  labelInactive: string;
+  arc: string;
+  arcHighlight: string;
+  arcDanger: string;
+  dot: string;
+  dotDanger: string;
+  overlayFill: string;
+  overlayStroke: string;
+}
+
+type ThemeName = "dark" | "light";
+
+const THEMES: Record<ThemeName, Theme> = {
   dark: {
     bg: "#050b15",
     bgGradient: ["#0a1628", "#050b15"],
@@ -54,11 +80,72 @@ const THEMES = {
   },
 };
 
-function buildProjection(type, width, height) {
+function buildProjection(type: ProjectionType, width: number, height: number): d3.GeoProjection {
   const factory = PROJECTIONS[type] ?? PROJECTIONS.naturalEarth;
   return factory().fitSize([width, height], { type: "Sphere" });
 }
 
+export interface Marker {
+  id: string;
+  lon: number;
+  lat: number;
+  label?: string | false;
+  active?: boolean;
+}
+
+export interface Arc {
+  id: string;
+  from: [number, number];
+  to: [number, number];
+  danger?: boolean;
+  color?: string;
+  dotColor?: string;
+  progress?: number;
+  _path?: string | null;
+}
+
+export interface Overlay {
+  id: string;
+  center: [number, number];
+  radius?: number;
+  fill?: string;
+  stroke?: string;
+}
+
+export interface InitialBounds {
+  sw: [number, number];
+  ne: [number, number];
+  padding?: number;
+}
+
+interface ChildrenFunctionProps {
+  proj: d3.GeoProjection;
+  pathGen: d3.GeoPath;
+  theme: Theme;
+  width: number;
+  height: number;
+  transform: d3.ZoomTransform;
+}
+
+export interface GeoMapProps {
+  width?: number;
+  height?: number;
+  projection?: ProjectionType;
+  theme?: ThemeName;
+  markers?: Marker[];
+  arcs?: Arc[];
+  overlays?: Overlay[];
+  selectedId?: string | null;
+  onArcClick?: (arc: Arc) => void;
+  onMarkerClick?: (marker: Marker) => void;
+  zoomable?: boolean;
+  minZoom?: number;
+  maxZoom?: number;
+  initialBounds?: InitialBounds | null;
+  className?: string;
+  children?: React.ReactNode | ((props: ChildrenFunctionProps) => React.ReactNode);
+}
+
 export default function GeoMap({
   width = 960,
   height = 480,
@@ -76,11 +163,11 @@ export default function GeoMap({
   initialBounds = null,
   className = "",
   children,
-}) {
+}: GeoMapProps): React.ReactElement {
   const t = THEMES[theme] ?? THEMES.dark;
-  const svgRef = useRef(null);
-  const [transform, setTransform] = useState(d3.zoomIdentity);
-  const zoomRef = useRef(null);
+  const svgRef = useRef<SVGSVGElement>(null);
+  const [transform, setTransform] = useState<d3.ZoomTransform>(d3.zoomIdentity);
+  const zoomRef = useRef<d3.ZoomBehavior<SVGSVGElement, unknown> | null>(null);
 
   const { proj, pathGen, graticulePath, spherePath, landPath } = useMemo(() => {
     const proj = buildProjection(projType, width, height);
@@ -98,12 +185,14 @@ export default function GeoMap({
   useEffect(() => {
     if (!zoomable || !svgRef.current) return;
     const svg = d3.select(svgRef.current);
-    const zoom = d3.zoom()
+    const zoom = d3.zoom<SVGSVGElement, unknown>()
       .scaleExtent([minZoom, maxZoom])
-      .on("zoom", (e) => setTransform(e.transform));
+      .on("zoom", (e: d3.D3ZoomEvent<SVGSVGElement, unknown>) => setTransform(e.transform));
     zoomRef.current = zoom;
     svg.call(zoom);
-    return () => svg.on(".zoom", null);
+    return () => {
+      svg.on(".zoom", null);
+    };
   }, [zoomable, minZoom, maxZoom]);
 
   // Apply initial zoom to fit bounds (markers/region) on mount
@@ -144,15 +233,15 @@ export default function GeoMap({
   const isZoomed = transform.k !== 1 || transform.x !== 0 || transform.y !== 0;
 
   const arcPaths = useMemo(() => {
-    const cache = {};
+    const cache: Record<string, string | null> = {};
     arcs.forEach(a => {
       const key = `${a.from[0]},${a.from[1]}-${a.to[0]},${a.to[1]}`;
       if (cache[key]) { a._path = cache[key]; return; }
       const interp = d3.geoInterpolate(a.from, a.to);
-      const pts = [];
+      const pts: [number, number][] = [];
       for (let i = 0; i <= 1; i += 0.02) {
         const p = proj(interp(i));
-        if (p) pts.push(p);
+        if (p) pts.push(p as [number, number]);
       }
       const path = pts.length > 1 ? d3.line()(pts) : null;
       cache[key] = path;
@@ -162,7 +251,7 @@ export default function GeoMap({
   }, [arcs, proj]);
 
   const activeMarkerIds = useMemo(() => {
-    const s = new Set();
+    const s = new Set<string>();
     markers.forEach(m => { if (m.active) s.add(m.id); });
     return s;
   }, [markers]);
@@ -194,9 +283,9 @@ export default function GeoMap({
 
         {/* Zoomable content group */}
         <g transform={txStr}>
-          <path d={spherePath} fill="none" stroke={t.sphere} strokeWidth={0.8 * invScale} />
-          <path d={landPath} fill={t.land} stroke={t.landStroke} strokeWidth={0.4 * invScale} />
-          <path d={graticulePath} fill="none" stroke={t.graticule} strokeWidth={0.3 * invScale} opacity={t.graticuleOpacity} />
+          <path d={spherePath ?? undefined} fill="none" stroke={t.sphere} strokeWidth={0.8 * invScale} />
+          <path d={landPath ?? undefined} fill={t.land} stroke={t.landStroke} strokeWidth={0.4 * invScale} />
+          <path d={graticulePath ?? undefined} fill="none" stroke={t.graticule} strokeWidth={0.3 * invScale} opacity={t.graticuleOpacity} />
 
           {/* Overlay zones (disruptions, weather) */}
           {overlays.map(o => {

package/src/components/library/chat/{ChatBar.jsx → ChatBar.tsx}

@@ -9,7 +9,8 @@ import {
 } from "@heroicons/react/24/outline";
 import ChatMessageList from "./ChatMessageList";
 import ChatInput from "./ChatInput";
-import useChatState from "./useChatState";
+import useChatState, { UseChatStateOptions, ChatMessage } from "./useChatState";
+import { ChatMessageData } from "./ChatMessage";
 
 const BACKDROP_VARIANTS = {
   hidden: { opacity: 0 },
@@ -23,11 +24,22 @@ const PANEL_VARIANTS = {
     opacity: 1,
     y: 0,
     scale: 1,
-    transition: { type: "spring", damping: 28, stiffness: 380 },
+    transition: { type: "spring" as const, damping: 28, stiffness: 380 },
   },
   exit: { opacity: 0, y: 10, scale: 0.97, transition: { duration: 0.12 } },
 };
 
+export interface ChatBarProps {
+  onSend?: UseChatStateOptions["onSend"];
+  suggestions?: string[];
+  placeholder?: string;
+  title?: string;
+  initialMessages?: UseChatStateOptions["initialMessages"];
+  className?: string;
+  renderAvatar?: (message: ChatMessageData) => React.ReactNode;
+  onOpenInTab?: (messages: ChatMessage[]) => void;
+}
+
 /**
  * Command-palette style AI chat bar.
  *
@@ -41,17 +53,16 @@ const PANEL_VARIANTS = {
 export default function ChatBar({
   onSend,
   suggestions = [],
-  placeholder = "Ask a question\u2026",
+  placeholder = "Ask a question…",
   title = "AI Assistant",
   initialMessages = [],
   className = "",
-  panelHeight,
   renderAvatar,
   onOpenInTab,
-}) {
+}: ChatBarProps) {
   const [open, setOpen] = useState(false);
   const [portalVisible, setPortalVisible] = useState(false);
-  const panelRef = useRef(null);
+  const panelRef = useRef<HTMLDivElement>(null);
   const chat = useChatState({ initialMessages, onSend });
   const isEmpty = chat.messages.length === 0;
 
@@ -62,7 +73,7 @@ export default function ChatBar({
   }, [open]);
 
   useEffect(() => {
-    function onKey(e) {
+    function onKey(e: KeyboardEvent) {
       if ((e.metaKey || e.ctrlKey) && e.key === "k") {
         e.preventDefault();
         setOpen((prev) => !prev);
@@ -79,7 +90,7 @@ export default function ChatBar({
     return () => { document.body.style.overflow = ""; };
   }, [open]);
 
-  function handleSend(content) {
+  function handleSend(content: string) {
     if (!open) setOpen(true);
     chat.sendMessage(content);
   }

package/src/components/library/chat/{ChatInput.jsx → ChatInput.tsx}

@@ -1,16 +1,18 @@
-import React, { useState, useRef, useEffect } from "react";
+import { useState, useRef, useEffect } from "react";
 import { PaperAirplaneIcon, StopCircleIcon } from "@heroicons/react/24/solid";
 
+export interface ChatInputProps {
+  onSend?: (content: string) => void;
+  disabled?: boolean;
+  isLoading?: boolean;
+  onStop?: () => void;
+  placeholder?: string;
+  maxRows?: number;
+}
+
 /**
  * Chat input with auto-resize textarea, Send button, and keyboard shortcuts.
  * Enter sends, Shift+Enter inserts newline.
- *
- * @param {Function} onSend — (content: string) => void
- * @param {boolean}  disabled — disable input while agent is processing
- * @param {boolean}  isLoading — show stop button instead of send
- * @param {Function} onStop — optional: called when stop is clicked
- * @param {string}   placeholder
- * @param {number}   maxRows — max visible rows before scroll (default 6)
  */
 export default function ChatInput({
   onSend,
@@ -19,9 +21,9 @@ export default function ChatInput({
   onStop,
   placeholder = "Type a message…",
   maxRows = 6,
-}) {
+}: ChatInputProps) {
   const [value, setValue] = useState("");
-  const textareaRef = useRef(null);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
 
   useEffect(() => {
     const ta = textareaRef.current;
@@ -41,7 +43,7 @@ export default function ChatInput({
     }
   }
 
-  function handleKeyDown(e) {
+  function handleKeyDown(e: React.KeyboardEvent<HTMLTextAreaElement>) {
     if (e.key === "Enter" && !e.shiftKey) {
       e.preventDefault();
       handleSend();

package/src/components/library/chat/{ChatMessage.jsx → ChatMessage.tsx}

@@ -1,9 +1,9 @@
 import React from "react";
 import { renderSchemaComponent } from "@/components/workspace/ComponentRegistry";
-import ChatToolCall from "./ChatToolCall";
+import ChatToolCall, { ToolCall } from "./ChatToolCall";
 import { UserCircleIcon, CpuChipIcon } from "@heroicons/react/24/solid";
 
-function cx(...classes) {
+function cx(...classes: (string | boolean | undefined)[]): string {
   return classes.filter(Boolean).join(" ");
 }
 
@@ -11,9 +11,9 @@ function cx(...classes) {
  * Lightweight inline formatter for assistant messages.
  * Handles code blocks, inline code, bold, italic, and line breaks.
  */
-function formatContent(text) {
+function formatContent(text: string): React.ReactNode {
   if (!text) return null;
-  const parts = [];
+  const parts: React.ReactNode[] = [];
   let key = 0;
 
   const codeBlockRegex = /```(\w*)\n?([\s\S]*?)```/g;
@@ -46,7 +46,7 @@ function formatContent(text) {
   return parts;
 }
 
-function formatInline(text) {
+function formatInline(text: string): React.ReactNode {
   const tokens = text.split(/(`[^`]+`|\*\*[^*]+\*\*|\*[^*]+\*)/g);
   return tokens.map((token, i) => {
     if (token.startsWith("**") && token.endsWith("**")) {
@@ -74,13 +74,26 @@ function formatInline(text) {
   });
 }
 
+export interface ChatMessageData {
+  id: string;
+  role: "user" | "assistant" | "system";
+  content?: string;
+  components?: unknown[];
+  toolCalls?: ToolCall[];
+  isError?: boolean;
+  isStreaming?: boolean;
+  timestamp?: string;
+}
+
+export interface ChatMessageProps {
+  message: ChatMessageData;
+  avatar?: React.ReactNode;
+}
+
 /**
  * Renders a single chat message.
- *
- * @param {Object} message — { id, role, content, components?, toolCalls?, isError?, isStreaming?, timestamp? }
- * @param {React.ReactNode} avatar — custom avatar override
  */
-export default function ChatMessage({ message, avatar }) {
+export default function ChatMessage({ message, avatar }: ChatMessageProps) {
   const isUser = message.role === "user";
   const isSystem = message.role === "system";
   const isAssistant = message.role === "assistant";

package/src/components/library/chat/{ChatMessageList.jsx → ChatMessageList.tsx}

@@ -1,17 +1,19 @@
 import React, { useRef, useEffect } from "react";
-import ChatMessage from "./ChatMessage";
+import ChatMessage, { ChatMessageData } from "./ChatMessage";
 import ChatTypingIndicator from "./ChatTypingIndicator";
 import ChatSuggestions from "./ChatSuggestions";
 
+export interface ChatMessageListProps {
+  messages?: ChatMessageData[];
+  isLoading?: boolean;
+  isStreaming?: boolean;
+  suggestions?: string[];
+  onSuggestion?: (text: string) => void;
+  renderAvatar?: (message: ChatMessageData) => React.ReactNode;
+}
+
 /**
  * Scrollable message area with auto-scroll to latest message.
- *
- * @param {Array}     messages — array of message objects
- * @param {boolean}   isLoading — show typing indicator
- * @param {boolean}   isStreaming — agent is streaming (show different indicator text)
- * @param {string[]}  suggestions — follow-up suggestions shown after last assistant message
- * @param {Function}  onSuggestion — (text) => void
- * @param {Function}  renderAvatar — (message) => ReactNode, optional per-message avatar
  */
 export default function ChatMessageList({
   messages = [],
@@ -20,9 +22,9 @@ export default function ChatMessageList({
   suggestions = [],
   onSuggestion,
   renderAvatar,
-}) {
-  const bottomRef = useRef(null);
-  const containerRef = useRef(null);
+}: ChatMessageListProps) {
+  const bottomRef = useRef<HTMLDivElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
     bottomRef.current?.scrollIntoView({ behavior: "smooth" });

package/src/components/library/chat/{ChatPanel.jsx → ChatPanel.tsx}

@@ -2,23 +2,26 @@ import React from "react";
 import ChatMessageList from "./ChatMessageList";
 import ChatInput from "./ChatInput";
 import ChatWelcome from "./ChatWelcome";
-import useChatState from "./useChatState";
+import useChatState, { UseChatStateOptions } from "./useChatState";
+import { ChatMessageData } from "./ChatMessage";
 import { TrashIcon } from "@heroicons/react/24/outline";
 
+export interface ChatPanelProps {
+  title?: string;
+  onSend?: UseChatStateOptions["onSend"];
+  initialMessages?: UseChatStateOptions["initialMessages"];
+  welcomeTitle?: string;
+  welcomeSubtitle?: string;
+  suggestions?: string[];
+  placeholder?: string;
+  className?: string;
+  renderAvatar?: (message: ChatMessageData) => React.ReactNode;
+  showHeader?: boolean;
+}
+
 /**
  * All-in-one chat panel. Composes ChatMessageList, ChatInput, ChatWelcome,
  * and useChatState into a single drop-in component.
- *
- * @param {string}   title — panel header title
- * @param {Function} onSend — async (userMessage, history, helpers) => assistantMessage?
- * @param {Array}    initialMessages — seed messages
- * @param {string}   welcomeTitle — welcome screen heading
- * @param {string}   welcomeSubtitle — welcome screen description
- * @param {string[]} suggestions — starter and follow-up prompts
- * @param {string}   placeholder — input placeholder
- * @param {string}   className — additional classes on the root container
- * @param {Function} renderAvatar — (message) => ReactNode
- * @param {boolean}  showHeader — show the title bar (default true)
  */
 export default function ChatPanel({
   title = "AI Assistant",
@@ -31,7 +34,7 @@ export default function ChatPanel({
   className = "",
   renderAvatar,
   showHeader = true,
-}) {
+}: ChatPanelProps) {
   const chat = useChatState({ initialMessages, onSend });
 
   const isEmpty = chat.messages.length === 0;