dnd-timeline

https://samuel-arbibe.gitbook.io/dnd-timeline
Admin
dnd-timeline is a headless, hook-based UI for creating performant and flexible timelines, built on...
Tokens:7,504
Snippets:59
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### TimelineContext Usage Example

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

An example of using TimelineContext with state management for rows, items, and the time range. It includes an onResizeEnd handler to update item spans.

```typescript
function App(){
  const [rows, setRows] = useRows()
  const [items, setItems] = useItems()
  const [range, setRange] = useState(DEFAULT_TIMEFRAME)
  
  const onResizeEnd = useCallback((event: ResizeEndEvent) => {
      const updatedSpan =
        event.active.data.current.getSpanFromResizeEvent?.(event)

      if (!updatedSpan) return

      const activeItemId = event.active.id

// Only update the changed item. This will cause only the changed items to re-render
      setItems((prev) => prev.map((item) => {
          if (item.id !== activeItemId) return item

          return {
            ...item,
            span: updatedSpan,
          }
      }))
    }, [])
  
  return (
    <TimelineContext
      onResizeEnd={onResizeEnd}
      range={range}
      onRangeChanged={setRange}
    >
      <Timeline rows={rows} items={items} />
    </TimelineContext>
  )
}
```

--------------------------------

### Configure Dynamic Snap Grid

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation

Example of creating a dynamic snap grid using an array of GridSizeDefinition. This allows the snap grid to adapt based on the current range size.

```typescript
  const rangeGridSize: GridSizeDefinition[] = [
    {
      value: hoursToMilliseconds(1),
    },
    {
      value: minutesToMilliseconds(30),
      maxRangeSize: hoursToMilliseconds(24),
    }
  ]
```

--------------------------------

### TimelineContext Usage with State Management

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation

Shows a practical example of using TimelineContext in an App component, managing rows, items, and the visible range, with event handlers for resizing.

```javascript
function App(){
  const [rows, setRows] = useRows()
  const [items, setItems] = useItems()
  const [range, setRange] = useState(DEFAULT_TIMEFRAME)
  
  const onResizeEnd = useCallback((event: ResizeEndEvent) => {
      const updatedSpan = 
        event.active.data.current.getSpanFromResizeEvent?.(event)
  
      if (!updatedSpan) return
  
      const activeItemId = event.active.id
  
// Only update the changed item. This will cause only the changed items to re-render
      setItems((prev) => prev.map((item) => {
          if (item.id !== activeItemId) return item
  
          return {
            ...item,
            span: updatedSpan,
          }
      }))
    }, [])
  
  return (
    <TimelineContext
      onResizeEnd={onResizeEnd}
      range={range}
      onRangeChanged={setRange}
    >
      <Timeline rows={rows} items={items} />
    </TimelineContext>
  )
}
```

--------------------------------

### onDragEnd Event Handler Example

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Illustrates how to implement the onDragEnd event handler, extracting updated span information using a helper function provided by the library.

```typescript
const onDragEnd = (event: DragEndEvent) => {
  const overedId = event.over?.id.toString()
  if (!overedId) return

  const activeItemId = event.active.id

  const updatedSpan =
    event.active.data.current.getSpanFromDragEvent?.(event)
    
  // update your state using the updated span.
}
```

--------------------------------

### Timeline Component Rendering

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Shows a basic Timeline component that utilizes the useTimelineContext hook to get the timeline's ref and style, and maps over provided rows.

```typescript
function Timeline(props: TimelineProps){
  const { setTimelineRef, style } = useTimelineContext()
  
  return (
    <div ref={setTimelineRef} style={style}>
      {props.rows.map((row) => 
        // Render rows here...
      )}
    </div>
  )
}
```

--------------------------------

### Handling Resize Move Events with useItem

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/item/useitem

This example shows how to use the `onResizeMove` callback within the `useItem` hook to update local state with the latest span information during a resize operation. It utilizes `useCallback` for performance optimization.

```typescript
const onResizeMove = useCallback(() => {
  const updatedSpan = event.active.data.current.getSpanFromResizeEvent?.(event)

  // update some local state with the updated-span
}, [])

useItem({
  id: props.id,
  span: props.span,
  onResizeMove,
})
```

--------------------------------

### useTimelineContext API - Screen Position Mapping

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext/usetimelinecontext

Includes `getValueFromScreenX` to map a screen's X-coordinate to a timeline date value and `getDeltaXFromScreenX` to calculate the delta X distance from the timeline's start. These help in inferring time values and relative positions from mouse events.

```typescript
getValueFromScreenX: (screenX: number) => number
```

```typescript
getDeltaXFromScreenX: (screenX: number) => number
```

--------------------------------

### Range Prop Definition

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation

Specifies the structure of the Range prop, which defines the start and end boundaries for the timeline's viewable area.

```typescript
range: Range
```

```typescript
type Range = {
  start: number
  end: number
}
```

--------------------------------

### Range Type Definition

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Defines the TypeScript type for the Range object, specifying the structure for start and end times within the timeline.

```typescript
type Range = {
  start: number
  end: number
}
```

--------------------------------

### Handle Drag End Event for Timeline Rows

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row/userow

This example demonstrates how to handle the `DragEndEvent` when items are dragged within the timeline. It checks the `rowType` to determine if the dragged item belongs to a 'timeline-row' and outlines logic for updating item relevance or row data.

```typescript
const onDragEnd = (event: DragEndEvent) => {
  const updatedRelevance = 
    event.active.data.current.getRelevanceFromDragEvent?.(event)

  const rowType = event.active.data.current.type
  
  if (rowType === 'timeline-row') {
    // update item with id activeItemId with the updatedRelevance, or the updated row using overedId
  }
}
```

--------------------------------

### Wrap App with TimelineContext

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Demonstrates how to wrap your application's timeline components with the TimelineContext provider. This context manages the timeline's state and handles events.

```typescript
function App() {
    return (
        <TimelineContext>
            // You code here
        </TimelineContext>
    )
}
```

--------------------------------

### Implement Pan and Zoom Strategy

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Enables and configures the panning and zooming functionality of the timeline. The default strategy uses mouse wheel events with modifier keys for intuitive control.

```typescript
type UsePanStrategy = (
  timelineRef: React.MutableRefObject<HTMLElement | null>,
  onPanEnd: OnPanEnd
) => void
```

```typescript
type OnPanEnd = (event: PanEndEvent) => void
```

```typescript
type PanEndEvent = {
  clientX?: number
  clientY?: number
  deltaX: number
  deltaY: number
}
```

```typescript
usePanStrategy?: UsePanStrategy = useWheelStrategy
```

--------------------------------

### useItem Hook API

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/item/useitem

Details the parameters and events available for the useItem hook, enabling customization of timeline items.

```APIDOC
## useItem Hook

A hook to declare a timeline item.
Use this hook to declare an HTML element as an item in the timeline.
This hook is based on dnd-kit's useDraggable hook.

### Options

- **`id`** (string) - Required - A unique id to identify this item.
- **`span`** (Span) - Required - An object representing the start and end values of the item.
- **`disabled?`** (boolean) - Optional - An optional boolean to disable the interactivity of the item.
- **`data?`** (object) - Optional - Custom data that can be passed to the row. This can be passed to rows to identify their type. This type can later be used in the event callbacks to apply different behaviors to different row types.
- **`resizeHandleWidth?`** (number) - Optional - An optional resize handler width, in pixels. Defaults to the `resizeHandleWidth` provided to the context. Choosing a larger or a smaller `handleWidth` will change the resize action's sensitivity. If set to 0, resizing will be disabled for the item.

### Events

- **`onResizeStart?`** ((event: ResizeStartEvent) => void) - Callback when resizing starts.
  `type ResizeStartEvent = { active: Omit<Active, 'rect'>, direction: DragDirection }`
- **`onResizeMove?`** ((event: ResizeMoveEvent) => void) - Callback during resizing.
  `type ResizeMoveEvent = { active: Omit<Active, 'rect'>, delta: { x: number }, direction: DragDirection }`
- **`onResizeEnd?`** ((event: ResizeEndEvent) => void) - Callback when resizing ends.
  `type ResizeEndEvent = { active: Omit<Active, 'rect'>, delta: { x: number }, direction: DragDirection }`

### API

All of dnd-kit useDraggable api are returned as well.

- **`itemStyle`** (CSSProperties) - Basic style properties that must be passed to the item wrapper element.
- **`itemContentStyle`** (CSSProperties) - Basic style properties that must be passed to the item's children wrapper element.
```

--------------------------------

### TimelineContext Props Interface

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Defines the TypeScript interface for TimelineContextProps, outlining the available props such as range, overlayed, various event handlers, and DndContext props.

```typescript
interface TimelineContextProps {
    range: Range // { start: number, end: number }
    overlayed?: boolean
    onResizeEnd: OnResizeEnd
    onResizeMove?: OnResizeMove
    onResizeStart?: OnResizeStart
    usePanStrategy?: UsePanStrategy
    onRangeChanged: OnRangeChanged
    rangeGridSizeDefinition?: number | GridSizeDefinition[]
    // ...DndContext Props
}
```

--------------------------------

### Define Grid Size Definition Type

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation

Defines the structure for gridSizeDefinition, allowing custom snap grid configurations with optional maximum range sizes.

```typescript
type GridSizeDefinition = {
  value: number
  maxRangeSize?: number
}
```

--------------------------------

### ResizeStartEvent Type Definition

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Defines the TypeScript type for ResizeStartEvent, detailing the structure of the event object passed to the onResizeStart handler.

```typescript
type ResizeStartEvent = {
  active: Omit<Active, 'rect'>
  direction: DragDirection // 'start' | 'end'
}
```

--------------------------------

### Throttling with a Custom useThrottle Hook

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/zoom-and-pan/performance

This snippet illustrates implementing throttling using a custom `useThrottle` hook. Throttling limits how often a function can be executed, ensuring that updates to the timeline's range occur at a controlled rate. This is another effective method to prevent performance issues caused by rapid state changes.

```typescript
function App() {
  const [range, setRange] = useState(DEFAULT_TIMEFRAME);
  const debouncedRange = useThrottle(range, 300);
  
  ...
  
  return (
    <TimelineContext
        onDragEnd={onDragEnd}
        onResizeEnd={onResizeEnd}
        range={debouncedRange} // provide the debounced range
        onRangeChanged={setRange}
    >
      <Timeline items={items} rows={rows} />
    </TimelineContext>
  )
}
```

```typescript
function Item(props: ItemProps) {
  ...
  const style: CSSProperties = {
    ...itemStyle,
    transition: 'left .2s linear, width .2s linear',
    // You can a CSS transition to make the debounce feel smoother
  }

  return (
    <div ref={setNodeRef} style={style} {...listeners} {...attributes}>
    ...
    </div>
  )
}
```

```typescript
export function useThrottle<T>(value: T, interval = 500) {
  const [throttledValue, setThrottledValue] = useState(value);
  const lastUpdated = useRef<number | null>(null);

  useEffect(() => {
    const now = Date.now();

    if (lastUpdated.current && now >= lastUpdated.current + interval) {
      lastUpdated.current = now;
      setThrottledValue(value);
    } else {
      const id = window.setTimeout(() => {
        lastUpdated.current = now;
        setThrottledValue(value);
      }, interval);

      return () => {
        window.clearTimeout(id)
      };
    }
  }, [value, interval]);

  return throttledValue;
}
```

--------------------------------

### useTimelineContext API - Value and Pixel Conversion

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext/usetimelinecontext

Offers `valueToPixels` to convert timeline values to pixel measurements and `pixelsToValue` to convert pixel measurements back to timeline values. These are essential for positioning and sizing elements within the timeline.

```typescript
valueToPixels: (value: number) => number
```

```typescript
pixelsToValue: (pixels: number) => number
```

--------------------------------

### Define Pan Strategy Hook Type

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation

Defines the type for usePanStrategy, a hook used to enable and configure timeline panning and zooming behavior.

```typescript
type UsePanStrategy = (
  timelineRef: React.MutableRefObject<HTMLElement | null>,
  onPanEnd: OnPanEnd
) => void
```

--------------------------------

### Implement Default Wheel Strategy for Zoom/Pan in TypeScript

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/zoom-and-pan

The default wheel strategy for dnd-timeline. It listens for 'wheel' events on the timeline element, handling zoom (Ctrl+scroll) and pan (Ctrl+Shift+scroll) based on wheel deltas and cursor position.

```typescript
export const useWheelStrategy: UsePanStrategy = (timelineBag, onPanEnd) => {
	useLayoutEffect(() => {
		const element = timelineBag.timelineRef.current;
		if (!element) return;

		const pointerWheelHandler = (event: WheelEvent) => {
			if (!event.ctrlKey && !event.metaKey) return;

			event.preventDefault();

			const isHorizontal = event.shiftKey;

			const panEndEvent: PanEndEvent = {
				clientX: event.clientX,
				clientY: event.clientY,
				deltaX: isHorizontal ? event.deltaX || event.deltaY : 0,
				deltaY: isHorizontal ? 0 : event.deltaY,
			};

			onPanEnd(panEndEvent);
		};

		element.addEventListener("wheel", pointerWheelHandler, { passive: false });

		return () => {
			element.removeEventListener("wheel", pointerWheelHandler);
		};
	}, [onPanEnd, timelineBag.timelineRef]);
};
```

--------------------------------

### Basic Item Component Implementation (React/TypeScript)

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/item

A foundational React component for dnd-timeline's Item. It utilizes the useItem hook for drag-and-drop functionality and accepts an id, span, and children as props. The component renders a div with specific styling and event listeners for drag operations.

```typescript
interface ItemProps {
  id: string
  span: Span
  children: ReactNode
}

function Item(props: ItemProps) {
  const {
    setNodeRef,
    attributes,
    listeners,
    itemStyle,
    itemContentStyle,
  } = useItem({
    id: props.id,
    span: props.span,
  })

  return (
    <div
      ref={setNodeRef}
      style={itemStyle}
      {...listeners}
      {...attributes}
    >
      <div style={itemContentStyle}>
        {props.children}
      </div>
    </div>
  )
}
```

--------------------------------

### Define Grid Size for Timeline Snapping

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Configures and enables snapping behavior in the timeline. Can be a single number for a fixed grid size or an array of GridSizeDefinition objects for dynamic snapping based on range size.

```typescript
type GridSizeDefinition = {
  value: number
  maxRangeSize?: number
}
```

```typescript
rangeGridSizeDefinition?: number | GridSizeDefinition[]
```

```typescript
  const rangeGridSize: GridSizeDefinition[] = [
    {
      value: hoursToMilliseconds(1),
    },
    {
      value: minutesToMilliseconds(30),
      maxRangeSize: hoursToMilliseconds(24),
    }
  ]
```

--------------------------------

### Configure Overlayed Rendering

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Prop to enable or disable the rendering of items during drag operations. Set to true when using dnd-kit's DragOverlay for seamless integration.

```typescript
overlayed?: boolean = false
```

--------------------------------

### useTimelineContext Hook API

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext/usetimelinecontext

The `useTimelineContext` hook provides access to the timeline's state and a set of helper functions for managing its behavior.

```APIDOC
## `useTimelineContext` Hook

### Description
This hook allows access to the timeline's state and provides utility functions for interactions.

### API Details:

- **`style`** (CSSProperties) - A set of mandatory style properties that must be applied to the timeline container element.

- **`timelineRef`** (React.MutableRefObject<HTMLElement | null>) - A ref to the timeline container element.

- **`setTimelineRef`** (function) - A ref setter that must be passed to the timeline's container element. Signature: `(element: HTMLElement | null) => void`

- **`valueToPixels`** (function) - A helper function that converts a value (e.g., time) to its pixel representation within the timeline container. Signature: `(value: number) => number`. Useful for inferring element sizes and positions based on duration.

- **`pixelsToValue`** (function) - A helper function that converts pixel measurements to their equivalent duration or value within the timeline container. Signature: `(pixels: number) => number`. Useful for converting positions/widths to time spans.

- **`getValueFromScreenX`** (function) - A helper function that converts a screen X coordinate to a date representation relative to the timeline container. Signature: `(screenX: number) => number`. Useful for inferring time from mouse events like clicks.

- **`getDeltaXFromScreenX`** (function) - A helper function that calculates the delta X distance from the timeline's start for a given screen X coordinate. Signature: `(screenX: number) => number`. Useful for determining relative positions for custom items from pointer events.

- **`getSpanFromDragEvent`** (function) - Extracts span information from a dnd-kit drag event. Signature: `(event: DragEvent) => Span | null`, where `DragEvent` can be `DragStartEvent`, `DragEndEvent`, `DragCancelEvent`, or `DragMoveEvent`. This function is injected into drag events to infer the dragged item's span.

- **`getSpanFromResizeEvent`** (function) - Extracts span information from a dnd-timeline resize event. Signature: `(event: ResizeEvent) => Span | null`, where `ResizeEvent` can be `ResizeStartEvent`, `ResizeMoveEvent`, or `ResizeEndEvent`. This function is injected into resize events to infer the resized item's span.
```

--------------------------------

### useTimelineContext API - CSSProperties

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext/usetimelinecontext

Provides the `style` property, a set of mandatory CSS properties to be applied to the timeline container element. This is crucial for the correct rendering and behavior of the timeline.

```typescript
style: CSSProperties
```

--------------------------------

### Set Resize Handle Width

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Determines the width of the resize handles in pixels, affecting the sensitivity of the resizing action. Setting this to 0 disables resizing.

```typescript
resizeHandleWidth?: number = 20
```

--------------------------------

### useTimelineContext API - Drag and Resize Event Span Extraction

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext/usetimelinecontext

Provides `getSpanFromDragEvent` and `getSpanFromResizeEvent` to extract span information from drag and resize events respectively. These functions are injected into dnd-kit and dnd-timeline events, enabling state updates based on user interactions.

```typescript
type DragEvent = DragStartEvent | DragEndEvent | DragCancelEvent | DragMoveEvent
```

```typescript
getSpanFromDragEvent: (event: DragEvent) => Span | null
```

```typescript
type ResizeEvent = ResizeStartEvent | ResizeMoveEvent | ResizeEndEvent
```

```typescript
getSpanFromResizeEvent: (event: ResizeEvent) => Span | null
```

```typescript
const onDragEnd = (event: DragEndEvent) => {
  const updatedSpan = event.active.data.current.getSpanFromDragEvent?.(event)
  // update your state using the updated span.
}
```

```typescript
const onResizeEnd = (event: ResizeEndEvent) => {
  const updatedSpan = event.active.data.current.getSpanFromResizeEvent?.(event)
  // update your state using the updated span.
}
```

--------------------------------

### Timeline Row Styles and Refs

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row/userow

This snippet details the CSS properties and React Refs that must be applied to timeline row elements for proper styling and interaction. These include styles for the wrapper, the row itself, and its sidebar, along with a ref for the sidebar element.

```typescript
rowWrapperStyle: CSSProperties
rowStyle: CSSProperties
rowSidebarStyle: CSSProperties
setSidebarRef: React.RefObject<HTMLDivElement>
```

--------------------------------

### Basic CSS for Subrow Element

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row/subrow

These CSS properties are suggested for basic styling of the subrow element to ensure proper stacking and layout. The `height` property should be adjusted based on the specific row height implementation.

```css
position: relative;
height: 50px; // replace with your own row height
```

--------------------------------

### Define Pan End Event Type

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation

Defines the structure for the PanEndEvent, which contains information about the deltaX and deltaY from a panning action.

```typescript
type PanEndEvent = {
  clientX?: number
  clientY?: number
  deltaX: number
  deltaY: number
}
```

--------------------------------

### Basic Row Component in TypeScript

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row

A fundamental React component for the dnd-timeline that acts as a container for items. It extends dnd-kit's Droppable and utilizes the useRow hook for drag-and-drop functionality. It includes slots for sidebar content and the main row items.

```tsx
interface RowProps extends RowDefinition {
  children: React.ReactNode
  sidebar: React.ReactNode
}

function Row(props: RowProps) {
  const {
    setNodeRef,
    setSidebarRef,
    rowWrapperStyle,
    rowStyle,
    rowSidebarStyle,
  } = useRow({ id: props.id })

  return (
    <div style={rowWrapperStyle}>
      <div ref={setSidebarRef} style={rowSidebarStyle}>
        {props.sidebar}
      </div>
      <div ref={setNodeRef} style={rowStyle}>
        {props.children}
      </div>
    </div>
  )
}
```

--------------------------------

### useTimelineContext API - Timeline Refs

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext/usetimelinecontext

Exposes `timelineRef` and `setTimelineRef` for managing the timeline's container element. `timelineRef` provides a mutable ref object to the DOM element, while `setTimelineRef` is a setter function to pass the element ref.

```typescript
timelineRef: React.MutableRefObject<HTMLElement | null>
```

```typescript
setTimelineRef: (element: HTMLElement | null) => void
```

--------------------------------

### App Component with Debounced Range in React Timeline

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/zoom-and-pan/performance

The App component sets up the timeline context, managing the time range and applying a debounce effect to range changes for smoother UI updates. It passes the debounced range to the Timeline component and provides handlers for drag and resize events.

```tsx
function App() {
  const [range, setRange] = useState(DEFAULT_TIMEFRAME);
  const debouncedRange = useDebounce(range, 300)
  
  ...
  
  return (
    <TimelineContext
        onDragEnd={onDragEnd}
        onResizeEnd={onResizeEnd}
        range={debouncedRange} // provide the debounced range
        onRangeChanged={setRange}
    >
      <Timeline items={items} rows={rows} />
    </TimelineContext>
  )
}
```

--------------------------------

### Timeline Item Styling with CSS Transitions in React

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/zoom-and-pan/performance

The Item component defines the visual presentation and interactive behavior of individual items within the timeline. It applies CSS transitions to properties like 'left' and 'width' to ensure a smooth visual response to debounced state changes.

```tsx
function Item(props: ItemProps) {
  ...
  const style: CSSProperties = {
    ...itemStyle,
    transition: 'left .2s linear, width .2s linear',
    // You can a CSS transition to make the debounce feel smoother
  }

  return (
    <div ref={setNodeRef} style={style} {...listeners} {...attributes}>
    ...
    </div>
  )
}
```

--------------------------------

### Timeline Component Usage with Rows

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row

Demonstrates how to render multiple Row components within a Timeline component using React. It maps over an array of row data, passing each row's ID and sidebar content to the custom Row component.

```tsx
const { setTimelineRef, style } = useTimelineContext()

return (
  <div ref={setTimelineRef} style={style}>
    {rows.map((row) => 
      <Row id={row.id} sidebar={<Sidebar row={row} />}> \
        // render row items...
      </Row>
    )}
  </div>
)
```

--------------------------------

### ResizeEndEvent Type Definition

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Defines the TypeScript type for ResizeEndEvent, detailing the structure of the event object passed to the onResizeEnd handler, including delta and direction.

```typescript
type ResizeEndEvent = {
  active: Omit<Active, 'rect'>
  delta: {
    x: number
  }
  direction: DragDirection // 'start' | 'end'
}
```

--------------------------------

### Declaring a Timeline Item with useItem

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/item/useitem

This snippet demonstrates the basic usage of the `useItem` hook to declare an HTML element as a timeline item. It requires an `id` and a `span` object, and can optionally include custom `data` for row identification.

```typescript
useItem({
  id: props.id,
  span: props.span,
  data: { type: 'timeline-item' },
})
```

--------------------------------

### Define Custom Zoom/Pan Strategy Hook in TypeScript

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/zoom-and-pan

Defines the structure for a custom pan strategy hook in dnd-timeline. This hook receives timeline context and a callback for pan end events, specifying how zoom/pan actions are handled.

```typescript
type UsePanStrategy = (
    timelineBag: TimelineBag,
    onPanEnd: OnPanEnd,
) => void

type OnPanEnd = (event: PanEndEvent) => void

type PanEndEvent = {
  clientX?: number
  clientY?: number
  deltaX: number
  deltaY: number
}
```

--------------------------------

### Timeline Component with Subrow Grouping (TypeScript)

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row/subrow

This React component demonstrates how to use the `groupItemsToSubrows` utility to render items in subrows. It iterates through rows and their corresponding subrows, rendering each item within its subrow container. It relies on a `useTimelineContext` hook and expects `items` and `range` to be available.

```typescript
function Timeline(props: TimelineProps) {
  const { setTimelineRef, style, range } = useTimelineContext()

  const groupedSubrows = useMemo(
    () => groupItemsToSubrows(items, range),
    [items, range]
  )

  return (
    <div ref={setTimelineRef} style={style}>
      {props.rows.map((row) => 
        <Row key={row.id} id={row.id} sidebar={<Sidebar row={row} />}>
          {groupedSubrows[row.id]?.map((subrow, index) => 
            <div key={`${row.id}-${index}`}>
              {subrow.map((item) => 
                // Render item here...
              )}
            </div>
          )}
        </Row>
      )}
    </div>
  )
}
```

--------------------------------

### Debouncing with React's useDeferredValue

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/zoom-and-pan/performance

This snippet demonstrates how to use React's `useDeferredValue` hook to defer updates to the timeline's range. This reduces the number of re-renders when the range changes frequently, improving performance during zooming and panning. It's suitable for React 18+ applications.

```typescript
function App() {
  const [range, setRange] = useState(DEFAULT_TIMEFRAME);
  const debouncedRange = useDeferredValue(range);
  
  ...
  
  return (
    <TimelineContext
        onDragEnd={onDragEnd}
        onResizeEnd={onResizeEnd}
        range={debouncedRange} // provide the debounced range
        onRangeChanged={setRange}
    >
      <Timeline items={items} rows={rows} />
    </TimelineContext>
  )
}
```

```typescript
function Item(props: ItemProps) {
  ...
  const style: CSSProperties = {
    ...itemStyle,
    transition: 'left .2s linear, width .2s linear',
    // You can a CSS transition to make the debounce feel smoother
  }

  return (
    <div ref={setNodeRef} style={style} {...listeners} {...attributes}>
    ...
    </div>
  )
}
```

--------------------------------

### ResizeMoveEvent Type Definition

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Defines the TypeScript type for ResizeMoveEvent, detailing the structure of the event object passed to the onResizeMove handler, including delta and direction.

```typescript
type ResizeMoveEvent = {
  active: Omit<Active, 'rect'>
  delta: {
    x: number
  }
  direction: DragDirection // 'start' | 'end'
}
```

--------------------------------

### groupItemsToSubrows API Definition

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row/subrow

This defines the signature for the `groupItemsToSubrows` helper function. It accepts an array of `ItemDefinition` objects and an optional `Span` for range filtering. It returns a `Record` where keys are `rowId`s and values are matrices of `ItemDefinition` arrays, representing subrows.

```typescript
groupItemsToSubrows: 
    (items: ItemDefinition[], range?: Span) =>
    Record<string, ItemDefinition[][]>
```

--------------------------------

### useDebounce Hook for Debouncing Values in React

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/zoom-and-pan/performance

A custom React hook that debounces a given value. It delays updating the state until a specified time has passed without the value changing, preventing rapid re-renders and improving performance, especially for input-driven updates.

```tsx
export function useDebounce<T>(value: T, delay = 500) {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      clearTimeout(handler);
    };
  }, [value, delay]);

  return debouncedValue;
}
```

--------------------------------

### ItemDefinition Type

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row/subrow

Defines the expected structure for an item within the timeline. Each item must have a unique `id`, belong to a `rowId`, and have a `span` property indicating its duration. An optional `disabled` flag can also be included.

```typescript
type ItemDefinition = {
    id: string
    rowId: string
    span: Span
    disabled?: boolean
}
```

--------------------------------

### Handling Drag End Events in dnd-timeline

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/item/useitem

This code illustrates how to handle the `onDragEnd` event when dragging timeline items. It checks the `rowType` and `itemType` to determine whether to update the timeline or display an error message.

```typescript
const onDragEnd = (event: DragEndEvent) => {
  const updatedSpan = event.active.data.current.getSpanFromDragEvent?.(event)

  const rowType = event.active.data.current.type
  
  if (rowType === 'timeline-row' && itemType === 'timeline-item') {
    // update
  }
    
  if (rowType === 'timeline-disabled-row' && itemType === 'timeline-item') {
    // don't update, and pop an error message
  }
}
```

--------------------------------

### Declare a Timeline Row with useRow Hook

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row/userow

This snippet shows how to use the `useRow` hook to declare an HTML element as a row in the timeline. It requires a unique `id` and allows for custom `data` to identify row types.

```typescript
useRow({
  id: props.id,
  data: { type: 'timeline-row' },
})
```

--------------------------------

### Usage of Item Component within a Row (React)

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/item

Demonstrates how to render custom Item components as children of a Row component in dnd-timeline. It shows mapping over a collection of items, passing necessary props like id and span to each Item.

```jsx
<Row id={row.id}>
  {groupedItems[row.id].map((item) => 
    <Item id={item.id} span={item.span}>
      // item content...
    </Item>
  )}
</Row>
```

--------------------------------

### Define onRangeChanged Callback

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/timelinecontext

Defines the type for the onRangeChanged callback function. This function receives an update function as a parameter, which is used to modify the controlled state of the timeline's range.

```typescript
type OnRangeChanged = (
  updateFunction: (prev: Range) => Range
) => void
```

--------------------------------

### Row Definition Type in TypeScript

Source: https://samuel-arbibe.gitbook.io/dnd-timeline/documentation/row

A helper type provided by dnd-timeline that can be extended for Row components. It defines the basic properties required for a row, including a unique identifier and an optional disabled state.

```typescript
type RowDefinition = {
    id: string
    disabled?: boolean
};
```
Tokens:
Raw