@propbinder/mobile-design 0.2.47 → 0.2.50

package/src/components/shared/mobile-modal-base.ts

@@ -0,0 +1,457 @@
+import { input, output, Directive, OnInit, OnDestroy, inject, ViewChild } from '@angular/core';
+import { ModalController, IonContent } from '@ionic/angular/standalone';
+import { Keyboard } from '@capacitor/keyboard';
+
+/**
+ * MobileModalBase
+ *
+ * Shared base class for mobile modal components.
+ * Provides consistent modal behavior, state management, and keyboard handling.
+ *
+ * **Key Features:**
+ * - Loading and error state management
+ * - Header configuration (title, meta)
+ * - Automatic keyboard height tracking (iOS/Android)
+ * - Fixed bottom component support
+ * - Consistent close behavior
+ *
+ * **Usage:**
+ * ```typescript
+ * export class MyModalComponent extends MobileModalBase {
+ *   constructor() {
+ *     super();
+ *   }
+ * }
+ * ```
+ *
+ * @internal This is a base class and should not be used directly.
+ */
+@Directive()
+export abstract class MobileModalBase implements OnInit, OnDestroy {
+  protected modalController = inject(ModalController);
+
+  /**
+   * Reference to IonContent for accessing scroll element
+   */
+  @ViewChild(IonContent, { read: IonContent }) protected ionContent?: IonContent;
+
+  /**
+   * ResizeObserver for tracking fixed bottom height
+   */
+  private fixedBottomObserver?: ResizeObserver;
+
+  /**
+   * Flag to prevent ResizeObserver from updating padding during keyboard animations
+   */
+  private isKeyboardAnimating = false;
+
+  /**
+   * Loading state - when true, shows loading indicator
+   * @default false
+   */
+  loading = input<boolean>(false);
+
+  /**
+   * Error state - when set, shows error message
+   * @default undefined
+   */
+  error = input<string | undefined>();
+
+  /**
+   * Modal header title
+   * @default ''
+   */
+  headerTitle = input<string>('');
+
+  /**
+   * Modal header metadata (subtitle/secondary text)
+   * @default ''
+   */
+  headerMeta = input<string>('');
+
+  /**
+   * Accessibility label for close button
+   * @default 'Close'
+   */
+  closeButtonLabel = input<string>('Close');
+
+  /**
+   * Enable automatic keyboard height tracking
+   * When enabled, sets --keyboard-height CSS variable for sliding content
+   * @default false
+   */
+  enableKeyboardHandling = input<boolean>(false);
+
+  /**
+   * Whether modal has a fixed bottom component
+   * Used to manage spacing and keyboard interactions
+   * @default false
+   */
+  hasFixedBottom = input<boolean>(false);
+
+  /**
+   * Content padding for modal content
+   * Controls padding inside .modal-main-content
+   * - '0' (default) - No padding, use ds-mobile-section for content organization
+   * - '20px' - Legacy padding for content without sections
+   * - Any custom CSS padding value
+   *
+   * @default '0'
+   */
+  contentPadding = input<string>('0');
+
+  /**
+   * Enable auto-height behavior for bottom sheets
+   * When true, sets [fullscreen]="false" on ion-content and enforces flex: 0 0 auto
+   * @default false
+   */
+  isAutoHeight = input<boolean>(false);
+
+  /**
+   * Controls how modal content behaves when the keyboard opens.
+   * - 'follow': content is pushed to follow keyboard movement
+   * - 'overlay': keyboard/footer overlays lower content (no auto scroll push)
+   * @default 'follow'
+   */
+  keyboardContentBehavior = input<'follow' | 'overlay'>('follow');
+
+  /**
+   * Emitted when modal is closed
+   */
+  closed = output<void>();
+
+  /**
+   * Emitted when keyboard is about to show
+   * Provides keyboard height in pixels
+   * Child components can listen to this to react to keyboard appearance
+   */
+  keyboardWillShow = output<number>();
+
+  /**
+   * Emitted when keyboard is about to hide
+   * Child components can listen to this to react to keyboard dismissal
+   */
+  keyboardWillHide = output<void>();
+
+  ngOnInit(): void {
+    if (this.enableKeyboardHandling()) {
+      this.setupKeyboardListeners();
+    }
+
+    if (this.hasFixedBottom()) {
+      this.setupFixedBottomObserver();
+    }
+  }
+
+  ngOnDestroy(): void {
+    if (this.enableKeyboardHandling()) {
+      this.cleanupKeyboardListeners();
+    }
+
+    if (this.fixedBottomObserver) {
+      this.fixedBottomObserver.disconnect();
+    }
+  }
+
+  /**
+   * Close the modal
+   * Emits closed event and dismisses the modal
+   */
+  close(): void {
+    this.closed.emit();
+    this.modalController.dismiss();
+  }
+
+  /**
+   * Set up keyboard event listeners to adjust component position
+   * Uses --keyboard-height for fixed bottom composer and adds padding to scroll area.
+   * Adjusts scroll position so content smoothly follows the keyboard up (like Messenger/Telegram).
+   * Only responds if this modal is the currently active (top-most) modal.
+   * @protected
+   */
+  protected setupKeyboardListeners(): void {
+    Keyboard.addListener('keyboardWillShow', async (info) => {
+      // Check if this modal is the top-most modal
+      const topModal = await this.modalController.getTop();
+      if (!topModal || !this.isThisModal(topModal)) {
+        // console.log('[MobileModalBase] Keyboard event ignored - not top modal');
+        return; // Not the active modal, ignore keyboard event
+      }
+      
+      // console.log('[MobileModalBase] 🎹 Keyboard showing, height:', info.keyboardHeight);
+      // Set flag to prevent ResizeObserver from interfering
+      this.isKeyboardAnimating = true;
+
+      // Set global keyboard height FIRST so ResizeObserver can use it
+      document.documentElement.style.setProperty('--keyboard-height', `${info.keyboardHeight}px`);
+
+      // Update padding immediately to include keyboard height
+      if (this.ionContent) {
+        try {
+          const scrollElement = await this.ionContent.getScrollElement();
+          if (scrollElement) {
+            // Get current fixed bottom height and add keyboard height
+            const fixedBottomHeight = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--fixed-bottom-height') || '0');
+            const totalPadding = this.getScrollPadding(fixedBottomHeight, info.keyboardHeight);
+            scrollElement.style.paddingBottom = `${totalPadding}px`;
+            // console.log('[MobileModalBase] Updated padding:', totalPadding, '(fixed:', fixedBottomHeight, '+ keyboard:', info.keyboardHeight, ')');
+
+            // In overlay mode, keep content stationary and let keyboard/footer overlap.
+            if (this.isOverlayBehavior()) {
+              this.isKeyboardAnimating = false;
+            } else {
+              // Store current scroll position before keyboard animation
+              const currentScrollTop = scrollElement.scrollTop;
+              // Animate scroll position to match keyboard
+              const startTime = performance.now();
+              const duration = 300; // Match keyboard animation duration
+
+              const animateScroll = (currentTime: number) => {
+                const elapsed = currentTime - startTime;
+                const progress = Math.min(elapsed / duration, 1);
+
+                // Ease-out cubic (matches iOS/Android keyboard animation curve)
+                const easeProgress = 1 - Math.pow(1 - progress, 3);
+
+                // Scroll down by keyboard height so content "follows" keyboard up
+                scrollElement.scrollTop = currentScrollTop + info.keyboardHeight * easeProgress;
+
+                if (progress < 1) {
+                  requestAnimationFrame(animateScroll);
+                } else {
+                  // Animation complete - re-enable ResizeObserver
+                  // console.log('[MobileModalBase] ✅ Keyboard animation complete');
+                  this.isKeyboardAnimating = false;
+                }
+              };
+
+              requestAnimationFrame(animateScroll);
+            }
+          }
+        } catch (e) {
+          // console.log('[MobileModalBase] Could not access scroll element:', e);
+          this.isKeyboardAnimating = false;
+        }
+      } else {
+        this.isKeyboardAnimating = false;
+      }
+
+      // Emit event for child components to react to keyboard appearance
+      this.keyboardWillShow.emit(info.keyboardHeight);
+    }).catch((e) => {
+      // console.log('[MobileModalBase] Keyboard listeners not available:', e);
+    });
+
+    Keyboard.addListener('keyboardWillHide', async () => {
+      // Check if this modal is the top-most modal
+      const topModal = await this.modalController.getTop();
+      if (!topModal || !this.isThisModal(topModal)) {
+        // console.log('[MobileModalBase] Keyboard hide event ignored - not top modal');
+        return; // Not the active modal, ignore keyboard event
+      }
+      
+      // console.log('[MobileModalBase] 🎹 Keyboard hiding');
+      // Set flag to prevent ResizeObserver from interfering
+      this.isKeyboardAnimating = true;
+
+      // Get keyboard height before resetting (for scroll position adjustment)
+      const keyboardHeight = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--keyboard-height') || '0');
+
+      // Reset keyboard height variable FIRST
+      document.documentElement.style.setProperty('--keyboard-height', '0px');
+
+      // Update padding immediately to remove keyboard height
+      if (this.ionContent) {
+        try {
+          const scrollElement = await this.ionContent.getScrollElement();
+          if (scrollElement) {
+            // Get current fixed bottom height (without keyboard)
+            const fixedBottomHeight = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--fixed-bottom-height') || '0');
+            const totalPadding = this.getScrollPadding(fixedBottomHeight, 0);
+            scrollElement.style.paddingBottom = `${totalPadding}px`;
+            // console.log('[MobileModalBase] Removed keyboard padding, now:', fixedBottomHeight);
+
+            // In overlay mode, keep content stationary and let keyboard/footer overlap.
+            if (this.isOverlayBehavior()) {
+              this.isKeyboardAnimating = false;
+            } else {
+              // Store current scroll position
+              const currentScrollTop = scrollElement.scrollTop;
+              // Animate scroll position back
+              const startTime = performance.now();
+              const duration = 300;
+
+              const animateScroll = (currentTime: number) => {
+                const elapsed = currentTime - startTime;
+                const progress = Math.min(elapsed / duration, 1);
+
+                // Ease-out cubic
+                const easeProgress = 1 - Math.pow(1 - progress, 3);
+
+                // Scroll up by keyboard height (reverse the push)
+                const newScrollTop = currentScrollTop - keyboardHeight * easeProgress;
+                scrollElement.scrollTop = Math.max(0, newScrollTop);
+
+                if (progress < 1) {
+                  requestAnimationFrame(animateScroll);
+                } else {
+                  // Animation complete - re-enable ResizeObserver
+                  // console.log('[MobileModalBase] ✅ Keyboard hide animation complete');
+                  this.isKeyboardAnimating = false;
+                }
+              };
+
+              requestAnimationFrame(animateScroll);
+            }
+          }
+        } catch (e) {
+          // console.log('[MobileModalBase] Could not access scroll element:', e);
+          this.isKeyboardAnimating = false;
+        }
+      } else {
+        this.isKeyboardAnimating = false;
+      }
+
+      // Emit event for child components to react to keyboard dismissal
+      this.keyboardWillHide.emit();
+    }).catch((e) => {
+      // console.log('[MobileModalBase] Keyboard listeners not available:', e);
+    });
+  }
+
+  /**
+   * Set up ResizeObserver to track fixed bottom height and apply as CSS variable
+   * This allows dynamic bottom padding that adjusts to content
+   * @protected
+   */
+  protected async setupFixedBottomObserver(): Promise<void> {
+    // Use measured fixed-bottom height directly; safe-area tuning is handled in CSS.
+    const offset = 0;
+
+    // Small delay to ensure DOM is ready
+    setTimeout(async () => {
+      const fixedBottom = document.querySelector('.modal-fixed-bottom');
+      // console.log('[MobileModalBase] Fixed bottom element:', fixedBottom, 'Offset:', offset);
+
+      if (fixedBottom) {
+        this.fixedBottomObserver = new ResizeObserver(async (entries) => {
+          // Skip updates during keyboard animations to prevent conflicts
+          if (this.isKeyboardAnimating) {
+            // console.log('[MobileModalBase] 🚫 ResizeObserver - skipping update during keyboard animation');
+            return;
+          }
+
+          // console.log('[MobileModalBase] ✅ ResizeObserver - processing update');
+          for (const entry of entries) {
+            // Use getBoundingClientRect to get full border-box height (includes padding)
+            const height = (entry.target as HTMLElement).getBoundingClientRect().height;
+            // Add platform-specific offset
+            const totalHeight = height + offset;
+
+            // CRITICAL: Include keyboard height if keyboard is visible!
+            const keyboardHeight = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--keyboard-height') || '0');
+            const paddingWithKeyboard = this.getScrollPadding(totalHeight, keyboardHeight);
+
+            // console.log('[MobileModalBase] ResizeObserver - height:', height, 'totalHeight:', totalHeight, 'keyboard:', keyboardHeight, 'finalPadding:', paddingWithKeyboard);
+            document.documentElement.style.setProperty('--fixed-bottom-height', `${totalHeight}px`);
+
+            // Also update scroll element padding (including keyboard height!)
+            if (this.ionContent) {
+              try {
+                const scrollElement = await this.ionContent.getScrollElement();
+                if (scrollElement) {
+                  // Get PREVIOUS padding to calculate the difference
+                  const previousPadding = parseFloat(scrollElement.style.paddingBottom || '0');
+                  const paddingDifference = paddingWithKeyboard - previousPadding;
+
+                  // Update padding
+                  scrollElement.style.paddingBottom = `${paddingWithKeyboard}px`;
+
+                  // CRITICAL: Adjust scroll to maintain visual position
+                  // When padding increases, we need to scroll down by the same amount
+                  if (!this.isOverlayBehavior() && paddingDifference !== 0) {
+                    const currentScrollTop = scrollElement.scrollTop;
+                    scrollElement.scrollTop = currentScrollTop + paddingDifference;
+                    // console.log('[MobileModalBase] Adjusted scroll by', paddingDifference, 'px (from', currentScrollTop, 'to', scrollElement.scrollTop, ')');
+                  }
+                }
+              } catch (e) {
+                // console.log('[MobileModalBase] Could not update scroll element padding:', e);
+              }
+            }
+          }
+        });
+
+        this.fixedBottomObserver.observe(fixedBottom);
+
+        // Set initial height immediately (with platform-specific offset)
+        const initialHeight = fixedBottom.getBoundingClientRect().height;
+        const initialTotal = initialHeight + offset;
+        // console.log('[MobileModalBase] Initial height:', initialHeight, 'initialTotal:', initialTotal);
+        document.documentElement.style.setProperty('--fixed-bottom-height', `${initialTotal}px`);
+
+        // Set initial scroll element padding
+        if (this.ionContent) {
+          try {
+            const scrollElement = await this.ionContent.getScrollElement();
+            if (scrollElement) {
+              // Include keyboard height if present
+              const keyboardHeight = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--keyboard-height') || '0');
+              const paddingWithKeyboard = this.getScrollPadding(initialTotal, keyboardHeight);
+              scrollElement.style.paddingBottom = `${paddingWithKeyboard}px`;
+            }
+          } catch (e) {
+            // console.log('[MobileModalBase] Could not set initial scroll element padding:', e);
+          }
+        }
+      }
+    }, 100);
+  }
+
+  /**
+   * Clean up keyboard event listeners
+   * @protected
+   */
+  protected cleanupKeyboardListeners(): void {
+    Keyboard.removeAllListeners().catch((e) => {
+      // console.log('[MobileModalBase] Keyboard cleanup not available:', e);
+    });
+  }
+
+  /**
+   * Check if the given modal element is this modal component's parent modal
+   * @protected
+   */
+  protected isThisModal(modalElement: HTMLIonModalElement): boolean {
+    // The modal element should contain this component
+    // We traverse up from the component to find the ion-modal
+    let element = document.querySelector('ds-mobile-modal-base')?.parentElement;
+    while (element) {
+      if (element === modalElement) {
+        return true;
+      }
+      if (element.tagName === 'ION-MODAL') {
+        return element === modalElement;
+      }
+      element = element.parentElement;
+    }
+    return false;
+  }
+
+  /**
+   * Returns true when keyboard should overlay content without push-scrolling.
+   */
+  private isOverlayBehavior(): boolean {
+    return this.keyboardContentBehavior() === 'overlay';
+  }
+
+  /**
+   * Computes scroll bottom inset for current keyboard behavior.
+   */
+  private getScrollPadding(fixedBottomHeight: number, keyboardHeight: number): number {
+    if (this.isOverlayBehavior()) {
+      return fixedBottomHeight;
+    }
+    return fixedBottomHeight + keyboardHeight;
+  }
+}

package/src/components/shared/mobile-page-base.ts

@@ -0,0 +1,204 @@
+import { input, computed, signal, Directive, OnDestroy } from '@angular/core';
+import { Network } from '@capacitor/network';
+
+/**
+ * Content width preset values
+ * - 'narrow' - 640px max width (reading content)
+ * - 'standard' - 1024px max width (default)
+ * - 'wide' - 1440px max width (dashboards)
+ * - 'full' - 100% width (no max)
+ */
+export type ContentWidth = 'narrow' | 'standard' | 'wide' | 'full';
+
+/**
+ * Network status type
+ */
+export type NetworkStatus = 'online' | 'offline' | 'unknown';
+
+/**
+ * MobilePageBase
+ * 
+ * Shared base class for mobile page components (ds-mobile-page-main, ds-mobile-page-details).
+ * Provides consistent content width control and network status monitoring across all page types.
+ * 
+ * **Padding Strategy:**
+ * - All pages use 20px horizontal padding globally
+ * - For tappable lists, use negative margins (e.g., margin: 0 -8px) to create full-width sections
+ * - This approach simplifies padding management and provides consistency
+ * 
+ * **Network Monitoring:**
+ * - Tracks online/offline status via Capacitor Network plugin (native) or browser API (web)
+ * - Exposes `isOffline()` computed signal for easy consumption by child components
+ * - Pages can use this to conditionally disable features or show offline indicators
+ * 
+ * @internal This is a base class and should not be used directly.
+ */
+@Directive()
+export abstract class MobilePageBase implements OnDestroy {
+  /**
+   * Shows a loading overlay above page content area.
+   *
+   * Non-breaking: defaults to false, so existing pages are unchanged
+   * until they explicitly opt in.
+   */
+  contentLoading = input<boolean>(false);
+
+  /**
+   * Maximum content width (desktop only)
+   * 
+   * **Options:**
+   * - `'narrow'` (640px) - For reading content, forms
+   * - `'standard'` (1024px) - Default for most pages
+   * - `'wide'` (1440px) - For dashboards, tables
+   * - `'full'` - No max-width constraint
+   * 
+   * **Note:** Only applies on desktop (>= 768px). Mobile is always full width.
+   * 
+   * @default 'standard'
+   * 
+   * @example
+   * ```html
+   * <!-- Narrow reading layout -->
+   * <ds-mobile-page-main title="Article" contentWidth="narrow">
+   * 
+   * <!-- Wide dashboard -->
+   * <ds-mobile-page-main title="Dashboard" contentWidth="wide">
+   * ```
+   */
+  contentWidth = input<ContentWidth>('standard');
+
+  /**
+   * Resolved max-width value (computed)
+   * Maps preset values to pixel values
+   * 
+   * @internal
+   */
+  protected maxWidthValue = computed(() => {
+    const w = this.contentWidth();
+    
+    const widthMap: Record<ContentWidth, string> = {
+      'narrow': '640px',
+      'standard': '1024px',
+      'wide': '1440px',
+      'full': '100%'
+    };
+    
+    return widthMap[w];
+  });
+
+  /**
+   * Network status signal
+   * Tracks current online/offline state
+   * 
+   * @internal
+   */
+  protected networkStatus = signal<NetworkStatus>('unknown');
+
+  /**
+   * Is the device currently offline?
+   * Public computed signal for consumption by child components and pages
+   * 
+   * @example
+   * ```typescript
+   * // In a page component
+   * @ViewChild(DsMobilePageMainComponent) pageComponent!: DsMobilePageMainComponent;
+   * 
+   * get isOffline() {
+   *   return this.pageComponent?.isOffline();
+   * }
+   * ```
+   */
+  public isOffline = computed(() => this.networkStatus() === 'offline');
+
+  /**
+   * Is the device currently online?
+   * Public computed signal for consumption by child components and pages
+   */
+  public isOnline = computed(() => this.networkStatus() === 'online');
+
+  /**
+   * Network listener ID for Capacitor Network plugin
+   * Used to clean up listener on destroy
+   * 
+   * @internal
+   */
+  private networkListenerId?: string;
+
+  /**
+   * Browser API event handlers
+   * Stored as class properties for proper cleanup
+   * 
+   * @internal
+   */
+  private handleOnline = () => {
+    this.networkStatus.set('online');
+  };
+
+  private handleOffline = () => {
+    this.networkStatus.set('offline');
+  };
+
+  /**
+   * Initialize network status monitoring
+   * Uses Capacitor Network plugin for native apps, browser API for web
+   * 
+   * @param isNative - Whether running on native platform (iOS/Android)
+   * @internal Called by child components in ngAfterViewInit
+   */
+  protected async initNetworkMonitoring(isNative: boolean): Promise<void> {
+    if (isNative) {
+      try {
+        // Try to use Capacitor Network plugin for native apps
+        const status = await Network.getStatus();
+        this.networkStatus.set(status.connected ? 'online' : 'offline');
+        
+        // Listen for network status changes
+        const listener = await Network.addListener('networkStatusChange', (status: any) => {
+          this.networkStatus.set(status.connected ? 'online' : 'offline');
+        });
+        
+        // Store listener ID for cleanup
+        this.networkListenerId = 'networkStatusChange';
+      } catch (error) {
+        // Fallback to browser API if Capacitor plugin fails
+        console.warn('Capacitor Network plugin not available, falling back to browser API', error);
+        this.initBrowserNetworkMonitoring();
+      }
+    } else {
+      // Use browser API for web/PWA
+      this.initBrowserNetworkMonitoring();
+    }
+  }
+
+  /**
+   * Initialize browser-based network monitoring
+   * Uses navigator.onLine and window events
+   * 
+   * @internal
+   */
+  private initBrowserNetworkMonitoring(): void {
+    // Set initial status from browser
+    this.networkStatus.set(navigator.onLine ? 'online' : 'offline');
+    
+    // Listen for online/offline events
+    window.addEventListener('online', this.handleOnline);
+    window.addEventListener('offline', this.handleOffline);
+  }
+
+  /**
+   * Cleanup network monitoring listeners
+   * Called automatically on component destroy
+   */
+  ngOnDestroy(): void {
+    // Clean up Capacitor listener if it exists
+    if (this.networkListenerId) {
+      Network.removeAllListeners().catch((err: any) => {
+        console.warn('Failed to remove network listeners', err);
+      });
+    }
+    
+    // Clean up browser event listeners
+    window.removeEventListener('online', this.handleOnline);
+    window.removeEventListener('offline', this.handleOffline);
+  }
+}