Experimental getSchema

[joe-bell]

Warning

Extremely WIP

Description

Surfaces a getSchema function to extract a cva component's variant schema for documentation purposes

Inspired by @bengry's wonderful proposal

Additional context

---

What is the purpose of this pull request?

• Bug fix
• New Feature
• Documentation update
• Other

Before submitting the PR, please make sure you do the following

• Read the Contributing Guidelines.
• Follow the Style Guide.
• Check that there isn't already a PR that solves the problem the same way to avoid creating a duplicate.
• Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123).

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	Jan 25, 2025 6:19pm
docs-beta	✅ Ready (Inspect)	Visit Preview	Jan 25, 2025 6:19pm

[bengry]

@joe-bell Just a heads up, if it helps - my fork already has some tests for .variants being exposed (as well as the other stuff it adds). They're not exhaustive, but feel free to take inspiration from them.

Overall the code in both the actual code as well as the tests are very similar to the current state of [email protected], so you can probably even compare the two branches to save you some time.

[joe-bell]

Thanks @bengry!

I think my preference here would be for us to instead do something kinda like:

const getSchema: GetSchema = (comp) => {
  // CVA function would spit the `variants` out from the specified `config`– untouched – into a hidden `_cva` metadata object. Which we'd use to create the schema
  return comp._cva?.variants
    ? Object.fromEntries(
        Object.entries(comp._cva?.variants).map(([key, value]) => [
          key,
          Object.keys(value).map((propertyKey) =>
            normalizeVariantKey(propertyKey),
          ),
        ]),
      )
    : {};
};

// Demo
const button = cva({
    variants: {
      size: {
        sm: "p-2",
      },
    },
  });

const schema = getSchema(button); // { size: readonly "sm"[]; }

I'd largely consider getting the schema to be somewhat of a power-user feature and I wouldn't want to inflate the cva much further if possible – especially considering there's some more features I'm considering

Biggest challenge is going to be typing these damn types – it's had me pretty stumped today

[joe-bell]

Making good progress, but gotta whole lotta types nonsense to figure out here

[joe-bell]

Temporary bump. Might consider moving getSchema into a separate cva/utils entry point to keep bundlesize lower

[bengry]

@joe-bell I didn't look at your implementation too much, but here's a very quick POC I made for what you suggested. It split the ~2kB bundle size into two parts, and using ESM further reduces the bundle size a bit:

PASS  ./dist/index.mjs: 962B < maxSize 1KB (gzip) 
PASS  ./dist/utils/index.mjs: 410B < maxSize 500B (gzip) 

I also replaced swc with tsup since it basically does the same thing with less config IMO, and I couldn't get swc to bundle multiple entrypoints easily. unbuild might also be worth a look, though I haven't looked at it too much.

Basic types work as expected, but I didn't implement the private variants, or the same for compose. There's also some copy-paste stuff, and circular type dependencies going on which need to be cleaned up. Should be easy enough to do.

[joe-bell]

Oh nice, thanks for the heads up @bengry, I'll take a look!

Feel pretty happy with the progress on my solution so far –  mostly type issues