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

[chihsuan]

Proposed changes

First leaf in M2 — Shared Packages Integration (WOOA7S-1312): port @next-woo-analytics/datetime into @automattic/jetpack-premium-analytics as an internal package. Provides timezone-aware date helpers (date-fns + @date-fns/tz) and date-range presets (Today, Last 7 days, Last Year, Custom, comparison ranges) consumed by analytics widgets.

Chosen first because it's a true leaf — no internal deps, only date-fns, @date-fns/tz, @wordpress/i18n. Stacked on #49189 (which sets up the @jetpack-premium-analytics/* tsconfig paths alias this work relies on).

What's in the package

File	Purpose
src/tz.ts	TZ-aware date helpers (createTZDateFromParts, startOfDayTZ, endOfDayTZ, ISO format helpers)
src/get-comparison-range.ts	Comparison range math (previous period / week / month / year)
src/presets/{primary,comparison,types}.ts	Selectable + comparison preset definitions with i18n labels

Monorepo adaptations

Upstream	Here	Why
name: @next-woo-analytics/datetime	name: @automattic/jetpack-premium-analytics-datetime	Per the internal-packages convention in the parent README.md — the import specifier (@jetpack-premium-analytics/datetime) comes from wpPlugin.packageNamespace; the name: field is separate and must use the @automattic/... form
date-fns: "*", @date-fns/tz: "*"	date-fns: 4.1.0, @date-fns/tz: 1.4.1	Jetpack convention — every other package pins concrete versions; the repo also sets minimumReleaseAge: 1440 which conflicts with "*"
Leaf tsconfig.json	(deleted)	Parent already includes: [packages/**/*]; sibling packages/init/ has no leaf tsconfig either
any[] in GrowTuple constraint	unknown[]	Same semantics (generic array constraint), satisfies @typescript-eslint/no-explicit-any
'woocommerce-analytics' text domain	'jetpack-premium-analytics'	Auto-fixed by Jetpack's ESLint text-domain rule
README header (title/description)	Rewritten to match monorepo context	Title uses the package's canonical name (@automattic/jetpack-premium-analytics-datetime); the internal-package note was dropped (the parent README's dual-naming section was reverted in #49189)

Two structural files added at the parent level:

• package.json: adds date-fns and @date-fns/tz so the leaf's imports resolve. packages/datetime/ 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. This mirrors how packages/init/'s deps are declared at the parent level.
• eslint.config.mjs (new — temporary): softens jsdoc/require-* for packages/datetime/** so the initial port can land with the upstream JSDoc style (/** @param value */ without descriptions). The plan is to backfill proper JSDoc on the helpers in a follow-up and delete this config file entirely.

What's intentionally not here

• No link: dep on the parent yet. The parent README documents the pattern (@jetpack-premium-analytics/datetime: link:packages/datetime), but eslint-plugin-package-json's valid-dependencies rule rejects link: URLs by default. Since no route or sibling package imports datetime 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 (probably by relaxing the rule for this package.json or aligning with whatever feat(premium-analytics): resolve internal packages for build and types #49189's test plan assumed).
• 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-1312
• Stacked on feat(premium-analytics): resolve internal packages for build and types #49189 (WOOA7S-1320)

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/datetime/   # clean

Optional — type/IDE resolution (confirms the tsconfig path alias works through the typechecker):

1. Edit routes/dashboard/stage.tsx:

   import { getDefaultDateRangePresets } from '@jetpack-premium-analytics/datetime';
   void getDefaultDateRangePresets;

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

Optional — build-time resolution via link: (confirms wp-build tracks it as a module dependency):

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

   'module_dependencies' => array( array( 'id' => '@jetpack-premium-analytics/datetime', 'import' => 'static' ) )

4. Revert both edits + pnpm install.

Note: the @jetpack-premium-analytics/datetime 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-datetime) and the bare-scope alias/link: drop out — so long term there's no @jetpack-premium-analytics/... to maintain.

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

bin/jetpack-downloader test jetpack wooa7s-1312-integrate-datetime-package-into-analytics

bin/jetpack-downloader test jetpack-mu-wpcom-plugin wooa7s-1312-integrate-datetime-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 2beeaa9, 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 2beeaa9 is available.

Full summary · PHP report · JS report

[dognose24]

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

• pnpm typecheck — exit 0
• pnpm build — datetime transpiled (142ms), full build clean
• pnpm exec eslint --flag v10_config_lookup_from_file --max-warnings=0 packages/datetime/ — exit 0
• Smoke import (getDefaultDateRangePresets + type DateRangePreset from routes/dashboard/stage.tsx) — typecheck passes, the @jetpack-premium-analytics/* alias resolves end-to-end

Two small doc nits inline. Otherwise LGTM. Disclosure: downstream consumer of these presets via WOOA7S-1329 (date filters in dashboard route need exactly this).

[chihsuan]

Two small doc nits inline. Otherwise LGTM. Disclosure: downstream consumer of these presets via WOOA7S-1329 (date filters in dashboard route need exactly this).

Thanks @dognose24 Applied your suggestions. 🙌