feat: expose form validation methods from EventTypePlatformWrapper (calcom#22655)

* feat: expose form validation methods from EventTypePlatformWrapper

- Add validateForm and handleFormSubmit methods to onFormStateChange prop
- Update useEventTypeForm hook to return validateForm method
- Add proper TypeScript types for form validation result
- Enable external form validation and submission capabilities

Co-Authored-By: somay@cal.com <somay@cal.com>

* fix: correct forwardRef syntax to resolve parsing errors

- Fix forwardRef parameter destructuring syntax
- Use proper props parameter pattern for forwardRef components
- Ensure prettier can parse the file correctly

Co-Authored-By: somay@cal.com <somay@cal.com>

* feat: add form validation and submission handlers to event types platform wrapper

* refactor: move form validation and submit handlers from hook to wrapper component

* fix: add ref to the save button for proper form validation

* feat: extend ref-based validation API to AvailabilitySettingsPlatformWrapper

- Add AvailabilityFormValidationResult and AvailabilitySettingsPlatformWrapperRef types
- Implement forwardRef pattern in AvailabilitySettings component with save button ref
- Add validateForm and handleFormSubmit methods using useImperativeHandle
- Update AvailabilitySettingsPlatformWrapper to support ref forwarding
- Add comprehensive documentation for ref-based validation API in both event-type.mdx and availability-settings.mdx
- Follow same patterns established in EventTypePlatformWrapper for consistency

Co-Authored-By: somay@cal.com <somay@cal.com>

* refactor: rename AvailabilitySettingsPlatformWrapperRef to AvailabilitySettingsFormRef

* feat: add ref-based validation pattern to availability example page

- Mirror the ref-based validation implementation from event-types.tsx
- Add useRef, handleValidate, and handleSubmit functions
- Demonstrate validateForm() and handleFormSubmit() methods
- Add validation and submit buttons to showcase the new API
- Use AvailabilitySettingsFormRef type for proper typing

Co-Authored-By: somay@cal.com <somay@cal.com>

* refactor: remove unused state variables

* docs: clarify form validation behavior for availability and event type atoms

* chore: remove console.logs

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: somay@cal.com <somay@cal.com>
Co-authored-by: Somay Chauhan <somaychauhan98@gmail.com>

Author: 3 people

docs/platform/atoms/availability-settings.mdx

@@ -133,3 +133,59 @@ Along with the props, Availability settings atom accepts custom styles via the *
 | overridesModalClassNames  | Adds styling to the date overrides modal                              |
 
 <Info>Please ensure all custom classnames are valid [Tailwind CSS](https://tailwindcss.com/) classnames.</Info>
+
+## Programmatic Form Validation and Submission
+
+The AvailabilitySettings component supports programmatic form validation and submission through a ref-based API. This allows you to validate availability data and submit forms programmatically without user interaction.
+
+```js
+import { useRef } from 'react';
+import { AvailabilitySettings } from "@calcom/atoms";
+import type { AvailabilitySettingsFormRef } from "@calcom/atoms";
+
+export function AvailabilityWithValidation() {
+  const availabilityRef = useRef<AvailabilitySettingsFormRef>(null);
+
+  const handleValidate = async () => {
+    const result = await availabilityRef.current?.validateForm();
+    if (result?.isValid) {
+      console.log("Availability form is valid");
+    } else {
+      console.log("Validation errors:", result?.errors);
+    }
+  };
+
+  const handleSubmit = () => {
+    availabilityRef.current?.handleFormSubmit();
+  };
+
+  return (
+    <>
+      <AvailabilitySettings
+        ref={availabilityRef}
+        onUpdateSuccess={() => {
+          console.log("Updated schedule successfully");
+        }}
+        onFormStateChange={(formState) => {
+          console.log("Form state changed:", formState);
+        }}
+      />
+      <button onClick={handleValidate}>Validate Form</button>
+      <button onClick={handleSubmit}>Submit Form</button>
+    </>
+  );
+}
+```
+
+### Ref Methods
+
+| Method | Description |
+|:-------|:------------|
+| validateForm | Validates the current availability form state and returns a promise with validation results. |
+| handleFormSubmit | Programmatically submits the availability form, triggering the same validation and submission flow as clicking the save button. Unlike `validateForm`, this method will check required fields and prevent submission unless all required fields are set |
+
+The `validateForm` method returns an `AvailabilityFormValidationResult` object with:
+- `isValid`: Boolean indicating if the form passed validation
+- `errors`: Object containing any validation errors found
+
+**Note:** If a required field is not filled in, the `validateForm` method will not return any error. The validation focuses on the format and consistency of provided data rather than enforcing required field completion.

docs/platform/atoms/event-type.mdx

@@ -196,6 +196,60 @@ Along with the props, event type settings atom accepts custom styles via the **c
   Please ensure all custom classnames are valid [Tailwind CSS](https://tailwindcss.com/) classnames.
 </Info>
 
+## Programmatic Form Validation and Submission
+
+The EventTypeSettings component supports programmatic form validation and submission through a ref-based API. This allows you to validate form data and submit forms programmatically without user interaction.
+
+```js
+import { useRef } from 'react';
+import { EventTypeSettings } from "@calcom/atoms";
+import type { EventTypePlatformWrapperRef } from "@calcom/atoms";
+
+export function EventTypeWithValidation(eventTypeId: number) {
+  const eventTypeRef = useRef<EventTypePlatformWrapperRef>(null);
+
+  const handleValidate = async () => {
+    const result = await eventTypeRef.current?.validateForm();
+    if (result?.isValid) {
+      console.log("Form is valid");
+    } else {
+      console.log("Validation errors:", result?.errors);
+    }
+  };
+
+  const handleSubmit = () => {
+    eventTypeRef.current?.handleFormSubmit();
+  };
+
+  return (
+    <>
+      <EventTypeSettings
+        ref={eventTypeRef}
+        id={eventTypeId}
+        onSuccess={(eventType) => {
+          console.log("EventType updated successfully", eventType);
+        }}
+      />
+      <button onClick={handleValidate}>Validate Form</button>
+      <button onClick={handleSubmit}>Submit Form</button>
+    </>
+  );
+}
+```
+
+### Ref Methods
+
+| Method | Description |
+|:-------|:------------|
+| validateForm | Validates the current event type form state and returns a promise with validation results. |
+| handleFormSubmit | Programmatically submits the event type form, triggering the same validation and submission flow as clicking the save button. Unlike `validateForm`, this method will check required fields and prevent submission unless all required fields are set |
+
+The `validateForm` method returns an `EventTypeFormValidationResult` object with:
+- `isValid`: Boolean indicating if the form passed validation
+- `errors`: Object containing any validation errors found
+
+**Note:** If a required field is not filled in, the `validateForm` method will not return any error. The validation focuses on the format and consistency of provided data rather than enforcing required field completion.
+
 Following are the tabs that are available in the event type settings atom:
 
 <p></p>

packages/features/eventtypes/components/EventType.tsx

@@ -64,6 +64,7 @@ export type EventTypeComponentProps = EventTypeSetupProps & {
   tabName: (typeof tabs)[number];
   tabsNavigation: VerticalTabItemProps[];
   allowDelete?: boolean;
+  saveButtonRef?: React.RefObject<HTMLButtonElement>;
 };
 
 export const EventType = ({
@@ -82,6 +83,7 @@ export const EventType = ({
   handleSubmit,
   children,
   allowDelete = true,
+  saveButtonRef,
 }: EventTypeComponentProps) => {
   const [animationParentRef] = useAutoAnimate<HTMLDivElement>();
 
@@ -101,7 +103,8 @@ export const EventType = ({
         isDeleting={isDeleting}
         isPlatform={isPlatform}
         allowDelete={allowDelete}
-        tabsNavigation={tabsNavigation}>
+        tabsNavigation={tabsNavigation}
+        saveButtonRef={saveButtonRef}>
         <Form form={formMethods} id="event-type-form" handleSubmit={handleSubmit}>
           <div ref={animationParentRef}>{tabMap[tabName]}</div>
         </Form>

packages/features/eventtypes/components/EventTypeLayout.tsx

@@ -47,6 +47,7 @@ type Props = {
   isPlatform?: boolean;
   tabsNavigation: VerticalTabItemProps[];
   allowDelete?: boolean;
+  saveButtonRef?: React.RefObject<HTMLButtonElement>;
 };
 
 function EventTypeSingleLayout({
@@ -64,6 +65,7 @@ function EventTypeSingleLayout({
   isPlatform,
   tabsNavigation,
   allowDelete = true,
+  saveButtonRef,
 }: Props) {
   const { t } = useLocale();
   const eventTypesLockedByOrg = eventType.team?.parent?.organizationSettings?.lockEventTypeCreationForUsers;
@@ -262,6 +264,7 @@ function EventTypeSingleLayout({
           </Dropdown>
           <div className="border-default border-l-2" />
           <Button
+            ref={saveButtonRef}
             className="ml-4 lg:ml-0"
             type="submit"
             loading={isUpdateMutationLoading}

packages/features/eventtypes/lib/types.ts

@@ -220,3 +220,13 @@ export type SelectClassNames = {
   label?: string;
   container?: string;
 };
+
+export type FormValidationResult = {
+  isValid: boolean;
+  errors: Record<string, unknown>;
+};
+
+export interface EventTypePlatformWrapperRef {
+  validateForm: () => Promise<FormValidationResult>;
+  handleFormSubmit: () => void;
+}