@synetics/ui 0.7.0-alpha

package/src/components/formular/hooks/bindings/use-toggle-bind.ts

@@ -0,0 +1,31 @@
+/**
+ * useToggleBind
+ *
+ * Adapts a formular IUseFieldResult to the props contract of atom/toggle/Toggle.
+ * Called inside a component render function — values are evaluated in the reactive context.
+ *
+ * @example
+ * ```tsx
+ * const field = useFormContext().getField('notifications')
+ * const state = useField(field)
+ * const bind = useToggleBind(state)
+ * return <Toggle {...bind} />
+ * ```
+ */
+
+import type { IUseFieldResult } from '../use-field';
+import type { IToggleBindProps } from './field-bindings.type';
+
+export function useToggleBind(field: IUseFieldResult): IToggleBindProps {
+  return {
+    name: field.name(),
+    checked: () => Boolean(field.value()),
+    disabled: field.isDisabled,
+    required: field.isRequired,
+    'aria-invalid': field.hasErrors,
+    'aria-required': field.isRequired,
+    onChange: (checked: boolean) => field.setValue(checked),
+    onFocus: field.focus,
+    onBlur: field.blur,
+  };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Hooks exports
+ */
+
+export { useField } from './use-field';
+export type { IUseFieldResult } from './use-field';
+export { useFieldValidation } from './use-field-validation';
+export type { IFieldValidationResult } from './use-field-validation';
+export { useFormularSignal } from './use-formular-signal';
+
+// Signal adapter / headless bind hooks — atoms stay agnostic of formular
+export {
+  useCheckboxBind,
+  useInputBind,
+  useRadioBind,
+  useSelectBind,
+  useTextareaBind,
+  useToggleBind,
+} from './bindings';
+export type {
+  IBaseBindProps,
+  ICheckboxBindProps,
+  IInputBindProps,
+  IRadioBindProps,
+  ISelectBindProps,
+  ITextareaBindProps,
+  IToggleBindProps,
+} from './bindings';

package/src/components/formular/hooks/use-field-validation.ts

@@ -0,0 +1,42 @@
+/**
+ * useFieldValidation hook
+ * Abstracts validation data gathering from formular.dev fields
+ *
+ * @example
+ * ```tsx
+ * const { hasErrors, errors, guides } = useFieldValidation(field);
+ *
+ * return (
+ *   <div>
+ *     {hasErrors() && <ErrorList errors={errors()} />}
+ *   </div>
+ * );
+ * ```
+ */
+
+import type { IFieldGuide } from '@synetics/formular.dev';
+import type { IFieldError, IValidationResult } from '../types';
+import { useField } from './use-field';
+
+export interface IFieldValidationResult {
+  /** Reactive function: returns true if field has validation errors */
+  hasErrors: () => boolean;
+  /** Reactive function: returns array of error messages */
+  errors: () => IFieldError[];
+  /** Reactive function: returns array of guide/hint messages */
+  guides: () => IFieldGuide[];
+  /** Reactive function: returns raw validation results */
+  validationResults: () => IValidationResult[];
+}
+
+/**
+ * Hook to extract and track validation state from formular.dev field
+ *
+ * @param field - The formular.dev field instance (from form.getField())
+ * @returns Reactive functions for validation state
+ */
+export function useFieldValidation(field: any): IFieldValidationResult {
+  // Delegate to the unified useField hook — it owns the single notifier bridge.
+  const { hasErrors, errors, guides, validationResults } = useField(field);
+  return { hasErrors, errors, guides, validationResults };
+}

package/src/components/formular/hooks/use-field.ts

@@ -0,0 +1,282 @@
+/**
+ * useField hook - Unified formular.dev field synchronization
+ *
+ * This hook consolidates ALL field state reactivity in ONE place for optimal performance.
+ * Instead of having multiple hooks (useFieldValidation, useFieldState, useFieldFocus, etc.),
+ * this single hook syncs all formular.dev signals to Pulsar reactivity.
+ *
+ * @example
+ * ```tsx
+ * const field = formContext.getField('email');
+ * const {
+ *   value,
+ *   setValue,
+ *   hasErrors,
+ *   errors,
+ *   guides,
+ *   isValid,
+ *   isDirty,
+ *   isPristine,
+ *   isTouched,
+ *   isFocused,
+ *   isDisabled,
+ *   isRequired,
+ *   focus,
+ *   blur,
+ *   reset,
+ * } = useField(field);
+ *
+ * return (
+ *   <input
+ *     value={value()}
+ *     onInput={(e) => setValue(e.target.value)}
+ *     disabled={isDisabled()}
+ *     required={isRequired()}
+ *   />
+ * );
+ * ```
+ */
+
+import type { IFieldGuide } from '@synetics/formular.dev';
+import { useSync } from '@synetics/synetics.dev';
+import type { IFieldError, IValidationResult } from '../types';
+
+export interface IUseFieldResult {
+  // ==================== VALUE MANAGEMENT ====================
+  /** Reactive function: returns current field value */
+  value: () => any;
+  /** Set field value programmatically */
+  setValue: (newValue: any) => void;
+
+  // ==================== VALIDATION STATE ====================
+  /** Reactive function: returns true if field has validation errors */
+  hasErrors: () => boolean;
+  /** Reactive function: returns array of error messages */
+  errors: () => IFieldError[];
+  /** Reactive function: returns array of guide/hint messages */
+  guides: () => IFieldGuide[];
+  /** Reactive function: returns raw validation results */
+  validationResults: () => IValidationResult[];
+
+  // ==================== FIELD STATE ====================
+  /** Reactive function: returns true if field passes all validation */
+  isValid: () => boolean;
+  /** Reactive function: returns true if field has been modified */
+  isDirty: () => boolean;
+  /** Reactive function: returns true if field is in original state */
+  isPristine: () => boolean;
+  /** Reactive function: returns true if field has been interacted with */
+  isTouched: () => boolean;
+  /** Reactive function: returns true if field currently has focus */
+  isFocused: () => boolean;
+
+  // ==================== FIELD PROPERTIES ====================
+  /** Reactive function: returns true if field is disabled */
+  isDisabled: () => boolean;
+  /** Reactive function: returns true if field is required */
+  isRequired: () => boolean;
+  /** Get field label */
+  label: () => string;
+  /** Get field name */
+  name: () => string;
+  /** Get field type */
+  type: () => string;
+
+  // ==================== FIELD ACTIONS ====================
+  /** Focus the field */
+  focus: () => void;
+  /** Blur the field */
+  blur: () => void;
+  /** Reset field to default value */
+  reset: () => void;
+  /** Mark field as touched */
+  touch: () => void;
+}
+
+/**
+ * Hook to sync ALL formular.dev field state to Pulsar reactivity
+ *
+ * This is the ONE hook to rule them all - consolidates all field behaviors:
+ * - Value management
+ * - Validation state
+ * - User interaction state (touched, focused, dirty)
+ * - Field properties (disabled, required)
+ * - Field actions (focus, blur, reset)
+ *
+ * @param field - The formular.dev field instance (from form.getField())
+ * @returns Complete reactive field interface
+ */
+export function useField(field: any): IUseFieldResult {
+  if (!field) {
+    throw new Error('[useField] Field instance is required');
+  }
+
+  const input = field.input;
+
+  // ==================== SINGLE OBSERVER-CHANNEL BRIDGE ====================
+  // formular.dev's reactive flow runs through `notifiers` (debounceNotify path),
+  // NOT through `observers`. The value setter calls debounceNotify('onUiUpdate', ...)
+  // after every value change; handleValidation calls it after every validation run.
+  // We register a notifier that listens to 'onUiUpdate' events and calls notify(),
+  // which re-reads all plain formular.dev properties fresh from the field instance.
+  // Key = `"${event.target}.${event.action}"` — must be unique per field instance.
+  const snapshot = useSync<{
+    value: any;
+    validationResults: IValidationResult[];
+    isValid: boolean;
+    isDirty: boolean;
+    isPristine: boolean;
+    isFocus: boolean;
+    isRequired: boolean;
+  }>(
+    (notify) => {
+      const nm = input?.notificationManager;
+      if (!nm) return () => {};
+      const fieldKey = input?.name ? String(input.name) : String(input?.id ?? 'unknown');
+      const notifier = {
+        event: {
+          types: ['onUiUpdate'] as unknown as any[],
+          target: `${fieldKey}.use-field`,
+          action: 'sync',
+          emitterName: 'use-field',
+          name: `${fieldKey}.use-field`,
+          toFlags: () => '',
+        },
+        method: () => notify(),
+      };
+      nm.accept(notifier as any);
+      return () => nm.dismiss(notifier as any);
+    },
+    () => ({
+      value: input?.value ?? null,
+      validationResults: input?.validationResults ?? [],
+      isValid: input?.isValid ?? true,
+      isDirty: input?.isDirty ?? false,
+      isPristine: input?.isPristine ?? true,
+      isFocus: input?.isFocus ?? false,
+      isRequired: input?.validationOptions?.required?.value ?? false,
+    })
+  );
+
+  // ==================== REACTIVE ACCESSORS ====================
+  const value = (): any => snapshot().value;
+  const validationResults = (): IValidationResult[] =>
+    snapshot().validationResults as IValidationResult[];
+  const isValid = (): boolean => snapshot().isValid;
+  const isDirty = (): boolean => snapshot().isDirty;
+  const isPristine = (): boolean => snapshot().isPristine;
+  const isFocused = (): boolean => snapshot().isFocus;
+  const isRequired = (): boolean => snapshot().isRequired;
+  const isDisabled = (): boolean => input?.disabled ?? false;
+
+  // ==================== DERIVED VALIDATION FUNCTIONS ====================
+  const hasErrors = () => {
+    const results = validationResults();
+    return results.some((r) => r.state === false && r.error);
+  };
+
+  const errors = (): IFieldError[] => {
+    const results = validationResults();
+    return results
+      .filter((result: IValidationResult) => result.state === false && result.error)
+      .map(
+        (result: IValidationResult) =>
+          ({
+            name: result.fieldName,
+            message: result.error!,
+            code: result.code,
+          }) as IFieldError
+      );
+  };
+
+  const guides = (): IFieldGuide[] => {
+    const results = validationResults();
+    // ✅ Return ALL guides regardless of validation state
+    // Guides are helpful hints that should show even when validation passes
+    return results
+      .filter((result: IValidationResult) => result.guide)
+      .map(
+        (result: IValidationResult) =>
+          ({
+            name: result.fieldName,
+            code: result.code,
+            message: result.guide!,
+          }) as IFieldGuide
+      );
+  };
+
+  // ==================== DERIVED STATE FUNCTIONS ====================
+  // "Touched" means the field has been focused and then blurred at least once
+  // We derive this from isDirty state (if dirty, user must have touched it)
+  const isTouched = () => {
+    // If field is dirty, it's been touched
+    return isDirty();
+  };
+
+  // ==================== FIELD METADATA ====================
+  const label = () => input?.label ?? field.name ?? '';
+  const name = () => input?.name ?? field.name ?? '';
+  const type = () => input?.type ?? 'text';
+
+  // ==================== FIELD ACTIONS ====================
+  const setValue = (newValue: any) => {
+    // input.setValue() is the formular.dev public API — _value signal does not exist
+    input?.setValue(newValue);
+  };
+
+  const focus = () => {
+    field?.focus?.();
+  };
+
+  const blur = () => {
+    field?.blur?.();
+  };
+
+  const reset = () => {
+    field?.reset?.();
+  };
+
+  const touch = () => {
+    // Mark field as touched by making it dirty if it isn't already
+    // In formular, "touched" is implicit from user interaction
+    // We can simulate it by ensuring the field has been interacted with
+    if (!isDirty() && !isFocused()) {
+      // Focus and blur to mark as touched
+      focus();
+      // Use setTimeout to allow focus to register before blur
+      setTimeout(() => blur(), 0);
+    }
+  };
+
+  return {
+    // Value management
+    value,
+    setValue,
+
+    // Validation state
+    hasErrors,
+    errors,
+    guides,
+    validationResults,
+
+    // Field state
+    isValid,
+    isDirty,
+    isPristine,
+    isTouched,
+    isFocused,
+
+    // Field properties
+    isDisabled,
+    isRequired,
+    label,
+    name,
+    type,
+
+    // Field actions
+    focus,
+    blur,
+    reset,
+    touch,
+  };
+}

package/src/components/formular/hooks/use-formular-signal.ts

@@ -0,0 +1,29 @@
+/**
+ * Bridge between formular.dev signals and Pulsar's reactive system
+ * Similar to React's useSyncExternalStore
+ *
+ * This hook allows Pulsar components to reactively subscribe to formular.dev signals
+ * and trigger re-renders when the signal values change.
+ */
+
+import { createSignal } from '@synetics/synetics.dev';
+
+/**
+ * Subscribe a Pulsar signal to a formular.dev signal
+ *
+ * @deprecated Pulsar's createEffect uses a separate reactive graph and cannot
+ * track formular.dev signals. Use useField() from formular/hooks instead.
+ * This function returns a one-shot snapshot that never updates.
+ *
+ * @param formularSignalGetter - The formular.dev signal getter to subscribe to
+ * @returns A Pulsar signal that holds the initial value only — DOES NOT update
+ */
+export function useFormularSignal<T>(formularSignalGetter: () => T): [() => T, (value: T) => void] {
+  console.warn(
+    '[useFormularSignal] DEPRECATED: Pulsar createEffect cannot observe formular.dev signals. ' +
+      'The returned signal will hold the initial value only and never update. ' +
+      'Use useField() from @synetics/synetics-ui.dev instead.'
+  );
+  const [pulsarValue, setPulsarValue] = createSignal<T>(formularSignalGetter());
+  return [pulsarValue, setPulsarValue];
+}

package/src/components/formular/index.ts

@@ -0,0 +1,3 @@
+export * from './components';
+export * from './types';
+export * from './utils';

package/src/components/formular/types/field-component.type.ts

@@ -0,0 +1,78 @@
+/**
+ * Field component prop types
+ * Shared interfaces for field components
+ */
+
+/**
+ * Field options for integrated components
+ * Controls debugging and loading states
+ */
+export interface IFieldOptions {
+  /** Enable debug mode to show field state information */
+  readonly debug: boolean;
+
+  /** Show skeleton loader instead of field */
+  readonly loading: boolean;
+}
+
+/**
+ * Default field options factory
+ */
+export const fieldOptions: IFieldOptions = {
+  debug: false,
+  loading: false,
+};
+
+/**
+ * Base props for primitive field components (F-prefixed)
+ * These components bind directly to Formular fields via context
+ */
+export interface IFieldComponentProps {
+  /** Name of the field (must match field descriptor name) */
+  readonly name: string;
+
+  /** Show skeleton loader */
+  readonly loading?: boolean;
+
+  /** Additional CSS classes */
+  readonly className?: string;
+}
+
+/**
+ * Props for integrated field components (Field-suffixed wrappers)
+ * These wrap primitives with Label + ValidationResults + Debug
+ */
+export interface IFieldSetProps {
+  /** Name of the field (must match field descriptor name) */
+  readonly name: string;
+
+  /** Field options for debug and loading */
+  readonly options?: IFieldOptions;
+}
+
+/**
+ * Props for select field components
+ */
+export interface ISelectFieldProps extends IFieldComponentProps {
+  /** Placeholder text for the select */
+  readonly placeholder?: string;
+}
+
+/**
+ * Props for radio button components
+ */
+export interface IRadioButtonProps extends IFieldComponentProps {
+  /** Value of this specific radio button */
+  readonly value: any;
+
+  /** Label for this radio button */
+  readonly label?: string;
+}
+
+/**
+ * Props for checkbox field components
+ */
+export interface ICheckboxFieldProps extends IFieldComponentProps {
+  /** Label for the checkbox */
+  readonly label?: string;
+}

package/src/components/formular/types/field-descriptor-config.type.ts

@@ -0,0 +1,79 @@
+/**
+ * Field descriptor configuration types
+ * Used for declarative field definition with useFieldDescriptors hook
+ */
+
+import type { IFieldDescriptor, ValidationConstraintConfig } from '@synetics/formular.dev';
+
+/**
+ * Field configuration for a single field
+ * Simplified API for creating field descriptors
+ */
+export interface IFieldConfig {
+  /** Field type (text, email, password, number, checkbox, select, radio, etc.) */
+  readonly type?: string;
+
+  /** Display label for the field */
+  readonly label?: string;
+
+  /** Default value for the field */
+  readonly defaultValue?: string | number | boolean | null;
+
+  /** Validation constraints for this field */
+  readonly validation?: ValidationConstraintConfig[];
+
+  /** Minimum value (for numbers) or length (for text) */
+  readonly min?: number;
+
+  /** Maximum value (for numbers) or length (for text) */
+  readonly max?: number;
+
+  /** Minimum length (for text fields) */
+  readonly minLength?: number;
+
+  /** Maximum length (for text fields) */
+  readonly maxLength?: number;
+
+  /** Pattern for validation (regex) */
+  readonly pattern?: string;
+
+  /** Options for select/radio/checkbox fields */
+  readonly options?: Array<{ label: string; value: any }>;
+
+  /** Placeholder text */
+  readonly placeholder?: string;
+
+  /** Whether field is disabled */
+  readonly disabled?: boolean;
+
+  /** Whether field is read-only */
+  readonly readOnly?: boolean;
+
+  /** Input mask pattern */
+  readonly mask?: string;
+
+  /** Any additional properties to pass to the field descriptor */
+  [key: string]: any;
+}
+
+/**
+ * Configuration object for multiple fields
+ * Maps field names to their configurations
+ *
+ * @example
+ * ```typescript
+ * const config: FieldDescriptorConfig<User> = {
+ *   username: { type: 'text', required: true },
+ *   email: { type: 'email', required: true },
+ *   age: { type: 'number', min: 18 }
+ * }
+ * ```
+ */
+export type FieldDescriptorConfig<T extends Record<string, any>> = {
+  [K in keyof T]?: IFieldConfig;
+};
+
+/**
+ * Result type from useFieldDescriptors hook
+ */
+export type FieldDescriptorResult = IFieldDescriptor[];

package/src/components/formular/types/form-context.type.ts

@@ -0,0 +1,67 @@
+/**
+ * Form context type definitions
+ * Defines the shape of the FormContext provider value
+ */
+
+import type { IExtendedInput, IFieldError, IFormular } from '@synetics/formular.dev';
+
+/**
+ * Form context interface
+ * Provides access to form operations and field instances
+ *
+ * @template T - The shape of the form data
+ */
+export interface IFormContext<T extends object> {
+  /** The form instance */
+  readonly form: IFormular<T>;
+
+  /**
+   * Update a field's value
+   * @param fieldName - Name of the field to update
+   * @param value - New value for the field
+   */
+  updateField: (fieldName: string, value: unknown) => void;
+
+  /**
+   * Clear a field's value (reset to default)
+   * @param fieldName - Name of the field to clear
+   */
+  clearField: (fieldName: string) => void;
+
+  /**
+   * Reset the entire form to its default state
+   */
+  reset: () => void;
+
+  /**
+   * Get a field instance by name
+   * @param fieldName - Name of the field to retrieve
+   * @returns The field instance or undefined
+   */
+  getField: (fieldName: string) => IExtendedInput | undefined;
+
+  /**
+   * Validate a single field
+   * @param fieldName - Name of the field to validate
+   */
+  validateField: (fieldName: string) => void;
+
+  /**
+   * Pre-validate a field (before blur/change)
+   * @param fieldName - Name of the field to pre-validate
+   * @returns Whether pre-validation passed
+   */
+  preValidateField: (fieldName: string) => boolean;
+
+  /**
+   * Validate the entire form
+   * @returns Promise resolving to whether the form is valid
+   */
+  validateForm: () => Promise<boolean>;
+
+  /**
+   * Get all form errors
+   * @returns Object mapping field names to their error arrays
+   */
+  getErrors: () => Record<string, IFieldError[]>;
+}