@lingxia/types 0.5.1 → 0.6.0

package/src/index.ts

@@ -5,11 +5,14 @@
  */
 
 export * from './app';
+export * from './lxapp';
 export * from './device';
 export * from './display';
 export * from './input';
+export * from './env';
 export * from './storage';
 export * from './file';
+export * from './transfer';
 export * from './location';
 export * from './navigator';
 export * from './system';
@@ -23,11 +26,17 @@ export * from './generated/i18n';
 import type {
   AppConfig,
   AppInstance,
-  LxAppInfo,
+  HostAppApi,
+  PageMessagePort,
   PageConfig,
   PageInstance,
+  Surface,
 } from './app';
 
+import type {
+  LxAppInfo,
+} from './lxapp';
+
 import type {
   DeviceInfo,
   ScreenInfo,
@@ -41,10 +50,9 @@ import type {
 
 import type { KeyEventCallback } from './input';
 
-import type {
-  LxEnv,
-  Storage,
-} from './storage';
+import type { LxEnv } from './env';
+
+import type { Storage } from './storage';
 
 import type {
   OpenFileOptions,
@@ -52,9 +60,15 @@ import type {
   ChooseDirectoryResult,
   ChooseFileOptions,
   ChooseFileResult,
+  FileManager,
+} from './file';
+
+import type {
   DownloadOptions,
   DownloadTask,
-} from './file';
+  UploadOptions,
+  UploadTask,
+} from './transfer';
 
 import type {
   DeviceOrientation,
@@ -67,7 +81,6 @@ import type {
 } from './location';
 
 import type {
-  AppBaseInfo,
   SystemSettingInfo,
   OpenURLOptions,
 } from './system';
@@ -104,7 +117,6 @@ import type {
   ShowActionSheetOptions,
   ActionSheetResult,
   NavigateToOptions,
-  NavigateToResult,
   NavigateBackOptions,
   RedirectToOptions,
   SwitchTabOptions,
@@ -116,13 +128,24 @@ import type {
   RemoveTabBarBadgeOptions,
   SetTabBarStyleOptions,
   SetTabBarItemOptions,
-  ShowPopupOptions,
-  ShowPopupResult,
+  SurfaceOpenOptions,
   CapsuleRect,
 } from './ui';
 
+export interface SurfaceApi {
+  /**
+   * Dynamically opens a page or URL in a runtime-managed surface.
+   *
+   * `popup` is cross-platform. `window` is a desktop capability and rejects on
+   * mobile platforms.
+   */
+  open(options: SurfaceOpenOptions): Promise<Surface>;
+}
+
 export interface Lx {
   env: LxEnv;
+  app: HostAppApi;
+  surface: SurfaceApi;
 
   getDeviceInfo(): DeviceInfo;
   getScreenInfo(): ScreenInfo;
@@ -152,6 +175,8 @@ export interface Lx {
    */
   openFile(options: OpenFileOptions): void;
   downloadFile(options: DownloadOptions): DownloadTask;
+  uploadFile(options: UploadOptions): UploadTask;
+  getFileManager(): FileManager;
 
   getStorage(): Storage;
 
@@ -160,7 +185,6 @@ export interface Lx {
   navigateToLxApp(options: NavigateToLxAppOptions): Promise<void>;
   navigateBackLxApp(): Promise<void>;
 
-  getAppBaseInfo(): AppBaseInfo;
   getLxAppInfo(): LxAppInfo;
   getSystemSetting(): SystemSettingInfo;
   openURL(options: OpenURLOptions): void;
@@ -203,7 +227,7 @@ export interface Lx {
 
   showActionSheet(options: ShowActionSheetOptions): Promise<ActionSheetResult>;
 
-  navigateTo(options: NavigateToOptions): Promise<NavigateToResult>;
+  navigateTo(options: NavigateToOptions): Promise<PageMessagePort>;
   navigateBack(options: NavigateBackOptions): void;
   redirectTo(options: RedirectToOptions): Promise<void>;
   switchTab(options: SwitchTabOptions): Promise<void>;
@@ -222,17 +246,12 @@ export interface Lx {
   setTabBarStyle(options: SetTabBarStyleOptions): boolean;
   setTabBarItem(options: SetTabBarItemOptions): boolean;
 
-  showPopup(options: ShowPopupOptions): Promise<ShowPopupResult>;
-  hidePopup(): void;
-
   startPullDownRefresh(): void;
   stopPullDownRefresh(): void;
 
   getCapsuleRect(): Promise<CapsuleRect>;
 
-  /** Desktop only. Currently supported on macOS. Windows is planned. */
   chooseFile(options?: ChooseFileOptions): Promise<ChooseFileResult>;
-  /** Desktop only. Currently supported on macOS. Windows is planned. */
   chooseDirectory(options?: ChooseDirectoryOptions): Promise<ChooseDirectoryResult>;
 
   onKeyDown(callback: KeyEventCallback): void;

package/src/input/index.ts

@@ -1,6 +1,5 @@
 /**
- * Input APIs
- * Corresponds to: lingxia-logic/src/input.rs
+ * Input event APIs.
  *
  * Platform support: Android only
  */

package/src/location/index.ts

@@ -1,6 +1,5 @@
 /**
- * Location APIs
- * Corresponds to: lingxia-logic/src/location.rs
+ * Location APIs.
  */
 
 export interface GetLocationOptions {

package/src/lxapp/index.ts

@@ -0,0 +1,12 @@
+/**
+ * LxApp metadata APIs.
+ */
+
+export type LxAppReleaseType = 'release' | 'preview' | 'developer';
+
+export interface LxAppInfo {
+  appId: string;
+  appName: string;
+  version: string;
+  releaseType: LxAppReleaseType;
+}

package/src/media/index.ts

@@ -1,6 +1,5 @@
 /**
- * Media APIs
- * Corresponds to: lingxia-logic/src/media/
+ * Media picker, preview, scan, and file processing APIs.
  */
 
 export interface GetImageInfoOptions {
@@ -188,14 +187,9 @@ export interface PreviewMediaSource {
    * Media source path.
    * Recommended: `lx://` path (for example `lx://usercache/...`) or a sandbox-local path
    * that can be resolved by runtime access rules.
-   */
+  */
   path: string;
   type?: 'image' | 'video';
-  /**
-   * Optional poster image path for video preview.
-   * Uses the same path contract as `path`.
-   */
-  coverPath?: string;
   /**
    * Optional clockwise rotation in degrees (`0 | 90 | 180 | 270`).
    * Default: when omitted, runtime resolves orientation from media metadata.
@@ -207,8 +201,8 @@ export interface PreviewMediaSource {
    */
   objectFit?: MediaObjectFit;
   /**
-   * Image display duration in milliseconds.
-   * Effective only for image items and only when preview `advance` is not `manual`.
+   * Display duration in milliseconds.
+   * Effective when preview `advance` is not `manual`.
    */
   durationMs?: number;
 }

package/src/navigator/index.ts

@@ -1,10 +1,16 @@
 /**
- * LxApp navigator APIs
- * Corresponds to: lingxia-logic/src/navigator.rs
+ * LxApp navigator APIs.
  */
 
+import type { PageQuery } from '../ui';
+
+export type LxAppEnvVersion = 'release' | 'preview' | 'develop';
+
 export interface NavigateToLxAppOptions {
   appId: string;
+  page?: string;
   path?: string;
-  envVersion?: 'develop' | 'trial' | 'release';
+  query?: PageQuery;
+  envVersion?: LxAppEnvVersion;
+  targetVersion?: string;
 }

package/src/storage/index.ts

@@ -1,13 +1,7 @@
 /**
- * Storage APIs
- * Corresponds to: lingxia-logic/src/storage.rs, env.rs
+ * Key-value storage APIs.
  */
 
-export interface LxEnv {
-  USER_DATA_PATH: string;
-  USER_CACHE_PATH: string;
-}
-
 export interface Storage {
   get(key: string): unknown;
   set(key: string, value: unknown): void;

package/src/system/index.ts

@@ -1,15 +1,7 @@
 /**
- * System APIs
- * Corresponds to: lingxia-logic/src/system.rs
+ * System settings and URL APIs.
  */
 
-export interface AppBaseInfo {
-  language: string;
-  productName: string;
-  version: string;
-  SDKVersion: string;
-}
-
 export interface SystemSettingInfo {
   bluetoothEnabled: boolean;
   locationEnabled: boolean;

package/src/transfer/index.ts

@@ -0,0 +1,136 @@
+/**
+ * Transfer task APIs.
+ */
+
+export interface DownloadOptions {
+  /** HTTP(S) source URL. */
+  url: string;
+  /**
+   * Optional request headers.
+   * Restricted headers such as `Referer` are ignored by the runtime.
+   */
+  headers?: Record<string, string>;
+  /** Request timeout in milliseconds. */
+  timeout?: number;
+  /**
+   * Optional durable destination.
+   *
+   * - Omit `filePath` to receive a temporary file in `tempFilePath`
+   * - Relative paths resolve under user data
+   * - `lx://` paths must target `lx://userdata`
+   *
+   * `lx://usercache` is not accepted here.
+   */
+  filePath?: string;
+  /** Optional abort signal. */
+  signal?: AbortSignal;
+}
+
+export interface DownloadProgressEvent {
+  kind: 'progress' | 'paused' | 'resumed' | 'canceled' | 'completed';
+  downloadedBytes?: number;
+  totalBytes?: number;
+  /** Present only when the total size is known. */
+  progress?: number;
+  result?: DownloadResult;
+}
+
+export interface DownloadIteratorResult {
+  done: boolean;
+  value?: DownloadProgressEvent;
+}
+
+export type DownloadResult =
+  | {
+      /**
+       * Temporary result.
+       *
+       * Not durable; move or copy it to `lx://userdata` if you need to keep it.
+       *
+       * When `filePath` is omitted, the runtime must be able to infer a file
+       * type from the URL or the server's `Content-Type` header.
+       */
+      tempFilePath: string;
+      filePath?: never;
+      mimeType?: string;
+      size: number;
+    }
+  | {
+      /** Durable destination under `lx://userdata`. */
+      filePath: string;
+      tempFilePath?: never;
+      mimeType?: string;
+      size: number;
+    };
+
+export interface DownloadTask extends PromiseLike<DownloadResult>, AsyncIterable<DownloadProgressEvent> {
+  next(): Promise<DownloadIteratorResult>;
+  /** Stops iteration only. Does not cancel the underlying download task. */
+  return(): Promise<DownloadIteratorResult>;
+  catch<TResult = never>(
+    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<DownloadResult | TResult>;
+  finally(onfinally?: (() => void) | null): Promise<DownloadResult>;
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+  cancel(): Promise<void>;
+  /** Alias for cancel(), matching browser/mini-program abort naming. */
+  abort(): Promise<void>;
+  wait(): Promise<DownloadResult>;
+}
+
+export interface UploadOptions {
+  /** HTTP(S) destination URL. */
+  url: string;
+  /** Local file path or runtime-managed URI to upload. */
+  filePath: string;
+  /** Multipart field name. Default: `file`. */
+  name?: string;
+  /**
+   * Optional request headers.
+   * Restricted headers such as `Referer` are ignored by the runtime.
+   */
+  headers?: Record<string, string>;
+  /** Optional extra `multipart/form-data` text fields. */
+  formData?: Record<string, string>;
+  /** Request timeout in milliseconds. */
+  timeout?: number;
+  /** Override multipart filename. */
+  fileName?: string;
+  /** Override file MIME type. */
+  mimeType?: string;
+  /** Optional abort signal. */
+  signal?: AbortSignal;
+}
+
+export interface UploadProgressEvent {
+  kind: 'progress' | 'canceled' | 'completed';
+  uploadedBytes?: number;
+  totalBytes?: number;
+  progress?: number;
+  result?: UploadResult;
+}
+
+export interface UploadIteratorResult {
+  done: boolean;
+  value?: UploadProgressEvent;
+}
+
+export interface UploadResult {
+  /** HTTP status code returned by the server. */
+  statusCode: number;
+  /** Response body decoded as UTF-8 text. */
+  data: string;
+}
+
+export interface UploadTask extends PromiseLike<UploadResult>, AsyncIterable<UploadProgressEvent> {
+  next(): Promise<UploadIteratorResult>;
+  /** Stops iteration only. Does not cancel the underlying upload task. */
+  return(): Promise<UploadIteratorResult>;
+  catch<TResult = never>(
+    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<UploadResult | TResult>;
+  finally(onfinally?: (() => void) | null): Promise<UploadResult>;
+  cancel(): Promise<void>;
+  wait(): Promise<UploadResult>;
+}

package/src/ui/index.ts

@@ -1,10 +1,7 @@
 /**
- * UI APIs
- * Corresponds to: lingxia-logic/src/ui/
+ * UI feedback, navigation, and surface control APIs.
  */
 
-import type { EventEmitter } from '../app';
-
 export interface ShowToastOptions {
   title: string;
   icon?: 'success' | 'error' | 'loading' | 'none';
@@ -38,29 +35,32 @@ export interface ActionSheetResult {
   tapIndex: number;
 }
 
-export interface NavigateToOptions {
-  url: string;
-}
+export type PageQueryValue = string | number | boolean | null | undefined;
+export type PageQuery = Record<string, PageQueryValue>;
 
-export interface NavigateToResult {
-  eventEmitter: EventEmitter;
-}
+export type PageTargetOptions =
+  | {
+      page: string;
+      path?: never;
+      query?: PageQuery;
+    }
+  | {
+      path: string;
+      page?: never;
+      query?: PageQuery;
+    };
+
+export type NavigateToOptions = PageTargetOptions;
 
 export interface NavigateBackOptions {
   delta: number;
 }
 
-export interface RedirectToOptions {
-  url: string;
-}
+export type RedirectToOptions = PageTargetOptions;
 
-export interface SwitchTabOptions {
-  url: string;
-}
+export type SwitchTabOptions = PageTargetOptions;
 
-export interface ReLaunchOptions {
-  url: string;
-}
+export type ReLaunchOptions = PageTargetOptions;
 
 export interface SetNavigationBarTitleOptions {
   title: string;
@@ -98,17 +98,67 @@ export interface SetTabBarItemOptions {
   selectedIconPath?: string;
 }
 
-export interface ShowPopupOptions {
+export type SurfaceQueryValue = PageQueryValue;
+export type SurfaceQuery = PageQuery;
+
+export type SurfacePageTargetOptions =
+  | {
+      page: string;
+      path?: never;
+      url?: never;
+      query?: SurfaceQuery;
+    }
+  | {
+      path: string;
+      page?: never;
+      url?: never;
+      query?: SurfaceQuery;
+    };
+
+export type SurfaceUrlTargetOptions = {
   url: string;
-  widthRatio?: number;
-  heightRatio?: number;
-  position?: 'center' | 'bottom' | 'left' | 'right';
+  page?: never;
+  path?: never;
+  query?: never;
+};
+
+export type SurfaceTargetOptions = SurfacePageTargetOptions | SurfaceUrlTargetOptions;
+
+/**
+ * Popup size value.
+ *
+ * - number: absolute size, must be > 0
+ * - `${number}%`: percentage size, must be > 0% and <= 100%
+ */
+export type PopupSurfaceSizeValue = number | `${number}%`;
+
+export interface PopupSurfaceSize {
+  /** Width for popup surface. */
+  width?: PopupSurfaceSizeValue;
+  /** Height for popup surface. */
+  height?: PopupSurfaceSizeValue;
 }
 
-export interface ShowPopupResult {
-  eventEmitter: EventEmitter;
+export type PopupSurfaceOptions = SurfaceTargetOptions & {
+  kind: 'popup';
+  position?: 'center' | 'bottom' | 'left' | 'right' | 'top';
+  size?: PopupSurfaceSize;
+};
+
+export interface WindowSurfaceSize {
+  /** Window width, must be a positive number. */
+  width?: number;
+  /** Window height, must be a positive number. */
+  height?: number;
 }
 
+export type WindowSurfaceOptions = SurfaceTargetOptions & {
+  kind: 'window';
+  size?: WindowSurfaceSize;
+};
+
+export type SurfaceOpenOptions = PopupSurfaceOptions | WindowSurfaceOptions;
+
 export interface CapsuleRect {
   width?: number;
   height?: number;

package/src/update/index.ts

@@ -1,6 +1,5 @@
 /**
- * Update APIs
- * Corresponds to: lingxia-logic/src/update.rs
+ * Runtime update APIs.
  */
 
 export interface UpdateManager {
@@ -12,7 +11,7 @@ export interface UpdateManager {
 export interface UpdateReadyInfo {
   version?: string;
   isForceUpdate?: boolean;
-  releaseType?: "release" | "preview" | "developer" | string;
+  channel?: "release" | "preview" | "developer" | string;
 }
 
 export interface UpdateFailedInfo extends UpdateReadyInfo {