@juspay/blend-design-system 0.0.37-beta.2 → 0.0.37-beta.4

package/lib/components/Directory/Section.tsx

@@ -0,0 +1,270 @@
+import React, {
+    createContext,
+    useContext,
+    useCallback,
+    useRef,
+    useLayoutEffect,
+} from 'react'
+import type { SectionProps } from './types'
+import { ChevronDown } from 'lucide-react'
+import NavItem from './NavItem'
+import Block from '../Primitives/Block/Block'
+import Text from '../Text/Text'
+import styled from 'styled-components'
+import { useResponsiveTokens } from '../../hooks/useResponsiveTokens'
+import { DirectoryTokenType } from './directory.tokens'
+import { useSectionScroll } from '../../hooks/useSectionScroll'
+
+type SectionStateContextValue = {
+    sectionStates: Map<number, boolean>
+    setSectionState: (index: number, isOpen: boolean) => void
+}
+
+const SectionStateContext = createContext<SectionStateContextValue | null>(null)
+
+const useSectionState = () => {
+    const context = useContext(SectionStateContext)
+    return context
+}
+
+export { SectionStateContext }
+
+const ChevronWrapper = styled(Block)<{
+    $isOpen: boolean
+    $tokens: DirectoryTokenType
+}>`
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin-left: auto;
+
+    & > svg {
+        width: ${({ $tokens }) =>
+            $tokens.section.header.chevron.width} !important;
+        height: ${({ $tokens }) =>
+            $tokens.section.header.chevron.width} !important;
+        transition: transform 150ms;
+        transform: ${({ $isOpen }) =>
+            $isOpen ? 'rotate(180deg)' : 'rotate(0)'};
+    }
+`
+
+const Section = ({
+    section,
+    sectionIndex,
+    onNavigateBetweenSections,
+    idPrefix,
+    iconOnlyMode = false,
+}: SectionProps) => {
+    const tokens = useResponsiveTokens<DirectoryTokenType>('DIRECTORY')
+    const sectionStateContext = useSectionState()
+    const { scrollIntoView } = useSectionScroll()
+
+    const defaultIsOpen = section.defaultOpen !== false
+    const sharedIsOpen = sectionStateContext?.sectionStates.get(sectionIndex)
+    const [localIsOpen, setLocalIsOpen] = React.useState(defaultIsOpen)
+
+    const isOpen = sharedIsOpen !== undefined ? sharedIsOpen : localIsOpen
+    const previousIsOpen = useRef(isOpen)
+
+    const setIsOpen = useCallback(
+        (value: boolean) => {
+            if (sectionStateContext) {
+                sectionStateContext.setSectionState(sectionIndex, value)
+            } else {
+                setLocalIsOpen(value)
+            }
+        },
+        [sectionIndex, sectionStateContext]
+    )
+    const sectionRef = useRef<HTMLDivElement>(null)
+    const headerRef = useRef<HTMLDivElement>(null)
+    const itemRefs = useRef<Array<React.RefObject<HTMLElement | null>>>([])
+
+    React.useEffect(() => {
+        if (section.items) {
+            itemRefs.current = section.items.map(() =>
+                React.createRef<HTMLElement | null>()
+            )
+        }
+    }, [section.items])
+
+    useLayoutEffect(() => {
+        const wasCollapsed = !previousIsOpen.current
+        const isExpanding = isOpen && wasCollapsed
+        previousIsOpen.current = isOpen
+
+        if (isExpanding && sectionRef.current) {
+            scrollIntoView(sectionRef.current)
+        }
+    }, [isOpen, scrollIntoView])
+
+    const toggleSection = () => {
+        if (!iconOnlyMode) {
+            setIsOpen(!isOpen)
+        }
+    }
+
+    const handleKeyDown = (e: React.KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+            toggleSection()
+        } else if (e.key === 'ArrowDown') {
+            e.preventDefault()
+            if (!isOpen) {
+                setIsOpen(true)
+            } else {
+                const firstItem = sectionRef.current
+                    ?.querySelector('ul')
+                    ?.querySelector('button, a')
+                if (firstItem) {
+                    ;(firstItem as HTMLElement).focus()
+                } else {
+                    onNavigateBetweenSections('down', sectionIndex)
+                }
+            }
+        } else if (e.key === 'ArrowUp') {
+            e.preventDefault()
+            onNavigateBetweenSections('up', sectionIndex)
+        }
+    }
+
+    const handleItemNavigation = (
+        direction: 'up' | 'down',
+        currentIndex: number
+    ) => {
+        if (direction === 'up') {
+            if (currentIndex === 0) {
+                headerRef.current?.focus()
+            } else {
+                const prevItem = sectionRef.current
+                    ?.querySelector('ul')
+                    ?.querySelectorAll('button, a')[currentIndex - 1]
+                if (prevItem) {
+                    ;(prevItem as HTMLElement).focus()
+                }
+            }
+        } else {
+            if (currentIndex === (section.items?.length || 0) - 1) {
+                onNavigateBetweenSections('down', sectionIndex)
+            } else {
+                const nextItem = sectionRef.current
+                    ?.querySelector('ul')
+                    ?.querySelectorAll('button, a')[currentIndex + 1]
+                if (nextItem) {
+                    ;(nextItem as HTMLElement).focus()
+                }
+            }
+        }
+    }
+
+    const isCollapsible = section.isCollapsible !== false
+
+    return (
+        <Block
+            display="flex"
+            flexDirection="column"
+            gap={iconOnlyMode ? '8px' : tokens.section.gap}
+            width="100%"
+            ref={sectionRef}
+            data-state={isOpen ? 'open' : 'closed'}
+            key={`section-${sectionIndex}`}
+            data-element="sidebar-section"
+            data-id={section.label || `section-${sectionIndex}`}
+            data-status={isOpen ? 'expanded' : 'collapsed'}
+        >
+            {section.label && !iconOnlyMode && (
+                <Block
+                    display="flex"
+                    alignItems="center"
+                    paddingX={tokens.section.header.padding.x}
+                    paddingY={tokens.section.header.padding.y}
+                    cursor={isCollapsible ? 'pointer' : undefined}
+                    ref={headerRef}
+                    onClick={isCollapsible ? toggleSection : undefined}
+                    onKeyDown={isCollapsible ? handleKeyDown : undefined}
+                    role={isCollapsible ? 'button' : undefined}
+                    tabIndex={isCollapsible ? 0 : undefined}
+                    aria-expanded={
+                        isCollapsible ? (isOpen ? true : false) : undefined
+                    }
+                    aria-controls={
+                        isCollapsible && isOpen
+                            ? `${idPrefix || ''}section-content-${sectionIndex}`
+                            : undefined
+                    }
+                    aria-label={
+                        isCollapsible && section.label
+                            ? `${section.label}, ${isOpen ? 'expanded' : 'collapsed'}`
+                            : undefined
+                    }
+                >
+                    <Text
+                        variant="body.sm"
+                        color={tokens.section.header.label.color}
+                        fontWeight={tokens.section.header.label.fontWeight}
+                        fontSize={tokens.section.header.label.fontSize}
+                    >
+                        {section.label.toUpperCase()}
+                    </Text>
+                    {isCollapsible && (
+                        <ChevronWrapper
+                            $isOpen={isOpen}
+                            $tokens={tokens}
+                            aria-hidden="true"
+                        >
+                            <ChevronDown
+                                color={tokens.section.header.chevron.color}
+                            />
+                        </ChevronWrapper>
+                    )}
+                </Block>
+            )}
+
+            {iconOnlyMode && sectionIndex > 0 && (
+                <Block
+                    width="32px"
+                    height="1px"
+                    backgroundColor={tokens.section.header.label.color}
+                    style={{
+                        opacity: 0.2,
+                        margin: '0 auto 8px auto',
+                    }}
+                    role="separator"
+                    aria-hidden="true"
+                />
+            )}
+
+            {section.items && (isOpen || iconOnlyMode) && (
+                <ul
+                    style={{
+                        width: '100%',
+                        display: 'flex',
+                        flexDirection: 'column',
+                        gap: tokens.section.itemList.gap,
+                    }}
+                    id={`${idPrefix || ''}section-content-${sectionIndex}`}
+                    role="list"
+                    aria-label={
+                        section.label
+                            ? `${section.label} navigation`
+                            : undefined
+                    }
+                >
+                    {section.items.map((item, itemIdx) => (
+                        <NavItem
+                            key={itemIdx}
+                            item={item}
+                            index={itemIdx}
+                            itemPath={item.label}
+                            iconOnlyMode={iconOnlyMode}
+                            onNavigate={handleItemNavigation}
+                        />
+                    ))}
+                </ul>
+            )}
+        </Block>
+    )
+}
+
+export default Section

package/lib/components/Directory/directory.tokens.ts

@@ -0,0 +1,283 @@
+import type { CSSObject } from 'styled-components'
+import { type FoundationTokenType } from '../../tokens/theme.token'
+import { BreakpointType } from '../../breakpoints/breakPoints'
+
+export type DirectoryState = 'default' | 'hover' | 'active'
+
+/**
+ * Directory Tokens following the pattern: [target].CSSProp.[state]
+ *
+ * Hierarchical Structure:
+ * - Container level: gap, paddingX, paddingY (spacing for the entire directory)
+ * - Section level: Contains header, label, chevron, and item
+ *   - header: Controls section header layout
+ *   - label: Controls section label text styling
+ *   - chevron: Controls section collapse/expand icon
+ *   - item: Navigation items within the section (NavItem)
+ *     - nested: Child items within navigation items
+ *
+ * Pattern examples:
+ * - gap (space between sections)
+ * - paddingX (container horizontal padding)
+ * - section.header.padding (section header spacing)
+ * - section.item.backgroundColor.[state] (nav item background with states)
+ * - section.item.nested.paddingLeft (nested item indentation)
+ */
+export type DirectoryTokenType = {
+    // Container-level spacing
+    gap: CSSObject['gap'] // Space between sections
+    paddingX: CSSObject['padding'] // Container horizontal padding
+    paddingY: CSSObject['padding'] // Container vertical padding
+
+    // Section configuration
+    section: {
+        gap: CSSObject['gap'] // Space between section header and items
+
+        // Section header (clickable area with label and chevron)
+        header: {
+            padding: {
+                x: CSSObject['padding']
+                y: CSSObject['padding']
+            }
+            label: {
+                fontSize: CSSObject['fontSize'] // Label text size
+                color: CSSObject['color'] // Label text color
+                fontWeight: CSSObject['fontWeight'] // Label text weight
+            }
+            // Section collapse/expand chevron icon
+            chevron: {
+                width: CSSObject['width'] // Chevron icon width
+                color: CSSObject['color'] // Chevron icon color
+            }
+        }
+
+        // Section label text styling
+
+        // Navigation items within the section
+        itemList: {
+            gap: CSSObject['gap'] // Space between items in the list
+
+            item: {
+                padding: {
+                    x: CSSObject['padding']
+                    y: CSSObject['padding']
+                }
+                iconOnlyPadding: {
+                    paddingTop: CSSObject['paddingTop']
+                    paddingBottom: CSSObject['paddingBottom']
+                    paddingLeft: CSSObject['paddingLeft']
+                    paddingRight: CSSObject['paddingRight']
+                }
+                gap: CSSObject['gap'] // Gap between icon and text within item
+                borderRadius: CSSObject['borderRadius'] // Item border radius
+                fontWeight: CSSObject['fontWeight'] // Item text weight
+                fontSize: CSSObject['fontSize'] // Item text size
+                transition: CSSObject['transition'] // Hover/active transitions
+
+                // Item background color for different states
+                backgroundColor: {
+                    [key in DirectoryState]: CSSObject['backgroundColor']
+                }
+
+                // Item text color for different states
+                color: {
+                    [key in DirectoryState]: CSSObject['color']
+                }
+
+                // Icon/leftSlot styling
+                icon: {
+                    width: CSSObject['width'] // Icon size
+                }
+
+                // Chevron for expandable items
+                chevron: {
+                    width: CSSObject['width'] // Chevron icon size
+                    color: CSSObject['color'] // Chevron icon color
+                }
+            }
+
+            // Nested/child items configuration
+            nested: {
+                paddingLeft: CSSObject['paddingLeft'] // Nested item indentation
+                marginTop: CSSObject['marginTop'] // Space above nested list
+
+                // Vertical connector line for nested items
+                border: {
+                    width: CSSObject['width'] // Border line width
+                    color: CSSObject['color'] // Border line color
+                    leftOffset: CSSObject['left'] // Border line left position
+                }
+            }
+        }
+    }
+}
+
+export type ResponsiveDirectoryTokens = {
+    [key in keyof BreakpointType]: DirectoryTokenType
+}
+
+export const getDirectoryTokens = (
+    foundationToken: FoundationTokenType
+): ResponsiveDirectoryTokens => {
+    return {
+        sm: {
+            gap: foundationToken.unit[24],
+            paddingX: foundationToken.unit[8],
+            paddingY: foundationToken.unit[8],
+
+            section: {
+                gap: foundationToken.unit[4],
+
+                header: {
+                    padding: {
+                        x: foundationToken.unit[12],
+                        y: foundationToken.unit[2],
+                    },
+                    label: {
+                        fontSize: foundationToken.font.size.body.sm.fontSize,
+                        color: foundationToken.colors.gray[400],
+                        fontWeight: 500,
+                    },
+                    chevron: {
+                        width: foundationToken.unit[16],
+                        color: foundationToken.colors.gray[400],
+                    },
+                },
+
+                itemList: {
+                    gap: foundationToken.unit[8],
+
+                    item: {
+                        padding: {
+                            x: foundationToken.unit[12],
+                            y: foundationToken.unit[6],
+                        },
+                        iconOnlyPadding: {
+                            paddingTop: foundationToken.unit[8],
+                            paddingBottom: foundationToken.unit[8],
+                            paddingLeft: foundationToken.unit[10],
+                            paddingRight: foundationToken.unit[10],
+                        },
+                        gap: foundationToken.unit[12],
+                        borderRadius: foundationToken.border.radius[4],
+                        fontWeight: 500,
+                        fontSize: foundationToken.font.size.body.md.fontSize,
+                        transition: 'background-color 0.2s, color 0.2s',
+
+                        backgroundColor: {
+                            default: 'transparent',
+                            hover: foundationToken.colors.gray[50],
+                            active: foundationToken.colors.gray[150],
+                        },
+
+                        color: {
+                            default: foundationToken.colors.gray[600],
+                            hover: foundationToken.colors.gray[600],
+                            active: foundationToken.colors.gray[1000],
+                        },
+
+                        icon: {
+                            width: foundationToken.unit[20],
+                        },
+
+                        chevron: {
+                            width: foundationToken.unit[16],
+                            color: foundationToken.colors.gray[600],
+                        },
+                    },
+
+                    nested: {
+                        paddingLeft: foundationToken.unit[24],
+                        marginTop: foundationToken.unit[8],
+
+                        border: {
+                            width: foundationToken.unit[1],
+                            color: foundationToken.colors.gray[200],
+                            leftOffset: foundationToken.unit[16],
+                        },
+                    },
+                },
+            },
+        },
+
+        lg: {
+            gap: foundationToken.unit[24],
+            paddingX: foundationToken.unit[12],
+            paddingY: foundationToken.unit[12],
+
+            section: {
+                gap: foundationToken.unit[4],
+
+                header: {
+                    padding: {
+                        x: foundationToken.unit[12],
+                        y: foundationToken.unit[2],
+                    },
+                    label: {
+                        fontSize: foundationToken.font.size.body.sm.fontSize,
+                        color: foundationToken.colors.gray[400],
+                        fontWeight: 600,
+                    },
+                    chevron: {
+                        width: foundationToken.unit[16],
+                        color: foundationToken.colors.gray[400],
+                    },
+                },
+
+                itemList: {
+                    gap: foundationToken.unit[8],
+
+                    item: {
+                        padding: {
+                            x: foundationToken.unit[12],
+                            y: foundationToken.unit[6],
+                        },
+                        iconOnlyPadding: {
+                            paddingTop: foundationToken.unit[8],
+                            paddingBottom: foundationToken.unit[8],
+                            paddingLeft: foundationToken.unit[10],
+                            paddingRight: foundationToken.unit[10],
+                        },
+                        gap: foundationToken.unit[10],
+                        borderRadius: foundationToken.border.radius[4],
+                        fontWeight: 500,
+                        fontSize: foundationToken.font.size.body.md.fontSize,
+                        transition: 'background-color 0.2s, color 0.2s',
+
+                        backgroundColor: {
+                            default: 'transparent',
+                            hover: foundationToken.colors.gray[50],
+                            active: foundationToken.colors.gray[150],
+                        },
+
+                        color: {
+                            default: foundationToken.colors.gray[600],
+                            hover: foundationToken.colors.gray[600],
+                            active: foundationToken.colors.gray[1000],
+                        },
+
+                        icon: {
+                            width: foundationToken.unit[14],
+                        },
+
+                        chevron: {
+                            width: foundationToken.unit[16],
+                            color: foundationToken.colors.gray[600],
+                        },
+                    },
+
+                    nested: {
+                        paddingLeft: foundationToken.unit[24],
+                        marginTop: foundationToken.unit[8],
+
+                        border: {
+                            width: foundationToken.unit[1],
+                            color: foundationToken.colors.gray[200],
+                            leftOffset: foundationToken.unit[16],
+                        },
+                    },
+                },
+            },
+        },
+    }
+}

package/lib/components/Directory/index.ts

@@ -0,0 +1,3 @@
+export { default as Directory } from './Directory'
+export * from './directory.tokens'
+export * from './types'

package/lib/components/Directory/types.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react'
+
+export type DirectoryProps = {
+    directoryData: DirectoryData[]
+    idPrefix?: string
+    activeItem?: string | null
+    onActiveItemChange?: (item: string | null) => void
+    defaultActiveItem?: string | null
+    iconOnlyMode?: boolean
+}
+
+export type DirectoryData = {
+    label?: string
+    items?: NavbarItem[]
+    isCollapsible?: boolean
+    defaultOpen?: boolean
+}
+
+export type NavbarItem = {
+    label: string
+    items?: NavbarItem[]
+    leftSlot?: ReactNode
+    rightSlot?: ReactNode
+    onClick?: () => void
+    href?: string
+    isSelected?: boolean
+    /**
+     * When true, the item appears in the Sidebar mobile navigation drawer.
+     * Desktop always renders all items regardless of this flag.
+     */
+    showOnMobile?: boolean
+}
+
+export type SectionProps = {
+    section: DirectoryData
+    sectionIndex: number
+    // totalSections: number;
+    onNavigateBetweenSections: (
+        direction: 'up' | 'down',
+        currentIndex: number
+    ) => void
+    idPrefix?: string
+    iconOnlyMode?: boolean
+}
+
+export type NavItemProps = {
+    item: NavbarItem
+    index: number
+    onNavigate: (direction: 'up' | 'down', currentIndex: number) => void
+    itemPath?: string
+    iconOnlyMode?: boolean
+}

package/lib/components/Directory/utils.ts

@@ -0,0 +1,77 @@
+export const handleSectionNavigation = (
+    direction: 'up' | 'down',
+    currentIndex: number,
+    totalItems: number,
+    selector: string = '[data-state]',
+    childSelector: string = '[role="button"]'
+) => {
+    const nextIndex =
+        direction === 'up'
+            ? Math.max(0, currentIndex - 1)
+            : Math.min(totalItems - 1, currentIndex + 1)
+
+    if (nextIndex !== currentIndex) {
+        const nextSection = document.querySelectorAll(selector)[nextIndex]
+        const elementToFocus = nextSection?.querySelector(
+            childSelector
+        ) as HTMLElement
+
+        if (elementToFocus) {
+            elementToFocus.focus()
+        }
+    }
+
+    return nextIndex
+}
+
+export const handleKeyDown = (
+    e: React.KeyboardEvent,
+    options: {
+        hasChildren?: boolean
+        isExpanded?: boolean
+        setIsExpanded?: (value: boolean) => void
+        handleClick?: () => void
+        index?: number
+        onNavigate?: (direction: 'up' | 'down', index: number) => void
+    }
+) => {
+    const {
+        hasChildren,
+        isExpanded,
+        setIsExpanded,
+        handleClick,
+        index,
+        onNavigate,
+    } = options
+
+    if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault()
+        handleClick?.()
+    } else if (
+        e.key === 'ArrowRight' &&
+        hasChildren &&
+        !isExpanded &&
+        setIsExpanded
+    ) {
+        e.preventDefault()
+        setIsExpanded(true)
+    } else if (
+        e.key === 'ArrowLeft' &&
+        hasChildren &&
+        isExpanded &&
+        setIsExpanded
+    ) {
+        e.preventDefault()
+        setIsExpanded(false)
+    } else if (
+        e.key === 'ArrowDown' &&
+        onNavigate &&
+        typeof index === 'number'
+    ) {
+        e.preventDefault()
+        onNavigate('down', index)
+    } else if (e.key === 'ArrowUp' && onNavigate && typeof index === 'number') {
+        e.preventDefault()
+        onNavigate('up', index)
+    }
+}