@nxgt/material 3.26.1 → 3.28.0

package/dist/lib/components/ui/collections/filter/internal.d.ts

@@ -1,12 +1,14 @@
-export { FilterBar } from './bar/filter-bar.js';
+export { FilterBarView } from './bar/filter-bar-view.js';
 export { FilterClearAll } from './bar/partials/filter-clear-all.js';
 export type { FilterBarFieldProps } from './editors/custom-types.js';
 export { FilterFacets } from './facets/filter-facets.js';
 export { FilterQueryProvider, useFilterQueryContext, } from './query/filter-query-context.js';
 export type { FilterQueryProps } from './query/types.js';
+export { type AnswerWait, useAnswerWait, } from './query/use-answer-wait.js';
 export { useFilterAnnouncement } from './query/use-filter-announcement.js';
 export { FilterAnswerHost, useFilterAnswerWatch, } from './query/use-filter-answer-watch.js';
 export { useFilterQueryValue } from './query/use-filter-query-value.js';
+export { type FilterUrlCodec, type FilterUrlQuery, type UseFilterUrlQueryOptions, useFilterUrlQuery, } from './query/use-filter-url-query.js';
 export { FilterChipBody } from './sections/chips/filter-chip-body.js';
 export { FilterChipList } from './sections/chips/filter-chip-list.js';
 export { FILTER_BAND_COMPACT_CLASS, FILTER_BAND_SURFACE_COMPACT_CLASS, } from './sections/filter-band-classes.js';

package/dist/lib/components/ui/collections/filter/query/filter-results-status.d.ts

@@ -4,6 +4,9 @@
  * "Level is any of CE1, 24 results" after "Add filter"'s Done), never while
  * loading, pending or adding, never a stale count. Without `resultCount`,
  * only "Filters cleared" and the filter added. The core's `barAnnouncement`
- * decides what is said.
+ * decides what is said. The server's refusals (the `errors` prop) are told in
+ * the same region, "Period: The period cannot exceed 366 days.", as they are
+ * in the page, after the count, once (`useRefusalAnnouncement`): one frame after they first
+ * appear or change, and gone when the region next changes for its own reason.
  */
 export declare function FilterResultsStatus(): import("react").JSX.Element;

package/dist/lib/components/ui/collections/filter/query/types.d.ts

@@ -1,9 +1,9 @@
-import { FilterApply, FilterCountsOption, FilterLockedCondition, FilterModel, FilterPreviewCount, FilterQuery, FilterSearchApplyMode, FilterShortcutsOption } from '@nxgt/material-core/filter';
+import { FilterApply, FilterCountsOption, FilterDefaults, FilterFieldErrors, FilterLockedCondition, FilterModel, FilterPreviewCount, FilterQuery, FilterSearchApplyMode, FilterShortcutsOption } from '@nxgt/material-core/filter';
 import { FilterBarFieldProps } from '../editors/custom-types.js';
 /** The bar's spacing: `compact` draws small chips; every target stays 24px or more. */
 export type FilterDensity = 'comfortable' | 'compact';
-/** The props `FilterBar` and `FilterFacets` share. */
-export type FilterBarProps = {
+/** The props `FilterBarView` and `FilterFacets` share. */
+export type FilterViewProps = {
     label?: string;
     searchLabel?: string;
     searchPlaceholder?: string;
@@ -54,6 +54,24 @@ export type FilterQueryProps = {
     onQueryChange?: (query: FilterQuery) => void;
     /** The conditions the page imposes: a lock, no ✕, never in `query`. */
     locked?: readonly FilterLockedCondition[];
+    /**
+     * The values of the `default: 'page'` fields, the same object as the
+     * loader's (a fixed `default` needs nothing). A field with a default and
+     * no condition of the user's shows it, uncounted and with no ✕: a hint
+     * chip, a pressed quick toggle, a "Default: …" note in the facets and the
+     * sheet. It is never in `query`: choosing a value replaces it, and "Clear
+     * all" returns to it.
+     */
+    defaults?: FilterDefaults;
+    /**
+     * A server's refusal of a condition, by field id: `{ period: 'The period
+     * cannot exceed 366 days.' }`. The field's chip (or quick pill) reads
+     * "Invalid" in the error tone, described by the message; its editor and
+     * its facets section show the message; the live region tells it. Only a
+     * field of the model the page does not lock; cleared by the page when the
+     * condition changes (the loader answers again).
+     */
+    errors?: FilterFieldErrors;
     /** How long the live apply waits after an edit (ms, default 200). */
     liveDelayMs?: number;
     /**

package/dist/lib/components/ui/collections/{server-table → filter/query}/use-answer-wait.d.ts

@@ -51,5 +51,7 @@ export declare function graceOf(held: Held | null): number | null;
  * takes it: the params reach its target (`key`), or a foreign change drops
  * it, or `WRITE_GRACE_MS` does if the router never takes it. What the page
  * answers after that is not this hook's: `useTableAnswer` watches it.
+ * `enabled: false` (a page that already owns the wait) keeps it inert: no
+ * timer, and a `write` that hands the params straight on.
  */
-export declare function useAnswerWait(key: string): AnswerWait;
+export declare function useAnswerWait(key: string, enabled?: boolean): AnswerWait;

package/dist/lib/components/ui/collections/filter/query/use-apply-now.d.ts

@@ -0,0 +1,6 @@
+/**
+ * "Apply now", one shot: the edit that asked is applied by the live timer (set
+ * in this commit, 0 ms); an edit that changed nothing must not leave the next
+ * one without its delay.
+ */
+export declare function useApplyNow(): [boolean, () => void];

package/dist/lib/components/ui/collections/filter/query/use-defaults.d.ts

@@ -0,0 +1,15 @@
+import { FilterCondition, FilterModelField } from '@nxgt/material-core/filter';
+/**
+ * The values a field is filtered by when the user chose none: its `default`
+ * (the page's `defaults` for a `'page'` one), `undefined` for none or while
+ * the page locks the field. Whether they apply now is `useIsDefaulted`.
+ */
+export declare function useFieldDefault(field: FilterModelField): readonly string[] | undefined;
+/** Whether the field is filtered by its default now: it has one and the user (or the staged draft) set no value. */
+export declare function useIsDefaulted(field: FilterModelField): boolean;
+/**
+ * The defaults that get a hint chip in the active filters: uncounted, no ✕
+ * (the core's `defaultHints`: not a toggle that is on, not a quick pill,
+ * which show the default themselves).
+ */
+export declare function useDefaultHints(): FilterCondition[];

package/dist/lib/components/ui/collections/filter/query/use-field-error.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The server's refusal of this field (the `errors` prop), `undefined` for
+ * none, for a field the model lacks and for a field the page locks.
+ */
+export declare function useFieldError(field: string): string | undefined;

package/dist/lib/components/ui/collections/filter/query/use-filter-query-options.d.ts

@@ -0,0 +1,14 @@
+import { FilterQueryProps } from './types.js';
+/** The props the model only carries through, with their defaults. */
+export declare function viewOptions({ defaults, errors, loading, resultCount, density, apply, searchApply, searchMinLength, previewCount, counts, }: FilterQueryProps): {
+    defaults: Readonly<Record<string, readonly string[]>> | undefined;
+    errors: Readonly<Record<string, string>> | undefined;
+    loading: boolean;
+    resultCount: number | undefined;
+    density: import('./types.js').FilterDensity;
+    apply: import('@nxgt/material-core/filter').FilterApply;
+    searchApply: import('@nxgt/material-core/filter').FilterSearchApplyMode;
+    searchMinLength: number;
+    previewCount: import('@nxgt/material-core/filter').FilterPreviewCount | undefined;
+    counts: import('@nxgt/material-core/filter').FilterCountsOption | undefined;
+};

package/dist/lib/components/ui/collections/filter/query/use-filter-query-value.d.ts

@@ -14,6 +14,8 @@ export declare function useFilterQueryValue(props: FilterQueryProps): {
     shortcuts: import('@nxgt/material-core/filter').FilterShortcutKeys;
     model: import('@nxgt/material-core/filter').FilterModel;
     machine: import('@nxgt/material-core/filter').FilterMachineState;
+    defaults?: import('@nxgt/material-core/filter').FilterDefaults;
+    errors?: import('@nxgt/material-core/filter').FilterFieldErrors;
     applied: import('@nxgt/material-core/filter').FilterQuery;
     editing: string | null;
     pending: boolean;

package/dist/lib/components/ui/collections/filter/query/use-filter-query.d.ts

@@ -1,4 +1,4 @@
-import { FilterApply, FilterCountsOption, FilterEvent, FilterFocusTarget, FilterMachineState, FilterModel, FilterPreviewCount, FilterQuery } from '@nxgt/material-core/filter';
+import { FilterApply, FilterCountsOption, FilterDefaults, FilterEvent, FilterFieldErrors, FilterFocusTarget, FilterMachineState, FilterModel, FilterPreviewCount, FilterQuery } from '@nxgt/material-core/filter';
 import { RefObject } from 'react';
 import { FilterDensity, FilterQueryProps, FilterSearchApply } from './types.js';
 import { FilterBarFields } from './use-filter-bar-fields.js';
@@ -6,6 +6,10 @@ import { FilterBarFields } from './use-filter-bar-fields.js';
 export type FilterQueryModel = FilterBarFields & {
     model: FilterModel;
     machine: FilterMachineState;
+    /** The `default: 'page'` fields' values (the `defaults` prop). */
+    defaults?: FilterDefaults;
+    /** A server's refusal per field id (the `errors` prop). */
+    errors?: FilterFieldErrors;
     applied: FilterQuery;
     editing: string | null;
     /** An edit not carried yet: the count shown is the previous query's. */
@@ -42,4 +46,4 @@ export type FilterQueryModel = FilterBarFields & {
  * and `locked` mirrored into it (an equal one changes nothing), and live
  * apply. Thin by design: every decision is the core's.
  */
-export declare function useFilterQuery({ model, query, defaultQuery, onQueryChange, locked, liveDelayMs, loading, resultCount, density, shortcuts: shortcutsOption, apply, searchApply, searchMinLength, previewCount, counts, }: FilterQueryProps): FilterQueryModel;
+export declare function useFilterQuery(props: FilterQueryProps): FilterQueryModel;

package/dist/lib/components/ui/collections/filter/query/use-filter-url-query.d.ts

@@ -0,0 +1,52 @@
+import { FilterDefaults, FilterLockedCondition, FilterModel, FilterQuery } from '@nxgt/material-core/filter';
+import { AnswerWait } from './use-answer-wait.js';
+/**
+ * How the page reads and writes the URL, to match the loader's
+ * `parseFilterQuery` / `serializeFilterQuery` options exactly: without them
+ * the chips and the loader's rows can disagree.
+ */
+export type FilterUrlCodec = {
+    /** Keeps the readable values of a list condition (`status=A&status=zzz`). */
+    keepKnownValues?: boolean;
+    /** `'standard'` writes `URLSearchParams`' own text; default `'readable'`. */
+    encoding?: 'readable' | 'standard';
+};
+export type UseFilterUrlQueryOptions = {
+    model: FilterModel;
+    /** The search params the page is at (the router's). */
+    params: URLSearchParams;
+    /** Hands the router the next params; the hook then waits for it to take them. */
+    onParamsChange: (next: URLSearchParams) => void;
+    /** The conditions the page imposes: never read from, nor written to, the URL. */
+    locked?: readonly FilterLockedCondition[];
+    /** The values of the `default: 'page'` fields, the loader's own. */
+    defaults?: FilterDefaults;
+    codec?: FilterUrlCodec;
+    /** Params dropped on every write: a cursor, a page, so a new query starts over. */
+    reset?: readonly string[];
+    /** The write the page has already started waiting on (`ServerTable`'s), else the hook's own. */
+    wait?: AnswerWait;
+};
+export type FilterUrlQuery = {
+    /** The user's query, read from where the list is heading. */
+    query: FilterQuery;
+    /** Writes the query into the params (the `reset` ones dropped, the others kept). */
+    onQueryChange: (next: FilterQuery) => void;
+    /** A write the router has not taken yet: the count on screen is the previous query's. */
+    waiting: boolean;
+    /** Where the list is heading: the write not taken yet, else the params. */
+    heading: string;
+};
+/**
+ * A filter's query bound to the search params: read from them, written back
+ * on a change with the `reset` params dropped (the cursor starts over), and
+ * `waiting` from the write until the router takes it. The page's own params
+ * (a sort, a tab) survive a write; the locked conditions are never written.
+ * `FilterBar` and `ServerTable` both use it, so they share one URL path.
+ *
+ * @example
+ * ```tsx
+ * const { query, onQueryChange, waiting } = useFilterUrlQuery({ model, params, onParamsChange: setParams });
+ * ```
+ */
+export declare function useFilterUrlQuery({ model, params, onParamsChange, locked, defaults, codec, reset, wait, }: UseFilterUrlQueryOptions): FilterUrlQuery;

package/dist/lib/components/ui/collections/filter/query/use-refusal-announcement.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The refusal text the bar's one live region adds to its message, once. It
+ * appears one frame after it is first there or changes (a refusal present at
+ * mount included, so the region changes after mount and is read), stays while
+ * the region says the same thing, and leaves when the region next changes for
+ * its own reason (a new count): that change is read anyway, so the count is
+ * never read a second time on the refusal's account, and no timer is involved.
+ * Clearing the refusal forgets it, so the same one returning is told again.
+ */
+export declare function useRefusalAnnouncement(refusal: string, base: string): string;

package/dist/lib/components/ui/collections/filter/sections/chips/condition-panel.d.ts

@@ -12,6 +12,7 @@ export type ConditionPanelProps = {
 /**
  * A chip's edit popover: a dialog named by its title ("Level is not", as in
  * "Add filter"; no operator picker: "Add filter" replaces a condition), the
- * field's value editor in it, the focus on its first control.
+ * field's value editor in it, the focus on its first control. A condition
+ * the server refused shows its message under the title.
  */
 export declare function ConditionPanel({ field, condition, Editor, onValues, onInteractOutside, onCloseAutoFocus, }: ConditionPanelProps): import("react").JSX.Element;

package/dist/lib/components/ui/collections/filter/sections/chips/filter-chip-body.d.ts

@@ -2,11 +2,13 @@ import { FilterLabeledParts } from '@nxgt/material-core/filter';
 import { ChipProps } from '../../../../display/chip/chip.js';
 export type FilterChipBodyProps = Omit<ChipProps, 'label' | 'dismissLabel' | 'size'> & {
     parts: FilterLabeledParts;
+    /** The server's refusal of this filter: the error tone and "Invalid" beside the words (`aria-describedby` is the caller's). */
+    error?: string;
 };
 /**
  * A user's filter as a chip: its words (`FilterChipLabel`), its ✕ named
- * "Remove <filter>", sized by the filter's density and marked with
+ * "Remove <filter>" (in the error tone, with "Invalid", when the server refused it), sized by the filter's density and marked with
  * `FILTER_CHIP_ATTRIBUTE` for the focus rules. `FilterChip` adds its edit
  * popover; ServerTable's empty page renders it as is.
  */
-export declare function FilterChipBody({ parts, ...props }: FilterChipBodyProps): import("react").JSX.Element;
+export declare function FilterChipBody({ parts, error, ...props }: FilterChipBodyProps): import("react").JSX.Element;

package/dist/lib/components/ui/collections/filter/sections/chips/filter-chip-list.d.ts

@@ -1,8 +1,9 @@
 /**
  * The active filters, a list named "Active filters": the page's locked
  * conditions first, then the user's in the order they were added, but what
- * the quick filters show themselves (`chipConditions`). Nothing when there
- * is none. The facets panel lists only the fields it has no section for
+ * the quick filters show themselves (`chipConditions`), then a hint chip for
+ * each default in effect (`FilterDefaultChip`: uncounted, no ✕). Nothing when
+ * there is none. The facets panel lists only the fields it has no section for
  * (`fields`), without the locked ones (it lists them itself), from its
  * draft while one is staged.
  */

package/dist/lib/components/ui/collections/filter/sections/chips/filter-default-chip.d.ts

@@ -0,0 +1,14 @@
+import { FilterCondition, FilterLabeledParts } from '@nxgt/material-core/filter';
+/**
+ * A default in effect, as the active filters list it: the field's words and
+ * values, then "Default", dashed beside the tinted chips of what the user
+ * set. No ✕, no count, no announcement. A button named "Status: Active,
+ * Upcoming, default value. Change", described "Default value, …": it opens
+ * the field's editor on the default, like an applied chip does, and the first
+ * edit makes the choice the user's own. A field with no editor (a custom one
+ * without `render`) gets a focusable `group` instead.
+ */
+export declare function FilterDefaultChip({ condition, parts, }: {
+    condition: FilterCondition;
+    parts: FilterLabeledParts;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/collections/filter/sections/chips/filter-default-group.d.ts

@@ -0,0 +1,16 @@
+import { FilterLabeledParts } from '@nxgt/material-core/filter';
+import { ReactNode } from 'react';
+/**
+ * The default chip of a field with no editor (a custom one without `render`):
+ * nothing to open, so a focusable `group` named by its words, with the hint
+ * as its tooltip and description.
+ */
+export declare function FilterDefaultGroup({ parts, name, hint, density, describedBy, invalid, children, }: {
+    parts: FilterLabeledParts;
+    name: string;
+    hint: string;
+    density: 'comfortable' | 'compact';
+    describedBy: string | undefined;
+    invalid: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/collections/filter/sections/chips/filter-default-parts.d.ts

@@ -0,0 +1,12 @@
+/** "Default" as the hint chip, a pill and a toggle name it (`material.filter.default.*`). */
+export declare function useDefaultWords(): {
+    label: string;
+    hint: string;
+    tag: string;
+};
+/** The "· Default" tag after a pill's or toggle's words: for the eye only, the hint describes it. */
+export declare function FilterDefaultTag(): import("react").JSX.Element;
+/** The hint a defaulted control is described by (`aria-describedby={id}`). */
+export declare function FilterDefaultHint({ id }: {
+    id: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/collections/filter/sections/chips/filter-error-parts.d.ts

@@ -0,0 +1,22 @@
+/** "Invalid" and the sentence a screen reader gets (`material.filter.error.*`). */
+export declare function useErrorWords(message: string): {
+    tag: string;
+    label: string;
+};
+/**
+ * The word after a refused chip's or pill's value: an icon and "Invalid", so
+ * the state is never colour alone. For the eye only; the description says it.
+ */
+export declare function FilterErrorTag({ message }: {
+    message: string;
+}): import("react").JSX.Element;
+/** What a refused chip or pill is described by (`aria-describedby={id}`). */
+export declare function FilterErrorDescription({ id, message, }: {
+    id: string;
+    message: string;
+}): import("react").JSX.Element;
+/** The refusal in a field's editor or section: its icon, the word and the message. */
+export declare function FilterErrorNote({ id, message, }: {
+    id: string;
+    message: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/collections/filter/sections/chips/use-control-description.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+/**
+ * What a control that can be defaulted and refused is described by: the
+ * `aria-describedby` ids, joined, the ids themselves, and the two sr-only nodes they name (the
+ * default's hint, the error's sentence), to render beside the control.
+ * Shared by the chips, the pills and the toggles, which each carried a copy.
+ */
+export declare function useControlDescription(byDefault: boolean, error: string | undefined): {
+    describedBy: string | undefined;
+    hintId: string;
+    errorId: string;
+    nodes: ReactNode;
+};

package/dist/lib/components/ui/collections/filter/sections/filter-facet-section.d.ts

@@ -8,6 +8,11 @@ import { FilterModelField } from '@nxgt/material-core/filter';
  * focus stays on the control. A lone switch or checkbox sits in a
  * full-width label, its row, which toggles it. It starts open when `roomy`
  * (the panel from 1024px), else only with a condition set (`sectionOpen`).
+ * A field in effect by its default (no value of the user's) shows it checked,
+ * with "Default" beside its title; unchecking or changing one makes the
+ * choice the user's own, counted and in the URL. A scope field (`scope: true`)
+ * is the first section, with no count, no Clear and no "Default". A condition
+ * the server refused shows its message under the title.
  */
 export declare function FilterFacetSection({ field, roomy, }: {
     field: FilterModelField;

package/dist/lib/components/ui/collections/filter/sections/filter-search.d.ts

@@ -3,9 +3,10 @@
  * (default) sends it as it is typed, applied after `liveDelayMs`;
  * `"enter"` keeps the text in a draft until Enter. Below `searchMinLength`
  * nothing is sent and a hint is announced politely. Clearing (✕, Escape)
- * applies at once in `"enter"`; `/` (its hint shown) focuses it.
+ * applies at once in `"enter"`; `/` (its hint shown) focuses it. Nothing for
+ * a model declared `search: false`.
  */
-export declare function FilterSearch({ label, placeholder, }: {
+export declare function FilterSearch(props: {
     label?: string;
     placeholder?: string;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;

package/dist/lib/components/ui/collections/filter/sections/filter-sections-classes.d.ts

@@ -36,6 +36,14 @@ export declare const FILTER_LOCKED_CHIP_CLASS: {
     readonly comfortable: "inline-flex max-w-full cursor-default items-center border border-[color-mix(in_oklab,var(--foreground)_15%,var(--background))] bg-muted/60 font-medium text-foreground outline-0 outline-transparent focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--primary-text) h-7 gap-[0.3125rem] rounded-lg px-2 text-[0.8125rem]";
     readonly compact: "inline-flex max-w-full cursor-default items-center border border-[color-mix(in_oklab,var(--foreground)_15%,var(--background))] bg-muted/60 font-medium text-foreground outline-0 outline-transparent focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--primary-text) h-6 gap-1 rounded-[0.4375rem] px-2 text-xs";
 };
+export declare const FILTER_DEFAULT_CHIP_CLASS: {
+    readonly comfortable: "inline-flex max-w-full cursor-default items-center border border-dashed border-[color-mix(in_oklab,var(--foreground)_30%,var(--background))] bg-transparent text-muted-foreground outline-0 outline-transparent focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--primary-text) h-7 gap-[0.3125rem] rounded-lg px-2 text-[0.8125rem]";
+    readonly compact: "inline-flex max-w-full cursor-default items-center border border-dashed border-[color-mix(in_oklab,var(--foreground)_30%,var(--background))] bg-transparent text-muted-foreground outline-0 outline-transparent focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--primary-text) h-6 gap-1 rounded-[0.4375rem] px-2 text-xs";
+};
+/** A refusal in an editor or a section: the error tone's text, an icon, the word and the message. */
+export declare const FILTER_ERROR_NOTE_CLASS = "mb-2 flex items-start gap-1.5 text-sm text-error-text";
+/** The "Default" tag after a hint's words, or a pill's or toggle's. */
+export declare const FILTER_DEFAULT_TAG_CLASS = "shrink-0 text-xs font-normal text-muted-foreground";
 /** The chip's operator, quieter than the field and its value. */
 export declare const FILTER_CHIP_OPERATOR_CLASS = "text-muted-foreground";
 /** The chip's value. */

package/dist/lib/components/ui/collections/filter/sections/renderers/choice-facet.d.ts

@@ -6,4 +6,4 @@ import { FilterEditorProps } from '../../editors/types.js';
  * `disabled`), each option with its count as every option group shows it
  * ("CE1 24", named "CE1 24 results"). A long list folds behind "Show more".
  */
-export declare function ChoiceFacet({ field, op, values, onValuesChange, labelledBy, }: FilterEditorProps): import("react").JSX.Element;
+export declare function ChoiceFacet({ field, op, values, onValuesChange, labelledBy, describedBy, }: FilterEditorProps): import("react").JSX.Element;

package/dist/lib/components/ui/collections/filter/sections/use-filter-shortcuts.d.ts

@@ -1,11 +1,12 @@
-import { FilterQueryModel } from '../query/use-filter-query.js';
+import { FilterQueryContextValue } from '../query/filter-query-context.js';
 /**
  * The bar's keys, on the window: `/` focuses the search and `F` opens "Add
  * filter", or the sheet on a phone (the core's `shortcutFor`: never while
  * typing, with a modifier, or while a layer is open, the bar's own popovers
- * included). Off with `shortcuts={false}`.
+ * included). Off with `shortcuts={false}`. A model with `search: false` sends
+ * `/` to the first quick filter.
  */
-export declare function useFilterShortcuts({ shortcuts, machine, editing, send, focus, canAdd, openSheet, }: Pick<FilterQueryModel, 'shortcuts' | 'machine' | 'editing' | 'send' | 'focus'> & {
+export declare function useFilterShortcuts({ shortcuts, model, quick, machine, editing, send, focus, canAdd, openSheet, }: Pick<FilterQueryContextValue, 'shortcuts' | 'model' | 'quick' | 'machine' | 'editing' | 'send' | 'focus'> & {
     /** The bar shows "Add filter", or the sheet a section (some field is not locked). */
     canAdd: boolean;
     /** On a phone: `F` opens the sheet. */

package/dist/lib/components/ui/collections/server-table/partials/server-table-empty-chips.d.ts

@@ -1,6 +1,6 @@
 /**
  * "Nothing matches": the user's filters that narrow the list, as chips
- * removed by their ✕ (a widening switch such as "Show archived" is not
+ * removed by their ✕ (a kept field, a widening switch such as "Show archived" or a scope such as the period, is not
  * one, a locked condition stays in the band), then "Clear all" while two
  * or a search remain. A removal focuses the next chip, then "Clear all",
  * then the search (the core's `focusAfterRemove`, from `empty`).

package/dist/lib/components/ui/collections/server-table/types.d.ts

@@ -1,4 +1,4 @@
-import { FilterLockedCondition, FilterModel } from '@nxgt/material-core/filter';
+import { FilterDefaults, FilterFieldErrors, FilterLockedCondition, FilterModel } from '@nxgt/material-core/filter';
 import { IconStyleInput } from '@nxgt/material-core/icons';
 import { ErrorStateKind } from '@nxgt/material-core/states';
 import { PagingNames, TableFilterBinding, TableSorting } from '@nxgt/material-core/table-url';
@@ -64,6 +64,18 @@ export type ServerTableFilter = {
     model: FilterModel;
     /** The conditions the page imposes: a lock in the band, never in the URL. */
     locked?: readonly FilterLockedCondition[];
+    /**
+     * The values of the `default: 'page'` fields, the same object as the
+     * loader's. The band shows a defaulted value (a hint chip, a pressed
+     * toggle), uncounted and with no ✕; the URL holds explicit choices only.
+     */
+    defaults?: FilterDefaults;
+    /**
+     * A server's refusal of a condition, by field id (`{ period: 'The period
+     * cannot exceed 366 days.' }`): the chip reads "Invalid", described by the
+     * message, the editor shows it and the live region tells it.
+     */
+    errors?: FilterFieldErrors;
     /**
      * How the page reads and writes the URL, to match the loader's
      * `parseFilterQuery` / `serializeFilterQuery` options exactly:

package/dist/lib/components/ui/collections/server-table/use-filter-params.d.ts

@@ -3,9 +3,10 @@ import { FilterQueryProps } from '../filter/internal.js';
 import { ServerTableFilter, ServerTableProps } from './types.js';
 import { TableAnswer } from './use-table-answer.js';
 /**
- * The Filter's props, bound to the search params: its query read from them,
- * and written back on a change, back on the first page (the cursor reset).
- * From that write until its answer lands (`announcing`), the Filter is told
- * `loading`: the count it would say is the previous query's.
+ * The Filter's props, bound to the search params through `useFilterUrlQuery`
+ * (the one `FilterBar` uses): its query read from them, and written back on a
+ * change, back on the first page (the cursor reset). From that write until
+ * its answer lands (`announcing`), the Filter is told `loading`: the count it
+ * would say is the previous query's.
  */
 export declare function useFilterParams<T extends RowData>(props: ServerTableProps<T>, filter: ServerTableFilter, { wait: answer, announcing }: TableAnswer): FilterQueryProps;

package/dist/lib/components/ui/collections/server-table/use-table-answer.d.ts

@@ -1,7 +1,7 @@
 import { FilterAnswerWatch } from '@nxgt/material-core/filter';
 import { RowData } from '@tanstack/react-table';
+import { AnswerWait } from '../filter/internal.js';
 import { ServerTableFilter, ServerTableProps } from './types.js';
-import { AnswerWait } from './use-answer-wait.js';
 /** What changes with an answer of the page (pure): the count, the rows
  * (`rows`: which array, counted), the error. */
 export declare function tableAnswerCount(totalCount: number, rows: number, errored: boolean): string;

package/dist/lib/components/ui/layout/app-shell/activity-column.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
 import { ActivityLayoutProps } from './activity-layout.types.js';
-type ColumnProps = Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'context' | 'headerTitle' | 'breadcrumb' | 'breadcrumbRoot' | 'headerActions' | 'avatar' | 'linkComponent' | 'menuOpen' | 'onMenuOpenChange' | 'routeTransition' | 'backdrop'> & {
+type ColumnProps = Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name' | 'context' | 'headerTitle' | 'breadcrumb' | 'breadcrumbRoot' | 'headerActions' | 'avatar' | 'linkComponent' | 'menuOpen' | 'onMenuOpenChange' | 'routeTransition' | 'backdrop' | 'keepClear'> & {
     /** The element of the content region. */
     as: 'main' | 'div';
     contained: boolean;
@@ -13,5 +13,5 @@ type ColumnProps = Pick<ActivityLayoutProps, 'items' | 'brand' | 'logo' | 'name'
  * The content column of {@link ActivityLayout}: the backdrop layer behind, the
  * app bar, the breadcrumb and the routed content region.
  */
-export declare function ActivityColumn({ as, contained, hasBackdrop, themeBackdrop, items, brand, logo, name, context, headerTitle, breadcrumb, breadcrumbRoot, headerActions, avatar, linkComponent, menuOpen, onMenuOpenChange, routeTransition, backdrop, children, }: ColumnProps): import("react").JSX.Element;
+export declare function ActivityColumn({ as, contained, hasBackdrop, themeBackdrop, items, brand, logo, name, context, headerTitle, breadcrumb, breadcrumbRoot, headerActions, avatar, linkComponent, menuOpen, onMenuOpenChange, routeTransition, backdrop, keepClear, children, }: ColumnProps): import("react").JSX.Element;
 export {};

package/dist/lib/components/ui/layout/app-shell/activity-layout.d.ts

@@ -15,4 +15,4 @@ export type { ActivityLayoutProps } from './activity-layout.types.js';
  * phone's toolbar (the bottom of the screen hidden). The bottom keeps clear
  * of a `MediaPlayerHost`'s docked bar (`--nxgt-media-dock`).
  */
-export declare function ActivityLayout({ items, brand, logo, name, context, headerTitle, breadcrumb, breadcrumbRoot, headerActions, avatar, linkComponent, contentAs: Content, scroll, align, menuOpen, onMenuOpenChange, routeTransition, backdrop, children, className, ...props }: ActivityLayoutProps): import("react").JSX.Element;
+export declare function ActivityLayout({ items, brand, logo, name, context, headerTitle, breadcrumb, breadcrumbRoot, headerActions, avatar, linkComponent, contentAs: Content, scroll, align, menuOpen, onMenuOpenChange, routeTransition, backdrop, keepClear, children, className, ...props }: ActivityLayoutProps): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/activity-layout.types.d.ts

@@ -110,4 +110,15 @@ export type ActivityLayoutProps = {
      * ```
      */
     backdrop?: ReactNode | false;
+    /**
+     * How the backdrop's glyphs (shapes or icons) keep clear of the page. A
+     * glyph is dropped whole, never moved. `true` (default): any glyph within
+     * 8px of text, a control or a surface (a card, a list, a table) is dropped.
+     * `'gaps'`: a glyph may also stay in a gap of 24px or more between two
+     * surfaces, with 4px to spare, so a dense page keeps some backdrop; it is
+     * still dropped when it meets text, a control or the inside of a surface.
+     * `false`: nothing is kept clear (the edge and the header band still are).
+     * See the app shell guide, "Keep the backdrop clear of the content".
+     */
+    keepClear?: boolean | 'gaps';
 } & ComponentProps<'div'>;

package/dist/lib/components/ui/layout/app-shell/backdrop-layer.d.ts

@@ -1,11 +1,13 @@
 import { ReactNode } from 'react';
+import { ClearMode } from './shapes-clear-content.js';
 /**
  * The layer behind the content column that holds the backdrop: the theme's
  * background (`themed`) or the app's own node. It is `inert`, `aria-hidden`
  * and takes no pointer, so what it draws is decoration only. A `Background`
  * node keeps its shapes whole, as the theme's does (use-keep-shapes-inside.ts).
  */
-export declare function BackdropLayer({ backdrop, themed, }: {
+export declare function BackdropLayer({ backdrop, themed, mode, }: {
     backdrop: ReactNode;
     themed: boolean;
+    mode?: ClearMode;
 }): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/shapes-clear-content.d.ts

@@ -18,3 +18,27 @@ export declare const SURFACES = "[data-slot=\"card\"], [data-slot=\"stat-card\"]
  * scroll offsets that bring them to the viewport.
  */
 export declare function hitsContent(shape: Box, occupied: readonly Box[], dx: number, dy: number, margin?: number): boolean;
+/**
+ * How the content is kept clear (`keepClear` on `ActivityLayout` and
+ * `AuthCard`): `all` drops every glyph that meets any occupied box (the
+ * default, `true`); `gaps` also lets a glyph stay in a wide gap between
+ * surfaces; `off` keeps nothing clear (`false`).
+ */
+export type ClearMode = 'all' | 'gaps' | 'off';
+/** The `keepClear` prop: `true` (default), `false`, or `'gaps'`. */
+export type KeepClear = boolean | 'gaps';
+/** The pass mode of a `keepClear` value. */
+export declare const clearMode: (keepClear: KeepClear) => ClearMode;
+/** The least gap between two surfaces, in pixels, a glyph may sit in (`keepClear="gaps"`). */
+export declare const GAP_MIN = 24;
+/** The space a glyph keeps from the surfaces around it in a gap, in pixels. */
+export declare const GAP_CLEARANCE = 4;
+/**
+ * The drop rule of `keepClear="gaps"`: whether a glyph must be dropped. It is
+ * dropped when it meets text, a control or a marked block (`solid`, with
+ * `margin`), or the inside of a surface (`GAP_CLEARANCE` plus the drift the
+ * margin holds above `CONTENT_MARGIN`). Otherwise it stays when it is clear of
+ * every surface by `margin` (free space, as in `all`), or when it sits between
+ * two surfaces whose free gap is `GAP_MIN` or more along either axis.
+ */
+export declare function hitsContentOutsideGaps(shape: Box, solid: readonly Box[], surfaces: readonly Box[], dx: number, dy: number, margin?: number): boolean;

package/dist/lib/components/ui/layout/app-shell/theme-backdrop.d.ts

@@ -1,8 +1,10 @@
+import { ClearMode } from './shapes-clear-content.js';
 /**
  * The nearest theme's background, filling the backdrop layer (it reads the
  * theme itself). Its shapes stay whole: none crosses the layer's edge or
  * reaches the header band (use-keep-shapes-inside.ts).
  */
-export declare function ThemeBackdrop({ anchored }: {
+export declare function ThemeBackdrop({ anchored, mode, }: {
     anchored?: boolean;
+    mode?: ClearMode;
 }): import("react").JSX.Element;

package/dist/lib/components/ui/layout/app-shell/use-keep-shapes-inside.d.ts

@@ -1,4 +1,5 @@
 import { Box } from './keep-shapes-inside.js';
+import { ClearMode } from './shapes-clear-content.js';
 /** The band's strips: a sticky one (the app bar) is measured where it rests, above the first strip that scrolls. */
 export declare function bandBoxes(column: Element, layer: Box): Box[];
 /**
@@ -14,13 +15,13 @@ export declare function bandBoxes(column: Element, layer: Box): Box[];
  * missing, the scene is only marked checked. Presets without discrete shapes (waves, gradient) are
  * only marked checked.
  */
-export declare function keepInside(layer: HTMLElement, column: HTMLElement, scenes: () => Element[], anchored?: boolean): () => void;
+export declare function keepInside(layer: HTMLElement, column: HTMLElement, scenes: () => Element[], anchored?: boolean, mode?: ClearMode): () => void;
 /** A callback ref for the theme's `Background`, a child of the backdrop layer (it is loaded lazily, so it mounts after this hook). */
-export declare function useKeepShapesInside(anchored?: boolean): (el: HTMLElement | null) => void;
+export declare function useKeepShapesInside(anchored?: boolean, mode?: ClearMode): (el: HTMLElement | null) => void;
 /**
  * The same for a `Background` the app passes as `backdrop`: a callback ref on
  * the backdrop layer, which finds every preset (`[data-background]`) inside it
  * whenever the layer's content changes, so a lazily loaded or swapped preset
  * is kept whole too. Anything else in the layer (a custom node) is left alone.
  */
-export declare function useKeepNodeShapesInside(anchored?: boolean): (layer: HTMLElement | null) => void;
+export declare function useKeepNodeShapesInside(anchored?: boolean, mode?: ClearMode): (layer: HTMLElement | null) => void;