design.estate/dees-catalog
3
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): add documentation for new input components, activity log features, theming, and expand DeesAppui docs

Browse Source
This commit is contained in:
Jürgen Kunz
2026-01-03 02:09:13 +00:00
parent c3444aac01
commit 8313c24c9d
4 changed files with 469 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ts_web/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@design.estate/dees-catalog',
version: '3.28.1',
version: '3.29.0',
description: 'A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.'
}

339
ts_web/elements/00group-appui/dees-appui/readme.md
View File

@@ -1,6 +1,6 @@
# DeesAppui
A comprehensive application shell component providing a complete UI framework with navigation, menus, activity logging, and view management.
A comprehensive application shell component providing a complete UI framework with navigation, menus, activity logging, and view management. 🚀
## Quick Start
@@ -35,6 +35,34 @@ class MyApp extends DeesElement {
}
```
## Architecture Overview
The DeesAppui shell consists of several interconnected components:
```
┌─────────────────────────────────────────────────────────────────────┐
│ AppBar (dees-appui-appbar) │
│ ├── Menus (File, Edit, View...) │
│ ├── Breadcrumbs │
│ ├── User Profile + Dropdown │
│ └── Activity Log Toggle │
├─────────────┬───────────────────────────────────┬───────────────────┤
│ Main Menu │ Content Area │ Activity Log │
│ (collapsed/ │ ├── Content Tabs │ (slide panel) │
│ expanded) │ │ (closable, from tables/lists)│ │
│ │ └── View Container │ │
│ ┌─────────┐ │ └── Active View │ │
│ │ 🏠 Home │ ├─────────────────────────────────┐ │ │
│ │ 📁 Files│ │ Secondary Menu │ │ │
│ │ ⚙ Settings ├── Collapsible Groups │ │ │
│ │ │ │ ├── Item 1 │ │ │
│ └─────────┘ │ ├── Item 2 (with badge) │ │ │
│ │ └── Item 3 │ │ │
└─────────────┴─────────────────────────────────┴───────────────────────┘
```
---
## Configuration API
### `configure(config: IAppConfig)`
@@ -155,74 +183,289 @@ appui.removeMainMenuItem('Main', 'tasks');
// Selection
appui.setMainMenuSelection('dashboard');
appui.setMainMenuCollapsed(true);
// Visibility control
appui.setMainMenuCollapsed(true); // Collapse to icon-only sidebar
appui.setMainMenuVisible(false); // Hide completely
// Badges
appui.setMainMenuBadge('inbox', 12);
appui.clearMainMenuBadge('inbox');
```
### Secondary Menu API
---
Views can control the secondary (contextual) menu.
## Secondary Menu API 📋
The secondary menu is a contextual sidebar that appears next to the main content area. It supports **collapsible groups** with icons and badges, making it perfect for:
- **Settings pages** (grouped settings categories)
- **File browsers** (folder trees)
- **Project navigation** (grouped by category)
- **Documentation** (chapters/sections)
### Collapsible Groups
Groups can be collapsed/expanded by clicking the group header. The state is visually indicated with an icon rotation.
```typescript
// Set menu
// Set secondary menu with collapsible groups
appui.setSecondaryMenu({
heading: 'Settings',
groups: [
{
name: 'Account',
iconName: 'lucide:user', // Group icon
collapsed: false, // Initial state (default: false)
items: [
{ key: 'profile', iconName: 'lucide:user', action: () => {} },
{ key: 'security', iconName: 'lucide:shield', action: () => {} },
{ key: 'profile', iconName: 'lucide:user', action: () => showProfile() },
{ key: 'security', iconName: 'lucide:shield', badge: '!', badgeVariant: 'warning', action: () => showSecurity() },
{ key: 'billing', iconName: 'lucide:credit-card', action: () => showBilling() }
]
},
{
name: 'Preferences',
iconName: 'lucide:settings',
collapsed: true, // Start collapsed
items: [
{ key: 'notifications', iconName: 'lucide:bell', action: () => {} },
{ key: 'appearance', iconName: 'lucide:palette', action: () => {} },
{ key: 'language', iconName: 'lucide:globe', action: () => {} }
]
}
]
});
```
// Update group
appui.updateSecondaryMenuGroup('Account', { items: newItems });
### Secondary Menu Item Properties
// Add item
appui.addSecondaryMenuItem('Account', {
key: 'notifications',
iconName: 'lucide:bell',
action: () => {}
```typescript
interface ISecondaryMenuItem {
key: string; // Unique identifier
iconName?: string; // Icon (e.g., 'lucide:user')
action: () => void; // Click handler
badge?: string | number; // Badge text/count
badgeVariant?: 'default' | 'success' | 'warning' | 'error';
}
interface ISecondaryMenuGroup {
name: string; // Group name (shown in header)
iconName?: string; // Group icon
collapsed?: boolean; // Initial collapsed state
items: ISecondaryMenuItem[]; // Items in this group
}
```
### Updating Secondary Menu
```typescript
// Update a specific group
appui.updateSecondaryMenuGroup('Account', {
items: [...newItems]
});
// Selection
// Add item to a group
appui.addSecondaryMenuItem('Account', {
key: 'api-keys',
iconName: 'lucide:key',
action: () => showApiKeys()
});
// Selection (highlights the item)
appui.setSecondaryMenuSelection('profile');
// Visibility control
appui.setSecondaryMenuCollapsed(true); // Collapse panel
appui.setSecondaryMenuVisible(false); // Hide completely
// Clear
appui.clearSecondaryMenu();
```
### Content Tabs API
### View-Specific Secondary Menus
Control tabs in the main content area.
Each view can define its own secondary menu that appears when the view is activated:
```typescript
// Set tabs
appui.setContentTabs([
{ key: 'code', iconName: 'lucide:code', action: () => {} },
{ key: 'preview', iconName: 'lucide:eye', action: () => {} }
]);
// In view definition
{
id: 'settings',
name: 'Settings',
content: 'my-settings-view',
secondaryMenu: [
{
name: 'General',
items: [
{ key: 'account', iconName: 'lucide:user', action: () => {} },
{ key: 'security', iconName: 'lucide:shield', action: () => {} }
]
}
]
}
// Add/remove
appui.addContentTab({ key: 'debug', iconName: 'lucide:bug', action: () => {} });
appui.removeContentTab('debug');
// Select
appui.selectContentTab('preview');
// Get current
const current = appui.getSelectedContentTab();
// Or set dynamically in view's onActivate hook
onActivate(context: IViewActivationContext) {
context.appui.setSecondaryMenu({
heading: 'Project Files',
groups: [...]
});
}
```
### Activity Log API
---
Add activity entries to the right-side activity log.
## Content Tabs API 📑
Content tabs appear above the main view content. They're designed for **opening multiple items** from tables, lists, or other data sources—similar to browser tabs or IDE editor tabs.
### Common Use Cases
- **Table row details** - Click a row to open it as a tab
- **Document editing** - Open multiple documents
- **Entity inspection** - View customer, order, product details
- **Multi-file editing** - Edit multiple configuration files
### Closable Tabs
Tabs can be closable, allowing users to open items, work with them, and close when done:
```typescript
// Set initial tabs
appui.setContentTabs([
{ key: 'overview', iconName: 'lucide:home', action: () => showOverview() },
{ key: 'activity', iconName: 'lucide:activity', action: () => showActivity() }
]);
// Add a closable tab when user clicks a table row
table.addEventListener('row-click', (e) => {
const item = e.detail.item;
appui.addContentTab({
key: `item-${item.id}`,
label: item.name, // Display label
iconName: 'lucide:file',
closable: true, // Allow closing
action: () => showItemDetails(item)
});
// Select the new tab
appui.selectContentTab(`item-${item.id}`);
});
// Handle tab close
appui.addEventListener('tab-close', (e) => {
const tabKey = e.detail.key;
// Cleanup resources if needed
console.log(`Tab ${tabKey} closed`);
});
```
### Tab Management
```typescript
// Add/remove tabs
appui.addContentTab({
key: 'debug',
iconName: 'lucide:bug',
closable: true,
action: () => {}
});
appui.removeContentTab('debug');
// Select tab
appui.selectContentTab('preview');
// Get current tab
const current = appui.getSelectedContentTab();
// Visibility control
appui.setContentTabsVisible(false); // Hide tab bar
// Auto-hide when only one tab
appui.setContentTabsAutoHide(true, 1); // Hide when ≤ 1 tab
```
### Opening Items from Tables/Lists
A common pattern is opening table rows as closable tabs:
```typescript
@customElement('my-customers-view')
class MyCustomersView extends DeesElement {
private appui: DeesAppui;
onActivate(context: IViewActivationContext) {
this.appui = context.appui;
// Set base tabs
this.appui.setContentTabs([
{ key: 'list', label: 'All Customers', iconName: 'lucide:users', action: () => this.showList() }
]);
}
render() {
return html`
<dees-table
.data=${this.customers}
@row-dblclick=${this.openCustomerTab}
></dees-table>
`;
}
openCustomerTab(e: CustomEvent) {
const customer = e.detail.item;
const tabKey = `customer-${customer.id}`;
// Check if tab already exists
const existingTab = this.appui.getSelectedContentTab();
if (existingTab?.key === tabKey) {
return; // Already viewing this customer
}
// Add new closable tab
this.appui.addContentTab({
key: tabKey,
label: customer.name,
iconName: 'lucide:user',
closable: true,
action: () => this.showCustomerDetails(customer)
});
this.appui.selectContentTab(tabKey);
}
showCustomerDetails(customer: Customer) {
// Render customer details
this.currentView = html`<customer-details .customer=${customer}></customer-details>`;
}
showList() {
this.currentView = html`<dees-table ...></dees-table>`;
}
}
```
---
## Activity Log API 📊
The activity log is a slide-out panel on the right side showing user actions and system events.
### Activity Log Toggle
The appbar includes a toggle button with a badge showing the entry count:
```typescript
// Control visibility
appui.setActivityLogVisible(true); // Show panel
appui.toggleActivityLog(); // Toggle state
const isVisible = appui.getActivityLogVisible();
// The toggle button automatically shows entry count
// Add entries and the badge updates automatically
```
### Adding Entries
```typescript
// Add single entry
@@ -234,19 +477,35 @@ appui.activityLog.add({
data: { invoiceId: '123' } // Optional metadata
});
// Add multiple
// Add multiple entries (e.g., from backend)
appui.activityLog.addMany([...entries]);
// Clear
// Clear all entries
appui.activityLog.clear();
// Query
// Query entries
const entries = appui.activityLog.getEntries();
const filtered = appui.activityLog.filter({ user: 'John', type: 'create' });
const searched = appui.activityLog.search('invoice');
```
### Navigation API
### Activity Entry Types
Each type has a default icon that can be overridden:
| Type | Default Icon | Use Case |
|------|--------------|----------|
| `login` | `lucide:log-in` | User sign-in |
| `logout` | `lucide:log-out` | User sign-out |
| `view` | `lucide:eye` | Page/item viewed |
| `create` | `lucide:plus` | New item created |
| `update` | `lucide:pencil` | Item modified |
| `delete` | `lucide:trash` | Item deleted |
| `custom` | `lucide:activity` | Custom events |
---
## Navigation API
Navigate between views programmatically.
@@ -512,6 +771,7 @@ class CrmSettings extends DeesElement {
groups: [
{
name: 'Account',
iconName: 'lucide:user',
items: [
{ key: 'profile', iconName: 'lucide:user', action: () => this.showSection('profile') },
{ key: 'security', iconName: 'lucide:shield', action: () => this.showSection('security') }
@@ -519,6 +779,8 @@ class CrmSettings extends DeesElement {
},
{
name: 'Preferences',
iconName: 'lucide:settings',
collapsed: true,
items: [
{ key: 'notifications', iconName: 'lucide:bell', action: () => this.showSection('notifications') }
]
@@ -557,4 +819,5 @@ All interfaces are exported from `@design.estate/dees-catalog`:
- `IAppBarMenuItem` - App bar menu item
- `IMainMenuConfig` - Main menu configuration
- `ISecondaryMenuGroup` - Secondary menu group
- `ITab` - Tab definition
- `ISecondaryMenuItem` - Secondary menu item
- `IMenuItem` - Tab/menu item definition