UI Storia

https://github.com/iq2i/storia-bundle
Admin
UI Storia is a visual and modular development environment that simplifies UI development in Symfony...
Tokens:36,692
Snippets:562
Trust Score:3.9
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Full Configuration Example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/configuration.md

Comprehensive configuration example demonstrating environment variable usage and custom watch paths.

```yaml
# config/packages/iq2i_storia.yaml
iq2i_storia:
  # Relative or absolute path to storia YAML files
  default_path: '%kernel.project_dir%/storia'
  
  # Enable/disable - useful for production
  enabled: '%env(bool:STORIA_ENABLED)%'
  
  # Paths to watch during development (for live reload)
  watch:
    - '%kernel.project_dir%/assets'
    - '%kernel.project_dir%/templates'
    - '%kernel.project_dir%/src'  # Custom addition
```

--------------------------------

### Process YAML configuration example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/yaml-preprocessing.md

Example demonstrating the processing of a YAML file into a configuration array.

```php
$config = $preprocessor->process('/app/storia', 'components/button');

// Returns validated array:
[
    'component' => 'Button',
    'variants' => [
        'primary' => ['args' => [...], 'blocks' => [...]],
        'secondary' => ['args' => [...], 'blocks' => [...]],
    ],
]
```

--------------------------------

### Template Support Examples

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Usage examples demonstrating explicit, implicit, and unsupported template configurations.

```php
// Explicit template config
$config = ['template' => 'components/button.html.twig', 'variants' => [...]];
$builder->supports('components/button', $config); // true

// Implicit template (file exists)
$builder->supports('components/button', []); // true if components/button.html.twig exists

// No template
$config = ['form' => 'MyFormClass'];
$builder->supports('components/button', $config); // false
```

--------------------------------

### Resolve file path usage examples

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/yaml-preprocessing.md

Examples demonstrating how to resolve file paths and handle path traversal security.

```php
$preprocessor = new YamlPreProcessor();

$preprocessor->resolveFilePath('/app/storia', 'components/button');
// Returns '/app/storia/components/button.yaml' (if exists)

$preprocessor->resolveFilePath('/app/storia', 'components/button');
// Returns '/app/storia/components/button.yml' (if .yaml doesn't exist)

$preprocessor->resolveFilePath('/app/storia', '../../etc/passwd');
// Returns null (path escapes base)
```

--------------------------------

### Watch Command Output Example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

Example console output showing active watch paths and detected file changes.

```text
[16:30:45] Watching [page]: /app/storia
[16:30:45] Watching [iframe]: /app/assets
[16:30:45] Watching [iframe]: /app/templates
[16:30:45] Watching for changes… (Ctrl+C to stop)
[16:30:52] Change detected: button.yaml (update) → page reload
[16:30:58] Change detected: button.scss (update) → iframe reload
```

--------------------------------

### FormBuilder supports() Usage Example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Examples demonstrating how the supports method evaluates form configurations.

```php
$config = ['form' => 'App\Form\ButtonType'];
$builder->supports('forms/button', $config); // true (if class exists)

$config = ['form' => 'NonExistentForm'];
$builder->supports('forms/button', $config); // false
```

--------------------------------

### ComponentBuilder YAML Configuration Example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Example YAML configuration for defining a component and its variants.

```yaml
component: Button
variants:
  primary:
    args:
      label: Click Me
      type: primary
  secondary:
    args:
      label: Don't Click
      type: secondary
    blocks:
      default: |
        <span>Icon</span>
```

--------------------------------

### Configure IQ2iStoriaBundle

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/bundle.md

Example YAML configuration for the bundle settings.

```yaml
iq2i_storia:
  default_path: '%kernel.project_dir%/storia'
  enabled: true
  watch:
    - '%kernel.project_dir%/assets'
    - '%kernel.project_dir%/templates'
```

--------------------------------

### FormBuilder YAML Configuration Example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Example YAML configuration for a form, including options and a custom form theme.

```yaml
form: App\Form\UserType
options:
  label: User Form
form_theme: '@MyApp/form/custom_theme.html.twig'
```

--------------------------------

### Example Usage of Menu

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Demonstrates creating a menu, adding children, and sorting them.

```php
$menu = new Menu('Components');
$menu->addChild(new MenuItem('Button', '/storia/components/button', false))
     ->addChild(new MenuItem('Card', '/storia/components/card', false))
     ->reorderChildren();

echo $menu->getLabel();          // 'Components'
echo count($menu->getChildren()); // 2
```

--------------------------------

### View Usage Example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Demonstrates creating a View instance and accessing its properties and current variant.

```php
use IQ2i\StoriaBundle\View\Dto\View;
use IQ2i\StoriaBundle\View\Dto\Variant;

$variant = new Variant('primary', 'Primary Button', true);

$view = new View(
    path: 'components/button',
    twigContent: '{{ label }}',
    htmlContent: '<button>Click me</button>',
    includeContent: '<Button text="Click me" />',
    markdownContent: '<h2>Button Component</h2><p>A clickable button.</p>',
    variants: [$variant]
);

echo $view->getPath();              // 'components/button'
echo $view->getTwigContent();       // '{{ label }}'
echo $view->getHtmlContent();       // '<button>Click me</button>'

$current = $view->getCurrentVariant();
echo $current->getName();           // 'Primary Button'
```

--------------------------------

### Example Usage of MenuItem

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Demonstrates creating a menu item and accessing its properties.

```php
$item = new MenuItem('Primary Button', '/storia/components/button', true);

echo $item->getLabel();    // 'Primary Button'
echo $item->getUrl();      // '/storia/components/button'
echo $item->isActive();    // true
```

--------------------------------

### Example usage of MenuBuilder

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Demonstrates how to generate a menu and inspect its properties based on a request.

```php
use IQ2i\\\StoriaBundle\\\Menu\\\MenuBuilder;
use Symfony\\\Component\\\HttpFoundation\\\Request;

// MenuBuilder is injected
$request = new Request();
$request->server->set('REQUEST_URI', '/storia/components/button');

$menu = $menuBuilder->createSidebarMenu($request);

echo $menu->getLabel();                        // null (root)
$children = $menu->getChildren();              // [Components, Pages]
$components = $children[0];
echo $components->getLabel();                  // 'Components'
echo $components->isOpened();                  // true (has active child)

foreach ($components->getChildren() as $item) {
    echo $item->getLabel();
    echo $item->getUrl();
    echo $item->isActive() ? 'ACTIVE' : '';
}
```

--------------------------------

### Register Bundle and Configuration

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/bundle.md

Example of registering the bundle in bundles.php and setting configuration in a YAML file.

```php
// In config/bundles.php
return [
    IQ2i\StoriaBundle\IQ2iStoriaBundle::class => ['all' => true],
];

// In config/packages/iq2i_storia.yaml
iq2i_storia:
  default_path: '%kernel.project_dir%/storia'
  enabled: '%env(STORIA_ENABLED)%'
```

--------------------------------

### Integrate HighlightController in HTML

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Example of applying the highlight controller to a code block.

```html
<pre><code class="language-twig" data-controller="highlight">
{{ variable }}
</code></pre>
```

--------------------------------

### Iframe request and response example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/controllers.md

Example of an iframe request and the resulting response structure.

```http
// Request
GET /storia/iframe/components/button?variant=primary

// Response headers
200 OK
Content-Type: text/html; charset=utf-8

// Response body (either direct HTML or wrapped version)
<html>
  <head>...</head>
  <body>
    <button>...</button>
  </body>
</html>
```

--------------------------------

### Usage example for HighlightController

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Demonstrates highlighting a Twig loop block.

```html
<pre><code data-controller="highlight" class="language-twig">
{% for item in items %}
  <div>{{ item.name }}</div>
{% endfor %}
</code></pre>
```

--------------------------------

### ViewController request examples

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/controllers.md

Illustrates how the controller handles requests with and without variant parameters.

```text
// Request to /storia/components/button
// GET /storia/components/button
// → Redirects to GET /storia/components/button?variant=primary

// Request with variant
// GET /storia/components/button?variant=secondary
// → Renders full interface with secondary variant
```

--------------------------------

### Integrate ResizeController in HTML

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Example structure for the resize controller with orientation and boundary configuration.

```html
<div data-controller="resize" 
     data-resize-orientation-value="horizontal"
     data-resize-min-value="0.1"
     data-resize-max-value="0.9"
     style="--resize-size: 0.2">
  
  <div data-resize-target="panelA" class="panel-left">
    Left content
  </div>
  
  <div data-resize-target="resizer" class="resizer"></div>
  
  <div data-resize-target="panelB" class="panel-right">
    Right content
  </div>
</div>
```

--------------------------------

### View Endpoint Behavior Examples

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Demonstration of redirect behavior when no variant is provided versus rendering the full interface.

```text
GET /storia/components/button
→ 302 Redirect to /storia/components/button?variant=primary
```

```text
GET /storia/components/button?variant=primary
→ 200 OK (full HTML page)
```

--------------------------------

### Request and Response examples for /changes

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Standard HTTP request and response headers for establishing the SSE connection.

```http
GET /storia/changes HTTP/1.1
Host: localhost
Accept: text/event-stream
```

```http
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
X-Accel-Buffering: no
Transfer-Encoding: chunked
```

--------------------------------

### Integrate ControlsController in HTML

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Example of setting up the controls controller with iframe targets and action buttons.

```html
<div data-controller="controls" data-controls-scale-value="1">
  <button data-action="controls#refreshIframe">Refresh</button>
  <button data-action="controls#zoomIn">Zoom In</button>
  <button data-action="controls#zoomOut">Zoom Out</button>
  <button data-action="controls#resetZoom">Reset</button>
  <button data-action="controls#copyLink">Copy Link</button>
  
  <iframe data-controls-target="iframe" src="/storia/iframe/..."></iframe>
</div>
```

--------------------------------

### Implement custom UI with MenuExtension

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/twig-extensions.md

A complete example demonstrating how to render a sidebar menu and view details using the extension.

```twig
{# templates/storia/view.html.twig #}
<div class="storia-layout">
  <aside class="sidebar">
    <nav class="menu">
      {% for section in iq2i_storia_menu() %}
        <div class="menu-section">
          {% if section.label %}
            <h3 class="menu-section-title">{{ section.label }}</h3>
          {% endif %}
          
          <ul class="menu-list">
            {% for item in section.children %}
              <li class="menu-item{% if item.active %} active{% endif %}">
                {% if item.url %}
                  <a href="{{ item.url }}" class="menu-link">
                    {{ item.label }}
                  </a>
                {% else %}
                  <span class="menu-submenu-title">{{ item.label }}</span>
                {% endif %}
              </li>
            {% endfor %}
          </ul>
        </div>
      {% endfor %}
    </nav>
  </aside>
  
  <main class="content">
    <div class="view-details">
      {% if view %}
        <h1>{{ view.path }}</h1>
        
        <div class="variant-selector">
          {% for variant in view.variants %}
            <a href="?variant={{ variant.path }}" 
               class="btn{% if variant.current %} active{% endif %}">
              {{ variant.name }}
            </a>
          {% endfor %}
        </div>
        
        {% if view.markdownContent %}
          <div class="documentation">
            {{ view.markdownContent | raw }}
          </div>
        {% endif %}
        
        <div class="preview">
          <iframe src="/storia/iframe/{{ view.path }}?variant={{ view.currentVariant.path }}"></iframe>
        </div>
        
        {% if view.twigContent %}
          <div class="source">
            <h3>Template</h3>
            <pre><code class="language-twig" data-controller="highlight">{{ view.twigContent }}</code></pre>
          </div>
        {% endif %}
        
        {% if view.includeContent %}
          <div class="include">
            <h3>Include</h3>
            <pre><code class="language-twig" data-controller="highlight">{{ view.includeContent }}</code></pre>
          </div>
        {% endif %}
      {% else %}
        <div class="error">Component not found</div>
      {% endif %}
    </div>
  </main>
</div>
```

--------------------------------

### Variant Usage Example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Demonstrates instantiation of Variant objects and usage of getter methods.

```php
use IQ2i\StoriaBundle\View\Dto\Variant;

$primaryVariant = new Variant('primary', 'Primary Button', true);
$secondaryVariant = new Variant('secondary', 'Secondary Button', false);
$disabledVariant = new Variant('disabled', 'Disabled Button', false);

echo $primaryVariant->getPath();    // 'primary'
echo $primaryVariant->getName();    // 'Primary Button'
echo $primaryVariant->isCurrent();  // true

echo $secondaryVariant->isCurrent(); // false
```

--------------------------------

### Request component preview

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Example HTTP request to retrieve a component preview with a specific variant.

```http
GET /historia/iframe/components/button?variant=primary HTTP/1.1
Host: localhost
Accept: text/html
```

--------------------------------

### Template Configuration YAML

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Example YAML configuration defining a template and its variants.

```yaml
template: components/button.html.twig
variants:
  primary:
    args:
      label: Click Me
      type: primary
  secondary:
    args:
      label: Don't Click
      type: secondary
```

--------------------------------

### Usage of ViewBuilder

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-builder.md

Example of using ViewBuilder to retrieve and interact with a View object.

```php
use IQ2i\\\StoriaBundle\\\View\\\ViewBuilder;
use Symfony\\\Component\\\HttpFoundation\\\Request;

// Assuming ViewBuilder is injected
$request = new Request();
$request->attributes->set('view', 'components/button');

$view = $viewBuilder->createFromRequest($request);

if ($view !== null) {
    echo $view->getPath();          // 'components/button'
    echo $view->getTwigContent();   // Twig template source
    echo $view->getHtmlContent();   // Rendered HTML
    
    foreach ($view->getVariants() as $variant) {
        echo $variant->getName();   // e.g., 'Primary', 'Secondary'
    }
}
```

--------------------------------

### Start development workflow

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

Commands to run the development server and the file watcher in separate terminal sessions.

```bash
# Terminal 1: Start development server
php bin/console server:run

# Terminal 2: Start file watcher
php bin/console storia:watch

# Now in your editor, make changes
# → Watcher detects change
# → Browser automatically reloads
```

--------------------------------

### _definitions block usage

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/yaml-preprocessing.md

Example of defining reusable anchors within a _definitions block.

```yaml
_definitions:
  common_args: &common
    size: md
    padding: default

component: Button
variants:
  primary:
    args:
      <<: *common
      type: primary
  secondary:
    args:
      <<: *common
      type: secondary
```

--------------------------------

### JavaScript client implementation

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/controllers.md

Example of how to consume the SSE stream and handle reload or stop events in the browser.

```javascript
const eventSource = new EventSource('/storia/changes');

eventSource.addEventListener('reload', (e) => {
  const { type } = JSON.parse(e.data);
  if (type === 'page') {
    window.location.reload();
  } else if (type === 'iframe') {
    // Reload iframe
  }
});

eventSource.addEventListener('stop', () => {
  eventSource.close();
});
```

--------------------------------

### Include directive file structure

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/yaml-preprocessing.md

Example of how to structure files to use the include directive with _definitions blocks.

```yaml
# storia/_shared.yaml
_definitions:
  button_defaults: &button_defaults
    type: primary
    size: md
  text_colors: &text_colors
    light: '#ffffff'
    dark: '#000000'

# storia/components/button.yaml
include: _shared
component: Button
variants:
  primary:
    args:
      <<: *button_defaults
      label: Click Me
  secondary:
    args:
      <<: *button_defaults
      type: secondary
```

--------------------------------

### Complex YAML Configuration Example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/yaml-preprocessing.md

Demonstrates the use of YAML anchors and aliases for shared definitions and component inheritance.

```yaml
# storia/_shared.yaml
_definitions:
  sizes: &sizes
    sm: small
    md: medium
    lg: large
  states: &states
    enabled: true
    disabled: false

# storia/components/button-base.yaml
include: _shared
component: Button
variants:
  default:
    args:
      <<: *sizes
      <<: *states

# storia/components/button-variants.yaml
extends: components/button-base
variants:
  default:
    args:
      size: md
  large:
    args:
      size: lg
```

--------------------------------

### Start the file watcher

Source: https://github.com/iq2i/storia-bundle/blob/main/doc/pages/index.md

Execute this command in the terminal to begin monitoring files for changes.

```bash
bin/console storia:watch
```

--------------------------------

### Integrate LiveReloadController in HTML

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Example of attaching the controller to a DOM element and configuring the SSE URL.

```html
<div data-controller="live-reload" 
     data-live-reload-url-value="/storia/changes">
  <iframe data-live-reload-target="iframe" src="..."></iframe>
</div>
```

--------------------------------

### Integrate MenuController in HTML

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Example structure for the menu controller using data attributes for targets and actions.

```html
<div data-controller="menu" data-menu-opened-value="false">
  <button data-action="menu#toggle">
    <svg data-menu-target="svg" class="menu-closed">→</svg>
  </button>
  
  <ul data-menu-target="submenu" class="hidden">
    <li><a href="#">Item 1</a></li>
    <li><a href="#">Item 2</a></li>
  </ul>
</div>
```

--------------------------------

### Get HTML Content

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Retrieves the rendered HTML output.

```php
public function getHtmlContent(): ?string
```

--------------------------------

### Get Markdown Content

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Retrieves the markdown documentation rendered as HTML.

```php
public function getMarkdownContent(): ?string
```

--------------------------------

### Get Include Content

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Retrieves the generated include or component statement.

```php
public function getIncludeContent(): ?string
```

--------------------------------

### GET /storia/components/{component}

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Retrieves a specific UI component view.

```APIDOC
## GET /storia/components/{component}

### Description
Retrieves the rendered view of a specific component.

### Method
GET

### Endpoint
/storia/components/{component}

### Parameters
#### Path Parameters
- **component** (string) - Required - The identifier of the component to view.

#### Query Parameters
- **variant** (string) - Optional - The specific variant of the component to render.
```

--------------------------------

### Install StoriaBundle via Composer

Source: https://github.com/iq2i/storia-bundle/blob/main/doc/pages/index.md

Run this command in your terminal to add the bundle dependency to your project.

```bash
composer require iq2i/storia-bundle
```

--------------------------------

### Integrate TabController in HTML

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Example structure for implementing tabbed content using data attributes for controllers, targets, and actions.

```html
<div data-controller="tab" data-tab-index-value="0">
  <div class="tabs">
    <button class="tab" data-tab-target="tab" data-action="tab#change">
      Tab 1
    </button>
    <button class="tab" data-tab-target="tab" data-action="tab#change">
      Tab 2
    </button>
  </div>
  
  <div data-tab-target="tabPanel" class="tab-panel">
    Panel 1 content
  </div>
  <div data-tab-target="tabPanel" class="tab-panel hidden">
    Panel 2 content
  </div>
</div>
```

--------------------------------

### Invoke Watch Command

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

Command line execution to start the file watcher.

```bash
php bin/console storia:watch
```

--------------------------------

### GET /iframe/{view}

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Renders a component preview in a sandboxed iframe without a page wrapper.

```APIDOC
## GET /iframe/{view}

### Description
Renders component preview in sandboxed iframe without page wrapper.

### Method
GET

### Endpoint
/iframe/{view}

### Parameters
#### Path Parameters
- **view** (string) - Required - Path to YAML file without extension

#### Query Parameters
- **variant** (string) - Required - Selected variant identifier

### Request Example
GET /historia/iframe/components/button?variant=primary HTTP/1.1
Host: localhost
Accept: text/html

### Response
#### Success Response (200)
- **body** (string/html) - Rendered component HTML with minimal document structure

#### Status Codes
- 200: OK - Component rendered successfully
- 404: Not Found - Component YAML file not found
```

--------------------------------

### Variant Name Generation Examples

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Demonstrates the transformation logic applied to variant paths to generate human-readable display names.

```text
Input path:  'primaryLargeButton'
Output name: 'Primary Large Button'

Input path:  'disabled_state'
Output name: 'Disabled State'

Input path:  'error-with-icon'
Output name: 'Error With Icon'
```

--------------------------------

### Implement sidebar menu template

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Complete example of rendering a recursive sidebar menu using the iq2i_storia_menu function and a partial template.

```twig
{# Render sidebar menu #}
<ul class="menu">
  {% for item in iq2i_storia_menu() %}
    {% include '@IQ2iStoria/menu/_item.html.twig' with {
      item: item,
      level: 0
    } %}
  {% endfor %}
</ul>

{# _item.html.twig #}
<li class="menu-item{% if item.active %} active{% endif %}">
  {% if item is instanceof('IQ2i\\StoriaBundle\\Menu\\Dto\\MenuItem') %}
    <a href="{{ item.url }}">{{ item.label }}</a>
  {% else %}
    <span class="menu-label">{{ item.label }}</span>
    {% if item.opened %}
      <ul class="submenu">
        {% for child in item.children %}
          {% include '@IQ2iStoria/menu/_item.html.twig' with {
            item: child,
            level: level + 1
          } %}
        {% endfor %}
      </ul>
    {% endif %}
  {% endif %}
</li>
```

--------------------------------

### Watch Command Log Output

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

Example of the log format generated when file changes are detected by the watcher.

```text
[16:30:52] Change detected: button.yaml (update) → page reload
[16:30:58] Change detected: button.scss (update) → iframe reload
[16:31:05] Change detected: new-component.yaml (create) → page reload
```

--------------------------------

### YAML Variant Configuration

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Example YAML structure for defining component variants within a configuration file.

```yaml
# components/button.yaml
component: Button
variants:
  primary:
    name: Primary
    args:
      label: Click Me
  secondary:
    name: Secondary
    args:
      label: Don't Click Me
```

--------------------------------

### GET /{view}

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/controllers.md

Handles HTTP requests to display the story UI. If no variant is specified, it redirects to the first available variant; otherwise, it renders the component interface.

```APIDOC
## GET /{view}

### Description
Handles HTTP requests to display the story UI. If no variant is specified, it redirects to the first available variant; otherwise, it renders the component interface.

### Method
GET

### Endpoint
/{view}

### Parameters
#### Path Parameters
- **view** (string) - Required - The view identifier path.

#### Query Parameters
- **variant** (string) - Optional - The specific variant of the component to render.

### Response
#### Success Response (200)
- **Response** (HTML) - Renders the @IQ2iStoria/view.html.twig template.
```

--------------------------------

### GET /changes

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/controllers.md

Establishes a Server-Sent Events (SSE) stream to receive file change notifications for live reloading.

```APIDOC
## GET /changes

### Description
Handles the SSE stream for live reload events. The server polls for file changes and pushes events to the client.

### Method
GET

### Endpoint
/changes

### Response
#### Success Response (200)
- **Content-Type** (header) - text/event-stream
- **Cache-Control** (header) - no-cache
- **X-Accel-Buffering** (header) - no

### Stream Events
- **reload**: Sent when a change is detected. Data: `{"type":"page"}` or `{"type":"iframe"}`.
- **stop**: Sent when the stream is closing.
```

--------------------------------

### GET /{view}

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Displays the complete UI Storia interface for a specific component or page, including documentation, source code, and preview.

```APIDOC
## GET /{view}

### Description
Displays the complete UI Storia interface for a specific component or page. It renders the sidebar, component preview, variant selector, and documentation.

### Method
GET

### Endpoint
/{view}

### Parameters
#### Path Parameters
- **view** (string) - Required - Path to YAML file without extension (e.g., components/button)

#### Query Parameters
- **variant** (string) - Optional - Selected variant identifier

### Request Example
GET /storia/components/button?variant=secondary HTTP/1.1
Host: localhost
Accept: text/html

### Response
#### Success Response (200)
- **body** (html) - Complete HTML document containing the UI Storia interface.

#### Status Codes
- 200: OK - Component found and rendered
- 404: Not Found - Component YAML file not found
```

--------------------------------

### Extends directive inheritance example

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/yaml-preprocessing.md

Demonstrates deep merging behavior when extending a base component configuration.

```yaml
# storia/components/base-button.yaml
component: Button
variants:
  primary:
    args:
      type: primary
      size: md
      label: Default
  secondary:
    args:
      type: secondary
      size: md
      label: Default

# storia/components/large-button.yaml
extends: components/base-button
variants:
  primary:
    args:
      size: lg
```

```yaml
component: Button
variants:
  primary:
    args:
      type: primary
      size: lg          # ← overridden
      label: Default    # ← inherited
  secondary:
    args:
      type: secondary
      size: md
      label: Default
```

--------------------------------

### Request View Endpoint

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Example HTTP requests for accessing a component view with and without a variant parameter.

```http
GET /storia/components/button HTTP/1.1
Host: localhost
Accept: text/html

GET /storia/components/button?variant=secondary HTTP/1.1
Host: localhost
Accept: text/html
```

--------------------------------

### Define Component Arguments in YAML

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/arg-resolver.md

Example of referencing a class method within a component variant configuration.

```yaml
# stories/components/user-profile.yaml
component: UserProfile
variants:
  loaded:
    args:
      user: App\DataFixture::getTestUser
```

--------------------------------

### Get Variants

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Retrieves all available variants for the view.

```php
public function getVariants(): array
```

--------------------------------

### Get Current Variant

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Retrieves the currently selected variant.

```php
public function getCurrentVariant(): ?Variant
```

--------------------------------

### Get View Path

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Retrieves the path identifier for the view.

```php
public function getPath(): string
```

--------------------------------

### SSE Event Formats

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Examples of the different event types sent over the stream, including reload triggers, stop signals, and keepalive pings.

```text
event: reload
data: {"type":"page"}

event: reload
data: {"type":"iframe"}
```

```yaml
type: object
properties:
  type:
    type: string
    enum: [page, iframe]
    description: Reload scope - page for full reload, iframe for preview only
```

```text
event: stop
data: {}
```

```text
: ping

```

--------------------------------

### GET /storia/changes

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Provides a live reload stream for UI changes.

```APIDOC
## GET /storia/changes

### Description
Establishes a server-sent event stream for live reloading.

### Method
GET

### Endpoint
/storia/changes

### Headers
- **Accept**: text/event-stream
```

--------------------------------

### GET /storia/pages/{page}

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Retrieves a specific UI page view.

```APIDOC
## GET /storia/pages/{page}

### Description
Retrieves the rendered view of a specific page.

### Method
GET

### Endpoint
/storia/pages/{page}

### Parameters
#### Path Parameters
- **page** (string) - Required - The identifier of the page to view.

#### Query Parameters
- **variant** (string) - Optional - The specific variant of the page to render.
```

--------------------------------

### Implement supports() method

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Define the logic to determine if the builder can handle a specific configuration based on the path and array structure.

```php
public function supports(string $path, array $config): bool
```

--------------------------------

### GET /iframe/{view}

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/controllers.md

Handles HTTP requests to render a component preview in an iframe. The controller disables the Symfony profiler, resolves the view, and returns the component HTML, optionally wrapping it in a minimal document structure if necessary.

```APIDOC
## GET /iframe/{view}

### Description
Handles HTTP requests to render component preview in iframe. Disables the Symfony profiler and returns an HTML response without a layout wrapper.

### Method
GET

### Endpoint
/iframe/{view}

### Parameters
#### Path Parameters
- **view** (string) - Required - The component view identifier.

#### Query Parameters
- **variant** (string) - Optional - The specific variant of the component to render.

### Response
#### Success Response (200)
- **Response** (HTML) - HTML content of the component, either as-is or wrapped in the iframe template.

#### Error Response (404)
- **NotFoundHttpException** - Returned if the requested component view is not found.
```

--------------------------------

### Retrieve Menu Label

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Method to get the display label of the menu.

```php
public function getLabel(): ?string
```

--------------------------------

### Initialize MenuExtension constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/twig-extensions.md

Constructor requiring the MenuBuilder service.

```php
public function __construct(
    private readonly MenuBuilder $menuBuilder,
)
```

--------------------------------

### Retrieve MenuItem URL

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Method to get the link URL of the menu item.

```php
public function getUrl(): ?string
```

--------------------------------

### Retrieve MenuItem Label

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Method to get the display text of the menu item.

```php
public function getLabel(): string
```

--------------------------------

### Retrieve Menu Children

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Method to get all child Menu or MenuItem objects.

```php
public function getChildren(): array
```

--------------------------------

### Initialize Menu Constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Constructor for creating a new Menu instance with optional label, open state, and children.

```php
public function __construct(
    private readonly ?string $label = null,
    private bool $opened = false,
    private array $children = [],
)
```

--------------------------------

### Get Twig Content

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Retrieves the raw Twig template source code.

```php
public function getTwigContent(): ?string
```

--------------------------------

### View Constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Initializes a new View instance with template content, rendered output, and associated variants.

```php
public function __construct(
    private string $path,
    private ?string $twigContent = null,
    private ?string $htmlContent = null,
    private ?string $includeContent = null,
    private ?string $markdownContent = null,
    private array $variants = [],
)
```

--------------------------------

### Initialize MenuBuilder

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Constructor requirements for the MenuBuilder service.

```php
public function __construct(
    private string $defaultPath,
    private RouterInterface $router,
)
```

--------------------------------

### Implement build() method

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Define the logic to construct a View object using the provided request, path, and configuration.

```php
public function build(Request $request, string $path, array $config): ?View
```

--------------------------------

### Configuration Keys

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/INDEX.md

Define the bundle configuration in your YAML file.

```yaml
iq2i_storia:
  default_path: string      # Default: %kernel.project_dir%/storia
  enabled: boolean          # Default: true
  watch: string[]           # Default: [assets, templates]
```

--------------------------------

### Initialize MenuItem Constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/menu.md

Constructor for creating a new MenuItem instance.

```php
public function __construct(
    private string $label,
    private ?string $url = null,
    private bool $active = false,
)
```

--------------------------------

### WatchCommand Constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

Constructor for initializing the command with required path configurations.

```php
public function __construct(
    private readonly string $defaultPath,
    private readonly array $watchPaths,
    private readonly string $projectDir,
)
```

--------------------------------

### Configure Var Directory

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

Ensure the var directory exists and has appropriate write permissions for the watcher.

```bash
mkdir -p var
chmod 777 var
```

--------------------------------

### Render variant blocks in template

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/twig-extensions.md

Example of rendering variant blocks within a Twig template.

```twig
{% set blocks = iq2i_storia_variant_blocks('components/button', 'with_icon') %}

<button>
  {% if blocks.icon %}
    {{ blocks.icon | raw }}
  {% endif %}
  
  {% if blocks.label %}
    {{ blocks.label | raw }}
  {% else %}
    {{ args.label }}
  {% endif %}
</button>
```

--------------------------------

### Access variant arguments in template

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/twig-extensions.md

Example of accessing variant arguments within a Twig template.

```twig
{% set args = iq2i_storia_variant_args('components/button', 'primary') %}

{# In template #}
Label: {{ args.label }}      {# 'Click Me' #}
Type: {{ args.type }}        {# 'primary' #}
Icon: {{ args.icon }}        {# null #}
```

--------------------------------

### Implementing a Custom Builder

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Create a custom builder by implementing the BuilderInterface, defining support logic, and providing the build implementation.

```php
use IQ2i\StoriaBundle\View\Builder\BuilderInterface;
use IQ2i\StoriaBundle\View\Dto\View;
use Symfony\Component\HttpFoundation\Request;

class CustomBuilder implements BuilderInterface
{
    public function supports(string $path, array $config): bool
    {
        return isset($config['custom_type']);
    }

    public function build(Request $request, string $path, array $config): ?View
    {
        // Your implementation
        return new View(
            $path,
            twigContent: '...',
            htmlContent: '...',
            variants: [...]
        );
    }
}
```

--------------------------------

### Configure Bundle Method

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/bundle.md

Method signature for configuring the bundle's configuration tree.

```php
public function configure(DefinitionConfigurator $definition): void
```

--------------------------------

### ViewController constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/controllers.md

Initializes the controller with necessary services for view building, templating, and routing.

```php
public function __construct(
    private ViewBuilder $viewBuilder,
    private Environment $twig,
    private RouterInterface $router,
)
```

--------------------------------

### GET /storia/iframe/{type}/{name}

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Retrieves a component or page view optimized for iframe embedding.

```APIDOC
## GET /storia/iframe/{type}/{name}

### Description
Retrieves a component or page view specifically for iframe previewing.

### Method
GET

### Endpoint
/storia/iframe/{type}/{name}

### Parameters
#### Path Parameters
- **type** (string) - Required - The type of resource (components or pages).
- **name** (string) - Required - The identifier of the resource.

#### Query Parameters
- **variant** (string) - Optional - The specific variant to render.
```

--------------------------------

### Define Bundle Configuration

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/types.md

Structure for the main bundle configuration settings.

```php
array{
    'default_path': string,   // Base directory for storia YAML files
    'enabled': boolean,       // Enable/disable UI Storia
    'watch': string[]         // Directories to monitor for changes
}
```

--------------------------------

### Configuration Classes

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/INDEX.md

Classes for handling YAML preprocessing and view configuration.

```php
namespace IQ2i\StoriaBundle\Config;

class YamlPreProcessor
- resolveFilePath(string $basePath, string $path): ?string
- process(string $basePath, string $path): array

class ViewConfiguration implements ConfigurationInterface
- getConfigTreeBuilder(): TreeBuilder
```

--------------------------------

### View Project File Organization

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/INDEX.md

Displays the directory structure of the project documentation and source files.

```text
output/
├── README.md                           # Overview & architecture
├── INDEX.md                            # This file
├── configuration.md                    # Bundle configuration
├── endpoints.md                        # HTTP endpoints
├── types.md                            # Type definitions
└── api-reference/
    ├── bundle.md                       # IQ2iStoriaBundle
    ├── view-builder.md                 # ViewBuilder
    ├── view-dto.md                     # View/Variant DTOs
    ├── builders.md                     # Builder implementations
    ├── controllers.md                  # HTTP controllers
    ├── menu.md                         # Menu system
    ├── yaml-preprocessing.md           # YAML processing
    ├── arg-resolver.md                 # Argument resolution
    ├── twig-extensions.md              # Twig functions
    ├── frontend-controllers.md         # JS controllers
    └── watch-command.md                # File watching
```

--------------------------------

### Development Environment Configuration

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/configuration.md

Configure Storia for development, including file watching paths.

```yaml
# config/packages/dev/iq2i_storia.yaml
iq2i_storia:
  enabled: true
  default_path: '%kernel.project_dir%/storia'
  watch:
    - '%kernel.project_dir%/assets'
    - '%kernel.project_dir%/templates'
```

--------------------------------

### Builder Interfaces and Implementations

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/INDEX.md

Interfaces and concrete classes for view building strategies.

```php
namespace IQ2i\StoriaBundle\View\Builder;

interface BuilderInterface
- supports(string $path, array $config): bool
- build(Request, string, array): ?View

class AbstractBuilder
- generateInclude(string, array): string
- getTwigContent(string): string
- generateHtml(string, array): string

class ComponentBuilder extends AbstractBuilder
- supports(string, array): bool
- build(Request, string, array): ?View

class TemplateBuilder extends AbstractBuilder
- supports(string, array): bool
- build(Request, string, array): ?View

class FormBuilder extends AbstractBuilder
- supports(string, array): bool
- build(Request, string, array): ?View
```

--------------------------------

### Path traversal protection

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-builder.md

Example of a request that triggers path traversal protection, resulting in a null return.

```php
// This will return null (path escapes base dir)
$view = $viewBuilder->createFromRequest($request);
$request->attributes->set('view', '../../etc/passwd');
```

--------------------------------

### Build Method

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/bundle.md

Method signature for registering compiler passes.

```php
public function build(ContainerBuilder $container): void
```

--------------------------------

### Handle non-existent directory warning

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

Displays the log message when a specific directory is skipped because it does not exist.

```text
<comment>Skipping non-existent directory: /app/nonexistent</comment>
```

--------------------------------

### Build Controller Assets

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Commands to trigger the Rollup build process for bundling frontend controllers.

```bash
npm run build    # Build once
npm run watch    # Watch for changes
```

--------------------------------

### Expected Directory Structure

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/configuration.md

The required file system layout for components and pages within the default path.

```text
{default_path}/
├── components/
│   ├── button.yaml
│   ├── button/
│   │   ├── button.yaml
│   │   └── button.md
│   └── card.yaml
└── pages/
    ├── dashboard.yaml
    └── profile.yaml
```

--------------------------------

### ViewExtension constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/twig-extensions.md

Constructor requiring the base directory for YAML files.

```php
public function __construct(
    private readonly string $defaultPath,
)
```

--------------------------------

### iq2i_storia_menu()

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/twig-extensions.md

Retrieves the full menu structure.

```APIDOC
## iq2i_storia_menu()

### Description
Retrieves the entire menu structure configured in the application.

### Returns
- **array** - The complete menu structure.
```

--------------------------------

### Initialize Method

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

Lifecycle method that runs upon controller initialization to set the default tab.

```javascript
initialize()
```

--------------------------------

### Disable UI Storia via Environment Variable

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/endpoints.md

Command line example to disable UI Storia using an environment variable.

```bash
STORIA_ENABLED=false php bin/console server:run
```

--------------------------------

### Load Extension Method

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/bundle.md

Method signature for loading and registering services and controllers.

```php
public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
```

--------------------------------

### Implement and Register a Custom Builder

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/README.md

Define a class implementing BuilderInterface and register it in services.yaml using the iq2i_storia.builder tag.

```php
class CustomBuilder implements BuilderInterface { }
```

```yaml
services:
  App\Builder\CustomBuilder:
    tags:
      - iq2i_storia.builder
```

--------------------------------

### Include directive syntax

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/yaml-preprocessing.md

Demonstrates various ways to include shared YAML definitions using the include directive.

```yaml
include: _shared
component: Button
variants:
  primary:
    args:
      <<: *button_defaults
```

```yaml
include:
  - _shared
  - _colors
  - _spacing
component: Button
```

```yaml
include: [_shared, _colors]
component: Button
```

--------------------------------

### process(string $basePath, string $path)

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/yaml-preprocessing.md

Processes a Storia YAML file and returns the fully resolved configuration array.

```APIDOC
## process(string $basePath, string $path)

### Description
Processes a Storia YAML file and returns the resolved configuration. It handles include and extends directives to resolve cross-file dependencies.

### Parameters
- **$basePath** (string) - Required - Base directory path
- **$path** (string) - Required - Relative path without extension

### Returns
- **array** - Processed configuration array

### Throws
- **RuntimeException** - File not found, circular extends detected, or include file missing

### Example
```php
$config = $preprocessor->process('/app/storia', 'components/button');
```
```

--------------------------------

### View Building Classes

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/INDEX.md

Classes for building and representing views and variants.

```php
namespace IQ2i\StoriaBundle\View;

class ViewBuilder
- __construct(string, iterable, YamlPreProcessor)
- createFromRequest(Request): ?View

namespace IQ2i\StoriaBundle\View\Dto;

readonly class View
- getPath(): string
- getTwigContent(): ?string
- getHtmlContent(): ?string
- getIncludeContent(): ?string
- getMarkdownContent(): ?string
- getVariants(): array
- getCurrentVariant(): ?Variant

readonly class Variant
- getPath(): string
- getName(): string
- isCurrent(): bool
```

--------------------------------

### ViewBuilder constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-builder.md

Constructor requiring the default path, a collection of builders, and the YAML preprocessor.

```php
public function __construct(
    private string $defaultPath,
    private iterable $builders,
    private YamlPreProcessor $yamlPreProcessor,
)
```

--------------------------------

### Register Custom Builders

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/configuration.md

Register a custom builder class by tagging it with iq2i_storia.builder.

```yaml
# config/services.yaml
services:
  App\Builder\CustomBuilder:
    arguments:
      - '%iq2i_storia.default_path%'
      - '@twig'
    tags:
      - iq2i_storia.builder
```

--------------------------------

### Handle missing builder

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-builder.md

Exception thrown when a configuration is valid but no registered builder supports it.

```php
throw new \\LogicException(
    'Missing template for component "components/unknown"'
);
```

--------------------------------

### Load Dynamic Data for Components

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/README.md

Configure component variants in YAML files to fetch data from static methods or fixtures.

```yaml
# stories/components/list.yaml
component: MyList
variants:
  with_items:
    args:
      items: App\DataFixture::getTestItems
```

--------------------------------

### Menu System Classes

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/INDEX.md

Classes for building and managing the sidebar menu.

```php
namespace IQ2i\StoriaBundle\Menu;

readonly class MenuBuilder
- __construct(string $defaultPath, RouterInterface $router)
- createSidebarMenu(Request): Menu

namespace IQ2i\StoriaBundle\Menu\Dto;

class Menu
- __construct(?string, bool, array)
- getLabel(): ?string
- isOpened(): bool
- setOpened(bool): static
- getChildren(): array
- addChild(Menu|MenuItem): static
- reorderChildren(): static

readonly class MenuItem
- __construct(string, ?string, bool)
- getLabel(): string
- getUrl(): ?string
- isActive(): bool
```

--------------------------------

### Variant Constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/view-dto.md

Initializes a new Variant instance with a path, name, and optional current status.

```php
public function __construct(
    private string $path,
    private string $name,
    private bool $isCurrent = false,
)
```

--------------------------------

### Configure Bundle Routes

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/bundle.md

Import the bundle routes into your application's routing configuration.

```yaml
// In config/routes.yaml
storia:
  resource: '@IQ2iStoriaBundle/config/routes.php'
  prefix: /storia
```

--------------------------------

### AbstractBuilder Constructor

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/builders.md

Initializes the builder with a default path and Twig environment.

```php
public function __construct(
    protected string $defaultPath,
    protected Environment $twig,
)
```

--------------------------------

### Implement graceful shutdown

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

PHP implementation for handling SIGINT and SIGTERM signals to stop child processes gracefully.

```php
if (function_exists('pcntl_async_signals')) {
    pcntl_async_signals(true);
    $stop = function () use (&$running, $processes) {
        $running = false;
        foreach ($processes as ['process' => $process]) {
            $process->stop(5);  // 5 second timeout
        }
        // Signal stop event to browser
    };
    pcntl_signal(SIGINT, $stop);
    pcntl_signal(SIGTERM, $stop);
}
```

--------------------------------

### TabController

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/frontend-controllers.md

A Stimulus controller for managing tabbed content with switchable panels.

```APIDOC
## TabController

### Description
Manages tabbed content with switchable panels using Stimulus data attributes.

### Properties
- **index** (Number) - Default: 0 - Currently selected tab index

### Targets
- **tab** - Tab buttons (multiple)
- **tabPanel** - Tab content panels (multiple)

### Methods

#### initialize()
Runs once when controller is initialized. Shows the default tab (index 0).

#### change(e)
Called when a tab button is clicked. Calculates index from button position and updates the indexValue.
- **e** (ClickEvent) - Click event from button

#### showTab()
Shows tab and panel at current index by iterating all pairs, hiding non-active elements, and applying CSS classes.
```

--------------------------------

### Verify File Permissions

Source: https://github.com/iq2i/storia-bundle/blob/main/_autodocs/api-reference/watch-command.md

Check that the watcher binary has the correct executable permissions.

```bash
ls -la src/tools/watcher/bin/
# Should show executable (rwxr-xr-x)
```
Tokens:
Raw