Add setStageTitle method to the prepare context API

CHANGELOG.md

@@ -1,5 +1,14 @@
 ## next
 
+- Added `setStageTitle` method to the prepare context API to display additional text on the progress bar:
+```js
+export function async prepare(input, { setStageTitle }) {
+    await setStageTitle('phase 1');
+    // ...
+    await setStageTitle('phase 2');
+    // ...
+}
+```
 - Fixed crashing the entire render tree on an exception in a view's `render` function; now, crashes are isolated to the affected view
 - Fixed unnecessary view rendering when returning to the discovery page
 - Fixed hiding a popup with `hideOnResize: true` when scrolling outside of the popup element

src/core/utils/progressbar.ts

@@ -137,6 +137,8 @@ export default class Progressbar extends Observer<ProgressbarState> {
     appearanceDelay: number;
     domReady: Promise<any>;
     el: HTMLElement;
+    #titleEl: HTMLElement;
+    #stepEl: HTMLElement;
 
     constructor({ onTiming, onFinish, delay, domReady }: ProgressbarOptions) {
         super({ stage: 'inited', progress: null, error: null });
@@ -152,7 +154,10 @@ export default class Progressbar extends Observer<ProgressbarState> {
         this.domReady = domReady || Promise.resolve();
 
         this.el = createElement('div', 'view-progress init', [
-            createElement('div', 'title'),
+            createElement('div', 'content main-secondary', [
+                this.#titleEl = createElement('span', 'main'),
+                this.#stepEl = createElement('span', 'secondary')
+            ]),
             createElement('div', 'progress')
         ]);
     }
@@ -173,6 +178,16 @@ export default class Progressbar extends Observer<ProgressbarState> {
         this.onTiming(entry);
     }
 
+    async #awaitRenderIfNeeded(enforce = false, now = performance.now()) {
+        const timeSinceAwaitRepaint = now - (this.awaitRepaint || 0);
+        const timeSinceLastStageStart = now - (this.lastStageStart || 0);
+
+        if (enforce || (timeSinceAwaitRepaint > 65 && timeSinceLastStageStart > 200)) {
+            await letRepaintIfNeeded();
+            this.awaitRepaint = performance.now();
+        }
+    }
+
     async setState(state: Partial<ProgressbarState>) {
         const { stage = this.lastStage, progress = null, error = null } = state;
 
@@ -224,18 +239,20 @@ export default class Progressbar extends Observer<ProgressbarState> {
         }
 
         const { title, progressValue } = decodeStageProgress(stage, progress);
-        const titleEl = this.el.querySelector('.title');
 
         this.el.style.setProperty('--progress', String(progressValue));
 
-        if (titleEl !== null) {
-            titleEl.textContent = title;
-        }
+        this.#titleEl.textContent = title;
+        this.#stepEl.textContent = '';
 
-        if (stageChanged || (now - (this.awaitRepaint || 0) > 65 && now - (this.lastStageStart || 0) > 200)) {
-            await letRepaintIfNeeded();
-            this.awaitRepaint = performance.now();
-        }
+        return this.#awaitRenderIfNeeded(stageChanged, now);
+    }
+
+    async setStateStep(name: string) {
+        this.#titleEl.textContent = (this.#titleEl.textContent || '').replace(/(\.{3}|:)?$/, ':');
+        this.#stepEl.textContent = name;
+
+        return this.#awaitRenderIfNeeded(true);
     }
 
     finish(error?: Error) {

src/main/model-extension-api.ts

@@ -1,14 +1,15 @@
-import jora from 'jora';
-import type { Model, ModelOptions, PageParams, PageRef, PrepareContextApiWrapper, SetupMethods } from './model.js';
+import type { Model, ModelOptions, PageParams, PageRef, PrepareContextApiWrapper, SetDataOptions, SetupMethods } from './model.js';
 import type { ObjectMarkerConfig } from '../core/object-marker.js';
+import jora from 'jora';
 
-export function createExtensionApi(host: Model): PrepareContextApiWrapper {
+export function createExtensionApi(host: Model, options?: SetDataOptions): PrepareContextApiWrapper {
     return {
         before() {
             host.objectMarkers.reset();
         },
         contextApi: {
             markers: host.objectMarkers.markerMap(),
+            setStageTitle: options?.setPrepareStepTitle || (() => Promise.resolve()),
             rejectData(message: string, renderContent: any) {
                 throw Object.assign(new Error(message), { renderContent });
             }

src/main/model-legacy-extension-api.ts

@@ -1,13 +1,14 @@
-import jora from 'jora';
-import ObjectMarker, { ObjectMarkerConfig } from '../core/object-marker.js';
-import type { LegacyPrepareContextApi, PrepareContextApiWrapper, Model, Query, PageRef, PageParams } from './model.js';
+import type { LegacyPrepareContextApi, PrepareContextApiWrapper, Model, Query, PageRef, PageParams, SetDataOptions } from './model.js';
 import type { ValueAnnotationContext, Widget } from './widget.js';
+import ObjectMarker, { ObjectMarkerConfig } from '../core/object-marker.js';
+import jora from 'jora';
 
-export function createLegacyExtensionApi(host: Model): PrepareContextApiWrapper {
+export function createLegacyExtensionApi(host: Model, options?: SetDataOptions): PrepareContextApiWrapper {
     const objectMarkers = new ObjectMarker();
     const linkResolvers: Model['linkResolvers'] = [];
     const annotations: Widget['annotations'] = [];
     const contextApi: LegacyPrepareContextApi = {
+        setStageTitle: options?.setPrepareStepTitle || (() => Promise.resolve()),
         rejectData(message: string, renderContent: any) {
             throw Object.assign(new Error(message), { renderContent });
         },

src/main/model.ts

@@ -45,6 +45,7 @@ export type ModelDataset = Dataset | RawDataDataset;
 export type GetDecodeParams = (pageId: string) => (entries: [string, any][]) => object;
 
 export interface SetDataOptions {
+    setPrepareStepTitle?: (name: string) => Promise<void>;
     dataset?: Dataset;
 }
 
@@ -64,10 +65,12 @@ export type PrepareContextApiWrapper = {
     contextApi: PrepareContextApi | LegacyPrepareContextApi;
 };
 export interface PrepareContextApi {
+    setStageTitle: (name: string) => Promise<void>;
     rejectData: (message: string, extra: any) => void;
     markers: Record<string, (value: unknown) => void>;
 }
 export interface LegacyPrepareContextApi {
+    setStageTitle: (name: string) => Promise<void>;
     rejectData: (message: string, extra: any) => void;
     defineObjectMarker<T extends object>(name: string, options: ObjectMarkerConfig<T>): ObjectMarker<T>['mark'];
     lookupObjectMarker(value: any, type?: string): ObjectMarkerDescriptor<object> | null;
@@ -227,7 +230,7 @@ export class Model<
         this.prepare = fn;
     }
 
-    setData(data: unknown, options: SetDataOptions) {
+    setData(data: unknown, options?: SetDataOptions) {
         options = options || {};
 
         // mark as last setData promise
@@ -243,8 +246,8 @@ export class Model<
         };
 
         const prepareApi = this.#legacyPrepare
-            ? createLegacyExtensionApi(this)
-            : createExtensionApi(this);
+            ? createLegacyExtensionApi(this, options)
+            : createExtensionApi(this, options);
         const setDataPromise = Promise.resolve()
             .then(() => {
                 checkIsNotPrevented();

src/main/widget.ts

@@ -245,6 +245,7 @@ export class Widget<
         await progressbar?.setState({ stage: 'prepare' });
         await this.setData(data, context, {
             dataset,
+            setPrepareStepTitle: progressbar?.setStateStep.bind(progressbar),
             render: false
         });
 

src/views/controls/progress.css

@@ -32,3 +32,15 @@
     /* transition: transform .2s; */ /* since Chrome (tested on 85) freezes transition during js loop */
     background-color: var(--color, #1f7ec5);
 }
+
+.view-progress > .content.main-secondary {
+    display: flex;
+    white-space: nowrap;
+    gap: 1ex;
+}
+.view-progress > .content > .secondary {
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    color: #888;
+}

src/views/controls/progress.js

@@ -5,13 +5,16 @@ import usage from './progress.usage.js';
 export default function(host) {
     host.view.define('progress', function(el, config, data, context) {
         const { content, progress, color } = config;
-        const progressEl = el.appendChild(createElement('div', {
+
+        el.append(createElement('div', {
             class: 'progress',
             style: `--progress: ${Math.max(0, Math.min(1, Number(progress)))};--color: ${color || 'unset'};`
         }));
 
         if (content) {
-            const contentEl = el.insertBefore(createElement('div', { class: 'content' }), progressEl);
+            const contentEl = createElement('div', 'content');
+
+            el.prepend(contentEl);
 
             return host.view.render(contentEl, content, data, context);
         }