@nxgt/material 3.28.0 → 3.29.0

package/docs/components/data-table-filter-and-lists.md

@@ -1570,6 +1570,48 @@ one. The page clears it when the condition changes, by passing no error. The
 words are `material.filter.error.*`; `fieldErrors(errors, model, locked)` in
 the core lists what the bar shows.
 
+#### A refused search, and a refusal of no field
+
+`errors` is keyed by field id, so it cannot name the search box nor carry a
+refusal that belongs to no field. Two more props, on the same three surfaces
+(`Filter`, `FilterBar` and `ServerTable`'s `filter`), take them:
+
+```tsx
+<FilterBar
+  model={model}
+  params={params}
+  onParamsChange={setParams}
+  searchError="Not a valid item."
+  formError="The list could not be filtered right now."
+/>
+```
+
+- **`searchError`** (a node) is the refusal of the typed search. The search
+  box takes the error tone and shows an icon, "Invalid." and the message under
+  it; the input is `aria-invalid` and `aria-describedby` points at the message.
+  Nothing for a model with `search: false`.
+- **`formError`** (a node) is a refusal that belongs to no field: one error
+  `Alert` under the bar, in place (under the bar's row in `FilterBar`, between
+  the band and the chips in `ServerTable`, under the search in the facets
+  panel). It is no live region of its own.
+
+Both are told by the bar's one polite live region, the same refusal path as a
+field's, once and after the count: "Search: Not a valid item." and the
+`formError`'s text (a node is read as its text). The page drops them when the
+search or the query changes, by passing nothing, as it does for `errors`.
+
+When the loader answers one flat record, `splitFilterErrors(refusal, model)`
+from `@nxgt/material-core/filter` splits it: the key equal to the model's
+search param becomes `searchError`, the key `FILTER_FORM_ERROR_KEY`
+(`'$form'`, never a field id) becomes `formError`, and the rest stays in
+`errors`. Messages are trimmed and an empty one is dropped:
+
+```tsx
+// the loader answered { item: 'Not a valid item.', $form: 'Try again later.', period: 'Too long.' }
+<FilterBar model={model} params={params} onParamsChange={setParams}
+  {...splitFilterErrors(data.fieldErrors, model)} />
+```
+
 #### A list without a search box
 
 `defineFilterModel({ search: false, fields })` declares a list with no text

package/docs/troubleshooting.md

@@ -2538,6 +2538,25 @@ the field out of `locked`. `fieldErrors(errors, model, locked)` from
 <ServerTable filter={{ model, locked, errors: { period: 'The period cannot exceed 366 days.' } }} {...table} />
 ```
 
+### A refused search or a refusal of no field shows nothing
+
+**When:** the server refuses the typed search, or refuses with a message that
+names no field, and the page passes it as `errors={{ item: 'Not a valid item' }}`
+(the search param as a key) or `errors={{ form: '…' }}`: the search box looks
+normal and no Alert shows. Nothing is printed.
+**Why:** `errors` only reads field ids. The search box and a refusal of no field
+have their own props, `searchError` and `formError`.
+**Fix:** pass them as props, or split one flat record with `splitFilterErrors`
+from `@nxgt/material-core/filter` (the key equal to `model.search.param` is the
+search, `'$form'` is the form). A model with `search: false` shows no
+`searchError`, and an empty message shows nothing. The page must drop them when
+the search changes:
+
+```tsx
+<FilterBar model={model} params={params} onParamsChange={setParams}
+  {...splitFilterErrors({ item: 'Not a valid item.', $form: 'Try again later.' }, model)} />
+```
+
 ### `@nxgt/material-core/filter: unknown time zone "…", using the runtime's`
 
 **When:** in the console, once, when a date preset (`this-month`) is matched or
@@ -2566,7 +2585,8 @@ const conditions = resolveDateConditions(effectiveConditions(query, model, locke
 neither, it has nothing to offer. The functions live in `fieldProps`, never in
 the model, so the loader can share it.
 **Fix:** give the field `options`, or a `search` (and `resolveLabels`, for the
-ids a link brings) by field id:
+ids a link brings) by field id. A field only a link sets (`addable: false`)
+is never offered for picking and needs neither, so it raises no warning:
 
 ```tsx
 const fieldProps: FilterFieldProps = {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.28.0",
+	"version": "3.29.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -362,7 +362,7 @@
 		"docs:previews": "rm -rf node_modules/.cache/nxgt-preview-free/missing && NXGT_PREVIEW_FREE=1 vitest run --project previews && bun .storybook/preview-free-report.ts"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.36.0",
+		"@nxgt/material-core": "^0.37.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",