@synetics/ui 0.7.0-alpha

package/src/components/formular/components/primitives/f-radio-button.syn

@@ -0,0 +1,64 @@
+/**
+ * FRadioButton primitive component
+ * Atomic radio button with formular.dev binding
+ *
+ * @example
+ * ```tsx
+ * <FRadioButton name="gender" value="male" />
+ * <FRadioButton name="gender" value="female" />
+ * ```
+ */
+
+import type { IRadioButtonProps } from '../../types';
+import { devLog } from '../../utils/dev-logger';
+import { useFormContext } from '../form-context';
+
+/**
+ * FRadioButton component - Primitive radio button
+ * Single output: <input type="radio"> element ONLY (no label)
+ */
+export const FRadioButton = ({
+  name,
+  value,
+  loading = false,
+  className = '',
+}: IRadioButtonProps): 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-full"
+        data-loading={`${name}-${value}`}
+      />
+    );
+  }
+
+  // Single output: radio input (NO label wrapper)
+  // Destructure type out to prevent register() spreading type:'text', and wrap
+  // ref in an arrow function so field.ref(el) is called with correct `this`.
+  // Use the `name` prop (field key string, e.g. "plan") — NOT field.name which
+  // resolves to the numeric element id, breaking radio grouping (browser uses
+  // identical name= attributes to enforce single-select within a group).
+  const { type: _type, ...registerProps } = field.register();
+  const isChecked = field.value === value;
+
+  return (
+    <input
+      type="radio"
+      {...registerProps}
+      ref={(el) => field.ref(el)}
+      name={name}
+      value={value}
+      checked={isChecked}
+      className={`h-5 w-5 text-blue-600 border-gray-300 focus:ring-blue-500 ${className}`}
+    />
+  );
+};

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

@@ -0,0 +1,61 @@
+/**
+ * FSelectField primitive component
+ * Atomic select field with formular.dev binding
+ *
+ * @example
+ * ```tsx
+ * <FSelectField name="country" />
+ * ```
+ */
+
+import type { ISelectFieldProps } from '../../types';
+import type { IOptionItem } from '@synetics/formular.dev';
+import { devLog } from '../../utils/dev-logger';
+import { useFormContext } from '../form-context';
+
+/**
+ * FSelectField component - Primitive select field
+ * Single output: <select> element
+ */
+export const FSelectField = ({
+  name,
+  loading = false,
+  placeholder,
+  className = '',
+}: ISelectFieldProps): 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-10 w-full bg-gray-200 animate-pulse rounded" data-loading={name} />;
+  }
+
+  // <select> has a read-only `type` getter — strip it from register() spread.
+  const { type: _type, ...registerAttrs } = field.register();
+
+  // field.ref is a prototype method — must invoke via dot-notation or .call()
+  // to preserve `this`. Passing it bare loses the receiver.
+  const boundRef = (el: HTMLSelectElement | null) => { field.ref(el); };
+
+  // Single output: select element
+  return (
+    <select
+      {...registerAttrs}
+      ref={boundRef}
+      className={`px-3 py-2 border border-gray-300 rounded focus:border-blue-500 focus:outline-none w-full ${className}`}
+    >
+      {placeholder && <option value="">{placeholder}</option>}
+      {field.options?.map((option: IOptionItem) => (
+        <option key={String(option.id ?? option.value)} value={String(option.value)}>
+          {option.label}
+        </option>
+      ))}
+    </select>
+  );
+};

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

@@ -0,0 +1,53 @@
+/**
+ * FTextareaField primitive component
+ * Atomic textarea field with formular.dev binding
+ *
+ * @example
+ * ```tsx
+ * <FTextareaField name="description" />
+ * ```
+ */
+
+import type { IFieldComponentProps } from '../../types';
+import { devLog } from '../../utils/dev-logger';
+import { useFormContext } from '../form-context';
+
+/**
+ * FTextareaField component - Primitive textarea field
+ * Single output: <textarea> element
+ */
+export const FTextareaField = ({
+  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-24 w-full bg-gray-200 animate-pulse rounded" data-loading={name} />;
+  }
+
+  // <textarea> has a read-only `type` getter — strip it from register() spread.
+  const { type: _type, ...registerAttrs } = field.register();
+
+  // field.ref is a prototype method — must invoke via dot-notation or .call()
+  // to preserve `this`. Passing it bare loses the receiver.
+  const boundRef = (el: HTMLTextAreaElement | null) => { field.ref(el); };
+
+  // Single output: textarea element
+  return (
+    <textarea
+      {...registerAttrs}
+      ref={boundRef}
+      className={`px-3 py-2 border border-gray-300 rounded focus:border-blue-500 focus:outline-none w-full ${className}`}
+      rows={4}
+    />
+  );
+};

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

@@ -0,0 +1,50 @@
+/**
+ * FToggleField primitive component
+ * Atomic toggle/switch field with formular.dev binding
+ *
+ * @example
+ * ```tsx
+ * <FToggleField name="notifications" />
+ * ```
+ */
+
+import type { IFieldComponentProps } from '../../types';
+import { devLog } from '../../utils/dev-logger';
+import { useFormContext } from '../form-context';
+
+/**
+ * FToggleField component - Primitive toggle field
+ * Single output: <input type="checkbox"> styled as toggle
+ */
+export const FToggleField = ({
+  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-6 w-11 bg-gray-200 animate-pulse rounded-full" data-loading={name} />;
+  }
+
+  // Single output: checkbox input (styled as toggle)
+  // Destructure type out — spreading type:'text' from register() onto a boolean field
+  // makes formular use string-io validators, producing PARSING ERRORS on true/false values.
+  const { type: _type, ...registerProps } = field.register();
+  return (
+    <input
+      type="checkbox"
+      {...registerProps}
+      ref={(el) => field.ref(el)}
+      className={`h-6 w-11 appearance-none bg-gray-200 rounded-full relative cursor-pointer transition-colors checked:bg-blue-600 before:content-[''] before:absolute before:h-5 before:w-5 before:rounded-full before:bg-white before:top-0.5 before:left-0.5 before:transition-transform checked:before:translate-x-5 ${className}`}
+      checked={field.value}
+    />
+  );
+};

package/src/components/formular/components/primitives/field-label.syn

@@ -0,0 +1,49 @@
+/**
+ * FieldLabel component
+ * Label wrapper with conditional rendering
+ *
+ * @example
+ * ```tsx
+ * <FieldLabel
+ *   showLabel={true}
+ *   label="Email Address"
+ *   htmlFor="email-input"
+ * />
+ * ```
+ */
+
+export interface IFieldLabelProps {
+  /** Whether to show the label */
+  showLabel?: boolean;
+  /** Label text to display */
+  label?: string;
+  /** HTML for attribute (input id) */
+  htmlFor?: string;
+  /** Optional CSS class name (default: "block text-sm font-medium text-gray-700 mb-1") */
+  className?: string;
+  /** Whether the field is required (shows asterisk) */
+  required?: boolean;
+}
+
+/**
+ * FieldLabel component
+ * Wrapper for form field labels with conditional display
+ */
+export const FieldLabel = ({
+  showLabel = true,
+  label,
+  htmlFor,
+  className = 'block text-sm font-medium text-gray-700 mb-1',
+  required = false,
+}: IFieldLabelProps): HTMLElement | null => {
+  if (!showLabel || !label) {
+    return null;
+  }
+
+  return (
+    <label htmlFor={htmlFor} className={className}>
+      {label}
+      {required && <span className="text-red-600 ml-1">*</span>}
+    </label>
+  ) as HTMLElement;
+};

package/src/components/formular/components/primitives/helper-text.syn

@@ -0,0 +1,32 @@
+/**
+ * HelperText component
+ * Simple helper text display for form fields
+ *
+ * @example
+ * ```tsx
+ * <HelperText helperText="Enter your email address" />
+ * <HelperText helperText="Must be at least 8 characters" className="text-xs" />
+ * ```
+ */
+
+export interface IHelperTextProps {
+  /** Helper text to display */
+  helperText?: string;
+  /** Optional CSS class name (default: "text-gray-500 text-sm mt-1") */
+  className?: string;
+}
+
+/**
+ * HelperText component
+ * Displays supplementary help text for form fields
+ */
+export const HelperText = ({
+  helperText,
+  className = 'text-gray-500 text-sm mt-1',
+}: IHelperTextProps): HTMLElement | null => {
+  if (!helperText) {
+    return null;
+  }
+
+  return (<p className={className}>{helperText}</p>) as HTMLElement;
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Primitive field component exports
+ * Basic bindings between Formular fields and Pulsar UI atoms
+ */
+
+/**
+ * Primitive form field components (F-prefixed)
+ * These are atomic components that bind directly to formular.dev fields
+ * Each outputs a SINGLE DOM element (input/textarea/select) + skeleton fallback
+ */
+
+export { FCheckboxField } from './f-checkbox-field';
+export { FInputField } from './f-input-field';
+export { FRadioButton } from './f-radio-button';
+export { FSelectField } from './f-select-field';
+export { FTextareaField } from './f-textarea-field';
+export { FToggleField } from './f-toggle-field';
+
+/**
+ * Utility components for field composition
+ */
+export { FieldValidation } from './validation-results';
+export type { IFieldValidationProps } from './validation-results';
+
+export { HelperText } from './helper-text';
+export type { IHelperTextProps } from './helper-text';
+
+export { FieldLabel } from './field-label';
+export type { IFieldLabelProps } from './field-label';
+
+// Note: Non-prefixed names (CheckboxField, InputField, etc.) are exported from ./integrated
+// to avoid naming conflicts. Use F-prefixed components directly for primitive bindings.

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

@@ -0,0 +1,76 @@
+/**
+ * FieldValidation component
+ * Displays validation errors and guides for a field
+ *
+ * @example
+ * ```tsx
+ * <FieldValidation
+ *   fieldName="email"
+ *   showErrors={true}
+ *   showGuides={true}
+ * />
+ * ```
+ */
+
+import { ShowRegistry as Show } from '@synetics/synetics.dev';
+import { useField } from '../../hooks/use-field';
+import type { IFieldError } from '../../types';
+import { useFormContext } from '../form-context';
+
+export interface IFieldValidationProps {
+  /** Field name to display validation for */
+  fieldName: string;
+  /** Whether to show error messages (default: true) */
+  showErrors?: boolean;
+  /** Whether to show guide/hint messages (default: true) */
+  showGuides?: boolean;
+  /** Optional CSS class for errors container */
+  errorsClassName?: string;
+  /** Optional CSS class for guides container */
+  guidesClassName?: string;
+}
+
+/**
+ * FieldValidation component
+ * Encapsulates error and guide display logic
+ */
+export const FieldValidation = ({
+  fieldName,
+  showErrors = true,
+  showGuides = true,
+  errorsClassName = 'validation-errors mt-1',
+  guidesClassName = 'validation-guides mt-1',
+}: IFieldValidationProps): HTMLElement => {
+  const formContext = useFormContext();
+  const field = formContext.getField(fieldName);
+
+  if (!field) {
+    return <div className="field-validation-container" /> as HTMLElement;
+  }
+
+  // ✅ Use unified hook - gets ALL field state in one place
+  const { hasErrors, errors, guides, isFocused } = useField(field);
+
+  return (
+    <div className="field-validation-container">
+      <Show when={() => showErrors && hasErrors() && !isFocused()}>
+        <div className={errorsClassName}>
+          {errors().map((error: IFieldError) => (
+            <p key={error.code} className="text-red-600 text-sm">
+              {error.message}
+            </p>
+          ))}
+        </div>
+      </Show>
+      <Show when={() => showGuides && isFocused()}>
+        <div className={guidesClassName}>
+          {guides().map((guide) => (
+            <p key={guide.code} className="text-blue-600 text-sm">
+              {guide.message}
+            </p>
+          ))}
+        </div>
+      </Show>
+    </div>
+  ) as HTMLElement;
+};

package/src/components/formular/hooks/bindings/field-bindings.type.ts

@@ -0,0 +1,58 @@
+/**
+ * Field binding types
+ *
+ * These types describe the props shape each bind hook returns.
+ * They are pure HTML-compatible — atoms remain agnostic of formular.
+ */
+
+/** Base aria + interaction props shared by all bind results */
+export interface IBaseBindProps {
+  readonly name: string;
+  /** Reactive getter — call inside a reactive context or effect */
+  readonly disabled: () => boolean;
+  /** Reactive getter — call inside a reactive context or effect */
+  readonly required: () => boolean;
+  /** Reactive getter — call inside a reactive context or effect */
+  readonly 'aria-invalid': () => boolean;
+  /** Reactive getter — call inside a reactive context or effect */
+  readonly 'aria-required': () => boolean;
+  readonly onFocus: () => void;
+  readonly onBlur: () => void;
+}
+
+/** Bind props for <Input> (text, number, email, …) */
+export interface IInputBindProps extends IBaseBindProps {
+  readonly value: () => string | number;
+  readonly onInput: (e: Event & { target: HTMLInputElement }) => void;
+}
+
+/** Bind props for <Textarea> */
+export interface ITextareaBindProps extends IBaseBindProps {
+  readonly value: () => string;
+  readonly onInput: (e: Event & { target: HTMLTextAreaElement }) => void;
+}
+
+/** Bind props for <Checkbox> */
+export interface ICheckboxBindProps extends IBaseBindProps {
+  readonly checked: () => boolean;
+  readonly onChange: (e: Event & { target: HTMLInputElement }) => void;
+}
+
+/** Bind props for <Radio> — requires the option value this radio represents */
+export interface IRadioBindProps extends IBaseBindProps {
+  readonly checked: () => boolean;
+  readonly value: string;
+  readonly onChange: () => void;
+}
+
+/** Bind props for <Toggle> */
+export interface IToggleBindProps extends IBaseBindProps {
+  readonly checked: () => boolean;
+  readonly onChange: (checked: boolean) => void;
+}
+
+/** Bind props for <Select> */
+export interface ISelectBindProps extends IBaseBindProps {
+  readonly value: () => string;
+  readonly onChange: (value: string) => void;
+}

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

@@ -0,0 +1,16 @@
+export type {
+  IBaseBindProps,
+  ICheckboxBindProps,
+  IInputBindProps,
+  IRadioBindProps,
+  ISelectBindProps,
+  ITextareaBindProps,
+  IToggleBindProps,
+} from './field-bindings.type';
+
+export { useCheckboxBind } from './use-checkbox-bind';
+export { useInputBind } from './use-input-bind';
+export { useRadioBind } from './use-radio-bind';
+export { useSelectBind } from './use-select-bind';
+export { useTextareaBind } from './use-textarea-bind';
+export { useToggleBind } from './use-toggle-bind';

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

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

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

@@ -0,0 +1,31 @@
+/**
+ * useInputBind
+ *
+ * Adapts a formular IUseFieldResult to the props contract of atom/input/Input.
+ * Called inside a component render function — values are evaluated in the reactive context.
+ *
+ * @example
+ * ```tsx
+ * const field = useFormContext().getField('email')
+ * const state = useField(field)
+ * const bind = useInputBind(state)
+ * return <Input {...bind} />
+ * ```
+ */
+
+import type { IUseFieldResult } from '../use-field';
+import type { IInputBindProps } from './field-bindings.type';
+
+export function useInputBind(field: IUseFieldResult): IInputBindProps {
+  return {
+    name: field.name(),
+    value: () => field.value() ?? '',
+    disabled: field.isDisabled,
+    required: field.isRequired,
+    'aria-invalid': field.hasErrors,
+    'aria-required': field.isRequired,
+    onInput: (e: Event & { target: HTMLInputElement }) => field.setValue(e.target.value),
+    onFocus: field.focus,
+    onBlur: field.blur,
+  };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * useRadioBind
+ *
+ * Adapts a formular IUseFieldResult to the props contract of atom/radio/Radio
+ * for a single radio option within a group.
+ *
+ * `radioValue` is the value this specific radio option represents.
+ * `checked` is derived by comparing field value against `radioValue`.
+ *
+ * @example
+ * ```tsx
+ * const field = useFormContext().getField('gender')
+ * const state = useField(field)
+ * return (
+ *   <>
+ *     <Radio {...useRadioBind(state, 'male')}   label="Male" />
+ *     <Radio {...useRadioBind(state, 'female')} label="Female" />
+ *   </>
+ * )
+ * ```
+ */
+
+import type { IUseFieldResult } from '../use-field';
+import type { IRadioBindProps } from './field-bindings.type';
+
+export function useRadioBind(field: IUseFieldResult, radioValue: string): IRadioBindProps {
+  return {
+    name: field.name(),
+    value: radioValue,
+    checked: () => field.value() === radioValue,
+    disabled: field.isDisabled,
+    required: field.isRequired,
+    'aria-invalid': field.hasErrors,
+    'aria-required': field.isRequired,
+    onChange: () => field.setValue(radioValue),
+    onFocus: field.focus,
+    onBlur: field.blur,
+  };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * useSelectBind
+ *
+ * Adapts a formular IUseFieldResult to the props contract of organisms/select/Select.
+ * Note: `options` are NOT part of the bind — they are static data provided by the caller.
+ * Called inside a component render function — values are evaluated in the reactive context.
+ *
+ * @example
+ * ```tsx
+ * const field = useFormContext().getField('country')
+ * const state = useField(field)
+ * const bind = useSelectBind(state)
+ * return <Select {...bind} options={countryOptions} />
+ * ```
+ */
+
+import type { IUseFieldResult } from '../use-field';
+import type { ISelectBindProps } from './field-bindings.type';
+
+export function useSelectBind(field: IUseFieldResult): ISelectBindProps {
+  return {
+    name: field.name(),
+    value: () => String(field.value() ?? ''),
+    disabled: field.isDisabled,
+    required: field.isRequired,
+    'aria-invalid': field.hasErrors,
+    'aria-required': field.isRequired,
+    onChange: (value: string) => field.setValue(value),
+    onFocus: field.focus,
+    onBlur: field.blur,
+  };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * useTextareaBind
+ *
+ * Adapts a formular IUseFieldResult to the props contract of atom/textarea/Textarea.
+ * Called inside a component render function — values are evaluated in the reactive context.
+ *
+ * @example
+ * ```tsx
+ * const field = useFormContext().getField('description')
+ * const state = useField(field)
+ * const bind = useTextareaBind(state)
+ * return <Textarea {...bind} />
+ * ```
+ */
+
+import type { IUseFieldResult } from '../use-field';
+import type { ITextareaBindProps } from './field-bindings.type';
+
+export function useTextareaBind(field: IUseFieldResult): ITextareaBindProps {
+  return {
+    name: field.name(),
+    value: () => String(field.value() ?? ''),
+    disabled: field.isDisabled,
+    required: field.isRequired,
+    'aria-invalid': field.hasErrors,
+    'aria-required': field.isRequired,
+    onInput: (e: Event & { target: HTMLTextAreaElement }) => field.setValue(e.target.value),
+    onFocus: field.focus,
+    onBlur: field.blur,
+  };
+}