feat(vtex): make hideUnavailableItems configurable at app level

[guitavano]

Problema

Para esconder produtos indisponíveis (out of stock) a única opção era setar a prop hideUnavailableItems em cada página/loader. Isso não escala: toda página nova criada volta ao comportamento padrão (false), então itens sem estoque reaparecem até alguém lembrar de setar a prop de novo.

Solução

Torna hideUnavailableItems configurável no nível do app VTEX (vtex/mod.ts), usado como fallback padrão em todos os loaders relevantes. A prop por página continua funcionando e tem prioridade.

Precedência: prop do loader > config do app > false

Como state = { ...props } no app VTEX, o valor fica disponível como ctx.hideUnavailableItems.

Loaders ajustados (fallback para ctx.hideUnavailableItems)

• intelligentSearch/productListingPage.ts — PLP (searchArgsOf + cacheKey)
• intelligentSearch/productList.ts — prateleiras/shelves (fromProps + getSearchParams/cacheKey)
• legacy/relatedProductsLoader.ts — produtos relacionados (loader + cacheKey)

O valor do ctx foi incluído nos cacheKey para evitar colisão de cache quando a config muda.

Como usar (ex.: Osklen)

Ligar o toggle Hide Unavailable Items na config do app VTEX. Todas as páginas — inclusive as novas — passam a esconder itens sem estoque por padrão, sem editar página por página.

Notas

• Não afeta a PLP legada (loaders/legacy/productListingPage.ts), que usa a API antiga (fq) e não consome esse parâmetro.
• deno check limpo nos arquivos alterados (o único erro do typecheck é pré-existente em website/utils/crypto.ts, não tocado neste PR).

🤖 Generated with Claude Code

---

Summary by cubic

Adds an app-level default to hide out-of-stock items for VTEX, now stored at advancedConfigs.hideUnavailableItems. Search, shelves, and listings use this as a fallback to cut per-page flags and keep new pages consistent.

• New Features

  • Added advancedConfigs.hideUnavailableItems?: boolean in vtex/mod.ts; precedence: loader prop > app config > false.
  • Loaders now read ctx.advancedConfigs?.hideUnavailableItems: intelligentSearch/productListingPage.ts, intelligentSearch/productList.ts, and legacy/relatedProductsLoader.ts.
  • Included this value in cache keys to avoid collisions when the config changes.

• Migration

  • In the VTEX app config, under Advanced Configs, toggle “Hide Unavailable Items” to set the store-wide default.
  • Override per page/loader with the hideUnavailableItems prop when needed.

^{Written for commit dd74cc5. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added a global option to hide unavailable products across search results, product shelves, and listing pages.
  • Individual components can override the global setting when needed.

• Bug Fixes

  • Product availability filtering now consistently respects configured defaults.
  • Updated caching to distinguish results based on availability settings.

[github-actions]

Tagging Options

Should a new tag be published when this PR is merged?

• 👍 for Patch 0.159.8 update
• 🎉 for Minor 0.160.0 update
• 🚀 for Major 1.0.0 update

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

hideUnavailableItems is added to shared VTEX props. Product-list, listing-page, and related-product loaders now fall back to ctx.hideUnavailableItems when the prop is unset, and cache keys reflect the resolved value.

Unavailable-item filtering

Layer / File(s)	Summary
Shared configuration and product-list resolution vtex/mod.ts, vtex/loaders/intelligentSearch/productList.ts	Adds the shared hideUnavailableItems prop and applies context-aware resolution across product-list search shapes and cache parameters.
Product-listing resolution and caching vtex/loaders/intelligentSearch/productListingPage.ts	Passes context into search argument construction and includes the fallback value in cache keys.
Related-products filtering and caching vtex/loaders/legacy/relatedProductsLoader.ts	Uses context-aware filtering and cache-key parameter construction for related products.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• deco-cx/apps#1540: Updates related-products invocation through ctx.invoke, exercising the changed context fallback.
• deco-cx/apps#1559: Changes related-products call paths while this PR updates its filtering and cache-key logic.
• deco-cx/apps#1637: Calls productList with hideUnavailableItems: true, intersecting with this PR’s product-list resolution changes.

Suggested reviewers: mcandeia

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: making hideUnavailableItems configurable at app level.
Description check	✅ Passed	The description explains the change well, but it omits the template's Issue Link, Loom Video, and Demonstration Link sections.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/vtex-hide-unavailable-app-config

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

1 issue found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="vtex/loaders/intelligentSearch/productList.ts">

<violation number="1" location="vtex/loaders/intelligentSearch/productList.ts:160">
P2: Product-ID shelves can return a cached result with the wrong stock filtering after the app toggle changes, because their new effective `hideUnavailableItems` value is not represented in `cacheKey`. Include the resolved boolean for `isProductIDList(props)` too.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Product-ID shelves can return a cached result with the wrong stock filtering after the app toggle changes, because their new effective hideUnavailableItems value is not represented in cacheKey. Include the resolved boolean for isProductIDList(props) too.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At vtex/loaders/intelligentSearch/productList.ts, line 160:

<comment>Product-ID shelves can return a cached result with the wrong stock filtering after the app toggle changes, because their new effective `hideUnavailableItems` value is not represented in `cacheKey`. Include the resolved boolean for `isProductIDList(props)` too.</comment>

<file context>
@@ -147,14 +147,17 @@ const isQueryList = (p: any): p is QueryProps =>
       sort: props.sort || "",
       selectedFacets: [{ key: "", value: props.facets }],
-      hideUnavailableItems: props.hideUnavailableItems,
+      hideUnavailableItems: hideUnavailableItems(props),
       simulationBehavior: props.simulationBehavior || "default",
     } as const;
</file context>