@nativescript/vite 8.0.0-alpha.5 → 8.0.0-alpha.51

package/hmr/shared/runtime/dev-overlay.d.ts

@@ -1,38 +1,131 @@
-type HmrOverlayTone = 'info' | 'warn' | 'error';
-type HmrOverlayMode = 'hidden' | 'boot' | 'connection';
-export type HmrBootStage = 'placeholder' | 'probing-origin' | 'loading-entry-runtime' | 'configuring-import-map' | 'loading-runtime-bridge' | 'loading-core-bridge' | 'preloading-style-scope' | 'installing-css' | 'importing-main' | 'waiting-for-app' | 'app-root-committed' | 'ready' | 'error';
-export type HmrConnectionStage = 'connecting' | 'reconnecting' | 'synchronizing' | 'offline' | 'healthy';
-export type HmrOverlayStageInfo = {
-    detail?: string;
-    origin?: string;
-    progress?: number | null;
-    attempt?: number;
-    attempts?: number;
-};
-export type HmrOverlaySnapshot = {
-    visible: boolean;
-    mode: HmrOverlayMode;
-    badge: string;
-    title: string;
-    phase: string;
-    detail: string;
-    progress: number | null;
-    busy: boolean;
-    blocking: boolean;
-    tone: HmrOverlayTone;
-};
+import { type HmrBootStage, type HmrConnectionStage, type HmrOverlayPosition, type HmrOverlaySnapshot, type HmrOverlayStageInfo, type HmrUpdateStage } from './dev-overlay-snapshots.js';
+export { createBootOverlaySnapshot, createConnectionOverlaySnapshot, createUpdateOverlaySnapshot } from './dev-overlay-snapshots.js';
+export type { HmrBootStage, HmrConnectionStage, HmrOverlayPosition, HmrOverlaySnapshot, HmrOverlayStageInfo, HmrUpdateStage } from './dev-overlay-snapshots.js';
 type HmrOverlayApi = {
     ensureBootPage: (verbose?: boolean) => any | null;
     setBootStage: (stage: HmrBootStage, info?: HmrOverlayStageInfo) => HmrOverlaySnapshot;
     setConnectionStage: (stage: HmrConnectionStage, info?: HmrOverlayStageInfo) => HmrOverlaySnapshot;
+    setUpdateStage: (stage: HmrUpdateStage, info?: HmrOverlayStageInfo) => HmrOverlaySnapshot;
     hide: (reason?: string) => void;
     getSnapshot: () => HmrOverlaySnapshot;
 };
-export declare function createBootOverlaySnapshot(stage: HmrBootStage, info?: HmrOverlayStageInfo): HmrOverlaySnapshot;
-export declare function createConnectionOverlaySnapshot(stage: HmrConnectionStage, info?: HmrOverlayStageInfo): HmrOverlaySnapshot;
+/**
+ * Resolve the configured live-overlay position.
+ *
+ * Reads `globalThis.__NS_HMR_OVERLAY_POSITION__` so a project can
+ * override the default at boot time (e.g. inside `app.ts` before the
+ * Vite session bootstraps). Falls back to 'top' which gives the
+ * toast-style chip with a slide-in animation and safe-area padding.
+ */
+export declare function getHmrDevOverlayPosition(): HmrOverlayPosition;
+/**
+ * Imperative setter for the live-overlay position. Re-applies the
+ * current snapshot so the change is visible without waiting for the
+ * next HMR cycle. Useful during dev to A/B between top/bottom/center
+ * without restarting the app.
+ */
+export declare function setHmrDevOverlayPosition(position: HmrOverlayPosition): void;
+/**
+ * Returns the UIWindow level we use for the live/connection overlay. We lift
+ * above `UIWindowLevelAlert` so system alerts (and any app-presented modal)
+ * stack underneath. When the platform does not expose `UIWindowLevelAlert`
+ * we fall back to the documented constant value (2000).
+ */
+export declare function computeIosOverlayWindowLevel(baseAlert?: number | null): number;
+export type IosSafeInsets = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+export type IosRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type IosOverlayLayout = {
+    backdrop: IosRect;
+    panel: IosRect;
+    title: IosRect;
+    status: IosRect;
+};
+/**
+ * Layout math for the live overlay when it runs inside its own UIWindow.
+ * Pure, deterministic and independent of UIKit so we can verify the rules
+ * (max panel width, position-aware placement, safe-area clamping, sane
+ * defaults) from tests.
+ *
+ * `position` controls where the panel sits vertically:
+ *   - 'top':    hugs `safeInsets.top + toastVerticalInset` so the chip
+ *               sits just below the notch / Dynamic Island.
+ *   - 'bottom': hugs `viewHeight - safeInsets.bottom - panelHeight -
+ *               toastVerticalInset` so the chip sits just above the
+ *               home indicator / nav bar.
+ *   - 'center': original modal placement (vertically centered, clamped
+ *               so it never crosses the top safe-area inset).
+ */
+export declare function computeIosOverlayLayout(input: {
+    viewWidth: number;
+    viewHeight: number;
+    safeInsets?: IosSafeInsets | null;
+    titleHeight: number;
+    statusHeight: number;
+    maxPanelWidth?: number;
+    horizontalMargin?: number;
+    panelPadding?: number;
+    interLabelSpacing?: number;
+    minTopInset?: number;
+    position?: HmrOverlayPosition;
+    toastVerticalInset?: number;
+}): IosOverlayLayout;
+export type AndroidSafeAreaInsets = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+export type AndroidToastMargin = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/**
+ * Margin math for the in-tree (Android) live/update toast chip.
+ *
+ * NativeScript enables edge-to-edge on every Android activity
+ * (`@nativescript/core` → `application.android.ts` → `enableEdgeToEdge`),
+ * so the page content — and therefore the overlay wrapper we inject into
+ * it — extends underneath the status bar and navigation bar. A fixed
+ * top/bottom margin leaves the chip tucked behind the system bars, where
+ * it gets clipped (Android 15 / API 35 enforces edge-to-edge, so this is
+ * now the norm rather than the exception).
+ *
+ * This pure helper folds the system-bar safe-area insets into the chip's
+ * margin so the toast always clears the status bar (top position) /
+ * navigation bar (bottom position). It is deterministic and free of
+ * native deps so the rules stay unit-testable — the runtime reads the
+ * live insets via `readAndroidSafeAreaInsets()` and forwards them here.
+ *
+ *   - 'top':    margin.top    = baseVerticalInset + safeInsets.top
+ *   - 'bottom': margin.bottom = baseVerticalInset + safeInsets.bottom
+ *   - 'center': fixed `centerMargin` all around (vertically centered, so
+ *               it never approaches the system bars on normal viewports).
+ *
+ * Horizontal margins always include the relevant safe-area inset so a
+ * landscape display cutout / gesture pill doesn't clip the chip edge.
+ */
+export declare function computeAndroidToastMargin(input: {
+    position: HmrOverlayPosition;
+    safeInsets?: AndroidSafeAreaInsets | null;
+    baseVerticalInset?: number;
+    baseHorizontalInset?: number;
+    centerMargin?: number;
+}): AndroidToastMargin;
 export declare function ensureHmrDevOverlayRuntimeInstalled(verbose?: boolean): HmrOverlayApi;
 export declare function createHmrBootOverlayPage(verbose?: boolean): any | null;
 export declare function setHmrBootStage(stage: HmrBootStage, info?: HmrOverlayStageInfo): HmrOverlaySnapshot;
 export declare function setHmrConnectionStage(stage: HmrConnectionStage, info?: HmrOverlayStageInfo): HmrOverlaySnapshot;
+export declare function setHmrUpdateStage(stage: HmrUpdateStage, info?: HmrOverlayStageInfo): HmrOverlaySnapshot;
 export declare function hideHmrDevOverlay(reason?: string): void;
-export {};