@nxgt/material 3.31.0 → 3.32.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @nxgt/material
 
+## 3.32.0
+
+### Minor Changes
+
+- [#1710](https://github.com/softistx/nxgt-material/pull/1710) [`d0a51eb`](https://github.com/softistx/nxgt-material/commit/d0a51eb58c63b1e8db2e47118e5b7c248ff3e1fe) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Filter model: a field can declare the fields that depend on it, `resets: ['subcategory']` on `category` ([#1703](https://github.com/softistx/nxgt-material/issues/1703)). When its value changes through the bar, the phone sheet, a chip's ✕, a quick pill or a scope pill, the dependents are cleared in the same query change, so one URL write and one history entry, and the page goes back to the first page like any filter change. Chains hold (a resets b, b resets c: a clears both), a dependent with a `default` returns to it, and a scope field may reset others and be reset. A cycle, an unknown id or a field resetting itself throws in `defineFilterModel`. "Clear all", the codec, `effectiveConditions` and the loader are unchanged. Core: `applyFieldChange(query, model, fieldId, next)` and `resetFields(model, fieldId)` give an app writing the URL itself the same result.
+
+### Patch Changes
+
+- Updated dependencies [[`d0a51eb`](https://github.com/softistx/nxgt-material/commit/d0a51eb58c63b1e8db2e47118e5b7c248ff3e1fe)]:
+  - @nxgt/material-core@0.38.0
+
 ## 3.31.0
 
 ### Minor Changes

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

@@ -1613,6 +1613,44 @@ left out of "Add filter" and of the quick filters (also when listed in
 `quick`), and the phone sheet and the facets panel list its section only
 while the applied query holds a value. Core: `isAddableField(model, id)`.
 
+#### A field that resets the fields depending on it
+
+A subcategory's options depend on the category: when the category changes, the
+subcategory's value may no longer exist. Declare it on the parent with `resets`:
+
+```ts
+const model = defineFilterModel({
+  fields: [
+    { id: 'category', type: 'select', label: 'Category', options: categories,
+      quick: true, resets: ['subcategory'] },
+    { id: 'subcategory', type: 'select', label: 'Subcategory', options: subcategories },
+  ],
+});
+```
+
+When the category changes (the bar, the phone sheet, a chip's ✕, a quick pill
+or a scope pill) the subcategory's condition is cleared in the **same** query
+change: one URL write, one history entry (Back restores both), and the page
+param goes back to the first page like any filter change.
+
+- **Chains.** a resets b and b resets c: changing a clears b and c. A cycle,
+  an unknown id and a field resetting itself throw in `defineFilterModel`.
+- **Clearing the parent** clears its dependents too. Picking the value it
+  already has changes nothing. "Clear all" is unchanged.
+- **A dependent with a `default`** returns to its default, not to empty. A
+  `scope` field may reset others and be reset.
+- **A locked dependent** is left alone.
+- **"Add filter"**: the dependents are cleared as soon as the parent's value is
+  entered; cancelling the flow (Escape, Back) restores the parent's previous
+  value, not the dependents it cleared.
+- **Only writes from the UI** are shaped. The codec, `effectiveConditions`
+  and the loader read a URL as it is, so `?category=b&subcategory=a1` from a
+  link stays as written.
+- **Core.** An app writing the URL itself gets the same result with
+  `applyFieldChange(query, model, 'category', condition)` (`null` removes the
+  field), pure and returning the same query when nothing changed.
+  `resetFields(model, 'category')` lists the fields a change resets.
+
 #### A refused condition
 
 A server can refuse a value (a date span too long, an end before a start).

package/docs/troubleshooting.md

@@ -132,6 +132,7 @@ words in your error.
 - [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" is part of a resets cycle …`](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/troubleshooting.md#definefiltermodel-field-x-is-part-of-a-resets-cycle--and-the-other-resets-errors)
 - [`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)

package/package.json

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