Discoverability of component parameters - typed parameters

[Marcin Gordziejewski]

Hey,

I discovered your project through a comment on HackerNews - and it got me curious. The idea looks really nice as I often struggle with managing my components in Django projects, so this fits the bill nicely.

I'm posting more as a discussion / idea issue rather than actual problem.

Have you thought about any way on how could it be possible to make discoverability of component parameters better?

Let's use the examples from your website: https://mitchel.me/slippers/docs/getting-started/

{% #card heading="I am the heading" %}

Card accepts in this case children (that will be embedded) and parameter heading. But let's imagine a case where I've component consisting of 10 different parameters (and let's assume this is a must, and it's greatly reusable for my imaginary project). This can be for example parameter color that must be css-compatible color name, or size that must be either small, medium or large

Is there any way to make discoverability of parameters and their values better? Right now you have to go to the source code of the component and find your way through the HTML and discover every and each parameter and judge from the code if its required/obligatory or not and what is it even accepting.

I've always thought that components in django miss some kind of typing like React's propTypes: https://www.npmjs.com/package/prop-types

Do you think slippers could be a project where this kind of typing could be useful?

I've been thinking about hacking with your project to implement such thing but wanted to hear on if you have had any vision about that :)

[Mitchel Cabuloy]

Hi Nicarim,

Thanks for this. I totally get your point and this is something that I have been thinking about. I do believe that the discoverability of component parameters is important and it's something I want slippers to facilitate.

I'm not too sure about going with full-blown type checking like PropTypes because I don't think DTL was built for that. It's like when I try to access a parameter that doesn't exist, it just prints nothing; it doesn't explode.

Barring that though, I am keen for there to be a way to "surface" what parameters a component requires to render, and maybe even validate enums like in your example for size.

My initial ideas:

{% prop color %} {# If DEBUG=True, explodes if color is not defined #}
{% prop variant|default:"primary" %} {# Sets variant to "primary" if variant isn't defined #}
{% prop size "small" "medium" "large" %} {# If DEBUG=True, explodes if size is not one of the following #}

Or alternatively, using filters and var.

{% var color=color|required %}
{% var variant=variant|default:"primary" %}
{% var size=size|one_of:"small,medium,large" %}

Maybe we could add shorthand syntax to var so we don't have to have the variable name twice.

{% var color|required %}
{% var variant|default:"primary" %}
{% var size|one_of:"small,medium,large" %}

I'm keen to hear your ideas as well for how to improve the discoverability of component parameters.

[Marcin Gordziejewski]

What you've proposed is actually more or less what I thought about - having a way to define that at the top of component.

More so - if you would have such definitions in the components themselves there could be a way to have some kind of static checks that you can run as for example django command that would tell you if all components are properly used / you defined all variables that you try to use. Like manage.py check_components would tell you componentX in file.py:123 is not defining required param *color*. Or componentY uses param size but has no definition. This could be really useful for CI pipelines to be sure everyone follows same convention.

This would be incredibly useful IMO.

I'm not just sure if filters are fit for that. I was thinking more in terms of pydantic models that you would assign to components. Not as clean as what you provided (because defining that in the same file would be impossible) but on the other hand it would allow for some more complex validation. It would also allow for better integration with IDE plugins if they were to be ever created for your project :).

But I like the idea of defining these as filters.

[Mitchel Cabuloy]

I've started working on this on #25

[Jan Baykara]

The work you've done in #25 is fantastic and it makes me think of the possibility of code editor 'intellisense'-style extensions. By scanning for components.yaml files, then parsing the frontmatter of referenced components' template files, a code editor extension could provide hints and autocompletions for available props, as one types. This is especially simple as Slippers prefixes template tags with a #.

[Matthias Schoettle]

I see that #25 is merged. However, after the last release. Are there any plans for the next release?

[Mitchel Cabuloy]

Sorry my weekends have been busy and I haven't finished writing the docs. That's why the next release is taking so long.

[Matthias Schoettle]

No problem, totally understand. Let me know if there is any way I can help.

[Mitchel Cabuloy]

Hiya. This is now out with v0.6.0, but no docs yet.