@design.estate/dees-wcctools 3.1.2 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-wcctools",
-  "version": "3.1.2",
+  "version": "3.3.0",
   "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": {

package/readme.hints.md

@@ -1,5 +1,67 @@
 # Project Hints and Findings
 
+## Section-based Configuration API (2025-12-27)
+
+### Overview
+Refactored `setupWccTools` to accept a section-based configuration object instead of separate elements/pages arguments. This allows multiple custom sections with filtering, sorting, and collapsible headers.
+
+### New API
+```typescript
+import * as deesWccTools from '@design.estate/dees-wcctools';
+
+deesWccTools.setupWccTools({
+  sections: [
+    {
+      name: 'Pages',
+      type: 'pages',
+      items: pages,
+    },
+    {
+      name: 'Elements',
+      type: 'elements',
+      items: elements,
+      filter: (name, item) => !name.startsWith('internal-'),
+      sort: ([a], [b]) => a.localeCompare(b),
+    },
+    {
+      name: 'Views',
+      type: 'elements',
+      items: elements,
+      filter: (name, item) => name.startsWith('view-'),
+      icon: 'web',
+      collapsed: true,  // Start collapsed
+    },
+  ],
+});
+```
+
+### Section Properties
+- `name`: Display name for the section header
+- `type`: `'elements'` (shows demos) or `'pages'` (renders directly)
+- `items`: Record of items (element classes or page factories)
+- `filter`: Optional `(name, item) => boolean` to filter items
+- `sort`: Optional `([name, item], [name, item]) => number` for ordering
+- `icon`: Optional Material icon name for section header
+- `collapsed`: Optional boolean to start section collapsed
+
+### Backwards Compatibility
+Legacy format is still supported:
+```typescript
+deesWccTools.setupWccTools(elements, pages);  // Still works
+```
+
+### URL Routing
+Changed from `/wcctools-route/:itemType/:itemName/...` to `/wcctools-route/:sectionName/:itemName/...`
+Section names are URL-encoded. Legacy routes (`element`/`page` as section name) still work for backwards compatibility.
+
+### Files Changed
+- `ts_web/wcctools.interfaces.ts` - New types: `IWccSection`, `IWccConfig`
+- `ts_web/index.ts` - Updated `setupWccTools` with backwards compat detection
+- `ts_web/elements/wcc-dashboard.ts` - Uses sections, updated routing
+- `ts_web/elements/wcc-sidebar.ts` - Dynamic section rendering
+
+---
+
 ## UI Redesign with Shadcn-like Styles (2025-06-27)
 
 ### Changes Made

package/readme.md

@@ -6,12 +6,13 @@
 
 `@design.estate/dees-wcctools` provides a comprehensive development environment for web components, featuring:
 
-- 🎨 **Interactive Component Catalogue** — Live preview with sidebar navigation
+- 🎨 **Interactive Component Catalogue** — Live preview with customizable sidebar sections
 - 🔧 **Real-time Property Editing** — Modify component props on the fly with auto-detected editors
 - 🌓 **Theme Switching** — Test light/dark modes instantly
 - 📱 **Responsive Viewport Testing** — Phone, phablet, tablet, and desktop views
 - 🎬 **Screen Recording** — Record component demos with audio support and video trimming
 - 🧪 **Advanced Demo Tools** — Post-render hooks for interactive testing
+- 📂 **Section-based Organization** — Group components into custom sections with filtering and sorting
 - 🚀 **Zero-config Setup** — TypeScript and Lit support out of the box
 
 ## Issue Reporting and Security
@@ -57,29 +58,22 @@ export class MyButton extends DeesElement {
         padding: 8px 16px;
         border-radius: 4px;
         border: none;
-        font-size: 14px;
         cursor: pointer;
-        transition: all 0.3s;
       }
       button.primary {
-        background: #007bff;
+        background: #3b82f6;
         color: white;
       }
       button.secondary {
-        background: #6c757d;
+        background: #6b7280;
         color: white;
       }
-      button:hover {
-        opacity: 0.9;
-      }
     `
   ];
 
   public render() {
     return html`
-      <button class="${this.variant}">
-        ${this.label}
-      </button>
+      <button class="${this.variant}">${this.label}</button>
     `;
   }
 }
@@ -93,33 +87,32 @@ import { setupWccTools } from '@design.estate/dees-wcctools';
 import { html } from 'lit';
 
 // Import your components
-import { MyButton } from './components/my-button.js';
-import { MyCard } from './components/my-card.js';
-
-// Define elements for the catalogue
-const elements = {
-  'my-button': MyButton,
-  'my-card': MyCard,
-};
-
-// Optionally define pages
-const pages = {
-  'home': () => html`
-    <div style="padding: 20px;">
-      <h1>Welcome to My Component Library</h1>
-      <p>Browse components using the sidebar.</p>
-    </div>
-  `,
-  'getting-started': () => html`
-    <div style="padding: 20px;">
-      <h2>Getting Started</h2>
-      <p>Installation and usage instructions...</p>
-    </div>
-  `,
-};
-
-// Initialize the catalogue
-setupWccTools(elements, pages);
+import * as elements from './components/index.js';
+import * as views from './views/index.js';
+import * as pages from './pages/index.js';
+
+// Initialize with sections-based configuration
+setupWccTools({
+  sections: [
+    {
+      name: 'Pages',
+      type: 'pages',
+      items: pages,
+    },
+    {
+      name: 'Views',
+      type: 'elements',
+      items: views,
+      icon: 'web',
+    },
+    {
+      name: 'Elements',
+      type: 'elements',
+      items: elements,
+      sort: ([a], [b]) => a.localeCompare(b),
+    },
+  ],
+});
 ```
 
 ### 3. Create an HTML Entry Point
@@ -137,6 +130,69 @@ setupWccTools(elements, pages);
 </html>
 ```
 
+## 📂 Sections Configuration
+
+The sections-based API gives you full control over how components are organized in the sidebar.
+
+### Section Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Display name for the section header |
+| `type` | `'elements' \| 'pages'` | How items render (`elements` show demos, `pages` render directly) |
+| `items` | `Record<string, any>` | Object containing element classes or page factories |
+| `filter` | `(name, item) => boolean` | Optional filter function to include/exclude items |
+| `sort` | `([a, itemA], [b, itemB]) => number` | Optional sort function for ordering items |
+| `icon` | `string` | Optional Material Symbols icon name |
+| `collapsed` | `boolean` | Start section collapsed (default: `false`) |
+
+### Advanced Example
+
+```typescript
+import { setupWccTools } from '@design.estate/dees-wcctools';
+import * as allElements from './elements/index.js';
+import * as pages from './pages/index.js';
+
+setupWccTools({
+  sections: [
+    {
+      name: 'Pages',
+      type: 'pages',
+      items: pages,
+    },
+    {
+      name: 'Form Controls',
+      type: 'elements',
+      items: allElements,
+      icon: 'edit_note',
+      filter: (name) => name.startsWith('form-') || name.includes('input'),
+      sort: ([a], [b]) => a.localeCompare(b),
+    },
+    {
+      name: 'Layout',
+      type: 'elements',
+      items: allElements,
+      icon: 'dashboard',
+      filter: (name) => name.startsWith('layout-') || name.startsWith('grid-'),
+    },
+    {
+      name: 'Legacy',
+      type: 'elements',
+      items: allElements,
+      filter: (name) => name.startsWith('legacy-'),
+      collapsed: true,  // Start collapsed
+    },
+  ],
+});
+```
+
+### Legacy API (Still Supported)
+
+```typescript
+// The old format still works for simple use cases
+setupWccTools(elements, pages);
+```
+
 ## Features
 
 ### 🎯 Live Property Editing
@@ -162,19 +218,7 @@ Test your components across different screen sizes:
 
 ### 🌓 Theme Support
 
-Components automatically adapt to light/dark themes using the `goBright` property:
-
-```typescript
-public render() {
-  return html`
-    <div class="${this.goBright ? 'light-theme' : 'dark-theme'}">
-      <!-- Your component content -->
-    </div>
-  `;
-}
-```
-
-Or use CSS custom properties with the theme manager:
+Components automatically adapt to light/dark themes. Use CSS custom properties with the theme manager:
 
 ```typescript
 import { cssManager } from '@design.estate/dees-element';
@@ -182,8 +226,8 @@ import { cssManager } from '@design.estate/dees-element';
 public static styles = [
   css`
     :host {
-      color: ${cssManager.bdTheme('#000', '#fff')};
-      background: ${cssManager.bdTheme('#fff', '#000')};
+      color: ${cssManager.bdTheme('#1a1a1a', '#e5e5e5')};
+      background: ${cssManager.bdTheme('#ffffff', '#0a0a0a')};
     }
   `
 ];
@@ -191,7 +235,7 @@ public static styles = [
 
 ### 🎬 Screen Recording
 
-Record component demos directly from the catalogue! The built-in recorder supports:
+Record component demos directly from the catalogue:
 
 - **Viewport Recording** — Record just the component viewport
 - **Full Screen Recording** — Capture the entire screen
@@ -232,9 +276,26 @@ export class MyComponent extends DeesElement {
 }
 ```
 
+### 🎭 Multiple Demos
+
+Components can expose multiple demo variations:
+
+```typescript
+@customElement('my-button')
+export class MyButton extends DeesElement {
+  public static demo = [
+    () => html`<my-button variant="primary">Primary</my-button>`,
+    () => html`<my-button variant="secondary">Secondary</my-button>`,
+    () => html`<my-button variant="danger">Danger</my-button>`,
+  ];
+}
+```
+
+Each demo appears as a numbered item in an expandable folder in the sidebar.
+
 ### ⏳ Async Demos
 
-Return a `Promise` from `demo` for async setup. The dashboard waits for resolution:
+Return a `Promise` from `demo` for async setup:
 
 ```typescript
 public static demo = async () => {
@@ -243,7 +304,7 @@ public static demo = async () => {
 };
 ```
 
-### 🎭 Container Queries
+### 🎯 Container Queries
 
 Components can respond to their container size using the `wccToolsViewport` container:
 
@@ -269,7 +330,7 @@ public static styles = [
 
 ### Required for Catalogue Display
 
-1. Components must expose a static `demo` property returning a Lit template
+1. Components must expose a static `demo` property returning a Lit template (or array of templates)
 2. Use `@property()` decorators with the `accessor` keyword for editable properties
 3. Export component classes for proper detection
 
@@ -278,7 +339,7 @@ public static styles = [
 ```typescript
 @customElement('best-practice-component')
 export class BestPracticeComponent extends DeesElement {
-  // ✅ Static demo property
+  // ✅ Static demo property (single or array)
   public static demo = () => html`
     <best-practice-component
       .complexProp=${{ key: 'value' }}
@@ -305,23 +366,40 @@ export class BestPracticeComponent extends DeesElement {
 The catalogue uses URL routing for deep linking:
 
 ```
-/wcctools-route/:type/:name/:viewport/:theme
+/wcctools-route/:sectionName/:itemName/:demoIndex/:viewport/:theme
 
 Examples:
-/wcctools-route/element/my-button/desktop/dark
-/wcctools-route/page/home/tablet/bright
+/wcctools-route/Elements/my-button/0/desktop/dark
+/wcctools-route/Views/view-dashboard/0/tablet/bright
+/wcctools-route/Pages/home/0/desktop/dark
 ```
 
 ## API Reference
 
-### `setupWccTools(elements, pages?)`
+### `setupWccTools(config)`
+
+Initialize the WCC Tools dashboard with sections configuration.
 
-Initialize the WCC Tools dashboard.
+```typescript
+interface IWccSection {
+  name: string;
+  type: 'elements' | 'pages';
+  items: Record<string, any>;
+  filter?: (name: string, item: any) => boolean;
+  sort?: (a: [string, any], b: [string, any]) => number;
+  icon?: string;
+  collapsed?: boolean;
+}
+
+interface IWccConfig {
+  sections: IWccSection[];
+}
+
+setupWccTools(config: IWccConfig): void;
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `elements` | `Record<string, typeof LitElement>` | Map of element names to classes |
-| `pages` | `Record<string, TTemplateFactory>` | Optional map of page names to template functions |
+// Legacy (still supported)
+setupWccTools(elements: Record<string, any>, pages?: Record<string, TTemplateFactory>): void;
+```
 
 ### `DeesDemoWrapper`
 
@@ -357,14 +435,21 @@ recorder.stopRecording();
 ## Project Structure
 
 ```
-my-components/
+my-component-library/
 ├── src/
-│   ├── components/
+│   ├── elements/          # UI components
 │   │   ├── my-button.ts
-│   │   └── my-card.ts
-│   └── catalogue.ts
-├── dist/
-├── index.html
+│   │   ├── my-card.ts
+│   │   └── index.ts
+│   ├── views/             # Full-page layouts
+│   │   ├── view-dashboard.ts
+│   │   └── index.ts
+│   ├── pages/             # Documentation pages
+│   │   ├── home.ts
+│   │   └── index.ts
+│   └── catalogue.ts       # WCC Tools setup
+├── html/
+│   └── index.html
 └── package.json
 ```
 

package/ts_web/00_commitinfo_data.ts

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

package/ts_web/elements/wcc-dashboard.ts

@@ -1,6 +1,7 @@
 import { DeesElement, property, html, customElement, type TemplateResult, queryAsync, render, domtools } from '@design.estate/dees-element';
 import { resolveTemplateFactory, getDemoAtIndex, getDemoCount, hasMultipleDemos } 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';
 
@@ -9,13 +10,37 @@ import './wcc-frame.js';
 import './wcc-sidebar.js';
 import './wcc-properties.js';
 import { type TTheme } from './wcc-properties.js';
-import { type TElementType } from './wcc-sidebar.js';
 import { breakpoints } from '@design.estate/dees-domtools';
 import { WccFrame } from './wcc-frame.js';
 
+/**
+ * Get filtered and sorted items from a section
+ */
+export const getSectionItems = (section: IWccSection): Array<[string, any]> => {
+  let entries = Object.entries(section.items);
+
+  // Apply filter if provided
+  if (section.filter) {
+    entries = entries.filter(([name, item]) => section.filter(name, item));
+  }
+
+  // Apply sort if provided
+  if (section.sort) {
+    entries.sort(section.sort);
+  }
+
+  return entries;
+};
+
 @customElement('wcc-dashboard')
 export class WccDashboard extends DeesElement {
 
+  @property()
+  accessor sections: IWccSection[] = [];
+
+  @property()
+  accessor selectedSection: IWccSection | null = null;
+
   @property()
   accessor selectedType: TElementType;
 
@@ -39,36 +64,43 @@ export class WccDashboard extends DeesElement {
     return this.selectedViewport === 'native';
   }
 
-  @property()
-  accessor pages: Record<string, TTemplateFactory> = {};
-
-  @property()
-  accessor elements: { [key: string]: DeesElement } = {};
-
   @property()
   accessor warning: string = null;
-  
+
   private frameScrollY: number = 0;
   private sidebarScrollY: number = 0;
   private scrollPositionsApplied: boolean = false;
-  
+
   @queryAsync('wcc-frame')
   accessor wccFrame: Promise<WccFrame>;
 
-  constructor(
-    elementsArg?: { [key: string]: DeesElement },
-    pagesArg?: Record<string, TTemplateFactory>
-  ) {
+  constructor(config?: IWccConfig) {
     super();
-    if (elementsArg) {
-      this.elements = elementsArg;
-      console.log('got elements:');
-      console.log(this.elements);
+    if (config && config.sections) {
+      this.sections = config.sections;
+      console.log('got sections:', this.sections.map(s => s.name));
     }
+  }
 
-    if (pagesArg) {
-      this.pages = pagesArg;
+  /**
+   * Find an 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 entries = getSectionItems(section);
+      const found = entries.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 {
@@ -159,19 +191,37 @@ export class WccDashboard extends DeesElement {
       this.setupScrollListeners();
     }, 500);
     
-    // Route with demo index (new format)
+    // New route format with section name
     this.domtools.router.on(
-      '/wcctools-route/:itemType/:itemName/:demoIndex/:viewport/:theme',
+      '/wcctools-route/:sectionName/:itemName/:demoIndex/:viewport/:theme',
       async (routeInfo) => {
-        this.selectedType = routeInfo.params.itemType as TElementType;
+        const sectionName = decodeURIComponent(routeInfo.params.sectionName);
+        this.selectedSection = this.findSectionByName(sectionName);
         this.selectedItemName = routeInfo.params.itemName;
         this.selectedDemoIndex = parseInt(routeInfo.params.demoIndex) || 0;
         this.selectedViewport = routeInfo.params.viewport as breakpoints.TViewport;
         this.selectedTheme = routeInfo.params.theme as TTheme;
-        if (routeInfo.params.itemType === 'element') {
-          this.selectedItem = this.elements[routeInfo.params.itemName];
-        } else if (routeInfo.params.itemType === 'page') {
-          this.selectedItem = this.pages[routeInfo.params.itemName];
+
+        if (this.selectedSection) {
+          // Find item within the section
+          const entries = getSectionItems(this.selectedSection);
+          const found = entries.find(([name]) => name === routeInfo.params.itemName);
+          if (found) {
+            this.selectedItem = found[1];
+            this.selectedType = this.selectedSection.type === 'elements' ? 'element' : 'page';
+          }
+        } else {
+          // Fallback: try legacy format (element/page as section name)
+          const legacyType = routeInfo.params.sectionName;
+          if (legacyType === 'element' || legacyType === 'page') {
+            this.selectedType = legacyType as TElementType;
+            // Find item in any matching section
+            const result = this.findItemByName(routeInfo.params.itemName);
+            if (result) {
+              this.selectedItem = result.item;
+              this.selectedSection = result.section;
+            }
+          }
         }
 
         // Restore scroll positions from query parameters
@@ -201,17 +251,33 @@ export class WccDashboard extends DeesElement {
 
     // Legacy route without demo index (for backwards compatibility)
     this.domtools.router.on(
-      '/wcctools-route/:itemType/:itemName/:viewport/:theme',
+      '/wcctools-route/:sectionName/:itemName/:viewport/:theme',
       async (routeInfo) => {
-        this.selectedType = routeInfo.params.itemType as TElementType;
+        const sectionName = decodeURIComponent(routeInfo.params.sectionName);
+        this.selectedSection = this.findSectionByName(sectionName);
         this.selectedItemName = routeInfo.params.itemName;
-        this.selectedDemoIndex = 0; // Default to first demo
+        this.selectedDemoIndex = 0;
         this.selectedViewport = routeInfo.params.viewport as breakpoints.TViewport;
         this.selectedTheme = routeInfo.params.theme as TTheme;
-        if (routeInfo.params.itemType === 'element') {
-          this.selectedItem = this.elements[routeInfo.params.itemName];
-        } else if (routeInfo.params.itemType === 'page') {
-          this.selectedItem = this.pages[routeInfo.params.itemName];
+
+        if (this.selectedSection) {
+          const entries = getSectionItems(this.selectedSection);
+          const found = entries.find(([name]) => name === routeInfo.params.itemName);
+          if (found) {
+            this.selectedItem = found[1];
+            this.selectedType = this.selectedSection.type === 'elements' ? 'element' : 'page';
+          }
+        } else {
+          // Fallback: try legacy format
+          const legacyType = routeInfo.params.sectionName;
+          if (legacyType === 'element' || legacyType === 'page') {
+            this.selectedType = legacyType as TElementType;
+            const result = this.findItemByName(routeInfo.params.itemName);
+            if (result) {
+              this.selectedItem = result.item;
+              this.selectedSection = result.section;
+            }
+          }
         }
 
         // Restore scroll positions from query parameters
@@ -297,7 +363,10 @@ export class WccDashboard extends DeesElement {
   }
 
   public buildUrl() {
-    const baseUrl = `/wcctools-route/${this.selectedType}/${this.selectedItemName}/${this.selectedDemoIndex}/${this.selectedViewport}/${this.selectedTheme}`;
+    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.frameScrollY > 0) {
@@ -351,7 +420,10 @@ export class WccDashboard extends DeesElement {
   }
   
   private updateUrlWithScrollState() {
-    const baseUrl = `/wcctools-route/${this.selectedType}/${this.selectedItemName}/${this.selectedDemoIndex}/${this.selectedViewport}/${this.selectedTheme}`;
+    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.frameScrollY > 0) {