@skysoftware-co/bayan-core-widgets-ui 0.0.1

package/README.md

@@ -0,0 +1,336 @@
+# @skysoftware-co/bayan-core-widgets-ui
+
+Reusable Angular widgets for Bayan top-menu scenarios.
+
+## Package Surface
+
+This package currently exports:
+
+- `BayanCoreTopMenuWidgetComponent`
+- `BayanCoreTopMenuService`
+- shared DTOs from `menu.dtos`
+
+The child widgets are documented below because they make up the top-menu contract, but they are currently intended for internal composition rather than direct package consumption.
+
+## Installation
+
+```bash
+npm install @skysoftware-co/bayan-core-widgets-ui
+```
+
+## Basic Usage
+
+```html
+<bayan-core-top-menu-widget
+  [baseUrl]="appBaseUrl"
+  [sidebarCollapsed]="sidebarCollapsed"
+  [homeUrl]="homeUrl"
+  [logoUrl]="logoUrl"
+  [collapsedLogoUrl]="collapsedLogoUrl"
+  [menuItems]="menuItems"
+  [searchItems]="searchItems"
+  [userPanel]="userPanel"
+  [nameModeItems]="nameModeItems"
+  [showGlobalSearch]="true"
+  [showUserPanel]="true"
+  [showSettings]="true"
+  [showNotifications]="true"
+  [showHelp]="true"
+  [useInternalDialogs]="true"
+  [aboutDialog]="aboutDialog"
+  [changePasswordDialog]="changePasswordDialog"
+  (menuItemClick)="onMenuItemClick($event)"
+  (searchSubmit)="onSearchSubmit($event)"
+  (searchItemNavigate)="onSearchItemNavigate($event)"
+  (propertyChange)="onPropertyChange($event)"
+  (signOutClick)="onSignOut()"
+  (submitPasswordChange)="onSubmitPasswordChange($event)">
+</bayan-core-top-menu-widget>
+```
+
+## Models
+
+```ts
+interface TopMenuWidgetItem {
+  id?: string | number;
+  menuName: string;
+  menuUrl?: string | null;
+  children?: TopMenuWidgetItem[];
+}
+
+interface TopMenuWidgetSearchItem {
+  id?: string | number;
+  menuTitle: string;
+  menuSubTitle: string;
+  menuUrl?: string | null;
+  iconClass?: string | null;
+  isTranslatable?: boolean;
+}
+
+interface TopMenuWidgetPropertyOption {
+  propertyId: number;
+  propertyName: string;
+}
+
+interface TopMenuWidgetUserPanel {
+  userDisplayName: string;
+  activePropertyId: number | null;
+  activePropertyName: string;
+  properties: TopMenuWidgetPropertyOption[];
+  isSsoLogin?: boolean;
+  photoPath?: string | null;
+  nameInitials?: string | null;
+}
+
+interface TopMenuWidgetNameModeItem {
+  id: string;
+  text: string;
+  selected: boolean;
+}
+
+interface TopMenuWidgetAboutDialogConfig {
+  title?: string;
+  logoUrl?: string;
+  version?: string;
+  versionLabel?: string;
+  copyright?: string;
+  statusLabel?: string;
+  licenseButtonLabel?: string;
+  releaseNotesButtonLabel?: string;
+  supportButtonLabel?: string;
+  closeButtonLabel?: string;
+}
+
+interface TopMenuWidgetChangePasswordDialogConfig {
+  title: string;
+  currentPasswordLabel: string;
+  newPasswordLabel: string;
+  confirmNewPasswordLabel: string;
+  primaryButtonText: string;
+}
+
+interface TopMenuWidgetChangePasswordPayload {
+  currentPassword: string;
+  newPassword: string;
+  confirmNewPassword: string;
+}
+```
+
+## Top Menu Widget
+
+Selector: `bayan-core-top-menu-widget`
+
+### Inputs
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | `''` | Base URL used to resolve internal and external navigation targets. |
+| `sidebarCollapsed` | `boolean` | `false` | Switches the brand area to the collapsed logo state. |
+| `homeUrl` | `string \| null` | `null` | Brand navigation target. |
+| `logoUrl` | `string` | Bayan CDN URL | Expanded logo source. |
+| `collapsedLogoUrl` | `string` | Bayan CDN URL | Collapsed logo source. |
+| `searchPlaceholder` | `string` | `'TopMenu.SearchPlaceholder'` | Search placeholder text or translation key. |
+| `menuItems` | `TopMenuWidgetItem[]` | `[]` | Top-level navigation items. |
+| `searchItems` | `TopMenuWidgetSearchItem[]` | `[]` | Autocomplete items for global search. |
+| `userPanel` | `TopMenuWidgetUserPanel \| null` | `null` | Current user data and available properties. |
+| `isSsoLogin` | `boolean` | `false` | Fallback SSO flag when the user panel does not provide one. |
+| `useAlternateNames` | `boolean` | `false` | Enables alternate-names behavior in settings. |
+| `displayAlternateNames` | `boolean` | `false` | Marks alternate names as active. |
+| `hrBlocked` | `boolean` | `false` | Current HR block state. |
+| `hrCanBlock` | `boolean` | `false` | Enables HR block and release actions. |
+| `tkBlocked` | `boolean` | `false` | Current Timekeeping block state. |
+| `tkCanBlock` | `boolean` | `false` | Enables Timekeeping block and release actions. |
+| `nameModeItems` | `TopMenuWidgetNameModeItem[]` | `[]` | Name display mode options. |
+| `settingsEnabled` | `boolean` | `true` | Enables settings interactions. |
+| `useInternalDialogs` | `boolean` | `false` | Shows built-in About and Change Password dialogs. |
+| `changePasswordLoading` | `boolean` | `false` | Loading state for the built-in Change Password dialog. |
+| `changePasswordDialog` | `TopMenuWidgetChangePasswordDialogConfig` | default labels | Built-in Change Password dialog labels. |
+| `aboutDialog` | `TopMenuWidgetAboutDialogConfig` | default labels | Built-in About dialog content and labels. |
+| `showGlobalSearch` | `boolean` | `false` | Shows the global search widget. |
+| `showUserPanel` | `boolean` | `false` | Shows the user panel widget. |
+| `showSettings` | `boolean` | `false` | Shows the settings widget. |
+| `showNotifications` | `boolean` | `true` | Shows the notifications widget. |
+| `notificationsTitle` | `string` | `'Notifications'` | Notification link title text or translation key. |
+| `showHelp` | `boolean` | `true` | Shows the help action. |
+| `helpTitle` | `string` | `'Help'` | Help link title text or translation key. |
+| `helpUrl` | `string \| null` | `null` | Help navigation target. |
+| `helpIcon` | `IconDefinition` | `faQuestionCircle` | Help icon. |
+| `helpAnchorClass` | `string` | `'menu-icon-btn top-menu-widget__help-link'` | CSS classes for the help anchor. |
+| `helpUrlTarget` | `'_self' \| '_blank' \| string` | `'_blank'` | Anchor target for the help action. |
+
+### Outputs
+
+| Name | Type | Description |
+|---|---|---|
+| `logoClick` | `EventEmitter<void>` | Fired when the brand link is clicked. |
+| `helpClick` | `EventEmitter<void>` | Fired when the help action is clicked. |
+| `menuItemClick` | `EventEmitter<TopMenuWidgetItem>` | Fired when a leaf menu item is activated. |
+| `searchSubmit` | `EventEmitter<string>` | Fired when free-text search is submitted. |
+| `searchItemNavigate` | `EventEmitter<TopMenuWidgetSearchItem>` | Fired when an autocomplete result is chosen. |
+| `propertyChange` | `EventEmitter<TopMenuWidgetPropertyOption>` | Fired when the active property changes. |
+| `signOutClick` | `EventEmitter<void>` | Fired when sign out is requested. |
+| `alternateNamesChange` | `EventEmitter<void>` | Fired when alternate names are toggled. |
+| `nameModeChange` | `EventEmitter<number>` | Fired when a name mode item is selected. |
+| `blockHrClick` | `EventEmitter<void>` | Fired when HR block is requested. |
+| `releaseHrClick` | `EventEmitter<void>` | Fired when HR release is requested. |
+| `blockTkClick` | `EventEmitter<void>` | Fired when Timekeeping block is requested. |
+| `releaseTkClick` | `EventEmitter<void>` | Fired when Timekeeping release is requested. |
+| `changePasswordClick` | `EventEmitter<void>` | Fired when Change Password is requested from settings. |
+| `openAboutClick` | `EventEmitter<void>` | Fired when About is requested from settings. |
+| `aboutLicenseClick` | `EventEmitter<void>` | Fired when the About dialog license action is clicked. |
+| `aboutReleaseNotesClick` | `EventEmitter<void>` | Fired when the About dialog release-notes action is clicked. |
+| `aboutSupportClick` | `EventEmitter<void>` | Fired when the About dialog support action is clicked. |
+| `submitPasswordChange` | `EventEmitter<TopMenuWidgetChangePasswordPayload>` | Fired when the built-in Change Password dialog is submitted. |
+
+## Internal Composition Widgets
+
+These widgets are used by the top-menu component and are documented here so the full contract is visible.
+
+### Global Search Widget
+
+Selector: `bayan-core-global-search-widget`
+
+Inputs:
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | `''` | Base URL used to resolve selected item URLs. |
+| `placeholder` | `string` | `'TopMenu.SearchPlaceholder'` | Placeholder text or translation key. |
+| `dataSource` | `TopMenuWidgetSearchItem[]` | `[]` | Search results shown in the autocomplete. |
+
+Outputs:
+
+| Name | Type | Description |
+|---|---|---|
+| `search` | `EventEmitter<string>` | Fired when the user submits free-text search with Enter. |
+| `itemNavigate` | `EventEmitter<TopMenuWidgetSearchItem>` | Fired when the user selects a result item. |
+
+### Item Widget
+
+Selector: `bayan-core-item-widget`
+
+Inputs:
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | `''` | Base URL used to resolve item URLs. |
+| `item` | `TopMenuWidgetItem` | required | Menu item to render. |
+
+Outputs:
+
+| Name | Type | Description |
+|---|---|---|
+| `itemClick` | `EventEmitter<TopMenuWidgetItem>` | Fired when a leaf menu item is activated. |
+
+### Notifications Widget
+
+Selector: `bayan-core-notifications-widget`
+
+Inputs:
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | `''` | Base URL used to load the notifications summary and resolve its navigation URL. |
+| `title` | `string` | `'Notifications'` | Link title text or translation key. |
+| `wrapperClass` | `string` | `'notifications-icon-wrap menu-dropdown-host'` | Wrapper CSS classes. |
+| `linkClass` | `string` | `'menu-icon-btn cursor-pointer top-menu-widget__notification-btn'` | Anchor CSS classes. |
+| `iconClass` | `string` | `'fs-6'` | Bell icon CSS classes. |
+| `badgeClass` | `string` | `'top-menu-widget__notification-badge'` | Badge CSS classes. |
+
+Outputs: none.
+
+### Settings Widget
+
+Selector: `bayan-core-settings-widget`
+
+Inputs:
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `useAlternateNames` | `boolean` | `false` | Enables alternate names behavior. |
+| `displayAlternateNames` | `boolean` | `false` | Marks alternate names as active. |
+| `hrBlocked` | `boolean` | `false` | Current HR block state. |
+| `hrCanBlock` | `boolean` | `false` | Enables HR block and release actions. |
+| `tkBlocked` | `boolean` | `false` | Current Timekeeping block state. |
+| `tkCanBlock` | `boolean` | `false` | Enables Timekeeping block and release actions. |
+| `nameModeItems` | `TopMenuWidgetNameModeItem[]` | `[]` | Name mode options. |
+| `settingsEnabled` | `boolean` | `true` | Enables settings interactions. |
+
+Outputs:
+
+| Name | Type | Description |
+|---|---|---|
+| `alternateNamesChange` | `EventEmitter<void>` | Fired when alternate names are toggled. |
+| `nameModeChange` | `EventEmitter<number>` | Fired when a name mode item is selected. |
+| `blockHrClick` | `EventEmitter<void>` | Fired when HR block is requested. |
+| `releaseHrClick` | `EventEmitter<void>` | Fired when HR release is requested. |
+| `blockTkClick` | `EventEmitter<void>` | Fired when Timekeeping block is requested. |
+| `releaseTkClick` | `EventEmitter<void>` | Fired when Timekeeping release is requested. |
+| `changePasswordClick` | `EventEmitter<void>` | Fired when Change Password is requested. |
+| `openAboutClick` | `EventEmitter<void>` | Fired when About is requested. |
+
+### User Panel Widget
+
+Selector: `bayan-core-user-panel-widget`
+
+Inputs:
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | `''` | Reserved for consistency with the top-menu contract. |
+| `userPanel` | `TopMenuWidgetUserPanel \| null` | `null` | Current user and property data. |
+| `isSsoLogin` | `boolean` | `false` | Fallback SSO flag when `userPanel.isSsoLogin` is not present. |
+
+Outputs:
+
+| Name | Type | Description |
+|---|---|---|
+| `propertyChange` | `EventEmitter<TopMenuWidgetPropertyOption>` | Fired when the active property changes. |
+| `signOutClick` | `EventEmitter<void>` | Fired when sign out is requested. |
+
+### Change Password Widget
+
+Selector: `bayan-core-change-password-widget`
+
+Inputs:
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | `''` | Reserved for dialog-level extensibility. |
+| `visible` | `boolean` | `false` | Controls popup visibility. |
+| `config` | `TopMenuWidgetChangePasswordDialogConfig` | required | Dialog labels and title. |
+| `isSubmitting` | `boolean` | `false` | Disables editing while submission is in progress. |
+
+Outputs:
+
+| Name | Type | Description |
+|---|---|---|
+| `visibleChange` | `EventEmitter<boolean>` | Fired when the dialog requests a visibility change. |
+| `submitPasswordChange` | `EventEmitter<TopMenuWidgetChangePasswordPayload>` | Fired with the form payload when save succeeds validation. |
+
+### About Dialog Widget
+
+Selector: `bayan-core-about-dialog-widget`
+
+Inputs:
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | `''` | Reserved for dialog-level extensibility. |
+| `visible` | `boolean` | `false` | Controls dialog visibility. |
+| `config` | `TopMenuWidgetAboutDialogConfig` | required | Dialog content and action labels. |
+
+Outputs:
+
+| Name | Type | Description |
+|---|---|---|
+| `visibleChange` | `EventEmitter<boolean>` | Fired when the dialog requests to close. |
+| `licenseClick` | `EventEmitter<void>` | Fired when the license action is clicked. |
+| `releaseNotesClick` | `EventEmitter<void>` | Fired when the release-notes action is clicked. |
+| `supportClick` | `EventEmitter<void>` | Fired when the support action is clicked. |
+
+## Build
+
+```bash
+npm run build -- --project BayanCoreComponents --configuration development
+```