feature: Pre-configured framework-agnostic `makeStyles` & Co.

[aweebit]

Despite the fact only React usage is documented, @griffel/react is actually just a thin wrapper around the core functionality that is framework-agnostic (see also #370).

However, the ergonomics of using @griffel/core directly are questionable because while the React wrapper's makeStyles function returns a hook that ensures that the provided renderer and writing direction are used, @griffel/core's makeStyles returns a function that expects those context parameters to be provided as arguments so that it can spit out the actual class string:

const renderer = createDOMRenderer();
const dir = 'ltr';

const getStylesA = makeStyles({ root: { color: 'red' }});
const classesA = getStylesA({ renderer, dir });

const getStylesB = makeStyles({ root: { color: 'green' }});
const classesB = getStylesB({ renderer, dir });

To simplify vanilla usage, I suggest providing a Griffel class whose instances would include pre-configured makeStyles, makeResetStyles and makeStaticStyles functions that return the class strings directly. The code above could then be simplified to this:

const { makeStyles } = new Griffel();

const classesA = makeStyles({ root: { color: 'red' }});
const classesB = makeStyles({ root: { color: 'green' }});

You would of course be able to also provide your custom renderer and writing direction with new Griffel({ renderer, dir }), but if you didn't, a renderer would be created automatically with a createDOMRenderer() call and the left-to-right direction would be assumed. This would be in accordance with the default values of the React wrapper's RendererContext and TextDirectionContext.

Implementation is pretty straight-forward:

type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };

type TextDirection = "ltr" | "rtl";

interface GriffelOptions {
  insertionFactory?: GriffelInsertionFactory;
  renderer?: GriffelRenderer;
  dir?: TextDirection;
}

class Griffel
  implements WithRequired<GriffelOptions, "renderer" | "dir">
{
  insertionFactory?: GriffelInsertionFactory = undefined;
  renderer: GriffelRenderer = createDOMRenderer();
  dir: TextDirection = "ltr";

  constructor(options?: GriffelOptions) {
    Object.assign(this, options);
  }

  makeStyles = <Slots extends string | number>(
    stylesBySlots: StylesBySlots<Slots>
  ) => {
    const { insertionFactory, renderer, dir } = this;
    return makeStyles(stylesBySlots, insertionFactory)({ renderer, dir });
  };

  makeResetStyles = (styles: GriffelResetStyle) => {
    const { insertionFactory, renderer, dir } = this;
    return makeResetStyles(styles, insertionFactory)({ renderer, dir });
  };

  makeStaticStyles = (styles: GriffelStaticStyles | GriffelStaticStyles[]) => {
    const { insertionFactory, renderer } = this;
    return makeStaticStyles(styles, insertionFactory)({ renderer });
  };
}

This is the code I would have to write if I were to employ Griffel in non-React projects today. It would be great if @griffel/core itself included such a class, as it would make it truly ready for framework-agnostic usage.

I would like to hear feedback from maintainers and could then submit a pull request if this addition to the library is deemed reasonable.

[aweebit]

Actually, this class would even make @griffel/react largely unnecessary. Unless the user made use of RendererContext or TextDirectionContext, they wouldn't really need a useClasses hook, and so could use a Griffel instance instead:

// griffel.ts
import { Griffel } from "@griffel/core";

const { makeStyles, makeResetStyles, makeStaticStyles } = new Griffel();

export { makeStyles, makeResetStyles, makeStaticStyles };

// App.tsx
import { makeStyles } from "./griffel";

const classes = makeStyles({ root: { color: "red" } });

export default function App() {
  return <div className={classes.root}>App</div>;
}

[aweebit]

AOT compilation support

For WyW-in-JS to be able to associate makeStyles and makeResetStyles with respective tag processors, the functions have to be imported from some module.

That is why having a file exporting those methods of a Griffel instance (like griffel.ts in my previous comment) becomes a requirement when AOT compilation is desired.

Moreover, the file is expected to export __styles and __resetStyles functions used in the transformed code, so it makes sense to include wrappers around the original definitions of those functions in the Griffel class:

__styles<Slots extends string>(
  classesMapBySlot: CSSClassesMapBySlot<Slots>,
  cssRules: CSSRulesByBucket
) {
  const { insertionFactory, renderer, dir } = this;
  return __styles(
    classesMapBySlot,
    cssRules,
    insertionFactory
  )({ renderer, dir });
}

__resetStyles(
  ltrClassName: string,
  rtlClassName: string | null,
  cssRules: CSSRulesByBucket | string[]
) {
  const { insertionFactory, renderer, dir } = this;
  return __resetStyles(
    ltrClassName,
    rtlClassName,
    cssRules,
    insertionFactory
  )({ renderer, dir });
}

This will be then our module file:

// src/griffel.ts
import { Griffel } from "@griffel/core";

const {
  makeStyles,
  makeResetStyles,
  makeStaticStyles,
  __styles,
  __resetStyles,
} = new Griffel();

export {
  makeStyles,
  makeResetStyles,
  makeStaticStyles,
  __styles,
  __resetStyles,
};

Now we need to instruct WyW-in-JS to process makeStyles and makeResetStyles exported from this file. For that, the tagResolver configuration option can be used. Unfortunately, the function we provide only receives the imported symbol ("tag") and the module name as found in the import statement ("source") as arguments, but not the path to the source file. I've just created an issue for this, but for now, aliases seem to be our best bet:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "$griffel": ["./src/griffel.ts"]
    },
    /* ... */
  }
  /* ... */
}

// vite.config.ts
import griffel from "@griffel/vite-plugin";
import { createRequire } from "node:module";
import { resolve } from "node:path";
import { defineConfig } from "vite";

const require = createRequire(import.meta.url);

export default defineConfig({
  resolve: {
    alias: { $griffel: resolve(import.meta.dirname, "./src/griffel.ts") },
  },

  plugins: [
    griffel({
      tagResolver: (source, tag) => {
        if (source === "$griffel") {
          if (tag === "makeStyles") {
            return require.resolve("@griffel/tag-processor/make-styles");
          }

          if (tag === "makeResetStyles") {
            return require.resolve("@griffel/tag-processor/make-reset-styles");
          }
        }

        return null;
      },
    }),
  ],
});

// src/App.tsx
import { makeStyles } from "$griffel";

/* ... */

Alternatively, we could simply not check source at all and base our tagResolver purely on the tag argument.

---

To prevent the AOT compilation from silently not happening because tagResolver isn't set up correctly, we could let the Griffel constructor additionally accept a compiledOnly option and, if it is set to true, set makeStyles & Co. to functions that throw errors when called. That will happen at runtime if tagResolver is not right because calls to those functions will not be replaced at compile time.

Click to expand code (now a little involved)

type TextDirection = "ltr" | "rtl";

export interface GriffelOptions {
  insertionFactory?: GriffelInsertionFactory;
  renderer?: GriffelRenderer;
  dir?: TextDirection;
  compiledOnly?: boolean;
}

const runtimeErrorFactory = (functionName: string) =>
  [
    `${functionName}(): this function cannot be called at runtime.`,
    "The Griffel instance was configured with compiledOnly: true.",
    "Make sure you have configured ahead-of-time compilation correctly!",
  ].join(" ");

const makeStylesRuntimeError = runtimeErrorFactory("makeStyles");
const makeResetStylesRuntimeError = runtimeErrorFactory("makeResetStyles");
const makeStaticStylesRuntimeError = runtimeErrorFactory(
  "makeStaticStylesRuntimeError"
);

const makeStylesRuntimeErrorFunctions = {
  makeStyles() {
    throw new Error(makeStylesRuntimeError);
  },
  makeResetStyles() {
    throw new Error(makeResetStylesRuntimeError);
  },
  makeStaticStyles() {
    throw new Error(makeStaticStylesRuntimeError);
  },
};

const makeStylesFunctions = {
  makeStyles<Slots extends string | number>(
    this: Griffel,
    stylesBySlots: StylesBySlots<Slots>
  ) {
    const { insertionFactory, renderer, dir } = this;
    return makeStyles(stylesBySlots, insertionFactory)({ renderer, dir });
  },

  makeResetStyles(this: Griffel, styles: GriffelResetStyle) {
    const { insertionFactory, renderer, dir } = this;
    return makeResetStyles(styles, insertionFactory)({ renderer, dir });
  },

  makeStaticStyles(
    this: Griffel,
    styles: GriffelStaticStyles | GriffelStaticStyles[]
  ) {
    const { insertionFactory, renderer } = this;
    return makeStaticStyles(styles, insertionFactory)({ renderer });
  },
};

export class Griffel
  implements WithRequired<GriffelOptions, "renderer" | "dir" | "compiledOnly">
{
  insertionFactory?: GriffelInsertionFactory;
  renderer: GriffelRenderer = createDOMRenderer();
  dir: TextDirection = "ltr";
  compiledOnly = false;

  makeStyles!: <Slots extends string | number>(
    stylesBySlots: StylesBySlots<Slots>
  ) => Record<Slots, string>;
  makeResetStyles!: (styles: GriffelResetStyle) => string;
  makeStaticStyles!: (
    styles: GriffelStaticStyles | GriffelStaticStyles[]
  ) => void;

  constructor(options?: GriffelOptions) {
    Object.assign(this, options);
    Object.assign(
      this,
      this.compiledOnly
        ? makeStylesRuntimeErrorFunctions
        : {
            makeStyles: makeStylesFunctions.makeStyles.bind(this),
            makeResetStyles: makeStylesFunctions.makeResetStyles.bind(this),
            makeStaticStyles: makeStylesFunctions.makeStaticStyles.bind(this),
          }
    );
  }

  __styles = <Slots extends string>(
    classesMapBySlot: CSSClassesMapBySlot<Slots>,
    cssRules: CSSRulesByBucket
  ) => {
    const { insertionFactory, renderer, dir } = this;
    return __styles(
      classesMapBySlot,
      cssRules,
      insertionFactory
    )({ renderer, dir });
  };

  __resetStyles = (
    ltrClassName: string,
    rtlClassName: string | null,
    cssRules: CSSRulesByBucket | string[]
  ) => {
    const { insertionFactory, renderer, dir } = this;
    return __resetStyles(
      ltrClassName,
      rtlClassName,
      cssRules,
      insertionFactory
    )({ renderer, dir });
  };
}