dees-catalog/readme.md

1156 lines
26 KiB
Markdown
Raw Permalink Normal View History

# @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
<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 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
<dees-toast
message="Changes saved"
type="success"
autoClose
duration="3000"
></dees-toast>
```
### 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>
```
#### `DeesInputRadio`
Radio button group for single-choice selections.
```typescript
<dees-input-radio
key="gender"
label="Gender"
.options=${[
{ key: 'male', option: 'Male' },
{ key: 'female', option: 'Female' },
{ key: 'other', option: 'Other' }
]}
required
></dees-input-radio>
```
#### `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>
```
#### `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.
```typescript
<dees-appui-base>
<dees-appui-mainmenu></dees-appui-mainmenu>
<dees-appui-mainselector></dees-appui-mainselector>
<dees-appui-maincontent></dees-appui-maincontent>
<dees-appui-appbar></dees-appui-appbar>
</dees-appui-base>
```
#### `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`
Top application bar with actions and status information.
```typescript
<dees-appui-appbar
title="My Application"
.actions=${[
{
icon: 'bell',
label: 'Notifications',
action: () => showNotifications()
},
{
icon: 'user',
label: 'Profile',
action: () => showProfile()
}
]}
showSearch // Optional: display search bar
@search=${handleSearch}
></dees-appui-appbar>
```
#### `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
### 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
#### `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
<dees-mobilenavigation
heading="MENU"
.menuItems=${[
{
name: 'Profile',
action: (nav) => handleNavigation('profile')
},
{
name: 'Settings',
action: (nav) => handleNavigation('settings')
}
]}
></dees-mobilenavigation>
```
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
<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
#### `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
2020-05-10 23:19:31 +00:00
4. Update Management
- Regular version checks
- Clear update messaging
- Progress indication
- Error recovery
- User confirmation
2020-05-10 23:19:31 +00:00
Common Use Cases:
2020-09-13 16:24:48 +00:00
1. Code Editor
- Configuration editing
- Script development
- Code snippets
- Documentation
- Teaching tools
2020-05-10 23:19:31 +00:00
2. Markdown Editor
- Documentation
- Content creation
- README files
- Blog posts
- Release notes
2020-05-10 23:19:31 +00:00
3. Terminal
- Command execution
- System monitoring
- Development tools
- Debugging
- Training environments
2020-09-13 16:24:48 +00:00
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>
```
2020-05-10 23:19:31 +00:00
Performance Considerations:
- Lazy loading of heavy components
- Memory management
- Resource cleanup
- Event handling optimization
- Efficient updates
2020-05-10 23:19:31 +00:00
Accessibility Features:
- Keyboard navigation
- Screen reader support
- High contrast themes
- Focus management
- ARIA attributes
2020-05-10 23:19:31 +00:00
[End of component documentation]