@pantheon-systems/pds-toolkit-react 2.0.0-alpha.7 → 2.0.0-alpha.71

package/dist/utilities/hooks/useKeyPress/useKeyPress.d.ts

@@ -20,4 +20,10 @@ export interface UseKeyPressOptions {
      */
     shiftKey?: boolean;
 }
+/**
+ * @deprecated Use `useKeyboardShortcut` instead. `useKeyPress` fires even while
+ * the user is typing in a form field and requires callers to manually disable
+ * shortcuts when an overlay is open; `useKeyboardShortcut` handles both by
+ * default. This hook will be removed before the v2 stable release.
+ */
 export declare const useKeyPress: (targetKey: string, callback?: (event: KeyboardEvent) => void, options?: UseKeyPressOptions) => boolean;

package/dist/utilities/hooks/useKeyboardShortcut/useKeyboardShortcut.d.ts

@@ -0,0 +1,29 @@
+import { HotkeyCallback, Keys, Options } from 'react-hotkeys-hook';
+export type UseKeyboardShortcutOptions = Options;
+/**
+ * Registers a keyboard shortcut, applying the PDS defaults on top of
+ * `react-hotkeys-hook`:
+ *
+ * - **Ignores form fields by default.** Shortcuts do not fire while focus is in
+ *   an `input`, `textarea`, `select`, or `contentEditable` element, so typing a
+ *   shortcut character (e.g. `/`) into a field never hijacks it. Opt in per
+ *   shortcut with `enableOnFormTags` / `enableOnContentEditable` when a shortcut
+ *   genuinely needs to fire inside a field.
+ * - **Overlay-aware.** Shortcuts auto-suppress while any PDS overlay (modal,
+ *   drawer, mobile menu, etc.) is open, so callers never have to thread
+ *   `hasOpenOverlay` through their own `enabled` flag.
+ *
+ * The full `react-hotkeys-hook` option surface (scopes, key sequences,
+ * `description`, cross-platform `mod`, etc.) is available via `options`.
+ *
+ * @param keys - The key or combination to listen for, e.g. `'/'`, `'mod+k'`,
+ *   `'shift+['`. Uses `react-hotkeys-hook` key syntax.
+ * @param callback - Invoked when the shortcut fires. Receives the
+ *   `KeyboardEvent` and the parsed hotkey event.
+ * @param options - `react-hotkeys-hook` options. `enabled` is combined with the
+ *   overlay state so a shortcut is active only when enabled *and* no overlay is
+ *   open.
+ * @param dependencies - Optional dependency array for the callback, forwarded to
+ *   `react-hotkeys-hook`.
+ */
+export declare const useKeyboardShortcut: (keys: Keys, callback: HotkeyCallback, options?: UseKeyboardShortcutOptions, dependencies?: unknown[]) => (instance: HTMLElement) => void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pantheon-systems/pds-toolkit-react",
 	"technology": "React",
-	"version": "2.0.0-alpha.7",
+	"version": "2.0.0-alpha.71",
 	"description": "PDS toolkit built using the React framework",
 	"publishConfig": {
 		"access": "public",
@@ -20,6 +20,9 @@
 		"url": "https://github.com/pantheon-systems/pds-toolkit-react/issues"
 	},
 	"homepage": "https://github.com/pantheon-systems/pds-toolkit-react#readme",
+	"bin": {
+		"pds-codemod": "./bin/pds-codemod.cjs"
+	},
 	"module": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"exports": {
@@ -27,10 +30,17 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js"
 		},
+		"./tailwind/v3/preset": "./tailwind/v3/preset.cjs",
+		"./tailwind/v4/theme.css": "./tailwind/v4/theme.css",
 		"./*": "./dist/*"
 	},
 	"files": [
-		"dist"
+		"bin",
+		"codemods/v1-to-v2/transforms",
+		"codemods/v1-to-v2/mappings.json",
+		"codemods/v1-to-v2/css-token-renames.js",
+		"dist",
+		"tailwind"
 	],
 	"sideEffects": [
 		"*.css"
@@ -41,17 +51,17 @@
 		"build:lib": "vite build && npm run build:types",
 		"build:types": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
 		"postbuild:lib": "npm run build:css && npm run build:css:components && npm run build:css:layouts && npm run build:css:packageExtraCss && npm run generate:svg-icons",
-		"build:css": "postcss src/core.css -o dist/css/pds-core.css",
-		"build:css:components": "postcss src/components/index.css -o dist/css/pds-components.css",
-		"build:css:layouts": "postcss src/layouts/index.css -o dist/css/pds-layouts.css",
-		"build:css:packageExtraCss": "node scripts/package-extra-css.js",
+		"build:css": "PDS_CSS_LAYER=pds-v2 postcss src/core.css -o dist/css/pds-core.css",
+		"build:css:components": "PDS_CSS_LAYER=pds-v2 postcss src/components/index.css -o dist/css/pds-components.css",
+		"build:css:layouts": "PDS_CSS_LAYER=pds-v2 postcss src/layouts/index.css -o dist/css/pds-layouts.css",
+		"build:css:packageExtraCss": "PDS_CSS_LAYER=pds-v2 node scripts/package-extra-css.js",
 		"build:css:watch": "npm run build:css -- -w",
 		"prestorybook": "node scripts/filter-exports-by-tags.js && npm run build:css && npm run build:css:components && npm run build:css:layouts && npm run generate:ux-writing-search-index && npm run generate:ux-writing-guide",
-		"storybook": "storybook dev -p 6006",
+		"storybook": "PDS_CSS_LAYER=pds-v2 storybook dev -p 6006",
 		"prebuild": "npm run build:css && npm run build:css:components && npm run build:css:layouts && npm run build:css:packageExtraCss && npm run generate:ux-writing-search-index && npm run generate:ux-writing-guide",
-		"build": "NODE_ENV=production storybook build",
+		"build": "NODE_OPTIONS=--max-old-space-size=4096 NODE_ENV=production storybook build",
 		"build-storybook": "NODE_ENV=production storybook build",
-		"postbuild": "node scripts/copy-mcp-assets.js && node scripts/build-starter-template.js && node scripts/generate-html-docs.js && node scripts/verify-mcp-build.js",
+		"postbuild": "node scripts/generate-html-docs.js && node scripts/build-starter-template.js && node scripts/copy-mcp-assets.js && node scripts/verify-mcp-build.js",
 		"verify:mcp": "node scripts/verify-mcp-build.js",
 		"start": "node index.js",
 		"develop": "npm run storybook",
@@ -85,83 +95,99 @@
 		"generate:ux-writing-search-index": "node scripts/generate-search-index.js",
 		"generate:ux-writing-guide": "node scripts/generate-ux-writing-guide.js",
 		"generate:html-docs": "node scripts/generate-html-docs.js",
+		"test:codemods": "jest --testPathPatterns=codemods/",
 		"test:version-switcher": "bash scripts/test-version-switcher.sh",
 		"pack:local": "bash scripts/pack-local.sh",
 		"prepare": "husky install",
 		"chromatic": "npx chromatic --project-token=chpt_8f57e9785118676"
 	},
+	"jest": {
+		"testMatch": [
+			"**/codemods/**/__tests__/**/*.test.js"
+		],
+		"testEnvironment": "node"
+	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.15.3",
-		"@axe-core/playwright": "^4.11.0",
-		"@babel/preset-env": "^7.21.5",
+		"@axe-core/playwright": "^4.11.3",
+		"@babel/preset-env": "^7.29.5",
 		"@babel/preset-react": "^7.18.6",
 		"@babel/preset-typescript": "^7.28.5",
 		"@csstools/postcss-design-tokens": "^2.0.4",
 		"@csstools/postcss-global-data": "^1.0.3",
-		"@playwright/test": "^1.36.2",
-		"@storybook/addon-a11y": "^10.2.3",
-		"@storybook/addon-docs": "^10.2.3",
-		"@storybook/addon-links": "^10.2.3",
-		"@storybook/addon-mcp": "^0.2.0",
-		"@storybook/addon-webpack5-compiler-swc": "^4.0.2",
-		"@storybook/react-vite": "^10.2.3",
-		"@storybook/react-webpack5": "^10.2.3",
-		"@types/prismjs": "^1.26.5",
-		"@types/react": "^19.2.2",
-		"@typescript-eslint/eslint-plugin": "^8.47.0",
-		"@typescript-eslint/parser": "^8.47.0",
-		"@vitejs/plugin-react": "^4.3.0",
+		"@fortawesome/free-brands-svg-icons": "7.2.0",
+		"@fortawesome/pro-regular-svg-icons": "7.2.0",
+		"@fortawesome/pro-solid-svg-icons": "7.2.0",
+		"@playwright/test": "^1.60.0",
+		"@storybook/addon-a11y": "^10.4.0",
+		"@storybook/addon-docs": "^10.4.0",
+		"@storybook/addon-links": "^10.4.0",
+		"@storybook/addon-mcp": "^0.6.0",
+		"@storybook/addon-webpack5-compiler-swc": "^4.0.3",
+		"@storybook/react-vite": "^10.4.0",
+		"@storybook/react-webpack5": "^10.4.0",
+		"@types/prismjs": "^1.26.6",
+		"@types/react": "^19.2.14",
+		"@typescript-eslint/eslint-plugin": "^8.59.3",
+		"@typescript-eslint/parser": "^8.59.3",
+		"@vitejs/plugin-react": "^6.0.2",
 		"@vueless/storybook-dark-mode": "^9.0.9",
 		"axe-html-reporter": "^2.2.3",
 		"chromatic": "^13.3.4",
 		"concurrently": "^8.0.1",
 		"cssnano": "^6.0.1",
-		"eslint": "^9.26.0",
+		"eslint": "^9.39.4",
 		"eslint-config-prettier": "^9.1.0",
 		"eslint-import-resolver-typescript": "^4.4.4",
 		"eslint-plugin-import": "^2.32.0",
-		"eslint-plugin-prettier": "^5.1.3",
+		"eslint-plugin-prettier": "^5.5.5",
 		"eslint-plugin-react": "^7.32.2",
 		"eslint-plugin-simple-import-sort": "^12.1.1",
 		"eslint-plugin-sort-destructure-keys": "^2.0.0",
-		"eslint-plugin-storybook": "^10.2.3",
+		"eslint-plugin-storybook": "^10.4.0",
 		"eslint-plugin-typescript-sort-keys": "^3.3.0",
 		"fast-glob": "^3.3.2",
 		"husky": "^8.0.3",
+		"jest": "^30.4.2",
+		"jscodeshift": "^17.3.0",
 		"lint-staged": "^13.2.3",
 		"pino-pretty": "^13.1.3",
 		"plop": "^3.1.2",
-		"postcss": "^8.4.38",
+		"postcss": "^8.5.14",
 		"postcss-cli": "^10.1.0",
 		"postcss-custom-media": "^9.1.3",
 		"postcss-import": "^15.1.0",
 		"postcss-insert": "^1.0.0",
-		"postcss-loader": "^8.1.1",
+		"postcss-loader": "^8.2.1",
 		"postcss-nested": "^6.0.1",
-		"prettier": "3.2.5",
-		"prettier-plugin-css-order": "^2.1.2",
+		"prettier": "^3.8.3",
+		"prettier-plugin-css-order": "^2.2.0",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0",
-		"storybook": "^10.2.3",
-		"tsc-alias": "^1.8.16",
+		"storybook": "^10.4.0",
+		"tsc-alias": "^1.8.17",
 		"typescript": "^5.4.5",
-		"vite": "^7.2.2",
+		"vite": "^8.0.16",
 		"vite-plugin-lib-inject-css": "^2.1.1",
 		"vite-tsconfig-paths": "^4.3.2"
 	},
 	"peerDependencies": {
-		"react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-		"react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+		"react": "^18.0.0 || ^19.0.0",
+		"react-dom": "^18.0.0 || ^19.0.0"
 	},
 	"dependencies": {
+		"@dnd-kit/core": "^6.3.1",
+		"@dnd-kit/sortable": "^10.0.0",
+		"@dnd-kit/utilities": "^3.2.2",
 		"@floating-ui/react": "^0.24.3",
 		"@floating-ui/react-dom": "~1.3.0",
-		"@pantheon-systems/pds-design-tokens": "^2.0.0-alpha.33",
+		"@internationalized/date": "^3.12.2",
+		"@pantheon-systems/pds-design-tokens": "^2.0.0-alpha.67",
 		"@reactuses/core": "^5.0.15",
 		"date-fns": "^4.1.0",
-		"downshift": "^9.0.8",
-		"express": "^4.22.1",
-		"express-rate-limit": "^8.2.1",
+		"downshift": "^9.3.2",
+		"express": "^5.0.0",
+		"express-rate-limit": "^8.5.2",
 		"focus-trap-react": "^10.2.1",
 		"hash-sum": "^2.0.0",
 		"modern-normalize": "^3.0.1",
@@ -169,16 +195,26 @@
 		"pino-http": "^11.0.0",
 		"prism-react-renderer": "^2.4.1",
 		"prismjs": "^1.29.0",
+		"react-aria": "^3.50.0",
 		"react-code-block": "^1.1.1",
-		"react-day-picker": "^9.11.1",
 		"react-device-detect": "^2.2.3",
-		"react-router-dom": "^6.13.0",
-		"react-toastify": "^9.0.3"
+		"react-hotkeys-hook": "^4.5.1",
+		"react-stately": "^3.48.0",
+		"react-toastify": "^11.1.0",
+		"recharts": "^3.8.1"
 	},
-	"optionalDependencies": {
-		"@fortawesome/free-brands-svg-icons": "^7.2.0",
-		"@fortawesome/pro-regular-svg-icons": "^7.2.0",
-		"@fortawesome/pro-solid-svg-icons": "^7.2.0"
+	"overrides": {
+		"@babel/plugin-transform-modules-systemjs": "^7.29.4",
+		"fast-uri": "^3.1.5",
+		"hono": "^4.12.18",
+		"ip-address": "^10.1.1",
+		"micromatch": "^4.0.8",
+		"minimatch": "^10.0.0",
+		"postcss-insert": {
+			"postcss": "^8.4.31"
+		},
+		"valibot": "^1.4.2",
+		"yaml": "^2.8.3"
 	},
 	"lint-staged": {
 		"*": "prettier --write --ignore-unknown",

package/tailwind/README.md

@@ -0,0 +1,220 @@
+# PDS Tailwind Configuration
+
+Tailwind CSS configs that map Pantheon Design System tokens to Tailwind utilities. Available for both Tailwind v3 and v4.
+
+> **Note:** Using Tailwind CSS alongside PDS is not the recommended approach. PDS components handle their own styling. This configuration is provided so that UI built outside the scope of PDS components uses correct design system values rather than arbitrary ones.
+
+---
+
+## Prerequisites
+
+Both configs require `pds-core.css` to be loaded globally in your app. This provides the `--pds-*` CSS custom properties that the Tailwind utilities reference at runtime.
+
+Import it as a JavaScript import in your app's root layout — this ensures reliable module resolution via the package `exports` map:
+
+```ts
+import '@pantheon-systems/pds-toolkit-react/css/pds-core.css';
+```
+
+> **Note:** Use `css/pds-core.css`, not `dist/css/pds-core.css`. The package exports map handles the `dist/` prefix automatically. Using a CSS `@import` instead of a JS import can cause resolution failures in some bundlers (including Next.js with Turbopack).
+
+---
+
+## Tailwind v4
+
+**Recommended for new projects.**
+
+### Setup
+
+In `app/layout.tsx` (or your root layout):
+
+```ts
+import '@pantheon-systems/pds-toolkit-react/css/pds-core.css';
+import './globals.css';
+```
+
+In `app/globals.css`:
+
+```css
+/* Tailwind layers — imported separately to exclude preflight */
+@import 'tailwindcss/theme' layer(theme);
+@import 'tailwindcss/utilities' layer(utilities);
+
+/* PDS theme overrides */
+@import '@pantheon-systems/pds-toolkit-react/tailwind/v4/theme.css';
+```
+
+> **Why not `@import "tailwindcss"`?**
+> The single `@import "tailwindcss"` shorthand includes Tailwind's preflight CSS reset, which conflicts with PDS base styles. Importing the layers individually lets you skip preflight.
+
+No `tailwind.config.js` is needed.
+
+---
+
+## Tailwind v3
+
+### Setup
+
+```bash
+npm install tailwindcss@3
+```
+
+`tailwind.config.js`:
+
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+	presets: [require('@pantheon-systems/pds-toolkit-react/tailwind/v3/preset')],
+	content: ['./src/**/*.{js,ts,jsx,tsx}'],
+};
+```
+
+In `app/layout.tsx` (or your root layout):
+
+```ts
+import '@pantheon-systems/pds-toolkit-react/css/pds-core.css';
+import './globals.css';
+```
+
+`app/globals.css`:
+
+```css
+/* Tailwind directives */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+Preflight is disabled automatically by the preset.
+
+---
+
+## What's included
+
+### Colors
+
+All values reference PDS CSS custom properties — dark mode works automatically.
+
+| Group               | Example utility                | PDS token                               |
+| ------------------- | ------------------------------ | --------------------------------------- |
+| `bg-*`              | `bg-bg-default`                | `--pds-color-bg-default`                |
+| `fg-*`              | `text-fg-default`              | `--pds-color-fg-default`                |
+| `text-*`            | `text-text-secondary`          | `--pds-color-text-default-secondary`    |
+| `border-*`          | `border-border-input`          | `--pds-color-border-input`              |
+| `interactive-*`     | `text-interactive-link`        | `--pds-color-interactive-link-default`  |
+| `status-{type}-*`   | `bg-status-success-background` | `--pds-color-status-success-background` |
+| `brand-primary-*`   | `bg-brand-primary-400`         | `--pds-color-brand-primary-400`         |
+| `brand-secondary-*` | `bg-brand-secondary`           | `--pds-color-brand-secondary-default`   |
+| `brand-accent-*`    | `text-brand-accent`            | `--pds-color-brand-accent-default`      |
+
+### Spacing
+
+The PDS named scale replaces Tailwind's default numeric scale. Use semantic keys like `p-m`, `gap-xl`, `mt-2xl`.
+
+```html
+<div class="p-m gap-xl mt-2xl">...</div>
+```
+
+Common Tailwind numeric values are also aliased to their nearest PDS equivalent, so `p-4` still works and stays in sync with the token:
+
+| Tailwind | PDS key | Value   |
+| -------- | ------- | ------- |
+| `p-1`    | `p-4xs` | 0.25rem |
+| `p-2`    | `p-2xs` | 0.5rem  |
+| `p-3`    | `p-s`   | 0.75rem |
+| `p-4`    | `p-m`   | 1rem    |
+| `p-5`    | `p-l`   | 1.25rem |
+| `p-6`    | `p-xl`  | 1.5rem  |
+| `p-8`    | `p-2xl` | 2rem    |
+| `p-10`   | `p-3xl` | 2.5rem  |
+| `p-12`   | `p-4xl` | 3rem    |
+| `p-16`   | `p-5xl` | 4rem    |
+
+Values like `p-7`, `p-9`, `p-11` (which don't have a clean PDS equivalent) are not aliased and will not generate any CSS.
+
+> **Numeric aliases use CSS variable references**, not hardcoded values. If a PDS spacing token ever changes, `p-4` will automatically reflect the new value — no config update needed.
+
+### Typography
+
+```html
+<p class="font-sans text-m font-normal leading-m">Body text</p>
+<h2 class="font-sans text-2xl font-semibold leading-s">Heading</h2>
+```
+
+| Scale | Font size    | Font family             | Font weight                                     | Line height         | Letter spacing      |
+| ----- | ------------ | ----------------------- | ----------------------------------------------- | ------------------- | ------------------- |
+| Keys  | `xs` – `9xl` | `sans`, `serif`, `mono` | `light`, `normal`, `medium`, `semibold`, `bold` | `s`, `m`, `l`, `xl` | `s`, `m`, `l`, `xl` |
+
+### Border radius
+
+```html
+<div class="rounded-container">Card</div>
+<button class="rounded-button">Button</button>
+<input class="rounded-input" />
+```
+
+Keys: `none`, `DEFAULT` (`rounded`), `button`, `input`, `container`, `bar`, `full`
+
+### Z-index
+
+```html
+<div class="z-modal">Modal</div>
+<nav class="z-navigation">Nav</nav>
+```
+
+Keys: `navigation`, `dropdown`, `notifications`, `overlay`, `modal`, `max`
+
+### Max width
+
+Matches PDS `Container` component breakpoints. Use when building layout sections outside PDS container components.
+
+```html
+<div class="max-w-standard mx-auto px-m">...</div>
+```
+
+Keys: `narrow` (1024px), `standard` (1200px), `wide` (1440px), `x-wide` (1600px)
+
+---
+
+## Important caveats
+
+### Borders require an explicit border-style
+
+The PDS preset resets `border-style` to `none` on all elements so that borders are fully opt-in. This prevents phantom borders on elements that pick up a non-zero `border-width` from PDS components, inheritance, or browser defaults. When adding borders with Tailwind, always include a border-style class (`border-solid`, `border-dashed`, or `border-dotted`):
+
+```html
+<div class="border border-solid border-border-default">...</div>
+<div class="border-b border-solid border-border-separator">Divider</div>
+```
+
+### Opacity modifiers are not supported
+
+Tailwind's opacity modifier syntax (`bg-bg-default/50`) does not work with CSS variable color references. This is a known Tailwind limitation — the compiler cannot decompose a CSS variable into RGB channels. Avoid using opacity modifiers with PDS colors.
+
+### Apply Tailwind utilities to your own elements, not PDS components
+
+PDS components are styled with scoped BEM classes. Do not use Tailwind utilities to override PDS component styles — use component props and the `className` prop for layout adjustments only. Applying Tailwind utility classes to PDS component internals will lead to unpredictable results.
+
+```jsx
+// ✅ Tailwind for your layout, PDS for the component
+<div class="flex gap-m items-center">
+  <Button label="Save" variant="primary" />
+</div>
+
+// ❌ Don't override PDS component internals with Tailwind
+<Button label="Save" className="text-red-500 bg-blue-200" />
+```
+
+### Import order matters
+
+`pds-core.css` must be imported before Tailwind. If Tailwind's utilities load before PDS variables are defined, the CSS custom property references will resolve to empty values.
+
+### Scanning for class names (`@source` in v4)
+
+Tailwind v4 automatically scans your project files for class names. If your source files are outside the default scan path (common in monorepos), add a `@source` directive to your CSS entry point:
+
+```css
+@source './src/**/*.{js,ts,jsx,tsx}';
+```
+
+This is your project's responsibility — the PDS package does not need to be scanned (PDS components do not use Tailwind class names internally).