@flusys/ng-ui 8.1.5 → 9.0.0

package/README.md

@@ -161,6 +161,19 @@ export class SomePage {}
 
 ---
 
+## Disabled State
+
+Every component with a `disabled` input handles it the same way:
+
+- **Form controls** (`select`, `multiselect`, `checkbox`, `radiobutton`, `toggleswitch`, `togglebutton`, `selectbutton`, `password`, `inputnumber`, `inputotp`, `datepicker`, `autocomplete`, `cascadeselect`, `treeselect`, `colorpicker`, `listbox`, `rating`, `knob`, `slider`) expose `isDisabled()`, which combines the `disabled` input with `setDisabledState()`. That covers `[formField]`, `FormControl.disable()` and `[(ngModel)] [disabled]`.
+- **Host clicks are blocked while disabled.** Buttons, `fButton`, split buttons, speed dial, chips, tabs, accordion headers, inplace, file upload, tree, order list, pick list, organization chart and all of the form controls above swallow clicks and middle-clicks in the capture phase, so a consumer's `(click)` or `routerLink` on the host never fires while the component is disabled.
+- **`fButton` on non-button hosts** (e.g. `<a fButton routerLink>`) also drops out of the tab order while disabled or loading, and restores the consumer's own `tabindex` afterwards.
+- **Disabled menu items** in `menu`, `menubar`, `tieredmenu`, `contextmenu`, `megamenu`, `panelmenu` and `breadcrumb` render with no `href`, don't navigate, and don't run `command`.
+
+Use `(onChange)` to react to value changes, not `(click)` on the host: a `<label>` click re-dispatches a second click to the inner input.
+
+---
+
 ## Buttons & Actions
 
 ### ButtonComponent
@@ -183,6 +196,8 @@ Attribute-directive version of the button — apply button styling to a native `
 
 Key inputs: `severity`, `text`, `outlined`, `link`, `rounded`, `raised`, `fluid`, `disabled`, `loading`, `size`, `label`, `icon`, `iconPos`, `ariaLabel`, `plain`.
 
+`icon` and `loadingIcon` are Lucide names (same as `ui-icon`); the directive renders a real `ui-icon` before or after the label, and a spinning `loader-circle` while `loading`.
+
 ### SplitButtonComponent
 
 Primary action button with an attached dropdown menu. Selector: `f-splitbutton`.
@@ -378,7 +393,21 @@ File upload with drag-drop, auto-upload, and progress. Selector: `f-fileupload`.
 <f-fileupload accept="image/*" [maxFileSize]="2000000" [multiple]="true" (onSelect)="onFilesSelected($event)" (onError)="onUploadError($event)" />
 ```
 
-Key inputs: `name`, `accept`, `multiple`, `auto`, `maxFileSize`, `fileLimit`, `disabled`, `url`, `customUpload`, `chooseLabel`, `mode` (`advanced | basic`). Outputs: `onSelect` (`FileSelectEvent`), `onRemove` (`FileRemoveEvent`), `onClear`, `onError` (`FileErrorEvent[]`).
+Key inputs: `name`, `accept`, `multiple`, `auto`, `maxFileSize`, `fileLimit`, `disabled`, `url`, `customUpload`, `mode` (`advanced | basic`). Outputs: `onSelect` (`FileSelectEvent`), `onRemove` (`FileRemoveEvent`), `onClear`, `onError` (`FileErrorEvent[]`).
+
+Text inputs (English defaults — bind translated strings): `chooseLabel`, `uploadLabel`, `cancelLabel`, `removeLabel` (per-file remove button's accessible name), `dragDropLabel`, `dragDropHintLabel`.
+
+Pass `<ng-template #content>` (or `fTemplate="content"`) to replace the default drop zone and file list in advanced mode. Drag-and-drop still works on the wrapper. Context (`FileUploadContentContext`): `$implicit`/`files`, `items`, `disabled`, `removeFile(file)`, `clear()`.
+
+```html
+<f-fileupload [chooseLabel]="'storage.button.choose.file' | translate">
+  <ng-template #content let-files let-removeFile="removeFile">
+    @for (file of files; track file.name) {
+      <button fButton [text]="true" [ariaLabel]="'shared.remove' | translate" (click)="removeFile(file)">{{ file.name }}</button>
+    }
+  </ng-template>
+</f-fileupload>
+```
 
 ### AutoCompleteComponent
 
@@ -388,7 +417,23 @@ Type-ahead input backed by an async or static suggestion list. Selector: `f-auto
 <f-autocomplete [suggestions]="filteredUsers()" field="name" [(ngModel)]="selectedUser" (completeMethod)="search($event.query)" />
 ```
 
-Key inputs: `suggestions`, `field`, `placeholder`, `disabled`, `dropdown`, `forceSelection`, `multiple`, `delay`, `minLength`, `invalid`, `touched`, `appendTo` (`self | body`). Outputs: `completeMethod` (`AutoCompleteCompleteEvent`), `onSelect` (`AutoCompleteSelectEvent`), `onUnselect`, `onClear`, `onChange`.
+Key inputs: `suggestions`, `field`, `placeholder`, `ariaLabel`, `disabled`, `dropdown`, `forceSelection`, `multiple`, `delay`, `minLength`, `completeOnFocus`, `freeText`, `filterLocally`, `invalid`, `touched`, `appendTo` (`self | body`). Outputs: `completeMethod` (`AutoCompleteCompleteEvent`), `onSelect` (`AutoCompleteSelectEvent`), `onUnselect`, `onClear`, `onChange`.
+
+**Editable combobox (free text + suggestions).** By default only a picked suggestion reaches the model; typed text stays in the input. `freeText` writes every keystroke to the model (single mode), so the value can be anything the user types, with the suggestions as shortcuts. `filterLocally` filters a static `suggestions` list case-insensitively by the typed text, with no `completeMethod` handler needed (grouped lists are filtered per group, empty groups dropped). Focusing the input or pressing the dropdown button shows the full list again. In `freeText` mode the panel stays closed rather than showing the empty message when nothing matches, and clearing sets `''` instead of `null`.
+
+```html
+<f-autocomplete
+  freeText
+  filterLocally
+  completeOnFocus
+  dropdown
+  [minLength]="0"
+  [delay]="0"
+  [suggestions]="['input.email', 'loop.item', 'user.id']"
+  [ariaLabel]="'app.field' | translate"
+  [(ngModel)]="path"
+/>
+```
 
 ### ColorPickerComponent
 
@@ -478,7 +523,7 @@ Select input backed by a hierarchical tree of options. Selector: `f-treeselect`.
 <f-treeselect [options]="orgTree" [(ngModel)]="selectedNode" selectionMode="checkbox" [filter]="true" />
 ```
 
-Key inputs: `options` (`TreeNode[]`), `placeholder`, `disabled`, `filter`, `selectionMode` (`single | multiple | checkbox`), `invalid`, `touched`, `appendTo` (`self | body`).
+Key inputs: `options` (`TreeNode[]`), `placeholder`, `inputId` (id of the trigger, for `<label for>`), `disabled`, `filter`, `filterBy`, `selectionMode` (`single | multiple | checkbox`), `propagateSelectionDown` / `propagateSelectionUp` (checkbox cascading), `invalid`, `touched`, `appendTo` (`self | body`). A node with `selectable: false` is a heading: clicking it expands or collapses it, and it never becomes part of the value.
 
 ### IconFieldComponent / InputIconComponent