devin-ai-integration[bot]GitHubDevin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>somay@cal.com <somay@cal.com>Somay Chauhan* 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>
192 lines
9.3 KiB
Plaintext
192 lines
9.3 KiB
Plaintext
---
|
|
title: "Availability settings"
|
|
---
|
|
|
|
The availability settings atom enables a user to set their available time slots. This atom allows users to define specific time slots when they are available for meetings or events, helping them manage their schedules effectively and avoid double bookings.
|
|
|
|
First, for the AvailabilitySettings toggle animation to work set the reading direction on the `<html>` element:
|
|
|
|
```html
|
|
<html dir="ltr"> ... </html>
|
|
```
|
|
|
|
Below code snippet can be used to render the availability settings atom
|
|
|
|
```js
|
|
import { AvailabilitySettings } from "@calcom/atoms";
|
|
|
|
export default function Availability() {
|
|
return (
|
|
<>
|
|
<AvailabilitySettings
|
|
onUpdateSuccess={() => {
|
|
console.log("Updated schedule successfully");
|
|
}}
|
|
onDeleteSuccess={() => {
|
|
console.log("Deleted schedule successfully");
|
|
}}
|
|
onFormStateChange={(formState) => {
|
|
console.log("Form state updated");
|
|
// Access form data: formState.name, formState.schedule, formState.timeZone, etc.
|
|
}}
|
|
/>
|
|
</>
|
|
)
|
|
}
|
|
```
|
|
For a demonstration of the availability settings atom, please refer to the video below.
|
|
|
|
<p></p>
|
|
|
|
<iframe
|
|
height="315"
|
|
style={{ width: "100%", maxWidth: "560px" }}
|
|
src="https://www.loom.com/embed/6fd65789f5744227b4ea6d0189d4fc67?sid=544a6afd-2836-4704-aa56-e801cbd93cbc"
|
|
frameborder="0"
|
|
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
|
allowfullscreen="true"
|
|
></iframe>
|
|
|
|
<p></p>
|
|
|
|
If a user wishes to add further adjustments to their availability for special occasions or events, they can use the date overrides feature. Date overrides enables users to pick any date that they're currently available and set specific hours for availability on that day or mark themselves entirely unavailable. Once that day is passed, the date override is automatically deleted.
|
|
|
|
Below code snippet can be used to render date overrides into the availability settings atom
|
|
|
|
```js
|
|
import { AvailabilitySettings } from "@calcom/atoms";
|
|
|
|
export default function Availability() {
|
|
return (
|
|
<>
|
|
<AvailabilitySettings
|
|
enableOverrides={true}
|
|
onUpdateSuccess={() => {
|
|
console.log("Updated schedule successfully");
|
|
}}
|
|
onDeleteSuccess={() => {
|
|
console.log("Deleted schedule successfully");
|
|
}}
|
|
onFormStateChange={(formState) => {
|
|
console.log("Form state changed:", formState);
|
|
// Access form data including dateOverrides: formState.dateOverrides
|
|
}}
|
|
/>
|
|
</>
|
|
)
|
|
}
|
|
```
|
|
|
|
For a demonstration of the availability settings atom with date overrides, please refer to the video below.
|
|
|
|
<p></p>
|
|
|
|
<iframe
|
|
height="315"
|
|
style={{ width: "100%", maxWidth: "560px" }}
|
|
src="https://www.loom.com/embed/aa9ba47cbc284496ac51c26e172c7b12?sid=6d2b5bb3-d2eb-4a95-adb5-c67d863d4e34"
|
|
frameborder="0"
|
|
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
|
allowfullscreen="true"
|
|
></iframe>
|
|
|
|
<p></p>
|
|
|
|
We offer all kinds of customizations to the availability settings atom via props and customClassNames.
|
|
|
|
Below is a list of props that can be passed to the availability settings atom.
|
|
<p></p>
|
|
|
|
| Name | Required | Description |
|
|
|:--------------------|:----------|:-----------------------------------------------------------------------------------------------------------|
|
|
| id | No | The ID of the schedule which fetches a user's availability |
|
|
| labels | No | Helpful if you want to pass in custom labels for i18n |
|
|
| customClassNames | No | To pass in custom classnames from outside for styling the atom |
|
|
| onUpdateSuccess | No | A callback function to handle updating user availability successfully |
|
|
| onBeforeUpdate | No | Validates schedule before it is sent to the server; if true, the schedule is sent, else it is not |
|
|
| onUpdateError | No | A callback function that gets triggered when the user availability fails to update |
|
|
| onDeleteSuccess | No | A callback function that gets triggered when the user availability is deleted successfully |
|
|
| onDeleteError | No | A callback function that gets triggered when the user availability fails to delete |
|
|
| onFormStateChange | No | A callback function that gets triggered whenever the form state changes, providing real-time access to form data |
|
|
| enableOverrides | No | Allows user to enable or disable date overrides display in the atom; defaults to disabled |
|
|
| disableEditableHeading | No | Prevents users from editing the heading |
|
|
| allowDelete | No | When set to false, this prop hides the delete button |
|
|
| allowSetToDefault | No | When set to false, this prop hides the set to default toggle |
|
|
| disableToasts | No | Allows users to enable or disable toast notifications, with the default setting being disabled. |
|
|
|
|
Along with the props, Availability settings atom accepts custom styles via the **customClassNames** prop. Below is a list of props that fall under this **customClassNames** prop.
|
|
<p></p>
|
|
|
|
| Name | Description |
|
|
|:---------------------------|:-----------------------------------------------------------------------|
|
|
| containerClassName | Adds styling to the whole availability settings component |
|
|
| ctaClassName | Adds stylings only to certain call-to-action buttons |
|
|
| editableHeadingClassName | Editable heading or title can be styled |
|
|
| formClassName | Form which contains the days and toggles |
|
|
| timezoneSelectClassName | Adds styling to the timezone select component |
|
|
| subtitlesClassName | Styles the subtitle |
|
|
| scheduleContainer | Styles the entire schedule component |
|
|
| scheduleDay | Adds styling to just the day of a particular schedule |
|
|
| dayRanges | Adds styling to day ranges |
|
|
| timeRanges | Time ranges in the availability settings can be customized |
|
|
| labelAndSwitchContainer | Adds styling to label and switches |
|
|
| 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.
|