@arraypress/search 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to `@arraypress/search` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — 2026-11-15
+
+### Added
+
+- **A filter panel's logic:** `facetTable` (each record's values per facet, worked out once), `narrow` (any picked value within a facet, every facet with a pick), `facetCounts` (each value's live count against the other facets' picks, so it is what ticking it would show), `toggle`, `pickCount`, `picks`, `sameSelection`, and `readSelection` / `writeSelection` for the selection in a page's address. From the Logomarks filter panel. `facets()` is unchanged: it counts values without a selection.
+
 ## [0.1.0] — 2026-11-05
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @arraypress/search
 
-Ranked in-memory search with synonyms and facets. Field weights, synonym phrases (up to three words read as one), plural folding, word-start matching for what is typed and whole-word matching for synonyms, exact filters, stable tie-breaks, and a compact prebuilt index you build once and load in the browser. Plus rule-based tagging: weighted word rules with caps, hand picks and a review.
+Ranked in-memory search with synonyms and facets. Field weights, synonym phrases (up to three words read as one), plural folding, word-start matching for what is typed and whole-word matching for synonyms, exact filters, a filter panel's facet logic (live counts, the selection in the address), stable tie-breaks, and a compact prebuilt index you build once and load in the browser. Plus rule-based tagging: weighted word rules with caps, hand picks and a review.
 
 No dependencies. Runs in the browser and in Node. About 2.2 KB minified and gzipped; the rules are 1.1 KB more.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/search",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Ranked in-memory search with synonyms and facets: field weights, synonym phrases, plural folding, word-start and whole-word matching, exact filters, stable tie-breaks and a compact prebuilt JSON index. Plus rule-based tagging (weighted word rules, caps, picks and a review). No dependencies; browser and Node.",
   "type": "module",
   "main": "src/index.js",

package/src/filter/address.d.ts

@@ -0,0 +1,6 @@
+import type { Selection } from './selection.js';
+
+/** Writes the selection into a query (one comma-joined parameter per picked facet), keeping other parameters. */
+export function writeSelection<F extends string>(params: URLSearchParams, ids: readonly F[], sel: Selection<F>, keys?: Partial<Record<F, string>>): URLSearchParams;
+/** The selection a query asks for; unknown values and repeats dropped. */
+export function readSelection<F extends string>(params: URLSearchParams, ids: readonly F[], known?: Partial<Record<F, ReadonlySet<string>>>, keys?: Partial<Record<F, string>>): Selection<F>;

package/src/filter/address.js

@@ -0,0 +1,48 @@
+/**
+ * @module @arraypress/search/filter/address
+ *
+ * A selection in a page's address: one query parameter per facet with a pick,
+ * its values joined by commas (`?style=iso,track&mood=calm`), and back.
+ */
+
+/**
+ * Writes the selection into a query: one parameter per facet with a pick (its key from `keys`, else its id), the
+ * values joined by commas, in facet order. Other parameters are kept; a facet without a pick is removed.
+ *
+ * @param {URLSearchParams} params The query, changed in place.
+ * @param {readonly string[]} ids The facets, in order.
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @param {Record<string, string>} [keys] A parameter name per facet, where it isn't the facet's id.
+ * @returns {URLSearchParams} The same query.
+ */
+export function writeSelection(params, ids, sel, keys = {}) {
+	for (const f of ids) {
+		const key = keys[f] ?? f;
+		const vals = sel[f];
+		if (vals?.length) params.set(key, vals.join(','));
+		else params.delete(key);
+	}
+	return params;
+}
+
+/**
+ * The selection a query asks for. Values a facet doesn't take (when `known` is given) are dropped, and repeats.
+ *
+ * @param {URLSearchParams} params The query.
+ * @param {readonly string[]} ids The facets.
+ * @param {Record<string, ReadonlySet<string>>} [known] The values each facet takes (a table's `known`).
+ * @param {Record<string, string>} [keys] A parameter name per facet, where it isn't the facet's id.
+ * @returns {import('./selection.js').Selection} The selection.
+ */
+export function readSelection(params, ids, known, keys = {}) {
+	/** @type {Record<string, string[]>} */
+	const sel = {};
+	for (const f of ids) {
+		const raw = params.get(keys[f] ?? f);
+		if (!raw) continue;
+		const ok = known?.[f];
+		const vals = [...new Set(raw.split(',').map((v) => v.trim()))].filter((v) => v && (!ok || ok.has(v)));
+		if (vals.length) sel[f] = vals;
+	}
+	return sel;
+}

package/src/filter/selection.d.ts

@@ -0,0 +1,28 @@
+/** The values picked in each facet; an absent or empty list means any. */
+export type Selection<F extends string = string> = Partial<Record<F, readonly string[]>>;
+
+/** Each record's values per facet: `values[k][i]` are record i's values in facet `ids[k]`. */
+export interface FacetTable<F extends string = string> {
+	ids: readonly F[];
+	values: (readonly string[])[][];
+	/** Every value each facet takes, for checking a selection read from an address. */
+	known: Record<F, ReadonlySet<string>>;
+}
+
+/** Live counts: per facet, each value's count among the records that pass every other facet. */
+export type FacetCounts<F extends string = string> = Record<F, Map<string, number>>;
+
+/** Each record's values in each facet, as a table. */
+export function facetTable<T, F extends string>(records: readonly T[], valuesOf: Record<F, (record: T) => readonly string[]>): FacetTable<F>;
+/** The records (indices, in the order given) that pass every facet with a pick. */
+export function narrow<F extends string>(table: FacetTable<F>, candidates: Iterable<number>, sel: Selection<F>): number[];
+/** Each facet's value counts among the candidates, each counted against the other facets' picks. */
+export function facetCounts<F extends string>(table: FacetTable<F>, candidates: Iterable<number>, sel: Selection<F>): FacetCounts<F>;
+/** The selection with one value ticked, unticked or (with `on`) forced. */
+export function toggle<F extends string>(sel: Selection<F>, facet: F, value: string, on?: boolean): Selection<F>;
+/** How many values are picked across every facet. */
+export function pickCount(sel: Selection): number;
+/** Every pick as [facet, value], in facet order then pick order. */
+export function picks<F extends string>(ids: readonly F[], sel: Selection<F>): (readonly [F, string])[];
+/** Whether two selections pick the same values, in any order. */
+export function sameSelection(a: Selection, b: Selection): boolean;

package/src/filter/selection.js

@@ -0,0 +1,135 @@
+/**
+ * @module @arraypress/search/filter/selection
+ *
+ * A filter panel's logic over facets: each record's values per facet worked
+ * out once (a table), the records that pass a selection (any picked value
+ * within a facet, every facet with a pick), each value's live count (counted
+ * against the other facets' picks, so it is what ticking it would show), and
+ * small helpers for changing and comparing selections. Generic over facet ids.
+ */
+
+/**
+ * Each record's values in each facet, as a table.
+ *
+ * @template T, F
+ * @param {readonly T[]} records The records.
+ * @param {Record<F & string, (record: T) => readonly string[]>} valuesOf Per facet, a record's values in it (none for none).
+ * @returns {import('./selection.js').FacetTable<F & string>} The table.
+ */
+export function facetTable(records, valuesOf) {
+	const ids = /** @type {(F & string)[]} */ (Object.keys(valuesOf));
+	const values = ids.map((f) => records.map((r) => valuesOf[f](r)));
+	const known = /** @type {Record<F & string, ReadonlySet<string>>} */ (Object.fromEntries(ids.map((f, k) => [f, new Set(values[k].flat())])));
+	return { ids, values, known };
+}
+
+/**
+ * The facets with a pick, as [table column, picked values].
+ *
+ * @param {import('./selection.js').FacetTable} table The table.
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {(readonly [number, Set<string>])[]} The picks.
+ */
+const picked = (table, sel) => table.ids.flatMap((f, k) => (sel[f]?.length ? [/** @type {const} */ ([k, new Set(sel[f])])] : []));
+
+/**
+ * Whether a record has any of the picked values.
+ *
+ * @param {readonly string[]} have The record's values.
+ * @param {ReadonlySet<string>} want The picked values.
+ * @returns {boolean} True when one matches.
+ */
+const hasAny = (have, want) => have.some((v) => want.has(v));
+
+/**
+ * The records (indices, in the order given) that pass every facet with a pick: any of its picked values.
+ *
+ * @param {import('./selection.js').FacetTable} table The table.
+ * @param {Iterable<number>} candidates The records to consider (a search's hits, or all).
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {number[]} The indices that pass.
+ */
+export function narrow(table, candidates, sel) {
+	const picks = picked(table, sel);
+	/** @type {number[]} */
+	const out = [];
+	for (const i of candidates) if (picks.every(([k, want]) => hasAny(table.values[k][i], want))) out.push(i);
+	return out;
+}
+
+/**
+ * Each facet's value counts among the candidates: a value's count is how many candidates have it and pass every
+ * OTHER facet, so it is how many records ticking it would add (or, in a facet with no pick, show).
+ *
+ * @param {import('./selection.js').FacetTable} table The table.
+ * @param {Iterable<number>} candidates The records to count (a search's hits, or all).
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {Record<string, Map<string, number>>} Per facet, each value's count.
+ */
+export function facetCounts(table, candidates, sel) {
+	const picks = picked(table, sel);
+	const counts = table.ids.map(() => /** @type {Map<string, number>} */ (new Map()));
+	/** Counts record i's values in facet column k. */
+	const add = (/** @type {number} */ k, /** @type {number} */ i) => {
+		for (const v of table.values[k][i]) counts[k].set(v, (counts[k].get(v) ?? 0) + 1);
+	};
+	for (const i of candidates) {
+		// the facets it fails: none, it counts everywhere; one, it counts only there (ticking more of that facet adds it)
+		let failed = -1;
+		let fails = 0;
+		for (const [k, want] of picks)
+			if (!hasAny(table.values[k][i], want)) {
+				failed = k;
+				if (++fails > 1) break;
+			}
+		if (fails === 0) table.ids.forEach((_, k) => add(k, i));
+		else if (fails === 1) add(failed, i);
+	}
+	return Object.fromEntries(table.ids.map((f, k) => [f, counts[k]]));
+}
+
+/**
+ * The selection with one value ticked or unticked.
+ *
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @param {string} facet The facet.
+ * @param {string} value The value.
+ * @param {boolean} [on] Force it on or off; toggles when absent.
+ * @returns {import('./selection.js').Selection} A new selection.
+ */
+export function toggle(sel, facet, value, on) {
+	const have = sel[facet] ?? [];
+	const now = on ?? !have.includes(value);
+	const next = now ? (have.includes(value) ? have : [...have, value]) : have.filter((v) => v !== value);
+	return { ...sel, [facet]: next };
+}
+
+/**
+ * How many values are picked across every facet.
+ *
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {number} The count.
+ */
+export const pickCount = (sel) => Object.values(sel).reduce((n, v) => n + (v?.length ?? 0), 0);
+
+/**
+ * Every pick as [facet, value], in facet order then pick order (a row of chips).
+ *
+ * @param {readonly string[]} ids The facets, in order.
+ * @param {import('./selection.js').Selection} sel The selection.
+ * @returns {(readonly [string, string])[]} The picks.
+ */
+export const picks = (ids, sel) => ids.flatMap((f) => (sel[f] ?? []).map((v) => /** @type {const} */ ([f, v])));
+
+/**
+ * Whether two selections pick the same values, in any order (an empty list is no pick).
+ *
+ * @param {import('./selection.js').Selection} a One selection.
+ * @param {import('./selection.js').Selection} b The other.
+ * @returns {boolean} True when they match.
+ */
+export function sameSelection(a, b) {
+	const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const k of keys) if ([...(a[k] ?? [])].sort().join(',') !== [...(b[k] ?? [])].sort().join(',')) return false;
+	return true;
+}

package/src/index.d.ts

@@ -5,6 +5,9 @@ export { pack, unpack, PACK_VERSION } from './pack/index.js';
 export { facets } from './filter/facets.js';
 export type { Filter, FilterValue } from './filter/filter.js';
 export { filterOf } from './filter/filter.js';
+export { facetTable, narrow, facetCounts, toggle, pickCount, picks, sameSelection } from './filter/selection.js';
+export type { Selection, FacetTable, FacetCounts } from './filter/selection.js';
+export { readSelection, writeSelection } from './filter/address.js';
 export type { Tie } from './filter/tie.js';
 export type { Term, TermOptions } from './query/terms.js';
 export { termsOf, synonymMap } from './query/terms.js';

package/src/index.js

@@ -11,5 +11,7 @@ export { createSearch } from './search.js';
 export { pack, unpack, PACK_VERSION } from './pack/index.js';
 export { facets } from './filter/facets.js';
 export { filterOf } from './filter/filter.js';
+export { facetTable, narrow, facetCounts, toggle, pickCount, picks, sameSelection } from './filter/selection.js';
+export { readSelection, writeSelection } from './filter/address.js';
 export { termsOf, synonymMap } from './query/terms.js';
 export { singular } from './query/plural.js';