ng-hub-ui-board 19.3.6 → 19.3.8

package/.npmignore

@@ -1,2 +1 @@
-# Nested package.json's are only needed for development.
-**/package.json
+node_modules

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [19.3.8] - 2026-01-16
+
+### Fixed
+
+-   Ensured correct publication of compiled artifacts by refining the release process.
+-   Reverted `exports` configuration to maintain consistency with other libraries.
+
+## [19.3.7] - 2026-01-16
+
+### Fixed
+
+-   Removed incorrect `!src/**/*` exclusion from `package.json` that was preventing CSS files from being included in the published package.
+
+## [19.3.6] - 2026-01-16
+
+### Fixed
+
+-   Added `styles` export configuration in package.json to properly expose SCSS files.
+
+## [19.3.5] - 2026-01-15
+
+### Changed
+
+-   Complete refactoring of board styling to use CSS variables for enhanced customization.
+-   Documented all available CSS variables in README.
+-   Added `StylingBoardExampleComponent` to showcase custom styling capabilities.
+
+## [19.3.4] - 2026-01-15
+
+### Changed
+
+-   Complete refactoring of board styling to use CSS variables for enhanced customization.
+-   Documented all available CSS variables in README.
+-   Added `StylingBoardExampleComponent` to showcase custom styling capabilities.
+
+## [19.3.3] - 2026-01-15
+
+### Changed
+
+-   Complete refactoring of board styling to use CSS variables for enhanced customization.
+-   Documented all available CSS variables in README.
+-   Added `StylingBoardExampleComponent` to showcase custom styling capabilities.
+
+## [19.3.2] - 2025-01-15
+
+### Changed
+
+-   Improved `reachedEnd` event documentation in README with correct usage examples showing `event.data` as the complete `BoardColumn` object
+-   Updated `reachedEnd` event example to include proper container with fixed height requirement for scroll detection
+-   Enhanced license section in README with detailed explanation of CC BY 4.0 permissions, requirements, and attribution example
+
+### Fixed
+
+-   Corrected misleading `reachedEnd` event documentation that incorrectly showed direct access to `event.data.title` instead of extracting the column first
+
+## [19.3.1] - 2024-10-05
+
+### Added
+
+-   Comprehensive JSDoc coverage across public models, directives, pipes, and the `HubBoardComponent` for improved API discoverability.
+-   New unit test ensuring the `reachedEnd` event is not emitted when column data is unavailable.
+
+### Changed
+
+-   Refined infinite-scroll detection tolerance to ensure `reachedEnd` fires reliably at the bottom of each column.
+-   Hardened the document example logic to avoid duplicate lazy-load requests while columns are already loading.
+-   Typed the `invertColor` pipe output and improved error handling for invalid HEX values.
+
+[19.3.1]: https://github.com/carlos-morcillo/ng-hub-ui-board/compare/19.3.0...19.3.1

package/FUNCTIONALITIES.md

@@ -0,0 +1,23 @@
+# Functionalities of Board Library
+
+This table details the functionalities of the `ng-hub-ui-board` library and indicates which ones are covered by interactive examples.
+
+## Kanban Board (`hub-ui-board`)
+
+| Category | Functionality | Example Covered |
+| :--- | :--- | :---: |
+| **Basic Usage** | Board Display (Columns & Cards) | ✅ |
+| | Responsive Layout | ✅ |
+| **Interactions** | Card Drag & Drop (Same Column) | ✅ |
+| | Card Drag & Drop (Cross Column) | ✅ |
+| | Column Reordering | ✅ |
+| | Card Click Handling | ✅ |
+| | Infinite Scroll (Column Reach End) | ✅ |
+| **Templates** | Custom Card Template (`*cardTpt`) | ✅ |
+| | Custom Column Header Template (`*columnHeaderTpt`) | ✅ |
+| | Custom Column Footer Template (`*columnFooterTpt`) | ✅ |
+| **Configuration** | Disable Column Sorting | ✅ |
+| | Custom Scroll Detection Padding | ✅ |
+
+---
+*Note: ✅ indicates an active interactive example is available in the documentation.*

package/karma.conf.js

@@ -0,0 +1,44 @@
+// Karma configuration file, see link for more information
+// https://karma-runner.github.io/1.0/config/configuration-file.html
+
+module.exports = function (config) {
+  config.set({
+    basePath: '',
+    frameworks: ['jasmine', '@angular-devkit/build-angular'],
+    plugins: [
+      require('karma-jasmine'),
+      require('karma-chrome-launcher'),
+      require('karma-jasmine-html-reporter'),
+      require('karma-coverage'),
+      require('@angular-devkit/build-angular/plugins/karma')
+    ],
+    client: {
+      jasmine: {
+        // you can add configuration options for Jasmine here
+        // the possible options are listed at https://jasmine.github.io/api/edge/Configuration.html
+        // for example, you can disable the random execution with `random: false`
+        // or set a specific seed with `seed: 4321`
+      },
+      clearContext: false // leave Jasmine Spec Runner output visible in browser
+    },
+    jasmineHtmlReporter: {
+      suppressAll: true // removes the duplicated traces
+    },
+    coverageReporter: {
+      dir: require('path').join(__dirname, '../../coverage/board'),
+      subdir: '.',
+      reporters: [
+        { type: 'html' },
+        { type: 'text-summary' }
+      ]
+    },
+    reporters: ['progress', 'kjhtml'],
+    port: 9876,
+    colors: true,
+    logLevel: config.LOG_INFO,
+    autoWatch: true,
+    browsers: ['Chrome'],
+    singleRun: false,
+    restartOnFileChange: true
+  });
+};

package/ng-package.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+	"dest": "../../dist/board",
+	"lib": {
+		"entryFile": "src/public-api.ts",
+		"styleIncludePaths": ["src/lib/styles"]
+	},
+	"assets": ["src/lib/styles"]
+}

package/package.json

@@ -1,105 +1,101 @@
 {
-  "name": "ng-hub-ui-board",
-  "version": "19.3.6",
-  "description": "An Angular-based Kanban board component with Trello-like drag-and-drop, customizable columns, and straightforward event handling.",
-  "main": "bundles/ng-hub-ui-board.umd.js",
-  "module": "fesm2022/ng-hub-ui-board.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./fesm2022/ng-hub-ui-board.mjs"
-    },
-    "./styles/*": {
-      "sass": "./src/lib/styles/*",
-      "default": "./src/lib/styles/*"
-    }
-  },
-  "peerDependencies": {
-    "@angular/common": ">=18.0.0",
-    "@angular/core": ">=18.0.0",
-    "@angular/cdk": ">=18.0.0"
-  },
-  "dependencies": {
-    "tslib": "^2.3.0"
-  },
-  "sideEffects": false,
-  "files": [
-    "**/*",
-    "!**/*.spec.ts",
-    "!**/*.spec.js",
-    "!**/*.test.ts",
-    "!**/*.test.js",
-    "!src/**/*"
-  ],
-  "keywords": [
-    "angular",
-    "kanban",
-    "board",
-    "trello",
-    "drag-drop",
-    "dnd",
-    "columns",
-    "cards",
-    "tasks",
-    "todo",
-    "productivity",
-    "collaboration",
-    "organization",
-    "project-management",
-    "workflow",
-    "agile",
-    "scrum",
-    "component",
-    "reusable",
-    "open-source",
-    "typescript",
-    "standalone",
-    "cdk",
-    "ui-library",
-    "ng-hub-ui"
-  ],
-  "author": {
-    "name": "Carlos Morcillo Fernández",
-    "email": "carlos.morcillo@me.com",
-    "url": "https://www.carlosmorcillo.com"
-  },
-  "maintainers": [
-    {
-      "name": "Carlos Morcillo Fernández",
-      "email": "carlos.morcillo@me.com",
-      "url": "https://www.carlosmorcillo.com"
-    }
-  ],
-  "homepage": "https://github.com/carlos-morcillo/ng-hub-ui-board#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/carlos-morcillo/ng-hub-ui-board.git"
-  },
-  "bugs": {
-    "url": "https://github.com/carlos-morcillo/ng-hub-ui-board/issues",
-    "email": "carlos.morcillo@me.com"
-  },
-  "funding": {
-    "type": "buymeacoffee",
-    "url": "https://buymeacoffee.com/carlosmorcillo"
-  },
-  "license": "CC-BY-4.0",
-  "engines": {
-    "node": ">=18.13.0",
-    "npm": ">=9.0.0"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "ng-add": {
-    "save": "dependencies"
-  },
-  "contributors": [
-    "Carlos Morcillo Fernández <carlos.morcillo@me.com>"
-  ]
-}
+	"name": "ng-hub-ui-board",
+	"version": "19.3.8",
+	"description": "An Angular-based Kanban board component with Trello-like drag-and-drop, customizable columns, and straightforward event handling.",
+	"main": "bundles/ng-hub-ui-board.umd.js",
+	"module": "fesm2022/ng-hub-ui-board.mjs",
+	"typings": "index.d.ts",
+	"peerDependencies": {
+		"@angular/common": ">=18.0.0",
+		"@angular/core": ">=18.0.0",
+		"@angular/cdk": ">=18.0.0"
+	},
+	"dependencies": {
+		"tslib": "^2.3.0"
+	},
+	"sideEffects": false,
+	"scripts": {
+		"build": "ng build board",
+		"build:prod": "ng build board --configuration production",
+		"test": "ng test board",
+		"test:watch": "ng test board --watch",
+		"test:coverage": "ng test board --code-coverage",
+		"lint": "ng lint board",
+		"pack": "npm pack",
+		"publish:npm": "npm publish"
+	},
+	"files": [
+		"**/*",
+		"!**/*.spec.ts",
+		"!**/*.spec.js",
+		"!**/*.test.ts",
+		"!**/*.test.js"
+	],
+	"keywords": [
+		"angular",
+		"kanban",
+		"board",
+		"trello",
+		"drag-drop",
+		"dnd",
+		"columns",
+		"cards",
+		"tasks",
+		"todo",
+		"productivity",
+		"collaboration",
+		"organization",
+		"project-management",
+		"workflow",
+		"agile",
+		"scrum",
+		"component",
+		"reusable",
+		"open-source",
+		"typescript",
+		"standalone",
+		"cdk",
+		"ui-library",
+		"ng-hub-ui"
+	],
+	"author": {
+		"name": "Carlos Morcillo Fernández",
+		"email": "carlos.morcillo@me.com",
+		"url": "https://www.carlosmorcillo.com"
+	},
+	"maintainers": [
+		{
+			"name": "Carlos Morcillo Fernández",
+			"email": "carlos.morcillo@me.com",
+			"url": "https://www.carlosmorcillo.com"
+		}
+	],
+	"homepage": "https://github.com/carlos-morcillo/ng-hub-ui-board#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/carlos-morcillo/ng-hub-ui-board.git"
+	},
+	"bugs": {
+		"url": "https://github.com/carlos-morcillo/ng-hub-ui-board/issues",
+		"email": "carlos.morcillo@me.com"
+	},
+	"funding": {
+		"type": "buymeacoffee",
+		"url": "https://buymeacoffee.com/carlosmorcillo"
+	},
+	"license": "CC-BY-4.0",
+	"engines": {
+		"node": ">=18.13.0",
+		"npm": ">=9.0.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"ng-add": {
+		"save": "dependencies"
+	},
+	"contributors": [
+		"Carlos Morcillo Fernández <carlos.morcillo@me.com>"
+	]
+}

package/src/lib/board.module.ts

@@ -0,0 +1,51 @@
+import { NgModule } from '@angular/core';
+import { HubBoardComponent } from './components/board/board.component';
+import { BoardColumnFooterDirective } from './directives/board-column-footer.directive';
+import { BoardColumnHeaderDirective } from './directives/board-column-header.directive';
+import { CardTemplateDirective } from './directives/card-template.directive';
+
+/**
+ * Angular module that provides board functionality with drag-and-drop support.
+ * 
+ * This module includes all the necessary components and directives for creating
+ * Kanban-style boards with customizable columns, cards, and templates.
+ * 
+ * @deprecated Use standalone components instead. Import individual components and directives directly.
+ * @publicApi
+ * 
+ * @example
+ * ```typescript
+ * // Legacy module approach (not recommended)
+ * import { BoardModule } from 'ng-hub-ui-board';
+ * 
+ * @NgModule({
+ *   imports: [BoardModule]
+ * })
+ * export class AppModule {}
+ * 
+ * // Recommended standalone approach
+ * import { HubBoardComponent, CardTemplateDirective } from 'ng-hub-ui-board';
+ * 
+ * @Component({
+ *   standalone: true,
+ *   imports: [HubBoardComponent, CardTemplateDirective]
+ * })
+ * export class MyComponent {}
+ * ```
+ */
+@NgModule({
+	declarations: [],
+	imports: [
+		HubBoardComponent,
+		CardTemplateDirective,
+		BoardColumnHeaderDirective,
+		BoardColumnFooterDirective
+	],
+	exports: [
+		HubBoardComponent,
+		CardTemplateDirective,
+		BoardColumnHeaderDirective,
+		BoardColumnFooterDirective
+	]
+})
+export class BoardModule {}

package/src/lib/components/board/board.component.html

@@ -0,0 +1,88 @@
+@if (columns().length) {
+<div
+	class="hub-board__drop-list"
+	cdkDropList
+	cdkDropListOrientation="horizontal"
+	[cdkDropListData]="columns()"
+	(cdkDropListDropped)="dropColumn($event)"
+	[cdkDropListSortingDisabled]="columnSortingDisabled()"
+>
+	<div cdkDropListGroup class="hub-board__columns">
+		@for (column of columns(); let index = $index; track column) {
+		<div class="hub-board__column-container" cdkDrag [cdkDragData]="column" [cdkDragDisabled]="column.disabled">
+			<div class="hub-board__column" [ngClass]="column.classlist" [ngStyle]="column.style">
+				<div class="hub-board__column-header">
+					<ng-container
+						[ngTemplateOutlet]="columnHeaderTpt() || defaultColumnHeaderTpt"
+						[ngTemplateOutletContext]="{ column: column }"
+					>
+					</ng-container>
+				</div>
+				<div
+					class="hub-board__column-body"
+					cdkDropList
+					[cdkDropListData]="column"
+					(cdkDropListDropped)="dropCard($event)"
+					(scroll)="onScroll(index, $event)"
+					[cdkDropListEnterPredicate]="column.predicate ?? defaultEnterPredicateFn"
+					[cdkDropListSortingDisabled]="column.cardSortingDisabled"
+				>
+					@for ( card of column.cards; let index = $index; track card ) {
+					<div
+						class="hub-board__card"
+						[class.hub-board__card--disabled]="card.disabled"
+						cdkDrag
+						[cdkDragData]="card"
+						[cdkDragDisabled]="card.disabled"
+						(click)="cardClick(card)"
+						(mousedown)="card.disabled && $event.stopPropagation()"
+						[ngClass]="card.classlist"
+						[ngStyle]="card.style"
+					>
+						<div class="hub-board__card-body">
+							<ng-container
+								[ngTemplateOutlet]="cardTpt() || defaultCardTpt"
+								[ngTemplateOutletContext]="{
+									item: card,
+									column
+								}"
+							>
+							</ng-container>
+						</div>
+					</div>
+					}
+				</div>
+
+				@if (columnFooterTpt()) {
+				<div class="hub-board__column-footer">
+					<ng-container
+						[ngTemplateOutlet]="columnFooterTpt() ?? null"
+						[ngTemplateOutletContext]="{
+							column: column
+						}"
+					>
+					</ng-container>
+				</div>
+				}
+			</div>
+		</div>
+		}
+	</div>
+</div>
+}
+
+<ng-template #defaultCardTpt let-item="item">
+	<h6 class="hub-board__card-title">{{ item.title }}</h6>
+	<p class="hub-board__card-subtitle">{{ item.description }}</p>
+</ng-template>
+
+<ng-template #defaultColumnHeaderTpt let-column="column">
+	<div class="d-flex flex-column">
+		<h5 class="hub-board__column-header-title">
+			{{ column.title }}
+		</h5>
+		<h6 class="hub-board__column-header-subtitle">
+			{{ column.description }}
+		</h6>
+	</div>
+</ng-template>

package/src/lib/components/board/board.component.ts

@@ -0,0 +1,167 @@
+import { CdkDragDrop, DragDropModule, moveItemInArray, transferArrayItem } from '@angular/cdk/drag-drop';
+import { NgClass, NgStyle, NgTemplateOutlet } from '@angular/common';
+import { Component, Signal, TemplateRef, computed, contentChild, input, output } from '@angular/core';
+import { BoardColumnFooterDirective } from '../../directives/board-column-footer.directive';
+import { BoardColumnHeaderDirective } from '../../directives/board-column-header.directive';
+import { CardTemplateDirective } from '../../directives/card-template.directive';
+import { Board } from '../../models/board';
+import { BoardCard } from '../../models/board-card';
+import { BoardColumn } from '../../models/board-column';
+import { ReachedEndEvent } from '../../models/reached-end-event';
+
+/**
+ * Standalone Kanban-style board component that provides column-based drag-and-drop,
+ * custom templates and infinite-scroll detection.
+ *
+ * @publicApi
+ */
+@Component({
+	selector: 'hub-board, hub-ui-board',
+	templateUrl: './board.component.html',
+	imports: [NgClass, NgStyle, NgTemplateOutlet, DragDropModule],
+	host: {
+		class: 'hub-board'
+	}
+})
+export class HubBoardComponent {
+	/**
+	 * Reactive input containing the full board definition (columns and cards).
+	 */
+	readonly board = input<Board>();
+
+	/**
+	 * Pixel threshold used when determining whether a column has reached scroll end.
+	 * Allows for fractional scroll values across different browsers.
+	 */
+	private readonly scrollDetectionPadding = 1;
+
+	/**
+	 * Derived list of board columns exposed as a signal to the template.
+	 */
+	columns: Signal<Array<BoardColumn>> = computed(() => {
+		return this.board()?.columns ?? [];
+	});
+
+	/**
+	 * When true, column reordering via drag-and-drop is disabled.
+	 */
+	readonly columnSortingDisabled = input<boolean>(false);
+
+	/**
+	 * Custom card template supplied via the `cardTpt` structural directive.
+	 */
+	readonly cardTpt = contentChild(CardTemplateDirective, {
+		read: TemplateRef<unknown>
+	});
+
+	/**
+	 * Custom column header template supplied via the `columnHeaderTpt` structural directive.
+	 */
+	readonly columnHeaderTpt = contentChild(BoardColumnHeaderDirective, {
+		read: TemplateRef<unknown>
+	});
+
+	/**
+	 * Custom column footer template supplied via the `columnFooterTpt` structural directive.
+	 */
+	readonly columnFooterTpt = contentChild(BoardColumnFooterDirective, {
+		read: TemplateRef<unknown>
+	});
+
+	/**
+	 * Emits each time a card is clicked within the board.
+	 */
+	readonly onCardClick = output<BoardCard>();
+
+	/**
+	 * Emits when a card has been repositioned, either within the same column or into another column.
+	 */
+	readonly onCardMoved = output<CdkDragDrop<BoardColumn, BoardColumn, BoardCard<any>>>();
+
+	/**
+	 * Emits when columns are reordered through drag-and-drop.
+	 */
+	readonly onColumnMoved = output<CdkDragDrop<BoardColumn[]>>();
+
+	/**
+	 * Emits when a column body is scrolled to its end, enabling infinite-scroll behaviour.
+	 */
+	readonly reachedEnd = output<ReachedEndEvent>();
+
+	/**
+	 * Default predicate that allows any card to be dropped into any column.
+	 *
+	 * @returns Always `true`, indicating that drop operations are permitted.
+	 */
+	defaultEnterPredicateFn = () => true;
+
+	/**
+	 * Emits the clicked card through {@link onCardClick}.
+	 *
+	 * @param item - The card that triggered the click event.
+	 */
+	cardClick(item: BoardCard) {
+		this.onCardClick.emit(item);
+	}
+
+	/**
+	 * Updates column order when a drag-and-drop operation completes and emits the resulting event.
+	 *
+	 * @param event - Drag-and-drop metadata describing the column movement.
+	 */
+	dropColumn(event: CdkDragDrop<BoardColumn[]>) {
+		moveItemInArray(event.container.data, event.previousIndex, event.currentIndex);
+		this.onColumnMoved.emit(event);
+	}
+
+	/**
+	 * Applies card reordering or transfer logic depending on the drag-drop target,
+	 * then emits the corresponding drag event metadata.
+	 *
+	 * @param event - Drag-and-drop metadata describing the card movement.
+	 */
+	dropCard(event: CdkDragDrop<BoardColumn, BoardColumn, BoardCard<any>>) {
+		if (event.previousContainer === event.container) {
+			// Reorder the card within the same column
+			moveItemInArray(event.container.data.cards, event.previousIndex, event.currentIndex);
+		} else {
+			// Transfer the card from one column to another
+			transferArrayItem(
+				event.previousContainer.data.cards,
+				event.container.data.cards,
+				event.previousIndex,
+				event.currentIndex
+			);
+		}
+		this.onCardMoved.emit(event);
+	}
+
+	/**
+	 * Emits {@link reachedEnd} once a column body is scrolled to its bottom.
+	 *
+	 * @param index - Index of the scrolled column within the board.
+	 * @param event - Browser scroll event originating from the column body element.
+	 */
+	onScroll(index: number, event: Event) {
+		const el = event.target as HTMLElement | null;
+		if (!el) {
+			return;
+		}
+
+		const scrolledToBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - this.scrollDetectionPadding;
+
+		if (!scrolledToBottom) {
+			return;
+		}
+
+		const column = this.board()?.columns?.[index];
+		if (!column) {
+			return;
+		}
+
+		this.reachedEnd.emit({
+			index,
+			data: column
+		});
+	}
+}