feat: implement Fullscreen

Author: evermake

packages/mini-app-react/src/context.ts

@@ -1,5 +1,6 @@
 import type {
   BackButton,
+  Fullscreen,
   Haptic,
   MainButton,
   SecondaryButton,
@@ -12,6 +13,7 @@ import { createContext } from 'react'
 
 export interface MiniApp {
   viewport: Viewport.Viewport
+  fullscreen: Fullscreen.Fullscreen
   backButton: BackButton.BackButton
   settingsButton: SettingsButton.SettingsButton
   mainButton: MainButton.MainButton

packages/mini-app-react/src/hooks/useFullscreen.ts

@@ -0,0 +1,21 @@
+import { useStore } from '@tanstack/react-store'
+import { useMiniApp } from './useMiniApp'
+
+export interface UseFullscreenReturn {
+  isFullscreen: boolean
+  state: 'fullscreen' | 'not-fullscreen' | 'entering' | 'exiting'
+  setFullscreen: (value: boolean) => Promise<{
+    isFullscreen: boolean
+    error?: 'UNSUPPORTED' | 'ALREADY_FULLSCREEN'
+  }>
+}
+
+export function useFullscreen(): UseFullscreenReturn {
+  const { fullscreen } = useMiniApp()
+  const state = useStore(fullscreen.stateStore, ({ state }) => state)
+  return {
+    isFullscreen: state === 'fullscreen',
+    state,
+    setFullscreen: fullscreen.setFullscreen,
+  }
+}

packages/mini-app-react/src/index.ts

@@ -9,6 +9,10 @@ export { useMiniApp } from './hooks/useMiniApp.ts'
 export type { UseViewportOptions, UseViewportReturn } from './hooks/useViewport.ts'
 export { useViewport } from './hooks/useViewport.ts'
 
+// fullscreen
+export type { UseFullscreenReturn } from './hooks/useFullscreen.ts'
+export { useFullscreen } from './hooks/useFullscreen.ts'
+
 // theme
 export type { UseThemeReturn } from './hooks/useTheme.ts'
 export { useTheme } from './hooks/useTheme.ts'

packages/mini-app/src/Fullscreen.ts

@@ -0,0 +1,73 @@
+import type { Bridge } from './Bridge.ts'
+import type { LaunchParams } from './LaunchParams.ts'
+import type { StoredState } from './SessionStorage.ts'
+import { Store } from '@tanstack/store'
+
+/**
+ * Module for controlling the fullscreen mode of the mini app.
+ */
+export interface Fullscreen {
+  stateStore: Store<State>
+  setFullscreen: (value: boolean) => Promise<{
+    isFullscreen: boolean
+    error?: 'UNSUPPORTED' | 'ALREADY_FULLSCREEN'
+  }>
+}
+
+export interface State {
+  state: 'fullscreen' | 'not-fullscreen' | 'entering' | 'exiting'
+}
+
+const toState = (value: boolean): State['state'] => (value ? 'fullscreen' : 'not-fullscreen')
+
+export const init = (options: {
+  launchParams: LaunchParams
+  bridge: Bridge
+  storedState: StoredState<State>
+}): Fullscreen => {
+  const { launchParams, bridge, storedState } = options
+  const stored = storedState.load()
+  const stateStore = new Store<State>({ state: stored?.state ?? toState(launchParams.fullscreen) })
+  stateStore.subscribe(({ currentVal }) => {
+    storedState.save(currentVal)
+  })
+  let request: null | {
+    promise: ReturnType<Fullscreen['setFullscreen']>
+    resolve: (result: Awaited<ReturnType<Fullscreen['setFullscreen']>>) => void
+  } = null
+  bridge.on('fullscreen_changed', ({ is_fullscreen }) => {
+    stateStore.setState({ state: toState(is_fullscreen) })
+    if (request) {
+      request.resolve({ isFullscreen: is_fullscreen })
+      request = null
+    }
+  })
+  bridge.on('fullscreen_failed', ({ error }) => {
+    stateStore.setState({ state: toState(error === 'ALREADY_FULLSCREEN') })
+    if (request) {
+      request.resolve({
+        isFullscreen: stateStore.state.state === 'fullscreen',
+        error,
+      })
+      request = null
+    }
+  })
+  return {
+    stateStore,
+    setFullscreen: (value) => {
+      if (request) {
+        return request.promise
+      }
+      if (value) {
+        stateStore.setState({ state: 'entering' })
+        bridge.emit('web_app_request_fullscreen')
+      }
+      else {
+        stateStore.setState({ state: 'exiting' })
+        bridge.emit('web_app_exit_fullscreen')
+      }
+      request = Promise.withResolvers()
+      return request.promise
+    },
+  }
+}

packages/mini-app/src/SessionStorage.ts

@@ -15,9 +15,19 @@ export const make = (options: {
   const { storage, transformKey } = options
   return {
     storedState: (key: string) => ({
-      save: state => storage.setItem(transformKey(key), JSON.stringify(state)),
-      load: () => JSON.parse(storage.getItem(transformKey(key)) || 'null'),
-      clear: () => storage.removeItem(transformKey(key)),
+      save: (state) => {
+        storage.setItem(transformKey(key), JSON.stringify(state))
+      },
+      load: () => {
+        const stored = storage.getItem(transformKey(key))
+        if (stored) {
+          return JSON.parse(stored)
+        }
+        return null
+      },
+      clear: () => {
+        storage.removeItem(transformKey(key))
+      },
     }),
   }
 }

packages/mini-app/src/index.ts

@@ -1,6 +1,7 @@
 export * as BackButton from './BackButton.ts'
 export * as Bridge from './Bridge.ts'
 export * as Events from './Events.ts'
+export * as Fullscreen from './Fullscreen.ts'
 export * as Haptic from './Haptic.ts'
 export * as InitParams from './InitParams.ts'
 export * as LaunchParams from './LaunchParams.ts'

tsconfig.lib.json

@@ -2,7 +2,7 @@
   "extends": "./tsconfig.base.json",
   "compilerOptions": {
     "target": "es2020",
-    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
     "baseUrl": ".",
     "rootDir": ".",
     "module": "esnext",