From 765b01afe049c1493258af022de838fe87a024f9 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Fri, 11 Apr 2025 11:19:23 +0000 Subject: [PATCH] fix(readme): Update readme.md: remove redundant usage section and refine component documentation with improved examples. --- changelog.md | 14 + readme.md | 1066 +++++++++++++++++++++++++++++++--- ts_web/00_commitinfo_data.ts | 2 +- 3 files changed, 1006 insertions(+), 76 deletions(-) diff --git a/changelog.md b/changelog.md index bb17467..23992b0 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,19 @@ # Changelog +## 2025-04-11 - 1.5.3 - fix(readme) +Update readme.md: remove redundant usage section and refine component documentation with improved examples. + +- Removed the standalone manual import and usage example for components. +- Added refined examples demonstrating both basic and option-based usage (e.g. for DeesButton). +- Improved markdown formatting and consistency across component documentation. + +## 2025-04-11 - 1.5.3 - fix(readme) +Update readme.md for clearer documentation: removed redundant 'Usage' section and refined component examples (e.g., DeesButton's basic and options usage) for improved clarity and consistency. + +- Removed standalone usage example showing manual import and creation of components +- Added refined examples demonstrating both basic and option-based usage of components +- Improved overall readme formatting and consistency across component documentation + ## 2025-04-11 - 1.5.2 - fix(ci) Remove obsolete GitLab CI configuration file diff --git a/readme.md b/readme.md index a185c70..a35cd9b 100644 --- a/readme.md +++ b/readme.md @@ -2,30 +2,14 @@ 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. Using npm is recommended: +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 ``` -## Usage -To use the components provided by `@design.estate/dees-catalog`, you need to import them into your project. Here's an example of how to import and use the `DeesButton` component: - -```typescript -import { DeesButton } from '@design.estate/dees-catalog'; - -const button = document.createElement('dees-button'); -button.text = 'Click me'; -button.type = 'highlighted'; // Options: normal, highlighted, discreet -button.status = 'pending'; // Options: normal, pending, success, error - -document.body.appendChild(button); -``` - ## Components Overview -Below is a comprehensive list of all available components: - | Category | Components | |----------|------------| | Core UI | `DeesButton`, `DeesBadge`, `DeesChips`, `DeesIcon`, `DeesLabel`, `DeesSpinner`, `DeesToast` | @@ -45,10 +29,17 @@ Below is a comprehensive list of all available components: A versatile button component supporting multiple styles and states. ```typescript +// Basic usage const button = document.createElement('dees-button'); button.text = 'Click me'; -button.type = 'highlighted'; // Options: normal, highlighted, discreet -button.status = 'pending'; // Options: normal, pending, success, error + +// With options +Click me ``` #### `DeesBadge` @@ -57,8 +48,8 @@ Display status indicators or counts with customizable styles. ```typescript ``` @@ -68,23 +59,82 @@ 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 collection. +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 ``` @@ -94,146 +144,1012 @@ Text input field with validation and formatting options. ```typescript ``` +#### `DeesInputCheckbox` +Checkbox input component for boolean values. + +```typescript + +``` + #### `DeesInputDropdown` -Dropdown selection component with search and multi-select capabilities. +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 layout component for application structure. +Base container component for application layout structure. ```typescript + + ``` #### `DeesAppuiMainmenu` -Navigation menu component for application sidebar. +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 row selection. +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) + } ]} - selectable + 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 using ApexCharts. +Area chart component built on ApexCharts for visualizing time-series data. ```typescript ``` -### Dialog Components +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`

Are you sure?

`, + content: html` + + + + `, menuOptions: [ - { name: 'Cancel', action: () => modal.destroy() }, - { name: 'Confirm', action: () => handleConfirm() } + { + 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 based on Monaco Editor. +Code editor component with syntax highlighting and code completion, powered by Monaco Editor. ```typescript ``` -## Customization and Theming +Key Features: +- Syntax highlighting for multiple languages +- Code completion +- Line numbers +- Minimap navigation +- Customizable options +- Theme support +- Search and replace +- Multiple cursors +- Code folding -Components can be customized using CSS custom properties and the built-in theme system. Example: +#### `DeesEditorMarkdown` +Markdown editor component with live preview. -```css -dees-button { - --dees-button-background: #007bff; - --dees-button-color: white; -} +```typescript + ``` -## Browser Support +Key Features: +- Live preview +- Toolbar for common formatting +- Markdown syntax highlighting +- Image upload support +- Table editor +- Customizable preview styles +- Spellcheck integration +- Auto-save functionality -The library supports modern browsers with Web Components implementation: -- Chrome (latest) -- Firefox (latest) -- Safari (latest) -- Edge (latest) +#### `DeesTerminal` +Terminal emulator component for command-line interface. -## Contributing +```typescript + `Echo: ${args.join(' ')}`, + 'help': () => 'Available commands: echo, help' + }} + .prompt=${'$'} + .welcomeMessage=${'Welcome! Type "help" for available commands.'} + .historySize=${100} + .autoFocus={true} +> +``` -Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on submitting pull requests. +Key Features: +- Command history +- Custom commands +- Auto-completion +- Copy/paste support +- ANSI color support +- Scrollback buffer +- Keyboard shortcuts +- Command aliases -## License and Legal Information +#### `DeesUpdater` +Component for managing application updates and version control. -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](license) file within this repository. +```typescript + +``` -**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. +Key Features: +- Version checking +- Update notifications +- Progress tracking +- Automatic updates +- Rollback support +- Update scheduling +- Dependency management -### Trademarks +Best Practices: -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. +1. Code Editor Usage + - Configure appropriate language + - Set reasonable defaults + - Handle content changes + - Manage undo/redo stack + - Consider performance -### Company Information +2. Markdown Editing + - Provide clear toolbar + - Show live preview + - Handle image uploads + - Support shortcuts + - Maintain consistent styling -Task Venture Capital GmbH -Registered at District court Bremen HRB 35230 HB, Germany +3. Terminal Implementation + - Clear command documentation + - Handle errors gracefully + - Provide command history + - Support common shortcuts + - Implement auto-completion -For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. +4. Update Management + - Regular version checks + - Clear update messaging + - Progress indication + - Error recovery + - User confirmation -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. +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] diff --git a/ts_web/00_commitinfo_data.ts b/ts_web/00_commitinfo_data.ts index 4b36c05..7b79bc9 100644 --- a/ts_web/00_commitinfo_data.ts +++ b/ts_web/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@design.estate/dees-catalog', - version: '1.5.2', + version: '1.5.3', description: 'A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.' }