build!: Allow direct imports and component normalization

.node-version

@@ -1 +1 @@
-18.15.0
+18.19.1

.storybook/USWDS.js

@@ -1,14 +1,15 @@
-import { create } from '@storybook/theming/create';
+import { create } from '@storybook/theming/create'
 
 export default create({
   brandTitle: 'U.S. Web Design System (USWDS)',
   brandUrl: 'https://github.com/trussworks/react-uswds',
-  brandImage: '/uswds.svg',
+  brandImage: 'uswds.svg',
   brandTarget: '_self',
   base: 'light',
 
   // Text
-  fontBase: "'Public Sans Web', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'",
+  fontBase:
+    "'Public Sans Web', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'",
   textColor: '#1b1b1b',
   inputTextColor: '#1b1b1b',
   textInverseColor: '#ffffff',
@@ -22,4 +23,4 @@ export default create({
   appBorderRadius: 4,
   inputBorder: '#5c5c5c',
   inputBorderRadius: 4,
-});
+})

.storybook/custom-styles.scss

@@ -1,4 +1,4 @@
-@forward '../src/styles/uswds-theme';
+@forward '../libSrc/styles/uswds-theme';
 @use 'uswds-core' as *;
 
 // Add custom styles for storybook implementation

.storybook/main.ts

@@ -1,7 +1,10 @@
 import type { StorybookConfig } from '@storybook/react-vite'
 
 const config: StorybookConfig = {
-  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  stories: [
+    '../libSrc/**/*.mdx',
+    '../libSrc/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+  ],
   addons: [
     '@storybook/addon-a11y',
     '@storybook/addon-docs',

.storybook/preview.ts

@@ -1,12 +1,12 @@
 import 'happo-plugin-storybook/register'
 
 import '@uswds/uswds/css/uswds.css'
-import '../src/styles/index.scss'
+import '../libSrc/styles/index.scss'
 import './custom-styles.scss'
 
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport'
-import { Preview } from '@storybook/react';
-import USWDS from './USWDS';
+import { Preview } from '@storybook/react'
+import USWDS from './USWDS'
 
 const preview: Preview = {
   parameters: {
@@ -20,9 +20,15 @@ const preview: Preview = {
       showPanel: true,
       storySort: {
         method: 'alphabetical',
-        order: ['Welcome', 'Design tokens', 'Page Templates', 'Components', 'Other'],
+        order: [
+          'Welcome',
+          'Design tokens',
+          'Page Templates',
+          'Components',
+          'Other',
+        ],
       },
     },
   },
 }
-export default preview;
+export default preview

custom.d.ts

@@ -31,3 +31,5 @@ declare namespace globalThis {
     MSStream: object
   }
 }
+
+declare module '@uswds/compile'

gulpfile.ts

@@ -0,0 +1,29 @@
+import uswds from '@uswds/compile'
+
+uswds.settings.version = 3
+uswds.paths.dist = {
+  ...uswds.paths.dist,
+  theme: 'lib/dist/assets/uswds/sass',
+  img: 'lib/dist/assets/uswds/img',
+  fonts: 'lib/dist/assets/uswds/fonts',
+  js: 'lib/dist/assets/uswds/js',
+  css: 'lib/dist/assets/uswds/css',
+}
+
+export {
+  settings,
+  paths,
+  sprite,
+  copyTheme,
+  copyFonts,
+  copyImages,
+  copyJS,
+  copyAssets,
+  copyAll,
+  compileSass,
+  compileIcons,
+  compile,
+  updateUswds,
+  init,
+  watch,
+} from '@uswds/compile'

src/components/Alert/Alert.stories.tsx → libSrc/components/Alert/Alert.stories.tsx

@@ -1,7 +1,7 @@
 import React from 'react'
-import { Alert } from './Alert'
 
-import { Button } from '../Button/Button'
+import Alert from './Alert.js'
+import Button from '../Button/ButtonForwardRef.js'
 
 export default {
   title: 'Components/Alert',

src/components/Alert/Alert.test.tsx → libSrc/components/Alert/Alert.test.tsx

@@ -1,8 +1,8 @@
 import React from 'react'
 import { render } from '@testing-library/react'
 
-import { Alert } from './Alert'
-import { HeadingLevel } from '../../types/headingLevel'
+import Alert from './Alert.js'
+import type { HeadingLevel } from '../../types/headingLevel.js'
 
 describe('Alert component', () => {
   beforeEach(() => {

src/components/Alert/Alert.tsx → libSrc/components/Alert/Alert.tsx

@@ -1,12 +1,12 @@
 import React from 'react'
 import classnames from 'classnames'
 
-import { HeadingLevel } from '../../types/headingLevel'
+import type { HeadingLevel } from '../../types/headingLevel.js'
 
 import styles from './Alert.module.scss'
 
-type AlertProps = {
-  type: 'success' | 'warning' | 'error' | 'info'
+export interface BaseAlertProps {
+  type?: 'success' | 'warning' | 'error' | 'info'
   heading?: React.ReactNode
   headingLevel: HeadingLevel
   children?: React.ReactNode
@@ -16,7 +16,9 @@ type AlertProps = {
   validation?: boolean
 }
 
-export const Alert = ({
+export type AlertProps = BaseAlertProps & JSX.IntrinsicElements['div']
+
+const Alert = ({
   type,
   heading,
   headingLevel,
@@ -27,7 +29,7 @@ export const Alert = ({
   className,
   validation,
   ...props
-}: AlertProps & React.HTMLAttributes<HTMLDivElement>): React.ReactElement => {
+}: AlertProps): React.ReactElement => {
   const classes = classnames(
     'usa-alert',
     {

src/components/Button/Button.stories.tsx → libSrc/components/Button/Button.stories.tsx

@@ -1,5 +1,6 @@
 import React from 'react'
-import { Button } from './Button'
+
+import Button from './Button.js'
 
 export default {
   title: 'Components/Button',

src/components/Button/Button.test.tsx → libSrc/components/Button/Button.test.tsx

@@ -1,8 +1,9 @@
-import React from 'react'
+import React, { createRef } from 'react'
 import { render, fireEvent } from '@testing-library/react'
 
+import Button from './Button.js'
+
 vi.mock('../../deprecation')
-import { Button } from './Button'
 
 describe('Button component', () => {
   beforeEach(() => {
@@ -14,6 +15,17 @@ describe('Button component', () => {
     expect(queryByTestId('button')).toBeInTheDocument()
   })
 
+  it('renders ref', () => {
+    const testRef = createRef<HTMLButtonElement>()
+    const { queryByTestId } = render(
+      <Button type="button" _ref={testRef}>
+        Click Me
+      </Button>
+    )
+    expect(queryByTestId('button')).toBeInTheDocument()
+    expect(testRef.current).toBeInstanceOf(HTMLButtonElement)
+  })
+
   describe('renders uswds classes', () => {
     it('usa-button', () => {
       const { queryByTestId } = render(<Button type="button">Click Me</Button>)

src/components/Button/Button.tsx → libSrc/components/Button/Button.tsx

@@ -1,8 +1,8 @@
 import React from 'react'
 import classnames from 'classnames'
 
-export type ButtonProps = {
-  type: 'button' | 'submit' | 'reset'
+export interface BaseButtonProps {
+  type?: 'button' | 'submit' | 'reset'
   children: React.ReactNode
   secondary?: boolean
   base?: boolean
@@ -11,10 +11,14 @@ export type ButtonProps = {
   inverse?: boolean
   size?: 'big'
   unstyled?: boolean
+  // TODO: Remove underscore, or remove property entirely if handled by new React 19 typing
+  _ref?: React.ForwardedRef<HTMLButtonElement>
 }
 
-export const Button = ({
-  type,
+export type ButtonProps = BaseButtonProps & JSX.IntrinsicElements['button']
+
+function Button({
+  type = 'button',
   children,
   secondary,
   base,
@@ -23,10 +27,10 @@ export const Button = ({
   inverse,
   size,
   unstyled,
-  onClick,
   className,
+  _ref,
   ...defaultProps
-}: ButtonProps & JSX.IntrinsicElements['button']): React.ReactElement => {
+}: ButtonProps): React.ReactElement {
   const classes = classnames(
     'usa-button',
     {
@@ -46,8 +50,8 @@ export const Button = ({
     <button
       type={type}
       className={classes}
-      onClick={onClick}
       data-testid="button"
+      ref={_ref}
       {...defaultProps}>
       {children}
     </button>

libSrc/components/Button/ButtonForwardRef.tsx

@@ -0,0 +1,13 @@
+import React, { forwardRef } from 'react'
+import Button, { ButtonProps } from './Button.js'
+
+const ButtonForwardRef = forwardRef(function ButtonForwardRef(
+  props: ButtonProps,
+  ref: React.ForwardedRef<HTMLButtonElement>
+) {
+  return <Button _ref={ref} {...props} />
+})
+
+export type { BaseButtonProps, ButtonProps } from './Button.js'
+
+export default ButtonForwardRef

src/components/ButtonGroup/ButtonGroup.stories.tsx → libSrc/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -1,7 +1,8 @@
 import React from 'react'
-import { ButtonGroup } from './ButtonGroup'
-import { Button } from '../Button/Button'
-import { Link } from '../Link/Link'
+
+import ButtonGroup from './ButtonGroup.js'
+import Button from '../Button/ButtonForwardRef.js'
+import Link from '../Link/Link.js'
 
 export default {
   title: 'Components/Button groups',

src/components/ButtonGroup/ButtonGroup.test.tsx → libSrc/components/ButtonGroup/ButtonGroup.test.tsx

@@ -1,7 +1,7 @@
 import React from 'react'
 import { render } from '@testing-library/react'
 
-import { ButtonGroup } from './ButtonGroup'
+import ButtonGroup from './ButtonGroup.js'
 
 describe('ButtonGroup component', () => {
   it('renders without errors', () => {

src/components/ButtonGroup/ButtonGroup.tsx → libSrc/components/ButtonGroup/ButtonGroup.tsx

@@ -1,13 +1,16 @@
 import React from 'react'
 import classnames from 'classnames'
 
-type ButtonGroupProps = {
+export interface BaseButtonGroupProps {
   children: React.ReactNode
   className?: string
   type?: 'default' | 'segmented'
-} & JSX.IntrinsicElements['ul']
+}
+
+export type ButtonGroupProps = BaseButtonGroupProps &
+  JSX.IntrinsicElements['ul']
 
-export const ButtonGroup = ({
+const ButtonGroup = ({
   className,
   children,
   type = 'default',

src/components/Icon/Icon.stories.tsx → libSrc/components/Icon/Icon.stories.tsx

@@ -1,6 +1,6 @@
 import React from 'react'
 
-import { Icon } from './Icons'
+import Icon from './Icon.js'
 
 type StorybookArgs = {
   size: 3 | 4 | 5 | 6 | 7 | 8 | 9

src/components/Icon/Icon.test.tsx → libSrc/components/Icon/Icon.test.tsx

@@ -1,7 +1,7 @@
 import React from 'react'
 import { render, screen } from '@testing-library/react'
 
-import { Icon } from './Icons'
+import Icon from './Icon.js'
 
 describe('Icon component', () => {
   it('renders without errors', () => {

src/components/Icon/Icons.ts → libSrc/components/Icon/Icon.ts

@@ -242,10 +242,10 @@ import ZoomInSvg from '@uswds/uswds/img/usa-icons/zoom_in.svg?svgr'
 import ZoomOutMapSvg from '@uswds/uswds/img/usa-icons/zoom_out_map.svg?svgr'
 import ZoomOutSvg from '@uswds/uswds/img/usa-icons/zoom_out.svg?svgr'
 
-import { makeUSWDSIcon, IconProps } from './Icon'
+import { makeUSWDSIcon, type IconProps } from './utils.js'
 import React from 'react'
 
-export class Icon {
+class Icon {
   public static AccessibilityNew: React.ComponentType<IconProps> =
     makeUSWDSIcon(AccessibilityNewSvg)
 
@@ -926,4 +926,6 @@ export class Icon {
     makeUSWDSIcon(ZoomOutSvg)
 }
 
+export type { BaseIconProps, IconProps } from './utils.js'
+
 export default Icon

src/components/Icon/Icons.stories.tsx → libSrc/components/Icon/Icons.stories.tsx

@@ -1,6 +1,6 @@
 import React from 'react'
 
-import { Icon } from './Icons'
+import Icon from './Icon.js'
 
 type StorybookArgs = {
   size: 3 | 4 | 5 | 6 | 7 | 8 | 9

src/components/Icon/Icon.tsx → libSrc/components/Icon/utils.tsx

@@ -1,14 +1,14 @@
 import React from 'react'
 import classnames from 'classnames'
 
-interface USWDSIconProps {
+export interface BaseIconProps {
   focusable?: boolean
   role?: string
   size?: 3 | 4 | 5 | 6 | 7 | 8 | 9
   className?: string
 }
 
-export type IconProps = USWDSIconProps & JSX.IntrinsicElements['svg']
+export type IconProps = BaseIconProps & JSX.IntrinsicElements['svg']
 
 export const makeUSWDSIcon = (
   Component: React.ComponentType<IconProps>