@egret/engine 7.0.1-rc.3 → 7.0.2

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 (304) hide show
  1. package/dist/Engine.js +7 -2
  2. package/dist/animation/sequenceResetTypes.d.ts +6 -0
  3. package/dist/animation/types.d.ts +6 -0
  4. package/dist/assetBundle.d.ts +2 -0
  5. package/dist/assetGroupTypes.d.ts +2 -0
  6. package/dist/audioCues.d.ts +4 -0
  7. package/dist/audioTypes.d.ts +13 -0
  8. package/dist/bitmapButtonTypes.d.ts +2 -0
  9. package/dist/bitmapFontTypes.d.ts +3 -0
  10. package/dist/bitmapResourceSlot.d.ts +1 -0
  11. package/dist/camera2d.js +10 -2
  12. package/dist/cameraTypes.d.ts +12 -0
  13. package/dist/contentTypes.d.ts +2 -0
  14. package/dist/createEngineForProfile.js +8 -5
  15. package/dist/fontContentTypes.d.ts +5 -0
  16. package/dist/gameClockTypes.d.ts +6 -0
  17. package/dist/gameRun.d.ts +3 -0
  18. package/dist/gamepadTypes.d.ts +8 -0
  19. package/dist/hoverInputTypes.d.ts +10 -0
  20. package/dist/index.d.ts +5 -2
  21. package/dist/index.js +2 -1
  22. package/dist/inputActions.d.ts +5 -0
  23. package/dist/internal/uiFactoryState.d.ts +4 -0
  24. package/dist/internal/uiFactoryState.js +18 -2
  25. package/dist/keyboardInput.d.ts +1 -0
  26. package/dist/keyboardInput.js +1 -0
  27. package/dist/keyboardInputTypes.d.ts +12 -0
  28. package/dist/kit.d.ts +3 -1
  29. package/dist/kit.js +2 -1
  30. package/dist/manifestResourceState.d.ts +1 -0
  31. package/dist/manifestResourceState.js +1 -0
  32. package/dist/manifestResourceTypes.d.ts +1 -0
  33. package/dist/motion.d.ts +2 -0
  34. package/dist/mouseInputTypes.d.ts +4 -0
  35. package/dist/particleEmitter.js +8 -0
  36. package/dist/particleTypes.d.ts +8 -0
  37. package/dist/physics2d.d.ts +2 -2
  38. package/dist/physics2d.js +1 -1
  39. package/dist/physics2dTypes.d.ts +55 -1
  40. package/dist/physics2dWorld.js +209 -9
  41. package/dist/pointerInput.d.ts +1 -0
  42. package/dist/pointerInput.js +1 -0
  43. package/dist/pointerInputTypes.d.ts +3 -0
  44. package/dist/random.d.ts +1 -0
  45. package/dist/rendering/packSharedDraws2D.js +53 -5
  46. package/dist/rendering/prepareSharedDraws2D.d.ts +2 -0
  47. package/dist/rendering/prepareSharedDraws2D.js +17 -6
  48. package/dist/rendering/sharedColor2D.d.ts +35 -1
  49. package/dist/rendering/sharedColor2D.js +131 -8
  50. package/dist/rendering/sharedEffects2D.js +16 -8
  51. package/dist/rendering/world3d/Animation3D.d.ts +9 -0
  52. package/dist/rendering/world3d/Animation3D.js +4 -0
  53. package/dist/rendering/world3d/AnimationTexture3D.d.ts +6 -0
  54. package/dist/rendering/world3d/AnimationTexture3D.js +2 -0
  55. package/dist/rendering/world3d/Batch3D.d.ts +4 -0
  56. package/dist/rendering/world3d/Batch3D.js +3 -0
  57. package/dist/rendering/world3d/Camera3D.d.ts +5 -0
  58. package/dist/rendering/world3d/Camera3D.js +3 -0
  59. package/dist/rendering/world3d/Character3D.d.ts +4 -0
  60. package/dist/rendering/world3d/Character3D.js +2 -0
  61. package/dist/rendering/world3d/Cloth3D.d.ts +18 -3
  62. package/dist/rendering/world3d/Cloth3D.js +6 -1
  63. package/dist/rendering/world3d/Compression3D.d.ts +1 -0
  64. package/dist/rendering/world3d/Compression3D.js +1 -0
  65. package/dist/rendering/world3d/Curves3D.d.ts +8 -0
  66. package/dist/rendering/world3d/Curves3D.js +5 -0
  67. package/dist/rendering/world3d/Decal3D.d.ts +2 -0
  68. package/dist/rendering/world3d/Decal3D.js +1 -0
  69. package/dist/rendering/world3d/Export3D.d.ts +13 -0
  70. package/dist/rendering/world3d/Export3D.js +263 -0
  71. package/dist/rendering/world3d/Geometry3D.d.ts +11 -1
  72. package/dist/rendering/world3d/Geometry3D.js +10 -1
  73. package/dist/rendering/world3d/GeometryBuilder3D.d.ts +2 -0
  74. package/dist/rendering/world3d/Gizmo3D.d.ts +5 -0
  75. package/dist/rendering/world3d/Gizmo3D.js +2 -0
  76. package/dist/rendering/world3d/Gltf3D.d.ts +6 -0
  77. package/dist/rendering/world3d/Gltf3D.js +25 -5
  78. package/dist/rendering/world3d/GpuParticles3D.d.ts +2 -0
  79. package/dist/rendering/world3d/GpuParticles3D.js +1 -0
  80. package/dist/rendering/world3d/Hdr3D.d.ts +2 -0
  81. package/dist/rendering/world3d/Hdr3D.js +1 -0
  82. package/dist/rendering/world3d/Jelly3D.d.ts +2 -0
  83. package/dist/rendering/world3d/Jelly3D.js +1 -0
  84. package/dist/rendering/world3d/Ktx23D.d.ts +3 -0
  85. package/dist/rendering/world3d/Light3D.d.ts +9 -0
  86. package/dist/rendering/world3d/Light3D.js +4 -0
  87. package/dist/rendering/world3d/Material3D.d.ts +10 -0
  88. package/dist/rendering/world3d/Material3D.js +2 -0
  89. package/dist/rendering/world3d/Mesh3D.d.ts +4 -0
  90. package/dist/rendering/world3d/Mesh3D.js +16 -2
  91. package/dist/rendering/world3d/Meshopt3D.d.ts +3 -0
  92. package/dist/rendering/world3d/Meshopt3D.js +1 -0
  93. package/dist/rendering/world3d/Navigation3D.d.ts +41 -1
  94. package/dist/rendering/world3d/Navigation3D.js +74 -2
  95. package/dist/rendering/world3d/Object3D.d.ts +11 -0
  96. package/dist/rendering/world3d/Object3D.js +10 -0
  97. package/dist/rendering/world3d/Particles3D.d.ts +5 -0
  98. package/dist/rendering/world3d/Particles3D.js +3 -0
  99. package/dist/rendering/world3d/Physics3D.d.ts +14 -0
  100. package/dist/rendering/world3d/Physics3D.js +5 -0
  101. package/dist/rendering/world3d/PhysicsHull3D.d.ts +2 -0
  102. package/dist/rendering/world3d/PhysicsHull3D.js +2 -0
  103. package/dist/rendering/world3d/PhysicsMesh3D.d.ts +2 -0
  104. package/dist/rendering/world3d/PhysicsMesh3D.js +2 -0
  105. package/dist/rendering/world3d/PhysicsRemote3D.d.ts +5 -0
  106. package/dist/rendering/world3d/PhysicsRemote3D.js +2 -0
  107. package/dist/rendering/world3d/Ragdoll3D.d.ts +5 -0
  108. package/dist/rendering/world3d/Ragdoll3D.js +2 -0
  109. package/dist/rendering/world3d/Raycast3D.d.ts +3 -0
  110. package/dist/rendering/world3d/Raycast3D.js +1 -0
  111. package/dist/rendering/world3d/RenderList3D.d.ts +3 -0
  112. package/dist/rendering/world3d/RenderList3D.js +12 -0
  113. package/dist/rendering/world3d/Retarget3D.d.ts +1 -0
  114. package/dist/rendering/world3d/Rig3D.d.ts +57 -0
  115. package/dist/rendering/world3d/Rig3D.js +219 -0
  116. package/dist/rendering/world3d/Sdf3D.d.ts +181 -0
  117. package/dist/rendering/world3d/Sdf3D.js +1136 -0
  118. package/dist/rendering/world3d/SdfLod3D.d.ts +17 -0
  119. package/dist/rendering/world3d/SdfLod3D.js +56 -0
  120. package/dist/rendering/world3d/Serialize3D.d.ts +17 -0
  121. package/dist/rendering/world3d/Serialize3D.js +22 -0
  122. package/dist/rendering/world3d/Simplify3D.d.ts +29 -0
  123. package/dist/rendering/world3d/Simplify3D.js +426 -0
  124. package/dist/rendering/world3d/StateMachine3D.d.ts +9 -0
  125. package/dist/rendering/world3d/StateMachine3D.js +3 -0
  126. package/dist/rendering/world3d/SurfaceMaterial3D.d.ts +26 -0
  127. package/dist/rendering/world3d/SurfaceMaterial3D.js +138 -0
  128. package/dist/rendering/world3d/Terrain3D.d.ts +21 -0
  129. package/dist/rendering/world3d/Terrain3D.js +25 -1
  130. package/dist/rendering/world3d/Text3D.d.ts +5 -0
  131. package/dist/rendering/world3d/Text3D.js +2 -0
  132. package/dist/rendering/world3d/Texture3D.d.ts +16 -1
  133. package/dist/rendering/world3d/Texture3D.js +19 -1
  134. package/dist/rendering/world3d/Trail3D.d.ts +3 -0
  135. package/dist/rendering/world3d/Trail3D.js +2 -0
  136. package/dist/rendering/world3d/Vehicle3D.d.ts +5 -0
  137. package/dist/rendering/world3d/Vehicle3D.js +2 -0
  138. package/dist/rendering/world3d/VolumetricFog3D.d.ts +2 -0
  139. package/dist/rendering/world3d/VolumetricFog3D.js +1 -0
  140. package/dist/rendering/world3d/Water3D.d.ts +2 -0
  141. package/dist/rendering/world3d/Water3D.js +1 -0
  142. package/dist/rendering/world3d/core3D.d.ts +2 -0
  143. package/dist/rendering/world3d/debug3D.d.ts +5 -0
  144. package/dist/rendering/world3d/debug3D.js +5 -0
  145. package/dist/rendering/world3d/geometries3D.d.ts +12 -0
  146. package/dist/rendering/world3d/geometries3D.js +5 -0
  147. package/dist/rendering/world3d/helpers3D.d.ts +2 -0
  148. package/dist/rendering/world3d/helpers3D.js +1 -0
  149. package/dist/rendering/world3d/index.d.ts +12 -0
  150. package/dist/rendering/world3d/index.js +6 -0
  151. package/dist/rendering/world3d/math3D.d.ts +36 -0
  152. package/dist/rendering/world3d/math3D.js +35 -0
  153. package/dist/rendering/world3d/primitives3D.d.ts +7 -0
  154. package/dist/rendering/world3d/primitives3D.js +1 -0
  155. package/dist/saveStore.d.ts +18 -3
  156. package/dist/saveStore.js +23 -4
  157. package/dist/semanticList.d.ts +4 -0
  158. package/dist/semanticList.js +1 -0
  159. package/dist/semanticTree.js +11 -4
  160. package/dist/semanticTypes.d.ts +8 -0
  161. package/dist/sequencePlaybackTypes.d.ts +3 -0
  162. package/dist/text.d.ts +1 -0
  163. package/dist/textTable.d.ts +41 -0
  164. package/dist/textTable.js +114 -0
  165. package/dist/tilemapTypes.d.ts +13 -0
  166. package/dist/timer.d.ts +34 -0
  167. package/dist/timer.js +119 -0
  168. package/dist/tweenTypes.d.ts +4 -0
  169. package/dist/ui/controlKeys.d.ts +4 -0
  170. package/dist/ui/controlKeys.js +1 -0
  171. package/dist/ui/controls.d.ts +6 -0
  172. package/dist/ui/controls.js +2 -0
  173. package/dist/ui/layerTypes.d.ts +7 -0
  174. package/dist/ui/rangeControl.d.ts +3 -0
  175. package/dist/ui/rangeControl.js +1 -0
  176. package/dist/ui/scrollControl.d.ts +12 -0
  177. package/dist/ui/scrollControl.js +5 -1
  178. package/dist/ui/stateControls.d.ts +8 -0
  179. package/dist/ui/stateControls.js +3 -0
  180. package/dist/ui/textEditor.d.ts +1 -0
  181. package/dist/ui/textEditor.js +1 -0
  182. package/dist/ui/textEditorTypes.d.ts +7 -0
  183. package/dist/ui/textFieldControl.d.ts +4 -0
  184. package/dist/ui/textFieldControl.js +1 -0
  185. package/dist/ui/theme.d.ts +5 -0
  186. package/dist/ui/theme.js +1 -0
  187. package/dist/ui/types.d.ts +20 -0
  188. package/dist/ui/uiRoot.js +38 -9
  189. package/dist/ui/uiRootModel.d.ts +3 -1
  190. package/dist/ui/uiRootModel.js +8 -2
  191. package/dist/videoTypes.d.ts +3 -0
  192. package/dist/web/BrowserAssetBundle.d.ts +2 -0
  193. package/dist/web/BrowserAudio.d.ts +34 -1
  194. package/dist/web/BrowserAudio.js +69 -39
  195. package/dist/web/BrowserFrameLoop.d.ts +4 -0
  196. package/dist/web/BrowserGame.d.ts +64 -2
  197. package/dist/web/BrowserGame.js +129 -8
  198. package/dist/web/BrowserGamepadInput.d.ts +3 -0
  199. package/dist/web/BrowserHoverInput.d.ts +1 -0
  200. package/dist/web/BrowserImageTextures.d.ts +6 -0
  201. package/dist/web/BrowserInputActions.d.ts +10 -0
  202. package/dist/web/BrowserInputActions.js +4 -1
  203. package/dist/web/BrowserPlay.d.ts +130 -2
  204. package/dist/web/BrowserPlay.js +366 -19
  205. package/dist/web/BrowserPreferences.d.ts +10 -0
  206. package/dist/web/BrowserPreferences.js +39 -0
  207. package/dist/web/BrowserSemantics.d.ts +2 -0
  208. package/dist/web/BrowserStatsPanel.d.ts +10 -0
  209. package/dist/web/BrowserStatsPanel.js +9 -3
  210. package/dist/web/BrowserStorage.d.ts +2 -0
  211. package/dist/web/BrowserTextEditor.d.ts +3 -0
  212. package/dist/web/BrowserTextInput.d.ts +6 -0
  213. package/dist/web/BrowserTextureProvider.d.ts +6 -0
  214. package/dist/web/BrowserVideo.d.ts +13 -1
  215. package/dist/web/BrowserVideo.js +28 -2
  216. package/dist/web/CanvasKitFontSetProvider.d.ts +3 -0
  217. package/dist/web/CanvasKitParagraphProvider.d.ts +4 -0
  218. package/dist/web/CanvasKitParagraphProvider.js +1 -0
  219. package/dist/web/ManifestByteSource.d.ts +4 -0
  220. package/dist/web/ManifestByteSource.js +1 -0
  221. package/dist/web/ManifestFontContentLoader.d.ts +1 -0
  222. package/dist/web/WebGL2Host.js +64 -25
  223. package/dist/web/WebGPUHost.d.ts +13 -0
  224. package/dist/web/WebGPUHost.js +117 -36
  225. package/dist/web/audio.d.ts +2 -2
  226. package/dist/web/audio.js +1 -1
  227. package/dist/web/editorFonts.d.ts +4 -0
  228. package/dist/web/game.d.ts +1 -1
  229. package/dist/web/imageProjections2D.d.ts +2 -0
  230. package/dist/web/kit.d.ts +1 -0
  231. package/dist/web/kit.js +1 -0
  232. package/dist/web/play.d.ts +6 -1
  233. package/dist/web/play.js +4 -1
  234. package/dist/web/playMusic.d.ts +33 -0
  235. package/dist/web/playMusic.js +194 -0
  236. package/dist/web/playTouch.d.ts +45 -0
  237. package/dist/web/playTouch.js +141 -0
  238. package/dist/web/playWidgets.d.ts +71 -0
  239. package/dist/web/playWidgets.js +431 -0
  240. package/dist/web/prepareSharedSubmission2D.js +9 -3
  241. package/dist/web/resources.d.ts +2 -0
  242. package/dist/web/sharedEffectShaders.d.ts +6 -2
  243. package/dist/web/sharedEffectShaders.js +23 -7
  244. package/dist/web/sharedSubmissionStorage2D.js +1 -1
  245. package/dist/web/sharedWebGL2Options.d.ts +3 -0
  246. package/dist/web/sharedWebGL2Options.js +8 -2
  247. package/dist/web/sharedWebGL2Shaders.d.ts +15 -2
  248. package/dist/web/sharedWebGL2Shaders.js +108 -14
  249. package/dist/web/sharedWebGPUOptions.d.ts +5 -1
  250. package/dist/web/sharedWebGPUOptions.js +6 -2
  251. package/dist/web/video.d.ts +1 -1
  252. package/dist/web/webgl2Native.d.ts +3 -1
  253. package/dist/web/webgl2Native.js +9 -5
  254. package/dist/web/webgl2Types.d.ts +18 -0
  255. package/dist/web/webgpuImageResidency.d.ts +5 -2
  256. package/dist/web/webgpuImageResidency.js +7 -3
  257. package/dist/web/webgpuRetentionPool.d.ts +2 -2
  258. package/dist/web/webgpuRetentionPool.js +2 -1
  259. package/dist/web/webgpuSharedPass.d.ts +1 -1
  260. package/dist/web/webgpuSharedPass.js +87 -5
  261. package/dist/web/webgpuSharedResolvePass.d.ts +1 -1
  262. package/dist/web/webgpuSharedResolvePass.js +9 -4
  263. package/dist/web/world3d/Audio3D.d.ts +18 -1
  264. package/dist/web/world3d/Audio3D.js +62 -3
  265. package/dist/web/world3d/BrowserPlay3D.d.ts +115 -2
  266. package/dist/web/world3d/BrowserPlay3D.js +448 -43
  267. package/dist/web/world3d/FlyControls3D.d.ts +4 -0
  268. package/dist/web/world3d/FlyControls3D.js +2 -0
  269. package/dist/web/world3d/FollowControls3D.d.ts +3 -0
  270. package/dist/web/world3d/FollowControls3D.js +2 -0
  271. package/dist/web/world3d/OrbitControls3D.d.ts +3 -0
  272. package/dist/web/world3d/OrbitControls3D.js +2 -0
  273. package/dist/web/world3d/TransformControls3D.d.ts +5 -2
  274. package/dist/web/world3d/TransformControls3D.js +7 -4
  275. package/dist/web/world3d/WebGL2Renderer3D.d.ts +3 -0
  276. package/dist/web/world3d/WebGL2Renderer3D.js +2 -0
  277. package/dist/web/world3d/WebGPURenderer3D.d.ts +2 -0
  278. package/dist/web/world3d/WebGPURenderer3D.js +1 -0
  279. package/dist/web/world3d/World3DView.d.ts +3 -0
  280. package/dist/web/world3d/World3DView.js +2 -0
  281. package/dist/web/world3d/app3D.d.ts +7 -0
  282. package/dist/web/world3d/app3D.js +1 -0
  283. package/dist/web/world3d/assets3D.d.ts +1 -0
  284. package/dist/web/world3d/atmosphere3D.d.ts +9 -0
  285. package/dist/web/world3d/atmosphere3D.js +19 -4
  286. package/dist/web/world3d/canvasFont3D.d.ts +21 -0
  287. package/dist/web/world3d/canvasFont3D.js +165 -0
  288. package/dist/web/world3d/frame3D.d.ts +2 -0
  289. package/dist/web/world3d/host3D.d.ts +1 -0
  290. package/dist/web/world3d/index.d.ts +4 -2
  291. package/dist/web/world3d/index.js +2 -1
  292. package/dist/web/world3d/loaders3D.d.ts +1 -0
  293. package/dist/web/world3d/markers3D.d.ts +4 -0
  294. package/dist/web/world3d/overlay3D.d.ts +19 -0
  295. package/dist/web/world3d/overlay3D.js +21 -4
  296. package/dist/web/world3d/post3D.d.ts +4 -0
  297. package/dist/web/world3d/post3D.js +3 -0
  298. package/dist/web/world3d/probe3D.d.ts +1 -0
  299. package/dist/web/world3d/stats3D.d.ts +3 -0
  300. package/dist/web/world3d/stats3D.js +1 -0
  301. package/dist/web/world3d/webGL2FrameMetrics3D.d.ts +5 -0
  302. package/dist/web/world3d/webgpu.d.ts +2 -0
  303. package/dist/web/world3d/webgpu.js +1 -0
  304. package/package.json +3 -3
@@ -31,6 +31,7 @@ export interface ActionKeysOptions extends ControlKeysTarget {
31
31
  };
32
32
  readonly onPressChange?: (pressed: boolean) => void;
33
33
  }
34
+ /** Keys for a toggle: which kind of toggle, the control, and what is called when its press changes. */
34
35
  export interface ToggleKeysOptions extends ControlKeysTarget {
35
36
  readonly kind: 'toggle';
36
37
  readonly control: {
@@ -98,12 +99,15 @@ export interface MovementKeysOptions extends ControlKeysTarget {
98
99
  readonly keys?: 'arrows' | 'wasd' | 'both';
99
100
  readonly onPressChange?: (pressed: boolean) => void;
100
101
  }
102
+ /** Keys for one control: an action, a toggle, a text field or a selection group. */
101
103
  export type ControlKeysOptions = ActionKeysOptions | ToggleKeysOptions | TextFieldKeysOptions | SelectionKeysOptions | ScrollKeysOptions | RangeKeysOptions | MovementKeysOptions;
104
+ /** Keys bound to a control: which are pressed now; dispose of it to unbind them. */
102
105
  export interface ControlKeys {
103
106
  /** Whether a key of this binding is held: an activation that waits for its release, or a direction. */
104
107
  readonly pressed: boolean;
105
108
  dispose(): void;
106
109
  }
110
+ /** Binds the keyboard to a control: Space and Enter press an action or a toggle, arrows move a selection. */
107
111
  export declare function createControlKeys(options: ControlKeysOptions): ControlKeys;
108
112
  export {};
109
113
  //# sourceMappingURL=controlKeys.d.ts.map
@@ -17,6 +17,7 @@ const METHODS = {
17
17
  range: ['stepBy', 'toMin', 'toMax'],
18
18
  movement: ['setDirection']
19
19
  };
20
+ /** Binds the keyboard to a control: Space and Enter press an action or a toggle, arrows move a selection. */
20
21
  export function createControlKeys(options) {
21
22
  if (options === null || typeof options !== 'object')
22
23
  throw new EgretError('UI_CONTROL_OPTIONS');
@@ -12,6 +12,7 @@ export interface MovementValue {
12
12
  readonly x: number;
13
13
  readonly y: number;
14
14
  }
15
+ /** A movement control to make: its input and target, its radius and dead zone, and what it calls. */
15
16
  export interface MovementControlOptions {
16
17
  readonly input: PointerInput;
17
18
  /** The surface that owns this control; contacts routed elsewhere are not claimed. */
@@ -22,6 +23,7 @@ export interface MovementControlOptions {
22
23
  readonly deadZone?: number;
23
24
  readonly onMovement?: (value: MovementValue) => void;
24
25
  }
26
+ /** A virtual stick: where it points now, whether it is held, and calls that set or disable it. */
25
27
  export interface MovementControl {
26
28
  readonly value: MovementValue;
27
29
  readonly active: boolean;
@@ -31,12 +33,14 @@ export interface MovementControl {
31
33
  setEnabled(enabled: boolean): void;
32
34
  dispose(): void;
33
35
  }
36
+ /** An action control to make: its input and target, and what is called when it is activated or pressed. */
34
37
  export interface ActionControlOptions {
35
38
  readonly input: PointerInput;
36
39
  readonly target: DisplayObject;
37
40
  readonly onActivate?: () => void;
38
41
  readonly onPressChange?: (pressed: boolean) => void;
39
42
  }
43
+ /** A button control: whether it is pressed, how often it was activated, and calls that press or disable it. */
40
44
  export interface ActionControl {
41
45
  readonly pressed: boolean;
42
46
  readonly enabled: boolean;
@@ -47,6 +51,8 @@ export interface ActionControl {
47
51
  setEnabled(enabled: boolean): void;
48
52
  dispose(): void;
49
53
  }
54
+ /** A virtual stick on a target: dragging inside its radius gives a direction. */
50
55
  export declare function createMovementControl(options: MovementControlOptions): MovementControl;
56
+ /** A button on a target: a press and release inside it activates it. */
51
57
  export declare function createActionControl(options: ActionControlOptions): ActionControl;
52
58
  //# sourceMappingURL=controls.d.ts.map
@@ -24,6 +24,7 @@ function direction(x, y) {
24
24
  const scale = length > 1 ? 1 / length : 1;
25
25
  return Object.freeze({ x: x * scale, y: y * scale });
26
26
  }
27
+ /** A virtual stick on a target: dragging inside its radius gives a direction. */
27
28
  export function createMovementControl(options) {
28
29
  checkOptions(options);
29
30
  const { input, target, radius, onMovement } = options;
@@ -154,6 +155,7 @@ export function createMovementControl(options) {
154
155
  }
155
156
  });
156
157
  }
158
+ /** A button on a target: a press and release inside it activates it. */
157
159
  export function createActionControl(options) {
158
160
  checkOptions(options);
159
161
  const { input, target, onActivate, onPressChange } = options;
@@ -4,6 +4,7 @@ import type { Engine } from '../Engine.js';
4
4
  import type { PointerInput } from '../pointerInputTypes.js';
5
5
  import type { KeyboardInput } from '../keyboardInputTypes.js';
6
6
  import type { UiRoot } from './types.js';
7
+ /** What a layer is anchored to: a leaf of the tree, or a row of a list. */
7
8
  export type UiLayerTarget = Readonly<{
8
9
  kind: 'leaf';
9
10
  id: string;
@@ -12,6 +13,7 @@ export type UiLayerTarget = Readonly<{
12
13
  listId: string;
13
14
  key: string;
14
15
  }>;
16
+ /** Where a layer is placed beside its target: on which side, how aligned, and how far from it. */
15
17
  export interface UiLayerAnchor {
16
18
  readonly root: UiRoot;
17
19
  readonly target: UiLayerTarget;
@@ -20,6 +22,7 @@ export interface UiLayerAnchor {
20
22
  readonly align?: 'start' | 'center' | 'end';
21
23
  readonly gap?: number;
22
24
  }
25
+ /** A layer manager to make: its engine, scope and input, its viewport and limits. */
23
26
  export interface UiLayerManagerOptions {
24
27
  readonly engine: Engine;
25
28
  readonly scope: EngineScope;
@@ -31,6 +34,7 @@ export interface UiLayerManagerOptions {
31
34
  /** Request the caller's existing UI publication/capture path, never a second loop. */
32
35
  readonly onInvalidate?: () => void;
33
36
  }
37
+ /** A layer to open: its id and root, its kind and anchor, where focus goes, how it closes, and its backdrop. */
34
38
  export interface UiLayerOptions {
35
39
  readonly id: string;
36
40
  readonly root: UiRoot;
@@ -45,15 +49,18 @@ export interface UiLayerOptions {
45
49
  readonly backdropColor?: number;
46
50
  readonly backdropAlpha?: number;
47
51
  }
52
+ /** An open layer; dispose of it to close it. */
48
53
  export interface UiLayerRegistration {
49
54
  readonly id: string;
50
55
  dispose(): void;
51
56
  }
57
+ /** What committing the layers did, and any errors after the commit. */
52
58
  export interface UiLayerCommitResult {
53
59
  readonly kind: 'committed' | 'unchanged' | 'pending' | 'closed';
54
60
  readonly revision: number;
55
61
  readonly postCommitErrors: readonly unknown[];
56
62
  }
63
+ /** The layers as they are now: committed and desired stacks, each layer, and counters. */
57
64
  export interface UiLayerSnapshot {
58
65
  readonly state: 'open' | 'closed';
59
66
  readonly committedRevision: number;
@@ -8,6 +8,7 @@ import type { PointerInput } from '../pointerInputTypes.js';
8
8
  * what the control reports.
9
9
  */
10
10
  export type RangeAxis = 'x' | 'y';
11
+ /** A range control to make: its input and target, its axis and track, its range and step, and what it calls. */
11
12
  export interface RangeControlOptions {
12
13
  readonly input: PointerInput;
13
14
  /** The track. A press on it or on something inside it moves the value there. */
@@ -28,6 +29,7 @@ export interface RangeControlOptions {
28
29
  readonly onChange?: (value: number, previous: number) => void;
29
30
  readonly onDragChange?: (dragging: boolean) => void;
30
31
  }
32
+ /** A slider: its value and range, whether it is dragged, and calls that set or step it. */
31
33
  export interface RangeControl {
32
34
  readonly value: number;
33
35
  readonly min: number;
@@ -46,5 +48,6 @@ export interface RangeControl {
46
48
  setEnabled(enabled: boolean): void;
47
49
  dispose(): void;
48
50
  }
51
+ /** A slider on a target: dragging along its track or pressing keys sets a value between its least and greatest. */
49
52
  export declare function createRangeControl(options: RangeControlOptions): RangeControl;
50
53
  //# sourceMappingURL=rangeControl.d.ts.map
@@ -1,6 +1,7 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
  import { EgretError } from '@egret/runtime';
3
3
  const finite = (value) => typeof value === 'number' && Number.isFinite(value);
4
+ /** A slider on a target: dragging along its track or pressing keys sets a value between its least and greatest. */
4
5
  export function createRangeControl(options) {
5
6
  if (options === null || typeof options !== 'object')
6
7
  throw new EgretError('UI_CONTROL_OPTIONS');
@@ -10,13 +10,21 @@ import type { PointerInput } from '../pointerInputTypes.js';
10
10
  * and is not recognized here.
11
11
  */
12
12
  export type ScrollAxis = 'x' | 'y';
13
+ /** How the wheel scrolls: the hover input, the target, and how far one line is. */
13
14
  export interface ScrollWheelOptions {
14
15
  readonly hover: HoverInput;
15
16
  /** The viewport. A wheel over it or over a descendant scrolls. */
16
17
  readonly target: DisplayObject;
17
18
  /** Logical units of one wheel line. Defaults to 40. */
18
19
  readonly lineLength?: number;
20
+ /**
21
+ * Reads the other axis of the wheel when its own is still: an ordinary mouse wheel, which turns only up and down,
22
+ * then scrolls a sideways list. Leave it off for a list inside a page that scrolls the other way, whose wheel should
23
+ * scroll the page. Defaults to false.
24
+ */
25
+ readonly crossAxis?: boolean;
19
26
  }
27
+ /** A scroll thumb to drag: its input and target, its track's length and its shortest length. */
20
28
  export interface ScrollThumbOptions {
21
29
  readonly input: PointerInput;
22
30
  /** The thumb of the scrollbar. One contact drags it. */
@@ -26,6 +34,7 @@ export interface ScrollThumbOptions {
26
34
  /** The shortest the thumb is drawn. Defaults to 16, and is never more than the track. */
27
35
  readonly minimumLength?: number;
28
36
  }
37
+ /** A scroll control to make: its axis, the lengths of its viewport and content, its wheel and thumb, and what it calls. */
29
38
  export interface ScrollControlOptions {
30
39
  /** The axis of the stage the offset moves along. Defaults to 'y'. */
31
40
  readonly axis?: ScrollAxis;
@@ -39,11 +48,13 @@ export interface ScrollControlOptions {
39
48
  readonly onScroll?: (offset: number) => void;
40
49
  readonly onDragChange?: (dragging: boolean) => void;
41
50
  }
51
+ /** Where the thumb is on its track and how long it is. */
42
52
  export interface ScrollThumb {
43
53
  /** Where the thumb begins on its track, and how long it is, in logical units. */
44
54
  readonly start: number;
45
55
  readonly length: number;
46
56
  }
57
+ /** Scrolling along one axis: the offset and its maximum, the thumb, and calls that scroll by lines, pages or to the ends. */
47
58
  export interface ScrollControl {
48
59
  readonly axis: ScrollAxis;
49
60
  readonly offset: number;
@@ -68,5 +79,6 @@ export interface ScrollControl {
68
79
  setEnabled(enabled: boolean): void;
69
80
  dispose(): void;
70
81
  }
82
+ /** Scrolls content past a viewport along one axis, by wheel, by dragging a thumb, or by calls. */
71
83
  export declare function createScrollControl(options: ScrollControlOptions): ScrollControl;
72
84
  //# sourceMappingURL=scrollControl.d.ts.map
@@ -8,6 +8,7 @@ function displayTarget(value) {
8
8
  throw new EgretError('UI_CONTROL_OPTIONS');
9
9
  return value;
10
10
  }
11
+ /** Scrolls content past a viewport along one axis, by wheel, by dragging a thumb, or by calls. */
11
12
  export function createScrollControl(options) {
12
13
  if (options === null || typeof options !== 'object' || Array.isArray(options))
13
14
  throw new EgretError('UI_CONTROL_OPTIONS');
@@ -35,6 +36,8 @@ export function createScrollControl(options) {
35
36
  lineLength = wheel.lineLength ?? 40;
36
37
  if (!length(lineLength) || lineLength <= 0)
37
38
  throw new EgretError('UI_CONTROL_OPTIONS');
39
+ if (wheel.crossAxis !== undefined && typeof wheel.crossAxis !== 'boolean')
40
+ throw new EgretError('UI_CONTROL_OPTIONS');
38
41
  }
39
42
  if (thumb !== undefined) {
40
43
  if (thumb === null ||
@@ -92,7 +95,8 @@ export function createScrollControl(options) {
92
95
  // The zoom gesture of the platform is not a scroll.
93
96
  if (point.zoom === true)
94
97
  return;
95
- const delta = axis === 'y' ? point.deltaY : point.deltaX;
98
+ const own = axis === 'y' ? point.deltaY : point.deltaX, other = axis === 'y' ? point.deltaX : point.deltaY;
99
+ const delta = own === 0 && wheel.crossAxis === true ? other : own;
96
100
  const step = point.unit === 'pixel' ? delta : point.unit === 'line' ? delta * lineLength : delta * viewportLength;
97
101
  // At its end the viewport leaves the wheel to whatever is outside it.
98
102
  if (move(offset + step))
@@ -13,6 +13,7 @@ export interface HoverControlOptions {
13
13
  readonly target: DisplayObject;
14
14
  readonly onHoverChange?: (hovered: boolean) => void;
15
15
  }
16
+ /** Whether a pointer hovers over a target; dispose of it to stop. */
16
17
  export interface HoverControl {
17
18
  /** Whether an enabled control has a pointer over it. */
18
19
  readonly hovered: boolean;
@@ -20,6 +21,7 @@ export interface HoverControl {
20
21
  setEnabled(enabled: boolean): void;
21
22
  dispose(): void;
22
23
  }
24
+ /** A toggle to make: its input and target, whether it starts checked, and what it calls. */
23
25
  export interface ToggleControlOptions {
24
26
  readonly input: PointerInput;
25
27
  readonly target: DisplayObject;
@@ -28,6 +30,7 @@ export interface ToggleControlOptions {
28
30
  readonly onChange?: (checked: boolean) => void;
29
31
  readonly onPressChange?: (pressed: boolean) => void;
30
32
  }
33
+ /** A checkbox or switch: whether it is checked and pressed, and calls that toggle or set it. */
31
34
  export interface ToggleControl {
32
35
  readonly checked: boolean;
33
36
  readonly pressed: boolean;
@@ -42,12 +45,14 @@ export interface ToggleControl {
42
45
  setEnabled(enabled: boolean): void;
43
46
  dispose(): void;
44
47
  }
48
+ /** One item of a selection group: its key, its target and whether it can be chosen. */
45
49
  export interface SelectionItem {
46
50
  readonly key: string;
47
51
  readonly target: DisplayObject;
48
52
  /** Defaults to true. A disabled item is skipped by movement and refuses a press. */
49
53
  readonly enabled?: boolean;
50
54
  }
55
+ /** A selection group to make: its input and items, the one selected, whether it wraps, and what it calls. */
51
56
  export interface SelectionGroupOptions {
52
57
  readonly input: PointerInput;
53
58
  /** One to 256 items with distinct keys and distinct targets, in the order movement follows. */
@@ -76,7 +81,10 @@ export interface SelectionGroup {
76
81
  setEnabled(enabled: boolean): void;
77
82
  dispose(): void;
78
83
  }
84
+ /** Tells whether a pointer hovers over a target. */
79
85
  export declare function createHoverControl(options: HoverControlOptions): HoverControl;
86
+ /** A checkbox or switch on a target: a press and release inside it toggles it. */
80
87
  export declare function createToggleControl(options: ToggleControlOptions): ToggleControl;
88
+ /** Radio buttons or tabs: one item of the group is selected at a time. */
81
89
  export declare function createSelectionGroup(options: SelectionGroupOptions): SelectionGroup;
82
90
  //# sourceMappingURL=stateControls.d.ts.map
@@ -27,6 +27,7 @@ function within(root, node) {
27
27
  }
28
28
  return false;
29
29
  }
30
+ /** Tells whether a pointer hovers over a target. */
30
31
  export function createHoverControl(options) {
31
32
  const { hover, onHoverChange } = record(options);
32
33
  const target = displayTarget(options.target);
@@ -116,6 +117,7 @@ export function createHoverControl(options) {
116
117
  }
117
118
  });
118
119
  }
120
+ /** A checkbox or switch on a target: a press and release inside it toggles it. */
119
121
  export function createToggleControl(options) {
120
122
  const { input, target, onChange, onPressChange } = record(options);
121
123
  let checked = options.checked ?? false;
@@ -178,6 +180,7 @@ export function createToggleControl(options) {
178
180
  }
179
181
  });
180
182
  }
183
+ /** Radio buttons or tabs: one item of the group is selected at a time. */
181
184
  export function createSelectionGroup(options) {
182
185
  const { input, onChange } = record(options);
183
186
  const { items, wrap = true } = options;
@@ -48,6 +48,7 @@ export interface TextEditorHostPort {
48
48
  }
49
49
  /** Browser-only package alias; the public UI entry never exposes native session operations. */
50
50
  export declare function bindTextEditorHost(editor: UiTextEditor, hooks: HostHooks): TextEditorHostPort;
51
+ /** A text editor drawn by the engine, its text and selection kept by the platform's text input. */
51
52
  export declare function createUiTextEditor(options: UiTextEditorOptions): UiTextEditor;
52
53
  export { requireUiEngine as requireEditorEngine } from '../internal/uiFactoryState.js';
53
54
  //# sourceMappingURL=textEditor.d.ts.map
@@ -63,6 +63,7 @@ export function bindTextEditorHost(editor, hooks) {
63
63
  return fail('INVALID');
64
64
  return record.bind(hooks);
65
65
  }
66
+ /** A text editor drawn by the engine, its text and selection kept by the platform's text input. */
66
67
  export function createUiTextEditor(options) {
67
68
  if (options === null || typeof options !== 'object')
68
69
  return fail('OPTIONS');
@@ -3,6 +3,7 @@ import type { TextEditSelection, TextEditSnapshot } from '@egret/runtime/ui/edit
3
3
  import type { ParagraphCache, ParagraphTextGeometry } from '@egret/runtime/paragraph';
4
4
  import type { Engine } from '../Engine.js';
5
5
  import type { UiLeafContent, UiLeafPrepareContext, RowBinding, UiRoot } from './types.js';
6
+ /** How a text editor's text looks: its fonts and size, line height, locale and direction, colors and alignment. */
6
7
  export interface UiTextEditorStyle {
7
8
  readonly fontSet: string;
8
9
  readonly fontFamilies: readonly string[];
@@ -14,6 +15,7 @@ export interface UiTextEditorStyle {
14
15
  readonly backgroundColor?: number;
15
16
  readonly textAlign?: 'left' | 'right' | 'center' | 'start' | 'end';
16
17
  }
18
+ /** A change to a text editor's content or selection, and what made it. */
17
19
  export interface UiTextEditorChange {
18
20
  readonly kind: 'value' | 'style';
19
21
  readonly source: 'native' | 'programmatic';
@@ -22,6 +24,7 @@ export interface UiTextEditorChange {
22
24
  readonly value: string;
23
25
  readonly selection: Required<TextEditSelection>;
24
26
  }
27
+ /** A text editor to make: its engine, scope and cache, its mode, value and limits, its style and size, and what it calls. */
25
28
  export interface UiTextEditorOptions {
26
29
  readonly engine: Engine;
27
30
  readonly scope: Scope;
@@ -39,6 +42,7 @@ export interface UiTextEditorOptions {
39
42
  /** Stage a new existing UI tree/source revision; never run another frame loop. */
40
43
  readonly onChange?: (change: UiTextEditorChange) => void;
41
44
  }
45
+ /** What a text editor is drawn in: a leaf of the tree, or a row of a list. */
42
46
  export type UiTextEditorTarget = Readonly<{
43
47
  kind: 'leaf';
44
48
  id: string;
@@ -47,18 +51,21 @@ export type UiTextEditorTarget = Readonly<{
47
51
  listId: string;
48
52
  key: string;
49
53
  }>;
54
+ /** A text editor as it is now: its content revision, style, and whether the native editor shows. */
50
55
  export interface UiTextEditorSnapshot extends Omit<TextEditSnapshot, 'session'> {
51
56
  readonly contentRevision: number;
52
57
  readonly style: UiTextEditorStyle;
53
58
  readonly nativeVisible: boolean;
54
59
  readonly livePresentations: number;
55
60
  }
61
+ /** How a value is set: the selection after it, the revision it expects, and whether a composition is cancelled. */
56
62
  export interface UiTextEditorSetOptions {
57
63
  readonly selection?: TextEditSelection;
58
64
  readonly expectedRevision?: number;
59
65
  readonly cancelComposition?: boolean;
60
66
  }
61
67
  declare const editorBrand: unique symbol;
68
+ /** A text editor: its content, the calls that set its value, selection and style, and the geometry of its text. */
62
69
  export interface UiTextEditor {
63
70
  readonly [editorBrand]: true;
64
71
  readonly mode: UiTextEditorOptions['mode'];
@@ -14,6 +14,7 @@ export interface TextFieldRectangle {
14
14
  readonly width: number;
15
15
  readonly height: number;
16
16
  }
17
+ /** A text field's value after a change, and whether a composition is under way. */
17
18
  export interface TextFieldChange {
18
19
  readonly value: string;
19
20
  /** True while an input method still holds provisional text. */
@@ -41,6 +42,7 @@ export interface TextFieldEditor<Request> {
41
42
  cancel(): void;
42
43
  setValue(value: string): void;
43
44
  }
45
+ /** A text field to make: its input, target and editor, its value and limits, its labels, and what it calls. */
44
46
  export interface TextFieldControlOptions<Presentation extends TextFieldRectangle> {
45
47
  readonly input: PointerInput;
46
48
  /** The surface of the field. A completed press on it begins an edit. */
@@ -68,6 +70,7 @@ export interface TextFieldControlOptions<Presentation extends TextFieldRectangle
68
70
  readonly onEditingChange?: (editing: boolean) => void;
69
71
  readonly onPressChange?: (pressed: boolean) => void;
70
72
  }
73
+ /** A text field: its value and draft, whether it is being edited, and calls that edit, commit or cancel. */
71
74
  export interface TextFieldControl {
72
75
  /** The committed text. */
73
76
  readonly value: string;
@@ -92,5 +95,6 @@ export interface TextFieldControl {
92
95
  setEnabled(enabled: boolean): void;
93
96
  dispose(): void;
94
97
  }
98
+ /** A text field on a target: pressing it opens the platform's editing, and the value is committed or cancelled. */
95
99
  export declare function createTextFieldControl<Presentation extends TextFieldRectangle>(options: TextFieldControlOptions<Presentation>): TextFieldControl;
96
100
  //# sourceMappingURL=textFieldControl.d.ts.map
@@ -15,6 +15,7 @@ function clip(text, limit) {
15
15
  }
16
16
  return text.slice(0, index);
17
17
  }
18
+ /** A text field on a target: pressing it opens the platform's editing, and the value is committed or cancelled. */
18
19
  export function createTextFieldControl(options) {
19
20
  if (options === null || typeof options !== 'object')
20
21
  throw new EgretError('UI_CONTROL_OPTIONS');
@@ -1,4 +1,5 @@
1
1
  import type { UiLayoutTree } from '@egret/runtime/ui';
2
+ /** A theme's type: its font family, size and line height. */
2
3
  export interface UiThemeTypography {
3
4
  readonly fontFamily: string;
4
5
  readonly fontSize: number;
@@ -15,6 +16,7 @@ export interface UiThemeSkin {
15
16
  readonly selected?: string;
16
17
  readonly expanded?: string;
17
18
  }
19
+ /** A theme to make: its id, colors, spacing, type and skins. */
18
20
  export interface UiThemeDescriptor {
19
21
  readonly id: string;
20
22
  readonly colors?: Readonly<Record<string, number>>;
@@ -32,14 +34,17 @@ export interface UiTheme {
32
34
  readonly typography: Readonly<Record<string, UiThemeTypography>>;
33
35
  readonly skins: Readonly<Record<string, UiThemeSkin>>;
34
36
  }
37
+ /** How a node of a theme is filled and spaced. */
35
38
  export interface UiThemeNode {
36
39
  readonly fill?: string;
37
40
  readonly padding?: string;
38
41
  readonly gap?: string;
39
42
  }
43
+ /** Checks and freezes a theme from its description. */
40
44
  export declare function createUiTheme(descriptor: UiThemeDescriptor): UiTheme;
41
45
  /** The states of a control that a skin may have a name for. */
42
46
  export type UiSkinStateName = Exclude<keyof UiThemeSkin, 'default'>;
47
+ /** Which named states of a control are on, to choose its skin. */
43
48
  export type UiSkinState = {
44
49
  readonly [Name in UiSkinStateName]?: boolean;
45
50
  };
package/dist/ui/theme.js CHANGED
@@ -45,6 +45,7 @@ function tokens(value, capture) {
45
45
  result[key] = capture(input[key]);
46
46
  return freeze(result);
47
47
  }
48
+ /** Checks and freezes a theme from its description. */
48
49
  export function createUiTheme(descriptor) {
49
50
  const raw = record(descriptor, ['id', 'colors', 'spacing', 'typography', 'skins']);
50
51
  const result = freeze({
@@ -8,6 +8,7 @@ import type { PointerInput, PointerContact, PointerCancelReason } from '../point
8
8
  type LayoutDimensions = Omit<UiLayoutNode, 'kind' | 'children' | 'source' | 'initialScrollOffset' | 'measure' | 'fill'> & {
9
9
  readonly theme?: UiThemeNode;
10
10
  };
11
+ /** A node of a UI layout tree: a leaf, a stack of children, or a virtual list. */
11
12
  export type LayoutNode = (LayoutDimensions & {
12
13
  readonly kind: 'leaf';
13
14
  readonly fill?: NonNullable<UiLayoutNode['fill']>;
@@ -25,24 +26,29 @@ export type LayoutNode = (LayoutDimensions & {
25
26
  readonly source: VirtualDataSource<unknown>;
26
27
  readonly initialScrollOffset?: number;
27
28
  });
29
+ /** What of a UI root has to be done again: its layout, its content, or both. */
28
30
  export type UiInvalidationKind = UiDirtyKind;
31
+ /** How far past the viewport a list keeps rows, and how many rows it keeps resident and retained. */
29
32
  export interface UiLimits {
30
33
  readonly overscan?: number;
31
34
  readonly residentCap?: number;
32
35
  readonly retainedCap?: number;
33
36
  }
37
+ /** One record of a virtual list: its key, its content version, its estimated height and its value. */
34
38
  export interface VirtualRecord<T> {
35
39
  readonly key: string;
36
40
  readonly contentVersion: number;
37
41
  readonly estimatedHeight: number;
38
42
  readonly value: T;
39
43
  }
44
+ /** The records of a virtual list, and how a row is bound to a record and unbound from it. */
40
45
  export interface VirtualDataSource<T> {
41
46
  readonly revision: number;
42
47
  readonly records: readonly VirtualRecord<T>[];
43
48
  bind(context: RowBindContext<T>): RowBinding | Promise<RowBinding>;
44
49
  unbind(info: RowUnbindInfo): void;
45
50
  }
51
+ /** What binding a row is given: the record, its place, the theme and density, its scope, signal and target. */
46
52
  export interface RowBindContext<T> {
47
53
  readonly theme: UiTheme | undefined;
48
54
  readonly key: string;
@@ -69,23 +75,28 @@ export interface UiLeafPrepareContext {
69
75
  readonly density: number;
70
76
  readonly signal: CancellationSignal;
71
77
  }
78
+ /** What a leaf shows, prepared for the size it is given. */
72
79
  export interface UiLeafContent {
73
80
  readonly revision: number;
74
81
  prepare(context: UiLeafPrepareContext): RowBinding | Promise<RowBinding>;
75
82
  }
83
+ /** What a bound row shows, and its measured height. */
76
84
  export interface RowBinding {
77
85
  readonly content: DisplayObjectContainer;
78
86
  readonly measuredHeight: number;
79
87
  }
88
+ /** A row that was unbound: its key, its binding and content versions, and why. */
80
89
  export interface RowUnbindInfo {
81
90
  readonly key: string;
82
91
  readonly bindingGeneration: number;
83
92
  readonly contentVersion: number;
84
93
  readonly reason: 'recycle' | 'replace' | 'delete' | 'cancel' | 'dispose' | 'error';
85
94
  }
95
+ /** A row kept bound after it leaves the viewport; release it to let it go. */
86
96
  export interface RowRetention {
87
97
  release(): void;
88
98
  }
99
+ /** A pointer that began, moved, ended or was cancelled on a row of a list. */
89
100
  export type UiRowPointerNotification = Readonly<{
90
101
  kind: 'begin' | 'move' | 'end';
91
102
  listId: string;
@@ -121,6 +132,7 @@ export interface UiKeyboardOptions {
121
132
  */
122
133
  readonly tabStop?: number;
123
134
  }
135
+ /** A UI root to make: its theme, engine and scope, its viewport, density and tree, its input, and its limits. */
124
136
  export interface UiRootOptions {
125
137
  readonly theme?: UiTheme;
126
138
  readonly engine: Engine;
@@ -142,17 +154,20 @@ export interface UiRootOptions {
142
154
  readonly limits?: UiLimits;
143
155
  }
144
156
  declare const preparationBrand: unique symbol;
157
+ /** Where a preparation is, and the revisions it works from. */
145
158
  export interface UiPreparation {
146
159
  readonly [preparationBrand]: true;
147
160
  readonly status: 'ready' | 'pending' | 'unchanged';
148
161
  readonly desiredRevision: number;
149
162
  readonly baseCommittedRevision: number;
150
163
  }
164
+ /** What a commit did, and any errors after it. */
151
165
  export interface UiCommitResult {
152
166
  readonly kind: 'unchanged' | 'committed' | 'stale' | 'closed';
153
167
  readonly revision: number;
154
168
  readonly postCommitErrors: readonly unknown[];
155
169
  }
170
+ /** One row as committed: its key and place, its versions, its box and whether it shows. */
156
171
  export interface UiRowSnapshot {
157
172
  readonly key: string;
158
173
  readonly index: number;
@@ -166,6 +181,7 @@ export interface UiRowSnapshot {
166
181
  }>;
167
182
  readonly visible: boolean;
168
183
  }
184
+ /** What a UI root counted in its last passes: layouts, records, rows, bindings and measurements. */
169
185
  export interface UiCounters {
170
186
  /** Cumulative planner calls, including detached constraint discovery. */
171
187
  readonly layoutPasses: number;
@@ -188,6 +204,7 @@ export interface UiCounters {
188
204
  readonly resourceDemands: number | undefined;
189
205
  readonly resourceLeases: number | undefined;
190
206
  }
207
+ /** A virtual list as committed: its rows, scroll offset and extent, its anchor and counters. */
191
208
  export interface VirtualListSnapshot {
192
209
  readonly id: string;
193
210
  readonly rows: readonly UiRowSnapshot[];
@@ -199,6 +216,7 @@ export interface VirtualListSnapshot {
199
216
  }> | undefined;
200
217
  readonly counters: UiCounters;
201
218
  }
219
+ /** A UI root as committed: its theme, revisions, origin, viewport, density and boxes. */
202
220
  export interface UiSnapshot extends VirtualListSnapshot {
203
221
  readonly theme: UiTheme | undefined;
204
222
  readonly rootId: string;
@@ -221,6 +239,7 @@ export interface UiSnapshot extends VirtualListSnapshot {
221
239
  export interface VirtualListRevealOptions {
222
240
  readonly align?: 'nearest' | 'start' | 'center' | 'end';
223
241
  }
242
+ /** A virtual list of a UI root: reveal a record, change its source or scroll, and read its snapshot. */
224
243
  export interface VirtualListHandle<T> {
225
244
  /** Stage key-directed scrolling. Undefined cancels an uncommitted reveal. */
226
245
  reveal(key: string | undefined, options?: VirtualListRevealOptions): void;
@@ -239,6 +258,7 @@ export interface VirtualListHandle<T> {
239
258
  }>;
240
259
  snapshot(): VirtualListSnapshot;
241
260
  }
261
+ /** A tree of UI laid out in a viewport: change its tree, theme or input, then prepare and commit it. */
242
262
  export interface UiRoot {
243
263
  readonly id: string;
244
264
  readonly state: 'open' | 'closed';