@lingxia/types 0.6.3 → 0.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/dist/app/index.d.ts +73 -0
  2. package/dist/app/index.d.ts.map +1 -1
  3. package/dist/ui/index.d.ts +5 -0
  4. package/dist/ui/index.d.ts.map +1 -1
  5. package/package.json +1 -1
  6. package/src/app/index.ts +76 -0
  7. package/src/ui/index.ts +5 -0
package/dist/app/index.d.ts CHANGED
@@ -60,7 +60,29 @@ export interface HostAppUpdateTask extends PromiseLike<HostAppUpdateResult>, Asy
60
60
  finally(onfinally?: (() => void) | null): Promise<HostAppUpdateResult>;
61
61
  wait(): Promise<HostAppUpdateResult>;
62
62
  }
63
+ /**
64
+ * Build-time environment version of the host app.
65
+ *
66
+ * Surfaced via {@link HostAppApi.envVersion}. Mirrors the
67
+ * `crates/lingxia-update::ReleaseType` enum and the `envVersion` field in the
68
+ * generated `app.json`. Pre-envVersion app artifacts are treated as `'release'`.
69
+ *
70
+ * Note: this is *separate* from `LxAppEnvVersion` in the navigator module,
71
+ * which encodes lxapp release channels (`'develop' | 'preview' | 'release'`)
72
+ * for cross-app navigation URLs and uses the truncated `develop` form.
73
+ */
74
+ export type HostAppEnvVersion = 'developer' | 'preview' | 'release';
63
75
  export interface HostAppApi {
76
+ /**
77
+ * The environment this build was produced for, mirroring `app.json::envVersion`.
78
+ * Always present; defaults to `'release'` for builds produced before the field
79
+ * existed in the artifact.
80
+ *
81
+ * Use this to branch on environment-specific behavior (e.g. verbose logging in
82
+ * developer builds, distinct theme tinting, distinct error-reporter tags).
83
+ * Synchronous; the value is fixed at app boot.
84
+ */
85
+ readonly envVersion: HostAppEnvVersion;
64
86
  getBaseInfo(): AppBaseInfo;
65
87
  /**
66
88
  * Check whether the host app has an update.
@@ -132,9 +154,33 @@ export interface SurfaceClosedEvent {
132
154
  kind: 'popup' | 'window';
133
155
  reason: SurfaceCloseReason;
134
156
  }
157
+ /**
158
+ * Detail payload for `onShow` / `onHide` events. `source` identifies which
159
+ * Surface object initiated the visibility change so observers can
160
+ * distinguish self-driven transitions from peer-driven ones (e.g. an opener
161
+ * UI that wants to update its own button state only when the page side
162
+ * toggled visibility).
163
+ */
164
+ export interface SurfaceVisibilityEvent {
165
+ id: string;
166
+ kind: 'popup' | 'window';
167
+ source: 'opener' | 'page';
168
+ }
135
169
  export interface Surface {
136
170
  readonly id: string;
137
171
  readonly kind: 'popup' | 'window';
172
+ /**
173
+ * Last-known visibility, kept in sync with the native side via show/hide
174
+ * events. False once the surface has been closed. Safe to bind into
175
+ * declarative UI; for event-driven updates subscribe via `onShow`/`onHide`.
176
+ */
177
+ readonly visible: boolean;
178
+ /**
179
+ * True until `close()` fires. After close the surface is detached and the
180
+ * page instance is being torn down; further `show()` / `hide()` calls will
181
+ * reject.
182
+ */
183
+ readonly alive: boolean;
138
184
  /**
139
185
  * Sends a message to the other side of a page surface.
140
186
  *
@@ -144,7 +190,34 @@ export interface Surface {
144
190
  postMessage(message: unknown): void;
145
191
  onMessage(handler: (message: unknown) => void): () => void;
146
192
  onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
193
+ /**
194
+ * Fires when the surface transitions to visible, regardless of whether
195
+ * `show()` was called on this side or on the peer. Returns an unsubscribe
196
+ * function. Only fires on real state changes — calling `show()` on an
197
+ * already-visible surface is a no-op for listeners.
198
+ */
199
+ onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
200
+ /**
201
+ * Fires when the surface transitions to hidden, regardless of which side
202
+ * triggered it. Returns an unsubscribe function. Only fires on real state
203
+ * changes.
204
+ */
205
+ onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
147
206
  close(): Promise<void>;
207
+ /**
208
+ * Toggle the surface to visible without tearing it down. The page instance
209
+ * and its state survive a hide / show round-trip — only close() actually
210
+ * destroys the surface and fires the onClose listener. Idempotent: calling
211
+ * on an already-visible surface resolves without firing `onShow`.
212
+ */
213
+ show(): Promise<void>;
214
+ /**
215
+ * Hide the surface without destroying it. The page instance stays mounted,
216
+ * so a subsequent show() restores the same scroll position, form input,
217
+ * and JS state. Hidden surfaces still receive postMessage but are not
218
+ * visible to the user. Idempotent.
219
+ */
220
+ hide(): Promise<void>;
148
221
  }
149
222
  export interface PageMessagePort {
150
223
  postMessage(message: unknown): void;
package/dist/app/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,iBAAiB,CAAC;CAC5B;AAED,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7D,MAAM,MAAM,wBAAwB,GAChC;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB,GACD;IACE,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AAEN,MAAM,MAAM,kBAAkB,GAC1B;IACE,KAAK,EAAE,aAAa,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACD;IACE,KAAK,EAAE,YAAY,GAAG,kBAAkB,CAAC;CAC1C,GACD;IACE,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,uBAAuB,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,WAAW,iBACf,SAAQ,WAAW,CAAC,mBAAmB,CAAC,EACtC,aAAa,CAAC,kBAAkB,CAAC;IACnC,IAAI,IAAI,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7C,6FAA6F;IAC7F,MAAM,IAAI,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC/C,KAAK,CAAC,OAAO,GAAG,KAAK,EACnB,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GACxE,OAAO,CAAC,mBAAmB,GAAG,OAAO,CAAC,CAAC;IAC1C,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvE,IAAI,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,IAAI,WAAW,CAAC;IAE3B;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,MAAM,EACF,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,MAAM,GACN,OAAO,GACP,aAAa,GACb,aAAa,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,mBAAmB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,UAAU,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzF,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,cAAc,GACd,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IAClC;;;;;MAKE;IACF,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3D,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5D;AAED,MAAM,WAAW,YAAY,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3F,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACtF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,4BAA4B;IAC5B,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IACvB,mDAAmD;IACnD,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,oCAAoC;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IAChE,8BAA8B;IAC9B,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,yCAAyC;IACzC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,+CAA+C;IAC/C,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAC;IAC9D,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CACrF"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"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"}
package/dist/ui/index.d.ts CHANGED
@@ -120,6 +120,11 @@ export interface WindowSurfaceSize {
120
120
  /** Window height, must be a positive number. */
121
121
  height?: number;
122
122
  }
123
+ /**
124
+ * Window-kind surfaces are macOS-only. Android, iOS, and Harmony reject
125
+ * `kind: 'window'` at open() and surface a `surface_open_failed` error;
126
+ * use `PopupSurfaceOptions` for cross-platform code.
127
+ */
123
128
  export type WindowSurfaceOptions = SurfaceTargetOptions & {
124
129
  kind: 'window';
125
130
  size?: WindowSurfaceSize;
package/dist/ui/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lingxia/types",
3
- "version": "0.6.3",
3
+ "version": "0.6.5",
4
4
  "description": "TypeScript type definitions for the LingXia JS API",
5
5
  "repository": {
6
6
  "type": "git",
package/src/app/index.ts CHANGED
@@ -78,7 +78,31 @@ export interface HostAppUpdateTask
78
78
  wait(): Promise<HostAppUpdateResult>;
79
79
  }
80
80
 
81
+ /**
82
+ * Build-time environment version of the host app.
83
+ *
84
+ * Surfaced via {@link HostAppApi.envVersion}. Mirrors the
85
+ * `crates/lingxia-update::ReleaseType` enum and the `envVersion` field in the
86
+ * generated `app.json`. Pre-envVersion app artifacts are treated as `'release'`.
87
+ *
88
+ * Note: this is *separate* from `LxAppEnvVersion` in the navigator module,
89
+ * which encodes lxapp release channels (`'develop' | 'preview' | 'release'`)
90
+ * for cross-app navigation URLs and uses the truncated `develop` form.
91
+ */
92
+ export type HostAppEnvVersion = 'developer' | 'preview' | 'release';
93
+
81
94
  export interface HostAppApi {
95
+ /**
96
+ * The environment this build was produced for, mirroring `app.json::envVersion`.
97
+ * Always present; defaults to `'release'` for builds produced before the field
98
+ * existed in the artifact.
99
+ *
100
+ * Use this to branch on environment-specific behavior (e.g. verbose logging in
101
+ * developer builds, distinct theme tinting, distinct error-reporter tags).
102
+ * Synchronous; the value is fixed at app boot.
103
+ */
104
+ readonly envVersion: HostAppEnvVersion;
105
+
82
106
  getBaseInfo(): AppBaseInfo;
83
107
 
84
108
  /**
@@ -174,9 +198,34 @@ export interface SurfaceClosedEvent {
174
198
  reason: SurfaceCloseReason;
175
199
  }
176
200
 
201
+ /**
202
+ * Detail payload for `onShow` / `onHide` events. `source` identifies which
203
+ * Surface object initiated the visibility change so observers can
204
+ * distinguish self-driven transitions from peer-driven ones (e.g. an opener
205
+ * UI that wants to update its own button state only when the page side
206
+ * toggled visibility).
207
+ */
208
+ export interface SurfaceVisibilityEvent {
209
+ id: string;
210
+ kind: 'popup' | 'window';
211
+ source: 'opener' | 'page';
212
+ }
213
+
177
214
  export interface Surface {
178
215
  readonly id: string;
179
216
  readonly kind: 'popup' | 'window';
217
+ /**
218
+ * Last-known visibility, kept in sync with the native side via show/hide
219
+ * events. False once the surface has been closed. Safe to bind into
220
+ * declarative UI; for event-driven updates subscribe via `onShow`/`onHide`.
221
+ */
222
+ readonly visible: boolean;
223
+ /**
224
+ * True until `close()` fires. After close the surface is detached and the
225
+ * page instance is being torn down; further `show()` / `hide()` calls will
226
+ * reject.
227
+ */
228
+ readonly alive: boolean;
180
229
  /**
181
230
  * Sends a message to the other side of a page surface.
182
231
  *
@@ -186,7 +235,34 @@ export interface Surface {
186
235
  postMessage(message: unknown): void;
187
236
  onMessage(handler: (message: unknown) => void): () => void;
188
237
  onClose(handler: (event: SurfaceClosedEvent) => void): () => void;
238
+ /**
239
+ * Fires when the surface transitions to visible, regardless of whether
240
+ * `show()` was called on this side or on the peer. Returns an unsubscribe
241
+ * function. Only fires on real state changes — calling `show()` on an
242
+ * already-visible surface is a no-op for listeners.
243
+ */
244
+ onShow(handler: (event: SurfaceVisibilityEvent) => void): () => void;
245
+ /**
246
+ * Fires when the surface transitions to hidden, regardless of which side
247
+ * triggered it. Returns an unsubscribe function. Only fires on real state
248
+ * changes.
249
+ */
250
+ onHide(handler: (event: SurfaceVisibilityEvent) => void): () => void;
189
251
  close(): Promise<void>;
252
+ /**
253
+ * Toggle the surface to visible without tearing it down. The page instance
254
+ * and its state survive a hide / show round-trip — only close() actually
255
+ * destroys the surface and fires the onClose listener. Idempotent: calling
256
+ * on an already-visible surface resolves without firing `onShow`.
257
+ */
258
+ show(): Promise<void>;
259
+ /**
260
+ * Hide the surface without destroying it. The page instance stays mounted,
261
+ * so a subsequent show() restores the same scroll position, form input,
262
+ * and JS state. Hidden surfaces still receive postMessage but are not
263
+ * visible to the user. Idempotent.
264
+ */
265
+ hide(): Promise<void>;
190
266
  }
191
267
 
192
268
  export interface PageMessagePort {
package/src/ui/index.ts CHANGED
@@ -152,6 +152,11 @@ export interface WindowSurfaceSize {
152
152
  height?: number;
153
153
  }
154
154
 
155
+ /**
156
+ * Window-kind surfaces are macOS-only. Android, iOS, and Harmony reject
157
+ * `kind: 'window'` at open() and surface a `surface_open_failed` error;
158
+ * use `PopupSurfaceOptions` for cross-platform code.
159
+ */
155
160
  export type WindowSurfaceOptions = SurfaceTargetOptions & {
156
161
  kind: 'window';
157
162
  size?: WindowSurfaceSize;