@robust-ui/contexts v0.2.0
Functions
InjectCSS
/**
* Injects CSS styles based on the provided component props and theme.
* @param classSelector - The CSS class selector to target the component.
* @param componentProps - The component props containing style information.
* @param breakPoint - The breakpoint value for responsive styles.
* @param theme - The theme object containing style mappings.
* @returns void
*/
export function InjectCSS({
classSelector,
componentProps,
breakPoint,
theme = defaultTheme,
}: InjectCSST): void;
The InjectCSS
function is a powerful utility that allows you to dynamically inject CSS styles into the DOM based on the provided componentProps
and theme
. It enables flexible and customized styling of components using class selectors and a set of properties and values.
Parameters
classSelector
: The CSS class selector used to target the component to which the styles will be applied. It should be a valid CSS selector string, such as'.my-component'
.componentProps
: An object containing the component's properties and their respective style values. Each property represents a CSS property, and its value represents the corresponding value for that property. The supported value types include strings and objects.breakPoint
(optional): The breakpoint value used for responsive styles. It allows styles to be adapted based on the screen size or device. It should be a string representing the desired breakpoint value, such as'md'
,'lg'
, etc.theme
(optional): An object containing theme-specific style mappings. It provides a way to set default values for certain properties and customize styles based on the theme. The theme object should follow a specific structure with property-value mappings.
Usage
To use the InjectCSS
function, follow these steps:
- Import the
InjectCSS
function into your file:
import { InjectCSS } from "InjectCSS";
- Define your component and its props. For example:
const MyComponent = ({ color, fontSize }) => {
// Your component logic here
};
- Within your component, call the
InjectCSS
function to apply the styles:
const MyComponent = ({ color, fontSize }) => {
const classSelector = ".my-component";
const componentProps = {
color,
fontSize,
// Additional component properties and their values
};
InjectCSS({
classSelector,
componentProps,
breakPoint: "md", // Optional: Set the breakpoint for responsive styles
theme: myCustomTheme, // Optional: Provide a custom theme object
});
// Rest of your component code
};
In the example above, the
InjectCSS
function is called within the component to apply the styles defined by thecolor
andfontSize
props. The styles will be applied to any element with the classmy-component
. You can add additional properties tocomponentProps
as needed for your component.Optionally, you can specify a breakpoint value using the
breakPoint
parameter to apply responsive styles. This allows the styles to adapt based on the screen size or device. The breakpoint value should be a string corresponding to the desired breakpoint, such as'md'
,'lg'
, etc.If you have a theme object with style mappings specific to your application, you can provide it using the
theme
parameter. The theme object should have property-value mappings that align with the CSS properties used in yourcomponentProps
. This allows you to customize the styles based on the theme.Finally, make sure to render your component with
the appropriate class name:
const MyComponent = ({ color, fontSize }) => {
// Your component logic here
return <div className="my-component">Hello, world!</div>;
};
It's important to note that the InjectCSS
function should be called whenever the component props change to ensure that the styles are updated accordingly.
That's it! The InjectCSS
function provides a powerful mechanism for dynamically applying styles to components based on props and themes. It offers great flexibility in styling and enables you to create versatile and visually appealing components.
generateHash
import crypto from "crypto";
import { generateHashT } from "functions";
/**
* Generates a hash using the specified algorithm from a given string.
* @param {string} str - The string to generate the hash from.
* @param {string} algorithm - The hash algorithm to use. Default is "sha512".
* @returns {string} - The generated hash as a hexadecimal string.
* @throws {Error} - If an invalid hash algorithm is provided.
*/
export function generateHash({
str,
algorithm = "sha512",
}: generateHashT): string {
if (!crypto.getHashes().includes(algorithm)) {
throw new Error(
`Invalid algorithm: ${algorithm}. Valid algorithms are: ${crypto
.getHashes()
.join(", ")}.`
);
}
return crypto.createHash(algorithm).update(str).digest("hex");
}
The generateHash
function generates a hash using the specified algorithm from a given string. It uses the crypto
module from Node.js for hash generation.
Parameters
str
(string): The string to generate the hash from.algorithm
(string): The hash algorithm to use. Default is "sha512".
Returns
- A string representing the generated hash as a hexadecimal string.
Throws
- An error if an invalid hash algorithm is provided.
generateId
import { generateIdT } from "functions";
import { generateHash, safeJSON } from "functions";
/**
* Generates a unique ID based on the provided object or string using a specified algorithm.
*
* @param obj - The object or string to generate the ID from.
* @param prefix - An optional prefix to include in the generated ID.
* @param algorithm - The hash algorithm to use for generating the hash. Default is "sha1".
* @returns The generated ID as a string.
*/
export function generateId({
obj,
prefix,
algorithm = "sha1",
}: generateIdT): string {
if (typeof obj === "string") {
// If obj is a string, generate hash directly from it
return generateHash({ str: obj, algorithm });
}
// If obj is an object, generate hash from its JSON representation
return `${Boolean(prefix) && prefix}-${generateHash({
str: safeJSON({ obj }),
algorithm,
})}`;
}
The generateId
function generates a unique ID based on the provided object or string using a specified algorithm. It internally uses the generateHash
and safeJSON
functions.
Parameters
obj
(object|string): The object or string to generate the ID from.prefix
(string, optional): An optional prefix to include in the generated ID.algorithm
(string, optional): The hash algorithm to use for generating the hash. Default is "sha1".
Returns
- The generated ID as a string.
How to Use
To use the generateHash
and generateId
functions, follow these steps:
- Import the functions into your project:
import { generateHash, generateId } from "./path/to/functions";
- Use the functions in your code:
const hash = generateHash({
str: "Hello, world!",
algorithm: "sha256",
});
console.log("Generated hash:", hash);
const id = generateId({
obj: { key: "value" },
prefix: "id",
algorithm: "md5",
});
console.log("Generated ID:", id);
Make sure to provide the necessary
createCSSRule
import { createCSSRuleT } from "functions";
/**
* Creates a CSS rule string with the specified selector and styles.
*
* @param selector - The CSS selector for the rule.
* @param styles - The CSS styles to apply.
* @returns The generated CSS rule as a string.
*/
export function createCSSRule({ selector, styles }: createCSSRuleT): string {
return `.${selector} {${styles}}`;
}
The createCSSRule
function generates a CSS rule string with the specified selector and styles.
Parameters
selector
(string): The CSS selector for the rule.styles
(string): The CSS styles to apply.
Returns
- The generated CSS rule as a string.
createStyleSheet
import { createStyleSheetT } from "functions";
/**
* Creates a CSS stylesheet string with the specified rules.
*
* @param rules - An array of CSS rules.
* @returns The generated CSS stylesheet as a string.
*/
export function createStyleSheet({ rules }: createStyleSheetT): string {
return rules.join("\n");
}
The createStyleSheet
function generates a CSS stylesheet string with the specified rules.
Parameters
rules
(string[]): An array of CSS rules.
Returns
- The generated CSS stylesheet as a string.
How to Use
To use the createCSSRule
and createStyleSheet
functions, follow these steps:
- Import the functions into your project:
import { createCSSRule, createStyleSheet } from "./path/to/functions";
- Use the functions in your code:
const cssRule = createCSSRule({
selector: "my-class",
styles: "color: red; font-size: 16px;",
});
console.log("Generated CSS rule:", cssRule);
const cssStylesheet = createStyleSheet({
rules: [
createCSSRule({ selector: "class-1", styles: "background-color: blue;" }),
createCSSRule({ selector: "class-2", styles: "background-color: green;" }),
],
});
console.log("Generated CSS stylesheet:", cssStylesheet);
Make sure to provide the necessary parameters and handle the generated CSS rule or stylesheet as needed in your application.
getInitials
/**
* Returns the initials of a given name.
* If the name is composed of multiple words, it takes the first letter of each word.
* If the name is empty, it returns an empty string.
* @param name - The name to get the initials from.
* @param maxLength - Optional parameter to specify the maximum number of characters to return. If not provided or if the resulting string is shorter than the specified length, it returns the full initials.
* @returns The initials of the given name, or an empty string if the name is empty.
*/
export function getInitials({
name,
maxLength = 2,
}: {
name: string;
maxLength?: number;
}): string {
if (!name) return "";
const words = name.trim().split(/\s+/);
let initials = "";
for (const word of words) {
initials += word[0].toUpperCase();
if (maxLength && initials.length >= maxLength) break;
}
return initials;
}
The getInitials
function returns the initials of a given name. If the name is composed of multiple words, it takes the first letter of each word. If the name is empty, it returns an empty string.
Parameters
name
(string): The name to get the initials from.maxLength
(number, optional): Optional parameter to specify the maximum number of characters to return. If not provided or if the resulting string is shorter than the specified length, it returns the full initials.
Returns
- The initials of the given name, or an empty string if the name is empty.
How to Use
To use the getInitials
function, follow these steps:
- Import the function into your project:
import { getInitials } from "./path/to/functions";
- Use the function in your code:
const initials = getInitials({ name: "John Doe", maxLength: 2 });
console.log("Initials:", initials);
Make sure to provide the necessary parameters and handle the returned initials as needed in your application.
getPropValueGetters
/**
* Retrieves the property value getter function based on the component type.
* @param componentType - The component type.
* @returns The property value getter function or undefined if not found.
*/
export function getPropValueGetters({
componentType,
}: {
componentType: string;
}) {
let STRforced = false;
const CTString = componentType
.split(/(?=[A-Z])/)
.filter((item) => {
const itemLowerCase = item.toLowerCase();
if (itemLowerCase === "str" || itemLowerCase === "string") {
STRforced = true;
}
return itemLowerCase !== "str" && itemLowerCase !== "string";
})
.join("-")
.toLowerCase();
if (cssPropertyMappings[componentType] === undefined && !STRforced) {
return undefined;
} else if (alternative[CTString]) {
return alternative[CTString];
}
return (propValue: string): string => {
return `${CTString} : ${propValue};`;
};
}
export enum cssPropertyMappings {}
// List of CSS property mappings
export const alternative = {
// List of alternative property value getter functions
};
The getPropValueGetters
function retrieves the property value getter function based on the component type.
Parameters
componentType
(string): The component type.
Returns
- The property value getter function or
undefined
if not found.
How to Use
To use the getPropValueGetters
function, follow these steps:
- Import the function into your project:
import { getPropValueGetters } from "./path/to/functions";
- Use the function in your code:
const propValueGetter = getPropValueGetters({ componentType: "borderColor" });
console.log("Property Value Getter:", propValueGetter);
The propValueGetter
variable will contain the property value getter function for the specified component type. You can then use this function to generate the desired property value based on a provided value.
Note: The cssPropertyMappings
enum and alternative
object in the code represent placeholders for the actual mappings and alternative property value getter functions. Make sure to update them with the appropriate values according to your application's needs.
Make sure to provide the necessary parameters and handle the returned property value getter function as needed in your application.
getPropValueWithBreakpoint
/**
* Retrieves the property value with the specified breakpoint.
* @param propValue - The property value.
* @param breakPoint - The breakpoint to consider.
* @returns The property value with the specified breakpoint or undefined.
* @throws {Error} - If an invalid propValue or breakpoint is provided.
*/
export function getPropValueWithBreakpoint({
propValue,
breakPoint,
}: getPropValueWithBreakpointT): string | undefined {
if (typeof propValue === "string") {
return propValue as string;
} else if (
typeof propValue === "object" &&
propValue !== null &&
breakPoint !== undefined
) {
if (propValue[breakPoint]) return propValue[breakPoint] as string;
for (const e of Object.keys(breakpoints)) {
if (e <= breakPoint && propValue[e]) {
return propValue[e] as string;
}
if (e > breakPoint) {
return propValue[e] as string;
}
}
throw new Error(
`Invalid propValue for breakpoint ${breakPoint} and propValue ${propValue}`
);
} else if (typeof propValue === "undefined") {
const Location = new Error().stack?.split("\n")[2];
throw new Error(`Invalid propValue ${propValue} at ${Location}`);
}
}
The getPropValueWithBreakpoint
function retrieves the property value with the specified breakpoint.
Parameters
propValue
(string | object): The property value.breakPoint
(string): The breakpoint to consider.
Returns
- The property value with the specified breakpoint or
undefined
.
Throws
Error
: If an invalidpropValue
orbreakpoint
is provided.
How to Use
To use the getPropValueWithBreakpoint
function, follow these steps:
- Import the function into your project:
import { getPropValueWithBreakpoint } from "./path/to/functions";
- Use the function in your code:
const propValue = { base: "10px", md: "20px", lg: "30px" };
const breakPoint = "md";
const result = getPropValueWithBreakpoint({ propValue, breakPoint });
console.log("Result:", result);
The result
variable will contain the property value with the specified breakpoint. If a value for the exact breakpoint exists in the propValue
object, that value will be returned. Otherwise, the function will find the nearest breakpoint based on the provided breakPoint
and return the corresponding value. If no value is found, undefined
will be returned.
Note: The breakpoints
object in the code represents the breakpoints mapping. Make sure to update it with the appropriate breakpoints and values according to your application's needs.
Make sure to provide the necessary parameters and handle the returned property value as needed in your application.
handleDragStart
/**
* Handles the drag start event.
* @param onDragStart - The callback function to execute on drag start.
* @param event - The drag start event object.
* @param dragRef - The drag reference object.
* @returns void
*/
export function handleDragStart({
onDragStart,
event,
dragRef,
}: handleDragStartT): void {
event.stopPropagation();
if (onDragStart) onDragStart(event);
if (dragRef.current) {
event.dataTransfer.setData("text/plain", dragRef.current.id);
event.dataTransfer.effectAllowed = "move";
}
}
The handleDragStart
function is responsible for handling the drag start event.
Parameters
onDragStart
(function): The callback function to execute on drag start.event
(DragEvent): The drag start event object.dragRef
(RefObject): The drag reference object.
Returns
void
How to Use
To use the handleDragStart
function, follow these steps:
- Import the function into your project:
import { handleDragStart } from "./path/to/functions";
- Use the function in your code:
function MyComponent() {
const dragRef = useRef(null);
const handleOnDragStart = (event) => {
console.log("Drag started!");
};
const handleDragStartEvent = (event) => {
handleDragStart({
onDragStart: handleOnDragStart,
event,
dragRef,
});
};
return (
<div draggable="true" ref={dragRef} onDragStart={handleDragStartEvent}>
Drag me!
</div>
);
}
In the example above, handleDragStart
is used to handle the drag start event. The handleOnDragStart
function is passed as the onDragStart
callback, which will be executed when the drag starts. The event
object and dragRef
are also provided as parameters.
Ensure that you have a draggable element and assign the handleDragStartEvent
function to the onDragStart
event handler.
Customize the implementation of handleOnDragStart
to perform the desired actions when the drag starts.
Make sure to provide the necessary parameters and handle the event accordingly in your application.
Sure! Here's the documentation for the isDark
function:
isDark
/**
* Determines if a given color is considered "dark" or "light".
* @param color - The color string to check.
* @returns True if the color is considered "dark", false otherwise.
* @throws An error if the color string is not in the format "hsl(H, S%, L%)", where H is the hue value, S is the saturation value, and L is the lightness value.
*/
export function isDark({ color }: { color: string }): boolean;
The isDark
function is a utility that helps determine if a given color is considered "dark" or "light" based on the HSL (Hue, Saturation, Lightness) color model. It takes a color string as input and returns true
if the color is considered "dark," and false
otherwise.
Parameters
color
: The color string to be evaluated. It should be in the format "hsl(H, S%, L%)", where H represents the hue value, S represents the saturation value, and L represents the lightness value.
Returns
- A boolean value indicating whether the color is considered "dark" (
true
) or "light" (false
).
Throws
- An error is thrown if the provided color string does not adhere to the required format of "hsl(H, S%, L%)".
Usage
To use the isDark
function, follow these steps:
- Import the
isDark
function into your file:
import { isDark } from "isDark";
- Call the
isDark
function with the color string you want to evaluate:
const color = "hsl(200, 50%, 20%)";
const isColorDark = isDark({ color });
console.log(isColorDark); // Output: true
In the example above, the isDark
function is used to determine if the color 'hsl(200, 50%, 20%)'
is considered "dark" or "light." The function returns true
since the color has a lightness value below 128, indicating a "dark" color.
Please ensure that the color string you provide follows the correct format of "hsl(H, S%, L%)" to avoid any errors.
The isDark
function can be helpful in various scenarios where you need to assess the brightness of a color and make decisions based on its perceived darkness or lightness.
randomColor
/**
* Generates a random HSL color based on a given seed string.
* @param seed - The seed string used to generate the color.
* @returns A random HSL color in the format "hsl(H, S%, L%)", where H is the hue value, S is the saturation value, and L is the lightness value.
*/
export function randomColor({ seed }: { seed?: string } = {}): string;
The randomColor
function generates a random HSL (Hue, Saturation, Lightness) color based on a given seed string. It returns a string representation of the color in the format "hsl(H, S%, L%)", where H represents the hue value, S represents the saturation value, and L represents the lightness value.
Parameters
seed
(optional): The seed string used to generate the random color. If not provided, a random seed string will be generated internally. The seed string helps ensure that the generated color remains consistent for a given seed.
Returns
- A string representing a random HSL color in the format "hsl(H, S%, L%)".
Usage
To use the randomColor
function, follow these steps:
- Import the
randomColor
function into your file:
import { randomColor } from "randomColor";
- Call the
randomColor
function to generate a random color:
const color = randomColor();
console.log(color); // Output: e.g., "hsl(200, 100%, 70%)"
In the example above, the randomColor
function is called without any arguments, generating a random HSL color. The function returns a string representing the color, such as "hsl(200, 100%, 70%)".
If you want to generate a consistent color based on a specific seed string, you can provide the seed
parameter:
const seed = "mySeed";
const color = randomColor({ seed });
console.log(color); // Output: e.g., "hsl(120, 100%, 70%)"
By using the same seed
value, you can ensure that the generated color remains the same across multiple invocations.
The randomColor
function can be useful in scenarios where you need to generate random colors dynamically, such as for visualizations, user interfaces, or data representation.
Please note that the generated colors are pseudorandom and deterministic based on the provided seed.
RecoveryBreakPointValue
/**
* Retrieves the current breakpoint value from the global context.
* @returns The current breakpoint value as a string.
*/
export function RecoveryBreakPointValue(): string;
The RecoveryBreakPointValue
function is responsible for retrieving the current breakpoint value from the global context. It returns the current breakpoint value as a string.
Usage
To use the RecoveryBreakPointValue
function, follow these steps:
- Import the
RecoveryBreakPointValue
function and the necessary dependencies into your file:
import { useGlobalContext } from "hooks";
import { GlobalContext } from "provider";
- Call the
RecoveryBreakPointValue
function to retrieve the current breakpoint value:
const breakpointValue = RecoveryBreakPointValue();
console.log(breakpointValue); // Output: The current breakpoint value as a string
In the example above, the RecoveryBreakPointValue
function is called to retrieve the current breakpoint value from the global context. The function returns the breakpoint value as a string.
Please note that you need to ensure that the useGlobalContext
hook is set up correctly and that the GlobalContext
provider is properly configured to provide the breakpoint value to the RecoveryBreakPointValue
function.
If the breakpointValue
exists in the global context, it will be returned. Otherwise, the function will return the string "base" as a fallback value.
The RecoveryBreakPointValue
function can be useful in scenarios where you need to access and utilize the current breakpoint value within your application logic or UI components.
It's important to have a proper understanding of the useGlobalContext
hook and the GlobalContext
provider to ensure the correct usage of the RecoveryBreakPointValue
function.
safeJSON
/**
* Safely converts an object to a JSON string, handling circular references.
* @param {unknown} obj - The object to convert to JSON.
* @param {(key: string, value: unknown) => unknown} replacer - A function that alters the behavior of stringifying objects. Optional.
* @param {string | number} indent - The number of spaces to use for indentation or a string to use for indentation. Optional.
* @returns {string} - The JSON string representation of the object.
*/
export function safeJSON({ obj, replacer, indent }: safeJSONT): string;
The safeJSON
function is responsible for safely converting an object to a JSON string, handling circular references. It takes in an object obj
to convert, an optional replacer
function that can alter the behavior of stringifying objects, and an optional indent
parameter that specifies the indentation format for the resulting JSON string.
Usage
To use the safeJSON
function, follow these steps:
- Import the
safeJSON
function and the necessary dependencies into your file:
import { safeJSONT } from "functions";
- Call the
safeJSON
function with the appropriate parameters:
const jsonObject = {
/* Your object here */
};
const jsonString = safeJSON({ obj: jsonObject, replacer: null, indent: 2 });
console.log(jsonString); // Output: The JSON string representation of the object
In the example above, the safeJSON
function is called to convert an object jsonObject
to a JSON string. The replacer
parameter is set to null
and the indent
parameter is set to 2
spaces for indentation. The function returns the JSON string representation of the object.
The replacer
parameter allows you to provide a custom function that alters the behavior of stringifying objects. This can be useful for selectively including or excluding certain properties or transforming values before stringification. If not provided, the default behavior of JSON.stringify
is used.
The indent
parameter determines the indentation format of the resulting JSON string. It can be either a number specifying the number of spaces to use for indentation or a string (e.g., "\t") to use for indentation. If not provided, the JSON string will not be indented.
The safeJSON
function handles circular references in objects by replacing them with the string "Circular". This helps prevent errors that can occur when stringifying objects with circular references.
Please note that the safeJSON
function relies on the JSON.stringify
method to perform the stringification. Therefore, it supports the same data types and limitations as the native JSON.stringify method.
Ensure that the safeJSON
function is used when you need to convert objects to JSON strings and handle circular references in a safe manner.