@stapel/search-react 0.27.0 → 0.29.0

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";
@@ -269,14 +272,18 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
    * the two frames want opposite shapes and only this component knows which
    * one it is drawing: the desktop rail gets `"field"` (a select-style «Any»
    * that opens the searchable list — a 418-value vocabulary held open in a
-   * 280px column is the whole column), the phone sheet gets `"inline"`
-   * (the sheet is already the disclosure). Set it to override both.
+   * 280px column is the whole column), the phone sheet gets `"sheet"` — the
+   * same trigger row, opening a nested picker with a search box, a
+   * recommended band and the rest.
    *
-   * It was unreachable through this component until now: the panel had the
-   * prop, `<SearchPage>` forwarded nothing, and a storefront that mounts the
-   * page rather than the pane could not get the field at all.
+   * The phone default was `"inline"`, which drew the axis as a wall of
+   * checkboxes with a "Find a value" box over it while the COMPOSER's picker
+   * for the very same vocabulary was a trigger and a sheet. One dictionary,
+   * two gestures, depending on which half of the product you were in. Set it
+   * to override both; `"inline"` is still there for a surface that is
+   * already devoted to one group.
    */
-  readonly dictionaryMode?: "field" | "inline";
+  readonly dictionaryMode?: "field" | "inline" | "sheet";
   /**
    * How many groups the rail draws before the rest fold behind "All filters"
    * — see {@link FacetPanelPaneProps.visibleGroups}.
@@ -367,6 +374,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;
@@ -449,7 +459,7 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
 
 interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
-  readonly dictionaryMode?: "field" | "inline";
+  readonly dictionaryMode?: "field" | "inline" | "sheet";
   readonly visibleGroups?: number | null;
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly renderEmptyExits?: () => ReactNode;
@@ -468,6 +478,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;
@@ -580,7 +591,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
             : // STATIC, not sticky: the rail scrolls with the page, and a bar
               // pinned to the port's floor sat on top of the last groups.
               { footerBar: "static" as const })}
-          dictionaryMode={props.dictionaryMode ?? (layout === "sheet" ? "inline" : "field")}
+          dictionaryMode={props.dictionaryMode ?? (layout === "sheet" ? "sheet" : "field")}
           // `??` would treat an explicit `null` ("never fold") the same as
           // "not set": `visibleGroups` uses `null` as a real value, unlike
           // `dictionaryMode` above, so only `undefined` falls through.
@@ -659,6 +670,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 +852,7 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     appliedChips,
     otherCategories,
     categoryName,
+    categoryHref,
     resultsHeading,
     degradationNotice,
     filtersLayout,
@@ -879,6 +894,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";
 
@@ -106,6 +107,7 @@ export {
   facetOptionNodes,
   isDictionaryFacet,
   FACET_DICTIONARY_THRESHOLD,
+  FACET_SHEET_PAGE,
   FACET_VISIBLE_OPTIONS,
 } from "./FacetGroupControl.js";
 export type {

package/src/headless/FacetPanel.tsx

@@ -89,6 +89,15 @@ export interface FacetPanelBag {
   readonly activeFilters: number;
 
   toggle(slug: string, value: string): void;
+  /**
+   * Write one slug's chosen values WHOLE — the bulk half of `toggle`.
+   *
+   * `toggle` reads the state it flips, so several of them in one tick
+   * collapse into the last. A control that holds a draft and applies it once
+   * — the phone's dictionary sheet — needs to say the whole list, and a
+   * storefront replaying a saved search needs the same call.
+   */
+  setValues(slug: string, values: readonly string[]): void;
   setRange(slug: string, range: SearchRange | null): void;
   clear(slug: string): void;
   clearAll(): void;
@@ -224,6 +233,7 @@ export function useFacetPanel(props: {
       envelope.data.degraded.includes(FACET_PLAN_EVIDENCE),
     activeFilters,
     toggle: toggleFilter,
+    setValues: setFilter,
     setRange,
     clear: (slug) => {
       setFilter(slug, []);

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/i18n/es.ts

@@ -93,6 +93,9 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.facets.dictionary_empty": "Ningún valor coincide con esto",
   "search.facets.dictionary_chosen": "Elegido",
   "search.facets.dictionary_any": "Cualquiera",
+  "search.facets.dictionary_recommended": "Recomendados",
+  "search.facets.dictionary_all_values": "Todos los valores",
+  "search.facets.dictionary_done": "Listo",
   "search.facets.all_filters": "Todos los filtros ({count})",
   "search.facets.range_bounds": "de {min} a {max}",
   "search.facets.popular_all": "Todos",

package/src/i18n/keys.ts

@@ -183,6 +183,21 @@ export const SEARCH_I18N_KEYS = {
    * diverge in every language with gender or case.
    */
   facetsDictionaryAny: "search.facets.dictionary_any",
+  /**
+   * The heading over a dictionary sheet's first band: the busiest values of
+   * this axis, which is the EVIDENCE the answer carries and not an editorial
+   * pick. Distinct from `facetsPopularValues`, which names a block on the
+   * results page rather than a section inside one picker.
+   */
+  facetsDictionaryRecommended: "search.facets.dictionary_recommended",
+  /** The heading over the rest of the dictionary sheet — everything the band
+   * did not take, alphabetically. Not `facetsShowAll`: that is a fold's
+   * button, this is a section a person scrolls into. */
+  facetsDictionaryAllValues: "search.facets.dictionary_all_values",
+  /** The dictionary sheet's commit. A multi-select sheet holds a draft and
+   * applies it once, so this word is the difference between keeping the
+   * ticks and dismissing them. */
+  facetsDictionaryDone: "search.facets.dictionary_done",
   /**
    * The tail of the rail, folded: how many groups are behind one control.
    * `{count}` is a number in parentheses, not a counted noun, so this is not
@@ -563,6 +578,9 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.facets.dictionary_empty": "No value matches this",
   "search.facets.dictionary_chosen": "Chosen",
   "search.facets.dictionary_any": "Any",
+  "search.facets.dictionary_recommended": "Recommended",
+  "search.facets.dictionary_all_values": "All values",
+  "search.facets.dictionary_done": "Done",
   "search.facets.all_filters": "All filters ({count})",
   "search.facets.range_bounds": "from {min} to {max}",
   "search.facets.popular_all": "All",

package/src/i18n/ru.ts

@@ -118,6 +118,9 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.facets.dictionary_empty": "Такого значения здесь нет",
   "search.facets.dictionary_chosen": "Выбрано",
   "search.facets.dictionary_any": "Любая",
+  "search.facets.dictionary_recommended": "Рекомендуемые",
+  "search.facets.dictionary_all_values": "Все варианты",
+  "search.facets.dictionary_done": "Готово",
   "search.facets.all_filters": "Все фильтры ({count})",
   "search.facets.range_bounds": "от {min} до {max}",
   "search.facets.popular_all": "Все",

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;
 }