@tma.js/sdk 2.6.1 → 3.0.0

package/dist/dts/features/SecondaryButton/SecondaryButton.d.ts

@@ -0,0 +1,253 @@
+import { Computed } from '@tma.js/signals';
+import { RGB } from '@tma.js/types';
+import { PostEventError, SecondaryButtonPosition } from '@tma.js/bridge';
+import { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+import { ButtonOptions } from '../../composables/Button.js';
+import { MaybeAccessor } from '../../types.js';
+import * as E from 'fp-ts/Either';
+type SecondaryButtonEither = E.Either<PostEventError, void>;
+export interface SecondaryButtonState {
+    isVisible: boolean;
+    bgColor?: RGB;
+    hasShineEffect: boolean;
+    isEnabled: boolean;
+    isLoaderVisible: boolean;
+    text: string;
+    textColor?: RGB;
+    position: SecondaryButtonPosition;
+}
+export interface SecondaryButtonOptions extends Omit<ButtonOptions<SecondaryButtonState, 'web_app_setup_secondary_button'>, 'initialState' | 'method' | 'payload'> {
+    /**
+     * Default values for different kinds of the button properties.
+     */
+    defaults: {
+        bgColor: MaybeAccessor<RGB>;
+        textColor: MaybeAccessor<RGB>;
+    };
+}
+/**
+ * @since Mini Apps v7.10
+ */
+export declare class SecondaryButton {
+    constructor({ defaults, ...options }: SecondaryButtonOptions);
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * The button position relative to the main one.
+     */
+    readonly position: Computed<SecondaryButtonPosition>;
+    /**
+     * The button background color.
+     */
+    readonly bgColor: Computed<RGB>;
+    /**
+     * True if the button has a shining effect.
+     */
+    readonly hasShineEffect: Computed<boolean>;
+    /**
+     * True if the button is clickable.
+     */
+    readonly isEnabled: Computed<boolean>;
+    /**
+     * True if the button loader is visible.
+     */
+    readonly isLoaderVisible: Computed<boolean>;
+    /**
+     * True if the button is visible.
+     */
+    readonly isVisible: Computed<boolean>;
+    /**
+     * Signal indicating if the component is currently mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * The complete button state.
+     */
+    readonly state: Computed<SecondaryButtonState>;
+    /**
+     * The button displayed text.
+     */
+    readonly text: Computed<string>;
+    /**
+     * The button text color.
+     *
+     * Note that this value is computed based on the external defaults. For
+     * example, if not explicitly set, this value may be equal to one of theme
+     * params colors.
+     */
+    readonly textColor: Computed<RGB>;
+    /**
+     * Shows the button.
+     * @since Mini Apps v7.10
+     */
+    readonly showFp: WithChecksFp<() => SecondaryButtonEither, true>;
+    /**
+     * @see showFp
+     */
+    readonly show: WithChecks<() => void, true>;
+    /**
+     * Hides the button.
+     * @since Mini Apps v7.10
+     */
+    readonly hideFp: WithChecksFp<() => SecondaryButtonEither, true>;
+    /**
+     * @see hideFp
+     */
+    readonly hide: WithChecks<() => void, true>;
+    /**
+     * Enables the button.
+     * @since Mini Apps v7.10
+     */
+    readonly enableFp: WithChecksFp<() => SecondaryButtonEither, true>;
+    /**
+     * @see enableFp
+     */
+    readonly enable: WithChecks<() => void, true>;
+    /**
+     * Enables the button.
+     * @since Mini Apps v7.10
+     */
+    readonly enableShineEffectFp: WithChecksFp<() => SecondaryButtonEither, true>;
+    /**
+     * @see enableShineEffectFp
+     */
+    readonly enableShineEffect: WithChecks<() => void, true>;
+    /**
+     * Disables the button.
+     * @since Mini Apps v7.10
+     */
+    readonly disableFp: WithChecksFp<() => SecondaryButtonEither, true>;
+    /**
+     * @see disableFp
+     */
+    readonly disable: WithChecks<() => void, true>;
+    /**
+     * Enables the button.
+     * @since Mini Apps v7.10
+     */
+    readonly disableShineEffectFp: WithChecksFp<() => SecondaryButtonEither, true>;
+    /**
+     * @see disableShineEffectFp
+     */
+    readonly disableShineEffect: WithChecks<() => void, true>;
+    /**
+     * Updates the button background color.
+     * @since Mini Apps v7.10
+     */
+    readonly setBgColorFp: WithChecksFp<(value: RGB) => SecondaryButtonEither, true>;
+    /**
+     * @see setBgColorFp
+     */
+    readonly setBgColor: WithChecks<(value: RGB) => void, true>;
+    /**
+     * Updates the button text color.
+     * @since Mini Apps v7.10
+     */
+    readonly setTextColorFp: WithChecksFp<(value: RGB) => SecondaryButtonEither, true>;
+    /**
+     * @see setTextColorFp
+     */
+    readonly setTextColor: WithChecks<(value: RGB) => void, true>;
+    /**
+     * Updates the button text.
+     * @since Mini Apps v7.10
+     */
+    readonly setTextFp: WithChecksFp<(value: string) => SecondaryButtonEither, true>;
+    /**
+     * @see setTextFp
+     */
+    readonly setText: WithChecks<(value: string) => void, true>;
+    /**
+     * Updates the button position.
+     * @since Mini Apps v7.10
+     */
+    readonly setPositionFp: WithChecksFp<(position: SecondaryButtonPosition) => SecondaryButtonEither, true>;
+    /**
+     * @see setPositionFp
+     */
+    readonly setPosition: WithChecks<(position: SecondaryButtonPosition) => void, true>;
+    /**
+     * Shows the button loader.
+     * @since Mini Apps v7.10
+     */
+    readonly showLoaderFp: WithChecksFp<() => SecondaryButtonEither, true>;
+    /**
+     * @see showLoaderFp
+     */
+    readonly showLoader: WithChecks<() => void, true>;
+    /**
+     * Hides the button loader.
+     * @since Mini Apps v7.10
+     */
+    readonly hideLoaderFp: WithChecksFp<() => SecondaryButtonEither, true>;
+    /**
+     * @see hideLoaderFp
+     */
+    readonly hideLoader: WithChecks<() => void, true>;
+    /**
+     * Updates the button state.
+     * @param state - updates to apply.
+     * @since Mini Apps v7.10
+     * @example
+     * button.setParams({
+     *   text: 'Submit',
+     *   isEnabled: true,
+     *   hasShineEffect: true,
+     * });
+     */
+    readonly setParamsFp: WithChecksFp<(state: Partial<SecondaryButtonState>) => SecondaryButtonEither, true>;
+    /**
+     * @see setParamsFp
+     */
+    readonly setParams: WithChecks<(state: Partial<SecondaryButtonState>) => void, true>;
+    /**
+     * Mounts the component restoring its state.
+     * @since Mini Apps v7.10
+     */
+    readonly mountFp: WithChecksFp<() => void, true>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<() => void, true>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+    /**
+     * Adds a new button listener.
+     * @param listener - event listener.
+     * @param once - should the listener be called only once.
+     * @returns A function to remove bound listener.
+     * @since Mini Apps v7.10
+     * @example
+     * const off = button.onClick(() => {
+     *   console.log('User clicked the button');
+     *   off();
+     * });
+     */
+    readonly onClickFp: WithChecksFp<(listener: VoidFunction, once?: boolean) => VoidFunction, true>;
+    /**
+     * @see onClick
+     */
+    readonly onClick: WithChecks<(listener: VoidFunction, once?: boolean) => VoidFunction, true>;
+    /**
+     * Removes the button click listener.
+     * @param listener - event listener.
+     * @param once - should the listener be called only once.
+     * @since Mini Apps v7.10
+     * @example
+     * function listener() {
+     *   console.log('User clicked the button');
+     *   button.offClick(listener);
+     * }
+     * button.onClick(listener);
+     */
+    readonly offClickFp: WithChecksFp<(listener: VoidFunction, once?: boolean) => void, true>;
+    /**
+     * @see offClick
+     */
+    readonly offClick: WithChecks<(listener: VoidFunction, once?: boolean) => void, true>;
+}
+export {};

package/dist/dts/features/SecondaryButton/exports.d.ts

@@ -0,0 +1,2 @@
+export { secondaryButton } from './instance.js';
+export { type SecondaryButtonOptions, SecondaryButton, type SecondaryButtonState, } from './SecondaryButton.js';

package/dist/dts/features/SecondaryButton/instance.d.ts

@@ -0,0 +1,2 @@
+import { SecondaryButton } from './SecondaryButton.js';
+export declare const secondaryButton: SecondaryButton;

package/dist/dts/features/SettingsButton/SettingsButton.d.ts

@@ -0,0 +1,96 @@
+import { Computed } from '@tma.js/signals';
+import { PostEventError } from '@tma.js/bridge';
+import { ButtonOptions } from '../../composables/Button.js';
+import { WithChecksFp, WithChecks } from '../../with-checks/withChecksFp.js';
+import * as E from 'fp-ts/Either';
+export interface SettingsButtonState {
+    isVisible: boolean;
+}
+export type SettingsButtonOptions = Omit<ButtonOptions<SettingsButtonState, 'web_app_setup_settings_button'>, 'method' | 'payload' | 'initialState'>;
+/**
+ * @since Mini Apps v6.10
+ */
+export declare class SettingsButton {
+    constructor(options: SettingsButtonOptions);
+    /**
+     * Signal indicating if the component is currently visible.
+     */
+    readonly isVisible: Computed<boolean>;
+    /**
+     * Signal indicating if the component is currently mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * Hides the button.
+     * @since Mini Apps v6.10
+     */
+    readonly hideFp: WithChecksFp<() => E.Either<PostEventError, void>, true>;
+    /**
+     * @see hideFp
+     */
+    readonly hide: WithChecks<() => void, true>;
+    /**
+     * Shows the button.
+     * @since Mini Apps v6.10
+     */
+    readonly showFp: WithChecksFp<() => E.Either<PostEventError, void>, true>;
+    /**
+     * @see showFp
+     */
+    readonly show: WithChecks<() => void, true>;
+    /**
+     * Adds a new button listener.
+     * @param listener - event listener.
+     * @param once - should the listener be called only once.
+     * @returns A function to remove bound listener.
+     * @since Mini Apps v6.10
+     * @example
+     * const off = button.onClick(() => {
+     *   console.log('User clicked the button');
+     *   off();
+     * });
+     */
+    readonly onClickFp: WithChecksFp<(listener: VoidFunction, once?: boolean) => VoidFunction, true>;
+    /**
+     * @see onClickFp
+     */
+    readonly onClick: WithChecks<(listener: VoidFunction, once?: boolean) => VoidFunction, true>;
+    /**
+     * Removes the button click listener.
+     * @param listener - event listener.
+     * @param once - should the listener be called only once.
+     * @since Mini Apps v6.10
+     * @example
+     * function listener() {
+     *   console.log('User clicked the button');
+     *   button.offClick(listener);
+     * }
+     * button.onClick(listener);
+     */
+    readonly offClickFp: WithChecksFp<(listener: VoidFunction, once?: boolean) => void, true>;
+    /**
+     * @see offClickFp
+     */
+    readonly offClick: WithChecks<(listener: VoidFunction, once?: boolean) => void, true>;
+    /**
+     * Mounts the component restoring its state.
+     * @since Mini Apps v6.10
+     */
+    readonly mountFp: WithChecksFp<() => void, true>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<() => void, true>;
+    /**
+     * Unmounts the component.
+     *
+     * Note that this function does not remove listeners added via the `onClick`
+     * function, so you have to remove them on your own.
+     * @see onClick
+     */
+    readonly unmount: () => void;
+}

package/dist/dts/features/SettingsButton/exports.d.ts

@@ -0,0 +1,2 @@
+export { settingsButton } from './instance.js';
+export { type SettingsButtonOptions, SettingsButton, type SettingsButtonState, } from './SettingsButton.js';

package/dist/dts/features/SettingsButton/instance.d.ts

@@ -0,0 +1,2 @@
+import { SettingsButton } from './SettingsButton.js';
+export declare const settingsButton: SettingsButton;

package/dist/dts/features/SwipeBehavior/SwipeBehavior.d.ts

@@ -0,0 +1,62 @@
+import { Computed } from '@tma.js/signals';
+import { PostEventError } from '@tma.js/bridge';
+import { WithChecksFp, WithChecks } from '../../with-checks/withChecksFp.js';
+import { WithStateRestore } from '../../fn-options/withStateRestore.js';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import { WithVersion } from '../../fn-options/withVersion.js';
+import { WithPostEvent } from '../../fn-options/withPostEvent.js';
+import * as E from 'fp-ts/Either';
+export interface SwipeBehaviorState {
+    isVerticalEnabled: boolean;
+}
+export interface SwipeBehaviorOptions extends WithStateRestore<SwipeBehaviorState>, WithVersion, WithPostEvent, SharedFeatureOptions {
+}
+/**
+ * @since Mini Apps v7.7
+ */
+export declare class SwipeBehavior {
+    constructor({ postEvent, storage, isTma, isPageReload, version }: SwipeBehaviorOptions);
+    /**
+     * Signal indicating if the component is supported.
+     */
+    readonly isSupported: Computed<boolean>;
+    /**
+     * Signal indicating if vertical swipes are enabled.
+     */
+    readonly isVerticalEnabled: Computed<boolean>;
+    /**
+     * Signal indicating if the component is currently mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * Mounts the component restoring its state.
+     * @since Mini Apps v7.7
+     */
+    readonly mountFp: WithChecksFp<() => void, true>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<() => void, true>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+    /**
+     * Disables the closing confirmation dialog.
+     * @since Mini Apps v7.7
+     */
+    readonly disableVerticalFp: WithChecksFp<() => E.Either<PostEventError, void>, true>;
+    /**
+     * @see disableVerticalFp
+     */
+    readonly disableVertical: WithChecks<() => void, true>;
+    /**
+     * Enables the closing confirmation dialog.
+     * @since Mini Apps v7.7
+     */
+    readonly enableVerticalFp: WithChecksFp<() => E.Either<PostEventError, void>, true>;
+    /**
+     * @see enableVerticalFp
+     */
+    readonly enableVertical: WithChecks<() => void, true>;
+}

package/dist/dts/features/SwipeBehavior/exports.d.ts

@@ -0,0 +1,2 @@
+export { swipeBehavior } from './instance.js';
+export { type SwipeBehaviorOptions, SwipeBehavior, type SwipeBehaviorState, } from './SwipeBehavior.js';

package/dist/dts/features/SwipeBehavior/instance.d.ts

@@ -0,0 +1,2 @@
+import { SwipeBehavior } from './SwipeBehavior.js';
+export declare const swipeBehavior: SwipeBehavior;

package/dist/dts/features/ThemeParams/ThemeParams.d.ts

@@ -0,0 +1,127 @@
+import { Computed } from '@tma.js/signals';
+import { ThemeParams as ThemeParamsType, RGB } from '@tma.js/types';
+import { EventListener } from '@tma.js/bridge';
+import { WithChecks, WithChecksFp } from '../../with-checks/withChecksFp.js';
+import { CSSVarsBoundError } from '../../errors.js';
+import { WithStateRestore } from '../../fn-options/withStateRestore.js';
+import { SharedFeatureOptions } from '../../fn-options/sharedFeatureOptions.js';
+import { MaybeAccessor } from '../../types.js';
+import * as E from 'fp-ts/Either';
+export type ThemeParamsState = ThemeParamsType;
+export interface ThemeParamsOptions extends WithStateRestore<ThemeParamsState>, SharedFeatureOptions {
+    /**
+     * Removes a theme change listener.
+     * @param listener - a listener to remove.
+     */
+    offChange: (listener: EventListener<'theme_changed'>) => void;
+    /**
+     * Adds a theme change listener.
+     * @returns A function to remove listener.
+     * @param listener - a listener to add.
+     */
+    onChange: (listener: EventListener<'theme_changed'>) => void;
+    /**
+     * Theme parameters initial state.
+     */
+    initialState: MaybeAccessor<ThemeParamsType>;
+}
+export interface ThemeParamsGetCssVarNameFn {
+    /**
+     * @param property - palette key.
+     * @returns Computed complete CSS variable name.
+     */
+    (property: Extract<keyof ThemeParamsType, string>): string;
+}
+export declare class ThemeParams {
+    constructor({ initialState, onChange, offChange, isTma, storage, isPageReload, }: ThemeParamsOptions);
+    /**
+     * @since v6.10
+     */
+    readonly accentTextColor: Computed<RGB | undefined>;
+    readonly bgColor: Computed<RGB | undefined>;
+    readonly buttonColor: Computed<RGB | undefined>;
+    readonly buttonTextColor: Computed<RGB | undefined>;
+    /**
+     * @since v7.10
+     */
+    readonly bottomBarBgColor: Computed<RGB | undefined>;
+    readonly destructiveTextColor: Computed<RGB | undefined>;
+    /**
+     * @since v6.10
+     */
+    readonly headerBgColor: Computed<RGB | undefined>;
+    readonly hintColor: Computed<RGB | undefined>;
+    readonly linkColor: Computed<RGB | undefined>;
+    readonly secondaryBgColor: Computed<RGB | undefined>;
+    /**
+     * @since v6.10
+     */
+    readonly sectionBgColor: Computed<RGB | undefined>;
+    /**
+     * @since v6.10
+     */
+    readonly sectionHeaderTextColor: Computed<RGB | undefined>;
+    /**
+     * @since v7.6
+     */
+    readonly sectionSeparatorColor: Computed<RGB | undefined>;
+    /**
+     * @since v6.10
+     */
+    readonly subtitleTextColor: Computed<RGB | undefined>;
+    readonly textColor: Computed<RGB | undefined>;
+    private readonly _isCssVarsBound;
+    /**
+     * True if CSS variables are currently bound.
+     */
+    readonly isCssVarsBound: Computed<boolean>;
+    /**
+     * Creates CSS variables connected with the current theme parameters.
+     *
+     * By default, created CSS variables names are following the pattern "--tg-theme-{name}", where
+     * {name} is a theme parameters key name converted from snake case to kebab case.
+     *
+     * Default variables:
+     * - `--tg-theme-bg-color`
+     * - `--tg-theme-secondary-text-color`
+     *
+     * Variables are being automatically updated if theme parameters were changed.
+     *
+     * @param getCSSVarName - function, returning complete CSS variable name for the specified
+     * theme parameters key.
+     * @returns Function to stop updating variables.
+     * @throws {CSSVarsBoundError} CSS variables are already bound
+     * @example Using custom CSS vars generator
+     * themeParams.bindCssVars(key => `--my-prefix-${key}`);
+     */
+    readonly bindCssVarsFp: WithChecksFp<(getCSSVarName?: ThemeParamsGetCssVarNameFn) => E.Either<CSSVarsBoundError, VoidFunction>, false>;
+    /**
+     * @see bindCssVarsFp
+     */
+    readonly bindCssVars: WithChecks<(getCSSVarName?: ThemeParamsGetCssVarNameFn) => VoidFunction, false>;
+    /**
+     * Complete component state.
+     */
+    readonly state: Computed<ThemeParamsType>;
+    /**
+     * @returns True if the current color scheme is recognized as dark.
+     * This value is calculated based on the current theme's background color.
+     */
+    readonly isDark: Computed<boolean>;
+    /**
+     * Signal indicating if the component is currently mounted.
+     */
+    readonly isMounted: Computed<boolean>;
+    /**
+     * Mounts the component restoring its state.
+     */
+    readonly mountFp: WithChecksFp<() => E.Either<never, void>, false>;
+    /**
+     * @see mountFp
+     */
+    readonly mount: WithChecks<() => void, false>;
+    /**
+     * Unmounts the component.
+     */
+    readonly unmount: () => void;
+}

package/dist/dts/features/ThemeParams/exports.d.ts

@@ -0,0 +1,2 @@
+export { themeParams } from './instance.js';
+export { type ThemeParamsOptions, ThemeParams, type ThemeParamsState, type ThemeParamsGetCssVarNameFn, } from './ThemeParams.js';

package/dist/dts/features/ThemeParams/instance.d.ts

@@ -0,0 +1,2 @@
+import { ThemeParams } from './ThemeParams.js';
+export declare const themeParams: ThemeParams;