ngx-st-qty-input 18.0.0 → 18.0.1

package/README.md

@@ -1,24 +1,569 @@
-# NgxStQtyInput
+# Quantity Input Component - Complete Documentation
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 14.2.0.
+## Table of Contents
+- [Overview](#overview)
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Inputs](#inputs)
+- [Outputs](#outputs)
+- [Usage Examples](#usage-examples)
+- [Best Practices](#best-practices)
 
-## Code scaffolding
+---
 
-Run `ng generate component component-name --project ngx-st-qty-input` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ngx-st-qty-input`.
-> Note: Don't forget to add `--project ngx-st-qty-input` or else it will be added to the default project in your `angular.json` file. 
+## Overview
 
-## Build
+The `ngx-st-qty-input` component is a quantity selector with increment/decrement buttons. Features include:
+- Plus/minus buttons for incrementing/decrementing values
+- Direct numeric input
+- Negative value support (optional)
+- Two-way data binding with model
+- Disabled state support
+- Error state display
+- Change event emission
 
-Run `ng build ngx-st-qty-input` to build the project. The build artifacts will be stored in the `dist/` directory.
+---
 
-## Publishing
+## Installation
 
-After building your library with `ng build ngx-st-qty-input`, go to the dist folder `cd dist/ngx-st-qty-input` and run `npm publish`.
+```bash
+npm install ngx-st-qty-input
+```
 
-## Running unit tests
+Import the module:
 
-Run `ng test ngx-st-qty-input` to execute the unit tests via [Karma](https://karma-runner.github.io).
+```typescript
+import { NgxStQtyInputModule } from 'ngx-st-qty-input';
 
-## Further help
+@NgModule({
+  imports: [NgxStQtyInputModule]
+})
+export class AppModule { }
+```
+
+---
+
+## Basic Usage
+
+```html
+<ngx-st-qty-input
+  [(qtyModel)]="quantity">
+</ngx-st-qty-input>
+
+<p>Quantity: {{ quantity }}</p>
+```
+
+---
+
+## Inputs
+
+### `qtyModel` (model signal)
+- **Type:** `number`
+- **Required:** Yes
+- **Description:** The quantity value. Uses Angular's model signal for two-way binding.
+- **Example:**
+  ```html
+  [(qtyModel)]="quantity"
+  ```
+
+### `allowNegative`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Allows negative values. When false, values below 0 are automatically reset to 0.
+- **Example:**
+  ```html
+  [allowNegative]="true"
+  [allowNegative]="false"
+  ```
+
+### `disabled`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Disables the entire component (input and buttons).
+- **Example:**
+  ```html
+  [disabled]="isProcessing"
+  [disabled]="true"
+  ```
+
+### `showError`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows an error state styling on the input.
+- **Example:**
+  ```html
+  [showError]="quantity < minRequired"
+  [showError]="hasValidationError"
+  ```
+
+---
+
+## Outputs
+
+### `newValueEmitter`
+- **Type:** `number`
+- **Description:** Emitted whenever the quantity value changes (via buttons or direct input).
+- **Example:**
+  ```typescript
+  (newValueEmitter)="onQuantityChange($event)"
+  
+  onQuantityChange(newValue: number): void {
+    console.log('New quantity:', newValue);
+    this.updateCart(newValue);
+  }
+  ```
+
+---
+
+## Usage Examples
+
+### Example 1: Basic Shopping Cart Quantity
+
+```typescript
+// Component
+@Component({
+  selector: 'app-cart-item',
+  template: `
+    <div class="cart-item">
+      <img [src]="product.image" [alt]="product.name">
+      <h3>{{ product.name }}</h3>
+      <p>Price: ${{ product.price }}</p>
+      
+      <ngx-st-qty-input
+        [(qtyModel)]="quantity"
+        (newValueEmitter)="updateCartItem($event)">
+      </ngx-st-qty-input>
+      
+      <p>Total: ${{ total }}</p>
+    </div>
+  `
+})
+export class CartItemComponent {
+  product = {
+    id: 1,
+    name: 'Product Name',
+    price: 19.99,
+    image: 'product.jpg'
+  };
+  
+  quantity = 1;
+  
+  get total(): number {
+    return this.product.price * this.quantity;
+  }
+  
+  updateCartItem(newQuantity: number): void {
+    console.log('Updating cart with quantity:', newQuantity);
+    // API call to update cart
+  }
+}
+```
+
+### Example 2: With Negative Values
+
+```typescript
+// Component
+@Component({
+  selector: 'app-adjustment',
+  template: `
+    <h3>Stock Adjustment</h3>
+    <p>Current Stock: {{ currentStock }}</p>
+    
+    <label>Adjustment:</label>
+    <ngx-st-qty-input
+      [(qtyModel)]="adjustment"
+      [allowNegative]="true"
+      (newValueEmitter)="calculateNewStock($event)">
+    </ngx-st-qty-input>
+    
+    <p>New Stock: {{ newStock }}</p>
+    <button (click)="applyAdjustment()">Apply</button>
+  `
+})
+export class StockAdjustmentComponent {
+  currentStock = 100;
+  adjustment = 0;
+  newStock = 100;
+  
+  calculateNewStock(adjustment: number): void {
+    this.newStock = this.currentStock + adjustment;
+  }
+  
+  applyAdjustment(): void {
+    this.currentStock = this.newStock;
+    this.adjustment = 0;
+  }
+}
+```
+
+### Example 3: Disabled State
+
+```typescript
+// Component
+@Component({
+  selector: 'app-disabled-qty',
+  template: `
+    <ngx-st-qty-input
+      [(qtyModel)]="quantity"
+      [disabled]="outOfStock">
+    </ngx-st-qty-input>
+    
+    <p *ngIf="outOfStock" class="error">Out of Stock</p>
+    <button (click)="toggleStock()">Toggle Stock</button>
+  `
+})
+export class DisabledQtyComponent {
+  quantity = 1;
+  outOfStock = false;
+  
+  toggleStock(): void {
+    this.outOfStock = !this.outOfStock;
+  }
+}
+```
+
+### Example 4: With Validation and Error Display
+
+```typescript
+// Component
+@Component({
+  selector: 'app-validated-qty',
+  template: `
+    <div class="qty-input-wrapper">
+      <label>Quantity (Min: {{ minQty }}, Max: {{ maxQty }}):</label>
+      <ngx-st-qty-input
+        [(qtyModel)]="quantity"
+        [showError]="hasError"
+        (newValueEmitter)="validate($event)">
+      </ngx-st-qty-input>
+      
+      <p *ngIf="hasError" class="error-message">
+        {{ errorMessage }}
+      </p>
+    </div>
+  `
+})
+export class ValidatedQtyComponent {
+  quantity = 1;
+  minQty = 1;
+  maxQty = 10;
+  hasError = false;
+  errorMessage = '';
+  
+  validate(value: number): void {
+    if (value < this.minQty) {
+      this.hasError = true;
+      this.errorMessage = `Minimum quantity is ${this.minQty}`;
+    } else if (value > this.maxQty) {
+      this.hasError = true;
+      this.errorMessage = `Maximum quantity is ${this.maxQty}`;
+    } else {
+      this.hasError = false;
+      this.errorMessage = '';
+    }
+  }
+}
+```
+
+### Example 5: Multiple Quantity Inputs
+
+```typescript
+// Component
+@Component({
+  selector: 'app-order-form',
+  template: `
+    <h3>Order Products</h3>
+    <div *ngFor="let item of orderItems" class="order-item">
+      <span>{{ item.name }}</span>
+      <ngx-st-qty-input
+        [(qtyModel)]="item.quantity"
+        (newValueEmitter)="updateItemTotal(item)">
+      </ngx-st-qty-input>
+      <span>{{ item.price | currency }} each</span>
+      <span>Total: {{ item.total | currency }}</span>
+    </div>
+    
+    <div class="order-summary">
+      <h4>Order Total: {{ orderTotal | currency }}</h4>
+    </div>
+  `
+})
+export class OrderFormComponent {
+  orderItems = [
+    { id: 1, name: 'Item 1', price: 10, quantity: 1, total: 10 },
+    { id: 2, name: 'Item 2', price: 15, quantity: 2, total: 30 },
+    { id: 3, name: 'Item 3', price: 20, quantity: 1, total: 20 }
+  ];
+  
+  updateItemTotal(item: any): void {
+    item.total = item.price * item.quantity;
+  }
+  
+  get orderTotal(): number {
+    return this.orderItems.reduce((sum, item) => sum + item.total, 0);
+  }
+}
+```
+
+### Example 6: With Min/Max Enforcement
+
+```typescript
+// Component
+@Component({
+  selector: 'app-constrained-qty',
+  template: `
+    <label>Select Quantity (1-100):</label>
+    <ngx-st-qty-input
+      [(qtyModel)]="quantity"
+      [showError]="isOutOfRange"
+      (newValueEmitter)="enforceRange($event)">
+    </ngx-st-qty-input>
+    
+    <p *ngIf="isOutOfRange" class="warning">
+      Quantity must be between 1 and 100
+    </p>
+  `
+})
+export class ConstrainedQtyComponent {
+  quantity = 1;
+  minValue = 1;
+  maxValue = 100;
+  isOutOfRange = false;
+  
+  enforceRange(value: number): void {
+    this.isOutOfRange = false;
+    
+    if (value < this.minValue) {
+      this.quantity = this.minValue;
+      this.isOutOfRange = true;
+    } else if (value > this.maxValue) {
+      this.quantity = this.maxValue;
+      this.isOutOfRange = true;
+    }
+  }
+}
+```
+
+### Example 7: Real-time Price Calculator
+
+```typescript
+// Component
+@Component({
+  selector: 'app-price-calculator',
+  template: `
+    <div class="calculator">
+      <h3>{{ product.name }}</h3>
+      <img [src]="product.image" [alt]="product.name">
+      
+      <div class="price-info">
+        <p>Unit Price: {{ product.price | currency }}</p>
+        
+        <div class="qty-selector">
+          <label>Quantity:</label>
+          <ngx-st-qty-input
+            [(qtyModel)]="quantity"
+            [disabled]="!product.inStock"
+            (newValueEmitter)="calculatePrice($event)">
+          </ngx-st-qty-input>
+        </div>
+        
+        <div class="discount" *ngIf="discount > 0">
+          <p>Discount: -{{ discount | currency }}</p>
+        </div>
+        
+        <div class="total">
+          <h2>Total: {{ totalPrice | currency }}</h2>
+        </div>
+        
+        <button 
+          [disabled]="!product.inStock"
+          (click)="addToCart()">
+          Add to Cart
+        </button>
+      </div>
+    </div>
+  `
+})
+export class PriceCalculatorComponent {
+  product = {
+    id: 1,
+    name: 'Premium Widget',
+    price: 29.99,
+    image: 'widget.jpg',
+    inStock: true
+  };
+  
+  quantity = 1;
+  totalPrice = 29.99;
+  discount = 0;
+  
+  calculatePrice(qty: number): void {
+    const subtotal = this.product.price * qty;
+    
+    // Apply bulk discounts
+    if (qty >= 10) {
+      this.discount = subtotal * 0.1; // 10% off
+    } else if (qty >= 5) {
+      this.discount = subtotal * 0.05; // 5% off
+    } else {
+      this.discount = 0;
+    }
+    
+    this.totalPrice = subtotal - this.discount;
+  }
+  
+  addToCart(): void {
+    console.log(`Adding ${this.quantity} items to cart`);
+    // Add to cart logic
+  }
+}
+```
+
+### Example 8: With Stock Availability
+
+```typescript
+// Component
+@Component({
+  selector: 'app-stock-aware-qty',
+  template: `
+    <div class="product">
+      <h3>{{ product.name }}</h3>
+      <p>Available Stock: {{ product.stock }}</p>
+      
+      <ngx-st-qty-input
+        [(qtyModel)]="quantity"
+        [showError]="exceedsStock"
+        [disabled]="product.stock === 0"
+        (newValueEmitter)="checkStock($event)">
+      </ngx-st-qty-input>
+      
+      <p *ngIf="exceedsStock" class="error">
+        Only {{ product.stock }} items available
+      </p>
+      
+      <p *ngIf="product.stock === 0" class="out-of-stock">
+        Out of Stock
+      </p>
+      
+      <button 
+        [disabled]="exceedsStock || product.stock === 0"
+        (click)="purchase()">
+        Purchase
+      </button>
+    </div>
+  `
+})
+export class StockAwareQtyComponent {
+  product = {
+    name: 'Limited Edition Item',
+    stock: 5
+  };
+  
+  quantity = 1;
+  exceedsStock = false;
+  
+  checkStock(qty: number): void {
+    if (qty > this.product.stock) {
+      this.exceedsStock = true;
+      // Optionally auto-correct
+      this.quantity = this.product.stock;
+    } else {
+      this.exceedsStock = false;
+    }
+  }
+  
+  purchase(): void {
+    this.product.stock -= this.quantity;
+    console.log(`Purchased ${this.quantity} items`);
+    this.quantity = 1;
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Set appropriate initial values**:
+   ```typescript
+   quantity = 1;  // Don't start with 0 for shopping carts
+   ```
+
+2. **Use validation** to enforce business rules:
+   ```typescript
+   onQuantityChange(qty: number): void {
+     if (qty > maxStock) {
+       this.quantity = maxStock;
+     }
+   }
+   ```
+
+3. **Disable when not applicable**:
+   ```html
+   [disabled]="outOfStock || isProcessing"
+   ```
+
+4. **Show errors for invalid values**:
+   ```html
+   [showError]="quantity < minRequired || quantity > maxAllowed"
+   ```
+
+5. **Use `allowNegative` only when needed**:
+   ```html
+   <!-- For adjustments -->
+   [allowNegative]="true"
+   
+   <!-- For quantities (default) -->
+   [allowNegative]="false"
+   ```
+
+6. **Provide feedback** on changes:
+   ```typescript
+   onQuantityChange(qty: number): void {
+     this.updateTotal();
+     this.checkAvailability();
+     this.calculateShipping();
+   }
+   ```
+
+7. **Consider debouncing** for API calls:
+   ```typescript
+   onQuantityChange = debounce((qty: number) => {
+     this.updateCartOnServer(qty);
+   }, 500);
+   ```
+
+---
+
+## Component Behavior
+
+### Increment Button (+)
+- Increases value by 1
+- Emits `newValueEmitter` event
+- Disabled when component is disabled
+
+### Decrement Button (-)
+- Decreases value by 1
+- If `allowNegative` is false and value would go below 0, sets to 0
+- Emits `newValueEmitter` event
+- Disabled when component is disabled
+
+### Direct Input
+- Allows manual entry of numeric values
+- Validates and corrects negative values if `allowNegative` is false
+- Emits `newValueEmitter` event on blur or enter
+
+---
+
+## Common Use Cases
+
+1. **Shopping Cart**: Product quantity selection
+2. **Inventory Management**: Stock adjustments (with negative values)
+3. **Order Forms**: Quantity selection for multiple items
+4. **Configurators**: Selecting quantities of customizable items
+5. **Bulk Operations**: Specifying number of items to process
+
+---
+
+This documentation covers all inputs, outputs, and usage patterns for the Quantity Input component.
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-st-qty-input",
-  "version": "18.0.0",
+  "version": "18.0.1",
   "peerDependencies": {
     "@angular/common": "^18.0.0",
     "@angular/core": "^18.0.0",