feat(docs): add documentation for new input components, activity log features, theming, and expand DeesAppui docs
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user