@tma.js/sdk 0.13.2 → 1.0.0

package/src/init/creators/createViewport.ts

@@ -1,54 +1,104 @@
-import type { PostEvent } from '@tma.js/bridge';
-import type { Platform } from '@tma.js/launch-params';
+import { getStorageValue, saveStorageValue } from '~/storage.js';
+import { requestViewport, Viewport } from '~/viewport/index.js';
+import type { PostEvent } from '~/bridge/index.js';
+import type { Platform } from '~/types/index.js';
 
-import { Viewport } from '../../components/index.js';
+/**
+ * Attempts to create Viewport instance using known parameters and local storage.
+ * @param isPageReload - was page reloaded.
+ * @param platform - platform identifier.
+ * @param postEvent - Bridge postEvent function.
+ */
+function tryCreate(
+  isPageReload: boolean,
+  platform: Platform,
+  postEvent: PostEvent,
+): Viewport | null {
+  if (isPageReload || platform === 'macos' || platform === 'web' || platform === 'weba') {
+    return new Viewport({
+      height: window.innerHeight,
+      isExpanded: true,
+      postEvent,
+      stableHeight: window.innerHeight,
+      width: window.innerWidth,
+    });
+  }
+
+  const state = getStorageValue('viewport');
+  if (state) {
+    return new Viewport({ ...state, postEvent });
+  }
+
+  return null;
+}
+
+/**
+ * Synchronizes specified Viewport instance with Telegram application and always saves its state
+ * in local storage.
+ * @param viewport - Viewport instance.
+ */
+function bind(viewport: Viewport): Viewport {
+  viewport.listen();
+
+  // TODO: Should probably use throttle for height.
+  viewport.on('change', () => saveStorageValue('viewport', {
+    height: viewport.height,
+    isExpanded: viewport.isExpanded,
+    stableHeight: viewport.stableHeight,
+    width: viewport.width,
+  }));
 
-import { getStorageValue, saveStorageValue } from '../../storage.js';
+  return viewport;
+}
 
 /**
- * Creates Viewport instance using last locally saved data also saving each state in
- * the storage.
- * @param isPageReload - was current page reloaded.
- * @param platform - Telegram Mini Apps platform name.
- * @param postEvent - Bridge postEvent function
+ * Creates Viewport instance using its actual state from the storage. Otherwise, creates it
+ * with default parameters.
+ * @param isPageReload - was page reloaded.
+ * @param platform - platform identifier.
+ * @param postEvent - Bridge postEvent function.
  */
-export async function createViewport(
+export function createViewportSync(
   isPageReload: boolean,
   platform: Platform,
   postEvent: PostEvent,
-): Promise<Viewport> {
-  const {
-    height = window.innerHeight,
-    stableHeight = window.innerHeight,
-    width = window.innerWidth,
-    isExpanded = false,
-  } = isPageReload ? getStorageValue('viewport') || {} : {};
-
-  const createSynced = () => {
-    const viewport = new Viewport(height, width, stableHeight, isExpanded, postEvent);
-    Viewport.sync(viewport);
-
-    return viewport;
-  };
-
-  // MacOS and Web K versions do not support requesting current viewport information. That's why we
-  // should construct Viewport instance by ourselves.
-  const component = platform === 'macos' || platform === 'web'
-    ? createSynced()
-    : await Viewport.synced({ postEvent });
-
-  const saveState = () => saveStorageValue('viewport', {
-    height: component.height,
-    isExpanded: component.isExpanded,
-    stableHeight: component.stableHeight,
-    width: component.width,
+): Viewport {
+  const viewport = bind(
+    tryCreate(isPageReload, platform, postEvent) || new Viewport({
+      width: 0,
+      height: 0,
+      isExpanded: false,
+      postEvent,
+      stableHeight: 0,
+    }),
+  );
+
+  viewport.sync({ postEvent, timeout: 100 }).catch((e) => {
+    // eslint-disable-next-line no-console
+    console.error('Unable to actualize viewport state', e);
   });
 
-  // TODO: Should probably use throttle for height.
-  component.on('heightChanged', saveState);
-  component.on('isExpandedChanged', saveState);
-  component.on('stableHeightChanged', saveState);
-  component.on('widthChanged', saveState);
+  return viewport;
+}
 
-  return component;
+/**
+ * Creates Viewport instance using its actual state from the Telegram application.
+ * @param isPageReload - was page reloaded.
+ * @param platform - platform identifier.
+ * @param postEvent - Bridge postEvent function.
+ */
+export async function createViewportAsync(
+  isPageReload: boolean,
+  platform: Platform,
+  postEvent: PostEvent,
+): Promise<Viewport> {
+  return bind(
+    tryCreate(isPageReload, platform, postEvent)
+    || await requestViewport({ postEvent, timeout: 100 })
+      .then(({ height, isStateStable, ...rest }) => new Viewport({
+        ...rest,
+        height,
+        stableHeight: isStateStable ? height : 0,
+      })),
+  );
 }

package/src/init/creators/index.ts

@@ -1,7 +1,7 @@
 export * from './createBackButton.js';
 export * from './createClosingBehavior.js';
 export * from './createMainButton.js';
+export * from './createMiniApp.js';
 export * from './createRequestIdGenerator.js';
 export * from './createThemeParams.js';
 export * from './createViewport.js';
-export * from './createWebApp.js';

package/src/init/css/bindMiniAppCSSVars.ts

@@ -0,0 +1,48 @@
+import { setCSSVar } from '~/init/css/setCSSVar.js';
+import type { MiniApp } from '~/mini-app/index.js';
+import type { ThemeParams } from '~/theme-params/index.js';
+
+/**
+ * Creates CSS variables connected with WebApp background and header colors based on
+ * passed WebApp and ThemeParams instances.
+ *
+ * Created variables:
+ * - `--tg-background-color`
+ * - `--tg-header-color`
+ *
+ * Variables are being automatically updated in case, corresponding properties are updating.
+ *
+ * @param miniApp - MiniApp instance.
+ * @param themeParams - ThemeParams instance.
+ */
+export function bindMiniAppCSSVars(miniApp: MiniApp, themeParams: ThemeParams): void {
+  const actualizeBackground = () => {
+    setCSSVar('--tg-background-color', miniApp.backgroundColor);
+  };
+
+  const actualizeHeader = () => {
+    const {
+      backgroundColor,
+      secondaryBackgroundColor,
+    } = themeParams;
+
+    if (miniApp.headerColor === 'bg_color') {
+      if (backgroundColor) {
+        setCSSVar('--tg-header-color', backgroundColor);
+      }
+    } else if (miniApp.headerColor === 'secondary_bg_color') {
+      if (secondaryBackgroundColor) {
+        setCSSVar('--tg-header-color', secondaryBackgroundColor);
+      }
+    } else {
+      setCSSVar('--tg-header-color', miniApp.headerColor);
+    }
+  };
+
+  themeParams.on('change', actualizeHeader);
+  miniApp.on('change:backgroundColor', actualizeBackground);
+  miniApp.on('change:headerColor', actualizeHeader);
+
+  actualizeBackground();
+  actualizeHeader();
+}

package/src/init/css/bindThemeCSSVars.ts

@@ -0,0 +1,31 @@
+import type { ThemeParams } from '~/theme-params/index.js';
+
+import { setCSSVar } from './setCSSVar.js';
+
+/**
+ * Creates CSS variables connected with theme parameters. Created CSS variables names are
+ * following the pattern "--tg-theme-{name}". {name} is a theme parameters key name converted
+ * from snake to kebab case.
+ *
+ * Variables are being automatically updated in case, corresponding properties
+ * updated in passed ThemeParams instance.
+ *
+ * @param themeParams - ThemeParams instance.
+ */
+export function bindThemeCSSVars(themeParams: ThemeParams): void {
+  const actualize = () => {
+    const state = themeParams.getState();
+
+    Object.entries(state).forEach(([k, v]) => {
+      if (v) {
+        const key = k
+          .replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+        setCSSVar(`--tg-theme-${key}`, v);
+      }
+    });
+  };
+
+  themeParams.on('change', actualize);
+
+  actualize();
+}

package/src/init/css/bindViewportCSSVars.ts

@@ -0,0 +1,36 @@
+import type { Viewport } from '~/viewport/index.js';
+
+import { setCSSVar } from './setCSSVar.js';
+
+/**
+ * Accepts Viewport instance and sets CSS variables connected with viewport
+ * sizes.
+ *
+ * Be careful using this function as long as it can impact application
+ * performance. Viewport size is changing rather often, this makes CSS
+ * variables update, which leads to possible layout redraw.
+ *
+ * Variables:
+ * - `--tg-viewport-height`
+ * - `--tg-viewport-width`
+ * - `--tg-viewport-stable-height`
+ *
+ * Variables are being automatically updated in case, corresponding properties
+ * updated in passed Viewport instance.
+ *
+ * @param viewport - Viewport instance.
+ */
+export function bindViewportCSSVars(viewport: Viewport): void {
+  const setHeight = () => setCSSVar('--tg-viewport-height', `${viewport.height}px`);
+  const setWidth = () => setCSSVar('--tg-viewport-width', `${viewport.width}px`);
+  const setStableHeight = () => setCSSVar('--tg-viewport-height', `${viewport.stableHeight}px`);
+
+  // TODO: Should probably add debounce or throttle.
+  viewport.on('change:height', setHeight);
+  viewport.on('change:width', setWidth);
+  viewport.on('change:stableHeight', setStableHeight);
+
+  setHeight();
+  setWidth();
+  setStableHeight();
+}

package/src/init/css/index.ts

@@ -0,0 +1 @@
+export * from './processCSSVarsOption.js';

package/src/init/css/processCSSVarsOption.ts

@@ -0,0 +1,57 @@
+import type { MiniApp } from '~/mini-app/index.js';
+import type { ThemeParams } from '~/theme-params/index.js';
+import type { Viewport } from '~/viewport/index.js';
+
+import { bindMiniAppCSSVars } from './bindMiniAppCSSVars.js';
+import { bindThemeCSSVars } from './bindThemeCSSVars.js';
+import { bindViewportCSSVars } from './bindViewportCSSVars.js';
+import type { InitCSSVarsOption, InitCSSVarsSpecificOption } from '../types.js';
+
+/**
+ * Converts init cssVars option to more narrow type.
+ * @param option - option value.
+ */
+function parseCSSVarsOptions(option: InitCSSVarsOption): InitCSSVarsSpecificOption {
+  if (typeof option === 'object') {
+    return option;
+  }
+  return option
+    ? {
+      themeParams: true,
+      viewport: true,
+      miniApp: true,
+    }
+    : {};
+}
+
+/**
+ * Process initialization CSS vars option.
+ * @param option - option value.
+ * @param miniApp - MiniApp instance.
+ * @param themeParams - ThemeParams instance.
+ * @param viewportOrPromise - Viewport instance or promise resolving it.
+ */
+export function processCSSVars(
+  option: InitCSSVarsOption,
+  miniApp: MiniApp,
+  themeParams: ThemeParams,
+  viewportOrPromise: Viewport | Promise<Viewport>,
+): void {
+  const cssVarsOptions = parseCSSVarsOptions(option);
+
+  if (cssVarsOptions.miniApp) {
+    bindMiniAppCSSVars(miniApp, themeParams);
+  }
+
+  if (cssVarsOptions.themeParams) {
+    bindThemeCSSVars(themeParams);
+  }
+
+  if (cssVarsOptions.viewport) {
+    if (viewportOrPromise instanceof Promise) {
+      viewportOrPromise.then(bindViewportCSSVars);
+    } else {
+      bindViewportCSSVars(viewportOrPromise);
+    }
+  }
+}

package/src/init/css/setCSSVar.ts

@@ -0,0 +1,8 @@
+/**
+ * Sets CSS variable.
+ * @param name - variable name.
+ * @param value - variable value.
+ */
+export function setCSSVar(name: string, value: string): void {
+  document.documentElement.style.setProperty(name, value);
+}

package/src/init/init.ts

@@ -1,167 +1,125 @@
+import { createPostEvent, isIframe, on } from '~/bridge/index.js';
+import { CloudStorage } from '~/cloud-storage/index.js';
+import { HapticFeedback } from '~/haptic-feedback/index.js';
+import { catchCustomStyles } from '~/init/catchCustomStyles.js';
 import {
-  isIframe,
-  setDebug,
-  setTargetOrigin,
-  on,
-  createPostEvent,
-  postEvent as bridgePostEvent,
-} from '@tma.js/bridge';
-import { withTimeout } from '@tma.js/utils';
-import { parse, retrieveLaunchData } from '@tma.js/launch-params';
-
-import {
-  CloudStorage,
-  HapticFeedback,
-  InitData,
-  Popup,
-  QRScanner,
-} from '../components/index.js';
-import {
-  bindThemeCSSVariables,
-  bindViewportCSSVariables,
-  bindWebAppVariables,
-  parseCSSVarsOptions,
-} from './css.js';
-import {
-  createThemeParams,
   createBackButton,
+  createClosingBehavior,
   createMainButton,
-  createViewport,
-  createWebApp,
+  createMiniApp,
   createRequestIdGenerator,
-  createClosingBehavior,
-} from './creators/index.js';
+  createThemeParams, createViewportAsync,
+  createViewportSync,
+} from '~/init/creators/index.js';
+import { processCSSVars } from '~/init/css/index.js';
+import { InitData } from '~/init-data/index.js';
+import { Invoice } from '~/invoice/index.js';
+import { retrieveLaunchData } from '~/launch-params/index.js';
+import { Popup } from '~/popup/index.js';
+import { QRScanner } from '~/qr-scanner/index.js';
+import { Utils } from '~/utils/index.js';
 
 import type { InitOptions, InitResult } from './types.js';
 
-/**
- * Represents actual init function.
- * @param options - init options.
- */
-async function actualInit(options: InitOptions = {}): Promise<InitResult> {
+type ComputedInitResult<O> = O extends { async: true } ? Promise<InitResult> : InitResult;
+
+export function init<O extends InitOptions>(options: O): ComputedInitResult<O> {
   const {
-    checkCompat = true,
+    async = false,
     cssVars = false,
-    acceptScrollbarStyle = true,
-    acceptCustomStyles = acceptScrollbarStyle,
-    targetOrigin,
-    launchParams: launchParamsOption,
-    debug = false,
+    acceptCustomStyles = false,
   } = options;
 
-  // Set global settings.
-  if (debug) {
-    setDebug(debug);
-  }
-
-  if (typeof targetOrigin === 'string') {
-    setTargetOrigin(targetOrigin);
-  }
-
   // Retrieve launch data.
-  const { launchParams, isPageReload } = retrieveLaunchData({
-    currentLaunchParams: typeof launchParamsOption === 'string' || launchParamsOption instanceof URLSearchParams
-      ? parse(launchParamsOption)
-      : launchParamsOption,
-  });
-
   const {
-    initData,
-    initDataRaw,
-    version,
-    platform,
-    themeParams: lpThemeParams,
-  } = launchParams;
-  const {
-    backgroundColor = '#ffffff',
-    buttonColor = '#000000',
-    buttonTextColor = '#ffffff',
-  } = lpThemeParams;
-
-  const createRequestId = createRequestIdGenerator();
-  const postEvent = checkCompat
-    ? createPostEvent(version)
-    : bridgePostEvent;
-  const themeParams = createThemeParams(lpThemeParams);
-  const webApp = createWebApp(
+    launchParams: {
+      initData,
+      initDataRaw,
+      version,
+      platform,
+      themeParams,
+      botInline = false,
+    },
     isPageReload,
-    backgroundColor,
-    version,
-    platform,
-    createRequestId,
-    postEvent,
-  );
+  } = retrieveLaunchData();
 
-  const {
-    themeParams: createThemeParamsCSSVars,
-    viewport: createViewportCSSVars,
-    webApp: createWebAppCSSVars,
-  } = parseCSSVarsOptions(cssVars);
-
-  if (createWebAppCSSVars) {
-    bindWebAppVariables(webApp, themeParams);
-  }
-
-  if (createThemeParamsCSSVars) {
-    bindThemeCSSVariables(themeParams);
-  }
-
-  const viewport = await createViewport(isPageReload, platform, postEvent);
-
-  // Apply viewport CSS variables.
-  if (createViewportCSSVars) {
-    bindViewportCSSVariables(viewport);
-  }
-
-  // In case, we are currently in iframe, it is required to listen to
-  // messages, coming from parent source to apply requested changes.
-  // The only one case, when current application was placed into iframe is
-  // web version of Telegram.
-  if (acceptCustomStyles && isIframe()) {
-    // Create special style element which is responsible for application
-    // style controlled by external app.
-    const styleElement = document.createElement('style');
-    styleElement.id = 'telegram-custom-styles';
-    document.head.appendChild(styleElement);
-
-    // Listen to custom style changes.
-    on('set_custom_style', (html) => {
-      styleElement.innerHTML = html;
-    });
-
-    // Notify Telegram, iframe is ready. This will result in sending style
-    // tag html from native application.
-    postEvent('iframe_ready');
+  const createRequestId = createRequestIdGenerator();
+  const postEvent = createPostEvent(version);
+
+  // In Telegram web version we should listen to special event sent from the Telegram application
+  // to know, when we should reload the Mini App.
+  if (isIframe()) {
+    if (acceptCustomStyles) {
+      catchCustomStyles();
+    }
+
+    // Notify Telegram, iframe is ready. This will result in sending style tag html from native
+    // application which is used in catchCustomStyles function. We should call this method also
+    // to start receiving "reload_iframe" events from the Telegram application.
+    postEvent('iframe_ready', { reload_supported: true });
+    on('reload_iframe', () => window.location.reload());
   }
 
-  const result: InitResult = {
+  const result: Omit<InitResult, 'viewport'> = {
     backButton: createBackButton(isPageReload, version, postEvent),
     closingBehavior: createClosingBehavior(isPageReload, postEvent),
     cloudStorage: new CloudStorage(version, createRequestId, postEvent),
-    haptic: new HapticFeedback(version, postEvent),
-    mainButton: createMainButton(isPageReload, buttonColor, buttonTextColor, postEvent),
+    createRequestId,
+    hapticFeedback: new HapticFeedback(version, postEvent),
+    invoice: new Invoice(version, postEvent),
+    mainButton: createMainButton(
+      isPageReload,
+      themeParams.buttonColor || '#000000',
+      themeParams.buttonTextColor || '#ffffff',
+      postEvent,
+    ),
+    miniApp: createMiniApp(
+      isPageReload,
+      themeParams.backgroundColor || '#ffffff',
+      version,
+      botInline,
+      postEvent,
+    ),
     popup: new Popup(version, postEvent),
     postEvent,
     qrScanner: new QRScanner(version, postEvent),
-    themeParams,
-    viewport,
-    webApp,
+    themeParams: createThemeParams(themeParams),
+    utils: new Utils(version, createRequestId, postEvent),
+    ...(initData
+      // Init data could be missing in case, application was launched via InlineKeyboardButton.
+      ? {
+        initData: new InitData(initData),
+        initDataRaw,
+      }
+      : {}),
   };
 
-  // Init data could be missing in case, application was launched via InlineKeyboardButton.
-  if (initData !== undefined) {
-    const { authDate, hash, ...restInitData } = initData;
-    result.initData = new InitData(authDate, hash, restInitData);
-    result.initDataRaw = initDataRaw;
+  const viewport = async
+    ? createViewportAsync(isPageReload, platform, postEvent)
+    : createViewportSync(isPageReload, platform, postEvent);
+
+  if (viewport instanceof Promise) {
+    return viewport.then((vp) => {
+      processCSSVars(
+        cssVars,
+        result.miniApp,
+        result.themeParams,
+        vp,
+      );
+
+      return {
+        ...result,
+        viewport: vp,
+      };
+    }) as ComputedInitResult<O>;
   }
 
-  return result;
-}
+  processCSSVars(
+    cssVars,
+    result.miniApp,
+    result.themeParams,
+    viewport,
+  );
 
-/**
- * Initializes all SDK components.
- * @param options - initialization options.
- */
-export function init(options: InitOptions = {}): Promise<InitResult> {
-  return withTimeout(actualInit(options), options.timeout || 1000);
+  return { ...result, viewport } as ComputedInitResult<O>;
 }