@api-client/ui 0.5.30 → 0.5.32

package/src/core/renderer/Renderer.ts

@@ -1,10 +1,10 @@
+import { render, type RootPart, type TemplateResult, type nothing } from 'lit'
+
 export enum RenderingState {
   Idle,
   Rendering,
 }
 
-export const renderFn = Symbol('renderFn')
-
 /**
  * A class that manages rendering of the application screen.
  */
@@ -22,8 +22,10 @@ export abstract class Renderer {
   }
 
   /**
-   * Sets the root element where the application will be rendered.
-   * @param renderRoot The root element or its selector.
+   * Sets the root element where the application or activity will be rendered.
+   *
+   * @param renderRoot - The root element or a CSS selector string for the element.
+   * If a string is provided, it will be queried from the document.
    */
   setRenderRoot(renderRoot: HTMLElement | string): void {
     if (typeof renderRoot === 'string') {
@@ -34,8 +36,10 @@ export abstract class Renderer {
   }
 
   /**
-   * Requests an update of the application UI. This will call the `render()` method
-   * and update the DOM.
+   * Requests an update of the UI. Schedules a render if one is not already pending.
+   *
+   * This will call the `renderer()` method and update the DOM in the next animation frame.
+   * Ensures only one render is scheduled at a time.
    */
   requestUpdate(): void {
     if (this.#renderingState !== RenderingState.Idle) {
@@ -47,7 +51,7 @@ export abstract class Renderer {
       this.#setUpdatePromise()
     }
     requestAnimationFrame(() => {
-      this[renderFn]()
+      this.renderer()
       this.#renderingState = RenderingState.Idle
     })
   }
@@ -55,8 +59,7 @@ export abstract class Renderer {
   protected firstRenderedFlag = false
 
   /**
-   * Determines whether the initial render had run and the `onFirstRender()`
-   * function was called.
+   * Indicates whether the initial render has occurred and `onFirstRender()` was called.
    */
   get firstRendered(): boolean {
     return this.firstRenderedFlag
@@ -67,6 +70,15 @@ export abstract class Renderer {
    */
   #renderingState = RenderingState.Idle
 
+  /**
+   * Returns the current rendering state.
+   *
+   * @returns The current rendering state.
+   */
+  get state(): RenderingState {
+    return this.#renderingState
+  }
+
   /**
    * A flag that helps to determine whether the `updateComplete` is setup.
    */
@@ -80,13 +92,19 @@ export abstract class Renderer {
   /**
    * The resolver to call when the update completes.
    */
-  #updateResolver?: () => void;
+  #updateResolver?: () => void
 
   /**
-   * Manages the rendering of the UI.
+   * Abstract method that must be implemented by subclasses to perform the actual rendering logic.
+   *
+   * Called by `requestUpdate()` when a render is scheduled.
    */
-  abstract [renderFn](): void
+  protected abstract renderer(): void
 
+  /**
+   * Sets up the promise that will be resolved when the next render completes.
+   * Used for tracking asynchronous rendering.
+   */
   #setUpdatePromise(): void {
     this.#updateComplete = new Promise<void>((resolve) => {
       this.#updateResolver = resolve
@@ -94,6 +112,9 @@ export abstract class Renderer {
     })
   }
 
+  /**
+   * Resolves the update promise if one is pending, indicating that rendering has finished.
+   */
   protected resolveUpdatePromise(): void {
     if (!this.#hasPendingUpdatePromise) {
       return
@@ -104,4 +125,31 @@ export abstract class Renderer {
       resolver()
     }
   }
+
+  /**
+   * Renders the given Lit template into the specified root element, setting the host context.
+   *
+   * @param content - The Lit template or `nothing` to render.
+   * @param root - The root HTMLElement to render into.
+   * @param host - The host object for Lit's context (usually the Application or Activity).
+   */
+  protected _render(content: TemplateResult | typeof nothing, root: HTMLElement, host: object): void {
+    const litPart = root as HTMLElement & { _$litPart$?: RootPart }
+    if (litPart._$litPart$ && litPart._$litPart$.options) {
+      litPart._$litPart$.options.host = host
+    }
+    render(content, root, { host })
+    this.resolveUpdatePromise()
+  }
+
+  /**
+   * Removes all child nodes from the given root element.
+   *
+   * Uses `replaceChildren()` for efficient DOM cleanup.
+   * @param root - The root HTMLElement to clear.
+   */
+  protected _clearRoot(root: HTMLElement): void {
+    // Using replaceChildren() is a modern and clean way to clear a node's children.
+    root.replaceChildren()
+  }
 }

package/test/core/activity_manager.spec.ts

@@ -354,10 +354,10 @@ describe('ActivityManager', () => {
 
       assert.isTrue(activity1.onActivityResult.calledOnce)
       const [calledRequestCode, calledResultCode, calledIntent] = activity1.onActivityResult.firstCall.args
-      assert.equal(calledRequestCode, requestCode)
-      assert.equal(calledResultCode, IntentResult.RESULT_OK)
-      assert.deepEqual(calledIntent.data, resultData)
-      assert.equal(calledIntent.action, TestActivity2.action)
+      assert.equal(calledRequestCode, requestCode, 'has the request code from activity1')
+      assert.equal(calledResultCode, IntentResult.RESULT_OK, 'has the OK result code')
+      assert.deepEqual(calledIntent.data, resultData, 'has the result data from activity2')
+      assert.equal(calledIntent.action, TestActivity2.action, 'has the action of activity2')
     })
 
     it('handles finishing an activity that was only created (not fully started)', async () => {

package/test/core/renderer.spec.ts

@@ -0,0 +1,113 @@
+import { html } from 'lit'
+import { assert, nextFrame } from '@open-wc/testing'
+import sinon from 'sinon'
+import { ApplicationRenderer } from '../../src/core/renderer/ApplicationRenderer.js'
+import { type Application } from '../../src/core/Application.js'
+import { FragmentRenderer } from '../../src/core/renderer/FragmentRenderer.js'
+import { Renderer } from '../../src/core/renderer/Renderer.js'
+import { type Fragment } from '../../src/core/Fragment.js'
+
+describe('Renderer', () => {
+  class TestRenderer extends Renderer {
+    public renderCalled = false
+    public renderArgs: unknown[] = []
+    protected renderer(): void {
+      this.renderCalled = true
+      // eslint-disable-next-line prefer-rest-params
+      this.renderArgs = [...arguments]
+      this.resolveUpdatePromise()
+    }
+  }
+
+  it('should set renderRoot from HTMLElement', () => {
+    const el = document.createElement('div')
+    const renderer = new TestRenderer()
+    renderer.setRenderRoot(el)
+    assert.strictEqual(renderer.renderRoot, el)
+  })
+
+  it('should set renderRoot from selector', () => {
+    const el = document.createElement('div')
+    el.id = 'test-root'
+    document.body.appendChild(el)
+    const renderer = new TestRenderer()
+    renderer.setRenderRoot('#test-root')
+    assert.strictEqual(renderer.renderRoot, el)
+    document.body.removeChild(el)
+  })
+
+  it('should call renderer() on requestUpdate()', () => {
+    const renderer = new TestRenderer()
+    const spy = sinon.spy(renderer as unknown as { renderer: () => void }, 'renderer')
+    renderer.requestUpdate()
+    // Wait for animation frame
+    return new Promise<void>((resolve) => {
+      requestAnimationFrame(() => {
+        assert.isTrue(spy.calledOnce)
+        resolve()
+      })
+    })
+  })
+
+  it('should not schedule multiple renders if already rendering', async () => {
+    const renderer = new TestRenderer()
+    renderer.requestUpdate()
+    const spy = sinon.spy(renderer as unknown as { renderer: () => void }, 'renderer')
+    renderer.requestUpdate()
+    assert.isTrue(spy.notCalled)
+  })
+
+  it('should clear root with _clearRoot()', () => {
+    const el = document.createElement('div')
+    el.appendChild(document.createElement('span'))
+    const renderer = new TestRenderer()
+    renderer['_clearRoot'](el)
+    assert.strictEqual(el.childNodes.length, 0)
+  })
+
+  it('should resolve updateComplete after _render()', async () => {
+    const el = document.createElement('div')
+    const renderer = new TestRenderer()
+    renderer.setRenderRoot(el)
+    renderer.requestUpdate()
+    await renderer.updateComplete
+    assert.isFalse(renderer.firstRendered) // firstRenderedFlag is not set in TestRenderer
+  })
+})
+
+describe('ApplicationRenderer', () => {
+  it('should call _handleFirstRender and _render', async () => {
+    const app = {
+      onFirstRender: sinon.spy(),
+      onRendered: sinon.spy(),
+      manager: { getTopActivity: () => null },
+      render: () => html`<div>app</div>`,
+    }
+    const renderer = new ApplicationRenderer(app as unknown as Application)
+    const root = document.createElement('div')
+    renderer.setRenderRoot(root)
+    const spyRender = sinon.spy(renderer as unknown as { _render: () => void }, '_render')
+    renderer['renderer']()
+    await nextFrame()
+    assert.isTrue(app.onFirstRender.called, 'onFirstRender should be called')
+    assert.isTrue(app.onRendered.called, 'onRendered should be called')
+    assert.isTrue(spyRender.called, '_render should be called')
+  })
+})
+
+describe('FragmentRenderer', () => {
+  it('should call _clearRoot and _render on first render', async () => {
+    const fragment = {
+      getSingleVisibleFragment: () => null,
+      render: () => html`<div>fragment</div>`,
+      onFirstRender: sinon.spy(),
+    }
+    const renderer = new FragmentRenderer(fragment as unknown as Fragment)
+    const root = document.createElement('div')
+    renderer.setRenderRoot(root)
+    renderer['renderer']()
+    await nextFrame()
+    assert.isTrue(fragment.onFirstRender.called, 'onFirstRender should be called')
+    assert.strictEqual(root.childElementCount, 1, 'Root should have one child after rendering')
+  })
+})