dees-catalog/readme.md

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

[![npm version](https://img.shields.io/npm/v/@design.estate/dees-catalog.svg)](https://www.npmjs.com/package/@design.estate/dees-catalog)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![Web Components](https://img.shields.io/badge/Web%20Components-Ready-green.svg)](https://www.webcomponents.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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>