@lingxia/types 0.16.0 → 0.18.0

package/src/index.ts

@@ -18,7 +18,9 @@ import type {
   AppLifecycleName,
   BinaryFileData,
   FsWriteOptions,
+  ManagedPath,
   NoLifecycleTypos,
+  NoReservedPageMembers,
   PageConfig,
   PageInstance,
   PageLifecycleName,
@@ -36,9 +38,9 @@ declare global {
      * signature above covers the string case.
      */
     write(
-      path: string,
+      path: ManagedPath,
       data: BinaryFileData,
-      options?: Omit<FsWriteOptions, 'encoding'>
+      options?: Omit<FsWriteOptions, 'encoding'> & { encoding?: never }
     ): Promise<void>;
   }
 
@@ -69,14 +71,15 @@ declare global {
   function getApp<T extends AppInstance = AppInstance>(): T | null;
   /**
    * `TData` comes from `data`, `TCustom` from everything else you declare, so
-   * `this.data` is typed, `this.myMethod()` resolves, and `setData` checks
-   * top-level keys against `data`.
+   * `this.data` is a readonly view of that type, `this.myMethod()` resolves,
+   * and `setData` checks top-level keys against `data`.
    */
-  function Page<TData extends Record<string, unknown>, TCustom>(
+  function Page<TData extends object, TCustom>(
     config: PageConfig<TData> &
       TCustom &
       NoLifecycleTypos<TCustom, PageLifecycleName> &
-      ThisType<PageInstance<TData> & TCustom>
+      NoReservedPageMembers<TCustom> &
+      ThisType<PageInstance<TData> & Omit<TCustom, keyof PageInstance>>
   ): void;
   function getCurrentPages<T extends PageInstance = PageInstance>(): T[];
 }

package/src/process.ts

@@ -31,6 +31,14 @@ export interface RongSpawnOptionsWithCmd extends RongSpawnOptions {
   cmd: string[];
 }
 
+/** Synchronous spawning cannot deliver async callbacks or react to an AbortSignal. */
+export type RongSpawnSyncOptions = Omit<RongSpawnOptions, 'onExit' | 'signal' | 'killSignal'> & {
+  onExit?: never;
+  signal?: never;
+  killSignal?: never;
+};
+export type RongSpawnSyncOptionsWithCmd = RongSpawnSyncOptions & { cmd: string[] };
+
 export interface RongSyncSubprocess {
   readonly exitCode: number | null;
   readonly success: boolean;
@@ -96,8 +104,10 @@ export interface RongShellCommand extends PromiseLike<RongShellResult> {
 export interface RongShellTag {
   (strings: TemplateStringsArray, ...values: unknown[]): RongShellCommand;
   (command: string): RongShellCommand;
-  cwd(path?: string): string | RongShellTag | undefined;
-  env(values?: RongEnvMap): RongEnvMap | RongShellTag | undefined;
+  cwd(): string | undefined;
+  cwd(path: string): RongShellTag;
+  env(): RongEnvMap | undefined;
+  env(values: RongEnvMap): RongShellTag;
   throws(value?: boolean): RongShellTag;
   nothrow(): RongShellTag;
   quiet(): RongShellTag;
@@ -122,8 +132,8 @@ declare global {
     readonly stderr: RongOutputHandle;
     spawn(cmd: string[], options?: RongSpawnOptions): RongSubprocess;
     spawn(options: RongSpawnOptionsWithCmd): RongSubprocess;
-    spawnSync(cmd: string[], options?: RongSpawnOptions): RongSyncSubprocess;
-    spawnSync(options: RongSpawnOptionsWithCmd): RongSyncSubprocess;
+    spawnSync(cmd: string[], options?: RongSpawnSyncOptions): RongSyncSubprocess;
+    spawnSync(options: RongSpawnSyncOptionsWithCmd): RongSyncSubprocess;
     readonly $: RongShellTag;
     readonly ShellError: {
       new (message: string): RongShellError;

package/src/testing/public-api.ts

@@ -25,18 +25,21 @@ import type {
   AppearanceApi,
   AppCacheApi,
   AutostartApi,
+  BannerApi,
   CompressVideoTask,
   ControlApi,
   ControlAppearanceApi,
   ControlDisplayLanguageApi,
   DisplayLanguageApi,
   DownloadTask,
+  ClipboardApi,
   FileSystemApi,
   HostAppApi,
   HostAppUpdateInfo,
   HostAppUpdateTask,
   LxFile,
   NavigationBarApi,
+  NotificationApi,
   PageMessagePort,
   PreviewMediaHandle,
   TabSurface,
@@ -57,11 +60,16 @@ import type {
 } from '../generated/logic.js';
 
 export const LX_API_NAMES = [
-  'app',
+  'host',
   'automation',
+  'alert',
+  'confirm',
+  'pickFile',
+  'pickFiles',
   'chooseDirectory',
   'chooseFile',
   'chooseMedia',
+  'clipboard',
   'compressImage',
   'compressVideo',
   'connectWifi',
@@ -127,22 +135,38 @@ export const LX_API_NAMES = [
 const HOST_APP_API = [
   'appearance',
   'autostart',
+  'banner',
   'cache',
   'checkUpdate',
+  'claimCustomUpdate',
   'control',
   'displayLanguage',
   'env',
   'exit',
   'getBaseInfo',
+  'notification',
   'screenshot',
   'setBadge',
 ] as const;
-// `autostart`, `control`, and `cache` are injected only where they apply, so a
-// runtime walk of `lx.app` must not require them.
+// `autostart`, `banner`, `control`, `cache`, and `notification` are injected
+// only where they apply, so a runtime walk of `lx.host` must not require them.
 const HOST_APP_RUNTIME_API = HOST_APP_API.filter(
-  (name) => name !== 'autostart' && name !== 'control' && name !== 'cache',
+  (name) =>
+    name !== 'autostart' &&
+    name !== 'banner' &&
+    name !== 'control' &&
+    name !== 'cache' &&
+    name !== 'notification',
 );
 const AUTOSTART_API = ['isEnabled', 'setEnabled'] as const;
+const BANNER_API = ['dismiss', 'show'] as const;
+const NOTIFICATION_API = [
+  'cancel',
+  'cancelAll',
+  'getPermission',
+  'requestPermission',
+  'show',
+] as const;
 const APP_CACHE_API = ['clear', 'size'] as const;
 const DISPLAY_LANGUAGE_API = ['get', 'watch'] as const;
 const CONTROL_API = ['appearance', 'displayLanguage'] as const;
@@ -166,10 +190,11 @@ const TERMINAL_FONTS_API = ['list'] as const;
 const TERMINAL_PREVIEW_API = ['clear', 'close', 'show'] as const;
 const WINDOWS_TERMINAL_API = ['install', 'setEnabled', 'status'] as const;
 const ENV_API = ['USER_CACHE_PATH', 'USER_DATA_PATH'] as const;
-const SURFACE_NAMESPACE_API = ['get', 'onContext', 'openDeclared', 'openPage', 'openUrl'] as const;
+const SURFACE_NAMESPACE_API = ['getByKey', 'watchContext', 'openDeclared', 'openPage', 'openUrl'] as const;
 const SHELL_API = ['openApp', 'openBuiltin', 'openDeclared', 'reconfigure', 'sidebarActions'] as const;
 const SHELL_SIDEBAR_ACTIONS_API = ['clear', 'remove', 'replace', 'update'] as const;
-const TRAY_API = ['hide', 'onClick', 'setBadge', 'setIcon', 'setMenu', 'setTitle', 'show'] as const;
+const TRAY_API = ['hide', 'onClick', 'setIcon', 'setMenu', 'setTitle', 'show'] as const;
+const CLIPBOARD_API = ['clear', 'read', 'readText', 'types', 'write', 'writeText'] as const;
 const FILE_SYSTEM_API = [
   'copy',
   'exists',
@@ -212,7 +237,7 @@ const AUTOMATION_API = [
   'shell',
   'terminal',
 ] as const;
-const SHELL_DRIVER_API = ['pins', 'setPin'] as const;
+const SHELL_DRIVER_API = ['pins', 'setPin', 'reorderPins'] as const;
 const TERMINAL_DRIVER_API = ['input', 'newTab', 'setMaximized', 'snapshot', 'split'] as const;
 const LXAPP_DRIVER_API = ['eval', 'info', 'nav', 'page', 'pages', 'surfaceLayout'] as const;
 const LXAPP_MANAGER_API = [
@@ -333,9 +358,10 @@ export const LX_RUNTIME_SURFACES = [
     members: LX_API_NAMES,
     optionalMembers: ['terminal'],
     properties: [
-      'app',
+      'clipboard',
       'env',
       'fs',
+      'host',
       'navigationBar',
       'shell',
       'surface',
@@ -345,57 +371,71 @@ export const LX_RUNTIME_SURFACES = [
     ],
   },
   {
-    name: 'lx.app',
+    name: 'lx.host',
     layer: 'logic',
-    expression: 'lx.app',
+    expression: 'lx.host',
     members: HOST_APP_RUNTIME_API,
     properties: ['appearance', 'displayLanguage', 'env'],
   },
   {
-    name: 'lx.app.autostart',
+    name: 'lx.host.autostart',
     layer: 'logic',
-    expression: 'lx.app.autostart',
+    expression: 'lx.host.autostart',
     members: AUTOSTART_API,
     optional: true,
   },
   {
-    name: 'lx.app.cache',
+    name: 'lx.host.banner',
     layer: 'logic',
-    expression: 'lx.app.cache',
+    expression: 'lx.host.banner',
+    members: BANNER_API,
+    optional: true,
+  },
+  {
+    name: 'lx.host.notification',
+    layer: 'logic',
+    expression: 'lx.host.notification',
+    members: NOTIFICATION_API,
+    optional: true,
+  },
+  {
+    name: 'lx.host.cache',
+    layer: 'logic',
+    expression: 'lx.host.cache',
     members: APP_CACHE_API,
     optional: true,
   },
   {
-    name: 'lx.app.displayLanguage',
+    name: 'lx.host.displayLanguage',
     layer: 'logic',
-    expression: 'lx.app.displayLanguage',
+    expression: 'lx.host.displayLanguage',
     members: DISPLAY_LANGUAGE_API,
   },
   {
-    name: 'lx.app.control',
+    name: 'lx.host.control',
     layer: 'logic',
-    expression: 'lx.app.control',
+    expression: 'lx.host.control',
     members: CONTROL_API,
     properties: CONTROL_API,
     optional: true,
   },
   {
-    name: 'lx.app.control.displayLanguage',
+    name: 'lx.host.control.displayLanguage',
     layer: 'logic',
-    expression: 'lx.app.control?.displayLanguage',
+    expression: 'lx.host.control?.displayLanguage',
     members: CONTROL_DISPLAY_LANGUAGE_API,
     optional: true,
   },
   {
-    name: 'lx.app.appearance',
+    name: 'lx.host.appearance',
     layer: 'logic',
-    expression: 'lx.app.appearance',
+    expression: 'lx.host.appearance',
     members: APPEARANCE_API,
   },
   {
-    name: 'lx.app.control.appearance',
+    name: 'lx.host.control.appearance',
     layer: 'logic',
-    expression: 'lx.app.control?.appearance',
+    expression: 'lx.host.control?.appearance',
     members: CONTROL_APPEARANCE_API,
     optional: true,
   },
@@ -476,6 +516,7 @@ export const LX_RUNTIME_SURFACES = [
   },
   { name: 'lx.tray', layer: 'logic', expression: 'lx.tray', members: TRAY_API },
   { name: 'lx.fs', layer: 'logic', expression: 'lx.fs', members: FILE_SYSTEM_API },
+  { name: 'lx.clipboard', layer: 'logic', expression: 'lx.clipboard', members: CLIPBOARD_API },
   { name: 'Storage', layer: 'logic', expression: 'lx.getStorage()', members: STORAGE_API },
   { name: 'UpdateManager', layer: 'logic', expression: 'lx.getUpdateManager()', members: UPDATE_MANAGER_API },
   {
@@ -549,22 +590,11 @@ export const LX_RUNTIME_CAPABILITY_NAMES = LX_RUNTIME_SURFACES.flatMap(({ name,
 /** Canonical identifiers used by runtime shape automation coverage. */
 export const LX_RUNTIME_SHAPE_NAMES = LX_RUNTIME_CAPABILITY_NAMES.map((name) => `shape:${name}`);
 
-const DOWNLOAD_TASK_API = [
-  'abort',
-  'cancel',
-  'catch',
-  'finally',
-  'next',
-  'pause',
-  'resume',
-  'return',
-  'then',
-  'wait',
-] as const;
-const UPLOAD_TASK_API = ['cancel', 'catch', 'finally', 'next', 'return', 'then', 'wait'] as const;
-const COMPRESS_VIDEO_TASK_API = ['cancel', 'catch', 'finally', 'next', 'return', 'then', 'wait'] as const;
-const HOST_UPDATE_INFO_API = ['apply', 'isForceUpdate', 'releaseNotes', 'size', 'version'] as const;
-const HOST_UPDATE_TASK_API = ['catch', 'finally', 'next', 'return', 'then', 'wait'] as const;
+const DOWNLOAD_TASK_API = ["result", "progress", "pause", "resume", "cancel"] as const;
+const UPLOAD_TASK_API = ["result", "progress", "cancel"] as const;
+const COMPRESS_VIDEO_TASK_API = ["result", "progress", "cancel"] as const;
+const HOST_UPDATE_INFO_API = ['apply', 'channel', 'releaseNotes', 'size', 'version'] as const;
+const HOST_UPDATE_TASK_API = ["result", "progress"] as const;
 const PREVIEW_MEDIA_API = ['completed', 'current', 'onChange', 'presented'] as const;
 const PAGE_SURFACE_API = [
   'alive',
@@ -616,7 +646,7 @@ export const LX_RETURNED_OBJECT_SURFACES = [
   {
     name: 'DownloadTask',
     members: DOWNLOAD_TASK_API,
-    properties: [],
+    properties: ['result', 'progress'],
     optionalProperties: [],
     fixture: 'external-service',
     factory: 'lx.downloadFile',
@@ -624,7 +654,7 @@ export const LX_RETURNED_OBJECT_SURFACES = [
   {
     name: 'UploadTask',
     members: UPLOAD_TASK_API,
-    properties: [],
+    properties: ['result', 'progress'],
     optionalProperties: [],
     fixture: 'external-service',
     factory: 'lx.uploadFile',
@@ -632,7 +662,7 @@ export const LX_RETURNED_OBJECT_SURFACES = [
   {
     name: 'CompressVideoTask',
     members: COMPRESS_VIDEO_TASK_API,
-    properties: [],
+    properties: ['result', 'progress'],
     optionalProperties: [],
     fixture: 'external-media',
     factory: 'lx.compressVideo',
@@ -640,15 +670,15 @@ export const LX_RETURNED_OBJECT_SURFACES = [
   {
     name: 'HostAppUpdateInfo',
     members: HOST_UPDATE_INFO_API,
-    properties: ['isForceUpdate', 'releaseNotes', 'size', 'version'],
+    properties: ['channel', 'releaseNotes', 'size', 'version'],
     optionalProperties: ['releaseNotes', 'size'],
     fixture: 'external-service',
-    factory: 'lx.app.checkUpdate().update',
+    factory: 'lx.host.checkUpdate().update',
   },
   {
     name: 'HostAppUpdateTask',
     members: HOST_UPDATE_TASK_API,
-    properties: [],
+    properties: ['result', 'progress'],
     optionalProperties: [],
     fixture: 'external-service',
     factory: 'HostAppUpdateInfo.apply',
@@ -731,6 +761,8 @@ export type LxApiManifestGate = [
   AssertTrue<Exact<PublishedLx, typeof LX_API_NAMES>>,
   AssertTrue<Exact<HostAppApi, typeof HOST_APP_API>>,
   AssertTrue<Exact<AutostartApi, typeof AUTOSTART_API>>,
+  AssertTrue<Exact<BannerApi, typeof BANNER_API>>,
+  AssertTrue<Exact<NotificationApi, typeof NOTIFICATION_API>>,
   AssertTrue<Exact<AppCacheApi, typeof APP_CACHE_API>>,
   AssertTrue<Exact<DisplayLanguageApi, typeof DISPLAY_LANGUAGE_API>>,
   AssertTrue<Exact<ControlApi, typeof CONTROL_API>>,
@@ -749,6 +781,7 @@ export type LxApiManifestGate = [
   AssertTrue<Exact<ShellApi['sidebarActions'], typeof SHELL_SIDEBAR_ACTIONS_API>>,
   AssertTrue<Exact<TrayApi, typeof TRAY_API>>,
   AssertTrue<Exact<FileSystemApi, typeof FILE_SYSTEM_API>>,
+  AssertTrue<Exact<ClipboardApi, typeof CLIPBOARD_API>>,
   AssertTrue<Exact<LxFile, typeof LX_FILE_API>>,
   AssertTrue<Exact<Storage, typeof STORAGE_API>>,
   AssertTrue<Exact<UpdateManager, typeof UPDATE_MANAGER_API>>,
@@ -782,6 +815,6 @@ export type LxApiManifestGate = [
   AssertTrue<Exact<PreviewMediaHandle, typeof PREVIEW_MEDIA_API>>,
   AssertTrue<Exact<SurfaceApi, typeof SURFACE_NAMESPACE_API>>,
   AssertTrue<Exact<PageSurface, typeof PAGE_SURFACE_API>>,
-  AssertTrue<Exact<TabSurface, typeof TAB_SURFACE_API>>,
+  AssertTrue<Exact<Extract<TabSurface, { scope: 'tab' }>, typeof TAB_SURFACE_API>>,
   AssertTrue<Exact<PageMessagePort, typeof PAGE_MESSAGE_PORT_API>>,
 ];