v3.7.1

changelog.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 2026-01-04 - 3.7.1 - fix(sidebar)
+increase scrolled sidebar header box-shadow intensity and size to improve visual separation
+
+- Changed .sidebar-header.scrolled box-shadow from `0 4px 12px -2px rgba(0, 0, 0, 0.4)` to `0 8px 24px -2px rgba(0, 0, 0, 1)`
+- File modified: ts_web/elements/wcc-sidebar.ts — stronger, larger, and fully opaque shadow for better contrast when scrolled
+
+## 2026-01-04 - 3.7.0 - feat(wcc-sidebar)
+add header shadow and scrolled state for sidebar menu to show elevation when content is scrolled
+
+- Introduce isMenuScrolled state to track whether the menu has been scrolled
+- Add handleMenuScroll handler and bind it to the menu scroll event
+- Apply a 'scrolled' class to .sidebar-header to add box-shadow and border-bottom color with transitions
+- Update template to conditionally add scrolled class and attach scroll listener
+
+## 2026-01-04 - 3.6.2 - fix(wcc-sidebar)
+use sidebar's internal .menu element for scroll management and expose scrollableContainer getter
+
+- Add public scrollableContainer getter to wcc-sidebar that returns the .menu element for external scroll control
+- Update wcc-dashboard to query wcc-sidebar as WccSidebar and attach scroll listeners to sidebar.scrollableContainer instead of the host element
+- Restore sidebar scroll position by setting scrollTop on the scrollableContainer when applying saved positions
+- TypeScript casting added to avoid nullable/implicit any issues when querying the sidebar element
+
+## 2026-01-04 - 3.6.1 - fix(wcc-sidebar)
+sort sidebar items alphabetically and unify grouped and ungrouped items for consistent ordering
+
+- Unifies ungrouped elements and groups into a single render list using a RenderItem type with a sortKey.
+- Sorts all top-level items alphabetically by element name (case-insensitive via toLowerCase) so sidebar order is deterministic.
+- Groups are ordered by the first element's name; individual items inside a group preserve their original order.
+- Replaces previous separate rendering paths with a single sorted render pass that returns TemplateResult array.
+
+## 2026-01-04 - 3.6.0 - feat(sidebar)
+restructure sidebar layout, add search clear button, and improve scrolling behavior
+
+- Change sidebar root to a flex column layout and add a .sidebar-header to separate header content from the scrollable menu
+- Move pinned section into the header and make .menu flex: 1 with min-height: 0 so the menu becomes the scrollable area
+- Replace overflow-y on the root with overflow:hidden to avoid double scrolling and constrain scrolling to .menu
+- Add a clear button for the search input (.search-clear) with positioning, hover styles, and a clearSearch() method to reset the query and emit searchChanged
+- Adjust search input padding and make .search-container position: relative to correctly position the clear button
+
+## 2026-01-04 - 3.5.3 - fix(deps)
+bump dependency versions: @design.estate/dees-domtools to ^2.3.7, @design.estate/dees-element to ^2.1.5, lit to ^3.3.2; update devDependencies @api.global/typedserver to ^8.1.0 and @git.zone/tstest to ^3.1.4
+
+- Updated runtime dependencies: @design.estate/dees-domtools ^2.3.7, @design.estate/dees-element ^2.1.5, lit ^3.3.2.
+- Updated devDependencies: @api.global/typedserver ^8.1.0 (major bump), @git.zone/tstest ^3.1.4.
+- @api.global/typedserver major bump affects development tooling only (devDependency), not runtime API.
+- Current package version is 3.5.2; recommend a patch release to 3.5.3.
+
+## 2026-01-04 - 3.5.2 - fix(elements)
+delay hiding sidebar and properties panels during native-mode transition and use transparent rgba border for frame to avoid layout jumps
+
+- Add isHidden state to wcc-sidebar and wcc-properties and switch display bindings to use isHidden instead of directly using isNative
+- Introduce a 300ms delayed hide when entering native mode so UI hides after frame animation completes; show immediately when exiting native mode
+- Replace hardcoded hex border values in wcc-frame with rgba and set native border to a transparent 0px to prevent abrupt visual jumps
+
 ## 2026-01-04 - 3.5.1 - fix(sidebar)
 disable frame CSS transition while user is resizing the sidebar to prevent janky animations
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-wcctools",
-  "version": "3.5.1",
+  "version": "3.7.1",
   "private": false,
   "description": "A set of web component tools for creating element catalogues, enabling the structured development and documentation of custom elements and pages.",
   "exports": {
@@ -17,17 +17,17 @@
   "author": "Lossless GmbH",
   "license": "UNLICENSED",
   "dependencies": {
-    "@design.estate/dees-domtools": "^2.3.6",
-    "@design.estate/dees-element": "^2.1.3",
+    "@design.estate/dees-domtools": "^2.3.7",
+    "@design.estate/dees-element": "^2.1.5",
     "@push.rocks/smartdelay": "^3.0.5",
-    "lit": "^3.3.1"
+    "lit": "^3.3.2"
   },
   "devDependencies": {
-    "@api.global/typedserver": "^7.11.1",
+    "@api.global/typedserver": "^8.1.0",
     "@git.zone/tsbuild": "^4.0.2",
     "@git.zone/tsbundle": "^2.6.3",
     "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^3.1.3",
+    "@git.zone/tstest": "^3.1.4",
     "@git.zone/tswatch": "^2.3.13",
     "@push.rocks/projectinfo": "^5.0.2",
     "@types/node": "^25.0.3"

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-wcctools',
-  version: '3.5.1',
+  version: '3.7.1',
   description: 'A set of web component tools for creating element catalogues, enabling the structured development and documentation of custom elements and pages.'
 }

ts_web/elements/wcc-dashboard.ts

@@ -12,6 +12,7 @@ import './wcc-properties.js';
 import { type TTheme } from './wcc-properties.js';
 import { breakpoints } from '@design.estate/dees-domtools';
 import { WccFrame } from './wcc-frame.js';
+import { WccSidebar } from './wcc-sidebar.js';
 
 /**
  * Get filtered and sorted items from a section
@@ -493,7 +494,7 @@ export class WccDashboard extends DeesElement {
     }
 
     const wccFrame = await this.wccFrame;
-    const wccSidebar = this.shadowRoot.querySelector('wcc-sidebar');
+    const wccSidebar = this.shadowRoot.querySelector('wcc-sidebar') as WccSidebar | null;
 
     if (wccFrame) {
       // The frame element itself is the scrollable container
@@ -505,11 +506,14 @@ export class WccDashboard extends DeesElement {
     }
     
     if (wccSidebar) {
-      // The sidebar element itself is the scrollable container
-      wccSidebar.addEventListener('scroll', () => {
-        this.sidebarScrollY = wccSidebar.scrollTop;
-        this.debouncedScrollUpdate();
-      });
+      // Use the sidebar's scrollable container (.menu element)
+      const scrollContainer = wccSidebar.scrollableContainer;
+      if (scrollContainer) {
+        scrollContainer.addEventListener('scroll', () => {
+          this.sidebarScrollY = scrollContainer.scrollTop;
+          this.debouncedScrollUpdate();
+        });
+      }
     }
   }
   
@@ -557,7 +561,7 @@ export class WccDashboard extends DeesElement {
     }
 
     const wccFrame = await this.wccFrame;
-    const wccSidebar = this.shadowRoot.querySelector('wcc-sidebar');
+    const wccSidebar = this.shadowRoot.querySelector('wcc-sidebar') as WccSidebar | null;
 
     if (wccFrame && this.frameScrollY > 0) {
       // The frame element itself is the scrollable container
@@ -565,8 +569,11 @@ export class WccDashboard extends DeesElement {
     }
     
     if (wccSidebar && this.sidebarScrollY > 0) {
-      // The sidebar element itself is the scrollable container
-      wccSidebar.scrollTop = this.sidebarScrollY;
+      // Use the sidebar's scrollable container (.menu element)
+      const scrollContainer = wccSidebar.scrollableContainer;
+      if (scrollContainer) {
+        scrollContainer.scrollTop = this.sidebarScrollY;
+      }
     }
     
     this.scrollPositionsApplied = true;

ts_web/elements/wcc-frame.ts

@@ -28,7 +28,7 @@ export class WccFrame extends DeesElement {
   public static styles = [
     css`
       :host {
-        border: 10px solid #ffaeaf;
+        border: 10px solid rgba(255, 174, 175, 1);
         position: absolute;
         background: ${cssManager.bdTheme('#333', '#000')};
         right: 0px;
@@ -52,14 +52,14 @@ export class WccFrame extends DeesElement {
       <style>
         :host {
           ${this.isNative ? `
-            border: none !important;
+            border: 0px solid rgba(255, 174, 175, 0) !important;
             left: 0px !important;
             right: 0px !important;
             top: 0px !important;
             bottom: 0px !important;
           ` : `
             bottom: ${this.advancedEditorOpen ? '400px' : '100px'};
-            border: 10px solid #ffaeaf;
+            border: 10px solid rgba(255, 174, 175, 1);
             left: ${this.sidebarWidth}px;
           `}
           transition: ${this.isResizing ? 'none' : 'all 0.3s ease'};

ts_web/elements/wcc-properties.ts

@@ -63,6 +63,10 @@ export class WccProperties extends DeesElement {
   @state()
   accessor recordingDuration: number = 0;
 
+  // Delayed hide for native mode transition
+  @state()
+  accessor isHidden: boolean = false;
+
   public editorHeight: number = 300;
 
   public render(): TemplateResult {
@@ -99,7 +103,7 @@ export class WccProperties extends DeesElement {
           overflow: hidden;
           background: var(--background);
           color: var(--foreground);
-          display: ${this.isNative ? 'none' : 'block'};
+          display: ${this.isHidden ? 'none' : 'block'};
         }
         .grid {
           display: grid;
@@ -931,6 +935,19 @@ export class WccProperties extends DeesElement {
   protected updated(changedProperties: Map<string, unknown>) {
     super.updated(changedProperties);
 
+    // Handle delayed hide for native mode transition
+    if (changedProperties.has('isNative')) {
+      if (this.isNative) {
+        // Delay hiding until frame animation completes
+        setTimeout(() => {
+          this.isHidden = true;
+        }, 300);
+      } else {
+        // Show immediately when exiting native mode
+        this.isHidden = false;
+      }
+    }
+
     // Only recreate properties when selectedItem changes
     if (changedProperties.has('selectedItem')) {
       this.createProperties().catch(error => {

ts_web/elements/wcc-sidebar.ts

@@ -44,8 +44,23 @@ export class WccSidebar extends DeesElement {
   @state()
   accessor isResizing: boolean = false;
 
+  // Delayed hide for native mode transition
+  @state()
+  accessor isHidden: boolean = false;
+
+  // Track if menu is scrolled for header shadow
+  @state()
+  accessor isMenuScrolled: boolean = false;
+
   private sectionsInitialized = false;
 
+  /**
+   * Returns the scrollable container element (.menu) for external scroll management
+   */
+  public get scrollableContainer(): HTMLElement | null {
+    return this.shadowRoot?.querySelector('.menu') as HTMLElement | null;
+  }
+
   public render(): TemplateResult {
     return html`
       <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" rel="stylesheet" />
@@ -67,7 +82,8 @@ export class WccSidebar extends DeesElement {
           --ring: #3b82f6;
           --radius: 4px;
 
-          display: ${this.isNative ? 'none' : 'block'};
+          display: ${this.isHidden ? 'none' : 'flex'};
+          flex-direction: column;
           border-right: 1px solid rgba(255, 255, 255, 0.08);
           font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
           font-size: 14px;
@@ -77,13 +93,29 @@ export class WccSidebar extends DeesElement {
           width: ${this.sidebarWidth}px;
           top: 0px;
           bottom: 0px;
-          overflow-y: auto;
-          overflow-x: hidden;
+          overflow: hidden;
           background: var(--background);
           color: var(--foreground);
         }
 
+        .sidebar-header {
+          flex-shrink: 0;
+          transition: box-shadow 0.2s ease, border-color 0.2s ease;
+          border-bottom: 1px solid transparent;
+          position: relative;
+          z-index: 1;
+        }
+
+        .sidebar-header.scrolled {
+          box-shadow: 0 8px 24px -2px rgba(0, 0, 0, 1);
+          border-bottom-color: var(--border);
+        }
+
         .menu {
+          flex: 1;
+          min-height: 0;
+          overflow-y: auto;
+          overflow-x: hidden;
           padding: 0.5rem 0;
         }
 
@@ -277,6 +309,7 @@ export class WccSidebar extends DeesElement {
         .search-container {
           padding: 0.5rem;
           border-bottom: 1px solid var(--border);
+          position: relative;
         }
 
         .search-input {
@@ -285,7 +318,7 @@ export class WccSidebar extends DeesElement {
           background: var(--input);
           border: 1px solid var(--border);
           border-radius: var(--radius);
-          padding: 0.5rem 0.75rem;
+          padding: 0.5rem 1.75rem 0.5rem 0.75rem;
           color: var(--foreground);
           font-size: 0.75rem;
           font-family: inherit;
@@ -301,6 +334,33 @@ export class WccSidebar extends DeesElement {
           color: var(--muted-foreground);
         }
 
+        .search-clear {
+          position: absolute;
+          right: 0.75rem;
+          top: 50%;
+          transform: translateY(-50%);
+          background: none;
+          border: none;
+          padding: 0.25rem;
+          cursor: pointer;
+          color: var(--muted-foreground);
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          border-radius: 2px;
+          transition: color 0.15s ease, background 0.15s ease;
+        }
+
+        .search-clear:hover {
+          color: var(--foreground);
+          background: rgba(255, 255, 255, 0.1);
+        }
+
+        .search-clear .material-symbols-outlined {
+          font-size: 14px;
+          opacity: 1;
+        }
+
         .highlight {
           background: rgba(59, 130, 246, 0.3);
           border-radius: 2px;
@@ -390,17 +450,24 @@ export class WccSidebar extends DeesElement {
           background: var(--primary);
         }
       </style>
-      <div class="search-container">
-        <input
-          type="text"
-          class="search-input"
-          placeholder="Search..."
-          .value=${this.searchQuery}
-          @input=${this.handleSearchInput}
-        />
-      </div>
-      <div class="menu">
+      <div class="sidebar-header ${this.isMenuScrolled ? 'scrolled' : ''}">
+        <div class="search-container">
+          <input
+            type="text"
+            class="search-input"
+            placeholder="Search..."
+            .value=${this.searchQuery}
+            @input=${this.handleSearchInput}
+          />
+          ${this.searchQuery ? html`
+            <button class="search-clear" @click=${this.clearSearch}>
+              <i class="material-symbols-outlined">close</i>
+            </button>
+          ` : null}
+        </div>
         ${this.renderPinnedSection()}
+      </div>
+      <div class="menu" @scroll=${this.handleMenuScroll}>
         ${this.renderSections()}
       </div>
       <div
@@ -600,27 +667,43 @@ export class WccSidebar extends DeesElement {
         groupedItems.get(group)!.push(entry);
       }
 
-      const result: TemplateResult[] = [];
+      // Build a unified list of render items (ungrouped elements and groups)
+      // Each item has a sortKey (element name or first element name of group)
+      type RenderItem =
+        | { type: 'element'; entry: [string, any]; sortKey: string }
+        | { type: 'group'; groupName: string; items: Array<[string, any]>; sortKey: string };
 
-      // Render ungrouped items first
+      const renderItems: RenderItem[] = [];
+
+      // Add ungrouped items
       const ungrouped = groupedItems.get(null) || [];
       for (const entry of ungrouped) {
-        result.push(this.renderElementItem(entry, section));
+        renderItems.push({ type: 'element', entry, sortKey: entry[0].toLowerCase() });
       }
 
-      // Render grouped items
+      // Add groups (sorted by their first element's name)
       for (const [groupName, items] of groupedItems) {
         if (groupName === null) continue;
-
-        result.push(html`
-          <div class="item-group">
-            <span class="item-group-legend">${groupName}</span>
-            ${items.map((entry) => this.renderElementItem(entry, section))}
-          </div>
-        `);
+        const firstElementName = items[0]?.[0] || '';
+        renderItems.push({ type: 'group', groupName, items, sortKey: firstElementName.toLowerCase() });
       }
 
-      return result;
+      // Sort all items alphabetically by sortKey
+      renderItems.sort((a, b) => a.sortKey.localeCompare(b.sortKey));
+
+      // Render in sorted order
+      return renderItems.map((item) => {
+        if (item.type === 'element') {
+          return this.renderElementItem(item.entry, section);
+        } else {
+          return html`
+            <div class="item-group">
+              <span class="item-group-legend">${item.groupName}</span>
+              ${item.items.map((entry) => this.renderElementItem(entry, section))}
+            </div>
+          `;
+        }
+      });
     }
   }
 
@@ -712,6 +795,16 @@ export class WccSidebar extends DeesElement {
     this.dispatchEvent(new CustomEvent('searchChanged', { detail: this.searchQuery }));
   }
 
+  private clearSearch() {
+    this.searchQuery = '';
+    this.dispatchEvent(new CustomEvent('searchChanged', { detail: this.searchQuery }));
+  }
+
+  private handleMenuScroll(e: Event) {
+    const target = e.target as HTMLElement;
+    this.isMenuScrolled = target.scrollTop > 0;
+  }
+
   private matchesSearch(name: string): boolean {
     if (!this.searchQuery) return true;
     return name.toLowerCase().includes(this.searchQuery.toLowerCase());
@@ -732,6 +825,19 @@ export class WccSidebar extends DeesElement {
   protected updated(changedProperties: Map<string, unknown>) {
     super.updated(changedProperties);
 
+    // Handle delayed hide for native mode transition
+    if (changedProperties.has('isNative')) {
+      if (this.isNative) {
+        // Delay hiding until frame animation completes
+        setTimeout(() => {
+          this.isHidden = true;
+        }, 300);
+      } else {
+        // Show immediately when exiting native mode
+        this.isHidden = false;
+      }
+    }
+
     // Auto-expand folder when a multi-demo element is selected
     if (changedProperties.has('selectedItem') && this.selectedItem && this.dashboardRef?.sections) {
       // Find the element in any section