@schandlergarcia/sf-web-components 1.9.37 → 1.9.39

package/src/components/library/chat/ChatSuggestions.jsx

@@ -0,0 +1,28 @@
+import React from "react";
+import { SparklesIcon } from "@heroicons/react/24/outline";
+
+/**
+ * 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 }) {
+  if (!suggestions.length) return null;
+
+  return (
+    <div className="flex flex-wrap gap-2">
+      {suggestions.map((text) => (
+        <button
+          key={text}
+          type="button"
+          onClick={() => onSelect?.(text)}
+          className="inline-flex items-center gap-1.5 rounded-full border border-slate-200 bg-white px-3 py-1.5 text-xs font-medium text-slate-600 shadow-sm transition hover:border-brand-300 hover:bg-brand-50 hover:text-brand-700 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-300 dark:hover:border-brand-700 dark:hover:bg-brand-950/30 dark:hover:text-brand-300"
+        >
+          <SparklesIcon className="h-3 w-3" aria-hidden="true" />
+          {text}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/components/library/chat/ChatToolCall.jsx

@@ -0,0 +1,100 @@
+import React, { useState } from "react";
+import Spinner from "../ui/Spinner";
+import {
+  WrenchScrewdriverIcon,
+  CheckCircleIcon,
+  XCircleIcon,
+  ChevronDownIcon,
+} from "@heroicons/react/24/outline";
+
+const STATUS_CONFIG = {
+  running: {
+    icon: <Spinner size="xs" tone="brand" label="Running" />,
+    text: "text-brand-600 dark:text-brand-400",
+    bg: "bg-brand-50 border-brand-100 dark:bg-brand-950/20 dark:border-brand-900/30",
+    label: "Running",
+  },
+  complete: {
+    icon: <CheckCircleIcon className="h-3.5 w-3.5 text-emerald-500" />,
+    text: "text-emerald-700 dark:text-emerald-300",
+    bg: "bg-emerald-50 border-emerald-100 dark:bg-emerald-950/20 dark:border-emerald-900/30",
+    label: "Complete",
+  },
+  error: {
+    icon: <XCircleIcon className="h-3.5 w-3.5 text-red-500" />,
+    text: "text-red-700 dark:text-red-300",
+    bg: "bg-red-50 border-red-100 dark:bg-red-950/20 dark:border-red-900/30",
+    label: "Failed",
+  },
+};
+
+/**
+ * Displays an agent tool call / function execution step.
+ *
+ * @param {Object} toolCall — { id?, name, args?, status: "running"|"complete"|"error", result? }
+ */
+export default function ChatToolCall({ toolCall }) {
+  const [expanded, setExpanded] = useState(false);
+  const config = STATUS_CONFIG[toolCall.status] ?? STATUS_CONFIG.running;
+  const hasDetails = toolCall.args || toolCall.result;
+
+  return (
+    <div
+      className={[
+        "rounded-lg border text-xs",
+        config.bg,
+      ].join(" ")}
+    >
+      <button
+        type="button"
+        onClick={() => hasDetails && setExpanded(!expanded)}
+        className={[
+          "flex w-full items-center gap-2 px-3 py-1.5",
+          hasDetails ? "cursor-pointer" : "cursor-default",
+        ].join(" ")}
+      >
+        {config.icon}
+        <WrenchScrewdriverIcon className="h-3 w-3 text-slate-400 dark:text-slate-500" />
+        <span className={["font-medium", config.text].join(" ")}>
+          {toolCall.name}
+        </span>
+        <span className="text-slate-400 dark:text-slate-500">
+          — {config.label}
+        </span>
+        {hasDetails ? (
+          <ChevronDownIcon
+            className={[
+              "ml-auto h-3 w-3 text-slate-400 transition-transform dark:text-slate-500",
+              expanded ? "rotate-180" : "",
+            ].join(" ")}
+          />
+        ) : null}
+      </button>
+
+      {expanded && hasDetails ? (
+        <div className="border-t border-inherit px-3 py-2 font-mono text-[11px] leading-relaxed text-slate-600 dark:text-slate-300">
+          {toolCall.args ? (
+            <div className="mb-1">
+              <span className="font-sans font-semibold text-slate-500 dark:text-slate-400">
+                Args:{" "}
+              </span>
+              {typeof toolCall.args === "string"
+                ? toolCall.args
+                : JSON.stringify(toolCall.args, null, 2)}
+            </div>
+          ) : null}
+          {toolCall.result ? (
+            <div>
+              <span className="font-sans font-semibold text-slate-500 dark:text-slate-400">
+                Result:{" "}
+              </span>
+              {typeof toolCall.result === "string"
+                ? toolCall.result
+                : JSON.stringify(toolCall.result, null, 2)}
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/library/chat/ChatTypingIndicator.jsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { CpuChipIcon } from "@heroicons/react/24/solid";
+
+/**
+ * Animated typing indicator shown while the agent is processing.
+ */
+export default function ChatTypingIndicator({ label = "Thinking" }) {
+  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">
+        <CpuChipIcon className="h-4 w-4 text-brand-600 dark:text-brand-400" />
+      </div>
+      <div className="flex items-center gap-2 rounded-2xl rounded-tl-md bg-slate-100 px-4 py-3 dark:bg-slate-800">
+        <div className="flex gap-1">
+          <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-slate-400 dark:bg-slate-500 [animation-delay:0ms]" />
+          <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-slate-400 dark:bg-slate-500 [animation-delay:150ms]" />
+          <span className="h-1.5 w-1.5 animate-bounce rounded-full bg-slate-400 dark:bg-slate-500 [animation-delay:300ms]" />
+        </div>
+        <span className="text-xs text-slate-400 dark:text-slate-500">{label}</span>
+      </div>
+    </div>
+  );
+}

package/src/components/library/chat/ChatWelcome.jsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { CpuChipIcon } from "@heroicons/react/24/solid";
+import ChatSuggestions from "./ChatSuggestions";
+
+/**
+ * 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?",
+  subtitle = "Ask me anything about your data, or try one of the suggestions below.",
+  suggestions = [],
+  onSuggestion,
+  icon,
+}) {
+  return (
+    <div className="flex flex-1 flex-col items-center justify-center gap-4 px-6 py-12 text-center">
+      {icon ?? (
+        <div className="flex h-14 w-14 items-center justify-center rounded-2xl bg-brand-100 dark:bg-brand-900/40">
+          <CpuChipIcon className="h-7 w-7 text-brand-600 dark:text-brand-400" />
+        </div>
+      )}
+      <div>
+        <h3 className="text-base font-semibold text-slate-900 dark:text-slate-50">
+          {title}
+        </h3>
+        <p className="mt-1 text-sm text-slate-500 dark:text-slate-400">
+          {subtitle}
+        </p>
+      </div>
+      {suggestions.length ? (
+        <div className="mt-2">
+          <ChatSuggestions suggestions={suggestions} onSelect={onSuggestion} />
+        </div>
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,10 @@
+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";

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

@@ -0,0 +1,130 @@
+import { useState, useCallback, useRef } from "react";
+
+let _nextId = 1;
+function uid() {
+  return `msg-${Date.now()}-${_nextId++}`;
+}
+
+/**
+ * Core state management hook for AI chat.
+ *
+ * @param {Object} options
+ * @param {Array}  options.initialMessages — seed the conversation
+ * @param {Function} options.onSend — async (userMessage, allMessages) => assistantMessage | void
+ *   Return a message object to add it, or use appendChunk / addMessage for streaming.
+ *
+ * @returns {Object}
+ *
+ * @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 } = {}) {
+  const [messages, setMessages] = useState(() =>
+    initialMessages.map((m) => ({ id: uid(), timestamp: new Date().toISOString(), ...m }))
+  );
+  const [isLoading, setIsLoading] = useState(false);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState(null);
+  const onSendRef = useRef(onSend);
+  onSendRef.current = onSend;
+
+  const addMessage = useCallback((msg) => {
+    const full = { id: uid(), timestamp: new Date().toISOString(), ...msg };
+    setMessages((prev) => [...prev, full]);
+    return full.id;
+  }, []);
+
+  const updateMessage = useCallback((id, updates) => {
+    setMessages((prev) =>
+      prev.map((m) => (m.id === id ? { ...m, ...updates } : m))
+    );
+  }, []);
+
+  const appendChunk = useCallback((id, chunk) => {
+    setMessages((prev) =>
+      prev.map((m) =>
+        m.id === id ? { ...m, content: (m.content ?? "") + chunk } : m
+      )
+    );
+  }, []);
+
+  const removeMessage = useCallback((id) => {
+    setMessages((prev) => prev.filter((m) => m.id !== id));
+  }, []);
+
+  const clearMessages = useCallback(() => {
+    setMessages([]);
+    setError(null);
+  }, []);
+
+  const sendMessage = useCallback(
+    async (content, extra = {}) => {
+      if (!content?.trim()) return;
+      setError(null);
+
+      const userMsg = { role: "user", content: content.trim(), ...extra };
+      const userId = uid();
+      const fullUser = { ...userMsg, id: userId, timestamp: new Date().toISOString() };
+
+      setMessages((prev) => [...prev, fullUser]);
+      setIsLoading(true);
+
+      try {
+        const allMsgs = [...messages, fullUser];
+        const result = await onSendRef.current?.(fullUser, allMsgs, {
+          addMessage,
+          updateMessage,
+          appendChunk,
+          setStreaming: setIsStreaming,
+        });
+
+        if (result && typeof result === "object" && result.role) {
+          addMessage(result);
+        }
+      } catch (err) {
+        setError(err?.message ?? "Failed to send message");
+        addMessage({
+          role: "system",
+          content: 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

@@ -0,0 +1,67 @@
+import React from "react";
+
+const DataModeContext = React.createContext({
+  mode: "sample",
+  isSample: true,
+  isLive: false,
+  toggle: () => {},
+  setMode: () => {},
+});
+
+const STORAGE_KEY = "app-data-mode";
+const VALID_MODES = ["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() {
+  return React.useContext(DataModeContext);
+}
+
+/**
+ * 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);
+
+  React.useEffect(() => {
+    try {
+      const stored = window.localStorage.getItem(STORAGE_KEY);
+      if (VALID_MODES.includes(stored)) setModeState(stored);
+    } catch {
+      // SSR or storage unavailable
+    }
+  }, []);
+
+  React.useEffect(() => {
+    try {
+      window.localStorage.setItem(STORAGE_KEY, mode);
+    } catch {
+      // ignore
+    }
+  }, [mode]);
+
+  const setMode = React.useCallback((m) => {
+    if (VALID_MODES.includes(m)) setModeState(m);
+  }, []);
+
+  const value = React.useMemo(
+    () => ({
+      mode,
+      isSample: mode === "sample",
+      isLive: mode === "live",
+      toggle: () => setModeState((m) => (m === "sample" ? "live" : "sample")),
+      setMode,
+    }),
+    [mode, setMode]
+  );
+
+  return (
+    <DataModeContext.Provider value={value}>{children}</DataModeContext.Provider>
+  );
+}

package/src/components/library/data/DataModeToggle.jsx

@@ -0,0 +1,36 @@
+import React from "react";
+import { useDataMode } from "./DataModeProvider";
+import { BeakerIcon, SignalIcon } from "@heroicons/react/24/outline";
+
+/**
+ * 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 = "" }) {
+  const { mode, toggle } = useDataMode();
+  const isSample = mode === "sample";
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      className={[
+        "inline-flex items-center gap-1.5 rounded-lg border px-2.5 py-1.5 text-xs font-semibold shadow-sm transition",
+        isSample
+          ? "border-amber-200 bg-amber-50 text-amber-700 hover:bg-amber-100 dark:border-amber-800 dark:bg-amber-950/40 dark:text-amber-300 dark:hover:bg-amber-950/60"
+          : "border-emerald-200 bg-emerald-50 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-800 dark:bg-emerald-950/40 dark:text-emerald-300 dark:hover:bg-emerald-950/60",
+        className,
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      aria-label={`Data mode: ${mode}. Click to switch to ${isSample ? "live" : "sample"}.`}
+    >
+      {isSample ? (
+        <BeakerIcon className="h-3.5 w-3.5" aria-hidden="true" />
+      ) : (
+        <SignalIcon className="h-3.5 w-3.5" aria-hidden="true" />
+      )}
+      {isSample ? "Sample" : "Live"}
+    </button>
+  );
+}

package/src/components/library/data/chartDataProvider.jsx

@@ -0,0 +1,61 @@
+// 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 = {
+  sales_pipeline_qtr: {
+    title: "Sales Pipeline (Quarter)",
+    metrics: [
+      {
+        metricId: "pipeline_value",
+        title: "Pipeline",
+        subtitle: "This quarter",
+        value: "$1.28M",
+        change: "+6.2%",
+        changeType: "positive",
+        color: "primary",
+        trend: "vs last quarter"
+      },
+      {
+        metricId: "win_rate",
+        title: "Win rate",
+        subtitle: "Trailing 90 days",
+        value: "34%",
+        change: "+1.1%",
+        changeType: "positive",
+        color: "success"
+      }
+    ],
+    table: {
+      title: "Opportunities",
+      subtitle: "Pipeline opportunities",
+      columns: [
+        { key: "name", label: "Opportunity", sortable: true },
+        { key: "amount", label: "Amount", type: "currency", sortable: true, mono: true },
+        { key: "stage", label: "Stage", sortable: true },
+        { key: "owner", label: "Owner", sortable: true }
+      ],
+      rows: [
+        { id: 1, name: "Acme Renewal", amount: 125000, stage: "Negotiation", owner: "Sam" },
+        { id: 2, name: "Globex Expansion", amount: 420000, stage: "Discovery", owner: "Jules" },
+        { id: 3, name: "Initech New Logo", amount: 98000, stage: "Proposal", owner: "Riley" },
+        { id: 4, name: "Umbrella Upsell", amount: 56000, stage: "Qualification", owner: "Alex" }
+      ]
+    }
+  }
+};
+
+export function listSemanticIds() {
+  return Object.keys(SEMANTIC_DATASETS);
+}
+
+export function getSemanticDataset(semanticId) {
+  if (!semanticId) return null;
+  return SEMANTIC_DATASETS[semanticId] ?? null;
+}
+
+export function getSemanticMetric(semanticId, metricId) {
+  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

@@ -0,0 +1,141 @@
+/**
+ * Pure data utilities for filtering, sorting, and searching.
+ * Stateless — combine with usePageFilters hook for state management.
+ */
+
+/**
+ * Text search across multiple keys.
+ * @param {Array} data
+ * @param {string} query — search string
+ * @param {string[]} keys — object keys to search within
+ * @returns {Array} filtered data
+ */
+export function filterBySearch(data, query, keys = []) {
+  if (!query || !query.trim()) return data;
+  const q = query.trim().toLowerCase();
+  return data.filter((row) =>
+    keys.some((key) => {
+      const val = row?.[key];
+      return val != null && String(val).toLowerCase().includes(q);
+    })
+  );
+}
+
+/**
+ * Filter rows where key matches a specific value.
+ * Pass "all" or "" to skip filtering.
+ * @param {Array} data
+ * @param {string} key — object key to match
+ * @param {*} value — value to match (exact, case-insensitive for strings)
+ * @returns {Array}
+ */
+export function filterByValue(data, key, value) {
+  if (value == null || value === "" || value === "all") return data;
+  return data.filter((row) => {
+    const v = row?.[key];
+    if (typeof v === "string" && typeof value === "string") {
+      return v.toLowerCase() === value.toLowerCase();
+    }
+    return v === value;
+  });
+}
+
+/**
+ * Filter rows where a boolean condition is met.
+ * When toggle is off, returns all data (no filtering).
+ * @param {Array} data
+ * @param {string} key — object key to check
+ * @param {boolean} isActive — whether the toggle is on
+ * @param {*} matchValue — value that key should equal when active (default: truthy check)
+ * @returns {Array}
+ */
+export function filterByToggle(data, key, isActive, matchValue) {
+  if (!isActive) return data;
+  return data.filter((row) => {
+    const v = row?.[key];
+    if (matchValue !== undefined) return v === matchValue;
+    return Boolean(v);
+  });
+}
+
+/**
+ * Filter rows where a date field falls within a range.
+ * @param {Array} data
+ * @param {string} key — object key containing date (ISO string or Date)
+ * @param {{ start?: Date|string, end?: Date|string }} range
+ * @returns {Array}
+ */
+export function filterByDateRange(data, key, range) {
+  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];
+    if (raw == null) return false;
+    const d = raw instanceof Date ? raw : new Date(raw);
+    if (Number.isNaN(d.getTime())) return false;
+    if (start && d < start) return false;
+    if (end && d > end) return false;
+    return true;
+  });
+}
+
+/**
+ * Sort data by a key.
+ * @param {Array} data
+ * @param {string} key — object key to sort by
+ * @param {"asc"|"desc"} direction
+ * @returns {Array} new sorted array
+ */
+export function sortByKey(data, key, direction = "asc") {
+  if (!key) return data;
+  const dir = direction === "desc" ? -1 : 1;
+  return [...data].sort((a, b) => {
+    const av = a?.[key];
+    const bv = b?.[key];
+    if (av == null && bv == null) return 0;
+    if (av == null) return -1 * dir;
+    if (bv == null) return 1 * dir;
+    if (typeof av === "number" && typeof bv === "number") return (av - bv) * dir;
+    return String(av).localeCompare(String(bv)) * dir;
+  });
+}
+
+/**
+ * Apply a set of filter definitions to data.
+ * Each filter in `filters` has { id, type, key/keys } and `values` holds the current state.
+ *
+ * @param {Array} data
+ * @param {Array} filters — filter definitions [{ id, type, key?, keys? }]
+ * @param {Object} values — current filter values keyed by filter id
+ * @returns {Array} filtered data
+ */
+export function applyFilters(data, filters = [], values = {}) {
+  let result = data;
+
+  for (const filter of filters) {
+    const val = values[filter.id];
+    if (val === undefined || val === null) continue;
+
+    switch (filter.type) {
+      case "search":
+        result = filterBySearch(result, val, filter.keys ?? []);
+        break;
+      case "select":
+        result = filterByValue(result, filter.key, val);
+        break;
+      case "toggle":
+        result = filterByToggle(result, filter.key, val, filter.matchValue);
+        break;
+      case "dateRange":
+        result = filterByDateRange(result, filter.key, val);
+        break;
+      default:
+        break;
+    }
+  }
+
+  return result;
+}

package/src/components/library/data/useDataSource.jsx

@@ -0,0 +1,33 @@
+import { useMemo } from "react";
+import { useDataMode } from "./DataModeProvider";
+
+/**
+ * Select between sample and live data based on the global data mode.
+ *
+ * Values can be plain data or functions (lazy-evaluated only when active).
+ *
+ * @param {{ sample: any | () => any, live: any | () => any }} sources
+ * @returns {any} the resolved value for the active mode
+ *
+ * @example
+ * // Static data
+ * const incidents = useDataSource({
+ *   sample: sampleIncidents,
+ *   live: fetchedIncidents,
+ * });
+ *
+ * @example
+ * // Lazy — factory only runs when that mode is active
+ * const metrics = useDataSource({
+ *   sample: () => generateSampleMetrics(),
+ *   live: () => computeFromAPI(apiData),
+ * });
+ */
+export default function useDataSource({ sample, live }) {
+  const { mode } = useDataMode();
+
+  return useMemo(() => {
+    const source = mode === "sample" ? sample : live;
+    return typeof source === "function" ? source() : source;
+  }, [mode, sample, live]);
+}