Skip to content

Commit e8a015e

Browse files
Arucard89Arucard89
authored
feat(DateField): add component's description in README (#35)
Add description for DateField component and remove using window object for detecting key
1 parent 9dfeffd commit e8a015e

File tree

3 files changed

+384
-5
lines changed

3 files changed

+384
-5
lines changed

‎src/components/DateField/README.md‎

Lines changed: 382 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,382 @@
1+
<!--GITHUB_BLOCK-->
2+
3+
# DateField
4+
5+
<!--/GITHUB_BLOCK-->
6+
7+
```tsx
8+
import {DateField} from '@gravity-ui/date-components';
9+
```
10+
11+
`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.
12+
13+
## Appearance
14+
15+
The appearance of `DateField` is controlled by the `size`, `view` and `pin` properties.
16+
17+
### Size
18+
19+
To control the size of the `DateField` use the `size` property. Default size is `m`.
20+
21+
<!--LANDING_BLOCK
22+
<ExampleBlock
23+
code={`
24+
<DateField size="s" />
25+
<DateField size="m" />
26+
<DateField size="l" />
27+
<DateField size="xl" />
28+
`}
29+
>
30+
<DateComponents.DateField size="s" />
31+
<DateComponents.DateField size="m" />
32+
<DateComponents.DateField size="l" />
33+
<DateComponents.DateField size="xl" />
34+
</ExampleBlock>
35+
LANDING_BLOCK-->
36+
37+
<!--GITHUB_BLOCK-->
38+
39+
```tsx
40+
<DateField size="s" />
41+
<DateField size="m" />
42+
<DateField size="l" />
43+
<DateField size="xl" />
44+
```
45+
46+
<!--/GITHUB_BLOCK-->
47+
48+
### View
49+
50+
`normal` - the main view of `DateField` (used by default).
51+
52+
<!--LANDING_BLOCK
53+
<ExampleBlock code={`<DateField />`}>
54+
<DateComponents.DateField />
55+
</ExampleBlock>
56+
LANDING_BLOCK-->
57+
58+
`clear` - view of `DateField` without visible borders (can be used with a custom wrapper)
59+
60+
<!--LANDING_BLOCK
61+
<ExampleBlock code={`<DateField view="clear" />`}>
62+
<DateComponents.DateField view="clear" />
63+
</ExampleBlock>
64+
LANDING_BLOCK-->
65+
66+
<!--GITHUB_BLOCK-->
67+
68+
```tsx
69+
<DateField view="normal" />
70+
<DateField view="clear" />
71+
```
72+
73+
<!--/GITHUB_BLOCK-->
74+
75+
### Pin
76+
77+
The `pin` property allows you to control the shape of the right and left edges and is usually used for combining multiple controls in a single unit.
78+
The value of the `pin` property consists of left and edge style names divided by a dash, e.g. `"round-brick"`.
79+
The edge styles are: `round` (default), `circle`, `brick` and `clear`.
80+
81+
<!--LANDING_BLOCK
82+
<ExampleBlock
83+
code={`
84+
<DateField pin="round-brick" />
85+
<DateField pin="brick-brick" />
86+
<DateField pin="brick-round" />
87+
`}
88+
>
89+
<DateComponents.DateField pin="round-brick" />
90+
<DateComponents.DateField pin="brick-brick" />
91+
<DateComponents.DateField pin="brick-round" />
92+
</ExampleBlock>
93+
LANDING_BLOCK-->
94+
95+
<!--GITHUB_BLOCK-->
96+
97+
```tsx
98+
<DateField pin="round-brick" />
99+
<DateField pin="brick-brick" />
100+
<DateField pin="brick-round" />
101+
```
102+
103+
<!--/GITHUB_BLOCK-->
104+
105+
## Value
106+
107+
### Min and max value
108+
109+
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. If you input the value out of this bounds component changes it's view like in case of invalid validation state.
110+
111+
<!--LANDING_BLOCK
112+
<ExampleBlock
113+
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'"}/>
116+
`}
117+
>
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'"} />
120+
</ExampleBlock>
121+
LANDING_BLOCK-->
122+
123+
<!--GITHUB_BLOCK-->
124+
125+
```tsx
126+
127+
<DateField minValue={new DateTime('01.01.2024')} />
128+
<DateField maxValue={new DateTime('01.01.2025')} />
129+
```
130+
131+
<!--/GITHUB_BLOCK-->
132+
133+
## States
134+
135+
### Disabled
136+
137+
The state of the `DateField` where you don't want the user to be able to interact with the component.
138+
139+
<!--LANDING_BLOCK
140+
<ExampleBlock
141+
code={`
142+
<DateField disabled={true} />
143+
`}
144+
>
145+
<DateComponents.DateField disabled={true} />
146+
</ExampleBlock>
147+
LANDING_BLOCK-->
148+
149+
<!--GITHUB_BLOCK-->
150+
151+
```tsx
152+
<DateField disabled />
153+
```
154+
155+
<!--/GITHUB_BLOCK-->
156+
157+
### Readonly
158+
159+
`readOnly` is a boolean attribute that, when set to true, makes the `DateField` component immutable to the user. This means that while the input will display its current value, users will not be able to change it.
160+
161+
<!--LANDING_BLOCK
162+
<ExampleBlock
163+
code={`
164+
<DateField readOnly />
165+
`}
166+
>
167+
<DateComponents.DateField readOnly />
168+
</ExampleBlock>
169+
LANDING_BLOCK-->
170+
171+
<!--GITHUB_BLOCK-->
172+
173+
```tsx
174+
<DateField readOnly />
175+
```
176+
177+
<!--/GITHUB_BLOCK-->
178+
179+
### Error
180+
181+
The state of the `DateField` in which you want to indicate incorrect user input. To change `DateField` appearance, use the `validationState` property with the `"invalid"` value. An optional message text can be added via the `errorMessage` property. Message text will be rendered under the component.
182+
183+
<!--LANDING_BLOCK
184+
<ExampleBlock
185+
code={`
186+
<DateField errorMessage="Error message" validationState="invalid" />
187+
<DateField validationState="invalid" />
188+
`}
189+
>
190+
<DateComponents.DateField errorMessage="Error message" validationState="invalid" />
191+
<DateComponents.DateField validationState="invalid" />
192+
</ExampleBlock>
193+
LANDING_BLOCK-->
194+
195+
<!--GITHUB_BLOCK-->
196+
197+
```tsx
198+
<DateField errorMessage="Error message" validationState="invalid" />
199+
<DateField validationState="invalid" />
200+
```
201+
202+
<!--/GITHUB_BLOCK-->
203+
204+
## Additional content
205+
206+
### Placeholder
207+
208+
This prop allows you to provide a short hint that describes the expected value of the input field. This hint is displayed within the input field before the user enters a value, and it disappears upon the entry of text.
209+
210+
<!--LANDING_BLOCK
211+
<ExampleBlock
212+
code={`
213+
<DateField placeholder='Placeholder' />
214+
`}
215+
>
216+
<DateComponents.DateField placeholder='Placeholder' />
217+
</ExampleBlock>
218+
LANDING_BLOCK-->
219+
220+
<!--GITHUB_BLOCK-->
221+
222+
```tsx
223+
<DateField placeholder="Placeholder" />
224+
```
225+
226+
<!--/GITHUB_BLOCK-->
227+
228+
### Label
229+
230+
Allows you to place the label in the left part of the field. Label can take up no more than half the width of the entire space of `DateField`.
231+
232+
<!--LANDING_BLOCK
233+
<ExampleBlock
234+
code={`
235+
<DateField label="Label" />
236+
<DateField label="Very long label with huge amount of symbols" />
237+
`}
238+
>
239+
<DateComponents.DateField label="Label" />
240+
<DateComponents.DateField label="Very long label with huge amount of symbols" />
241+
</ExampleBlock>
242+
LANDING_BLOCK-->
243+
244+
<!--GITHUB_BLOCK-->
245+
246+
```tsx
247+
<DateField label="Label" />
248+
```
249+
250+
<!--/GITHUB_BLOCK-->
251+
252+
### Clear button
253+
254+
`hasClear` is a boolean prop that, provides users with the ability to quickly clear the content of the input field.
255+
256+
<!--LANDING_BLOCK
257+
<ExampleBlock
258+
code={`<DateField hasClear />`}
259+
>
260+
<DateComponents.DateField
261+
hasClear
262+
/>
263+
</ExampleBlock>
264+
LANDING_BLOCK-->
265+
266+
<!--GITHUB_BLOCK-->
267+
268+
```tsx
269+
<DateField hasClear />
270+
```
271+
272+
<!--/GITHUB_BLOCK-->
273+
274+
### Left content
275+
276+
Allows you to add content to the left part of the field. It is placed before all other components.
277+
278+
<!--LANDING_BLOCK
279+
<ExampleBlock
280+
code={`<DateField label="Label" leftContent={<Label size="s">Left content</Label>} />`}
281+
>
282+
<DateComponents.DateField
283+
label="Label"
284+
leftContent={<UIKit.Label size="s">Left content</UIKit.Label>}
285+
/>
286+
</ExampleBlock>
287+
LANDING_BLOCK-->
288+
289+
<!--GITHUB_BLOCK-->
290+
291+
```tsx
292+
<DateField label="Label" leftContent={<Label>Left content</Label>} />
293+
```
294+
295+
<!--/GITHUB_BLOCK-->
296+
297+
### Right content
298+
299+
Allows you to add content to the right part of the field. It is placed after all other components.
300+
301+
<!--LANDING_BLOCK
302+
<ExampleBlock
303+
code={`<DateField rightContent={<Label size="s">Right</Label>} hasClear/>`}
304+
>
305+
<DateComponents.DateField
306+
hasClear
307+
rightContent={<UIKit.Label size="s">Right</UIKit.Label>}
308+
/>
309+
</ExampleBlock>
310+
LANDING_BLOCK-->
311+
312+
<!--GITHUB_BLOCK-->
313+
314+
```tsx
315+
<DateField hasClear rightContent={<Label>Right</Label>} />
316+
```
317+
318+
<!--/GITHUB_BLOCK-->
319+
320+
## Format
321+
322+
The `format` prop is a string that defines the date and time format the `DateField` component will accept and display. This prop determines how the date and time are visually presented to the user and how the user's input is expected to be formatted. [Available formats](https://day.js.org/docs/en/display/format)
323+
324+
<!--LANDING_BLOCK
325+
<ExampleBlock
326+
code={`
327+
<DateField format='LTS' />
328+
`}
329+
>
330+
<DateComponents.DateField format='LTS' />
331+
</ExampleBlock>
332+
LANDING_BLOCK-->
333+
334+
<!--GITHUB_BLOCK-->
335+
336+
```tsx
337+
<DateField format="LTS" />
338+
```
339+
340+
## Time zone
341+
342+
`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)
343+
344+
<!--/GITHUB_BLOCK-->
345+
346+
## Properties
347+
348+
| Name | Description | Type | Default |
349+
| :---------------- | :------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----------------------: |
350+
| aria-describedby | The control's `aria-describedby` attribute | `string` | |
351+
| aria-details | The control's `aria-details` attribute | `string` | |
352+
| aria-label | The control's `aria-label` attribute | `string` | |
353+
| aria-labelledby | The control's `aria-labelledby` attribute | `string` | |
354+
| autoFocus | The control's `autofocus` attribute | `boolean` | |
355+
| className | The control's wrapper class name | `string` | |
356+
| defaultValue | Sets the initial value for uncontrolled component. | `DateTime` | |
357+
| disabled | Indicates that the user cannot interact with the control | `boolean` | `false` |
358+
| errorMessage | Error text | `string` | |
359+
| format | Format of the date when rendered in the input. [Available formats](https://day.js.org/docs/en/display/format) | `string` | |
360+
| hasClear | Shows the icon for clearing control's value | `boolean` | `false` |
361+
| id | The control's `id` attribute | `string` | |
362+
| isDateUnavailable | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. | `((date: DateTime) => boolean)` | |
363+
| label | Help text rendered to the left of the input node | `string` | |
364+
| leftContent | The user`s node rendered before label and input | `React.ReactNode` | |
365+
| maxValue | The maximum allowed date that a user may select. | `DateTime` | |
366+
| minValue | The minimum allowed date that a user may select. | `DateTime` | |
367+
| onBlur | Fires when the control lost focus. Provides focus event as a callback's argument | `((e: FocusEvent<Element, Element>) => void)` | |
368+
| onFocus | Fires when the control gets focus. Provides focus event as a callback's argument | `((e: FocusEvent<Element, Element>) => void)` | |
369+
| onKeyDown | Fires when a key is pressed. Provides keyboard event as a callback's argument | `((e: KeyboardEvent<Element>) => void)` | |
370+
| onKeyUp | Fires when a key is released. Provides keyboard event as a callback's argument | `((e: KeyboardEvent<Element>) => void)` | |
371+
| onUpdate | Fires when the value is changed by the user. Provides new value as an callback's argument | `((value: DateTime \| null) => void` | |
372+
| pin | Corner rounding | `string` | `'round-round'` |
373+
| placeholder | Text that appears in the control when it has no value set | `string` | |
374+
| 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` |
376+
| rightContent | User`s node rendered after the input node and clear button | `React.ReactNode` | |
377+
| size | The size of the control | `"s"` `"m"` `"l"` `"xl"` | `"m"` |
378+
| style | Sets inline style for the element. | `CSSProperties` | |
379+
| timeZone | Sets the time zone. [Learn more about time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) | `string` | |
380+
| validationState | Validation state | `"invalid"` | |
381+
| value | The value of the control | `DateTime` `null` | |
382+
| view | The view of the control | `"normal"` `"clear"` | `"normal"` |

0 commit comments

Comments
 (0)