Preview panel

Problem Context

• A source region contains selectable content objects such as files, emails, invoices, contracts, images, videos, audio, or attachments.
• Users must compare or triage multiple nearby items quickly while seeing each selected item's rendered body or media.
• A partial preview is useful enough for review, but deep reading, editing, annotation, or sharing can move to a full viewer.
• The product can detect unsupported formats, risky files, permission loss, loading, stale selection, and preview-render failures.

Selection Rules

• Choose preview panel when users need durable rendered content beside a collection, not only metadata about the selected object.
• Use details panel when the main content is structured fields, status, ownership, and activity rather than the document or media body.
• Use hover card when the preview is small, transient, and appears before a navigation decision.
• Use drawer when the surface is temporarily opened by a command and needs a close path and focus movement into it.
• Use full-page or full-screen preview when users need long reading, annotation, page thumbnails, shareable URL state, or large media controls.
• Use object picker with preview when the preview is part of selecting an entity for a form or workflow.
• Do not use a preview panel when the selected content cannot be rendered safely, quickly, or accurately enough to support user decisions.
• Do not use a preview panel as a dumping ground for filters, global navigation, settings, or unrelated actions.

Required States

• No selection state that asks users to choose a file, message, or media item.
• Selected content state with source row highlighted and preview heading naming the same item.
• Loading preview state that hides or clearly labels old content as no longer current.
• Rendered document state with page, zoom, fit, and open-full-preview controls when the type supports them.
• Rendered image, video, audio, or message state with controls appropriate to that content type.
• Unsupported type state with format, reason, and alternate actions such as download or open with an app.
• Blocked or suspicious file state that explains why inline preview is disabled and offers safer choices.
• Permission lost, deleted item, or filtered-away state that clears the rendered content and returns users to selection.
• Narrow viewport state with collapse, resize, or full preview route.

Interaction Contract

• Selecting an item updates both the source selection indicator and the preview panel title.
• The preview panel renders the selected item's content body or media, while metadata remains supporting context.
• Keyboard focus stays in the source list, grid, or inbox while users move selection for rapid review.
• Preview controls update only the current selected item and announce changes such as page, zoom, fit, blocked, or open-full state.
• Loading, unsupported, blocked, stale, permission, and deleted states replace the rendered content rather than letting old content appear current.
• The panel offers a route to full preview or full object view when the content needs more space or deeper interaction.
• Download, open with app, and external viewer actions preserve selected-item identity and communicate risk when relevant.

Implementation Checklist

• Define the selected content ID and preview-render lifecycle before painting preview content.
• Show the selected item in the source region and repeat its name, type, and current preview state in the panel.
• Support media-specific controls such as page, zoom, fit, play, transcript, alt text, rotate, or full preview only when they match the selected type.
• Handle loading, unsupported format, blocked file, suspicious source, permission loss, deleted content, filtered-away selection, and render failure.
• Prevent stale previews by clearing or labelling old rendered content during selection changes and load failures.
• Keep focus in the source region during rapid selection movement; move focus into preview controls only after explicit user action.
• Provide collapse, resize, or full preview when the panel cannot keep both source context and content readable.
• Test row selection, keyboard movement, paging, zoom, fit width, blocked preview, unsupported format, resize, and full preview route.

Common Generated-UI Mistakes

• Showing metadata in a preview panel when users need the document, message, or media body.
• Leaving stale rendered content visible after selection changes or preview loading fails.
• Rendering risky downloaded or remote content without a blocked state or warning.
• Using a preview panel for long editing, annotation, or reading workflows that need a full route.
• Stealing focus into the preview on every source-list movement.
• Making the preview too small to read while hiding the full-preview route.
• Mixing preview, filters, navigation, destructive actions, and settings in one side region.

Critique Questions

• Which selected content item owns the rendered preview right now?
• Can users see the selected source item and the preview title at the same time?
• Does the panel render content body or media, or only metadata better suited to a details panel?
• What happens while a new preview is loading, blocked, unsupported, deleted, or denied by permissions?
• Are page, zoom, fit, play, transcript, and full-preview controls present only when the content type needs them?
• How do users reach a full viewer when the panel is too small or the task becomes deep reading or annotation?