@design.estate/wcctools 5.1.0 → 6.1.0

package/ts_web/elements/wcc-dashboard.ts

@@ -1,672 +0,0 @@
-import { DeesElement, property, state, html, customElement, type TemplateResult, queryAsync, render } from '@design.estate/dees-element';
-import {
-  classifyCatalogEntry,
-  getDemoAtIndex,
-  getDemoCount,
-  getElementTagName,
-  isElementConstructor,
-  resolveTemplateFactory,
-} from './wcctools.helpers.js';
-import type { TTemplateFactory } from './wcctools.helpers.js';
-import type { IWccConfig, IWccSection, TElementType } from '../wcctools.interfaces.js';
-
-import * as plugins from '../wcctools.plugins.js';
-
-// wcc tools
-import './wcc-frame.js';
-import './wcc-sidebar.js';
-import './wcc-properties.js';
-import { type TTheme } from './wcc-properties.js';
-import { breakpoints } from '@design.estate/dees-domtools';
-import { WccFrame, type IWccEmptyState } from './wcc-frame.js';
-import { WccSidebar } from './wcc-sidebar.js';
-
-type TSectionEntry = [string, any];
-
-const applySectionFilterAndSort = (
-  section: IWccSection,
-  entries: TSectionEntry[],
-  fallbackSort?: (a: TSectionEntry, b: TSectionEntry) => number
-): TSectionEntry[] => {
-  let result = entries;
-  if (section.filter) {
-    const filterFn = section.filter;
-    result = result.filter(([name, item]) => filterFn(name, item));
-  }
-  const sortFn = section.sort ?? fallbackSort;
-  if (sortFn) {
-    result = [...result].sort(sortFn);
-  }
-  return result;
-};
-
-/**
- * The navigable entries of a section, after classification and the section's own filter and sort.
- * Elements sections keep only custom element classes with a usable static `demo`;
- * pages sections keep only template factories.
- */
-export const getSectionItems = (section: IWccSection): TSectionEntry[] => {
-  const entries = Object.entries(section.items).filter(([, item]) =>
-    section.type === 'elements'
-      ? classifyCatalogEntry(item) === 'demo'
-      : typeof item === 'function'
-  );
-  return applySectionFilterAndSort(section, entries);
-};
-
-/**
- * Registered custom elements of an elements section that have no usable demo.
- * They are listed (not navigable) in the sidebar's "Without demo" group.
- */
-export const getSectionItemsWithoutDemo = (section: IWccSection): TSectionEntry[] => {
-  if (section.type !== 'elements') {
-    return [];
-  }
-  const entries = Object.entries(section.items).filter(([, item]) => classifyCatalogEntry(item) === 'no-demo');
-  return applySectionFilterAndSort(section, entries, ([a], [b]) => a.localeCompare(b));
-};
-
-/** An addressed entry the dashboard cannot preview. */
-export interface IWccUnavailableEntry {
-  kind: 'no-demo' | 'ignored' | 'missing';
-  sectionName: string;
-  itemName: string;
-}
-
-/** Parameters of a `/wcctools-route/...` URL. */
-export interface IWccRouteParams {
-  sectionName: string;
-  itemName: string;
-  demoIndex?: string;
-  viewport: string;
-  theme: string;
-}
-
-type TResolvedEntry =
-  | { kind: 'listed'; section: IWccSection; item: unknown }
-  | { kind: IWccUnavailableEntry['kind']; section: IWccSection | null };
-
-interface IRenderedSelection {
-  item: unknown;
-  demoIndex: number;
-  type: TElementType;
-  unavailable: IWccUnavailableEntry | null;
-}
-
-@customElement('wcc-dashboard')
-export class WccDashboard extends DeesElement {
-
-  @property()
-  accessor sections: IWccSection[] = [];
-
-  @property()
-  accessor selectedSection: IWccSection | null = null;
-
-  @property()
-  accessor selectedType: TElementType = 'element';
-
-  @property()
-  accessor selectedItemName: string = '';
-
-  @property()
-  accessor selectedItem: TTemplateFactory | DeesElement | null = null;
-
-  @property({ type: Number })
-  accessor selectedDemoIndex: number = 0;
-
-  @property()
-  accessor selectedViewport: plugins.deesDomtools.breakpoints.TViewport = 'desktop';
-
-  @property()
-  accessor selectedTheme: TTheme = 'dark';
-
-  @property()
-  accessor searchQuery: string = '';
-
-  // Pinned items as Set of "sectionName::itemName"
-  @property({ attribute: false })
-  accessor pinnedItems: Set<string> = new Set();
-
-  // Sidebar width (resizable)
-  @property({ type: Number })
-  accessor sidebarWidth: number = 200;
-
-  /** Set when the route addresses an entry that cannot be previewed. */
-  @state()
-  accessor unavailableEntry: IWccUnavailableEntry | null = null;
-
-  /** What the frame shows instead of a demo, if anything. */
-  @state()
-  accessor emptyState: IWccEmptyState | null = null;
-
-  // Derived from selectedViewport - no need for separate property
-  public get isNative(): boolean {
-    return this.selectedViewport === 'native';
-  }
-
-  private frameScrollY: number = 0;
-  private sidebarScrollY: number = 0;
-  private scrollPositionsApplied: boolean = false;
-
-  private renderedSelection: IRenderedSelection | null = null;
-  private renderGeneration = 0;
-  private routeDisposers: Array<() => void> = [];
-  private scrollDisposers: Array<() => void> = [];
-  private scrollSetupTimeout: ReturnType<typeof setTimeout> | undefined;
-  private routeSettleTimeout: ReturnType<typeof setTimeout> | undefined;
-  private scrollUpdateTimeout: ReturnType<typeof setTimeout> | undefined;
-
-  @queryAsync('wcc-frame')
-  accessor wccFrame: Promise<WccFrame>;
-
-  constructor(config?: IWccConfig) {
-    super();
-    if (config && config.sections) {
-      this.sections = config.sections;
-    }
-  }
-
-  /**
-   * Find a listed item by name across all sections, returns the item and its section
-   */
-  public findItemByName(name: string): { item: any; section: IWccSection } | null {
-    for (const section of this.sections) {
-      const found = getSectionItems(section).find(([itemName]) => itemName === name);
-      if (found) {
-        return { item: found[1], section };
-      }
-    }
-    return null;
-  }
-
-  /**
-   * Find a section by name (URL-decoded)
-   */
-  public findSectionByName(name: string): IWccSection | null {
-    return this.sections.find(s => s.name === name) || null;
-  }
-
-  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: wccDashboard;
-        }
-        :host([hidden]) {
-          display: none;
-        }
-      </style>
-      <wcc-sidebar
-        .dashboardRef=${this}
-        .selectedItem=${this.selectedItem}
-        .searchQuery=${this.searchQuery}
-        .pinnedItems=${this.pinnedItems}
-        .sidebarWidth=${this.sidebarWidth}
-        .isNative=${this.isNative}
-        @selectedType=${(eventArg) => {
-          this.selectedType = eventArg.detail;
-        }}
-        @selectedItemName=${(eventArg) => {
-          this.selectedItemName = eventArg.detail;
-        }}
-        @selectedItem=${(eventArg) => {
-          this.unavailableEntry = null;
-          this.selectedItem = eventArg.detail;
-        }}
-        @searchChanged=${(eventArg: CustomEvent) => {
-          this.searchQuery = eventArg.detail;
-          this.updateUrlWithScrollState();
-        }}
-        @pinnedChanged=${(eventArg: CustomEvent) => {
-          this.pinnedItems = eventArg.detail;
-          this.updateUrlWithScrollState();
-        }}
-        @widthChanged=${async (eventArg: CustomEvent) => {
-          this.sidebarWidth = eventArg.detail;
-          this.updateUrlWithScrollState();
-          const frame = await this.wccFrame;
-          if (frame) {
-            frame.sidebarWidth = eventArg.detail;
-            frame.requestUpdate();
-          }
-        }}
-      ></wcc-sidebar>
-      <wcc-properties
-        role="region"
-        aria-label="Properties and preview controls"
-        .dashboardRef=${this}
-        .selectedItem=${this.selectedItem}
-        .selectedViewport=${this.selectedViewport}
-        .selectedTheme=${this.selectedTheme}
-        .isNative=${this.isNative}
-        .sidebarWidth=${this.sidebarWidth}
-        @selectedViewport=${(eventArg) => {
-          this.selectedViewport = eventArg.detail;
-        }}
-        @selectedTheme=${(eventArg) => {
-          this.selectedTheme = eventArg.detail;
-        }}
-        @editorStateChanged=${async (eventArg) => {
-          const frame = await this.wccFrame;
-          if (frame) {
-            frame.advancedEditorOpen = eventArg.detail.isOpen;
-            frame.requestUpdate();
-          }
-        }}
-        @toggleNative=${() => {
-          this.toggleNative();
-        }}
-      ></wcc-properties>
-      <wcc-frame
-        id="wccFrame"
-        role="main"
-        aria-label="Preview"
-        viewport=${this.selectedViewport}
-        .isNative=${this.isNative}
-        .sidebarWidth=${this.sidebarWidth}
-        .emptyState=${this.emptyState}
-      >
-      </wcc-frame>
-    `;
-  }
-
-  public toggleNative() {
-    // Toggle between 'native' and 'desktop' viewports
-    this.selectedViewport = this.selectedViewport === 'native' ? 'desktop' : 'native';
-    this.buildUrl();
-  }
-
-  private handleDocumentKeydown = (event: KeyboardEvent) => {
-    if (event.key === 'Escape' && this.isNative) {
-      this.selectedViewport = 'desktop';
-      this.buildUrl();
-    }
-  };
-
-  public async connectedCallback() {
-    const connected = super.connectedCallback();
-    document.addEventListener('keydown', this.handleDocumentKeydown);
-    // On a reconnect firstUpdated does not run again
-    if (this.hasUpdated) {
-      this.scheduleScrollListeners();
-    }
-    await this.connectRoutes();
-    return connected;
-  }
-
-  public async disconnectedCallback() {
-    const disconnected = super.disconnectedCallback();
-    document.removeEventListener('keydown', this.handleDocumentKeydown);
-    for (const dispose of this.routeDisposers) {
-      dispose();
-    }
-    this.routeDisposers = [];
-    for (const dispose of this.scrollDisposers) {
-      dispose();
-    }
-    this.scrollDisposers = [];
-    clearTimeout(this.scrollSetupTimeout);
-    clearTimeout(this.routeSettleTimeout);
-    clearTimeout(this.scrollUpdateTimeout);
-    return disconnected;
-  }
-
-  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;
-      await 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();
-  }
-
-  public async firstUpdated() {
-    this.scheduleScrollListeners();
-  }
-
-  private scheduleScrollListeners() {
-    // Set up scroll listeners after DOM is ready
-    clearTimeout(this.scrollSetupTimeout);
-    this.scrollSetupTimeout = setTimeout(() => {
-      this.setupScrollListeners();
-    }, 500);
-  }
-
-  /**
-   * Resolve a section/item pair to a listed entry, or to the reason it cannot be previewed.
-   * The legacy section names `element` and `page` search every section.
-   */
-  public resolveEntry(sectionNameArg: string, itemNameArg: string): TResolvedEntry {
-    const section = this.findSectionByName(sectionNameArg);
-    const isLegacyName = !section && (sectionNameArg === 'element' || sectionNameArg === 'page');
-    const candidates = section ? [section] : isLegacyName ? this.sections : [];
-
-    for (const candidate of candidates) {
-      const listed = getSectionItems(candidate).find(([name]) => name === itemNameArg);
-      if (listed) {
-        return { kind: 'listed', section: candidate, item: listed[1] };
-      }
-    }
-    for (const candidate of candidates) {
-      if (getSectionItemsWithoutDemo(candidate).some(([name]) => name === itemNameArg)) {
-        return { kind: 'no-demo', section: candidate };
-      }
-    }
-    for (const candidate of candidates) {
-      if (Object.prototype.hasOwnProperty.call(candidate.items, itemNameArg)) {
-        const item = candidate.items[itemNameArg];
-        const notDemoable = candidate.type === 'elements'
-          ? classifyCatalogEntry(item) === 'ignored'
-          : typeof item !== 'function';
-        return { kind: notDemoable ? 'ignored' : 'missing', section: candidate };
-      }
-    }
-    return { kind: 'missing', section };
-  }
-
-  /**
-   * Apply a `/wcctools-route/...` location to the dashboard state.
-   */
-  public async applyRoute(routeArg: IWccRouteParams, queryParamsArg?: Record<string, string>) {
-    const sectionName = decodeURIComponent(routeArg.sectionName);
-    const itemName = routeArg.itemName;
-    this.selectedItemName = itemName;
-    this.selectedDemoIndex = parseInt(routeArg.demoIndex ?? '0', 10) || 0;
-    this.selectedViewport = routeArg.viewport as breakpoints.TViewport;
-    this.selectedTheme = routeArg.theme as TTheme;
-
-    const resolved = this.resolveEntry(sectionName, itemName);
-    if (resolved.kind === 'listed') {
-      this.selectedSection = resolved.section;
-      this.selectedType = resolved.section.type === 'elements' ? 'element' : 'page';
-      this.selectedItem = resolved.item as TTemplateFactory | DeesElement;
-      this.unavailableEntry = null;
-    } else {
-      this.selectedSection = resolved.section;
-      this.selectedType = resolved.section?.type === 'pages' ? 'page' : 'element';
-      this.selectedItem = null;
-      this.unavailableEntry = { kind: resolved.kind, sectionName, itemName };
-    }
-
-    // Restore state from query parameters
-    const queryParams = queryParamsArg ?? {};
-    this.searchQuery = queryParams.search || '';
-    if (queryParams.frameScrollY) {
-      this.frameScrollY = parseInt(queryParams.frameScrollY, 10);
-    }
-    if (queryParams.sidebarScrollY) {
-      this.sidebarScrollY = parseInt(queryParams.sidebarScrollY, 10);
-    }
-    if (queryParams.pinned) {
-      const newPinned = new Set(queryParams.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();
-    }
-    if (queryParams.sidebarWidth) {
-      this.sidebarWidth = parseInt(queryParams.sidebarWidth, 10);
-    }
-
-    // Apply scroll positions and update frame after a short delay to ensure DOM is ready
-    clearTimeout(this.routeSettleTimeout);
-    this.routeSettleTimeout = setTimeout(async () => {
-      this.applyScrollPositions();
-      const frame = await this.wccFrame;
-      if (!this.isConnected) {
-        return;
-      }
-      if (frame) {
-        frame.sidebarWidth = this.sidebarWidth;
-        frame.requestUpdate();
-      }
-    }, 100);
-
-    const domtoolsInstance = await plugins.deesDomtools.elementBasic.setup();
-    this.selectedTheme === 'bright'
-      ? domtoolsInstance.themeManager.goBright()
-      : domtoolsInstance.themeManager.goDark();
-  }
-
-  public async updated(changedPropertiesArg: Map<string, any>) {
-    super.updated(changedPropertiesArg);
-    if (changedPropertiesArg.has('selectedItemName') && this.selectedItemName) {
-      document.title = this.selectedItemName;
-    }
-    await this.renderSelection();
-  }
-
-  /**
-   * Render the selected demo or page into the frame. Only a change of the selected item,
-   * demo index, type or unavailable entry re-renders; theme, viewport, search, pins and
-   * sidebar width leave the rendered demo (and its internal state) untouched.
-   */
-  private async renderSelection() {
-    const selection: IRenderedSelection = {
-      item: this.selectedItem,
-      demoIndex: this.selectedDemoIndex,
-      type: this.selectedType,
-      unavailable: this.unavailableEntry,
-    };
-    const previous = this.renderedSelection;
-    if (
-      previous &&
-      previous.item === selection.item &&
-      previous.demoIndex === selection.demoIndex &&
-      previous.type === selection.type &&
-      previous.unavailable === selection.unavailable
-    ) {
-      return;
-    }
-    this.renderedSelection = selection;
-    const generation = ++this.renderGeneration;
-
-    const frame = await this.wccFrame;
-    const viewport = await frame.getViewportElement();
-    if (generation !== this.renderGeneration) {
-      return;
-    }
-
-    const target = this.resolveRenderTarget();
-    if ('emptyState' in target) {
-      render(html``, viewport);
-      this.emptyState = target.emptyState;
-      return;
-    }
-
-    try {
-      const template = await resolveTemplateFactory(target.factory);
-      if (generation !== this.renderGeneration) {
-        return;
-      }
-      render(template, viewport);
-      this.emptyState = null;
-    } catch (error) {
-      if (generation !== this.renderGeneration) {
-        return;
-      }
-      console.error(`wcctools: rendering "${this.selectedItemName}" failed`, error);
-      render(html``, viewport);
-      this.emptyState = {
-        title: `${this.selectedItemName} failed to render`,
-        detail: error instanceof Error ? error.message : String(error),
-      };
-    }
-  }
-
-  private resolveRenderTarget(): { factory: TTemplateFactory } | { emptyState: IWccEmptyState } {
-    const unavailable = this.unavailableEntry;
-    if (unavailable) {
-      return { emptyState: this.getUnavailableEmptyState(unavailable) };
-    }
-    const item = this.selectedItem;
-    if (!item) {
-      return {
-        emptyState: {
-          title: 'Nothing selected',
-          detail: 'Choose an element or page in the sidebar to preview it here.',
-        },
-      };
-    }
-    if (this.selectedType === 'page') {
-      return { factory: item as TTemplateFactory };
-    }
-    const demo = isElementConstructor(item) ? item.demo : undefined;
-    const demoFactory = demo ? getDemoAtIndex(demo as TTemplateFactory | TTemplateFactory[], this.selectedDemoIndex) : null;
-    if (!demoFactory) {
-      const count = demo ? getDemoCount(demo as TTemplateFactory | TTemplateFactory[]) : 0;
-      return {
-        emptyState: {
-          title: `${this.selectedItemName} has no demo ${this.selectedDemoIndex + 1}`,
-          detail: `This element defines ${count} ${count === 1 ? 'demo' : 'demos'}.`,
-        },
-      };
-    }
-    return { factory: demoFactory };
-  }
-
-  private getUnavailableEmptyState(entryArg: IWccUnavailableEntry): IWccEmptyState {
-    switch (entryArg.kind) {
-      case 'no-demo': {
-        const section = this.findSectionByName(entryArg.sectionName);
-        const item = section?.items[entryArg.itemName]
-          ?? this.sections.map((s) => s.items[entryArg.itemName]).find((i) => i !== undefined);
-        const tagName = getElementTagName(item);
-        return {
-          title: `${entryArg.itemName} has no demo`,
-          detail: `${tagName ? `<${tagName}>` : 'This element'} is a registered custom element without a static demo. It is listed under "Without demo".`,
-        };
-      }
-      case 'ignored':
-        return {
-          title: `${entryArg.itemName} cannot be previewed`,
-          detail: 'This export is not a custom element with a demo, so the catalog does not list it.',
-        };
-      case 'missing':
-        return {
-          title: `${entryArg.itemName} was not found`,
-          detail: `No entry with this name exists in "${entryArg.sectionName}".`,
-        };
-    }
-  }
-
-  private getRouteUrl(): string {
-    const sectionName = this.selectedSection
-      ? encodeURIComponent(this.selectedSection.name)
-      : this.selectedType; // Fallback for legacy
-    const baseUrl = `/wcctools-route/${sectionName}/${this.selectedItemName}/${this.selectedDemoIndex}/${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 !== 200) {
-      queryParams.set('sidebarWidth', this.sidebarWidth.toString());
-    }
-
-    const queryString = queryParams.toString();
-    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
-  }
-
-  public buildUrl() {
-    this.domtools.router.pushUrl(this.getRouteUrl());
-  }
-
-  private handleFrameScroll = (event: Event) => {
-    this.frameScrollY = (event.currentTarget as HTMLElement).scrollTop;
-    this.debouncedScrollUpdate();
-  };
-
-  private handleSidebarScroll = (event: Event) => {
-    this.sidebarScrollY = (event.currentTarget as HTMLElement).scrollTop;
-    this.debouncedScrollUpdate();
-  };
-
-  public async setupScrollListeners() {
-    const wccFrame = await this.wccFrame;
-    // Prevent duplicate listeners and listeners on a removed dashboard
-    if (!this.isConnected || this.scrollDisposers.length > 0) {
-      return;
-    }
-    const wccSidebar = this.shadowRoot.querySelector('wcc-sidebar') as WccSidebar | null;
-
-    if (wccFrame) {
-      // The frame element itself is the scrollable container
-      wccFrame.addEventListener('scroll', this.handleFrameScroll);
-      this.scrollDisposers.push(() => wccFrame.removeEventListener('scroll', this.handleFrameScroll));
-    }
-
-    // Use the sidebar's scrollable container (.menu element)
-    const scrollContainer = wccSidebar?.scrollableContainer;
-    if (scrollContainer) {
-      scrollContainer.addEventListener('scroll', this.handleSidebarScroll);
-      this.scrollDisposers.push(() => scrollContainer.removeEventListener('scroll', this.handleSidebarScroll));
-    }
-  }
-
-  private debouncedScrollUpdate() {
-    clearTimeout(this.scrollUpdateTimeout);
-    this.scrollUpdateTimeout = setTimeout(() => {
-      this.updateUrlWithScrollState();
-    }, 300);
-  }
-
-  private updateUrlWithScrollState() {
-    // Use replaceState to update URL without navigation
-    window.history.replaceState(null, '', this.getRouteUrl());
-  }
-
-  public async applyScrollPositions() {
-    // Only apply scroll positions once to avoid interfering with user scrolling
-    if (this.scrollPositionsApplied) {
-      return;
-    }
-
-    const wccFrame = await this.wccFrame;
-    const wccSidebar = this.shadowRoot.querySelector('wcc-sidebar') as WccSidebar | null;
-
-    if (wccFrame && this.frameScrollY > 0) {
-      // The frame element itself is the scrollable container
-      wccFrame.scrollTop = this.frameScrollY;
-    }
-
-    if (wccSidebar && this.sidebarScrollY > 0) {
-      // Use the sidebar's scrollable container (.menu element)
-      const scrollContainer = wccSidebar.scrollableContainer;
-      if (scrollContainer) {
-        scrollContainer.scrollTop = this.sidebarScrollY;
-      }
-    }
-
-    this.scrollPositionsApplied = true;
-  }
-}