feat: add async demo support and enhance template resolution

- Introduced async demo functionality in the README, allowing for asynchronous data preparation before rendering components.
- Updated WccDashboard, WccProperties, and WccSidebar to support Promise-based template factories.
- Implemented resolveTemplateFactory to handle both synchronous and asynchronous template results.
- Added tests for resolveTemplateFactory to ensure correct behavior for both sync and async templates.
- Updated pnpm workspace configuration.

package.json

@@ -17,18 +17,20 @@
   "author": "Lossless GmbH",
   "license": "UNLICENSED",
   "dependencies": {
-    "@design.estate/dees-domtools": "^2.0.57",
+    "@design.estate/dees-domtools": "^2.3.3",
-    "@design.estate/dees-element": "^2.0.34",
+    "@design.estate/dees-element": "^2.1.2",
     "@push.rocks/smartdelay": "^3.0.5",
-    "lit": "^3.1.3"
+    "lit": "^3.3.1"
   },
   "devDependencies": {
-    "@api.global/typedserver": "^3.0.29",
+    "@api.global/typedserver": "^3.0.79",
-    "@git.zone/tsbuild": "^2.1.72",
+    "@git.zone/tsbuild": "^2.6.8",
-    "@git.zone/tsbundle": "^2.0.15",
+    "@git.zone/tsbundle": "^2.5.1",
     "@git.zone/tsrun": "^1.2.44",
-    "@git.zone/tswatch": "^2.0.23",
+    "@git.zone/tstest": "^2.3.8",
-    "@push.rocks/projectinfo": "^5.0.2"
+    "@git.zone/tswatch": "^2.2.1",
+    "@push.rocks/projectinfo": "^5.0.2",
+    "@types/node": "^22.18.6"
   },
   "files": [
     "ts/**/*",

pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - esbuild
+  - mongodb-memory-server
+  - puppeteer

readme.md

@@ -211,6 +211,19 @@ export class MyComponent extends DeesElement {
 }
 ```
 
+### ⏳ Async Demos
+
+If your catalogue needs additional setup before rendering, return a `Promise` from the `demo` function. The dashboard waits for the result before inserting it into the viewport:
+
+```typescript
+public static demo = async () => {
+  await Promise.resolve(); // e.g. fetch data, load fixtures, or await wrappers
+  return html`<my-component .value=${'Loaded asynchronously'}></my-component>`;
+};
+```
+
+The same pattern works for page factories you pass into `setupWccTools`, enabling asynchronous data preparation across the entire demo surface.
+
 ### 🎭 Container Queries Support
 
 Components can respond to their container size:

readme.plan.md

@@ -98,3 +98,10 @@ Properties panel was overwriting values set by demo functions
 3. Added proper number parsing for number inputs
 4. Increased initial wait to 200ms for demo wrappers to complete
 5. Simplified select element handling to use property binding
+# Async Demo Support (IN PROGRESS)
+
+## Tasks
+- [ ] Allow dashboard-selected items to return Promise-based TemplateResults
+- [ ] Await async demos/pages before rendering them into the viewport
+- [ ] Add regression test covering async demo usage
+- [ ] Document async demo pattern in README and verify with pnpm scripts

test/test.demoresolver.node.ts

@@ -0,0 +1,22 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import { resolveTemplateFactory } from '../ts_web/elements/wcctools.helpers.js';
+import { html } from 'lit';
+
+const waitFor = (durationMs: number) => new Promise(resolve => setTimeout(resolve, durationMs));
+
+tap.test('resolveTemplateFactory returns sync TemplateResult', async () => {
+  const template = html`<p>sync demo</p>`;
+  const resolvedTemplate = await resolveTemplateFactory(() => template);
+  expect(resolvedTemplate).toEqual(template);
+});
+
+tap.test('resolveTemplateFactory awaits async TemplateResult', async () => {
+  const template = html`<p>async demo</p>`;
+  const resolvedTemplate = await resolveTemplateFactory(async () => {
+    await waitFor(5);
+    return template;
+  });
+  expect(resolvedTemplate).toEqual(template);
+});
+
+export default tap.start();

ts_web/elements/wcc-dashboard.ts

@@ -1,4 +1,6 @@
 import { DeesElement, property, html, customElement, type TemplateResult, queryAsync, render, domtools } from '@design.estate/dees-element';
+import { resolveTemplateFactory } from './wcctools.helpers.js';
+import type { TTemplateFactory } from './wcctools.helpers.js';
 
 import * as plugins from '../wcctools.plugins.js';
 
@@ -21,7 +23,7 @@ export class WccDashboard extends DeesElement {
   public selectedItemName: string;
 
   @property()
-  public selectedItem: (() => TemplateResult) | DeesElement;
+  public selectedItem: TTemplateFactory | DeesElement;
 
   @property()
   public selectedViewport: plugins.deesDomtools.breakpoints.TViewport = 'desktop';
@@ -33,7 +35,7 @@ export class WccDashboard extends DeesElement {
   public isFullscreen: boolean = false;
 
   @property()
-  public pages: { [key: string]: () => TemplateResult } = {};
+  public pages: Record<string, TTemplateFactory> = {};
 
   @property()
   public elements: { [key: string]: DeesElement } = {};
@@ -50,7 +52,7 @@ export class WccDashboard extends DeesElement {
 
   constructor(
     elementsArg?: { [key: string]: DeesElement },
-    pagesArg?: { [key: string]: () => TemplateResult }
+    pagesArg?: Record<string, TTemplateFactory>
   ) {
     super();
     if (elementsArg) {
@@ -201,7 +203,9 @@ export class WccDashboard extends DeesElement {
       if (typeof this.selectedItem === 'function') {
         console.log('slotting page.');
         const viewport = await wccFrame.getViewportElement();
-        render(this.selectedItem(), viewport);
+        const pageFactory = this.selectedItem as TTemplateFactory;
+        const pageTemplate = await resolveTemplateFactory(pageFactory);
+        render(pageTemplate, viewport);
         console.log('rendered page.');
       } else {
         console.error('The selected item looks strange:');
@@ -222,7 +226,8 @@ export class WccDashboard extends DeesElement {
       }
       this.setWarning(null);
       const viewport = await wccFrame.getViewportElement();
-      render(anonItem.demo(), viewport);;
+      const demoTemplate = await resolveTemplateFactory(() => anonItem.demo());
+      render(demoTemplate, viewport);
     }
   }
 

ts_web/elements/wcc-properties.ts

@@ -1,5 +1,6 @@
 import { DeesElement, property, html, customElement, type TemplateResult, state } from '@design.estate/dees-element';
 import { WccDashboard } from './wcc-dashboard.js';
+import type { TTemplateFactory } from './wcctools.helpers.js';
 
 export type TPropertyType = 'String' | 'Number' | 'Boolean' | 'Object' | 'Enum' | 'Array';
 
@@ -20,7 +21,7 @@ export class WccProperties extends DeesElement {
   public dashboardRef: WccDashboard;
 
   @property()
-  public selectedItem: (() => TemplateResult) | DeesElement;
+  public selectedItem: TTemplateFactory | DeesElement;
 
   @property()
   public selectedViewport: TEnvironment = 'native';

ts_web/elements/wcc-sidebar.ts

@@ -1,13 +1,14 @@
 import * as plugins from '../wcctools.plugins.js';
 import { DeesElement, property, html, customElement, type TemplateResult } from '@design.estate/dees-element';
 import { WccDashboard } from './wcc-dashboard.js';
+import type { TTemplateFactory } from './wcctools.helpers.js';
 
 export type TElementType = 'element' | 'page';
 
 @customElement('wcc-sidebar')
 export class WccSidebar extends DeesElement {
   @property({ attribute: false })
-  public selectedItem: DeesElement | (() => TemplateResult);
+  public selectedItem: DeesElement | TTemplateFactory;
 
   @property({ attribute: false })
   public selectedType: TElementType;
@@ -202,7 +203,7 @@ export class WccSidebar extends DeesElement {
     `;
   }
 
-  public selectItem(typeArg: TElementType, itemNameArg: string, itemArg: (() => TemplateResult) | DeesElement) {
+  public selectItem(typeArg: TElementType, itemNameArg: string, itemArg: TTemplateFactory | DeesElement) {
     console.log('selected item');
     console.log(itemNameArg);
     console.log(itemArg);

ts_web/elements/wcctools.helpers.ts

@@ -0,0 +1,9 @@
+import type { TemplateResult } from 'lit';
+
+export type TTemplateFactory = () => TemplateResult | Promise<TemplateResult>;
+
+export const resolveTemplateFactory = async (
+  factoryArg: TTemplateFactory
+): Promise<TemplateResult> => {
+  return await Promise.resolve(factoryArg());
+};

ts_web/index.ts

@@ -1,7 +1,11 @@
 import { WccDashboard } from './elements/wcc-dashboard.js';
-import { LitElement, type TemplateResult } from 'lit';
+import { LitElement } from 'lit';
+import type { TTemplateFactory } from './elements/wcctools.helpers.js';
 
-const setupWccTools = (elementsArg?: { [key: string]: LitElement }, pagesArg?: { [key: string]: () => TemplateResult }) => {
+const setupWccTools = (
+  elementsArg?: { [key: string]: LitElement },
+  pagesArg?: Record<string, TTemplateFactory>
+) => {
   let hasRun = false;
   const runWccToolsSetup = async () => {
     if (document.readyState === 'complete' && !hasRun) {