Skip to content

api.md

Latest commit

 

History

History
352 lines (303 loc) · 19.1 KB

api.md

File metadata and controls

352 lines (303 loc) · 19.1 KB
Raw

Classes

StyleSheet

Functions

createTheme(themes, [options]) ⇒ StyleSheet

The createTheme function generates a theme StyleSheet instance with CSS variables based on the provided themes and options. It supports multiple color schemes, including light, dark, light dark, and normal.

The themes object defines the styles for these color schemes. Each key in the object corresponds to a color scheme (light, dark, normal), and its value is an object containing key-value pairs that will be converted into CSS variables. Nested keys are concatenated with - to form the variable name. For example, { light : { colors : { primary : 'blue' } } } generates --fun-colors-primary : blue.

css(styles, [options]) ⇒ StyleSheet

Creates and attaches a new StyleSheet instance to the DOM.

StyleSheet

Kind: global class
Properties

Name Type Description
classes Object Map of class name selectors to their generated unique class name.
styles Object The original styles object provided to the instance.
uid string Unique identifier for the StyleSheet instance, generated using this.generateUid.
prefix string Prefix for generating unique identifiers and data attributes. Taken from the options, from the subclass, or from the static prefix of the instance's class.
[attributes] Object | function Optional attributes to be added to the <style> element. May be undefined, an object, or a function returning one, resolved by getDecoratedAttributes every time the attributes are read.
renderers Array | function Renderer functions or method names used to process the styles object, or a function returning them. Resolved by render on every call.
el HTMLElement Reference to the <style> element in the DOM. Created when the instance is attached to the DOM.

new StyleSheet(styles, [options])

The StyleSheet class is responsible for creating and managing a CSS stylesheet. It takes a styles object and an optional options object as input, processes the styles, and generates a CSS stylesheet that can be attached to the DOM, destroyed, or rendered as a string for server-side rendering.

Param Type Default Description
styles Object The styles object. This is an object where keys represent CSS selectors and values are style objects. An at-rule key may also hold a statement prelude string, rendered as @rule prelude;; an array value emits one statement per element, so a name can repeat (e.g. several @import rules) and properties can carry fallback values. The styles object is processed through the renderers to generate the final CSS string. It is stored in the instance as this.styles.
[options] Object {} Configuration options. The following options are assigned to the instance (this): prefix, generateUid, generateClassName, shouldAttachToDOM, attributes, renderers.
[options.prefix] string Prefix for generating unique identifiers and data attributes. Defaults to the static prefix of the instance's class.
[options.generateUid] function Custom function to generate the unique identifier.
[options.generateClassName] function Custom function to generate unique class names.
[options.attributes] Object | function Attributes to be added to the <style> element. May be a function returning the attributes object, resolved every time the attributes are read.
[options.renderers] Array | function ['parseStyles', 'renderStyles'] Array of renderer functions or method names, or a function returning such an array. Resolved by render on every call and applied in order, each renderer receiving the previous one's output. Renderers are called with the instance as this.
[options.shouldAttachToDOM] function Custom function to determine whether the StyleSheet should be added to the DOM.

Example

// Create a new StyleSheet instance with a styles object.
const instance = new StyleSheet({
    root: {
        color: 'black'
    }
});

// Attach the StyleSheet instance to the DOM.
instance.attach();

// Retrieve the generated classes object from the instance.
const { classes } = instance;

// Use the generated class name in your component.
function Header() {
    return <h1 className={classes.root}>Hello World</h1>;
}

styleSheet.preinitialize(styles, [options]) ⇒ void

Hook run at the very start of the constructor, before styles and options are applied and before prefix, uid and classes are computed. Does nothing by default. Override it in a subclass to define instance properties, which is the only place options can be read before the class names are generated. Values set here are still overridden by the matching options.

Kind: instance method of StyleSheet

Param Type Description
styles Object The styles object passed to the constructor.
[options] Object The options object passed to the constructor (may be undefined).

styleSheet.generateUid() ⇒ string

Generate a stable unique identifier. May be overridden by options.generateUid.

Kind: instance method of StyleSheet
Returns: string - The unique identifier.

styleSheet.generateClassName(className, index) ⇒ string

Generate a unique class name. Transform local selectors that are classes to unique class names to be used as class names in the styles object. May be overridden by options.generateClassName or by extending the class.

Kind: instance method of StyleSheet
Returns: string - The unique class name.

Param Type Description
className string The class name.
index number The index of the class name.

styleSheet.render() ⇒ string

Apply the renderers to the styles object. this.renderers is resolved on every call, so the function form is evaluated and method-name strings are looked up on the instance at render time. Renderers are applied in order, starting from this.styles, with each renderer receiving the previous one's output and called with the instance as this. It will return a string ready to be added to the style element.

Kind: instance method of StyleSheet
Returns: string - The styles object as a string.

styleSheet.toString() ⇒ string

Render the StyleSheet as a style element string. Used for server-side rendering. The result is markup, so it is escaped to stay a single well formed <style> element: attribute values are HTML escaped, attribute names that are not legal are dropped, and a </style sequence in the CSS is escaped as \3c /style. The DOM API used by attach applies the equivalent rules on its own.

Kind: instance method of StyleSheet
Returns: string - The instance as a string.

styleSheet.shouldAttachToDOM() ⇒ boolean

Check if the StyleSheet should be added to the DOM. By default, it returns true if running in a browser environment and no style element with the same data-fun-uid attribute exists in the DOM. This prevents duplicate style elements and ensures proper behavior for server-side rendering. May be overridden by options.shouldAttachToDOM.

Kind: instance method of StyleSheet
Returns: boolean - True if the StyleSheet should be added to the DOM, false otherwise.

styleSheet.attach() ⇒ StyleSheet

Add the instance to the registry of its class and if we are in the browser, attach it to the DOM.

Kind: instance method of StyleSheet
Returns: StyleSheet - The instance.

styleSheet.destroy() ⇒ StyleSheet

Destroy the instance and remove it from the registry of its class and from the DOM, if it's present.

Kind: instance method of StyleSheet
Returns: StyleSheet - The instance.

StyleSheet.prefix

Kind: static property of StyleSheet
Default: fun
Properties

Name Type Description
prefix string The class prefix. Used to generate unique class names and data attributes. An instance falls back to the static of its own class, so a subclass may declare its own; options.prefix overrides it per instance.

StyleSheet.indent

Kind: static property of StyleSheet
Default: ' '
Properties

Name Type Description
indent string The indent string. Used to format text when debug is enabled.

StyleSheet.registry

Kind: static property of StyleSheet
Properties

Name Type Description
registry Array The registry array. attach adds an instance to the registry of its own class, and the static toString, toCSS and destroy read the registry of the class they are called on. A subclass shares this array unless it declares its own.

StyleSheet.debug

Kind: static property of StyleSheet
Default: DEV
Properties

Name Type Description
debug boolean The debug flag. If true, the styles will be formatted with indentation and new lines.

StyleSheet.toString() ⇒ string

Render all instances in the registry as a string, including the style tags. Reads the registry of the class it is called on, so it must not be detached from it. Can be used to insert style tags in an HTML template for server-side rendering.

Kind: static method of StyleSheet
Returns: string - All instances in the registry as a string.

StyleSheet.toCSS() ⇒ string

Render all instances in the registry as CSS string. Reads the registry of the class it is called on, so it must not be detached from it. Can be used to generate an external CSS file.

Kind: static method of StyleSheet
Returns: string - All instances in the registry rendered as CSS string.

StyleSheet.destroy()

Destroy all instances in the registry and remove them from it and from the DOM. Reads the registry of the class it is called on, so it must not be detached from it.

Kind: static method of StyleSheet

createTheme(themes, [options]) ⇒ StyleSheet

The createTheme function generates a theme StyleSheet instance with CSS variables based on the provided themes and options. It supports multiple color schemes, including light, dark, light dark, and normal.

The themes object defines the styles for these color schemes. Each key in the object corresponds to a color scheme (light, dark, normal), and its value is an object containing key-value pairs that will be converted into CSS variables. Nested keys are concatenated with - to form the variable name. For example, { light : { colors : { primary : 'blue' } } } generates --fun-colors-primary : blue.

Kind: global function
Returns: StyleSheet - The theme StyleSheet instance. Use classes.root to get the theme class name. Apply this class to the element you want to theme. The CSS variables will be available for all its descendants.

Param Type Description
themes Object An object defining styles for color schemes (light, dark, normal). Each key corresponds to a color scheme, and its value is an object of key-value pairs converted to CSS variables. Nested keys are concatenated with - to form variable names.
[options] Object An optional object to customize the theme generation. It includes options for selecting color schemes, customizing CSS variable prefixes, and controlling StyleSheet creation.
[options.colorScheme] String Specifies the color scheme(s) to use. Possible values are: light (uses the light theme only), dark (uses the dark theme only), light dark (default, supports both light and dark themes, adapting to system preferences; can override system preference with data-color-scheme set to light or dark), and normal (uses the normal theme only).
[options.cssVarsPrefix] String | null Prefix for the generated CSS variables. Defaults to StyleSheet.prefix. Pass null or '' to generate variables without a prefix (e.g. --color instead of --fun-color).
[options.createStyleSheet] function A function used to create a new StyleSheet instance. By default, it uses the css function.
[options.styleSheetOptions] Object Options to pass when creating the StyleSheet instance.

Example

// Create a theme with light and dark color schemes and apply it to the entire page.
const theme = createTheme({
    light : {
        colorPrimary : 'black',
        backgroundLevel1 : 'white'
    },
    dark : {
        colorPrimary : 'white',
        backgroundLevel1 : 'black'
    }
});

// Add the `root` class (the theme class) to the body element.
// This will apply the theme to the entire page.
document.body.classList.add(theme.classes.root);

// Add some styles using the theme CSS variables.
const { classes } = css({
    button : {
        color : 'var(--fun-colorPrimary)', // Use the CSS variable generated from the theme.
        backgroundColor : 'var(--fun-backgroundLevel1)'
    }
});

// Add the `button` class to a button component.
// The button will use the CSS variables defined in the theme for its styles.
// Once the theme is applied, the button will automatically update its styles.
// If the system color scheme changes (e.g., from light to dark), the button will 
// dynamically update to reflect the new theme without requiring additional code.
const Button = ({ label }) => <button className={classes.button}>{label}</button>;

css(styles, [options]) ⇒ StyleSheet

Creates and attaches a new StyleSheet instance to the DOM.

Kind: global function
Returns: StyleSheet - The created and attached StyleSheet instance. Its classes property maps class name selectors to their generated unique class name.

Param Type Description
styles Object An object containing CSS rules. Keys represent selectors, and values represent style objects. An at-rule key may also hold a statement prelude string, rendered as @rule prelude;; an array value emits one statement per element, so a name can repeat (e.g. several @import rules) and properties can carry fallback values.
[options] Object Optional configuration for the StyleSheet instance. Includes options like prefix, renderers, and more.

Example

// Create styles for a link component.
const { classes } = css({
    link : {
        color : 'blue',
        '&:hover' : {
            textDecoration : 'underline'
        }
    }
});

// Use the generated `link` class in a component.
const Link = ({ label, href }) => <a className={classes.link} href={href}>{label}</a>;

Example

// Declare the layer order and define the classes inside layer blocks.
const { classes } = css({
    '@layer' : 'base, theme',
    '@layer base' : {
        button : {
            color : 'black'
        }
    },
    '@layer theme' : {
        button : {
            color : 'blue'
        }
    }
});

// Both blocks share the same generated `button` class.
const Button = ({ label }) => <button className={classes.button}>{label}</button>;