@mono-lit/helper 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,160 @@
+/**
+ * Search-expression entries: the fields a typed term is matched against.
+ *
+ * One grammar, shared by every component that searches data — `monoDataGrid`'s
+ * `searchExpr`, and the `search-value` prop on `mono-select`, `mono-tag-input`
+ * and `mono-dropdown-table`. An entry may be:
+ *
+ * - a plain column name (`'Nama'`)
+ * - a **path** (`'Company.Name'`, `'Transaction.[1].Name'`, `'Transaction.[*].Price'`)
+ * - a **`*` pattern** (`'*'`, `'Company.*'`, `'*.*'`, `'*.[*].*'`)
+ * - a **`{ field, custom }` clause builder**
+ *
+ * An entry is normally just a column name, and every column is searched the same
+ * way — `contains(<col>,'<term>')`. That is wrong for any column whose data isn't
+ * free text: a **boolean** can't take `contains` at all, and a **coded** column
+ * stores something the user never types (a `Month` of `0..11` can never match the
+ * string `"Jan"`).
+ *
+ * So an entry may instead be `{ field, custom }`, where `custom` receives the live
+ * term and returns the clause to use for that column:
+ *
+ * ```ts
+ * const MONTHS = ['Jan', 'Feb', 'Mar', …]
+ *
+ * searchExpr: [
+ *   'Code',
+ *   'Nama',
+ *   { field: 'Active', custom: ({ field, value }) => `${field} eq ${value}` },
+ *   { field: 'Month',  custom: ({ field, value }) => [field, '=', MONTHS.indexOf(value)] },
+ * ]
+ * ```
+ *
+ * A custom column takes part in the plain search box like any other, so it runs on
+ * every term. **Return `null`/`undefined` to opt out** of one — which is what makes
+ * the `Month` example workable: `"Jan"` → `0`, `"zzz"` → `-1` → return `null` and
+ * the column simply drops out of that query instead of matching nothing.
+ *
+ * | `custom` returns | remote (devextreme store) | array / in-memory |
+ * | --- | --- | --- |
+ * | `[field, op, value]`, or a nested `and`/`or` array | used as-is | compiled to a predicate |
+ * | `(row) => boolean` | warn + skip | used as the predicate |
+ * | `"Active eq true"` (raw OData) | wrapped as `[raw]` | warn + skip |
+ * | `null` / `undefined` / `false` | skipped | skipped |
+ *
+ * Only the explicit `{ field, custom }` shape is accepted — a `{ Month: fn }` map
+ * is not, so there is exactly one form to read and to type.
+ *
+ * An entry may also be a **`*` pattern**, resolved against the loaded rows so a
+ * grid can search everything without listing columns:
+ *
+ * ```ts
+ * searchExpr: ['*']                     // every top-level field
+ * searchExpr: ['*', '*.[*].*']          // …plus every field of every array expand
+ * searchExpr: ['*', '*.*']              // …plus every field of every object expand
+ * searchExpr: ['*', { field: 'Month', custom }]   // the explicit entry wins for Month
+ * ```
+ *
+ * Patterns read literally, segment by segment — `'*.[*].*'` covers the expand ONLY.
+ * See {@link expandWildcard} for the type rule that keeps a remote `$filter` valid.
+ *
+ * This module is pure: types + stateless helpers, no controller state, mirroring
+ * `field-path.ts`.
+ */
+/** What a `custom` builder is handed for the term being applied. */
+export interface MonoSearchCustomCtx {
+    /** The column this entry declares — echoed so the builder needn't repeat it. */
+    field: string;
+    /** The raw text the user typed, exactly as typed. */
+    value: string;
+    /** The grid's configured `searchOperation` (default `'contains'`). */
+    operation: string;
+}
+/**
+ * What a `custom` builder may return. `null` / `undefined` / `false` all mean
+ * "this column has nothing to say about this term" — skip it.
+ */
+export type MonoSearchCustomResult = string | unknown[] | ((row: any) => boolean) | null | undefined | false;
+/** A `searchExpr` entry that builds its own clause. */
+export interface MonoSearchExprCustom {
+    /** Column this entry covers — the name a bound `MonoSearchTerm.field` matches. */
+    field: string;
+    /** Build the clause for one term. See {@link MonoSearchCustomResult}. */
+    custom: (ctx: MonoSearchCustomCtx) => MonoSearchCustomResult;
+}
+/** One `searchExpr` entry: a plain column name, or a custom builder. */
+export type MonoSearchExprEntry = string | MonoSearchExprCustom;
+/** The `searchExpr` option: one entry or a list. */
+export type MonoSearchExpr = MonoSearchExprEntry | MonoSearchExprEntry[];
+/** Every usable entry, in the order written. Strings and customs, malformed dropped. */
+export declare function normalizeSearchExpr(expr: MonoSearchExpr | undefined): MonoSearchExprEntry[];
+/**
+ * The plain column names only — no `{ field, custom }` entries, no `*` patterns.
+ *
+ * This is what a SOURCE may be handed: `monoArraySource`, `storeGroupSource` and
+ * devextreme all type `searchExpr` as `string | string[]` and feed it straight to
+ * `toODataClause` — an object entry would serialize to garbage and a `'*'` would
+ * be searched as a column literally named `*`. Both are resolved by the controller
+ * instead.
+ */
+export declare function plainSearchColumns(expr: MonoSearchExpr | undefined): string[];
+/** The field name an entry covers. */
+export declare function searchEntryField(entry: MonoSearchExprEntry): string;
+/** The entry declaring `field`, if any — used to resolve a column-bound term. */
+export declare function searchEntryFor(expr: MonoSearchExpr | undefined, field: string): MonoSearchExprEntry | undefined;
+/** Whether any entry brings its own builder (so folding must be bypassed). */
+export declare function hasCustomSearch(expr: MonoSearchExpr | undefined): boolean;
+/** Whether `field` is a `*` pattern rather than a concrete column/path. */
+export declare function isWildcardPattern(field: string): boolean;
+/**
+ * Resolve a `*` pattern against real rows, returning the concrete field paths it
+ * covers — `'*.[*].*'` over `{ Detail: [{ Bulan, Ket }] }` gives
+ * `['Detail.[*].Bulan', 'Detail.[*].Ket']`, which the existing path machinery
+ * already knows how to match client-side and translate to an OData lambda.
+ *
+ * `textOnly` drops every leaf that isn't a string. A REMOTE source needs that:
+ * `contains(Price,'x')` is not valid OData and would reject the whole request, so
+ * a wildcard never emits a clause for a numeric/boolean/date column. Give such a
+ * column an explicit `{ field, custom }` entry instead. In-memory sources compare
+ * stringified values, so they keep every leaf.
+ *
+ * A field that is `null`/`undefined` in every sampled row is skipped — there is
+ * nothing to type it by.
+ */
+export declare function expandWildcard(pattern: string, rows: readonly unknown[], textOnly: boolean): string[];
+/** Options for {@link resolveSearchEntries}. */
+export interface ResolveSearchOptions {
+    /** Rows to resolve `*` patterns against (the loaded data). */
+    rows?: readonly unknown[];
+    /** Keep only string-valued leaves — required for a remote OData source. */
+    textOnly?: boolean;
+}
+/**
+ * The entries a search actually runs over: every `*` pattern replaced by the
+ * concrete fields it resolves to, in place.
+ *
+ * **An explicitly named field always wins.** A field named anywhere in the list —
+ * as a plain string or as `{ field, custom }` — is dropped from every pattern
+ * expansion regardless of order, so `['*', { field: 'Name', custom }]` and
+ * `[{ field: 'Name', custom }, '*']` both search `Name` with the custom, exactly
+ * once, at the position it was written.
+ */
+export declare function resolveSearchEntries(expr: MonoSearchExpr | undefined, options?: ResolveSearchOptions): MonoSearchExprEntry[];
+/** Whether any entry is a `*` pattern (so folding must be bypassed). */
+export declare function hasWildcardSearch(expr: MonoSearchExpr | undefined): boolean;
+/**
+ * The devextreme filter clause for one custom entry + term, or `null` to skip it.
+ *
+ * A raw string is wrapped as `[raw]` — the single-member raw-passthrough clause
+ * devextreme honours inside a filter array, the same shape `toODataClause` emits
+ * for a wildcard lambda, so it slots into the OR/AND groups unchanged.
+ */
+export declare function customRemoteClause(entry: MonoSearchExprCustom, value: string, operation: string): unknown | null;
+/**
+ * The client-side row predicate for one custom entry + term, or `null` to skip it.
+ *
+ * Filter arrays go through `compileFilterPredicate`, which already understands
+ * nested `and`/`or` groups, `['!', …]` negation and path fields — so the SAME
+ * `[field, op, value]` a remote source receives also narrows an array source.
+ */
+export declare function customPredicate(entry: MonoSearchExprCustom, value: string, operation: string): ((row: any) => boolean) | null;

package/dist/src/utils/data-source-apply.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ONE `$apply` request through a devextreme OData store.
+ *
+ * The header filter, the summary footer and a bound chart all want the same
+ * thing — the server rolls the data up (`groupby` / `aggregate`) and hands back
+ * a handful of rows — and all of them want to send it through the SOURCE'S OWN
+ * STORE, so the request rides its url, `beforeSend`, auth and credentials
+ * exactly as every ordinary load does. This module is the one place that knows
+ * how to get an `$apply` into that request.
+ *
+ * ── Why not `customQueryParams` ──
+ *
+ * It is the option that looks right, and it is wrong on every OData version.
+ * devextreme treats `customQueryParams` as SERVICE-OPERATION parameters: each
+ * value goes through its literal serializer, so a string is quoted and every
+ * `'` doubled — `$apply='filter(A eq ''B'')'` — and on **v4 the whole thing
+ * becomes a FUNCTION-INVOCATION url**, `Entity($apply='…')`, which any entity
+ * set answers with 404. (`ODataStore.createQuery`: `escapeServiceOperationParams`
+ * always; v4 → `formatFunctionInvocationUrl`, v2/v3 → `queryOptions.params`.)
+ *
+ * The hatch that works is `loadOptions.urlOverride`: the store requests exactly
+ * that url, and devextreme's ajax appends its own parameters (`$top`, `$filter`,
+ * `$count`) with `&` when the url already carries a `?`. So the clause goes
+ * INTO the url, pre-encoded. A store without `version()` — a CustomStore, an
+ * array — never honoured `$apply` at all, and gets no request.
+ *
+ * @mono-lit/helper never imports devextreme, so everything here is duck-typed on the
+ * store: `version()` is public API, the url is read off `_requestDispatcher.url`
+ * (25.x) with `_url` (older builds) as the fallback.
+ */
+/** The slice of a devextreme store this module touches. */
+export interface ApplyStore {
+    load(options?: unknown): PromiseLike<unknown> | unknown;
+    /** OData protocol version (`ODataStore` only). */
+    version?(): number;
+}
+export interface ApplyLoadOptions {
+    /** Cap the rolled-up rows (`$top`). */
+    top?: number;
+}
+/** The store's OData version, or `null` for anything that is not an OData store. */
+export declare function odataStoreVersion(store: unknown): number | null;
+/** The store's base url, or `null` when it cannot be read. */
+export declare function odataStoreUrl(store: unknown): string | null;
+/** `<url>?$apply=<encoded clause>` — `&` when the url already has a query string. */
+export declare function applyRequestUrl(url: string, apply: string): string;
+/**
+ * The `store.load()` options that carry `apply`, or `null` when this store
+ * cannot carry one (no request should be made).
+ *
+ * `requireTotalCount: false` keeps `$count` off — a rolled-up result has no
+ * meaningful total, and `$count` beside `$apply` is rejected by some servers.
+ */
+export declare function applyLoadOptions(store: unknown, apply: string, options?: ApplyLoadOptions): Record<string, unknown> | null;
+/** Normalise a devextreme store `load` result into a plain rows array. */
+export declare function storeRows(res: unknown): any[];
+/**
+ * Send `apply` through `store` and return the rolled-up rows, or `null` when
+ * the store cannot carry an `$apply` (nothing was requested). A request that
+ * FAILS throws — the caller decides whether that disables the path for good
+ * (see {@link createApplyGate}).
+ */
+export declare function loadApply(store: unknown, apply: string, options?: ApplyLoadOptions): Promise<Array<Record<string, unknown>> | null>;
+/**
+ * Whether `rows` are what an honoured `$apply` returns — each row carrying
+ * ONLY the grouping key(s) and the aggregate aliases in `keys` (plus OData
+ * `@odata.*` annotations) — as opposed to plain entities from a server that
+ * ignored the clause. The distinction matters because an alias is usually the
+ * field's own name: an entity `{ Id, Dept, Total }` has the alias `Total` too,
+ * and would be mistaken for a bucket by a presence check. The extra `Id` is
+ * what gives it away. `keys` are matched on their ROOT segment (`Job/Title`
+ * comes back as `{ Job: { Title } }`).
+ */
+export declare function isRolledUp(rows: readonly unknown[], keys: readonly string[]): boolean;
+/**
+ * Whether a failed `$apply` request means the BACKEND does not do `$apply` —
+ * a 4xx (`400 Bad Request`, `404`) or `501 Not Implemented` — as opposed to a
+ * transient fault (network down: `httpStatus` 0 / absent, a 5xx). devextreme
+ * puts the status on the error as `httpStatus`.
+ */
+export declare function isApplyRejected(err: unknown): boolean;
+export interface ApplyGate {
+    /** `true` once the path is off — disabled by option, or rejected by the backend. */
+    readonly skip: boolean;
+    /** Report a failed request; a definite rejection turns the gate off for good. */
+    reject(err: unknown): void;
+}
+/**
+ * Per-controller "is the `$apply` path still worth trying?" switch.
+ *
+ * A backend without `$apply` answers every attempt with the same 4xx, and a
+ * grid that retried on every panel open / recompute would pay one failed
+ * request each time before falling back. So the FIRST definite rejection is
+ * remembered for the controller's lifetime; a transient failure is not, and
+ * the next attempt goes out normally.
+ */
+export declare function createApplyGate(enabled: boolean): ApplyGate;

package/dist/src/utils/data-source-options.d.ts

@@ -0,0 +1,116 @@
+import { MaybeReactive } from '../composables/reactive.js';
+/** One sort entry, in devextreme's object form. */
+export interface MonoSourceSortEntry {
+    selector: string;
+    desc: boolean;
+}
+/**
+ * DataSource-level knobs a controller keeps STICKY — `{ dataSourceOptions }`.
+ *
+ * These are the devextreme `DataSource` options a consumer would otherwise set on
+ * the source itself, and the point of routing them through the controller is that
+ * the controller then composes every query it runs on top of them: a search, a
+ * header column filter, a sort, a page, a scroll page, a drain, an `$apply` —
+ * each one goes out with this `filter` AND-ed in, this `select`, this `expand`.
+ *
+ * The option is read fresh at every query (see `MaybeReactive`), so hand a getter
+ * or a `computed` and the CURRENT reactive value is the one that lands in the
+ * request. Changing it does not by itself run a query — that is `refresh()`.
+ */
+export interface MonoDataSourceOptions {
+    /** Base filter, AND-ed under everything the controller adds. Array sources take a predicate too. */
+    filter?: unknown;
+    /** `$select`. */
+    select?: string | string[];
+    /** `$expand`. Simple navigation names union; a nested `Nav($select=…)` string is kept verbatim. */
+    expand?: string | string[];
+    /**
+     * Base sort. A sort the user picks wins; these follow as tiebreakers (entries
+     * whose selector is already sorted are skipped).
+     */
+    sort?: string | {
+        selector: string;
+        desc?: boolean;
+    } | Array<string | {
+        selector: string;
+        desc?: boolean;
+    }>;
+    /** Extra query-string parameters (ODataStore `customQueryParams`). */
+    customQueryParams?: Record<string, unknown>;
+    paginate?: boolean;
+    /** Source page size. A component's own page-size control still wins. */
+    pageSize?: number;
+    requireTotalCount?: boolean;
+    /** Source-level search columns/operation — used only when the controller declares none of its own. */
+    searchExpr?: string | string[];
+    searchOperation?: string;
+    [key: string]: unknown;
+}
+/**
+ * The same thing in raw OData vocabulary — `{ odataOptions }`.
+ *
+ * Normalised into {@link MonoDataSourceOptions} and merged with it: `$select` →
+ * `select`, `$expand` → `expand`, `$orderby` → `sort`, `$filter` → `filter`, and
+ * every other key (`$top`, `$count`, a custom parameter) → `customQueryParams`.
+ *
+ * `$filter` is a string. It is parsed into devextreme's array form so the store
+ * compiles it together with whatever the component adds; an expression the
+ * parser cannot read (an `any()` lambda, an ISO date literal) is sent as-is and
+ * comes out as `(expr) eq true`, which is valid OData — but devextreme rewrites
+ * every `.` in that raw text to `/`, so keep decimals and dotted strings out of
+ * it, or write the array form under `dataSourceOptions.filter` instead. Array
+ * sources cannot evaluate a raw string and ignore it (with one console warning).
+ */
+export interface MonoOdataOptions {
+    $select?: string | string[];
+    $expand?: string | string[];
+    $orderby?: string;
+    $filter?: string;
+    [key: string]: unknown;
+}
+/** The knobs with a meaning of their own; anything else is passed through as a load option. */
+export declare const DATA_SOURCE_KNOBS: ReadonlySet<string>;
+/** A comma string or an array → a trimmed string list; `null`/`undefined` → `undefined`. */
+export declare function toList(v: unknown): string[] | undefined;
+/** devextreme's sort forms (string / object / array / mixed) → an ordered entry list. */
+export declare function normalizeSortList(value: unknown): MonoSourceSortEntry[];
+/** `"A desc, B"` → `[{A, desc}, {B}]`. */
+export declare function parseOrderby(text: string): MonoSourceSortEntry[];
+/**
+ * The parser emits OData keyword operators (`eq`, `ge`) — the filter builder's
+ * tree reads either — but devextreme's ODataStore compiles ONLY the symbol forms
+ * and throws `E4003` on a keyword. Rewritten recursively.
+ */
+export declare function toSymbolOps(expr: unknown): unknown;
+/**
+ * A raw `$filter` → devextreme's array form, so the store compiles it TOGETHER
+ * with whatever the component adds. The parser throws on syntax it does not know
+ * (lambdas, ISO date literals); those go through as a one-element raw clause,
+ * which devextreme emits as `(expr) eq true` — valid OData, with the caveat that
+ * it rewrites `.` to `/` inside the text.
+ */
+export declare function parseOdataFilter(raw: string): unknown;
+/** `{ $select, $expand, $orderby, $filter, …custom }` → the DataSource shape. */
+export declare function normalizeOdataOptions(o: MonoOdataOptions): MonoDataSourceOptions;
+/**
+ * `a` ∧ `b`: filters AND-ed (predicates and arrays each on their own terms),
+ * `select`/`expand` unioned, sort de-duplicated by selector with `a` leading,
+ * `customQueryParams` merged with `b` winning, scalars `b` if defined else `a`.
+ */
+export declare function mergeDataSourceOptions(a: MonoDataSourceOptions, b: MonoDataSourceOptions): MonoDataSourceOptions;
+/**
+ * Read both option bags fresh and merge them — the one call a controller makes
+ * at the top of every query. Returns a NEW object every time (a getter hands
+ * back fresh state), so callers that need change detection compare by content:
+ * see {@link dataSourceOptionsKey}.
+ */
+export declare function resolveDataSourceOptions(dataSourceOptions: MaybeReactive<MonoDataSourceOptions> | undefined, odataOptions: MaybeReactive<MonoOdataOptions> | undefined): MonoDataSourceOptions;
+/**
+ * A content key for change detection. Functions (an array-source predicate) do
+ * not stringify, so they are marked and must be compared by reference by the
+ * caller; a circular object yields a fresh random key and so always counts as
+ * changed.
+ */
+export declare function dataSourceOptionsKey(o: MonoDataSourceOptions): string;
+/** `expand` / `customQueryParams` / unknown keys — what goes onto a `store.load()` beside the knobs. */
+export declare function extraLoadOptions(o: MonoDataSourceOptions): Record<string, unknown>;

package/dist/src/utils/data-source-read.d.ts

@@ -0,0 +1,85 @@
+import { andFilters } from '../search/filter-eval';
+import { unwrapReactive } from '../composables/reactive';
+/** The structural surface of a devextreme DataSource this module touches. */
+export interface ReadableDataSource<T = any> {
+    load(): PromiseLike<T[]> | T[];
+    items(): T[];
+    store?(): ReadableStore | undefined;
+    filter?(value?: unknown): unknown;
+    /** The source's own `$select`, inherited by a drain unless overridden. */
+    select?(value?: unknown): unknown;
+    sort?(value?: unknown): unknown;
+    searchValue?(value?: unknown): unknown;
+    searchExpr?(value?: unknown): unknown;
+    searchOperation?(value?: string): string;
+    paginate?(value?: boolean): boolean;
+    pageIndex?(value?: number): number;
+    totalCount?(): number;
+}
+/** The structural surface of a devextreme store. */
+export interface ReadableStore {
+    load(options?: unknown): PromiseLike<unknown> | unknown;
+    key?(): unknown;
+    byKey?(key: unknown): unknown;
+    /** OData protocol version (a devextreme `ODataStore`); absent on a CustomStore. */
+    version?(): number;
+}
+export interface ReadAllRowsOptions {
+    /**
+     * Rows per request (default `100`). The total is unknowable up front for a
+     * remote source, so the read walks in fixed chunks until one comes back short.
+     */
+    chunkSize?: number;
+    /** Restrict the columns fetched (remote sources only). */
+    select?: string[];
+    /** Sort override. Defaults to whatever the source itself carries. */
+    sort?: unknown;
+    /**
+     * An extra filter AND-ed onto the source's own (and its search) — a controller's
+     * base, which is not written on the source when the read goes to the STORE.
+     * Remote sources only; an array source is filtered by what it holds.
+     */
+    filter?: unknown;
+    /** Extra load options spread into every chunk request (`expand`, `customQueryParams`, …). */
+    loadOptions?: Record<string, unknown>;
+}
+/**
+ * Unwrap Vue reactivity. A `ref(dataSource)` renders as nothing (the template
+ * sees the wrapper, not the source), and a *reactive proxy* around a DataSource
+ * can break its internals — devextreme stores identity-sensitive state that
+ * doesn't survive being proxied.
+ *
+ * Re-exported (not redefined) from `composables/reactive` so the components that
+ * need the same unwrap for value identity share one implementation.
+ */
+export { unwrapReactive };
+/** A devextreme DataSource: it both loads and holds a current page. */
+export declare function isDataSourceLike(value: unknown): value is ReadableDataSource;
+/** A bare store (ODataStore / CustomStore / ArrayStore) — loads, but has no page. */
+export declare function isStoreLike(value: unknown): value is ReadableStore;
+/** Anything this module can drain into an array. */
+export declare function isReadableSource(value: unknown): boolean;
+/**
+ * Build a devextreme filter expression for a DataSource's **active search**.
+ *
+ * This is the subtle one. `searchValue` / `searchExpr` are DataSource-level
+ * options: the DataSource folds them into the request it sends to its store.
+ * Reading the store directly bypasses them entirely — so an export would
+ * silently include rows the user filtered away with `<mono-table-search>`.
+ * Reconstructing the filter here keeps the store path faithful to the grid.
+ */
+export declare function searchFilterOf(source: ReadableDataSource): unknown;
+/**
+ * AND-combine two optional devextreme filter expressions.
+ *
+ * Re-exported (not redefined) from the shared search module so the grid's filter
+ * composition and a drain's composition can never disagree.
+ */
+export { andFilters };
+/**
+ * Read every row a source can produce, in chunks.
+ *
+ * A plain array passes straight through, so callers can accept
+ * "array or DataSource" without branching.
+ */
+export declare function readAllRows<T = any>(source: unknown, options?: ReadAllRowsOptions): Promise<T[]>;

package/dist/src/utils/data-source-summary.d.ts

@@ -0,0 +1,55 @@
+import { arrayToODataString } from '../components/filter/filter-odata';
+/** Aggregate kinds a spec may ask for — mirrors `MonoSummaryType` structurally. */
+export type MonoAggregateType = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'countDistinct';
+/** The part of a summary spec that decides what to ask for. */
+export interface MonoAggregateSpec {
+    field?: string;
+    type?: MonoAggregateType;
+    /** Disambiguates two aggregates on the same field; also used as the alias. */
+    name?: string;
+}
+/**
+ * A field a server can aggregate.
+ *
+ * A WILDCARD or INDEX path (`Lines.[*].Total`) is rejected: `getFieldValue`
+ * resolves those by walking a collection on a loaded row, and no `$apply`
+ * expression means the same thing — the nearest OData construct aggregates the
+ * collection per parent rather than across all of them.
+ */
+export declare const isAggregatableField: (field: string) => boolean;
+/**
+ * The response key each spec's value comes back under.
+ *
+ * Plain `field` while that field carries ONE aggregate, which is the ordinary
+ * case and keeps the response readable; `field_type` once the same field has
+ * two (a `sum` and an `avg` of `Price`), because an `$apply` cannot alias two
+ * values to the same name. An explicit `name` always wins, and a bare `count`
+ * has no field to name it after.
+ */
+export declare function summaryAliases(specs: readonly MonoAggregateSpec[]): string[];
+/**
+ * Build `aggregate(<field> with <agg> as <alias>, …)` for a set of specs.
+ *
+ * Returns `null` when no spec can be expressed — a caller with nothing to ask
+ * for should not make a request.
+ */
+export declare function buildSummaryApply(specs: readonly MonoAggregateSpec[]): string | null;
+/**
+ * Compose a filter with an aggregate: `filter(<expr>)/aggregate(…)`.
+ *
+ * The filter goes INSIDE `$apply` rather than travelling as a sibling `$filter`
+ * — that is what makes the two compose, since the filter runs first and the
+ * aggregation sees only matching rows.
+ */
+export declare function composeSummaryApply(apply: string, filter: unknown): string;
+/**
+ * The predicate a summary must aggregate over — IDENTICAL to what the drain uses.
+ *
+ * `readAllRows` reads a DataSource as its own `filter()` AND its reconstructed
+ * `searchValue`, which is a DataSource-level option the store knows nothing
+ * about. Anything less here and a total would quietly count rows the user had
+ * searched away, which is worse than being slow.
+ */
+export declare function summaryFilterOf(source: unknown): unknown;
+/** Re-exported so a resolver can convert a devextreme filter itself. */
+export { arrayToODataString as summaryODataFilter };

package/dist/src/utils/normalize-error.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A readable message for `raw`, or `fallback` when nothing legible can be found.
+ *
+ * Never throws, and never returns an empty string — a caller rendering this into
+ * an error bar has to have something to render, and a blank bar is worse than a
+ * generic one.
+ */
+export declare function normalizeError(raw: unknown, fallback?: string): string;
+/**
+ * Keys of the preset map: an HTTP status, `'network'` for "the request never
+ * got an answer" (status 0, `TypeError: Failed to fetch`, devextreme's
+ * "Unspecified network error"), and `'default'` for everything else.
+ */
+export type MonoErrorMessageKey = number | 'network' | 'default';
+/** Wording overrides — per grid (`monoDataGrid({ errorMessages })`) or app-wide (`setErrorMessages`). */
+export type MonoErrorMessages = Partial<Record<MonoErrorMessageKey, string>>;
+/**
+ * What the bar says for a status. English; an app puts its own language in
+ * ONCE with `setErrorMessages()` rather than on every table.
+ */
+export declare const DEFAULT_ERROR_MESSAGES: Readonly<Record<MonoErrorMessageKey, string>>;
+/**
+ * App-wide wording, merged over the defaults; `null` restores them. A grid's own
+ * `errorMessages` merges over this in turn, so a single table can still differ.
+ */
+export declare function setErrorMessages(messages: MonoErrorMessages | null): void;
+/** Defaults ← app-wide ← `local`, same shape as the filter builder's `resolveTexts`. */
+export declare function resolveErrorMessages(local?: MonoErrorMessages): Record<MonoErrorMessageKey, string>;
+/**
+ * The HTTP status an error carries, `0` for a network failure, `undefined` when
+ * it has none.
+ *
+ * Reads the fields the common transports use — devextreme's `httpStatus`, a
+ * fetch `Response` / axios error's `status` and `response.status`, ofetch's
+ * `statusCode`, an OData error body's numeric `code` — on an `Error` instance as
+ * readily as on a plain object, since devextreme `extend()`s them onto an
+ * `Error`.
+ */
+export declare function errorStatus(raw: unknown): number | undefined;
+export interface DescribedError {
+    /** The headline: the preset for the status when there is one, else the error's own text. */
+    message: string;
+    /** The HTTP status, `0` for a network failure, absent when the error carries none. */
+    status?: number;
+    /**
+     * Text the server (or the error itself) added beyond the status — the part a
+     * user CAN act on ("Budget period is closed"). Never a bare reason phrase.
+     */
+    detail?: string;
+}
+/**
+ * The line a person should read for `raw`.
+ *
+ * Order: a preset for the status (`'network'` for 0) → the error's own text →
+ * `messages.default`. When a preset is the headline, whatever the server said
+ * on top of the status becomes `detail`; without a preset, the raw text IS the
+ * headline and only a distinct server body is a detail. Never throws, never
+ * returns an empty `message`.
+ */
+export declare function describeError(raw: unknown, messages?: MonoErrorMessages): DescribedError;

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

@@ -0,0 +1,48 @@
+/// <reference path="../../vue.d.ts" />
+import { Plugin } from 'vite';
+import { monoClientOnlyPlugin } from './mono-client-only';
+import { monoSsrStubPlugin } from './mono-ssr-stub';
+export interface MonoSsrOptions {
+    /** Custom-element tag prefix wrapped in <ClientOnly>. Default 'mono-'. */
+    prefix?: string;
+    /** Wrapper component used for client-only rendering. Default 'ClientOnly'. */
+    wrapper?: string;
+    /** Import prefix of registration modules stubbed during SSR. Default '@mono-lit/helper/ui/'. */
+    ssrStubPrefix?: string;
+    /**
+     * Tag names (e.g. `['mono-nav']`) to NOT wrap in `<ClientOnly>` — for
+     * components server-rendered by another mechanism (e.g. `nuxt-ssr-lit`
+     * shadow-DOM builds). Default `[]`.
+     */
+    exclude?: string[];
+    /**
+     * Wrap LIGHT `<prefix*>` elements in `<ClientOnly>`. Default `true`. `false`
+     * keeps the server import-stub and the shadow `<LitWrapper>` wrap but leaves
+     * light tags as they are — see `MonoClientOnlyOptions.lightWrap`.
+     */
+    lightWrap?: boolean;
+    /**
+     * Enable the import-driven SSR wrap: `<mono-*>` whose `@mono-lit/helper/ui/shadow/
+     * <entry>` build a `.vue` file imports get wrapped in `<LitWrapper>`
+     * (Declarative Shadow DOM) instead of `<ClientOnly>`. Default off.
+     */
+    litWrapper?: boolean;
+    /** Component name used for the SSR wrap. Default `'LitWrapper'`. */
+    litWrapperComponent?: string;
+    /** Tags to ALWAYS treat as shadow (for globally-registered components). */
+    shadowOverride?: string[];
+}
+/**
+ * One import, one props object — wires both halves of SSR support for the
+ * mono web components:
+ *   - the SSR import-stub (so `@mono-lit/helper/ui/*` never evaluates on the server)
+ *   - the `<ClientOnly>` template wrapper (so `<mono-*>` only renders client-side)
+ *
+ * Usage:
+ *   import { monoSsr } from '@mono-lit/helper/vite'
+ *   plugins: [monoSsr()]
+ */
+export declare function monoSsr(options?: MonoSsrOptions): Plugin[];
+export { monoClientOnlyPlugin, monoSsrStubPlugin };
+export type { MonoClientOnlyOptions } from './mono-client-only';
+export type { MonoSsrStubOptions } from './mono-ssr-stub';

package/dist/src/vite/mono-client-only.d.ts

@@ -0,0 +1,35 @@
+import { Plugin } from 'vite';
+export interface MonoClientOnlyOptions {
+    prefix?: string;
+    wrapper?: string;
+    /**
+     * Tag names (e.g. `'mono-nav'`) to NOT wrap in the client-only wrapper.
+     * Use this for components that are server-rendered by another mechanism
+     * (e.g. `@lit-labs/ssr` / `nuxt-ssr-lit` shadow-DOM builds) — wrapping them
+     * in `<ClientOnly>` would suppress their server markup.
+     */
+    exclude?: string[];
+    /**
+     * Wrap LIGHT `<prefix*>` elements in the client-only wrapper. Default `true`.
+     * `false` leaves light tags untouched (they server-render as inert custom-element
+     * tags and upgrade in the browser) while the shadow `<LitWrapper>` wrap below
+     * keeps working — for apps whose pages are client-only as a whole and must not
+     * have each `<mono-*>` deferred past the page's `onMounted`.
+     */
+    lightWrap?: boolean;
+    /**
+     * Enable the import-driven SSR wrap: a `.vue` file that imports
+     * `@mono-lit/helper/ui/shadow/<entry>` gets its matching `<mono-*>` wrapped in
+     * `<LitWrapper>` (Declarative Shadow DOM) instead of `<ClientOnly>`. Needs
+     * `nuxt-ssr-lit` installed (provides the `<LitWrapper>` component). Default off.
+     */
+    litWrapper?: boolean;
+    /** Component name used for the SSR wrap. Default `'LitWrapper'`. */
+    litWrapperComponent?: string;
+    /**
+     * Tags to ALWAYS treat as shadow (LitWrapper-wrapped) regardless of per-file
+     * imports — for components registered once in a shared plugin. Default `[]`.
+     */
+    shadowOverride?: string[];
+}
+export declare function monoClientOnlyPlugin(options?: MonoClientOnlyOptions): Plugin;