@primer/components 33.0.0 → 33.1.0-rc.6856bcf5

package/docs/src/component-checklist.js

@@ -0,0 +1,89 @@
+import {Box, StyledOcticon, Link, Text} from '@primer/components'
+import {H3} from '@primer/gatsby-theme-doctocat/src/components/heading'
+import {CheckCircleFillIcon, CircleIcon, SkipIcon} from '@primer/octicons-react'
+import React from 'react'
+
+/** Render component status checklist in documentation pages */
+export function ComponentChecklist({items}) {
+  return (
+    <>
+      <H3>Alpha</H3>
+      <Checklist aria-describedby="alpha">
+        <Checklist.Item checked={items.propsDocumented}>
+          Component props are documented on <Link href="https://primer.style/react/">primer.style/react</Link>.
+        </Checklist.Item>
+        <Checklist.Item checked={items.noUnnecessaryDeps}>
+          Component does not have any unnecessary third-party dependencies.
+        </Checklist.Item>
+        <Checklist.Item checked={items.adaptsToThemes}>Component can adapt to different themes.</Checklist.Item>
+        <Checklist.Item checked={items.adaptsToScreenSizes}>
+          Component can adapt to different screen sizes.
+        </Checklist.Item>
+        <Checklist.Item checked={items.fullTestCoverage}>Component has 100% test coverage.</Checklist.Item>
+      </Checklist>
+      <H3>Beta</H3>
+      <Checklist aria-describedby="beta">
+        <Checklist.Item checked={items.usedInProduction}>Component is used in a production application.</Checklist.Item>
+        <Checklist.Item checked={items.usageExamplesDocumented}>
+          Common usage examples are documented on <Link href="https://primer.style/react/">primer.style/react</Link>.
+        </Checklist.Item>
+        <Checklist.Item checked={items.hasStorybookStories}>
+          Common usage examples are documented in <Link href="https://primer.style/react/storybook">storybook</Link>{' '}
+          stories.
+        </Checklist.Item>
+        <Checklist.Item checked={items.designReviewed}>
+          Component has been reviewed by a systems designer and any resulting issues have been addressed.
+        </Checklist.Item>
+        <Checklist.Item checked={items.a11yReviewed}>
+          Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.
+        </Checklist.Item>
+      </Checklist>
+      <H3>Stable</H3>
+      <Checklist aria-describedby="stable">
+        <Checklist.Item checked={items.apiIsStable}>
+          Component API has been stable with no breaking changes for at least one month.
+        </Checklist.Item>
+        <Checklist.Item checked={items.addressedApiFeedback}>
+          Feedback on API usability has been sought from developers using the component and any resulting issues have
+          been addressed.
+        </Checklist.Item>
+        <Checklist.Item checked={items.hasDesignGuidelines}>
+          Component has corresponding design guidelines documented in the{' '}
+          <Link href="https://primer.style/design/">interface guidelines</Link>.
+        </Checklist.Item>
+        <Checklist.Item checked={items.hasFigmaComponent}>
+          Component has corresponding Figma component in the Primer Web library.
+        </Checklist.Item>
+      </Checklist>
+    </>
+  )
+}
+
+// TODO: This component should live in Doctocat
+function Checklist({'aria-describedby': ariaDescribedby, children}) {
+  return (
+    <Box aria-describedby={ariaDescribedby} as="ul" display="grid" gridGap={2} p={0} m={0} mb={3}>
+      {children}
+    </Box>
+  )
+}
+
+Checklist.Item = ({checked, children}) => {
+  return (
+    <Box as="li" display="grid" gridTemplateColumns="auto 1fr" gridGap={2} sx={{listStyleType: 'none'}}>
+      <Box height="24px" display="flex" alignItems="center">
+        {checked ? (
+          <StyledOcticon aria-label="Completed" icon={CheckCircleFillIcon} sx={{color: 'success.fg'}} />
+        ) : checked === null ? (
+          <StyledOcticon icon={SkipIcon} sx={{color: 'fg.subtle'}} />
+        ) : (
+          <StyledOcticon aria-label="To do" icon={CircleIcon} sx={{color: 'fg.subtle'}} />
+        )}
+      </Box>
+      <Text color={checked === null ? 'fg.subtle' : 'fg.default'}>
+        {checked === null ? <Text color="fg.subtle">N/A: </Text> : null}
+        {children}
+      </Text>
+    </Box>
+  )
+}

package/docs/src/component-statuses.js

@@ -0,0 +1,74 @@
+import componentMetadata from '@primer/component-metadata'
+import {Link} from '@primer/components'
+import StatusLabel from '@primer/gatsby-theme-doctocat/src/components/status-label'
+import Table from '@primer/gatsby-theme-doctocat/src/components/table'
+import {graphql, Link as GatsbyLink, useStaticQuery} from 'gatsby'
+import React from 'react'
+
+export function ComponentStatuses() {
+  const data = useStaticQuery(graphql`
+    query ComponentStatuses {
+      allSitePage {
+        nodes {
+          path
+          context {
+            frontmatter {
+              title
+              status
+              description
+              componentId
+            }
+          }
+        }
+      }
+    }
+  `)
+
+  const pages = data.allSitePage.nodes
+    // Only show components that have a status
+    .filter(node => node.context.frontmatter && node.context.frontmatter.status !== null)
+    // Sort alphabetically by title
+    .sort((a, b) => a.context.frontmatter.title.localeCompare(b.context.frontmatter.title))
+
+  return (
+    <div>
+      <Table>
+        <thead>
+          <tr>
+            <th align="left">Component</th>
+            <th align="left">Status</th>
+            <th align="left">Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {pages.map(page => {
+            // eslint-disable-next-line prefer-const
+            let {title, status, description, componentId} = page.context.frontmatter
+
+            const component = componentMetadata.components[componentId]
+
+            // Auto-populate title and description using component metadata
+            if (component) {
+              title ||= component.displayName
+              description ||= component.description
+            }
+
+            return (
+              <tr key={page.path}>
+                <td valign="top">
+                  <Link as={GatsbyLink} to={page.path}>
+                    {title}
+                  </Link>
+                </td>
+                <td valign="top">
+                  <StatusLabel status={status} />
+                </td>
+                <td>{description}</td>
+              </tr>
+            )
+          })}
+        </tbody>
+      </Table>
+    </div>
+  )
+}

package/docs/src/props-table.js

@@ -0,0 +1,165 @@
+import React from 'react'
+import {Box, Link, Label} from '@primer/components'
+import Table from '@primer/gatsby-theme-doctocat/src/components/table'
+import InlineCode from '@primer/gatsby-theme-doctocat/src/components/inline-code'
+
+function PropsTable({children}) {
+  return (
+    <Table>
+      <colgroup>
+        <col style={{width: '20%'}} />
+        <col style={{width: '30%'}} />
+        <col style={{width: '10%'}} />
+        <col style={{width: '40%'}} />
+      </colgroup>
+      <thead>
+        <tr>
+          <Box as="th" textAlign="left">
+            Name
+          </Box>
+          <Box as="th" textAlign="left">
+            Type
+          </Box>
+          <Box as="th" textAlign="left">
+            Default
+          </Box>
+          <Box as="th" textAlign="left">
+            Description
+          </Box>
+        </tr>
+      </thead>
+      <tbody>{children}</tbody>
+    </Table>
+  )
+}
+
+function Row({name, type, defaultValue, description, required, deprecated}) {
+  return (
+    <tr>
+      <Box as="td" fontFamily="mono" fontSize={1} sx={{whiteSpace: 'nowrap'}} verticalAlign="top">
+        {name}
+        {required ? (
+          <>
+            {` `}
+            <Label outline sx={{verticalAlign: 'middle', fontFamily: 'normal'}}>
+              Required
+            </Label>
+          </>
+        ) : null}
+        {deprecated ? (
+          <>
+            {` `}
+            <Label
+              outline
+              sx={{verticalAlign: 'middle', fontFamily: 'normal', color: 'danger.fg', borderColor: 'danger.emphasis'}}
+            >
+              Deprecated
+            </Label>
+          </>
+        ) : null}
+      </Box>
+      <Box as="td" fontFamily="mono" fontSize={1} verticalAlign="top">
+        <Box as="pre" fontFamily="inherit" fontSize="inherit" margin={0} sx={{whiteSpace: 'pre-wrap'}}>
+          {type}
+        </Box>
+      </Box>
+      <Box as="td" fontFamily="mono" fontSize={1} verticalAlign="top">
+        {defaultValue}
+      </Box>
+      <Box as="td" verticalAlign="top">
+        {description}
+      </Box>
+    </tr>
+  )
+}
+
+function BasePropRows({passthroughPropsLink, elementType, isPolymorphic, refType}) {
+  return (
+    <>
+      <SxRow />
+      {isPolymorphic && <AsRow defaultElementType={elementType} />}
+      <RefRow refType={refType} isPolymorphic={isPolymorphic} />
+      <PassthroughPropsRow
+        passthroughPropsLink={passthroughPropsLink}
+        elementName={elementType}
+        isPolymorphic={isPolymorphic}
+      />
+    </>
+  )
+}
+
+function PassthroughPropsRow({elementName, isPolymorphic, passthroughPropsLink}) {
+  return (
+    <tr>
+      <Box as="td" colSpan={4} fontSize={1} verticalAlign="top">
+        Additional props are passed to the <InlineCode>&lt;{elementName}&gt;</InlineCode> element. See{' '}
+        {passthroughPropsLink} for a list of props accepted by the <InlineCode>&lt;{elementName}&gt;</InlineCode>{' '}
+        element.
+        {isPolymorphic && (
+          <>
+            {' '}
+            If an <InlineCode>as</InlineCode> prop is specified, the accepted props will change accordingly.
+          </>
+        )}
+      </Box>
+    </tr>
+  )
+}
+
+function AsRow({defaultElementType}) {
+  return (
+    <Row
+      name="as"
+      defaultValue={`"${defaultElementType}"`}
+      type={
+        <Link href="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react/index.d.ts#L73">
+          React.ElementType
+        </Link>
+      }
+      description="The underlying element to render — either a HTML element name or a React component."
+    />
+  )
+}
+
+function RefRow({refType, isPolymorphic}) {
+  return (
+    <Row
+      name="ref"
+      type={`React.RefObject<${refType}>`}
+      description={
+        <>
+          A ref to the element rendered by this component.
+          {isPolymorphic && (
+            <>
+              {' '}
+              Because this component is polymorphic, the type will vary based on the value of the{' '}
+              <InlineCode>as</InlineCode> prop.
+            </>
+          )}
+        </>
+      }
+    />
+  )
+}
+
+function SxRow() {
+  return (
+    <Row
+      name="sx"
+      type={
+        <Link href="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/styled-system__css/index.d.ts#L407">
+          SystemStyleObject
+        </Link>
+      }
+      description={
+        <>
+          Style overrides to apply to the component. See also <Link href="/overriding-styles">overriding styles</Link>.
+        </>
+      }
+    />
+  )
+}
+
+Object.assign(PropsTable, {Row, BasePropRows, AsRow, RefRow, PassthroughPropsRow, SxRow})
+
+export {PropsTable}

package/docs/src/props.js

@@ -0,0 +1,63 @@
+import {Flash} from '@primer/components'
+import {H3} from '@primer/gatsby-theme-doctocat/src/components/heading'
+import Paragraph from '@primer/gatsby-theme-doctocat/src/components/paragraph'
+import {graphql, useStaticQuery} from 'gatsby'
+import React from 'react'
+import {PropsTable} from './props-table'
+
+/** Render prop documentation for the given component */
+export function Props({of}) {
+  const data = useStaticQuery(graphql`
+    query {
+      allComponentMetadata {
+        nodes {
+          id
+          name
+          props {
+            description
+            defaultValue
+            name
+            required
+            type
+          }
+        }
+      }
+    }
+  `)
+
+  const displayName = of?.displayName || of?.name || ''
+  const component = data.allComponentMetadata.nodes.find(node => node.name === displayName)
+
+  if (!component) {
+    // eslint-disable-next-line no-console
+    console.error(`Could not find component ${displayName}`)
+    return (
+      <>
+        <H3>{displayName}</H3>
+        <Flash variant="danger">Component not found</Flash>
+      </>
+    )
+  }
+
+  return (
+    <>
+      <H3>{component.name}</H3>
+      {component.props.length > 0 ? (
+        <PropsTable>
+          {component.props.map(prop => (
+            <PropsTable.Row
+              key={prop.name}
+              required={prop.required}
+              name={prop.name}
+              defaultValue={prop.defaultValue}
+              type={prop.type}
+              description={prop.description}
+            />
+          ))}
+        </PropsTable>
+      ) : (
+        <Paragraph>No props</Paragraph>
+      )}
+    </>
+  )
+}

package/jest.config.js

@@ -0,0 +1,13 @@
+/* eslint-disable github/unescaped-html-literal */
+module.exports = {
+  testEnvironment: 'jsdom',
+  cacheDirectory: '.test',
+  collectCoverage: true,
+  collectCoverageFrom: ['src/**/*.{js,jsx,ts,tsx}', '!src/stories/**'],
+  setupFilesAfterEnv: [
+    '<rootDir>/src/utils/test-matchers.tsx',
+    '<rootDir>/src/utils/test-deprecations.tsx',
+    '<rootDir>/src/utils/test-helpers.tsx'
+  ],
+  testMatch: ['<rootDir>/(src|codemods)/__tests__/**/*.test.[jt]s?(x)', '!**/*.types.test.[jt]s?(x)']
+}

package/lib/ActionList2/{MenuContext.d.ts → ActionListContainerContext.d.ts}

@@ -1,10 +1,10 @@
 /** This context can be used by components that compose ActionList inside a Menu */
 import React from 'react';
 declare type ContextProps = {
-    parent?: string;
+    container?: string;
     listRole?: string;
     itemRole?: string;
-    afterSelect?: () => void;
+    afterSelect?: Function;
 };
-export declare const MenuContext: React.Context<ContextProps>;
+export declare const ActionListContainerContext: React.Context<ContextProps>;
 export {};

package/lib/ActionList2/{MenuContext.js → ActionListContainerContext.js}

@@ -3,13 +3,13 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.MenuContext = void 0;
+exports.ActionListContainerContext = void 0;
 
 var _react = _interopRequireDefault(require("react"));
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 /** This context can be used by components that compose ActionList inside a Menu */
-const MenuContext = /*#__PURE__*/_react.default.createContext({});
+const ActionListContainerContext = /*#__PURE__*/_react.default.createContext({});
 
-exports.MenuContext = MenuContext;
+exports.ActionListContainerContext = ActionListContainerContext;

package/lib/ActionList2/Item.js

@@ -21,7 +21,7 @@ var _createSlots = _interopRequireDefault(require("../utils/create-slots"));
 
 var _List = require("./List");
 
-var _MenuContext = require("./MenuContext");
+var _ActionListContainerContext = require("./ActionListContainerContext");
 
 var _Selection = require("./Selection");
 
@@ -96,7 +96,7 @@ const Item = /*#__PURE__*/_react.default.forwardRef(({
   const {
     itemRole,
     afterSelect
-  } = _react.default.useContext(_MenuContext.MenuContext);
+  } = _react.default.useContext(_ActionListContainerContext.ActionListContainerContext);
 
   const {
     theme
@@ -171,22 +171,20 @@ const Item = /*#__PURE__*/_react.default.forwardRef(({
   };
 
   const clickHandler = _react.default.useCallback(event => {
-    if (typeof onSelect !== 'function') return;
     if (disabled) return;
 
     if (!event.defaultPrevented) {
-      onSelect(event); // if this Item is inside a Menu, close the Menu
+      if (typeof onSelect === 'function') onSelect(event); // if this Item is inside a Menu, close the Menu
 
       if (typeof afterSelect === 'function') afterSelect();
     }
   }, [onSelect, disabled, afterSelect]);
 
   const keyPressHandler = _react.default.useCallback(event => {
-    if (typeof onSelect !== 'function') return;
     if (disabled) return;
 
     if (!event.defaultPrevented && [' ', 'Enter'].includes(event.key)) {
-      onSelect(event); // if this Item is inside a Menu, close the Menu
+      if (typeof onSelect === 'function') onSelect(event); // if this Item is inside a Menu, close the Menu
 
       if (typeof afterSelect === 'function') afterSelect();
     }

package/lib/ActionList2/List.js

@@ -11,7 +11,7 @@ var _styledComponents = _interopRequireDefault(require("styled-components"));
 
 var _sx = _interopRequireWildcard(require("../sx"));
 
-var _MenuContext = require("./MenuContext");
+var _ActionListContainerContext = require("./ActionListContainerContext");
 
 function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function (nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
 
@@ -48,7 +48,7 @@ const List = /*#__PURE__*/_react.default.forwardRef(({
 
   const {
     listRole
-  } = _react.default.useContext(_MenuContext.MenuContext);
+  } = _react.default.useContext(_ActionListContainerContext.ActionListContainerContext);
 
   return /*#__PURE__*/_react.default.createElement(ListBox, _extends({
     sx: (0, _sx.merge)(styles, sxProp),

package/lib/ActionList2/Selection.js

@@ -13,7 +13,7 @@ var _List = require("./List");
 
 var _Group = require("./Group");
 
-var _MenuContext = require("./MenuContext");
+var _ActionListContainerContext = require("./ActionListContainerContext");
 
 var _Visuals = require("./Visuals");
 
@@ -31,8 +31,8 @@ const Selection = ({
   } = _react.default.useContext(_Group.GroupContext);
 
   const {
-    parent
-  } = _react.default.useContext(_MenuContext.MenuContext);
+    container
+  } = _react.default.useContext(_ActionListContainerContext.ActionListContainerContext);
   /** selectionVariant in Group can override the selectionVariant in List root */
 
 
@@ -44,7 +44,7 @@ const Selection = ({
     return null;
   }
 
-  if (parent === 'ActionMenu') {
+  if (container === 'ActionMenu') {
     throw new Error('ActionList cannot have a selectionVariant inside ActionMenu, please use DropdownMenu or SelectPanel instead. More information: https://primer.style/design/components/action-list#application');
     return null;
   }

package/lib/ActionMenu2.d.ts

@@ -1,10 +1,12 @@
 import { ButtonProps } from './Button';
 import React from 'react';
+import { AnchoredOverlayProps } from './AnchoredOverlay';
 import { OverlayProps } from './Overlay';
-import { AnchoredOverlayWrapperAnchorProps } from './AnchoredOverlay/AnchoredOverlay';
-declare type ActionMenuBaseProps = {
+declare type MenuContextProps = Pick<AnchoredOverlayProps, 'anchorRef' | 'renderAnchor' | 'open' | 'onOpen' | 'onClose'>;
+export declare const MenuContext: React.Context<MenuContextProps>;
+export declare type ActionMenuProps = {
     /**
-     * Recommended: `ActionMenu.Button` or `ActionMenu.Anchor` with ActionList`
+     * Recommended: `ActionMenu.Button` or `ActionMenu.Anchor` with `ActionMenu.Overlay`
      */
     children: React.ReactElement[] | React.ReactElement;
     /**
@@ -15,17 +17,18 @@ declare type ActionMenuBaseProps = {
      * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `open`.
      */
     onOpenChange?: (s: boolean) => void;
-    /**
-     * Props to be spread on the internal `Overlay` component.
-     */
-    overlayProps?: Partial<OverlayProps>;
-};
-export declare type ActionMenuProps = ActionMenuBaseProps & AnchoredOverlayWrapperAnchorProps;
+} & Pick<AnchoredOverlayProps, 'anchorRef'>;
 export declare type MenuAnchorProps = {
     children: React.ReactElement;
 };
 /** this component is syntactical sugar 🍭 */
 export declare type MenuButtonProps = ButtonProps;
+declare type MenuOverlayProps = Partial<OverlayProps> & {
+    /**
+     * Recommended: `ActionList`
+     */
+    children: React.ReactElement[] | React.ReactElement;
+};
 export declare const ActionMenu: React.FC<ActionMenuProps> & {
     Button: React.ForwardRefExoticComponent<Pick<{
         color?: string | undefined;
@@ -308,6 +311,7 @@ export declare const ActionMenu: React.FC<ActionMenuProps> & {
         variant?: "small" | "medium" | "large" | undefined;
     }> & React.RefAttributes<React.RefObject<HTMLElement> | undefined>>;
     Anchor: React.ForwardRefExoticComponent<MenuAnchorProps & React.RefAttributes<React.RefObject<HTMLElement> | undefined>>;
+    Overlay: React.FC<MenuOverlayProps>;
     Divider: React.FC<import("./sx").SxProp>;
 };
 export {};