quang 20.1.9 → 20.2.2

package/components/autocomplete/README.md

@@ -1,73 +1,90 @@
 # QuangAutocompleteComponent
 
-The `QuangAutocompleteComponent` provides real-time suggestions as the user types, allowing for easy selection from a list of filtered options. It is designed to be flexible and customizable for a variety of use cases in Angular forms.
-
-## Features
-
-- Real-time suggestions as the user types
-- Easy selection from filtered options
-- Customizable suggestion list and display
-- Supports Angular Reactive Forms and Template-driven Forms
-- Configurable debounce for search input
-- Readonly and validation support
-- **Multiple selection with chips** (with horizontal/vertical display)
-- Keyboard navigation and chip deletion (Backspace)
-- Focus management for chips (Backspace focuses last chip, second Backspace deletes it)
+The `QuangAutocompleteComponent` is a comprehensive autocomplete input with real-time suggestions, multiple selection capabilities, and chip management. It provides intelligent filtering, keyboard navigation, and seamless integration with Angular forms while supporting both single and multiple selection modes.
 
 ## Inputs
 
-- `selectOptions`: `SelectOption[]` — Array of options to display as suggestions. **(Required)**
-- `multiple`: `boolean` — Enable multiple selection mode (chips). Default: `false`.
-- `multiSelectDisplayMode`: `'vertical' | 'horizontal'` — Display chips vertically or horizontally. Default: `'vertical'`.
-- `chipMaxLength`: `number` — Maximum length (in characters) for a single chip label. Default: `0` (no limit).
-- `syncFormWithText`: `boolean` — If true, the form value is kept in sync with the input text. Default: `false`.
-- `optionListMaxHeight`: `string` — Max height for the dropdown list. Default: `'200px'`.
-- `translateValue`: `boolean` — Whether to translate option values. Default: `true`.
-- `scrollBehaviorOnOpen`: `ScrollBehavior` — Scroll behavior when opening the dropdown. Default: `'smooth'`.
-- `emitOnly`: `boolean` — If true, only emits the value without saving it in ngControl. Default: `false`.
-- `searchTextDebounce`: `number` — Debounce time in milliseconds for search input. Default: `300`.
-- `internalFilterOptions`: `boolean` — If true, filters options internally. Default: `true`.
-- All standard form/label/validation-related inputs inherited from `QuangBaseComponent`:
-  - `isReadonly`, `componentLabel`, `componentPlaceholder`, `componentTabIndex`, `componentClass`, `errorMap`, `successMessage`, `helpMessage`, `formControl`
+- `selectOptions`: `SelectOption[]` — Array of available options for selection. Each option should have `value` and `label` properties. **(Required)**
+- `multiple`: `boolean` — Enable multiple selection mode with chip display. Default: `false`
+- `multiSelectDisplayMode`: `'vertical' | 'horizontal'` — Layout direction for chips in multiple mode. Horizontal mode includes scroll support. Default: `'vertical'`
+- `chipMaxLength`: `number` — Maximum character length for chip labels. Longer labels will be truncated with ellipsis. Default: `0` (no limit)
+- `syncFormWithText`: `boolean` — Synchronize form control value with input text as user types. Useful for free-text input with suggestions. Default: `false`
+- `optionListMaxHeight`: `string` — Maximum height for dropdown option list with CSS units. Default: `'200px'`
+- `translateValue`: `boolean` — Enable translation of option values through QuangTranslationService. Default: `true`
+- `scrollBehaviorOnOpen`: `ScrollBehavior` — Scroll behavior when opening dropdown ('smooth' or 'instant'). Default: `'smooth'`
+- `emitOnly`: `boolean` — Only emit selection events without updating form control. Useful for read-only suggestion display. Default: `false`
+- `searchTextDebounce`: `number` — Debounce delay in milliseconds for search input to optimize performance. Default: `300`
+- `internalFilterOptions`: `boolean` — Use built-in filtering logic. Disable for custom external filtering via searchTextChange event. Default: `true`
+- `isReadonly`: `boolean` — Set component to read-only mode. Inherited from `QuangBaseComponent`
+- `componentLabel`: `string` — Label text for the component. Inherited from `QuangBaseComponent`
+- `componentPlaceholder`: `string` — Placeholder text for the input. Inherited from `QuangBaseComponent`
+- `componentTabIndex`: `number` — Tab index for accessibility. Inherited from `QuangBaseComponent`
+- `componentClass`: `string | string[]` — Additional CSS classes. Inherited from `QuangBaseComponent`
+- `errorMap`: `{[key: string]: string}` — Custom error messages. Inherited from `QuangBaseComponent`
+- `successMessage`: `string` — Success message to display. Inherited from `QuangBaseComponent`
+- `helpMessage`: `string` — Help text for the component. Inherited from `QuangBaseComponent`
+- `formControl`: `FormControl` — Form control for reactive forms. Inherited from `QuangBaseComponent`
 
 ## Outputs
 
-- `selectedOption`: Emits the selected value when a suggestion is selected.
-- `searchTextChange`: Emits the current search text as the user types.
-- All standard outputs inherited from `QuangBaseComponent`:
-  - `componentBlur`
+- `selectedOption`: `EventEmitter<string | number | null>` — Emitted when an option is selected in single mode. Provides the selected option's value
+- `searchTextChange`: `EventEmitter<string>` — Emitted when search text changes after debounce period. Use for external filtering or API calls
+- `componentBlur`: `EventEmitter<void>` — Emitted when component loses focus. Inherited from `QuangBaseComponent`
 
-## Multiple/Chip Mode
+## Usage
 
-- When `multiple` is `true`, selected options are displayed as removable chips.
-- Chips can be displayed horizontally or vertically using `multiSelectDisplayMode`.
-- Chips have a close button for removal. When the input is empty, pressing Backspace focuses the last chip; pressing Backspace again deletes it.
-- Focus is managed for accessibility: after deleting a chip, focus moves to the previous chip or input.
-- Chip container supports horizontal scrolling with the mouse wheel in horizontal mode.
-- You can limit chip label length with `chipMaxLength`.
+### Basic Single Selection
 
-## Usage
+```html
+<quang-autocomplete
+  [selectOptions]="countryOptions"
+  formControlName="country"
+>
+</quang-autocomplete>
+```
+
+### Multiple Selection with Chips
 
 ```html
 <quang-autocomplete
+  [selectOptions]="skillOptions"
   [multiple]="true"
-  [multiSelectDisplayMode]="'horizontal'"
-  [chipMaxLength]="12"
-  [errorMap]="errors()"
-  [isReadonly]="isReadonly()"
-  [searchTextDebounce]="500"
-  [selectOptions]="stringListFiltered()"
-  (searchTextChange)="changeTextTest($event)"
-  (selectedOption)="onSelectOption($event)"
-  class="col-6"
-  componentLabel="form.label.autocompleteAsync"
-  formControlName="testInput1"
-  successMessage="form.label.success"
-/>
+  formControlName="skills"
+>
+</quang-autocomplete>
+```
+
+#### TypeScript Example
+
+```typescript
+export class MyComponent {
+  countryOptions: SelectOption[] = [
+    { value: 'us', label: 'United States' },
+    { value: 'ca', label: 'Canada' },
+    { value: 'uk', label: 'United Kingdom' }
+  ]
+
+  skillOptions: SelectOption[] = [
+    { value: 'angular', label: 'Angular' },
+    { value: 'typescript', label: 'TypeScript' },
+    { value: 'javascript', label: 'JavaScript' }
+  ]
+
+  onOptionSelected(value: string | number | null): void {
+    console.log('Selected:', value)
+  }
+
+  onSearchChange(searchTerm: string): void {
+    // Handle external filtering
+  }
+}
 ```
 
-## Notes
+### Translation Integration
 
-This component extends the `QuangBaseComponent` and inherits its features, such as label and validation messages. It is recommended to use with Angular Reactive Forms for best results.
+The component uses QuangTranslationService for all text content:
 
-For more advanced usage and customization, refer to the full documentation and examples in the Quang library.
+- **Automatic Translation**: Option labels and component messages are translated automatically
+- **Key Support**: Use translation keys as labels for automatic localization
+- **Fallback Handling**: Provides fallback display when translations are unavailable
+- **Dynamic Language Switching**: Responds to language changes without component reload

package/components/checkbox/README.md

@@ -1,63 +1,73 @@
 # QuangCheckboxComponent
 
-The `QuangCheckboxComponent` can be used as a standard checkbox or as a toggle switch by setting the `checkType` input.
-
-## Features
-
-- Standard checkbox functionality
-- Toggle switch mode
-- Configurable label position
-- Validation feedback (success and error messages)
+The `QuangCheckboxComponent` is a versatile checkbox and toggle switch component that provides flexible label positioning, comprehensive validation feedback, and seamless integration with Angular forms. It supports both traditional checkbox and modern toggle switch modes with extensive customization options.
 
 ## Inputs
 
-- `checkType`: `'checkbox' | 'toggle'` — Specifies the type of the component. **(Required)**
-- `labelPosition`: `'top' | 'left' | 'right' | 'bottom'` — Position of the label. Default: `'top'`.
-- `removeMargin`: `boolean` — Removes the default margin. Default: `false`.
-- All standard form/label/validation-related inputs inherited from `QuangBaseComponent`:
-  - `isReadonly`, `componentLabel`, `componentPlaceholder`, `componentTabIndex`, `componentClass`, `errorMap`, `successMessage`, `helpMessage`, `formControl`
+- `checkType`: `'checkbox' | 'toggle'` — Specifies the input type. Checkbox renders as traditional checkmark input, toggle renders as modern switch control. **(Required)**
+- `labelPosition`: `'top' | 'left' | 'right' | 'bottom'` — Position of the label relative to the input control. Affects layout direction and spacing. Default: `'top'`
+- `removeMargin`: `boolean` — Removes default bottom margin and form-check class. Useful for custom layouts or tight spacing requirements. Default: `false`
+- `isReadonly`: `boolean` — Set component to read-only mode. Inherited from `QuangBaseComponent`
+- `componentLabel`: `string` — Label text for the component. Inherited from `QuangBaseComponent`
+- `componentPlaceholder`: `string` — Placeholder text for the input. Inherited from `QuangBaseComponent`
+- `componentTabIndex`: `number` — Tab index for accessibility. Inherited from `QuangBaseComponent`
+- `componentClass`: `string | string[]` — Additional CSS classes. Inherited from `QuangBaseComponent`
+- `errorMap`: `{[key: string]: string}` — Custom error messages. Inherited from `QuangBaseComponent`
+- `successMessage`: `string` — Success message to display. Inherited from `QuangBaseComponent`
+- `helpMessage`: `string` — Help text for the component. Inherited from `QuangBaseComponent`
+- `formControl`: `FormControl` — Form control for reactive forms. Inherited from `QuangBaseComponent`
 
 ## Outputs
 
-- `changedHandler`: Emits the updated value when the checkbox state changes.
-- All standard outputs inherited from `QuangBaseComponent`:
-  - `componentBlur`
+- `changedHandler`: `EventEmitter<boolean>` — Emitted when checkbox state changes. Provides the new boolean value (true for checked, false for unchecked)
+- `componentBlur`: `EventEmitter<void>` — Emitted when component loses focus. Inherited from `QuangBaseComponent`
 
 ## Usage
 
+### Basic Checkbox
+
 ```html
 <quang-checkbox
-  [errorMap]="errors()"
-  [isReadonly]="isReadonly()"
   checkType="checkbox"
-  class="col-3"
-  componentLabel="form.label.toggle"
-  formControlName="toggle"
-  labelPosition="top"
-  successMessage="form.label.success"
-/>
+  componentLabel="form.label.agreeToTerms"
+  formControlName="agreeToTerms"
+>
+</quang-checkbox>
+```
+
+### Toggle Switch
+
+```html
 <quang-checkbox
-  [errorMap]="errors()"
-  [isReadonly]="isReadonly()"
   checkType="toggle"
-  class="col-6"
-  componentLabel="form.label.checkbox"
-  formControlName="checkbox"
+  componentLabel="form.label.enableNotifications"
   labelPosition="left"
-  successMessage="form.label.success"
-/>
+  formControlName="notifications"
+>
+</quang-checkbox>
 ```
 
-## Styling
+#### TypeScript Example
 
-The component supports the following CSS classes for customization:
+```typescript
+export class MyComponent {
+  form = this.fb.group({
+    agreeToTerms: [false, Validators.requiredTrue],
+    enableNotifications: [true]
+  })
+
+  onToggleChange(isChecked: boolean): void {
+    console.log('Checkbox state changed:', isChecked)
+    // Handle state change
+  }
+}
+```
 
-- `.label-top`: Positions the label above the checkbox.
-- `.label-bottom`: Positions the label below the checkbox.
-- `.label-left`: Positions the label to the left of the checkbox.
-- `.label-right`: Positions the label to the right of the checkbox.
-- `.toggle-wrapper`: Styles the component as a toggle switch.
+### Translation Integration
 
-## Notes
+The component uses QuangTranslationService for all text content:
 
-This component extends the `QuangBaseComponent` and inherits its features, such as label, error messages, and success messages.
+- **Automatic Translation**: All labels, help text, and error messages are automatically translated
+- **Key Support**: Use translation keys for all text content
+- **Fallback Handling**: Provides graceful fallback when translations are unavailable
+- **Dynamic Language**: Responds to language changes without component reload