commons-shared-web-ui 0.0.50 → 0.0.51

package/documentation/form-components.md

@@ -1,384 +0,0 @@
-# Form Components
-
-The `FormComponentsModule` provides a set of customizable, theme-aware form components. All components support `ControlValueAccessor` for seamless integration with Angular Reactive and Template-driven forms.
-
-## Module Import
-
-```typescript
-import { FormComponentsModule } from 'commons-shared-web-ui';
-
-@NgModule({
-  imports: [FormComponentsModule]
-})
-export class YourModule {}
-```
-
----
-
-## Input (`lib-input`)
-
-A text input field supporting multiple types (text, number, email, password, tel, url, textarea).
-
-### Selector
-`<lib-input>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `InputConfig` | — | Configuration object for all properties |
-| `labels` | `InputLabels` | — | i18n labels |
-| `type` | `InputType` | `'text'` | Input type: `text`, `number`, `email`, `password`, `tel`, `url`, `textarea` |
-| `label` | `string` | `''` | Field label |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `readonly` | `boolean` | `false` | Read-only state |
-| `maxLength` | `number` | — | Maximum character length |
-| `minLength` | `number` | — | Minimum character length |
-| `min` | `number` | — | Minimum numeric value |
-| `max` | `number` | — | Maximum numeric value |
-| `pattern` | `string` | — | Validation pattern |
-| `errorMessage` | `string` | — | Error message to display |
-| `helperText` | `string` | — | Helper text below the field |
-| `rows` | `number` | — | Rows for textarea type |
-| `prefixIcon` | `string \| IconObject` | — | Icon before input |
-| `suffixIcon` | `string \| IconObject` | — | Icon after input |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `valueChange` | `EventEmitter<any>` | Emitted when value changes |
-| `blur` | `EventEmitter<void>` | Emitted on blur |
-| `focus` | `EventEmitter<void>` | Emitted on focus |
-
-### Usage
-
-```html
-<lib-input
-  [config]="{ type: 'text', label: 'Name', placeholder: 'Enter your name', required: true }"
-  [labels]="{ label: 'Full Name', placeholder: 'Enter name' }"
-  (valueChange)="onNameChange($event)">
-</lib-input>
-```
-
----
-
-## Dropdown (`lib-dropdown`)
-
-A select/dropdown component with single or multi-select, search, virtual scrolling, and keyboard navigation.
-
-### Selector
-`<lib-dropdown>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `DropdownConfig` | — | Configuration object |
-| `labels` | `DropdownLabels` | — | i18n labels |
-| `options` | `DropdownOption[]` | `[]` | Array of selectable options |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `label` | `string` | `''` | Field label |
-| `multiple` | `boolean` | `false` | Enable multi-select |
-| `searchable` | `boolean` | `false` | Enable search filtering |
-| `clearable` | `boolean` | `false` | Show clear button |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-
-### `DropdownOption` Interface
-
-```typescript
-interface DropdownOption {
-  value: any;
-  label: string;
-  disabled?: boolean;
-  icon?: string | { type: 'material' | 'fontawesome' | 'img'; value: string };
-}
-```
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `selectionChange` | `EventEmitter<any>` | Emitted on selection change |
-
-### Usage
-
-```html
-<lib-dropdown
-  [config]="{ options: items, label: 'Country', searchable: true, clearable: true }"
-  [labels]="{ placeholder: 'Select a country', searchPlaceholder: 'Search...' }"
-  (selectionChange)="onCountryChange($event)">
-</lib-dropdown>
-```
-
----
-
-## Checkbox (`lib-checkbox`)
-
-A checkbox component supporting single and group modes.
-
-### Selector
-`<lib-checkbox>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `CheckboxConfig` | — | Configuration object |
-| `labels` | `CheckboxLabels` | — | i18n labels |
-| `label` | `string` | `''` | Checkbox label |
-| `checked` | `boolean` | `false` | Checked state |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `indeterminate` | `boolean` | `false` | Indeterminate state |
-| `options` | `CheckboxOption[]` | `[]` | Group options |
-| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position |
-| `color` | `'primary' \| 'accent' \| 'warn'` | `'primary'` | Color theme |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `change` | `EventEmitter<boolean>` | Emitted when checked state changes |
-| `groupChange` | `EventEmitter<CheckboxOption[]>` | Emitted when group selection changes |
-
-### Usage
-
-```html
-<!-- Single checkbox -->
-<lib-checkbox
-  [config]="{ label: 'Accept Terms', required: true }"
-  (change)="onAccept($event)">
-</lib-checkbox>
-
-<!-- Checkbox group -->
-<lib-checkbox
-  [config]="{ label: 'Select interests', options: interestOptions }"
-  (groupChange)="onInterestsChange($event)">
-</lib-checkbox>
-```
-
----
-
-## Radio (`lib-radio`)
-
-A radio button group component.
-
-### Selector
-`<lib-radio>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `RadioConfig` | — | Configuration object |
-| `labels` | `RadioLabels` | — | i18n labels |
-| `options` | `RadioOption[]` | `[]` | Radio options |
-| `label` | `string` | `''` | Group label |
-| `value` | `any` | — | Selected value |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position |
-| `color` | `'primary' \| 'warning' \| 'danger' \| 'success' \| 'accent' \| 'warn' \| string` | `'primary'` | Radio theme color |
-| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
-
-### `RadioOption` Interface
-
-```typescript
-interface RadioOption {
-  value: any;
-  label: string;
-  disabled?: boolean;
-}
-```
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `selectionChange` | `EventEmitter<any>` | Emitted when selection changes |
-
-### Usage
-
-```html
-<lib-radio
-  [config]="{ label: 'Gender', options: genderOptions, layout: 'horizontal' }"
-  [labels]="{ label: 'Select Gender' }"
-  (selectionChange)="onGenderChange($event)">
-</lib-radio>
-```
-
----
-
-## Toggle (`lib-toggle`)
-
-A slide toggle / switch component.
-
-### Selector
-`<lib-toggle>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `ToggleConfig` | — | Configuration object |
-| `labels` | `ToggleLabels` | — | i18n labels |
-| `label` | `string` | `''` | Toggle label |
-| `checked` | `boolean` | `false` | Toggle state |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `labelPosition` | `'before' \| 'after'` | `'after'` | Label position |
-| `color` | `'primary' \| 'warning' \| 'danger' \| 'success' \| string` | `'primary'` | Track checked color |
-| `uncheckedColor` | `string` | — | Unchecked track color |
-| `checkedColor` | `string` | — | Checked track color |
-| `thumbColor` | `string` | — | Thumb color |
-| `toggleWidth` | `string` | — | Toggle width |
-| `toggleHeight` | `string` | — | Toggle height |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `change` | `EventEmitter<boolean>` | Emitted when toggled |
-
-### Usage
-
-```html
-<lib-toggle
-  [config]="{ label: 'Dark Mode', checked: isDarkMode }"
-  (change)="onToggleDarkMode($event)">
-</lib-toggle>
-```
-
----
-
-## Datepicker (`lib-datepicker`)
-
-A date picker component supporting single date and date range selection.
-
-### Selector
-`<lib-datepicker>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `DatePickerConfig` | — | Configuration object |
-| `labels` | `DatepickerLabels` | — | i18n labels |
-| `label` | `string` | `''` | Field label |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `required` | `boolean` | `false` | Required state |
-| `minDate` | `Date` | — | Minimum selectable date |
-| `maxDate` | `Date` | — | Maximum selectable date |
-| `isRange` | `boolean` | `false` | Enable date range mode |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `dateChange` | `EventEmitter<Date>` | Emitted on single date change |
-| `rangeChange` | `EventEmitter<{start: Date, end: Date}>` | Emitted on range change |
-
-### Usage
-
-```html
-<!-- Single date -->
-<lib-datepicker
-  [config]="{ label: 'Start Date', placeholder: 'Pick a date', required: true }"
-  (dateChange)="onDateChange($event)">
-</lib-datepicker>
-
-<!-- Date range -->
-<lib-datepicker
-  [config]="{ label: 'Date Range', isRange: true }"
-  [labels]="{ startDateLabel: 'From', endDateLabel: 'To' }"
-  (rangeChange)="onRangeChange($event)">
-</lib-datepicker>
-```
-
----
-
-## Search (`lib-search`)
-
-A search input with built-in debounce and clear button support.
-
-### Selector
-`<lib-search>`
-
-### Inputs
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `config` | `FilterSearchConfig` | — | Configuration object |
-| `labels` | `SearchLabels` | — | i18n labels |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `label` | `string` | `''` | Field label |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `debounceMs` | `number` | `300` | Debounce time in milliseconds |
-| `clearable` | `boolean` | `true` | Show clear button |
-
-### Outputs
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `search` | `EventEmitter<string>` | Emitted on search (debounced) |
-| `clear` | `EventEmitter<void>` | Emitted when search is cleared |
-
-### Usage
-
-```html
-<lib-search
-  [config]="{ placeholder: 'Search users...', debounceTime: 500, clearable: true }"
-  (search)="onSearch($event)"
-  (clear)="onClear()">
-</lib-search>
-```
-
----
-
-## Theming
-
-All form components support theming via CSS variables and SCSS mixins.
-
-### SCSS Mixin Setup
-
-Include the theme mixin in your application's global `styles.scss`:
-
-```scss
-@use 'commons-shared-web-ui/src/lib/modules/form-components/form-components.theme' as forms;
-
-html, body {
-  @include forms.form-components-theme();
-}
-```
-
-### Customizing Theme
-
-Pass a configuration map to override defaults:
-
-```scss
-@include forms.form-components-theme((
-  primary-color: #ff0000,
-  input-border-radius: 8px
-));
-```
-
-### Key CSS Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--cc-input-bg` | `#FEFEFE` | Input background color |
-| `--cc-input-border-radius` | `0.4375rem` | Input border radius |
-| `--cc-input-border-color` | `#BDC1C6` | Input border color |
-| `--cc-input-focus-border-color` | `#1A73E8` | Focus border color |
-| `--cc-dropdown-bg` | `#FEFEFE` | Dropdown background color |
-| `--cc-dropdown-height` | `2.5rem` | Dropdown trigger height |
-| `--cc-checkbox-checked-color` | `#1A73E8` | Checkbox checked color |
-
-### Inline Style Overrides
-
-All components accept style customization properties (`width`, `height`, `borderRadius`, `fontSize`, `backgroundColor`, `borderColor`, etc.) via their respective `config` objects. These are applied as inline styles with `!important` for precedence.