Product Narrative Component

Relevant source files

The following files were used as context for generating this wiki page: - [src/components/ProductNarrative.jsx](https://github.com/hamzaelsherif03/X/blob/HEAD/src/components/ProductNarrative.jsx) - [src/components/Features.jsx](https://github.com/hamzaelsherif03/X/blob/HEAD/src/components/Features.jsx) - [src/components/Process.jsx](https://github.com/hamzaelsherif03/X/blob/HEAD/src/components/Process.jsx) - [src/components/Hero.jsx](https://github.com/hamzaelsherif03/X/blob/HEAD/src/components/Hero.jsx) - [src/components/Solutions.jsx](https://github.com/hamzaelsherif03/X/blob/HEAD/src/components/Solutions.jsx) - [package.json](https://github.com/hamzaelsherif03/X/blob/HEAD/package.json)

The ProductNarrative component is a scroll-driven, animated UI section designed to tell a story about the product's core functionalities. It creates an immersive experience by synchronizing textual content with corresponding visual representations as the user scrolls. The component leverages the framer-motion library to achieve complex scroll-triggered animations, making it a visually engaging way to present a multi-stage product value proposition.

This component is structured as a self-contained <section> with a significant height (400vh) to facilitate a long scroll experience. Inside, a sticky container holds the content, allowing visuals and text to animate in and out of view while the user's viewport remains focused on the same area of the page. This technique is also seen in other components like Features.jsx, indicating a common design pattern for showcasing features in the application.

Sources: src/components/ProductNarrative.jsx:1-254, src/components/Features.jsx:26-29

Architecture and Core Concepts

The component's architecture is based on a parent container that manages the scroll progress and two types of child components (NarrativeText and VisualCard) that react to this progress.

Sources: src/components/ProductNarrative.jsx:14-51

Component Structure

The ProductNarrative component is built with a two-column layout. The left side displays the textual narrative, while the right side presents animated visuals that correspond to the text.

• Main Container (<section>): A relative positioned container with a height of 400vh to create the scrollable area. It uses a useRef to track its position on the page.
• Sticky Wrapper (<div>): A sticky positioned div that remains fixed to the top of the viewport as the user scrolls through the main container. This wrapper holds both the text and visual columns.
• Text Column (<div>): Contains multiple instances of the NarrativeText component, which are absolutely positioned and fade in and out based on scroll position.
• Visuals Column (<div>): Contains multiple instances of the VisualCard component, which also animate based on scroll position to synchronize with the text.

The following diagram illustrates the high-level structure of the component.

Scroll Animation Logic

The core of the animation is handled by framer-motion hooks.

1. useRef: A ref (containerRef) is attached to the main <section> element to serve as a target for scroll tracking.
2. useScroll: This hook monitors the scroll progress of the containerRef. It returns a scrollYProgress motion value, which is a number between 0 and 1 representing the scroll position within the target element.
3. useTransform: This hook is used within the child components (NarrativeText, VisualCard) to map the scrollYProgress value to other values, such as opacity, y (vertical position), and scale. This creates the dynamic animations tied to the user's scroll action.

This flow is central to how the narrative unfolds visually.

Sub-components

The ProductNarrative component orchestrates two key child components to build its user experience.

NarrativeText Component

This component is responsible for displaying the textual part of the narrative. It animates in and out based on a specific scroll range.

Prop	Type	Description
progress	MotionValue<any>	The scrollYProgress value from the parent's useScroll hook.
range	[number, number]	The start and end points (0-1) of the scroll progress for this text to be visible.
title	string	The main heading for the narrative stage.
desc	string	The descriptive paragraph for the narrative stage.

The component uses useTransform to calculate opacity and y position. The text fades in and slides up, stays visible for the duration of its range, and then fades out and continues sliding up as the user scrolls past.

Sources: src/components/ProductNarrative.jsx:218-234

VisualCard Component

This component acts as a container for the visual elements that correspond to each narrative stage. It fades and scales in and out of view.

Prop	Type	Description
children	React.ReactNode	The visual content (JSX) to be displayed inside the card.
progress	MotionValue<any>	The scrollYProgress value from the parent's useScroll hook.
range	[number, number]	The start and end points (0-1) of the scroll progress for this visual to be visible.

Like NarrativeText, it uses useTransform to map the scroll progress to opacity and scale properties, creating a smooth cross-fade and zoom effect between the different visual cards.

Sources: src/components/ProductNarrative.jsx:236-248

Narrative Stages & Visuals

The component hardcodes a three-stage narrative, with each stage having its own text and a corresponding visual card. The lucide-react library provides icons for these visuals.

Sources: src/components/ProductNarrative.jsx:4, src/components/ProductNarrative.jsx:24-42

| Stage | Title | Description | Scroll Range | Visual Content - | :----------- | :--------------------- |
| 1 | Real-time Visibility | "Track every shipment across your global network with satellite precision. Detect anomalies before they become delays." | [0, 0.3] | A map view with pulsing location pins (LAX, JFK, MIA) and a floating card showing "In Transit • On Time" status with a Map icon. - |
| 2 | Predictive AI Models | "Our neural networks analyze historical data and weather patterns to forecast disruptions with 94% accuracy." | [0.3, 0.6] | An "AI Risk Analysis" card with a Zap icon. It displays animated progress bars for risk factors like 'Weather Impact', 'Port Congestion', and 'Fuel Availability'. - |
| 3 | Automated Resolution | "When issues arise, OptiFlow automatically reroutes shipments and notifies stakeholders. Zero manual intervention." | [0.6, 0.9] | A success screen with a large CheckCircle icon and the title "Route Optimized". It shows a comparison between the "Original Route (Blocked)" and the "New Route (Active)". - |

Sources: src/components/ProductNarrative.jsx:24-209

Dependencies

The component relies on several key libraries defined in package.json.

Package	Version	Usage
react	^19.2.0	The core library for building the component UI.
framer-motion	^12.23.24	Used for all animations, including motion components, useScroll, and useTransform. This is critical to the component's functionality.
lucide-react	^0.554.0	Provides the SVG icons (Map, Zap, CheckCircle) used in the visual cards.

Sources: package.json:13-15, src/components/ProductNarrative.jsx:2-4

Conclusion

The ProductNarrative component is an excellent example of "scrollytelling" within a React application. It effectively breaks down a complex product story into three digestible stages, using sophisticated, scroll-synchronized animations to keep the user engaged. By combining a long-scroll container with a sticky content area and leveraging framer-motion's powerful animation hooks, it delivers a polished and interactive narrative experience that explains the product's value in a dynamic and memorable way. Its architecture is reusable and could be adapted to tell different stories with new text and visual content.

Sources: src/components/ProductNarrative.jsx