Candour Component Library

Introduction

The Candour Component Library is a collection of reusable React components designed to simplify the development of user interfaces. This library provides a set of well-crafted components that can be easily integrated into your projects, ensuring a consistent look and feel while saving development time. Whether you're building a small application or a large-scale project, these components are flexible, customizable, and ready to use.

Key Features

• Customizable Components: Each component comes with a variety of props for customization, allowing you to tailor styles and behavior to your needs.
• Accessibility: Designed with accessibility in mind to ensure your applications are usable by everyone.
• Lightweight: The library is lightweight and optimized for performance, ensuring a smooth user experience.
• Responsive Design: Components are built to be responsive, adapting to different screen sizes seamlessly.

Installation

To install the library, you can use npm or yarn:

npm install @candourorg/ui

or

yarn add @candourorg/ui

or

bun install @candourorg/ui

Button Component

Usage

<Button
  type="submit"
  variant="solid"
  disabled
  plusIcon
  className="submitButton"
  onClick={() => console.log('Button clicked!')}
>
  Submit
</Button>

Dropdown Component

DropdownItem

| Prop | Type | Default | Description | | ---------- | ----------- | ------- | --------------------------- | | children | ReactNode | - | Dropdown item to display. | | itemKey | string | - | Unique key for the item. | | padding | string | - | Padding style for the item. | | font | string | - | Font style for the item. | | color | string | - | Text color for the item. |

DropDownMenu

| Prop | Type | Default | Description | | ---------- | ----------------------- | ------- | -------------------------------- | | children | ReactNode | - | Dropdown items to display. | | bg | string | - | Background color for the menu. | | padding | string | - | Padding style for the menu. | | size | string | - | Size of the menu. | | radius | string | - | border radius of the DropDown. | | shadow | string | - | box shadow of the DropDown. | | onAction | (key: string) => void | - | Called when an item is selected. |

DropdownTrigger

| Prop | Type | Default | Description | | ---------- | ----------- | ------- | --------------------------- | | children | ReactNode | - | Content inside the trigger. |

DropdownWrapper

| Prop | Type | Default | Description | | ------------ | ----------- | ------- | ----------------------------- | | children | ReactNode | - | Trigger and menu items. | | position | string | - | Positioning of the menu. | | otherProps | object | - | Additional props for context. |

Usage

<DropdownWrapper>
  <DropdownTrigger>
    <Button type="button" variant="solid" onClick={() => {}}>
      Trigger Drop Down
    </Button>
  </DropdownTrigger>

  <DropDownMenu
    onAction={handleDropDownAction}
    size="lg"
    radius="md"
    shadow="xl"
  >
    <DropdownItem itemKey="new" text="New file" />
    <DropdownItem itemKey="old" text="Old file" />
  </DropDownMenu>
</DropdownWrapper>

Popover Component

Popover

| Prop | Type | Default | Description | | ---------------------- | ----------- | ------- | --------------------------------- | | popoverId | string | - | Unique ID for the popover. | | children | ReactNode | - | Content inside the popover. | | closeOnBackdropClick | boolean | true | Closes popover on backdrop click. | | position | string | - | Positioning of the popover. |

PopoverTrigger

| Prop | Type | Default | Description | | ---------- | ----------- | ------- | --------------------------- | | children | ReactNode | - | Content inside the trigger. |

PopoverContent

| Prop | Type | Default | Description | | ---------- | ----------- | ------- | --------------------------------- | | children | ReactNode | - | Content inside the popover. | | bg | string | - | Background color for the content. | | padding | string | - | Padding style for the content. | | size | string | - | Size of the content. |

Usage

<Popover>
  <PopoverTrigger>
    <button>Open Popover</button>
  </PopoverTrigger>
  <PopoverContent variant="solid" position="bottom">
    <p>Popover content (bottom)!</p>
  </PopoverContent>
</Popover>

Modal

| Prop | Type | Default | Description | | ---------------------- | ----------- | ------- | ------------------------------- | | modalId | string | - | Unique ID for the modal. | | children | ReactNode | - | Content inside the modal. | | closeOnBackdropClick | boolean | true | Closes modal on backdrop click. |

Usage

<Modal modalId="modalId" closeOnBackdropClick>
  <div>This is the modal content</div>
</Modal>

Toast

| Prop Name | Type | Default | Description | | ------------- | ----------------------------------------------------------------------- | ------------- | ----------------------------------------------------------- | | action | string | - | Title or label of the toast. | | toastId | string | - | Unique ID for the toast. | | message | string | - | Content displayed in the toast. | | closeButton | boolean | false | Shows a close button if true. | | duration | number | 5000 | Time in milliseconds before the toast automatically closes. | | position | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' | 'top-right' | Defines the corner of the screen where toasts appear. | | variant | 'default' \| 'success' \| 'error' \| 'info' \| 'warning' \| 'promise' | 'default' | Sets the visual style of the toast based on its type. |

Usage

<Toast
  action="Success"
  toastId="toastId"
  message="Item deleted successfully."
  variant="info"
  position="top-right"
  closeButton
/>

Toast Container

Usage

Place the ToastContainer at the root of your app or in a specific component

<ToastContainer />

ToggleTheme

-

<ToggleTheme />

Filter Component

Filter

| Prop | Type | Default | Description | | ---------- | ---------------------- | ----------- | ------------------------------------------------ | | children | ReactNode | - | The trigger and menu items of the filter button. | | variant | 'solid' or 'outline' | 'outline' | Style variant of the filter button. |

FilterTrigger

| Prop | Type | Default | Description | | -------------- | ------------------- | --------- | -------------------------------------------------- | | label | string | - | The text label for the filter button. | | arrowDown | boolean | false | If true, shows an arrow-down icon in the button. | | filterIcon | boolean | false | If true, displays a filter icon in the button. | | iconPosition | 'left' or 'right' | 'right' | Determines the position of the icon in the button. | | className | string | - | Additional class names for custom styling. | | disabled | boolean | false | If true, the button is disabled. |

FilterMenu

| Prop | Type | Default | Description | | ------------------- | ------------------------- | ------- | -------------------------------------------- | | children | ReactNode | - | List of filter items to display in the menu. | | onSelectionChange | (value: string) => void | - | Callback when a filter item is selected. | | selectedKey | string | - | Key of the currently selected filter item. | | className | string | - | Additional class names for custom styling. |

FilterItem

| Prop | Type | Default | Description | | ---------- | ----------- | ------- | ------------------------------------------ | | value | string | - | The value that represents the filter item. | | children | ReactNode | - | The content to be displayed in the item. |

Usage

<Filter>
  <FilterTrigger
    label="Filter"
    arrowDown
    iconPosition="right"
    variant="solid"
  />

  <FilterMenu onSelectionChange={handleFilterChange} selectedKey={selectedKey}>
    <FilterItem value="new">New Item</FilterItem>
    <FilterItem value="popular">Popular Item</FilterItem>
    <FilterItem value="old">Old Item</FilterItem>
  </FilterMenu>
</Filter>

Sort Component

Sort

| Prop | Type | Default | Description | | ---------- | ------------------------- | ------- | --------------------------------------------------------- | | children | ReactNode | - | The trigger and menu items of the sort component. | | | | onChange | (value: string) => void | - | Callback function triggered when a sort item is selected. |

SortTrigger

| Prop | Type | Default | Description | | ----------- | --------- | ------- | -------------------------------------------------- | | label | string | - | The text label for the sort button. | | arrowDown | boolean | false | If true, shows an arrow-down icon in the button. | | sortIcon | boolean | false | If true, displays a sort icon in the button. | | className | string | - | Additional class names for custom styling. | | disabled | boolean | false | If true, the button is disabled. |

SortMenu

| Prop | Type | Default | Description | | ------------------- | ------------------------- | ------- | ------------------------------------------ | | children | ReactNode | - | List of sort items to display in the menu. | | onSelectionChange | (value: string) => void | - | Callback when a sort item is selected. | | selectedKey | string | - | Key of the currently selected sort item. | | className | string | - | Additional class names for custom styling. |

SortItem

| Prop | Type | Default | Description | | ---------- | ---------------------------------- | ------- | ---------------------------------------- | | value | string | - | The value that represents the sort item. | | onClick | MouseEventHandler<HTMLLIElement> | - | Handler called when the item is clicked. | | children | ReactNode | - | The content to be displayed in the item. |

Usage

<Sort onChange={handleChange}>
  <SortTrigger sortIcon arrowDown label="Sort" />
  <SortMenu selectedKey={selected} onSelectionChange={handleChange}>
    {data.map((item) => (
      <SortItem value={item.value} key={item.label}>
        {item.label}
      </SortItem>
    ))}
  </SortMenu>
</Sort>

DatePicker Component

RegularDatePicker

The RegularDatePicker component is a flexible and customizable. It allows users to select a single date or a date range, with support for various configurations such as date format, display options, and accessibility features.

Features

• Supports both single-date and range selection.
• Customizable date format for display and input.
• Optional footer and shortcut options to improve usability.
• Min and Max date restrictions to ensure valid date selection.

Example Usage

Below are two examples demonstrating how to use the RegularDatePicker component in a React application: one in range mode and the other in single-date mode.

Example 1: Date Range Selection (Range Mode)

In this example, the RegularDatePicker allows users to select a range of dates. The useRange prop is set to true, and asSingle is set to false.

import React, { useState } from 'react';
import { RegularDatePicker } from '@candourorg/ui';

const DateRangePickerExample: React.FC = () => {
  const [value, setValue] = useState<DateRange>({
    startDate: null,
    endDate: null,
  });

  console.log(value);

  return (
    <RegularDatePicker
      useRange={true}
      label="Select a Date Range"
      placeholder="Select date range"
      asSingle={false}
      value={value}
      displayFormat={'DD/MM/YYYY'}
      onChange={(newValue: DateValueType) => setValue(newValue as DateRange)}
    />
  );
};

Example 2: Single-Date Selection (Single Mode)

In this example, the RegularDatePicker is configured for selecting a single date. The useRange prop is set to false, and asSingle is set to true.

import React, { useState } from 'react';
import { RegularDatePicker } from '@candourorg/ui';

const DateRangePickerExample: React.FC = () => {
  const [value, setValue] = useState<DateRange>({
    startDate: null,
    endDate: null,
  });

  console.log(value);

  return (
    <RegularDatePicker
      useRange={false}
      label="Select a Date Range"
      placeholder="Select date range"
      asSingle={true}
      value={value}
      displayFormat={'DD/MM/YYYY'}
      onChange={(newValue: DateValueType) => setValue(newValue as DateRange)}
    />
  );
};

Key Differences Between Range Mode and Single-Date Mode

The RegularDatePicker component can be used in two distinct modes: Range Mode and Single-Date Mode. Below is a comparison of the key differences between these modes:

| Feature | Range Mode | Single-Date Mode | | ----------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | useRange Prop | Set to true to enable range selection. | Set to false to disable range selection. | | asSingle Prop | Set to false to allow selecting a range of dates. | Set to true for selecting a single date. | | Purpose | Allows selecting a start and end date, ideal for booking systems and event scheduling. | Allows selecting only one date, ideal for picking specific dates like birthdays. | | Value Type | Managed as a DateRange object with startDate and endDate. | Managed as a single DateValueType. |

By toggling the useRange and asSingle props, you can easily switch between range and single-date selection modes to fit your specific use case.

Regular Date Comprehensive Props Guide

| Prop Name | Type | Required | Description | | -------------------- | --------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------- | | primaryColor | ColorKeys | No (Optional) | Primary color for styling the date picker. | | value | DateValueType | Yes | The current value of the date picker. | | onChange | (value: DateValueType, e?: HTMLInputElement \| null \| undefined) => void | Yes | Callback triggered when the date value changes. | | useRange | boolean | No (Optional) | Whether to allow selecting a range of dates. | | showFooter | boolean | No (Optional) | Whether to show footer actions in the date picker. | | showShortcuts | boolean | No (Optional) | Whether to show shortcut options in the date picker. | | configs | Configs | No (Optional) | Additional configuration options for the date picker. | | asSingle | boolean | No (Optional) | Whether the picker operates in single-date selection mode. | | placeholder | string | No (Optional) | Placeholder text displayed in the date picker input. | | separator | string | No (Optional) | Separator text for date ranges. | | startFrom | DateType | No (Optional) | Initial date or month to display when the picker opens. | | i18n | string | No (Optional) | Internationalization key for locale settings. | | disabled | boolean | No (Optional) | Whether the date picker is disabled. | | classNames | ClassNamesTypeProp | No (Optional) | Custom class names for styling. | | containerClassName | ClassNameType | No (Optional) | Class name for the container element. | | popupClassName | ClassNameType | No (Optional) | Class name for the popup element. | | inputClassName | ClassNameType | No (Optional) | Class name for the input field. | | toggleClassName | ClassNameType | No (Optional) | Class name for the toggle button. | | toggleIcon | (open: boolean) => ReactNode | No (Optional) | Custom toggle icon component. | | inputId | string | No (Optional) | ID for the input field. | | inputName | string | No (Optional) | Name attribute for the input field. | | displayFormat | string | No (Optional) | Format in which the selected date(s) are displayed. | | readOnly | boolean | No (Optional) | Whether the input field is read-only. | | minDate | DateType | No (Optional) | Minimum selectable date. | | maxDate | DateType | No (Optional) | Maximum selectable date. | | dateLooking | DateLookingType | No (Optional) | Type of date selection behavior. | | disabledDates | DateRangeType[] | No (Optional) | Array of date ranges to disable. | | startWeekOn | WeekStringType | No (Optional) | The day of the week to start on (e.g., Sunday or Monday). | | popoverDirection | PopoverDirectionType | No (Optional) | Direction in which the popover opens (e.g., top, bottom). | | required | boolean | No (Optional) | Whether the date picker is required. |

FormikDatePicker

FormikDatePicker is a React component designed for use with Formik to handle single-date input fields in forms. It supports selecting only one date.

Key Features:

• Single-Date Selection: For selecting one date.
• Formik Integration: Seamlessly works with Formik for form state and validation.
• Customizable: Easily configure label, error messages, and more.

Example Usage

The following example demonstrates how to use FormikDatePicker with Formik, including form validation using Yup.

import { Button, FormikDatePicker } from '@candourorg/ui';

const DatePickerFormik: React.FC = () => {
  const validationSchema = Yup.object().shape({
    startDate: Yup.string().required('Start Date is required').nullable(),
  });

  const companyTaxFormvalues = {
    startDate: '',
  };

  return (
    <Formik
      initialValues={companyTaxFormvalues}
      validationSchema={validationSchema}
      onSubmit={(values) => {
        console.log(values);
      }}
    >
      {(formikProps: FormikProps<any>) => {
        const { values, errors } = formikProps;

        return (
          <Form className="flex flex-col h-[calc(100vh-48px)]">
            <div className="flex items-center gap-5">
              <div className="grow">
                <Field
                  type="date"
                  id="startDate"
                  name="startDate"
                  label="Start Date"
                  placeholder="Choose a date"
                  value={values.startDate}
                  component={FormikDatePicker}
                  showError={!!errors.startDate}
                  errorMessage={errors.startDate}
                  form={formikProps}
                />
              </div>
            </div>
            <div className="flex-none">
              <Button
                type="submit"
                disabled={false}
                isSubmitting={false}
                className="w-full mt-3"
              >
                Submit
              </Button>
            </div>
          </Form>
        );
      }}
    </Formik>
  );
};

Formik Date Picker Comprehensive Props Guide

| Prop Name | Type | Required | Description | | --------------- | --------------- | ------------- | ---------------------------------------------------- | | value | Date | Yes | The current value of the date picker. | | label | string | Yes | Label text for the date picker. | | disabled | boolean | Yes | Whether the date picker is disabled. | | showError | boolean | Yes | Controls the visibility of error messages. | | errorMessage | string | Yes | Error message displayed when validation fails. | | placeholder | string | No (Optional) | Placeholder text displayed in the date picker. | | showFooter | boolean | No (Optional) | Whether to show footer actions in the date picker. | | showShortcuts | boolean | No (Optional) | Whether to show shortcut options in the date picker. | | displayFormat | string | No (Optional) | The format in which the selected date is displayed. | | minDate | DateValueType | No (Optional) | Minimum selectable date. |