@design.estate/wcctools 5.1.0

package/ts_web/elements/wcctools.helpers.ts

@@ -0,0 +1,153 @@
+import type { TemplateResult } from 'lit';
+
+export type TTemplateFactory = () => TemplateResult | Promise<TemplateResult>;
+
+/** Find the nearest matching instance through light DOM and open shadow roots. */
+export const findElementInstance = <T extends HTMLElement>(
+  containerArg: Element | ShadowRoot,
+  elementClassArg: new (...args: any[]) => T,
+): T | null => {
+  const pending = Array.from(containerArg.children);
+  for (let index = 0; index < pending.length; index++) {
+    const element = pending[index];
+    if (element instanceof elementClassArg) return element;
+    pending.push(...element.children);
+    if (element.shadowRoot) pending.push(...element.shadowRoot.children);
+  }
+  return null;
+};
+
+// Demo can be a single function or an array of functions
+export type TDemoDefinition = TTemplateFactory | TTemplateFactory[];
+
+/**
+ * How a catalog export is treated in an elements section:
+ * - `demo`: a custom element class with a usable static `demo`; listed and navigable
+ * - `no-demo`: a registered custom element without a usable demo; listed under "Without demo"
+ * - `ignored`: anything else (helpers, constants, types at runtime, abstract base classes)
+ */
+export type TCatalogEntryKind = 'demo' | 'no-demo' | 'ignored';
+
+/** The static surface wcctools reads from a catalog element class. */
+export interface ICatalogElementConstructor extends CustomElementConstructor {
+  demo?: unknown;
+  demoGroups?: unknown;
+}
+
+/** A demo is one template factory or a non-empty array of template factories. */
+export const isDemoDefinition = (demoArg: unknown): demoArg is TDemoDefinition => {
+  if (typeof demoArg === 'function') {
+    return true;
+  }
+  return Array.isArray(demoArg)
+    && demoArg.length > 0
+    && demoArg.every((factoryArg) => typeof factoryArg === 'function');
+};
+
+/** True for classes that extend HTMLElement (registered or not). */
+export const isElementConstructor = (itemArg: unknown): itemArg is ICatalogElementConstructor => {
+  return typeof HTMLElement !== 'undefined'
+    && typeof itemArg === 'function'
+    && itemArg.prototype instanceof HTMLElement;
+};
+
+/** Classify one export of an elements section. */
+export const classifyCatalogEntry = (itemArg: unknown): TCatalogEntryKind => {
+  if (!isElementConstructor(itemArg)) {
+    return 'ignored';
+  }
+  if (isDemoDefinition(itemArg.demo)) {
+    return 'demo';
+  }
+  return customElements.getName(itemArg) ? 'no-demo' : 'ignored';
+};
+
+/** The tag name an element class is registered under, if any. */
+export const getElementTagName = (itemArg: unknown): string | null => {
+  return isElementConstructor(itemArg) ? customElements.getName(itemArg) : null;
+};
+
+/** The demo groups an element declares, normalized to an array. */
+export const getElementDemoGroups = (itemArg: unknown): string[] => {
+  if (!isElementConstructor(itemArg)) {
+    return [];
+  }
+  const groups = itemArg.demoGroups;
+  const list = Array.isArray(groups) ? groups : [groups];
+  return list.filter((groupArg): groupArg is string => typeof groupArg === 'string' && groupArg.length > 0);
+};
+
+export type TPropertyType = 'String' | 'Number' | 'Boolean' | 'Object' | 'Enum' | 'Array';
+
+export interface IReactivePropertyDeclaration {
+  state?: boolean;
+  type?: unknown;
+}
+
+const isEnumerationType = (typeArg: unknown): boolean => {
+  if (!typeArg || typeof typeArg !== 'object' || Array.isArray(typeArg)) {
+    return false;
+  }
+
+  const values = Object.values(typeArg);
+  return values.length > 0 && values.every((valueArg) =>
+    typeof valueArg === 'string' || typeof valueArg === 'number'
+  );
+};
+
+export const determinePropertyType = (
+  propertyArg: IReactivePropertyDeclaration
+): TPropertyType | null => {
+  if (!propertyArg || typeof propertyArg !== 'object' || propertyArg.state) {
+    return null;
+  }
+
+  switch (propertyArg.type) {
+    case String:
+      return 'String';
+    case Number:
+      return 'Number';
+    case Boolean:
+      return 'Boolean';
+    case Object:
+      return 'Object';
+    case Array:
+      return 'Array';
+    default:
+      return isEnumerationType(propertyArg.type) ? 'Enum' : null;
+  }
+};
+
+export const resolveTemplateFactory = async (
+  factoryArg: TTemplateFactory
+): Promise<TemplateResult> => {
+  return await Promise.resolve(factoryArg());
+};
+
+/**
+ * Get the number of demos for an element
+ */
+export const getDemoCount = (demo: TDemoDefinition): number => {
+  if (Array.isArray(demo)) {
+    return demo.length;
+  }
+  return 1;
+};
+
+/**
+ * Get a specific demo by index (0-based internally, displayed as 1-based)
+ */
+export const getDemoAtIndex = (demo: TDemoDefinition, index: number): TTemplateFactory | null => {
+  if (Array.isArray(demo)) {
+    return demo[index] ?? null;
+  }
+  // Single demo - only index 0 is valid
+  return index === 0 ? demo : null;
+};
+
+/**
+ * Check if an element has multiple demos
+ */
+export const hasMultipleDemos = (demo: TDemoDefinition): boolean => {
+  return Array.isArray(demo) && demo.length > 1;
+};

package/ts_web/index.ts

@@ -0,0 +1,38 @@
+import { WccDashboard } from './elements/wcc-dashboard.js';
+import type { IWccConfig, IWccSection } from './wcctools.interfaces.js';
+
+// Export recording components and service
+export { RecorderService, type IRecorderEvents, type IRecordingOptions, type TOutputFormat } from './services/recorder.service.js';
+export { WccRecordButton } from './elements/wcc-record-button.js';
+export { WccRecordingPanel } from './elements/wcc-recording-panel.js';
+
+// Export types for external use
+export type { IWccConfig, IWccSection } from './wcctools.interfaces.js';
+
+/**
+ * Set up the WCC Tools dashboard:
+ * ```typescript
+ * setupWccTools({
+ *   sections: [
+ *     { name: 'Elements', type: 'elements', items: elements },
+ *     { name: 'Pages', type: 'pages', items: pages },
+ *   ]
+ * });
+ * ```
+ */
+const setupWccTools = (config: IWccConfig) => {
+  let hasRun = false;
+  const runWccToolsSetup = async () => {
+    if (document.readyState === 'complete' && !hasRun) {
+      hasRun = true;
+      const wccTools = new WccDashboard(config);
+      document.querySelector('body').append(wccTools);
+    }
+  };
+  document.addEventListener('readystatechange', runWccToolsSetup);
+  runWccToolsSetup();
+};
+
+export {
+  setupWccTools
+};

package/ts_web/pages/index.ts

@@ -0,0 +1 @@
+export const page1 = null;

package/ts_web/readme.md

@@ -0,0 +1,177 @@
+# @design.estate/wcctools
+
+🛠️ **Web Component Catalogue Tools** — The core dashboard and UI components for building interactive component catalogues
+
+## Overview
+
+This is the main module of `@design.estate/wcctools`, providing the complete dashboard experience for developing, testing, and documenting web components.
+
+## Installation
+
+```bash
+pnpm add -D @design.estate/wcctools
+```
+
+## Usage
+
+### Sections-based Configuration (Recommended)
+
+```typescript
+import { setupWccTools } from '@design.estate/wcctools';
+import * as elements from './elements/index.js';
+import * as views from './views/index.js';
+import * as pages from './pages/index.js';
+
+setupWccTools({
+  sections: [
+    {
+      name: 'Pages',
+      type: 'pages',
+      items: pages,
+    },
+    {
+      name: 'Views',
+      type: 'elements',
+      items: views,
+      icon: 'web',
+    },
+    {
+      name: 'Elements',
+      type: 'elements',
+      items: elements,
+      filter: (name) => !name.startsWith('internal-'),
+      sort: ([a], [b]) => a.localeCompare(b),
+    },
+  ],
+});
+```
+
+### Migration from the Two-Argument Form
+
+`setupWccTools(elements, pages)` is removed in 5.0.0; pass the same maps as `pages` and `elements` sections.
+
+### What the Sidebar Lists
+
+In an `elements` section, only classes extending `HTMLElement` with a static `demo` are listed and navigable. Registered custom elements without a demo appear in a collapsed, non-clickable **Without demo** group; every other export (helpers, constants, unregistered base classes) is ignored. Classification runs before the section's `filter` and `sort`. `pages` sections list template factories only. See the package readme for details and keyboard use.
+
+## Exports
+
+### Main Entry Point
+
+| Export | Description |
+|--------|-------------|
+| `setupWccTools` | Initialize the component catalogue dashboard |
+| `IWccConfig` | TypeScript interface for sections configuration |
+| `IWccSection` | TypeScript interface for individual section |
+
+### Recording Components
+
+| Export | Description |
+|--------|-------------|
+| `RecorderService` | Service class for screen/viewport recording and MP4 conversion |
+| `WccRecordButton` | Record button UI component |
+| `WccRecordingPanel` | Recording options and preview panel |
+| `IRecorderEvents` | TypeScript interface for recorder callbacks |
+| `IRecordingOptions` | TypeScript interface for recording options |
+| `TOutputFormat` | Type for output format selection (`'webm' \| 'mp4'`) |
+
+## Section Configuration
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Display name for the section header |
+| `type` | `'elements' \| 'pages'` | Rendering behavior |
+| `items` | `Record<string, any>` | Element classes or page factories |
+| `filter` | `(name, item) => boolean` | Optional filter function |
+| `sort` | `([a, itemA], [b, itemB]) => number` | Optional sort function |
+| `icon` | `string` | Material Symbols icon name |
+| `collapsed` | `boolean` | Start section collapsed (default: false) |
+
+## Internal Components
+
+The module includes these internal web components:
+
+| Component | Description |
+|-----------|-------------|
+| `wcc-dashboard` | Main dashboard container with routing |
+| `wcc-sidebar` | Navigation sidebar with collapsible sections and search |
+| `wcc-frame` | Responsive viewport with size controls |
+| `wcc-properties` | Property panel with live editing |
+| `wcc-record-button` | Recording state indicator button |
+| `wcc-recording-panel` | Recording workflow UI with format selection |
+
+## RecorderService API
+
+For programmatic recording and MP4 conversion:
+
+```typescript
+import { RecorderService, type IRecorderEvents } from '@design.estate/wcctools';
+
+const events: IRecorderEvents = {
+  onDurationUpdate: (duration) => console.log(`Recording: ${duration}s`),
+  onRecordingComplete: (blob) => saveBlob(blob),
+  onAudioLevelUpdate: (level) => updateMeter(level),
+  onError: (error) => console.error(error),
+  onStreamEnded: () => console.log('User stopped sharing'),
+};
+
+const recorder = new RecorderService(events);
+
+// Load available microphones
+const mics = await recorder.loadMicrophones(true);
+
+// Start audio level monitoring
+await recorder.startAudioMonitoring(mics[0].deviceId);
+
+// Start recording (always captures as WebM internally at up to 60fps)
+await recorder.startRecording({
+  mode: 'viewport',
+  audioDeviceId: mics[0].deviceId,
+  viewportElement: document.querySelector('.viewport'),
+});
+
+// Stop recording
+recorder.stopRecording();
+
+// Convert to MP4 for universal playback (H.264 + AAC via WebCodecs)
+const mp4Blob = await recorder.convertToMp4(recorder.recordedBlob);
+
+// Or export trimmed video
+const trimmedBlob = await recorder.exportTrimmedVideo(videoElement, startTime, endTime);
+
+// Cleanup
+recorder.dispose();
+```
+
+## Architecture
+
+```
+ts_web/
+├── index.ts                    # Main exports
+├── wcctools.interfaces.ts      # Type definitions
+├── types/
+│   ├── dom-webcodecs-stub/     # TS6 compatibility shim
+│   └── dom-mediacapture-stub/  # MediaCapture Transform types
+├── elements/
+│   ├── wcc-dashboard.ts        # Root dashboard component
+│   ├── wcc-sidebar.ts          # Navigation sidebar
+│   ├── wcc-frame.ts            # Responsive viewport
+│   ├── wcc-properties.ts       # Property editing panel
+│   ├── wcc-record-button.ts    # Recording button
+│   ├── wcc-recording-panel.ts  # Recording options/preview
+│   └── wcctools.helpers.ts     # Shared utilities
+├── services/
+│   └── recorder.service.ts     # MediaRecorder + mediabunny MP4 conversion
+└── pages/
+    └── index.ts                # Built-in pages
+```
+
+## Features
+
+- 🎨 Interactive component preview
+- 📂 Section-based sidebar with filtering, sorting & search (by name, tag, or group)
+- 🔧 Real-time property editing with type detection
+- 🌓 Theme switching (light/dark)
+- 📱 Responsive viewport testing
+- 🎬 Screen recording with MP4/WebM export, trimming, and audio
+- 🔗 URL-based deep linking