@schandlergarcia/sf-web-components 1.7.0 → 1.9.0

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

@@ -1,5 +1,41 @@
 import { useState, useMemo, useCallback } from "react";
-import { applyFilters, sortByKey } from "./filterUtils";
+import { applyFilters, sortByKey, FilterDefinition } from "./filterUtils";
+
+export type SortDirection = "asc" | "desc";
+
+export interface SortState {
+  key: string;
+  direction: SortDirection;
+}
+
+export interface DateRange {
+  start?: Date | string;
+  end?: Date | string;
+}
+
+export type FilterValue = string | boolean | DateRange | null;
+
+export interface FilterValues {
+  [key: string]: FilterValue;
+}
+
+export interface UsePageFiltersOptions<T> {
+  data?: T[];
+  filters?: FilterDefinition[];
+  defaultSort?: SortState | null;
+}
+
+export interface UsePageFiltersReturn<T> {
+  values: FilterValues;
+  setFilter: (id: string, value: FilterValue) => void;
+  resetFilters: () => void;
+  sort: SortState | null;
+  setSort: (key: string | null, direction?: SortDirection) => void;
+  toggleSort: (key: string) => void;
+  filteredData: T[];
+  sortedData: T[];
+  activeFilterCount: number;
+}
 
 /**
  * Hook for managing page-level filter and sort state.
@@ -21,9 +57,13 @@ import { applyFilters, sortByKey } from "./filterUtils";
  *   defaultSort: { key: "timestamp", direction: "desc" },
  * });
  */
-export default function usePageFilters({ data = [], filters = [], defaultSort = null } = {}) {
+export default function usePageFilters<T = any>({
+  data = [],
+  filters = [],
+  defaultSort = null,
+}: UsePageFiltersOptions<T> = {}): UsePageFiltersReturn<T> {
   const initialValues = useMemo(() => {
-    const v = {};
+    const v: FilterValues = {};
     for (const f of filters) {
       if (f.defaultValue !== undefined) {
         v[f.id] = f.defaultValue;
@@ -40,10 +80,10 @@ export default function usePageFilters({ data = [], filters = [], defaultSort =
     return v;
   }, [filters]);
 
-  const [values, setValues] = useState(initialValues);
-  const [sort, setSortState] = useState(defaultSort);
+  const [values, setValues] = useState<FilterValues>(initialValues);
+  const [sort, setSortState] = useState<SortState | null>(defaultSort);
 
-  const setFilter = useCallback((id, value) => {
+  const setFilter = useCallback((id: string, value: FilterValue) => {
     setValues((prev) => ({ ...prev, [id]: value }));
   }, []);
 
@@ -51,11 +91,11 @@ export default function usePageFilters({ data = [], filters = [], defaultSort =
     setValues(initialValues);
   }, [initialValues]);
 
-  const setSort = useCallback((key, direction) => {
+  const setSort = useCallback((key: string | null, direction?: SortDirection) => {
     setSortState(key ? { key, direction: direction ?? "asc" } : null);
   }, []);
 
-  const toggleSort = useCallback((key) => {
+  const toggleSort = useCallback((key: string) => {
     setSortState((prev) => {
       if (prev?.key !== key) return { key, direction: "asc" };
       if (prev.direction === "asc") return { key, direction: "desc" };
@@ -77,7 +117,7 @@ export default function usePageFilters({ data = [], filters = [], defaultSort =
     let count = 0;
     for (const f of filters) {
       const v = values[f.id];
-      if (f.type === "search" && v && v.trim()) count++;
+      if (f.type === "search" && v && typeof v === "string" && 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++;

package/src/components/library/filters/{FilterBar.jsx → FilterBar.tsx}

@@ -1,19 +1,29 @@
-import React from "react";
 import SearchFilter from "./SearchFilter";
-import SelectFilter from "./SelectFilter";
+import SelectFilter, { SelectOption } from "./SelectFilter";
 import ToggleFilter from "./ToggleFilter";
-import { FunnelIcon, XMarkIcon } from "@heroicons/react/24/outline";
+import { XMarkIcon } from "@heroicons/react/24/outline";
+
+export interface FilterDefinition {
+  id: string;
+  type: "search" | "select" | "toggle";
+  label?: string;
+  placeholder?: string;
+  options?: (string | SelectOption)[];
+  className?: string;
+}
+
+export interface FilterBarProps {
+  filters?: FilterDefinition[];
+  values?: Record<string, any>;
+  onChange?: (filterId: string, value: any) => void;
+  onReset?: () => void;
+  activeCount?: number;
+  layout?: "inline" | "stacked";
+}
 
 /**
  * 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 = [],
@@ -22,7 +32,7 @@ export default function FilterBar({
   onReset,
   activeCount = 0,
   layout = "inline",
-}) {
+}: FilterBarProps) {
   if (!filters.length) return null;
 
   const isStacked = layout === "stacked";

package/src/components/library/filters/{SearchFilter.jsx → SearchFilter.tsx}

@@ -1,12 +1,18 @@
-import React from "react";
 import { MagnifyingGlassIcon, XMarkIcon } from "@heroicons/react/24/outline";
 
+export interface SearchFilterProps {
+  value?: string;
+  onChange?: (value: string) => void;
+  placeholder?: string;
+  className?: string;
+}
+
 export default function SearchFilter({
   value = "",
   onChange,
   placeholder = "Search…",
   className = "",
-}) {
+}: SearchFilterProps) {
   return (
     <div className={["relative", className].filter(Boolean).join(" ")}>
       <MagnifyingGlassIcon

package/src/components/library/filters/{SelectFilter.jsx → SelectFilter.tsx}

@@ -1,14 +1,21 @@
-import React from "react";
 import { ChevronDownIcon } from "@heroicons/react/24/outline";
 
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+export interface SelectFilterProps {
+  value?: string;
+  onChange?: (value: string) => void;
+  options?: (string | SelectOption)[];
+  label?: string;
+  placeholder?: string;
+  className?: string;
+}
+
 /**
  * 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",
@@ -17,7 +24,7 @@ export default function SelectFilter({
   label,
   placeholder,
   className = "",
-}) {
+}: SelectFilterProps) {
   const normalizedOptions = options.map((opt) =>
     typeof opt === "string" ? { value: opt, label: opt } : opt
   );

package/src/components/library/filters/{ToggleFilter.jsx → ToggleFilter.tsx}

@@ -1,18 +1,19 @@
-import React from "react";
+export interface ToggleFilterProps {
+  value?: boolean;
+  onChange?: (value: boolean) => void;
+  label?: string;
+  className?: string;
+}
 
 /**
  * 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 = "",
-}) {
+}: ToggleFilterProps) {
   return (
     <label
       className={[

package/src/components/library/forms/{FormField.jsx → FormField.tsx}

@@ -1,5 +1,6 @@
-import React from "react";
+import * as React from "react";
 import { ChevronDownIcon } from "@heroicons/react/24/outline";
+import type { FormField as FormFieldType } from "./FormRenderer";
 
 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";
@@ -7,11 +8,17 @@ const INPUT_BASE =
 const INPUT_ERROR =
   "border-red-300 focus:ring-red-500 dark:border-red-700 dark:focus:ring-red-500";
 
-function cx(...classes) {
+function cx(...classes: (string | boolean | undefined)[]): string {
   return classes.filter(Boolean).join(" ");
 }
 
-function FieldLabel({ label, required, htmlFor }) {
+interface FieldLabelProps {
+  label?: string;
+  required?: boolean;
+  htmlFor: string;
+}
+
+function FieldLabel({ label, required, htmlFor }: FieldLabelProps) {
   if (!label) return null;
   return (
     <label htmlFor={htmlFor} className="block text-sm font-medium text-slate-700 dark:text-slate-200">
@@ -21,20 +28,36 @@ function FieldLabel({ label, required, htmlFor }) {
   );
 }
 
-function FieldError({ error }) {
+interface FieldErrorProps {
+  error?: string;
+}
+
+function FieldError({ error }: FieldErrorProps) {
   if (!error) return null;
   return <p className="text-xs text-red-600 dark:text-red-400">{error}</p>;
 }
 
-function FieldDescription({ description }) {
+interface FieldDescriptionProps {
+  description?: string;
+}
+
+function FieldDescription({ description }: FieldDescriptionProps) {
   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;
+interface FieldRendererProps {
+  field: FormFieldType & Record<string, unknown>;
+  value: unknown;
+  onChange: (value: unknown) => void;
+  onBlur: () => void;
+  error?: boolean;
+}
+
+function TextField({ field, value, onChange, onBlur, error }: FieldRendererProps) {
+  const inputType = (field.inputType as string | undefined) ?? field.type;
   const type = { text: "text", email: "email", url: "url", number: "number", date: "date" }[inputType] ?? "text";
 
   return (
@@ -42,32 +65,32 @@ function TextField({ field, value, onChange, onBlur, error }) {
       id={field.id}
       name={field.id}
       type={type}
-      value={value ?? ""}
+      value={(value as string | number) ?? ""}
       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}
+      placeholder={field.placeholder as string | undefined}
+      disabled={field.disabled as boolean | undefined}
+      readOnly={field.readOnly as boolean | undefined}
+      min={field.min as number | undefined}
+      max={field.max as number | undefined}
+      step={field.step as number | undefined}
       className={cx(INPUT_BASE, error && INPUT_ERROR)}
     />
   );
 }
 
-function TextareaField({ field, value, onChange, onBlur, error }) {
+function TextareaField({ field, value, onChange, onBlur, error }: FieldRendererProps) {
   return (
     <textarea
       id={field.id}
       name={field.id}
-      value={value ?? ""}
+      value={(value as string) ?? ""}
       onChange={(e) => onChange(e.target.value)}
       onBlur={onBlur}
-      placeholder={field.placeholder}
-      disabled={field.disabled}
-      readOnly={field.readOnly}
-      rows={field.rows ?? 3}
+      placeholder={field.placeholder as string | undefined}
+      disabled={field.disabled as boolean | undefined}
+      readOnly={field.readOnly as boolean | undefined}
+      rows={(field.rows as number | undefined) ?? 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
@@ -76,8 +99,13 @@ function TextareaField({ field, value, onChange, onBlur, error }) {
   );
 }
 
-function SelectField({ field, value, onChange, onBlur, error }) {
-  const options = (field.options ?? []).map((opt) =>
+interface SelectOption {
+  value: string;
+  label: string;
+}
+
+function SelectField({ field, value, onChange, onBlur, error }: FieldRendererProps) {
+  const options = ((field.options as (string | SelectOption)[] | undefined) ?? []).map((opt) =>
     typeof opt === "string" ? { value: opt, label: opt } : opt
   );
 
@@ -86,17 +114,17 @@ function SelectField({ field, value, onChange, onBlur, error }) {
       <select
         id={field.id}
         name={field.id}
-        value={value ?? ""}
+        value={(value as string) ?? ""}
         onChange={(e) => onChange(e.target.value)}
         onBlur={onBlur}
-        disabled={field.disabled}
+        disabled={field.disabled as boolean | undefined}
         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>
+          <option value="">{field.placeholder as string}</option>
         ) : null}
         {options.map((opt) => (
           <option key={opt.value} value={opt.value}>
@@ -112,11 +140,16 @@ function SelectField({ field, value, onChange, onBlur, error }) {
   );
 }
 
-function RadioField({ field, value, onChange }) {
-  const options = (field.options ?? []).map((opt) =>
+interface RadioOption extends SelectOption {
+  description?: string;
+  disabled?: boolean;
+}
+
+function RadioField({ field, value, onChange }: FieldRendererProps) {
+  const options = ((field.options as (string | RadioOption)[] | undefined) ?? []).map((opt) =>
     typeof opt === "string" ? { value: opt, label: opt } : opt
   );
-  const layout = field.layout ?? (options.length <= 4 ? "horizontal" : "vertical");
+  const layout = (field.layout as string | undefined) ?? (options.length <= 4 ? "horizontal" : "vertical");
 
   return (
     <div
@@ -138,7 +171,7 @@ function RadioField({ field, value, onChange }) {
             value={opt.value}
             checked={value === opt.value}
             onChange={() => onChange(opt.value)}
-            disabled={field.disabled || opt.disabled}
+            disabled={(field.disabled as boolean | undefined) || 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}
@@ -151,7 +184,7 @@ function RadioField({ field, value, onChange }) {
   );
 }
 
-function CheckboxField({ field, value, onChange }) {
+function CheckboxField({ field, value, onChange }: FieldRendererProps) {
   return (
     <label className="inline-flex cursor-pointer items-center gap-2.5 text-sm text-slate-700 dark:text-slate-200">
       <input
@@ -160,22 +193,26 @@ function CheckboxField({ field, value, onChange }) {
         name={field.id}
         checked={Boolean(value)}
         onChange={(e) => onChange(e.target.checked)}
-        disabled={field.disabled}
+        disabled={field.disabled as boolean | undefined}
         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}
+      {(field.checkboxLabel as string | undefined) ?? field.label}
     </label>
   );
 }
 
-function CheckboxGroupField({ field, value, onChange }) {
+interface CheckboxOption extends SelectOption {
+  disabled?: boolean;
+}
+
+function CheckboxGroupField({ field, value, onChange }: FieldRendererProps) {
   const selected = Array.isArray(value) ? value : [];
-  const options = (field.options ?? []).map((opt) =>
+  const options = ((field.options as (string | CheckboxOption)[] | undefined) ?? []).map((opt) =>
     typeof opt === "string" ? { value: opt, label: opt } : opt
   );
-  const layout = field.layout ?? (options.length <= 4 ? "horizontal" : "vertical");
+  const layout = (field.layout as string | undefined) ?? (options.length <= 4 ? "horizontal" : "vertical");
 
-  function toggleValue(optValue) {
+  function toggleValue(optValue: string) {
     const next = selected.includes(optValue)
       ? selected.filter((v) => v !== optValue)
       : [...selected, optValue];
@@ -198,7 +235,7 @@ function CheckboxGroupField({ field, value, onChange }) {
             type="checkbox"
             checked={selected.includes(opt.value)}
             onChange={() => toggleValue(opt.value)}
-            disabled={field.disabled || opt.disabled}
+            disabled={(field.disabled as boolean | undefined) || 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}
@@ -208,7 +245,7 @@ function CheckboxGroupField({ field, value, onChange }) {
   );
 }
 
-function ToggleField({ field, value, onChange }) {
+function ToggleField({ field, value, onChange }: FieldRendererProps) {
   const checked = Boolean(value);
 
   return (
@@ -218,7 +255,7 @@ function ToggleField({ field, value, onChange }) {
         role="switch"
         aria-checked={checked}
         onClick={() => onChange(!checked)}
-        disabled={field.disabled}
+        disabled={field.disabled as boolean | undefined}
         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",
@@ -234,7 +271,7 @@ function ToggleField({ field, value, onChange }) {
         />
       </button>
       {field.toggleLabel ? (
-        <span className="text-sm text-slate-700 dark:text-slate-200">{field.toggleLabel}</span>
+        <span className="text-sm text-slate-700 dark:text-slate-200">{field.toggleLabel as string}</span>
       ) : null}
     </div>
   );
@@ -242,7 +279,7 @@ function ToggleField({ field, value, onChange }) {
 
 // ─── Main FormField ───
 
-const FIELD_RENDERERS = {
+const FIELD_RENDERERS: Record<string, React.ComponentType<FieldRendererProps>> = {
   text: TextField,
   email: TextField,
   url: TextField,
@@ -256,11 +293,20 @@ const FIELD_RENDERERS = {
   toggle: ToggleField,
 };
 
+export interface FormFieldProps {
+  field: FormFieldType & Record<string, unknown>;
+  value: unknown;
+  error?: string;
+  touched?: boolean;
+  onChange: (value: unknown) => void;
+  onBlur: () => void;
+}
+
 /**
  * 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 }) {
+export default function FormField({ field, value, error, touched, onChange, onBlur }: FormFieldProps) {
   const Renderer = FIELD_RENDERERS[field.type];
   if (!Renderer) return null;
 
@@ -273,17 +319,17 @@ export default function FormField({ field, value, error, touched, onChange, onBl
         <FieldLabel label={field.label} required={field.required} htmlFor={field.id} />
       ) : null}
       {field.description && field.type !== "toggle" ? (
-        <FieldDescription description={field.description} />
+        <FieldDescription description={field.description as string} />
       ) : null}
       <Renderer
         field={field}
         value={value}
         onChange={onChange}
         onBlur={onBlur}
-        error={showError}
+        error={Boolean(showError)}
       />
       {field.type === "toggle" && field.description ? (
-        <FieldDescription description={field.description} />
+        <FieldDescription description={field.description as string} />
       ) : null}
       {showError ? <FieldError error={error} /> : null}
     </div>

package/src/components/library/forms/{FormModal.jsx → FormModal.tsx}

@@ -1,10 +1,11 @@
-import React, { useEffect, useCallback } from "react";
+import { useEffect, useCallback } from "react";
 import { createPortal } from "react-dom";
 import { motion, AnimatePresence } from "framer-motion";
 import { XMarkIcon } from "@heroicons/react/24/outline";
 import Spinner from "../ui/Spinner";
 import FormRenderer from "./FormRenderer";
 import useFormState from "./useFormState";
+import type { FormSection } from "./FormRenderer";
 
 const OVERLAY_VARIANTS = {
   hidden: { opacity: 0 },
@@ -13,35 +14,35 @@ const OVERLAY_VARIANTS = {
 
 const PANEL_VARIANTS = {
   hidden: { opacity: 0, y: 24, scale: 0.97 },
-  visible: { opacity: 1, y: 0, scale: 1, transition: { type: "spring", damping: 25, stiffness: 350 } },
+  visible: { opacity: 1, y: 0, scale: 1, transition: { type: "spring" as const, damping: 25, stiffness: 350 } },
   exit: { opacity: 0, y: 16, scale: 0.97, transition: { duration: 0.15 } },
 };
 
-/**
- * Size → max-width mapping.
- */
 const SIZE_CLASSES = {
   sm: "max-w-md",
   md: "max-w-xl",
   lg: "max-w-2xl",
   xl: "max-w-4xl",
-};
+} as const;
+
+export interface FormModalProps {
+  isOpen?: boolean;
+  onClose?: () => void;
+  title: string;
+  subtitle?: string;
+  sections?: FormSection[];
+  initialValues?: Record<string, unknown>;
+  onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+  submitLabel?: string;
+  cancelLabel?: string;
+  size?: keyof typeof SIZE_CLASSES;
+  destructive?: boolean;
+  minSubmitMs?: number;
+}
 
 /**
  * Modal dialog for creating or editing records.
  * Wraps FormRenderer + useFormState in an animated overlay.
- *
- * @param {boolean}  isOpen — whether the modal is visible
- * @param {Function} onClose — close handler
- * @param {string}   title — modal title (e.g. "Edit Service", "New Incident")
- * @param {string}   subtitle — optional subtitle
- * @param {Array}    sections — form schema sections
- * @param {Object}   initialValues — prefill for editing (empty = create mode)
- * @param {Function} onSubmit — async (values) => void, called on valid submit
- * @param {string}   submitLabel — submit button text (default: "Save")
- * @param {string}   cancelLabel — cancel button text (default: "Cancel")
- * @param {string}   size — "sm" | "md" | "lg" | "xl" (default: "lg")
- * @param {boolean}  destructive — if true, submit button is red (for delete confirmations)
  */
 export default function FormModal({
   isOpen = false,
@@ -56,7 +57,7 @@ export default function FormModal({
   size = "lg",
   destructive = false,
   minSubmitMs,
-}) {
+}: FormModalProps) {
   const form = useFormState({
     initialValues,
     sections,
@@ -73,7 +74,7 @@ export default function FormModal({
   }, [isOpen]);
 
   const onKeyDown = useCallback(
-    (e) => {
+    (e: KeyboardEvent) => {
       if (e.key === "Escape") onClose?.();
     },
     [onClose]

package/src/components/library/forms/{FormRenderer.jsx → FormRenderer.tsx}

@@ -1,17 +1,39 @@
-import React from "react";
 import FormSection from "./FormSection";
 
+export interface FormSection {
+  id?: string;
+  title?: string;
+  description?: string;
+  fields: FormField[];
+}
+
+export interface FormField {
+  id: string;
+  type: string;
+  label?: string;
+  placeholder?: string;
+  description?: string;
+  required?: boolean;
+  requiredMessage?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  validate?: (value: unknown, values: Record<string, unknown>) => string | undefined;
+  [key: string]: unknown;
+}
+
+export interface FormRendererProps {
+  sections?: FormSection[];
+  values?: Record<string, unknown>;
+  errors?: Record<string, string>;
+  touched?: Record<string, boolean>;
+  onFieldChange: (fieldId: string, value: unknown) => void;
+  onFieldBlur: (fieldId: string) => void;
+  formError?: string;
+}
+
 /**
  * Renders a complete form from a schema definition.
  * Pairs with useFormState for state management.
- *
- * @param {Array}    sections — form schema sections
- * @param {Object}   values   — current form values
- * @param {Object}   errors   — current validation errors
- * @param {Object}   touched  — which fields have been touched
- * @param {Function} onFieldChange — (fieldId, value) => void
- * @param {Function} onFieldBlur — (fieldId) => void
- * @param {string}   formError — top-level form error (e.g. submission failure)
  */
 export default function FormRenderer({
   sections = [],
@@ -21,7 +43,7 @@ export default function FormRenderer({
   onFieldChange,
   onFieldBlur,
   formError,
-}) {
+}: FormRendererProps) {
   return (
     <div className="space-y-8">
       {formError ? (