Download the PHP package artisanpack-ui/visual-editor without Composer

ArtisanPack UI Visual Editor

A Gutenberg-powered visual editor for Laravel applications. Brings the WordPress block editor to any Eloquent model, plus a full site editor for templates, template parts, global styles, navigation menus, and patterns.

V1.0 ships:

• Post editor — block-based content editing on any model that opts in via the HasBlockContent trait.
• Site editor — 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. core/* markup pasted from upstream auto-converts on insert.
• Icon block (artisanpack/icon, v1.1) — Font Awesome 6 Free bundled, custom SVG paste with server-side sanitization, and admin upload for licensed sets (e.g. Font Awesome Pro). See docs/blocks/Icon-Block.md.
• Three renderer packages — Blade (server-side), React, and Vue — for rendering saved block content on the public site.
• First-class pairing with artisanpack-ui/cms-framework for Posts, Pages, site-meta, navigation, and global-styles persistence. Both packages remain usable standalone.

Full documentation: see documentation home for the full surface.

Installation

For the site editor (recommended for most apps):

See the Quick Start for the full setup.

Version compatibility

The visual-editor and artisanpack-ui/cms-framework packages ship as a version pair — both packages need to be present, and both need to be on a compatible major version, for the site-editor integration to work. Install one without the other and the site-editor's install gate (#432) surfaces a "cms-framework required" page instead of mounting.

Bumping the major on either package without bumping the partner is unsupported.

Peer dependencies

The editor UI is built on @artisanpack-ui/react, which is styled with DaisyUI and Tailwind CSS. Host applications embedding the editor must have the following installed and loaded:

• tailwindcss ^4.0.0
• daisyui ^5.0.0

Usage

Add the HasBlockContent trait to any model and register it in config/artisanpack/visual-editor.php:

Mount the editor in a Blade view:

The site editor mounts automatically at /visual-editor/site when cms-framework is installed and the configured SiteEditorAccessGate permits the request.

See docs/post-editor/Blade-Component.md for the full component reference and docs/site-editor.md for the site-editor surface.

Documentation

📚 Complete Documentation

Getting Started

• Installation Guide — Setup and configuration
• Quick Start — Ship your first post in under an hour
• Configuration — Full configuration reference

Core Concepts

Post Editor

Site Editor

Blocks

Developer Resources

• Developer Guide — Extending the editor
• Hooks and Events — Filters, actions, and browser events

Gutenberg adoption — transient shims

The V1 editor adopts the upstream @wordpress/* packages. Some of those packages expect a WordPress backend that this package doesn't provide, so we ship temporary shims under resources/js/visual-editor/vendor/:

• core-data-shim.ts — aliased in vite.config.ts as @wordpress/core-data. Provides the entity registrations and selectors Gutenberg expects (getEntityRecord, getEntityRecords, resolvers, permissions stubs). Templates, template parts, navigation, patterns, global styles, attachments, and site-meta are wired through to the package's REST surface.
• media-upload-stub.tsx — registers editor.MediaUpload via @wordpress/hooks so the media-library picker on core/image is routed through a stub or the real registerArtisanpackMediaBridge(MediaModal, uploadMedia) bridge.

Both shims will be replaced over the V1.x release line as the cms-framework side surfaces real backings. Every selector or filter implemented here is one to re-verify against Gutenberg upgrades. See docs/troubleshooting.md.

Block defaults

V1 ships a frozen allow-list of forked blocks under the artisanpack/* namespace. The defaults in config/artisanpack/visual-editor.php expose every block that landed during the Phase I block fork — @wordpress/block-library's registerCoreBlocks() is no longer called, and the editor registers only the in-package forks discovered under resources/js/visual-editor/blocks/. See docs/blocks.md for the full block library overview and the core/* → artisanpack/* mapping.

The forked allow-list covers the content, media, layout, widget, entity, loop/feed, comments, query/pagination, and authentication clusters. Entity blocks (artisanpack/post-*, artisanpack/site-*, artisanpack/template-part, artisanpack/navigation) and the loop / feed cluster (artisanpack/query, artisanpack/post-template, artisanpack/archives, artisanpack/categories, artisanpack/tag-cloud) need an entity in scope to render meaningful content — pair the editor with artisanpack-ui/cms-framework and they resolve against Posts / Pages / templates / site settings end-to-end. Standalone, they fall back to empty shells rather than crashing.

disabled_blocks is empty by default: with the I7 cutover (#415) the editor no longer registers any core/* block, so there's nothing to deny-list. New @wordpress/block-library releases similarly bring no new registrations into this package — additions land only when a fork is added to the in-package blocks directory and to the allow-list. from:core/* transforms ship on each fork so existing core/* markup pasted from upstream converts on insert.

Override the defaults by publishing the config to config/artisanpack/visual-editor.php and editing the enabled_blocks / disabled_blocks arrays. The deny-list always wins over the allow-list.

Using with cms-framework

The visual editor is fully usable standalone, but pairs with artisanpack-ui/cms-framework to unlock:

• Editable Post and Page content out of the box.
• A real backing for core/site-* blocks (site title, tagline, logo, icon).
• Working core/post-*, core/query, taxonomy widget, and navigation blocks.
• Templates, template parts, patterns, global styles, and menus persisted via cms-framework's models.
• Seeded visual_editor.* permissions.

Both packages are loosely coupled — cms-framework's editor wiring is guarded by class_exists(\ArtisanPackUI\VisualEditor\VisualEditor::class), so each remains usable on its own. See docs/site-editor/Getting-Started.md for the site-editor pairing walkthrough.

Extensibility

Hook rename (v1.5.0, #664). Every visual-editor hook now uses camelCase — the old kebab-case names below (ap.visual-editor.*, ap.icons.register-icon-sets, visual_editor.pre_publish_checks) remain functional through deprecateHook() aliases and continue to route callbacks to the canonical name, but log a deprecation notice the first time each alias resolves per process. New code should use the camelCase names. See src/Support/HookAliases.php for the full rename table.

ap.visualEditor.resources

Register slug → Eloquent model class mappings used by /visual-editor/api/{resource}/{id}/content. Filter contributions are merged with config('artisanpack.visual-editor.resources'); the static config wins on key collision so host-app overrides always take precedence. Models must use ArtisanPackUI\VisualEditor\Concerns\HasBlockContent — invalid entries surface as InvalidArgumentException on first request rather than at boot, so a contributor's standalone install never trips host boot.

Full contract: docs/content-model.md and docs/Hooks-and-Events.md.

ap.icons.registerIconSets

Editor chrome icons resolve through artisanpack-ui/icons. Register additional icon sets in a service provider — see the artisanpack-ui/icons docs.

Lifecycle hooks (v1.6.0, #665)

Six additional hooks cover the block-registration, block-render, post-persistence, editor-config, and pattern-render lifecycles. The tables below summarise each; the full contract is documented in docs/Hooks-and-Events.md.

AI features

The visual editor ships five optional AI-powered authoring affordances that build on top of the artisanpack-ui/ai foundation. All five default to off — hosts opt in by enabling the corresponding feature key from the AI package's settings surface, and each affordance honors that toggle before rendering.

The first three agents live in this package (src/Ai/Agents/); the last two are cross-cutting agents consumed directly from artisanpack-ui/ai so the same prompt + feature toggle powers alt-text and content rewrites across every package that opts in.

Server-side surface

The features are auto-registered with the AI package's FeatureRegistry via VisualEditorServiceProvider::aiFeatures() — no manual wiring required. Each has a JSON endpoint under /visual-editor/api/ai/* for the React editor to hit:

Blade / Livewire hosts can consume the same triggers through the shipped Livewire component artisanpack-visual-editor.ai.tools, which listens for ap-ve-ai:* browser events and re-dispatches results as ap-ve-ai:{feature}:{status}.

React surface

Full component list: resources/js/visual-editor/ai/index.ts.

Requirements

• artisanpack-ui/ai ^1.0 installed and configured with credentials.
• The individual feature toggle enabled (default: off) from the AI settings admin surface.
• CSRF middleware active on the /visual-editor/api/* route group so the shipped JS client's X-CSRF-TOKEN header is honored.

Every affordance surfaces as a suggestion — never an automatic mutation. Accepting a suggestion is always explicit user action, per the AI RFC.

i18n

Editor strings use @wordpress/i18n with the artisanpack-visual-editor text domain. The domain is initialized via bootI18n() in resources/js/visual-editor/vendor/i18n.ts.

Regenerate the placeholder .pot catalog with:

The extractor scans resources/js/visual-editor/**/*.{ts,tsx} for __/_x/_n/_nx calls bound to the text domain and writes languages/artisanpack-visual-editor.pot.

Contributing

As an open source project, this package is open to contributions from anyone. Please read through the contributing guidelines to learn more about how you can contribute to this project.