@rdlabo/ionic-theme-ios26 0.0.2 → 0.0.4

package/USING_ION_ITEM_GROUP.md

@@ -0,0 +1,56 @@
+# Using `ion-item-group` with iOS26 Theme
+
+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`.
+
+## When is `ion-item-group` required?
+
+It is only required when **both** of the following conditions are met:
+
+- You have enabled the `inset` property on `ion-list`
+
+Only when these conditions apply, you need to wrap your list items with `ion-item-group`.
+
+## Implementation Example
+
+```diff
+  <ion-list inset=true>
+    <ion-list-header><ion-label>Label</ion-label></ion-list-header>
++   <ion-item-group>
+      <ion-item>...</ion-item>
+      <ion-item>...</ion-item>
++   </ion-item-group>
+  </ion-list>
+```
+
+## Why is this change necessary?
+
+### Background: Challenges in iOS Design Reproduction
+
+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)
+
+### Solution: Background Color Separation
+
+To faithfully reproduce iOS design, this theme makes the following changes:
+
+- Set `ion-list` background color to transparent
+- Delegate background color to `ion-item-group`
+
+This change allows `ion-list-header` to be treated as an independent element, achieving the native iOS appearance.
+
+## Using the Same Design with Material Design
+
+If you want to use the same design pattern with Material Design theme, import the following CSS:
+
+```css
+@import '@rdlabo/ionic-theme-ios26/css/md-ion-list-inset.css';
+```
+
+This will apply the same `ion-item-group` pattern to the Material Design theme as well.
+
+## 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`
+- **Purpose**: To accurately reproduce iOS 26's native design patterns

package/demo/ .cursor/rules/angular-20.mdc

@@ -0,0 +1,136 @@
+---
+description: This rule provides comprehensive best practices and coding standards for Angular development, focusing on modern TypeScript, standalone components, signals, and performance optimizations.
+globs: ["**/*.{ts,html,scss,css}"]
+---
+
+# Angular Best Practices
+
+This project adheres to modern Angular best practices, emphasizing maintainability, performance, accessibility, and scalability.
+
+## TypeScript Best Practices
+
+* **Strict Type Checking:** Always enable and adhere to strict type checking. This helps catch errors early and improves code quality.
+* **Prefer Type Inference:** Allow TypeScript to infer types when they are obvious from the context. This reduces verbosity while maintaining type safety.
+    * **Bad:**
+        ```typescript
+        let name: string = 'Angular';
+        ```
+    * **Good:**
+        ```typescript
+        let name = 'Angular';
+        ```
+* **Avoid `any`:** Do not use the `any` type unless absolutely necessary as it bypasses type checking. Prefer `unknown` when a type is uncertain and you need to handle it safely.
+
+## Angular Best Practices
+
+* **Standalone Components:** Always use standalone components, directives, and pipes. Avoid using `NgModules` for new features or refactoring existing ones.
+* **Implicit Standalone:** When creating standalone components, you do not need to explicitly set `standalone: true` inside the `@Component`, `@Directive` and `@Pipe` decorators, as it is implied by default.
+    * **Bad:**
+        ```typescript
+        @Component({
+          standalone: true,
+          // ...
+        })
+        export class MyComponent {}
+        ```
+    * **Good:**
+        ```typescript
+        @Component({
+          // `standalone: true` is implied
+          // ...
+        })
+        export class MyComponent {}
+        ```
+* **Signals for State Management:** Utilize Angular Signals for reactive state management within components and services.
+* **Lazy Loading:** Implement lazy loading for feature routes to improve initial load times of your application.
+* **NgOptimizedImage:** Use `NgOptimizedImage` for all static images to automatically optimize image loading and performance.
+* **Host bindings:** Do NOT use the `@HostBinding` and `@HostListener` decorators. Put host bindings inside the `host` object of the `@Component` or `@Directive` decorator instead.
+
+## Components
+
+* **Single Responsibility:** Keep components small, focused, and responsible for a single piece of functionality.
+* **`input()` and `output()` Functions:** Prefer `input()` and `output()` functions over the `@Input()` and `@Output()` decorators for defining component inputs and outputs.
+    * **Old Decorator Syntax:**
+        ```typescript
+        @Input() userId!: string;
+        @Output() userSelected = new EventEmitter<string>();
+        ```
+    * **New Function Syntax:**
+        ```typescript
+        import { input, output } from '@angular/core';
+
+        // ...
+        userId = input<string>('');
+        userSelected = output<string>();
+        ```
+* **`computed()` for Derived State:** Use the `computed()` function from `@angular/core` for derived state based on signals.
+* **`ChangeDetectionStrategy.OnPush`:** Always set `changeDetection: ChangeDetectionStrategy.OnPush` in the `@Component` decorator for performance benefits by reducing unnecessary change detection cycles.
+* **Inline Templates:** Prefer inline templates (template: `...`) for small components to keep related code together. For larger templates, use external HTML files.
+* **Reactive Forms:** Prefer Reactive forms over Template-driven forms for complex forms, validation, and dynamic controls due to their explicit, immutable, and synchronous nature.
+* **No `ngClass` / `NgClass`:** Do not use the `ngClass` directive. Instead, use native `class` bindings for conditional styling.
+    * **Bad:**
+        ```html
+        <section [ngClass]="{'active': isActive}"></section>
+        ```
+    * **Good:**
+        ```html
+        <section [class.active]="isActive"></section>
+        <section [class]="{'active': isActive}"></section>
+        <section [class]="myClasses"></section>
+        ```
+* **No `ngStyle` / `NgStyle`:** Do not use the `ngStyle` directive. Instead, use native `style` bindings for conditional inline styles.
+    * **Bad:**
+        ```html
+        <section [ngStyle]="{'font-size': fontSize + 'px'}"></section>
+        ```
+    * **Good:**
+        ```html
+        <section [style.font-size.px]="fontSize"></section>
+        <section [style]="myStyles"></section>
+        ```
+
+## State Management
+
+* **Signals for Local State:** Use signals for managing local component state.
+* **`computed()` for Derived State:** Leverage `computed()` for any state that can be derived from other signals.
+* **Pure and Predictable Transformations:** Ensure state transformations are pure functions (no side effects) and predictable.
+* **Signal value updates:** Do NOT use `mutate` on signals, use `update` or `set` instead.
+
+## Templates
+
+* **Simple Templates:** Keep templates as simple as possible, avoiding complex logic directly in the template. Delegate complex logic to the component's TypeScript code.
+* **Native Control Flow:** Use the new built-in control flow syntax (`@if`, `@for`, `@switch`) instead of the older structural directives (`*ngIf`, `*ngFor`, `*ngSwitch`).
+    * **Old Syntax:**
+        ```html
+        <section *ngIf="isVisible">Content</section>
+        <section *ngFor="let item of items">{{ item }}</section>
+        ```
+    * **New Syntax:**
+        ```html
+        @if (isVisible) {
+          <section>Content</section>
+        }
+        @for (item of items; track item.id) {
+          <section>{{ item }}</section>
+        }
+        ```
+* **Async Pipe:** Use the `async` pipe to handle observables in templates. This automatically subscribes and unsubscribes, preventing memory leaks.
+
+## Services
+
+* **Single Responsibility:** Design services around a single, well-defined responsibility.
+* **`providedIn: 'root'`:** Use the `providedIn: 'root'` option when declaring injectable services to ensure they are singletons and tree-shakable.
+* **`inject()` Function:** Prefer the `inject()` function over constructor injection when injecting dependencies, especially within `provide` functions, `computed` properties, or outside of constructor context.
+    * **Old Constructor Injection:**
+        ```typescript
+        constructor(private myService: MyService) {}
+        ```
+    * **New `inject()` Function:**
+        ```typescript
+        import { inject } from '@angular/core';
+
+        export class MyComponent {
+          private myService = inject(MyService);
+          // ...
+        }
+        ```

package/demo/.browserslistrc

@@ -0,0 +1,15 @@
+# This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
+# For additional information regarding the format and rule options, please see:
+# https://github.com/browserslist/browserslist#queries
+
+# For the full list of supported browsers by the Angular framework, please see:
+# https://angular.dev/reference/versions#browser-support
+
+# You can see what browsers were selected by your queries by running:
+#   npx browserslist
+
+Chrome >=107
+Firefox >=106
+Edge >=107
+Safari >=16.1
+iOS >=16.1

package/demo/.editorconfig

@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/demo/.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+       "Webnative.webnative"
+    ]
+}

package/demo/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "typescript.preferences.autoImportFileExcludePatterns": ["@ionic/angular/common", "@ionic/angular"]
+}

package/demo/angular.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "app": {
+      "projectType": "application",
+      "schematics": {
+        "@ionic/angular-toolkit:page": {
+          "styleext": "scss",
+          "standalone": true
+        }
+      },
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:application",
+          "options": {
+            "outputPath": {
+              "base": "www",
+              "browser": ""
+            },
+            "index": "src/index.html",
+            "tsConfig": "tsconfig.app.json",
+            "inlineStyleLanguage": "scss",
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "src/assets",
+                "output": "assets"
+              }
+            ],
+            "styles": ["src/global.scss", "src/theme/variables.scss"],
+            "scripts": [],
+            "browser": "src/main.ts"
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "2mb",
+                  "maximumError": "5mb"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "2kb",
+                  "maximumError": "4kb"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true,
+              "namedChunks": true
+            },
+            "ci": {
+              "progress": false
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "app:build:production"
+            },
+            "development": {
+              "buildTarget": "app:build:development"
+            },
+            "ci": {
+              "progress": false
+            }
+          },
+          "defaultConfiguration": "development"
+        },
+        "extract-i18n": {
+          "builder": "@angular-devkit/build-angular:extract-i18n",
+          "options": {
+            "buildTarget": "app:build"
+          }
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "main": "src/test.ts",
+            "tsConfig": "tsconfig.spec.json",
+            "karmaConfig": "karma.conf.js",
+            "inlineStyleLanguage": "scss",
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "src/assets",
+                "output": "assets"
+              }
+            ],
+            "styles": ["src/global.scss", "src/theme/variables.scss"],
+            "scripts": []
+          },
+          "configurations": {
+            "ci": {
+              "progress": false,
+              "watch": false
+            }
+          }
+        },
+        "lint": {
+          "builder": "@angular-eslint/builder:lint",
+          "options": {
+            "lintFilePatterns": ["src/**/*.ts", "src/**/*.html"]
+          }
+        }
+      }
+    }
+  },
+  "cli": {
+    "schematicCollections": [
+      "@ionic/angular-toolkit"
+    ],
+    "analytics": "cbe1df8d-204f-4a38-b88d-9f3a65fd6af4"
+  },
+  "schematics": {
+    "@ionic/angular-toolkit:component": {
+      "styleext": "scss"
+    },
+    "@ionic/angular-toolkit:page": {
+      "styleext": "scss"
+    },
+    "@angular-eslint/schematics:application": {
+      "setParserOptionsProject": true
+    },
+    "@angular-eslint/schematics:library": {
+      "setParserOptionsProject": true
+    }
+  }
+}

package/demo/capacitor.config.ts

@@ -0,0 +1,9 @@
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'io.ionic.starter',
+  appName: 'demo',
+  webDir: 'www',
+};
+
+export default config;

package/demo/eslint.config.js

@@ -0,0 +1,49 @@
+// @ts-check
+const eslint = require("@eslint/js");
+const tseslint = require("typescript-eslint");
+const angular = require("angular-eslint");
+const rdlabo = require('@rdlabo/eslint-plugin-rules');
+
+module.exports = tseslint.config(
+  {
+    files: ["**/*.ts"],
+    plugins: {
+      '@rdlabo/rules': rdlabo,
+    },
+    extends: [
+      eslint.configs.recommended,
+      ...tseslint.configs.recommended,
+      ...tseslint.configs.stylistic,
+      ...angular.configs.tsRecommended,
+    ],
+    processor: angular.processInlineTemplates,
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": "off",
+      "@angular-eslint/directive-selector": "off",
+      "@angular-eslint/component-selector": "off",
+      "@angular-eslint/no-empty-lifecycle-method": "off",
+      "@typescript-eslint/no-empty-function": "off",
+      '@rdlabo/rules/deny-constructor-di': 'error',
+      '@rdlabo/rules/deny-import-from-ionic-module': 'error',
+      '@rdlabo/rules/implements-ionic-lifecycle': 'error',
+      '@rdlabo/rules/deny-soft-private-modifier': 'error',
+      '@rdlabo/rules/signal-use-as-signal': 'error',
+      '@rdlabo/rules/signal-use-as-signal-template': 'error',
+      '@rdlabo/rules/component-property-use-readonly': 'error',
+    },
+  },
+  {
+    files: ["**/*.html"],
+    plugins: {
+      '@rdlabo/rules': rdlabo,
+    },
+    extends: [
+      ...angular.configs.templateRecommended,
+      ...angular.configs.templateAccessibility,
+    ],
+    rules: {
+      '@rdlabo/rules/ionic-attr-type-check': 'error',
+    },
+  }
+);

package/demo/ionic.config.json

@@ -0,0 +1,7 @@
+{
+  "name": "demo",
+  "integrations": {
+    "capacitor": {}
+  },
+  "type": "angular-standalone"
+}

package/demo/karma.conf.js

@@ -0,0 +1,44 @@
+// Karma configuration file, see link for more information
+// https://karma-runner.github.io/1.0/config/configuration-file.html
+
+module.exports = function (config) {
+  config.set({
+    basePath: '',
+    frameworks: ['jasmine', '@angular-devkit/build-angular'],
+    plugins: [
+      require('karma-jasmine'),
+      require('karma-chrome-launcher'),
+      require('karma-jasmine-html-reporter'),
+      require('karma-coverage'),
+      require('@angular-devkit/build-angular/plugins/karma')
+    ],
+    client: {
+      jasmine: {
+        // you can add configuration options for Jasmine here
+        // the possible options are listed at https://jasmine.github.io/api/edge/Configuration.html
+        // for example, you can disable the random execution with `random: false`
+        // or set a specific seed with `seed: 4321`
+      },
+      clearContext: false // leave Jasmine Spec Runner output visible in browser
+    },
+    jasmineHtmlReporter: {
+      suppressAll: true // removes the duplicated traces
+    },
+    coverageReporter: {
+      dir: require('path').join(__dirname, './coverage/app'),
+      subdir: '.',
+      reporters: [
+        { type: 'html' },
+        { type: 'text-summary' }
+      ]
+    },
+    reporters: ['progress', 'kjhtml'],
+    port: 9876,
+    colors: true,
+    logLevel: config.LOG_INFO,
+    autoWatch: true,
+    browsers: ['Chrome'],
+    singleRun: false,
+    restartOnFileChange: true
+  });
+};