@quazardous/qdadm 2.18.0 → 2.20.0

package/src/composables/useListPage.ts

@@ -28,7 +28,13 @@ import {
   provide,
   type Ref,
 } from 'vue'
-import { useRouter, useRoute } from 'vue-router'
+import { useRouter, useRoute, type RouteLocationRaw } from 'vue-router'
+import {
+  createDefaultRouteStatePersister,
+  resolveRouteStatePersister,
+  createRouteStatePersisterFactory,
+  type RouteStatePersister,
+} from '../routeState'
 import { useConfirm } from 'primevue/useconfirm'
 import { useHooks } from './useHooks.js'
 import { useEntityItemPage, type ParentConfig, type UseEntityItemPageReturn } from './useEntityItemPage.js'
@@ -68,6 +74,8 @@ import type {
 export type {
   ColumnConfig,
   FilterConfig,
+  FilterOptions,
+  FilterType,
   ActionConfig,
   ResolvedAction,
   HeaderActionConfig,
@@ -86,11 +94,11 @@ export type {
 // Stateless utilities (cookies, session storage, formatters, constants).
 import {
   PAGE_SIZE_OPTIONS,
-  getSavedPageSize,
+  restorePageSize,
   getSessionFilters,
-  getSessionSort,
-  setSessionSort,
-  persistPageSize,
+  restoreSort,
+  clearSessionSort,
+  retireLegacyPageSizeCookie,
 } from './useListPage.utils'
 import { useActionRegistry } from './useActionRegistry'
 import { useListFilters } from './useListPage.filters'
@@ -101,6 +109,9 @@ import { createOrchestratorToast } from './useOrchestratorToast'
 // Re-export PAGE_SIZE_OPTIONS so existing consumers (qdadm/index.ts,
 // composables/index.ts) keep their import path.
 export { PAGE_SIZE_OPTIONS } from './useListPage.utils'
+// A VALUE, not only a type: a consumer guard should read this list rather
+// than copy it, so adding a type here never turns correct code red (#2147).
+export { FILTER_TYPES } from './useListPage.types'
 
 
 /**
@@ -120,6 +131,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     persistFilters = true,
     persistSort = true,
     syncUrlParams = true,
+    routeState = null,
     autoLoadFilters = true,
     onBeforeLoad = null,
     onAfterLoad = null,
@@ -215,6 +227,41 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   // Session key for filter persistence (based on entity name)
   const filterSessionKey = entity || entityName
 
+  // App-wide route-state default (#2146). Null when the kernel said nothing,
+  // or when there is no kernel at all — which is the case in tests.
+  const kernelRouteState = inject<string | RouteStatePersister | null>('qdadmRouteState', null)
+
+  // Where this list remembers what it is showing (#2146).
+  //
+  // WHO DECIDES, most specific first: this list, then the entity (so every
+  // screen showing it agrees), then the kernel, then the default composition.
+  // Each level exists because somebody has to be able to say it at that level
+  // — a list is a screen's decision, an entity's medium is a modelling one,
+  // and the app-wide floor belongs in the bootstrap.
+  //
+  // Built HERE, before the state refs, because `pageSize` is restored from it
+  // and the table needs a row count from its very first render.
+  const routeStateScope = entity || entityName
+  const chosenRouteState = routeState ?? manager.routeState ?? kernelRouteState
+  const persister: RouteStatePersister = chosenRouteState
+    ? resolveRouteStatePersister(
+        chosenRouteState,
+        createRouteStatePersisterFactory({ router, route })
+      )
+    : createDefaultRouteStatePersister({ router, route })
+
+  // `syncUrlParams` governs WRITING, and only ever has: a list configured
+  // with `false` still restored from a query string typed by hand. Kept
+  // exactly, because moving this behind a seam must not change what any
+  // existing app does.
+  //
+  // Naming a persister is a deliberate choice about a medium, so it answers
+  // the URL flag rather than obeying it: `routeState` set means read AND
+  // write, whatever `syncUrlParams` says about the query string.
+  const routeStateWrites = chosenRouteState ? true : syncUrlParams
+
+  const storedRouteState = persister.read(routeStateScope)
+
   // Entity filters registry (optional, provided by consuming app)
   const entityFilters = inject<Record<string, { search?: SearchConfig; filters?: FilterConfig[] }>>(
     'qdadmEntityFilters',
@@ -238,15 +285,29 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
 
   // Pagination
   const page = ref(1)
-  const pageSize = ref(getSavedPageSize(defaultPageSize))
+  // Rows per page comes through the seam now (#2146) — by default routed to
+  // the same cookie it has always used, because it is a comfort setting
+  // somebody chose once, not something a link should impose on its reader.
+  //
+  // The legacy bare-number cookie is read when the seam has nothing, so an
+  // existing user's choice survives the move; the first change retires it.
+  const pageSize = ref(restorePageSize(storedRouteState?.pageSize, defaultPageSize))
   const totalRecords = ref(0)
   const rowsPerPageOptions = PAGE_SIZE_OPTIONS
 
-  // Sorting — restored from the per-entity session (#1218), defaultSort as
-  // fallback; same persistence discipline as filters/pageSize.
-  const savedSort = persistSort ? getSessionSort(filterSessionKey) : null
-  const sortField = ref<string | null>(savedSort ? savedSort.field : defaultSort)
-  const sortOrder = ref(savedSort ? savedSort.order : defaultSortOrder)
+  // Sorting — through the seam now (#2146), and still landing in the session
+  // by default: the composition routes `sort` back to `sessionStorage` on
+  // purpose, so an ordering keeps surviving a clean `/offers` the way it
+  // always has. Only the key changed, which is why the legacy entry is read
+  // when the seam has nothing.
+  const savedSort = persistSort
+    ? restoreSort(storedRouteState, filterSessionKey, {
+        field: defaultSort,
+        order: defaultSortOrder as 1 | -1,
+      })
+    : { field: defaultSort, order: defaultSortOrder as 1 | -1 }
+  const sortField = ref<string | null>(savedSort.field)
+  const sortOrder = ref<number>(savedSort.order)
 
   // Search
   const searchQuery = ref(savedSearch)
@@ -588,18 +649,38 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   // ============ FILTERS (#1195 — extracted subsystem) ============
   // loadItems and setSearch are passed as thunks: both are declared further
   // down and only ever run post-setup.
+  // Where this list remembers what it is showing (#2146).
+  //
+  // The scope is the entity, so two lists on one route stop colliding — the
+  // case page-compositions.md currently tells people to dodge by turning
+  // persistence off entirely.
+  //
+  // `syncUrlParams` governs WRITING, and only ever has: a list configured
+  // with `false` still restored from a query string typed by hand. Kept
+  // exactly, because moving this behind a seam must not change what any
+  // existing app does — the asymmetry is arguable, but arguing it belongs in
+  // its own change with its own changelog line.
+  //
+  // Naming a persister is a deliberate choice about a medium, so it answers
+  // the URL flag rather than obeying it: `routeState` set means read AND
+  // write, whatever `syncUrlParams` says about the query string.
+
   const listFilters = useListFilters({
     entityName,
+    persister,
+    routeStateScope,
+    routeStateWrites,
+    pageSize,
+    sortField,
+    sortOrder,
+    persistSort,
     manager,
     orchestrator,
     items: items as Ref<unknown[]>,
     page,
     searchQuery,
-    route,
-    router,
     savedFilters,
     persistFilters,
-    syncUrlParams,
     autoLoadFilters,
     filterSessionKey,
     entityFilters,
@@ -798,7 +879,9 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   function onPage(event: { page: number; rows: number }): void {
     page.value = event.page + 1
     pageSize.value = event.rows
-    persistPageSize(event.rows)
+    // Written by writeStateToUrl() below, through the persister, rather than
+    // straight to a cookie from here (#2146).
+    retireLegacyPageSizeCookie()
     // The page joins the URL (#2113) — it was the only piece of list state
     // that survived nothing, so leaving a list for a detail view and coming
     // back dropped the user on page 1.
@@ -818,11 +901,12 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
       sortField.value = event.sortField
       sortOrder.value = event.sortOrder as 1 | -1
     }
+    // Written through the persister by writeStateToUrl(), not straight to
+    // the session from here (#2146). The legacy entry is retired at the same
+    // time, so it cannot shadow the seam on a later read.
     if (persistSort) {
-      setSessionSort(filterSessionKey, {
-        field: sortField.value,
-        order: sortOrder.value as 1 | -1,
-      })
+      writeStateToUrl()
+      clearSessionSort(filterSessionKey)
     }
     loadItems()
   }
@@ -855,21 +939,55 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     return { name: `${routePrefix}-create` }
   }
 
+  /** Route names already reported as missing — one warning each. */
+  const warnedMissingRoutes = new Set<string>()
+
+  /**
+   * Navigate by route name, and say something when that name does not exist
+   * (#1923 lot 2).
+   *
+   * The failure this catches is quiet by nature: the route prefix is derived
+   * from the entity name, so a mismatch between the side that NAMES routes
+   * and the side that LOOKS THEM UP produces a push to a name nobody
+   * registered. Nothing happens, and nothing says why — the divergence that
+   * caused #1923 behaved exactly like this, invisible until someone clicked.
+   *
+   * We warn at the moment of use rather than auditing the prefix upfront: an
+   * entity that only ever appears as a child of another has no routes under
+   * its own prefix and is perfectly healthy, so an upfront check would cry
+   * wolf. A warning nobody trusts is worse than none (ADR 0011).
+   */
+  function pushNamedRoute(name: string, params?: Record<string, unknown>): void {
+    if (!router.hasRoute(name)) {
+      if (!warnedMissingRoutes.has(name)) {
+        warnedMissingRoutes.add(name)
+        console.warn(
+          `[qdadm] No route named "${name}" — this navigation does nothing. ` +
+            `The list for "${entity}" derives it from the route prefix ` +
+            `"${routePrefix}". Either that page is not declared, or the ` +
+            `prefix disagrees with the one its routes were registered under ` +
+            `(pass routePrefix on the entity, or on useListPage, to pin it).`
+        )
+      }
+      return
+    }
+    router.push({ name, ...(params ? { params } : {}) } as RouteLocationRaw)
+  }
+
   function goToCreate(): void {
-    router.push(findCreateRoute() as { name: string })
+    const target = findCreateRoute() as { name: string; params?: Record<string, unknown> }
+    pushNamedRoute(target.name, target.params)
   }
 
   function goToEdit(item: unknown): void {
-    router.push({
-      name: `${routePrefix}-edit`,
-      params: { [manager.idField]: (item as Record<string, unknown>)[resolvedDataKey] as string },
+    pushNamedRoute(`${routePrefix}-edit`, {
+      [manager.idField]: (item as Record<string, unknown>)[resolvedDataKey] as string,
     })
   }
 
   function goToShow(item: unknown): void {
-    router.push({
-      name: `${routePrefix}-show`,
-      params: { [manager.idField]: (item as Record<string, unknown>)[resolvedDataKey] as string },
+    pushNamedRoute(`${routePrefix}-show`, {
+      [manager.idField]: (item as Record<string, unknown>)[resolvedDataKey] as string,
     })
   }
 
@@ -1167,6 +1285,10 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     lazy: true,
     totalRecords: totalRecords.value,
     rows: pageSize.value,
+    // Where the paginator sits (#2145). Derived from `page` rather than held
+    // separately, so the highlighted page and the rows on screen cannot
+    // disagree — which is exactly what they did while this was unbound.
+    first: (page.value - 1) * pageSize.value,
     rowsPerPageOptions,
     sortField: sortField.value,
     sortOrder: sortOrder.value,

package/src/composables/useListPage.types.ts

@@ -3,6 +3,7 @@
  *
  * Extracted from useListPage.ts for maintainability.
  */
+import type { RouteStatePersister } from '../routeState'
 import type { Ref, ComputedRef } from 'vue'
 import type { Router } from 'vue-router'
 import type { FilterQuery } from '../query/FilterQuery'
@@ -76,9 +77,45 @@ export interface ColumnConfig {
 /**
  * Filter configuration
  */
-export interface FilterConfig {
-  name: string
-  type?: 'select' | 'multiselect' | 'date' | 'checkbox' | 'dropdown' | 'autocomplete'
+/**
+ * The filter controls qdadm knows how to render.
+ *
+ * Exported as a VALUE, not only a type, so a consumer's own guard can read
+ * this list instead of copying it — a copy goes stale the day a type is
+ * added and starts rejecting correct code.
+ */
+export const FILTER_TYPES = [
+  'select',
+  'multiselect',
+  'date',
+  'checkbox',
+  'dropdown',
+  'autocomplete',
+] as const
+
+export type FilterType = (typeof FILTER_TYPES)[number]
+
+/**
+ * Everything a filter can be given EXCEPT its name (#2147).
+ *
+ * Split out rather than written as `Omit<FilterConfig, 'name'>`, and the
+ * reason is not style. `FilterConfig` carries an index signature, so
+ * `keyof` includes `string`; `Exclude<string, 'name'>` is still `string`, and
+ * the `Omit` therefore collapsed to a bare `{ [x: string]: unknown }` —
+ * ERASING every declared property.
+ *
+ * `addFilter` took that type, so **no filter option was checked at all**:
+ * not `type`, not `optionLabel`, not `local_filter`. A consumer declared
+ * `type: 'text'`, TypeScript accepted it, and the filter rendered as an empty
+ * dropdown saying "No available options". Nothing was wrong at any single
+ * step, which is why it survived.
+ *
+ * Declaring the properties here and having `FilterConfig` extend it keeps the
+ * index signature — apps do stash their own keys — while the declared ones
+ * are checked again.
+ */
+export interface FilterOptions {
+  type?: FilterType
   placeholder?: string
   options?: Array<{ label: string; value: unknown }>
   default?: unknown
@@ -101,6 +138,10 @@ export interface FilterConfig {
   [key: string]: unknown
 }
 
+export interface FilterConfig extends FilterOptions {
+  name: string
+}
+
 /**
  * Row action configuration
  */
@@ -229,8 +270,27 @@ export interface UseListPageOptions<T = unknown> {
   persistFilters?: boolean
   /** Persist the active sort per entity (session storage), restored on init (#1218). Default true. */
   persistSort?: boolean
-  /** Sync filters to URL query params (default: true) */
+  /**
+   * WRITE filters, search and the page to the URL query (default: true).
+   *
+   * Writing only. `false` has never stopped the query string being read, so
+   * a deep link someone typed by hand still restores the list — say
+   * `routeState` if you want the state kept somewhere else entirely.
+   */
   syncUrlParams?: boolean
+  /**
+   * Where this list's state is remembered (#2146): a slug the framework
+   * knows (`'url'`, …), or your own persister. Defaults to the URL.
+   *
+   * Setting it is a deliberate choice of medium, so it answers
+   * `syncUrlParams` rather than obeying it: a list with `routeState` set
+   * reads and writes that medium whatever the URL flag says.
+   *
+   * An unknown slug throws rather than falling back to the URL — a list
+   * quietly persisting somewhere other than where you asked is worse than
+   * one that will not start (ADR 0011).
+   */
+  routeState?: string | RouteStatePersister
   /** Filter mode: 'auto' | 'manager' | 'local' */
   filterMode?: 'auto' | 'manager' | 'local'
   /** Auto-filter threshold for 'auto' mode */
@@ -270,6 +330,15 @@ export interface ListPageProps {
   lazy: boolean
   totalRecords: number
   rows: number
+  /**
+   * Row offset of the current page — what POSITIONS the paginator (#2145).
+   *
+   * In lazy mode the table renders exactly the rows it is handed and has no
+   * way to know which page they are; `first` is the only thing that tells it.
+   * Without it, a restored page 2 showed page 2's rows under a paginator
+   * highlighting 1.
+   */
+  first: number
   rowsPerPageOptions: number[]
   sortField: string | null
   sortOrder: number
@@ -382,7 +451,7 @@ export interface UseListPageReturn<T = unknown> {
   filterValues: Ref<Record<string, unknown>>
   filteredItems: ComputedRef<T[]>
   fromCache: Ref<boolean>
-  addFilter: (name: string, config: Omit<FilterConfig, 'name'>) => void
+  addFilter: (name: string, config: FilterOptions) => void
   removeFilter: (name: string) => void
   setFilterValue: (name: string, value: unknown) => void
   updateFilters: (values: Record<string, unknown>) => void

package/src/composables/useListPage.utils.ts

@@ -40,6 +40,35 @@ export function persistPageSize(size: number): void {
   setCookie(COOKIE_NAME, size, COOKIE_EXPIRY_DAYS)
 }
 
+/**
+ * Settle the rows-per-page a list opens on (#2146).
+ *
+ * The seam owns this now, so the stored value arrives from whichever medium
+ * the app chose. The LEGACY bare-number cookie is read only when the seam has
+ * nothing — an existing user's choice must survive the move, or a comfort
+ * setting they picked once quietly resets on upgrade.
+ *
+ * Anything outside {@link PAGE_SIZE_OPTIONS} falls back to the default: the
+ * value reaches us from a cookie or a query string that anyone can edit, and
+ * a row count the paginator cannot offer would leave its dropdown showing a
+ * blank.
+ */
+export function restorePageSize(stored: unknown, defaultSize: number): number {
+  const fromSeam = Number(stored)
+  if (PAGE_SIZE_OPTIONS.includes(fromSeam)) return fromSeam
+  return getSavedPageSize(defaultSize)
+}
+
+/**
+ * Drop the pre-seam cookie once its value has been carried over.
+ *
+ * Left in place it would outlive the setting it stands for by a year, and
+ * shadow the seam on any machine where the new store was cleared.
+ */
+export function retireLegacyPageSizeCookie(): void {
+  setCookie(COOKIE_NAME, '', -1)
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Default label formatter (snake_case → Title Case)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -129,6 +158,35 @@ export function clearSessionSort(key: string): void {
   }
 }
 
+/**
+ * Settle the sort a list opens on (#2146).
+ *
+ * The seam owns this now. The medium has not changed — the default
+ * composition routes `sort` back to `sessionStorage`, deliberately, so that
+ * moving it behind an interface changes nothing anyone can observe. Only the
+ * KEY changed, from `qdadm_sort_offers` to `qdadm:offers:sort`.
+ *
+ * Which is why the legacy entry is still read when the seam has nothing: a
+ * sort somebody set five minutes ago must not vanish because the framework
+ * was upgraded under them.
+ */
+export function restoreSort(
+  stored: { sort?: unknown; sortOrder?: unknown } | null,
+  legacyKey: string,
+  defaults: SessionSort
+): SessionSort {
+  const field = stored?.sort
+  const order = Number(stored?.sortOrder)
+  if (typeof field === 'string' && field && (order === 1 || order === -1)) {
+    return { field, order }
+  }
+
+  const legacy = getSessionSort(legacyKey)
+  if (legacy) return legacy
+
+  return defaults
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Smart filter discovery
 // ─────────────────────────────────────────────────────────────────────────────

package/src/entity/EntityManager.interface.ts

@@ -27,6 +27,7 @@
 import type { EntityBadge } from './EntityManager.types'
 import type { SignalBus } from '../kernel/SignalBus'
 import type { EntityAuthAdapter } from './auth/EntityAuthAdapter'
+import type { RouteStatePersister } from '../routeState'
 
 // ─── Base ────────────────────────────────────────────────────────────────────
 
@@ -84,6 +85,16 @@ export interface EntityManagerRead<T = unknown> extends EntityManagerBase<T>, En
   getFieldConfig: (name: string) => unknown | null
   /** Config-carrying property: always present on the class, VALUE nullable */
   localFilterThreshold?: number | null
+  /**
+   * Where lists of this entity remember their state (#2146): a slug the
+   * framework knows, or a persister instance.
+   *
+   * A property of the ENTITY, so every screen showing it agrees — a list of
+   * audit rows nobody links to can say `local_storage` once here rather than
+   * on each of the four pages that render it. A list's own `routeState`
+   * still wins; the kernel default applies when neither says anything.
+   */
+  routeState?: string | RouteStatePersister
 }
 
 // ─── CRUD ────────────────────────────────────────────────────────────────────

package/src/entity/EntityManager.ts

@@ -51,6 +51,7 @@ export type {
 } from './EntityManager.types'
 
 // Import concrete types needed in method signatures
+import type { RouteStatePersister } from '../routeState'
 import type {
   RoutingContext,
   PresaveContext,
@@ -88,6 +89,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   protected _fields: Record<string, FieldConfig>
 
   localFilterThreshold: number | null
+  /** Where lists of this entity remember their state (#2146); null = inherit. */
+  routeState: string | RouteStatePersister | null
   /** Default null placement for local sorts (#1222); field-level nullSort wins. */
   nullSort?: NullSortMode
   protected _cacheTtlMs: number | null
@@ -163,6 +166,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
       badges = null,
       fields = {},
       localFilterThreshold = null,
+      routeState = null,
       nullSort,
       cacheTtlMs = null,
       asymmetric = false,
@@ -196,6 +200,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     this._fields = fields
 
     this.localFilterThreshold = localFilterThreshold
+    this.routeState = routeState
     this.nullSort = nullSort
     this._cacheTtlMs = cacheTtlMs
     this._asymmetric = asymmetric

package/src/entity/EntityManager.types.ts

@@ -16,6 +16,7 @@ import type { HookRegistry } from '../hooks/HookRegistry'
 
 // Circular type import — safe because `import type` is erased at runtime
 import type { EntityManager } from './EntityManager'
+import type { RouteStatePersister } from '../routeState'
 
 // ============ INTERNAL TYPES ============
 
@@ -235,6 +236,16 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   badges?: (entity: T) => EntityBadge[]
   fields?: Record<string, FieldConfig>
   localFilterThreshold?: number | null
+  /**
+   * Where lists of this entity remember their state (#2146): a slug the
+   * framework knows, or a persister instance.
+   *
+   * A property of the ENTITY, so every screen showing it agrees — a list of
+   * audit rows nobody links to can say `local_storage` once here rather than
+   * on each of the four pages that render it. A list's own `routeState`
+   * still wins; the kernel default applies when neither says anything.
+   */
+  routeState?: string | RouteStatePersister
   /** Default null placement for local sorts: 'first' | 'last' | 'low' | 'high' (default 'last', #1222). Field-level nullSort wins. */
   nullSort?: NullSortMode
   /** Cache TTL in milliseconds (0=disabled, -1=infinite, >0=TTL). Overrides global, overridden by storage. */

package/src/entity/storage/ApiStorage.ts

@@ -151,7 +151,7 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
   }
 
   async list(params: ListParams = {}, context: RoutingContext | null = null): Promise<ListResult<T>> {
-    const { page = 1, page_size = 20, sort_by, sort_order, filters = {} } = params
+    const { page = 1, page_size = 20, sort_by, sort_order, search, filters = {} } = params
 
     // `paramMapping` covers the WHOLE outgoing query, pagination included
     // (#2113). It used to be applied to the filters only, so `status` could
@@ -160,9 +160,23 @@ export class ApiStorage<T extends EntityRecord = EntityRecord> extends IStorage<
     // storage for that alone. The names qdadm uses internally are its own
     // business; what goes on the wire is the backend's.
     //
+    // `search` goes out too (#2147). It is part of `ListParams` and always
+    // has been, but this method never read it — a user typed in the search
+    // box, the list rebuilt its query, and the term was dropped here without
+    // a word. The rows came back unfiltered and nothing anywhere said why,
+    // which is the silent no-op ADR 0011 exists to forbid.
+    //
+    // It travels under whatever name your backend uses, like every other key:
+    // `paramMapping: { search: 'q' }`.
+    //
+    // `searchFields` deliberately stays behind. It says which fields the
+    // FRONT should look at when filtering a cached page locally; a backend
+    // that searches knows its own columns, and shipping an array parameter
+    // nobody asked for would be a new surprise in place of the old one.
+    //
     // Filters keep their precedence over the pagination keys, exactly as
     // before: a filter named `page` still wins, for better or worse.
-    const outgoing = { page, page_size, sort_by, sort_order, ...filters }
+    const outgoing = { page, page_size, sort_by, sort_order, search, ...filters }
 
     const response = await this.client.get<Record<string, unknown>>(this.endpoint, {
       params: this._applyParamMapping(outgoing),

package/src/entity/storage/LocalStorage.ts

@@ -67,7 +67,7 @@ export class LocalStorage<T extends EntityRecord = EntityRecord> extends IStorag
     items = filterItems(items, filters, { stringMatch: 'exact' })
 
     // Apply search (shared pipeline, #1192)
-    items = searchItems(items, search as string | undefined)
+    items = searchItems(items, search)
 
     const total = items.length
 

package/src/entity/storage/MemoryStorage.ts

@@ -1,7 +1,7 @@
 import { IStorage } from './IStorage'
 import type { EntityRecord, ListParams, ListResult, StorageCapabilities } from '../../types'
 import { StorageError } from './errors'
-import { sortItems, filterItems, paginate, defaultGenerateId } from '../../query/clientFilter'
+import { sortItems, filterItems, paginate, defaultGenerateId, searchItems } from '../../query/clientFilter'
 
 /**
  * MemoryStorage options
@@ -61,10 +61,15 @@ export class MemoryStorage<T extends EntityRecord = EntityRecord> extends IStora
   }
 
   async list(params: ListParams = {}): Promise<ListResult<T>> {
-    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {} } = params
+    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {}, search } = params
 
     let items = this._getAll()
 
+    // Apply the search term (#2147). `searchItems` has existed since #1192
+    // and LocalStorage and MockApiStorage both called it; this one never did,
+    // so a search box over a MemoryStorage entity typed into the void.
+    items = searchItems(items, search)
+
     // Apply filters (shared pipeline, #1192 — legacy substring semantics)
     items = filterItems(items, filters, { stringMatch: 'includes' })
 

package/src/entity/storage/MockApiStorage.ts

@@ -151,7 +151,7 @@ export class MockApiStorage<T extends EntityRecord = EntityRecord> extends IStor
     }
 
     // Apply search (shared pipeline, #1192)
-    items = searchItems(items, search as string | undefined)
+    items = searchItems(items, search)
 
     const total = items.length