@aquera/ngx-smart-table 0.0.2-alpha

package/lib/models/base-column-config.class.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Base column configuration class implementing Template Method pattern
+ */
+import { ColumnConfig } from './column-config.interface';
+import { Cell } from '../renderer/models/cell.class';
+import { CellFormatter, CellValidator, CellEditor, CellParser, CellLifecycleHooks } from './cell-strategies.interface';
+import { CellAlignment, CellVerticalAlignment, EditMode, CellDataType, ValidationResult } from './cell-types';
+import { TemplateRef } from '@angular/core';
+/**
+ * Abstract base class for column configurations
+ * Implements Template Method pattern for cell operations
+ */
+export declare abstract class BaseColumnConfig<T = any> implements ColumnConfig<T> {
+    readonly key: string;
+    readonly header?: string;
+    readonly dataType?: CellDataType;
+    readonly formatter?: CellFormatter<T>;
+    readonly validator?: CellValidator<T>;
+    readonly editor?: CellEditor<T>;
+    readonly parser?: CellParser<T>;
+    readonly editable?: boolean;
+    readonly editMode?: EditMode;
+    readonly sortable?: boolean;
+    readonly filterable?: boolean;
+    readonly resizable?: boolean;
+    readonly width?: number | string;
+    readonly minWidth?: number;
+    readonly maxWidth?: number;
+    readonly alignment?: CellAlignment;
+    readonly verticalAlignment?: CellVerticalAlignment;
+    readonly truncate?: boolean;
+    readonly tooltip?: string | ((value: T, rowData: any) => string);
+    readonly className?: string | string[] | ((value: T, rowData: any) => string | string[]);
+    readonly style?: Record<string, any> | ((value: T, rowData: any) => Record<string, any>);
+    readonly cellTemplate?: TemplateRef<any>;
+    readonly headerTemplate?: TemplateRef<any>;
+    readonly visible?: boolean;
+    readonly pinned?: 'left' | 'right' | false;
+    readonly sortPriority?: number;
+    readonly comparator?: (a: T, b: T) => number;
+    readonly valueGetter?: (rowData: any) => T;
+    readonly valueSetter?: (rowData: any, value: T) => void;
+    readonly hooks?: CellLifecycleHooks<T>;
+    readonly showLoadingIndicator?: boolean;
+    readonly metadata?: Record<string, any>;
+    constructor(config: Partial<ColumnConfig<T>> & {
+        key: string;
+    });
+    /**
+     * Factory method to create a cell (Factory Pattern)
+     * Can be overridden by subclasses for custom cell creation
+     */
+    createCell(rowData: any, rowIndex?: number): Cell<T>;
+    /**
+     * Template method for processing cell edit workflow
+     * Defines the algorithm steps that subclasses can customize
+     */
+    processEdit(cell: Cell<T>, newValue: T): boolean;
+    /**
+     * Hook: Before edit validation (can be overridden)
+     */
+    protected beforeEdit(cell: Cell<T>, newValue: T): boolean;
+    /**
+     * Hook: After edit completion (can be overridden)
+     */
+    protected afterEdit(cell: Cell<T>, newValue: T): void;
+    /**
+     * Hook: After cell is created (can be overridden)
+     */
+    protected afterCellCreated(cell: Cell<T>, rowData: any, rowIndex?: number): void;
+    /**
+     * Hook: When validation fails (can be overridden)
+     */
+    protected onValidationFailed(cell: Cell<T>, validationResult: ValidationResult): void;
+    /**
+     * Extract value from row data (can be overridden)
+     */
+    protected extractValue(rowData: any): T;
+    /**
+     * Parse value using parser if available (can be overridden)
+     */
+    protected parseValue(value: any): T | undefined;
+    /**
+     * Validate value using validator if available (can be overridden)
+     */
+    protected validateValue(value: T, rowData: any): ValidationResult;
+    /**
+     * Format value for display (can be overridden)
+     */
+    formatValue(value: T, rowData?: any): string;
+    /**
+     * Get cell tooltip (can be overridden)
+     */
+    getTooltip(value: T, rowData: any): string | undefined;
+    /**
+     * Get cell class names (can be overridden)
+     */
+    getClassName(value: T, rowData: any): string | string[] | undefined;
+    /**
+     * Get cell styles (can be overridden)
+     */
+    getStyle(value: T, rowData: any): Record<string, any> | undefined;
+    /**
+     * Compare two values for sorting (can be overridden)
+     */
+    compare(a: T, b: T): number;
+}
+/**
+ * Concrete implementation for simple use cases
+ */
+export declare class SimpleColumnConfig<T = any> extends BaseColumnConfig<T> {
+    constructor(config: Partial<ColumnConfig<T>> & {
+        key: string;
+    });
+}

package/lib/models/cell-strategies.interface.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Strategy interfaces for cell behavior
+ * These interfaces define pluggable strategies for formatting, validation, and editing
+ */
+import { ValidationResult, CellEvent } from './cell-types';
+/**
+ * Strategy interface for formatting cell values for display
+ * Formatters are stateless and can be shared across multiple cells
+ */
+export interface CellFormatter<T = any> {
+    /**
+     * Formats a value for display
+     * @param value The value to format
+     * @returns Formatted string representation
+     */
+    format(value: T): string;
+    /**
+     * Optional method to format value with additional context
+     * @param value The value to format
+     * @param rowData The entire row data
+     * @param columnKey The column key
+     * @returns Formatted string representation
+     */
+    formatWithContext?(value: T, rowData: any, columnKey: string): string;
+}
+/**
+ * Strategy interface for validating cell values
+ * Validators are stateless and can be shared across multiple cells
+ */
+export interface CellValidator<T = any> {
+    /**
+     * Validates a cell value
+     * @param value The value to validate
+     * @returns Validation result with success flag and optional error messages
+     */
+    validate(value: T): ValidationResult;
+    /**
+     * Optional method to validate with additional context
+     * @param value The value to validate
+     * @param rowData The entire row data
+     * @param columnKey The column key
+     * @returns Validation result
+     */
+    validateWithContext?(value: T, rowData: any, columnKey: string): ValidationResult;
+    /**
+     * Optional error message template
+     */
+    errorMessage?: string;
+}
+/**
+ * Editor context provided to cell editors
+ */
+export interface CellEditorContext<T = any> {
+    /**
+     * Current cell value
+     */
+    value: T;
+    /**
+     * Row data context
+     */
+    rowData?: any;
+    /**
+     * Column key
+     */
+    columnKey: string;
+    /**
+     * Row index
+     */
+    rowIndex?: number;
+    /**
+     * Callback when value changes
+     */
+    onChange: (newValue: T) => void;
+    /**
+     * Callback to save the edited value
+     */
+    onSave: (newValue: T) => void;
+    /**
+     * Callback to cancel editing
+     */
+    onCancel: () => void;
+    /**
+     * Container element for the editor
+     */
+    container?: HTMLElement;
+}
+/**
+ * Strategy interface for handling inline cell editing
+ * Editors are stateless and can be shared across multiple cells
+ */
+export interface CellEditor<T = any> {
+    /**
+     * Initialize and render the editor
+     * @param context Editor context with value, callbacks, and container
+     */
+    edit(context: CellEditorContext<T>): void;
+    /**
+     * Optional cleanup when editor is destroyed
+     */
+    destroy?(): void;
+    /**
+     * Optional method to focus the editor
+     */
+    focus?(): void;
+    /**
+     * Optional method to get current editor value without saving
+     */
+    getCurrentValue?(): T;
+}
+/**
+ * Parser interface for converting user input to typed values
+ * Used by editors to convert string input to proper data types
+ */
+export interface CellParser<T = any> {
+    /**
+     * Parse user input to typed value
+     * @param input User input (usually string)
+     * @returns Parsed typed value
+     */
+    parse(input: any): T;
+    /**
+     * Optional method to check if input can be parsed
+     * @param input User input
+     * @returns True if input can be parsed
+     */
+    canParse?(input: any): boolean;
+}
+/**
+ * Composite validator that chains multiple validators
+ */
+export interface CompositeValidator<T = any> extends CellValidator<T> {
+    /**
+     * Add a validator to the chain
+     */
+    addValidator(validator: CellValidator<T>): this;
+    /**
+     * Get all validators in the chain
+     */
+    getValidators(): CellValidator<T>[];
+}
+/**
+ * Event handler types for cell lifecycle events
+ */
+export declare type CellEventHandler<T = any> = (event: CellEvent<T>) => void;
+/**
+ * Cell lifecycle hooks
+ */
+export interface CellLifecycleHooks<T = any> {
+    /**
+     * Called before editing starts
+     */
+    beforeEdit?: CellEventHandler<T>;
+    /**
+     * Called when edit mode is entered
+     */
+    onEdit?: CellEventHandler<T>;
+    /**
+     * Called after edit mode is exited
+     */
+    afterEdit?: CellEventHandler<T>;
+    /**
+     * Called before value is saved
+     */
+    beforeSave?: CellEventHandler<T>;
+    /**
+     * Called after value is saved
+     */
+    onSave?: CellEventHandler<T>;
+    /**
+     * Called when edit is cancelled
+     */
+    onCancel?: CellEventHandler<T>;
+    /**
+     * Called when validation fails
+     */
+    onValidationError?: CellEventHandler<T>;
+    /**
+     * Called when cell value changes
+     */
+    onChange?: CellEventHandler<T>;
+}

package/lib/models/cell-types.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Base type definitions for cell configuration model
+ */
+import type { Cell } from '../renderer/models/cell.class';
+import type { CellState } from '../renderer/models/cell-state.interface';
+/**
+ * Supported cell data types
+ */
+export declare type CellValue = string | number | boolean | Date | null | undefined | any;
+/**
+ * Data type enumeration for type-specific handling
+ */
+export declare enum CellDataType {
+    STRING = "string",
+    NUMBER = "number",
+    BOOLEAN = "boolean",
+    DATE = "date",
+    CUSTOM = "custom"
+}
+/**
+ * Result of cell validation
+ */
+export interface ValidationResult {
+    /**
+     * Whether the value is valid
+     */
+    valid: boolean;
+    /**
+     * Error message if validation failed
+     */
+    error?: string;
+    /**
+     * Field-specific error messages for complex validations
+     */
+    errors?: Record<string, string>;
+    /**
+     * Warning messages (non-blocking)
+     */
+    warnings?: string[];
+}
+/**
+ * Cell alignment options
+ */
+export declare enum CellAlignment {
+    LEFT = "left",
+    CENTER = "center",
+    RIGHT = "right"
+}
+/**
+ * Vertical alignment options
+ */
+export declare enum CellVerticalAlignment {
+    TOP = "top",
+    MIDDLE = "middle",
+    BOTTOM = "bottom"
+}
+/**
+ * Edit mode trigger options
+ */
+export declare enum EditMode {
+    /**
+     * Single click to edit
+     */
+    CLICK = "click",
+    /**
+     * Enter key to edit (requires keyboard navigation enabled)
+     */
+    ENTER = "enter",
+    /**
+     * Manual trigger (via API call)
+     */
+    MANUAL = "manual",
+    /**
+     * Never editable
+     */
+    NONE = "none"
+}
+/**
+ * Navigation key identifiers for keyboard navigation
+ */
+export declare enum NavigationKey {
+    /**
+     * Arrow up key
+     */
+    ARROW_UP = "ArrowUp",
+    /**
+     * Arrow down key
+     */
+    ARROW_DOWN = "ArrowDown",
+    /**
+     * Arrow left key
+     */
+    ARROW_LEFT = "ArrowLeft",
+    /**
+     * Arrow right key
+     */
+    ARROW_RIGHT = "ArrowRight",
+    /**
+     * Tab key
+     */
+    TAB = "Tab",
+    /**
+     * Enter key
+     */
+    ENTER = "Enter",
+    /**
+     * Escape key
+     */
+    ESCAPE = "Escape"
+}
+/**
+ * Navigation directions
+ */
+export declare enum NavigationDirection {
+    UP = "up",
+    DOWN = "down",
+    LEFT = "left",
+    RIGHT = "right"
+}
+/**
+ * Cell lifecycle states
+ */
+export declare enum CellLifecycleState {
+    /**
+     * Cell is displaying value
+     */
+    DISPLAY = "display",
+    /**
+     * Cell is in edit mode
+     */
+    EDITING = "editing",
+    /**
+     * Cell value is being validated
+     */
+    VALIDATING = "validating",
+    /**
+     * Cell value is being saved
+     */
+    SAVING = "saving",
+    /**
+     * Cell has error
+     */
+    ERROR = "error",
+    /**
+     * Cell is disabled
+     */
+    DISABLED = "disabled"
+}
+/**
+ * Generic cell event data
+ */
+export interface CellEvent<T = any> {
+    /**
+     * The cell value
+     */
+    value: T;
+    /**
+     * Previous value (for change events)
+     */
+    previousValue?: T;
+    /**
+     * Row data context
+     */
+    rowData?: any;
+    /**
+     * Column key
+     */
+    columnKey: string;
+    /**
+     * Row index
+     */
+    rowIndex?: number;
+    /**
+     * Native event if triggered by user interaction
+     */
+    originalEvent?: Event;
+}
+/**
+ * Type guard to check if value is null or undefined
+ */
+export declare function isNullOrUndefined(value: any): value is null | undefined;
+/**
+ * Type guard to check if value is a valid date
+ */
+export declare function isValidDate(value: any): value is Date;
+/**
+ * Type guard to check if validation result is valid
+ */
+export declare function isValidationSuccess(result: ValidationResult): boolean;
+/**
+ * Cell edit started event
+ * Emitted when a cell enters edit mode
+ */
+export interface CellEditEvent<T = any> {
+    /**
+     * The cell instance
+     */
+    cell: Cell<T>;
+    /**
+     * Current cell value
+     */
+    value: T;
+    /**
+     * Row data context
+     */
+    rowData: any;
+    /**
+     * Column key
+     */
+    columnKey: string;
+    /**
+     * Row index
+     */
+    rowIndex?: number;
+    /**
+     * Current cell state snapshot
+     */
+    cellState: CellState<T>;
+}
+/**
+ * Cell value saved event
+ * Emitted when a cell value is successfully saved after editing
+ */
+export interface CellSaveEvent<T = any> {
+    /**
+     * The cell instance
+     */
+    cell: Cell<T>;
+    /**
+     * New value after save
+     */
+    newValue: T;
+    /**
+     * Previous value before save
+     */
+    previousValue?: T;
+    /**
+     * Row data context
+     */
+    rowData: any;
+    /**
+     * Column key
+     */
+    columnKey: string;
+    /**
+     * Row index
+     */
+    rowIndex?: number;
+    /**
+     * Whether the saved value is valid
+     */
+    isValid: boolean;
+    /**
+     * Validation error messages if any
+     */
+    validationErrors?: string[];
+    /**
+     * Current cell state snapshot after save
+     */
+    cellState: CellState<T>;
+}
+/**
+ * Cell value changed event
+ * Emitted after a successful cell value change (after save and validation)
+ */
+export interface CellChangeEvent<T = any> {
+    /**
+     * The cell instance
+     */
+    cell: Cell<T>;
+    /**
+     * Old value before change
+     */
+    oldValue: T;
+    /**
+     * New value after change
+     */
+    newValue: T;
+    /**
+     * Row data context
+     */
+    rowData: any;
+    /**
+     * Column key
+     */
+    columnKey: string;
+    /**
+     * Row index
+     */
+    rowIndex?: number;
+    /**
+     * Whether the old value was valid
+     */
+    wasValid: boolean;
+    /**
+     * Whether the new value is valid
+     */
+    isValid: boolean;
+    /**
+     * Current cell state snapshot
+     */
+    cellState: CellState<T>;
+}
+/**
+ * Cell edit cancelled event
+ * Emitted when cell editing is cancelled without saving
+ */
+export interface CellCancelEvent<T = any> {
+    /**
+     * The cell instance
+     */
+    cell: Cell<T>;
+    /**
+     * Current value (unchanged)
+     */
+    value: T;
+    /**
+     * Previous value that was being edited
+     */
+    previousValue?: T;
+    /**
+     * Row data context
+     */
+    rowData: any;
+    /**
+     * Column key
+     */
+    columnKey: string;
+    /**
+     * Row index
+     */
+    rowIndex?: number;
+    /**
+     * Current cell state snapshot
+     */
+    cellState: CellState<T>;
+}

package/lib/models/column-action.interface.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Column action interface - defines actions that can be performed on table columns
+ * Similar to RowAction but for column-level operations
+ */
+import { ColumnConfig } from './column-config.interface';
+import { TableState } from '../renderer/models/table-state.class';
+/**
+ * Defines a single action that can be performed on a column
+ */
+export interface ColumnAction {
+    /**
+     * Unique identifier for the action
+     */
+    id: string;
+    /**
+     * Display label for the action
+     */
+    label: string;
+    /**
+     * Optional icon to display with the action
+     */
+    icon?: string;
+    /**
+     * Callback function executed when the action is clicked
+     * @param column - The column config
+     * @param columnIndex - The index of the column
+     */
+    action?: (column: ColumnConfig<any>, columnIndex: number) => void;
+    /**
+     * Whether the action should be hidden
+     * Can be a boolean or a function that returns boolean based on column state
+     */
+    hidden?: boolean | ((column: ColumnConfig<any>, columnIndex: number) => boolean);
+    /**
+     * Whether the action should be disabled
+     * Can be a boolean or a function that returns boolean based on column state
+     */
+    disabled?: boolean | ((column: ColumnConfig<any>, columnIndex: number) => boolean);
+}
+/**
+ * Context object passed to the column menu dropdown component
+ * Contains all information needed to render and handle column actions
+ */
+export interface ColumnActionContext {
+    /**
+     * The column configuration
+     */
+    column: ColumnConfig<any>;
+    /**
+     * The index of the column in the visible columns array
+     */
+    columnIndex: number;
+    /**
+     * Whether this is the first column
+     */
+    isFirstColumn: boolean;
+    /**
+     * Whether this is the last column
+     */
+    isLastColumn: boolean;
+    /**
+     * Table state for accessing sorting, filtering, etc.
+     */
+    tableState?: TableState;
+    /**
+     * Available actions for this column
+     */
+    actions: ColumnAction[];
+}
+/**
+ * Event emitted when a column action is clicked
+ */
+export interface ColumnActionEvent {
+    /**
+     * The action that was clicked
+     */
+    action: ColumnAction;
+    /**
+     * The column configuration
+     */
+    column: ColumnConfig<any>;
+    /**
+     * The index of the column
+     */
+    columnIndex: number;
+}