@theholocron/ahsoka

Ahsoka

This provides a set of single-purpose, functional utilities for writing (S)CSS animations within the Galaxy.

Installation

$ npm install --save-dev @theholocron/ahsoka

Table of Contents

• Usage
• Documentation
• Change Log
• Versioning
• Contribution
• Tools
• Support
• License

Usage

If you're using (S)CSS, preferably dart-sass, then there are a few ways you can import. Each of these will produce a CSS class that can then be used within your HTML.

// _index.scss

// include all animations with 'ahsoka' as the namespace
// calls all mixins and will include in CSS output
@use "./node_modules/@theholocron/ahsoka/src" as ahsoka;
// call the mixin
@include ahsoka.bounce-back-forth();

// use all animations with a different base class
// calls all mixins and will include in CSS output
@use "./node_modules/@theholocron/ahsoka/src" as ahsoka with (
    $base-class: 'my-animation-class'
);
// call the mixin
@include ahsoka.bounce-back-forth();

// include only a specific group of mixins
@use "./node_modules/@theholocron/ahsoka/src/bounce as *";
// call the mixins from this group
@include bounce-back-forth();
@include bounce-out-down();

// use only a specific mixin
@use "./node_modules/@theholocron/ahsoka/src/bounce/back-forth";
// call the mixin you want to use
@include bounce-back-forth();
// call the mixin you want, but override this animations base class
@include bounce-back-forth('.another-class');

If you only want the CSS, there are several configurations you can choose. The following uses unpkg as a CDN, so all of the rules apply to retrieving a specific version or file.

• The [@<semver>] is an optional field that allows you to pick a specific version, or if you omit it will grab the latest tagged version.
• The [min] is optional as well, but highly recommended if you're going to call the CSS file directly in your HTML, as its minified.
• The <type> is a required field that allows one to pick a specific group of animations to include or include the entire set. The following are allowed types:
  • ahsoka - the entire collection
  • bounce - only include the bounce animations
  • fade - only include the fade animations
  • slide - only include the slide animations

<link rel="stylesheet" href="https://unpkg.com/@theholocron/ahsoka[@<semver>]/dist/<type>.[min].css" />

Once you've determined how you're going to include the files, then copy the code below, swapping out the <animation-name> for one of the ones in a collection. Add .infinite to keep the animation going on forever. And if you change out the $base-class, as in one of the examples above, then be sure to swap out ahsoka for that.

<div class="animate <animation-name>">Text</div>

The previous examples are only a sample of what utilities are available.

Where to Find Documentation

The best way to find out what's available is to check out the source code or test but you can also take a look at the-holocron.github.io/ahsoka or the README which have been generated by SassDoc and sassdoc-to-markdown.

• Bounce - these animations come from the opposite direction listed in the class (named after the direction it travels) and go slightly past the target and then oscillating a bit giving it the appearance of momentum and bounce.
• Fade - these animations are a bit more subtle. They still come from the opposite direction listed in the class (named after the direction it travels) but they transition the opacity of the element instead.
• Slide - these animations come from the opposite direction listed in the class (named after the direction it travels) with a smooth transition.

How We Track Changes

This project uses a CHANGELOG and GitHub releases which contains a curated, chronologically ordered list of notable changes for each version of a project. Read more about changelogs.

How We Version

We use SemVer for its versioning providing us an opt-in approach to releases. This means we add a version number according to the spec, as you see below. So rather than force developers to consume the latest and greatest, they can choose which version to consume and test any newer ones before upgrading. Please the read the spec as it goes into further detail.

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes.
• MINOR version when you add functionality in a backward-compatible manner.
• PATCH version when you make backward-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

How to Contribute

Have a bug or a feature request? Looking to contribute to advance the project? Read our contribution guide or maintenance guide first in order to understand how we do things around here. Or you could look at some of our other guides below:

How do I… (click to expand)

• Ask or Say Something?
  • Request Support
  • Report an Error or Bug
  • Request a Feature
• Make Something?
  • Setup the Project
  • Create an Issue
  • Create a Feature Request
  • Contribute Documentation
  • Contribute Code
  • Join the Team
• Manage Something
  • Provide Support on Issues
  • Label Issues
  • Clean Up Issues and PRs
  • Create a Pull Request
  • Review Pull Requests
  • Merge Pull Requests
  • Tag a Release
  • Release a Version

Where to Find Support

Looking to talk to someone or need some help? Please read our support guidelines.

Tools We Use

• Browserslist - Used to share to our code which browsers we support
• CommitLint - Used to ensure our commits follow our standards
• Dart Sass - Used to compile (S)CSS
• Conventional Changelog - Used to generate our CHANGELOG
• Husky - Used for auto-fixing linting errors on each commit
• MarkdownLint - Used to lint our Markdown docs
• PostCSS - Used to compile (S)CSS
• Semantic Release - Used for automating and releasing our library
• StyleLint - Used to lint our (S)CSS
• True - Used to test our (S)CSS mixins and functions
• @godban's Browser Support Badges - The tool used to generate the "Which Browsers [sic] We Support" section

References

• Conventional Commits - For how we format commit messages
• Contributor Convenant
• Keep a Changelog - For building out a quality CHANGELOG
• Make a README - For building out this README
• SemVer - For versioning this library

License

©2020 GNU General Public License v3. See LICENSE for specifics.