Add docs for TIME_AXIS_MARKERS and markerSideDeltas

[colehart]

Hello, I'm using your package for a use-case that requires 4 digit time markers and a colon (i.e., 02:00 for 2am). I'm running into issues when I zoom with the numbers running together at the beginning of a new zoom breakpoint:

I started problem-solving by attempting to add marginLeft to the markers being mapped in the component, but that didn't do anything to the individual divs. It just added margin to the time axis as a whole (at least everything right of the sidebar). I'm also concerned that messing with the marker spacing and those div widths could make the time cursor inaccurate.

I've been playing with a custom usePanStrategy deltaY multiplier to give it more room between time markers when a user scrolls, tho this is a little janky as an experience, and I've also looked at eliminating some time markers from the default TIME_AXIS_MARKERS array, but I don't feel confident enough that I understand what they are to do that.

I'm pretty confused with what is happening between the TIME_AXIS_MARKERS values and how the markers are being calculated in the TimeAxis component, particularly multiplier stuff in the for loop. I'm really having to slow down and take it line by line, console.logging all of the vars and zooming to different levels to understand how these are correlating to what is on the screen.

Writing this issue out has helped me grasp it a little better:

• timeframe represents the start and end times of the current zoom level
• delta is the smallest value (in milliseconds) of the TIME_AXIS_MARKERS array

why is startTime calculated the way it is with the flooring and references to the delta? I noticed endTime doesn't .ceil or reference the delta

• the for loop is grabbing the first TIME_AXIS_MARKER entry whose value is an even dividend of the floored start time and is within the marker's maxTimeframeSize and minTimeframeSize if both are present, are above the min or below the max if only one is present, or are an element where neither are present

why do some TIME_AXIS_MARKER entries not have a max/minTimeframeSize?

• the rest of the multiplier stuff is to get the marker to the correct position from the start time of the zoomed timeframe

I'm still curious about the above questions, as well as the need in my use-case to have both the date labeled as well as 00:00. I'm thinking I may need to have two time-axes in my app, one for just dates (above the hourly markers) that sticks as you scroll through a 24 hr period. Here's the design I'm working off of.

Thanks for considering my suggestions and answering any questions. I'm also happy to help contribute to this request if you'd like any assistance

[colehart]

Oh, another question I had about zoom and pan is if there's a way to have a max/min zoom? For example, I don't want users to be able to pan to less than 15 min markers or more than 2 days

Again assuming that's somewhere in the TIME_AXIS_MARKERS values, but also thinking the limiting would be something I need to change via css or custom PanStrategy

[samuelarbibe]

Hey!

1. The time axis is a private implmentation that uses the library but is not a part of it. Therefore, there is no documentation for it. That being said, I have already implemented in the past a time axis that looks and behaves just like the design you are working off. If you want, I can try and replicate it and send you the code.
2. You can very simply set limits for zooming and panning via the setTimeframe function: when zooming or panning, the onTimeframeChanged callback is being called with an updater function. therfore, you can very simply check if the updated timeframe is valid, and only if valid actaully procceed with the state object.

Feel free to contact me if you need further help :)

[colehart]

Hi, Samuel! 1. Oh, that would be awesome. 2. Sweet – thanks for the info there. Thank you!

[samuelarbibe]

 const markers = useMemo(() => {
    // sort the markers from large to small.
    const sortedMarkers = [...props.markers];
    sortedMarkers.sort((a, b) => b.value - a.value);

    // the smallest marker size, in ms
    const delta = sortedMarkers[sortedMarkers.length - 1].value;

    // the total timeframe size/
    const timeframeSize = timeframe.end.getTime() - timeframe.start.getTime();

    const startTime = Math.floor(timeframe.start.getTime() / delta) * delta;

    const endTime = timeframe.end.getTime();
    const timezoneOffset = minutesToMilliseconds(
      new Date().getTimezoneOffset(),
    );

    const markerSideDeltas: Marker[] = [];

    // Here, we "walk" from the start of the timeframe to the end of it,
    // and on every step we check if a marker should be placed there.
    // A marker "should" be placed in a certain location if it divides the current location's time
    // without remainder.
    // using the findIndex function, we find the largest matching marker, 
    // because the sortedMarkers is sorted from large to small.
    // that way, if on 24:00 we have both an hour marker and a day marker, we only display the day. 
    for (let time = startTime; time <= endTime; time += delta) {
      const multiplierIndex = sortedMarkers.findIndex(
        (marker) =>
          (time - timezoneOffset) % marker.value === 0 &&
          (!marker.maxTimeframeSize ||
            timeframeSize <= marker.maxTimeframeSize) &&
          (!marker.minTimeframeSize ||
            timeframeSize >= marker.minTimeframeSize),
      );

      if (multiplierIndex === -1) continue;

      // optional: use the index of the selected marker to adjust it's height relativly to other markers.
      const multiplier = sortedMarkers[multiplierIndex];

      const label = multiplier.getLabel?.(new Date(time));

      // push the marker to the array
      markerSideDeltas.push({
        label,
        heightMultiplier: 1 / (multiplierIndex + 1),
        sideDelta: millisecondsToPixels(time - timeframe.start.getTime()),
      });
    }

    return markerSideDeltas;
  }, [timeframe, millisecondsToPixels, props.markers]);

[samuelarbibe]

Hello, I'm using your package for a use-case that requires 4 digit time markers and a colon (i.e., 02:00 for 2am). I'm running into issues when I zoom with the numbers running together at the beginning of a new zoom breakpoint:

I started problem-solving by attempting to add marginLeft to the markers being mapped in the component, but that didn't do anything to the individual divs. It just added margin to the time axis as a whole (at least everything right of the sidebar). I'm also concerned that messing with the marker spacing and those div widths could make the time cursor inaccurate.

I've been playing with a custom usePanStrategy deltaY multiplier to give it more room between time markers when a user scrolls, tho this is a little janky as an experience, and I've also looked at eliminating some time markers from the default TIME_AXIS_MARKERS array, but I don't feel confident enough that I understand what they are to do that.

I'm pretty confused with what is happening between the TIME_AXIS_MARKERS values and how the markers are being calculated in the TimeAxis component, particularly multiplier stuff in the for loop. I'm really having to slow down and take it line by line, console.logging all of the vars and zooming to different levels to understand how these are correlating to what is on the screen.

Writing this issue out has helped me grasp it a little better:

• timeframe represents the start and end times of the current zoom level
• delta is the smallest value (in milliseconds) of the TIME_AXIS_MARKERS array

why is startTime calculated the way it is with the flooring and references to the delta? I noticed endTime doesn't .ceil or reference the delta

• the for loop is grabbing the first TIME_AXIS_MARKER entry whose value is an even dividend of the floored start time and is within the marker's maxTimeframeSize and minTimeframeSize if both are present, are above the min or below the max if only one is present, or are an element where neither are present

why do some TIME_AXIS_MARKER entries not have a max/minTimeframeSize?

• the rest of the multiplier stuff is to get the marker to the correct position from the start time of the zoomed timeframe

I'm still curious about the above questions, as well as the need in my use-case to have both the date labeled as well as 00:00. I'm thinking I may need to have two time-axes in my app, one for just dates (above the hourly markers) that sticks as you scroll through a 24 hr period. Here's the design I'm working off of.

Thanks for considering my suggestions and answering any questions. I'm also happy to help contribute to this request if you'd like any assistance

In your design, I see that you need to render the day and the hour marker differently.
In that case, I would deffinitly separate them into 2 different time axis.

The simplest solution I can think of, rendering the TimeAxis twice, with different timeAxisMarkers, and also pass through some styling.
You can also separate them into 2 different TimeAxis components, up to you!

(there is also a "fake" hour marker in the daily because of a bug I just discovered... the % method doesn't work with markers greater of equal then days because of changing UTC offsets...)

And it looks something like that:

Add a bit of styling... and thats it!

[colehart]

Dope - thank you!

[colehart]

How would you make the date "sticky" to whatever pan level is shown?

I need the current date to always show at the left of the time axis and then scroll off to the new one once the date changes.

I've got two time axes rendering at the moment with the following markers:

// note: our package uses luxon for date formatting, so I converted from date-fns
export const MONTH_TIME_AXIS_MARKERS: MarkerDefinition[] = [
  {
    value: hoursToMilliseconds(24),
    getLabel: (date: Date) => DateTime.fromJSDate(date).toFormat('dd LLL yyyy'),
  },
];

export const TIME_AXIS_MARKERS: MarkerDefinition[] = [
  {
    value: hoursToMilliseconds(2),
    minTimeframeSize: hoursToMilliseconds(24),
    getLabel: (date: Date) => DateTime.fromJSDate(date).toFormat('T'),
  },
  {
    value: hoursToMilliseconds(1),
    maxTimeframeSize: hoursToMilliseconds(32),
    getLabel: (date: Date) => DateTime.fromJSDate(date).toFormat('T'),
  },
  {
    value: minutesToMilliseconds(30),
    maxTimeframeSize: hoursToMilliseconds(15),
    getLabel: (date: Date) => DateTime.fromJSDate(date).toFormat('T'),
  },
  {
    value: minutesToMilliseconds(15),
    maxTimeframeSize: hoursToMilliseconds(7),
    getLabel: (date: Date) => DateTime.fromJSDate(date).toFormat('T'),
  },
  {
    value: minutesToMilliseconds(1),
    maxTimeframeSize: hoursToMilliseconds(2),
  },
];

[samuelarbibe]

You have 2 options:

1. Use the CSS position: sticky attribute. Should work just fine.
2. Use a different component to display the current day statically.