); } } ``` ### First Component ```tsx // pages/index.tsx import { Button, Flex, Text } from "@bonyan/ui"; export default function Home() { return ( Welcome to Bonyan ); } ``` ## Bonyan Components Bonyan provides 83+ components organized into categories: ### Form & Input Components - `Button`, `ButtonGroup` - Primary actions and grouped buttons - `TextInput`, `Textarea` - Text input fields with validation - `CheckBox`, `Radio`, `ToggleSwitch` - Selection controls - `InputFile`, `Searchbox` - File upload and search inputs - `DatePicker`, `PinCode` - Specialized input components - `Slider`, `RangeSlider` - Range selection controls - `Wheel`, `WheelTimePicker` - Picker components ### Layout & Container Components - `Flex`, `Block` - Flexible layouts and containers - `Row`, `RowContent`, `NestableRow` - List and table row layouts - `Divider`, `SectionSeparator` - Content separation - `AspectRatio` - Responsive aspect ratio containers - `InView` - Viewport intersection utilities ### Navigation Components - `TopAppBar`, `ActionBar` - Application headers - `BottomNavigation`, `BottomNavigationItem` - Mobile navigation - `Breadcrumb`, `BreadcrumbItem` - Breadcrumb navigation - `Tab`, `TabItem` - Tab navigation - `Menu`, `Dropdown` - Dropdown menus - `Stepper` - Step-by-step navigation ### Overlay & Modal Components - `Modal`, `Dialog` - Modal dialogs - `BottomSheet` - Mobile bottom sheets - `Tooltip` - Contextual tooltips - `Toast` - Notification toasts ### Data Display Components - `Text`, `Title`, `Label` - Typography components - `Badge`, `Chip` - Status and tag indicators - `Table` - Data tables - `Price`, `Toman` - Currency display - `Rate`, `RateBar` - Rating components - `ProgressBar`, `ProgressStep` - Progress indicators - `Loading`, `Skeleton` - Loading states - `EmptyState` - Empty state illustrations ### Media & Visual Components - `Img` - Enhanced image component - `Icon`, `ServiceIcon`, `BankIcon` - Icon components - `Illustration` - Illustration assets - `Map`, `MapPin` - Map components - `Branding` - Brand assets ### Feedback & Status Components - `Banner`, `InlineMessage` - Alert messages - `Validation` - Form validation messages - `TryAgainAction` - Error recovery actions - `CountDown` - Countdown timers - `SlideIndicator` - Carousel indicators ### Interactive Components - `FAB` - Floating Action Button - `IconButton` - Icon-only buttons - `SelectableItem` - Selectable list items - `Collapsible` - Expandable content - `SegmentedControl` - Segmented selection - `ItemCounter` - Quantity counters - `Thumb` - Thumbnail components ### Utility Components - `InputContainer`, `InputWrapper` - Input wrappers - `SheetHeader` - Sheet headers - `StickyHeader` - Sticky positioning - `AutoActionButton` - Smart action buttons - `MessageBubble` - Chat message bubbles - `Compound` - Compound component patterns ## Design Tokens ### Color System Bonyan uses a semantic color system with light/dark theme support: ```tsx // Semantic Colors primary: { primary, onPrimary, primaryContainer, primaryOnContainer } secondary: { secondary, onSecondary, secondaryContainer, secondaryOnContainer } success: { success, onSuccess, successContainer, successOnContainer } error: { error, onError, errorContainer, errorOnContainer } warning: { warning, onWarning, warningContainer, warningOnContainer } promotion: { promotion, onPromotion, promotionContainer, promotionOnContainer } // Background & Surface background: { backgroundBase, backgroundSoft } surface: { surfaceBase, surfaceSoft, surfaceDim } // Emphasis Levels onBackground: { highEmphasis, mediumEmphasis, disable } onSurface: { highEmphasis, mediumEmphasis, disable } // Surface Alpha (transparent overlays) surfaceAlpha: { primary: { highEmphasis, mediumEmphasis, lowEmphasis }, secondary: { highEmphasis, mediumEmphasis, lowEmphasis }, // ... other colors } // Outlines outline: { highEmphasis, mediumEmphasis, lowEmphasis } ``` ### Color Usage ```tsx import styled from "@bonyan/ui"; const StyledButton = styled.button` background: ${({ theme }) => theme.colors.primary.primary}; color: ${({ theme }) => theme.colors.primary.onPrimary}; border: 1px solid ${({ theme }) => theme.colors.outline.mediumEmphasis}; `; ``` ### Spacing System ```tsx const spacing = { none: "0px", // 0 xxs: "2px", // 2px xs: "4px", // 4px ssm: "6px", // 6px sm: "8px", // 8px md: "12px", // 12px lg: "16px", // 16px xl: "20px", // 20px "2xl": "24px", // 24px "3xl": "32px", // 32px "4xl": "40px", // 40px "5xl": "48px", // 48px "6xl": "64px" // 64px } ``` ### Border Radius System ```tsx const rounding = { none: "0px", // 0 xs: "2px", // 2px sm: "4px", // 4px md: "6px", // 6px lg: "8px", // 8px xl: "12px", // 12px "2xl": "16px", // 16px "3xl": "20px", // 20px full: "999px" // Fully rounded } ``` ### Typography System ```tsx // Font Sizes & Line Heights const typography = { display: { small: { fontSize: "36px", lineHeight: "54px" }, medium: { fontSize: "45px", lineHeight: "68px" }, large: { fontSize: "57px", lineHeight: "88px" } }, headline: { small: { fontSize: "24px", lineHeight: "36px" }, medium: { fontSize: "28px", lineHeight: "42px" }, large: { fontSize: "32px", lineHeight: "48px" } }, title: { tiny: { fontSize: "14px", lineHeight: "24px" }, small: { fontSize: "16px", lineHeight: "28px" }, medium: { fontSize: "18px", lineHeight: "30px" }, large: { fontSize: "20px", lineHeight: "32px" } }, label: { tiny: { fontSize: "11px", lineHeight: "16px" }, small: { fontSize: "12px", lineHeight: "20px" }, medium: { fontSize: "14px", lineHeight: "24px" }, large: { fontSize: "16px", lineHeight: "28px" }, xlarge: { fontSize: "20px", lineHeight: "30px" } }, body: { tiny: { fontSize: "12px", lineHeight: "20px" }, small: { fontSize: "14px", lineHeight: "24px" }, medium: { fontSize: "16px", lineHeight: "28px" }, large: { fontSize: "18px", lineHeight: "30px" } } } // Font Weights const fontWeight = { light: 300, regular: 400, demibold: 600, bold: 700 } ``` ## Theme & Styling ### Using Design Tokens ```tsx import { spacing, rounding, shadow, colors } from "@bonyan/ui"; // Direct token usage const spacing_lg = spacing.lg; // "16px" const border_radius = rounding.md; // "6px" // In styled components const Card = styled.div` padding: ${spacing.lg}; border-radius: ${rounding.md}; box-shadow: ${shadow.sm}; background: ${({ theme }) => theme.colors.surface.surfaceBase}; `; ``` ### Custom Styling with styled ```tsx import styled, { Flex, Button } from "@bonyan/ui"; // Custom component export const CustomCard = styled.div` background: ${({ theme }) => theme.colors.surface.surfaceBase}; border: 1px solid ${({ theme }) => theme.colors.outline.lowEmphasis}; border-radius: ${({ theme }) => theme.tokens.rounding.lg}; padding: ${({ theme }) => theme.tokens.spacing.lg}; `; // Extending existing components export const PrimaryFlex = styled(Flex)` background: ${({ theme }) => theme.colors.primary.primaryContainer}; color: ${({ theme }) => theme.colors.primary.primaryOnContainer}; `; export const LargeButton = styled(Button)` padding: ${({ theme }) => theme.tokens.spacing.xl} ${({ theme }) => theme.tokens.spacing["2xl"]}; font-size: 18px; `; ``` ### Theme Switching ```tsx import { defaultTheme, darkTheme, DesignSystemProvider } from "@bonyan/ui"; import { useState } from "react"; function App() { const [isDark, setIsDark] = useState(false); return ( ); } ``` ### Responsive Design ```tsx import { useResponsive } from "@bonyan/ui"; function ResponsiveComponent() { const { isMobile, isTablet, isDesktop } = useResponsive(); return ( Responsive content ); } ``` ## Usage Patterns ### Form Layout ```tsx import { Flex, TextInput, Button, CheckBox, Validation } from "@bonyan/ui"; function LoginForm() { return ( ); } ``` ### Data Display ```tsx import { Flex, Text, Badge, Price, Rate, Button } from "@bonyan/ui"; function ProductCard() { return ( Product Name In Stock Product description goes here ); } ``` ### Navigation Layout ```tsx import { TopAppBar, BottomNavigation, BottomNavigationItem, IconButton, Text } from "@bonyan/ui"; function AppLayout({ children }) { return ( App Title {children} ); } ``` ## Best Practices 1. **Use Semantic Colors**: Prefer semantic color tokens over specific color values 2. **Responsive Design**: Use responsive utilities and breakpoints 3. **Typography Scale**: Stick to the defined typography scale 4. **Spacing Consistency**: Use spacing tokens for consistent layouts 5. **Component Composition**: Combine simple components to build complex UIs 6. **Theme Integration**: Always wrap your app with DesignSystemProvider 7. **TypeScript**: Leverage TypeScript for better development experience 8. **Performance**: Use component lazy loading for better performance ## Advanced Usage ### Custom Theme Creation ```tsx import { createTheme, DesignSystemProvider } from "@bonyan/ui"; const customTheme = createTheme({ colors: { primary: { primary: "#6366f1", onPrimary: "#ffffff", primaryContainer: "#e0e7ff", primaryOnContainer: "#312e81" } // ... other color overrides } }); function App() { return ( ); } ``` ### Component Variants ```tsx // Creating custom button variants const IconOnlyButton = styled(Button)` width: 40px; height: 40px; padding: 0; border-radius: 50%; `; const GlassButton = styled(Button)` background: ${({ theme }) => theme.colors.surface.surfaceAlpha.primary.lowEmphasis}; backdrop-filter: blur(10px); border: 1px solid ${({ theme }) => theme.colors.outline.lowEmphasis}; `; ``` --- # Component Documentation ## ActionBar Component **Version**: 0.1.10 **Props Count**: 24 **Description**: ActionBar: Wraps content in a ButtonGroup, managing action-oriented buttons. **Documentation Source**: Generated from TypeScript + AI # ActionBar ActionBar is a component that wraps content in a ButtonGroup, managing action-oriented buttons. It provides a flexible way to display multiple actions in a compact or spacious layout with optional dividers and safe area handling. ## Overview ActionBar is a container for action buttons that supports various layouts, dividers, and safe area handling. It uses ButtonGroup under the hood and exposes similar props for customization. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `direction` | direction option | Type: "compact", "spacious", "compact"... | | `disableToastAware` | Boolean flag for disableToastAware | Type: true | false | | `divider` | Boolean flag for divider | Type: true | false | | `id` | The unique identifier for the component | Type: string | | `safeArea` | Boolean flag for safeArea | Type: true | false | ## Examples ### Basic Examples #### Basic ActionBar A simple ActionBar with two action buttons using default props. ```tsx export const BasicActionBar = () => { const handleAction = (action: string) => { console.log(`Action triggered: ${action}`); }; return ( ); }; ``` #### ActionBar with Divider Demonstrates ActionBar with a divider between action buttons. ```tsx export const ActionBarWithDivider = () => { const handleAction = (action: string) => { console.log(`Action triggered: ${action}`); }; return ( ); }; ``` ### Variant Examples #### Compact ActionBar ActionBar using compact direction for smaller layout. ```tsx export const CompactActionBar = () => { const handleAction = (action: string) => { console.log(`Action triggered: ${action}`); }; return ( ); }; ``` ### Advanced Examples #### Safe Area ActionBar ActionBar with safe area handling for better layout positioning. ```tsx export const SafeAreaActionBar = () => { const handleAction = (action: string) => { console.log(`Action triggered: ${action}`); }; return ( ); }; ``` #### Advanced ActionBar with Spacing Demonstrates ActionBar with custom spacing and multiple actions. ```tsx export const AdvancedActionBar = () => { const handleAction = (action: string) => { console.log(`Action triggered: ${action}`); }; return ( ); }; ``` ### Styling Examples #### Styling ActionBar Customizing ActionBar with styled-components and additional styling props. ```tsx const StyledActionBar = styled(ActionBar)` background-color: ${props => props.theme.colors.neutral[0]}; border: 1px solid ${props => props.theme.colors.neutral[200]}; border-radius: 8px; padding: 8px; `; export const StyledActionBarExample = () => { const handleAction = (action: string) => { console.log(`Action triggered: ${action}`); }; return ( ); }; ``` ## Variants ### Direction Variants ActionBar supports different layout directions for buttons. **Configuration:** ```tsx { "direction": "compact" } ``` **Example:** ```tsx CompactActionBar ``` ### Divider Variant ActionBar can show dividers between action buttons. **Configuration:** ```tsx { "divider": true } ``` **Example:** ```tsx ActionBarWithDivider ``` ## Usage ### Basic Usage Wrap buttons in ActionBar for a clean, action-oriented layout. ### Advanced Usage Use direction and spacing props to customize the layout according to your needs. ### Common Patterns - Using ActionBar for primary actions in a form - Placing ActionBar at the bottom of a screen - Combining with other components for complex layouts ## Styling ### Theme Integration ActionBar uses theme properties for colors, spacing, and typography. It supports custom styling through styled-components and direct style props. ### Customization You can customize ActionBar using styled-components or by passing direct style props. The component respects theme tokens for consistent styling. ### Available Tokens - `colors.neutral` - `spacing.compact` - `spacing.spacious` - `borderRadius` ### Styling Examples ```tsx StyledActionBarExample ``` ```tsx SafeAreaActionBar ``` ```tsx AdvancedActionBar ``` ## Best Practices - Use ActionBar for action-oriented buttons in a single line. - Prefer compact direction for mobile interfaces and spacious for desktop. - Always ensure proper spacing using margin and padding props. - Use safeArea prop when positioning near screen edges. ## Accessibility - ActionBar ensures proper button spacing for touch targets. - Supports keyboard navigation through buttons. - Maintains proper color contrast for better readability. - Uses appropriate ARIA roles for screen reader compatibility. ## Performance Considerations Tips for optimal ActionBar performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the ActionBar component: ```tsx test('renders actionbar component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## AspectRatio Component **Version**: 0.1.10 **Props Count**: 387 **Description**: Enforces aspect ratio for content. Allows specifying a ratio and rendering with custom HTML elements. **Documentation Source**: Generated from TypeScript + AI # AspectRatio A component that enforces a specific aspect ratio for its content, useful for images, videos, and other media. ## Overview The AspectRatio component allows you to maintain a consistent aspect ratio for your content while ensuring it scales appropriately within different layouts. It supports various content types, including images, videos, and text, and provides flexible styling options through Bonyan's spacing system. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `as` | as component or element | Type: ElementType | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | | `ratio` | String value for ratio | Type: string | Required | ## Examples ### Basic Examples #### Basic Image Aspect Ratio A basic example using the AspectRatio component to maintain a 16:9 aspect ratio for an image. ```tsx const sampleImage = 'https://unsplash.com/photos/1527pjeb6jg/download?force=true&w=640'; export const BasicImageAspectRatio = () => ( Sample image with 16:9 aspect ratio

); ``` #### Background Image Aspect Ratio Using the AspectRatio component with a background image while maintaining the 16:9 aspect ratio. ```tsx const sampleImage = 'https://unsplash.com/photos/1527pjeb6jg/download?force=true&w=640'; export const BackgroundImageAspectRatio = () => ( ); ``` ### Advanced Examples #### Video Aspect Ratio Maintaining a 16:9 aspect ratio for a video element. ```tsx export const VideoAspectRatio = () => (

); ``` #### Text Content Aspect Ratio Using the AspectRatio component to create a container with text content while maintaining a specific aspect ratio. ```tsx export const TextAspectRatio = () => (

This is a text content within a 4:3 aspect ratio container.

); ``` ### Styling Examples #### Custom Styled Aspect Ratio Applying custom styles to the AspectRatio component using styled-components. ```tsx const StyledAspectRatio = styled(AspectRatio)` border: 2px solid #333; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); `; export const CustomStyledAspectRatio = () => ( Custom styled aspect ratio

); ``` ## Usage ### Basic Usage The AspectRatio component is used to maintain a specific aspect ratio for its content. Simply wrap your content (like images, videos, or text) within the component and specify the desired ratio using the ratio prop. ### Advanced Usage For more complex use cases, you can combine the AspectRatio component with other layout components or apply custom styles using styled-components. You can also use it in responsive layouts by adjusting the ratio dynamically based on screen size. ### Common Patterns - Image galleries with consistent aspect ratios - Video players with specific video ratios - Card layouts with text and images - Responsive banners and hero sections ## Styling ### Theme Integration The AspectRatio component integrates with Bonyan's theme system through spacing values. You can use the theme's spacing scale to apply consistent margins and padding. ### Customization The component can be customized using styled-components. You can extend the base styles and add custom CSS properties as needed. ### Available Tokens - `spacing` - `colors` - `typography` - `border` - `shadow` ### Styling Examples ```tsx Adding a border and border-radius ``` ```tsx Applying custom background colors ``` ```tsx Adjusting spacing and padding ``` ```tsx Adding box shadows for depth ``` ## Best Practices - Always provide meaningful alt text for images within AspectRatio - Use appropriate ratios based on your content requirements - Ensure content is responsive within the aspect ratio container - Avoid using fixed heights or widths that could disrupt the aspect ratio - Test different screen sizes to ensure consistent appearance ## Accessibility - Provide alt text for all images within the AspectRatio component - Ensure that interactive elements within the component are keyboard-navigable - Use appropriate ARIA roles and attributes when necessary - Ensure sufficient color contrast for text content within the component - Test screen reader compatibility for all interactive elements ## Performance Considerations Tips for optimal AspectRatio performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the AspectRatio component: ```tsx test('renders aspectratio component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## AutoActionButton Component **Version**: 0.1.10 **Props Count**: 393 **Description**: AutoActionButton is a button in Bonyan Design System. It auto-triggers an action (onClick) after a specified delay (seconds). **Documentation Source**: Generated from TypeScript + AI # AutoActionButton A button that auto-triggers an action after a specified delay, with support for icons, loading states, and various styling options. ## Overview AutoActionButton is a versatile button component that combines a progress indicator with automatic action triggering. It supports multiple sizes, variants, colors, and includes features like loading states and icon integration. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `color` | The color variant of the component | Type: "primary", "secondary", "neutral"... | | `dataTest` | Data attribute for testing purposes | Type: string | | `disabled` | Whether the component is disabled | Type: true | false | | `elevated` | Whether the component has elevated styling | Type: true | false | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `id` | The unique identifier for the component | Type: string | | `inline` | Whether the component displays inline | Type: true | false | | `loading` | Whether the component is in a loading state | Type: true | false | | `onClickWhenDisabled` | Click event handler when component is disabled | Type: click handler | | `postIcon` | Icon displayed after the content | Type: React element | | `preIcon` | Icon displayed before the content | Type: React element | | `seconds` | Numeric value for seconds | Type: number | Required | | `shape` | The shape variant of the component | Type: string | | `size` | The size variant of the component | Type: "small", "medium", "large"... | | `title` | The title attribute for the component | Type: string | | `type` | The type attribute for the component | Type: "button", "submit", "reset" | | `variant` | The visual variant of the component | Type: "solid", "tonal", "plain"... | ## Examples ### Basic Examples #### Basic AutoActionButton A simple example of an AutoActionButton with default settings. The button will trigger an alert after 6 seconds. ```tsx export const BasicAutoActionButton = () => { const handleClick = () => { alert('Action completed!'); }; return ( Click me ); }; ``` #### Disabled AutoActionButton Shows how to disable the AutoActionButton. The button is non-interactive and shows a disabled state. ```tsx export const DisabledAutoActionButton = () => { return ( Disabled button ); }; ``` ### Variant Examples #### Size and Color Variants Demonstrates different size and color variants of the AutoActionButton. The example shows small, medium, and large sizes with primary, secondary, and error colors. ```tsx export const SizeAndColorVariants = () => { const handleClick = () => { alert('Button clicked!'); }; return (

Small primary Medium secondary Large error

); }; ``` ### Advanced Examples #### AutoActionButton with Icons Example showing the use of pre and post icons with the AutoActionButton. The button includes a check icon before and a send icon after the text. ```tsx export const AutoActionButtonWithIcons = () => { const handleClick = () => { alert('Action completed!'); }; return ( } postIcon={} > Submit with icons ); }; ``` #### Loading State Example Demonstrates the loading state of the AutoActionButton. The button shows a loading indicator and disables interaction during the process. ```tsx export const LoadingAutoActionButton = () => { const [isLoading, setIsLoading] = React.useState(false); const [isCompleted, setIsCompleted] = React.useState(false); const handleClick = () => { setIsLoading(true); setTimeout(() => { setIsLoading(false); setIsCompleted(true); }, 3000); }; return ( {isCompleted ? 'Completed!' : 'Click to start'} ); }; ``` ### Styling Examples #### Advanced Customization Shows an advanced example with custom styling, icons, and different variants. The button uses a tonal variant with custom margins and padding. ```tsx export const AdvancedCustomization = () => { const handleClick = () => { alert('Advanced button clicked!'); }; return ( } postIcon={} elevated > Advanced button ); }; ``` ## Variants ### Size Variants The AutoActionButton comes in three sizes: small, medium, and large. Use the size prop to adjust the button dimensions. **Configuration:** ```tsx { "size": "small | medium | large" } ``` **Example:** ```tsx SizeAndColorVariants ``` ### Color Variants Available colors are primary, secondary, neutral, and error. Use the color prop to change the button's color scheme. **Configuration:** ```tsx { "color": "primary | secondary | neutral | error" } ``` **Example:** ```tsx SizeAndColorVariants ``` ### Variant Types The button supports solid, tonal, and plain variants. Use the variant prop to change the visual style. **Configuration:** ```tsx { "variant": "solid | tonal | plain" } ``` **Example:** ```tsx AdvancedCustomization ``` ## Usage ### Basic Usage Import the component and use it with the required props. The minimum required prop is seconds. ### Advanced Usage Combine various props like size, variant, color, and icons to create custom button styles. Implement loading and disabled states for better user feedback. ### Common Patterns - Use as a submit button with form validation. - Implement loading states for asynchronous actions. - Combine with icons for better visual hierarchy. ## Styling ### Theme Integration The AutoActionButton uses the Bonyan Design System theme for consistent styling. It supports theme colors, spacing, and typography. ### Customization You can customize the button using styled-components. Here's an example: const CustomButton = styled(AutoActionButton)` background-color: ${props => props.theme.colors.customColor}; margin: ${props => props.theme.spacing.customSpacing}; `; ### Available Tokens - `colors.primary` - `colors.secondary` - `colors.neutral` - `colors.error` - `spacing.small` - `spacing.medium` - `spacing.large` ### Styling Examples ```tsx const CustomButton = styled(AutoActionButton)` background-color: ${props => props.theme.colors.customColor}; margin: ${props => props.theme.spacing.customSpacing}; `; ``` ## Best Practices - Always provide meaningful text content for accessibility. - Use appropriate color contrasts for different states. - Implement proper focus management for keyboard navigation. - Avoid using too many variants in a single form to maintain consistency. ## Accessibility - The button includes proper ARIA roles and attributes. - It supports keyboard navigation with space and enter keys. - High contrast ratios between text and background for better readability. - Focus states are clearly visible and follow the theme's focus styles. ## Events and Handlers The AutoActionButton component supports various event handlers for user interactions: - `onClickWhenDisabled`: Event handler ## Async Operations The AutoActionButton component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Performance Considerations Tips for optimal AutoActionButton performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the AutoActionButton component: ```tsx test('renders autoactionbutton component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Badge Component **Version**: 0.1.10 **Props Count**: 387 **Documentation Source**: Generated from TypeScript + AI # Badge The Badge component displays a small, styled indicator. It shows a content (often a number) or a status with customizable color and size, part of Bonyan. ## Overview A versatile component for displaying notifications, status indicators, or small pieces of information. Supports different variants, colors, and content types. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `color` | The color variant of the component | Type: string | | `content` | content property | Type: string | number | | `dataTest` | Data attribute for testing purposes | Type: string | | `variant` | The visual variant of the component | Type: "hint", "notify" | ## Examples ### Basic Examples #### Basic Dot Badge A simple dot badge without any content, typically used as a notification indicator. ```tsx export const BasicDotBadge = () => { return ; }; ``` #### Text Badge Display text content inside the badge. Useful for showing status labels like 'New' or 'Updated'. ```tsx export const TextBadge = () => { return ; }; ``` #### Digit Badge Show a single digit number in the badge. Ideal for notifications counts. ```tsx export const DigitBadge = () => { return ; }; ``` #### Multi-Digit Badge Display multiple digits or a combination of digits and symbols in the badge. ```tsx export const MultiDigitBadge = () => { return ; }; ``` ### Variant Examples #### Hint Variant Badge Use the hint variant for a more subtle badge appearance. ```tsx export const HintVariantBadge = () => { return ; }; ``` ### Styling Examples #### Custom Color Badge Customize the badge color using the color prop. This example uses a custom color '#4CAF50'. ```tsx export const CustomColorBadge = () => { return ; }; ``` ## Variants ### notify The default variant, typically used for notifications. It has a more prominent appearance with higher contrast. **Configuration:** ```tsx { "variant": "notify" } ``` **Example:** ```tsx export const NotifyVariantExample = () => { return ; }; ``` ### hint A more subtle variant, suitable for less critical information or status indicators. **Configuration:** ```tsx { "variant": "hint" } ``` **Example:** ```tsx export const HintVariantExample = () => { return ; }; ``` ## Usage ### Basic Usage Import the Badge component and use it with optional props for variant, content, and color. The component can be used inline with other elements. ### Advanced Usage Combine the Badge component with other UI elements like Avatar or Button to create complex interfaces. Customize its appearance using styled-components or custom CSS classes. ### Common Patterns - Notification indicators - Status labels - Activity indicators - Count displays ## Styling ### Theme Integration The Badge component uses Bonyan's theme system for consistent styling. It supports theme colors and spacing tokens. The background and text colors can be customized using the theme's color palette. ### Customization You can customize the Badge component using styled-components. Here's an example of customizing the background color and padding: const CustomBadge = styled(Badge)` background-color: #4CAF50; padding: 0 8px; `; export const CustomizedBadge = () => { return ; }; ### Available Tokens - `colors.error.error` - `colors.error.onError` - `colors.onSurface.mediumEmphasis` - `colors.surface.surfaceBase` ### Styling Examples ```tsx export const CustomColorBadge = () => { return ; }; ``` ```tsx const SmallBadge = styled(Badge)` min-width: 20px; height: 20px; font-size: 12px; `; export const SizedBadge = () => { return ; }; ``` ## Best Practices - Use the Badge component for notifications, status indicators, or small information displays. - Prefer short text or numbers as content for better readability. - Use appropriate variants based on the context: 'notify' for important notifications and 'hint' for subtle status indicators. - Ensure proper color contrast for accessibility, especially when customizing colors. ## Accessibility - The Badge component uses ARIA attributes to ensure screen reader compatibility. - The component supports keyboard navigation and focus management. - Ensure that custom colors maintain sufficient contrast for readability. - Use meaningful content that provides context to users of assistive technologies. ## Performance Considerations Tips for optimal Badge performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Badge component: ```tsx test('renders badge component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## BankIcon Component **Version**: 0.1.10 **Props Count**: 376 **Description**: Displays a bank icon based on a name or card number. Uses Bonyan Design System's `Img` component for rendering. **Documentation Source**: Generated from TypeScript + AI # BankIcon A React component that displays bank icons based on the provided name or card number. It utilizes the Bonyan Design System's Img component for rendering. ## Overview The BankIcon component is designed to display bank icons dynamically. It can fetch the appropriate icon using either a bank name or a card number. The component supports various customization options such as size, fallback behaviors, and loading states. ### Props | Prop | Description | |------|-------------| | `as` | You can pass a Nextjs Image component in this prop so the render component will change: | Type: ElementType | | `baseUrl` | String value for baseUrl | Type: string | | `cardNumber` | String value for cardNumber | Type: string | | `disabledFallback` | Disabled state | Type: true | false | | `disabledPlaceholder` | Disabled state | Type: true | false | | `fallbackDirection` | fallbackDirection option | Type: "horizontal", "vertical" | | `fallbackSize` | Size configuration | Type: "base", "narrow", "narrower"... | | `fallbackVariant` | Visual variant | Type: "logotype", "sign" | | `fill` | Boolean flag for fill | Type: true | false | | `iconFallback` | Icon configuration | Type: true | false | | `loader` | loader property | Type: (url: { src: string; quality: number; width: number; }) => string | | `loading` | Whether the component is in a loading state | Type: "lazy", "eager" | | `name` | The name attribute for form elements | Type: "ansar", "ayandeh", "bank_markazi"... | | `onLoadCallback` | onLoadCallback property | Type: () => void | | `placeholderColor` | Color configuration | Type: string | | `priority` | Boolean flag for priority | Type: true | false | | `quality` | Numeric value for quality | Type: number | | `size` | The size variant of the component | Type: string | number | Required | | `sizes` | Size configuration | Type: string | | `wrapperStyle` | wrapperStyle property | Type: CSSProperties | ## Examples ### Basic Examples #### Basic Bank Icon A simple example of displaying a bank icon using the name prop. ```tsx export const BasicBankIcon = () => { return ( ); }; ``` #### Bank Icon with Card Number Displays a bank icon based on a provided card number. ```tsx export const BankIconWithCardNumber = () => { return ( ); }; ``` ### Advanced Examples #### Loading State Example Demonstrates the loading state of the BankIcon component. ```tsx export const LoadingBankIcon = () => { return ( ); }; ``` #### Fallback Icon Example Demonstrates the fallback behavior when the main icon fails to load. ```tsx export const FallbackBankIcon = () => { return ( ); }; ``` ### Styling Examples #### Custom Size Bank Icon Shows how to display the bank icon in different sizes. ```tsx export const CustomSizeBankIcon = () => { return (

); }; ``` #### Custom Styled Bank Icon Shows how to customize the appearance of the bank icon using wrapper styles. ```tsx export const CustomStyledBankIcon = () => { return ( ); }; ``` ## Variants ### small A small-sized bank icon. **Configuration:** ```tsx { "size": 16 } ``` **Example:** ```tsx export const SmallBankIcon = () => ( ); ``` ### medium A medium-sized bank icon. **Configuration:** ```tsx { "size": 24 } ``` **Example:** ```tsx export const MediumBankIcon = () => ( ); ``` ### large A large-sized bank icon. **Configuration:** ```tsx { "size": 32 } ``` **Example:** ```tsx export const LargeBankIcon = () => ( ); ``` ## Usage ### Basic Usage Import the BankIcon component and use it by providing either the name or cardNumber prop along with the size prop. ### Advanced Usage Customize the icon's appearance using wrapperStyle, implement loading states, and handle fallback behaviors for robust icon display. ### Common Patterns - Using the name prop for direct bank icon selection. - Utilizing cardNumber to dynamically determine the bank icon. - Implementing fallback icons for error states. - Customizing the icon's styling to match your application's theme. ## Styling ### Theme Integration The BankIcon component uses the Bonyan Design System's theme for consistent styling. The theme provides default values for sizes, colors, and other visual properties. ### Customization You can customize the BankIcon component using styled-components or by passing custom styles through the wrapperStyle prop. This allows you to adjust the appearance to match your application's design requirements. ### Available Tokens - `size` - `color` - `backgroundColor` - `padding` - `borderRadius` ### Styling Examples ```tsx Custom size: ``` ```tsx Custom wrapper styles: ``` ## Best Practices - Always specify the size prop to ensure consistent icon sizing across your application. - Use the name prop for explicit bank selection when possible, as it provides better performance. - Leverage the loading prop to optimize image loading behavior based on your use case. - Implement proper error handling using fallback props to ensure a good user experience when icons fail to load. ## Accessibility - The BankIcon component includes proper ARIA attributes for accessibility. - Ensure that the icon has appropriate alt text for screen readers. - Use meaningful ARIA labels to describe the icon's purpose when necessary. ## Events and Handlers The BankIcon component supports various event handlers for user interactions: - `onLoadCallback`: Event handler ## Async Operations The BankIcon component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Performance Considerations Tips for optimal BankIcon performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the BankIcon component: ```tsx test('renders bankicon component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Banner Component **Version**: 0.1.10 **Props Count**: 30 **Description**: The Banner component displays important messages with icons and styles, providing feedback or alerts in Bonyan. **Documentation Source**: Generated from TypeScript + AI # Banner The Banner component displays important messages with icons and styles, providing feedback or alerts in Bonyan. ## Overview A versatile component for showing different types of messages with optional actions, icons, and customizable styles. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `actions` | actions property | Type: ReactNode | | `className` | String value for className | Type: string | | `dataTest` | Data attribute for testing purposes | Type: string | | `description` | description component or element | Type: React element | | `dismissButton` | Boolean flag for dismissButton | Type: true | false | | `icon` | Icon to display | Type: React element | | `id` | The unique identifier for the component | Type: string | | `onDismissClick` | Click event handler | Type: () => void | | `rightSlot` | rightSlot property | Type: ReactNode | | `style` | style property | Type: CSSProperties | | `title` | The title attribute for the component | Type: string | | `variant` | The visual variant of the component | Type: "neutral", "informative", "positive"... | Required | ## Examples ### Basic Examples #### Basic Banner A simple banner with title and description. ```tsx export const BasicBanner = () => { return ( ); }; ``` ### Variant Examples #### Informative Banner A banner with an informative variant and an icon. ```tsx export const InformativeBanner = () => { return ( ); }; ``` ### Advanced Examples #### Banner with Action A banner with an action button and right slot content. ```tsx export const BannerWithAction = () => { return ( Update Now } rightSlot={ Update icon

} /> ); }; ``` #### Custom Icon Banner A banner with a custom icon in the right slot. ```tsx export const CustomIconBanner = () => { return ( } /> ); }; ``` ### Styling Examples #### Styling Banner Customizing the banner's appearance using styled-components. ```tsx const CustomBanner = styled(Banner)` background-color: #f5f5f5; border-radius: 8px; padding: 16px; margin: 8px; `; export const StyledBanner = () => { return ( ); }; ``` ## Variants ### Neutral Used for general information messages. **Configuration:** ```tsx "{ variant: 'neutral' }" ``` **Example:** ```tsx BasicBanner ``` ### Informative Used for information that needs to stand out but isn't critical. **Configuration:** ```tsx "{ variant: 'informative' }" ``` **Example:** ```tsx InformativeBanner ``` ### Positive Used for success messages or positive feedback. **Configuration:** ```tsx "{ variant: 'positive' }" ``` ### Warning Used for warnings or cautions that need attention. **Configuration:** ```tsx "{ variant: 'warning' }" ``` ### Brand Used for promotional or brand-related messages. **Configuration:** ```tsx "{ variant: 'brand' }" ``` ### Critical Low Used for critical messages with lower priority. **Configuration:** ```tsx "{ variant: 'criticalLow' }" ``` ### Critical High Used for the most critical and urgent messages. **Configuration:** ```tsx "{ variant: 'criticalHigh' }" ``` ## Usage ### Basic Usage Import the Banner component and use it with the required variant prop. Optionally, provide title, description, and other props as needed. ### Advanced Usage For more complex use cases, utilize the rightSlot and actions props to add custom content and buttons. Combine with other components for enhanced functionality. ### Common Patterns - Displaying system messages - Showing update notifications - Highlighting important information - Providing feedback after user actions ## Styling ### Theme Integration The Banner component uses the theme to determine background colors, text colors, and border radius. Different variants map to different theme colors for consistent styling across the application. ### Customization You can customize the Banner component using styled-components. Create a custom styled component by extending the Banner component and adding your own styles. ### Available Tokens - `background-color` - `text-color` - `border-radius` - `padding` - `margin` ### Styling Examples ```tsx const CustomBanner = styled(Banner)` background-color: #f5f5f5; border-radius: 8px; padding: 16px; margin: 8px; `; ``` ## Best Practices - Use clear and concise text for the title and description. - Ensure proper color contrast for accessibility. - Use appropriate variants for different message types. - Avoid overcrowding the banner with too much content. - Consider performance when using images in the right slot. ## Accessibility - The Banner component uses ARIA roles and attributes for screen reader support. - Keyboard navigation is supported for interactive elements like buttons. - High contrast ratios are maintained for text and background colors. - Focus management ensures that interactive elements can be accessed with a keyboard. ## Events and Handlers The Banner component supports various event handlers for user interactions: - `onDismissClick`: Event handler ## Performance Considerations Tips for optimal Banner performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Banner component: ```tsx test('renders banner component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Block Component **Version**: 0.1.10 **Props Count**: 390 **Description**: A foundational, flexible layout component for Bonyan. Controls display (block/inline), width, height, overflow, and spacing. **Documentation Source**: Generated from TypeScript + AI # Block A foundational, flexible layout component for Bonyan. Controls display (block/inline), width, height, overflow, and spacing. ## Overview The Block component is a versatile layout utility that provides comprehensive control over display properties, dimensions, overflow, and spacing. It serves as a building block for creating custom layouts and components. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `inline` | Whether the component displays inline | Type: true | false | | `overflow` | overflow property | Type: Overflow | | `width` | Width configuration | Type: string | ## Examples ### Basic Examples #### Basic Block A simple example demonstrating the default block element with default styling. ```tsx export const BasicBlockExample = () => { return ( This is a basic block element with default styling. ); }; ``` #### Inline Block An example showing the block element in inline mode. ```tsx export const InlineBlockExample = () => { return ( This is an inline block element. ); }; ``` ### Advanced Examples #### Block with Overflow An example showing the block element with overflow control. ```tsx export const BlockWithOverflowExample = () => { return (

); }; ``` #### Responsive Block Layout A responsive layout example using multiple Block components with different widths. ```tsx export const ResponsiveBlockLayoutExample = () => { return ( Full-width block Half-width block One-third width block ); }; ``` ### Styling Examples #### Block with Spacing Demonstrates various spacing properties applied to the block element. ```tsx export const BlockWithSpacingExample = () => { return ( This block has margin, padding, and specific top/bottom margins applied. ); }; ``` ## Variants ### Flex Layout Using Block as a flex container. **Configuration:** ```tsx { "display": "flex", "flexDirection": "row", "justifyContent": "spaceBetween", "alignItems": "center" } ``` **Example:** ```tsx export const FlexBlockExample = () => (

Item 1

Item 2

Item 3

); ``` ### Grid Layout Using Block as a grid container. **Configuration:** ```tsx { "display": "grid", "gridTemplateColumns": "repeat(3, 1fr)", "gap": "medium" } ``` **Example:** ```tsx export const GridBlockExample = () => (

Item 1

Item 2

Item 3

); ``` ## Usage ### Basic Usage The Block component is used as a basic layout element. It can be used as a simple div replacement with additional styling and layout controls. ### Advanced Usage For more complex layouts, Block can be combined with other layout utilities or styled-components to create custom components. ### Common Patterns - Container with consistent spacing - Responsive layouts - Overflow handling - Custom styled components ## Styling ### Theme Integration The Block component integrates with Bonyan's theme system through spacing and color props. It uses the theme's spacing scale for margin and padding values. ### Customization The Block component can be customized using styled-components. You can extend its styles by creating a new styled component: ### Available Tokens - `spacing` - `colors` - `typography` ### Styling Examples ```tsx const CustomBlock = styled(Block)` background-color: ${props => props.theme.colors.neutral[100]}; border-radius: ${props => props.theme.radii.medium}; `; export const CustomBlockExample = () => ( Custom styled block ); ``` ## Best Practices - Always use meaningful values for width and height props to ensure responsiveness. - Leverage the spacing props (m, p, mx, etc.) for consistent spacing across components. - Avoid using Block for typography-heavy content - consider using Typography components instead. - Use the overflow prop judiciously to handle content overflow scenarios. ## Accessibility - The Block component inherits ARIA attributes through the dataTest prop. - Ensure proper color contrast when customizing background and text colors. - Use appropriate ARIA roles when Block is used as a container for interactive elements. ## Performance Considerations Tips for optimal Block performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Block component: ```tsx test('renders block component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## BottomNavigation Component **Version**: Unknown **Props Count**: 0 **Documentation Source**: Generated from TypeScript + AI # BottomNavigation A responsive bottom navigation component that provides easy access to app sections. ## Overview The BottomNavigation component is used for displaying navigation items at the bottom of a screen. It supports multiple items, icons, labels, and badges, making it suitable for various navigation patterns. ## Examples ### Basic Examples #### Basic Two Items A simple bottom navigation with two items, labels, and icons. ```tsx export const BasicTwoItems = () => ( } iconFilled={} label="خانه" selected={true} /> } iconFilled={} label="پروفایل" selected={false} /> ); ``` #### Three Items with Badges Bottom navigation with three items, including badges with different content types. ```tsx export const ThreeItemsWithBadges = () => ( } iconFilled={} label="خانه" selected={true} badgeContent="جدید" /> } iconFilled={} label="پروفایل" selected={false} badgeContent={2} /> } iconFilled={} label="عنوان" selected={false} badgeContent="" /> ); ``` #### Icon-Only Navigation Bottom navigation with items showing only icons. ```tsx export const IconOnlyNavigation = () => ( } iconFilled={} selected={true} /> } iconFilled={} selected={false} /> ); ``` ### Styling Examples #### Full Width Navigation Bottom navigation that spans the full width of the screen. ```tsx export const FullWidthNavigation = () => ( } iconFilled={} label="خانه" selected={true} /> } iconFilled={} label="پروفایل" selected={false} /> ); ``` #### Custom Styled Navigation Bottom navigation with custom styling applied using styled-components. ```tsx const CustomBottomNavigation = styled(BottomNavigation)` background-color: ${props => props.theme.colors.surface.secondary}; padding: ${props => props.theme.spacing.md}; `; export const CustomStyledNavigation = () => ( } iconFilled={} label="خانه" selected={true} /> } iconFilled={} label="پروفایل" selected={false} /> ); ``` ## Usage ### Basic Usage Import the BottomNavigation and BottomNavigationItem components, then structure your navigation items within the BottomNavigation container. ### Advanced Usage Customize the appearance using styled-components, handle item selections, and integrate with application state for dynamic behavior. ### Common Patterns - Using icons with labels for better recognition. - Adding badges to indicate notifications or updates. - Implementing full-width navigation for specific layouts. ## Styling ### Theme Integration The BottomNavigation component uses the theme's colors, spacing, and safe area settings. It respects the theme's outline colors for borders and background colors for the container. ### Customization You can customize the BottomNavigation component using styled-components. You can modify properties like background color, padding, and border styles by extending the component's styles. ### Available Tokens - `colors.surface.primary` - `colors.surface.secondary` - `colors.outline.mediumEmphasis` - `spacing.sm` - `spacing.md` - `spacing.lg` ### Styling Examples ```tsx Customizing background color: const CustomBottomNavigation = styled(BottomNavigation)` background-color: ${props => props.theme.colors.surface.secondary}; `; ``` ## Best Practices - Always provide meaningful labels for icons to ensure accessibility. - Use badges sparingly and only for important notifications. - Avoid using too many items (ideally 2-5) to maintain usability. - Ensure proper color contrast for accessibility. ## Accessibility - The component uses ARIA roles to ensure screen reader compatibility. - Items are keyboard navigable and support focus management. - Proper color contrast is maintained between background and text. - Labels are provided for all icons to ensure accessibility. ## Performance Considerations Tips for optimal BottomNavigation performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the BottomNavigation component: ```tsx test('renders bottomnavigation component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## BottomNavigationItem Component **Version**: 0.1.10 **Props Count**: 8 **Description**: This React component renders a single item within a bottom navigation bar. It includes styling, badge support, and uses Bonyan's theming. **Documentation Source**: Generated from TypeScript + AI # BottomNavigationItem A React component for creating navigation items in a bottom navigation bar. Supports icons, labels, badges, and selection states. ## Overview The BottomNavigationItem component is designed to be used within a bottom navigation context. It provides a flexible way to display navigation items with icons, labels, and badges. The component supports selection states, custom theming, and accessibility features. ### Props | Prop | Description | |------|-------------| | `badgeContent` | badgeContent property | Type: string | number | boolean | | `icon` | Icon to display | Type: React element | Required | | `iconFilled` | Icon configuration | Type: React element | Required | | `id` | The unique identifier for the component | Type: string | | `label` | The label text for the component | Type: string | | `name` | The name attribute for form elements | Type: string | | `onClick` | Click event handler | Type: () => void | | `selected` | Boolean flag for selected | Type: true | false | ## Examples ### Basic Examples #### Basic Usage A simple example showing three bottom navigation items with icons and labels. ```tsx export const BasicBottomNavigationItem = () => { const [selected, setSelected] = React.useState('home'); const handleItemClick = (name: string) => { setSelected(name); }; return (

handleItemClick('home')} icon={} iconFilled={} label="Home" /> handleItemClick('search')} icon={} iconFilled={} label="Search" /> handleItemClick('profile')} icon={} iconFilled={} label="Profile" />

); }; ``` ### Variant Examples #### Custom Icons and Labels Example demonstrating different icon types and label configurations. ```tsx export const CustomIconsAndLabels = () => { const [selected, setSelected] = React.useState('home'); const handleItemClick = (name: string) => { setSelected(name); }; return (

handleItemClick('home')} icon={} iconFilled={} label="Home" /> handleItemClick('settings')} icon={} iconFilled={} label="Settings" /> handleItemClick('help')} icon={} iconFilled={} label="Help & Support" /> handleItemClick('profile')} icon={} iconFilled={} label="My Profile" />

); }; ``` ### Advanced Examples #### Advanced Usage with Badges Example showing bottom navigation items with badges and dynamic content. ```tsx export const AdvancedBottomNavigationItem = () => { const [selected, setSelected] = React.useState('home'); const [badgeCount, setBadgeCount] = React.useState(3); const handleItemClick = (name: string) => { setSelected(name); }; return (

handleItemClick('home')} icon={} iconFilled={} label="Home" badgeContent={badgeCount} /> handleItemClick('cart')} icon={} iconFilled={} label="Cart" badgeContent="New" /> handleItemClick('profile')} icon={} iconFilled={} label="Profile" />

); }; ``` ### Styling Examples #### Styling Example Example showing how to customize the appearance using styled-components. ```tsx const CustomBottomNavigationItem = styled(BottomNavigationItem)({ '&:hover': { backgroundColor: '#f5f5f5', }, selected: { color: '#ff4081', }, }); export const StyledBottomNavigationItem = () => { const [selected, setSelected] = React.useState('home'); const handleItemClick = (name: string) => { setSelected(name); }; return (

handleItemClick('home')} icon={} iconFilled={} label="Home" /> handleItemClick('search')} icon={} iconFilled={} label="Search" /> handleItemClick('profile')} icon={} iconFilled={} label="Profile" />

); }; ``` ## Usage ### Basic Usage Import the component and use it within a bottom navigation context. Provide required props like icon, iconFilled, and label. Handle selection state and click events appropriately. ### Advanced Usage Implement badges, custom styling, and dynamic content. Use the selected prop to manage the active state and update the UI accordingly. ### Common Patterns - Using the component within a BottomNavigation context - Implementing navigation with icons and labels - Adding badges for notifications or updates - Customizing appearance using styled-components ## Styling ### Theme Integration The BottomNavigationItem component uses Bonyan's theme system for consistent styling. It supports theme properties for colors, typography, and spacing. The component uses the onSurface color tokens for text and icons, and provides a selected state with high emphasis colors. ### Customization To customize the BottomNavigationItem, you can use styled-components to override styles. You can target specific parts of the component using class names or by extending the styled component. ### Available Tokens - `onSurface.highEmphasis` - `onSurface.mediumEmphasis` - `spacing.sm` - `spacing.xxs` ### Styling Examples ```tsx Customizing hover state: const CustomBottomNavigationItem = styled(BottomNavigationItem)({ '&:hover': { backgroundColor: '#f5f5f5', }, }); ``` ```tsx Changing selected color: const CustomBottomNavigationItem = styled(BottomNavigationItem)({ selected: { color: '#ff4081', }, }); ``` ## Best Practices - Always provide an accessible label for the navigation item. - Use meaningful icons that clearly represent the navigation item's purpose. - Implement proper focus and hover states for better user interaction. - Avoid using too many navigation items to maintain a clean interface. ## Accessibility - The component automatically handles ARIA roles and states. - Keyboard navigation is supported through proper focus management. - Screen readers can interpret the label and icon content. - Ensure sufficient color contrast between selected and unselected states. ## Events and Handlers The BottomNavigationItem component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal BottomNavigationItem performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the BottomNavigationItem component: ```tsx test('renders bottomnavigationitem component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## BottomSheet Component **Version**: Unknown **Props Count**: 13 **Documentation Source**: Generated from TypeScript + AI # BottomSheet A flexible bottom sheet component that can display various content, including forms, information, and actions. It supports different states such as loading and error, and can be customized with headers and footers. ## Overview The BottomSheet component is a versatile solution for displaying temporary content in a sheet that slides up from the bottom of the screen. It supports multiple states, including loading and error, and can be customized with headers and footers to provide a rich user experience. ### Props | Prop | Description | |------|-------------| | `className` | String value for className | Type: string | | `errorContent` | String value for errorContent | Type: string | | `fixedSnapPoint` | Boolean flag for fixedSnapPoint | Type: true | false | | `footer` | footer component or element | Type: React element | | `header` | header component or element | Type: React element | | `id` | The unique identifier for the component | Type: string | | `isOpen` | Boolean flag for isOpen | Type: true | false | Required | | `onClose` | onClose property | Type: () => void | Required | | `onOpen` | onOpen property | Type: () => void | | `onRetry` | onRetry property | Type: () => void | | `preventScrollOnBody` | Boolean flag for preventScrollOnBody | Type: true | false | | `state` | state option | Type: "active", "error", "loading" | | `zIndex` | Numeric value for zIndex | Type: number | ## Examples ### Basic Examples #### Basic BottomSheet Usage A simple example demonstrating how to open and close the bottom sheet with basic content. ```tsx export const BasicBottomSheet = () => { const [isOpen, setIsOpen] = useState(false); return (

setIsOpen(false)} >

Basic Content

This is a simple bottom sheet with basic content.

); }; ``` ### Advanced Examples #### BottomSheet with Header and Footer An example showing how to use a header and footer in the bottom sheet, including action buttons. ```tsx export const BottomSheetWithHeaderFooter = () => { const [isOpen, setIsOpen] = useState(false); return (

setIsOpen(false)} header={ Close} /> } footer={

} >

This is a bottom sheet with header and footer.

); }; ``` #### Loading State Example Demonstrates how to use the loading state in the bottom sheet. ```tsx export const LoadingStateExample = () => { const [state, setState] = useState('active'); return (

setState('active')} >

Loading content...

); }; ``` #### Error State Handling Shows how to display an error state with a retry button in the bottom sheet. ```tsx export const ErrorStateExample = () => { const [state, setState] = useState('active'); return (

setState('active')} onRetry={() => { // Handle retry logic setState('active'); }} errorContent="An error occurred while loading content. Please try again." >

Error content...

); }; ``` ### Styling Examples #### Custom Styling Example Demonstrates how to customize the bottom sheet's styling using styled-components. ```tsx const CustomBottomSheet = styled(BottomSheet)({ '& .byn-bottom-sheet__content': { background: '#f5f5f5', borderRadius: '16px 16px 0 0', }, }); export const CustomStylingExample = () => { const [isOpen, setIsOpen] = useState(false); return (

setIsOpen(false)} >

Custom Styled BottomSheet

This bottom sheet has custom styling applied.

); }; ``` ## Usage ### Basic Usage The basic usage involves opening and closing the bottom sheet using the isOpen and onClose props. You can pass any content as children to be displayed inside the sheet. ### Advanced Usage For more complex use cases, you can use the StatefulBottomSheet component which handles loading and error states. You can also customize the header and footer to include action buttons and other controls. ### Common Patterns - Using the bottom sheet to display forms or important information - Implementing loading and error states to provide feedback - Adding custom headers and footers with action buttons - Styling the bottom sheet to match your application's design ## Styling ### Theme Integration The BottomSheet component uses the theme to style its background, borders, and text colors. It supports the light and dark themes through the theme.colors object. ### Customization You can customize the BottomSheet component using styled-components. The component accepts a className prop and can be styled by targeting the appropriate class names. ### Available Tokens - `colors.general.white` - `colors.surface.surfaceBase` - `colors.onSurface.mediumEmphasis` ### Styling Examples ```tsx Customizing the background color: const CustomBottomSheet = styled(BottomSheet)({ '& .byn-bottom-sheet__content': { background: '#f5f5f5' } }); ``` ```tsx Changing the border radius: const CustomBottomSheet = styled(BottomSheet)({ '& .byn-bottom-sheet__content': { borderRadius: '16px 16px 0 0' } }); ``` ## Best Practices - Always provide a clear and accessible way to close the bottom sheet, such as a close button or the default overlay. - Use the loading and error states appropriately to provide feedback to the user about the current state of the content. - Ensure that the content inside the bottom sheet is properly scrollable if it exceeds the viewport height. - Avoid overloading the bottom sheet with too much content; keep it simple and focused. ## Accessibility - The BottomSheet component automatically handles ARIA roles and attributes for accessibility. - The component supports keyboard navigation, allowing users to close it using the Escape key. - The close button in the header is properly labeled for screen readers. - The component maintains focus management to ensure proper navigation for keyboard users. ## Events and Handlers The BottomSheet component supports various event handlers for user interactions: - `onClose`: Event handler - `onOpen`: Event handler - `onRetry`: Event handler ## Performance Considerations Tips for optimal BottomSheet performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the BottomSheet component: ```tsx test('renders bottomsheet component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Branding Component **Version**: 0.1.10 **Props Count**: 377 **Description**: The `Branding` component displays a branded image using a specified name, width, height, and base URL. It leverages the `Img` component for image rendering. **Documentation Source**: Generated from TypeScript + AI # Branding The Branding component is part of the Bonyan Design System. ## Overview Branding provides a flexible and customizable interface for user interactions. ### Props | Prop | Description | |------|-------------| | `as` | You can pass a Nextjs Image component in this prop so the render component will change: | Type: ElementType | | `baseUrl` | String value for baseUrl | Type: string | | `disabledFallback` | Disabled state | Type: true | false | | `disabledPlaceholder` | Disabled state | Type: true | false | | `fallbackDirection` | fallbackDirection option | Type: "horizontal", "vertical" | | `fallbackSize` | Size configuration | Type: "base", "narrow", "narrower"... | | `fallbackVariant` | Visual variant | Type: "logotype", "sign" | | `fill` | Boolean flag for fill | Type: true | false | | `height` | Height configuration | Type: string | number | | `iconFallback` | Icon configuration | Type: true | false | | `loader` | loader property | Type: (url: { src: string; quality: number; width: number; }) => string | | `loading` | Whether the component is in a loading state | Type: "lazy", "eager" | | `name` | The name attribute for form elements | Type: string | | `onLoadCallback` | onLoadCallback property | Type: () => void | | `placeholderColor` | Color configuration | Type: string | | `priority` | Boolean flag for priority | Type: true | false | | `quality` | Numeric value for quality | Type: number | | `sizes` | Size configuration | Type: string | | `width` | Width configuration | Type: string | number | | `wrapperStyle` | wrapperStyle property | Type: CSSProperties | ## Examples ### Basic Examples #### Default Default example from Storybook - based on Storybook story ```tsx export const Default = () => { return ( Default ); }; // Export story metadata for dynamic usage export const DefaultMeta = { title: "Default", component: Default, args: {}, category: "basic" }; ``` ## Usage ### Basic Usage Basic usage of Branding ### Advanced Usage Advanced usage patterns for Branding ### Common Patterns - Standard implementation - Custom styling - Event handling ## Styling ### Theme Integration Integrates with Bonyan Design System theme tokens ### Customization Can be customized using styled() function ### Available Tokens - `primary` - `secondary` - `success` - `error` - `warning` ## Best Practices - Use semantic props for better accessibility - Follow design system guidelines - Consider responsive behavior ## Accessibility - Supports keyboard navigation - ARIA attributes included - Screen reader compatible ## Events and Handlers The Branding component supports various event handlers for user interactions: - `onLoadCallback`: Event handler ## Async Operations The Branding component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Performance Considerations Tips for optimal Branding performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Branding component: ```tsx test('renders branding component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Breadcrumb Component **Version**: 0.1.10 **Props Count**: 20 **Description**: The Breadcrumb component provides a navigation trail using a horizontal flex layout, part of the Bonyan Design System. **Documentation Source**: Generated from TypeScript + AI # Breadcrumb A component that provides a navigation trail using a horizontal flex layout. ## Overview The Breadcrumb component is used to display a hierarchical sequence of navigation items. It uses a flex layout to arrange items horizontally with proper spacing and alignment. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | ## Examples ### Basic Examples #### Basic Breadcrumb A simple breadcrumb trail showing hierarchy with default spacing. ```tsx export const BasicBreadcrumb = () => { return ( ); }; ``` ### Advanced Examples #### Advanced Breadcrumb Custom styled breadcrumb using styled-components for unique visual appearance. ```tsx const CustomBreadcrumb = styled(Breadcrumb)` gap: 24px; & > *:not(:last-child) > * { color: #666; } `; export const AdvancedBreadcrumb = () => { return ( ); }; ``` ### Styling Examples #### Breadcrumb with Spacing Custom spacing using margin and padding props to adjust layout. ```tsx export const BreadcrumbWithSpacing = () => { return ( ); }; ``` ## Usage ### Basic Usage Import the Breadcrumb and BreadcrumbItem components, then structure your navigation hierarchy. ### Advanced Usage For more complex use cases, customize the appearance using styled-components or custom styles. ### Common Patterns - Displaying navigation history - Showing current location in a multi-level structure - Enhancing navigation with icons or badges ## Styling ### Theme Integration The Breadcrumb component uses the Bonyan UI theme for consistent spacing and colors. It supports various margin and padding props that follow the theme's spacing scale. ### Customization You can customize the Breadcrumb component using styled-components or by passing custom style props. The component accepts all standard box styling props. ### Available Tokens - `spacing.sm` - `spacing.md` - `spacing.lg` - `colors.primary` - `colors.secondary` - `colors.neutral` ### Styling Examples ```tsx Using custom gap spacing: gap="24px" ``` ```tsx Applying custom colors: color="#666" ``` ```tsx Adding custom padding: p="md" ``` ## Best Practices - Always provide meaningful text for accessibility - Use consistent spacing throughout the application - Avoid deeply nested breadcrumb trails for better UX - Ensure proper color contrast for readability ## Accessibility - The Breadcrumb component uses an ordered list (`

Test content

Content

Click me

Test content

Custom Styled Button

Compact Direction

Spacious Direction

With Divider

Without Divider

Test content

setChecked(e.target.checked)} /> ); }; ``` #### Indeterminate State Demonstrates the indeterminate state of the checkbox. ```tsx export const IndeterminateExample = () => { const [checked, setChecked] = React.useState(false); return ( setChecked(e.target.checked)} /> ); }; ``` #### Disabled State Shows a disabled checkbox that cannot be interacted with. ```tsx export const DisabledCheckBox = () => { return ( ); }; ``` ### Advanced Examples #### Form Integration Integrates the checkbox within a form using Formik for state management. ```tsx export const FormikIntegration = () => { const onSubmit = (values, { setSubmitting }) => { console.log('Form submitted:', values); setSubmitting(false); }; return ( {({ values, handleChange }) => ( ); }; ``` ### Styling Examples #### Custom Styling Customizes the checkbox appearance using styled-components. ```tsx const CustomCheckBox = styled(CheckBox)` &.byn-checkbox { &__input { border-color: ${({ theme }) => theme.colors.primary.primary}; } &.checked { background: ${({ theme }) => theme.colors.primary.primary}; } } `; export const CustomStylingExample = () => { const [checked, setChecked] = React.useState(false); return ( setChecked(e.target.checked)} /> ); }; ``` ## Variants ### Size Variations Different size options for the checkbox. **Configuration:** ```tsx { "small": { "wrapperSize": 16, "boxSize": 12 }, "medium": { "wrapperSize": 20, "boxSize": 16 }, "large": { "wrapperSize": 24, "boxSize": 20 } } ``` **Example:** ```tsx const SizeVariants = () => { const [smallChecked, setSmallChecked] = React.useState(false); const [mediumChecked, setMediumChecked] = React.useState(false); const [largeChecked, setLargeChecked] = React.useState(false); return (

setSmallChecked(e.target.checked)} wrapperSize={16} boxSize={12} /> setMediumChecked(e.target.checked)} wrapperSize={20} boxSize={16} /> setLargeChecked(e.target.checked)} wrapperSize={24} boxSize={20} />

); }; export const SizeVariantsExample = () => ( ); ``` ## Usage ### Basic Usage Import the CheckBox component and use it with the checked and onChange props to handle its state. The label prop provides the text displayed next to the checkbox. ### Advanced Usage Integrate the CheckBox with form libraries like Formik or React Hook Form for advanced form handling. Use the indeterminate prop for mixed selection states. ### Common Patterns - Basic form input - Terms and conditions acceptance - Multiple choice selections - Nested checkboxes in complex forms - Custom styled checkboxes for brand consistency ## Styling ### Theme Integration The CheckBox component uses the Bonyan Design System theme for consistent styling. It leverages theme colors, spacing, and other design tokens to maintain a cohesive look across applications. ### Customization The component can be customized using styled-components or by passing custom props. You can override default styles by targeting the underlying class names or using the `styled` function from styled-components. ### Available Tokens - `colors.primary.primary` - `colors.secondary.secondary` - `spacingValues` - `borderRadius` - `boxShadow` ### Styling Examples ```tsx Customizing border color: const CustomCheckBox = styled(CheckBox)` &.byn-checkbox__input { border-color: ${({ theme }) => theme.colors.primary.primary}; } `; ``` ```tsx Changing the box size: ``` ```tsx Applying custom padding: ``` ## Best Practices - Always provide a meaningful label for accessibility. - Use the indeterminate state for mixed or partial selections. - Ensure proper state management for checked and indeterminate states. - Consider form integration for handling multiple checkboxes. - Optimize performance by memoizing expensive operations. ## Accessibility - The CheckBox component includes proper ARIA attributes for accessibility. - It supports keyboard navigation with spacebar activation. - The component ensures high contrast ratios for better visibility. - Focus states are clearly indicated for better UX. - Screen reader compatibility is maintained through proper labeling. ## Performance Considerations Tips for optimal CheckBox performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the CheckBox component: ```tsx test('renders checkbox component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Chip Component **Version**: 0.1.10 **Props Count**: 392 **Description**: The "Chip" component in Bonyan Design System is a versatile UI element for displaying concise, removable, or interactive information. **Documentation Source**: Generated from TypeScript + AI # Chip The Chip component is a compact element used to represent a small amount of information or a tag. It can be interactive, allowing users to perform actions such as selecting or removing the chip. ## Overview The Chip component is versatile and can display various states, icons, and counters. It supports different sizes, variants, and can be customized to fit various design needs. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `badge` | badge property | Type: string | number | false | | `counter` | Numeric value for counter | Type: number | | `dataTest` | Data attribute for testing purposes | Type: string | | `disabled` | Whether the component is disabled | Type: true | false | | `ellipsis` | Boolean flag for ellipsis | Type: true | false | | `endIcon` | Icon configuration | Type: React element | | `hasClear` | Boolean flag for hasClear | Type: true | false | | `id` | The unique identifier for the component | Type: string | | `onClear` | onClear property | Type: () => void | | `onClick` | Click event handler | Type: click handler | | `selected` | Boolean flag for selected | Type: true | false | | `size` | The size variant of the component | Type: "base", "large", "base"... | Required | | `startIcon` | Icon configuration | Type: React element | | `title` | The title attribute for the component | Type: string | | `variant` | The visual variant of the component | Type: "fill", "outline", "fill"... | ## Examples ### Basic Examples #### Basic Chip A simple chip with text content. ```tsx export const BasicChip = () => { return ( ); }; ``` #### Chip with Icons A chip with both start and end icons. ```tsx export const ChipWithIcons = () => { return ( } endIcon={} /> ); }; ``` #### Disabled Chip A disabled chip that cannot be interacted with. ```tsx export const DisabledChip = () => { return ( ); }; ``` ### Variant Examples #### Selected Chip A chip that is selected, indicating active state. ```tsx export const SelectedChip = () => { return ( ); }; ``` ### Advanced Examples #### Chip with Counter A chip displaying a numerical counter. ```tsx export const ChipWithCounter = () => { return ( ); }; ``` ### Styling Examples #### Custom Styled Chip A chip with custom styling using styled-components. ```tsx const CustomChip = styled(Chip)({ background: ({ theme }) => theme.colors.primary.primaryContainer, color: ({ theme }) => theme.colors.primary.primaryOnContainer, }); export const CustomStyledChip = () => { return ( ); }; ``` ## Variants ### Size Variants The Chip component comes in different sizes to accommodate various content lengths. **Configuration:** ```tsx { "size": "CHIP_SIZE.LARGE" } ``` **Example:** ```tsx export const LargeChip = () => { return ( ); }; ``` ### Variant Types The Chip can be either outlined or filled. **Configuration:** ```tsx { "variant": "fill" } ``` **Example:** ```tsx export const FillChip = () => { return ( ); }; ``` ## Usage ### Basic Usage Import the Chip component and use it with the title prop for basic functionality. ### Advanced Usage Combine various props like startIcon, endIcon, selected, and counter to create more complex and interactive chips. ### Common Patterns - Filter chips for selecting multiple options - Action chips for triggering specific actions - Display chips for showing static information ## Styling ### Theme Integration The Chip component uses the Bonyan Design System theme to style its appearance. It leverages theme properties for colors, spacing, and typography to maintain consistency across the application. ### Customization The Chip component can be customized using styled-components. You can override the default styles by creating a custom styled component. ### Available Tokens - `colors.primary` - `colors.secondary` - `colors.onSurface` - `spacing.token` - `typography.token` ### Styling Examples ```tsx Custom background and text color: const CustomChip = styled(Chip)({ background: ({ theme }) => theme.colors.primary.primaryContainer, color: ({ theme }) => theme.colors.primary.primaryOnContainer, }); ``` ```tsx Override padding: const PaddedChip = styled(Chip)({ padding: '0 16px', }); ``` ## Best Practices - Always provide meaningful content for the chip's title to ensure proper accessibility. - Use the appropriate size variant based on the content length to maintain a clean layout. - Ensure that interactive chips have proper onClick handlers to handle user actions. - When using icons, ensure they are relevant and enhance the user's understanding of the chip's purpose. ## Accessibility - The Chip component follows ARIA standards for accessibility, ensuring proper screen reader support. - Interactive chips are keyboard navigable and support focus states. - The component ensures proper color contrast between the background and text for readability. - When using icons, ensure they have appropriate ARIA attributes to describe their purpose to screen readers. ## Events and Handlers The Chip component supports various event handlers for user interactions: - `onClick`: Event handler - `onClear`: Event handler ## Performance Considerations Tips for optimal Chip performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Chip component: ```tsx test('renders chip component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Collapsible Component **Version**: 0.1.10 **Props Count**: 4 **Description**: The Collapsible component from Bonyan Design System creates an animated, expandable/collapsible section. **Documentation Source**: Generated from TypeScript + AI # Collapsible The Collapsible component is part of the Bonyan Design System. ## Overview Collapsible provides a flexible and customizable interface for user interactions. ### Props | Prop | Description | |------|-------------| | `duration` | Numeric value for duration | Type: number | Default: 225 | | `easing` | String value for easing | Type: string | Default: ease-out | | `height` | Height configuration | Type: number | "auto" | | `isOpen` | Boolean flag for isOpen | Type: true | false | ## Examples ### Basic Examples #### Default Default example from Storybook - based on Storybook story ```tsx export const Default = () => { return ( Default ); }; // Export story metadata for dynamic usage export const DefaultMeta = { title: "Default", component: Default, args: {}, category: "basic" }; ``` ## Usage ### Basic Usage Basic usage of Collapsible ### Advanced Usage Advanced usage patterns for Collapsible ### Common Patterns - Standard implementation - Custom styling - Event handling ## Styling ### Theme Integration Integrates with Bonyan Design System theme tokens ### Customization Can be customized using styled() function ### Available Tokens - `primary` - `secondary` - `success` - `error` - `warning` ## Best Practices - Use semantic props for better accessibility - Follow design system guidelines - Consider responsive behavior ## Accessibility - Supports keyboard navigation - ARIA attributes included - Screen reader compatible ## Animation and Transitions The Collapsible component includes smooth animations: - CSS-based transitions for better performance - Configurable animation duration - Respects user motion preferences ## Testing Testing the Collapsible component: ```tsx test('renders collapsible component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Compound Component **Version**: Unknown **Props Count**: 0 **Documentation Source**: Generated from TypeScript + AI # Compound A versatile compound component that wraps its children in a React Fragment, ideal for grouping elements without adding extra DOM nodes. ## Overview The Compound component is a lightweight wrapper that uses React Fragment to group child components. It's particularly useful when you need to return multiple elements from a component without adding extra nodes to the DOM. This component is essential for maintaining a clean DOM structure while providing flexibility in layout composition. ## Examples ### Basic Examples #### Basic Usage A simple example demonstrating how to use the Compound component to wrap basic elements. ```tsx export const BasicCompoundExample = () => (

Welcome to Compound Component

This is a basic example showing how to wrap elements

); ``` ### Advanced Examples #### Advanced Layout Demonstrates using Compound for creating complex layouts with nested components. ```tsx export const AdvancedCompoundExample = () => (

Nested Compound

This shows how to nest Compound components

Another section within the parent Compound

); ``` #### Compound with Custom Components Using Compound to wrap custom components and maintain layout structure. ```tsx const CustomButton = ({ children }: { children: React.ReactNode }) => ( ); export const CustomComponentsExample = () => ( Custom Button 1 Custom Button 2

These buttons are wrapped in a Compound component

); ``` ### Styling Examples #### Styling Variants Example showing how to apply different styles to Compound components. ```tsx export const StylingVariantsExample = () => (

Variant 1

Compound with background color

Variant 2

Compound with border styling

); ``` ## Usage ### Basic Usage Import the Compound component and wrap your elements with it. It's useful when you need to return multiple elements from a component. ### Advanced Usage You can nest multiple Compound components to create complex layouts without adding extra DOM elements. Combine with other components to maintain a clean structure. ### Common Patterns - Grouping form elements - Creating layout sections - Wrapping lists and list items ## Styling ### Theme Integration The Compound component doesn't directly use theme tokens but can be styled using custom styles. It's primarily a structural component. ### Customization You can customize the Compound component using styled-components or inline styles. Since it's a Fragment wrapper, any styles applied will affect the wrapped elements. ### Styling Examples ```tsx Using inline styles: ``` ```tsx Using styled-components: const StyledCompound = styled(Compound){{ padding: 20px; background-color: #f0f0f0; }}} ``` ## Best Practices - Use Compound when you need to group elements without adding extra DOM nodes. - Avoid using Compound if you need to apply styles that require a DOM element. - Prefer Fragment over div elements when possible for better DOM structure. ## Accessibility - The Compound component doesn't interfere with accessibility since it uses React Fragment. - Ensure that all child components follow proper accessibility guidelines. - Use appropriate ARIA roles and attributes on child elements as needed. ## Performance Considerations Tips for optimal Compound performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Compound component: ```tsx test('renders compound component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## CountDown Component **Version**: 0.1.10 **Props Count**: 31 **Documentation Source**: Generated from TypeScript + AI # CountDown A countdown timer component that displays the remaining time until a specified expiration. ## Overview The CountDown component is a flexible timer that shows days, hours, minutes, and seconds remaining. It supports various formats, titles, icons, and visual variants to suit different use cases. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `counterColor` | Color configuration | Type: string | | `dataTest` | Data attribute for testing purposes | Type: string | | `expirationTimestamp` | Numeric value for expirationTimestamp | Type: number | Required | | `format` | format option | Type: "d:hh:mm:ss", "hh:mm:ss", "mm:ss" | | `hasTitle` | Boolean flag for hasTitle | Type: true | false | | `icon` | Icon to display | Type: ReactNode | | `iconPosition` | Icon configuration | Type: "none", "start", "end" | | `id` | The unique identifier for the component | Type: string | | `onEndCallback` | onEndCallback property | Type: () => void | | `startTimestamp` | Numeric value for startTimestamp | Type: number | | `title` | The title attribute for the component | Type: string | | `titleColor` | Color configuration | Type: string | | `variant` | The visual variant of the component | Type: "inline", "block" | ## Examples ### Basic Examples #### Basic Inline Countdown A simple inline countdown showing days, hours, minutes, and seconds remaining. ```tsx export const BasicInlineCountdown = () => { return ( ); }; ``` #### Countdown with Custom Format Display only hours, minutes, and seconds with a custom format. ```tsx export const CustomFormatCountdown = () => { return ( ); }; ``` ### Variant Examples #### Block Variant Countdown A block-level countdown that serves as a standalone component. ```tsx export const BlockVariantCountdown = () => { return ( ); }; ``` ### Advanced Examples #### Countdown with Icon Display countdown with an icon positioned at the start. ```tsx export const CountdownWithIcon = () => { return ( } iconPosition="start" format="d:hh:mm:ss" hasTitle={true} title="Time remaining" /> ); }; ``` #### Countdown with End Callback Execute a callback function when the countdown reaches zero. ```tsx export const CountdownWithCallback = () => { const handleEnd = () => { console.log('Countdown finished!'); }; return ( ); }; ``` ### Styling Examples #### Custom Styled Countdown Customize the appearance of the countdown using styled-components. ```tsx const CustomCountdown = styled(CountDown)` --count-down-item-value-color: #2c3e50; --count-down-item-text-color: #7f8c8d; --count-down-title-color: #34495e; `; export const CustomStyledCountdown = () => { return ( ); }; ``` ## Variants ### inline Renders the countdown in an inline format, suitable for placement within text or other components. **Configuration:** ```tsx { "variant": "inline" } ``` **Example:** ```tsx BasicInlineCountdown ``` ### block Renders the countdown as a standalone block element, suitable for dedicated display. **Configuration:** ```tsx { "variant": "block" } ``` **Example:** ```tsx BlockVariantCountdown ``` ## Usage ### Basic Usage Import the CountDown component and set the expirationTimestamp prop to a future timestamp. Optionally, customize the format and title. ### Advanced Usage Use the onEndCallback for handling countdown completion, customize the appearance using styled-components, and explore different variants for layout needs. ### Common Patterns - Displaying time remaining for a limited-time offer - Counting down to an event or launch - Showing remaining time for a task or process - Integrating with forms for time-based submissions ## Styling ### Theme Integration The CountDown component uses theme variables for colors, spacing, and typography. You can customize its appearance by modifying these variables or using custom styles. ### Customization Use styled-components to create custom styles for the countdown. You can override CSS variables like --count-down-item-value-color, --count-down-item-text-color, and --count-down-title-color. ### Available Tokens - `--count-down-item-value-color` - `--count-down-item-text-color` - `--count-down-title-color` - `--count-down-item-width` - `--count-down-item-separator-width` - `--count-down-gap` ### Styling Examples ```tsx CustomStyledCountdown ``` ```tsx Using CSS variables to style the countdown ``` ## Best Practices - Always provide a meaningful title for accessibility purposes. - Use appropriate color contrasts for readability. - Avoid using countdowns for critical timers without user feedback. - Consider performance when using frequent updates. ## Accessibility - Provides ARIA labels for screen readers. - Ensures proper color contrast for readability. - Supports keyboard navigation where applicable. - Uses semantic HTML elements for better accessibility. ## Events and Handlers The CountDown component supports various event handlers for user interactions: - `onEndCallback`: Event handler ## Form Integration The CountDown component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal CountDown performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the CountDown component: ```tsx test('renders countdown component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## DatePicker Component **Version**: Unknown **Props Count**: 1 **Documentation Source**: Generated from TypeScript + AI # DatePicker A date picker component using a wheel-based interface for selecting dates in the Jalali calendar system. ## Overview The DatePicker component provides an interactive wheel-based interface for users to select dates. It supports Jalali calendar dates and includes features like date validation, error handling, and customizable styling. ### Props | Prop | Description | |------|-------------| | `onChange` | Change event handler | Type: (selectedDate: Date | { error: number; message: string; }) => void | Required | ## Examples ### Basic Examples #### Basic Usage A simple example demonstrating the basic usage of the DatePicker component with default settings. ```tsx export const BasicDatePicker = () => { const handleDateChange = (date) => { console.log('Selected date:', date); }; return ( ); }; ``` ### Variant Examples #### Disabled State Demonstrates how to disable the DatePicker component. ```tsx export const DisabledDatePicker = () => { const handleDateChange = (date) => { console.log('Selected date:', date); }; return ( ); }; ``` ### Advanced Examples #### Error Handling Demonstrates how to handle invalid dates and future dates with appropriate error messages. ```tsx export const DatePickerWithErrorHandling = () => { const handleDateChange = (date) => { if ('error' in date) { console.error('Date error:', date.message); } else { console.log('Selected date:', date); } }; return ( ); }; ``` #### Advanced Usage with Form Integrating the DatePicker within a form to demonstrate controlled component usage. ```tsx export const DatePickerInForm = () => { const [selectedDate, setSelectedDate] = useState(null); const handleDateChange = (date: Date | { error: number; message: string }) => { if ('error' in date) { setSelectedDate(null); } else { setSelectedDate(date); } }; return (

Select a date:

{selectedDate && (

Selected date: {selectedDate.toLocaleDateString()}

)}

); }; ``` #### Large Dataset Handling Example of handling a large range of years in the DatePicker. ```tsx export const LargeRangeDatePicker = () => { const handleDateChange = (date) => { console.log('Selected date:', date); }; return ( ); }; ``` ### Styling Examples #### Custom Styling Example of custom styling using styled-components to change the appearance of the DatePicker. ```tsx const CustomStyledDatePicker = styled(WheelDatePicker)({ '.wheel-container': { backgroundColor: '#f5f5f5', borderRadius: '8px', padding: '16px', }, '.wheel': { margin: '8px 0', }, }); export const StyledDatePicker = () => { const handleDateChange = (date) => { console.log('Selected date:', date); }; return ( ); }; ``` ## Variants ### Size Variants The DatePicker supports different size variants to accommodate various layout needs. **Configuration:** ```tsx { "size": "small|medium|large" } ``` **Example:** ```tsx export const SizeVariants = () => (

{}} /> {}} /> {}} />

); ``` ## Usage ### Basic Usage Import the DatePicker component and use it with an onChange handler to capture selected dates. ### Advanced Usage Integrate the DatePicker within forms, combine it with other input components, and handle date validation based on your application's requirements. ### Common Patterns - Using the DatePicker as part of a form for data collection. - Implementing date range selection with multiple DatePicker instances. - Dynamic date validation based on user input and application constraints. ## Styling ### Theme Integration The DatePicker component uses the theme's color palette for styling. It respects the theme's outline colors for borders and background colors for various states. ### Customization You can customize the DatePicker's appearance using styled-components or by passing custom style props. The component exposes class names for different parts of the wheel picker for targeted styling. ### Available Tokens - `colors.outline.mediumEmphasis` - `colors.onSurface.highEmphasis` - `colors.onSurface.mediumEmphasis` ### Styling Examples ```tsx Custom styling using styled-components: const CustomDatePicker = styled(WheelDatePicker)({ '.wheel-container': { backgroundColor: '#f0f0f0', borderRadius: '12px', }, }); ``` ## Best Practices - Always handle potential errors when working with date selection to provide good user feedback. - Use the disabled prop to control the component's interactivity based on application state. - Consider performance implications when dealing with large date ranges and optimize rendering when necessary. - Ensure proper ARIA attributes are provided for accessibility when customizing the component. ## Accessibility - The DatePicker component provides ARIA labels for screen reader support. - It supports keyboard navigation for selecting dates. - The component ensures proper focus management for better accessibility. - Color contrast ratios are maintained for readability across different states. ## Events and Handlers The DatePicker component supports various event handlers for user interactions: - `onChange`: Event handler ## Form Integration The DatePicker component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal DatePicker performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the DatePicker component: ```tsx test('renders datepicker component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Dialog Component **Version**: 0.1.10 **Props Count**: 6 **Description**: The Dialog component in Bonyan Design System displays a modal dialog. It handles header, actions, content, and closes on user interaction. **Documentation Source**: Generated from TypeScript + AI # Dialog A modal dialog component that displays content, headers, and actions in an overlay. ## Overview The Dialog component is used to display important information or actions in a modal overlay. It supports headers, content, and action buttons, making it versatile for various use cases like confirmations, alerts, and forms. ### Props | Prop | Description | |------|-------------| | `actions` | actions property | Type: ReactNode | | `className` | String value for className | Type: string | | `header` | header property | Type: ReactNode | | `id` | The unique identifier for the component | Type: string | | `isOpen` | Boolean flag for isOpen | Type: true | false | Required | | `onClose` | onClose property | Type: () => void | ## Examples ### Basic Examples #### Basic Dialog A simple dialog with a header, content, and action buttons. Demonstrates the basic usage of the Dialog component. ```tsx export const BasicDialog = () => { const [isOpen, setIsOpen] = React.useState(false); return (

); }; ``` ### Variant Examples #### Dialog Without Actions A dialog that displays only content and header, without any action buttons. ```tsx export const DialogWithoutActions = () => { const [isOpen, setIsOpen] = React.useState(false); return (

); }; ``` #### Warning Dialog A dialog with a warning message and styled buttons to indicate different actions. ```tsx export const WarningDialog = () => { const [isOpen, setIsOpen] = React.useState(false); return (

); }; ``` ### Advanced Examples #### Loading Dialog A dialog showing a loading state with a spinner and disabled actions. ```tsx export const LoadingDialog = () => { const [isOpen, setIsOpen] = React.useState(false); return (

); }; ``` ### Styling Examples #### Custom Styled Dialog A dialog with custom styling applied through className prop. ```tsx export const CustomStyledDialog = () => { const [isOpen, setIsOpen] = React.useState(false); return (

); }; ``` ## Usage ### Basic Usage Import the Dialog component and use it by controlling the isOpen state. Provide header, content, and actions as needed. ### Advanced Usage For more complex use cases, customize the dialog with additional props or custom styling. Integrate with other components for forms or wizards. ### Common Patterns - Confirmation dialogs - Alerts and notifications - Form dialogs - Wizard steps - Error messages ## Styling ### Theme Integration The Dialog component uses the Bonyan Design System theme to style its elements. It leverages design tokens for spacing, colors, and typography to maintain consistency across the application. ### Customization The Dialog component can be customized using the className prop. You can apply custom styles by adding CSS classes to the container. For more complex customizations, you can use styled-components to extend the component's styles. ### Available Tokens - `spacing` - `colors` - `typography` - `zIndex` ### Styling Examples ```tsx Using className prop for custom styling: ``` ```tsx export const CustomDialog = () => { // ... return ( ); }; ``` ## Best Practices - Keep dialog content concise and focused on a single purpose - Use clear and actionable button labels - Ensure proper accessibility by using ARIA attributes and keyboard navigation - Avoid overloading dialogs with too much information - Use appropriate dialog types (warning, error, confirmation) based on context ## Accessibility - The Dialog component uses ARIA roles and attributes for proper screen reader support - Keyboard navigation is supported for action buttons - Focus is managed to ensure proper tabbing within the dialog - High contrast colors are used for better readability - Proper ARIA labels are provided for buttons and interactive elements ## Events and Handlers The Dialog component supports various event handlers for user interactions: - `onClose`: Event handler ## Performance Considerations Tips for optimal Dialog performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Dialog component: ```tsx test('renders dialog component', () => { render(); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Dropdown Component **Version**: 0.1.10 **Props Count**: 408 **Description**: The Bonyan Design System's `Dropdown` component offers a customizable select input for choosing from a predefined list of options, often using a bottom sheet display. **Documentation Source**: Generated from TypeScript + AI # Dropdown The Dropdown component is part of the Bonyan Design System. ## Overview Dropdown provides a flexible and customizable interface for user interactions. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `charCount` | Numeric value for charCount | Type: number | | `containerClassName` | String value for containerClassName | Type: string | | `dataTest` | Data attribute for testing purposes | Type: string | | `defaultValue` | The default value | Type: DropdownOption | | `disabled` | Whether the component is disabled | Type: true | false | | `disableHTMLInput` | Boolean flag for disableHTMLInput | Type: true | false | | `endIcon` | Icon configuration | Type: React element | | `error` | error property | Type: string | boolean | | `format` | format property | Type: "price" | "card" | "mobile" | "phone" | "sheba" | InputFormatFunction | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `helpText` | String value for helpText | Type: string | | `inputErrorId` | String value for inputErrorId | Type: string | | `label` | The label text for the component | Type: string | | `multiline` | Boolean flag for multiline | Type: true | false | | `onChange` | Change event handler | Type: (option: DropdownOption) => void | | `onChangeValue` | Change event handler | Type: (value: string) => void | | `onSelectMenuOpen` | onSelectMenuOpen property | Type: () => void | | `onWrapperClick` | Click event handler | Type: () => void | | `options` | options property | Type: DropdownOption[] | | `outfield` | Boolean flag for outfield | Type: true | false | | `placeholder` | The placeholder text | Type: string | | `postfix` | String value for postfix | Type: string | | `prefix` | String value for prefix | Type: string | | `renderOption` | renderOption component or element | Type: (option: DropdownOption, onItemClick: () => void, index?: number) => Element | | `sheetHeader` | sheetHeader component or element | Type: React element | | `startIcon` | Icon configuration | Type: React element | | `toEnglish` | Boolean flag for toEnglish | Type: true | false | | `valueDirection` | valueDirection option | Type: "ltr", "rtl" | | `warning` | String value for warning | Type: string | | `wrapperClassName` | String value for wrapperClassName | Type: string | ## Examples ### Basic Examples #### With Label WithLabel example from Storybook - based on Storybook story ```tsx export const WithLabel = () => { return ( WithLabel ); }; // Export story metadata for dynamic usage export const WithLabelMeta = { title: "With Label", component: WithLabel, args: {}, category: "basic" }; ``` #### With Placeholder WithPlaceholder example from Storybook - based on Storybook story ```tsx export const WithPlaceholder = () => { return ( WithPlaceholder ); }; // Export story metadata for dynamic usage export const WithPlaceholderMeta = { title: "With Placeholder", component: WithPlaceholder, args: {}, category: "basic" }; ``` #### With Label And Placeholder WithLabelAndPlaceholder example from Storybook - based on Storybook story ```tsx export const WithLabelAndPlaceholder = () => { return ( WithLabelAndPlaceholder ); }; // Export story metadata for dynamic usage export const WithLabelAndPlaceholderMeta = { title: "With Label And Placeholder", component: WithLabelAndPlaceholder, args: {}, category: "basic" }; ``` #### With Help Text WithHelpText example from Storybook - based on Storybook story ```tsx export const WithHelpText = () => { return ( WithHelpText ); }; // Export story metadata for dynamic usage export const WithHelpTextMeta = { title: "With Help Text", component: WithHelpText, args: {}, category: "basic" }; ``` #### With Char Count WithCharCount example from Storybook - based on Storybook story ```tsx export const WithCharCount = () => { return ( WithCharCount ); }; // Export story metadata for dynamic usage export const WithCharCountMeta = { title: "With Char Count", component: WithCharCount, args: {}, category: "basic" }; ``` #### With Start Icon WithStartIcon example from Storybook - based on Storybook story ```tsx export const WithStartIcon = () => { return ( WithStartIcon ); }; // Export story metadata for dynamic usage export const WithStartIconMeta = { title: "With Start Icon", component: WithStartIcon, args: {}, category: "basic" }; ``` #### All Properties AllProperties example from Storybook - based on Storybook story ```tsx export const AllProperties = () => { return ( AllProperties ); }; // Export story metadata for dynamic usage export const AllPropertiesMeta = { title: "All Properties", component: AllProperties, args: {}, category: "basic" }; ``` #### Disabled Disabled example from Storybook - based on Storybook story ```tsx export const Disabled = () => { return ( Disabled ); }; // Export story metadata for dynamic usage export const DisabledMeta = { title: "Disabled", component: Disabled, args: {}, category: "basic" }; ``` #### Error Error example from Storybook - based on Storybook story ```tsx export const Error = () => { return ( Error ); }; // Export story metadata for dynamic usage export const ErrorMeta = { title: "Error", component: Error, args: {}, category: "basic" }; ``` #### Error Content ErrorContent example from Storybook - based on Storybook story ```tsx export const ErrorContent = () => { return ( ErrorContent ); }; // Export story metadata for dynamic usage export const ErrorContentMeta = { title: "Error Content", component: ErrorContent, args: {}, category: "basic" }; ``` #### Custom Option CustomOption example from Storybook - based on Storybook story ```tsx export const CustomOption = () => { return ( CustomOption ); }; // Export story metadata for dynamic usage export const CustomOptionMeta = { title: "Custom Option", component: CustomOption, args: {}, category: "basic" }; ``` #### Test Test example from Storybook - based on Storybook story ```tsx export const Test = () => { return ( Test ); }; // Export story metadata for dynamic usage export const TestMeta = { title: "Test", component: Test, args: {}, category: "basic" }; ``` ## Usage ### Basic Usage Basic usage of Dropdown ### Advanced Usage Advanced usage patterns for Dropdown ### Common Patterns - Standard implementation - Custom styling - Event handling ## Styling ### Theme Integration Integrates with Bonyan Design System theme tokens ### Customization Can be customized using styled() function ### Available Tokens - `primary` - `secondary` - `success` - `error` - `warning` ## Best Practices - Use semantic props for better accessibility - Follow design system guidelines - Consider responsive behavior ## Accessibility - Supports keyboard navigation - ARIA attributes included - Screen reader compatible ## Events and Handlers The Dropdown component supports various event handlers for user interactions: - `onChange`: Event handler - `onSelectMenuOpen`: Event handler - `onWrapperClick`: Event handler - `onChangeValue`: Event handler ## Form Integration The Dropdown component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal Dropdown performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Dropdown component: ```tsx test('renders dropdown component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## EmptyState Component **Version**: 0.1.10 **Props Count**: 26 **Documentation Source**: Generated from TypeScript + AI # EmptyState A component to display visual messaging when content is unavailable, providing feedback to users. ## Overview The EmptyState component is used to inform users when there is no content to display. It supports various configurations including headlines, descriptions, images, and actions. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `action` | action property | Type: ReactNode | | `dataTest` | Data attribute for testing purposes | Type: string | | `description` | String value for description | Type: string | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `headline` | String value for headline | Type: string | | `id` | The unique identifier for the component | Type: string | | `image` | image property | Type: ReactNode | Required | | `imageAlt` | String value for imageAlt | Type: string | ## Examples ### Variant Examples #### Custom Image Empty State An empty state using a custom image instead of the default illustration. ```tsx const CustomImageEmptyState = () => { return ( } headline="Custom Empty State" description="This is a custom empty state with a different image." /> ); }; export const CustomImageEmptyStateExample = CustomImageEmptyState; ``` ### Styling Examples #### Styled Empty State An empty state with custom styling applied using styled-components. ```tsx const StyledEmptyState = styled(EmptyState)` .empty-state__headline { color: ${({ theme }) => theme.colors.primary.default}; } .empty-state__description { color: ${({ theme }) => theme.colors.secondary.default}; } padding: 32px; `; const StyledEmptyStateExample = () => { const image = ( ); return ( ); }; export const StyledEmptyStateExample = StyledEmptyStateExample; ``` ### Undefined Examples #### Basic Empty State A simple empty state with a headline and image. ```tsx const BasicEmptyState = () => { const image = ( ); return ( ); }; export const BasicEmptyStateExample = BasicEmptyState; ``` #### Empty State with Description An empty state with both headline and description. ```tsx const EmptyStateWithDescription = () => { const image = ( ); return ( ); }; export const EmptyStateWithDescriptionExample = EmptyStateWithDescription; ``` #### Empty State with Action An empty state with a headline, description, and a call-to-action button. ```tsx const EmptyStateWithAction = () => { const image = ( ); const handleActionButtonClick = () => { // Handle button click logic console.log('Action button clicked'); }; return ( تلاش دوباره } /> ); }; export const EmptyStateWithActionExample = EmptyStateWithAction; ``` #### Empty State with Two Actions An empty state with two action buttons. ```tsx const EmptyStateWithTwoActions = () => { const image = ( ); const handlePrimaryButtonClick = () => { console.log('Primary button clicked'); }; const handleSecondaryButtonClick = () => { console.log('Secondary button clicked'); }; return ( } /> ); }; export const EmptyStateWithTwoActionsExample = EmptyStateWithTwoActions; ``` ## Variants ### Image Variants Different image options for the empty state. **Configuration:** ```tsx { "image": "string | ReactNode" } ``` **Example:** ```tsx CustomImageEmptyStateExample ``` ## Usage ### Basic Usage Import the EmptyState component and use it by providing the required image prop along with optional headline, description, and action props. ### Advanced Usage Combine multiple props to create complex empty states with custom images, descriptions, and multiple actions. Use custom styling to adapt the component to different design systems or contexts. ### Common Patterns - Displaying no results in a search interface - Indicating an empty list or collection - Providing feedback for unavailable content - Guiding users to take specific actions ## Styling ### Theme Integration The EmptyState component uses the theme to derive colors, spacing, and typography. It leverages the theme's color palette for text and background colors, ensuring consistent styling across applications. ### Customization Developers can customize the EmptyState component using styled-components. By extending the base styles, you can modify colors, spacing, and other visual properties to match specific design requirements. ### Available Tokens - `colors.onBackground.highEmphasis` - `colors.onBackground.mediumEmphasis` - `spacing.padding` - `spacing.margin` ### Styling Examples ```tsx StyledEmptyStateExample ``` ## Best Practices - Always provide a clear and concise headline that explains the empty state. - Use meaningful images or illustrations that contextually relevant to the empty state scenario. - Ensure that the description provides helpful guidance or next steps for the user. - Consider adding appropriate actions to help users resolve the empty state. - Optimize images and illustrations for different screen sizes and devices. ## Accessibility - The EmptyState component uses ARIA roles and attributes to ensure proper screen reader support. - Headline and description texts have appropriate color contrast ratios for readability. - Action buttons are keyboard-navigable and have proper focus states. - Images have alternative text for screen readers. ## Performance Considerations Tips for optimal EmptyState performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the EmptyState component: ```tsx test('renders emptystate component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## FAB Component **Version**: 0.1.10 **Props Count**: 389 **Description**: The "FAB" component in Bonyan Design System is a Floating Action Button. It's a styled button for primary actions, with options for icons, colors, sizes, and spacing, and can be disabled. **Documentation Source**: Generated from TypeScript + AI # FAB A Floating Action Button (FAB) for primary actions, supporting icons, colors, sizes, and states. ## Overview The FAB component is a styled button for primary actions, with options for icons, colors, sizes, and spacing, and can be disabled or show loading states. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `color` | The color variant of the component | Type: string | | `dataTest` | Data attribute for testing purposes | Type: string | | `disabled` | Whether the component is disabled | Type: true | false | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `id` | The unique identifier for the component | Type: string | | `onClick` | Click event handler | Type: click handler | | `postIcon` | Icon displayed after the content | Type: React element | | `preIcon` | Icon displayed before the content | Type: React element | | `title` | The title attribute for the component | Type: string | ## Examples ### Basic Examples #### Basic FAB A simple FAB with an icon and text label. ```tsx export const BasicFAB = () => { const handleClick = () => { // Handle click event console.log('FAB clicked'); }; return ( } > Add Item ); }; ``` ### Variant Examples #### Icon-only FAB A FAB showing only an icon with no text label. ```tsx export const IconOnlyFAB = () => { return ( } /> ); }; ``` ### Advanced Examples #### Disabled FAB A FAB in disabled state, preventing user interaction. ```tsx export const DisabledFAB = () => { return ( } > Edit ); }; ``` #### Loading FAB A FAB showing a loading state with a spinner. ```tsx export const LoadingFAB = () => { return ( } /> ); }; ``` ### Styling Examples #### Elevated FAB A FAB with elevated box shadow for visual emphasis. ```tsx export const ElevatedFAB = () => { return ( } > Share ); }; ``` ## Variants ### small Small size FAB with compact dimensions. **Configuration:** ```tsx { "size": "small" } ``` **Example:** ```tsx export const SmallFAB = () => ( Small ); ``` ### medium Medium size FAB, the default size. **Configuration:** ```tsx { "size": "medium" } ``` **Example:** ```tsx export const MediumFAB = () => ( Medium ); ``` ### large Large size FAB for prominent actions. **Configuration:** ```tsx { "size": "large" } ``` **Example:** ```tsx export const LargeFAB = () => ( Large ); ``` ## Usage ### Basic Usage Import the FAB component and use it with basic props like color and onClick handlers. ### Advanced Usage Combine FAB with icons, loading states, and custom styling for more complex use cases. ### Common Patterns - Primary action buttons - Floating action triggers - Dashboard quick actions - Navigation helpers ## Styling ### Theme Integration The FAB component uses the theme's color and spacing tokens. The background and text colors are derived from the theme's color palette, while spacing is handled through the theme's spacing scale. ### Customization To customize the FAB, you can use styled-components. For example: const CustomFAB = styled(FAB)` box-shadow: ${props => props.theme.boxShadow[3]}; &.button--large { padding: ${props => props.theme.spacing.md}; } `; ### Available Tokens - `color.primary` - `color.secondary` - `spacing.md` - `spacing.lg` - `boxShadow.4` ### Styling Examples ```tsx Custom padding: const PaddedFAB = styled(FAB)` padding: ${spacing.lg}; `; ``` ```tsx Custom colors: const BrandFAB = styled(FAB)` background-color: ${theme.colors.brand}; `; ``` ## Best Practices - Use FAB for primary actions that require immediate attention. - Ensure FAB has proper spacing and positioning relative to other content. - Use icons to complement the text and improve understanding. - Avoid using FAB for secondary or less important actions. ## Accessibility - The FAB component includes proper ARIA roles and attributes. - It supports keyboard navigation with Enter and Space keys. - Ensure sufficient color contrast between background and text. - Provide meaningful labels for icons using aria-label or aria-labelledby. ## Events and Handlers The FAB component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal FAB performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the FAB component: ```tsx test('renders fab component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Flex Component **Version**: 0.1.10 **Props Count**: 400 **Description**: **Purpose:** A flexible layout component for Bonyan, allowing for easy arrangement of children with width, height, and display control. **Documentation Source**: Generated from TypeScript + AI # Flex A flexible layout component for arranging children with width, height, and display control. ## Overview The Flex component provides a powerful way to create flexible layouts using flexbox. It supports various alignment options, gaps, and responsive configurations. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `alignContent` | alignContent option | Type: "normal", "flex-start", "flex-end"... | | `alignItems` | alignItems option | Type: "normal", "flex-start", "flex-end"... | | `alignSelf` | alignSelf option | Type: "start", "normal", "flex-start"... | | `as` | as component or element | Type: ElementType | | `dataTest` | Data attribute for testing purposes | Type: string | | `display` | display option | Type: "inline-flex", "flex" | | `flexBasis` | String value for flexBasis | Type: string | | `flexDirection` | flexDirection option | Type: "row", "row-reverse", "column"... | | `flexFlow` | String value for flexFlow | Type: string | | `flexGrow` | flexGrow property | Type: number | CssGlobalValues | | `flexShrink` | flexShrink property | Type: number | CssGlobalValues | | `flexWrap` | flexWrap option | Type: "wrap", "nowrap", "wrap-reverse" | | `gap` | gap property | Type: xs | sm | md | lg | xl | | `horizontalGap` | horizontalGap property | Type: xs | sm | md | lg | xl | | `id` | The unique identifier for the component | Type: string | | `justifyContent` | justifyContent option | Type: "normal", "flex-start", "flex-end"... | | `verticalGap` | verticalGap property | Type: xs | sm | md | lg | xl | ## Examples ### Basic Examples #### Basic Row Layout A simple flex container with items arranged in a row. ```tsx export const BasicRowLayout = () => (

Item 1

Item 2

Item 3

); ``` #### Column Layout with Spacing A vertical flex layout with spacing between items. ```tsx export const ColumnLayout = () => (

Item 1

Item 2

Item 3

); ``` ### Advanced Examples #### Responsive Grid A responsive grid layout that changes based on screen size. ```tsx export const ResponsiveGrid = () => (

Item 1

Item 2

Item 3

); ``` #### Centered Content Flex container with centered content both vertically and horizontally. ```tsx export const CenteredContent = () => (

Centered Item 1

Centered Item 2

); ``` #### Wrapped Content Flex container with wrapped content items. ```tsx export const WrappedContent = () => ( {[1, 2, 3, 4, 5, 6].map((item) => (

Item {item}

))} ); ``` ## Usage ### Basic Usage Import the Flex component and use it to create flexible layouts. Set basic props like flexDirection and justifyContent to control the layout. ### Advanced Usage Combine multiple Flex props for complex layouts. Use gap and flexWrap for multi-line arrangements. ### Common Patterns - Responsive grids - Centered layouts - Vertical stacks - Horizontal rows ## Styling ### Theme Integration The Flex component uses the Bonyan theme for consistent spacing and layout. Theme properties are applied through the component's styling. ### Customization You can customize the Flex component using styled-components. Here's an example of creating a custom Flex variant: ### Available Tokens - `spacing` - `width` - `height` - `flexDirection` - `alignItems` - `justifyContent` ### Styling Examples ```tsx const CustomFlex = styled(Flex)`\n gap: ${props => props.theme.spacing.md};\n flex-direction: column;\n`; ``` ## Best Practices - Use the gap prop for consistent spacing between flex items. - Prefer the shorthand flexFlow prop for setting both flex-direction and flex-wrap. - Ensure proper accessibility by using appropriate ARIA roles when needed. ## Accessibility - The Flex component supports ARIA roles and attributes. - Ensure that interactive elements within Flex containers are keyboard-navigable. - Use appropriate color contrast for text content within Flex containers. ## Performance Considerations Tips for optimal Flex performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Flex component: ```tsx test('renders flex component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## IconButton Component **Version**: 0.1.10 **Props Count**: 390 **Description**: The `IconButton` component in Bonyan Design System renders a customizable button with an icon, supporting various styles (color, shape, size, and variant). **Documentation Source**: Generated from TypeScript + AI # IconButton A customizable button with an icon that supports various styles such as color, shape, size, and variant. ## Overview The IconButton component is a flexible and accessible button solution that can be tailored to fit various design needs within your application. It supports different sizes, colors, variants, and shapes, making it suitable for a wide range of use cases. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `color` | The color variant of the component | Type: "primary", "secondary", "neutral"... | | `dataTest` | Data attribute for testing purposes | Type: string | | `disabled` | Whether the component is disabled | Type: true | false | | `elevated` | Whether the component has elevated styling | Type: true | false | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `icon` | Icon to display | Type: React element | | `id` | The unique identifier for the component | Type: string | | `loading` | Whether the component is in a loading state | Type: true | false | | `onClick` | Click event handler | Type: click handler | | `onClickWhenDisabled` | Click event handler when component is disabled | Type: click handler | | `shape` | The shape variant of the component | Type: string | | `size` | The size variant of the component | Type: "small", "medium", "large"... | | `type` | The type attribute for the component | Type: "button", "submit", "reset" | | `variant` | The visual variant of the component | Type: "solid", "tonal", "standard"... | ## Examples ### Basic Examples #### Basic Icon Button A simple icon button with an 'Add' icon. ```tsx export const BasicIconButton = () => { return ( } onClick={() => console.log('Button clicked!')} /> ); }; ``` ### Variant Examples #### Icon Button with Different Sizes Examples of small, medium, and large icon buttons. ```tsx export const IconButtonSizes = () => { return (

} size="small" onClick={() => console.log('Small button clicked!')} /> } size="medium" onClick={() => console.log('Medium button clicked!')} /> } size="large" onClick={() => console.log('Large button clicked!')} />

); }; ``` #### Icon Button with Different Colors Examples of primary, secondary, and error icon buttons. ```tsx export const IconButtonColors = () => { return (

} color="primary" onClick={() => console.log('Primary button clicked!')} /> } color="secondary" onClick={() => console.log('Secondary button clicked!')} /> } color="error" onClick={() => console.log('Error button clicked!')} />

); }; ``` #### Icon Button with Different Variants Examples of solid, tonal, and standard icon button variants. ```tsx export const IconButtonVariants = () => { return (

} variant="solid" onClick={() => console.log('Solid button clicked!')} /> } variant="tonal" onClick={() => console.log('Tonal button clicked!')} /> } variant="standard" onClick={() => console.log('Standard button clicked!')} />

); }; ``` ### Advanced Examples #### Advanced Icon Button with Loading and Disabled States Demonstrates loading and disabled states of the icon button. ```tsx export const AdvancedIconButton = () => { const handleLoadingClick = () => { console.log('Loading button clicked!'); // Simulate loading state setTimeout(() => { console.log('Loading complete!'); }, 2000); }; return (

} loading onClick={handleLoadingClick} disabled={true} /> } disabled onClick={() => console.log('Disabled button clicked!')} />

); }; ``` ### Styling Examples #### Custom Styled Icon Button Example of custom styling using styled-components. ```tsx const CustomIconButton = styled(IconButton)({ background: '#4CAF50'; color: 'white'; padding: '12px'; border-radius: '4px'; '&:hover': { background: '#45a049'; } }); export const CustomStyledIconButton = () => { return ( } onClick={() => console.log('Custom styled button clicked!')} /> ); }; ``` ## Variants ### Size Variants IconButton supports three size variants: small, medium, and large. **Configuration:** ```tsx { "size": "small | medium | large" } ``` **Example:** ```tsx IconButtonSizes ``` ### Color Variants IconButton supports multiple color variants including primary, secondary, and error. **Configuration:** ```tsx { "color": "primary | secondary | error" } ``` **Example:** ```tsx IconButtonColors ``` ### Variant Types IconButton supports different visual variants: solid, tonal, and standard. **Configuration:** ```tsx { "variant": "solid | tonal | standard" } ``` **Example:** ```tsx IconButtonVariants ``` ## Usage ### Basic Usage Import the IconButton component and use it with an icon and an onClick handler. ### Advanced Usage Customize the button's appearance using various props like size, color, variant, and shape. You can also use styled-components for more advanced styling. ### Common Patterns - Use the IconButton as a standalone action button. - Integrate it with forms to trigger specific actions. - Use it in toolbars for quick access to common features. - Implement loading and disabled states for better user feedback. ## Styling ### Theme Integration The IconButton component uses the theme to derive its colors, spacing, and other visual properties. The theme provides consistent design tokens across your application. ### Customization You can customize the IconButton using styled-components or by passing custom props. For advanced customization, you can extend the component using styled-components. ### Available Tokens - `color.primary` - `color.secondary` - `color.error` - `spacing.small` - `spacing.medium` - `spacing.large` - `borderRadius.square` - `borderRadius.rounded` ### Styling Examples ```tsx CustomStyledIconButton ``` ```tsx IconButtonColors ``` ```tsx IconButtonSizes ``` ```tsx IconButtonVariants ``` ## Best Practices - Always provide a meaningful icon that clearly communicates the button's action. - Ensure proper color contrast for accessibility, especially for users with visual impairments. - Use appropriate sizing and spacing to maintain consistency across your application's UI. - Avoid using too many variants in a single application to maintain a cohesive design language. - Consider using the loading state to provide feedback for asynchronous actions. ## Accessibility - The IconButton component includes proper ARIA attributes for accessibility. - It supports keyboard navigation, allowing users to interact with the button using their keyboard. - The component ensures sufficient color contrast between the background and text colors. - Focus states are clearly visible to indicate the button's current state. - Screen readers can interpret the button's purpose through its ARIA labels. ## Events and Handlers The IconButton component supports various event handlers for user interactions: - `onClick`: Event handler - `onClickWhenDisabled`: Event handler ## Async Operations The IconButton component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Performance Considerations Tips for optimal IconButton performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the IconButton component: ```tsx test('renders iconbutton component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Illustration Component **Version**: 0.1.10 **Props Count**: 377 **Description**: This React component, Illustration, displays an image from a specified CDN as an illustration, with configurable size and an optional custom element type. **Documentation Source**: Generated from TypeScript + AI # Illustration The Illustration component is part of the Bonyan Design System. ## Overview Illustration provides a flexible and customizable interface for user interactions. ### Props | Prop | Description | |------|-------------| | `as` | You can pass a Nextjs Image component in this prop so the render component will change: | Type: ElementType | | `baseUrl` | String value for baseUrl | Type: string | | `disabledFallback` | Disabled state | Type: true | false | | `disabledPlaceholder` | Disabled state | Type: true | false | | `fallbackDirection` | fallbackDirection option | Type: "horizontal", "vertical" | | `fallbackSize` | Size configuration | Type: "base", "narrow", "narrower"... | | `fallbackVariant` | Visual variant | Type: "logotype", "sign" | | `fill` | Boolean flag for fill | Type: true | false | | `height` | Height configuration | Type: string | number | | `iconFallback` | Icon configuration | Type: true | false | | `loader` | loader property | Type: (url: { src: string; quality: number; width: number; }) => string | | `loading` | Whether the component is in a loading state | Type: "lazy", "eager" | | `name` | The name attribute for form elements | Type: string | | `onLoadCallback` | onLoadCallback property | Type: () => void | | `placeholderColor` | Color configuration | Type: string | | `priority` | Boolean flag for priority | Type: true | false | | `quality` | Numeric value for quality | Type: number | | `sizes` | Size configuration | Type: string | | `width` | Width configuration | Type: string | number | | `wrapperStyle` | wrapperStyle property | Type: CSSProperties | ## Examples ### Basic Examples #### Default Default example from Storybook - based on Storybook story ```tsx export const Default = () => { return ( Default ); }; // Export story metadata for dynamic usage export const DefaultMeta = { title: "Default", component: Default, args: {}, category: "basic" }; ``` ## Usage ### Basic Usage Basic usage of Illustration ### Advanced Usage Advanced usage patterns for Illustration ### Common Patterns - Standard implementation - Custom styling - Event handling ## Styling ### Theme Integration Integrates with Bonyan Design System theme tokens ### Customization Can be customized using styled() function ### Available Tokens - `primary` - `secondary` - `success` - `error` - `warning` ## Best Practices - Use semantic props for better accessibility - Follow design system guidelines - Consider responsive behavior ## Accessibility - Supports keyboard navigation - ARIA attributes included - Screen reader compatible ## Events and Handlers The Illustration component supports various event handlers for user interactions: - `onLoadCallback`: Event handler ## Async Operations The Illustration component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Performance Considerations Tips for optimal Illustration performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Illustration component: ```tsx test('renders illustration component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Img Component **Version**: 0.1.10 **Props Count**: 379 **Description**: The `Img` component in Bonyan Design System displays images. It handles loading states, fallbacks, and size optimizations, including Next.js image integration. **Documentation Source**: Generated from TypeScript + AI # Img The Img component is a versatile image display component that handles loading states, fallbacks, and size optimizations. It supports Next.js image integration and provides various customization options. ## Overview The Img component displays images with features like lazy loading, placeholders, and fallback images. It optimizes image rendering and provides a smooth user experience. ### Props | Prop | Description | |------|-------------| | `alt` | String value for alt | Type: string | Required | | `as` | You can pass a Nextjs Image component in this prop so the render component will change: | Type: ElementType | | `baseUrl` | String value for baseUrl | Type: string | | `disabledFallback` | Disabled state | Type: true | false | | `disabledPlaceholder` | Disabled state | Type: true | false | | `fallbackDirection` | fallbackDirection option | Type: "horizontal", "vertical" | | `fallbackSize` | Size configuration | Type: "base", "narrow", "narrower"... | | `fallbackVariant` | Visual variant | Type: "logotype", "sign" | | `fill` | Boolean flag for fill | Type: true | false | | `height` | Height configuration | Type: string | number | | `iconFallback` | Icon configuration | Type: true | false | | `loader` | loader property | Type: (url: { src: string; quality: number; width: number; }) => string | | `loading` | Whether the component is in a loading state | Type: "lazy", "eager" | | `onLoadCallback` | onLoadCallback property | Type: () => void | | `placeholderColor` | Color configuration | Type: string | | `priority` | Boolean flag for priority | Type: true | false | | `quality` | Numeric value for quality | Type: number | | `sizes` | Size configuration | Type: string | | `src` | String value for src | Type: string | Required | | `width` | Width configuration | Type: string | number | | `wrapperStyle` | wrapperStyle property | Type: CSSProperties | ## Examples ### Basic Examples #### Basic Image A simple image display with width and height specified. ```tsx export const BasicImage = () => { return ( Beautiful Iranian dish

); }; ``` ### Variant Examples #### Image with Fallback Demonstrates fallback image display when the main image fails to load. ```tsx export const ImageWithFallback = () => { return ( Fallback example

); }; ``` ### Advanced Examples #### Lazy Loaded Image Demonstrates lazy loading with a loading state. ```tsx export const LazyLoadedImage = () => { return (

); }; ``` #### Responsive Image with Sizes Responsive image using the sizes prop for different screen sizes. ```tsx export const ResponsiveImage = () => { return (

); }; ``` ### Styling Examples #### Custom Placeholder Customizes the placeholder color and uses an icon as fallback. ```tsx export const CustomPlaceholder = () => { return (

); }; ``` ## Variants ### Fallback Direction Changes how the fallback image is oriented. **Configuration:** ```tsx { "fallbackDirection": "horizontal" } ``` **Example:** ```tsx export const FallbackDirectionExample = () => (

); ``` ### Fallback Variant Changes the style of the fallback image. **Configuration:** ```tsx { "fallbackVariant": "logotype" } ``` **Example:** ```tsx export const FallbackVariantExample = () => (

); ``` ### Fallback Size Adjusts the size category of the fallback image. **Configuration:** ```tsx { "fallbackSize": "base" } ``` **Example:** ```tsx export const FallbackSizeExample = () => (

); ``` ## Usage ### Basic Usage Import the Img component and use it with the required src and alt props. You can optionally specify width, height, and other customization props. ### Advanced Usage For more complex use cases, utilize the fallback props, lazy loading, and custom styling options. You can also integrate with Next.js by using the as prop with Next.js Image. ### Common Patterns - Displaying profile pictures with fallback icons. - Showing product images with loading placeholders. - Creating responsive image grids with different sizes. ## Styling ### Theme Integration The Img component uses theme tokens for colors, spacing, and other visual properties. You can customize the appearance by modifying the theme or using styled-components. ### Customization You can customize the Img component using styled-components. Here's an example: const CustomImg = styled(Img)` border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); `; ### Available Tokens - `colors.placeholder` - `spacing.size.base` - `border.radius.full` ### Styling Examples ```tsx Custom styled component with border radius and shadow ``` ```tsx Themed placeholder color using theme.tokens.colors.placeholder ``` ## Best Practices - Always provide meaningful alt text for accessibility. - Use lazy loading for images that are not immediately visible. - Specify width and height to prevent layout shifts. - Use fallback images for better user experience when images fail to load. ## Accessibility - The Img component provides proper ARIA attributes for accessibility. - Ensures images are accessible with screen readers via alt text. - Supports keyboard navigation for interactive images. - Maintains proper color contrast for visually impaired users. ## Events and Handlers The Img component supports various event handlers for user interactions: - `onLoadCallback`: Event handler ## Async Operations The Img component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Performance Considerations Tips for optimal Img performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Img component: ```tsx test('renders img component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## InView Component **Version**: 0.1.10 **Props Count**: 4 **Description**: An InView component detects when an element is visible within the viewport, triggering actions like animations. **Documentation Source**: Generated from TypeScript + AI # InView A component that detects when it becomes visible within the viewport and triggers a callback. ## Overview The InView component uses the Intersection Observer API to detect visibility and perform actions. It's useful for animations, lazy loading, and tracking visibility. ### Props | Prop | Description | |------|-------------| | `once` | Boolean flag for once | Type: true | false | | `onVisible` | onVisible property | Type: () => void | | `options` | options property | Type: IUseIntersectionObserverOptions | | `position` | Numeric value for position | Type: number | ## Examples ### Basic Examples #### Basic Usage A simple example that triggers an alert when the component becomes visible. ```tsx export const BasicInView = () => { const handleVisible = () => { alert('Component is now visible!'); }; return (

Scroll down to see me!

); }; ``` ### Advanced Examples #### Once Flag Example Demonstrates the use of the 'once' prop to trigger the callback only once. ```tsx export const OnceInView = () => { const [count, setCount] = useState(0); const handleVisible = () => { setCount(prev => prev + 1); }; return (

Should trigger once: {count}

); }; ``` #### Custom Position Shows how to set a custom vertical position for the visibility check. ```tsx export const CustomPositionInView = () => { const handleVisible = () => { alert('I am visible at position 200px from the top!'); }; return (

Scroll down to 200px

); }; ``` #### Advanced Configuration Custom threshold and multiple visibility triggers. ```tsx export const AdvancedInView = () => { const [entries, setEntries] = useState(0); const handleVisible = () => { setEntries(prev => prev + 1); }; return (

Visibility entries: {entries}

); }; ``` #### Real-World Usage Using InView to load more items when scrolling to the bottom. ```tsx export const RealWorldInView = () => { const [items, setItems] = useState(['Item 1', 'Item 2', 'Item 3']); const loadMore = () => { setTimeout(() => { setItems(prev => [...prev, 'Item 4', 'Item 5', 'Item 6']); }, 1000); }; return (

{items.map((item, index) => (

{item}

))}

); }; ``` ## Usage ### Basic Usage Import and use the component with the onVisible prop to handle visibility. ### Advanced Usage Configure with position, options, and once for custom behavior. ### Common Patterns - Lazy loading content - Triggering animations - Infinite scroll - Tracking visibility for analytics ## Styling ### Theme Integration The InView component uses the theme's spacing and positioning tokens. ### Customization Customize using styled-components. For example: const CustomInView = styled(InView)` background-color: ${props => props.theme.colors.primary}; padding: ${props => props.theme.spacing.medium}; `; ### Available Tokens - `spacing` - `colors` - `position` ### Styling Examples ```tsx const StyledInView = styled(InView)` background-color: ${props => props.theme.colors.primary}; padding: ${props => props.theme.spacing.medium}; `; ``` ## Best Practices - Use the 'once' prop to prevent multiple triggers for single actions. - Optimize performance by using the 'threshold' option wisely. - Avoid heavy computations or API calls in the onVisible callback. ## Accessibility - The component automatically handles ARIA attributes for screen readers. - Ensure the content inside InView is accessible to screen readers. - Test with keyboard navigation to ensure proper focus management. ## Events and Handlers The InView component supports various event handlers for user interactions: - `onVisible`: Event handler - `once`: Event handler ## Performance Considerations Tips for optimal InView performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the InView component: ```tsx test('renders inview component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## InlineMessage Component **Version**: 0.1.10 **Props Count**: 23 **Description**: ## InlineMessage Component in Bonyan Design System: The `InlineMessage` component in Bonyan Design System is a versatile component for displaying contextual messages within a user interface. It's used to convey information related to a specific element or **Documentation Source**: Generated from TypeScript + AI # InlineMessage The InlineMessage component is used to display contextual messages within a user interface, providing feedback or information related to specific elements or actions. ## Overview The InlineMessage component is a flexible way to present messages in different contexts. It supports various types such as success, warning, error, and neutral, each with distinct styling to convey the message's severity. The component can be customized using spacing, typography, and color props to fit different design needs. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `className` | String value for className | Type: string | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | | `style` | style property | Type: CSSProperties | | `type` | The type attribute for the component | Type: "neutral", "warning", "error"... | ## Examples ### Basic Examples #### Basic Inline Message A simple example of an inline message with default styling and content. ```tsx export const BasicInlineMessage = () => { return ( This is a basic inline message. ); }; ``` ### Variant Examples #### Success Message Displaying a success message with appropriate styling and content. ```tsx export const SuccessMessage = () => { return ( Operation completed successfully! ); }; ``` #### Warning Message Showing a warning message to indicate potential issues. ```tsx export const WarningMessage = () => { return ( Be cautious: this action may have unintended consequences. ); }; ``` #### Error Message Displaying an error message to indicate something went wrong. ```tsx export const ErrorMessage = () => { return ( An error occurred while processing your request. ); }; ``` ### Advanced Examples #### Inline Message with Spacing Using spacing props to control the layout of the inline message. ```tsx export const MessageWithSpacing = () => { return ( Success message with custom spacing properties. ); }; ``` ### Styling Examples #### Custom Styled Inline Message Customizing the inline message with specific styling and spacing. ```tsx export const CustomStyledMessage = () => { return ( This is a custom styled warning message. ); }; ``` ## Variants ### Neutral Used for general information messages that don't require specific emphasis. **Configuration:** ```tsx "{ type: 'neutral' }" ``` **Example:** ```tsx BasicInlineMessage ``` ### Success Indicates a successful operation or positive feedback. **Configuration:** ```tsx "{ type: 'success' }" ``` **Example:** ```tsx SuccessMessage ``` ### Warning Warns about potential issues or requires user attention. **Configuration:** ```tsx "{ type: 'warning' }" ``` **Example:** ```tsx WarningMessage ``` ### Error Indicates an error or failure that needs to be addressed. **Configuration:** ```tsx "{ type: 'error' }" ``` **Example:** ```tsx ErrorMessage ``` ## Usage ### Basic Usage Import the InlineMessage component and use it by providing the message content as children. Set the type prop based on the message context. ### Advanced Usage Customize the appearance using spacing props, custom styles, or theme overrides. Combine with other components to create complex UI patterns. ### Common Patterns - Form validation messages - Action confirmation - Error notifications - Status updates - Helpful tips and hints ## Styling ### Theme Integration The InlineMessage component uses the Bonyan UI theme for consistent styling. It supports various theme properties like colors, spacing, and typography to maintain a cohesive design. ### Customization You can customize the InlineMessage component using styled-components or by passing custom style props. For example, you can change the background color, text color, padding, and border radius to match your design requirements. ### Available Tokens - `color.primary` - `color.secondary` - `color.error` - `color.warning` - `color.success` - `color.neutral` - `spacing.small` - `spacing.medium` - `spacing.large` - `typography.body1` - `typography.body2` ### Styling Examples ```tsx CustomStyledMessage ``` ```tsx MessageWithSpacing ``` ## Best Practices - Use InlineMessage for contextual feedback related to specific UI elements or actions. - Choose the appropriate message type (success, warning, error, neutral) based on the context and severity of the message. - Ensure messages are concise and clear to provide effective feedback to users. - Use spacing props to control the layout and positioning of the message within the UI. - Avoid using InlineMessage for lengthy content; instead, use it for short, informative messages. ## Accessibility - The InlineMessage component includes proper ARIA roles and attributes for screen reader support. - Messages are displayed in a way that ensures good color contrast for readability. - The component supports keyboard navigation and focus management for better accessibility. - Ensure that all messages are understandable and accessible to users with disabilities. ## Performance Considerations Tips for optimal InlineMessage performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the InlineMessage component: ```tsx test('renders inlinemessage component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## InlineProgressStep Component **Version**: 0.1.10 **Props Count**: 6 **Documentation Source**: Generated from TypeScript + AI # InlineProgressStep A component that displays progress steps in a linear arrangement, with optional animations and captions. ## Overview The InlineProgressStep component visually represents progress through a series of steps. It supports customization through various props, including colors, captions, and pulsing effects. ### Props | Prop | Description | |------|-------------| | `activeBarColor` | Color configuration | Type: string | | `currentStep` | Numeric value for currentStep | Type: number | Required | | `pulseCount` | Numeric value for pulseCount | Type: number | | `pulsingBarColor` | Color configuration | Type: string | | `showCaption` | Boolean flag for showCaption | Type: true | false | Default: true | | `totalSteps` | Numeric value for totalSteps | Type: number | Required | ## Examples ### Basic Examples #### Basic Progress Steps A simple example with 5 steps, showing progress up to the third step. ```tsx export const BasicProgressSteps = () => { return (

); }; ``` #### Progress with Pulsing Effect Demonstrates the pulsing animation on the current step and the next step. ```tsx export const ProgressWithPulsingEffect = () => { return (

); }; ``` #### Custom Colors for Progress Bars Shows how to customize the colors of the active and pulsing bars. ```tsx export const CustomProgressColors = () => { return (

); }; ``` #### Progress Without Captions Hides the step captions for a cleaner look. ```tsx export const ProgressWithoutCaptions = () => { return (

); }; ``` ### Advanced Examples #### Dynamic Progress Steps Demonstrates changing the current step dynamically with buttons. ```tsx export const DynamicProgressSteps = () => { const [currentStep, setCurrentStep] = useState(2); const totalSteps = 4; const handlePrevious = () => { setCurrentStep(prev => Math.max(1, prev - 1)); }; const handleNext = () => { setCurrentStep(prev => Math.min(totalSteps, prev + 1)); }; return (

); }; ``` ### Styling Examples #### Styled Progress Step Customizes the appearance using styled-components. ```tsx const CustomInlineProgressStep = styled(InlineProgressStep)` & .byn-inline-progress-step__bar { height: 12px; } & .byn-inline-progress-step__bar--active { background: #FF6B6B; } `; ``` ## Usage ### Basic Usage Import the component and use it with totalSteps and currentStep props. ### Advanced Usage Combine with user interactions or state management for dynamic updates. ### Common Patterns - Multi-step forms - Checkout processes - Wizard interfaces ## Styling ### Theme Integration The InlineProgressStep component uses the theme's color and spacing tokens. The default colors are derived from the theme's secondary and outline colors, while spacing is used for gaps and dimensions. ### Customization The component can be customized using styled-components. You can target the bar classes to modify heights, colors, and other styles. ### Available Tokens - `colors.secondary` - `colors.outline` - `spacing.xs` - `spacing.xxs` ### Styling Examples ```tsx Customizing bar height: .byn-inline-progress-step__bar { height: 12px; } ``` ```tsx Changing active bar color: .byn-inline-progress-step__bar--active { background: #FF6B6B; } ``` ## Best Practices - Use the pulseCount prop judiciously to avoid performance issues. - Ensure color contrast for accessibility, especially when customizing colors. - Consider the container width to maintain consistent step sizes. ## Accessibility - The component uses ARIA roles for accessibility. - Ensure proper color contrast for visually impaired users. - Test with screen readers to confirm proper announcements. ## Performance Considerations Tips for optimal InlineProgressStep performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the InlineProgressStep component: ```tsx test('renders inlineprogressstep component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## InputContainer Component **Version**: 0.1.10 **Props Count**: 373 **Description**: The InputContainer component provides a styled container for input elements in the Bonyan Design System. It manages visual styling with theming, icons, and error messages. **Documentation Source**: Generated from TypeScript + AI # InputContainer A styled container for input elements with theming, icons, and error handling. ## Overview The InputContainer component provides a flexible and styled container for various input elements. It supports features like labeling, icon placement, error states, and theming. ### Props | Prop | Description | |------|-------------| | `centricLabel` | Boolean flag for centricLabel | Type: true | false | | `disabled` | Whether the component is disabled | Type: true | false | | `endIcon` | Icon configuration | Type: React element | | `error` | Boolean flag for error | Type: true | false | | `hasValue` | Boolean flag for hasValue | Type: true | false | | `label` | The label text for the component | Type: string | | `outfield` | Boolean flag for outfield | Type: true | false | | `placeholder` | The placeholder text | Type: string | | `startIcon` | Icon configuration | Type: React element | ## Examples ### Basic Examples #### Basic InputContainer A simple input container with a label and placeholder text. ```tsx export const BasicInputContainerExample = () => { return ( ); }; ``` ### Variant Examples #### Outfield InputContainer Input container using the outfield variant for a different visual style. ```tsx export const OutfieldInputContainerExample = () => { return ( ); }; ``` ### Advanced Examples #### InputContainer with Icons Input container with start and end icons. ```tsx export const IconsInputContainerExample = () => { return ( } endIcon={} placeholder="johndoe" /> ); }; ``` #### Error Handling Input container with error state and helper text. ```tsx export const ErrorInputContainerExample = () => { return ( ); }; ``` #### Advanced InputContainer Combining multiple features: error state, icons, and outfield styling. ```tsx export const AdvancedInputContainerExample = () => { return ( } endIcon={} outfield helperText="Invalid credentials" /> ); }; ``` ### Styling Examples #### Styling with Theme Customizing the input container using theme colors and tokens. ```tsx export const StylingInputContainerExample = () => { return ( ); }; ``` ## Variants ### outfield An alternative visual style for the input container. **Configuration:** ```tsx { "outfield": true } ``` **Example:** ```tsx OutfieldInputContainerExample ``` ## Usage ### Basic Usage Use the InputContainer component to wrap your input elements and provide consistent styling and theming. ### Advanced Usage Combine various props like error handling, icons, and outfield styling for more complex use cases. ### Common Patterns - Form fields with labels and placeholders - Search inputs with icons - Error handling in forms - Custom theming and styling ## Styling ### Theme Integration The InputContainer component uses the Bonyan Design System theme to style its appearance. It supports various theme properties like colors, spacing, and typography. ### Customization You can customize the InputContainer component using styled-components or by passing custom style props. The component exposes various CSS variables for fine-grained control. ### Available Tokens - `--outline-high-emphasis` - `--outline-medium-emphasis` - `--on-surface-medium-emphasis` - `--on-surface-high-emphasis` - `--border-width` - `--min-height` - `--content-space` - `--icon-space` ### Styling Examples ```tsx StylingInputContainerExample ``` ```tsx export const CustomStyling = () => { return ( ); } ``` ## Best Practices - Always provide a meaningful label for accessibility. - Use the error prop to indicate validation errors. - Consider using icons to enhance the user experience. - Use the outfield prop for alternative styling when needed. ## Accessibility - The InputContainer component follows ARIA practices for accessibility. - It provides proper focus management and keyboard navigation. - The component ensures high contrast ratios for better readability. - Screen reader compatibility is maintained through proper ARIA attributes. ## Performance Considerations Tips for optimal InputContainer performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the InputContainer component: ```tsx test('renders inputcontainer component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## InputFile Component **Version**: Unknown **Props Count**: 9 **Documentation Source**: Generated from TypeScript + AI # InputFile A versatile file input component that supports various states and actions, including progress tracking and error handling. ## Overview The InputFile component provides a comprehensive solution for handling file uploads with different states (done, in progress, failed), captions, and action buttons. It integrates seamlessly with the Bonyan Design System and supports customization through theme variables and styled-components. ### Props | Prop | Description | |------|-------------| | `actionButtonIcon` | Icon configuration | Type: React element | | `caption` | String value for caption | Type: string | | `file` | file property | Type: File | | `imageUrl` | String value for imageUrl | Type: string | | `onActionClick` | Click event handler | Type: click handler | | `onCancelProgressClick` | Click event handler | Type: click handler | | `onFailedClick` | Click event handler | Type: click handler | | `progressValue` | Numeric value for progressValue | Type: number | | `status` | status option | Type: "done", "inProgress", "failed"... | Required | ## Examples ### Undefined Examples #### Basic File Input A basic example demonstrating the InputFile component with default props and different file states. ```tsx const BasicInputFile = () => { const imageUrl = 'https://cdn.snappfood.ir/200x201/cdn/57/02/7/vendor/62b6c80333608.jpeg'; return ( } imageUrl={imageUrl} status="done" caption="Primary Image" /> } imageUrl={imageUrl} status="inProgress" /> } imageUrl={imageUrl} status="failed" /> ); }; export const BasicInputFileExample = BasicInputFile; ``` #### File Upload with Progress Demonstrates how to implement a file upload component with progress tracking and cancel functionality. ```tsx const ProgressInputFile = () => { const imageUrl = 'https://cdn.snappfood.ir/200x201/cdn/57/02/7/vendor/62b6c80333608.jpeg'; const handleCancelProgress = () => { console.log('Upload process canceled'); }; return ( } imageUrl={imageUrl} status="inProgress" progressValue={60} onCancelProgressClick={handleCancelProgress} /> ); }; export const ProgressInputFileExample = ProgressInputFile; ``` #### Error Handling Shows how to handle failed file uploads with appropriate error messages and retry functionality. ```tsx const ErrorHandlingInputFile = () => { const imageUrl = 'https://cdn.snappfood.ir/200x201/cdn/57/02/7/vendor/62b6c80333608.jpeg'; const handleRetry = () => { console.log('Retrying file upload...'); }; return ( } imageUrl={imageUrl} status="failed" caption="Upload failed. Click to retry." onFailedClick={handleRetry} /> ); }; export const ErrorHandlingInputFileExample = ErrorHandlingInputFile; ``` #### Custom Styling Demonstrates how to customize the appearance of the InputFile component using styled-components. ```tsx const CustomInputFile = styled(InputFile)` & .input-item { border-radius: 16px; background-color: ${({ theme }) => theme.colors.surface.surface100}; } & .input-item__caption { color: ${({ theme }) => theme.colors.primary.primary500}; } `; const CustomStylingExample = () => { const imageUrl = 'https://cdn.snappfood.ir/200x201/cdn/57/02/7/vendor/62b6c80333608.jpeg'; return ( } imageUrl={imageUrl} status="done" caption="Custom Styled Image" /> ); }; export const CustomStylingExample = CustomStylingExample; ``` ## Variants ### Done State Represents a successfully uploaded file with an action button. **Configuration:** ```tsx { "status": "done", "actionButtonIcon": "" } ``` **Example:** ```tsx BasicInputFileExample ``` ### In Progress State Shows an ongoing file upload with progress tracking. **Configuration:** ```tsx { "status": "inProgress", "progressValue": "60" } ``` **Example:** ```tsx ProgressInputFileExample ``` ### Failed State Indicates a failed file upload with retry functionality. **Configuration:** ```tsx { "status": "failed", "onFailedClick": "handleRetry" } ``` **Example:** ```tsx ErrorHandlingInputFileExample ``` ## Usage ### Basic Usage Import the InputFile and InputFileItem components, and use them together to create a file upload interface with different states. ### Advanced Usage Implement custom styling, error handling, and progress tracking to create a robust file upload experience. ### Common Patterns - Multiple file uploads with individual progress tracking. - Dynamic image previews with captions. - Error recovery with retry functionality. ## Styling ### Theme Integration The InputFile component uses the Bonyan Design System theme to style its elements. It leverages theme variables for colors, spacing, and typography to ensure consistency across applications. ### Customization You can customize the InputFile component using styled-components. Wrap the component in a styled component and modify the CSS properties as needed. ### Available Tokens - `inputFileItemToken.borderRadius` - `inputFileItemToken.actionButton.right` - `inputFileItemToken.actionButton.top` - `inputFileItemToken.captionHeight` - `inputFileToken.spacing` ### Styling Examples ```tsx CustomInputFileExample ``` ```tsx CustomStylingExample ``` ## Best Practices - Always provide meaningful captions for accessibility and better user understanding. - Use appropriate icons for action buttons to enhance user experience. - Implement proper error handling and retry mechanisms for failed uploads. - Ensure progress tracking is accurate and reflects real-time upload status. ## Accessibility - The component uses ARIA attributes to ensure screen reader compatibility. - Action buttons are keyboard-navigable and support focus management. - Proper color contrast is maintained for text and background elements. - Error messages are clearly presented and accessible to all users. ## Events and Handlers The InputFile component supports various event handlers for user interactions: - `onActionClick`: Event handler - `onCancelProgressClick`: Event handler - `onFailedClick`: Event handler ## Performance Considerations Tips for optimal InputFile performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the InputFile component: ```tsx test('renders inputfile component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## InputWrapper Component **Version**: 0.1.10 **Props Count**: 392 **Description**: The `InputWrapper` component in Bonyan Design System provides a consistent styling wrapper around input fields, handling errors and warnings visually. **Documentation Source**: Generated from TypeScript + AI # InputWrapper The InputWrapper component is part of the Bonyan Design System. ## Overview InputWrapper provides a flexible and customizable interface for user interactions. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `charCount` | charCount property | Type: string | number | | `dataTest` | Data attribute for testing purposes | Type: string | | `error` | error property | Type: string | boolean | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `helpText` | String value for helpText | Type: string | | `inputErrorId` | String value for inputErrorId | Type: string | | `warning` | String value for warning | Type: string | ## Examples ### Basic Examples #### Basic InputWrapper A basic implementation of the InputWrapper component ```tsx export const BasicInputWrapper = () => { return ( Content ); }; ``` ## Usage ### Basic Usage Basic usage of InputWrapper ### Advanced Usage Advanced usage patterns for InputWrapper ### Common Patterns - Standard implementation - Custom styling - Event handling ## Styling ### Theme Integration Integrates with Bonyan Design System theme tokens ### Customization Can be customized using styled() function ### Available Tokens - `primary` - `secondary` - `success` - `error` - `warning` ## Best Practices - Use semantic props for better accessibility - Follow design system guidelines - Consider responsive behavior ## Accessibility - Supports keyboard navigation - ARIA attributes included - Screen reader compatible ## Form Integration The InputWrapper component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal InputWrapper performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the InputWrapper component: ```tsx test('renders inputwrapper component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## ItemCounter Component **Version**: 0.1.10 **Props Count**: 3 **Description**: This React component, `ItemCounter`, is a UI element within the Bonyan Design System designed for displaying and manipulating item quantities. It allows users to increment, decrement, and potentially reset or clear the count. Its styled with the system's **Documentation Source**: Generated from TypeScript + AI # ItemCounter A component to display and manage item quantities with increment, decrement, and reset functionality. ## Overview The ItemCounter component is designed to display item counts and provide basic counter controls. It supports different visual variants and can be styled according to your needs. ### Props | Prop | Description | |------|-------------| | `className` | String value for className | Type: string | | `count` | Numeric value for count | Type: number | Required | | `variant` | The visual variant of the component | Type: "flat", "elevated", "flat"... | ## Examples ### Basic Examples #### Basic Item Counter A simple example of an ItemCounter displaying a count of 2 items. ```tsx export const BasicItemCounter = () => { return ( ); }; ``` ### Variant Examples #### Flat Variant An example of the flat variant ItemCounter, suitable for minimal designs. ```tsx export const FlatVariant = () => { return ( ); }; ``` #### Elevated Variant An example of the elevated variant ItemCounter with increased visual prominence. ```tsx export const ElevatedVariant = () => { return ( ); }; ``` ### Advanced Examples #### ItemCounter with Additional Content Using ItemCounter alongside other elements to create a shopping cart item preview. ```tsx export const AdvancedUsage = () => { return ( Shopping Cart Items: ); }; ``` ### Styling Examples #### Custom Styled ItemCounter An example of customizing the ItemCounter using styled-components. ```tsx const CustomItemCounter = styled(ItemCounter)` background-color: #e0e0e0; padding: 8px; border-radius: 16px; `; export const CustomStyling = () => { return ( ); }; ``` ## Variants ### flat A minimal design with a smaller height and subtle background. **Configuration:** ```tsx { "variant": "flat" } ``` **Example:** ```tsx FlatVariant ``` ### elevated A more prominent design with a higher shadow effect and larger height. **Configuration:** ```tsx { "variant": "elevated" } ``` **Example:** ```tsx ElevatedVariant ``` ## Usage ### Basic Usage Import and use the ItemCounter component with the required `count` prop. Optionally, specify the `variant` for different visual styles. ### Advanced Usage Combine ItemCounter with other components like Flex for layout management, or use it within lists and tables for data representation. ### Common Patterns - Shopping cart item count display - Product quantity selector - Task progress indicator - Notification badge replacement ## Styling ### Theme Integration The ItemCounter component uses the following theme tokens: - `height.flat`: Height for the flat variant - `height.elevated`: Height for the elevated variant - `colors.onSurface.highEmphasis`: Text color - `colors.surface.surfaceDim`: Background color for flat variant - `colors.surface.surfaceBase`: Background color for elevated variant ### Customization You can customize the ItemCounter component using styled-components or by passing custom className props. The component accepts any valid CSS class for additional styling. ### Available Tokens - `height.flat` - `height.elevated` - `colors.onSurface.highEmphasis` - `colors.surface.surfaceDim` - `colors.surface.surfaceBase` ### Styling Examples ```tsx CustomStyling ``` ```tsx AdvancedUsage ``` ## Best Practices - Use the `flat` variant for minimal designs and the `elevated` variant when the counter needs more visual emphasis. - Ensure proper color contrast for readability, especially when customizing the background and text colors. - Consider the context where the counter is used - elevated variant works well in focused areas while flat variant is better for secondary information. ## Accessibility - The component uses proper ARIA roles and attributes for accessibility. - Ensure that the text color has sufficient contrast with the background for readability. - The component supports keyboard navigation and screen reader compatibility through proper focus management. ## Performance Considerations Tips for optimal ItemCounter performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the ItemCounter component: ```tsx test('renders itemcounter component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Label Component **Version**: 0.1.10 **Props Count**: 0 **Description**: The "Label" component displays text with various styles and purposes, like discounts, scores, or general info, within the Bonyan Design System. **Documentation Source**: Generated from TypeScript + AI # Label The Label component is part of the Bonyan Design System. ## Overview Label provides a flexible and customizable interface for user interactions. ## Examples ### Basic Examples #### Medium Medium example from Storybook - based on Storybook story ```tsx export const Medium = () => { return ( Medium ); }; // Export story metadata for dynamic usage export const MediumMeta = { title: "Medium", component: Medium, args: {}, category: "basic" }; ``` #### Large Large example from Storybook - based on Storybook story ```tsx export const Large = () => { return ( Large ); }; // Export story metadata for dynamic usage export const LargeMeta = { title: "Large", component: Large, args: {}, category: "basic" }; ``` #### Reverse Order ReverseOrder example from Storybook - based on Storybook story ```tsx export const ReverseOrder = () => { return ( ReverseOrder ); }; // Export story metadata for dynamic usage export const ReverseOrderMeta = { title: "Reverse Order", component: ReverseOrder, args: {}, category: "basic" }; ``` ## Usage ### Basic Usage Basic usage of Label ### Advanced Usage Advanced usage patterns for Label ### Common Patterns - Standard implementation - Custom styling - Event handling ## Styling ### Theme Integration Integrates with Bonyan Design System theme tokens ### Customization Can be customized using styled() function ### Available Tokens - `primary` - `secondary` - `success` - `error` - `warning` ## Best Practices - Use semantic props for better accessibility - Follow design system guidelines - Consider responsive behavior ## Accessibility - Supports keyboard navigation - ARIA attributes included - Screen reader compatible ## Performance Considerations Tips for optimal Label performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Label component: ```tsx test('renders label component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Loading Component **Version**: 0.1.10 **Props Count**: 367 **Documentation Source**: Generated from TypeScript + AI # Loading A circular loading indicator component that provides visual feedback for ongoing processes. ## Overview The Loading component displays an animated circular spinner to indicate loading or processing. It supports customizable sizes and integrates with Bonyan's theme system for consistent styling. ### Props | Prop | Description | |------|-------------| | `size` | The size variant of the component | Type: number | ## Examples ### Basic Examples #### Basic Loading A default loading spinner with the standard size and color scheme. ```tsx export const BasicLoading = () => { return ; }; ``` ### Variant Examples #### Large Loading A larger loading spinner with a size of 48 pixels. ```tsx export const LargeLoading = () => { return ; }; ``` ### Advanced Examples #### Loading with Wrapper A loading spinner wrapped in a div to demonstrate context usage. ```tsx export const LoadingWithWrapper = () => { return (

); }; ``` ### Styling Examples #### Custom Colored Loading A loading spinner with custom colors using theme tokens. ```tsx const CustomLoading = styled(Loading)({ circle:nth-child(1) { fill: ${props => props.theme.colors.primary}; } circle:nth-child(2) { fill: ${props => props.theme.colors.secondary}; } circle:nth-child(3) { fill: ${props => props.theme.colors.error}; } }); export const CustomColoredLoading = () => { return ; }; ``` ## Usage ### Basic Usage Import and use the Loading component directly in your JSX. You can adjust the size prop to change the spinner's dimensions. ### Advanced Usage For more complex use cases, wrap the Loading component in a styled-component or another container to integrate with your application's design system. ### Common Patterns - Displaying while data is being fetched - Indicating processing status - Providing feedback during asynchronous operations ## Styling ### Theme Integration The Loading component uses theme tokens for colors and animation timing. The default colors are derived from the onSurface palette, and the animation duration is defined in the theme configuration. ### Customization You can customize the appearance of the Loading component by using styled-components to override the circle colors or adjust the animation properties. ### Available Tokens - `colors.onSurface.disable` - `colors.onSurface.mediumEmphasis` - `colors.onSurface.highEmphasis` - `loading.animationTime` ### Styling Examples ```tsx Customizing size: ``` ```tsx Customizing colors using styled-components: ``` ## Best Practices - Use the Loading component to indicate ongoing processes or data fetching. - Ensure the loading spinner has appropriate contrast with its background. - Avoid using multiple loading spinners in close proximity without clear context. - Consider wrapping the spinner in a container with a fixed size for consistent layout behavior. ## Accessibility - The Loading component does not include ARIA attributes by default. Consider adding aria-label or aria-busy for screen reader support. - Ensure the spinner has sufficient color contrast against its background for visual accessibility. - Avoid using the spinner in situations where progress indication is necessary - use a progress bar instead. ## Performance Considerations Tips for optimal Loading performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Loading component: ```tsx test('renders loading component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Map Component **Version**: Unknown **Props Count**: 5 **Documentation Source**: Generated from TypeScript + AI # Map Interactive map component with markers and location spots, supporting fullscreen mode and various customization options. ## Overview The Map component provides an interactive mapping solution with support for markers, location spots, and fullscreen functionality. It integrates with Pigeon Maps and offers various customization options through props and styled-components. ### Props | Prop | Description | |------|-------------| | `anchor` | anchor property | Type: Point | | `isDragged` | Boolean flag for isDragged | Type: true | false | | `textMaxWidth` | Width configuration | Type: number | | `title` | The title attribute for the component | Type: string | | `type` | The type attribute for the component | Type: "origin", "destination" | ## Examples ### Basic Examples #### Basic Map with Markers A simple map showing two markers with different types and titles. ```tsx const center: [number, number] = [35.7222963, 51.3421122]; const secondCenter: [number, number] = [35.72245, 51.35013]; export const BasicMapExample = () => { return (

); }; ``` ### Advanced Examples #### Fullscreen Map with Location Spot A map that can be toggled to fullscreen mode with a location spot marker. ```tsx const center: [number, number] = [35.7222963, 51.3421122]; const secondCenter: [number, number] = [35.72245, 51.35013]; export const FullscreenMapExample = () => { const [isFullscreen, setIsFullscreen] = useState(false); return (

setIsFullscreen(true)} onCloseFullscreen={() => setIsFullscreen(false)} fullscreenBtn height="300px" >

); }; ``` #### Map with Tooltip Integration A map marker with an integrated tooltip showing additional information. ```tsx const center: [number, number] = [35.7222963, 51.3421122]; export const MapWithTooltipExample = () => { return (

); }; ``` #### Interactive Map with Click Handler A map that responds to click events and updates the state accordingly. ```tsx const center: [number, number] = [35.7222963, 51.3421122]; export const InteractiveMapExample = () => { const [clicked, setClicked] = useState(false); const handleClick = () => { setClicked(true); console.log('Map marker clicked!'); }; return (

{clicked &&

Marker clicked!

}

); }; ``` ### Styling Examples #### Custom Styled Map A map with custom styling using styled-components and theme tokens. ```tsx const CustomMapWrapper = styled.div` .byn-map { border: 2px solid ${props => props.theme.colors.neutral[500]}; border-radius: ${props => props.theme.rounding.md}; } `; export const CustomStyledMapExample = () => { return ( ); }; ``` ## Variants ### Marker Types Different types of markers (origin, destination) **Configuration:** ```tsx { "type": "origin|destination" } ``` **Example:** ```tsx MapMarker type="origin" ``` ## Usage ### Basic Usage Initialize the map with center coordinates and add markers as needed. ### Advanced Usage Integrate with other components like Tooltip, customize styles, and handle user interactions. ### Common Patterns - Displaying multiple markers on the map - Implementing fullscreen functionality - Adding custom event handlers ## Styling ### Theme Integration The Map component uses theme tokens for colors, spacing, and rounding. You can customize the appearance by overriding these tokens or using styled-components. ### Customization Use styled-components to wrap the Map component and apply custom styles. You can target specific classes like .byn-map for customization. ### Available Tokens - `colors.neutral.500` - `rounding.md` - `spacing.md` ### Styling Examples ```tsx Custom styled wrapper with border and rounded corners ``` ```tsx Override map container styles using .byn-map class ``` ## Best Practices - Use meaningful titles for markers to improve accessibility - Optimize marker rendering for large datasets - Implement proper error handling for map loading - Use debouncing for map event handlers ## Accessibility - Markers have proper ARIA labels through the title prop - Keyboard navigation support for interactive elements - Screen reader compatibility through proper semantic markup - Focus management for interactive components ## Performance Considerations Tips for optimal Map performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Map component: ```tsx test('renders map component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## MapPin Component **Version**: 0.1.10 **Props Count**: 4 **Description**: The `MapPin` component renders a map pin with customizable title, type (origin/destination), and drag state. It's part of Bonyan Design System. **Documentation Source**: Generated from TypeScript + AI # MapPin The MapPin component is used to represent locations on a map with optional titles and drag functionality. It supports different types such as origin and destination, and can be customized with various props. ## Overview A versatile map pin component that can display titles, indicate drag states, and differentiate between origin and destination locations. It is styled using Bonyan's design system tokens and supports advanced customization. ### Props | Prop | Description | |------|-------------| | `isDragged` | Boolean flag for isDragged | Type: true | false | | `textMaxWidth` | Width configuration | Type: number | | `title` | The title attribute for the component | Type: string | | `type` | The type attribute for the component | Type: "origin", "destination" | ## Examples ### Basic Examples #### Basic MapPin A simple map pin without any title or drag state. ```tsx export const BasicMapPin = () => { return ; }; ``` #### MapPin with Title Displays a map pin with a title below it. ```tsx export const MapPinWithTitle = () => { return ; }; ``` #### Dragged MapPin A map pin that shows the dragged state. ```tsx export const DraggedMapPin = () => { return }; ``` ### Variant Examples #### Destination Type MapPin Shows a map pin with destination type styling. ```tsx export const DestinationMapPin = () => { return ( ); }; ``` ### Advanced Examples #### Custom Text Max Width MapPin with custom maximum width for the title text. ```tsx export const CustomWidthMapPin = () => { return ( ); }; ``` #### Combined Props Example Demonstrates using multiple props together including type, isDragged, and custom textMaxWidth. ```tsx export const CombinedPropsMapPin = () => { return ( ); }; ``` ## Variants ### Origin Standard origin map pin with default styling. **Configuration:** ```tsx "{ type: 'origin' }" ``` **Example:** ```tsx export const OriginVariant = () => ; ``` ### Destination Destination map pin with distinct styling. **Configuration:** ```tsx "{ type: 'destination' }" ``` **Example:** ```tsx export const DestinationVariant = () => ; ``` ## Usage ### Basic Usage Import and use the MapPin component with basic props like title and type. ### Advanced Usage Combine multiple props like isDragged, textMaxWidth, and custom styling for more complex use cases. ### Common Patterns - Using MapPin in a map interface to mark locations. - Combining with other components for a complete mapping solution. - Implementing drag-and-drop functionality with the isDragged prop. ## Styling ### Theme Integration The MapPin component uses Bonyan's theme system for consistent styling. It leverages theme tokens for colors, spacing, and transitions to maintain a cohesive look across applications. ### Customization You can customize the MapPin component using styled-components. Here's an example of custom styling: ### Available Tokens - `colors.onSurface.highEmphasis` - `spacing.token` - `transitions.ease` - `transitions.duration` ### Styling Examples ```tsx const CustomMapPin = styled(MapPin)` &.dot::after { background-color: ${({ theme }) => theme.colors.primary}; } `; ``` ## Best Practices - Always provide meaningful titles for better user understanding. - Use the appropriate type prop (origin/destination) based on context. - Ensure accessibility by providing proper ARIA attributes if needed. - Avoid excessive customization that might break the design system consistency. - Test different states (dragged, with title, etc.) thoroughly. ## Accessibility - The component should be accessible to screen readers by providing appropriate ARIA attributes. - Ensure that the title text is readable with sufficient color contrast. - Test keyboard navigation if the component is part of an interactive element. - Provide alternative text or labels for the pin's visual elements. ## Performance Considerations Tips for optimal MapPin performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the MapPin component: ```tsx test('renders mappin component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Menu Component **Version**: 0.1.10 **Props Count**: 2 **Description**: The `Menu` component from Bonyan Design System creates a dropdown menu. It controls visibility based on a menu button and aligns content. **Documentation Source**: Generated from TypeScript + AI # Menu A dropdown menu component that provides a list of actions or options. It supports custom menu buttons, alignment options, and integrates with other menu components like MenuItem, MenuDivider, and SubMenu. ## Overview The Menu component creates a dropdown list of items that can be triggered by a custom menu button. It supports various alignments and can be customized to fit different use cases. The component is built on top of @szhsin/react-menu and extends its functionality with Bonyan's styling and theming system. ### Props | Prop | Description | |------|-------------| | `align` | align option | Type: "start", "center", "end" | | `menuButton` | menuButton component or element | Type: React element | Required | ## Examples ### Basic Examples #### Basic Menu with Button A simple dropdown menu using a Button as the trigger. Includes basic menu items, a divider, and a header. ```tsx export const BasicMenu = () => { return ( Open Menu}> Profile Settings Actions Logout ); }; ``` #### Menu with Icon Button A dropdown menu triggered by an IconButton instead of a standard button. ```tsx export const IconMenu = () => { return ( } /> }> Share Edit More Actions Delete ); }; ``` ### Variant Examples #### Right-Aligned Menu A menu aligned to the right side of its trigger button. ```tsx export const RightAlignedMenu = () => { return ( Right Menu}> Option 1 Option 2 Section Sub-option ); }; ``` ### Advanced Examples #### Center-Aligned Menu with Icons A center-aligned menu with icons in the menu items. ```tsx export const CenterAlignedMenu = () => { return ( Center Menu}> }>Settings }>Logout Actions Help Feedback ); }; ``` #### Danger Menu Items Menu items with danger state for destructive actions. ```tsx export const DangerMenu = () => { return ( Danger Menu}> Delete Account Reset Settings Danger Zone Permanent Delete ); }; ``` ### Styling Examples #### Custom Styled Menu A menu with custom styling applied using styled-components. ```tsx const CustomMenu = styled(Menu) ` background-color: ${props => props.theme.colors.surface.soft}; box-shadow: ${props => props.theme.boxShadow(2)}; border-radius: ${props => props.theme.rounding.lg}; `; export const StyledMenu = () => { return ( Styled Menu}> Custom Item 1 Custom Item 2 Custom Section Sub-item ); }; ``` ## Variants ### Alignment Variants The Menu component supports different alignment options for positioning relative to the trigger button. **Configuration:** ```tsx { "align": "\"start\", \"center\", or \"end\"" } ``` **Example:** ```tsx export const AlignmentExample = () => (

Start}> Item Center}> Item End}> Item

); ``` ### Trigger Button Variants The menu can be triggered by different types of buttons, including IconButtons and custom buttons. **Configuration:** ```tsx { "menuButton": "Button | IconButton | Custom ReactElement" } ``` **Example:** ```tsx export const TriggerExample = () => (

Button Trigger}> Item } /> }> Item

); ``` ## Usage ### Basic Usage 1. Import the Menu component and its related components (MenuItem, MenuDivider, etc.). 2. Use the menuButton prop to specify the trigger button. 3. Add menu items, dividers, and headers as needed inside the Menu component. ### Advanced Usage 1. Customize the menu alignment using the align prop. 2. Use different types of buttons for the menu trigger. 3. Apply custom styling using styled-components. 4. Implement danger states for destructive actions. ### Common Patterns - Using Menu with IconButton for compact layouts - Creating multi-level menus with SubMenu - Styling menus to match specific design requirements - Implementing accessibility features ## Styling ### Theme Integration The Menu component uses the following theme properties: - colors: for background, text, and divider colors - borderRadius: for menu border radius - boxShadow: for menu shadow - spacing: for internal padding and margins - font: for menu item typography ### Customization The Menu component can be customized using styled-components. You can extend the base styles and override the CSS properties to match your design requirements. ### Available Tokens - `colors.general.white` - `colors.onSurface.mediumEmphasis` - `colors.surface.surfaceSoft` - `spacing.sm` - `spacing.md` - `spacing.lg` - `rounding.sm` - `rounding.md` - `rounding.lg` - `boxShadow(1)` - `boxShadow(2)` - `boxShadow(3)` - `font.body` - `font.title` ### Styling Examples ```tsx Custom background color: const CustomMenu = styled(Menu)` background-color: ${props => props.theme.colors.surface.soft}; `; ``` ```tsx Custom border radius: const CustomMenu = styled(Menu)` border-radius: ${props => props.theme.rounding.lg}; `; ``` ```tsx Custom shadow: const CustomMenu = styled(Menu)` box-shadow: ${props => props.theme.boxShadow(2)}; `; ``` ## Best Practices - Always provide a meaningful menuButton prop that clearly indicates the menu's purpose. - Use MenuDivider and MenuHeader components to organize menu items logically. - Ensure proper keyboard navigation and focus management for accessibility. - Avoid using menus for too many items; consider alternative components for complex interactions. - Use danger prop for menu items that trigger destructive actions. ## Accessibility - The Menu component follows WAI-ARIA standards for dropdown menus. - Proper ARIA roles and attributes are applied automatically. - Keyboard navigation is supported out of the box. - Ensure that menu items have proper color contrast for readability. - The component handles focus management to ensure accessibility. ## Performance Considerations Tips for optimal Menu performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Menu component: ```tsx test('renders menu component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## MessageBubble Component **Version**: 0.1.10 **Props Count**: 26 **Description**: The MessageBubble component in Bonyan Design System displays conversational message bubbles, supporting various types, shapes, and grouping behaviors. **Documentation Source**: Generated from TypeScript + AI # MessageBubble The MessageBubble component displays conversational message bubbles, supporting various types, shapes, and grouping behaviors. ## Overview MessageBubble is used to create chat-like interfaces with different message types (sender/recipient), shapes (individual, top, middle, last), and statuses. It supports error states, loading states, and custom styling through theme integration. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `error` | String value for error | Type: string | | `id` | The unique identifier for the component | Type: string | | `message` | String value for message | Type: string | | `shape` | The shape variant of the component | Type: "individual", "top", "middle"... | | `status` | String value for status | Type: string | | `type` | The type attribute for the component | Type: "sender", "recipient", "sender"... | | `typing` | Boolean flag for typing | Type: true | false | ## Examples ### Basic Examples #### Basic Message Bubbles A simple example showing sender and recipient messages with basic configuration. ```tsx export const BasicMessageBubbles = () => { return ( ); }; ``` ### Variant Examples #### Message Bubble Group with Different Shapes Demonstrates a group of messages with different shapes (top, middle, last) for a cohesive chat appearance. ```tsx export const MessageGroupShapes = () => { return ( ); }; ``` ### Advanced Examples #### Error and Status Messages Shows how to display error messages and status information in message bubbles. ```tsx export const ErrorMessageBubble = () => { return ( ); }; ``` ### Styling Examples #### Custom Styling Example Demonstrates how to customize the appearance of message bubbles using styled-components. ```tsx const CustomMessageBubble = styled(MessageBubble)` && { background-color: ${({ theme }) => theme.colors.primary.primary}; color: white; padding: ${({ theme }) => theme.spacing.sm} ${({ theme }) => theme.spacing.md}; } `; export const CustomStylingExample = () => { return ( ); }; ``` ## Variants ### Sender Message Message sent by the user, typically appearing on the right side. **Configuration:** ```tsx { "type": "sender" } ``` **Example:** ```tsx MessageBubble shape="individual" type="sender" message="Hello!" ``` ### Recipient Message Message received from another user, typically appearing on the left side. **Configuration:** ```tsx { "type": "recipient" } ``` **Example:** ```tsx MessageBubble shape="individual" type="recipient" message="Hi!" ``` ## Usage ### Basic Usage Import MessageBubble and MessageBubbleGroup, then create message bubbles with appropriate props for type, shape, and message content. ### Advanced Usage Customize message bubbles using styled-components, implement error handling, and add status indicators. ### Common Patterns - Chat interfaces - Conversational UI - Error messages display - Loading states ## Styling ### Theme Integration The MessageBubble component uses the following theme tokens: - Colors: primary, secondary, surface, error - Spacing: padding and margin values - Typography: font sizes and weights ### Customization MessageBubble can be customized using styled-components. You can override the default styles by creating a custom styled component. ### Available Tokens - `colors.primary` - `colors.secondary` - `colors.surface` - `colors.error` - `spacing.sm` - `spacing.md` - `spacing.lg` - `typography.body1` ### Styling Examples ```tsx Custom padding and colors ``` ```tsx Adding borders ``` ```tsx Changing font sizes ``` ## Best Practices - Always wrap individual MessageBubble components in a MessageBubbleGroup for proper layout and styling. - Use appropriate shapes (top, middle, last) when grouping messages to create a cohesive chat interface. - Include error messages and status updates to provide feedback to users. - Consider accessibility when customizing styles, ensuring proper color contrast and focus states. ## Accessibility - MessageBubble components should have proper ARIA roles and labels for screen reader compatibility. - Ensure that interactive elements (if any) have proper keyboard navigation and focus states. - Maintain adequate color contrast between background and text colors. - Provide alternative text for any icons used in messages. ## Performance Considerations Tips for optimal MessageBubble performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the MessageBubble component: ```tsx test('renders messagebubble component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Modal Component **Version**: 0.1.10 **Props Count**: 373 **Documentation Source**: Generated from TypeScript + AI # Modal A modal component that displays content in an overlay layer. ## Overview The Modal component provides a flexible way to display content in an overlay layer. It supports various animations, sizes, and configurations to suit different use cases. ### Props | Prop | Description | |------|-------------| | `animation` | animation option | Type: "fade", "slide" | | `fullScreen` | Boolean flag for fullScreen | Type: true | false | | `isOpen` | Boolean flag for isOpen | Type: true | false | Required | | `onClose` | onClose property | Type: () => void | | `onOpenCallback` | onOpenCallback property | Type: () => void | | `parentRef` | parentRef component or element | Type: RefObject | | `wrapperClassName` | String value for wrapperClassName | Type: string | ## Examples ### Basic Examples #### Basic Modal A simple modal that opens when a button is clicked and closes when the overlay is clicked or the escape key is pressed. ```tsx export const BasicModalExample = () => { const [isOpen, setIsOpen] = React.useState(false); return (

setIsOpen(false)} >

Modal Title

This is a basic modal with default settings.

); }; ``` ### Variant Examples #### Modal with Slide Animation A modal that uses the slide animation effect when opening and closing. ```tsx export const SlideModalExample = () => { const [isOpen, setIsOpen] = React.useState(false); return (

setIsOpen(false)} animation="slide" >

Slide Modal

This modal uses the slide animation effect.

); }; ``` ### Advanced Examples #### Advanced Modal with Form A modal containing a form with input fields and a submit button. ```tsx export const AdvancedModalExample = () => { const [isOpen, setIsOpen] = React.useState(false); const [formData, setFormData] = React.useState({ name: '', email: '' }); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); // Handle form submission console.log(formData); setIsOpen(false); }; return (

setIsOpen(false)} fullScreen >

Contact Form

); }; ``` ### Styling Examples #### Small Modal A small modal with custom dimensions. ```tsx export const SmallModalExample = () => { const [isOpen, setIsOpen] = React.useState(false); return (

setIsOpen(false)} className="small-modal" >

Small Modal

This is a small modal with custom styling.

); }; ``` #### Custom Styled Modal A modal with custom styling using styled-components. ```tsx const CustomModal = styled(Modal)`` &.byn-modal { background-color: #f0f0f0; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); } ``; export const CustomStyledModalExample = () => { const [isOpen, setIsOpen] = React.useState(false); return (

setIsOpen(false)} >

Custom Styled Modal

This modal has custom styling applied using styled-components.

); }; ``` ## Variants ### Slide Animation Modal with slide animation effect. **Configuration:** ```tsx { "animation": "slide" } ``` **Example:** ```tsx SlideModalExample ``` ### Fade Animation Modal with fade animation effect. **Configuration:** ```tsx { "animation": "fade" } ``` **Example:** ```tsx BasicModalExample ``` ### Full Screen Modal that takes up the full screen. **Configuration:** ```tsx { "fullScreen": true } ``` **Example:** ```tsx AdvancedModalExample ``` ## Usage ### Basic Usage Import the Modal component and use it by controlling its isOpen state. Provide content through its Header, Body, and Footer components. ### Advanced Usage Customize the modal's appearance using props like animation, fullScreen, and className. Integrate forms and other components within the modal. ### Common Patterns - Use as a dialog for user interactions. - Display forms for data collection. - Show alerts and confirmations. - Load content dynamically within the modal. ## Styling ### Theme Integration The Modal component uses the theme's color, spacing, and typography tokens. It supports custom styling through styled-components and CSS classes. ### Customization You can customize the Modal by using the className prop or by creating a custom styled component. The Modal's overlay and content can be styled separately using the wrapperClassName and className props. ### Available Tokens - `colors.backDrop.main` - `spacing.none` - `spacing.md` - `spacing.lg` - `spacing.xl` - `zIndex.drawer` ### Styling Examples ```tsx Using custom classes: ``` ```tsx Using styled-components: const CustomModal = styled(Modal)`...`; ``` ## Best Practices - Always provide an onClose handler to allow users to close the modal. - Use the parentRef prop to render the modal relative to a specific container. - Ensure proper focus management by using the Modal's built-in focus trapping. - Avoid nesting modals as it can cause accessibility issues and performance problems. ## Accessibility - The Modal component automatically handles ARIA roles and attributes for accessibility. - It supports keyboard navigation, allowing users to close the modal with the Escape key. - The component ensures proper focus trapping to prevent focus from escaping the modal. - Screen readers are supported through proper ARIA labeling and roles. ## Events and Handlers The Modal component supports various event handlers for user interactions: - `onClose`: Event handler - `onOpenCallback`: Event handler ## Animation and Transitions The Modal component includes smooth animations: - CSS-based transitions for better performance - Configurable animation duration - Respects user motion preferences ## Performance Considerations Tips for optimal Modal performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Modal component: ```tsx test('renders modal component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## NestableRow Component **Version**: 0.1.10 **Props Count**: 394 **Description**: The `NestableRow` component in the Bonyan Design System is a layout element. It renders a row that supports nested content with indentation and optional dividers before and after the element. **Documentation Source**: Generated from TypeScript + AI # NestableRow A layout component that supports nested content with indentation and optional dividers. ## Overview The NestableRow component is designed to handle nested layouts with ease. It provides features like indentation, optional dividers, and support for various alignment options. It's ideal for creating hierarchical structures, navigation items, or any content that requires a nested layout. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `align` | align option | Type: "flex-end", "flex-start", "center"... | | `className` | String value for className | Type: string | | `clickable` | Click event handler | Type: true | false | | `dataTest` | Data attribute for testing purposes | Type: string | | `description` | description property | Type: ReactNode | | `disabled` | Whether the component is disabled | Type: true | false | | `divider` | divider property | Type: boolean | NestableRowDivider | | `dividerMiddleInset` | Numeric value for dividerMiddleInset | Type: number | | `ellipsis` | ellipsis option | Type: "title", "all", "description" | | `headingSlot` | headingSlot component or element | Type: React element | | `id` | The unique identifier for the component | Type: string | | `indent` | indent property | Type: boolean[] | | `leftElement` | leftElement component or element | Type: React element | Required | | `onClick` | Click event handler | Type: click handler | | `rightElement` | rightElement component or element | Type: React element | Required | | `title` | The title attribute for the component | Type: string | ## Examples ### Basic Examples #### Basic Usage A simple example showing the basic structure with title and description. ```tsx export const BasicNestableRow = () => { return ( ); }; ``` #### With Left and Right Elements Example showing how to use leftElement and rightElement props to add icons or controls. ```tsx export const NestableRowWithElements = () => { return ( } > } /> ); }; ``` ### Variant Examples #### Alignment Options Demonstrates different alignment options for the content. ```tsx export const AlignmentExample = () => { return ( ); }; ``` #### Disabled State Shows how to disable interaction with the NestableRow. ```tsx export const DisabledNestableRow = () => { return ( ); }; ``` ### Advanced Examples #### Advanced Nesting Example with multiple levels of nesting and different options. ```tsx export const AdvancedNesting = () => { return ( } > } /> ); }; ``` ## Variants ### Alignment Variants Different alignment options for content within the row. **Configuration:** ```tsx { "align": "flex-start | center | flex-end" } ``` **Example:** ```tsx export const AlignmentExample = () => ( ); ``` ### Divider Variants Different divider styles and positions. **Configuration:** ```tsx { "divider": "boolean | object" } ``` **Example:** ```tsx export const DividerExample = () => ( ); ``` ## Usage ### Basic Usage Import the component and use it with the required props. Nest other components or content as needed. ### Advanced Usage Use the component with various alignment options, dividers, and custom styling for complex layouts. ### Common Patterns - Hierarchical navigation - Nested lists - Tree structures ## Styling ### Theme Integration The NestableRow component uses the theme's spacing and color values for consistent styling. The padding, margins, and divider colors are derived from the theme's token values. ### Customization You can customize the NestableRow component using styled-components. Here's an example of custom styling: ### Available Tokens - `spacing` - `colors` - `typography` ### Styling Examples ```tsx const CustomNestableRow = styled(NestableRow)` padding: ${props => props.theme.spacing.md}; margin: ${props => props.theme.spacing.sm}; `; ``` ## Best Practices - Use meaningful titles and descriptions to improve accessibility. - Consider the depth of nesting to maintain visual hierarchy. - Use appropriate padding and margins for spacing between nested elements. ## Accessibility - The component supports ARIA roles and attributes for better screen reader compatibility. - Ensure that interactive elements have proper keyboard navigation. - Maintain adequate color contrast for text and background elements. ## Events and Handlers The NestableRow component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal NestableRow performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the NestableRow component: ```tsx test('renders nestablerow component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## PinCode Component **Version**: 0.1.10 **Props Count**: 25 **Description**: The `PinCode` component in Bonyan Design System renders a customizable, styled input field for entering pin codes, handling input validation and error display. **Documentation Source**: Generated from TypeScript + AI # PinCode A customizable input field for entering pin codes with validation and error handling. ## Overview The PinCode component provides a user-friendly way to input and validate pin codes. It supports various states such as error and disabled, and can be customized to fit different design requirements. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `disabled` | Whether the component is disabled | Type: true | false | | `error` | error property | Type: string | boolean | | `fields` | fields property | Type: PinInputFieldProps[] | Required | | `hiddenInputValue` | hiddenInputValue property | Type: string[] | | `id` | The unique identifier for the component | Type: string | | `setHiddenInputValue` | setHiddenInputValue property | Type: Dispatch> | ## Examples ### Basic Examples #### Basic PinCode A simple PinCode input with default styling and behavior. ```tsx export const BasicPinCode = () => { const [value, setValue] = React.useState(''); const handleComplete = (pin: string) => { console.log('Pin entered:', pin); }; return ( setValue(e.target.value)} /> ); }; ``` #### Disabled PinCode A PinCode input that is disabled and cannot be interacted with. ```tsx export const DisabledPinCode = () => { const [value, setValue] = React.useState(''); const handleComplete = (pin: string) => { console.log('Pin entered:', pin); }; return ( setValue(e.target.value)} /> ); }; ``` ### Advanced Examples #### PinCode with Error Handling A PinCode input that displays an error message when invalid input is detected. ```tsx export const ErrorPinCode = () => { const [value, setValue] = React.useState(''); const [error, setError] = React.useState(false); const handleComplete = (pin: string) => { if (pin.length !== 5) { setError(true); } else { setError(false); console.log('Valid pin:', pin); } }; return ( setValue(e.target.value)} /> ); }; ``` #### PinCode with Custom Layout A PinCode input integrated with a custom layout and additional elements. ```tsx export const CustomLayoutPinCode = () => { const [value, setValue] = React.useState(''); const [error, setError] = React.useState(false); const handleComplete = (pin: string) => { if (pin.length !== 5) { setError(true); } else { setError(false); console.log('Valid pin:', pin); } }; const generateCode = () => { // Implement code generation logic console.log('Generating code...'); }; return ( setValue(e.target.value)} /> ); }; ``` ### Styling Examples #### Custom Styled PinCode A PinCode input with custom styling using styled-components. ```tsx const CustomPinCode = styled(PinCode)({ '& .byn-pin-code__input': { backgroundColor: '#f0f0f0', borderRadius: '8px', }, '&.error': { '& .byn-pin-code__input': { backgroundColor: '#ffebee', border: '1px solid #ff5252', }, }, }); export const CustomStyledPinCode = () => { const [value, setValue] = React.useState(''); const handleComplete = (pin: string) => { console.log('Pin entered:', pin); }; return ( setValue(e.target.value)} /> ); }; ``` ## Variants ### Default Standard PinCode input with default styling. **Example:** ```tsx BasicPinCode ``` ### Disabled Non-interactive PinCode input. **Configuration:** ```tsx { "disabled": true } ``` **Example:** ```tsx DisabledPinCode ``` ### Error PinCode input with error state. **Configuration:** ```tsx { "error": true } ``` **Example:** ```tsx ErrorPinCode ``` ## Usage ### Basic Usage Import the PinCode component and use it within your form. Provide an onComplete handler to process the pin code. ### Advanced Usage Integrate the PinCode component with additional form elements and custom layouts. Implement error handling and validation as needed. ### Common Patterns - Form validation - User authentication - Code verification - Custom form layouts ## Styling ### Theme Integration The PinCode component uses the Bonyan Design System theme for consistent styling. It supports custom colors, spacing, and typography through theme tokens. ### Customization The PinCode component can be customized using styled-components. You can target specific parts of the component using class names or by extending the component's styles. ### Available Tokens - `colors.error` - `colors.primary` - `spacing.sm` - `spacing.md` - `typography.headlineSmall` ### Styling Examples ```tsx CustomPinCode styled component example ``` ```tsx Themed PinCode using theme overrides ``` ## Best Practices - Always provide meaningful helper text for error states. - Use the PinCode component for numerical input validation. - Ensure proper spacing and layout when integrating with other components. - Handle errors gracefully by providing clear feedback. ## Accessibility - The PinCode component uses proper ARIA attributes for accessibility. - Keyboard navigation is supported for better usability. - Error messages are properly announced to screen readers. - Color contrast meets accessibility standards. ## Performance Considerations Tips for optimal PinCode performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the PinCode component: ```tsx test('renders pincode component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Price Component **Version**: 0.1.10 **Props Count**: 393 **Description**: The "Price" component displays formatted prices in the Bonyan Design System, using various styles and formatting options. **Documentation Source**: Generated from TypeScript + AI # Price The Price component is used to display formatted prices with various styling options such as size, weight, alignment, and discount calculations. ## Overview The Price component is a flexible and customizable solution for displaying prices in different formats. It supports features like discount calculations, price alignment, and various visual styles to fit different design needs. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `align` | align option | Type: "right", "left", "right"... | | `color` | The color variant of the component | Type: string | DefaultTheme | ((theme: DefaultTheme) => string) | | `containerRef` | containerRef component or element | Type: MutableRefObject | | `dataTest` | Data attribute for testing purposes | Type: string | | `discount` | Numeric value for discount | Type: number | | `free` | Boolean flag for free | Type: true | false | | `hideCurrency` | Boolean flag for hideCurrency | Type: true | false | | `id` | The unique identifier for the component | Type: string | | `isFreeTitle` | String value for isFreeTitle | Type: string | | `label` | The label text for the component | Type: true | false | | `price` | price property | Type: string | number | Required | | `realPrice` | realPrice property | Type: string | number | | `size` | The size variant of the component | Type: "standard", "large", "standard"... | | `type` | The type attribute for the component | Type: string | | `weight` | weight option | Type: "light", "base", "light"... | ## Examples ### Basic Examples #### Basic Price Display A simple example showing how to display a price with default styling. ```tsx export const BasicPriceExample = () => { return ( ); }; ``` ### Variant Examples #### Different Price Sizes Examples of different price sizes (standard and large). ```tsx export const SizePriceExample = () => { return ( ); }; ``` ### Advanced Examples #### Price with Discount Displaying a discounted price with the original price struck through. ```tsx export const DiscountPriceExample = () => { return ( ); }; ``` #### Price with Spacing Demonstrating how to add margins and padding to the Price component. ```tsx export const SpacingPriceExample = () => { return ( ); }; ``` ### Styling Examples #### Custom Colored Prices Using different colors for different price elements. ```tsx export const CustomColorPriceExample = () => { return ( ); }; ``` ## Variants ### Size Variants The Price component comes in two sizes: standard and large. **Configuration:** ```tsx { "size": "PRICE_SIZE.standard | PRICE_SIZE.large" } ``` **Example:** ```tsx export const SizeExample = () => ( ); ``` ### Weight Variants The Price component supports light and base font weights. **Configuration:** ```tsx { "weight": "PRICE_WEIGHT.light | PRICE_WEIGHT.base" } ``` **Example:** ```tsx export const WeightExample = () => ( ); ``` ### Alignment Variants Prices can be aligned to the left or right. **Configuration:** ```tsx { "align": "PRICE_ALIGN.left | PRICE_ALIGN.right" } ``` **Example:** ```tsx export const AlignExample = () => ( ); ``` ## Usage ### Basic Usage Import the Price component and use it with the price prop to display a formatted price. ### Advanced Usage For more complex use cases, use additional props like realPrice, discount, and custom styling to create unique price displays. ### Common Patterns - Displaying original and discounted prices - Highlighting prices with different colors - Adjusting spacing around prices - Using different sizes for visual hierarchy ## Styling ### Theme Integration The Price component uses the Bonyan theme for consistent styling. It leverages theme properties for colors, typography, and spacing to maintain a cohesive design across applications. ### Customization The Price component can be customized using styled-components. You can create custom styles by extending the base component and adding your own styles. ### Available Tokens - `colors.primary` - `colors.secondary` - `colors.error` - `colors.success` - `colors.onSurface` - `spacing.xs` - `spacing.sm` - `spacing.md` - `spacing.lg` - `spacing.xl` - `typography.label` ### Styling Examples ```tsx export const CustomPrice = styled(Price)` color: ${props => props.theme.colors.error}; font-size: 24px; `; ``` ## Best Practices - Always provide a meaningful price value for accessibility. - Use appropriate color contrasts for different states. - Avoid using too many different sizes in a single view for consistency. - Consider the context when choosing between different variants. ## Accessibility - The Price component includes ARIA labels for screen reader support. - Proper color contrast ratios are maintained for readability. - Keyboard navigation is supported for interactive elements. - The component follows semantic HTML structure for better accessibility. ## Performance Considerations Tips for optimal Price performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Price component: ```tsx test('renders price component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## ProgressStep Component **Version**: 0.1.10 **Props Count**: 24 **Description**: A component from Bonyan Design System visualized as a single step inside a progress bar, with a text label and status indication related to total steps. **Documentation Source**: Generated from TypeScript + AI # ProgressStep A component that visually represents a single step within a progress bar, indicating the current state relative to total steps. ## Overview The ProgressStep component is used to display progress through a series of steps. It supports different weights, custom middle words, and various styling options through Bonyan's design system. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `currentSteps` | Numeric value for currentSteps | Type: number | Required | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | | `middleWord` | String value for middleWord | Type: string | | `totalSteps` | Numeric value for totalSteps | Type: number | Required | | `weight` | weight option | Type: "light", "medium" | ## Examples ### Basic Examples #### Basic Usage A simple example with 6 total steps and current step set to 3, using the light weight. ```tsx export const BasicProgressStep = () => { return ( ); }; ``` #### More Than 6 Steps Example with 10 total steps and current step set to 1. ```tsx export const MoreThan6StepsProgress = () => { return ( ); }; ``` ### Variant Examples #### Medium Weight Progress Example using medium weight with 6 total steps and current step set to 2. ```tsx export const MediumWeightProgress = () => { return ( ); }; ``` #### Custom Middle Word Progress step with a custom middle word for localization. ```tsx export const CustomMiddleWordProgress = () => { return ( ); }; ``` ### Advanced Examples #### Advanced Progress with Spacing Customizing spacing using Bonyan's spacing props. ```tsx export const AdvancedProgressSpacing = () => { return ( ); }; ``` ### Styling Examples #### Styling with Theme Tokens Customizing the progress step using theme tokens and styled-components. ```tsx const CustomProgressStep = styled(ProgressStep)` & .title { color: ${({ theme }) => theme.colors.primary.primary500}; } & .steps-container { background-color: ${({ theme }) => theme.colors.surface.surface200}; } `; export const StyledProgressStep = () => { return ( ); }; ``` ## Variants ### Light Weight The default light weight visualization with minimal styling. **Configuration:** ```tsx { "weight": "light" } ``` **Example:** ```tsx BasicProgressStep ``` ### Medium Weight A heavier visual weight with more pronounced styling. **Configuration:** ```tsx { "weight": "medium" } ``` **Example:** ```tsx MediumWeightProgress ``` ## Usage ### Basic Usage Import the component and use it with required totalSteps and currentSteps props. Optional props like weight and middleWord can be added as needed. ### Advanced Usage For advanced use cases, customize the component using styled-components and Bonyan's theme tokens. Adjust spacing and other visual properties to fit specific design requirements. ### Common Patterns - Checkout processes with multiple steps - File upload progress indication - Wizard interfaces with step tracking - Installation progress tracking ## Styling ### Theme Integration The ProgressStep component uses Bonyan's theme system for consistent styling. It leverages color, spacing, and typography tokens to maintain a cohesive design language across applications. ### Customization The component can be customized using styled-components. You can target specific parts of the component using class names like .title and .steps-container to apply custom styles. ### Available Tokens - `colors.surface.surfaceBase` - `colors.onSurface.mediumEmphasis` - `spacing.sm` - `spacing.lg` - `spacing.xs` - `spacing.sm` ### Styling Examples ```tsx CustomProgressStep styled component example ``` ```tsx Using theme colors for background and text ``` ## Best Practices - Always provide both totalSteps and currentSteps for accurate progress representation. - Use meaningful values for middleWord when localization is required. - Leverage Bonyan's spacing system for consistent layout. - Avoid excessive customization that deviates from the design system. - Ensure accessibility by following ARIA guidelines and proper focus management. ## Accessibility - The component uses ARIA roles to ensure screen reader compatibility. - Proper focus management is handled through Bonyan's system. - Maintains appropriate color contrast for readability. - Keyboard navigation is supported for interactive elements. - Follows semantic HTML structure for better accessibility. ## Performance Considerations Tips for optimal ProgressStep performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the ProgressStep component: ```tsx test('renders progressstep component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Radio Component **Version**: 0.1.10 **Props Count**: 315 **Description**: The Bonyan Design System's `Radio` component creates a customizable radio button with label, styled for a consistent UI. It supports states like checked, disabled, and various styling options. **Documentation Source**: Generated from TypeScript + AI # Radio A customizable radio button component with label support, designed for consistent UI experiences. ## Overview The Radio component provides a flexible way to create radio buttons with various states and styling options. It supports features like checked, disabled, and read-only states, along with customizable spacing and theming. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | | `label` | The label text for the component | Type: string | ## Examples ### Basic Examples #### Basic Radio Example A simple radio button with a label demonstrating the basic usage. ```tsx export const BasicRadio = () => { return ( ); }; ``` #### Checked and Disabled States Demonstrates both checked and disabled states of the radio button. ```tsx export const CheckedDisabledRadio = () => { return (

); }; ``` #### Radio Playground Interactive example with state management to demonstrate radio behavior. ```tsx export const RadioPlayground = () => { const [checked, setChecked] = useState(false); return ( setChecked(e.target.checked)} dataTest="playground-radio" /> ); }; ``` ### Advanced Examples #### Radio Group Example A group of radio buttons demonstrating multiple choice selection. ```tsx export const RadioGroup = () => { const [selected, setSelected] = useState(''); return (

setSelected(e.target.value)} label="Option 1" /> setSelected(e.target.value)} label="Option 2" /> setSelected(e.target.value)} label="Option 3" />

); }; ``` ### Styling Examples #### Custom Styled Radio Example of customizing the radio appearance using styled-components. ```tsx const CustomRadioContainer = styled.div` padding: 16px; background-color: #f5f5f5; border-radius: 8px; display: flex; align-items: center; gap: 8px; `; export const CustomStyledRadio = () => { return ( ); }; ``` #### Themed Radio Example Demonstrates how to customize the radio's appearance using theme tokens. ```tsx export const ThemedRadio = () => { return (

); }; ``` ## Usage ### Basic Usage Import and use the Radio component directly in your React components. Provide a label and manage the checked state using the onChange handler. ### Advanced Usage For multiple choice scenarios, use the name prop to group radio buttons. Implement state management to track the selected option. ### Common Patterns - Single radio button with label - Grouped radio buttons for multiple choice - Custom styled radio buttons - Themed radio buttons ## Styling ### Theme Integration The Radio component uses Bonyan's theme system for consistent styling. It leverages theme tokens for colors, spacing, and other visual properties. The component's styling can be customized through CSS variables and styled-components. ### Customization To customize the Radio component, you can use styled-components or apply custom CSS classes. The component's styling can be extended by modifying its underlying CSS variables or by wrapping it in a styled container. ### Available Tokens - `circleSize` - `stateWrapperSize` - `borderWidth` - `spacing` ### Styling Examples ```tsx Using styled-components to wrap the radio ``` ```tsx Applying custom CSS classes for container styling ``` ```tsx Modifying CSS variables for color customization ``` ## Best Practices - Always provide a meaningful label for accessibility - Use radio groups for multiple choice scenarios - Ensure proper spacing using margin and padding props - Test all states (checked, disabled, read-only) thoroughly ## Accessibility - The Radio component follows ARIA practices for accessibility - Proper ARIA attributes are automatically applied - Keyboard navigation is supported - High contrast ratios for visual accessibility ## Performance Considerations Tips for optimal Radio performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Radio component: ```tsx test('renders radio component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## RangeSlider Component **Version**: 0.1.10 **Props Count**: 31 **Description**: **RangeSlider** in Bonyan provides a customizable slider for selecting a numerical range. **Documentation Source**: Generated from TypeScript + AI # RangeSlider A customizable range slider component for selecting numerical values. ## Overview The RangeSlider component provides an interactive way to select a single value within a defined range. It supports various configurations including custom steps, minimum and maximum values, headers, and assistance labels. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `endAssistLabel` | String value for endAssistLabel | Type: string | | `endHeader` | endHeader property | Type: RangeSliderHeader | | `id` | The unique identifier for the component | Type: string | | `marks` | marks property | Type: MarkSpot[] | | `max` | Numeric value for max | Type: number | | `min` | Numeric value for min | Type: number | | `onChange` | Change event handler | Type: ((value: number) => void) | ((value: IRangeValue) => void) | Required | | `startAssistLabel` | String value for startAssistLabel | Type: string | | `startHeader` | startHeader property | Type: RangeSliderHeader | | `step` | Numeric value for step | Type: number | | `title` | The title attribute for the component | Type: string | | `value` | The current value | Type: number | IRangeValue | Required | ## Examples ### Basic Examples #### Basic RangeSlider A simple range slider with default settings. ```tsx export const BasicRangeSlider = () => { const [value, setValue] = React.useState(50); const handleChange = (newValue: number) => { setValue(newValue); }; return ( ); }; ``` #### RangeSlider with Step Prop A range slider that snaps to specific values using the step prop. ```tsx export const RangeSliderWithStep = () => { const [value, setValue] = React.useState(50); const handleChange = (newValue: number) => { setValue(newValue); }; return ( ); }; ``` ### Advanced Examples #### Custom Min and Max Values RangeSlider with custom minimum and maximum values. ```tsx export const CustomMinMaxRangeSlider = () => { const [value, setValue] = React.useState(250); const handleChange = (newValue: number) => { setValue(newValue); }; return ( ); }; ``` #### RangeSlider with Headers RangeSlider with custom headers at both ends. ```tsx export const RangeSliderWithHeaders = () => { const [value, setValue] = React.useState(50); const handleChange = (newValue: number) => { setValue(newValue); }; const startHeader = 'Start'; const endHeader = ( End ); return ( ); }; ``` #### RangeSlider with Assist Labels RangeSlider with assistance labels below the thumbs. ```tsx export const RangeSliderWithAssistLabels = () => { const [value, setValue] = React.useState(50); const handleChange = (newValue: number) => { setValue(newValue); }; return ( ); }; ``` ### Styling Examples #### Disabled RangeSlider A disabled range slider that prevents user interaction. ```tsx export const DisabledRangeSlider = () => { const [value, setValue] = React.useState(50); const handleChange = (newValue: number) => { setValue(newValue); }; return ( ); }; ``` ## Variants ### Single Thumb RangeSlider with a single thumb for selecting a single value. **Configuration:** ```tsx { "value": 50, "onChange": "(value: number) => setValue(value)" } ``` **Example:** ```tsx BasicRangeSlider ``` ### Range with Headers RangeSlider with custom headers at both ends. **Configuration:** ```tsx { "startHeader": "'Start'", "endHeader": "'End'" } ``` **Example:** ```tsx RangeSliderWithHeaders ``` ## Usage ### Basic Usage Import the RangeSlider component and use it with an initial value and onChange handler to update the value. ### Advanced Usage Customize the RangeSlider with headers, assist labels, and specific min/max values for more complex use cases. ### Common Patterns - Using the RangeSlider to select a value within a specific range. - Implementing a filter with the RangeSlider to narrow down results. - Adding custom visual elements using the header props. ## Styling ### Theme Integration The RangeSlider component uses the theme's color palette for styling. The track and thumb colors are derived from the theme's onSurface colors. The component also respects the theme's spacing and typography settings. ### Customization You can customize the RangeSlider's appearance using styled-components. Here's an example of customizing the track color: const CustomRangeSlider = styled(RangeSlider)` .rail__content { background-color: ${props => props.theme.colors.primary.lowEmphasis}; } `; ### Available Tokens - `onSurface.highEmphasis` - `onSurface.mediumEmphasis` - `primary.lowEmphasis` ### Styling Examples ```tsx CustomRangeSlider ``` ```tsx StyledRangeSlider ``` ## Best Practices - Always provide a meaningful title prop for accessibility. - Use the step prop to control the granularity of the slider's values. - Ensure the slider has proper ARIA labels for screen reader support. - Avoid using overly large ranges that could make the slider difficult to use. ## Accessibility - The RangeSlider component includes ARIA attributes for accessibility. - The slider supports keyboard navigation for users who cannot use a mouse. - Proper ARIA labels are provided through the title prop. - The component ensures high contrast ratios for better visibility. ## Events and Handlers The RangeSlider component supports various event handlers for user interactions: - `onChange`: Event handler ## Form Integration The RangeSlider component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal RangeSlider performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the RangeSlider component: ```tsx test('renders rangeslider component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Rate Component **Version**: Unknown **Props Count**: 10 **Documentation Source**: Generated from TypeScript + AI # Rate A satisfaction rating component with customizable icons, labels, and colors. ## Overview The Rate component allows users to provide feedback through an interactive rating system. It supports various sizes, colors, and can display both icons and labels. The component is fully accessible and integrates with the Bonyan design system. ## Examples ### Basic Examples #### Basic Icon-Only Rate A simple icon-only rate component with default size and colors. ```tsx export const BasicIconOnly = () => { const [value, setValue] = React.useState(-1); return ( ); }; ``` #### Label and Icon Rate A rate component with both labels and icons, using the default size. ```tsx export const LabelAndIcon = () => { const [value, setValue] = React.useState(-1); const label = ['راضی بودم', 'راضی نبودم']; return ( ); }; ``` ### Variant Examples #### Large Size Rate with Labels A large size rate component with labels and custom colors. ```tsx export const LargeSizeRate = () => { const [value, setValue] = React.useState(-1); const label = ['راضی بودم', 'راضی نبودم']; return ( ); }; ``` ### Advanced Examples #### Disabled State Example Demonstrates how to use the rate component in a disabled state. ```tsx export const DisabledRate = () => { const [value, setValue] = React.useState(-1); const label = ['راضی بودم', 'راضی نبودم']; return ( ); }; ``` ### Styling Examples #### Custom Styled Rate A custom styled rate component using styled-components. ```tsx const CustomRateContainer = styled.div` .label { color: ${props => props.theme.colors.custom.color1}; } `; export const CustomStyledRate = () => { const [value, setValue] = React.useState(-1); const label = ['راضی بودم', 'راضی نبودم']; return ( ); }; ``` ## Variants ### Size Variants The Rate component comes in three sizes: small, medium, and large. **Configuration:** ```tsx { "size": "small | medium | large" } ``` **Example:** ```tsx export const SizeVariants = () => { const [smallValue, setSmallValue] = React.useState(-1); const [mediumValue, setMediumValue] = React.useState(-1); const [largeValue, setLargeValue] = React.useState(-1); const label = ['راضی بودم', 'راضی نبودم']; return (

); }; ``` ### Color Variants The Rate component supports different colors for different states. **Configuration:** ```tsx { "color": "default | positive | negative" } ``` **Example:** ```tsx export const ColorVariants = () => { const [value, setValue] = React.useState(-1); const label = ['راضی بودم', 'راضی نبودم']; return (

); }; ``` ## Usage ### Basic Usage Import the SatisfactionRate component and use it with the required props. The component must be used within a form or with an onChange handler to manage the selected value. ### Advanced Usage For more complex use cases, customize the styling using styled-components or modify the component's behavior by extending it. ### Common Patterns - Using the Rate component in a feedback form. - Integrating with other form components for comprehensive data collection. - Customizing the appearance to match specific brand guidelines. ## Styling ### Theme Integration The Rate component uses the Bonyan theme for consistent styling. It leverages theme properties for colors, spacing, and typography to maintain a cohesive design across applications. ### Customization The component can be customized using styled-components. You can create custom styles by wrapping the component in a styled container or directly modifying the component's class names. ### Available Tokens - `colors.onSurface.highEmphasis` - `colors.onSurface.mediumEmphasis` - `spacing.token` - `typography.size.small` - `typography.size.medium` ### Styling Examples ```tsx Custom color for selected state: const CustomRate = styled(SatisfactionRate)` &.label--selected { color: ${props => props.theme.colors.custom.color1}; } `; ``` ## Best Practices - Always provide ARIA labels for accessibility. - Use meaningful labels that clearly indicate the rating options. - Ensure proper color contrast for both selected and unselected states. - Consider the component's size in relation to the overall layout. ## Accessibility - The component uses ARIA labels for screen reader support. - Keyboard navigation is supported for better accessibility. - Focus states are clearly indicated for better user interaction. - Color contrast is maintained for readability. ## Performance Considerations Tips for optimal Rate performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Rate component: ```tsx test('renders rate component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## RateBar Component **Version**: 0.1.10 **Props Count**: 24 **Documentation Source**: Generated from TypeScript + AI # RateBar Displays a rating visually with progress bars and stars, showing the distribution of ratings. ## Overview The RateBar component is used to visually represent rating distributions. It displays multiple progress bars for different rating categories, each with a percentage and a star icon. The component is highly customizable and integrates well with the Bonyan Design System's theme. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `bars` | bars property | Type: number[] | Required | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | | `rate` | Numeric value for rate | Type: number | | `rateCount` | Numeric value for rateCount | Type: number | Required | | `reviewCount` | Numeric value for reviewCount | Type: number | Required | ## Examples ### Basic Examples #### Basic RateBar Example A simple example showing the basic usage of RateBar with default props. ```tsx export const BasicRateBar = () => { return ( ); }; ``` #### Minimal RateBar Example A minimal example showing only the required props for the RateBar component. ```tsx export const MinimalRateBar = () => { return ( ); }; ``` ### Variant Examples #### Customized RateBar Variant An example showing a customized RateBar with a different progress bar color. ```tsx export const CustomizedRateBar = () => { return ( ); }; ``` ### Advanced Examples #### Advanced RateBar with Stacked Layout An advanced example showing multiple RateBars stacked vertically to display different rating categories. ```tsx export const AdvancedRateBar = () => { return ( ); }; ``` #### RateBar with Custom Layout An example showing RateBar integrated with other components in a custom layout. ```tsx export const CustomLayoutRateBar = () => { return ( Product Ratings: ); }; ``` ### Styling Examples #### Styled RateBar Example An example showing how to style the RateBar component using styled-components. ```tsx const CustomRateBar = styled(RateBar)` background-color: #f5f5f5; padding: 16px; border-radius: 8px; `; export const StyledRateBar = () => { return ( ); }; ``` ## Variants ### Progress Color Variant Changes the color of the progress bar to match different themes or states. **Configuration:** ```tsx { "progressColor": "#FF6B6B" } ``` **Example:** ```tsx CustomizedRateBar ``` ## Usage ### Basic Usage Import the RateBar component and use it by providing the required props: bars, rateCount, and reviewCount. Optional props like rate and progressColor can be used to further customize the component. ### Advanced Usage For more complex use cases, combine the RateBar with other components like Flex for layouts or Text for additional information. You can also use styled-components to create custom styles. ### Common Patterns - Using RateBar in a product listing to show average ratings. - Displaying detailed rating distributions on a product details page. - Customizing the appearance of RateBar to match different application themes. ## Styling ### Theme Integration The RateBar component uses the Bonyan Design System's theme for consistent styling. It leverages theme colors for progress bars, text, and icons, ensuring a cohesive look across applications. ### Customization The RateBar can be customized using styled-components. You can create custom styles by wrapping the component in a styled component and applying your own CSS. ### Available Tokens - `colors.onSurface.highEmphasis` - `colors.onSurface.mediumEmphasis` - `colors.outline.mediumEmphasis` - `spacing.sm` - `spacing.md` - `spacing.lg` ### Styling Examples ```tsx StyledRateBar ``` ```tsx CustomizedRateBar ``` ## Best Practices - Always provide meaningful ARIA labels for accessibility. - Use the progressColor prop to match the RateBar's progress with your application's theme. - Consider the context in which the RateBar is used to determine appropriate sizing and spacing. - Avoid over-customizing the component to maintain consistency with the design system. ## Accessibility - The RateBar component includes proper ARIA labels for screen reader support. - It uses keyboard navigation to ensure accessibility for all users. - The component maintains appropriate color contrast ratios for readability. - Focus management is handled to ensure the component can be accessed by all users. ## Performance Considerations Tips for optimal RateBar performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the RateBar component: ```tsx test('renders ratebar component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Row Component **Version**: 0.1.10 **Props Count**: 398 **Description**: The "Row" component from the Bonyan Design System likely represents a fundamental layout element. It arranges content horizontally, possibly with dividers and expandable sections. It supports various row types and styling options. **Documentation Source**: Generated from TypeScript + AI # Row A flexible layout component that arranges content horizontally with support for various densities, alignments, and expandable sections. ## Overview The Row component is a fundamental layout element that organizes content in a horizontal arrangement. It supports different densities, alignments, and can include expandable sections, making it versatile for various use cases. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `align` | align option | Type: "flex-end", "flex-start", "center"... | | `className` | String value for className | Type: string | | `clickable` | Click event handler | Type: true | false | | `dataTest` | Data attribute for testing purposes | Type: string | | `density` | density option | Type: "specious", "base", "narrow"... | | `description` | description property | Type: ReactNode | | `disabled` | Whether the component is disabled | Type: true | false | | `disPadding` | Boolean flag for disPadding | Type: true | false | | `divider` | divider property | Type: false | DIVIDER_VARIANT | | `dividerMiddleInset` | Numeric value for dividerMiddleInset | Type: number | | `ellipsis` | ellipsis option | Type: "title", "all", "description" | | `expandContent` | Some prop that is going to be removed in the future @deprecated This will be removed soon in favor of Row.Expand | Type: React element | | `headingSlot` | headingSlot component or element | Type: React element | | `id` | The unique identifier for the component | Type: string | | `isReversed` | Boolean flag for isReversed | Type: true | false | | `leftElement` | Some prop that is going to be removed in the future @deprecated This will be removed soon in favor of Row.Left | Type: React element | | `onClick` | Click event handler | Type: click handler | | `overline` | overline property | Type: ReactNode | | `rightElement` | Some prop that is going to be removed in the future @deprecated This will be removed soon in favor of Row.Right | Type: React element | | `title` | The title attribute for the component | Type: string | ## Examples ### Basic Examples #### Basic Row A simple row with basic content. ```tsx export const BasicRowExample = () => { return (

Basic Row Content

); }; ``` #### Row with Label A row containing a label element. ```tsx export const RowWithLabelExample = () => { return ( Row Label ); }; ``` #### Non-Clickable Row A row that is not clickable, useful for non-interactive content. ```tsx export const NonClickableRowExample = () => { return (

Non-Clickable Row Content

); }; ``` #### Row with Left Element A row with an icon on the left side. ```tsx export const RowWithLeftElementExample = () => { return ( }>

Row Content with Left Icon

); }; ``` ### Advanced Examples #### Clickable Row with Alert A clickable row that triggers an alert when clicked. ```tsx export const ClickableRowExample = () => { const handleClick = () => { alert('Row clicked!'); }; return (

Click me!

); }; ``` #### Expandable Row A row with expandable content that toggles visibility when clicked. ```tsx export const ExpandableRowExample = () => { const [isExpanded, setIsExpanded] = useState(false); return ( Expanded content with more information.

) : null} onClick={() => setIsExpanded(!isExpanded)} >

Expandable Row

); }; ``` ## Variants ### Density Variants Different density options for row height and padding. **Configuration:** ```tsx { "density": "narrower" } ``` **Example:** ```tsx export const DensityVariantsExample = () => { return (

Specious Density Base Density Narrow Density Narrower Density

); }; ``` ## Usage ### Basic Usage Import the Row component and use it to wrap your content. You can add optional props like density, align, and clickable to customize its appearance and behavior. ### Advanced Usage For more complex use cases, use the expandContent prop to add collapsible content or include interactive elements like buttons and icons. You can also customize the styling using styled-components. ### Common Patterns - Using Row as a layout container for other components. - Adding interactive elements on either side using leftElement and rightElement. - Implementing expandable content for detailed information. ## Styling ### Theme Integration The Row component uses the theme's surface colors for background and text, and spacing tokens for padding and gaps. ### Customization You can customize the Row component using styled-components. Here's an example: const CustomRow = styled(Row)` background-color: ${({ theme }) => theme.colors.primary[100]}; color: white; padding: ${spacing(2)}; `; ### Available Tokens - `horizontalPadding` - `verticalPadding` - `gap` - `elementWrapperSize` ### Styling Examples ```tsx Custom background color: const CustomRow = styled(Row)` background-color: #f0f0f0; `; ``` ```tsx Custom padding: const CustomRow = styled(Row)` padding: 16px; `; ``` ## Best Practices - Use appropriate density based on content size and importance. - Ensure proper color contrast for text and background. - Use expandable content sparingly and with clear visual cues. - Test row interactions for accessibility and responsiveness. ## Accessibility - The Row component uses appropriate ARIA roles for accessibility. - Ensure that interactive rows have proper keyboard navigation. - Provide alternative text for icons and images within the row. - Check color contrast between text and background for readability. ## Events and Handlers The Row component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal Row performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Row component: ```tsx test('renders row component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## RowContent Component **Version**: 0.1.10 **Props Count**: 9 **Description**: `RowContent` displays content within a row in the Bonyan Design System. It supports a title, description, overline, and heading. **Documentation Source**: Generated from TypeScript + AI # RowContent A flexible component for displaying row-based content with optional title, description, overline, and custom heading slot. ## Overview The RowContent component is designed to display structured content in a row layout. It supports various configurations including title, description, overline, and custom heading slots. The component also provides features like text overflow handling and layout reversal. ### Props | Prop | Description | |------|-------------| | `description` | description property | Type: ReactNode | | `disabled` | Whether the component is disabled | Type: true | false | | `ellipsis` | ellipsis option | Type: "title", "description", "all" | | `headingSlot` | headingSlot component or element | Type: React element | | `isReversed` | Boolean flag for isReversed | Type: true | false | | `overline` | overline property | Type: ReactNode | | `title` | The title attribute for the component | Type: string | ## Examples ### Basic Examples #### Basic Usage A simple example showing the basic usage of RowContent with title and description. ```tsx export const BasicRowContent = () => { return ( ); }; ``` ### Variant Examples #### Ellipsis Variants Demonstrates different ellipsis configurations for handling text overflow. ```tsx export const EllipsisVariants = () => { return (

); }; ``` ### Advanced Examples #### Advanced Configuration Shows a complex configuration with all possible props including overline, headingSlot, and reversed layout. ```tsx export const AdvancedRowContent = () => { return ( 👋} disabled isReversed ellipsis="title" /> ); }; ``` ### Styling Examples #### Custom Styling Example of customizing RowContent using styled-components. ```tsx const CustomRowContent = styled(RowContent)``; background-color: ${({ theme }) => theme.colors.surface.disabled}; padding: ${({ theme }) => theme.spacing.small}; ``; export const StyledRowContentExample = () => { return ( ); }; ``` ## Variants ### ellipsis-all Applies ellipsis to both title and description when text overflows. **Configuration:** ```tsx { "ellipsis": "all" } ``` **Example:** ```tsx RowContent with ellipsis="all" ``` ### ellipsis-title Applies ellipsis only to the title when it overflows. **Configuration:** ```tsx { "ellipsis": "title" } ``` **Example:** ```tsx RowContent with ellipsis="title" ``` ### ellipsis-description Applies ellipsis only to the description when it overflows. **Configuration:** ```tsx { "ellipsis": "description" } ``` **Example:** ```tsx RowContent with ellipsis="description" ``` ## Usage ### Basic Usage Import and use the RowContent component with basic props like title and description. ### Advanced Usage Combine multiple props like overline, headingSlot, and ellipsis for complex layouts. ### Common Patterns - Using RowContent in lists - Combining with other row components - Implementing interactive rows ## Styling ### Theme Integration The RowContent component uses the theme to derive colors, typography, and spacing. The colors are taken from the onSurface palette, and spacing is derived from the small and medium tokens. ### Customization RowContent can be customized using styled-components. You can create custom styles by wrapping the component in a styled component and applying your own styles. ### Available Tokens - `colors.onSurface.highEmphasis` - `colors.onSurface.disable` - `spacing.small` - `spacing.medium` - `typography.size.small` - `typography.size.tiny` ### Styling Examples ```tsx Custom padding and background color ``` ```tsx Custom font sizes and weights ``` ```tsx Custom colors for different states ``` ## Best Practices - Always provide meaningful content for title and description to ensure proper accessibility. - Use the ellipsis prop judiciously based on the expected content length. - Consider the disabled state for rows that should not be interactive. - Use isReversed when you need to reverse the layout for visual emphasis. ## Accessibility - The component uses proper ARIA roles and attributes for accessibility. - Text content is readable by screen readers. - Disabled state properly handles focus and interaction. - Color contrast meets accessibility standards. ## Performance Considerations Tips for optimal RowContent performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the RowContent component: ```tsx test('renders rowcontent component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Searchbox Component **Version**: 0.1.10 **Props Count**: 391 **Description**: The `Searchbox` component is a styled input field with search functionality, integrated with the Bonyan Design System. It includes a clear button, loading state, and theming, and leverages other core components. **Documentation Source**: Generated from TypeScript + AI # Searchbox A styled input field with search functionality, integrated with the Bonyan Design System. It includes a clear button, loading state, and theming, and leverages other core components. ## Overview The Searchbox component is a versatile search input that supports various visual styles, loading states, and customizations. It integrates seamlessly with the Bonyan Design System and provides features like right-aligned elements, density control, and accessibility support. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `defaultValue` | The default value | Type: string | | `density` | density option | Type: "base", "narrow", "base"... | | `id` | The unique identifier for the component | Type: string | | `loading` | Whether the component is in a loading state | Type: true | false | | `onChange` | Change event handler | Type: (value: string) => void | | `onLeftElementClick` | Click event handler | Type: (event?: MouseEvent) => void | | `persistSearchIcon` | Icon configuration | Type: true | false | | `placeholder` | The placeholder text | Type: string | | `rightElement` | rightElement component or element | Type: React element | | `variant` | The visual variant of the component | Type: "tonal", "elevated", "tonal"... | ## Examples ### Basic Examples #### Basic Searchbox A simple searchbox with a placeholder text. ```tsx export const BasicSearchbox = () => { const [value, setValue] = React.useState(''); const handleChange = (e: React.ChangeEvent) => { setValue(e.target.value); }; return ( ); }; ``` ### Advanced Examples #### Elevated Searchbar with Right Element An elevated searchbox with a right-aligned button showing the current location. ```tsx export const ElevatedSearchbar = () => { const rightAction = ( ); return ( ); }; ``` #### Searchbox with Loading State A searchbox showing the loading state with a progress bar. ```tsx export const LoadingSearchbox = () => { return ( ); }; ``` ### Styling Examples #### Custom Styled Searchbox A custom styled searchbox using styled-components for unique styling. ```tsx const CustomSearchbox = styled(Searchbox)({ '&.byn-search-box': { border: '2px solid #ff4081', background: '#f5f5f5', transition: 'all 0.3s ease', '&:focus-within': { border: '2px solid #ff4081', box-shadow: '0 0 0 2px rgba(255, 64, 129, 0.2)', }, }, }); export const CustomSearchboxExample = () => { return ( ); }; ``` ## Variants ### Tonal A subtle, tonal searchbox with a soft background color. **Configuration:** ```tsx { "variant": "tonal" } ``` **Example:** ```tsx export const TonalSearchbox = () => { return ( ); }; ``` ### Elevated A more prominent searchbox with an elevated shadow effect. **Configuration:** ```tsx { "variant": "elevated" } ``` **Example:** ```tsx export const ElevatedSearchbox = () => { return ( ); }; ``` ## Usage ### Basic Usage Import the Searchbox component and use it with a placeholder prop for basic search functionality. ### Advanced Usage Combine the Searchbox with other components like Button for right-aligned actions, and manage state for real-time search results. ### Common Patterns - Search filters with rightElement buttons. - Real-time search results display. - Location-based search with geolocation integration. ## Styling ### Theme Integration The Searchbox component uses the Bonyan Design System's theme for consistent styling. It leverages theme properties like colors, spacing, and typography to maintain a cohesive look and feel across applications. ### Customization You can customize the Searchbox using styled-components or by passing custom style props. The component's styling can be extended to fit specific design requirements while maintaining its core functionality. ### Available Tokens - `colors.surface.surfaceSoft` - `colors.surface.surfaceBase` - `spacing.md` - `spacing.sm` - `rounding.md` - `font.body.medium.regular` ### Styling Examples ```tsx Custom border color: const CustomSearchbox = styled(Searchbox)({ '&.byn-search-box': { border: '2px solid #ff4081', }, }); ``` ```tsx Custom focus state: const CustomSearchbox = styled(Searchbox)({ '&.byn-search-box:focus-within': { box-shadow: '0 0 0 2px rgba(255, 64, 129, 0.2)', }, }); ``` ## Best Practices - Always provide a meaningful placeholder text for better user experience. - Use the loading prop to indicate ongoing processes like search queries. - Implement proper keyboard navigation and focus management for accessibility. - Consider using the rightElement prop for additional interactive elements. - Regularly test the component with different densities and variants to ensure consistent behavior. ## Accessibility - The Searchbox component includes proper ARIA attributes for accessibility. - It supports keyboard navigation with arrow keys and Enter for actions. - The component ensures high contrast ratios between text and background for readability. - Focus states are clearly visible to indicate user interaction. - Screen reader compatibility is maintained through semantic HTML structure. ## Events and Handlers The Searchbox component supports various event handlers for user interactions: - `onLeftElementClick`: Event handler - `onChange`: Event handler ## Async Operations The Searchbox component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Form Integration The Searchbox component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal Searchbox performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Searchbox component: ```tsx test('renders searchbox component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## SectionSeparator Component **Version**: 0.1.10 **Props Count**: 21 **Description**: SectionSeparator creates visual separation between sections with a styled horizontal line. It supports customizable height and spacing. **Documentation Source**: Generated from TypeScript + AI # SectionSeparator A component that creates a visual separation between sections with a styled horizontal line. ## Overview SectionSeparator is a versatile component used to visually separate content sections. It supports customizable height and various spacing options, making it adaptable to different layouts and designs. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `height` | Height configuration | Type: number | | `id` | The unique identifier for the component | Type: string | ## Examples ### Basic Examples #### Basic Section Separator A simple horizontal line with default height (8px) and no additional spacing. ```tsx export const BasicSectionSeparator = () => { return (

); }; ``` ### Variant Examples #### Custom Height Section Separator A section separator with a custom height of 4px, demonstrating how to adjust the visual thickness. ```tsx export const CustomHeightSectionSeparator = () => { return (

); }; ``` ### Advanced Examples #### Section Separator with Margins Demonstrates how to add margins around the section separator to create spacing between sections. ```tsx export const SectionSeparatorWithMargins = () => { return (

); }; ``` ### Styling Examples #### Section Separator with Custom Styling Shows how to customize the section separator's appearance using styled-components. ```tsx const CustomStyledSectionSeparator = styled(SectionSeparator)` border-color: #666; opacity: 0.5; `; export const StyledSectionSeparator = () => { return (

); }; ``` ## Variants ### Thin Separator A section separator with reduced height for more subtle visual separation. **Configuration:** ```tsx { "height": 4 } ``` **Example:** ```tsx CustomHeightSectionSeparator ``` ### Thick Separator A section separator with increased height for more pronounced visual separation. **Configuration:** ```tsx { "height": 12 } ``` **Example:** ```tsx CustomHeightSectionSeparator ``` ## Usage ### Basic Usage Import the SectionSeparator component and use it within a div container to ensure proper visualization. ### Advanced Usage Customize the section separator's appearance and spacing to fit specific design requirements while maintaining consistency with your application's theme. ### Common Patterns - Using the section separator between form sections - Separating content blocks in a layout - Creating visual divisions in a list of items - Enhancing the visual hierarchy in a complex UI ## Styling ### Theme Integration The SectionSeparator component uses the theme's border properties for consistent styling across your application. You can customize the border color and opacity through the theme or directly via props. ### Customization To customize the SectionSeparator, you can use styled-components to override the border color, opacity, and other styles. Additionally, you can adjust the height and spacing props to match your design requirements. ### Available Tokens - `borderColor` - `borderWidth` - `opacity` - `spacing` ### Styling Examples ```tsx CustomStyledSectionSeparator ``` ```tsx SectionSeparatorWithMargins ``` ## Best Practices - Always consider the visual hierarchy when choosing the height of the section separator. - Use consistent spacing (m, mx, my) throughout your application for a cohesive look. - Avoid over-customizing the section separator; instead, rely on the theme's border styles for consistency. - Use the section separator to clearly delineate different sections of content without creating visual clutter. ## Accessibility - The SectionSeparator component does not interfere with screen reader functionality as it is a simple div element. - Ensure that the section separator's color contrast is sufficient for visual accessibility. - When using the section separator in interactive contexts, ensure that focus states are properly managed. - The component does not include ARIA roles by default; add them as needed based on your use case. ## Performance Considerations Tips for optimal SectionSeparator performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the SectionSeparator component: ```tsx test('renders sectionseparator component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## SegmentedControl Component **Version**: 0.1.10 **Props Count**: 27 **Description**: The SegmentedControl component provides a UI element for selecting a single option from a defined set, using styled buttons within the Bonyan Design System. **Documentation Source**: Generated from TypeScript + AI # SegmentedControl A segmented control component that allows users to select a single option from a set of options. ## Overview The SegmentedControl component provides a UI element for selecting a single option from a defined set, using styled buttons within the Bonyan Design System. It supports various densities, icons, and states to accommodate different use cases. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `className` | String value for className | Type: string | | `dataTest` | Data attribute for testing purposes | Type: string | | `density` | density option | Type: "base", "narrow", "base"... | Default: base | | `id` | The unique identifier for the component | Type: string | | `name` | The name attribute for form elements | Type: string | Required | | `onChange` | Change event handler | Type: (value: string | number) => void | | `onClick` | Click event handler | Type: () => void | | `options` | options property | Type: OptionType[] | Required | | `selected` | selected property | Type: string | number | ## Examples ### Basic Examples #### Basic Segmented Control A simple segmented control with three options. ```tsx const options = [ { label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }, { label: 'Option 3', value: '3' } ]; export const BasicSegmentedControl = () => { const [selected, setSelected] = React.useState('1'); return ( ); }; ``` #### Disabled Segmented Control A segmented control with disabled options. ```tsx const options = [ { label: 'Enabled', value: '1' }, { label: 'Disabled', value: '2', disabled: true }, { label: 'Enabled', value: '3' } ]; export const DisabledSegmentedControl = () => { const [selected, setSelected] = React.useState('1'); return ( ); }; ``` ### Variant Examples #### Narrow Density Segmented Control A segmented control using the narrow density option. ```tsx const options = [ { label: 'Small', value: '1' }, { label: 'Medium', value: '2' }, { label: 'Large', value: '3' } ]; export const NarrowDensitySegmentedControl = () => { const [selected, setSelected] = React.useState('1'); return ( ); }; ``` ### Advanced Examples #### Segmented Control with Icons A segmented control that includes both labels and icons. ```tsx const options = [ { label: 'Add', value: '1', icon: }, { label: 'Remove', value: '2', icon: }, { label: 'Edit', value: '3' } ]; export const SegmentedControlWithIcons = () => { const [selected, setSelected] = React.useState('1'); return ( ); }; ``` #### Advanced Segmented Control A complex example with mixed options, including icons and different colors. ```tsx const options = [ { label: 'Add', value: '1', icon: , color: 'positive' }, { label: 'Remove', value: '2', icon: , color: 'negative' }, { label: 'Edit', value: '3', icon: } ]; export const AdvancedSegmentedControl = () => { const [selected, setSelected] = React.useState('1'); return ( ); }; ``` ### Styling Examples #### Custom Styled Segmented Control An example of customizing the segmented control's appearance using styled-components. ```tsx const CustomSegmentedControl = styled(SegmentedControl)({ '& .byn-segmented-control__button-container': { background: '#f0f0f0', '&.selected': { background: '#007bff', color: 'white' } } }); const options = [ { label: 'Custom 1', value: '1' }, { label: 'Custom 2', value: '2' }, { label: 'Custom 3', value: '3' } ]; export const CustomStyledSegmentedControl = () => { const [selected, setSelected] = React.useState('1'); return ( ); }; ``` ## Variants ### Density The SegmentedControl supports different densities to accommodate different layouts. **Configuration:** ```tsx { "density": "base | narrow" } ``` **Example:** ```tsx export const DensityExample = () => { const [selected, setSelected] = React.useState('1'); return (

); }; ``` ## Usage ### Basic Usage Import the SegmentedControl component and use it with an array of options. Each option should have a label and value. Use the selected prop to control the currently selected option and the onChange prop to handle selection changes. ### Advanced Usage For more complex use cases, you can customize the appearance using styled-components, add icons to options, and use different densities. You can also mix and match different options with varying properties like disabled states and colors. ### Common Patterns - Using the segmented control in a form to select between different options. - Combining with other components like Text to create a filter interface. - Implementing the segmented control in a header to switch between different views. ## Styling ### Theme Integration The SegmentedControl component uses the Bonyan Design System theme to style its appearance. The theme provides color, spacing, and typography tokens that can be customized. ### Customization You can customize the SegmentedControl component using styled-components. Here's an example of how to create a custom styled version: const CustomSegmentedControl = styled(SegmentedControl)({ '& .byn-segmented-control__button-container': { background: '#f0f0f0', '&.selected': { background: '#007bff', color: 'white' } } }); ### Available Tokens - `colors.primary` - `colors.secondary` - `colors.success` - `colors.error` - `spacing.base` - `spacing.narrow` - `typography.label` ### Styling Examples ```tsx Customizing the background and text colors: const CustomSegmentedControl = styled(SegmentedControl)({ '& .byn-segmented-control__button-container': { background: '#f0f0f0', '&.selected': { background: '#007bff', color: 'white' } } }); ``` ```tsx Adjusting the spacing: const CustomSegmentedControl = styled(SegmentedControl)({ '& .byn-segmented-control__button': { margin: '0 8px' } }); ``` ## Best Practices - Always provide meaningful labels for options to ensure accessibility. - Use the density prop to control the size of the segmented control based on the context. - Consider using icons to supplement labels for better visual understanding. - Ensure that the onChange handler is properly implemented to handle state changes. - Avoid using too many options in a single segmented control for better usability. ## Accessibility - The SegmentedControl component uses proper ARIA roles and attributes to ensure accessibility. - Each button in the segmented control is keyboard navigable and follows the WAI-ARIA practices. - The component provides visual feedback for selected and disabled states. - The component supports screen readers by providing appropriate labels and descriptions. ## Events and Handlers The SegmentedControl component supports various event handlers for user interactions: - `onChange`: Event handler - `onClick`: Event handler ## Form Integration The SegmentedControl component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal SegmentedControl performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the SegmentedControl component: ```tsx test('renders segmentedcontrol component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## ServiceIcon Component **Version**: 0.1.10 **Props Count**: 378 **Description**: The `ServiceIcon` component in Bonyan Design System displays a service icon using an image, customizable by size, base URL, and other properties. **Documentation Source**: Generated from TypeScript + AI # ServiceIcon The ServiceIcon component is part of the Bonyan Design System. ## Overview ServiceIcon provides a flexible and customizable interface for user interactions. ### Props | Prop | Description | |------|-------------| | `as` | You can pass a Nextjs Image component in this prop so the render component will change: | Type: ElementType | | `baseUrl` | String value for baseUrl | Type: string | | `disabledFallback` | Disabled state | Type: true | false | | `disabledPlaceholder` | Disabled state | Type: true | false | | `fallbackDirection` | fallbackDirection option | Type: "horizontal", "vertical" | | `fallbackSize` | Size configuration | Type: "base", "narrow", "narrower"... | | `fallbackVariant` | Visual variant | Type: "logotype", "sign" | | `fill` | Boolean flag for fill | Type: true | false | | `height` | Height configuration | Type: string | number | | `iconFallback` | Icon configuration | Type: true | false | | `isDisabled` | Disabled state | Type: true | false | | `loader` | loader property | Type: (url: { src: string; quality: number; width: number; }) => string | | `loading` | Whether the component is in a loading state | Type: "lazy", "eager" | | `name` | The name attribute for form elements | Type: string | | `onLoadCallback` | onLoadCallback property | Type: () => void | | `placeholderColor` | Color configuration | Type: string | | `priority` | Boolean flag for priority | Type: true | false | | `quality` | Numeric value for quality | Type: number | | `size` | The size variant of the component | Type: string | number | | `sizes` | Size configuration | Type: string | | `width` | Width configuration | Type: string | number | | `wrapperStyle` | wrapperStyle property | Type: CSSProperties | ## Examples ### Basic Examples #### Default Default example from Storybook - based on Storybook story ```tsx export const Default = () => { return ( Default ); }; // Export story metadata for dynamic usage export const DefaultMeta = { title: "Default", component: Default, args: {}, category: "basic" }; ``` ## Usage ### Basic Usage Basic usage of ServiceIcon ### Advanced Usage Advanced usage patterns for ServiceIcon ### Common Patterns - Standard implementation - Custom styling - Event handling ## Styling ### Theme Integration Integrates with Bonyan Design System theme tokens ### Customization Can be customized using styled() function ### Available Tokens - `primary` - `secondary` - `success` - `error` - `warning` ## Best Practices - Use semantic props for better accessibility - Follow design system guidelines - Consider responsive behavior ## Accessibility - Supports keyboard navigation - ARIA attributes included - Screen reader compatible ## Events and Handlers The ServiceIcon component supports various event handlers for user interactions: - `onLoadCallback`: Event handler ## Async Operations The ServiceIcon component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Performance Considerations Tips for optimal ServiceIcon performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the ServiceIcon component: ```tsx test('renders serviceicon component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## SheetHeader Component **Version**: 0.1.10 **Props Count**: 5 **Description**: The `SheetHeader` component from Bonyan Design System renders the header for a sheet (modal). It includes a title, subtitle, actions, and optionally a drag handle. **Documentation Source**: Generated from TypeScript + AI # SheetHeader The SheetHeader component is a flexible header for sheets (modals) that supports titles, subtitles, and actions on both sides. It also includes an optional drag handle for repositioning. ## Overview The SheetHeader component provides a consistent and accessible way to display headers in modal sheets. It supports various configurations, including drag handles and action buttons, making it suitable for different use cases. ### Props | Prop | Description | |------|-------------| | `leftAction` | leftAction component or element | Type: React element | | `rightAction` | rightAction component or element | Type: React element | | `showDragHandle` | Boolean flag for showDragHandle | Type: true | false | | `subtitle` | String value for subtitle | Type: string | | `title` | The title attribute for the component | Type: ReactNode | ## Examples ### Basic Examples #### Basic Sheet Header A simple sheet header with a title and subtitle. ```tsx export const BasicSheetHeader = () => { return ( ); }; ``` ### Variant Examples #### Minimal Sheet Header A minimal sheet header with no drag handle and basic actions. ```tsx export const MinimalSheetHeader = () => { return ( OK} showDragHandle={false} /> ); }; ``` ### Advanced Examples #### Sheet Header with Actions A sheet header with action buttons on both sides. ```tsx export const SheetHeaderWithActions = () => { return ( Cancel} rightAction={} /> ); }; ``` #### Sheet Header with Drag Handle A sheet header with a visible drag handle and actions. ```tsx export const SheetHeaderWithDragHandle = () => { return ( Close} rightAction={} /> ); }; ``` ### Styling Examples #### Custom Styled Sheet Header A sheet header with custom styling using styled-components. ```tsx const CustomSheetHeader = styled(SheetHeader)` &.byn-sheet-header { &__title { color: ${({ theme }) => theme.colors.primary}; } &__subtitle { color: ${({ theme }) => theme.colors.secondary}; } &.byn-sheet-header__drag-handle { background-color: ${({ theme }) => theme.colors.outline.highEmphasis}; } } `; export const CustomSheetHeaderExample = () => { return ( ); }; ``` ## Variants ### With Drag Handle Includes a drag handle for repositioning the sheet. **Configuration:** ```tsx "{ showDragHandle: true }" ``` **Example:** ```tsx SheetHeaderWithDragHandle ``` ### Without Drag Handle Hides the drag handle for a cleaner look. **Configuration:** ```tsx "{ showDragHandle: false }" ``` **Example:** ```tsx MinimalSheetHeader ``` ### With Actions Includes action buttons on either side. **Configuration:** ```tsx "{ leftAction: , rightAction: }" ``` **Example:** ```tsx SheetHeaderWithActions ``` ## Usage ### Basic Usage Import the SheetHeader component and provide a title. Optionally add a subtitle and actions as needed. ### Advanced Usage Customize the header with specific styling using styled-components. Add drag functionality and multiple actions for complex use cases. ### Common Patterns - Using the drag handle for repositioning modals - Adding cancel and confirm buttons - Customizing colors for brand consistency ## Styling ### Theme Integration The SheetHeader component uses the theme's color and spacing tokens. The title and subtitle colors can be customized through theme overrides. ### Customization You can customize the appearance of the SheetHeader using styled-components. Target specific classes like .byn-sheet-header__title to modify styles. ### Available Tokens - `colors.primary` - `colors.secondary` - `colors.onSurface.mediumEmphasis` - `spacing.lg` - `spacing.md` - `spacing.sm` ### Styling Examples ```tsx Customizing the title color: const CustomSheetHeader = styled(SheetHeader)` &.byn-sheet-header__title { color: ${({ theme }) => theme.colors.primary}; } `; ``` ## Best Practices - Always provide meaningful content for the title and subtitle to ensure proper context. - Use action buttons sparingly and only when necessary to maintain a clean interface. - Consider accessibility when customizing colors to ensure proper contrast ratios. - Avoid overloading the header with too many actions; consider alternative layouts if needed. ## Accessibility - The component uses proper ARIA roles for semantic HTML structure. - Action buttons are keyboard-navigable and support focus states. - The drag handle is visually distinct and supports touch interactions. - Color contrast between text and background meets accessibility standards. ## Performance Considerations Tips for optimal SheetHeader performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the SheetHeader component: ```tsx test('renders sheetheader component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Skeleton Component **Version**: Unknown **Props Count**: 269 **Documentation Source**: Generated from TypeScript + AI # Skeleton A Skeleton component used to display placeholders while content is loading. ## Overview The Skeleton component provides a visual representation of content while it is being loaded. It supports three variants: Object, Rectangle, and Text, each with customizable sizes and responsive behavior. ### Props | Prop | Description | |------|-------------| | `size` | The size variant of the component | Type: number | Required | ## Examples ### Basic Examples #### Basic Usage Basic examples of each skeleton variant with default dimensions. ```tsx export const BasicSkeletonExample = () => { return (

); }; ``` ### Advanced Examples #### Advanced Usage Combining different skeleton components to create a loading card layout. ```tsx export const AdvancedSkeletonExample = () => { return (

); }; ``` #### Responsive Skeletons Using fullWidth for responsive text and rectangle skeletons. ```tsx export const ResponsiveSkeletonExample = () => { return (

); }; ``` #### Loading State Using skeletons to represent loading states in a real-world interface. ```tsx export const LoadingStateSkeletonExample = () => { return (

); }; ``` ### Styling Examples #### Custom Sizes Demonstrating different size variations for each skeleton type. ```tsx export const CustomSizeSkeletonExample = () => { return (

); }; ``` #### Custom Styling Customizing the skeleton's appearance using styled-components. ```tsx const CustomObjectSkeleton = styled(ObjectSkeleton)` background-color: ${({ theme }) => theme.colors.primary.primary500}; border-radius: 8px; `; const CustomRectangleSkeleton = styled(RectangleSkeleton)` background-color: ${({ theme }) => theme.colors.secondary.secondary500}; border-radius: 12px; `; const CustomTextSkeleton = styled(TextSkeleton)` background-color: ${({ theme }) => theme.colors.tertiary.tertiary500}; border-radius: 4px; `; export const CustomStylingSkeletonExample = () => { return (

); }; ``` ## Variants ### ObjectSkeleton A circular skeleton used for avatars or icons. **Configuration:** ```tsx { "size": "number" } ``` **Example:** ```tsx ObjectSkeleton size={24} ``` ### RectangleSkeleton A rectangular skeleton used for images or blocks of content. **Configuration:** ```tsx { "width": "number | string", "height": "number", "fullWidth": "boolean" } ``` **Example:** ```tsx RectangleSkeleton width={100} height={100} ``` ### TextSkeleton A text-line skeleton used for text blocks. **Configuration:** ```tsx { "width": "number | string", "height": "number", "fullWidth": "boolean" } ``` **Example:** ```tsx TextSkeleton width={176} height={16} ``` ## Usage ### Basic Usage Import the Skeleton component and use it to represent loading content. Choose the appropriate variant based on the content type. ### Advanced Usage Combine multiple skeleton components to create complex loading states. Customize their sizes and responsive behavior to match your layout. ### Common Patterns - Loading states for images, avatars, and text content - Responsive layouts during data fetching - Custom themed placeholders for brand consistency ## Styling ### Theme Integration The Skeleton component uses the theme's surface colors for its background and animation. ### Customization You can customize the Skeleton component's appearance using styled-components. You can modify properties like background color, border radius, and animation. ### Available Tokens - `surface.surfaceDim` - `primary.primary500` - `secondary.secondary500` - `tertiary.tertiary500` ### Styling Examples ```tsx const CustomSkeleton = styled(RectangleSkeleton)` background-color: ${({ theme }) => theme.colors.primary.primary500}; border-radius: 8px; `; ``` ## Best Practices - Use the appropriate skeleton variant based on the content you're loading (Object for avatars, Rectangle for images, Text for text). - Implement responsive behavior using the fullWidth prop for text and rectangle skeletons. - Customize the skeleton's appearance to match your application's theme and design language. - Ensure proper accessibility by providing ARIA labels for assistive technologies. ## Accessibility - The Skeleton component should be used in conjunction with loading states to inform users of content being loaded. - Provide ARIA labels to describe the content being loaded for screen readers. - Ensure proper color contrast for accessibility, especially when customizing colors. - The Skeleton component does not interfere with keyboard navigation as it is a visual placeholder. ## Performance Considerations Tips for optimal Skeleton performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Skeleton component: ```tsx test('renders skeleton component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## SlideIndicator Component **Version**: 0.1.10 **Props Count**: 6 **Documentation Source**: Generated from TypeScript + AI # SlideIndicator A component to indicate the current position in a sequence of slides or steps. ## Overview The SlideIndicator component provides a visual representation of the current slide or step in a sequence. It supports different variants, sizes, and dynamic behavior to suit various use cases. ### Props | Prop | Description | |------|-------------| | `count` | Numeric value for count | Type: number | Required | | `dynamicTimeout` | Numeric value for dynamicTimeout | Type: number | | `selectedIndex` | Numeric value for selectedIndex | Type: number | Required | | `size` | The size variant of the component | Type: "small", "large", "small"... | | `type` | The type attribute for the component | Type: "static", "dynamic", "static"... | | `variant` | The visual variant of the component | Type: "flat", "elevated", "flat"... | ## Examples ### Basic Examples #### Basic Slide Indicator A basic example showing a static slide indicator with 5 slides. ```tsx export const BasicSlideIndicator = () => { return ( ); }; ``` ### Variant Examples #### Small Elevated Slide Indicator A small elevated slide indicator with 7 slides, showing the third slide selected. ```tsx export const SmallElevatedSlideIndicator = () => { return ( ); }; ``` ### Advanced Examples #### Dynamic Slide Indicator A dynamic slide indicator that automatically updates every 3 seconds. ```tsx export const DynamicSlideIndicator = () => { const [selectedIndex, setSelectedIndex] = useState(0); const count = 4; useEffect(() => { const interval = setInterval(() => { setSelectedIndex((prev) => (prev + 1) % count); }, 3000); return () => clearInterval(interval); }, []); return ( ); }; ``` ### Styling Examples #### Custom Styled Slide Indicator An example with custom styling using styled-components. ```tsx const CustomSlideIndicator = styled(SlideIndicator)` &.elevated { background-color: rgba(0, 0, 0, 0.1); padding: 8px; border-radius: 16px; } &.selected { background-color: #fff; } `; export const CustomStyledSlideIndicator = () => { return ( ); }; ``` ## Variants ### Elevated An elevated variant with a background and shadow. **Configuration:** ```tsx { "variant": "elevated" } ``` **Example:** ```tsx export const ElevatedVariant = () => ( ); ``` ### Flat A flat variant without background or shadow. **Configuration:** ```tsx { "variant": "flat" } ``` **Example:** ```tsx export const FlatVariant = () => ( ); ``` ## Usage ### Basic Usage Import the component and use it with the required props `count` and `selectedIndex`. The component will display dots indicating the current slide. ### Advanced Usage For dynamic behavior, set the `type` prop to 'dynamic' and provide a `dynamicTimeout` value. You can also customize the appearance using styled-components. ### Common Patterns - Use with a carousel component to indicate the current slide. - Implement dynamic updates for automatic slide transitions. - Customize the styling to match your application's theme. ## Styling ### Theme Integration The SlideIndicator component uses the theme's colors for its styling. The dots' colors are derived from the theme's inverse surface colors. ### Customization You can customize the appearance of the SlideIndicator using styled-components or by passing custom styles. The component accepts className and style props for further customization. ### Available Tokens - `indicatorDot.size.small` - `indicatorDot.size.large` - `indicatorDot.sequenceSize.small` - `indicatorDot.sequenceSize.large` - `slideIndicatorWrapper.gap` ### Styling Examples ```tsx const CustomSlideIndicator = styled(SlideIndicator)` &.elevated { background-color: rgba(0, 0, 0, 0.1); padding: 8px; border-radius: 16px; } &.selected { background-color: #fff; } `; ``` ## Best Practices - Always provide the required props `count` and `selectedIndex`. - Use the `dynamicTimeout` prop carefully to avoid performance issues. - Ensure good color contrast for accessibility. - Consider the component's size in relation to the container. ## Accessibility - The component uses proper ARIA roles and attributes for accessibility. - Keyboard navigation is supported through the component's props. - The component is screen reader compatible. - Ensure that the color contrast between dots and background is sufficient. ## Performance Considerations Tips for optimal SlideIndicator performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the SlideIndicator component: ```tsx test('renders slideindicator component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Slider Component **Version**: 0.1.10 **Props Count**: 370 **Documentation Source**: Generated from TypeScript + AI # Slider A responsive and customizable slider component for displaying content in a carousel-like format. Built on top of Keen Slider, it supports features like looping, autoplay, and slide indicators. ## Overview The Slider component provides a modern and flexible way to display multiple items in a sliding layout. It supports various configurations such as automatic playback, looped slides, and customizable indicators. The component is designed to be accessible and performs well with large numbers of slides. ### Props | Prop | Description | |------|-------------| | `autoPlay` | Boolean flag for autoPlay | Type: true | false | | `indicator` | indicator property | Type: boolean | SliderIndicatorType | | `interval` | Numeric value for interval | Type: number | | `keenSliderProps` | keenSliderProps property | Type: Omit | | `loop` | Boolean flag for loop | Type: true | false | | `onSlideChange` | Change event handler | Type: (index: number) => void | ## Examples ### Basic Examples #### Basic Slider A simple slider with default settings, showing 6 slides with numbers. ```tsx export const BasicSlider = () => { return ( {[1, 2, 3, 4, 5, 6].map((slide) => (

{slide}

))} ); }; ``` #### Slider with Indicators A slider with visible indicators to show the current slide position. ```tsx export const SliderWithIndicators = () => { return ( {[1, 2, 3, 4, 5, 6].map((slide) => (

{slide}

))} ); }; ``` ### Advanced Examples #### Autoplay Slider A slider that automatically advances slides every 3 seconds with loop enabled. ```tsx export const AutoplaySlider = () => { return ( {[1, 2, 3, 4, 5, 6].map((slide) => (

{slide}

))} ); }; ``` #### Custom Slide Content A slider with custom content including images and text. ```tsx export const CustomContentSlider = () => { return ( console.log(`Slide changed to ${index}`)} >

First Slide

Welcome to our slider!

Third Slide

Explore more features!

); }; ``` ### Styling Examples #### Styled Slider A slider with custom styling using styled-components. ```tsx const CustomSlider = styled(Slider)` & .byn-slider { &__slide { background: #333; color: white; padding: 20px; } &__indicator { background: #fff; width: 12px; height: 12px; margin: 0 5px; } } `; export const StyledSliderExample = () => { return ( {[1, 2, 3, 4, 5, 6].map((slide) => (

{slide}

))} ); }; ``` ## Usage ### Basic Usage Import the Slider component and use it by wrapping your slide content within it. The basic usage includes creating multiple child div elements as slides. ### Advanced Usage For more complex scenarios, utilize props like `loop`, `autoPlay`, and `indicator` to create custom behaviors. You can also use the `onSlideChange` callback to handle slide transitions. ### Common Patterns - Creating a hero section with autoplay - Displaying product cards in an e-commerce layout - Building a carousel for image galleries - Implementing a wizard with multiple steps ## Styling ### Theme Integration The Slider component uses the Bonyan Design System theme for consistent styling. It leverages theme properties for colors, spacing, and typography to maintain a cohesive look across applications. ### Customization The Slider can be customized using styled-components. You can target specific parts of the slider using class names like .byn-slider__slide for slides and .byn-slider__indicator for indicators. ### Available Tokens - `colors.primary` - `colors.secondary` - `colors.neutral` - `spacing.medium` - `spacing.large` - `typography.body1` ### Styling Examples ```tsx Customizing slide background color: const CustomSlider = styled(Slider)` & .byn-slider__slide { background: ${props => props.theme.colors.primary}; } `; ``` ```tsx Styling indicators: const StyledIndicatorSlider = styled(Slider)` & .byn-slider__indicator { width: 10px; height: 10px; background: ${props => props.theme.colors.secondary}; } `; ``` ## Best Practices - Always provide meaningful content for slides, including proper ARIA attributes for accessibility. - Use the `loop` prop carefully as it may affect performance with many slides. - Implement slide content with proper semantic HTML for better accessibility. - Optimize images used in slides to improve loading times and performance. ## Accessibility - The Slider component provides ARIA attributes for proper screen reader support. - Slides are navigable using keyboard arrow keys for better accessibility. - Indicators are properly labeled and focusable for screen reader users. - Ensure all images in slides have appropriate `alt` text for accessibility. ## Events and Handlers The Slider component supports various event handlers for user interactions: - `onSlideChange`: Event handler ## Performance Considerations Tips for optimal Slider performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Slider component: ```tsx test('renders slider component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Stepper Component **Version**: 0.1.10 **Props Count**: 32 **Description**: The Stepper component from Bonyan Design System allows users to increment/decrement a value with visual feedback, including a progress bar. **Documentation Source**: Generated from TypeScript + AI # Stepper A Stepper component allows users to increment or decrement a value with visual feedback, including a progress bar. ## Overview The Stepper component provides a user interface to increment or decrement a value. It supports various states, sizes, and configurations to suit different use cases. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `className` | String value for className | Type: string | | `dataTest` | Data attribute for testing purposes | Type: string | | `disabled` | Whether the component is disabled | Type: boolean | { increase: boolean; decrease: boolean; } | | `elevated` | Whether the component has elevated styling | Type: true | false | | `id` | The unique identifier for the component | Type: string | | `loading` | Whether the component is in a loading state | Type: true | false | | `minusButtonDataTest` | String value for minusButtonDataTest | Type: string | | `onChange` | Change event handler | Type: (value: number, type?: "increase" | "decrease") => void | | `onClickWhenDisabled` | Click event handler when component is disabled | Type: click handler | | `onlyPlusOnZero` | Boolean flag for onlyPlusOnZero | Type: true | false | | `plusButtonDataTest` | String value for plusButtonDataTest | Type: string | | `rounded` | Boolean flag for rounded | Type: true | false | | `size` | The size variant of the component | Type: "base", "large", "base"... | | `value` | The current value | Type: number | Required | ## Examples ### Basic Examples #### Basic Stepper Usage A simple stepper that allows incrementing and decrementing values. ```tsx export const BasicStepper = () => { const [value, setValue] = useState(0); const onChange = (newValue: number) => { setValue(newValue); }; return ( ); }; ``` #### Elevated Stepper A stepper with elevation effect for better visual hierarchy. ```tsx export const ElevatedStepper = () => { const [value, setValue] = useState(0); const onChange = (newValue: number) => { setValue(newValue); }; return ( ); }; ``` ### Variant Examples #### Stepper with Different Sizes Demonstrates small and large stepper sizes. ```tsx export const SizedStepper = () => { const [smallValue, setSmallValue] = useState(0); const [largeValue, setLargeValue] = useState(0); const onChange = (value: number, isLarge: boolean) => { if (isLarge) { setLargeValue(value); } else { setSmallValue(value); } }; return (

Small Stepper onChange(v, false)} dataTest="small-stepper" />

Large Stepper onChange(v, true)} dataTest="large-stepper" />

); }; ``` ### Advanced Examples #### Loading State Stepper A stepper that shows a loading state when operations are pending. ```tsx export const LoadingStepper = () => { const [value, setValue] = useState(0); const [isLoading, setIsLoading] = useState(false); const onChange = (newValue: number) => { setIsLoading(true); setTimeout(() => { setValue(newValue); setIsLoading(false); }, 1000); }; return ( ); }; ``` #### Disabled Stepper Shows how to disable the stepper or specific buttons. ```tsx export const DisabledStepper = () => { const [value, setValue] = useState(0); const onClickWhenDisabled = () => { alert('Stepper is disabled!'); }; return (

Fully Disabled

Only Decrease Disabled

); }; ``` #### Advanced Stepper Configuration Demonstrates various stepper configurations including rounded corners and custom styling. ```tsx export const AdvancedStepper = () => { const [value, setValue] = useState(0); const onChange = (newValue: number) => { setValue(newValue); }; return (

Rounded Stepper

Only Plus on Zero

); }; ``` ## Variants ### Size Variants The stepper is available in two sizes: base and large. **Configuration:** ```tsx { "size": "base | large" } ``` **Example:** ```tsx SizedStepper ``` ### Elevation Variant The stepper can be displayed with or without elevation. **Configuration:** ```tsx { "elevated": "boolean" } ``` **Example:** ```tsx ElevatedStepper ``` ### Rounded Variant The stepper can have rounded corners for a different visual appearance. **Configuration:** ```tsx { "rounded": "boolean" } ``` **Example:** ```tsx AdvancedStepper ``` ## Usage ### Basic Usage Import the Stepper component and use it with the required `value` and `onChange` props. ### Advanced Usage Configure the Stepper with additional props like `elevated`, `rounded`, and `disabled` for more complex use cases. ### Common Patterns - Quantity selection in e-commerce applications - Rating systems - Form input for numerical values ## Styling ### Theme Integration The Stepper component uses the following theme tokens: - `dimension` for size-related measurements - `textWidth` for content width - `surface` for background colors - `colors` for various states ### Customization You can customize the Stepper component using styled-components. Here's an example: ```jsx const CustomStepper = styled(Stepper)` &.stepper--base { background-color: ${({ theme }) => theme.colors.customColor}; } `; ``` ### Available Tokens - `dimension` - `textWidth` - `surface` - `colors` ### Styling Examples ```tsx CustomStepper styled component example ``` ## Best Practices - Always provide an `onChange` handler to respond to value changes. - Use the `disabled` prop to control user interaction appropriately. - Consider accessibility by providing proper ARIA attributes and keyboard navigation. - Use meaningful data attributes for testing purposes. ## Accessibility - The Stepper component follows keyboard navigation standards. - Proper ARIA attributes are provided for screen reader compatibility. - Focus management is handled to ensure accessible interaction. - Color contrast is maintained for visual accessibility. ## Events and Handlers The Stepper component supports various event handlers for user interactions: - `onChange`: Event handler - `onClickWhenDisabled`: Event handler - `onlyPlusOnZero`: Event handler ## Async Operations The Stepper component handles asynchronous operations gracefully: - Loading states are managed automatically - Error handling is built-in - Proper loading indicators are displayed ## Form Integration The Stepper component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal Stepper performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Stepper component: ```tsx test('renders stepper component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## StickyHeader Component **Version**: Unknown **Props Count**: 6 **Documentation Source**: Generated from TypeScript + AI # StickyHeader A component that creates a sticky header with navigation, visually highlighting active sections while scrolling. ## Overview The StickyHeader component provides a sticky navigation header that highlights active sections as the user scrolls. It supports various features like dynamic content loading, custom actions, and integration with other components. ### Props | Prop | Description | |------|-------------| | `badge` | badge component or element | Type: React element | | `disabled` | Whether the component is disabled | Type: true | false | | `eventKey` | String value for eventKey | Type: string | Required | | `icon` | Icon to display | Type: React element | | `label` | The label text for the component | Type: string | | `onClick` | Click event handler | Type: () => void | ## Examples ### Basic Examples #### Basic Sticky Header A simple example of StickyHeader with multiple sections. ```tsx export const BasicStickyHeaderExample = () => { return (

Content for Section 1

Content for Section 2

Content for Section 3

); }; ``` #### Sticky Header with Action Example of StickyHeader with an action button. ```tsx export const StickyHeaderWithActionExample = () => { const searchIconButton = ( } color="neutral-medium" size="large" variant="standard" /> ); return (

Content for Section 1

Content for Section 2

); }; ``` ### Advanced Examples #### Dynamic Content Loading Example demonstrating dynamic content loading with StickyHeader. ```tsx export const DynamicContentLoadingExample = () => { const [sections, setSections] = useState([ { id: 'section1', label: 'Section 1' }, { id: 'section2', label: 'Section 2' }, { id: 'section3', label: 'Section 3' } ]); const loadMoreSections = () => { setSections(prev => [...prev, { id: `section${prev.length + 1}`, label: `Section ${prev.length + 1}` }]); }; return ( { if (activeSection === sections.length) { loadMoreSections(); } }} > {sections.map((section) => (

Content for {section.label}

))} ); }; ``` #### Sticky Header with Tabs Example combining StickyHeader with Tabs component for a tabbed interface. ```tsx export const StickyHeaderWithTabsExample = () => { return ( Tab 1 Content 1 Tab 1 Content 2 Tab 2 Content 1 Tab 2 Content 2 ); }; ``` ### Styling Examples #### Custom Styling Example Example demonstrating custom styling of StickyHeader using styled-components. ```tsx const CustomStickyHeader = styled(StickyHeader)` &.byn-sticky-header { background-color: #f0f0f0; padding: 16px; border-radius: 8px; } `; export const CustomStylingExample = () => { return (

Content for Section 1

Content for Section 2

); }; ``` ## Usage ### Basic Usage Import the component and use it with StickyHeaderItem components as children. Set the eventKey and label for each section. ### Advanced Usage Implement dynamic content loading by listening to the onChange event. Integrate with other components for complex layouts. ### Common Patterns - Dynamic content loading - Tabbed interfaces - Custom styling - Accessibility features ## Styling ### Theme Integration The StickyHeader component uses theme tokens for consistent styling. The background color, text color, and other visual properties are derived from the theme. ### Customization You can customize the appearance of StickyHeader using styled-components. Create a custom styled component by extending the base StickyHeader component and applying your own styles. ### Available Tokens - `background-color` - `text-color` - `border-radius` - `padding` - `margin` ### Styling Examples ```tsx Custom background color: `background-color: #f0f0f0;` ``` ```tsx Custom text color: `color: #333;` ``` ```tsx Custom padding: `padding: 16px;` ``` ## Best Practices - Use meaningful labels for sections to improve accessibility. - Implement dynamic content loading for large datasets. - Combine with other components like Tabs for complex layouts. - Ensure proper spacing and padding for content readability. ## Accessibility - The component provides ARIA labels for screen readers. - Sections are properly marked with ARIA roles. - Keyboard navigation is supported for accessibility. - Focus management ensures proper navigation for users. ## Events and Handlers The StickyHeader component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal StickyHeader performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the StickyHeader component: ```tsx test('renders stickyheader component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Tab Component **Version**: 0.1.10 **Props Count**: 6 **Documentation Source**: Generated from TypeScript + AI # Tab A flexible tab component for creating tabbed interfaces. Handles click events and supports various configurations including icons, badges, and different states. ## Overview The Tab component is used to create tabbed interfaces. It works in conjunction with the Tabs component to manage the active state and content display. Tabs can be customized with icons, badges, and different visual states to suit various design needs. ### Props | Prop | Description | |------|-------------| | `badge` | badge component or element | Type: React element | | `disabled` | Whether the component is disabled | Type: true | false | | `eventKey` | String value for eventKey | Type: string | Required | | `icon` | Icon to display | Type: React element | | `label` | The label text for the component | Type: string | | `onClick` | Click event handler | Type: () => void | ## Examples ### Basic Examples #### Basic Tabs A simple implementation of Tabs with two Tab components. Demonstrates the basic structure and functionality. ```tsx export const BasicTabsExample = () => { const [activeKey, setActiveKey] = useState('tab1'); return ( setActiveKey(key)}> Content for Tab 1 Content for Tab 2 ); }; ``` ### Advanced Examples #### Tabs with Icons and Badges Demonstrates how to use icons and badges within Tab components. The first tab includes an icon, and the second tab includes a badge. ```tsx export const TabsWithIconsAndBadgesExample = () => { const [activeKey, setActiveKey] = useState('tab1'); return ( setActiveKey(key)}> }> Content for Tab 1 3}> Content for Tab 2 ); }; ``` #### Disabled Tab Example Shows how to disable a tab. The second tab is disabled and cannot be selected. ```tsx export const DisabledTabExample = () => { const [activeKey, setActiveKey] = useState('tab1'); return ( setActiveKey(key)}> Content for Tab 1 Content for Tab 2 (Disabled) ); }; ``` ### Styling Examples #### Custom Styled Tabs Demonstrates how to customize the styling of Tabs using styled-components. Applies custom background color and tab button styling. ```tsx const CustomTabs = styled(Tabs)` &.byn-tabs { background-color: #f5f5f5; border-radius: 8px; padding: 8px; } .byn-tab-button { background-color: #fff; border-radius: 4px; padding: 8px 16px; margin: 0 4px; } .byn-tab-button:hover { background-color: #e0e0e0; } .byn-tab-button.active { background-color: #e0e0e0; } `; export const CustomStyledTabsExample = () => { const [activeKey, setActiveKey] = useState('tab1'); return ( setActiveKey(key)}> Custom styled Tab 1 content Custom styled Tab 2 content ); }; ``` ## Variants ### Icon Tab A Tab with an icon. Useful for visual representation. **Configuration:** ```tsx { "icon": "", "label": "Tab 1" } ``` **Example:** ```tsx }> ``` ### Badge Tab A Tab with a badge. Useful for notifications. **Configuration:** ```tsx { "badge": "3", "label": "Tab 2" } ``` **Example:** ```tsx 3}> ``` ## Usage ### Basic Usage Import the Tabs and Tab components, set up the activeKey state, and render the Tabs with Tab children. Use onSelect to handle tab changes. ### Advanced Usage Customize the appearance using styled-components, add icons and badges, and manage more complex state as needed. ### Common Patterns - Using tabs to organize content in a limited space. - Implementing tab navigation with icons for visual cues. - Adding badges to indicate notifications or status. ## Styling ### Theme Integration The Tab component uses the Bonyan Design System theme for consistent styling. It supports various theme properties like colors, spacing, and typography. ### Customization The Tab component can be customized using styled-components. You can target specific classes like .byn-tab-button to apply custom styles. ### Available Tokens - `color.primary` - `color.secondary` - `spacing.small` - `spacing.medium` - `typography.body1` ### Styling Examples ```tsx Custom background color for Tabs: const CustomTabs = styled(Tabs)` background-color: #f5f5f5; `; ``` ```tsx Custom tab button styling: const CustomTabButton = styled(Tab)` &.byn-tab-button { padding: 8px 16px; } `; ``` ## Best Practices - Always provide unique eventKey values for each Tab. - Use the onSelect callback to manage the active tab state. - Consider adding ARIA attributes for better accessibility. - Avoid overloading tabs with too much content; keep labels concise. ## Accessibility - The Tab component follows ARIA practices for tabbed interfaces. - Uses role="tab" and role="tablist" appropriately. - Supports keyboard navigation with arrow keys. - Ensures proper focus management for better screen reader compatibility. ## Events and Handlers The Tab component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal Tab performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Tab component: ```tsx test('renders tab component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## TabItem Component **Version**: 0.1.10 **Props Count**: 12 **Description**: `TabItem` is a styled component within Bonyan Design System, used to represent individual selectable items within a tab group. **Documentation Source**: Generated from TypeScript + AI # TabItem A styled component representing an individual selectable item within a tab group. ## Overview The TabItem component is used to represent individual selectable items within a tab group. It supports various states, icons, and labels, making it versatile for different use cases. ### Props | Prop | Description | |------|-------------| | `badge` | badge component or element | Type: React element | | `containerRef` | containerRef component or element | Type: Ref | | `disabled` | Whether the component is disabled | Type: true | false | | `eventKey` | String value for eventKey | Type: string | | `icon` | Icon to display | Type: React element | | `label` | The label text for the component | Type: string | | `navigationRef` | navigationRef component or element | Type: (elem: HTMLDivElement) => void | | `onClick` | Click event handler | Type: () => void | | `selected` | Boolean flag for selected | Type: true | false | | `variant` | The visual variant of the component | Type: "neutral", "secondary" | Required | ## Examples ### Basic Examples #### Basic TabItem with Label A simple TabItem with a text label, demonstrating the basic usage. ```tsx export const BasicLabel = () => { return ( ); }; ``` #### TabItem with Icon and Label A TabItem that includes both an icon and a text label, demonstrating how to combine visual and text elements. ```tsx export const IconAndLabel = () => { return ( } label="Add Item" variant="secondary" /> ); }; ``` #### Disabled TabItem A TabItem that is disabled, showing how to prevent user interaction. ```tsx export const DisabledTab = () => { return ( } label="Disabled Tab" variant="neutral" disabled /> ); }; ``` ### Advanced Examples #### Selected TabItem A TabItem that is currently selected, demonstrating the active state. ```tsx export const SelectedTab = () => { return ( } label="Selected Tab" variant="secondary" selected /> ); }; ``` #### TabItem with Loading State A TabItem that shows a loading state, useful for asynchronous operations. ```tsx export const LoadingTab = () => { return ( } label="Loading..." variant="neutral" onClick={() => { console.log('Loading tab clicked'); }} /> ); }; ``` ### Styling Examples #### Custom Styled TabItem A TabItem with custom styling applied using styled-components. ```tsx const CustomTabItem = styled(TabItem)` background-color: ${props => props.theme.colors.primary[100]}; color: ${props => props.theme.colors.onPrimary.highEmphasis}; padding: ${props => props.theme.spacing.md}; `; export const StyledTab = () => { return ( ); }; ``` ## Variants ### neutral Neutral variant of the TabItem, suitable for most use cases. **Configuration:** ```tsx { "variant": "neutral" } ``` **Example:** ```tsx export const NeutralVariant = () => { return ( ); }; ``` ### secondary Secondary variant of the TabItem, providing a different visual emphasis. **Configuration:** ```tsx { "variant": "secondary" } ``` **Example:** ```tsx export const SecondaryVariant = () => { return ( ); }; ``` ## Usage ### Basic Usage Import the TabItem component and use it within a tab group. Provide a label or icon, and specify the variant. ### Advanced Usage Combine TabItem with other components like TabGroup and TabPanel to create a complete tabbed interface. Handle user interactions using onClick and manage the selected state. ### Common Patterns - Using TabItem with icons for visual emphasis. - Implementing loading states within tabs. - Creating custom styled tabs that match your application's theme. ## Styling ### Theme Integration The TabItem component uses the theme's color palette for its styling. It supports primary and secondary colors, and adapts to the theme's onSurface colors for text and icons. ### Customization You can customize the TabItem using styled-components or by passing custom class names. The component respects the theme's design tokens for consistent styling. ### Available Tokens - `colors.primary` - `colors.secondary` - `colors.onSurface` - `spacing.md` - `spacing.xs` - `spacing.sm` ### Styling Examples ```tsx Custom padding and colors: const CustomTab = styled(TabItem)` padding: ${spacing.lg} ${spacing.md}; background-color: ${props => props.theme.colors.primary[100]}; `; ``` ## Best Practices - Always provide a meaningful label or icon to ensure proper accessibility. - Use the selected prop to indicate the active tab in a tab group. - Ensure proper color contrast for text and icons, especially when customizing. - Avoid using too many tabs in a single group to maintain a clean interface. ## Accessibility - The TabItem component includes proper ARIA attributes for accessibility. - It supports keyboard navigation, allowing users to focus and select tabs using their keyboard. - The component ensures high contrast between text and background for better readability. - When disabled, the component properly announces its state to screen readers. ## Events and Handlers The TabItem component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal TabItem performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the TabItem component: ```tsx test('renders tabitem component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Table Component **Version**: Unknown **Props Count**: 8 **Documentation Source**: Generated from TypeScript + AI # Table A flexible and feature-rich table component built on top of TanStack Table v8, supporting expandable rows, error states, and custom styling. ## Overview The Table component provides a robust solution for displaying data in a tabular format. It supports features like expandable rows, error handling, and retry functionality, making it suitable for complex data visualization needs. The component is themable and allows for custom styling through class names. ### Props | Prop | Description | |------|-------------| | `className` | String value for className | Type: string | | `columns` | columns property | Type: ColumnType[] | Required | | `data` | data property | Type: TableData[] | Required | | `error` | Boolean flag for error | Type: true | false | | `expanded` | Boolean flag for expanded | Type: true | false | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `lastDivider` | Boolean flag for lastDivider | Type: true | false | | `onRetryClick` | Click event handler | Type: () => void | ## Examples ### Basic Examples #### Basic Table A simple table displaying a list of people with their first name, last name, and gender. ```tsx interface Person { firstName: string; lastName: string; gender: string; } export const BasicTableExample = () => { const columns = [ { header: 'نام', accessorKey: 'firstName', fill: true }, { header: 'نام خانوادگی', accessorKey: 'lastName' }, { header: 'جنسیت', accessorKey: 'gender', alignment: 'left' } ]; const data = [ { firstName: 'مقدار', lastName: 'مقدار', gender: 'مقدار' }, { firstName: 'مقدار طولانی', lastName: 'مقدار', gender: 'مقدار' }, { firstName: 'مقدار', lastName: 'مقدار', gender: 'مقدار' } ]; return ( ); }; ``` ### Variant Examples #### Full Width Table A table that spans the full width of its container. ```tsx interface Person { firstName: string; lastName: string; gender: string; } export const FullWidthTableExample = () => { const columns = [ { header: 'نام', accessorKey: 'firstName', fill: true }, { header: 'نام خانوادگی', accessorKey: 'lastName' }, { header: 'جنسیت', accessorKey: 'gender', alignment: 'left' } ]; const data = [ { firstName: 'مقدار', lastName: 'مقدار', gender: 'مقدار' }, { firstName: 'مقدار طولانی', lastName: 'مقدار', gender: 'مقدار' }, { firstName: 'مقدار', lastName: 'مقدار', gender: 'مقدار' } ]; return (

); }; ``` ### Advanced Examples #### Expanded Rows A table with expandable rows showing sub-rows for each main row. ```tsx interface Person { firstName: string; lastName: string; gender: string; subRows?: Person[]; } export const ExpandedRowsExample = () => { const columns = [ { header: 'نام', accessorKey: 'firstName', fill: true }, { header: 'نام خانوادگی', accessorKey: 'lastName' }, { header: 'جنسیت', accessorKey: 'gender', alignment: 'left' } ]; const data = [ { firstName: 'مقدار', lastName: 'مقدار', gender: 'مقدار', subRows: [ { firstName: 'مقدار ۲', lastName: 'مقدار', gender: 'مقدار' }, { firstName: 'مقدار ۲', lastName: 'مقدار', gender: 'مقدار' } ] }, { firstName: 'مقدار طولانی', lastName: 'مقدار', gender: 'مقدار' } ]; return (

); }; ``` #### Error State with Retry A table displaying an error state with a retry button. ```tsx interface Person { firstName: string; lastName: string; gender: string; } export const ErrorStateExample = () => { const columns = [ { header: 'نام', accessorKey: 'firstName', fill: true }, { header: 'نام خانوادگی', accessorKey: 'lastName' }, { header: 'جنسیت', accessorKey: 'gender', alignment: 'left' } ]; const data = []; return (

console.log('Retrying...')} /> ); }; ``` ### Styling Examples #### Custom Styled Table A table with custom styling applied through className. ```tsx interface Person { firstName: string; lastName: string; gender: string; } export const CustomStylingExample = () => { const columns = [ { header: 'نام', accessorKey: 'firstName', fill: true }, { header: 'نام خانوادگی', accessorKey: 'lastName' }, { header: 'جنسیت', accessorKey: 'gender', alignment: 'left' } ]; const data = [ { firstName: 'مقدار', lastName: 'مقدار', gender: 'مقدار' }, { firstName: 'مقدار طولانی', lastName: 'مقدار', gender: 'مقدار' }, { firstName: 'مقدار', lastName: 'مقدار', gender: 'مقدار' } ]; return (

); }; ``` ## Usage ### Basic Usage Import the Table component and define your columns and data. Pass these props to the Table component to render your data. ### Advanced Usage Use features like expandable rows, error handling, and custom styling to create complex data visualizations. ### Common Patterns - Displaying hierarchical data with expandable rows. - Handling loading and error states with retry functionality. - Customizing the table's appearance using className and styled-components. ## Styling ### Theme Integration The Table component uses the theme's colors, typography, and spacing tokens. It respects the theme's outline colors for borders and background colors for text. ### Customization The Table component can be customized using styled-components. You can create a custom styled component by extending the Table component and applying your own styles. ### Available Tokens - `colors.outline.lowEmphasis` - `colors.onBackground.mediumEmphasis` - `colors.onBackground.highEmphasis` - `spacing.sm` - `spacing.md` - `spacing.lg` - `typography.label.small` - `typography.label.medium` ### Styling Examples ```tsx const CustomTable = styled(Table)` th { background-color: ${({ theme }) => theme.colors.primary.lowEmphasis}; } td { padding: ${({ theme }) => theme.spacing.md} 0; } `; ``` ## Best Practices - Always memoize expensive calculations and data transformations using useMemo to optimize performance. - Use the error and onRetryClick props to handle error states and provide retry functionality. - Apply appropriate padding and spacing using the theme's spacing tokens for consistent styling. - Consider accessibility by ensuring proper ARIA attributes and keyboard navigation support. ## Accessibility - The Table component uses proper ARIA attributes for accessibility. - Rows and cells are navigable using keyboard navigation. - The component supports screen readers by providing appropriate roles and attributes. - Ensure sufficient color contrast between text and background for better readability. ## Events and Handlers The Table component supports various event handlers for user interactions: - `onRetryClick`: Event handler ## Performance Considerations Tips for optimal Table performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Table component: ```tsx test('renders table component', () => { render(

Test content

); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Text Component **Version**: 0.1.10 **Props Count**: 40 **Description**: Renders styled text using Bonyan's design system, handling color, and custom data attributes. Supports children & styles. **Documentation Source**: Generated from TypeScript + AI # Text A versatile text component with extensive styling options and theme integration. ## Overview The Text component is a foundational element that supports various text styles, margins, padding, and other design tokens. It's ideal for displaying body text, headings, and labels while maintaining consistency with Bonyan's design system. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `as` | as component or element | Type: ElementType | | `className` | String value for className | Type: string | | `color` | The color variant of the component | Type: string | DefaultTheme | ((theme: DefaultTheme) => string) | | `cssDisplay` | cssDisplay property | Type: Display | | `dangerouslySetInnerHTML` | dangerouslySetInnerHTML property | Type: { __html: string | TrustedHTML; } | | `dataAttrName` | String value for dataAttrName | Type: string | | `dataAttrValue` | dataAttrValue property | Type: any | | `dataTest` | Data attribute for testing purposes | Type: string | | `ellipsis` | ellipsis property | Type: number | boolean | | `forwardedAs` | forwardedAs component or element | Type: ElementType | | `id` | The unique identifier for the component | Type: string | | `numberAlign` | Boolean flag for numberAlign | Type: true | false | | `onClick` | Click event handler | Type: (e: MouseEvent) => void | | `size` | The size variant of the component | Type: "tiny", "small", "medium"... | | `striketrough` | Boolean flag for striketrough | Type: true | false | | `style` | style property | Type: CSSProperties | | `textAlign` | textAlign option | Type: "center", "-moz-initial", "inherit"... | | `toPersian` | Boolean flag for toPersian | Type: true | false | | `underline` | Boolean flag for underline | Type: true | false | | `variant` | The visual variant of the component | Type: "display", "headline", "title"... | | `weight` | weight option | Type: "bold", "demibold", "regular"... | | `width` | Width configuration | Type: number | ## Examples ### Basic Examples #### Basic Text Example A simple text component displaying a welcome message. ```tsx export const BasicTextExample = () => { return ( Welcome to Bonyan Design System ); }; ``` ### Variant Examples #### Text with Different Variants Demonstrates different text variants (display, headline, title, label, body) with varying sizes and weights. ```tsx export const TextVariantsExample = () => (

Display Text - Extra Large Headline Text - Large Title Text - Medium Label Text - Small Body Text - Tiny

); ``` ### Advanced Examples #### Ellipsis and Number Alignment Demonstrates ellipsis for text truncation and number alignment for better readability. ```tsx export const EllipsisNumberAlignExample = () => (

This is a very long text that will be truncated with ellipsis... 1234567890

); ``` ### Styling Examples #### Text Alignment and Color Shows text alignment options (left, center, right) and different color styles. ```tsx export const TextAlignColorExample = () => (

Left aligned primary text Center aligned secondary text Right aligned error text

); ``` #### Custom Styled Text Shows how to apply custom styles using margin and padding props. ```tsx export const CustomStyledTextExample = () => (

Custom styled text with margin and padding Centered text with horizontal margins and padding

); ``` ## Variants ### Display Large, bold text suitable for headings. **Configuration:** ```tsx { "variant": "display", "size": "xlarge", "weight": "bold" } ``` **Example:** ```tsx export const DisplayVariant = () => ( Display Text ); ``` ### Headline Prominent text for titles. **Configuration:** ```tsx { "variant": "headline", "size": "large", "weight": "demibold" } ``` **Example:** ```tsx export const HeadlineVariant = () => ( Headline Text ); ``` ### Title Medium-sized text for subheadings. **Configuration:** ```tsx { "variant": "title", "size": "medium", "weight": "regular" } ``` **Example:** ```tsx export const TitleVariant = () => ( Title Text ); ``` ## Usage ### Basic Usage Import the Text component and use it with basic props for simple text display. ### Advanced Usage Combine various props like variant, size, weight, and alignment for complex text layouts. ### Common Patterns - Using Text with other components like Button or Card for consistent typography. - Applying ellipsis for text truncation in limited space. - Utilizing number alignment for better readability of numerical data. ## Styling ### Theme Integration The Text component uses Bonyan's default theme for consistent styling. It supports theme colors, typography, and spacing. ### Customization You can customize the Text component using styled-components or by passing custom style props. For example: const CustomText = styled(Text)` color: ${props => props.theme.colors.primary}; `; ### Available Tokens - `color` - `spacing` - `typography` - `weight` - `alignment` ### Styling Examples ```tsx Using custom color and margin: Custom Color ``` ```tsx Applying padding and font weight: Bold Text ``` ```tsx Center-aligned text with specific width: Centered Text ``` ## Best Practices - Use appropriate text variants for different content types (e.g., display for headings, body for paragraphs). - Ensure proper color contrast for accessibility, especially when using custom colors. - Avoid using multiple text components in a row without proper spacing; use margin or padding props instead. - Prefer theme colors over arbitrary color values for consistency. ## Accessibility - The Text component supports ARIA attributes for better screen reader compatibility. - Ensure that text has sufficient contrast with its background for readability. - Use appropriate text alignment based on the content and layout requirements. - Avoid using color as the sole indicator of important information. ## Events and Handlers The Text component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal Text performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Text component: ```tsx test('renders text component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## TextInput Component **Version**: 0.1.10 **Props Count**: 405 **Description**: `TextInput` is a customizable input field component within the Bonyan Design System. It provides features like formatting options, input validation, and focus management. **Documentation Source**: Generated from TypeScript + AI # TextInput A versatile text input component with support for icons, formatting, and error states. ## Overview The TextInput component provides a flexible and customizable input field for various use cases, including form inputs, search bars, and more. It supports features like input formatting, icons, and error handling. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `charCount` | Numeric value for charCount | Type: number | | `containerClassName` | String value for containerClassName | Type: string | | `dataTest` | Data attribute for testing purposes | Type: string | | `disabled` | Whether the component is disabled | Type: true | false | | `disableHTMLInput` | Boolean flag for disableHTMLInput | Type: true | false | | `endIcon` | Icon configuration | Type: React element | | `error` | error property | Type: string | boolean | | `format` | format property | Type: "price" | "card" | "mobile" | "phone" | "sheba" | InputFormatFunction | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `helpText` | String value for helpText | Type: string | | `inputErrorId` | String value for inputErrorId | Type: string | | `label` | The label text for the component | Type: string | | `multiline` | Boolean flag for multiline | Type: true | false | | `onChangeValue` | Change event handler | Type: (value: string) => void | | `onWrapperClick` | Click event handler | Type: () => void | | `outfield` | Boolean flag for outfield | Type: true | false | | `placeholder` | The placeholder text | Type: string | | `postfix` | String value for postfix | Type: string | | `prefix` | String value for prefix | Type: string | | `startIcon` | Icon configuration | Type: React element | | `toEnglish` | Boolean flag for toEnglish | Type: true | false | | `valueDirection` | valueDirection option | Type: "ltr", "rtl" | | `warning` | String value for warning | Type: string | | `wrapperClassName` | String value for wrapperClassName | Type: string | ## Examples ### Basic Examples #### Basic TextInput A simple text input with a label and placeholder. ```tsx export const BasicTextInput = () => { return ( ); }; ``` ### Advanced Examples #### TextInput with Icons A text input with start and end icons. ```tsx export const TextInputWithIcons = () => { return ( } endIcon={} placeholder="Search or type..." /> ); }; ``` #### TextInput with Error Handling A text input showing error state and message. ```tsx export const TextInputWithError = () => { return ( ); }; ``` #### Formatted TextInput A text input with number formatting for phone numbers. ```tsx export const FormattedTextInput = () => { return ( ); }; ``` ### Styling Examples #### Custom Styled TextInput A text input with custom styling using styled-components. ```tsx const CustomTextInput = styled(TextInput)` & .byn-text-input__context input { border: 2px solid #007AFF; border-radius: 8px; padding: 12px 16px; } & .byn-text-input__context input:focus { border-color: #0056B3; box-shadow: 0 0 0 2px rgba(0, 122, 255, 0.2); } `; export const StyledTextInputExample = () => { return ( ); }; ``` ## Usage ### Basic Usage Use the TextInput component for basic input fields. Provide a label and placeholder for context. ### Advanced Usage For more complex use cases, utilize features like input formatting, icons, and error handling. Combine these props to create specialized input fields. ### Common Patterns - Form inputs with validation - Search bars with icons - Formatted number inputs - Error handling and feedback ## Styling ### Theme Integration The TextInput component uses the theme to derive its colors, spacing, and typography. The theme provides consistent styling across the design system. ### Customization You can customize the TextInput component using styled-components or by passing custom class names. The component's styling can be extended to fit specific design requirements. ### Available Tokens - `colors.onSurface.mediumEmphasis` - `spacing.token` ### Styling Examples ```tsx Custom border and focus styles ``` ```tsx Different padding and margins ``` ```tsx Custom font sizes and colors ``` ## Best Practices - Always provide a label for accessibility purposes. - Use appropriate formatting options for different input types (e.g., phone numbers, prices). - Handle errors gracefully by providing clear error messages. - Ensure proper spacing and layout when using icons or additional content. ## Accessibility - The component uses proper ARIA attributes for accessibility. - It supports keyboard navigation and screen reader compatibility. - Focus management is handled to ensure proper accessibility. - Color contrast is maintained for readability. ## Events and Handlers The TextInput component supports various event handlers for user interactions: - `onWrapperClick`: Event handler - `onChangeValue`: Event handler ## Form Integration The TextInput component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal TextInput performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the TextInput component: ```tsx test('renders textinput component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Textarea Component **Version**: 0.1.10 **Props Count**: 395 **Description**: The Textarea component is a styled, multi-line text input for Bonyan, built with React and styled-components. **Documentation Source**: Generated from TypeScript + AI # Textarea A styled, multi-line text input component for Bonyan Design System. ## Overview The Textarea component provides a flexible, accessible text input area for users to enter multi-line text. It supports various features like labels, placeholders, error states, icons, and helper text. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `charCount` | Numeric value for charCount | Type: number | | `dataTest` | Data attribute for testing purposes | Type: string | | `disabled` | Whether the component is disabled | Type: true | false | | `disableHTMLInput` | Boolean flag for disableHTMLInput | Type: true | false | | `endIcon` | Icon configuration | Type: React element | | `error` | error property | Type: string | boolean | | `fullWidth` | Whether the component takes the full width of its container | Type: true | false | | `helpText` | String value for helpText | Type: string | | `label` | The label text for the component | Type: string | | `onWrapperClick` | Click event handler | Type: () => void | | `outfield` | Boolean flag for outfield | Type: true | false | | `placeholder` | The placeholder text | Type: string | | `startIcon` | Icon configuration | Type: React element | ## Examples ### Basic Examples #### Basic Textarea A simple textarea with a label and placeholder. ```tsx export const BasicTextarea = () => { return (

);
};
```

#### Textarea with Icons

A textarea with start and end icons.
```tsx

export const TextareaWithIcons = () => {
  return (
    <Textarea
      label="Search or send message"
      placeholder="Type your message..."
      startIcon={<Search />}
      endIcon={<Send />}
    />
  );
};
```

### Advanced Examples

#### Error Handling

A textarea showing error state with helper text.
```tsx

export const TextareaError = () => {
  return (
    <Textarea
      label="Required field"
      placeholder="Enter valid input"
      error="This field is required"
      helpText="Please enter valid information"
    />
  );
};
```

#### Character Count

A textarea with character count limitation.
```tsx

export const TextareaCharCount = () => {
  return (
    <Textarea
      label="Limited to 200 characters"
      placeholder="Type your short message..."
      charCount={200}
    />
  );
};
```

### Styling Examples

#### Styling Example

Custom styled textarea with margin and padding.
```tsx

export const StyledTextarea = () => {
  return (
    <Textarea
      label="Styled Textarea"
      placeholder="Custom styled textarea"
      m="major-2"
      p="major-3"
      style={{
        border: '2px solid #0066cc',
        borderRadius: '8px'
      }}
    />
  );
};
```

## Usage

### Basic Usage

Import and use the Textarea component with basic props like label and placeholder.

### Advanced Usage

Use additional features like error handling, character count, and custom styling for more complex use cases.

### Common Patterns

- Form integration with validation
- Comment sections in social media
- Message composition in chat applications

## Styling

### Theme Integration

The Textarea component uses Bonyan's theme system for consistent styling. It supports margin and padding props that integrate with the theme's spacing values.

### Customization

You can customize the Textarea using styled-components. Here's an example:

const CustomTextarea = styled(Textarea)`
  border: 2px solid #0066cc;
  border-radius: 8px;
  padding: 12px;
`;

### Available Tokens

- `spacing`
- `typography`
- `colors`
- `border`
- `shadow`

### Styling Examples
```tsx
Adding custom border and padding:
<Textarea style={{ border: '2px solid #0066cc', padding: '12px' }} />
```
```tsx
Using theme spacing:
<Textarea m="major-2" p="major-3" />
```

## Best Practices

- Always provide a label for accessibility.
- Use helper text to guide users.
- Implement error handling and display error messages clearly.
- Consider adding character count for input limitations.
- Use appropriate margin and padding for spacing.

## Accessibility

- The Textarea component includes proper ARIA attributes.
- It supports keyboard navigation and focus states.
- Ensure sufficient color contrast for readability.
- Provide clear error messages and helper text.

## Events and Handlers

The Textarea component supports various event handlers for user interactions:

- `onWrapperClick`: Event handler

## Performance Considerations

Tips for optimal Textarea performance:

- Minimize re-renders by memoizing callbacks
- Use React.memo for expensive child components
- Consider virtualization for large datasets
- Profile rendering performance in development

## Testing

Testing the Textarea component:
```tsx

test('renders textarea component', () => {
  render(<Textarea>Test content

); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Thumb Component **Version**: 0.1.10 **Props Count**: 368 **Description**: The `Thumb` component in Bonyan Design System renders a thumbnail image container. It accepts `size` and `isOverlay` props. **Documentation Source**: Generated from TypeScript + AI # Thumb A circular container component that can be used for avatars, icons, or other circular content. ## Overview The Thumb component provides a flexible circular container with support for different sizes and overlay states. It is commonly used for avatars, profile pictures, or other circular visual elements in your application. ### Props | Prop | Description | |------|-------------| | `isOverlay` | Boolean flag for isOverlay | Type: true | false | | `size` | The size variant of the component | Type: number | ## Examples ### Basic Examples #### Basic Thumb A simple example of the Thumb component with default size and no overlay. ```tsx export const BasicThumb = () => { return ; }; ``` ### Variant Examples #### Overlay Thumb An example of the Thumb component with the overlay effect enabled. ```tsx export const OverlayThumb = () => { return { return (

); }; ``` #### Dynamic Size Thumb Demonstrates how to dynamically change the size of the Thumb component based on props. ```tsx export const DynamicSizeThumb = () => { const [size, setSize] = React.useState(40); return (

); }; ``` ### Styling Examples #### Styled Thumb Customizing the Thumb component using styled-components. ```tsx const CustomThumb = styled(Thumb)` background-color: #f0f0f0; border: 2px solid #e0e0e0; &:after { background-color: #fff; } `; export const StyledThumb = () => { return }; ``` ## Variants ### Size Variants The Thumb component supports different sizes to accommodate various content sizes. **Configuration:** ```tsx { "size": "40" } ``` **Example:** ```tsx export const SizeExample = () => (

); ``` ### Overlay Variant The Thumb component can be displayed with an overlay effect for visual emphasis. **Configuration:** ```tsx { "isOverlay": "true" } ``` **Example:** ```tsx export const OverlayExample = () => (

); ``` ## Usage ### Basic Usage Import the Thumb component and use it with the desired size and overlay properties. ### Advanced Usage Combine the Thumb component with other components to create complex layouts. Use dynamic props for interactive experiences. ### Common Patterns - Using Thumb for profile avatars - Creating icon buttons with Thumb - Displaying circular progress indicators ## Styling ### Theme Integration The Thumb component uses theme tokens for colors and spacing. The background color and outline are derived from the theme's color palette. ### Customization You can customize the Thumb component using styled-components or by passing custom CSS classes. The component accepts all valid span attributes. ### Available Tokens - `colors.secondary.secondary` - `colors.surface.surfaceBase` ### Styling Examples ```tsx Custom background color: const CustomThumb = styled(Thumb)` background-color: #f0f0f0; `; ``` ```tsx Adding a border: const BorderedThumb = styled(Thumb)` border: 2px solid #e0e0e0; `; ``` ## Best Practices - Use the Thumb component for circular content like avatars or icons. - Avoid using the Thumb component for non-circular content as it may distort the appearance. - Always provide meaningful content inside the Thumb component for better accessibility. - Use the isOverlay prop sparingly and only when you want to draw attention to the Thumb. ## Accessibility - The Thumb component is a span element and does not have any default ARIA roles. - If the Thumb component is used as an interactive element (like a button), ensure you add appropriate ARIA attributes. - Provide alternative text for any images inside the Thumb component using the alt attribute. ## Performance Considerations Tips for optimal Thumb performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Thumb component: ```tsx test('renders thumb component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Title Component **Version**: 0.1.10 **Props Count**: 388 **Description**: The Title component in Bonyan Design System displays a primary title with an optional subtitle, actions, and styling options. **Documentation Source**: Generated from TypeScript + AI # Title The Title component is a flexible and versatile component used to display headings with optional subtitles and actions. It supports various styling options, including different sizes, colors, and weights, making it suitable for a wide range of use cases. ## Overview The Title component is designed to display primary and secondary text with accompanying actions. It provides features like customizable margins, padding, color, and typography options, allowing developers to tailor its appearance to fit different design needs. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `color` | The color variant of the component | Type: string | DefaultTheme | ((theme: DefaultTheme) => string) | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | | `leftAction` | leftAction component or element | Type: React element | | `rightAction` | rightAction component or element | Type: React element | | `size` | The size variant of the component | Type: "tiny", "small", "medium"... | | `subtitle` | String value for subtitle | Type: string | | `title` | The title attribute for the component | Type: string | | `weight` | weight option | Type: "bold", "demibold", "regular"... | ## Examples ### Basic Examples #### Basic Title A simple example of the Title component displaying only the main title. ```tsx export const BasicTitleExample = () => { return ( ); }; ``` ### Variant Examples #### Customized Title with Specific Size and Weight Example demonstrating how to customize the Title component with specific size and font weight. ```tsx export const CustomizedTitleExample = () => { return ( <Title title="Customized Title" size="xlarge" weight="bold" color="#2563eb" /> ); }; ``` ### Advanced Examples #### Title with Subtitle and Actions An advanced example showcasing the Title component with a subtitle and actions on both sides. ```tsx export const AdvancedTitleExample = () => { return ( <Title title="Dashboard Overview" subtitle="Analytics Dashboard for October 2023" leftAction={ <IconButton variant="standard" icon={<Add />} /> } rightAction={ <IconButton variant="standard" icon={<Home />} /> } /> ); }; ``` ### Styling Examples #### Title with Overridden Styles An example showing how to override the Title component's styles using styled-components. ```tsx const CustomTitle = styled(Title)` color: ${props => props.theme.colors.error.error}; margin-bottom: ${props => props.theme.spacing.spaces.medium}; `; export const StyledTitleExample = () => { return ( <CustomTitle title="Styled Title Example" subtitle="This title uses custom styling" /> ); }; ``` ## Variants ### Size Variants The Title component supports different size options to accommodate various layout needs. **Configuration:** ```tsx { "size": "tiny|small|medium|large|xlarge" } ``` **Example:** ```tsx export const SizeVariantExample = () => { return ( <div> <Title title="Tiny Title" size="tiny" /> <Title title="Small Title" size="small" /> <Title title="Medium Title" size="medium" /> <Title title="Large Title" size="large" /> <Title title="XLarge Title" size="xlarge" /> </div> ); }; ``` ### Weight Variants The component offers different font weights to emphasize the title according to the design requirements. **Configuration:** ```tsx { "weight": "light|regular|medium|demibold|bold" } ``` **Example:** ```tsx export const WeightVariantExample = () => { return ( <div> <Title title="Light Title" weight="light" /> <Title title="Regular Title" weight="regular" /> <Title title="Medium Title" weight="medium" /> <Title title="Demibold Title" weight="demibold" /> <Title title="Bold Title" weight="bold" /> </div> ); }; ``` ## Usage ### Basic Usage Import the Title component and use it by providing the title prop. You can optionally add a subtitle and actions on either side. ### Advanced Usage Customize the Title component by adjusting its size, weight, color, and spacing. Use the styled-components approach for more complex styling requirements. ### Common Patterns - Using the Title component as a page header with actions. - Displaying a section title with an optional subtitle. - Creating custom-styled titles that match your application's theme. ## Styling ### Theme Integration The Title component integrates with Bonyan's theme system, allowing you to customize its appearance using theme tokens. You can override colors, spacing, and typography by modifying the theme or using styled-components. ### Customization To customize the Title component, you can use the styled() function from @bonyan/system. This allows you to override styles and create custom variants without affecting the component's functionality. ### Available Tokens - `title.color` - `title.spacing` - `title.typography` ### Styling Examples ```tsx Custom color and spacing: const CustomTitle = styled(Title)` color: ${props => props.theme.colors.primary.primary}; margin: ${props => props.theme.spacing.spaces.medium}; `; ``` ## Best Practices - Always provide a meaningful title to ensure proper accessibility and SEO. - Use subtitles sparingly and only when necessary to avoid clutter. - Ensure that actions are relevant to the title and subtitle content. - Optimize title length to maintain proper layout and readability. - Leverage the theme system for consistent styling across your application. ## Accessibility - The Title component uses proper ARIA roles to ensure accessibility. - Ensure that all interactive elements within the title have proper keyboard navigation. - Maintain adequate color contrast between the title and its background for readability. - Use the subtitle judiciously to avoid overwhelming screen readers. ## Performance Considerations Tips for optimal Title performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Title component: ```tsx test('renders title component', () => { render(<Title>Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Toast Component **Version**: Unknown **Props Count**: 4 **Documentation Source**: Generated from TypeScript + AI # Toast A versatile toast component for displaying temporary notifications with various configurations. ## Overview The Toast component provides a flexible way to display temporary notifications with support for action buttons, close icons, timers, and different layouts. It can be customized to fit various use cases and design requirements. ## Examples ### Basic Examples #### Basic Toast A simple toast notification with a title and message. ```tsx export const BasicToastExample = () => { const config = { title: 'Notification', message: 'This is a basic toast notification.' }; return ; }; ``` #### Toast with Close Icon A toast notification with a close icon. ```tsx export const ToastWithCloseIconExample = () => { const config = { title: 'Notification', message: 'You can close this toast using the close icon.', showCloseIcon: true }; return ; }; ``` ### Variant Examples #### Column Layout Toast A toast notification using column layout instead of the default row layout. ```tsx export const ColumnLayoutToastExample = () => { const config = { title: 'Column Notification', message: 'This toast uses a column layout.', direction: 'column' }; return ; }; ``` ### Advanced Examples #### Toast with Action Button A toast notification with an action button. ```tsx export const ToastWithActionButtonExample = () => { const config = { title: 'Notification', message: 'Click the action button below.', actionButton: { title: 'Action', onClick: () => console.log('Action button clicked') } }; return ; }; ``` #### Toast with Timer A toast notification with a visible timer and auto-dismissal after 6 seconds. ```tsx export const ToastWithTimerExample = () => { const config = { title: 'Temporary Notification', message: 'This toast will disappear in 6 seconds.', showTimer: true, seconds: 6 }; return ; }; ``` ### Styling Examples #### Custom Styled Toast A toast notification with custom styling using styled-components. ```tsx const CustomStyledToast = styled(Toast)` background-color: ${props => props.theme.colors.primary[500]}; color: white; border-radius: 8px; `; export const CustomStyledToastExample = () => { const config = { title: 'Custom Style', message: 'This toast has a custom background color and border radius.' }; return ; }; ``` ## Variants ### Direction The toast can be displayed in either row or column layout. **Configuration:** ```tsx { "direction": "row | column" } ``` **Example:** ```tsx ColumnLayoutToastExample ``` ### Visibility Control the visibility of the close icon and timer. **Configuration:** ```tsx { "showCloseIcon": "boolean", "showTimer": "boolean" } ``` **Example:** ```tsx ToastWithCloseIconExample ``` ## Usage ### Basic Usage Import the Toast component and use it by providing the required configuration props. The minimum required prop is the title. ### Advanced Usage For more complex use cases, you can customize the layout, add action buttons, show timers, and control the visibility of UI elements. You can also customize the styling using styled-components. ### Common Patterns - Displaying temporary success or error messages - Showing notifications with action buttons - Providing countdown timers for auto-dismissal - Customizing the appearance to match your brand ## Styling ### Theme Integration The Toast component uses the theme's inverse color palette for text and background colors, and the standard color palette for action buttons and close icons. ### Customization The Toast component can be customized using styled-components. You can override the background color, text color, border radius, and other styles by creating a custom styled component. ### Available Tokens - `colors.inverse.onSurfaceHigh` - `colors.inverse.surface` - `colors.primary[500]` - `spacing.md` - `spacing.lg` - `rounding.md` ### Styling Examples ```tsx CustomStyledToastExample ``` ```tsx background-color: ${props => props.theme.colors.secondary[500]}; ``` ```tsx border-radius: 12px; ``` ## Best Practices - Use toasts for non-intrusive notifications that don't require immediate user interaction. - Avoid using toasts for critical errors that require immediate attention. - Ensure that toasts are accessible by providing proper ARIA attributes and keyboard navigation. - Don't overload the user with too many toasts at once; use the preventDuplicate prop when necessary. ## Accessibility - The Toast component automatically adds ARIA roles and attributes for accessibility. - The close icon button has an aria-label for screen reader support. - Action buttons are keyboard navigable and have proper focus states. - The component respects the system's reduced motion preferences for animations. ## Performance Considerations Tips for optimal Toast performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Toast component: ```tsx test('renders toast component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## ToggleSwitch Component **Version**: Unknown **Props Count**: 315 **Documentation Source**: Generated from TypeScript + AI # ToggleSwitch A toggle switch component that allows users to select between two states, on or off. ## Overview The ToggleSwitch component is a binary choice control used for selecting between two mutually exclusive states. It supports various states like checked, disabled, and loading, and can be customized using different props. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | | `label` | The label text for the component | Type: string | ## Examples ### Basic Examples #### Basic ToggleSwitch A simple toggle switch with default styling and behavior. ```tsx export const BasicToggle = () => { return ( ); }; ``` #### Disabled ToggleSwitch A toggle switch that is disabled and cannot be interacted with. ```tsx export const DisabledToggle = () => { return ( ); }; ``` #### Checked ToggleSwitch A toggle switch that is checked by default. ```tsx export const CheckedToggle = () => { return ( ); }; ``` ### Advanced Examples #### Controlled ToggleSwitch A toggle switch that demonstrates controlled usage with state management. ```tsx export const ControlledToggle = () => { const [isChecked, setIsChecked] = useState(false); const handleToggle = (event: React.ChangeEvent) => { setIsChecked(event.target.checked); // Perform some action when the toggle state changes console.log('Toggle state:', event.target.checked); }; return ( ); }; ``` #### Loading State ToggleSwitch A toggle switch that demonstrates a loading state. ```tsx export const LoadingToggle = () => { return ( ); }; ``` ### Styling Examples #### Custom Styled ToggleSwitch An example of customizing the toggle switch using styled-components. ```tsx const CustomToggleSwitch = styled(ToggleSwitch)` &.byn-switch { &__container { background-color: #f0f0f0; } &__indicator { background-color: #4CAF50; } } `; export const CustomToggle = () => { return ( ); }; ``` ## Variants ### Checked The toggle switch is in the checked state. **Configuration:** ```tsx { "checked": true } ``` **Example:** ```tsx CheckedToggle ``` ### Disabled The toggle switch is disabled and cannot be interacted with. **Configuration:** ```tsx { "disabled": true } ``` **Example:** ```tsx DisabledToggle ``` ## Usage ### Basic Usage Import the ToggleSwitch component and use it with the label prop. The component can be used in both controlled and uncontrolled modes. ### Advanced Usage For more complex use cases, use the controlled component pattern by managing the checked state with React state. You can also customize the appearance using styled-components or custom CSS classes. ### Common Patterns - Use the toggle switch to allow users to select between two mutually exclusive options. - Implement the toggle switch in forms for boolean inputs. - Use the disabled state to prevent user interaction while maintaining the visual presence. - Customize the appearance of the toggle switch to match your application's design system. ## Styling ### Theme Integration The ToggleSwitch component uses the theme to derive its colors and spacing. The default theme provides styling for different states such as checked, disabled, and hover. The component uses design tokens for consistent spacing, colors, and transitions. ### Customization The ToggleSwitch can be customized using styled-components or by passing custom class names. You can override the default styles by targeting the appropriate class names in your custom CSS. ### Available Tokens - `container.width` - `container.height` - `indicator.size` - `transitionTime` - `colors.onSurface.disable` - `colors.surface.surfaceBase` ### Styling Examples ```tsx CustomToggle ``` ```tsx export const CustomColorToggle = () => { return ( ); }; .custom-color-toggle { &.byn-switch { &__container { background-color: #ffcccc; } &__indicator { background-color: #ff0000; } } } ``` ## Best Practices - Always provide a meaningful label for the toggle switch to ensure proper accessibility. - Use the disabled prop to prevent user interaction when necessary. - Consider using the controlled component pattern for form handling. - Avoid unnecessary customization that could disrupt the user experience. - Ensure proper color contrast for accessibility compliance. ## Accessibility - The ToggleSwitch component includes proper ARIA attributes for accessibility. - The component supports keyboard navigation, allowing users to toggle the state using the spacebar. - The toggle switch has proper focus management, ensuring it can receive and handle focus events. - The component uses semantic HTML elements and roles for better screen reader compatibility. - Ensure that the color contrast between the toggle states meets WCAG guidelines for accessibility. ## Performance Considerations Tips for optimal ToggleSwitch performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the ToggleSwitch component: ```tsx test('renders toggleswitch component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Toman Component **Version**: 0.1.10 **Props Count**: 23 **Description**: The "Toman" component displays the Persian currency symbol (تومانء) using a Text component. **Documentation Source**: Generated from TypeScript + AI # Toman The Toman component displays the Persian currency symbol (تومانء) using a Text component. It supports various styling options through props. ## Overview A component for displaying the Persian currency symbol with customizable typography and spacing. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `id` | The unique identifier for the component | Type: string | | `size` | The size variant of the component | Type: "tiny", "small", "medium"... | | `variant` | The visual variant of the component | Type: "display", "headline", "title"... | | `weight` | weight option | Type: "bold", "demibold", "regular"... | ## Examples ### Basic Examples #### Basic Usage A simple example of the Toman component with default styling. ```tsx export const BasicToman = () => { return ; }; ``` ### Variant Examples #### Size Variants Demonstrates different size options for the Toman component. ```tsx export const TomanSizes = () => { return (

); }; ``` #### Weight Variants Shows different font weight options for the Toman component. ```tsx export const TomanWeights = () => { return (

); }; ``` ### Advanced Examples #### Combined Usage with Number Input Using Toman alongside a NumberInput component for currency display. ```tsx export const TomanWithInput = () => { return (

console.log('Value changed:', value)} />

); }; ``` ### Styling Examples #### Custom Styled Toman Applying custom styles to the Toman component using styled-components. ```tsx const StyledToman = styled(Toman)` color: #ff4444; font-size: 24px; font-weight: bold; margin: 16px; `; export const CustomToman = () => { return ; }; ``` ## Variants ### Size Variants The Toman component supports different size options (tiny, small, medium, large, xlarge) to fit various layout needs. **Configuration:** ```tsx { "size": "tiny | small | medium | large | xlarge" } ``` **Example:** ```tsx TomanSizes ``` ### Weight Variants Different font weights (light, regular, demibold, bold) can be applied to the Toman component for visual emphasis. **Configuration:** ```tsx { "weight": "light | regular | demibold | bold" } ``` **Example:** ```tsx TomanWeights ``` ## Usage ### Basic Usage Import and use the Toman component directly in your JSX. It will render the تومانء symbol with default styling. ### Advanced Usage Combine the Toman component with other UI elements like NumberInput or custom styles for more complex use cases. ### Common Patterns - Currency Display - Input Fields - Price Tags - Financial Data Visualization ## Styling ### Theme Integration The Toman component uses the theme's typography settings for consistent styling across the application. It supports theme variants and can be customized through theme overrides. ### Customization You can customize the Toman component using styled-components or by passing inline styles. The component accepts all standard typography props and spacing props for extensive customization. ### Available Tokens - `typography.variant` - `typography.size` - `typography.weight` - `spacing.margin` - `spacing.padding` ### Styling Examples ```tsx Using styled-components to create a custom styled Toman component. ``` ```tsx Passing inline styles to change color, font size, and margins. ``` ## Best Practices - Use the Toman component consistently throughout your application for displaying currency values. - Combine Toman with NumberInput or TextInput components for currency input fields. - Avoid using custom styles when possible - rely on theme variants for consistent styling. - Ensure proper spacing and alignment when using Toman alongside other components. ## Accessibility - The Toman component uses ARIA roles and attributes appropriately for screen reader support. - Ensure that the component has proper color contrast for readability. - Use appropriate font sizes and weights for better visual hierarchy and accessibility. - The component supports keyboard navigation when used with interactive elements. ## Performance Considerations Tips for optimal Toman performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Toman component: ```tsx test('renders toman component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Tooltip Component **Version**: 0.1.10 **Props Count**: 8 **Documentation Source**: Generated from TypeScript + AI # Tooltip The Tooltip component displays contextual help or information when users interact with it, either on hover or click. It supports various placements and customization options to fit different use cases. ## Overview A versatile tooltip component that can be triggered by hover or click events, with multiple placement options and customizable styling. Ideal for providing contextual help or additional information to users. ### Props | Prop | Description | |------|-------------| | `maxWidth` | Width configuration | Type: string | | `open` | Boolean flag for open | Type: true | false | | `openBy` | openBy option | Type: "click", "hover" | | `placement` | placement option | Type: "top", "top-start", "top-end"... | Default: placements.bottom | | `portal` | Boolean flag for portal | Type: true | false | | `showCloseIcon` | Icon configuration | Type: true | false | | `title` | The title attribute for the component | Type: string | Required | | `zIndex` | Numeric value for zIndex | Type: number | ## Examples ### Basic Examples #### Basic Tooltip with Top Placement A simple tooltip that appears when hovering over a button, positioned at the top. ```tsx export const BasicTooltipTop = () => { return ( ); }; ``` #### Tooltip with Close Icon Demonstrates a tooltip with a close icon, allowing users to dismiss it. ```tsx export const TooltipWithCloseIcon = () => { return ( ); }; ``` #### Right-Sided Tooltip A tooltip positioned to the right of its trigger element. ```tsx export const RightTooltip = () => { return ( ); }; ``` ### Advanced Examples #### Controlled Tooltip with Portal A tooltip controlled by external state and rendered through a portal for better layering. ```tsx export const ControlledTooltip = () => { const [isOpen, setOpen] = useState(false); return (

); }; ``` ### Styling Examples #### Custom Styled Tooltip Demonstrates how to customize the tooltip's appearance using styled-components. ```tsx const CustomTooltip = styled(Tooltip)({ '& .szh-menu': { backgroundColor: '#1a1a1a', color: '#ffffff', border: '1px solid #333', }, }); export const StyledTooltipExample = () => { return ( ); }; ``` ## Variants ### Placement Variants The tooltip supports various placement options relative to its trigger element. **Configuration:** ```tsx { "placement": "top | topStart | topEnd | bottom | bottomStart | bottomEnd | right | left" } ``` **Example:** ```tsx export const PlacementVariants = () => { return (

); }; ``` ### Trigger Variants Tooltips can be triggered by hover or click events. **Configuration:** ```tsx { "openBy": "hover | click" } ``` **Example:** ```tsx export const TriggerVariants = () => { const [clicked, setClicked] = useState(false); return (

); }; ``` ## Usage ### Basic Usage 1. Import the Tooltip component 2. Wrap the trigger element with the Tooltip component 3. Provide the tooltip content through the title prop 4. Customize placement and trigger behavior using props ### Advanced Usage For more complex use cases, control the tooltip's visibility using the open prop and manage state externally. Use the portal prop to handle complex layout scenarios. ### Common Patterns - Providing contextual help for form inputs - Displaying additional information on hover - Creating interactive tutorials with step-by-step tooltips - Enhancing user interface elements with descriptive tooltips ## Styling ### Theme Integration The Tooltip component uses the theme's inverse color palette for proper contrast and visual hierarchy. It also leverages the theme's spacing and transition tokens for consistent styling. ### Customization The Tooltip can be customized using styled-components. You can target the underlying menu element through CSS selectors to modify its appearance. ### Available Tokens - `colors.inverse.onSurfaceHigh` - `colors.inverse.surface` - `spacing.token` - `transitions.token` ### Styling Examples ```tsx Custom background color: const CustomTooltip = styled(Tooltip)({ '& .szh-menu': { backgroundColor: '#1a1a1a', }, }); ``` ```tsx Custom border: const BorderedTooltip = styled(Tooltip)({ '& .szh-menu': { border: '1px solid #333', }, }); ``` ## Best Practices - Use the portal prop when the tooltip needs to overlay other elements that have fixed or absolute positioning. - Prefer hover triggers for tooltips that provide additional information without requiring user action. - Ensure that interactive elements inside the tooltip have proper focus management. - Avoid using tooltips for critical information that must be immediately visible. ## Accessibility - The tooltip follows ARIA practices for providing accessible tooltips. - Proper focus management ensures that keyboard users can interact with the tooltip content. - The component respects the system's reduced motion preferences through the theme's transition tokens. - High contrast colors ensure readability for users with visual impairments. ## Performance Considerations Tips for optimal Tooltip performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Tooltip component: ```tsx test('renders tooltip component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## TopAppBar Component **Version**: Unknown **Props Count**: 394 **Documentation Source**: Generated from TypeScript + AI # TopAppBar A persistent top navigation bar with scroll-based styling and shadow effects, featuring text display and actions. ## Overview The TopAppBar component provides a flexible and responsive top navigation bar that can display titles, subtitles, images, and actions. It supports various modes such as floating and expanded states, with automatic shadow adjustments based on scroll position. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `disableBorder` | Boolean flag for disableBorder | Type: true | false | | `expanded` | Boolean flag for expanded | Type: true | false | | `expandedLeftAction` | expandedLeftAction property | Type: ReactNode | | `floating` | Boolean flag for floating | Type: true | false | | `id` | The unique identifier for the component | Type: string | | `image` | image component or element | Type: React element | | `isLeftActionIconBtn` | Icon configuration | Type: true | false | | `leftAction` | leftAction property | Type: ReactNode | | `reverseTexts` | Boolean flag for reverseTexts | Type: true | false | | `rightAction` | rightAction property | Type: ReactNode | | `subtitle` | String value for subtitle | Type: string | | `title` | The title attribute for the component | Type: string | ## Examples ### Basic Examples #### Basic TopAppBar A simple TopAppBar with a title and subtitle. ```tsx export const BasicTopAppBar = () => { return ( ); }; ``` #### TopAppBar with Image A TopAppBar displaying an image alongside the title and subtitle. ```tsx export const TopAppBarWithImage = () => { return ( } /> ); }; ``` ### Advanced Examples #### TopAppBar with Actions A TopAppBar with left and right actions including buttons and icons. ```tsx export const TopAppBarWithActions = () => { return ( } > Add } rightAction={ } color="neutral" size="large" variant="standard" /> } /> ); }; ``` #### Floating TopAppBar A floating TopAppBar with a subtitle and actions. ```tsx export const FloatingTopAppBar = () => { return ( } color="neutral" size="large" variant="solid" elevated /> } rightAction={ } color="neutral" size="large" variant="solid" elevated /> } /> ); }; ``` ### Styling Examples #### Custom Styled TopAppBar A TopAppBar with custom styling using styled-components. ```tsx const CustomTopAppBar = styled(TopAppBar)` &.top-app-bar { background-color: ${props => props.theme.colors.primary.light}; --border-shadow-color: ${props => props.theme.colors.primary.dark}; } `; export const StyledTopAppBarExample = () => { return ( ); }; ``` ## Variants ### Floating A floating TopAppBar that appears to float above content. **Configuration:** ```tsx { "floating": true } ``` **Example:** ```tsx FloatingTopAppBar ``` ### Expanded An expanded TopAppBar with additional content. **Configuration:** ```tsx { "expanded": true } ``` **Example:** ```tsx ExpandedTopAppBar ``` ## Usage ### Basic Usage Import the TopAppBar component and use it with title and subtitle props for basic usage. ### Advanced Usage Combine the TopAppBar with actions, images, and custom styling for more complex layouts. ### Common Patterns - Using the TopAppBar as a header with navigation buttons. - Displaying user information with an image and text. - Creating a floating action bar with elevated buttons. ## Styling ### Theme Integration The TopAppBar integrates with the theme system by using theme colors for background and text. It also respects the theme's spacing and typography settings. ### Customization You can customize the TopAppBar using styled-components or by passing custom styles. The component exposes various CSS variables for fine-grained control. ### Available Tokens - `background-color` - `text-color` - `spacing` - `typography` ### Styling Examples ```tsx Customizing background color: const CustomTopAppBar = styled(TopAppBar)` &.top-app-bar { background-color: ${props => props.theme.colors.primary.light}; } `; ``` ## Best Practices - Use the TopAppBar for primary navigation and actions at the top of the screen. - Ensure that actions are accessible and have proper ARIA labels. - Use the floating prop to create a floating effect that overlays content. - Combine with other components like Button and IconButton for rich interactions. ## Accessibility - The TopAppBar uses proper ARIA roles and attributes for accessibility. - Actions have keyboard navigation support. - Ensure that all interactive elements have proper focus states. - Use high contrast colors for text and background to maintain readability. ## Performance Considerations Tips for optimal TopAppBar performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the TopAppBar component: ```tsx test('renders topappbar component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## TryAgainAction Component **Version**: Unknown **Props Count**: 2 **Documentation Source**: Generated from TypeScript + AI # TryAgainAction A component that provides a retry action with an icon and description, typically used when an operation fails and the user needs to retry. ## Overview The TryAgainAction component is designed to offer users a way to retry an operation that previously failed. It combines an icon with a descriptive text and a clickable action to trigger the retry mechanism. ### Props | Prop | Description | |------|-------------| | `description` | String value for description | Type: string | | `onClick` | Click event handler | Type: () => void | ## Examples ### Basic Examples #### Basic Try Again The most basic implementation of TryAgainAction with default props. ```tsx export const BasicTryAgain = () => { return ( ); }; ``` #### Custom Description TryAgainAction with a custom description text in English. ```tsx export const CustomDescription = () => { return ( ); }; ``` ### Advanced Examples #### Retry with Custom Icon TryAgainAction using a different icon for the retry action. ```tsx export const CustomIcon = () => { return ( console.log('Retrying with custom icon...')} /> ); }; ``` #### Loading State TryAgainAction with a loading state that disables the button. ```tsx export const LoadingState = () => { const [isLoading, setIsLoading] = React.useState(false); const handleRetry = () => { setIsLoading(true); setTimeout(() => setIsLoading(false), 2000); }; return ( ); }; ``` ### Styling Examples #### Styled Try Again Customizing the appearance of TryAgainAction using styles. ```tsx export const StyledTryAgain = () => { return ( ); }; ``` ## Variants ### Icon Size Variants Different icon sizes for the TryAgainAction component. **Configuration:** ```tsx { "size": "small" } ``` **Example:** ```tsx export const IconSizeVariants = () => { return (

); }; ``` ### Icon Type Variants Different icons for the TryAgainAction component. **Configuration:** ```tsx { "icon": "Restart" } ``` **Example:** ```tsx export const IconTypeVariants = () => { return (

} />

); }; ``` ## Usage ### Basic Usage Import the TryAgainAction component and use it with optional description and onClick props. ### Advanced Usage Combine with loading states and custom styling to create more complex retry interactions. ### Common Patterns - Error recovery - Network request retries - User-initiated refresh ## Styling ### Theme Integration The TryAgainAction component uses the theme's color, spacing, and typography settings. The default colors are derived from the theme's onSurface medium emphasis, and the spacing uses the theme's gap and padding values. ### Customization You can customize the TryAgainAction component using styled-components or by passing custom styles directly. The component accepts style props which can be used to override its default styles. ### Available Tokens - `colors.onSurface.mediumEmphasis` - `spacing.md` - `typography.body.small` ### Styling Examples ```tsx Using styled-components: const CustomTryAgain = styled(TryAgainAction)` color: ${props => props.theme.colors.primary}; padding: ${props => props.theme.spacing.lg}; `; ``` ## Best Practices - Always provide a meaningful description for the TryAgainAction to inform users what action they're performing. - Use the onClick handler to implement the retry logic appropriately. - Consider adding loading states to provide feedback when the retry operation is in progress. ## Accessibility - The TryAgainAction component includes proper ARIA attributes for accessibility. - The button is keyboard-navigable and can be activated using the Enter key. - The component ensures sufficient color contrast for readability. ## Events and Handlers The TryAgainAction component supports various event handlers for user interactions: - `onClick`: Event handler ## Performance Considerations Tips for optimal TryAgainAction performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the TryAgainAction component: ```tsx test('renders tryagainaction component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Validation Component **Version**: Unknown **Props Count**: 370 **Documentation Source**: Generated from TypeScript + AI # Validation A component that displays a list of validation items with status indicators. ## Overview The Validation component is used to show the status of multiple validation tests. It supports different states (Passed, Failed, Initial) and can be customized to fit various use cases. ### Props | Prop | Description | |------|-------------| | `onError` | onError event handler | Type: event handler | | `onSuccess` | onSuccess property | Type: () => void | Required | | `shouldReValidateErrors` | Boolean flag for shouldReValidateErrors | Type: true | false | | `validations` | validations property | Type: ValidationTest[] | Required | | `value` | The current value | Type: string | number | T | readonly string[] | ## Examples ### Basic Examples #### Basic Password Validation A basic example showing password validation with three criteria: minimum length, mixed case, and at least one number. ```tsx type ValidationTest = { title: string; test: (value: T) => boolean; }; const exampleValidation: ValidationTest[] = [ { title: 'حداقل هشت کاراکتر', test: (value) => value.length > 8 }, { title: 'حاوی حروف بزرگ و کوچک', test: (value) => /[A-Z]/.test(value) && /[a-z]/.test(value) }, { title: 'حداقل یک عدد', test: (value) => /\d/.test(value) } ]; export const BasicPasswordValidation = () => { const [value, setValue] = useState(''); return (

setValue(e.target.value)} placeholder="Enter your password" /> value={value} validations={exampleValidation} onSuccess={() => console.log('All tests passed')} onError={() => console.log('One test failed')} />

); }; ``` ### Advanced Examples #### Advanced Email Validation An advanced example showing email validation with multiple criteria and error handling. ```tsx type ValidationTest = { title: string; test: (value: T) => boolean; }; const emailValidation: ValidationTest[] = [ { title: 'Must contain @ symbol', test: (value) => value.includes('@') }, { title: 'Must have a valid domain', test: (value) => value.split('@')[1].includes('.') }, { title: 'Must be at least 8 characters', test: (value) => value.length >= 8 } ]; export const AdvancedEmailValidation = () => { const [value, setValue] = useState(''); return (

setValue(e.target.value)} placeholder="Enter your email" /> value={value} validations={emailValidation} onSuccess={() => console.log('Email is valid')} onError={() => console.log('Email validation failed')} shouldReValidateErrors />

); }; ``` #### Dynamic Validation Based on Input Type Shows how to dynamically change validations based on the input type. ```tsx type ValidationTest = { title: string; test: (value: T) => boolean; }; export const DynamicValidation = () => { const [value, setValue] = useState(''); const [inputType, setInputType] = useState<'password' | 'email'>('password'); const getPasswordValidations = (): ValidationTest[] => [ { title: 'At least 8 characters', test: (val) => val.length >= 8 }, { title: 'Must contain at least one number', test: (val) => /\d/.test(val) } ]; const getEmailValidations = (): ValidationTest[] => [ { title: 'Must contain @ symbol', test: (val) => val.includes('@') }, { title: 'Must have a valid domain', test: (val) => val.split('@')[1].includes('.') } ]; return (

setValue(e.target.value)} placeholder={`Enter your ${inputType}`} /> value={value} validations={inputType === 'password' ? getPasswordValidations() : getEmailValidations()} onSuccess={() => console.log('Validations passed')} onError={() => console.log('Validations failed')} />

); }; ``` #### Validation with Array Input Example showing validation with array input values. ```tsx type ValidationTest = { title: string; test: (value: T) => boolean; }; export const ValidationWithArray = () => { const [value, setValue] = useState(['a', 'b']); const arrayValidations: ValidationTest[] = [ { title: 'Must have at least 3 items', test: (val) => val.length >= 3 }, { title: 'All items must be unique', test: (val) => new Set(val).size === val.length } ]; return (

{ const newValue = e.target.value.split(', '); setValue(newValue); }} placeholder="Enter items separated by comma" /> value={value} validations={arrayValidations} onSuccess={() => console.log('Array is valid')} onError={() => console.log('Array validation failed')} />

); }; ``` ### Styling Examples #### Custom Styled Validation Example of how to customize the validation component's styling using styled-components. ```tsx type ValidationTest = { title: string; test: (value: T) => boolean; }; const CustomValidation = styled(Validation)<{ customColor?: string }> ${({ theme, customColor }) => ` & .byn-validation-item { &--passed { color: ${customColor || theme.colors.success.success}; } &--failed { color: ${customColor || theme.colors.error.error}; } } `} ; const exampleValidation: ValidationTest[] = [ { title: 'Test 1', test: () => true }, { title: 'Test 2', test: () => false } ]; export const CustomStyledValidation = () => { return ( console.log('Success')} onError={() => console.log('Error')} customColor="#ff9900" /> ); }; ``` ## Usage ### Basic Usage 1. Import the Validation component. 2. Define your validation tests. 3. Use the component with the input value and validations. 4. Handle success and error states. ### Advanced Usage For advanced use cases, you can dynamically change validations based on input type or use custom styling. ### Common Patterns - Form validation - Real-time input feedback - Dynamic form configurations ## Styling ### Theme Integration The Validation component uses the theme's color palette for different states. The colors are defined in the theme's success and error properties. ### Customization You can customize the Validation component using styled-components. You can override the default styles by providing custom CSS properties. ### Available Tokens - `colors.success` - `colors.error` - `spacing.xs` - `typography.tiny` ### Styling Examples ```tsx Customizing the color of passed and failed states: const CustomValidation = styled(Validation)<{ customColor?: string }> ${({ theme, customColor }) => ` & .byn-validation-item { &--passed { color: ${customColor || theme.colors.success.success}; } &--failed { color: ${customColor || theme.colors.error.error}; } } `} ; ``` ## Best Practices - Always provide meaningful validation titles for better user understanding. - Use the shouldReValidateErrors prop carefully to control re-validation behavior. - Consider performance when using complex validation tests, especially with large datasets. ## Accessibility - The component uses ARIA roles to ensure screen reader compatibility. - Each validation item is properly labeled for accessibility. - The component supports keyboard navigation for better accessibility. ## Events and Handlers The Validation component supports various event handlers for user interactions: - `onError`: Event handler - `onSuccess`: Event handler ## Form Integration The Validation component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal Validation performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Validation component: ```tsx test('renders validation component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## Wheel Component **Version**: 0.1.10 **Props Count**: 9 **Documentation Source**: Generated from TypeScript + AI # Wheel A horizontal, circular slider for numeric input using Keen Slider. Enables looped scrolling for seamless navigation through numbers. ## Overview The Wheel component provides a unique way to select numerical values with a circular, scrollable interface. It supports features like looping, custom labels, and different visual perspectives. ### Props | Prop | Description | |------|-------------| | `initIdx` | Numeric value for initIdx | Type: number | | `initNumber` | Numeric value for initNumber | Type: number | | `itemsMap` | itemsMap property | Type: string[] | | `length` | Numeric value for length | Type: number | Required | | `loop` | Boolean flag for loop | Type: true | false | | `onChange` | Change event handler | Type: (slide: number) => void | | `perspective` | perspective option | Type: "left", "right", "center" | | `setValue` | setValue property | Type: (relative: number, absolute: number) => string | | `showAsTwoDigits` | Boolean flag for showAsTwoDigits | Type: true | false | ## Examples ### Basic Examples #### Basic Usage A simple wheel with 5 slides, starting at index 0 without looping. ```tsx export const BasicWheel = () => { const onChange = (slide: number) => { console.log('Selected slide:', slide); }; return ( ); }; ``` ### Variant Examples #### Looping Wheel A wheel with 3 visible slides that loops infinitely. ```tsx export const LoopingWheel = () => { const onChange = (slide: number) => { console.log('Selected slide:', slide); }; return ( ); }; ``` #### Perspective Variants Different visual perspectives of the wheel. ```tsx export const PerspectiveVariants = () => { const onChange = (slide: number) => { console.log('Selected slide:', slide); }; return (

); }; ``` ### Advanced Examples #### Custom Labels A wheel with custom labels instead of numbers. ```tsx export const CustomLabelsWheel = () => { const onChange = (slide: number) => { console.log('Selected slide:', slide); }; return ( ); }; ``` #### Disabled State Handling Disable the wheel and show a disabled state. ```tsx export const DisabledWheel = () => { const onChange = (slide: number) => { console.log('Selected slide:', slide); }; const setValue = (relative: number, absolute: number) => { return 'Disabled'; }; return ( ); }; ``` ### Styling Examples #### Two-Digit Display Numbers displayed as two digits with leading zeros. ```tsx export const TwoDigitWheel = () => { const onChange = (slide: number) => { console.log('Selected slide:', slide); }; return ( ); }; ``` ## Variants ### Perspective The wheel can be displayed with different perspectives: left, center, or right. **Configuration:** ```tsx { "perspective": "left | center | right" } ``` **Example:** ```tsx PerspectiveVariants ``` ## Usage ### Basic Usage Import the Wheel component and use it with the required `length` prop. Initialize the wheel with `initIdx` and handle changes with `onChange`. ### Advanced Usage Combine `loop` and `itemsMap` for custom, repeating selections. Use `perspective` to change the visual layout. ### Common Patterns - Time selection in a form - Custom value picker in a dashboard - Navigation in a circular list ## Styling ### Theme Integration The Wheel component uses the theme's color palette for text and shadows. You can customize the appearance by modifying the theme variables or using styled-components. ### Customization Use styled-components to wrap the Wheel component and apply custom styles. You can override the default styles by targeting the class names used in the component. ### Available Tokens - `height` - `slideDegree` - `slideWidth` - `slideHeight` - `shadow.topBackground` - `shadow.bottomBackground` - `shadow.height` ### Styling Examples ```tsx Customizing the wheel's height and colors: const CustomWheel = styled(Wheel)` height: 200px; .wheel.keen-slider { color: ${props => props.theme.colors.primary}; } `; ``` ## Best Practices - Use the `loop` prop for scenarios where continuous scrolling is needed, such as time selection. - Implement `itemsMap` for custom labels when numerical values need context. - Ensure `onChange` is properly handled for form integration and state management. - Optimize performance by limiting the number of slides when possible. ## Accessibility - The component supports keyboard navigation through arrow keys. - Uses ARIA roles for improved screen reader compatibility. - Ensure proper color contrast for text and background. - The `setValue` function can be used to format the displayed value for better understanding. ## Events and Handlers The Wheel component supports various event handlers for user interactions: - `onChange`: Event handler ## Form Integration The Wheel component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal Wheel performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the Wheel component: ```tsx test('renders wheel component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- ## WheelTimePicker Component **Version**: 0.1.10 **Props Count**: 24 **Documentation Source**: Generated from TypeScript + AI # WheelTimePicker A React component that allows users to select time using interactive wheels. ## Overview WheelTimePicker is a time selection component that provides an intuitive user interface with rotating wheels for hours and minutes. It supports features like looping for seamless selection and customizable styling through design tokens. ### Props | Prop | Description | |------|-------------| | `globalSpacingValues` | Global spacing values | Type: xs | sm | md | lg | xl | Supports margin (m, mx, my, mt, mb, mr, ml, ms, me) and padding (p, px, py, pt, pb, pr, pl, ps, pe) | | `dataTest` | Data attribute for testing purposes | Type: string | | `defaultHour` | Numeric value for defaultHour | Type: number | | `defaultMinute` | Numeric value for defaultMinute | Type: number | | `id` | The unique identifier for the component | Type: string | | `loop` | Boolean flag for loop | Type: true | false | | `onChange` | Change event handler | Type: (selectedHour: number, selectedMinute: number) => void | ## Examples ### Basic Examples #### Basic Time Picker A simple example of WheelTimePicker with default settings. ```tsx export const BasicTimePicker = () => { const handleTimeChange = (hour: number, minute: number) => { console.log(`Selected time: ${hour}:${minute}`); }; return ( ); }; ``` #### Time Picker with Looping Demonstrates the loop feature for seamless time selection. ```tsx export const TimePickerWithLoop = () => { const handleTimeChange = (hour: number, minute: number) => { console.log(`Selected time: ${hour}:${minute}`); }; return ( ); }; ``` ### Advanced Examples #### Custom Default Time Sets default hour and minute values for the time picker. ```tsx export const CustomDefaultTime = () => { const handleTimeChange = (hour: number, minute: number) => { console.log(`Selected time: ${hour}:${minute}`); }; return ( ); }; ``` #### 24-Hour Time Format Example showing 24-hour format handling with custom display. ```tsx export const TwentyFourHourTime = () => { const handleTimeChange = (hour: number, minute: number) => { console.log(`Selected time: ${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}`); }; return ( ); }; ``` ### Styling Examples #### Time Picker with Custom Styling Shows how to style the WheelTimePicker using styled-components. ```tsx const CustomWheelTimePicker = styled(WheelTimePicker)` .wheel-container { background-color: #f0f0f0; border-radius: 8px; } .wheel { color: #2196f3; } `; export const StyledTimePicker = () => { const handleTimeChange = (hour: number, minute: number) => { console.log(`Selected time: ${hour}:${minute}`); }; return ( ); }; ``` #### Time Picker with Margins Demonstrates styling with margin props. ```tsx export const TimePickerWithMargins = () => { const handleTimeChange = (hour: number, minute: number) => { console.log(`Selected time: ${hour}:${minute}`); }; return ( ); }; ``` ## Variants ### Looping Enables or disables the looping feature for seamless time selection. **Configuration:** ```tsx { "loop": true } ``` **Example:** ```tsx export const LoopingVariant = () => { const handleTimeChange = (hour: number, minute: number) => { console.log(`Selected time: ${hour}:${minute}`); }; return ( ); }; ``` ## Usage ### Basic Usage Import the component and use it with the onChange handler to capture selected times. ### Advanced Usage Customize the component by setting defaultHour and defaultMinute, and enable looping for seamless selection. Use styled-components for advanced styling. ### Common Patterns - Time selection in forms - Scheduling appointments - Setting reminders - Event timing configuration ## Styling ### Theme Integration The WheelTimePicker component uses the Bonyan UI theme for consistent styling. It supports design tokens for colors, spacing, and typography, allowing for a unified look across applications. ### Customization You can customize the appearance of WheelTimePicker using styled-components or by applying custom CSS classes. The component exposes class names like .wheel-container and .wheel for targeted styling. ### Available Tokens - `color.primary` - `color.secondary` - `spacing.major-1` - `spacing.major-2` - `typography.body-medium` ### Styling Examples ```tsx Custom styling using styled-components: ``` ```tsx const CustomWheelTimePicker = styled(WheelTimePicker)` .wheel-container { background-color: #f0f0f0; border-radius: 8px; } .wheel { color: #2196f3; } `; ``` ## Best Practices - Always use the loop prop for a better user experience when seamless time selection is needed. - Ensure that the onChange handler is properly implemented to track time changes. - Use meaningful default values for hour and minute when appropriate. - Avoid unnecessary custom styling to maintain design consistency. ## Accessibility - The component includes ARIA attributes for better screen reader support. - It supports keyboard navigation for enhanced accessibility. - Ensure that the color contrast between text and background meets accessibility standards. - The component handles focus management appropriately for better UX. ## Events and Handlers The WheelTimePicker component supports various event handlers for user interactions: - `onChange`: Event handler ## Form Integration The WheelTimePicker component integrates seamlessly with forms: - Controlled and uncontrolled modes supported - Form validation integration - Proper form submission handling ## Performance Considerations Tips for optimal WheelTimePicker performance: - Minimize re-renders by memoizing callbacks - Use React.memo for expensive child components - Consider virtualization for large datasets - Profile rendering performance in development ## Testing Testing the WheelTimePicker component: ```tsx test('renders wheeltimepicker component', () => { render(Test content); expect(screen.getByText('Test content')).toBeInTheDocument(); }); ``` --- --- *Generated on: 2025-07-19T09:11:18.817Z* *Total Components Documented: 80/80* *Documentation Type: MDX with AI-generated content*