Repository navigation
docs: V1 documentation set and release notes (#325) - #536
Merged
Merged
Conversation
Write the full V1 documentation set: install/onboarding, content model, Blade component reference, post-editor surface, custom blocks (with dynamic-block hook reference), Blade/React/Vue renderers, site-editor surface, templates with fallback chain, theme.json-backed global styles, navigation menus, synced/unsynced patterns, Inertia embedding (React + Vue), troubleshooting, and migration. Refresh README to lead with the final V1 scope (post editor + site editor + patterns) and link to every doc. Move alpha.1 entries into a dedicated CHANGELOG section and open a 1.0.0 section for the ship. Record the @wordpress/* audit conclusion for V1.0.0 in release-notes-inputs-1.0.0.md §5: hold the pins, document the multi-major delta on @wordpress/components as the blocker, resume Renovate post-tag. Add MEMORY.md capturing the final V1 architecture for future sessions. Closes #325 Closes #309 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (7)
✅ Files skipped from review due to trivial changes (7)
📝 WalkthroughWalkthroughThis PR delivers the complete V1.0.0 documentation set and release artifacts: restructures CHANGELOG and README for V1.0.0 scope, adds MEMORY.md as architecture reference, and introduces 14 comprehensive new docs covering getting started, post editor, site editor, renderers, embedding, migration, and troubleshooting—fulfilling acceptance criteria for issue ChangesVisual Editor V1.0.0 Documentation & Release
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/blade-component.md`:
- Around line 54-55: The docs incorrectly state that a missing resource-map
class match throws InvalidArgumentException; update the documentation to
reference RuntimeException instead and mention the specific failure point
(resource lookup / dynamic renderer resolution) so readers know that
RuntimeException is thrown by the resource-map lookup logic when no class match
is found (replace `InvalidArgumentException` with `RuntimeException` in the
relevant text).
In `@docs/content-model.md`:
- Around line 113-115: Docs incorrectly state that unknown resources throw
InvalidArgumentException and that controllers use $this->authorize; update the
text to reflect the implementation: unknown resources result in a 404
(NotFoundHttpException) and controllers call Gate::authorize(...) rather than
$this->authorize(...). Also ensure the discussion about deferred validation of
models with HasBlockContent remains accurate (validated on first resolving
request) and adjust the same wording at the other occurrence referenced (lines
~137-138).
In `@docs/custom-blocks.md`:
- Around line 233-243: The docs snippet for class DynamicBlock is invalid
because validateAttrs(), searchableText(), and authorize() are shown without
bodies; update the snippet to match the real safe-default implementations in
src/Blocks/DynamicBlock.php by making them concrete methods: implement
validateAttrs(array $attrs): array to return the incoming $attrs,
searchableText(array $attrs): string to return an empty string '', and
authorize(?Authenticatable $user, array $attrs): bool to return true (keep
name() and render() abstract as shown).
In `@docs/inertia.md`:
- Around line 107-112: The snippet uses editor.current?.isDirty() while the
earlier mount example uses a local editor variable; make the handle shape
consistent by changing handleNavigate to use the same editor handle as the mount
example (e.g., replace editor.current?.isDirty() with editor?.isDirty() if the
mount example exposes a local editor, or alternatively update the mount example
to use useRef and editor.current everywhere) — update the handleNavigate
function (symbol: handleNavigate) to reference the same editor variable shape
used in the mount example so both snippets are executable and consistent.
- Around line 146-164: The template binds `@change`="onChange" but no onChange
handler is defined in the <script setup>; add a handler named onChange (e.g.,
const onChange = (payload) => { /* sync local state / handle validation / mark
dirty */ }) or remove the `@change` binding from the VisualEditor instantiation;
update the script block where onSave is declared so the symbol onChange is
declared alongside onSave and used consistently with VisualEditor events.
In `@docs/post-editor.md`:
- Line 199: The link "[Theming](theming.md) — restyle editor chrome" in
docs/post-editor.md is pointing to a non-existent theming.md; update that
markdown link to point to the existing global-styles.md (i.e. replace theming.md
with global-styles.md) or alternatively add a new theming.md that
forwards/duplicates the content from global-styles.md so the navigation isn't
broken; ensure the link text remains descriptive and that the target file is
committed alongside this change.
In `@docs/site-editor.md`:
- Around line 144-150: The fenced code block containing the list starting with
"/visual-editor/site/templates/single" should include a language identifier to
satisfy markdownlint MD040; update the opening fence from "```" to "```text" so
the block becomes "```text" followed by the lines
"/visual-editor/site/templates/single",
"/visual-editor/site/template-parts/header",
"/visual-editor/site/patterns/hero", "/visual-editor/site/styles",
"/visual-editor/site/navigation/primary" and the closing "```".
In `@docs/templates.md`:
- Around line 19-24: The fenced code block showing the template hierarchy is
missing a language tag (triggers MD040); update the opening fence from ``` to
```text for the block containing "single-post-hello-world (slug-specific) ..."
so the code fence is language-specified (e.g., ```text ... ```).
In `@README.md`:
- Around line 168-169: The README mixes two config path names; replace the
inconsistent reference so the doc uses one canonical path name everywhere—update
the occurrence of "config/visual-editor.php" to the preferred
"config/artisanpack/visual-editor.php" (or vice versa if the project standard is
the shorter path) and ensure all mentions of the visual editor config in the
README consistently reference the same string
("config/artisanpack/visual-editor.php" and "config/visual-editor.php" are the
symbols to check and reconcile).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 6891aca4-96a3-48bc-a277-059df3d3b176
📒 Files selected for processing (18)
CHANGELOG.mdMEMORY.mdREADME.mddocs/blade-component.mddocs/content-model.mddocs/custom-blocks.mddocs/getting-started.mddocs/global-styles.mddocs/inertia.mddocs/migration.mddocs/navigation.mddocs/patterns.mddocs/post-editor.mddocs/release-notes-inputs-1.0.0.mddocs/renderers.mddocs/site-editor.mddocs/templates.mddocs/troubleshooting.md
| - [Blade component reference](blade-component.md) | ||
| - [Custom blocks](custom-blocks.md) | ||
| - [Renderers](renderers.md) — get saved content back onto the public site | ||
| - [Theming](theming.md) — restyle editor chrome |
There was a problem hiding this comment.
Fix likely broken internal docs link.
Line 199 points to theming.md, but this PR’s docs set references theming via global-styles.md. Please update this link or add the missing file to avoid dead navigation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/post-editor.md` at line 199, The link "[Theming](theming.md) — restyle
editor chrome" in docs/post-editor.md is pointing to a non-existent theming.md;
update that markdown link to point to the existing global-styles.md (i.e.
replace theming.md with global-styles.md) or alternatively add a new theming.md
that forwards/duplicates the content from global-styles.md so the navigation
isn't broken; ensure the link text remains descriptive and that the target file
is committed alongside this change.
Fix 8 actionable findings from CodeRabbit's review pass: - blade-component.md: VisualEditorComponent throws RuntimeException (not InvalidArgumentException) when the resource map has no match. - content-model.md: clarify that unknown resources raise NotFoundHttpException (404) and only missing HasBlockContent raises InvalidArgumentException; controllers use Gate::authorize() not \$this->authorize(). - custom-blocks.md: rewrite the DynamicBlock signature snippet so the default-bodied methods (validateAttrs, searchableText, authorize) match the real implementations rather than presenting them as bodyless pseudo-abstract methods. - inertia.md: hold the editor handle in a ref so handleNavigate's isDirty() check is consistent with the mount example; declare the onChange handler referenced by the Vue template. - site-editor.md, templates.md: add 'text' lang tags to bare fenced code blocks (markdownlint MD040). - README.md: use the published config path config/artisanpack/visual-editor.php consistently in the block defaults section. Skipped one finding: docs/post-editor.md:199 reports docs/theming.md as missing, but it exists on release/1.0 — left as-is. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Member
Author
|
Addressed 8 of 9 actionable findings in 60e33e2. Skipped the post-editor.md:199 |
github-project-automation
Bot
moved this from In Review
to Done
in ArtisanPack UI Overview
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Writes the full V1 documentation set, refreshes README + CHANGELOG for the V1 ship, and records the audited @wordpress/* version decision for V1.0.0.
Closes: #325
Closes: #309
Type of Change
Related Issue
Issue: #325
Motivation and Context
M15 is the V1 release ticket. This PR delivers everything #325's acceptance criteria asks for under "docs" (15 doc files + README + CHANGELOG + plan 11 retained as historical record), plus the @wordpress/* audit pass from plan 11 §4.1 and the package's root MEMORY.md. Tagging v1.0.0-beta.1 and v1.0.0 happens after this PR merges.
Changes Made
New docs (12):
docs/getting-started.md— install, config, first post under an hourdocs/content-model.md—HasBlockContent, resource map, policies, site-editor access gatedocs/blade-component.md— full<x-visual-editor />referencedocs/post-editor.md— canvas, inspector, document settings, media bridge, autosave flowdocs/renderers.md— Blade vs React vs Vue, registering custom renderers, paritydocs/site-editor.md— shell, navigator, canvas, sections, REST surfacedocs/templates.md— hierarchy,TemplateResolver, template parts, fallback chaindocs/navigation.md— menus, locations, fallback chain,core/navigationblock, RESTdocs/patterns.md— synced vs unsynced, authoring, library/inserter,core/blockreferencesdocs/inertia.md— Inertia+React (mountVisualEditor) and Inertia+Vue (<VisualEditor>) recipesdocs/troubleshooting.md— core-data shim, WordPress package upgrade procedure, theme.json schema upgrades, theming quirks, common errorsdocs/migration.md—visual-editor-wp-importcompanion pointer, in-package migrations, alpha.1 → 1.0.0 upgrade pathRefreshed docs:
docs/custom-blocks.md— addedDynamicBlockhooks section (validateAttrs,searchableText,authorize) + preview endpoint contractdocs/global-styles.md— rewrote out of the C3-ship framing into the V1 final state; added panels reference (typography, colors, layout, blocks) and CSS emission sectionOther:
README.mdrewritten to lead with V1 final scope; new doc table linking every pageCHANGELOG.md—[1.0.0]section opened for the ship; alpha.1 entries moved under their own header; package name fixeddocs/release-notes-inputs-1.0.0.md§5 — V1.0.0 @wordpress/* audit conclusion (hold pins; resume Renovate post-tag; +3 majors on @wordpress/components is the blocker for adoption)MEMORY.md(root) — final V1 architecture reference for future sessionsdocs/livewire.mdalready covered the M13 recipe end-to-end, so left as-is.docs/plans/11-v1-expansion.mdretained as historical record per acceptance criteria.How Has This Been Tested?
Testing Environment:
Tests Performed:
./vendor/bin/pest --compact→ 878 passed (2450 assertions)npm test→ 1836 passed across 229 test filesAccessibility Tests Run
release/1.0.Tests Added
Test details: Docs-only PR. Existing Pest + Vitest suites both green against the branch HEAD.
Documentation
Documentation details: This PR is the documentation update.
Screenshots
N/A — docs only.
Pre-Submission Checklist
Post-merge
After this merges, the v1.0.0 release sequence is:
package.jsonversion to1.0.0-beta.1; tagv1.0.0-beta.1fromrelease/1.0HEAD.docs/g6-smoke-flow.md+docs/h8-smoke-flow.md.1.0.0; tagv1.0.0.docs/release-notes-inputs-1.0.0.md§2.3).🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Changelog