@mono-lit/helper 0.0.0-stage → 0.0.2

package/dist/src/import/parse.d.ts

@@ -0,0 +1,15 @@
+import { MonoImportOptions, MonoImportType } from './types';
+/** A parsed sheet: the header row plus the data rows beneath it. */
+export interface ParsedSheet {
+    headers: string[];
+    rows: unknown[][];
+}
+/** Decide how to read `data` when the caller didn't say. */
+export declare function inferType(data: MonoImportOptions['data']): MonoImportType;
+/**
+ * Parse the caller's `data` into headers + rows.
+ *
+ * Rows above `headerRow` are dropped, which is what lets a sheet carry a title
+ * block above its table.
+ */
+export declare function parseSheet(options: MonoImportOptions): Promise<ParsedSheet>;

package/dist/src/import/types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Public types for `table.import()` — reading an edited spreadsheet back into
+ * the grid as *staged* changes.
+ */
+/** Where the sheet data comes from. Inferred from `data` when omitted. */
+export type MonoImportType = 'excel' | 'copy-paste';
+/** How a column's raw text is interpreted. */
+export type MonoImportValueType = 'string' | 'number' | 'date' | 'boolean';
+/** Decimal/grouping convention for `number` columns. */
+export type MonoImportNumberFormat = 'auto' | 'us' | 'eu';
+/** One leg of the composite key that pairs a sheet row with a table row. */
+export interface MonoImportMatch<T = any> {
+    /** Header text in the sheet. */
+    excel: string;
+    /** Field on the table row. */
+    field: string;
+    /**
+     * Normalise this key part before comparing — applied to **both** sides, so a
+     * sheet's `"  PT  Mono "` can match a row's `"PT Mono"`. Runs on top of the
+     * default normalisation (trim, collapse whitespace, lowercase).
+     */
+    transform?: (value: unknown, side: 'excel' | 'table') => unknown;
+}
+/** A column the sheet is allowed to write into a matched row. */
+export interface MonoImportColumn<T = any> {
+    /** Header text in the sheet. */
+    excel: string;
+    /** Field on the table row to stage. */
+    field: string;
+    /** How to interpret the cell (default `'string'`). */
+    type?: MonoImportValueType;
+    /** Post-process the parsed value; return `undefined` to skip the cell. */
+    transform?: (value: unknown, ctx: {
+        row: T;
+        field: string;
+        raw: unknown;
+    }) => unknown;
+}
+/** A sheet row that produced no staged change, and why. */
+export interface MonoImportRejection {
+    /** Zero-based index within the sheet's data rows. */
+    index: number;
+    /** The sheet row as `{ header: value }`. */
+    row: Record<string, unknown>;
+    /** Human-readable cause. */
+    reason?: string;
+}
+/** A sheet row that matched more than one table row. */
+export interface MonoImportAmbiguity extends MonoImportRejection {
+    /** How many table rows the strongest usable key resolved to. */
+    candidates: number;
+}
+/** One row's staged patch. */
+export interface MonoImportChange<T = any> {
+    /** The controller's string row key. */
+    rowKey: string;
+    /** The row's `keyExpr` value, for a store update. */
+    key: unknown;
+    /** The matched table row (pre-change). */
+    row: T;
+    /** field → new value. */
+    patch: Record<string, unknown>;
+}
+export interface MonoImportOptions<T = any> {
+    /** The spreadsheet file, or the text pasted out of one. */
+    data: File | Blob | ArrayBuffer | Uint8Array | string;
+    /** Force the reader; inferred from `data` when omitted. */
+    type?: MonoImportType;
+    /** Worksheet name or zero-based index (`'excel'` only; default: the first). */
+    sheet?: string | number;
+    /** 1-based row holding the headers (default `1`). */
+    headerRow?: number;
+    /** Column delimiter for pasted text. Auto-detects tab / `;` / `,`. */
+    delimiter?: string;
+    /**
+     * Composite key pairing a sheet row with a table row. Required — an import
+     * with no key would have nowhere to put its values.
+     */
+    match: Array<MonoImportMatch<T>>;
+    /** The columns the sheet may write. Required. */
+    columns: Array<MonoImportColumn<T>>;
+    /** Extra header spellings to accept, e.g. `{ 'JAN': ['Januari', 'Jan-26'] }`. */
+    headerAliases?: Record<string, string[]>;
+    /**
+     * Smallest number of key fields allowed to identify a row (default `2`).
+     * Raise it when a single shared field would produce false matches.
+     */
+    minKeyFields?: number;
+    /** Override key normalisation (applied to both sides). */
+    normalizeKey?: (value: unknown) => string;
+    /**
+     * Rows to match against. Defaults to every row the grid can produce
+     * (`table.getData()`), not just the visible page.
+     */
+    target?: T[];
+    /** Skip sheet rows — summary/total lines, blank separators, … */
+    rowFilter?: (sheetRow: Record<string, unknown>, index: number) => boolean;
+    /** Restrict which table rows may be written at all. */
+    targetFilter?: (row: T) => boolean;
+    /**
+     * Veto a write. Return `true` (or a string reason) to refuse. The reason is
+     * surfaced in `skippedRows`, so the user can be told *which* rows were
+     * ignored and why instead of silently losing them.
+     */
+    readOnly?: (row: T, field: string) => boolean | string;
+    /**
+     * `'stage'` (default) writes the changes into the grid's staged buffer.
+     * `'none'` computes everything and hands back `result.apply()`, so the result
+     * can be validated — and the import abandoned — before anything is staged.
+     */
+    apply?: 'stage' | 'none';
+    /** Decimal/grouping convention for `number` columns (default `'auto'`). */
+    numberFormat?: MonoImportNumberFormat;
+    /** Accept negative numbers, including `(1.234)` (default `true`). */
+    allowNegative?: boolean;
+    /** Sheet rows processed between yields (default `300`). */
+    chunkSize?: number;
+    /** Milliseconds to yield between chunks so the UI stays responsive (default `0`). */
+    yieldMs?: number;
+    /** Progress across the sheet's data rows. */
+    onProgress?: (done: number, total: number) => void;
+    /** Log matching decisions to the console. */
+    debug?: boolean;
+}
+export interface MonoImportResult<T = any> {
+    /** Every considered sheet row matched exactly one table row. */
+    ok: boolean;
+    /** Sheet rows considered (after `rowFilter`). */
+    total: number;
+    /** Rows that resolved to exactly one table row. */
+    matched: number;
+    /** Rows that resolved to none. */
+    unmatched: number;
+    /** Rows whose strongest usable key hit several table rows. */
+    ambiguous: number;
+    /** Matched rows that actually produced a change. */
+    changed: number;
+    /** Cells refused by `targetFilter` / `readOnly`. */
+    skipped: number;
+    /** Headers found in the sheet. */
+    headers: string[];
+    /** Headers named in `match` / `columns` that the sheet doesn't have. */
+    missingHeaders: string[];
+    /** The staged (or stageable) patches. */
+    changes: Array<MonoImportChange<T>>;
+    unmatchedRows: MonoImportRejection[];
+    ambiguousRows: MonoImportAmbiguity[];
+    skippedRows: MonoImportRejection[];
+    /** `target` with every patch applied — for validating before committing. */
+    merged: T[];
+    /** Stage the changes now. A no-op when they were already staged. */
+    apply: () => void;
+}

package/dist/src/nuxt/index.d.ts

@@ -0,0 +1,94 @@
+/// <reference path="../../vue.d.ts" />
+import { NuxtModule } from '@nuxt/schema';
+import { MonoSsrOptions } from '../vite';
+import { MonoTooltipGlobalOptions } from '../components/tooltip/tooltip-types';
+import { MonoUIConfig } from '../composables/mono-ui';
+import { MonoSkeletonDefaults } from '../composables/mono-skeleton';
+export interface MonoHelperModuleOptions extends MonoSsrOptions {
+    /** Auto-add `@mono-lit/helper/ui/index.css` to nuxt css. Default true. */
+    css?: boolean;
+    /** Register `<prefix*>` tags as custom elements (composed). Default true. */
+    customElement?: boolean;
+    /**
+     * Auto-wire SSR for shadow builds: importing `@mono-lit/helper/ui/shadow/<c>` in a
+     * `.vue` file makes its `<mono-c>` server-render (Declarative Shadow DOM) — no
+     * manual `litElementPrefix` / `exclude` lists, and nothing for the app to
+     * install (`nuxt-ssr-lit` ships as a @mono-lit/helper dependency). Default true.
+     * Set false (or keep a manual `nuxt-ssr-lit` module entry) to use the legacy
+     * manual wiring.
+     */
+    ssr?: boolean;
+    /**
+     * Wrap every LIGHT `<prefix*>` in `<ClientOnly>`. Default: **`nuxt.options.ssr !== false`**.
+     *
+     * The wrap exists so the server never renders a light-DOM custom element. It has a cost:
+     * Nuxt's `<ClientOnly>` renders its slot one tick AFTER it mounts, so the owning page's
+     * `onMounted` runs before the `<mono-*>` element exists and a `controlMonoTable(ref)` /
+     * `controlMonoForm(ref)` bound there sees `null`. Hence:
+     *  - `ssr: false` app: nothing renders on the server — no wrap, no `nuxt-ssr-lit`
+     *    (set `true` to force the legacy wrap anyway).
+     *  - `ssr: true` app: wrapped by default. Set `false` when the pages are client-only as a
+     *    WHOLE (route `mode: 'client'`, or `<ClientOnly><NuxtPage/>`) and only a shadow-built
+     *    shell server-renders: light tags are then left alone (they SSR as inert tags and
+     *    upgrade in the browser), while the server import-stub and the `<LitWrapper>` wrap of
+     *    the shadow tags a file imports stay on.
+     */
+    clientOnly?: boolean;
+    /**
+     * Tags to ALWAYS treat as shadow (SSR-wrapped) regardless of per-file imports
+     * — for components registered once in a shared plugin (e.g. nav/sidebar).
+     */
+    shadow?: string[];
+    /**
+     * Packages to add to `vite.resolve.dedupe`. Defaults to the lit family, which
+     * MUST resolve to one instance — @mono-lit/helper's externalized shadow build and
+     * `@lit-labs/ssr` / `nuxt-ssr-lit` otherwise get separate lit-html copies and
+     * hydration dies with `currentDirective._$initialize is not a function`.
+     * Merged with whatever the app already lists. Pass `false` to opt out.
+     */
+    dedupe?: string[] | false;
+    /**
+     * Packages to add to `vite.optimizeDeps.include`. Pre-bundling these keeps the
+     * optimize-deps hash stable, so Vite doesn't discover them mid-session on the
+     * first federated-route visit, re-optimize, and re-fetch @mono-lit/helper's chunks
+     * under a new `?v=` — which re-evaluates its `@customElement()` side effects
+     * and throws `'mono-nav' has already been defined`.
+     *
+     * Defaults to `['@mono-lit/devextreme']`. Entries that don't resolve from the app
+     * are dropped, because Vite hard-fails on an unresolvable include. Add your
+     * app's own federated-only deps here (or keep them in `vite.optimizeDeps`).
+     * Pass `false` to opt out.
+     */
+    optimizeInclude?: string[] | false;
+    /**
+     * The tooltip addon — the Nuxt twin of `createMonoTooltip({...})` in a Vue
+     * `main.ts`. `true` (or an options object) turns on the `mono-tooltip-content`
+     * attributes app-wide; the options WIN over those passed to `controlMonoTooltip`.
+     * Applied by a client-only plugin, so they must be JSON (no `content` /
+     * `onShow` functions, no nodes). Needs the optional peers `@floating-ui/dom` +
+     * `@floating-ui/core`.
+     */
+    tooltip?: MonoTooltipGlobalOptions | boolean;
+    /**
+     * App-wide default props for every mono component — the Nuxt twin of
+     * `createMonoUI({...})` in a Vue `main.ts`:
+     *   ui: { 'mono-button': { size: 'xs' }, 'mono-input': { size: 'sm' } }
+     * One key covers the light and the shadow build. Applied by an EARLY plugin on
+     * the server AND the client (shadow SSR must render with the same defaults the
+     * browser hydrates with). Must be JSON.
+     */
+    ui?: MonoUIConfig;
+    /**
+     * The automatic skeleton (`pending` on every mono element, drawn by phantom-ui). BUILT
+     * IN and ZERO-CONFIG: when the optional peer `@aejkatappaja/phantom-ui` resolves from the
+     * app, the module loads it in a client plugin before anything mounts and tells mono
+     * whether this is an SSR app (`nuxt.options.ssr`, which decides the automatic default of
+     * light elements). Not installed → nothing happens and `pending` is a no-op.
+     * `false` turns it off even when installed; an object sets the GLOBAL phantom defaults
+     * (`{ animation: 'pulse', duration: 1.2 }`) — the same as `createMonoUI({ skeleton })`.
+     * Must be JSON.
+     */
+    skeleton?: false | MonoSkeletonDefaults;
+}
+declare const monoHelperModule: NuxtModule;
+export default monoHelperModule;

package/dist/src/search/data-search.d.ts

@@ -0,0 +1,207 @@
+import { MonoSearchExpr, MonoSearchExprEntry } from './search-expr.js';
+export type { MonoSearchExpr, MonoSearchExprEntry };
+/**
+ * A `search-value` prop as authored: the comma-separated string form, or the
+ * array form (which additionally allows `{ field, custom }` entries).
+ */
+export type MonoSearchValue = string | MonoSearchExprEntry[];
+/** The default devextreme search operation. */
+export declare const DEFAULT_SEARCH_OPERATION = "contains";
+/**
+ * Split the string form of `search-value` on commas.
+ *
+ * Kept separate from {@link resolveSearchFields} so a component can show a user
+ * what its raw prop parsed to without also resolving `*` patterns against data.
+ */
+export declare function parseSearchValue(value: MonoSearchValue | undefined | null): MonoSearchExprEntry[];
+/**
+ * The four accepted spellings of "which fields does a typed term match".
+ *
+ * The data grid shipped this option as `searchExpr`; select and tag-input named
+ * the same idea `search-value`. Rather than pick a winner and break one of them,
+ * every surface accepts all four names for one concept — `searchExpr` is kept
+ * purely for back-compat.
+ */
+export interface MonoSearchFieldsAliases {
+    searchExpr?: MonoSearchValue | null;
+    'search-expr'?: MonoSearchValue | null;
+    searchValue?: MonoSearchValue | null;
+    'search-value'?: MonoSearchValue | null;
+}
+/** The spellings, in the order a merge reads them. */
+export declare const SEARCH_FIELDS_KEYS: readonly ["searchExpr", "search-expr", "searchValue", "search-value"];
+/**
+ * Merge every spelling present into one entry list, de-duplicated by field name.
+ *
+ * They all mean the same thing, so passing two of them means the union rather
+ * than one silently shadowing the other. Order only decides *position* among
+ * equal field names — first occurrence wins, so a `{ field, custom }` entry
+ * written under one spelling isn't displaced by a plain column under another.
+ *
+ * Returns **`undefined` when none of the keys is present**, which callers rely on
+ * to mean "not configured at all" — distinctly different from `[]` ("configured,
+ * but empty"). The grid uses that difference to decide whether to leave a data
+ * source's own `searchExpr` alone.
+ */
+export declare function mergeSearchFields(src: MonoSearchFieldsAliases | undefined | null): MonoSearchExprEntry[] | undefined;
+/** Inputs to {@link resolveSearchFields}. */
+export interface ResolveSearchFieldsOptions {
+    /** The component's `search-value` prop, in either form. */
+    searchValue?: MonoSearchValue | null;
+    /**
+     * Fields to search when `search-value` is empty — a component's natural
+     * defaults (`display-value` when it's a string, then `key-value`).
+     */
+    fallbackFields?: Array<string | undefined | null>;
+    /** Loaded rows, sampled to resolve `*` patterns. */
+    rows?: readonly unknown[];
+    /**
+     * Whether the source is remote (store-backed). A remote `$filter` can only
+     * `contains` a **string** column, so a `*` pattern expands to string leaves
+     * only — `contains(Price,'x')` is invalid OData and would reject the request.
+     */
+    remote?: boolean;
+    /**
+     * Search **everything** when `search-value` is empty: `'*'` is prepended ahead
+     * of {@link fallbackFields} rather than the fallbacks being used alone.
+     *
+     * The fallbacks are kept as a safety net rather than replaced, for two reasons:
+     * a `'*'` resolves against `rows`, so before a remote source's first page has
+     * landed it expands to NOTHING and the query would silently match everything;
+     * and `textOnly` drops non-string leaves on a remote source, which would stop a
+     * numeric `key-value` being searchable. A concrete fallback entry is exempt from
+     * both — `resolveSearchEntries` treats an explicitly named field as explicit, so
+     * it survives expansion and appears exactly once.
+     */
+    defaultToWildcard?: boolean;
+}
+/** The default when nothing is configured: every top-level field. */
+export declare const DEFAULT_SEARCH_FIELDS: readonly string[];
+/**
+ * The entries a search actually runs over: the prop parsed, the fallbacks applied
+ * when it's empty, and every `*` pattern expanded against `rows`.
+ *
+ * Call this **once per query**, never per row — a pattern samples up to 20 rows,
+ * so resolving inside a row loop is O(rows × fields) on every keystroke.
+ */
+export declare function resolveSearchFields(options?: ResolveSearchFieldsOptions): MonoSearchExprEntry[];
+/**
+ * Whether a source's own `searchValue`/`searchExpr` folding can express these
+ * entries — true only for plain top-level column names.
+ *
+ * A path needs a nav selector or an `any()` lambda and a custom brings its own
+ * clause; folding would silently search either with a flat `contains` instead.
+ */
+export declare function isFoldableSearch(entries: readonly MonoSearchExprEntry[]): boolean;
+/** The plain column names among `entries` — what a source may safely be handed. */
+export declare function plainSearchFields(entries: readonly MonoSearchExprEntry[]): string[];
+/**
+ * Read a field off a row, path-aware. A wildcard path resolves to an array of
+ * every match, so the caller matches if ANY element hits.
+ */
+export declare function readSearchField(row: unknown, field: string): unknown[];
+/**
+ * The client-side row test for one query, or `null` when there is nothing to
+ * match on.
+ *
+ * `null` means "no opinion" — the caller should keep every row rather than filter
+ * them all away, which is what a component with no configured fields wants.
+ */
+export declare function searchRowPredicate(entries: readonly MonoSearchExprEntry[], query: string, operation?: string): ((row: any) => boolean) | null;
+/**
+ * The devextreme `$filter` expression for one query — an OR across every entry —
+ * or `null` when there is nothing to send.
+ */
+export declare function searchRemoteFilter(entries: readonly MonoSearchExprEntry[], query: string, operation?: string): unknown;
+/** The structural slice of a devextreme DataSource a search touches. */
+export interface SearchableSource {
+    searchOperation?: (op?: string) => unknown;
+    searchExpr?: (expr?: unknown) => unknown;
+    searchValue?: (v?: unknown) => unknown;
+    filter?: (v?: unknown) => unknown;
+    pageIndex?: (n?: number) => unknown;
+    load?: () => PromiseLike<unknown> | unknown;
+}
+/** Inputs to {@link MonoSourceSearch.apply}. */
+export interface ApplySourceSearchOptions extends ResolveSearchFieldsOptions {
+    /** The text the user typed. */
+    query: string;
+    /** devextreme search operation (default `'contains'`). */
+    operation?: string;
+}
+/**
+ * Applies a search to a bound DataSource, choosing between the source's own
+ * folding and a controller-built `$filter`.
+ *
+ * The reason this needs to be an object rather than a function is the **base
+ * filter**: when the search can't be folded it has to live in `source.filter()`,
+ * which is also where the consumer's own filter lives. So the consumer's filter is
+ * captured and every search re-composes from that snapshot — otherwise each
+ * keystroke would AND another search clause onto the previous one and the filter
+ * would grow without bound.
+ *
+ * The snapshot is not taken once and kept. Before every apply (and every clear)
+ * the live `filter()` is compared against what this instance last WROTE: if it
+ * differs, the consumer changed the filter in the meantime — a watcher scoping
+ * the source — and that becomes the new base. Snapshotting only at `bind()` made
+ * the next keystroke overwrite such a filter with the stale one, and "restored"
+ * the stale one on clear.
+ *
+ * ```ts
+ * private _search = new MonoSourceSearch()
+ * // on `dataSource` change:
+ * this._search.bind(this.dataSource)
+ * // on a (debounced) query:
+ * await this._search.apply(this.dataSource, {
+ *   query, searchValue: this.searchValue, fallbackFields: [...], rows, remote: true,
+ * })
+ * ```
+ */
+export declare class MonoSourceSearch {
+    /** The source the captured base filter belongs to. */
+    private _source;
+    /** The consumer's own `filter()`, as it was before any search touched it. */
+    private _baseFilter;
+    /** Whether the last apply wrote a search clause into `filter()`. */
+    private _wroteFilter;
+    /** What the source HELD after this instance's last `filter()` write (read back). */
+    private _lastWritten;
+    /**
+     * Snapshot a source's own filter. Safe to call repeatedly — the snapshot is
+     * only (re)taken when the source identity actually changes, so it can be driven
+     * straight from a `willUpdate` branch. A change on the SAME source is picked up
+     * by `_syncBase` at the next apply/clear instead.
+     */
+    bind(source: unknown): void;
+    /**
+     * Adopt a filter the consumer set on the source since the last write —
+     * anything the source holds that is not what this instance last put there.
+     * `_writeFilter` records what the source HOLDS after a write (read back), so a
+     * source that ignores writes reads back as its own last write and is never
+     * re-adopted, and one that normalises compares against its normalised value.
+     */
+    private _syncBase;
+    /** Write `filter()` and remember what the source holds afterwards. */
+    private _writeFilter;
+    /**
+     * Undo whatever this instance wrote onto the source, then forget it.
+     *
+     * `reset()` alone is not enough at teardown. With `defaultToWildcard`, a `'*'`
+     * entry is never foldable, so the search is AND-ed into `source.filter()` — the
+     * same slot the CONSUMER's own filter lives in. Only `apply()` ever restores the
+     * captured base (and only when the next apply happens to be foldable), so an
+     * element torn down mid-query used to leave its clause behind on a DataSource
+     * the app still owns and shares.
+     *
+     * Deliberately does NOT `load()`: teardown must not issue a request. The next
+     * consumer of the source reloads on its own terms.
+     */
+    clear(source?: unknown): void;
+    /** Forget the captured state without touching the source. */
+    reset(): void;
+    /**
+     * Push `query` onto `source` and reload it. Returns the resolved entries so a
+     * caller can reuse them for its own client-side rendering without re-resolving.
+     */
+    apply(source: unknown, options: ApplySourceSearchOptions): Promise<MonoSearchExprEntry[]>;
+}

package/dist/src/search/field-path.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Path field expressions.
+ *
+ * Any field a component addresses — a `mono-table-th` `field`, a `searchExpr` /
+ * `search-value` entry on the grid, select, tag-input or dropdown-table — may be
+ * a **path** into nested / collection data instead of a flat top-level key:
+ *
+ * - `"Job.Name"`       — nested property (dot path)
+ * - `"User.[1].Id"`    — array index
+ * - `"User.[*].Name"`  — wildcard (all elements of a collection)
+ *
+ * Client (array) sources resolve these against plain JS objects; remote OData
+ * sources translate them to navigation (`Job.Name` → `Job/Name`) and, for a
+ * wildcard search/filter, a lambda (`User.[*].Name` + `'x'` + `contains` →
+ * `User/any(d: contains(d/Name,'x'))`).
+ *
+ * `.` and `[` are RESERVED — a literal top-level key containing them is not
+ * addressable here. Brackets must be their own dot-segment (`User.[1].Id`, not
+ * `User[1].Id`). Every consumer gates on {@link isPath} first and falls through
+ * to plain `row[field]` when it returns false, so plain fields are unchanged.
+ */
+export type FieldSegment = {
+    kind: 'key';
+    name: string;
+} | {
+    kind: 'index';
+    index: number;
+} | {
+    kind: 'wildcard';
+};
+export interface ParsedFieldPath {
+    segments: FieldSegment[];
+    hasWildcard: boolean;
+    raw: string;
+}
+/** Whether `field` is a path expression (contains `.` or `[`) vs a plain key. */
+export declare function isPath(field: string): boolean;
+/** Parse a path field into ordered segments (cached). Plain keys → one `key` segment. */
+export declare function parseFieldPath(field: string): ParsedFieldPath;
+/**
+ * Resolve a path field against a row. Returns a **scalar** when the path has no
+ * wildcard, or a flattened **array** of matches when it does (`User.[*].Name` →
+ * `string[]`). Missing links yield `undefined` (scalar) / are skipped (wildcard).
+ */
+export declare function getFieldValue(row: unknown, field: string): unknown;
+/**
+ * Write `value` into `obj` at a dot/index path, creating intermediate `{}`/`[]`
+ * as needed. Wildcard paths are ambiguous to write — a `console.warn` + no-op.
+ */
+export declare function setFieldValue(obj: Record<string, unknown>, field: string, value: unknown): void;
+/**
+ * Project a row down to the given key paths, **rebuilding the nested shape**.
+ *
+ * This is what `<mono-table-checkbox>`'s `key-value` produces, so a selection can
+ * be handed to an API in the shape the API expects rather than as flat values:
+ *
+ * ```ts
+ * projectFields(row, ['Id'])                            // { Id: 8 }
+ * projectFields(row, ['Company.Name'])                  // { Company: { Name: 'Hey' } }
+ * projectFields(row, ['Transaction.[*].Id'])            // { Transaction: [{ Id: 4 }] }
+ * projectFields(row, ['Company.Name', 'Transaction.[*].Id'])
+ * //                → { Company: { Name: 'Hey' }, Transaction: [{ Id: 4 }] }
+ * ```
+ *
+ * Separate from {@link setFieldValue}, which deliberately refuses wildcard paths
+ * (there is no single place to write to). Here a wildcard is not ambiguous at all:
+ * it MAPS over the source array, emitting one projected element per entry — so the
+ * result mirrors the source's own cardinality. Several paths merge into one object,
+ * and an empty key list means "the row itself".
+ */
+export declare function projectFields(row: unknown, keys: string[]): unknown;
+/**
+ * Merge a staged `patch` (keys may be path fields) into a **clone** of `row`.
+ * Path keys nest via {@link setFieldValue}; plain keys are set directly. The
+ * original row is never mutated. Used by the client (array/optimistic) save path.
+ */
+export declare function mergePatch<T>(row: T, patch: Record<string, unknown>): T;
+/**
+ * OData selector for `$orderby` / `$select` / nav column filters — dotted path
+ * with `.` → `/` (`Job.Name` → `Job/Name`). Returns `null` when the path has any
+ * index/wildcard segment (not expressible as a plain selector); the caller warns
+ * and skips.
+ */
+export declare function toODataSelector(field: string): string | null;
+/** A devextreme filter clause: a `[selector, op, value]` triple or a wrapped raw lambda `[string]`. */
+export type ODataClause = [selector: string, op: string, value: unknown] | [raw: string];
+/**
+ * Quote/serialize a value as an OData literal (numbers/bools bare, strings quoted
+ * with `''` escaping). Exported so `mono-filter-builder` shares one set of quoting
+ * rules instead of restating them.
+ */
+export declare function odataLiteral(value: unknown): string;
+/** Map a devextreme operator token to its OData comparison keyword. */
+export declare function odataComparison(op: string): string | null;
+/**
+ * Build a devextreme filter clause for a (possibly path) field.
+ *
+ * - plain / dotted-nav → a `[selector, op, value]` triple (`['Job/Name','contains','x']`),
+ *   which devextreme serializes to a nav filter.
+ * - wildcard → a single wrapped raw lambda clause
+ *   (`["User/any(d: contains(d/Name,'x'))"]`) — the raw-string passthrough devextreme
+ *   filter arrays honor. Slots into OR/AND groups as one group member.
+ *
+ * Returns `null` when the field can't be expressed (a second wildcard, or an
+ * index segment mixed into a remote path); the caller warns + skips.
+ */
+export declare function toODataClause(field: string, op: string, value: unknown): ODataClause | null;

package/dist/src/search/filter-eval.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Compile a devextreme filter expression (the array form `monoFilterBuilder`
+ * emits via `changed({ type: 'array' })`) into a client-side row predicate, so a
+ * built filter can narrow an array-backed grid the same way a remote store would
+ * narrow from a `$filter`. Remote devextreme stores read the array directly; this
+ * is the client-side mirror for sources that only accept a `(row) => boolean`.
+ *
+ * The grammar handled is exactly the subset `treeToArray` produces: `[field, op,
+ * value]` triples, `'and'` / `'or'` joined groups, `['!', expr]` negation, with
+ * `between` / `in` / blank checks already expanded to those primitives.
+ */
+export declare function compileFilterPredicate(expr: unknown): ((row: any) => boolean) | null;
+/** AND-combine two optional devextreme filter expressions (either may be null). */
+export declare function andFilters(a: unknown, b: unknown): unknown;
+/** A client-side row filter, as `monoArraySource.filter()` stores it. */
+export type RowPredicate = (row: any, index: number) => boolean;
+/**
+ * AND-combine optional row predicates — the array-source twin of `andFilters`.
+ *
+ * Returns the lone member UNWRAPPED when only one is present, so a caller that
+ * compares the result by reference (the grid's compose memo) sees the same
+ * function back and does not treat "nothing changed" as a change.
+ */
+export declare function andPredicates(...fns: Array<RowPredicate | null | undefined>): RowPredicate | null;
+/**
+ * Join expressions with `and` / `or`, dropping nulls and returning a lone member
+ * unwrapped — devextreme's filter arrays interleave the join token between
+ * members (`[a, 'or', b, 'or', c]`) rather than nesting pairs.
+ */
+export declare function joinFilters(parts: unknown[], join: 'and' | 'or'): unknown;

package/dist/src/search/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@mono-lit/helper/search` — the shared data-search module.
+ *
+ * Everything about "which fields does a typed term match, and how does that
+ * become a filter" lives here, independent of any component: path expressions,
+ * `*` patterns, custom clause builders, the client predicate, the remote
+ * `$filter`, and the DataSource application strategy.
+ *
+ * Consumed by `monoDataGrid`, `mono-select`, `mono-tag-input` and
+ * `mono-dropdown-table`. It imports nothing outside this folder, so it can be
+ * lifted into another package unchanged.
+ */
+export { isPath, parseFieldPath, getFieldValue, setFieldValue, projectFields, mergePatch, toODataSelector, odataLiteral, odataComparison, toODataClause, } from './field-path.js';
+export type { FieldSegment, ParsedFieldPath, ODataClause } from './field-path.js';
+export { compileFilterPredicate, andFilters, andPredicates, joinFilters } from './filter-eval.js';
+export type { RowPredicate } from './filter-eval.js';
+export { normalizeSearchExpr, plainSearchColumns, searchEntryField, searchEntryFor, hasCustomSearch, hasWildcardSearch, isWildcardPattern, expandWildcard, resolveSearchEntries, customRemoteClause, customPredicate, } from './search-expr.js';
+export type { MonoSearchCustomCtx, MonoSearchCustomResult, MonoSearchExpr, MonoSearchExprCustom, MonoSearchExprEntry, ResolveSearchOptions, } from './search-expr.js';
+export { odataSearchExpr } from './odata-search.js';
+export type { MonoODataSearchOptions } from './odata-search.js';
+export { DEFAULT_SEARCH_OPERATION, SEARCH_FIELDS_KEYS, parseSearchValue, mergeSearchFields, resolveSearchFields, isFoldableSearch, plainSearchFields, readSearchField, searchRowPredicate, searchRemoteFilter, MonoSourceSearch, } from './data-search.js';
+export type { MonoSearchValue, MonoSearchFieldsAliases, ResolveSearchFieldsOptions, ApplySourceSearchOptions, SearchableSource, } from './data-search.js';

package/dist/src/search/odata-search.d.ts

@@ -0,0 +1,18 @@
+import { MonoSearchExpr } from './search-expr.js';
+/** Metadata and selected properties used to compile a safe remote OData search. */
+export interface MonoODataSearchOptions {
+    /** CSDL returned by the service's `$metadata` endpoint. */
+    metadata: string | XMLDocument;
+    /** Fully qualified EDM type (`Default.Customer`) or its short name (`Customer`). */
+    entityType: string;
+    /** Properties made available to the search box, in display order. */
+    fields: readonly string[];
+}
+/**
+ * Compile selected CSDL properties into the grid's existing `searchExpr` contract.
+ *
+ * Strings retain case-insensitive matching unless the service annotates the property
+ * with `Mono.Search.CaseFold=false`; numeric EDM properties accept a complete numeric
+ * input as equality. Unsupported EDM types do not generate invalid text predicates.
+ */
+export declare function odataSearchExpr(options: MonoODataSearchOptions): MonoSearchExpr;