@spree/docs 0.1.139 → 0.1.141

package/dist/developer/core-concepts/metafields.md

@@ -33,6 +33,8 @@ erDiagram
         string metafield_type
         string resource_type
         string display_on
+        boolean searchable
+        boolean sortable
     }
 
     Metafield {
@@ -83,6 +85,40 @@ Metafields support two visibility levels via the `display_on` attribute:
 | `both` | Yes | Yes | Public product specifications |
 | `back_end` | No | Yes | Internal notes, integration IDs |
 
+## Search, sort & filter
+
+Product metafield definitions can opt into SearchProvider participation:
+
+| Flag | Effect | Allowed field types |
+|------|--------|---------------------|
+| `searchable` | Values are included in product text search | `short_text`, `long_text`, `number` |
+| `sortable` | Listings can sort with `sort=cf_{namespace}_{key}` (prefix `-` for descending), e.g. `cf_custom_label` | `short_text`, `number` |
+
+Both default to `false`. Set them on the definition (Admin UI, Admin API, or seeds). For an existing catalog with Meilisearch, run `rake spree:search:reindex` after toggling flags so index settings and product documents pick up new `cf_*` fields.
+
+### Filtering
+
+Any definition with either flag set also becomes filterable on product listings, using its `cf_*` key as a Ransack predicate. The Store and Admin APIs accept the same keys and the same `sort` values:
+
+```
+GET /api/v3/store/products?q[cf_custom_material_i_cont]=wool
+GET /api/v3/admin/products?q[cf_custom_weight_gteq]=3.5
+GET /api/v3/store/products?sort=-cf_custom_weight
+```
+
+| Field type | Predicates |
+|------------|------------|
+| `short_text`, `long_text` | `i_cont`, `cont`, `eq`, `not_eq`, `start`, `end`, `present`, `blank` |
+| `number` | `eq`, `gt`, `gteq`, `lt`, `lteq`, `present`, `blank` |
+
+Use `i_cont` for case-insensitive matching — plain `cont` is case-sensitive on PostgreSQL.
+
+Predicates that don't match the definition's field type are ignored rather than rejected, as are keys matching no definition. Meilisearch supports the equality, range, and `present`/`blank` predicates; substring predicates (`i_cont`, `cont`, `start`, `end`) apply only to the database provider.
+
+CSV exports honor the same predicates, so exporting a filtered product list matches what the admin sees.
+
+In the admin dashboard, these fields appear in the products table's column selector, Sort dropdown, and filter panel — hidden by default, so admins opt in per column.
+
 ## Supported Resources
 
 Metafields can be attached to most Spree resources including Products, Variants, Orders, Line Items, Taxons, Payments, Shipments, Gift Cards, Store Credits, and more.

package/dist/developer/core-concepts/search-filtering.md

@@ -9,11 +9,11 @@ import { Since } from '/snippets/since.mdx';
 
 Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
 
-- Full-text search across product names and SKUs
+- Full-text search across product names, SKUs, and searchable product metafields
 - Attribute-based filtering (price range, availability, stock status)
 - Category and taxon filtering
 - Faceted search with filter counts
-- Flexible sorting options
+- Flexible sorting options (including sortable product custom fields via `sort=cf_{namespace}_{key}`)
 
 ## Product Search
 
@@ -156,6 +156,7 @@ const sorted = await client.products.list({
 
 // Available sort options (prefix '-' for descending; use '-available_on' for newest):
 // price, -price, name, -name, available_on, -available_on, best_selling
+// Plus any product custom field marked sortable, e.g. cf_custom_label / -cf_custom_label
 ```
 
 ```typescript Admin SDK

package/dist/developer/how-to/custom-search-provider.md

@@ -224,6 +224,12 @@ Background jobs (`IndexJob`, `RemoveJob`) fire on `after_commit` when `indexing_
 
 Always use prefixed IDs (`ctg_abc`, `prod_xyz`, `optval_abc`) when indexing. Never use raw database IDs — Spree supports UUID primary keys.
 
+### Metafield search schema
+
+Product metafields marked `searchable` / `sortable` on `MetafieldDefinition` are projected through `Spree::SearchProvider::MetafieldSchema` — shared by providers and `ProductPresenter`. Toggle participation with definition flags; run `rake spree:search:reindex` after changes when using Meilisearch.
+
+Document shaping for `cf_*` fields stays on `search_product_presenter` — the only search-related dependency.
+
 ## Related Documentation
 
 - [Search & Filtering](../core-concepts/search-filtering.md) — Store API search reference

package/dist/developer/upgrades/5.5-to-5.6.md

@@ -129,6 +129,36 @@ bundle exec rake spree:upgrade:backfill_product_tag_tenants
 
 Sets the `tenant` column on existing `Spree::Product` taggings from each product's `store_id`. New product taggings tenant themselves automatically — only rows created before the upgrade need this. Until it runs, product tags created before the upgrade are hidden from the store's tag-autocomplete vocabulary (they reappear once it completes; storefront and admin tag *display* are unaffected).
 
+### Sanitize stored product descriptions (added in 5.6.2)
+
+Spree 5.6.2 sanitizes product description HTML on every write (`Spree::RichTextSanitizer` — strips `script` tags, event-handler attributes, and `javascript:` URLs; keeps tables, images, links, and safe inline styles). This task runs your **existing** descriptions and their translations through the same sanitizer:
+
+
+```bash Spree CLI (Docker)
+spree rake spree:sanitize_rich_text
+```
+
+```bash Without Spree CLI
+bundle exec rake spree:sanitize_rich_text
+```
+
+
+Idempotent — only rows whose sanitized output differs are rewritten, and a changed-row count is printed per model.
+
+> **NOTE:** **Already on 5.6.0 or 5.6.1?** This step was added to the manifest in 5.6.2, so a `spree:upgrade` you ran earlier did not include it. Re-run `spree:upgrade` after bumping (every step is idempotent, so the earlier steps are no-ops), or run just this one:
+> 
+> ```bash
+bundle exec rake spree:upgrade STEP=sanitize_rich_text
+```
+
+> **WARNING:** `iframe` is stripped by default. If your descriptions embed videos or other iframes, permit the tag **before** running the task (and before saving products under 5.6.2):
+> 
+> ```ruby
+# config/initializers/spree.rb
+Spree::RichTextSanitizer.allowed_tags += %w[iframe]
+Spree::RichTextSanitizer.allowed_attributes += %w[allow allowfullscreen frameborder]
+```
+
 ## Update the Spree SDK
 
 Spree 5.6 ships alongside `@spree/sdk` 1.2. The backend upgrade never touches your frontend source — bump the SDK in every JavaScript consumer of the Store API and take it through your normal PR/CI cycle:
@@ -169,3 +199,9 @@ With `store_id` on role assignments, an admin's abilities are scoped to the stor
 ### Product tag autocomplete is store-scoped
 
 The Admin API tag-autocomplete endpoint (`GET /api/v3/admin/tags`) now returns only tags used within the current store for store-owned taggables (products and orders). Customer tags remain global. If an integration relied on this endpoint returning tags across every store, that cross-store vocabulary is no longer exposed. Run [the tag-tenant backfill](#backfill-the-store-tenant-on-product-tags) so pre-upgrade product tags are included.
+
+### Product descriptions are sanitized on write (5.6.2)
+
+From 5.6.2, product description HTML is sanitized on save — Admin API writes, CSV imports, and translation writes all pass through `Spree::RichTextSanitizer`. `script`, event-handler attributes, and `javascript:` URLs are removed; tables, images, links, and safe inline CSS are preserved. The allowlist is configurable (`Spree::RichTextSanitizer.allowed_tags` / `.allowed_attributes`) — see [the sanitize task](#sanitize-stored-product-descriptions-added-in-562) for the iframe note. If an integration wrote raw `<script>` into descriptions for storefront injection, that pattern no longer works — move such code into your storefront theme.
+
+Sanitization runs in an ActiveRecord callback, so it covers writes that go through `save`/`update`. Callback-bypassing writes (`update_columns`, `update_all`, raw SQL) are not sanitized — if your code writes descriptions that way, call `Spree::RichTextSanitizer.sanitize` explicitly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.139",
+  "version": "0.1.141",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",