@schandlergarcia/sf-web-components 1.7.0 → 1.8.0

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 ? (

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

@@ -1,15 +1,21 @@
-import React from "react";
 import FormField from "./FormField";
+import type { FormSection as FormSectionType, FormField as FormFieldType } from "./FormRenderer";
 
-/**
- * Fields that naturally span full width by default.
- */
 const FULL_WIDTH_TYPES = new Set([
   "textarea",
   "radio",
   "checkboxGroup",
 ]);
 
+export interface FormSectionProps {
+  section: FormSectionType;
+  values: Record<string, unknown>;
+  errors: Record<string, string>;
+  touched: Record<string, boolean>;
+  onFieldChange: (fieldId: string, value: unknown) => void;
+  onFieldBlur: (fieldId: string) => void;
+}
+
 /**
  * A titled section of a form with a 2-column grid layout.
  * Fields default to 1-column (half width) unless the type is naturally
@@ -22,7 +28,7 @@ export default function FormSection({
   touched,
   onFieldChange,
   onFieldBlur,
-}) {
+}: FormSectionProps) {
   const fields = section.fields ?? [];
   if (!fields.length) return null;
 
@@ -42,7 +48,7 @@ export default function FormSection({
       ) : null}
 
       <div className="grid grid-cols-1 gap-x-4 gap-y-5 sm:grid-cols-2">
-        {fields.map((field) => {
+        {fields.map((field: FormFieldType & { colSpan?: number }) => {
           const span =
             field.colSpan ??
             (FULL_WIDTH_TYPES.has(field.type) ? 2 : 1);
@@ -57,7 +63,7 @@ export default function FormSection({
                 value={values[field.id]}
                 error={errors[field.id]}
                 touched={touched[field.id]}
-                onChange={(val) => onFieldChange(field.id, val)}
+                onChange={(val: unknown) => onFieldChange(field.id, val)}
                 onBlur={() => onFieldBlur(field.id)}
               />
             </div>

package/src/components/library/forms/index.tsx

@@ -0,0 +1,11 @@
+export { default as FormModal } from "./FormModal";
+export { default as FormRenderer } from "./FormRenderer";
+export { default as FormSection } from "./FormSection";
+export { default as FormField } from "./FormField";
+export { default as useFormState } from "./useFormState";
+
+export type { FormModalProps } from "./FormModal";
+export type { FormRendererProps } from "./FormRenderer";
+export type { FormSection as FormSectionType, FormField as FormFieldType } from "./FormRenderer";
+export type { FormSectionProps } from "./FormSection";
+export type { FormFieldProps } from "./FormField";

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

@@ -1,12 +1,35 @@
 import { useState, useMemo, useCallback, useRef } from "react";
+import type { FormSection } from "./FormRenderer";
 
 const DEFAULT_MIN_SUBMIT_MS = 4000;
 
+interface UseFormStateOptions {
+  initialValues?: Record<string, unknown>;
+  sections?: FormSection[];
+  onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+  minSubmitMs?: number;
+}
+
+interface UseFormStateReturn {
+  values: Record<string, unknown>;
+  errors: Record<string, string>;
+  touched: Record<string, boolean>;
+  isDirty: boolean;
+  isValid: boolean;
+  isSubmitting: boolean;
+  setValue: (id: string, value: unknown) => void;
+  setValues: (vals: Record<string, unknown>) => void;
+  setTouched: (id: string) => void;
+  validate: () => boolean;
+  reset: () => void;
+  handleSubmit: (e?: React.FormEvent) => Promise<boolean>;
+}
+
 /**
  * Extracts all field ids and their default values from a form schema.
  */
-function buildDefaults(sections) {
-  const defaults = {};
+function buildDefaults(sections: FormSection[]): Record<string, unknown> {
+  const defaults: Record<string, unknown> = {};
   for (const section of sections) {
     for (const field of section.fields ?? []) {
       if (field.type === "checkboxGroup") {
@@ -25,8 +48,8 @@ function buildDefaults(sections) {
  * Runs validation for all fields.
  * Returns an object of { fieldId: errorMessage } (empty object = valid).
  */
-function runValidation(values, sections) {
-  const errors = {};
+function runValidation(values: Record<string, unknown>, sections: FormSection[]): Record<string, string> {
+  const errors: Record<string, string> = {};
   for (const section of sections) {
     for (const field of section.fields ?? []) {
       const val = values[field.id];
@@ -54,23 +77,19 @@ function runValidation(values, sections) {
 
 /**
  * Form state management hook.
- *
- * @param {Object} options
- * @param {Object}  options.initialValues — prefill for editing (merged over field defaults)
- * @param {Array}   options.sections — form schema sections (used for defaults + validation)
- * @param {Function} options.onSubmit — called with (values) when form is valid
- * @param {number}  options.minSubmitMs — minimum time the submit spinner shows (default 4000ms, set 0 to disable)
- *
- * @returns {Object} { values, errors, touched, isDirty, isValid, isSubmitting,
- *                     setValue, setValues, setTouched, validate, reset, handleSubmit }
  */
-export default function useFormState({ initialValues = {}, sections = [], onSubmit, minSubmitMs = DEFAULT_MIN_SUBMIT_MS } = {}) {
+export default function useFormState({
+  initialValues = {},
+  sections = [],
+  onSubmit,
+  minSubmitMs = DEFAULT_MIN_SUBMIT_MS
+}: UseFormStateOptions = {}): UseFormStateReturn {
   const defaults = useMemo(() => buildDefaults(sections), [sections]);
   const merged = useMemo(() => ({ ...defaults, ...initialValues }), [defaults, initialValues]);
 
-  const [values, setValuesState] = useState(merged);
-  const [errors, setErrors] = useState({});
-  const [touched, setTouchedState] = useState({});
+  const [values, setValuesState] = useState<Record<string, unknown>>(merged);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [touched, setTouchedState] = useState<Record<string, boolean>>({});
   const [isSubmitting, setIsSubmitting] = useState(false);
   const submitRef = useRef(onSubmit);
   submitRef.current = onSubmit;
@@ -86,7 +105,7 @@ export default function useFormState({ initialValues = {}, sections = [], onSubm
     });
   }, [merged, values]);
 
-  const setValue = useCallback((id, value) => {
+  const setValue = useCallback((id: string, value: unknown) => {
     setValuesState((prev) => ({ ...prev, [id]: value }));
     setErrors((prev) => {
       if (!prev[id]) return prev;
@@ -96,18 +115,18 @@ export default function useFormState({ initialValues = {}, sections = [], onSubm
     });
   }, []);
 
-  const setValues = useCallback((vals) => {
+  const setValues = useCallback((vals: Record<string, unknown>) => {
     setValuesState((prev) => ({ ...prev, ...vals }));
   }, []);
 
-  const setTouched = useCallback((id) => {
+  const setTouched = useCallback((id: string) => {
     setTouchedState((prev) => (prev[id] ? prev : { ...prev, [id]: true }));
   }, []);
 
   const validate = useCallback(() => {
     const errs = runValidation(values, sections);
     setErrors(errs);
-    const allTouched = {};
+    const allTouched: Record<string, boolean> = {};
     for (const section of sections) {
       for (const field of section.fields ?? []) {
         allTouched[field.id] = true;
@@ -124,7 +143,7 @@ export default function useFormState({ initialValues = {}, sections = [], onSubm
   }, [merged]);
 
   const handleSubmit = useCallback(
-    async (e) => {
+    async (e?: React.FormEvent) => {
       e?.preventDefault?.();
       const valid = validate();
       if (!valid) return false;
@@ -137,7 +156,8 @@ export default function useFormState({ initialValues = {}, sections = [], onSubm
         await Promise.all([submitRef.current?.(values), delay]);
         return true;
       } catch (err) {
-        setErrors((prev) => ({ ...prev, _form: err?.message ?? "Submission failed" }));
+        const errorMessage = err instanceof Error ? err.message : "Submission failed";
+        setErrors((prev) => ({ ...prev, _form: errorMessage }));
         return false;
       } finally {
         setIsSubmitting(false);

package/src/components/library/layout/{PageContainer.jsx → PageContainer.tsx}

@@ -1,11 +1,14 @@
 import React from "react";
 
-export default function PageContainer({ className = "", children }) {
+export interface PageContainerProps {
+  className?: string;
+  children: React.ReactNode;
+}
+
+export default function PageContainer({ className = "", children }: PageContainerProps) {
   return (
     <div className={["mx-auto w-full max-w-6xl px-4 sm:px-6", className].filter(Boolean).join(" ")}>
       {children}
     </div>
   );
 }
-
-

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

@@ -1,5 +0,0 @@
-export { default as FormModal } from "./FormModal";
-export { default as FormRenderer } from "./FormRenderer";
-export { default as FormSection } from "./FormSection";
-export { default as FormField } from "./FormField";
-export { default as useFormState } from "./useFormState";