@aquera/ngx-smart-table 0.0.2-alpha

package/public-api.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Public API Surface of ngx-smart-table
+ * Cell Configuration Model exports
+ */
+export * from './lib/models/cell-types';
+export * from './lib/models/cell-strategies.interface';
+export * from './lib/renderer/models/cell-state.interface';
+export * from './lib/models/column-config.interface';
+export * from './lib/renderer/models/table-types';
+export * from './lib/renderer/models/table-state.interface';
+export * from './lib/renderer/models/table-state.class';
+export * from './lib/renderer/models/z-index.enum';
+export * from './lib/models/table-config.interface';
+export { DEFAULT_TABLE_CONFIG, mergeTableConfig } from './lib/models/table-config.interface';
+export * from './lib/models/row-action.interface';
+export * from './lib/models/column-action.interface';
+export * from './lib/models/sheet-config.interface';
+export * from './lib/models/sheet-action.interface';
+export * from './lib/renderer/models/sheet-state.interface';
+export * from './lib/renderer/models/sheet-state.class';
+export * from './lib/models/workbook-config.interface';
+export * from './lib/models/workbook-action.interface';
+export * from './lib/renderer/models/workbook-state.interface';
+export * from './lib/renderer/models/workbook-state.class';
+export * from './lib/renderer/models/cell.class';
+export * from './lib/models/base-column-config.class';
+export * from './lib/strategies/default-formatters';
+export * from './lib/strategies/default-validators';
+export * from './lib/renderer/models/row-validation-state.interface';
+export * from './lib/renderer/models/table-validation-state.interface';
+export * from './lib/strategies/default-editors';
+export * from './lib/editors/index';
+export * from './lib/factories/column-config.factory';
+export * from './lib/renderer/components/st-cell/st-cell.component';
+export * from './lib/renderer/components/st-table/st-table.component';
+export * from './lib/renderer/components/st-header/st-header.component';
+export * from './lib/renderer/components/st-column-menu/st-column-menu.component';
+export * from './lib/renderer/components/st-column-visibility/st-column-visibility.component';
+export * from './lib/renderer/components/st-column-filter/st-column-filter.component';
+export * from './lib/renderer/components/st-pagination/st-pagination.component';
+export * from './lib/renderer/components/st-add-column-button/st-add-column-button.component';
+export * from './lib/renderer/components/st-column-editor-modal/st-column-editor-modal.component';
+export * from './lib/renderer/components/st-table-actions/st-table-actions.component';
+export * from './lib/renderer/components/st-row-actions-dropdown/st-row-actions-dropdown.component';
+export * from './lib/renderer/components/st-sheet/st-sheet.component';
+export * from './lib/renderer/components/st-sheet-actions/st-sheet-actions.component';
+export * from './lib/renderer/components/st-workbook/st-workbook.component';
+export * from './lib/renderer/directives/click-outside.directive';
+export * from './lib/renderer/directives/st-column-resize.directive';
+export * from './lib/renderer/directives/st-keyboard-navigation.directive';
+export * from './lib/smart-table.module';
+export * from './lib/shared/shared-table-components.module';
+export * from './lib/builder/components/definition-builder/definition-builder.component';
+export * from './lib/builder/components/builder-toolbar/builder-toolbar.component';
+export * from './lib/builder/components/column-list/column-list.component';
+export * from './lib/builder/components/column-editor/column-editor.component';
+export * from './lib/builder/components/table-config-editor/table-config-editor.component';
+export * from './lib/builder/components/builder-preview/builder-preview.component';
+export * from './lib/builder/services/definition-builder.service';
+export * from './lib/builder/services/definition-export.service';
+export * from './lib/builder/services/definition-import.service';
+export * from './lib/builder/services/sample-data-generator.service';
+export * from './lib/builder/models/builder-state.interface';
+export * from './lib/builder/definition-builder.module';
+export * from './lib/services/json-schema-validator.service';
+export * from './lib/services/validation-logger.service';
+export * from './lib/services/row-validation.service';
+export * from './lib/services/virtual-scroll.service';
+export * from './lib/models/autosave-config.interface';
+export * from './lib/services/autosave.service';

package/src/lib/builder/README.md

@@ -0,0 +1,30 @@
+# Definition Builder Module
+
+The Definition Builder provides a visual UI for creating and managing Smart Table configurations.
+
+## Usage
+
+To use the Definition Builder, import both `SmartTableModule` and `DefinitionBuilderModule` in your application:
+
+```typescript
+import { SmartTableModule, DefinitionBuilderModule } from 'ngx-smart-table';
+
+@NgModule({
+  imports: [
+    SmartTableModule,      // Required for preview component
+    DefinitionBuilderModule
+  ]
+})
+export class AppModule { }
+```
+
+Then use the builder component in your template:
+
+```html
+<st-definition-builder></st-definition-builder>
+```
+
+## Note
+
+`SmartTableModule` must be imported alongside `DefinitionBuilderModule` because the preview component (`st-builder-preview`) uses the `st-table` component for live preview.
+

package/src/lib/editors/README.md

@@ -0,0 +1,303 @@
+# Custom Editors
+
+This folder contains custom cell editors for the ngx-smart-table demo.
+
+## Creating Custom Editors
+
+Custom editors can be created by implementing the `CellEditor<T>` interface from `ngx-smart-table`.
+
+### Example: NileInputEditor
+
+The `NileInputEditor` demonstrates how to use custom web components (from `@aquera/nile-elements`) as cell editors.
+
+**Important:** NileInput uses custom events that replace their native counterparts:
+- `nile-blur` replaces `blur`
+- `nile-focus` replaces `focus`
+- `nile-input` replaces `input`
+- `nile-change` replaces `change`
+- Standard keyboard events (`keydown`, `keyup`, etc.) still work normally
+
+#### Features
+
+- ✅ **Generic type support** - Type-safe with `<T>` parameter (defaults to `string`)
+- ✅ **Full NileInput API support** - All NileInput properties configurable via options
+- ✅ **Built-in validation** - Validates before saving with `checkValidity()` and `reportValidity()`
+- ✅ **Type-aware values** - Returns proper types for number, date, and text inputs
+- ✅ **Clear button support** - Optional clearable input with `nile-clear` event handling
+- ✅ **Proper cleanup** - All event listeners tracked and removed on destroy
+- ✅ **Mobile-friendly** - Uses `enterkeyhint: 'done'` by default for better mobile UX
+- ✅ **Real-time updates** - Triggers `onChange` during typing via `nile-input` event
+- ✅ **Visual states** - Support for error, warning, success states
+- ✅ **Style variants** - Filled and pill styles available
+
+```typescript
+import { CellEditor, CellEditorContext } from 'ngx-smart-table';
+import { NileInput } from '@aquera/nile-elements';
+import { NileInputEditorOptions } from './nile-input-editor';
+
+export class NileInputEditor<T = string> implements CellEditor<T> {
+  private input?: NileInput;
+
+  constructor(options?: NileInputEditorOptions) {}
+
+  edit(context: CellEditorContext<T>): void {
+    // 1. Create your custom element
+    this.input = new NileInput();
+    this.input.value = String(context.value ?? '');
+    
+    // 2. Apply all options
+    this.applyOptions();
+    
+    // 3. Set up event handlers
+    // ✅ Use keydown (still works - not replaced)
+    this.input.addEventListener('keydown', (e: KeyboardEvent) => {
+      if (e.key === 'Enter') this.saveValue(context, true);
+      if (e.key === 'Escape') context.onCancel();
+    });
+    
+    // ✅ Use custom nile-blur event (replaces blur)
+    this.input.addEventListener('nile-blur', (e: Event) => {
+      const customEvent = e as CustomEvent;
+      if (this.input?.checkValidity()) {
+        context.onSave(customEvent.detail.value);
+      }
+    });
+    
+    // Optional: Real-time updates
+    this.input.addEventListener('nile-input', (e: Event) => {
+      const customEvent = e as CustomEvent;
+      context.onChange(customEvent.detail.value);
+    });
+    
+    // 4. Render in the container
+    context.container.appendChild(this.input);
+    this.input.focus();
+  }
+
+  destroy(): void {
+    // Cleanup all event listeners
+    this.input?.remove();
+  }
+}
+```
+
+### Using Custom Editors in Column Config
+
+```typescript
+import { Columns } from 'ngx-smart-table';
+import { NileInputEditor } from '../editors';
+
+export const columns = [
+  // Basic text input (generic type defaults to string)
+  Columns.text('name', {
+    header: 'Name',
+    editable: true,
+    editor: new NileInputEditor({
+      placeholder: 'Enter name',
+      maxLength: 100,
+      required: true,
+      validateOnSave: true
+    })
+  }),
+  
+  // Email input with validation
+  Columns.text('email', {
+    header: 'Email',
+    editable: true,
+    editor: new NileInputEditor({
+      type: 'email',
+      placeholder: 'user@example.com',
+      required: true,
+      pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+      errorMessage: 'Please enter a valid email address'
+    })
+  }),
+  
+  // Number input with range (explicitly typed as number)
+  Columns.number('age', {
+    header: 'Age',
+    editable: true,
+    editor: new NileInputEditor<number>({
+      type: 'number',
+      min: 18,
+      max: 120,
+      step: 1,
+      required: true
+    })
+  }),
+  
+  // Input with clear button and filled style
+  Columns.text('notes', {
+    header: 'Notes',
+    editable: true,
+    editor: new NileInputEditor({
+      placeholder: 'Add notes...',
+      clearable: true,
+      filled: true,
+      maxLength: 500
+    })
+  }),
+  
+  // Phone number with custom input mode
+  Columns.text('phone', {
+    header: 'Phone',
+    editable: true,
+    editor: new NileInputEditor({
+      type: 'tel',
+      placeholder: '+1 (555) 000-0000',
+      inputmode: 'tel',
+      pattern: '^\\+?[1-9]\\d{1,14}$'
+    })
+  })
+];
+```
+
+## CellEditor Interface
+
+```typescript
+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;
+}
+```
+
+## NileInputEditorOptions
+
+Complete configuration interface for NileInputEditor:
+
+```typescript
+interface NileInputEditorOptions {
+  // Basic properties
+  placeholder?: string;              // Placeholder text
+  maxLength?: number;                // Maximum character length
+  minLength?: number;                // Minimum character length
+  autoFocus?: boolean;               // Auto-focus on edit (default: true)
+  selectOnFocus?: boolean;           // Select text on focus (default: true)
+  type?: 'text' | 'email' | 'tel' | 'url' | 'search' | 'number' | 'password' | 'date' | 'time' | 'datetime-local';
+  size?: 'small' | 'medium' | 'large';  // Input size (default: 'medium')
+  
+  // Style options
+  filled?: boolean;                  // Filled background style
+  pill?: boolean;                    // Rounded pill style
+  
+  // Behavior options
+  clearable?: boolean;               // Show clear button
+  disabled?: boolean;                // Disable input
+  readonly?: boolean;                // Make readonly
+  required?: boolean;                // Required field
+  
+  // Validation
+  pattern?: string;                  // Regex pattern for validation
+  min?: number | string;             // Minimum value (number/date types)
+  max?: number | string;             // Maximum value (number/date types)
+  step?: number | 'any';             // Step increment (number type)
+  
+  // Visual states
+  warning?: boolean;                 // Warning state styling
+  error?: boolean;                   // Error state styling
+  success?: boolean;                 // Success state styling
+  errorMessage?: string;             // Error message text
+  helpText?: string;                 // Help text below input
+  
+  // Advanced options
+  enterkeyhint?: 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';
+  spellcheck?: boolean;              // Enable spell checking
+  autocomplete?: string;             // Autocomplete attribute
+  inputmode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
+  
+  // Validation behavior
+  validateOnSave?: boolean;          // Validate before saving (default: true)
+}
+```
+
+## CellEditorContext
+
+The context object passed to `edit()` contains:
+
+- `value: T` - Current cell value
+- `rowData: any` - Full row data
+- `columnKey: string` - Column identifier
+- `rowIndex: number` - Row index
+- `container: HTMLElement` - DOM element to render the editor in
+- `onChange: (newValue: T) => void` - Real-time change callback
+- `onSave: (newValue: T) => void` - Save and exit edit mode
+- `onCancel: () => void` - Cancel editing and restore original value
+
+## Best Practices
+
+1. **Always check for container**: Ensure `context.container` exists before rendering
+2. **Handle keyboard events**: Support Enter (save) and Escape (cancel)
+3. **Clean up in destroy()**: Remove event listeners and DOM elements
+4. **Auto-focus**: Focus the editor element after rendering
+5. **Style appropriately**: Set width/height to fit the cell
+6. **Use correct events**: If using custom elements with custom events, use those instead of native events
+
+## NileInput Custom Events
+
+NileInput from `@aquera/nile-elements` uses custom events that replace native DOM events:
+
+| Custom Event | Replaces | Detail | Usage |
+|--------------|----------|--------|-------|
+| `nile-blur` | `blur` | `{ value }` | Input lost focus - use for saving |
+| `nile-focus` | `focus` | `{ value }` | Input gained focus |
+| `nile-input` | `input` | `{ value }` | Value updated on each keystroke |
+| `nile-change` | `change` | `{ value }` | Committed change (includes clear) |
+| `nile-clear` | N/A | `{ value: '' }` | Clear button clicked |
+| `nile-init` | N/A | N/A | Component connected/initialized |
+| `nile-after-init` | N/A | N/A | After initial render/setup |
+| `nile-destroy` | N/A | N/A | Component disconnected/cleanup |
+| `nile-value-marked` | N/A | marked value + flags | Non-printable chars marked |
+
+**Note:** Standard keyboard events (`keydown`, `keyup`, `keypress`) are NOT replaced and work normally.
+
+### Example with Multiple Events
+
+```typescript
+edit(context: CellEditorContext<string>): void {
+  this.input = new NileInput();
+  this.input.value = context.value ?? '';
+
+  // Keyboard events still work
+  this.input.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key === 'Enter') context.onSave(this.input!.value);
+    if (e.key === 'Escape') context.onCancel();
+  });
+
+  // Use custom events
+  this.input.addEventListener('nile-blur', (e: Event) => {
+    const customEvent = e as CustomEvent;
+    context.onSave(customEvent.detail.value);
+  });
+
+  this.input.addEventListener('nile-input', (e: Event) => {
+    const customEvent = e as CustomEvent;
+    context.onChange(customEvent.detail.value); // Real-time updates
+  });
+
+  this.input.addEventListener('nile-clear', (e: Event) => {
+    const customEvent = e as CustomEvent;
+    context.onSave(''); // Handle clear button
+  });
+
+  context.container.appendChild(this.input);
+  this.input.focus();
+}
+```

package/src/lib/renderer/components/st-column-filter/README.md

@@ -0,0 +1,286 @@
+# StColumnFilterComponent - Nile Elements Integration
+
+## Overview
+
+The `StColumnFilterComponent` has been refactored to use Nile Elements components for a consistent, modern UI. It's now designed as a shared component that can accept context-based inputs.
+
+## Key Changes
+
+### 1. **Nile Components Integration**
+- Replaced native HTML inputs with `nile-input`
+- Replaced native selects with `nile-select` and `nile-option`
+- Replaced native checkboxes with `nile-checkbox`
+- Replaced native buttons with `nile-button`
+- Wrapped everything in `nile-popover` for better positioning and control
+
+### 2. **Context-Based Architecture**
+Added `FilterContext` interface for flexible component usage:
+
+```typescript
+export interface FilterContext {
+  column: ColumnConfig<any>;
+  tableState?: TableState;
+  columnIndex: number;
+  isFirstColumn: boolean;
+  isLastColumn: boolean;
+}
+```
+
+### 3. **New Event Emitters**
+- `@Output() filterApplied` - Emits when filter is applied with operator and value
+- `@Output() filterCleared` - Emits when filter is cleared
+- `@Output() closed` - Existing event, emits when popover closes
+
+## Usage
+
+### Traditional Usage (Individual Inputs)
+```typescript
+<st-column-filter
+  [column]="columnConfig"
+  [tableState]="tableState"
+  [columnIndex]="0"
+  [isFirstColumn]="true"
+  [isLastColumn]="false"
+  (filterApplied)="onFilterApplied($event)"
+  (filterCleared)="onFilterCleared()"
+  (closed)="onFilterClosed()">
+</st-column-filter>
+```
+
+### Context-Based Usage (Shared Component Pattern)
+```typescript
+// Define context
+const filterContext: FilterContext = {
+  column: columnConfig,
+  tableState: this.tableState,
+  columnIndex: 0,
+  isFirstColumn: true,
+  isLastColumn: false
+};
+
+// Use in template
+<st-column-filter
+  [filterContext]="filterContext"
+  (filterApplied)="onFilterApplied($event)"
+  (filterCleared)="onFilterCleared()">
+</st-column-filter>
+```
+
+## Nile Component Event Handlers
+
+The component now uses Nile Elements custom events:
+
+| Nile Component | Event | Handler Method |
+|----------------|-------|----------------|
+| `nile-popover` | `nile-hide` | `onPopoverHide()` |
+| `nile-select` | `nile-change` | `onOperatorChange($event)` / `onSelectChange($event)` |
+| `nile-input` | `nile-input` | `onValueInput($event)` |
+| `nile-checkbox` | `nile-change` | `onCheckboxChange($event)` / `onMultiselectCheckboxChange($event, value)` |
+| `nile-button` | `click` | `onApply()` / `onClear()` |
+
+## Event Details Structure
+
+### nile-change (select/checkbox)
+```typescript
+{
+  detail: {
+    value: any,      // For select
+    checked: boolean // For checkbox
+  }
+}
+```
+
+### nile-input
+```typescript
+{
+  detail: {
+    value: string
+  }
+}
+```
+
+### filterApplied Output
+```typescript
+{
+  operator: FilterOperator,
+  value: any
+}
+```
+
+## Filter Input Types
+
+The component automatically renders appropriate Nile components based on data type:
+
+| Data Type | Nile Component | Description |
+|-----------|----------------|-------------|
+| `text` | `nile-input[type="text"]` | Text input with operators |
+| `number` | `nile-input[type="number"]` | Number input with comparison operators |
+| `date` | `nile-input[type="date"]` | Date picker with before/after operators |
+| `checkbox` | `nile-checkbox` | Boolean toggle |
+| `select` | `nile-select` | Single selection dropdown |
+| `multiselect` | Multiple `nile-checkbox` | Multiple selection with checkboxes |
+
+## Styling
+
+### CSS Parts (Shadow DOM)
+The component uses Nile Elements' CSS parts for customization:
+
+```scss
+// Customize popover
+st-column-filter::part(popover) {
+  min-width: 320px;
+}
+
+// Customize inputs
+st-column-filter nile-input::part(base) {
+  width: 100%;
+}
+
+// Customize buttons
+st-column-filter nile-button::part(base) {
+  min-width: 80px;
+}
+```
+
+### Component SCSS Classes
+Internal classes for layout:
+
+- `.st-column-filter-popover` - Wrapper class
+- `.filter-content` - Main content container
+- `.filter-value-section` - Value input area
+- `.filter-multiselect` - Multiselect container
+- `.filter-actions` - Button area
+
+## Programmatic Control
+
+### Opening the Filter
+```typescript
+@ViewChild(StColumnFilterComponent) filterComponent!: StColumnFilterComponent;
+
+openFilter() {
+  this.filterComponent.open();
+}
+```
+
+### Closing the Filter
+```typescript
+closeFilter() {
+  this.filterComponent.close();
+}
+```
+
+### Getting Filter Context
+```typescript
+const context = this.filterComponent.context;
+console.log('Current column:', context.column.key);
+```
+
+## Migration Guide
+
+If you're migrating from the old HTML-based filter:
+
+### Before (Native HTML)
+```html
+<input type="text" [(ngModel)]="filterValue">
+<button (click)="onApply()">Apply</button>
+```
+
+### After (Nile Components)
+```html
+<nile-input 
+  [value]="filterValue"
+  (nile-input)="onValueInput($event)">
+</nile-input>
+<nile-button (click)="onApply()">Apply</nile-button>
+```
+
+### Event Handler Updates
+```typescript
+// Old: Direct ngModel binding
+// filterValue is automatically updated
+
+// New: Event handler
+onValueInput(event: Event): void {
+  const customEvent = event as CustomEvent;
+  this.filterValue = customEvent.detail.value;
+}
+```
+
+## Best Practices
+
+1. **Use Context Pattern** for shared/reusable filters
+2. **Listen to Events** - Use `filterApplied` and `filterCleared` for logging/analytics
+3. **Customize via CSS Parts** - Use Nile's shadow DOM parts for theming
+4. **Programmatic Control** - Use `open()`/`close()` methods for complex UX flows
+
+## Examples
+
+### Complete Example with All Features
+```typescript
+@Component({
+  template: `
+    <st-column-filter
+      [filterContext]="getFilterContext(column)"
+      (filterApplied)="logFilterApplied($event)"
+      (filterCleared)="logFilterCleared()"
+      (closed)="onFilterUIClosed()">
+    </st-column-filter>
+  `
+})
+export class MyComponent {
+  getFilterContext(column: ColumnConfig): FilterContext {
+    return {
+      column,
+      tableState: this.tableState,
+      columnIndex: this.getColumnIndex(column),
+      isFirstColumn: this.isFirst(column),
+      isLastColumn: this.isLast(column)
+    };
+  }
+  
+  logFilterApplied(event: { operator: FilterOperator; value: any }) {
+    console.log(`Filter applied: ${event.operator} = ${event.value}`);
+    // Send to analytics, etc.
+  }
+  
+  logFilterCleared() {
+    console.log('Filter cleared');
+  }
+  
+  onFilterUIClosed() {
+    console.log('Filter UI closed');
+  }
+}
+```
+
+## Troubleshooting
+
+### Popover Not Showing
+- Ensure `isOpen` is set to `true`
+- Check that the anchor element is in the DOM
+- Verify Nile Elements are properly imported: `import '@aquera/nile-elements'`
+
+### Events Not Firing
+- Make sure you're using custom event handlers (e.g., `nile-change`, not `change`)
+- Cast events to `CustomEvent` to access `detail` property
+- Check browser console for any Nile Elements errors
+
+### Styling Issues
+- Use `::part()` pseudo-element for shadow DOM styling
+- Check that CSS imports are correct
+- Verify SCSS variables are available
+
+## Dependencies
+
+- `@aquera/nile-elements` - Required for all Nile components
+- Angular forms (FormsModule) - For ngModel directives
+- RxJS - For observable subscriptions (TableState)
+
+## Browser Compatibility
+
+Works with all browsers that support:
+- Web Components (Custom Elements)
+- Shadow DOM
+- ES6+
+
+See Nile Elements documentation for specific browser support matrix.