feat: composed-view ribbon and site-editor slug deep links

docs/site-editor.md

@@ -153,6 +153,56 @@ entity work:
 These are shareable — bookmark or send to a colleague to jump straight
 into editing that entity.
 
+### Deep links by slug
+
+Path routes address entities by database id. Callers outside the SPA
+usually do not have one — the post editor's composed view, for instance,
+knows only the slug of the template it composed against. For those, the
+site editor accepts a query-string deep link on the mount URL:
+
+```text
+/visual-editor/site?entity=template&slug=single
+```
+
+On mount the SPA parses the query string, resolves the slug through the
+templates list endpoint, and navigates to that template's editor view.
+The `pushState` that follows rewrites the address bar to the canonical
+path route (`/visual-editor/site/templates/12`), so the query-string form
+is an entry point rather than a URL the user is left holding.
+
+| Parameter | Required | Notes |
+|-----------|----------|-------|
+| `entity` | yes | Only `template` is supported today. Unknown values are ignored. |
+| `slug` | yes | Entity slug. Blank or whitespace-only values are ignored. |
+| `entity_id` | no | Pre-resolved id. When supplied the slug lookup is skipped. Reserved for entity kinds that have no slug. |
+
+Behaviour worth relying on:
+
+- **Additive.** Mounting with no query string behaves exactly as it did
+  before — no lookup is issued and the SPA lands on its default section.
+- **Unknown entity is a no-op**, not an error. A link written against a
+  future package version lands on the default section rather than
+  throwing.
+- **Unresolvable slug lands on the Templates index** with a toast reading
+  `The template "{slug}" was not found.` A failed lookup does the same.
+- **The access gate is unchanged.** `SiteEditorAccessGate` runs
+  server-side, before the SPA mounts, so a denied request still renders
+  the deny-by-default page and never reaches this parsing.
+
+Build links with `buildTemplateDeepLink()` from
+`site-editor/deep-link.ts` rather than assembling the query string by
+hand, so both sides of the contract move together. The first consumer is
+the post editor's composed-view ribbon, whose **Edit template ↗** button
+opens one of these links in a new tab.
+
+`buildTemplateDeepLink()` defaults to the package's own mount path
+(`/visual-editor/site`) and takes the route base as an optional second
+argument. The composed-view ribbon currently relies on that default: the
+post editor has no way to discover a `data-route-base` the host may have
+overridden on the site-editor mount element. A host that mounts the site
+editor at a non-default path will get a ribbon CTA pointing at the
+default path until that value is threaded through to the post editor.
+
 ---
 
 ## 6. Preview

resources/js/visual-editor/editor/__tests__/canvas-styles.test.ts

@@ -45,7 +45,7 @@ describe('canvasStyles', () => {
         expect(framingIndex).toBeGreaterThan(defaultsIndex);
     });
 
-    it('places COMPOSED_CHROME_STYLES last so it can undo the framing inside chrome regions', () => {
+    it('places COMPOSED_CHROME_STYLES after the framing so it can undo it inside chrome regions', () => {
         const framingIndex = canvasStyles.findIndex(
             (entry) => entry.css === POST_EDITOR_FRAMING_STYLES
         );
@@ -56,10 +56,15 @@ describe('canvasStyles', () => {
         // The framing entry exists to frame post *content* — 48px padding
         // and a 720px column. Composed-view chrome (#655) renders inside
         // the same canvas but is a site header/footer, so it has to win
-        // against that framing; hence it lands after. Anything added later
-        // would silently outrank the chrome reset.
+        // against that framing; hence it lands after.
+        //
+        // Only the #623 ribbon sheet follows it: the ribbon is editor
+        // chrome that happens to render in the canvas and shares no
+        // selectors with the chrome regions, so it cannot outrank the
+        // reset. Any *other* future entry appended past the chrome reset
+        // would, so this pins the tail to exactly one trailing sheet.
         expect(chromeIndex).toBeGreaterThan(framingIndex);
-        expect(chromeIndex).toBe(canvasStyles.length - 1);
+        expect(chromeIndex).toBe(canvasStyles.length - 2);
     });
 
     it('keeps the alignment overrides between the canvas defaults and the post-editor framing', () => {

resources/js/visual-editor/editor/__tests__/editor-canvas.test.tsx

@@ -247,4 +247,78 @@ describe('EditorCanvas', () => {
             expect(frame.style.width).toBe('');
         });
     });
+
+    describe('composed-view ribbon (#623)', () => {
+        it('is absent in bare-content mode', () => {
+            render(
+                <EditorCanvas
+                    showTitle
+                    title=""
+                    onTitleChange={() => undefined}
+                    blockContext={null}
+                    chrome={null}
+                />
+            );
+
+            expect(
+                screen.queryByTestId('ap-composed-view-ribbon')
+            ).not.toBeInTheDocument();
+        });
+
+        it('mounts inside the canvas iframe when chrome is supplied', () => {
+            render(
+                <EditorCanvas
+                    showTitle
+                    title=""
+                    onTitleChange={() => undefined}
+                    blockContext={null}
+                    chrome={{
+                        header: [],
+                        footer: [],
+                        templateName: 'Single Post',
+                        templateSlug: 'single',
+                    }}
+                />
+            );
+
+            const ribbon = screen.getByTestId('ap-composed-view-ribbon');
+
+            // Inside the `BlockCanvas` stub, not beside it — the ribbon
+            // has to scroll with the composed preview rather than sit in
+            // the editor chrome above the frame.
+            expect(
+                screen.getByTestId('ap-stub-block-canvas')
+            ).toContainElement(ribbon);
+            expect(
+                screen.getByTestId('ap-composed-view-ribbon-cta')
+            ).toHaveAttribute(
+                'href',
+                '/visual-editor/site?entity=template&slug=single'
+            );
+        });
+
+        it('drops the CTA when composing against the fallback template', () => {
+            render(
+                <EditorCanvas
+                    showTitle
+                    title=""
+                    onTitleChange={() => undefined}
+                    blockContext={null}
+                    chrome={{
+                        header: [],
+                        footer: [],
+                        templateName: 'Default template',
+                        templateSlug: null,
+                    }}
+                />
+            );
+
+            expect(
+                screen.getByTestId('ap-composed-view-ribbon')
+            ).toBeInTheDocument();
+            expect(
+                screen.queryByTestId('ap-composed-view-ribbon-cta')
+            ).not.toBeInTheDocument();
+        });
+    });
 });

resources/js/visual-editor/editor/canvas-styles.ts

@@ -37,6 +37,7 @@ import {
 } from '../editor-settings';
 
 import canvasThemeTokens from './canvas-theme-tokens.css?inline';
+import composedRibbonStyles from './composed-view/composed-view-ribbon.css?inline';
 import flexLayoutStyles from '../../../css/flex-layout.css?inline';
 import photoGridStyles from '../blocks/_shared/photo-grid/photo-grid.css?inline';
 
@@ -221,6 +222,12 @@ const baseCanvasStyles: CanvasStyle[] = [
     // it exists to undo that framing inside the read-only header/footer
     // regions, which are chrome, not post content.
     { css: COMPOSED_CHROME_STYLES },
+    // Composed-view ribbon (#623). Lives under `composed-view/`, which
+    // the `blocks/*/*.css` glob above does not reach, so it is handed
+    // to the iframe explicitly. Last in the list because it is editor
+    // chrome rendered inside the canvas — nothing downstream should
+    // restyle it.
+    { css: composedRibbonStyles },
 ];
 
 /**

resources/js/visual-editor/editor/composed-view/__tests__/composed-view-ribbon.test.tsx

@@ -0,0 +1,90 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { ComposedViewRibbon } from '../composed-view-ribbon';
+
+describe('ComposedViewRibbon', () => {
+    it('names the resolved template', () => {
+        render(
+            <ComposedViewRibbon templateName="Single Post" templateSlug="single" />
+        );
+
+        expect(
+            screen.getByText('Editing content inside Single Post')
+        ).toBeInTheDocument();
+    });
+
+    it('labels itself as a landmark region for assistive tech', () => {
+        render(
+            <ComposedViewRibbon templateName="Single Post" templateSlug="single" />
+        );
+
+        expect(
+            screen.getByRole('region', { name: 'Composed-view controls' })
+        ).toBeInTheDocument();
+    });
+
+    it('deep-links the CTA at the site editor in a new tab', () => {
+        render(
+            <ComposedViewRibbon templateName="Single Post" templateSlug="single" />
+        );
+
+        const cta = screen.getByTestId('ap-composed-view-ribbon-cta');
+
+        expect(cta).toHaveAttribute(
+            'href',
+            '/visual-editor/site?entity=template&slug=single'
+        );
+        expect(cta).toHaveAttribute('target', '_blank');
+        expect(cta).toHaveAttribute('rel', 'noopener noreferrer');
+    });
+
+    it('encodes reserved characters in the slug', () => {
+        render(
+            <ComposedViewRibbon
+                templateName="Odd"
+                templateSlug="single/post&more"
+            />
+        );
+
+        expect(
+            screen.getByTestId('ap-composed-view-ribbon-cta')
+        ).toHaveAttribute(
+            'href',
+            '/visual-editor/site?entity=template&slug=single%2Fpost%26more'
+        );
+    });
+
+    it('honours a host-supplied site-editor route base', () => {
+        render(
+            <ComposedViewRibbon
+                templateName="Single Post"
+                templateSlug="single"
+                siteEditorRouteBase="/admin/site-editor/"
+            />
+        );
+
+        expect(
+            screen.getByTestId('ap-composed-view-ribbon-cta')
+        ).toHaveAttribute(
+            'href',
+            '/admin/site-editor?entity=template&slug=single'
+        );
+    });
+
+    it('hides the CTA on the fallback template, keeping the name', () => {
+        render(
+            <ComposedViewRibbon
+                templateName="Default template"
+                templateSlug={null}
+            />
+        );
+
+        expect(
+            screen.getByText('Editing content inside Default template')
+        ).toBeInTheDocument();
+        expect(
+            screen.queryByTestId('ap-composed-view-ribbon-cta')
+        ).not.toBeInTheDocument();
+    });
+});

resources/js/visual-editor/editor/composed-view/composed-view-ribbon.css

@@ -0,0 +1,61 @@
+/**
+ * Composed-view ribbon — #623.
+ *
+ * Injected into the canvas iframe via `canvas-styles.ts` (`?inline`),
+ * NOT imported for side effects by the component: the iframe document
+ * sees none of the parent document's Vite-injected stylesheets.
+ *
+ * Colours resolve from the ArtisanPack UI tokens re-established on the
+ * iframe root by `canvas-theme-tokens.css`, with hex fallbacks so the
+ * ribbon still reads correctly when the editor is mounted outside a
+ * DaisyUI host.
+ */
+
+.ap-visual-editor__composed-ribbon {
+	position: sticky;
+	top: 0;
+	z-index: 20;
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	justify-content: space-between;
+	gap: 0.75rem;
+	padding: 0.5rem 1rem;
+	background-color: var( --color-base-200, #f3f4f6 );
+	border-bottom: 1px solid var( --color-base-300, #e5e7eb );
+	color: var( --color-base-content, #1f2937 );
+	font-size: 0.8125rem;
+	line-height: 1.4;
+
+	/* The ribbon is editor chrome that happens to live in the canvas —
+	   selecting its text on the way to selecting a block is never what
+	   the author meant. */
+	user-select: none;
+}
+
+.ap-visual-editor__composed-ribbon-label {
+	font-weight: 500;
+}
+
+.ap-visual-editor__composed-ribbon-cta {
+	flex-shrink: 0;
+	padding: 0.25rem 0.625rem;
+	border: 1px solid var( --color-base-300, #e5e7eb );
+	border-radius: 0.25rem;
+	background-color: var( --color-base-100, #ffffff );
+	color: var( --color-primary, #2563eb );
+	font-weight: 600;
+	text-decoration: none;
+	white-space: nowrap;
+}
+
+.ap-visual-editor__composed-ribbon-cta:hover,
+.ap-visual-editor__composed-ribbon-cta:focus-visible {
+	text-decoration: underline;
+}
+
+.ap-visual-editor__composed-ribbon-cta:focus-visible {
+	outline: var( --wp-admin-border-width-focus, 2px ) solid
+		var( --color-primary, #2563eb );
+	outline-offset: 1px;
+}