@truenas/ui-components 0.8.13 → 0.8.15

package/package.json

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

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

@@ -18214,14 +18214,33 @@ export interface FileSystemItem {
   disabled?: boolean;
 }
 export interface FilePickerCallbacks {
+  /**
+   * Lists a directory. Reject with an Error to fail the navigation: the popup
+   * shows its message above the listing (and `error` emits a `navigation`
+   * error) until a later listing succeeds.
+   */
   getChildren?: (path: string) => Promise<FileSystemItem[]>;
   validatePath?: (path: string) => Promise<boolean>;
 }
+/**
+ * Everything that decides what the picker browses and how its value is
+ * expressed, as one object — for consumers that build it from their own data
+ * source and would otherwise bind the same four inputs at every call site.
+ * Each field mirrors the input of the same name; an input that is bound
+ * explicitly wins over the field.
+ */
+export interface FilePickerSource {
+  callbacks?: FilePickerCallbacks;
+  rootPath?: string;
+  startPath?: string;
+  valueRoot?: string;
+}
 /**
  * A consumer-defined creation flow surfaced as a button in the picker footer,
  * e.g. creating a dataset or zvol through a dialog. The creation itself
- * always happens outside the picker — either in a fully consumer-owned flow
- * (`createAction` event) or through the pluggable inline flow (`create`).
+ * always happens outside the picker — through the pluggable inline flow
+ * (`create`), a consumer-owned flow the picker awaits (`run`), or, with
+ * neither, a fully consumer-owned flow driven by the `createAction` event.
  */
 export interface FilePickerCreateAction {
   /** Identifies the action in `createAction` events, e.g. 'dataset'. */
@@ -18251,12 +18270,45 @@ export interface FilePickerCreateAction {
    * that (e.g. creation is cheap to leave behind, or idempotent).
    */
   create?: (parentPath: string, name: string) => Promise<string>;
+  /**
+   * A consumer-owned creation flow the picker awaits, e.g. one that opens a
+   * dialog or side panel. Called with the browsed directory when the button is
+   * pressed (and `create` is not set). Resolve with the created path to have
+   * the picker refresh the listing and select it, exactly as after an inline
+   * `create`; resolve with `null` when the user cancelled. Reject with an
+   * Error to show its message in the popup (and emit a `creation` error).
+   * Without `create` or `run`, pressing the button emits `createAction`.
+   */
+  run?: (parentPath: string) => Promise<string | null>;
+  /**
+   * Whether the action applies in the directory being browsed. Called with
+   * that directory's path and its listed item — `null` when the picker has not
+   * listed it, e.g. the start directory or the root. The button is hidden
+   * where this returns false. Omit it to show the action everywhere.
+   */
+  canCreateAt?: (parentPath: string, directory: FileSystemItem | null) => boolean;
 }
 export interface FilePickerCreateActionEvent {
   actionId: string;
   /** Directory being browsed when the action was triggered. */
   parentPath: string;
 }
+/**
+ * Payload of `itemSelectionChange`: the committed value together with the
+ * listed items it refers to, for consumers that need more than the path
+ * (e.g. to require that a FILE was picked).
+ */
+export interface FilePickerSelection {
+  /** The committed value — the same payload `selectionChange` carries. */
+  value: string | string[];
+  /**
+   * One entry per selected path, in value order. `null` when the picker has
+   * not listed that path in this session — e.g. a typed path the user never
+   * browsed to, or the browsed directory itself submitted on an empty
+   * selection before its parent was listed. Empty for a cleared selection.
+   */
+  items: (FileSystemItem | null)[];
+}
 export interface FilePickerError {
   type: 'navigation' | 'permission' | 'creation' | 'validation';
   message: string;
@@ -18281,6 +18333,24 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
   /** Consumer-defined creation flows shown as buttons in the popup footer. */
   createActions: import("@angular/core").InputSignal<FilePickerCreateAction[]>;
   allowManualInput: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Commit typed input verbatim instead of treating it as a path to validate:
+   * no `rootPath` confinement, no `callbacks.validatePath`, no `valueRoot`
+   * mapping — the text the user typed is the value. Lets a field accept
+   * entries the browser cannot list, e.g. `EXTERNAL:192.168.0.200\SHARE` or
+   * a dataset name for a pool that is not imported. With `multiSelect`, the
+   * text is split on commas into one entry per comma-separated part (trimmed,
+   * empty parts dropped), so commas cannot appear inside an entry. Committing
+   * closes the popup. Popup selections are unaffected. Requires
+   * `allowManualInput`.
+   */
+  allowFreeText: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Explicit accessible name for the path input. Inside a `tn-form-field` the
+   * input is named by the field label automatically (via `aria-labelledby`),
+   * so leave this unset there unless the field has no visible label.
+   */
+  ariaLabel: import("@angular/core").InputSignal<string | undefined>;
   /**
    * Open the picker popup when the input is clicked while no path is selected
    * yet — an empty field means the user is about to pick something, so the
@@ -18294,6 +18364,13 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
   openOnClick: import("@angular/core").InputSignal<boolean>;
   placeholder: import("@angular/core").InputSignal<string>;
   disabled: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Shows the value without letting the user change it: the input cannot be
+   * edited and the popup cannot be opened. Unlike `disabled` (or a disabled
+   * form control) the field stays focusable and its value stays part of the
+   * form — e.g. for a user who may view a setting but not edit it.
+   */
+  readonly: import("@angular/core").InputSignal<boolean>;
   /**
    * Test-id base applied to the file-picker container (`file-picker-` prefixed)
    * and derived onto the inner chrome: the path input (`input-<base>`), the
@@ -18303,7 +18380,13 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
    * (default `data-testid`).
    */
   testId: import("@angular/core").InputSignal<TnTestIdValue>;
-  startPath: import("@angular/core").InputSignal<string>;
+  /**
+   * Bundles `callbacks`, `rootPath`, `startPath` and `valueRoot` into one
+   * object. Each of those inputs, when bound, wins over its field here.
+   */
+  source: import("@angular/core").InputSignal<FilePickerSource | undefined>;
+  /** Directory the popup opens in. Defaults to `source.startPath`, else `/mnt`. */
+  startPath: import("@angular/core").InputSignal<string | undefined>;
   /** Restricts navigation — users cannot navigate above this path. */
   rootPath: import("@angular/core").InputSignal<string | undefined>;
   /**
@@ -18319,8 +18402,16 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
   fileExtensions: import("@angular/core").InputSignal<string[] | undefined>;
   callbacks: import("@angular/core").InputSignal<FilePickerCallbacks | undefined>;
   selectionChange: import("@angular/core").OutputEmitterRef<string | string[]>;
+  /**
+   * Emitted alongside every `selectionChange` with the listed
+   * `FileSystemItem` behind each selected path (or `null` when unknown).
+   */
+  itemSelectionChange: import("@angular/core").OutputEmitterRef<FilePickerSelection>;
   pathChange: import("@angular/core").OutputEmitterRef<string>;
-  /** Re-emitted from the popup when one of the `createActions` buttons is pressed. */
+  /**
+   * Emitted when one of the `createActions` buttons with neither `create` nor
+   * `run` is pressed.
+   */
   createAction: import("@angular/core").OutputEmitterRef<FilePickerCreateActionEvent>;
   error: import("@angular/core").OutputEmitterRef<FilePickerError>;
   wrapperEl: import("@angular/core").Signal<ElementRef<HTMLDivElement>>;
@@ -18335,8 +18426,32 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
   selectedItems: import("@angular/core").WritableSignal<string[]>;
   loading: import("@angular/core").WritableSignal<boolean>;
   hasError: import("@angular/core").WritableSignal<boolean>;
+  /**
+   * Message of the last failed listing or creation, shown in the popup until
+   * a listing succeeds or the popup closes.
+   */
+  popupError: import("@angular/core").WritableSignal<string | null>;
   private formDisabled;
+  /**
+   * Field-derived ARIA for the path input when projected into a
+   * `tn-form-field` (label, description, invalid, required). All-null when
+   * standalone or when `ariaLabel` overrides.
+   */
+  protected readonly fieldAria: import("@truenas/ui-components").TnFormFieldAriaBindings;
+  /**
+   * Every item the picker has listed, by absolute path, so a selection can be
+   * resolved back to its item even after browsing elsewhere (multi-select
+   * across directories, `selectPath`, typed paths). Kept for the picker's
+   * lifetime: a stale entry only means a stale `type` for a path that changed
+   * on disk after it was listed.
+   */
+  private listedItems;
   isDisabled: import("@angular/core").Signal<boolean>;
+  private effectiveCallbacks;
+  private effectiveStartPath;
+  private effectiveValueRoot;
+  /** `createActions` that apply in the directory being browsed (`canCreateAt`). */
+  protected availableCreateActions: import("@angular/core").Signal<FilePickerCreateAction[]>;
   /** Explicit `testId` wins; otherwise the bound control's name (formControlName etc.). */
   protected resolvedTestId: import("@angular/core").Signal<TnTestIdValue>;
   /**
@@ -18365,6 +18480,14 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
    * and spam `validatePath` with paths the user never meant.
    */
   onPathCommit(event: Event): void;
+  /**
+   * `allowFreeText` commit: the typed text is the value, verbatim (single
+   * mode keeps even surrounding whitespace, as the field shows it), and a
+   * field holding only whitespace clears the selection like an empty one.
+   * Selection state still tracks the absolute form of each trimmed entry (the
+   * same mapping `writeValue` applies) so reopening the popup reflects it.
+   */
+  private commitFreeText;
   /** `openOnClick` entry point. */
   onInputClick(): void;
   /**
@@ -18405,6 +18528,23 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
   navigateToPath(path: string): void;
   /** An inline `create` flow finished — show the new item selected and applied. */
   onCreated(path: string): void;
+  /**
+   * A footer button for an action without `create` was pressed: await its
+   * `run` flow and select what it created, or hand the action to the consumer
+   * through `createAction`.
+   *
+   * Deliberately not named `onCreateAction`: Storybook copies a story's props
+   * onto the rendered component, and stories commonly name their
+   * `(createAction)` handler that way, which would replace this method.
+   */
+  runCreateAction(event: FilePickerCreateActionEvent): Promise<void>;
+  /**
+   * `selectPath` for an item a create action just made. The user is looking at
+   * the popup, so a path outside `rootPath` — which `selectPath` would only
+   * report as a `validation` error, never shown there — is told as a
+   * `creation` error in the popup instead of the press seeming to do nothing.
+   */
+  private selectCreatedPath;
   /**
    * Re-fetches the listing of the directory currently being browsed. Call it
    * when the directory changed outside the picker, e.g. after a
@@ -18446,6 +18586,14 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
    * would be the surprising behavior.
    */
   private updateSelection;
+  /**
+   * Emits `selectionChange` and `itemSelectionChange` for a committed value.
+   * Items are looked up by the absolute form of each trimmed entry, which is
+   * how listings are indexed — a free-text value keeps any surrounding
+   * whitespace the user typed, but still resolves to the item it names.
+   */
+  private emitSelection;
+  private indexListedItems;
   private normalizedValueRoot;
   /** Maps an internal absolute path into the `valueRoot`-relative value space. */
   private toValueSpace;
@@ -18475,6 +18623,16 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
       "required": false;
       "isSignal": true;
     };
+    "allowFreeText": {
+      "alias": "allowFreeText";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
     "openOnClick": {
       "alias": "openOnClick";
       "required": false;
@@ -18490,11 +18648,21 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
       "required": false;
       "isSignal": true;
     };
+    "readonly": {
+      "alias": "readonly";
+      "required": false;
+      "isSignal": true;
+    };
     "testId": {
       "alias": "testId";
       "required": false;
       "isSignal": true;
     };
+    "source": {
+      "alias": "source";
+      "required": false;
+      "isSignal": true;
+    };
     "startPath": {
       "alias": "startPath";
       "required": false;
@@ -18522,6 +18690,7 @@ export declare class TnFilePickerComponent implements ControlValueAccessor, OnIn
     };
   }, {
     "selectionChange": "selectionChange";
+    "itemSelectionChange": "itemSelectionChange";
     "pathChange": "pathChange";
     "createAction": "createAction";
     "error": "error";
@@ -18605,31 +18774,35 @@ export declare class TnFilePickerHarness extends ComponentHarness {
    */
   getValue(): Promise<string>;
   /**
-   * Sets the picker's value by typing a single path into the path input and
-   * committing it via the input's `change` event, exactly as a user pressing
-   * Enter would.
+   * Sets the picker's value by typing into the path input and committing it
+   * via the input's `change` event, exactly as a user pressing Enter would.
+   *
+   * By default tn-file-picker treats typed input as ONE path even in
+   * multi-select mode (commas are legal in paths, so they are never list
+   * separators): committing a typed path REPLACES the whole selection with
+   * that single path, and commits go through the component's normal
+   * validation — paths outside `rootPath` are rejected (the value stays
+   * unchanged and an `error` is emitted), and `callbacks.validatePath` is
+   * consulted when provided. Build a real multi-selection through the popup
+   * with {@link clickItem} + {@link clickSelect}.
    *
-   * Unlike `IxExplorerHarness.setValue` there is no `string[]` overload:
-   * tn-file-picker treats typed input as ONE path even in multi-select mode
-   * (commas are legal in paths, so they are never list separators). In
-   * multi-select, committing a typed path REPLACES the whole selection with
-   * that single path; build a real multi-selection through the popup with
-   * {@link clickItem} + {@link clickSelect}.
+   * With `allowFreeText`, the typed text is committed verbatim with no
+   * validation, and in multi-select it is split on commas — so passing a
+   * `string[]` (typed joined with `', '`) sets one entry per element.
    *
-   * Commits go through the component's normal validation: paths outside
-   * `rootPath` are rejected (the value stays unchanged and an `error` is
-   * emitted), and `callbacks.validatePath` is consulted when provided.
    * Setting an empty string clears the selection. Has no effect when
    * `allowManualInput` is false (the input is readonly).
    *
-   * @param value The path to set.
+   * @param value The path to set, or several entries for a free-text
+   *   multi-select picker.
    *
    * @example
    * ```typescript
    * await picker.setValue('/mnt/tank/media');
+   * await freeTextMultiPicker.setValue(['/mnt/tank/a', 'EXTERNAL:host\\share']);
    * ```
    */
-  setValue(value: string): Promise<void>;
+  setValue(value: string | string[]): Promise<void>;
   /**
    * Gets the path input's placeholder text.
    *
@@ -18824,8 +18997,8 @@ export declare class TnFilePickerPopupComponent implements AfterViewChecked {
   multiSelect: import("@angular/core").InputSignal<boolean>;
   /**
    * Consumer-defined creation flows rendered as buttons in the footer, next to the
-   * Select button. Pressing one emits `createAction` with the action id and the
-   * currently browsed path.
+   * Select button. Pressing one without `create` emits `createAction` with the
+   * action id and the currently browsed path; the owning picker runs its `run`.
    */
   createActions: import("@angular/core").InputSignal<FilePickerCreateAction[]>;
   currentPath: import("@angular/core").InputSignal<string>;
@@ -18838,6 +19011,8 @@ export declare class TnFilePickerPopupComponent implements AfterViewChecked {
   fileItems: import("@angular/core").InputSignal<FileSystemItem[]>;
   selectedItems: import("@angular/core").InputSignal<string[]>;
   loading: import("@angular/core").InputSignal<boolean>;
+  /** Message of a failed listing or creation, shown above the listing. */
+  errorMessage: import("@angular/core").InputSignal<string | null>;
   fileExtensions: import("@angular/core").InputSignal<string[] | undefined>;
   /**
    * Test-id base the owning picker resolved (explicit `testId`, else the bound
@@ -18900,6 +19075,7 @@ export declare class TnFilePickerPopupComponent implements AfterViewChecked {
    */
   protected readonly selectTestId: import("@angular/core").Signal<(string | number | null | undefined)[]>;
   protected readonly clearSelectionTestId: import("@angular/core").Signal<(string | number | null | undefined)[]>;
+  protected readonly errorTestId: import("@angular/core").Signal<(string | number | null | undefined)[]>;
   /** Role-first segments for the inline creation input: `input-create[-<base>]`. */
   protected readonly inlineCreateTestId: import("@angular/core").Signal<(string | number | null | undefined)[]>;
   /**
@@ -19003,6 +19179,11 @@ export declare class TnFilePickerPopupComponent implements AfterViewChecked {
       "required": false;
       "isSignal": true;
     };
+    "errorMessage": {
+      "alias": "errorMessage";
+      "required": false;
+      "isSignal": true;
+    };
     "fileExtensions": {
       "alias": "fileExtensions";
       "required": false;