@schandlergarcia/sf-web-components 1.7.0 → 1.9.0

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

@@ -1,13 +1,14 @@
-import React from "react";
 import { SparklesIcon } from "@heroicons/react/24/outline";
 
+export interface ChatSuggestionsProps {
+  suggestions?: string[];
+  onSelect?: (suggestion: string) => void;
+}
+
 /**
  * Quick-action prompt buttons. Place above the input or after an assistant message.
- *
- * @param {string[]} suggestions — prompt strings
- * @param {Function} onSelect — (suggestion) => void
  */
-export default function ChatSuggestions({ suggestions = [], onSelect }) {
+export default function ChatSuggestions({ suggestions = [], onSelect }: ChatSuggestionsProps) {
   if (!suggestions.length) return null;
 
   return (

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

@@ -1,4 +1,4 @@
-import React, { useState } from "react";
+import { useState } from "react";
 import Spinner from "../ui/Spinner";
 import {
   WrenchScrewdriverIcon,
@@ -7,6 +7,18 @@ import {
   ChevronDownIcon,
 } from "@heroicons/react/24/outline";
 
+export interface ToolCall {
+  id?: string;
+  name: string;
+  args?: unknown;
+  status: "running" | "complete" | "error";
+  result?: unknown;
+}
+
+export interface ChatToolCallProps {
+  toolCall: ToolCall;
+}
+
 const STATUS_CONFIG = {
   running: {
     icon: <Spinner size="xs" tone="brand" label="Running" />,
@@ -30,10 +42,8 @@ const STATUS_CONFIG = {
 
 /**
  * Displays an agent tool call / function execution step.
- *
- * @param {Object} toolCall — { id?, name, args?, status: "running"|"complete"|"error", result? }
  */
-export default function ChatToolCall({ toolCall }) {
+export default function ChatToolCall({ toolCall }: ChatToolCallProps) {
   const [expanded, setExpanded] = useState(false);
   const config = STATUS_CONFIG[toolCall.status] ?? STATUS_CONFIG.running;
   const hasDetails = toolCall.args || toolCall.result;

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

@@ -1,10 +1,13 @@
-import React from "react";
 import { CpuChipIcon } from "@heroicons/react/24/solid";
 
+export interface ChatTypingIndicatorProps {
+  label?: string;
+}
+
 /**
  * Animated typing indicator shown while the agent is processing.
  */
-export default function ChatTypingIndicator({ label = "Thinking" }) {
+export default function ChatTypingIndicator({ label = "Thinking" }: ChatTypingIndicatorProps) {
   return (
     <div className="flex items-start gap-3">
       <div className="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg bg-brand-100 dark:bg-brand-900/40">

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

@@ -2,14 +2,16 @@ import React from "react";
 import { CpuChipIcon } from "@heroicons/react/24/solid";
 import ChatSuggestions from "./ChatSuggestions";
 
+export interface ChatWelcomeProps {
+  title?: string;
+  subtitle?: string;
+  suggestions?: string[];
+  onSuggestion?: (text: string) => void;
+  icon?: React.ReactNode;
+}
+
 /**
  * Empty-state welcome screen shown before the first message.
- *
- * @param {string} title — welcome heading
- * @param {string} subtitle — description text
- * @param {string[]} suggestions — starter prompt suggestions
- * @param {Function} onSuggestion — (text) => void
- * @param {React.ReactNode} icon — custom icon override
  */
 export default function ChatWelcome({
   title = "How can I help?",
@@ -17,7 +19,7 @@ export default function ChatWelcome({
   suggestions = [],
   onSuggestion,
   icon,
-}) {
+}: ChatWelcomeProps) {
   return (
     <div className="flex flex-1 flex-col items-center justify-center gap-4 px-6 py-12 text-center">
       {icon ?? (

package/src/components/library/chat/index.tsx

@@ -0,0 +1,26 @@
+export { default as ChatPanel } from "./ChatPanel";
+export { default as ChatBar } from "./ChatBar";
+export { default as ChatMessageList } from "./ChatMessageList";
+export { default as ChatMessage } from "./ChatMessage";
+export { default as ChatInput } from "./ChatInput";
+export { default as ChatTypingIndicator } from "./ChatTypingIndicator";
+export { default as ChatSuggestions } from "./ChatSuggestions";
+export { default as ChatToolCall } from "./ChatToolCall";
+export { default as ChatWelcome } from "./ChatWelcome";
+export { default as useChatState } from "./useChatState";
+
+export type { ChatPanelProps } from "./ChatPanel";
+export type { ChatBarProps } from "./ChatBar";
+export type { ChatMessageListProps } from "./ChatMessageList";
+export type { ChatMessageProps, ChatMessageData } from "./ChatMessage";
+export type { ChatInputProps } from "./ChatInput";
+export type { ChatTypingIndicatorProps } from "./ChatTypingIndicator";
+export type { ChatSuggestionsProps } from "./ChatSuggestions";
+export type { ChatToolCallProps, ToolCall } from "./ChatToolCall";
+export type { ChatWelcomeProps } from "./ChatWelcome";
+export type {
+  UseChatStateOptions,
+  UseChatStateReturn,
+  ChatMessage as ChatMessageType,
+  ChatStateHelpers,
+} from "./useChatState";

package/src/components/library/chat/useChatState.tsx

@@ -0,0 +1,181 @@
+import { useState, useCallback, useRef } from "react";
+import { ToolCall } from "./ChatToolCall";
+
+let _nextId = 1;
+function uid(): string {
+  return `msg-${Date.now()}-${_nextId++}`;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: "user" | "assistant" | "system";
+  content?: string;
+  timestamp: string;
+  components?: unknown[];
+  toolCalls?: ToolCall[];
+  isError?: boolean;
+  isStreaming?: boolean;
+}
+
+export interface ChatStateHelpers {
+  addMessage: (msg: Partial<ChatMessage>) => string;
+  updateMessage: (id: string, updates: Partial<ChatMessage>) => void;
+  appendChunk: (id: string, chunk: string) => void;
+  setStreaming: (streaming: boolean) => void;
+}
+
+export interface UseChatStateOptions {
+  initialMessages?: Partial<ChatMessage>[];
+  onSend?: (
+    userMessage: ChatMessage,
+    allMessages: ChatMessage[],
+    helpers: ChatStateHelpers
+  ) => Promise<Partial<ChatMessage> | void>;
+}
+
+export interface UseChatStateReturn {
+  messages: ChatMessage[];
+  isLoading: boolean;
+  isStreaming: boolean;
+  error: string | null;
+  sendMessage: (content: string, extra?: Partial<ChatMessage>) => Promise<void>;
+  addMessage: (msg: Partial<ChatMessage>) => string;
+  updateMessage: (id: string, updates: Partial<ChatMessage>) => void;
+  appendChunk: (id: string, chunk: string) => void;
+  removeMessage: (id: string) => void;
+  clearMessages: () => void;
+  retryLast: () => void;
+  setError: (error: string | null) => void;
+}
+
+/**
+ * Core state management hook for AI chat.
+ *
+ * @example
+ * const chat = useChatState({
+ *   onSend: async (msg, history) => {
+ *     const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ messages: history }) });
+ *     const data = await res.json();
+ *     return { role: "assistant", content: data.reply, components: data.components };
+ *   },
+ * });
+ */
+export default function useChatState({ initialMessages = [], onSend }: UseChatStateOptions = {}): UseChatStateReturn {
+  const [messages, setMessages] = useState<ChatMessage[]>(() =>
+    initialMessages.map((m) => ({
+      id: uid(),
+      timestamp: new Date().toISOString(),
+      role: m.role || "user",
+      ...m
+    } as ChatMessage))
+  );
+  const [isLoading, setIsLoading] = useState(false);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const onSendRef = useRef(onSend);
+  onSendRef.current = onSend;
+
+  const addMessage = useCallback((msg: Partial<ChatMessage>): string => {
+    const full: ChatMessage = {
+      id: uid(),
+      timestamp: new Date().toISOString(),
+      role: msg.role || "assistant",
+      ...msg
+    } as ChatMessage;
+    setMessages((prev) => [...prev, full]);
+    return full.id;
+  }, []);
+
+  const updateMessage = useCallback((id: string, updates: Partial<ChatMessage>) => {
+    setMessages((prev) =>
+      prev.map((m) => (m.id === id ? { ...m, ...updates } : m))
+    );
+  }, []);
+
+  const appendChunk = useCallback((id: string, chunk: string) => {
+    setMessages((prev) =>
+      prev.map((m) =>
+        m.id === id ? { ...m, content: (m.content ?? "") + chunk } : m
+      )
+    );
+  }, []);
+
+  const removeMessage = useCallback((id: string) => {
+    setMessages((prev) => prev.filter((m) => m.id !== id));
+  }, []);
+
+  const clearMessages = useCallback(() => {
+    setMessages([]);
+    setError(null);
+  }, []);
+
+  const sendMessage = useCallback(
+    async (content: string, extra: Partial<ChatMessage> = {}) => {
+      if (!content?.trim()) return;
+      setError(null);
+
+      const userMsg: ChatMessage = {
+        role: "user",
+        content: content.trim(),
+        ...extra,
+        id: uid(),
+        timestamp: new Date().toISOString()
+      } as ChatMessage;
+
+      setMessages((prev) => [...prev, userMsg]);
+      setIsLoading(true);
+
+      try {
+        const allMsgs = [...messages, userMsg];
+        const result = await onSendRef.current?.(userMsg, allMsgs, {
+          addMessage,
+          updateMessage,
+          appendChunk,
+          setStreaming: setIsStreaming,
+        });
+
+        if (result && typeof result === "object" && result.role) {
+          addMessage(result);
+        }
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : "Failed to send message";
+        setError(errorMessage);
+        addMessage({
+          role: "system",
+          content: err instanceof Error ? err.message : "Something went wrong. Please try again.",
+          isError: true,
+        });
+      } finally {
+        setIsLoading(false);
+        setIsStreaming(false);
+      }
+    },
+    [messages, addMessage, updateMessage, appendChunk]
+  );
+
+  const retryLast = useCallback(() => {
+    const lastUser = [...messages].reverse().find((m) => m.role === "user");
+    if (!lastUser) return;
+
+    const idx = messages.lastIndexOf(lastUser);
+    setMessages(messages.slice(0, idx));
+    setError(null);
+
+    sendMessage(lastUser.content || "");
+  }, [messages, sendMessage]);
+
+  return {
+    messages,
+    isLoading,
+    isStreaming,
+    error,
+    sendMessage,
+    addMessage,
+    updateMessage,
+    appendChunk,
+    removeMessage,
+    clearMessages,
+    retryLast,
+    setError,
+  };
+}

package/src/components/library/data/{DataModeProvider.jsx → DataModeProvider.tsx}

@@ -1,6 +1,16 @@
 import React from "react";
 
-const DataModeContext = React.createContext({
+export type DataMode = "sample" | "live";
+
+export interface DataModeContextValue {
+  mode: DataMode;
+  isSample: boolean;
+  isLive: boolean;
+  toggle: () => void;
+  setMode: (mode: DataMode) => void;
+}
+
+const DataModeContext = React.createContext<DataModeContextValue>({
   mode: "sample",
   isSample: true,
   isLive: false,
@@ -9,30 +19,37 @@ const DataModeContext = React.createContext({
 });
 
 const STORAGE_KEY = "app-data-mode";
-const VALID_MODES = ["sample", "live"];
+const VALID_MODES: DataMode[] = ["sample", "live"];
 
 /**
  * Read the current data mode from any component.
  *
  * @returns {{ mode: "sample"|"live", isSample: boolean, isLive: boolean, toggle: () => void, setMode: (mode) => void }}
  */
-export function useDataMode() {
+export function useDataMode(): DataModeContextValue {
   return React.useContext(DataModeContext);
 }
 
+export interface DataModeProviderProps {
+  initialMode?: DataMode;
+  children: React.ReactNode;
+}
+
 /**
  * Provides global data-mode state (sample vs live) to the component tree.
  * Persists to localStorage so the choice survives page reloads.
  *
  * Wrap once in _app.js alongside AppThemeProvider.
  */
-export default function DataModeProvider({ initialMode = "sample", children }) {
-  const [mode, setModeState] = React.useState(initialMode);
+export default function DataModeProvider({ initialMode = "sample", children }: DataModeProviderProps) {
+  const [mode, setModeState] = React.useState<DataMode>(initialMode);
 
   React.useEffect(() => {
     try {
       const stored = window.localStorage.getItem(STORAGE_KEY);
-      if (VALID_MODES.includes(stored)) setModeState(stored);
+      if (stored && VALID_MODES.includes(stored as DataMode)) {
+        setModeState(stored as DataMode);
+      }
     } catch {
       // SSR or storage unavailable
     }
@@ -46,11 +63,11 @@ export default function DataModeProvider({ initialMode = "sample", children }) {
     }
   }, [mode]);
 
-  const setMode = React.useCallback((m) => {
+  const setMode = React.useCallback((m: DataMode) => {
     if (VALID_MODES.includes(m)) setModeState(m);
   }, []);
 
-  const value = React.useMemo(
+  const value = React.useMemo<DataModeContextValue>(
     () => ({
       mode,
       isSample: mode === "sample",

package/src/components/library/data/{DataModeToggle.jsx → DataModeToggle.tsx}

@@ -1,12 +1,15 @@
-import React from "react";
 import { useDataMode } from "./DataModeProvider";
 import { BeakerIcon, SignalIcon } from "@heroicons/react/24/outline";
 
+export interface DataModeToggleProps {
+  className?: string;
+}
+
 /**
  * Pill toggle for switching between sample and live data modes.
  * Place in the AppShell header next to the theme toggle.
  */
-export default function DataModeToggle({ className = "" }) {
+export default function DataModeToggle({ className = "" }: DataModeToggleProps) {
   const { mode, toggle } = useDataMode();
   const isSample = mode === "sample";
 

package/src/components/library/data/{chartDataProvider.jsx → chartDataProvider.tsx}

@@ -1,7 +1,52 @@
 // Minimal semantic data provider (seed data + lookup helpers).
 // This is intentionally local/in-memory for now; later we can swap to API-backed providers.
 
-const SEMANTIC_DATASETS = {
+export type ChangeType = "positive" | "negative" | "neutral";
+export type MetricColor = "primary" | "success" | "warning" | "danger";
+export type ColumnType = "currency" | "percentage" | "number" | "text";
+
+export interface SemanticMetric {
+  metricId: string;
+  title: string;
+  subtitle: string;
+  value: string;
+  change?: string;
+  changeType?: ChangeType;
+  color?: MetricColor;
+  trend?: string;
+}
+
+export interface TableColumn {
+  key: string;
+  label: string;
+  type?: ColumnType;
+  sortable?: boolean;
+  mono?: boolean;
+}
+
+export interface TableRow {
+  id: number;
+  [key: string]: any;
+}
+
+export interface SemanticTable {
+  title: string;
+  subtitle: string;
+  columns: TableColumn[];
+  rows: TableRow[];
+}
+
+export interface SemanticDataset {
+  title: string;
+  metrics?: SemanticMetric[];
+  table?: SemanticTable;
+}
+
+export interface SemanticDatasets {
+  [key: string]: SemanticDataset;
+}
+
+const SEMANTIC_DATASETS: SemanticDatasets = {
   sales_pipeline_qtr: {
     title: "Sales Pipeline (Quarter)",
     metrics: [
@@ -44,18 +89,17 @@ const SEMANTIC_DATASETS = {
   }
 };
 
-export function listSemanticIds() {
+export function listSemanticIds(): string[] {
   return Object.keys(SEMANTIC_DATASETS);
 }
 
-export function getSemanticDataset(semanticId) {
+export function getSemanticDataset(semanticId: string): SemanticDataset | null {
   if (!semanticId) return null;
   return SEMANTIC_DATASETS[semanticId] ?? null;
 }
 
-export function getSemanticMetric(semanticId, metricId) {
+export function getSemanticMetric(semanticId: string, metricId: string): SemanticMetric | null {
   const ds = getSemanticDataset(semanticId);
   if (!ds?.metrics) return null;
   return ds.metrics.find((m) => m.metricId === metricId) ?? null;
 }
-

package/src/components/library/data/{filterUtils.jsx → filterUtils.tsx}

@@ -3,6 +3,52 @@
  * Stateless — combine with usePageFilters hook for state management.
  */
 
+export type SortDirection = "asc" | "desc";
+
+export interface DateRange {
+  start?: Date | string;
+  end?: Date | string;
+}
+
+export type FilterType = "search" | "select" | "toggle" | "dateRange";
+
+export interface BaseFilterDefinition {
+  id: string;
+  type: FilterType;
+  defaultValue?: any;
+}
+
+export interface SearchFilterDefinition extends BaseFilterDefinition {
+  type: "search";
+  keys: string[];
+}
+
+export interface SelectFilterDefinition extends BaseFilterDefinition {
+  type: "select";
+  key: string;
+}
+
+export interface ToggleFilterDefinition extends BaseFilterDefinition {
+  type: "toggle";
+  key: string;
+  matchValue?: any;
+}
+
+export interface DateRangeFilterDefinition extends BaseFilterDefinition {
+  type: "dateRange";
+  key: string;
+}
+
+export type FilterDefinition =
+  | SearchFilterDefinition
+  | SelectFilterDefinition
+  | ToggleFilterDefinition
+  | DateRangeFilterDefinition;
+
+export interface FilterValues {
+  [key: string]: any;
+}
+
 /**
  * Text search across multiple keys.
  * @param {Array} data
@@ -10,12 +56,12 @@
  * @param {string[]} keys — object keys to search within
  * @returns {Array} filtered data
  */
-export function filterBySearch(data, query, keys = []) {
+export function filterBySearch<T>(data: T[], query: string, keys: string[] = []): T[] {
   if (!query || !query.trim()) return data;
   const q = query.trim().toLowerCase();
   return data.filter((row) =>
     keys.some((key) => {
-      const val = row?.[key];
+      const val = (row as any)?.[key];
       return val != null && String(val).toLowerCase().includes(q);
     })
   );
@@ -29,10 +75,10 @@ export function filterBySearch(data, query, keys = []) {
  * @param {*} value — value to match (exact, case-insensitive for strings)
  * @returns {Array}
  */
-export function filterByValue(data, key, value) {
+export function filterByValue<T>(data: T[], key: string, value: any): T[] {
   if (value == null || value === "" || value === "all") return data;
   return data.filter((row) => {
-    const v = row?.[key];
+    const v = (row as any)?.[key];
     if (typeof v === "string" && typeof value === "string") {
       return v.toLowerCase() === value.toLowerCase();
     }
@@ -49,10 +95,10 @@ export function filterByValue(data, key, value) {
  * @param {*} matchValue — value that key should equal when active (default: truthy check)
  * @returns {Array}
  */
-export function filterByToggle(data, key, isActive, matchValue) {
+export function filterByToggle<T>(data: T[], key: string, isActive: boolean, matchValue?: any): T[] {
   if (!isActive) return data;
   return data.filter((row) => {
-    const v = row?.[key];
+    const v = (row as any)?.[key];
     if (matchValue !== undefined) return v === matchValue;
     return Boolean(v);
   });
@@ -65,14 +111,14 @@ export function filterByToggle(data, key, isActive, matchValue) {
  * @param {{ start?: Date|string, end?: Date|string }} range
  * @returns {Array}
  */
-export function filterByDateRange(data, key, range) {
+export function filterByDateRange<T>(data: T[], key: string, range: DateRange | null): T[] {
   if (!range) return data;
   const start = range.start ? new Date(range.start) : null;
   const end = range.end ? new Date(range.end) : null;
   if (!start && !end) return data;
 
   return data.filter((row) => {
-    const raw = row?.[key];
+    const raw = (row as any)?.[key];
     if (raw == null) return false;
     const d = raw instanceof Date ? raw : new Date(raw);
     if (Number.isNaN(d.getTime())) return false;
@@ -89,12 +135,12 @@ export function filterByDateRange(data, key, range) {
  * @param {"asc"|"desc"} direction
  * @returns {Array} new sorted array
  */
-export function sortByKey(data, key, direction = "asc") {
+export function sortByKey<T>(data: T[], key: string, direction: SortDirection = "asc"): T[] {
   if (!key) return data;
   const dir = direction === "desc" ? -1 : 1;
   return [...data].sort((a, b) => {
-    const av = a?.[key];
-    const bv = b?.[key];
+    const av = (a as any)?.[key];
+    const bv = (b as any)?.[key];
     if (av == null && bv == null) return 0;
     if (av == null) return -1 * dir;
     if (bv == null) return 1 * dir;
@@ -112,7 +158,7 @@ export function sortByKey(data, key, direction = "asc") {
  * @param {Object} values — current filter values keyed by filter id
  * @returns {Array} filtered data
  */
-export function applyFilters(data, filters = [], values = {}) {
+export function applyFilters<T>(data: T[], filters: FilterDefinition[] = [], values: FilterValues = {}): T[] {
   let result = data;
 
   for (const filter of filters) {

package/src/components/library/data/{useDataSource.jsx → useDataSource.tsx}

@@ -1,6 +1,13 @@
 import { useMemo } from "react";
 import { useDataMode } from "./DataModeProvider";
 
+export type DataSourceValue<T> = T | (() => T);
+
+export interface UseDataSourceOptions<T> {
+  sample: DataSourceValue<T>;
+  live: DataSourceValue<T>;
+}
+
 /**
  * Select between sample and live data based on the global data mode.
  *
@@ -23,11 +30,11 @@ import { useDataMode } from "./DataModeProvider";
  *   live: () => computeFromAPI(apiData),
  * });
  */
-export default function useDataSource({ sample, live }) {
+export default function useDataSource<T>({ sample, live }: UseDataSourceOptions<T>): T {
   const { mode } = useDataMode();
 
   return useMemo(() => {
     const source = mode === "sample" ? sample : live;
-    return typeof source === "function" ? source() : source;
+    return typeof source === "function" ? (source as () => T)() : source;
   }, [mode, sample, live]);
 }