@genesislcap/foundation-header 14.408.0 → 14.409.0

package/README.md

@@ -1,652 +1,25 @@
-# Foundation Header
+# @genesislcap/foundation-header
 
-[API](./docs/api/index.md)
+Documentation for this package is published on the Genesis docs site:
 
-## Introduction
+**Docs: [Header](https://docs.genesis.global/docs/develop/client-capabilities/header/)**
 
-The Header micro front-end is a semi-batteries-included component. It consists of a navigation bar and flyout menu, with routing and account-logout capabilities.
+## Installation
 
-### Customise
-
-You can customise:
-
-- the icon shown on the navigation bar and flyout menu (this shows the Genesis logo by default)
-- navigation links at the left-hand side of the navigation bar
-- the control buttons on the right-hand side of the navigation bar; these can be shown or hidden, and their behaviour controlled via event listeners
-- the contents of the flyout menu
-
-### Examples
-
-Here is an example of the navigation bar with three navigation items, and all three control buttons shown.
-![Header with the standard genesis logo](./docs/img/foundation-header-standard.png)
-
-This next example is the same as the previous example, except the Genesis logo is replaced with a custom icon.
-![Header with a customised logo](./docs/img/foundation-header-replaced-img.png)
-
-In this next example, we have put a set of example options set in the flyout menu.
-![The sidebar included with the header opened with some example content](./docs/img/foundation-header-sidebar.png)
-
-## Header set-up
-
-A lot of the Genesis seed apps come with the Header set up by default. To verify, you can do a text search in the client code for the `<rapid-header>` tag.
-
-### Icon
-
-By default, the navigation bar and flyout menu show the Genesis logo. You can override this by setting the `logoSrc` attribute. For example:
-
-```html
-<rapid-header logoSrc="https://icotar.com/avatar/genesis"></rapid-header>
-```
-
-The `logoSrc` defines the image that you want to display. Adding this attribute updates the logo on both the flyout and navigation bar. If you want to keep the Genesis logo, just omit this attribute.
-
-### Navigation items
-
-You can add navigation items to the left-hand side of the navigation bar. For each element, you can set `slot="routes"` attribute, so that navigation is controlled via a `@click` event. The following is a really basic example for adding a 'Home' button:
-
-```javascript
-html`
-<rapid-header>
-  <rapid-button
-    slot="routes"
-    value="1"
-    @click=${(x, c) => c.parent.navigation.navigateTo("home")}
-  >Home</rapid-button>
-</rapid-header>`;
-```
-
-The `navigation` object referenced via the `parent` object is why the `navigation` object is added as an attribute to the `router` in the [setup step](#header-set-up). From it, the `navigateTo` method can be called, which allows the user to navigate around the finished application from the navigation buttons.
-
-Moving on from this basic example, a dynamic set of routes can be configured, using the `repeat` directive from `@genesislcap/web-core`.
-
-1. Add the routes configuration into an array in the router configuration class.
-
-```javascript
-export class MainRouterConfig extends RouterConfiguration<LoginSettings> {
-
-  // New configuration added to existing MainRouterConfig class
-  public allRoutes = [
-    { index: 1, path: 'protected', title: 'Home', icon: 'home', variant: 'solid' },
-    { index: 2, path: 'admin', title: 'Admin', icon: 'cog', variant: 'solid' },
-    { index: 3, path: 'reporting', title: 'Reporting', variant: 'solid' },
-  ];
-
-  ...
-}
-```
-
-2. When setting the navigation items, use the `repeat` directive to iterate over the defined routes and create a navigation item for each one.
-
-The following example creates a button with an associated logo for each of the three defined routes:
-
-html`
-<rapid-header>
-  <div slot="routes">
-    ${repeat(
-      (x) => x.config.allRoutes,
-      html`
-        <rapid-button
-          appearance="neutral-grey"
-          value="${(x) => x.index}"
-          @click=${(x, c) => c.parent.navigation.navigateTo(x.path)}
-        >
-          <rapid-icon variant="${(x) => x.variant}" name="${(x) => x.icon}"></rapid-icon>
-          ${(x) => x.title}
-        </rapid-button>
-      `
-    )}
-  </div>
-</rapid-header>`;
-```
-
-### Control buttons
-
-There are three control buttons that can be shown or hidden on the right-hand side of the navigation bar (these are hidden by default). Each one of them is a boolean attribute that can be added where the `<rapid-header>` tag is defined.
-
-| Logo          | Toggle Attribute             | Dispatched Event          |
-|---------------|------------------------------|---------------------------|
-| Moon          | show-luminance-toggle-button | luminance-icon-clicked    |
-| Misc          | show-misc-toggle-button      | misc-icon-clicked         |
-| Notifications | show-notification-button     | notification-icon-clicked |
-
-Implementing the functionality of the buttons is up to the client. For example:
-
-- Define the functionality of the event callback in the class of a class which is a parent to the router.
-
-```javascript
-export class MainApplication extends GenesisElement {
-
-  onMiscButtonPressed() {
-    // ... do something
-  }
-  //...
-}
-```
-
-- Set the event listener in the parent html to call the defined functionality.
-
-```javascript
-const MainTemplate: ViewTemplate<MainApplication> = html`
-  <foundation-router
-    :navigation=${(x) => x.navigation}
-    @misc-icon-clicked=${(x) => x.onMiscButtonPressed()}
-  >
-  </foundation-router>
-`;
-```
-
-### Language Selector
-
-The rapid-header component can display a language selector if the ```show-language-selector``` attribute is set. This allows users to switch between different languages within the application.
-
-```html
-<rapid-header show-language-selector></rapid-header>
-```
-
-By default, the component uses the languageOptions object, which contains an availableLanguage array and a selectedLanguage property. These default options provide a list of available languages and the currently selected language.
-
-You can also pass custom language options by providing an attribute with this data. Here is an example of how to set up the rapid-header component with the show-language-selector attribute and custom language options:
-
-<rapid-header
-  show-language-selector
-  :languageOptions=${() => {
-    return { availableLanguages: ['en', 'es'], selectedLanguage: 'es' };
-  }}
-></rapid-header>
-
-### Menu contents
-
-To set the content of the flyout menu, add the content in the html within an element that has the `slot="menu-contents"` attribute.
-```html
-<rapid-header>
-  <div slot="menu-contents">
-    <!-- Example markup -->
-    <p>GROUP SLOT</p>
-    <rapid-tree-view>
-      <rapid-tree-item>
-        <rapid-icon name="location-arrow"></rapid-icon>
-        Slot Tree Item
-      </rapid-tree-item>
-      <rapid-tree-item>
-        <rapid-icon name="location-arrow"></rapid-icon>
-        Slot Tree Item
-      </rapid-tree-item>
-    </rapid-tree-view>
-    <p>GROUP SLOT 2</p>
-    <rapid-tree-view>
-      <rapid-tree-item>
-        <rapid-icon name="location-arrow"></rapid-icon>
-        Slot Tree Item 2
-      </rapid-tree-item>
-      <rapid-tree-item>
-        <rapid-icon name="location-arrow"></rapid-icon>
-        Slot Tree Item 2
-      </rapid-tree-item>
-    </rapid-tree-view>
-  </div>
-</rapid-header>
-```
-
-:::tip
-The `allRoutes` array, which you need to change to set the navigation buttons on the Header, is found in **client/web/src/routes/config.ts**.
-:::
-
-## Manual Header set-up
-
-If the rapid-header component has not been implemented in your project, follow the steps below to add this micro front-end to your application.
-
-1. Add `@genesislcap/foundation-header` as a dependency in your **package.json** file. Whenever you change the dependencies of your project, ensure you run the bootstrap command again. There is more information in the [package.json basics](https://learn.genesis.global/secure/web/basics/package-json-basics/) page.
+Add the package to your `package.json` dependencies. After changing dependencies, run `npm run bootstrap` (or your project's equivalent). See [package.json basics](https://learn.genesis.global/secure/web/basics/package-json-basics/) for more information.
 
 ```json
 {
-  ...
   "dependencies": {
     "@genesislcap/foundation-header": "latest"
-  },
-  ...
-}
-```
-
-:::note
-This page assumes you're already using the Login and Routing systems that are part of `foundation-ui` for the logout and routing functionality.
-
-It is possible for you to set up routing manually, but that won't be covered in this tutorial.
-:::
-
-2. In the top-level class of your application, import the Navigation class and inject it as a dependency.
-
-```javascript {1,6}
-import { GenesisElement, customElement, inject } from '@genesislcap/web-core';
-import { Navigation } from '@genesislcap/foundation-header';
-
-@customElement({ name, template, styles })
-export class MainApplication extends GenesisElement {
-  @inject(MainRouterConfig) config!: MainRouterConfig;
-  @inject(Navigation) navigation!: Navigation;
-
-  //...
-
-}
-```
-
-:::tip
-If you haven't used the `inject` annotation in your application yet, you'll need to get it from the `@genesislcap/web-core` package.
-:::
-
-3. Set a reference to the `navigation` object on the foundation-router when you instantiate it; this enables you to set up navigation functionality from the navigation bar in the [navigation items step](#navigation-items).
-
-```javascript
-const MainTemplate: ViewTemplate<MainApplication> = html`
-  <foundation-router :navigation=${(x) => x.navigation}></foundation-router>
-`;
-```
-
-4. Add the `rapid-header` tag as part of the html that you set as the markup for the `defaultLayout` in your router configuration.
-
-```javascript {3}
-export const defaultLayout = new GenesisElementLayout(html`
-<div class="container">
-  <!-- show-luminance-toggle-button boolean attribute added to show that button on the navigation bar -->
-  <rapid-header show-luminance-toggle-button></rapid-header>
-  <!-- Other markup -->
-</div>`);
-
-export class MainRouterConfig extends RouterConfiguration<LoginSettings> {
-  //...
-
-  public configure() {
-    this.title = 'Example app';
-    this.defaultLayout = defaultLayout;
-    //...
   }
 }
 ```
 
-## Inactivity Monitoring
-
-The `foundation-header` component supports configurable inactivity monitoring through attributes.
-
-### Configuration Attributes
-
-#### `inactivity-timeout-minutes`
-- **Type**: Number
-- **Default**: 30
-- **Description**: Sets the inactivity timeout in minutes before automatic logout
-
-#### `inactivity-warning-minutes`
-- **Type**: Number
-- **Default**: 5
-- **Description**: Sets the inactivity warning time in minutes before timeout
-
-#### `enable-inactivity-monitoring`
-- **Type**: Boolean
-- **Default**: `true`
-- **Description**: Controls whether inactivity monitoring is enabled
-
-### Usage Examples
-
-#### Basic Configuration
-```html
-<foundation-header
-  inactivity-timeout-minutes="20"
-  inactivity-warning-minutes="3"
-></foundation-header>
-```
-
-#### Short Session (15 minutes timeout, 2 minutes warning)
-```html
-<foundation-header
-  inactivity-timeout-minutes="15"
-  inactivity-warning-minutes="2"
-></foundation-header>
-```
-
-#### Long Session (60 minutes timeout, 10 minutes warning)
-```html
-<foundation-header
-  inactivity-timeout-minutes="60"
-  inactivity-warning-minutes="10"
-></foundation-header>
-```
-
-#### Default Configuration (30 minutes timeout, 5 minutes warning)
-```html
-<foundation-header></foundation-header>
-```
-
-#### Enable Inactivity Monitoring (Default)
-```html
-<foundation-header></foundation-header>
-```
-
-#### Enable Inactivity Monitoring (Explicit)
-```html
-<foundation-header enable-inactivity-monitoring></foundation-header>
-```
-
-#### Disable Inactivity Monitoring
-```html
-<foundation-header enable-inactivity-monitoring="false"></foundation-header>
-```
-
-#### Complete Configuration with Enable/Disable
-```html
-<!-- Enabled with custom timeout -->
-<foundation-header
-  enable-inactivity-monitoring
-  inactivity-timeout-minutes="20"
-  inactivity-warning-minutes="3"
-></foundation-header>
-
-<!-- Disabled (other attributes ignored) -->
-<foundation-header
-  enable-inactivity-monitoring="false"
-  inactivity-timeout-minutes="30"
-  inactivity-warning-minutes="5"
-></foundation-header>
-```
-
-### Behavior
-
-#### When Enabled (Default)
-- InactivityManager is created and started
-- User activity is monitored
-- Warning dialog appears before timeout
-- Automatic logout occurs on timeout
-- Debug log: "Inactivity manager initialized and started..."
-
-#### When Disabled
-- No InactivityManager is created
-- No activity monitoring occurs
-- No warning dialogs or timeouts
-- Debug log: "Inactivity monitoring is disabled"
-
-### Event Handling
-
-The component automatically emits events based on the configured timeout and warning settings:
-
-```html
-<foundation-header
-  id="app-header"
-  inactivity-timeout-minutes="20"
-  inactivity-warning-minutes="3"
-></foundation-header>
-
-<script>
-  const header = document.getElementById('app-header');
-  
-  // Warning will be triggered 3 minutes before timeout (at 17 minutes of inactivity)
-  header.addEventListener('inactivity-warning', (event) => {
-    const remainingSeconds = event.detail.remainingSeconds;
-    console.log(`Warning: Session will expire in ${remainingSeconds} seconds`);
-  });
-  
-  // Timeout will be triggered after 20 minutes of inactivity
-  header.addEventListener('inactivity-timeout', () => {
-    console.log('Session expired due to inactivity');
-  });
-  
-  // Reset is triggered whenever user activity is detected
-  header.addEventListener('inactivity-reset', () => {
-    console.log('User activity detected - timer reset');
-  });
-</script>
-```
-
-### Configuration Guidelines
-
-#### Recommended Settings
-
-| Use Case | Timeout | Warning | Description |
-|----------|---------|---------|-------------|
-| **High Security** | 15-20 min | 2-3 min | Banking, healthcare, sensitive data |
-| **Standard** | 30 min | 5 min | General business applications |
-| **Long Sessions** | 60 min | 10 min | Creative work, analysis tools |
-| **Development** | 120 min | 15 min | Development environments |
-
-#### Best Practices
-
-1. **Warning Time**: Should be 10-20% of the timeout time
-2. **Minimum Values**: Don't set timeout below 10 minutes or warning below 1 minute
-3. **User Experience**: Consider the user's workflow when setting these values
-4. **Security Requirements**: Align with your organization's security policies
-
-### Use Cases
-
-#### Development/Testing
-```html
-<!-- Disable during development -->
-<foundation-header enable-inactivity-monitoring="false"></foundation-header>
-```
-
-#### Production with Monitoring
-```html
-<!-- Enable with appropriate timeout for production -->
-<foundation-header
-  enable-inactivity-monitoring
-  inactivity-timeout-minutes="30"
-  inactivity-warning-minutes="5"
-></foundation-header>
-```
-
-#### Conditional Monitoring
-```javascript
-const header = document.querySelector('foundation-header');
-
-// Enable monitoring for admin users
-if (userRole === 'admin') {
-  header.setAttribute('enable-inactivity-monitoring', 'true');
-} else {
-  header.setAttribute('enable-inactivity-monitoring', 'false');
-}
-```
-
-### Dynamic Configuration
-
-You can also set these attributes programmatically:
-
-```javascript
-const header = document.querySelector('foundation-header');
-
-// Set timeout to 45 minutes
-header.setAttribute('inactivity-timeout-minutes', '45');
-
-// Set warning to 5 minutes
-header.setAttribute('inactivity-warning-minutes', '5');
-
-// Disable monitoring
-header.setAttribute('enable-inactivity-monitoring', 'false');
-
-// Enable monitoring
-header.setAttribute('enable-inactivity-monitoring', 'true');
-
-// Check current state
-const isEnabled = header.hasAttribute('enable-inactivity-monitoring') && 
-                  header.getAttribute('enable-inactivity-monitoring') !== 'false';
-```
-
-### Integration with Authentication
-
-The inactivity monitoring integrates seamlessly with the existing authentication system:
-
-```html
-<foundation-header
-  inactivity-timeout-minutes="30"
-  inactivity-warning-minutes="5"
-></foundation-header>
-
-<script>
-  const header = document.querySelector('foundation-header');
-  
-  // Handle logout when timeout occurs
-  header.addEventListener('logout-clicked', () => {
-    // Clear session data
-    sessionStorage.clear();
-    localStorage.removeItem('auth-token');
-    
-    // Redirect to login page
-    window.location.href = '/login';
-  });
-</script>
-```
-
-### Complete Example
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Foundation Header with Inactivity Monitoring</title>
-</head>
-<body>
-  <foundation-header
-    id="app-header"
-    enable-inactivity-monitoring
-    inactivity-timeout-minutes="25"
-    inactivity-warning-minutes="4"
-    show-connection-indicator
-    show-language-selector
-  ></foundation-header>
-
-  <div id="inactivity-notification" style="display: none; position: fixed; top: 20px; right: 20px; background: #ff9800; color: white; padding: 16px; border-radius: 4px; z-index: 1000;">
-    <div id="notification-text"></div>
-    <button onclick="extendSession()" style="margin-top: 8px; padding: 4px 8px;">Continue Session</button>
-  </div>
-
-  <!-- Control buttons -->
-  <div style="margin: 20px;">
-    <button onclick="enableMonitoring()">Enable Monitoring</button>
-    <button onclick="disableMonitoring()">Disable Monitoring</button>
-    <button onclick="checkStatus()">Check Status</button>
-  </div>
-
-  <script type="module">
-    import { foundationHeader } from '@genesislcap/foundation-header';
-    
-    const header = document.getElementById('app-header');
-    const notification = document.getElementById('inactivity-notification');
-    const notificationText = document.getElementById('notification-text');
-    
-    header.addEventListener('inactivity-warning', (event) => {
-      const remainingSeconds = event.detail.remainingSeconds;
-      notificationText.textContent = `Your session will expire in ${remainingSeconds} seconds.`;
-      notification.style.display = 'block';
-    });
-    
-    header.addEventListener('inactivity-reset', () => {
-      notification.style.display = 'none';
-    });
-    
-    header.addEventListener('logout-clicked', () => {
-      alert('Session expired. You will be redirected to the login page.');
-      window.location.href = '/login';
-    });
-    
-    function extendSession() {
-      // Trigger user activity to reset the timer
-      document.body.click();
-    }
-    
-    function enableMonitoring() {
-      header.setAttribute('enable-inactivity-monitoring', 'true');
-      console.log('Inactivity monitoring enabled');
-    }
-    
-    function disableMonitoring() {
-      header.setAttribute('enable-inactivity-monitoring', 'false');
-      console.log('Inactivity monitoring disabled');
-    }
-    
-    function checkStatus() {
-      const isEnabled = header.hasAttribute('enable-inactivity-monitoring') && 
-                       header.getAttribute('enable-inactivity-monitoring') !== 'false';
-      console.log('Inactivity monitoring is:', isEnabled ? 'enabled' : 'disabled');
-    }
-    
-    // Check initial status
-    checkStatus();
-  </script>
-</body>
-</html>
-```
-
-### Notes
-
-- When disabled, the InactivityManager is not created, saving memory and CPU
-- The enable/disable state is checked only during initialization
-- Changing the attribute after the component is created requires reconnecting the component to take effect
-- All other inactivity-related attributes are ignored when monitoring is disabled
-
-## DOM API
-
-Property and attribute binding examples for foundation-header micro-frontend.
-
-### Attributes
-
-| Attribute | Type | Use | Example |
-|---|---|---|---|
-| logo-src | `any` | Optional attribute which sets the source of the image in the navigation bar and flyout menu. The Genesis logo will be shown if this attribute is not provided. | `<foundation-header logo-src="path/to/logo.png">` |
-| logo-alt-text | `string` | Optional attribute which controls the alt text of the logo. If this attribute is not set then the alt text is set to 'Corporate Logo'. | `<foundation-header logo-alt-text="My Logo">` |
-| show-luminance-toggle-button | `boolean` | Boolean attribute which controls whether the navigation bar will display the luminance toggle icon. | `<foundation-header show-luminance-toggle-button>` |
-| show-misc-toggle-button | `boolean` | Boolean attribute which controls whether the navigation bar will display the miscellaneous behaviour icon. | `<foundation-header show-misc-toggle-button>` |
-| show-notification-button | `boolean` | Boolean attribute which controls whether the navigation bar will display the show notification icon. | `<foundation-header show-notification-button>` |
-| show-connection-indicator | `boolean` | Boolean attribute which controls whether the navigation bar will display the connection indicator. | `<foundation-header show-connection-indicator>` |
-| show-language-selector | `boolean` | Boolean attribute which controls whether the navigation bar will display the language selector. | `<foundation-header show-language-selector>` |
-| hide-side-bar | `boolean` | Boolean attribute which controls whether the navigation bar will display the side bar. | `<foundation-header hide-side-bar>` |
-| inactivity-timeout-minutes | `number` | Number attribute which sets the inactivity timeout in minutes (default: 30). | `<foundation-header inactivity-timeout-minutes="20">` |
-| inactivity-warning-minutes | `number` | Number attribute which sets the inactivity warning time in minutes (default: 5). | `<foundation-header inactivity-warning-minutes="3">` |
-| enable-inactivity-monitoring | `boolean` | Boolean attribute which controls whether inactivity monitoring is enabled (default: true). | `<foundation-header enable-inactivity-monitoring="false">` |
-
-### Properties
-
-| Property | Type | Use | Example |
-|---|---|---|---|
-| userName | `string` | Username of the logged in user. | `<foundation-header ?userName="${(x) => x.userName}">` |
-| languageOptions | `LanguageOptions` | Object which defines the language options to be displayed in the language selector. | `<foundation-header :languageOptions="${(x) => x.languageOptions}">` |
-| routeButtons | `Array` | Array of objects which define the route buttons to be displayed in the navigation bar. | `<foundation-header :routeButtons="${(x) => x.routeButtons}">` |
-| routeNavItems | `FoundationRouteNavItem[]` | Array of FoundationRouteNavItems which define the route buttons to be displayed in the navigation bar. | `<foundation-header :routeNavItems="${(x) => x.routeNavItems}">` |
-
-### Slots
-
-| Slot Name       | Description                                                                 |
-|-----------------|-----------------------------------------------------------------------------|
-| `menu-contents` | Slot for adding custom content to the flyout menu (side navigation).        |
-| `routes`        | Slot for adding custom route buttons to the navigation bar.                 |
-| `routes-end`    | Slot for adding custom route buttons to the end of the navigation bar.      |
-
-### Parts
-
-| Part Name       | Description                                                                 |
-|-----------------|-----------------------------------------------------------------------------|
-| `dynamic-template` | The element representing the dynamic template content.                    |
-
-### Methods
-
-| Method | Description |
-|---|---|
-| `logout` | Logs the user out of their session. |
-| `navigateTo` | Changes the route of the current page. |
-
-### Fired Events
-
-| Event | Type | Description | Example |
-|---|---|---|---|
-| luminance-icon-clicked | `void` | Dispatched when the user clicks on the luminance toggle icon in the navigation bar. | `<foundation-header @luminance-icon-clicked="${(x) => x.handleLuminanceIconClick}">` |
-| misc-icon-clicked | `void` | Dispatched when the user clicks on the miscellaneous behaviour icon in the navigation bar. | `<foundation-header @misc-icon-clicked="${(x) => x.handleMiscIconClick}">` |
-| notification-icon-clicked | `void` | Dispatched when the user clicks on the notification icon in the navigation bar. | `<foundation-header @notification-icon-clicked="${(x) => x.handleNotificationIconClick}">` |
-| language-changed | `void` | Dispatched when the user changes the language in the language selector. | `<foundation-header @language-changed="${(x) => x.handleLanguageChange}">` |
-| inactivity-warning | `InactivityWarningEvent` | Dispatched when the inactivity warning is triggered. | `<foundation-header @inactivity-warning="${(x) => x.handleInactivityWarning}">` |
-| inactivity-timeout | `void` | Dispatched when the inactivity timeout is reached. | `<foundation-header @inactivity-timeout="${(x) => x.handleInactivityTimeout}">` |
-| inactivity-reset | `void` | Dispatched when user activity is detected and the timer is reset. | `<foundation-header @inactivity-reset="${(x) => x.handleInactivityReset}">` |
-| logout-clicked | `void` | Dispatched when logout is triggered due to inactivity timeout. | `<foundation-header @logout-clicked="${(x) => x.handleLogout}">` |
-
-## Listened Events
-
-This component doesn't listen to any events.
-
 ## License
 
 Note: this project provides front-end dependencies and uses licensed components listed in the next section; thus, licenses for those components are required during development. Contact [Genesis Global](https://genesis.global/contact-us/) for more details.
 
 ### Licensed components
+
 Genesis low-code platform