satchelspencer/ctyled

contextual styles for react

ctyled

ctyled is a HOC for styling components. its fundamental tool for styling is the style prop. a style prop takes in some arbitrary value and maps it to some css rules for a given component. for example, a style prop named 'size' may be used to determine the font-size, padding, and width of a button component. style props are contextual. 'size' for a component is not defined as an absolute value, but rather as a ratio comparing that component's size relative to its parent. this is true not just for size, but color, padding, spacing, or any style prop you want to define.

default style props

by default, components with ctyled have a set of core style props pre-defined, some provide extra functionality:

• color: base color for component. see relative colors
• borderColor: color of borders, variation of base color by default
• bgColor: color of background, base color bg by default
• size: base size for component
• bg: bool if bg should exist
• border: bool if border should exist
• padd: bool if padding should exist. if numeric treated as a multiple of the base size
• gutter: bool if gutter spacing between child elements should exist. if numeric treated as multiple of the base size
• lined: bool if internal borders should be put between each child component
• disabled: bool if component should be non interactive and greyed out

and some are just shorthands for existing css rules:

• column: bool changes flex-direction
• align: shorthand for align-items
• justify: shorthand for justify-content
• alignSelf: shorthand for align-self
• reverse: changes flex direction to *-reverse
• flex: sets the flex property
• rounded: shorthand for border-radius. defined as multiple of base size
• flatLeft, flatRight... removes border radius on verts adjacent to the flat side
• noselect makes the component not selectable

constructing ctyled component

base dom elements with ctyled can be created with the shorthand ctyled.element_name, or an existing component can be passed to ctyled(Component):

import ctyled from 'ctyled'
const CtyledLink = ctyled.link
const CtyledThing = ctyled(MyOwnComponent)

defining style props for a component

default style prop values for a component can be defined with component.styles({...props}). Usually each prop value is a function that takes in the value from the components parent, and returns the new value.

import ctyled from 'ctyled'
const CtyledLink = ctyled.link.styles({
  size: parentSize => parentSize * 0.9, //small link
  color: parentColor => parentColor.invert(), //flip fg and bg
  padd: true, //add padding (relative to size as per prop definition)
})

style prop values can also be extends on the component at render by passing the styles prop. In this case the CtyledLink will have all of its defaultProps and a border:

<CtyledLink styles={{ border: true }} />

adding CSS

ctyled components can call component.extendSheet with a template literal to add arbitrary css. functions in the template will be passed the style props of the component, and the properties on the component itself (styleProps, reactProps) => css

import ctyled from 'ctyled'
const CtyledButton = ctyled(MyButton).styles({
  size: parentSize => parentSize * 2, // massive button
}).extendSheet`
    opacity:0.5;
    margin-left:${styleProps => style.props.size * 3}px;
  `

if only features of inline styles component.extend can be used instead and no stylesheet will be generated.

defining default props

often it is useful to make the styles of a component be dependent on other properties. you can use component.attrs({defaultProps}) to set the default values for those props and to tell the typesystem what to expect.

import ctyled from 'ctyled'
const CtyledButton = ctyled.div.attrs({ big: false }).styles({
  size: parentSize => parentSize * (big ? 2 : 1), // massive button if 'big'
})

const big = <CtyledButton big />

defining your own style props

its maybe changing look at /classes/core for an example

relative color system

to make colors in ctyled useful we need a way of defining a color scheme, then a way of defining specific colors relative to each other within that scheme. A color scheme is defined as a gradient with a series of stops from the foreground to the background of that color.

import Color from 'ctyled/color'

const grayScale = new Color(['white', 'black']),
  red = new Color(['red', 'white'])

once the color is created you can retrieve fg and bg colors using color.fg and color.bg. you can also change where on the gradient the fg and bg are sampled from using the functions:

• color.nudge(amount: number) get a new color, different from the current one. the larger the |amount| the greater the difference from the starting color
• color.contrast(amount: number) change the contrast of the color, moving the fg and bg further or closer to eachother with a + or - amount
• color.invert() swap the fg and bg
• color.as(otherColor: gradient) get a new color with the same brightness, contrast, invertedness, but from a different color palette

ctyled's Issues

Unable to use Ctyled with react-resizable-panels

We're trying to utilize react-resizable-panels in our application with the ctyled library. Errors are generated because ctyled uses the short hand value for flex.

We've been able to modify the ctyled library locally such that it works with the resizable panels library. I'm happy to provide the code if you are interested in updating the ctyled library.