From 3a8652fd8d336588c723db356bfbc119c5bbded5 Mon Sep 17 00:00:00 2001 From: Jose Olarte III Date: Fri, 22 Aug 2025 22:07:37 +0800 Subject: [PATCH] docs: revert misplaced changelog --- BUILDING.md | 373 ---------------------------------------------------- 1 file changed, 373 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index d3522295..8cf98f80 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1184,146 +1184,6 @@ If you need to build manually or want to understand the individual steps: Prerequisites: Android Studio with Java SDK installed -### Android Safe Area Inset Implementation - -**Date**: 2025-08-22 -**Status**: ✅ **ACTIVE** - Android WebView safe area support - -TimeSafari now includes comprehensive safe area inset support for Android WebView, addressing the limitation that Android doesn't natively support CSS `env(safe-area-inset-*)` variables like iOS. - -#### Implementation Overview - -The Android safe area implementation consists of two complementary systems: - -1. **Native Android Plugin** (`SafeAreaPlugin.java`) - Provides native safe area measurements -2. **JavaScript Injection** (`safeAreaInset.js`) - Injects CSS custom properties for WebView compatibility - -#### Native Android Plugin - -**File**: `android/app/src/main/java/app/timesafari/safearea/SafeAreaPlugin.java` - -The native plugin provides accurate safe area measurements using Android's WindowInsets API: - -```java -@CapacitorPlugin(name = "SafeArea") -public class SafeAreaPlugin extends Plugin { - @PluginMethod - public void getSafeAreaInsets(PluginCall call) { - // Uses WindowInsets API for Android 11+ (API 30+) - // Provides fallback values for older versions - } -} -``` - -**Features**: -- Uses Android 11+ WindowInsets API for accurate measurements -- Provides status bar, navigation bar, and system bar insets -- Fallback values for older Android versions -- Capacitor plugin integration - -#### JavaScript Safe Area Injection - -**File**: `src/utils/safeAreaInset.js` - -The JavaScript implementation provides WebView-compatible safe area support: - -**Key Features**: -- **Platform Detection**: Only runs on Android WebView with Capacitor -- **Multiple Detection Methods**: Uses screen dimensions, visual viewport, and device characteristics -- **CSS Custom Properties**: Injects `--safe-area-inset-*` variables -- **Fallback Support**: Provides reasonable defaults when native API unavailable -- **Dynamic Updates**: Re-injects on orientation changes and resize events - -**Detection Methods**: -1. **Direct Comparison**: `screenHeight - windowHeight` -2. **Gesture Navigation**: Detects modern gesture-based navigation -3. **Visual Viewport**: Uses `window.visualViewport` for WebView accuracy -4. **Device-Specific**: Common resolution-based estimations - -#### CSS Integration - -The implementation provides both CSS environment variables and custom properties: - -```css -/* CSS Environment Variables (iOS-style) */ -env(safe-area-inset-top) -env(safe-area-inset-bottom) - -/* CSS Custom Properties (Android WebView) */ -var(--safe-area-inset-top, 0px) -var(--safe-area-inset-bottom, 0px) -``` - -**Usage Pattern**: -```css -/* Cross-platform safe area support */ -padding-top: max(env(safe-area-inset-top), var(--safe-area-inset-top, 0px)); -padding-bottom: max(env(safe-area-inset-bottom), var(--safe-area-inset-bottom, 0px)); -``` - -#### Dependencies Added - -**New Capacitor Plugin**: -- `@capacitor/status-bar`: Provides status bar information for safe area calculations - -**Development Dependencies**: -- `@commitlint/cli`: Commit message linting -- `@commitlint/config-conventional`: Conventional commit standards -- `husky`: Git hooks for pre-commit validation -- `lint-staged`: Staged file linting - -#### Build Integration - -The safe area implementation is automatically loaded in Capacitor builds: - -```typescript -// src/main.capacitor.ts -import "./utils/safeAreaInset"; -``` - -**Build Commands**: -```bash -# Standard Android builds (now include safe area support) -npm run build:android:dev -npm run build:android:prod - -# Asset validation (includes safe area assets) -npm run assets:validate:android -``` - -#### Testing Safe Area Implementation - -**Manual Testing**: -1. Build and run on Android device/emulator -2. Check safe area insets in different orientations -3. Verify CSS custom properties are injected -4. Test on devices with different navigation types - -**Debugging**: -```javascript -// Check if safe area script is running -console.log('Safe area script loaded:', window.Capacitor !== undefined); - -// Check injected CSS properties -getComputedStyle(document.documentElement).getPropertyValue('--safe-area-inset-top'); -``` - -#### Troubleshooting - -**Common Issues**: -- **No safe area detected**: Ensure running on Android with Capacitor -- **Incorrect measurements**: Check device orientation and navigation type -- **CSS not applied**: Verify CSS custom properties are injected - -**Debug Commands**: -```bash -# Check Android build includes safe area plugin -npm run build:android:dev - -# Validate assets include safe area support -npm run assets:validate:android -``` - #### Android Build Commands ```bash @@ -1596,145 +1456,6 @@ npm run lint-fix # Fix linting issues Use the commands above to check and fix code quality issues. -### Git Hooks and Commit Standards - -**Date**: 2025-08-22 -**Status**: ✅ **ACTIVE** - Automated code quality enforcement - -TimeSafari now includes comprehensive git hooks and commit standards to ensure code quality and consistent development practices. - -#### Husky Git Hooks - -**Configuration**: `package.json` husky section - -The project uses Husky to manage git hooks: - -```json -{ - "husky": { - "hooks": { - "pre-commit": "lint-staged", - "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" - } - } -} -``` - -**Available Hooks**: -- **pre-commit**: Runs lint-staged to check staged files -- **commit-msg**: Validates commit message format using commitlint - -#### Lint-Staged Configuration - -**Configuration**: `package.json` lint-staged section - -Automatically runs linting on staged files before commits: - -```json -{ - "lint-staged": { - "*.{js,ts,vue,css,md,json,yml,yaml}": "eslint --fix || true" - } -} -``` - -**Features**: -- Runs ESLint on JavaScript, TypeScript, Vue, CSS, Markdown, JSON, YAML files -- Automatically fixes auto-fixable issues -- Continues commit process even if some files can't be fixed - -#### Commit Message Standards - -**Configuration**: `package.json` commitlint section - -Uses conventional commit standards for consistent commit messages: - -```json -{ - "commitlint": { - "extends": ["@commitlint/config-conventional"] - } -} -``` - -**Commit Message Format**: -``` -type(scope): description - -[optional body] - -[optional footer] -``` - -**Supported Types**: -- `feat`: New features -- `fix`: Bug fixes -- `docs`: Documentation changes -- `style`: Code style changes (formatting, etc.) -- `refactor`: Code refactoring -- `test`: Adding or updating tests -- `chore`: Maintenance tasks - -**Examples**: -```bash -feat(android): add safe area inset support for Android WebView -fix(ios): resolve navigation bar overlap issue -docs(building): update Android build documentation -style(vue): fix component formatting -``` - -#### Development Workflow - -**Pre-commit Process**: -1. Stage files: `git add .` -2. Pre-commit hook runs automatically -3. Lint-staged checks and fixes staged files -4. Commit proceeds if all checks pass - -**Commit Message Validation**: -1. Write commit message: `git commit -m "type(scope): description"` -2. Commit-msg hook validates format -3. Commit proceeds if format is valid - -#### Bypassing Hooks (Emergency Only) - -**Warning**: Only use in emergency situations - -```bash -# Skip pre-commit hooks -git commit --no-verify -m "emergency: critical fix" - -# Skip all hooks -git commit --no-verify --no-verify-signatures -m "emergency: critical fix" -``` - -#### Troubleshooting Git Hooks - -**Common Issues**: -- **Hooks not running**: Ensure Husky is properly installed and configured -- **Lint errors blocking commit**: Fix linting issues or use `--no-verify` (emergency only) -- **Commit message rejected**: Follow conventional commit format - -**Debug Commands**: -```bash -# Check if Husky is installed -npm list husky - -# Test lint-staged manually -npx lint-staged - -# Test commitlint manually -echo "feat: test commit" | npx commitlint -``` - -#### Dependencies - -**Development Dependencies Added**: -- `husky`: Git hooks management -- `lint-staged`: Staged file linting -- `@commitlint/cli`: Commit message validation -- `@commitlint/config-conventional`: Conventional commit standards - ## Code Build Architecture ### Web Build Process @@ -1972,100 +1693,6 @@ npm run build:android:assets - [Web Build Scripts](docs/web-build-scripts.md) - [Build Troubleshooting](docs/build-troubleshooting.md) -## Recent Updates - -### CSS Safe Area Improvements (2025-08-22) - -**Status**: ✅ **COMPLETED** - Cross-platform safe area support - -TimeSafari's Vue components have been updated to provide consistent safe area support across all platforms, including Android WebView. - -#### Updated Components - -**Core Components**: -- `src/App.vue` - Main application layout -- `src/components/QuickNav.vue` - Bottom navigation -- `src/components/TopMessage.vue` - Top message display - -**View Components**: -- `src/views/ContactQRScanFullView.vue` - QR scanner full view -- `src/views/ContactQRScanShowView.vue` - QR scanner show view -- `src/views/DeepLinkErrorView.vue` - Deep link error handling -- `src/views/DeepLinkRedirectView.vue` - Deep link redirect - -#### CSS Pattern Implementation - -All components now use the cross-platform safe area pattern: - -```css -/* Before (iOS-only) */ -padding-top: env(safe-area-inset-top); - -/* After (Cross-platform) */ -padding-top: max(env(safe-area-inset-top), var(--safe-area-inset-top, 0px)); -``` - -**Benefits**: -- **iOS**: Uses native `env()` variables -- **Android**: Uses injected CSS custom properties -- **Web**: Falls back to 0px values -- **Future-proof**: Supports new platforms automatically - -#### Implementation Details - -**CSS Custom Properties**: -- `--safe-area-inset-top`: Top safe area inset -- `--safe-area-inset-bottom`: Bottom safe area inset -- `--safe-area-inset-left`: Left safe area inset -- `--safe-area-inset-right`: Right safe area inset - -**Fallback Strategy**: -```css -/* Primary: CSS environment variables (iOS) */ -/* Secondary: CSS custom properties (Android WebView) */ -/* Tertiary: Fallback value (Web, older browsers) */ -max(env(safe-area-inset-top), var(--safe-area-inset-top, 0px)) -``` - -#### Testing Cross-Platform Support - -**iOS Testing**: -```bash -npm run build:ios:dev -# Test on iOS simulator and device -# Verify env() variables work correctly -``` - -**Android Testing**: -```bash -npm run build:android:dev -# Test on Android emulator and device -# Verify CSS custom properties are injected -``` - -**Web Testing**: -```bash -npm run build:web:dev -# Test in browser -# Verify fallback values work correctly -``` - -#### Migration Guide - -**For New Components**: -```css -/* Use this pattern for all safe area references */ -padding-top: max(env(safe-area-inset-top), var(--safe-area-inset-top, 0px)); -padding-bottom: max(env(safe-area-inset-bottom), var(--safe-area-inset-bottom, 0px)); -padding-left: max(env(safe-area-inset-left), var(--safe-area-inset-left, 0px)); -padding-right: max(env(safe-area-inset-right), var(--safe-area-inset-right, 0px)); -``` - -**For Existing Components**: -1. Replace `env(safe-area-inset-*)` with the max() pattern -2. Test on all target platforms -3. Verify safe area behavior is consistent - --- ## Appendix: Build System Organization