[Toolkit] Add support for documenting props API

[Kocal]

Maybe something similar to https://github.com/smnandre/ux-kit-bootstrap/blob/743023df35fa8b4925f115c76d36dc869cbca4dc/bootstrap/templates/components/Carousel.html.twig#L1-L23

Either in the same file, but we need to introduce some parsing first in order to validate them (and use them in the UX website on component documentation page), either we simply put them in the *.meta.json files (that's the easiest solution for the moment)

[Kocal]

WDYT about the following syntax {# @prop <name> <type> <description> #}? Similary to @var when documenting properties inside a PHP class:

{# @prop variant 'default'|'secondary'|'destructive'|'outline'|'ghost'|'link' The variant, default to "default" #}
{# @prop size 'default'|'sm'|'lg'|'icon' The size, default to "default" #}
{# @prop as 'button' The HTML tag to use, default to "button" #}
{# @block content The default block #}
{%- props variant = 'default', size = 'default', as = 'button' -%}
{%- set style = html_cva(
    base: 'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
    variants: {
        variant: {
            default: 'bg-primary text-primary-foreground hover:bg-primary/90',
            secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
            destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
            outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
            ghost: 'hover:bg-accent hover:text-accent-foreground',
            link: 'text-primary underline-offset-4 hover:underline',
        },
        size: {
            default: 'h-10 px-4 py-2',
            sm: 'h-9 rounded-md px-3',
            lg: 'h-11 rounded-md px-8',
            icon: 'h-10 w-10',
        },
    },
) -%}

<{{ as }}
    class="{{ style.apply({variant: variant, size: size}, attributes.render('class'))|tailwind_merge }}"
    {{ attributes }}
>
    {%- block content %}{% endblock -%}
</{{ as }}>

?

I think it could be easily parsed and understandable by human.

cc @kbond @smnandre

[smnandre]

I'm not sure using prop (@ + singular) for documentation and props (no @ + plural) for runtime checks is safe, I think I would find it a bit confusing tbh ...

And i'm really not sure about the quotes (at least for enum-like, choices list)

Lastly, parsing comments is a real challenge, as it must be before the Lexer work, and i'm not sure we should do another pass of pre-lexer 😅

What about a custom block to type / declare component, props, other

{% declare prop variant =  .... %}
{% declare @variant =  .... %}
{% declare variant:  %}

... multiple similar words could be helpful and why not allow us to "reserve" the first word

{% define variant ... %}
{% define option ... %}
{% define prop ... %}

wdyt ?

[Kocal]

Going for {% declare %} or {% define %} means that we, or Twig, must implement these Twig tags, which is not something I wan't:

• Toolkit should never boot at the runtime, it should stays an "improved copy-paste tool"
• I don't think it will benefit Twig

Using comments is the way to go.

[smnandre]

Well I miss understood the parsing part, for sure!

Then yeah, looks good to me!