@synetics/ui 0.7.0-alpha

package/src/components/formular/components/form-provider/form-provider.syn

@@ -0,0 +1,182 @@
+/**
+ * FormProvider component
+ * Main form wrapper that provides context, lifecycle management, and validation orchestration
+ *
+ * @example
+ * ```tsx
+ * const form = useMemo(
+ *   () => formManager.createFromDescriptors<User>('userForm', userFields),
+ *   [formManager, userFields]
+ * )
+ *
+ * <FormProvider
+ *   form={form}
+ *   data={userData}
+ *   onSaveCallback={handleSave}
+ *   onQuitCallback={handleQuit}
+ * >
+ *   <InputField name="username" />
+ *   <InputField name="email" />
+ * </FormProvider>
+ * ```
+ */
+
+import { useEffect } from '@synetics/synetics.dev/hooks';
+import { Button } from '@synetics/ui';
+import type { IFormContext, IFormProviderProps } from '../../types';
+import { ModaleCommands, ModaleStyle } from '../../types';
+import { FormContext } from '../form-context';
+import { FormModale, FormValidationResults, useModale } from '../modal';
+// import { Portal } from '../portal' // TODO: Portal component not yet implemented
+
+/**
+ * FormProvider component
+ * Provides form context and manages form lifecycle
+ */
+export const FormProvider = <T extends object>({
+  form,
+  data,
+  onSaveCallback,
+  onQuitCallback,
+  children,
+}: IFormProviderProps<T>): HTMLElement => {
+  const { openModale, onModaleResult } = useModale(ModaleCommands.YesCancel, ModaleStyle.Primary);
+
+  if (!form) {
+    return <div>FormProvider requires an instance of a form !</div>;
+  }
+
+  // Parse data on mount, clear on unmount
+  useEffect(() => {
+    if (data) {
+      form?.parse(data);
+    }
+
+    return () => {
+      form?.clear();
+    };
+  }, [data, form]);
+
+  // Handle modal result (quit confirmation)
+  useEffect(() => {
+    if (onModaleResult.Yes) {
+      onQuitCallback();
+    }
+  }, [onModaleResult, onQuitCallback]);
+
+  /**
+   * Save form data (after validation)
+   */
+  const handleSaveData = async () => {
+    const valid = await form?.validateForm();
+    if (!valid) {
+      return;
+    }
+    onSaveCallback();
+  };
+
+  /**
+   * Quit form (with confirmation if dirty)
+   */
+  const handleQuit = () => {
+    if (form?.isDirty) {
+      openModale('form.quit.confirm');
+      return;
+    }
+    onQuitCallback();
+  };
+
+  /**
+   * Update field value (with pre-validation)
+   */
+  const handleFieldUpdate = (fieldName: string, value: unknown) => {
+    if (!form?.preValidateField(fieldName)) {
+      return;
+    }
+    form?.updateField(fieldName, value as string | number | boolean | null);
+  };
+
+  /**
+   * Clear field value
+   */
+  const handleClearField = (fieldName: string) => {
+    form?.clearField(fieldName);
+  };
+
+  /**
+   * Reset form to defaults
+   */
+  const handleResetForm = () => {
+    form?.reset();
+  };
+
+  /**
+   * Get field instance by name
+   * Returns the actual field with register() and ref methods
+   */
+  const getField = (fieldName: string) => {
+    const fieldWrapper = form?.getField(fieldName);
+    // Return the wrapper itself - it should have register() and ref() methods
+    return fieldWrapper;
+  };
+
+  /**
+   * Pre-validate field (before blur/change)
+   */
+  const preValidateField = (fieldName: string) => {
+    return form?.preValidateField(fieldName);
+  };
+
+  /**
+   * Validate single field
+   */
+  const validateField = (fieldName: string) => {
+    form?.validateField(fieldName);
+  };
+
+  /**
+   * Validate entire form
+   */
+  const validateForm = () => {
+    return form?.validateForm();
+  };
+
+  /**
+   * Get all form errors
+   */
+  const getErrors = () => {
+    return form?.getErrors();
+  };
+
+  // Form context value
+  const formContextData: IFormContext<T> = {
+    form,
+    updateField: handleFieldUpdate,
+    clearField: handleClearField,
+    reset: handleResetForm,
+    getField,
+    validateField,
+    preValidateField,
+    validateForm,
+    getErrors,
+  };
+
+  // Context.Provider will set the signal BEFORE evaluating children
+  // Don't pre-evaluate children here - let Provider handle the timing
+  return (
+    <FormContext.Provider value={formContextData}>
+      <div data-form-provider={form?.id}>
+        <form id={form?.id} className="space-y-6">
+          {children?.()}
+        </form>
+        <FormModale />
+        <FormValidationResults />
+        <div data-form-commands className="flex gap-2 mt-4">
+          <Button {...{ onclick: handleSaveData }}>Save</Button>
+          <Button {...{ onclick: handleResetForm }}>Reset</Button>
+          <Button {...{ onclick: handleQuit }}>Quit</Button>
+        </div>
+      </div>
+    </FormContext.Provider>
+  );
+};

package/src/components/formular/components/form-provider/index.ts

@@ -0,0 +1,5 @@
+/**
+ * FormProvider exports
+ */
+
+export { FormProvider } from './form-provider';

package/src/components/formular/components/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Form components
+ * Export all form components from this file
+ */
+
+// Form provider and context
+export * from './form-context';
+export * from './form-provider';
+
+// Modal components (validation display)
+export * from './modal';
+
+// Primitive field components (F-prefixed, single output)
+export * from './primitives';
+
+// Integrated field components (FieldSet wrappers with Field suffix)
+export * from './integrated';
+
+// Debug components
+export { FormDataDisplay } from './debug/form-data-display';

package/src/components/formular/components/integrated/checkbox-field.syn

@@ -0,0 +1,50 @@
+import {
+  fieldOptions as defaultFieldOptions,
+  IFieldSetProps,
+} from '../../types/field-component.type';
+import { useFormContext } from '../form-context';
+import { ValidationResults } from '../modal/validation-results';
+import { FCheckboxField } from '../primitives/f-checkbox-field';
+
+/**
+ * CheckboxField - Integrated checkbox component
+ *
+ * A FieldSet wrapper that combines:
+ * - Label element (wraps checkbox for better UX)
+ * - FCheckboxField primitive
+ * - ValidationResults
+ * - Optional debug panel
+ *
+ * @param name - Field name (must match form field descriptor)
+ * @param options - Optional field options (debug, loading)
+ */
+export const CheckboxField = (props: IFieldSetProps): HTMLElement => {
+  const { name, options = defaultFieldOptions } = props;
+  const formContext = useFormContext();
+  const field = formContext.getField(name);
+
+  if (!field) {
+    return (
+      <div id={`${name}-field-set`} className="text-red-600">
+        Field "{name}" not found in form context
+      </div>
+    );
+  }
+
+  return (
+    <div id={`${name}-field-set`} className="form-field-set">
+      <label className="flex items-center cursor-pointer">
+        <FCheckboxField name={name} />
+        <span className="ml-2 text-sm">{field.label}</span>
+      </label>
+
+      <ValidationResults name={name} />
+
+      {options.debug && (
+        <div className="field-debug">
+          <strong>Debug:</strong> name={name}, checked={String(field.value)}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/formular/components/integrated/checkbox.syn

@@ -0,0 +1,53 @@
+/**
+ * Checkbox integrated component
+ * Full-featured checkbox with label and errors
+ *
+ * @example
+ * ```tsx
+ * <Checkbox name="agreeToTerms" label="I agree to the terms" />
+ * ```
+ */
+
+import type { IFieldError } from '@synetics/formular.dev';
+import type { IIntegratedFieldProps } from '../../types';
+import { useFormContext } from '../form-context';
+import { FCheckboxField } from '../primitives';
+
+/**
+ * Checkbox component
+ * Integrated checkbox with label and validation errors
+ */
+export const Checkbox = ({
+  name,
+  label,
+  showErrors = true,
+  className = '',
+}: IIntegratedFieldProps): HTMLElement => {
+  const { getField } = useFormContext();
+  const field = getField(name);
+
+  if (!field) {
+    console.warn(`Field "${name}" not found in form`);
+    return <div data-field-error>{`Field "${name}" not found`}</div>;
+  }
+
+  const displayLabel = label || field.label;
+  const hasErrors = showErrors && field.errors && field.errors.length > 0;
+
+  return (
+    <div className={`form-field ${className}`} data-field={name}>
+      <label className="inline-flex items-center cursor-pointer">
+        <FCheckboxField name={name} />
+        {displayLabel && <span className="ml-2 text-sm text-gray-700">{displayLabel}</span>}
+      </label>
+
+      {hasErrors && (
+        <div className="validation-errors mt-1 ml-6">
+          {field?.errors?.map((error: IFieldError) => (
+            <p className="text-red-600 text-sm">{error.message}</p>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/components/formular/components/integrated/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Integrated component exports (FieldSet wrappers)
+ * Full-featured components with labels, primitives, validation, and debug panels
+ * Each follows Rule 8 pattern: name + options props only
+ */
+
+// New FieldSet wrappers (Field suffix)
+export { CheckboxField } from './checkbox-field';
+export { InputField } from './input-field';
+export { RadioGroupField } from './radio-group-field';
+export { SelectField } from './select-field';
+export { TextareaField } from './textarea-field';
+export { ToggleField } from './toggle-field';
+
+// Deprecated: Old naming conventions (remove in next major version)
+export { Checkbox } from './checkbox';
+export { RadioGroup } from './radio-group';
+export { SelectInput } from './select-input';
+export { TextField } from './text-field';
+export { TextareaInput } from './textarea-input';
+export { Toggle } from './toggle';

package/src/components/formular/components/integrated/input-field.syn

@@ -0,0 +1,51 @@
+import {
+  fieldOptions as defaultFieldOptions,
+  IFieldSetProps,
+} from '../../types/field-component.type';
+import { useFormContext } from '../form-context';
+import { ValidationResults } from '../modal/validation-results';
+import { FInputField } from '../primitives/f-input-field';
+
+/**
+ * InputField - Integrated text input component
+ *
+ * A FieldSet wrapper that combines:
+ * - Label element
+ * - FInputField primitive
+ * - ValidationResults
+ * - Optional debug panel
+ *
+ * @param name - Field name (must match form field descriptor)
+ * @param options - Optional field options (debug, loading)
+ */
+export const InputField = (props: IFieldSetProps): HTMLElement => {
+  const { name, options = defaultFieldOptions } = props;
+  const formContext = useFormContext();
+  const field = formContext.getField(name);
+
+  if (!field) {
+    return (
+      <div id={`${name}-field-set`} className="text-red-600">
+        Field "{name}" not found in form context
+      </div>
+    );
+  }
+
+  return (
+    <div id={`${name}-field-set`} className="form-field-set">
+      <label htmlFor={`${name}-input`} className="block text-sm font-medium">
+        {field.label}
+      </label>
+
+      <FInputField name={name} />
+
+      <ValidationResults name={name} />
+
+      {options.debug && (
+        <div className="field-debug">
+          <strong>Debug:</strong> name={name}, value={JSON.stringify(field.value)}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/formular/components/integrated/radio-group-field.syn

@@ -0,0 +1,68 @@
+import type { IOptionItem } from '@synetics/formular.dev';
+import {
+  fieldOptions as defaultFieldOptions,
+  IFieldSetProps,
+} from '../../types/field-component.type';
+import { useFormContext } from '../form-context';
+import { ValidationResults } from '../modal/validation-results';
+import { FRadioButton } from '../primitives/f-radio-button';
+
+/**
+ * RadioGroupField - Integrated radio button group component
+ *
+ * A FieldSet wrapper that combines:
+ * - Group label
+ * - Multiple FRadioButton primitives with labels
+ * - ValidationResults
+ * - Optional debug panel
+ *
+ * Note: Radio options must be defined in field descriptor's options array
+ *
+ * @param name - Field name (must match form field descriptor)
+ * @param options - Optional field options (debug, loading)
+ */
+export const RadioGroupField = (props: IFieldSetProps): HTMLElement => {
+  const { name, options = defaultFieldOptions } = props;
+  const formContext = useFormContext();
+  const field = formContext.getField(name);
+
+  if (!field) {
+    return (
+      <div id={`${name}-field-set`} className="text-red-600">
+        Field "{name}" not found in form context
+      </div>
+    );
+  }
+
+  if (!field.options || field.options.length === 0) {
+    return (
+      <div id={`${name}-field-set`} className="text-red-600">
+        Field "{name}" requires options array for radio group
+      </div>
+    );
+  }
+
+  return (
+    <div id={`${name}-field-set`} className="form-field-set">
+      <fieldset>
+        <legend className="block text-sm font-medium mb-2">{field.label}</legend>
+        <div className="space-y-2">
+          {field.options.map((option: IOptionItem) => (
+            <label key={String(option.value)} className="flex items-center cursor-pointer">
+              <FRadioButton name={name} value={option.value} />
+              <span className="ml-2 text-sm">{option.label}</span>
+            </label>
+          ))}
+        </div>
+      </fieldset>
+
+      <ValidationResults name={name} />
+
+      {options.debug && (
+        <div className="field-debug">
+          <strong>Debug:</strong> name={name}, value={JSON.stringify(field.value)}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/formular/components/integrated/radio-group.syn

@@ -0,0 +1,63 @@
+/**
+ * RadioGroup integrated component
+ * Full-featured radio group with label and errors
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup name="gender" label="Select Gender" />
+ * ```
+ */
+
+import type { IFieldError } from '@synetics/formular.dev';
+import type { IIntegratedFieldProps } from '../../types';
+import { useFormContext } from '../form-context';
+import { FRadioButton } from '../primitives';
+
+/**
+ * RadioGroup component
+ * Integrated radio button group with label and validation errors
+ * Automatically renders all options from field descriptor
+ */
+export const RadioGroup = ({
+  name,
+  showLabel = true,
+  label,
+  showErrors = true,
+  className = '',
+}: IIntegratedFieldProps): HTMLElement => {
+  const { getField } = useFormContext();
+  const field = getField(name);
+
+  if (!field) {
+    console.warn(`Field "${name}" not found in form`);
+    return <div data-field-error>{`Field "${name}" not found`}</div>;
+  }
+
+  const displayLabel = label || field.label;
+  const hasErrors = showErrors && field.errors && field.errors.length > 0;
+
+  return (
+    <div className={`form-field ${className}`} data-field={name}>
+      {displayLabel && (
+        <label className="block text-sm font-medium text-gray-700 mb-2">
+          {displayLabel}
+          {field.required && <span className="text-red-500 ml-1">*</span>}
+        </label>
+      )}
+
+      <div className="space-y-2">
+        {field.options?.map((option: any) => (
+          <FRadioButton name={name} value={option.value} label={option.label} />
+        ))}
+      </div>
+
+      {hasErrors && (
+        <div className="validation-errors mt-1">
+          {field.errors?.map((error: IFieldError, index: number) => (
+            <p className="text-red-600 text-sm">{error.message}</p>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/components/formular/components/integrated/select-field.syn

@@ -0,0 +1,51 @@
+import {
+  fieldOptions as defaultFieldOptions,
+  IFieldSetProps,
+} from '../../types/field-component.type';
+import { useFormContext } from '../form-context';
+import { ValidationResults } from '../modal/validation-results';
+import { FSelectField } from '../primitives/f-select-field';
+
+/**
+ * SelectField - Integrated select dropdown component
+ *
+ * A FieldSet wrapper that combines:
+ * - Label element
+ * - FSelectField primitive
+ * - ValidationResults
+ * - Optional debug panel
+ *
+ * @param name - Field name (must match form field descriptor)
+ * @param options - Optional field options (debug, loading)
+ */
+export const SelectField = (props: IFieldSetProps): HTMLElement => {
+  const { name, options = defaultFieldOptions } = props;
+  const formContext = useFormContext();
+  const field = formContext.getField(name);
+
+  if (!field) {
+    return (
+      <div id={`${name}-field-set`} className="text-red-600">
+        Field "{name}" not found in form context
+      </div>
+    );
+  }
+
+  return (
+    <div id={`${name}-field-set`} className="form-field-set">
+      <label htmlFor={`${name}-select`} className="block text-sm font-medium">
+        {field.label}
+      </label>
+
+      <FSelectField name={name} />
+
+      <ValidationResults name={name} />
+
+      {options.debug && (
+        <div className="field-debug">
+          <strong>Debug:</strong> name={name}, value={JSON.stringify(field.value)}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/formular/components/integrated/select-input.syn

@@ -0,0 +1,73 @@
+/**
+ * SelectInput integrated component
+ * Full-featured select with label, errors, and helper text
+ *
+ * @example
+ * ```tsx
+ * <SelectInput name="country" label="Select Country" />
+ * ```
+ */
+
+import type { IFieldError } from '@synetics/formular.dev';
+import type { IIntegratedFieldProps } from '../../types';
+import { useFormContext } from '../form-context';
+import { FSelectField } from '../primitives';
+
+/**
+ * SelectInput component
+ * Integrated select dropdown with label and validation errors
+ */
+export const SelectInput = ({
+  name,
+  showLabel = true,
+  label,
+  showErrors = true,
+  showGuides = true,
+  helperText,
+  className = '',
+}: IIntegratedFieldProps): HTMLElement => {
+  const { getField } = useFormContext();
+  const field = getField(name);
+
+  if (!field) {
+    console.warn(`Field "${name}" not found in form`);
+    return <div data-field-error>{`Field "${name}" not found`}</div>;
+  }
+
+  const displayLabel = label || field.label;
+  const hasErrors = showErrors && field.errors && field.errors.length > 0;
+  const hasGuides = showGuides && field.guides && field.guides.length > 0;
+
+  return (
+    <div className={`form-field ${className}`} data-field={name}>
+      {showLabel && (
+        <label htmlFor={name} className="block text-sm font-medium text-gray-700 mb-1">
+          {displayLabel}
+          {field.required && <span className="text-red-500 ml-1">*</span>}
+        </label>
+      )}
+
+      <FSelectField name={name} className={hasErrors ? 'border-red-500' : ''} />
+
+      {hasErrors && (
+        <div className="validation-errors mt-1">
+          {field.errors?.map((error: IFieldError, index: number) => (
+            <p className="text-red-600 text-sm">{error.message}</p>
+          ))}
+        </div>
+      )}
+
+      {hasGuides && (
+        <div className="validation-guides mt-1">
+          {field.guides?.map((guide: { message: string }, index: number) => (
+            <p className="text-blue-600 text-sm">{guide.message}</p>
+          ))}
+        </div>
+      )}
+
+      {helperText && !hasErrors && !hasGuides && (
+        <p className="text-gray-500 text-sm mt-1">{helperText}</p>
+      )}
+    </div>
+  );
+};

package/src/components/formular/components/integrated/text-field.syn

@@ -0,0 +1,49 @@
+/**
+ * TextField integrated component
+ * Full-featured text input with label, errors, and helper text
+ *
+ * @example
+ * ```tsx
+ * <TextField name="username" />
+ * <TextField name="email" label="Email Address" showErrors={true} />
+ * ```
+ */
+
+import type { IIntegratedFieldProps } from '../../types';
+import { useFormContext } from '../form-context';
+import { FieldLabel, FieldValidation, FInputField, HelperText } from '../primitives';
+
+/**
+ * TextField component
+ * Integrated text input with label, validation errors, and guides
+ *
+ * Composition pattern: Combines primitives for full-featured field
+ * - FieldLabel: Conditional label display
+ * - FInputField: Core input with formular.dev binding
+ * - FieldValidation: Error and guide messages
+ * - HelperText: Supplementary help text
+ */
+export const TextField = ({
+  name,
+  showLabel = true,
+  label,
+  showErrors = true,
+  showGuides = true,
+  helperText,
+  className = '',
+}: IIntegratedFieldProps): HTMLElement => {
+  const formContext = useFormContext();
+
+  const field = formContext.getField(name);
+  const input = field?.input;
+  const displayLabel = label || input?.label;
+
+  return (
+    <div className={`form-field ${className}`} data-field={name}>
+      <FieldLabel showLabel={showLabel} label={displayLabel} htmlFor={`${input?.id}`} />
+      <FInputField name={name} className="" />
+      <FieldValidation fieldName={name} showErrors={showErrors} showGuides={showGuides} />
+      <HelperText helperText={helperText} />
+    </div>
+  ) as HTMLElement;
+};