refactor(google-maps)!: deprecate top-level center/zoom props

[harlan-zw]

🔗 Linked issue

Related to #689 (PR B in the umbrella split-up plan).

❓ Type of change

• 📖 Documentation
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

Marks <ScriptGoogleMaps>'s top-level center and zoom props as deprecated. Both APIs keep working; the legacy form emits a dev-mode console warning pointing at mapOptions and the v0→v1 migration page. This is the first step towards consolidating map configuration on a single, idiomatic API surface.

⚠️ Breaking Changes

mapOptions.center and mapOptions.zoom now take precedence over the deprecated top-level props when both are set. Previously the top-level props won (the JSDoc on zoom claimed precedence and defu ordering matched).

The new precedence order in the options computed is:

1. centerOverride (resolved location query) — always wins for center
2. mapOptions — preferred public API
3. Deprecated top-level center / zoom — legacy fallback
4. Defaults — { zoom: 15 }

If a user was setting both :center and :map-options="{ center: ... }", the resolved center will change. This combination is not documented and is unusual; the warning surfaces the conflict.

📝 Migration

-<ScriptGoogleMaps :center="{ lat, lng }" :zoom="12" />
+<ScriptGoogleMaps :map-options="{ center: { lat, lng }, zoom: 12 }" />

🛡 Protected behaviours

• Skip-if-equal setCenter watcher: untouched
• setOptions exclusion of zoom/center: untouched
• centerOverride flow for location-query strings: untouched
• InfoWindow group close, overlay data-state: untouched

🧪 Tests

Extracted warnDeprecatedTopLevelMapProps into useGoogleMapsResource so the dev-warning behaviour is unit-testable without mounting the SFC. Added 12 unit tests in test/unit/google-maps-components.test.ts:

• Warns for top-level center, top-level zoom, both, neither, explicit-undefined
• mapOptions.center wins over deprecated top-level center
• mapOptions.zoom wins over deprecated top-level zoom
• Top-level props are used when mapOptions lacks the corresponding key
• Old and new APIs produce identical merged options when set in isolation
• Default zoom: 15 fallback when nothing is set
• centerOverride (resolved query) wins over both APIs

All 75 google-maps-* unit tests pass; lint and typecheck clean.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
scripts-playground	Ready	Preview, Comment	Apr 9, 2026 1:21pm

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/scripts@694

commit: bd5136e

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR deprecates the top-level center and zoom props on the <ScriptGoogleMaps> component in favor of passing these values through the map-options prop. The implementation adds TypeScript deprecation annotations, a dev-mode warning utility, and reorders the option merge logic to enforce map-options precedence over the legacy top-level props. Documentation and unit tests are updated to describe the deprecation pathway and validate the new precedence behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: deprecating top-level center/zoom props on ScriptGoogleMaps, which is the primary objective of the changeset.
Description check	✅ Passed	The description provides comprehensive detail about the deprecation, breaking changes, migration guidance, protected behaviors, and test coverage—all directly related to the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 refactor/google-maps-deprecate-top-level-center-zoom

---

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 and usage tips.}