@beyondwork/docx-react-component 1.0.53 → 1.0.55

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

@@ -4,15 +4,20 @@ import * as Tabs from "@radix-ui/react-tabs";
 /**
  * TwShellHeader — the top "app chrome" bar above the document canvas.
  *
- * Anatomy matches the editorial reference mock:
+ * Designsystem §6.1 — three subregions on a single 48-px row:
  *   ┌─────────────────────────────────────────────────────────────────────┐
- *   │  [brand]        Edit | Review | Workflow | More          [⋯] [CTA] │
+ *   │ LEFT          │          CENTER           │               RIGHT     │
+ *   │ brand + slot  │ mode tabs (always-on)     │ icon actions + CTA      │
  *   └─────────────────────────────────────────────────────────────────────┘
  *
- * All three regions are optional slots — hosts opt in by supplying the
- * corresponding prop.  When nothing is supplied the header renders empty but
- * preserves layout height so the document canvas does not jump when a CTA
- * appears.
+ * Layout is CSS-grid `grid-cols-[1fr_auto_1fr]` so the center zone is
+ * always visually centred regardless of left / right slot width.  The
+ * 4-mode switcher (edit / review / workflow / more) renders
+ * unconditionally — Lane 6b §6b.S1 flips it from opt-in to always-on.
+ *
+ * All colors, shadows, radius, and motion bind to the Lane 6a token
+ * substrate (`var(--color-*)` / `var(--shadow-*)` / `var(--radius-*)` /
+ * `var(--motion-*)`) — no hex literals or legacy Tailwind palette names.
  */
 
 export type ShellHeaderMode = "edit" | "review" | "workflow" | "more";
@@ -40,6 +45,10 @@ export interface ShellHeaderIconAction {
 
 export interface TwShellHeaderProps {
   brand?: ReactNode;
+  /**
+   * Mode tab options.  When omitted, a default 4-mode set is rendered so
+   * the center subregion always has tabs per designsystem §6.1.
+   */
   modes?: readonly ShellHeaderModeOption[];
   activeMode?: ShellHeaderMode;
   onModeChange?: (mode: ShellHeaderMode) => void;
@@ -50,23 +59,33 @@ export interface TwShellHeaderProps {
   className?: string;
 }
 
-const focusRingClass =
-  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-canvas";
+/**
+ * Default 4-mode set — designsystem §6.1.  Exported so hosts can extend
+ * / relabel without reconstructing the whole list.
+ */
+export const DEFAULT_SHELL_HEADER_MODES: readonly ShellHeaderModeOption[] = [
+  { id: "edit", label: "Edit" },
+  { id: "review", label: "Review" },
+  { id: "workflow", label: "Workflow" },
+  { id: "more", label: "More" },
+];
 
-export function TwShellHeader(props: TwShellHeaderProps) {
-  const hasContent =
-    props.brand ||
-    (props.modes && props.modes.length > 0) ||
-    (props.iconActions && props.iconActions.length > 0) ||
-    props.primaryAction;
+const focusRingClass =
+  "focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)]";
 
-  if (!hasContent) {
-    return null;
-  }
+export function TwShellHeader(props: TwShellHeaderProps): React.ReactElement {
+  const modes =
+    props.modes && props.modes.length > 0
+      ? props.modes
+      : DEFAULT_SHELL_HEADER_MODES;
+  const activeMode: ShellHeaderMode = props.activeMode ?? modes[0]!.id;
 
   const className = [
-    "flex h-12 shrink-0 items-center justify-between gap-4 px-4 bg-canvas/92 backdrop-blur-sm",
-    props.isScrolled ? "border-b border-border" : "border-b border-transparent",
+    "grid h-12 shrink-0 grid-cols-[1fr_auto_1fr] items-center gap-2 px-4",
+    "bg-[var(--color-bg-chrome)]/92 backdrop-blur-sm",
+    props.isScrolled
+      ? "border-b border-[var(--color-border-subtle)]"
+      : "border-b border-transparent",
     "transition-colors duration-[var(--motion-fast)]",
     props.className,
   ]
@@ -75,10 +94,15 @@ export function TwShellHeader(props: TwShellHeaderProps) {
 
   return (
     <header className={className} data-testid="tw-shell-header">
-      <div className="flex min-w-0 items-center gap-3">
+      {/* LEFT: brand + host-supplied slot */}
+      <div
+        className="flex min-w-0 items-center gap-3"
+        data-region="left"
+        data-testid="tw-shell-header__region-left"
+      >
         {props.brand ? (
           <div
-            className="font-[family-name:var(--font-legal-serif)] text-[15px] font-semibold text-primary truncate"
+            className="truncate font-[family-name:var(--font-legal-serif)] text-[15px] font-semibold text-[var(--color-text-primary)]"
             data-testid="tw-shell-header__brand"
           >
             {props.brand}
@@ -86,9 +110,14 @@ export function TwShellHeader(props: TwShellHeaderProps) {
         ) : null}
       </div>
 
-      {props.modes && props.modes.length > 0 && props.activeMode ? (
+      {/* CENTER: mode tabs (always on) */}
+      <div
+        className="flex items-center justify-center"
+        data-region="center"
+        data-testid="tw-shell-header__region-center"
+      >
         <Tabs.Root
-          value={props.activeMode}
+          value={activeMode}
           onValueChange={(v: string) =>
             props.onModeChange?.(v as ShellHeaderMode)
           }
@@ -97,7 +126,7 @@ export function TwShellHeader(props: TwShellHeaderProps) {
             aria-label="Workspace modes"
             className="flex items-center gap-1"
           >
-            {props.modes.map((mode) => (
+            {modes.map((mode) => (
               <Tabs.Trigger
                 key={mode.id}
                 value={mode.id}
@@ -110,17 +139,26 @@ export function TwShellHeader(props: TwShellHeaderProps) {
             ))}
           </Tabs.List>
         </Tabs.Root>
-      ) : (
-        <div aria-hidden="true" />
-      )}
+      </div>
 
-      <div className="flex items-center gap-1">
+      {/* RIGHT: icon actions + primary CTA */}
+      <div
+        className="flex items-center justify-end gap-1"
+        data-region="right"
+        data-testid="tw-shell-header__region-right"
+      >
         {props.iconActions?.map((action) => {
           const commonProps = {
             key: action.id,
             "aria-label": action.label,
             title: action.label,
-            className: `inline-flex h-8 w-8 items-center justify-center rounded-sm text-secondary transition-colors hover:bg-surface-hover hover:text-primary ${focusRingClass}`,
+            className: [
+              "inline-flex h-8 w-8 items-center justify-center rounded-[var(--radius-sm)]",
+              "text-[var(--color-text-secondary)]",
+              "transition-colors duration-[var(--motion-fast)]",
+              "hover:bg-[var(--color-bg-hover)] hover:text-[var(--color-text-primary)]",
+              focusRingClass,
+            ].join(" "),
           } as const;
 
           if (action.href) {
@@ -145,10 +183,13 @@ export function TwShellHeader(props: TwShellHeaderProps) {
             onClick={props.primaryAction.onClick}
             data-tone={props.primaryAction.tone ?? "accent"}
             className={[
-              "ml-2 inline-flex h-8 items-center rounded-sm px-3 text-xs font-semibold transition-colors disabled:opacity-40",
+              "ml-2 inline-flex h-8 items-center rounded-[var(--radius-sm)] px-3",
+              "text-xs font-semibold",
+              "transition-colors duration-[var(--motion-fast)]",
+              "disabled:opacity-40",
               props.primaryAction.tone === "neutral"
-                ? "bg-surface text-primary hover:bg-surface-hover"
-                : "bg-accent text-white hover:bg-[color-mix(in_srgb,var(--color-accent)_85%,#000)]",
+                ? "bg-[var(--color-bg-muted)] text-[var(--color-text-primary)] hover:bg-[var(--color-bg-hover)]"
+                : "bg-[var(--color-accent-primary)] text-[var(--color-text-on-accent)] hover:bg-[var(--color-accent-primary-hover)]",
               focusRingClass,
             ].join(" ")}
             data-testid="tw-shell-header__primary-action"

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

@@ -7,13 +7,31 @@ export interface TwToolbarIconButtonProps {
   icon: React.ComponentType<{ className?: string }>;
   label: string;
   disabled?: boolean;
+  /**
+   * Active / pressed state.  Designsystem §6.2 + Lane 6b §6b.S2: active
+   * buttons paint an accent-soft tint with an accent border ring — NOT a
+   * filled accent CTA.  The filled-CTA grammar is reserved for the shell
+   * header primary action only.
+   */
   active?: boolean;
+  /**
+   * Emphasis variant — used for "stand-out" toolbar items (e.g. a pinned
+   * AI action).  Paints the accent glyph color at rest; still tints on
+   * hover and on active.
+   */
   emphasis?: boolean;
+  /**
+   * Lane 6b §6b.U6 — optional keyboard-shortcut hint rendered as a small
+   * `<kbd>` chip to the right of the label inside the tooltip.  Use
+   * platform-agnostic symbols (⌘, ⇧, ⌥, ⌃) — callers format for macOS
+   * vs. Windows however they like.
+   */
+  shortcut?: string;
   onClick?: () => void;
 }
 
 const focusRingClass =
-  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
+  "focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)]";
 
 export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
   return (
@@ -22,17 +40,22 @@ export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
         <button
           type="button"
           aria-label={props.label}
+          aria-pressed={props.active ?? undefined}
+          data-active={props.active ? "true" : undefined}
           disabled={props.disabled}
           onMouseDown={preserveEditorSelectionMouseDown}
           onClick={props.onClick}
           className={[
-            "inline-flex h-6 w-6 items-center justify-center rounded-md border border-transparent transition-colors outline-none",
+            "inline-flex h-6 w-6 items-center justify-center rounded-[var(--radius-sm)]",
+            "border border-transparent outline-none",
+            "transition-colors duration-[var(--motion-fast)]",
             "disabled:opacity-30 disabled:cursor-not-allowed",
-            props.emphasis
-              ? "text-accent hover:border-border/60 hover:bg-surface"
-              : props.active
-                ? "border-border/70 bg-surface text-accent shadow-[0_4px_12px_-10px_var(--color-shadow-strong)]"
-                : "text-secondary hover:border-border/60 hover:bg-surface hover:text-primary",
+            props.active
+              ? // Active = underline-tint grammar: accent-soft fill, accent-primary glyph, accent border ring.
+                "bg-[var(--color-accent-soft)] text-[var(--color-accent-primary)] border-[var(--color-border-accent)]"
+              : props.emphasis
+                ? "text-[var(--color-accent-primary)] hover:bg-[var(--color-bg-hover)] hover:border-[var(--color-border-subtle)]"
+                : "text-[var(--color-text-secondary)] hover:bg-[var(--color-bg-hover)] hover:text-[var(--color-text-primary)] hover:border-[var(--color-border-subtle)]",
             focusRingClass,
           ].join(" ")}
         >
@@ -41,10 +64,27 @@ export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
       </Tooltip.Trigger>
       <Tooltip.Portal>
         <Tooltip.Content
-          className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50"
+          className={[
+            "inline-flex items-center gap-2 rounded-[var(--radius-sm)] px-2 py-1 text-xs z-50",
+            "bg-[var(--color-text-primary)] text-[var(--color-text-inverse)]",
+            "shadow-[var(--shadow-soft)]",
+          ].join(" ")}
           sideOffset={6}
         >
-          {props.label}
+          <span>{props.label}</span>
+          {props.shortcut ? (
+            <kbd
+              className={[
+                "inline-flex items-center rounded-[var(--radius-sm)]",
+                "px-1 py-0.5 font-sans text-[10px] font-medium",
+                "border border-[var(--color-border-subtle)]/40",
+                "bg-[var(--color-bg-overlay)] text-[var(--color-text-inverse)]/80",
+              ].join(" ")}
+              data-testid="tw-toolbar-icon-button__shortcut"
+            >
+              {props.shortcut}
+            </kbd>
+          ) : null}
         </Tooltip.Content>
       </Tooltip.Portal>
     </Tooltip.Root>

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

@@ -174,6 +174,40 @@ export interface TwToolbarProps {
   chromePins?: ChromePinsState;
   /** Called when the user detaches or re-attaches the topnav. */
   onChromePinChange?: (surface: ChromePinSurface, pin: PinState | null) => void;
+
+  /**
+   * Lane 6b §6b.U1 — unread count badges on the sidebar toggle when the
+   * review rail is closed.  Hosts pass summed open-comment / open-change
+   * counts from the runtime snapshot; the badge only shows when
+   * `isSidebarOpen === false` and `(openCommentCount + openChangeCount) > 0`.
+   */
+  openCommentCount?: number;
+  openChangeCount?: number;
+
+  /**
+   * Lane 6b §6b.U2 — mixed-value grammar for the three style / font
+   * dropdowns.  When `true`, the trigger renders italic "Mixed" instead
+   * of the current value (selection spans different values).  Hosts
+   * compute this from whatever mixed-selection signal their runtime
+   * exposes; undefined keeps today's single-value behaviour.
+   */
+  hasMixedParagraphStyle?: boolean;
+  hasMixedFontFamily?: boolean;
+  hasMixedFontSize?: boolean;
+
+  /**
+   * Lane 6b §6b.U3 — per-item disabled-explanation reasons for the
+   * Insert menu.  When the item is disabled (either because its handler
+   * is undefined or because `canInsertStructural` is false), hovering
+   * it surfaces `title="Not available: {reason}"` so the user understands
+   * WHY the capability is missing in the current context.
+   */
+  insertDisabledReasons?: {
+    pageBreak?: string;
+    table?: string;
+    image?: string;
+    sectionBreak?: string;
+  };
 }
 
 export interface ToolbarInteractionPolicy {
@@ -275,11 +309,26 @@ export function TwToolbar(props: TwToolbarProps) {
 
   return (
     <header
+      data-testid="tw-toolbar"
+      style={
+        isCompact
+          ? undefined
+          : {
+              // Lane 6b §6b.U5 — density opt-in.  Scales the 40 px base
+              // by `--space-density-multiplier` so `data-density="compact"`
+              // shrinks the toolbar to ~34 px and `comfortable` expands
+              // it to ~46 px.  Wrap mode keeps flex-wrap semantics in
+              // compact viewports.
+              height:
+                "calc(40px * var(--space-density-multiplier, 1))",
+            }
+      }
       className={[
-        "shrink-0 rounded-xl border border-border/70 bg-canvas/92 px-2.5 shadow-[0_8px_20px_-18px_var(--color-shadow-strong)] backdrop-blur-sm",
+        "shrink-0 rounded-[var(--radius-sm)] border border-[var(--color-border-subtle)]",
+        "bg-[var(--color-bg-chrome)]/92 px-2.5 shadow-[var(--shadow-soft)] backdrop-blur-sm",
         isCompact
           ? "flex min-h-10 flex-wrap items-center gap-1.5 py-1.5"
-          : "flex h-10 items-center gap-1",
+          : "flex items-center gap-1",
       ].join(" ")}
     >
       {/* Left cluster: undo/redo + formatting */}
@@ -287,12 +336,14 @@ export function TwToolbar(props: TwToolbarProps) {
         <TwToolbarIconButton
           icon={Undo2}
           label="Undo"
+          shortcut="⌘Z"
           disabled={caps ? !caps.canUndo : true}
           onClick={props.onUndo}
         />
         <TwToolbarIconButton
           icon={Redo2}
           label="Redo"
+          shortcut="⌘⇧Z"
           disabled={caps ? !caps.canRedo : true}
           onClick={props.onRedo}
         />
@@ -304,17 +355,20 @@ export function TwToolbar(props: TwToolbarProps) {
               disabled={!canEdit || paragraphStyles.length === 0 || !props.onSetParagraphStyle}
               styles={paragraphStyles}
               value={props.formattingState?.paragraphStyleId}
+              hasMixedValue={props.hasMixedParagraphStyle ?? false}
               onValueChange={props.onSetParagraphStyle}
             />
 
             <ToolbarFontFamilySelect
               disabled={!canEdit || !props.onSetFontFamily}
               value={props.formattingState?.fontFamily}
+              hasMixedValue={props.hasMixedFontFamily ?? false}
               onValueChange={props.onSetFontFamily}
             />
             <ToolbarFontSizeSelect
               disabled={!canEdit || !props.onSetFontSize}
               value={props.formattingState?.fontSize}
+              hasMixedValue={props.hasMixedFontSize ?? false}
               onValueChange={props.onSetFontSize}
             />
 
@@ -327,6 +381,7 @@ export function TwToolbar(props: TwToolbarProps) {
             <TwToolbarIconButton
               icon={Bold}
               label="Bold"
+              shortcut="⌘B"
               active={props.formattingState?.bold ?? false}
               disabled={!canEdit}
               onClick={props.onToggleBold}
@@ -334,6 +389,7 @@ export function TwToolbar(props: TwToolbarProps) {
             <TwToolbarIconButton
               icon={Italic}
               label="Italic"
+              shortcut="⌘I"
               active={props.formattingState?.italic ?? false}
               disabled={!canEdit}
               onClick={props.onToggleItalic}
@@ -341,6 +397,7 @@ export function TwToolbar(props: TwToolbarProps) {
             <TwToolbarIconButton
               icon={Underline}
               label="Underline"
+              shortcut="⌘U"
               active={props.formattingState?.underline ?? false}
               disabled={!canEdit}
               onClick={props.onToggleUnderline}
@@ -455,6 +512,7 @@ export function TwToolbar(props: TwToolbarProps) {
         {showInsertMenu && showInsertActionsInRow ? (
           <ToolbarInsertMenu
             disabled={!canInsertStructural}
+            disabledReasons={props.insertDisabledReasons}
             onInsertImage={props.onInsertImage}
             onInsertPageBreak={props.onInsertPageBreak}
             onInsertSectionBreak={props.onInsertSectionBreak}
@@ -581,12 +639,43 @@ export function TwToolbar(props: TwToolbarProps) {
         ) : null}
         {showSidebarToggle ? (
           <>
-            <TwToolbarIconButton
-              icon={PanelRight}
-              label="Toggle sidebar"
-              active={props.isSidebarOpen ?? false}
-              onClick={props.onToggleSidebar}
-            />
+            {/*
+              Lane 6b §6b.U1 — unread badge on the sidebar toggle when the
+              rail is closed.  Host passes summed open-comment / open-
+              change counts; we only paint the badge when the rail is
+              closed AND there is something unread.
+            */}
+            <span className="relative inline-flex">
+              <TwToolbarIconButton
+                icon={PanelRight}
+                label="Toggle sidebar"
+                active={props.isSidebarOpen ?? false}
+                onClick={props.onToggleSidebar}
+              />
+              {(() => {
+                const isOpen = props.isSidebarOpen ?? false;
+                const count =
+                  (props.openCommentCount ?? 0) +
+                  (props.openChangeCount ?? 0);
+                if (isOpen || count <= 0) return null;
+                const display = count > 99 ? "99+" : String(count);
+                return (
+                  <span
+                    className={[
+                      "pointer-events-none absolute -top-1 -right-1",
+                      "inline-flex h-4 min-w-4 items-center justify-center",
+                      "rounded-[var(--radius-pill)] px-1",
+                      "bg-[var(--color-accent-primary)] text-[var(--color-text-on-accent)]",
+                      "text-[9px] font-semibold leading-none",
+                    ].join(" ")}
+                    data-testid="toolbar-sidebar-toggle-badge"
+                    aria-label={`${count} unread review items`}
+                  >
+                    {display}
+                  </span>
+                );
+              })()}
+            </span>
             <div className="mx-1 h-4 w-px bg-border" />
           </>
         ) : null}
@@ -851,10 +940,14 @@ function ToolbarParagraphStyleSelect(props: {
   styles: StyleCatalogSnapshot["paragraphs"];
   value?: string;
   disabled: boolean;
+  hasMixedValue?: boolean;
   onValueChange?: (styleId: string) => void;
 }) {
+  const isMixed = props.hasMixedValue === true;
   const resolvedValue =
-    props.value && props.styles.some((style) => style.styleId === props.value)
+    !isMixed &&
+    props.value &&
+    props.styles.some((style) => style.styleId === props.value)
       ? props.value
       : "";
 
@@ -868,10 +961,20 @@ function ToolbarParagraphStyleSelect(props: {
         aria-label="Paragraph style"
         aria-disabled={props.disabled || undefined}
         data-disabled={props.disabled ? "" : undefined}
+        data-mixed={isMixed ? "true" : 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}`}
       >
-        <Select.Value placeholder="Style" />
+        {isMixed ? (
+          <span
+            className="italic text-[var(--color-text-tertiary)]"
+            data-testid="toolbar-paragraph-style-mixed"
+          >
+            Mixed
+          </span>
+        ) : (
+          <Select.Value placeholder="Style" />
+        )}
         <Select.Icon>
           <ChevronDown className="h-3.5 w-3.5 text-tertiary" />
         </Select.Icon>
@@ -903,9 +1006,14 @@ function ToolbarParagraphStyleSelect(props: {
 function ToolbarFontFamilySelect(props: {
   value?: string;
   disabled: boolean;
+  hasMixedValue?: boolean;
   onValueChange?: (fontFamily: string) => void;
 }) {
-  const resolvedValue = props.value && FONT_FAMILIES.includes(props.value) ? props.value : "";
+  const isMixed = props.hasMixedValue === true;
+  const resolvedValue =
+    !isMixed && props.value && FONT_FAMILIES.includes(props.value)
+      ? props.value
+      : "";
 
   return (
     <Select.Root
@@ -917,10 +1025,20 @@ function ToolbarFontFamilySelect(props: {
         aria-label="Font family"
         aria-disabled={props.disabled || undefined}
         data-disabled={props.disabled ? "" : undefined}
+        data-mixed={isMixed ? "true" : 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}`}
       >
-        <Select.Value placeholder="Font" />
+        {isMixed ? (
+          <span
+            className="italic text-[var(--color-text-tertiary)]"
+            data-testid="toolbar-font-family-mixed"
+          >
+            Mixed
+          </span>
+        ) : (
+          <Select.Value placeholder="Font" />
+        )}
         <Select.Icon>
           <ChevronDown className="h-3.5 w-3.5 text-tertiary" />
         </Select.Icon>
@@ -952,10 +1070,16 @@ function ToolbarFontFamilySelect(props: {
 function ToolbarFontSizeSelect(props: {
   value?: number;
   disabled: boolean;
+  hasMixedValue?: boolean;
   onValueChange?: (fontSize: number) => void;
 }) {
+  const isMixed = props.hasMixedValue === true;
   const resolvedValue =
-    typeof props.value === "number" && FONT_SIZES.includes(props.value) ? String(props.value) : "";
+    !isMixed &&
+    typeof props.value === "number" &&
+    FONT_SIZES.includes(props.value)
+      ? String(props.value)
+      : "";
 
   return (
     <Select.Root
@@ -967,10 +1091,20 @@ function ToolbarFontSizeSelect(props: {
         aria-label="Font size"
         aria-disabled={props.disabled || undefined}
         data-disabled={props.disabled ? "" : undefined}
+        data-mixed={isMixed ? "true" : 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}`}
       >
-        <Select.Value placeholder="Size" />
+        {isMixed ? (
+          <span
+            className="italic text-[var(--color-text-tertiary)]"
+            data-testid="toolbar-font-size-mixed"
+          >
+            Mixed
+          </span>
+        ) : (
+          <Select.Value placeholder="Size" />
+        )}
         <Select.Icon>
           <ChevronDown className="h-3.5 w-3.5 text-tertiary" />
         </Select.Icon>
@@ -1483,6 +1617,17 @@ function ToolbarAlignmentPopover(props: {
 
 function ToolbarInsertMenu(props: {
   disabled: boolean;
+  /**
+   * Lane 6b §6b.U3 — optional per-item disabled-explanation reasons.
+   * When the item is disabled (no handler or policy-gated), hovering it
+   * surfaces a `title=` tooltip "Not available: {reason}".
+   */
+  disabledReasons?: {
+    pageBreak?: string;
+    table?: string;
+    image?: string;
+    sectionBreak?: string;
+  };
   onInsertPageBreak?: () => void;
   onInsertTable?: () => void;
   onInsertSectionBreak?: (type: SectionBreakType) => void;
@@ -1535,6 +1680,7 @@ function ToolbarInsertMenu(props: {
             <ToolbarMenuButton
               ariaLabel="Insert page break"
               disabled={props.disabled || !props.onInsertPageBreak}
+              disabledReason={props.disabledReasons?.pageBreak}
               icon={<Minus className="h-3.5 w-3.5" />}
               label="Page break"
               onClick={() => {
@@ -1545,6 +1691,7 @@ function ToolbarInsertMenu(props: {
             <ToolbarMenuButton
               ariaLabel="Insert table"
               disabled={props.disabled || !props.onInsertTable}
+              disabledReason={props.disabledReasons?.table}
               icon={<Rows3 className="h-3.5 w-3.5" />}
               label="Table"
               onClick={() => {
@@ -1573,6 +1720,7 @@ function ToolbarInsertMenu(props: {
             <ToolbarMenuButton
               ariaLabel="Insert next-page section break"
               disabled={props.disabled || !props.onInsertSectionBreak}
+              disabledReason={props.disabledReasons?.sectionBreak}
               icon={<FileText className="h-3.5 w-3.5" />}
               label="Next-page section break"
               onClick={() => {
@@ -1616,13 +1764,29 @@ function ToolbarMenuButton(props: {
   disabled: boolean;
   icon: React.ReactNode;
   label: string;
+  /**
+   * Lane 6b §6b.U3 — optional explanation surfaced as `title=` when the
+   * item is disabled.  Hosts pass the capability-policy reason so users
+   * hover the entry and understand why it is unavailable in the current
+   * context, rather than just seeing a faded click target.
+   */
+  disabledReason?: string;
   onClick?: () => void;
 }) {
+  const titleAttr =
+    props.disabled && props.disabledReason
+      ? `Not available: ${props.disabledReason}`
+      : undefined;
   return (
     <button
       type="button"
       aria-label={props.ariaLabel}
+      aria-disabled={props.disabled ? "true" : undefined}
       disabled={props.disabled}
+      title={titleAttr}
+      data-disabled-reason={
+        props.disabled && props.disabledReason ? props.disabledReason : undefined
+      }
       onMouseDown={preserveEditorSelectionMouseDown}
       onClick={props.onClick}
       className={`flex h-7 w-full items-center gap-2 rounded-md px-2 text-left text-[11px] font-medium text-primary transition-colors hover:bg-surface disabled:cursor-not-allowed disabled:opacity-40 ${focusRingClass}`}