Creating utilities

The simple form

Use properties when one value goes into one or more CSS properties.

import { definePlugin, values } from "@croff/core";

export default definePlugin({
  name: "croff-plugin-tabs",
  utilities: {
    "tab-size": {
      description: "Sets the width of tab characters.",
      args: [{ name: "size", types: [values.integer({ min: 1, max: 16 })] }],
      properties: ["tab-size"],
      examples: ["tab-size(4)", "tab-size[2ch]"],
    },
  },
});

The bracket form is available automatically. Set arbitrary: false to turn it off, or to a function when the value needs wrapping, as in arbitrary: (value) => ({ transform: scale(${value}) }).

The compile form

Use compile when output depends on the arguments.

import { definePlugin, values } from "@croff/core";

export default definePlugin({
  name: "croff-plugin-stack",
  utilities: {
    stack: {
      description: "A flex column with a gap.",
      args: [{ name: "gap", types: values.spacing(), optional: true }],
      compile: ({ args }) => ({
        display: "flex",
        "flex-direction": "column",
        ...(args[0] ? { gap: args[0] } : {}),
      }),
    },
  },
});

compile receives the resolved args, the source text in words, and the resolve context for reading the theme.

What it returns is checked before it reaches the stylesheet. Property names must be valid, and values must be non-empty strings that can't affect anything outside their declaration, so 1px}body{color:red is rejected as unsafe-output. If compile throws, that's a utility-error. Either way, only that expression fails.

Value types

Value types live in values and decide what's valid. Try several in order by listing them in types.

Arguments