@schandlergarcia/sf-web-components 1.7.0 → 1.8.0

package/src/components/library/cards/{SemanticMetricCardWithLoading.jsx → SemanticMetricCardWithLoading.tsx}

@@ -1,5 +1,12 @@
 import React from "react";
-import SemanticMetricCard from "./SemanticMetricCard";
+import SemanticMetricCard, { SemanticMetricCardProps } from "./SemanticMetricCard";
+
+export interface SemanticMetricCardWithLoadingProps extends SemanticMetricCardProps {
+  simulateInitialLoad?: boolean;
+  minInitialDelayMs?: number;
+  maxInitialDelayMs?: number;
+  loading?: boolean;
+}
 
 export default function SemanticMetricCardWithLoading({
   simulateInitialLoad = true,
@@ -7,7 +14,7 @@ export default function SemanticMetricCardWithLoading({
   maxInitialDelayMs = 900,
   loading: loadingProp,
   ...props
-}) {
+}: SemanticMetricCardWithLoadingProps) {
   const [loading, setLoading] = React.useState(Boolean(simulateInitialLoad));
 
   React.useEffect(() => {
@@ -20,4 +27,3 @@ export default function SemanticMetricCardWithLoading({
 
   return <SemanticMetricCard loading={loadingProp ?? loading} {...props} />;
 }
-

package/src/components/library/cards/{SemanticTableCard.jsx → SemanticTableCard.tsx}

@@ -1,7 +1,19 @@
 import React from "react";
-import TableCard from "./TableCard";
+import TableCard, { TableCardProps, TableColumn } from "./TableCard";
 import { getSemanticDataset } from "../data/chartDataProvider";
 
+export interface SemanticTableCardProps extends Omit<TableCardProps, "data" | "columns"> {
+  semanticId: string;
+  dataOverride?: unknown[];
+  columnsOverride?: TableColumn[];
+  compact?: boolean;
+  striped?: boolean;
+  isDark?: boolean;
+  simulateInitialLoad?: boolean;
+  minInitialDelayMs?: number;
+  maxInitialDelayMs?: number;
+}
+
 export default function SemanticTableCard({
   semanticId,
   dataOverride,
@@ -19,7 +31,7 @@ export default function SemanticTableCard({
   minInitialDelayMs,
   maxInitialDelayMs,
   ...rest
-}) {
+}: SemanticTableCardProps) {
   const ds = React.useMemo(() => getSemanticDataset(semanticId), [semanticId]);
   const table = ds?.table;
 
@@ -45,4 +57,3 @@ export default function SemanticTableCard({
     />
   );
 }
-

package/src/components/library/cards/{SemanticTableCardWithLoading.jsx → SemanticTableCardWithLoading.tsx}

@@ -1,5 +1,11 @@
-import React from "react";
-import SemanticTableCard from "./SemanticTableCard";
+import SemanticTableCard, { SemanticTableCardProps } from "./SemanticTableCard";
+
+export interface SemanticTableCardWithLoadingProps extends SemanticTableCardProps {
+  simulateInitialLoad?: boolean;
+  minInitialDelayMs?: number;
+  maxInitialDelayMs?: number;
+  loading?: boolean;
+}
 
 export default function SemanticTableCardWithLoading({
   simulateInitialLoad = true,
@@ -7,8 +13,7 @@ export default function SemanticTableCardWithLoading({
   maxInitialDelayMs = 900,
   loading: loadingProp,
   ...props
-}) {
-  // Leverage TableCard's simulateInitialLoad by default; also allow explicit loading override.
+}: SemanticTableCardWithLoadingProps) {
   return (
     <SemanticTableCard
       {...props}
@@ -19,4 +24,3 @@ export default function SemanticTableCardWithLoading({
     />
   );
 }
-

package/src/components/library/cards/{StatusCard.jsx → StatusCard.tsx}

@@ -1,8 +1,17 @@
 import React from "react";
-import BaseCard from "./BaseCard";
+import BaseCard, { BaseCardProps } from "./BaseCard";
 import UIText from "../ui/Text";
 
-const STATUS_META = {
+type Status = "operational" | "degraded" | "outage" | "maintenance";
+type Layout = "list" | "grid" | "timeline";
+
+interface StatusMeta {
+  label: string;
+  dot: string;
+  chip: string;
+}
+
+const STATUS_META: Record<Status, StatusMeta> = {
   operational: {
     label: "Operational",
     dot: "bg-emerald-500",
@@ -25,15 +34,15 @@ const STATUS_META = {
   }
 };
 
-function normalizeStatus(status) {
+function normalizeStatus(status: string | undefined): Status {
   const s = String(status ?? "operational").toLowerCase();
   if (s === "ok" || s === "healthy" || s === "up") return "operational";
   if (s === "warn" || s === "warning" || s === "partial") return "degraded";
   if (s === "down" || s === "critical") return "outage";
-  return STATUS_META[s] ? s : "operational";
+  return STATUS_META[s as Status] ? (s as Status) : "operational";
 }
 
-function formatTimestamp(ts) {
+function formatTimestamp(ts: string | Date | undefined): string {
   if (!ts) return "";
   try {
     const d = ts instanceof Date ? ts : new Date(ts);
@@ -44,7 +53,11 @@ function formatTimestamp(ts) {
   }
 }
 
-function StatusChip({ status }) {
+interface StatusChipProps {
+  status: string | undefined;
+}
+
+function StatusChip({ status }: StatusChipProps) {
   const key = normalizeStatus(status);
   const meta = STATUS_META[key];
   return (
@@ -55,7 +68,23 @@ function StatusChip({ status }) {
   );
 }
 
-function ItemRow({ item, showTimestamp }) {
+export interface StatusItem {
+  id?: string | number;
+  title?: string;
+  name?: string;
+  description?: string;
+  status?: string;
+  timestamp?: string | Date;
+  value?: string | number;
+  unit?: string;
+}
+
+interface ItemRowProps {
+  item: StatusItem;
+  showTimestamp: boolean;
+}
+
+function ItemRow({ item, showTimestamp }: ItemRowProps) {
   const name = item?.title ?? item?.name ?? "Item";
   const desc = item?.description;
   const value = item?.value;
@@ -89,7 +118,12 @@ function ItemRow({ item, showTimestamp }) {
   );
 }
 
-function Timeline({ items, showTimestamp }) {
+interface TimelineProps {
+  items: StatusItem[];
+  showTimestamp: boolean;
+}
+
+function Timeline({ items, showTimestamp }: TimelineProps) {
   return (
     <div className="relative mt-4">
       <div className="absolute left-3 top-0 h-full w-px bg-slate-200 dark:bg-slate-800" aria-hidden="true" />
@@ -110,6 +144,21 @@ function Timeline({ items, showTimestamp }) {
   );
 }
 
+export interface StatusCardProps extends Omit<BaseCardProps, "variant" | "header" | "body"> {
+  title?: string;
+  subtitle?: string;
+  status?: string;
+  items?: StatusItem[];
+  layout?: Layout;
+  showProgress?: boolean;
+  showTimestamp?: boolean;
+  actions?: React.ReactNode;
+  loading?: boolean;
+  error?: string | Error;
+  emptyMessage?: string;
+  maxBodyHeight?: string | number;
+}
+
 export default function StatusCard({
   title,
   subtitle,
@@ -124,7 +173,7 @@ export default function StatusCard({
   emptyMessage = "No status items.",
   maxBodyHeight,
   ...cardProps
-}) {
+}: StatusCardProps) {
   const overall = normalizeStatus(status);
   const header = (
     <div className="flex items-start justify-between gap-3">
@@ -166,7 +215,9 @@ export default function StatusCard({
   const okCount = items.filter((it) => normalizeStatus(it?.status) === "operational").length;
   const percentOk = total > 0 ? Math.round((okCount / total) * 100) : 100;
 
-  const scrollStyle = maxBodyHeight ? { maxHeight: maxBodyHeight, overflowY: "auto" } : {};
+  const scrollStyle: React.CSSProperties = maxBodyHeight
+    ? { maxHeight: typeof maxBodyHeight === "number" ? `${maxBodyHeight}px` : maxBodyHeight, overflowY: "auto" }
+    : {};
 
   const itemsContent = loading ? (
     <div className="space-y-3">
@@ -216,5 +267,3 @@ export default function StatusCard({
 
   return <BaseCard variant="status" header={header} body={body} {...cardProps} />;
 }
-
-

package/src/components/library/cards/{TableCard.jsx → TableCard.tsx}

@@ -1,10 +1,12 @@
 import React from "react";
-import BaseCard from "./BaseCard";
+import BaseCard, { BaseCardProps } from "./BaseCard";
 import UIInput from "../ui/UIInput";
 import UIButton from "../ui/UIButton";
 import UIText from "../ui/Text";
 
-function defaultTypeFormat(type, value) {
+type ColumnType = "currency" | "percentage" | "number" | "text";
+
+function defaultTypeFormat(type: ColumnType | undefined, value: unknown): string {
   if (value == null) return "";
   if (!type) return String(value);
 
@@ -23,7 +25,7 @@ function defaultTypeFormat(type, value) {
   return String(value);
 }
 
-function stableSort(data, compare) {
+function stableSort<T>(data: T[], compare: (a: T, b: T) => number): T[] {
   return data
     .map((item, idx) => ({ item, idx }))
     .sort((a, b) => {
@@ -33,6 +35,44 @@ function stableSort(data, compare) {
     .map((x) => x.item);
 }
 
+export interface TableColumn {
+  key: string;
+  label: string;
+  type?: ColumnType;
+  sortable?: boolean;
+  mono?: boolean;
+  className?: string;
+  render?: (value: unknown, row: Record<string, unknown>) => React.ReactNode;
+}
+
+export interface SortState {
+  key: string;
+  direction: "asc" | "desc";
+}
+
+export interface TableCardProps extends Omit<BaseCardProps, "variant" | "header" | "body"> {
+  data?: Record<string, unknown>[];
+  columns?: TableColumn[];
+  title?: string;
+  subtitle?: string;
+  searchable?: boolean;
+  sortable?: boolean;
+  paginated?: boolean;
+  selectable?: boolean;
+  pageSize?: number;
+  actions?: React.ReactNode;
+  rowActions?: (row: Record<string, unknown>) => React.ReactNode;
+  onRowSelect?: (row: Record<string, unknown>) => void;
+  onSort?: (sort: SortState) => void;
+  onSearch?: (query: string) => void;
+  loading?: boolean;
+  error?: string | Error;
+  emptyMessage?: string;
+  simulateInitialLoad?: boolean;
+  minInitialDelayMs?: number;
+  maxInitialDelayMs?: number;
+}
+
 export default function TableCard({
   data = [],
   columns = [],
@@ -55,12 +95,12 @@ export default function TableCard({
   minInitialDelayMs = 350,
   maxInitialDelayMs = 900,
   ...cardProps
-}) {
+}: TableCardProps) {
   const [query, setQuery] = React.useState("");
-  const [sortKey, setSortKey] = React.useState(null);
-  const [sortDir, setSortDir] = React.useState("asc");
+  const [sortKey, setSortKey] = React.useState<string | null>(null);
+  const [sortDir, setSortDir] = React.useState<"asc" | "desc">("asc");
   const [page, setPage] = React.useState(1);
-  const [selectedId, setSelectedId] = React.useState(null);
+  const [selectedId, setSelectedId] = React.useState<string | number | undefined>(undefined);
   const [simLoading, setSimLoading] = React.useState(simulateInitialLoad);
 
   React.useEffect(() => {
@@ -163,7 +203,7 @@ export default function TableCard({
     );
   }
 
-  const canSort = (col) => sortable && (col.sortable ?? true);
+  const canSort = (col: TableColumn) => sortable && (col.sortable ?? true);
 
   return (
     <BaseCard
@@ -248,11 +288,12 @@ export default function TableCard({
                   </tr>
                 ) : (
                   pageData.map((row, idx) => {
-                    const rowId = row?.id ?? idx;
+                    const rawId = row?.id;
+                    const rowId: string | number = typeof rawId === "string" || typeof rawId === "number" ? rawId : idx;
                     const selected = selectable && selectedId === rowId;
                     return (
                       <tr
-                        key={rowId}
+                        key={String(rowId)}
                         className={[
                           "group",
                           selectable ? "cursor-pointer" : "",
@@ -333,5 +374,3 @@ export default function TableCard({
     />
   );
 }
-
-

package/src/components/library/cards/{WidgetCard.jsx → WidgetCard.tsx}

@@ -1,8 +1,22 @@
 import React from "react";
-import BaseCard from "./BaseCard";
+import BaseCard, { BaseCardProps } from "./BaseCard";
 import UIText from "../ui/Text";
 
-function Section({ title, actions, content, divided }) {
+export interface WidgetSection {
+  id?: string | number;
+  title?: string;
+  actions?: React.ReactNode;
+  content: React.ReactNode;
+}
+
+interface SectionProps {
+  title?: string;
+  actions?: React.ReactNode;
+  content: React.ReactNode;
+  divided: boolean;
+}
+
+function Section({ title, actions, content, divided }: SectionProps) {
   return (
     <div className={divided ? "border-t border-slate-200 pt-4 dark:border-slate-800" : ""}>
       {(title || actions) ? (
@@ -22,6 +36,17 @@ function Section({ title, actions, content, divided }) {
   );
 }
 
+export interface WidgetCardProps extends Omit<BaseCardProps, "variant" | "header" | "body"> {
+  header: React.ReactNode;
+  sections?: WidgetSection[];
+  footer?: React.ReactNode;
+  divided?: boolean;
+  collapsible?: boolean;
+  defaultExpanded?: boolean;
+  loading?: boolean;
+  emptyMessage?: string;
+}
+
 export default function WidgetCard({
   header,
   sections = [],
@@ -32,7 +57,7 @@ export default function WidgetCard({
   loading = false,
   emptyMessage = "No sections.",
   ...cardProps
-}) {
+}: WidgetCardProps) {
   const [expanded, setExpanded] = React.useState(defaultExpanded);
 
   const hdr = (
@@ -86,5 +111,3 @@ export default function WidgetCard({
 
   return <BaseCard variant="widget" header={hdr} body={body} {...cardProps} />;
 }
-
-

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