Visual Editor Documentation

Welcome to the ArtisanPack UI Visual Editor documentation! This Laravel package brings the WordPress Gutenberg block editor to any Eloquent model and ships a full site editor for templates, template parts, global styles, navigation menus, and patterns.

Overview

The Visual Editor is designed to give Laravel apps a first-class block-based authoring experience. It provides:

• Post editor — A Gutenberg-powered block editor for any Eloquent model that opts in via the HasBlockContent trait
• Site editor — WordPress-style templates, template parts, theme.json-backed global styles, navigation menus, and patterns; mounted at /visual-editor/site
• 42 forked core blocks under the artisanpack/* namespace — content, media, layout, widget, entity, loop/feed, comments, and query/pagination clusters
• Three renderer packages — Blade (PHP, server-side), React, and Vue — for rendering saved block content on the public site
• Custom blocks — Authoring API for shipping your own static or dynamic blocks under any namespace
• Responsive design tools — Per-breakpoint values on block controls, resolved through a theme-aware breakpoint registry (desktop-first Tablet / Mobile overrides since 1.12.1)
• Interactive state tools — Per-state (hover, focus, active, disabled, custom) overrides on block controls
• Media bridge — Pluggable picker + upload bridge that routes Gutenberg's MediaUpload hook through any host media library
• Livewire & Inertia recipes — Drop-in embedding patterns for both stacks, plus the same browser-event contract regardless of host
• First-class pairing with artisanpack-ui/cms-framework for Post / Page / site-meta / navigation / global-styles persistence — both packages remain usable standalone
• Pluggable access gate — Fail-closed SiteEditorAccessGate contract for the site-editor surface; bind your own to integrate with any RBAC

Getting Started

• Installation Guide — Setup and configuration instructions
• Quick Start — Get up and running with a working editor in under an hour
• Configuration — Configuring the visual editor for your application

Core Concepts

• Content Model — The HasBlockContent trait, resource map, and authorization
• Renderers — Rendering saved block content on the public site
• Migration — Migrating content into the editor (including from WordPress)
• Troubleshooting — Common problems and how to resolve them

Editing Surfaces

Post Editor

The block editor for a single resource — a post, page, or any custom Eloquent model. Mounted with a single Blade component.

• Post Editor — Surface tour and what each region does
• post-editor/Getting Started — Mount your first editor in five minutes
• post-editor/Blade Component — <x-visual-editor /> reference
• post-editor/Composed View — Editing content inside its resolved template
• post-editor/Livewire Integration — Embedding inside Livewire components
• post-editor/Inertia Integration — Embedding inside Inertia (React or Vue)
• post-editor/Theming — Restyling editor chrome through DaisyUI tokens

Site Editor

The surface for editing site-wide chrome — templates, template parts, global styles, navigation menus, and patterns. Mounted at /visual-editor/site. Requires artisanpack-ui/cms-framework.

• Site Editor — Module overview and layout tour
• site-editor/Getting Started — Mount the site editor and open the access gate
• site-editor/Access Gate — Fail-closed SiteEditorAccessGate contract and bundled gates
• site-editor/Templates — Template hierarchy, fallback chain, and template parts
• site-editor/Global Styles — theme.json-backed global styles, schema pinning, and CSS emission
• site-editor/Navigation — Menus, items, and theme-declared menu locations
• site-editor/Patterns — Synced and unsynced block patterns
• Fonts — The Font Library: browse, upload, and self-host fonts (v1.7)
• Font Providers — Implement FontProvider and register a custom font catalog (v1.7)

Blocks

The block library — what ships, how to author your own, and how to wire responsive + state-aware controls.

• Blocks — Block library overview and the artisanpack/* allow-list
• blocks/Custom Blocks — Authoring your own blocks (static and dynamic)
• blocks/Icon Block — The artisanpack/icon block (FA Free + admin upload)
• blocks/Social Icons — The artisanpack/social-links block (48 services, per-icon styles) (v1.18)
• blocks/Responsive Design Tools — Per-breakpoint values on block controls
• blocks/State Design Tools — Per-state overrides (hover, focus, active, etc.)
• blocks/Effects — Block Effects panel (opacity, overflow, blend, clip shapes, gradient text) and per-block Custom CSS (v1.15)
• Animations — Block entrance, hover, and continuous animations (v1.1)
• Border Gradients — Linear / radial / conic borders + tabbed color/gradient picker (v1.1)
• Block Bindings — Bind block attributes to parent post/page/CPT data (v1.1)
• Position — CSS positioning (static / relative / absolute / fixed / sticky) with per-side offsets, z-index, and per-breakpoint overrides (v1.4)
• Visibility — Per-block runtime visibility rules: contextual (screen size, query string, referrer, browser/OS/device), user & auth (login state, role, specific user), and scheduling (v1.4)
• Dynamic Content — cms-framework Dynamic Content integration: tokens, block bindings, snippets, and the dynamic-loop block (v1.4)

Developer Resources

• Developer Guide — Extending and customizing the editor
• Hooks and Events — Filters, actions, and browser events for extending functionality
• Translations — Translate the editor UI for the artisanpack-visual-editor text domain (v1.15.1)
• Renderers — Blade, React, and Vue renderers for the public site
• AI Features — Optional AI-powered authoring affordances (suggest next block, layout, alt text, rewrite, heading hierarchy) built on artisanpack-ui/ai (v1.3); gated on the use_ai_features capability, throttled, and payload-bounded since v1.12.1

Surface Quick Reference

REST API Surface

All endpoints use the /visual-editor/api/ prefix and run through the middleware stack in config('artisanpack.visual-editor.api.middleware') (default ['api', 'auth']).

Content

• GET /{resource}, GET /{resource}/{id} — Minimal { id, title, slug } record list and lookup for any registered resource, used by record pickers (since v1.16.0)
• GET/PUT /{resource}/{id}/content — Block content CRUD for any registered resource
• PUT /{resource}/{id}/entry — Title and excerpt saves for custom content types (since v1.15.3)
• GET /{resource}/{id}/applied-template — Resolved template chrome for the post editor's composed view
• POST /blocks/preview — Dynamic block editor preview rendering; also takes an items batch of up to 25 blocks (since v1.17.0)
• GET /blocks — Enabled-block manifest (allow/deny lists applied)
• POST /query/resolve — core/query block resolution

Site editor

• GET/POST/PUT/DELETE /templates, /template-parts — Templates and parts (wp_template shape)
• GET/POST/PUT/DELETE /patterns — Synced and unsynced patterns
• GET /global-styles/lookup, GET /global-styles/base, GET /global-styles/css, GET/PUT /global-styles/{id} — Global styles
• GET/POST/PUT/DELETE /menus, /menu-items, GET /menu-locations — Navigation

Other

• GET /attachments/{id} — Media bridge (Gutenberg-shape attachment objects)
• GET /search — Link picker across all entity types
• GET /site/{id} — Site-meta envelope for core/site-* blocks

Version Compatibility

The site-editor integration needs artisanpack-ui/cms-framework installed at a compatible version.

visual-editor 1.12 declares a Composer conflict with cms-framework older than 2.11, so Composer refuses the unsupported pairing.

Configuration

The editor uses a single configuration file:

// config/artisanpack/visual-editor.php
return [
    'resources' => [
        'posts' => App\Models\Post::class,
    ],
    'api' => [
        'middleware' => ['api', 'auth'],
    ],
    // ...
];

See Configuration for the full reference.

Support

For issues, feature requests, and contributions:

• GitHub: https://github.com/ArtisanPack-UI/visual-editor
• Documentation: https://artisanpack.dev/packages/visual-editor

This documentation covers visual-editor v1.15.0