# @design.estate/dees-catalog
An extensive library for building modern web applications with dynamic components using Web Components, JavaScript, and TypeScript.

## Install
To install the `@design.estate/dees-catalog` library, you can use npm or any other compatible JavaScript package manager:

```bash
npm install @design.estate/dees-catalog
```

## Components Overview

| Category | Components |
|----------|------------|
| Core UI | `DeesButton`, `DeesButtonExit`, `DeesButtonGroup`, `DeesBadge`, `DeesChips`, `DeesHeading`, `DeesHint`, `DeesIcon`, `DeesLabel`, `DeesPanel`, `DeesSearchbar`, `DeesSpinner`, `DeesToast`, `DeesWindowcontrols` |
| Forms | `DeesForm`, `DeesInputText`, `DeesInputCheckbox`, `DeesInputDropdown`, `DeesInputRadiogroup`, `DeesInputFileupload`, `DeesInputIban`, `DeesInputPhone`, `DeesInputQuantitySelector`, `DeesInputMultitoggle`, `DeesInputTags`, `DeesInputTypelist`, `DeesInputRichtext`, `DeesInputWysiwyg`, `DeesFormSubmit` |
| Layout | `DeesAppuiBase`, `DeesAppuiMainmenu`, `DeesAppuiMainselector`, `DeesAppuiMaincontent`, `DeesAppuiAppbar`, `DeesAppuiActivitylog`, `DeesAppuiProfiledropdown`, `DeesAppuiTabs`, `DeesAppuiView`, `DeesMobileNavigation` |
| Data Display | `DeesTable`, `DeesDataviewCodebox`, `DeesDataviewStatusobject`, `DeesPdf`, `DeesStatsGrid`, `DeesPagination` |
| Visualization | `DeesChartArea`, `DeesChartLog` |
| Dialogs & Overlays | `DeesModal`, `DeesContextmenu`, `DeesSpeechbubble`, `DeesWindowlayer` |
| Navigation | `DeesStepper`, `DeesProgressbar`, `DeesMobileNavigation` |
| Development | `DeesEditor`, `DeesEditorMarkdown`, `DeesEditorMarkdownoutlet`, `DeesTerminal`, `DeesUpdater` |
| Auth & Utilities | `DeesSimpleAppdash`, `DeesSimpleLogin` |

## Detailed Component Documentation

### Core UI Components

#### `DeesButton`
A versatile button component supporting multiple styles and states.

```typescript
// Basic usage
const button = document.createElement('dees-button');
button.text = 'Click me';

// With options
<dees-button
  type="highlighted"  // Options: normal, highlighted, discreet
  status="pending"    // Options: normal, pending, success, error
  disabled={false}    // Optional: disables the button
  @click=${handleClick}
>Click me</dees-button>
```

#### `DeesBadge`
Display status indicators or counts with customizable styles.

```typescript
<dees-badge
  type="success"  // Options: default, primary, success, warning, error
  text="New"      // Text to display
  rounded        // Optional: applies rounded corners
></dees-badge>
```

#### `DeesChips`
Interactive chips/tags with selection capabilities.

```typescript
<dees-chips
  selectionMode="multiple"  // Options: none, single, multiple
  chipsAreRemovable        // Optional: allows removing chips
  .selectableChips=${[
    { key: 'tag1', value: 'Important' },
    { key: 'tag2', value: 'Urgent' }
  ]}
  @selection-change=${handleSelection}
></dees-chips>
```

#### `DeesIcon`
Display icons from various icon sets including FontAwesome.

```typescript
<dees-icon
  icon="home"           // FontAwesome icon name
  type="solid"          // Options: solid, regular, brands
  size="1.5rem"         // Optional: custom size
  color="#007bff"       // Optional: custom color
></dees-icon>
```

#### `DeesLabel`
Text label component with optional icon and status indicators.

```typescript
<dees-label
  text="Status"         // Label text
  icon="info-circle"    // Optional: icon name
  type="info"           // Options: default, info, success, warning, error
  size="medium"         // Options: small, medium, large
></dees-label>
```

#### `DeesSpinner`
Loading indicator with customizable appearance.

```typescript
<dees-spinner
  size="medium"         // Options: small, medium, large
  type="primary"        // Options: primary, secondary, light, dark
  overlay              // Optional: adds a full-screen overlay
></dees-spinner>
```

#### `DeesToast`
Notification toast messages with various styles, positions, and auto-dismiss functionality.

```typescript
// Programmatic usage
DeesToast.show({
  message: 'Operation successful',
  type: 'success',      // Options: info, success, warning, error
  duration: 3000,       // Time in milliseconds before auto-dismiss
  position: 'top-right' // Options: top-right, top-left, bottom-right, bottom-left, top-center, bottom-center
});

// Convenience methods
DeesToast.info('Information message');
DeesToast.success('Success message');
DeesToast.warning('Warning message');
DeesToast.error('Error message');

// Advanced control
const toast = await DeesToast.show({
  message: 'Processing...',
  type: 'info',
  duration: 0  // No auto-dismiss
});

// Later dismiss programmatically
toast.dismiss();

// Component usage (not typically used directly)
<dees-toast
  message="Changes saved"
  type="success"
  duration="3000"
></dees-toast>
```

Key Features:
- Multiple toast types with distinct icons and colors
- 6 position options for flexible placement
- Auto-dismiss with visual progress indicator
- Manual dismiss by clicking
- Smooth animations and transitions
- Automatic stacking of multiple toasts
- Theme-aware styling
- Programmatic control

#### `DeesButtonExit`
Exit/close button component with consistent styling.

```typescript
<dees-button-exit
  @click=${handleClose}
></dees-button-exit>
```

#### `DeesButtonGroup`
Container for grouping related buttons together.

```typescript
<dees-button-group
  .buttons=${[
    { text: 'Save', type: 'highlighted', action: handleSave },
    { text: 'Cancel', type: 'normal', action: handleCancel }
  ]}
  spacing="medium"    // Options: small, medium, large
></dees-button-group>
```

#### `DeesHeading`
Consistent heading component with level and styling options.

```typescript
<dees-heading
  level={1}           // 1-6 for H1-H6
  text="Page Title"
  .subheading=${'Optional subtitle'}
  centered           // Optional: center alignment
></dees-heading>
```

#### `DeesHint`
Hint/tooltip component for providing contextual help.

```typescript
<dees-hint
  text="This field is required"
  type="info"        // Options: info, warning, error, success
  position="top"     // Options: top, bottom, left, right
></dees-hint>
```

#### `DeesPanel`
Container component for grouping related content with optional title and actions.

```typescript
<dees-panel
  .title=${'Panel Title'}
  .subtitle=${'Optional subtitle'}
  collapsible        // Optional: allow collapse/expand
  collapsed={false}  // Initial collapsed state
  .actions=${[
    { icon: 'settings', action: handleSettings }
  ]}
>
  <!-- Panel content -->
</dees-panel>
```

#### `DeesSearchbar`
Search input component with suggestions and search handling.

```typescript
<dees-searchbar
  placeholder="Search..."
  .suggestions=${['item1', 'item2', 'item3']}
  showClearButton    // Show clear button when has value
  @search=${handleSearch}
  @suggestion-select=${handleSuggestionSelect}
></dees-searchbar>
```

#### `DeesWindowcontrols`
Window control buttons (minimize, maximize, close) for desktop-like applications.

```typescript
<dees-windowcontrols
  .controls=${['minimize', 'maximize', 'close']}
  @minimize=${handleMinimize}
  @maximize=${handleMaximize}
  @close=${handleClose}
></dees-windowcontrols>
```

### Form Components

#### `DeesForm`
Container component for form elements with built-in validation and data handling.

```typescript
<dees-form
  @formData=${(e) => handleFormData(e.detail)}  // Emitted when form is submitted
  @formValidation=${(e) => handleValidation(e.detail)}  // Emitted during validation
>
  <dees-input-text required></dees-input-text>
  <dees-form-submit>Submit</dees-form-submit>
</dees-form>
```

#### `DeesInputText`
Text input field with validation and formatting options.

```typescript
<dees-input-text
  key="email"           // Unique identifier for form data
  label="Email"         // Input label
  value="initial@value.com"  // Initial value
  required             // Makes the field required
  disabled            // Disables the input
  placeholder="Enter your email"
></dees-input-text>
```

#### `DeesInputCheckbox`
Checkbox input component for boolean values.

```typescript
<dees-input-checkbox
  key="terms"
  label="Accept Terms"
  checked             // Initial checked state
  required
  @change=${handleChange}
></dees-input-checkbox>
```

#### `DeesInputDropdown`
Dropdown selection component with search and filtering capabilities.

```typescript
<dees-input-dropdown
  key="country"
  label="Select Country"
  .options=${[
    { key: 'us', option: 'United States' },
    { key: 'uk', option: 'United Kingdom' }
  ]}
  searchable          // Enables search functionality
  multiple           // Allows multiple selections
></dees-input-dropdown>
```

#### `DeesInputFileupload`
File upload component with drag-and-drop support.

```typescript
<dees-input-fileupload
  key="documents"
  label="Upload Files"
  multiple            // Allow multiple file selection
  accept=".pdf,.doc"  // Accepted file types
  maxSize="5MB"      // Maximum file size
  @upload=${handleUpload}
></dees-input-fileupload>
```

#### `DeesInputIban`
Specialized input for IBAN (International Bank Account Number) with validation.

```typescript
<dees-input-iban
  key="bankAccount"
  label="IBAN"
  country="DE"        // Default country format
  required
  @validate=${handleIbanValidation}
></dees-input-iban>
```

#### `DeesInputPhone`
Phone number input with country code selection and formatting.

```typescript
<dees-input-phone
  key="phone"
  label="Phone Number"
  defaultCountry="US"  // Default country code
  required
  @validate=${handlePhoneValidation}
></dees-input-phone>
```

#### `DeesInputQuantitySelector`
Numeric input with increment/decrement controls.

```typescript
<dees-input-quantity-selector
  key="quantity"
  label="Quantity"
  min="0"             // Minimum value
  max="100"           // Maximum value
  step="1"            // Increment/decrement step
  value="1"           // Initial value
></dees-input-quantity-selector>
```

#### `DeesInputMultitoggle`
Multi-state toggle button group.

```typescript
<dees-input-multitoggle
  key="status"
  label="Status"
  .options=${[
    { key: 'active', label: 'Active' },
    { key: 'pending', label: 'Pending' },
    { key: 'inactive', label: 'Inactive' }
  ]}
  value="active"      // Initial selected value
></dees-input-multitoggle>
```

#### `DeesInputRadiogroup`
Radio button group for single-choice selections with internal state management.

```typescript
<dees-input-radiogroup
  key="plan"
  label="Select Plan"
  .options=${['Free', 'Pro', 'Enterprise']}
  selectedOption="Pro"
  required
  @change=${handlePlanChange}
></dees-input-radiogroup>

// With custom option objects
<dees-input-radiogroup
  key="priority"
  label="Priority Level"
  .options=${[
    { key: 'low', label: 'Low Priority' },
    { key: 'medium', label: 'Medium Priority' },
    { key: 'high', label: 'High Priority' }
  ]}
  selectedOption="medium"
></dees-input-radiogroup>
```

#### `DeesInputTags`
Tag input component for managing lists of tags with auto-complete and validation.

```typescript
<dees-input-tags
  key="skills"
  label="Skills"
  .value=${['JavaScript', 'TypeScript', 'CSS']}
  placeholder="Add a skill..."
  .suggestions=${[
    'JavaScript', 'TypeScript', 'Python', 'Go', 'Rust',
    'React', 'Vue', 'Angular', 'Node.js', 'Docker'
  ]}
  maxTags={10}  // Optional: limit number of tags
  required
  @change=${handleTagsChange}
></dees-input-tags>
```

Key Features:
- Add tags by pressing Enter or typing comma/semicolon
- Remove tags with click or backspace
- Auto-complete suggestions with keyboard navigation
- Maximum tag limit support
- Full theme support
- Form validation integration

#### `DeesInputTypelist`
Dynamic list input for managing arrays of typed values.

```typescript
<dees-input-typelist
  key="features"
  label="Product Features"
  placeholder="Add a feature..."
  .value=${['Feature 1', 'Feature 2']}
  @change=${handleFeaturesChange}
></dees-input-typelist>
```

#### `DeesInputRichtext`
Rich text editor with formatting toolbar powered by TipTap.

```typescript
<dees-input-richtext
  key="content"
  label="Article Content"
  .value=${htmlContent}
  placeholder="Start writing..."
  minHeight={300}      // Minimum editor height
  showWordCount={true} // Show word/character count
  @change=${handleContentChange}
></dees-input-richtext>
```

Key Features:
- Full formatting toolbar (bold, italic, underline, strike, etc.)
- Heading levels (H1-H6)
- Lists (bullet, ordered)
- Links with URL editing
- Code blocks and inline code
- Blockquotes
- Horizontal rules
- Undo/redo support
- Word and character count
- HTML output

#### `DeesInputWysiwyg`
Advanced block-based editor with slash commands and rich content blocks.

```typescript
<dees-input-wysiwyg
  key="document"
  label="Document Editor"
  .value=${documentContent}
  outputFormat="html"  // Options: html, markdown, json
  @change=${handleDocumentChange}
></dees-input-wysiwyg>
```

Key Features:
- Slash commands for quick formatting
- Block-based editing (paragraphs, headings, lists, etc.)
- Drag and drop block reordering
- Multiple output formats
- Keyboard shortcuts
- Collaborative editing ready
- Extensible block types

#### `DeesFormSubmit`
Submit button component specifically designed for `DeesForm`.

```typescript
<dees-form-submit
  disabled            // Optional: disable submit button
  status="normal"     // Options: normal, pending, success, error
>Submit Form</dees-form-submit>
```

### Layout Components

#### `DeesAppuiBase`
Base container component for application layout structure with integrated appbar, menu system, and content areas.

```typescript
<dees-appui-base
  // Appbar configuration
  .appbarMenuItems=${[
    {
      name: 'File',
      action: async () => {},
      submenu: [
        { name: 'New', shortcut: 'Cmd+N', iconName: 'file-plus', action: async () => {} },
        { name: 'Open', shortcut: 'Cmd+O', iconName: 'folder-open', action: async () => {} },
        { divider: true },
        { name: 'Save', shortcut: 'Cmd+S', iconName: 'save', action: async () => {} }
      ]
    },
    {
      name: 'Edit',
      action: async () => {},
      submenu: [
        { name: 'Undo', shortcut: 'Cmd+Z', iconName: 'undo', action: async () => {} },
        { name: 'Redo', shortcut: 'Cmd+Shift+Z', iconName: 'redo', action: async () => {} }
      ]
    }
  ]}
  .appbarBreadcrumbs=${'Dashboard > Overview'}
  .appbarTheme=${'dark'}
  .appbarUser=${{
    name: 'John Doe',
    status: 'online'
  }}
  .appbarShowSearch=${true}
  .appbarShowWindowControls=${true}
  
  // Main menu configuration (left sidebar)
  .mainmenuTabs=${[
    { key: 'dashboard', iconName: 'home', action: () => {} },
    { key: 'projects', iconName: 'folder', action: () => {} },
    { key: 'settings', iconName: 'cog', action: () => {} }
  ]}
  .mainmenuSelectedTab=${selectedTab}
  
  // Selector configuration (second sidebar)
  .mainselectorOptions=${[
    { key: 'Overview', action: () => {} },
    { key: 'Components', action: () => {} },
    { key: 'Services', action: () => {} }
  ]}
  .mainselectorSelectedOption=${selectedOption}
  
  // Main content tabs
  .maincontentTabs=${[
    { key: 'tab1', iconName: 'file', action: () => {} }
  ]}
  
  // Event handlers
  @appbar-menu-select=${(e) => handleMenuSelect(e.detail)}
  @appbar-breadcrumb-navigate=${(e) => handleBreadcrumbNav(e.detail)}
  @appbar-search-click=${() => handleSearch()}
  @appbar-user-menu-open=${() => handleUserMenu()}
  @mainmenu-tab-select=${(e) => handleTabSelect(e.detail)}
  @mainselector-option-select=${(e) => handleOptionSelect(e.detail)}
>
  <div slot="maincontent">
    <!-- Your main application content goes here -->
  </div>
</dees-appui-base>
```

Key Features:
- **Integrated Layout System**: Automatically arranges appbar, sidebars, and content area
- **Centralized Configuration**: Pass properties to all child components from one place
- **Event Propagation**: All child component events are re-emitted for easy handling
- **Responsive Grid**: Uses CSS Grid for flexible, responsive layout
- **Slot Support**: Main content area supports custom content via slots

Layout Structure:
```
┌─────────────────────────────────────────────────┐
│                    AppBar                       │
├────┬──────────────┬─────────────────┬──────────┤
│    │              │                 │          │
│ M  │   Selector   │   Main Content  │ Activity │
│ e  │              │                 │   Log    │
│ n  │              │                 │          │
│ u  │              │                 │          │
│    │              │                 │          │
└────┴──────────────┴─────────────────┴──────────┘
```

Grid Configuration:
- Main Menu: 60px width
- Selector: 240px width
- Main Content: Flexible (1fr)
- Activity Log: 240px width

Child Component Access:
```typescript
// Access child components after firstUpdated
const base = document.querySelector('dees-appui-base');
base.appbar;       // DeesAppuiAppbar instance
base.mainmenu;     // DeesAppuiMainmenu instance
base.mainselector; // DeesAppuiMainselector instance
base.maincontent;  // DeesAppuiMaincontent instance
base.activitylog;  // DeesAppuiActivitylog instance
```

Best Practices:
1. **Configuration**: Set all properties on the base component for consistency
2. **Event Handling**: Listen to events on the base component rather than child components
3. **Content**: Use the `maincontent` slot for your application's primary interface
4. **State Management**: Manage selected tabs and options at the base component level

#### `DeesAppuiMainmenu`
Main navigation menu component for application-wide navigation.

```typescript
<dees-appui-mainmenu
  .menuItems=${[
    {
      key: 'dashboard',
      label: 'Dashboard',
      icon: 'home',
      action: () => handleNavigation('dashboard')
    },
    {
      key: 'settings',
      label: 'Settings',
      icon: 'cog',
      action: () => handleNavigation('settings')
    }
  ]}
  collapsed           // Optional: show collapsed version
  position="left"     // Options: left, right
></dees-appui-mainmenu>
```

#### `DeesAppuiMainselector`
Secondary navigation component for sub-section selection.

```typescript
<dees-appui-mainselector
  .items=${[
    {
      key: 'section1',
      label: 'Section 1',
      icon: 'folder',
      action: () => selectSection('section1')
    }
  ]}
  selectedKey="section1"  // Currently selected section
  @selection-change=${handleSectionChange}
></dees-appui-mainselector>
```

#### `DeesAppuiMaincontent`
Main content area with tab management support.

```typescript
<dees-appui-maincontent
  .tabs=${[
    {
      key: 'tab1',
      label: 'Tab 1',
      content: html`<div>Tab 1 Content</div>`,
      action: () => handleTabAction('tab1')
    }
  ]}
  selectedTab="tab1"     // Currently active tab
  @tab-change=${handleTabChange}
></dees-appui-maincontent>
```

#### `DeesAppuiAppbar`
Professional application bar component with hierarchical menus, breadcrumb navigation, and user account management.

```typescript
<dees-appui-appbar
  .menuItems=${[
    {
      name: 'File',
      action: async () => {},  // No-op for parent menu items
      submenu: [
        { 
          name: 'New File', 
          shortcut: 'Cmd+N', 
          iconName: 'file-plus', 
          action: async () => handleNewFile() 
        },
        { 
          name: 'Open...', 
          shortcut: 'Cmd+O', 
          iconName: 'folder-open', 
          action: async () => handleOpen() 
        },
        { divider: true },  // Menu separator
        { 
          name: 'Save', 
          shortcut: 'Cmd+S', 
          iconName: 'save', 
          action: async () => handleSave(),
          disabled: true  // Disabled state
        }
      ]
    },
    {
      name: 'Edit',
      action: async () => {},
      submenu: [
        { name: 'Undo', shortcut: 'Cmd+Z', iconName: 'undo', action: async () => handleUndo() },
        { name: 'Redo', shortcut: 'Cmd+Shift+Z', iconName: 'redo', action: async () => handleRedo() }
      ]
    }
  ]}
  .breadcrumbs=${'Project > src > components > AppBar.ts'}
  .breadcrumbSeparator=${' > '}
  .showWindowControls=${true}
  .showSearch=${true}
  .theme=${'dark'}  // Options: 'light' | 'dark'
  .user=${{
    name: 'John Doe',
    avatar: '/path/to/avatar.jpg',  // Optional
    status: 'online'  // Options: 'online' | 'offline' | 'busy' | 'away'
  }}
  @menu-select=${(e) => handleMenuSelect(e.detail.item)}
  @breadcrumb-navigate=${(e) => handleBreadcrumbClick(e.detail)}
  @search-click=${() => handleSearchClick()}
  @user-menu-open=${() => handleUserMenuOpen()}
></dees-appui-appbar>
```

Key Features:
- **Hierarchical Menu System**
  - Top-level text-only menus (following desktop UI standards)
  - Dropdown submenus with icons and keyboard shortcuts
  - Support for nested submenus
  - Menu dividers for visual grouping
  - Disabled state support
  
- **Keyboard Navigation**
  - Tab navigation between top-level items
  - Arrow keys for dropdown navigation (Up/Down in dropdowns, Left/Right between top items)
  - Enter to select items
  - Escape to close dropdowns
  - Home/End keys for first/last item
  
- **Breadcrumb Navigation**
  - Customizable breadcrumb trail
  - Configurable separator
  - Click events for navigation
  
- **User Account Section**
  - User avatar with fallback to initials
  - Status indicator (online, offline, busy, away)
  - Click handler for user menu
  
- **Visual Features**
  - Light and dark theme support
  - Smooth animations and transitions
  - Window controls integration
  - Search icon with click handler
  - Responsive layout using CSS Grid
  
- **Accessibility**
  - Full ARIA support (menubar, menuitem roles)
  - Keyboard navigation
  - Focus management
  - Screen reader compatible

Menu Item Interface:
```typescript
// Regular menu item
interface IAppBarMenuItemRegular {
  name: string;          // Display text
  action: () => Promise<any>;  // Click handler
  iconName?: string;     // Optional icon (for dropdown items)
  shortcut?: string;     // Keyboard shortcut display
  submenu?: IAppBarMenuItem[];  // Nested menu items
  disabled?: boolean;    // Disabled state
  checked?: boolean;     // For checkbox menu items
  radioGroup?: string;   // For radio button menu items
}

// Divider item
interface IAppBarMenuDivider {
  divider: true;
}

// Combined type
type IAppBarMenuItem = IAppBarMenuItemRegular | IAppBarMenuDivider;
```

Best Practices:
1. **Menu Structure**
   - Keep top-level menus text-only (no icons)
   - Use icons in dropdown items for visual clarity
   - Group related actions with dividers
   - Provide keyboard shortcuts for common actions
   
2. **Navigation**
   - Use breadcrumbs for deep navigation hierarchies
   - Keep breadcrumb labels concise
   - Provide meaningful navigation events
   
3. **User Experience**
   - Show user status when relevant
   - Provide clear visual feedback
   - Ensure smooth transitions
   - Handle edge cases (long menus, small screens)
   
4. **Accessibility**
   - Always provide text labels
   - Ensure keyboard navigation works
   - Test with screen readers
   - Maintain focus management

#### `DeesAppuiActivitylog`
Activity log component for displaying system events and user actions.

```typescript
<dees-appui-activitylog
  .entries=${[
    {
      timestamp: new Date(),
      type: 'info',
      message: 'User logged in',
      details: { userId: '123' }
    },
    {
      timestamp: new Date(),
      type: 'error',
      message: 'Failed to save document',
      details: { error: 'Network error' }
    }
  ]}
  maxEntries={100}    // Maximum entries to display
  @entry-click=${handleEntryClick}
></dees-appui-activitylog>
```

#### `DeesAppuiProfiledropdown`
User profile dropdown component with status and menu options.

```typescript
<dees-appui-profiledropdown
  .user=${{
    name: 'John Doe',
    email: 'john@example.com',
    avatar: '/path/to/avatar.jpg',
    status: 'online'  // Options: online, offline, busy, away
  }}
  .menuItems=${[
    { name: 'Profile', iconName: 'user', action: async () => {} },
    { name: 'Settings', iconName: 'settings', action: async () => {} },
    { divider: true },
    { name: 'Logout', iconName: 'logOut', action: async () => {} }
  ]}
  @status-change=${handleStatusChange}
></dees-appui-profiledropdown>
```

#### `DeesAppuiTabs`
Tab navigation component for organizing content sections.

```typescript
<dees-appui-tabs
  .tabs=${[
    {
      key: 'overview',
      label: 'Overview',
      icon: 'home',
      content: html`<div>Overview content</div>`
    },
    {
      key: 'details',
      label: 'Details',
      icon: 'info',
      content: html`<div>Details content</div>`
    }
  ]}
  selectedTab="overview"
  @tab-change=${handleTabChange}
></dees-appui-tabs>
```

#### `DeesAppuiView`
View container component for consistent page layouts.

```typescript
<dees-appui-view
  viewTitle="Dashboard"
  viewSubtitle="System Overview"
  .headerActions=${[
    { icon: 'refresh', action: handleRefresh },
    { icon: 'settings', action: handleSettings }
  ]}
>
  <!-- View content -->
</dees-appui-view>
```

#### `DeesMobileNavigation`
Responsive navigation component for mobile devices.

```typescript
<dees-mobile-navigation
  .menuItems=${[
    {
      key: 'home',
      label: 'Home',
      icon: 'home',
      action: () => navigate('home')
    },
    {
      key: 'profile',
      label: 'Profile',
      icon: 'user',
      action: () => navigate('profile')
    }
  ]}
  activeKey="home"    // Currently active item
  position="bottom"   // Options: bottom, top
  @item-click=${handleNavigationClick}
></dees-mobile-navigation>
```

### Data Display Components

#### `DeesTable`
Advanced table component with sorting, filtering, and action support.

```typescript
<dees-table
  .data=${tableData}
  .displayFunction=${(item) => ({
    name: item.name,
    date: item.date,
    amount: item.amount,
    description: item.description
  })}
  .dataActions=${[
    {
      name: 'Edit',
      icon: 'edit',
      action: (item) => handleEdit(item)
    },
    {
      name: 'Delete',
      icon: 'trash',
      action: (item) => handleDelete(item)
    }
  ]}
  heading1="Transactions"
  heading2="Recent Activity"
  searchable           // Enable search functionality
  dataName="transaction"  // Name for single data item
  @selection-change=${handleSelectionChange}
></dees-table>
```

#### `DeesDataviewCodebox`
Code display component with syntax highlighting and line numbers.

```typescript
<dees-dataview-codebox
  progLang="typescript"  // Programming language for syntax highlighting
  .codeToDisplay=${`
    import { html } from '@design.estate/dees-element';
    
    export const myComponent = () => {
      return html\`<div>Hello World</div>\`;
    };
  `}
></dees-dataview-codebox>
```

#### `DeesDataviewStatusobject`
Status display component for complex objects with nested status indicators.

```typescript
<dees-dataview-statusobject
  .statusObject=${{
    id: '1',
    name: 'System Status',
    combinedStatus: 'partly_ok',
    combinedStatusText: 'Partially OK',
    details: [
      {
        name: 'Database',
        value: 'Connected',
        status: 'ok',
        statusText: 'OK'
      },
      {
        name: 'API Service',
        value: 'Degraded',
        status: 'partly_ok',
        statusText: 'Partially OK'
      }
    ]
  }}
></dees-dataview-statusobject>
```

#### `DeesPdf`
PDF viewer component with navigation and zoom controls.

```typescript
<dees-pdf
  source="path/to/document.pdf"  // URL or base64 encoded PDF
  page={1}            // Current page number
  scale={1.0}         // Zoom level
  .controls=${[       // Optional: customize available controls
    'zoom',
    'download',
    'print',
    'navigation'
  ]}
  @page-change=${handlePageChange}
  @document-loaded=${handleDocumentLoaded}
></dees-pdf>
```

Key Features:
- `DeesTable`:
  - Sortable columns
  - Searchable content
  - Customizable row actions
  - Selection support
  - Form compatibility
  - Custom display formatting

- `DeesDataviewCodebox`:
  - Syntax highlighting for multiple languages
  - Line numbering
  - Copy to clipboard functionality
  - Custom theme support
  - Window-like appearance with controls

- `DeesDataviewStatusobject`:
  - Hierarchical status display
  - Color-coded status indicators
  - Expandable details
  - JSON export capability
  - Customizable styling

- `DeesPdf`:
  - Page navigation
  - Zoom controls
  - Download support
  - Print functionality
  - Responsive layout
  - Loading states

#### `DeesStatsGrid`
A responsive grid component for displaying statistical data with various visualization types including numbers, gauges, percentages, and trends.

```typescript
<dees-statsgrid
  .tiles=${[
    {
      id: 'revenue',
      title: 'Total Revenue',
      value: 125420,
      unit: '$',
      type: 'number',
      icon: 'faDollarSign',
      description: '+12.5% from last month',
      color: '#22c55e',
      actions: [
        {
          name: 'View Details',
          iconName: 'faChartLine',
          action: async () => {
            console.log('Viewing revenue details');
          }
        },
        {
          name: 'Export Data',
          iconName: 'faFileExport',
          action: async () => {
            console.log('Exporting revenue data');
          }
        }
      ]
    },
    {
      id: 'cpu',
      title: 'CPU Usage',
      value: 73,
      type: 'gauge',
      icon: 'faMicrochip',
      gaugeOptions: {
        min: 0,
        max: 100,
        thresholds: [
          { value: 0, color: '#22c55e' },
          { value: 60, color: '#f59e0b' },
          { value: 80, color: '#ef4444' }
        ]
      }
    },
    {
      id: 'storage',
      title: 'Storage Used',
      value: 65,
      type: 'percentage',
      icon: 'faHardDrive',
      description: '650 GB of 1 TB',
      color: '#3b82f6'
    },
    {
      id: 'requests',
      title: 'API Requests',
      value: '1.2k',
      unit: '/min',
      type: 'trend',
      icon: 'faServer',
      trendData: [45, 52, 38, 65, 72, 68, 75, 82, 79, 85, 88, 92]
    },
    {
      id: 'uptime',
      title: 'System Uptime',
      value: '99.95%',
      type: 'text',
      icon: 'faCheckCircle',
      color: '#22c55e',
      description: 'Last 30 days'
    }
  ]}
  .gridActions=${[
    {
      name: 'Refresh',
      iconName: 'faSync',
      action: async () => {
        console.log('Refreshing stats...');
      }
    },
    {
      name: 'Export Report',
      iconName: 'faFileExport',
      action: async () => {
        console.log('Exporting stats report...');
      }
    }
  ]}
  .minTileWidth=${250}  // Minimum tile width in pixels
  .gap=${16}            // Gap between tiles in pixels
></dees-statsgrid>
```

Key Features:
- Auto-responsive grid layout with configurable minimum tile width
- Multiple tile types for different data visualizations
- Full theme support (light/dark mode)
- Interactive tiles with action support
- Grid-level and tile-level actions
- Smooth animations and transitions
- Icon support for visual hierarchy

Tile Types:
1. **`number`** - Display numeric values with optional units
   - Large, prominent value display
   - Optional unit display
   - Custom color support
   - Description text

2. **`gauge`** - Circular gauge visualization
   - Min/max value configuration
   - Color thresholds for visual alerts
   - Animated value transitions
   - Compact circular design

3. **`percentage`** - Progress bar visualization
   - Horizontal progress bar
   - Percentage display overlay
   - Custom color support
   - Ideal for capacity metrics

4. **`trend`** - Mini sparkline chart
   - Array of numeric values for trend data
   - Area chart visualization
   - Current value display
   - Responsive SVG rendering

5. **`text`** - Simple text display
   - Flexible text content
   - Custom color support
   - Ideal for status messages

Action System:
- **Grid Actions**: Displayed as buttons in the grid header
  - Apply to the entire stats grid
  - Use standard `dees-button` components
  - Support icons and text

- **Tile Actions**: Context-specific actions per tile
  - Single action: Direct click on tile
  - Multiple actions: Right-click context menu
  - Actions access tile data through closures
  - Consistent with other library components

Configuration Options:
- `tiles`: Array of `IStatsTile` objects defining the grid content
- `gridActions`: Array of actions for the entire grid
- `minTileWidth`: Minimum width for tiles (default: 250px)
- `gap`: Space between tiles (default: 16px)

Best Practices:
1. **Data Organization**
   - Group related metrics together
   - Use consistent units and scales
   - Provide meaningful descriptions
   - Choose appropriate tile types for data

2. **Visual Hierarchy**
   - Use colors strategically for alerts
   - Include relevant icons
   - Keep titles concise
   - Balance tile types for visual interest

3. **Interactivity**
   - Provide relevant actions for detailed views
   - Use tile actions for item-specific operations
   - Use grid actions for global operations
   - Keep action names clear and concise

4. **Performance**
   - Update only changed tiles
   - Use reasonable update intervals
   - Batch updates when possible
   - Consider data volume for trends

Common Use Cases:
- System monitoring dashboards
- Business intelligence displays
- Performance metrics
- Resource utilization
- Real-time statistics
- KPI tracking

Integration Example:
```typescript
// Real-time updates
setInterval(() => {
  const grid = document.querySelector('dees-statsgrid');
  const updatedTiles = [...grid.tiles];
  
  // Update specific tile
  const cpuTile = updatedTiles.find(t => t.id === 'cpu');
  cpuTile.value = Math.round(Math.random() * 100);
  
  // Update trend data
  const trendTile = updatedTiles.find(t => t.id === 'requests');
  trendTile.trendData = [...trendTile.trendData.slice(1), 
    Math.round(Math.random() * 100)];
  
  grid.tiles = updatedTiles;
}, 3000);
```

#### `DeesPagination`
Pagination component for navigating through large datasets.

```typescript
<dees-pagination
  totalItems={500}
  itemsPerPage={20}
  currentPage={1}
  maxVisiblePages={7}  // Maximum page numbers to display
  @page-change=${handlePageChange}
></dees-pagination>
```

Key Features:
- Page number navigation
- Previous/next buttons
- Jump to first/last page
- Configurable items per page
- Responsive design
- Keyboard navigation support

### Visualization Components

#### `DeesChartArea`
Area chart component built on ApexCharts for visualizing time-series data.

```typescript
<dees-chart-area
  label="System Usage"    // Chart title
  .series=${[
    {
      name: 'CPU',
      data: [
        { x: '2025-01-15T03:00:00', y: 25 },
        { x: '2025-01-15T07:00:00', y: 30 },
        { x: '2025-01-15T11:00:00', y: 20 }
      ]
    },
    {
      name: 'Memory',
      data: [
        { x: '2025-01-15T03:00:00', y: 10 },
        { x: '2025-01-15T07:00:00', y: 12 },
        { x: '2025-01-15T11:00:00', y: 10 }
      ]
    }
  ]}
></dees-chart-area>
```

Key Features:
- Responsive design with automatic resizing
- Gradient fill support
- Interactive tooltips
- Grid customization
- Multiple series support
- Time-based x-axis
- Customizable styling

Configuration Options:
- Series data format: `{ x: timestamp, y: value }`
- Tooltip customization with datetime formatting
- Grid line styling and colors
- Gradient fill properties
- Chart dimensions and responsiveness

#### `DeesChartLog`
Specialized chart component for visualizing log data and events.

```typescript
<dees-chart-log
  label="System Events"
  .data=${[
    {
      timestamp: '2025-01-15T03:00:00',
      event: 'Server Start',
      type: 'info'
    },
    {
      timestamp: '2025-01-15T03:15:00',
      event: 'Error Detected',
      type: 'error'
    }
  ]}
  .filters=${['info', 'warning', 'error']}  // Event types to display
  @event-click=${handleEventClick}
></dees-chart-log>
```

Key Features:
- Event timeline visualization
- Color-coded event types
- Interactive event details
- Filtering capabilities
- Zoom and pan support
- Time-based navigation
- Event clustering

Common Use Cases:
- System monitoring
- Performance tracking
- Resource utilization
- Event logging
- Time-series analysis
- Trend visualization

Best Practices:
1. Data Formatting
   - Use consistent timestamp formats
   - Provide meaningful series names
   - Include appropriate data points

2. Responsiveness
   - Charts automatically adjust to container size
   - Consider mobile viewports
   - Set appropriate min/max dimensions

3. Interaction
   - Enable relevant tooltips
   - Configure meaningful click handlers
   - Implement appropriate zoom levels

4. Styling
   - Use consistent color schemes
   - Configure appropriate grid lines
   - Set readable font sizes

### Dialogs & Overlays Components

#### `DeesModal`
Modal dialog component with customizable content and actions.

```typescript
// Programmatic usage
DeesModal.createAndShow({
  heading: 'Confirm Action',
  content: html`
    <dees-form>
      <dees-input-text
        .label=${'Enter reason'}
      ></dees-input-text>
    </dees-form>
  `,
  menuOptions: [
    {
      name: 'Cancel',
      action: async (modal) => {
        modal.destroy();
        return null;
      }
    },
    {
      name: 'Confirm',
      action: async (modal) => {
        // Handle confirmation
        modal.destroy();
        return null;
      }
    }
  ]
});

// Component usage
<dees-modal
  heading="Settings"
  .content=${settingsContent}
  .menuOptions=${actions}
></dees-modal>
```

Key Features:
- Backdrop blur effect
- Customizable content using HTML templates
- Flexible action buttons
- Outside click handling
- Animated transitions
- Automatic window layer management

#### `DeesContextmenu`
Context menu component for right-click actions.

```typescript
<dees-contextmenu
  .items=${[
    {
      label: 'Edit',
      icon: 'edit',
      action: () => handleEdit()
    },
    {
      label: 'Delete',
      icon: 'trash',
      action: () => handleDelete()
    }
  ]}
  position="right"    // Options: right, left, auto
  @item-click=${handleMenuItemClick}
></dees-contextmenu>
```

#### `DeesSpeechbubble`
Tooltip-style speech bubble component for contextual information.

```typescript
// Programmatic usage
const bubble = await DeesSpeechbubble.createAndShow(
  referenceElement,    // Element to attach to
  'Helpful information about this feature'
);

// Component usage
<dees-speechbubble
  .reffedElement=${targetElement}
  text="Click here to continue"
></dees-speechbubble>
```

Key Features:
- Automatic positioning
- Non-intrusive overlay
- Animated appearance
- Reference element tracking
- Custom styling options

#### `DeesWindowlayer`
Base overlay component used by modal dialogs and other overlay components.

```typescript
// Programmatic usage
const layer = await DeesWindowLayer.createAndShow({
  blur: true,    // Enable backdrop blur
});

// Component usage
<dees-windowlayer
  .options=${{
    blur: true
  }}
  @clicked=${handleOverlayClick}
>
  <div class="content">
    <!-- Overlay content -->
  </div>
</dees-windowlayer>
```

Key Features:
- Backdrop blur support
- Click event handling
- Z-index management
- Animated transitions
- Flexible content container

Best Practices:

1. Modal Dialogs
   - Use for important user interactions
   - Provide clear action buttons
   - Include close/cancel options
   - Handle outside clicks appropriately
   - Use meaningful headings

2. Context Menus
   - Group related actions
   - Use consistent icons
   - Provide keyboard shortcuts
   - Consider position constraints
   - Handle menu item states

3. Speech Bubbles
   - Keep content concise
   - Position strategically
   - Avoid overlapping
   - Consider mobile viewports
   - Use appropriate timing

4. Window Layers
   - Manage z-index carefully
   - Handle backdrop interactions
   - Consider performance impact
   - Implement proper cleanup
   - Manage multiple layers

### Navigation Components

#### `DeesStepper`
Multi-step navigation component for guided user flows.

```typescript
<dees-stepper
  .steps=${[
    {
      key: 'personal',
      label: 'Personal Info',
      content: html`<div>Personal Information Form</div>`,
      validation: () => validatePersonalInfo()
    },
    {
      key: 'address',
      label: 'Address',
      content: html`<div>Address Form</div>`,
      validation: () => validateAddress()
    },
    {
      key: 'confirm',
      label: 'Confirmation',
      content: html`<div>Review and Confirm</div>`
    }
  ]}
  currentStep="personal"
  @step-change=${handleStepChange}
  @complete=${handleComplete}
></dees-stepper>
```

Key Features:
- Linear or non-linear progression
- Step validation
- Progress tracking
- Customizable step content
- Navigation controls
- Step completion indicators

#### `DeesProgressbar`
Progress indicator component for tracking completion status.

```typescript
<dees-progressbar
  value={75}           // Current progress (0-100)
  label="Uploading"    // Optional label
  showPercentage      // Display percentage
  type="determinate"  // Options: determinate, indeterminate
  status="normal"     // Options: normal, success, warning, error
  @progress=${handleProgress}
></dees-progressbar>
```

Key Features:
- Determinate and indeterminate states
- Percentage display
- Custom styling options
- Status indicators
- Animation support
- Accessibility features

Best Practices:

1. Stepper Implementation
   - Clear step labels
   - Validation feedback
   - Progress indication
   - Error handling
   - Consistent navigation

2. Progress Tracking
   - Accurate progress calculation
   - Clear visual feedback
   - Status communication
   - Performance monitoring
   - Error state handling

Common Use Cases:

1. Stepper
   - Multi-step forms
   - User onboarding
   - Checkout processes
   - Setup wizards
   - Tutorial flows

2. Progress Bar
   - File uploads
   - Process tracking
   - Loading indicators
   - Task completion
   - Step progression

Accessibility Considerations:
- Keyboard navigation support
- ARIA labels and roles
- Focus management
- Screen reader compatibility
- Color contrast compliance

### Development Components

#### `DeesEditor`
Code editor component with syntax highlighting and code completion, powered by Monaco Editor.

```typescript
<dees-editor
  .value=${code}
  @change=${handleCodeChange}
  .language=${'typescript'}
  .theme=${'vs-dark'}
  .options=${{
    lineNumbers: true,
    minimap: { enabled: true },
    autoClosingBrackets: 'always'
  }}
></dees-editor>
```

Key Features:
- Syntax highlighting for multiple languages
- Code completion
- Line numbers
- Minimap navigation
- Customizable options
- Theme support
- Search and replace
- Multiple cursors
- Code folding

#### `DeesEditorMarkdown`
Markdown editor component with live preview.

```typescript
<dees-editor-markdown
  .value=${markdown}
  @change=${handleMarkdownChange}
  .options=${{
    preview: true,
    toolbar: true,
    spellcheck: true,
    autosave: true
  }}
></dees-editor-markdown>
```

Key Features:
- Live preview
- Toolbar for common formatting
- Markdown syntax highlighting
- Image upload support
- Table editor
- Customizable preview styles
- Spellcheck integration
- Auto-save functionality

#### `DeesEditorMarkdownoutlet`
Markdown preview component for rendering markdown content.

```typescript
<dees-editor-markdownoutlet
  .markdown=${markdownContent}
  .theme=${'github'}  // Options: github, dark, custom
  .plugins=${['mermaid', 'highlight']}  // Optional plugins
  allowHtml={false}   // Security: disable raw HTML
></dees-editor-markdownoutlet>
```

Key Features:
- Safe markdown rendering
- Multiple themes
- Plugin support (mermaid diagrams, syntax highlighting)
- XSS protection
- Custom CSS injection
- Responsive images

#### `DeesTerminal`
Terminal emulator component for command-line interface.

```typescript
<dees-terminal
  .commands=${{
    'echo': (args) => `Echo: ${args.join(' ')}`,
    'help': () => 'Available commands: echo, help'
  }}
  .prompt=${'$'}
  .welcomeMessage=${'Welcome! Type "help" for available commands.'}
  .historySize=${100}
  .autoFocus={true}
></dees-terminal>
```

Key Features:
- Command history
- Custom commands
- Auto-completion
- Copy/paste support
- ANSI color support
- Scrollback buffer
- Keyboard shortcuts
- Command aliases

#### `DeesUpdater`
Component for managing application updates and version control.

```typescript
<dees-updater
  .currentVersion=${'1.5.2'}
  .checkInterval=${3600000}  // Check every hour
  .autoUpdate=${false}
  @update-available=${handleUpdateAvailable}
  @update-progress=${handleUpdateProgress}
></dees-updater>
```

Key Features:
- Version checking
- Update notifications
- Progress tracking
- Automatic updates
- Rollback support
- Update scheduling
- Dependency management

Best Practices:

1. Code Editor Usage
   - Configure appropriate language
   - Set reasonable defaults
   - Handle content changes
   - Manage undo/redo stack
   - Consider performance

2. Markdown Editing
   - Provide clear toolbar
   - Show live preview
   - Handle image uploads
   - Support shortcuts
   - Maintain consistent styling

3. Terminal Implementation
   - Clear command documentation
   - Handle errors gracefully
   - Provide command history
   - Support common shortcuts
   - Implement auto-completion

4. Update Management
   - Regular version checks
   - Clear update messaging
   - Progress indication
   - Error recovery
   - User confirmation

Common Use Cases:

1. Code Editor
   - Configuration editing
   - Script development
   - Code snippets
   - Documentation
   - Teaching tools

2. Markdown Editor
   - Documentation
   - Content creation
   - README files
   - Blog posts
   - Release notes

3. Terminal
   - Command execution
   - System monitoring
   - Development tools
   - Debugging
   - Training environments

4. Updater
   - Application updates
   - Plugin management
   - Feature deployment
   - Security patches
   - Configuration updates

Integration Examples:

```typescript
// Combining components for a development environment
<dees-form>
  <dees-editor
    .language=${'javascript'}
    .value=${code}
    @change=${updatePreview}
  ></dees-editor>
  
  <dees-terminal
    .commands=${devCommands}
    @command=${executeCommand}
  ></dees-terminal>
  
  <dees-updater
    .currentVersion=${appVersion}
    @update-available=${notifyUser}
  ></dees-updater>
</dees-form>
```

Performance Considerations:
- Lazy loading of heavy components
- Memory management
- Resource cleanup
- Event handling optimization
- Efficient updates

Accessibility Features:
- Keyboard navigation
- Screen reader support
- High contrast themes
- Focus management
- ARIA attributes

### Auth & Utilities Components

#### `DeesSimpleAppdash`
Simple application dashboard component for quick prototyping.

```typescript
<dees-simple-appdash
  .appTitle=${'My Application'}
  .menuItems=${[
    { name: 'Dashboard', icon: 'home', route: '/dashboard' },
    { name: 'Settings', icon: 'settings', route: '/settings' }
  ]}
  .user=${{
    name: 'John Doe',
    role: 'Administrator'
  }}
  @menu-select=${handleMenuSelect}
>
  <!-- Dashboard content -->
</dees-simple-appdash>
```

Key Features:
- Quick setup dashboard layout
- Built-in navigation
- User profile section
- Responsive design
- Minimal configuration

#### `DeesSimpleLogin`
Simple login form component with validation and customization.

```typescript
<dees-simple-login
  .appName=${'My Application'}
  .logo=${'./assets/logo.png'}
  .backgroundImage=${'./assets/background.jpg'}
  .fields=${['username', 'password']}  // Options: username, email, password
  showForgotPassword
  showRememberMe
  @login=${handleLogin}
  @forgot-password=${handleForgotPassword}
></dees-simple-login>
```

Key Features:
- Customizable fields
- Built-in validation
- Remember me option
- Forgot password link
- Custom branding
- Responsive layout
- Loading states

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.