@truenas/ui-components 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/ui-components",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/types/truenas-ui-components.d.ts

@@ -2293,30 +2293,54 @@ interface ChipHarnessFilters extends BaseHarnessFilters {
     label?: string | RegExp;
 }
 
+/**
+ * Option shape for `tn-chip-input`'s value mode — the `label` is displayed on
+ * the chip, the `value` is committed to the form control. Structurally
+ * identical to `TnSelectOption`/`TnAutocompleteOption`, so the same data sources
+ * feed all three.
+ */
+type TnChipInputOption<T = unknown> = TnSelectOption<T>;
 /**
  * An editable, multi-value chip input — tokenized entry where typed text
  * becomes removable `tn-chip`s alongside an inline text field. Text is
  * committed to a chip on Enter (or a configurable separator key); Backspace on
  * an empty field removes the last chip.
  *
- * It is a `ControlValueAccessor` over `string[]`, so it drops into a reactive
- * or template-driven form (`[formControl]`, `[(ngModel)]`) and slots into a
- * `tn-form-field` as a real projected control — the field's required/error
- * inference reads this control directly.
+ * It is a `ControlValueAccessor` over `T[]` (defaulting to `string[]`), so it
+ * drops into a reactive or template-driven form (`[formControl]`, `[(ngModel)]`)
+ * and slots into a `tn-form-field` as a real projected control — the field's
+ * required/error inference reads this control directly.
+ *
+ * **String mode (default).** Pass `[suggestions]` (a `string[]`) for typeahead;
+ * the typed/picked string is the value. Set `allowCustomValue=false` to restrict
+ * commits to the suggestion list.
  *
- * Suggestions are optional: pass `[suggestions]` for a static list, or drive
- * them asynchronously by listening to `(searchChange)` and updating
- * `[suggestions]` as results arrive. The dropdown is portaled through a CDK
- * overlay so it escapes any ancestor `overflow: hidden` (cards, side panels).
+ * **Value mode.** Pass `[options]` (`{ label, value }[]`) to display labels while
+ * committing values — the model becomes `T[]`. A written value resolves to its
+ * option's label (falling back to `String(value)` until the option is
+ * available). Provide `[compareWith]` when the values are objects. Committing a
+ * typed string matches an option by label (case-insensitive); free text that
+ * matches no option is only accepted when `allowCustomValue` is `true` (which is
+ * only sound for string-valued inputs).
+ *
+ * Either source can be driven asynchronously by listening to `(searchChange)`
+ * and updating `[suggestions]`/`[options]` as results arrive. The dropdown is
+ * portaled through a CDK overlay so it escapes any ancestor `overflow: hidden`.
  *
  * @example
  * ```html
+ * <!-- string mode -->
  * <tn-form-field label="Tags">
- *   <tn-chip-input [formControl]="tags" placeholder="Add a tag…" />
+ *   <tn-chip-input [formControl]="tags" [suggestions]="tagSuggestions" />
+ * </tn-form-field>
+ *
+ * <!-- value mode: shows names, commits ids -->
+ * <tn-form-field label="Groups">
+ *   <tn-chip-input [formControl]="groupIds" [options]="groupOptions" [allowCustomValue]="false" />
  * </tn-form-field>
  * ```
  */
-declare class TnChipInputComponent implements ControlValueAccessor, OnDestroy {
+declare class TnChipInputComponent<T = string> implements ControlValueAccessor, OnDestroy {
     private readonly overlay;
     private readonly viewContainerRef;
     /** Unique instance id for ARIA linkage between the input and its dropdown. */
@@ -2333,21 +2357,43 @@ declare class TnChipInputComponent implements ControlValueAccessor, OnDestroy {
     separatorKeys: _angular_core.InputSignal<string[]>;
     /** Commit a pending (non-empty) text value as a chip when the field loses focus. */
     addOnBlur: _angular_core.InputSignal<boolean>;
+    /**
+     * Whether free text not matching any option/suggestion may be committed.
+     * Defaults to `true` — any typed value becomes a chip. Set `false` to restrict
+     * the field to its list (a "pick from the list" control): a commit only
+     * succeeds when the text matches an option/suggestion label (case-insensitive,
+     * committing the canonical entry); unmatched text is discarded. Mirrors
+     * `tn-autocomplete`'s `allowCustomValue`. In value mode, leave this `false` —
+     * fabricating a typed string as a non-string value is unsound.
+     */
+    allowCustomValue: _angular_core.InputSignal<boolean>;
     /**
      * Allow the same value to be added more than once. Off by default.
-     * Duplicate detection is exact-match (case-sensitive), so with this off
-     * `Angular` and `angular` are still distinct values — only suggestion
-     * *filtering* is case-insensitive.
+     * Duplicate detection uses `compareWith` (or identity); string-mode matching
+     * is exact (case-sensitive), so `Angular` and `angular` are distinct — only
+     * the *filtering* of suggestions is case-insensitive.
      */
     allowDuplicates: _angular_core.InputSignal<boolean>;
     /** Hard cap on the number of chips; `undefined` means no limit. */
     maxChips: _angular_core.InputSignal<number | undefined>;
     /**
-     * Optional suggestion list. When non-empty, a dropdown offers entries that
-     * match the typed text and are not already selected. For async sources,
-     * update this in response to `(searchChange)`.
+     * String-mode suggestion list. When non-empty, a dropdown offers entries that
+     * match the typed text and are not already selected. Ignored when `options`
+     * is provided. For async sources, update this in response to `(searchChange)`.
      */
     suggestions: _angular_core.InputSignal<string[]>;
+    /**
+     * Value-mode option list (`{ label, value }`). When non-empty, chips display
+     * the resolved `label` while the form model holds `value`s. Takes precedence
+     * over `suggestions`. For async sources, update in response to `(searchChange)`.
+     */
+    options: _angular_core.InputSignal<TnChipInputOption<T>[]>;
+    /**
+     * Comparator for value equality — used for de-duplication, display resolution
+     * and the selected-set. Defaults to identity (`===`), correct for primitives;
+     * provide this when values are objects (e.g. `(a, b) => a?.id === b?.id`).
+     */
+    compareWith: _angular_core.InputSignal<((a: T | null, b: T | null) => boolean) | undefined>;
     /** Accessible name for the text field. Leave unset inside a `tn-form-field`. */
     ariaLabel: _angular_core.InputSignal<string | undefined>;
     /**
@@ -2357,9 +2403,9 @@ declare class TnChipInputComponent implements ControlValueAccessor, OnDestroy {
      */
     testId: _angular_core.InputSignal<TnTestIdValue>;
     /** Emits the committed value whenever a chip is added. */
-    chipAdded: _angular_core.OutputEmitterRef<string>;
+    chipAdded: _angular_core.OutputEmitterRef<T>;
     /** Emits the removed value whenever a chip is removed. */
-    chipRemoved: _angular_core.OutputEmitterRef<string>;
+    chipRemoved: _angular_core.OutputEmitterRef<T>;
     /**
      * Emits the current text as the user types (not on programmatic writes or
      * chip commits). Drive server-side suggestion lookups from this; debounce in
@@ -2370,7 +2416,7 @@ declare class TnChipInputComponent implements ControlValueAccessor, OnDestroy {
     private readonly inputEl;
     private readonly dropdownTemplate;
     /** Committed chip values — the form model. */
-    protected values: _angular_core.WritableSignal<string[]>;
+    protected values: _angular_core.WritableSignal<T[]>;
     /** Current text in the field. */
     protected inputValue: _angular_core.WritableSignal<string>;
     /** Whether the suggestion dropdown is open. */
@@ -2385,16 +2431,21 @@ declare class TnChipInputComponent implements ControlValueAccessor, OnDestroy {
     protected isDisabled: _angular_core.Signal<boolean>;
     /** Whether another chip may still be added under `maxChips`. */
     protected canAddMore: _angular_core.Signal<boolean>;
-    /** Suggestions that match the typed text and are not already selected. */
-    protected filteredSuggestions: _angular_core.Signal<string[]>;
+    /**
+     * Unified option list. Value-mode `options` win; otherwise string-mode
+     * `suggestions` are lifted into `{ label: s, value: s }`.
+     */
+    protected optionList: _angular_core.Signal<TnChipInputOption<T>[]>;
+    /** Options matching the typed text and not already selected. */
+    protected filteredSuggestions: _angular_core.Signal<TnChipInputOption<T>[]>;
     private onChange;
     private onTouched;
     private overlayRef?;
     private overlaySubs;
     constructor();
     ngOnDestroy(): void;
-    writeValue(value: string[] | null | undefined): void;
-    registerOnChange(fn: (value: string[]) => void): void;
+    writeValue(value: T[] | null | undefined): void;
+    registerOnChange(fn: (value: T[]) => void): void;
     registerOnTouched(fn: () => void): void;
     setDisabledState(isDisabled: boolean): void;
     /** Clicking anywhere in the container focuses the text field. */
@@ -2403,19 +2454,26 @@ declare class TnChipInputComponent implements ControlValueAccessor, OnDestroy {
     protected onFocus(): void;
     protected onBlur(): void;
     protected onKeydown(event: KeyboardEvent): void;
-    protected onSuggestionClick(suggestion: string): void;
+    protected onSuggestionClick(option: TnChipInputOption<T>): void;
     /** Prevents the option `mousedown` from blurring the input before the click lands. */
     protected onSuggestionMousedown(event: MouseEvent): void;
     protected removeChip(index: number): void;
+    /** The label shown on a chip for a committed value. */
+    protected displayLabel(value: T): string;
     /** Scopes a per-chip test id beneath the component's base. */
-    protected chipTestId(value: string): TnTestIdValue;
+    protected chipTestId(value: T): TnTestIdValue;
     private isCommitKey;
-    private addChip;
+    /** Commits typed text: resolve it to an option's value, else accept as custom. */
+    private commitText;
+    /** Commits a resolved value, honouring duplicate and cap rules. */
+    private commitValue;
+    private valuesIncludes;
+    private valueMatches;
     private clearInput;
     /**
      * Opens the dropdown when there is something to show, closes it otherwise.
      * Stays closed once the chip cap is reached — suggesting rows that
-     * `addChip()` would reject is misleading.
+     * `commitValue()` would reject is misleading.
      */
     private syncDropdown;
     /** Keeps the keyboard-highlighted suggestion visible within the scrolling panel. */
@@ -2424,8 +2482,8 @@ declare class TnChipInputComponent implements ControlValueAccessor, OnDestroy {
     private close;
     private attachOverlay;
     private detachOverlay;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnChipInputComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnChipInputComponent, "tn-chip-input", never, { "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "separatorKeys": { "alias": "separatorKeys"; "required": false; "isSignal": true; }; "addOnBlur": { "alias": "addOnBlur"; "required": false; "isSignal": true; }; "allowDuplicates": { "alias": "allowDuplicates"; "required": false; "isSignal": true; }; "maxChips": { "alias": "maxChips"; "required": false; "isSignal": true; }; "suggestions": { "alias": "suggestions"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "chipAdded": "chipAdded"; "chipRemoved": "chipRemoved"; "searchChange": "searchChange"; }, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnChipInputComponent<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnChipInputComponent<any>, "tn-chip-input", never, { "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "separatorKeys": { "alias": "separatorKeys"; "required": false; "isSignal": true; }; "addOnBlur": { "alias": "addOnBlur"; "required": false; "isSignal": true; }; "allowCustomValue": { "alias": "allowCustomValue"; "required": false; "isSignal": true; }; "allowDuplicates": { "alias": "allowDuplicates"; "required": false; "isSignal": true; }; "maxChips": { "alias": "maxChips"; "required": false; "isSignal": true; }; "suggestions": { "alias": "suggestions"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "chipAdded": "chipAdded"; "chipRemoved": "chipRemoved"; "searchChange": "searchChange"; }, never, never, true, never>;
 }
 
 /**
@@ -8291,4 +8349,4 @@ declare const TN_THEME_DEFINITIONS: readonly TnThemeDefinition[];
 declare const THEME_MAP: Map<TnTheme, TnThemeDefinition>;
 
 export { CommonShortcuts, DEFAULT_THEME, DiskIconComponent, DiskType, FileSizePipe, InputType, LIGHT_THEME, LabelMarkupPipe, LabelTextPipe, LinuxModifierKeys, LinuxShortcuts, ModifierKeys, QuickShortcuts, ShortcutBuilder, StripMntPrefixPipe, THEME_MAP, THEME_STORAGE_KEY, TN_FORM_FIELD_ERRORS, TN_TABLE_PAGER_DEFAULT_LABELS, TN_TABLE_PAGER_LABELS, TN_TEST_ATTR, TN_THEME_DEFINITIONS, TnAutocompleteComponent, TnAutocompleteHarness, TnBannerActionDirective, TnBannerComponent, TnBannerHarness, TnBrandedSpinnerComponent, TnButtonComponent, TnButtonHarness, TnButtonToggleComponent, TnButtonToggleGroupComponent, TnButtonToggleGroupHarness, TnButtonToggleHarness, TnCalendarComponent, TnCalendarHeaderComponent, TnCardComponent, TnCardFooterActionsDirective, TnCardHeaderActionsDirective, TnCardHeaderDirective, TnCellDefDirective, TnCheckboxComponent, TnCheckboxHarness, TnCheckboxLabelDirective, TnChipComponent, TnChipHarness, TnChipInputComponent, TnChipInputHarness, TnConfirmDialogComponent, TnDateInputComponent, TnDateInputHarness, TnDateRangeInputComponent, TnDateRangeInputHarness, TnDetailRowDefDirective, TnDialog, TnDialogHarness, TnDialogShellComponent, TnDialogTesting, TnDividerComponent, TnDividerDirective, TnDrawerComponent, TnDrawerContainerComponent, TnDrawerContainerHarness, TnDrawerContentComponent, TnDrawerHarness, TnEmptyComponent, TnEmptyHarness, TnExpansionPanelComponent, TnExpansionPanelHarness, TnFilePickerComponent, TnFilePickerPopupComponent, TnFormFieldComponent, TnFormFieldHarness, TnFormSectionComponent, TnFormSectionHarness, TnHeaderCellDefDirective, TnIconButtonComponent, TnIconButtonHarness, TnIconComponent, TnIconHarness, TnIconRegistryService, TnIconTesting, TnInputComponent, TnInputDirective, TnInputHarness, TnKeyboardShortcutComponent, TnKeyboardShortcutService, TnListAvatarDirective, TnListComponent, TnListIconDirective, TnListItemComponent, TnListItemLineDirective, TnListItemPrimaryDirective, TnListItemSecondaryDirective, TnListItemTitleDirective, TnListItemTrailingDirective, TnListOptionComponent, TnListSubheaderComponent, TnMenuActivateHoverDirective, TnMenuComponent, TnMenuHarness, TnMenuItemComponent, TnMenuTesting, TnMenuTriggerDirective, TnMonthViewComponent, TnMultiYearViewComponent, TnNestedTreeNodeComponent, TnParticleProgressBarComponent, TnProgressBarComponent, TnRadioComponent, TnRadioHarness, TnSelectComponent, TnSelectHarness, TnSelectionListComponent, TnSidePanelActionDirective, TnSidePanelComponent, TnSidePanelHarness, TnSidePanelHeaderActionDirective, TnSlideToggleComponent, TnSlideToggleHarness, TnSliderComponent, TnSliderThumbDirective, TnSliderWithLabelDirective, TnSpinnerComponent, TnSpriteLoaderService, TnStepComponent, TnStepperComponent, TnTabComponent, TnTabHarness, TnTabPanelComponent, TnTabPanelHarness, TnTableColumnDirective, TnTableComponent, TnTableHarness, TnTablePagerComponent, TnTablePagerHarness, TnTabsComponent, TnTabsHarness, TnTestIdDirective, TnTheme, TnThemeService, TnTimeInputComponent, TnToastComponent, TnToastMock, TnToastPosition, TnToastRef, TnToastService, TnToastTesting, TnToastType, TnTooltipComponent, TnTooltipDirective, TnTreeComponent, TnTreeFlatDataSource, TnTreeFlattener, TnTreeNodeComponent, TnTreeNodeOutletDirective, TruncatePathPipe, WindowsModifierKeys, WindowsShortcuts, composeTestId, createLucideLibrary, createShortcut, defaultSpriteBasePath, defaultSpriteConfigPath, formatSize, kebabTestSegment, labelMarkupToHtml, labelMarkupToText, libIconMarker, parseLabelMarkup, parseSize, registerLucideIcons, scopeTestId, setupLucideIntegration, tnIconMarker, writeTestId };
-export type { AutocompleteHarnessFilters, BannerHarnessFilters, ButtonHarnessFilters, ButtonToggleHarnessFilters, CalendarCell, CheckboxHarnessFilters, ChipColor, ChipHarnessFilters, CreateFolderEvent, DateInputHarnessFilters, DateRange, DateRangeInputHarnessFilters, DialogHarnessFilters, EmptyHarnessFilters, ExpansionPanelHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, FormFieldHarnessFilters, FormSectionHarnessFilters, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelMarkupSegment, LabelMarkupSegmentType, LabelType, LucideIconOptions, MenuHarnessFilters, MockIconRegistry, MockSpriteLoader, PathSegment, PlatformType, ProgressBarMode, RadioHarnessFilters, ResolvedIcon, SelectHarnessFilters, ShortcutHandler, SidePanelHarnessFilters, SizeStandard, SlideToggleColor, SlideToggleHarnessFilters, SpinnerMode, SpriteConfig, SubscriptSizing, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnAutocompleteOption, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnChipInputHarnessFilters, TnConfirmDialogData, TnDialogDefaults, TnDialogOpenTarget, TnDrawerMode, TnDrawerPosition, TnEmptySize, TnFlatTreeNode, TnFormFieldErrorMessage, TnFormFieldErrorMessages, TnFormFieldErrorResolver, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnSortEvent, TnTableDataProvider, TnTableDataSource, TnTableHarnessFilters, TnTablePagerHarnessFilters, TnTablePagerLabels, TnTablePagination, TnTestAttrName, TnTestIdValue, TnThemeDefinition, TnToastCall, TnToastConfig, TooltipPosition, YearCell };
+export type { AutocompleteHarnessFilters, BannerHarnessFilters, ButtonHarnessFilters, ButtonToggleHarnessFilters, CalendarCell, CheckboxHarnessFilters, ChipColor, ChipHarnessFilters, CreateFolderEvent, DateInputHarnessFilters, DateRange, DateRangeInputHarnessFilters, DialogHarnessFilters, EmptyHarnessFilters, ExpansionPanelHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, FormFieldHarnessFilters, FormSectionHarnessFilters, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelMarkupSegment, LabelMarkupSegmentType, LabelType, LucideIconOptions, MenuHarnessFilters, MockIconRegistry, MockSpriteLoader, PathSegment, PlatformType, ProgressBarMode, RadioHarnessFilters, ResolvedIcon, SelectHarnessFilters, ShortcutHandler, SidePanelHarnessFilters, SizeStandard, SlideToggleColor, SlideToggleHarnessFilters, SpinnerMode, SpriteConfig, SubscriptSizing, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnAutocompleteOption, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnChipInputHarnessFilters, TnChipInputOption, TnConfirmDialogData, TnDialogDefaults, TnDialogOpenTarget, TnDrawerMode, TnDrawerPosition, TnEmptySize, TnFlatTreeNode, TnFormFieldErrorMessage, TnFormFieldErrorMessages, TnFormFieldErrorResolver, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnSortEvent, TnTableDataProvider, TnTableDataSource, TnTableHarnessFilters, TnTablePagerHarnessFilters, TnTablePagerLabels, TnTablePagination, TnTestAttrName, TnTestIdValue, TnThemeDefinition, TnToastCall, TnToastConfig, TooltipPosition, YearCell };