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

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

@@ -0,0 +1,273 @@
+import { AXPMultiLanguageString, AXPEntityReference } from '@acorex-platform/framework-shared/core';
+import { AXStyleColorType } from '@acorex/cdk/common';
+import * as i0 from '@angular/core';
+import { InjectionToken } from '@angular/core';
+import * as i1 from '@angular/common';
+import * as i2 from '@acorex-platform/framework-client/layout/widget-core';
+
+/**
+ * Chart node data types for organization chart.
+ */
+
+/**
+ * Chart nodes use {@link AXPMultiLanguageString} for every user-visible string on the card
+ * (`title`, `subtitle`, `description`) so stored chart JSON and the UI respect locale.
+ *
+ * - Prefer **locale maps** `{ 'en-US': '…', 'fa-IR': '…' }` (see `createMultiLanguageString` in platform core).
+ * - A **plain string** is allowed as a narrow fallback; the resolver treats it as the value for any locale.
+ * - **`metadata`** fields that are shown in templates must also be `AXPMultiLanguageString` (or plain string
+ *   with the same rules), not English-only literals baked into feature code.
+ */
+declare enum AXMOrgChartNodeType {
+    Company = "Company",
+    BusinessUnit = "BusinessUnit",
+    Position = "Position",
+    Employee = "Employee"
+}
+/** Card layout for organizational (and compatible geographic) charts — see README merging strategy. */
+type AXMOrgChartCardTemplate = 'merged-executive' | 'merged-unit' | 'merged-manager' | 'position-ic' | 'employee-card' | 'compact';
+/** Structured head / CEO block for merged cards; `positionTitle` is always localized. */
+interface AXMOrgChartMergedRoleBlock {
+    positionTitle: AXPMultiLanguageString;
+    positionId?: string;
+    employeeName?: string;
+    employeeId?: string;
+    vacant: boolean;
+}
+declare enum AXMOrgChartCategory {
+    Company = "Company",
+    BusinessUnit = "BusinessUnit",
+    Position = "Position",
+    Employee = "Employee"
+}
+/** User-selectable hierarchy chart view in the organization chart page. */
+type OrgChartMode = 'location' | 'structure' | 'reporting' | 'positionHierarchy';
+interface AXMOrganizationNode {
+    id: string;
+    /** Primary label; must be multi-language when content is not a proper name. */
+    title: AXPMultiLanguageString;
+    /** Secondary line (e.g. head summary); use locale map when mixing labels and entity titles. */
+    subtitle?: AXPMultiLanguageString;
+    /** Body / mission text. */
+    description?: AXPMultiLanguageString;
+    isExpanded?: boolean;
+    children?: AXMOrganizationNode[];
+    icon?: string;
+    type?: AXMOrgChartNodeType;
+    parentId?: string | null;
+    entity?: AXPEntityReference;
+    /** Rich card data; any **display** field here should use `AXPMultiLanguageString` like the core node fields. */
+    metadata?: Record<string, any>;
+}
+/**
+ * Pill badge on org chart node cards (icon + label). {@link title} is translated in the template.
+ */
+interface AXMOrgChartNodeBadgeItem {
+    /** Font Awesome class segment (e.g. `fa-light fa-building`). */
+    icon: string;
+    title: AXPMultiLanguageString;
+}
+/**
+ * Footer metric cell: icon, numeric or short value, and translated label.
+ */
+interface AXMOrgChartNodeFooterMetric {
+    icon: string;
+    /** Plain display value (formatted number or short text). */
+    value: string;
+    title: AXPMultiLanguageString;
+}
+
+/**
+ * Injected by org chart node components to access colors, i18n labels, and expand/collapse.
+ */
+interface AXMOrgChartHostApi {
+    getNodeColors(color: string): Record<string, string>;
+    isNodeSelected(data: AXMOrganizationNode): boolean;
+    selectNode(data: AXMOrganizationNode): void;
+    openNodeContextMenuFromMore(event: unknown, data: AXMOrganizationNode): void;
+    readonly chartML: {
+        vacant: AXPMultiLanguageString;
+        directReports: AXPMultiLanguageString;
+        teams: AXPMultiLanguageString;
+        people: AXPMultiLanguageString;
+        positions: AXPMultiLanguageString;
+        chiefExecutive: AXPMultiLanguageString;
+        /** Business unit detail rows: unit head display name and role title from `metadata.unitHead`. */
+        buHead: AXPMultiLanguageString;
+        buPosition: AXPMultiLanguageString;
+        unitType: AXPMultiLanguageString;
+        businessUnit: AXPMultiLanguageString;
+        location: AXPMultiLanguageString;
+        code: AXPMultiLanguageString;
+        capacity: AXPMultiLanguageString;
+        level: AXPMultiLanguageString;
+        email: AXPMultiLanguageString;
+        phone: AXPMultiLanguageString;
+        employmentType: AXPMultiLanguageString;
+        workMode: AXPMultiLanguageString;
+        /** i18n key for the node “more” control (translate pipe). */
+        more: string;
+        /** i18n key when the context menu has no runnable actions. */
+        noActionsAvailable: string;
+    };
+    getTeamsMembershipCount(data: AXMOrganizationNode): number | null;
+    /** When the card body already shows the assignee (merged unit / manager seat), hide `subtitle` so it is not duplicated. */
+    shouldShowOrgCardSubtitle(data: AXMOrganizationNode): boolean;
+    /** Subtree / seat strip: BU & company snapshot stats, or `position-ic` seats (1 position; people from vacant state or subtree). */
+    getSubtreeRosterCounts(data: AXMOrganizationNode): {
+        people: number;
+        positions: number;
+    } | null;
+    /** Key-value rows for the side detail panel only (not rendered on node cards). */
+    getNodeInfoItems(data: AXMOrganizationNode): Array<{
+        label: AXPMultiLanguageString;
+        value: string;
+    }>;
+    toggleNode(data: AXMOrganizationNode, el?: HTMLDivElement | null): void;
+    /** Shows or hides the chart detail panel. */
+    toggleDetailPanel(): void;
+    /**
+     * Sets explicit expand/collapse for a branch and redraws the chart.
+     * @param expanded When false, children are hidden on the next layout (`isExpanded === false`).
+     */
+    setNodeBranchExpanded(data: AXMOrganizationNode, expanded: boolean): void;
+}
+
+type AXMOrgChartNodeKind = 'company-root' | 'business-unit' | 'position' | 'employee' | 'other';
+/** Section separator for org chart context menu rows built from {@link AXMOrgChartNodeMenuAction}. */
+type AXMOrgChartNodeMenuBreak = 'before' | 'after' | 'both';
+interface AXMOrgChartNodeContributionContext {
+    node: AXMOrganizationNode;
+    nodeKind: AXMOrgChartNodeKind;
+    selectedMode: 'location' | 'structure' | 'reporting' | 'positionHierarchy';
+    refreshChart: () => Promise<void>;
+    /** Page host (detail panel, branch expand/collapse, selection). */
+    host: AXMOrgChartHostApi;
+}
+interface AXMOrgChartNodeMenuAction {
+    id: string;
+    /** i18n key (`@scope:...`) or {@link AXPMultiLanguageString} locale map (`ax-menu-item` pipes `translate` without forwarding params — use maps for interpolated copy). */
+    title: string | AXPMultiLanguageString;
+    /** Interpolation helper for contributors; the org chart host does not pipe params into menu `translate` (use `title` maps). */
+    titleParams?: Record<string, string | number>;
+    icon?: string;
+    color?: AXStyleColorType;
+    order?: number;
+    disabled?: boolean;
+    /**
+     * Section separator for this row (and for `submenuGroupId` buckets: `before` / `after` / `both` also move the
+     * parent flyout's separator relative to siblings). `before` is implemented by setting `AXMenuItem.break` on the
+     * **previous** sibling at the same level (no-op when first).
+     */
+    break?: AXMOrgChartNodeMenuBreak;
+    /**
+     * Adds a separator after this row. Applies at any menu level (including root when a `submenuGroupId` flyout is
+     * flattened, e.g. Employee actions on an employee node). Does not set the parent bucket's trailing break; use
+     * {@link break} `after` / `both` on a member when the parent flyout row should also end a section.
+     */
+    submenuSectionBreak?: boolean;
+    /**
+     * When true, nested under the chart **Add …** submenu (business unit kinds, add position, and similar).
+     */
+    nestedInAddFlyout?: boolean;
+    /**
+     * Optional flyout: actions that share the same `submenuGroupId` render as children of one parent row.
+     * Use the same `submenuGroupTitle` for every member; `submenuGroupIcon` may be set on any member (first wins).
+     * On grouped members: {@link break} `after` / `both` adds a line inside the flyout below that child and sets the
+     * parent row's section break after the flyout; `before` / `both` on any member adds a line before the parent row
+     * (previous top-level sibling gets `break`). Use {@link submenuSectionBreak} for a separator after that child
+     * without affecting the parent bucket's trailing break.
+     * Cross-module chat + email on the org chart should use the communication constants in
+     * `org-chart-communication-submenu.const.ts` (`AXM_ORG_CHART_COMMUNICATION_SUBMENU_GROUP_ID`, title key, icon).
+     */
+    submenuGroupId?: string;
+    submenuGroupTitle?: string | AXPMultiLanguageString;
+    submenuGroupIcon?: string;
+    execute: (context: AXMOrgChartNodeContributionContext) => Promise<void>;
+}
+interface AXMOrgChartNodeInfoContribution {
+    id: string;
+    title: AXPMultiLanguageString;
+    order?: number;
+    load: (context: AXMOrgChartNodeContributionContext) => Promise<unknown>;
+}
+interface AXMOrgChartNodeContributionProvider {
+    getMenuActions(context: AXMOrgChartNodeContributionContext): Promise<AXMOrgChartNodeMenuAction[]>;
+    getInfoContributions?(context: AXMOrgChartNodeContributionContext): Promise<AXMOrgChartNodeInfoContribution[]>;
+}
+/**
+ * One multi-provider slot: an eager instance or a promise from a lazy provider factory (`provideLazyProvider`).
+ */
+type AXMOrgChartNodeContributorRef = AXMOrgChartNodeContributionProvider | Promise<AXMOrgChartNodeContributionProvider>;
+declare const AXM_ORG_CHART_NODE_CONTRIBUTOR: InjectionToken<AXMOrgChartNodeContributorRef>;
+
+/**
+ * Employee id for org chart **Employee** flyout actions: card occupant, unit head, top role, or an `employee` node.
+ * Returns undefined when the seat is vacant or no person is linked.
+ */
+declare function axmResolveOrgChartFlyoutEmployeeId(context: AXMOrgChartNodeContributionContext): string | undefined;
+
+/**
+ * Stable {@link AXMOrgChartNodeMenuAction.submenuGroupId} for actions that target the person on a card
+ * (chief executive, unit head, seat occupant) or the {@link AXMOrgChartNodeKind} `employee` node itself.
+ * Private chat/email move here from the Communication group.
+ */
+declare const AXM_ORG_CHART_EMPLOYEE_SUBMENU_GROUP_ID: "organization-management.org-chart.employee-submenu";
+/**
+ * i18n key: `organization-chart.employee-submenu.title` in `organization-management` assets.
+ */
+declare const AXM_ORG_CHART_EMPLOYEE_SUBMENU_TITLE_I18N_KEY: "@organization-management:organization-chart.employee-submenu.title";
+declare const AXM_ORG_CHART_EMPLOYEE_SUBMENU_ICON: "fa-light fa-user";
+
+/**
+ * Stable {@link AXMOrgChartNodeMenuAction.submenuGroupId} for panel toggle and branch expand/collapse.
+ */
+declare const AXM_ORG_CHART_LAYOUT_SUBMENU_GROUP_ID: "organization-management.org-chart.layout-submenu";
+/**
+ * i18n key: `organization-chart.layout-submenu.title` in `organization-management` assets.
+ */
+declare const AXM_ORG_CHART_LAYOUT_SUBMENU_TITLE_I18N_KEY: "@organization-management:organization-chart.layout-submenu.title";
+declare const AXM_ORG_CHART_LAYOUT_SUBMENU_ICON: "fa-light fa-sidebar";
+
+/**
+ * Stable {@link AXMOrgChartNodeMenuAction.submenuGroupId} so chat and email extensions merge
+ * their org-chart context actions under one parent flyout.
+ */
+declare const AXM_ORG_CHART_COMMUNICATION_SUBMENU_GROUP_ID: "organization-management.org-chart.communication-submenu";
+/**
+ * i18n key for the flyout parent label (`apps/.../organization-management.json`:
+ * `organization-chart.communication-submenu.title`).
+ */
+declare const AXM_ORG_CHART_COMMUNICATION_SUBMENU_TITLE_I18N_KEY: "@organization-management:organization-chart.communication-submenu.title";
+/** Parent row icon when actions from multiple modules supply the same group id. */
+declare const AXM_ORG_CHART_COMMUNICATION_SUBMENU_ICON: "fa-light fa-comments";
+
+/**
+ * Broadcasts when persisted org chart structure was rebuilt (server regen or optional client listener template).
+ * The chart page reloads from storage when {@link structureDataRevision} increments.
+ */
+declare class AXMOrgChartStructureRefreshHub {
+    private readonly revision;
+    readonly structureDataRevision: i0.Signal<number>;
+    notifyStructureRebuilt(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMOrgChartStructureRefreshHub, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMOrgChartStructureRefreshHub>;
+}
+
+/**
+ * Registers organization chart node contributors and chart-scoped commands for Organization Management.
+ */
+declare class AXMOrganizationChartModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMOrganizationChartModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<AXMOrganizationChartModule, never, never, never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<AXMOrganizationChartModule>;
+}
+
+declare class AXMOrganizationManagementModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMOrganizationManagementModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<AXMOrganizationManagementModule, never, [typeof i1.CommonModule, typeof i2.AXPWidgetCoreModule, typeof AXMOrganizationChartModule], never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<AXMOrganizationManagementModule>;
+}
+
+export { AXMOrgChartCategory, AXMOrgChartNodeType, AXMOrgChartStructureRefreshHub, AXMOrganizationManagementModule, AXM_ORG_CHART_COMMUNICATION_SUBMENU_GROUP_ID, AXM_ORG_CHART_COMMUNICATION_SUBMENU_ICON, AXM_ORG_CHART_COMMUNICATION_SUBMENU_TITLE_I18N_KEY, AXM_ORG_CHART_EMPLOYEE_SUBMENU_GROUP_ID, AXM_ORG_CHART_EMPLOYEE_SUBMENU_ICON, AXM_ORG_CHART_EMPLOYEE_SUBMENU_TITLE_I18N_KEY, AXM_ORG_CHART_LAYOUT_SUBMENU_GROUP_ID, AXM_ORG_CHART_LAYOUT_SUBMENU_ICON, AXM_ORG_CHART_LAYOUT_SUBMENU_TITLE_I18N_KEY, AXM_ORG_CHART_NODE_CONTRIBUTOR, axmResolveOrgChartFlyoutEmployeeId };
+export type { AXMOrgChartCardTemplate, AXMOrgChartMergedRoleBlock, AXMOrgChartNodeBadgeItem, AXMOrgChartNodeContributionContext, AXMOrgChartNodeContributionProvider, AXMOrgChartNodeContributorRef, AXMOrgChartNodeFooterMetric, AXMOrgChartNodeInfoContribution, AXMOrgChartNodeKind, AXMOrgChartNodeMenuAction, AXMOrgChartNodeMenuBreak, AXMOrganizationNode, OrgChartMode };