Search blocks: Add end-user docs for WooCommerce filter blocks

[kangzj]

Fixes #

Proposed changes

• Add per-block end-user README documentation for the five WooCommerce-only Search blocks:
  • filter-wc-attribute — Filter by Product Attribute
  • filter-wc-price — Filter by Price (inputs + slider variations)
  • filter-wc-rating — Filter by Rating
  • filter-wc-stock-status — Filter by Stock Status
  • filters-product — Product Filters (container)
• Each README is written from the end-user / site author perspective (no implementation details), and covers when to use the block, available settings, and tips.
• Add src/search-blocks/blocks/WOOCOMMERCE.md — a hub doc that indexes the five WC-only blocks above and documents every WooCommerce-related option that lives on shared (non-WC-only) Search blocks:
  • Checkbox Filter — Product Category, Product Tag, Product Brand variations
  • Results List — the "Product (for WooCommerce stores)" result format
  • Sort By — Rating, Price: low to high, Price: high to low sort orders
  • Active Filters — the dismissable price-range chip
• Bundle editor preview, settings panel, and (where applicable) front-end screenshots for each surface under src/search-blocks/blocks/.docs-assets/.

Related product discussion/links

• Linear: RSM-3000 — Documentation for Jetpack Search blocks — WooCommerce features
• Follow-up to RSM-2807 / Add per-block README.md documentation for 14 non-WooCommerce Jetpack Search blocks (RSM-2807) #48679 — that work covered the non-WC Search blocks; this PR covers the WooCommerce-gated set plus the WC features on shared blocks.

Does this pull request change what data or activity we track or use?

No — docs and screenshot assets only. No tracking or runtime changes.

Testing instructions

This PR is documentation only — no functional code changes — so testing is a documentation review rather than a build/run cycle.

• Browse each new doc in the GitHub diff view (or locally) and confirm the prose reads naturally from a site author's perspective without referencing internals:
  • projects/packages/search/src/search-blocks/blocks/WOOCOMMERCE.md (the hub)
  • projects/packages/search/src/search-blocks/blocks/filter-wc-attribute/README.md
  • projects/packages/search/src/search-blocks/blocks/filter-wc-price/README.md
  • projects/packages/search/src/search-blocks/blocks/filter-wc-rating/README.md
  • projects/packages/search/src/search-blocks/blocks/filter-wc-stock-status/README.md
  • projects/packages/search/src/search-blocks/blocks/filters-product/README.md
• Confirm each doc's screenshots render in GitHub (editor preview, settings panel, and where applicable a front-end shot).
• Spot-check the cross-links between the WC READMEs and the hub (Product Filters → Stock Status, Rating, Price, Attribute; every WC-only README → WOOCOMMERCE.md). They should all resolve.
• Confirm the changelog entry under projects/packages/search/changelog/rsm-2807-wc-search-block-docs covers both the per-block READMEs and the hub doc.

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the rsm-2807-wc-search-block-docs branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack rsm-2807-wc-search-block-docs

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[jp-launch-control]

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report

[kangzj]

🤖 Review-cycle summary — 6d439902cb7 → 9680c40b546

4 round(s); CI green; 0 inline threads (review was at the issue level); 1 AI reviewer (@claude) addressed.

What changed during the cycle

Commits added:

• 9680c40b546 — Address review: de-link cross-references to non-existent READMEs and normalize US English

Diff summary: 4 files changed, 12 insertions(+), 12 deletions(-)

Review threads addressed:

Source	Comment	Resolution
@claude (bot)	#4435993130 — Six cross-links in filters-product/README.md point to READMEs that don't exist on trunk yet (Filters, Post Type Scope, Clear Filters, Active Filters, Checkbox Filter, Filter by Date).	Converted those six references to plain bold text in 9680c40b546. The five links to WC READMEs added in this PR remain as working markdown links. Re-link in a follow-up once the sibling docs land.
@claude (bot)	#4435993130 — flavours should be flavors (US-primary codebase).	Fixed filter-wc-price/README.md L3 in 9680c40b546. Also caught three other UK spellings the bot missed: recognisable → recognizable (price/L82), Customise → Customize (rating/L41), favour → favor (rating/L57).
@claude (bot)	#4435993130 — Pa Material example may confuse authors.	Changed the Label setting example in filter-wc-attribute/README.md L35 from "Pa Material" → "Made from" to "Material" → "Made from" in 9680c40b546.
@claude (bot)	#4436050360 / #4436051936 — Re-review verdict: all three issues correctly resolved; no remaining issues.	Endorsement received; no further action needed.

Unaddressed (flagged for owner): None.

CI: all required checks passing (21 pass, 10 skipping; 0 fail, 0 pending).

[kangzj]

@claude please review the follow-up commit covering WooCommerce features on shared blocks (filter-checkbox variations, results-list Product layout, results-sort Price/Rating orders, active-filters price chip) and the new WOOCOMMERCE.md hub doc.

[claude]

Claude finished @kangzj's task in 2m 19s —— View job

---

Review of follow-up commit — WC features on shared blocks + WOOCOMMERCE.md hub doc

• Read WOOCOMMERCE.md hub doc
• Read shared-block sections (filter-checkbox variations, results-list, results-sort, active-filters)
• Check cross-links, prose quality, US English, accuracy
• Post review feedback

---

Overall this is a strong, well-organized hub doc. The four shared-block sections (Checkbox Filter variations, Results List Product layout, Sort By, Active Filters) are exactly the right scope — concise, end-user-framed, and complementary to the per-block READMEs. The "Putting it together" summary at the end is a nice touch. One factual error in the inserter section, a few cosmetic nits, and a couple of suggestions below.

Issues

Factual error — WOOCOMMERCE.md line 15

The same cluster collapses to just Checkbox Filter and Filter by Rating (and a few other non-product blocks) when WooCommerce isn't active.

Filter by Rating is filter-wc-rating — a WC-only block, listed in the table two lines above on line 26. It does not appear in the inserter without WooCommerce active. The sentence should read:

The same cluster collapses to just Checkbox Filter (and a few other non-product blocks) when WooCommerce isn't active.

Fix this →

---

Minor nits

Double blank line before every ## See also

filter-wc-attribute/README.md L68–70, filter-wc-price/README.md L84–86, filter-wc-rating/README.md L58–60, filter-wc-stock-status/README.md L44–46, filters-product/README.md L58–60 all have two blank lines before the heading. Markdown renders them identically, but a single blank line before headings is the conventional style in the rest of this codebase. Cosmetic only.

WOOCOMMERCE.md table alignment on line 23

The separator row for the WC-only blocks table uses uneven column widths (|-------|------|-----------|). Not a rendering issue, just inconsistent with the tighter-aligned tables later in the file.

---

Suggestions (non-blocking)

Consider linking Filter by Price, Rating, and Stock Status in the Checkbox Filter tips (line 66)

The tips paragraph mentions them by name but only links Product Filters. The rest of WOOCOMMERCE.md consistently links to sibling READMEs in similar tip sentences. Linking here would be consistent and save a reader a trip to the table at the top.

WOOCOMMERCE.md inserter section could clarify the "non-product blocks" parenthetical

Line 15's "(and a few other non-product blocks)" is slightly vague. After fixing the Filter by Rating error, a brief gloss — e.g., "(Search Input, Active Filters, and the universal filter blocks)" — would help authors understand what they're still looking at.

---

What's working well

• Hub-doc structure (WC-only index table → shared-block sections → "Putting it together") mirrors how a site author would actually discover these features. Right call to organize it this way.
• Chip-label format table in the Active Filters section (both bounds / min only / max only) is the most useful practical reference in the whole doc set.
• Sort By tip about three options being the right number is concrete and actionable — exactly the kind of guidance that belongs in end-user docs.
• All five WC-only READMEs now have consistent ## See also footers pointing back at the hub. The changelog entry correctly covers both the original per-block READMEs and the new hub doc in a single entry.
• US English is consistent throughout (previous flavours, recognisable, Customise, favour fixes are all intact).

---

One fix required (the Filter by Rating / inserter claim). Everything else is optional polish. Good work on the hub doc.

[kangzj]

Thanks for the follow-up review @claude — addressed in 5d49399:

• 🔴 Factual error on WOOCOMMERCE.md line 16 — Rewrote the post-image paragraph. The corrected version states that without WooCommerce the entire product-filter cluster disappears from the inserter, with only the base Checkbox Filter remaining (which authors can still configure for Category, Tag, Author, or any taxonomy). Filter by Rating is no longer mentioned there.
• 🟡 Table separator alignment — Re-spaced the WooCommerce-only blocks table separator and rows for consistent column widths.
• 🟡 Double blank lines before ## See also — Collapsed to a single blank line across all five WC READMEs.
• Suggestion: cross-link Filter by Price / Rating / Stock Status in Checkbox Filter tips — Done. The three filters now resolve as markdown links in line 66 of the hub doc.
• Suggestion: clarify "non-product blocks" parenthetical — Folded the clarification into the rewrite for issue 1, naming the specific taxonomies that the base Checkbox Filter can still drive (Category, Tag, Author, any registered taxonomy). The vague parenthetical is gone.

[claude]

Claude finished @kangzj's task in 1m 6s —— View job

---

Re-review of addressed items — commit 5d49399

• Read WOOCOMMERCE.md — verify factual fix, table alignment, cross-links, parenthetical
• Read WC READMEs — verify double blank lines collapsed
• Post verdict

---

All five items correctly resolved. Verification details:

🔴 Factual error (WOOCOMMERCE.md line 16) — Fixed. The rewritten sentence reads:

"Without WooCommerce, this whole product cluster disappears from the inserter — only the base Checkbox Filter stays, which authors can still configure to filter by Category, Tag, Author, or any registered taxonomy."

Filter by Rating is gone from that sentence, and the "non-product blocks" vagueness is resolved — two issues addressed in one clean rewrite. ✅

🟡 Table separator alignment (WOOCOMMERCE.md lines 22–28) — Column widths are now consistent across the header, separator, and all five data rows. ✅

🟡 Double blank lines before ## See also — Collapsed to a single blank line in all five WC READMEs:

• filter-wc-attribute/README.md L68–69 ✅
• filter-wc-price/README.md L84–85 ✅
• filter-wc-rating/README.md L58–59 ✅
• filter-wc-stock-status/README.md L44–45 ✅
• filters-product/README.md L58–59 ✅

Suggestion: cross-links in Checkbox Filter tips (WOOCOMMERCE.md line 66) — All three now linked:

"All three pair naturally with Filter by Price, Filter by Rating, and Filter by Stock Status inside a Product Filters container." ✅

Suggestion: clarify parenthetical — Folded into the factual-error rewrite above. ✅

---

No remaining issues. This doc set is ready.

[kangzj]

@claude please re-review — two follow-up commits: 5d49399 (hub-doc nits from your prior review) and 7371c6f (split the Checkbox Filter WC variations into per-variation entries per a separate ask from the PR owner).

[claude]

Claude finished @kangzj's task in 1m 50s —— View job

---

Re-review of follow-up commits 5d49399 + 7371c6f

• Read WOOCOMMERCE.md (current state after both commits)
• Verify 5d49399 nits (quick confirmation pass)
• Review 7371c6f — Checkbox Filter WC variations split into per-variation entries
• Check prose quality, accuracy, cross-links, US English
• Post verdict

---

5d49399 — hub-doc nits (quick confirm)

Carrying over the prior endorsement — all five items from that round are correctly applied in the current file. No regressions introduced by 7371c6f.

---

7371c6f — Checkbox Filter WC variations split

The restructuring is well-executed. Three per-variation entries (Filter by Product Category, Filter by Product Tag, Filter by Product Brand) each get their own when-to-use, editor preview, and tips, while a single ### Shared settings inspector subsection covers the common inspector UI once with a full settings table. That's the right DRY trade-off — readers who pick one variation get specific guidance without wading through the other two.

The two new screenshots (filter-checkbox-product-tag.png, filter-checkbox-product-brand.png) slot in cleanly and the alt text is accurate.

The [Shared settings inspector](#shared-settings-inspector) anchor resolves correctly against the ### Shared settings inspector heading (GitHub lowercases and hyphenates as #shared-settings-inspector). ✅

---

One factual issue

Admin path for Product Brand — WOOCOMMERCE.md line 80

If you don't see it, open WooCommerce → Products → Brands in your admin and create one

Products is a top-level WordPress admin menu item, not a submenu of WooCommerce. The correct path is:

Products → Brands

The WooCommerce prefix implies a three-level nested nav that doesn't exist in the standard WordPress admin — WooCommerce → takes you to Orders, Customers, Settings, etc., not the Products post-type menus. The product_brand taxonomy page lives at Products → Brands in the WP admin sidebar.

Fix this →

---

Minor nit (cosmetic)

The repeated "Pair with…" tip at the end of each variation's Tips section is intentionally duplicated for discoverability and that's the right call — readers who land on only one variation get the cross-links without having to find the combined section. No action needed.

---

What's working well

• The per-variation structure mirrors how the blocks actually present in the inserter — three distinct cards for Category, Tag, Brand. Much clearer than the old combined section.
• The ### Shared settings inspector as a fourth sub-section is a clean way to avoid repeating the full settings table three times.
• The settings table in the shared inspector section is expanded (7 rows vs. 4 in the old version) and now covers Show result counts, Sort order, and Logic — the previously missing entries.
• The tips for each variation are variation-specific: Category gets the chip/hierarchy note, Tag gets the "use sparingly" conversion note, Brand gets the placement-below-category advice. None feel copy-pasted.
• Brand availability prerequisite note is in the right place (under "When to use it") — it's a pre-condition, not a setting.

---

One fix required (the WooCommerce → prefix on the admin path). Everything else is solid.

[kangzj]

Thanks @claude — fixed the admin-path error in e56371c.

• 🔴 WOOCOMMERCE.md line 80 — Changed "WooCommerce → Products → Brands" to "Products → Brands" (Products is a top-level WordPress admin menu, not a submenu of WooCommerce).
• I also caught the same mistake in filter-wc-attribute/README.md line 19 — fixed "WooCommerce → Products → Attributes" to "Products → Attributes" in the same commit.

The PHP 8.2 CI failure on the previous push was an infra flake (Your github oauth token for github.com contains invalid characters: "***" in the Setup-tools step, before any tests ran). This push re-triggers CI and should land clean.

[kangzj]

@claude please re-review.

[claude]

Claude finished @kangzj's task in 40s —— View job

---

Re-review of commit e56371c8 — admin-path fixes

• Read WOOCOMMERCE.md — verify Products → Brands fix
• Read filter-wc-attribute/README.md — verify Products → Attributes fix
• Check remaining READMEs for any similar admin-path issues
• Post verdict

---

Both fixes correctly applied. Verification:

WOOCOMMERCE.md line 80 — Now reads:

"If you don't see it, open Products → Brands in your WordPress admin and create one"

The WooCommerce → prefix is gone. ✅

filter-wc-attribute/README.md line 19 — Now reads:

"Visit Products → Attributes in your WordPress admin to create one"

The WooCommerce → prefix is gone. ✅

Grepped the remaining four WC READMEs (filter-wc-price, filter-wc-rating, filter-wc-stock-status, filters-product) for any surviving WooCommerce → nav references — none found. ✅

---

No remaining issues. The full doc set is ready to merge.

[claude]

Claude finished @kangzj's task in 1m 0s —— View job

---

Re-review of commit e56371c8 — admin-path fix

• Read WOOCOMMERCE.md — verify "Products → Brands" path
• Read filter-wc-attribute/README.md — verify "Products → Attributes" path
• Final pass on full doc set for any remaining issues
• Post verdict

---

Both fixes correctly applied. No new issues.

🔴 WOOCOMMERCE.md line 80 — admin path for Product Brand ✅

"open Products → Brands in your WordPress admin and create one"

The WooCommerce → prefix is gone. Path is correct.

🔴 filter-wc-attribute/README.md line 19 — admin path for Product Attributes ✅

"Visit Products → Attributes in your WordPress admin to create one"

Same fix applied — good catch to apply it here too. Path is correct.

---

Full doc set — final state

All prior fixes across the six review rounds are intact:

• US English throughout (flavors, recognizable, Customize, favor) ✅
• WOOCOMMERCE.md inserter paragraph: Filter by Rating correctly removed from the "without WooCommerce" description ✅
• Table separator alignment in WOOCOMMERCE.md ✅
• Cross-links in Checkbox Filter tips (Price, Rating, Stock Status) ✅
• Single blank line before all ## See also sections across all five WC READMEs ✅
• filters-product/README.md: six unresolvable links correctly converted to plain bold text; five intra-PR WC links remain as working markdown links ✅
• Label example in filter-wc-attribute/README.md: "Material" → "Made from" ✅
• Per-variation Checkbox Filter structure in WOOCOMMERCE.md: Category / Tag / Brand each have their own when-to-use and tips; shared settings table appears once ✅

No remaining issues. This doc set is ready to merge.