@aquera/ngx-smart-table 0.0.17-alpha → 0.0.19-alpha

package/src/lib/editors/README.md

@@ -1,303 +0,0 @@
-# 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

@@ -1,286 +0,0 @@
-# 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.