432 lines
12 KiB
Markdown
432 lines
12 KiB
Markdown
# @design.estate/dees-catalog 🎨
|
|
> **A comprehensive web components library built with TypeScript and LitElement**
|
|
> 75+ Production-ready UI components for building modern web applications with consistent design and behavior
|
|
|
|
[](https://www.npmjs.com/package/@design.estate/dees-catalog)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://www.webcomponents.org/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
## 🚀 Quick Start
|
|
|
|
```bash
|
|
# Install with npm
|
|
npm install @design.estate/dees-catalog
|
|
|
|
# Or with pnpm (recommended)
|
|
pnpm add @design.estate/dees-catalog
|
|
|
|
# Or with yarn
|
|
yarn add @design.estate/dees-catalog
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```typescript
|
|
// Import components you need
|
|
import { DeesButton, DeesForm, DeesInputText } from '@design.estate/dees-catalog';
|
|
|
|
// Use in your HTML or framework
|
|
<dees-form @formData=${handleSubmit}>
|
|
<dees-input-text
|
|
label="Your Name"
|
|
required
|
|
></dees-input-text>
|
|
<dees-button type="highlighted">
|
|
Submit
|
|
</dees-button>
|
|
</dees-form>
|
|
```
|
|
|
|
## 📦 What's Inside?
|
|
|
|
### Component Categories at a Glance
|
|
|
|
| 🎯 Category | 📊 Count | 🔥 Popular Components |
|
|
|------------|----------|----------------------|
|
|
| **Core UI** | 15+ | Buttons, Icons, Badges, Labels, Panels |
|
|
| **Forms** | 20+ | Text Input, Dropdown, Date Picker, WYSIWYG Editor |
|
|
| **Layout** | 12+ | App Shell, Navigation, Dashboard Grid |
|
|
| **Data Display** | 8+ | Tables, Charts, Stats Grid, Pagination |
|
|
| **Overlays** | 5+ | Modals, Context Menus, Toasts |
|
|
| **Development** | 6+ | Code Editor, Terminal, Markdown Editor |
|
|
|
|
## 🌟 Key Features
|
|
|
|
- ✅ **100% TypeScript** - Full type safety and IntelliSense support
|
|
- 🎨 **Theme System** - Built-in light/dark theme support
|
|
- 📱 **Responsive** - Mobile-first design approach
|
|
- ♿ **Accessible** - ARIA compliant with keyboard navigation
|
|
- 🚀 **Performance** - Lazy loading and optimized rendering
|
|
- 🔧 **Customizable** - CSS variables and property APIs
|
|
- 🧩 **Framework Agnostic** - Works with any framework or vanilla JS
|
|
- 📖 **Well Documented** - Comprehensive demos and examples
|
|
|
|
## 💡 Component Highlights
|
|
|
|
### 🎯 Core UI Components
|
|
|
|
#### Buttons & Actions
|
|
```typescript
|
|
// Beautiful button with multiple styles
|
|
<dees-button
|
|
type="highlighted" // normal | highlighted | discreet
|
|
status="pending" // normal | pending | success | error
|
|
@click=${handleClick}
|
|
>
|
|
Click Me
|
|
</dees-button>
|
|
|
|
// Button groups for related actions
|
|
<dees-button-group
|
|
.buttons=${[
|
|
{ text: 'Save', type: 'highlighted', action: save },
|
|
{ text: 'Cancel', type: 'normal', action: cancel }
|
|
]}
|
|
></dees-button-group>
|
|
```
|
|
|
|
#### Icons with Library Prefixes
|
|
```typescript
|
|
// FontAwesome icons
|
|
<dees-icon icon="fa:check" iconSize="24"></dees-icon>
|
|
|
|
// Lucide icons
|
|
<dees-icon icon="lucide:menu" iconSize="24"></dees-icon>
|
|
```
|
|
|
|
#### Toast Notifications
|
|
```typescript
|
|
// Show toast notifications programmatically
|
|
DeesToast.success('Changes saved successfully!');
|
|
DeesToast.error('Something went wrong');
|
|
DeesToast.info('New update available');
|
|
|
|
// Advanced control
|
|
const toast = await DeesToast.show({
|
|
message: 'Processing...',
|
|
type: 'info',
|
|
duration: 0 // No auto-dismiss
|
|
});
|
|
// Later...
|
|
toast.dismiss();
|
|
```
|
|
|
|
### 📝 Form Components
|
|
|
|
#### Complete Form System
|
|
```typescript
|
|
<dees-form @formData=${(e) => console.log('Form data:', e.detail)}>
|
|
<!-- Text input with validation -->
|
|
<dees-input-text
|
|
key="email"
|
|
label="Email"
|
|
required
|
|
validationRegex="^[^@]+@[^@]+\.[^@]+$"
|
|
></dees-input-text>
|
|
|
|
<!-- Date picker with constraints -->
|
|
<dees-input-datepicker
|
|
key="eventDate"
|
|
label="Event Date"
|
|
minDate="2025-01-01"
|
|
enableTime
|
|
></dees-input-datepicker>
|
|
|
|
<!-- List management (NEW!) -->
|
|
<dees-input-list
|
|
key="features"
|
|
label="Product Features"
|
|
placeholder="Add feature..."
|
|
sortable
|
|
minItems={3}
|
|
maxItems={10}
|
|
></dees-input-list>
|
|
|
|
<!-- Rich text editor -->
|
|
<dees-input-wysiwyg
|
|
key="description"
|
|
label="Description"
|
|
></dees-input-wysiwyg>
|
|
|
|
<dees-form-submit>Submit</dees-form-submit>
|
|
</dees-form>
|
|
```
|
|
|
|
### 🏗️ Layout Components
|
|
|
|
#### Application Shell
|
|
```typescript
|
|
// Complete application layout with one component
|
|
<dees-appui-base
|
|
.appbarMenuItems=${menuItems}
|
|
.appbarBreadcrumbs=${'Home > Dashboard'}
|
|
.mainmenuTabs=${tabs}
|
|
.user=${{ name: 'John Doe', status: 'online' }}
|
|
>
|
|
<div slot="maincontent">
|
|
<!-- Your app content -->
|
|
</div>
|
|
</dees-appui-base>
|
|
```
|
|
|
|
#### Dashboard Grid
|
|
```typescript
|
|
// Drag-and-drop dashboard widgets
|
|
<dees-dashboardgrid
|
|
.widgets=${[
|
|
{
|
|
id: 'sales',
|
|
title: 'Sales Overview',
|
|
x: 0, y: 0, w: 4, h: 3,
|
|
content: html`<sales-chart></sales-chart>`
|
|
},
|
|
{
|
|
id: 'stats',
|
|
title: 'Statistics',
|
|
x: 4, y: 0, w: 4, h: 3,
|
|
content: html`<dees-statsgrid .tiles=${stats}></dees-statsgrid>`
|
|
}
|
|
]}
|
|
editable
|
|
></dees-dashboardgrid>
|
|
```
|
|
|
|
### 📊 Data Display
|
|
|
|
#### Advanced Tables
|
|
```typescript
|
|
<dees-table
|
|
.data=${users}
|
|
.displayFunction=${(user) => ({
|
|
Name: user.name,
|
|
Email: user.email,
|
|
Role: user.role,
|
|
Status: html`<dees-badge type="${user.active ? 'success' : 'error'}">
|
|
${user.active ? 'Active' : 'Inactive'}
|
|
</dees-badge>`
|
|
})}
|
|
.dataActions=${[
|
|
{ name: 'Edit', icon: 'fa:edit', action: editUser },
|
|
{ name: 'Delete', icon: 'fa:trash', action: deleteUser }
|
|
]}
|
|
searchable
|
|
></dees-table>
|
|
```
|
|
|
|
#### Statistics Grid
|
|
```typescript
|
|
<dees-statsgrid
|
|
.tiles=${[
|
|
{
|
|
title: 'Revenue',
|
|
value: 125420,
|
|
unit: '$',
|
|
type: 'number',
|
|
description: '+12.5% from last month'
|
|
},
|
|
{
|
|
title: 'CPU Usage',
|
|
value: 73,
|
|
type: 'gauge',
|
|
gaugeOptions: {
|
|
thresholds: [
|
|
{ value: 0, color: '#22c55e' },
|
|
{ value: 80, color: '#ef4444' }
|
|
]
|
|
}
|
|
}
|
|
]}
|
|
></dees-statsgrid>
|
|
```
|
|
|
|
### 🎭 Overlays & Dialogs
|
|
|
|
#### Modal Dialogs
|
|
```typescript
|
|
DeesModal.createAndShow({
|
|
heading: 'Confirm Action',
|
|
content: html`
|
|
<p>Are you sure you want to proceed?</p>
|
|
`,
|
|
menuOptions: [
|
|
{
|
|
name: 'Cancel',
|
|
action: async (modal) => modal.destroy()
|
|
},
|
|
{
|
|
name: 'Confirm',
|
|
action: async (modal) => {
|
|
await performAction();
|
|
modal.destroy();
|
|
}
|
|
}
|
|
]
|
|
});
|
|
```
|
|
|
|
## 🎨 Theme System
|
|
|
|
All components support automatic theme switching:
|
|
|
|
```typescript
|
|
// Components automatically adapt to light/dark themes
|
|
// Use the cssManager for theme-aware colors
|
|
import { cssManager } from '@design.estate/dees-catalog';
|
|
|
|
css`
|
|
.my-element {
|
|
background: ${cssManager.bdTheme('#fff', '#1a1a1a')};
|
|
color: ${cssManager.bdTheme('#000', '#fff')};
|
|
}
|
|
`
|
|
```
|
|
|
|
## 🔧 Development
|
|
|
|
### Prerequisites
|
|
- Node.js 18+
|
|
- pnpm (recommended) or npm
|
|
|
|
### Setup
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/design-estate/dees-catalog.git
|
|
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Build the project
|
|
pnpm run build
|
|
|
|
# Run in development mode
|
|
pnpm run watch
|
|
|
|
# Run tests
|
|
pnpm test
|
|
```
|
|
|
|
### Project Structure
|
|
```
|
|
dees-catalog/
|
|
├── ts_web/
|
|
│ ├── elements/ # All component implementations
|
|
│ │ ├── dees-*.ts # Component files
|
|
│ │ └── *.demo.ts # Component demos
|
|
│ ├── pages/ # Demo showcase pages
|
|
│ └── index.ts # Main exports
|
|
├── dist_ts_web/ # Built distribution files
|
|
└── test/ # Test files
|
|
```
|
|
|
|
## 📚 Documentation
|
|
|
|
### Component Demos
|
|
Each component includes a built-in demo accessible via the static `.demo` property:
|
|
|
|
```typescript
|
|
import { DeesButton } from '@design.estate/dees-catalog';
|
|
|
|
// Access the component's demo
|
|
const demoHTML = DeesButton.demo();
|
|
```
|
|
|
|
### Interactive Playground
|
|
For a complete interactive playground with all components:
|
|
|
|
1. Clone the repository
|
|
2. Run `pnpm install && pnpm run build`
|
|
3. Open the demo pages in `dist_ts_web/pages/`
|
|
|
|
### TypeScript Support
|
|
Full TypeScript definitions are included. Your IDE will provide:
|
|
- 🔍 IntelliSense for all properties and methods
|
|
- 📝 JSDoc comments with usage examples
|
|
- ✅ Type checking for component properties
|
|
- 🎯 Auto-imports and code completion
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
|
|
### Development Workflow
|
|
1. Fork the repository
|
|
2. Create a feature branch: `git checkout -b feature/amazing-feature`
|
|
3. Make your changes and add tests
|
|
4. Ensure all tests pass: `pnpm test`
|
|
5. Commit with conventional commits: `git commit -m 'feat: add amazing feature'`
|
|
6. Push and create a Pull Request
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Issue: Components not rendering**
|
|
```typescript
|
|
// Ensure you're importing from the correct path
|
|
import '@design.estate/dees-catalog/dist_ts_web/elements/dees-button.js';
|
|
// Or use the bundled version
|
|
import '@design.estate/dees-catalog';
|
|
```
|
|
|
|
**Issue: TypeScript errors**
|
|
```typescript
|
|
// Add to tsconfig.json
|
|
{
|
|
"compilerOptions": {
|
|
"moduleResolution": "node",
|
|
"experimentalDecorators": true,
|
|
"allowSyntheticDefaultImports": true
|
|
}
|
|
}
|
|
```
|
|
|
|
**Issue: Styles not applying**
|
|
```html
|
|
<!-- Components use Shadow DOM, styles are encapsulated -->
|
|
<!-- Use CSS custom properties for theming -->
|
|
<style>
|
|
dees-button {
|
|
--button-background: #007bff;
|
|
--button-color: white;
|
|
}
|
|
</style>
|
|
```
|
|
|
|
## 🔗 Links & Resources
|
|
|
|
- 📖 [Full Documentation](https://design.estate/docs/dees-catalog)
|
|
- 🎮 [Interactive Demo](https://design.estate/demo/dees-catalog)
|
|
- 📦 [NPM Package](https://www.npmjs.com/package/@design.estate/dees-catalog)
|
|
- 🐛 [Issue Tracker](https://github.com/design-estate/dees-catalog/issues)
|
|
- 💬 [Discussions](https://github.com/design-estate/dees-catalog/discussions)
|
|
|
|
## 📄 License
|
|
|
|
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.
|
|
|
|
**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.
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
<p>Built with ❤️ by <a href="https://task.vc">Task Venture Capital GmbH</a></p>
|
|
<p>
|
|
<a href="https://github.com/design-estate/dees-catalog/stargazers">⭐ Star us on GitHub</a> •
|
|
<a href="https://twitter.com/taskventure">🐦 Follow on Twitter</a> •
|
|
<a href="https://www.linkedin.com/company/task-venture-capital">💼 LinkedIn</a>
|
|
</p>
|
|
</div> |