feat(mobile): show editing toolbar whenever a soft keyboard is up, not just on phones

The edit bar was gated purely on viewport width (useIsMobile, max-width
767px), so a wide iPad with NO hardware keyboard — where the soft keyboard
does appear — never got the toolbar. Add a width-independent arm: show when
editing AND (narrow OR a soft keyboard is up).

- keyboardViewport: add pan-invariant `softKeyboardPresent(layoutHeight,
  vvHeight)` = `layoutHeight - vvHeight >= SOFT_KEYBOARD_MIN_HEIGHT` (150px).
  It deliberately omits offsetTop (so it stays true while the page pans/scrolls
  with the keyboard up, unlike the positioning overlap) and sits well above the
  URL-bar band so a collapsing URL bar can't read as a keyboard. ~0 on
  Chromium/Firefox resizes-content (layout shrinks with the keyboard) — fine,
  those phones are already covered by the width gate.
- MobileKeyboardToolbar: gate on `isEditing && (isMobile || softKeyboardPresent)`;
  detect the keyboard only when `!isMobile` so phones don't pay for it. Extract
  the shared subscribe-and-derive pattern (inset + presence) into one generic
  `useKeyboardViewportValue` hook.

With a hardware keyboard connected no soft keyboard appears, so the bar stays
hidden — which is the desired behavior. Unit-tested; on-device confirm pending.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Stvad

src/plugins/mobile-keyboard-toolbar/MobileKeyboardToolbar.tsx

@@ -7,45 +7,53 @@ import { ActionContextTypes } from '@/shortcuts/types.js'
 import { withEditModeKeepalive } from '@/components/editModeKeepalive.js'
 import {
   getLayoutViewportKeyboardOverlap,
+  getSoftKeyboardPresent,
   setEditingToolbarHeight,
   subscribeKeyboardViewport,
 } from '@/utils/keyboardViewport.js'
 import { EXIT_EDIT_ACTION_ID, mobileKeyboardToolbarItemsFacet } from './facet.ts'
 
-/** The mobile editing toolbar's `bottom` inset — lifts the `position: fixed`
- *  toolbar just above the on-screen keyboard while editing. The value is the
- *  layout-viewport keyboard overlap (see `getLayoutViewportKeyboardOverlap` for
- *  the formula and the iOS clientHeight-vs-innerHeight + pan rationale); this
- *  hook tracks it live while the toolbar is active (`isMobile && isEditing`)
- *  and re-renders on change. */
-const useKeyboardInset = (active: boolean): number => {
-  const [inset, setInset] = useState(0)
+/** Track a value derived from viewport geometry, recomputed on every relevant
+ *  change via the shared keyboard-viewport subscription (the same listener set
+ *  keyboardAwareScroll uses), and re-rendering only when the mapped value
+ *  changes. `read` must be a stable module-level reader. Only subscribes while
+ *  `active`, so an app with no active editor carries no listeners.
+ *
+ *  Accepted transient: during a rapid keyboard open/close iOS emits a burst of
+ *  events while clientHeight / vv.height / offsetTop settle independently, so a
+ *  derived value can be briefly off for a frame; the next event recomputes it.
+ *  Not rAF-coalesced — that would add a frame of latency to the common
+ *  smooth-scroll case for a rare, self-correcting blip. */
+const useKeyboardViewportValue = <T,>(active: boolean, read: () => T, initial: T): T => {
+  const [value, setValue] = useState(initial)
 
   useEffect(() => {
     if (!active || typeof window === 'undefined') return
-    // Recompute on every viewport change (keyboard open/close, the iOS pan on
-    // scroll, rotation) via the shared subscription — the same listener set
-    // keyboardAwareScroll uses. Its extra fire on toolbar-height changes is a
-    // no-op here: the inset doesn't depend on that, and the equality guard
-    // drops the redundant recompute.
-    //
-    // Accepted transient: during a rapid keyboard open/close iOS emits a burst
-    // of events while clientHeight / vv.height / offsetTop settle
-    // independently, so the inset can be briefly off for a frame; the next
-    // event recomputes it correctly. Not rAF-coalesced — that would add a frame
-    // of latency to the common smooth-scroll case for a rare, self-correcting
-    // blip.
-    const update = () => {
-      const next = getLayoutViewportKeyboardOverlap()
-      setInset(prev => (prev === next ? prev : next))
-    }
+    const update = () =>
+      setValue(prev => {
+        const next = read()
+        return prev === next ? prev : next
+      })
     update()
     return subscribeKeyboardViewport(update)
-  }, [active])
+  }, [active, read])
 
-  return inset
+  return value
 }
 
+/** The toolbar's `bottom` inset — the live layout-viewport keyboard overlap
+ *  that lifts the `position: fixed` toolbar just above the on-screen keyboard
+ *  (see `getLayoutViewportKeyboardOverlap` for the iOS clientHeight/pan
+ *  rationale). ~0 on Chromium/Firefox, nonzero on iOS Safari. */
+const useKeyboardInset = (active: boolean): number =>
+  useKeyboardViewportValue(active, getLayoutViewportKeyboardOverlap, 0)
+
+/** Whether a soft keyboard is currently up (pan-invariant — see
+ *  `getSoftKeyboardPresent`). Lets the toolbar show on a wide iPad with no
+ *  hardware keyboard, where the `useIsMobile` width gate is off. */
+const useSoftKeyboardPresent = (active: boolean): boolean =>
+  useKeyboardViewportValue(active, getSoftKeyboardPresent, false)
+
 /** Mobile-only toolbar that sits above the on-screen keyboard while a
  *  block is being edited. Its buttons are facet contributions
  *  (`mobileKeyboardToolbarItemsFacet`): the structural/reference set comes
@@ -69,10 +77,18 @@ export function MobileKeyboardToolbar() {
   // presentation lives on the action. The toolbar only shows in edit mode, so
   // unqualified items resolve against EDIT_MODE_CM.
   const resolved = useActionRefItems(mobileKeyboardToolbarItemsFacet, ActionContextTypes.EDIT_MODE_CM)
+  // Show while editing on a narrow (phone) viewport, OR — regardless of width —
+  // whenever a soft keyboard is up. The soft-keyboard arm covers a wide iPad
+  // with no hardware keyboard: the keyboard appears, so the toolbar should too;
+  // with a hardware keyboard connected no soft keyboard shows and the toolbar
+  // stays hidden. Only detect the keyboard when the width gate wouldn't already
+  // show the bar (`!isMobile`), so phones don't pay for the extra subscription.
+  const softKeyboardPresent = useSoftKeyboardPresent(isEditing && !isMobile)
+  const showToolbar = isEditing && (isMobile || softKeyboardPresent)
   // Hooks above the early-return must run on every render. Pass the
   // activation flag in so the sentinel only mounts/listens while the
   // toolbar is on screen.
-  const keyboardInset = useKeyboardInset(isMobile && isEditing)
+  const keyboardInset = useKeyboardInset(showToolbar)
 
   // Publish the toolbar's rendered height so keyboardAwareScroll can keep
   // the caret above the toolbar, not just above the keyboard. Measured
@@ -93,9 +109,9 @@ export function MobileKeyboardToolbar() {
       observer.disconnect()
       setEditingToolbarHeight(0)
     }
-  }, [isMobile, isEditing])
+  }, [showToolbar])
 
-  if (!isMobile || !isEditing) return null
+  if (!showToolbar) return null
 
   // Prevent the editor from blurring when a button is pressed — losing
   // focus would dismiss the on-screen keyboard mid-tap and tear down

src/utils/keyboardViewport.ts

@@ -72,6 +72,35 @@ export const getLayoutViewportKeyboardOverlap = (): number => {
 export const getVisualViewportHeight = (): number =>
   typeof window === 'undefined' ? 0 : Math.round(window.visualViewport?.height ?? 0)
 
+/** Minimum layout-vs-visual height delta (CSS px) that counts as a soft
+ *  keyboard being up. Deliberately well above the URL-bar band (~60–100px on
+ *  mobile Safari): the delta is used width-independently to decide whether to
+ *  show the editing toolbar on a wide iPad (no hardware keyboard ⇒ soft
+ *  keyboard ⇒ toolbar), so a collapsing URL bar must NOT read as a keyboard.
+ *  A real soft keyboard is ≥ ~200px; this sits between. */
+export const SOFT_KEYBOARD_MIN_HEIGHT = 150
+
+/** Pure: is a soft keyboard up, judged by how much the visual viewport has
+ *  shrunk below the layout viewport? Uses ONLY the height delta (no offsetTop)
+ *  so it's invariant to the iOS pan — unlike the positioning overlap, this must
+ *  stay true while the page scrolls with the keyboard up. On Chromium/Firefox
+ *  (interactive-widget=resizes-content) the layout viewport shrinks WITH the
+ *  keyboard, so the delta is ~0 and this reads false — fine, because those are
+ *  the phones already covered by the width (`useIsMobile`) gate; the delta is
+ *  the extra signal for wide iOS where the layout viewport stays full. */
+export const softKeyboardPresent = (layoutHeight: number, visualViewportHeight: number): boolean =>
+  layoutHeight - visualViewportHeight >= SOFT_KEYBOARD_MIN_HEIGHT
+
+/** Live {@link softKeyboardPresent} read from the DOM. Layout height is
+ *  `documentElement.clientHeight` (stays full on iOS while the keyboard is up),
+ *  matching {@link getLayoutViewportKeyboardOverlap}'s source. */
+export const getSoftKeyboardPresent = (): boolean => {
+  if (typeof document === 'undefined') return false
+  const vv = typeof window === 'undefined' ? undefined : window.visualViewport
+  if (!vv) return false
+  return softKeyboardPresent(document.documentElement.clientHeight, vv.height)
+}
+
 const listeners = new CallbackSet('keyboard-viewport')
 let attached = false
 

src/utils/test/keyboardViewport.test.ts

@@ -4,6 +4,7 @@ import {
   getKeyboardOverlap,
   layoutViewportKeyboardOverlap,
   setEditingToolbarHeight,
+  softKeyboardPresent,
   subscribeKeyboardViewport,
 } from '@/utils/keyboardViewport'
 
@@ -104,6 +105,41 @@ describe('layoutViewportKeyboardOverlap', () => {
   })
 })
 
+describe('softKeyboardPresent', () => {
+  // Width-independent "is a soft keyboard up" signal for showing the editing
+  // toolbar on a wide iPad. Uses only the layout-vs-visual height delta (no
+  // offsetTop), so unlike the positioning overlap it stays true as the page
+  // pans/scrolls with the keyboard up.
+  it('is true when the visual viewport is shrunk by a keyboard (iOS)', () => {
+    // Real iPad: clientHeight 650, keyboard shrinks vv to 314.
+    expect(softKeyboardPresent(650, 314)).toBe(true)
+  })
+
+  it('stays true while scrolled — the same shrunk vv.height, no offsetTop term', () => {
+    // Scrolled case where the positioning overlap drops to 59; presence must
+    // NOT, because the keyboard is still up (vv.height still 314).
+    expect(softKeyboardPresent(650, 314)).toBe(true)
+  })
+
+  it('is false with no keyboard (visual viewport fills the layout viewport)', () => {
+    expect(softKeyboardPresent(650, 650)).toBe(false)
+  })
+
+  it('does NOT treat a collapsing URL bar as a keyboard', () => {
+    // A mobile-Safari URL bar shrinks the visual viewport by ~60px — well below
+    // the threshold, so it must not switch the toolbar on.
+    expect(softKeyboardPresent(650, 600)).toBe(false)
+  })
+
+  it('is false on Chromium resizes-content (layout shrinks with the keyboard)', () => {
+    expect(softKeyboardPresent(433, 433)).toBe(false)
+  })
+
+  it('is true exactly at the 150px threshold', () => {
+    expect(softKeyboardPresent(650, 500)).toBe(true)
+  })
+})
+
 describe('subscribeKeyboardViewport', () => {
   it('attaches on first subscriber and detaches once the last leaves', () => {
     const vv = installViewport({height: 500})