---
url: /guide/introduction.md
---
# Introduction

**FilamentCraft** is a Shopify-style visual website builder for **Filament v4 and v5**.
Drag-and-drop sections, a live iframe preview, revisioned templates, undo/redo, and
multi-tenant support — all installed into your existing Filament panel.

::: tip Dual version support
FilamentCraft dual-supports Filament 4 (with Livewire 3) and Filament 5 (with Livewire 4)
from one codebase. Composer picks the right pair based on what your host app already has
installed. See [Dual Version Support](/reference/dual-version).
:::

## Requirements

* PHP 8.2+
* Laravel 11 or 12
* Filament 4.x or 5.x
* Livewire 3.x or 4.x

## What you get out of the box

* **Editor page** — left rail of section catalog + page sections, center iframe preview
  (desktop / tablet / mobile), right settings panel.
* **12 built-in sections** — Header, Hero, Logo cloud, Features, Image with text, Stats,
  Testimonials, Pricing, FAQ, Rich text, CTA, Footer. Toggle all off with
  `->withBuiltinSections(false)` or hide specific section types with `->withoutSections([...])`.
* **Live preview** — section-level refresh from the server's draft state (no full reload),
  debounced settings, undo/redo with a 50-step ring buffer, autosave-to-draft every keystroke.
* **Revisions** — every Save creates a `template_revision` row; Publish promotes the head
  revision to the public-facing one. Discard rolls back to the published state.
* **Public routing** — opt-in catch-all that serves published templates. Off by default;
  flip on when you want FilamentCraft to own the front-end.
* **Multi-tenant** — sites can belong to any host model (`User`, `Workspace`, `Shop`, …)
  via a polymorphic `owner` morph. Resolves automatically against Filament's tenant.
* **Homepage assignment** — set any template as the site's `/` from the editor topbar.

## How the pieces fit together

| Concept | What it is |
|---|---|
| **Site** | A buildable website. Belongs to an owner model (for multi-tenant apps) and points at a Theme. |
| **Theme** | A PHP class that declares the settings panel your end-users see — colors, typography, buttons, color schemes, etc. |
| **Template** | A page within a Site (`home`, `pricing`, …). Has a status (draft / published) and a type. |
| **Template Revision** | An immutable snapshot of a template's sections. Every Save writes one; Publish promotes one. |
| **Region** | Shared areas (header / footer) rendered around every page and around custom dynamic pages. |
| **Section** | A reusable block (Hero, Features, …) with a static settings schema and a Blade view. |

## Where to go next

* [Installation](/guide/getting-started) — install via Anystack, register the plugin, build your first page.
* [Sections](/guide/sections) — use the built-ins, write custom sections, curate the catalog.
* [Theme Authoring](/guide/theme-authoring) — expose a full theme settings panel to your users.
* [Tenancy](/guide/tenancy) — how the current Site is resolved at runtime.

## License

Proprietary — see [filamentcraft.dev](https://filamentcraft.dev) for commercial tiers.
Distributed via [Anystack](https://anystack.sh).

---

---
url: /guide/getting-started.md
---
# Installation

FilamentCraft is distributed as a private Composer package through
[Anystack](https://anystack.sh). You'll add the private repository and HTTP basic
credentials, then `composer require` as usual.

## Install

```bash
# Use the Composer repository URL and credentials shown in your Anystack license/account.
composer config repositories.filamentcraft composer <your-anystack-composer-repository-url>
composer config http-basic.<your-anystack-host> <username> <license-key>
composer require filamentcraft/filamentcraft
php artisan filamentcraft:install
```

Anystack private Composer packages require adding the private repository and HTTP basic
credentials before `composer require`; the license key is used as the Composer password.

The install command:

* publishes the config + migrations and runs them,
* registers editor assets via `filament:assets`,
* creates the public storage symlink used by image uploads.

## Start with an example site

To land on a working page right after install, pass `--example`:

```bash
php artisan filamentcraft:install --example
```

That seeds a `studio` Theme, a `studio-demo` Site, and a published `home` template
populated with Hero + Features + Footer sections. Re-running the command is idempotent —
the second invocation prints `Example site already seeded` and exits cleanly.

## Register the plugin

Register the plugin on the panel that should host the editor:

```php
use FilamentCraft\FilamentCraftPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->plugin(FilamentCraftPlugin::make());
}
```

That's it for the minimal install — open the panel and you'll find a **Templates** resource
and an **Editor** page.

## Build your first page

1. Create a **Theme** and **Site** row (via the resources or a seeder).
2. Add a **Template** and click **Open in Editor**.
3. Add sections from the catalog, edit their settings, and watch the live preview update.
4. **Save** to write a draft revision, then **Publish** to promote it.

## Next steps

* [Styling & Tailwind](/guide/styling) — wire FilamentCraft into your panel's Tailwind build.
* [Sections](/guide/sections) — the built-in catalog and writing your own.
* [The Editor](/guide/editor) — topbar actions, devices, focus mode, undo/redo.

---

---
url: /guide/styling.md
---
# Styling & Tailwind

FilamentCraft ships compiled fallback CSS so the editor and the built-in sections are
usable immediately after `php artisan filamentcraft:install`. For a real project, you
should still use a Filament custom theme and let the host app compile the Tailwind classes
used by this package and by your own sections.

## Why a custom theme

Filament's default panel stylesheet only contains Filament's own UI classes. Any Tailwind
utilities used in package views, custom pages, custom section Blade files, or section PHP
classes must be visible to the host app's Tailwind build.

## 1. Create a panel theme

Create a panel theme if the app does not already have one:

```bash
php artisan make:filament-theme admin
```

## 2. Register it on the panel

```php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->viteTheme('resources/css/filament/admin/theme.css')
        ->plugin(FilamentCraftPlugin::make());
}
```

## 3. Add FilamentCraft (and your section) sources

Add FilamentCraft and your own section sources to
`resources/css/filament/admin/theme.css`:

```css
@import '../../../../vendor/filament/filament/resources/css/theme.css';

@source '../../../../app/Filament/**/*';
@source '../../../../resources/views/filament/**/*';

/* FilamentCraft editor views, field views, and PHP classes that emit classes. */
@source '../../../../vendor/filamentcraft/filamentcraft/resources/views/**/*.blade.php';
@source '../../../../vendor/filamentcraft/filamentcraft/src/**/*.php';

/* Your host-app sections. */
@source '../../../../app/Sections/**/*.php';
@source '../../../../resources/views/sections/**/*.blade.php';

@custom-variant dark (&:where(.dark, .dark *));
```

## 4. Rebuild

Rebuild after changing the source list:

```bash
npm run build
php artisan filament:assets
```

This follows Filament's plugin guidance: plugin views that use Tailwind should be included
in the host custom theme with `@source`. FilamentCraft keeps its compiled CSS enabled as a
fallback for quick installs and for users who have not created a custom theme yet.

::: info Preview & public-page styling
The Filament panel theme styles the editor *chrome*. The iframe preview and public template
output are **separate HTML documents** that need their own CSS. See
[Preview & Public Assets](/reference/assets) for the three-tier asset model.
:::

---

---
url: /guide/sections.md
---
# Sections

Sections are the reusable building blocks that make up a page — Hero, Features, Pricing, and
so on. A page (template) is an ordered list of section instances, each with its own settings,
blocks, and color scheme.

FilamentCraft ships **12 built-in sections** and treats custom sections as a first-class
citizen: a single PHP class plus a Blade view is all it takes to add your own.

## Start here

| Page | What it covers |
|---|---|
| [Built-in Sections](/guide/built-in-sections) | All 12 shipped sections — their settings, blocks, and presets. |
| [Custom Sections](/guide/custom-sections) | Author your own section, mix DSL + Filament components, add blocks and presets. |
| [Curating the Catalog](/guide/curating-the-catalog) | Control which section types appear in the Add Section picker. |
| [Setting Types](/guide/inputs/overview) | Every input you can put in a section's `settings()`. |

## Anatomy of a section

* **Settings** — the controls shown in the section's panel, declared in a static `settings()`
  method. See [Setting Types](/guide/inputs/overview).
* **Blocks** — repeatable child items (nav links, pricing plans, quotes) with their own
  settings and an optional limit. See [Custom Sections → Blocks](/guide/custom-sections#blocks).
* **Presets** — named, one-click starting points bundling settings + blocks. See
  [Custom Sections → Presets](/guide/custom-sections#presets).
* **A Blade (or Livewire) view** — renders the resolved data on the page.

## A custom section in 30 seconds

```php
namespace App\Sections;

use FilamentCraft\Sections\BladeSection;
use FilamentCraft\Settings\Types\Text;
use FilamentCraft\Settings\Types\Textarea;

final class TestimonialSection extends BladeSection
{
    protected static string $view = 'sections.testimonial';

    public static function slug(): string { return 'testimonial'; }
    public static function name(): string { return 'Testimonial'; }

    public static function settings(): array
    {
        return [
            Textarea::make('quote')->label('Quote')->required(),
            Text::make('author')->label('Author')->required(),
        ];
    }

    public static function defaults(): array
    {
        return ['settings' => ['author' => 'Customer Name'], 'blocks' => []];
    }
}
```

Register it with `->registerSection(\App\Sections\TestimonialSection::class)` or drop it in
`app/Sections/` for auto-discovery. The full walkthrough — the contract, blocks, presets, and
extending a built-in — is in [Custom Sections](/guide/custom-sections).

::: tip Scaffold it
`php artisan make:filamentcraft-section Testimonial` generates the class and Blade view (add
`--livewire` for a Livewire section). See [Make Commands](/reference/commands).
:::

---

---
url: /guide/built-in-sections.md
---
# Built-in Sections

FilamentCraft ships **12** built-in sections, registered automatically unless you opt out.
Each is a `BladeSection` subclass under `FilamentCraft\Sections\Builtin` with a curated
settings schema, optional repeatable **blocks**, and one or more ready-made **presets**.

| # | Section | Slug | Icon | Blocks |
|---|---|---|---|---|
| 1 | Header | `header` | `heroicon-o-bars-3` | `nav-link` |
| 2 | Hero | `hero` | `heroicon-o-sparkles` | `proof` (limit 4) |
| 3 | Logo cloud | `logo-cloud` | `heroicon-o-building-office-2` | `logo` |
| 4 | Features | `features` | `heroicon-o-squares-2x2` | `feature` |
| 5 | Image with text | `image-text` | `heroicon-o-photo` | — |
| 6 | Stats | `stats` | `heroicon-o-chart-bar` | `stat` |
| 7 | Testimonials | `testimonials` | `heroicon-o-chat-bubble-left-right` | `quote` |
| 8 | Pricing | `pricing` | `heroicon-o-credit-card` | `plan` |
| 9 | FAQ | `faq` | `heroicon-o-question-mark-circle` | `item` |
| 10 | Rich text | `rich-text` | `heroicon-o-document-text` | — |
| 11 | CTA | `cta` | `heroicon-o-megaphone` | — |
| 12 | Footer | `footer` | `heroicon-o-bars-3-bottom-left` | `link` |

::: info Where to find them
The registration list lives in `FilamentCraftPlugin::BUILTIN_SECTIONS`; each class is in
`src/Sections/Builtin/`. To hide or replace them, see
[Curating the Catalog](/guide/curating-the-catalog).
:::

## Shared style enums

Most sections expose the same four `EnumButtons` controls, backed by these enums (each
implements `HasLabel`, `HasColor`, `HasIcon` and offers an `::options()` helper):

| Enum | Setting | Cases |
|---|---|---|
| `SectionShape` | `shape` | `clean`, `contained`, `layered`, `wireframe` |
| `SectionDensity` | `density` | `compact`, `comfortable`, `airy` |
| `SectionAlignment` | `align` / `content_align` | `start`, `center` |
| `MediaPlacement` | `media_mode` / `media_placement` | `none`, `background`, `start`, `end` |

Every section also exposes a `ColorScheme::make('scheme')` control — see
[Color Inputs](/guide/inputs/color#colorscheme).

***

## 1. Header

A site header with brand, navigation links, an optional CTA, and a locale switcher.

**Settings:** `brand_text` (Text), `brand_logo` (Image), `cta_enabled` (Toggle),
`cta_label` (Text, shown when `cta_enabled`), `cta_url` (Link, shown when `cta_enabled`),
`show_locale_switcher` (Toggle), `alignment` (Select: `split` / `centered` / `compact`),
`sticky` (Toggle), `show_border` (Toggle), `shape` + `density` (EnumButtons),
`scheme` (ColorScheme).

**Blocks:** `nav-link` — `label` (Text), `url` (Link).

**Presets:** *Split Header*, *Centered Header*.

## 2. Hero

The flagship section, and a live demonstration of the dual-input schema (DSL settings sit
next to raw Filament components like `Toggle`, `ColorPicker`, and `TemplateUrlPicker`).

**Settings:** `eyebrow`, `heading` (Text), `subheading` (Textarea), `cta_enabled` (Toggle),
`cta_url` (TemplateUrlPicker — searches published templates), `cta_label` (Text),
`supporting_text` (Text), `bg_image` (Image), `media_mode` (EnumButtons → `MediaPlacement`),
`layout` (Select: `spotlight` / `editorial` / `compact`),
`content_align` (EnumButtons → `SectionAlignment`),
`density` (EnumButtons → `SectionDensity`), `shape` (EnumButtons → `SectionShape`),
`scheme` (ColorScheme), `surface_style` (Select: `glass` / `solid` / `none`),
`use_accent_override` (Toggle), `accent_color` (ColorPicker, shown when override is on).

**Blocks:** `proof` (limit 4) — `value` (Text), `label` (Text).

**Presets:** *SaaS Spotlight*, *Editorial Split*.

## 3. Logo cloud

Social-proof logos in a grid or single row.

**Settings:** `eyebrow`, `title` (Text), `intro` (Textarea),
`layout` (Select: `grid` / `row`), `align` (EnumButtons → `SectionAlignment`),
`shape` + `density` (EnumButtons), `tone` (Select: `mono` / `color`), `scheme` (ColorScheme).

**Blocks:** `logo` — `name` (Text), `logo` (Image).

**Presets:** *Partner Grid*.

## 4. Features

A feature grid with configurable layout, column count, and per-card icon/proof.

**Settings:** `eyebrow`, `title` (Text), `intro` (Textarea),
`layout` (Select: `cards` / `bands` / `minimal`),
`columns` (Select: `2` / `3` / `4`), `align` (EnumButtons → `SectionAlignment`),
`shape` + `density` (EnumButtons), `scheme` (ColorScheme).

**Blocks:** `feature` — `icon` (Icon), `eyebrow` (Text), `title` (Text),
`description` (Textarea), `stat` (Text), `url` (Link).

**Presets:** *Product Grid*, *Editorial Bands*.

## 5. Image with text

One idea, a supporting image, and focused copy. No blocks.

**Settings:** `eyebrow`, `title` (Text), `body` (Textarea), `url` (Link), `label` (Text),
`image` (Image), `media_placement` (EnumButtons → `MediaPlacement`),
`align` (EnumButtons → `SectionAlignment`), `shape` + `density` (EnumButtons),
`scheme` (ColorScheme).

**Presets:** *Product Story*.

## 6. Stats

Concise metrics in a grid or band.

**Settings:** `eyebrow`, `title` (Text), `intro` (Textarea),
`layout` (Select: `grid` / `band`), `align` (EnumButtons → `SectionAlignment`),
`shape` + `density` (EnumButtons), `scheme` (ColorScheme).

**Blocks:** `stat` — `icon` (Icon), `value` (Text), `label` (Text),
`description` (Textarea).

**Presets:** *Metric Grid*.

## 7. Testimonials

Customer quotes as cards, a featured quote, or a compact list.

**Settings:** `eyebrow`, `title` (Text), `intro` (Textarea),
`layout` (Select: `cards` / `featured` / `compact`),
`align` (EnumButtons → `SectionAlignment`), `shape` + `density` (EnumButtons),
`scheme` (ColorScheme).

**Blocks:** `quote` — `quote` (Textarea), `name` (Text), `role` (Text), `avatar` (Image).

**Presets:** *Customer Proof*.

## 8. Pricing

Comparable pricing plans with a highlightable tier.

**Settings:** `eyebrow`, `title` (Text), `intro` (Textarea), `billing_note` (Text),
`align` (EnumButtons → `SectionAlignment`), `shape` + `density` (EnumButtons),
`scheme` (ColorScheme).

**Blocks:** `plan` — `name` (Text), `price` (Text), `period` (Text),
`description` (Textarea), `features` (Textarea, one per line), `highlighted` (Toggle),
`url` (Link), `label` (Text).

**Presets:** *Three Plan*.

## 9. FAQ

Accessible disclosure list — no JavaScript required.

**Settings:** `eyebrow`, `title` (Text), `intro` (Textarea),
`align` (EnumButtons → `SectionAlignment`), `shape` + `density` (EnumButtons),
`scheme` (ColorScheme).

**Blocks:** `item` — `question` (Text), `answer` (Textarea).

**Presets:** *Launch FAQ*.

## 10. Rich text

Long-form content with an article or split-with-aside layout. No blocks.

**Settings:** `eyebrow`, `title` (Text), `body` (RichText), `aside_title` (Text),
`aside_body` (RichText), `layout` (Select: `article` / `split`),
`width` (Select: `sm` / `md` / `lg`), `align` (EnumButtons → `SectionAlignment`),
`shape` + `density` (EnumButtons), `scheme` (ColorScheme),
`surface` (Toggle — wrap content in a surface).

**Presets:** *Founder Note*, *Editorial Essay*.

## 11. CTA

A conversion moment as a centered card, split callout, or inline banner. No blocks.

**Settings:** `badge` (Text), `heading` (Text), `subheading` (Textarea), `note` (Text),
`url` (Link), `label` (Text), `layout` (Select: `center` / `split` / `banner`),
`align` (EnumButtons → `SectionAlignment`), `shape` + `density` (EnumButtons),
`scheme` (ColorScheme).

**Presets:** *Launch Card*, *Sales Banner*.

## 12. Footer

A branded footer with a description, copyright, and grouped links.

**Settings:** `brand` (Text), `description` (Textarea), `copyright` (Textarea),
`density` (EnumButtons → `SectionDensity`), `shape` (EnumButtons → `SectionShape`),
`scheme` (ColorScheme).

**Blocks:** `link` — `column` (Text, optional grouping heading), `label` (Text),
`description` (Textarea), `url` (Link).

**Presets:** *Studio Footer*, *Minimal Footer*.

***

## Presets

A **preset** is a named starting point — a bundle of settings and blocks the editor can apply
in one click. Built-in sections ship the presets listed above; you can define your own on a
[custom section](/guide/custom-sections#presets) by returning `Preset` objects from a static
`presets()` method.

## Blocks

A **block** is a repeatable child item within a section (a nav link, a pricing plan, a quote).
Blocks have their own settings schema and an optional `limit`. See
[Custom Sections](/guide/custom-sections#blocks) for how to declare them.

---

---
url: /guide/custom-sections.md
---
# Custom Sections

Custom sections are first-class citizens. Drop a class anywhere on the autoloader, extend
`BladeSection`, and FilamentCraft renders it in the editor and on published pages — the same
pipeline the [built-in sections](/guide/built-in-sections) use.

## A minimal section

```php
namespace App\Sections;

use FilamentCraft\Sections\BladeSection;
use FilamentCraft\Settings\Types\Image;
use FilamentCraft\Settings\Types\Text;
use FilamentCraft\Settings\Types\Textarea;

final class TestimonialSection extends BladeSection
{
    protected static string $view = 'sections.testimonial';

    public static function slug(): string
    {
        return 'testimonial';
    }

    public static function name(): string
    {
        return 'Testimonial';
    }

    public static function settings(): array
    {
        return [
            Textarea::make('quote')->label('Quote')->required(),
            Text::make('author')->label('Author')->required(),
            Image::make('avatar')->label('Avatar'),
        ];
    }

    public static function defaults(): array
    {
        return [
            'settings' => [
                'quote' => 'A useful quote about the product.',
                'author' => 'Customer Name',
            ],
            'blocks' => [],
        ];
    }
}
```

The matching Blade view (`resources/views/sections/testimonial.blade.php`) receives a
`$section` data object:

```blade
<figure class="px-6 py-12 text-center">
    <blockquote class="text-2xl">{{ $section->settings->get('quote') }}</blockquote>
    <figcaption class="mt-4 text-sm text-gray-500">{{ $section->settings->get('author') }}</figcaption>
</figure>
```

::: tip Scaffold it
`php artisan make:filamentcraft-section Testimonial` generates the class and Blade view (or a
Livewire class with `--livewire`). See [Make Commands](/reference/commands).
:::

## The Section contract

`BladeSection` implements `FilamentCraft\Sections\Contracts\Section` via the `SectionSchema`
trait, which supplies sensible defaults for everything except the view. Override only what you
need:

| Method | Returns | Default | Purpose |
|---|---|---|---|
| `slug()` | `string` | kebab of class name minus `-section` | Stable id stored in revisions. |
| `name()` | `string` | headline of the slug | Display label in the catalog. |
| `category()` | `string` | `'general'` | Catalog grouping. |
| `description()` | `?string` | `null` | Sub-label in the catalog. |
| `icon()` | `string` | `heroicon-o-puzzle-piece` | Catalog icon. |
| `maxBlocks()` | `int` | `16` | Cap on total blocks across all block types. |
| `wrapper()` | `string` | `'section'` | The HTML tag/selector wrapping the rendered output. |
| `settings()` | `array` | `[]` | The settings schema (see below). |
| `blocks()` | `array` | `[]` | Repeatable child blocks. |
| `presets()` | `array` | `[]` | Named starting points. |
| `enabledOn()` | `array` | `['*']` | Template types the section is offered on. |
| `disabledOn()` | `array` | `[]` | Template types to exclude. |
| `previewImageUrl()` | `?string` | `null` | Catalog thumbnail. |
| `defaults()` | `array` | `['settings' => [], 'blocks' => []]` | Initial content when added. |

`slug()`, `name()`, `settings()`, and `defaults()` are the ones you'll usually define.

## Settings

`settings()` returns an array of [setting types](/guide/inputs/overview). It can mix the
FilamentCraft DSL with **raw Filament v4 components** — the compiler wires `live()` on every
leaf field so the preview keeps updating, and resolves visibility from either the DSL's
`visibleIf([...])` shortcut or Filament's native `visible(Closure)` callback.

```php
use Filament\Forms\Components\Toggle;
use Filament\Schemas\Components\Utilities\Get;
use FilamentCraft\Settings\Types\Group;
use FilamentCraft\Settings\Types\Text;

public static function settings(): array
{
    return [
        Group::make('content')->label('Content'),
        Text::make('heading')->label('Heading')->default('Welcome'),

        Group::make('cta')->label('Call to action')->collapsed(),
        Toggle::make('cta_enabled')->label('Show button')->default(true),
        Text::make('cta_label')->label('Button label')
            ->visibleIf(['cta_enabled' => true]),                       // DSL shortcut
        Text::make('cta_note')->label('Note')
            ->visible(fn (Get $get): bool => (bool) $get('cta_enabled')), // native closure
    ];
}
```

Use `Group` to break a long form into labelled clusters — see
[Layout & Structure](/guide/inputs/layout).

## Blocks

A **block** is a repeatable child item (a nav link, a pricing plan, a quote). Declare them with
`Block::make('slug')`, each with its own settings schema and an optional `limit`:

```php
use FilamentCraft\Sections\Block;
use FilamentCraft\Settings\Types\Text;
use FilamentCraft\Settings\Types\Link;

public static function blocks(): array
{
    return [
        Block::make('nav-link')
            ->name('Nav link')
            ->limit(6)
            ->settings([
                Text::make('label')->label('Label')->default('Page'),
                Link::make('url')->label('URL')->default('/'),
            ]),
    ];
}
```

Read blocks in the Blade view from `$section->blocks`. The `maxBlocks()` cap (default 16)
limits the *total* number of blocks added to one section instance, across every block type.

## Presets

A **preset** is a named bundle of settings and blocks the editor can apply in one click.
Return `Preset` objects from `presets()`:

```php
use FilamentCraft\Sections\Preset;

public static function presets(): array
{
    return [
        Preset::make('split-header', 'Split Header')
            ->settings([
                'brand_text' => 'Acme',
                'cta_enabled' => true,
            ])
            ->blocks([
                ['id' => 'nav-1', 'type' => 'nav-link', 'settings' => ['label' => 'Product', 'url' => '/product']],
                ['id' => 'nav-2', 'type' => 'nav-link', 'settings' => ['label' => 'Pricing', 'url' => '/pricing']],
            ]),
    ];
}
```

In the editor, presets surface behind the **Browse presets** button on the section's header —
each one is a one-click starting point.

## Registering a section

Two ways — both are calls on the plugin instance in your panel provider:

```php
use FilamentCraft\FilamentCraftPlugin;

public function panel(Panel $panel): Panel
{
    return $panel->plugin(
        FilamentCraftPlugin::make()
            ->registerSection(\App\Sections\TestimonialSection::class)
            // …or auto-discover a whole directory:
            ->discoverSectionsIn(app_path('Sections'))
    );
}
```

The conventional path `app/Sections/` is auto-scanned with no extra config.

## Extending a built-in section

The bundled sections are intentionally subclassable. Give the subclass its own slug,
optionally point it at a custom view, and override only what you want to change:

```php
namespace App\Sections;

use FilamentCraft\Sections\Builtin\HeroSection;

class ProductHeroSection extends HeroSection
{
    protected static string $view = 'sections.product-hero';

    public static function slug(): string
    {
        return 'product-hero';
    }

    public static function name(): string
    {
        return 'Product hero';
    }
}
```

Register the subclass with `->registerSection(ProductHeroSection::class)`. It inherits the
parent's settings, blocks, and presets unless you override those methods too.

## Related

* [Built-in Sections](/guide/built-in-sections) — the 12 shipped sections and their settings.
* [Setting Types](/guide/inputs/overview) — every input you can put in `settings()`.
* [Curating the Catalog](/guide/curating-the-catalog) — control which sections appear.
* [Testing Sections](/reference/testing) — the `SectionDataFactory` for Pest tests.

---

---
url: /guide/curating-the-catalog.md
---
# Curating the Catalog

The **catalog** is the *Add Section* picker inside the editor — the menu of section types a
content editor can insert into a page. By default it contains all 12
[built-in sections](/guide/built-in-sections) plus any
[custom sections](/guide/custom-sections) you've registered or discovered.

Curating the catalog lets you decide **which section types appear in that picker**, without
breaking pages that already use a type.

::: info Catalog ≠ rendering
These filters affect **only** the Add Section picker. A section type that's already placed in a
template keeps rendering on the published page even if you later hide it from the catalog —
existing content never breaks.
:::

## Show only a short list

`allowSections()` takes an allow-list of slugs. When set, the catalog shows *only* those types
— everything else is hidden, built-in or custom.

```php
use FilamentCraft\FilamentCraftPlugin;

FilamentCraftPlugin::make()
    ->allowSections(['hero', 'features', 'cta']);
```

Use this when editors should work from a deliberately small, on-brand set.

## Hide a few types

`withoutSections()` is the inverse: keep the full library *except* the slugs you name.

```php
FilamentCraftPlugin::make()
    ->withoutSections(['pricing', 'logo-cloud']);
```

The named types are removed from the picker but stay **registered**, so any template already
using them continues to render.

## Drop the built-ins entirely

To remove **all 12** built-in sections — for example when you ship your own complete library —
turn them off:

```php
FilamentCraftPlugin::make()
    ->withBuiltinSections(false)
    ->discoverSectionsIn(app_path('Sections'));
```

With `withBuiltinSections(false)`, the built-in classes are never registered, so the catalog
contains only your custom sections.

## Configure via `config/filamentcraft.php`

`allowSections()` and `withoutSections()` write to config, so you can set the same values in
`config/filamentcraft.php` instead of code:

```php
'builtin_sections_enabled' => true,   // toggled by withBuiltinSections()

'sections' => [
    'allowed'  => ['hero', 'features', 'cta'],  // null = allow all
    'disabled' => ['pricing'],
],
```

| Plugin method | Config key |
|---|---|
| `allowSections([...])` | `filamentcraft.sections.allowed` |
| `withoutSections([...])` | `filamentcraft.sections.disabled` |
| `withBuiltinSections(bool)` | `filamentcraft.builtin_sections_enabled` |

The plugin methods take precedence when both are set.

## How the rules combine

1. **Built-ins** register only when `builtin_sections_enabled` is true (default).
2. **Custom sections** register via `registerSection()` / `discoverSectionsIn()`.
3. The catalog then shows every registered type, **filtered** by `allowed` (if set) and minus
   `disabled`.

So `allowSections()` is a whitelist applied on top of whatever is registered, and
`withoutSections()` is a blacklist — they can be combined, but `allowSections()` is the
stronger constraint.

---

---
url: /guide/inputs/overview.md
---
# Setting Types

Every editable control in FilamentCraft — whether it lives in a **section's** settings panel
or a **theme's** template-settings panel — is declared with a small PHP DSL. Each control is
a `Setting` subclass under `FilamentCraft\Settings\Types`, instantiated with a `make('id')`
call and configured fluently:

```php
use FilamentCraft\Settings\Types\Text;

Text::make('heading')
    ->label('Heading')
    ->default('Welcome')
    ->required();
```

The editor compiles each `Setting` into a real Filament v4 form component at runtime, so the
inputs you get are the same battle-tested fields Filament renders everywhere else — wired up
for FilamentCraft's live-preview bus.

## The 18 built-in types

| Type | Class | Page |
|---|---|---|
| Text | `Text` | [Text inputs](/guide/inputs/text) |
| Textarea | `Textarea` | [Text inputs](/guide/inputs/text) |
| Number | `Number` | [Text inputs](/guide/inputs/text) |
| Range | `Range` | [Text inputs](/guide/inputs/text) |
| Select | `Select` | [Choice inputs](/guide/inputs/choice) |
| Radio | `Radio` | [Choice inputs](/guide/inputs/choice) |
| Checkbox | `Checkbox` | [Choice inputs](/guide/inputs/choice) |
| Enum buttons | `EnumButtons` | [Choice inputs](/guide/inputs/choice) |
| Color | `Color` | [Color inputs](/guide/inputs/color) |
| Color scheme | `ColorScheme` | [Color inputs](/guide/inputs/color) |
| Color scheme group | `ColorSchemeGroup` | [Color inputs](/guide/inputs/color) |
| Font | `Font` | [Font picker](/guide/inputs/font) |
| Image | `Image` | [Media & content](/guide/inputs/media) |
| Icon | `Icon` | [Media & content](/guide/inputs/media) |
| Link | `Link` | [Media & content](/guide/inputs/media) |
| Rich text | `RichText` | [Media & content](/guide/inputs/media) |
| Group | `Group` | [Layout & structure](/guide/inputs/layout) |
| Category | `Category` | [Layout & structure](/guide/inputs/layout) |

## Shared API (every type)

All setting types inherit the same base methods from `FilamentCraft\Settings\Setting`:

| Method | Purpose |
|---|---|
| `make(string $id)` | Construct the setting. The id must match `/^[a-z0-9_][a-z0-9_-]*$/i`. |
| `label(string $label)` | The field label shown in the editor. |
| `default(mixed $value)` | The value used until the user changes it. |
| `info(string $text)` | Helper text rendered under the field. |
| `required(bool $value = true)` | Mark the field required. |
| `visibleIf(array $predicates)` | Show the field only when other fields match — e.g. `->visibleIf(['cta_enabled' => true])`. |
| `cssVar(string $name, ?string $unit = null)` | Bind the value to a CSS custom property in `<style id="fc-tokens">`. The optional unit is appended to numeric values. |

`cssVar()` is what makes a setting *themeable*: the resolved value is written to `:root` as a
CSS variable so your section Blade and theme CSS can read it. See
[Theme Authoring](/guide/theme-authoring) for the full token pipeline.

```php
Range::make('button_radius')
    ->cssVar('--button-radius', 'px')
    ->min(0)->max(24)->default(8);
// emits:  --button-radius: 8px;
```

## Live-update behaviour

When a setting changes in the editor, FilamentCraft pushes the change to the preview iframe.
The `SchemaCompiler` chooses one of two Livewire live modes per type — you never configure
this, it is automatic:

* **Instant `live()`** — fires on every change. Used for discrete, one-click inputs:
  `Checkbox`, `Radio`, `EnumButtons`, `Select`, `ColorScheme`, `Font`, `Icon`.
* **Lazy `live(onBlur: true)`** — defers the round-trip until the field loses focus. Used for
  typed/dragged/uploaded inputs where a half-finished value shouldn't trigger a re-render:
  `Text`, `Textarea`, `Number`, `Range`, `Color`, `Image`, `Link`, `RichText`.

The lazy mode matters most for `RichText`: Filament v4's TipTap editor throws if the
surrounding DOM is morphed mid-keystroke, so the round-trip is deferred to blur.

## Where settings are used

* **In a section** — return them from the static `settings()` method. See
  [Custom Sections](/guide/custom-sections). Section settings can also mix in raw Filament v4
  components (e.g. `Toggle`, `ColorPicker`) alongside the DSL.
* **In a theme** — return them from `settingsSchema()`, usually wrapped in `Category` groups.
  See [Theme Authoring](/guide/theme-authoring).

---

---
url: /guide/inputs/text.md
---
# Text Inputs

Four types cover free-form text and numbers: `Text`, `Textarea`, `Number`, and `Range`. All
four use the lazy `live(onBlur: true)` update mode — the preview refreshes when the field
loses focus, not on every keystroke.

## Text

A single-line input, compiled to a Filament `TextInput`.

```php
use FilamentCraft\Settings\Types\Text;

Text::make('heading')
    ->label('Heading')
    ->placeholder('Welcome to Acme')
    ->maxLength(80)
    ->default('Welcome')
    ->required();
```

| Method | Effect |
|---|---|
| `placeholder(string $placeholder)` | Greyed-out hint shown when empty. |
| `maxLength(int $maxLength)` | Hard character cap (enforced by Filament's `maxLength`). |

Plus all [shared methods](/guide/inputs/overview#shared-api-every-type).

## Textarea

A multi-line input, compiled to a Filament `Textarea`.

```php
use FilamentCraft\Settings\Types\Textarea;

Textarea::make('subheading')
    ->label('Subheading')
    ->placeholder('A short supporting sentence')
    ->rows(4);
```

| Method | Effect |
|---|---|
| `placeholder(string $placeholder)` | Empty-state hint. |
| `rows(int $rows)` | Visible row count (default height). |

::: tip One value per line
Several built-in sections (e.g. the Pricing plan's `features`) store a `Textarea` value and
split it on newlines in the Blade view. It's a simple way to accept a list without a repeater.
:::

## Number

A numeric input, compiled to a `TextInput()->numeric()`. Stores a number; ideal for counts,
weights, or any integer setting.

```php
use FilamentCraft\Settings\Types\Number;

Number::make('columns')
    ->label('Columns')
    ->min(1)
    ->max(6)
    ->step(1)
    ->default(3);
```

| Method | Effect |
|---|---|
| `min(int $min)` | Minimum allowed value (`minValue`). |
| `max(int $max)` | Maximum allowed value (`maxValue`). |
| `step(int $step)` | Increment step. |

## Range

A numeric input designed for **CSS dimensions**. It is the type you reach for in themes: pair
it with `cssVar()` and a `unit()` and the resolved value lands in `<style id="fc-tokens">`
with the unit appended.

```php
use FilamentCraft\Settings\Types\Range;

Range::make('body_size')
    ->cssVar('--font-body-size', 'px')
    ->unit('px')
    ->min(12)
    ->max(20)
    ->step(1)
    ->default(16);
// emits:  --font-body-size: 16px;
```

| Method | Effect |
|---|---|
| `min(int\|float $min)` | Minimum value. |
| `max(int\|float $max)` | Maximum value. |
| `step(int\|float $step)` | Increment step (accepts floats, e.g. `0.05`). |
| `unit(string $unit)` | Unit suffix. Shown in the label *and* appended to the CSS value. |

`min`, `max`, and `step` accept floats, so `Range` works for `em`, `rem`, and unitless
line-heights as well as pixels.

---

---
url: /guide/inputs/choice.md
---
# Choice Inputs

Four types let the user pick from a fixed set of options: `Select`, `Radio`, `Checkbox`, and
`EnumButtons`. All four use the instant `live()` update mode — one click pushes the change to
the preview immediately.

## Select

A dropdown, compiled to a Filament `Select`. Pass an `id => label` map to `options()`.

```php
use FilamentCraft\Settings\Types\Select;

Select::make('layout')
    ->label('Layout')
    ->options([
        'spotlight' => 'Spotlight',
        'editorial' => 'Editorial',
        'compact'   => 'Compact',
    ])
    ->searchable()
    ->default('spotlight');
```

| Method | Effect |
|---|---|
| `options(array $options)` | `value => label` choices. |
| `searchable(bool $value = true)` | Enable the search box (good for long lists). |

## Radio

A radio-button group, compiled to a Filament `Radio`. Same `options()` shape as `Select`, but
all choices are visible at once — best for two or three options.

```php
use FilamentCraft\Settings\Types\Radio;

Radio::make('tone')
    ->label('Logo tone')
    ->options([
        'mono'  => 'Monochrome',
        'color' => 'Full color',
    ])
    ->default('mono');
```

| Method | Effect |
|---|---|
| `options(array $options)` | `value => label` choices. |

## Checkbox

A single boolean toggle, compiled to a Filament `Checkbox`. Its special power is `cssValues()`:
map the on/off state directly to two CSS strings, so a boolean becomes a usable CSS value.

```php
use FilamentCraft\Settings\Types\Checkbox;

Checkbox::make('button_uppercase')
    ->cssVar('--button-text-transform')
    ->cssValues('uppercase', 'none')   // true -> uppercase, false -> none
    ->default(false);
// emits:  --button-text-transform: none;   (until toggled on)
```

| Method | Effect |
|---|---|
| `cssValues(string $on, string $off)` | The CSS string emitted for the checked / unchecked state. |

Without `cssValues()`, a checkbox stores a plain boolean you read in your Blade.

## Enum buttons

A segmented button group, compiled to a Filament `ToggleButtons` rendered inline. Instead of
an `options()` array it takes a **string-backed enum class** — each case becomes a button with
its own label, color, and icon.

```php
use FilamentCraft\Enums\Sections\SectionShape;
use FilamentCraft\Settings\Types\EnumButtons;

EnumButtons::make('shape')
    ->label('Shape')
    ->enum(SectionShape::class)
    ->default(SectionShape::Contained->value);
```

| Method | Effect |
|---|---|
| `enum(string $enum)` | FQCN of a string-backed enum. **Required** — the field throws without it. |

::: warning Enum requirements
The enum must be `: string` backed and implement Filament's `HasLabel`, `HasColor`, and
`HasIcon` contracts so the buttons can render their label/color/icon. The built-in section
enums (`SectionShape`, `SectionDensity`, `SectionAlignment`, `MediaPlacement`) all satisfy
this — see [Built-in Sections](/guide/built-in-sections#shared-style-enums) for their cases.
:::

Because the value stored is the enum's backing string (e.g. `'contained'`), always set the
default with `->default(SectionShape::Contained->value)`, not the case instance.

---

---
url: /guide/inputs/color.md
---
# Color Inputs

Three types handle color, ranging from a single swatch to a full multi-token scheme system:
`Color`, `ColorScheme`, and `ColorSchemeGroup`.

## Color

A single color picker, compiled to a Filament `ColorPicker`. Stores a hex string. Uses the
lazy `live(onBlur: true)` update mode.

```php
use FilamentCraft\Settings\Types\Color;

Color::make('accent')
    ->label('Accent color')
    ->allowAlpha()
    ->cssVar('--accent')
    ->default('#f59e0b');
```

| Method | Effect |
|---|---|
| `allowAlpha(bool $value = true)` | Allow an alpha channel (RGBA), not just opaque hex. |

Reach for `Color` when you need one ad-hoc color. For a coordinated palette that sections can
reference semantically (`bg-primary`, `text-on-surface`), use a **color scheme** instead.

## ColorScheme

A scheme **picker**, compiled to FilamentCraft's `ColorSchemePicker`. It lets the editor choose
*which* color scheme a section (or block) renders with — the schemes themselves are defined by
`ColorSchemeGroup` (below) or shipped as built-ins. Uses the instant `live()` update mode.

```php
use FilamentCraft\Settings\Types\ColorScheme;

ColorScheme::make('scheme')
    ->label('Color scheme')
    ->inheritable();
```

| Method | Effect |
|---|---|
| `inheritable(bool $value = true)` | Allow an "inherit" option so the section falls back to the page/theme scheme. |

Every built-in section exposes a `ColorScheme::make('scheme')` control. In the Blade view the
selected scheme is applied with:

```blade
<div {!! $section->colorScheme()->attributes() !!} class="bg-background text-on-background">
  …
</div>
```

## ColorSchemeGroup

The full scheme **manager**, compiled to FilamentCraft's `ColorSchemeGroupField`. This is a
theme-level control: it renders a grid of scheme tiles plus an "Add scheme" affordance, and
drilling into a tile opens the 22-token editor.

```php
use FilamentCraft\Settings\Types\ColorSchemeGroup;

ColorSchemeGroup::make('color_scheme')->default('light');
```

`ColorSchemeGroup` takes no extra configuration beyond the [shared methods](/guide/inputs/overview#shared-api-every-type)
— its behaviour (token set, built-in schemes, OkLch shade generation) is fixed.

The 22 tokens per scheme are: Background, On Background, Surface, On Surface, Surface Alt,
On Surface-Alt, Primary, On Primary, Secondary, On Secondary, Accent, On Accent, Neutral,
On Neutral, Info, On Info, Success, On Success, Warning, On Warning, Danger, On Danger.

For the full scheme system — the 14 shipped schemes, auto-generated OkLch shades, per-site
persistence, and the Tailwind `@theme` mapping — see the dedicated
[Color Schemes](/guide/theming/color-schemes) page.

---

---
url: /guide/inputs/font.md
---
# Font Picker

`Font::make('default_font')` renders a searchable typography picker compiled to FilamentCraft's
`FontPickerField` — far more than a `<select>`. It is the control you use for every typography
setting in a theme. Uses the instant `live()` update mode.

```php
use FilamentCraft\Settings\Types\Font;

Font::make('default_font')
    ->cssVar('--font-default')
    ->default('inter');
```

| Method | Effect |
|---|---|
| `onlyCategory(array\|string $categories)` | Restrict the picker to one or more categories. |

## What the picker does

* **Live catalog from `https://fonts.bunny.net/list`** — fetched once and cached server-side
  for 24 hours, with system stacks added locally.
* **Popular tab pinned first** — Inter, Roboto, Open Sans, Lato, Poppins, Manrope, DM Sans,
  Merriweather, Playfair Display, JetBrains Mono, and more, ahead of the alphabetical roster.
* **Per-row preview in the option's own font** — lazy-loaded via IntersectionObserver as you
  scroll.
* **Eager-load** of the active font plus the top 25 popular fonts on mount, so opening the
  popover is instant.
* **Searchable** with debounced 150 ms input.
* **Category chips**: Popular · All · System · Sans · Serif · Display · Mono · Handwriting.
* **Keyboard navigation**: arrow up/down to highlight, Enter to commit, Escape to close.
* **Live preview**: pick a font → the setting persists → the iframe `<head>` re-syncs (Bunny
  `<link>` injected, `<style id="fc-tokens">` updated) within ~1.5 s.

## Restricting categories

```php
Font::make('heading_font')
    ->cssVar('--font-heading')
    ->onlyCategory(['display', 'serif'])   // hides sans / mono / handwriting
    ->default('playfair-display');
```

`onlyCategory()` accepts a single string or an array. Valid categories mirror the chips:
`system`, `sans`, `serif`, `display`, `mono`, `handwriting`.

## What gets stored and rendered

The picker stores the font **slug** (e.g. `'inter'`, `'merriweather'`, `'system-sans'`). At
render time `Font::resolveFamily($slug)` expands it to the full CSS font stack via the cached
`FontCatalog` — so the CSS variable receives something like
`"Inter", ui-sans-serif, sans-serif`.

Free-form values pass through unchanged, so a theme author can ship a literal stack and skip
the catalog entirely:

```php
Font::make('brand')->default('"Acme Sans", sans-serif');
```

System stacks (`system-sans`, `system-serif`, `system-mono`) resolve entirely to platform
fonts and emit **no** Bunny `<link>` tag. Any other family auto-injects:

```html
<link rel="stylesheet"
      href="https://fonts.bunny.net/css?family={slug}:400,500,600,700&display=swap">
```

## Catalog extension points

| Hook | Purpose |
|---|---|
| `\FilamentCraft\Support\FontCatalog` | The catalog service singleton — bind your own implementation to swap the data source (e.g. self-host the list). |
| `FontCatalog::flush()` | Clear the 24-hour cache to force a fresh fetch. |

---

---
url: /guide/inputs/media.md
---
# Media & Content Inputs

Four types handle media and rich content: `Image`, `Icon`, `Link`, and `RichText`. These store
structured values you read in your section Blade, rather than CSS tokens.

## Image

A file upload, compiled to a Filament `FileUpload()->image()` with the built-in image editor.
Uses the lazy `live(onBlur: true)` update mode.

```php
use FilamentCraft\Settings\Types\Image;

Image::make('bg_image')
    ->label('Background image')
    ->disk('public')
    ->directory('sections')
    ->visibility('public')
    ->accept(['image/png', 'image/jpeg', 'image/webp'])
    ->maxSize(4096)
    ->editor()
    ->aspectRatios([null, '16:9', '4:3', '1:1'])
    ->editorMode(2)
    ->editorEmptyFillColor('#000000');
```

| Method | Effect |
|---|---|
| `disk(string $disk)` | Storage disk. Defaults to the package upload config. |
| `directory(string $directory)` | Upload sub-directory. |
| `visibility(string $visibility)` | `public` or `private`. |
| `accept(array $accept)` | Allowed MIME types. |
| `maxSize(int $kilobytes)` | Max upload size in KB (falls back to `filamentcraft.uploads.max_size_kb`, default 5120). |
| `editor(bool $editor = true)` | Enable Filament's in-browser image editor. |
| `aspectRatios(array $ratios)` | Crop ratios offered in the editor (default `[null, '16:9', '4:3', '1:1']`). |
| `editorMode(int $mode)` | Filament image-editor mode (default `2`). |
| `editorEmptyFillColor(string $color)` | Fill color for transparent areas (default `#000000`). |

For how stored image values resolve to URLs and resized variants at render time, see
[Image Uploads & Variants](/reference/images).

## Icon

An icon picker, compiled to FilamentCraft's `IconPicker`. Uses the instant `live()` update
mode. Defaults to the Heroicons set.

```php
use FilamentCraft\Settings\Types\Icon;

Icon::make('icon')
    ->label('Icon')
    ->set('heroicons');
```

| Method | Effect |
|---|---|
| `set(string $set)` | Restrict to a specific icon set. `''` or `'heroicons'` uses the default; any other value scopes the picker to that registered set. |

See [Icons](/reference/icons) for registering additional sets.

## Link

A URL input, compiled to a `TextInput()->url()`. Uses the lazy `live(onBlur: true)` update
mode. It takes no extra configuration beyond the [shared methods](/guide/inputs/overview#shared-api-every-type).

```php
use FilamentCraft\Settings\Types\Link;

Link::make('cta_url')
    ->label('Button link')
    ->default('/start');
```

::: tip Template-aware links
For CTAs that should point at one of your **published** FilamentCraft pages, the Hero section
uses `TemplateUrlPicker` — a `Select` subclass that searches published templates and stores
their resolved public URL. It's a raw Filament component, droppable into any section schema.
:::

## Rich text

A WYSIWYG editor, compiled to Filament's `RichEditor` (TipTap/ProseMirror). The editor
stores Filament's rich-content document state; when you read the setting in a section,
FilamentCraft transforms it into a `RichTextValue` whose string form is rendered HTML.

```php
use FilamentCraft\Settings\Types\RichText;

RichText::make('body')
    ->label('Body')
    ->inline();
```

| Method | Effect |
|---|---|
| `inline(bool $value = true)` | Inline editing mode. |

`RichText` is forced into the lazy `live(onBlur: true)` mode for a reason: the TipTap bubble
menu throws if Livewire morphs the surrounding DOM mid-keystroke, so the preview round-trip is
deferred until you click away. You don't configure this — it's automatic.

---

---
url: /guide/inputs/layout.md
---
# Layout & Structure

Two types add **structure** to a settings panel rather than storing a value: `Group` and
`Category`. They organise the other inputs into readable, collapsible sections.

## Group

A sub-heading that visually groups the inputs that follow it, compiled to a Filament section
header. Used inside a single section's or theme category's settings list to break a long form
into labelled clusters.

```php
use FilamentCraft\Settings\Types\Group;

return [
    Group::make('content_group')->label('Content'),
    Text::make('heading')->label('Heading'),
    Textarea::make('subheading')->label('Subheading'),

    Group::make('cta_group')->label('Call to action')->collapsed(),
    Toggle::make('cta_enabled')->label('Show button'),
    Text::make('cta_label')->label('Button label'),
];
```

| Method | Effect |
|---|---|
| `content(string $content)` | Optional descriptive text under the group heading. |
| `collapsed(bool $collapsed = true)` | Start the group collapsed. |
| `icon(string $icon)` | An icon for the group heading. |

A `Group` doesn't nest its fields as children — it acts as a divider/header, and every field
listed after it (until the next `Group`) belongs to it visually. This is the pattern every
built-in section uses (`content_group`, `cta_group`, `layout_group`, `style_group`).

## Category

A top-level collapsible panel for the **theme** template-settings panel. Unlike `Group`,
`Category` *contains* its settings via `settings()`, and each category becomes a distinct
collapsible block in the editor's theme panel.

```php
use FilamentCraft\Settings\Types\Category;
use FilamentCraft\Settings\Types\Font;
use FilamentCraft\Settings\Types\Range;

Category::make('typography')
    ->label('Typography')
    ->icon('heroicon-o-language')
    ->collapsed(false)   // open by default; categories are collapsed otherwise
    ->settings([
        Font::make('default_font')->cssVar('--font-default')->default('inter'),
        Range::make('body_size')->cssVar('--font-body-size', 'px')
            ->unit('px')->min(12)->max(20)->default(16),
    ]);
```

| Method | Effect |
|---|---|
| `icon(string $icon)` | Icon shown next to the category title. |
| `collapsed(bool $collapsed = true)` | Start collapsed. **Categories are collapsed by default** — pass `->collapsed(false)` to open one. |
| `settings(array $settings)` | The settings contained in this category. |

`Category` is the backbone of a theme's `settingsSchema()` — see
[Theme Authoring](/guide/theme-authoring) for a complete multi-category theme class.

## Group vs. Category

| | `Group` | `Category` |
|---|---|---|
| Where | Inside a section, or inside a `Category` | Top level of a theme schema |
| Holds children? | No — acts as a divider/header | Yes — via `->settings([...])` |
| Default state | Open | Collapsed |
| Typical use | Cluster a section's fields | A whole theme panel (Colors, Typography, Buttons…) |

---

---
url: /guide/theme-authoring.md
---
# Theme Authoring

A FilamentCraft **theme** is one PHP class that declares the settings panel your end-users see
in the editor — Colors, Typography, Buttons, Inputs, Boxes, and anything else you want to
expose. The package ships one default theme (`StudioTheme`) with a 9-category panel. Custom
themes coexist alongside it or replace it entirely.

## On this page vs. its siblings

| Page | Covers |
|---|---|
| **Theme Authoring** (here) | Create a theme class, register it, and consume its CSS variables. |
| [Color Schemes](/guide/theming/color-schemes) | The `ColorSchemeGroup` system — 14 built-in schemes, OkLch shades, per-site persistence. |
| [Live Preview](/guide/theming/live-preview) | How edits patch the iframe, live-update modes, and where values are stored. |
| [Setting Types](/guide/inputs/overview) | Every input you can place in a theme schema. |

## 1. Create the theme class

Place it in `app/Themes/AcmeTheme.php` and extend `AbstractTheme`. A theme's `settingsSchema()`
returns top-level [`Category`](/guide/inputs/layout#category) groups, each holding
[setting types](/guide/inputs/overview):

```php
<?php

namespace App\Themes;

use FilamentCraft\Settings\Types\Category;
use FilamentCraft\Settings\Types\Checkbox;
use FilamentCraft\Settings\Types\ColorSchemeGroup;
use FilamentCraft\Settings\Types\Font;
use FilamentCraft\Settings\Types\Range;
use FilamentCraft\Theming\AbstractTheme;

final class AcmeTheme extends AbstractTheme
{
    public function slug(): string
    {
        return 'acme';
    }

    public function name(): string
    {
        return 'Acme';
    }

    public function settingsSchema(): array
    {
        return [
            Category::make('colors')
                ->label('Colors')
                ->icon('heroicon-o-swatch')
                ->collapsed(false) // open by default; categories are collapsed otherwise
                ->settings([
                    ColorSchemeGroup::make('color_scheme')->default('light'),
                ]),

            Category::make('typography')
                ->label('Typography')
                ->icon('heroicon-o-language')
                ->settings([
                    Font::make('default_font')->cssVar('--font-default')->default('inter'),
                    Font::make('heading_font')
                        ->cssVar('--font-heading')
                        ->onlyCategory(['display', 'serif'])
                        ->default('playfair-display'),
                    Range::make('body_size')
                        ->cssVar('--font-body-size', 'px')
                        ->unit('px')->min(12)->max(20)->default(16),
                ]),

            Category::make('buttons')
                ->label('Buttons')
                ->icon('heroicon-o-cursor-arrow-rays')
                ->settings([
                    Range::make('button_radius')
                        ->cssVar('--button-radius', 'px')
                        ->unit('px')->min(0)->max(24)->default(8),
                    Checkbox::make('button_uppercase')
                        ->cssVar('--button-text-transform')
                        ->cssValues('uppercase', 'none')
                        ->default(false),
                ]),
        ];
    }
}
```

`AbstractTheme` also gives you optional overrides: `description()`, `previewImage()`,
`stylesheets()`, and `scripts()`.

## 2. Register it

Two equivalent ways — pick whichever fits your setup.

**A. Via `config/filamentcraft.php`** (recommended — works for panel routes *and* public
preview/site routes):

```php
'themes' => [
    'paths' => [],
    'builtin_enabled' => true,    // ship StudioTheme alongside; set false to replace it
    'register' => [
        \App\Themes\AcmeTheme::class,
    ],
],
```

**B. Via the plugin's fluent API** (panel-only — for themes that should render *only* inside
Filament admin, not on public pages):

```php
use FilamentCraft\FilamentCraftPlugin;

public function panel(Panel $panel): Panel
{
    return $panel->plugin(
        FilamentCraftPlugin::make()
            ->registerTheme(\App\Themes\AcmeTheme::class)
            ->withoutBuiltinThemes() // optional — drop StudioTheme so only Acme appears
    );
}
```

Then create a `Theme` Eloquent row whose `slug` matches (`'acme'`) and assign your `Site` to it.

## 3. Consume the variables in your CSS

Every `cssVar()` declaration is emitted into `<style id="fc-tokens">` on `:root` of the
rendered iframe / public page:

```css
.btn {
  border-radius: var(--button-radius);
  text-transform: var(--button-text-transform);
  font-size: var(--font-body-size);
  font-family: var(--font-default);
}
```

If you use Tailwind v4, map them into utility classes via `@theme inline` so `bg-primary`,
`text-on-primary`, etc. work in your section blades:

```css
@theme inline {
  --font-default: var(--font-default);
  --font-heading: var(--font-heading);
  --color-primary: var(--color-primary);
  --color-primary-50: var(--color-primary-50);
  --color-primary-500: var(--color-primary-500);
  --color-primary-900: var(--color-primary-900);
}
```

`ColorSchemeGroup` automatically emits Tailwind-style 11-step OkLch shades
(`--color-primary-50…950`) for every non-`on-*` token of the active scheme — so
`bg-primary-600` and `hover:bg-primary-700` work natively. The full color system is on the
[Color Schemes](/guide/theming/color-schemes) page.

## 4. Reading values programmatically

To read or write theme settings outside the editor (migrations, seeds, API endpoints):

```php
use FilamentCraft\Support\SiteThemeSettings;

// Read merged values (overrides + schema defaults).
$values = SiteThemeSettings::values($site, $site->theme->templateSettings());

// Write a partial set (diffs against defaults; values matching default aren't stamped).
SiteThemeSettings::sync($site, $schema, ['button_radius' => 12]);
```

Where these land — and how authored color schemes persist separately — is covered in
[Live Preview → Persistence](/guide/theming/live-preview#persistence).

## Reference

* **Canonical theme**: `src/Theming/Themes/StudioTheme.php` — the 9-category default panel.
* **Theme contract**: `FilamentCraft\Theming\ThemeContract` (extend `AbstractTheme` for
  sensible defaults: `description`, `previewImage`, `stylesheets`, `scripts`).
* **Setting base**: `FilamentCraft\Settings\Setting` — `cssVar()`, `default()`, `label()`,
  `info()`, `required()`, `visibleIf()`.

---

---
url: /guide/theming/color-schemes.md
---
# Color Schemes

A **color scheme** is a coordinated set of 22 semantic color tokens (Background, Surface,
Primary, and their `on-*` foreground pairs, etc.). Sections reference these tokens semantically
— `bg-primary`, `text-on-surface` — so changing the scheme re-skins the whole page without
touching any section.

The system is driven by the [`ColorSchemeGroup`](/guide/inputs/color#colorschemegroup) theme
setting and the [`ColorScheme`](/guide/inputs/color#colorscheme) per-section picker.

## The token editor

`ColorSchemeGroup::make('color_scheme')` renders a grid of scheme tiles plus an "Add scheme"
affordance. Click a tile to drill into the 22-token editor.

The 22 tokens are paired foreground/background semantics:

| Background token | Foreground token |
|---|---|
| Background | On Background |
| Surface | On Surface |
| Surface Alt | On Surface-Alt |
| Primary | On Primary |
| Secondary | On Secondary |
| Accent | On Accent |
| Neutral | On Neutral |
| Info | On Info |
| Success | On Success |
| Warning | On Warning |
| Danger | On Danger |

## The 14 built-in schemes

These schemes are always available and can't be deleted:

`light`, `dark`, `default`, `modern`, `velocity`, `neutral`, `accent`, `inverse`,
`brand-primary`, `brand-secondary`, `cupcake`, `lofi`, `nord`, `silk`.

End-users can add their own on top of these — see [Persistence](#persistence).

## Auto-generated OkLch shades

For every non-`on-*` token of the active scheme, `ColorSchemeGroup` emits a Tailwind-style
11-step shade ramp computed in OkLch: `--color-primary-50` through `--color-primary-950`. That
means utilities like `bg-primary-600` and `hover:bg-primary-700` work natively with no extra
configuration — map them once in your `@theme inline` block (see
[Theme Authoring → step 3](/guide/theme-authoring#_3-consume-the-variables-in-your-css)).

## Applying a scheme in a section

Every built-in section exposes a `ColorScheme::make('scheme')` control. In the Blade view,
apply the selected scheme's data attributes and use the semantic utility classes:

```blade
<div {!! $section->colorScheme()->attributes() !!} class="bg-background text-on-background">
  <h2 class="text-on-surface">…</h2>
  <a class="bg-primary text-on-primary hover:bg-primary-700">Get started</a>
</div>
```

Switching the active scheme only flips a data attribute on the wrapper — the tokens for all
schemes are pre-rendered into `<style id="fc-tokens">`, so the change is instant with no server
round-trip (see [Live Preview](/guide/theming/live-preview)).

## Persistence

* The active **scheme slug** is stored on the **template draft**, so different templates can use
  different schemes.
* **User-authored schemes** (Add scheme + custom tokens) are persisted on
  `Site.settings_json['schemes']`, separate from the 14 package built-ins — so each site keeps
  its own additions without mutating the shared `Theme`.

Programmatic helpers:

```php
use FilamentCraft\Support\SiteColorSchemes;

$schemes = SiteColorSchemes::forSite($site);          // 14 built-ins + this site's overrides
$newSlug = SiteColorSchemes::add($site, cloneFrom: 'cupcake');  // returns "scheme-N"
SiteColorSchemes::remove($site, 'scheme-13');
```

## Related

* [Color Inputs](/guide/inputs/color) — the `Color`, `ColorScheme`, and `ColorSchemeGroup`
  setting types.
* [Theme Authoring](/guide/theme-authoring) — declaring a `ColorSchemeGroup` in a theme.
* [Live Preview](/guide/theming/live-preview) — how scheme changes patch the iframe.

---

---
url: /guide/theming/live-preview.md
---
# Live Preview

Editing any setting in the editor patches the preview iframe in place. This page explains the
two live-update modes, what the iframe does per change, and where values are stored.

## Live-update modes

The `SchemaCompiler` routes every field through one of two Livewire live modes. You don't
configure this — it's chosen automatically per setting type.

* **Instant `live()`** — the round-trip fires on every change. Used for discrete, one-click
  inputs:
  `Checkbox`, `Radio`, `EnumButtons`, `Select`, `ColorScheme`, `Font`, `Icon`.
* **Lazy `live(onBlur: true)`** — the round-trip is deferred until the field loses focus. Used
  for typed, dragged, or uploaded inputs where a half-finished value shouldn't trigger a
  re-render mid-edit:
  `Text`, `Textarea`, `Number`, `Range`, `Color`, `Image`, `Link`, `RichText`.

The lazy mode is load-bearing for `RichText`: Filament v4's TipTap editor throws if Livewire
morphs the surrounding DOM mid-keystroke, so its round-trip is always deferred to blur.

## What the iframe does per change

| Change | What the iframe does |
|---|---|
| **Active color scheme slug only** | Flips `data-fc-color-scheme` on `<html>` instantly — no server round-trip, because every scheme's tokens are pre-rendered into `<style id="fc-tokens">`. |
| **Authored color tokens, font slug, range / checkbox / etc.** | Requests a server `templateRefresh` (single GET, ~150 ms), then morphs `<body>` **and** re-syncs `<head>`: the `<style id="fc-tokens">` text is replaced, stale Bunny `<link>` tags are pruned, and fresh ones added. No flash, no FOUC for cached fonts. |
| **Section settings** (e.g. a Hero heading) | Either patched in place via the LivePatcher (any element with `data-fc-live="…"` gets a surgical update) or via a section-level refresh, depending on the field shape. |

## Fonts in the live loop

The renderer auto-injects a Bunny Fonts stylesheet for every `Font` setting whose value
resolves to a remote family:

```html
<link rel="stylesheet"
      href="https://fonts.bunny.net/css?family={slug}:400,500,600,700&display=swap">
```

System stacks (`system-sans`, `system-serif`, `system-mono`) emit no `<link>` because they
resolve entirely to platform fonts. See [Font Picker](/guide/inputs/font) for details.

## Persistence

Where values live once you save:

* **Active color scheme slug** — on the **template draft**, so different templates can use
  different schemes.
* **User-authored color schemes** (Add scheme + 22 tokens) — on `Site.settings_json['schemes']`,
  kept separate from the 14 package-shipped built-ins.
* **Every other theme setting value** — on `Site.settings_json`, keyed by setting id. Writes
  are **diff-only**: a value matching its schema default isn't stamped, so unset values inherit
  the schema's default and package upgrades to those defaults flow through automatically.

Programmatic read/write (migrations, seeds, API endpoints):

```php
use FilamentCraft\Support\SiteThemeSettings;
use FilamentCraft\Support\SiteColorSchemes;

// Read merged values (overrides + schema defaults).
$values = SiteThemeSettings::values($site, $site->theme->templateSettings());

// Write a partial set (diffs against defaults).
SiteThemeSettings::sync($site, $schema, ['button_radius' => 12]);

// Color-scheme overrides (per-site authored map).
$schemes = SiteColorSchemes::forSite($site);          // 14 built-ins + overrides
SiteColorSchemes::add($site, cloneFrom: 'cupcake');   // returns "scheme-N"
SiteColorSchemes::remove($site, 'scheme-13');
```

## Related

* [The Editor](/guide/editor) — the editing UI as a whole.
* [Setting Types](/guide/inputs/overview) — the per-type live-mode summary.
* [Color Schemes](/guide/theming/color-schemes) — the scheme system the first row above relies on.

---

---
url: /guide/editor.md
---
# The Editor

The editor is a three-column workspace: a left rail with the section catalog and the page's
sections, a center iframe preview, and a right settings panel.

## Topbar

* **Page / Site dropdowns** — switch templates of the current site, or jump to a sibling
  site (multi-locale setups).
* **URL pill** — shows the live URL of the current page; click-through opens it in a new
  tab. The home icon on the left toggles "set as homepage."
* **Device switcher** — desktop / tablet / mobile widths. Mobile and tablet render the
  preview inside a device frame:

- **Focus mode** — collapses both rails to maximize the canvas.
- **Save / Publish / Discard** — Save writes a draft revision; Publish promotes it to public;
  Discard rolls back to the published state.
- **Undo / Redo** — 50-step ring buffer per template, persisted across reloads so a refresh
  doesn't lose your last 10 minutes.

## Live preview behaviour

* **Section-level refresh** from the server's draft state — no full reload.
* **Debounced settings** so typing doesn't fire a round-trip per keystroke.
* **Autosave-to-draft** every keystroke.
* **Undo / redo** with a 50-step ring buffer.

See [Theme Authoring §9](/guide/theme-authoring#_9-live-preview-architecture) for how
setting changes patch the iframe.

## Next steps

* [Editor Internals](/guide/editor-internals) — the post-message bus, auto-scroll dedupe,
  the morph-safe sidebar resize, and where the editor's `.ts` code lives.

---

---
url: /guide/editor-internals.md
---
# Editor Internals

You don't need any of this to *use* the editor — only to debug it if something looks off,
or to extend it. For the day-to-day tour of the workspace, see [The Editor](/guide/editor).

## Auto-scroll preview on section selection

When you click a section in the sidebar (or open the editor with `?section=<id>` in the URL),
the preview iframe smooth-scrolls to that section. Trigger paths:

1. **Sidebar click** — `SectionList` Livewire component dispatches `section-selected` (with
   the section id). Editor parent listens via `Livewire.on('section-selected', …)`.
2. **Settings panel open** — same dispatch from `SettingsPanel`.
3. **Initial URL load** — `?section=<id>` in the URL is read once when the iframe's
   postMessage bus reports ready.
4. **Iframe click** — clicking a section inside the iframe round-trips through the bus and
   fires the same `section-selected` Livewire event.

All four paths funnel into the same parent-side handler. Two guards keep it efficient.

### Parent-side dedupe

```ts
let lastScrolledSectionId: string | null = null;

window.Livewire.on('section-selected', (payload) => {
    if (data.id === lastScrolledSectionId) return;
    lastScrolledSectionId = data.id;
    // ... fan-out per iframe
});
```

Without this, sidebar-click + settings-open + initial-URL-load all fire `section-selected`
in rapid succession for the same id, and the parent would fan out three identical
`postMessage`s per canvas iframe.

### Iframe-side visibility guard

The iframe's `SectionScrollTo` handler reads `getBoundingClientRect()` and skips the scroll
when the target is already in the upper half of the viewport:

```ts
const rect = el.getBoundingClientRect();
const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
const inUpperHalf = rect.top >= 0 && rect.top <= viewportHeight * 0.5;
if (inUpperHalf) return;
```

Without this, clicking a section *inside* the iframe (case 4 above) would snap the iframe
back to the same spot the user just clicked — visually jarring.

### Cross-version Livewire hook

In Livewire 3, `livewire:morph.updated` was a DOM event you could subscribe to with
`document.addEventListener`. Livewire 4 removed the DOM dispatch; the same name is now an
internal `trigger()` hook only.

The editor subscribes through **both** APIs so the post-morph boot reliably runs on both
versions:

```ts
// Legacy v3 DOM event — silently dead on v4, harmless to subscribe.
document.addEventListener('livewire:morph.updated', bootAll);

// Universal hook — exists in both v3 and v4.
document.addEventListener('livewire:init', () => {
    window.Livewire?.hook?.('morph.updated', bootAll);
});
```

`Livewire.hook` is the API that matters going forward.

## Sidebar resize

The editor's three-column layout (nav rail · settings rail · preview canvas) is managed by
`split-grid` via `resources/js/layout-resize.ts`. The user drags the vertical handle between
the settings rail and the preview to resize.

### The morph problem

`split-grid` binds a `mousedown` listener to the gutter element (`[data-fc-layout-gutter]`).
When Livewire or Filament navigation morphs the editor page tree, the body element keeps its
identity but **the gutter child can be replaced** — leaving the listener bound to a detached
element. The handle goes silently dead.

### The fix

`layout-resize.ts` tracks two WeakMaps:

```ts
const instances = new WeakMap<HTMLElement, SplitInstance>();   // body → split-grid
const gutterByBody = new WeakMap<HTMLElement, HTMLElement>();  // body → live gutter
```

`bindBody()` checks the parallel map and rebinds if the live gutter differs from the bound
one:

```ts
if (instances.has(body)) {
    const previousGutter = gutterByBody.get(body);
    if (previousGutter && previousGutter === gutter && previousGutter.isConnected) {
        return;  // still good, skip
    }
    destroyBody(body, false);  // tear down the stale instance
}
// ... bind a fresh split-grid to the live gutter
```

The end-to-end effect: any code path that re-runs `bindLayoutResize()` (`livewire:init`,
`livewire:navigated`, `livewire:update`, the `morph.updated` hook) heals a resize handle
that was broken by a morph.

### Why not bind on the gutter directly?

`split-grid`'s API takes the gutter as the configured target but reads
`this.element.parentNode` (the body) at drag-start. The grid layout lives on the parent. So
the WeakMap key has to be the body (because it's the grid container), and we just track the
gutter identity alongside.

## Where the code lives

| File | What it does |
|---|---|
| `resources/js/editor.ts` | Parent-side bus setup, Livewire listeners, scroll dispatch, layout boot orchestration |
| `resources/js/iframe-injected.ts` | Iframe-side bus handlers including `SectionScrollTo` with the visibility guard |
| `resources/js/layout-resize.ts` | split-grid + the gutter-rebind logic |
| `resources/js/postmessage-bus.ts` | The transport between editor and iframes; framework-agnostic |
| `src/Editor/Protocol/MessageType.php` | Enum of every message type sent over the bus |

If you change any `.ts` file, run `npm run build` to refresh `resources/dist/` — the CI gate
enforces parity between source and dist.

---

---
url: /guide/tenancy.md
---
# Tenancy

FilamentCraft never `require`s a tenancy package (`stancl/tenancy`,
`spatie/laravel-multitenancy`, etc.) — it resolves the current `Site` at runtime from
whatever signals your host app provides. It works with any of those packages,
Filament-only setups, or single-site apps without modification.

The current `Site` is resolved by `<x-filamentcraft::layout>` in this order — **first match
wins**:

## Tenancy modes

| Mode | What it does |
|---|---|
| `auto` (default) | `single_site_id` if set, then `Filament::getTenant()`, then a container-bound `owner_model`, then the first live Site. |
| `none` | Single-site mode — resolves `single_site_id` when set, otherwise the first live Site. |
| `filament` | `single_site_id` if set, then the active Filament tenant, then the first live Site. |
| `owner` | `single_site_id` if set, then a container-bound `owner_model`, then the first live Site. |

## Single-app / non-tenant setup

```php
use FilamentCraft\FilamentCraftPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            FilamentCraftPlugin::make()
                ->singleSite()
        );
}
```

If you already know the site id and want to pin resolution to it:

```php
FilamentCraftPlugin::make()
    ->singleSite(1);
```

## Multi-tenant setup

```php
use App\Models\Workspace;
use FilamentCraft\FilamentCraftPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            FilamentCraftPlugin::make()
                ->tenantSites(Workspace::class)
        );
}
```

`tenantSites()` configures the Filament panel tenant, FilamentCraft tenant resolution, and
live-page URL generation together. Its default public URL strategy assumes your tenant route
is named `filamentcraft.tenant.public`, uses a `{tenantSlug}` parameter, and reads the tenant
slug from a `slug` column (see [Public Routing](/guide/public-routing)).

***

## The two resolvers

FilamentCraft ships two cooperating singletons, both registered in
`FilamentCraftServiceProvider::packageBooted()`:

| Resolver | Purpose | Used by |
|---|---|---|
| **`TenancyResolver`** | Generic "find a Site for the current request". Tries `single_site_id` → Filament panel tenant → container-bound owner model → first live Site, with mode-specific skips. | Filament resources, the editor page, the Layout component's middle resolution step |
| **`TenantSiteResolver`** | Given an explicit `(ownerModel, slug)` pair, loads the owner, sets it as the Filament tenant when possible, and returns the matching live Site. | The `filamentcraft.tenant` middleware, the Layout component's URL fallback step |

You'll usually never call them directly — they're the substrate under the middleware and the
`<x-filamentcraft::layout>` component.

## Resolution order inside `<x-filamentcraft::layout>`

When you use any of the four [dynamic-page doors](/guide/dynamic-pages), the Layout component
resolves `$site` in this order (first match wins):

1. **Explicit `:site` prop** — you passed one. End of chain.
2. **Container binding** — `app()->bound(Site::class)` returns true (set by middleware:
   `filamentcraft.tenant`, `filamentcraft.site`, or any of your own).
3. **`TenancyResolver::resolve()`** — runs the mode-aware generic chain (below). Works
   inside the admin panel because `Filament::getTenant()` populates it.
4. **`TenantSiteResolver` URL-parameter fallback** — when the current request has a
   `{tenantSlug}` route param **and** `filamentcraft.tenancy.owner_model` is configured,
   looks up the tenant and its live Site without any middleware on the route.

If all four fail, a `RuntimeException` is thrown with a message that names the options to
fix it.

## What `TenancyResolver::resolve()` checks

In order:

1. **`config('filamentcraft.tenancy.single_site_id')`** — single-site mode for hosts that
   don't want any multi-tenancy. Returns the named Site directly.
2. **`Filament::getTenant()`** — works inside a Filament panel context. Loads the Site for
   the current panel tenant.
3. **Configured owner model** — `config('filamentcraft.tenancy.owner_model')` set + an
   instance of that model already bound in the container → resolves via the owner's
   `primarySite()` method. This path is for host apps that bind their current workspace,
   academy, team, etc. in middleware.
4. **First live Site** — last-resort fallback. Returns the earliest live Site by id.
   Useful for staging / single-site setups where you don't care about strict isolation.

## What `TenantSiteResolver::resolve()` does

```php
$site = app(TenantSiteResolver::class)
    ->resolve('App\\Models\\Academy', 'acme', 'slug');
```

1. **Validates** the owner model class exists and is an `Eloquent\Model` subclass. Throws
   `InvalidArgumentException` otherwise.
2. **Loads the owner** via `Academy::query()->where('slug', 'acme')->first()`. Returns
   `null` if no match (caller decides whether to 404).
3. **Calls `Filament::setTenant($owner)`** inside a try/catch. Panel contexts use this for
   scoped queries; non-panel contexts (public routes, tests) swallow the throw — the Site
   binding is what the shell actually needs.
4. **Loads the Site** via `Site::query()->forOwner($owner)->live()->first()`. `forOwner()`
   is the polymorphic-morph scope on the `Site` model — always use it instead of raw
   `where('owner_type', …)->where('owner_id', …)`.

The middleware and the Layout component's URL fallback both route through this method — they
don't reimplement the chain. If you find yourself writing owner-by-slug logic in your own
code, call `TenantSiteResolver` instead.

## Configuration

```php
return [
    'tenancy' => [
        // One of: auto, none, filament, owner.
        'mode' => 'auto',

        // Forces every request to use this Site id. Skips the chain entirely.
        'single_site_id' => null,

        // The Eloquent class that owns Sites (Academy, Team, Workspace, etc.).
        // For TenancyResolver owner mode, this model should implement SiteOwner
        // (using FilamentCraft\Concerns\HasSite is the usual path).
        'owner_model' => null,

        // Optional: add this if your tenant slug column is not 'slug'.
        'slug_column' => 'slug',

        // Optional: add this if your route param is not '{tenantSlug}'.
        'url_parameter' => 'tenantSlug',
    ],
];
```

The published config ships with `mode`, `owner_model`, and `single_site_id`. The
`slug_column` and `url_parameter` keys are optional overrides read by the tenant middleware
and Layout URL fallback; add them only when your routes differ from the defaults.

## The middleware: `filamentcraft.tenant`

Registered automatically. Use it to bind a Site eagerly before your handlers run:

```php
// routes/web.php
Route::middleware(['web', 'filamentcraft.tenant'])
    ->prefix('{tenantSlug}')
    ->group(function (): void {
        Route::get('cart', CartPage::class);
    });
```

With three optional middleware arguments to override config:

```php
'filamentcraft.tenant:academySlug,App\\Models\\Academy,public_slug'
```

The `Route::filamentCraftStorefront()` macro wraps this for you — see
[Dynamic Pages → Door 2](/guide/dynamic-pages#door-2-routefilamentcraftstorefront-macro).

::: warning /admin coexistence
`Route::filamentCraftTenant()` and `Route::filamentCraftStorefront()` both default their
`tenantPattern` to `^(?!admin\b)[A-Za-z0-9-]+` so a Filament admin panel at
`/admin/{tenant}` stays reachable. If your panel uses a non-default `->path('something-else')`,
pass a `tenantPattern` argument that excludes that prefix too — otherwise the FC tenant route
will capture `/something-else/whatever` as a tenant slug.
:::

## Common scenarios

### Single-site mode

```php
FilamentCraftPlugin::make()
    ->singleSite(1);
```

`TenancyResolver` short-circuits to that Site for every request. The URL fallback is never
invoked because step 3 succeeds first.

### Multi-tenant, Filament panel only

Use `tenantSites(Workspace::class)` or set `owner_model` and `tenancy('filament')`. Inside
the admin panel, `Filament::getTenant()` resolves the tenant from the panel's tenancy config;
`TenancyResolver` finds the matching Site. The Layout component (if used inside a custom
admin page) gets it from step 3 — no public-route middleware needed.

### Multi-tenant, public storefront

Set `owner_model` + `url_parameter` (if your routes use a non-default param name). Add the
`filamentcraft.tenant` middleware (or the `Route::filamentCraftStorefront()` macro) to your
storefront routes. The middleware binds the Site to the container; the Layout component picks
it up from step 2.

If you forget the middleware but your URL has a `{tenantSlug}` param matching
`url_parameter`, the Layout component's URL fallback (step 4) saves you. This is what makes
Door 1 (`#[Storefront]`) work without per-route middleware.

### Custom resolution logic

Override the binding in your own middleware before any FilamentCraft middleware runs:

```php
app()->instance(\FilamentCraft\Models\Site::class, $yourCustomSiteLookup);
```

The Layout component finds it at step 2 and skips the rest of the chain.

If you prefer `tenancy('owner')`, bind the current owner instance instead:

```php
app()->instance(\App\Models\Workspace::class, $workspace);
```

Then set `filamentcraft.tenancy.owner_model` to the same class. The owner model should
implement `FilamentCraft\Contracts\SiteOwner`, usually by using
`FilamentCraft\Concerns\HasSite`.

---

---
url: /guide/public-routing.md
---
# Public Routing

Off by default — most hosts already own their front-end and only want the editor. Flip on
when you want FilamentCraft to serve published templates directly.

## Enable the catch-all

```php
// config/filamentcraft.php
'public_routes' => true,
```

This registers a catch-all `GET /{path?}` that resolves the host (via `Site::domain` /
`subdomain`) and renders the matching template's published revision. The homepage assignment
in the editor topbar drives `/`. Slugs like `/pricing` resolve to the published template with
that slug.

## Tenant URL scheme

If you want a tenant URL scheme — `/{tenant}/{slug}` — keep `public_routes => false` and add
one route:

```php
use App\Models\Workspace;
use Illuminate\Support\Facades\Route;

Route::filamentCraftTenant(Workspace::class);
```

That registers `GET /{tenantSlug}/{path?}`, resolves the `Workspace` by `slug`, binds the
workspace's live FilamentCraft site, and renders the published page. The default route name
is `filamentcraft.tenant.public`.

Use named arguments only when your app differs from the defaults:

```php
Route::filamentCraftTenant(
    ownerModel: Workspace::class,
    tenantParameter: 'workspace',
    tenantSlugColumn: 'domain_slug',
    name: 'tenant.public',
);
```

For completely custom URL schemes — `/shop/{tenant}/{slug}`, locale prefixes, channel paths,
etc. — register your own route, bind the resolved `Site` into the container, then call
`[PublicSiteController::class, 'show']` with the remaining page path. For tenant-slug routes,
prefer `Route::filamentCraftTenant()` unless your URL shape is truly custom.

## Custom URL strategy — `publicUrlsViaNamedRoute()`

Hosts that own their routing (multi-tenant slugs, locale prefixes, channel paths) tell
FilamentCraft how to build the public URL of a `Template`. This drives the editor topbar's
"open live" pill, the URL bar, and the **View live** action on the Templates list — every
place that asks "where does this page live?".

For the 90% case — a named Laravel route with a path parameter and an optional tenant
parameter — use the declarative helper:

```php
use FilamentCraft\FilamentCraftPlugin;

// Single-tenant: route('page.show', ['path' => $template->slug])
$plugin = FilamentCraftPlugin::make()
    ->publicUrlsViaNamedRoute('page.show');

// Multi-tenant with Route::filamentCraftTenant(...):
$plugin = FilamentCraftPlugin::make()
    ->publicUrlsViaNamedRoute(
        'filamentcraft.tenant.public',
        tenantParameter: 'tenantSlug',
    );

// Locale-prefixed extras
$plugin = FilamentCraftPlugin::make()
    ->publicUrlsViaNamedRoute(
        'tenant.public',
        tenantParameter: 'tenantSlug',
        extraParameters: [
            'locale' => fn (\FilamentCraft\Models\Template $t) => $t->site?->locale,
        ],
    );
```

Pass the configured `$plugin` to `$panel->plugin($plugin)` in your panel provider; do not
create a separate throwaway plugin instance.

Parameters: `pathParameter` (defaults to `'path'`), `tenantParameter` (the route placeholder
for the owner slug — `null` for single-tenant), `tenantSlugColumn` (the attribute on
`Site::owner` holding the slug, defaults to `'slug'`), `homepagePath` (the literal value for
the homepage — `''` by default; set to `'home'` etc. if your route demands it), and
`extraParameters` (scalar literals or closures resolved against the template at call time).

The result is **memoised per-request** on the `Template` instance, so the editor topbar, the
templates list, the sitemap, and `<og:url>` tags all hit the resolver once — not once per
call. The cache is cleared automatically on `save()` / `refresh()` so a status flip or slug
rename invalidates it.

### Or a raw closure — `publicUrlUsing()`

For exotic schemes (channel paths, custom domains per template, on-the-fly redirects), drop
down to the closure form:

```php
use FilamentCraft\Models\Template;

$plugin = FilamentCraftPlugin::make()
    ->publicUrlUsing(function (Template $template): ?string {
        $owner = $template->site?->owner;

        if (! $owner instanceof \App\Models\Team) {
            return null; // fall through to default resolver
        }

        return route('tenant.public', [
            'tenantSlug' => $owner->slug,
            'path' => $template->isHomepage() ? '' : $template->slug,
        ]);
    });
```

Return `null` from either form to fall through to the default behaviour (catch-all route
when `public_routes` is on, otherwise the auth'd preview URL). Partial overrides — "only when
the site has an owner", "only when the locale is set" — degrade gracefully.

## Linking to FilamentCraft pages — `TemplateUrlPicker`

Need to let an admin pick a published page from a CTA button, a banner link, a footer menu
item, or any other "open this page" field? Drop the picker into any Filament schema:

```php
use FilamentCraft\Filament\Forms\Components\TemplateUrlPicker;

TemplateUrlPicker::make('cta_url')
    ->label('Destination page')
    ->required();
```

**Where do the options come from?** The picker queries `Template::query()->published()` —
every template whose `status === Published` and whose `publicUrl()` resolves to a non-empty
string. The URL itself is whatever your `publicUrlsViaNamedRoute()` / `publicUrlUsing()`
resolver returns (or the default catch-all / preview URL when no resolver is wired). Drafts
are excluded — they have no public URL by design.

Defaults: options preload on open (no typing required), searchable filter by template name,
scoped to the active Filament tenant, stores the resolved URL string so existing `<a href>`
rendering keeps working without extra resolution code.

Configurable:

```php
TemplateUrlPicker::make('cta_url')
    ->forSite($site->id)   // pin to a specific site, ignoring the active tenant
    ->forAllSites()        // list templates across every site (admin tools)
    ->searchLimit(20);     // cap the dropdown size (defaults to 50)
```

---

---
url: /guide/dynamic-pages.md
---
# Dynamic Pages

FilamentCraft templates handle marketing pages. Every real storefront also has pages that
are too dynamic to live in a visual builder — **cart, checkout, account, lesson player,
search results, blog comments, gated downloads** — driven by user state or per-request data.

These pages aren't FilamentCraft templates, but they still need to look like part of the
academy / tenant's site. FilamentCraft ships **four doors** — all backed by the same shell
renderer — so you reach for the Laravel idiom you already use.

| Adopter style | The door | One-liner |
|---|---|---|
| **Livewire-first** | [`#[Storefront]` attribute](#door-1-storefront-livewire-attribute-recommended) | `#[Storefront]` on the component class |
| **Route-driven** | [`Route::filamentCraftStorefront()` macro](#door-2-routefilamentcraftstorefront-macro) | `Route::filamentCraftStorefront(Academy::class, fn () => …)` |
| **File-based** | [Laravel Folio integration](#door-3-laravel-folio-file-based-routing-zero-php) | drop a `.blade.php` in `resources/views/storefront/` |
| **Explicit / one-off** | [`<x-filamentcraft::layout>` Blade component](#door-4-x-filamentcraft-layout-blade-component) | `<x-filamentcraft::layout>…</x-filamentcraft::layout>` |

All four render the same theme tokens + header region + footer region + fonts + stylesheets +
correct `lang`/`dir`/`data-fc-color-scheme` on `<html>`. Pick one and never think about the
others.

***

## Door 1 — `#[Storefront]` Livewire attribute (recommended)

For any Livewire full-page component, one attribute is the whole integration. The Site is
auto-resolved from the container, `TenancyResolver`, or the URL's tenant slug — no middleware
on the route required when your route parameter matches the configured fallback.

```php
use FilamentCraft\Attributes\Storefront;
use Illuminate\Contracts\View\View;
use Livewire\Component;

#[Storefront]
final class CartPage extends Component
{
    public function render(): View
    {
        return view('livewire.cart');
    }
}
```

```php
// routes/web.php — note: no middleware, no group, no layout wrapper.
Route::get('/{tenantSlug}/cart', CartPage::class);
```

That's it. `<x-filamentcraft::layout>` does all the work under the hood; `#[Storefront]` is a
self-documenting alias for the standard `#[Layout('filamentcraft::layout')]`. Anything you
can do with Livewire's own `#[Layout]` — pass data, target different layouts per method —
works identically with `#[Storefront]`.

> If you prefer staying with the Livewire-native attribute, write
> `#[Layout('filamentcraft::layout')]` instead. Same behaviour, two more tokens of code.

### Page titles

Use Livewire's own `#[Title]` attribute alongside `#[Storefront]`:

```php
use Livewire\Attributes\Title;

#[Storefront]
#[Title('Your cart')]
final class CartPage extends Component { /* ... */ }
```

### Passing data to the layout

```php
#[Storefront(['canonical' => 'https://example.com/cart'])]
final class CartPage extends Component { /* ... */ }
```

The array is forwarded to the layout view's `$slot` scope. Useful for SEO metadata, OG tags,
etc.

***

## Door 2 — `Route::filamentCraftStorefront()` macro

For traditional Laravel controllers / Blade pages / Livewire components without
`#[Storefront]`, register a whole storefront group in one line. Tenancy + URL prefix +
middleware are wired for you, the Site is bound to the container before each handler runs.

```php
// routes/web.php — register BEFORE Route::filamentCraftTenant(...)
Route::filamentCraftStorefront(\App\Models\Academy::class, function (): void {
    Route::get('cart',     CartPage::class);
    Route::get('checkout', CheckoutPage::class);
    Route::get('account',  AccountPage::class);
    Route::get('courses/{course}/lessons/{lesson}', LessonPlayer::class);
});
```

The macro registers the group with prefix `{tenantSlug}` and middleware `web` +
`filamentcraft.tenant:{tenantSlug},{Owner},{slug}`.

With `filamentcraft.tenancy.owner_model` in config, even the first argument is optional:

```php
Route::filamentCraftStorefront(routes: function (): void {
    Route::get('cart', CartPage::class);
});
```

### Customising parameter / slug column / pattern

```php
Route::filamentCraftStorefront(
    \App\Models\Academy::class,
    function (): void { /* routes */ },
    tenantParameter: 'academySlug',
    tenantSlugColumn: 'public_slug',
    tenantPattern: '^[a-z0-9-]+$',
);
```

***

## Door 3 — Laravel Folio file-based routing (zero PHP)

For adopters using [Laravel Folio](https://laravel.com/docs/12.x/folio): opt in once and each
`.blade.php` file under `resources/views/storefront/` can be routed under the tenant prefix
and wrapped in the FilamentCraft shell.

```bash
composer require laravel/folio
php artisan filamentcraft:install --folio
```

The `--folio` flag:

1. Warns (without crashing) if Folio isn't installed yet.
2. Scaffolds `resources/views/storefront/cart.blade.php` from a starter stub.
3. Prints the FolioServiceProvider snippet you need to add manually:

   ```php
   // app/Providers/FolioServiceProvider.php
   public function boot(): void
   {
       Folio::path(resource_path('views/storefront'))
           ->uri('/{tenantSlug}')
           ->middleware(['*' => ['filamentcraft.tenant']]);
   }
   ```

Now drop files:

```
resources/views/storefront/
  cart.blade.php           → /{tenantSlug}/cart
  checkout.blade.php       → /{tenantSlug}/checkout
  account/index.blade.php  → /{tenantSlug}/account
```

Wrap each file in `<x-filamentcraft::layout>` (the `--folio` flag generates a starter
`cart.blade.php` you can copy). Zero PHP boilerplate per page.

***

## Door 4 — `<x-filamentcraft::layout>` Blade component

The escape hatch when none of the above fits — for example, a controller that needs to swap
layouts based on some runtime check, or a one-off page in an admin panel.

```blade
{{-- resources/views/cart.blade.php in the host app --}}
<x-filamentcraft::layout :title="'Your cart — '.$site->name">
    <div class="container py-12">
        <h1 class="fc-h1">Your cart</h1>

        @livewire('cart-items')
    </div>
</x-filamentcraft::layout>
```

This is what Doors 1, 2, and 3 use under the hood. All it provides over the others is
**explicitness** — useful when you want the dependency visible at the top of the file.

The component wraps any content you give it in the same shell the FilamentCraft renderer uses
for built templates:

* The site's theme tokens (CSS variables for colors, fonts, spacing)
* The site's **header region** (whatever sections the owner placed there)
* The site's **footer region**
* All registered stylesheets, fonts (Bunny preconnect included), scripts
* Correct `lang`, `dir` (RTL), and `data-fc-color-scheme` on `<html>`

### Props

| Prop | Type | Default | Notes |
|---|---|---|---|
| `:site` | `Site` | `app(Site::class)` → `TenancyResolver` → URL fallback | The Site whose theme + regions to render. Auto-resolved from the container when middleware (or a `{tenantSlug}` URL param) is in play. |
| `:title` | `?string` | `$site->name` | Sets `<title>`. |
| `:color-scheme` | `string` | `'light'` | Mirrors a template-level color scheme. |
| `:mode` | `string` | `'published'` | `'published'` reads live region data; `'draft'` reads in-progress edits (rare outside the editor preview). |
| `:locale` | `?string` | `$site->default_locale` | Forces a locale; otherwise inherits the site default. |

### Renaming the component

The package ships one class — the host picks the name. Alias in your service provider:

```php
// app/Providers/AppServiceProvider.php
use FilamentCraft\View\Components\Layout as FilamentCraftLayout;
use Illuminate\Support\Facades\Blade;

public function boot(): void
{
    Blade::component('academy-shell', FilamentCraftLayout::class);
}
```

Then everywhere in your views:

```blade
<x-academy-shell>
    @livewire('cart-items')
</x-academy-shell>
```

Pick whatever reads best for your team — `storefront`, `site-frame`, `mediano-page`, etc.
The component class is the same; the tag is yours.

***

## How Site resolution works

Every door eventually calls `<x-filamentcraft::layout>`, which resolves `$site` in this order
(first match wins):

1. **Explicit `:site` prop** — you passed one.
2. **Container binding** — `app(Site::class)` is set by middleware (`filamentcraft.tenant`,
   `filamentcraft.site`, or your own).
3. **`TenancyResolver::resolve()`** — config single-site id → `Filament::getTenant()` →
   container-bound owner model → first live site, with mode-specific skips. This is what
   makes the component work inside the admin panel.
4. **URL parameter fallback** — when the current request has a `{tenantSlug}` route param and
   `filamentcraft.tenancy.owner_model` is configured, looks up the tenant and its live Site
   on its own. This is what makes Door 1 work without middleware on the route.

If all four fail, a `RuntimeException` is thrown with a message naming the three options to
fix it. See [Tenancy](/guide/tenancy) for the deep dive.

***

## Gotchas

1. **Route order matters.** `Route::filamentCraftTenant(...)` (from
   [Public Routing](/guide/public-routing)) is a wildcard `{tenantSlug}/{path?}` that catches
   everything. Register your storefront routes (cart, checkout, account, …) **before** it, or
   they're shadowed.

2. **Filament panel tenancy.** Inside the admin panel, `<x-filamentcraft::layout>` works
   automatically because `Filament::getTenant()` populates the resolution chain. On public
   storefront routes, you need either the `filamentcraft.tenant` middleware, the
   `Route::filamentCraftStorefront()` macro, or a URL slug that matches
   `filamentcraft.tenancy.url_parameter` (default: `tenantSlug`).

3. **Stylesheet ordering.** The shell auto-injects the package's `filamentcraft-site.css`
   (built-in section styles). When you ship your own Vite bundle, make sure your CSS doesn't
   fight the `--fc-*` variables. See [Styling & Tailwind](/guide/styling).

4. **`/admin/*` coexistence.** `Route::filamentCraftTenant()` defaults its `tenantPattern` to
   `^(?!admin\b)[A-Za-z0-9-]+`, which excludes any tenant slug starting with `admin` so a
   Filament panel mounted at `/admin/{tenant}` keeps working. If you change Filament's panel
   `path` to something other than `admin` (e.g. `->path('control-panel')`), pass a matching
   `tenantPattern` to the macro to exclude that prefix too — otherwise URLs like
   `/control-panel/users` will be captured as a tenant slug.

   ```php
   Route::filamentCraftTenant(
       \App\Models\Academy::class,
       tenantPattern: '^(?!admin\b|control-panel\b)[A-Za-z0-9-]+',
   );
   ```

5. **Seeding templates: circular FK between `Template` and `TemplateRevision`.** The schema
   has a circular FK by design (templates reference their head/published revision, revisions
   reference their template). When seeding programmatically, **create the `Template` row
   first, then the `TemplateRevision` with the parent `template_id`, then update the
   template's `head_revision_id` / `published_revision_id`** — three steps:

   ```php
   $template = Template::query()->create([
       'site_id' => $site->id,
       'slug' => 'home',
       'name' => 'Home',
       'status' => TemplateStatus::Published,
       'type' => 'page',
   ]);

   $revision = TemplateRevision::query()->create([
       'template_id' => $template->id,
       'sections_json' => ['version' => 2, 'locales' => [/* ... */]],
   ]);

   $template->headRevision()->associate($revision);
   $template->publishedRevision()->associate($revision);
   $template->save();
   ```

   Creating `TemplateRevision` first hits a `NOT NULL constraint failed: template_id` error —
   the schema doesn't allow orphan revisions.

6. **Header / footer regions need explicit seeding.** A freshly-created `Site` has no
   `Region` rows. `RegionRenderer` returns an empty `HtmlString` for missing regions, so your
   shell will render *correctly* but without a visible header bar or footer until the academy
   owner creates them in the editor (or you seed them).

---

---
url: /reference/assets.md
---
# Preview & Public Assets

The Filament panel theme styles the editor chrome. The iframe preview and public template
output are **separate HTML documents**, so they also need CSS. FilamentCraft uses a three-tier
asset model.

## Tier 0 — package fallback (default)

`php artisan filamentcraft:install` copies the package's compiled section bundle to
`public/css/...`. Built-in sections render correctly out of the box, even before the host has
a custom front-end build.

## Tier 1 — mirror the admin panel into the iframe

If your Filament panel theme also contains your site/section utilities, copy those `<link>`
and `<style>` tags into the iframe at runtime:

```php
$plugin = FilamentCraftPlugin::make()
    ->mirrorEditorStyles();
```

This is useful while editing because the iframe inherits the same compiled theme as the
panel. It only affects authenticated preview rendering; public pages still need their own
stylesheet.

## Tier 2 — register the host site's Vite build

Production hosts should register the CSS/JS that visitors will receive:

```php
$plugin = FilamentCraftPlugin::make()
    ->viteManifest(public_path('build/manifest.json'), [
        'resources/css/site.css',
        'resources/js/site.ts',
    ]);
```

Or for theme-style builds under a sub-directory:

```php
$plugin = FilamentCraftPlugin::make()
    ->viteBuild('themes/shop/debut/editor');
```

Pass the configured `$plugin` to `$panel->plugin($plugin)`. You can also register URLs
directly with `->stylesheet('https://…/theme.css')` / `->script('…/site.js')` or via
`config('filamentcraft.assets.extra_styles')` / `extra_scripts`.

## Disabling the fallback

If your site build fully owns the section styling, disable the package fallback:

```php
'assets' => [
    'site_css_enabled' => false,
],
```

---

---
url: /reference/icons.md
---
# Icons

Icon settings (`Icon::make('icon')`) store the fully-qualified blade-icons name (e.g.
`heroicon-m-check-badge`). Render them in any Blade view with the bundled component:

```blade
<x-filamentcraft::icon :name="$block->settings->get('icon')" class="h-6 w-6" />
```

The component renders nothing when the name is empty, missing, or invalid — no exceptions, no
broken markup. Pass any `class` / attribute through to the `<svg>`:

```blade
<x-filamentcraft::icon
    :name="$section->settings->get('cta_icon')"
    class="h-5 w-5 text-primary"
    stroke-width="1.5"
/>
```

A `fallback` prop lets you pin a default for empty values:

```blade
<x-filamentcraft::icon :name="$icon" fallback="heroicon-o-sparkles" class="h-6 w-6" />
```

## Picking which sets to expose

By default, every set registered with `blade-icons` (Heroicons, Phosphor, Bootstrap,
Material, …) is available in the picker. Restrict per-field with the raw Filament component:

```php
use FilamentCraft\Filament\Forms\Components\IconPicker;

IconPicker::make('icon')
    ->sets(['heroicons', 'phosphor-bold'])  // only these sets
    ->styles(['outline', 'solid'])          // heroicons sub-styles
    ->gridColumns(10);                      // grid density (4–12)
```

Or via the DSL setting (single-set only):

```php
use FilamentCraft\Settings\Types\Icon;

Icon::make('cta_icon')->set('phosphor-bold');
```

To register a new icon set globally, follow the standard
[blade-icons](https://github.com/blade-ui-kit/blade-icons#defining-sets) instructions — the
picker discovers them automatically.

---

---
url: /reference/images.md
---
# Image Uploads & Variants

## Uploads

Built-in sections that accept images (Hero `bg_image`, Features icons, etc.) write to the
`public` disk under `filamentcraft/uploads/` by default. Override with environment variables:

```dotenv
FILAMENTCRAFT_UPLOADS_DISK=s3
FILAMENTCRAFT_UPLOADS_DIR=tenants/acme/site
FILAMENTCRAFT_UPLOADS_VISIBILITY=public
FILAMENTCRAFT_UPLOADS_MAX_KB=10240
```

The disk MUST be publicly readable so the renderer's `Storage::disk()->url($path)` call
resolves to a working URL.

## Size variants

`ImageValue::small()`, `medium()`, and `large()` return the original URL by default —
FilamentCraft does not bundle an image transformer. To wire up your stack's resizer (Glide,
Imgix, Cloudinary, etc.), register a resolver on the plugin:

```php
->imageSizesUsing(fn (ImageValue $image, string $size): string => match ($size) {
    'small' => $glide->getUrl($image->path, ['w' => 480]),
    'medium' => $glide->getUrl($image->path, ['w' => 1024]),
    'large' => $glide->getUrl($image->path, ['w' => 1920]),
    default => $image->url,
})
```

---

---
url: /reference/cache.md
---
# Cache

Rendered sections are fragment-cached in published mode. Tagged stores (Redis, Memcached) get
the full benefit — per-site/per-template invalidation on publish. File/array stores
transparently fall back to no-cache.

```php
'cache' => [
    'enabled' => true,
    'store' => 'redis',
    'ttl' => 3600,
    'tag_prefix' => 'fc',
],
```

Drafts are never cached — the editor always reads fresh from the in-memory `DraftStore`.

---

---
url: /reference/commands.md
---
# Make Commands

```bash
php artisan make:filamentcraft-section Testimonial
php artisan make:filamentcraft-theme Acme
```

`make:filamentcraft-section` scaffolds the section class + matching Blade view (or a Livewire
class with `--livewire`). `make:filamentcraft-theme` scaffolds an `AbstractTheme` subclass
under `app/Themes/` with a minimal `settingsSchema()` to fill in.

## Install command flags

```bash
php artisan filamentcraft:install            # publish config + migrations, register assets
php artisan filamentcraft:install --example  # also seed a working studio Site + home template
php artisan filamentcraft:install --folio    # scaffold a Folio storefront starter (Door 3)
```

`--example` is idempotent — re-running prints `Example site already seeded` and exits cleanly.

---

---
url: /reference/events.md
---
# Lifecycle Events

FilamentCraft fires four lifecycle events you can listen to:

| Event | Fired when |
|---|---|
| `FilamentCraft\Events\SiteCreated` | A new `Site` row is persisted (factory or manual). |
| `FilamentCraft\Events\TemplateDraftSaved` | The editor's Save button writes a new draft revision. |
| `FilamentCraft\Events\TemplatePublished` | A revision is promoted to `published_revision_id`. |
| `FilamentCraft\Events\SectionAdded` | A section is inserted via the Add-section modal. |

```php
Event::listen(TemplatePublished::class, function (TemplatePublished $event): void {
    Log::info("Published {$event->template->name} (revision {$event->revision->id})");
});
```

---

---
url: /reference/testing.md
---
# Testing Sections

Use `SectionDataFactory` to build a fully-resolved `SectionData` fixture in your Pest tests:

```php
use FilamentCraft\Testing\SectionDataFactory;

it('renders the heading', function (): void {
    $section = SectionDataFactory::for(MyHeroSection::class)
        ->settings(['heading' => 'Hello'])
        ->blocks([['id' => 'p1', 'type' => 'proof', 'settings' => ['value' => '3x']]])
        ->make();

    expect($section->settings->get('heading'))->toBe('Hello');
});
```

The factory exercises the same `SectionData::fromArray()` pipeline the editor uses, so
transformer-resolved values (`ImageValue`, `LinkValue`, `ColorSchemeValue`) are produced
exactly as in production.

---

---
url: /reference/dual-version.md
---
# Dual Version Support

FilamentCraft installs cleanly on **either** Filament 4 + Livewire 3 **or** Filament 5 +
Livewire 4 — the same codebase, picked automatically by Composer from what the host app
already has.

## Why it works

Filament v5 ships **zero Filament-side API changes** versus v4 — the major version bump
exists only to allow `livewire/livewire: ^4.0`. So FilamentCraft's Filament-touching code
(resources, pages, schemas, the editor) needs no version-specific branching. The
compatibility surface is the **Livewire 3 → 4** delta, and the package's surface there is
small:

* The Livewire components in `src/Editor/Livewire/` use only stable v4 APIs (`#[Url]`,
  `#[Computed]`, `#[Locked]`, `#[On]`, `dispatch()`).
* No `<livewire:...>` tag usages in any Blade view (Livewire 4 requires self-closing tags;
  we don't have any).
* No `wire:transition` modifiers (Livewire 4 removed them).

The one real risk: `livewire:morph.updated` is no longer a DOM event in v4 (it's an internal
hook). The editor's JS handles this by subscribing through `Livewire.hook('morph.updated', cb)`
— an API that exists in **both** v3 and v4 — alongside the legacy
`document.addEventListener('livewire:morph.updated', cb)` for older v3 builds.

## Supported matrix

| PHP | Laravel | Filament | Livewire | Pest | Status |
|---|---|---|---|---|---|
| 8.2 | 11.x | 4.x | 3.x | 3.x | ✅ Strict gate |
| 8.3 | 11.x | 4.x | 3.x | 3.x | ✅ Strict gate |
| 8.3 | 11.x | 5.x | 4.x | 4.x | ✅ Tests green; PHPStan `continue-on-error` |
| 8.3 | 12.x | 4.x | 3.x | 3.x | ✅ Strict gate |
| 8.3 | 12.x | 5.x | 4.x | 4.x | ✅ Tests green; PHPStan `continue-on-error` |
| 8.4 | 12.x | 4.x | 3.x | 3.x | ✅ Strict gate |
| 8.4 | 12.x | 5.x | 4.x | 4.x | ✅ Tests green; PHPStan `continue-on-error` |

Mutually-exclusive pairs (F4 + L4, F5 + L3) are explicitly excluded from CI — they don't
satisfy each other's `composer.json` requirements.

## Host installation

```bash
# Filament 4 host (existing apps)
composer require filamentcraft/filamentcraft  # resolves to F4+L3

# Filament 5 host (new or migrated apps)
composer require filamentcraft/filamentcraft  # resolves to F5+L4
```

Composer picks the pair that matches your installed Filament/Livewire automatically.

## Migrating an existing host from Filament 4 → 5

1. **Read the official Filament v5 upgrade guide first** —
   `https://filamentphp.com/docs/5.x/upgrade-guide`. It ships an automated
   `vendor/bin/filament-v5` script.
2. **Bump Filament**: `composer require filament/filament:^5.0 livewire/livewire:^4.0 -W`.
3. **`filament/blueprint`**: Blueprint v1.x caps `filament/support: ^4.0`. If your host
   depends on Blueprint, either bump to a v5-compatible Blueprint release (when available) or
   `composer remove filament/blueprint --dev` temporarily.
4. **Rebuild caches**: `php artisan config:clear && php artisan view:clear && php artisan optimize:clear`.
5. **Run your test suite** to catch Livewire 4's small breaking changes.

FilamentCraft itself needs no changes — `composer update` resolves the package's existing
dual-version constraints onto the new pair.

## What you can rely on

* **Identical behaviour across both pairs.**
* **One bundle, both versions.** The editor's JS (`resources/dist/editor.js`,
  `resources/dist/iframe-injected.js`) is the same file regardless of which version you're on
  — it negotiates the Livewire API at runtime.
* **No runtime version-sniffing in PHP.** No `version_compare()` checks. The intersection of
  APIs is the only surface used.

---

---
url: /changelog.md
---

# Changelog

All notable changes to FilamentCraft are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## \[Unreleased]

### Added

* **Dual Filament 4 + 5 / Livewire 3 + 4 support.** `composer.json` constraints
  broadened to `filament/filament: ^4.0|^5.0`, `livewire/livewire: ^3.0|^4.0`,
  `pestphp/pest: ^3.0|^4.0`, `pestphp/pest-plugin-laravel: ^3.0|^4.0` and
  `pestphp/pest-plugin-livewire: ^3.0|^4.0`. Filament v5 ships zero API changes
  versus v4 (it only exists to allow Livewire 4); the editor's JS now uses the
  version-agnostic `Livewire.hook('morph.updated', …)` API alongside the legacy
  `document.addEventListener('livewire:morph.updated', …)` listener so
  post-DOM-patch reboots fire on both Livewire 3 and 4. `phpunit.xml.dist`
  sets a deterministic `APP_KEY` so Laravel 12 + Pest 4 boots without an
  encryption-key error. CI matrix in `tests.yml` runs the full Pest suite
  against both Filament/Livewire pairs (with `filament/blueprint` auto-removed
  on the v5 leg, since Blueprint v1.x caps `filament/support` at `^4.0`).

* **Custom dynamic pages — four idiomatic doors, one shell.** Host apps can
  now render any non-template page (cart, checkout, account, lesson player,
  search results, blog comments, gated downloads) inside the same theme +
  header region + footer region + fonts + tokens that FilamentCraft templates
  use. Each adopter picks the door that matches their style:
  * **`#[Storefront]` Livewire attribute** — `FilamentCraft\Attributes\Storefront`
    extends `Livewire\Attributes\Layout` with the layout name pre-set. Drop it
    on any full-page Livewire component for zero-ceremony shell wrapping. The
    raw `#[Layout('filamentcraft::layout')]` form also works.
  * **`Route::filamentCraftStorefront(Owner::class, fn () => …)` route macro** —
    registers prefix + tenant middleware + Site binding for a whole group in
    one line. Reads the owner model from `filamentcraft.tenancy.owner_model`
    when omitted.
  * **`<x-filamentcraft::layout>` Blade component** — the explicit escape
    hatch with full prop control (`:site`, `:title`, `:color-scheme`, `:mode`,
    `:locale`). Aliasable via `Blade::component('your-name', Layout::class)`.
  * **Laravel Folio integration** — `php artisan filamentcraft:install --folio`
    scaffolds a starter `resources/views/storefront/cart.blade.php` and prints
    the FolioServiceProvider wiring. Zero PHP boilerplate per page after that.

* **`ResolveSiteFromTenant` middleware** (alias `filamentcraft.tenant`) —
  resolves the current tenant from a route-param slug, sets it as the Filament
  tenant when a panel is bootable, and binds the matching live `Site` to the
  container. Config-driven so `'filamentcraft.tenant'` with no arguments works
  when `filamentcraft.tenancy.owner_model` is set.

* **`TenantSiteResolver`** (`src/Resolvers/`) — singleton that centralises
  "owner-by-slug → `Filament::setTenant()` → live `Site`-by-morph" so the
  middleware and the Layout component's URL fallback share one implementation
  instead of duplicating ~30 lines each.

* **`Site::forOwner(Model $owner)` local scope** — polymorphic owner-match
  helper used by the resolver, replacing two raw
  `->where('owner_type', …)->where('owner_id', …)` chains.

* **`TemplateRenderer::buildShell()`** — extracted public method that returns
  the shell payload (tokens, header, footer, stylesheets, scripts, fonts,
  locale, dir, color scheme). Both `renderPayload()` and the new Layout
  component funnel through it so there's a single source of truth for the
  document chrome.

* **Auto-scroll preview on section selection.** Opening a section in the
  editor sidebar (or visiting an editor URL with `?section=…`) now smooth-
  scrolls the preview iframe to that section, using Livewire's
  `morph.updated` hook (version-agnostic) for post-patch reboots.
  Visibility-guard in the iframe handler suppresses the scroll if the
  section is already in the upper half of the viewport, so clicking a
  section inside the iframe doesn't snap-back. Consecutive same-id
  selections are deduped parent-side to skip the per-iframe `postMessage`
  fan-out.

### Fixed

* **Editor sidebar resize stopped working after page morphs.** `layout-resize.ts`
  keyed split-grid instances on the body element only — when Livewire /
  Filament navigation morphed the page tree and replaced the
  `[data-fc-layout-gutter]` node, the resize handle silently lost its
  `mousedown` listener. Now tracks the gutter element identity in a parallel
  `gutterByBody` WeakMap and rebinds when it changes.

* **`Route::filamentCraftTenant()` shadowed Filament `/admin/*` routes.** The
  default `tenantPattern` was `^(?!admin$)[A-Za-z0-9-]+`. Because PHP regex
  `$` anchors to end-of-input (the whole URL path), the negative lookahead
  only blocked the literal segment `admin` — multi-segment URLs like
  `/admin/acme` passed the lookahead, the FC tenant route captured
  `tenantSlug=admin` + `path=acme`, and every Filament panel route at
  `/admin/{tenant}/...` 404'd in real integrations. Default pattern is now
  `^(?!admin\b)[A-Za-z0-9-]+` (word boundary), which correctly rejects both
  the bare `admin` segment and `admin/anything`. Hosts that mount Filament at
  a non-default path should pass a custom `tenantPattern` to the macro that
  excludes their panel prefix too — see `docs/guides/custom-dynamic-pages.md`
  §Gotchas. New regression test in
  `tests/Feature/Routing/AdminRouteCoexistenceTest.php`.

### Changed

* `<title>` in `filamentcraft::renderer.layout` now accepts an optional
  `$title` variable, falling back to `$site->name` (used by the new Layout
  component for per-page titles in dynamic pages). No behaviour change for
  existing template renders.

* PHPStan grew a `phpstan-bootstrap.php` that registers the
  `filamentcraft::` view namespace + the `Route::filamentCraftTenant()` and
  `Route::filamentCraftStorefront()` macros at analysis time, so namespaced
  view paths and macro calls resolve cleanly without per-file `@phpstan-ignore`
  noise.

### Known caveats

* The v5 + Livewire 4 PHPStan leg is currently marked `continue-on-error` in
  `static.yml`. Pest 4 + Livewire 4 ship stricter generic stubs whose
  `@template TComponent` does not propagate through the `Livewire` facade's
  `@method static test()` declaration, surfacing ~26 false-positive errors in
  test files (`Unable to resolve template type`, `#[Computed]` properties
  missing on `instance()`). The Filament 4 + Livewire 3 leg remains the strict
  static-analysis gate. Tracking upstream: re-enable the v5 PHPStan gate once
  `larastan/larastan-livewire` ships v4 support or the Livewire facade
  propagates the template parameter.

* The `--folio` install flag scaffolds the starter file and prints the
  FolioServiceProvider snippet but does NOT auto-edit the host's
  service provider — Folio's path/uri/middleware wiring is currently a copy-
  paste step. Track for full automation once a Folio adopter asks.

### Tests

* 719 / 3098 (was 692 / 3041 in 0.1.0). New coverage: layout component
  rendering + alias support + custom-title + colour-scheme,
  `ResolveSiteFromTenant` middleware happy path + config defaults +
  not-found cases + invalid-owner errors, `Route::filamentCraftStorefront`
  route macro behaviour, URL-parameter fallback inside the Layout component
  with and without custom param names, `#[Layout]` and `#[Storefront]`
  attribute rendering through Livewire's full-page pipeline, `--folio`
  flag warning path. v4 leg PHPStan-clean, v5 leg test-clean.

## \[0.1.0] — 2026-05-12

First public release. Covers phases 0–6 of the master plan.

### Added

* **Scaffolding** — `FilamentCraftServiceProvider`, `FilamentCraftPlugin`,
  package config, install command, stubs.
* **Data layer + tenancy** — `Site`, `Theme`, `Template`, `TemplateRevision`,
  `Region` Eloquent models with circular FK split (templates ↔ revisions);
  `TenancyResolver` that works without a tenancy package; `SiteStatus`,
  `TemplateStatus`, `TemplateType`, `RegionName`, `Device` enums.
* **Section DSL + registry + transformers** — `AbstractSection`,
  `BladeSection`, `LivewireSection`, `Setting` value object, `Field`
  descriptors, `SectionRegistry`, JSON ↔ runtime transformers, locale buckets.
* **Public renderer + fragment cache** — `TemplateResolver` (exact + dynamic
  routes), `TemplateRenderer` with per-section fragment caching, `Region`
  rendering, `PublicSiteController`, `SiteContext` middleware.
* **Livewire editor shell** — `EditorPage`, plus Livewire components
  `Topbar`, `SectionList`, `SettingsPanel`, `Canvas`, `AddSectionModal`,
  `PresetPicker`; `DraftStore`, `UndoStack`, `TemplateState`,
  `LocaleBucket`, `BroadcastPayloadBuilder`, `AutoSavePreference`.
* **Iframe preview + postMessage bus + morphdom** —
  `Editor/Protocol/Message` + `MessageType`; `resources/js/postmessage-bus.ts`,
  `iframe-injected.ts`, `editor.ts`, `keybindings.ts`, `layout-resize.ts`,
  `protocol.ts`, `tooltips.ts`; `AllowSameOriginIframe` and
  `InjectEditorScript` middleware; `PreviewController`,
  `SectionRefreshController`, `TemplateRefreshController`.
* **Filament resources** — `SiteResource`, `TemplateResource`,
  `ThemeResource` (each with List / Create / Edit pages), the
  `FilamentCraftDashboard` page, and the form components
  `ColorSchemeTokensField`, `ColorSchemeGroupField`,
  `ColorSchemeGroupEditor`, `ColorSchemePicker`, `FontPickerField`,
  `IconPicker`, `TemplateUrlPicker`.
* **Blueprints** — `AbstractBlueprint`, `BlueprintRegistry`,
  `BlueprintSection`, `BlueprintSeeder`, `SeedResult`,
  `filamentcraft:seed-blueprints` artisan command, plugin-level
  registration API, locked / hidden section flags with sealed-list guards.
* **Theming** — `ThemeRegistry`, `ThemeContract`,
  `filamentcraft:sync-themes` command, default token sets, font-picker
  integration with Bunny Fonts.
* **Multi-locale** — `Locales` helper, `LocaleAwareSections` state slice,
  empty-state UX (sidebar hint + canvas card), built-in `Header` section
  with locale switcher.
* **Built-in section catalog** — `Header` section with mobile-safe wrapping
  classes.
* **Make commands** — `filamentcraft:make-section`,
  `filamentcraft:make-theme`.
* **Testing & gate** — Orchestra Testbench base case, in-memory SQLite,
  692 Pest unit + feature tests at 3043 assertions; Pint + PHPStan level 6
  * Pest wired through `composer check`; CI workflows for tests, static
    analysis, and committed JS/CSS dist parity.
* **Demo app integration** — end-to-end browser test suite running against
  `filamentcraft-demo` via Pest 4 + `pest-plugin-browser`, covering the
  editor shell, save / publish, section CRUD, drag reorder at 3 viewports,
  device switcher, keyboard shortcuts, layout resize, breakpoints, file
  upload, public renderer, multi-tenant isolation, and locked / hidden
  Blueprint sections.

### Notes

* This release ships **without** Anystack licence enforcement. The
  soft-degrade SDK + UX will land in 0.2.0. Until then the package is
  delivered as-is via the path repository in `filamentcraft-demo` for
  internal verification.
* Documentation (`filamentcraft.dev/docs`) is not part of this release.