javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2026-03-13 10:22:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: sync with main

Browse Source
This commit is contained in:
Liam DeBeasi
2024-03-19 14:24:51 -04:00
parent acc1042124 58d217d0cf
commit e8f63560eb
75 changed files with 1065 additions and 645 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
.github/COMPONENT-GUIDE.md vendored
View File

@@ -2,10 +2,10 @@
- [Button States](#button-states)
* [Component Structure](#component-structure)
* [Activated](#activated)
* [Disabled](#disabled)
* [Focused](#focused)
* [Hover](#hover)
* [Activated](#activated)
* [Ripple Effect](#ripple-effect)
* [Example Components](#example-components)
* [References](#references)
@@ -21,7 +21,7 @@
## Button States
Any component that renders a button should have the following states: [`activated`](#activated), [`disabled`](#disabled), [`focused`](#focused), [`hover`](#hover). It should also have a [Ripple Effect](#ripple-effect) component added for Material Design.
Any component that renders a button should have the following states: [`disabled`](#disabled), [`focused`](#focused), [`hover`](#hover), [`activated`](#activated). It should also have a [Ripple Effect](#ripple-effect) component added for Material Design.
### Component Structure
@@ -89,78 +89,6 @@ The following styles should be set for the CSS to work properly. Note that the `
```
### Activated
The activated state should be enabled for elements with actions on "press". It usually changes the opacity or background of an element.
> [!WARNING]
>`:active` should not be used here as it is not received on mobile Safari unless the element has a `touchstart` listener (which we don't necessarily want to have to add to every element). From [Safari Web Content Guide](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/AdjustingtheTextSize/AdjustingtheTextSize.html):
>
>> On iOS, mouse events are sent so quickly that the down or active state is never received. Therefore, the `:active` pseudo state is triggered only when there is a touch event set on the HTML element
> Make sure the component has the correct [component structure](#component-structure) before continuing.
#### JavaScript
The `ion-activatable` class needs to be set on an element that can be activated:
```jsx
render() {
return (
<Host class='ion-activatable'>
<slot></slot>
</Host>
);
}
```
Once that is done, the element will get the `ion-activated` class added on press after a small delay. This delay exists so that the active state does not show up when an activatable element is tapped while scrolling.
In addition to setting that class, `ion-activatable-instant` can be set in order to have an instant press with no delay:
```jsx
<Host class='ion-activatable ion-activatable-instant'>
```
#### CSS
```css
/**
* @prop --color-activated: Color of the button when pressed
* @prop --background-activated: Background of the button when pressed
* @prop --background-activated-opacity: Opacity of the background when pressed
*/
```
Style the `ion-activated` class based on the spec for that element:
```scss
:host(.ion-activated) .button-native {
color: var(--color-activated);
&::after {
background: var(--background-activated);
opacity: var(--background-activated-opacity);
}
}
```
> Order is important! Activated should be after the focused & hover states.
#### User Customization
Setting the activated state on the `::after` pseudo-element allows the user to customize the activated state without knowing what the default opacity is set at. A user can customize in the following ways to have a solid red background on press, or they can leave out `--background-activated-opacity` and the button will use the default activated opacity to match the spec.
```css
ion-button {
--background-activated: red;
--background-activated-opacity: 1;
}
```
### Disabled
The disabled state should be set via prop on all components that render a native button. Setting a disabled state will change the opacity or color of the button and remove click events from firing.
@@ -197,7 +125,8 @@ render() {
}
```
> Note: if the class being added was for `ion-back-button` it would be `back-button-disabled`.
> [!NOTE]
> If the class being added was for `ion-back-button` it would be `back-button-disabled`.
#### CSS
@@ -215,9 +144,10 @@ The following CSS _at the bare minimum_ should be added for the disabled class,
TODO
### Focused
The focused state should be enabled for elements with actions when tabbed to via the keyboard. This will only work inside of an `ion-app`. It usually changes the opacity or background of an element.
The focused state should be enabled for elements with actions when tabbed to via the keyboard. This will only work inside of an `ion-app`. It usually changes the opacity or background of an element.
> [!WARNING]
> Do not use `:focus` because that will cause the focus to apply even when an element is tapped (because the element is now focused). Instead, we only want the focus state to be shown when it makes sense which is what the `.ion-focusable` utility mentioned below does.
@@ -225,6 +155,7 @@ The focused state should be enabled for elements with actions when tabbed to via
> [!NOTE]
> The [`:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible) pseudo-class mostly does the same thing as our JavaScript-driven utility. However, it does not work well with Shadow DOM components as the element that receives focus is typically inside of the Shadow DOM, but we usually want to set the `:focus-visible` state on the host so we can style other parts of the component. Using other combinations such as `:has(:focus-visible)` does not work because `:has` does not pierce the Shadow DOM (as that would leak implementation details about the Shadow DOM contents). `:focus-within` does work with the Shadow DOM, but that has the same problem as `:focus` that was mentioned before. Unfortunately, a [`:focus-visible-within` pseudo-class does not exist yet](https://github.com/WICG/focus-visible/issues/151).
> [!IMPORTANT]
> Make sure the component has the correct [component structure](#component-structure) before continuing.
#### JavaScript
@@ -234,7 +165,7 @@ The `ion-focusable` class needs to be set on an element that can be focused:
```jsx
render() {
return (
<Host class='ion-focusable'>
<Host class="ion-focusable">
<slot></slot>
</Host>
);
@@ -269,7 +200,8 @@ Style the `ion-focused` class based on the spec for that element:
}
```
> Order is important! Focused should be after the activated and before the hover state.
> [!IMPORTANT]
> Order matters! Focused should be **before** the activated and hover states.
#### User Customization
@@ -286,11 +218,12 @@ ion-button {
### Hover
The [hover state](https://developer.mozilla.org/en-US/docs/Web/CSS/:hover) happens when a user moves their cursor on top of an element without pressing on it. It should not happen on mobile, only on desktop devices that support hover.
The [hover state](https://developer.mozilla.org/en-US/docs/Web/CSS/:hover) happens when a user moves their cursor on top of an element without pressing on it. It should not happen on mobile, only on desktop devices that support hover.
> [!NOTE]
> Some Android devices [incorrectly report their inputs](https://issues.chromium.org/issues/40855702) which can result in certain devices receiving hover events when they should not.
> [!IMPORTANT]
> Make sure the component has the correct [component structure](#component-structure) before continuing.
#### CSS
@@ -321,7 +254,8 @@ Style the `:hover` based on the spec for that element:
}
```
> Order is important! Hover should be before the activated state.
> [!IMPORTANT]
> Order matters! Hover should be **before** the activated state.
#### User Customization
@@ -336,6 +270,79 @@ ion-button {
```
### Activated
The activated state should be enabled for elements with actions on "press". It usually changes the opacity or background of an element.
> [!WARNING]
>`:active` should not be used here as it is not received on mobile Safari unless the element has a `touchstart` listener (which we don't necessarily want to have to add to every element). From [Safari Web Content Guide](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/AdjustingtheTextSize/AdjustingtheTextSize.html):
>
>> On iOS, mouse events are sent so quickly that the down or active state is never received. Therefore, the `:active` pseudo state is triggered only when there is a touch event set on the HTML element
> [!IMPORTANT]
> Make sure the component has the correct [component structure](#component-structure) before continuing.
#### JavaScript
The `ion-activatable` class needs to be set on an element that can be activated:
```jsx
render() {
return (
<Host class="ion-activatable">
<slot></slot>
</Host>
);
}
```
Once that is done, the element will get the `ion-activated` class added on press after a small delay. This delay exists so that the active state does not show up when an activatable element is tapped while scrolling.
In addition to setting that class, `ion-activatable-instant` can be set in order to have an instant press with no delay:
```jsx
<Host class="ion-activatable ion-activatable-instant">
```
#### CSS
```css
/**
* @prop --color-activated: Color of the button when pressed
* @prop --background-activated: Background of the button when pressed
* @prop --background-activated-opacity: Opacity of the background when pressed
*/
```
Style the `ion-activated` class based on the spec for that element:
```scss
:host(.ion-activated) .button-native {
color: var(--color-activated);
&::after {
background: var(--background-activated);
opacity: var(--background-activated-opacity);
}
}
```
> [!IMPORTANT]
> Order matters! Activated should be **after** the focused & hover states.
#### User Customization
Setting the activated state on the `::after` pseudo-element allows the user to customize the activated state without knowing what the default opacity is set at. A user can customize in the following ways to have a solid red background on press, or they can leave out `--background-activated-opacity` and the button will use the default activated opacity to match the spec.
```css
ion-button {
--background-activated: red;
--background-activated-opacity: 1;
}
```
### Ripple Effect
The ripple effect should be added to elements for Material Design. It *requires* the `ion-activatable` class to be set on the parent element to work, and relative positioning on the parent.

28
.github/workflows/actions/test-core-screenshot/action.yml vendored
View File

@@ -21,33 +21,13 @@ runs:
name: ionic-core
path: ./core
filename: CoreBuild.zip
- name: Install Playwright Dependencies
run: npm install && npx playwright install && npx playwright install-deps
- name: Install Dependencies
run: npm install
shell: bash
working-directory: ./core
- id: clean-component-name
name: Clean Component Name
# Remove `ion-` prefix from the `component` variable if it exists.
run: |
echo "component=$(echo ${{ inputs.component }} | sed 's/ion-//g')" >> $GITHUB_OUTPUT
shell: bash
- id: set-test-file
name: Set Test File
# Screenshots can be updated for all components or specified component(s).
# If the `component` variable is set, then the test has the option to
# - run all the file paths that are in a component folder.
# -- For example: if the `component` value is "item", then the test will run all the file paths that are in the "src/components/item" folder.
# -- For example: if the `component` value is "item chip", then the test will run all the file paths that are in the "src/components/item" and "src/components/chip" folders.
run: |
if [ -n "${{ steps.clean-component-name.outputs.component }}" ]; then
echo "testFile=\$(echo '${{ steps.clean-component-name.outputs.component }}' | awk '{for(i=1;i<=NF;i++) \$i=\"src/components/\"\$i}1')" >> $GITHUB_OUTPUT
else
echo "testFile=$(echo '')" >> $GITHUB_OUTPUT
fi
shell: bash
- name: Test
if: inputs.update != 'true'
run: npm run test.e2e ${{ steps.set-test-file.outputs.testFile }} -- --shard=${{ inputs.shard }}/${{ inputs.totalShards }}
run: npm run test.e2e.docker.ci ${{ inputs.component }} -- --shard=${{ inputs.shard }}/${{ inputs.totalShards }}
shell: bash
working-directory: ./core
- name: Test and Update
@@ -69,7 +49,7 @@ runs:
# which is why we not using the upload-archive
# composite step here.
run: |
npm run test.e2e ${{ steps.set-test-file.outputs.testFile }} -- --shard=${{ inputs.shard }}/${{ inputs.totalShards }} --update-snapshots
npm run test.e2e.docker.ci ${{ inputs.component }} -- --shard=${{ inputs.shard }}/${{ inputs.totalShards }} --update-snapshots
git add src/\*.png --force
mkdir updated-screenshots
cd ../ && rsync -R --progress $(git diff --name-only --cached) core/updated-screenshots

11
.github/workflows/actions/update-reference-screenshots/action.yml vendored
View File

@@ -25,12 +25,9 @@ runs:
# Configure user as Ionitron
# and push only the changed .png snapshots
# to the remote branch.
# Screenshots are in .gitignore
# Non-Linux screenshots are in .gitignore
# to prevent local screenshots from getting
# pushed to Git. As a result, we need --force
# here so that CI generated screenshots can
# get added to git. Screenshot ground truths
# should only be added via this CI process.
# pushed to Git.
run: |
git config user.name ionitron
git config user.email hi@ionicframework.com
@@ -38,7 +35,7 @@ runs:
# This adds an empty entry for new
# screenshot files so we can track them with
# git diff
git add src/\*.png --force -N
git add src/\*.png -N
if git diff --exit-code; then
echo -e "\033[1;31m⚠️ Error: No new screenshots generated ⚠️\033[0m"
@@ -48,7 +45,7 @@ runs:
else
# This actually adds the contents
# of the screenshots (including new ones)
git add src/\*.png --force
git add src/\*.png
git commit -m "chore(): add updated snapshots"
git push
fi

14
.github/workflows/update-screenshots.yml vendored
View File

@@ -3,6 +3,20 @@ name: 'Update Reference Screenshots'
on:
workflow_dispatch:
inputs:
# Screenshots can be updated for all components or specified component(s).
# If the `component` variable is set, then the test has the option to
# - run all the instances of the specified component(s) in the `src/components` folder
# -- For example: if the `component` value is "item", then the following command will be: `npm run test.e2e item`
# - run the specified file path
# -- For example: if the `component` value is "src/components/item/test/basic", then the following command will be: `npm run test.e2e src/components/item/test/basic`
# - run multiple specified components based on the space-separated value
# -- For example: if the `component` value is "item basic", then the following command will be: `npm run test.e2e item basic`
# -- For example: if the `component` value is "src/components/item/test/basic src/components/item/test/a11y", then the following command will be: `npm run test.e2e src/components/item/test/basic src/components/item/test/a11y`
#
# If the `component` variable is not set, then the test will run all the instances of the components in the `src/components` folder.
# - For example: `npm run test.e2e`
#
# More common options can be found at the Playwright Command line page: https://playwright.dev/docs/test-cli
component:
description: 'What component(s) should be updated? (leave blank to update all or use a space-separated list for multiple components)'
required: false