From df5a823236394bffc0275eebd9c945b727075713 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 25 Aug 2023 12:22:35 -0400 Subject: [PATCH 01/10] docs(datetime): add playground for customizing calendar days --- docs/api/datetime.md | 21 +++- .../angular/example_component_css.md | 52 ++++++++++ .../angular/example_component_html.md | 3 + .../angular/example_component_ts.md | 32 ++++++ .../datetime/styling/calendar-days/demo.html | 97 +++++++++++++++++++ .../datetime/styling/calendar-days/index.md | 35 +++++++ .../styling/calendar-days/javascript.md | 78 +++++++++++++++ .../styling/calendar-days/react/main_css.md | 52 ++++++++++ .../styling/calendar-days/react/main_tsx.md | 36 +++++++ .../v7/datetime/styling/calendar-days/vue.md | 94 ++++++++++++++++++ 10 files changed, 495 insertions(+), 5 deletions(-) create mode 100644 static/usage/v7/datetime/styling/calendar-days/angular/example_component_css.md create mode 100644 static/usage/v7/datetime/styling/calendar-days/angular/example_component_html.md create mode 100644 static/usage/v7/datetime/styling/calendar-days/angular/example_component_ts.md create mode 100644 static/usage/v7/datetime/styling/calendar-days/demo.html create mode 100644 static/usage/v7/datetime/styling/calendar-days/index.md create mode 100644 static/usage/v7/datetime/styling/calendar-days/javascript.md create mode 100644 static/usage/v7/datetime/styling/calendar-days/react/main_css.md create mode 100644 static/usage/v7/datetime/styling/calendar-days/react/main_tsx.md create mode 100644 static/usage/v7/datetime/styling/calendar-days/vue.md diff --git a/docs/api/datetime.md b/docs/api/datetime.md index 26368c8f2b6..4fa89d1cdce 100644 --- a/docs/api/datetime.md +++ b/docs/api/datetime.md @@ -37,6 +37,7 @@ import HighlightedDatesCallback from '@site/static/usage/v7/datetime/highlighted import MultipleDateSelection from '@site/static/usage/v7/datetime/multiple/index.md'; import GlobalTheming from '@site/static/usage/v7/datetime/styling/global-theming/index.md'; +import CalendarDaysStyling from '@site/static/usage/v7/datetime/styling/calendar-days/index.md'; import WheelStyling from '@site/static/usage/v7/datetime/styling/wheel-styling/index.md'; @@ -50,7 +51,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Datetimes present a calendar interface and time wheel, making it easy for users to select dates and times. Datetimes are similar to the native `input` elements of `datetime-local`, however, Ionic Framework's Datetime component makes it easy to display the date and time in the preferred format, and manage the datetime values. -## Overview +## Overview Historically, handling datetime values within JavaScript, or even within HTML inputs, has always been a challenge. Specifically, JavaScript's `Date` object is @@ -100,7 +101,7 @@ If you need to present a datetime in an overlay such as a modal or a popover, we ## Setting Values Asynchronously -If its `value` is updated programmatically after a datetime has already been created, the datetime will automatically jump to the new date. However, it is recommended to avoid updating the `value` in this way when users are able to interact with the datetime, as this could be disorienting for those currently trying to select a date. For example, if a datetime's `value` is loaded by an asyncronous process, it is recommended to hide the datetime with CSS until the value has finished updating. +If its `value` is updated programmatically after a datetime has already been created, the datetime will automatically jump to the new date. However, it is recommended to avoid updating the `value` in this way when users are able to interact with the datetime, as this could be disorienting for those currently trying to select a date. For example, if a datetime's `value` is loaded by an asynchronous process, it is recommended to hide the datetime with CSS until the value has finished updating. ## Date Constraints @@ -108,7 +109,7 @@ If its `value` is updated programmatically after a datetime has already been cre To customize the minimum and maximum datetime values, the `min` and `max` component properties can be provided which may make more sense for the app's use-case. Following the same IS0 8601 format listed in the table above, each component can restrict which dates can be selected by the user. -The following example restricts date selection to March 2022 through May 2022 only. +The following example restricts date selection to March 2022 through May 2022 only. @@ -122,7 +123,7 @@ The following example allows minutes to be selected in increments of 15. It also ### Advanced Date Constraints -With the `isDateEnabled` property, developers can customize the `ion-datetime` to disable a specific day, range of dates, weekends or any custom rule using an ISO 8601 date string. +With the `isDateEnabled` property, developers can customize the `ion-datetime` to disable a specific day, range of dates, weekends or any custom rule using an ISO 8601 date string. The `isDateEnabled` property accepts a function returning a boolean, indicating if a date is enabled. The function is called for each rendered calendar day, for the previous, current and next month. Custom implementations should be optimized for performance to avoid jank. The following example shows how to disable all weekend dates. For more advanced date manipulation, we recommend using a date utility such as `date-fns`. @@ -325,6 +326,16 @@ The benefit of this approach is that every component, not just `ion-datetime`, c +### Calendar Days + +The calendar days in the grid-style of an `ion-datetime` can be styled using CSS shadow parts. + +:::note +The example below selects the day 2 days ago, unless that day is in the previous month, then it selects a day 2 days in the future. This is done for demo purposes in order to show how to apply custom styling to all days, the current day, and the selected day. +::: + + + ### Wheel Pickers The wheels used in `ion-datetime` can be styled through a combination of shadow parts and CSS variables. This applies to both the columns in wheel-style datetimes, and the month/year picker in grid-style datetimes. @@ -367,7 +378,7 @@ import { format, parseISO } from 'date-fns'; /** * This is provided in the event * payload from the `ionChange` event. - * + * * The value is an ISO-8601 date string. */ const dateFromIonDatetime = '2021-06-04T14:23:00-04:00'; diff --git a/static/usage/v7/datetime/styling/calendar-days/angular/example_component_css.md b/static/usage/v7/datetime/styling/calendar-days/angular/example_component_css.md new file mode 100644 index 00000000000..e6b22947fca --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/angular/example_component_css.md @@ -0,0 +1,52 @@ +```css +/* +* Custom Datetime Day Parts +* ------------------------------------------- +*/ + +ion-datetime::part(calendar-day) { + color: #da5296; + + margin: 2px 0; +} + +ion-datetime::part(calendar-day today) { + color: #8462d1; +} + +/* +* Custom Material Design Datetime Day Parts +* ------------------------------------------- +*/ + +ion-datetime.md::part(calendar-day):focus { + background-color: rgb(154 209 98 / 0.2); + box-shadow: 0px 0px 0px 4px rgb(154 209 98 / 0.2); +} + +ion-datetime.md::part(calendar-day active), +ion-datetime.md::part(calendar-day active):focus { + background-color: #9ad162; + border-color: #9ad162; + color: #fff; +} + +ion-datetime.md::part(calendar-day today) { + border-color: #8462d1; +} + +/* +* Custom iOS Datetime Day Parts +* ------------------------------------------- +*/ + +ion-datetime.ios::part(calendar-day):focus { + background-color: rgb(154 209 98 / 0.2); +} + +ion-datetime.ios::part(calendar-day active), +ion-datetime.ios::part(calendar-day active):focus { + background-color: rgb(154 209 98 / 0.2); + color: #9ad162; +} +``` diff --git a/static/usage/v7/datetime/styling/calendar-days/angular/example_component_html.md b/static/usage/v7/datetime/styling/calendar-days/angular/example_component_html.md new file mode 100644 index 00000000000..dde0aec7085 --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/angular/example_component_html.md @@ -0,0 +1,3 @@ +```html + +``` diff --git a/static/usage/v7/datetime/styling/calendar-days/angular/example_component_ts.md b/static/usage/v7/datetime/styling/calendar-days/angular/example_component_ts.md new file mode 100644 index 00000000000..209113236f7 --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/angular/example_component_ts.md @@ -0,0 +1,32 @@ +```ts +import { Component, OnInit, ViewChild } from '@angular/core'; + +@Component({ + selector: 'app-example', + templateUrl: 'example.component.html', + styleUrls: ['example.component.css'], +}) +export class ExampleComponent implements OnInit { + public datetime; + + ngOnInit() { + const date = new Date(); + + // Set the value of the datetime to 2 days + // before the current day + let dayChange = -2; + + // If the day we are going to set the value to + // is in the previous month then set the day 2 days + // later instead so it remains in the same month + if (date.getDate() + dayChange <= 0) { + dayChange = -dayChange; + } + + // Set the value of the datetime to the day + // calculated above + date.setDate(date.getDate() + dayChange); + this.datetime = date.toISOString().substr(0, 19); + } +} +``` diff --git a/static/usage/v7/datetime/styling/calendar-days/demo.html b/static/usage/v7/datetime/styling/calendar-days/demo.html new file mode 100644 index 00000000000..9688831813f --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/demo.html @@ -0,0 +1,97 @@ + + + + + + Datetime + + + + + + + + + + + +
+ +
+ + + + + + diff --git a/static/usage/v7/datetime/styling/calendar-days/index.md b/static/usage/v7/datetime/styling/calendar-days/index.md new file mode 100644 index 00000000000..4ab6c14f639 --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/index.md @@ -0,0 +1,35 @@ +import Playground from '@site/src/components/global/Playground'; + +import javascript from './javascript.md'; + +import react_main_tsx from './react/main_tsx.md'; +import react_main_css from './react/main_css.md'; + +import vue from './vue.md'; + +import angular_example_component_html from './angular/example_component_html.md'; +import angular_example_component_css from './angular/example_component_css.md'; +import angular_example_component_ts from './angular/example_component_ts.md'; + + diff --git a/static/usage/v7/datetime/styling/calendar-days/javascript.md b/static/usage/v7/datetime/styling/calendar-days/javascript.md new file mode 100644 index 00000000000..5ff975721a5 --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/javascript.md @@ -0,0 +1,78 @@ +```html + + + + + +``` diff --git a/static/usage/v7/datetime/styling/calendar-days/react/main_css.md b/static/usage/v7/datetime/styling/calendar-days/react/main_css.md new file mode 100644 index 00000000000..e6b22947fca --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/react/main_css.md @@ -0,0 +1,52 @@ +```css +/* +* Custom Datetime Day Parts +* ------------------------------------------- +*/ + +ion-datetime::part(calendar-day) { + color: #da5296; + + margin: 2px 0; +} + +ion-datetime::part(calendar-day today) { + color: #8462d1; +} + +/* +* Custom Material Design Datetime Day Parts +* ------------------------------------------- +*/ + +ion-datetime.md::part(calendar-day):focus { + background-color: rgb(154 209 98 / 0.2); + box-shadow: 0px 0px 0px 4px rgb(154 209 98 / 0.2); +} + +ion-datetime.md::part(calendar-day active), +ion-datetime.md::part(calendar-day active):focus { + background-color: #9ad162; + border-color: #9ad162; + color: #fff; +} + +ion-datetime.md::part(calendar-day today) { + border-color: #8462d1; +} + +/* +* Custom iOS Datetime Day Parts +* ------------------------------------------- +*/ + +ion-datetime.ios::part(calendar-day):focus { + background-color: rgb(154 209 98 / 0.2); +} + +ion-datetime.ios::part(calendar-day active), +ion-datetime.ios::part(calendar-day active):focus { + background-color: rgb(154 209 98 / 0.2); + color: #9ad162; +} +``` diff --git a/static/usage/v7/datetime/styling/calendar-days/react/main_tsx.md b/static/usage/v7/datetime/styling/calendar-days/react/main_tsx.md new file mode 100644 index 00000000000..5f96e3edcc8 --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/react/main_tsx.md @@ -0,0 +1,36 @@ +```tsx +import React, { useEffect, useState } from 'react'; +import { IonDatetime } from '@ionic/react'; + +import './main.css'; + +function Example() { + const [datetime, setDatetime] = useState(null); + + useEffect(() => { + const date = new Date(); + + // Set the value of the datetime to 2 days + // before the current day + let dayChange = -2; + + // If the day we are going to set the value to + // is in the previous month then set the day 2 days + // later instead so it remains in the same month + if (date.getDate() + dayChange <= 0) { + dayChange = -dayChange; + } + + // Set the value of the datetime to the day + // calculated above + date.setDate(date.getDate() + dayChange); + setDatetime(date.toISOString().substr(0, 19)); + }, []); + + return ( + + ); +} +export default Example; +``` + diff --git a/static/usage/v7/datetime/styling/calendar-days/vue.md b/static/usage/v7/datetime/styling/calendar-days/vue.md new file mode 100644 index 00000000000..9718fb17e77 --- /dev/null +++ b/static/usage/v7/datetime/styling/calendar-days/vue.md @@ -0,0 +1,94 @@ +```html + + + + + +``` From c81f746bd265bde92993a71a04abd29059f59f9d Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 25 Aug 2023 12:22:47 -0400 Subject: [PATCH 02/10] chore: update ionic version for demos --- static/code/stackblitz/v7/angular/package.json | 4 ++-- static/code/stackblitz/v7/html/package.json | 2 +- static/code/stackblitz/v7/react/package.json | 4 ++-- static/code/stackblitz/v7/vue/package.json | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/static/code/stackblitz/v7/angular/package.json b/static/code/stackblitz/v7/angular/package.json index 66f368834db..12d0bfa9ead 100644 --- a/static/code/stackblitz/v7/angular/package.json +++ b/static/code/stackblitz/v7/angular/package.json @@ -1,6 +1,6 @@ { "dependencies": { - "@ionic/angular": "^7.0.0", - "@ionic/core": "^7.0.0" + "@ionic/angular": "7.3.1-dev.11692914300.171273b6", + "@ionic/core": "7.3.1-dev.11692914300.171273b6" } } diff --git a/static/code/stackblitz/v7/html/package.json b/static/code/stackblitz/v7/html/package.json index 7583138334d..3925afc5a22 100644 --- a/static/code/stackblitz/v7/html/package.json +++ b/static/code/stackblitz/v7/html/package.json @@ -1,5 +1,5 @@ { "dependencies": { - "@ionic/core": "^7.0.0" + "@ionic/core": "7.3.1-dev.11692914300.171273b6" } } diff --git a/static/code/stackblitz/v7/react/package.json b/static/code/stackblitz/v7/react/package.json index 9e3c1a361ff..ed2ecc8dd79 100644 --- a/static/code/stackblitz/v7/react/package.json +++ b/static/code/stackblitz/v7/react/package.json @@ -3,8 +3,8 @@ "version": "0.1.0", "private": true, "dependencies": { - "@ionic/react": "^7.0.10", - "@ionic/react-router": "^7.0.10", + "@ionic/react": "7.3.1-dev.11692914300.171273b6", + "@ionic/react-router": "7.3.1-dev.11692914300.171273b6", "@types/node": "^16.11.35", "@types/react": "^18.0.9", "@types/react-dom": "^18.0.4", diff --git a/static/code/stackblitz/v7/vue/package.json b/static/code/stackblitz/v7/vue/package.json index 5d661e04f57..13fa8fb7009 100644 --- a/static/code/stackblitz/v7/vue/package.json +++ b/static/code/stackblitz/v7/vue/package.json @@ -8,8 +8,8 @@ "preview": "vite preview" }, "dependencies": { - "@ionic/vue": "^7.0.10", - "@ionic/vue-router": "^7.0.10", + "@ionic/vue": "7.3.1-dev.11692914300.171273b6", + "@ionic/vue-router": "7.3.1-dev.11692914300.171273b6", "vue": "^3.2.25", "vue-router": "4.0.13" }, From 9b64821c8cc48067fa799f943752b82a4edd4a82 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 25 Aug 2023 12:45:58 -0400 Subject: [PATCH 03/10] style: lint --- .../v7/datetime/styling/calendar-days/react/main_tsx.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/static/usage/v7/datetime/styling/calendar-days/react/main_tsx.md b/static/usage/v7/datetime/styling/calendar-days/react/main_tsx.md index 5f96e3edcc8..93b0b61bf21 100644 --- a/static/usage/v7/datetime/styling/calendar-days/react/main_tsx.md +++ b/static/usage/v7/datetime/styling/calendar-days/react/main_tsx.md @@ -27,10 +27,7 @@ function Example() { setDatetime(date.toISOString().substr(0, 19)); }, []); - return ( - - ); + return ; } export default Example; ``` - From 733626f4e389d9d326b0734eb092f523794dcb2c Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Mon, 28 Aug 2023 12:51:07 -0400 Subject: [PATCH 04/10] docs(datetime): update styling test to remove substr --- .../styling/calendar-days/angular/example_component_ts.md | 2 +- static/usage/v7/datetime/styling/calendar-days/demo.html | 2 +- static/usage/v7/datetime/styling/calendar-days/javascript.md | 2 +- .../usage/v7/datetime/styling/calendar-days/react/main_tsx.md | 2 +- static/usage/v7/datetime/styling/calendar-days/vue.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/static/usage/v7/datetime/styling/calendar-days/angular/example_component_ts.md b/static/usage/v7/datetime/styling/calendar-days/angular/example_component_ts.md index 209113236f7..f1b2ad5ef5b 100644 --- a/static/usage/v7/datetime/styling/calendar-days/angular/example_component_ts.md +++ b/static/usage/v7/datetime/styling/calendar-days/angular/example_component_ts.md @@ -26,7 +26,7 @@ export class ExampleComponent implements OnInit { // Set the value of the datetime to the day // calculated above date.setDate(date.getDate() + dayChange); - this.datetime = date.toISOString().substr(0, 19); + this.datetime = date.toISOString(); } } ``` diff --git a/static/usage/v7/datetime/styling/calendar-days/demo.html b/static/usage/v7/datetime/styling/calendar-days/demo.html index 9688831813f..462e435293a 100644 --- a/static/usage/v7/datetime/styling/calendar-days/demo.html +++ b/static/usage/v7/datetime/styling/calendar-days/demo.html @@ -91,7 +91,7 @@ // Set the value of the datetime to the day // calculated above date.setDate(date.getDate() + dayChange); - datetime.value = date.toISOString().substr(0, 19); + datetime.value = date.toISOString(); diff --git a/static/usage/v7/datetime/styling/calendar-days/javascript.md b/static/usage/v7/datetime/styling/calendar-days/javascript.md index 5ff975721a5..178a843ca2c 100644 --- a/static/usage/v7/datetime/styling/calendar-days/javascript.md +++ b/static/usage/v7/datetime/styling/calendar-days/javascript.md @@ -20,7 +20,7 @@ // Set the value of the datetime to the day // calculated above date.setDate(date.getDate() + dayChange); - datetime.value = date.toISOString().substr(0, 19); + datetime.value = date.toISOString();