@acorex-platform/module-dashboard-management-client 0.0.21

package/types/acorex-platform-module-dashboard-management-client-contracts.d.ts

@@ -0,0 +1,368 @@
+declare const AXPDashboardManagementFeatureKeys: {};
+
+declare const AXPDashboardManagementMenuKeys: {
+    readonly Root: "DashboardManagement:Menu";
+    readonly Dashboards: "DashboardManagement:Menu:Dashboards";
+};
+
+/**
+ * Administration capabilities used by this module.
+ * Domain capability keys for this module. Root groups live in `AXPCommonPermissionGroupKeys` (common contracts).
+ */
+declare const AXPAdministrationPermissionKeys: {
+    readonly Access: "Administration:Permission:Access";
+    readonly MaintainUsersAndRoles: "Administration:Permission:MaintainUsersAndRoles";
+    readonly ManageSessions: "Administration:Permission:ManageSessions";
+    readonly MaintainPolicies: "Administration:Permission:MaintainPolicies";
+    readonly ViewIntegrations: "Administration:Permission:ViewIntegrations";
+    readonly MaintainConnections: "Administration:Permission:MaintainConnections";
+    readonly MaintainWorkflows: "Administration:Permission:MaintainWorkflows";
+    readonly ManageWorkflowActions: "Administration:Permission:ManageWorkflowActions";
+    readonly ViewRules: "Administration:Permission:ViewRules";
+    readonly MaintainRules: "Administration:Permission:MaintainRules";
+    readonly ManageRuleActions: "Administration:Permission:ManageRuleActions";
+    readonly MaintainAi: "Administration:Permission:MaintainAi";
+    readonly UseAiAssist: "Administration:Permission:UseAiAssist";
+    readonly MaintainDashboards: "Administration:Permission:MaintainDashboards";
+    readonly ViewJobs: "Administration:Permission:ViewJobs";
+    readonly ManageJobActions: "Administration:Permission:ManageJobActions";
+    readonly ViewObservability: "Administration:Permission:ViewObservability";
+    readonly MaintainObservability: "Administration:Permission:MaintainObservability";
+};
+/**
+ * @deprecated Prefer {@link AXPAdministrationPermissionKeys}.
+ * Legacy nested shape kept so existing imports compile during migration.
+ */
+declare const AXMPermissionsKeys: {
+    readonly DashboardManagement: {
+        readonly Management: "Administration:Permission:MaintainDashboards";
+        readonly Dashboard: {
+            readonly Management: "Administration:Permission:MaintainDashboards";
+            readonly View: "Administration:Permission:MaintainDashboards";
+            readonly Edit: "Administration:Permission:MaintainDashboards";
+            readonly Delete: "Administration:Permission:MaintainDashboards";
+            readonly Create: "Administration:Permission:MaintainDashboards";
+        };
+    };
+};
+
+declare enum AXPHomeDashboardSetting {
+    CurrentDashboard = "DashboardManagement:Setting:Home.CurrentDashboard"
+}
+
+/** Component key for the dashboard Layout page tab. Register via AXP_PAGE_COMPONENT_PROVIDER. */
+declare const DASHBOARD_LAYOUT_PAGE_COMPONENT_KEY = "dashboard-layout-page";
+
+declare const RootConfig: {
+    config: {
+        readonly i18n: "dashboard-management";
+        readonly module: "DashboardManagement";
+    };
+    module: {
+        module: "DashboardManagement";
+        name: "DashboardManagement";
+        title: string;
+        icon: string;
+    };
+    entities: {
+        dashboard: {
+            name: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+    };
+    /** Dashboard widget type ids owned by dashboard-management. */
+    widgets: {
+        barChart: string;
+        donutChart: string;
+        lineChart: string;
+        gaugeChart: string;
+        funnelChart: string;
+        heatmapChart: string;
+        stickyNote: string;
+        clockCalendar: string;
+        weather: string;
+        shortcut: string;
+        kpiProgress: string;
+        kpiSegmented: string;
+        kpiDetails: string;
+        kpiStatCard: string;
+    };
+    /**
+     * @deprecated Dashboard queries moved to owning modules (`{Module}:Dashboard:*`).
+     * Update seeds/widgets to module keys; these aliases remain for transitional references only.
+     */
+    queries: {
+        tenantAdmin: {
+            activeUsersKpi: string;
+            employeesKpi: string;
+            openTasksKpi: string;
+            activeProjectsKpi: string;
+            openHazardsKpi: string;
+            documentsKpi: string;
+            workflowDefinitionsKpi: string;
+            subscriptionKpi: string;
+            usersByRoleDonut: string;
+            taskStatusDonut: string;
+            deliveryStatusDonut: string;
+            integrationsDonut: string;
+            jobsByStatusBar: string;
+            jobSchedulesByStatusBar: string;
+            workflowsByStatusBar: string;
+            teamsBar: string;
+            projectsByStatusBar: string;
+            trainingComplianceGauge: string;
+        };
+    };
+};
+
+/**
+ * Dashboard visibility scope.
+ * - `T`: Tenant shared dashboard
+ * - `U`: User personal dashboard
+ * - `E`: Entity-scoped dashboard
+ */
+type AXMDashboardScope = 'U' | 'T' | 'E';
+/** Scope reference for personal dashboards. */
+interface AXMDashboardUserScopeRef {
+    userId: string;
+}
+/** Scope reference for tenant dashboards. */
+interface AXMDashboardTenantScopeRef {
+    tenantId: string;
+    roleIds: string[];
+}
+/** Scope reference for entity-type dashboards (one layout shared by all records of the type). */
+interface AXMDashboardEntityScopeRef {
+    entityType: string;
+}
+/**
+ * Scope-specific reference payload.
+ * Shape depends on {@link AXMDashboardScope}.
+ */
+type AXMDashboardScopeRef = AXMDashboardUserScopeRef | AXMDashboardTenantScopeRef | AXMDashboardEntityScopeRef;
+
+/** Grid size preset as `[width, height]` in column/row units. */
+type AXGridLayoutSize = readonly [width: number, height: number];
+interface AXGridLayoutNode {
+    id?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    /** When set, resize snaps to one of these `[width, height]` presets. */
+    allowedSizes?: readonly AXGridLayoutSize[];
+}
+type AXMDashboardBreakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
+interface AXMDashboardWidgetLayoutMap {
+    id: string;
+    title?: string;
+    lg: AXGridLayoutNode;
+    md: AXGridLayoutNode;
+    sm: AXGridLayoutNode;
+    xl?: AXGridLayoutNode;
+    '2xl'?: AXGridLayoutNode;
+    '3xl'?: AXGridLayoutNode;
+    '4xl'?: AXGridLayoutNode;
+}
+interface AXMDashboardWidgetData {
+    config: AXMDashboardWidgetLayoutMap;
+    node?: unknown;
+}
+type AXPMultiLanguageString = string | Record<string, string>;
+interface AXPEntityModel<Id> {
+    id: Id;
+    auditInfo?: {
+        created?: {
+            at?: string | Date;
+            by?: {
+                id: string;
+                type?: string;
+            };
+        };
+        updated?: {
+            at?: string | Date;
+            by?: {
+                id: string;
+                type?: string;
+            };
+        };
+    };
+    stateInfo?: Record<string, unknown>;
+    scopeInfo?: {
+        tenantId?: string;
+        userId?: string;
+        applicationId?: string;
+    };
+}
+interface AXMCommonDashboardEntityModel extends AXPEntityModel<string> {
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
+    widgets: AXMDashboardWidgetData[];
+    isArchived?: boolean;
+    archivedAt?: string | Date;
+    locked?: boolean;
+    scope: AXMDashboardScope;
+    scopeRef: AXMDashboardScopeRef;
+    categoryIds?: string[];
+}
+
+/**
+ * Strict DTOs for dashboard chart / KPI queries.
+ * Chart widgets fetch an AXPQuery whose result matches one of these shapes.
+ */
+/** Stable result-type ids stored on query definitions for designer filtering. */
+declare const AXP_CHART_QUERY_RESULT_TYPE: {
+    readonly barSeries: "AXPBarChartQueryResult";
+    readonly lineSeries: "AXPLineChartQueryResult";
+    readonly donutSeries: "AXPDonutChartQueryResult";
+    readonly gaugeValue: "AXPGaugeChartQueryResult";
+    readonly funnelSeries: "AXPFunnelChartQueryResult";
+    readonly heatmapSeries: "AXPHeatmapChartQueryResult";
+    readonly kpiStatCard: "AXPKpiStatCardQueryResult";
+    readonly kpiSegmented: "AXPKpiSegmentedQueryResult";
+    readonly kpiProgress: "AXPKpiProgressQueryResult";
+    readonly kpiDetails: "AXPKpiDetailsQueryResult";
+};
+type AXPChartQueryResultType = (typeof AXP_CHART_QUERY_RESULT_TYPE)[keyof typeof AXP_CHART_QUERY_RESULT_TYPE];
+interface AXPBarChartQueryItem {
+    id: string;
+    label: string;
+    value: number;
+    color?: string;
+    tooltipLabel?: string;
+}
+interface AXPLineChartQueryPoint {
+    x: number | string;
+    y: number;
+    tooltipLabel?: string;
+}
+interface AXPLineChartQuerySeries {
+    id?: string;
+    label?: string;
+    lineColor?: string;
+    fillColor?: string;
+    data: AXPLineChartQueryPoint[];
+}
+interface AXPDonutChartQueryItem {
+    id: string;
+    label: string;
+    value: number;
+    color?: string;
+    tooltipLabel?: string;
+}
+interface AXPFunnelChartQueryItem {
+    id?: string;
+    name: string;
+    value: number;
+    color?: string;
+}
+interface AXPHeatmapChartQueryItem {
+    x: number | string;
+    y: number | string;
+    value: number;
+    label?: string;
+}
+interface AXPBarChartQueryResult {
+    items: AXPBarChartQueryItem[];
+}
+interface AXPLineChartQueryResult {
+    series: AXPLineChartQuerySeries[];
+}
+interface AXPDonutChartQueryResult {
+    items: AXPDonutChartQueryItem[];
+}
+interface AXPGaugeChartQueryResult {
+    value: number;
+}
+interface AXPFunnelChartQueryResult {
+    items: AXPFunnelChartQueryItem[];
+}
+interface AXPHeatmapChartQueryResult {
+    items: AXPHeatmapChartQueryItem[];
+}
+interface AXPKpiStatCardQueryResult {
+    title?: string;
+    titleBadgeText?: string;
+    titleBadgeTone?: string;
+    value?: number | string;
+    valuePrefix?: string;
+    valueSuffix?: string;
+    format?: {
+        style?: 'decimal' | 'currency' | 'percent';
+        currency?: string;
+        minimumFractionDigits?: number;
+        maximumFractionDigits?: number;
+    };
+    icon?: string;
+    iconTone?: string;
+    trendValue?: string;
+    trendLabel?: string;
+    trendStatus?: 'success' | 'danger' | 'neutral';
+}
+interface AXPKpiSegmentedQueryResult {
+    title?: string;
+    icon?: string;
+    segments: Array<{
+        label: string;
+        value: number;
+        color?: string;
+    }>;
+}
+interface AXPKpiProgressQueryResult {
+    title?: string;
+    icon?: string;
+    value?: number | string;
+    valuePrefix?: string;
+    valueSuffix?: string;
+    subtitle?: string;
+    targetValue?: number | string;
+    progressValue?: number;
+    progressPercent?: number;
+}
+interface AXPKpiDetailsQueryResult {
+    title?: string;
+    value?: number | string;
+    valuePrefix?: string;
+    valueSuffix?: string;
+    subtitle?: string;
+    details: Array<{
+        label: string;
+        value: string | number;
+        color?: string;
+    }>;
+}
+/** Chart/KPI widget options for data binding (dashboard query and/or AI inline data). */
+interface AXPChartQueryWidgetOptions {
+    /** Runtime AXPQuery key (e.g. `PlatformManagement:Dashboard:TenantsByStatusBar`). */
+    query?: string;
+    /** Optional input payload passed to `queryExecutor.fetch(query, queryInput)`. */
+    queryInput?: Record<string, unknown>;
+    /** Inline chart rows/series for AI chat (see chart-widget-data.util.ts). */
+    dataSource?: unknown;
+}
+
+declare function buildUserScopeRef(userId: string): AXMDashboardUserScopeRef;
+declare function buildTenantScopeRef(tenantId: string, roleIds: readonly string[]): AXMDashboardTenantScopeRef;
+declare function buildEntityScopeRef(entityType: string): AXMDashboardEntityScopeRef;
+declare function readScopeUserId(scopeRef: AXMDashboardScopeRef | undefined): string | undefined;
+declare function readScopeTenantId(scopeRef: AXMDashboardScopeRef | undefined): string | undefined;
+declare function readScopeRoleIds(scopeRef: AXMDashboardScopeRef | undefined): string[];
+declare function readScopeEntityType(scopeRef: AXMDashboardScopeRef | undefined): string | undefined;
+/**
+ * Ensures {@link scopeRef} matches {@link scope} and strips incompatible keys.
+ */
+declare function normalizeDashboardScopeRef(scope: AXMDashboardScope, scopeRef: unknown, fallback?: Partial<{
+    userId: string;
+    tenantId: string;
+    roleIds: readonly string[];
+    entityType: string;
+}>): AXMDashboardScopeRef;
+
+export { AXMPermissionsKeys, AXPAdministrationPermissionKeys, AXPDashboardManagementFeatureKeys, AXPDashboardManagementMenuKeys, AXPHomeDashboardSetting, AXP_CHART_QUERY_RESULT_TYPE, DASHBOARD_LAYOUT_PAGE_COMPONENT_KEY, RootConfig, buildEntityScopeRef, buildTenantScopeRef, buildUserScopeRef, normalizeDashboardScopeRef, readScopeEntityType, readScopeRoleIds, readScopeTenantId, readScopeUserId };
+export type { AXGridLayoutNode, AXGridLayoutSize, AXMCommonDashboardEntityModel, AXMDashboardBreakpoint, AXMDashboardEntityScopeRef, AXMDashboardScope, AXMDashboardScopeRef, AXMDashboardTenantScopeRef, AXMDashboardUserScopeRef, AXMDashboardWidgetData, AXMDashboardWidgetLayoutMap, AXPBarChartQueryItem, AXPBarChartQueryResult, AXPChartQueryResultType, AXPChartQueryWidgetOptions, AXPDonutChartQueryItem, AXPDonutChartQueryResult, AXPEntityModel, AXPFunnelChartQueryItem, AXPFunnelChartQueryResult, AXPGaugeChartQueryResult, AXPHeatmapChartQueryItem, AXPHeatmapChartQueryResult, AXPKpiDetailsQueryResult, AXPKpiProgressQueryResult, AXPKpiSegmentedQueryResult, AXPKpiStatCardQueryResult, AXPLineChartQueryPoint, AXPLineChartQueryResult, AXPLineChartQuerySeries, AXPMultiLanguageString };