Skip to content

robinweser/brandeur

Repository files navigation

Brandeur

Brandeur is a convenience layer and tool belt on top of css-hooks for React.

npm version npm downloads Bundlephobia

Benefits

  • Similar API
  • Theming
  • RTL Conversion
  • Vendor Prefixing
  • Fallback Value Support
  • Keyframes Support
  • Extendable Plugin System
  • Fela Plugin Compatibility
  • TypeScript Support

Installation

# npm
npm i --save brandeur
# yarn
yarn add brandeur
# pnpm
pnpm add brandeur

The Gist

import { createHooks } from 'brandeur'
import prefixer, { fallbacks } from 'brandeur-plugin-prefixer'

const theme = {
  colors: { primary: 'red' },
}

const [staticCSS, css] = createHooks({
  hooks: {
    // either custom hooks or @css-hooks/recommended
  },
  plugins: [prefixer()] as const,
  fallbacks: [
    ...fallbacks,
    { property: 'position', values: ['-webkit-sticky', 'sticky'] },
  ],
  keyframes: {
    fadeIn: {
      from: { opacity: 0 },
      to: { opacity: 1 },
    },
  },
  theme,
})

// fades in, red color, vendor prefixed and browser-compatible position: sticky
const style = css(({ theme, keyframes }) => ({
  animationName: keyframes.fadeIn,
  color: theme.colors.primary,
  position: 'sticky',
  appearance: 'none',
}))

Why

tbd.

API

Currently Brandeur only exposes two functions:

createHooks

The main API that wraps createHooks from css-hooks.
It returns the same structural array including both the static CSS and the css function. The difference is that the static CSS includes more than just the hooks and the css function also accepts functions.

Arguments

It accepts the following arguments as an object.

Argument Type Description
plugins Array<Plugin> List of plugins that are used to process each style before transforming into a flat hooks style. See Plugins for a list of all available plugins.
fallbacks Array<Fallback> List of fallbacks that are added and automatically replace within style objects.
keyframes Object A map of animationName-keyframe pairs.
theme Object A theme object that can be accessed from within style functions.
Plugin
type Plugin = style => style

Plugins are simple functions that take a style object and return a new one, similar to Fela plugins.

Note: See Plugins for a list of all available plugins.

Fallback
type Fallback = {
  property: string | Array<string>
  values: Array<string>
  match?: string
}

Tip: The fallbackValue API provides a convenient way to create those fallback objects.

Returns

It returns an array where the first item is a static CSS string and the second item is the css function to create styles. The css function accepts both style object as well as functions where the first argument is an object that only has a theme property.

Example

See The Gist.

fallbackValue

A tiny helper function to create fallbacks in a more convenient way.

Arguments

It accepts the following arguments as an object.

Argument Type Description
property Array<string> | string A property or list of properties for which the fallback value applies.
values Array<string> A list of fallback values where the last one is the default.
match string? An optional matcher string that's used to replace values in style objects. Defaults to the last values value.

Returns

(Fallback) An object with respective fallback properties.

Example

import { fallbackValue } from 'brandeur'

const positionSticky = fallbackValue('position', ['-webkit-sticky', 'sticky'])

Plugins

Brandeur becomes really powerful when utilising the rich plugin echosystem. That way, we can extend the styling engine to support our personal needs.

Brandeur Plugins

Name Description
brandeur-plugin-debug Uses styles-debugger to visually debug styles.
brandeur-plugin-enforce-longhand Specific implementation of sort-property. Enforces longhand over shorthand properties for more deterministic results.
brandeur-plugin-prefixer Adds vendor prefixes to style objects.
brandeur-plugin-sort-property Sorts properties according to a priorty map. Helpful when trying to enforce certain properties over others.
brandeur-plugin-responsive-value Resolves responsive array values.

Fela Plugins

Thanks to similar architecture and API design, brandeur supports almost all Fela plugins out of the box.

Tip: In order to get proper types, make sure that you import brandeur in the same file where Fela plugins are imported as types for all Fela plugins are shipped with the core package.

Name Description Compatibility
fela-plugin-bidi Enables direction-independent styles by converting them to either rtl or ltr on the fly. Does not support context-specific direction via theme.
fela-plugin-custom-property Resolves custom properties. Full
fela-plugin-expand-shorthand Expands shorthand properties into their longhand forms. Full
fela-plugin-extend Adds a convenient syntax for (conditionally) extending styles. Full
fela-plugin-hover-media Wraps :hover styles in @media (hover: hover) queries. Full
fela-plugin-kebab-case Converts properties written in kebab-case to camelCase. Full
fela-plugin-logger Logs processed style objects. Full
fela-plugin-multiple-selectors Resolves multiple comma-separated selectors to individual object keys. Full
fela-plugin-responsive-value Resolves array values to pre-defined media queries. Useful for component APIs. Does not support the props argument to receive the theme. Use a static theme instead.
fela-plugin-rtl Converts styles to their right-to-left counterpart Does not support context-specific direction via theme.
fela-plugin-unit Automatically adds units to values if needed. Full
fela-plugin-validator Validates, logs & optionally deletes invalid properties for keyframes and rules. Full

Incompatible Plugins

Plugin Alternative
fela-plugin-prefixer Use brandeur-plugin-prefixer instead.
fela-plugin-named-keys
fela-plugin-friendly-pseudo-class
fela-plugin-pseudo-prefixer
fela-plugin-fullscreen-prefixer
fela-plugin-placeholder-prefixer
Use hooks directly to set those.
fela-plugin-embedded No replacement yet due to missing font and keyframe primitives.
fela-plugin-theme-value No replacement yet due to incompatible plugin APIs.

TypeScript

Brandeur comes with native TypeScript support, but requires some manual setup to get the correct types for all plugins.

Style Object

By default, Brandeur automatically infers the type just like css-hooks does. It supports all React.CSSProperties. For convenience, we also export a Style type from brandeur.

In order to extend the type with plugins, we need to set them up correctly.

import { createHooks } from 'brandeur'

import extend from 'fela-plugin-extend'
import responsiveValue, {
  ResponsiveStyle,
} from 'brandeur-plugin-responsive-value'

const [staticCSS, css] = createHooks({
  // ... config
  plugins: [
    // allow responsvie array values in extended styles
    extend<ResponsiveStyle>(),
    responsiveValue([
      '@media (min-width: 480px)',
      '@media (min-width: 1024px)',
    ]),
    prefixer(),
    // use "as const" to get fixed types
  ] as const,
})

Fela Plugins

Make sure to import brandeur in your configuration file to load all the plugin types for Fela plugins. Otherwise you'll get the native ones from Fela which have conflicting types.

// load types
import 'brandeur'

import extend from 'fela-plugin-extend'
import hoverMedia from 'fela-plugin-hover-media'

Keyframes

Brandeur provides a simple way to create and consume global keyframes. Check the gist for an example.

Sometimes however we want to have dynamic keyframes and/or not render all keyframes upfront. In such cases, we recommend using a separate package to deal with that.
I created react-create-keyframe for exactly those use cases. Feel free to check it out!

Roadmap

  • Theming Primitives
  • Framework-Agnostic API

License

Brandeur is licensed under the MIT License.
Documentation is licensed under Creative Commons License.
Created with ♥ by @robinweser.