@schandlergarcia/sf-web-components 1.9.37 → 1.9.39

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";

package/src/components/library/forms/FormField.jsx

@@ -0,0 +1,291 @@
+import React from "react";
+import { ChevronDownIcon } from "@heroicons/react/24/outline";
+
+const INPUT_BASE =
+  "h-10 w-full rounded-lg border border-slate-200 bg-white px-3 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";
+
+const INPUT_ERROR =
+  "border-red-300 focus:ring-red-500 dark:border-red-700 dark:focus:ring-red-500";
+
+function cx(...classes) {
+  return classes.filter(Boolean).join(" ");
+}
+
+function FieldLabel({ label, required, htmlFor }) {
+  if (!label) return null;
+  return (
+    <label htmlFor={htmlFor} className="block text-sm font-medium text-slate-700 dark:text-slate-200">
+      {label}
+      {required ? <span className="ml-0.5 text-red-500">*</span> : null}
+    </label>
+  );
+}
+
+function FieldError({ error }) {
+  if (!error) return null;
+  return <p className="text-xs text-red-600 dark:text-red-400">{error}</p>;
+}
+
+function FieldDescription({ description }) {
+  if (!description) return null;
+  return <p className="text-xs text-slate-500 dark:text-slate-400">{description}</p>;
+}
+
+// ─── Individual field renderers ───
+
+function TextField({ field, value, onChange, onBlur, error }) {
+  const inputType = field.inputType ?? field.type;
+  const type = { text: "text", email: "email", url: "url", number: "number", date: "date" }[inputType] ?? "text";
+
+  return (
+    <input
+      id={field.id}
+      name={field.id}
+      type={type}
+      value={value ?? ""}
+      onChange={(e) => onChange(field.type === "number" ? e.target.value : e.target.value)}
+      onBlur={onBlur}
+      placeholder={field.placeholder}
+      disabled={field.disabled}
+      readOnly={field.readOnly}
+      min={field.min}
+      max={field.max}
+      step={field.step}
+      className={cx(INPUT_BASE, error && INPUT_ERROR)}
+    />
+  );
+}
+
+function TextareaField({ field, value, onChange, onBlur, error }) {
+  return (
+    <textarea
+      id={field.id}
+      name={field.id}
+      value={value ?? ""}
+      onChange={(e) => onChange(e.target.value)}
+      onBlur={onBlur}
+      placeholder={field.placeholder}
+      disabled={field.disabled}
+      readOnly={field.readOnly}
+      rows={field.rows ?? 3}
+      className={cx(
+        "w-full rounded-lg border border-slate-200 bg-white px-3 py-2 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",
+        error && INPUT_ERROR
+      )}
+    />
+  );
+}
+
+function SelectField({ field, value, onChange, onBlur, error }) {
+  const options = (field.options ?? []).map((opt) =>
+    typeof opt === "string" ? { value: opt, label: opt } : opt
+  );
+
+  return (
+    <div className="relative">
+      <select
+        id={field.id}
+        name={field.id}
+        value={value ?? ""}
+        onChange={(e) => onChange(e.target.value)}
+        onBlur={onBlur}
+        disabled={field.disabled}
+        className={cx(
+          "h-10 w-full appearance-none rounded-lg border border-slate-200 bg-white py-0 pl-3 pr-9 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",
+          error && INPUT_ERROR
+        )}
+      >
+        {field.placeholder ? (
+          <option value="">{field.placeholder}</option>
+        ) : null}
+        {options.map((opt) => (
+          <option key={opt.value} value={opt.value}>
+            {opt.label}
+          </option>
+        ))}
+      </select>
+      <ChevronDownIcon
+        className="pointer-events-none absolute right-2.5 top-1/2 h-4 w-4 -translate-y-1/2 text-slate-400 dark:text-slate-500"
+        aria-hidden="true"
+      />
+    </div>
+  );
+}
+
+function RadioField({ field, value, onChange }) {
+  const options = (field.options ?? []).map((opt) =>
+    typeof opt === "string" ? { value: opt, label: opt } : opt
+  );
+  const layout = field.layout ?? (options.length <= 4 ? "horizontal" : "vertical");
+
+  return (
+    <div
+      className={cx(
+        "flex gap-3",
+        layout === "vertical" ? "flex-col" : "flex-row flex-wrap"
+      )}
+      role="radiogroup"
+      aria-labelledby={`${field.id}-label`}
+    >
+      {options.map((opt) => (
+        <label
+          key={opt.value}
+          className="inline-flex cursor-pointer items-center gap-2 text-sm text-slate-700 dark:text-slate-200"
+        >
+          <input
+            type="radio"
+            name={field.id}
+            value={opt.value}
+            checked={value === opt.value}
+            onChange={() => onChange(opt.value)}
+            disabled={field.disabled || opt.disabled}
+            className="h-4 w-4 border-slate-300 text-brand-600 focus:ring-brand-500 dark:border-slate-600 dark:bg-slate-800"
+          />
+          {opt.label}
+          {opt.description ? (
+            <span className="text-xs text-slate-400 dark:text-slate-500">{opt.description}</span>
+          ) : null}
+        </label>
+      ))}
+    </div>
+  );
+}
+
+function CheckboxField({ field, value, onChange }) {
+  return (
+    <label className="inline-flex cursor-pointer items-center gap-2.5 text-sm text-slate-700 dark:text-slate-200">
+      <input
+        type="checkbox"
+        id={field.id}
+        name={field.id}
+        checked={Boolean(value)}
+        onChange={(e) => onChange(e.target.checked)}
+        disabled={field.disabled}
+        className="h-4 w-4 rounded border-slate-300 text-brand-600 focus:ring-brand-500 dark:border-slate-600 dark:bg-slate-800"
+      />
+      {field.checkboxLabel ?? field.label}
+    </label>
+  );
+}
+
+function CheckboxGroupField({ field, value, onChange }) {
+  const selected = Array.isArray(value) ? value : [];
+  const options = (field.options ?? []).map((opt) =>
+    typeof opt === "string" ? { value: opt, label: opt } : opt
+  );
+  const layout = field.layout ?? (options.length <= 4 ? "horizontal" : "vertical");
+
+  function toggleValue(optValue) {
+    const next = selected.includes(optValue)
+      ? selected.filter((v) => v !== optValue)
+      : [...selected, optValue];
+    onChange(next);
+  }
+
+  return (
+    <div
+      className={cx(
+        "flex gap-3",
+        layout === "vertical" ? "flex-col" : "flex-row flex-wrap"
+      )}
+    >
+      {options.map((opt) => (
+        <label
+          key={opt.value}
+          className="inline-flex cursor-pointer items-center gap-2 text-sm text-slate-700 dark:text-slate-200"
+        >
+          <input
+            type="checkbox"
+            checked={selected.includes(opt.value)}
+            onChange={() => toggleValue(opt.value)}
+            disabled={field.disabled || opt.disabled}
+            className="h-4 w-4 rounded border-slate-300 text-brand-600 focus:ring-brand-500 dark:border-slate-600 dark:bg-slate-800"
+          />
+          {opt.label}
+        </label>
+      ))}
+    </div>
+  );
+}
+
+function ToggleField({ field, value, onChange }) {
+  const checked = Boolean(value);
+
+  return (
+    <div className="flex items-center gap-3">
+      <button
+        type="button"
+        role="switch"
+        aria-checked={checked}
+        onClick={() => onChange(!checked)}
+        disabled={field.disabled}
+        className={cx(
+          "relative inline-flex h-6 w-11 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",
+          checked ? "bg-brand-500" : "bg-slate-200 dark:bg-slate-700",
+          field.disabled && "cursor-not-allowed opacity-60"
+        )}
+      >
+        <span
+          aria-hidden="true"
+          className={cx(
+            "pointer-events-none inline-block h-5 w-5 rounded-full bg-white shadow ring-0 transition-transform",
+            checked ? "translate-x-5" : "translate-x-0"
+          )}
+        />
+      </button>
+      {field.toggleLabel ? (
+        <span className="text-sm text-slate-700 dark:text-slate-200">{field.toggleLabel}</span>
+      ) : null}
+    </div>
+  );
+}
+
+// ─── Main FormField ───
+
+const FIELD_RENDERERS = {
+  text: TextField,
+  email: TextField,
+  url: TextField,
+  number: TextField,
+  date: TextField,
+  textarea: TextareaField,
+  select: SelectField,
+  radio: RadioField,
+  checkbox: CheckboxField,
+  checkboxGroup: CheckboxGroupField,
+  toggle: ToggleField,
+};
+
+/**
+ * Renders a single form field with label, description, error message,
+ * and the appropriate input type.
+ */
+export default function FormField({ field, value, error, touched, onChange, onBlur }) {
+  const Renderer = FIELD_RENDERERS[field.type];
+  if (!Renderer) return null;
+
+  const showError = error && touched;
+  const noLabel = field.type === "checkbox";
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      {!noLabel ? (
+        <FieldLabel label={field.label} required={field.required} htmlFor={field.id} />
+      ) : null}
+      {field.description && field.type !== "toggle" ? (
+        <FieldDescription description={field.description} />
+      ) : null}
+      <Renderer
+        field={field}
+        value={value}
+        onChange={onChange}
+        onBlur={onBlur}
+        error={showError}
+      />
+      {field.type === "toggle" && field.description ? (
+        <FieldDescription description={field.description} />
+      ) : null}
+      {showError ? <FieldError error={error} /> : null}
+    </div>
+  );
+}