[typescript] Generic date type (#1966)

docs/layout/components/navigationMap.ts

@@ -39,6 +39,7 @@ export const navItems = [
   {
     title: 'Guides',
     children: [
+      { title: 'TypeScript', href: '/guides/typescript' },
       { title: 'Accessibility', href: '/guides/accessibility' },
       { title: 'Form integration', href: '/guides/forms' },
       { title: 'CSS overrides', href: '/guides/css-overrides' },

docs/pages/demo/daterangepicker/BasicDateRangePicker.example.tsx

@@ -3,7 +3,7 @@ import TextField from '@material-ui/core/TextField';
 import { DateRangePicker, DateRange, DateRangeDelimiter } from '@material-ui/pickers';
 
 function BasicDateRangePicker() {
-  const [selectedDate, handleDateChange] = React.useState<DateRange>([null, null]);
+  const [selectedDate, handleDateChange] = React.useState<DateRange<Date>>([null, null]);
 
   return (
     <DateRangePicker

docs/pages/demo/daterangepicker/CalendarsDateRangePicker.example.tsx

@@ -4,7 +4,7 @@ import { Typography, TextField } from '@material-ui/core';
 import { DateRangePicker, DateRangeDelimiter, DateRange } from '@material-ui/pickers';
 
 function CalendarsDateRangePicker() {
-  const [selectedDate, handleDateChange] = React.useState<DateRange>([null, null]);
+  const [selectedDate, handleDateChange] = React.useState<DateRange<Date>>([null, null]);
 
   return (
     <Grid container direction="column" alignItems="center">

docs/pages/demo/daterangepicker/CustomRangeInputs.example.tsx

@@ -1,8 +1,8 @@
-import React, { useState } from 'react';
+import * as React from 'react';
 import { DateRangePicker, DateRange } from '@material-ui/pickers';
 
 function CustomRangeInputs() {
-  const [selectedDate, handleDateChange] = useState<DateRange>([null, null]);
+  const [selectedDate, handleDateChange] = React.useState<DateRange<Date>>([null, null]);
 
   return (
     <DateRangePicker

docs/pages/demo/daterangepicker/MinMaxDateRangePicker.example.tsx

@@ -13,7 +13,7 @@ function getWeeksAfter(date: Moment | DateTime | Dayjs | Date, amount: number) {
 }
 
 function MinMaxDateRangePicker() {
-  const [selectedRange, handleDateChange] = React.useState<DateRange>([null, null]);
+  const [selectedRange, handleDateChange] = React.useState<DateRange<Date>>([null, null]);
 
   return (
     <DateRangePicker

docs/pages/demo/daterangepicker/ResponsiveDateRangePicker.example.tsx

@@ -8,7 +8,7 @@ import {
 } from '@material-ui/pickers';
 
 function ResponsiveDateRangePicker() {
-  const [selectedDate, handleDateChange] = React.useState<DateRange>([null, null]);
+  const [selectedDate, handleDateChange] = React.useState<DateRange<Date>>([null, null]);
 
   return (
     <React.Fragment>

docs/pages/demo/daterangepicker/StaticDateRangePicker.example.tsx

@@ -3,7 +3,7 @@ import TextField from '@material-ui/core/TextField';
 import { StaticDateRangePicker, DateRangeDelimiter, DateRange } from '@material-ui/pickers';
 
 function StaticDateRangePickerExample() {
-  const [selectedDate, handleDateChange] = React.useState<DateRange>([null, null]);
+  const [selectedDate, handleDateChange] = React.useState<DateRange<Date>>([null, null]);
 
   return (
     <React.Fragment>

docs/pages/guides/typescript.mdx

@@ -0,0 +1,83 @@
+import PageMeta from '_shared/PageMeta';
+
+<PageMeta
+  title="TypeScript – @material-ui/pickers"
+  description="A guide of how to use @material-ui/pickers with TypeScript"
+/>
+
+## TypeScript guide
+
+The date picker components come with built-in TypeScript definitions.
+Here is some information about how to achive better experience with TypeScript.
+
+<!-- https://stackoverflow.com/questions/62452160/material-datetimepicker-onchange-typescript-mismatch-error/62471345 -->
+
+#### Nullable value
+
+Any picker can return null in the `onChange` argument so if you are using `React.useState`, you **must** manually cast your default value as nullable. (e.g. `Date | null`)
+
+```tsx
+function MyComponent() {
+  const [value, setValue] = React.useState<Date | null>(new Date());
+
+  return (
+    <DatePicker
+      value={value}
+      onChange={newValue => setValue(newValue)}
+      renderInput={props => <TextField {...props} />}
+    />
+  );
+}
+```
+
+#### Generics
+
+The components don't know which adapter you will pass to the `<LocalizationProvider />`. So any picker component is generic by default.
+It means that it will try to infer the `value` and `onChange` type from the passed props.
+
+```tsx
+<DatePicker
+  value={new Date()}
+  // date will be inferred as `Date | null`
+  onChange={newValue => newValue?.getDate()}
+/>
+```
+
+It also means that you can manually set value type thanks to the generic JSX sytax:
+
+```tsx
+<DatePicker<Date>
+  // You can pass any value right here that can be parsed
+  value={new Date()}
+  onChange={newValue => newValue?.getDate()}
+/>
+```
+
+#### Important note on type inference!
+
+If you are passing not typed value to the picker (such like `null`) we cannot properly infer the type for you. It is required to properly type the vaue:
+
+```tsx
+<DatePicker
+  value={null}
+  // @ts-expect-error `Property 'getDate' does not exist on type 'never'.`
+  onChange={newValue => newValue?.getDate()}
+/>
+```
+
+In this case it is required to manually set proper [generic type manually](#generics).
+
+```tsx
+<DatePicker<Date>
+  value={null}
+  onChange={newValue => newValue?.getDate()}
+/>
+
+// Or cast the type for the `value` or `onChange` prop.
+
+<DatePicker
+  value={null as Date | null}
+  // @ts-expect-error `Property 'getDate' does not exist on type 'never'.`
+  onChange={newValue => newValue?.getDate()}
+/>
+```