feat: apply the nav ui kit to the doc site (#3328)

* feat: apply the nav ui kit to the doc site

* chore: website types

* feat: scrolling and scrollspy for TOC

* feat: responsive nav ui kit on the website

* chore: types

* chore: pr feedback

* chore: responsive sidebars

* chore: changesets and docs for new style props

* chore: revised sidebar push container logic

* chore: see if a tiny increase in wait will help flakes in Percy

* fix: hierarchy indentation for sidebar nav

* fix: topbar alignment with the sidebar header

* fix: sidebar reopening on window resize

* fix: search test

.changeset/fifty-socks-sneeze.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/topbar': patch
+'@twilio-paste/core': patch
+---
+
+[Topbar] improved alignment with the sidebar header

.changeset/friendly-squids-wait.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/style-props': patch
+'@twilio-paste/core': patch
+---
+
+[Style-props] Create types for responsive versions of basic CSS properties to be use in Box and Text style primitives. Previously they were just static single css property values

.changeset/giant-mayflies-impress.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/topbar': patch
+'@twilio-paste/core': patch
+---
+
+[Topbar] Allow responsive display properties on Topbar Actions to enable building responsive and adaptive topbars

.changeset/itchy-birds-provide.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/text': patch
+'@twilio-paste/core': patch
+---
+
+[Text] Add transistionDelay CSS property to accompany transistion style prop

.changeset/lovely-rabbits-care.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/sidebar': patch
+'@twilio-paste/core': patch
+---
+
+[Sidebar] corrected the SideBarNavigationItem children proptype validation rule

.changeset/orange-numbers-end.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/topbar': patch
+'@twilio-paste/core': patch
+---
+
+[Topbar] match z-index level to that of the sidebar so they share the same plane within an application

.changeset/seven-geese-promise.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/box': patch
+'@twilio-paste/core': patch
+---
+
+[Box] Allow responsive values for the CSS properties Box supports as style props.

.changeset/soft-eggs-invent.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/sidebar': patch
+'@twilio-paste/core': patch
+---
+
+[Sidebar] improved SSR handling of the push content wrapper for small screen responsive layouts

cypress/integration/sidebar-navigation/index.spec.ts

@@ -20,20 +20,11 @@ const sidebarNavigationDisclosures = [
 const BASE = 'sidebar-disclosure';
 
 describe('Sidebar navigation', () => {
-  // set of the data-cy attribute values for all the tested disclosures
-  let visited = new Set<string>();
-
   before(() => {
     cy.visit('/');
     cy.wait(1000);
   });
 
-  beforeEach(() => {
-    if (visited.size > 0) {
-      cleanupOpenDisclosures(visited);
-    }
-  });
-
   sidebarNavigationDisclosures.forEach((disclosureName) => {
     const buttonSelector = `${BASE}-button-${disclosureName}`;
     const contentSelector = `${BASE}-content-${disclosureName}`;
@@ -44,7 +35,14 @@ describe('Sidebar navigation', () => {
       cy.get(`[data-cy="${contentSelector}"]`).as('currentContent');
 
       cy.get('@currentContent').scrollIntoView().should('be.visible');
-      visited.add(buttonSelector);
+    });
+  });
+
+  sidebarNavigationDisclosures.reverse().forEach((disclosureName) => {
+    const buttonSelector = `${BASE}-button-${disclosureName}`;
+
+    it(`should close the the "${disclosureName}" sidebar disclosure`, () => {
+      cy.get(`[data-cy="${buttonSelector}"]`).click().should('have.attr', 'aria-expanded', 'false');
     });
   });
 });
@@ -61,48 +59,3 @@ describe('Sidebar opens correct section on first load', () => {
     alertDialogLink.should('have.attr', 'aria-current', 'page');
   });
 });
-
-/**
- * Helper that goes through all the top level disclosure buttons. If their associated content has no unvisited disclosures within it, cypress closes the disclosure and expects the aria-expanded attribute to update accordingly.
- * @param visited {Set<string>} - set of the data-cy attribute values of disclosures that have aleady been tested
- */
-function cleanupOpenDisclosures(visited: Set<string>) {
-  cy.get('aside').then(($aside) => {
-    // array of the HTMLElements of all the expanded disclosure buttons
-    const expandedButtons = $aside.find(`[aria-expanded="true"]`).toArray();
-
-    // array of the cy attribute values of all the top level expanded and visited buttons (decided we don't need to collapse nested disclosures because can just collapse the top level one)
-    const filteredCyAttributes = expandedButtons.reduce((accum, disclosure) => {
-      const cyAttr = disclosure.getAttribute('data-cy');
-      const level = Number(disclosure.getAttribute('data-level'));
-
-      return visited.has(cyAttr) && level === 0 ? [...accum, cyAttr] : accum;
-    }, []);
-
-    filteredCyAttributes.forEach((currentSelector) => {
-      // get the content associated with the current button
-      cy.get(`[data-cy="${currentSelector.replace('button', 'content')}"]`)
-        // returns an array of disclosure buttons inside the content that are not in the visited set
-        .then(($content) => {
-          return $content
-            .find('button')
-            .toArray()
-            .filter(($btn) => {
-              const btnAttr = $btn.getAttribute('data-cy');
-              return !visited.has(btnAttr);
-            });
-        })
-        // returns a boolean - the disclosure should close if there are no unvisited disclosures in the content
-        .then((result) => {
-          return result.length === 0;
-        })
-        .then((shouldClose) => {
-          if (shouldClose) {
-            cy.log(`closing disclosure button: ${currentSelector}`);
-            cy.get(`[data-cy="${currentSelector}"]`).click().should('have.attr', 'aria-expanded', 'false');
-          }
-        })
-        .end();
-    });
-  });
-}

cypress/integration/site-search/index.spec.ts

@@ -9,7 +9,7 @@ describe('Docs website search', () => {
   });
 
   beforeEach(() => {
-    cy.get('[data-cy="paste-docsearch-container"] button').as('searchButtonEl');
+    cy.get('[data-cy="paste-docsearch-container"] button:visible').as('searchButtonEl');
   });
 
   it('should handle a search string', () => {

cypress/support/commands/parent-commands.ts

@@ -98,7 +98,7 @@ Cypress.Commands.add('getInFixedContainer', (selector) => {
 
 Cypress.Commands.add('visualRegressionTestUrl', ({url, testName}) => {
   cy.visit(url);
-  cy.wait(2000);
+  cy.wait(2500);
   cy.log('[VRT]: checking if VRT is enabled');
 
   if (vrtIsEnabled()) {

packages/paste-core/components/sidebar/src/content-wrappers/SidebarPushContentWrapper.tsx

@@ -41,7 +41,9 @@ export const SidebarPushContentWrapper = React.forwardRef<HTMLDivElement, Sideba
         {...safelySpreadBoxProps(props)}
         ref={ref}
         element={element}
-        style={breakpointIndex === 0 ? undefined : styles}
+        // when using push sidebars in responsive layouts, we don't want any left margin in small screen, or initial SSR render situations. So basically never apply it in those situations
+        style={breakpointIndex === undefined || breakpointIndex === 0 ? undefined : styles}
+        marginLeft={['space0', theme.sizes.sizeSidebar]}
       >
         {children}
       </AnimatedStyledContentWrapper>

packages/paste-core/components/sidebar/src/navigation/SidebarNavigationItem.tsx

@@ -95,7 +95,7 @@ const SidebarNavigationItem = React.forwardRef<HTMLAnchorElement, SidebarNavigat
 );
 SidebarNavigationItem.displayName = 'SidebarNavigationItem';
 SidebarNavigationItem.propTypes = {
-  children: PropTypes.string.isRequired,
+  children: PropTypes.node.isRequired,
   element: PropTypes.string,
   selected: PropTypes.bool,
 };

packages/paste-core/components/topbar/src/Topbar.tsx

@@ -27,13 +27,12 @@ export const Topbar = React.forwardRef<HTMLDivElement, TopbarProps>(
         borderBottomStyle="solid"
         borderBottomColor="colorBorderWeaker"
         paddingX="space70"
-        paddingY="space60"
         position="sticky"
         top="0"
         display="flex"
         justifyContent="space-between"
         alignItems="center"
-        zIndex="zIndex10"
+        zIndex="zIndex40"
       >
         {children}
       </Box>

packages/paste-core/components/topbar/src/TopbarActions.tsx

@@ -2,19 +2,21 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import {Box, safelySpreadBoxProps} from '@twilio-paste/box';
 import type {BoxElementProps} from '@twilio-paste/box';
+import type {ResponsiveValue} from '@twilio-paste/styling-library';
 
 type Justify = 'start' | 'end';
 export interface TopbarActionsProps {
   children: NonNullable<React.ReactNode>;
   element?: BoxElementProps['element'];
   justify?: Justify;
+  display?: ResponsiveValue<'none' | 'flex'>;
 }
 const TopbarActions = React.forwardRef<HTMLDivElement, TopbarActionsProps>(
-  ({children, element = 'TOPBAR_ACTIONS', justify, ...props}, ref) => {
+  ({children, element = 'TOPBAR_ACTIONS', justify, display = 'flex', ...props}, ref) => {
     return (
       <Box
         {...safelySpreadBoxProps(props)}
-        display="flex"
+        display={display}
         justifyContent={justify === 'start' ? 'flex-start' : 'flex-end'}
         flexShrink={justify === 'start' ? null : 0}
         flexWrap="wrap"

packages/paste-core/primitives/box/src/CustomStyleProps.ts

@@ -31,6 +31,7 @@ export const customStyleProps = {
   cursor: true,
   appearance: true,
   transition: true,
+  transitionDelay: true,
   transform: true,
   animation: true,
   transformOrigin: true,

packages/paste-core/primitives/box/src/types.ts

@@ -8,25 +8,7 @@ import type {
   ShadowProps,
   SpaceProps,
   TypographyProps,
-  AnimationProperty,
-  AppearanceProperty,
-  BoxSizingProperty,
-  ClipProperty,
-  CursorProperty,
-  FloatProperty,
-  ObjectFitProperty,
-  ObjectPositionProperty,
-  OpacityProperty,
-  OutlineProperty,
-  PointerEventsProperty,
-  ResizeProperty,
-  TableLayoutProperty,
-  TransformOriginProperty,
-  TransformProperty,
-  TransitionProperty,
-  UserSelectProperty,
-  VisibilityProperty,
-  WillChangeProperty,
+  CSSProps,
 } from '@twilio-paste/style-props';
 import type {CustomTheme} from '@twilio-paste/customization';
 
@@ -41,30 +23,8 @@ export interface BoxBaseStyleProps
     PositionProps,
     TypographyProps,
     FlexboxProps,
-    GridProps {
-  animation?: AnimationProperty;
-  appearance?: AppearanceProperty;
-  boxSizing?: BoxSizingProperty;
-  clip?: ClipProperty;
-  content?: string;
-  cursor?: CursorProperty;
-  float?: FloatProperty;
-  objectFit?: ObjectFitProperty;
-  objectPosition?: ObjectPositionProperty;
-  opacity?: OpacityProperty;
-  outline?: OutlineProperty;
-  pointerEvents?: PointerEventsProperty;
-  resize?: ResizeProperty;
-  tableLayout?: TableLayoutProperty;
-  transform?: TransformProperty;
-  transformOrigin?: TransformOriginProperty;
-  transition?: TransitionProperty;
-  userSelect?: UserSelectProperty;
-  visibility?: VisibilityProperty;
-  willChange?: WillChangeProperty;
-  '-webkit-text-fill-color'?: string;
-  '-webkit-opacity'?: string;
-}
+    GridProps,
+    CSSProps {}
 
 export type BoxPseudoStyleProps = Partial<Record<keyof typeof PseudoPropStyles, BoxBaseStyleProps>>;
 

packages/paste-core/primitives/text/src/CustomStyleProps.ts

@@ -6,6 +6,7 @@ export const customStyleProps = {
   cursor: true,
   outline: true,
   transition: true,
+  transitionDelay: true,
   textDecoration: true,
   textTransform: true,
   whiteSpace: true,

packages/paste-core/primitives/text/src/types.ts

@@ -10,6 +10,7 @@ import type {
   CursorProperty,
   OutlineProperty,
   TransitionProperty,
+  TransitionDelayProperty,
 } from '@twilio-paste/style-props';
 
 import type {PseudoPropStyles} from './PseudoPropStyles';
@@ -20,6 +21,7 @@ export interface TextBaseStyleProps extends OverflowProps, PositionProps, Shadow
   display?: Display;
   outline?: OutlineProperty;
   transition?: TransitionProperty;
+  transitionDelay?: TransitionDelayProperty;
   verticalAlign?: VerticalAlign;
 }
 

packages/paste-style-props/src/types/css-props.ts

@@ -1,4 +1,5 @@
 import type {Properties} from 'csstype';
+import {type ResponsiveValue} from '@twilio-paste/styling-library';
 
 export type AnimationProperty = Properties['animation'];
 export type AppearanceProperty = Properties['appearance'];
@@ -16,6 +17,54 @@ export type TableLayoutProperty = Properties['tableLayout'];
 export type TransformOriginProperty = Properties['transformOrigin'];
 export type TransformProperty = Properties['transform'];
 export type TransitionProperty = Properties['transition'];
+export type TransitionDelayProperty = Properties['transitionDelay'];
 export type UserSelectProperty = Properties['userSelect'];
 export type VisibilityProperty = Properties['visibility'];
 export type WillChangeProperty = Properties['willChange'];
+
+export type Animation = ResponsiveValue<AnimationProperty>;
+export type Appearance = ResponsiveValue<AppearanceProperty>;
+export type BoxSizing = ResponsiveValue<BoxSizingProperty>;
+export type Clip = ResponsiveValue<ClipProperty>;
+export type Cursor = ResponsiveValue<CursorProperty>;
+export type Float = ResponsiveValue<FloatProperty>;
+export type ObjectFit = ResponsiveValue<ObjectFitProperty>;
+export type ObjectPosition = ResponsiveValue<ObjectPositionProperty>;
+export type Opacity = ResponsiveValue<OpacityProperty>;
+export type Outline = ResponsiveValue<OutlineProperty>;
+export type PointerEvents = ResponsiveValue<PointerEventsProperty>;
+export type Resize = ResponsiveValue<ResizeProperty>;
+export type TableLayout = ResponsiveValue<TableLayoutProperty>;
+export type TransformOrigin = ResponsiveValue<TransformOriginProperty>;
+export type Transform = ResponsiveValue<TransformProperty>;
+export type Transition = ResponsiveValue<TransitionProperty>;
+export type TransitionDelay = ResponsiveValue<TransitionDelayProperty>;
+export type UserSelect = ResponsiveValue<UserSelectProperty>;
+export type Visibility = ResponsiveValue<VisibilityProperty>;
+export type WillChange = ResponsiveValue<WillChangeProperty>;
+
+export type CSSProps = {
+  animation?: Animation;
+  appearance?: Appearance;
+  boxSizing?: BoxSizing;
+  clip?: Clip;
+  content?: string;
+  cursor?: Cursor;
+  float?: Float;
+  objectFit?: ObjectFit;
+  objectPosition?: ObjectPosition;
+  opacity?: Opacity;
+  outline?: Outline;
+  pointerEvents?: PointerEvents;
+  resize?: Resize;
+  tableLayout?: TableLayout;
+  transform?: Transform;
+  transformOrigin?: TransformOrigin;
+  transition?: Transition;
+  transitionDelay?: TransitionDelay;
+  userSelect?: UserSelect;
+  visibility?: Visibility;
+  willChange?: WillChange;
+  '-webkit-text-fill-color'?: string;
+  '-webkit-opacity'?: string;
+};