# @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]