@schandlergarcia/sf-web-components 1.2.5 → 1.2.7

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

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

@@ -0,0 +1,201 @@
+import React, { 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";
+
+const OVERLAY_VARIANTS = {
+  hidden: { opacity: 0 },
+  visible: { opacity: 1 },
+};
+
+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 } },
+  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",
+};
+
+/**
+ * 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,
+  onClose,
+  title,
+  subtitle,
+  sections = [],
+  initialValues = {},
+  onSubmit,
+  submitLabel = "Save",
+  cancelLabel = "Cancel",
+  size = "lg",
+  destructive = false,
+  minSubmitMs,
+}) {
+  const form = useFormState({
+    initialValues,
+    sections,
+    minSubmitMs,
+    onSubmit: async (vals) => {
+      await onSubmit?.(vals);
+      onClose?.();
+    },
+  });
+
+  useEffect(() => {
+    if (isOpen) form.reset();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen]);
+
+  const onKeyDown = useCallback(
+    (e) => {
+      if (e.key === "Escape") onClose?.();
+    },
+    [onClose]
+  );
+
+  useEffect(() => {
+    if (!isOpen) return;
+    document.addEventListener("keydown", onKeyDown);
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      document.body.style.overflow = "";
+    };
+  }, [isOpen, onKeyDown]);
+
+  if (typeof document === "undefined") return null;
+
+  return createPortal(
+    <AnimatePresence>
+      {isOpen ? (
+        <div className="fixed inset-0 z-50 flex items-start justify-center px-4 pt-[10vh] sm:pt-[12vh]">
+          {/* Backdrop */}
+          <motion.div
+            key="overlay"
+            className="fixed inset-0 bg-black/40 backdrop-blur-sm"
+            variants={OVERLAY_VARIANTS}
+            initial="hidden"
+            animate="visible"
+            exit="hidden"
+            transition={{ duration: 0.2 }}
+            onClick={onClose}
+            aria-hidden="true"
+          />
+
+          {/* Panel */}
+          <motion.div
+            key="panel"
+            role="dialog"
+            aria-modal="true"
+            aria-label={title}
+            variants={PANEL_VARIANTS}
+            initial="hidden"
+            animate="visible"
+            exit="exit"
+            className={[
+              "relative z-10 flex w-full flex-col rounded-xl border border-slate-200 bg-white shadow-xl dark:border-slate-800 dark:bg-slate-900",
+              SIZE_CLASSES[size] ?? SIZE_CLASSES.lg,
+              "max-h-[80vh]",
+            ].join(" ")}
+          >
+            {/* Header */}
+            <div className="flex items-start justify-between border-b border-slate-100 px-6 py-4 dark:border-slate-800">
+              <div>
+                <h2 className="text-base font-semibold text-slate-900 dark:text-slate-50">
+                  {title}
+                </h2>
+                {subtitle ? (
+                  <p className="mt-0.5 text-sm text-slate-500 dark:text-slate-400">{subtitle}</p>
+                ) : null}
+              </div>
+              <button
+                type="button"
+                onClick={onClose}
+                className="rounded-lg p-1.5 text-slate-400 transition hover:bg-slate-100 hover:text-slate-600 dark:text-slate-500 dark:hover:bg-slate-800 dark:hover:text-slate-300"
+                aria-label="Close"
+              >
+                <XMarkIcon className="h-5 w-5" />
+              </button>
+            </div>
+
+            {/* Body — scrollable */}
+            <div className="flex-1 overflow-y-auto px-6 py-5">
+              <FormRenderer
+                sections={sections}
+                values={form.values}
+                errors={form.errors}
+                touched={form.touched}
+                onFieldChange={form.setValue}
+                onFieldBlur={form.setTouched}
+                formError={form.errors._form}
+              />
+            </div>
+
+            {/* Footer */}
+            <div className="flex items-center justify-between border-t border-slate-100 px-6 py-4 dark:border-slate-800">
+              <div className="text-xs text-slate-400 dark:text-slate-500">
+                {form.isDirty ? "Unsaved changes" : "\u00A0"}
+              </div>
+              <div className="flex items-center gap-3">
+                <button
+                  type="button"
+                  onClick={onClose}
+                  className="inline-flex h-9 items-center rounded-lg border border-slate-200 bg-white px-4 text-sm font-medium text-slate-700 shadow-sm transition hover:bg-slate-50 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-200 dark:hover:bg-slate-700"
+                >
+                  {cancelLabel}
+                </button>
+                <button
+                  type="button"
+                  onClick={form.handleSubmit}
+                  disabled={form.isSubmitting}
+                  className={[
+                    "inline-flex h-9 items-center gap-2 rounded-lg border border-transparent px-4 text-sm font-medium text-white shadow-sm transition",
+                    "focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 dark:focus-visible:ring-offset-slate-900",
+                    "disabled:cursor-not-allowed disabled:opacity-60",
+                    destructive
+                      ? "bg-red-600 hover:bg-red-500 focus-visible:ring-red-500 dark:bg-red-600 dark:hover:bg-red-500"
+                      : "bg-brand-600 hover:bg-brand-500 focus-visible:ring-brand-500 dark:bg-brand-500 dark:hover:bg-brand-400",
+                  ].join(" ")}
+                >
+                  {form.isSubmitting ? (
+                    <>
+                      <Spinner size="sm" tone="white" label="Submitting" />
+                      Saving…
+                    </>
+                  ) : submitLabel}
+                </button>
+              </div>
+            </div>
+          </motion.div>
+        </div>
+      ) : null}
+    </AnimatePresence>,
+    document.body
+  );
+}

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

@@ -0,0 +1,46 @@
+import React from "react";
+import FormSection from "./FormSection";
+
+/**
+ * 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 = [],
+  values = {},
+  errors = {},
+  touched = {},
+  onFieldChange,
+  onFieldBlur,
+  formError,
+}) {
+  return (
+    <div className="space-y-8">
+      {formError ? (
+        <div className="rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700 dark:border-red-800 dark:bg-red-950/30 dark:text-red-300">
+          {formError}
+        </div>
+      ) : null}
+
+      {sections.map((section, idx) => (
+        <FormSection
+          key={section.id ?? idx}
+          section={section}
+          values={values}
+          errors={errors}
+          touched={touched}
+          onFieldChange={onFieldChange}
+          onFieldBlur={onFieldBlur}
+        />
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,69 @@
+import React from "react";
+import FormField from "./FormField";
+
+/**
+ * Fields that naturally span full width by default.
+ */
+const FULL_WIDTH_TYPES = new Set([
+  "textarea",
+  "radio",
+  "checkboxGroup",
+]);
+
+/**
+ * A titled section of a form with a 2-column grid layout.
+ * Fields default to 1-column (half width) unless the type is naturally
+ * full-width or the field specifies `colSpan: 2`.
+ */
+export default function FormSection({
+  section,
+  values,
+  errors,
+  touched,
+  onFieldChange,
+  onFieldBlur,
+}) {
+  const fields = section.fields ?? [];
+  if (!fields.length) return null;
+
+  return (
+    <fieldset className="space-y-4">
+      {section.title ? (
+        <div className="border-b border-slate-100 pb-3 dark:border-slate-800">
+          <legend className="text-sm font-semibold text-slate-900 dark:text-slate-50">
+            {section.title}
+          </legend>
+          {section.description ? (
+            <p className="mt-0.5 text-xs text-slate-500 dark:text-slate-400">
+              {section.description}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+
+      <div className="grid grid-cols-1 gap-x-4 gap-y-5 sm:grid-cols-2">
+        {fields.map((field) => {
+          const span =
+            field.colSpan ??
+            (FULL_WIDTH_TYPES.has(field.type) ? 2 : 1);
+
+          return (
+            <div
+              key={field.id}
+              className={span === 2 ? "sm:col-span-2" : undefined}
+            >
+              <FormField
+                field={field}
+                value={values[field.id]}
+                error={errors[field.id]}
+                touched={touched[field.id]}
+                onChange={(val) => onFieldChange(field.id, val)}
+                onBlur={() => onFieldBlur(field.id)}
+              />
+            </div>
+          );
+        })}
+      </div>
+    </fieldset>
+  );
+}

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

@@ -0,0 +1,5 @@
+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";