Merge pull request #4 from mconf/fixes-1

Enhance documentation and some fixes

Author: Arthurk12

README.md

@@ -2,7 +2,6 @@
 
 This repository contains a library of reusable React components extracted from the main [**BigBlueButton (BBB)**](https://github.com/bigbluebutton/bigbluebutton) project. These components provide a consistent and customizable interface that can be reused in other projects, allowing them to easily adopt the BBB visual identity.
 
-
 ## Peer Dependencies
 
 This library requires the following peer dependencies to be installed in your project:
@@ -22,6 +21,64 @@ react-icons ^5.5.0
 
 Make sure to install these dependencies to avoid runtime errors and ensure compatibility.
 
+## Color Customization with CSS Variables
+
+This library supports overriding component colors using CSS custom properties (variables). You can define these variables in your project's global CSS or stylesheets to customize the appearance of components without modifying the library code. This is particularly useful for theming and maintaining consistency with your application's design system.
+
+To use this feature:
+1. Define the CSS variables in your project's root styles (e.g., in a global CSS file or via styled-components' `createGlobalStyle`).
+2. The library's components will automatically pick up these variables if they are set on the `:root` element or a parent container.
+
+**Note**: These variables are optional. If not defined, the components will fall back to their default styled-components theme values, which are derived from the project's `src/stylesheets/palette.ts` file.
+
+### Available CSS Variables
+
+The following table lists the supported CSS variables for color overriding, extracted from `src/stylesheets/palette.ts`. Each variable corresponds to a specific color aspect used in the components (e.g., neutrals, brands, semantics). The "Maps to BBB Core Variable" column indicates if the variable aligns with a standard BBB core color (based on the file's comments). The "Default Value" column shows the fallback color used if the variable is not set.
+
+| Variable Name              | Maps to BBB Core Variable  | Default Value |
+|----------------------------|----------------------------|---------------|
+| `--color-neutral-2`        | No                         | #717C91      |
+| `--color-neutral-3`        | No                         | #B0BDC9      |
+| `--color-neutral-4`        | No                         | #DCE4EC      |
+| `--color-neutral-white`    | No                         | #FFFFFF      |
+| `--color-light-gray`       | No                         | #F4F6FA      |
+| `--color-gray`             | No                         | #4E5A66      |
+| `--color-dark-gray`        | No                         | #393C48      |
+| `--color-brand-1`          | No                         | #1D65D4      |
+| `--color-brand-2`          | No                         | #1D65D4      |
+| `--color-brand-3`          | No                         | #1D65D4      |
+| `--color-brand-light`      | Yes (`--color-blue-aux`)   | #E5EFFB      |
+| `--color-brand-aux`        | Yes (`--color-brand-aux`)  | #E5EFFB      |
+| `--color-success`          | No                         | #2DD36F      |
+| `--color-warning`          | No                         | #F59240      |
+| `--color-error`            | Yes (`--color-danger`)     | #D6232D      |
+| `--color-error-dark`       | Yes (`--color-danger-dark`)| #B91C25      |
+| `--color-background-white` | No                         | #FFFFFF      |
+| `--color-background-light` | No                         | #F4F6FA      |
+| `--color-background-blue`  | No                         | #E5EFFB      |
+| `--color-border-default`   | No                         | #B0BDC9      |
+| `--color-border-selected`  | No                         | #1D65D4      |
+| `--color-border-error`     | No                         | #D6232D      |
+| `--color-border-default`   | Yes (`--default-border`)   | #B0BDC9      |
+| `--color-text-default`     | No                         | #393C48      |
+| `--color-text-light`       | No                         | #717C91      |
+| `--color-icon-default`     | No                         | #717C91      |
+| `--color-icon-blue`        | No                         | #1D65D4      |
+| `--color-icon-white`       | No                         | #FFFFFF      |
+| `--color-hover-dark`       | No                         | #1E53AF      |
+| `--color-hover-light`      | No                         | #D4E5FA      |
+| `--color-hover-neutral`    | No                         | #DCE4EC      |
+
+**Example Usage**:
+```css
+:root {
+  --color-primary: #ff5733; /* Override primary brand color to a custom orange */
+  --color-text-default: #333333; /* Darker text for better contrast */
+}
+```
+
+If you need to override colors for specific components or add new variables, refer to the component's `styles.ts` file for implementation details.
+
 ## Installation
 
 This library is under active development and has not yet been published on npm. For now, you can clone the repository and install it locally.
@@ -30,7 +87,7 @@ This library is under active development and has not yet been published on npm.
 
 ```
 npm install
-npm run build-bundle
+npm run build
 ```
 
 ### Using npm link

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@mconf/bbb-ui-components-react",
   "version": "1.0.0",
-  "main": "dist/index.ts",
+  "main": "dist/components/index.js",
   "types": "dist/types/index.d.ts",
   "files": [
     "dist",

package.json

@@ -71,8 +71,10 @@ function Button(props: ButtonProps): JSX.Element {
     'aria-labelledby'?: string;
     'aria-describedby'?: string;
   } = {};
-  if (ariaLabel) accessibilityProps['aria-label'] = ariaLabel;
-  if (ariaLabelledBy) accessibilityProps['aria-labelledby'] = ariaLabelledBy;
+  const generatedId = useId();
+  const defaultLabelId = `${id || generatedId}-label`;
+  accessibilityProps['aria-label'] = ariaLabel || label;
+  accessibilityProps['aria-labelledby'] = ariaLabelledBy || defaultLabelId;
   if (ariaDescribedBy) accessibilityProps['aria-describedby'] = ariaDescribedBy;
 
   const buttonElement = (() => {
@@ -87,10 +89,10 @@ function Button(props: ButtonProps): JSX.Element {
           onClick={onClick}
           onKeyDown={onKeyDown}
           {...accessibilityProps}
-          color={color}
-          variant={variant}
-          size={size}
-          layout={layout}
+          $color={color}
+          $variant={variant}
+          $size={size}
+          $layout={layout}
           disabled={disabled}
         >
           {icon}
@@ -108,27 +110,28 @@ function Button(props: ButtonProps): JSX.Element {
       const testId = dataTest || `${LAYOUTS.STACKED}-button-${id || label || 'default'}`;
 
       return (
-        <Styled.ButtonWrapper data-test={testId} layout={layout}>
+        <Styled.ButtonWrapper data-test={testId} $layout={layout}>
           <Styled.Button
             id={id}
             onClick={onClick}
             onKeyDown={onKeyDown}
             {...accessibilityProps}
-            color={color}
-            variant={variant}
-            size={size}
-            layout={layout}
+            $color={color}
+            $variant={variant}
+            $size={size}
+            $layout={layout}
             disabled={disabled}
           >
             {!hideHelperIcon && (
-              <Styled.helperIconContainer
+              <Styled.HelperIconContainer
                 // Add this property only when there is a onClick function for the auxiliary icon.
                 // It controls whether the auxiliary button is going to have an independent hover state.
                 {...(helperOnClick && { 'data-is-aux-icon': true })}
-                role="button"
-                hover={helperOnClick !== null}
-                color={color}
-                variant={variant}
+                {...(helperOnClick && { 'aria-label': accessibilityProps['aria-label'] + ' helper' })}
+                {...(helperOnClick && { role: "button" })}
+                $hover={helperOnClick !== null}
+                $color={color}
+                $variant={variant}
                 onClick={(event) => {
                   if (helperOnClick) {
                     helperOnClick(event);
@@ -137,12 +140,12 @@ function Button(props: ButtonProps): JSX.Element {
                   }
                 }}
               >
-                <Styled.helperIcon>{helperIcon}</Styled.helperIcon>
-              </Styled.helperIconContainer>
+                <Styled.HelperIcon>{helperIcon}</Styled.HelperIcon>
+              </Styled.HelperIconContainer>
             )}
             {icon && <Styled.IconWrapper>{icon}</Styled.IconWrapper>}
           </Styled.Button>
-          <Styled.ButtonText>{label}</Styled.ButtonText>
+          <Styled.ButtonText id={defaultLabelId}>{label}</Styled.ButtonText>
         </Styled.ButtonWrapper>
       );
     }
@@ -157,14 +160,14 @@ function Button(props: ButtonProps): JSX.Element {
         onClick={onClick}
         onKeyDown={onKeyDown}
         {...accessibilityProps}
-        color={color}
-        variant={variant}
-        size={size}
-        layout={layout}
+        $color={color}
+        $variant={variant}
+        $size={size}
+        $layout={layout}
         disabled={disabled}
       >
         {iconStart && iconStart}
-        {label && <span>{label}</span>}
+        {label && <span id={defaultLabelId}>{label}</span>}
         {children}
         {iconEnd && iconEnd}
       </Styled.Button>

src/components/Button/component.tsx

@@ -10,7 +10,7 @@ import {
   LAYOUTS,
 } from './constants';
 import {
-  StyledhelperIconContainer, StyledButtonProps,
+  StyledHelperIconContainer, StyledButtonProps,
   StyledButtonWrapperProps,
 } from './type';
 import {
@@ -31,15 +31,15 @@ const commonButtonStyles = css<StyledButtonProps>`
   position: relative;
   transition: opacity 0.2s ease-in-out;
 
-  ${({ size }) => {
-    return CSS_SIZE_PROPERTIES[size]
-      ? `padding: ${CSS_SIZE_PROPERTIES[size].padding};`
+  ${({ $size }) => {
+    return CSS_SIZE_PROPERTIES[$size]
+      ? `padding: ${CSS_SIZE_PROPERTIES[$size].padding};`
       : `padding: ${CSS_SIZE_PROPERTIES[DEFAULT_SIZE].padding};`;
   }}
 
-  ${({ color, variant }) => {
-    const safeColor = color || DEFAULT_COLOR;
-    const safeVariant = variant || DEFAULT_VARIANT;
+  ${({ $color, $variant }) => {
+    const safeColor = $color || DEFAULT_COLOR;
+    const safeVariant = $variant || DEFAULT_VARIANT;
     const {
       color: contentColor,
       iconColor,
@@ -72,8 +72,8 @@ const commonButtonStyles = css<StyledButtonProps>`
     `;
   }}
 
-  ${({ variant }) =>
-    variant === VARIANTS.SUBTLE &&
+  ${({ $variant }) =>
+    $variant === VARIANTS.SUBTLE &&
     `
     text-decoration: underline;
   `}
@@ -139,7 +139,7 @@ const defaultLayoutStyles = css`
 `;
 
 export const ButtonWrapper = styled.div<StyledButtonWrapperProps>`
-  ${({ layout }) => layout === LAYOUTS.STACKED && `
+  ${({ $layout }) => $layout === LAYOUTS.STACKED && `
     width: 5rem;
     display: flex;
     flex-direction: column;
@@ -151,8 +151,8 @@ export const ButtonWrapper = styled.div<StyledButtonWrapperProps>`
 export const Button = styled.button<StyledButtonProps>`
   ${commonButtonStyles}
 
-  ${({ layout }) => {
-    switch (layout) {
+  ${({ $layout }) => {
+    switch ($layout) {
       case LAYOUTS.STACKED:
         return stackedLayoutStyles;
       case LAYOUTS.CIRCLE:
@@ -163,16 +163,22 @@ export const Button = styled.button<StyledButtonProps>`
   }}
 `;
 
-export const helperIconContainer = styled.div<StyledhelperIconContainer>`
-  ${({ hover, variant, color }) => hover && `
-    &&:hover,
-    &&:active,
-      background-color: ${CSS_COLOR_PROPERTIES[variant][color].hoverBackground};
-    }
-    &&:focus {
-      outline: 1px solid ${CSS_COLOR_PROPERTIES[variant][color].outline};
-    }
-  `}
+export const HelperIconContainer = styled.div<StyledHelperIconContainer>`
+  ${({ $hover, $variant, $color }) => {
+    if (!$hover) return null;
+
+    return css`
+      &&:hover,
+      &&:active {
+        ${CSS_COLOR_PROPERTIES[$variant][$color].hoverBackground &&
+        `background-color: ${CSS_COLOR_PROPERTIES[$variant][$color].hoverBackground};`}
+      }
+
+      &&:focus {
+        outline: 1px solid ${CSS_COLOR_PROPERTIES[$variant][$color].outline};
+      }
+    `;
+  }}
   border-radius: 50%;
   padding: 0.2rem;
   position: absolute;
@@ -183,7 +189,7 @@ export const helperIconContainer = styled.div<StyledhelperIconContainer>`
   }
 `;
 
-export const helperIcon = styled.div`
+export const HelperIcon = styled.div`
   display: flex;
   align-items: center;
   justify-content: center;

src/components/Button/styles.ts

@@ -42,21 +42,21 @@ type SizeType = typeof SIZE_VALUES[number];
 type LayoutType = typeof LAYOUT_VALUES[number];
 type TooltipPlacementType = typeof TOOLTIP_PLACEMENT_VALUES[number];
 
-export interface StyledhelperIconContainer {
-  hover: boolean;
-  variant: VariantType;
-  color: ColorType;
+export interface StyledHelperIconContainer {
+  $hover: boolean;
+  $variant: VariantType;
+  $color: ColorType;
 }
 
 export interface StyledButtonWrapperProps {
-  layout: LayoutType;
+  $layout: LayoutType;
 }
 
 export interface StyledButtonProps {
-  variant?: VariantType;
-  color?: ColorType;
-  size?: SizeType;
-  layout?: LayoutType;
+  $variant?: VariantType;
+  $color?: ColorType;
+  $size?: SizeType;
+  $layout?: LayoutType;
   disabled: boolean;
 }
 

src/components/Button/type.ts

@@ -72,7 +72,7 @@ const Modal: React.FC<ModalProps> = ({
       {showDividers && <BBBDivider />}
 
       <Styled.ModalBody
-        allowScroll={allowScroll}
+        $allowScroll={allowScroll}
       >
         {children}
       </Styled.ModalBody>
@@ -81,7 +81,7 @@ const Modal: React.FC<ModalProps> = ({
           {showDividers && (<BBBDivider />)}
 
           <Styled.ModalFooter
-            stickyFooter={stickyFooter}
+            $stickyFooter={stickyFooter}
           >
             {footerContent}
           </Styled.ModalFooter>

src/components/Modal/component.tsx

@@ -55,7 +55,7 @@ export const CloseButton = styled.button`
 
 export const ModalBody = styled.div<StyledModalBodyProps>`
   flex-grow: 1;
-  overflow-y: ${({ allowScroll }) => allowScroll ? 'auto' : 'hidden'};
+  overflow-y: ${({ $allowScroll }) => $allowScroll ? 'auto' : 'hidden'};
   overflow-x: hidden;
   display: flex;
   flex-direction: column;
@@ -68,4 +68,12 @@ export const ModalFooter = styled.div<StyledModalFooterProps>`
   display: flex;
   justify-content: flex-end;
   gap: ${spacingMedium};
+  
+  ${({ $stickyFooter }) =>
+    $stickyFooter &&
+    `
+      position: sticky;
+      bottom: 0;
+      background-color: #fff;
+    `}
 `;

src/components/Modal/styles.ts

@@ -1,11 +1,11 @@
 import React from 'react';
 
 export interface StyledModalBodyProps {
-  allowScroll: boolean;
+  $allowScroll: boolean;
 }
 
 export interface StyledModalFooterProps {
-  stickyFooter: boolean;
+  $stickyFooter: boolean;
 }
 
 export interface ModalProps {