@lingxia/types 0.10.0 → 0.11.1

package/src/app/index.ts

@@ -1,378 +0,0 @@
-/**
- * Host app, app lifecycle, and page instance APIs.
- */
-
-export interface AppBaseInfo {
-  language: string;
-  productName: string;
-  version: string;
-  SDKVersion: string;
-}
-
-export interface HostAppUpdateInfo {
-  version: string;
-  size?: number;
-  releaseNotes?: string[];
-  isForceUpdate: boolean;
-  /**
-   * Download and apply this checked update.
-   *
-   * `apply()` is single-use for this update object.
-   *
-   * The returned task can be awaited directly when progress is not needed, or
-   * consumed with `for await...of` to render progress.
-   *
-   * Direct package handoff is currently supported on Android and macOS. Other
-   * platforms reject with an unsupported-operation error; use `version` and
-   * `releaseNotes` to guide users to the appropriate app marketplace.
-   */
-  apply(): HostAppUpdateTask;
-}
-
-export type HostAppUpdateApplyStage = 'download' | 'install';
-
-export type HostAppUpdateCheckResult =
-  | {
-      hasUpdate: false;
-      update?: never;
-    }
-  | {
-      hasUpdate: true;
-      update: HostAppUpdateInfo;
-    };
-
-export type HostAppUpdateEvent =
-  | {
-      state: 'downloading';
-      downloadedBytes?: number;
-      progress?: number;
-    }
-  | {
-      state: 'downloaded' | 'installRequested';
-    }
-  | {
-      state: 'failed';
-      stage: HostAppUpdateApplyStage;
-      error: string;
-    };
-
-export interface HostAppUpdateResult {
-  state: 'installRequested';
-}
-
-export interface HostAppUpdateIteratorResult {
-  done: boolean;
-  value?: HostAppUpdateEvent;
-}
-
-export interface HostAppUpdateTask
-  extends PromiseLike<HostAppUpdateResult>,
-    AsyncIterable<HostAppUpdateEvent> {
-  next(): Promise<HostAppUpdateIteratorResult>;
-  /** Stops iteration only. It does not cancel an app update already handed to the platform. */
-  return(): Promise<HostAppUpdateIteratorResult>;
-  catch<TResult = never>(
-    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
-  ): Promise<HostAppUpdateResult | TResult>;
-  finally(onfinally?: (() => void) | null): Promise<HostAppUpdateResult>;
-  wait(): Promise<HostAppUpdateResult>;
-}
-
-/**
- * Build-time environment version of the host app.
- *
- * Surfaced via {@link HostAppApi.envVersion}. Mirrors the
- * `crates/lingxia-update::ReleaseType` enum and the `envVersion` field in the
- * generated `app.json`. Pre-envVersion app artifacts are treated as `'release'`.
- *
- * Note: this is *separate* from `LxAppEnvVersion` in the navigator module,
- * which encodes lxapp release channels (`'develop' | 'preview' | 'release'`)
- * for cross-app navigation URLs and uses the truncated `develop` form.
- */
-export type HostAppEnvVersion = 'developer' | 'preview' | 'release';
-
-export interface AppScreenshotOptions {
-  /**
-   * Platform-specific window id to capture (desktop only). Omit to let the
-   * platform pick: the key/main window on desktop, the sole window on mobile.
-   */
-  windowId?: string;
-}
-
-export interface AppScreenshotResult {
-  /** `lx://` URI of the captured PNG in the lxapp temp directory. */
-  tempFilePath: string;
-  /** Image width in pixels, when the runtime could read it from the PNG. */
-  width?: number;
-  /** Image height in pixels, when the runtime could read it from the PNG. */
-  height?: number;
-}
-
-export interface HostAppApi {
-  /**
-   * The environment this build was produced for, mirroring `app.json::envVersion`.
-   * Always present; defaults to `'release'` for builds produced before the field
-   * existed in the artifact.
-   *
-   * Use this to branch on environment-specific behavior (e.g. verbose logging in
-   * developer builds, distinct theme tinting, distinct error-reporter tags).
-   * Synchronous; the value is fixed at app boot.
-   */
-  readonly envVersion: HostAppEnvVersion;
-
-  getBaseInfo(): AppBaseInfo;
-
-  /**
-   * Check whether the host app has an update.
-   *
-   * This is a host app level capability and is only available to the home
-   * lxapp. Non-home lxapps receive a permission error.
-   *
-   * Calling this API opts the host app into custom update handling for this
-   * process. LingXia will not show its built-in host app update UI or
-   * auto-install host app updates after that point.
-   *
-   * If no update is available, or if an update requires a newer LingXia
-   * runtime than the current host app provides, `hasUpdate` is `false`.
-   *
-   * `checkUpdate()` may return version metadata on platforms that cannot apply
-   * host app packages directly. In that case, `update.apply()` rejects with an
-   * unsupported-operation error.
-   */
-  checkUpdate(): Promise<HostAppUpdateCheckResult>;
-
-  /**
-   * Exit the host app immediately.
-   *
-   * This API does not show a confirmation dialog. If the user should confirm
-   * first, call `lx.showModal(...)` in page logic and invoke `lx.app.exit()`
-   * only after the user confirms.
-   */
-  exit(): void;
-
-  /**
-   * Capture the host app's window as a PNG and save it to the lxapp temp
-   * directory.
-   *
-   * App-level semantics — one level above any page/WebView capture: the image
-   * is what the user currently sees of the whole app, including host-drawn
-   * navigation chrome, native overlays, and every composited WebView. Because
-   * that view can include other lxapps' UI, this API is only available to the
-   * home lxapp; other lxapps receive a permission error.
-   */
-  screenshot(options?: AppScreenshotOptions): Promise<AppScreenshotResult>;
-
-  /**
-   * Set the app-icon badge — e.g. an unread count.
-   *
-   * Cross-platform: the dock (macOS), the taskbar (Windows), and the home /
-   * launcher icon (iOS, Android). Pass `null` or an empty string to clear it.
-   * On platforms where it is not wired this is a no-op (it never throws), so it
-   * is safe to call from portable code.
-   */
-  setBadge(value: string | number | null): void;
-}
-
-export interface AppLifecycleEventArgs {
-  source: 'host' | 'lxapp';
-  reason:
-    | 'foreground'
-    | 'background'
-    | 'screenshot'
-    | 'open'
-    | 'close'
-    | 'switch_back'
-    | 'switch_away';
-}
-
-export interface AppLaunchOptions {
-  path?: string;
-  query?: Record<string, string>;
-  scene?: number;
-  referrerInfo?: {
-    appId?: string;
-    extraData?: Record<string, unknown>;
-  };
-}
-
-export interface AppConfig {
-  globalData?: Record<string, unknown>;
-  onLaunch?: (options?: AppLaunchOptions) => void | Promise<void>;
-  onShow?: (args?: AppLifecycleEventArgs) => void | Promise<void>;
-  onHide?: (args?: AppLifecycleEventArgs) => void | Promise<void>;
-  onUserCaptureScreen?: () => void | Promise<void>;
-  [key: string]: unknown;
-}
-
-export interface AppInstance extends AppConfig {
-  globalData: Record<string, unknown>;
-}
-
-export interface PageLoadOptions {
-  [key: string]: string | undefined;
-}
-
-export interface PageConfig<TData extends Record<string, unknown> = Record<string, unknown>> {
-  data?: TData;
-  onLoad?: (options?: PageLoadOptions) => void | Promise<void>;
-  onShow?: () => void | Promise<void>;
-  onReady?: () => void | Promise<void>;
-  onHide?: () => void | Promise<void>;
-  onUnload?: () => void | Promise<void>;
-  onPullDownRefresh?: () => void | Promise<void>;
-  [key: string]: unknown;
-}
-
-export type SurfaceCloseReason =
-  | 'user'
-  | 'programmatic'
-  | 'owner_closed'
-  | 'app_closed'
-  | 'failed'
-  /**
-   * The SDK reclaimed a long-hidden overlay surface for resource reasons.
-   * Treat as a normal close: the page instance is gone; further postMessage /
-   * show / hide calls will fail. The opener may immediately reopen if needed.
-   */
-  | 'reclaimed'
-  | 'unknown';
-
-export interface SurfaceClosedEvent {
-  id: string;
-  kind: 'overlay' | 'window';
-  reason: SurfaceCloseReason;
-}
-
-/**
- * Detail payload for `onShow` / `onHide` events. `source` identifies which
- * Surface object initiated the visibility change so observers can
- * distinguish self-driven transitions from peer-driven ones (e.g. an opener
- * UI that wants to update its own button state only when the page side
- * toggled visibility).
- */
-export interface SurfaceVisibilityEvent {
-  id: string;
-  kind: 'overlay' | 'window';
-  source: 'opener' | 'page';
-}
-
-export interface SurfaceHandle {
-  readonly id: string;
-  /**
-   * Show a host-managed surface. Dynamic page/url surfaces return a Promise;
-   * host-declared surfaces may complete synchronously.
-   */
-  show(): void | Promise<void>;
-  /**
-   * Hide without destroying user-visible state when the platform supports it.
-   */
-  hide(): void | Promise<void>;
-  /**
-   * Close or hide the surface depending on how it is managed by the host.
-   */
-  close(): void | Promise<void>;
-}
-
-export interface Surface extends SurfaceHandle {
-  readonly kind: 'overlay' | 'window';
-  /**
-   * Last-known visibility, kept in sync with the native side via show/hide
-   * events. False once the surface has been closed. Safe to bind into
-   * declarative UI; for event-driven updates subscribe via `onShow`/`onHide`.
-   */
-  readonly visible: boolean;
-  /**
-   * True until `close()` fires. After close the surface is detached and the
-   * page instance is being torn down; further `show()` / `hide()` calls will
-   * reject.
-   */
-  readonly alive: boolean;
-  /**
-   * Sends a message to the other side of a page surface.
-   *
-   * For the opener this targets the opened page. For the opened page this
-   * targets the opener. URL surfaces have no page-side receiver.
-  */
-  postMessage(message: unknown): void;
-  onMessage(handler: (message: unknown) => void): () => void;
-  onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
-  /**
-   * Fires when the surface transitions to visible, regardless of whether
-   * `show()` was called on this side or on the peer. Returns an unsubscribe
-   * function. Only fires on real state changes — calling `show()` on an
-   * already-visible surface is a no-op for listeners.
-   */
-  onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
-  /**
-   * Fires when the surface transitions to hidden, regardless of which side
-   * triggered it. Returns an unsubscribe function. Only fires on real state
-   * changes.
-   */
-  onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
-  close(): Promise<void>;
-  /**
-   * Toggle the surface to visible without tearing it down. The page instance
-   * and its state survive a hide / show round-trip — only close() actually
-   * destroys the surface and fires the onClose listener. Idempotent: calling
-   * on an already-visible surface resolves without firing `onShow`.
-   */
-  show(): Promise<void>;
-  /**
-   * Hide the surface without destroying it. The page instance stays mounted,
-   * so a subsequent show() restores the same scroll position, form input,
-   * and JS state. Hidden surfaces still receive postMessage but are not
-   * visible to the user. Idempotent.
-   */
-  hide(): Promise<void>;
-}
-
-export interface PageMessagePort {
-  postMessage(message: unknown): void;
-  onMessage(handler: (message: unknown) => void): () => void;
-}
-
-export interface PageInstance<TData extends Record<string, unknown> = Record<string, unknown>> {
-  data: TData;
-  route: string;
-  /**
-   * Available when this page was opened as a surface via `lx.openSurface(...)`.
-   */
-  surface?: Surface;
-  /**
-   * Available when this page was opened by `lx.navigateTo(...)`.
-   */
-  opener?: PageMessagePort;
-  setData(data: Partial<TData> | Record<string, unknown>, callback?: () => void): void;
-}
-
-/**
- * Injected by the runtime into methods listed in `stream_handlers` page metadata.
- *
- * Use this when your async source uses callbacks rather than an async iterator.
- * For the generator form (`async *method()`), no handle is needed — the runtime
- * pumps the generator automatically.
- */
-export interface StreamHandle<T = unknown> {
-  /** Send a chunk to View. */
-  send(payload: T): void;
-  /** End the stream with an optional final value. */
-  end(result?: unknown): void;
-  /** End the stream with an error. */
-  error(code: string, message?: string): void;
-}
-
-/**
- * Injected by the runtime as the second parameter when View opens a channel.
- *
- * Use `ch.send()` to push data to View, `ch.on()` to receive data/close
- * events from View, and `ch.close()` to shut down the channel.
- */
-export interface ChannelHandle<TSend = unknown, TReceive = unknown> {
-  /** Push a message to View. */
-  send(payload: TSend): void;
-  /** Close the channel from Logic side. */
-  close(code?: string, reason?: string): void;
-  /** Register a listener for incoming events. */
-  on(event: 'data', handler: (payload: TReceive) => void): void;
-  on(event: 'close', handler: (info: { code: string; reason: string }) => void): void;
-}

package/src/device/actions.ts

@@ -1,7 +0,0 @@
-/**
- * Device action APIs.
- */
-
-export interface MakePhoneCallOptions {
-  phoneNumber: string;
-}

package/src/device/index.ts

@@ -1,4 +0,0 @@
-export * from './info';
-export * from './actions';
-export * from './wifi';
-export * from './network';

package/src/device/info.ts

@@ -1,17 +0,0 @@
-/**
- * Device info APIs.
- */
-
-export interface DeviceInfo {
-  brand: string;
-  model: string;
-  marketName: string;
-  osName: string;
-  osVersion: string;
-}
-
-export interface ScreenInfo {
-  width: number;
-  height: number;
-  scale: number;
-}

package/src/device/network.ts

@@ -1,23 +0,0 @@
-/**
- * Network status APIs.
- */
-
-// Matches mini-program style where possible: wifi/2g/3g/4g/5g/none/unknown.
-export type NetworkType =
-  | 'none'
-  | 'unknown'
-  | 'wifi'
-  | '2g'
-  | '3g'
-  | '4g'
-  | '5g'
-  | 'ethernet';
-
-export interface NetworkInfo {
-  isConnected: boolean;
-  networkType: NetworkType;
-  ipv4: string[];
-  ipv6: string[];
-}
-
-export type NetworkChangeCallback = (info: NetworkInfo) => void;

package/src/device/wifi.ts

@@ -1,23 +0,0 @@
-/**
- * Wi-Fi APIs.
- */
-
-export interface WifiInfo {
-  SSID: string;
-  BSSID?: string;
-  secure: boolean;
-  signalStrength: number;
-  frequency?: number;
-}
-
-export interface WifiConnectedInfo extends WifiInfo {
-  connected: boolean;
-  state: string;
-}
-
-export interface ConnectWifiOptions {
-  SSID: string;
-  password?: string;
-}
-
-export type WifiConnectedCallback = (info: WifiConnectedInfo) => void;

package/src/display/index.ts

@@ -1,9 +0,0 @@
-/**
- * Display and orientation APIs.
- */
-
-export type DeviceOrientation = "portrait" | "landscape";
-
-export interface DeviceOrientationChangeEvent {
-  value: DeviceOrientation;
-}

package/src/env/index.ts

@@ -1,8 +0,0 @@
-/**
- * Runtime environment constants.
- */
-
-export interface LxEnv {
-  USER_DATA_PATH: string;
-  USER_CACHE_PATH: string;
-}

package/src/file/index.ts

@@ -1,171 +0,0 @@
-/**
- * File system APIs.
- */
-
-export interface OpenFileOptions {
-  /** Local file path or runtime-managed temp path. */
-  filePath: string;
-  /** Optional coarse file type hint such as `pdf`, `docx`, or `xlsx`. */
-  fileType?: string;
-  /**
-   * `auto`: prefer native review, then fall back to external open.
-   * `review`: require native review UI and reject when unsupported.
-   * `external`: hand off directly to the system / external app.
-   */
-  mode?: 'auto' | 'review' | 'external';
-  /** Hint for whether the native review UI should expose its action menu when supported. */
-  showMenu?: boolean;
-}
-
-export interface FileDialogFilter {
-  /** Optional label shown in the native dialog. */
-  name?: string;
-  /** Allowed extensions without dots, e.g. ['pdf', 'txt']. */
-  extensions: string[];
-}
-
-export interface ChooseFileOptions {
-  /** Allow selecting multiple files. Default: false */
-  multiple?: boolean;
-  /** Optional file filters. Empty or omitted means all file types. */
-  filters?: FileDialogFilter[];
-  /**
-   * Initial directory the dialog opens in.
-   *
-   * When this resolves to an app-local directory, LingXia may use its internal
-   * file picker. When omitted, the platform system file picker is used.
-   */
-  defaultPath?: string;
-}
-
-export interface ChooseFileResult {
-  /** True if the user dismissed the dialog without selecting. */
-  canceled: boolean;
-  /**
-   * File paths returned by LingXia. Values may be app-local paths, `lx://...`
-   * paths, or platform system-picker references. Treat them as opaque strings
-   * and pass them back to LingXia APIs such as `lx.share`.
-   */
-  paths: string[];
-}
-
-export interface ChooseDirectoryOptions {
-  /** Initial directory the dialog opens in. Platform default if omitted. */
-  defaultPath?: string;
-}
-
-export interface ChooseDirectoryResult {
-  /** True if the user dismissed the dialog without selecting. */
-  canceled: boolean;
-  /** Native-consumable directory reference (path or URI). Undefined when canceled. */
-  path?: string;
-}
-
-export interface ExistsOptions {
-  path: string;
-}
-
-export interface StatOptions {
-  path: string;
-}
-
-export interface FileStats {
-  isFile: boolean;
-  isDirectory: boolean;
-  isSymlink: boolean;
-  size: number;
-  lastModifiedTime?: number;
-  lastAccessedTime?: number;
-  createTime?: number;
-}
-
-export interface ReadDirOptions {
-  path: string;
-}
-
-export interface DirEntry {
-  name: string;
-  isFile: boolean;
-  isDirectory: boolean;
-  isSymlink: boolean;
-}
-
-export interface MkdirOptions {
-  path: string;
-  recursive?: boolean;
-}
-
-export interface ReadTextFileOptions {
-  filePath: string;
-  encoding: 'utf8' | 'base64';
-}
-
-export interface ReadBinaryFileOptions {
-  filePath: string;
-  encoding?: undefined;
-}
-
-export type ReadFileOptions = ReadTextFileOptions | ReadBinaryFileOptions;
-
-export interface ReadTextFileResult {
-  data: string;
-}
-
-export interface ReadBinaryFileResult {
-  data: ArrayBuffer;
-}
-
-export type ReadFileResult = ReadTextFileResult | ReadBinaryFileResult;
-
-export type BinaryFileData = ArrayBuffer | ArrayBufferView;
-
-export interface WriteTextFileOptions {
-  filePath: string;
-  data: string;
-  encoding?: 'utf8' | 'base64';
-  /** Defaults to false. */
-  overwrite?: boolean;
-}
-
-export interface WriteBinaryFileOptions {
-  filePath: string;
-  data: BinaryFileData;
-  encoding?: never;
-  /** Defaults to false. */
-  overwrite?: boolean;
-}
-
-export type WriteFileOptions = WriteTextFileOptions | WriteBinaryFileOptions;
-
-export interface CopyFileOptions {
-  srcPath: string;
-  destPath: string;
-  /** Defaults to false. */
-  overwrite?: boolean;
-}
-
-export interface RenameOptions {
-  oldPath: string;
-  newPath: string;
-  /** Defaults to false. */
-  overwrite?: boolean;
-}
-
-export interface RemoveOptions {
-  path: string;
-  recursive?: boolean;
-}
-
-export interface FileManager {
-  exists(options: ExistsOptions): Promise<boolean>;
-  stat(options: StatOptions): Promise<FileStats>;
-  readDir(options: ReadDirOptions): Promise<AsyncIterableIterator<DirEntry>>;
-  mkdir(options: MkdirOptions): Promise<void>;
-  readFile(options: ReadTextFileOptions): Promise<ReadTextFileResult>;
-  readFile(options: ReadBinaryFileOptions): Promise<ReadBinaryFileResult>;
-  readFile(options: ReadFileOptions): Promise<ReadFileResult>;
-  writeFile(options: WriteFileOptions): Promise<void>;
-  copyFile(options: CopyFileOptions): Promise<void>;
-  rename(options: RenameOptions): Promise<void>;
-  remove(options: RemoveOptions): Promise<void>;
-}

package/src/input/index.ts

@@ -1,19 +0,0 @@
-/**
- * Input event APIs.
- *
- * Platform support: Android only
- */
-
-export interface KeyEvent {
-  /** Key value following W3C naming (e.g. "Enter", "ArrowLeft", "a") */
-  key: string;
-  /** Physical key code (e.g. "ENTER", "DPAD_LEFT") */
-  code: string;
-  altKey?: boolean;
-  ctrlKey?: boolean;
-  shiftKey?: boolean;
-  metaKey?: boolean;
-  repeat?: boolean;
-}
-
-export type KeyEventCallback = (event: KeyEvent) => void;

package/src/location/index.ts

@@ -1,20 +0,0 @@
-/**
- * Location APIs.
- */
-
-export interface GetLocationOptions {
-  type?: 'wgs84' | 'gcj02';
-  altitude?: boolean;
-  isHighAccuracy?: boolean;
-  highAccuracyExpireTime?: number;
-}
-
-export interface LocationInfo {
-  latitude: number;
-  longitude: number;
-  speed?: number;
-  accuracy?: number;
-  altitude?: number;
-  verticalAccuracy?: number;
-  horizontalAccuracy?: number;
-}

package/src/lxapp/index.ts

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