@atscript/ui-table 0.1.111 → 0.1.113

package/dist/index.cjs

@@ -1172,7 +1172,8 @@ function makeParserSafeAnd(children) {
 function buildTableQuery(opts) {
 	const userFilter = filtersToUniqueryFilter(opts.filters);
 	const filter = mergeFilters(opts.forceFilters, userFilter);
-	const sorters = opts.forceSorters?.length ? mergeSorters(opts.forceSorters, opts.sorters) : opts.sorters;
+	const userSorters = opts.ignoreSorters ? [] : opts.sorters;
+	const sorters = opts.forceSorters?.length ? mergeSorters(opts.forceSorters, userSorters) : userSorters;
 	const $sort = {};
 	for (const s of sorters) $sort[s.field] = s.direction === "asc" ? 1 : -1;
 	const controls = {};
@@ -1222,6 +1223,7 @@ function stateToUrlQueryString(state, defaults) {
 		filters,
 		search: searchOff ? void 0 : state.searchTerm || void 0
 	});
+	if (!searchOff && state.searchTerm && state.ignoreSorters !== void 0 && state.ignoreSorters !== (defaults.defaultIgnoreSorters ?? false)) query.controls.$relevance = state.ignoreSorters ? 1 : 0;
 	if (!paginationOff) {
 		const itemsPerPage = state.itemsPerPage ?? defaults.defaultItemsPerPage;
 		const page = state.page ?? 1;
@@ -1294,6 +1296,11 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
+	if (!searchOff) {
+		const $relevance = parsed.controls?.$relevance;
+		if ($relevance === "1" || $relevance === 1) out.ignoreSorters = true;
+		else if ($relevance === "0" || $relevance === 0) out.ignoreSorters = false;
+	}
 	if (!paginationOff) {
 		const $skip = parsed.controls?.$skip;
 		if (typeof $skip === "number" && $skip > 0 && Number.isFinite($skip)) out.skip = $skip;

package/dist/index.d.cts

@@ -585,6 +585,12 @@ interface BuildTableQueryOptions {
   sorters: SortControl[];
   /** Always-applied sorters (prepended before user sorters). */
   forceSorters?: SortControl[];
+  /**
+   * When true, user `sorters` are omitted from `$sort`; `forceSorters` still
+   * apply. Used to preserve search relevance ranking — the caller computes
+   * the search-active condition; this function just honours the flag.
+   */
+  ignoreSorters?: boolean;
   /** User-configured field filters. */
   filters: FieldFilters;
   /** Always-applied Uniquery filter (AND'd with user filters). */
@@ -648,6 +654,14 @@ interface UrlQueryStateLike {
   itemsPerPage?: number;
   /** Full-text search term. Omitted from the URL when empty. */
   searchTerm?: string;
+  /**
+   * Runtime "preserve relevance ranking" flag — while true and a search is
+   * active, user sorters are suppressed at query time. Serialized as
+   * `$relevance=1|0` only when a search term is present AND the value differs
+   * from `defaultIgnoreSorters`, so a link shared mid-search reproduces what
+   * the sharer saw.
+   */
+  ignoreSorters?: boolean;
 }
 /** Snapshot recovered from a URL string — partial on purpose so callers can layer it onto state. */
 interface UrlQueryStateSnapshot {
@@ -661,6 +675,11 @@ interface UrlQueryStateSnapshot {
    */
   skip?: number;
   searchTerm: string;
+  /**
+   * Runtime relevance flag decoded from `$relevance` (omitted when the URL
+   * carries no explicit value — the recipient keeps their configured default).
+   */
+  ignoreSorters?: boolean;
 }
 /**
  * Per-aspect opt-in/out for the URL bridge. Honoured symmetrically by both
@@ -691,6 +710,11 @@ interface UrlQueryDefaults {
   defaultItemsPerPage: number;
   /** Per-aspect sync gates. Omitted = full sync (existing behaviour). */
   sync?: UrlQuerySync;
+  /**
+   * Consumer's configured `ignoreSortersWhenSearched` default. `$relevance`
+   * is emitted only when the runtime flag differs from this. Default `false`.
+   */
+  defaultIgnoreSorters?: boolean;
 }
 /**
  * Resolve a `boolean | string[]` aspect gate into a tri-state:

package/dist/index.d.mts

@@ -585,6 +585,12 @@ interface BuildTableQueryOptions {
   sorters: SortControl[];
   /** Always-applied sorters (prepended before user sorters). */
   forceSorters?: SortControl[];
+  /**
+   * When true, user `sorters` are omitted from `$sort`; `forceSorters` still
+   * apply. Used to preserve search relevance ranking — the caller computes
+   * the search-active condition; this function just honours the flag.
+   */
+  ignoreSorters?: boolean;
   /** User-configured field filters. */
   filters: FieldFilters;
   /** Always-applied Uniquery filter (AND'd with user filters). */
@@ -648,6 +654,14 @@ interface UrlQueryStateLike {
   itemsPerPage?: number;
   /** Full-text search term. Omitted from the URL when empty. */
   searchTerm?: string;
+  /**
+   * Runtime "preserve relevance ranking" flag — while true and a search is
+   * active, user sorters are suppressed at query time. Serialized as
+   * `$relevance=1|0` only when a search term is present AND the value differs
+   * from `defaultIgnoreSorters`, so a link shared mid-search reproduces what
+   * the sharer saw.
+   */
+  ignoreSorters?: boolean;
 }
 /** Snapshot recovered from a URL string — partial on purpose so callers can layer it onto state. */
 interface UrlQueryStateSnapshot {
@@ -661,6 +675,11 @@ interface UrlQueryStateSnapshot {
    */
   skip?: number;
   searchTerm: string;
+  /**
+   * Runtime relevance flag decoded from `$relevance` (omitted when the URL
+   * carries no explicit value — the recipient keeps their configured default).
+   */
+  ignoreSorters?: boolean;
 }
 /**
  * Per-aspect opt-in/out for the URL bridge. Honoured symmetrically by both
@@ -691,6 +710,11 @@ interface UrlQueryDefaults {
   defaultItemsPerPage: number;
   /** Per-aspect sync gates. Omitted = full sync (existing behaviour). */
   sync?: UrlQuerySync;
+  /**
+   * Consumer's configured `ignoreSortersWhenSearched` default. `$relevance`
+   * is emitted only when the runtime flag differs from this. Default `false`.
+   */
+  defaultIgnoreSorters?: boolean;
 }
 /**
  * Resolve a `boolean | string[]` aspect gate into a tri-state:

package/dist/index.mjs

@@ -1171,7 +1171,8 @@ function makeParserSafeAnd(children) {
 function buildTableQuery(opts) {
 	const userFilter = filtersToUniqueryFilter(opts.filters);
 	const filter = mergeFilters(opts.forceFilters, userFilter);
-	const sorters = opts.forceSorters?.length ? mergeSorters(opts.forceSorters, opts.sorters) : opts.sorters;
+	const userSorters = opts.ignoreSorters ? [] : opts.sorters;
+	const sorters = opts.forceSorters?.length ? mergeSorters(opts.forceSorters, userSorters) : userSorters;
 	const $sort = {};
 	for (const s of sorters) $sort[s.field] = s.direction === "asc" ? 1 : -1;
 	const controls = {};
@@ -1221,6 +1222,7 @@ function stateToUrlQueryString(state, defaults) {
 		filters,
 		search: searchOff ? void 0 : state.searchTerm || void 0
 	});
+	if (!searchOff && state.searchTerm && state.ignoreSorters !== void 0 && state.ignoreSorters !== (defaults.defaultIgnoreSorters ?? false)) query.controls.$relevance = state.ignoreSorters ? 1 : 0;
 	if (!paginationOff) {
 		const itemsPerPage = state.itemsPerPage ?? defaults.defaultItemsPerPage;
 		const page = state.page ?? 1;
@@ -1293,6 +1295,11 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
+	if (!searchOff) {
+		const $relevance = parsed.controls?.$relevance;
+		if ($relevance === "1" || $relevance === 1) out.ignoreSorters = true;
+		else if ($relevance === "0" || $relevance === 0) out.ignoreSorters = false;
+	}
 	if (!paginationOff) {
 		const $skip = parsed.controls?.$skip;
 		if (typeof $skip === "number" && $skip > 0 && Number.isFinite($skip)) out.skip = $skip;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/ui-table",
-  "version": "0.1.111",
+  "version": "0.1.113",
   "description": "Framework-agnostic filter model, filter-to-Uniquery conversion, and preset serialization for atscript tables",
   "keywords": [
     "atscript",
@@ -42,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@atscript/ui": "0.1.111"
+    "@atscript/ui": "0.1.113"
   },
   "devDependencies": {
     "@atscript/db-client": "^0.1.111",