Social: modernize into a unified wp-admin product (five-PR sequence)

[keoshi]

Goal

Modernize Jetpack Social into a unified wp-admin product with two tabs:

1. Overview (default) — connect/manage social accounts: the existing connection list and "Add account" flow lifted into a WPDS Card surface. A "Traffic from social media" line chart lands as PR 4 before the flip.
2. Settings — every customization control currently on the Social admin page, ported onto WPDS Card primitives and grouped to match the design (Content creation / Customize links / Customize media).

Product visibility is owned by the wp-admin module-toggles surface (the "Social" module card with the Active toggle), so the in-product master Publicize toggle on the legacy admin page goes away — no in-tab on/off switch. After this work the current SocialAdminPage shell (single-page Header + AdminSection layout) retires. The connection screen and the free-plan pricing page keep pre-empting the tabs the same way they pre-empt the dashboard today. The block-editor publicize panel, post-publish flows, and share-status views are untouched.

This umbrella adapts the cadence used for the Boost modernization umbrella (#48717), itself a compression of the Newsletter modernization umbrella (#48530).

Approach

Five small, self-contained PRs. Each builds on the previous one. Everything from PR 1 onward is gated behind a feature filter (rsm_jetpack_ui_modernization_social) — the legacy Social admin page renders unchanged unless a site explicitly opts in. The final PR flips the default and retires the legacy surface.

PRs

• PR 1 — wp-build scaffold + Page/router shell + tabs UI behind feature flag. Add wp-build alongside webpack in projects/packages/publicize/; introduce rsm_jetpack_ui_modernization_social filter + helpers on Social_Admin_Page; branched menu render; legacy enqueue short-circuit; Page from @wordpress/admin-ui + QueryClientProvider; @wordpress/route driving ?tab=; persistent Tabs.Root from @wordpress/ui with Overview (default) and Settings. Both tabs render placeholders. No connections, no toggles, no chart yet. — Social: scaffold the wp-build dashboard chassis behind the modernization flag (PR 1 / #48824) #48826 (7ecbfd8)

• PR 2 — Overview tab behind flag. "Add account" as a page-header action (lifts openConnectionsModal out of the existing connection-management component). A WPDS Card.Root wrapping the existing ConnectionManagement list — re-uses components/connection-management/, components/manage-connections-modal/, components/services/ unchanged. Connection-error notice + JITM mount-point preserved above the card. — Social: build the Overview tab on the modernization chassis (PR 2 / #48824) #48829 (9c722d9)

• PR 2.5 — Modal + connected-accounts WPDS refresh. Closes the deferred "Per-account inline disclosure rows" item below. Both the chassis Overview connected-accounts card and the shared Add-account modal switch to a single flat-row Collapsible.Trigger disclosure pattern inside one outer Card.Root. Mastodon/Bluesky custom inputs move to __experimentalInputControl; IconTooltip → WPDS Tooltip with Tooltip.Provider delay={0} mounted at both surfaces. ConnectionIcon grows a size="medium" variant; Disconnect button → size="compact" tone="neutral". SCSS pass swaps hard-coded values for --wpds-dimension-* / --wpds-typography-* / --wpds-color-fg-content-neutral-weak tokens. Message Templates interaction: ConnectionTemplateEditor is already mounted inside both ConnectionInfo (Overview disclosure panel) and ServiceConnectionInfo (Add-account modal disclosure panel) — no code change required here. The editor is gated on social-message-templates (WPCOM blog sticker) AND social-enhanced-publishing (paid plan), so validating the visual integration needs a stickered + paid-plan site (free-plan JN sites with only the sticker render nothing). — Social: modernize Add-account modal + connected-accounts onto WPDS (#48824 PR 2.5) #48833

• PR 3 — Settings tab behind flag. Port the three remaining toggles onto Card.Root / Card.Header / Card.Title / Card.Content from @wordpress/ui, grouped to match the design:

  • Content creation — SocialNotesToggle (plugin-only) with the existing "Create note" action.
  • Customize links — UtmToggle.
  • Customize media — SocialImageGeneratorToggle (paid) with the existing "Change defaults" action.
  • Default share message — mount MessageTemplateSection (the global message-template editor currently rendered inside the legacy SocialModuleToggle). It self-gates on siteHasFeature('social-message-templates') + manage_options, so stickerless sites just don't see the card; no extra branching needed in the chassis. This re-homes the surface that's lost when SocialModuleToggle retires.

  The legacy SocialModuleToggle (master Publicize on/off) is not ported — product visibility is owned by the wp-admin module-toggles surface. If an admin reaches the page while Publicize is inactive, render a thin empty state pointing back at the module toggles. Source of truth for Settings scope = current code (_inc/components/admin-page/toggles/ + _inc/components/admin-page/message-template-section/) minus the master toggle, grouped by the categories shown in the design. — Social: Settings tab on the modernization chassis (#48824 PR 3) #48860

• PR 4 — Overview traffic chart behind flag. A "Traffic from social media" line chart card on Overview (above the accounts list), with a 7/30/90-day range Select. Data path: WPCOM_Stats::get_referrers() (existing stats package) bucketed by social-network host. The chart shows every matched social referrer (not only Publicize-connected services) so non-connected networks surface as a discovery cue. Free-plan sites get a locked dummy + WPDS Notice upgrade overlay, mirroring Boost's Historical-performance paywall pattern. Rendered with @automattic/charts for visual parity. — Social: Traffic-from-social-media chart on the Overview tab (#48824 PR 4) #48863

• PR 5 — Retire the modernization gate + legacy SocialAdminPage. Removed the rsm_jetpack_ui_modernization_social filter and the legacy single-page SocialAdminPage shell (Header, AdminSection toggle bank, InfoSection, the MessageTemplateSection wrapper, and their tests). The chassis owns both tab routes by default. jetpack_social_tab_view Tracks event lives in the chassis stage. Slight deviation from the original spec: kept the social-admin-page webpack entry slim — it now renders only the ConnectionScreen / PricingPage pre-empt surfaces, which still pre-empt at the PHP layer to keep the chassis bundle free of jetpack-connection's disconnect-dialog asset imports. The three editor entries (block-editor-jetpack, block-editor-social, classic-editor) ship unchanged. — Social: default modernized dashboard on; keep filter + legacy shell as kill switch (#48824 PR 5) #48867

Test plan (per PR)

• Hard-reload wp-admin/admin.php?page=jetpack-social with the filter OFF — legacy Social admin page is unchanged at every step.
• Add add_filter( 'rsm_jetpack_ui_modernization_social', '__return_true' ); and reload — the new chassis renders, growing in capability PR-by-PR.
• Toggle the filter back off — legacy returns immediately, no cache clears needed.
• Verify both ConnectionScreen (site not connected) and PricingPage (free Jetpack, not dismissed) still pre-empt the tabs.
• Verify the wp-admin Social module toggle (the module-toggles surface) still hides/shows the menu item correctly with the chassis enabled.
• PR 5 removes the gate entirely and the legacy surface; the test plan there is the smoke test for the unified product.

Architecture decisions

• Where it lives. The chassis lives in projects/packages/publicize/ (same package the legacy admin page lives in today). Menu slug remains jetpack-social.
• Scaffolding source of truth. wp-build pipeline (alongside webpack throughout the umbrella); Page from @wordpress/admin-ui; @wordpress/route for tabs; React Query; WP_Build_Polyfills; the boot-layout stage / inspector pattern.
• Webpack stays in the package after PR 5. The publicize webpack config builds four entry points: social-admin-page (our chassis target), block-editor-jetpack, block-editor-social, and classic-editor. PR 5 drops only the social-admin-page entry; the three editor entries continue to ship from webpack because they run inside the post editor and are out of scope for this umbrella. This is not the dual-bundle situation Boost has (Boost mounts legacy webpack code inside the chassis tab because Critical CSS generator needs Node polyfills esbuild can't provide) — here the chassis is fully wp-build, webpack just sticks around for unrelated editor bundles. Porting the editor entries to wp-build is a separate future workstream with no user-visible payoff for this work.
• Tabs. Tabs from @wordpress/ui, route-driven via ?tab=, persistent Tabs.Root so the active-tab indicator slides.
• Product visibility owned by module toggles. The master Publicize on/off lives on the wp-admin module-toggles surface, not in the product. The chassis renders no master toggle; admins who reach the page while Publicize is inactive see an empty state pointing at the module toggles.
• Pre-empting states stay pre-empting. ConnectionScreen and PricingPage keep their current "above the tabs" behavior. Adding the upsell inside Overview is deferred.
• Connection list is the existing ConnectionManagement component. Re-used, not rewritten. PR 2 wraps it in a WPDS Card and lifts only the "Add account" button into the page header.
• Settings scope = current code minus the master toggle. Source of truth for what ships in Settings is the three remaining toggles in _inc/components/admin-page/toggles/ (Social Notes, UTM, SIG) plus the MessageTemplateSection from _inc/components/admin-page/message-template-section/, grouped by the categories shown in the design.

Deferred

• Per-account inline disclosure rows (matching the screenshot's chevron-row pattern) — current implementation is an ~~<ul>~~ of ~~ConnectionInfo~~ rows; restyling onto a disclosure pattern is a PR-2 polish or a follow-up. — shipped as PR 2.5 (Social: modernize Add-account modal + connected-accounts onto WPDS (#48824 PR 2.5) #48833).
• Pricing-page-as-inline-Overview-upsell — keep pre-empting today; revisit when the chassis is in.
• My Jetpack Social product card refresh — defer.

Out of scope

• Block-editor publicize panel, classic editor integration, post-publish manual sharing UI, share-status views.
• Social Image Generator template editor — deep link only.
• Restructuring connection / service logic (no behavior changes to Publicize, Connections_Controller, Share_Post_Controller, etc.).
• Migrating REST endpoints.
• Adding new Social features.

References

• Boost modernization umbrella (cadence template, 4-PR sequence): Boost: modernize into a unified wp-admin product (four-PR sequence) #48717
• Boost PR 2 (Overview chart reference): Boost: build the Overview tab on the modernization chassis #48726
• Newsletter modernization umbrella (cadence template, 6-PR sequence): Newsletter: modernize into a unified wp-admin product (six-PR sequence) #48530
• VideoPress wp-build scaffold (PR 1 cadence model): Automattic/jetpack#48494
• Newsletter PR 1 (scaffold reference): Automattic/jetpack#48532
• Newsletter PR 2 (Page shell reference): Automattic/jetpack#48574
• WPDS Card / Tabs: @wordpress/ui
• Message Templates feature work (gated by jetpack-social-message-templates blog sticker; provides MessageTemplateSection and ConnectionTemplateEditor): Social: add global message template editor (SOCIAL-450) #48560 · Social: per-connection message template editor (SOCIAL-451) #48564 · Social: Use message-template placeholder catalogue from WPCOM #48769