feat(docs): document new media & tile components and expand Workspace/IDE component docs; update component count to 90+

2026-01-27 12:36:46 +00:00
parent 264e460365
commit 85badfbd21
3 changed files with 243 additions and 42 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,6 +1,6 @@
 # @design.estate/dees-catalog

-A comprehensive web components library built with TypeScript and LitElement, providing **70+ production-ready UI components** for building modern web applications with consistent design and behavior. 🚀
+A comprehensive web components library built with TypeScript and LitElement, providing **90+ production-ready UI components** for building modern web applications with consistent design and behavior. 🚀

 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![LitElement](https://img.shields.io/badge/LitElement-4.0+-orange.svg)](https://lit.dev/)
@@ -18,6 +18,8 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - 🔧 **TypeScript-First** — Fully typed APIs with excellent IDE support
 - 🧩 **Modular** — Use only what you need, tree-shakeable architecture
 - 🏗️ **Full App Shell** — `dees-appui` provides a complete application framework with menus, routing, activity log, and bottom bar
+- 🎬 **Media Components** — Rich tile-based previews for PDFs, images, audio, video, notes, and folders
+- 💻 **IDE Workspace** — Full workspace component with Monaco editor, file tree, terminal, and diff viewer

 ## 📦 Installation

@@ -55,12 +57,13 @@ For developers working on this library, please refer to the [UI Components Playb
 |----------|------------|
 | **Core UI** | [`DeesButton`](#deesbutton), [`DeesButtonExit`](#deesbuttonexit), [`DeesButtonGroup`](#deesbuttongroup), [`DeesBadge`](#deesbadge), [`DeesChips`](#deeschips), [`DeesHeading`](#deesheading), [`DeesHint`](#deeshint), [`DeesIcon`](#deesicon), [`DeesLabel`](#deeslabel), [`DeesPanel`](#deespanel), [`DeesSearchbar`](#deessearchbar), [`DeesSpinner`](#deesspinner), [`DeesToast`](#deestoast), [`DeesWindowcontrols`](#deeswindowcontrols), [`DeesActionbar`](#deesactionbar) |
 | **Forms** | [`DeesForm`](#deesform), [`DeesInputText`](#deesinputtext), [`DeesInputCheckbox`](#deesinputcheckbox), [`DeesInputDropdown`](#deesinputdropdown), [`DeesInputRadiogroup`](#deesinputradiogroup), [`DeesInputFileupload`](#deesinputfileupload), [`DeesInputIban`](#deesinputiban), [`DeesInputPhone`](#deesinputphone), [`DeesInputQuantitySelector`](#deesinputquantityselector), [`DeesInputMultitoggle`](#deesinputmultitoggle), [`DeesInputToggle`](#deesinputtoggle), [`DeesInputTags`](#deesinputtags), [`DeesInputTypelist`](#deesinputtypelist), [`DeesInputList`](#deesinputlist), [`DeesInputProfilepicture`](#deesinputprofilepicture), [`DeesInputRichtext`](#deesinputrichtext), [`DeesInputWysiwyg`](#deesinputwysiwyg), [`DeesInputDatepicker`](#deesinputdatepicker), [`DeesInputSearchselect`](#deesinputsearchselect), [`DeesInputCode`](#deesinputcode), [`DeesFormSubmit`](#deesformsubmit) |
-| **App Shell (Layout)** | [`DeesAppui`](#deesappui-), [`DeesAppuiMainmenu`](#deesappuimainmenu), [`DeesAppuiSecondarymenu`](#deesappuisecondarymenu), [`DeesAppuiMaincontent`](#deesappuimaincontent), [`DeesAppuiAppbar`](#deesappuiappbar), [`DeesAppuiActivitylog`](#deesappuiactivitylog), [`DeesAppuiBottombar`](#deesappuibottombar), [`DeesAppuiProfiledropdown`](#deesappuiprofiledropdown), [`DeesAppuiTabs`](#deesappuitabs), [`DeesMobileNavigation`](#deesmobilenavigation), [`DeesDashboardGrid`](#deesdashboardgrid) |
+| **App Shell (Layout)** | [`DeesAppui`](#deesappui-️), [`DeesAppuiMainmenu`](#deesappuimainmenu), [`DeesAppuiSecondarymenu`](#deesappuisecondarymenu), [`DeesAppuiMaincontent`](#deesappuimaincontent), [`DeesAppuiAppbar`](#deesappuiappbar), [`DeesAppuiActivitylog`](#deesappuiactivitylog), [`DeesAppuiBottombar`](#deesappuibottombar), [`DeesAppuiProfiledropdown`](#deesappuiprofiledropdown), [`DeesAppuiTabs`](#deesappuitabs), [`DeesMobileNavigation`](#deesmobilenavigation), [`DeesDashboardGrid`](#deesdashboardgrid) |
 | **Data Display** | [`DeesTable`](#deestable), [`DeesDataviewCodebox`](#deesdataviewcodebox), [`DeesDataviewStatusobject`](#deesdataviewstatusobject), [`DeesPdf`](#deespdf), [`DeesStatsGrid`](#deesstatsgrid), [`DeesPagination`](#deespagination) |
+| **Media & Tiles** | [`DeesTilePdf`](#deestilepdf), [`DeesTileImage`](#deestileimage), [`DeesTileAudio`](#deestileaudio), [`DeesTileVideo`](#deestilevideo), [`DeesTileNote`](#deestilenote), [`DeesTileFolder`](#deestilefolder), [`DeesPreview`](#deespreview), [`DeesPdfViewer`](#deespdfviewer), [`DeesPdfPreview`](#deespdfpreview), [`DeesImageViewer`](#deesimageviewer), [`DeesAudioViewer`](#deesaudioviewer), [`DeesVideoViewer`](#deesvideoviewer) |
 | **Visualization** | [`DeesChartArea`](#deeschartarea), [`DeesChartLog`](#deeschartlog) |
 | **Dialogs & Overlays** | [`DeesModal`](#deesmodal), [`DeesContextmenu`](#deescontextmenu), [`DeesSpeechbubble`](#deesspeechbubble), [`DeesWindowlayer`](#deeswindowlayer) |
 | **Navigation** | [`DeesStepper`](#deesstepper), [`DeesProgressbar`](#deesprogressbar) |
-| **Workspace / IDE** | [`DeesEditor`](#deeseditor), [`DeesTerminal`](#deesterminal), [`DeesUpdater`](#deesupdater) |
+| **Workspace / IDE** | [`DeesWorkspace`](#deesworkspace), [`DeesWorkspaceMonaco`](#deesworkspacemonaco), [`DeesWorkspaceDiffEditor`](#deesworkspacediffeditor), [`DeesWorkspaceFiletree`](#deesworkspacefiletree), [`DeesWorkspaceTerminal`](#deesworkspaceterminal), [`DeesWorkspaceTerminalPreview`](#deesworkspaceterminalpreview), [`DeesWorkspaceMarkdown`](#deesworkspacemarkdown), [`DeesWorkspaceMarkdownoutlet`](#deesworkspacemarkdownoutlet), [`DeesWorkspaceBottombar`](#deesworkspacebottombar) |
 | **Theming** | [`DeesTheme`](#deestheme) |
 | **Pre-built Templates** | [`DeesSimpleAppdash`](#deessimpleappdash), [`DeesSimpleLogin`](#deessimplelogin) |
 | **Shopping** | [`DeesShoppingProductcard`](#deesshoppingproductcard) |
@@ -1234,6 +1237,146 @@ Pagination component for navigating through large datasets.

 ---

+### Media & Tile Components 🎬
+
+A rich collection of tile-based preview components for displaying media files in grids. All tiles share a consistent base class (`DeesTileBase`) with lazy loading via `IntersectionObserver`, hover interactions, click events, context menus, and three size variants (`small`, `default`, `large`).
+
+All tile badges use a unified styling system with label-awareness — when a `label` is set, bottom badges automatically shift up to avoid overlapping.
+
+#### `DeesTilePdf`
+PDF document tile with live page preview on hover.
+
+```typescript
+<dees-tile-pdf
+  pdfUrl="/documents/report.pdf"
+  label="Annual Report"
+  clickable
+  @tile-click=${handleClick}
+></dees-tile-pdf>
+```
+
+**Key Features:**
+- Renders first page as canvas preview
+- Hover to scrub through pages (mouse X position maps to page number)
+- Shows page count badge, hover page indicator
+- Detects A4/Letter vs non-standard aspect ratios
+
+#### `DeesTileImage`
+Image tile with lazy loading and dimension display.
+
+```typescript
+<dees-tile-image
+  src="/photos/landscape.jpg"
+  alt="Mountain landscape"
+  label="landscape.jpg"
+  clickable
+  @tile-click=${handleClick}
+></dees-tile-image>
+```
+
+**Key Features:**
+- Lazy loads image on scroll into view
+- Shows image dimensions on hover (e.g. "1920 × 1080")
+- Checkerboard background for transparent images
+
+#### `DeesTileAudio`
+Audio file tile with waveform visualization.
+
+```typescript
+<dees-tile-audio
+  src="/music/track.mp3"
+  title="Summer Vibes"
+  artist="DJ Example"
+  clickable
+  @tile-click=${handleClick}
+></dees-tile-audio>
+```
+
+**Key Features:**
+- Generates waveform visualization from audio data
+- Shows duration badge (e.g. "3:42")
+- Displays title and artist metadata
+- Play overlay on hover
+
+#### `DeesTileVideo`
+Video tile with thumbnail capture and hover preview.
+
+```typescript
+<dees-tile-video
+  src="/videos/intro.mp4"
+  poster="/thumbs/intro.jpg"
+  label="Introduction"
+  clickable
+  @tile-click=${handleClick}
+></dees-tile-video>
+```
+
+**Key Features:**
+- Auto-captures first frame as thumbnail (or uses provided `poster`)
+- Plays video preview on hover
+- Shows duration badge
+- Play button overlay
+
+#### `DeesTileNote`
+Code/text snippet tile with syntax-aware display.
+
+```typescript
+<dees-tile-note
+  title="config.ts"
+  language="TypeScript"
+  .content=${codeString}
+  clickable
+  @tile-click=${handleClick}
+></dees-tile-note>
+```
+
+**Key Features:**
+- Monospace font with line numbers
+- Language badge (top-right)
+- Scrollable content on hover (mouse X position controls scroll)
+- Line indicator badge while scrolling
+- Gradient fade at bottom
+
+#### `DeesTileFolder`
+Folder tile with 2×2 content preview grid.
+
+```typescript
+<dees-tile-folder
+  name="Project Assets"
+  .items=${[
+    { type: 'image', name: 'logo.png', thumbnailSrc: '/thumbs/logo.png' },
+    { type: 'pdf', name: 'spec.pdf' },
+    { type: 'audio', name: 'jingle.mp3' },
+    { type: 'video', name: 'demo.mp4' },
+  ]}
+  clickable
+  @tile-click=${handleClick}
+></dees-tile-folder>
+```
+
+**Key Features:**
+- 2×2 preview grid showing first 4 items (thumbnails or type icons)
+- Item count badge (e.g. "12 items")
+- Folder icon header with name
+- Supports: `pdf`, `image`, `audio`, `video`, `note`, `folder`, `unknown` types
+
+#### `DeesPreview`
+Unified preview component that auto-selects the right tile type based on content.
+
+#### `DeesPdfViewer` / `DeesPdfPreview`
+Full PDF viewing components with navigation controls.
+
+#### `DeesImageViewer`
+Full-screen image viewer with zoom and pan.
+
+#### `DeesAudioViewer`
+Audio playback component with waveform and controls.
+
+#### `DeesVideoViewer`
+Video playback component with standard controls.
+
+---
+
 ### Visualization Components

 #### `DeesChartArea`
@@ -1294,16 +1437,41 @@ DeesModal.createAndShow({
 ```

 #### `DeesContextmenu`
-Context menu component for right-click actions.
+Context menu component for right-click actions with nested submenu support.

 ```typescript
-<dees-contextmenu
-  .items=${[
-    { label: 'Edit', icon: 'edit', action: () => handleEdit() },
-    { label: 'Delete', icon: 'trash', action: () => handleDelete() }
-  ]}
-  position="right"
-></dees-contextmenu>
+// Programmatic usage
+DeesContextmenu.openContextMenuWithOptions(mouseEvent, [
+  {
+    name: 'Edit',
+    iconName: 'lucide:edit',
+    action: async () => handleEdit()
+  },
+  { divider: true },
+  {
+    name: 'More Options',
+    iconName: 'lucide:moreHorizontal',
+    submenu: [
+      { name: 'Duplicate', iconName: 'lucide:copy', action: async () => handleDuplicate() },
+      { name: 'Archive', iconName: 'lucide:archive', action: async () => handleArchive() },
+    ]
+  },
+  {
+    name: 'Delete',
+    iconName: 'lucide:trash2',
+    action: async () => handleDelete()
+  }
+]);
+
+// Component-based (implement getContextMenuItems on any element)
+class MyComponent extends DeesElement {
+  getContextMenuItems() {
+    return [
+      { name: 'View Details', iconName: 'lucide:eye', action: async () => { ... } },
+      { name: 'Edit', iconName: 'lucide:edit', action: async () => { ... } },
+    ];
+  }
+}
 ```

 #### `DeesSpeechbubble`
@@ -1395,51 +1563,68 @@ Theme provider component that wraps children and provides CSS custom properties

 ---

-### Workspace / IDE Components
+### Workspace / IDE Components 💻

-#### `DeesEditor`
-Code editor component with syntax highlighting and code completion, powered by Monaco Editor.
+A full-featured IDE workspace component suite for building browser-based code editors, terminal interfaces, and documentation viewers.
+
+#### `DeesWorkspace`
+Top-level workspace shell that composes editor, file tree, terminal, and bottom bar into an IDE-like layout.

 ```typescript
-<dees-editor
+<dees-workspace></dees-workspace>
+```
+
+#### `DeesWorkspaceMonaco`
+Monaco Editor integration for code editing with full IntelliSense, syntax highlighting, and language support.
+
+```typescript
+<dees-workspace-monaco
  .value=${code}
-  @change=${handleCodeChange}
  .language=${'typescript'}
-  .theme=${'vs-dark'}
-  .options=${{
-    lineNumbers: true,
-    minimap: { enabled: true },
-    autoClosingBrackets: 'always'
-  }}
-></dees-editor>
+  @change=${handleCodeChange}
+></dees-workspace-monaco>
 ```

-#### `DeesTerminal`
-Terminal emulator component for command-line interface.
+#### `DeesWorkspaceDiffEditor`
+Side-by-side diff editor powered by Monaco for comparing file versions.

 ```typescript
-<dees-terminal
-  .commands=${{
-    'echo': (args) => `Echo: ${args.join(' ')}`,
-    'help': () => 'Available commands: echo, help'
-  }}
-  .prompt=${'$'}
-  .welcomeMessage=${'Welcome! Type "help" for available commands.'}
-></dees-terminal>
+<dees-workspace-diff-editor
+  .originalValue=${originalCode}
+  .modifiedValue=${modifiedCode}
+  .language=${'typescript'}
+></dees-workspace-diff-editor>
 ```

-#### `DeesUpdater`
-Component for managing application updates and version control.
+#### `DeesWorkspaceFiletree`
+File tree navigation component with expand/collapse, file icons, and selection.

 ```typescript
-<dees-updater
-  .currentVersion=${'1.5.2'}
-  .checkInterval=${3600000}
-  .autoUpdate=${false}
-  @update-available=${handleUpdateAvailable}
-></dees-updater>
+<dees-workspace-filetree
+  .files=${fileTreeData}
+  @file-select=${handleFileSelect}
+></dees-workspace-filetree>
 ```

+#### `DeesWorkspaceTerminal`
+Terminal emulator component powered by xterm.js.
+
+```typescript
+<dees-workspace-terminal></dees-workspace-terminal>
+```
+
+#### `DeesWorkspaceTerminalPreview`
+Terminal with integrated preview pane for output visualization.
+
+#### `DeesWorkspaceMarkdown`
+Markdown editor with live preview.
+
+#### `DeesWorkspaceMarkdownoutlet`
+Read-only markdown renderer for documentation display.
+
+#### `DeesWorkspaceBottombar`
+IDE-style bottom status bar for the workspace.
+
 ---

 ### Pre-built Templates
@@ -1582,6 +1767,13 @@ interface IViewActivationContext {
  viewId: string;
  params?: Record<string, string>;
 }
+
+// Tile folder item (for DeesTileFolder)
+interface ITileFolderItem {
+  type: 'pdf' | 'image' | 'audio' | 'video' | 'note' | 'folder' | 'unknown';
+  thumbnailSrc?: string;
+  name: string;
+}
 ```

 ---