@akinon/pz-theme 2.0.79-rc.1 → 2.0.80-beta.0

package/CHANGELOG.md

@@ -1,72 +1,25 @@
 # @akinon/pz-theme
 
-## 2.0.79-rc.1
-
-### Patch Changes
-
-- Updated dependencies [86187b1c]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b]
-  - @akinon/next@2.0.79-rc.1
-  - @akinon/theme-contract@2.0.79-rc.1
-
-## 2.0.79-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b]
-  - @akinon/next@2.0.79-rc.0
-  - @akinon/theme-contract@2.0.79-rc.0
+## 2.0.80-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.80-beta.0
+  - @akinon/theme-contract@2.0.80-beta.0
+
+## 2.0.79
+
+### Patch Changes
+
+- 945e153d: ZERO-4669: Keep the designer action toolbar reachable at the top of the canvas.
+
+  The toolbar is portaled to `<body>` (ZERO-4651), so nothing can clip it any more — but hanging above its host still draws it at a negative y when the host sits at the viewport top: the first section at scroll 0, and any section in a chrome slot pinned with `position: sticky; top: 0`, which reports the same box at every scroll position and so was unreachable permanently. The toolbar now flips inside its host when there is not enough room above it on screen, while the portal frame stays pinned to the host's box.
+
+  Also adds the `@akinon/pz-theme` content globs to the app's Tailwind config: without them the toolbar's own utilities (`-top-0.5`, `top-1`, `-translate-y-full`, `bg-[#4482ff]`) are never generated, so the designer chrome rendered unstyled. The app template carries the same two lines, so scaffolded brand apps are not shipping unstyled designer chrome either.
+
+  - @akinon/next@2.0.79
+  - @akinon/theme-contract@2.0.79
 
 ## 2.0.78
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.79-rc.1",
+  "version": "2.0.80-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.79-rc.1",
+    "@akinon/next": "2.0.80-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.79-rc.1",
+    "@akinon/theme-contract": "2.0.80-beta.0",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.79-rc.1",
+    "@akinon/next": "2.0.80-beta.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/components/__tests__/action-toolbar.test.tsx

@@ -0,0 +1,338 @@
+import React from 'react';
+import { render, screen, fireEvent, act } from '@testing-library/react';
+import ActionToolbar from '../action-toolbar';
+
+/**
+ * The toolbar is portaled to <body> and pinned onto its host's viewport box, so
+ * everything here is read off `document`, never off the render container, and
+ * the host has to carry `[data-block-id]` / `[data-section-id]` — that is the
+ * selector the toolbar resolves its host with.
+ *
+ * These are the placement cases; that the portal escapes every clipping
+ * declaration a composition can set is covered in
+ * `src/__tests__/designer-chrome-clipping.test.tsx`.
+ */
+
+/** Mirrors the component's own constants: 40px tall + the 2px `-top-0.5`. */
+const SPACE_NEEDED_ABOVE = 42;
+const CHROME_Z_BASE = 2147483000;
+
+const rectAt = (top: number, left = 40) => ({
+  top,
+  left,
+  right: left + 300,
+  bottom: top + 200,
+  width: 300,
+  height: 200,
+  x: left,
+  y: top
+});
+
+/**
+ * A complete rect for the host and a zero rect for everything else — the shape
+ * `getBoundingClientRect` really has. A partial mock leaves `rect.left`
+ * undefined, which used to turn the every-render measure into an infinite
+ * render loop; `nonFiniteHostRect` below pins the guard that stops it.
+ */
+const ZERO_RECT = {
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+  width: 0,
+  height: 0,
+  x: 0,
+  y: 0
+};
+
+const mockHostRect = (rect: ReturnType<typeof rectAt>) =>
+  jest
+    .spyOn(Element.prototype, 'getBoundingClientRect')
+    .mockImplementation(function (this: Element) {
+      const value = this.hasAttribute('data-block-id') ? rect : ZERO_RECT;
+      return { ...value, toJSON: () => value } as DOMRect;
+    });
+
+const renderToolbar = (
+  props: Partial<React.ComponentProps<typeof ActionToolbar>> = {}
+) =>
+  render(
+    <div data-block-id="b1">
+      <ActionToolbar label="My Section" {...props} />
+    </div>
+  );
+
+const toolbarEl = () =>
+  document.querySelector('[data-action-toolbar]') as HTMLElement;
+
+const frameEl = () => toolbarEl().parentElement as HTMLElement;
+
+/** Every re-measure but a re-render is coalesced into a frame. */
+const flushFrame = () =>
+  act(() => {
+    jest.advanceTimersByTime(20);
+  });
+
+describe('ActionToolbar placement', () => {
+  beforeEach(() => jest.useFakeTimers());
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  it('hangs above the host when there is room above it on screen', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+
+    expect(toolbarEl().className).toContain('-top-0.5');
+    expect(toolbarEl().className).toContain('-translate-y-full');
+    expect(toolbarEl().className).not.toContain('top-1');
+  });
+
+  /**
+   * The case the portal alone does not solve. Hanging above a host at the
+   * viewport top draws the toolbar at y = -42, off-screen, and nothing scrolls
+   * above 0 — rename / duplicate / delete would be unreachable. A chrome slot
+   * pinned with `position: sticky; top: 0` reports this rect at *every* scroll
+   * position, so there it is unreachable permanently.
+   */
+  it('flips inside the host when the host sits at the viewport top', () => {
+    mockHostRect(rectAt(0));
+    renderToolbar();
+
+    expect(toolbarEl().className).toContain('top-1');
+    expect(toolbarEl().className).not.toContain('-translate-y-full');
+    expect(toolbarEl().className).not.toContain('-top-0.5');
+  });
+
+  /**
+   * The flip must be expressed in the toolbar's own classes and nowhere else.
+   * Clamping or offsetting the frame instead would break the contract that the
+   * frame is pinned to the host's box
+   * (`designer-chrome-clipping.test.tsx` → 'pins a nested block toolbar…').
+   */
+  it('leaves the frame pinned to the host box when the toolbar flips', () => {
+    mockHostRect(rectAt(0, 220));
+    renderToolbar();
+
+    expect(toolbarEl().className).toContain('top-1');
+    expect(frameEl().style.position).toBe('fixed');
+    expect(frameEl().style.top).toBe('0px');
+    expect(frameEl().style.left).toBe('220px');
+  });
+
+  it('flips one pixel short of the room it needs and not one pixel over', () => {
+    mockHostRect(rectAt(SPACE_NEEDED_ABOVE - 1));
+    const short = render(
+      <div data-block-id="b1">
+        <ActionToolbar label="My Section" />
+      </div>
+    );
+    expect(toolbarEl().className).toContain('top-1');
+    short.unmount();
+
+    mockHostRect(rectAt(SPACE_NEEDED_ABOVE));
+    renderToolbar();
+    expect(toolbarEl().className).toContain('-translate-y-full');
+  });
+
+  /**
+   * Documented limitation, asserted so that fixing it is a deliberate change:
+   * once the host's top has scrolled *past* the viewport edge, neither branch
+   * puts the toolbar on screen — flipped it lands at `origin.top + 4`. The
+   * in-tree predecessor had the same hole. The fix is to slide the toolbar
+   * down inside the host by a computed amount, which needs the host's height
+   * carried in the measured origin.
+   */
+  it('still flips, but cannot rescue a host scrolled above the viewport', () => {
+    mockHostRect(rectAt(-300));
+    renderToolbar();
+
+    expect(toolbarEl().className).toContain('top-1');
+    // The frame is where the host is, i.e. off-screen; the flip does not clamp.
+    expect(frameEl().style.top).toBe('-300px');
+  });
+
+  it('repositions and re-evaluates placement on scroll', () => {
+    const spy = mockHostRect(rectAt(200));
+    renderToolbar();
+    expect(frameEl().style.top).toBe('200px');
+    expect(toolbarEl().className).toContain('-translate-y-full');
+
+    spy.mockRestore();
+    mockHostRect(rectAt(0));
+    fireEvent.scroll(window);
+    flushFrame();
+
+    expect(frameEl().style.top).toBe('0px');
+    expect(toolbarEl().className).toContain('top-1');
+    expect(toolbarEl().className).not.toContain('-translate-y-full');
+  });
+
+  it('repositions and re-evaluates placement on resize', () => {
+    const spy = mockHostRect(rectAt(0));
+    renderToolbar();
+    expect(frameEl().style.top).toBe('0px');
+    expect(toolbarEl().className).toContain('top-1');
+
+    spy.mockRestore();
+    mockHostRect(rectAt(200));
+    fireEvent.resize(window);
+    flushFrame();
+
+    expect(frameEl().style.top).toBe('200px');
+    expect(toolbarEl().className).toContain('-translate-y-full');
+  });
+
+  /**
+   * Move Up / Move Down are buttons on this toolbar: they move the host to a
+   * different y without resizing it, scrolling it or touching its attributes,
+   * so no listener fires. The canvas re-renders, so a render has to be a
+   * measuring point too.
+   */
+  it('re-evaluates placement on a re-render that moved the host', () => {
+    const spy = mockHostRect(rectAt(200));
+    const { rerender } = renderToolbar();
+    expect(toolbarEl().className).toContain('-translate-y-full');
+
+    spy.mockRestore();
+    mockHostRect(rectAt(0));
+    rerender(
+      <div data-block-id="b1">
+        <ActionToolbar label="My Section" isLocked />
+      </div>
+    );
+
+    expect(toolbarEl().className).toContain('top-1');
+  });
+
+  /**
+   * The measure runs on every render and its only brake is an unchanged
+   * origin, so a coordinate that is not a number (`NaN !== NaN`) would set a
+   * fresh origin every commit and render forever.
+   */
+  it('ignores an unreadable rect instead of re-rendering forever', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+    expect(frameEl().style.top).toBe('200px');
+
+    jest.restoreAllMocks();
+    jest
+      .spyOn(Element.prototype, 'getBoundingClientRect')
+      .mockReturnValue({ top: 10 } as DOMRect);
+
+    expect(() => {
+      fireEvent.scroll(window);
+      flushFrame();
+    }).not.toThrow();
+
+    // Left exactly where the last good measurement put it.
+    expect(frameEl().style.top).toBe('200px');
+    expect(frameEl().style.left).toBe('40px');
+  });
+
+  it('marks the toolbar with data-action-toolbar for outside-click guards', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+
+    // `accordion-block` reads this off the click target to tell chrome clicks
+    // from content clicks; portaled events still bubble through the React tree.
+    expect(toolbarEl()).toBeInTheDocument();
+  });
+});
+
+describe('ActionToolbar stacking', () => {
+  beforeEach(() => jest.useFakeTimers());
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  /**
+   * At <body> the toolbar no longer inherits the host's stacking context, so
+   * the frame carries an absolute z-index and `zIndex` is only the relative
+   * order of block chrome (default 30) over section chrome (20).
+   */
+  it('stacks the frame above page chrome and leaves the toolbar unstyled', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+
+    expect(frameEl().style.zIndex).toBe(String(CHROME_Z_BASE + 30));
+    expect(toolbarEl().style.zIndex).toBe('');
+  });
+
+  it('orders section chrome below block chrome', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar({ zIndex: 20 });
+
+    expect(frameEl().style.zIndex).toBe(String(CHROME_Z_BASE + 20));
+    expect(Number(frameEl().style.zIndex)).toBeLessThan(CHROME_Z_BASE + 30);
+  });
+
+  /**
+   * `zIndex` is added to a base that already sits just under the 32-bit
+   * maximum browsers clamp z-index to, so only a small range is usable: a
+   * larger value silently ties with everything else past the clamp instead of
+   * ordering above it.
+   */
+  it('keeps the default inside the range a browser can represent', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar();
+
+    expect(Number(frameEl().style.zIndex)).toBeLessThanOrEqual(2147483647);
+  });
+});
+
+describe('ActionToolbar rename', () => {
+  beforeEach(() => jest.useFakeTimers());
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  it('starts rename on label click and commits the trimmed value on Enter', () => {
+    mockHostRect(rectAt(200));
+    const onRename = jest.fn();
+    renderToolbar({ onRename });
+
+    fireEvent.click(screen.getByText('My Section'));
+    const input = screen.getByDisplayValue('My Section');
+    fireEvent.change(input, { target: { value: '  Renamed  ' } });
+    fireEvent.keyDown(input, { key: 'Enter' });
+
+    expect(onRename).toHaveBeenCalledWith('Renamed');
+  });
+
+  it('cancels rename on Escape without calling onRename', () => {
+    mockHostRect(rectAt(200));
+    const onRename = jest.fn();
+    renderToolbar({ onRename });
+
+    fireEvent.click(screen.getByText('My Section'));
+    const input = screen.getByDisplayValue('My Section');
+    fireEvent.change(input, { target: { value: 'Changed' } });
+    fireEvent.keyDown(input, { key: 'Escape' });
+
+    expect(onRename).not.toHaveBeenCalled();
+    expect(screen.getByText('My Section')).toBeInTheDocument();
+  });
+
+  /**
+   * The renaming input's `border-2` makes the control strip 44px, so a
+   * measured height would move the flip threshold mid-interaction and could
+   * pull the toolbar out from under the cursor. The height is a constant
+   * precisely so it cannot.
+   */
+  it('does not move the toolbar when a rename starts', () => {
+    mockHostRect(rectAt(200));
+    renderToolbar({ onRename: jest.fn() });
+    const before = toolbarEl().className;
+
+    fireEvent.click(screen.getByText('My Section'));
+
+    expect(toolbarEl().className).toBe(before);
+  });
+});

package/src/components/action-toolbar.tsx

@@ -30,6 +30,27 @@ const HOST_SELECTOR = '[data-block-id],[data-section-id]';
  */
 const CHROME_Z_BASE = 2147483000;
 
+/**
+ * The toolbar's own height, as a constant rather than a measurement: it is
+ * fully determined by this file's markup — the control strip is `h-10` and the
+ * label column is a `text-sm` 20px line box inside `p-2.5` — and nothing about
+ * the host or the composition can change it. Measuring would need a ref on an
+ * element that does not exist until `origin` is known, i.e. a second pass and
+ * a frame of wrong placement, and it would make the placement depend on
+ * `isRenaming` (the input's `border-2` makes the row 44px), so starting a
+ * rename could move the toolbar out from under the cursor.
+ */
+const TOOLBAR_HEIGHT = 40;
+
+/** The `-top-0.5` nudge above the host's edge, in pixels. */
+const TOOLBAR_TOP_OFFSET = 2;
+
+/**
+ * Room the toolbar needs above the host to be fully on screen. Hanging above,
+ * it occupies `[origin.top - 42, origin.top - 2]`.
+ */
+const SPACE_NEEDED_ABOVE = TOOLBAR_HEIGHT + TOOLBAR_TOP_OFFSET;
+
 // `useLayoutEffect` would warn during SSR; the toolbar only ever mounts in the
 // designer, but the module is part of a server-rendered package.
 const useIsomorphicLayoutEffect =
@@ -140,6 +161,13 @@ export default function ActionToolbar({
         left: rect.left + host.clientLeft
       };
 
+      // A coordinate that is not a number would defeat the bail-out below
+      // (`NaN !== NaN`), and this effect runs on every render — so the measure
+      // would set a fresh origin every commit and re-render forever. Leaving
+      // the toolbar where it is is also the right answer: an unreadable rect
+      // is a failed measurement, not a moved host.
+      if (!Number.isFinite(next.top) || !Number.isFinite(next.left)) return;
+
       setOrigin((previous) =>
         previous && previous.top === next.top && previous.left === next.left
           ? previous
@@ -232,10 +260,38 @@ export default function ActionToolbar({
       handleCancelRename();
     }
   };
+
+  /**
+   * Portaled to <body>, no ancestor can clip the toolbar any more, so the one
+   * reason left to draw it *inside* its host is that there is no room above it
+   * on screen: a host whose top is at the viewport edge would have its toolbar
+   * drawn at a negative y, painted off-screen with no scroll position that
+   * reveals it — and rename / duplicate / delete exist nowhere else. Two hosts
+   * sit there in the canvas: the top-most section at scroll 0, and anything in
+   * a chrome slot pinned with `position: sticky; top: 0`, which reports
+   * `rect.top === 0` at every scroll position and so is unreachable
+   * permanently.
+   *
+   * This covers `0 <= origin.top < SPACE_NEEDED_ABOVE` only. A host whose top
+   * has scrolled *past* the viewport edge keeps an off-screen toolbar, exactly
+   * as it did when the toolbar rendered in-tree; fixing that means sliding the
+   * toolbar down inside the host by a computed amount, which needs the host's
+   * height carried in `origin`.
+   *
+   * Derived from `origin` during render rather than kept in its own state:
+   * `origin` is the only input, so a second state set from an effect would buy
+   * an extra render and one painted frame in the old place. It cannot feed
+   * back either — the toolbar is `fixed` inside a zero-size frame at <body>
+   * and contributes no layout, so flipping it can never move the host.
+   */
+  const placeInside = origin !== null && origin.top < SPACE_NEEDED_ABOVE;
+
   const toolbar = (
     <div
       data-action-toolbar=""
-      className="absolute -top-0.5 left-0 -translate-y-full flex items-center pointer-events-auto gap-1 min-w-max"
+      className={`absolute left-0 flex items-center pointer-events-auto gap-1 min-w-max ${
+        placeInside ? 'top-1' : '-top-0.5 -translate-y-full'
+      }`}
     >
       <div className="flex items-center gap-1">
         {isRenaming ? (