@ -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
Jose Olarte III
2 weeks ago