add a way to describe what `--style-props` a component expects

Is your feature request related to a problem? Please describe.

When working on a lot of components, I can’t remember every prop a component has defined. Thats why VS Code offers a great auto-completion for “normal” props a component exports. But when using components that contain style props, I currently always have to go into the component to take a look what style props are used inside the style tag.

Describe the solution you’d like I want a way to be able to describe the style props my components intents to handle.

type

A basic approach (similar to the already existing $$Props and $$Events interfaces) could look like:

<!-- Hello.svelte -->
<script lang="ts">
   type $$StyleProps = 'color' | 'font-size'
</script>

<div>Hello</div>

<style>
   div {
      color: var(--color, red);
      font-size: var(--font-size, 1rem)
   }
</style>

When you then use this component, you would get auto-completion for the available style props and you also get errors when you try to set a property that does not exist.

<!-- Parent.svelte -->
<script lang="ts">
   import Hello from './Hello.svelte'
</script>

<Hello --colour="blue" />
             ^
<!-- error: there exists no style-prop named 'colour' for the component 'Hello'-->

When a component doesn’t define $$StyleProps, then it defaults to string so all properties are accepted (the current behaviour)

Defining the props like in the example above would already be a great addition.

interface

An alternative way would be to use an interface:

interface $$StyleProps {
   color: string
   font-size: string
}

This would need a few more keystrokes to type but this could add the functionality to better describe what the passed prop should look like:

interface $$StyleProps {
   color: 'red' | 'green' | 'blue' 
   font-size: `${number}rem`
}

In the example above, we only want a fixed set of values to be passed to the --color prop and the --font-size to be a number ending with ‘rem’. And there are probably a lot more use-cases that can be enabled with the inferface-syntax.

One such use-case could be to define optional and required style props by simply using TypeScript syntax:

interface $$StyleProps {
   color: string
   font-size?: string
}

Here this component would require parent components to pass a --color prop.

keys

I’m not sure if if its needed for the keys of the interface to begin with -- or if we should omit them since we already know that these are style-props and they have to be accessed via the -- prefix.

interface $$StyleProps {
   color: string
   font-size: string
}

vs.

interface $$StyleProps {
   --color: string 
   --font-size: string
}

limitations

Adding this feature would not prevent users to “override” the restrictions a component defines on it’s style props. Maybe the component uses internally a --color´ prop but only wants developers to be able to set the –font-size` prop. Of course anyone could define the style prop like in this example to override it:

<div style="--color: white">
   <Hello />
</div>

This feature would only be an additional way to describe components even better.

Describe alternatives you’ve considered

Leave it like it is. Offer no IDE hints for style props.

[Monkatraz]

I really do feel like making it part of the TypeScript interfaces is… weird? Like, it makes sense for normal exported props because they are JS values and types. But style props are always strings, and they can be any CSS expression. Trying to strongly type them using template strings seems like a bad idea because there are so many edge cases.

[Monkatraz]

To give some examples:

interface $$Props { '--color': 'red' | 'blue' }
// invalid values:
// - rgb(255, 0, 0)
// - rgb(0, 0, 255)
// - var(--my-red)

interface $$Props { '--font-size': `{number}em` }
// invalid values:
// - var(--font-size)
// - calc((2 * var(--base-font-size)) * 1em)