raain-ui 2.3.7 → 2.3.8

package/CHANGELOG.md

@@ -5,51 +5,67 @@ All notable changes to the raain-ui project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
 ## [2.3.x] - Current
 
 ### Added
+
 - Cartesian earth optimization for improved performance
+- DateStatusUtils for improved date handling and formatting in DateStatusElement and DynamicDateStatusElement
+- Memory bank documentation for AI assistance
 
 ## [2.2.x]
 
 ### Enhanced
+
 - Model polar visualization improvements
 
 ## [2.1.x]
 
 ### Added
+
 - Support for icons in composite layers
 
 ## [2.0.x]
 
 ### Changed
+
 - Updated raain-model integration
 
 ## [1.11.x]
 
 ### Changed
+
 - Refactored Factory components
 
 ### Added
+
 - Performance monitoring capabilities
 
 ## [1.10.x]
 
 ### Fixed
+
 - Cartesian visualization issues
 
 ### Added
+
 - Show/hide capability for UI elements
 
 ## [1.0.x - 1.9.x]
 
 ### Added
+
 - Various factories for UI components:
-  - Map integration
-  - Compare functionality
-  - Configuration options
+    - Map integration
+    - Compare functionality
+    - Configuration options
 
 ## [0.x.x]
 
 ### Added
+
 - Initial release with core components extracted from RAAIN project

package/README.md

@@ -1,35 +1,86 @@
-# raain-ui
+<div align="center">
 
-UI components and visualization layers for raain.io applications.
+# 🌧️ raain-ui
 
-## Description
+[![npm version](https://img.shields.io/npm/v/raain-ui.svg)](https://www.npmjs.com/package/raain-ui)
+[![Build Status](https://github.com/raainio/raain-ui/workflows/CI/badge.svg)](https://github.com/raainio/raain-ui/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.0-blue.svg)](https://www.typescriptlang.org/)
 
-raain-ui is a library that provides UI components and visualization layers for displaying and interacting with rainfall data. It uses Leaflet for maps, Pixi.js for rendering, and Chart.js for charting.
+**Advanced UI components and visualization layers for rainfall data**
 
-## Installation
+</div>
+
+<p align="center">
+  <b>raain-ui</b> is a library that provides specialized UI components and visualization layers for displaying and interacting with rainfall data coming from <a href="https://radartorain.com">radartorain.com</a>. Built with modern web technologies, it offers high-performance visualizations for meteorological applications.
+</p>
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Screenshots](#-screenshots)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [Documentation](#-documentation)
+- [Angular Configuration](#-angular-configuration)
+- [Changelog](#-changelog)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+## ✨ Features
+
+- **Interactive Maps**: Leaflet-based map visualizations for geospatial rainfall data
+- **High-Performance Rendering**: Pixi.js-powered rendering for smooth visualizations
+- **Data Charting**: Chart.js integration for time-series and statistical analysis
+- **3D Globe Visualization**: Earth visualization for global rainfall patterns
+- **Time Navigation**: Advanced date/time controls for temporal data exploration
+- **Responsive Design**: Components that adapt to different screen sizes
+- **Framework Agnostic**: Works with vanilla JavaScript or any framework
+
+## 📸 Screenshots
+
+Here are some screenshots showcasing the raain-ui components in action:
+
+### Map Visualization
+
+![Map Visualization](./screenshots/Screenshot%202025-05-20%20at%2016.13.31.png)
+
+### Compare Data
+
+![Compare](./screenshots/Screenshot%202025-05-20%20at%2016.13.49.png)
+
+### Date Analysis
+
+![Date Analysis](./screenshots/Screenshot%202025-05-20%20at%2016.14.07.png)
+
+## 📦 Installation
 
 ```bash
 npm install raain-ui
 ```
 
-## Usage
+## 🚀 Usage
 
-### Basic Setup
+raain-ui provides a set of components that can be easily integrated into your application. Here's a simple example of
+how to use the MapElement component:
 
 ```javascript
-import { MapElement } from 'raain-ui';
+import {MapElementFactory} from 'raain-ui';
 
 // Create a map element
-const mapElement = new MapElement({
-  container: 'map-container',
-  center: [51.505, -0.09],
-  zoom: 13
+const mapElement = MapElementFactory.create({
+    container: 'map-container',
+    center: [51.505, -0.09],
+    zoom: 13
 });
+
+// Add a rainfall layer
+mapElement.addRainfallLayer(rainfallData);
 ```
 
-### Example Application
+### 🔍 Example Application
 
-The project includes an example application that demonstrates how to use the library:
+The project includes a comprehensive example application that demonstrates how to use the library:
 
 ```bash
 # Clone the repository
@@ -45,29 +96,111 @@ cd example/
 npm start
 ```
 
-This will open the example application at http://localhost:1234
+This will open the example application at http://localhost:1234, where you can explore the various components and
+features of raain-ui.
+
+## 📚 Documentation
+
+Comprehensive API documentation is available in the [specifications](./specs) directory. This includes detailed
+information about all components, their properties, methods, and events.
+
+### 🧠 Memory Bank
+
+This project uses a Memory Bank for comprehensive documentation and context retention. The Memory Bank provides in-depth
+information about the project's architecture, design decisions, and development context.
+
+<details>
+<summary><b>Memory Bank Files</b> (click to expand)</summary>
+
+The Memory Bank is located in the `.memory-bank` directory and contains the following files:
+
+| File                   | Description                                                       |
+|------------------------|-------------------------------------------------------------------|
+| `memory-bank-rules.md` | Rules to follow and to consider in all contexts                   |
+| `projectbrief.md`      | Overview of the project, core requirements, and goals             |
+| `productContext.md`    | Why the project exists, problems it solves, and how it works      |
+| `systemPatterns.md`    | System architecture, key technical decisions, and design patterns |
+| `techContext.md`       | Technologies used, development setup, and technical constraints   |
+| `activeContext.md`     | Current work focus, recent changes, and next steps                |
+| `progress.md`          | What works, what's left to build, and known issues                |
+
+</details>
+
+### 🅰️ Angular Configuration
+
+If you're using this library in an Angular application, you'll need to configure Angular to handle the CSS files
+properly. Here are two approaches:
+
+<details>
+<summary><b>Option 1: Import CSS in angular.json</b></summary>
+
+```json
+"styles": [
+"src/styles.css",
+"node_modules/raain-ui/dist/data/globe.css"
+]
+```
+
+</details>
+
+<details>
+<summary><b>Option 2: Configure webpack for CSS imports</b></summary>
+
+First, create a custom webpack configuration:
+
+```javascript
+// custom-webpack.config.js
+module.exports = {
+    module: {
+        rules: [
+            {
+                test: /\.css$/,
+                include: [/node_modules\/raain-ui/],
+                use: ['style-loader', 'css-loader']
+            }
+        ]
+    }
+};
+```
+
+Then use `@angular-builders/custom-webpack` to apply this configuration:
+
+```json
+"architect": {
+"build": {
+"builder": "@angular-builders/custom-webpack:browser",
+"options": {
+"customWebpackConfig": {
+"path": "./custom-webpack.config.js"
+}
+}
+}
+}
+```
 
-## Development
+</details>
 
-Please read the [Development Guidelines](./GUIDELINES.md) for detailed information about:
-- Build and configuration instructions
-- Testing information
-- Code style and development guidelines
-- Project structure
-- Dependencies
+## 📝 Changelog
 
-## Documentation
+See the [Changelog](./CHANGELOG.md) for a detailed list of changes in each version. Recent highlights include:
 
-API documentation is available in the [specifications](./specs) directory.
+- **v2.3.x**: Cartesian earth optimization, DateStatusUtils, Memory bank documentation
+- **v2.2.x**: Model polar visualization improvements
+- **v2.1.x**: Support for icons in composite layers
+- **v2.0.x**: Updated raain-model integration
 
-## Changelog
+## 👥 Contributing
 
-See the [Changelog](./CHANGELOG.md) for a list of changes in each version.
+Contributions are welcome! If you'd like to contribute to raain-ui, please follow these steps:
 
-## Release Process
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-See the [Release Process](./RELEASE_PROCESS.md) for information about how releases are managed.
+Please make sure your code follows the existing style and includes appropriate tests.
 
-## License
+## 📄 License
 
-MIT
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

package/data/globe.css

@@ -0,0 +1,167 @@
+.globe {
+    --settingwidth: min(480px, 100vw);
+    --infowidth: min(480px, 50vw);
+    --xslide: min(480px, 50vw);
+    --menuheight: 100%;
+    --yslide: 0px;
+}
+
+@media screen and (max-width: 768px) and (orientation: portrait) {
+    .globe {
+        --infowidth: 100%;
+        --xslide: 0px;
+        --menuheight: 50vh;
+        --yslide: 50vh;
+    }
+}
+
+.globe * {
+    box-sizing: border-box;
+}
+
+.globe div {
+    transition: 0.33s;
+}
+
+.globe button {
+    background: transparent;
+    border: none;
+    padding: 8px;
+    cursor: pointer;
+    appearance: none;
+    -webkit-appearance: none;
+    touch-action: manipulation;
+}
+
+.globe button svg {
+    touch-action: manipulation;
+}
+
+.globe canvas.map {
+    width: 100%;
+    height: 100%;
+    display: inline-block;
+    position: absolute;
+    padding: 0;
+}
+
+.globe .sprite {
+    width: 0;
+    height: 0;
+    position: absolute;
+    visibility: hidden;
+    display: none;
+}
+
+.globe .settings {
+    position: absolute;
+    width: var(--settingwidth);
+    height: 100%;
+    transform: translate(calc(0px - 100%));
+    visibility: hidden; /* Hide from tab navigation when offscreen */
+    z-index: 2;
+}
+
+.globe .main {
+    width: 100%;
+    height: 100%;
+    position: relative;
+    overflow: hidden;
+    background-color: #404542;
+}
+
+.globe .shifted {
+    transform: translate(calc(0px - var(--xslide) / 2), calc(0px - var(--yslide) / 2));
+}
+
+.globe .infoslider {
+    position: absolute;
+    bottom: 0;
+    right: 0;
+    width: var(--infowidth);
+    height: var(--menuheight);
+    transform: translate(var(--xslide), var(--yslide));
+    visibility: hidden; /* Hide from tab navigation when offscreen */
+    z-index: 1;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    padding: 0;
+    box-shadow: 0px 0px 10px 0px black;
+    background-color: white;
+}
+
+.globe .infoslider .infoTopBar {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    gap: 20px;
+    box-shadow: 0px 3px 5px 0px rgba(0, 0, 0, 0.14);
+    font-family: 'Source Sans Pro', sans-serif;
+}
+
+.globe .infoslider .infobox {
+    word-wrap: break-word;
+    overflow-y: auto;
+    overflow-x: hidden;
+    flex: 1;
+}
+
+.globe .slid {
+    visibility: visible;
+    transform: translate(0px);
+}
+
+.globe .status {
+    position: absolute;
+    bottom: 0;
+    right: 0;
+    text-align: right;
+    font-family: "Lucida Console", monospace;
+    color: white;
+    background-color: rgba(34, 34, 34, 0.5);
+    padding: 0.2em;
+    z-index: 1;
+}
+
+.globe .icon {
+    width: 20px;
+    height: 20px;
+}
+
+.globe .stroke {
+    stroke: grey;
+    stroke-width: 2;
+}
+
+.globe .stroke:hover {
+    stroke: black;
+}
+
+.globe .close-button {
+    position: absolute;
+    top: 0;
+    right: 0;
+}
+
+.globe .marker {
+    display: inline-block;
+    position: absolute;
+    z-index: 1;
+    width: 30px;
+    height: 30px;
+    transform: translate(-50%, -96%);
+    stroke: white;
+}
+
+.globe .spot {
+    display: inline-block;
+    position: absolute;
+    z-index: 1;
+    width: 12px;
+    height: 12px;
+    transform: translate(-50%, -50%);
+    fill: red;
+    stroke: black;
+    stroke-width: 2px;
+}

package/factories/DateStatusElement.d.ts

@@ -1,67 +1,67 @@
 import Chart from 'chart.js/auto';
 import { DateRange } from './Tools';
-export declare class DateStatusElementInput {
-    setOfData: {
-        label: string;
-        style: string;
-        values: {
-            date: Date;
-            value: number;
-        }[];
+export interface IDataSet {
+    label: string;
+    style: string;
+    values: {
+        date: Date;
+        value: number;
     }[];
+}
+export interface IDataPoint {
+    label: string;
+    type: string;
+    data: number[];
+    borderColor: string;
+    backgroundColor: string;
+}
+export declare class DateStatusElementInput {
+    setOfData: IDataSet[];
     focusDate: Date;
     focusRange: DateRange;
-    constructor(setOfData?: {
-        label: string;
-        style: string;
-        values: {
-            date: Date;
-            value: number;
-        }[];
-    }[], focusDate?: Date, focusRange?: DateRange);
+    chartMinValue?: number;
+    chartMaxValue?: number;
+    constructor(setOfData?: IDataSet[], focusDate?: Date, focusRange?: DateRange, chartMinValue?: number, chartMaxValue?: number);
 }
 export declare class DateStatusElement {
     protected addSomeDebugInfos: boolean;
     chart: Chart<any>;
-    focusReset: () => void;
-    focusPrevious: () => void;
-    focusNext: () => void;
-    focusClick: (e: any) => void;
+    chartTitle: string;
+    focusReset: (dataPoints?: IDataPoint[]) => Promise<void>;
+    focusPrevious: () => Promise<void>;
+    focusNext: () => Promise<void>;
+    focusClick: (e: any) => Promise<void>;
+    minDate: Date;
+    maxDate: Date;
+    focusPos: number;
+    focusDate: Date;
+    focusRange: DateRange;
+    chartMinValue: number | undefined;
+    chartMaxValue: number | undefined;
     constructor(addSomeDebugInfos?: boolean);
-    protected static filterFocus(mapToFilter: Array<{
-        date: Date;
-        value: number;
-    }>, focusDate: Date, focusRange: DateRange): Array<{
-        date: Date;
-        value: number;
-    }>;
-    protected static groupFocus(mapToFilter: Array<{
-        date: Date;
-        value: number;
-    }>, focusDate: Date, focusRange: DateRange, min: Date, max: Date): any[];
-    protected static focusLabels(focusDate: Date, focusRange: DateRange, min: Date, max: Date, data: {
-        label: string;
-        style: string;
-        values: {
-            date: Date;
-            value: number;
-        }[];
-    }[]): any[];
-    protected static getFocusDateAndTitle(oldFocusDate: Date, focusRange: DateRange, index: number, min: Date, max: Date): {
-        newFocusDate: Date;
-        newTitle: string;
-    };
-    protected static buildLabel(date: Date): string;
-    protected static buildLabelYear(date: Date, year: number): string;
-    protected static buildLabelMonth(date: Date, month: number): string;
-    protected static buildLabelDay(date: Date, day: number): string;
-    protected static buildLabelHour(date: Date, hour: number): string;
-    protected static buildLabelMinute(date: Date, minute: number): string;
+    protected _setOfData: IDataSet[];
+    protected get setOfData(): IDataSet[];
+    protected set setOfData(value: IDataSet[]);
+    protected _originalDataPoints: number[][];
+    protected get originalDataPoints(): number[][];
     build(element: HTMLCanvasElement, inputs: DateStatusElementInput): void;
-    getFocusPosRelative(event: any, chart: any): any;
+    getFocusPosRelative(event: any, chart_: any): any;
+    protected updateChartTitle(title: string): void;
+    protected createChartConfig(data: {
+        datasets: IDataPoint[];
+        labels: string[];
+    }): any;
+    protected initializeChart(element: HTMLCanvasElement, config: any, inputs: DateStatusElementInput): void;
+    protected setupFocusHandlers(inputs: DateStatusElementInput): void;
+    protected setupFocusClickHandler(): void;
+    protected setupFocusResetHandler(inputs: DateStatusElementInput): void;
+    protected setupFocusNavigationHandlers(): void;
+    protected updateChartData(): void;
+    protected updateChart(eFocusPos: number, eFocusDate: Date, eFocusRange?: DateRange): void;
+    protected buildDateTimeSeries(focusDate: Date, focusRange: DateRange): IDataPoint[];
     protected getInitialFocusPos(focusDate: Date, focusRange: DateRange, min: Date): number;
-    protected getFocusPosAdded(chart: any, focusRange: DateRange, toAdd: number, focusDate: Date, min: Date): {
-        pos: any;
+    protected getFocusPosAdded(toAdd: number, focusDate?: Date, focusRange?: DateRange): {
+        pos: number;
         newFocusDate: Date;
     };
 }