@stapel/search-react 0.27.0 → 0.28.0

package/src/default/OtherCategoriesLine.tsx

@@ -30,9 +30,18 @@
  * show a different, larger number, so the caption would be a lie one click
  * later. Each entry therefore writes the `category` parameter of the search
  * already on screen, keeping the query: press "Cars 12" and twelve results
- * follow. That is a state change, so each entry is a real `<button>` and not
- * an anchor.
+ * follow.
  *
+ * Without {@link OtherCategoriesLineProps.categoryHref} that state change is
+ * ALL an entry does, so it is a plain `<button>` with no `href` — no address
+ * to hover, no "open in a new tab", nothing a crawler can follow. `categoryHref`
+ * turns the entry into a real `<a href>` without giving up the in-app
+ * narrowing: a plain click still rewrites the query in place (a full
+ * navigation would answer a different question than the one the count was
+ * counted for), while a modified click — the browser's own "open in a new
+ * tab/window" — is left alone and follows the address like any other link.
+ *
+
  * ## Two rows on a phone, at most
  *
  * The cap is halved on the sheet surface ({@link OTHER_CATEGORIES_PHONE_LIMIT}),
@@ -70,6 +79,10 @@ export const OTHER_CATEGORIES_SLOT_MIN_HEIGHT = 24;
  * drops the row rather than printing a number at a person. */
 export type OtherCategoryNamer = (category: string) => string | undefined;
 
+/** Resolves an id path to a real, navigable address. Returning `undefined`
+ * leaves the row's in-app narrowing as the only way to press it. */
+export type OtherCategoryHrefResolver = (category: string) => string | undefined;
+
 export interface OtherCategoriesLineProps {
   /** How many entries before the fold (default {@link OTHER_CATEGORIES_LIMIT}). */
   readonly limit?: number;
@@ -86,6 +99,24 @@ export interface OtherCategoriesLineProps {
    * slug — and drops the rest, because "163 · 149" is not a sentence.
    */
   readonly categoryName?: OtherCategoryNamer;
+  /**
+   * A real address for a category id path, when the host has one — a
+   * category page's own URL, most usefully.
+   *
+   * Without it every entry is a `<button>` with no `href`: it narrows the
+   * search on click, and nothing else — no "open in a new tab", no address
+   * to hover, nothing a crawler can follow. With it the entry becomes a real
+   * `<a href>` (a middle-click, a ctrl/cmd-click, "open in new tab" all work
+   * as they do for any link), while a plain click still narrows THIS search
+   * in place rather than leaving it — the whole reason the count beside a
+   * name is trustworthy is that it is a count for the query on screen, and a
+   * full navigation to the host's address would be answering a different
+   * question than the one the click asked.
+   *
+   * A row this returns nothing for keeps the in-app-only behaviour; the row
+   * is dropped only when it has no NAME, exactly as without this prop.
+   */
+  readonly categoryHref?: OtherCategoryHrefResolver;
   /** Skip the read entirely — mirrors `<SearchResultsPane enabled>`. */
   readonly enabled?: boolean;
 }
@@ -130,6 +161,7 @@ export function otherCategoriesCss(): string {
 interface Entry {
   readonly row: OtherCategoryRow;
   readonly name: string;
+  readonly href?: string;
 }
 
 export function OtherCategoriesLine(
@@ -152,7 +184,9 @@ export function OtherCategoriesLine(
   for (const row of bag.rows) {
     const name =
       props.categoryName?.(row.category) ?? row.name ?? otherCategoryLeaf(row.category);
-    if (name !== undefined) entries.push({ row, name });
+    if (name === undefined) continue;
+    const href = props.categoryHref?.(row.category);
+    entries.push(href !== undefined ? { row, name, href } : { row, name });
   }
 
   const shown = expanded ? entries : entries.slice(0, limit);
@@ -201,12 +235,26 @@ export function OtherCategoriesLine(
             style={ENTRY}
             data-testid="search-other-category"
             data-category={entry.row.category}
+            {...(entry.href !== undefined ? { href: entry.href } : {})}
             data-analytics="none"
             data-analytics-reason="narrowing a search is a read, not a flow step"
             aria-label={t(SEARCH_I18N_KEYS.otherCategoriesNarrow, {
               name: entry.name,
             })}
-            onClick={() => {
+            onClick={(event) => {
+              // A real `href` still narrows THIS search in place on a plain
+              // click — a full navigation would answer a different query
+              // than the one the count beside the name was counted for.
+              // Anything asking for a new tab/window (a modified click) is
+              // left to the browser, which is what makes the address real
+              // rather than decorative.
+              if (
+                entry.href !== undefined &&
+                (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+              ) {
+                return;
+              }
+              event.preventDefault();
               setCategory(entry.row.category);
             }}
           >

package/src/default/SearchPage.tsx

@@ -86,7 +86,10 @@ import { FilterChips } from "./FilterChips.js";
 import { LocationSummaryLine } from "./LocationSummaryLine.js";
 import { PageSizeSelect } from "./PageSizeSelect.js";
 import { SearchBox } from "./SearchBox.js";
-import type { OtherCategoryNamer } from "./OtherCategoriesLine.js";
+import type {
+  OtherCategoryHrefResolver,
+  OtherCategoryNamer,
+} from "./OtherCategoriesLine.js";
 import { SearchResultsPane } from "./SearchResultsPane.js";
 import type { SearchResultsWrapper } from "./SearchResultsPane.js";
 import { SortSelect } from "./SortSelect.js";
@@ -367,6 +370,9 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
   /** What a category id path is CALLED, for the line above. The same question
    * `categoryLabel` answers for the chip, asked once per row. */
   readonly categoryName?: OtherCategoryNamer;
+  /** A real address for a category id path, for the line above — see
+   * {@link OtherCategoriesLineProps.categoryHref}. */
+  readonly categoryHref?: OtherCategoryHrefResolver;
   /** What this surface calls its result list. See
    * {@link SearchResultsPaneProps.heading}. */
   readonly resultsHeading?: ReactNode;
@@ -468,6 +474,7 @@ interface SearchPageBodyProps {
   readonly appliedChips?: boolean | "desktop";
   readonly otherCategories?: boolean;
   readonly categoryName?: OtherCategoryNamer;
+  readonly categoryHref?: OtherCategoryHrefResolver;
   readonly resultsHeading?: ReactNode;
   readonly degradationNotice?: DegradationNoticeVariant;
   readonly filtersLayout?: SearchFiltersLayout;
@@ -659,6 +666,9 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
       {...(props.categoryName !== undefined
         ? { categoryName: props.categoryName }
         : {})}
+      {...(props.categoryHref !== undefined
+        ? { categoryHref: props.categoryHref }
+        : {})}
       {...(props.resultsHeading !== undefined
         ? { heading: props.resultsHeading }
         : {})}
@@ -838,6 +848,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     appliedChips,
     otherCategories,
     categoryName,
+    categoryHref,
     resultsHeading,
     degradationNotice,
     filtersLayout,
@@ -879,6 +890,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(appliedChips !== undefined ? { appliedChips } : {})}
           {...(otherCategories !== undefined ? { otherCategories } : {})}
           {...(categoryName !== undefined ? { categoryName } : {})}
+          {...(categoryHref !== undefined ? { categoryHref } : {})}
           {...(resultsHeading !== undefined ? { resultsHeading } : {})}
           {...(degradationNotice !== undefined ? { degradationNotice } : {})}
           {...(filtersLayout !== undefined ? { filtersLayout } : {})}

package/src/default/SearchResultsPane.tsx

@@ -47,7 +47,10 @@ import { DegradationNotice } from "./DegradationNotice.js";
 import { EmptyExits } from "./EmptyExits.js";
 import type { DegradationNoticeVariant } from "./DegradationNotice.js";
 import { OtherCategoriesLine } from "./OtherCategoriesLine.js";
-import type { OtherCategoryNamer } from "./OtherCategoriesLine.js";
+import type {
+  OtherCategoryHrefResolver,
+  OtherCategoryNamer,
+} from "./OtherCategoriesLine.js";
 import { SearchResultCard } from "./SearchResultCard.js";
 import type { SearchCardRenderer } from "./SearchResultCard.js";
 import type { SearchResultsLayout } from "./ViewSwitch.js";
@@ -277,6 +280,9 @@ export interface SearchResultsPaneProps extends ThemeModeProp {
   /** What a category id path is CALLED, for the line above — see
    * {@link OtherCategoriesLineProps.categoryName}. */
   readonly categoryName?: OtherCategoryNamer;
+  /** A real address for a category id path, for the line above — see
+   * {@link OtherCategoriesLineProps.categoryHref}. */
+  readonly categoryHref?: OtherCategoryHrefResolver;
 }
 
 function Count(props: { bag: SearchResultsBag }): ReactElement | null {
@@ -400,6 +406,9 @@ export function SearchResultsPane(props: SearchResultsPaneProps): ReactElement {
                 {...(props.categoryName !== undefined
                   ? { categoryName: props.categoryName }
                   : {})}
+                {...(props.categoryHref !== undefined
+                  ? { categoryHref: props.categoryHref }
+                  : {})}
               />
             )}
 

package/src/default/index.ts

@@ -58,6 +58,7 @@ export {
 } from "./OtherCategoriesLine.js";
 export type {
   OtherCategoriesLineProps,
+  OtherCategoryHrefResolver,
   OtherCategoryNamer,
 } from "./OtherCategoriesLine.js";
 

package/src/headless/SearchStateProvider.tsx

@@ -50,11 +50,79 @@ export interface SearchParamsAdapter {
    * `replace` is meaningful, not decorative: a FILTER change pushes (so Back
    * removes exactly the last filter — the spec's §4.2 acceptance), while a
    * correction that the person did not perform replaces. Callers below pass
-   * it deliberately; an adapter that ignores it breaks the Back button.
+   * it deliberately, following {@link DEFAULT_HISTORY_MODE} — see that table
+   * for which change gets which. An adapter that ignores `replace` breaks the
+   * Back button.
    */
   setParams(next: URLSearchParams, options?: { readonly replace?: boolean }): void;
 }
 
+/** One kind of change a control can make to the search — the unit
+ * {@link DEFAULT_HISTORY_MODE} assigns a history mode to. */
+export type SearchHistoryKind =
+  | "text"
+  | "sort"
+  | "category"
+  | "language"
+  | "filter"
+  | "range"
+  | "geo"
+  | "limit"
+  | "clear"
+  | "page"
+  | "patch";
+
+/** `"push"` opens a new history entry; `"replace"` overwrites the current one. */
+export type HistoryMode = "push" | "replace";
+
+/**
+ * THE HISTORY POLICY — one place stating which change gets its own Back step.
+ *
+ * `"push"` is what makes Back undo exactly one thing: choosing or removing a
+ * facet value (`filter`), narrowing or widening a range (`range`), picking a
+ * partition or another category (`category` — `<PartitionChips>` and
+ * `<OtherCategoriesLine>` both go through `setCategory`), applying a place
+ * (`geo`) or a sort (`sort`) are all decisions a person can want to take back
+ * one press at a time, so each one opens its own entry — this is the
+ * behaviour spec §4.2 tests: "press Back and lose exactly the last filter".
+ *
+ * `"replace"` is for a change too fine-grained, or too incidental, to be a
+ * Back-able step of its own:
+ *
+ *  - `text` — one history entry per keystroke would make Back useless long
+ *    before it reached the filter underneath;
+ *  - `limit` — a page-size preference, not a narrowing;
+ *  - `page` — a keyset cursor move is SCROLLING, not a decision. Back from
+ *    page 3 has to land where the visitor WAS (off the pager, before they
+ *    started paging), not quietly on page 2 with the pager still showing —
+ *    the reference behaves the first way, and a mutator that pushed here used
+ *    to make Back page backwards forever instead of leaving the results.
+ *
+ * Every mutator {@link SearchStateBag} ships follows this table; `clear` and
+ * the `patch` escape hatch push by default like any other applied change. A
+ * host that disagrees can still call {@link SearchStateBag.patch} directly
+ * with its own `replace` — the table governs this pair's own controls, not
+ * every possible call.
+ */
+export const DEFAULT_HISTORY_MODE: Readonly<Record<SearchHistoryKind, HistoryMode>> = {
+  text: "replace",
+  sort: "push",
+  category: "push",
+  language: "push",
+  filter: "push",
+  range: "push",
+  geo: "push",
+  limit: "replace",
+  clear: "push",
+  page: "replace",
+  patch: "push",
+};
+
+/** {@link DEFAULT_HISTORY_MODE} as the `setParams` options it produces. */
+function historyOptions(kind: SearchHistoryKind): { readonly replace?: boolean } {
+  return DEFAULT_HISTORY_MODE[kind] === "replace" ? { replace: true } : {};
+}
+
 /** Everything a control needs to read and move the search. */
 export interface SearchStateBag {
   /** The current state, parsed from the URL. Nothing else holds a copy. */
@@ -292,11 +360,15 @@ export function SearchStateProvider(
   const commit = useCallback(
     (next: SearchQueryState, options?: { readonly replace?: boolean }): void => {
       setParams(
-        writeSearchState(next, new URLSearchParams(search), facetKeys),
+        writeSearchState(next, new URLSearchParams(search), facetKeys, {
+          defaultType,
+          ...(defaultSort !== undefined ? { defaultSort } : {}),
+          ...(defaultLimit !== undefined ? { defaultLimit } : {}),
+        }),
         options
       );
     },
-    [setParams, search, facetKeys]
+    [setParams, search, facetKeys, defaultType, defaultSort, defaultLimit]
   );
 
 
@@ -337,31 +409,38 @@ export function SearchStateProvider(
       geoOffer: state.geo === undefined ? offer : undefined,
       geoIsOffer: sameCenter(state.geo, offer),
 
-      // Typing replaces rather than pushes: one history entry per letter
-      // would make Back useless, which is the control the spec's acceptance
-      // leans on for "Back removes the last filter".
-      setText: (q) => apply(patchSearchState(state, { q }), { replace: true }),
-      setSort: (sort) => apply(patchSearchState(state, { sort })),
-      setCategory: (category) => apply(patchSearchState(state, { category })),
-      setLanguage: (lang) => apply(patchSearchState(state, { lang })),
-      toggleFilter: (slug, value) => apply(toggleFilterValue(state, slug, value)),
-      setFilter: (slug, values) => apply(setFilterValues(state, slug, values)),
-      setRange: (slug, range) => apply(setRangeValue(state, slug, range)),
+      // Every history mode below follows DEFAULT_HISTORY_MODE — see that
+      // table for the reasoning behind which kind pushes and which replaces.
+      setText: (q) => apply(patchSearchState(state, { q }), historyOptions("text")),
+      setSort: (sort) => apply(patchSearchState(state, { sort }), historyOptions("sort")),
+      setCategory: (category) =>
+        apply(patchSearchState(state, { category }), historyOptions("category")),
+      setLanguage: (lang) =>
+        apply(patchSearchState(state, { lang }), historyOptions("language")),
+      toggleFilter: (slug, value) =>
+        apply(toggleFilterValue(state, slug, value), historyOptions("filter")),
+      setFilter: (slug, values) =>
+        apply(setFilterValues(state, slug, values), historyOptions("filter")),
+      setRange: (slug, range) =>
+        apply(setRangeValue(state, slug, range), historyOptions("range")),
       setGeo: (geo) => {
-        apply(patchSearchState(state, { geo }));
+        apply(patchSearchState(state, { geo }), historyOptions("geo"));
       },
       acceptGeoOffer: () => {
         if (offer === undefined || state.geo !== undefined) return;
         // A PUSH, like any other filter the person applies: Back takes the
         // narrowing off again, which is the same promise every chip makes.
-        apply(patchSearchState(state, { geo: offer }));
+        apply(patchSearchState(state, { geo: offer }), historyOptions("geo"));
       },
-      // A page size is a preference, not a step through the results.
-      setLimit: (limit) => apply(patchSearchState(state, { limit }), { replace: true }),
-      clearAll: () => apply(clearFilters(state)),
+      setLimit: (limit) =>
+        apply(patchSearchState(state, { limit }), historyOptions("limit")),
+      clearAll: () => apply(clearFilters(state), historyOptions("clear")),
+      // A keyset move REPLACES: it is scrolling, not a decision, and a push
+      // here used to make Back page backwards forever instead of leaving the
+      // results where the visitor actually was.
       goToAnchor: (anchor, direction) =>
-        apply(patchSearchState(state, { anchor, direction })),
-      patch: (patch) => apply(patchSearchState(state, patch)),
+        apply(patchSearchState(state, { anchor, direction }), historyOptions("page")),
+      patch: (patch) => apply(patchSearchState(state, patch), historyOptions("patch")),
     };
   }, [parsed, commit, geoOffer]);
 

package/src/index.ts

@@ -102,6 +102,7 @@ export type {
   SearchStateIssue,
   SearchStateIssueCode,
   SearchStatePatch,
+  WriteSearchStateDefaults,
 } from "./state/urlState.js";
 
 export {
@@ -185,12 +186,15 @@ export { useRankingDisclosure, useSearchQuery, useSuggest } from "./model/querie
 // ── headless (renderless components) ─────────────────────────────────────────
 export { SearchProvider } from "./headless/SearchProvider.js";
 export {
+  DEFAULT_HISTORY_MODE,
   SearchStateProvider,
   useFacetKeys,
   usePublishFacetKeys,
   useSearchState,
 } from "./headless/SearchStateProvider.js";
 export type {
+  HistoryMode,
+  SearchHistoryKind,
   SearchParamsAdapter,
   SearchStateBag,
   SearchStateProviderProps,

package/src/state/urlState.ts

@@ -462,6 +462,26 @@ function optional<K extends string, V>(
   return value === undefined ? {} : ({ [key]: value } as Record<K, V>);
 }
 
+/**
+ * The defaults {@link writeSearchState} may omit — the other half of
+ * {@link ParseSearchStateOptions}.
+ *
+ * A value equal to its default is written back by {@link parseSearchState}
+ * whether or not the URL states it, so writing it too is pure noise: it is
+ * how `?type=listing` ended up in every address on a host with exactly one
+ * doc type, and how a page-size default rode along in a link that never
+ * touched it. Omitting it costs nothing on the read side — the same default
+ * fills the gap — and the address stops asserting a fact nobody chose.
+ */
+export interface WriteSearchStateDefaults {
+  /** Matches {@link ParseSearchStateOptions.defaultType}. */
+  readonly defaultType?: string;
+  /** Matches {@link ParseSearchStateOptions.defaultSort}. */
+  readonly defaultSort?: string;
+  /** Matches {@link ParseSearchStateOptions.defaultLimit}. */
+  readonly defaultLimit?: number;
+}
+
 /**
  * State → URL.
  *
@@ -473,11 +493,18 @@ function optional<K extends string, V>(
  * `keys` is the answer's short-key map: a filter is written as its
  * `url_key` when the answer states one and as its slug otherwise, so the two
  * halves of a round trip agree without either side chopping at a string.
+ *
+ * `defaults` is what lets `type`, `sort` and `limit` disappear from the
+ * address when they equal the value {@link parseSearchState} would have
+ * filled in anyway — see {@link WriteSearchStateDefaults}. Omitted, nothing
+ * changes: every one of the three is written whenever the state carries it,
+ * exactly as before this existed.
  */
 export function writeSearchState(
   state: SearchQueryState,
   base?: URLSearchParams,
-  keys?: FacetKeyMap
+  keys?: FacetKeyMap,
+  defaults?: WriteSearchStateDefaults
 ): URLSearchParams {
   const next = new URLSearchParams();
 
@@ -488,7 +515,7 @@ export function writeSearchState(
     }
   }
 
-  next.set(SEARCH_PARAM.type, state.type);
+  if (state.type !== defaults?.defaultType) next.set(SEARCH_PARAM.type, state.type);
   if (state.q.length > 0) next.set(SEARCH_PARAM.q, state.q);
   if (state.lang !== undefined) next.set(SEARCH_PARAM.lang, state.lang);
   if (state.category !== undefined) next.set(SEARCH_PARAM.category, state.category);
@@ -523,7 +550,9 @@ export function writeSearchState(
     }
   }
 
-  if (state.sort !== undefined) next.set(SEARCH_PARAM.sort, state.sort);
+  if (state.sort !== undefined && state.sort !== defaults?.defaultSort) {
+    next.set(SEARCH_PARAM.sort, state.sort);
+  }
   if (state.facets !== undefined) {
     next.set(
       SEARCH_PARAM.facets,
@@ -532,7 +561,9 @@ export function writeSearchState(
   }
   if (state.anchor !== undefined) next.set(SEARCH_PARAM.anchor, state.anchor);
   if (state.direction !== undefined) next.set(SEARCH_PARAM.direction, state.direction);
-  if (state.limit !== undefined) next.set(SEARCH_PARAM.limit, String(state.limit));
+  if (state.limit !== undefined && state.limit !== defaults?.defaultLimit) {
+    next.set(SEARCH_PARAM.limit, String(state.limit));
+  }
 
   return next;
 }