@mk-kit/ui 0.37.0 → 0.38.0

package/types/mk-kit-ui-testing.d.ts

@@ -0,0 +1,344 @@
+import { ComponentFixture } from '@angular/core/testing';
+
+/**
+ * Filters every harness lookup accepts. `selector` narrows the host elements
+ * considered (e.g. a class or attribute your template sets); `text` matches
+ * the host's trimmed text content — a string must match exactly, a RegExp
+ * is tested.
+ */
+interface MkHarnessFilters {
+    selector?: string;
+    text?: string | RegExp;
+}
+/** Constructor shape of every harness class: a static `hostSelector`. */
+interface MkHarnessType<T extends MkHarness> {
+    new (host: MkTestElement, loader: MkHarnessLoader): T;
+    readonly hostSelector: string;
+}
+/** Keys accepted by `MkTestElement.sendKeys` besides printable characters. */
+type MkTestKey = 'Enter' | 'Escape' | 'Tab' | 'Backspace' | 'Delete' | ' ' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
+/**
+ * A DOM element wrapped for tests: reads are synchronous, every interaction
+ * dispatches the same events a user would and then settles change detection
+ * (`fixture.detectChanges()` + `whenStable()`), so the next read sees the
+ * updated view.
+ */
+declare class MkTestElement {
+    /** The underlying element — reach for it when a harness has no getter. */
+    readonly native: HTMLElement;
+    /** Flush change detection after an interaction. */
+    readonly settle: () => Promise<void>;
+    constructor(
+    /** The underlying element — reach for it when a harness has no getter. */
+    native: HTMLElement, 
+    /** Flush change detection after an interaction. */
+    settle?: () => Promise<void>);
+    /** Trimmed text content with whitespace collapsed. */
+    text(): string;
+    attr(name: string): string | null;
+    hasClass(name: string): boolean;
+    /** Read a DOM property (`value`, `checked`, `open`, …). */
+    prop<T = unknown>(name: string): T;
+    matches(selector: string): boolean;
+    isFocused(): boolean;
+    /** Native `disabled`, `aria-disabled="true"` or a `--disabled` host class. */
+    isDisabled(): boolean;
+    query(selector: string): MkTestElement | null;
+    queryAll(selector: string): MkTestElement[];
+    /** Like `query`, but throws a readable error when nothing matches. */
+    child(selector: string): MkTestElement;
+    /** pointerdown → mousedown → focus → pointerup → mouseup → click, like a user. */
+    click(): Promise<void>;
+    hover(): Promise<void>;
+    leave(): Promise<void>;
+    focus(): Promise<void>;
+    blur(): Promise<void>;
+    /**
+     * Type into an input/textarea/contenteditable character by character —
+     * keydown, `value` append, `input`, keyup — then settle. Use `setValue`
+     * to replace the value in one go.
+     */
+    type(text: string): Promise<void>;
+    /** Set the value of an input/textarea/select and fire `input` + `change`. */
+    setValue(value: string): Promise<void>;
+    clear(): Promise<void>;
+    /** Dispatch keydown/keyup for each key. Printable single characters are also typed. */
+    sendKeys(...keys: Array<MkTestKey | (string & {})>): Promise<void>;
+    /** Dispatch any event on the element and settle. */
+    dispatch(event: Event): Promise<void>;
+    private describe;
+}
+/**
+ * Finds harnesses under a root element. Create one with
+ * `MkHarnessLoader.fromFixture(fixture)`; use `.document()` for content that
+ * mk-kit teleports into `document.body` (dialogs, toasts, menus, select
+ * panels) and `.within(el)` to scope lookups.
+ */
+declare class MkHarnessLoader {
+    readonly root: Element;
+    readonly settle: () => Promise<void>;
+    constructor(root: Element, settle: () => Promise<void>);
+    /**
+     * Loader rooted at the fixture's host element. Every interaction runs
+     * `fixture.detectChanges()` and awaits `fixture.whenStable()` afterwards,
+     * so it works in zoneless and zone-based TestBeds alike.
+     */
+    static fromFixture(fixture: ComponentFixture<unknown>): MkHarnessLoader;
+    /** Same settle function, rooted at `document.body` — for overlays. */
+    document(): MkHarnessLoader;
+    within(root: Element | MkTestElement): MkHarnessLoader;
+    /** Wrap the root element itself. */
+    rootElement(): MkTestElement;
+    element(selector: string): MkTestElement;
+    elements(selector: string): MkTestElement[];
+    /** First matching harness; throws when there is none. */
+    get<T extends MkHarness>(type: MkHarnessType<T>, filters?: MkHarnessFilters): Promise<T>;
+    getOrNull<T extends MkHarness>(type: MkHarnessType<T>, filters?: MkHarnessFilters): Promise<T | null>;
+    has<T extends MkHarness>(type: MkHarnessType<T>, filters?: MkHarnessFilters): Promise<boolean>;
+    getAll<T extends MkHarness>(type: MkHarnessType<T>, filters?: MkHarnessFilters): Promise<T[]>;
+}
+declare function matchText(actual: string, expected: string | RegExp): boolean;
+/**
+ * Base class of every mk-kit harness. Subclasses declare `hostSelector`
+ * and expose user-level actions (`click()`, `selectOption()`, …) and reads
+ * (`isChecked()`, `text()`), so specs never depend on the component's DOM.
+ */
+declare abstract class MkHarness {
+    /** The component's host element. */
+    readonly host: MkTestElement;
+    protected readonly loader: MkHarnessLoader;
+    static readonly hostSelector: string;
+    constructor(
+    /** The component's host element. */
+    host: MkTestElement, loader: MkHarnessLoader);
+    protected settle(): Promise<void>;
+    /** Query inside the host. */
+    protected q(selector: string): MkTestElement | null;
+    protected qAll(selector: string): MkTestElement[];
+    /** Query the whole document — for panels teleported to `document.body`. */
+    protected qDocument(selector: string): MkTestElement | null;
+    /** Element referenced by an `aria-controls` / `aria-owns` id on `from`. */
+    protected controlled(from: MkTestElement, attribute?: string): MkTestElement | null;
+}
+/** Resolve "by index or by label" arguments shared by option-style harnesses. */
+declare function pickBy<T>(items: T[], which: number | string | RegExp, label: (item: T) => string, what: string): T;
+
+/** `button[mkButton]` / `a[mkButton]`. */
+declare class MkButtonHarness extends MkHarness {
+    static readonly hostSelector = "button[mkButton], a[mkButton], .mk-button";
+    text(): string;
+    click(): Promise<void>;
+    focus(): Promise<void>;
+    isDisabled(): boolean;
+    isLoading(): boolean;
+    tone(): string | null;
+    /** `solid` | `soft` | `outline` | `ghost` | `link`. */
+    variant(): string | null;
+    size(): string | null;
+}
+/** Native `input[mkInput]` / `textarea[mkInput]`. */
+declare class MkInputHarness extends MkHarness {
+    static readonly hostSelector = "[mkInput], .mk-input";
+    value(): string;
+    /** Replace the value (fires `input` + `change`). */
+    setValue(value: string): Promise<void>;
+    /** Append text one character at a time (keydown / input / keyup). */
+    type(text: string): Promise<void>;
+    clear(): Promise<void>;
+    focus(): Promise<void>;
+    blur(): Promise<void>;
+    placeholder(): string;
+    type_(): string;
+    isDisabled(): boolean;
+    isInvalid(): boolean;
+    isRequired(): boolean;
+    isFocused(): boolean;
+}
+/** `mk-checkbox`. */
+declare class MkCheckboxHarness extends MkHarness {
+    static readonly hostSelector = "mk-checkbox";
+    private get input();
+    label(): string;
+    isChecked(): boolean;
+    isIndeterminate(): boolean;
+    isDisabled(): boolean;
+    isRequired(): boolean;
+    toggle(): Promise<void>;
+    check(): Promise<void>;
+    uncheck(): Promise<void>;
+    focus(): Promise<void>;
+    blur(): Promise<void>;
+}
+/** `mk-switch`. */
+declare class MkSwitchHarness extends MkHarness {
+    static readonly hostSelector = "mk-switch";
+    private get control();
+    label(): string;
+    isChecked(): boolean;
+    isDisabled(): boolean;
+    toggle(): Promise<void>;
+    check(): Promise<void>;
+    uncheck(): Promise<void>;
+    focus(): Promise<void>;
+}
+/** One `mk-radio` inside a group. */
+declare class MkRadioHarness extends MkHarness {
+    static readonly hostSelector = "mk-radio";
+    label(): string;
+    isChecked(): boolean;
+    isDisabled(): boolean;
+    select(): Promise<void>;
+    focus(): Promise<void>;
+}
+/** `mk-radio-group`. */
+declare class MkRadioGroupHarness extends MkHarness {
+    static readonly hostSelector = "mk-radio-group";
+    radios(): Promise<MkRadioHarness[]>;
+    labels(): Promise<string[]>;
+    /** Label of the checked radio, or `null`. */
+    checkedLabel(): Promise<string | null>;
+    checkedIndex(): Promise<number>;
+    /** Select by index, exact label or RegExp. */
+    select(which: number | string | RegExp): Promise<void>;
+    isDisabled(): boolean;
+}
+interface MkSelectOptionState {
+    label: string;
+    selected: boolean;
+    disabled: boolean;
+}
+/** `mk-select` — opens the teleported listbox and picks options like a user. */
+declare class MkSelectHarness extends MkHarness {
+    static readonly hostSelector = "mk-select";
+    private get trigger();
+    /** Label of the selected option, or `''` when only the placeholder shows. */
+    valueText(): string;
+    placeholder(): string;
+    isOpen(): boolean;
+    isDisabled(): boolean;
+    isInvalid(): boolean;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    focus(): Promise<void>;
+    /** Options of the (opened) listbox. Opens it if needed. */
+    options(): Promise<MkSelectOptionState[]>;
+    /** Pick an option by index, exact label or RegExp (opens the list first). */
+    selectOption(which: number | string | RegExp): Promise<void>;
+    private optionElements;
+}
+/** `mk-form-field` — label / hint / error around any control. */
+declare class MkFormFieldHarness extends MkHarness {
+    static readonly hostSelector = "mk-form-field";
+    label(): string;
+    hint(): string | null;
+    /** The visible validation message, or `null` when the field is valid/untouched. */
+    error(): string | null;
+    hasError(): boolean;
+    isRequired(): boolean;
+    /** The control inside the field, as a harness of the given type. */
+    control<T extends MkHarness>(type: Parameters<typeof this$1.loader.get<T>>[0]): Promise<T>;
+}
+
+/** `mk-tabs`. */
+declare class MkTabsHarness extends MkHarness {
+    static readonly hostSelector = "mk-tabs";
+    private tabButtons;
+    labels(): string[];
+    selectedIndex(): number;
+    selectedLabel(): string | null;
+    /** Select by index, exact label or RegExp. */
+    select(which: number | string | RegExp): Promise<void>;
+    isDisabled(which: number | string | RegExp): boolean;
+    /** The visible tab panel (`mk-tab` host). */
+    selectedPanel(): MkTestElement | null;
+    /** Text of the visible panel. */
+    selectedPanelText(): string;
+}
+/**
+ * A `[mkMenuTriggerFor]` trigger and the `mk-menu` panel it opens. The host
+ * is matched by the trigger's `aria-haspopup="menu"` (the directive's
+ * attribute is an input binding, so it is not in the DOM).
+ */
+declare class MkMenuHarness extends MkHarness {
+    static readonly hostSelector = "[aria-haspopup=\"menu\"]";
+    isOpen(): boolean;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    /** The teleported panel (`[role="menu"]`), or `null` while closed. */
+    panel(): MkTestElement | null;
+    /** Item texts of the open menu (opens it if needed). Submenu panels excluded. */
+    items(): Promise<string[]>;
+    /** Click an item by index, exact text or RegExp (opens the menu first). */
+    clickItem(which: number | string | RegExp): Promise<void>;
+    isItemDisabled(which: number | string | RegExp): Promise<boolean>;
+    private itemElements;
+}
+
+/** One data row of `mk-table`. */
+declare class MkTableRowHarness extends MkHarness {
+    static readonly hostSelector = "tr.mk-table__row";
+    /** Cell texts of the data columns (expand / select cells excluded). */
+    cells(): string[];
+    cell(index: number): string;
+    isSelected(): boolean;
+    isExpanded(): boolean;
+    click(): Promise<void>;
+    /** Toggle the selection checkbox (throws when the table is not `selectable`). */
+    toggleSelected(): Promise<void>;
+    /** Toggle the expand / tree control of the row. */
+    toggleExpanded(): Promise<void>;
+    private dataCells;
+}
+/** `mk-table`. */
+declare class MkTableHarness extends MkHarness {
+    static readonly hostSelector = "mk-table";
+    /** Header labels of the data columns, in display order. */
+    headers(): string[];
+    rows(): Promise<MkTableRowHarness[]>;
+    rowCount(): Promise<number>;
+    /** Every data cell as text: `rows()[r].cells()`. */
+    cellTexts(): Promise<string[][]>;
+    /** Click a sortable header (by index, exact label or RegExp). */
+    sortBy(which: number | string | RegExp): Promise<void>;
+    /** `'ascending' | 'descending' | 'none' | null` (null = not sortable). */
+    sortDirection(which: number | string | RegExp): string | null;
+    selectedRowCount(): Promise<number>;
+    /** Toggle the header "select all" checkbox. */
+    toggleAll(): Promise<void>;
+    isEmpty(): boolean;
+    private headerCells;
+}
+
+/**
+ * A dialog opened by `MkDialogService` (`open()`, `confirm()`, `alert()`,
+ * `prompt()`). Dialogs live in `document.body`, so look them up through
+ * `loader.document()`.
+ */
+declare class MkDialogHarness extends MkHarness {
+    static readonly hostSelector = ".mk-overlay-panel[role=\"dialog\"], .mk-overlay-panel[role=\"alertdialog\"]";
+    title(): string;
+    bodyText(): string;
+    /** Texts of every button in the dialog (header close excluded). */
+    buttons(): string[];
+    /** Click a button by index, exact text or RegExp. */
+    clickButton(which: number | string | RegExp): Promise<void>;
+    /** The header × button. */
+    close(): Promise<void>;
+    pressEscape(): Promise<void>;
+    /** The prompt dialog's text field, if any. */
+    input(): MkTestElement | null;
+    private buttonElements;
+}
+/** One toast shown by `MkToastService` (lives in `document.body` — use `loader.document()`). */
+declare class MkToastHarness extends MkHarness {
+    static readonly hostSelector = "mk-toast";
+    title(): string | null;
+    message(): string;
+    tone(): string | null;
+    actionLabel(): string | null;
+    clickAction(): Promise<void>;
+    dismiss(): Promise<void>;
+}
+
+export { MkButtonHarness, MkCheckboxHarness, MkDialogHarness, MkFormFieldHarness, MkHarness, MkHarnessLoader, MkInputHarness, MkMenuHarness, MkRadioGroupHarness, MkRadioHarness, MkSelectHarness, MkSwitchHarness, MkTableHarness, MkTableRowHarness, MkTabsHarness, MkTestElement, MkToastHarness, matchText, pickBy };
+export type { MkHarnessFilters, MkHarnessType, MkSelectOptionState, MkTestKey };

package/types/mk-kit-ui.d.ts

@@ -17,4 +17,5 @@ export * from '@mk-kit/ui/context-menu';
 export * from '@mk-kit/ui/layout';
 export * from '@mk-kit/ui/chat';
 export * from '@mk-kit/ui/query-builder';
+export * from '@mk-kit/ui/dynamic-form';
 export * from '@mk-kit/ui/media';