# @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`, `DeesBadge`, `DeesChips`, `DeesIcon`, `DeesLabel`, `DeesSpinner`, `DeesToast` | | Forms | `DeesForm`, `DeesInputText`, `DeesInputCheckbox`, `DeesInputDropdown`, `DeesInputRadio`, `DeesInputFileupload`, `DeesInputIban`, `DeesInputPhone`, `DeesInputQuantitySelector`, `DeesInputMultitoggle`, `DeesFormSubmit` | | Layout | `DeesAppuiBase`, `DeesAppuiMainmenu`, `DeesAppuiMainselector`, `DeesAppuiMaincontent`, `DeesAppuiAppbar`, `DeesMobileNavigation` | | Data Display | `DeesTable`, `DeesDataviewCodebox`, `DeesDataviewStatusobject`, `DeesPdf` | | Visualization | `DeesChartArea`, `DeesChartLog` | | Dialogs & Overlays | `DeesModal`, `DeesContextmenu`, `DeesSpeechbubble`, `DeesWindowlayer` | | Navigation | `DeesStepper`, `DeesProgressbar` | | Development | `DeesEditor`, `DeesEditorMarkdown`, `DeesTerminal`, `DeesUpdater` | ## 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 Click me ``` #### `DeesBadge` Display status indicators or counts with customizable styles. ```typescript ``` #### `DeesChips` Interactive chips/tags with selection capabilities. ```typescript ``` #### `DeesIcon` Display icons from various icon sets including FontAwesome. ```typescript ``` #### `DeesLabel` Text label component with optional icon and status indicators. ```typescript ``` #### `DeesSpinner` Loading indicator with customizable appearance. ```typescript ``` #### `DeesToast` Notification toast messages with various styles and auto-dismiss. ```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 }); // Component usage ``` ### Form Components #### `DeesForm` Container component for form elements with built-in validation and data handling. ```typescript handleFormData(e.detail)} // Emitted when form is submitted @formValidation=${(e) => handleValidation(e.detail)} // Emitted during validation > Submit ``` #### `DeesInputText` Text input field with validation and formatting options. ```typescript ``` #### `DeesInputCheckbox` Checkbox input component for boolean values. ```typescript ``` #### `DeesInputDropdown` Dropdown selection component with search and filtering capabilities. ```typescript ``` #### `DeesInputRadio` Radio button group for single-choice selections. ```typescript ``` #### `DeesInputFileupload` File upload component with drag-and-drop support. ```typescript ``` #### `DeesInputIban` Specialized input for IBAN (International Bank Account Number) with validation. ```typescript ``` #### `DeesInputPhone` Phone number input with country code selection and formatting. ```typescript ``` #### `DeesInputQuantitySelector` Numeric input with increment/decrement controls. ```typescript ``` #### `DeesInputMultitoggle` Multi-state toggle button group. ```typescript ``` #### `DeesFormSubmit` Submit button component specifically designed for `DeesForm`. ```typescript Submit Form ``` ### Layout Components #### `DeesAppuiBase` Base container component for application layout structure. ```typescript ``` #### `DeesAppuiMainmenu` Main navigation menu component for application-wide navigation. ```typescript handleNavigation('dashboard') }, { key: 'settings', label: 'Settings', icon: 'cog', action: () => handleNavigation('settings') } ]} collapsed // Optional: show collapsed version position="left" // Options: left, right > ``` #### `DeesAppuiMainselector` Secondary navigation component for sub-section selection. ```typescript selectSection('section1') } ]} selectedKey="section1" // Currently selected section @selection-change=${handleSectionChange} > ``` #### `DeesAppuiMaincontent` Main content area with tab management support. ```typescript Tab 1 Content`, action: () => handleTabAction('tab1') } ]} selectedTab="tab1" // Currently active tab @tab-change=${handleTabChange} > ``` #### `DeesAppuiAppbar` Top application bar with actions and status information. ```typescript showNotifications() }, { icon: 'user', label: 'Profile', action: () => showProfile() } ]} showSearch // Optional: display search bar @search=${handleSearch} > ``` #### `DeesMobileNavigation` Responsive navigation component for mobile devices. ```typescript navigate('home') }, { key: 'profile', label: 'Profile', icon: 'user', action: () => navigate('profile') } ]} activeKey="home" // Currently active item position="bottom" // Options: bottom, top @item-click=${handleNavigationClick} > ``` ### Data Display Components #### `DeesTable` Advanced table component with sorting, filtering, and action support. ```typescript ({ 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} > ``` #### `DeesDataviewCodebox` Code display component with syntax highlighting and line numbers. ```typescript { return html\`
Hello World
\`; }; `} >
``` #### `DeesDataviewStatusobject` Status display component for complex objects with nested status indicators. ```typescript ``` #### `DeesPdf` PDF viewer component with navigation and zoom controls. ```typescript ``` 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 ### Visualization Components #### `DeesChartArea` Area chart component built on ApexCharts for visualizing time-series data. ```typescript ``` 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 ``` 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` `, menuOptions: [ { name: 'Cancel', action: async (modal) => { modal.destroy(); return null; } }, { name: 'Confirm', action: async (modal) => { // Handle confirmation modal.destroy(); return null; } } ] }); // Component usage ``` 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 handleEdit() }, { label: 'Delete', icon: 'trash', action: () => handleDelete() } ]} position="right" // Options: right, left, auto @item-click=${handleMenuItemClick} > ``` #### `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 ``` 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
``` 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 Personal Information Form`, validation: () => validatePersonalInfo() }, { key: 'address', label: 'Address', content: html`
Address Form
`, validation: () => validateAddress() }, { key: 'confirm', label: 'Confirmation', content: html`
Review and Confirm
` } ]} currentStep="personal" @step-change=${handleStepChange} @complete=${handleComplete} >
``` 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 ``` Key Features: - Determinate and indeterminate states - Percentage display - Custom styling options - Status indicators - Animation support - Accessibility features #### `DeesMobileNavigation` Mobile-optimized navigation component with touch support. ```typescript // Programmatic usage DeesMobilenavigation.createAndShow([ { name: 'Home', action: async (nav) => { // Handle navigation return null; } }, { name: 'Settings', action: async (nav) => { // Handle navigation return null; } } ]); // Component usage handleNavigation('profile') }, { name: 'Settings', action: (nav) => handleNavigation('settings') } ]} > ``` Key Features: - Touch-friendly interface - Slide-in animation - Backdrop overlay - Single instance management - Custom menu items - Responsive design 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 3. Mobile Navigation - Touch-optimized targets - Clear visual hierarchy - Smooth animations - Gesture support - Responsive behavior 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 3. Mobile Navigation - Responsive menus - App navigation - Settings access - User actions - Context switching 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 ``` 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 ``` Key Features: - Live preview - Toolbar for common formatting - Markdown syntax highlighting - Image upload support - Table editor - Customizable preview styles - Spellcheck integration - Auto-save functionality #### `DeesTerminal` Terminal emulator component for command-line interface. ```typescript `Echo: ${args.join(' ')}`, 'help': () => 'Available commands: echo, help' }} .prompt=${'$'} .welcomeMessage=${'Welcome! Type "help" for available commands.'} .historySize=${100} .autoFocus={true} > ``` 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 ``` 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 ``` 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 [End of component documentation]