docs(website): add Sidebar docs and fix minor component types

.changeset/neat-mugs-call.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/sidebar': patch
+'@twilio-paste/core': patch
+---
+
+[Sidebar] `SidebarBetaBadge` no longer passes `onClick` when `as="span"`. Other miscellaneous typescript fixes.

cypress/integration/sitemap-vrt/constants.ts

@@ -65,6 +65,7 @@ export const SITEMAP = [
   '/components/screen-reader-only/',
   '/components/select/',
   '/components/separator/',
+  '/components/sidebar/',
   '/components/stack/',
   '/components/status-badge/',
   '/components/status-menu/',

packages/paste-core/components/sidebar/src/SidebarBetaBadge.tsx

@@ -1,41 +1,40 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import {Box, safelySpreadBoxProps} from '@twilio-paste/box';
+import type {BoxProps} from '@twilio-paste/box';
 import {badgeBaseStyles, useResizeChildIcons} from '@twilio-paste/badge';
 import type {BadgeProps} from '@twilio-paste/badge';
 
+const SidebarBetaBadgeSpanStyles: BoxProps = {
+  ...badgeBaseStyles,
+  paddingX: 'space20',
+  paddingY: 'space10',
+  boxShadow: 'shadowBorderInverseNewWeaker',
+  backgroundColor: 'colorBackgroundInverseStrong',
+  color: 'colorTextInverseNew',
+};
+const SidebarBetaBadgeButtonStyles: BoxProps = {
+  ...SidebarBetaBadgeSpanStyles,
+  boxShadow: 'shadowBorderBottomInverseNewWeaker',
+  // The following styles are copied from getBadgeButtonStyles() in the Badge package
+  cursor: 'pointer',
+  _hover: {top: '1px', boxShadow: 'none'},
+  _focus: {top: '1px', boxShadow: 'shadowFocusInverse'}, // shadowFocus in Badge
+};
+
 type SidebarBetaBadgeProps = Omit<BadgeProps, 'as' | 'variant' | 'size'> & {
   as: 'span' | 'button';
 };
 
 export const SidebarBetaBadge = React.forwardRef<HTMLElement, SidebarBetaBadgeProps>(
-  ({children, as, element = 'SIDEBAR_BETA_BADGE', ...props}, ref) => {
+  ({children, as, element = 'SIDEBAR_BETA_BADGE', onClick, ...props}, ref) => {
     const resizedChildren = useResizeChildIcons(children);
-    let badgeStyles = badgeBaseStyles;
-
-    if (as === 'button') {
-      badgeStyles = {
-        ...badgeStyles,
-        // The following styles are copied from getBadgeButtonStyles() in the Badge package
-        cursor: 'pointer',
-        _hover: {top: '1px', boxShadow: 'none'},
-        _focus: {top: '1px', boxShadow: 'shadowFocusInverse'}, // shadowFocus in Badge
-      };
-    }
+    const styles = as === 'button' ? SidebarBetaBadgeButtonStyles : SidebarBetaBadgeSpanStyles;
+    // We don't want the provided onClick to function if as = span
+    const handleOnClick = as === 'button' ? onClick : undefined;
 
     return (
-      <Box
-        {...safelySpreadBoxProps(props)}
-        {...badgeStyles}
-        paddingX="space20"
-        paddingY="space10"
-        boxShadow={as === 'button' ? 'shadowBorderBottomInverseNewWeaker' : 'shadowBorderInverseNewWeaker'}
-        backgroundColor="colorBackgroundInverseStrong"
-        color="colorTextInverseNew"
-        as={as}
-        ref={ref}
-        element={element}
-      >
+      <Box {...safelySpreadBoxProps(props)} {...styles} as={as} ref={ref} element={element} onClick={handleOnClick}>
         {resizedChildren}
       </Box>
     );

packages/paste-core/components/sidebar/src/SidebarCollapseButton.tsx

@@ -1,7 +1,6 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import {Button} from '@twilio-paste/button';
-import type {ButtonProps} from '@twilio-paste/button';
 import type {BoxProps} from '@twilio-paste/box';
 import {ScreenReaderOnly} from '@twilio-paste/screen-reader-only';
 import {ChevronDoubleLeftIcon} from '@twilio-paste/icons/esm/ChevronDoubleLeftIcon';
@@ -13,7 +12,6 @@ export interface SidebarCollapseButtonProps extends React.HTMLAttributes<HTMLBut
   i18nCollapseLabel: string;
   i18nExpandLabel: string;
   element?: BoxProps['element'];
-  tabIndex?: ButtonProps['tabIndex'];
   onClick?: () => void;
 }
 
@@ -28,6 +26,7 @@ export const SidebarCollapseButton = React.forwardRef<HTMLButtonElement, Sidebar
         variant="inverse"
         element={element}
         {...props}
+        tabIndex={0}
         aria-expanded={!collapsed}
         aria-controls={sidebarId}
       >
@@ -52,7 +51,6 @@ SidebarCollapseButton.propTypes = {
   i18nExpandLabel: PropTypes.string.isRequired,
   element: PropTypes.string,
   onClick: PropTypes.func,
-  tabIndex: PropTypes.oneOf([-1, 0]),
 };
 
 SidebarCollapseButton.displayName = 'SidebarCollapseButton';

packages/paste-core/components/sidebar/src/SidebarHeader.tsx

@@ -4,8 +4,7 @@ import {Box, safelySpreadBoxProps} from '@twilio-paste/box';
 import type {BoxProps} from '@twilio-paste/box';
 
 export interface SidebarHeaderProps extends React.HTMLAttributes<HTMLButtonElement> {
-  productIcon?: React.ReactNode;
-  onClick?: () => void;
+  children: React.ReactNode;
   element?: BoxProps['element'];
 }
 
@@ -34,9 +33,8 @@ export const SidebarHeader = React.forwardRef<HTMLButtonElement, SidebarHeaderPr
 );
 
 SidebarHeader.propTypes = {
-  productIcon: PropTypes.node,
+  children: PropTypes.node,
   element: PropTypes.string,
-  onClick: PropTypes.func,
 };
 
 SidebarHeader.displayName = 'SidebarHeader';

packages/paste-core/components/sidebar/src/SidebarHeaderIconButton.tsx

@@ -6,14 +6,15 @@ import type {BoxProps} from '@twilio-paste/box';
 
 export interface SidebarHeaderIconButtonProps extends React.HTMLAttributes<HTMLButtonElement> {
   children: NonNullable<React.ReactNode>;
-  tabIndex?: ButtonProps['tabIndex'];
-  onClick?: () => void;
+  as: 'a' | 'button';
+  onClick?: ButtonProps['onClick'];
+  href?: ButtonProps['href'];
   element?: BoxProps['element'];
 }
 
 export const SidebarHeaderIconButton = React.forwardRef<HTMLButtonElement, SidebarHeaderIconButtonProps>(
   ({element = 'SIDEBAR_HEADER_ICON_BUTTON', ...props}, ref) => {
-    return <Button {...props} size="icon" variant="inverse" element={element} ref={ref} />;
+    return <Button {...props} tabIndex={0} size="icon" variant="inverse" element={element} ref={ref} />;
   }
 );
 

packages/paste-core/components/sidebar/stories/BetaBadge.stories.tsx

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import type {StoryFn} from '@storybook/react';
+
+import {SidebarBetaBadge} from '../src';
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: 'Components/Sidebar',
+};
+
+export const BetaBadge: StoryFn = () => {
+  return <SidebarBetaBadge as="span">Beta</SidebarBetaBadge>;
+};

packages/paste-core/components/sidebar/stories/SidebarHeader.stories.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import {Box} from '@twilio-paste/box';
+import type {StoryFn} from '@storybook/react';
+import {LogoTwilioIcon} from '@twilio-paste/icons/esm/LogoTwilioIcon';
+
+import {SidebarHeader, SidebarHeaderLabel, SidebarHeaderIconButton} from '../src';
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: 'Components/Sidebar',
+};
+
+export const Header: StoryFn = () => {
+  return (
+    <Box backgroundColor="colorBackgroundInverse" maxWidth="size50">
+      <SidebarHeader>
+        <SidebarHeaderIconButton href="#" as="a">
+          <LogoTwilioIcon size="sizeIcon20" decorative={false} title="Go to Console homepage" />
+        </SidebarHeaderIconButton>
+        <SidebarHeaderLabel>Twilio Console</SidebarHeaderLabel>
+      </SidebarHeader>
+    </Box>
+  );
+};

packages/paste-core/components/sidebar/stories/customization.stories.tsx

@@ -23,7 +23,7 @@ import {
 
 // eslint-disable-next-line import/no-default-export
 export default {
-  title: 'Components/Sidebar/Customization',
+  title: 'Components/Sidebar/Sidebar/Customization',
 };
 
 export const WithDefaultElementName: StoryFn = (_args, {parameters: {isTestEnvironment}}) => {

packages/paste-core/components/sidebar/stories/full-composition/console.stories.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import {Button} from '@twilio-paste/button';
+import {Stack} from '@twilio-paste/stack';
+import {Box} from '@twilio-paste/box';
+import type {StoryFn} from '@storybook/react';
+import {LogoTwilioIcon} from '@twilio-paste/icons/esm/LogoTwilioIcon';
+// ONLY for storybook stacked view not to complain on duplicates. aria-label should be carefully selected strings
+import {useUID} from '@twilio-paste/uid-library';
+import {Topbar} from '@twilio-paste/topbar';
+
+import {
+  Sidebar,
+  SidebarHeader,
+  SidebarHeaderLabel,
+  SidebarHeaderIconButton,
+  SidebarCollapseButton,
+  SidebarCollapseButtonWrapper,
+  SidebarPushContentWrapper,
+} from '../../src';
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: 'Components/Sidebar/FullCompositions',
+};
+
+export const Console: StoryFn = () => {
+  const id = useUID();
+  const [pushSidebarCollapsed, setPushSidebarCollapsed] = React.useState(false);
+
+  return (
+    <Box>
+      {/* Can be placed anywhere - position fixed */}
+      <Sidebar aria-label={id} collapsed={pushSidebarCollapsed} variant="compact">
+        <Stack orientation="vertical" spacing="space100">
+          <SidebarHeader>
+            <SidebarHeaderIconButton as="a" href="#">
+              <LogoTwilioIcon size="sizeIcon20" decorative={false} title="Go to Console homepage" />
+            </SidebarHeaderIconButton>
+            <SidebarHeaderLabel>Twilio Console</SidebarHeaderLabel>
+          </SidebarHeader>
+          <SidebarCollapseButtonWrapper>
+            <SidebarCollapseButton
+              onClick={() => setPushSidebarCollapsed(!pushSidebarCollapsed)}
+              i18nCollapseLabel="Close sidebar"
+              i18nExpandLabel="Open sidebar"
+            />
+          </SidebarCollapseButtonWrapper>
+        </Stack>
+      </Sidebar>
+
+      {/* Must wrap content area */}
+      <SidebarPushContentWrapper collapsed={pushSidebarCollapsed} variant="compact">
+        <Topbar>topbar</Topbar>
+        <Box padding="space70">
+          <Button variant="primary" onClick={() => setPushSidebarCollapsed(!pushSidebarCollapsed)}>
+            Toggle Push Sidebar
+          </Button>
+        </Box>
+      </SidebarPushContentWrapper>
+    </Box>
+  );
+};
+Console.parameters = {
+  padding: false,
+};

packages/paste-core/components/sidebar/stories/full-composition/flex.stories.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import {Button} from '@twilio-paste/button';
+import {Stack} from '@twilio-paste/stack';
+import {Box} from '@twilio-paste/box';
+import type {StoryFn} from '@storybook/react';
+import {ProductFlexIcon} from '@twilio-paste/icons/esm/ProductFlexIcon';
+// ONLY for storybook stacked view not to complain on duplicates. aria-label should be carefully selected strings
+import {useUID} from '@twilio-paste/uid-library';
+import {Topbar} from '@twilio-paste/topbar';
+
+import {
+  Sidebar,
+  SidebarHeader,
+  SidebarHeaderLabel,
+  SidebarHeaderIconButton,
+  SidebarCollapseButton,
+  SidebarCollapseButtonWrapper,
+  SidebarOverlayContentWrapper,
+} from '../../src';
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: 'Components/Sidebar/FullCompositions',
+};
+
+export const Flex: StoryFn = () => {
+  const id = useUID();
+  const [overlaySidebarExpanded, setOverlaySidebarExpanded] = React.useState(true);
+
+  return (
+    <Box>
+      {/* Can be placed anywhere - position fixed */}
+      <Sidebar aria-label={id} collapsed={overlaySidebarExpanded} variant="compact">
+        <Stack orientation="vertical" spacing="space100">
+          <SidebarHeader>
+            <SidebarHeaderIconButton as="a" href="#">
+              <ProductFlexIcon size="sizeIcon20" decorative={false} title="Go to Flex homepage" />
+            </SidebarHeaderIconButton>
+            <SidebarHeaderLabel>Twilio Flex</SidebarHeaderLabel>
+          </SidebarHeader>
+          <SidebarCollapseButtonWrapper>
+            <SidebarCollapseButton
+              onClick={() => setOverlaySidebarExpanded(!overlaySidebarExpanded)}
+              i18nCollapseLabel="Close sidebar"
+              i18nExpandLabel="Open sidebar"
+            />
+          </SidebarCollapseButtonWrapper>
+        </Stack>
+      </Sidebar>
+
+      {/* Must wrap content area */}
+      <SidebarOverlayContentWrapper collapsed={overlaySidebarExpanded} variant="compact">
+        <Topbar>topbar</Topbar>
+        <Box padding="space70">
+          <Button variant="primary" onClick={() => setOverlaySidebarExpanded(!overlaySidebarExpanded)}>
+            Toggle Overlay Sidebar
+          </Button>
+        </Box>
+      </SidebarOverlayContentWrapper>
+    </Box>
+  );
+};
+Flex.parameters = {
+  padding: false,
+};

packages/paste-core/components/sidebar/stories/full-composition/segment.stories.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import {Button} from '@twilio-paste/button';
+import {Stack} from '@twilio-paste/stack';
+import {Box} from '@twilio-paste/box';
+import type {StoryFn} from '@storybook/react';
+import {ProductSegmentIcon} from '@twilio-paste/icons/esm/ProductSegmentIcon';
+// ONLY for storybook stacked view not to complain on duplicates. aria-label should be carefully selected strings
+import {useUID} from '@twilio-paste/uid-library';
+import {Topbar} from '@twilio-paste/topbar';
+
+import {
+  Sidebar,
+  SidebarHeader,
+  SidebarHeaderLabel,
+  SidebarHeaderIconButton,
+  SidebarCollapseButton,
+  SidebarCollapseButtonWrapper,
+  SidebarPushContentWrapper,
+} from '../../src';
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: 'Components/Sidebar/FullCompositions',
+};
+
+export const Segment: StoryFn = () => {
+  const id = useUID();
+  const [pushSidebarCollapsed, setPushSidebarCollapsed] = React.useState(false);
+
+  return (
+    <Box>
+      {/* Can be placed anywhere - position fixed */}
+      <Sidebar aria-label={id} collapsed={pushSidebarCollapsed} variant="compact">
+        <Stack orientation="vertical" spacing="space100">
+          <SidebarHeader>
+            <SidebarHeaderIconButton as="a" href="#">
+              <ProductSegmentIcon size="sizeIcon20" decorative={false} title="Go to Segment homepage" />
+            </SidebarHeaderIconButton>
+            <SidebarHeaderLabel>Twilio Segment</SidebarHeaderLabel>
+          </SidebarHeader>
+          <SidebarCollapseButtonWrapper>
+            <SidebarCollapseButton
+              onClick={() => setPushSidebarCollapsed(!pushSidebarCollapsed)}
+              i18nCollapseLabel="Close sidebar"
+              i18nExpandLabel="Open sidebar"
+            />
+          </SidebarCollapseButtonWrapper>
+        </Stack>
+      </Sidebar>
+
+      {/* Must wrap content area */}
+      <SidebarPushContentWrapper collapsed={pushSidebarCollapsed} variant="compact">
+        <Topbar>topbar</Topbar>
+        <Box padding="space70">
+          <Button variant="primary" onClick={() => setPushSidebarCollapsed(!pushSidebarCollapsed)}>
+            Toggle Push Sidebar
+          </Button>
+        </Box>
+      </SidebarPushContentWrapper>
+    </Box>
+  );
+};
+Segment.parameters = {
+  padding: false,
+};