search-result

Imported from vtex-apps/search-result (AGENTS.md). Install upstream with npx skills add vtex-apps/search-result. Copyright stays with the author.

AGENTS.md — search-result

Repository Purpose

vtex.search-result is a VTEX IO Store Framework app (builders: react, messages, store, docs) that exports the PLP (Product Listing Page) blocks for VTEX storefronts: galleries, filter navigators, sort controls, layout switchers, pagination ("fetch more"/"fetch previous"), and search-context primitives.

It is the storefront consumer of the GraphQL surface published by vtex.search-graphql (resolved by vtex.search-resolver) and coordinates with vtex.delivery-promise-components for pickup-point shipping facets on PLP (shared localStorage['vtex.search.pickupInPoint'] key).

Where it sits in the IS topology

Sources of Truth

Architecture

Storefront route renders <search-result>
    │
    ├─► SearchResultContainer
    │      ├─ LocalQuery (when no parent layout provides data)
    │      │     └─ Apollo query against vtex.store-graphql / vtex.search-graphql
    │      └─ SearchPageContext provider (from vtex.search-page-context)
    │
    └─► child blocks composed in store/blocks.json
           ├─ <filter-navigator>      → FilterNavigatorLegacy | FilterNavigator | FilterNavigatorFlexible
           ├─ <gallery>               → Gallery | GalleryLegacy → uses <product-summary> (vtex.product-summary)
           ├─ <gallery-layout-switcher> → GalleryLayoutSwitcher (composition: children)
           ├─ <gallery-layout-option>   → GalleryLayoutOption  (composition: children)
           ├─ <order-by>              → OrderBy | OrderByFlexible
           ├─ <total-products>        → TotalProducts | TotalProductsFlexible
           ├─ <search-title>          → SearchTitle | SearchTitleFlexible
           ├─ <not-found>             → NotFoundSearch (allowed: shelf)
           ├─ <search-fetch-more>     → FetchMore
           ├─ <search-fetch-previous> → FetchPrevious
           └─ <search-products-progress-bar> → ProductsProgressBar

FilterNavigator family

Three implementations coexist for migration:

The v2 component is the active development target. Legacy variants are maintained for backwards compatibility — do not refactor them without explicit cross-team coordination.

Shared state with vtex.delivery-promise-components

This app reads localStorage['vtex.search.pickupInPoint'] to scope PLP filtering by the shopper's selected pickup point. The key is owned by vtex.delivery-promise-components (see its react/pickupInPointPreference.ts). Format:

{ id: string, friendlyName: string, address: string, postalCode: string }

vtex.delivery-promise-components invalidates this when the stored postalCode differs from the current session.

Verified Commands

make dev          # yarn install (root + react) + vtex setup
make lint         # eslint (no --fix)
make test         # cd react && yarn test (vtex-test-tools)
make coverage     # cd react && yarn test --coverage (60% threshold via react/package.json jest key)
make check        # lint + test (pre-PR gate)
make link         # vtex link (uses active VTEX account/workspace)
make run          # alias for make link

Root yarn scripts: yarn lint, yarn format, yarn test.

CI

.github/workflows/pull-request.yml triggers on PRs targeting master. It runs three jobs:

1. danger-ci — vtex/danger enforces changelog and PR conventions.
2. io-app-test — vtex/action-io-app-test runs vtex-test-tools in the react builder.
3. lint — vtex/action-lint runs the linter.

Node 12 is still the CI target. The dependency tree (TypeScript 3.7, @types/node 13, jsdom 16, jest-environment-jsdom 26) is locked to that era. A future runtime bump should be a dedicated PR — golden-path keeps Node 12 here on purpose.

Expected Skills

• vtex-io-cli · vtex-io-app-structure · vtex-io-react-apps · vtex-store-framework-navigator
• specification + implementing (vtex-agent-skills) for SDD Lite
• For SDD Full work, use the spec-kit pipeline against the parent Specs repo

Expected MCPs

• GitHub MCP — cross-repo references (especially vtex.search-graphql, vtex.search-resolver, vtex.delivery-promise-components, vtex.product-summary).
• Atlassian MCP — Jira/Confluence context.
• Consider Playwright / vtex-qa for E2E generation against PLP blocks.

Multi-repo Specs

Part of the is-io-specs multi-repo workspace. SpecKit artifacts live at the parent aggregator (is-io-specs/.specify/, is-io-specs/specs/). This repo intentionally has no local .specify/. See the Multi-repo spec-kit extension.

Autonomy Limits

Toolbelt and platform

• Never run vtex link, vtex publish, vtex deploy, workspace promotion, or any account/workspace-changing Toolbelt command without explicit confirmation.
• Ask before running vtex setup --tooling — this repo uses eslint-config-vtex@^12 + eslint-config-vtex-react@^6 with custom rules in .eslintrc; vtex setup --tooling could overwrite them.
• Never modify manifest.json version directly — use vtex release <patch|minor|major> stable.
• Never modify react/typings/ — regenerated by vtex setup --typings --ignore-linked.
• Note: manifest.json:scripts.postreleasy: "vtex publish --verbose" means a successful vtex release automatically publishes. This is part of the team's release flow but worth flagging in any release-related PR.

Block contract

• Never remove a block name from store/interfaces.json without a coordinated deprecation cycle — themes in production rely on block names being stable.
• Adding allowed children to an existing block is safe.
• Removing required children is breaking — themes may stop rendering correctly.
• The filter-navigator (unversioned) alias still resolves to FilterNavigatorLegacy. Changing that mapping is a stealth breaking change for any theme that uses the unversioned name. Always change .v1 / .v2 explicitly.

React component constraints

• Three FilterNavigator implementations coexist by design — FilterNavigator (v2, active), FilterNavigatorLegacy (compat), FilterNavigatorFlexible (flex-layout). Do not collapse them without explicit cross-team coordination.
• The repo mixes .js, .ts, .tsx. New files should be .tsx (with proper TypeScript types). Avoid migrating legacy .js files in passing — keep the migration deliberate.
• CSS handles are exposed via vtex.css-handles. Adding handles is safe; renaming or removing them is a breaking theme change.

Storage and analytics

• localStorage['vtex.search.pickupInPoint'] is owned by vtex.delivery-promise-components, not this repo. Read it; do not write it.
• Pixel events are emitted via vtex.pixel-manager. Adding new events is safe; renaming or removing existing ones breaks analytics dashboards.

Branch / release flow

• Current default branch is master (not yet migrated to main). PR workflow triggers on master. Confirm before any branch rename.
• vtex release patch stable (or minor/major) creates the tag; postreleasy then publishes.

Test maintenance

• New tests go in react/__tests__/ using vtex-test-tools. Coverage threshold (60%) is declared under the jest key in react/package.json.
• The legacy mocks live in react/__mocks__/. Prefer jest.mock() at the test level for new fixtures.