ng-hub-ui-board/index.d.ts

An Angular-based Kanban board component with Trello-like drag-and-drop, customizable columns, and straightforward event handling.

import * as i0 from '@angular/core';
import { Signal, TemplateRef, PipeTransform } from '@angular/core';
import { CdkDrag, CdkDragDrop } from '@angular/cdk/drag-drop';

/**
 * Represents a card within a board column, containing the core data and behavior.
 *
 * @template T The type of custom data attached to the card (defaults to `any`).
 * @publicApi
 */
interface BoardCard<T = any> {
    /**
     * Unique identifier for the card.
     */
    id?: number;
    /**
     * The identifier of the column this card belongs to.
     */
    columnId?: number;
    /**
     * The main title displayed on the card.
     */
    title: string;
    /**
     * Optional description providing additional details about the card.
     */
    description?: string;
    /**
     * Custom data that can be attached to this card, such as metadata,
     * priority levels, due dates, or any application-specific information.
     */
    data?: T;
    /**
     * Optional list of CSS classes to apply to the card for custom styling.
     */
    classlist?: string[];
    /**
     * Custom inline styles for the card, represented as a key-value mapping.
     */
    style?: {
        [key: string]: any;
    };
    /**
     * If true, the card is disabled and cannot be interacted with (e.g., dragged or clicked).
     */
    disabled?: boolean;
}

/**
 * Represents a column within a board layout.
 *
 * @template T The data type associated with the column (defaults to `any`).
 * @publicApi
 */
interface BoardColumn<T = any> {
    /**
     * A unique identifier for the column.
     */
    id?: number;
    /**
     * The identifier of the board this column belongs to.
     */
    boardId?: number;
    /**
     * The title displayed for this column.
     */
    title: string;
    /**
     * An optional description of this column.
     */
    description?: string;
    /**
     * An array of cards contained within this column.
     */
    cards: BoardCard<T>[];
    /**
     * An optional set of inline styles applied to the column.
     */
    style?: {
        [key: string]: any;
    };
    /**
     * A string or array of CSS classes applied to the column.
     */
    classlist?: string[] | string;
    /**
     * If true, the column is disabled (e.g., user interactions might be restricted).
     */
    disabled?: boolean;
    /**
     * Additional data that can be attached to this column.
     */
    data?: any;
    /**
     * If true, sorting cards within this column (via drag-and-drop) is disabled.
     */
    cardSortingDisabled?: boolean;
    /**
     * A function to determine whether a dragged item is allowed in this column.
     *
     * @param item The dragged item (if any) being tested.
     * @returns A boolean indicating if the item can be dropped in this column.
     */
    predicate?: (item?: CdkDrag<T>) => boolean;
}

/**
 * Represents a board that can be composed of multiple columns.
 *
 * @template T - The type of data handled by each column (defaults to `any`).
 * @publicApi
 */
interface Board<T = any> {
    /**
     * Unique identifier for the board.
     */
    id?: number;
    /**
     * The board's main title.
     */
    title: string;
    /**
     * Optional description providing more details about the board.
     */
    description?: string;
    /**
     * An array of columns that belong to this board.
     */
    columns?: BoardColumn<T>[];
    /**
     * Optional list of CSS classes to apply to the board.
     */
    classlist?: string[];
    /**
     * Custom inline styles for the board, represented as a key-value mapping.
     */
    style?: {
        [key: string]: any;
    };
}

/**
 * Event emitted when a column body is scrolled to its bottom.
 *
 * @template T - The type of column data being exposed to consumers (defaults to `any`).
 * @publicApi
 */
interface ReachedEndEvent<T = any> {
    index: number;
    data: T;
}

/**
 * Standalone Kanban-style board component that provides column-based drag-and-drop,
 * custom templates and infinite-scroll detection.
 *
 * @publicApi
 */
declare class HubBoardComponent {
    /**
     * Reactive input containing the full board definition (columns and cards).
     */
    readonly board: i0.InputSignal<Board<any> | undefined>;
    /**
     * Pixel threshold used when determining whether a column has reached scroll end.
     * Allows for fractional scroll values across different browsers.
     */
    private readonly scrollDetectionPadding;
    /**
     * Derived list of board columns exposed as a signal to the template.
     */
    columns: Signal<Array<BoardColumn>>;
    /**
     * When true, column reordering via drag-and-drop is disabled.
     */
    readonly columnSortingDisabled: i0.InputSignal<boolean>;
    /**
     * Custom card template supplied via the `cardTpt` structural directive.
     */
    readonly cardTpt: Signal<TemplateRef<any> | undefined>;
    /**
     * Custom column header template supplied via the `columnHeaderTpt` structural directive.
     */
    readonly columnHeaderTpt: Signal<TemplateRef<any> | undefined>;
    /**
     * Custom column footer template supplied via the `columnFooterTpt` structural directive.
     */
    readonly columnFooterTpt: Signal<TemplateRef<any> | undefined>;
    /**
     * Emits each time a card is clicked within the board.
     */
    readonly onCardClick: i0.OutputEmitterRef<BoardCard<any>>;
    /**
     * Emits when a card has been repositioned, either within the same column or into another column.
     */
    readonly onCardMoved: i0.OutputEmitterRef<CdkDragDrop<BoardColumn<any>, BoardColumn<any>, BoardCard<any>>>;
    /**
     * Emits when columns are reordered through drag-and-drop.
     */
    readonly onColumnMoved: i0.OutputEmitterRef<CdkDragDrop<BoardColumn<any>[], BoardColumn<any>[], any>>;
    /**
     * Emits when a column body is scrolled to its end, enabling infinite-scroll behaviour.
     */
    readonly reachedEnd: i0.OutputEmitterRef<ReachedEndEvent<any>>;
    /**
     * Default predicate that allows any card to be dropped into any column.
     *
     * @returns Always `true`, indicating that drop operations are permitted.
     */
    defaultEnterPredicateFn: () => boolean;
    /**
     * Emits the clicked card through {@link onCardClick}.
     *
     * @param item - The card that triggered the click event.
     */
    cardClick(item: BoardCard): void;
    /**
     * 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[]>): void;
    /**
     * 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>>): void;
    /**
     * 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): void;
    static ɵfac: i0.ɵɵFactoryDeclaration<HubBoardComponent, never>;
    static ɵcmp: i0.ɵɵComponentDeclaration<HubBoardComponent, "hub-board, hub-ui-board", never, { "board": { "alias": "board"; "required": false; "isSignal": true; }; "columnSortingDisabled": { "alias": "columnSortingDisabled"; "required": false; "isSignal": true; }; }, { "onCardClick": "onCardClick"; "onCardMoved": "onCardMoved"; "onColumnMoved": "onColumnMoved"; "reachedEnd": "reachedEnd"; }, ["cardTpt", "columnHeaderTpt", "columnFooterTpt"], never, true, never>;
}

/**
 * Directive that allows customization of card templates within board columns.
 *
 * This directive is used to define custom templates for rendering board cards.
 * It provides access to the template reference that can be used by the board component
 * to render cards with custom layouts and styling.
 *
 * @publicApi
 *
 * @example
 * ```html
 * <ng-template cardTpt let-card="item" let-column="column">
 *   <div class="custom-card">
 *     <h3>{{ card.title }}</h3>
 *     <p>{{ card.description }}</p>
 *   </div>
 * </ng-template>
 * ```
 */
declare class CardTemplateDirective {
    templateRef: TemplateRef<unknown>;
    /**
     * Creates a new CardTemplateDirective instance.
     *
     * @param templateRef - The template reference that contains the custom card layout
     */
    constructor(templateRef: TemplateRef<unknown>);
    static ɵfac: i0.ɵɵFactoryDeclaration<CardTemplateDirective, never>;
    static ɵdir: i0.ɵɵDirectiveDeclaration<CardTemplateDirective, "[cardTpt]", never, {}, {}, never, never, true, never>;
}

/**
 * Directive that allows customization of column header templates within board columns.
 *
 * This directive provides the ability to define custom templates for rendering column headers,
 * giving developers full control over the appearance and functionality of column headers
 * including titles, descriptions, actions, and metadata display.
 *
 * @publicApi
 *
 * @example
 * ```html
 * <ng-template columnHeaderTpt let-column="column">
 *   <div class="custom-header">
 *     <h2>{{ column.title }}</h2>
 *     <span class="card-count">{{ column.cards.length }} items</span>
 *     <button (click)="addCard(column)">Add Card</button>
 *   </div>
 * </ng-template>
 * ```
 */
declare class BoardColumnHeaderDirective {
    templateRef: TemplateRef<unknown>;
    /**
     * Creates a new BoardColumnHeaderDirective instance.
     *
     * @param templateRef - The template reference that contains the custom column header layout
     */
    constructor(templateRef: TemplateRef<unknown>);
    static ɵfac: i0.ɵɵFactoryDeclaration<BoardColumnHeaderDirective, never>;
    static ɵdir: i0.ɵɵDirectiveDeclaration<BoardColumnHeaderDirective, "[columnHeaderTpt]", never, {}, {}, never, never, true, never>;
}

/**
 * Directive that allows customization of column footer templates within board columns.
 *
 * This directive enables developers to define custom templates for column footers,
 * perfect for displaying summary information, quick actions, statistics,
 * or any column-specific controls at the bottom of each column.
 *
 * @publicApi
 *
 * @example
 * ```html
 * <ng-template columnFooterTpt let-column="column">
 *   <div class="custom-footer">
 *     <div class="column-summary">
 *       <span>Total: {{ column.cards.length }}</span>
 *       <span>Priority Items: {{ getPriorityItems(column) }}</span>
 *     </div>
 *     <button (click)="quickAddCard(column)">Quick Add</button>
 *   </div>
 * </ng-template>
 * ```
 */
declare class BoardColumnFooterDirective {
    templateRef: TemplateRef<unknown>;
    /**
     * Creates a new BoardColumnFooterDirective instance.
     *
     * @param templateRef - The template reference that contains the custom column footer layout
     */
    constructor(templateRef: TemplateRef<unknown>);
    static ɵfac: i0.ɵɵFactoryDeclaration<BoardColumnFooterDirective, never>;
    static ɵdir: i0.ɵɵDirectiveDeclaration<BoardColumnFooterDirective, "[columnFooterTpt]", never, {}, {}, never, never, true, never>;
}

/**
 * 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 {}
 * ```
 */
declare class BoardModule {
    static ɵfac: i0.ɵɵFactoryDeclaration<BoardModule, never>;
    static ɵmod: i0.ɵɵNgModuleDeclaration<BoardModule, never, [typeof HubBoardComponent, typeof CardTemplateDirective, typeof BoardColumnHeaderDirective, typeof BoardColumnFooterDirective], [typeof HubBoardComponent, typeof CardTemplateDirective, typeof BoardColumnHeaderDirective, typeof BoardColumnFooterDirective]>;
    static ɵinj: i0.ɵɵInjectorDeclaration<BoardModule>;
}

/**
 * Converts a hexadecimal color string into its inverted counterpart, offering both
 * high-contrast black/white and full-spectrum inversion modes.
 *
 * @publicApi
 */
declare class InvertColorPipe implements PipeTransform {
    /**
     * Inverts a HEX color value.
     *
     * @param hex - Color expressed as a 3- or 6-digit HEX string with or without a hash prefix.
     * @param bw - When `true`, returns either black or white based on perceived brightness to maximise contrast.
     * @returns The inverted color represented as a 6-digit HEX string (always prefixed with `#`).
     * @throws Error if the provided value cannot be parsed as a valid HEX color.
     */
    transform(hex: string, bw: boolean): string;
    static ɵfac: i0.ɵɵFactoryDeclaration<InvertColorPipe, never>;
    static ɵpipe: i0.ɵɵPipeDeclaration<InvertColorPipe, "invertColor", true>;
}

export { BoardColumnFooterDirective, BoardColumnHeaderDirective, BoardModule, CardTemplateDirective, HubBoardComponent, InvertColorPipe };
export type { Board, BoardCard, BoardColumn, ReachedEndEvent };