diff --git a/BREAKING.md b/BREAKING.md deleted file mode 100644 index 8fb3032..0000000 --- a/BREAKING.md +++ /dev/null @@ -1,2 +0,0 @@ -# Breaking Changes -This is a comprehensive list of the breaking changes introduced in the major version releases of `@rdlabo/ionic-theme-md3` diff --git a/README.md b/README.md index 076f673..1a38a4e 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,6 @@ If you need a more comprehensive Material Design 3 implementation, you may also > **Note:** This theme is purpose-built for compatibility with Ionic's design approach and `@rdlabo/ionic-theme-ios26`; it is not intended as a strict, full MD3 recreation. - ## Quick start After [Installation](#installation), import the theme CSS and set `navAnimation` as shown below. @@ -72,12 +71,21 @@ createApp(App) }) ``` - ## Documentation Start with [Installation](#installation). Pair this theme with [@rdlabo/ionic-theme-ios26](https://docs.rdlabo.dev/projects/ionic-theme-ios26) when you need both platforms from one markup tree. +- [Special markup](./docs/special-markup.md) — opt-in component combinations used by the demo. +- [Using ion-item-group](./docs/using-ion-item-group.md) — shared inset-list markup for iOS 26 and MD3. + + + +- [Breaking changes](./docs/breaking.md) — changes required when upgrading major versions. + + + + **Full documentation:** [https://docs.rdlabo.dev/projects/ionic-theme-md3](https://docs.rdlabo.dev/projects/ionic-theme-md3) ## Development & Testing @@ -118,4 +126,5 @@ npm run test:e2e:debug # Update baseline screenshots (when intentionally changing UI) npm run test:e2e:update ``` + diff --git a/demo/E2E_TESTING.md b/demo/E2E_TESTING.md deleted file mode 100644 index 6de239a..0000000 --- a/demo/E2E_TESTING.md +++ /dev/null @@ -1,214 +0,0 @@ -# E2E Screenshot Testing Guide - -This document explains how to use the Playwright-based screenshot testing system for the Ionic iOS26 Theme Demo application. - -## Overview - -The E2E test suite uses Playwright to capture full-page screenshots of all routes in the demo application. This ensures visual consistency and helps catch unintended UI changes. - -## Test Coverage - -### Routes Tested -All routes defined in `src/app/index/index.routes.ts` are automatically tested: - -- Index (main page) -- Action Sheet -- Alert -- Button -- Checkbox -- Range -- Toast -- Toggle -- Segment -- Modal -- Card -- Chip -- Breadcrumbs -- Searchbar -- Popover -- Progress Indicators -- Floating Action Button -- Select -- Radio -- Date and Time Pickers -- Accordion -- Inputs -- Item List -- Reorder -- Tabs -- Toolbar - -### Test Modes -Each route is tested in two modes: -- **Light Mode**: Default Ionic styling -- **Dark Mode**: With `ion-palette-dark` class applied - -**Total Tests**: 26 routes × 2 modes = **52 screenshot tests** - -## Running Tests - -### Prerequisites - -Make sure you have installed all dependencies: - -```bash -npm install -``` - -Playwright browsers will be automatically installed when needed, or you can install them manually: - -```bash -npx playwright install chromium -``` - -### Test Commands - -#### Run all tests -```bash -npm run test:e2e -``` - -#### Interactive UI mode -Run tests with Playwright's interactive UI: -```bash -npm run test:e2e:ui -``` - -#### Debug mode -Step through tests with debugging tools: -```bash -npm run test:e2e:debug -``` - -#### Update screenshots -When you intentionally change the UI and need to update baseline screenshots: -```bash -npm run test:e2e:update -``` - -#### Run in Docker (same as CI) -To run tests in the same Linux environment as GitHub Actions (using the same Docker image): - -**Run tests in Docker**: -```bash -npm run test:e2e:docker -``` - -**Update screenshots in Docker**: -```bash -npm run test:e2e:docker:update -``` - -These commands will: -1. Mount the project root into the Docker container -2. Install dependencies -3. Start the development server inside Docker -4. Run Playwright tests -5. Clean up automatically - -This ensures your local test results match the CI environment exactly, including font rendering and browser behavior differences between macOS and Linux. - -## Understanding Test Results - -### Passing Tests -When a test passes, it means the current screenshot matches the baseline screenshot stored in `e2e/screenshot.spec.ts-snapshots/`. - -### Failing Tests -When a test fails, it indicates a visual difference between the current and baseline screenshots. This could be: -- An intentional UI change (update baselines with `npm run test:e2e:update`) -- An unintended regression (fix the issue and re-run tests) - -### Test Reports -After running tests, you can view detailed HTML reports: -```bash -npx playwright show-report -``` - -## CI/CD Integration - -The E2E tests run automatically on: -- Push to `main` or `develop` branches -- Pull requests targeting `main` or `develop` branches - -See `.github/workflows/e2e-tests.yml` for the CI configuration. - -### Viewing CI Results -When tests fail in CI: -1. Check the GitHub Actions workflow results -2. Download the `playwright-report` artifact to view the full report -3. Download the `test-results` artifact to see actual vs expected screenshots - -## File Structure - -``` -demo/ -├── e2e/ -│ ├── screenshot.spec.ts # Test specifications -│ └── screenshot.spec.ts-snapshots/ # Baseline screenshots (committed to git) -├── playwright-report/ # Test reports (gitignored) -├── test-results/ # Failed test artifacts (gitignored) -└── playwright.config.ts # Playwright configuration -``` - -## Best Practices - -1. **Review visual changes carefully** before updating baselines -2. **Run tests locally** before pushing to avoid CI failures -3. **Update baselines only when UI changes are intentional** -4. **Use UI mode** (`npm run test:e2e:ui`) for easier debugging -5. **Check both light and dark mode** when making UI changes - -## Troubleshooting - -### Tests failing on CI but passing locally -This can happen due to: -- Font rendering differences between macOS and Linux -- Browser behavior differences between operating systems - -**Solution**: Update screenshots using Docker to match the CI environment: -```bash -npm run test:e2e:docker:update -``` - -This uses the same `mcr.microsoft.com/playwright:v1.56.0-noble` Docker image as GitHub Actions and regenerates screenshots in the Linux environment. - -### Slow test execution -- The development server takes time to start (configured timeout: 120s) -- Each screenshot capture includes a 500ms wait for animations to complete -- Parallel execution is configured to speed up the process - -### Screenshots appear incorrect -1. Ensure the development server is running correctly -2. Check that the route paths match those in `index.routes.ts` -3. Verify the page has fully loaded before screenshot capture - -## Updating the Test Suite - -### Adding new routes -When adding a new route to `index.routes.ts`, update `e2e/screenshot.spec.ts`: - -```typescript -const routes = [ - // ... existing routes - { path: '/index/new-page', name: 'new-page' }, -]; -``` - -Then run: -```bash -npm run test:e2e:update -``` - -### Modifying test behavior -Edit `playwright.config.ts` to adjust: -- Browser configurations -- Viewport sizes -- Timeout settings -- Screenshot options - -## Additional Resources - -- [Playwright Documentation](https://playwright.dev/) -- [Playwright Screenshots Guide](https://playwright.dev/docs/screenshots) -- [Visual Comparisons](https://playwright.dev/docs/test-snapshots) - diff --git a/docs/breaking.md b/docs/breaking.md new file mode 100644 index 0000000..1c80a56 --- /dev/null +++ b/docs/breaking.md @@ -0,0 +1,3 @@ +# Breaking changes + +This document lists the breaking changes introduced in major releases of `@rdlabo/ionic-theme-md3` and the steps required to migrate. There are no documented breaking changes yet. diff --git a/docs/e2e-testing.md b/docs/e2e-testing.md new file mode 100644 index 0000000..5700a89 --- /dev/null +++ b/docs/e2e-testing.md @@ -0,0 +1,51 @@ +# E2E screenshot testing + +This maintainer guide explains how to run the Playwright visual-regression suite for the Material Design 3 demo. The suite covers every entry declared in `demo/e2e/screenshot.spec.ts` in both light and dark modes. Overlay variants are generated from the shared arrays in `demo/src/app/overlay-types.ts`. + +## Run the suite + +Install the demo dependencies first: + +```bash +cd demo +npm install +``` + +Then choose the command that matches the task: + +```bash +npm run test:e2e # Run the suite +npm run test:e2e:ui # Open Playwright UI mode +npm run test:e2e:debug # Run with the Playwright debugger +npm run test:e2e:update # Regenerate intentional baseline changes +``` + +To reproduce the Linux environment used by CI, run the Docker variants from `demo/`: + +```bash +npm run test:e2e:docker +npm run test:e2e:docker:update +``` + +The Docker commands use the Playwright image pinned in `demo/package.json`. + +## Review a failure + +A screenshot mismatch can be a regression or an intentional visual change. Before updating a baseline: + +1. Inspect the actual, expected, and diff images in `demo/test-results/`. +2. Check the affected route in both light and dark modes. +3. Confirm that the component change is intentional. +4. Regenerate the baseline with `npm run test:e2e:update`, or use the Docker variant when matching CI rendering. + +The HTML report is written to `demo/playwright-report/` and can be opened with: + +```bash +npx playwright show-report +``` + +## Add coverage + +When adding a demo route or overlay variant, update `demo/e2e/screenshot.spec.ts` and regenerate the relevant baselines. Commit baseline changes only after reviewing the visual diff. + +Pull requests run the E2E workflow in `.github/workflows/e2e-pull_request.yml`; pushes to `main` run `.github/workflows/e2e-main.yml`. diff --git a/docs/special-markup.md b/docs/special-markup.md new file mode 100644 index 0000000..4f7745e --- /dev/null +++ b/docs/special-markup.md @@ -0,0 +1,36 @@ +--- +title: Special markup +--- + +# Special markup + +Most Ionic markup works without changes. The combination below is an explicit opt-in demonstrated in `demo/src/app/docs` and is useful when the same template also uses `@rdlabo/ionic-theme-ios26`. + +## Two-line inset list items + +Place an unslotted `ion-label` immediately alongside an unslotted `ion-note` to render a two-line item. Use `slot="end"` on `ion-note` when you want the standard trailing-note layout instead. + +```html + + + Network & internet + Mobile, Wi-Fi, hotspot + + +``` + +If the application imports `@rdlabo/ionic-theme-ios26/dist/css/md-ion-list-inset.css`, wrap list items in `ion-item-group` and keep `ion-list-header` outside the group: + +```html + + Connections + + + Network & internet + Mobile, Wi-Fi, hotspot + + + +``` + +See [Using `ion-item-group`](./using-ion-item-group.md) for the required import and background model. diff --git a/USING_ION_ITEM_GROUP.md b/docs/using-ion-item-group.md similarity index 64% rename from USING_ION_ITEM_GROUP.md rename to docs/using-ion-item-group.md index c21e544..c03e917 100644 --- a/USING_ION_ITEM_GROUP.md +++ b/docs/using-ion-item-group.md @@ -1,14 +1,19 @@ -# Using `ion-item-group` with iOS26 Theme +--- +title: Using ion-item-group +--- -This theme aims to bring Ionic Framework applications as close as possible to iOS 26 design. In most cases, you can use your existing Ionic code as-is, but **only under specific conditions**, you need to add `ion-item-group`. +# Using `ion-item-group` with the MD3 theme + +The MD3 theme supports the same inset-list markup as `@rdlabo/ionic-theme-ios26`, so an application can share one template across Ionic modes. Add `ion-item-group` when you opt in to that shared pattern. ## When is `ion-item-group` required? -It is only required when **both** of the following conditions are met: +It is only required when both of the following conditions are met: - You have enabled the `inset` property on `ion-list` +- You import the iOS 26 package's optional `md-ion-list-inset.css` stylesheet -Only when these conditions apply, you need to wrap your list items with `ion-item-group`. +When these conditions apply, wrap the list items—but not the list header—with `ion-item-group`. ## Implementation Example @@ -28,7 +33,7 @@ Only when these conditions apply, you need to wrap your list items with `ion-ite By default in Ionic Framework, `ion-list` has a background color, and `ion-list-header` is treated as part of the list. However, with this structure, it's impossible to accurately reproduce **iOS's native design patterns**. -![](screenshots/why-ion-list-inset.png) +![Inset list background comparison](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-ios26/v2.3.2/screenshots/why-ion-list-inset.png) ### Solution: Background Color Separation @@ -52,5 +57,5 @@ This will apply the same `ion-item-group` pattern to the Material Design theme a ## Summary - **Most cases**: You can use your existing Ionic code as-is -- **Specific conditions only**: `ion-item-group` is only required when setting using `inset` on `ion-list` +- **Specific conditions only**: `ion-item-group` is required when using the optional shared inset-list stylesheet - **Purpose**: To accurately reproduce iOS 26's native design patterns