@chelone/core 0.6.0 → 0.9.0

package/dist/controller/list-controller.js

@@ -1,425 +1,472 @@
-import { QueryObserver } from "@tanstack/query-core";
 import { getListOptions } from "../data/query-options.js";
+import { removeEmpty } from "../data/remove-empty.js";
+import { isRecord } from "../guards.js";
 import { createMicroStore } from "../store/micro-store.js";
-const DEFAULT_PER_PAGE = 10;
-const DEFAULT_DEBOUNCE_MS = 500;
-const DEFAULT_SELECT_ALL_LIMIT = 250;
-const DEFAULT_SORT = [{ field: "id", order: "ASC" }];
+import { QueryObserver } from "@tanstack/query-core";
+// src/controller/list-controller.ts
+/** The `perPage` a list starts at when nothing is persisted or in the URL. The single definition: `prev-next` and both adapters read this. */
+var DEFAULT_PER_PAGE = 10;
+/** Debounce delay for `setFilters(..., debounced=true)` when no `debounceMs` option is given. Shared with the reference-many and choices controllers. */
+var DEFAULT_DEBOUNCE_MS = 500;
+var DEFAULT_SORT = [{
+	field: "id",
+	order: "ASC"
+}];
 function normalizeSort(sort, fallback) {
-  if (!sort) return fallback.map((entry) => ({ ...entry }));
-  const entries = Array.isArray(sort) ? sort : [sort];
-  return entries.map((entry) => ({ ...entry }));
-}
-function removeEmpty(filter) {
-  const result = {};
-  for (const [key, value] of Object.entries(filter)) {
-    if (value === "" || value === null || value === void 0) continue;
-    result[key] = value;
-  }
-  return result;
+	if (!sort) return fallback.map((entry) => ({ ...entry }));
+	return (Array.isArray(sort) ? sort : [sort]).map((entry) => ({ ...entry }));
 }
+/**
+* Returns `filter` without the value at `path`: the flat key of that name and,
+* for a dotted path, the nested value, pruning parents it leaves empty. Never
+* mutates `filter`. Shared with the client controller.
+*/
 function removeFilterPath(filter, path) {
-  const { [path]: _flat, ...rest } = filter;
-  const keys = path.split(".");
-  if (keys.length === 1) return rest;
-  const prune = (node, depth) => {
-    const key = keys[depth];
-    const child = node[key];
-    if (depth === keys.length - 1) {
-      const { [key]: _removed, ...others } = node;
-      return others;
-    }
-    if (child == null || typeof child !== "object" || Array.isArray(child)) {
-      return node;
-    }
-    const pruned = prune(child, depth + 1);
-    if (pruned === child) return node;
-    if (Object.keys(pruned).length === 0) {
-      const { [key]: _emptied, ...others } = node;
-      return others;
-    }
-    return { ...node, [key]: pruned };
-  };
-  return prune(rest, 0);
+	const { [path]: _flat, ...rest } = filter;
+	const keys = path.split(".");
+	if (keys.length === 1) return rest;
+	const prune = (node, depth) => {
+		const key = keys[depth];
+		if (key === void 0) return node;
+		const child = node[key];
+		if (depth === keys.length - 1) {
+			const { [key]: _removed, ...others } = node;
+			return others;
+		}
+		if (!isRecord(child)) return node;
+		const pruned = prune(child, depth + 1);
+		if (pruned === child) return node;
+		if (Object.keys(pruned).length === 0) {
+			const { [key]: _emptied, ...others } = node;
+			return others;
+		}
+		return {
+			...node,
+			[key]: pruned
+		};
+	};
+	return prune(rest, 0);
 }
+/**
+* Turns a {@link ListParamsPatch} into the state slice it changes. Shared with
+* the client controller so the page-reset rule lives in one place.
+*/
 function listParamsFromPatch(patch) {
-  const next = {};
-  if (patch.filter !== void 0) next.filter = removeEmpty(patch.filter);
-  if (patch.displayedFilters !== void 0) {
-    next.displayedFilters = { ...patch.displayedFilters };
-  }
-  if (patch.sort !== void 0) next.sort = normalizeSort(patch.sort, []);
-  if (patch.perPage !== void 0) next.perPage = patch.perPage;
-  if (patch.page !== void 0) {
-    next.page = patch.page;
-  } else if (patch.filter !== void 0 || patch.sort !== void 0 || patch.perPage !== void 0) {
-    next.page = 1;
-  }
-  return next;
+	const next = {};
+	if (patch.filter !== void 0) next.filter = removeEmpty(patch.filter);
+	if (patch.displayedFilters !== void 0) next.displayedFilters = { ...patch.displayedFilters };
+	if (patch.sort !== void 0) next.sort = normalizeSort(patch.sort, []);
+	if (patch.perPage !== void 0) next.perPage = patch.perPage;
+	if (patch.page !== void 0) next.page = patch.page;
+	else if (patch.filter !== void 0 || patch.sort !== void 0 || patch.perPage !== void 0) next.page = 1;
+	return next;
 }
+/** The notification key for a failed fetch: the error's own message, else `chelone.notification.http_error`. */
 function errorMessageKey(error) {
-  const message = error instanceof Error ? error.message : "";
-  return message || "chelone.notification.http_error";
+	return (error instanceof Error ? error.message : "") || "chelone.notification.http_error";
 }
+/** Notifies a failed fetch under its message, falling back to the generic http error. */
 function notifyFetchError(notifications, error) {
-  notifications?.notify(errorMessageKey(error), {
-    type: "error",
-    messageArgs: { _: String(error) }
-  });
+	notifications?.notify(errorMessageKey(error), {
+		type: "error",
+		messageArgs: { _: String(error) }
+	});
 }
+/** Warns that `selectAll` stopped at `limit` rows. A shorter result is complete and stays quiet. */
 function notifySelectAllLimit(notifications, count, limit) {
-  if (count < limit) return;
-  notifications?.notify("chelone.message.select_all_limit_reached", {
-    type: "warning",
-    messageArgs: { max: limit }
-  });
+	if (count < limit) return;
+	notifications?.notify("chelone.message.select_all_limit_reached", {
+		type: "warning",
+		messageArgs: { max: limit }
+	});
 }
-async function runSelectAll(notifications, fetchPage, apply, isDestroyed, limit = DEFAULT_SELECT_ALL_LIMIT) {
-  if (isDestroyed()) return;
-  try {
-    const rows = await fetchPage(limit);
-    if (isDestroyed()) return;
-    apply(rows.map((record) => record.id));
-    notifySelectAllLimit(notifications, rows.length, limit);
-  } catch (error) {
-    if (isDestroyed()) return;
-    notifyFetchError(notifications, error);
-  }
+/**
+* Fetches one page with `limit` (default 250), applies its ids, then warns at
+* the limit. Fetch, apply and warning failures use `notifyFetchError`.
+* Destruction skips the fetch or suppresses its result and failure notification.
+*/
+async function runSelectAll(notifications, fetchPage, apply, isDestroyed, limit = 250) {
+	if (isDestroyed()) return;
+	try {
+		const rows = await fetchPage(limit);
+		if (isDestroyed()) return;
+		apply(rows.map((record) => record.id));
+		notifySelectAllLimit(notifications, rows.length, limit);
+	} catch (error) {
+		if (isDestroyed()) return;
+		notifyFetchError(notifications, error);
+	}
 }
+/**
+* Notifies a distinct error OBJECT once however many results carry it (a new
+* Error with the same message is a new failure and is announced). `rearm`
+* forgets the last one, so a controller that wants the same error announced
+* again after a success can say so.
+*/
 function createErrorAnnouncer(notifications) {
-  let last = null;
-  return {
-    announce(error) {
-      if (!error || error === last) return;
-      last = error;
-      notifyFetchError(notifications, error);
-    },
-    rearm() {
-      last = null;
-    }
-  };
+	let last = null;
+	return {
+		announce(error) {
+			if (!error || error === last) return;
+			last = error;
+			notifyFetchError(notifications, error);
+		},
+		rearm() {
+			last = null;
+		}
+	};
 }
+/** `hasNextPage`/`hasPreviousPage` from the provider's `pageInfo` or, failing that, the total. */
 function pageFlags(page, perPage, total, pageInfo) {
-  if (pageInfo) {
-    return {
-      hasNextPage: pageInfo.hasNextPage,
-      hasPreviousPage: pageInfo.hasPreviousPage
-    };
-  }
-  if (total !== void 0) {
-    return { hasNextPage: page * perPage < total, hasPreviousPage: page > 1 };
-  }
-  return { hasNextPage: void 0, hasPreviousPage: void 0 };
+	if (pageInfo) return {
+		hasNextPage: pageInfo.hasNextPage,
+		hasPreviousPage: pageInfo.hasPreviousPage
+	};
+	if (total !== void 0) return {
+		hasNextPage: page * perPage < total,
+		hasPreviousPage: page > 1
+	};
+	return {
+		hasNextPage: void 0,
+		hasPreviousPage: void 0
+	};
 }
+/**
+* The page an out-of-range state should move to, or undefined when it is in
+* range. Only a SETTLED result may move past page 1, so a reset-induced
+* refetch can never trigger another reset.
+*/
 function resetPageTarget(s) {
-  if (s.page <= 0) return 1;
-  if (s.isPending || s.isFetching) return void 0;
-  if (s.total !== void 0) {
-    const lastPage = Math.max(Math.ceil(s.total / s.perPage), 1);
-    return s.page > lastPage ? lastPage : void 0;
-  }
-  if (s.page > 1 && s.data !== void 0 && s.data.length === 0) return 1;
-  return void 0;
+	if (s.page <= 0) return 1;
+	if (s.isPending || s.isFetching) return void 0;
+	if (s.total !== void 0) {
+		const lastPage = Math.max(Math.ceil(s.total / s.perPage), 1);
+		return s.page > lastPage ? lastPage : void 0;
+	}
+	if (s.page > 1 && s.data !== void 0 && s.data.length === 0) return 1;
 }
+/**
+* Vanilla list controller: one QueryObserver mapped into a micro-store.
+*
+* Lifecycle (Task 4R): construction is INERT — pure state + closures, zero
+* subscriptions, zero fetching. A controller constructed in a discarded
+* React render (Suspense retry, StrictMode double render, hidden
+* <Activity> pre-render) is plain garbage, never a zombie. Acquisition
+* (QueryObserver + KV selection subscription) happens on the micro-store's
+* FIRST subscriber; the LAST unsubscribe releases everything. Attach/detach
+* cycles are re-entrant; re-attach rebuilds query options from CURRENT
+* state, so params changed while detached take effect on the next attach.
+* `destroy()` remains the hard imperative teardown for non-React consumers.
+*
+* Loop-prevention architecture rule: `observer.setOptions` is called ONLY
+* from param-mutating actions — never directly from the observer result
+* subscription. Out-of-range page resets go through the normal `setPage`
+* action path and are guarded to run only on SETTLED results, so they
+* cannot ping-pong.
+*/
+/**
+* The actions of a list controller, for an adapter to spread next to its own
+* reactive state. They are the same functions across state changes.
+*/
 function listControllerActions(controller) {
-  return {
-    setPage: controller.setPage,
-    setPerPage: controller.setPerPage,
-    setSort: controller.setSort,
-    setFilters: controller.setFilters,
-    setParams: controller.setParams,
-    showFilter: controller.showFilter,
-    hideFilter: controller.hideFilter,
-    select: controller.select,
-    toggleItem: controller.toggleItem,
-    unselectAll: controller.unselectAll,
-    selectAll: controller.selectAll,
-    refetch: controller.refetch
-  };
+	return {
+		setPage: controller.setPage,
+		setPerPage: controller.setPerPage,
+		setSort: controller.setSort,
+		setFilters: controller.setFilters,
+		setParams: controller.setParams,
+		showFilter: controller.showFilter,
+		hideFilter: controller.hideFilter,
+		select: controller.select,
+		toggleItem: controller.toggleItem,
+		unselectAll: controller.unselectAll,
+		selectAll: controller.selectAll,
+		refetch: controller.refetch
+	};
 }
 function createListController(ctx, resource, options = {}) {
-  const storeKey = options.storeKey === false ? null : options.storeKey ?? resource;
-  const paramsKey = storeKey ? `${storeKey}.listParams` : null;
-  const selectionKey = storeKey ? `${storeKey}.selectedIds` : null;
-  const kv = ctx.store;
-  const defaults = {
-    page: 1,
-    perPage: options.perPage ?? DEFAULT_PER_PAGE,
-    sort: normalizeSort(options.sort, DEFAULT_SORT),
-    filter: { ...options.filterDefaultValues ?? {} },
-    displayedFilters: {}
-  };
-  const persisted = paramsKey && kv ? kv.getItem(paramsKey) : void 0;
-  const initialParams = persisted ? {
-    page: persisted.page ?? defaults.page,
-    perPage: persisted.perPage ?? defaults.perPage,
-    sort: normalizeSort(persisted.sort, defaults.sort),
-    filter: { ...persisted.filter ?? defaults.filter },
-    displayedFilters: { ...persisted.displayedFilters ?? {} }
-  } : defaults;
-  const readSelection = () => (selectionKey && kv ? kv.getItem(selectionKey) : void 0) ?? [];
-  const store = createMicroStore(
-    {
-      ...initialParams,
-      selectedIds: readSelection(),
-      data: void 0,
-      total: void 0,
-      pageInfo: void 0,
-      isPending: true,
-      isFetching: false,
-      error: null,
-      hasNextPage: void 0,
-      hasPreviousPage: void 0
-    },
-    // Acquisition is subscription-driven: nothing is fetched or subscribed
-    // until the first subscriber attaches (see `acquire` below, hoisted).
-    { onSubscribed: acquire }
-  );
-  let destroyed = false;
-  store.onDestroy(() => {
-    destroyed = true;
-  });
-  let observer = null;
-  const buildOptions = () => {
-    const s = store.getSnapshot();
-    return {
-      ...getListOptions(ctx, resource, {
-        pagination: { page: s.page, perPage: s.perPage },
-        // Pass a single object when there is exactly one key (adapter compat).
-        sort: s.sort.length === 1 ? s.sort[0] : s.sort,
-        filter: { ...s.filter, ...options.filter ?? {} }
-      }),
-      placeholderData: (prev) => prev,
-      retry: false,
-      enabled: options.enabled ?? true
-    };
-  };
-  const persistParams = () => {
-    if (!paramsKey || !kv) return;
-    const s = store.getSnapshot();
-    const params = {
-      page: s.page,
-      perPage: s.perPage,
-      sort: s.sort,
-      filter: s.filter,
-      displayedFilters: s.displayedFilters
-    };
-    kv.setItem(paramsKey, params);
-  };
-  const applyParams = (patch) => {
-    store.setState(patch);
-    persistParams();
-    observer?.setOptions(buildOptions());
-  };
-  const setPage = (page) => {
-    if (destroyed) return;
-    applyParams({ page });
-  };
-  const setPerPage = (perPage) => {
-    if (destroyed) return;
-    applyParams({ perPage, page: 1 });
-  };
-  const setSort = (input) => {
-    if (destroyed) return;
-    const current = store.getSnapshot().sort;
-    const single = current.length === 1 ? current[0] : void 0;
-    let next;
-    if (Array.isArray(input)) {
-      next = input.map((entry) => ({ ...entry }));
-    } else if (single && single.field === input.field) {
-      next = [
-        { field: input.field, order: single.order === "ASC" ? "DESC" : "ASC" }
-      ];
-    } else {
-      next = [{ field: input.field, order: input.order ?? "ASC" }];
-    }
-    applyParams({ sort: next, page: 1 });
-  };
-  const applyFilters = (filter, displayedFilters) => {
-    applyParams({
-      filter: removeEmpty(filter),
-      displayedFilters: displayedFilters === void 0 ? store.getSnapshot().displayedFilters : { ...displayedFilters },
-      page: 1
-    });
-  };
-  const setParams = (patch) => {
-    if (destroyed) return;
-    const next = listParamsFromPatch(patch);
-    if (Object.keys(next).length === 0) return;
-    if (patch.filter !== void 0) clearDebounce();
-    applyParams(next);
-  };
-  let debounceTimer;
-  let pendingFilters;
-  const clearDebounce = () => {
-    if (debounceTimer !== void 0) {
-      clearTimeout(debounceTimer);
-      debounceTimer = void 0;
-    }
-    pendingFilters = void 0;
-  };
-  store.onDestroy(clearDebounce);
-  const setFilters = (filter, displayedFilters, debounced = false) => {
-    if (destroyed) return;
-    clearDebounce();
-    if (!debounced) {
-      applyFilters(filter, displayedFilters);
-      return;
-    }
-    pendingFilters = { filter, displayedFilters };
-    debounceTimer = setTimeout(() => {
-      debounceTimer = void 0;
-      pendingFilters = void 0;
-      if (destroyed) return;
-      applyFilters(filter, displayedFilters);
-    }, options.debounceMs ?? DEFAULT_DEBOUNCE_MS);
-  };
-  const showFilter = (name, defaultValue) => {
-    if (destroyed) return;
-    const s = store.getSnapshot();
-    applyParams({
-      // Keep the same filter reference when no default value is supplied.
-      filter: defaultValue === void 0 ? s.filter : removeEmpty({ ...s.filter, [name]: defaultValue }),
-      displayedFilters: { ...s.displayedFilters, [name]: true }
-    });
-  };
-  const hideFilter = (name) => {
-    if (destroyed) return;
-    const s = store.getSnapshot();
-    const pending = pendingFilters;
-    clearDebounce();
-    const filter = removeFilterPath(
-      pending ? removeEmpty(pending.filter) : s.filter,
-      name
-    );
-    const { [name]: _shown, ...displayedFilters } = pending?.displayedFilters ?? s.displayedFilters;
-    applyParams({
-      filter,
-      displayedFilters,
-      ...pending ? { page: 1 } : {}
-    });
-  };
-  const writeSelection = (ids) => {
-    if (selectionKey && kv) {
-      kv.setItem(selectionKey, ids);
-      if (!observer) store.setState({ selectedIds: ids });
-    } else {
-      store.setState({ selectedIds: ids });
-    }
-  };
-  const select = (ids) => {
-    if (destroyed) return;
-    writeSelection([...ids]);
-  };
-  const toggleItem = (id) => {
-    if (destroyed) return;
-    const current = store.getSnapshot().selectedIds;
-    writeSelection(
-      current.includes(id) ? current.filter((existing) => existing !== id) : [...current, id]
-    );
-  };
-  const unselectAll = () => {
-    if (destroyed) return;
-    writeSelection([]);
-  };
-  const selectAll = (opts) => runSelectAll(
-    ctx.notifications,
-    async (limit) => {
-      const s = store.getSnapshot();
-      const result = await ctx.queryClient.fetchQuery({
-        ...getListOptions(ctx, resource, {
-          pagination: { page: 1, perPage: limit },
-          sort: s.sort.length === 1 ? s.sort[0] : s.sort,
-          filter: { ...s.filter, ...options.filter ?? {} }
-        }),
-        retry: false
-      });
-      return result.data;
-    },
-    writeSelection,
-    () => destroyed,
-    opts?.limit
-  );
-  const refetch = () => {
-    if (destroyed) return;
-    void observer?.refetch();
-  };
-  const maybeResetPage = () => {
-    const target = resetPageTarget(store.getSnapshot());
-    if (target !== void 0) setPage(target);
-  };
-  const errors = createErrorAnnouncer(ctx.notifications);
-  const onResult = (result) => {
-    const list = result.data;
-    const { page, perPage } = store.getSnapshot();
-    store.setState({
-      data: list?.data,
-      total: list?.total,
-      pageInfo: list?.pageInfo,
-      isPending: result.isPending,
-      isFetching: result.isFetching,
-      error: result.error ?? null,
-      ...pageFlags(page, perPage, list?.total, list?.pageInfo)
-    });
-    if (result.error) errors.announce(result.error);
-    else errors.rearm();
-    maybeResetPage();
-  };
-  function acquire() {
-    const attached = new QueryObserver(
-      ctx.queryClient,
-      buildOptions()
-    );
-    observer = attached;
-    const unsubscribeObserver = attached.subscribe(onResult);
-    onResult(attached.getCurrentResult());
-    let unsubscribeSelection;
-    if (selectionKey && kv) {
-      const syncKey = selectionKey;
-      const syncSelection = () => {
-        store.setState({
-          selectedIds: kv.getItem(syncKey) ?? []
-        });
-      };
-      unsubscribeSelection = kv.subscribe(syncKey, syncSelection);
-      syncSelection();
-    }
-    return () => {
-      unsubscribeObserver();
-      unsubscribeSelection?.();
-      observer = null;
-      clearDebounce();
-    };
-  }
-  return {
-    ...store,
-    defaultPerPage: defaults.perPage,
-    setPage,
-    setPerPage,
-    setSort,
-    setFilters,
-    setParams,
-    showFilter,
-    hideFilter,
-    select,
-    toggleItem,
-    unselectAll,
-    selectAll,
-    refetch
-  };
+	const storeKey = options.storeKey === false ? null : options.storeKey ?? resource;
+	const paramsKey = storeKey ? `${storeKey}.listParams` : null;
+	const selectionKey = storeKey ? `${storeKey}.selectedIds` : null;
+	const kv = ctx.store;
+	const defaults = {
+		page: 1,
+		perPage: options.perPage ?? 10,
+		sort: normalizeSort(options.sort, DEFAULT_SORT),
+		filter: { ...options.filterDefaultValues ?? {} },
+		displayedFilters: {}
+	};
+	const persisted = paramsKey && kv ? kv.getItem(paramsKey) : void 0;
+	const initialParams = persisted ? {
+		page: persisted.page ?? defaults.page,
+		perPage: persisted.perPage ?? defaults.perPage,
+		sort: normalizeSort(persisted.sort, defaults.sort),
+		filter: { ...persisted.filter ?? defaults.filter },
+		displayedFilters: { ...persisted.displayedFilters ?? {} }
+	} : defaults;
+	const readSelection = () => (selectionKey && kv ? kv.getItem(selectionKey) : void 0) ?? [];
+	const store = createMicroStore({
+		...initialParams,
+		selectedIds: readSelection(),
+		data: void 0,
+		total: void 0,
+		pageInfo: void 0,
+		isPending: true,
+		isFetching: false,
+		error: null,
+		hasNextPage: void 0,
+		hasPreviousPage: void 0
+	}, { onSubscribed: acquire });
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+	});
+	/** Non-null exactly while attached — doubles as the attached flag. */
+	let observer = null;
+	const buildOptions = () => {
+		const s = store.getSnapshot();
+		return {
+			...getListOptions(ctx, resource, {
+				pagination: {
+					page: s.page,
+					perPage: s.perPage
+				},
+				sort: s.sort.length === 1 ? s.sort[0] : s.sort,
+				filter: {
+					...s.filter,
+					...options.filter ?? {}
+				}
+			}),
+			placeholderData: (prev) => prev,
+			retry: false,
+			enabled: options.enabled ?? true
+		};
+	};
+	const persistParams = () => {
+		if (!paramsKey || !kv) return;
+		const s = store.getSnapshot();
+		const params = {
+			page: s.page,
+			perPage: s.perPage,
+			sort: s.sort,
+			filter: s.filter,
+			displayedFilters: s.displayedFilters
+		};
+		kv.setItem(paramsKey, params);
+	};
+	/**
+	* The ONLY path that reconfigures the observer — param-mutating actions.
+	* Detached, the observer does not exist: state still updates and persists,
+	* and the next attach rebuilds options from CURRENT state.
+	*/
+	const applyParams = (patch) => {
+		store.setState(patch);
+		persistParams();
+		observer?.setOptions(buildOptions());
+	};
+	const setPage = (page) => {
+		if (destroyed) return;
+		applyParams({ page });
+	};
+	const setPerPage = (perPage) => {
+		if (destroyed) return;
+		applyParams({
+			perPage,
+			page: 1
+		});
+	};
+	const setSort = (input) => {
+		if (destroyed) return;
+		const current = store.getSnapshot().sort;
+		const single = current.length === 1 ? current[0] : void 0;
+		let next;
+		if (Array.isArray(input)) next = input.map((entry) => ({ ...entry }));
+		else if (single && single.field === input.field) next = [{
+			field: input.field,
+			order: single.order === "ASC" ? "DESC" : "ASC"
+		}];
+		else next = [{
+			field: input.field,
+			order: input.order ?? "ASC"
+		}];
+		applyParams({
+			sort: next,
+			page: 1
+		});
+	};
+	const applyFilters = (filter, displayedFilters) => {
+		applyParams({
+			filter: removeEmpty(filter),
+			displayedFilters: displayedFilters === void 0 ? store.getSnapshot().displayedFilters : { ...displayedFilters },
+			page: 1
+		});
+	};
+	const setParams = (patch) => {
+		if (destroyed) return;
+		const next = listParamsFromPatch(patch);
+		if (Object.keys(next).length === 0) return;
+		if (patch.filter !== void 0) clearDebounce();
+		applyParams(next);
+	};
+	let debounceTimer;
+	let pendingFilters;
+	const clearDebounce = () => {
+		if (debounceTimer !== void 0) {
+			clearTimeout(debounceTimer);
+			debounceTimer = void 0;
+		}
+		pendingFilters = void 0;
+	};
+	store.onDestroy(clearDebounce);
+	const setFilters = (filter, displayedFilters, debounced = false) => {
+		if (destroyed) return;
+		clearDebounce();
+		if (!debounced) {
+			applyFilters(filter, displayedFilters);
+			return;
+		}
+		pendingFilters = {
+			filter,
+			displayedFilters
+		};
+		debounceTimer = setTimeout(() => {
+			debounceTimer = void 0;
+			pendingFilters = void 0;
+			if (destroyed) return;
+			applyFilters(filter, displayedFilters);
+		}, options.debounceMs ?? 500);
+	};
+	const showFilter = (name, defaultValue) => {
+		if (destroyed) return;
+		const s = store.getSnapshot();
+		applyParams({
+			filter: defaultValue === void 0 ? s.filter : removeEmpty({
+				...s.filter,
+				[name]: defaultValue
+			}),
+			displayedFilters: {
+				...s.displayedFilters,
+				[name]: true
+			}
+		});
+	};
+	const hideFilter = (name) => {
+		if (destroyed) return;
+		const s = store.getSnapshot();
+		const pending = pendingFilters;
+		clearDebounce();
+		const filter = removeFilterPath(pending ? removeEmpty(pending.filter) : s.filter, name);
+		const { [name]: _shown, ...displayedFilters } = pending?.displayedFilters ?? s.displayedFilters;
+		applyParams({
+			filter,
+			displayedFilters,
+			...pending ? { page: 1 } : {}
+		});
+	};
+	const writeSelection = (ids) => {
+		if (selectionKey && kv) {
+			kv.setItem(selectionKey, ids);
+			if (!observer) store.setState({ selectedIds: ids });
+		} else store.setState({ selectedIds: ids });
+	};
+	const select = (ids) => {
+		if (destroyed) return;
+		writeSelection([...ids]);
+	};
+	const toggleItem = (id) => {
+		if (destroyed) return;
+		const current = store.getSnapshot().selectedIds;
+		writeSelection(current.includes(id) ? current.filter((existing) => existing !== id) : [...current, id]);
+	};
+	const unselectAll = () => {
+		if (destroyed) return;
+		writeSelection([]);
+	};
+	const selectAll = (opts) => runSelectAll(ctx.notifications, async (limit) => {
+		const s = store.getSnapshot();
+		return (await ctx.queryClient.fetchQuery({
+			...getListOptions(ctx, resource, {
+				pagination: {
+					page: 1,
+					perPage: limit
+				},
+				sort: s.sort.length === 1 ? s.sort[0] : s.sort,
+				filter: {
+					...s.filter,
+					...options.filter ?? {}
+				}
+			}),
+			retry: false
+		})).data;
+	}, writeSelection, () => destroyed, opts?.limit);
+	const refetch = () => {
+		if (destroyed) return;
+		observer?.refetch();
+	};
+	const maybeResetPage = () => {
+		const target = resetPageTarget(store.getSnapshot());
+		if (target !== void 0) setPage(target);
+	};
+	const errors = createErrorAnnouncer(ctx.notifications);
+	const onResult = (result) => {
+		const list = result.data;
+		const { page, perPage } = store.getSnapshot();
+		store.setState({
+			data: list?.data,
+			total: list?.total,
+			pageInfo: list?.pageInfo,
+			isPending: result.isPending,
+			isFetching: result.isFetching,
+			error: result.error ?? null,
+			...pageFlags(page, perPage, list?.total, list?.pageInfo)
+		});
+		if (result.error) errors.announce(result.error);
+		else errors.rearm();
+		maybeResetPage();
+	};
+	/**
+	* Attach: runs on the micro-store's FIRST subscriber (hoisted into the
+	* `createMicroStore` options above). Creates and subscribes the observer
+	* with options built from CURRENT state, arms the KV selection sync, and
+	* returns the teardown that the micro-store runs on last-unsubscribe AND
+	* on destroy-while-attached.
+	*/
+	function acquire() {
+		const attached = new QueryObserver(ctx.queryClient, buildOptions());
+		observer = attached;
+		const unsubscribeObserver = attached.subscribe(onResult);
+		onResult(attached.getCurrentResult());
+		let unsubscribeSelection;
+		if (selectionKey && kv) {
+			const syncKey = selectionKey;
+			const syncSelection = () => {
+				store.setState({ selectedIds: kv.getItem(syncKey) ?? [] });
+			};
+			unsubscribeSelection = kv.subscribe(syncKey, syncSelection);
+			syncSelection();
+		}
+		return () => {
+			unsubscribeObserver();
+			unsubscribeSelection?.();
+			observer = null;
+			clearDebounce();
+		};
+	}
+	return {
+		...store,
+		defaultPerPage: defaults.perPage,
+		setPage,
+		setPerPage,
+		setSort,
+		setFilters,
+		setParams,
+		showFilter,
+		hideFilter,
+		select,
+		toggleItem,
+		unselectAll,
+		selectAll,
+		refetch
+	};
 }
-export {
-  DEFAULT_DEBOUNCE_MS,
-  DEFAULT_SELECT_ALL_LIMIT,
-  createErrorAnnouncer,
-  createListController,
-  errorMessageKey,
-  listControllerActions,
-  listParamsFromPatch,
-  notifyFetchError,
-  notifySelectAllLimit,
-  pageFlags,
-  removeFilterPath,
-  resetPageTarget,
-  runSelectAll
-};
+export { DEFAULT_DEBOUNCE_MS, DEFAULT_PER_PAGE, createErrorAnnouncer, createListController, errorMessageKey, listControllerActions, listParamsFromPatch, notifyFetchError, notifySelectAllLimit, pageFlags, removeFilterPath, resetPageTarget, runSelectAll };