Dawuti - Worköholics utils package

Dawuti is a package with different utils implemented by Worköholics development team. Here you can find individual utilities to resolve common funcionalities for different languages or technologies (Sass, JS, TS...).

[[TOC]]

Installation

Dawuti is a NPM package hosted on the NPM public registry (https://www.npmjs.com/). You can install de package executing the following command:

npm install -D dawuti

Sass

Configuration and Usage

To configure Sass utils within Dawuti you can create a dawuti.scss or dawuti.config.scss file into your project.

If you don't need to override the default variables skip this step and use directly the package from node_modules.

@use "dawuti" as *;

If you need to change the default value of variables include override declarations in the dawuti.scss or dawuti.config.scss file of your project and then use it as the entrypoint.

// Override variables in dawuti.scss or dawuti.config.scss
@forward 'dawuti' with (
  $s: 8px,
  $breakpoint-xs: 470px
);

// Use dawuti from dawuti.scss or dawuti.config.scss in your scss main file. (For example styles.scss)
@use 'dawuti' as dawuti;

You can override the following sass variables:

$breakpoint-xs: 576px !default;
$breakpoint-sm: 768px !default;
$breakpoint-md: 992px !default;
$breakpoint-lg: 1200px !default;
$breakpoint-xl: 1600px !default;
$breakpoint-xxl: 2400px !default;

$s: 5px !default;
$gutter: 15px !default;
$cols: 12 !default;

$wrapper-centered-xs: 540px !default;
$wrapper-centered-sm: 720px !default;
$wrapper-centered-md: 960px !default;
$wrapper-centered-lg: 1140px !default;
$wrapper-centered-xl: 1540px !default;
$wrapper-centered-xxl: 2340px !default;

You can also override the variables changing the value of his correspondent CSS variable on the :root of your project.

For example, if you want to override the column quantity of the grid ($cols) to 6, you can do:

:root {
  --cols: 6
}

Utilities

Sass utils are implemented using mixins or funtions. Mixins can be used individually to optimize the compiled css bundle of the project, so only include the mixins you need within the project.

Accessibility

Utilities to resolve accessibility features.

Accessibility all

Mixin to include all accessibility features of Dawuti.

Usage

@include accessibility-all();

Sr-only

Mixin that include the utility class .sr-only. This class hide elements of the DOM but mantains the visibility for the screen reader.

Usage

@include sr-only();

Prefers motion

A mixin that can be used to adopt a "no-motion" first approach, ensuring that animations and transitions are only displayed to users who have no preference regarding motion.

Focus native styles

Add native focus styles if for some reason were removed or if it is necessary to add them by another selector such as :focus-within

@include focus-native-styles();

Hover

Apply hover styles only in devices which primary input mechanism can hover over elements. Can be used in elements like cards or to avoid unwanted interactions triggered by the :hover selector.

@include hover();

Usage

//animation only for users with no-preference
@include prefers-motion() {
  animation: animationName 5s linear infinite;
}

//animation faster only for user with no-preference
--animation-duration: 20s;
@include prefers-motion() {
  --animation-duration: 5s;
}
animation: animationName var(--animation-duration) linear infinite;

Animations

Usage

In order to use an animation in your project.

1. Declare the animation in a global/animations stylesheet:

   _animations.scss

   @include animate-use-opacity();

2. Animate a specific element:

   _component1.scss

   .component1{
     @include animate-opacity(1s 3s ease-in forwards, 0.2, 0.5);
   }

• Note that we don't pass the "animation-name" as it will be added later by the mixin.

Exceptions

The following mixins don't need to be declared before usage:

dawuti.animate-transforms

Just use it, passing a different ref each time. This will create a different keyframe for each ref. Example:

      .el1{
        @include animate-transforms("1", "0", "100px", "0deg", "360deg", "0", 1 );
      }

Here we pass 1 as ref, which will generate a keyframe called transforms1. Once this is done you can reuse the generated animation in any other element: Example:

      .el2{ //reuse the animation used by .el
        animation: transforms1 1s 3s ease-in forwards;
      }

dawuti.animate-scale-elastic

    .el1{
      @include animate-scale-elastic("1", 1s 3s ease-in backwards, 1, 1.25, 1, 0%, 80%, 100%);
    }

dawuti.animate-delays

 .delays {
    > div {
      @include animate-opacity(1s 3s ease-in forwards, 0, 1); //use any animation
      @include animate-delays(1, 6, 0.2s); //specify delay between elements 
    }
  }

Here the list of available animations:

//animation declaration
@include animate-use-opacity(); 
@include animate-use-scale(); 
@include animate-use-translate();
@include animate-use-rotate();
@include animate-use-skew();
@include animate-use-transforms();
@include animate-use-dash(); //add (pathLength="1") to your <path> element
@include animate-use-filter();
//animation usage
@include animate-opacity(<animation>, $start, $end); //numbers
@include animate-scale(<animation>, $start, $end); //numbers
@include animate-translate(<animation>, $start-x, $start-y, $end-x, $end-y); //px, vw, vh...
@include animate-rotate(<animation>, $start, $end);
@include animate-skew(<animation>, $start-x, $start-y, $end-x, $end-y); //deg
@include animate-dash();
@include filter(<animation>, $start, $end); //numbers
@include animate-transforms($ref: "1", $translate-start-x:0, $translate-end-x: 0, $rotate-start: 0, $rotate-end: 0, $scale-start:0, $scale-end:0 );
@include animate-scale-elastic($ref: "1", <animation>, $start, $middle, $end, $p1: 0%, $p2: 80%, $p3: 100%)
@include animate-delays(1, 6, 0.2s);

You can check and try the animations at animations.html

Breakpoints

This mixin include css variables for the different breakpoints of a project. Remember that these variables can be overriden as is explained in 'Configuration and Usage' section.

@include breakpoints();

Helpers

Display helpers

Use this mixin to create helpers to manage the visibility of elements between breakpoints.

@include display-helpers();

Including the mixin, you can use the folowing classes to show or hide DOM elements:

• .hidden-xs : Hide element 0 < vw < SM
• .hidden-sm : Hide element SM < vw < MD
• .hidden-md : Hide element MD < vw < LG
• .hidden-lg : Hide element LG < vw < XL
• .hidden-xl : Hide element XL < vw < XXL
• .hidden-xxl : Hide element XXL < vw
• .hidden-sm-up : Hide element vw > SM
• .hidden-md-up : Hide element vw > MD
• .hidden-lg-up : Hide element vw > LG
• .hidden-xl-up : Hide element vw > XL
• .hidden-xxl-up : Hide element vw > XXL
• .hidden-sm-down : Hide element vw < SM
• .hidden-md-down : Hide element vw < MD
• .hidden-lg-down : Hide element vw < LG
• .hidden-xl-down : Hide element vw < XL
• .hidden-xxl-down : Hide element vw < XXL

Media queries

MQ XS

Create a media query for include rules to viewports wider or narrower (depending on the boolean parameter $down) than XS breakpoint:

@include mq-xs($down /* true or false */) {
  // Your scss rules
}

MQ SM

Create a media query for include rules to viewports wider or narrower (depending on the boolean parameter $down) than SM breakpoint:

@include mq-sm($down /* true or false */){
  // Your scss rules
}

MQ MD

Create a media query for include rules to viewports wider or narrower (depending on the boolean parameter $down) than MD breakpoint:

@include mq-md($down /* true or false */){
  // Your scss rules
}

MQ LG

Create a media query for include rules to viewports wider or narrower (depending on the boolean parameter $down) than LG breakpoint:

@include mq-lg($down /* true or false */){
  // Your scss rules
}

MQ XL

Create a media query for include rules to viewports wider or narrower (depending on the boolean parameter $down) than XL breakpoint:

@include mq-xl($down /* true or false */){
  // Your scss rules
}

MQ XXL

Create a media query for include rules to viewports wider or narrower (depending on the boolean parameter $down) than XXL breakpoint:

@include mq-xxl($down /* true or false */){
  // Your scss rules
}

MQ XXL

Create a media query for include rules to viewports wider or narrower (depending on the boolean parameter $down) than the width passed by the parameter $width:

@include mq-xxl($width, /*Width of the viewport*/ $down /* true or false */){
  // Your scss rules
}

Grid

//helpers with defaults: 12columns, single breakpoint from 'sm'
@include grid-helpers();

If the design requires changing columns in multiple breakpoints, or the number of columns is other than 12, we can pass the following parameters:

@include grid-helpers(12, ("xs", "sm", "md", "lg", "xl", "xxl"));

Use helper classes in out HTML:

<div class="grid">
  <!-- column from line 1 to line 13 -->
  <div class="grid__col grid__col--start-1 grid__col--end-13"></div>

  <!-- column from line 1 to line 13, and from 'sm' line 4 to line 12 -->
  <div class="grid__col grid__col--start-1 grid__col--end-13 grid__col--start-4-sm grid__col--end-12-sm"></div>
</div>

We can also use .grid.grid--autofit useful for columns to fit a minimum column width, which will be wrapped in new rows if needed. This can be applied in forms with multiple fields, that have a minimum width.

We can also use .grid-z to span all columns the entire width of the grid, so we can overlap elements and play with their z-index.

Actions wrapper

@include  actions-wrapper-helpers();

.actions-wrapper // <SM: center | >SM: start 
.actions-wrapper.actions-wrapper--start  // <SM: start  | >SM: start 
.actions-wrapper.actions-wrapper--center  // <SM: center | >SM: center

Reset

Mixins to manage rules to reset the defalt styles of the different browsers.

Reset all

This util includes all mixins related with the reset of the browser default styles.

@include reset-all();

Reset height

Adds 100% of height to body and html elements.

@include reset-height();

Reset line height

Adds default line height to all elements of the site with the * selector.

@include reset-line-height();

Reset form controls

Enables the inheritance of the font-family of form controls within a form.

@include reset-form-controls();

Reset box sizing

Enables border-box box sizing strategy to all elements of the site.

@include reset-box-sizing();

Reset margin

Removes al margings by default to all elements of the site.

@include reset-margin();

Reset media

Adds rules by default to media elements.

@include reset-media();

Reset font smoothing

Adds rules to avoid the blur of the tipography in some browsers.

@include reset-font-smoothing();

Reset Nav List

Removes the bullets and the padding of a list inside a nav.

@include reset-nav-list();

Space

Mixins to manage the spacing of the elements.

Space vars

Adds space css variables to the :root of your site. Remember that these variables can be overriden as is explained in 'Configuration and Usage' section.

@include space-vars();

These are the available css variables:

• --s
• --gutter
• --safe-area
• --cols

Size by cols

Function to calculate the size by given size and total in columns.

// $cols: Width in cols
// $total: Total of columns, optional parameter (by default 12)

.selector{
  width: dawuti.size-by-cols($cols, $total);
}

Wrappers

Utils to manage the main wrappers of the site. Remember that breakpoint and wrapper variables can be overriden as is explained in 'Configuration and Usage' section.

Wrappers all

Enables .wrapper-centered and .wrapper-fluid. This usage is extrange but Maybe you need both wrappers in the same site. Normaly you only need one of them.

@include wrappers-all();

Wrapper fluid

Enables .wrapper-fluid in your site to align the content properly depending on the size of the viewport, the breakpoints and the safe area.

@include wrappers-fluid();

Wrapper centered

Enables .wrapper-centered in your site to center and align the content properly depending on the size of the viewport and the breakpoints.

@include wrappers-centered();

Text

Balance text and avoid orphans:

@include enhance-text();