feat(premium-analytics): port layout package from next-woocommerce-analytics

[chihsuan]

Proposed changes

Second leaf in M2 — Shared Packages Integration (WOOA7S-1315): port @next-woo-analytics/layout into @automattic/jetpack-premium-analytics as an internal package. Provides a single BaseLayout primitive — a vertical @wordpress/ui Stack with a header slot above the children — used by analytics routes to keep page chrome consistent.

A true leaf — no internal deps, only @wordpress/ui. Stacked on #49189 (which sets up the @jetpack-premium-analytics/* tsconfig paths alias this work relies on). Sibling to #49221 (datetime port); the two don't touch the same files.

What's in the package

File	Purpose
src/base/base.tsx	BaseLayout component — Stack gap="lg" direction="column" with header + children slots
src/base/index.ts, src/index.ts	barrel exports
README.md	usage + props reference (new — upstream had none)

Monorepo adaptations

Upstream	Here	Why
name: @next-woo-analytics/layout	name: @automattic/jetpack-premium-analytics-layout	Per the internal-packages convention in the parent README.md — the import specifier (@jetpack-premium-analytics/layout) comes from wpPlugin.packageNamespace; the name: field is separate and must use the @automattic/... form
version: 1.0.0	version: 0.1.0	Matches the datetime port and sibling packages/init/
@wordpress/ui: "*"	@wordpress/ui: 0.13.0	Jetpack convention — every other package pins concrete versions; the repo also sets minimumReleaseAge: 1440 which conflicts with "*"
@automattic/ui: "*", @wordpress/components: "*"	(dropped)	Declared upstream but never imported — only Stack from @wordpress/ui is used
wpModule: true, exports: { ./build/src/index.js }	wpScript: true, module: "build-module/index.mjs", wpScriptModuleExports: "./build-module/index.mjs"	Upstream wpModule: true told CIAB's wp-build to emit a standalone script module (build/packages/layout/index.js + index.asset.php). @wordpress/build's dependency-graph.mjs uses wpScript / wpScriptModuleExports for the same role; sibling packages/init/ follows the same triple. Without these the package would be inlined into every consumer instead of loaded once via the script-module registry — same as upstream behavior
Leaf tsconfig.json	(deleted)	Parent already includes: [packages/**/*]; sibling packages/init/ and the datetime port carry no leaf tsconfig either
header: React.ReactNode (global namespace)	import type { ReactNode } from 'react'; header: ReactNode	tsgo doesn't have a global React in scope under this package's config (TS2503: Cannot find namespace 'React'); behaviorally identical
No README	New README	Documents the only export, its props, and the @wordpress/ui Stack dependency — mirrors the datetime README style

Two structural files touched at the parent level:

• package.json: adds @wordpress/ui: 0.13.0 so the leaf's Stack import resolves. packages/layout/ is not a pnpm workspace member (the root pnpm-workspace.yaml glob projects/*/* doesn't reach in two levels), so the leaf's own dep declarations are decorative — only the parent's matter to pnpm. Same pattern as the datetime port adds date-fns / @date-fns/tz here.
• eslint.config.mjs (new — temporary): softens jsdoc/require-* for packages/layout/** so the initial port can land with the upstream JSDoc style. Mirrors the override feat(premium-analytics): port datetime package from next-woocommerce-analytics #49221 introduced for packages/datetime/**. Backfill proper JSDoc on BaseLayout and delete this config file entirely in a follow-up.

What's intentionally not here

• No link: dep on the parent yet. The parent README documents the pattern (@jetpack-premium-analytics/layout: link:packages/layout), but eslint-plugin-package-json's valid-dependencies rule rejects link: URLs by default. Since no route or sibling package imports layout yet, the wiring isn't load-bearing — wp-build's packages/* autodiscovery is enough for the package to exist. The first consumer PR will need to resolve the lint conflict (same blocker the datetime port called out).
• No tests. The upstream package ships no tests; not adding speculative ones here.
• No JSDoc backfill. Out of scope for the port commit — tracked by the comment in eslint.config.mjs.

Related product discussion/links

• WOOA7S-1315
• Stacked on feat(premium-analytics): resolve internal packages for build and types #49189 (WOOA7S-1320)
• Sibling port: feat(premium-analytics): port datetime package from next-woocommerce-analytics #49221 (datetime, WOOA7S-1312) — same conventions, but datetime is bundled (no wpScript) while layout is a script module (wpScript: true), matching each upstream package's role

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Requires Node 24 (repo engineStrict).

pnpm install
cd projects/packages/premium-analytics
pnpm typecheck   # tsgo --noEmit — passes
pnpm build       # wp-build — passes (~300ms); emits build/modules/layout/index.min.{js,asset.php}
pnpm exec eslint --flag v10_config_lookup_from_file --max-warnings=0 packages/layout/   # clean

Confirm the script module is registered:

grep -A2 '@jetpack-premium-analytics/layout' build/modules/registry.php
# →   'id' => '@jetpack-premium-analytics/layout',
#     'path' => 'layout/index',
#     'asset' => 'layout/index.min.asset.php',

Optional smoke import, to confirm the path alias works through the typechecker:

1. Edit routes/dashboard/stage.tsx:

   import { BaseLayout } from '@jetpack-premium-analytics/layout';
   void BaseLayout;

2. pnpm typecheck — resolves and passes.
3. Revert the edit.

Optional — build-time resolution via link: (confirms wp-build tracks the package as a module dependency once a consumer imports it):

1. Add to projects/packages/premium-analytics/package.json dependencies: "@jetpack-premium-analytics/layout": "link:packages/layout" (the valid-dependencies lint rejects link: — relax it for the temp edit).
2. Import + reference a layout export in routes/dashboard/stage.tsx.
3. pnpm install && pnpm build → build/routes/dashboard/content.min.asset.php lists the dependency under module_dependencies.
4. Revert the edits + pnpm install.

Note: the @jetpack-premium-analytics/layout specifier is a temporary bridge inherited from the source repo. Once name-based identity (WordPress/gutenberg#78822, mirrored monorepo-wide by #48089) lands, the specifier becomes the package's own name (@automattic/jetpack-premium-analytics-layout) and the bare-scope alias/link: drop out — so long term there's no @jetpack-premium-analytics/... to maintain. The package README already uses the canonical @automattic/jetpack-premium-analytics-layout name.

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the wooa7s-1315-integrate-layout-package-into-analytics branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack wooa7s-1315-integrate-layout-package-into-analytics

bin/jetpack-downloader test jetpack-mu-wpcom-plugin wooa7s-1315-integrate-layout-package-into-analytics

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• 🔴 Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[jp-launch-control]

Code Coverage Summary

No summary data is available for parent commit d4da9ca, so cannot calculate coverage changes. 😴

If that commit is a feature branch rather than a trunk commit, this is expected. Otherwise, this should be updated once coverage for d4da9ca is available.

Full summary · PHP report · JS report

[simison]

Have you looked if Admin UI package's Page component would work for you?

[chihsuan]

Have you looked if Admin UI package's Page component would work for you?

No, but I just found that this package is not actually used so we don't really need it. I'll close this PR.