@nxgt/material 3.26.1 → 3.28.0

package/docs/guides/server-lists-url.md

@@ -48,7 +48,9 @@ field that declares `param` and `style` (`'repeat'`, `'single'` or `'flag'`),
 the app's own param, so an older link such as `?archived=1` keeps working.
 A flag alias at `0` (`?archived=0`) means off: it is no condition, so the link
 shows every row. To filter on "No", write `f=archived:is:0`, which the
-serializer does for you.
+serializer does for you. A field declared `off: 'remove'` (a narrowing switch
+such as "Only unassigned") has no "No": its `:is:0` and `=0` are both
+dropped, and the serializer never writes them.
 A range is written `a..b` with either end open (`6..`, `..8`).
 
 ## Parse it in the loader
@@ -171,6 +173,107 @@ export default function Students({ loaderData }: Route.ComponentProps) {
 - **Dates and times** stay relative in the URL (`f=term:between:this-month`),
   so a bookmark keeps meaning "this month".
 
+## A list that is no table: `FilterBar`
+
+A feed or a card list has no `ServerTable` to bind the URL for it. `FilterBar`
+does the same: pass it the router's search params and a setter, and it reads
+and writes the query as above (the codec options, `reset` for the cursor, the
+page's other params kept):
+
+```tsx
+import { FilterBar } from '@nxgt/material/components';
+import { useSearchParams } from 'react-router';
+
+const [params, setParams] = useSearchParams();
+<FilterBar
+  model={FEED_FILTERS}
+  params={params}
+  onParamsChange={(next) => setParams(next, { replace: true })}
+  codec={{ keepKnownValues: true }} // the loader's own options
+  reset={['after']}
+  resultCount={loaderData.total}
+  loading={loading}
+/>
+```
+
+`useFilterUrlQuery` is the same binding as a hook, for a page that places the
+`Filter` itself (it takes a `UseFilterUrlQueryOptions` and returns a
+`FilterUrlQuery`; `FilterBarProps` and `FilterUrlCodec` name the bar's props
+and the codec options). `ServerTable`'s `filter` uses it, so the two cannot
+drift.
+
+## A default the loader computes
+
+Some views start narrowed: "Mine only" on for some users, a list showing
+`active` and `upcoming` while nothing is picked. Declare it on the field, so an
+absent param means it, and the URL still holds the user's explicit choices only:
+
+```ts
+const FILTERS = defineFilterModel({
+  fields: [
+    { id: 'status', type: 'multi-select', label: 'Status', options,
+      default: ['active', 'upcoming'] },
+    // The page decides per request: `defaults` passes the value.
+    { id: 'mine', type: 'switch', label: 'Mine only', default: 'page' },
+  ],
+});
+
+export async function loader({ request, context }: Route.LoaderArgs) {
+  const query = parseFilterQuery(new URL(request.url).searchParams, FILTERS);
+  const defaults = { mine: context.user.prefersMine ? ['1'] : [] };
+  const conditions = effectiveConditions(query, FILTERS, LOCKED, { defaults });
+  return api.students({ search: query.search, conditions });
+}
+```
+
+Order is locked, then the user's, then defaulted. `resolveDefaults(query,
+FILTERS, defaults, LOCKED)` also names the fields it defaulted. A default is
+never in `query`, so `isFiltered`, `withoutFilters` and "Clear all" are
+unchanged, and "Clear all" returns the field to its default. Choosing a value
+replaces the default, also a value equal to it, which stays in the URL as
+written. An explicit off of a default-bearing switch is `f=mine:is:0`, or
+`mine=0` for a `style: 'flag'` field; on a field without `default` that `0`
+keeps its old meaning. A link shared between users with different `'page'`
+defaults renders per viewer, by design. A `'page'` field the page gives no value
+for has no default, yet `mine=0` still reads as an explicit off for it. Pass the same `defaults` (and `locked`)
+to `matchQuery` and `valueCounts` in client mode.
+
+The page shows the default too: pass the same `defaults` to `ServerTable`'s
+`filter` (`filter={{ model, defaults }}`), `FilterBar` or `Filter`. A defaulted
+value is shown but uncounted, with no ✕ and no announced count, and never
+written to the URL:
+
+- a select or multi-select reads as a dashed hint chip, "Status: Active,
+  Upcoming · Default". It is a button named "Status: Active, Upcoming, default
+  value. Change": it opens the field's editor on the default, like an applied
+  chip, and has no ✕. A quick pill reads the same;
+- a switch or checkbox quick toggle is pressed, marked "Default"; pressing it
+  writes the explicit off (`mine=0`), which is then counted as a "No" chip;
+- the facets panel and the phone sheet show the default values checked, with
+  "Default" beside the field's title. Unchecking or changing one writes an
+  explicit choice (counted, in the URL); "Clear all" goes back to the checked
+  defaults. The section starts open;
+- "Filters (N)" and the announced count leave defaults out, and "Clear all"
+  (which shows from two filters) returns every field to its default.
+
+`defaults` must be the loader's own object, or the chips and the rows disagree.
+
+## A scope, a refusal and a list without a search
+
+- **A scope** (`scope: true` with a `default`, `'page'` for "the current
+  period") is the value a list is scoped by and the user changes but never
+  clears. The loader treats it as any condition (it is in `query`, and in
+  `effectiveConditions`), but `isFiltered`, `withoutFilters` and the bar's
+  count and "Clear all" leave it out: `/students?f=period:is:p1&q=ada` resets
+  to `?f=period:is:p1`. An invalid value means the default.
+- **A refusal.** When the loader refuses a value, return the message per
+  field and pass it as `errors` (`filter={{ model, errors }}`): the chip reads
+  "Invalid", described by the message, and the editor and the live region
+  show it. Clear it once the user changes the condition.
+- **`search: false`** in `defineFilterModel` drops the search box and frees the
+  `q` param: `parseFilterQuery` returns `search: ''` and
+  `serializeFilterQuery` never writes it.
+
 ## Client mode
 
 When all the rows are already in the page, skip the loader's fetch and filter
@@ -198,5 +301,15 @@ page, or the hydrating page renders another count.
   `FILTER_MAX_VALUES` or `FILTER_MAX_VALUE_LENGTH`, a slider value off its
   track or an unsafe integer is dropped silently: see
   [a condition in the URL is missing from the filter](../troubleshooting.md#a-condition-in-the-url-is-missing-from-the-filter).
+- A field you switch to `off: 'remove'` stops reading its old `f=x:is:0`
+  links as "No": they are dropped silently, so a shared link that meant
+  "not x" now shows every row. Leave `off` out when "No" matters.
+- A `default: 'page'` field reads its values from `defaults`: give the loader and
+  the page the same record, or the counts and the chips disagree. Compute a
+  period-style default in the loader and pass it as a string, never
+  `new Date()` in render (a hydration mismatch).
+- Adding `default` to a field changes its `x=0` and `f=x:is:0` links from "no
+  condition" (or dropped) to an explicit off, and an absent param from "every
+  row" to the default.
 - Parse with the same `locked` list in the loader and in the page, or the two
   read different queries.

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)
@@ -722,9 +726,20 @@ list) hold shapes.
 backdrop layer). Since 3.22 a glyph whose box meets a surface, a text or a
 control, within 8px, is dropped whole (the keep-clear pass), so a gap narrower
 than a glyph shows none.
-**Fix:** none needed, it is the documented behaviour (see [the drop rule](./guides/backgrounds.md) in
-the backgrounds guide). To see more shapes, leave open space in the page, or draw
-the backdrop in a layout that has no content over it.
+**Fix:** it is the documented behaviour (see [the drop rule](./guides/backgrounds.md) in
+the backgrounds guide). On a dense page, opt in to `keepClear="gaps"` on the
+`ActivityLayout` (or `AuthCard`): a glyph then stays when its box fits in a gap of
+24px or more between two surfaces, and is still dropped over text, a control or a
+card. A glyph wider than the gap is dropped as before. Or leave open space in the page.
+
+```tsx
+import { ActivityLayout } from '@nxgt/material/components';
+import { Background } from '@nxgt/material/backgrounds';
+
+<ActivityLayout items={items} backdrop={<Background preset="shapes" />} keepClear="gaps">
+  <Outlet />
+</ActivityLayout>
+```
 
 ### The page and the cards look the same
 
@@ -2460,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.
@@ -2470,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.26.1",
+	"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",