feat: add stylelint configuration and implement sticky toolbar feature in timeline components

Author: gcodeprabhu

.stylelintrc.json

@@ -0,0 +1,65 @@
+{
+  "customSyntax": "postcss-styled-syntax",
+  "extends": [
+    "stylelint-config-recommended",
+    "stylelint-config-recess-order"
+  ],
+  "rules": {
+    "alpha-value-notation": "number",
+    "color-function-notation": "modern",
+    "color-hex-case": "lower",
+    "color-hex-length": "short",
+    "color-no-invalid-hex": true,
+    "declaration-block-no-duplicate-properties": true,
+    "declaration-block-no-redundant-longhand-properties": true,
+    "declaration-block-single-line-max-declarations": 1,
+    "font-family-name-quotes": "always-unless-keyword",
+    "function-calc-no-unspaced-operator": true,
+    "function-linear-gradient-no-nonstandard-direction": true,
+    "function-name-case": "lower",
+    "length-zero-no-unit": true,
+    "max-nesting-depth": 3,
+    "no-descending-specificity": null,
+    "no-duplicate-selectors": true,
+    "no-empty-source": null,
+    "no-invalid-double-slash-comments": null,
+    "number-leading-zero": "always",
+    "property-no-vendor-prefix": [
+      true,
+      {
+        "ignoreProperties": ["appearance", "background-clip", "backdrop-filter"]
+      }
+    ],
+    "selector-class-pattern": null,
+    "selector-id-pattern": null,
+    "selector-max-id": 0,
+    "selector-no-vendor-prefix": true,
+    "selector-pseudo-class-no-unknown": [
+      true,
+      {
+        "ignorePseudoClasses": ["global", "local"]
+      }
+    ],
+    "shorthand-property-no-redundant-values": true,
+    "string-quotes": "single",
+    "unit-no-unknown": true,
+    "value-keyword-case": [
+      "lower",
+      {
+        "ignoreKeywords": ["currentColor"]
+      }
+    ],
+    "value-no-vendor-prefix": true
+  },
+  "ignoreFiles": [
+    "node_modules/**/*",
+    "dist/**/*",
+    "coverage/**/*",
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.jsx",
+    "**/*.css.ts",
+    "**/*.css.js"
+  ]
+}

MIGRATION.md

@@ -975,6 +975,7 @@ const handleFullscreenChange = (isFullscreen) => {
 | `uniqueId`              | `string`              |         | Sets a custom unique ID for the timeline wrapper. Useful with `noUniqueId={true}`.                              |
 | `disableToolbar`        | `boolean`             | `false` | Hides the entire toolbar/control panel.                                                                         |
 | `toolbarPosition`       | `'top'` or `'bottom'` | `'top'` | Positions the toolbar at the top or bottom of the timeline.                                                     |
+| `stickyToolbar`         | `boolean`             | `false` | Makes the toolbar sticky at the top while scrolling, keeping controls visible for long timelines.              |
 | `highlightCardsOnHover` | `boolean`             | `false` | Highlights timeline cards on mouse hover.                                                                       |
 
 ## 🎨 Customization

README.md

@@ -32,7 +32,18 @@ function convertToLegacyProps(props: TimelinePropsV2): TimelineProps {
     activeItemIndex: props.activeItemIndex,
     allowDynamicUpdate: props.allowDynamicUpdate,
     uniqueId: props.id,
-    onItemSelected: props.onItemSelected,
+    onItemSelected: props.onItemSelected ? 
+      (data: any) => {
+        // Convert from legacy flat structure to new nested structure
+        if ('item' in data) {
+          // Already in new format
+          props.onItemSelected!(data);
+        } else {
+          // Convert from legacy format
+          const { index, ...item } = data;
+          props.onItemSelected!({ item, index });
+        }
+      } : undefined,
     onScrollEnd: props.onScrollEnd,
     onThemeChange: props.onThemeChange as any,
     onRestartSlideshow: props.onRestartSlideshow,
@@ -402,7 +413,9 @@ const Chrono: React.FunctionComponent<ChronoProps> = (
     // This prevents unwanted resets during dynamic loading and circular updates
     if (activeItemIndex !== previousActiveItemIndexRef.current) {
       previousActiveItemIndexRef.current = activeItemIndex;
-      handleTimelineUpdate(activeItemIndex);
+      if (activeItemIndex !== undefined) {
+        handleTimelineUpdate(activeItemIndex);
+      }
     }
   }, [activeItemIndex, handleTimelineUpdate]);
 
@@ -427,15 +440,15 @@ const Chrono: React.FunctionComponent<ChronoProps> = (
     if (!timeLineItems.length) {
       return;
     }
-    if (activeTimelineItem < timeLineItems.length - 1) {
+    if (activeTimelineItem !== undefined && activeTimelineItem < timeLineItems.length - 1) {
       const newTimeLineItem = activeTimelineItem + 1;
 
       // Update timeline state and trigger smooth navigation
       handleTimelineUpdate(newTimeLineItem);
       setActiveTimelineItem(newTimeLineItem);
 
       if (
-        mode === 'HORIZONTAL' &&
+        mapNewModeToLegacy(mode) === 'HORIZONTAL' &&
         slideShowActive &&
         items &&
         items.length - 1 === newTimeLineItem
@@ -453,7 +466,7 @@ const Chrono: React.FunctionComponent<ChronoProps> = (
   ]);
 
   const handleOnPrevious = useCallback(() => {
-    if (activeTimelineItem > 0) {
+    if (activeTimelineItem !== undefined && activeTimelineItem > 0) {
       const newTimeLineItem = activeTimelineItem - 1;
 
       // Update timeline state and trigger smooth navigation
@@ -537,7 +550,7 @@ const Chrono: React.FunctionComponent<ChronoProps> = (
           id="testette"
         >
           <Timeline
-            activeTimelineItem={activeTimelineItem}
+            activeTimelineItem={activeTimelineItem ?? 0}
             contentDetailsChildren={contentDetailsChildren}
             iconChildren={iconChildren}
             items={timeLineItems}
@@ -553,7 +566,7 @@ const Chrono: React.FunctionComponent<ChronoProps> = (
             slideItemDuration={slideItemDuration}
             {...pickDefined({
               onScrollEnd,
-              onItemSelected,
+              onItemSelected: legacyProps.onItemSelected,
             })}
             onOutlineSelection={handleOutlineSelection}
             mode={mapNewModeToLegacy(mode)}

src/components/index.tsx

@@ -246,7 +246,7 @@ globalStyle(`${shape} img`, {
 // Timeline title container using new patterns
 export const timelineTitleContainer = recipe({
   base: [
-    patterns.text({ variant: 'title' }),
+    patterns.text({ variant: 'h3' }),
     sprinkles({
       display: 'flex',
       alignItems: 'center',
@@ -294,7 +294,7 @@ export const timelineTitleContainer = recipe({
 
 // Base timeline content container using new system
 const baseTimelineContentContainer = style([
-  patterns.card({ size: 'md', elevation: 'medium' }),
+  patterns.card({ size: 'md', elevation: 'low' }),
   sprinkles({
     alignItems: 'flex-start',
   }),
@@ -408,7 +408,7 @@ globalStyle(`${timelineContentContainer}.vertical`, {
 
 // Card container using new unified system
 export const cardContainer = style([
-  patterns.card({ size: 'lg', elevation: 'medium' }),
+  patterns.card({ size: 'lg', elevation: 'low' }),
   sprinkles({
     display: 'flex',
     flexDirection: 'column',

src/components/timeline-elements/timeline-card/timeline-horizontal-card-ve.css.ts

@@ -59,7 +59,7 @@ const TimelineCard: React.FunctionComponent<TimelineCardModel> = ({
   } = useTimelineCard({
     cardLess,
     showAllCardsHorizontal,
-    mode,
+    mode: mode as 'HORIZONTAL' | 'VERTICAL' | 'VERTICAL_ALTERNATING' | 'HORIZONTAL_ALL',
     position,
     iconChild,
     ...pickDefined({

src/components/timeline-elements/timeline-card/timeline-horizontal-card.tsx

@@ -118,7 +118,7 @@ const QuickJump: FunctionComponent<QuickJumpProp> = ({
 
   return (
     <PopOver
-      placeholder={buttonTexts?.jumpToTimeline || "Jump to timeline item"}
+      placeholder={buttonTexts?.jumpTo || "Jump to timeline item"}
       position={position}
       theme={theme}
       width={400}

src/components/timeline/timeline-popover-elements.tsx

@@ -640,7 +640,7 @@ const Timeline: React.FunctionComponent<TimelineModel> = (
             console.error('Fullscreen error:', error);
             setIsFullscreen(false);
           }}
-          stickyToolbar={props.stickyToolbar}
+          stickyToolbar={props.stickyToolbar ?? false}
         />
       )}
 

src/components/timeline/timeline.tsx

@@ -64,6 +64,8 @@ export const componentContainerTree = style({
   borderRadius: '4px',
   height: '300px',
   margin: '0 auto',
+  width: "100%",
+  border: '1px solid #ccc',
 });
 
 export const componentContainerTreeDesktop = style([

src/demo/App.css.ts

@@ -49,10 +49,10 @@ export const AlternatingVertical: FunctionComponent<AlternatingVerticalProps> =
 
         display={{
           toolbar: { 
-            enabled: true
+            enabled: true,
+            sticky: true
           },
         }}
-        stickyToolbar={true}
 
         animation={{
           slideshow: {