@tma.js/sdk 0.11.3

package/src/components/QRScanner/types.ts

@@ -0,0 +1,11 @@
+import type { StateEvents } from '../../state/index.js';
+
+export interface QRScannerState {
+  isOpened: boolean;
+}
+
+export type QRScannerEvents = StateEvents<QRScannerState>;
+
+export type QRScannerEventName = keyof QRScannerEvents;
+
+export type QRScannerEventListener<E extends QRScannerEventName> = QRScannerEvents[E];

package/src/components/ThemeParams/ThemeParams.ts

@@ -0,0 +1,154 @@
+import { EventEmitter } from '@tma.js/event-emitter';
+import { on, request, type RequestOptions } from '@tma.js/bridge';
+import { isColorDark } from '@tma.js/colors';
+
+import type { RGB } from '@tma.js/colors';
+
+import { parseThemeParams, type ThemeParamsType } from '../../theme-params.js';
+import { State } from '../../state/index.js';
+
+import type { ThemeParamsEvents, ThemeParamsState } from './types.js';
+
+function prepareThemeParams(value: ThemeParamsType): ThemeParamsState {
+  const {
+    backgroundColor = null,
+    buttonTextColor = null,
+    buttonColor = null,
+    hintColor = null,
+    linkColor = null,
+    textColor = null,
+    secondaryBackgroundColor = null,
+  } = value;
+
+  return {
+    backgroundColor,
+    buttonTextColor,
+    buttonColor,
+    hintColor,
+    linkColor,
+    textColor,
+    secondaryBackgroundColor,
+  };
+}
+
+/**
+ * Contains information about currently used theme by application.
+ * @see https://core.telegram.org/bots/webapps#themeparams
+ */
+export class ThemeParams {
+  /**
+   * Requests fresh information about current theme.
+   * FIXME: Be careful using this function in desktop version of Telegram as
+   *  long as method web_app_request_theme does not work on `macos` platform.
+   * @param options - method options.
+   */
+  static async request(options: RequestOptions = {}): Promise<ThemeParamsType> {
+    const { timeout = 1000, ...restOptions } = options;
+    const result = await request('web_app_request_theme', 'theme_changed', {
+      ...restOptions,
+      timeout,
+    });
+
+    return parseThemeParams(result.theme_params);
+  }
+
+  /**
+   * Synchronizes specified instance of ThemeParams with the actual value in the native
+   * application.
+   * @param themeParams - ThemeParams instance.
+   */
+  static sync(themeParams: ThemeParams): void {
+    on('theme_changed', (event) => {
+      themeParams.state.set(prepareThemeParams(parseThemeParams(event.theme_params)));
+    });
+  }
+
+  /**
+   * Returns instance of ThemeParams which is synchronized with external
+   * environment.
+   * @param options - method options.
+   */
+  static async synced(options?: RequestOptions): Promise<ThemeParams> {
+    const params = await this.request(options);
+    const tp = new ThemeParams(params);
+
+    this.sync(tp);
+
+    return tp;
+  }
+
+  private readonly ee = new EventEmitter<ThemeParamsEvents>();
+
+  private readonly state: State<ThemeParamsState>;
+
+  constructor(params: ThemeParamsType) {
+    this.state = new State(prepareThemeParams(params), this.ee);
+  }
+
+  /**
+   * Returns background color.
+   */
+  get backgroundColor(): RGB | null {
+    return this.state.get('backgroundColor');
+  }
+
+  /**
+   * Returns button color.
+   */
+  get buttonColor(): RGB | null {
+    return this.state.get('buttonColor');
+  }
+
+  /**
+   * Returns button text color.
+   */
+  get buttonTextColor(): RGB | null {
+    return this.state.get('buttonTextColor');
+  }
+
+  /**
+   * Returns hint color.
+   */
+  get hintColor(): RGB | null {
+    return this.state.get('hintColor');
+  }
+
+  /**
+   * Returns true in case, current color scheme is recognized as dark. This
+   * value is calculated according to theme background color.
+   */
+  get isDark(): boolean {
+    return this.backgroundColor === null || isColorDark(this.backgroundColor);
+  }
+
+  /**
+   * Returns current link color.
+   */
+  get linkColor(): RGB | null {
+    return this.state.get('linkColor');
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off = this.ee.off.bind(this.ee);
+
+  /**
+   * Returns secondary background color.
+   */
+  get secondaryBackgroundColor(): RGB | null {
+    return this.state.get('secondaryBackgroundColor');
+  }
+
+  /**
+   * Returns text color.
+   */
+  get textColor(): RGB | null {
+    return this.state.get('textColor');
+  }
+}

package/src/components/ThemeParams/index.ts

@@ -0,0 +1,2 @@
+export * from './ThemeParams.js';
+export * from './types.js';

package/src/components/ThemeParams/types.ts

@@ -0,0 +1,18 @@
+import type { HasUndefined, If } from '@tma.js/util-types';
+
+import type { ThemeParamsType } from '../../theme-params.js';
+import type { StateEvents } from '../../state/index.js';
+
+export type ThemeParamsState = {
+  [K in keyof ThemeParamsType]-?: If<
+    HasUndefined<ThemeParamsType[K]>,
+    Exclude<ThemeParamsType[K], undefined> | null,
+    ThemeParamsType[K]
+  >;
+};
+
+export type ThemeParamsEvents = StateEvents<ThemeParamsState>;
+
+export type ThemeParamsEventName = keyof ThemeParamsEvents;
+
+export type ThemeParamsEventListener<E extends ThemeParamsEventName> = ThemeParamsEvents[E];

package/src/components/Viewport/Viewport.ts

@@ -0,0 +1,197 @@
+import { EventEmitter } from '@tma.js/event-emitter';
+import { on, postEvent as defaultPostEvent, request, type RequestOptions, type PostEvent } from '@tma.js/bridge';
+
+import { State } from '../../state/index.js';
+
+import type { ViewportEvents, ViewportState } from './types.js';
+
+export interface RequestViewportResult {
+  height: number;
+  isStateStable: boolean;
+  isExpanded: boolean;
+  width: number;
+}
+
+/**
+ * Formats value to make it stay in bounds [0, +Inf).
+ * @param value - value to format.
+ */
+function truncate(value: number): number {
+  return value < 0 ? 0 : value;
+}
+
+/**
+ * Contains information about current WebApp device viewport, its dimensions
+ * and state.
+ */
+export class Viewport {
+  /**
+   * Requests fresh information about current viewport.
+   * FIXME: Be careful using this function in desktop version of Telegram as
+   *  long as method web_app_request_viewport does not work on `macos` platform.
+   * @see Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/5
+   * @param options - method options.
+   */
+  static async request(options: RequestOptions = {}): Promise<RequestViewportResult> {
+    const { timeout = 1000, ...restOptions } = options;
+    const {
+      is_expanded: isExpanded,
+      is_state_stable: isStateStable,
+      ...rest
+    } = await request('web_app_request_viewport', 'viewport_changed', {
+      ...restOptions,
+      timeout,
+    });
+
+    return { ...rest, isExpanded, isStateStable };
+  }
+
+  /**
+   * Synchronizes specified instance of Viewport with the actual value in the native
+   * application.
+   * @param viewport - Viewport instance.
+   */
+  static sync(viewport: Viewport): void {
+    on('viewport_changed', (event) => {
+      const {
+        height,
+        width,
+        is_expanded: isExpanded,
+        is_state_stable: isStateStable,
+      } = event;
+      const formattedHeight = truncate(height);
+
+      viewport.state.set({
+        height: formattedHeight,
+        isExpanded,
+        width: truncate(width),
+        stableHeight: isStateStable ? formattedHeight : undefined,
+      });
+    });
+  }
+
+  /**
+   * Returns initialized instance of Viewport which is synchronized with
+   * its actual state in Web Apps.
+   * @param options - method options.
+   */
+  static async synced(options: RequestOptions = {}): Promise<Viewport> {
+    const { height, isExpanded, width } = await this.request(options);
+    const viewport = new Viewport(height, width, height, isExpanded, options.postEvent);
+
+    this.sync(viewport);
+
+    return viewport;
+  }
+
+  private readonly ee = new EventEmitter<ViewportEvents>();
+
+  private readonly state: State<ViewportState>;
+
+  constructor(
+    height: number,
+    width: number,
+    stableHeight: number,
+    isExpanded: boolean,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
+    this.state = new State({
+      height: truncate(height),
+      isExpanded,
+      stableHeight: truncate(stableHeight),
+      width: truncate(width),
+    }, this.ee);
+  }
+
+  /**
+   * The current height of the visible area of the Web App.
+   *
+   * The application can display just the top part of the Web App, with its
+   * lower part remaining outside the screen area. From this position, the
+   * user can "pull" the Web App to its maximum height, while the bot can do
+   * the same by calling `expand` method. As the position of the Web App
+   * changes, the current height value of the visible area will be updated
+   * in real time.
+   *
+   * Please note that the refresh rate of this value is not sufficient
+   * to smoothly follow the lower border of the window. It should not be
+   * used to pin interface elements to the bottom of the visible area. It's
+   * more appropriate to use the value of the `stableHeight`
+   * field for this purpose.
+   *
+   * @see init
+   * @see expand
+   * @see stableHeight
+   */
+  get height(): number {
+    return this.state.get('height');
+  }
+
+  /**
+   * The height of the visible area of the Web App in its last stable state.
+   *
+   * The application can display just the top part of the Web App, with its
+   * lower part remaining outside the screen area. From this position,
+   * the user can "pull" the Web App to its maximum height, while the bot can
+   * do the same by calling `expand` method.
+   *
+   * Unlike the value of `height`, the value of `stableHeight`
+   * does not change as the position of the Web App changes with user
+   * gestures or during animations. The value of `stableHeight`
+   * will be updated after all gestures and animations are completed and
+   * the Web App reaches its final size.
+   *
+   * @see init
+   * @see expand
+   * @see height
+   */
+  get stableHeight(): number {
+    return this.state.get('stableHeight');
+  }
+
+  /**
+   * Returns true if the Web App is expanded to the maximum available height.
+   * Otherwise, if the Web App occupies part of the screen and can be expanded
+   * to the full height using `expand` method.
+   * @see expand
+   */
+  get isExpanded(): boolean {
+    return this.state.get('isExpanded');
+  }
+
+  /**
+   * Current viewport width.
+   */
+  get width(): number {
+    return this.state.get('width');
+  }
+
+  /**
+   * A method that expands the Web App to the maximum available height. To
+   * find out if the Web App is expanded to the maximum height, refer to the
+   * value of the `isExpanded`.
+   * @see isExpanded
+   */
+  expand(): void {
+    this.state.set('isExpanded', true);
+    this.postEvent('web_app_expand');
+  }
+
+  /**
+   * Returns true in case current viewport height is stable and is not going to
+   * change in the next moment.
+   */
+  get isStable(): boolean {
+    return this.stableHeight === this.height;
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on: typeof this.ee.on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off: typeof this.ee.off = this.ee.off.bind(this.ee);
+}

package/src/components/Viewport/index.ts

@@ -0,0 +1,2 @@
+export * from './Viewport.js';
+export type { ViewportEvents, ViewportEventListener, ViewportEventName } from './types.js';

package/src/components/Viewport/types.ts

@@ -0,0 +1,14 @@
+import type { StateEvents } from '../../state/index.js';
+
+export interface ViewportState {
+  height: number;
+  isExpanded: boolean;
+  stableHeight: number;
+  width: number;
+}
+
+export type ViewportEvents = StateEvents<ViewportState>;
+
+export type ViewportEventName = keyof ViewportEvents;
+
+export type ViewportEventListener<E extends ViewportEventName> = ViewportEvents[E];