refactor: behavior of marker/pointer positioning

Author: stampaaaron

src/components/Timeline.css

@@ -4,7 +4,6 @@
   --marker-size: 1rem;
   --marker-color: var(--line-color);
   --marker-radius: 50%;
-  --marker-offset: 3rem;
   --pointer-height: 2rem;
   --pointer-width: 1rem;
   --card-background: whitesmoke;
@@ -43,10 +42,6 @@
   right: 0;
 }
 
-.timeline-item__marker {
-  margin-top: var(--marker-offset);
-}
-
 .timeline-item__marker:not(.timeline-item__marker--custom) {
   border-radius: var(--marker-radius);
   width: var(--marker-size);
@@ -86,7 +81,6 @@
 }
 
 .timeline-card__pointer {
-  top: var(--marker-offset);
   transform: translate(100%, -50%);
   position: absolute;
 }

src/components/Timeline.tsx

@@ -1,6 +1,6 @@
 import './Timeline.css';
 import { Key, ReactElement, useEffect, useRef } from 'react';
-import { PropsWithKey, TimelineItem, TimelineItemProps } from './TimelineItem';
+import { PropsWithKey, TimelineItem, TimelineItemProps, TimelineItemRefs } from './TimelineItem';
 import { OffsetConfig, resolveOffsets } from '../models/offset';
 import { Positioning } from '../models/positioning';
 import { convertToCssVariable, StyleConfig } from '../models/style';
@@ -11,6 +11,7 @@ export type TimelineProps = {
   gap?: number;
   offset?: OffsetConfig;
   minMarkerGap?: number;
+  defaultPointerOffset?: number;
   dateFormat?: string;
   dateLocale?: Locale;
   customMarker?: ReactElement;
@@ -23,18 +24,32 @@ const defaultTimelineConfig: Partial<TimelineProps> = {
   positioning: 'alternating',
   gap: 50,
   offset: 50,
-  minMarkerGap: 100,
+  minMarkerGap: 50,
+  defaultPointerOffset: 40,
   dateFormat: 'P',
 };
 
 export function Timeline(props: TimelineProps) {
-  const { items, positioning, gap, offset, minMarkerGap, className, dateFormat, dateLocale, customMarker, customPointer, styleConfig } = {
+  const {
+    items,
+    positioning,
+    gap,
+    offset,
+    minMarkerGap,
+    defaultPointerOffset,
+    className,
+    dateFormat,
+    dateLocale,
+    customMarker,
+    customPointer,
+    styleConfig,
+  } = {
     ...defaultTimelineConfig,
     ...props,
   };
 
   const timelineRef = useRef<HTMLDivElement>(null);
-  const itemsRef = useRef<Map<Key, HTMLElement>>();
+  const itemsRef = useRef<Map<Key, TimelineItemRefs>>();
 
   function getRefMap() {
     if (!itemsRef.current) {
@@ -61,26 +76,34 @@ export function Timeline(props: TimelineProps) {
     let leftHeight = left;
     let rightHeight = right;
 
-    elements.forEach((item) => {
-      const element = item;
+    let nextMarkerOffset = defaultPointerOffset ?? 0;
 
-      if ((positioning !== 'right' && leftHeight > rightHeight) || positioning === 'left') {
-        leftHeight += getMinMarkerGapCompensation(leftHeight, rightHeight);
+    elements.forEach((refs) => {
+      const { item, pointer, marker } = refs;
+      if (!item || !pointer || !marker) return;
 
-        element.style.top = `${rightHeight}px`;
-        element.classList.add('timeline-item--right');
-        element.classList.remove('timeline-item--left');
-        rightHeight += element.offsetHeight + (gap ?? 0);
-      } else {
-        rightHeight += getMinMarkerGapCompensation(leftHeight, rightHeight);
+      // offsets marker + pointer if it would get in the way of the last marker
+      pointer.style.top = `${nextMarkerOffset}px`;
+      marker.style.marginTop = `${nextMarkerOffset}px`;
+
+      const markerOffsetCompensation = getMinMarkerGapCompensation(leftHeight, rightHeight);
+      nextMarkerOffset = markerOffsetCompensation + (defaultPointerOffset ?? 0);
 
-        element.style.top = `${leftHeight}px`;
-        element.classList.add('timeline-item--left');
-        element.classList.remove('timeline-item--right');
-        leftHeight += element.offsetHeight + (gap ?? 0);
+      // defines whether an item should be positioned left or right of the timeline
+      if ((positioning !== 'right' && leftHeight > rightHeight) || positioning === 'left') {
+        item.style.top = `${rightHeight}px`;
+        item.classList.add('timeline-item--right');
+        item.classList.remove('timeline-item--left');
+        rightHeight += item.offsetHeight + (gap ?? 0);
+      } else {
+        item.style.top = `${leftHeight}px`;
+        item.classList.add('timeline-item--left');
+        item.classList.remove('timeline-item--right');
+        leftHeight += item.offsetHeight + (gap ?? 0);
       }
     });
 
+    // update height of container element to match absolute positioned timeline
     const timelineElement = timelineRef.current;
     if (timelineElement) {
       timelineElement.style.height = `${Math.max(leftHeight, rightHeight)}px`;

src/components/TimelineItem.tsx

@@ -1,10 +1,12 @@
-import { forwardRef, Key, PropsWithChildren, ReactElement } from 'react';
+import { forwardRef, Key, PropsWithChildren, ReactElement, useRef, useImperativeHandle } from 'react';
 import { format } from 'date-fns';
 
 export type PropsWithKey<T> = T & {
   key: Key;
 };
 
+export type TimelineItemRefs = { pointer: HTMLDivElement | null; item: HTMLDivElement | null; marker: HTMLDivElement | null };
+
 export type TimelineItemProps = PropsWithChildren<{
   className?: string;
   date: Date | string;
@@ -15,13 +17,27 @@ export type TimelineItemProps = PropsWithChildren<{
   customPointer?: ReactElement;
 }>;
 
-export const TimelineItem = forwardRef<HTMLDivElement, TimelineItemProps>(
+export const TimelineItem = forwardRef<TimelineItemRefs, TimelineItemProps>(
   ({ className, title, date, children, dateFormat, dateLocale, customMarker, customPointer }, ref) => {
+    const itemRef = useRef<HTMLDivElement>(null);
+    const pointerRef = useRef<HTMLDivElement>(null);
+    const markerRef = useRef<HTMLDivElement>(null);
+
+    useImperativeHandle(ref, () => ({
+      item: itemRef.current,
+      pointer: pointerRef.current,
+      marker: markerRef.current,
+    }));
+
     return (
-      <div ref={ref} className={['timeline-item', className].join(' ')}>
-        <div className={['timeline-item__marker', customMarker && 'timeline-item__marker--custom'].join(' ')}>{customMarker}</div>
+      <div ref={itemRef} className={['timeline-item', className].join(' ')}>
+        <div ref={markerRef} className={['timeline-item__marker', customMarker && 'timeline-item__marker--custom'].join(' ')}>
+          {customMarker}
+        </div>
         <div className="timeline-card">
-          <div className={['timeline-card__pointer', customPointer && 'timeline-card__pointer--custom'].join(' ')}>{customPointer}</div>
+          <div ref={pointerRef} className={['timeline-card__pointer', customPointer && 'timeline-card__pointer--custom'].join(' ')}>
+            {customPointer}
+          </div>
           <p className="timeline-card__date">{date instanceof Date ? format(date, dateFormat ?? 'P', { locale: dateLocale }) : date}</p>
           <p className="timeline-card__title">{title}</p>
           {children}

src/models/style.ts

@@ -9,7 +9,6 @@ export type StyleConfig = {
     size?: string;
     color?: string;
     radius?: string;
-    offset?: string;
   };
   pointer?: {
     height?: string;