Player State Hooks

useAtlasForm

The primary hook. Returns the complete form state and mutation functions:

// packages/player-components-react/src/hooks/useAtlasForm.ts

interface AtlasFormState {
  // State
  values:      Record<string, any>;   // Current field values
  errors:      Record<string, string>; // Current validation errors
  isDirty:     boolean;                // True if any value differs from initialValues
  isValid:     boolean;                // True if no validation errors exist
  isSubmitting: boolean;               // True while onSubmit is awaiting

  // Mutations
  setFieldValue: (fieldId: string, value: any) => void;
  setValues:     (values: Record<string, any>) => void;
  resetForm:     () => void;           // Reset to initialValues
  submitForm:    () => Promise<void>;  // Trigger validation + onSubmit
  clearErrors:   () => void;

  // Engine access
  engine:      FormEngine;             // Direct access to FormEngine instance
}

function useAtlasForm(): AtlasFormState;

Usage Example

// Inside a custom button component embedded in a form
import { useAtlasForm } from '@atlas-forms/player-components-react';

const SaveDraftButton: React.FC = () => {
  const { isDirty, values, isSubmitting } = useAtlasForm();

  const handleSaveDraft = async () => {
    await fetch('/api/drafts', {
      method: 'POST',
      body: JSON.stringify(values),
      headers: { 'Content-Type': 'application/json' }
    });
  };

  return (
    <button onClick={handleSaveDraft} disabled={!isDirty || isSubmitting}>
      Save Draft
    </button>
  );
};

useFormVisibility

Returns visibility state for controls, accounting for both modeVisibilitySettings and visibilityRule expressions:

// packages/player-components-react/src/hooks/useFormVisibility.ts

interface FormVisibilityState {
  isVisible:       (controlId: string) => boolean;
  getVisibleControls: (sectionId?: string) => FormControl[];
  visibleControlIds:  string[];
}

function useFormVisibility(): FormVisibilityState;

Usage Example

import { useFormVisibility } from '@atlas-forms/player-components-react';

// In a custom player — render only visible controls
const MyCustomSection: React.FC<{ sectionId: string }> = ({ sectionId }) => {
  const { getVisibleControls } = useFormVisibility();
  const controls = getVisibleControls(sectionId);

  return (
    <div className="section">
      {controls.map(control => (
        <ControlRenderer key={control.id} control={control} />
      ))}
    </div>
  );
};

useControlDependencies

Returns dependency information for a specific control — which fields trigger a re-evaluation of its visibility rule, options, or computed value:

// packages/player-components-react/src/hooks/useControlDependencies.ts

interface ControlDependencies {
  dependsOn:      string[];   // Field IDs that affect this control's visibility/options
  affectedBy:     string[];   // Same — alias for dependsOn
  cascadesTo:     string[];   // Fields whose options/visibility depend on this control
}

function useControlDependencies(controlId: string): ControlDependencies;

Usage Example

// Highlight dependent fields when a select is changed
const CountrySelect: React.FC = () => {
  const { cascadesTo } = useControlDependencies('country');
  const { setFieldValue } = useAtlasForm();

  const handleChange = (value: string) => {
    setFieldValue('country', value);
    // Clear dependent fields when country changes
    cascadesTo.forEach(depId => setFieldValue(depId, null));
  };

  return /* ... */;
};

Hook Usage Rules