Skip to content

Commit 95226dc

Browse files
Arucard89Arucard89
authored
feat(Calendar): add README for Calendar (#38)
1 parent 61db996 commit 95226dc

File tree

2 files changed

+230
-15
lines changed

2 files changed

+230
-15
lines changed

‎src/components/Calendar/README.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
<!--GITHUB_BLOCK-->
2+
3+
# Calendar
4+
5+
<!--/GITHUB_BLOCK-->
6+
7+
```tsx
8+
import {Calendar} from '@gravity-ui/date-components';
9+
```
10+
11+
`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.
12+
13+
### Useful addition
14+
15+
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)
16+
17+
```tsx
18+
import {dateTimeParse} from '@gravity-ui/date-utils';
19+
```
20+
21+
## Size
22+
23+
To control the size of the `Calendar` use the `size` property. Default size is `m`.
24+
25+
<!--LANDING_BLOCK
26+
<ExampleBlock
27+
code={`
28+
<Calendar size="m" />
29+
<Calendar size="l" />
30+
<Calendar size="xl" />
31+
`}
32+
>
33+
<DateComponents.Calendar size="m" />
34+
<DateComponents.Calendar size="l" />
35+
<DateComponents.Calendar size="xl" />
36+
</ExampleBlock>
37+
LANDING_BLOCK-->
38+
39+
<!--GITHUB_BLOCK-->
40+
41+
```tsx
42+
<Calendar size="m" />
43+
<Calendar size="l" />
44+
<Calendar size="xl" />
45+
```
46+
47+
<!--/GITHUB_BLOCK-->
48+
49+
## Value
50+
51+
### Min and max value
52+
53+
The `minValue` property allows you to specify the earliest date and time that can be entered by the user. Conversely, the `maxValue` property specifies the latest date and time that can be entered. All other values will be disabled for user.
54+
55+
<!--LANDING_BLOCK
56+
<ExampleBlock
57+
code={`
58+
<Calendar minValue={dateTimeParse('01.01.2024')} maxValue={dateTimeParse('01.01.2025')} />
59+
`}
60+
>
61+
<DateComponentsExamples.CalendarExample minValue={'01.01.2024'} maxValue={'01.01.2025'}/>
62+
</ExampleBlock>
63+
LANDING_BLOCK-->
64+
65+
<!--GITHUB_BLOCK-->
66+
67+
```tsx
68+
<Calendar minValue={dateTimeParse('01.01.2024')} maxValue={dateTimeParse('01.01.2025')} />
69+
```
70+
71+
<!--/GITHUB_BLOCK-->
72+
73+
## Mode
74+
75+
Defines the time interval that `Calendar` should display. With `mode` you can choose it in controlled way. For uncontrolled way you don't need to specify any value. Also you can set the initial mode in uncontrolled way with `defaultMode` prop.
76+
77+
`days` - default mode for `Calendar`. It shows days in month.
78+
79+
`months` - shows months in year
80+
81+
`quarters` - shows quarters by years (not available as value in `defaultMode`)
82+
83+
`years` - shows several years for select
84+
85+
You can limit enabled modes by using prop `modes`.
86+
87+
<!--LANDING_BLOCK
88+
<ExampleBlock
89+
code={`
90+
<Calendar defaultMode="months"/>
91+
`}
92+
>
93+
<DateComponents.Calendar defaultMode="months" />
94+
</ExampleBlock>
95+
LANDING_BLOCK-->
96+
97+
<!--GITHUB_BLOCK-->
98+
99+
```tsx
100+
<Calendar defaultMode="months" />
101+
```
102+
103+
<!--/GITHUB_BLOCK-->
104+
105+
## States
106+
107+
### Disabled
108+
109+
The state of the `Calendar` where you don't want the user to be able to interact with the component.
110+
111+
<!--LANDING_BLOCK
112+
<ExampleBlock
113+
code={`
114+
<Calendar disabled={true} />
115+
`}
116+
>
117+
<DateComponents.Calendar disabled={true} />
118+
</ExampleBlock>
119+
LANDING_BLOCK-->
120+
121+
<!--GITHUB_BLOCK-->
122+
123+
```tsx
124+
<Calendar disabled={true} />
125+
```
126+
127+
<!--/GITHUB_BLOCK-->
128+
129+
### Readonly
130+
131+
`readOnly` is a boolean attribute that, when set to true, makes the `Calendar` component immutable to the user. This means that while the input will display its current value, users will not be able to change it.
132+
133+
<!--LANDING_BLOCK
134+
<ExampleBlock
135+
code={`
136+
<Calendar readOnly={true} />
137+
`}
138+
>
139+
<DateComponents.Calendar readOnly={true} />
140+
</ExampleBlock>
141+
LANDING_BLOCK-->
142+
143+
<!--GITHUB_BLOCK-->
144+
145+
```tsx
146+
<Calendar readOnly={true} />
147+
```
148+
149+
<!--/GITHUB_BLOCK-->
150+
151+
## Focused value
152+
153+
Allows to select the date that `Calendar` view is focused on. If you need it to be controlled you shoud use `focusedValue` prop. You can set the initial focused value for uncontrolled component with optional prop `defaultFocusedValue`.
154+
155+
<!--LANDING_BLOCK
156+
<ExampleBlock
157+
code={`
158+
<Calendar defaultFocusedValue={dateTimeParse('01.01.2020')} />
159+
`}
160+
>
161+
<DateComponentsExamples.CalendarExample defaultFocusedValue={'01.01.2020'} />
162+
</ExampleBlock>
163+
LANDING_BLOCK-->
164+
165+
<!--GITHUB_BLOCK-->
166+
167+
```tsx
168+
<Calendar defaultFocusedValue={dateTimeParse('01.01.2020')} />
169+
```
170+
171+
<!--/GITHUB_BLOCK-->
172+
173+
## Time zone
174+
175+
`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)
176+
177+
## Properties
178+
179+
| Name | Description | Type | Default |
180+
| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------: | :---------------------------------------------------------: |
181+
| aria-describedby | The control's `aria-describedby` attribute | `string` | |
182+
| aria-details | The control's `aria-details` attribute | `string` | |
183+
| aria-label | The control's `aria-label` attribute | `string` | |
184+
| aria-labelledby | The control's `aria-labelledby` attribute | `string` | |
185+
| autoFocus | The control's `autofocus` attribute | `boolean` | |
186+
| className | The control's wrapper class name | `string` | |
187+
| [defaultFocusedValue](#focused-value) | The date that is focused when the calendar first mounts (uncontrolled) | `DateTime` | |
188+
| [defaultMode](#mode) | Initial mode to show in calendar | `days` `months` `quarters` `years` | |
189+
| [defaultValue](#value) | Sets the initial value for uncontrolled component. | `DateTime` | |
190+
| [disabled](#disabled) | Indicates that the user cannot interact with the control | `boolean` | `false` |
191+
| [focusedValue](#focused-value) | Set the default view of uncontrolled component which includes this value | `DateTime` `null` | |
192+
| id | The control's `id` attribute | `string` | |
193+
| isDateUnavailable | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. | `((date: DateTime) => boolean)` | |
194+
| [maxValue](#min-and-max-value) | The maximum allowed date that a user may select. | `DateTime` | |
195+
| [minValue](#min-and-max-value) | The minimum allowed date that a user may select. | `DateTime` | |
196+
| [mode](#mode) | Defines the time interval that `Calendar` should display in colttrolled way. | `days` `months` `quarters` `years` | |
197+
| modes | Modes available to user | `Partial<Record<CalendarLayout, boolean>>` | `{days: true, months: true, quarters: false, years: true }` |
198+
| onBlur | Fires when the control lost focus. Provides focus event as a callback's argument | `((e: FocusEvent<Element, Element>) => void)` | |
199+
| onFocus | Fires when the control gets focus. Provides focus event as a callback's argument | `((e: FocusEvent<Element, Element>) => void)` | |
200+
| onFocusUpdate | Fires when the control's focused date changes. | `((date: DateTime) => void)` | |
201+
| onUpdate | Fires when the value is changed. | `((value: DateTime) => void` | |
202+
| onUpdateMode | Fires when the mode is changed. | `((value: 'days' \| 'months' \| 'quarters' \| 'years' ) => void` | |
203+
| [readOnly](#readonly) | Whether the calendar value is immutable. | `boolean` | `false` |
204+
| [size](#size) | The size of the control | `"m"` `"l"` `"xl"` | `"m"` |
205+
| style | Sets inline style for the element. | `CSSProperties` | |
206+
| [timeZone](#time-zone) | Sets the time zone. [Learn more about time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) | `string` | |
207+
| [value](#calendar) | The value of the control | `DateTime` `null` | |

‎src/components/DateField/README.md‎

Lines changed: 23 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,14 @@ import {DateField} from '@gravity-ui/date-components';
1010

1111
`DateField` component is a versatile and convenient input field specifically designed for date entry in React applications. With an intuitive interface and easy integration, it's perfect for any form that requires date or time input, such as event schedulers, booking systems, or data-driven reports. 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.
1212

13+
### Useful addition
14+
15+
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)
16+
17+
```tsx
18+
import {dateTimeParse} from '@gravity-ui/date-utils';
19+
```
20+
1321
## Appearance
1422

1523
The appearance of `DateField` is controlled by the `size`, `view` and `pin` properties.
@@ -111,21 +119,21 @@ The `minValue` property allows you to specify the earliest date and time that ca
111119
<!--LANDING_BLOCK
112120
<ExampleBlock
113121
code={`
114-
<DateField minValue={new DateTime('01.01.2024')} placeholder={"minValue: '01.01.2024'"}/>
115-
<DateField maxValue={new DateTime('01.01.2025')} placeholder={"maxValue: '01.01.2025'"}/>
122+
<DateField minValue={dateTimeParse('01.01.2024')} placeholder={"minValue: '01.01.2024'"}/>
123+
<DateField maxValue={dateTimeParse('01.01.2025')} placeholder={"maxValue: '01.01.2025'"}/>
116124
`}
117125
>
118-
<DateComponents.DateField minValue={new Date('01.01.2024')} placeholder={"minValue: '01.01.2024'"} />
119-
<DateComponents.DateField maxValue={new Date('01.01.2025')} placeholder={"maxValue: '01.01.2025'"} />
126+
<DateComponentsExamples.DateFieldExample minValue={'01.01.2024'} placeholder={"minValue: '01.01.2024'"} />
127+
<DateComponentsExamples.DateFieldExample maxValue={'01.01.2025'} placeholder={"maxValue: '01.01.2025'"} />
120128
</ExampleBlock>
121129
LANDING_BLOCK-->
122130

123131
<!--GITHUB_BLOCK-->
124132

125133
```tsx
126134

127-
<DateField minValue={new DateTime('01.01.2024')} />
128-
<DateField maxValue={new DateTime('01.01.2025')} />
135+
<DateField minValue={dateTimeParse('01.01.2024')} />
136+
<DateField maxValue={dateTimeParse('01.01.2025')} />
129137
```
130138

131139
<!--/GITHUB_BLOCK-->
@@ -139,17 +147,17 @@ The state of the `DateField` where you don't want the user to be able to interac
139147
<!--LANDING_BLOCK
140148
<ExampleBlock
141149
code={`
142-
<DateField disabled={true} />
150+
<DateField disabled={true} defaultValue={dateTimeParse(new Date())} />
143151
`}
144152
>
145-
<DateComponents.DateField disabled={true} />
153+
<DateComponentsExamples.DateFieldExample disabled={true} defaultValue={new Date()} />
146154
</ExampleBlock>
147155
LANDING_BLOCK-->
148156

149157
<!--GITHUB_BLOCK-->
150158

151159
```tsx
152-
<DateField disabled />
160+
<DateField disabled defaultValue={dateTimeParse(new Date())} />
153161
```
154162

155163
<!--/GITHUB_BLOCK-->
@@ -161,17 +169,17 @@ LANDING_BLOCK-->
161169
<!--LANDING_BLOCK
162170
<ExampleBlock
163171
code={`
164-
<DateField readOnly />
172+
<DateField readOnly defaultValue={dateTimeParse(new Date())} />
165173
`}
166174
>
167-
<DateComponents.DateField readOnly />
175+
<DateComponentsExamples.DateFieldExample readOnly defaultValue={new Date()} />
168176
</ExampleBlock>
169177
LANDING_BLOCK-->
170178

171179
<!--GITHUB_BLOCK-->
172180

173181
```tsx
174-
<DateField readOnly />
182+
<DateField readOnly defaultValue={dateTimeParse(new Date())} />
175183
```
176184

177185
<!--/GITHUB_BLOCK-->
@@ -337,12 +345,12 @@ LANDING_BLOCK-->
337345
<DateField format="LTS" />
338346
```
339347

348+
<!--/GITHUB_BLOCK-->
349+
340350
## Time zone
341351

342352
`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)
343353

344-
<!--/GITHUB_BLOCK-->
345-
346354
## Properties
347355

348356
| Name | Description | Type | Default |
@@ -372,7 +380,7 @@ LANDING_BLOCK-->
372380
| pin | Corner rounding | `string` | `'round-round'` |
373381
| placeholder | Text that appears in the control when it has no value set | `string` | |
374382
| placeholderValue | A placeholder date that controls the default values of each segment when the user first interacts with them. | `DateTime` | `today's date at midnigh` |
375-
| readOnly | Whether the calendar value is immutable. | `boolean` | `false` |
383+
| readOnly | Whether the component's value is immutable. | `boolean` | `false` |
376384
| rightContent | User`s node rendered after the input node and clear button | `React.ReactNode` | |
377385
| size | The size of the control | `"s"` `"m"` `"l"` `"xl"` | `"m"` |
378386
| style | Sets inline style for the element. | `CSSProperties` | |

0 commit comments

Comments
 (0)