Merge pull request #392 from Telegram-Mini-Apps/feature/v7-7

Add Mini Apps v7.7 features
Telegram-Mini-Apps · Jul 7, 2024 · 8a9664e · 8a9664e
2 parents 8b3f83d + 54adc6f
commit 8a9664e
Show file tree

Hide file tree

Showing 27 changed files with 352 additions and 25 deletions.
diff --git a/.changeset/real-eagles-wave.md b/.changeset/real-eagles-wave.md
@@ -0,0 +1,7 @@
+---
+"@telegram-apps/sdk-react": minor
+"@telegram-apps/sdk-solid": minor
+"@telegram-apps/sdk": minor
+---
+
+Add the `SwipeBehavior` component, related hooks and HOCs.
diff --git a/apps/docs/.vitepress/packages.ts b/apps/docs/.vitepress/packages.ts
@@ -33,6 +33,7 @@ export const packagesSidebar = {
               Popup: 'popup',
               QRScanner: 'qr-scanner',
               SettingsButton: 'settings-button',
+              SwipeBehavior: 'swipe-behavior',
               ThemeParams: 'theme-params',
               Utils: 'utils',
               Viewport: 'viewport',

diff --git a/apps/docs/packages/telegram-apps-sdk/components/mini-app.md b/apps/docs/packages/telegram-apps-sdk/components/mini-app.md
@@ -124,6 +124,14 @@ Closes the Mini App.
 miniApp.close();
 ```
 
+If you would like to wrap the application into the bottom app bar, but not to close it, 
+consider using the first argument `returnBack: boolean`.
+
+```ts
+// Will wrap the application into the bottom app bar.
+miniApp.close(true);
+```
+
 ## Other Methods
 
 ### `sendData`

diff --git a/apps/docs/packages/telegram-apps-sdk/components/swipe-behavior.md b/apps/docs/packages/telegram-apps-sdk/components/swipe-behavior.md
@@ -0,0 +1,41 @@
+# `SwipeBehavior`
+
+Implements Telegram Mini Apps swipe behavior functionality.
+
+## Initialization
+
+To initialize the component, use the `initSwipeBehavior` function:
+
+```typescript
+import { initSwipeBehavior } from '@telegram-apps/sdk';
+
+const [swipeBehavior] = initSwipeBehavior();  
+```
+
+## Vertical Swipe
+
+By default, users are allowed to hide the application just by swiping the application down.
+To prevent a possible closure, you can disable this behavior by calling the `disableVerticalSwipe()` method, or enable via the `enableVerticalSwipe()` method. In turn,
+both of these methods update the `isVerticalSwipeEnabled` property:
+
+```typescript  
+swipeBehaviour.enableVerticalSwipe();
+console.log(swipeBehaviour.isVerticalSwipeEnabled); // true  
+
+swipeBehaviour.disableVerticalSwipe();
+console.log(swipeBehaviour.isVerticalSwipeEnabled); // false
+```
+
+## Events
+
+List of events, which could be [tracked](../components#events):
+
+| Event                           | Listener                   | Triggered when                            |
+|---------------------------------|----------------------------|-------------------------------------------|
+| `change`                        | `() => void`               | Something in component changed            |
+| `change:isVerticalSwipeEnabled` | `(value: boolean) => void` | `isVerticalSwipeEnabled` property changed |
+
+## Methods Support
+
+List of methods, which could be used in [support checks](../components#methods-support):
+`disableVerticalSwipe`, `enableVerticalSwipe`.
diff --git a/apps/docs/platform/methods.md b/apps/docs/platform/methods.md
@@ -79,7 +79,8 @@ window.external.notify(data);
 ## Calling Methods
 
 Handling all possible environments for a developer's application can be challenging. To simplify
-this process, the community developed the [@telegram-apps/sdk](../packages/telegram-apps-sdk) package, which
+this process, the community developed the [@telegram-apps/sdk](../packages/telegram-apps-sdk)
+package, which
 greatly eases integration.
 
 Here's how to use it:
@@ -463,6 +464,16 @@ Updates current state of [Settings Button](settings-button.md).
 |------------|-----------|------------------------------------------|
 | is_visible | `boolean` | Should the Settings Button be displayed. |
 
+### `web_app_setup_swipe_behavior`
+
+Available since: **v7.7**
+
+Sets new swipe behavior.
+
+| Field                | Type      | Description                                          |
+|----------------------|-----------|------------------------------------------------------|
+| allow_vertical_swipe | `boolean` | Allows closing the application using vertical swipe. |
+
 ### `web_app_switch_inline_query`
 
 Available since: **v6.7**

diff --git a/apps/docs/platform/sticky-app.md b/apps/docs/platform/sticky-app.md
@@ -1,5 +1,15 @@
 # Sticky App
 
+::: tip
+
+Starting from the Mini Apps version **7.7**, you are able to prevent the application from
+closing due to swipe down by using a special method. 
+
+- [Mini Apps method](methods.md#web-app-setup-swipe-behavior)
+- [@telegram-apps/sdk component](../packages/telegram-apps-sdk/components/swipe-behavior.md)
+
+:::
+
 Developers often seek ways to make their applications "sticky." In this context, "sticky" refers to
 preventing the application from being closed accidentally, such as by a swipe-down gesture.
 

diff --git a/packages/sdk-react/src/hooks-hocs/swipe-behavior.ts b/packages/sdk-react/src/hooks-hocs/swipe-behavior.ts
@@ -0,0 +1,11 @@
+import { initSwipeBehavior } from '@telegram-apps/sdk';
+
+import { createHOCs } from '../createHOCs.js';
+import { createHooks } from '../createHooks.js';
+
+export const [useSwipeBehaviorRaw, useSwipeBehavior] = createHooks(initSwipeBehavior);
+
+export const [withSwipeBehaviorRaw, withSwipeBehavior] = createHOCs(
+  useSwipeBehaviorRaw,
+  useSwipeBehavior,
+);
diff --git a/packages/sdk-react/src/index.ts b/packages/sdk-react/src/index.ts
@@ -11,6 +11,7 @@ export * from './hooks-hocs/mini-app.js';
 export * from './hooks-hocs/popup.js';
 export * from './hooks-hocs/qr-scanner.js';
 export * from './hooks-hocs/settings-button.js';
+export * from './hooks-hocs/swipe-behavior.js';
 export * from './hooks-hocs/theme-params.js';
 export { useLaunchParams } from './hooks-hocs/launch-params.js';
 export * from './hooks-hocs/utils.js';

diff --git a/packages/sdk-solid/src/hooks-hocs/swipe-behavior.ts b/packages/sdk-solid/src/hooks-hocs/swipe-behavior.ts
@@ -0,0 +1,14 @@
+import { initSwipeBehavior } from '@telegram-apps/sdk';
+
+import { createHOC } from '../createHOC.js';
+import { createHook } from '../createHook.js';
+
+/**
+ * Hook to receive the SwipeBehavior component instance.
+ */
+export const useSwipeBehavior = createHook(initSwipeBehavior);
+
+/**
+ * HOC to pass the SwipeBehavior component instance to the wrapped component.
+ */
+export const withSwipeBehavior = createHOC(useSwipeBehavior);
diff --git a/packages/sdk-solid/src/index.ts b/packages/sdk-solid/src/index.ts
@@ -10,6 +10,7 @@ export { useMiniApp, withMiniApp } from './hooks-hocs/mini-app.js';
 export { usePopup, withPopup } from './hooks-hocs/popup.js';
 export { useQRScanner, withQRScanner } from './hooks-hocs/qr-scanner.js';
 export { useSettingsButton, withSettingsButton } from './hooks-hocs/settings-button.js';
+export { useSwipeBehavior, withSwipeBehavior } from './hooks-hocs/swipe-behavior.js';
 export { useThemeParams, withThemeParams } from './hooks-hocs/theme-params.js';
 export { useUtils, withUtils } from './hooks-hocs/utils.js';
 export { useViewport, withViewport } from './hooks-hocs/viewport.js';

diff --git a/packages/sdk/src/bridge/methods/createPostEvent.ts b/packages/sdk/src/bridge/methods/createPostEvent.ts
@@ -1,7 +1,7 @@
 import { createError } from '@/errors/createError.js';
 import { ERR_METHOD_PARAMETER_UNSUPPORTED, ERR_METHOD_UNSUPPORTED } from '@/errors/errors.js';
 import { isRecord } from '@/misc/isRecord.js';
-import { supports } from '@/supports/supports.js';
+import { supports } from '@/bridge/supports.js';
 import type { Version } from '@/version/types.js';
 
 import { type PostEvent, postEvent } from './postEvent.js';

diff --git a/packages/sdk/src/bridge/methods/types/methods.ts b/packages/sdk/src/bridge/methods/types/methods.ts
@@ -335,6 +335,14 @@ export interface MiniAppsMethods {
      */
     is_visible: boolean;
   }>;
+  /**
+   * Changes swipe behavior.
+   * @see https://docs.telegram-mini-apps.com/platform/methods#web-app-setup-swipe-behavior
+   * @since v7.7
+   */
+  web_app_setup_swipe_behavior: CreateParams<{
+    allow_vertical_swipe: boolean;
+  }>;
   /**
    * Inserts the bot's username and the specified inline query in the current chat's input field.
    * Query may be empty, in which case only the bot's username will be inserted. The client prompts

diff --git a/packages/sdk/src/supports/supports.test.ts → packages/sdk/src/bridge/supports.test.ts b/packages/sdk/src/supports/supports.test.ts → packages/sdk/src/bridge/supports.test.ts
@@ -102,6 +102,9 @@ describe.each<[
       parameter: 'return_back',
     },
   ]],
+  ['7.7', [
+    'web_app_setup_swipe_behavior',
+  ]],
 ])('%s', (version, methods) => {
   const higher = increaseVersion(version, 1);
   const lower = increaseVersion(version, -1);

diff --git a/packages/sdk/src/supports/supports.ts → packages/sdk/src/bridge/supports.ts b/packages/sdk/src/supports/supports.ts → packages/sdk/src/bridge/supports.ts
@@ -89,6 +89,8 @@ export function supports(
     case 'web_app_biometry_request_auth':
     case 'web_app_biometry_update_token':
       return versionLessOrEqual('7.2', paramOrVersion);
+    case 'web_app_setup_swipe_behavior':
+      return versionLessOrEqual('7.7', paramOrVersion);
     default:
       return [
         'iframe_ready',

diff --git a/packages/sdk/src/components/BiometryManager/initBiometryManager.ts b/packages/sdk/src/components/BiometryManager/initBiometryManager.ts
@@ -1,5 +1,5 @@
 import { createComponentInitFn } from '@/misc/createComponentInitFn/createComponentInitFn.js';
-import { supports } from '@/supports/supports.js';
+import { supports } from '@/bridge/supports.js';
 
 import { BiometryManager } from './BiometryManager.js';
 import { requestBiometryInfo } from './requestBiometryInfo.js';

diff --git a/packages/sdk/src/components/ClosingBehavior/ClosingBehavior.test.ts b/packages/sdk/src/components/ClosingBehavior/ClosingBehavior.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 
 import { ClosingBehavior } from './ClosingBehavior.js';
 
-describe('disable', () => {
+describe('disableConfirmation', () => {
   it('should call "web_app_setup_closing_behavior" method with "need_confirmation" equal to false', () => {
     const postEvent = vi.fn();
     const confirmation = new ClosingBehavior(true, postEvent);
@@ -14,7 +14,8 @@ describe('disable', () => {
   });
 
   it('should emit "isConfirmationNeededChanged" event with false value', () => {
-    const confirmation = new ClosingBehavior(true, vi.fn());
+    const confirmation = new ClosingBehavior(true, vi.fn(() => {
+    }));
     const listener = vi.fn();
 
     confirmation.on('change:isConfirmationNeeded', listener);
@@ -25,7 +26,7 @@ describe('disable', () => {
   });
 });
 
-describe('enable', () => {
+describe('enableConfirmation', () => {
   it('should call "web_app_setup_closing_behavior" method with "need_confirmation" equal to true', () => {
     const postEvent = vi.fn();
     const confirmation = new ClosingBehavior(false, postEvent);
@@ -37,7 +38,8 @@ describe('enable', () => {
   });
 
   it('should emit "isConfirmationNeededChanged" event with true value', () => {
-    const confirmation = new ClosingBehavior(false, vi.fn());
+    const confirmation = new ClosingBehavior(false, vi.fn(() => {
+    }));
     const listener = vi.fn();
 
     confirmation.on('change:isConfirmationNeeded', listener);
@@ -52,7 +54,8 @@ describe('on', () => {
   describe('"isConfirmationNeededChanged" event', () => {
     it('should add event listener to event', () => {
       const listener = vi.fn();
-      const confirmation = new ClosingBehavior(false, vi.fn());
+      const confirmation = new ClosingBehavior(false, vi.fn(() => {
+      }));
 
       confirmation.on('change:isConfirmationNeeded', listener);
 
@@ -67,7 +70,8 @@ describe('off', () => {
   describe('"isConfirmationNeededChanged" event', () => {
     it('should remove event listener from event', () => {
       const listener = vi.fn();
-      const confirmation = new ClosingBehavior(false, vi.fn());
+      const confirmation = new ClosingBehavior(false, vi.fn(() => {
+      }));
 
       confirmation.on('change:isConfirmationNeeded', listener);
 

diff --git a/packages/sdk/src/components/MiniApp/MiniApp.ts b/packages/sdk/src/components/MiniApp/MiniApp.ts
@@ -69,6 +69,7 @@ export class MiniApp extends WithSupportsAndTrackableState<
 
     this.supportsParam = createSupportsParamFn(version, {
       'setHeaderColor.color': ['web_app_set_header_color', 'color'],
+      'close.returnBack': ['web_app_close', 'return_back'],
     });
   }
 
@@ -102,7 +103,9 @@ export class MiniApp extends WithSupportsAndTrackableState<
    * @param returnBack - should the application be wrapped into the bottom bar.
    */
   close(returnBack?: boolean): void {
-    this.postEvent('web_app_close', { return_back: returnBack });
+    this.postEvent('web_app_close', this.supportsParam('close.returnBack')
+      ? { return_back: returnBack }
+      : {});
   }
 
   /**
@@ -172,7 +175,8 @@ export class MiniApp extends WithSupportsAndTrackableState<
       while (Date.now() < deadlineAt) {
         try {
           return await this.getRequestedContact();
-        } catch {}
+        } catch {
+        }
 
         // Sleep for some time.
         await sleep(sleepTime);
@@ -270,7 +274,7 @@ export class MiniApp extends WithSupportsAndTrackableState<
   /**
    * Checks if specified method parameter is supported by current component.
    */
-  supportsParam: SupportsFn<'setHeaderColor.color'>;
+  supportsParam: SupportsFn<'setHeaderColor.color' | 'close.returnBack'>;
 
   /**
    * Inserts the bot's username and the specified inline query in the current chat's input field.