@reblu/site-blocks 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @reblu/site-blocks
 
+## 0.5.0
+
+### Minor Changes
+
+- baa36cf: Add a plug-and-play `ShopFilters` component so a SITE never hand-builds shop
+  filter UI again (REB-809) — the gap that made the dermamedicin SITE hardcode
+  `BRAND_AXIS = 'brand'` while that tenant's real axis key is `marca`.
+
+  `@reblu/site-blocks` exports `ShopFilters` (root entry, RSC-safe): one
+  fieldset per non-empty `facets.taxonomies` axis (single-select, with a
+  click-to-clear toggle on the active term — see the component's doc comment
+  for why single-select, given the current `taxonomy[<key>]` query contract), a
+  multi-select fieldset per filterable attribute, a price-band fieldset
+  (`priceBands` prop, sensible EUR defaults, also click-to-clear), and an
+  on-sale toggle. A filter selection that collapses every facet to empty still
+  renders "Clear filters" rather than nothing — also exported as the standalone
+  predicate `shouldRenderShopFilters(facets, active)`, so a consuming page can
+  gate its own wrapping landmark on the identical decision. Every option always
+  renders a real `<a href>`; `onChange` is strictly additive for a Client
+  Component caller. Price-band labels ("Under €25", "€25 – €50", "€100+") come
+  from three overridable `ShopFiltersLabels` templates (`priceUnder`,
+  `priceOver`, `priceRange`), not hardcoded English, plus `currencyCode`/
+  `locale` props matching `ProductCard`'s. Tokens only, fieldset/legend
+  semantics, `aria-current` on the active option(s), zero accessibility
+  violations (`jest-axe`).
+
+  `@reblu/site-next` exports the URL glue from two new subpaths:
+  `./shop-server` (`parseShopSearchParams`, `serializeShopParams`,
+  `toURLSearchParams`, `buildShopFilterHrefs`, `getShopCollection` — all
+  server-safe, no `'use client'`) and `./shop` (adds the client-reactive
+  `useShopFilterLinks` hook). `parseShopSearchParams`/`serializeShopParams`
+  mirror base-api's own `parseListParams` bracket shape and MVP
+  single-value-per-taxonomy-axis collapse, so a URL this SDK builds is exactly
+  the URL the server parses back — including hardening against
+  prototype-pollution-shaped bracket keys (`taxonomy[__proto__]` and friends)
+  and strict digit-only numeric parsing, while `taxonomy`/`attr` on the
+  returned `ShopProductsParams` are always guaranteed PLAIN objects (never the
+  null-prototype accumulator used internally for that hardening) — React
+  Flight refuses a null-prototype prop crossing the Server→Client Component
+  boundary, and a Client Component caller passing `active={params}` into
+  `ShopFilters`' `onChange` mode is exactly the documented usage this
+  guarantees stays safe. `toURLSearchParams` converts Next's `searchParams`
+  route prop into a `URLSearchParams`, preserving a repeated key as a repeated
+  entry (the native `URLSearchParams` constructor does not). `getShopCollection`
+  fetches products and facets with the identical params, in parallel — a
+  products failure propagates, a facets failure degrades to an empty
+  `ShopFacets` so the listing survives rather than one upstream outage taking
+  both down, logs once (`console.warn('[getShopCollection] …')`) so the
+  degradation is never silent, and the resolved `ShopCollection` carries
+  `facetsStatus: 'ok' | 'unavailable'` so a caller can tell "no filterable axes
+  configured" apart from "facets endpoint is down" without parsing a log line.
+
+### Patch Changes
+
+- Updated dependencies [baa36cf]
+  - @reblu/site-contracts@1.3.0
+
 ## 0.4.4
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,7 @@ a different-looking site for every tenant, with zero forks.
 | `sanitizeHtml` | `.` | Sanitises an HTML string before `dangerouslySetInnerHTML` — the **HTML boundary**. See "Security boundaries" below. |
 | `MarkdownRenderer` | `.` | Canonical Blog renderer: `marked` → **hast-util-sanitize** (XSS) → component map, with a YouTube-domain allowlist. RSC-safe. |
 | `Treatment`, `Specialty`, `ProfileCard`, `ProductCard` | `.` | Presentational organisms over the SITE API contracts. RSC-safe. |
+| `ShopFilters` | `.` | Plug-and-play shop filter chrome over `GET /api/site/shop/facets`. RSC-safe. See "Shop filters" below. |
 | `useCollection` | `./client` | Headless filterable/sortable/paginated collection hook (facets, category, tag, search). Serves both page and blog indexes. |
 | `Collection` | `./client` | Token-driven presentational grid over `useCollection`. |
 | `ShareButtons` | `./client` | Social share (X / LinkedIn / WhatsApp / copy). |
@@ -91,6 +92,95 @@ harden external links, and it forwards only the attributes that carry **meaning*
 - **Dropped upstream by the sanitiser, before the renderer sees it:** `reversed`
   on `<ol>`. Number a descending list explicitly with `value` on each `<li>`.
 
+## Shop filters
+
+`ShopFilters` (REB-809) is the plug-and-play SDK component that closes a real
+gap: before it existed, every SITE hand-built its own shop filter UI — the
+dermamedicin SITE hardcoded `BRAND_AXIS = 'brand'` while that tenant's real
+taxonomy axis key is `marca`, a bug fixed ad hoc in that SITE's own repo (PR
+#69). Which axes appear, their order and their labels come ENTIRELY from
+`GET /api/site/shop/facets` (nexus config — Clasificaciones "Usar como filtro
+en la tienda", custom field "filtrable") — the component knows no concrete
+axis or attribute.
+
+```tsx
+import { ShopFilters } from '@reblu/site-blocks'
+import {
+  getShopCollection,
+  buildShopFilterHrefs,
+  parseShopSearchParams,
+  toURLSearchParams,
+} from '@reblu/site-next/shop-server'
+import { client } from '@/lib/reblu'
+
+// An async Server Component — a route's page.tsx. No 'use client' anywhere.
+export default async function ShopPage({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}) {
+  // toURLSearchParams, NOT `new URLSearchParams(await searchParams)` — the
+  // native constructor only accepts Record<string, string> and silently
+  // comma-joins a repeated-key array value into ONE entry, which breaks
+  // parseShopSearchParams' repeat-count-based array/scalar distinction for
+  // every multi-value attr[<key>] filter. See its own doc comment.
+  const params = parseShopSearchParams(toURLSearchParams(await searchParams))
+  const { products, facets } = await getShopCollection(client, params)
+  const hrefs = buildShopFilterHrefs(params, '/shop')
+
+  return (
+    <>
+      <ShopFilters facets={facets} hrefs={hrefs} active={params} />
+      {/* render products.data */}
+    </>
+  )
+}
+```
+
+**RSC-safe by construction (REB-647).** Every option always renders a real
+`<a href>` built by the `hrefs` prop — no event handler is ever attached
+unless you also pass `onChange`, so the snippet above works from an actual
+Server Component with zero client boundary: clicking a filter is a normal
+navigation, and the server re-renders with the new `searchParams`. Pass
+`onChange` only from inside a `'use client'` boundary (attaching a function
+prop to a host element only works when the call site itself runs on the
+client) — `@reblu/site-next/shop`'s `useShopFilterLinks()` hook is there for
+that case.
+
+**Single-select taxonomy filters, everywhere, on purpose.** `ShopFacets.
+taxonomies[].selectionMode` (REB-809/REB-801) is `'single' | 'multiple'`, but
+it describes how many terms a PRODUCT may carry on that axis — NOT how many
+the storefront filter may select at once. `GET /api/site/shop/products`'s
+`taxonomy[<key>]` query param accepts exactly one term slug per axis today
+(base-api's `parseListParams` collapses any repeat), so `ShopFilters` renders
+every taxonomy axis as single-select regardless of `selectionMode`: clicking
+the active term's own link clears the axis, clicking another replaces it.
+Wiring `selectionMode` into a true multi-value taxonomy filter needs the
+query contract to grow an array form first — out of this component's scope.
+Attribute facets (`facets.attributes`) are genuinely multi-select already
+(`attr[<key>]` repeats to OR-match several values), so those render as a
+checkbox-shaped list where more than one option may be active at once.
+
+Price bands are a `priceBands` prop with sensible EUR defaults
+(`DEFAULT_SHOP_PRICE_BANDS`) — `ShopFacets.price` only carries `{ min, max }`,
+never bands, so the component never invents a business-specific breakdown.
+A band's auto-generated label ("Under €25", "€25 – €50", "€100+") is built
+from `formatPrice` plus three `labels` templates — `priceUnder`, `priceOver`,
+`priceRange` — not hardcoded English; override them (and `currencyCode`/
+`locale`) the same way you override `allTerms`/`clearAll`/`onSale`/`price`.
+Clicking the currently ACTIVE band clears the price filter, the same toggle
+affordance as an active taxonomy term or attribute value.
+
+Every option toggles: clicking the active taxonomy term, the active price
+band, or an active attribute value all clear that selection rather than
+re-applying it as a no-op. `shouldRenderShopFilters(facets, active)` is
+exported so a consuming page can decide whether to render a wrapping
+landmark around `ShopFilters` without hand-copying its internal "is there
+anything to show" check — true when `facets` has real content OR `active`
+has a selection to clear (an active filter can legitimately collapse every
+facet option to zero; the component still renders "Clear filters" then,
+never stranding the visitor with no way back).
+
 ## Security boundaries
 
 Two sinks, two different helpers, in two different packages — do not reach for

package/dist/index.cjs

@@ -21,10 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   ALLOWED_YOUTUBE_HOSTS: () => ALLOWED_YOUTUBE_HOSTS,
+  DEFAULT_SHOP_PRICE_BANDS: () => DEFAULT_SHOP_PRICE_BANDS,
   MarkdownRenderer: () => MarkdownRenderer,
   ProductCard: () => ProductCard,
   ProfileCard: () => ProfileCard,
   SafeHtml: () => SafeHtml,
+  ShopFilters: () => ShopFilters,
   Specialty: () => Specialty,
   Treatment: () => Treatment,
   buildShareUrls: () => buildShareUrls,
@@ -32,7 +34,8 @@ __export(src_exports, {
   isAllowedYouTubeHost: () => isAllowedYouTubeHost,
   markdownToSafeHtml: () => markdownToSafeHtml,
   readingTime: () => readingTime,
-  sanitizeHtml: () => sanitizeHtml
+  sanitizeHtml: () => sanitizeHtml,
+  shouldRenderShopFilters: () => shouldRenderShopFilters
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -13429,13 +13432,198 @@ function ProductCard({ product, href, currencyCode = "EUR", locale, className })
     }
   );
 }
+
+// src/components/shop-filters.tsx
+var import_utils7 = require("@reblu/site-ui/utils");
+var import_jsx_runtime7 = require("react/jsx-runtime");
+var DEFAULT_SHOP_PRICE_BANDS = [
+  { max: 2500 },
+  { min: 2500, max: 5e3 },
+  { min: 5e3, max: 1e4 },
+  { min: 1e4 }
+];
+var DEFAULT_LABELS = {
+  allTerms: "All",
+  clearAll: "Clear filters",
+  onSale: "On sale",
+  price: "Price",
+  priceUnder: (formattedMax) => `Under ${formattedMax}`,
+  priceOver: (formattedMin) => `${formattedMin}+`,
+  priceRange: (formattedMin, formattedMax) => `${formattedMin} \u2013 ${formattedMax}`
+};
+function toValueArray(value) {
+  if (value === void 0) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function hasAnyActiveFilter(active) {
+  return Object.keys(active.taxonomy ?? {}).length > 0 || Object.keys(active.attr ?? {}).length > 0 || active.priceMin !== void 0 || active.priceMax !== void 0 || Boolean(active.onSale);
+}
+function shouldRenderShopFilters(facets, active = {}) {
+  const hasFacetContent = facets.taxonomies.some((axis) => axis.terms.length > 0) || facets.attributes.some((attr) => attr.options.length > 0) || facets.price.max > facets.price.min || facets.onSale.count > 0;
+  return hasFacetContent || hasAnyActiveFilter(active);
+}
+function priceBandLabel(band, t, currencyCode, locale) {
+  if (band.label) return band.label;
+  if (band.min === void 0 && band.max !== void 0) {
+    return t.priceUnder(formatPrice(band.max, currencyCode, locale));
+  }
+  if (band.max === void 0 && band.min !== void 0) {
+    return t.priceOver(formatPrice(band.min, currencyCode, locale));
+  }
+  if (band.min !== void 0 && band.max !== void 0) {
+    return t.priceRange(formatPrice(band.min, currencyCode, locale), formatPrice(band.max, currencyCode, locale));
+  }
+  return "";
+}
+function OptionLink({ href, active, label, onActivate }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+    "a",
+    {
+      href,
+      "aria-current": active ? "true" : void 0,
+      onClick: onActivate ? (event) => {
+        event.preventDefault();
+        onActivate();
+      } : void 0,
+      className: (0, import_utils7.cn)(
+        "inline-flex items-center rounded-full border px-3 py-1 text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        active ? "border-transparent bg-primary text-primary-foreground" : "border-border text-muted-foreground hover:bg-muted hover:text-foreground"
+      ),
+      children: label
+    }
+  );
+}
+function FilterFieldset({ legend, children: children2 }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)("fieldset", { className: "space-y-2", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("legend", { className: "text-sm font-medium text-foreground", children: legend }),
+    /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { className: "flex flex-wrap gap-2", children: children2 })
+  ] });
+}
+function ShopFilters({
+  facets,
+  hrefs,
+  active = {},
+  onChange,
+  priceBands = DEFAULT_SHOP_PRICE_BANDS,
+  labels,
+  currencyCode,
+  locale,
+  className
+}) {
+  const t = { ...DEFAULT_LABELS, ...labels };
+  const visibleTaxonomies = facets.taxonomies.filter((axis) => axis.terms.length > 0);
+  const visibleAttributes = facets.attributes.filter((attr) => attr.options.length > 0);
+  const hasPriceSpread = facets.price.max > facets.price.min;
+  const hasOnSale = facets.onSale.count > 0;
+  if (!shouldRenderShopFilters(facets, active)) {
+    return null;
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)("div", { className: (0, import_utils7.cn)("space-y-6", className), "data-slot": "shop-filters", children: [
+    visibleTaxonomies.map((axis) => {
+      const activeSlug = active.taxonomy?.[axis.key];
+      return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(FilterFieldset, { legend: axis.label, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+          OptionLink,
+          {
+            href: hrefs.taxonomy(axis.key, void 0),
+            active: activeSlug === void 0,
+            label: t.allTerms,
+            onActivate: onChange ? () => {
+              const next2 = { ...active.taxonomy };
+              delete next2[axis.key];
+              onChange({ taxonomy: next2 });
+            } : void 0
+          }
+        ),
+        axis.terms.map((term) => {
+          const isActive = activeSlug === term.slug;
+          return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+            OptionLink,
+            {
+              href: hrefs.taxonomy(axis.key, isActive ? void 0 : term.slug),
+              active: isActive,
+              label: `${term.name} (${term.count})`,
+              onActivate: onChange ? () => {
+                const next2 = { ...active.taxonomy };
+                if (isActive) delete next2[axis.key];
+                else next2[axis.key] = term.slug;
+                onChange({ taxonomy: next2 });
+              } : void 0
+            },
+            term.slug
+          );
+        })
+      ] }, axis.key);
+    }),
+    visibleAttributes.map((attr) => {
+      const activeValues = toValueArray(active.attr?.[attr.key]);
+      return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(FilterFieldset, { legend: attr.label, children: attr.options.map((opt) => {
+        const isActive = activeValues.includes(opt.value);
+        return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+          OptionLink,
+          {
+            href: hrefs.attr(attr.key, opt.value),
+            active: isActive,
+            label: `${opt.label} (${opt.count})`,
+            onActivate: onChange ? () => {
+              const next2 = isActive ? activeValues.filter((v2) => v2 !== opt.value) : [...activeValues, opt.value];
+              const attrNext = { ...active.attr };
+              if (next2.length === 0) delete attrNext[attr.key];
+              else attrNext[attr.key] = next2;
+              onChange({ attr: attrNext });
+            } : void 0
+          },
+          opt.value
+        );
+      }) }, attr.key);
+    }),
+    hasPriceSpread && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(FilterFieldset, { legend: t.price, children: priceBands.map((band, i) => {
+      const isActive = active.priceMin === band.min && active.priceMax === band.max;
+      const nextMin = isActive ? void 0 : band.min;
+      const nextMax = isActive ? void 0 : band.max;
+      return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+        OptionLink,
+        {
+          href: hrefs.price(nextMin, nextMax),
+          active: isActive,
+          label: priceBandLabel(band, t, currencyCode, locale),
+          onActivate: onChange ? () => onChange({ priceMin: nextMin, priceMax: nextMax }) : void 0
+        },
+        i
+      );
+    }) }),
+    hasOnSale && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+      OptionLink,
+      {
+        href: hrefs.onSale(!active.onSale),
+        active: Boolean(active.onSale),
+        label: `${t.onSale} (${facets.onSale.count})`,
+        onActivate: onChange ? () => onChange({ onSale: !active.onSale }) : void 0
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+      "a",
+      {
+        href: hrefs.clearAll(),
+        onClick: onChange ? (event) => {
+          event.preventDefault();
+          onChange({ taxonomy: {}, attr: {}, priceMin: void 0, priceMax: void 0, onSale: false });
+        } : void 0,
+        className: "text-sm font-medium text-muted-foreground underline-offset-4 hover:text-foreground hover:underline",
+        children: t.clearAll
+      }
+    )
+  ] });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALLOWED_YOUTUBE_HOSTS,
+  DEFAULT_SHOP_PRICE_BANDS,
   MarkdownRenderer,
   ProductCard,
   ProfileCard,
   SafeHtml,
+  ShopFilters,
   Specialty,
   Treatment,
   buildShareUrls,
@@ -13443,6 +13631,7 @@ function ProductCard({ product, href, currencyCode = "EUR", locale, className })
   isAllowedYouTubeHost,
   markdownToSafeHtml,
   readingTime,
-  sanitizeHtml
+  sanitizeHtml,
+  shouldRenderShopFilters
 });
 //# sourceMappingURL=index.cjs.map