docs: clean up documentation post v14 (#1882)

* also update sub-component docs and React type usages

.storybook/components/Docs/Guidelines/CodeGuidelines.stories.mdx

@@ -460,7 +460,7 @@ i.e. in `src/components/{componentFolder}/index.ts`
 export { ComponentName as default } from './ComponentName';
 ```
 
-and in `src/index.ts`
+...and in `src/index.ts`
 
 ```tsx
 ...
@@ -470,11 +470,11 @@ export { default as ComponentName } from './components/ComponentName';
 
 ### Children
 
-When a component uses `children` as a prop, use the type `React.ReactNode` unless context dictates otherwise, including `ReactNode` as a named import.
+When a component uses `children` as a prop, use the type `ReactNode` unless context dictates otherwise, including `ReactNode` as a named import.
 
 ```tsx
-import React, { ReactNode } from 'react';
-
+import React, from 'react';
+import type { ReactNode } from 'react';
 ...
 
 export const ComponentName = ({ children }: { children: ReactNode }) => {
@@ -531,7 +531,7 @@ return <div className={componentClassName} {...other} />;
 
 ### Compound Components
 
-Certain components (such as `<Tabs />` and `<Table />`) require splitting up into smaller subcomponents.
+Certain components (such as `<Tabs />` and `<Table />`) require splitting up into smaller sub-components.
 
 By default, we err towards more centralized control over the component architecture in order to prevent undesired results (for instance, we don't want users to put a `<Card />` inside of `<Breadcrumbs />`). However, certain components will require more flexibility and will therefore be architected to be composable and flexible (such as `<Card>`).
 
@@ -541,10 +541,10 @@ By default, we err towards more centralized control over the component architect
 - Compound component children must be declared within the parent component file.
 - Compound component children names must always begin with the parent name. A parent component `Table` means that all child components related to it must begin with `Table` (such as `Table.Body`, `Table.Row` and `Table.Cell`).
 - Compound components never have an associated `.stories.tsx` file as they rely on the parent component's stories to render properly.
-- Compound components should be exported as subcomponents from their parent component file for easier usage. For example, at the bottom of `Card.tsx`, add the lines:
+- Compound components should be exported as sub-components from their parent component file for easier usage. For example, at the bottom of `Card.tsx`, add the lines:
 
 ```ts
-// This demonstrates how bound subcomponents are attached
+// This demonstrates how bound sub-components are attached
 Card.Header = CardHeader;
 Card.Footer = CardFooter;
 ```
@@ -571,12 +571,10 @@ EDS adheres to the following API naming conventions:
 The default option should be the one most commonly used in order to reduce friction for developers using the components.
 
 - `variant` should be used for primary _stylistic_ variations of a component, such as (e.g. `<Card variant="bordered">` or `<Button variant="secondary">`). `variant` should be used if there is primarily one variable used to manipulate the component style.
-- `inverted` should be used consistently for stylistic `variation`s that "invert" the color schemes (e.g. `inverted=true`) to work on a darker background.
-- `size` should be used for adjusting size attributes (e.g. `<Button variant="secondary" size="sm">` or `<Button size="md"`>). Use abbreviations for sizes (ex: `xs`, `sm`, `md`, `lg`).
+- `size` should be used for adjusting size attributes (e.g. `<Button variant="secondary" size="sm">` or `<Button size="md"`>). Use abbreviations for sizes (ex: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`).
 - `behavior` should be used for functional variations of a pattern, such as `<Banner behavior="dismissable">`. Additional non-exclusive behaviors should be handled using boolean props prefixed with `is` (e.g. `isSticky` and `isDismissable`).
 - `orientation` should be used for controlling the layout or orientation of a component (e.g. `<ButtonGroup orientation="stacked">`)
 - `disabled` boolean should be used to control the interactivity of a component (e.g. `<Button disabled />`)
-- `align` should be used for aligning content, and should include `left` (default), `center`, `right` if needed.
 - `verticalAlign` should be used for vertically aligning content, and should include `top`, `middle`, `bottom` if needed.
 
 ### Text, Labels, Titles, and Children
@@ -585,7 +583,7 @@ The default option should be the one most commonly used in order to reduce frict
 - For headings, default to `title`, such as `<PageHeader title="My Page Title">`.
 - Default to `description` for text that serves as a descriptor, such as `<PageHeader title="Project name" description="Brief overview of the project..." />`
 - For form-related components, use the semantic `label` or `legend` (e.g. `<TextField label="first name" />` and `<Fieldset.Legend text="Grade level">`).
-- `children` can be used for components that only have one main block of content being passed in (so there will be no confusion with other content props) and when it's safe for that content to be a `ReactNode`. (If it's important for the content to only come in the form of a string, use a different prop name, like `text`.)
+- `children` can be used for components that only have one main block of content being passed in (so there will be no confusion with other content props) and when it's safe for that content to be a `ReactNode`. (If it's important for the content to only come in the form of a string, restrict the type to `string`).
 
 ### Tag name
 

.storybook/components/Docs/Guidelines/Components.stories.mdx

@@ -21,7 +21,7 @@ yarn add @chanzuckerberg/eds
 Next, import any needed components from the EDS component library into your application like so:
 
 ```js
-import { Button, Grid } from '@chanzuckerberg/eds';
+import { Button } from '@chanzuckerberg/eds';
 ```
 
 From there, call EDS components in your React application and pass in the desired values into each component's API:
@@ -42,16 +42,14 @@ If you have questions or are experiencing any issues when working with EDS's com
 
 ### Creating a component
 
-**NOTE**: Refer to this [Tag](https://github.com/chanzuckerberg/edu-design-system/tree/upcoming-components) for examples of potential upcoming components. If you see one you like, you can use it as a baseline for implementation.
-
 1. To create a component, run `yarn plop` in the command line.
 2. The command will ask, "What is your component name?" Add your component name (you can either type `PageHeader` or `page header` and it will automatically generate the proper casing).
 3. Edit component source code in accordance with [EDS's code guidelines][code-guidelines]
 4. Create relevant stories for all component variants
 
 ### Component Beta status
 
-When components are first created using the `plop` feature, they're given a beta tag in the `.stories` file and a line is added to the component docstring stating that the component is in beta. When the component is first officially released/announced internally, the component will be in beta, but it will leave beta in the following release. We expect these releases to happen about once/month, and the removal of the beta information will happen as part of the release process.
+When components are first created using the `plop` feature, they're given a beta tag in the `.stories` file and a line is added to the component docstring stating that the component is in beta. When the component is first officially released/announced internally, the component will be in beta, but it will leave beta in the following release.
 
 Exceptions can be made for components that are still fluctuating and experiencing a lot of changes when the second release comes around.
 
@@ -64,7 +62,7 @@ The component stucture is as follows:
 ```
 Components
 --Component Name
-----Component Stories
+----Component Stories & Files
 ```
 
 [code-guidelines]: ./?path=/story/documentation-guidelines-code-guidelines--page

.storybook/components/Docs/Guidelines/Layout.stories.mdx

@@ -7,13 +7,6 @@ import {InlineNotification} from "../../../../src";
 
 <InlineNotification text="The layout components are being deprecated in favor of using TailwindCSS" variant="warning" />
 
-This includes the following:
-
-* `Grid` and `GridItem`
-* `Layout` and `LayoutSection`
-* `LayoutContainer`
-* `LayoutLinelength`
-
 Please refer to our documentation [on ZeroHeight](https://eds.czi.design/styleguide/s/36770/p/17f0a9-layout/b/66febf)
 for suggested alternatives and patterns.
 

.storybook/components/Docs/Guidelines/Typography.stories.mdx

@@ -37,7 +37,7 @@ When defining a new usage, you can refer to the variable by name
       "typography": {
         "headline": {
           "lg": {
-            "value": "var(--eds-typography-preset-001-bold)"
+            "value": "{eds.typography.preset.001.bold}"
           }
         }
       }
@@ -71,10 +71,10 @@ And defining tier 3 tokens using lower token values:
         "tab": {
           "lg": {
             "@": {
-              "value": "var(--eds-typography-preset-006-light)"
+              "value": "{eds.typography.preset.006.light}"
             },
             "active": {
-              "value": "var(--eds-typography-preset-006)"
+              "value": "{eds.typography.preset.006}"
             }
           },
         }

.storybook/components/TokenSpecimen/TokenSpecimen.tsx

@@ -1,11 +1,12 @@
 import clsx from 'clsx';
 import React from 'react';
+import type { ReactNode } from 'react';
 import './TokenSpecimen.css';
 
 type Props = {
   name: string;
   value: any;
-  children?: React.ReactNode;
+  children?: ReactNode;
   comment?: string;
   inlineStyles?: Record<string, string>;
   variant?: string;

src/components/Accordion/Accordion.tsx

@@ -1,6 +1,7 @@
 import { Disclosure } from '@headlessui/react';
 import clsx from 'clsx';
 import React, { createContext, useContext } from 'react';
+import type { ReactNode } from 'react';
 import { ENTER_KEYCODE, SPACEBAR_KEYCODE } from '../../util/keycodes';
 import type { Size } from '../../util/variant-types';
 import Button from '../Button';
@@ -12,7 +13,7 @@ type AccordionProps = {
   /**
    * Child node(s) that can be nested inside component.
    */
-  children: React.ReactNode;
+  children: ReactNode;
   /**
    * Additional classnames passed in for styling.
    */
@@ -41,7 +42,7 @@ type AccordionButtonProps = {
   /**
    * Child node(s) that can be nested inside component.
    */
-  children: React.ReactNode;
+  children: ReactNode;
   /**
    * Additional classnames passed in for styling
    */
@@ -71,7 +72,7 @@ type AccordionPanelProps = {
   /**
    * Child node(s) that can be nested inside component.
    */
-  children: React.ReactNode;
+  children: ReactNode;
   /**
    * Additional classnames passed in for styling
    */
@@ -82,9 +83,7 @@ type AccordionRowProps = {
   /**
    * Child node(s) that can be nested inside component.
    */
-  children:
-    | React.ReactNode
-    | (({ open }: { open: boolean }) => React.ReactNode);
+  children: ReactNode | (({ open }: { open: boolean }) => ReactNode);
   /**
    * Additional classnames passed in for styling.
    */

src/components/Badge/Badge.tsx

@@ -1,5 +1,6 @@
 import clsx from 'clsx';
 import React from 'react';
+import type { ReactNode } from 'react';
 import Icon from '../Icon';
 import type { IconName, IconProps } from '../Icon';
 import styles from './Badge.module.css';
@@ -9,7 +10,7 @@ type BadgeProps = {
    * Badgeable object MUST have accessible name describing the attached badge.
    * Wraps the badgeable object and the element on its upper right corner.
    */
-  children?: React.ReactNode;
+  children?: ReactNode;
   /**
    * CSS class names that can be appended to the component.
    */

src/components/Breadcrumbs/Breadcrumbs.tsx

@@ -154,7 +154,7 @@ export const Breadcrumbs = ({
   );
 };
 
-const flattenBreadcrumbsItems = (children: React.ReactNode) => {
+const flattenBreadcrumbsItems = (children: ReactNode) => {
   const flattenedChildren = flattenReactChildren(children);
   /**
    * Throws error if children are not BreadcrumbsItems
@@ -201,7 +201,7 @@ type BreadcrumbItemProps = {
    * URLs for the collapsed breadcrumbs variant.
    * Should be <Menu.Item href={href}>{text}</Menu.Item>.
    */
-  menuItems?: React.ReactNode[];
+  menuItems?: ReactNode[];
   /**
    * Custom string separator after current breadcrumb item.
    * Defaults to '/'

src/components/Checkbox/Checkbox.tsx

@@ -1,5 +1,6 @@
 import clsx from 'clsx';
 import React, { forwardRef } from 'react';
+import type { ReactNode } from 'react';
 import useForwardedRef from '../../util/useForwardedRef';
 import { useId } from '../../util/useId';
 import type { EitherInclusive } from '../../util/utility-types';
@@ -53,7 +54,7 @@ type CheckboxProps = Omit<CheckboxInputProps, 'id'> & {
       /**
        * Visible text label for the component.
        */
-      label: React.ReactNode;
+      label: ReactNode;
     },
     {
       /**

src/components/Heading/Heading.tsx

@@ -1,11 +1,12 @@
 import clsx from 'clsx';
 import React, { forwardRef } from 'react';
+import type { ReactNode, HTMLAttributes } from 'react';
 import type { Preset } from '../../util/variant-types';
 import styles from './Heading.module.css';
 
 export type HeadingElement = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 
-type HeadingProps = React.HTMLAttributes<HTMLHeadingElement> & {
+type HeadingProps = HTMLAttributes<HTMLHeadingElement> & {
   /**
    * This prop can be used to specify which level heading should
    * actually be rendered, in the case that you want to render an element
@@ -14,7 +15,7 @@ type HeadingProps = React.HTMLAttributes<HTMLHeadingElement> & {
    * **Default is `"h1"`**.
    */
   as?: HeadingElement;
-  children: React.ReactNode;
+  children: ReactNode;
   className?: string;
   tabIndex?: number;
   /**

src/components/HorizontalStepper/HorizontalStepper.tsx

@@ -1,5 +1,6 @@
 import clsx from 'clsx';
 import React from 'react';
+import type { ReactNode } from 'react';
 import Icon, { type IconName } from '../Icon';
 import NumberIcon from '../NumberIcon';
 import Text from '../Text';
@@ -84,7 +85,7 @@ export const HorizontalStepper = ({
   /**
    * Creates a list of <HorizontalStep> components with lines in between.
    */
-  const stepComponents: React.ReactNode[] = [];
+  const stepComponents: ReactNode[] = [];
   steps.forEach((step, index) => {
     /**
      * If it is not the first step, add a line to stepComponents.

src/components/InlineNotification/InlineNotification.tsx

@@ -1,5 +1,6 @@
 import clsx from 'clsx';
 import React from 'react';
+import type { ReactNode } from 'react';
 import Icon, { type IconName } from '../Icon';
 import Text from '../Text';
 import styles from './InlineNotification.module.css';
@@ -47,7 +48,7 @@ type Props = {
   /**
    * The text contents of the tag, nested inside the component, in addition to the icon.
    */
-  text: React.ReactNode;
+  text: ReactNode;
   /**
    * The color variant of the tag.
    */

src/components/InputLabel/InputLabel.tsx

@@ -1,13 +1,14 @@
 import clsx from 'clsx';
 import React from 'react';
+import type { ReactNode } from 'react';
 import type { Size } from '../../util/variant-types';
 import styles from './InputLabel.module.css';
 
 export type InputLabelProps = {
   /**
    * Text to render in label.
    */
-  children: React.ReactNode;
+  children: ReactNode;
   /**
    * Additional classnames passed in for styling.
    */

src/components/Menu/Menu.tsx

@@ -1,6 +1,6 @@
 import { Menu as HeadlessMenu } from '@headlessui/react';
 import clsx from 'clsx';
-import type { MouseEventHandler } from 'react';
+import type { ReactNode, MouseEventHandler } from 'react';
 import { useContext, useState } from 'react';
 import React from 'react';
 import { createPortal } from 'react-dom';
@@ -51,7 +51,7 @@ export type MenuButtonProps = {
   /**
    * The button contents placed left of the chevron icon.
    */
-  children: React.ReactNode;
+  children: ReactNode;
   /**
    * Allow custom classes to be applied to the menu button.
    */
@@ -199,7 +199,7 @@ const MenuItem = ({
             disabled={disabled}
             icon={icon}
           >
-            {children as React.ReactNode}
+            {children as ReactNode}
           </PopoverListItem>
         );
         return disabled ? (

src/components/Popover/Popover.tsx

@@ -1,7 +1,7 @@
 import { Popover as HeadlessPopover } from '@headlessui/react';
 import clsx from 'clsx';
-import { useState, createContext, useContext } from 'react';
-import React from 'react';
+import React, { useState, createContext, useContext } from 'react';
+import type { ReactNode, RefObject } from 'react';
 import { createPortal } from 'react-dom';
 import { usePopper } from 'react-popper';
 import type { ExtractProps, RenderProps } from '../../util/utility-types';
@@ -42,9 +42,7 @@ export type PopoverContentProps = ExtractProps<typeof HeadlessPopover.Panel> & {
     /**
      * Render prop that closes popover when called.
      */
-    close: (
-      focusableElement?: HTMLElement | React.RefObject<HTMLElement>,
-    ) => void;
+    close: (focusableElement?: HTMLElement | RefObject<HTMLElement>) => void;
   }>;
 
 export const PopoverContext = createContext<PopoverContextType>({});
@@ -64,7 +62,7 @@ export const Popover = ({
   const [referenceElement, setReferenceElement] = useState<Element>();
   const [popperElement, setPopperElement] = useState<HTMLElement>();
 
-  // Leverage usePopper hook from Popper js for additional popover behavior and adds behavior to context for consumption by subcomponents.
+  // Leverage usePopper hook from Popper js for additional popover behavior and adds behavior to context for consumption by sub-components.
   const { styles: popperStyles, attributes } = usePopper(
     referenceElement,
     popperElement,
@@ -143,7 +141,7 @@ const PopoverContent = ({
             className={componentClassName}
           >
             <PopoverContainer className={bodyClassName}>
-              {children as React.ReactNode}
+              {children as ReactNode}
             </PopoverContainer>
           </HeadlessPopover.Panel>,
           document.body,