From e2f32db24297e0236aa82ab274510ad51432b6aa Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Wed, 3 Apr 2024 12:14:55 -0400 Subject: [PATCH 01/16] chore(docs): move contributing and component guide docs --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- README.md | 6 +++--- core/README.md | 4 ++-- {.github => docs}/COMPONENT-GUIDE.md | 0 {.github => docs}/CONTRIBUTING.md | 0 packages/vue-router/README.md | 4 ++-- packages/vue/README.md | 2 +- 7 files changed, 9 insertions(+), 9 deletions(-) rename {.github => docs}/COMPONENT-GUIDE.md (100%) rename {.github => docs}/CONTRIBUTING.md (100%) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c565dcac8c2..29910b7b2b2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -25,7 +25,7 @@ Issue number: resolves # 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. + 3. Add "BREAKING CHANGE: [...]" to the commit description when merging. See https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer for more information. --> diff --git a/README.md b/README.md index 3ca6f6ca97a..091377a155f 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Ionic Framework is released under the MIT license. - + PRs welcome! @@ -38,7 +38,7 @@ Documentation ยท - Contribute + Contribute ยท Blog
@@ -88,7 +88,7 @@ The Ionic Conference App is a full featured Ionic app. It is the perfect startin ### Contributing Thanks for your interest in contributing! Read up on our guidelines for -[contributing](https://github.com/ionic-team/ionic/blob/main/.github/CONTRIBUTING.md) +[contributing](https://github.com/ionic-team/ionic/blob/main/docs/CONTRIBUTING.md) and then look through our issues with a [help wanted](https://github.com/ionic-team/ionic/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) label. diff --git a/core/README.md b/core/README.md index 23dbfc1c2fe..3132e38c401 100644 --- a/core/README.md +++ b/core/README.md @@ -89,14 +89,14 @@ defineCustomElement(); const showModal = async () => { const modal = await modalController.create({ ... }); - + ... } ``` ## How to contribute -[Check out the CONTRIBUTE guide](/.github/CONTRIBUTING.md) +[Check out the CONTRIBUTE guide](/docs/CONTRIBUTING.md) ## Related diff --git a/.github/COMPONENT-GUIDE.md b/docs/COMPONENT-GUIDE.md similarity index 100% rename from .github/COMPONENT-GUIDE.md rename to docs/COMPONENT-GUIDE.md diff --git a/.github/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 100% rename from .github/CONTRIBUTING.md rename to docs/CONTRIBUTING.md diff --git a/packages/vue-router/README.md b/packages/vue-router/README.md index 83cc23717bb..6dcdd7d267b 100644 --- a/packages/vue-router/README.md +++ b/packages/vue-router/README.md @@ -24,8 +24,8 @@ npm run build ## Contributing -See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md). +See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md). ## Need Help? -Post your question on the [Ionic Forum](http://forum.ionicframework.com/). \ No newline at end of file +Post your question on the [Ionic Forum](http://forum.ionicframework.com/). diff --git a/packages/vue/README.md b/packages/vue/README.md index 2bd35bf6b0b..f1e964c6d78 100644 --- a/packages/vue/README.md +++ b/packages/vue/README.md @@ -50,7 +50,7 @@ npm run build ## Contributing -See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md). +See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md). ## Need Help? From 203686f9b95a01a3c85efaeb3355e92b4375ea0c Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Wed, 3 Apr 2024 16:36:18 -0400 Subject: [PATCH 02/16] docs: fix typo --- docs/COMPONENT-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/COMPONENT-GUIDE.md b/docs/COMPONENT-GUIDE.md index 24af57fdcea..4a52d047476 100644 --- a/docs/COMPONENT-GUIDE.md +++ b/docs/COMPONENT-GUIDE.md @@ -760,7 +760,7 @@ To work around this, you should set an RTL class on the host of your component a ... From f6338db03e660756506a36e544d58325e4b3d556 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Thu, 4 Apr 2024 15:27:08 -0400 Subject: [PATCH 03/16] chore(docs): consolidate markdown files for packages, scripts and testing to docs directory --- core/README.md | 112 +---- core/scripts/readme.md | 44 +- docs/CONTRIBUTING.md | 2 +- docs/README.md | 34 ++ docs/_config.yml | 2 + docs/angular/README.md | 74 ++++ docs/angular/testing.md | 118 +++++ docs/core/README.md | 113 +++++ docs/core/scripts.md | 46 ++ docs/react/README.md | 49 +++ docs/react/testing.md | 55 +++ docs/react/testing2.md | 47 ++ docs/sass-guidelines.md | 685 +++++++++++++++++++++++++++++ docs/vue/README.md | 57 +++ docs/vue/testing.md | 58 +++ packages/angular/README.md | 73 +-- packages/angular/test/README.md | 117 +---- packages/react/README.md | 50 +-- packages/react/test/README.md | 54 +-- packages/react/test/base/README.md | 46 +- packages/vue/README.md | 56 +-- packages/vue/test/README.md | 57 +-- 22 files changed, 1350 insertions(+), 599 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/_config.yml create mode 100644 docs/angular/README.md create mode 100644 docs/angular/testing.md create mode 100644 docs/core/README.md create mode 100644 docs/core/scripts.md create mode 100644 docs/react/README.md create mode 100644 docs/react/testing.md create mode 100644 docs/react/testing2.md create mode 100644 docs/sass-guidelines.md create mode 100644 docs/vue/README.md create mode 100644 docs/vue/testing.md diff --git a/core/README.md b/core/README.md index 3132e38c401..7dd2f861817 100644 --- a/core/README.md +++ b/core/README.md @@ -1,113 +1,3 @@ # @ionic/core -[Ionic](https://ionicframework.com/) is an open source App Development Framework that makes it easy to build top quality Native and Progressive Web Apps with web technologies. - -The Ionic Core package contains the Web Components that make up the reusable UI building blocks of Ionic Framework. These components are designed to be used in traditional frontend view libraries/frameworks (such as [Stencil](https://stenciljs.com/), React, Angular, or Vue), or on their own through traditional JavaScript in the browser. - - -## Features - -* Tiny, highly optimized components built with [Stencil](https://stenciljs.com/) -* Styling for both iOS and Material Design -* No build or compiling required -* Simply add the static files to any project -* Lazy-loaded components without configuration -* Asynchronous rendering -* Theming through CSS Variables - - -## How to use - -### Vanilla HTML - -Easiest way to start using Ionic Core is by adding a script tag to the CDN: - -```html - - - -``` - -Any Ionic component added to the webpage will automatically load. This includes writing the component tag directly in HTML, or using JavaScript such as `document.createElement('ion-toggle')`. - -Additionally, within this package is a `dist/ionic.js` file and accompanying `dist/ionic/` directory. These are the same files which are used by the CDN, and they're available in this package so they can be apart of an app's local development. - - -## Framework Bindings - -The `@ionic/core` package can be used in simple HTML, or by vanilla JavaScript without any framework at all. Ionic also has packages that make it easier to integrate Ionic into a framework's traditional ecosystem and patterns. (However, at the lowest-level framework bindings are still just using Ionic Core and Web Components). - -* [@ionic/angular](https://www.npmjs.com/package/@ionic/angular) - - -## Custom Elements Build - -In addition to the default, self lazy-loading components built by Stencil, this package also comes with each component exported as a stand-alone custom element within `@ionic/core/components`. Each component extends `HTMLElement`, and does not lazy-load itself. Instead, this package is useful for projects already using a bundler such as Webpack or Rollup. While all components are available to be imported, the custom elements build also ensures bundlers only import what's used, and tree-shakes any unused components. - -Below is an example of importing `ion-badge`, and initializing Ionic so it is able to correctly load the "mode", such as Material Design or iOS. Additionally, the `initialize({...})` function can receive the Ionic config. - -```typescript -import { defineCustomElement } from "@ionic/core/components/ion-badge.js"; -import { initialize } from "@ionic/core/components"; - -// Initializes the Ionic config and `mode` behavior -initialize(); - -// Defines the `ion-badge` web component -defineCustomElement(); -``` - -Notice how we import from `@ionic/core/components` as opposed to `@ionic/core`. This helps bundlers pull in only the code that is needed. - -The `defineCustomElement` function will automatically define the component as well as any child components that may be required. - -For example, if you wanted to use `ion-modal`, you would do the following: - -```typescript -import { defineCustomElement } from "@ionic/core/components/ion-modal.js"; -import { initialize } from "@ionic/core/components"; - -// Initializes the Ionic config and `mode` behavior -initialize(); - -// Defines the `ion-modal` and child `ion-backdrop` web components. -defineCustomElement(); -``` - -The `defineCustomElement` function will define `ion-modal`, but it will also define `ion-backdrop`, which is a component that `ion-modal` uses internally. - -### Using Overlay Controllers - -When using an overlay controller, developers will need to define the overlay component before it can be used. Below is an example of using `modalController`: - -```typescript -import { defineCustomElement } from '@ionic/core/components/ion-modal.js'; -import { initialize, modalController } from '@ionic/core/components'; - -initialize(); -defineCustomElement(); - -const showModal = async () => { - const modal = await modalController.create({ ... }); - - ... -} -``` - -## How to contribute - -[Check out the CONTRIBUTE guide](/docs/CONTRIBUTING.md) - -## Related - -* [Ionic Documentation](https://ionicframework.com/docs/) -* [Ionic Discord](https://ionic.link/discord) -* [Ionic Forum](https://forum.ionicframework.com/) -* [Ionicons](http://ionicons.com/) -* [Stencil](https://stenciljs.com/) -* [Capacitor](https://capacitor.ionicframework.com/) - - -## License - -* [MIT](https://raw.githubusercontent.com/ionic-team/ionic/master/LICENSE) +This file has been moved to [/docs/core/README.md](/docs/core/README.md). diff --git a/core/scripts/readme.md b/core/scripts/readme.md index 1611f4bccda..d1560e15422 100644 --- a/core/scripts/readme.md +++ b/core/scripts/readme.md @@ -1,44 +1,4 @@ -## Build +# Core Scripts -### 1. Clone ionic - - git@github.com:ionic-team/ionic.git - cd ionic - -### 2. Run `npm install` - - cd core - npm install - - -Notice that `@ionic/core` lives in `core`. - -### 3. Run `npm start` - -Make sure you are inside the `core` directory. - - npm start - -With the `dev` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and http://localhost:3333/ will open in a browser. - -### 4. Preview - -Navigate to http://localhost:3333/src/components/. Each component has small e2e apps found in the `test` directory, for example: http://localhost:3333/src/components/button/test/basic - -As changes are made in an editor to source files, the e2e app will live-reload. - -## How to contribute - -1. `npm start` allows you to modify the components and have live reloading, just like another ionic app. - -2. When everything looks good, run `npm run validate` to verify the tests linter and production build passes. - - -# Deploy - -1. `npm run prepare.deploy` -2. Review/update changelog -3. Commit updates using the package name and version number as the commit message. -4. `npm run deploy` -5. :tada: +This file has been moved to [/docs/core/scripts.md](/docs/core/scripts.md). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index e20ec3194f8..65225784b93 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -Thanks for your interest in contributing to the Ionic Framework! :tada: +Thanks for your interest in contributing to the Ionic Framework! ๐ŸŽ‰ - [Contributing Etiquette](#contributing-etiquette) - [Creating an Issue](#creating-an-issue) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..71d2d36df22 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,34 @@ +

+ + Ionic Logo + +

+ +

+ Ionic Framework Developer Resources +

+ +

+ This documentation includes guidelines on contributing, coding conventions, best practices, testing steps, and more. It should serve as a collective resource for all documentation related to developing Ionic Framework. +

+ +## What is Ionic Framework? + +Ionic Framework is an open source app development toolkit for building modern, fast, top-quality cross-platform native and Progressive Web Apps from a single codebase with JavaScript and the Web. + +It is based on Web Components, which enables significant performance, usability, and feature improvements alongside support for popular web frameworks like Angular, React, and Vue. + +## Guides + +- [Contributing](./CONTRIBUTING.md) +- [Component Guide](./component-guide.md) +- [Sass Guidelines](./sass-guidelines.md) + +## Packages + +| Project | Package | Documentation | Guides | +| ----------- | ---------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------- | +| **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Scripts](core/scripts.md) | +| **Angular** | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular) | [Readme](angular/README.md) | [Testing](angular/testing.md) | +| **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [Readme](vue/README.md) | [Testing](vue/testing.md) | +| **React** | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react) | [Readme](react/README.md) | [Testing](react/testing.md) โ€ข [Testing Part 2](react/testing2.md) | diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000000..78e6441ffb7 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,2 @@ +name: Ionic Framework +include: CONTRIBUTING.md diff --git a/docs/angular/README.md b/docs/angular/README.md new file mode 100644 index 00000000000..0a1b2c488d7 --- /dev/null +++ b/docs/angular/README.md @@ -0,0 +1,74 @@ +# @ionic/angular + +Ionic Angular specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components. + + +## Related + +* [Ionic Core Components](https://www.npmjs.com/package/@ionic/core) +* [Ionic Documentation](https://ionicframework.com/docs/) +* [Ionic Discord](https://ionic.link/discord) +* [Ionic Forum](https://forum.ionicframework.com/) +* [Ionicons](http://ionicons.com/) +* [Stencil](https://stenciljs.com/) +* [Capacitor](https://capacitor.ionicframework.com/) + + +## License + +* [MIT](https://raw.githubusercontent.com/ionic-team/ionic/main/LICENSE) + +## Testing ng-add in ionic + +1. Pull the latest from `main` +2. Build ionic/angular: `npm run build` +3. Run `npm link` from `ionic/angular/dist` directory +4. Create a blank angular project + +``` +ng new add-test +// Say yes to including the router, we need it +cd add-test +``` + +5. To run schematics locally, we need the schematics-cli (once published, this will not be needed) + +``` +npm install @angular-devkit/schematics-cli +``` + +6. Link `@ionic/angular` + +``` +npm link @ionic/angular +``` + + +7. Run the local copy of the ng-add schematic + +``` +$ npx schematics @ionic/angular:ng-add +``` + + +You'll now be able to add ionic components to a vanilla Angular app setup. + +## Project Structure + +**common** + +This is where logic that is shared between lazy loaded and standalone components live. For example, the lazy loaded IonPopover and standalone IonPopover components extend from a base IonPopover implementation that exists in this directory. + +**Note:** This directory exposes internal APIs and is only accessed in the `standalone` and `src` submodules. Ionic developers should never import directly from `@ionic/angular/common`. Instead, they should import from `@ionic/angular` or `@ionic/angular/standalone`. + +**standalone** + +This is where the standalone component implementations live. It was added as a separate entry point to avoid any lazy loaded logic from accidentally being pulled in to the final build. Having a separate directory allows the lazy loaded implementation to remain accessible from `@ionic/angular` for backwards compatibility. + +Ionic developers can access this by importing from `@ionic/angular/standalone`. + +**src** + +This is where the lazy loaded component implementations live. + +Ionic developers can access this by importing from `@ionic/angular`. diff --git a/docs/angular/testing.md b/docs/angular/testing.md new file mode 100644 index 00000000000..b2e56ef2ee4 --- /dev/null +++ b/docs/angular/testing.md @@ -0,0 +1,118 @@ +# Angular E2E Test Apps + +Ionic Framework supports multiple versions of Angular. As a result, we need to verify that Ionic works correctly with each of these Angular versions. + +## Syncing Local Changes + +The Angular test app supports syncing your locally built changes for validation. + +1. Build the `core` and `packages/angular` directories using `npm run build`. +2. [Build the Angular test app](#test-app-build-structure). +3. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng14`). +4. Install dependencies using `npm install`. +5. Sync your local changes using `npm run sync`. + +From here you can either build the application or start a local dev server. When re-syncing changes, you will need to [wipe or disable the application cache](#application-cache). + +## Application Cache + +Angular CLI creates a cache of several files on disk by default in the `.angular` directory. This decreases the time taken to build the test application. However, the cache makes it difficult to quickly sync and check local changes of Ionic. As a result, the `.angular` cache is disabled by default in the test app projects. + +See https://angular.io/cli/cache for more information. + +### Disable Cache + +```shell +ng cache disable +``` + +> [!NOTE] +> You may need to manually remove the `.angular` directory once after running this command. + +### Enable Cache + +```shell +ng cache enable +``` + +> [!NOTE] +> You will need to delete the `.angular` cache and restart the dev server every time you want to sync local changes of Ionic. + +## Test App Build Structure + +> [!NOTE] +> Please confirm your current directory as `packages/angular/test` before proceeding with any of the following commands. + +Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. + +**apps** - This directory contains partial applications for each version of Angular we want to test. Typically these directories contain new `package.json` files, `angular.json` files, and more. If you have code that is specific to a particular version of Angular, put it in this directory. + +**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. + +**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. + +**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. + +Usage: + +```shell +# Build a test app using apps/ng14 as a reference +./build.sh ng14 +``` + +## How to modify test apps + +To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. + +If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.spec.ts` in `apps/ng14`, make sure you place the file in `apps/ng14/e2e/src/test.spec.ts`. + +### Version-specific tests + +If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. + +### Testing Lazy Loaded Ionic Components + +Tests for lazy loaded Ionic UI components should only be added under the `/lazy` route. This ensures the `IonicModule` is added. + +### Testing Standalone Ionic Components + +Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. + +## Adding New Test Apps + +As we add support for new versions of Angular, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: + +1. Navigate to the built app for the most recent version of Angular that Ionic tests. +2. Update the application by following the steps on https://update.angular.io/. +3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, `angular.json`, etc). +4. Copy the changed files to a new directory in `apps`. +5. Add a new entry to the matrix for `test-core-angular` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. +6. Commit these changes and push. + +Example: + +In this example, we are going to add the Angular 14 test app. + +1. Build the Angular 13 test app using `./build.sh ng13`. +2. Navigate to `build/ng13`. +3. Perform the upgrade steps on https://update.angular.io/. The "From" field should say "13.0" and the "To" field should say "14.0". + +Note: You may encounter some other peer dependency issues not covered by the Angular Upgrade Guide. These peer dependency issues can be resolved manually by updating the installed version of each dependency. + +4. Observe that the output of the Angular upgrade indicates that the following files were modified: + +`angular.json` +`package-lock.json` +`package.json` +`tsconfig.json` +`src/app/form/form.component.ts` +`src/app/modal-example/modal-example.component.ts` + +5. Create a directory in `apps` named `ng14`. +6. Copy the modified files to the `apps/ng14` directory. +7. Open `./github/workflows/build.yml` and find the `test-angular-e2e` job. +8. Find the `apps` field under `matrix`. +9. Add "ng14" to the `apps` field. +10. Open `./github/workflows/stencil-nightly.yml` and find the `test-angular-e2e` job. +11. Repeat steps 8 and 9. +12. Commit these changes and push. diff --git a/docs/core/README.md b/docs/core/README.md new file mode 100644 index 00000000000..3132e38c401 --- /dev/null +++ b/docs/core/README.md @@ -0,0 +1,113 @@ +# @ionic/core + +[Ionic](https://ionicframework.com/) is an open source App Development Framework that makes it easy to build top quality Native and Progressive Web Apps with web technologies. + +The Ionic Core package contains the Web Components that make up the reusable UI building blocks of Ionic Framework. These components are designed to be used in traditional frontend view libraries/frameworks (such as [Stencil](https://stenciljs.com/), React, Angular, or Vue), or on their own through traditional JavaScript in the browser. + + +## Features + +* Tiny, highly optimized components built with [Stencil](https://stenciljs.com/) +* Styling for both iOS and Material Design +* No build or compiling required +* Simply add the static files to any project +* Lazy-loaded components without configuration +* Asynchronous rendering +* Theming through CSS Variables + + +## How to use + +### Vanilla HTML + +Easiest way to start using Ionic Core is by adding a script tag to the CDN: + +```html + + + +``` + +Any Ionic component added to the webpage will automatically load. This includes writing the component tag directly in HTML, or using JavaScript such as `document.createElement('ion-toggle')`. + +Additionally, within this package is a `dist/ionic.js` file and accompanying `dist/ionic/` directory. These are the same files which are used by the CDN, and they're available in this package so they can be apart of an app's local development. + + +## Framework Bindings + +The `@ionic/core` package can be used in simple HTML, or by vanilla JavaScript without any framework at all. Ionic also has packages that make it easier to integrate Ionic into a framework's traditional ecosystem and patterns. (However, at the lowest-level framework bindings are still just using Ionic Core and Web Components). + +* [@ionic/angular](https://www.npmjs.com/package/@ionic/angular) + + +## Custom Elements Build + +In addition to the default, self lazy-loading components built by Stencil, this package also comes with each component exported as a stand-alone custom element within `@ionic/core/components`. Each component extends `HTMLElement`, and does not lazy-load itself. Instead, this package is useful for projects already using a bundler such as Webpack or Rollup. While all components are available to be imported, the custom elements build also ensures bundlers only import what's used, and tree-shakes any unused components. + +Below is an example of importing `ion-badge`, and initializing Ionic so it is able to correctly load the "mode", such as Material Design or iOS. Additionally, the `initialize({...})` function can receive the Ionic config. + +```typescript +import { defineCustomElement } from "@ionic/core/components/ion-badge.js"; +import { initialize } from "@ionic/core/components"; + +// Initializes the Ionic config and `mode` behavior +initialize(); + +// Defines the `ion-badge` web component +defineCustomElement(); +``` + +Notice how we import from `@ionic/core/components` as opposed to `@ionic/core`. This helps bundlers pull in only the code that is needed. + +The `defineCustomElement` function will automatically define the component as well as any child components that may be required. + +For example, if you wanted to use `ion-modal`, you would do the following: + +```typescript +import { defineCustomElement } from "@ionic/core/components/ion-modal.js"; +import { initialize } from "@ionic/core/components"; + +// Initializes the Ionic config and `mode` behavior +initialize(); + +// Defines the `ion-modal` and child `ion-backdrop` web components. +defineCustomElement(); +``` + +The `defineCustomElement` function will define `ion-modal`, but it will also define `ion-backdrop`, which is a component that `ion-modal` uses internally. + +### Using Overlay Controllers + +When using an overlay controller, developers will need to define the overlay component before it can be used. Below is an example of using `modalController`: + +```typescript +import { defineCustomElement } from '@ionic/core/components/ion-modal.js'; +import { initialize, modalController } from '@ionic/core/components'; + +initialize(); +defineCustomElement(); + +const showModal = async () => { + const modal = await modalController.create({ ... }); + + ... +} +``` + +## How to contribute + +[Check out the CONTRIBUTE guide](/docs/CONTRIBUTING.md) + +## Related + +* [Ionic Documentation](https://ionicframework.com/docs/) +* [Ionic Discord](https://ionic.link/discord) +* [Ionic Forum](https://forum.ionicframework.com/) +* [Ionicons](http://ionicons.com/) +* [Stencil](https://stenciljs.com/) +* [Capacitor](https://capacitor.ionicframework.com/) + + +## License + +* [MIT](https://raw.githubusercontent.com/ionic-team/ionic/master/LICENSE) diff --git a/docs/core/scripts.md b/docs/core/scripts.md new file mode 100644 index 00000000000..a4feb9a05ea --- /dev/null +++ b/docs/core/scripts.md @@ -0,0 +1,46 @@ + +# Core Scripts + +## Build + +### 1. Clone ionic + + git@github.com:ionic-team/ionic.git + cd ionic + +### 2. Run `npm install` + + cd core + npm install + + +Notice that `@ionic/core` lives in `core`. + +### 3. Run `npm start` + +Make sure you are inside the `core` directory. + + npm start + +With the `dev` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and http://localhost:3333/ will open in a browser. + +### 4. Preview + +Navigate to http://localhost:3333/src/components/. Each component has small e2e apps found in the `test` directory, for example: http://localhost:3333/src/components/button/test/basic + +As changes are made in an editor to source files, the e2e app will live-reload. + +## How to contribute + +1. `npm start` allows you to modify the components and have live reloading, just like another ionic app. + +2. When everything looks good, run `npm run validate` to verify the tests linter and production build passes. + + +# Deploy + +1. `npm run prepare.deploy` +2. Review/update changelog +3. Commit updates using the package name and version number as the commit message. +4. `npm run deploy` +5. :tada: diff --git a/docs/react/README.md b/docs/react/README.md new file mode 100644 index 00000000000..9cba7b48648 --- /dev/null +++ b/docs/react/README.md @@ -0,0 +1,49 @@ +# @ionic/react + +These are React specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components/services. + +To get started, install the Ionic CLI by running `npm i -g @ionic/cli`. Then, start a new Ionic React Project by running `ionic start myapp --type=react`. + +## Publishing a Native Application + +You can now make use of all of the ionic components in your React application. +If you want to publish your app to the App Store or Google Play you will need to use the ionic cli to execute Capacitor commands to do so. + +More information on this can be found here. https://ionicframework.com/docs/cli +If you want to learn more about Capacitor our dedicated site can be found here. https://capacitor.ionicframework.com/ + +The commands that you will need to execute are below in your project's root. + +```sh +ionic init "My React App" --type=react +ionic integrations enable capacitor +``` + +Then run the following command to get started with either `ios` or `android` platforms. + +``` +ionic capacitor add +``` + +After build you build your app you will need to copy your capacitor resources into the build dir so execute the following command. + +``` +ionic capacitor copy +``` + +To open your application to build/emulate in Android Studio or Xcode run the `open` command. + +``` +ionic capacitor open +``` + +## Related + +- [Ionic Documentation](https://ionicframework.com/docs/) +- [Ionic Forum](https://forum.ionicframework.com/) +- [Ionicons](http://ionicons.com/) +- [Capacitor](https://capacitor.ionicframework.com/) + +## License + +- [MIT](https://raw.githubusercontent.com/ionic-team/ionic/main/LICENSE) diff --git a/docs/react/testing.md b/docs/react/testing.md new file mode 100644 index 00000000000..e0b8efa3712 --- /dev/null +++ b/docs/react/testing.md @@ -0,0 +1,55 @@ +# React E2E Test Apps + +Ionic Framework supports multiple versions of React. As a result, we need to verify that Ionic works correctly with each of these React versions. + +## Syncing Local Changes + +The React test app supports syncing your locally built changes for validation. + +1. Build the `core`, `packages/react`, and `packages/react-router` directories using `npm run build`. +2. [Build the React test app](#test-app-build-structure). +3. Navigate to the built test app. +4. Install dependencies using `npm install`. +5. Sync your local changes using `npm run sync`. + +From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. + +## Test App Build Structure + +Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. + +**apps** - This directory contains partial applications for each version of React we want to test. Typically these directories contain new `package.json` files, `cypress.config.ts` files, and more. If you have code that is specific to a particular version of React, put it in this directory. + +**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. + +**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. + +**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. + +Usage: + +```shell +# Build a test app using apps/react17 as a reference +./build.sh react17 +``` + +## How to modify test apps + +To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. + +If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/react17`, make sure you place the file in `apps/react17/tests/e2e/test.e2e.ts`. + +### Version-specific tests + +If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. + +## Adding New Test Apps + +As we add support for new versions of React, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: + +1. Navigate to the built app for the most recent version of React that Ionic tests. +2. Update the application to the latest version of React. +3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc). +4. Copy the changed files to a new directory in `apps`. +5. Add a new entry to the matrix for `test-react-e2e` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. +6. Commit these changes and push. diff --git a/docs/react/testing2.md b/docs/react/testing2.md new file mode 100644 index 00000000000..10e49c2b066 --- /dev/null +++ b/docs/react/testing2.md @@ -0,0 +1,47 @@ +# React Test App + +## Getting Started + +### Setup + +Make sure you are using the latest versions of node and npm. If you do not have these, [download the installer](https://nodejs.org/) for the LTS version of Node.js. This is the best way to also [install npm](https://blog.npmjs.org/post/85484771375/how-to-install-npm#_=_). + +### Building Dependencies + +Navigate to the `core`, `packages/react` and `packages/react-router` directories and build each of them: + +```bash +npm i +npm run build +``` + +Then, install dependencies from this directory for this test app: + +``` +npm i +``` + +### Syncing Changes + +When making changes to the React package, run the following from this directory to sync the changes: + +```bash +npm run sync +``` + +### Previewing App + +To preview this app locally, run the following from this directory: + +```bash +npm start +``` + +### Running Tests + +To run the e2e tests, run the following from this directory: + +``` +npm run build +npm run e2e +``` diff --git a/docs/sass-guidelines.md b/docs/sass-guidelines.md new file mode 100644 index 00000000000..f5c0f9ed800 --- /dev/null +++ b/docs/sass-guidelines.md @@ -0,0 +1,685 @@ +# Sass Guidelines + +- [Definitions](#definitions) +- [Scope](#scope) +- [Historical Usage](#historical-usage) +- [Current Usage](#current-usage) +- [Proposed Usage](#proposed-usage) + * [Comments](#comments) + * [Variables](#variables) + + [โœ… Global](#-global) + + [โœ… Theming](#-theming) + + [โœ… Reusable values](#-reusable-values) + + [โœ… Media queries](#-media-queries) + + [โœ… Dynamic calculations](#-dynamic-calculations) + + [๐Ÿšซ Consistency](#-consistency) + + [๐Ÿšซ Text Alignment](#-text-alignment) + + [๐Ÿšซ Structural Changes](#-structural-changes) + + [๐Ÿšซ Font Properties](#-font-properties) + +## Definitions + +**Sass:** An extension to CSS that reduces the repetition in CSS and allows developers to use shared functions, mixins and variables. [^1] + +**Members:** Refers to variables, functions and mixins in Sass. + +## Scope + +Sass provides members that make it easier to reuse code throughout the Ionic Framework repository. Variables hold values that can be used by other stylesheets. Mixins define reusable blocks of styles that can be included in other selectors. Functions allow the manipulation of values and can perform calculations. + +The purpose of this document is to identify the scenarios in which Sass variables should be used. + +## Historical Usage + +In Ionic Framework v1 through v3, the project was built with Sass variables that developers could change at runtime. While the default values were provided by Ionic Framework, anyone developing with it could override these values to rebuild the Ionic Framework CSS with their own values. [^2] + +Due to this, Ionic Framework documented the Sass variables as part of the public API using `@prop` comments as early as [v2.0.0](https://github.com/ionic-team/ionic-framework/blob/v2.0.0/src/components/alert/alert.ios.scss): + +```scss +// alert.ios.scss + +/// @prop - Max width of the alert +$alert-ios-max-width: 270px !default; + +/// @prop - Border radius of the alert +$alert-ios-border-radius: 13px !default; +``` + +If a Sass variable was deprecated or hidden from the public API, the `@prop` comment would be removed, or it would never be added, as seen in [v3.9.2](https://github.com/ionic-team/ionic-framework/blob/v3.9.2/src/components/alert/alert.ios.scss#L18-L19): + +```scss +// alert.ios.scss + +// deprecated +$alert-ios-head-padding: null !default; +``` + +To ensure proper documentation of variables for customizing Ionic Framework, Sass variables were added for components even if they were not used multiple times within the same component or elsewhere: + +```scss +// alert.ios.scss + +/// @prop - Text color of the label for the checked radio alert +$alert-ios-radio-label-text-color-checked: $alert-ios-button-text-color !default; + +.alert-ios [aria-checked=true] .alert-radio-label { + color: $alert-ios-radio-label-text-color-checked; +} +``` + +## Current Usage + +The abundance of Sass variables currently in Ionic Framework is a result of their historical usage, being used to rebuild the CSS and customize Ionic Framework components. + +The comments for Sass variables are also still visible today in [v7.7.0](https://github.com/ionic-team/ionic-framework/blob/v7.7.0/core/src/components/alert/alert.ios.vars.scss), even though they are no longer used by any documentation generators: + +```scss +// alert.ios.vars.scss + +/// @prop - Max width of the alert +$alert-ios-max-width: dynamic-font-clamp(1, 270px, 1.2) !default; + +/// @prop - Border radius of the alert +$alert-ios-border-radius: 13px !default; +``` + +These comments aren't necessary when the naming describes its use thoroughly. The comments for the variables above do not need to be there, as it is fairly obvious what they are used for. + +However, the comment for the following variable might be helpful in explaining where it is used because on first glance it reads like it could be used for a sub title inside of a title: + +```scss +// action-sheet.ios.vars.scss + +/// @prop - Font weight of the action sheet title when it has a sub title +$action-sheet-ios-title-with-sub-title-font-weight: 600 !default; +``` + +It could be argued though that the comment doesn't really help, as seeing the variable in use will explain its purpose the best. Additionally, this is an example of a variable that isn't necessary, given it is only used in one place, which is why it is so specific in the first place. + +## Proposed Usage + +There are two things that need to be outlined here: when we should use comments and when we should use variables. The sections below detail the proposed usage for each of these. + +### Comments + +We should update the comments for Sass variables in one of the following ways: + +1. If we don't intend to ever publicly document the Sass variables again, we should update the comments to remove the syntax that was added for documentation generation: + ```diff + // alert.ios.vars.scss + + -/// @prop - Border radius of the alert + +// Border radius of the alert + $alert-ios-border-radius: 13px !default; + ``` + +2. If we don't find the comments to be helpful, and want to stick with keeping the variable names specific, we should remove the comments entirely: + ```diff + // alert.ios.vars.scss + + -/// @prop - Border radius of the alert + $alert-ios-border-radius: 13px !default; + ``` + +3. If we find the comments to be helpful for certain variables or situations, like when there are math calculations involved, we should keep only the comments that are necessary to explain what is going on: + ```diff + -/// @prop - Height of the alert button + /** + * We want the height of the button to + * scale with the text so the next never runs + * into the edge of the button. We change the height + * instead of adding padding because we would need to offset + * the height the padding and the border. Since the border uses + * a hairline (<1px) width, this will cause subpixel rendering + * differences across browsers. + */ + $alert-ios-button-height: dynamic-font-min(1, 44px) !default; + ``` + +### Variables + +The table below outlines the recommended approach for when to use Sass variables. Each scenario links to a section that explains it in more detail. + +| | Scenario | +| ---| ---------------------------------------------------------------| +| โœ… | [Global](#white_check_mark-global) | +| โœ… | [Theming](#white_check_mark-theming) | +| โœ… | [Reusable values](#white_check_mark-reusable-values) | +| โœ… | [Media queries](#white_check_mark-media-queries) | +| โœ… | [Dynamic calculations](#white_check_mark-dynamic-calculations) | +| ๐Ÿšซ | [Consistency](#no_entry_sign-consistency) | +| ๐Ÿšซ | [Text Alignment](#no_entry_sign-text-alignment) | +| ๐Ÿšซ | [Structural Changes](#no_entry_sign-structural-changes) | +| ๐Ÿšซ | [Font Properties](#no_entry_sign-font-properties) | + +#### โœ… Global + +Global variables that are used in multiple places include `font-family`, `z-index`, and `opacity`. These should continue to be set in variables as they affect multiple components that use them. + +Example of global variables: + +```scss +// ionic.globals.scss + +$font-family-base: var(--ion-font-family, inherit) !default; + +$hairlines-width: .55px !default; + +$placeholder-opacity: 0.6 !default; +``` + +#### โœ… Theming + +Storing colors and other design-related values makes it easy to update an entire theme by modifying a few variables. + +Example of theme variables: + +```scss +// ionic.theme.default.scss + +$background-color-value: #fff !default; +$background-color-rgb-value: 255, 255, 255 !default; + +$text-color-value: #000 !default; +$text-color-rgb-value: 0, 0, 0 !default; + +$background-color: var(--ion-background-color, $background-color-value) !default; +$background-color-rgb: var(--ion-background-color-rgb, $background-color-rgb-value) !default; +$text-color: var(--ion-text-color, $text-color-value) !default; +$text-color-rgb: var(--ion-text-color-rgb, $text-color-rgb-value) !default; +``` + +```scss +// ionic.theme.default.ios.scss + +$backdrop-ios-color: var(--ion-backdrop-color, #000) !default; +$overlay-ios-background-color: var(--ion-overlay-background-color, var(--ion-color-step-100, #f9f9f9)) !default; +``` + +#### โœ… Reusable values + +Use variables for values that are repeated throughout stylesheets, such as spacing, `border-radius`, `font-size`, or any other value used in multiple places. A value should only be considered reusable if it is used more than once and related among the elements it is being applied to in some way. For instance, a value is not considered related if it changes a common property, such as border style. While many components use `border-style: solid`, it does not need to be stored unless these components will require updates with design changes. Currently, the border styles have consistently been set to `solid`, with the exception of `none` for a CSS reset. + +Example of reusable values: + + + + + + + + + + + + + + + + + + + + +
Do โœ…
+ +```scss +// alert.ios.vars.scss + +/// @prop - Padding end of the alert head +$alert-ios-head-padding-end: 16px !default; + +/// @prop - Padding start of the alert head +$alert-ios-head-padding-start: $alert-ios-head-padding-end !default; +``` + +```scss +// alert.ios.scss + +.alert-head { + padding-top: 12px; + padding-inline-end: $alert-ios-head-padding-end; + padding-bottom: 7px; + padding-inline-start: $alert-ios-head-padding-start; +} +``` + +
Don't :x:
+ +```scss +// alert.ios.vars.scss + +/// @prop - Padding top of the alert head +$alert-ios-head-padding-top: 12px !default; + +/// @prop - Padding bottom of the alert head +$alert-ios-head-padding-bottom: 7px !default; +``` + +```scss +// alert.ios.scss + +.alert-head { + padding-top: $alert-ios-head-padding-top; + padding-bottom: $alert-ios-head-padding-bottom; +} +``` + +
+ +If a value is shared among multiple components, it should be made into a [global variable](#white_check_mark-global) instead of importing the variable from a specific component. For example, variables that are shared between list components (item, item divider, list header) should be defined in a global theme file: + + + + + + + + + + + + + + + + + + + + +
Do โœ…
+ +```scss +// ionic.theme.default.md.scss + +$global-md-item-padding-end: 16px; +$global-md-item-padding-start: $global-md-item-padding-end; +``` + +```scss +// item.md.vars.scss + +@import "../../themes/ionic.globals.md"; + +/// @prop - Padding end for the item content +$item-md-padding-end: $global-md-item-padding-end !default; + +/// @prop - Padding start for the item content +$item-md-padding-start: $global-md-item-padding-start !default; +``` + +```scss +// item-divider.md.vars.scss + +@import "../../themes/ionic.globals.md"; + +/// @prop - Padding start for the divider +$item-divider-md-padding-start: $global-md-item-padding-start !default; + +/// @prop - Padding end for the divider +$item-divider-md-padding-end: $global-md-item-padding-end !default; +``` + +
Don't :x:
+ +```scss +// item.md.vars.scss + +@import "../../themes/ionic.globals.md"; + +/// @prop - Padding end for the item content +$item-md-padding-end: 16px !default; + +/// @prop - Padding start for the item content +$item-md-padding-start: 16px !default; +``` + +```scss +// item-divider.md.vars.scss + +@import "../../themes/ionic.globals.md"; +@import "../item/item.md.vars"; + +/// @prop - Padding start for the divider +$item-divider-md-padding-start: $item-md-padding-start !default; + +/// @prop - Padding end for the divider +$item-divider-md-padding-end: $item-md-padding-end !default; +``` + +
+ +> [!TIP] +> The names of the global variables are just an example. We do not currently have a naming convention for global variables. + +#### โœ… Media queries + +Define breakpoints for responsive design to allow easy adjustments as needed. + +Example of breakpoints used by media queries: + +```scss +// ionic.globals.scss + +// The minimum dimensions at which your layout will change, +// adapting to different screen sizes, for use in media queries +$screen-breakpoints: ( + xs: 0, + sm: 576px, + md: 768px, + lg: 992px, + xl: 1200px +) !default; +``` + +#### โœ… Dynamic calculations + +Variables can be useful for dynamic calculations, such as storing a base font size in a variable and then using it in calculations for other font sizes or spacing values. Variables should not be used for storing a function call, even if the function itself has dynamic calculations. + + + + + + + + + + + + + + + + + + + + +
Do โœ…
+ +```scss +// chip.vars.scss + +/// @prop - Unitless font size of the chip before scaling +$chip-base-font-size: 14; + +/// @prop - Font size of the chip in rem before scaling +$chip-base-font-size-rem: #{math.div($chip-base-font-size, 16)}rem; + +/// @prop - Size of an icon within a chip (in em to scale as the font size of the chip scales) +$chip-icon-size: math.div(20em, $chip-base-font-size); + +/// @prop - Size of an avatar within a chip (in em to scale as the font size of the chip scales) +$chip-avatar-size: math.div(24em, $chip-base-font-size); +``` + +
Don't :x:
+ +```scss +// alert.vars.scss + +/// @prop - Font size of the alert button +$alert-button-font-size: dynamic-font(14px) !default; +``` + +
+ +#### ๐Ÿšซ Consistency + +While we usually aim for consistency across different modes, this isn't always necessary when dealing with Sass variables. If certain styles are present in one mode but absent in another, there's no need to include a Sass variable for the mode lacking those styles. + +For example, the color of the label changes when focused in `md` mode. However, in `ios`, the label does not receive different styling when focused, therefore it does not require the same styles or a Sass variable defined: + + + + + + + + + + + + + + + + + + + + +
Do โœ…
+ +```scss +// label.md.vars.scss + +/// @prop - Text color of the stacked/floating label when it is focused +$label-md-text-color-focused: ion-color(primary, base) !default; +``` + +```scss +// label.md.scss + +:host-context(.ion-focused).label-stacked:not(.ion-color), +:host-context(.ion-focused).label-floating:not(.ion-color), +:host-context(.item-has-focus).label-stacked:not(.ion-color), +:host-context(.item-has-focus).label-floating:not(.ion-color) { + color: $label-md-text-color-focused; +} +``` + +
Don't :x:
+ +```scss +// label.ios.vars.scss + +/// @prop - Text color of the stacked/floating label when it is focused +$label-ios-text-color-focused: null !default; +``` + +```scss +// label.ios.scss + +:host-context(.ion-focused).label-stacked:not(.ion-color), +:host-context(.ion-focused).label-floating:not(.ion-color), +:host-context(.item-has-focus).label-stacked:not(.ion-color), +:host-context(.item-has-focus).label-floating:not(.ion-color) { + color: $label-ios-text-color-focused; +} +``` + +
+ +#### ๐Ÿšซ Text Alignment + +A text alignment property should not be stored in a Sass variable, even if it is used in multiple places. This is because the alignment may be tied to a specific design, and the design may change, causing them to become disconnected. + + + + + + + + + + + + + +
Do โœ…Don't :x:
+ +```scss +// action-sheet.ios.scss + +:host { + text-align: center; +} + +.action-sheet-title { + text-align: center; +} +``` + + + +```scss +// action-sheet.ios.vars.scss + +/// @prop - Text align of the action sheet +$action-sheet-ios-text-align: center !default; +``` + +```scss +// action-sheet.ios.scss + +:host { + text-align: $action-sheet-ios-text-align; +} + +.action-sheet-title { + text-align: $action-sheet-ios-text-align; +} +``` + +
+ + +#### ๐Ÿšซ Structural Changes + +Variables should not be used when they are structural changes of an element. This includes `display` properties, `flex` properties, `grid` properties, and more. + + + + + + + + + + + + + + + + + + + + +
Do โœ…
+ +```scss +// alert.ios.scss + +.alert-button-group { + flex-wrap: wrap; +} + +.alert-button { + flex: 1 1 auto; +} +``` + +
Don't :x:
+ + +```scss +// alert.ios.vars.scss + +/// @prop - Flex wrap of the alert button group +$alert-ios-button-group-flex-wrap: wrap !default; + +/// @prop - Flex of the alert button +$alert-ios-button-flex: 1 1 auto !default; +``` + +```scss +// alert.ios.scss + +.alert-button-group { + flex-wrap: $alert-ios-button-group-flex-wrap; +} + +.alert-button { + flex: $alert-ios-button-flex; +} +``` + +
+ +#### ๐Ÿšซ Font Properties + +We shouldn't use variables for changing things such as `font-size` or `font-weight`, as these are not changed based on a theme and do not need to be updated globally. When updating the `font-size` and `font-weight` for these elements, it will always be done on a case-by-case basis: + + + + + + + + + + + + + + + + + + + + +
Do โœ…
+ +```scss +// action-sheet.ios.scss + +.action-sheet-title { + font-size: dynamic-font-min(1, 13px); + font-weight: 400; +} + +.action-sheet-sub-title { + font-size: dynamic-font-min(1, 13px); + font-weight: 400; +} +``` + +
Don't :x:
+ +```scss +// action-sheet.ios.vars.scss + +/// @prop - Font size of the action sheet title +$action-sheet-ios-title-font-size: dynamic-font-min(1, 13px) !default; + +/// @prop - Font weight of the action sheet title +$action-sheet-ios-title-font-weight: 400 !default; + +/// @prop - Font size of the action sheet sub title +$action-sheet-ios-sub-title-font-size: dynamic-font-min(1, 13px) !default; +``` + +```scss +// action-sheet.ios.scss + +.action-sheet-title { + font-size: $action-sheet-ios-title-font-size; + font-weight: $action-sheet-ios-title-font-weight; +} + +.action-sheet-sub-title { + font-size: $action-sheet-ios-sub-title-font-size; + font-weight: $action-sheet-ios-title-font-weight; +} +``` + +
+ +[^1]: Sass Documentation, https://sass-lang.com/documentation/ + +[^2]: Ionic Framework v3 Documentation - Theming - Overriding Ionic Variables, https://ionicframework.com/docs/v3/theming/overriding-ionic-variables/ diff --git a/docs/vue/README.md b/docs/vue/README.md new file mode 100644 index 00000000000..f1e964c6d78 --- /dev/null +++ b/docs/vue/README.md @@ -0,0 +1,57 @@ +# @ionic/vue + +Ionic Framework integration for Vue 3 apps. + +## Building + +1. Install dependencies in `@ionic/core`: + +```shell +cd core && npm install +``` + +2. Build `@ionic/core`. This will generate Vue component bindings in the `packages/vue` directory: + +```shell +npm run build +```` + +3. Install dependencies in `@ionic/vue`: + +```shell +cd packages/vue && npm install +``` + +4. Build `@ionic/vue`: + +```shell +npm run build +```` + +5. Install dependencies in `@ionic/vue-router`: + +```shell +cd packages/vue-router && npm install +``` + +6. Build `@ionic/vue-router`: + +```shell +npm run build +```` + +## Tests + +* E2E Tests are found in the `packages/vue/test/base/tests` directory and use Cypress. +* When making changes to `@ionic/vue` or `@ionic/vue-router` you can run `npm run sync` in the [test-app directory](test/README.md#syncing-local-changes) to ensure that the test application is using your built changes. Be sure to build in the `vue` and `vue-router` directories first. +* Tests can be run in headless mode by running `npm run cypress`. +* If you want to open the Cypress test runner, you can run `node_modules/.bin/cypress open`. +* Bug fix and feature PRs should have new tests verifying the PR functionality. + +## Contributing + +See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md). + +## Need Help? + +Post your question on the [Ionic Forum](http://forum.ionicframework.com/). diff --git a/docs/vue/testing.md b/docs/vue/testing.md new file mode 100644 index 00000000000..b124b491e77 --- /dev/null +++ b/docs/vue/testing.md @@ -0,0 +1,58 @@ +# Vue E2E Test Apps + +Ionic Framework supports multiple versions of Vue. As a result, we need to verify that Ionic works correctly with each of these Vue versions. + +## Syncing Local Changes + +The Vue test app supports syncing your locally built changes for validation. + +1. [Build](../README.md#building) the `core`, `packages/vue`, and `packages/vue-router` projects using `npm run build`. +2. [Build the Vue test app](#test-app-build-structure). +3. Navigate to the built test app directory (e.g. `packages/vue/test/build/vue3`). +4. Install dependencies using `npm install`. +5. Sync your local changes using `npm run sync`. + +From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. + +## Test App Build Structure + +> [!NOTE] +> Please confirm your current directory as `packages/vue/test` before proceeding with any of the following commands. + +Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. + +**apps** - This directory contains partial applications for each version of Vue we want to test. Typically these directories contain new `package.json` files, `jest.config.js` files, and more. If you have code that is specific to a particular version of Vue, put it in this directory. + +**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. + +**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. + +**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. + +Usage: + +```shell +# Build a test app using apps/vue3 as a reference +./build.sh vue3 +``` + +## How to modify test apps + +To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. + +If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/vue3`, make sure you place the file in `apps/vue3/tests/e2e/test.e2e.ts`. + +### Version-specific tests + +If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. + +## Adding New Test Apps + +As we add support for new versions of Vue, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: + +1. Navigate to the built app for the most recent version of Vue that Ionic tests. +2. Update the application to the latest version of Vue. +3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc). +4. Copy the changed files to a new directory in `apps`. +5. Add a new entry to the matrix for `test-core-vue` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. +6. Commit these changes and push. diff --git a/packages/angular/README.md b/packages/angular/README.md index 0a1b2c488d7..b65d0a7c725 100644 --- a/packages/angular/README.md +++ b/packages/angular/README.md @@ -1,74 +1,3 @@ # @ionic/angular -Ionic Angular specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components. - - -## Related - -* [Ionic Core Components](https://www.npmjs.com/package/@ionic/core) -* [Ionic Documentation](https://ionicframework.com/docs/) -* [Ionic Discord](https://ionic.link/discord) -* [Ionic Forum](https://forum.ionicframework.com/) -* [Ionicons](http://ionicons.com/) -* [Stencil](https://stenciljs.com/) -* [Capacitor](https://capacitor.ionicframework.com/) - - -## License - -* [MIT](https://raw.githubusercontent.com/ionic-team/ionic/main/LICENSE) - -## Testing ng-add in ionic - -1. Pull the latest from `main` -2. Build ionic/angular: `npm run build` -3. Run `npm link` from `ionic/angular/dist` directory -4. Create a blank angular project - -``` -ng new add-test -// Say yes to including the router, we need it -cd add-test -``` - -5. To run schematics locally, we need the schematics-cli (once published, this will not be needed) - -``` -npm install @angular-devkit/schematics-cli -``` - -6. Link `@ionic/angular` - -``` -npm link @ionic/angular -``` - - -7. Run the local copy of the ng-add schematic - -``` -$ npx schematics @ionic/angular:ng-add -``` - - -You'll now be able to add ionic components to a vanilla Angular app setup. - -## Project Structure - -**common** - -This is where logic that is shared between lazy loaded and standalone components live. For example, the lazy loaded IonPopover and standalone IonPopover components extend from a base IonPopover implementation that exists in this directory. - -**Note:** This directory exposes internal APIs and is only accessed in the `standalone` and `src` submodules. Ionic developers should never import directly from `@ionic/angular/common`. Instead, they should import from `@ionic/angular` or `@ionic/angular/standalone`. - -**standalone** - -This is where the standalone component implementations live. It was added as a separate entry point to avoid any lazy loaded logic from accidentally being pulled in to the final build. Having a separate directory allows the lazy loaded implementation to remain accessible from `@ionic/angular` for backwards compatibility. - -Ionic developers can access this by importing from `@ionic/angular/standalone`. - -**src** - -This is where the lazy loaded component implementations live. - -Ionic developers can access this by importing from `@ionic/angular`. +This file has been moved to [/docs/angular/README.md](/docs/angular/README.md). diff --git a/packages/angular/test/README.md b/packages/angular/test/README.md index b2e56ef2ee4..26bc797495e 100644 --- a/packages/angular/test/README.md +++ b/packages/angular/test/README.md @@ -1,118 +1,3 @@ # Angular E2E Test Apps -Ionic Framework supports multiple versions of Angular. As a result, we need to verify that Ionic works correctly with each of these Angular versions. - -## Syncing Local Changes - -The Angular test app supports syncing your locally built changes for validation. - -1. Build the `core` and `packages/angular` directories using `npm run build`. -2. [Build the Angular test app](#test-app-build-structure). -3. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng14`). -4. Install dependencies using `npm install`. -5. Sync your local changes using `npm run sync`. - -From here you can either build the application or start a local dev server. When re-syncing changes, you will need to [wipe or disable the application cache](#application-cache). - -## Application Cache - -Angular CLI creates a cache of several files on disk by default in the `.angular` directory. This decreases the time taken to build the test application. However, the cache makes it difficult to quickly sync and check local changes of Ionic. As a result, the `.angular` cache is disabled by default in the test app projects. - -See https://angular.io/cli/cache for more information. - -### Disable Cache - -```shell -ng cache disable -``` - -> [!NOTE] -> You may need to manually remove the `.angular` directory once after running this command. - -### Enable Cache - -```shell -ng cache enable -``` - -> [!NOTE] -> You will need to delete the `.angular` cache and restart the dev server every time you want to sync local changes of Ionic. - -## Test App Build Structure - -> [!NOTE] -> Please confirm your current directory as `packages/angular/test` before proceeding with any of the following commands. - -Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. - -**apps** - This directory contains partial applications for each version of Angular we want to test. Typically these directories contain new `package.json` files, `angular.json` files, and more. If you have code that is specific to a particular version of Angular, put it in this directory. - -**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. - -**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. - -**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. - -Usage: - -```shell -# Build a test app using apps/ng14 as a reference -./build.sh ng14 -``` - -## How to modify test apps - -To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. - -If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.spec.ts` in `apps/ng14`, make sure you place the file in `apps/ng14/e2e/src/test.spec.ts`. - -### Version-specific tests - -If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. - -### Testing Lazy Loaded Ionic Components - -Tests for lazy loaded Ionic UI components should only be added under the `/lazy` route. This ensures the `IonicModule` is added. - -### Testing Standalone Ionic Components - -Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. - -## Adding New Test Apps - -As we add support for new versions of Angular, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: - -1. Navigate to the built app for the most recent version of Angular that Ionic tests. -2. Update the application by following the steps on https://update.angular.io/. -3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, `angular.json`, etc). -4. Copy the changed files to a new directory in `apps`. -5. Add a new entry to the matrix for `test-core-angular` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. -6. Commit these changes and push. - -Example: - -In this example, we are going to add the Angular 14 test app. - -1. Build the Angular 13 test app using `./build.sh ng13`. -2. Navigate to `build/ng13`. -3. Perform the upgrade steps on https://update.angular.io/. The "From" field should say "13.0" and the "To" field should say "14.0". - -Note: You may encounter some other peer dependency issues not covered by the Angular Upgrade Guide. These peer dependency issues can be resolved manually by updating the installed version of each dependency. - -4. Observe that the output of the Angular upgrade indicates that the following files were modified: - -`angular.json` -`package-lock.json` -`package.json` -`tsconfig.json` -`src/app/form/form.component.ts` -`src/app/modal-example/modal-example.component.ts` - -5. Create a directory in `apps` named `ng14`. -6. Copy the modified files to the `apps/ng14` directory. -7. Open `./github/workflows/build.yml` and find the `test-angular-e2e` job. -8. Find the `apps` field under `matrix`. -9. Add "ng14" to the `apps` field. -10. Open `./github/workflows/stencil-nightly.yml` and find the `test-angular-e2e` job. -11. Repeat steps 8 and 9. -12. Commit these changes and push. +This file has been moved to [/docs/angular/testing.md](/docs/angular/testing.md). diff --git a/packages/react/README.md b/packages/react/README.md index 83119c93467..e3c9b85c9a6 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -1,49 +1,3 @@ -## @ionic/react +# @ionic/react -These are React specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components/services. - -To get started, install the Ionic CLI by running `npm i -g @ionic/cli`. Then, start a new Ionic React Project by running `ionic start myapp --type=react`. - -## Publishing a Native Application - -You can now make use of all of the ionic components in your React application. -If you want to publish your app to the App Store or Google Play you will need to use the ionic cli to execute Capacitor commands to do so. - -More information on this can be found here. https://ionicframework.com/docs/cli -If you want to learn more about Capacitor our dedicated site can be found here. https://capacitor.ionicframework.com/ - -The commands that you will need to execute are below in your project's root. - -```sh -ionic init "My React App" --type=react -ionic integrations enable capacitor -``` - -Then run the following command to get started with either `ios` or `android` platforms. - -``` -ionic capacitor add -``` - -After build you build your app you will need to copy your capacitor resources into the build dir so execute the following command. - -``` -ionic capacitor copy -``` - -To open your application to build/emulate in Android Studio or Xcode run the `open` command. - -``` -ionic capacitor open -``` - -## Related - -- [Ionic Documentation](https://ionicframework.com/docs/) -- [Ionic Forum](https://forum.ionicframework.com/) -- [Ionicons](http://ionicons.com/) -- [Capacitor](https://capacitor.ionicframework.com/) - -## License - -- [MIT](https://raw.githubusercontent.com/ionic-team/ionic/main/LICENSE) +This file has been moved to [/docs/react/README.md](/docs/react/README.md). diff --git a/packages/react/test/README.md b/packages/react/test/README.md index e0b8efa3712..a66ee32cff5 100644 --- a/packages/react/test/README.md +++ b/packages/react/test/README.md @@ -1,55 +1,3 @@ # React E2E Test Apps -Ionic Framework supports multiple versions of React. As a result, we need to verify that Ionic works correctly with each of these React versions. - -## Syncing Local Changes - -The React test app supports syncing your locally built changes for validation. - -1. Build the `core`, `packages/react`, and `packages/react-router` directories using `npm run build`. -2. [Build the React test app](#test-app-build-structure). -3. Navigate to the built test app. -4. Install dependencies using `npm install`. -5. Sync your local changes using `npm run sync`. - -From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. - -## Test App Build Structure - -Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. - -**apps** - This directory contains partial applications for each version of React we want to test. Typically these directories contain new `package.json` files, `cypress.config.ts` files, and more. If you have code that is specific to a particular version of React, put it in this directory. - -**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. - -**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. - -**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. - -Usage: - -```shell -# Build a test app using apps/react17 as a reference -./build.sh react17 -``` - -## How to modify test apps - -To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. - -If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/react17`, make sure you place the file in `apps/react17/tests/e2e/test.e2e.ts`. - -### Version-specific tests - -If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. - -## Adding New Test Apps - -As we add support for new versions of React, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: - -1. Navigate to the built app for the most recent version of React that Ionic tests. -2. Update the application to the latest version of React. -3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc). -4. Copy the changed files to a new directory in `apps`. -5. Add a new entry to the matrix for `test-react-e2e` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. -6. Commit these changes and push. +This file has been moved to [/docs/react/testing.md](/docs/react/testing.md). diff --git a/packages/react/test/base/README.md b/packages/react/test/base/README.md index 10e49c2b066..952ae866458 100644 --- a/packages/react/test/base/README.md +++ b/packages/react/test/base/README.md @@ -1,47 +1,3 @@ # React Test App -## Getting Started - -### Setup - -Make sure you are using the latest versions of node and npm. If you do not have these, [download the installer](https://nodejs.org/) for the LTS version of Node.js. This is the best way to also [install npm](https://blog.npmjs.org/post/85484771375/how-to-install-npm#_=_). - -### Building Dependencies - -Navigate to the `core`, `packages/react` and `packages/react-router` directories and build each of them: - -```bash -npm i -npm run build -``` - -Then, install dependencies from this directory for this test app: - -``` -npm i -``` - -### Syncing Changes - -When making changes to the React package, run the following from this directory to sync the changes: - -```bash -npm run sync -``` - -### Previewing App - -To preview this app locally, run the following from this directory: - -```bash -npm start -``` - -### Running Tests - -To run the e2e tests, run the following from this directory: - -``` -npm run build -npm run e2e -``` +This file has been moved to [/docs/react/testing2.md](/docs/react/testing2.md). diff --git a/packages/vue/README.md b/packages/vue/README.md index f1e964c6d78..6f44ffbeb3c 100644 --- a/packages/vue/README.md +++ b/packages/vue/README.md @@ -1,57 +1,3 @@ # @ionic/vue -Ionic Framework integration for Vue 3 apps. - -## Building - -1. Install dependencies in `@ionic/core`: - -```shell -cd core && npm install -``` - -2. Build `@ionic/core`. This will generate Vue component bindings in the `packages/vue` directory: - -```shell -npm run build -```` - -3. Install dependencies in `@ionic/vue`: - -```shell -cd packages/vue && npm install -``` - -4. Build `@ionic/vue`: - -```shell -npm run build -```` - -5. Install dependencies in `@ionic/vue-router`: - -```shell -cd packages/vue-router && npm install -``` - -6. Build `@ionic/vue-router`: - -```shell -npm run build -```` - -## Tests - -* E2E Tests are found in the `packages/vue/test/base/tests` directory and use Cypress. -* When making changes to `@ionic/vue` or `@ionic/vue-router` you can run `npm run sync` in the [test-app directory](test/README.md#syncing-local-changes) to ensure that the test application is using your built changes. Be sure to build in the `vue` and `vue-router` directories first. -* Tests can be run in headless mode by running `npm run cypress`. -* If you want to open the Cypress test runner, you can run `node_modules/.bin/cypress open`. -* Bug fix and feature PRs should have new tests verifying the PR functionality. - -## Contributing - -See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md). - -## Need Help? - -Post your question on the [Ionic Forum](http://forum.ionicframework.com/). +This file has been moved to [/docs/vue/README.md](/docs/vue/README.md). diff --git a/packages/vue/test/README.md b/packages/vue/test/README.md index b124b491e77..7531cde442b 100644 --- a/packages/vue/test/README.md +++ b/packages/vue/test/README.md @@ -1,58 +1,3 @@ # Vue E2E Test Apps -Ionic Framework supports multiple versions of Vue. As a result, we need to verify that Ionic works correctly with each of these Vue versions. - -## Syncing Local Changes - -The Vue test app supports syncing your locally built changes for validation. - -1. [Build](../README.md#building) the `core`, `packages/vue`, and `packages/vue-router` projects using `npm run build`. -2. [Build the Vue test app](#test-app-build-structure). -3. Navigate to the built test app directory (e.g. `packages/vue/test/build/vue3`). -4. Install dependencies using `npm install`. -5. Sync your local changes using `npm run sync`. - -From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. - -## Test App Build Structure - -> [!NOTE] -> Please confirm your current directory as `packages/vue/test` before proceeding with any of the following commands. - -Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. - -**apps** - This directory contains partial applications for each version of Vue we want to test. Typically these directories contain new `package.json` files, `jest.config.js` files, and more. If you have code that is specific to a particular version of Vue, put it in this directory. - -**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. - -**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. - -**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. - -Usage: - -```shell -# Build a test app using apps/vue3 as a reference -./build.sh vue3 -``` - -## How to modify test apps - -To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. - -If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/vue3`, make sure you place the file in `apps/vue3/tests/e2e/test.e2e.ts`. - -### Version-specific tests - -If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. - -## Adding New Test Apps - -As we add support for new versions of Vue, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: - -1. Navigate to the built app for the most recent version of Vue that Ionic tests. -2. Update the application to the latest version of Vue. -3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc). -4. Copy the changed files to a new directory in `apps`. -5. Add a new entry to the matrix for `test-core-vue` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. -6. Commit these changes and push. +This file has been moved to [/docs/vue/testing.md](/docs/vue/testing.md). From a0e09c1a303fd4aedeaaa6fd4ba4d836c8b49215 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Thu, 4 Apr 2024 15:59:20 -0400 Subject: [PATCH 04/16] chore(docs): move react and vue router docs to docs directory --- docs/README.md | 14 ++++--- docs/react-router/README.md | 2 + docs/react-router/testing.md | 55 ++++++++++++++++++++++++++++ docs/vue-router/README.md | 31 ++++++++++++++++ packages/react-router/README.md | 3 +- packages/react-router/test/README.md | 54 +-------------------------- packages/vue-router/README.md | 30 +-------------- 7 files changed, 100 insertions(+), 89 deletions(-) create mode 100644 docs/react-router/README.md create mode 100644 docs/react-router/testing.md create mode 100644 docs/vue-router/README.md diff --git a/docs/README.md b/docs/README.md index 71d2d36df22..486fbc0e1e2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -26,9 +26,11 @@ It is based on Web Componen ## Packages -| Project | Package | Documentation | Guides | -| ----------- | ---------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------- | -| **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Scripts](core/scripts.md) | -| **Angular** | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular) | [Readme](angular/README.md) | [Testing](angular/testing.md) | -| **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [Readme](vue/README.md) | [Testing](vue/testing.md) | -| **React** | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react) | [Readme](react/README.md) | [Testing](react/testing.md) โ€ข [Testing Part 2](react/testing2.md) | +| Project | Package | Documentation | Guides | +| ---------------- | -------------------------------------------------------------------------- | ---------------------------------| ----------------------------------------------------------------- | +| **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Scripts](core/scripts.md) | +| **Angular** | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular) | [Readme](angular/README.md) | [Testing](angular/testing.md) | +| **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [Readme](vue/README.md) | [Testing](vue/testing.md) | +| **Vue Router** | [`@ionic/vue-router`](https://www.npmjs.com/package/@ionic/vue-router) | [Readme](vue-router/README.md) | | +| **React** | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react) | [Readme](react/README.md) | [Testing](react/testing.md) โ€ข [Testing Part 2](react/testing2.md) | +| **React Router** | [`@ionic/react-router`](https://www.npmjs.com/package/@ionic/react-router) | [Readme](react-router/README.md) | [Testing](react-router/testing.md) | diff --git a/docs/react-router/README.md b/docs/react-router/README.md new file mode 100644 index 00000000000..2f48cca4045 --- /dev/null +++ b/docs/react-router/README.md @@ -0,0 +1,2 @@ +# @ionic/react-router + diff --git a/docs/react-router/testing.md b/docs/react-router/testing.md new file mode 100644 index 00000000000..22e912cedb1 --- /dev/null +++ b/docs/react-router/testing.md @@ -0,0 +1,55 @@ +# React Router E2E Test Apps + +Ionic Framework supports multiple versions of React Router. As a result, we need to verify that Ionic works correctly with each of these React Router versions. + +## Syncing Local Changes + +The React test app supports syncing your locally built changes for validation. + +1. Build the `@ionic/core`, `@ionic/react`, and `@ionic/react-router` projects using `npm run build`. +2. [Build the React test app](#test-app-build-structure). +3. Navigate to the built test app. +4. Install dependencies using `npm install`. +5. Sync your local changes using `npm run sync`. + +From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. + +## Test App Build Structure + +Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. + +**apps** - This directory contains partial applications for each version of React we want to test. Typically these directories contain new `package.json` files, `cypress.config.ts` files, and more. If you have code that is specific to a particular version of React, put it in this directory. + +**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. + +**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. + +**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. + +Usage: + +```shell +# Build a test app using apps/reactrouter5 as a reference +./build.sh reactrouter5 +``` + +## How to modify test apps + +To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. + +If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/reactrouter5`, make sure you place the file in `apps/react17/tests/e2e/test.e2e.ts`. + +### Version-specific tests + +If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. + +## Adding New Test Apps + +As we add support for new versions of React Router, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: + +1. Navigate to the built app for the most recent version of React Router that Ionic tests. +2. Update the application to the latest version of React Router. +3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc). +4. Copy the changed files to a new directory in `apps`. +5. Add a new entry to the matrix for `test-react-router-e2e` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. +6. Commit these changes and push. diff --git a/docs/vue-router/README.md b/docs/vue-router/README.md new file mode 100644 index 00000000000..6dcdd7d267b --- /dev/null +++ b/docs/vue-router/README.md @@ -0,0 +1,31 @@ +# @ionic/vue-router + +Routing integration for `@ionic/vue` applications. + +## Building + +1. Install dependencies: + +```shell +npm install +``` + +2. Run build script: + +```shell +npm run build +```` + +## Tests + +* Tests are found in the `__tests__` directory and use Jest. +* Tests can be run using `npm run test.spec` +* Bug fix and feature PRs should have new tests verifying the PR functionality. + +## Contributing + +See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md). + +## Need Help? + +Post your question on the [Ionic Forum](http://forum.ionicframework.com/). diff --git a/packages/react-router/README.md b/packages/react-router/README.md index 3f723796c6e..db07d45c19c 100644 --- a/packages/react-router/README.md +++ b/packages/react-router/README.md @@ -1,2 +1,3 @@ -## @ionic/react-router (beta) +# @ionic/react-router +This file has been moved to [/docs/react-router/README.md](/docs/react-router/README.md). diff --git a/packages/react-router/test/README.md b/packages/react-router/test/README.md index 22e912cedb1..1a98e97e5fa 100644 --- a/packages/react-router/test/README.md +++ b/packages/react-router/test/README.md @@ -1,55 +1,3 @@ # React Router E2E Test Apps -Ionic Framework supports multiple versions of React Router. As a result, we need to verify that Ionic works correctly with each of these React Router versions. - -## Syncing Local Changes - -The React test app supports syncing your locally built changes for validation. - -1. Build the `@ionic/core`, `@ionic/react`, and `@ionic/react-router` projects using `npm run build`. -2. [Build the React test app](#test-app-build-structure). -3. Navigate to the built test app. -4. Install dependencies using `npm install`. -5. Sync your local changes using `npm run sync`. - -From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build. - -## Test App Build Structure - -Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application. - -**apps** - This directory contains partial applications for each version of React we want to test. Typically these directories contain new `package.json` files, `cypress.config.ts` files, and more. If you have code that is specific to a particular version of React, put it in this directory. - -**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory. - -**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git. - -**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory. - -Usage: - -```shell -# Build a test app using apps/reactrouter5 as a reference -./build.sh reactrouter5 -``` - -## How to modify test apps - -To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version. - -If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/reactrouter5`, make sure you place the file in `apps/react17/tests/e2e/test.e2e.ts`. - -### Version-specific tests - -If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. - -## Adding New Test Apps - -As we add support for new versions of React Router, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: - -1. Navigate to the built app for the most recent version of React Router that Ionic tests. -2. Update the application to the latest version of React Router. -3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc). -4. Copy the changed files to a new directory in `apps`. -5. Add a new entry to the matrix for `test-react-router-e2e` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs. -6. Commit these changes and push. +This file has been moved to [/docs/react-router/testing.md](/docs/react-router/testing.md). diff --git a/packages/vue-router/README.md b/packages/vue-router/README.md index 6dcdd7d267b..110406c2459 100644 --- a/packages/vue-router/README.md +++ b/packages/vue-router/README.md @@ -1,31 +1,3 @@ # @ionic/vue-router -Routing integration for `@ionic/vue` applications. - -## Building - -1. Install dependencies: - -```shell -npm install -``` - -2. Run build script: - -```shell -npm run build -```` - -## Tests - -* Tests are found in the `__tests__` directory and use Jest. -* Tests can be run using `npm run test.spec` -* Bug fix and feature PRs should have new tests verifying the PR functionality. - -## Contributing - -See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md). - -## Need Help? - -Post your question on the [Ionic Forum](http://forum.ionicframework.com/). +This file has been moved to [/docs/vue-router/README.md](/docs/vue-router/README.md). From f99d0af9df8e4990fddf6acc083240150d2e590a Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Thu, 4 Apr 2024 16:42:29 -0400 Subject: [PATCH 05/16] git: revert changes to npm package readmes --- core/README.md | 112 +++++++++++++++++++++++++++++++- packages/angular/README.md | 73 ++++++++++++++++++++- packages/react-router/README.md | 1 - packages/react/README.md | 48 +++++++++++++- packages/vue-router/README.md | 30 ++++++++- packages/vue/README.md | 56 +++++++++++++++- 6 files changed, 314 insertions(+), 6 deletions(-) diff --git a/core/README.md b/core/README.md index 7dd2f861817..23dbfc1c2fe 100644 --- a/core/README.md +++ b/core/README.md @@ -1,3 +1,113 @@ # @ionic/core -This file has been moved to [/docs/core/README.md](/docs/core/README.md). +[Ionic](https://ionicframework.com/) is an open source App Development Framework that makes it easy to build top quality Native and Progressive Web Apps with web technologies. + +The Ionic Core package contains the Web Components that make up the reusable UI building blocks of Ionic Framework. These components are designed to be used in traditional frontend view libraries/frameworks (such as [Stencil](https://stenciljs.com/), React, Angular, or Vue), or on their own through traditional JavaScript in the browser. + + +## Features + +* Tiny, highly optimized components built with [Stencil](https://stenciljs.com/) +* Styling for both iOS and Material Design +* No build or compiling required +* Simply add the static files to any project +* Lazy-loaded components without configuration +* Asynchronous rendering +* Theming through CSS Variables + + +## How to use + +### Vanilla HTML + +Easiest way to start using Ionic Core is by adding a script tag to the CDN: + +```html + + + +``` + +Any Ionic component added to the webpage will automatically load. This includes writing the component tag directly in HTML, or using JavaScript such as `document.createElement('ion-toggle')`. + +Additionally, within this package is a `dist/ionic.js` file and accompanying `dist/ionic/` directory. These are the same files which are used by the CDN, and they're available in this package so they can be apart of an app's local development. + + +## Framework Bindings + +The `@ionic/core` package can be used in simple HTML, or by vanilla JavaScript without any framework at all. Ionic also has packages that make it easier to integrate Ionic into a framework's traditional ecosystem and patterns. (However, at the lowest-level framework bindings are still just using Ionic Core and Web Components). + +* [@ionic/angular](https://www.npmjs.com/package/@ionic/angular) + + +## Custom Elements Build + +In addition to the default, self lazy-loading components built by Stencil, this package also comes with each component exported as a stand-alone custom element within `@ionic/core/components`. Each component extends `HTMLElement`, and does not lazy-load itself. Instead, this package is useful for projects already using a bundler such as Webpack or Rollup. While all components are available to be imported, the custom elements build also ensures bundlers only import what's used, and tree-shakes any unused components. + +Below is an example of importing `ion-badge`, and initializing Ionic so it is able to correctly load the "mode", such as Material Design or iOS. Additionally, the `initialize({...})` function can receive the Ionic config. + +```typescript +import { defineCustomElement } from "@ionic/core/components/ion-badge.js"; +import { initialize } from "@ionic/core/components"; + +// Initializes the Ionic config and `mode` behavior +initialize(); + +// Defines the `ion-badge` web component +defineCustomElement(); +``` + +Notice how we import from `@ionic/core/components` as opposed to `@ionic/core`. This helps bundlers pull in only the code that is needed. + +The `defineCustomElement` function will automatically define the component as well as any child components that may be required. + +For example, if you wanted to use `ion-modal`, you would do the following: + +```typescript +import { defineCustomElement } from "@ionic/core/components/ion-modal.js"; +import { initialize } from "@ionic/core/components"; + +// Initializes the Ionic config and `mode` behavior +initialize(); + +// Defines the `ion-modal` and child `ion-backdrop` web components. +defineCustomElement(); +``` + +The `defineCustomElement` function will define `ion-modal`, but it will also define `ion-backdrop`, which is a component that `ion-modal` uses internally. + +### Using Overlay Controllers + +When using an overlay controller, developers will need to define the overlay component before it can be used. Below is an example of using `modalController`: + +```typescript +import { defineCustomElement } from '@ionic/core/components/ion-modal.js'; +import { initialize, modalController } from '@ionic/core/components'; + +initialize(); +defineCustomElement(); + +const showModal = async () => { + const modal = await modalController.create({ ... }); + + ... +} +``` + +## How to contribute + +[Check out the CONTRIBUTE guide](/.github/CONTRIBUTING.md) + +## Related + +* [Ionic Documentation](https://ionicframework.com/docs/) +* [Ionic Discord](https://ionic.link/discord) +* [Ionic Forum](https://forum.ionicframework.com/) +* [Ionicons](http://ionicons.com/) +* [Stencil](https://stenciljs.com/) +* [Capacitor](https://capacitor.ionicframework.com/) + + +## License + +* [MIT](https://raw.githubusercontent.com/ionic-team/ionic/master/LICENSE) diff --git a/packages/angular/README.md b/packages/angular/README.md index b65d0a7c725..0a1b2c488d7 100644 --- a/packages/angular/README.md +++ b/packages/angular/README.md @@ -1,3 +1,74 @@ # @ionic/angular -This file has been moved to [/docs/angular/README.md](/docs/angular/README.md). +Ionic Angular specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components. + + +## Related + +* [Ionic Core Components](https://www.npmjs.com/package/@ionic/core) +* [Ionic Documentation](https://ionicframework.com/docs/) +* [Ionic Discord](https://ionic.link/discord) +* [Ionic Forum](https://forum.ionicframework.com/) +* [Ionicons](http://ionicons.com/) +* [Stencil](https://stenciljs.com/) +* [Capacitor](https://capacitor.ionicframework.com/) + + +## License + +* [MIT](https://raw.githubusercontent.com/ionic-team/ionic/main/LICENSE) + +## Testing ng-add in ionic + +1. Pull the latest from `main` +2. Build ionic/angular: `npm run build` +3. Run `npm link` from `ionic/angular/dist` directory +4. Create a blank angular project + +``` +ng new add-test +// Say yes to including the router, we need it +cd add-test +``` + +5. To run schematics locally, we need the schematics-cli (once published, this will not be needed) + +``` +npm install @angular-devkit/schematics-cli +``` + +6. Link `@ionic/angular` + +``` +npm link @ionic/angular +``` + + +7. Run the local copy of the ng-add schematic + +``` +$ npx schematics @ionic/angular:ng-add +``` + + +You'll now be able to add ionic components to a vanilla Angular app setup. + +## Project Structure + +**common** + +This is where logic that is shared between lazy loaded and standalone components live. For example, the lazy loaded IonPopover and standalone IonPopover components extend from a base IonPopover implementation that exists in this directory. + +**Note:** This directory exposes internal APIs and is only accessed in the `standalone` and `src` submodules. Ionic developers should never import directly from `@ionic/angular/common`. Instead, they should import from `@ionic/angular` or `@ionic/angular/standalone`. + +**standalone** + +This is where the standalone component implementations live. It was added as a separate entry point to avoid any lazy loaded logic from accidentally being pulled in to the final build. Having a separate directory allows the lazy loaded implementation to remain accessible from `@ionic/angular` for backwards compatibility. + +Ionic developers can access this by importing from `@ionic/angular/standalone`. + +**src** + +This is where the lazy loaded component implementations live. + +Ionic developers can access this by importing from `@ionic/angular`. diff --git a/packages/react-router/README.md b/packages/react-router/README.md index db07d45c19c..2f48cca4045 100644 --- a/packages/react-router/README.md +++ b/packages/react-router/README.md @@ -1,3 +1,2 @@ # @ionic/react-router -This file has been moved to [/docs/react-router/README.md](/docs/react-router/README.md). diff --git a/packages/react/README.md b/packages/react/README.md index e3c9b85c9a6..9cba7b48648 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -1,3 +1,49 @@ # @ionic/react -This file has been moved to [/docs/react/README.md](/docs/react/README.md). +These are React specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components/services. + +To get started, install the Ionic CLI by running `npm i -g @ionic/cli`. Then, start a new Ionic React Project by running `ionic start myapp --type=react`. + +## Publishing a Native Application + +You can now make use of all of the ionic components in your React application. +If you want to publish your app to the App Store or Google Play you will need to use the ionic cli to execute Capacitor commands to do so. + +More information on this can be found here. https://ionicframework.com/docs/cli +If you want to learn more about Capacitor our dedicated site can be found here. https://capacitor.ionicframework.com/ + +The commands that you will need to execute are below in your project's root. + +```sh +ionic init "My React App" --type=react +ionic integrations enable capacitor +``` + +Then run the following command to get started with either `ios` or `android` platforms. + +``` +ionic capacitor add +``` + +After build you build your app you will need to copy your capacitor resources into the build dir so execute the following command. + +``` +ionic capacitor copy +``` + +To open your application to build/emulate in Android Studio or Xcode run the `open` command. + +``` +ionic capacitor open +``` + +## Related + +- [Ionic Documentation](https://ionicframework.com/docs/) +- [Ionic Forum](https://forum.ionicframework.com/) +- [Ionicons](http://ionicons.com/) +- [Capacitor](https://capacitor.ionicframework.com/) + +## License + +- [MIT](https://raw.githubusercontent.com/ionic-team/ionic/main/LICENSE) diff --git a/packages/vue-router/README.md b/packages/vue-router/README.md index 110406c2459..83cc23717bb 100644 --- a/packages/vue-router/README.md +++ b/packages/vue-router/README.md @@ -1,3 +1,31 @@ # @ionic/vue-router -This file has been moved to [/docs/vue-router/README.md](/docs/vue-router/README.md). +Routing integration for `@ionic/vue` applications. + +## Building + +1. Install dependencies: + +```shell +npm install +``` + +2. Run build script: + +```shell +npm run build +```` + +## Tests + +* Tests are found in the `__tests__` directory and use Jest. +* Tests can be run using `npm run test.spec` +* Bug fix and feature PRs should have new tests verifying the PR functionality. + +## Contributing + +See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md). + +## Need Help? + +Post your question on the [Ionic Forum](http://forum.ionicframework.com/). \ No newline at end of file diff --git a/packages/vue/README.md b/packages/vue/README.md index 6f44ffbeb3c..2bd35bf6b0b 100644 --- a/packages/vue/README.md +++ b/packages/vue/README.md @@ -1,3 +1,57 @@ # @ionic/vue -This file has been moved to [/docs/vue/README.md](/docs/vue/README.md). +Ionic Framework integration for Vue 3 apps. + +## Building + +1. Install dependencies in `@ionic/core`: + +```shell +cd core && npm install +``` + +2. Build `@ionic/core`. This will generate Vue component bindings in the `packages/vue` directory: + +```shell +npm run build +```` + +3. Install dependencies in `@ionic/vue`: + +```shell +cd packages/vue && npm install +``` + +4. Build `@ionic/vue`: + +```shell +npm run build +```` + +5. Install dependencies in `@ionic/vue-router`: + +```shell +cd packages/vue-router && npm install +``` + +6. Build `@ionic/vue-router`: + +```shell +npm run build +```` + +## Tests + +* E2E Tests are found in the `packages/vue/test/base/tests` directory and use Cypress. +* When making changes to `@ionic/vue` or `@ionic/vue-router` you can run `npm run sync` in the [test-app directory](test/README.md#syncing-local-changes) to ensure that the test application is using your built changes. Be sure to build in the `vue` and `vue-router` directories first. +* Tests can be run in headless mode by running `npm run cypress`. +* If you want to open the Cypress test runner, you can run `node_modules/.bin/cypress open`. +* Bug fix and feature PRs should have new tests verifying the PR functionality. + +## Contributing + +See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md). + +## Need Help? + +Post your question on the [Ionic Forum](http://forum.ionicframework.com/). From 9d53c4b930cf1ec0c531dddfbd70ddb78ecd7290 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Thu, 4 Apr 2024 16:46:12 -0400 Subject: [PATCH 06/16] copy editing --- packages/angular/test/README.md | 2 +- packages/react-router/test/README.md | 2 +- packages/react/test/README.md | 2 +- packages/react/test/base/README.md | 2 +- packages/vue/test/README.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/angular/test/README.md b/packages/angular/test/README.md index 26bc797495e..e761e146219 100644 --- a/packages/angular/test/README.md +++ b/packages/angular/test/README.md @@ -1,3 +1,3 @@ # Angular E2E Test Apps -This file has been moved to [/docs/angular/testing.md](/docs/angular/testing.md). +Refer to the [Angular Testing documentation](/docs/angular/testing.md) in order to build and run the test app. diff --git a/packages/react-router/test/README.md b/packages/react-router/test/README.md index 1a98e97e5fa..d072e40617e 100644 --- a/packages/react-router/test/README.md +++ b/packages/react-router/test/README.md @@ -1,3 +1,3 @@ # React Router E2E Test Apps -This file has been moved to [/docs/react-router/testing.md](/docs/react-router/testing.md). +Refer to the [React Router Testing documentation](/docs/react-router/testing.md) in order to build and run the test app. diff --git a/packages/react/test/README.md b/packages/react/test/README.md index a66ee32cff5..b398f18b65d 100644 --- a/packages/react/test/README.md +++ b/packages/react/test/README.md @@ -1,3 +1,3 @@ # React E2E Test Apps -This file has been moved to [/docs/react/testing.md](/docs/react/testing.md). +Refer to the [React Testing documentation](/docs/react/testing.md) in order to build and run the test app. diff --git a/packages/react/test/base/README.md b/packages/react/test/base/README.md index 952ae866458..5bb410e3c47 100644 --- a/packages/react/test/base/README.md +++ b/packages/react/test/base/README.md @@ -1,3 +1,3 @@ # React Test App -This file has been moved to [/docs/react/testing2.md](/docs/react/testing2.md). +Refer to the [React Testing documentation](/docs/react/testing2.md) in order to build and run the test app. diff --git a/packages/vue/test/README.md b/packages/vue/test/README.md index 7531cde442b..5db04476a52 100644 --- a/packages/vue/test/README.md +++ b/packages/vue/test/README.md @@ -1,3 +1,3 @@ # Vue E2E Test Apps -This file has been moved to [/docs/vue/testing.md](/docs/vue/testing.md). +Refer to the [Vue Testing documentation](/docs/vue/testing.md) in order to build and run the test app. From 5d1407c6f2df68aff61dede03fa341132295cc46 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Thu, 4 Apr 2024 17:24:05 -0400 Subject: [PATCH 07/16] chore(docs): update package readme and test files --- core/scripts/readme.md | 2 +- docs/README.md | 6 +- docs/angular/README.md | 75 ++---------------- docs/angular/testing.md | 2 +- docs/core/README.md | 114 ++------------------------- docs/core/{scripts.md => testing.md} | 22 +----- docs/react-router/README.md | 11 ++- docs/react-router/testing.md | 2 +- docs/react/README.md | 50 ++---------- docs/react/testing.md | 2 +- docs/react/testing2.md | 47 ----------- docs/vue-router/README.md | 30 ++----- docs/vue-router/testing.md | 9 +++ docs/vue/README.md | 56 ++----------- docs/vue/testing.md | 2 +- packages/react/test/base/README.md | 2 +- 16 files changed, 59 insertions(+), 373 deletions(-) rename docs/core/{scripts.md => testing.md} (61%) delete mode 100644 docs/react/testing2.md create mode 100644 docs/vue-router/testing.md diff --git a/core/scripts/readme.md b/core/scripts/readme.md index d1560e15422..2c2055179d7 100644 --- a/core/scripts/readme.md +++ b/core/scripts/readme.md @@ -1,4 +1,4 @@ # Core Scripts -This file has been moved to [/docs/core/scripts.md](/docs/core/scripts.md). +This file has been moved to [/docs/core/testing.md](/docs/core/testing.md). diff --git a/docs/README.md b/docs/README.md index 486fbc0e1e2..b500583616e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -28,9 +28,9 @@ It is based on Web Componen | Project | Package | Documentation | Guides | | ---------------- | -------------------------------------------------------------------------- | ---------------------------------| ----------------------------------------------------------------- | -| **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Scripts](core/scripts.md) | +| **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Testing](core/testing.md) | | **Angular** | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular) | [Readme](angular/README.md) | [Testing](angular/testing.md) | | **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [Readme](vue/README.md) | [Testing](vue/testing.md) | -| **Vue Router** | [`@ionic/vue-router`](https://www.npmjs.com/package/@ionic/vue-router) | [Readme](vue-router/README.md) | | -| **React** | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react) | [Readme](react/README.md) | [Testing](react/testing.md) โ€ข [Testing Part 2](react/testing2.md) | +| **Vue Router** | [`@ionic/vue-router`](https://www.npmjs.com/package/@ionic/vue-router) | [Readme](vue-router/README.md) | [Testing](vue-router/testing.md) | +| **React** | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react) | [Readme](react/README.md) | [Testing](react/testing.md) | | **React Router** | [`@ionic/react-router`](https://www.npmjs.com/package/@ionic/react-router) | [Readme](react-router/README.md) | [Testing](react-router/testing.md) | diff --git a/docs/angular/README.md b/docs/angular/README.md index 0a1b2c488d7..357afb4123f 100644 --- a/docs/angular/README.md +++ b/docs/angular/README.md @@ -1,74 +1,11 @@ -# @ionic/angular +# Ionic Angular -Ionic Angular specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components. +The [@ionic/angular](https://www.npmjs.com/package/@ionic/angular) package builds on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components. +## Contributing -## Related +See our [Contributing Guide](/docs/CONTRIBUTING.md). -* [Ionic Core Components](https://www.npmjs.com/package/@ionic/core) -* [Ionic Documentation](https://ionicframework.com/docs/) -* [Ionic Discord](https://ionic.link/discord) -* [Ionic Forum](https://forum.ionicframework.com/) -* [Ionicons](http://ionicons.com/) -* [Stencil](https://stenciljs.com/) -* [Capacitor](https://capacitor.ionicframework.com/) +## Testing - -## License - -* [MIT](https://raw.githubusercontent.com/ionic-team/ionic/main/LICENSE) - -## Testing ng-add in ionic - -1. Pull the latest from `main` -2. Build ionic/angular: `npm run build` -3. Run `npm link` from `ionic/angular/dist` directory -4. Create a blank angular project - -``` -ng new add-test -// Say yes to including the router, we need it -cd add-test -``` - -5. To run schematics locally, we need the schematics-cli (once published, this will not be needed) - -``` -npm install @angular-devkit/schematics-cli -``` - -6. Link `@ionic/angular` - -``` -npm link @ionic/angular -``` - - -7. Run the local copy of the ng-add schematic - -``` -$ npx schematics @ionic/angular:ng-add -``` - - -You'll now be able to add ionic components to a vanilla Angular app setup. - -## Project Structure - -**common** - -This is where logic that is shared between lazy loaded and standalone components live. For example, the lazy loaded IonPopover and standalone IonPopover components extend from a base IonPopover implementation that exists in this directory. - -**Note:** This directory exposes internal APIs and is only accessed in the `standalone` and `src` submodules. Ionic developers should never import directly from `@ionic/angular/common`. Instead, they should import from `@ionic/angular` or `@ionic/angular/standalone`. - -**standalone** - -This is where the standalone component implementations live. It was added as a separate entry point to avoid any lazy loaded logic from accidentally being pulled in to the final build. Having a separate directory allows the lazy loaded implementation to remain accessible from `@ionic/angular` for backwards compatibility. - -Ionic developers can access this by importing from `@ionic/angular/standalone`. - -**src** - -This is where the lazy loaded component implementations live. - -Ionic developers can access this by importing from `@ionic/angular`. +Refer to the [Angular Testing documentation](./testing.md) for testing the Angular package. diff --git a/docs/angular/testing.md b/docs/angular/testing.md index b2e56ef2ee4..dee9678da74 100644 --- a/docs/angular/testing.md +++ b/docs/angular/testing.md @@ -1,4 +1,4 @@ -# Angular E2E Test Apps +# Angular Testing Ionic Framework supports multiple versions of Angular. As a result, we need to verify that Ionic works correctly with each of these Angular versions. diff --git a/docs/core/README.md b/docs/core/README.md index 3132e38c401..5dad809d488 100644 --- a/docs/core/README.md +++ b/docs/core/README.md @@ -1,113 +1,11 @@ -# @ionic/core +# Ionic Core -[Ionic](https://ionicframework.com/) is an open source App Development Framework that makes it easy to build top quality Native and Progressive Web Apps with web technologies. +The [@ionic/core](https://www.npmjs.com/package/@ionic/core) package contains the Web Components that make up the reusable UI building blocks of Ionic Framework. These components are designed to be used in traditional frontend view libraries/frameworks (such as React, Angular, or Vue), or on their own through traditional JavaScript in the browser. -The Ionic Core package contains the Web Components that make up the reusable UI building blocks of Ionic Framework. These components are designed to be used in traditional frontend view libraries/frameworks (such as [Stencil](https://stenciljs.com/), React, Angular, or Vue), or on their own through traditional JavaScript in the browser. +## Contributing +See our [Contributing Guide](/docs/CONTRIBUTING.md). -## Features +## Testing -* Tiny, highly optimized components built with [Stencil](https://stenciljs.com/) -* Styling for both iOS and Material Design -* No build or compiling required -* Simply add the static files to any project -* Lazy-loaded components without configuration -* Asynchronous rendering -* Theming through CSS Variables - - -## How to use - -### Vanilla HTML - -Easiest way to start using Ionic Core is by adding a script tag to the CDN: - -```html - - - -``` - -Any Ionic component added to the webpage will automatically load. This includes writing the component tag directly in HTML, or using JavaScript such as `document.createElement('ion-toggle')`. - -Additionally, within this package is a `dist/ionic.js` file and accompanying `dist/ionic/` directory. These are the same files which are used by the CDN, and they're available in this package so they can be apart of an app's local development. - - -## Framework Bindings - -The `@ionic/core` package can be used in simple HTML, or by vanilla JavaScript without any framework at all. Ionic also has packages that make it easier to integrate Ionic into a framework's traditional ecosystem and patterns. (However, at the lowest-level framework bindings are still just using Ionic Core and Web Components). - -* [@ionic/angular](https://www.npmjs.com/package/@ionic/angular) - - -## Custom Elements Build - -In addition to the default, self lazy-loading components built by Stencil, this package also comes with each component exported as a stand-alone custom element within `@ionic/core/components`. Each component extends `HTMLElement`, and does not lazy-load itself. Instead, this package is useful for projects already using a bundler such as Webpack or Rollup. While all components are available to be imported, the custom elements build also ensures bundlers only import what's used, and tree-shakes any unused components. - -Below is an example of importing `ion-badge`, and initializing Ionic so it is able to correctly load the "mode", such as Material Design or iOS. Additionally, the `initialize({...})` function can receive the Ionic config. - -```typescript -import { defineCustomElement } from "@ionic/core/components/ion-badge.js"; -import { initialize } from "@ionic/core/components"; - -// Initializes the Ionic config and `mode` behavior -initialize(); - -// Defines the `ion-badge` web component -defineCustomElement(); -``` - -Notice how we import from `@ionic/core/components` as opposed to `@ionic/core`. This helps bundlers pull in only the code that is needed. - -The `defineCustomElement` function will automatically define the component as well as any child components that may be required. - -For example, if you wanted to use `ion-modal`, you would do the following: - -```typescript -import { defineCustomElement } from "@ionic/core/components/ion-modal.js"; -import { initialize } from "@ionic/core/components"; - -// Initializes the Ionic config and `mode` behavior -initialize(); - -// Defines the `ion-modal` and child `ion-backdrop` web components. -defineCustomElement(); -``` - -The `defineCustomElement` function will define `ion-modal`, but it will also define `ion-backdrop`, which is a component that `ion-modal` uses internally. - -### Using Overlay Controllers - -When using an overlay controller, developers will need to define the overlay component before it can be used. Below is an example of using `modalController`: - -```typescript -import { defineCustomElement } from '@ionic/core/components/ion-modal.js'; -import { initialize, modalController } from '@ionic/core/components'; - -initialize(); -defineCustomElement(); - -const showModal = async () => { - const modal = await modalController.create({ ... }); - - ... -} -``` - -## How to contribute - -[Check out the CONTRIBUTE guide](/docs/CONTRIBUTING.md) - -## Related - -* [Ionic Documentation](https://ionicframework.com/docs/) -* [Ionic Discord](https://ionic.link/discord) -* [Ionic Forum](https://forum.ionicframework.com/) -* [Ionicons](http://ionicons.com/) -* [Stencil](https://stenciljs.com/) -* [Capacitor](https://capacitor.ionicframework.com/) - - -## License - -* [MIT](https://raw.githubusercontent.com/ionic-team/ionic/master/LICENSE) +Refer to the [Core Testing documentation](./testing.md) for testing the Core package. diff --git a/docs/core/scripts.md b/docs/core/testing.md similarity index 61% rename from docs/core/scripts.md rename to docs/core/testing.md index a4feb9a05ea..c36e4f5ae48 100644 --- a/docs/core/scripts.md +++ b/docs/core/testing.md @@ -1,5 +1,5 @@ -# Core Scripts +# Core Testing ## Build @@ -10,9 +10,8 @@ ### 2. Run `npm install` - cd core - npm install - + cd core + npm install Notice that `@ionic/core` lives in `core`. @@ -29,18 +28,3 @@ With the `dev` command, Ionic components will be built with [Stencil](https://st Navigate to http://localhost:3333/src/components/. Each component has small e2e apps found in the `test` directory, for example: http://localhost:3333/src/components/button/test/basic As changes are made in an editor to source files, the e2e app will live-reload. - -## How to contribute - -1. `npm start` allows you to modify the components and have live reloading, just like another ionic app. - -2. When everything looks good, run `npm run validate` to verify the tests linter and production build passes. - - -# Deploy - -1. `npm run prepare.deploy` -2. Review/update changelog -3. Commit updates using the package name and version number as the commit message. -4. `npm run deploy` -5. :tada: diff --git a/docs/react-router/README.md b/docs/react-router/README.md index 2f48cca4045..4ef96223a68 100644 --- a/docs/react-router/README.md +++ b/docs/react-router/README.md @@ -1,2 +1,11 @@ -# @ionic/react-router +# Ionic React Router +The [@ionic/react-router](https://www.npmjs.com/package/@ionic/react-router) package is the routing integration for [@ionic/react](https://www.npmjs.com/package/@ionic/react). It uses the [React Router](https://github.com/remix-run/react-router) library beneath the surface. + +## Contributing + +See our [Contributing Guide](/docs/CONTRIBUTING.md). + +## Testing + +Refer to the [React Router Testing documentation](./testing.md) for testing the React Router package. diff --git a/docs/react-router/testing.md b/docs/react-router/testing.md index 22e912cedb1..d0dd1f49446 100644 --- a/docs/react-router/testing.md +++ b/docs/react-router/testing.md @@ -1,4 +1,4 @@ -# React Router E2E Test Apps +# React Router Testing Ionic Framework supports multiple versions of React Router. As a result, we need to verify that Ionic works correctly with each of these React Router versions. diff --git a/docs/react/README.md b/docs/react/README.md index 9cba7b48648..12d33523d8c 100644 --- a/docs/react/README.md +++ b/docs/react/README.md @@ -1,49 +1,11 @@ -# @ionic/react +# Ionic React -These are React specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components/services. +The [@ionic/react](https://www.npmjs.com/package/@ionic/react) package builds on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components. -To get started, install the Ionic CLI by running `npm i -g @ionic/cli`. Then, start a new Ionic React Project by running `ionic start myapp --type=react`. +## Contributing -## Publishing a Native Application +See our [Contributing Guide](/docs/CONTRIBUTING.md). -You can now make use of all of the ionic components in your React application. -If you want to publish your app to the App Store or Google Play you will need to use the ionic cli to execute Capacitor commands to do so. +## Testing -More information on this can be found here. https://ionicframework.com/docs/cli -If you want to learn more about Capacitor our dedicated site can be found here. https://capacitor.ionicframework.com/ - -The commands that you will need to execute are below in your project's root. - -```sh -ionic init "My React App" --type=react -ionic integrations enable capacitor -``` - -Then run the following command to get started with either `ios` or `android` platforms. - -``` -ionic capacitor add -``` - -After build you build your app you will need to copy your capacitor resources into the build dir so execute the following command. - -``` -ionic capacitor copy -``` - -To open your application to build/emulate in Android Studio or Xcode run the `open` command. - -``` -ionic capacitor open -``` - -## Related - -- [Ionic Documentation](https://ionicframework.com/docs/) -- [Ionic Forum](https://forum.ionicframework.com/) -- [Ionicons](http://ionicons.com/) -- [Capacitor](https://capacitor.ionicframework.com/) - -## License - -- [MIT](https://raw.githubusercontent.com/ionic-team/ionic/main/LICENSE) +Refer to the [React Testing documentation](./testing.md) for testing the React package. diff --git a/docs/react/testing.md b/docs/react/testing.md index e0b8efa3712..1c9da9c6829 100644 --- a/docs/react/testing.md +++ b/docs/react/testing.md @@ -1,4 +1,4 @@ -# React E2E Test Apps +# React Testing Ionic Framework supports multiple versions of React. As a result, we need to verify that Ionic works correctly with each of these React versions. diff --git a/docs/react/testing2.md b/docs/react/testing2.md deleted file mode 100644 index 10e49c2b066..00000000000 --- a/docs/react/testing2.md +++ /dev/null @@ -1,47 +0,0 @@ -# React Test App - -## Getting Started - -### Setup - -Make sure you are using the latest versions of node and npm. If you do not have these, [download the installer](https://nodejs.org/) for the LTS version of Node.js. This is the best way to also [install npm](https://blog.npmjs.org/post/85484771375/how-to-install-npm#_=_). - -### Building Dependencies - -Navigate to the `core`, `packages/react` and `packages/react-router` directories and build each of them: - -```bash -npm i -npm run build -``` - -Then, install dependencies from this directory for this test app: - -``` -npm i -``` - -### Syncing Changes - -When making changes to the React package, run the following from this directory to sync the changes: - -```bash -npm run sync -``` - -### Previewing App - -To preview this app locally, run the following from this directory: - -```bash -npm start -``` - -### Running Tests - -To run the e2e tests, run the following from this directory: - -``` -npm run build -npm run e2e -``` diff --git a/docs/vue-router/README.md b/docs/vue-router/README.md index 6dcdd7d267b..28494eda927 100644 --- a/docs/vue-router/README.md +++ b/docs/vue-router/README.md @@ -1,31 +1,11 @@ -# @ionic/vue-router +# Ionic Vue Router -Routing integration for `@ionic/vue` applications. - -## Building - -1. Install dependencies: - -```shell -npm install -``` - -2. Run build script: - -```shell -npm run build -```` - -## Tests - -* Tests are found in the `__tests__` directory and use Jest. -* Tests can be run using `npm run test.spec` -* Bug fix and feature PRs should have new tests verifying the PR functionality. +The [@ionic/vue-router](https://www.npmjs.com/package/@ionic/vue-router) package is the routing integration for [@ionic/vue](https://www.npmjs.com/package/@ionic/vue). It uses the [Vue Router](https://router.vuejs.org/) library beneath the surface. ## Contributing -See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md). +See our [Contributing Guide](/docs/CONTRIBUTING.md). -## Need Help? +## Testing -Post your question on the [Ionic Forum](http://forum.ionicframework.com/). +Refer to the [Vue Router Testing documentation](./testing.md) for testing the Vue Router package. diff --git a/docs/vue-router/testing.md b/docs/vue-router/testing.md new file mode 100644 index 00000000000..99c04db7073 --- /dev/null +++ b/docs/vue-router/testing.md @@ -0,0 +1,9 @@ +# Vue Router Testing + +Ionic Framework supports multiple versions of Vue Router. As a result, we need to verify that Ionic works correctly with each of these Vue Router versions. + +## Tests + +* Tests are found in the `__tests__` directory and use Jest. +* Tests can be run using `npm run test.spec` +* Bug fix and feature PRs should have new tests verifying the PR functionality. diff --git a/docs/vue/README.md b/docs/vue/README.md index f1e964c6d78..aa5628d0399 100644 --- a/docs/vue/README.md +++ b/docs/vue/README.md @@ -1,57 +1,11 @@ -# @ionic/vue +# Ionic Vue -Ionic Framework integration for Vue 3 apps. - -## Building - -1. Install dependencies in `@ionic/core`: - -```shell -cd core && npm install -``` - -2. Build `@ionic/core`. This will generate Vue component bindings in the `packages/vue` directory: - -```shell -npm run build -```` - -3. Install dependencies in `@ionic/vue`: - -```shell -cd packages/vue && npm install -``` - -4. Build `@ionic/vue`: - -```shell -npm run build -```` - -5. Install dependencies in `@ionic/vue-router`: - -```shell -cd packages/vue-router && npm install -``` - -6. Build `@ionic/vue-router`: - -```shell -npm run build -```` - -## Tests - -* E2E Tests are found in the `packages/vue/test/base/tests` directory and use Cypress. -* When making changes to `@ionic/vue` or `@ionic/vue-router` you can run `npm run sync` in the [test-app directory](test/README.md#syncing-local-changes) to ensure that the test application is using your built changes. Be sure to build in the `vue` and `vue-router` directories first. -* Tests can be run in headless mode by running `npm run cypress`. -* If you want to open the Cypress test runner, you can run `node_modules/.bin/cypress open`. -* Bug fix and feature PRs should have new tests verifying the PR functionality. +The [@ionic/vue](https://www.npmjs.com/package/@ionic/vue) package builds on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components. ## Contributing -See our [Contributing Guide](https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md). +See our [Contributing Guide](/docs/CONTRIBUTING.md). -## Need Help? +## Testing -Post your question on the [Ionic Forum](http://forum.ionicframework.com/). +Refer to the [Vue Testing documentation](./testing.md) for testing the Vue package. diff --git a/docs/vue/testing.md b/docs/vue/testing.md index b124b491e77..268628f2ea5 100644 --- a/docs/vue/testing.md +++ b/docs/vue/testing.md @@ -1,4 +1,4 @@ -# Vue E2E Test Apps +# Vue Testing Ionic Framework supports multiple versions of Vue. As a result, we need to verify that Ionic works correctly with each of these Vue versions. diff --git a/packages/react/test/base/README.md b/packages/react/test/base/README.md index 5bb410e3c47..7988565fb65 100644 --- a/packages/react/test/base/README.md +++ b/packages/react/test/base/README.md @@ -1,3 +1,3 @@ # React Test App -Refer to the [React Testing documentation](/docs/react/testing2.md) in order to build and run the test app. +Refer to the [React Testing documentation](/docs/react/testing.md) in order to build and run the test app. From 4fe0dc3ae94ba682d00b535fd2ba8fc254976a2f Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 5 Apr 2024 12:58:03 -0400 Subject: [PATCH 08/16] chore(docs): move testing docs for playwright to docs/core --- core/src/utils/test/playwright/docs/README.md | 10 +--------- docs/README.md | 10 ++++++---- docs/core/README.md | 2 +- docs/core/testing/README.md | 13 +++++++++++++ .../playwright/docs => docs/core/testing}/api.md | 0 .../docs => docs/core/testing}/best-practices.md | 0 .../core/{testing.md => testing/preview-changes.md} | 7 +++---- .../core/testing}/usage-instructions.md | 0 8 files changed, 24 insertions(+), 18 deletions(-) create mode 100644 docs/core/testing/README.md rename {core/src/utils/test/playwright/docs => docs/core/testing}/api.md (100%) rename {core/src/utils/test/playwright/docs => docs/core/testing}/best-practices.md (100%) rename docs/core/{testing.md => testing/preview-changes.md} (54%) rename {core/src/utils/test/playwright/docs => docs/core/testing}/usage-instructions.md (100%) diff --git a/core/src/utils/test/playwright/docs/README.md b/core/src/utils/test/playwright/docs/README.md index b3a30efe7c9..02797e2ab31 100644 --- a/core/src/utils/test/playwright/docs/README.md +++ b/core/src/utils/test/playwright/docs/README.md @@ -1,11 +1,3 @@ # Ionic E2E Tests Guide -This directory contains information on how to get the most out of Ionic's E2E test infrastructure when writing tests. - -## Directory - -| Directory | Description | -| - | - | -| [Usage Instructions](./usage-instructions.md) | How to run tests and update screenshots | -| [Best Practices](./best-practices.md) | Contains information on conventions to follow as well as pitfalls to avoid when writing tests | -| [API](./api.md) | Documents the custom functionality that has been built on top of Playwright | \ No newline at end of file +Refer to the [Core Testing documentation](/docs/core/testing/README.md) in order to build and run the e2e tests. diff --git a/docs/README.md b/docs/README.md index b500583616e..736a14cb8b6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,15 +20,17 @@ It is based on Web Componen ## Guides -- [Contributing](./CONTRIBUTING.md) -- [Component Guide](./component-guide.md) -- [Sass Guidelines](./sass-guidelines.md) +| Guide | Description | +| ----------------------------------------| ---------------------------------------------------------------------------------------- | +| [Contributing](./CONTRIBUTING.md) | How to contribute including creating pull requests, commit message guidelines, and more. | +| [Component Guide](./component-guide.md) | Guidelines for implementing component states, accessibility, and more. | +| [Sass Guidelines](./sass-guidelines.md) | Outlines scenarios where Sass members and comments should be used. | ## Packages | Project | Package | Documentation | Guides | | ---------------- | -------------------------------------------------------------------------- | ---------------------------------| ----------------------------------------------------------------- | -| **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Testing](core/testing.md) | +| **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Testing](core/testing/README.md) | | **Angular** | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular) | [Readme](angular/README.md) | [Testing](angular/testing.md) | | **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [Readme](vue/README.md) | [Testing](vue/testing.md) | | **Vue Router** | [`@ionic/vue-router`](https://www.npmjs.com/package/@ionic/vue-router) | [Readme](vue-router/README.md) | [Testing](vue-router/testing.md) | diff --git a/docs/core/README.md b/docs/core/README.md index 5dad809d488..17e99262d3a 100644 --- a/docs/core/README.md +++ b/docs/core/README.md @@ -8,4 +8,4 @@ See our [Contributing Guide](/docs/CONTRIBUTING.md). ## Testing -Refer to the [Core Testing documentation](./testing.md) for testing the Core package. +Refer to the [Core Testing documentation](./testing/README.md) for testing the Core package. diff --git a/docs/core/testing/README.md b/docs/core/testing/README.md new file mode 100644 index 00000000000..bdf96b4007f --- /dev/null +++ b/docs/core/testing/README.md @@ -0,0 +1,13 @@ + +# Core Testing + +## Directory + +| Directory | Description | +| --------------------------------------------- | --------------------------------------------------------------------------------------------- | +| [Preview Changes](./preview-changes.md) | Steps on building core and previewing changes | +| [Usage Instructions](./usage-instructions.md) | How to run tests and update screenshots | +| [Best Practices](./best-practices.md) | Contains information on conventions to follow as well as pitfalls to avoid when writing tests | +| [API](./api.md) | Documents the custom functionality that has been built on top of Playwright | + + diff --git a/core/src/utils/test/playwright/docs/api.md b/docs/core/testing/api.md similarity index 100% rename from core/src/utils/test/playwright/docs/api.md rename to docs/core/testing/api.md diff --git a/core/src/utils/test/playwright/docs/best-practices.md b/docs/core/testing/best-practices.md similarity index 100% rename from core/src/utils/test/playwright/docs/best-practices.md rename to docs/core/testing/best-practices.md diff --git a/docs/core/testing.md b/docs/core/testing/preview-changes.md similarity index 54% rename from docs/core/testing.md rename to docs/core/testing/preview-changes.md index c36e4f5ae48..42143f3b936 100644 --- a/docs/core/testing.md +++ b/docs/core/testing/preview-changes.md @@ -1,5 +1,4 @@ - -# Core Testing +# Preview Changes ## Build @@ -21,10 +20,10 @@ Make sure you are inside the `core` directory. npm start -With the `dev` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and http://localhost:3333/ will open in a browser. +With the `dev` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and [http://localhost:3333/](http://localhost:3333/) will open in a browser. ### 4. Preview -Navigate to http://localhost:3333/src/components/. Each component has small e2e apps found in the `test` directory, for example: http://localhost:3333/src/components/button/test/basic +Navigate to [http://localhost:3333/src/components/](http://localhost:3333/src/components/). Each component has small e2e apps found in the `test` directory, for example: [http://localhost:3333/src/components/button/test/basic](http://localhost:3333/src/components/button/test/basic) As changes are made in an editor to source files, the e2e app will live-reload. diff --git a/core/src/utils/test/playwright/docs/usage-instructions.md b/docs/core/testing/usage-instructions.md similarity index 100% rename from core/src/utils/test/playwright/docs/usage-instructions.md rename to docs/core/testing/usage-instructions.md From 216acf9be322810cd4da50f987391d5fea7d99d6 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 5 Apr 2024 16:06:20 -0400 Subject: [PATCH 09/16] lowercase component guide --- docs/{COMPONENT-GUIDE.md => component-guide.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{COMPONENT-GUIDE.md => component-guide.md} (100%) diff --git a/docs/COMPONENT-GUIDE.md b/docs/component-guide.md similarity index 100% rename from docs/COMPONENT-GUIDE.md rename to docs/component-guide.md From 80f8ff6e3d8a44632eaeb9b295a5aff9a5e15de1 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 5 Apr 2024 16:32:16 -0400 Subject: [PATCH 10/16] chore(docs): update README to remove link --- docs/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index 736a14cb8b6..bd98be27d10 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,5 @@

- - Ionic Logo - + Ionic Logo

From 35edb4a326e6a33be8b1a4d64822e2479c2bbecf Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 5 Apr 2024 16:38:55 -0400 Subject: [PATCH 11/16] Update docs/README.md Co-authored-by: Maria Hutt --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index bd98be27d10..85cbbc9422d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,7 +30,7 @@ It is based on Web Componen | ---------------- | -------------------------------------------------------------------------- | ---------------------------------| ----------------------------------------------------------------- | | **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [Readme](core/README.md) | [Testing](core/testing/README.md) | | **Angular** | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular) | [Readme](angular/README.md) | [Testing](angular/testing.md) | -| **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [Readme](vue/README.md) | [Testing](vue/testing.md) | -| **Vue Router** | [`@ionic/vue-router`](https://www.npmjs.com/package/@ionic/vue-router) | [Readme](vue-router/README.md) | [Testing](vue-router/testing.md) | | **React** | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react) | [Readme](react/README.md) | [Testing](react/testing.md) | | **React Router** | [`@ionic/react-router`](https://www.npmjs.com/package/@ionic/react-router) | [Readme](react-router/README.md) | [Testing](react-router/testing.md) | +| **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [Readme](vue/README.md) | [Testing](vue/testing.md) | +| **Vue Router** | [`@ionic/vue-router`](https://www.npmjs.com/package/@ionic/vue-router) | [Readme](vue-router/README.md) | [Testing](vue-router/testing.md) | From 295c76d0303b25404900bbfd1c3eba9dafdf9a0d Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 5 Apr 2024 16:40:57 -0400 Subject: [PATCH 12/16] chore(docs): remove vue router testing description --- docs/vue-router/testing.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/vue-router/testing.md b/docs/vue-router/testing.md index 99c04db7073..f633a009fc8 100644 --- a/docs/vue-router/testing.md +++ b/docs/vue-router/testing.md @@ -1,7 +1,5 @@ # Vue Router Testing -Ionic Framework supports multiple versions of Vue Router. As a result, we need to verify that Ionic works correctly with each of these Vue Router versions. - ## Tests * Tests are found in the `__tests__` directory and use Jest. From b9634661198b036c87b2f65da516aa69d497d4b5 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 5 Apr 2024 16:45:28 -0400 Subject: [PATCH 13/16] chore(docs): fix docs redirect path --- core/scripts/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/scripts/readme.md b/core/scripts/readme.md index 2c2055179d7..2b5b55f748b 100644 --- a/core/scripts/readme.md +++ b/core/scripts/readme.md @@ -1,4 +1,4 @@ # Core Scripts -This file has been moved to [/docs/core/testing.md](/docs/core/testing.md). +This file has been moved to [/docs/core/testing/preview-changes.md](/docs/core/testing/preview-changes.md). From 70160796323d868be3aeaa705e1607a9b1512124 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 5 Apr 2024 16:51:47 -0400 Subject: [PATCH 14/16] chore(docs): update preview changes commands --- docs/core/testing/preview-changes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/testing/preview-changes.md b/docs/core/testing/preview-changes.md index 42143f3b936..e1fc4a6f872 100644 --- a/docs/core/testing/preview-changes.md +++ b/docs/core/testing/preview-changes.md @@ -4,8 +4,8 @@ ### 1. Clone ionic - git@github.com:ionic-team/ionic.git - cd ionic + git clone https://github.com/ionic-team/ionic-framework.git + cd ionic-framework ### 2. Run `npm install` @@ -20,7 +20,7 @@ Make sure you are inside the `core` directory. npm start -With the `dev` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and [http://localhost:3333/](http://localhost:3333/) will open in a browser. +With the `start` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and [http://localhost:3333/](http://localhost:3333/) will open in a browser. ### 4. Preview From 78466752d87a6bb253df08e2a8c4b67d2f5e9d45 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Fri, 5 Apr 2024 17:29:46 -0400 Subject: [PATCH 15/16] chore(docs): update sass guidelines --- docs/sass-guidelines.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sass-guidelines.md b/docs/sass-guidelines.md index f5c0f9ed800..d97ec11dac2 100644 --- a/docs/sass-guidelines.md +++ b/docs/sass-guidelines.md @@ -4,7 +4,7 @@ - [Scope](#scope) - [Historical Usage](#historical-usage) - [Current Usage](#current-usage) -- [Proposed Usage](#proposed-usage) +- [Recommended Usage](#recommended-usage) * [Comments](#comments) * [Variables](#variables) + [โœ… Global](#-global) @@ -96,9 +96,9 @@ $action-sheet-ios-title-with-sub-title-font-weight: 600 !default; It could be argued though that the comment doesn't really help, as seeing the variable in use will explain its purpose the best. Additionally, this is an example of a variable that isn't necessary, given it is only used in one place, which is why it is so specific in the first place. -## Proposed Usage +## Recommended Usage -There are two things that need to be outlined here: when we should use comments and when we should use variables. The sections below detail the proposed usage for each of these. +There are two things that need to be outlined here: when we should use comments and when we should use variables. The sections below detail the recommended usage for each of these. ### Comments From 6ed3f371222a733c517d6ed1088053ead1394143 Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Mon, 8 Apr 2024 10:53:26 -0400 Subject: [PATCH 16/16] chore(docs): include should be an array --- docs/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_config.yml b/docs/_config.yml index 78e6441ffb7..7b20f622ba6 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,2 +1,2 @@ name: Ionic Framework -include: CONTRIBUTING.md +include: [ CONTRIBUTING.md ]