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

[chihsuan]

Proposed changes

Second leaf in M2 — Shared Packages Integration (WOOA7S-1311): port @next-woo-analytics/icons into @automattic/jetpack-premium-analytics as an internal package. Provides 13 illustrated WPDS icons (calendar, channel, coupon, customer, device, goal, location, megaphone, payment, payment-return, product-blouse, reports, search). Utility glyphs (dashboard/navigation, settings, plus, info) are imported directly from @wordpress/icons by consumers — the re-exports originally ported here were dropped during review.

A true leaf — no internal deps, only @wordpress/primitives. Stacked on #49189 (which sets up the @jetpack-premium-analytics/* tsconfig paths alias this work relies on); sibling to the datetime port (#49221) and shares its conventions.

What's in the package

File	Purpose
src/index.ts	Barrel — the 13 local illustrated icons
src/<icon>/index.tsx × 13	Branded multi-fill WPDS illustrations (48×48 for most; fills driven by var(--wpds-color-*))
src/stories/icons.stories.tsx	Storybook gallery of every exported icon
README.md	Exports list, WPDS vs @wordpress/icons rationale

Audit vs @wordpress/icons

Per the Linear issue, audited the 13 illustrated icons against @wordpress/icons (tier 1) before porting. Names overlap for calendar, megaphone, payment, search, but upstream ships 24×24 monochrome glyphs designed for fill: currentColor — visually distinct from these multi-fill WPDS illustrations. No swap warranted. The 4 utility icons (dashboard/navigation, settings, plus, info) already come from upstream — initially preserved as re-exports, then dropped during review so the package stays free of upstream names; consumers import them directly from @wordpress/icons.

Monorepo adaptations

Upstream	Here	Why
name: @next-woo-analytics/icons	name: @automattic/jetpack-premium-analytics-icons	Per the internal-packages convention in the parent README.md — the import specifier (@jetpack-premium-analytics/icons) comes from wpPlugin.packageNamespace; the name: field is separate and must use the @automattic/... form
@wordpress/primitives: "*", @wordpress/icons: "*"	@wordpress/primitives: 4.46.0, @wordpress/icons: ^13.0.0	Jetpack convention — every other package pins concrete versions; the repo also sets minimumReleaseAge: 1440 which conflicts with "*"
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/icons/index.js + index.asset.php). @wordpress/build's dependency-graph.mjs has the equivalent triple — wpScript: true + module + wpScriptModuleExports — used by sibling packages/init/. Skipped here because this leaf is consumed inline as TypeScript source (same pattern as the datetime leaf in #49221), not emitted as a separate runtime bundle. Can be promoted to wpScript later if a consumer wants the deduplicated module.
devDependencies: @automattic/design-system	(removed)	Unused — only @wordpress/ui is actually imported by the stories file
Leaf tsconfig.json	(deleted)	Parent already includes: [packages/**/*]; sibling packages/init/ has no leaf tsconfig either
src/stories/icons.stories.tsx title Icons/Gallery	Packages/Premium Analytics/Icons	Jetpack story-tree convention
Stories file imports / component	Drop External/Internal comment separators (Jetpack import/order); add component: Icon to satisfy storybook/csf-component	Lint conventions

Structural changes at the parent level:

• package.json dependencies: add @wordpress/primitives@4.46.0 so the leaf's imports resolve under tsgo and eslint.
• package.json devDependencies: add @wordpress/ui@0.13.0, @storybook/react@10.3.6, plus its peer pins (storybook@10.3.6, typescript@5.9.3, @testing-library/dom@10.4.1) — matching the versions already pinned by projects/packages/videopress and projects/packages/publicize — so fresh CI installs don't ERR_PNPM_PEER_DEP_ISSUES.

packages/icons/ is not a pnpm workspace member (the root pnpm-workspace.yaml glob projects/*/* doesn't reach in two levels), so pnpm only sees the parent. The leaf package.json deps are declared mainly so import/no-extraneous-dependencies finds them. Same reasoning as the datetime port (#49221).

What's intentionally not here

• No link: dep on the parent yet. Same reasoning as the datetime port: eslint-plugin-package-json's valid-dependencies rule rejects link: URLs by default, and no route or sibling package consumes icons yet — wp-build's packages/* autodiscovery is enough.
• No tests. The upstream package ships no tests; not adding speculative ones here.

Storybook integration

The shared Storybook (projects/js-packages/storybook) discovers stories from an explicit project allowlist. This PR registers projects/packages/premium-analytics/packages in storybook/projects.js — so the icons gallery (and any future internal package's stories/) is picked up — and adds a charts-style storybook script to the parent package.json. No extra dependency or build wiring was needed: the shared preview already loads @wordpress/theme/design-tokens.css (the --wpds-* tokens the gallery uses), and Vite resolves imports straight from source via the jetpack:src condition.

Commit structure

Split for reviewability:

1. chore: add @wordpress/primitives dependency — setup so the leaf's imports resolve
2. feat: copy icons sources from next-woocommerce-analytics — verbatim source files (13 icon TSX files + barrel)
3. feat: add icons package manifest — adapted leaf package.json (rename, pin, drop CIAB-isms)
4. docs: add icons README — new for monorepo
5. changelog: add entry
6. feat: restore icons stories with Jetpack adaptations — restore the upstream gallery + wire up @wordpress/ui / @storybook/react devDeps
7. chore: pin @storybook/react peer deps — pin storybook / typescript / @testing-library/dom to satisfy peers on fresh installs
8. feat(premium-analytics): integrate icons stories into shared Storybook — register the internal packages dir in the Storybook allowlist + add the storybook script

Related product discussion/links

• WOOA7S-1314
• Parent: WOOA7S-1311 (M2 — Shared Packages Integration)
• Stacked on feat(premium-analytics): resolve internal packages for build and types #49189 (WOOA7S-1320)
• Sibling: feat(premium-analytics): port datetime package from next-woocommerce-analytics #49221 (datetime port — same pattern)

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 (~150ms)
pnpm exec eslint --flag v10_config_lookup_from_file --max-warnings=0 packages/icons/   # clean

Storybook preview:

cd projects/packages/premium-analytics
pnpm storybook   # boots the shared Storybook at http://localhost:50240

Open Packages → Premium Analytics → Icons → All Icons — the 13 illustrated icons render in a gallery with their export names.

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

1. Edit routes/dashboard/stage.tsx:

   import { calendar } from "@jetpack-premium-analytics/icons";
   void calendar;

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/icons": "link:packages/icons" (the valid-dependencies lint rejects link: — relax it for the temp edit).
2. Import + reference a icons 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/icons 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-icons) and the bare-scope alias/link: drop out — so long term there's no @jetpack-premium-analytics/... to maintain. The package README's usage example uses the working @jetpack-premium-analytics/icons specifier.

[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-1314-integrate-icons-package-into-analytics branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack wooa7s-1314-integrate-icons-package-into-analytics

bin/jetpack-downloader test jetpack-mu-wpcom-plugin wooa7s-1314-integrate-icons-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

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report

[dognose24]

Walked through local verification (Node 24.14.0, branch tip):

• pnpm typecheck — exit 0
• pnpm build — icons transpiled (56ms), full build clean (icons not bundled, matches description's "no wpScript triple" choice)
• pnpm exec eslint --flag v10_config_lookup_from_file --max-warnings=0 packages/icons/ — exit 0
• Smoke import (calendar + megaphone from routes/dashboard/stage.tsx) — typecheck passes via the @jetpack-premium-analytics/* alias. Note: at this point in the stack no link: dep is wired, so pnpm build can't resolve the same import (by design per PR description — no consumer wires it yet).

One mismatch with the PR description: it mentions "re-exports from @wordpress/icons for utility glyphs (dashboard/navigation, settings, plus, info)" but src/index.ts has no re-exports — only the 13 local illustrated icons. The README is internally consistent (only the 13 are listed), so this looks like a description-only mismatch worth updating.

Two small doc nits inline. Otherwise LGTM. Disclosure: downstream consumer of these icons via WOOA7S-1329 (dashboard menu icon + widget headers need these).

[dognose24]

Thanks for addressing the feedback! Re-verified locally (Node 24.14.0):

• pnpm typecheck — exit 0
• pnpm build — icons transpiled cleanly
• pnpm exec eslint --max-warnings=0 packages/icons/ — exit 0

README changes look good. The Storybook integration commit (projects/js-packages/storybook/storybook/projects.js allowlist + the new storybook script in the package) addresses the rendering gap I'd mentioned earlier — nice bonus.

Agreed on keeping calendar's viewBox upstream-faithful for this port — a separate follow-up is the right scope.