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

2026-01-03 02:09:13 +00:00
parent c3444aac01
commit 8313c24c9d
4 changed files with 469 additions and 43 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,6 +1,6 @@
 # @design.estate/dees-catalog

-A comprehensive web components library built with TypeScript and LitElement, providing **75+ UI components** for building modern web applications with consistent design and behavior. 🚀
+A comprehensive web components library built with TypeScript and LitElement, providing **80+ production-ready UI components** for building modern web applications with consistent design and behavior. 🚀

 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![LitElement](https://img.shields.io/badge/LitElement-4.0+-orange.svg)](https://lit.dev/)
@@ -53,13 +53,14 @@ For developers working on this library, please refer to the [UI Components Playb
 | Category | Components |
 |----------|------------|
 | **Core UI** | [`DeesButton`](#deesbutton), [`DeesButtonExit`](#deesbuttonexit), [`DeesButtonGroup`](#deesbuttongroup), [`DeesBadge`](#deesbadge), [`DeesChips`](#deeschips), [`DeesHeading`](#deesheading), [`DeesHint`](#deeshint), [`DeesIcon`](#deesicon), [`DeesLabel`](#deeslabel), [`DeesPanel`](#deespanel), [`DeesSearchbar`](#deessearchbar), [`DeesSpinner`](#deesspinner), [`DeesToast`](#deestoast), [`DeesWindowcontrols`](#deeswindowcontrols) |
-| **Forms** | [`DeesForm`](#deesform), [`DeesInputText`](#deesinputtext), [`DeesInputCheckbox`](#deesinputcheckbox), [`DeesInputDropdown`](#deesinputdropdown), [`DeesInputRadiogroup`](#deesinputradiogroup), [`DeesInputFileupload`](#deesinputfileupload), [`DeesInputIban`](#deesinputiban), [`DeesInputPhone`](#deesinputphone), [`DeesInputQuantitySelector`](#deesinputquantityselector), [`DeesInputMultitoggle`](#deesinputmultitoggle), [`DeesInputTags`](#deesinputtags), [`DeesInputTypelist`](#deesinputtypelist), [`DeesInputRichtext`](#deesinputrichtext), [`DeesInputWysiwyg`](#deesinputwysiwyg), [`DeesInputDatepicker`](#deesinputdatepicker), [`DeesInputSearchselect`](#deesinputsearchselect), [`DeesFormSubmit`](#deesformsubmit) |
+| **Forms** | [`DeesForm`](#deesform), [`DeesInputText`](#deesinputtext), [`DeesInputCheckbox`](#deesinputcheckbox), [`DeesInputDropdown`](#deesinputdropdown), [`DeesInputRadiogroup`](#deesinputradiogroup), [`DeesInputFileupload`](#deesinputfileupload), [`DeesInputIban`](#deesinputiban), [`DeesInputPhone`](#deesinputphone), [`DeesInputQuantitySelector`](#deesinputquantityselector), [`DeesInputMultitoggle`](#deesinputmultitoggle), [`DeesInputTags`](#deesinputtags), [`DeesInputTypelist`](#deesinputtypelist), [`DeesInputList`](#deesinputlist), [`DeesInputProfilepicture`](#deesinputprofilepicture), [`DeesInputRichtext`](#deesinputrichtext), [`DeesInputWysiwyg`](#deesinputwysiwyg), [`DeesInputDatepicker`](#deesinputdatepicker), [`DeesInputSearchselect`](#deesinputsearchselect), [`DeesFormSubmit`](#deesformsubmit) |
 | **Layout** | [`DeesAppui`](#deesappui), [`DeesAppuiMainmenu`](#deesappuimainmenu), [`DeesAppuiSecondarymenu`](#deesappuisecondarymenu), [`DeesAppuiMaincontent`](#deesappuimaincontent), [`DeesAppuiAppbar`](#deesappuiappbar), [`DeesAppuiActivitylog`](#deesappuiactivitylog), [`DeesAppuiProfiledropdown`](#deesappuiprofiledropdown), [`DeesAppuiTabs`](#deesappuitabs), [`DeesMobileNavigation`](#deesmobilenavigation), [`DeesDashboardGrid`](#deesdashboardgrid) |
 | **Data Display** | [`DeesTable`](#deestable), [`DeesDataviewCodebox`](#deesdataviewcodebox), [`DeesDataviewStatusobject`](#deesdataviewstatusobject), [`DeesPdf`](#deespdf), [`DeesStatsGrid`](#deesstatsgrid), [`DeesPagination`](#deespagination) |
 | **Visualization** | [`DeesChartArea`](#deeschartarea), [`DeesChartLog`](#deeschartlog) |
 | **Dialogs & Overlays** | [`DeesModal`](#deesmodal), [`DeesContextmenu`](#deescontextmenu), [`DeesSpeechbubble`](#deesspeechbubble), [`DeesWindowlayer`](#deeswindowlayer) |
 | **Navigation** | [`DeesStepper`](#deesstepper), [`DeesProgressbar`](#deesprogressbar) |
 | **Development** | [`DeesEditor`](#deeseditor), [`DeesEditorMarkdown`](#deeseditormarkdown), [`DeesEditorMarkdownoutlet`](#deeseditormarkdownoutlet), [`DeesTerminal`](#deesterminal), [`DeesUpdater`](#deesupdater) |
+| **Theming** | [`DeesTheme`](#deestheme) |
 | **Auth & Utilities** | [`DeesSimpleAppdash`](#deessimpleappdash), [`DeesSimpleLogin`](#deessimplelogin) |
 | **Shopping** | [`DeesShoppingProductcard`](#deesshoppingproductcard) |

@@ -482,6 +483,62 @@ Dynamic list input for managing arrays of typed values.
 ></dees-input-typelist>
 ```

+#### `DeesInputList`
+Advanced list input with drag-and-drop reordering, inline editing, and validation.
+
+```typescript
+<dees-input-list
+  key="items"
+  label="List Items"
+  placeholder="Add new item..."
+  .value=${['Item 1', 'Item 2', 'Item 3']}
+  maxItems={10}            // Optional: maximum items
+  minItems={1}             // Optional: minimum items
+  allowDuplicates={false}  // Optional: allow duplicate values
+  sortable={true}          // Optional: enable drag-and-drop reordering
+  confirmDelete={true}     // Optional: confirm before deletion
+  @change=${handleListChange}
+></dees-input-list>
+```
+
+**Key Features:**
+- Add, edit, and remove items inline
+- Drag-and-drop reordering with visual feedback
+- Optional duplicate prevention
+- Min/max item constraints
+- Delete confirmation dialog
+- Full keyboard support
+- Form validation integration
+
+#### `DeesInputProfilepicture`
+Profile picture input with cropping, zoom, and image processing.
+
+```typescript
+<dees-input-profilepicture
+  key="avatar"
+  label="Profile Picture"
+  shape="round"           // Options: round, square
+  size={120}              // Display size in pixels
+  .value=${imageBase64}   // Base64 encoded image or URL
+  allowUpload={true}      // Enable upload button
+  allowDelete={true}      // Enable delete button
+  maxFileSize={5242880}   // Max file size in bytes (5MB)
+  .acceptedFormats=${['image/jpeg', 'image/png', 'image/webp']}
+  outputSize={800}        // Output resolution in pixels
+  outputQuality={0.95}    // JPEG quality (0-1)
+  @change=${handleAvatarChange}
+></dees-input-profilepicture>
+```
+
+**Key Features:**
+- Interactive cropping modal with zoom and pan
+- Drag-and-drop file upload
+- Round or square output shapes
+- Configurable output size and quality
+- File size and format validation
+- Delete functionality
+- Preview on hover
+
 #### `DeesInputDatepicker`
 Date and time picker component with calendar interface and manual typing support.

@@ -661,6 +718,7 @@ class MyApp extends DeesElement {
 - **Hash-based Routing**: Automatic URL synchronization with view navigation
 - **RxJS Observables**: `viewChanged$` and `viewLifecycle$` for reactive programming
 - **TypeScript-first**: Typed `IViewActivationContext` passed to views on activation
+- **Activity Log Toggle**: Built-in appbar button to show/hide activity panel with entry count badge

 **Programmatic APIs include:**
 - `navigateToView(viewId, params?)` - Navigate between views
@@ -670,6 +728,7 @@ class MyApp extends DeesElement {
 - `setSecondaryMenu()`, `setSecondaryMenuCollapsed()`, `setSecondaryMenuVisible()` - Control secondary menu
 - `setContentTabs()`, `setContentTabsVisible()` - Control view-specific UI
 - `activityLog.add()`, `activityLog.addMany()`, `activityLog.clear()` - Manage activity entries
+- `setActivityLogVisible()`, `toggleActivityLog()`, `getActivityLogVisible()` - Control activity panel

 **View Visibility Control:**
 ```typescript
@@ -740,7 +799,7 @@ Main content area with tab management support.
 ```

 #### `DeesAppuiAppbar`
-Professional application bar component with hierarchical menus, breadcrumb navigation, and user account management.
+Professional application bar component with hierarchical menus, breadcrumb navigation, user account management, and activity log toggle.

 ```typescript
 <dees-appui-appbar
@@ -775,6 +834,9 @@ Professional application bar component with hierarchical menus, breadcrumb navig
  .breadcrumbs=${'Project > src > components'}
  .showWindowControls=${true}
  .showSearch=${true}
+  .showActivityLogToggle=${true}
+  .activityLogCount=${5}
+  .activityLogActive=${false}
  .user=${{
    name: 'John Doe',
    avatar: '/path/to/avatar.jpg',
@@ -782,6 +844,7 @@ Professional application bar component with hierarchical menus, breadcrumb navig
  }}
  @menu-select=${(e) => handleMenuSelect(e.detail.item)}
  @breadcrumb-navigate=${(e) => handleBreadcrumbClick(e.detail)}
+  @activity-toggle=${() => handleActivityToggle()}
 ></dees-appui-appbar>
 ```

@@ -789,9 +852,40 @@ Professional application bar component with hierarchical menus, breadcrumb navig
 - **Hierarchical Menu System** - Top-level menus with dropdown submenus, icons, and keyboard shortcuts
 - **Keyboard Navigation** - Full keyboard support (Tab, Arrow keys, Enter, Escape)
 - **Breadcrumb Navigation** - Customizable breadcrumb trail with click events
- **User Account Section** - Avatar with status indicator
+- **User Account Section** - Avatar with status indicator and profile dropdown
+- **Activity Log Toggle** - Button with badge count to show/hide activity panel
 - **Accessibility** - Full ARIA support with menubar roles

+#### `DeesAppuiActivitylog`
+Real-time activity log panel for displaying user actions and system events.
+
+```typescript
+<dees-appui-activitylog></dees-appui-activitylog>
+
+// Programmatic API
+activityLog.add({
+  type: 'update',        // Options: login, logout, view, create, update, delete, custom
+  user: 'John Doe',
+  message: 'Updated project settings',
+  iconName: 'lucide:settings'  // Optional: custom icon
+});
+
+activityLog.addMany(entries);  // Add multiple entries
+activityLog.clear();           // Clear all entries
+activityLog.getEntries();      // Get all entries
+activityLog.filter({ user: 'John' });  // Filter by user/type
+activityLog.search('settings');        // Search by message
+```
+
+**Key Features:**
+- Stacked entry layout with icon, user, timestamp, and message
+- Date grouping (Today, Yesterday, etc.)
+- Search and filter functionality
+- Context menu for entry actions
+- Live streaming indicator
+- Animated slide-in/out panel
+- Theme-aware styling
+
 #### `DeesAppuiTabs`
 Reusable tab component with horizontal/vertical layout support.

@@ -1089,6 +1183,40 @@ Progress indicator component for tracking completion status.

 ---

+### Theming Components
+
+#### `DeesTheme`
+Theme provider component that wraps children and provides CSS custom properties for consistent theming.
+
+```typescript
+// Basic usage - wrap your app
+<dees-theme>
+  <my-app></my-app>
+</dees-theme>
+
+// With custom overrides
+<dees-theme
+  .customColors=${{
+    primary: '#007bff',
+    success: '#28a745'
+  }}
+  .customSpacing=${{
+    lg: '24px',
+    xl: '32px'
+  }}
+>
+  <my-section></my-section>
+</dees-theme>
+```
+
+**Key Features:**
+- Provides CSS custom properties for colors, spacing, radius, shadows, and transitions
+- Can be nested for section-specific theming
+- Works with dark/light mode
+- Overrides cascade to all child components
+
+---
+
 ### Development Components

 #### `DeesEditor`
@@ -1241,6 +1369,29 @@ interface IMenuGroup {
  collapsed?: boolean;
  iconName?: string;
 }
+
+// View definition for app navigation
+interface IViewDefinition {
+  id: string;
+  name: string;
+  iconName?: string;
+  content: string | HTMLElement | (() => TemplateResult);
+  secondaryMenu?: ISecondaryMenuGroup[];
+  contentTabs?: IMenuItem[];
+  route?: string;
+  badge?: string | number;
+}
+
+// Activity log entry
+interface IActivityEntry {
+  id?: string;
+  timestamp?: Date;
+  type: 'login' | 'logout' | 'view' | 'create' | 'update' | 'delete' | 'custom';
+  user: string;
+  message: string;
+  iconName?: string;
+  data?: Record<string, unknown>;
+}
 ```

 ---