@designfever/web-review-kit 0.5.0 → 0.6.0

package/README.md

@@ -26,6 +26,7 @@ This package does not own internal operator tools, private admin keys, or produc
 - [Architecture and runtime logic](docs/architecture.md): core runtime, React shell, coordinate, anchor, and extension boundaries.
 - [Figma overlay](docs/figma-overlay.md): how the shell toggles a host Figma overlay.
 - [Grid overlay](docs/grid-overlay.md): how the shell toggles a host grid/helper overlay.
+- [Release notes 0.6.0](docs/release-notes-0.6.0.md): latest shell/source tree changes and validation notes.
 
 ## Quick Start
 
@@ -130,7 +131,7 @@ export default defineConfig({
 });
 ```
 
-When source hints are available, hold `Option` over the review target to inspect source candidates from the DOM ancestry. Click the target to pin the candidate list, then choose a file to open. The side rail can also open a Source Tree panel with section/source/data links. DOM QA cards show a source action when the saved item has source hints. Keep these plugins disabled for production builds because they write source paths into the DOM.
+When source hints are available, hold `Option` over the review target to inspect source candidates from the DOM ancestry. Click the target to pin the candidate list, then choose a file to open. The side rail can also open a Source Tree panel with section/source/data links, live box metrics, text/font/media metadata, and class tags. DOM QA cards show a source action when the saved item has source hints. Source Tree filter/options, QA panel mode, and QA status filter are stored in browser localStorage. Keep these plugins disabled for production builds because they write source paths into the DOM.
 
 ```tsx
 mountReviewShell({

package/dist/{chunk-TWCSIBMY.js → chunk-IN36JHEU.js}

@@ -1266,6 +1266,14 @@ function createStyleElement() {
       cursor: default;
     }
 
+    .dfwr-shell.is-docked-composer {
+      position: relative;
+      inset: auto;
+      z-index: auto;
+      padding: 0;
+      pointer-events: auto;
+    }
+
     .dfwr-panel {
       position: fixed;
       right: 16px;
@@ -1766,6 +1774,20 @@ function createStyleElement() {
       border-color: rgba(99, 215, 199, 0.56);
     }
 
+    .dfwr-shell.is-docked-composer .dfwr-note-popover.is-docked-composer,
+    .dfwr-shell.is-docked-composer .dfwr-area-draft.is-docked-composer {
+      position: relative;
+      left: auto;
+      right: auto;
+      top: auto;
+      z-index: auto;
+      max-height: none;
+    }
+
+    .dfwr-shell.is-docked-composer .dfwr-textarea {
+      min-height: 184px;
+    }
+
     .dfwr-note-popover.is-dragging,
     .dfwr-area-draft.is-dragging {
       user-select: none;
@@ -1814,6 +1836,50 @@ function createStyleElement() {
       padding: 0;
     }
 
+    .dfwr-actions.has-leading {
+      align-items: center;
+      justify-content: space-between;
+      gap: 12px;
+    }
+
+    .dfwr-actions-leading,
+    .dfwr-actions-primary {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      min-width: 0;
+    }
+
+    .dfwr-actions-primary {
+      margin-left: auto;
+    }
+
+    .dfwr-shell.is-docked-composer .dfwr-actions.has-leading {
+      align-items: stretch;
+    }
+
+    .dfwr-shell.is-docked-composer .dfwr-actions.has-leading .dfwr-button,
+    .dfwr-shell.is-docked-composer .dfwr-actions.has-leading .dfwr-adjust-toggle {
+      height: var(--df-review-control-height-md);
+      min-height: var(--df-review-control-height-md);
+      border-radius: var(--df-review-radius-sm);
+    }
+
+    .dfwr-shell.is-docked-composer .dfwr-actions.has-leading .dfwr-button {
+      min-width: 96px;
+      padding: 0 12px;
+      font-size: var(--df-review-font-size-sm);
+    }
+
+    .dfwr-shell.is-docked-composer .dfwr-actions.has-leading .dfwr-adjust-toggle {
+      width: var(--df-review-control-height-md);
+    }
+
+    .dfwr-shell.is-docked-composer .dfwr-actions.has-leading .dfwr-adjust-toggle svg {
+      width: 18px;
+      height: 18px;
+    }
+
     .dfwr-note-actions {
       justify-content: flex-end;
     }
@@ -2138,10 +2204,12 @@ function createStyleElement() {
 
     @media (max-width: 520px) {
       .dfwr-panel {
+        left: 8px;
         right: 8px;
-        top: 8px;
-        width: calc(100vw - 16px);
-        max-height: calc(100vh - 16px);
+        top: auto;
+        bottom: 8px;
+        width: auto;
+        max-height: min(70vh, calc(100vh - 16px));
       }
     }
   `;
@@ -2221,6 +2289,7 @@ var WebReviewKitView = class {
   }
   clearDraftPreview() {
     this.restoreDraftPreview();
+    this.clearShellComposer();
   }
   render(shadow, hiddenItemsStyle) {
     const state = this.state;
@@ -2231,11 +2300,13 @@ var WebReviewKitView = class {
     shadow.append(createStyleElement());
     shadow.append(hiddenItemsStyle);
     const hasDismissableDraft = Boolean(state.noteDraft || state.areaDraft);
+    const shouldDockComposer = this.config.options.ui?.panel === false && hasDismissableDraft && Boolean(this.getShellComposerHost());
+    let dockedComposer;
     const shell = document.createElement("div");
     shell.className = [
       "dfwr-shell",
       state.isOpen ? "is-open" : "",
-      hasDismissableDraft ? "has-dismissible-draft" : ""
+      hasDismissableDraft && !shouldDockComposer ? "has-dismissible-draft" : ""
     ].filter(Boolean).join(" ");
     shell.setAttribute("aria-hidden", state.isOpen ? "false" : "true");
     if (this.config.options.ui?.panel !== false) {
@@ -2252,13 +2323,21 @@ var WebReviewKitView = class {
       shell.append(panel);
     }
     shell.append(this.createMarkerLayer());
-    if (state.isOpen && hasDismissableDraft) {
+    if (state.isOpen && hasDismissableDraft && !shouldDockComposer) {
       shell.append(this.createDraftCancelLayer());
     }
     if (state.isOpen && (state.mode === "note" || state.mode === "element")) {
-      shell.append(
-        state.noteDraft ? this.createNotePopover(state.noteDraft) : state.mode === "element" ? this.createElementLayer() : this.createNoteLayer()
-      );
+      if (state.noteDraft) {
+        const noteDraft = this.createNotePopover(state.noteDraft, {
+          dockComposer: shouldDockComposer
+        });
+        shell.append(noteDraft.layer);
+        dockedComposer = noteDraft.composer;
+      } else {
+        shell.append(
+          state.mode === "element" ? this.createElementLayer() : this.createNoteLayer()
+        );
+      }
     }
     if (state.isOpen && state.mode === "area" && !state.areaDraft) {
       shell.append(this.createAreaLayer());
@@ -2267,32 +2346,73 @@ var WebReviewKitView = class {
       if (state.areaDraft.selection) {
         shell.append(this.createAreaDraftOverlay(state.areaDraft));
       }
-      shell.append(this.createAreaDraftPopover(state.areaDraft));
+      const areaComposer = this.createAreaDraftPopover(state.areaDraft, {
+        dockComposer: shouldDockComposer
+      });
+      if (shouldDockComposer) {
+        dockedComposer = areaComposer;
+      } else {
+        shell.append(areaComposer);
+      }
     }
     shadow.append(shell);
+    this.renderShellComposer(dockedComposer);
   }
   get state() {
     return this.config.getState();
   }
+  getShellComposerHost() {
+    const environment = this.config.getEnvironment();
+    if (this.config.options.ui?.panel !== false) return void 0;
+    return environment?.composerHost ?? void 0;
+  }
+  renderShellComposer(composer) {
+    const host = composer ? this.getShellComposerHost() : void 0;
+    if (!host || !composer) {
+      this.clearShellComposer();
+      return;
+    }
+    if (this.shellComposerHost && this.shellComposerHost !== host) {
+      this.clearShellComposer();
+    }
+    this.shellComposerHost = host;
+    host.dataset.hasDraftComposer = "true";
+    if (host.parentElement) {
+      host.parentElement.dataset.hasDraftComposer = "true";
+    }
+    const shell = document.createElement("div");
+    shell.className = "dfwr-shell is-open is-shell-draft is-docked-composer";
+    shell.append(composer);
+    host.replaceChildren(createStyleElement(), shell);
+  }
+  clearShellComposer() {
+    const host = this.shellComposerHost;
+    host?.replaceChildren();
+    if (host) {
+      delete host.dataset.hasDraftComposer;
+      delete host.parentElement?.dataset.hasDraftComposer;
+    }
+    this.shellComposerHost = void 0;
+  }
   createDraftCancelLayer() {
     const layer = document.createElement("div");
     layer.className = "dfwr-draft-cancel-layer";
     layer.setAttribute("aria-hidden", "true");
-    const cancel = (event) => {
-      event.preventDefault();
-      event.stopPropagation();
-      event.stopImmediatePropagation();
-      this.config.actions.setModeState("idle");
-      this.config.actions.clearDrafts();
-      this.config.actions.setSelectingArea(false);
-      this.config.actions.render();
-    };
     layer.addEventListener("pointerdown", (event) => {
       if (event.button !== 0) return;
-      cancel(event);
+      this.cancelDraft(event);
     });
     return layer;
   }
+  cancelDraft(event) {
+    event?.preventDefault();
+    event?.stopPropagation();
+    event?.stopImmediatePropagation();
+    this.config.actions.setModeState("idle");
+    this.config.actions.clearDrafts();
+    this.config.actions.setSelectingArea(false);
+    this.config.actions.render();
+  }
   getDraftAdjustmentMetrics(draft) {
     const adjustment = draft.adjustment;
     const x = adjustment?.x ?? 0;
@@ -2686,11 +2806,11 @@ ${adjustment}` : adjustment;
     empty.textContent = this.state.noteDraft ? "Write the note in the page box." : this.state.mode === "element" ? "Click an element to add QA." : "Click on the page to place a note.";
     return empty;
   }
-  createNotePopover(draft) {
+  createNotePopover(draft, options = {}) {
     const environment = this.config.getEnvironment();
     const group = document.createElement("div");
     group.className = "dfwr-note-draft";
-    if (!environment) return group;
+    if (!environment) return { layer: group, composer: void 0 };
     const isElementDraft = this.state.mode === "element" && Boolean(draft.selection);
     const hostPoint = toHostPoint(
       isElementDraft ? this.getAdjustedDraftPoint(draft.marker.viewport, draft) : draft.marker.viewport,
@@ -2714,8 +2834,14 @@ ${adjustment}` : adjustment;
     pin.style.top = `${hostPoint.y}px`;
     const popover = document.createElement("div");
     const position = getPopoverPosition(hostPoint, environment);
-    popover.className = `dfwr-note-popover${isElementDraft ? " is-composer" : ""}`;
-    if (isElementDraft) {
+    popover.className = [
+      "dfwr-note-popover",
+      isElementDraft ? "is-composer" : "",
+      options.dockComposer ? "is-docked-composer" : ""
+    ].filter(Boolean).join(" ");
+    if (options.dockComposer) {
+      popover.style.width = "100%";
+    } else if (isElementDraft) {
       const selection = draft.selection ? toHostSelection(
         this.getAdjustedDraftSelection(
           toViewportSelection(draft.selection.viewport),
@@ -2774,18 +2900,27 @@ ${adjustment}` : adjustment;
       pin,
       popover,
       selectionHighlight,
-      textarea
+      textarea,
+      dockToggle: options.dockComposer
     }) : void 0;
-    const actions = this.createFormActions("Save note", saveDraft);
+    const actions = this.createFormActions("Save note", saveDraft, {
+      leading: adjustmentControls?.actionButton ? [adjustmentControls.actionButton] : void 0
+    });
     form.append(
       ...meta ? [meta] : [],
       ...adjustmentControls ? [adjustmentControls.panel] : [],
       textarea,
       actions
     );
-    const dragHandle = isElementDraft ? this.createDraftDragHandle("Move DOM composer") : void 0;
-    popover.append(...dragHandle ? [dragHandle] : [], form);
-    group.append(pin, popover);
+    const dragHandle = isElementDraft && !options.dockComposer ? this.createDraftDragHandle("Move DOM composer") : void 0;
+    popover.append(
+      ...dragHandle ? [dragHandle] : [],
+      form
+    );
+    group.append(pin);
+    if (!options.dockComposer) {
+      group.append(popover);
+    }
     if (dragHandle) {
       this.attachDraftComposerDrag(popover, dragHandle, (composerPosition) => {
         const noteDraft = this.state.noteDraft ?? draft;
@@ -2798,18 +2933,23 @@ ${adjustment}` : adjustment;
     }
     this.attachDraftPinDrag(
       pin,
-      isElementDraft ? void 0 : popover,
+      isElementDraft || options.dockComposer ? void 0 : popover,
       meta,
       textarea
     );
-    window.setTimeout(() => {
-      if (draft.adjustment?.isActive) {
-        adjustmentControls?.focusTarget.focus();
-        return;
-      }
-      textarea.focus();
-    }, 0);
-    return group;
+    if (!options.dockComposer) {
+      window.setTimeout(() => {
+        if (draft.adjustment?.isActive) {
+          adjustmentControls?.focusTarget.focus();
+          return;
+        }
+        textarea.focus();
+      }, 0);
+    }
+    return {
+      layer: group,
+      composer: options.dockComposer ? popover : void 0
+    };
   }
   createDraftDragHandle(label) {
     const handle = document.createElement("button");
@@ -2901,7 +3041,8 @@ ${adjustment}` : adjustment;
     pin,
     popover,
     selectionHighlight,
-    textarea
+    textarea,
+    dockToggle
   }) {
     const panel = document.createElement("div");
     panel.className = "dfwr-adjust-panel is-dom-adjust-panel";
@@ -2977,12 +3118,16 @@ ${adjustment}` : adjustment;
         }
       }));
     });
-    header.append(help, adjust);
+    header.append(help);
+    if (!dockToggle) {
+      header.append(adjust);
+    }
     panel.append(header, xyStatus, scaleStatus);
     syncControls(draft);
     return {
       panel,
-      focusTarget: adjust
+      focusTarget: adjust,
+      actionButton: dockToggle ? adjust : void 0
     };
   }
   getAdjustmentKeyDelta(event) {
@@ -3108,11 +3253,17 @@ ${adjustment}` : adjustment;
     }
     return layer;
   }
-  createAreaDraftPopover(draft) {
+  createAreaDraftPopover(draft, options = {}) {
     const environment = this.config.getEnvironment();
     const popover = document.createElement("div");
-    popover.className = "dfwr-area-draft is-composer";
-    if (environment && draft.selection) {
+    popover.className = [
+      "dfwr-area-draft",
+      "is-composer",
+      options.dockComposer ? "is-docked-composer" : ""
+    ].filter(Boolean).join(" ");
+    if (options.dockComposer) {
+      popover.style.width = "100%";
+    } else if (environment && draft.selection) {
       const selection = toHostSelection(
         toViewportSelection(draft.selection.viewport),
         environment
@@ -3128,15 +3279,20 @@ ${adjustment}` : adjustment;
       popover.style.width = `${composer.width}px`;
       popover.style.right = "auto";
     }
-    const dragHandle = this.createDraftDragHandle("Move area composer");
-    popover.append(dragHandle, this.createAreaForm());
-    this.attachDraftComposerDrag(popover, dragHandle, (composerPosition) => {
-      const areaDraft = this.state.areaDraft ?? draft;
-      this.config.actions.setAreaDraft({
-        ...areaDraft,
-        composerPosition
+    const dragHandle = options.dockComposer ? void 0 : this.createDraftDragHandle("Move area composer");
+    popover.append(
+      ...dragHandle ? [dragHandle] : [],
+      this.createAreaForm()
+    );
+    if (dragHandle) {
+      this.attachDraftComposerDrag(popover, dragHandle, (composerPosition) => {
+        const areaDraft = this.state.areaDraft ?? draft;
+        this.config.actions.setAreaDraft({
+          ...areaDraft,
+          composerPosition
+        });
       });
-    });
+    }
     return popover;
   }
   createFormActions(saveLabel, onSave, options) {
@@ -3156,12 +3312,19 @@ ${adjustment}` : adjustment;
     cancel.type = "button";
     cancel.textContent = "Cancel";
     cancel.addEventListener("click", (event) => {
-      event.preventDefault();
-      event.stopPropagation();
-      this.config.actions.setModeState("idle");
-      this.config.actions.clearDrafts();
-      this.config.actions.render();
+      this.cancelDraft(event);
     });
+    if (options?.leading?.length) {
+      actions.classList.add("has-leading");
+      const leading = document.createElement("div");
+      leading.className = "dfwr-actions-leading";
+      leading.append(...options.leading);
+      const primary = document.createElement("div");
+      primary.className = "dfwr-actions-primary";
+      primary.append(save, cancel);
+      actions.append(leading, primary);
+      return actions;
+    }
     if (options?.beforeSave?.length || options?.className) {
       actions.append(cancel, ...options.beforeSave ?? [], save);
       return actions;
@@ -3590,9 +3753,10 @@ var WebReviewKitApp = class {
       this.toggle();
     };
     this.handleViewportChange = () => {
-      if (!this.isOpen || this.renderFrame) return;
+      if (!this.isOpen || this.renderFrame || this.isDraftComposerFocused()) return;
       this.renderFrame = window.requestAnimationFrame(() => {
         this.renderFrame = void 0;
+        if (this.isDraftComposerFocused()) return;
         this.render();
       });
     };
@@ -3769,6 +3933,14 @@ var WebReviewKitApp = class {
     this.render();
     return true;
   }
+  isDraftComposerFocused() {
+    if (!this.noteDraft && !this.areaDraft) return false;
+    const composerHost = this.getEnvironment()?.composerHost;
+    const activeElement = composerHost?.ownerDocument.activeElement;
+    return Boolean(
+      composerHost && activeElement && composerHost.contains(activeElement)
+    );
+  }
   getEnvironment() {
     const target = typeof this.options.target === "function" ? this.options.target() : this.options.target;
     if (!target) {
@@ -3797,6 +3969,7 @@ var WebReviewKitApp = class {
         height: target.window.innerHeight
       };
       const overlayRect = target.getOverlayRect?.() ?? rect;
+      const composerHost = target.getComposerHost?.();
       return {
         window: target.window,
         document: target.document,
@@ -3811,7 +3984,8 @@ var WebReviewKitApp = class {
           top: overlayRect.top,
           width: overlayRect.width,
           height: overlayRect.height
-        }
+        },
+        composerHost
       };
     } catch {
       return void 0;
@@ -4090,4 +4264,4 @@ export {
   runWithAutoScrollBehavior,
   createWebReviewKit
 };
-//# sourceMappingURL=chunk-TWCSIBMY.js.map
+//# sourceMappingURL=chunk-IN36JHEU.js.map