feat(Calendar): customize Calendar/RangeCalendar view

Author: ValeraS

package.json

@@ -18,6 +18,16 @@
         "types": "./dist/cjs/index.d.ts",
         "default": "./dist/cjs/index.js"
       }
+    },
+    "./uikit": {
+      "import": {
+        "types": "./dist/esm/uikit.d.ts",
+        "default": "./dist/esm/uikit.js"
+      },
+      "require": {
+        "types": "./dist/cjs/uikit.d.ts",
+        "default": "./dist/cjs/uikit.js"
+      }
     }
   },
   "sideEffects": [

src/components/Calendar/Calendar.tsx

@@ -4,31 +4,51 @@ import React from 'react';
 
 import type {DateTime} from '@gravity-ui/date-utils';
 
-import {CalendarView} from '../CalendarView/CalendarView';
-import type {CalendarInstance, CalendarSize} from '../CalendarView/CalendarView';
+import {Provider, useContextProps} from '../../utils/providers';
+import type {RenderProps, SlotProps} from '../../utils/providers';
+import {CalendarContext, CalendarStateContext, CalendarView} from '../CalendarView/CalendarView';
+import type {CalendarSize} from '../CalendarView/CalendarView';
 import {useCalendarState} from '../CalendarView/hooks/useCalendarState';
-import type {CalendarStateOptions} from '../CalendarView/hooks/useCalendarState';
-import type {AccessibilityProps, DomProps, FocusEvents, StyleProps} from '../types';
+import type {CalendarState, CalendarStateOptions} from '../CalendarView/hooks/useCalendarState';
+import type {AccessibilityProps, DomProps, FocusEvents} from '../types';
 
 import '../CalendarView/Calendar.scss';
 
-export interface CalendarProps<T = DateTime>
+export interface CalendarRenderProps {
+    /**
+     * State of the calendar.
+     */
+    state: CalendarState;
+}
+
+export interface CalendarProps<T = DateTime, RP = CalendarRenderProps>
     extends CalendarStateOptions<T>,
+        RenderProps<RP>,
         DomProps,
-        StyleProps,
         FocusEvents,
-        AccessibilityProps {
+        AccessibilityProps,
+        SlotProps {
     /**
      * The size of the element.
      * @default m
      */
     size?: CalendarSize;
 }
-export const Calendar = React.forwardRef<CalendarInstance, CalendarProps>(function Calendar(
+export const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>(function Calendar(
     props: CalendarProps,
-    ref,
+    forwardedRef,
 ) {
-    const state = useCalendarState(props);
+    const [mergedProps, ref] = useContextProps(props, forwardedRef, CalendarContext);
+    const state = useCalendarState(mergedProps as any);
 
-    return <CalendarView ref={ref} {...props} state={state} />;
+    return (
+        <Provider
+            values={[
+                [CalendarStateContext, state],
+                [CalendarContext, mergedProps],
+            ]}
+        >
+            <CalendarView ref={ref} {...mergedProps} />
+        </Provider>
+    );
 });

src/components/Calendar/README.md

@@ -10,7 +10,7 @@ import {Calendar} from '@gravity-ui/date-components';
 
 `Calendar` is a flexible, user-friendly calendar component for React applications. It allows users to view, select, and manage dates with ease. Ideal for event scheduling, booking systems, and any application where date selection is essential. It can be controlled if you set `value` property. Or it can be uncontrolled if you don't set any value, but in this case you can manage the initial state with optional property `defaultValue`. Component is uncontrolled by default.
 
-### Useful addition
+## Useful addition
 
 To set dates in the right format you may need to include additional helpers from [Date Utils library](https://gravity-ui.com/libraries/date-utils)
 
@@ -174,6 +174,53 @@ LANDING_BLOCK-->
 
 `timeZone` is the property to set the time zone of the value in the input. [Learn more about time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List)
 
+## Customization
+
+A calendar consists of a grouping element containing date / month / quarter / year grid, a previous and next button for navigating between date ranges, heading for displaying current date range and layout switch button for switching layout mode e.g. days / months / quarters / years. Calendar grid consists of cells containing button elements that can be pressed and navigated to using the arrow keys to select a date.
+
+```jsx
+import {Flex} from '@gravity-ui/uikit';
+import {Button, Text} from '@gravity-ui/date-components/uikit';
+import {
+  Calendar,
+  CalendarGrid,
+  CalendarGridHeader,
+  CalendarGridHeaderCells,
+  CalendarGridHeaderCell,
+  CalendarGridBody,
+  CalendarGridRow,
+  CalendarGridRowHeader,
+  CalendarGridRowCells,
+  CalendarGridRowCell,
+} from '@gravity-ui/date-components';
+
+<Calendar>
+  <Flex justifyContent="space-between">
+    <Button slot="previous" />
+    <Text slot="heading" />
+    <Button slot="next" />
+  </Flex>
+  <CalendarGrid>
+    <CalendarGridHeader>
+      <div role="columnheader">#</div>
+      <CalendarGridHeaderCells>
+        {(date) => <CalendarGridHeaderCell date={date} />}
+      </CalendarGridHeaderCells>
+    </CalendarGridHeader>
+    <CalendarGridBody>
+      <CalendarGridRow>
+        <CalendarGridRowHeader>
+            {({dates}) => dates[0].format('W')}
+        </CalendarGridRowHeader>
+        <CalendarGridRowCells>
+            {(date) => <CalendarGridRowCell day={day} />}
+        </CalendarGridRowCells>
+      </CalendarGridRow>
+    </CalendarGridBody>
+  </CalendarGrid>
+</Calendar>;
+```
+
 ## Properties
 
 | Name                                  | Description                                                                                                          |                               Type                               |                           Default                           |