diff --git a/packages/blade/src/components/TopNav/_decisions/anatomy.png b/packages/blade/src/components/TopNav/_decisions/anatomy.png new file mode 100644 index 00000000000..5863c0ca51d Binary files /dev/null and b/packages/blade/src/components/TopNav/_decisions/anatomy.png differ diff --git a/packages/blade/src/components/TopNav/_decisions/decisions.md b/packages/blade/src/components/TopNav/_decisions/decisions.md index 6942ede4dd2..c5b92cb10f7 100644 --- a/packages/blade/src/components/TopNav/_decisions/decisions.md +++ b/packages/blade/src/components/TopNav/_decisions/decisions.md @@ -2,7 +2,7 @@ The navigation bar is positioned at the top of the screen that provides quick access to different products, search & user profile. - + ## Links @@ -24,6 +24,8 @@ The navigation bar is positioned at the top of the screen that provides quick ac - Avatar - MenuOverlay +Anatomy of TopNav + ## Basic Usage ```jsx @@ -33,16 +35,38 @@ The navigation bar is positioned at the top of the screen that provides quick ac - - - Money - Payroll - - Others - - { /* Other Menu Items */ } - - + + {({ items, overflowingItems }) => { + return ( + <> + + {items.map((item) => ( + + ))} + + + + {overflowingItems.map((item) => { + return ( + + + + ); + })} + + + ); + }} @@ -88,11 +112,11 @@ The navigation bar is positioned at the top of the screen that provides quick ac Desktop Navigation Bar: -TopNav Desktop Example +TopNav Desktop Example Mobile Navigation Bar: -TopNav Mobile Example +TopNav Mobile Example ## API @@ -122,6 +146,155 @@ The container for the right-aligned actions like search, buttons, and user profi ### TabNav +The horizontal navigation bar that contains multiple navigation items, each represented by TabNavItem. + +TabNav's interaction is as follows: + +1. There might already be items under More even at the highest screen size. These items might need a custom order. +2. Once the screen size starts getting reduced, more items will start moving into More. +3. The order of these items would follow a logical order. They keep getting added ahead of the already existing items. So the last item to go into More is the first item that you see when you click on More. + +TabNav automatically handles all these edge cases & responsiveness and let's you focus on the rendering of the items via the [render props](https://reactpatterns.js.org/docs/function-as-child-component/) pattern. + +```jsx + + {({ items, overflowingItems }) => { + return ( + <> + + {items.map((item) => ( + + ))} + + + + {overflowingItems.map((item) => { + return ( + + + + ); + })} + + + ); + }} + +``` + +#### TabNav Props + +Main tab navigation component that will contain multiple navigation items and will handle the responsiveness of the items. + +```ts +type TabNav = { + children: React.ReactNode; + /** + * Array of navigation items + */ + items: Array< + TabNavItem & { + /** + * force this item to always be inside "more" regardless of screen size + */ + isAlwaysOverflowing?: boolean; + } + >; +}; +``` + +#### TabNavItem Props + +The individual navigation item that will be rendered inside the TabNav component. + +```ts +type TabNavItem = { + /** + * href of the link + */ + href?: LinkProps['href']; + /** + * Anchor tag `target` attribute + */ + target?: LinkProps['target']; + /** + * as prop to pass ReactRouter's Link component. + * + * @default 'a' + * + * @example + * ```jsx + * import { Link } from 'react-router-dom'; + * + * + * ``` + */ + as: React.ComponentType; + /** + * Selected state of the navigation item. + * + * @default false + */ + isActive?: boolean; + /** + * Icon to render before the navigation item. + * + * @default undefined + */ + icon?: IconComponent; + /** + * Title of the navigation item. + */ + title?: React.ReactNode; + /** + * Accessibility label for the navigation item. + */ + accessibilityLabel?: string; +}; +``` + +#### TabNavItems Props + +The container for the navigation items. + +```ts +type TabNavItems = { + children: React.ReactNode; +}; +``` + +#### Why was this prop-based API chosen over the old compound component API? + +The old component's interaction was much simpler compared to this new TabNav, the old TabNav was just a horizontal navigation bar that contained multiple navigation items and it scrolled horizontally when the items could no longer fit in the available space. + +But the new TabNav is much more complex, it needs to accomodate for screen real estate, automagically move items to the "More" menu when they can't fit, and also handle responsiveness. This is why we chose to go with a prop-based API for the new TabNav. + +The prop based API allows us to have the data for the whole TabNav in one place so we can internally move things around as needed but still allow the consumer to have full control over the rendering of the items. + +For more detail please read the Alternatives section. + +
+ +Old API + The horizontal navigation bar that contains multiple navigation items, each represented by `TabNavItem`. Inspired from [Primer TabNav](https://primer.style/components/tab-nav/react/alpha). @@ -192,10 +365,9 @@ const WithMenu = () => { - {selected ? `Others: ${selected}` : "Others"} - + /> setSelected("Engage")}>Engage setSelected("Payroll")}>Payroll @@ -212,10 +384,47 @@ Once the available space for TabNavItems are less, the TabNav will start to hori https://github.com/razorpay/blade/assets/35374649/8a0fb6ae-cedd-4065-80ed-27647938453c +
## Mobile UX -On mobile, the TabNav component will no longer be present and the TopNavContent will contain a single button to toggle the side navigation. The TopNavActions will contain the search input, buttons, and user profile. +TopNav Mobile Example + +On mobile, most of the components from desktop aren't visible due to the lack of screen real estate. +Thus, we will let consumers decide what components they want to show on mobile and what they want to hide. + +Given the simplicity of the mobile navigation bar, consumers can conditionally render the components based on the screen size. + +Example: + +```jsx +const isMobile = useIsMobile(); + +return ( + <> + + + {isMobile ? ( + <> + + Home + + + Payments + + + + ) : ( + <> + + + + + )} + + +); +``` **Q:** So where will the product navigation items go? **Ans:** The product navigation items will be moved to the bottom of the screen, but this will be part of a separate component called `BottomNavigation` which we will ship in phase 2. @@ -264,6 +473,298 @@ const Dashboard = () => { - The navigation bar will have `role=navigation` to indicate that it is a navigation landmark. - TopNav sub components will only compose other components and will not have any ARIA roles or attributes. + +### Alternatives considered for new TabNav API + +
+ +Go inside rabbit hole + + +### The Problem + +The new interaction that we have gotten for top nav is a bit more trickier to implement than it seems while ensuring flexibility of the component. + +For example, we want users to: + +1. Be able to add a “More” dropdown with custom items (It’s just a Menu) +2. When the screen size reduces, automatically inject extra items into “More” menu +3. Have the flexibility to customize the what’s inside “More” menu + +**Our current API looks like this:** + +```jsx + + + + + + + + {overflowingItems.map((item) => { + // ?? + })} + + + + + + + + + +``` + +**This API has few issues:** + +1. While it lets you add the “More” Menu and choose initial ordering of Magic Checkout & RazorX, when screen size reduces there is no straightforward or intuitive way to move the overflowing items into the “More” Menu +2. Even if we could somehow magically get the overflowingItems what data will item contain that will enable us to render the ? We need title, description, icon etc data for rendering which the may not even need or be provided with since we don’t need to render description or icon. + +---- + + +> NOTE: If you want to go into the rabbit hole you can read the alternatives below. + +### Alternative APIs + +**Table Like Data API (Accepted approach):** + +A data driven API where we pass the data for the items and use render props to render the items and the overflowingItems. + +**Pros:** +1. Users have easy access to the overflowingItems via props +2. Intuitive and faimilar API, similar to Table API +3. Users have the flexibility to render TabNavItemLinks or any other component. +4. Users can easily control the order of the items inside the "More" dropdown +5. We have the data of the items so we can handle the responsiveness internally + +**Cons:** +1. More verbose than compound API + +```jsx + + {({ items, overflowingItems }) => { + return ( + <> + + {items.map((item) => ( + + ))} + + + + {overflowingItems.map((item) => { + return ( + + + + ); + })} + + + ); + }} + +``` + +**Config Based API:** + +Use config driven API to define the data and the rendering of the items and internally let TabNav handle rendering. + +**Pros:** + +1. Users have easy access to the overflowingItems via props +We have the data of the item inside the overflowingItems and can render it inside the Menu with any custom menu item component. +1. Users still have the flexibility to render TabNavItemLinks or any other component. + +**Cons:** + +1. More verbose than compound API +2. Not as intuitive very intuitive to use +3. Totally new API from the previous API that we had + +```jsx +const renderTabNavItem = (props) => { + return +} + + {} }, + { + href: '/capital', + title: 'Capital', + // description/icon etc extra props can later be rendered inside + description: 'Description', + icon: CapitalIcon, + render: renderTabNavItem, + }, + { + href: '/more', + render: (props) => ( + + } /> + + {props.overflowingItems.map((item) => { + return ( + + // custom explore item + + + ); + })} + + + + + + + + + ), + }, + ]} +/> +``` + + +**Alternative Approach: JSX with MetaData:** + +Another approach where we can pass a new overflowMetadata prop to TabNavItem components and use that to render the overflowingItems later on. + +**Pros:** +1. Familiar compound like API & less verbose +2. Arguably less confusing than other alternative approaches + +**Cons:** +1. Odd indirection & data flow, where the overflowMetadata gets indirectly passed to the overflowingItems +2. Introduces 1 extra component TabNavItems which wraps all other TabNavItemLink + +```jsx +const { overflowingItems, setOverflowingItems } = React.useState([]); + + + { + setOverflowingItems(items); + }} + > + + + + + + } /> + + // render the overflowing items + {overflowingItems.map((item) => { + return ( + + + + ); + })} + + + + + + + + + +``` + +**Alternative Approach: JSX as Data:** + +Another approach is this, where we treat the JSX as the Data. +This is similar to Dropdown where on initial render we loop over all the JSX elements build a list and store it and from that list we render. + +**Not leaning towards this API mainly because:** +1. JSX as Data gets very [complicated](https://github.com/razorpay/blade/blob/2e4b2cb309cdf3e87982cda9252e9ce97747c475/packages/blade/src/components/ActionList/actionListUtils.ts#L137-L159) as seen on Dropdown, and most of the time breaks composition, like it looks like the component is flexible and composable but in reality it isn’t. +2. Sets a odd expectation, where users need to pass the description/icon etc props to TabNavItemLink which that component may not even use but rather they are treated as “data” attributes for the overflowingItems +3. We need to get the overflowingItems from somewhere, it will either be as a controlled state or we may need to introduce a render prop inside + +**Pros** +1. Retains the original API that we had intact and doesn’t introduces a new API + +```jsx +const [overflowingItems, setOverflowingItems] = useState([]); + + setOverflowingItems(items)}> + + + + + + + {overflowingItems.map((item) => { + return ( + + + + ); + })} + + + + + + + + + +``` + +
+ ## References - [NavBar - NextUI](https://nextui.org/docs/components/navbar) diff --git a/packages/blade/src/components/TopNav/_decisions/top-nav-bar-new.png b/packages/blade/src/components/TopNav/_decisions/top-nav-bar-new.png new file mode 100644 index 00000000000..3ff9935897e Binary files /dev/null and b/packages/blade/src/components/TopNav/_decisions/top-nav-bar-new.png differ diff --git a/packages/blade/src/components/TopNav/_decisions/top-nav-desktop-example-new.png b/packages/blade/src/components/TopNav/_decisions/top-nav-desktop-example-new.png new file mode 100644 index 00000000000..12eb50aa721 Binary files /dev/null and b/packages/blade/src/components/TopNav/_decisions/top-nav-desktop-example-new.png differ diff --git a/packages/blade/src/components/TopNav/_decisions/top-nav-mobile-example-new.png b/packages/blade/src/components/TopNav/_decisions/top-nav-mobile-example-new.png new file mode 100644 index 00000000000..32779228a98 Binary files /dev/null and b/packages/blade/src/components/TopNav/_decisions/top-nav-mobile-example-new.png differ