Skip to content

context_menu: Lift an app-made preview beside the iOS system menu - #2297

Open
madcodelife wants to merge 3 commits into
mainfrom
context-menu-preview
Open

madcodelife wants to merge 3 commits into
mainfrom
context-menu-preview

Conversation

@madcodelife

@madcodelife madcodelife commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Description

ContextMenu with items shows the iOS system context menu (#2202), but the system always lifts the trigger itself. Apps often want to lift something else beside the menu: a conversation row that previews its last messages, a file row that previews the document, a link that previews the page. UIKit does this through the configuration's preview provider and commits a press on the preview through willPerformPreviewActionForMenuWithConfiguration.

This adds both to ContextMenu:

<ContextMenu
  items={actions}
  onSelect={({ id }) => act(chat, id)}
  preview={<ChatCard chat={chat} />}
  onPreviewPress={() => openChat(chat)}
  trigger={<ChatRow chat={chat} />}
/>
  • When the preview is made: when a finger goes down on the trigger. UIKit asks for the preview as the hold completes, without waiting on the app, so the view must already be laid out by then. It stays while the menu is up and goes once the menu closed. After a tap or a scroll that opened no menu, it goes a second later. Data the preview starts loading as it is made can arrive while the finger is held.
  • Where it lives: next to the native component, laid out at its own size far outside the window and hidden from assistive technologies, which keep the trigger. system_menu now returns a zero-size view holding the component and the preview. The native component finds the trigger around that view and the preview beside it.
  • iOS: the preview provider returns a view controller showing a picture of the preview, taken when the system asks for it, with preferredContentSize set to its size. Until the preview is laid out (no window yet, zero size), the provider returns nil and the system lifts the trigger as before. A press on the preview commits with the dismiss style and is told as previewPress before close, the same way a chosen action is told before the dismissal.
  • Events: onPreviewPress (Rust ContextMenuEvents::PreviewPress, .on_preview_press(..)). The order matches a chosen item: onOpenChange(false, select), onPreviewPress, onClose.
  • Other platforms: unchanged. preview and onPreviewPress are not used, just like items. Without preview, nothing changes on iOS either. No view is made, and the component gets preview: false, so the provider stays nil.

A picture instead of a live view keeps the preview out of UIKit's view hierarchy: NSH keeps owning the view, and nothing moves between hosts while the system animates. The cost is that the preview does not update once the menu is up. That is fine for content previews, and the preview stays a plain NSH view the app styles as it wants.

Also:

  • website/elements/menu.md (English and zh-CN): "A preview in place of the trigger", the new prop and event.
  • docs/dev/api-naming.md: preview / onPreviewPress next to ContextMenu's other NSH additions.

Public API

  • nsh/base ContextMenu: prop preview?: JSX.Element (Rust .preview(..), Prop<Option<Slot>>). iOS only, with items: what the system lifts beside its menu in place of the trigger. Not used on the other platforms.
  • nsh/base ContextMenu: event onPreviewPress (Rust .on_preview_press(|| ..), ContextMenuEvents::PreviewPress). iOS only: the preview was pressed, and the menu closed as for a chosen item.

Test plan

  • cargo test -p nsh-base --test base -- menu:: (57 passed), including three new tests:
    • the preview is made under a finger at its own size, not shown, kept while the menu is up, and gone after previewPress / close, with events in order;
    • after a tap that opened no menu, the preview goes after the linger;
    • without a preview, the component gets preview: false and a touch makes nothing.
  • cargo test -p nsh-engine --test engine context_menu
  • cargo clippy -p nsh-base --tests -- -D warnings, and nsh-platform-ios for aarch64-apple-ios-sim
  • cargo +nightly fmt --check
  • iOS simulator (iPhone 17, iOS 27): a held finger on a row whose ContextMenu has a preview (a card made at touch-down) lifts the card beside the system menu instead of the row. The finger was a real touch from nsh test --target ios.
  • Pressing the preview on a device: covered by the previewPress tests above, but not driven through UIKit (the test agent can't reach the system's preview window).

ContextMenu gains a `preview` slot and an `onPreviewPress` event. On iOS,
with `items`, the preview is made when a finger goes down on the trigger,
laid out out of sight, and handed to UIContextMenuInteraction as the lifted
preview; pressing it closes the menu and reports `onPreviewPress`.
@madcodelife
madcodelife marked this pull request as ready for review November 17, 2026 16:35
@madcodelife madcodelife changed the title feat(base): preview for iOS system context menus context_menu: Lift an app-made preview beside the iOS system menu Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant