Start your review here 👉
[docs/README.md](https://github.com/ionic-team/ionic-framework/blob/FW-6107/docs/README.md)
## What is the current behavior?
Documentation files with information on how to contribute, component
implementations, testing, etc. are scattered throughout various folders
in this repository.
## What is the new behavior?
Consolidates the documentation files into a root `docs/` directory for
easier discovery and organization.
`/docs` tree:
```
├── _config.yml
├── component-guide.md
├── CONTRIBUTING.md
├── README.md
├── sass-guidelines.md
├── angular
│ ├── README.md
│ └── testing.md
├── core
│ ├── README.md
│ └── testing
│ ├── README.md
│ ├── api.md
│ ├── best-practices.md
│ ├── preview-changes.md
│ └── usage-instructions.md
├── react
│ ├── README.md
│ └── testing.md
├── react-router
│ ├── README.md
│ └── testing.md
├── vue
│ ├── README.md
│ └── testing.md
└── vue-router
├── README.md
└── testing.md
```
**Migrates the following:**
| Previous Location | New Location |
| ----------------------------------------------------------- |
----------------------------------------- |
| `.github/COMPONENT-GUIDE.md` | `docs/component-guide.md` |
| `.github/CONTRIBUTING.md` | `docs/CONTRIBUTING.md` |
| `core/scripts/README.md` | `docs/core/testing/preview-changes.md` |
| `core/src/utils/test/playwright/docs/api.md` |
`docs/core/testing/api.md` |
| `core/src/utils/test/playwright/docs/best-practices.md` |
`docs/core/testing/best-practices.md` |
| `core/src/utils/test/playwright/docs/README.md` |
`docs/core/testing/README.md` |
| `core/src/utils/test/playwright/docs/usage-instructions.md` |
`docs/core/testing/usage-instructions.md` |
| `packages/angular/test/README.md` | `docs/angular/testing.md` |
| `packages/react-router/test/README.md` |
`docs/react-router/testing.md` |
| `packages/react/test/README.md` | `docs/react/testing.md` |
| `packages/react/test/base/README.md` | `docs/react/testing.md` |
| `packages/vue/test/README.md` | `docs/vue/testing.md` |
**Adds the following:**
| File | Description |
| ----------------------------- |
-----------------------------------------------------------------------
|
| `docs/sass-guidelines.md` | Sass Variable guidelines taken from
`ionic-framework-design-documents` |
| `docs/README.md` | Entry file that should link to all other files |
| `docs/_config.yml` | Config file for use with GitHub pages |
| `docs/core/README.md` | Description of core, links to contributing and
testing |
| `docs/angular/README.md` | Description of angular, links to
contributing and testing |
| `docs/react/README.md` | Description of react, links to contributing
and testing |
| `docs/react-router/README.md` | Description of react-router, links to
contributing and testing |
| `docs/vue/README.md` | Description of vue, links to contributing and
testing |
| `docs/vue-router/README.md` | Description of vue-router, links to
contributing and testing |
| `docs/vue-router/testing.md` | Testing file for vue-router, populated
from vue-router's main README |
**Does not** add any files for `angular-server`. This is because the
README is essentially empty and there is no testing in that directory. I
can add blank files if we want to have something to add to later.
**Does not** migrate the content of the packages' root `README.md`
files. These files are used for their npm package descriptions so we
should not edit them.
## Hosting Documentation
We can (and should) host these files using GitHub Pages. I have
duplicated them in a personal repository to see how this would look:
[docs-consolidation](https://brandyscarney.github.io/docs-consolidation/).
Doing so will require some formatting fixes (see [Sass
Guidelines](https://brandyscarney.github.io/docs-consolidation/sass-guidelines.html#-reusable-values))
so I did not publish them now but we can easily enable GitHub pages by
toggling a setting in this repository.
## Other information
- Verify that no documentation files were missed in the migration
- You can use these commands to search for `*.md` files in a directory:
- `find core/src -type f -name "*.md" -print`
- `find packages/angular -type f -name "*.md" -not -path
"**/node_modules/*" -print`
- I did add some redirect links in some of the existing markdown files
so they might still exist for that reason
- We should probably break up the contributing + component guide
documentation into smaller files, such as including best practices, but
I wanted to get everything in the same place first
- The contributing has sections on each of the packages that we could
move to that package's docs folder:
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#core
---------
Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>
Issue number: N/A
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
Ionic Framework developers make extensive use of multi-line comments in
the Sass files. However these comments are not stripped from the
generated output.
This leads to a significant increase to the file size of CSS and can
have an impact on runtime performance.
For example: https://cdn.jsdelivr.net/npm/@ionic/core/css/core.css has
183 lines of comment blocks before a single line of CSS.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- Compresses the generated output from Sass → CSS to strip out
multi-line comment blocks.
- Developers can use [loud
comments](https://sass-lang.com/documentation/syntax/comments/) if they
want to include comments in the generated output.
- In the case of just the core.css file, the file size goes from 20kb to
10kb.
- The entire CSS global styles goes from 758 KB to 606kb.
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
Dev-build: `7.8.4-dev.11712251308.1da8aede`
Issue number: N/A
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
Developers on a Windows environment using VS Code will experience an
issue when using prettier, where files will be tracked as modified even
though they have no actual diffs.
This is due to differences in how Unix based operating systems and
Windows treat carriage returns.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- Updates the contributing guide to educate developers using VS Code on
how to configure their local environment to not track additional diffs
when formatting the codebase.
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
This is the same documentation that exists on the ionic-docs repository
for the same reason. I've applied co-authored-by credit to Netkow for
his wonderful contribution to that documentation.
Co-authored-by: Matt Netkow <matt.netkow@gmail.com>
Move the `docs/` directory into the `packages/` directory. This will
enable us to create a top level `docs/` folder for onboarding and
contributing guidelines. It will also be necessary when migrating to
pnpm.
---------
Co-authored-by: Liam DeBeasi <liamdebeasi@users.noreply.github.com>
Issue number: N/A
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
When using an outline-style button in a toolbar on `md` dark mode, the
activated style causes the button to become invisible.
Steps to repro in `main`:
1. Update the `css-variables` themes test to use the latest dark theme
styles (at least for v7) by replacing the contents of [this
file](https://github.com/ionic-team/ionic-framework/blob/main/core/src/themes/test/css-variables/css/dark.css)
with the [styles from the
docs](https://ionicframework.com/docs/theming/dark-mode#ionic-dark-theme).
2. Host the project locally and navigate to the test at
`themes/test/css-variables/index.html`.
3. Switch to dark mode within the page. Note that the activated outline
button isn't visible:
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- Button styles corrected. The colors were correct for `ios` mode, but
had to be flipped for `md`, so I pulled the relevant styles into the
mode-specific stylesheets.
- CSS variables test has also been updated to use the same dark mode CSS
as in [the
docs](https://ionicframework.com/docs/theming/dark-mode#ionic-dark-theme),
as per the repro steps above. Let me know if you would rather this be
split into a separate PR.
Changes to the toolbar test were split into a separate PR to keep this
one clean and ensure the screenshot changes can be reviewed more
effectively: https://github.com/ionic-team/ionic-framework/pull/29231
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
5. Update the BREAKING.md file with the breaking change.
6. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
---------
Co-authored-by: ionitron <hi@ionicframework.com>
I'm removing myself from code owners in several places in favor of the
auto-assignment. However, I did keep my name on areas of the code that I
felt are still higher risk for potential regressions due to the nature
of how the code is built/tested.
Remove myself as the codeowner of specific directories as this bypasses
the random review assignment and automatically assigns me to any PRs
changing these files.
Issue number: resolves#29211
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
In https://github.com/ionic-team/ionic-framework/pull/28861 I fixed a
bug that caused `.popover-viewport` to have `overflow: hidden`. In
reality, this code should have always applied but due to an incorrect
selector it never did.
As it turns out in
https://github.com/ionic-team/ionic-framework/issues/29211, some
developers were relying on the broken behavior to build their
applications. In particular, developers were using `ion-popover` without
an `ion-content`. The linked change made it so that using popovers
without `ion-content` were not scrollable.
After talking with @mapsandapps we think it makes sense to officially
support this behavior. We support using [modals without
`ion-content`](https://ionicframework.com/docs/api/modal#custom-dialogs),
and we could not think of a reason to not support the same use case for
popover.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- If the `.popover-viewport` element has a child content then
`.popover-viewport `will not be scrollable.
- If the `.popover-viewport` element does not have a child content then
`.popover-viewport` will be scrollable.
I implemented this behavior using progressive enhancement via `:has`.
The [`:has` pseudo-class](https://caniuse.com/?search=%3Ahas) has
cross-browser support. Ionic v7 supports some versions of browsers that
do not have `:has` support. As a result, we fall back to the existing
behavior in this environment. Developers are able to get this behavior
on older browsers by explicitly setting `overflow: auto` on
`.popover-viewport`.
Fortunately, we will be dropping support for several of the older
browsers versions in Ionic v8, so the need to do the manual opt-in
should be less frequent as time goes on.
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
Dev build: `7.8.2-dev.11711383079.118d48a5`
Testing:
1. Open https://codepen.io/liamdebeasi/pen/JjVJrZQ?editors=1100 (this
has a dev build installed)
2. Click each button to open a popover.
3. Verify that each popover can be scrolled.
I could not find a great way to automate this test, but let me know if
anyone has ideas!
Issue number: N/A
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
The toolbar `basic` test only checks light theme. Dark theme coverage is
required to test against the bug fixed in
https://github.com/ionic-team/ionic-framework/pull/29216.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
Dark theme coverage added. This required converting the test to
`page.setContent` instead of `page.goto`, so I went ahead and split the
captured toolbars into multiple tests, including some cleanup of the
test content. Since this included changes across many different tests,
even ones not strictly related to the bug, this work has been split into
a separate PR.
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
---------
Co-authored-by: ionitron <hi@ionicframework.com>
Issue number: Internal
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
When given a password input it is hard to know what users are typing as
the contents of the input are obscured. As a result, it is a common
pattern to have a button that lets users temporarily toggle the
visibility of the password so they can correct any mistakes. Ionic
currently has the infrastructure for developers to implement this on
their own, but this use case is so common that the team thinks it is
worth having this functionality built-in to Ionic.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- Introduces the `ion-input-password-toggle` component. This component
is a button that toggles the visibility of the text in the input it is
slotted into.
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
⚠️ Give co-author credit to
https://github.com/ionic-team/ionic-framework/pull/29141 on merge.
Docs PR: https://github.com/ionic-team/ionic-docs/pull/3541
Note: We did not do the approach listed in the other PR due to
https://github.com/ionic-team/ionic-framework/pull/29141#discussion_r1523631811.
---------
Co-authored-by: OS-giulianasilva <OS-giulianasilva@users.noreply.github.com>
Issue number: Internal
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
[Amanda pointed out that the ripple effect for the Button inside of
InputPasswordToggle was not
working](https://github.com/ionic-team/ionic-framework/pull/29175#discussion_r1532627841).
I found out that calling `ev.preventDefault` on `pointerdown` causes
`mouseup` to not get fired. On desktop, we rely on `mouseup` to know
when to add the ripple effect. (`touchend` is not impacted)
Interestingly, calling `ev.preventDefault` on `pointerdown` does **not**
prevent `pointerup` from being fired. The idea here is that if we
migrate the tap click utility to use the PointerEvents API instead of
separate mouse/touch listeners we can keep the existing tap click
behavior while also fixing the bug that Amanda noted.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- Tap click nows listens for the Pointer Events instead of separate
mouse/touch events
Impact to developers is fairly minimal. There should be no behavior
change (other than the bug I noted being fixed). There should be a very
small perf boost because this util now only adds 4 event listeners on
the document instead of 7 previously.
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
Reviewers: Please manually test this on desktop devices as well as iOS
and Android devices (not Chrome Dev Tools. iOS simulators are fine).
Test that components such as `ion-button` correctly add the activated
state (or ripple effect for MD). Also verify that the activated state is
not added when tapping the button and then scrolling. For desktop, check
that right clicking does not add the activated state.
Issue number: resolves#29193
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
In an attempt to preserve backwards compatibility when adding
`autocapitalize` to Searchbar, we used `!` to indicate that the prop was
never undefined. The `autocapitalize` on `HTMLElement` expects this
value to be a string and never undefined.
For the purposes of the property on Searchbar, setting this prop to one
of the accepted values would constitute a breaking change because it
would override the default browser behavior (which we previously relied
upon). As a result, we used `!` to not set a default prop but inform
TypeScript that this prop is always defined. This unintentionally made
it so developers needed to define the `autocapitalize` property every
time which is not what we want.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- `autocapitalize` now defaults to the `'default'` keyword. This is an
internal keyword that is used to tell Ionic to **not** set the
`autocapitalize` attribute on the inner `input` element and instead rely
on the default browser behavior. This satisfies the `HTMLElement`
requirement that `autocapitalize` is never undefined. In Ionic 8 this
`'default'` value will be replaced with `'off'`.
[Typescript currently sets the `HTMLElement` `autocapitalize` type to
`string`](65812bf3ec/src/lib/dom.generated.d.ts (L10087))
which is why we can add a `'default'` keyword here. There is some risk
that if these type definitions change in the future that applications
may encounter errors. However, changing this on the TypeScript side
would itself be a breaking change. Additionally, we are moving away from
`'default'` in Ionic 8, so I think this is an acceptable amount of risk.
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
Dev build: `7.8.2-dev.11711027016.13b2a920`
Tested in a React starter app with Searchbar, and I verified this fix
works.
BREAKING CHANGE: Support for the Cordova Haptics plugin has been removed. Components that integrate with haptics, such as `ion-picker` and `ion-toggle`, will continue to function but will no longer play haptics in Cordova environments. Developers should migrate to Capacitor to continue to have haptics in these components.
Issue number: Internal
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
While doing other work I noticed that the Angular schematics still
reference the old dark theme.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- The Angular schematics now import the new dark theme found in Ionic
v8.
## Does this introduce a breaking change?
- [ ] Yes
- [x] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
Issue number: Internal
---------
<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->
<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->
## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->
Ionic Framework provides a small utility wrapper around the Web
Animations API. Historically not all browsers that Ionic Framework
supported, had support for the Web Animations API. To offer backwards
compatibility, Ionic Framework provided fallback behaviors for the
different wrapped APIs.
## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->
- Removes the legacy CSS animations fallback behavior from the Web
Animations API animation utility. Maintaining a few no-op behaviors for
test environments.
- Resolved a few internal type usages that were casting to any
- Removed spec tests that were testing the fallback CSS animations
behavior and/or already had test coverage from other unit tests.
## Does this introduce a breaking change?
- [x] Yes
- [ ] No
<!--
If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->
All modern browsers support the Web Animations API today. If a developer
needs to target an older browser that does not support Web Animations,
they should either use [a
polyfill](https://github.com/web-animations/web-animations-js), or
implement the fallback behavior themselves.
## Other information
<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->
---------
Co-authored-by: Liam DeBeasi <liamdebeasi@users.noreply.github.com>
