[Twig][Live] add component attribute system/helper

[kbond]

Q	A
Bug fix?	no
New feature?	yes
Tickets	n/a
License	MIT

A common pattern with other component library's (ie blade components/vue) is to pass html attributes to your component that are set on the component's root node. This proposal adds a way to do this with twig components. Enable on your component by adding the HasAttributesTrait. Attributes are any data passed to component() that cannot be mounted on the component itself. This extra data is added to a ComponentAttributes object that lives as a public property on your component (available as attributes in your component's template).

This should all work out-of-the box with live components.

Todo:

• Tests
• Documentation
• Upgrade php-cs-fixer used in gh action and run on php 8 #240
• [LiveComponent] add ability to have array props #241
• Merge init_live_component() into attributes when available
• Document PreRender event.
• Adjust ComponentAttributes api (defaults instead of merge)
• attributes always available in normal twig component templates (not sure about this - it would effectively make attributes native but it a lame way)
• replace init_live_component() with attributes in docs
• Finalize docs (versionadded tags)

Usage

To use, add the HasAttributesTrait to your component:

#[AsTwigComponent('my_component')]
class MyComponent
{
    use HasAttributesTrait;
}

Then, in your component's template:

{# templates/components/my_component.html.twig #}

<div{{ attributes }}>
  My Component!
</div>

When rendering the component, you can pass an array of html attributes to add:

{{ component('my_component', { class: 'foo', style: 'color:red' }) }}

{# renders as: #}
<div class="foo" style="color:red">
  My Component!
</div>

Defaults & Merging

In your component template, you can set defaults that are merged with
passed attributes. The passed attributes override the default with
the exception of class. For class, the defaults are prepended:

{# templates/components/my_component.html.twig #}

<button{{ attributes.defaults({ class: 'bar', type: 'button' }) }}>
  My Component!
</button>

{# render component #}
{{ component('my_component', { style: 'color:red' }) }}
{{ component('my_component', { class: 'foo', type: 'submit' }) }}

{# renders as: #}
<div class="bar" style="color:red">
  My Component!
</div>
<div class="bar foo" type="submit">
  My Component!
</div>

Only

{# templates/components/my_component.html.twig #}

<div{{ attributes.only('class')) }}>
  My Component!
</div>

{# render component #}
{{ component('my_component', { class: 'foo', style: 'color:red' }) }}

{# renders as: #}
<div class="foo">
  My Component!
</div>

Without

{# templates/components/my_component.html.twig #}

<div{{ attributes.without('class')) }}>
  My Component!
</div>

{# render component #}
{{ component('my_component', { class: 'foo', style: 'color:red' }) }}

{# renders as: #}
<div style="color:red">
  My Component!
</div>

Live Components

We removed the init_live_component() twig function (BC BREAK) and replaced with the attributes variable which is always available (even if your component doesn't use HasAttributesTrait).

To upgrade, replace all calls to init_live_component() with attributes:

- <div {{ init_live_component() }}>
+ <div {{ attributes }}>

[kbond]

629d834 demonstrates a bit of a hack to remove the requirement for {{ attributes|raw }}. Maybe there's a better way to do this?

BTW, I'm totally fine to just live with |raw.

[seb-jean]

I love this feature @kbond

[kbond]

To make this feature live, I was thinking to mark the property as a LiveProp (with a hydrator) so it just works when making an existing component live.

[weaverryan]

I like this - and the idea is proven by other libraries.

629d834 demonstrates a bit of a hack to remove the requirement for {{ attributes|raw }}. Maybe there's a better way to do this?

See https://twig.symfony.com/doc/3.x/api.html#escaper-extension - look for addSafeClass. I think that's the correct way to handle this.

To make this feature live, I was thinking to mark the property as a LiveProp (with a hydrator) so it just works when making an existing component live.

I can't think of why this would be a problem. So 👍

This proposal adds a way to do this (albeit a bit verbose) with twig components

2 ideas for this, both which are beyond the scope of this PR:

A) Allow using "…args" for the “props”

{{ component('my_component', attributes: { class: 'foo', style: 'color:red' }, otherProp: 'bar' ) }}

It removes an extra {} basically.

2. Allowing using an <component attributes="" style for the components.

[weaverryan]

Also, it would be great if, for live components, we could also do:

<div{{ attributes }}>

Instead of:

<div {{ init_live_component(this) }}>

[kbond]

See https://twig.symfony.com/doc/3.x/api.html#escaper-extension - look for addSafeClass. I think that's the correct way to handle this.

This is what I used. The hack I was referring to is the weird way of adding it in the extension. I don't think there's a great way for a third party bundle to add these.

[kbond]

The LiveComponent failing test will be fixed once #241 is merged/rebased. The cs fixer will pass once #240 is merged/rebased.

[weaverryan]

I really like this version!

[weaverryan]

Thank you Kevin!

[seb-jean]

Hi,

I wanted to use a null value but I got the following error:

An exception has been thrown during the rendering of a template ("Unable to use "value" (null) as an attribute. Attributes must be scalar. If you meant to mount this value on your component, make sure this is a writable property.").

{{ component('input', {type: 'text', name: 'query', value: form.address.vars.data }) }}

form.address.vars.data can be null at times.

I saw that it was this error that is affected: https://github.com/symfony/ux-twig-component/blob/2.x/src/HasAttributesTrait.php#L49

[kbond]

Ah, good catch, so you'd expect the html to be:

<input type="text" name="query" value="" />

[seb-jean]

@kbond Exactly

[seb-jean]

Something else to improve (maybe):
Sometimes, we don't need to provide a value like for the autofocus property.
How could we do to have just autofocus instead of autofocus="" ?
https://developer.mozilla.org/fr/docs/Web/HTML/Global_attributes/autofocus

[kbond]

Another good catch, @weaverryan and I were discussing and we think null or empty string should mean render the attribute name only:

{{ component('input', {type: 'text', name: 'query', value: null, autofocus: null }) }}

<input type="text" name="query" value autofocus />

WDYT?

[seb-jean]

Yes, null is better I think.
I don't see any other solutions anyway.

[kbond]

You're thinking?

{{ component('input', {type: 'text', name: 'query', value: '', autofocus: null }) }}

<input type="text" name="query" value="" autofocus />

There are some limitations to doing this when working with live components. But we are discussing some solutions.

[seb-jean]

Yeah