@lingxia/types 0.1.2 → 0.4.3

package/src/media/index.ts

@@ -25,6 +25,146 @@ export interface CompressImageResult {
   tempFilePath: string;
 }
 
+export type VideoCompressQuality = 'low' | 'medium' | 'high';
+
+export interface CompressVideoOptions {
+  /**
+   * Source video path or `lx://` URI.
+   */
+  path: string;
+  /**
+   * Cross-platform note: video compression parameters are best-effort and may map to
+   * native presets instead of exact encoder settings.
+   *
+   * Compression quality preset.
+   * When provided, `bitrate`, `fps`, and `resolution` are ignored.
+   */
+  quality?: VideoCompressQuality;
+  /**
+   * Preferred target video bitrate in kbps.
+   * May be adjusted or ignored by platform codec/runtime limitations.
+   */
+  bitrate?: number;
+  /**
+   * Preferred target frame rate in fps.
+   * Some platforms may ignore this option.
+   */
+  fps?: number;
+  /**
+   * Target resolution scale ratio relative to source size, in range `(0, 1]`.
+   * May be approximated or ignored by platform transcoder capabilities.
+   */
+  resolution?: number;
+  /**
+   * Optional output path for compressed file.
+   */
+  outputPath?: string;
+}
+
+export interface CompressVideoResult {
+  tempFilePath: string;
+  width: number;
+  height: number;
+  durationMs: number;
+  /**
+   * Output file size in bytes.
+   * Could be close to source size when platform falls back to source content.
+   */
+  size: number;
+  type: string;
+}
+
+export interface GetVideoInfoOptions {
+  /**
+   * Video file path or `lx://` URI.
+   */
+  path: string;
+}
+
+export interface VideoInfo {
+  /**
+   * Encoded display width in pixels.
+   */
+  width: number;
+  /**
+   * Encoded display height in pixels.
+   */
+  height: number;
+  /**
+   * Video duration in milliseconds.
+   */
+  durationMs: number;
+  /**
+   * Clockwise rotation in degrees (usually `0 | 90 | 180 | 270`).
+   */
+  rotation?: number;
+  /**
+   * Average bitrate in bits per second (bps).
+   */
+  bitrate?: number;
+  /**
+   * Frame rate in frames per second (fps).
+   */
+  fps?: number;
+  /**
+   * MIME type, e.g. `video/mp4`.
+   */
+  type?: string;
+  /**
+   * Resolved path used by runtime (typically `lx://...`).
+   */
+  path: string;
+}
+
+export interface ExtractVideoThumbnailOptions {
+  /**
+   * Source video path or `lx://` URI.
+   */
+  path: string;
+  /**
+   * Optional output image path. If omitted, runtime chooses a temporary path.
+   */
+  outputPath?: string;
+  /**
+   * Max output width in pixels.
+   * Optional; when set with/without `maxHeight`, output keeps aspect ratio (no cropping).
+   */
+  maxWidth?: number;
+  /**
+   * Max output height in pixels.
+   * Optional; when set with/without `maxWidth`, output keeps aspect ratio (no cropping).
+   */
+  maxHeight?: number;
+  /**
+   * Target frame time in milliseconds from video start.
+   * `0` means first frame.
+   */
+  timeMs?: number;
+  /**
+   * JPEG quality in range `0-100`.
+   */
+  quality?: number;
+}
+
+export interface ExtractVideoThumbnailResult {
+  /**
+   * Generated thumbnail file path.
+   */
+  tempFilePath: string;
+  /**
+   * Output image width in pixels.
+   */
+  width: number;
+  /**
+   * Output image height in pixels.
+   */
+  height: number;
+  /**
+   * Output MIME type, usually `image/jpeg`.
+   */
+  type: string;
+}
+
 export interface ChooseMediaOptions {
   count?: number;
   mediaType?: ('image' | 'video')[];
@@ -39,14 +179,121 @@ export interface ChosenMediaEntry {
   isOriginal: boolean;
 }
 
-export interface PreviewMediaItem {
+export type MediaRotation = 0 | 90 | 180 | 270;
+
+export type MediaObjectFit = 'cover' | 'contain' | 'fill' | 'fit';
+
+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.
+   */
+  rotate?: MediaRotation;
+  /**
+   * Optional display fit mode for video preview.
+   * Default: `contain`.
+   */
+  objectFit?: MediaObjectFit;
+  /**
+   * Image display duration in milliseconds.
+   * Effective only for image items and only when preview `advance` is not `manual`.
+   */
+  durationMs?: number;
+}
+
+export type PreviewMediaAdvance = 'manual' | 'next' | 'loop';
+
+export interface PreviewMediaSingleOptions extends PreviewMediaSource {
+  /**
+   * Auto behavior for the preview session.
+   *
+   * - `manual`: never auto-advance
+   * - `next`: advance to the next item; if already on the last item, close the session
+   * - `loop`: advance to the next item; if already on the last item, wrap to the first item
+   *
+   * Default: `manual`
+   */
+  advance?: PreviewMediaAdvance;
+  /**
+   * Optional cancellation signal for the preview request.
+   *
+   * Aborting rejects the returned promise with a cancellation error and requests the active
+   * native preview session to close immediately.
+   */
+  signal?: AbortSignal;
+  /**
+   * Whether to show the top `current/total` indicator.
+   *
+   * Default: `true` when previewing multiple items, otherwise `false`.
+   */
+  showIndexIndicator?: boolean;
 }
 
-export interface PreviewMediaOptions {
-  sources: PreviewMediaItem[];
+export interface PreviewMediaSequenceOptions {
+  /**
+   * Preview list. Supports images, videos, or a mixed queue.
+   */
+  sources: PreviewMediaSource[];
+  /**
+   * Initial item index in `sources`.
+   * Must be an integer.
+   * Out-of-range values are clamped by runtime.
+   * Default: `0`.
+   */
+  startIndex?: number;
+  /**
+   * Auto behavior for the preview session.
+   *
+   * - `manual`: never auto-advance
+   * - `next`: advance to the next item; if already on the last item, close the session
+   * - `loop`: advance to the next item; if already on the last item, wrap to the first item
+   *
+   * Default: `manual`
+   */
+  advance?: PreviewMediaAdvance;
+  /**
+   * Optional cancellation signal for the preview request.
+   *
+   * Aborting rejects the returned promise with a cancellation error and requests the active
+   * native preview session to close immediately.
+   */
+  signal?: AbortSignal;
+  /**
+   * Whether to show the top `current/total` indicator.
+   *
+   * Default: `true` when previewing multiple items, otherwise `false`.
+   */
+  showIndexIndicator?: boolean;
+}
+
+export type PreviewMediaOptions =
+  | string
+  | PreviewMediaSingleOptions
+  | PreviewMediaSequenceOptions;
+
+export type PreviewMediaCloseReason = 'manual' | 'completed' | 'interrupted' | 'error';
+
+export interface PreviewMediaResult {
+  /**
+   * Why the preview session finished.
+   */
+  reason: PreviewMediaCloseReason;
+  /**
+   * Last active item index before close.
+   */
+  lastIndex: number;
 }
 
 export interface SaveMediaOptions {

package/src/navigator/index.ts

@@ -0,0 +1,10 @@
+/**
+ * LxApp navigator APIs
+ * Corresponds to: lingxia-logic/src/navigator.rs
+ */
+
+export interface NavigateToLxAppOptions {
+  appId: string;
+  path?: string;
+  envVersion?: 'develop' | 'trial' | 'release';
+}

package/src/storage/index.ts

@@ -1,6 +1,6 @@
 /**
- * Storage & File System APIs
- * Corresponds to: lingxia-logic/src/storage.rs, fs.rs, env.rs
+ * Storage APIs
+ * Corresponds to: lingxia-logic/src/storage.rs, env.rs
  */
 
 export interface LxEnv {
@@ -17,9 +17,3 @@ export interface Storage {
   has(key: string): boolean;
   size(): number;
 }
-
-export interface OpenDocumentOptions {
-  filePath: string;
-  fileType?: string;
-  showMenu?: boolean;
-}

package/src/system/index.ts

@@ -1,12 +1,13 @@
 /**
  * System APIs
- * Corresponds to: lingxia-logic/src/system.rs, navigator.rs, update.rs
+ * Corresponds to: lingxia-logic/src/system.rs
  */
 
 export interface AppBaseInfo {
   language: string;
   productName: string;
   version: string;
+  SDKVersion: string;
 }
 
 export interface SystemSettingInfo {
@@ -17,17 +18,5 @@ export interface SystemSettingInfo {
 
 export interface OpenURLOptions {
   url: string;
-  openIn?: 'external' | 'internal';
-}
-
-export interface NavigateToLxAppOptions {
-  appId: string;
-  path?: string;
-  envVersion?: 'develop' | 'trial' | 'release';
-}
-
-export interface UpdateManager {
-  applyUpdate(): void;
-  onUpdateReady(callback: () => void): void;
-  onUpdateFailed(callback: () => void): void;
+  target?: 'self' | 'external';
 }

package/src/update/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Update APIs
+ * Corresponds to: lingxia-logic/src/update.rs
+ */
+
+export interface UpdateManager {
+  applyUpdate(): void;
+  onUpdateReady(callback: (info: UpdateReadyInfo) => void): void;
+  onUpdateFailed(callback: (info: UpdateFailedInfo) => void): void;
+}
+
+export interface UpdateReadyInfo {
+  version?: string;
+  isForceUpdate?: boolean;
+  releaseType?: "release" | "preview" | "developer" | string;
+}
+
+export interface UpdateFailedInfo extends UpdateReadyInfo {
+  error?: string;
+}