docs: Documentation Audit changes

docs/contributing.md

@@ -1,6 +1,6 @@
 # Contributing
 
-We are glad you are interested to contribute to this project! Please make sure you've seen the README and license for this project before continuing further. If you work for Truss, check out the [guide for Trussels](./for_trussels.md) as well.
+We are glad you are interested to contribute to this project! Please make sure you've seen the [README](../README.md) and [license](../README.md#license) for this project before continuing further. If you work for Truss, check out the [guide for Trussels](./for_trussels.md) as well.
 
 We welcome contributions in the form of comments, issues, or pull requests with code changes. If you see an error, have a question, or want to share feedback open an issue to discuss. This repository is governed by the [Contributor Covenant](../CODE_OF_CONDUCT.md)
 

docs/faqs.md

@@ -8,6 +8,12 @@
 
   - Most components are standalone and can be dropped into your codebase anywhere. Assuming that you have imported the library and styles properly, please reference the project [Storybook](https://trussworks.github.io/react-uswds/) to learn how to use the component in your code. Click any of the component stories and you can "Show Code" to see the usage of the component in context. Storybook also has a tab on each story called "Docs" which will allow you to see full documentation of the types of props you can use. In addition, we have an example app (see `/example` directory) which shows how to use `react-uswds` components with other widely used Javascript/React dependencies.
 
+- If something is not behaving as it should, or if I believe I've spotted a problem, where should I open an issue?
+
+  - If a `react-uswds` component is displaying or behaving unexpectedly there may be an issue with the `react-uswds`, however the issue may exist within the [USWDS](https://designsystem.digital.gov/) itself. For the fastest, most effective resolution of the issue we recommend verifying if the issue is present in the base [USWDS component(s)](https://designsystem.digital.gov/components/) first.
+    - If so, please [file the issue directly within the USDWS Github repository](https://github.com/uswds/uswds/issues/new).
+    - If not, please [file an issue with us](https://github.com/trussworks/react-uswds/issues/new/choose).
+
 - What's next? What is the roadmap for this project?
 
   - This library is active development. We use this library on our own projects at [Truss](https://truss.works/) and with clients. Follow library development and maintenance work in the [react-uswds Github project](https://github.com/trussworks/react-uswds/projects). In addition, reference the [milestones](https://github.com/trussworks/react-uswds/milestones) to track parity with various USWDS versions. There is no singular roadmap; our progress is shaped by those who contribute to the library, and by changes in the uswds specification. If you have work you'd like to see done earlier/sooner, please submit a PR. We welcome your contribution!

docs/for_trussels.md

@@ -30,7 +30,7 @@ Regardless of whether you are on client work or Reserve, it is _up to each indiv
 
 Typically any security alerts we receive will be related to third-party dependencies. This repo is currently configured so that Dependabot will automatically open PRs that fix dependency vulnerabilities, so ideally most of the time manual intervention is not needed. There may also be periods of time during which an alert is issued, but the related dependencies have not yet updated -- in this case, we usually choose to accept the risk of waiting until the updates have been released. However, if an exceptional case comes up -- such as a high severity vulnerability or even a vulnerability within this library -- and you aren't sure how to handle it, you can ask for help in one of the following Truss Slack channels (in order of relevance): #react-uswds, #g-frontend, #infrasec, #engineering
 
-### Merging External PRS
+### Merging External PRs
 
 Currently our CI cannot run on external PRs (work from outside the Truss organization) and this prevents merge. Instead, we pull PRs into a separate branch that a CODEOWNER creates [using this script](https://github.com/jklukas/git-push-fork-to-upstream-branch). We then close the external contribution PR [with a comment](https://github.com/trussworks/react-uswds/pull/375#issuecomment-668116811) explaining what's going. This allows automation to run properly. This is temporary solution.
 

docs/styles_and_assets.md

@@ -76,7 +76,9 @@ $theme-hero-image: '~uswds/src/img/hero.png';
 
 ### Icons
 
-[USWDS recommends using Font Awesome](https://designsystem.digital.gov/components/icons/), and that project [provides a package for use with React](https://github.com/FortAwesome/react-fontawesome).
+> **NOTE:** Newer USWDS versions have implemented [icons as a part of the USWDS](https://designsystem.digital.gov/components/icons/). These are on the `react-uswds` road map via [#992](https://github.com/trussworks/react-uswds/issues/992). This documentation will be updated once the `react-uswds` implementation is complete.
+
+USWDS previously recommended using [Font Awesome](https://fontawesome.com/), which [provides a package for use with React](https://github.com/FortAwesome/react-fontawesome).
 
 To add this to your project, install react-font-awesome and at least one style of icon:
 

src/components/Accordion/Accordion.stories.tsx

@@ -5,11 +5,15 @@ export default {
   title: 'Components/Accordion',
   component: Accordion,
   parameters: {
-    info: `
-USWDS 2.0 Accordion component
+    docs: {
+      description: {
+        component: `
+### USWDS 2.0 Accordion component
 
 Source: https://designsystem.digital.gov/components/accordion/
 `,
+      },
+    },
   },
 }
 

src/components/Accordion/Accordion.tsx

@@ -16,9 +16,14 @@ interface AccordionProps {
   className?: string
 }
 
-export const AccordionItem = (props: AccordionItem): React.ReactElement => {
-  const { title, id, content, expanded, className, handleToggle } = props
-
+export const AccordionItem = ({ 
+  title,
+  id,
+  content,
+  expanded,
+  className,
+  handleToggle
+}: AccordionItem): React.ReactElement => {
   const headingClasses = classnames('usa-accordion__heading', className)
   const contentClasses = classnames(
     'usa-accordion__content',
@@ -50,9 +55,7 @@ export const AccordionItem = (props: AccordionItem): React.ReactElement => {
   )
 }
 
-export const Accordion = (props: AccordionProps): React.ReactElement => {
-  const { bordered, items, className } = props
-
+export const Accordion = ({ bordered, items, className }: AccordionProps): React.ReactElement => {
   const [openItems, setOpenState] = useState(
     items.filter((i) => !!i.expanded).map((i) => i.id)
   )

src/components/Alert/Alert.stories.tsx

@@ -7,11 +7,15 @@ export default {
   title: 'Components/Alert',
   component: Alert,
   parameters: {
-    info: `
-USWDS 2.0 Alert component
+    docs: {
+      description: {
+        component: `
+### USWDS 2.0 Alert component
 
 Source: https://designsystem.digital.gov/components/alert/
 `,
+      },
+    },
   },
 }
 

src/components/Button/Button.stories.tsx

@@ -5,11 +5,15 @@ export default {
   title: 'Components/Button',
   component: Button,
   parameters: {
-    info: `
-USWDS 2.0 Button component
+    docs: {
+      description: {
+        component: `
+### USWDS 2.0 Button component
 
 Source: https://designsystem.digital.gov/components/button/
 `,
+      },
+    },
   },
 }
 

src/components/Button/Button.tsx

@@ -26,10 +26,7 @@ interface ButtonProps {
   unstyled?: boolean
 }
 
-export const Button = (
-  props: ButtonProps & JSX.IntrinsicElements['button']
-): React.ReactElement => {
-  const {
+export const Button = ({
     type,
     children,
     secondary,
@@ -45,7 +42,7 @@ export const Button = (
     onClick,
     className,
     ...defaultProps
-  } = props
+  }: ButtonProps & JSX.IntrinsicElements['button']): React.ReactElement => {
 
   if (big) {
     deprecationWarning('Button property big is deprecated.  Use size')

src/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -7,11 +7,15 @@ export default {
   title: 'Components/Button groups',
   component: ButtonGroup,
   parameters: {
-    info: `
-USWDS 2.0 ButtonGroup component
+    docs: {
+      description: {
+        component: `
+### USWDS 2.0 ButtonGroup component
 
 Source: https://designsystem.digital.gov/components/button-groups/
 `,
+      },
+    },
   },
 }
 

src/components/ButtonGroup/ButtonGroup.tsx

@@ -7,9 +7,12 @@ type ButtonGroupProps = {
   type?: 'default' | 'segmented'
 } & JSX.IntrinsicElements['ul']
 
-export const ButtonGroup = (props: ButtonGroupProps): React.ReactElement => {
-  const { className, children, type = 'default', ...restProps } = props
-
+export const ButtonGroup = ({ 
+  className,
+  children,
+  type = 'default',
+  ...restProps 
+}: ButtonGroupProps): React.ReactElement => {
   const classes = classnames(
     'usa-button-group',
     {

src/components/Footer/Address/Address.stories.tsx

@@ -5,11 +5,15 @@ export default {
   title: 'Components/Footer/Address',
   component: Address,
   parameters: {
-    info: `
-      Display address items (most likely links or simple text) in a row, wrapped in address tag.  Used in USWDS 2.0 Footer component.
+    docs: {
+      description: {
+        component: `
+Display address items (most likely links or simple text) in a row, wrapped in address tag.  Used in USWDS 2.0 Footer component.
 
-      Source: https://designsystem.digital.gov/components/form-controls/#footer
-      `,
+Source: https://designsystem.digital.gov/components/form-controls/#footer
+`,
+      },
+    },
   },
 }
 

src/components/Footer/Footer/Footer.stories.tsx

@@ -18,11 +18,15 @@ export default {
   title: 'Components/Footer',
   component: Footer,
   parameters: {
-    info: `
-  USWDS 2.0 Footer component
+    docs: {
+      description: {
+        component: `
+### USWDS 2.0 Footer component
 
-  Source: https://designsystem.digital.gov/components/form-controls/#footer
-    `,
+Source: https://designsystem.digital.gov/components/form-controls/#footer
+`,
+      },
+    },
   },
 }
 

src/components/Footer/FooterNav/FooterNav.stories.tsx

@@ -8,11 +8,15 @@ export default {
   title: 'Components/Footer/FooterNav',
   component: FooterNav,
   parameters: {
-    info: `
-     Display single list of nav items, or grouped nav items in an extended nav. Used in USWDS 2.0 Footer component.
+    docs: {
+      description: {
+        component: `
+Display single list of nav items, or grouped nav items in an extended nav. Used in USWDS 2.0 Footer component.
 
-    Source: https://designsystem.digital.gov/components/form-controls/#footer
-    `,
+Source: https://designsystem.digital.gov/components/form-controls/#footer
+`,
+      },
+    },
   },
 }
 

src/components/Footer/Logo/Logo.stories.tsx

@@ -9,11 +9,15 @@ export default {
   title: 'Components/Footer/Logo',
   component: Logo,
   parameters: {
-    info: `
-    Display logo image with optional heading.  Used in USWDS 2.0 Footer component.
+    docs: {
+      description: {
+        component: `
+Display logo image with optional heading.  Used in USWDS 2.0 Footer component.
 
-    Source: https://designsystem.digital.gov/components/form-controls/#footer
-    `,
+Source: https://designsystem.digital.gov/components/form-controls/#footer
+`,
+      },
+    },
   },
 }
 

src/components/Footer/SocialLinks/SocialLinks.stories.tsx

@@ -6,11 +6,15 @@ export default {
   title: 'Components/Footer/SocialLinks',
   component: SocialLinks,
   parameters: {
-    info: `
-    Display social links in styled row. Used in USWDS 2.0 Footer component.
-
-  Source: https://designsystem.digital.gov/components/form-controls/#footer
-  `,
+    docs: {
+      description: {
+        component: `
+Display social links in styled row. Used in USWDS 2.0 Footer component.
+
+Source: https://designsystem.digital.gov/components/form-controls/#footer
+`,
+      },
+    },
   },
 }
 

src/components/Footer/SocialLinks/SocialLinks.tsx

@@ -6,10 +6,9 @@ type SocialLinksProps = {
   links: React.ReactNode[]
 }
 
-export const SocialLinks = (
-  props: SocialLinksProps & JSX.IntrinsicElements['div']
-): React.ReactElement => {
-  const { className, links } = props
+export const SocialLinks = ({ 
+  className, links
+}: SocialLinksProps & JSX.IntrinsicElements['div']): React.ReactElement => {
   const classes = classnames(
     'usa-footer__social-links grid-row grid-gap-1',
     className

src/components/GovBanner/GovBanner.stories.tsx

@@ -1,7 +1,21 @@
 import React from 'react'
 import { GovBanner } from './GovBanner'
 
-export default { title: 'Components/Banner', component: GovBanner }
+export default { 
+  title: 'Components/Banner',
+  component: GovBanner,
+  parameters: {
+    docs: {
+      description: {
+        component: `
+### USWDS 2.0 Banner component
+
+Source: https://designsystem.digital.gov/components/banner/
+`,
+      },
+    },
+  },
+}
 
 export const govBannerDefault = (): React.ReactElement => (
   <GovBanner aria-label="Official government website" />

src/components/GovBanner/GovBanner.tsx

@@ -101,15 +101,12 @@ interface GovBannerProps {
   language?: Language
 }
 
-export const GovBanner = (
-  props: GovBannerProps & JSX.IntrinsicElements['section']
-): React.ReactElement => {
-  const {
-    tld = '.gov',
-    language = 'english',
-    className,
-    ...sectionProps
-  } = props
+export const GovBanner = ({
+  tld = '.gov',
+  language = 'english',
+  className,
+  ...sectionProps
+}: GovBannerProps & JSX.IntrinsicElements['section']): React.ReactElement => {
   const [isOpen, setOpenState] = useState(false)
 
   const classes = classnames('usa-banner', className)

src/components/Link/Link.stories.tsx

@@ -5,9 +5,13 @@ export default {
   title: 'Components/Typography/Link',
   component: Link,
   parameters: {
-    info: `Link component
-
-    Based on Typography guide: https://designsystem.digital.gov/components/typography/#links`,
+    docs: {
+      description: {
+        component: `
+Based on Typography guide: https://designsystem.digital.gov/components/typography/#links
+`,
+      },
+    },
   },
 }
 

src/components/Modal/Modal.stories.tsx

@@ -8,7 +8,15 @@ export default {
   title: 'Other/Modal',
   component: Modal,
   parameters: {
-    info: `Truss-designed component`,
+    docs: {
+      description: {
+        component: `
+Truss-designed component
+
+**Note:** This component has been deprecated and is scheduled for removal.
+`,
+      },
+    },
   },
 }
 

src/components/Search/Search.stories.tsx

@@ -5,11 +5,15 @@ export default {
   title: 'Components/Search',
   component: Search,
   parameters: {
-    info: `
-USWDS 2.0 Search component
+    docs: {
+      description: {
+        component: `
+### USWDS 2.0 Search component
 
 Source: https://designsystem.digital.gov/components/search/
 `,
+      },
+    },
   },
 }