ngx-lite-form 1.3.2 → 1.3.4

package/README.md

@@ -1,22 +1,22 @@
 # Lite Form: A Lightweight and Powerful Angular Form Library
 
-**Lite Form is a comprehensive, open-source library of 12+ standalone components for building modern, reactive forms in Angular (v17+). It provides lightweight, customizable, and fully-typed form controls—from basic inputs to advanced data tables—designed to accelerate development and improve user experience.**
+**Lite Form is a comprehensive, open-source library of 13+ standalone components for building modern, reactive forms in Angular (v20+). It provides lightweight, customizable, and fully-typed form controls—from basic inputs to advanced data tables and loading indicators—designed to accelerate development and improve user experience.**
 
 This library is built for developers who need a robust, out-of-the-box solution for form-heavy applications without the overhead of heavy-weight dependencies. All components are standalone, tree-shakable, and integrate seamlessly with Angular's Reactive Forms module.
 
 ## Why Choose Lite Form?
 
-- **🚀 Accelerate Development**: Get a complete suite of form controls ready to use, including complex components like date pickers, file uploads, and data tables. Drastically reduce boilerplate code.
-- **💎 Lightweight & Performant**: Built with modern Angular practices. All components are standalone and tree-shakable, ensuring a minimal bundle size.
-- **✅ Fully Typed & Integrated**: Enjoy excellent developer experience with fully-typed APIs for all components and Data Transfer Objects (DTOs), ensuring type safety and easier integration.
-- **🎨 Highly Customizable**: While providing a clean default UI, the library is designed for easy styling. A clear SCSS structure and BEM-style classes allow for deep customization to match your brand.
-- **🔒 Secure & Accessible**: Components are built with security and accessibility (ARIA) in mind, including advanced password strength analysis and accessible form field structures.
+- **Accelerate Development**: Get a complete suite of form controls ready to use, including complex components like date pickers, file uploads, and data tables. Drastically reduce boilerplate code.
+- **Lightweight & Performant**: Built with modern Angular practices. All components are standalone and tree-shakable, ensuring a minimal bundle size.
+- **Fully Typed & Integrated**: Enjoy excellent developer experience with fully-typed APIs for all components and Data Transfer Objects (DTOs), ensuring type safety and easier integration.
+- **Highly Customizable**: While providing a clean default UI, the library is designed for easy styling. A clear SCSS structure and BEM-style classes allow for deep customization to match your brand.
+- **Secure & Accessible**: Components are built with security and accessibility (ARIA) in mind, including advanced password strength analysis and accessible form field structures.
 
 ## Live Demo
 
 Experience Lite Form in action with our interactive live demo on StackBlitz. Test out all the components and see how they work in a real Angular application.
 
-[**🚀 Launch Live Demo on StackBlitz**](https://stackblitz.com/edit/angular-ivy-hfgxpd?file=src%2Fapp%2Fapp.ts)
+[**Launch Live Demo on StackBlitz**](https://stackblitz.com/~/github.com/liangk/lite-form)
 
 
 ## Use Cases
@@ -30,60 +30,64 @@ Lite Form is ideal for a wide range of applications, including but not limited t
 - **Internal Tools**: Rapidly prototype and build internal tools for data collection and management.
 
 ## Features
-- ✅ **Modern Angular 20+** - Built with standalone components, signals, and latest CLI tooling
-- ✅ **TypeScript Support** - Fully typed with generic support and DTO helpers
-- ✅ **Reactive Forms** - Integrated with Angular Reactive Forms
-- ✅ **Built-in Validation** - Form validation with error messages and utilities
-- ✅ **Password Security** - Advanced password validation and strength analysis
-- ✅ **Date Handling** - Single date and date range selection with custom formatting
-- ✅ **File Upload** - Drag & drop file upload with camera capture and file management
-- ✅ **Panels & Dialogs** - Template-driven modal panels with configurable action buttons
-- ✅ **Data Tables** - Flexible table component with custom columns, sorting, and pagination
-- ✅ **Pagination** - Standalone pagination component with customizable navigation
-- ✅ **Customizable Styling** - Space-saving SCSS style guide for consistent overrides
-- ✅ **Accessibility** - ARIA-compliant form controls
-- ✅ **Animations** - Smooth transitions and interactions
+- **Modern Angular 20+** - Built with standalone components, signals, and latest CLI tooling
+- **TypeScript Support** - Fully typed with generic support and DTO helpers
+- **Reactive Forms** - Integrated with Angular Reactive Forms
+- **Built-in Validation** - Form validation with error messages and utilities
+- **Password Security** - Advanced password validation and strength analysis
+- **Date Handling** - Single date and date range selection with custom formatting
+- **File Upload** - Drag & drop file upload with camera capture and file management
+- **Panels & Dialogs** - Modal panels supporting string, template, or component content with configurable action buttons
+- **Data Tables** - Flexible table component with custom columns, sorting, and pagination
+- **Pagination** - Standalone pagination component with customizable navigation
+- **Loading Indicators** - Spinner and progress bar components with defined/indeterminate states
+- **Customizable Styling** - Space-saving SCSS style guide for consistent overrides
+- **Accessibility** - ARIA-compliant form controls
+- **Animations** - Smooth transitions and interactions
 
 ## Components
 
-### 🎯 LiteInput
+### LiteInput
 Basic text input component with floating labels and validation.
 
-### 🔐 LitePassword
+### LitePassword
 Password input component with toggle visibility, strength indicator, and advanced validation features.
 
-### 📝 LiteTextarea  
+### LiteTextarea  
 Multi-line text input with auto-resize capabilities.
 
-### 📋 LiteSelect
+### LiteSelect
 Single-selection dropdown with search and filtering.
 
-### ☑️ LiteMultiSelect
+### LiteMultiSelect
 Multi-selection dropdown with inline selected items display and dynamic height adjustment.
 
-### 🔘 LiteRadio
+### LiteRadio
 Radio button group component for single selection from multiple options.
 
-### ✅ LiteCheckbox
+### LiteCheckbox
 Checkbox component for boolean input with validation support.
 
-### 📅 LiteDate
+### LiteDate
 Advanced date picker component with single date and date range selection, custom formatting, and intelligent calendar positioning.
 
-### 📎 LiteFile
+### LiteFile
 File upload component with drag & drop, badge, file management panel, and camera capture support.
 
-### 📅 LiteDateTime
+### LiteDateTime
 Date and time picker with timezone-safe handling and consistent formatting utilities.
 
-### 📊 LiteTable
+### LiteTable
 Flexible data table component with custom columns, cell templates, nested property access, and integrated pagination.
 
-### 📄 LitePaginator
+### LitePaginator
 Standalone pagination component with customizable page navigation, items per page selection, and total item display.
 
-### 🪟 LitePanel
-Modal-style panel component that renders custom templates, configurable header text, and action buttons via `LitePanelAction` definitions. Supports custom `width`, `height`, `maxWidth`, and `maxHeight` inputs with automatic `px` suffix for numeric values.
+### LitePanel
+Modal-style panel component that renders string content, Angular templates, or dynamic components. Supports configurable header text and action buttons via `LitePanelAction` definitions. Accepts custom `width`, `height`, `maxWidth`, and `maxHeight` inputs with automatic `px` suffix for numeric values.
+
+### LiteLoading
+Loading indicator component with view toggle for spinner (loading wheel) or progress bar modes. Supports defined progress percentage (0-100) or indeterminate animation, optional message display, and configurable spinner sizes (small, medium, large).
 
 ---
 
@@ -111,7 +115,8 @@ import {
   LiteFile,
   LiteTable,
   LitePaginator,
-  LitePanel
+  LitePanel,
+  LiteLoading
 } from 'ngx-lite-form';
 import { FormControl, Validators } from '@angular/forms';
 
@@ -141,7 +146,8 @@ import {
     LiteDateTime,
     LiteFile,
     LiteTable,
-    LitePaginator
+    LitePaginator,
+    LiteLoading
   ],
   templateUrl: './app.component.html',
   styleUrl: './app.component.scss'
@@ -308,6 +314,27 @@ export class AppComponent {
   <p>Panel content can render any Angular template.</p>
   <button type="button" (click)="close('acknowledged')">Acknowledge</button>
 </ng-template>
+
+<!-- Loading Indicators -->
+<!-- Spinner (default) -->
+<lite-loading [message]="'Loading data...'"></lite-loading>
+
+<!-- Spinner with size -->
+<lite-loading [size]="'large'" [message]="'Processing...'"></lite-loading>
+
+<!-- Progress bar with defined percentage -->
+<lite-loading 
+  [view]="'progress'" 
+  [progress]="75" 
+  [message]="'Uploading files...'"></lite-loading>
+
+<!-- Indeterminate progress bar -->
+<lite-loading 
+  [view]="'progress'" 
+  [message]="'Processing your request...'"></lite-loading>
+
+<!-- Controlled visibility -->
+<lite-loading [visible]="isLoading" [message]="'Please wait...'"></lite-loading>
 ```
 ---
 
@@ -657,6 +684,220 @@ onRowMenuAction(event: { action: string; row: any }) {
 <lite-table [table]="table" (menuAction)="onRowMenuAction($event)"></lite-table>
 ```
 
+### LitePanel Component
+
+**Selector:** `lite-panel`
+
+| Input | Type | Default | Description |
+| :---- | :--- | :------ | :---------- |
+| `title` | `string \| null` | `null` | Panel header title text |
+| `content` | `string \| TemplateRef \| Type<any> \| null` | `null` | Content to display: string, template, or component |
+| `contentInputs` | `Record<string, any> \| null` | `null` | Inputs to pass to dynamic component content |
+| `actions` | `LitePanelAction[] \| null` | `null` | Action buttons (defaults to single OK button) |
+| `closeOnOverlayClick` | `boolean` | `true` | Whether clicking backdrop closes the panel |
+| `width` | `string \| number \| null` | `null` | Panel width (numeric values get px suffix) |
+| `height` | `string \| number \| null` | `null` | Panel height (numeric values get px suffix) |
+| `maxWidth` | `string \| number \| null` | `null` | Maximum panel width |
+| `maxHeight` | `string \| number \| null` | `null` | Maximum panel height |
+
+| Output | Type | Description |
+| :----- | :--- | :---------- |
+| `closed` | `unknown \| null` | Emitted when panel closes with action value or null |
+
+**Features:**
+- Three content types: string, Angular template, or dynamic component
+- Configurable action buttons with variants (primary, secondary, danger)
+- Customizable dimensions with automatic px suffix for numbers
+- Backdrop click to close (configurable)
+- Close button in header
+- Component content with input binding support
+- Accessible with ARIA attributes
+
+**String Content Example:**
+```typescript
+panelOpen = signal(false);
+
+openPanel() {
+  this.panelOpen.set(true);
+}
+
+onPanelClosed(result: unknown | null) {
+  this.panelOpen.set(false);
+}
+```
+
+```html
+@if (panelOpen()) {
+  <lite-panel
+    [title]="'Information'"
+    [content]="'This is simple text content.'"
+    (closed)="onPanelClosed($event)">
+  </lite-panel>
+}
+```
+
+**Template Content Example:**
+```typescript
+panelActions: LitePanelAction[] = [
+  { label: 'Confirm', value: 'confirm', variant: 'primary' },
+  { label: 'Cancel', value: null, variant: 'secondary' }
+];
+```
+
+```html
+@if (panelOpen()) {
+  <lite-panel
+    [title]="'Confirmation'"
+    [content]="confirmTemplate"
+    [actions]="panelActions"
+    width="500px"
+    (closed)="onPanelClosed($event)">
+  </lite-panel>
+}
+
+<ng-template #confirmTemplate let-close="close">
+  <p>Are you sure you want to proceed?</p>
+  <button (click)="close('custom-value')">Custom Action</button>
+</ng-template>
+```
+
+**Component Content Example:**
+```typescript
+import { Component, Type } from '@angular/core';
+import { FormControl, Validators } from '@angular/forms';
+import { LiteInput, FieldDto } from 'ngx-lite-form';
+
+// Create a standalone component for panel content
+@Component({
+  selector: 'user-form',
+  standalone: true,
+  imports: [LiteInput],
+  template: `
+    <div class="form-content">
+      <p>Fill out the form below:</p>
+      <lite-input [control]="nameField"></lite-input>
+      <lite-input [control]="emailField"></lite-input>
+    </div>
+  `
+})
+export class UserFormComponent {
+  nameField = new FieldDto('Name', new FormControl('', [Validators.required]));
+  emailField = new FieldDto('Email', new FormControl('', [Validators.required, Validators.email]));
+}
+
+// In your main component
+userFormComponent: Type<any> = UserFormComponent;
+panelActions: LitePanelAction[] = [
+  { label: 'Submit', value: 'submit', variant: 'primary' },
+  { label: 'Cancel', value: null, variant: 'secondary' }
+];
+```
+
+```html
+@if (panelOpen()) {
+  <lite-panel
+    [title]="'User Registration'"
+    [content]="userFormComponent"
+    [actions]="panelActions"
+    width="600px"
+    maxHeight="80vh"
+    (closed)="onPanelClosed($event)">
+  </lite-panel>
+}
+```
+
+**Passing Inputs to Component Content:**
+```typescript
+// Component with inputs
+@Component({...})
+export class DataViewComponent {
+  @Input() userId!: number;
+  @Input() mode!: string;
+}
+
+// Usage
+componentInputs = { userId: 123, mode: 'edit' };
+```
+
+```html
+<lite-panel
+  [content]="dataViewComponent"
+  [contentInputs]="componentInputs"
+  (closed)="onPanelClosed($event)">
+</lite-panel>
+```
+
+### LiteLoading Component
+
+**Selector:** `lite-loading`
+
+| Input      | Type                            | Default     | Description                                                  |
+| :--------- | :------------------------------ | :---------- | :----------------------------------------------------------- |
+| `view`     | `'spinner' \| 'progress'`       | `'spinner'` | The view type: spinner for loading wheel, progress for bar. |
+| `progress` | `number \| undefined`           | `undefined` | Progress percentage (0-100). Undefined shows indeterminate.  |
+| `message`  | `string \| undefined`           | `undefined` | Optional message to display below the indicator.             |
+| `size`     | `'small' \| 'medium' \| 'large'`| `'medium'`  | Size of the spinner (only applies to spinner view).          |
+| `visible`  | `boolean`                       | `true`      | Whether the loading indicator is visible.                    |
+
+**Features:**
+- View toggle between spinner (loading wheel) and progress bar
+- Defined progress with percentage display (0-100%)
+- Indeterminate progress with animated sliding bar
+- Three spinner sizes: small, medium, large
+- Optional message display below indicator
+- Visibility control for conditional rendering
+- Smooth animations and transitions
+- Accessible with ARIA attributes
+
+**Example:**
+```typescript
+// Component
+import { signal } from '@angular/core';
+
+isLoading = signal(true);
+uploadProgress = signal(0);
+
+// Simulate progress
+startUpload() {
+  this.uploadProgress.set(0);
+  const interval = setInterval(() => {
+    const current = this.uploadProgress();
+    if (current >= 100) {
+      clearInterval(interval);
+      this.isLoading.set(false);
+    } else {
+      this.uploadProgress.set(current + 10);
+    }
+  }, 300);
+}
+```
+
+```html
+<!-- Basic spinner -->
+<lite-loading></lite-loading>
+
+<!-- Spinner with message and size -->
+<lite-loading 
+  [size]="'large'" 
+  [message]="'Loading data...'"></lite-loading>
+
+<!-- Defined progress bar -->
+<lite-loading 
+  [view]="'progress'" 
+  [progress]="uploadProgress()" 
+  [message]="'Uploading files...'"></lite-loading>
+
+<!-- Indeterminate progress bar -->
+<lite-loading 
+  [view]="'progress'" 
+  [message]="'Processing your request...'\"></lite-loading>
+
+<!-- Controlled visibility -->
+<lite-loading 
+  [visible]="isLoading()" 
+  [message]="'Please wait...'"></lite-loading>
+```
+
 ### LitePaginator Component
 
 **Selector:** `lite-paginator`
@@ -888,4 +1129,4 @@ This project is licensed under the MIT License - see the [LICENSE](https://githu
 ---
 
 ## Changelog
-- See [docs/CHANGELOG.md](https://github.com/liangk/lite-form/blob/main/docs/CHANGELOG.md) for the full historical record, including the latest `v1.3.2` release adding `LiteTable` single-action button rendering for one-item menus and neutral default styling (with optional `danger` variant).
+- See [docs/CHANGELOG.md](https://github.com/liangk/lite-form/blob/main/docs/CHANGELOG.md) for the full historical record, including the latest `v1.3.3` release adding the `LiteLoading` component with spinner and progress bar views.