@automattic/vip-design-system 2.15.9 → 2.17.0

package/.github/workflows/npm-prepare-release.yml

@@ -20,10 +20,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
 
       - name: Run npm-prepare-release
-        uses: Automattic/vip-actions/npm-prepare-release@v0.1.2
+        uses: Automattic/vip-actions/npm-prepare-release@v0.7.3
         with:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           npm-version-type: ${{ inputs.npm-version-type }}

package/.github/workflows/npm-publish.yml

@@ -1,3 +1,4 @@
+---
 name: Publish to npm (if applicable)
 
 on:
@@ -8,9 +9,16 @@ jobs:
   publish:
     name: Publish to npm
     runs-on: ubuntu-latest
+    environment: npm-publish
+    permissions:
+      id-token: write
+      contents: write
+      pull-requests: write
     if: contains( github.event.pull_request.labels.*.name, '[ Type ] NPM version update' ) && startsWith( github.head_ref, 'release/') && github.event.pull_request.merged == true
+
     steps:
-      - uses: Automattic/vip-actions/npm-publish@v0.1.2
+      - uses: Automattic/vip-actions/npm-publish@v0.7.3
         with:
+          USE_TRUSTED_PUBLISHING: 'true'
+          PROVENANCE: 'false'
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/AGENTS.md

@@ -0,0 +1,102 @@
+# Agents
+
+Instructions for AI agents working on this codebase.
+
+## Project Overview
+
+This is `@automattic/vip-design-system`, a React component library and design token system published to npm. It provides 40+ reusable UI components for VIP projects.
+
+## Tech Stack
+
+- **React 18** with **TypeScript 5.2**
+- **Theme UI 0.16** for styling (CSS-in-JS via Emotion)
+- **Radix UI** for accessible primitive components (accordion, checkbox, dialog, dropdown, switch, tabs, tooltip)
+- **Babel 7** for compilation (output to `build/`)
+- **Jest 29** + **@testing-library/react** + **jest-axe** for testing
+- **Storybook 7.6** for component documentation
+- **ESLint 8** with `@automattic/eslint-plugin-wpvip` + **Prettier** (`wp-prettier`)
+
+## Code Structure
+
+```
+src/system/              # All components, theme, and utilities
+src/system/<Component>/  # Individual component directories
+  ComponentName.tsx      # Component implementation
+  ComponentName.test.tsx # Unit tests
+  ComponentName.stories.tsx # Storybook documentation
+  index.ts               # Re-exports (optional)
+src/system/theme/        # Theme configuration and generated tokens
+src/system/utils/        # Shared utility functions
+src/system/index.js      # Package entry point (re-exports all components)
+tokens/                  # Design token source files (from Figma Studio)
+.storybook/              # Storybook configuration and decorators
+docs/                    # Detailed documentation (architecture, contributing, testing, releasing)
+build/                   # Compiled output (generated, do not edit)
+```
+
+## Commands
+
+| Command                | Purpose                                |
+| ---------------------- | -------------------------------------- |
+| `npm run test`         | Run Jest unit tests                    |
+| `npm run lint`         | Run ESLint                             |
+| `npm run lint:fix`     | Auto-fix ESLint issues                 |
+| `npm run format:check` | Check Prettier formatting              |
+| `npm run format`       | Auto-format with Prettier              |
+| `npm run check-types`  | TypeScript type checking               |
+| `npm run build`        | Full production build                  |
+| `npm run dev`          | Start Storybook dev server (port 6006) |
+
+## Component Conventions
+
+### Creating Components
+
+- Place new components in `src/system/<ComponentName>/`.
+- Each component needs at minimum: `ComponentName.tsx`, `ComponentName.test.tsx`, and `ComponentName.stories.tsx`.
+- Export the component from `src/system/index.js`.
+
+### Coding Standards
+
+- Follow the WPVIP ESLint configuration defined in `.eslintrc.js`.
+- Use Prettier formatting (`wp-prettier`). Run `npm run format` before committing.
+- Use TypeScript for all new code. Define prop interfaces with explicit types.
+- Use `forwardRef` when wrapping HTML elements or Theme UI components.
+
+### Styling
+
+- Use Theme UI's `sx` prop for styling. Do not use inline styles or CSS modules.
+- Reference theme tokens for colors, spacing, and typography (do not hardcode values).
+- Support both light and dark themes through the token system.
+
+### Accessibility
+
+- Accessibility is a priority. Use Radix UI primitives when building interactive components (dialogs, dropdowns, tooltips, etc.).
+- Include `jest-axe` tests (`toHaveNoViolations`) in component test files.
+- Ensure proper ARIA attributes, keyboard navigation, and screen reader support.
+
+### Testing
+
+- Write tests using `@testing-library/react`. Test user-visible behavior, not implementation details.
+- Include accessibility tests with `jest-axe`.
+- Place test files next to the component: `ComponentName.test.tsx`.
+- All tests must pass before submitting a PR: `npm run test`.
+
+### Storybook Stories
+
+- Write stories using the CSF3 format (Component Story Format).
+- Include multiple variants and states of the component.
+- Place stories next to the component: `ComponentName.stories.tsx`.
+
+## Theme and Design Tokens
+
+- Tokens are managed via Figma Studio and stored in `tokens/`.
+- Run `npm run theme-update` to regenerate theme files from tokens.
+- Do not manually edit files in `src/system/theme/generated/` — they are overwritten by the theme update script.
+- Light theme: `wpvip-product-core`. Dark theme: `wpvip-product-dark`.
+
+## Git Workflow
+
+- Main branch: `trunk`.
+- Versioning follows semver (`major.minor.patch`).
+- Releases are published to npm via GitHub Actions (preferred) or locally.
+- PRs require passing CI checks: lint, format, type checking, and tests.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/build/system/NewForm/FormSelect.d.ts

@@ -17,6 +17,7 @@ interface FormSelectProps {
     options: Option[];
     required?: boolean;
     label?: string;
+    separator?: boolean;
     getOptionLabel?: (option: Option) => string;
     getOptionValue?: (option: Option) => string | number;
     onChange?: (option: Option | undefined, event: React.ChangeEvent<HTMLSelectElement>) => void;

package/build/system/NewForm/FormSelect.js

@@ -1,4 +1,4 @@
-var _excluded = ["disabled", "isInline", "placeholder", "forLabel", "options", "required", "label", "getOptionLabel", "getOptionValue", "onChange", "hasError", "errorMessage", "wrapperSx"],
+var _excluded = ["disabled", "isInline", "placeholder", "forLabel", "options", "required", "label", "getOptionLabel", "getOptionValue", "onChange", "hasError", "errorMessage", "wrapperSx", "separator"],
   _excluded2 = ["options"];
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
 function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
@@ -63,6 +63,8 @@ var FormSelect = /*#__PURE__*/React.forwardRef(function (_ref2, forwardRef) {
     hasError = _ref2.hasError,
     errorMessage = _ref2.errorMessage,
     wrapperSx = _ref2.wrapperSx,
+    _ref2$separator = _ref2.separator,
+    separator = _ref2$separator === void 0 ? true : _ref2$separator,
     props = _objectWithoutPropertiesLoose(_ref2, _excluded);
   if (isDev && options.length > MAX_SUGGESTED_OPTIONS) {
     // eslint-disable-next-line no-console
@@ -112,7 +114,9 @@ var FormSelect = /*#__PURE__*/React.forwardRef(function (_ref2, forwardRef) {
         ref: forwardRef,
         sx: _extends({
           cursor: disabled ? 'not-allowed' : 'pointer'
-        }, defaultStyles),
+        }, defaultStyles, !separator && {
+          paddingRight: 6
+        }),
         required: required,
         disabled: disabled,
         "aria-required": required,
@@ -127,7 +131,8 @@ var FormSelect = /*#__PURE__*/React.forwardRef(function (_ref2, forwardRef) {
           return groupOptions ? renderGroup(optionLabel(option), groupOptions) : renderOption(optionLabel(option), optionValue(option));
         })]
       })), _jsx(FormSelectArrow, {
-        iconSize: ICON_SIZE
+        iconSize: ICON_SIZE,
+        separator: separator
       })]
     }), hasError && errorMessage && _jsx(Validation, {
       isValid: false,

package/build/system/NewForm/FormSelectArrow.d.ts

@@ -5,6 +5,7 @@
 import React from 'react';
 interface FormSelectArrowProps {
     iconSize?: number;
+    separator?: boolean;
 }
 export declare const FormSelectArrow: React.ForwardRefExoticComponent<FormSelectArrowProps & React.RefAttributes<SVGSVGElement>>;
 export {};

package/build/system/NewForm/FormSelectArrow.js

@@ -1,4 +1,4 @@
-var _excluded = ["iconSize"];
+var _excluded = ["iconSize", "separator"];
 function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
 /** @jsxImportSource theme-ui */
@@ -13,23 +13,26 @@ import { MdExpandMore } from 'react-icons/md';
  */
 import { baseControlBorderStyle as borderStyle } from '../Form/Input.styles';
 import { jsx as _jsx } from "theme-ui/jsx-runtime";
-var arrowStyles = {
-  position: 'absolute',
-  paddingLeft: 2,
-  borderLeftWidth: borderStyle.borderWidth,
-  borderLeftStyle: borderStyle.borderStyle,
-  borderLeftColor: borderStyle.borderColor,
-  right: 3,
-  top: '7px',
-  pointerEvents: 'none',
-  svg: {
-    fill: borderStyle.borderColor
-  }
-};
 export var FormSelectArrow = /*#__PURE__*/React.forwardRef(function (_ref, forwardRef) {
   var _ref$iconSize = _ref.iconSize,
     iconSize = _ref$iconSize === void 0 ? 24 : _ref$iconSize,
+    _ref$separator = _ref.separator,
+    separator = _ref$separator === void 0 ? true : _ref$separator,
     props = _objectWithoutPropertiesLoose(_ref, _excluded);
+  var arrowStyles = _extends({
+    position: 'absolute',
+    right: 3,
+    top: '7px',
+    pointerEvents: 'none',
+    svg: {
+      fill: borderStyle.borderColor
+    }
+  }, separator && {
+    paddingLeft: 2,
+    borderLeftWidth: borderStyle.borderWidth,
+    borderLeftStyle: borderStyle.borderStyle,
+    borderLeftColor: borderStyle.borderColor
+  });
   return _jsx("div", {
     ref: forwardRef,
     children: _jsx(MdExpandMore, _extends({

package/build/system/NewTooltip/NewTooltip.d.ts

@@ -0,0 +1,16 @@
+/** @jsxImportSource theme-ui */
+import React, { ReactElement, ReactNode } from 'react';
+import { ThemeUIStyleObject } from 'theme-ui';
+export interface NewTooltipProps {
+    content: ReactNode;
+    children: ReactElement;
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    arrow?: boolean;
+    sideOffset?: number;
+    sx?: ThemeUIStyleObject;
+    className?: string;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    delayDuration?: number;
+}
+export declare const NewTooltip: React.FC<NewTooltipProps>;

package/build/system/NewTooltip/NewTooltip.js

@@ -0,0 +1,44 @@
+/** @jsxImportSource theme-ui */
+
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import React from 'react';
+import { NewTooltipArrow } from './NewTooltipArrow';
+import { NewTooltipContent } from './NewTooltipContent';
+import { jsx as _jsx } from "theme-ui/jsx-runtime";
+import { jsxs as _jsxs } from "theme-ui/jsx-runtime";
+export var NewTooltip = function NewTooltip(_ref) {
+  var content = _ref.content,
+    children = _ref.children,
+    _ref$position = _ref.position,
+    position = _ref$position === void 0 ? 'top' : _ref$position,
+    _ref$arrow = _ref.arrow,
+    arrow = _ref$arrow === void 0 ? false : _ref$arrow,
+    sideOffset = _ref.sideOffset,
+    sx = _ref.sx,
+    className = _ref.className,
+    open = _ref.open,
+    onOpenChange = _ref.onOpenChange,
+    _ref$delayDuration = _ref.delayDuration,
+    delayDuration = _ref$delayDuration === void 0 ? 300 : _ref$delayDuration;
+  var defaultOffset = arrow ? 8 : 4;
+  var resolvedOffset = sideOffset != null ? sideOffset : defaultOffset;
+  return _jsx(TooltipPrimitive.Provider, {
+    children: _jsxs(TooltipPrimitive.Root, {
+      open: open,
+      onOpenChange: onOpenChange,
+      delayDuration: delayDuration,
+      children: [_jsx(TooltipPrimitive.Trigger, {
+        asChild: true,
+        children: children
+      }), _jsx(TooltipPrimitive.Portal, {
+        children: _jsxs(NewTooltipContent, {
+          side: position,
+          sideOffset: resolvedOffset,
+          sx: sx,
+          className: className,
+          children: [content, arrow && _jsx(NewTooltipArrow, {})]
+        })
+      })]
+    })
+  });
+};

package/build/system/NewTooltip/NewTooltip.stories.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="react" />
+declare const _default: {
+    title: string;
+    component: import("react").FC<import("./NewTooltip").NewTooltipProps>;
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+};
+export default _default;
+export declare const Basic: () => import("react").JSX.Element;
+export declare const WithArrow: () => import("react").JSX.Element;
+export declare const RichContent: () => import("react").JSX.Element;
+export declare const AllPositions: () => import("react").JSX.Element;

package/build/system/NewTooltip/NewTooltip.stories.js

@@ -0,0 +1,230 @@
+/**
+ * Internal dependencies
+ */
+import { NewTooltip, Button, Heading, Text, Grid } from '..';
+import { jsx as _jsx } from "theme-ui/jsx-runtime";
+import { jsxs as _jsxs } from "theme-ui/jsx-runtime";
+import { Fragment as _Fragment } from "theme-ui/jsx-runtime";
+export default {
+  title: 'NewTooltip',
+  component: NewTooltip,
+  parameters: {
+    docs: {
+      description: {
+        component: "\nA Radix-based tooltip component that supports rich content (ReactNode), including HTML elements\nlike `<strong>` and `<br />`. Built on `@radix-ui/react-tooltip` for full accessibility support.\n\n## Component Properties\n"
+      }
+    }
+  }
+};
+export var Basic = function Basic() {
+  return _jsxs(_Fragment, {
+    children: [_jsx(Heading, {
+      variant: "h2",
+      children: "Basic Usage"
+    }), _jsx(Text, {
+      sx: {
+        mb: 4
+      },
+      children: "A simple tooltip with plain text content on each position."
+    }), _jsxs(Grid, {
+      columns: ['auto auto'],
+      gap: '100px 160px',
+      sx: {
+        justifyContent: 'center',
+        pt: '50px'
+      },
+      children: [_jsx(NewTooltip, {
+        content: "At the top",
+        position: "top",
+        children: _jsx(Button, {
+          children: "Top"
+        })
+      }), _jsx(NewTooltip, {
+        content: "At the bottom",
+        position: "bottom",
+        children: _jsx(Button, {
+          children: "Bottom"
+        })
+      }), _jsx(NewTooltip, {
+        content: "On the left",
+        position: "left",
+        children: _jsx(Button, {
+          children: "Left"
+        })
+      }), _jsx(NewTooltip, {
+        content: "On the right",
+        position: "right",
+        children: _jsx(Button, {
+          children: "Right"
+        })
+      })]
+    })]
+  });
+};
+export var WithArrow = function WithArrow() {
+  return _jsxs(_Fragment, {
+    children: [_jsx(Heading, {
+      variant: "h2",
+      children: "With Arrow"
+    }), _jsx(Text, {
+      sx: {
+        mb: 4
+      },
+      children: "Enable the arrow indicator pointing to the trigger element."
+    }), _jsxs(Grid, {
+      columns: ['auto auto'],
+      gap: '100px 160px',
+      sx: {
+        justifyContent: 'center',
+        pt: '50px'
+      },
+      children: [_jsx(NewTooltip, {
+        content: "At the top with arrow",
+        position: "top",
+        arrow: true,
+        children: _jsx(Button, {
+          children: "Top"
+        })
+      }), _jsx(NewTooltip, {
+        content: "At the bottom with arrow",
+        position: "bottom",
+        arrow: true,
+        children: _jsx(Button, {
+          children: "Bottom"
+        })
+      }), _jsx(NewTooltip, {
+        content: "On the left with arrow",
+        position: "left",
+        arrow: true,
+        children: _jsx(Button, {
+          children: "Left"
+        })
+      }), _jsx(NewTooltip, {
+        content: "On the right with arrow",
+        position: "right",
+        arrow: true,
+        children: _jsx(Button, {
+          children: "Right"
+        })
+      })]
+    })]
+  });
+};
+export var RichContent = function RichContent() {
+  return _jsxs(_Fragment, {
+    children: [_jsx(Heading, {
+      variant: "h2",
+      children: "Rich Content"
+    }), _jsxs(Text, {
+      sx: {
+        mb: 4
+      },
+      children: ["NewTooltip supports ReactNode content, including HTML elements like", ' ', _jsx("code", {
+        children: "<strong>"
+      }), " and ", _jsx("code", {
+        children: "<br />"
+      }), "."]
+    }), _jsxs(Grid, {
+      columns: ['auto auto'],
+      gap: '100px 160px',
+      sx: {
+        justifyContent: 'center',
+        pt: '50px'
+      },
+      children: [_jsx(NewTooltip, {
+        content: _jsxs(_Fragment, {
+          children: ["Press ", _jsx("strong", {
+            children: "Enter"
+          }), _jsx("br", {}), "to confirm"]
+        }),
+        arrow: true,
+        children: _jsx(Button, {
+          children: "With bold and line break"
+        })
+      }), _jsx(NewTooltip, {
+        content: _jsxs(_Fragment, {
+          children: [_jsx("strong", {
+            children: "Tip:"
+          }), " Use keyboard shortcuts for faster navigation"]
+        }),
+        arrow: true,
+        children: _jsx(Button, {
+          children: "With bold label"
+        })
+      })]
+    })]
+  });
+};
+export var AllPositions = function AllPositions() {
+  return _jsxs(_Fragment, {
+    children: [_jsx(Heading, {
+      variant: "h2",
+      children: "All Positions"
+    }), _jsx(Text, {
+      sx: {
+        mb: 4
+      },
+      children: "All four positions with and without arrows."
+    }), _jsxs(Grid, {
+      columns: ['auto auto'],
+      gap: '100px 160px',
+      sx: {
+        justifyContent: 'center',
+        pt: '50px'
+      },
+      children: [_jsx(NewTooltip, {
+        content: "At the top",
+        position: "top",
+        children: _jsx(Button, {
+          children: "Top"
+        })
+      }), _jsx(NewTooltip, {
+        content: "At the top with arrow",
+        position: "top",
+        arrow: true,
+        children: _jsx(Button, {
+          children: "Top with Arrow"
+        })
+      }), _jsx(NewTooltip, {
+        content: "At the bottom",
+        position: "bottom",
+        children: _jsx(Button, {
+          children: "Bottom"
+        })
+      }), _jsx(NewTooltip, {
+        content: "At the bottom with arrow",
+        position: "bottom",
+        arrow: true,
+        children: _jsx(Button, {
+          children: "Bottom with Arrow"
+        })
+      }), _jsx(NewTooltip, {
+        content: "On the left",
+        position: "left",
+        children: _jsx(Button, {
+          children: "Left"
+        })
+      }), _jsx(NewTooltip, {
+        content: "On the left with arrow",
+        position: "left",
+        arrow: true,
+        children: _jsx(Button, {
+          children: "Left with Arrow"
+        })
+      }), _jsx(NewTooltip, {
+        content: "On the right",
+        position: "right",
+        children: _jsx(Button, {
+          children: "Right"
+        })
+      }), _jsx(NewTooltip, {
+        content: "On the right with arrow",
+        position: "right",
+        arrow: true,
+        children: _jsx(Button, {
+          children: "Right with Arrow"
+        })
+      })]
+    })]
+  });
+};

package/build/system/NewTooltip/NewTooltip.test.d.ts

@@ -0,0 +1 @@
+export {};