feat: release v3.0.0

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Connection with issue(s)
+
+Resolve issue #???
+
+<!-- Required: this reference (one or many) will be closed upon merge. Ideally it has the acceptance criteria and designs for features or fixes related to the work in this Pull Request -->
+
+Connected to #???
+
+<!-- Optional: other issues or pull requests related to this, but merging should not close it -->
+
+## Testing and Review Notes
+
+<!-- Required: steps to take to confirm this works as expected or other guidance for code, UX, and any other reviewers -->
+
+## Screenshots or Videos
+
+<!-- Optional: to clearly demonstrate the feature or fix to help with testing and reviews -->
+
+## To Do
+
+<!-- Add “WIP” to the PR title if pushing up but not complete nor ready for review -->
+- [ ] double check the original issue to confirm it is fully satisfied
+- [ ] add testing notes and screenshots in PR description to help guide reviewers
+- [ ] request the "UX" team perform a design review (if/when applicable)

.github/workflows/code-quality-tests.yml

@@ -0,0 +1,36 @@
+name: Code Quality
+
+on: [push]
+
+jobs:
+  format-and-fix:
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup flutter
+        uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+
+      - name: Get packages
+        run: flutter pub get
+
+      - name: Check format errors
+        run: flutter format --set-exit-if-changed .
+
+      - name: Check lint errors
+        run: flutter analyze .
+
+      - name: Run tests
+        run: flutter test --coverage --test-randomize-ordering-seed random
+
+      - name: Very Good Coverage
+        uses: VeryGoodOpenSource/very_good_coverage@v2.1.0
+        with:
+          min_coverage: 60
+
+      - name: Flutter Problem Matcher
+        uses: leancodepl/dart-problem-matcher@main

.github/workflows/conventional-pr-title.yml

@@ -0,0 +1,22 @@
+name: Check PR title
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: deepakputhraya/action-pr-title@master
+        with:
+          max_length: 100
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: amannn/action-semantic-pull-request@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pubignore

@@ -0,0 +1,9 @@
+# IDE project files — not needed by package consumers
+*.iml
+
+# Internal planning docs
+V3_PLAN.md
+CLAUDE.md
+
+# Coverage output
+coverage/

CHANGELOG.md

@@ -1,3 +1,29 @@
+## [3.0.0] - [April 10, 2026]
+
+### Breaking changes
+* Requires Flutter >=3.16.0 and Dart SDK >=3.5.0
+* Android and Web themes now derive colors from `Theme.of(context).colorScheme` (Material 3). Custom color overrides via `SettingsThemeData` still work.
+
+### New features
+* `compact: bool` parameter on `SettingsTile` — use smaller vertical padding for dense layouts
+* `crossAxisAlignment` parameter on `SettingsList`
+* `titleTextStyle`, `tileTextStyle`, `tileDescriptionTextStyle`, `inactiveSwitchColor` fields on `SettingsThemeData`
+
+### Bug fixes
+* Fixed iOS value text overflow in narrow tiles (#186)
+* Fixed RTL chevron direction — now shows back-arrow in right-to-left layouts
+* Fixed platform override being ignored on macOS host when `platform: android/web` was set (#139)
+* Fixed web switch ignoring `SwitchTheme` due to hardcoded fallback color (#188)
+* Fixed disabled switch using wrong inactive color on all platforms
+
+### Maintenance
+* Migrated all constructors to super-parameters (`super.key`, `super.child`)
+* Replaced deprecated `textScaleFactor` with `MediaQuery.textScalerOf`
+* Replaced deprecated `Switch.activeColor` with `Switch.activeThumbColor`
+* Replaced deprecated `CupertinoSwitch.activeColor` with `CupertinoSwitch.activeTrackColor`
+* Updated CI to `actions/checkout@v4`, coverage gate raised from 35% → 60%
+* Updated example app with Material 3 demo screen
+
 ## [2.0.3] - [June 13, 2022]
 * Updated documentation
 * Fixed display of web support on pub.dev

CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About this project
+
+`settings_ui` is a published Flutter package (pub.dev: `settings_ui`, current version: `2.0.3`) that renders native-looking settings screens for Android, iOS, macOS, Windows, Linux, Fuchsia, and Web — all from a single API. It is used in production by thousands of apps.
+
+## Commands
+
+```bash
+# Get dependencies
+flutter pub get
+
+# Run all tests
+flutter test
+
+# Run a single test file
+flutter test test/widget_test.dart
+
+# Run tests with coverage
+flutter test --coverage --test-randomize-ordering-seed random
+
+# Analyze for lint errors
+flutter analyze .
+
+# Fix formatting
+flutter format .
+
+# Check formatting without changing files (CI-style)
+flutter format --set-exit-if-changed .
+
+# Run the example app
+cd example && flutter run
+```
+
+## Architecture
+
+### Rendering strategy: platform dispatch
+
+Every public widget (`SettingsList`, `SettingsSection`, `SettingsTile`) is a thin dispatcher. At build time each checks `SettingsTheme.of(context).platform` and returns one of three concrete platform implementations:
+
+- `Android/Fuchsia/Linux` → Material widgets
+- `iOS/macOS/Windows` → Cupertino widgets
+- `Web` → Web-specific widgets (rounded cards, adjusted padding)
+
+Platform implementations live alongside their dispatcher:
+
+```
+lib/src/tiles/
+  settings_tile.dart          ← dispatcher
+  platforms/
+    android_settings_tile.dart
+    ios_settings_tile.dart
+    web_settings_tile.dart
+```
+
+Same pattern for `sections/` and `list/`.
+
+### Theme propagation via `InheritedWidget`
+
+`SettingsList` resolves platform and brightness, calls `ThemeProvider.getTheme()` to get hardcoded platform defaults, merges in any user-supplied `lightTheme`/`darkTheme` (`SettingsThemeData`), then pushes the result down the tree via `SettingsTheme` (an `InheritedWidget`).
+
+All platform tile/section widgets read theme from `SettingsTheme.of(context).themeData`. Never pass theme as a constructor argument.
+
+`ThemeProvider` (`lib/src/utils/theme_provider.dart`) contains all hardcoded color values for each platform/brightness combination. This is the main place to touch when fixing theme issues.
+
+### `DevicePlatform.device` is a sentinel
+
+`DevicePlatform.device` means "auto-detect at runtime" and is valid only as input to `SettingsList`. It must never reach the platform switch statements inside tiles/sections — doing so throws. `PlatformUtils.detectPlatform()` resolves it to a real platform.
+
+### `IOSSettingsTileAdditionalInfo`
+
+An extra `InheritedWidget` injected by `IOSSettingsSection` to tell each `IOSSettingsTile` whether to draw top/bottom border radius and whether to show the inter-tile divider. This is iOS/macOS/Windows only.
+
+### Public API surface (the only exports)
+
+`lib/settings_ui.dart` re-exports exactly:
+- `SettingsList` (+ `ApplicationType` enum)
+- `SettingsSection`, `AbstractSettingsSection`, `CustomSettingsSection`
+- `SettingsTile` (+ `SettingsTileType` enum), `AbstractSettingsTile`, `CustomSettingsTile`
+- `DevicePlatform`, `PlatformUtils`
+- `SettingsTheme`, `SettingsThemeData`
+
+Platform-specific implementations are internal and should not be part of the public API.
+
+## Testing conventions
+
+- Tests live in `test/` with a flat `widget_test.dart` entry point that calls helper functions grouped by concern (`settingsListTests`, `settingsSectionsTests`, `settingsTileTests`, etc.).
+- Helper test functions are parameterised over `DevicePlatform` and called for every platform value.
+- The `_wrapWithMaterialApp` / `TestWidgetScreen` helper wraps a tile or section in a `SettingsList` inside a `MaterialApp` and passes the desired platform explicitly so tests are platform-deterministic.
+- CI requires ≥ 35% line coverage (`very_good_coverage`).
+
+## CI / Release
+
+- **CI** runs on every push: format check → `flutter analyze` → `flutter test --coverage` → coverage gate (35%).
+- **PR titles** must follow Conventional Commits (enforced by `action-semantic-pull-request`).
+- There is currently no automated publish workflow; a new version requires bumping `version` in `pubspec.yaml`, updating `CHANGELOG.md`, tagging, then running `flutter pub publish`.

V3_PLAN.md

@@ -0,0 +1,133 @@
+# settings_ui v3.0.0 — Release Plan
+
+Target: `3.0.0` on pub.dev  
+Flutter: 3.41.x stable / Dart 3.x  
+Status: **READY TO PUBLISH**
+
+This file tracks every task needed before and after the release.  
+Check off items (`- [x]`) as they are completed.
+
+---
+
+## Phase 1 — Codebase Health & Deprecation Fixes ✅
+
+- [x] **1.1** Bump `pubspec.yaml` SDK constraint to `>=3.5.0 <4.0.0` and Flutter to `>=3.16.0`
+- [x] **1.2** Replace `MediaQuery.of(context).textScaleFactor` with `MediaQuery.textScalerOf(context).scale(value)`
+- [x] **1.3** Replace `Key? key` super-constructor patterns with `super.key`
+- [x] **1.4** Update `dev_dependencies`: `flutter_lints: ^5.0.0`
+- [x] **1.5** `flutter analyze` — zero issues
+
+---
+
+## Phase 2 — Bug Fixes ✅
+
+- [x] **2.1** iOS value text overflow — `Flexible` in inner Row of `buildTileContent` *(Issue #186)*
+- [x] **2.2** RTL chevron — `chevron_back` in RTL locales *(Issue #170)*
+- [x] **2.3** Web platform tag — `platforms:` block in `pubspec.yaml` *(Issue #179)*
+- [x] **2.4** `enabled` ignored on Web tile — `inactiveTitleColor` applied *(Issue #174)*
+- [x] **2.5** Web switch `activeColor` — hardcoded fallback removed *(Issue #188)*
+- [x] **2.6** `switchTheme` ignored on Web — no more hardcoded blue override *(Issue #188)*
+- [x] **2.7** `trailing` missing on Web switch tile — fixed
+- [x] **2.9** Platform override ignored on macOS host — `theme.platform` used instead of re-detecting *(Issue #139)*
+- [x] Replace deprecated `Switch.activeColor` → `Switch.activeThumbColor`
+- [x] Replace deprecated `CupertinoSwitch.activeColor` → `CupertinoSwitch.activeTrackColor`
+
+---
+
+## Phase 3 — Material 3 Theme Overhaul ✅
+
+- [x] **3.1/3.2** Android light + dark — derived from `ColorScheme`
+- [x] **3.3** iOS themes — Cupertino hardcoded values retained
+- [x] **3.4** Web theme — derived from `ColorScheme`
+- [x] **3.5** `ThemeProvider.getTheme` reads `Theme.of(context).colorScheme`
+- [x] **3.6** `inactiveSwitchColor` added to `SettingsThemeData`
+
+---
+
+## Phase 4 — New Features ✅
+
+- [x] **4.1** `compact: bool` on `SettingsTile` *(PR #178)*
+- [x] **4.2** `crossAxisAlignment` on `SettingsList` *(Issue #189)*
+- [x] **4.3** `titleTextStyle`, `tileTextStyle`, `tileDescriptionTextStyle` in `SettingsThemeData` *(Issue #185)*
+
+---
+
+## Phase 5 — Example App ✅
+
+- [x] **5.1** Bump example SDK + Flutter constraints
+- [x] **5.2** Removed `device_preview` (incompatible with Dart 3.x); cleaned up `main.dart`
+- [x] **5.3** `cupertino_icons: ^1.0.8`
+- [x] **5.4** Android Gradle updated (Gradle 8.7, AGP 8.3.2, Kotlin 1.9.24, Java 17) — builds and runs
+- [x] **5.5** `Material3DemoScreen` added to gallery
+- [x] **5.6** All deprecated API usage fixed; `flutter analyze` zero issues
+
+---
+
+## Phase 6 — Tests ✅
+
+- [x] **6.1** Test color assertions updated to use `colorScheme`
+- [x] **6.2** iOS value overflow test
+- [x] **6.3** RTL chevron tests (LTR + RTL)
+- [x] **6.4** Web enabled/switch color tests
+- [x] **6.5** Compact tile tests (Android, iOS, Web)
+- [x] **6.6** Coverage gate raised 35% → 60%; actual coverage: **92%**
+- [x] **6.7** 108 unit tests passing; 17 integration tests passing on Android emulator
+
+---
+
+## Phase 7 — CI & Release Prep ✅
+
+- [x] **7.1** `actions/checkout@v4` in CI; coverage gate 60%
+- [x] **7.3** `version: 3.0.0` in `pubspec.yaml`
+- [x] **7.4** `CHANGELOG.md` entry for `3.0.0`
+- [x] **7.5** `flutter pub publish --dry-run` — passes (2 soft warnings: uncommitted files + .iml git state)
+- [ ] **7.6** Commit → merge `dev` → `master` → tag `v3.0.0`
+- [ ] **7.7** `flutter pub publish`
+
+---
+
+## Phase 8 — Post-Release: Issues & PRs
+
+Do this **after** `3.0.0` is live on pub.dev.
+
+### PRs to merge / close
+| PR | Title | Action |
+|----|-------|--------|
+| #193 | fix long IOSSettingsTile value text | Close — fixed in 2.1 |
+| #192 | flip RTL arrow | Close — fixed in 2.2 |
+| #191 | web platform pub.dev tag | Close — fixed in 2.3 |
+| #178 | compact SettingsTile | Close — implemented in 4.1 |
+
+### Issues to close
+| Issue | Title | Response |
+|-------|-------|----------|
+| #199 | Future Updates | Announce v3.0.0 |
+| #198 | White screen in release APK | Likely unrelated to package; ask for minimal repro, link v3 |
+| #197 | Make a new release | Announce v3.0.0 |
+| #196 | Chevron missing | Fixed in v3 (RTL fix) |
+| #194 | inactiveColour for switchTile | Fixed in 3.6 |
+| #189 | SettingsList alignment override | Fixed in 4.2 |
+| #188 | Switch ignores switchTheme | Fixed in 2.6 |
+| #186 | Title/value wrapping | Fixed in 2.1 |
+| #185 | Custom font support | Fixed in 4.3 |
+| #184 | iOS dirty dependencies | Verify in v3 |
+| #180 | trailing missing on Web switch | Fixed in 2.7 |
+| #179 | Chrome/web support | Fixed in 2.3 |
+| #176 | Scrollbar on wide screens | Verify fix still works; close |
+| #174 | enabled ignored on Web | Fixed in 2.4 |
+| #173 | Switch color on Web | Fixed in 2.5 |
+| #170 | RTL navigation arrow | Fixed in 2.2 |
+| #168 | Alternative for background/subtitle | Document in v3 release notes |
+| #160 | Windows layout | Improved |
+| #148 | macOS layout | Improved |
+| #139 | platform override ignored on macOS | Fixed in 2.9 |
+| #110 | Switch not toggling | Ask if still present in v3 |
+
+---
+
+## Session Log
+
+| Date | Session | What was done |
+|------|---------|---------------|
+| 2026-04-10 | 1 | Repo audit, CLAUDE.md written, V3_PLAN.md created |
+| 2026-04-10 | 2 | Phases 1–7 completed; all tests passing; ready to publish |

analysis_options.yaml

@@ -1,3 +1 @@
-analyzer:
-  enable-experiment:
-    - extension-methods
+include: package:flutter_lints/flutter.yaml

example/analysis_options.yaml

@@ -0,0 +1,3 @@
+analyzer:
+  exclude:
+    - lib/generated_plugin_registrant.dart