@xiao-ying/miniapp-hooks 1.1.0

package/dist/use-share.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-share.js","sourceRoot":"","sources":["../src/use-share.ts"],"names":[],"mappings":"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"}

package/dist/use-storage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * useStorage 的配置项。
+ *
+ * @param defaultValue - 初始值（当 storage 为空时使用）。
+ * @param disabled - 禁用读写与订阅。
+ */
+export interface UseStorageOptions<T> {
+    defaultValue?: T;
+    disabled?: boolean;
+}
+/**
+ * useStorage 的返回结果。
+ *
+ * - `value`: 当前值
+ * - `loading`: 是否在加载
+ * - `error`: 最近一次错误
+ * - `setValue/remove/refresh`: 操作方法
+ */
+export interface UseStorageResult<T> {
+    value: T | null;
+    loading: boolean;
+    error?: unknown;
+    setValue: (next: T) => Promise<void>;
+    remove: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * 读取并订阅小应小程序存储的指定 key。
+ *
+ * @param key - storage key。
+ * @param options - 读取配置。
+ *
+ * @example
+ * const storage = useStorage<string>('nickname', { defaultValue: '游客' })
+ */
+export declare const useStorage: <T = any>(key: string, options?: UseStorageOptions<T>) => UseStorageResult<T>;
+//# sourceMappingURL=use-storage.d.ts.map

package/dist/use-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-storage.d.ts","sourceRoot":"","sources":["../src/use-storage.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,YAAY,CAAC,EAAE,CAAC,CAAA;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,GAAG,GAAG,EAChC,KAAK,MAAM,EACX,UAAS,iBAAiB,CAAC,CAAC,CAAM,KACjC,gBAAgB,CAAC,CAAC,CA+HpB,CAAA"}

package/dist/use-storage.js

@@ -0,0 +1,132 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * 读取并订阅小应小程序存储的指定 key。
+ *
+ * @param key - storage key。
+ * @param options - 读取配置。
+ *
+ * @example
+ * const storage = useStorage<string>('nickname', { defaultValue: '游客' })
+ */
+export const useStorage = (key, options = {}) => {
+    const { defaultValue, disabled = false } = options;
+    const initialDefault = defaultValue ?? null;
+    const isMounted = useRef(true);
+    const [value, setValueState] = useState(initialDefault);
+    const [loading, setLoading] = useState(!disabled);
+    const [error, setError] = useState();
+    useEffect(() => {
+        isMounted.current = true;
+        return () => {
+            isMounted.current = false;
+        };
+    }, []);
+    const setValueSafe = useCallback((next) => {
+        if (!isMounted.current)
+            return;
+        setValueState(next);
+    }, []);
+    const setLoadingSafe = useCallback((next) => {
+        if (!isMounted.current)
+            return;
+        setLoading(next);
+    }, []);
+    const setErrorSafe = useCallback((next) => {
+        if (!isMounted.current)
+            return;
+        setError(next);
+    }, []);
+    const refresh = useCallback(async () => {
+        if (disabled) {
+            setValueSafe(initialDefault);
+            setLoadingSafe(false);
+            setErrorSafe(undefined);
+            return;
+        }
+        setLoadingSafe(true);
+        try {
+            const res = await xy.getStorage({ key });
+            const resolved = res?.data === null || typeof res?.data === 'undefined' ? initialDefault : res.data;
+            setValueSafe(resolved);
+            setErrorSafe(undefined);
+        }
+        catch (err) {
+            setErrorSafe(err);
+            throw err;
+        }
+        finally {
+            setLoadingSafe(false);
+        }
+    }, [disabled, initialDefault, key, setErrorSafe, setLoadingSafe, setValueSafe, xy]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    useEffect(() => {
+        if (disabled || typeof xy.onStorageChange !== 'function') {
+            return;
+        }
+        const unsubscribe = xy.onStorageChange((event) => {
+            if (!event)
+                return;
+            if (event.key === '*' || event.key === key) {
+                const nextValue = event.key === '*' ? initialDefault : (event.newValue ?? initialDefault);
+                setValueSafe(nextValue);
+                setErrorSafe(undefined);
+            }
+        });
+        return () => {
+            if (typeof unsubscribe === 'function') {
+                unsubscribe();
+            }
+        };
+    }, [disabled, initialDefault, key, setErrorSafe, setValueSafe, xy]);
+    const setValue = useCallback(async (next) => {
+        if (disabled)
+            return;
+        setLoadingSafe(true);
+        try {
+            const res = await xy.setStorage({ key, data: next });
+            if (res?.success === false) {
+                throw new Error('SET_STORAGE_FAILED');
+            }
+            setValueSafe(next);
+            setErrorSafe(undefined);
+        }
+        catch (err) {
+            setErrorSafe(err);
+            throw err;
+        }
+        finally {
+            setLoadingSafe(false);
+        }
+    }, [disabled, key, setErrorSafe, setLoadingSafe, setValueSafe, xy]);
+    const remove = useCallback(async () => {
+        if (disabled)
+            return;
+        setLoadingSafe(true);
+        try {
+            const res = await xy.removeStorage({ key });
+            if (res?.success === false) {
+                throw new Error('REMOVE_STORAGE_FAILED');
+            }
+            setValueSafe(initialDefault);
+            setErrorSafe(undefined);
+        }
+        catch (err) {
+            setErrorSafe(err);
+            throw err;
+        }
+        finally {
+            setLoadingSafe(false);
+        }
+    }, [disabled, initialDefault, key, setErrorSafe, setLoadingSafe, setValueSafe, xy]);
+    return {
+        value,
+        loading,
+        error,
+        setValue,
+        remove,
+        refresh
+    };
+};
+//# sourceMappingURL=use-storage.js.map

package/dist/use-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-storage.js","sourceRoot":"","sources":["../src/use-storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@xiao-ying/miniapp-hooks",
+  "version": "1.1.0",
+  "description": "React hooks for @xiao-ying/miniapp-sdk to build reactive miniapp UIs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "license": "Shanghai Plum Technology Ltd. Software License Agreement",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Liplum",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "@xiao-ying/miniapp-sdk": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.5",
+    "react": "^19.2.0",
+    "typescript": "^5.9.3",
+    "@xiao-ying/miniapp-sdk": "^1.1.0"
+  },
+  "scripts": {
+    "build": "node ../scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "build:publish": "node ../scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+'use client'
+
+export { useBrightness } from './use-brightness.js'
+export { useForeground } from './use-foreground.js'
+export {
+  useMediaQuery,
+  type UseMediaQueryResult
+} from './use-media-query.js'
+export {
+  useStorage,
+  type UseStorageOptions,
+  type UseStorageResult
+} from './use-storage.js'
+export { useShare } from './use-share.js'
+export { useHapticFeedback, type UseHapticFeedbackOptions } from './use-haptic-feedback.js'
+export {
+  useSdkError,
+  type UseSdkErrorOptions,
+  type UseSdkErrorResult,
+  type UseSdkErrorFilter
+} from './use-sdk-error.js'
+// Backward compatibility
+export { useHapticFeedback as useHapticPress } from './use-haptic-feedback.js'
+export { useAuthState } from './use-auth-state.js'
+
+export type {
+  XYSdk,
+  XYMediaQuery,
+  XYSafeAreaInsets,
+  XYViewportSize,
+  XYBrightnessEvent,
+  XYStorageEvent,
+  XyShareData,
+  XyShareHandlerPayload,
+  MaybePromise
+} from '@xiao-ying/miniapp-sdk'

package/src/use-auth-state.ts

@@ -0,0 +1,51 @@
+import { useEffect, useMemo, useState } from 'react'
+import type { XYAuthState } from '@xiao-ying/miniapp-sdk'
+
+// undefined 代表无 XIAOYING_AUTH 权限；其余用 XYAuthState 表示。
+type AuthState = XYAuthState | undefined
+
+const readAuthState = (): AuthState => {
+  try {
+    const current = xy.getAuthState()
+    if (typeof current === 'undefined') return undefined
+    return current ?? { state: 'notSignedIn' }
+  } catch (_) {
+    return { state: 'notSignedIn' }
+  }
+}
+
+/**
+ * 获取并订阅宿主认证状态，提供常用派生字段。
+ *
+ * @returns `{ authState, hasAuthPermission, isSignedIn, userId }`
+ *
+ * @example
+ * const { isSignedIn } = useAuthState()
+ */
+export const useAuthState = () => {
+  const [authState, setAuthState] = useState<AuthState>(() => readAuthState())
+
+  useEffect(() => {
+    if (typeof xy.onAuthStateChange !== 'function') return
+    const unsubscribe = xy.onAuthStateChange((next) => {
+      if (typeof next === 'undefined') {
+        setAuthState(undefined)
+      } else {
+        setAuthState(next ?? { state: 'notSignedIn' })
+      }
+    })
+    return unsubscribe
+  }, [])
+
+  const derived = useMemo(
+    () => ({
+      authState,
+      hasAuthPermission: typeof authState !== 'undefined',
+      isSignedIn: authState?.state === 'signedIn',
+      userId: authState?.state === 'signedIn' ? authState.userId : undefined,
+    }),
+    [authState]
+  )
+
+  return derived
+}

package/src/use-brightness.ts

@@ -0,0 +1,44 @@
+import { useEffect, useMemo, useState } from 'react'
+
+/**
+ * 订阅宿主亮度变化并返回当前亮度信息。
+ *
+ * @returns `{ brightness, isDark }`，亮度变化会触发重新渲染。
+ *
+ * @example
+ * const { brightness, isDark } = useBrightness()
+ */
+export const useBrightness = (): { brightness: 'light' | 'dark'; isDark: boolean } => {
+  const [brightness, setBrightness] = useState<'light' | 'dark'>(() => {
+    try {
+      return xy.brightness() === 'dark' ? 'dark' : 'light'
+    } catch (_) {
+      return 'light'
+    }
+  })
+
+  useEffect(() => {
+    if (typeof xy.onBrightnessChange !== 'function') {
+      return
+    }
+
+    const unsubscribe = xy.onBrightnessChange((event) => {
+      const next = event?.brightness === 'dark' ? 'dark' : 'light'
+      setBrightness(next)
+    })
+
+    return () => {
+      if (typeof unsubscribe === 'function') {
+        unsubscribe()
+      }
+    }
+  }, [xy])
+
+  return useMemo(
+    () => ({
+      brightness,
+      isDark: brightness === 'dark'
+    }),
+    [brightness]
+  )
+}

package/src/use-foreground.ts

@@ -0,0 +1,28 @@
+import { useEffect, useMemo, useState } from 'react'
+/**
+ * 订阅前后台状态变化并返回当前前台状态。
+ *
+ * @returns `{ isForeground }`。
+ *
+ * @example
+ * const { isForeground } = useForeground()
+ */
+export const useForeground = (): { isForeground: boolean } => {
+  const [isForeground, setIsForeground] = useState<boolean>(() => !!xy.isForeground())
+
+  useEffect(() => {
+    const offBg = xy.onBackground(() => setIsForeground(false))
+    const offFg = xy.onForeground(() => setIsForeground(true))
+    return () => {
+      offBg()
+      offFg()
+    }
+  }, [])
+
+  return useMemo(
+    () => ({
+      isForeground
+    }),
+    [isForeground]
+  )
+}

package/src/use-haptic-feedback.ts

@@ -0,0 +1,32 @@
+import { useCallback } from 'react'
+import type { XYVibrateImpact } from '@xiao-ying/miniapp-sdk'
+
+/**
+ * 触感反馈 Hook 的配置项。
+ *
+ * @param impact - 震动强度；传 `false` 禁用。
+ * @param disabled - 是否禁用。
+ */
+export interface UseHapticFeedbackOptions {
+  impact?: XYVibrateImpact | false
+  disabled?: boolean
+}
+
+/**
+ * 返回可复用的触感反馈触发函数；禁用或不支持时为空操作。
+ *
+ * @example
+ * const haptic = useHapticFeedback({ impact: 'medium' })
+ * <button onClick={haptic}>Click</button>
+ */
+export const useHapticFeedback = (options: UseHapticFeedbackOptions = {}): (() => void) => {
+  const { impact = 'selection', disabled = false } = options
+
+  return useCallback(() => {
+    if (disabled || impact === false) return
+    if (typeof xy.vibrate !== 'function') return
+    void xy.vibrate({ impact }).catch(() => {
+      /* best-effort */
+    })
+  }, [disabled, impact, xy])
+}

package/src/use-media-query.ts

@@ -0,0 +1,48 @@
+import { useMemo } from 'react'
+import type { XYMediaQuery } from '@xiao-ying/miniapp-sdk'
+
+/**
+ * useMediaQuery 的返回结果（安全区、尺寸、DPR 等）。
+ *
+ * @property safeAreaInsets - 安全区内边距（px）。
+ * @property size - 视口尺寸（px）。
+ * @property devicePixelRatio - 设备 DPR。
+ */
+export interface UseMediaQueryResult extends XYMediaQuery {
+}
+
+const clampInset = (value?: number): number => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 0
+  return Math.max(0, value)
+}
+
+/**
+ * 获取媒体查询信息（安全区/尺寸/DPR），基于当前 `xy.mediaQuery` 快照。
+ *
+ * @returns 规范化后的媒体查询信息（数值兜底）。
+ *
+ * @example
+ * const { safeAreaInsets } = useMediaQuery()
+ */
+export const useMediaQuery = (): UseMediaQueryResult => {
+  return useMemo(() => {
+    const mediaQuery = (xy.mediaQuery ?? {}) as Partial<XYMediaQuery>
+    const insets = mediaQuery.safeAreaInsets ?? {}
+    const statusBarHeight = clampInset(mediaQuery.statusBarHeight)
+    const devicePixelRatio =
+      typeof mediaQuery.devicePixelRatio === 'number' && Number.isFinite(mediaQuery.devicePixelRatio)
+        ? mediaQuery.devicePixelRatio
+        : 1
+    return {
+      statusBarHeight,
+      safeAreaInsets: {
+        top: clampInset(insets.top),
+        bottom: clampInset(insets.bottom),
+        left: clampInset(insets.left),
+        right: clampInset(insets.right)
+      },
+      size: mediaQuery.size,
+      devicePixelRatio
+    }
+  }, [xy.mediaQuery])
+}

package/src/use-sdk-error.ts

@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import type { XYErrorInfo } from '@xiao-ying/miniapp-sdk'
+
+type XYRuntime = XYErrorInfo['runtime']
+
+/**
+ * SDK 错误过滤条件。
+ *
+ * - `method`: 过滤指定方法名
+ * - `code`: 过滤指定错误码
+ * - `runtime`: 过滤运行时（app/browser/unknown）
+ */
+export interface UseSdkErrorFilter {
+  method?: string | string[]
+  code?: string | string[]
+  runtime?: XYRuntime | XYRuntime[]
+}
+
+/**
+ * useSdkError 配置项。
+ *
+ * @param enabled - 是否启用订阅（默认 `true`）。
+ * @param limit - 缓存的错误数量上限（默认 `8`）。
+ * @param filter - 过滤条件。
+ */
+export interface UseSdkErrorOptions {
+  enabled?: boolean
+  limit?: number
+  filter?: UseSdkErrorFilter
+}
+
+/**
+ * useSdkError 返回值。
+ *
+ * - `latest`: 最新错误
+ * - `errors`: 错误列表
+ * - `clear`: 清空错误
+ */
+export interface UseSdkErrorResult {
+  latest?: XYErrorInfo
+  errors: XYErrorInfo[]
+  clear: () => void
+}
+
+const normalizeFilterSet = <T extends string>(value?: T | T[]): Set<T> | undefined => {
+  if (typeof value === 'undefined') return undefined
+  const items = Array.isArray(value) ? value : [value]
+  const normalized = items.filter((item) => typeof item === 'string' && item.length > 0) as T[]
+  if (normalized.length === 0) return undefined
+  return new Set(normalized)
+}
+
+/**
+ * 订阅 SDK 错误并在组件内维护错误列表。
+ *
+ * @example
+ * const { latest, errors, clear } = useSdkError({ filter: { method: 'request' } })
+ */
+export const useSdkError = (options: UseSdkErrorOptions = {}): UseSdkErrorResult => {
+  const { enabled = true, limit = 8, filter } = options
+  const resolvedLimit = Number.isFinite(limit) ? limit : 8
+
+  const methodSet = useMemo(() => normalizeFilterSet(filter?.method), [filter?.method])
+  const codeSet = useMemo(() => normalizeFilterSet(filter?.code), [filter?.code])
+  const runtimeSet = useMemo(() => normalizeFilterSet(filter?.runtime), [filter?.runtime])
+
+  const matchesFilter = useCallback(
+    (info: XYErrorInfo) => {
+      if (methodSet && !methodSet.has(info.method)) return false
+      if (codeSet && !codeSet.has(info.code)) return false
+      if (runtimeSet && !runtimeSet.has(info.runtime)) return false
+      return true
+    },
+    [methodSet, codeSet, runtimeSet]
+  )
+
+  const [errors, setErrors] = useState<XYErrorInfo[]>([])
+
+  useEffect(() => {
+    if (!enabled || typeof xy.onError !== 'function') {
+      return
+    }
+
+    const unsubscribe = xy.onError((info) => {
+      if (!matchesFilter(info)) return
+      setErrors((prev) => {
+        const next = [info, ...prev]
+        if (resolvedLimit <= 0) return next
+        return next.slice(0, resolvedLimit)
+      })
+    })
+
+    return () => {
+      if (typeof unsubscribe === 'function') {
+        unsubscribe()
+      }
+    }
+  }, [enabled, matchesFilter, resolvedLimit, xy])
+
+  const clear = useCallback(() => setErrors([]), [])
+
+  return useMemo(
+    () => ({
+      latest: errors[0],
+      errors,
+      clear
+    }),
+    [errors, clear]
+  )
+}

package/src/use-share.ts

@@ -0,0 +1,84 @@
+import { useEffect, useMemo } from 'react'
+import type { MaybePromise, XyShareData, XyShareHandlerPayload } from '@xiao-ying/miniapp-sdk'
+
+type SharePayload = Omit<XyShareHandlerPayload, 'path'> & {
+  path?: string
+}
+
+const buildDefaultSharePath = (): string | undefined => {
+  if (typeof window === 'undefined' || typeof window.location === 'undefined') return undefined
+  const { hash, pathname, search } = window.location
+
+  // Hash Router：使用 hash 部分作为真实路径（包含查询）
+  if (hash && hash !== '#') {
+    const hashBody = hash.slice(1) // 去掉开头的 #
+    const normalized = hashBody.startsWith('/') ? hashBody : `/${hashBody}`
+    return `/#${normalized}`
+  }
+
+  // 非 hash：直接使用 pathname + search
+  const safePath = pathname && pathname.startsWith('/') ? pathname : `/${pathname ?? ''}`
+  const safeSearch = typeof search === 'string' ? search : ''
+  return `${safePath || '/'}${safeSearch}`
+}
+
+const normalizeSharePath = (path: string): string => {
+  const hashIndex = path.indexOf('#')
+  if (hashIndex === -1) return path
+  const afterHash = path.slice(hashIndex + 1)
+  if (!afterHash) return '/'
+  return afterHash.startsWith('/') ? afterHash : `/${afterHash}`
+}
+
+const buildDefaultShareTitle = (): string => {
+  const name = typeof xy.manifest?.name === 'string' ? xy.manifest.name.trim() : ''
+  return name || '小应生活'
+}
+
+type ShareHandler = () => MaybePromise<SharePayload | XyShareData | null | undefined>
+
+/**
+ * 注册分享处理器，自动补齐默认 path 与 title。
+ *
+ * - 传入函数：自定义动态返回分享数据
+ * - 传入对象：作为静态配置
+ * - 不传：使用默认配置（自动 path/title）
+ *
+ * @param input - 处理器函数或静态分享对象。
+ *
+ * @example
+ * useShare(() => ({
+ *   title: '示例',
+ *   path: '/home'
+ * }))
+ */
+export const useShare = (input?: ShareHandler | SharePayload | XyShareData | null): void => {
+  const resolveHandler = useMemo<ShareHandler>(() => {
+    if (typeof input === 'function') return input
+    if (!input) return () => ({})
+    const payload = input
+    return () => payload
+  }, [input])
+
+  const wrappedHandler = useMemo(
+    () => async () => {
+      const res = await resolveHandler()
+      if (!res || typeof res !== 'object') return res
+
+      let path = res.path ?? buildDefaultSharePath()
+      const title = res.title ?? buildDefaultShareTitle()
+      if (!path) return null
+      path = normalizeSharePath(path)
+
+      // 返回符合 XyShareData 的结构，确保 path 为 string
+      const { path: _ignoredPath, title: _ignoredTitle, ...rest } = res
+      return { ...rest, path, title } as XyShareData
+    },
+    [resolveHandler]
+  )
+
+  useEffect(() => {
+    xy.setShareHandler(wrappedHandler)
+    return () => xy.setShareHandler(null)
+  }, [wrappedHandler, xy])
+}