Expose component CSS custom properties

[milkbump]

It'd be helpful to expose custom properties inside a component for easier documentation. Particularly with the addition of the <Component --css-var="var"/> syntax.

It would be even more helpful if custom properties that are defined in the component (e.g --value: 24px) were somehow distinguishable from custom properties that are only used in the component (e.g value : var(--from-global-scope);)

[alexprey]

Hi, @kafwangure
Thanks for idea! However, I'm not actually know how it can looks in real case. Can you please provide the Svelte component with custom properties and expected output? If you can provide different and edge cases for that it will be awesome!

[ekhaled]

@alexprey here is an example in the REPL

In terms of output, I think we can put this in data object with a custom type <String | StyleProp>

[milkbump]

Example library component

<button class="css-api class-i-dont-want-you-to-use">
    <slot/>
</button>

<style>
    .css-api {
        /** @random doc comment */
         --button-width: 100px;
         --unused-value-wont-help-you: auto;
    }
    .class-i-dont-want-you-to-use {
         width: var(--button-width, 100px);
         color: var(--global-color-you-shouldnt-care-about);
    }
</style>

Example usage:

<form>
    <input type="password"/>
    <Button --button-width="120px">Submit</Button>
</form>

<style>
    form :global(.css-api) {
         --button-width: 120px;
    }
</style>

Example docs
Like this:

     {
          css_vars: [
                { name: "--button-width", value: "120px", defined: true, used: true, },
                { name: "--global-color-you-shouldnt-care-about", defined: false, used: true },
                { name: "--unused-value-wont-help-you": value: "auto", defined: true, used: false },
          ],
     },

...but also including the /** comment */ docs.

Depending on someone's use case then, they can document their desired vars. For example, I imagine many will only display docs if var is defined && used.

I admittedly haven't thought too much about uses cases beyond what I have personally needed before.

[alexprey]

Wow, miss it from official documentation! Thanks for raising the issue 😸
Link to official docs

So, based on it, I think that it should be a new item in SvelteComponentDoc and it should present a new feature css_vars.

export interface SvelteCssItem extends ISvelteItem {
    // Not sure that we can extract this description correctly, but if will be nice to have
    description?: string;
    // Nice to have, but can be done later
    defaultValue?: string;
}

From techical side it should be a new parser - /lib/v3/style.js. As an example you can check the template and JS parsers at /lib/v3/template.js and /lib/v3/script.js.

That a complex task, so, can't promise to done it quick, but try to do that.