JigSass Tools Bidi

Painless bidirectional style authoring

Installation

Using npm:

npm i -S jigsass-tools-bidi

Usage

@import 'path/to/jigsass-tools-bidi/scss/index';

Managing bi-directionality in CSS can be an annoying, time consuming and error-prone task.

JigSass Bidi was written to make this process as simple as possible, without sacrificing flxibilty. It eases the process of writing clean and maintainable bidirectional style sheets by using a single mixin to handle transformation of all direction-related styles (values and/or properties) by automatically interpreting directions as start`endinstead ofleft\right`.

Caveats

The background shorthand is not supported. Set the background-image and background-position properties directly.
When multi-dimensional lists are passsed to to $values argument (e.g., to border-radius, box-shadow, text-shadow or background-position), They should be passed as space separated lists inside a comma-separated list.
The X argument of backgrond-position and transform-origin can be transformed only if set to start, end or a number in percentage (%). transforming non-relative widths requires knowledge of the container's dimensions.

License: MIT

bidi

variables

jigsass-direction

$jigsass-direction: ltr !default;

Description

The direction in which styles should be outputted

Type

String

Used by

[function] _jigsass-get-side
[function] _jigsass-bidi-bgp
[mixin] jigsass-bidi
[mixin] jigsass-bidi-direction
[mixin] _jigsass-bidi-direction
[mixin] _jigsass-bidi-simple
[mixin] _jigsass-bidi-sides
[mixin] _jigsass-bidi-shadow
[mixin] _jigsass-bidi-bgi
[mixin] _jigsass-bidi-transform
[mixin] _jigsass-bidi-transform-origin
[mixin] _jigsass-bidi-bdrs

jigsass-bidi-rem-default

$jigsass-bidi-rem-default: if(
  global-variable-exists($jigsass-default-unit),
  $jigsass-default-unit == rem,
  false
) !default;

Description

Determines if jigsass-bidi will convert pixel values to rem by default when possible

Type

Boolean

mixins

jigsass-bidi

@mixin jigsass-bidi($property, $values, $bps: false, $rem: $jigsass-bidi-rem-default) { ... }

Description

Direction-agnostic styles

Ease the process of writing clean and maintainable bidirectional stylesheets by using a single mixin to handle transformation of all direction-related styles (values and/or properties) by interpreting directions as start`endinstead ofleft\right`.

Whether start is considered to be left or right depends on the direction set in $jigsass-direction.

Caveats (See Examples bellow):

The background shorthand is not supported. Set the background-image and background-position properties directly.
When multi-dimensional lists are passsed to to $values argument (e.g., to border-radius, box-shadow, text-shadow or background-position), They should be passed as space separated lists inside a comma-separated list.
The X argument of backgrond-position and transform-origin can be transformed only if set to start, end or a number in percentage (%). transforming non-relative widths requires knowledge of the container's dimensions.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$property`	—none	`String`	—none
`$values`	Values to process	`String` or `Number` or `List` or `Color`	—none
`$bps`	list of breakpoints to output the converted values in. `auto` iterates over the breakpoints defined in the `rhythm-unit` key of the sizes palette (from `jigsass-tools-typography`). `all` iterates over all length breakpoints. Only supports min-width media-queries.	`String` or `List` or `Boolean`	`false`
`$rem`	Indicates if pixel values should be converted into rems	`Boolean`	`$jigsass-bidi-rem-default`

Throws

jigsass-bidi: $jigsass-direction must be either ltr or rtl,
jigsass-tools-bidi has a dependency on jigsass-tools-typography for setting
jigsass-tools-bidi has a dependency on jigsass-tools-typography

Requires

[mixin] _jigsass-bidi
[variable] jigsass-direction

Example

Direction (start to end)

@include jigsass-bidi(diraction, ste); // -> ltr-mode: direction: ltr;
                                       //    rtl-mode: direction: rtl;

Direction (end to start)

@include jigsass-bidi(diraction, ets); // -> ltr-mode: direction: rtl;
                                       //    rtl-mode: direction: ltr;

start/end property

@include jigsass-bidi(margin-start, 6px); // -> ltr-mode: margin-left: 6px;
                                          //    rtl-mode: margin-right: 6px;

start/end value

@include jigsass-bidi(float, end); // -> ltr-mode: float: right;
                                   //    rtl-mode: float: left;

List of numbers

@include jigsass-bidi(margin, 0 8px 6px 12px); // -> ltr-mode: margin: 0 8px 6px 12px;
                                               //    rtl-mode: margin: 0 12px 6px 8px;

List of lists

@include jigsass-bidi(
  border-radius,
  (8px 12px 6px, 12px 14px)
 ); // -> ltr-mode: border-radius: 8px 12px 16px / 12px 14px;
    // -> rtl-mode: border-radius: 12px 8px 12px 16px / 14px 14px;

jigsass-bidi-direction

@mixin jigsass-bidi-direction($direction) { ... }

Description

Temporarily set the direction for the context of the mixin's execution.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$direction`	—none	`String`	—none

Content

This mixin allows extra content to be passed (through the @content directive).

Requires

[variable] jigsass-direction

Example

scss input

$jigsass-direction: ltr;

.ltr-component {
  @include jigsass-bidi(margin-start, 12px);
}

.rtl-component {
  @include jigsass-bidi-direction(rtl) {
    @include jigsass-bidi(margin-start, 12px);
  }
}

CSS output

.ltr-component {
  margin-left: 12px;
}

.rtl-component {
  margin-right: 12px;
}

[private] _jigsass-bidi-bdrs

@mixin _jigsass-bidi-bdrs($values, $rem) { ... }

Description

Direction agnostic border radius

Parameters

parameterName parameterDescription parameterType parameterDefault value

parameterName	parameterDescription	parameterType	parameterDefault value
`$values`	Instead of being processed left to right, values are processed `top-start`, `top-end`, `bottom-end`, `bottom-start`. with support for primary and optionally secondary border-radius values for border-radius. When secondary values are set, each set of radii must be a space-separated list inside a comma-separated list. For example, to get: '''css border-radius: 12px 6px / 18px; ''' The `$values` argument should be passed as: '''scss $values: (12px 6px, 18px) '''	`List`	—none
`$rem`	Determines if pixel values will be converted into rems.	`Boolean`	—none

$values

Instead of being processed left to right, values are processed top-start, top-end, bottom-end, bottom-start. with support for primary and optionally secondary border-radius values for border-radius.

When secondary values are set, each set of radii must be a space-separated list inside a comma-separated list.

For example, to get: '''css border-radius: 12px 6px / 18px; '''

The $values argument should be passed as: '''scss $values: (12px 6px, 18px) '''

List

—

$rem

Determines if pixel values will be converted into rems.

Boolean

—

Throws

jigsass-bidi: border-radius can have a maximum of 4 primary or
jigsass-bidi: border-radius can have a maximum of 2 sets of
jigsass-bidi: border-radius accepts a maximum of 4 primary or

Requires

[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi

[private] _jigsass-bidi

@mixin _jigsass-bidi() { ... }

Description

A utility mixin to call the correct transformer mixins based on the property or values that were passed.

Parameters

None.

Used by

[mixin] jigsass-bidi

[private] _jigsass-bidi-simple

@mixin _jigsass-bidi-simple($property, $values) { ... }

Description

Contextually convert start and end into left or right.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$property`	—none	`String`	—none
`$values`	—none	`Number` or `String` or `List` or `Color`	—none

Requires

[function] _jigsass-get-side
[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi

[private] _jigsass-bidi-sides

@mixin _jigsass-bidi-sides($property, $values, $rem) { ... }

Description

Contextually interpret lists of four values as top-end-bottom-start instead of 'top-right-bottom-left'.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$property`	—none	`String`	—none
`$values`	—none	`List`	—none
`$rem`	Determines if pixel values will be converted into rems.	`Boolean`	—none

Requires

[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi

[private] _jigsass-bidi-shadow

@mixin _jigsass-bidi-shadow($property, $values, $rem) { ... }

Description

Direction agnostic box/text-shadow authoring

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$property`	`text-shadow` or `box-shadow`	`String`	—none
`$values`	A space-separated list of box-shadow values, or a comma-separated list of space-separated lists of box-shadow values	`List`	—none
`$rem`	Determines if pixel values will be converted into rems.	`Boolean`	—none

Requires

[function] _jigsass-bidi-shadow
[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi

[private] _jigsass-bidi-bgi

@mixin _jigsass-bidi-bgi($values) { ... }

Description

Helper to transform linear gradients as if they were written in a direction-agnostic manner (start-to-end and clockwise for ltr, counter-clockwise for rtl).

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$values`	One or more strings to serve as background-image values.	`String` or `List`	—none

Requires

[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi

[private] _jigsass-bidi-bgp

@mixin _jigsass-bidi-bgp($values, $rem) { ... }

Description

Direction agnostic background-position

transforms background-position values in a start-to-end, direction-agnostic manner

Parameters

parameterName parameterDescription parameterType parameterDefault value

parameterName	parameterDescription	parameterType	parameterDefault value
`$values`	Only numbers specified in percentage units can be transformed, as other units require knowledge of the container's width. For multiple positions (in cases of multiple background images), each set of position values must be a space-separated list inside a comma-separated list. For example, to get: '''css background-position: 25% 50%, left ''' The `$values` argument should be passed as: '''scss $values: (25% 50%, left) '''	`String` or `Number` or `List`	—none
`$rem`	Determines if pixel values will be converted into rems.	`Boolean`	—none

$values

Only numbers specified in percentage units can be transformed, as other units require knowledge of the container's width.

For multiple positions (in cases of multiple background images), each set of position values must be a space-separated list inside a comma-separated list.

For example, to get: '''css background-position: 25% 50%, left '''

The $values argument should be passed as: '''scss $values: (25% 50%, left) '''

String or Number or List

—

$rem

Determines if pixel values will be converted into rems.

Boolean

—

Throws

jigsass-bidi: background-position only takes two arguments per

Requires

[function] _jigsass-bidi-bgp

Used by

[mixin] _jigsass-bidi

[private] _jigsass-bidi-transform

@mixin _jigsass-bidi-transform($values, $rem) { ... }

Description

Direction agnostic transforms, with support for multiple transform functions.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$values`	A transform function or a list of transform functions.	`String` or `List`	—none
`$rem`	Determines if pixel values will be converted into rems.	`Boolean`	—none

Requires

[function] _jigsass-bidi-transform
[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi

[private] _jigsass-bidi-transform-origin

@mixin _jigsass-bidi-transform-origin() { ... }

Description

Direction agnostic transform-origin

transform transform-origin as if it were written start-to-end instead of right-to-left. caveat: Length values can only be transformed if they are in percentage, because transforming non-relative values requires knowledge of the container's dimensions.

Parameters

None.

Requires

[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi

[private] _jigsass-bidi-direction

@mixin _jigsass-bidi-direction($direction) { ... }

Description

Direction agnostic direction

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$direction`	`ste` = start-to-end, `ets` = end-to-start. `rtl` and `ltr` will be printed as is, without trasformation, regardless of the JigSass direction context	`String`	—none

Throws

jigsass-bidi: #{$direction} is not a valid direction value.

Requires

[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi

functions

[private] _jigsass-bidi-bgp

@function _jigsass-bidi-bgp() { ... }

Description

Utility function to transform background-position values in a start-to-end, direction-agnostic manner

Parameters

None.

Throws

jigsass-bidi: horizontal position must be passed before vertical

Requires

[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi-bgp

[private] _jigsass-bidi-transform

@function _jigsass-bidi-transform($value) { ... }

Description

A helper to convert direction agnostic transform functions' arguments

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$value`	The value to transform	`Number`	—none

Returns

Number

Used by

[mixin] _jigsass-bidi-transform

[private] _jigsass-get-side

@function _jigsass-get-side($side) { ... }

Description

Translate start or end into either left or right, depending on the current value of $jigsass-direction;

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$side`	The side to translate into `left` or `right`. Can be `start` or `end`.	`String`	—none

Returns

String —

The translated value of $side. left or right

Throws

_jigsass-get-side: $side may only be start or end, but you passed #{$side}

Requires

[variable] jigsass-direction

Used by

[mixin] _jigsass-bidi-simple

[private] _jigsass-bidi-shadow

@function _jigsass-bidi-shadow($values) { ... }

Description

Helper for transforming direction-agnostic text/box-shadow values

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$values`	A space-separated list of box-shadow values, or	`List`	—none

Returns

List —

Transformed box shadow values

Used by

[mixin] _jigsass-bidi-shadow