feat: support seo url route names of headless sales channels

[Mateusz Flasiński (mateuszfl)]

Description

Since shopware/shopware#17991 (upcoming 6.7.14), headless (API type) sales channels persist their SEO URLs against the store-api.* route family: store-api.product.detail, store-api.category.detail and store-api.landing-page.detail. The /store-api/seo-url endpoint returns those rows as-is, so on a headless sales channel resolvePath() hands a store-api.* route name to the page resolver, pascalCase() turns it into StoreApiProductDetail, and the catch-all page fails with Problem resolving component: StoreApiProductDetail.

This PR maps the headless route names to their storefront equivalents at the resolution boundary:

• new getFrontendRouteName helper in @shopware/helpers (store-api.product.detail → frontend.detail.page etc.; any other route name passes through unchanged),
• useNavigationSearch().resolvePath() normalizes the route name of the resolved SeoUrl entity,
• a note in the routing guide.

Everything downstream — the catch-all page resolver, useNavigationContext, CMS page rendering, history-state navigation — keeps working unchanged for both sales channel types.

This is part of finishing headless sales channel support for Composable Frontends: relates to shopware/shopware#19685 (core-side PRs: shopware/shopware#19686, shopware/shopware#19688). The end goal is dropping the "use the Storefront type" workaround from the troubleshooting guide.

Type of change

New feature (non-breaking change which adds functionality)

ToDo's

• Changeset file provided read more
• Documentation added/updated
• Unit-Tests added/updated
• Update the sales-channel-type troubleshooting entry once the core-side PRs are merged and released

Additional context

The mapping is inert on Storefront-type channels and on Shopware < 6.7.14 (no store-api.* rows exist there), so the change is safe to merge independently of the core PRs — opening as a draft anyway until the core side settles.

Two things intentionally left out to keep this minimal, happy to follow up if wanted:

• Technical-path entry URLs (/detail/{id}) don't get a canonical 301 redirect on headless channels, because the persisted pathInfo is /store-api/product/{id} and the pathInfo lookup misses. The synthetic fallback still renders the page correctly.
• The generated SeoUrl.routeName type union in storeApiTypes.d.ts doesn't include the store-api.* values; that mirrors the core OpenAPI schema, so it likely deserves a core-side schema fix rather than a hand edit here.

Open question on the mapping direction. Mapping store-api.* onto frontend.* is a deliberate compatibility choice, not a statement that the storefront names are the "right" ones: frontend.* is what the page-resolver component names (FrontendDetailPage & co.), the routing guide's switch examples, and getProductRoute/getCategoryRoute history state are all built on, in this repo and in every downstream project. Long term — once headless sales channels are the recommended setup — it may be worth flipping the canonical vocabulary: treat store-api.* (or better, an abstract page type like product/category/landing, as already hinted at in composables/src/types/index.ts) as the primary identifier and keep frontend.* as the legacy alias for Storefront-type channels. That's a breaking, major-version decision that affects template component naming, so this PR only introduces the boundary normalization that would make such a flip a one-map change later. Happy to draft that follow-up if the team wants to go there.

[vercel]

Mateusz Flasiński (@mateuszfl) is attempting to deploy a commit to the Shopware Frontends Team on Vercel.

A member of the Team first needs to authorize it.