@hnine-dev/scss-utils

@hnine-dev/scss-utils is a utility library that provides SCSS functions and mixins to simplify the styling process. This library offers reusable SCSS functions and mixins that can be easily imported and used in your projects.

Installation

To install the package, use npm or yarn:

npm install @hnine-dev/scss-utils

or

yarn add @hnine-dev/scss-utils

Usage

To use the SCSS functions and mixins provided by this library, you need to import them into your SCSS files. Below are the recommended ways to import the utilities:

Import All Utilities

To import all utilities at once, use the following import statement:

@import "@hnine-dev/scss-utils";

Import Specific Utilities

If you prefer to import only specific utilities, you can do so by importing the functions and mixins separately:

Import Functions

@import "@hnine-dev/scss-utils/functions";

Import Mixins

@import "@hnine-dev/scss-utils/mixins";

Functions

The library provides several useful SCSS functions. Here are some examples:

get-token-in-map($map, $token)

Retrieves the value of a token from a nested map structure. If the token is not found, it returns null.

• $map: The map to search within.
• $token: The token to search for.

$color: (
  level1: (
    level2: (
      level3: (
        level4-color: #654321,
      ),
    ),
  ),
);

.element {
  background-color: get-token-in-map($color, level4-color); // #654321
}

convert-to-kebab($text)

Converts a camelCase or PascalCase string to kebab-case. If the input string is empty, it throws an error.

• $text: The camelCase or PascalCase string to convert.

Usage Example:

$myClass: convert-to-kebab("camelCaseString");

.element {
  &--#{$myClass}; // .element--camel-case-string
}

extract-suffix($string, $delimiter)

Extracts the substring after the last occurrence of a specified delimiter. If the delimiter is not found or is at the end of the string, an error is thrown.

• $string: The string from which to extract the suffix.
• $delimiter: The delimiter to look for (default is "-").

Usage Example:

$myString: "level1-level2-level3";

$suffix: extract-suffix($myString); // "level3"

Mixins

The library also provides several useful SCSS mixins. Here are some examples:

disabled($bg-color, $text-color, $important)

Applies styles for a disabled state with customizable background color, text color, and importance.

• $bg-color: The background color for the disabled state.
• $text-color: The text color for the disabled state.
• $important: An optional flag to add !important to the styles.

.button {
  @include disabled(#ccc, #666, !important);
}

border($thickness, $color, $position)

Applies border styles with customizable thickness, color, and position.

• $thickness: The thickness of the border (default: 1px).
• $color: The color of the border (default: transparent).
• $position: The position of the border, which can be outline, inline, or center (default: outline).

.box {
  @include border(2px, #000, outline);
}

• outline: Applies a solid border around the element.
• inline: Applies an inset box-shadow to simulate an inner border.
• center: Splits the border thickness between an outer border and an inset box-shadow.

display($display, $justify, $align, $direction, $gap)

Sets the display property with additional flexbox options.

• $display: The display type to be set (e.g., flex, block, inline-block).
• $justify: The justify-content property for flexbox (default: center).
• $align: The align-items property for flexbox (default: null).
• $direction: The flex-direction property for flexbox (default: null).
• $gap: The gap property for flexbox (default: null).

.container {
  @include display(flex, space-between, center, row, 10px);
}

Contributing

If you would like to contribute to this project, please fork the repository and submit a pull request. We welcome all contributions that improve the library.

License

This project is licensed under the MIT License. See the LICENSE file for more details.