ICE Notification Component

A powerful StencilJS web component for displaying, filtering, and managing notifications in real-time.

ice-notification-component (v0.1.6) is a standalone web component built with StencilJS that provides a flexible notification system. It supports multiple display modes (icon-based or table view), advanced filtering, search capabilities, WebSocket real-time updates, and seamless integration with any framework or vanilla JavaScript applications.

Features

• Dual Display Modes: Compact icon view with badge count or detailed table view
• Real-time Notifications: Fetch and display notifications from a REST API
• Advanced Filtering: Filter by status, category, and application
• Search Functionality: Built-in search across notification data
• Pagination: Support for paginated notification lists with configurable record limits
• Notification Status Tracking: Mark notifications as read/unread
• Framework-Agnostic: Works seamlessly with React, Vue, Angular, or vanilla JavaScript
• Styled Components: Pre-built styling with customizable CSS variables
• Error Handling: Comprehensive error event emission and handling

Installation

Via NPM

npm install ice-notification-component

From Source

git clone https://github.com/ds2-eu/DLM-Catalog.git
cd DLM-Catalog/ice-notification-service/notification-component
npm install

Getting Started

Development

To start the development server with hot-reload:

npm start

The component will be available at http://localhost:3333 by default.

Production Build

To build the component for production:

npm run build

Running Tests

npm test          # Run tests once
npm run test:watch # Run tests in watch mode

Component Properties

The <notification-component> element accepts the following properties:

| Property | Type | Default | Description | |----------|------|---------|-------------| | owner | string | "" | The owner/user identifier for fetching notifications (required) | | applicationId | string | "" | Application ID to filter notifications by specific application | | displayType | 'icon' \| 'table' | 'icon' | Display mode: compact icon with badge count or detailed table view | | maxRecords | number | 10 | Maximum number of notifications to display per page (pagination support) | | listUrl | string | "/idm/notifications" | API endpoint path for fetching the notification list | | notificationUrl | string | "https://notifications.ds2.icelab.cloud/notifications-api" | Base URL for the notifications REST API server | | socketConnect | boolean | false | Enable WebSocket real-time notification updates | | socketUrl | string | "https://repository.ds2.icelab.cloud/socket" | WebSocket server URL for real-time notifications (when socketConnect is true) |

Events

The component emits the following events:

| Event | Description | Payload | |-------|-------------|---------| | onError | Emitted when an error occurs during notification operations | { title: string; message: string } |

Usage Examples

Basic Setup (HTML/Vanilla JavaScript)

<script type="module">
  import 'ice-notification-component/dist/ice-notification-component/ice-notification-component.esm.js';
</script>

<!-- Icon display mode with badge count -->
<notification-component 
  owner="user123"
  application-id="app-1"
  display-type="icon"
  max-records="15">
</notification-component>

<!-- Table display mode -->
<notification-component 
  owner="user123"
  display-type="table"
  max-records="20">
</notification-component>

<script>
const component = document.querySelector('notification-component');

// Listen for errors
component.addEventListener('onError', (event) => {
  console.error('Notification Error:', event.detail.title, event.detail.message);
});
</script>

React Integration

import React from 'react';
import 'ice-notification-component/notification-component';

function NotificationPanel() {
  const handleError = (event: CustomEvent) => {
    console.error('Error:', event.detail.title, event.detail.message);
  };

  return (
    <notification-component
      owner="user123"
      applicationId="app-1"
      displayType="table"
      maxRecords={20}
      socketConnect={true}
      socketUrl="wss://your-socket-server.com/socket"
      onError={handleError}
    />
  );
}

export default NotificationPanel;

Vue Integration

<template>
  <div class="notification-container">
    <notification-component
      :owner="currentUserId"
      :application-id="appId"
      :display-type="displayMode"
      :max-records="10"
      :socket-connect="enableRealTime"
      :socket-url="socketServerUrl"
      @onError="handleError"
    />
  </div>
</template>

<script>
import 'ice-notification-component/notification-component';

export default {
  name: 'NotificationWidget',
  data() {
    return {
      currentUserId: 'user123',
      appId: 'app-1',
      displayMode: 'icon', // or 'table'
      enableRealTime: true,
      socketServerUrl: 'wss://your-socket-server.com/socket'
    };
  },
  methods: {
    handleError(event) {
      console.error('Notification Error:', event.detail.title, event.detail.message);
      // Show error notification to user
    }
  }
};
</script>

<style scoped>
.notification-container {
  padding: 1rem;
}
</style>

Angular Integration

import { Component, OnInit } from '@angular/core';
import 'ice-notification-component/notification-component';

@Component({
  selector: 'app-notifications',
  template: `
    <notification-component
      [attr.owner]="userId"
      [attr.application-id]="appId"
      display-type="icon"
      [attr.max-records]="20"
      (onError)="onNotificationError($event)"
    ></notification-component>
  `
})
export class NotificationsComponent implements OnInit {
  userId: string = 'user123';
  appId: string = 'app-1';

  ngOnInit() {
    // Additional initialization if needed
  }

  onNotificationError(event: CustomEvent) {
    console.error('Notification Error:', event.detail);
  }
}

WebSocket Real-Time Updates

To enable real-time notifications via WebSocket:

<notification-component
  owner="user123"
  socketConnect={true}
  socketUrl="wss://notifications.ds2.icelab.cloud/socket"
>
</notification-component>

WebSocket Setup Requirements:

• Set socketConnect to true
• Provide a valid WebSocket URL via socketUrl
• Ensure the WebSocket server supports the same user/owner identification
• The server should emit notification events to connected clients

API Configuration

REST API Endpoints

The component communicates with the following API endpoints:

1. Count New Notifications

   • Method: POST
   • Endpoint: {notificationUrl}/count/status
   • Payload: { "ownerId": string, "status": "new", "application"?: string }
   • Response: number (count of new notifications)

2. Count Total Notifications

   • Method: POST
   • Endpoint: {notificationUrl}/count/custom
   • Payload: { "ownerId": string, "properties": object }
   • Response: number (total count)

3. List Notifications

   • Method: POST
   • Endpoint: {notificationUrl}/list
   • Payload: Complex filter object
   • Response: Array of notifications

Notification Object Format

{
  "id": "notif-123",
  "title": "Notification Title",
  "message": "Detailed notification message",
  "createdAt": "2024-01-15T10:30:00Z",
  "status": "new",
  "category": "system",
  "application": "app-name",
  "actionLink": "https://example.com/action",
  "metadata": {}
}

Filter Options

The component supports filtering by:

• Status: "new", "read"
• Category: Various category types from Constants
• Application: Application name or ID
• Text: Full-text search across title and message

Styling & Theming

The component uses CSS custom properties (variables) for theming. Override these in your CSS:

notification-component {
  /* Primary Colors */
  --primary-color: #108e8a;
  --primary-bg-color: #E0FEFA;
  --secondary-color: #22d4c5;

  /* Status Colors */
  --success-color: #4CAF50;
  --error-color: #ef9a9a;
  --error-bg-color: #e74c3c;
  --warning-color: #fd9e2a;

  /* Text Colors */
  --text-dark: #4c4d4d;
  --text-light: #ffffff;

  /* UI Elements */
  --action-button: #22d4c5;
  --action-button-hover: #3aa876;
  --secondary-button: #949393;
  --border-color: #e0e0e0;
  --background: #f5f5f5;
}

Sub-Components

loading-component

The <loading-component> is an internal sub-component used to display loading indicators when fetching notifications.

Properties:

| Property | Type | Default | Description | |----------|------|---------|-------------| | show | boolean | false | Controls visibility of the loading spinner | | size | string | "small" | Size of the loader: "small", "medium", or "big" |

Usage Example:

// Correct - Pass boolean true
<loading-component show={true} size="big"></loading-component>

// Correct - In Vue
<loading-component :show="isLoading" size="big"></loading-component>

// Correct - JavaScript property
const loader = document.querySelector('loading-component');
loader.show = true;      // Boolean value
loader.size = 'big';

// ❌ WRONG - Do NOT use string "true"
<loading-component show="true" size="big"></loading-component>

For detailed documentation, see loading-component documentation.

Troubleshooting

Notifications Not Loading

1. Check Owner Property: Ensure the owner property is set and not empty
2. Verify API URL: Confirm notificationUrl is correct and accessible
3. Check Network: Open browser DevTools and check Network tab for API calls
4. CORS Issues: If API is on different domain, ensure CORS is configured properly
5. Check Console: Look for error messages in browser console

WebSocket Connection Issues

1. Enable Socket: Set socketConnect={true}
2. Verify Socket URL: Ensure socketUrl is a valid WebSocket endpoint
3. Check Protocol: Use wss:// for secure connections
4. Firewall: Ensure WebSocket port is not blocked by firewall
5. Monitor DevTools: Use Network tab to inspect WebSocket connection

Performance Issues

• Reduce maxRecords to load fewer notifications
• Use applicationId to filter notifications for specific app
• Enable pagination to distribute large datasets
• Consider implementing lazy-loading for table view

FAQ

Q: How do I filter notifications by application? A: Set the applicationId property to filter notifications for a specific application.

Q: Can I use this component without WebSocket? A: Yes, set socketConnect={false} (default). The component will use REST API polling instead.

Q: How often does the component fetch new notifications? A: The component fetches new notifications on component load and when the owner changes. WebSocket (when enabled) provides real-time updates.

Q: Can I customize the notification display format? A: The component provides two display modes (icon and table). For custom formatting, you may need to create a custom component that wraps this one.

Q: Is the component production-ready? A: Yes, version 0.1.6 is production-ready. Always test in your specific environment before deploying.

Development

For development information, see Development Guide.

Development Setup

# Clone the repository
git clone https://github.com/ds2-eu/DLM-Catalog.git
cd DLM-Catalog/ice-notification-service/notification-component

# Install dependencies
npm install

# Start development server
npm start

# Run tests
npm test

# Watch mode for development
npm run test:watch

# Build for production
npm run build

Support & Contributing

For issues, bug reports, feature requests, or contributions, please visit:

• GitHub Repository: https://github.com/ds2-eu/DLM-Catalog
• Project Structure: ice-notification-service/notification-component

License

MIT - See LICENSE file for details

Changelog

Version 0.1.6

• Added WebSocket support for real-time notifications
• Added socketConnect and socketUrl properties
• Enhanced filtering capabilities
• Improved error handling
• Updated dependencies

Version 0.1.5

• Initial stable release
• Core notification display functionality
• Support for icon and table display modes
• Advanced filtering and search capabilities

Related Components

• notification-component: Main notification display component
• loading-component: Loading indicator sub-component
• ice-email-service: Related email notification service
• ice-repository-service: Related repository management service