npm package: @ng-shangjc/input
Description: Input component source package for ng-shangjc angular components
Author: jc-develop
Latest version: 1.0.2-beta

<p align="center">
<a href="https://juliancallejas.github.io/ng-shangjc-docs">
  <img src="https://res.cloudinary.com/dphleqb5t/image/upload/v1772819746/shangjc/shangjc-64-bg-dark_kwzs81.svg" width="307" alt="Shangjc"  /> 
</a>
</p>

# Input Component

A versatile and feature-rich input component with comprehensive form integration, label support, error handling, and advanced input controls. Built with modern Angular signals and supporting both template-driven and reactive forms with full accessibility and keyboard navigation.

## Official Documentation

<a href="https://juliancallejas.github.io/ng-shangjc-docs/?path=/docs/components-input">
    ng-Shangjc docs
</a>

## Features

- 🚀 **Multiple Input Types**: Support for text, email, password, number, tel, and url inputs
- 🎨 **Advanced Controls**: Built-in increment/decrement buttons for numbers, password reveal toggle, and clear button
- ♿ **Full Accessibility**: ARIA compliance, keyboard navigation, and screen reader support
- ⌨️ **Keyboard Navigation**: Complete support for Tab, Shift+Tab, Enter, Space, and Arrow keys
- 🎯 **Type-Safe**: Full TypeScript support with proper type definitions
- 🎨 **Customizable**: Extensive styling options with Tailwind CSS classes
- ⚡ **Performance**: Optimized with Angular signals for reactive updates
- 📝 **Form Integration**: Seamless integration with both template-driven and reactive forms
- 🔧 **HTML5 Attributes**: Full support for all standard HTML input attributes
- 🎭 **Control Value Accessor**: Implements ControlValueAccessor for form validation

## Installation

### Step 1: Install the CLI

First, install the ng-shangjc CLI globally or use npx:

```bash
# Install globally
npm install -g @ng-shangjc/cli

# or with yarn
yarn global add @ng-shangjc/cli

# or with pnpm
pnpm install -g @ng-shangjc/cli

# Or use npx without installation
npx @ng-shangjc/cli <command>
```

### Step 2: Initialize your project

If you haven't already, initialize your Angular project for ng-shangjc components:

```bash
ng-shangjc init
```

This will create a `shangjc.config.json` file and set up your project for component installations.

### Step 3: Install the component

Install the input component into your project:

```bash
ng-shangjc install input
```

The component will be installed in the configured path (default: `src/ui/shangjc`). Adjust the import path in your components based on your project structure and the configured installation path.

## Import

After installation, import the components from your configured installation path. The examples below use the default path `src/ui/shangjc` - adjust the path according to your project structure and configuration.

### Standalone Components (Recommended)

Import and use the individual components directly in your standalone components:

```typescript
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { 
  InputComponent
} from './ui/shangjc/input';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    InputComponent
  ],
  template: `
    <ng-shangjc-input>
      <!-- Component content -->
    </ng-shangjc-input>
  `
})
export class ExampleComponent { }
```

### Using NgModule (Legacy)

If you're using NgModules, import the `InputModule`:

```typescript
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { InputModule } from './ui/shangjc/input';

@NgModule({
  declarations: [YourComponent],
  imports: [
    CommonModule,
    InputModule
  ]
})
export class YourModule { }
```

Then use the components in your templates:

```html
<ng-shangjc-input>
  <!-- Component content -->
</ng-shangjc-input>
```

## Basic Usage

### Default Example

```typescript
import { Component } from '@angular/core';
import { 
  InputComponent
} from './ui/shangjc/input';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    InputComponent
  ],
  template: `
    <ng-shangjc-input 
      placeholder="Enter your text"
      label="Basic Input">
    </ng-shangjc-input>
  `,
})
export class ExampleComponent {}
```

### With Different Input Types

```html
<!-- Text input -->
<ng-shangjc-input 
  type="text" 
  placeholder="Enter text"
  label="Text Input">
</ng-shangjc-input>

<!-- Email input -->
<ng-shangjc-input 
  type="email" 
  placeholder="email@example.com"
  label="Email Address">
</ng-shangjc-input>

<!-- Password input with reveal toggle -->
<ng-shangjc-input 
  type="password" 
  placeholder="Enter password"
  label="Password">
</ng-shangjc-input>

<!-- Number input with increment/decrement -->
<ng-shangjc-input 
  type="number" 
  placeholder="0"
  label="Quantity">
</ng-shangjc-input>
```

### Form Integration

```typescript
import { Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { InputComponent } from './ui/shangjc/input';

@Component({
  selector: 'app-form-example',
  standalone: true,
  imports: [InputComponent, ReactiveFormsModule],
  template: `
    <form [formGroup]="userForm">
      <ng-shangjc-input 
        formControlName="name"
        label="Name"
        placeholder="Enter your name"
        [error]="userForm.get('name')?.errors?.required ? 'Name is required' : ''">
      </ng-shangjc-input>
      
      <ng-shangjc-input 
        formControlName="email"
        type="email"
        label="Email"
        placeholder="Enter your email"
        [error]="userForm.get('email')?.errors?.email ? 'Invalid email format' : ''">
      </ng-shangjc-input>
    </form>
  `,
})
export class FormExampleComponent {
  userForm = new FormGroup({
    name: new FormControl('', { validators: [Validators.required] }),
    email: new FormControl('', { validators: [Validators.email] })
  });
}
```

## Advanced Usage

### Controlled Component

```typescript
import { Component, signal } from '@angular/core';
import { InputComponent } from './ui/shangjc/input';

@Component({
  selector: 'app-controlled-example',
  standalone: true,
  imports: [InputComponent],
  template: `
    <ng-shangjc-input 
      [(value)]="searchTerm"
      placeholder="Search..."
      label="Search"
      (valueChange)="onSearchChange($event)">
    </ng-shangjc-input>
    
    <p>Current search term: {{ searchTerm() }}</p>
  `
})
export class ControlledExampleComponent {
  searchTerm = signal('');
  
  onSearchChange(value: string) {
    console.log('Search term changed:', value);
    // Perform search logic here
  }
}
```

### Custom Styling

```html
<ng-shangjc-input 
  class="border-2 border-blue-500 rounded-lg"
  labelClass="text-blue-600 font-bold"
  errorClass="text-red-500 italic"
  placeholder="Custom styled input"
  label="Custom Styling">
</ng-shangjc-input>
```

### Advanced HTML5 Attributes

```html
<ng-shangjc-input
  type="number"
  label="Age"
  placeholder="Enter age"
  min="18"
  max="100"
  required
  pattern="[0-9]+"
  title="Please enter a valid age between 18 and 100"
  autocomplete="age"
  inputmode="numeric">
</ng-shangjc-input>
```

## API Reference

### InputComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `type` | `InputTypes` | `'text'` | The type of input field ('text' \| 'email' \| 'password' \| 'number' \| 'tel' \| 'url') |
| `placeholder` | `string` | `''` | Placeholder text for the input |
| `label` | `string` | `''` | Label text displayed above the input |
| `error` | `string` | `''` | Error message displayed below the input |
| `disabled` | `boolean` | `false` | Whether the input is disabled |
| `controlButton` | `boolean` | `true` | Whether to show a control button |
| `id` | `string` | `inp-<random>` | The id of the input field |
| `class` | `string` | `''` | Additional classes for the input field |
| `errorClass` | `string` | `''` | Additional classes for the error message |
| `labelClass` | `string` | `''` | Additional classes for the label |
| `inputmode` | `InputModes` | `undefined` | Input mode for the input field |
| `value` | `string` | `''` | The value of the input field (two-way bindable) |
| `name` | `string \| undefined` | `undefined` | The name of the input element |
| `autocomplete` | `boolean` | `false` | The autocomplete attribute value |
| `max` | `string \| undefined` | `undefined` | The maximum value for number/date inputs |
| `maxLength` | `string \| undefined` | `undefined` | The maximum length of the input value |
| `min` | `string \| undefined` | `undefined` | The minimum value for number/date inputs |
| `minLength` | `string \| undefined` | `undefined` | The minimum length of the input value |
| `pattern` | `string \| undefined` | `undefined` | The pattern for input validation |
| `required` | `boolean` | `false` | Whether the input is required |
| `autofocus` | `boolean` | `false` | Whether the input should be focused when the page loads |
| `title` | `string \| undefined` | `undefined` | The title attribute value |
| `role` | `string \| undefined` | `undefined` | The role attribute value |

### Events

| Event | Type | Description |
|-------|------|-------------|
| `valueChange` | `EventEmitter<string>` | Emitted when the input value changes |
| `focused` | `EventEmitter<void>` | Emitted when the input receives focus |
| `blurred` | `EventEmitter<void>` | Emitted when the input loses focus |

## Accessibility

- **Keyboard Navigation**: Full support for Tab, Shift+Tab, Enter, Space, and Arrow keys
- **ARIA Attributes**: Proper ARIA labels, roles, and states
- **Focus Management**: Visible focus indicators and proper focus handling
- **Screen Reader**: Compatible with screen readers
- **Semantic Structure**: Uses proper HTML semantic elements

### ARIA Features

- `role="textbox"` on input elements
- `aria-label` and `aria-labelledby` for proper labeling
- `aria-required` indicates required fields
- `aria-disabled` indicates disabled state
- `aria-invalid` indicates validation errors
- `aria-describedby` links to error messages

## Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## Contributing

See the main project [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

---

**Part of ng-shangjc component library** • [Documentation](https://juliancallejas.github.io/ng-shangjc-docs/)

<p align="center">
<a href="https://github.com/JulianCallejas">
  <img src="https://res.cloudinary.com/dphleqb5t/image/upload/v1740784502/github-jc-develop/JC-LOGO-Horizontal-170-50-thin-github_uu3b5n.svg" width="170" alt="{ jc - develop }"  /> 
</a>
</p>