fela-plugin-bidi

Fela plugin to enable direction-independent style authoring

Usage no npm install needed!

<script type="module">
  import felaPluginBidi from 'https://cdn.skypack.dev/fela-plugin-bidi';
</script>

README

fela-plugin-bidi

npm version npm downloads Bundlephobia

Uses bidi-css-js to enable direction-independent style authoring based on the CSSWG's CSS Logical Properties and Values proposal.

It is important to note that, when used as a Fela renderer plugin, this package is not a true polyfill for the proposal, as all start and end properties (and so on) are converted to left or right values (etc.), and will not automatically flip when the writing direction (dir) changes in the document.

When used in conjunction with fela-plugin-fallback-value, fela-plugin-bidi must be passed to the plugins array after fela-plugin-fallback-value, as it cannot handle the array used to pass fallbacks on its own.

Installation

yarn add fela-plugin-bidi

You may alternatively use npm i --save fela-plugin-bidi.

Usage

Make sure to read the documentation on how to use plugins.

For details on what the plugin can and cannot do, please see the documentation in the underlying library. Please make sure to look at the note about four-directional shorthand properties, as there was a breaking change in version 2.0.0.

import { createRenderer } from 'fela'
import bidi from 'fela-plugin-bidi'

const renderer = createRenderer({
  plugins: [bidi('rtl')],
})

With fela-plugin-fallback-value:

import { createRenderer } from 'fela'
import fallbackValue from 'fela-plugin-fallback-value'
import bidi from 'fela-plugin-bidi'

const renderer = createRenderer({
  plugins: [fallbackValue(), bidi('rtl')], // Order matters.
})

Configuration

Parameters
 Parameter Value Default Description
flowDirection ("rtl" | "ltr")  ltr The default flow direction

Example

Input

{
  // BackgroundImage also supports transforming linear-gradient
  backgroundImage: 'logical url(/foo/bar/ste.png)',
  cursor: 'start-resize',
  float: 'end',
  margin: 'logical 1px 2px 3px 4px',
  paddingStart: 20,
}

Output

// When `flowDirection` is set to `rtl`
{
  backgroundImage: 'url(/foo/bar/rtl.png)',
  cursor: 'e-resize',
  float: 'left',
  margin: '1px 4px 3px 2px',
  paddingRight: 20,
}

// When `flowDirection` is set to `ltr`
{
  backgroundImage: 'url(/foo/bar/ltr.png)',
  cursor: 'w-resize',
  float: 'right',
  margin: '1px 2px 3px 4px',
  paddingLeft: 20,
}

Theme-Based Mode

Apart from enforcing either rtl or ltr all the time, one can also leverage a special props.theme.direction property to dynamically set the transformation mode. This is especially useful together with React to switch transformation for subtrees.

const rule = () => ({
  backgroundImage: 'logical url(/foo/bar/ste.png)',
  cursor: 'start-resize',
  float: 'end',
  margin: 'logical 1px 2px 3px 4px',
  paddingStart: 20,
})

// default
renderer.renderRule(rule, { theme: { direction: 'ltr' } })
renderer.renderRule(rule, { theme: { direction: 'rtl' } })

License

Fela is licensed under the MIT License.
Documentation is licensed under Creative Commons License.
Created with ♥ by @robinweser and all the great contributors.