Skip to content

Commit 17dc370

Browse files
mark-tatemark-tate
committed
improve docs
- show errors in Formfield based examples - remove dependency on getDayWeekName from adapters - document toJSDate in adapters - re-enforce the need for LocalizationProvider through examples - show how to set the date
1 parent b72c078 commit 17dc370

File tree

20 files changed

+546
-128
lines changed

20 files changed

+546
-128
lines changed

‎site/docs/components/calendar/examples.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@ data:
88
$ref: ./#/data
99
---
1010

11+
<Callout title="Note">
12+
13+
All date components require a [LocalizationProvider](/salt/components/localization-provider/examples) to be set up in your application.
14+
For the purpose of the examples, we use type `DateFrameworkType` so the examples can be used across all date adapters. For your own code you can replace this type with the type of your date object (e.g luxon would use `DateTime` type instead).
15+
16+
</Callout>
17+
1118
## Single date selection
1219

1320
When the `selectionVariant` prop is set to "single", the `Calendar` component allows users to select only a single date, providing a straightforward and focused date selection experience.

‎site/docs/components/calendar/usage.mdx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,28 @@ To import `CalendarGrid` from the Salt lab package, use:
6969
import { CalendarGrid } from "@salt-ds/lab";
7070
```
7171

72+
### Setting the date
73+
74+
Date controls, require your application to contain a [LocalizationProvider](../LocalizationProvider).
75+
76+
Pass a date object from your configured date framework via the `defaultDate` or `date` props.
77+
78+
```tsx
79+
import { DateTime } from "luxon";
80+
import { AdapterLuxon } from "@salt-ds/date-adapters/luxon";
81+
import { LocalizationProvider, DateInputSingle, DateInputRange } from "@salt-ds/lab";
82+
83+
<LocalizationProvider DateAdapter={AdapterLuxon}>
84+
<Calendar
85+
selectionVariant={"single"}
86+
defaultSelectedDate={new DateTime().now()}
87+
>
88+
<CalendarNavigation />
89+
<CalendarGrid />
90+
</Calendar>
91+
<LocalizationProvider>
92+
```
93+
7294
### Locale
7395

7496
The default locale for Salt's date adapters is "enUS".

‎site/docs/components/date-input/examples.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@ data:
88
$ref: ./#/data
99
---
1010

11+
<Callout title="Note">
12+
13+
All date components require a [LocalizationProvider](/salt/components/localization-provider/examples) to be set up in your application.
14+
For the purpose of the examples, we use type `DateFrameworkType` so the examples can be used across all date adapters. For your own code you can replace this type with the type of your date object (e.g luxon would use `DateTime` type instead).
15+
16+
</Callout>
17+
1118
## DateInputSingle
1219

1320
### Uncontrolled single date input
@@ -36,6 +43,16 @@ A `DateInputSingle` component with a border provides a visually distinct input f
3643
exampleName="SingleBordered"
3744
/>
3845

46+
### Custom Parsing
47+
48+
A custom parser can be provided through the `parse` prop.
49+
50+
<LivePreview
51+
componentName="date-input"
52+
displayName="Custom Parser"
53+
exampleName="CustomParser"
54+
/>
55+
3956
### Locale
4057

4158
A `DateInputSingle` component will use the locale defined by the nearest [LocalizationProvider](../LocalizationProvider) to determine locale specifics, such as date format.

‎site/docs/components/date-input/usage.mdx‎

Lines changed: 63 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -21,56 +21,87 @@ To avoid misleading users, set the width of the input to correlate with the leng
2121

2222
Avoid using the `DateInputSingle` component if your application requires users to select a range of dates, in which case the `DateInputRange` component would be more appropriate.
2323

24-
### Parsing
24+
## Import
25+
26+
### DateInputSingle
27+
28+
To import `DateInputSingle` from the Salt lab package, use:
29+
30+
```js
31+
import { DateInputSingle } from "@salt-ds/lab";
32+
```
33+
34+
### DateInputRange
2535

26-
By default, both `DateInputSingle` and `DateInputRange` accept a date string that can be passed to `new Date()`.
27-
28-
If the date string is valid, it is converted to an ISO string and then parsed to a local date using `parseAbsoluteToLocal(date.toISOString())`. The resulting date is then returned as a `CalendarDate` object with the year, month, and day. This default behavior ensures consistent and reliable date parsing, but it can be overridden by providing a custom parse function through the `parse` prop.
29-
30-
**Examples of valid date formats:**
31-
32-
1. **ISO 8601 string:**
33-
- YYYY-MM-DD
34-
- YYYY-MM-DDTHH:MM:SSZ
35-
- YYYY-MM-DDTHH:MM:SS+HH:MM
36-
- Example: "2023-01-15", "2023-01-15T15:45:00Z"
37-
2. **RFC 2822 string:**
38-
- DD MMM YYYY HH:MM:SS GMT
39-
- Example: "15 Jan 2023 15:45:00 GMT"
40-
3. **Date and Time String:**
41-
- Month DD, YYYY HH:MM:SS
42-
- Example: "January 15, 2023 15:45:00"
43-
4. **Date only string:**
44-
- Month DD, YYYY
45-
- Example: "January 15, 2023"
46-
5. **Milliseconds since epoch:**
47-
- Number of milliseconds since January 1, 1970, 00:00:00 UTC.
48-
- Example: 1673793900000
36+
To import `DateInputRange` from the Salt lab package, use:
37+
38+
```js
39+
import { DateInputRange } from "@salt-ds/lab";
40+
```
41+
42+
### Setting the date
43+
44+
Date controls, require your application to contain a [LocalizationProvider](../LocalizationProvider).
45+
46+
Date input accept dates in two formats:
47+
48+
Pass a date string (compatible with `new Date()`) via the `defaultValue` or `value` props.
49+
50+
```tsx
51+
import { DateTime } from "luxon";
52+
import { AdapterLuxon } from "@salt-ds/date-adapters/luxon";
53+
import { LocalizationProvider, DateInputSingle, DateInputRange } from "@salt-ds/lab";
54+
55+
<LocalizationProvider DateAdapter={AdapterLuxon}>
56+
<DateInputSingle
57+
defaultValue={"23 May 2025"}}
58+
/> // un-controlled value
59+
<DateInputRange
60+
value={{ startDate: "23 May 2025", endDate: "24 May 2025"}}
61+
/> // controlled value
62+
<LocalizationProvider>
63+
```
64+
65+
Pass a date object from your configured date framework via the `defaultDate` or `date` props.
66+
67+
```tsx
68+
import { DateTime } from "luxon";
69+
import { AdapterLuxon } from "@salt-ds/date-adapters/luxon";
70+
import { LocalizationProvider, DateInputSingle, DateInputRange } from "@salt-ds/lab";
71+
72+
<LocalizationProvider DateAdapter={AdapterLuxon}>
73+
<DateInputSingle
74+
defaultDate={new DateTime().now()}
75+
/> // un-controlled date
76+
<DateInputRange
77+
value={{ startDate: new DateTime().now(), endDate: new DateTime().now()}}
78+
/> // controlled date
79+
<LocalizationProvider>
80+
```
81+
82+
### Parsing
4983

5084
**Default parsing behavior:**
5185

52-
- If the input date string is valid, it is converted to an ISO string using `date.toISOString()`.
53-
- The ISO string is then parsed to a local date using `parseAbsoluteToLocal(date.toISOString())`.
54-
- The resulting date is returned as a `CalendarDate` object with the year, month, and day.
55-
- If the date string is invalid, the function returns `undefined`.
86+
- For a single a `null` value represents an empty date to ensure controlled components work as expected.
87+
- For date ranges, the `startDate` and `endDate` can be `null` to represent empty dates.
88+
- Invalid dates are represents by the `Invalid Date` object from the configured date framework.
5689

5790
This default behavior ensures consistent and reliable date parsing, but it can be customized by providing a custom parse function through the `parse` prop.
5891

59-
Additionally, you can provide your own `parse` function to convert shorthand dates to valid date objects.
60-
6192
### Formatting
6293

6394
By default, both `DateInputSingle` and `DateInputRange` format dates to `DD MMM YYYY`.
6495

6596
Formatting of entered dates occurs once the value is applied, either by the input losing it's focus or if the 'ENTER' is pressed.
6697

67-
Additionally, you can provide your own `formatDate` function to format `DateValue` to a `string`.
98+
Additionally, you can provide your own formatter through the `format` prop.
6899

69100
### Locale
70101

71102
The default locale for Salt's date adapters is "enUS".
72103

73-
`DateInputSingle` and `DateInputRange` use the locale of the configured date adapter provided by the nearest [LocalizationProvider] (../LocalizationProvider).
104+
`DateInputSingle` and `DateInputRange` use the locale of the configured date adapter provided by the nearest [LocalizationProvider](../LocalizationProvider).
74105
Configuration of locales is date framework specific and may require you to import specific locales from the date library you are using.
75106

76107
For example, if you are using `date-fns`, you may need to import the specific locale you want to use, such as `es` or `frFR`.
@@ -92,24 +123,6 @@ Valid values for `timezone` are date framework specific and can be one of the fo
92123
- "UTC" uses the UTC timezone.
93124
- string uses a specific IANA timezone string, such as "America/New_York" or "Europe/London".
94125

95-
## Import
96-
97-
### DateInputSingle
98-
99-
To import `DateInputSingle` from the Salt lab package, use:
100-
101-
```js
102-
import { DateInputSingle } from "@salt-ds/lab";
103-
```
104-
105-
### DateInputRange
106-
107-
To import `DateInputRange` from the Salt lab package, use:
108-
109-
```js
110-
import { DateInputRange } from "@salt-ds/lab";
111-
```
112-
113126
## Props
114127

115128
### DateInputSingle

‎site/docs/components/date-picker/examples.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ data:
1010

1111
<Callout title="Note">
1212

13-
All date components requires [LocalizationProvider](/salt/components/localization-provider/examples) to be set up in your application.
13+
All date components require a [LocalizationProvider](/salt/components/localization-provider/examples) to be set up in your application.
14+
For the purpose of the examples, we use type `DateFrameworkType` so the examples can be used across all date adapters. For your own code you can replace this type with the type of your date object (e.g luxon would use `DateTime` type instead).
1415

1516
</Callout>
1617

‎site/docs/components/date-picker/range-date-picker/examples.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ data:
1010

1111
<Callout title="Note">
1212

13-
All date components requires [LocalizationProvider](/salt/components/localization-provider/examples) to be set up in your application.
13+
All date components require a [LocalizationProvider](/salt/components/localization-provider/examples) to be set up in your application.
14+
For the purpose of the examples, we use type `DateFrameworkType` so the examples can be used across all date adapters. For your own code you can replace this type with the type of your date object (e.g luxon would use `DateTime` type instead).
1415

1516
</Callout>
1617

‎site/docs/components/date-picker/range-date-picker/usage.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,40 @@ To import `DatePicker` from the Salt lab package, use:
5656
import { DatePicker } from "@salt-ds/lab";
5757
```
5858

59+
### Setting the date
60+
61+
Date controls, require your application to contain a [LocalizationProvider](../LocalizationProvider).
62+
63+
Pass a range object from your configured date framework using the `defaultDate` or `date` props.
64+
65+
```tsx
66+
import { DateTime } from "luxon";
67+
import { AdapterLuxon } from "@salt-ds/date-adapters/luxon";
68+
import {
69+
DateInputRange,
70+
DatePicker,
71+
DatePickerOverlay,
72+
DatePickerRangeGridPanel,
73+
DatePickerRangeInput,
74+
DatePickerTrigger,
75+
LocalizationProvider,
76+
} from "@salt-ds/lab";
77+
78+
<LocalizationProvider DateAdapter={AdapterLuxon}>
79+
<DatePicker
80+
selectionVariant="range"
81+
defaultSelectedDate={{startDate: DateTime.fromFormat("23-06-2025", "dd-MM-yyyy") , endDate: DateTime.fromFormat("25-06-2025", "dd-MM-yyyy")}
82+
>
83+
<DatePickerTrigger>
84+
<DatePickerRangeInput />
85+
</DatePickerTrigger>
86+
<DatePickerOverlay>
87+
<DatePickerRangeGridPanel />
88+
</DatePickerOverlay>
89+
</DatePicker>
90+
<LocalizationProvider>
91+
```
92+
5993
### Locale
6094

6195
The default locale for Salt's date adapters is "enUS".

‎site/docs/components/date-picker/usage.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,40 @@ To import `DatePicker` from the Salt lab package, use:
5555
import { DatePicker } from "@salt-ds/lab";
5656
```
5757

58+
### Setting the date
59+
60+
Date controls, require your application to contain a [LocalizationProvider](../LocalizationProvider).
61+
62+
Pass a date object from your configured date framework via the `defaultDate` or `date` props.
63+
64+
```tsx
65+
import { DateTime } from "luxon";
66+
import { AdapterLuxon } from "@salt-ds/date-adapters/luxon";
67+
import {
68+
DateInputSingle
69+
DatePicker,
70+
DatePickerOverlay,
71+
DatePickerSingleGridPanel,
72+
DatePickerSingleInput,
73+
DatePickerTrigger,
74+
LocalizationProvider,
75+
} from "@salt-ds/lab";
76+
77+
<LocalizationProvider DateAdapter={AdapterLuxon}>
78+
<DatePicker
79+
selectionVariant="single"
80+
defaultSelectedDate={new DateTime().now()}
81+
>
82+
<DatePickerTrigger>
83+
<DatePickerSingleInput />
84+
</DatePickerTrigger>
85+
<DatePickerOverlay>
86+
<DatePickerSingleGridPanel />
87+
</DatePickerOverlay>
88+
</DatePicker>
89+
<LocalizationProvider>
90+
```
91+
5892
### Locale
5993

6094
The default locale for Salt's date adapters is "enUS".

‎site/docs/components/localization-provider/examples.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ data:
88
$ref: ./#/data
99
---
1010

11+
> For the purpose of the examples, we use type `DateFrameworkType` so the examples can be used across all date adapters. For your own code you can replace this type with the type of your date object (e.g luxon would be `DateTime`).
12+
1113
## Adapters
1214

1315
To integrate your date framework with Salt components and enable support for locales or timezones, defining a date adapter is essential. Salt provides date adapters for the most popular date frameworks, which you can extend or use as a foundation to create your own custom adapter.

0 commit comments

Comments
 (0)