@bitforgehq/ui 0.4.0 → 0.5.0-next.4

package/types/bitforgehq-ui-testing.d.ts

@@ -90,8 +90,11 @@ interface BfHarnessFilters extends BaseHarnessFilters {
   label?: string | RegExp;
 }
 /**
- * Harness for `bf-select`. It works by option label, so a test never needs the native option
- * values (an object option's native value is its index).
+ * Harness for `bf-select`, in both modes: the styled list under a mouse (its options render in the
+ * CDK overlay container while open, found through the field's `aria-controls`) and the native
+ * `<select>` under a coarse pointer. It also drives the native select with `data-bf-select` that a
+ * stacked `bf-table` renders as its Sort by select without `provideBfSelect()`. It works by option
+ * label, so a test never needs the option values (an object option's native value is its index).
  *
  * @example
  * const select = await loader.getHarness(BfSelectHarness.with({ label: 'Project' }));
@@ -102,11 +105,13 @@ interface BfHarnessFilters extends BaseHarnessFilters {
 export declare class BfSelectHarness extends ComponentHarness {
   /** The host element's selector. */
   static hostSelector: string;
-  private readonly select;
+  private readonly nativeSelect;
+  private readonly combobox;
   private readonly label;
   private readonly error;
   private readonly help;
   private readonly nativeOptions;
+  private readonly styledOptions;
   /**
    * A predicate for a select with the given label.
    * @param filters The label (text or pattern) and the CDK's selector and ancestor filters.
@@ -118,6 +123,13 @@ export declare class BfSelectHarness extends ComponentHarness {
    * @returns The label text.
    */
   getLabel(): Promise<string>;
+  /**
+   * Whether the styled option list is open (`aria-expanded`). Always false for the native select,
+   * whose list belongs to the platform.
+   * @returns True while the list is open.
+   * @since 0.5.0
+   */
+  isOpen(): Promise<boolean>;
   /**
    * The selected option's label, `''` while nothing is selected.
    * @returns The label text.
@@ -131,7 +143,8 @@ export declare class BfSelectHarness extends ComponentHarness {
   /**
    * Chooses the option with this label, as a user would: the select's `value` becomes that
    * option's value. Throws, leaving the value as it is, for an unknown or disabled option and
-   * while the select itself is disabled.
+   * while the select itself is disabled. On a read-only select it changes nothing, in both modes:
+   * the styled list does not open, and the native select restores the shown option.
    * @param label The option's label.
    */
   selectOption(label: string): Promise<void>;
@@ -160,10 +173,25 @@ export declare class BfSelectHarness extends ComponentHarness {
    * @returns The help text, `''` when there is none.
    */
   getHelpText(): Promise<string>;
-  /** Focuses the native select. */
+  /** Focuses the field, or the native select. */
   focus(): Promise<void>;
-  /** Blurs the native select, which marks a bound form field touched. */
+  /** Blurs the field, or the native select, which marks a bound form field touched. */
   blur(): Promise<void>;
+  /** The element the user works with: the native select, else the styled field. */
+  private control;
+  /** Opens the styled list with a click into the field; does nothing while it is open. */
+  private open;
+  /** Closes the styled list with `Escape`, as a user would; does nothing while it is closed. */
+  private close;
+  /** The styled list's options with their labels, from the listbox the field controls. */
+  private listOptions;
+  /** The styled select's options with their labels, from its hidden copy, whether open or not. */
+  private styledChoices;
+  /**
+   * `selectOption()` for the styled list: checks the option, then opens the list and clicks it. A
+   * read-only select stops after the check, as its list never opens.
+   */
+  private selectStyled;
   /** Every native option; the placeholder or hidden empty option comes first, empty and disabled. */
   private options;
 }
@@ -1362,4 +1390,487 @@ export declare class BfToggleHarness extends ComponentHarness {
    */
   getErrorText(): Promise<string>;
 }
+/**
+ * Harness for `bf-file-input`, in both looks. `addFiles()` drops files on the field, so they go
+ * through the same `accept`, `maxSize` and `maxFiles` rules as a real drop; read the outcome with
+ * `getFileNames()` and `getRejected()`. It works by file name, so a test never needs the rows.
+ *
+ * @example
+ * const input = await loader.getHarness(BfFileInputHarness.with({ label: 'Documents' }));
+ * await input.addFiles([new File(['x'], 'cv.pdf', { type: 'application/pdf' })]);
+ * expect(await input.getFileNames()).toEqual(['cv.pdf']);
+ * @summary Test harness for the file input: drops files and reads the list and rejections
+ * @since 0.5.0
+ */
+export declare class BfFileInputHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly label;
+  private readonly error;
+  private readonly box;
+  private readonly pick;
+  private readonly ariaLabelText;
+  private readonly dropzone;
+  private readonly nativeInput;
+  private readonly names;
+  private readonly removeButtons;
+  private readonly rejectedNames;
+  private readonly rejectedMessages;
+  /**
+   * A predicate for a file input with the given label.
+   * @param filters The label (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfFileInputHarness>;
+  /**
+   * The visible label without the required mark, else `ariaLabel`.
+   * @returns The label text.
+   */
+  getLabel(): Promise<string>;
+  /**
+   * The error text under the field (an explicit message, or the first form error once touched).
+   * @returns The error text, `''` when there is none.
+   */
+  getErrorText(): Promise<string>;
+  /**
+   * The look of the field.
+   * @returns `'dropzone'` or `'field'`.
+   */
+  getVariant(): Promise<'field' | 'dropzone'>;
+  /**
+   * Whether the field is disabled.
+   * @returns True when disabled.
+   */
+  isDisabled(): Promise<boolean>;
+  /**
+   * Whether the field is read-only: it has no pick target.
+   * @returns True when read-only.
+   */
+  isReadonly(): Promise<boolean>;
+  /**
+   * Drops files on the field, as a user would. On a disabled or read-only field it does nothing,
+   * like the UI.
+   * @param files The files to drop.
+   */
+  addFiles(files: File[]): Promise<void>;
+  /**
+   * The names of the chosen files, in order (rejected files are not included).
+   * @returns The file names.
+   */
+  getFileNames(): Promise<string[]>;
+  /**
+   * The files the last pick or drop refused, each with its reason, until they are dismissed.
+   * @returns The rejected files' names and messages.
+   */
+  getRejected(): Promise<{
+    name: string;
+    message: string;
+  }[]>;
+  /**
+   * Removes the chosen file with this name, as the row's remove button does. Throws when no
+   * chosen file has that name or the field cannot be edited.
+   * @param name The file's name.
+   */
+  removeFile(name: string): Promise<void>;
+}
+/**
+ * Harness for `bf-image-input`. `addFile()` drops the image on the tile, so it goes through the
+ * same `accept` and `maxSize` rules as a real drop; read the outcome with `hasPreview()`,
+ * `getPreviewSrc()` and `getRejectedMessage()`. jsdom has no `URL.createObjectURL`, so a picked
+ * image shows no preview there: assert on the bound value, or stub `URL.createObjectURL` to read
+ * the preview.
+ *
+ * @example
+ * const avatar = await loader.getHarness(BfImageInputHarness.with({ label: 'Profile picture' }));
+ * await avatar.addFile(new File(['x'], 'me.png', { type: 'image/png' }));
+ * expect(fixture.componentInstance.avatar()?.name).toBe('me.png');
+ * await avatar.addFile(new File(['x'], 'cv.pdf', { type: 'application/pdf' }));
+ * expect(await avatar.getRejectedMessage()).toBe('Not an accepted type');
+ * @summary Test harness for the image input: drops an image on it and reads the preview
+ * @since 0.5.0
+ */
+export declare class BfImageInputHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly label;
+  private readonly error;
+  private readonly tile;
+  private readonly preview;
+  private readonly removeButton;
+  private readonly rejection;
+  private readonly nativeInput;
+  /**
+   * A predicate for an image input with the given label.
+   * @param filters The label (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfImageInputHarness>;
+  /**
+   * The visible label without the required mark, else the tile's `aria-label`.
+   * @returns The label text.
+   */
+  getLabel(): Promise<string>;
+  /**
+   * The error text beside the tile (an explicit message, or the first form error once touched).
+   * @returns The error text, `''` when there is none.
+   */
+  getErrorText(): Promise<string>;
+  /**
+   * Whether the control is disabled.
+   * @returns True when disabled.
+   */
+  isDisabled(): Promise<boolean>;
+  /**
+   * Whether the control is read-only: its tile is not a button and there are no Upload or Remove
+   * buttons.
+   * @returns True when read-only.
+   */
+  isReadonly(): Promise<boolean>;
+  /**
+   * Whether the tile shows an image, picked or from `src`. A picked image needs
+   * `URL.createObjectURL`, which jsdom lacks: stub it to see one.
+   * @returns True while an image shows.
+   */
+  hasPreview(): Promise<boolean>;
+  /**
+   * The `src` of the shown image.
+   * @returns The URL, or null while the tile is empty.
+   */
+  getPreviewSrc(): Promise<string | null>;
+  /**
+   * Drops an image on the tile, as a user would. On a disabled or read-only control it does
+   * nothing, like the UI. It waits on no timer, so it works under fake timers and `fakeAsync`.
+   * @param file The image to drop.
+   */
+  addFile(file: File): Promise<void>;
+  /**
+   * Presses Remove, which clears the picked and the existing image. Throws while there is no
+   * image or the control cannot be edited.
+   */
+  remove(): Promise<void>;
+  /**
+   * The reason the last pick was refused, until the next pick or Remove.
+   * @returns The message, `''` when the last pick was accepted.
+   */
+  getRejectedMessage(): Promise<string>;
+}
+/**
+ * Harness for `bf-media-card`. jsdom never loads images, so `loadImage()` and `failImage()` fire
+ * the image's `load` and `error` events the way a browser would; `getState()` then tells what the
+ * image area shows.
+ *
+ * @example
+ * const card = await loader.getHarness(BfMediaCardHarness.with({ label: 'Starfall' }));
+ * await card.failImage();
+ * expect(await card.getState()).toBe('failed');
+ * @summary Test harness for a media card: its image state, its messages and its selection
+ * @since 0.5.0
+ */
+export declare class BfMediaCardHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly media;
+  private readonly image;
+  private readonly heading;
+  private readonly loadingLabel;
+  private readonly failedLabel;
+  private readonly selectButton;
+  /**
+   * A predicate for a card with the given title (its first heading).
+   * @param filters The title (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfMediaCardHarness>;
+  /**
+   * The card's title: the text of the first heading in its body.
+   * @returns The title, `''` without a heading.
+   */
+  getTitle(): Promise<string>;
+  /**
+   * What the image area shows: `empty` (no `src`, not loading), `loading` (the skeleton),
+   * `loaded` (the image) or `failed` (the failure message).
+   * @returns The state.
+   */
+  getState(): Promise<'empty' | 'loading' | 'loaded' | 'failed'>;
+  /**
+   * The URL of the image.
+   * @returns Its `src`, `''` while there is no image element.
+   */
+  getSrc(): Promise<string>;
+  /**
+   * The alternative text of the image.
+   * @returns Its `alt`, `''` for a decorative image or no image.
+   */
+  getAlt(): Promise<string>;
+  /**
+   * The caption over the skeleton while loading (the `loading` label when none is set).
+   * @returns The caption, `''` when the card is not loading.
+   */
+  getLoadingLabel(): Promise<string>;
+  /**
+   * The failure message.
+   * @returns The message, `''` when the image has not failed.
+   */
+  getFailedMessage(): Promise<string>;
+  /** Fires the image's `load` event, as a browser does when it arrives. Throws without one. */
+  loadImage(): Promise<void>;
+  /** Fires the image's `error` event, as a browser does when it fails. Throws without one. */
+  failImage(): Promise<void>;
+  /**
+   * Whether the card has a select button (`selectable`).
+   * @returns True for a selectable card.
+   */
+  isSelectable(): Promise<boolean>;
+  /**
+   * Whether the card is selected (its select button is pressed).
+   * @returns True while selected; false for a card that is not selectable.
+   */
+  isSelected(): Promise<boolean>;
+  /** Clicks the select button, toggling the selection. Throws for a card that is not selectable. */
+  toggleSelected(): Promise<void>;
+  private requireImage;
+}
+/**
+ * Harness for `bf-image-tile`. jsdom never loads images, so `loadImage()` and `failImage()` fire
+ * the picture's `load` and `error` events the way a browser would; `getState()` then tells what
+ * the tile shows. `click()` clicks the tile's `bfAction` link or button.
+ *
+ * @example
+ * const tile = await loader.getHarness(BfImageTileHarness.with({ label: 'Dragon' }));
+ * await tile.loadImage();
+ * expect(await tile.getState()).toBe('loaded');
+ * @summary Test harness for an image tile: its picture state, title, meta, selection and action
+ * @since 0.5.0
+ */
+export declare class BfImageTileHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly tile;
+  private readonly media;
+  private readonly image;
+  private readonly title;
+  private readonly meta;
+  private readonly placeholder;
+  private readonly failed;
+  private readonly action;
+  /**
+   * A predicate for a tile with the given title.
+   * @param filters The title (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfImageTileHarness>;
+  /**
+   * The tile's title: the text of its default slot.
+   * @returns The title, `''` without one.
+   */
+  getTitle(): Promise<string>;
+  /**
+   * The meta line under the title.
+   * @returns Its text, `''` without one.
+   */
+  getMeta(): Promise<string>;
+  /**
+   * What the picture area shows: `empty` (the placeholder), `loading` (the skeleton), `loaded`
+   * (the picture) or `failed` (the failure message).
+   * @returns The state.
+   */
+  getState(): Promise<'empty' | 'loading' | 'loaded' | 'failed'>;
+  /**
+   * The URL of the picture.
+   * @returns Its `src`, `''` while there is no image element.
+   */
+  getSrc(): Promise<string>;
+  /**
+   * The alternative text of the picture.
+   * @returns Its `alt`, `''` for a decorative picture or no picture.
+   */
+  getAlt(): Promise<string>;
+  /**
+   * The placeholder text while there is no picture.
+   * @returns The text, `''` when the tile is not empty.
+   */
+  getPlaceholderText(): Promise<string>;
+  /**
+   * The failure message.
+   * @returns The message, `''` when the picture has not failed.
+   */
+  getFailedMessage(): Promise<string>;
+  /**
+   * Whether the tile is marked selected.
+   * @returns True while `selected` is set.
+   */
+  isSelected(): Promise<boolean>;
+  /**
+   * Whether the tile is clickable (has a `bfAction` link or button).
+   * @returns True with an action.
+   */
+  isClickable(): Promise<boolean>;
+  /** Clicks the tile's `bfAction` link or button. Throws for a tile without one. */
+  click(): Promise<void>;
+  /** Fires the picture's `load` event, as a browser does when it arrives. Throws without one. */
+  loadImage(): Promise<void>;
+  /** Fires the picture's `error` event, as a browser does when it fails. Throws without one. */
+  failImage(): Promise<void>;
+  private requireImage;
+}
+/**
+ * Harness for `bf-image-viewer`, the lightbox `BfImageViewerService.open()` renders. It renders
+ * in the CDK overlay container outside the tested component, so get it through
+ * `TestbedHarnessEnvironment.documentRootLoader(fixture)`. jsdom never loads images: call
+ * `loadImage()` to fire the shown image's `load` event.
+ *
+ * @example
+ * const viewer = await TestbedHarnessEnvironment.documentRootLoader(fixture).getHarness(
+ *   BfImageViewerHarness,
+ * );
+ * await viewer.next();
+ * expect(await viewer.getIndex()).toBe(1);
+ * @summary Test harness for an image viewer: its image, index, caption, steps and close
+ * @since 0.5.0
+ */
+export declare class BfImageViewerHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly image;
+  private readonly frame;
+  private readonly caption;
+  private readonly counter;
+  private readonly closeButton;
+  private readonly nextButton;
+  private readonly previousButton;
+  /**
+   * A predicate for a viewer with the given accessible name.
+   * @param filters The name (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfImageViewerHarness>;
+  /**
+   * The viewer's accessible name (`ariaLabel`, else the `imageViewer` label).
+   * @returns The name.
+   */
+  getLabel(): Promise<string>;
+  /**
+   * The 0-based index of the shown image.
+   * @returns The index.
+   */
+  getIndex(): Promise<number>;
+  /**
+   * How many images the viewer steps through.
+   * @returns The number of images.
+   */
+  getCount(): Promise<number>;
+  /**
+   * The counter's text ("2 of 5"); a viewer of one image shows none.
+   * @returns The counter, `''` for a single image.
+   */
+  getCounterText(): Promise<string>;
+  /**
+   * The URL of the shown image.
+   * @returns Its `src`, `''` while it shows the failure message.
+   */
+  getSrc(): Promise<string>;
+  /**
+   * The alternative text of the shown image.
+   * @returns Its `alt`.
+   */
+  getAlt(): Promise<string>;
+  /**
+   * The caption under the shown image.
+   * @returns The caption, `''` without one.
+   */
+  getCaption(): Promise<string>;
+  /**
+   * Whether the shown image has loaded (no spinner and no failure message).
+   * @returns True once it has loaded.
+   */
+  isLoaded(): Promise<boolean>;
+  /**
+   * Whether the shown image failed to load (the failure message shows).
+   * @returns True after its `error` event.
+   */
+  hasFailed(): Promise<boolean>;
+  /** Fires the shown image's `load` event, as a browser does when it arrives. */
+  loadImage(): Promise<void>;
+  /** Fires the shown image's `error` event, as a browser does when it fails. */
+  failImage(): Promise<void>;
+  /** Clicks the next button. Throws for a viewer of one image (it has none). */
+  next(): Promise<void>;
+  /** Clicks the previous button. Throws for a viewer of one image (it has none). */
+  previous(): Promise<void>;
+  /**
+   * Presses a key inside the viewer: ArrowLeft and ArrowRight step, Home and End jump, Escape
+   * closes.
+   * @param key The key to press.
+   */
+  pressKey(key: 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'Escape'): Promise<void>;
+  /** Clicks the close button. */
+  close(): Promise<void>;
+  private requireImage;
+}
+/**
+ * Harness for `bf-chat-composer` (`@bitforgehq/ui/overlay`). Its `label` filter matches the text
+ * field's name: the visible label, else its `aria-label` ("Message" by default).
+ *
+ * @example
+ * const composer = await loader.getHarness(BfChatComposerHarness);
+ * await composer.setValue('Three names for a cafe');
+ * await composer.send();
+ * expect(await composer.getValue()).toBe('');
+ * @summary Test harness for the chat composer: types, sends, stops and reads its state
+ * @since 0.5.0
+ */
+export declare class BfChatComposerHarness extends ComponentHarness {
+  /** The host element's selector. */
+  static hostSelector: string;
+  private readonly textarea;
+  private readonly label;
+  private readonly button;
+  /**
+   * A predicate for a composer with the given field name.
+   * @param filters The name (text or pattern) and the CDK's selector and ancestor filters.
+   * @returns The predicate for `getHarness()` and friends.
+   */
+  static with(filters?: BfHarnessFilters): HarnessPredicate<BfChatComposerHarness>;
+  /**
+   * The text field's name: the visible label, else its `aria-label`.
+   * @returns The name, `''` without one.
+   */
+  getLabel(): Promise<string>;
+  /**
+   * The text in the field.
+   * @returns The current text.
+   */
+  getValue(): Promise<string>;
+  /**
+   * Replaces the text as the user would type it (`changed` and the value update).
+   * @param text The new text.
+   */
+  setValue(text: string): Promise<void>;
+  /** Sends the text with the send button, as a click does. Does nothing while it cannot send. */
+  send(): Promise<void>;
+  /** Sends the text with `Enter` in the field, as the keyboard does. */
+  pressEnter(): Promise<void>;
+  /** Stops the running reply with the stop button. Does nothing unless a reply is running. */
+  stop(): Promise<void>;
+  /**
+   * Whether a reply is running, so the button stops instead of sending.
+   * @returns True while running.
+   */
+  isRunning(): Promise<boolean>;
+  /**
+   * Whether the composer is disabled (its text field is).
+   * @returns True when disabled.
+   */
+  isDisabled(): Promise<boolean>;
+  /**
+   * Whether the button can send (or stop) now: not disabled and, to send, with text.
+   * @returns True when a press acts.
+   */
+  canAct(): Promise<boolean>;
+  /**
+   * The button's name, "Send" or "Stop" by default.
+   * @returns The button's text (also its accessible name beside an icon).
+   */
+  getButtonLabel(): Promise<string>;
+}
 export type { BfHarnessFilters, BfJsdomShimOptions, BfTestingOptions };