@dogsbay/docs-layout 0.2.0-beta.71 → 0.2.0-beta.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.71",
+  "version": "0.2.0-beta.72",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.71",
-    "@dogsbay/primitives": "0.2.0-beta.71"
+    "@dogsbay/ui": "0.2.0-beta.72",
+    "@dogsbay/primitives": "0.2.0-beta.72"
   },
   "devDependencies": {
     "vitest": "^3.0.0"

package/src/SearchDialog.astro

@@ -161,6 +161,7 @@ const {
     shapeFacets,
     resolveFacetLabel,
     resolveFacetTitle,
+    sortFacetNames,
     filterStateToUrlParams,
     parseFiltersFromUrl,
     filterStateToPagefindFilters,
@@ -182,10 +183,15 @@ const {
     meta: { title?: string };
     sub_results?: Array<{ title: string; url: string; excerpt: string }>;
   };
+  // Filter values match what filterStateToPagefindFilters emits:
+  // each facet wrapped in `{any: [...]}` for OR-within-facet semantics.
+  // Pagefind also accepts other operator shapes (`all`/`none`/`not`,
+  // bare strings, bare arrays) but we only emit the `any` form.
+  type PagefindFilterValue = { any: string[] };
   type PagefindModule = {
     search(
       query: string,
-      options?: { filters?: Record<string, string[]> },
+      options?: { filters?: Record<string, PagefindFilterValue> },
     ): Promise<{ results: PagefindResult[] }>;
     filters(): Promise<Record<string, Record<string, number>>>;
   };
@@ -340,7 +346,10 @@ const {
      * filters, the sidebar stays hidden — single-column layout.
      */
     function renderFacets() {
-      const facetNames = Object.keys(availableFacets);
+      const facetNames = sortFacetNames(
+        Object.keys(availableFacets),
+        taxonomyDisplay,
+      );
       if (facetNames.length === 0) {
         facetsBox!.classList.add("hidden");
         return;

package/src/search-facets.ts

@@ -16,6 +16,13 @@ import type { PrefixDisplay } from "./tag-list-data.js";
 export interface TaxonomyDisplay {
   prefixes?: Record<string, PrefixDisplay>;
   labels?: Record<string, string>;
+  /**
+   * Sort weight for the facet column in the search dialog. Lower
+   * numbers appear first. Facets without an `order` sort
+   * alphabetically *after* any pinned ones — so `{ type: { order: 1 } }`
+   * promotes "Type" to the top while everything else stays alpha.
+   */
+  order?: number;
 }
 
 /** Map of taxonomy name → display config. */
@@ -120,6 +127,40 @@ export function resolveFacetTitle(facetName: string): string {
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+/**
+ * Return facet names in sidebar render order.
+ *
+ * Pagefind's `filters()` map iterates in index-discovery order
+ * (effectively the first page Pagefind happened to read), so without
+ * sorting the column order is arbitrary and shifts between builds.
+ * Order rule:
+ *  1. Facets with a numeric `order` in their `TaxonomyDisplay`
+ *     come first, ascending — use this to pin "Type" or "Audience"
+ *     to the top regardless of name.
+ *  2. Everything else sorts alphabetically by facet name.
+ * Stable within each tier so ties don't shuffle.
+ */
+export function sortFacetNames(
+  names: string[],
+  display?: TaxonomyDisplayMap,
+): string[] {
+  const withOrder = (name: string): number | undefined => {
+    const o = display?.[name]?.order;
+    return typeof o === "number" ? o : undefined;
+  };
+  return [...names].sort((a, b) => {
+    const oa = withOrder(a);
+    const ob = withOrder(b);
+    if (oa !== undefined && ob !== undefined) {
+      if (oa !== ob) return oa - ob;
+      return a.localeCompare(b);
+    }
+    if (oa !== undefined) return -1;
+    if (ob !== undefined) return 1;
+    return a.localeCompare(b);
+  });
+}
+
 // ── URL persistence ──────────────────────────────────────────────
 
 /**
@@ -175,21 +216,32 @@ export function parseFiltersFromUrl(
 }
 
 /**
- * Pagefind's `search()` accepts filters keyed by facet name with
- * either a single value, an array (OR), or a nested operator
- * object. We always pass the array form so multi-select works
- * within a facet without special-casing single-select.
+ * Build Pagefind's `filters` argument from internal facet state.
+ *
+ * Pagefind's array shape (`{ tag: ["a", "b"] }`) is AND by default —
+ * "page must have BOTH tags" — per
+ * https://pagefind.app/docs/js-api-filtering/ ("All filtering
+ * defaults to AND filtering"). That's the wrong UX for faceted
+ * search: clicking two checkboxes in the same group should widen
+ * the result set, not collapse it to zero. We wrap each facet in
+ * `{ any: [...] }` so multi-select within a facet is OR. Across
+ * different facets Pagefind already ANDs the keys, which matches
+ * the standard "narrow with each additional dimension" UX.
+ *
+ * Single-value selections also go through `{ any: ["x"] }` —
+ * Pagefind treats a one-element `any` identically to a bare string,
+ * so there's no behavioural delta and the code stays branch-free.
  *
  * Empty filter state → `{}` (Pagefind returns the unfiltered
- * result set). A facet with an empty array also drops out so we
- * don't accidentally narrow to "must equal nothing".
+ * result set). A facet with an empty array drops out so we don't
+ * accidentally narrow to "must equal nothing".
  */
 export function filterStateToPagefindFilters(
   filters: FilterState,
-): Record<string, string[]> {
-  const out: Record<string, string[]> = {};
+): Record<string, { any: string[] }> {
+  const out: Record<string, { any: string[] }> = {};
   for (const [name, values] of Object.entries(filters)) {
-    if (values.length > 0) out[name] = [...values];
+    if (values.length > 0) out[name] = { any: [...values] };
   }
   return out;
 }