Skip to main content

registerScaleUnit

Description​

Allows adding a custom scale unit

Usage​

registerScaleUnit( 
    unit: string, 
    config: { 
      start: (date: Date) => Date,
      end: (date: Date) => Date,
      isSame: (date1: Date, date2: Date) => boolean,
      add: (date: Date, num: number) => Date,diff?: (date1: Date, date2: Date) => number,
      smallerCount?: {
        [key: TLengthUnit]: number | ((date: Date) => number),
    },
      biggerCount?: {
        [key: TLengthUnit]: number | ((date: Date) => number),
  };},
): void;

Parameters​

  • unitName - (required) the name of a new unit
  • config - (required) an object that contains date handlers for a new unit. These handlers are:

    • start - (required) gets a start unit date (Date) and returns Date. For example, if date is 5 Apr 2025, "start" for the "month" unit should return 1 Apr 2025 for this date.

    • end - (required) gets an end unit date (Date) and returns Date. For example, if date is 5 Apr 2025, "end" for the "month" unit should return 30 Apr 2025 for this date.

    • isSame - (required) gets two Dates and returns true if both dates belong to the same unit. Usage: isSame(date1: Date, date2: Date): boolean. For example, if dates are 10 Apr 2025 and 20 Apr 2025, "isSame" should return true for "month" unit.

    • add - (required) adds a certain amount of units to a date and returns the new date. Usage: add(date: Date, amount: number): Date. For example, if date is 1 Apr 2025 and amount 2, the "add" method should return 1 Jun 2025 for "month" unit.

    • diff - (optional) calculates the number of units between end and start dates. Usage: diff(endDate: Date, startDate: Date): number. For example, for "week" scale unit diff returns a difference in weeks for two dates.

    • smallerCount (object) - (optional) defines a structured representation for smaller time units and contains respective calculations. A unit can be a number or a function that takes Date and returns the number of units for it. For example, smallerCount for "year" unit is as follows:

      {
        quarter: 4,
        month: 12,
        week: getISOWeeksInYear,
        day: (date?: Date): number {
            if (date) return getDaysInYear(date);
            return 365;
        },
        hour: (date: Date): number {
            if (date) return getDaysInYear(date) * 24;
            return 365*24;
        }
      },

    • biggerCount (object) - (optional) defines a structured representation for bigger time units and contains respective calculations for number of custom units in bigger units. For example, biggerCount for "month" unit is as follows:

      {
        year: 12,
        quarter: 3,
      }

Only first 4 handlers should be defined for any new unit. If a unit is not planned as the last scale unit, it can be registered without "diff", "smallerCount" and "biggerCount" properties.

Example​

Let's consider an example of adding "sprint" unit that splits months in half and groups days. The top level scale is "month", the second one is "sprint" and the minimal is "day" unit.

<script>
  import { Gantt, registerScaleUnit} from "@svar-ui/svelte-gantt";
  import { differenceInDays, startOfMonth, endOfMonth, format } from "date-fns";

  function getMidDate(date) {
  const m = date.getMonth();
  return m === 1 ? 15 : 16;
  }

  const sprintStart = d => {
  const monthStart = startOfMonth(d);
  const midDate = getMidDate(d);
  if (d.getDate() >= midDate) monthStart.setDate(midDate);
  return monthStart;
  };

  const sprintEnd = d => {
  const end = endOfMonth(d);
  const midDate = getMidDate(d);
  if (d.getDate() < midDate) end.setDate(midDate);
  return end;
  };

  registerScaleUnit("sprint", {
  start: sprintStart,
  end: sprintEnd,
  isSame: (a, b) => {/*check whether both dates are from the same sprint*/...},
  add: (d, amount) => {/*add a certain amount of sprints to a date*/...},
  diff: (endDate, startDate) => {
    return Math.floor(differenceInDays(endDate, startDate) / 15);
   },
  smallerCount: {
  day: d => {
    if (!d) return 15;
    const start = sprintStart(d).getDate();
    const end = sprintEnd(d).getDate();
    return end - start + 1;
   }, 
  },
  biggerCount: {
    year: 24,
    quarter: 6,
    month: 2,
   },
  });

  const scale = [
  { unit: "month", step: 2, format: "MMMM yyy" },
  {
    unit: "sprint",
    step: 1,
    format: d => {
      const monthStr = format(d, "MMMM");
      const start = d.getDate();
      const end = sprintEnd(d).getDate();
      return `${monthStr} ${start} - ${end}`;
    },
  },
  { unit: "day", step: 1, format: "d"},
  ];
</script>

Related articles: