Merge pull request #11878 from brambrink/ufc/2212-date-clarify-reference-date

Date Picker improve reference date documentation

Author: ConnorLand

content/en/docs/refguide/modeling/pages/input-widgets/date-picker.md

@@ -63,19 +63,20 @@ The possible values for date format are shown below:
 
 If you choose **Custom** as the date format (see above), this property determines how the value is formatted. The custom date format is a string that allows for any combination of symbols found in the table below. Any punctuation will be rendered literally.
 
-{{% alert color="info" %}}
-When using `yyyy` custom format and typing `yy` in the date picker widget, the century guessing by proximity follows the rule of **50/50**. Specifically, it adjusts dates to be within 50 years before and 50 years after the time the date format instance is created:
-
-* `24` {{< icon name="arrow-narrow-right" >}} `2024`
-* `75` {{< icon name="arrow-narrow-right" >}} `1975`
-{{% /alert %}}
+Custom date formats, as well as date handling in general, are tricky technologies with real business ramifications. Be aware of the following behaviors when using this widget:
+
+* When the custom date format uses `yyyy`, the date picker also accepts a two-digit year (`yy`).
+*  The date picker uses a reference date for parsing partial date inputs (for example `mm/dd` or `yy/mm/dd`) into complete date inputs `yyyy/mm/dd`. The reference date is the date from the value already in the field. If the field is empty, the current date is the reference date.
+* For two-digit year input, the date picker chooses the century that places the entered year closest to the reference year. If two years are equally close, it chooses the earlier year.
+    * For example, with `2026` as the reference year (if the field previously contained a date in `1970`, entering `24` results in `1924`):
+        * `24` {{< icon name="arrow-narrow-right" >}} `2024`
+        * `75` {{< icon name="arrow-narrow-right" >}} `2075`
+        * `76` {{< icon name="arrow-narrow-right" >}} `1976`
+        * `97` {{< icon name="arrow-narrow-right" >}} `1997`
+* Even though a date picker with a custom date format is editable, the calendar drop-down button will only be shown if the custom format represents a full date (that is, the year [`y`–`yyyy`], month [`M`–`MMMM`], and day of month [`d`–`dd`] tokens are all present in the custom format).
 
 {{% snippet file="/static/_includes/refguide/custom-date-format-tokens.md" %}}
 
-{{% alert color="info" %}}
-Even though a date picker with a custom date format is editable, the calendar drop-down button will only be shown if the custom format represents a full date (that is, the year [`y`-`yyyy`], month [`M`-`MMMM`], and day of month [`d`-`dd`] tokens are all present in the custom format).
-{{% /alert %}}
-
 #### Placeholder Text
 
 The placeholder text is shown if the date value is empty. It can be used to give the end-user a hint as to the expected format.