Skip to content

Commit 8495f1b

Browse files
cab-mikeecab-mikee
committed
chore: improve datetime docs
1 parent 6c1ac03 commit 8495f1b

File tree

7 files changed

+529
-88
lines changed

7 files changed

+529
-88
lines changed

‎docs/features/date.md‎

Lines changed: 102 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,127 @@
1-
# Date Formatting
1+
# Date & DateTime Formatting
22

3-
Format and validate dates with support for various formats and locales.
3+
Format and validate dates with support for various formats, time components, and locales.
44

55
## Basic Usage
66

77
```typescript
8-
import { formatDate, isValidDate, parseDate } from 'ts-inputs'
9-
10-
// Format a date
11-
const formattedDate = formatDate(new Date(), 'YYYY-MM-DD')
12-
// Output: '2024-03-21'
8+
import { BaseInput } from 'ts-inputs'
9+
10+
// Create a date input
11+
const dateInput = new BaseInput('#date-input', {
12+
dateTime: true,
13+
dateTimeOptions: {
14+
format: 'YYYY-MM-DD',
15+
showSeconds: false,
16+
is24Hour: true,
17+
},
18+
onDateTimeFormatChanged: (formatted) => {
19+
console.log('Formatted date:', formatted)
20+
},
21+
onDateTimeValidityChanged: (isValid) => {
22+
console.log('Is valid date:', isValid)
23+
},
24+
})
1325

14-
// Parse a date string
15-
const parsedDate = parseDate('2024-03-21', 'YYYY-MM-DD')
16-
// Output: Date object
26+
// Get the formatted value
27+
const formattedValue = dateInput.getValue()
28+
// Example: '2024-03-21'
1729

18-
// Validate a date
19-
const isValid = isValidDate('2024-03-21')
20-
// Output: true
30+
// Get the unformatted value (numeric only)
31+
const unformattedValue = dateInput.getUnformattedValue()
32+
// Example: '20240321'
2133
```
2234

23-
## Date Formats
24-
25-
The library supports various date formats:
35+
## Date Formats & Options
2636

27-
- `YYYY-MM-DD` (ISO format)
28-
- `MM/DD/YYYY` (US format)
29-
- `DD/MM/YYYY` (European format)
30-
- `YYYY/MM/DD` (Japanese format)
31-
32-
## Locale Support
37+
The datetime input supports various configuration options:
3338

3439
```typescript
35-
import { formatDate, setLocale } from 'ts-inputs'
40+
const dateTimeInput = new BaseInput('#date-time-input', {
41+
dateTime: true,
42+
dateTimeOptions: {
43+
// Date format options
44+
format: 'YYYY-MM-DD HH:mm:ss', // Full format
45+
dateFormat: 'YYYY-MM-DD', // Date part format
46+
timeFormat: 'HH:mm:ss', // Time part format
47+
dateSeparator: '-', // Date component separator
48+
timeSeparator: ':', // Time component separator
49+
separator: ' ', // Separator between date and time
50+
51+
// Time format options
52+
is24Hour: true, // Use 24-hour format
53+
showSeconds: true, // Show seconds in time
54+
55+
// Validation options
56+
strictMode: true, // Enforce strict validation
57+
minDate: '2024-01-01', // Minimum allowed date
58+
maxDate: '2024-12-31', // Maximum allowed date
59+
disabledDates: ['2024-03-15'], // Disabled dates
60+
61+
// Other options
62+
locale: 'en-US', // Locale for formatting
63+
allowEmpty: true, // Allow empty input
64+
placeholder: 'Enter date...', // Input placeholder
65+
},
66+
})
67+
```
3668

37-
// Set locale
38-
setLocale('en-US')
69+
## Validation Features
3970

40-
// Format with locale
41-
const formattedDate = formatDate(new Date(), 'LL', { locale: 'en-US' })
42-
// Output: 'March 21, 2024'
71+
The datetime input includes comprehensive validation:
72+
73+
```typescript
74+
const dateInput = new BaseInput('#validated-date-input', {
75+
dateTime: true,
76+
dateTimeOptions: {
77+
strictMode: true,
78+
minDate: new Date('2024-01-01'),
79+
maxDate: new Date('2024-12-31'),
80+
disabledDates: [
81+
'2024-03-15',
82+
'2024-03-16',
83+
],
84+
},
85+
onDateTimeValidityChanged: (isValid) => {
86+
if (!isValid) {
87+
console.log('Invalid date selected')
88+
}
89+
},
90+
})
4391
```
4492

45-
## Date Validation
93+
## Direct API Usage
94+
95+
You can also use the formatting functions directly:
4696

4797
```typescript
48-
import { isValidDate, validateDate } from 'ts-inputs'
98+
import { formatDateTime, isValidDateTime, unformatDateTime } from 'ts-inputs'
4999

50-
// Simple validation
51-
const isValid = isValidDate('2024-03-21')
100+
// Format a date string
101+
const formatted = formatDateTime('20240321', {
102+
format: 'YYYY-MM-DD',
103+
strictMode: true,
104+
})
105+
// Output: '2024-03-21'
52106

53-
// Advanced validation with options
54-
const validation = validateDate('2024-03-21', {
55-
minDate: new Date('2024-01-01'),
56-
maxDate: new Date('2024-12-31'),
57-
format: 'YYYY-MM-DD'
107+
// Validate a date
108+
const isValid = isValidDateTime('2024-03-21', {
109+
minDate: '2024-01-01',
110+
maxDate: '2024-12-31',
58111
})
112+
// Output: true
113+
114+
// Get unformatted value
115+
const unformatted = unformatDateTime('2024-03-21')
116+
// Output: '20240321'
59117
```
60118

61119
## Error Handling
62120

63-
```typescript
64-
try {
65-
const formattedDate = formatDate('invalid-date', 'YYYY-MM-DD')
66-
}
67-
catch (error) {
68-
console.error('Invalid date:', error.message)
69-
}
70-
```
121+
The input handles various edge cases gracefully:
122+
123+
- Invalid dates are prevented in strict mode
124+
- Out-of-range values are handled according to validation rules
125+
- Empty values are allowed when `allowEmpty` is true
126+
- Disabled dates are prevented from being selected
127+
- Min/max date constraints are enforced

‎docs/features/time.md‎

Lines changed: 125 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,153 @@
11
# Time Formatting
22

3-
Format and validate time values with support for different formats.
3+
Format and validate time values with support for both 12-hour and 24-hour formats.
44

55
## Basic Usage
66

77
```typescript
8-
import { formatTime, isValidTime, parseTime } from 'ts-inputs'
9-
10-
// Format a time
11-
const formattedTime = formatTime('14:30:00')
12-
// Output: '02:30 PM'
8+
import { BaseInput } from 'ts-inputs'
9+
10+
// Create a time-only input
11+
const timeInput = new BaseInput('#time-input', {
12+
dateTime: true,
13+
dateTimeOptions: {
14+
format: 'HH:mm:ss',
15+
is24Hour: false,
16+
showSeconds: true,
17+
},
18+
onDateTimeFormatChanged: (formatted) => {
19+
console.log('Formatted time:', formatted)
20+
},
21+
onDateTimeValidityChanged: (isValid) => {
22+
console.log('Is valid time:', isValid)
23+
},
24+
})
1325

14-
// Parse a time string
15-
const parsedTime = parseTime('02:30 PM')
16-
// Output: '14:30:00'
26+
// Get the formatted value
27+
const formattedValue = timeInput.getValue()
28+
// Example: '02:30:00 PM'
1729

18-
// Validate a time
19-
const isValid = isValidTime('14:30:00')
20-
// Output: true
30+
// Get the unformatted value (numeric only)
31+
const unformattedValue = timeInput.getUnformattedValue()
32+
// Example: '143000'
2133
```
2234

23-
## Time Formats
35+
## Time Format Options
2436

25-
The library supports various time formats:
37+
The datetime input supports various time formats:
2638

27-
- `HH:mm:ss` (24-hour format)
28-
- `hh:mm:ss a` (12-hour format with AM/PM)
29-
- `HH:mm` (24-hour format without seconds)
30-
- `hh:mm a` (12-hour format without seconds)
39+
```typescript
40+
const timeInput = new BaseInput('#time-input', {
41+
dateTime: true,
42+
dateTimeOptions: {
43+
// Time format options
44+
format: 'HH:mm:ss', // Full time format
45+
timeFormat: 'HH:mm:ss', // Time format pattern
46+
timeSeparator: ':', // Time component separator
47+
48+
// Display options
49+
is24Hour: true, // Use 24-hour format (false for 12-hour with AM/PM)
50+
showSeconds: true, // Include seconds in the time
51+
52+
// Validation options
53+
strictMode: true, // Enforce strict time validation
54+
55+
// Other options
56+
allowEmpty: true, // Allow empty input
57+
placeholder: 'Enter time...', // Input placeholder
58+
},
59+
})
60+
```
61+
62+
## Format Examples
3163

32-
## Format Options
64+
The input supports multiple time formats:
3365

3466
```typescript
35-
import { formatTime, TimeFormat } from 'ts-inputs'
67+
// 24-hour format with seconds
68+
const militaryTime = new BaseInput('#military-time', {
69+
dateTime: true,
70+
dateTimeOptions: {
71+
format: 'HH:mm:ss',
72+
is24Hour: true,
73+
showSeconds: true,
74+
},
75+
})
76+
// Output: '14:30:00'
77+
78+
// 12-hour format without seconds
79+
const standardTime = new BaseInput('#standard-time', {
80+
dateTime: true,
81+
dateTimeOptions: {
82+
format: 'hh:mm a',
83+
is24Hour: false,
84+
showSeconds: false,
85+
},
86+
})
87+
// Output: '02:30 PM'
3688

37-
// Different format options
38-
const formats = {
39-
twentyFourHour: formatTime('14:30:00', TimeFormat.TWENTY_FOUR_HOUR),
40-
// Output: '14:30'
89+
// 24-hour format without seconds
90+
const shortTime = new BaseInput('#short-time', {
91+
dateTime: true,
92+
dateTimeOptions: {
93+
format: 'HH:mm',
94+
is24Hour: true,
95+
showSeconds: false,
96+
},
97+
})
98+
// Output: '14:30'
99+
```
41100

42-
twelveHour: formatTime('14:30:00', TimeFormat.TWELVE_HOUR),
43-
// Output: '02:30 PM'
101+
## Time Validation
44102

45-
withSeconds: formatTime('14:30:00', TimeFormat.WITH_SECONDS),
46-
// Output: '14:30:00'
47-
}
103+
The input includes built-in validation for time values:
104+
105+
```typescript
106+
const timeInput = new BaseInput('#validated-time', {
107+
dateTime: true,
108+
dateTimeOptions: {
109+
strictMode: true, // Enables strict validation
110+
},
111+
onDateTimeValidityChanged: (isValid) => {
112+
if (!isValid) {
113+
console.log('Invalid time format')
114+
}
115+
},
116+
})
48117
```
49118

50-
## Validation
119+
## Direct API Usage
120+
121+
You can also use the formatting functions directly:
51122

52123
```typescript
53-
import { validateTime } from 'ts-inputs'
124+
import { formatDateTime, isValidDateTime, unformatDateTime } from 'ts-inputs'
54125

55-
// Validate with options
56-
const validation = validateTime('14:30:00', {
57-
format: TimeFormat.TWENTY_FOUR_HOUR,
58-
strict: true
126+
// Format a time string
127+
const formatted = formatDateTime('143000', {
128+
format: 'HH:mm:ss',
129+
is24Hour: true,
130+
showSeconds: true,
59131
})
132+
// Output: '14:30:00'
133+
134+
// Validate a time
135+
const isValid = isValidDateTime('14:30:00', {
136+
strictMode: true,
137+
})
138+
// Output: true
139+
140+
// Get unformatted value
141+
const unformatted = unformatDateTime('14:30:00')
142+
// Output: '143000'
60143
```
61144

62145
## Error Handling
63146

64-
```typescript
65-
try {
66-
const formattedTime = formatTime('invalid-time')
67-
}
68-
catch (error) {
69-
console.error('Invalid time:', error.message)
70-
}
71-
```
147+
The time input handles various edge cases:
148+
149+
- Invalid hours (>23 in 24-hour format or >12 in 12-hour format)
150+
- Invalid minutes or seconds (>59)
151+
- Automatic AM/PM conversion
152+
- Empty value handling
153+
- Strict mode validation

0 commit comments

Comments
 (0)