@schandlergarcia/sf-web-components 1.2.5 → 1.2.7

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]);
+}

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

@@ -0,0 +1,99 @@
+import { useState, useMemo, useCallback } from "react";
+import { applyFilters, sortByKey } from "./filterUtils";
+
+/**
+ * Hook for managing page-level filter and sort state.
+ *
+ * @param {Object} options
+ * @param {Array}  options.data — raw data array
+ * @param {Array}  options.filters — filter definitions [{ id, type, key?, keys?, defaultValue? }]
+ * @param {Object} options.defaultSort — { key, direction } or null
+ * @returns {Object} { values, setFilter, resetFilters, sort, setSort, filteredData, sortedData, activeFilterCount }
+ *
+ * @example
+ * const { values, setFilter, resetFilters, sortedData } = usePageFilters({
+ *   data: incidents,
+ *   filters: [
+ *     { id: "search", type: "search", keys: ["title", "description"] },
+ *     { id: "severity", type: "select", key: "severity", defaultValue: "all" },
+ *     { id: "active", type: "toggle", key: "resolved", matchValue: false },
+ *   ],
+ *   defaultSort: { key: "timestamp", direction: "desc" },
+ * });
+ */
+export default function usePageFilters({ data = [], filters = [], defaultSort = null } = {}) {
+  const initialValues = useMemo(() => {
+    const v = {};
+    for (const f of filters) {
+      if (f.defaultValue !== undefined) {
+        v[f.id] = f.defaultValue;
+      } else if (f.type === "search") {
+        v[f.id] = "";
+      } else if (f.type === "select") {
+        v[f.id] = "all";
+      } else if (f.type === "toggle") {
+        v[f.id] = false;
+      } else if (f.type === "dateRange") {
+        v[f.id] = null;
+      }
+    }
+    return v;
+  }, [filters]);
+
+  const [values, setValues] = useState(initialValues);
+  const [sort, setSortState] = useState(defaultSort);
+
+  const setFilter = useCallback((id, value) => {
+    setValues((prev) => ({ ...prev, [id]: value }));
+  }, []);
+
+  const resetFilters = useCallback(() => {
+    setValues(initialValues);
+  }, [initialValues]);
+
+  const setSort = useCallback((key, direction) => {
+    setSortState(key ? { key, direction: direction ?? "asc" } : null);
+  }, []);
+
+  const toggleSort = useCallback((key) => {
+    setSortState((prev) => {
+      if (prev?.key !== key) return { key, direction: "asc" };
+      if (prev.direction === "asc") return { key, direction: "desc" };
+      return null;
+    });
+  }, []);
+
+  const filteredData = useMemo(
+    () => applyFilters(data, filters, values),
+    [data, filters, values]
+  );
+
+  const sortedData = useMemo(
+    () => (sort ? sortByKey(filteredData, sort.key, sort.direction) : filteredData),
+    [filteredData, sort]
+  );
+
+  const activeFilterCount = useMemo(() => {
+    let count = 0;
+    for (const f of filters) {
+      const v = values[f.id];
+      if (f.type === "search" && v && v.trim()) count++;
+      else if (f.type === "select" && v && v !== "all") count++;
+      else if (f.type === "toggle" && v) count++;
+      else if (f.type === "dateRange" && v) count++;
+    }
+    return count;
+  }, [filters, values]);
+
+  return {
+    values,
+    setFilter,
+    resetFilters,
+    sort,
+    setSort,
+    toggleSort,
+    filteredData,
+    sortedData,
+    activeFilterCount,
+  };
+}

package/src/components/library/filters/FilterBar.jsx

@@ -0,0 +1,95 @@
+import React from "react";
+import SearchFilter from "./SearchFilter";
+import SelectFilter from "./SelectFilter";
+import ToggleFilter from "./ToggleFilter";
+import { FunnelIcon, XMarkIcon } from "@heroicons/react/24/outline";
+
+/**
+ * Renders a row of filter controls from a definitions array.
+ * Pairs with usePageFilters hook for state management.
+ *
+ * @param {Array}    filters — filter definitions [{ id, type, ... }]
+ * @param {Object}   values  — current filter values keyed by filter id
+ * @param {Function} onChange — (filterId, value) => void
+ * @param {Function} onReset  — () => void
+ * @param {number}   activeCount — number of active filters (for badge)
+ * @param {string}   layout — "inline" (default) or "stacked"
+ */
+export default function FilterBar({
+  filters = [],
+  values = {},
+  onChange,
+  onReset,
+  activeCount = 0,
+  layout = "inline",
+}) {
+  if (!filters.length) return null;
+
+  const isStacked = layout === "stacked";
+
+  return (
+    <div
+      className={[
+        "flex gap-3",
+        isStacked
+          ? "flex-col"
+          : "flex-col sm:flex-row sm:flex-wrap sm:items-center",
+      ].join(" ")}
+    >
+      {filters.map((filter) => {
+        const val = values[filter.id];
+
+        switch (filter.type) {
+          case "search":
+            return (
+              <SearchFilter
+                key={filter.id}
+                value={val ?? ""}
+                onChange={(v) => onChange?.(filter.id, v)}
+                placeholder={filter.placeholder ?? "Search…"}
+                className={filter.className ?? (isStacked ? "w-full" : "w-full sm:w-64")}
+              />
+            );
+
+          case "select":
+            return (
+              <SelectFilter
+                key={filter.id}
+                value={val ?? "all"}
+                onChange={(v) => onChange?.(filter.id, v)}
+                options={filter.options ?? []}
+                label={filter.label}
+                placeholder={filter.placeholder ?? "All"}
+                className={filter.className}
+              />
+            );
+
+          case "toggle":
+            return (
+              <ToggleFilter
+                key={filter.id}
+                value={val ?? false}
+                onChange={(v) => onChange?.(filter.id, v)}
+                label={filter.label}
+                className={filter.className}
+              />
+            );
+
+          default:
+            return null;
+        }
+      })}
+
+      {activeCount > 0 && onReset ? (
+        <button
+          type="button"
+          onClick={onReset}
+          className="inline-flex items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-xs font-medium text-slate-500 transition hover:bg-slate-100 hover:text-slate-700 dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-200"
+        >
+          <XMarkIcon className="h-3.5 w-3.5" aria-hidden="true" />
+          Clear {activeCount} {activeCount === 1 ? "filter" : "filters"}
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/components/library/filters/SearchFilter.jsx

@@ -0,0 +1,36 @@
+import React from "react";
+import { MagnifyingGlassIcon, XMarkIcon } from "@heroicons/react/24/outline";
+
+export default function SearchFilter({
+  value = "",
+  onChange,
+  placeholder = "Search…",
+  className = "",
+}) {
+  return (
+    <div className={["relative", className].filter(Boolean).join(" ")}>
+      <MagnifyingGlassIcon
+        className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-slate-400 dark:text-slate-500"
+        aria-hidden="true"
+      />
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => onChange?.(e.target.value)}
+        placeholder={placeholder}
+        className="h-9 w-full rounded-lg border border-slate-200 bg-white pl-9 pr-8 text-sm text-slate-900 shadow-sm placeholder:text-slate-400 focus:outline-none focus:ring-2 focus:ring-brand-500 focus:ring-offset-2 dark:border-slate-800 dark:bg-slate-900 dark:text-slate-50 dark:placeholder:text-slate-500 dark:focus:ring-offset-slate-950"
+        aria-label={placeholder}
+      />
+      {value ? (
+        <button
+          type="button"
+          onClick={() => onChange?.("")}
+          className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-slate-400 hover:text-slate-600 dark:text-slate-500 dark:hover:text-slate-300"
+          aria-label="Clear search"
+        >
+          <XMarkIcon className="h-4 w-4" />
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/components/library/filters/SelectFilter.jsx

@@ -0,0 +1,55 @@
+import React from "react";
+import { ChevronDownIcon } from "@heroicons/react/24/outline";
+
+/**
+ * Dropdown select filter.
+ *
+ * @param {string} value — current selected value
+ * @param {Function} onChange — (value) => void
+ * @param {Array} options — [{ value, label }] or ["string", ...]
+ * @param {string} label — visible label
+ * @param {string} placeholder — placeholder when no value selected
+ */
+export default function SelectFilter({
+  value = "all",
+  onChange,
+  options = [],
+  label,
+  placeholder,
+  className = "",
+}) {
+  const normalizedOptions = options.map((opt) =>
+    typeof opt === "string" ? { value: opt, label: opt } : opt
+  );
+
+  return (
+    <div className={["relative inline-flex items-center gap-2", className].filter(Boolean).join(" ")}>
+      {label ? (
+        <span className="shrink-0 text-xs font-medium text-slate-500 dark:text-slate-400">
+          {label}
+        </span>
+      ) : null}
+      <div className="relative">
+        <select
+          value={value}
+          onChange={(e) => onChange?.(e.target.value)}
+          className="h-9 appearance-none rounded-lg border border-slate-200 bg-white py-0 pl-3 pr-8 text-sm font-medium text-slate-700 shadow-sm focus:outline-none focus:ring-2 focus:ring-brand-500 focus:ring-offset-2 dark:border-slate-800 dark:bg-slate-900 dark:text-slate-200 dark:focus:ring-offset-slate-950"
+          aria-label={label ?? placeholder ?? "Filter"}
+        >
+          {placeholder ? (
+            <option value="all">{placeholder}</option>
+          ) : null}
+          {normalizedOptions.map((opt) => (
+            <option key={opt.value} value={opt.value}>
+              {opt.label}
+            </option>
+          ))}
+        </select>
+        <ChevronDownIcon
+          className="pointer-events-none absolute right-2 top-1/2 h-4 w-4 -translate-y-1/2 text-slate-400 dark:text-slate-500"
+          aria-hidden="true"
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/library/filters/ToggleFilter.jsx

@@ -0,0 +1,52 @@
+import React from "react";
+
+/**
+ * Toggle switch filter.
+ *
+ * @param {boolean} value — current on/off state
+ * @param {Function} onChange — (boolean) => void
+ * @param {string} label — visible label
+ */
+export default function ToggleFilter({
+  value = false,
+  onChange,
+  label,
+  className = "",
+}) {
+  return (
+    <label
+      className={[
+        "inline-flex cursor-pointer items-center gap-2",
+        className,
+      ]
+        .filter(Boolean)
+        .join(" ")}
+    >
+      <button
+        type="button"
+        role="switch"
+        aria-checked={value}
+        onClick={() => onChange?.(!value)}
+        className={[
+          "relative inline-flex h-5 w-9 shrink-0 rounded-full border-2 border-transparent transition-colors focus:outline-none focus:ring-2 focus:ring-brand-500 focus:ring-offset-2 dark:focus:ring-offset-slate-950",
+          value
+            ? "bg-brand-500"
+            : "bg-slate-200 dark:bg-slate-700",
+        ].join(" ")}
+      >
+        <span
+          aria-hidden="true"
+          className={[
+            "pointer-events-none inline-block h-4 w-4 rounded-full bg-white shadow ring-0 transition-transform",
+            value ? "translate-x-4" : "translate-x-0",
+          ].join(" ")}
+        />
+      </button>
+      {label ? (
+        <span className="text-sm font-medium text-slate-700 dark:text-slate-200">
+          {label}
+        </span>
+      ) : null}
+    </label>
+  );
+}

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

@@ -0,0 +1,4 @@
+export { default as FilterBar } from "./FilterBar";
+export { default as SearchFilter } from "./SearchFilter";
+export { default as SelectFilter } from "./SelectFilter";
+export { default as ToggleFilter } from "./ToggleFilter";