quang 19.0.19 → 19.0.21

package/README.md

@@ -1,25 +1,105 @@
 # Quang
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 17.3.0.
+Quang is a comprehensive Angular component and utility library designed to streamline common operations in Angular applications.
 
-## Code scaffolding
+## Project Structure
 
-Run `ng generate component component-name --project quang` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project quang`.
+The library is organized into several functional modules, each focusing on different aspects of application development:
 
-> Note: Don't forget to add `--project quang` or else it will be added to the default project in your `angular.json` file.
+### [Auth](/projects/quang/auth/README.md)
+Authentication and authorization utilities including:
+- Authentication services and providers
+- Role-based access control directives
+- Authentication guards
+- Token storage management
+- Mobile-specific authentication features
 
-## Build
+### [Components](/projects/quang/components/README.md)
+Reusable UI components including:
+- Autocomplete
+- Checkbox
+- Date inputs
+- Form inputs
+- Paginator
+- Select dropdowns
+- Tables
+- WYSIWYG editor
 
-Run `ng build quang` to build the project. The build artifacts will be stored in the `dist/` directory.
+### [Data Handling](/projects/quang/data-handling)
+Utilities for:
+- Data conversion operations
+- File download helpers
 
-## Publishing
+### [Device](/projects/quang/device)
+Device and viewport management utilities including:
+- Resize observable service for responsive design
 
-After building your library with `ng build quang`, go to the dist folder `cd dist/quang` and run `npm publish`.
+### [Forms](/projects/quang/forms/README.md)
+Form management utilities including:
+- Form group model abstractions
+- Custom form validators
 
-## Running unit tests
+### [Loader](/projects/quang/loader/README.md)
+Loading state management including:
+- Loading indicator components
+- Loading state interceptor
+- Loading service
 
-Run `ng test quang` to execute the unit tests via [Karma](https://karma-runner.github.io).
+### [Network](/projects/quang/network)
+Network request utilities and services.
+- Interceptor utilities
 
-## Further help
+### [Overlay](/projects/quang/overlay/README.md)
+Overlay-based UI components including:
+- Modals
+- Popovers
+- Toasts
+- Tooltips
 
-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.
+### [Translation](/projects/quang/translation/README.md)
+Internationalization (i18n) utilities including:
+- Translation loader service
+- Translation providers
+- Translation tokens
+
+## Getting Started
+
+To use Quang in your project, install it via npm:
+
+```bash
+npm install quang
+```
+
+## Usage
+
+Quang uses standalone components, which means you can import only the specific components you need directly into your application:
+
+```typescript
+// Import services
+import { AuthService } from 'quang/auth';
+import { LoaderService } from 'quang/loader';
+
+// Import components
+import { SelectComponent } from 'quang/components/select';
+import { PaginatorComponent } from 'quang/components/paginator';
+import { LoaderComponent } from 'quang/loader';
+
+// Import directives
+import { IsAuthenticatedDirective } from 'quang/auth';
+```
+
+You can then use these components directly in your standalone components:
+
+```typescript
+@Component({
+  standalone: true,
+  imports: [SelectComponent, PaginatorComponent, LoaderComponent, IsAuthenticatedDirective],
+  // ...
+})
+export class YourComponent {
+  // ...
+}
+```
+
+For more detailed information about each component and feature, please refer to the corresponding README linked in the project structure section.
+`

package/auth/README.md

@@ -44,7 +44,7 @@ template.
 
 ### QuangHasEveryRoleDirective
 
-This directive shows content only if user is not authenticated.
+This directive shows content only if the user has every specified role.
 
 To use it import [QuangHasEveryRoleDirective](./directives/has-every-role.directive.ts) and put it in your template.
 
@@ -58,7 +58,7 @@ To use it import [QuangHasEveryRoleDirective](./directives/has-every-role.direct
 
 ### QuangHasAtLeastOneRoleDirective
 
-This directive shows content only if user is not authenticated.
+This directive shows content only if the user has at least one of the specified roles.
 
 To use it import [QuangHasAtLeastOneRoleDirective](./directives/has-at-least-one-role.directive.ts) and put it in your
 template.

package/components/autocomplete/README.md

@@ -0,0 +1,55 @@
+# 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
+
+## Inputs
+
+- `selectOptions`: `SelectOption[]` — Array of options to display as suggestions. **(Required)**
+- `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`
+
+## 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`
+
+## Usage
+
+```html
+<quang-autocomplete
+  [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"
+/>
+```
+
+## Notes
+
+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.
+
+For more advanced usage and customization, refer to the full documentation and examples in the Quang library.

package/components/checkbox/README.md

@@ -0,0 +1,63 @@
+# 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)
+
+## 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`
+
+## Outputs
+
+- `changedHandler`: Emits the updated value when the checkbox state changes.
+- All standard outputs inherited from `QuangBaseComponent`:
+  - `componentBlur`
+
+## Usage
+
+```html
+<quang-checkbox
+  [errorMap]="errors()"
+  [isReadonly]="isReadonly()"
+  checkType="checkbox"
+  class="col-3"
+  componentLabel="form.label.toggle"
+  formControlName="toggle"
+  labelPosition="top"
+  successMessage="form.label.success"
+/>
+<quang-checkbox
+  [errorMap]="errors()"
+  [isReadonly]="isReadonly()"
+  checkType="toggle"
+  class="col-6"
+  componentLabel="form.label.checkbox"
+  formControlName="checkbox"
+  labelPosition="left"
+  successMessage="form.label.success"
+/>
+```
+
+## Styling
+
+The component supports the following CSS classes for customization:
+
+- `.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.
+
+## Notes
+
+This component extends the `QuangBaseComponent` and inherits its features, such as label, error messages, and success messages.

package/components/date/README.md

@@ -0,0 +1,54 @@
+# QuangDateComponent
+
+The `QuangDateComponent` is based on Air Datepicker. It can be fully customized using the input property `datepickerOptions`.
+
+## Features
+- Fully customizable datepicker
+- Based on Air Datepicker
+- Supports date ranges and localization
+
+## Inputs
+
+- `datepickerOptions`: `object` — Configuration options for the datepicker. **(Required)**
+- `minDate`: `Date | string` — Minimum selectable date.
+- `maxDate`: `Date | string` — Maximum selectable date.
+- All standard form/label/validation-related inputs inherited from `QuangBaseComponent`:
+  - `isReadonly`, `componentLabel`, `componentPlaceholder`, `componentTabIndex`, `componentClass`, `errorMap`, `successMessage`, `helpMessage`, `formControl`
+
+## Outputs
+
+- `dateChange`: Emits the selected date when it changes.
+- All standard outputs inherited from `QuangBaseComponent`:
+  - `componentBlur`
+
+## Usage
+```html
+<quang-date
+  [minDate]="minDate"
+  [maxDate]="maxDate"
+  [errorMap]="errors()"
+  [formControl]="testForm.controls.testInput"
+  [isReadonly]="isReadonly()"
+  [timepicker]="true"
+  class="col-6"
+  componentLabel="form.label.date"
+  successMessage="form.label.success"
+>
+  <img src="./assets/icons/svg/calendar.svg" />
+</quang-date>
+```
+
+### Note
+Remember to add the import:
+
+`node_modules/quang/components/date/global-date.component.scss`
+
+or
+
+`quang/components/date/global-date.component.scss`
+
+in your global style (suggested "vendors" folder).
+
+## Notes
+
+This component extends the `QuangBaseComponent` and inherits its features, such as label, error messages, and success messages.

package/components/input/README.md

@@ -0,0 +1,58 @@
+# QuangInputComponent
+
+The `QuangInputComponent` must be configured using the `componentType` input property.
+
+## Supported Types
+
+- text
+- textarea
+- password
+- email
+- number
+- url
+- search
+- tel
+- color
+
+## Inputs
+
+- `componentType`: `'text' | 'textarea' | 'password' | 'email' | 'number' | 'url' | 'search' | 'tel' | 'color'` — Specifies the type of input. **(Required)**
+- `maxLengthText`: `number | null` — Maximum length for text input.
+- `minLengthText`: `number | null` — Minimum length for text input.
+- `minNumber`: `number | undefined` — Minimum value for number input.
+- `maxNumber`: `number | undefined` — Maximum value for number input.
+- `componentStep`: `number` — Step for number input. Default: `1`.
+- `resizable`: `boolean` — If false, disables textarea resizing. Default: `true` (only for textarea).
+- All standard form/label/validation-related inputs inherited from `QuangBaseComponent`:
+  - `isReadonly`, `componentLabel`, `componentPlaceholder`, `componentTabIndex`, `componentClass`, `errorMap`, `successMessage`, `helpMessage`, `formControl`
+
+## Outputs
+
+- All standard outputs inherited from `QuangBaseComponent`:
+  - `componentBlur`
+
+## Usage
+
+```html
+<quang-input
+  [errorMap]="errors()"
+  componentLabel="form.label.input"
+  componentType="text"
+  formControlName="testInput"
+/>
+
+<quang-input
+  [errorMap]="errors()"
+  [isReadonly]="isReadonly()"
+  [maxNumber]="10"
+  [minNumber]="0"
+  componentLabel="form.label.input"
+  componentType="number"
+  formControlName="testInput"
+  successMessage="form.label.success"
+/>
+```
+
+## Notes
+
+This component extends the `QuangBaseComponent` and inherits its features, such as label and validation messages.

package/components/paginator/README.md

@@ -0,0 +1,43 @@
+# QuangPaginatorComponent
+
+The `QuangPaginatorComponent` provides controls for navigating through pages of data, supporting configurations for total items, items per page, and current page.
+
+## Features
+
+- Pagination controls
+- Configurable total items, items per page, and current page
+- Emits events for page changes
+
+## Inputs
+
+- `page`: `number` — Current page number. **(Required)**
+- `pageSize`: `number` — Number of items per page. **(Required)**
+- `sizeList`: `number[]` — List of selectable page sizes. Default: `[]`.
+- `totalItems`: `number` — Total number of items to paginate. **(Required)**
+- `showTotalElementsCount`: `boolean` — Show/hide total items count. Default: `true`.
+- `totalItemsText`: `string` — Translation key for total items label. Default: `'quangPaginator.totalItems'`.
+- `sizeText`: `string` — Translation key for size label. Default: `'quangPaginator.size'`.
+- `pageRangeText`: `string` — Translation key for page range label. Default: `'quangPaginator.pageRange'`.
+- `componentId`, `componentTabIndex`, `componentClass`: Standard component inputs.
+
+## Outputs
+
+- `changePage`: Emits the new page number when the user navigates to a different page.
+- `changeSize`: Emits the new page size when the user changes it.
+
+## Usage
+
+```html
+<quang-paginator
+  [page]="1"
+  [pageSize]="10"
+  [sizeList]="[5, 10, 20]"
+  [totalItems]="30"
+  (changePage)="onChangePage($event)"
+  (changeSize)="onChangePageSize($event)"
+/>
+```
+
+## Notes
+
+This component provides a user-friendly interface for pagination in lists and tables.

package/components/select/README.md

@@ -0,0 +1,54 @@
+# QuangSelectComponent
+
+The `QuangSelectComponent` supports single or multiple selections from a dropdown list.
+
+## Features
+
+- Single selection
+- Multiple selection
+- Customizable options
+
+## Inputs
+
+- `selectOptions`: `SelectOption[]` — Array of options to display in the dropdown. **(Required)**
+- `selectionMode`: `'single' | 'multiple'` — Enables single or multiple selection mode. Default: `'single'`.
+- All standard form/label/validation-related inputs inherited from `QuangBaseComponent`:
+  - `isReadonly`, `componentLabel`, `componentPlaceholder`, `componentTabIndex`, `componentClass`, `errorMap`, `successMessage`, `helpMessage`, `formControl`
+
+## Outputs
+
+- All standard outputs inherited from `QuangBaseComponent`:
+  - `componentBlur`
+
+## Usage
+
+```html
+<quang-select
+  [errorMap]="errors()"
+  [isReadonly]="isReadonly()"
+  [selectOptions]="stringList"
+  class="col-4"
+  componentLabel="form.label.select"
+  componentPlaceholder="Placeholder select singola scelta"
+  formControlName="testInput"
+  playgroundSourceCode
+  selectionMode="single"
+  successMessage="form.label.success"
+/>
+
+<quang-select
+  [errorMap]="errors()"
+  [isReadonly]="isReadonly()"
+  [selectOptions]="numberList"
+  class="col-4"
+  componentLabel="form.label.multipleSelect"
+  componentPlaceholder="Placeholder select scelta multipla"
+  formControlName="testInputMultiple"
+  selectionMode="multiple"
+  successMessage="form.label.success"
+/>
+```
+
+## Notes
+
+This component extends the `QuangBaseComponent` and inherits its features, such as label and validation messages.

package/components/table/README.md

@@ -0,0 +1,63 @@
+# QuangTableComponent
+
+The `QuangTableComponent` allows for displaying data in a tabular format.
+
+## Features
+
+- Tabular data display
+- Customizable headers and rows
+- Supports sorting and filtering
+
+## Inputs
+
+- `tableConfigurations`: `{ headers: TableHeader[]; rows: any[] }` — Table configuration object containing headers and rows. **(Required)**
+- `stickyTable`: `boolean` — Enables sticky header/columns. Default: `false`.
+- All standard form/label/validation-related inputs inherited from `QuangBaseComponent` (if applicable):
+  - `isReadonly`, `componentLabel`, `componentPlaceholder`, `componentTabIndex`, `componentClass`, `errorMap`, `successMessage`, `helpMessage`, `formControl`
+
+## Outputs
+
+- `sortChanged`: Emits the sort state when the user changes sorting.
+- `rowClick`: Emits the clicked row data when a row is clicked.
+
+## Usage
+
+### HTML
+
+```html
+<quang-table
+  [stickyTable]="true"
+  [tableConfigurations]="tableConfig()"
+  (sortChanged)="onChangeSort($event)"
+  (rowClick)="onRowClick($event)"
+/>
+```
+
+### TypeScript
+
+```typescript
+import { computed, signal } from '@angular/core'
+
+// Angular signals for table data and headers
+
+tableRows = signal([
+  { id: 1, name: 'John Doe', age: 30 },
+  { id: 2, name: 'Jane Smith', age: 25 },
+  { id: 3, name: 'Alice Johnson', age: 35 },
+])
+
+tableHeaders = [
+  { key: 'id', label: 'ID', sortable: true },
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'age', label: 'Age', sortable: false },
+]
+
+tableConfig = computed(() => ({
+  headers: tableHeaders,
+  rows: tableRows(),
+}))
+```
+
+## Notes
+
+This component is highly customizable and can be styled to match your application's design.

package/components/wysiwyg/README.md

@@ -0,0 +1,55 @@
+# QuangWysiwygComponent
+
+The `QuangWysiwygComponent` is a rich text editor based on [SunEditor](https://github.com/JiHong88/SunEditor), offering a wide range of formatting options for creating and editing HTML content.
+
+## Features
+
+- Rich text editing
+- Wide range of formatting options
+- Supports custom toolbars and plugins
+
+## Inputs
+
+- `wysiwygOptions`: `object` — Configuration options for the editor. **(Required)**
+- `minHeight`: `string | undefined` — Minimum height for the editor area. Default: `'200px'`.
+- `highlightColor`: `boolean` — Show/hide the highlight color button in the toolbar. Default: `true`.
+- `isReadonly`: `boolean` — If true, the editor is readonly.
+- `onImageUploadError`: `(errorMessage: any, result: any, core: any) => boolean` — Callback for image upload errors.
+- `onFileDrop`: `(e: any, cleanData: any, maxCharCount: any, core: any) => boolean` — Callback for file drop events.
+- Toolbar button toggles (all `boolean`, default: `true`):
+  - `font`, `fontSize`, `formatBlock`, `paragraphStyle`, `blockquote`, `bold`, `underline`, `italic`, `strike`, `fontColor`, `textStyle`, `removeFormat`, `align`, `list`, `table`, `link`, `image`, `fullScreen`, `showBlocks`
+- All standard form/label/validation-related inputs inherited from `QuangBaseComponent`:
+  - `componentLabel`, `componentPlaceholder`, `componentTabIndex`, `componentClass`, `errorMap`, `successMessage`, `helpMessage`, `formControl`
+
+## Outputs
+
+- All standard outputs inherited from `QuangBaseComponent`:
+  - `componentBlur`
+
+## Usage
+
+```html
+<quang-wysiwyg
+  [errorMap]="errors()"
+  [highlightColor]="highlightColor()"
+  [isReadonly]="isReadonly()"
+  [minHeight]="wysiwygHeight()"
+  [onImageUploadError]="onImageUploadError"
+  [wysiwygOptions]="wysiwygOptions"
+  componentLabel="form.label.wysiwyg"
+  formControlName="testInput"
+  successMessage="form.label.success"
+/>
+```
+
+### Note
+
+Remember to import:
+
+`node_modules/quang/components/wysiwyg/global-wysiswyg.component.scss`
+
+or
+
+`quang/components/wysiwyg/global-wysiswyg.component.scss`
+
+in your global style (suggested "vendors" folder).