@beyondwork/docx-react-component 1.0.92 → 1.0.94

package/src/ui-tailwind/toolbar/tw-toolbar.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { createPortal } from "react-dom";
 
 import * as Popover from "@radix-ui/react-popover";
 import * as Select from "@radix-ui/react-select";
@@ -83,6 +84,13 @@ export interface TwToolbarProps {
   scopedChromePolicy?: ScopedChromePolicy;
   preset?: WordReviewEditorChromePreset;
   compactMode?: boolean;
+  /**
+   * True when the runtime has an active editable text/paragraph target
+   * (focused caret or range selection). Formatting, paragraph, list, and
+   * structural insert controls use this in addition to document-level edit
+   * capability so top chrome does not advertise commands against no target.
+   */
+  hasEditableSelectionTarget?: boolean;
   workspaceMode: WorkspaceMode;
   zoomLevel?: ZoomLevel;
   formattingState?: FormattingStateSnapshot;
@@ -231,6 +239,80 @@ const HIGHLIGHT_COLORS = [
   { value: null, label: "None" },
 ] as const;
 
+function ToolbarPortalMenu(props: {
+  anchorRef: React.RefObject<HTMLButtonElement | null>;
+  align?: "start" | "end";
+  children: React.ReactNode;
+  className: string;
+  menuWidthPx: number;
+  open: boolean;
+}): React.ReactPortal | null {
+  const style = useToolbarPortalPosition({
+    align: props.align ?? "start",
+    anchorRef: props.anchorRef,
+    menuWidthPx: props.menuWidthPx,
+    open: props.open,
+  });
+  const body = props.anchorRef.current?.ownerDocument?.body;
+  if (!props.open || !body) {
+    return null;
+  }
+  return createPortal(
+    <div className={props.className} style={style}>
+      {props.children}
+    </div>,
+    body,
+  );
+}
+
+function useToolbarPortalPosition(input: {
+  align: "start" | "end";
+  anchorRef: React.RefObject<HTMLButtonElement | null>;
+  menuWidthPx: number;
+  open: boolean;
+}): React.CSSProperties {
+  const [style, setStyle] = React.useState<React.CSSProperties>({
+    left: 8,
+    position: "fixed",
+    top: 8,
+    zIndex: 50,
+  });
+
+  React.useLayoutEffect(() => {
+    if (!input.open) return;
+    const anchor = input.anchorRef.current;
+    const ownerWindow = anchor?.ownerDocument?.defaultView;
+    if (!anchor || !ownerWindow) return;
+
+    const update = () => {
+      const rect = anchor.getBoundingClientRect();
+      const viewportWidth = ownerWindow.innerWidth || input.menuWidthPx + 16;
+      const rawLeft =
+        input.align === "end" ? rect.right - input.menuWidthPx : rect.left;
+      const left = Math.min(
+        Math.max(8, rawLeft),
+        Math.max(8, viewportWidth - input.menuWidthPx - 8),
+      );
+      setStyle({
+        left,
+        position: "fixed",
+        top: Math.max(8, rect.bottom + 8),
+        zIndex: 50,
+      });
+    };
+
+    update();
+    ownerWindow.addEventListener("resize", update);
+    ownerWindow.addEventListener("scroll", update, true);
+    return () => {
+      ownerWindow.removeEventListener("resize", update);
+      ownerWindow.removeEventListener("scroll", update, true);
+    };
+  }, [input.align, input.anchorRef, input.menuWidthPx, input.open]);
+
+  return style;
+}
+
 export function TwToolbar(props: TwToolbarProps) {
   const caps = props.capabilities;
   const preset = props.preset ?? "advanced";
@@ -238,8 +320,21 @@ export function TwToolbar(props: TwToolbarProps) {
   const workspaceMode = props.workspaceMode;
   const paragraphStyles = props.styleCatalog?.paragraphs ?? [];
   const zoomLevel = props.zoomLevel ?? 100;
-  const canEdit = props.interactionPolicy?.canFormatText ?? (caps ? caps.canEdit : false);
-  const canInsertStructural = props.interactionPolicy?.canInsertStructural ?? canEdit;
+  const hasEditableSelectionTarget = props.hasEditableSelectionTarget ?? true;
+  const baseCanFormatText = props.interactionPolicy?.canFormatText ?? (caps ? caps.canEdit : false);
+  const baseCanInsertStructural = props.interactionPolicy?.canInsertStructural ?? baseCanFormatText;
+  const selectionTargetDisabledReason = !hasEditableSelectionTarget
+    ? "Place the cursor in the document or select text first."
+    : undefined;
+  const editModeDisabledReason =
+    props.interactionPolicy && props.interactionPolicy.mode !== "edit"
+      ? `Not available in ${props.interactionPolicy.mode} mode.`
+      : "Editing is not available in this document.";
+  const editDisabledReason = selectionTargetDisabledReason ?? (!baseCanFormatText ? editModeDisabledReason : undefined);
+  const insertDisabledReason =
+    selectionTargetDisabledReason ?? (!baseCanInsertStructural ? editModeDisabledReason : undefined);
+  const canEdit = baseCanFormatText && hasEditableSelectionTarget;
+  const canInsertStructural = baseCanInsertStructural && hasEditableSelectionTarget;
   const canAddComment = props.interactionPolicy?.canAddComment ?? (caps ? caps.canAddComment : false);
   const showDiagnosticsChrome = props.showDiagnosticsChrome ?? true;
   const scopedChromePolicy = props.scopedChromePolicy ?? resolveScopedChromePolicy({
@@ -354,6 +449,7 @@ export function TwToolbar(props: TwToolbarProps) {
           <>
             <ToolbarParagraphStyleSelect
               disabled={!canEdit || paragraphStyles.length === 0 || !props.onSetParagraphStyle}
+              disabledReason={editDisabledReason}
               styles={paragraphStyles}
               value={props.formattingState?.paragraphStyleId}
               hasMixedValue={props.hasMixedParagraphStyle ?? false}
@@ -362,12 +458,14 @@ export function TwToolbar(props: TwToolbarProps) {
 
             <ToolbarFontFamilySelect
               disabled={!canEdit || !props.onSetFontFamily}
+              disabledReason={editDisabledReason}
               value={props.formattingState?.fontFamily}
               hasMixedValue={props.hasMixedFontFamily ?? false}
               onValueChange={props.onSetFontFamily}
             />
             <ToolbarFontSizeSelect
               disabled={!canEdit || !props.onSetFontSize}
+              disabledReason={editDisabledReason}
               value={props.formattingState?.fontSize}
               hasMixedValue={props.hasMixedFontSize ?? false}
               onValueChange={props.onSetFontSize}
@@ -385,6 +483,7 @@ export function TwToolbar(props: TwToolbarProps) {
               shortcut="⌘B"
               active={props.formattingState?.bold ?? false}
               disabled={!canEdit || !props.onToggleBold}
+              disabledReason={editDisabledReason}
               onClick={props.onToggleBold}
             />
             <TwToolbarIconButton
@@ -393,6 +492,7 @@ export function TwToolbar(props: TwToolbarProps) {
               shortcut="⌘I"
               active={props.formattingState?.italic ?? false}
               disabled={!canEdit || !props.onToggleItalic}
+              disabledReason={editDisabledReason}
               onClick={props.onToggleItalic}
             />
             <TwToolbarIconButton
@@ -401,6 +501,7 @@ export function TwToolbar(props: TwToolbarProps) {
               shortcut="⌘U"
               active={props.formattingState?.underline ?? false}
               disabled={!canEdit || !props.onToggleUnderline}
+              disabledReason={editDisabledReason}
               onClick={props.onToggleUnderline}
             />
             {showAdvancedFormatting ? (
@@ -411,6 +512,7 @@ export function TwToolbar(props: TwToolbarProps) {
                     !props.onToggleSuperscript &&
                     !props.onToggleSubscript)
                 }
+                disabledReason={editDisabledReason}
                 formattingState={props.formattingState}
                 onToggleStrikethrough={props.onToggleStrikethrough}
                 onToggleSuperscript={props.onToggleSuperscript}
@@ -427,7 +529,9 @@ export function TwToolbar(props: TwToolbarProps) {
                   ariaLabel="Text color"
                   colors={TEXT_COLORS.map((value) => ({ value, label: value }))}
                   disabled={!canEdit || !props.onSetTextColor}
+                  disabledReason={editDisabledReason}
                   icon={<Baseline className="h-3.5 w-3.5" />}
+                  activeValue={props.formattingState?.textColor?.toLowerCase()}
                   onSelect={(value) => {
                     if (value) {
                       props.onSetTextColor?.(value);
@@ -439,7 +543,9 @@ export function TwToolbar(props: TwToolbarProps) {
                   ariaLabel="Highlight color"
                   colors={HIGHLIGHT_COLORS.map((entry) => ({ value: entry.value, label: entry.label }))}
                   disabled={!canEdit || !props.onSetHighlightColor}
+                  disabledReason={editDisabledReason}
                   icon={<Highlighter className="h-3.5 w-3.5" />}
+                  activeValue={props.formattingState?.highlightColor?.toLowerCase() ?? null}
                   onSelect={(value) => props.onSetHighlightColor?.(value)}
                   title="Highlight color"
                 />
@@ -449,6 +555,7 @@ export function TwToolbar(props: TwToolbarProps) {
               <ToolbarAlignmentPopover
                 activeAlignment={props.formattingState?.alignment}
                 disabled={!canEdit || !props.onSetAlignment}
+                disabledReason={editDisabledReason}
                 onSelect={(alignment) => props.onSetAlignment?.(alignment)}
               />
             ) : null}
@@ -464,6 +571,7 @@ export function TwToolbar(props: TwToolbarProps) {
               label="Bulleted list"
               active={Boolean(props.activeListContext && !props.activeListContext.isOrdered)}
               disabled={!canEdit || !props.onToggleBulletedList}
+              disabledReason={editDisabledReason}
               onClick={props.onToggleBulletedList}
             />
             <TwToolbarIconButton
@@ -471,6 +579,7 @@ export function TwToolbar(props: TwToolbarProps) {
               label="Numbered list"
               active={Boolean(props.activeListContext?.isOrdered)}
               disabled={!canEdit || !props.onToggleNumberedList}
+              disabledReason={editDisabledReason}
               onClick={props.onToggleNumberedList}
             />
           </>
@@ -481,12 +590,14 @@ export function TwToolbar(props: TwToolbarProps) {
               icon={Outdent}
               label="Outdent"
               disabled={!canEdit || !props.onOutdent}
+              disabledReason={editDisabledReason}
               onClick={props.onOutdent}
             />
             <TwToolbarIconButton
               icon={Indent}
               label="Indent"
               disabled={!canEdit || !props.onIndent}
+              disabledReason={editDisabledReason}
               onClick={props.onIndent}
             />
           </>
@@ -497,6 +608,8 @@ export function TwToolbar(props: TwToolbarProps) {
               type="button"
               aria-label="Restart numbering"
               disabled={!canEdit || !props.onRestartNumbering}
+              title={!canEdit && editDisabledReason ? `Not available: ${editDisabledReason}` : undefined}
+              data-disabled-reason={!canEdit && editDisabledReason ? editDisabledReason : undefined}
               onMouseDown={preserveEditorSelectionMouseDown}
               onClick={props.onRestartNumbering}
               className={`inline-flex h-6 items-center rounded-md px-2 text-[11px] font-medium text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
@@ -507,6 +620,8 @@ export function TwToolbar(props: TwToolbarProps) {
               type="button"
               aria-label="Continue numbering"
               disabled={!canEdit || !props.onContinueNumbering}
+              title={!canEdit && editDisabledReason ? `Not available: ${editDisabledReason}` : undefined}
+              data-disabled-reason={!canEdit && editDisabledReason ? editDisabledReason : undefined}
               onMouseDown={preserveEditorSelectionMouseDown}
               onClick={props.onContinueNumbering}
               className={`inline-flex h-6 items-center rounded-md px-2 text-[11px] font-medium text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
@@ -518,6 +633,7 @@ export function TwToolbar(props: TwToolbarProps) {
         {showInsertMenu && showInsertActionsInRow ? (
           <ToolbarInsertMenu
             disabled={!canInsertStructural}
+            disabledReason={insertDisabledReason}
             disabledReasons={props.insertDisabledReasons}
             onInsertImage={props.onInsertImage}
             onInsertPageBreak={props.onInsertPageBreak}
@@ -531,6 +647,8 @@ export function TwToolbar(props: TwToolbarProps) {
               type="button"
               aria-label="Refresh fields"
               disabled={!canEdit || !props.onUpdateFields}
+              title={!canEdit && editDisabledReason ? `Not available: ${editDisabledReason}` : undefined}
+              data-disabled-reason={!canEdit && editDisabledReason ? editDisabledReason : undefined}
               onMouseDown={preserveEditorSelectionMouseDown}
               onClick={props.onUpdateFields}
               className={`inline-flex h-6 items-center rounded-md px-2 text-[11px] font-medium text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
@@ -541,6 +659,8 @@ export function TwToolbar(props: TwToolbarProps) {
               type="button"
               aria-label="Refresh table of contents"
               disabled={!canEdit || !props.onUpdateTableOfContents}
+              title={!canEdit && editDisabledReason ? `Not available: ${editDisabledReason}` : undefined}
+              data-disabled-reason={!canEdit && editDisabledReason ? editDisabledReason : undefined}
               onMouseDown={preserveEditorSelectionMouseDown}
               onClick={props.onUpdateTableOfContents}
               className={`inline-flex h-6 items-center rounded-md px-2 text-[11px] font-medium text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
@@ -554,7 +674,9 @@ export function TwToolbar(props: TwToolbarProps) {
             activeListContext={props.activeListContext}
             canEdit={canEdit}
             canInsertStructural={canInsertStructural}
+            editDisabledReason={editDisabledReason}
             formattingState={props.formattingState}
+            insertDisabledReason={insertDisabledReason}
             paragraphStyles={paragraphStyles}
             showInsertMenu={getToolbarChromePlacement(scopedChromePolicy, "insert-actions") === "overflow"}
             showListActions={getToolbarChromePlacement(scopedChromePolicy, "list-actions") === "overflow"}
@@ -918,6 +1040,7 @@ function ToolbarParagraphStyleSelect(props: {
   styles: StyleCatalogSnapshot["paragraphs"];
   value?: string;
   disabled: boolean;
+  disabledReason?: string;
   hasMixedValue?: boolean;
   onValueChange?: (styleId: string) => void;
 }) {
@@ -939,7 +1062,9 @@ function ToolbarParagraphStyleSelect(props: {
         aria-label="Paragraph style"
         aria-disabled={props.disabled || undefined}
         data-disabled={props.disabled ? "" : undefined}
+        data-disabled-reason={props.disabled && props.disabledReason ? props.disabledReason : undefined}
         data-mixed={isMixed ? "true" : undefined}
+        title={props.disabled && props.disabledReason ? `Not available: ${props.disabledReason}` : undefined}
         onMouseDown={preserveEditorSelectionMouseDown}
         className={`inline-flex h-6 min-w-[7.5rem] items-center justify-between gap-2 rounded-md border border-border bg-canvas px-2 text-[11px] font-medium text-primary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
       >
@@ -984,6 +1109,7 @@ function ToolbarParagraphStyleSelect(props: {
 function ToolbarFontFamilySelect(props: {
   value?: string;
   disabled: boolean;
+  disabledReason?: string;
   hasMixedValue?: boolean;
   onValueChange?: (fontFamily: string) => void;
 }) {
@@ -1003,7 +1129,9 @@ function ToolbarFontFamilySelect(props: {
         aria-label="Font family"
         aria-disabled={props.disabled || undefined}
         data-disabled={props.disabled ? "" : undefined}
+        data-disabled-reason={props.disabled && props.disabledReason ? props.disabledReason : undefined}
         data-mixed={isMixed ? "true" : undefined}
+        title={props.disabled && props.disabledReason ? `Not available: ${props.disabledReason}` : undefined}
         onMouseDown={preserveEditorSelectionMouseDown}
         className={`inline-flex h-6 min-w-[6.5rem] items-center justify-between gap-2 rounded-md border border-border bg-canvas px-2 text-[11px] font-medium text-primary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
       >
@@ -1048,6 +1176,7 @@ function ToolbarFontFamilySelect(props: {
 function ToolbarFontSizeSelect(props: {
   value?: number;
   disabled: boolean;
+  disabledReason?: string;
   hasMixedValue?: boolean;
   onValueChange?: (fontSize: number) => void;
 }) {
@@ -1069,7 +1198,9 @@ function ToolbarFontSizeSelect(props: {
         aria-label="Font size"
         aria-disabled={props.disabled || undefined}
         data-disabled={props.disabled ? "" : undefined}
+        data-disabled-reason={props.disabled && props.disabledReason ? props.disabledReason : undefined}
         data-mixed={isMixed ? "true" : undefined}
+        title={props.disabled && props.disabledReason ? `Not available: ${props.disabledReason}` : undefined}
         onMouseDown={preserveEditorSelectionMouseDown}
         className={`inline-flex h-6 min-w-[3.5rem] items-center justify-between gap-2 rounded-md border border-border bg-canvas px-2 text-[11px] font-medium text-primary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
       >
@@ -1115,7 +1246,9 @@ function ToolbarCompactOverflow(props: {
   activeListContext?: ActiveListContext | null;
   canEdit: boolean;
   canInsertStructural: boolean;
+  editDisabledReason?: string;
   formattingState?: FormattingStateSnapshot;
+  insertDisabledReason?: string;
   paragraphStyles: StyleCatalogSnapshot["paragraphs"];
   showInsertMenu: boolean;
   showListActions: boolean;
@@ -1140,6 +1273,7 @@ function ToolbarCompactOverflow(props: {
   onUpdateTableOfContents?: () => void;
 }) {
   const [open, setOpen] = React.useState(false);
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
 
   async function handleImageChange(event: React.ChangeEvent<HTMLInputElement>): Promise<void> {
     const file = event.target.files?.[0];
@@ -1159,19 +1293,28 @@ function ToolbarCompactOverflow(props: {
   }
 
   return (
-    <div className="relative">
+    <Popover.Root open={open} onOpenChange={setOpen}>
       <Tooltip.Root>
         <Tooltip.Trigger asChild>
-          <button
-            type="button"
-            aria-label="More document tools"
-            aria-expanded={open}
-            onMouseDown={preserveEditorSelectionMouseDown}
-            onClick={() => setOpen((value) => !value)}
-            className={`inline-flex h-6 w-6 items-center justify-center rounded-md border border-border bg-canvas text-primary transition-colors hover:bg-surface outline-none ${focusRingClass}`}
-          >
-            <MoreHorizontal className="h-3.5 w-3.5" />
-          </button>
+          <Popover.Anchor asChild>
+            <button
+              ref={triggerRef}
+              type="button"
+              aria-label="More document tools"
+              aria-expanded={open}
+              aria-haspopup="menu"
+              onMouseDown={preserveEditorSelectionMouseDown}
+              onClick={(event) => {
+                event.preventDefault();
+                setOpen((value) => !value);
+              }}
+              className={`inline-flex h-6 w-6 items-center justify-center rounded-md border border-border bg-canvas text-primary transition-colors hover:bg-surface outline-none ${
+                open ? "text-accent ring-1 ring-accent/30 shadow-sm" : ""
+              } ${focusRingClass}`}
+            >
+              <MoreHorizontal className="h-3.5 w-3.5" />
+            </button>
+          </Popover.Anchor>
         </Tooltip.Trigger>
         <Tooltip.Portal>
           <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
@@ -1179,8 +1322,12 @@ function ToolbarCompactOverflow(props: {
           </Tooltip.Content>
         </Tooltip.Portal>
       </Tooltip.Root>
-      {open ? (
-        <div className="absolute left-0 top-9 z-50 w-[min(20rem,calc(100vw-2rem))] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border">
+      <ToolbarPortalMenu
+        anchorRef={triggerRef}
+        className="w-[min(20rem,calc(100vw-2rem))] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border"
+        menuWidthPx={320}
+        open={open}
+      >
           <div className="space-y-3">
             {props.showStyleSelectors ? (
               <div className="space-y-2">
@@ -1190,6 +1337,7 @@ function ToolbarCompactOverflow(props: {
                 <div className="grid gap-2">
                   <ToolbarParagraphStyleSelect
                     disabled={!props.canEdit || props.paragraphStyles.length === 0 || !props.onSetParagraphStyle}
+                    disabledReason={props.editDisabledReason}
                     styles={props.paragraphStyles}
                     value={props.formattingState?.paragraphStyleId}
                     onValueChange={(styleId) => {
@@ -1200,6 +1348,7 @@ function ToolbarCompactOverflow(props: {
                   <div className="grid grid-cols-2 gap-2">
                     <ToolbarFontFamilySelect
                       disabled={!props.canEdit || !props.onSetFontFamily}
+                      disabledReason={props.editDisabledReason}
                       value={props.formattingState?.fontFamily}
                       onValueChange={(fontFamily) => {
                         props.onSetFontFamily?.(fontFamily);
@@ -1208,6 +1357,7 @@ function ToolbarCompactOverflow(props: {
                     />
                     <ToolbarFontSizeSelect
                       disabled={!props.canEdit || !props.onSetFontSize}
+                      disabledReason={props.editDisabledReason}
                       value={props.formattingState?.fontSize}
                       onValueChange={(fontSize) => {
                         props.onSetFontSize?.(fontSize);
@@ -1227,6 +1377,7 @@ function ToolbarCompactOverflow(props: {
                 <ToolbarMenuButton
                   ariaLabel="Bulleted list"
                   disabled={!props.canEdit || !props.onToggleBulletedList}
+                  disabledReason={props.editDisabledReason}
                   icon={<List className="h-3.5 w-3.5" />}
                   label="Bulleted list"
                   onClick={() => {
@@ -1237,6 +1388,7 @@ function ToolbarCompactOverflow(props: {
                 <ToolbarMenuButton
                   ariaLabel="Numbered list"
                   disabled={!props.canEdit || !props.onToggleNumberedList}
+                  disabledReason={props.editDisabledReason}
                   icon={<Rows3 className="h-3.5 w-3.5" />}
                   label="Numbered list"
                   onClick={() => {
@@ -1257,6 +1409,7 @@ function ToolbarCompactOverflow(props: {
                     <ToolbarMenuButton
                       ariaLabel="Outdent"
                       disabled={!props.canEdit || !props.onOutdent}
+                      disabledReason={props.editDisabledReason}
                       icon={<Outdent className="h-3.5 w-3.5" />}
                       label="Outdent"
                       onClick={() => {
@@ -1267,6 +1420,7 @@ function ToolbarCompactOverflow(props: {
                     <ToolbarMenuButton
                       ariaLabel="Indent"
                       disabled={!props.canEdit || !props.onIndent}
+                      disabledReason={props.editDisabledReason}
                       icon={<Indent className="h-3.5 w-3.5" />}
                       label="Indent"
                       onClick={() => {
@@ -1281,6 +1435,7 @@ function ToolbarCompactOverflow(props: {
                   <ToolbarMenuButton
                     ariaLabel="Restart numbering"
                     disabled={!props.canEdit || !props.onRestartNumbering}
+                    disabledReason={props.editDisabledReason}
                     icon={<Rows3 className="h-3.5 w-3.5" />}
                     label="Restart numbering"
                     onClick={() => {
@@ -1291,6 +1446,7 @@ function ToolbarCompactOverflow(props: {
                   <ToolbarMenuButton
                     ariaLabel="Continue numbering"
                     disabled={!props.canEdit || !props.onContinueNumbering}
+                    disabledReason={props.editDisabledReason}
                     icon={<Rows3 className="h-3.5 w-3.5" />}
                     label="Continue numbering"
                     onClick={() => {
@@ -1311,6 +1467,7 @@ function ToolbarCompactOverflow(props: {
                 <ToolbarMenuButton
                   ariaLabel="Insert page break"
                   disabled={!props.canInsertStructural || !props.onInsertPageBreak}
+                  disabledReason={props.insertDisabledReason}
                   icon={<Minus className="h-3.5 w-3.5" />}
                   label="Page break"
                   onClick={() => {
@@ -1321,6 +1478,7 @@ function ToolbarCompactOverflow(props: {
                 <ToolbarMenuButton
                   ariaLabel="Insert table"
                   disabled={!props.canInsertStructural || !props.onInsertTable}
+                  disabledReason={props.insertDisabledReason}
                   icon={<Rows3 className="h-3.5 w-3.5" />}
                   label="Table"
                   onClick={() => {
@@ -1329,6 +1487,16 @@ function ToolbarCompactOverflow(props: {
                   }}
                 />
                 <label
+                  title={
+                    !props.canInsertStructural && props.insertDisabledReason
+                      ? `Not available: ${props.insertDisabledReason}`
+                      : undefined
+                  }
+                  data-disabled-reason={
+                    !props.canInsertStructural && props.insertDisabledReason
+                      ? props.insertDisabledReason
+                      : undefined
+                  }
                   className={`flex h-7 cursor-pointer items-center gap-2 rounded-md px-2 text-left text-[11px] font-medium text-primary transition-colors hover:bg-surface ${
                     !props.canInsertStructural || !props.onInsertImage ? "pointer-events-none opacity-40" : ""
                   }`}
@@ -1349,6 +1517,7 @@ function ToolbarCompactOverflow(props: {
                 <ToolbarMenuButton
                   ariaLabel="Insert next-page section break"
                   disabled={!props.canInsertStructural || !props.onInsertSectionBreak}
+                  disabledReason={props.insertDisabledReason}
                   icon={<FileText className="h-3.5 w-3.5" />}
                   label="Next-page section break"
                   onClick={() => {
@@ -1367,6 +1536,7 @@ function ToolbarCompactOverflow(props: {
                 <ToolbarMenuButton
                   ariaLabel="Refresh fields"
                   disabled={!props.canEdit || !props.onUpdateFields}
+                  disabledReason={props.editDisabledReason}
                   icon={<RotateCcw className="h-3.5 w-3.5" />}
                   label="Fields"
                   onClick={() => {
@@ -1377,6 +1547,7 @@ function ToolbarCompactOverflow(props: {
                 <ToolbarMenuButton
                   ariaLabel="Refresh table of contents"
                   disabled={!props.canEdit || !props.onUpdateTableOfContents}
+                  disabledReason={props.editDisabledReason}
                   icon={<RotateCcw className="h-3.5 w-3.5" />}
                   label="Table of contents"
                   onClick={() => {
@@ -1387,36 +1558,50 @@ function ToolbarCompactOverflow(props: {
               </div>
             ) : null}
           </div>
-        </div>
-      ) : null}
-    </div>
+      </ToolbarPortalMenu>
+    </Popover.Root>
   );
 }
 
 function ToolbarFormattingOverflow(props: {
   disabled: boolean;
+  disabledReason?: string;
   formattingState?: FormattingStateSnapshot;
   onToggleStrikethrough?: () => void;
   onToggleSuperscript?: () => void;
   onToggleSubscript?: () => void;
 }) {
   const [open, setOpen] = React.useState(false);
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
+  const disabledTitle =
+    props.disabled && props.disabledReason ? `Not available: ${props.disabledReason}` : undefined;
 
   return (
-    <div className="relative">
+    <Popover.Root open={open} onOpenChange={setOpen}>
       <Tooltip.Root>
         <Tooltip.Trigger asChild>
-          <button
-            type="button"
-            aria-label="More text formatting"
-            aria-expanded={open}
-            disabled={props.disabled}
-            onMouseDown={preserveEditorSelectionMouseDown}
-            onClick={() => setOpen((value) => !value)}
-            className={`inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
-          >
-            <MoreHorizontal className="h-3.5 w-3.5" />
-          </button>
+          <Popover.Anchor asChild>
+            <button
+              ref={triggerRef}
+              type="button"
+              aria-label="More text formatting"
+              aria-expanded={open}
+              aria-haspopup="menu"
+              data-disabled-reason={props.disabled && props.disabledReason ? props.disabledReason : undefined}
+              disabled={props.disabled}
+              title={disabledTitle}
+              onMouseDown={preserveEditorSelectionMouseDown}
+              onClick={(event) => {
+                event.preventDefault();
+                setOpen((value) => !value);
+              }}
+              className={`inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${
+                open ? "bg-canvas text-accent ring-1 ring-accent/30 shadow-sm" : ""
+              } ${focusRingClass}`}
+            >
+              <MoreHorizontal className="h-3.5 w-3.5" />
+            </button>
+          </Popover.Anchor>
         </Tooltip.Trigger>
         <Tooltip.Portal>
           <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
@@ -1424,8 +1609,12 @@ function ToolbarFormattingOverflow(props: {
           </Tooltip.Content>
         </Tooltip.Portal>
       </Tooltip.Root>
-      {open ? (
-        <div className="absolute left-0 top-9 z-50 w-[220px] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border">
+      <ToolbarPortalMenu
+        anchorRef={triggerRef}
+        className="w-[220px] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border"
+        menuWidthPx={220}
+        open={open}
+      >
           <div className="mb-1 px-1 text-[10px] font-semibold uppercase tracking-[0.12em] text-tertiary">
             Text styling
           </div>
@@ -1434,6 +1623,7 @@ function ToolbarFormattingOverflow(props: {
               active={props.formattingState?.strikethrough ?? false}
               ariaLabel="Strikethrough"
               disabled={props.disabled || !props.onToggleStrikethrough}
+              disabledReason={props.disabledReason}
               icon={<Strikethrough className="h-3.5 w-3.5" />}
               onClick={() => {
                 props.onToggleStrikethrough?.();
@@ -1444,6 +1634,7 @@ function ToolbarFormattingOverflow(props: {
               active={props.formattingState?.superscript ?? false}
               ariaLabel="Superscript"
               disabled={props.disabled || !props.onToggleSuperscript}
+              disabledReason={props.disabledReason}
               icon={<Superscript className="h-3.5 w-3.5" />}
               onClick={() => {
                 props.onToggleSuperscript?.();
@@ -1454,6 +1645,7 @@ function ToolbarFormattingOverflow(props: {
               active={props.formattingState?.subscript ?? false}
               ariaLabel="Subscript"
               disabled={props.disabled || !props.onToggleSubscript}
+              disabledReason={props.disabledReason}
               icon={<Subscript className="h-3.5 w-3.5" />}
               onClick={() => {
                 props.onToggleSubscript?.();
@@ -1461,9 +1653,8 @@ function ToolbarFormattingOverflow(props: {
               }}
             />
           </div>
-        </div>
-      ) : null}
-    </div>
+      </ToolbarPortalMenu>
+    </Popover.Root>
   );
 }
 
@@ -1471,27 +1662,44 @@ function ToolbarColorPopover(props: {
   ariaLabel: string;
   colors: ReadonlyArray<{ value: string | null; label: string }>;
   disabled: boolean;
+  disabledReason?: string;
   icon: React.ReactNode;
+  activeValue?: string | null;
   title: string;
   onSelect: (value: string | null) => void;
 }) {
   const [open, setOpen] = React.useState(false);
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
+  const activeValue = props.activeValue?.toLowerCase() ?? null;
+  const disabledTitle =
+    props.disabled && props.disabledReason ? `Not available: ${props.disabledReason}` : undefined;
 
   return (
-    <div className="relative">
+    <Popover.Root open={open} onOpenChange={setOpen}>
       <Tooltip.Root>
         <Tooltip.Trigger asChild>
-          <button
-            type="button"
-            aria-label={props.ariaLabel}
-            aria-expanded={open}
-            disabled={props.disabled}
-            onMouseDown={preserveEditorSelectionMouseDown}
-            onClick={() => setOpen((value) => !value)}
-            className={`inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
-          >
-            {props.icon}
-          </button>
+          <Popover.Anchor asChild>
+            <button
+              ref={triggerRef}
+              type="button"
+              aria-label={props.ariaLabel}
+              aria-expanded={open}
+              aria-haspopup="menu"
+              data-disabled-reason={props.disabled && props.disabledReason ? props.disabledReason : undefined}
+              disabled={props.disabled}
+              title={disabledTitle}
+              onMouseDown={preserveEditorSelectionMouseDown}
+              onClick={(event) => {
+                event.preventDefault();
+                setOpen((value) => !value);
+              }}
+              className={`inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${
+                open ? "bg-canvas text-accent ring-1 ring-accent/30 shadow-sm" : ""
+              } ${focusRingClass}`}
+            >
+              {props.icon}
+            </button>
+          </Popover.Anchor>
         </Tooltip.Trigger>
         <Tooltip.Portal>
           <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
@@ -1499,44 +1707,59 @@ function ToolbarColorPopover(props: {
           </Tooltip.Content>
         </Tooltip.Portal>
       </Tooltip.Root>
-      {open ? (
-        <div className="absolute left-0 top-9 z-50 w-[180px] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border">
+      <ToolbarPortalMenu
+        anchorRef={triggerRef}
+        className="w-[180px] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border"
+        menuWidthPx={180}
+        open={open}
+      >
           <div className="mb-1 px-1 text-[10px] font-semibold uppercase tracking-[0.12em] text-tertiary">
             {props.title}
           </div>
           <div className="grid grid-cols-3 gap-1">
-            {props.colors.map((color) => (
-              <button
-                key={`${props.ariaLabel}-${color.label}`}
-                type="button"
-                aria-label={`${props.title} ${color.label}`}
-                disabled={props.disabled}
-                onMouseDown={preserveEditorSelectionMouseDown}
-                onClick={() => {
-                  props.onSelect(color.value);
-                  setOpen(false);
-                }}
-                className={`inline-flex h-7 items-center justify-center rounded-md border border-border text-[10px] font-medium text-primary transition-transform hover:scale-[1.04] disabled:cursor-not-allowed disabled:opacity-40 ${
-                  color.value ? "" : "bg-surface"
-                } ${focusRingClass}`}
-                style={color.value ? { backgroundColor: color.value } : undefined}
-              >
-                {color.value ? <span className="sr-only">{color.label}</span> : "None"}
-              </button>
-            ))}
+            {props.colors.map((color) => {
+              const normalizedValue = color.value?.toLowerCase() ?? null;
+              const isActive = normalizedValue === activeValue;
+              return (
+                <button
+                  key={`${props.ariaLabel}-${color.label}`}
+                  type="button"
+                  aria-label={`${props.title} ${color.label}`}
+                  aria-pressed={isActive}
+                  data-active={isActive ? "true" : undefined}
+                  disabled={props.disabled}
+                  onMouseDown={preserveEditorSelectionMouseDown}
+                  onClick={() => {
+                    props.onSelect(color.value);
+                    setOpen(false);
+                  }}
+                  className={`inline-flex h-7 items-center justify-center rounded-md border text-[10px] font-medium text-primary transition-transform hover:scale-[1.04] disabled:cursor-not-allowed disabled:opacity-40 ${
+                    isActive
+                      ? "border-accent ring-2 ring-accent/35 shadow-sm"
+                      : "border-border"
+                  } ${color.value ? "" : "bg-surface"} ${focusRingClass}`}
+                  style={color.value ? { backgroundColor: color.value } : undefined}
+                >
+                  {color.value ? <span className="sr-only">{color.label}</span> : "None"}
+                </button>
+              );
+            })}
           </div>
-        </div>
-      ) : null}
-    </div>
+      </ToolbarPortalMenu>
+    </Popover.Root>
   );
 }
 
 function ToolbarAlignmentPopover(props: {
   activeAlignment?: FormattingAlignment;
   disabled: boolean;
+  disabledReason?: string;
   onSelect: (alignment: FormattingAlignment) => void;
 }) {
   const [open, setOpen] = React.useState(false);
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
+  const disabledTitle =
+    props.disabled && props.disabledReason ? `Not available: ${props.disabledReason}` : undefined;
   const alignments = [
     { value: "left" as const, label: "Align left", icon: <AlignLeft className="h-3.5 w-3.5" /> },
     { value: "center" as const, label: "Align center", icon: <AlignCenter className="h-3.5 w-3.5" /> },
@@ -1545,20 +1768,31 @@ function ToolbarAlignmentPopover(props: {
   ];
 
   return (
-    <div className="relative">
+    <Popover.Root open={open} onOpenChange={setOpen}>
       <Tooltip.Root>
         <Tooltip.Trigger asChild>
-          <button
-            type="button"
-            aria-label="Paragraph alignment"
-            aria-expanded={open}
-            disabled={props.disabled}
-            onMouseDown={preserveEditorSelectionMouseDown}
-            onClick={() => setOpen((value) => !value)}
-            className={`inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
-          >
-            {(alignments.find((entry) => entry.value === props.activeAlignment) ?? alignments[0])?.icon}
-          </button>
+          <Popover.Anchor asChild>
+            <button
+              ref={triggerRef}
+              type="button"
+              aria-label="Paragraph alignment"
+              aria-expanded={open}
+              aria-haspopup="menu"
+              data-disabled-reason={props.disabled && props.disabledReason ? props.disabledReason : undefined}
+              disabled={props.disabled}
+              title={disabledTitle}
+              onMouseDown={preserveEditorSelectionMouseDown}
+              onClick={(event) => {
+                event.preventDefault();
+                setOpen((value) => !value);
+              }}
+              className={`inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${
+                open ? "bg-canvas text-accent ring-1 ring-accent/30 shadow-sm" : ""
+              } ${focusRingClass}`}
+            >
+              {(alignments.find((entry) => entry.value === props.activeAlignment) ?? alignments[0])?.icon}
+            </button>
+          </Popover.Anchor>
         </Tooltip.Trigger>
         <Tooltip.Portal>
           <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
@@ -1566,8 +1800,12 @@ function ToolbarAlignmentPopover(props: {
           </Tooltip.Content>
         </Tooltip.Portal>
       </Tooltip.Root>
-      {open ? (
-        <div className="absolute left-0 top-9 z-50 w-[220px] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border">
+      <ToolbarPortalMenu
+        anchorRef={triggerRef}
+        className="w-[220px] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border"
+        menuWidthPx={220}
+        open={open}
+      >
           <div className="mb-1 px-1 text-[10px] font-semibold uppercase tracking-[0.12em] text-tertiary">
             Paragraph alignment
           </div>
@@ -1578,6 +1816,7 @@ function ToolbarAlignmentPopover(props: {
                 active={props.activeAlignment === entry.value}
                 ariaLabel={entry.label}
                 disabled={props.disabled}
+                disabledReason={props.disabledReason}
                 icon={entry.icon}
                 onClick={() => {
                   props.onSelect(entry.value);
@@ -1586,14 +1825,14 @@ function ToolbarAlignmentPopover(props: {
               />
             ))}
           </div>
-        </div>
-      ) : null}
-    </div>
+      </ToolbarPortalMenu>
+    </Popover.Root>
   );
 }
 
 function ToolbarInsertMenu(props: {
   disabled: boolean;
+  disabledReason?: string;
   /**
    * Lane 6b §6b.U3 — optional per-item disabled-explanation reasons.
    * When the item is disabled (no handler or policy-gated), hovering it
@@ -1611,6 +1850,9 @@ function ToolbarInsertMenu(props: {
   onInsertImage?: (options: InsertImageOptions) => void;
 }) {
   const [open, setOpen] = React.useState(false);
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
+  const disabledTitle =
+    props.disabled && props.disabledReason ? `Not available: ${props.disabledReason}` : undefined;
 
   async function handleImageChange(event: React.ChangeEvent<HTMLInputElement>): Promise<void> {
     const file = event.target.files?.[0];
@@ -1629,21 +1871,32 @@ function ToolbarInsertMenu(props: {
   }
 
   return (
-    <div className="relative">
+    <Popover.Root open={open} onOpenChange={setOpen}>
       <Tooltip.Root>
         <Tooltip.Trigger asChild>
-          <button
-            type="button"
-            aria-label="Insert"
-            aria-expanded={open}
-            disabled={props.disabled}
-            onMouseDown={preserveEditorSelectionMouseDown}
-            onClick={() => setOpen((value) => !value)}
-            className={`inline-flex h-6 items-center gap-1 rounded-md border border-border bg-canvas px-2 text-[11px] font-medium text-primary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}
-          >
-            Insert
-            <ChevronDown className="h-3.5 w-3.5 text-tertiary" />
-          </button>
+          <Popover.Anchor asChild>
+            <button
+              ref={triggerRef}
+              type="button"
+              aria-label="Insert"
+              aria-expanded={open}
+              aria-haspopup="menu"
+              data-disabled-reason={props.disabled && props.disabledReason ? props.disabledReason : undefined}
+              disabled={props.disabled}
+              title={disabledTitle}
+              onMouseDown={preserveEditorSelectionMouseDown}
+              onClick={(event) => {
+                event.preventDefault();
+                setOpen((value) => !value);
+              }}
+              className={`inline-flex h-6 items-center gap-1 rounded-md border border-border bg-canvas px-2 text-[11px] font-medium text-primary transition-colors hover:bg-surface outline-none disabled:cursor-not-allowed disabled:opacity-40 ${
+                open ? "text-accent ring-1 ring-accent/30 shadow-sm" : ""
+              } ${focusRingClass}`}
+            >
+              Insert
+              <ChevronDown className="h-3.5 w-3.5 text-tertiary" />
+            </button>
+          </Popover.Anchor>
         </Tooltip.Trigger>
         <Tooltip.Portal>
           <Tooltip.Content className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50" sideOffset={6}>
@@ -1651,13 +1904,17 @@ function ToolbarInsertMenu(props: {
           </Tooltip.Content>
         </Tooltip.Portal>
       </Tooltip.Root>
-      {open ? (
-        <div className="absolute left-0 top-9 z-50 w-[220px] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border">
+      <ToolbarPortalMenu
+        anchorRef={triggerRef}
+        className="w-[220px] rounded-lg bg-canvas p-2 shadow-lg ring-1 ring-border"
+        menuWidthPx={220}
+        open={open}
+      >
           <div className="space-y-1">
             <ToolbarMenuButton
               ariaLabel="Insert page break"
               disabled={props.disabled || !props.onInsertPageBreak}
-              disabledReason={props.disabledReasons?.pageBreak}
+              disabledReason={props.disabled ? props.disabledReason : props.disabledReasons?.pageBreak}
               icon={<Minus className="h-3.5 w-3.5" />}
               label="Page break"
               onClick={() => {
@@ -1668,7 +1925,7 @@ function ToolbarInsertMenu(props: {
             <ToolbarMenuButton
               ariaLabel="Insert table"
               disabled={props.disabled || !props.onInsertTable}
-              disabledReason={props.disabledReasons?.table}
+              disabledReason={props.disabled ? props.disabledReason : props.disabledReasons?.table}
               icon={<Rows3 className="h-3.5 w-3.5" />}
               label="Table"
               onClick={() => {
@@ -1677,6 +1934,21 @@ function ToolbarInsertMenu(props: {
               }}
             />
             <label
+              aria-disabled={props.disabled || !props.onInsertImage ? "true" : undefined}
+              title={
+                props.disabled
+                  ? disabledTitle
+                  : !props.onInsertImage && props.disabledReasons?.image
+                    ? `Not available: ${props.disabledReasons.image}`
+                    : undefined
+              }
+              data-disabled-reason={
+                props.disabled
+                  ? props.disabledReason
+                  : !props.onInsertImage
+                    ? props.disabledReasons?.image
+                    : undefined
+              }
               className={`flex h-7 cursor-pointer items-center gap-2 rounded-md px-2 text-[11px] font-medium text-primary transition-colors hover:bg-surface ${
                 props.disabled || !props.onInsertImage ? "pointer-events-none opacity-40" : ""
               }`}
@@ -1697,7 +1969,7 @@ function ToolbarInsertMenu(props: {
             <ToolbarMenuButton
               ariaLabel="Insert next-page section break"
               disabled={props.disabled || !props.onInsertSectionBreak}
-              disabledReason={props.disabledReasons?.sectionBreak}
+              disabledReason={props.disabled ? props.disabledReason : props.disabledReasons?.sectionBreak}
               icon={<FileText className="h-3.5 w-3.5" />}
               label="Next-page section break"
               onClick={() => {
@@ -1706,9 +1978,8 @@ function ToolbarInsertMenu(props: {
               }}
             />
           </div>
-        </div>
-      ) : null}
-    </div>
+      </ToolbarPortalMenu>
+    </Popover.Root>
   );
 }
 
@@ -1716,15 +1987,24 @@ function ToolbarPopoverActionButton(props: {
   active: boolean;
   ariaLabel: string;
   disabled: boolean;
+  disabledReason?: string;
   icon: React.ReactNode;
   onClick?: () => void;
 }) {
+  const titleAttr =
+    props.disabled && props.disabledReason
+      ? `Not available: ${props.disabledReason}`
+      : undefined;
   return (
     <button
       type="button"
       aria-label={props.ariaLabel}
       aria-pressed={props.active}
       disabled={props.disabled}
+      title={titleAttr}
+      data-disabled-reason={
+        props.disabled && props.disabledReason ? props.disabledReason : undefined
+      }
       onMouseDown={preserveEditorSelectionMouseDown}
       onClick={props.onClick}
       className={`inline-flex h-7 items-center justify-center rounded-md border border-border transition-colors disabled:cursor-not-allowed disabled:opacity-40 ${