lightningcss-plugin-cobweb

LightningCSS plugin providing Cobweb specific CSS extensions. These extensions are required when using the cobweb package; however, the extensions are available for general use. The extensions are documented in the package documentation of index.ts, which is also published with the package declarations (target/tsc/index.d.ts).

| Extension | Description | | ----------------------- | --------------------------------------------------------------------- | | cw-var() | Resolve a role token to its value, or to its custom property. | | cw-scale-opacity() | Scale the alpha channel of a color. | | cw-spring-motion-of() | Generate the linear() easing function or duration of a spring. | | -cw-border-radius | Assign the corner radii of a corner group role. | | -cw-typescale | Assign the font and letter spacing of a typescale group role. | | @cw-attribute-roles | Register the role properties of an attribute. | | @cw-apply-theme | Assign the values of a theme, or the default values with default. | | @cw-apply-defaults | Assign the default values of component roles to the matched elements. |

A Cobweb module has one style sheet, so importing one of its components brings the rules of them all, and the roles of those with a design attribute of their own. Pass the components a bundle never shows as unusedComponents to newCobwebVisitor(design, opts), and check the built bundle with findUnusedComponent() and findUnusedRole(), against its scripts and any HTML it emits.

The style sheets published by cobweb are not compiled: they use these extensions. An application using cobweb must compile them with LightningCSS and this plugin, and must load the Cobweb design with cobweb-design. The plugin warns about var() fallbacks which can never apply.

Example (Vite)

import { Design } from "@pg-labs-incubator/cobweb-design";
import { COBWEB_AT_RULES, newCobwebVisitor } from "@pg-labs-incubator/lightningcss-plugin-cobweb";
import { composeVisitors } from "lightningcss";
import { defineConfig } from "vite";

export default defineConfig({
	css: {
		transformer: "lightningcss",
		lightningcss: {
			customAtRules: COBWEB_AT_RULES,
			visitor: composeVisitors([
				// Resolve the package from the directory of this configuration file:
				newCobwebVisitor(Design.load(
					"@pg-labs-incubator/cobweb",
					undefined,
					undefined,
					import.meta.dirname
				)),
				// ... additional visitors ...
			])
		}
	}
});

License

This package is licensed under the GPL-2.0 license.