@synetics/ui 0.7.0-alpha

package/src/components/formular/components/integrated/textarea-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 { FTextareaField } from '../primitives/f-textarea-field';
+
+/**
+ * TextareaField - Integrated textarea component
+ *
+ * A FieldSet wrapper that combines:
+ * - Label element
+ * - FTextareaField primitive
+ * - ValidationResults
+ * - Optional debug panel
+ *
+ * @param name - Field name (must match form field descriptor)
+ * @param options - Optional field options (debug, loading)
+ */
+export const TextareaField = (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}-textarea`} className="block text-sm font-medium">
+        {field.label}
+      </label>
+
+      <FTextareaField 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/textarea-input.syn

@@ -0,0 +1,73 @@
+/**
+ * TextareaInput integrated component
+ * Full-featured textarea with label, errors, and helper text
+ *
+ * @example
+ * ```tsx
+ * <TextareaInput name="description" label="Description" />
+ * ```
+ */
+
+import type { IFieldError } from '@synetics/formular.dev';
+import type { IIntegratedFieldProps } from '../../types';
+import { useFormContext } from '../form-context';
+import { FTextareaField } from '../primitives';
+
+/**
+ * TextareaInput component
+ * Integrated textarea with label and validation errors
+ */
+export const TextareaInput = ({
+  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>
+      )}
+
+      <FTextareaField 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/toggle-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 { FToggleField } from '../primitives/f-toggle-field';
+
+/**
+ * ToggleField - Integrated toggle switch component
+ *
+ * A FieldSet wrapper that combines:
+ * - Label element (wraps toggle for better UX)
+ * - FToggleField primitive
+ * - ValidationResults
+ * - Optional debug panel
+ *
+ * @param name - Field name (must match form field descriptor)
+ * @param options - Optional field options (debug, loading)
+ */
+export const ToggleField = (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">
+        <FToggleField name={name} />
+        <span className="ml-3 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/toggle.syn

@@ -0,0 +1,53 @@
+/**
+ * Toggle integrated component
+ * Full-featured toggle switch with label and errors
+ *
+ * @example
+ * ```tsx
+ * <Toggle name="enableNotifications" label="Enable Notifications" />
+ * ```
+ */
+
+import type { IFieldError } from '@synetics/formular.dev';
+import type { IIntegratedFieldProps } from '../../types';
+import { useFormContext } from '../form-context';
+import { FToggleField } from '../primitives';
+
+/**
+ * Toggle component
+ * Integrated toggle switch with label and validation errors
+ */
+export const Toggle = ({
+  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">
+        <FToggleField name={name} />
+        {displayLabel && <span className="ml-3 text-sm text-gray-700">{displayLabel}</span>}
+      </label>
+
+      {hasErrors && (
+        <div className="validation-errors mt-1 ml-12">
+          {field.errors?.map((error: IFieldError) => (
+            <p className="text-red-600 text-sm">{error.message}</p>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/components/formular/components/modal/error-message.syn

@@ -0,0 +1,21 @@
+/**
+ * ErrorMessage component
+ * Individual error message for .map() usage
+ */
+
+interface IErrorMessageProps {
+  readonly text: string;
+  readonly key?: string | number;
+}
+
+/**
+ * ErrorMessage - Displays a single validation error
+ */
+export const ErrorMessage = ({ text }: IErrorMessageProps): HTMLElement => {
+  return (
+    <div className="text-red-600 text-sm mt-1 flex items-start">
+      <span className="mr-1">✕</span>
+      <span>{text}</span>
+    </div>
+  );
+};

package/src/components/formular/components/modal/form-modale.syn

@@ -0,0 +1,44 @@
+/**
+ * FormModale component
+ * Confirmation dialog for form actions (quit, reset, etc.)
+ */
+
+import { createSignal } from '@synetics/synetics.dev/reactivity';
+import { Button } from '@synetics/ui';
+import { ModaleCommands, ModaleStyle } from '../../types';
+import { useModale } from './use-modale';
+
+/**
+ * FormModale component
+ * Displays confirmation dialogs for form operations
+ */
+export const FormModale = (): HTMLElement => {
+  const { modalState, handleYes, handleNo } = useModale(
+    ModaleCommands.YesCancel,
+    ModaleStyle.Primary
+  );
+
+  const [isVisible, setIsVisible] = createSignal(modalState.isOpen);
+
+  return (
+    <div
+      data-form-modale
+      className={`fixed inset-0 z-50 flex items-center justify-center transition-opacity ${
+        isVisible() ? 'opacity-100' : 'opacity-0 pointer-events-none'
+      }`}
+    >
+      {/* Backdrop */}
+      <div className="absolute inset-0 bg-black bg-opacity-50" onclick={handleNo}></div>
+
+      {/* Modal */}
+      <div className="relative bg-white rounded-lg shadow-xl max-w-md w-full mx-4 p-6">
+        <h3 className="text-lg font-semibold mb-4">{modalState.message || 'Confirm Action'}</h3>
+
+        <div className="flex justify-end gap-3 mt-6">
+          <Button {...{ onclick: handleNo }}>Cancel</Button>
+          <Button {...{ onclick: handleYes }}>Confirm</Button>
+        </div>
+      </div>
+    </div>
+  ) as HTMLElement;
+};

package/src/components/formular/components/modal/form-validation-results.syn

@@ -0,0 +1,46 @@
+/**
+ * FormValidationResults component
+ * Displays form-level validation errors
+ */
+
+import { useFormContext } from '../form-context';
+
+/**
+ * FormValidationResults component
+ * Shows all validation errors for the form
+ *
+ * @remarks
+ * This is a basic implementation. Customize styling and layout as needed.
+ */
+export const FormValidationResults = (): HTMLElement => {
+  const { getErrors } = useFormContext();
+  const errors = getErrors();
+
+  // Convert Record<string, IFieldError[]> to flat array
+  const errorList = Object.entries(errors).flatMap(([fieldName, fieldErrors]) =>
+    fieldErrors.map((error) => ({ fieldName, ...error }))
+  );
+
+  if (errorList.length === 0) {
+    const emptyDiv = document.createElement('div');
+    emptyDiv.setAttribute('data-form-validation-results', 'true');
+    emptyDiv.style.display = 'none';
+    return emptyDiv;
+  }
+
+  return (
+    <div
+      data-form-validation-results
+      className="form-validation-results bg-red-50 border border-red-200 rounded p-4 mb-4"
+    >
+      <h3 className="text-red-800 font-semibold mb-2">Validation Errors:</h3>
+      <ul className="list-disc list-inside space-y-1">
+        {errorList.map((error, index) => (
+          <li key={index} className="text-red-700 text-sm">
+            {error.fieldName}: {error.message || error.code}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+};

package/src/components/formular/components/modal/guide-message.syn

@@ -0,0 +1,21 @@
+/**
+ * GuideMessage component
+ * Individual guide message for .map() usage
+ */
+
+interface IGuideMessageProps {
+  readonly text: string;
+  readonly key?: string | number;
+}
+
+/**
+ * GuideMessage - Displays a single validation guide
+ */
+export const GuideMessage = ({ text }: IGuideMessageProps): HTMLElement => {
+  return (
+    <div className="text-blue-600 text-sm mt-1 flex items-start">
+      <span className="mr-1">ℹ</span>
+      <span>{text}</span>
+    </div>
+  );
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Modal components exports
+ */
+
+export { ErrorMessage } from './error-message';
+export { FormModale } from './form-modale';
+export { FormValidationResults } from './form-validation-results';
+export { GuideMessage } from './guide-message';
+export { useModale } from './use-modale';
+export { ValidationResults } from './validation-results';

package/src/components/formular/components/modal/use-modale.ts

@@ -0,0 +1,82 @@
+/**
+ * Modal hook for confirmation dialogs
+ * Placeholder implementation - integrate with your modal system
+ */
+
+import type { IModaleResult, ModaleCommands, ModaleStyle } from '../../types'
+
+interface IModalState {
+  isOpen: boolean
+  message: string
+  command: ModaleCommands
+  style: ModaleStyle
+}
+
+/**
+ * Hook for managing modal dialogs
+ * 
+ * @param defaultCommand - Default modal command type
+ * @param defaultStyle - Default modal style
+ * @returns Modal control functions and result
+ */
+export function useModale(
+  defaultCommand: ModaleCommands,
+  defaultStyle: ModaleStyle
+) {
+  let modalState: IModalState = {
+    isOpen: false,
+    message: '',
+    command: defaultCommand,
+    style: defaultStyle
+  }
+  
+  let modalResult: IModaleResult = {}
+  
+  /**
+   * Open the modal with a message
+   * @param messageKey - Translation key or message text
+   */
+  const openModale = (messageKey: string) => {
+    modalState = {
+      isOpen: true,
+      message: messageKey,
+      command: defaultCommand,
+      style: defaultStyle
+    }
+  }
+  
+  /**
+   * Close the modal
+   */
+  const closeModale = () => {
+    modalState = {
+      ...modalState,
+      isOpen: false
+    }
+  }
+  
+  /**
+   * Handle Yes/Ok button click
+   */
+  const handleYes = () => {
+    modalResult = { Yes: true, Ok: true }
+    closeModale()
+  }
+  
+  /**
+   * Handle No/Cancel button click
+   */
+  const handleNo = () => {
+    modalResult = { No: true, Cancel: true }
+    closeModale()
+  }
+  
+  return {
+    modalState,
+    onModaleResult: modalResult,
+    openModale,
+    closeModale,
+    handleYes,
+    handleNo
+  }
+}

package/src/components/formular/components/modal/validation-results.syn

@@ -0,0 +1,63 @@
+/**
+ * ValidationResults component
+ * Field-level validation display with pristine/focus/error logic
+ *
+ * Display Rules:
+ * - isPristine → NO validation displayed
+ * - !isPristine && isFocus && isError → Guide ONLY
+ * - !isPristine && !isFocus && isError → Error ONLY
+ * - !isPristine && !isError → Nothing
+ */
+
+import { useFormContext } from '../form-context';
+import { ErrorMessage } from './error-message';
+import { GuideMessage } from './guide-message';
+
+interface IValidationResultsProps {
+  readonly name: string;
+}
+
+/**
+ * ValidationResults - Displays field validation based on state
+ *
+ * @example
+ * ```tsx
+ * <ValidationResults name="email" />
+ * ```
+ */
+export const ValidationResults = ({ name }: IValidationResultsProps): HTMLElement | null => {
+  const { getField } = useFormContext();
+  const field = getField(name);
+
+  if (!field) {
+    return null;
+  }
+
+  const hasErrors = field.errors && field.errors.length > 0;
+  const hasGuides = field.guides && field.guides.length > 0;
+
+  // Rule: Show errors if present
+  if (hasErrors) {
+    return (
+      <div className="validation-errors" data-field={name}>
+        {field.errors?.map((error: string, i: number) => (
+          <ErrorMessage key={i} text={error} />
+        ))}
+      </div>
+    );
+  }
+
+  // Show guides if present and no errors
+  if (hasGuides) {
+    return (
+      <div className="validation-guides" data-field={name}>
+        {field.guides?.map((guide: string, i: number) => (
+          <GuideMessage key={i} text={guide} />
+        ))}
+      </div>
+    );
+  }
+
+  // No validation messages
+  return null;
+};

package/src/components/formular/components/primitives/f-checkbox-field.syn

@@ -0,0 +1,50 @@
+/**
+ * FCheckboxField primitive component
+ * Atomic checkbox field with formular.dev binding
+ *
+ * @example
+ * ```tsx
+ * <FCheckboxField name="agreeToTerms" />
+ * ```
+ */
+
+import type { IFieldComponentProps } from '../../types';
+import { devLog } from '../../utils/dev-logger';
+import { useFormContext } from '../form-context';
+
+/**
+ * FCheckboxField component - Primitive checkbox field
+ * Single output: <input type="checkbox"> element
+ */
+export const FCheckboxField = ({
+  name,
+  loading = false,
+  className = '',
+}: IFieldComponentProps): HTMLElement => {
+  const { getField } = useFormContext();
+  const field = getField(name);
+
+  if (!field) {
+    devLog.warn(`Field "${name}" not found in form`);
+    return <div data-field-error>{`Field "${name}" not found`}</div>;
+  }
+
+  // Skeleton fallback
+  if (loading) {
+    return <div className="h-5 w-5 bg-gray-200 animate-pulse rounded" data-loading={name} />;
+  }
+
+  // Single output: checkbox input
+  // Destructure type out of register() — spreading type:'text' would make formular
+  // use string-io validators on a boolean value, causing PARSING ERRORS at validation time.
+  const { type: _type, ...registerProps } = field.register();
+  return (
+    <input
+      type="checkbox"
+      {...registerProps}
+      ref={(el) => field.ref(el)}
+      className={`h-5 w-5 text-blue-600 border-gray-300 rounded focus:ring-blue-500 ${className}`}
+      checked={field.value}
+    />
+  );
+};

package/src/components/formular/components/primitives/f-input-field.syn

@@ -0,0 +1,77 @@
+/**
+ * FInputField primitive component
+ * Atomic input field with formular.dev binding
+ *
+ * @example
+ * ```tsx
+ * <FInputField name="username" />
+ * <FInputField name="email" loading={true} />
+ * ```
+ */
+
+import { onCleanup } from '@synetics/synetics.dev';
+import type { IFieldComponentProps } from '../../types';
+import { devLog } from '../../utils/dev-logger';
+import { useFormContext } from '../form-context';
+
+/**
+ * FInputField component - Primitive input field
+ * Single output: <input> element with formular binding
+ */
+export const FInputField = ({
+  name,
+  loading = false,
+  className = '',
+}: IFieldComponentProps): HTMLElement => {
+  const { getField } = useFormContext();
+  const field = getField(name);
+
+  if (!field) {
+    devLog.warn(`Field "${name}" not found in form`);
+    return <div data-field-error>{`Field "${name}" not found`}</div>;
+  }
+
+  // Skeleton fallback on loading
+  if (loading) {
+    return <div className="h-10 w-full bg-gray-200 animate-pulse rounded" data-loading={name} />;
+  }
+
+  // Get registration attributes from formular.dev
+  const registerAttrs = field.register();
+
+  // Use AbortController to remove all listeners when the component unmounts.
+  // Without this, each re-mount (Show toggle, SPA navigation, etc.) stacks
+  // additional handlers on the same element.
+  const ac = new AbortController();
+  onCleanup(() => ac.abort());
+
+  // Bind ref function to attach event listeners manually
+  const boundRef = (element: HTMLInputElement | null) => {
+    if (element) {
+      // Attach event handlers manually (Pulsar doesn't auto-convert JSX events to addEventListener)
+      if (registerAttrs.onChange) {
+        element.addEventListener('input', registerAttrs.onChange as EventListener, { signal: ac.signal });
+      }
+      if (registerAttrs.onBlur) {
+        element.addEventListener('blur', registerAttrs.onBlur as EventListener, { signal: ac.signal });
+      }
+      if (registerAttrs.onFocus) {
+        element.addEventListener('focus', registerAttrs.onFocus as EventListener, { signal: ac.signal });
+      }
+    }
+
+    field.ref(element);
+  };
+
+  // Extract non-event attributes for spreading
+  const { onChange, onBlur, onFocus, ...attrs } = registerAttrs;
+
+  return (
+    <input
+      {...attrs}
+      ref={boundRef}
+      className={`px-3 py-2 border rounded focus:outline-none w-full ${className}`}
+      style="background-color: var(--color-surface, #fff); color: var(--color-text, #111); border-color: var(--color-neutral-300, #d1d5db);"
+    />
+  );
+};