Versions Compared

Old Version 1

changes.mady.by.user GE-DevDoc-Bot

Saved on

compared with

New Version 2

changes.mady.by.user GE-DevDoc-Bot

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Document Viewer

Link to Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11613-105271&t=iosNC2AkSTGs5lMh-1

Overview

  • The Document Viewer displays PDF documents directly inside the application.
  • It offers configurable display options for document viewing.
  • It helps users read documents like contracts, reports, or manuals without external viewers.
  • It supports localized titles and optional text selection.
  • It can connect to a datasource to fetch the PDF content.

...

  • visibilityPolicySetId – Determines the visibility of the component based on specified policy sets. For example, setting to "documentAccessPolicy" restricts the document viewer visibility to users with document access privileges according to the specified policy.

Guidelines

[NO DATA AVAILABLE]

Accessibility

...

Usage

  • Provide a clear, localized label for context with title (multi-language map) so users know which document they are reading.
  • Choose rendering behavior based on intent: preserve exact layout with originalSize: true (e.g., contracts), or fit to available space with originalSize: false for general reading.
  • Control copying according to content policy by toggling allowSelectText (enable for research/citation workflows; disable for view-only or sensitive PDFs).
  • Optionally aid discovery during onboarding by enabling a guided-tour hotspot via enableAsHotspot, guidedTourHotSpotTitle, and guidedTourHotSpotDescription (all translatable).
  • Expose stable hooks for programmatic and test automation via id and dataTestId. (No component events are defined in the Article; avoid relying on event handlers.)

Sizing & Layout

  • Add breathing room around the viewer with paddingClass (e.g., “p-4”), using only the component’s own spacing token.
  • Use originalSize to govern scaling; when false, the viewer scales to fit its allotted area; when true, it uses the document’s native dimensions.

States & Feedback

  • Represent selection capability as a binary state using allowSelectText (enabled/disabled).

Data-Driven / Conditional Behavior

  • Show the viewer only when a valid document is available by defining displayConditions (e.g., check a bound documentId or fetch status that the component can “see”).
  • Prevent UI “flicker” by making displayConditions mutually exclusive and tied to stable values (e.g., only switch to “show” after required parameters are present).

Visibility & Authorization

  • Gate access without leaking content by assigning a policy set to visibilityPolicySetId so the viewer is hidden for unauthorized users.
  • Use displayConditions for contextual visibility (e.g., only show after a selection) and reserve visibilityPolicySetId for permission-based gating.

Content & Localization

  • Localize user-visible text with title (language map).
  • Localize guided-tour copy with guidedTourHotSpotTitle and guidedTourHotSpotDescription.
  • Keep title concise to avoid truncation in tight spaces; use the document itself for detailed naming, not the title line.

Dos & Don’ts

DoDon’tArticle setting(s)
Bind the viewer to a concrete source and pass explicit parameters for determinism.Rely on implicit/global state for which document appears.dataSourceId, getEntityCollectionHttpRequestParametersMap
Localize the title so users understand what they’re viewing.Hard-code an English-only title.title
Preserve exact layout for formal documents.Force-fit precise layouts that become blurry or misaligned.originalSize
Disable text selection for sensitive PDFs.Leave selection on when copying must be prevented.allowSelectText
Add spacing using the component’s own token.Hack spacing with external CSS not controlled by the component.paddingClass
Hide the viewer until a document is available.Show an empty/blank frame.displayConditions
Hide confidential documents from unauthorized users.Show the component and rely on the document to say “no access.”visibilityPolicySetId
Provide stable automation hooks for QA.Target the viewer with brittle selectors (e.g., DOM order).id, dataTestId
Use localized copy for guided tours.Show untranslated hotspot text.enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription

Accessibility

  • The component does not expose ARIA roles, focus management, or keyboard-handling props; accessibility relies on readable rendering (originalSize), text-selection capability (allowSelectText), and localized textual surfaces (title, guidedTourHotSpotTitle, guidedTourHotSpotDescription).
  • Ensure locale keys in title, guidedTourHotSpotTitle, and guidedTourHotSpotDescription match the user’s language so assistive technologies announce text in the correct voice.
  • If users must extract passages for assistive tools, enable allowSelectText; if content is sensitive, disable it and communicate restrictions via the title or the PDF content itself.
  • Choose originalSize only when it materially increases legibility for dense PDFs; otherwise keep scaling enabled to minimize horizontal scrolling for low-vision users.