platformcommons-web-lib 1.0.0

package/documentation/form-components.md

@@ -0,0 +1,384 @@
+# 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.