Skip to content

[Toolkit] Refactor (again) but improve @prop and @block comments format#3694

Merged
Kocal merged 1 commit into
symfony:3.xfrom
Kocal:feat/toolkit-lint-component-doc
Jul 5, 2026
Merged

[Toolkit] Refactor (again) but improve @prop and @block comments format#3694
Kocal merged 1 commit into
symfony:3.xfrom
Kocal:feat/toolkit-lint-component-doc

Conversation

@Kocal

@Kocal Kocal commented Jul 5, 2026

Copy link
Copy Markdown
Member
Q A
Bug fix? no
New feature? yes
Deprecations? no
Documentation? no
Issues Fix #...
License MIT

Related to twigphp/Twig#4770 and Haehnchen/idea-php-symfony2-plugin#2545

Improve the Kit linting by introducing ComponentDocChecker, which ensures {# @prop #} and {# @block #} comments are correctly formatted (no Defaults to ..., ensure capital letter at the start and . at the end,
ensure type is correct, ...).

This also introduces a new class ComponentDocParser, responsible for parsing the first lines of Twig components from Kit recipes, e.g.:

{# @prop defaultValue string Define the open Tabs at initial rendering. #}
{# @prop orientation 'horizontal'|'vertical' Define the visual orientation. #}
{# @block content The default block. #}
{%- props defaultValue = '', orientation = 'horizontal' -%}

<div
    data-controller="tabs"
    data-tabs-active-tab-value="{{ defaultValue }}"
    data-orientation="{{ orientation }}"
    class="{{ ('gap-4 group/tabs flex data-[orientation=horizontal]:flex-col ' ~ attributes.render('class'))|tailwind_merge }}"
    {{ attributes }}
>
    {% block content %}{% endblock %}
</div>

Here, the ComponentDocParser will be able to return a ComponentDoc, which contains a list of Prop and a list of Block, representing parsed @prop and @block comments. The @prop default value is now read from
{% props ... %} tag, no more duplication, no more string manipulation on the description to extract the default value (Defaults to ...).

This logic originally lived (in a simpler form) in the UX website repository, but moving (and improving) it here is IMHO a good choice:

  • a single logic for parsing component documentation
  • it can be used by both the UX website and the UX Toolkit linting tool
  • and it can drive LLMs to easily fix issues found by the linting tool.

All kit recipes were fixed accordingly.

@Kocal Kocal force-pushed the feat/toolkit-lint-component-doc branch from 83fde5c to 359ffca Compare July 5, 2026 19:00
@Kocal Kocal merged commit ac4f12f into symfony:3.x Jul 5, 2026
33 checks passed
@Kocal Kocal deleted the feat/toolkit-lint-component-doc branch July 5, 2026 19:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Feature New Feature Status: Needs Review Needs to be reviewed Toolkit

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants