Merge pull request #583 from qeeqez/feature/v8-active-state

v8 visible state

Author: heyqbnk

.changeset/eleven-ducks-carry.md

@@ -0,0 +1,5 @@
+---
+"@telegram-apps/sdk": minor
+---
+
+Add functionality related to the mini apps active state.

.changeset/strong-scissors-watch.md

@@ -0,0 +1,5 @@
+---
+"@telegram-apps/bridge": minor
+---
+
+Add `visibility_changed` event.

apps/docs/packages/telegram-apps-sdk/2-x/components/mini-app.md

@@ -159,7 +159,7 @@ if (miniApp.setBackgroundColor.isAvailable()) {
 ```
 
 ```ts [Functions]
-import { 
+import {
   setMiniAppBackgroundColor,
   miniAppBackgroundColor,
 } from '@telegram-apps/sdk';
@@ -172,6 +172,27 @@ if (setMiniAppBackgroundColor.isAvailable()) {
 
 :::
 
+## Active State
+
+The mini application becomes inactive if it is wrapped into the bottom native Telegram client tray
+or if the currently active tab of the mini apps browser is changed to another one.
+
+To track if the mini application is currently active, use the `isActive` signal.
+
+::: code-group
+
+```ts [Variable]
+miniApp.isActive();
+```
+
+```ts [Functions]
+import { isMiniAppActive } from '@telegram-apps/sdk';
+
+isMiniAppActive()
+```
+
+:::
+
 ## Methods
 
 ### `close`

apps/docs/platform/events.md

@@ -349,6 +349,19 @@ user started dragging the application or called the expansion method.
 > application window. You should probably use a stable height instead of the current one, or handle
 > this problem in another way.
 
+### `visibility_changed`
+
+Available since: **v8.0**
+
+Active state assumes that the native Telegram client is currently working with the
+current mini application. It is important to note that this is not related to the
+mini application’s visibility, but rather its selection among other currently opened
+mini applications.
+
+| Field      | Type      | Description                                       |
+|------------|-----------|---------------------------------------------------|
+| is_visible | `boolean` | Indicates if the application is currently active. |
+
 ### `write_access_requested`
 
 Available since: **v6.9**

packages/bridge/src/events/types/events.ts

@@ -365,6 +365,22 @@ export interface Events {
      */
     is_state_stable: boolean;
   };
+  /**
+   * Occurs whenever the mini app becomes active or inactive.
+   *
+   * Active state assumes that the native Telegram client is currently working with the
+   * current mini application. It is important to note that this is not related to the
+   * mini application’s visibility, but rather its selection among other currently opened
+   * mini applications.
+   * @since v8.0
+   * @see https://docs.telegram-mini-apps.com/platform/events#visibility_changed
+   */
+  visibility_changed: {
+    /**
+     * Indicates if the application is currently active.
+     */
+    is_visible: boolean;
+  };
   /**
    * Application received write access request status.
    * @since v6.9

packages/sdk/src/scopes/components/mini-app/exports.ts

@@ -11,13 +11,15 @@ export {
 } from './methods.js';
 export {
   backgroundColor as miniAppBackgroundColor,
+  backgroundColorRGB as miniAppBackgroundColorRGB,
   bottomBarColor as miniAppBottomBarColor,
   bottomBarColorRGB as miniAppBottomBarColorRGB,
   headerColor as miniAppHeaderColor,
   headerColorRGB as miniAppHeaderColorRGB,
   isMounted as isMiniAppMounted,
   isCssVarsBound as isMiniAppCssVarsBound,
   isDark as isMiniAppDark,
+  isActive as isMiniAppActive,
   state as miniAppState,
 } from './signals.js';
 export type {

packages/sdk/src/scopes/components/mini-app/methods.ts

@@ -6,9 +6,13 @@ import {
   deleteCssVar,
   setCssVar,
   supports,
+  on,
+  off,
+  type EventListener,
   type RGB,
   type BottomBarColor,
-  type BackgroundColor, MethodName,
+  type BackgroundColor,
+  type MethodName,
 } from '@telegram-apps/bridge';
 import { isRGB } from '@telegram-apps/transformers';
 import { isPageReload } from '@telegram-apps/navigation';
@@ -31,6 +35,7 @@ import {
   headerColorRGB,
   bottomBarColorRGB,
   backgroundColorRGB,
+  isActive,
 } from './signals.js';
 import type { GetCssVarNameFn, HeaderColor, State } from './types.js';
 
@@ -39,6 +44,7 @@ type StorageValue = State;
 const SET_BG_COLOR_METHOD = 'web_app_set_background_color';
 const SET_BOTTOM_BAR_COLOR_METHOD = 'web_app_set_bottom_bar_color';
 const SET_HEADER_COLOR_METHOD = 'web_app_set_header_color';
+const VISIBILITY_CHANGED_EVENT = 'visibility_changed';
 const COMPONENT_NAME = 'miniApp';
 
 const isSupportedSchema = {
@@ -138,6 +144,11 @@ export const close = wrapBasic('close', (returnBack?: boolean): void => {
   postEvent('web_app_close', { return_back: returnBack });
 });
 
+const onVisibilityChanged: EventListener<'visibility_changed'> = (data) => {
+  isActive.set(data.is_visible);
+  saveState();
+};
+
 /**
  * Mounts the component.
  *
@@ -165,6 +176,9 @@ export const mount = wrapSupported(
       setBackgroundColor.ifAvailable(s ? s.backgroundColor : 'bg_color');
       setBottomBarColor.ifAvailable(s ? s.bottomBarColor : 'bottom_bar_bg_color');
       setHeaderColor.ifAvailable(s ? s.headerColor : 'bg_color');
+      isActive.set(s ? s.isActive : true);
+
+      on(VISIBILITY_CHANGED_EVENT, onVisibilityChanged);
 
       isMounted.set(true);
     }
@@ -280,5 +294,6 @@ export const setHeaderColor = wrapComplete(
  * Unmounts the component, removing the listener, saving the component state in the local storage.
  */
 export function unmount(): void {
+  off(VISIBILITY_CHANGED_EVENT, onVisibilityChanged);
   isMounted.set(false);
 }

packages/sdk/src/scopes/components/mini-app/signals.ts

@@ -91,11 +91,17 @@ export const isDark = computed(() => {
   return color ? isColorDark(color) : false;
 });
 
+/**
+ * Signal indicating if the mini app is currently active.
+ */
+export const isActive = signal(true);
+
 /**
  * Complete component state.
  */
 export const state = computed<State>(() => ({
   backgroundColor: backgroundColor(),
   bottomBarColor: bottomBarColor(),
   headerColor: headerColor(),
+  isActive: isActive(),
 }));

packages/sdk/src/scopes/components/mini-app/types.ts

@@ -9,6 +9,7 @@ export interface State {
   backgroundColor: BackgroundColor;
   bottomBarColor: BottomBarColor;
   headerColor: HeaderColor;
+  isActive: boolean;
 }
 
 export interface GetCssVarNameFn {

packages/sdk/src/scopes/components/viewport/methods/mounting/mount.ts

@@ -9,7 +9,7 @@ import {
   CSA_CHANGED_EVENT,
   FS_CHANGED_EVENT,
   SA_CHANGED_EVENT,
-  VIEWPORT_CHANGED_EVENT
+  VIEWPORT_CHANGED_EVENT,
 } from '../../const.js';
 import { isMounted, mountPromise, mountError } from '../../signals/mounting.js';
 import { getStateFromStorage, setState } from '../../signals/state.js';
@@ -20,7 +20,12 @@ import { requestSafeAreaInsets } from '../static/requestSafeAreaInsets.js';
 import { requestViewport } from '../static/requestViewport.js';
 import type { State } from '../../types.js';
 
-import { onContentSafeAreaChanged, onFullscreenChanged, onSafeAreaChanged, onViewportChanged } from './shared.js';
+import {
+  onContentSafeAreaChanged,
+  onFullscreenChanged,
+  onSafeAreaChanged,
+  onViewportChanged,
+} from './shared.js';
 
 /**
  * Mounts the Viewport component.