@acorex/platform 21.0.0-next.10 → 21.0.0-next.11

package/core/index.d.ts

@@ -945,6 +945,7 @@ interface AXPContent {
 }
 
 type AXPDataSource = string | AXDataSource | any[];
+type AXPDataType = 'string' | 'number' | 'object' | 'boolean' | 'array';
 interface AXPPagedListResult<T = any> {
     items: T[];
     total: number;
@@ -958,16 +959,121 @@ interface AXPQueryRequest {
         [key: string]: string;
     };
 }
-type AXPDataType = 'string' | 'number' | 'object' | 'boolean' | 'array';
+/**
+ * Category Entity - Base interface for hierarchical category structures
+ *
+ * This interface provides a standardized data model for category entities across the platform.
+ * All category entities (e.g., ReportCategory, ActivityCategory, WorkflowCategory) extend this interface
+ * to ensure consistency in data structure and field names.
+ *
+ * @template TKey - The type of the identifier key (default: string)
+ *
+ * @example
+ * ```typescript
+ * const category: AXPCategoryEntity = {
+ *   id: 'cat-001',
+ *   title: 'Electronics',
+ *   description: 'Electronic products',
+ *   parentId: undefined, // Root category
+ *   childrenCount: 2,    // Has 2 direct child categories
+ *   itemsCount: 5,      // Has 5 items directly in this category
+ *   totalChildrenCount: 6,  // Total of 6 nested categories (including grandchildren)
+ *   totalItemsCount: 23     // Total of 23 items in entire category tree
+ * };
+ * ```
+ */
 interface AXPCategoryEntity<TKey = string> {
+    /** Unique identifier for the category */
     id: TKey;
+    /** Display name of the category (required) */
     title: string;
+    /** Optional description of the category */
     description?: string;
+    /** Parent category ID (undefined for root categories) */
     parentId?: TKey;
+    /**
+     * Count of direct child categories only (not recursive)
+     *
+     * Used by UI components to determine if a category has children and should show an expand icon.
+     * This enables efficient lazy loading - components can check this property without querying the API.
+     *
+     * @example
+     * - Category with 2 direct children: `childrenCount: 2`
+     * - Leaf category (no children): `childrenCount: 0`
+     *
+     * @remarks
+     * - Always set to `0` for leaf categories
+     * - Does not include grandchildren or nested descendants
+     * - Automatically maintained by middleware for category entities
+     */
     childrenCount: number;
+    /**
+     * Count of items directly assigned to this category (not recursive)
+     *
+     * Represents the number of items (e.g., reports, activities, workflows) that are directly
+     * assigned to this category. Does not include items from child categories.
+     *
+     * Useful for:
+     * - Displaying item counts per category in UI (e.g., "5 reports" badge)
+     * - Optimizing queries (skip API call if itemsCount === 0)
+     * - Showing category statistics
+     *
+     * @example
+     * - Category with 5 reports directly assigned: `itemsCount: 5`
+     * - Category with no direct items: `itemsCount: 0` or `undefined`
+     *
+     * @remarks
+     * - Does not include items from child categories
+     * - Can be calculated dynamically or stored
+     * - Optional - may be undefined if not needed
+     */
     itemsCount?: number;
-    totalChildren?: number;
-    totalItems?: number;
+    /**
+     * Recursive count of all nested child categories (includes all descendants)
+     *
+     * Represents the total number of categories in the entire subtree starting from this category.
+     * Includes children, grandchildren, and all nested descendants.
+     *
+     * Useful for:
+     * - Analytics and summary displays
+     * - Showing complete category tree scope
+     * - Performance metrics
+     *
+     * @example
+     * Root category with:
+     * - 2 direct children
+     * - Each child has 2 children (4 grandchildren)
+     * Result: `totalChildrenCount: 6` (2 + 4)
+     *
+     * @remarks
+     * - Optional - typically used for analytics
+     * - Includes all nested levels (recursive)
+     * - Can be expensive to calculate for large trees
+     */
+    totalChildrenCount?: number;
+    /**
+     * Recursive count of all items in this category and all descendants
+     *
+     * Represents the total number of items (e.g., reports, activities, workflows) in the entire
+     * category tree, including items from this category and all nested child categories.
+     *
+     * Useful for:
+     * - Analytics and summary displays
+     * - Showing complete scope of a category branch
+     * - Dashboard statistics
+     *
+     * @example
+     * Category with:
+     * - 5 items directly assigned
+     * - 1 child category with 3 items
+     * Result: `totalItemsCount: 8` (5 + 3)
+     *
+     * @remarks
+     * - Optional - typically used for analytics
+     * - Includes items from all nested categories (recursive)
+     * - Can be expensive to calculate for large trees
+     */
+    totalItemsCount?: number;
 }
 interface AXPCategoryEntityWithItems<T> extends AXPCategoryEntity {
     items: T[];

package/fesm2022/acorex-platform-core.mjs

@@ -3177,6 +3177,9 @@ function getNestedKeys(obj, prefix = '') {
     return keys;
 }
 
+//#region ----   Imports   ----
+//#endregion
+
 function applySystemActionDefault(action, type) {
     const systemAction = getSystemActions(type);
     return {