import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Introduction" />

# UI-Bundle Component Documentation

Interactive documentation for UI-Bundle's Twig components, powered by **php-wasm**
for exact PHP Twig rendering in the browser.

## How It Works

Unlike typical Storybook setups, this documentation runs **actual PHP Twig** in your browser:

1. **php-wasm** compiles PHP 8.1 to WebAssembly
2. **Twig 3.x** renders templates exactly as in production
3. **Symfony Twig Bridge** provides familiar functions and filters
4. **UiExtension** functions work with mocked services

What you see here matches what renders in production — no Twig.js approximations.

## Theme Switcher

The toolbar exposes the bundle's real theme axes — the same `$website-*-theme`
globals consuming sites set before importing the SCSS:

| Toolbar | SCSS global | Values |
|---|---|---|
| Grayscale | `$website-grayscale-theme` | `deepblue` (default), `onyx` |
| Radius | `$website-radius-theme` | `pepper` (default), `smoothy`, `dolce`, `honey` |
| Icons | `$website-icon-theme` | `rounded` (default), `sharp` |

Use them to check that a component holds up across every theme the bundle supports.

## Using Components

**Macro-based components** (Button, Label, Thumbnail):

```twig
{% from '@Ui/component/button.html.twig' import button %}

{{ button({ text: 'Click me', size: 'md' }) }}
```

**Include-based components** (Title, Subtitle, Share):

```twig
{% include '@Ui/component/title.html.twig' with {
    title_text: 'Section Title',
    title_markup: 'h2'
} only %}
```

**Extend-based sections** (Grid Layout, Roller Layout):

```twig
{% extends '@Ui/section/dynamic_content/layout_grid_simple.html.twig' %}

{% block item %}
    <article>{{ item.title }}</article>
{% endblock %}
```

## Component Contracts: the `@prop` Docblock

Templates document their parameters in a header docblock, which is the **single
source of truth** for the controls you see in Storybook:

```twig
{#-
    @component Button
    @propObject button_obj
    Versatile button component.

    @prop text ?string [Core] Button text label
    @prop size ?"sm"|"md"|"lg" [Core] Button size
-#}
```

`scripts/generate-argtypes.ts` turns these into story argTypes and **fails the CI
build** when a docblock and its template body disagree, or when the generated
file is stale. To update: edit the docblock, then run `pnpm run gen:argtypes`
in `.storybook/`. Params marked `{no-control}` are part of the template contract
but have no styling shipped in the bundle; `{deprecated}` params are kept for
backward compatibility only.

## Source Panel

Each story includes a **Source** panel (addons bar below) with:

- **Twig Usage** — copy-paste ready code for your templates
- **HTML Output** — the actual rendered markup
- **View template on GitLab** — jumps to the template source at the built commit

## Component Tiers

| Tier | Purpose | Examples |
|---|---|---|
| **Components** | Atomic building blocks | Button, Label, Title |
| **Modules** | Feature compositions | Pagination, Footer, Dropdown, Video Card |
| **Sections** | Page layouts | Grid Layout, Roller Layout |

## Getting Help

- Experiment with props in the **Controls** panel
- Check the **Unsupported Functions** panel for mock limitations
- Twig errors show the failing template, line number, and a code frame
- Source code: `templates/component/`, `templates/module/`, `templates/section/`
