@mk-kit/ui 0.36.0 → 0.38.0

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

@@ -83,8 +83,24 @@ declare class MkFormField implements MkFieldContext {
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Control size; nested controls inherit it. */
     readonly size: _angular_core.InputSignal<MkSize>;
+    /**
+     * Where the label sits: above the control (default), or `float` — inside
+     * the control, sliding up once it is focused or has a value. Floating works
+     * with `mkInput` / textarea and any control bound with `ngModel` or a
+     * `formControl`; the placeholder stays hidden until the label has moved.
+     */
+    readonly labelPosition: _angular_core.InputSignal<"top" | "float">;
+    private readonly host;
     /** The projected control's form binding, when it has one. */
     private readonly ngControl;
+    /** A control inside the field has focus. */
+    protected readonly focused: _angular_core.WritableSignal<boolean>;
+    /** Last value read straight from a native control (fallback when no NgControl). */
+    private readonly domValue;
+    /** The field holds a non-empty value (drives the floating label). */
+    protected readonly hasValue: _angular_core.Signal<boolean>;
+    /** Track a native control's value for the floating label when nothing else reports it. */
+    protected readDomValue(target: EventTarget | null): void;
     /**
      * Bumped on every change of the bound control so the computed state below
      * re-reads it. `AbstractControl` is not signal-based, so this bridges its
@@ -120,7 +136,7 @@ declare class MkFormField implements MkFieldContext {
      */
     readonly describedBy: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkFormField, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkFormField, "mk-form-field", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "errorMessages": { "alias": "errorMessages"; "required": false; "isSignal": true; }; "errorOn": { "alias": "errorOn"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, {}, ["ngControl"], ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkFormField, "mk-form-field", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "errorMessages": { "alias": "errorMessages"; "required": false; "isSignal": true; }; "errorOn": { "alias": "errorOn"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "labelPosition": { "alias": "labelPosition"; "required": false; "isSignal": true; }; }, {}, ["ngControl"], ["*"], true, never>;
 }
 
 /** One field-level error to surface in {@link MkFormErrorSummary}. */
@@ -602,6 +618,251 @@ declare class MkSelect implements ControlValueAccessor, OnDestroy {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkSelect, "mk-select", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
 }
 
+/** One row of an `mk-listbox`. */
+interface MkListboxOption {
+    /** Text shown (and matched by typeahead / the filter). */
+    label: string;
+    /** Value committed to the model when selected. */
+    value: unknown;
+    /** Secondary line under the label. */
+    description?: string;
+    /** Skipped by keyboard, not selectable. */
+    disabled?: boolean;
+    /** Options sharing a `group` render under one heading (keep them adjacent). */
+    group?: string;
+}
+/** A rendered row: either a group heading or an option with its index in the visible list. */
+type Row = {
+    kind: 'group';
+    label: string;
+    id: string;
+} | {
+    kind: 'option';
+    option: MkListboxOption;
+    index: number;
+};
+/**
+ * Listbox — a standalone, always-visible selection list (the ARIA `listbox`
+ * pattern) for one or many values: settings panes, "choose a template"
+ * pickers, side-by-side assignments, any place a dropdown would hide choices
+ * the user should see at once.
+ *
+ * Keyboard: Up / Down move, Home / End jump, PageUp / PageDown skip ten,
+ * type to jump to a label, Enter / Space select (toggle when `multiple`),
+ * Shift+Arrow / Shift+click extend a range, Ctrl/Cmd+A selects all. Focus
+ * stays on the list (`aria-activedescendant`). With `filterable`, a search
+ * box above the list narrows it by label or description.
+ *
+ * Implements `ControlValueAccessor` and a two-way `value` model — a single
+ * value, or an array when `multiple`.
+ *
+ * ```html
+ * <mk-listbox [options]="plans" [(value)]="plan" ariaLabel="Plan" />
+ * <mk-listbox multiple filterable [options]="people" [(ngModel)]="reviewers" />
+ * ```
+ */
+declare class MkListbox implements ControlValueAccessor, OnDestroy {
+    private readonly field;
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    private readonly listRef;
+    /** The rows to choose from. */
+    readonly options: _angular_core.InputSignal<readonly MkListboxOption[]>;
+    /** Allow several values; the model becomes an array. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Show a search box that narrows the list by label / description. */
+    readonly filterable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly filterPlaceholder: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Single-select only: moving with the arrow keys selects immediately
+     * (default `true`); `false` requires Enter / Space to commit.
+     */
+    readonly selectionFollowsFocus: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Control size. Ignored when nested in an `mk-form-field`. */
+    readonly size: _angular_core.InputSignal<MkSize>;
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Accessible name when there is no visible label / form field. */
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
+    /** Text shown when no option matches the filter. */
+    readonly emptyText: _angular_core.InputSignal<string | undefined>;
+    /** Two-way value: one value, or an array when `multiple`. */
+    readonly value: _angular_core.ModelSignal<unknown>;
+    /** Emitted after the user changes the selection (not on programmatic writes). */
+    readonly change: _angular_core.OutputEmitterRef<unknown>;
+    readonly listId: string;
+    protected readonly filterId: string;
+    protected readonly query: _angular_core.WritableSignal<string>;
+    protected readonly activeIndex: _angular_core.WritableSignal<number>;
+    private readonly cvaDisabled;
+    private onChange;
+    private onTouched;
+    private typeahead;
+    private typeaheadTimer?;
+    /** Range anchor for Shift selection (index in the visible list). */
+    private anchor;
+    protected readonly effectiveSize: _angular_core.Signal<MkSize>;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    protected readonly isInvalid: _angular_core.Signal<boolean>;
+    protected readonly labelledBy: _angular_core.Signal<string | null>;
+    protected readonly describedBy: _angular_core.Signal<string | null>;
+    /** Options that match the filter, in source order. */
+    protected readonly visible: _angular_core.Signal<MkListboxOption[]>;
+    /** Visible options with group headings interleaved. */
+    protected readonly rows: _angular_core.Signal<Row[]>;
+    protected readonly selectedValues: _angular_core.Signal<unknown[]>;
+    protected readonly activeId: _angular_core.Signal<string | null>;
+    constructor();
+    protected optionId(index: number): string;
+    protected isSelected(option: MkListboxOption): boolean;
+    /** Focus the list. */
+    focus(): void;
+    protected onOptionClick(index: number, event: MouseEvent): void;
+    protected onFilterInput(event: Event): void;
+    protected onFilterKeydown(event: KeyboardEvent): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    protected onBlur(): void;
+    /** Move the active row by `delta` (wrapping for ±1), extending the selection with Shift. */
+    private step;
+    private jump;
+    private firstEnabled;
+    private lastEnabled;
+    private typeaheadSearch;
+    private commit;
+    /** Select every enabled option between two visible indexes (replacing, or adding to, the selection). */
+    private selectRange;
+    private selectAll;
+    private emit;
+    ngOnDestroy(): void;
+    writeValue(value: unknown): void;
+    registerOnChange(fn: (value: unknown) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkListbox, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkListbox, "mk-listbox", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "filterable": { "alias": "filterable"; "required": false; "isSignal": true; }; "filterPlaceholder": { "alias": "filterPlaceholder"; "required": false; "isSignal": true; }; "selectionFollowsFocus": { "alias": "selectionFollowsFocus"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "ariaLabelledby"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "change": "change"; }, never, never, true, never>;
+}
+
+/** One node of a cascader: a leaf, or a parent with `children`. */
+interface MkCascaderOption {
+    label: string;
+    value: unknown;
+    children?: readonly MkCascaderOption[];
+    disabled?: boolean;
+}
+/**
+ * Cascader — a select whose choices are a hierarchy shown as side-by-side
+ * columns (region → country → city, category → subcategory, org unit → team).
+ * Each pick opens the next column; picking a leaf commits the whole path.
+ *
+ * The value is the **path** of option values (`['eu', 'pl', 'krk']`) by
+ * default, or just the leaf's value with `valueMode="leaf"`. Parents are only
+ * selectable with `selectParents` (a click on one then commits, and its
+ * children stay reachable).
+ *
+ * Keyboard: Up / Down move within a column, Right opens the children, Left
+ * goes back, Enter / Space selects, typing jumps to a label, Escape closes.
+ * `expandTrigger="hover"` opens columns on pointer hover as well as click.
+ *
+ * Implements `ControlValueAccessor` and a two-way `value` model.
+ *
+ * ```html
+ * <mk-cascader [options]="regions" [(value)]="location" placeholder="Where?" clearable />
+ * ```
+ */
+declare class MkCascader implements ControlValueAccessor, OnDestroy {
+    private readonly field;
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    private readonly host;
+    private readonly injector;
+    private readonly triggerRef;
+    private readonly panelRef;
+    /** The hierarchy to choose from. */
+    readonly options: _angular_core.InputSignal<readonly MkCascaderOption[]>;
+    /** Two-way value: the path of values (default) or the leaf value (`valueMode="leaf"`). */
+    readonly value: _angular_core.ModelSignal<unknown>;
+    /** Bind the full path of values (default) or only the chosen option's value. */
+    readonly valueMode: _angular_core.InputSignal<"path" | "leaf">;
+    /** Allow committing a parent option (click / Enter on it) instead of leaves only. */
+    readonly selectParents: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Open the next column on click (default) or also on pointer hover. */
+    readonly expandTrigger: _angular_core.InputSignal<"click" | "hover">;
+    readonly placeholder: _angular_core.InputSignal<string>;
+    /** Text between the labels of the chosen path. */
+    readonly separator: _angular_core.InputSignal<string>;
+    readonly clearable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Control size. Ignored when nested in an `mk-form-field`. */
+    readonly size: _angular_core.InputSignal<MkSize>;
+    /** Emitted after the user commits or clears a value. */
+    readonly change: _angular_core.OutputEmitterRef<unknown>;
+    readonly triggerId: string;
+    readonly panelId: string;
+    readonly valueId: string;
+    protected readonly open: _angular_core.WritableSignal<boolean>;
+    /** Row index highlighted in each open column, left to right. */
+    protected readonly activePath: _angular_core.WritableSignal<number[]>;
+    private readonly cvaDisabled;
+    private onChange;
+    private onTouched;
+    private typeahead;
+    private typeaheadTimer?;
+    protected readonly effectiveSize: _angular_core.Signal<MkSize>;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    protected readonly isInvalid: _angular_core.Signal<boolean>;
+    protected readonly isRequired: _angular_core.Signal<boolean>;
+    protected readonly labelledBy: _angular_core.Signal<string | null>;
+    protected readonly describedBy: _angular_core.Signal<string | null>;
+    /** The options along the committed value, or `[]`. */
+    protected readonly selectedPath: _angular_core.Signal<MkCascaderOption[]>;
+    protected readonly displayLabel: _angular_core.Signal<string>;
+    /**
+     * Columns rendered in the panel: the root list, then the children of every
+     * opened parent along the active path. The last entry of the path is the
+     * cursor — resting on a parent does not open it (click, hover or → does).
+     */
+    protected readonly columns: _angular_core.Signal<readonly MkCascaderOption[][]>;
+    /** The column the keyboard cursor is in. */
+    private readonly cursorColumn;
+    protected readonly activeId: _angular_core.Signal<string | null>;
+    constructor();
+    protected optionId(column: number, row: number): string;
+    protected isOnPath(column: number, row: number): boolean;
+    protected isSelected(column: number, option: MkCascaderOption): boolean;
+    protected isCursor(column: number, row: number): boolean;
+    protected toggle(): void;
+    protected openPanel(): void;
+    protected close(restoreFocus?: boolean): void;
+    protected onTriggerKeydown(event: KeyboardEvent): void;
+    protected onFocusOut(event: FocusEvent): void;
+    protected onPanelFocusout(event: FocusEvent): void;
+    protected onOptionClick(column: number, row: number): void;
+    protected onOptionHover(column: number, row: number): void;
+    protected clear(event: Event): void;
+    protected onPanelKeydown(event: KeyboardEvent): void;
+    /** Point the cursor at `(column, row)`, trimming any deeper columns. */
+    private setCursor;
+    /** Open the children of `(column, row)` and move the cursor onto the first enabled one. */
+    private expand;
+    private stepRow;
+    private firstEnabled;
+    private lastEnabled;
+    private typeaheadSearch;
+    private commit;
+    private emit;
+    /** Row indexes of a path of options. */
+    private indexPath;
+    /** Depth-first search for the option whose value is `value` (leaf mode). */
+    private findPath;
+    ngOnDestroy(): void;
+    writeValue(value: unknown): void;
+    registerOnChange(fn: (value: unknown) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkCascader, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkCascader, "mk-cascader", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "valueMode": { "alias": "valueMode"; "required": false; "isSignal": true; }; "selectParents": { "alias": "selectParents"; "required": false; "isSignal": true; }; "expandTrigger": { "alias": "expandTrigger"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "separator": { "alias": "separator"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "change": "change"; }, never, never, true, never>;
+}
+
 /** A single suggestion for {@link MkAutocomplete}. */
 interface MkAutocompleteOption {
     /** Text shown to the user and used as the input display value when chosen. */
@@ -3582,5 +3843,5 @@ declare class MkRangeSlider implements ControlValueAccessor, Validator, OnDestro
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkRangeSlider, "mk-range-slider", never, { "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "minLabel": { "alias": "minLabel"; "required": false; "isSignal": true; }; "maxLabel": { "alias": "maxLabel"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
 }
 
-export { MK_CARD_BRAND_NAMES, MK_IBAN_LENGTHS, MK_KEYBOARD_LAYOUT_QWERTY_PL, MK_PHONE_COUNTRIES, MK_POSTAL_FORMATS, MK_TAX_ID_FORMATS, MkAutocomplete, MkButtonToggle, MkButtonToggleGroup, MkCardNumberInput, MkCodeEditor, MkColorPicker, MkCurrencyInput, MkFileUpload, MkFormErrorSummary, MkFormField, MkI18nInput, MkIbanInput, MkInput, MkInputGroup, MkMention, MkMentionPanel, MkMultiSelect, MkNumberInput, MkNumericKeypad, MkOnScreenKeyboard, MkOnScreenKeyboardTrigger, MkOtp, MkPasswordInput, MkPhoneInput, MkPostalCodeInput, MkRadio, MkRadioGroup, MkRangeSlider, MkRating, MkRepeater, MkRepeaterEmpty, MkRepeaterRow, MkSelect, MkSignaturePad, MkSlider, MkSubmitInput, MkSwitch, MkTagInput, MkTaxIdInput, MkTransferList, MkTreeSelect, mkCountryFlag, mkDetectCardBrand, mkIbanChecksum, mkIbanIsValid, mkIbanValidator, mkLuhnCheck, mkNipChecksum, mkPostalCodeValidator, mkPostalFormat, mkTaxIdFormat, mkTaxIdIsValid, mkTaxIdValidator };
-export type { MkAutocompleteFilterMode, MkAutocompleteOption, MkCardBrand, MkCodeValidity, MkFormError, MkI18nLocale, MkI18nValue, MkKeyboardActionKey, MkKeyboardKey, MkKeyboardLayout, MkMentionFilterMode, MkMentionOption, MkMentionSearchEvent, MkMentionSelectEvent, MkMultiSelectFilterMode, MkMultiSelectOption, MkNumericKeypadMode, MkOnScreenKeyboardTarget, MkPasswordRule, MkPhoneCountry, MkPhoneValue, MkPostalFormat, MkRange, MkRepeaterRowContext, MkSelectOption, MkTaxIdFormat, MkTransferItem, MkUploadFile, MkUploadFn, MkUploadRejection, MkUploadStatus, MkUploadValueFormat };
+export { MK_CARD_BRAND_NAMES, MK_IBAN_LENGTHS, MK_KEYBOARD_LAYOUT_QWERTY_PL, MK_PHONE_COUNTRIES, MK_POSTAL_FORMATS, MK_TAX_ID_FORMATS, MkAutocomplete, MkButtonToggle, MkButtonToggleGroup, MkCardNumberInput, MkCascader, MkCodeEditor, MkColorPicker, MkCurrencyInput, MkFileUpload, MkFormErrorSummary, MkFormField, MkI18nInput, MkIbanInput, MkInput, MkInputGroup, MkListbox, MkMention, MkMentionPanel, MkMultiSelect, MkNumberInput, MkNumericKeypad, MkOnScreenKeyboard, MkOnScreenKeyboardTrigger, MkOtp, MkPasswordInput, MkPhoneInput, MkPostalCodeInput, MkRadio, MkRadioGroup, MkRangeSlider, MkRating, MkRepeater, MkRepeaterEmpty, MkRepeaterRow, MkSelect, MkSignaturePad, MkSlider, MkSubmitInput, MkSwitch, MkTagInput, MkTaxIdInput, MkTransferList, MkTreeSelect, mkCountryFlag, mkDetectCardBrand, mkIbanChecksum, mkIbanIsValid, mkIbanValidator, mkLuhnCheck, mkNipChecksum, mkPostalCodeValidator, mkPostalFormat, mkTaxIdFormat, mkTaxIdIsValid, mkTaxIdValidator };
+export type { MkAutocompleteFilterMode, MkAutocompleteOption, MkCardBrand, MkCascaderOption, MkCodeValidity, MkFormError, MkI18nLocale, MkI18nValue, MkKeyboardActionKey, MkKeyboardKey, MkKeyboardLayout, MkListboxOption, MkMentionFilterMode, MkMentionOption, MkMentionSearchEvent, MkMentionSelectEvent, MkMultiSelectFilterMode, MkMultiSelectOption, MkNumericKeypadMode, MkOnScreenKeyboardTarget, MkPasswordRule, MkPhoneCountry, MkPhoneValue, MkPostalFormat, MkRange, MkRepeaterRowContext, MkSelectOption, MkTaxIdFormat, MkTransferItem, MkUploadFile, MkUploadFn, MkUploadRejection, MkUploadStatus, MkUploadValueFormat };

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

@@ -0,0 +1,98 @@
+import * as _angular_core from '@angular/core';
+import * as _mk_kit_ui_core from '@mk-kit/ui/core';
+import { MkQueryField, MkQueryGroup, MkSize, mkIsQueryGroup, MkQueryRule, MkQueryCombinator, MkQueryNode } from '@mk-kit/ui/core';
+import { MkSelectOption } from '@mk-kit/ui/forms';
+
+/**
+ * QueryBuilder — a rule / group tree the user assembles from your `fields`,
+ * held as plain JSON (`MkQueryGroup`) in the two-way `query` model. Pair it
+ * with `mkQueryToPredicate()` to filter rows in the browser, with
+ * `MkTableDataSource.setQuery()` to send it to the server, or with
+ * `mkQueryToText()` for a readable summary.
+ *
+ * ```html
+ * <mk-query-builder [fields]="fields" [(query)]="query" allowNot />
+ *
+ * fields: MkQueryField[] = [
+ *   { key: 'name', label: 'Name' },
+ *   { key: 'orders', label: 'Orders', type: 'number' },
+ *   { key: 'status', label: 'Status', type: 'select', options: [{ label: 'Active', value: 'active' }, …] },
+ *   { key: 'since', label: 'Customer since', type: 'date' },
+ *   { key: 'vip', label: 'VIP', type: 'boolean' },
+ * ];
+ * rows = computed(() => this.all.filter(mkQueryToPredicate(this.query(), this.fields)));
+ * ```
+ */
+declare class MkQueryBuilder {
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    /** The filterable fields, in picker order. */
+    readonly fields: _angular_core.InputSignal<readonly MkQueryField[]>;
+    /** The query tree (two-way). Starts as an empty `and` group. */
+    readonly query: _angular_core.ModelSignal<MkQueryGroup>;
+    /** How deep groups may nest (0 = rules only). */
+    readonly maxDepth: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Offer a *Not* toggle on every group. */
+    readonly allowNot: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Control size (default `sm`). */
+    readonly size: _angular_core.InputSignal<MkSize>;
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    /** Reset to an empty group. */
+    clear(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkQueryBuilder, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkQueryBuilder, "mk-query-builder", never, { "fields": { "alias": "fields"; "required": true; "isSignal": true; }; "query": { "alias": "query"; "required": false; "isSignal": true; }; "maxDepth": { "alias": "maxDepth"; "required": false; "isSignal": true; }; "allowNot": { "alias": "allowNot"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "query": "queryChange"; }, never, never, true, never>;
+}
+
+/**
+ * One group of the builder — its combinator toggle, rules, nested groups and
+ * the add / remove actions. Used by `mk-query-builder`; every edit emits a
+ * new immutable group upward.
+ */
+declare class MkQueryGroupComponent {
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    readonly group: _angular_core.InputSignal<MkQueryGroup>;
+    readonly fields: _angular_core.InputSignal<readonly MkQueryField[]>;
+    readonly depth: _angular_core.InputSignalWithTransform<number, unknown>;
+    readonly maxDepth: _angular_core.InputSignalWithTransform<number, unknown>;
+    readonly allowNot: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly root: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly size: _angular_core.InputSignal<MkSize>;
+    /** A new version of this group after an edit. */
+    readonly groupChange: _angular_core.OutputEmitterRef<MkQueryGroup>;
+    /** The user removed this (non-root) group. */
+    readonly remove: _angular_core.OutputEmitterRef<void>;
+    protected readonly fieldOptions: _angular_core.Signal<MkSelectOption[]>;
+    protected readonly canNest: _angular_core.Signal<boolean>;
+    protected readonly booleanOptions: _angular_core.Signal<MkSelectOption[]>;
+    protected isGroup: typeof mkIsQueryGroup;
+    protected fieldOf(rule: MkQueryRule): MkQueryField | undefined;
+    protected typeOf(rule: MkQueryRule): string;
+    protected operatorOptions(rule: MkQueryRule): MkSelectOption[];
+    protected needsValue(rule: MkQueryRule): boolean;
+    protected selectOptions(rule: MkQueryRule): MkSelectOption[];
+    protected isList(rule: MkQueryRule): boolean;
+    protected isRange(rule: MkQueryRule): boolean;
+    protected asArray(value: unknown): unknown[];
+    protected rangePart(rule: MkQueryRule, index: 0 | 1): unknown;
+    protected dateValue(v: unknown): Date | null;
+    protected numberValue(v: unknown): number | null;
+    protected textValue(v: unknown): string;
+    protected setCombinator(combinator: MkQueryCombinator): void;
+    protected toggleNot(): void;
+    protected addRule(): void;
+    protected addGroup(): void;
+    protected removeAt(index: number): void;
+    protected replaceAt(index: number, node: MkQueryNode): void;
+    protected setField(index: number, rule: MkQueryRule, key: unknown): void;
+    protected setOperator(index: number, rule: MkQueryRule, op: unknown): void;
+    protected setValue(index: number, rule: MkQueryRule, value: unknown): void;
+    protected setRangePart(index: number, rule: MkQueryRule, part: 0 | 1, value: unknown): void;
+    protected setDate(index: number, rule: MkQueryRule, d: Date | null): void;
+    protected setDateRange(index: number, rule: MkQueryRule, part: 0 | 1, d: Date | null): void;
+    protected onTextInput(index: number, rule: MkQueryRule, event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkQueryGroupComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkQueryGroupComponent, "mk-query-group", never, { "group": { "alias": "group"; "required": true; "isSignal": true; }; "fields": { "alias": "fields"; "required": true; "isSignal": true; }; "depth": { "alias": "depth"; "required": false; "isSignal": true; }; "maxDepth": { "alias": "maxDepth"; "required": false; "isSignal": true; }; "allowNot": { "alias": "allowNot"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "root": { "alias": "root"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, { "groupChange": "groupChange"; "remove": "remove"; }, never, never, true, never>;
+}
+
+export { MkQueryBuilder, MkQueryGroupComponent };

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

@@ -2,6 +2,7 @@ import * as _mk_kit_ui_table from '@mk-kit/ui/table';
 import * as _angular_core from '@angular/core';
 import { TemplateRef, Signal } from '@angular/core';
 import * as _mk_kit_ui_core from '@mk-kit/ui/core';
+import { MkQueryGroup } from '@mk-kit/ui/core';
 import { Observable } from 'rxjs';
 
 /**
@@ -677,6 +678,8 @@ interface MkDataRequest {
     sort: MkSortState | null;
     /** Free-text filter query (`''` = none). */
     filter: string;
+    /** Structured filter from `mk-query-builder` (`null` = none). Compacted: no empty groups or unfinished rules. */
+    query: MkQueryGroup | null;
 }
 /** One page of server data returned by a {@link MkDataFetcher}. */
 interface MkDataPage<T> {
@@ -789,6 +792,7 @@ declare class MkTableDataSource<T> {
     private readonly _pageSize;
     private readonly _sort;
     private readonly _filter;
+    private readonly _query;
     /** Rows of the current page (`[]` until the first load lands). */
     readonly rows: Signal<T[]>;
     /** Total row count across all pages (feed to `mk-pagination`'s `total`). */
@@ -805,6 +809,8 @@ declare class MkTableDataSource<T> {
     readonly sort: Signal<MkSortState | null>;
     /** Current filter query (updates immediately, even while debouncing). */
     readonly filter: Signal<string>;
+    /** Current structured query, or `null`. */
+    readonly query: Signal<MkQueryGroup | null>;
     /** True when a settled load reported no rows at all. */
     readonly empty: Signal<boolean>;
     /** Monotonic request id — settles from older epochs are discarded. */
@@ -834,6 +840,12 @@ declare class MkTableDataSource<T> {
      * flushes it early. A no-op when the query is unchanged.
      */
     setFilter(query: string): void;
+    /**
+     * Set (or clear with `null`) the structured query from `mk-query-builder`.
+     * Empty groups and unfinished rules are dropped before the request; a query
+     * with nothing left is sent as `null`. Resets to page 1 and loads at once.
+     */
+    setQuery(query: MkQueryGroup | null): void;
     /**
      * Re-run the current request immediately (e.g. after a mutation). Flushes a
      * pending debounced filter, since the request reads the live filter value.