docs: add DateValue type reference (#462)

Co-authored-by: Andre Morise <andre.morise@pax.us>

sites/docs/src/lib/content/api-reference/calendar.ts

@@ -14,6 +14,7 @@ import type {
 } from "bits-ui";
 import { attrsSlotProp, builderAndAttrsSlotProps, domElProps } from "./helpers.js";
 import { enums, monthsSlotProp, weekdaysSlotProp } from "$lib/content/api-reference/helpers.js";
+import { dateValueProp } from "$lib/content/api-reference/extended-types/index.js";
 import * as C from "$lib/content/constants.js";
 import type { APISchema } from "$lib/types/index.js";
 
@@ -22,7 +23,7 @@ export const root: APISchema<CalendarPropsWithoutHTML> = {
 	description: "The root calendar component which contains all other calendar components.",
 	props: {
 		value: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The selected date.",
 		},
 		onValueChange: {
@@ -33,7 +34,7 @@ export const root: APISchema<CalendarPropsWithoutHTML> = {
 			description: "A function that is called when the selected date changes.",
 		},
 		placeholder: {
-			type: "DateValue",
+			type: dateValueProp,
 			description:
 				"The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar, and can be used to programatically control the calendar's view.",
 		},
@@ -95,11 +96,11 @@ export const root: APISchema<CalendarPropsWithoutHTML> = {
 			description: "A function that returns whether or not a date is unavailable.",
 		},
 		maxValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The maximum date that can be selected.",
 		},
 		minValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The minimum date that can be selected.",
 		},
 		locale: {
@@ -164,7 +165,7 @@ export const cell: APISchema<CalendarCellPropsWithoutHTML> = {
 	description: "A cell in the calendar grid.",
 	props: {
 		date: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The date for the cell.",
 		},
 		...domElProps("HTMLTableCellElement"),
@@ -189,11 +190,11 @@ export const day: APISchema<CalendarDayPropsWithoutHTML> = {
 	description: "A day in the calendar grid.",
 	props: {
 		date: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The date for the cell.",
 		},
 		month: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The current month the date is being displayed in.",
 		},
 		...domElProps("HTMLDivElement"),

sites/docs/src/lib/content/api-reference/date-field.ts

@@ -6,6 +6,7 @@ import type {
 } from "bits-ui";
 import { builderAndAttrsSlotProps } from "./helpers.js";
 import { domElProps, enums, idsSlotProp, union } from "$lib/content/api-reference/helpers.js";
+import { dateValueProp } from "$lib/content/api-reference/extended-types/index.js";
 import * as C from "$lib/content/constants.js";
 import type { APISchema } from "$lib/types/index.js";
 
@@ -14,7 +15,7 @@ export const root: APISchema<DateFieldPropsWithoutHTML> = {
 	description: "The root date field component.",
 	props: {
 		value: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The selected date.",
 		},
 		onValueChange: {
@@ -25,7 +26,7 @@ export const root: APISchema<DateFieldPropsWithoutHTML> = {
 			description: "A function that is called when the selected date changes.",
 		},
 		placeholder: {
-			type: "DateValue",
+			type: dateValueProp,
 			description:
 				"The placeholder date, which is used to determine what date to start the segments from when no value exists.",
 		},
@@ -75,11 +76,11 @@ export const root: APISchema<DateFieldPropsWithoutHTML> = {
 				"The id of your description element, if any, which will be applied to the `aria-describedby` attribute of the appropriate elements.",
 		},
 		maxValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The maximum valid date that can be entered.",
 		},
 		minValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The minimum valid date that can be entered.",
 		},
 		locale: {

sites/docs/src/lib/content/api-reference/date-picker.ts

@@ -17,7 +17,7 @@ import {
 	prevButton,
 } from "./calendar.js";
 import { label, segment } from "./date-field.js";
-import { focusProp } from "./extended-types/index.js";
+import { dateValueProp, focusProp } from "./extended-types/index.js";
 import { builderAndAttrsSlotProps, portalProp } from "./helpers.js";
 import { content, trigger } from "./popover.js";
 import type { APISchema } from "$lib/types/index.js";
@@ -36,7 +36,7 @@ const root: APISchema<DatePickerPropsWithoutHTML> = {
 	description: "The root date picker component.",
 	props: {
 		value: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The selected date.",
 		},
 		onValueChange: {
@@ -47,7 +47,7 @@ const root: APISchema<DatePickerPropsWithoutHTML> = {
 			description: "A function that is called when the selected date changes.",
 		},
 		placeholder: {
-			type: "DateValue",
+			type: dateValueProp,
 			description:
 				"The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar, and can be used to programatically control the calendar's view.",
 		},
@@ -109,11 +109,11 @@ const root: APISchema<DatePickerPropsWithoutHTML> = {
 			description: "A function that returns whether or not a date is unavailable.",
 		},
 		maxValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The maximum date that can be selected.",
 		},
 		minValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The minimum date that can be selected.",
 		},
 		locale: {

sites/docs/src/lib/content/api-reference/date-range-field.ts

@@ -6,6 +6,7 @@ import type {
 } from "bits-ui";
 import { builderAndAttrsSlotProps } from "./helpers.js";
 import { domElProps, enums, idsSlotProp, union } from "$lib/content/api-reference/helpers.js";
+import { dateValueProp } from "$lib/content/api-reference/extended-types/index.js";
 import * as C from "$lib/content/constants.js";
 import type { APISchema } from "$lib/types/index.js";
 
@@ -28,7 +29,7 @@ export const root: APISchema<DateRangeFieldPropsWithoutHTML> = {
 			description: "A function that is called when the selected date changes.",
 		},
 		placeholder: {
-			type: "DateValue",
+			type: dateValueProp,
 			description:
 				"The placeholder date, which is used to determine what date to start the segments from when no value exists.",
 		},
@@ -78,11 +79,11 @@ export const root: APISchema<DateRangeFieldPropsWithoutHTML> = {
 				"The id of your description element, if any, which will be applied to the `aria-describedby` attribute of the appropriate elements.",
 		},
 		maxValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The maximum valid date that can be entered.",
 		},
 		minValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The minimum valid date that can be entered.",
 		},
 		locale: {

sites/docs/src/lib/content/api-reference/date-range-picker.ts

@@ -4,7 +4,7 @@ import type {
 	DateRangePickerPropsWithoutHTML,
 } from "bits-ui";
 import { label, segment } from "./date-range-field.js";
-import { focusProp } from "./extended-types/index.js";
+import { dateValueProp, focusProp } from "./extended-types/index.js";
 import { builderAndAttrsSlotProps, portalProp } from "./helpers.js";
 import { content, trigger } from "./popover.js";
 import {
@@ -50,7 +50,7 @@ const root: APISchema<DateRangePickerPropsWithoutHTML> = {
 			description: "A function that is called when the selected date changes.",
 		},
 		placeholder: {
-			type: "DateValue",
+			type: dateValueProp,
 			description:
 				"The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar, and can be used to programatically control the calendar's view.",
 		},
@@ -112,11 +112,11 @@ const root: APISchema<DateRangePickerPropsWithoutHTML> = {
 			description: "A function that returns whether or not a date is unavailable.",
 		},
 		maxValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The maximum date that can be selected.",
 		},
 		minValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The minimum date that can be selected.",
 		},
 		locale: {

sites/docs/src/lib/content/api-reference/extended-types/date-value.ts

@@ -0,0 +1,6 @@
+import type { DateValue } from "@internationalized/date";
+
+/**
+ * Represents a date and/or time in a specific calendar system.
+ * type DateValue = CalendarDate | CalendarDateTime | ZonedDateTime;
+ */

sites/docs/src/lib/content/api-reference/extended-types/index.ts

@@ -1,8 +1,14 @@
 import rawFocusProp from "$lib/content/api-reference/extended-types/focus-target.js?raw";
 import rawMonthProp from "$lib/content/api-reference/extended-types/months.js?raw";
+import rawDateValueProp from "$lib/content/api-reference/extended-types/date-value.js?raw";
 import rawPageItemProp from "$lib/content/api-reference/extended-types/page-item.js?raw";
 import type { PropType } from "$lib/types/index.js";
 
+export const dateValueProp: PropType = {
+	type: "DateValue",
+	definition: rawDateValueProp,
+};
+
 export const monthsPropType: PropType = {
 	type: "Month[]",
 	definition: rawMonthProp,

sites/docs/src/lib/content/api-reference/range-calendar.ts

@@ -13,6 +13,7 @@ import type {
 	RangeCalendarPropsWithoutHTML,
 } from "bits-ui";
 import { builderAndAttrsSlotProps, domElProps } from "./helpers.js";
+import { dateValueProp } from "$lib/content/api-reference/extended-types/index.js";
 import {
 	attrsSlotProp,
 	enums,
@@ -42,7 +43,7 @@ export const root: APISchema<RangeCalendarPropsWithoutHTML> = {
 			description: "A function that is called when the selected date range changes.",
 		},
 		placeholder: {
-			type: "DateValue",
+			type: dateValueProp,
 			description:
 				"The placeholder date, which is used to determine what month to display when no date range is selected. This updates as the user navigates the calendar, and can be used to programatically control the calendar's view.",
 		},
@@ -104,11 +105,11 @@ export const root: APISchema<RangeCalendarPropsWithoutHTML> = {
 			description: "A function that returns whether or not a date is unavailable.",
 		},
 		maxValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The maximum date that can be selected.",
 		},
 		minValue: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The minimum date that can be selected.",
 		},
 		locale: {
@@ -192,7 +193,7 @@ export const cell: APISchema<RangeCalendarCellPropsWithoutHTML> = {
 	description: "A cell in the calendar grid.",
 	props: {
 		date: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The date for the cell.",
 		},
 		...domElProps("HTMLTableCellElement"),
@@ -217,11 +218,11 @@ export const day: APISchema<RangeCalendarDayPropsWithoutHTML> = {
 	description: "A day in the calendar grid.",
 	props: {
 		date: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The date for the cell.",
 		},
 		month: {
-			type: "DateValue",
+			type: dateValueProp,
 			description: "The current month the date is being displayed in.",
 		},
 		...domElProps("HTMLDivElement"),