@design.estate/wcctools 6.1.0 → 7.0.0

package/ts_shell/elements/wcc-shell.ts

@@ -0,0 +1,485 @@
+import { DeesElement, property, state, html, customElement, type TemplateResult } from '@design.estate/dees-element';
+import * as plugins from '../plugins.js';
+import { WccPreviewConnection } from '../previewconnection.js';
+import { WccBundleStatusClient } from '../bundlestatus.js';
+import type { TWccViewport, WccPreviewFrame } from './wcc-preview-frame.js';
+import type { WccSidebar } from './wcc-sidebar.js';
+import './wcc-preview-frame.js';
+import './wcc-sidebar.js';
+import './wcc-properties.js';
+
+/** Parameters of a `/wcctools-route/...` URL. */
+export interface IWccShellRouteParams {
+  sectionName: string;
+  itemName: string;
+  demoIndex?: string;
+  viewport: string;
+  theme: string;
+}
+
+const viewports: TWccViewport[] = ['native', 'desktop', 'tablet', 'phablet', 'phone'];
+const defaultSidebarWidth = 200;
+
+const selectionKey = (selectionArg: plugins.interfaces.IWccSelection | null): string | null =>
+  selectionArg ? `${selectionArg.sectionName}::${selectionArg.itemName}::${selectionArg.demoIndex}` : null;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'wcc-shell': WccShell;
+  }
+}
+
+/**
+ * The wcctools UI: catalog sidebar, properties and preview controls, and the preview frame
+ * that shows the catalog's own document. The shell owns the `/wcctools-route/...` URL and
+ * drives the preview through its bridge; a reloaded preview reconnects without the shell
+ * reloading.
+ */
+@customElement('wcc-shell')
+export class WccShell extends DeesElement {
+  /** The path the server serves the preview document on. */
+  @property({ attribute: 'preview-path' })
+  accessor previewPath: string = plugins.shared.previewRoutePath;
+
+  /**
+   * The dev server's typed API. With it, the shell follows the bundle status and shows a failed
+   * catalog bundle over the preview; without it (the shell outside `wcctools dev`), it does not.
+   * Read when the shell connects.
+   */
+  @property({ attribute: 'api-path' })
+  accessor apiPath: string = '';
+
+  @property({ attribute: false })
+  accessor selection: plugins.interfaces.IWccSelection | null = null;
+
+  @property()
+  accessor selectedViewport: TWccViewport = 'desktop';
+
+  @property()
+  accessor selectedTheme: plugins.interfaces.TWccTheme = 'dark';
+
+  @property()
+  accessor searchQuery: string = '';
+
+  // Pinned items as Set of "sectionName::itemName"
+  @property({ attribute: false })
+  accessor pinnedItems: Set<string> = new Set();
+
+  @property({ type: Number })
+  accessor sidebarWidth: number = defaultSidebarWidth;
+
+  /** The catalog as the connected preview describes it; kept while the preview reloads. */
+  @state()
+  accessor manifest: plugins.interfaces.IWccCatalogManifest | null = null;
+
+  /** The connected preview's bridge; null while the preview loads. */
+  @state()
+  accessor bridge: plugins.interfaces.IWccPreviewBridge | null = null;
+
+  /** Counts the renders of the preview, so the properties panel reads them. */
+  @state()
+  accessor renderCount: number = 0;
+
+  @state()
+  accessor previewSrc: string = '';
+
+  @state()
+  accessor advancedEditorOpen: boolean = false;
+
+  @state()
+  accessor isResizing: boolean = false;
+
+  @state()
+  accessor captureTarget: HTMLElement | null = null;
+
+  /** The catalog bundles whose latest completed run failed, as the dev server reports them. */
+  @state()
+  accessor bundleFailures: plugins.interfaces.IWccBundleStatus[] = [];
+
+  public get isNative(): boolean {
+    return this.selectedViewport === 'native';
+  }
+
+  private frameScrollY: number = 0;
+  private sidebarScrollY: number = 0;
+  private scrollPositionsRestored: boolean = false;
+  /** The selection the preview shows, as far as the shell asked it to. */
+  private previewSelectionKey: string | null = null;
+
+  private connection = new WccPreviewConnection(
+    () => this.shadowRoot?.querySelector<WccPreviewFrame>('wcc-preview-frame')?.iframe ?? null,
+    {
+      onReady: (bridgeArg) => {
+        this.handlePreviewReady(bridgeArg).catch((error) => {
+          console.error('wcctools: connecting the preview failed', error);
+        });
+      },
+      onDisconnect: () => {
+        this.bridge = null;
+      },
+      onEscape: () => this.leaveNative(),
+      onScroll: (scrollYArg) => {
+        this.frameScrollY = scrollYArg;
+        this.debouncedScrollUpdate();
+      },
+    },
+  );
+  private bundleStatusClient: WccBundleStatusClient | null = null;
+  private routeDisposers: Array<() => void> = [];
+  private scrollDisposers: Array<() => void> = [];
+  private scrollUpdateTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  public render(): TemplateResult {
+    return html`
+      <style>
+        :host {
+          background: #fcfcfc;
+          display: block;
+          box-sizing: border-box;
+          position: fixed;
+          inset: 0;
+          min-width: 0;
+          overflow: hidden;
+          container-type: inline-size;
+          container-name: wccShell;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <wcc-sidebar
+        .manifest=${this.manifest}
+        .selection=${this.selection}
+        .searchQuery=${this.searchQuery}
+        .pinnedItems=${this.pinnedItems}
+        .sidebarWidth=${this.sidebarWidth}
+        .isNative=${this.isNative}
+        @selectionChanged=${(eventArg: CustomEvent<plugins.interfaces.IWccSelection>) => {
+          this.selection = eventArg.detail;
+          this.buildUrl();
+        }}
+        @searchChanged=${(eventArg: CustomEvent<string>) => {
+          this.searchQuery = eventArg.detail;
+          this.updateUrlWithScrollState();
+        }}
+        @pinnedChanged=${(eventArg: CustomEvent<Set<string>>) => {
+          this.pinnedItems = eventArg.detail;
+          this.updateUrlWithScrollState();
+        }}
+        @widthChanged=${(eventArg: CustomEvent<number>) => {
+          this.sidebarWidth = eventArg.detail;
+        }}
+        @widthCommitted=${() => this.updateUrlWithScrollState()}
+        @resizingChanged=${(eventArg: CustomEvent<boolean>) => {
+          this.isResizing = eventArg.detail;
+        }}
+      ></wcc-sidebar>
+      <wcc-properties
+        role="region"
+        aria-label="Properties and preview controls"
+        .bridge=${this.bridge}
+        .renderCount=${this.renderCount}
+        .captureTarget=${this.captureTarget}
+        .selectedViewport=${this.selectedViewport}
+        .selectedTheme=${this.selectedTheme}
+        .isNative=${this.isNative}
+        .sidebarWidth=${this.sidebarWidth}
+        @selectedViewport=${(eventArg: CustomEvent<TWccViewport>) => {
+          this.selectedViewport = eventArg.detail;
+          this.buildUrl();
+        }}
+        @selectedTheme=${(eventArg: CustomEvent<plugins.interfaces.TWccTheme>) => {
+          this.selectedTheme = eventArg.detail;
+          this.buildUrl();
+        }}
+        @editorStateChanged=${(eventArg: CustomEvent<{ isOpen: boolean }>) => {
+          this.advancedEditorOpen = eventArg.detail.isOpen;
+        }}
+      ></wcc-properties>
+      <wcc-preview-frame
+        role="main"
+        aria-label="Preview"
+        .viewport=${this.selectedViewport}
+        .previewSrc=${this.previewSrc}
+        .isNative=${this.isNative}
+        .sidebarWidth=${this.sidebarWidth}
+        .advancedEditorOpen=${this.advancedEditorOpen}
+        .isResizing=${this.isResizing}
+        .bundleFailures=${this.bundleFailures}
+      ></wcc-preview-frame>
+    `;
+  }
+
+  private leaveNative() {
+    if (this.isNative) {
+      this.selectedViewport = 'desktop';
+      this.buildUrl();
+    }
+  }
+
+  private handleDocumentKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      this.leaveNative();
+    }
+  };
+
+  public async connectedCallback() {
+    const connected = super.connectedCallback();
+    document.addEventListener('keydown', this.handleDocumentKeydown);
+    this.connection.start();
+    this.startBundleStatus();
+    if (this.hasUpdated) {
+      await this.setupSidebarScrollListener();
+    }
+    await this.connectRoutes();
+    return connected;
+  }
+
+  public async disconnectedCallback() {
+    const disconnected = super.disconnectedCallback();
+    document.removeEventListener('keydown', this.handleDocumentKeydown);
+    this.connection.dispose();
+    this.bundleStatusClient?.dispose();
+    this.bundleStatusClient = null;
+    this.bridge = null;
+    for (const dispose of this.routeDisposers) {
+      dispose();
+    }
+    this.routeDisposers = [];
+    this.releaseScrollListeners();
+    clearTimeout(this.scrollUpdateTimeout);
+    return disconnected;
+  }
+
+  private startBundleStatus() {
+    if (!this.apiPath || this.bundleStatusClient) {
+      return;
+    }
+    this.bundleStatusClient = new WccBundleStatusClient(this.apiPath, (snapshotArg) => this.applyBundleStatus(snapshotArg));
+    this.bundleStatusClient.start();
+  }
+
+  /**
+   * Apply the dev server's bundle status: a bundle whose latest completed run failed is shown
+   * over the preview until a run of it finishes, which also reloads the preview.
+   */
+  public applyBundleStatus(snapshotArg: plugins.interfaces.IWccBundleStatusSnapshot) {
+    this.bundleFailures = snapshotArg.bundles.filter((bundleArg) => bundleArg.errorMessage !== undefined);
+  }
+
+  public async firstUpdated() {
+    await this.setupSidebarScrollListener();
+  }
+
+  private async connectRoutes() {
+    const domtools = await this.domtoolsPromise;
+    if (!this.isConnected || this.routeDisposers.length > 0) {
+      return;
+    }
+    this.domtools = domtools;
+    const handleRoute = async (routeInfo: { params: Record<string, string>; queryParams: Record<string, string> }) => {
+      const { sectionName, itemName, demoIndex, viewport, theme } = routeInfo.params;
+      this.applyRoute({ sectionName, itemName, demoIndex, viewport, theme }, routeInfo.queryParams);
+    };
+    this.routeDisposers = [
+      domtools.router.on('/wcctools-route/:sectionName/:itemName/:demoIndex/:viewport/:theme', handleRoute),
+      // Route without demo index (kept for existing links)
+      domtools.router.on('/wcctools-route/:sectionName/:itemName/:viewport/:theme', handleRoute),
+    ];
+    await domtools.router._handleRouteState();
+    if (this.isConnected && !this.previewSrc) {
+      // Loaded once: later selections render through the bridge without reloading the preview
+      this.previewSrc = `${this.previewPath}${plugins.shared.formatPreviewQuery({ selection: this.selection, theme: this.selectedTheme })}`;
+    }
+  }
+
+  /**
+   * Apply a `/wcctools-route/...` location to the shell state.
+   */
+  public applyRoute(routeArg: IWccShellRouteParams, queryParamsArg: Record<string, string> = {}) {
+    this.selection = {
+      sectionName: decodeURIComponent(routeArg.sectionName),
+      itemName: routeArg.itemName,
+      demoIndex: parseInt(routeArg.demoIndex ?? '0', 10) || 0,
+    };
+    this.selectedViewport = viewports.includes(routeArg.viewport as TWccViewport)
+      ? routeArg.viewport as TWccViewport
+      : 'desktop';
+    this.selectedTheme = routeArg.theme === 'bright' ? 'bright' : 'dark';
+
+    // Restore state from query parameters
+    this.searchQuery = queryParamsArg.search || '';
+    if (queryParamsArg.frameScrollY) {
+      this.frameScrollY = parseInt(queryParamsArg.frameScrollY, 10);
+    }
+    if (queryParamsArg.sidebarScrollY) {
+      this.sidebarScrollY = parseInt(queryParamsArg.sidebarScrollY, 10);
+    }
+    if (queryParamsArg.pinned) {
+      const newPinned = new Set(queryParamsArg.pinned.split(',').filter(Boolean));
+      // Only update if actually different to avoid update loops
+      if (this.pinnedItems.size !== newPinned.size ||
+          ![...newPinned].every(k => this.pinnedItems.has(k))) {
+        this.pinnedItems = newPinned;
+      }
+    } else if (this.pinnedItems.size > 0) {
+      this.pinnedItems = new Set();
+    }
+    this.sidebarWidth = queryParamsArg.sidebarWidth
+      ? parseInt(queryParamsArg.sidebarWidth, 10)
+      : defaultSidebarWidth;
+  }
+
+  public async updated(changedPropertiesArg: Map<string, unknown>) {
+    super.updated(changedPropertiesArg);
+    if (changedPropertiesArg.has('selection') && this.selection) {
+      document.title = this.selection.itemName;
+    }
+    if (changedPropertiesArg.has('selectedTheme')) {
+      await this.applyTheme();
+    }
+    if (changedPropertiesArg.has('selection')) {
+      await this.renderSelectionInPreview();
+    }
+  }
+
+  /** The shell's own elements and the preview follow the selected theme. */
+  private async applyTheme() {
+    const theme = this.selectedTheme;
+    const domtools = await plugins.deesDomtools.elementBasic.setup();
+    theme === 'bright' ? domtools.themeManager.goBright() : domtools.themeManager.goDark();
+    if (this.bridge && this.bridge.getTheme() !== theme) {
+      await this.bridge.setTheme(theme);
+    }
+  }
+
+  /**
+   * Render the selection in the preview. Only a change of the selected entry or demo
+   * re-renders; theme, viewport, search, pins and sidebar width leave the rendered demo
+   * (and its internal state) untouched.
+   */
+  private async renderSelectionInPreview() {
+    const bridge = this.bridge;
+    const key = selectionKey(this.selection);
+    if (!bridge || !this.selection || key === this.previewSelectionKey) {
+      return;
+    }
+    this.previewSelectionKey = key;
+    await bridge.render(this.selection);
+    if (this.bridge === bridge) {
+      this.renderCount++;
+    }
+  }
+
+  /** A preview document is ready: read its catalog and bring it to the shell's state. */
+  private async handlePreviewReady(bridgeArg: plugins.interfaces.IWccPreviewBridge) {
+    this.bridge = bridgeArg;
+    this.manifest = bridgeArg.getManifest();
+    this.captureTarget = this.shadowRoot?.querySelector<WccPreviewFrame>('wcc-preview-frame')?.iframe ?? null;
+    if (bridgeArg.getTheme() !== this.selectedTheme) {
+      await bridgeArg.setTheme(this.selectedTheme);
+    }
+    // A reloaded preview restores what it showed from its own URL
+    this.previewSelectionKey = selectionKey(bridgeArg.getSelection());
+    await this.renderSelectionInPreview();
+    if (this.bridge !== bridgeArg) {
+      return;
+    }
+    this.renderCount++;
+    await this.restoreScrollPositions();
+  }
+
+  /** Scroll the sidebar and the preview to the positions of the loaded URL, once. */
+  private async restoreScrollPositions() {
+    if (this.scrollPositionsRestored) {
+      return;
+    }
+    this.scrollPositionsRestored = true;
+    const sidebar = this.shadowRoot?.querySelector<WccSidebar>('wcc-sidebar');
+    await this.updateComplete;
+    await sidebar?.updateComplete;
+    if (sidebar?.scrollableContainer && this.sidebarScrollY > 0) {
+      sidebar.scrollableContainer.scrollTop = this.sidebarScrollY;
+    }
+    if (this.frameScrollY > 0) {
+      this.connection.scrollPreviewTo(this.frameScrollY);
+    }
+  }
+
+  private getRouteUrl(): string | null {
+    if (!this.selection) {
+      return null;
+    }
+    const sectionName = encodeURIComponent(this.selection.sectionName);
+    const baseUrl = `/wcctools-route/${sectionName}/${this.selection.itemName}/${this.selection.demoIndex}/${this.selectedViewport}/${this.selectedTheme}`;
+    const queryParams = new URLSearchParams();
+
+    if (this.searchQuery) {
+      queryParams.set('search', this.searchQuery);
+    }
+    if (this.frameScrollY > 0) {
+      queryParams.set('frameScrollY', this.frameScrollY.toString());
+    }
+    if (this.sidebarScrollY > 0) {
+      queryParams.set('sidebarScrollY', this.sidebarScrollY.toString());
+    }
+    if (this.pinnedItems.size > 0) {
+      queryParams.set('pinned', Array.from(this.pinnedItems).join(','));
+    }
+    if (this.sidebarWidth !== defaultSidebarWidth) {
+      queryParams.set('sidebarWidth', this.sidebarWidth.toString());
+    }
+
+    const queryString = queryParams.toString();
+    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+  }
+
+  /** Push the current state as a new history entry; without a selection there is no route to push. */
+  public buildUrl() {
+    const url = this.getRouteUrl();
+    if (url && this.domtools) {
+      this.domtools.router.pushUrl(url);
+    }
+  }
+
+  private updateUrlWithScrollState() {
+    const url = this.getRouteUrl();
+    if (url) {
+      // Use replaceState to update URL without navigation
+      window.history.replaceState(null, '', url);
+    }
+  }
+
+  private handleSidebarScroll = (event: Event) => {
+    this.sidebarScrollY = (event.currentTarget as HTMLElement).scrollTop;
+    this.debouncedScrollUpdate();
+  };
+
+  private async setupSidebarScrollListener() {
+    const sidebar = this.shadowRoot?.querySelector<WccSidebar>('wcc-sidebar');
+    await sidebar?.updateComplete;
+    // Prevent duplicate listeners and listeners on a removed shell
+    if (!this.isConnected || this.scrollDisposers.length > 0) {
+      return;
+    }
+    const scrollContainer = sidebar?.scrollableContainer;
+    if (scrollContainer) {
+      scrollContainer.addEventListener('scroll', this.handleSidebarScroll);
+      this.scrollDisposers.push(() => scrollContainer.removeEventListener('scroll', this.handleSidebarScroll));
+    }
+  }
+
+  private releaseScrollListeners() {
+    for (const dispose of this.scrollDisposers) {
+      dispose();
+    }
+    this.scrollDisposers = [];
+  }
+
+  private debouncedScrollUpdate() {
+    clearTimeout(this.scrollUpdateTimeout);
+    this.scrollUpdateTimeout = setTimeout(() => {
+      this.updateUrlWithScrollState();
+    }, 300);
+  }
+}