# API - Component Playground

The public playground demonstrates shared components and page markup patterns.

## Mounting

| Item | Path | Description |
|---|---|---|
| Route | `src/pages/routes.php` | Registers `playground` as public |
| Controller | `src/pages/public/playground/playground.controller.php` | Enqueues page JavaScript |
| View | `src/pages/public/playground/playground.view.php` | Renders fixtures and filters |
| JavaScript | `src/pages/public/playground/playground.js` | Applies URL-backed filtering |

Pages are resolved by `src/index.php` and wrapped by the active theme header/footer.

## Filter URL

| Parameter | Values | Default |
|---|---|---|
| `category` | `all`, or a category key | `all` |
| `component` | `all`, or a component key | `all` |

Example: `/playground?category=forms&component=showInputText`.

The script updates the current URI with `history.replaceState()` and restores it after refresh. Invalid combinations select `all`. Selecting `all` hides the entire subcategory tab row; selecting a category shows only that category's component tabs.

Paired lifecycle methods use one example: `startForm` with `endForm` and `startEmptyRow` with `endEmptyRow`. Page and block wrappers are implicit in the playground page and are not rendered as standalone examples.

## Categories

| Category | Components |
|---|---|
| `template` | Page, block, navigation, accordion, fields |
| `forms` | Full form, lifecycle, text, inputs, selects, buttons |
| `choices` | Radios, checkbox, language options |
| `feedback` | Alerts, status, CAPTCHA, CSRF token |
| `commerce` | Product helpers and store/cart placeholder |
| `ranking` | Generic ranking placeholder |
| `profiles` | User, guild, and player-icon placeholders |
| `content` | Complete CMS category and content-node layouts |
| `markup` | Tables, lists, images |

`forms/full-form` is the first forms example and exercises all form-rendering methods with static values. `forms/plain-form` follows it and renders every plain-capable control with `$plain=true`, one per `<div>`. Individual form examples follow these two for focused filtering.

## Empty Examples

| Key | Button config |
|---|---|
| `commerce/store-cart` | `store-cart` |
| `ranking/generic-ranking` | `generic-ranking` |
| `profiles/user-details` | `user-details` |
| `profiles/guild-members` | `guild-members` |
| `profiles/class-icons` | `class-icons` |

These sections intentionally render no example content. Their category/component metadata only controls the filter buttons. Add plain HTML or existing component methods when populating them; do not add custom data-config arrays without approval.

Content examples are complete presentation cases, not individual helper cards:

| Example | Rendered structure | Required classes / DOM hierarchy |
|---|---|---|
| `category-list` | Category title, breadcrumb, description, image, news list | `.panel.panel-content-category` > `.content-category-description` + `.content-node-image.content-category-image` + `.content-category-news` > `article.blog-item` > `.blog-content` > `.entry-header` > `h3` > `a` + `.content-node-image` + `.blog-story.short-story` |
| `category-cards` | Category title, breadcrumb, description, image, cards news list | `.panel.panel-content-category` > `.content-category-description` + `.content-node-image.content-category-image` + `.news-list.content-category-cards` > `article.news-card` > `.news-date` + `h3` > `a` + `p.text-muted` |
| `category-dropdown` | Category title, breadcrumb, description, image, FAQ dropdown | `.panel.panel-content-category` > `.content-category-description` + `.content-node-image.content-category-image` + `.faqs.content-category-dropdown` > `.accordion` > `.accordion__box-title` + `.accordion__box-content` |
| `category-description` | Category preview with description | `article.blog-item` > `.blog-content` > `.entry-header` > `h3` > `a` + `.content-node-image` + `.blog-category.short-story` > `.content-category-description` |
| `category-children` | Category preview with child links and dates | `article.blog-item` > `.blog-content` > `.entry-header` > `h3` > `a` + `.content-node-image` + `.blog-category.short-story` > `.content-category-preview-list` > `.content-category-preview-item` > `a` + `time` |
| `category-preview-dropdown` | Category preview with FAQ dropdown | `article.blog-item` > `.blog-content` > `.entry-header` > `h3` > `a` + `.content-node-image` + `.blog-category.short-story` > `.faqs.content-category-dropdown` > `.accordion` > `.accordion__box-title` + `.accordion__box-content` |
| `content-node` | Node title, breadcrumb, image, article body | `.panel.panel-content-article` > `.content-node-image.content-article-image` + `.content-article-body` |

### Required Classes for Content Cards (`category-cards`)

Themes implementing or styling the `cards` category list style must support:

- `.news-list.content-category-cards`: Grid or list wrapper for the article cards.
- `article.news-card`: Individual card container element.
- `.news-date`: Publication date container (uppercase `d M Y`).
- `h3 > a`: Card title heading wrapping the clickable hyperlink to the content node.
- `p.text-muted`: Card summary or excerpt paragraph.

## References

- `Docs/api/template-components.md`
- `Docs/api/form-components.md`
- `src/core/templates/components-base.template.php`
- `src/core/templates/components-form-base.template.php`
- `Docs/knowledge/05-content-management.md`
- `src/core/modules/Content/Content.php`
- `src/core/modules/Content/templates/news-content.php`
- `src/core/modules/Content/templates/news-category-description.php`
- `src/core/modules/Content/templates/news-category-children.php`
- `src/core/modules/Content/templates/news-category-dropdown.php`
- `src/settings/helpers.php` (`loadPageJS`)
- `src/pages/public/register/register.view.php`
- `src/pages/public/profile/profile.view.php`
- `src/pages/public/ranking/ranking.view.php`
- `src/pages/public/events/events.view.php`
- `src/pages/public/store/store.view.php`
- `src/pages/private/cart/cart.view.php`
- `src/pages/private/cart/cart-items.view.php`
- `Docs/knowledge/20-cart-orders.md`
- `Docs/knowledge/21-payment-discounts.md`
- `src/pages/private/recover-character/recover-character.view.php`
- `src/pages/private/notifications/notifications.view.php`
- `src/pages/admin/manual-sell/manual-sell.view.php`

## Theme Notes

- `ComponentsTemplate` and `FormComponents` are loaded from `THEME_PATH`.
- Theme overrides may change wrappers and visual output.
- Filter behavior depends only on playground `data-*` attributes.
- Footer-mounted helpers, including the floating cart, are not duplicated.
- Product examples use static fixtures and must not perform real purchases.
- Content examples copy production classes and structure manually; they never include content templates or query CMS data.