css-in-js-utilities

CSS-in-JS Utilities

A modern, comprehensive collection of helper functions and utilities for CSS-in-JS libraries. This package provides a set of TypeScript utilities to speed up common styling tasks and improve consistency in your React projects.

Features

• Layout helpers (Flexbox and Grid)
• Responsive design utilities
• Typography helpers
• Effects (shadows and transitions)
• Color utilities
• Animation helpers

Installation

Install the package using npm:

npm install css-in-js-utilities

or

yarn add css-in-js-utilities

Usage

Import the utilities you need from the package:

Flex Layout

import { flexContainer } from 'css-in-js-utilities';

// Create a flex container with default values
const defaultContainer = flexContainer();
// Result:
// {
//   display: 'flex',
//   flexDirection: 'row',
//   justifyContent: 'flex-start',
//   alignItems: 'stretch'
// }

// Create a custom flex container
const customContainer = flexContainer('column', 'space-between', 'center');
// Result:
// {
//   display: 'flex',
//   flexDirection: 'column',
//   justifyContent: 'space-between',
//   alignItems: 'center'
// }

Parameters

• direction: 'row' | 'column' (default: 'row')
• justify: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' (default: 'flex-start')
• align: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' (default: 'stretch')

import { flexItem } from 'css-in-js-utilities';
// Create a flex item with default values
const defaultItem = flexItem();
// Result:
// {
//   flexGrow: 0,
//   flexShrink: 1,
//   flexBasis: 'auto'
// }

// Create a custom flex item
const customItem = flexItem(2, 1, '100px');
// Result:
// {
//   flexGrow: 2,
//   flexShrink: 1,
//   flexBasis: '100px'
// }

Parameters

• grow: number (default: 0)
• shrink: number (default: 1)
• basis: string (default: 'auto')

Grid Layout

Import the grid utilities from the package:

import { gridContainer, gridItem } from 'css-in-js-utilities';

// Create a grid container with default values
const defaultGrid = gridContainer();
// Result:
// {
//   display: 'grid',
//   gridTemplateColumns: 'repeat(1, 1fr)',
//   gridTemplateRows: 'auto',
//   gap: '1rem',
//   justifyItems: 'stretch',
//   alignItems: 'stretch',
//   justifyContent: 'start',
//   alignContent: 'start'
// }

// Create a custom grid container
const customGrid = gridContainer(3, 2, '20px', 'center', 'end', 'space-between', 'space-around');
// Result:
// {
//   display: 'grid',
//   gridTemplateColumns: 'repeat(3, 1fr)',
//   gridTemplateRows: 'repeat(2, 1fr)',
//   gap: '20px',
//   justifyItems: 'center',
//   alignItems: 'end',
//   justifyContent: 'space-between',
//   alignContent: 'space-around'
// }

// Create a grid item with default values
const defaultItem = gridItem();
// Result:
// {
//   gridColumnStart: 'auto',
//   gridColumnEnd: 'auto',
//   gridRowStart: 'auto',
//   gridRowEnd: 'auto',
//   justifySelf: 'stretch',
//   alignSelf: 'stretch'
// }

// Create a custom grid item
const customItem = gridItem(1, 3, 2, 4, 'start', 'center');
// Result:
// {
//   gridColumnStart: 1,
//   gridColumnEnd: 3,
//   gridRowStart: 2,
//   gridRowEnd: 4,
//   justifySelf: 'start',
//   alignSelf: 'center'
// }

gridContainer Parameters

• columns: number | string (default: 1)
• rows: number | string (default: 'auto')
• gap: string (default: '1rem')
• justifyItems: 'start' | 'end' | 'center' | 'stretch' (default: 'stretch')
• alignItems: 'start' | 'end' | 'center' | 'stretch' (default: 'stretch')
• justifyContent: 'start' | 'end' | 'center' | 'stretch' | 'space-around' | 'space-between' | 'space-evenly' (default: 'start')
• alignContent: 'start' | 'end' | 'center' | 'stretch' | 'space-around' | 'space-between' | 'space-evenly' (default: 'start')

gridItem Parameters

• colStart: number | 'auto' (default: 'auto')
• colEnd: number | 'auto' (default: 'auto')
• rowStart: number | 'auto' (default: 'auto')
• rowEnd: number | 'auto' (default: 'auto')
• justifySelf: 'start' | 'end' | 'center' | 'stretch' (default: 'stretch')
• alignSelf: 'start' | 'end' | 'center' | 'stretch' (default: 'stretch')

Responsive Design

Import the responsive utility from the package:

import { responsive } from 'css-in-js-utilities';

// Create responsive styles
const responsiveStyles = responsive({
  display: { base: 'block', md: 'flex' },
  flexDirection: { base: 'column', lg: 'row' },
  padding: { base: '1rem', lg: '2rem' },
  fontSize: { base: '14px', md: '16px', xl: '18px' },
});

// Result:
// {
//   display: 'block',
//   flexDirection: 'column',
//   padding: '1rem',
//   fontSize: '14px',
//   '@media (min-width: 768px)': {
//     display: 'flex',
//     fontSize: '16px'
//   },
//   '@media (min-width: 1024px)': {
//     flexDirection: 'row',
//     padding: '2rem'
//   },
//   '@media (min-width: 1280px)': {
//     fontSize: '18px'
//   }
// }

The responsive function allows you to define styles that change based on screen size. It uses the following breakpoints:

• sm: 640px
• md: 768px
• lg: 1024px
• xl: 1280px
• 2xl: 1536px

Transitions

Import the transition utilities from the package:

import { transition, multipleTransitions } from 'css-in-js-utilities';

// Create a single transition
const singleTransition = transition('opacity', 300, 'ease-in-out', 100);
// Result:
// {
//   transition: 'opacity 300ms ease-in-out 100ms'
// }

// Create multiple transitions
const multiTransition = multipleTransitions(
  transition('opacity', 300, 'ease-in-out'),
  transition('transform', 500, 'ease-out', 100)
);
// Result:
// {
//   transition: 'opacity 300ms ease-in-out 0ms, transform 500ms ease-out 100ms'
// }

Parameters for transition:

• property: TransitionProperty (default: 'all')
• duration: number (in milliseconds, default: 300)
• timing: TransitionTiming (default: 'ease')
• delay: number (in milliseconds, default: 0)

The multipleTransitions function accepts any number of transition objects created by the transition function.

Shadows

Import the shadow utilities from the package:

import { boxShadow, textShadow } from 'css-in-js-utilities';

// Create a box shadow
const defaultBoxShadow = boxShadow();
// Result:
// {
//   boxShadow: '0px 2px 4px 0px rgba(0, 0, 0, 0.1)'
// }

// Create a custom box shadow
const customBoxShadow = boxShadow('lg', 'rgba(0, 0, 255, 0.2)', true);
// Result:
// {
//   boxShadow: 'inset 0px 4px 8px 0px rgba(0, 0, 255, 0.2)'
// }

// Create a text shadow
const defaultTextShadow = textShadow();
// Result:
// {
//   textShadow: '0px 2px 4px rgba(0, 0, 0, 0.1)'
// }

// Create a custom text shadow
const customTextShadow = textShadow('xl', 'rgba(255, 0, 0, 0.3)');
// Result:
// {
//   textShadow: '0px 8px 16px rgba(255, 0, 0, 0.3)'
// }

Parameters for boxShadow:

• size: 'sm' | 'md' | 'lg' | 'xl' | '2xl' (default: 'md')
• color: string (default: 'rgba(0, 0, 0, 0.1)')
• inset: boolean (default: false)

Parameters for textShadow:

• size: 'sm' | 'md' | 'lg' | 'xl' | '2xl' (default: 'md')
• color: string (default: 'rgba(0, 0, 0, 0.1)')

Typography

Import the typography utilities from the package:

import { fontSize, fontWeight, lineHeight, letterSpacing, textAlign, textTransform, fontFamily, textDecoration, fontStyle, createTypography } from 'css-in-js-utilities';

// Create font size styles
const responsiveFontSize = fontSize({ base: '16px', md: '18px', lg: '20px' });
// Result:
// {
//   fontSize: '16px',
//   '@media (min-width: 768px)': { fontSize: '18px' },
//   '@media (min-width: 1024px)': { fontSize: '20px' }
// }

// Create font weight styles
const boldWeight = fontWeight('bold');
// Result: { fontWeight: 'bold' }

// Create line height styles
const customLineHeight = lineHeight(1.5);
// Result: { lineHeight: 1.5 }

// Create letter spacing styles
const wideLetterSpacing = letterSpacing('0.05em');
// Result: { letterSpacing: '0.05em' }

// Create text align styles
const centerAlign = textAlign('center');
// Result: { textAlign: 'center' }

// Create text transform styles
const uppercase = textTransform('uppercase');
// Result: { textTransform: 'uppercase' }

// Create font family styles
const sansSerif = fontFamily('Arial, sans-serif');
// Result: { fontFamily: 'Arial, sans-serif' }

// Create text decoration styles
const underline = textDecoration('underline');
// Result: { textDecoration: 'underline' }

// Create font style styles
const italic = fontStyle('italic');
// Result: { fontStyle: 'italic' }

// Create a complete typography preset
const headingTypography = createTypography('heading', { base: '24px', md: '32px' }, 'bold', 'center');
// Result:
// {
//   fontSize: '24px',
//   fontWeight: 'bold',
//   textAlign: 'center',
//   lineHeight: 1.2,
//   letterSpacing: '-0.02em',
//   '@media (min-width: 768px)': { fontSize: '32px' }
// }

Parameters for fontSize: size: Font size value or responsive object

Parameters for fontWeight: weight: Font weight value or responsive object Values: 'normal', 'bold', 'lighter', 'bolder', 100-900

Parameters for lineHeight: height: Line height value or responsive object

Parameters for letterSpacing: spacing: Letter spacing value or responsive object

Parameters for textAlign: align: Text alignment value or responsive object Values: 'left', 'right', 'center', 'justify'

Parameters for textTransform: transform: Text transform value or responsive object Values: 'none', 'capitalize', 'uppercase', 'lowercase'

Parameters for fontFamily: family: Font family value or responsive object

Parameters for textDecoration: decoration: Text decoration value or responsive object Values: 'none', 'underline', 'overline', 'line-through'

Parameters for fontStyle: style: Font style value or responsive object Values: 'normal', 'italic', 'oblique'

Parameters for createTypography:

• preset: Typography preset ('heading', 'subheading', 'body', 'caption')
• size: Font size value or responsive object
• weight: Font weight value or responsive object (default: 'normal')
• align: Text alignment value or responsive object (default: 'left')

All functions support responsive values using the Record type with Breakpoint keys.

Color Utilities

Import the color utilities from the package:

import { toRgba, lighten, darken, complementary, analogous } from 'css-in-js-utilities';

// Convert a color to RGBA format
const rgbaColor = toRgba('#FF5733', 0.8);
// Result: 'rgba(255, 87, 51, 0.8)'

// Lighten a color
const lightenedColor = lighten('#3366CC', 20);
// Result: '#6699FF'

// Darken a color
const darkenedColor = darken('#3366CC', 20);
// Result: '#003399'

// Generate a complementary color
const complementaryColor = complementary('#3366CC');
// Result: '#CC9933'

// Generate an analogous color
const analogousColor = analogous('#3366CC', 30);
// Result: '#3333CC'

These color utilities provide powerful functions for manipulating and generating colors in your CSS-in-JS projects.

Parameters:

• toRgba(color: string, alpha: number = 1): Converts a color to RGBA format. Alpha should be between 0 and 1.
• lighten(color: string, amount: number): Lightens a color by a percentage (0-100).
• darken(color: string, percentage: number): Darkens a color by a percentage (0-100).
• complementary(color: string): Generates a complementary color.
• analogous(color: string, angle: number = 30): Generates an analogous color. Angle should be between 1 and 359 degrees.

All functions accept colors in various formats (hex, rgb, rgba, hsl, named colors) and return results in uppercase hexadecimal format, except for toRgba which returns a rgba string.

Animation Helpers

Import the animation utilities from the package:

import { keyframe, animation, multipleAnimations } from 'css-in-js-utilities';

// Define keyframe animations
const fadeIn = keyframe('fadeIn', {
  from: { opacity: 0 },
  to: { opacity: 1 }
});
// Result: '@keyframes animation { from { opacity: 0; } to { opacity: 1; } }'

// Create a single animation
const fadeInAnimation = animation('fadeIn', '1s', 'ease-in-out');
// Result: 'fadeIn 1s ease-in-out 0s 1 normal none running'

// Combine multiple animations
const complexAnimation = multipleAnimations(
  animation('fadeIn', '1s'),
  animation('slideIn', '0.5s', 'ease-out', '0.2s')
);
// Result: { animation: 'fadeIn 1s ease 0s 1 normal none running, slideIn 0.5s ease-out 0.2s 1 normal none running' }

These animation utilities provide powerful functions for creating and combining keyframe animations in your CSS-in-JS projects.

Parameters:

• keyframe (name: string, frames: KeyframeStyles): Creates a keyframe animation string.
• animation (name: string, duration?: string | number, timingFunction?: string, delay?: string | number, iterationCount?: string | number, direction?: AnimationDirection, fillMode?: AnimationFillMode, playState?: AnimationPlayState): Creates an animation string.
• multipleAnimations (...animations: string[]): Combines multiple animations into a single animation string.

These functions allow you to create complex animations with ease, providing full control over all animation properties.

Contributing

We welcome contributions to CSS-in-JS Utilities! If you'd like to contribute, please follow these steps:

• Fork the repository
• Create your feature branch (git checkout -b feature/SpecificFeature)
• Commit your changes (git commit -m 'Add some SpecificFeature')
• Push to the branch (git push origin feature/SpecificFeature)
• Open a Pull Request

For more detailed information on contributing, please see our CONTRIBUTE.md file.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2024 Ameen Alade