@nxgt/material 3.27.0 → 3.28.0

package/docs/roadmap.md

@@ -330,6 +330,22 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **One filter model: defaults, a scope, a refusal, `FilterBar`** — a filter
+  field says what an absent value means and what role it plays, so a list can
+  start narrowed and a page can keep a value the user never clears.
+  `default` (values, or `'page'` with `defaults` from the loader) is shown but
+  never counted, written to the URL or removed by "Clear all": a hint chip, a
+  pressed toggle, or checked values tagged "Default". `scope: true` makes a
+  field such as the period a leading pill that "Clear all" and `withoutFilters`
+  keep. `off: 'remove'` turns a switch into a plain "only when on" filter.
+  `errors` shows a server's refusal on the control, and `search: false` drops
+  the search box. `FilterBar` and `useFilterUrlQuery` bind the bar to the URL
+  for a feed or a list that is no table, the same binding `ServerTable` uses.
+  React only for now; the Vue gap is tracked in issue #1569.
+  [Filter bar](components/data-table-filter-and-lists.md#filter-bar) ·
+  [A field's default](components/data-table-filter-and-lists.md#a-fields-default) ·
+  [A scope field](components/data-table-filter-and-lists.md#a-scope-field) ·
+  [Server lists in the URL](guides/server-lists-url.md)
 - **Display polish** — `Badge` is a status badge: a 20 px pill with the
   `label-sm` text and no hover, a `soft` variant (the tone's container under
   the tone's text, 4.5:1) and a `tone` prop for `soft` and `outlined`, taking

package/docs/troubleshooting.md

@@ -131,6 +131,10 @@ words in your error.
 - [The filter URL is not encoded like URLSearchParams](#the-filter-url-is-not-encoded-like-urlsearchparams)
 - [A refused or reset edit stays in the filter bar](#a-refused-or-reset-edit-stays-in-the-filter-bar)
 - [`defineFilterModel: field "level" cannot use "gt" on a select field`](#definefiltermodel-field-level-cannot-use-gt-on-a-select-field)
+- [`defineFilterModel: field "x" can only set addable to false`](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#definefiltermodel-field-x-can-only-set-addable-to-false)
+- [`defineFilterModel: field "x" default …` and `off …`](#definefiltermodel-field-x-default--and-off-)
+- [`defineFilterModel: field "period" scope needs a default operator taking one value`](#definefiltermodel-field-period-scope-needs-a-default-operator-taking-one-value)
+- [`errors` shows nothing on the filter bar](#errors-shows-nothing-on-the-filter-bar)
 - [`@nxgt/material-core/filter: unknown time zone "…", using the runtime's`](#nxgtmaterial-corefilter-unknown-time-zone--using-the-runtimes)
 - [``Filter: the autocomplete field(s) … have neither `options` nor a `search` in `fieldProps`: their editor has nothing to offer.``](#filter-the-autocomplete-fields--have-neither-options-nor-a-search-in-fieldprops-their-editor-has-nothing-to-offer)
 - [`Filter bar parts must be used inside <Filter variant="bar">`](#filter-bar-parts-must-be-used-inside-filter-variantbar)
@@ -2471,8 +2475,11 @@ other messages say `must match [A-Za-z0-9_-]+` (a field id is written in the
 URL), `is declared twice`, `has an unknown type`, `declares an operator twice`,
 `uses the param "<p>" of the search` (two fields, or a field and the search,
 share a URL param), `can only use style "flag" as a switch or checkbox`,
-`needs a default operator taking several values for style "repeat"`, `needs a default operator taking one value for style "single"`, and, for a
-search param, `f` is reserved for the conditions.
+`needs a default operator taking several values for style "repeat"`, `needs a default operator taking one value for style "single"`, the scope
+checks (`scope needs a default`, `scope cannot be combined with widens`,
+`scope needs a single-value type`, `scope default must hold exactly one
+value`, `can only set scope to true`), and, for a search param, `f` is
+reserved for the conditions (a model with `search: false` has none).
 **Fix:** use the operators the type allows: numbers and sliders compare with
 `gt`, `lt`, `gte`, `lte`, dates and times with `before` and `after`; the
 first operator you list is the default.
@@ -2481,6 +2488,56 @@ first operator you list is the default.
 { id: 'age', type: 'number', label: 'Age', operators: ['gte', 'lte', 'between'] }
 ```
 
+### `defineFilterModel: field "x" default …` and `off …`
+
+**When:** the module that calls `defineFilterModel` is imported, with a
+`default` that is not an array of strings or `"page"`, repeats or does not
+read a value, is off on a field declared `off: 'remove'`, or sits on a
+`widens` field, or with an `off` that is not `'remove'` or `'no'`, is on
+something other than a switch or checkbox, or is `'no'` on a `widens` field.
+**Why:** a default is applied as the field's condition, so it must be one the
+URL could hold; and `off` only says what off means for a boolean.
+**Fix:** see the exact messages and fixes in the core page:
+[`default …`](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#definefiltermodel-field-x-default-) and
+[`off …`](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#definefiltermodel-field-x-widens-needs-off-remove-and-the-other-off-errors).
+
+### `defineFilterModel: field "period" scope needs a default operator taking one value`
+
+**When:** the module that calls `defineFilterModel` is imported, with a
+`scope: true` field whose default operator (the first of its `operators`)
+takes several values, such as `in` on a `select`.
+**Why:** a scope is one value the list is scoped by, shown in a pill
+("Period: P2"), so its default operator (the first of `operators`, or the
+type's own) must read exactly one value. The other scope checks name their
+own rule: `scope needs a default`, `scope needs a single-value type`,
+`scope default must hold exactly one value`, `scope cannot be combined with
+widens`.
+**Fix:** list a one-value operator first, or use a single-value type
+(`select`, `radio-group`, `chips-single`):
+
+```ts
+{ id: 'period', type: 'select', label: 'Period', options: PERIODS,
+  operators: ['is'], scope: true, default: ['p2'] }
+```
+
+### `errors` shows nothing on the filter bar
+
+**When:** a page passes `errors={{ period: 'Too long' }}` (to `Filter`,
+`FilterBar` or `ServerTable`'s `filter`) and the field's chip, pill or toggle
+keeps its normal look, with no "Invalid" and nothing announced. Nothing is
+printed.
+**Why:** only a field of the model that the page does not lock shows an error:
+a key that is not a field id (a typo, the search param, an alias), an empty
+message, or a field in `locked` is left out, since a locked field shows its
+lock only.
+**Fix:** key `errors` by the field's `id`, give a non-empty message, and keep
+the field out of `locked`. `fieldErrors(errors, model, locked)` from
+`@nxgt/material-core/filter` lists what the bar will show:
+
+```tsx
+<ServerTable filter={{ model, locked, errors: { period: 'The period cannot exceed 366 days.' } }} {...table} />
+```
+
 ### `@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

package/lib/components/ui/display/chip/chip-parts.css

@@ -82,6 +82,25 @@
 		background: color-mix(in oklab, var(--foreground) 4%, transparent);
 	}
 
+	/* A dashed chip in the error tone (a refused filter): the line and the
+	 * text take the tone, dashed or selected, hover and focus included. */
+	.nxgt-chip[data-dashed][data-tone="error"] {
+		--chip-tone: var(--error-text);
+		border-color: color-mix(in oklab, var(--error-text) 60%, var(--background));
+		color: var(--error-text);
+	}
+	.nxgt-chip[data-dashed][data-tone="error"]:not([data-selected]):is(
+		:hover,
+		:focus-visible
+	) {
+		color: var(--error-text);
+		border-color: var(--error-text);
+		background: color-mix(in oklab, var(--error-text) 6%, transparent);
+	}
+	.nxgt-chip[data-dashed][data-tone="error"][data-selected] {
+		background: color-mix(in oklab, var(--error-text) 8%, var(--background));
+	}
+
 	.nxgt-chip[data-tone="neutral"] {
 		--chip-tone: var(--muted-foreground);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.27.0",
+	"version": "3.28.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.35.0",
+		"@nxgt/material-core": "^0.36.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",