Skip to content

chore: merge feature-7.4 docs #3118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 14, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions docs/api/checkbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,27 @@ import Basic from '@site/static/usage/v7/checkbox/basic/index.md';

## Label Placement

Developers can use the `labelPlacement` property to control how the label is placed relative to the control.
Developers can use the `labelPlacement` property to control how the label is placed relative to the control. This property mirrors the flexbox `flex-direction` property.

import LabelPlacement from '@site/static/usage/v7/checkbox/label-placement/index.md';

<LabelPlacement />

## Alignment

Developers can use the `alignment` property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox `align-items` property.

:::note
Stacked checkboxes can be aligned using the `alignment` property. This can be useful when the label and control need to be centered horizontally.
:::

import Alignment from '@site/static/usage/v7/checkbox/alignment/index.md';

<Alignment />

## Justification

Developers can use the `justify` property to control how the label and control are packed on a line.
Developers can use the `justify` property to control how the label and control are packed on a line. This property mirrors the flexbox `justify-content` property.

import Justify from '@site/static/usage/v7/checkbox/justify/index.md';

Expand Down
23 changes: 19 additions & 4 deletions docs/api/datetime.md
Original file line number Diff line number Diff line change
Expand Up @@ -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';

<head>
Expand All @@ -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
Expand Down Expand Up @@ -98,13 +99,17 @@ While seconds, milliseconds, and time zone can be specified using the ISO 8601 d

If you need to present a datetime in an overlay such as a modal or a popover, we recommend using [ion-datetime-button](./datetime-button). `ion-datetime-button` should be used when space is constrained. This component displays buttons which show the current date and time values. When the buttons are tapped, the date or time pickers open in the overlay.

## 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 asynchronous process, it is recommended to hide the datetime with CSS until the value has finished updating.

## Date Constraints

### Max and Min Dates

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.

<MaxMin />

Expand All @@ -118,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`.
Expand Down Expand Up @@ -321,6 +326,16 @@ The benefit of this approach is that every component, not just `ion-datetime`, c

<GlobalTheming />

### Calendar Days

The calendar days in a grid-style `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.
:::

<CalendarDaysStyling />

### 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.
Expand Down Expand Up @@ -363,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';
Expand Down
17 changes: 14 additions & 3 deletions docs/api/radio.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,21 +30,32 @@ import Basic from '@site/static/usage/v7/radio/basic/index.md';

## Label Placement

Developers can use the `labelPlacement` property to control how the label is placed relative to the control.
Developers can use the `labelPlacement` property to control how the label is placed relative to the control. This property mirrors the flexbox `flex-direction` property.

import LabelPlacement from '@site/static/usage/v7/radio/label-placement/index.md';

<LabelPlacement />

## Alignment

Developers can use the `alignment` property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox `align-items` property.

:::note
Stacked radios can be aligned using the `alignment` property. This can be useful when the label and control need to be centered horizontally.
:::

import Alignment from '@site/static/usage/v7/radio/alignment/index.md';

<Alignment />

## Justification

Developers can use the `justify` property to control how the label and control are packed on a line.
Developers can use the `justify` property to control how the label and control are packed on a line. This property mirrors the flexbox `justify-content` property.

import Justify from '@site/static/usage/v7/radio/justify/index.md';

<Justify />


:::note
`ion-item` is only used in the demos to emphasize how `justify` works. It is not needed in order for `justify` to function correctly.
:::
Expand Down
12 changes: 11 additions & 1 deletion docs/api/toggle.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,17 @@ import LabelPlacement from '@site/static/usage/v7/toggle/label-placement/index.m

<LabelPlacement />

## Alignment

Developers can use the `alignment` property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox `align-items` property.

:::note
Stacked toggles can be aligned using the `alignment` property. This can be useful when the label and control need to be centered horizontally.
:::

import Alignment from '@site/static/usage/v7/toggle/alignment/index.md';

<Alignment />

## Justification

Expand All @@ -62,7 +73,6 @@ import Justify from '@site/static/usage/v7/toggle/justify/index.md';

<Justify />


## Theming

### Colors
Expand Down
11 changes: 11 additions & 0 deletions static/usage/v7/checkbox/alignment/angular.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
```html
<ion-list>
<ion-item>
<ion-checkbox label-placement="stacked" alignment="start">Aligned to the Start</ion-checkbox>
</ion-item>

<ion-item>
<ion-checkbox label-placement="stacked" alignment="center">Aligned to the Center</ion-checkbox>
</ion-item>
</ion-list>
```
29 changes: 29 additions & 0 deletions static/usage/v7/checkbox/alignment/demo.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Checkbox</title>
<link rel="stylesheet" href="../../../common.css" />
<script src="../../../common.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@7/dist/ionic/ionic.esm.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7/css/ionic.bundle.css" />
</head>
<body>
<ion-app>
<ion-content>
<div class="container">
<ion-list>
<ion-item>
<ion-checkbox label-placement="stacked" alignment="start">Aligned to the Start</ion-checkbox>
</ion-item>

<ion-item>
<ion-checkbox label-placement="stacked" alignment="center">Aligned to the Center</ion-checkbox>
</ion-item>
</ion-list>
</div>
</ion-content>
</ion-app>
</body>
</html>
17 changes: 17 additions & 0 deletions static/usage/v7/checkbox/alignment/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
import Playground from '@site/src/components/global/Playground';

import javascript from './javascript.md';
import react from './react.md';
import vue from './vue.md';
import angular from './angular.md';

<Playground
version="7"
code={{
javascript,
react,
vue,
angular,
}}
src="usage/v7/checkbox/alignment/demo.html"
/>
11 changes: 11 additions & 0 deletions static/usage/v7/checkbox/alignment/javascript.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
```html
<ion-list>
<ion-item>
<ion-checkbox label-placement="stacked" alignment="start">Aligned to the Start</ion-checkbox>
</ion-item>

<ion-item>
<ion-checkbox label-placement="stacked" alignment="center">Aligned to the Center</ion-checkbox>
</ion-item>
</ion-list>
```
25 changes: 25 additions & 0 deletions static/usage/v7/checkbox/alignment/react.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
```tsx
import React from 'react';
import { IonCheckbox, IonItem, IonList } from '@ionic/react';

function Example() {
return (
<>
<IonList>
<IonItem>
<IonCheckbox labelPlacement="stacked" alignment="start">
Aligned to the Start
</IonCheckbox>
</IonItem>

<IonItem>
<IonCheckbox labelPlacement="stacked" alignment="center">
Aligned to the Center
</IonCheckbox>
</IonItem>
</IonList>
</>
);
}
export default Example;
```
24 changes: 24 additions & 0 deletions static/usage/v7/checkbox/alignment/vue.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
```html
<template>
<ion-list>
<ion-item>
<ion-checkbox label-placement="stacked" alignment="start">Aligned to the Start</ion-checkbox>
</ion-item>

<ion-item>
<ion-checkbox label-placement="stacked" alignment="center">Aligned to the Center</ion-checkbox>
</ion-item>
</ion-list>
</template>

<script lang="ts">
import { IonCheckbox } from '@ionic/vue';
import { defineComponent } from 'vue';

export default defineComponent({
components: {
IonCheckbox,
},
});
</script>
```
4 changes: 4 additions & 0 deletions static/usage/v7/checkbox/label-placement/angular.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,8 @@
<br />

<ion-checkbox labelPlacement="fixed">Fixed Width Label</ion-checkbox>

<br />

<ion-checkbox labelPlacement="stacked">Stacked Label</ion-checkbox>
```
4 changes: 4 additions & 0 deletions static/usage/v7/checkbox/label-placement/demo.html
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@
<br />

<ion-checkbox label-placement="fixed">Fixed Width Label</ion-checkbox>

<br />

<ion-checkbox label-placement="stacked">Stacked Label</ion-checkbox>
</div>
</div>
</ion-content>
Expand Down
4 changes: 4 additions & 0 deletions static/usage/v7/checkbox/label-placement/javascript.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,8 @@
<br />

<ion-checkbox label-placement="fixed">Fixed Width Label</ion-checkbox>

<br />

<ion-checkbox label-placement="stacked">Stacked Label</ion-checkbox>
```
4 changes: 4 additions & 0 deletions static/usage/v7/checkbox/label-placement/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ function Example() {
<br />

<IonCheckbox labelPlacement="fixed">Fixed Width Label</IonCheckbox>

<br />

<IonCheckbox labelPlacement="stacked">Stacked Label</IonCheckbox>
</>
);
}
Expand Down
4 changes: 4 additions & 0 deletions static/usage/v7/checkbox/label-placement/vue.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@
<br />

<ion-checkbox label-placement="fixed">Fixed Width Label</ion-checkbox>

<br />

<ion-checkbox label-placement="stacked">Stacked Label</ion-checkbox>
</template>

<script lang="ts">
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
```css
/*
* Custom Datetime Day Parts
* -------------------------------------------
*/

ion-datetime::part(calendar-day) {
color: #da5296;
}

ion-datetime::part(calendar-day today) {
color: #8462d1;
}

ion-datetime::part(calendar-day):focus {
background-color: rgb(154 209 98 / 0.2);
box-shadow: 0px 0px 0px 4px rgb(154 209 98 / 0.2);
}

/*
* Custom Material Design Datetime Day Parts
* -------------------------------------------
*/

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 active),
ion-datetime.ios::part(calendar-day active):focus {
background-color: rgb(154 209 98 / 0.2);
color: #9ad162;
}
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
```html
<ion-datetime presentation="date" [(ngModel)]="datetime"></ion-datetime>
```
Loading