@trully/trully-helpers-react v0.0.18

TrullyHelpers

Package created to hold any function helper, React Hook, or React Component needed in more than one Trully React Project.

Components

Button

This component allows for extensive customization through props, including text content, click handling, style, and text style configurations. It integrates dynamic font loading and style application to ensure consistent and responsive UI elements.

Props:

• text: String (optional). The text to be displayed on the button. If not provided, defaults to "Button".
• handleClick: Function. The function to be called when the button is clicked.
• styles: Object (optional). An object containing style configurations for the button, including:
  • color: String (default: COLORS.WHITE). The text color of the button.
  • colorDisabled: String (default: COLORS.GULF). The text color of the button when disabled.
  • bg: String (default: COLORS.DODGER_BLUE). The background color of the button.
  • bgDisabled: String (default: COLORS.CATSKILL_WHITE). The background color of the button when disabled.
  • hoverColor: String (default: COLORS.WHITE). The text color of the button when hovered.
  • hoverBg: String (default: COLORS.GULF). The background color of the button when hovered.
• textStyles: Object (optional). An object containing style configurations specifically for the button text, such as fontFamily.
  • fontFamily: string (optional) - The font family to be used for the text. Defaults to "DM Sans", sans-serif.
• disabled: Boolean (optional, default: false). If true, the button will be disabled and unclickable.

Usage example:

<Button
  text="Click Me"
  handleClick={() => console.log("Button clicked")}
  styles={{
    color: "white",
    disabledColor: "grey",
    bg: "blue",
    bgDisabled: "white",
    hoverColor: "lightblue",
    hoverBg: "darkblue",
  }}
  textStyles={{ fontFamily: "Arial, sans-serif" }}
  disabled={false}
/>

DescriptionIcon

This component offers a flexible way to display icons and text in a cohesive manner, making it a valuable tool for enhancing the user interface with informative and visually appealing elements. The component uses the useDynamicStyle hook to apply dynamic CSS styles, ensuring consistent styling across instances. The icon and text are wrapped in a container div with the class trully-description-icon-container, facilitating custom styling and layout adjustments as needed.

Props:

• icon: String. The URL of the image to be used as the icon. This image is processed by the ImageFilterCanvas component to apply the specified color filter.
• text: String. The descriptive text to be displayed alongside the icon.
• textStyles: object (optional) - An object containing style overrides for the text.
  • fontFamily: string (optional) - The font family to be used for the text. Defaults to "DM Sans", sans-serif.
  • primaryTextColor: string (optional) - The color of the text. Defaults to #181c21
• color: String. A hexadecimal color code used to apply a filter to the icon, allowing for thematic consistency with the text or the overall UI

Usage example:

<DescriptionIcon
  icon="path/to/icon.png"
  text="Descriptive text goes here"
  textStyles={{ fontFamily: "Arial, sans-serif", primaryTextColor: "#333" }}
  color="#ff0000"
/>

ImageFilterCanvas

This React functional component renders an HTML canvas element that displays an image loaded from a provided URL and applies a color filter using the specified hex color. The component is designed to dynamically adjust the canvas size based on the provided width while maintaining the image's aspect ratio. The color filter effect is achieved by leveraging the applyColorFilter function. This component is useful for scenarios where you need to display images with a uniform width and a consistent color theme or filter effect, such as in galleries, product listings, or thematic presentations.

Props:

• imageUrl: String. The URL of the image to be displayed on the canvas. The image is loaded and drawn onto the canvas.
• color: String. A hexadecimal color code used for the color filter that will be applied to the image. The color filter modifies the visual appearance of the image by overlaying it with the specified color.
• canvasWidth: Number. The desired width of the canvas and the image within it. The height of the canvas is automatically adjusted to maintain the image's original aspect ratio.

The component uses a useRef hook to obtain a reference to the canvas element, and a useEffect hook to perform side effects such as loading the image, setting the canvas dimensions, drawing the image, and applying the color filter once the image is loaded. The image.onload event handler is responsible for scaling the image to the desired width, adjusting the canvas height to maintain the aspect ratio, and then drawing the scaled image onto the canvas. After drawing the image, the applyColorFilter function is called to apply the specified color filter to the image.

Usage example:

<ImageFilterCanvas
  imageUrl="path/to/image.jpg"
  color="#ff0000"
  canvasWidth={500}
/>

Loader

Displays a loading indicator with optional text. Ideal for indicating ongoing operations.

Props:

• color: String. The color of the loading indicator. Should be a valid CSS color string.
• text: String (optional, default: "Cargando..."). The text to be displayed alongside the loading indicator.
• textStyles: Object (optional). An object containing style configurations specifically for the text, including:
  • fontFamily: String. The font family to use for the text.
  • primaryTextColor: String (default: COLORS.SHARK). The color of the text.

Usage example:

<ImageFilterCanvas
  color="#ff0000"
  text="Cargando contenido..."
  textStyles={{ fontFamily: "Arial", primaryTextColor: "#000000" }}
/>

Loader

Displays a loading indicator with optional text. Ideal for indicating ongoing operations.

Props:

• color: String. The color of the loading indicator. Should be a valid CSS color string.
• text: String (optional, default: "Cargando..."). The text to be displayed alongside the loading indicator.
• textStyles: Object (optional). An object containing style configurations specifically for the text, including:
  • fontFamily: String. The font family to use for the text.
  • primaryTextColor: String (default: COLORS.SHARK). The color of the text.

Usage example:

<ImageFilterCanvas
  color="#ff0000"
  text="Cargando contenido..."
  textStyles={{ fontFamily: "Arial", primaryTextColor: "#000000" }}
/>

Helpers

applyColorFilter

This function applies a color filter to an HTML canvas element by setting each pixel to a specified color, while maintaining the original alpha values. It's useful for creating color overlay effects or thematic visual alterations on images or graphics rendered on a canvas. The function first verifies the existence of the canvas and its 2D context. It then retrieves the image data for the entire canvas and iterates over each pixel, replacing the red, green, and blue components with those of the specified color, while preserving the alpha (transparency) component.

Parameters:

• hexColor: String. The hexadecimal color code that will be used as the filter color. This should be in the format #RRGGBB
• canvasRef: React.RefObject. A reference to the canvas element on which the color filter will be applied. This allows direct manipulation of the canvas within a React component.

Returns:

• null | void: Returns null if the canvas is not found or the hex color conversion fails. Otherwise, the function does not return a value.
• canvasRef: React.RefObject. A reference to the canvas element on which the color filter will be applied. This allows direct manipulation of the canvas within a React component.

Usage example:

const canvasRef = useRef < HTMLCanvasElement > null;

useEffect(() => {
  if (canvasRef.current) {
    applyColorFilter({ hexColor: "#ff0000", canvasRef });
  }
}, []);

return <canvas ref={canvasRef}></canvas>;

darkerColor

This function generates a darker shade of a given hexadecimal color based on a specified percentage. It reduces the brightness of the original color to produce a darker variant. The function parses the hexadecimal color into its red, green, and blue components, then multiplies each by 1 - percentage to reduce their intensity. The resulting color values are constrained to the valid range 0, 255 and converted back to a two-digit hexadecimal format. The darker color is then returned as a string in the format #RRGGBB.

Parameters:

• hex: String. The original hexadecimal color code to be darkened. It should be in the format #RRGGBB, where RR, GG, and BB are two-digit hexadecimal values representing the red, green, and blue components of the color, respectively
• percentage: Number. A decimal value between 0 and 1 that specifies the percentage by which to darken the color. For example, 0.2 would darken the color by 20%.

Returns:

• void

Usage example:

const originalColor = "#3366FF";
const darkenedColor = darkerColor({ hex: originalColor, percentage: 0.3 });
// darkenedColor will be a darker shade of the original color

hexToRgb

Converts a hex color string to an RGB object. This function takes a hex color string and converts it to an object containing the red, green, and blue color values. If the input string is not a valid hex color, the function returns null. This function is designed to provide a straightforward way to convert hex color codes into their RGB components, making it easier to work with color values in various formats within your applications.

Parameters:

• hex: String. The hex color string to be converted. It can be in the format #RRGGBB or #RRGGBBAA.
• percentage: Number. A decimal value between 0 and 1 that specifies the percentage by which to darken the color. For example, 0.2 would darken the color by 20%.

Returns:

• object: An object with the properties r, g, and b representing the red, green, and blue color values, or null if the input is not a valid hex color string.

Usage example:

const rgb = hexToRgb("#FF5733");
// rgb = { r: 255, g: 87, b: 51 }

Hooks

useDMSansFont

A custom React hook for dynamically loading the DM Sans font from Google Fonts into a web application. This hook enhances performance by ensuring that the necessary <link> elements for preconnecting to Google Fonts services and for loading the font itself are only appended to the document head if they do not already exist, preventing duplicate entries. There is no cleanup function provided in this implementation, as fonts are typically loaded once and used throughout the lifespan of the application. However, developers should be cautious about dynamically adding fonts in Single Page Applications (SPAs) to avoid potential memory leaks or performance degradation over time.

The hook performs the following operations:

• Checks for existing <link> elements for preconnecting to Google Fonts (fonts.googleapis.com) and its font-serving domain (fonts.gstatic.com), and adds these preconnect links if they are missing. This optimization improves the font loading time by resolving DNS lookups in advance.
• Checks for an existing <link> element that imports the DM Sans font stylesheet. If such a link does not exist, the hook creates and appends it to the document head. This <link> element points to a URL specifying the desired font styles and weights to load.

Returns:

• object: An object with the properties r, g, and b representing the red, green, and blue color values, or null if the input is not a valid hex color string.

Usage example:

const MyComponent = () => {
  useDMSansFont(); // Ensures DM Sans font is loaded when this component is rendered
  return (
    <div style={{ fontFamily: '"DM Sans", sans-serif' }}>
      This text uses the DM Sans font.
    </div>
  );
};

useDynamicStyle

This hook dynamically injects CSS styles into the document head using a <style> element. It is designed for cases where styles need to be added or updated based on component or application state. The hook first checks if a <style> element with the specified ID already exists in the document head. If it does not exist, a new <style> element is created and appended to the head with the specified ID. The provided CSS styles are then injected into this element. Upon unmounting, if the remove parameter is set to true, the created <style> element is removed from the document head to clean up and prevent potential style conflicts or duplication in future renders.

Parameters:

• css: String. The CSS styles to be injected. These styles will replace the content of an existing <style> element with the same ID or will be added if no such element exists.
• id: String. The unique identifier for the <style> element. This ID is used to either target an existing <style> element or to assign an ID to a new one.
• remove: Boolean (optional, default: true). Determines whether the <style> element should be removed from the document head upon component unmount. If set to false, the style element will remain in the DOM.

Usage example:

const Component = () => {
  useDynamicStyle({
    css: `.dynamic-class { background-color: red; }`,
    id: "unique-style-id",
  });
  return (
    <div className="dynamic-class">This div will have a red background.</div>
  );
};

Styles Functions

text1BoldStyle

This function generates a CSS style block for a bold text style class named .trully-text-1-bold. It allows for customization of the font family while setting predefined styles for font sizing, weight, and line height. This function is particularly useful for defining consistent bold text styles across different components or sections of a web application.

Parameters:

• fontFamily: String (optional, default: '"DM Sans", sans-serif'). The font family to be used for the text. The default font family is DM Sans with a fallback to sans-serif. This parameter allows for customization of the font family to better match the design requirements of your application.

Returns:

• A string containing the CSS rules for the .trully-text-1-bold class. These rules include:
  • font-family: Sets the font family to the provided value or the default if none is provided.
  • font-optical-sizing: Enables automatic optical sizing for the font.
  • font-style: Sets the font style to normal.
  • font-size: Sets the font size to 1.5rem for relative scalability and readability.
  • font-weight: Sets the font weight to 700, making the text bold and prominent.
  • line-height: Sets the line height to 32px to ensure proper spacing between lines of text for better readability.
  • color: Sets the color to the provided value or the default if none is provided.

Usage example:

const Component = () => {
  useDynamicStyle({
    css: text1BoldStyle("Arial, sans-serif"),
    id: "custom-bold-text-style",
  });
  return <div className="trully-text-1-bold">Bold and Custom Text</div>;
};

text1Style

This function generates a CSS style block for a bold text style class named .trully-text-1. It allows for customization of the font family while setting predefined styles for font sizing, weight, and line height. This function is particularly useful for defining consistent bold text styles across different components or sections of a web application.

Parameters:

• fontFamily: String (optional, default: '"DM Sans", sans-serif'). The font family to be used for the text. The default font family is DM Sans with a fallback to sans-serif. This parameter allows for customization of the font family to better match the design requirements of your application.

Returns:

• A string containing the CSS rules for the .trully-text-1 class. These rules include:
  • font-family: Sets the font family to the provided value or the default if none is provided.
  • font-optical-sizing: Enables automatic optical sizing for the font.
  • font-style: Sets the font style to normal.
  • font-size: Sets the font size to 1rem for relative scalability and readability.
  • font-weight: Sets the font weight to 400, making the text bold and prominent.
  • line-height: Sets the line height to 24px to ensure proper spacing between lines of text for better readability.
  • color: Sets the color to the provided value or the default if none is provided.

Usage example:

const Component = () => {
  useDynamicStyle({
    css: text1Style("Arial, sans-serif"),
    id: "custom-text-style",
  });
  return <div className="trully-text-1">Custom Text</div>;
};

text2Style

This function generates a CSS style block for a bold text style class named .trully-text-2. It allows for customization of the font family while setting predefined styles for font sizing, weight, and line height. This function is particularly useful for defining consistent bold text styles across different components or sections of a web application.

Parameters:

• fontFamily: String (optional, default: '"DM Sans", sans-serif'). The font family to be used for the text. The default font family is DM Sans with a fallback to sans-serif. This parameter allows for customization of the font family to better match the design requirements of your application.

Returns:

• A string containing the CSS rules for the .trully-text-2 class. These rules include:
  • font-family: Sets the font family to the provided value or the default if none is provided.
  • font-optical-sizing: Enables automatic optical sizing for the font.
  • font-style: Sets the font style to normal.
  • font-size: Sets the font size to 0.875rem for relative scalability and readability.
  • font-weight: Sets the font weight to 400, making the text bold and prominent.
  • line-height: Sets the line height to 18px to ensure proper spacing between lines of text for better readability.
  • color: Sets the color to the provided value or the default if none is provided.

Usage example:

const Component = () => {
  useDynamicStyle({
    css: text2Style("Arial, sans-serif"),
    id: "custom-text-style",
  });
  return <div className="trully-text-2">Custom Text</div>;
};

containerStyle

Generates a CSS style block for a container class named .trully-container, with a customizable background color. It is designed for creating container elements with consistent styling across an application, while allowing for flexibility in the background color.

Parameters:

• bg: String. The background color for the container. This can be any valid CSS color value (e.g., hex, rgba, named colors).

Returns:

• A string containing the CSS rules for the .trully-container class. These rules configure the container's sizing, padding, and appearance, including:
  • width: Sets the width to 90% of the viewport width, providing a responsive design.
  • max-width: Caps the maximum width at 650px to maintain readability and usability at larger viewport sizes.
  • background-color: Uses the provided bg parameter to set the background color, offering customization.
  • padding: Adds 16px padding on the top and bottom, and 24px on the left and right, for content spacing.

Usage example:

const Component = () => {
  useDynamicStyle({
    css: containerStyle("#f0f0f0"),
    id: "trully-container-style",
  });
  return <div className="trully-container">Your content here</div>;
};

containerStyle

This function generates a CSS style block specifically for styling a logo element within an application. The style is applied to elements with the .trully-logo class, setting a fixed width to ensure consistent logo sizing across different parts of the application.

Returns:

• A string containing the CSS rule for the .trully-logo class, which includes:
  • width: Sets the width of the logo to 110px. This fixed width helps maintain a uniform appearance for the logo, ensuring it's neither too large nor too small across various application components.

Usage example:

const Component = () => {
  useDynamicStyle({ css: logoStyle(), id: "trully-logo-style" });
  return <img src="path/to/logo.png" className="trully-logo" alt="Logo" />;
};

Enums

COLORS

DEFAULT_IMAGES

DEFAULT_VIDEOS

Constants