@hyphen/hyphen-components 8.0.1 → 9.0.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyphen/hyphen-components",
-  "version": "8.0.1",
+  "version": "9.0.0-beta.0",
   "license": "MIT",
   "author": {
     "name": "@hyphen"
@@ -56,7 +56,7 @@
     "react-select": "^5.10.0",
     "react-select-event": "^5.5.1",
     "uuid": "^11.1.1",
-    "@hyphen/hyphen-design-tokens": "^8.0.1"
+    "@hyphen/hyphen-design-tokens": "^9.0.0-beta.0"
   },
   "devDependencies": {
     "@babel/core": "^7.27.4",
@@ -129,12 +129,13 @@
     "build-storybook": "storybook build",
     "build-storybook-docs": "storybook build --docs",
     "storybook-docs": "storybook dev --docs",
-    "lint": "eslint src --ext .ts,.tsx",
-    "lint-fix": "eslint src --ext .ts,.tsx --fix",
+    "lint": "eslint src type-tests --ext .ts,.tsx",
+    "lint-fix": "eslint src type-tests --ext .ts,.tsx --fix",
     "size": "size-limit",
     "start": "tsup --watch",
     "storybook": "storybook dev -p 6006",
-    "test": "jest --passWithNoTests",
+    "test": "pnpm test:types && jest --passWithNoTests",
+    "test:types": "tsc --project tsconfig.type-tests.json",
     "test-watch": "jest --coverage --watch",
     "chromatic": "chromatic --only-changed"
   }

package/src/components/Alert/Alert.tsx

@@ -8,13 +8,13 @@ import React, {
   memo,
 } from 'react';
 import classNames from 'classnames';
-import { Box } from '../Box/Box';
+import { Box, BoxProps } from '../Box/Box';
 import { Icon } from '../Icon/Icon';
 import styles from './Alert.module.scss';
 import { AlertVariant } from './Alert.types';
 import { ALERT_ICONS_MAP } from './Alert.constants';
 
-export interface AlertProps {
+interface AlertOwnProps {
   /**
    * The alert's contents.
    */
@@ -50,12 +50,11 @@ export interface AlertProps {
    * The type/color of the alert to show.
    */
   variant?: AlertVariant;
-  /**
-   * Additional props to be spread to rendered element
-   */
-  [x: string]: any; // eslint-disable-line
 }
 
+export type AlertProps = AlertOwnProps &
+  Omit<BoxProps<'div'>, keyof AlertOwnProps | 'as'>;
+
 const AlertComponent: FC<AlertProps> = ({
   children,
   className = '',

package/src/components/Badge/Badge.test.tsx

@@ -48,6 +48,18 @@ const getBadge = (text: string): HTMLElement =>
   screen.getByText(text).closest('.badge') as HTMLElement;
 
 describe('Badge', () => {
+  test('accepts attributes and refs for the element selected by as', () => {
+    const buttonRef = React.createRef<HTMLButtonElement>();
+
+    render(
+      <Badge as="button" type="button" disabled ref={buttonRef}>
+        Action
+      </Badge>
+    );
+
+    expect(buttonRef.current).toBeDisabled();
+  });
+
   test('Badge correctly renders with base props', () => {
     render(<Badge>hello</Badge>);
     const badge = getBadge('hello');

package/src/components/Badge/Badge.tsx

@@ -1,9 +1,14 @@
-import React, { Children, ReactNode, forwardRef } from 'react';
+import React, {
+  Children,
+  ReactElement,
+  ReactNode,
+  forwardRef,
+} from 'react';
 import classNames from 'classnames';
 import { ResponsiveProp } from '../../types';
 import { generateResponsiveClasses } from '../../lib/generateResponsiveClasses';
 import styles from './Badge.module.scss';
-import { Box, BoxProps } from '../Box/Box';
+import { Box, BoxElement, BoxProps, BoxRef } from '../Box/Box';
 
 export type BadgeSize = 'sm' | 'md' | 'lg';
 
@@ -50,7 +55,7 @@ const renderBadgeChildren = (children: ReactNode) =>
     )
   );
 
-export interface BadgeProps extends Omit<BoxProps, 'color' | 'radius'> {
+interface BadgeOwnProps {
   /**
    * The color of the badge. Accepts a hue, or one of the semantic names
    * (`danger`, `success`, `warning`, `info`) which map onto `red`, `green`, `yellow` and `blue`.
@@ -70,9 +75,22 @@ export interface BadgeProps extends Omit<BoxProps, 'color' | 'radius'> {
   variant?: BadgeVariant;
 }
 
-export const Badge = forwardRef<HTMLDivElement, BadgeProps>(
-  (
-    {
+export type BadgeProps<T extends BoxElement = 'div'> = BadgeOwnProps &
+  Omit<BoxProps<T>, keyof BadgeOwnProps>;
+
+type BadgeComponent = {
+  <T extends BoxElement>(
+    props: BadgeProps<T> & { as: T; ref?: BoxRef<T> }
+  ): ReactElement | null;
+  (props: BadgeProps<'div'> & { ref?: BoxRef<'div'> }): ReactElement | null;
+  displayName?: string;
+};
+
+const BadgeBaseComponent = <T extends BoxElement = 'div'>(
+  props: BadgeProps<T>,
+  ref: BoxRef<T>
+) => {
+    const {
       className = '',
       color = 'grey',
       radius = 'full',
@@ -80,9 +98,7 @@ export const Badge = forwardRef<HTMLDivElement, BadgeProps>(
       size = 'md',
       children,
       ...restProps
-    },
-    ref
-  ) => {
+    } = props as BadgeOwnProps & Omit<BoxProps<T>, keyof BadgeOwnProps>;
     const responsiveClasses = generateResponsiveClasses('size', size).map(
       (c) => styles[c]
     );
@@ -98,19 +114,35 @@ export const Badge = forwardRef<HTMLDivElement, BadgeProps>(
       styles[`radius-${radius}`]
     );
 
+    const boxProps = {
+      className: badgeClasses,
+      display: 'inline-flex',
+      alignItems: 'center',
+      direction: 'row',
+      ...restProps,
+    } as BoxProps<T>;
+
+    const badgeChildren = renderBadgeChildren(children);
+
+    if (boxProps.as) {
+      const boxPropsWithAs = boxProps as BoxProps<T> & { as: T };
+
+      return (
+        <Box<T> ref={ref} {...boxPropsWithAs}>
+          {badgeChildren}
+        </Box>
+      );
+    }
+
     return (
-      <Box
-        ref={ref}
-        className={badgeClasses}
-        display="inline-flex"
-        alignItems="center"
-        direction="row"
-        {...restProps}
-      >
-        {renderBadgeChildren(children)}
+      <Box ref={ref as BoxRef<'div'>} {...(boxProps as BoxProps<'div'>)}>
+        {badgeChildren}
       </Box>
     );
-  }
-);
+};
+
+// React.forwardRef cannot preserve a generic `as` parameter, so restore the
+// polymorphic call signature after wrapping the implementation.
+export const Badge = forwardRef(BadgeBaseComponent as never) as BadgeComponent;
 
 Badge.displayName = 'Badge';

package/src/components/Box/Box.mdx

@@ -9,7 +9,7 @@ import * as Stories from './Box.stories';
 A `<Box>` is a layout component to build UIs with consistent padding and spacing between elements.
 
 - Its content is arranged in a specified `direction`, with 'column' being the default
-- Renders a `<div />` element by default, but can be changed using `as`
+- Renders a `<div />` element by default, but can be changed using `as`. The element is never inferred from other props, so links must set `as="a"` alongside `href`
 - Allows you to specify the spacing between child elements using `gap`
 - Many props accept `ResponsiveProp` that take an object with keys that correspond to [breakpoint tokens](?path=/docs/foundation-design-tokens--docs#breakpoints).
 

package/src/components/Box/Box.stories.tsx

@@ -1726,7 +1726,7 @@ export const Focus = () => (
       focus={{
         shadow: 'lg',
       }}
-      tabIndex="0"
+      tabIndex={0}
       style={{ outline: 'none' }}
     >
       Card focus effect

package/src/components/Box/Box.test.tsx

@@ -4,7 +4,7 @@ import {
   CssOverflowValue,
   ResponsiveProp,
 } from '../../types';
-import { Box } from './Box';
+import { Box, boxPropsKeys } from './Box';
 import React from 'react';
 import { fireEvent, render } from '@testing-library/react';
 import {
@@ -20,6 +20,18 @@ import {
 describe('Box', () => {
   const renderBox = (props = {}) => render(<Box {...props}>Test Box</Box>);
 
+  test('accepts attributes for the element selected by as', () => {
+    const buttonRef = React.createRef<HTMLButtonElement>();
+
+    render(
+      <Box as="button" type="button" disabled ref={buttonRef}>
+        Action
+      </Box>
+    );
+
+    expect(buttonRef.current).toBeDisabled();
+  });
+
   describe('aria attributes', () => {
     test('aria-label is applied if set', () => {
       const { getByLabelText } = renderBox({ 'aria-label': 'test label' });
@@ -54,6 +66,17 @@ describe('Box', () => {
     expect(getByText('Test Box')).toHaveClass('hover:background-color-primary');
   });
 
+  test('renders hover classes that are not supported by focus', () => {
+    const { getByText } = renderBox({ hover: { fontSize: 'lg' } });
+    expect(getByText('Test Box')).toHaveClass('hover:font-size-lg');
+  });
+
+  test('lists all text wrapping props as Box props', () => {
+    expect(boxPropsKeys).toEqual(
+      expect.arrayContaining(['whiteSpace', 'wordBreak'])
+    );
+  });
+
   test('renders with proper focus classes', () => {
     const { getByText } = renderBox({ focus: { borderColor: 'primary' } });
     expect(getByText('Test Box')).toHaveClass('focus:border-color-primary');

package/src/components/Box/Box.tsx

@@ -31,9 +31,11 @@ import {
   TextTransform,
 } from '../../types';
 import {
+  ComponentPropsWithoutRef,
+  ComponentPropsWithRef,
   CSSProperties,
   Children,
-  FC,
+  ElementType,
   ReactElement,
   ReactNode,
   cloneElement,
@@ -41,12 +43,10 @@ import {
   forwardRef,
 } from 'react';
 
-import { KnownKeys } from '../../types/lib.types';
 import classNames from 'classnames';
 import { cssShorthandToClasses } from '../../lib/cssShorthandToClasses';
 import { generateResponsiveClasses } from '../../lib/generateResponsiveClasses';
 import { getDimensionCss } from '../../lib/getDimensionCss';
-import { getElementType } from '../../lib/getElementType';
 import styles from './Box.module.scss';
 
 const AUTO_FONT_COLOR_BACKGROUNDS: BackgroundColor[] = [
@@ -61,11 +61,7 @@ export type HoverableBoxProperties =
   | 'borderColor'
   | 'shadow'
   | 'background';
-export interface BoxProps {
-  /**
-   * The element type to be rendered.
-   */
-  as?: string;
+export interface BoxOwnProps {
   /**
    * How to align the contents along the cross axis.
    */
@@ -146,11 +142,11 @@ export interface BoxProps {
    * `* shadow`
    */
   focus?: {
-    background?: BoxProps['background'];
-    borderColor?: BoxProps['borderColor'];
-    borderWidth?: BoxProps['borderWidth'];
-    color?: BoxProps['color'];
-    shadow?: BoxProps['shadow'];
+    background?: BoxOwnProps['background'];
+    borderColor?: BoxOwnProps['borderColor'];
+    borderWidth?: BoxOwnProps['borderWidth'];
+    color?: BoxOwnProps['color'];
+    shadow?: BoxOwnProps['shadow'];
   };
   /**
    * The [font family token](/?path=/docs/foundation-design-tokens--docs#font-family) identifier for the Box's text
@@ -179,12 +175,12 @@ export interface BoxProps {
    * `* shadow`
    */
   hover?: {
-    background?: BoxProps['background'];
-    borderColor?: BoxProps['borderColor'];
-    borderWidth?: BoxProps['borderWidth'];
-    color?: BoxProps['color'];
-    fontSize?: BoxProps['fontSize'];
-    shadow?: BoxProps['shadow'];
+    background?: BoxOwnProps['background'];
+    borderColor?: BoxOwnProps['borderColor'];
+    borderWidth?: BoxOwnProps['borderWidth'];
+    color?: BoxOwnProps['color'];
+    fontSize?: BoxOwnProps['fontSize'];
+    shadow?: BoxOwnProps['shadow'];
   };
   /**
    * Sets the gaps (gutters) between rows and columns.
@@ -294,20 +290,41 @@ export interface BoxProps {
    * Can be responsive.
    */
   zIndex?: ZIndexSize | ResponsiveProp<ZIndexSize>;
+}
+
+export type BoxElement = ElementType;
+
+export type BoxProps<T extends BoxElement = 'div'> = BoxOwnProps & {
   /**
-   * Additional props to be spread to rendered element
+   * The element type to be rendered. Defaults to `div`.
+   *
+   * The element is no longer inferred from other props: passing `href` alone
+   * renders a `div` with an inert `href` attribute rather than an anchor, so
+   * links must set `as="a"` explicitly.
    */
-  [x: string]: any; // eslint-disable-line
-}
+  as?: T;
+} & Omit<ComponentPropsWithoutRef<T>, keyof BoxOwnProps | 'as'>;
+
+export type BoxRef<T extends BoxElement> = ComponentPropsWithRef<T>['ref'];
+
+type BoxComponent = {
+  <T extends BoxElement>(
+    props: BoxProps<T> & { as: T; ref?: BoxRef<T> }
+  ): ReactElement | null;
+  (props: BoxProps<'div'> & { ref?: BoxRef<'div'> }): ReactElement | null;
+  displayName?: string;
+};
 
 /**
  * A `<Box>` is a layout component to build UIs with consistent padding and spacing between
  * elements.
  */
-export const Box: FC<BoxProps> = forwardRef(
-  (
-    {
-      as = 'div',
+const BoxBaseComponent = <T extends BoxElement = 'div'>(
+  props: BoxProps<T>,
+  ref: BoxRef<T>
+) => {
+    const {
+      as,
       alignItems = undefined,
       alignContent = undefined,
       alignSelf = undefined,
@@ -352,9 +369,7 @@ export const Box: FC<BoxProps> = forwardRef(
       wordBreak = undefined,
       zIndex = undefined,
       ...restProps
-    },
-    ref
-  ) => {
+    } = props as BoxOwnProps & { as?: T };
     const heightCss = getDimensionCss('h', height);
     const widthCss = getDimensionCss('w', width);
     const maxHeightCss = getDimensionCss('mh', maxHeight);
@@ -369,7 +384,7 @@ export const Box: FC<BoxProps> = forwardRef(
       color ??
       (background === 'inverse'
         ? 'inverse'
-        : AUTO_FONT_COLOR_BACKGROUNDS.includes(background)
+        : background && AUTO_FONT_COLOR_BACKGROUNDS.includes(background)
         ? 'grey'
         : undefined);
 
@@ -411,16 +426,13 @@ export const Box: FC<BoxProps> = forwardRef(
 
     const getStatefulClasses = (
       stateKey: 'hover' | 'focus',
-      values: BoxProps['hover' | 'hover']
+      values: BoxOwnProps['hover' | 'focus']
     ) =>
       values // eslint-disable-line
         ? Object.entries(values).map(
             ([key, value]) =>
               cssPropertyMap[key].transformer(
-                `${stateKey}:${
-                  cssPropertyMap[key as keyof BoxProps['focus' | 'hover']]
-                    .classPrefix
-                }`,
+                `${stateKey}:${cssPropertyMap[key].classPrefix}`,
                 value
               ) // eslint-disable-line max-len
           )
@@ -629,7 +641,7 @@ export const Box: FC<BoxProps> = forwardRef(
       );
     }
 
-    const element = getElementType(Box, { as });
+    const element = as ?? 'div';
 
     return createElement(
       element,
@@ -641,52 +653,66 @@ export const Box: FC<BoxProps> = forwardRef(
       },
       children !== null && children !== undefined ? decoratedChildren : null
     );
-  }
-);
+};
+
+// React.forwardRef cannot preserve a generic `as` parameter, so restore the
+// polymorphic call signature after wrapping the implementation.
+export const Box = forwardRef(BoxBaseComponent as never) as BoxComponent;
 
 Box.displayName = 'Box';
 
-export const boxPropsKeys: (keyof Pick<BoxProps, KnownKeys<BoxProps>>)[] = [
-  'as',
-  'alignItems',
-  'alignContent',
-  'alignSelf',
-  'background',
-  'borderColor',
-  'borderWidth',
-  'className',
-  'childGap',
-  'children',
-  'color',
-  'columnGap',
-  'cursor',
-  'direction',
-  'display',
-  'flex',
-  'focus',
-  'fontFamily',
-  'fontSize',
-  'fontWeight',
-  'gap',
-  'height',
-  'hover',
-  'justifyContent',
-  'margin',
-  'maxHeight',
-  'minHeight',
-  'maxWidth',
-  'minWidth',
-  'overflow',
-  'padding',
-  'position',
-  'radius',
-  'rowGap',
-  'shadow',
-  'style',
-  'textAlign',
-  'textTransform',
-  'textWrap',
-  'wrap',
-  'width',
-  'zIndex',
-];
+// `boxPropsKeys` drives runtime prop routing (see SelectInputNative), so a key
+// missing from the list silently forwards a Box prop to the rendered element.
+// `Record` requires an entry for every `BoxOwnProps` key, so omitting one here
+// fails to compile.
+const boxPropsKeyMap: Record<keyof BoxOwnProps | 'as', true> = {
+  as: true,
+  alignItems: true,
+  alignContent: true,
+  alignSelf: true,
+  background: true,
+  borderColor: true,
+  borderWidth: true,
+  className: true,
+  childGap: true,
+  children: true,
+  color: true,
+  columnGap: true,
+  cursor: true,
+  direction: true,
+  display: true,
+  flex: true,
+  focus: true,
+  fontFamily: true,
+  fontSize: true,
+  fontWeight: true,
+  gap: true,
+  height: true,
+  hover: true,
+  justifyContent: true,
+  margin: true,
+  maxHeight: true,
+  minHeight: true,
+  maxWidth: true,
+  minWidth: true,
+  overflow: true,
+  padding: true,
+  position: true,
+  radius: true,
+  rowGap: true,
+  shadow: true,
+  style: true,
+  textAlign: true,
+  textTransform: true,
+  textWrap: true,
+  whiteSpace: true,
+  wrap: true,
+  width: true,
+  wordBreak: true,
+  zIndex: true,
+};
+
+export const boxPropsKeys = Object.keys(boxPropsKeyMap) as (
+  | keyof BoxOwnProps
+  | 'as'
+)[];

package/src/components/Card/Card.tsx

@@ -7,9 +7,13 @@ export interface CardProps extends BoxProps {
    * The Card's contents.
    */
   children?: ReactNode;
+  /**
+   * Whether the card uses its subdued background.
+   */
+  subdued?: boolean;
 }
 
-export const CardBaseComponent: React.FC<CardProps> = React.forwardRef(
+export const CardBaseComponent = React.forwardRef<HTMLDivElement, CardProps>(
   (
     {
       children,

package/src/components/Card/components/CardFooter/CardFooter.tsx

@@ -5,10 +5,6 @@ export interface CardFooterProps extends BoxProps {
    * Contents of the Footer.
    */
   children?: ReactNode;
-  /**
-   * Additional props to be spread to rendered element
-   */
-  [x: string]: any; // eslint-disable-line
 }
 
 export const CardFooter: FC<CardFooterProps> = ({

package/src/components/Card/components/CardHeader/CardHeader.tsx

@@ -2,7 +2,7 @@ import React, { FC, ReactNode } from 'react';
 import { Box, BoxProps } from '../../../Box/Box';
 import { Heading } from '../../../Heading/Heading';
 
-export interface CardHeaderProps extends BoxProps {
+interface CardHeaderOwnProps {
   /**
    * The title of the card
    */
@@ -13,6 +13,9 @@ export interface CardHeaderProps extends BoxProps {
   description?: ReactNode;
 }
 
+export type CardHeaderProps = CardHeaderOwnProps &
+  Omit<BoxProps<'div'>, keyof CardHeaderOwnProps | 'as'>;
+
 export const CardHeader: FC<CardHeaderProps> = ({
   children,
   title,

package/src/components/Card/components/CardSection/CardSection.tsx

@@ -4,7 +4,7 @@ import React, { FC, ReactNode } from 'react';
 import classNames from 'classnames';
 import styles from '../../Card.module.scss';
 
-export interface CardSectionProps extends BoxProps {
+interface CardSectionOwnProps {
   /**
    * Any valid background color token, or a `url()` for an image
    */
@@ -41,12 +41,11 @@ export interface CardSectionProps extends BoxProps {
    * Title for the section.
    */
   title?: ReactNode;
-  /**
-   * Additional props to be spread to rendered element
-   */
-  [x: string]: any; // eslint-disable-line
 }
 
+export type CardSectionProps = CardSectionOwnProps &
+  Omit<BoxProps<'div'>, keyof CardSectionOwnProps | 'as'>;
+
 export const CardSection: FC<CardSectionProps> = ({
   background = undefined,
   borderColor = undefined,

package/src/components/CheckboxInput/CheckboxInput.test.tsx

@@ -108,6 +108,23 @@ describe('CheckboxInput', () => {
     expect(checkbox.checked).toEqual(false);
   });
 
+  test.each([0, ''])('forwards the falsy value %p to the input', (value) => {
+    render(
+      <CheckboxInput
+        id="testCheckbox"
+        label="test checkbox"
+        isChecked={false}
+        onChange={() => null}
+        value={value}
+      />
+    );
+
+    expect(screen.getByRole('checkbox')).toHaveAttribute(
+      'value',
+      String(value)
+    );
+  });
+
   test('assigns the "aria-labelledby" attribute and calls FormLabel with expected props', () => {
     const { getByLabelText } = render(
       <CheckboxInput