@lingxia/types 0.8.0 → 0.10.0

package/src/share/index.ts

@@ -0,0 +1,97 @@
+/**
+ * Share APIs.
+ */
+
+export type ShareQuery = Record<string, string | number | boolean>;
+
+export type SharePage =
+  /**
+   * Share the current page.
+   */
+  | true
+  /**
+   * Share the current page with query.
+   */
+  | {
+      /**
+       * Query appended to the current page. Query belongs to the page target and is
+       * encoded into the AppLink URL.
+       */
+      query?: ShareQuery;
+    };
+
+interface ShareTitleOptions {
+  /**
+   * Share title.
+   */
+  title?: string;
+}
+
+interface ShareTextBaseOptions extends ShareTitleOptions {
+  /**
+   * Share text body.
+   */
+  text?: string;
+}
+
+/**
+ * Share title/text only. Receiver support is platform/app dependent; some
+ * share extensions may reject text-only shares.
+ */
+export interface ShareTextOptions extends ShareTextBaseOptions {
+  page?: never;
+  files?: never;
+}
+
+/**
+ * Share the current page as an AppLink.
+ */
+export interface SharePageOptions extends ShareTextBaseOptions {
+  /**
+   * Share the current page. The runtime uses the current appId and page path
+   * implicitly and shares it through the host AppLink configuration.
+   *
+   * Rejects when the host app has no `appLinks.hosts` configuration because
+   * receivers would not be able to open the shared page.
+   *
+   * `title` and `text` are presentation hints. Platforms and receivers may
+   * ignore them; on iOS the URL is shared by itself so receivers can render it
+   * as a webpage card when they support that.
+   *
+   * `page` and `files` are mutually exclusive.
+   */
+  page: SharePage;
+  files?: never;
+}
+
+/**
+ * Share images, PDFs, or other files.
+ */
+export interface ShareFilesOptions extends ShareTitleOptions {
+  /**
+   * File paths returned by LingXia APIs to share. Images, PDFs, and other
+   * documents are all represented as file paths.
+   *
+   * Use `lx.chooseFile` for system files and `lx.chooseMedia` for picked media;
+   * pass the returned path here without parsing it.
+   * Some platforms or receivers may limit multi-file shares. Share files one
+   * at a time when targeting those receivers.
+   *
+   * `files` and `page` are mutually exclusive.
+   * `text` is intentionally not supported for file shares because system
+   * receivers handle text+attachment inconsistently.
+   */
+  files: string[];
+  page?: never;
+  text?: never;
+}
+
+export type ShareOptions = ShareTextOptions | SharePageOptions | ShareFilesOptions;
+
+export interface ShareResult {
+  /**
+   * Best-effort completion flag. Some platforms can only confirm that the
+   * system share UI was opened or closed.
+   */
+  completed?: boolean;
+}

package/src/system/index.ts

@@ -1,5 +1,5 @@
 /**
- * System settings and URL APIs.
+ * System settings.
  */
 
 export interface SystemSettingInfo {
@@ -7,8 +7,3 @@ export interface SystemSettingInfo {
   locationEnabled: boolean;
   wifiEnabled: boolean;
 }
-
-export interface OpenURLOptions {
-  url: string;
-  target?: 'self' | 'external';
-}

package/src/transfer/index.ts

@@ -2,7 +2,22 @@
  * Transfer task APIs.
  */
 
-export interface DownloadOptions {
+declare const appDownloadPathBrand: unique symbol;
+declare const systemDownloadsPathBrand: unique symbol;
+
+export type DownloadDestination = 'app' | 'downloads';
+
+/** Runtime-managed app download path, usually under `lx://userdata`. */
+export type AppDownloadFilePath = string & {
+  readonly [appDownloadPathBrand]: 'app-download-file-path';
+};
+
+/** Native system Downloads path. Do not pass this to `FileManager`. */
+export type SystemDownloadsPath = string & {
+  readonly [systemDownloadsPathBrand]: 'system-downloads-path';
+};
+
+export interface DownloadOptionsBase {
   /** HTTP(S) source URL. */
   url: string;
   /**
@@ -12,35 +27,66 @@ export interface DownloadOptions {
   headers?: Record<string, string>;
   /** Request timeout in milliseconds. */
   timeout?: number;
+  /** Optional abort signal. */
+  signal?: AbortSignal;
+}
+
+export interface AppDownloadOptions extends DownloadOptionsBase {
   /**
-   * Optional durable destination.
-   *
-   * - Omit `filePath` to receive a temporary file in `tempFilePath`
-   * - Relative paths resolve under user data
-   * - `lx://` paths must target `lx://userdata`
+   * Optional app-owned durable output path.
    *
+   * Omit `filePath` to receive a temporary result 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;
+  /**
+   * App-owned output. Omit to use a temporary output unless `filePath` is set.
+   */
+  destination?: 'app';
+}
+
+export interface DownloadsDownloadOptions extends DownloadOptionsBase {
+  /**
+   * Optional filename hint for the system Downloads destination.
+   * This is not an app-owned FileManager path.
+   */
+  filePath?: string;
+  /** Save into the user's system Downloads directory. */
+  destination: 'downloads';
 }
 
-export interface DownloadProgressEvent {
+/**
+ * Download options.
+ *
+ * - `app`: app-owned temporary output, or durable `lx://userdata` output when
+ *   `filePath` is set
+ * - `downloads`: user-visible system Downloads output, requiring
+ *   `security.privileges: ["downloads"]` in `lxapp.json`
+ *
+ * Default: `app`.
+ */
+export type DownloadOptions<TDestination extends DownloadDestination = DownloadDestination> =
+  TDestination extends 'downloads' ? DownloadsDownloadOptions : AppDownloadOptions;
+
+export type DownloadResultForDestination<TDestination extends DownloadDestination> =
+  TDestination extends 'downloads' ? DownloadsDownloadResult : AppDownloadResult;
+
+export interface DownloadProgressEvent<TResult extends DownloadResult = DownloadResult> {
   kind: 'progress' | 'paused' | 'resumed' | 'canceled' | 'completed';
   downloadedBytes?: number;
   totalBytes?: number;
   /** Present only when the total size is known. */
   progress?: number;
-  result?: DownloadResult;
+  result?: TResult;
 }
 
-export interface DownloadIteratorResult {
+export interface DownloadIteratorResult<TResult extends DownloadResult = DownloadResult> {
   done: boolean;
-  value?: DownloadProgressEvent;
+  value?: DownloadProgressEvent<TResult>;
 }
 
-export type DownloadResult =
+export type AppDownloadResult =
   | {
       /**
        * Temporary result.
@@ -57,26 +103,38 @@ export type DownloadResult =
     }
   | {
       /** Durable destination under `lx://userdata`. */
-      filePath: string;
+      filePath: AppDownloadFilePath;
       tempFilePath?: never;
       mimeType?: string;
       size: number;
     };
 
-export interface DownloadTask extends PromiseLike<DownloadResult>, AsyncIterable<DownloadProgressEvent> {
-  next(): Promise<DownloadIteratorResult>;
+export interface DownloadsDownloadResult {
+  /** Native system Downloads path. Do not pass this to `FileManager`. */
+  filePath: SystemDownloadsPath;
+  tempFilePath?: never;
+  mimeType?: string;
+  size: number;
+}
+
+export type DownloadResult = AppDownloadResult | DownloadsDownloadResult;
+
+export interface DownloadTask<TDownloadResult extends DownloadResult = DownloadResult>
+  extends PromiseLike<TDownloadResult>,
+    AsyncIterable<DownloadProgressEvent<TDownloadResult>> {
+  next(): Promise<DownloadIteratorResult<TDownloadResult>>;
   /** 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>;
+  return(): Promise<DownloadIteratorResult<TDownloadResult>>;
+  catch<TRejected = never>(
+    onrejected?: ((reason: unknown) => TRejected | PromiseLike<TRejected>) | null,
+  ): Promise<TDownloadResult | TRejected>;
+  finally(onfinally?: (() => void) | null): Promise<TDownloadResult>;
   pause(): Promise<void>;
   resume(): Promise<void>;
   cancel(): Promise<void>;
   /** Alias for cancel(), matching browser/mini-program abort naming. */
   abort(): Promise<void>;
-  wait(): Promise<DownloadResult>;
+  wait(): Promise<TDownloadResult>;
 }
 
 export interface UploadOptions {

package/src/ui/index.ts

@@ -38,13 +38,33 @@ export interface ActionSheetResult {
 export type PageQueryValue = string | number | boolean | null | undefined;
 export type PageQuery = Record<string, PageQueryValue>;
 
+/**
+ * Target page for `navigateTo` / `redirectTo` / `switchTab` / `reLaunch`.
+ *
+ * Pass **exactly one** of `page` or `path` — there is **no `url` field**:
+ * - `page` — a configured page **name** from `lingxia.yaml` / `lxapp.json`
+ *   (e.g. `"pullToRefresh"`), resolved to its route by the page registry.
+ * - `path` — the full page **route**, e.g. `"/pages/pulltorefresh/index"`.
+ *
+ * Both are discoverable with `lxdev lxapp pages`, which lists every page's
+ * `name` and `path`; `lxdev lxapp nav to|relaunch|redirect|switch-tab <name>`
+ * drives navigation by name when automating.
+ */
 export type PageTargetOptions =
   | {
+      /**
+       * Configured page **name** from `lingxia.yaml` / `lxapp.json`
+       * (e.g. `"pullToRefresh"`). Mutually exclusive with `path`.
+       */
       page: string;
       path?: never;
       query?: PageQuery;
     }
   | {
+      /**
+       * Full page **route**, e.g. `"/pages/pulltorefresh/index"`.
+       * Mutually exclusive with `page`.
+       */
       path: string;
       page?: never;
       query?: PageQuery;
@@ -98,77 +118,42 @@ export interface SetTabBarItemOptions {
   selectedIconPath?: string;
 }
 
-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;
-  page?: never;
-  path?: never;
-  query?: never;
-};
-
-export type SurfaceTargetOptions = SurfacePageTargetOptions | SurfaceUrlTargetOptions;
+// ── Adaptive Surface Layout ─────────────────────────────────────────────────
+// The form is expressed by the `as` field on `lx.openSurface({ page, as })`; the
+// Host arbitrates the realized platform form (split pane on larger screens,
+// full-screen drill-in on compact screens).
 
 /**
- * Overlay surface size value.
+ * Size hint for an overlay surface (aside / float).
  *
- * - number: absolute size, must be > 0
- * - `${number}%`: percentage size, must be > 0% and <= 100%
+ * - number: absolute px, must be > 0
+ * - `${number}%`: percentage of the container, 0 < N ≤ 100
  */
 export type OverlaySurfaceSizeValue = number | `${number}%`;
 
 export interface OverlaySurfaceSize {
-  /** Width for overlay surface. */
+  /** Width hint. */
   width?: OverlaySurfaceSizeValue;
-  /** Height for overlay surface. */
+  /** Height hint. */
   height?: OverlaySurfaceSizeValue;
 }
 
-/**
- * Overlay surface: a webview composited on top of the host activity's
- * content. Cross-platform. Covers the screen (or a fraction of it) until
- * closed; coexists with native media preview at the same z-tier — the
- * later-added overlay or preview wins compositing order.
- */
-export type OverlaySurfaceOptions = SurfaceTargetOptions & {
-  kind: 'overlay';
-  position?: 'center' | 'bottom' | 'left' | 'right' | 'top';
-  size?: OverlaySurfaceSize;
-};
-
-export interface WindowSurfaceSize {
-  /** Window width, must be a positive number. */
-  width?: number;
-  /** Window height, must be a positive number. */
-  height?: number;
-}
+/** Edge an aside docks to; the Host decides the realized form by screen size. */
+export type SurfaceEdge = 'left' | 'right' | 'top' | 'bottom';
+
+/** Where a float popup anchors (default `center`). */
+export type SurfaceFloatPosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
 
 /**
- * Window-kind surfaces are macOS-only. Android, iOS, and Harmony reject
- * `kind: 'window'` at open() and surface a `surface_open_failed` error;
- * use `OverlaySurfaceOptions` for cross-platform code.
+ * The window's adaptive context, delivered to `lx.onSurfaceContext()` so an
+ * lxapp can self-adapt (e.g. switch column count by `sizeClass`).
  */
-export type WindowSurfaceOptions = SurfaceTargetOptions & {
-  kind: 'window';
-  size?: WindowSurfaceSize;
-};
-
-export type SurfaceOpenOptions = OverlaySurfaceOptions | WindowSurfaceOptions;
+export interface SurfaceContext {
+  /** compact (<600) / medium (600–840) / expanded (>840), with hysteresis. */
+  sizeClass: 'compact' | 'medium' | 'expanded';
+  /** In compact, the bottom region belongs to the app content. */
+  bottomOwner: 'app';
+}
 
 export interface CapsuleRect {
   width?: number;