@lingxia/types 0.8.0 → 0.10.0

package/src/app/index.ts

@@ -91,6 +91,23 @@ export interface HostAppUpdateTask
  */
 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`.
@@ -132,6 +149,28 @@ export interface HostAppApi {
    * 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 {
@@ -217,8 +256,24 @@ export interface SurfaceVisibilityEvent {
   source: 'opener' | 'page';
 }
 
-export interface Surface {
+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
@@ -280,7 +335,7 @@ export interface PageInstance<TData extends Record<string, unknown> = Record<str
   data: TData;
   route: string;
   /**
-   * Available when this page was opened by `lx.surface.open(...)`.
+   * Available when this page was opened as a surface via `lx.openSurface(...)`.
    */
   surface?: Surface;
   /**

package/src/file/index.ts

@@ -29,14 +29,23 @@ export interface ChooseFileOptions {
   multiple?: boolean;
   /** Optional file filters. Empty or omitted means all file types. */
   filters?: FileDialogFilter[];
-  /** Initial directory the dialog opens in. Platform default if omitted. */
+  /**
+   * 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;
-  /** Native-consumable file references (paths or URIs). Empty when canceled. */
+  /**
+   * 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[];
 }
 

package/src/generated/i18n.ts

@@ -26,37 +26,26 @@ export const I18N_KEYS = [
   "camera_switch_to_front",
   "camera_switching",
   "camera_tap_to_capture",
-  "camera_tap_to_record",
-  "camera_tap_to_stop",
   "camera_video_input_failed",
   "camera_video_output_failed",
   "capsule_clean_cache",
   "capsule_restart",
   "capsule_uninstall",
-  "common_auto",
   "common_back",
   "common_cancel",
   "common_close",
   "common_confirm",
   "common_delete",
   "common_done",
-  "common_edit",
-  "common_home",
   "common_loading",
   "common_ok",
-  "common_retry",
-  "common_save",
-  "common_settings",
-  "common_share",
-  "common_success",
-  "common_warning",
+  "common_refresh",
   "date_last_30_days",
   "date_last_7_days",
   "date_last_month",
   "date_last_week",
   "date_this_month",
   "date_this_week",
-  "document_pdf_page_preview",
   "err_code_1000",
   "err_code_1001",
   "err_code_1002",
@@ -96,13 +85,10 @@ export const I18N_KEYS = [
   "err_code_6000",
   "err_code_6001",
   "err_code_6002",
-  "error_network_error",
-  "error_save_failed",
-  "error_server_error",
-  "error_timeout",
-  "error_unauthorized",
-  "error_unknown",
   "error_video_too_short",
+  "file_chooser_choose_images",
+  "file_chooser_choose_media",
+  "file_chooser_choose_videos",
   "file_chooser_default_title",
   "file_chooser_empty_subtitle",
   "file_chooser_empty_title",
@@ -113,19 +99,26 @@ export const I18N_KEYS = [
   "file_chooser_filtered_empty_subtitle",
   "file_chooser_filtered_empty_title",
   "file_chooser_folder_subtitle",
+  "file_chooser_select_file",
+  "file_chooser_select_folder",
   "permission_limited_access_add_more_media",
   "permission_limited_access_add_more_photos",
   "permission_limited_access_add_more_videos",
   "permission_limited_access_warning",
-  "permission_location_reason",
   "permission_media_reason",
-  "permission_network_reason",
-  "permission_wifi_reason",
-  "update_confirm",
-  "update_download_failed",
+  "terminal_change_title",
+  "terminal_close_pane",
+  "terminal_copy",
+  "terminal_new_tab",
+  "terminal_paste",
+  "terminal_read_only",
+  "terminal_reset",
+  "terminal_split_down",
+  "terminal_split_left",
+  "terminal_split_right",
+  "terminal_split_up",
+  "terminal_title",
   "update_downloading",
-  "update_message",
-  "update_title",
   "video_quality",
   "video_speed",
 ] as const;

package/src/index.ts

@@ -18,6 +18,7 @@ export * from './navigator';
 export * from './system';
 export * from './update';
 export * from './media';
+export * from './share';
 export * from './ui';
 export * from './error';
 export * from './generated/error';
@@ -31,6 +32,7 @@ import type {
   PageConfig,
   PageInstance,
   Surface,
+  SurfaceHandle,
 } from './app';
 
 import type {
@@ -64,8 +66,14 @@ import type {
 } from './file';
 
 import type {
+  AppDownloadOptions,
+  AppDownloadResult,
+  DownloadDestination,
   DownloadOptions,
+  DownloadResultForDestination,
   DownloadTask,
+  DownloadsDownloadOptions,
+  DownloadsDownloadResult,
   UploadOptions,
   UploadTask,
 } from './transfer';
@@ -82,7 +90,6 @@ import type {
 
 import type {
   SystemSettingInfo,
-  OpenURLOptions,
 } from './system';
 
 import type { NavigateToLxAppOptions } from './navigator';
@@ -95,7 +102,7 @@ import type {
   CompressImageOptions,
   CompressImageResult,
   CompressVideoOptions,
-  CompressVideoResult,
+  CompressVideoTask,
   GetVideoInfoOptions,
   VideoInfo,
   ExtractVideoThumbnailOptions,
@@ -110,6 +117,11 @@ import type {
   VideoContext,
 } from './media';
 
+import type {
+  ShareOptions,
+  ShareResult,
+} from './share';
+
 import type {
   ShowToastOptions,
   ShowModalOptions,
@@ -128,24 +140,213 @@ import type {
   RemoveTabBarBadgeOptions,
   SetTabBarStyleOptions,
   SetTabBarItemOptions,
-  SurfaceOpenOptions,
+  SurfaceEdge,
+  SurfaceFloatPosition,
+  OverlaySurfaceSize,
+  SurfaceContext,
   CapsuleRect,
 } from './ui';
 
-export interface SurfaceApi {
+interface WindowSurfaceSize {
+  /** Initial window width in logical pixels. */
+  width?: number;
+  /** Initial window height in logical pixels. */
+  height?: number;
+}
+
+/**
+ * Spec for {@link Lx.openSurface}. A discriminated union keyed by source so a
+ * page name and a declared surface id never collide (each is its own string
+ * space, separately type-checkable).
+ *
+ * - `{ page }` — one of this lxapp's own pages, by name, arranged as `as`
+ *   (`aside` is a companion of the main; `float` is a popup; `window` is a bare
+ *   desktop window, which rejects on mobile). `edge` applies to `aside`,
+ *   `position` applies to `float`, and `size` is a Host-clamped hint. They are
+ *   fixed at open (re-open to change).
+ *
+ *   `aside` is **size-class adaptive**, not a fixed form: only on `medium` /
+ *   `expanded` (room to sit alongside) does it dock and split beside the main at
+ *   `edge` as a sidebar/split panel. On `compact` (phone, or a folded foldable)
+ *   there is no room to dock, so the same surface presents **full-screen** —
+ *   pushed over the main and dismissed by the host back affordance / edge swipe
+ *   (a drill-in), never a docked panel. So one declaration reads as a side panel
+ *   on large screens and a full-screen drill-in on small ones. For a destination
+ *   that should stay switchable on phones, declare it `role: main` instead.
+ *
+ *   `float` is a popup layered above the main at `position` (like a dialog); it
+ *   takes no layout space. The SDK gives it **no chrome of its own — there is no
+ *   built-in close button**: the lxapp owns the popup UI and dismisses it by
+ *   calling `surface.close()` (or `.hide()`). A float sized to the full container
+ *   (`size: { width: '100%', height: '100%' }`) presents immersively on mobile
+ *   (system bars hidden) and is likewise chrome-less — draw your own close
+ *   affordance. (iOS retains a silent left-edge swipe as a last-resort escape so a
+ *   full-screen float can never trap the user; don't rely on it as the primary
+ *   dismissal.)
+ * - `{ surface }` — a surface declared in `lingxia.yaml` `surfaces:`, by id
+ *   (e.g. `'terminal'`, `'ai-assistant'`). Form, position, and startup data come
+ *   from the declaration.
+ * - `{ url }` — an `http(s)://` or `lingxia://` url, shown in the in-app chromed
+ *   browser (always with an address bar — never a chromeless embed). Without
+ *   `as` it opens as a main browser tab (host chrome, no handle). With
+ *   `as: 'aside'` it docks an `http(s)://` page beside the main as a single
+ *   browser aside (its own chrome + close, returns a closable handle); `edge`
+ *   defaults to `'right'` and `size` is a host-clamped preferred size. At most
+ *   one browser aside per window — a new one replaces the existing one.
+ */
+export type OpenPageSurfaceSpec =
+  | {
+      page: string;
+      as: 'aside';
+      edge?: SurfaceEdge;
+      size?: OverlaySurfaceSize;
+      query?: Record<string, unknown>;
+      position?: never;
+      surface?: never;
+      url?: never;
+    }
+  | {
+      page: string;
+      /**
+       * A chrome-less popup above the main: the lxapp draws its own UI and close
+       * affordance — there is no SDK-provided close button (see
+       * {@link OpenPageSurfaceSpec}).
+       */
+      as: 'float';
+      position?: SurfaceFloatPosition;
+      size?: OverlaySurfaceSize;
+      query?: Record<string, unknown>;
+      edge?: never;
+      surface?: never;
+      url?: never;
+    }
+  | {
+      page: string;
+      as: 'window';
+      size?: WindowSurfaceSize;
+      query?: Record<string, unknown>;
+      edge?: never;
+      position?: never;
+      surface?: never;
+      url?: never;
+    };
+
+export interface OpenDeclaredSurfaceSpec {
+  surface: string;
+  page?: never;
+  url?: never;
+  as?: never;
+  edge?: never;
+  position?: never;
+  size?: never;
+  query?: never;
+}
+
+export interface OpenUrlTabSpec {
+  url: string;
+  as?: never;
+  page?: never;
+  surface?: never;
+  edge?: never;
+  position?: never;
+  size?: never;
+  query?: never;
+}
+
+export interface OpenUrlAsideSpec {
+  url: string;
+  as: 'aside';
+  edge?: SurfaceEdge;
+  size?: OverlaySurfaceSize;
+  page?: never;
+  surface?: never;
+  position?: never;
+  query?: never;
+}
+
+export type OpenSurfaceSpec =
+  | OpenPageSurfaceSpec
+  | OpenDeclaredSurfaceSpec
+  | OpenUrlTabSpec
+  | OpenUrlAsideSpec;
+
+/**
+ * Runtime control of the menu-bar (macOS) / system-tray (Windows) status item.
+ * The tray is declared in `lingxia.yaml` (`tray:`); these update its dynamic
+ * content at runtime.
+ *
+ * **Desktop only.** Mobile platforms have no tray, so every method here is a
+ * no-op there (it never throws) — safe to call from portable code. For an
+ * app-icon badge that *is* cross-platform (including mobile), use
+ * {@link HostAppApi.setBadge}.
+ */
+export interface TrayMenuItem {
+  label: string;
+  /** Invoked when this item is clicked. */
+  onClick?: () => void;
+  enabled?: boolean;
+  checked?: boolean;
+}
+
+export interface TrayMenuSeparator {
+  separator: true;
+}
+
+export interface TrayApi {
+  /** Replace the status-item icon (a resource path). */
+  setIcon(icon: string): void;
+  /** Set the text shown beside the icon (macOS). Pass `null`/empty to clear. */
+  setTitle(text: string | null): void;
+  /** Set the badge — e.g. an unread count. Pass `null`/empty to clear. */
+  setBadge(value: string | number | null): void;
   /**
-   * Dynamically opens a page or URL in a runtime-managed surface.
+   * Replace the right-click dropdown menu. There is no default menu — provide
+   * your own items (e.g. `{ label: 'Quit', onClick: () => lx.app.exit() }`).
    *
-   * `overlay` is cross-platform. `window` is a desktop capability and rejects
-   * on mobile platforms.
+   * The menu is a snapshot: to change an item's `checked`/`enabled`/`label`
+   * state, call `setMenu` again with the full updated array. There is no
+   * per-item mutation API.
+   */
+  setMenu(items: Array<TrayMenuItem | TrayMenuSeparator>): void;
+  /**
+   * Handle a left-click on the tray icon yourself. While a handler is
+   * registered the click runs only the handler — the tray's configured surface
+   * `action` is suppressed, so the click is fully yours (e.g. toggle a state and
+   * `setIcon`). Returns an unsubscribe function.
    */
-  open(options: SurfaceOpenOptions): Promise<Surface>;
+  onClick(handler: () => void): () => void;
+  /** Show the tray status item. */
+  show(): void;
+  /** Hide the tray status item (without removing the app). */
+  hide(): void;
 }
 
 export interface Lx {
   env: LxEnv;
   app: HostAppApi;
-  surface: SurfaceApi;
+  tray: TrayApi;
+
+  /**
+   * Open a surface.
+   *
+   * - `{ url }` without `as` opens a host browser tab and resolves to `null`.
+   * - `{ surface }` resolves to a host-managed handle with show/hide/close.
+   * - page surfaces and `{ url, as: 'aside' }` resolve to a full Surface handle.
+   *
+   * `as: 'window'` is desktop-only and rejects on mobile. See
+   * {@link OpenSurfaceSpec}.
+   */
+  openSurface(spec: OpenUrlTabSpec): Promise<null>;
+  openSurface(spec: OpenDeclaredSurfaceSpec): Promise<SurfaceHandle>;
+  openSurface(spec: OpenPageSurfaceSpec | OpenUrlAsideSpec): Promise<Surface>;
+  openSurface(spec: OpenSurfaceSpec): Promise<Surface | SurfaceHandle | null>;
+  /** Hand a url off to the OS default browser (leaves the app). */
+  openExternal(url: string): void;
+  /**
+   * Subscribe to adaptive-context changes ({@link SurfaceContext}); the handler
+   * fires with the new context. Returns an unsubscribe function.
+   */
+  onSurfaceContext(handler: (context: SurfaceContext) => void): () => void;
 
   getDeviceInfo(): DeviceInfo;
   getScreenInfo(): ScreenInfo;
@@ -174,7 +375,11 @@ export interface Lx {
    * otherwise prefer `mode: 'auto'`.
    */
   openFile(options: OpenFileOptions): void;
-  downloadFile(options: DownloadOptions): DownloadTask;
+  downloadFile(options: DownloadsDownloadOptions): DownloadTask<DownloadsDownloadResult>;
+  downloadFile(options: AppDownloadOptions): DownloadTask<AppDownloadResult>;
+  downloadFile<TDestination extends DownloadDestination = 'app'>(
+    options: DownloadOptions<TDestination>,
+  ): DownloadTask<DownloadResultForDestination<TDestination>>;
   uploadFile(options: UploadOptions): UploadTask;
   getFileManager(): FileManager;
 
@@ -187,13 +392,12 @@ export interface Lx {
 
   getLxAppInfo(): LxAppInfo;
   getSystemSetting(): SystemSettingInfo;
-  openURL(options: OpenURLOptions): void;
 
   getUpdateManager(): UpdateManager;
 
   getImageInfo(options: GetImageInfoOptions): Promise<ImageInfo>;
   compressImage(options: CompressImageOptions): Promise<CompressImageResult>;
-  compressVideo(options: CompressVideoOptions): Promise<CompressVideoResult>;
+  compressVideo(options: CompressVideoOptions): CompressVideoTask;
   getVideoInfo(options: GetVideoInfoOptions): Promise<VideoInfo>;
   extractVideoThumbnail(options: ExtractVideoThumbnailOptions): Promise<ExtractVideoThumbnailResult>;
 
@@ -208,9 +412,12 @@ export interface Lx {
    * - a sequence object for multi-item preview with `sources`, `startIndex`, and `advance`
    *
    * Returns a {@link PreviewMediaHandle} synchronously. Await `handle.completed`
-   * for the final session result (`reason`, `lastIndex`). Subscribe to
-   * `handle.presented` to learn when the first pixel hits the screen — useful
-   * for coordinating a hide of any overlay surface that was previously visible.
+   * for the final session result (`reason`, `index`, `source` — the item the
+   * user was viewing when the preview closed). Subscribe to
+   * `handle.onChange(...)` / read `handle.current` to follow the viewed item
+   * live, and to `handle.presented` to learn when the first pixel hits the
+   * screen — useful for coordinating a hide of any overlay surface that was
+   * previously visible.
    *
    * `handle.completed` rejects with a cancellation error if `signal` is aborted;
    * abort also requests the active native preview session to close immediately.
@@ -223,6 +430,8 @@ export interface Lx {
 
   scanCode(options?: ScanCodeOptions): Promise<ScanCodeResult>;
 
+  share(options: ShareOptions): Promise<ShareResult>;
+
   createVideoContext(componentId: string): VideoContext;
 
   showToast(options: ShowToastOptions): void;

package/src/media/index.ts

@@ -73,6 +73,41 @@ export interface CompressVideoResult {
   type: string;
 }
 
+export interface CompressVideoProgressEvent {
+  /** Transcode progress in percent, `0`-`100`. */
+  progress: number;
+}
+
+export interface CompressVideoIteratorResult {
+  done: boolean;
+  value?: CompressVideoProgressEvent;
+}
+
+/**
+ * Handle returned by `lx.compressVideo`.
+ *
+ * Awaiting the task resolves with the final {@link CompressVideoResult}.
+ * Iterating it with `for await` yields {@link CompressVideoProgressEvent}s
+ * while the transcode runs.
+ */
+export interface CompressVideoTask
+  extends PromiseLike<CompressVideoResult>,
+    AsyncIterable<CompressVideoProgressEvent> {
+  next(): Promise<CompressVideoIteratorResult>;
+  /** Stops iteration only. Does not cancel the compression. */
+  return(): Promise<CompressVideoIteratorResult>;
+  catch<TResult = never>(
+    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<CompressVideoResult | TResult>;
+  finally(onfinally?: (() => void) | null): Promise<CompressVideoResult>;
+  /**
+   * Cancels the transcode and deletes any partial output.
+   * The task promise rejects with an `AbortError` (`code: 'E_ABORT'`).
+   */
+  cancel(): void;
+  wait(): Promise<CompressVideoResult>;
+}
+
 export interface GetVideoInfoOptions {
   /**
    * Video file path or `lx://` URI.
@@ -279,35 +314,68 @@ export type PreviewMediaOptions =
 
 export type PreviewMediaCloseReason = 'manual' | 'completed' | 'interrupted' | 'error';
 
+/**
+ * The item the user is (or was) looking at, handed back as the caller
+ * described it — `path` is returned verbatim, so it can be matched against
+ * the caller's own data without re-indexing an array.
+ */
+export interface PreviewMediaShownSource {
+  /** The path exactly as passed in the request. */
+  path: string;
+  /** Resolved media kind (after extension inference when `type` was omitted). */
+  type: 'image' | 'video';
+}
+
+/** One change-stream event / the `current` snapshot. */
+export interface PreviewMediaChange {
+  index: number;
+  source: PreviewMediaShownSource;
+}
+
 export interface PreviewMediaResult {
   /**
    * Why the preview session finished.
    */
   reason: PreviewMediaCloseReason;
   /**
-   * Last active item index before close.
+   * Index of the item on screen when the session closed.
+   */
+  index: number;
+  /**
+   * The item on screen when the session closed — "what the user just
+   * viewed/played", without mapping `index` back yourself.
    */
-  lastIndex: number;
+  source: PreviewMediaShownSource;
 }
 
 /**
- * Handle returned synchronously from `lx.previewMedia(...)`. Exposes two
- * independent Promises so callers can coordinate transitions:
+ * Handle returned synchronously from `lx.previewMedia(...)` — synchronous so
+ * listeners can be attached before the first event fires:
  *
  * - `presented` resolves once the first pixel of the underlying media has
  *   been composited to screen. Use this to time the hide of an overlay
  *   surface above the preview so the swap is seamless. Never rejects;
  *   resolves with no value when the first frame is up. Safe to ignore.
- * - `completed` resolves when the preview session ends (manual / auto /
- *   interrupted / error). Replaces the previous `Promise<PreviewMediaResult>`
- *   that `previewMedia` used to return directly.
+ * - `current` is a live `{ index, source }` snapshot of the item on screen,
+ *   updated as the user swipes and as the session auto-advances.
+ * - `onChange(listener)` fires for every item change. Returns an
+ *   unsubscribe function.
+ * - `completed` resolves `{ reason, index, source }` when the preview
+ *   session ends (manual / auto / interrupted / error), or rejects on abort.
  *
  * If the call was aborted before any frame was presented, `presented` still
  * resolves (with no value) once the abort takes effect — it never rejects,
  * to keep fire-and-forget usage safe.
+ *
+ * @example
+ * const preview = lx.previewMedia({ sources, startIndex: 2 });
+ * preview.onChange(({ source }) => markAsViewed(source.path));
+ * const { reason, source } = await preview.completed;
  */
 export interface PreviewMediaHandle {
   readonly presented: Promise<void>;
+  readonly current: PreviewMediaChange;
+  onChange(listener: (change: PreviewMediaChange) => void): () => void;
   readonly completed: Promise<PreviewMediaResult>;
 }