Timeline
Hours run left to right across a day or a week, with one row per resource. It suits dispatch boards and room schedules, where the question is who's free when.
This is the TimelineCalendar recipe, showing 6 AM to 10 PM. Drag a job along the hours, drag it up or down to another technician, or stretch either edge. Overlapping jobs in a row stack into lanes, and the overnight retrofit runs off the end of the day.
Add it with the shadcn-vue CLI:
npx shadcn-vue@latest add https://benjivm.github.io/calends/r/timeline-calendar.jsonThe recipe's source
<script lang="ts">
import type { CalendarEventInput, CalendarResource } from '@calends/core';
export interface TimelineCalendarEvent extends CalendarEventInput {
title?: string;
/** Any CSS color, like `var(--chart-1)`, to tint the default bar. Defaults to `primary`. */
color?: string;
}
export interface TimelineCalendarResource extends CalendarResource {
title?: string;
name?: string;
}
</script>
<script
setup
lang="ts"
generic="T extends TimelineCalendarEvent, R extends TimelineCalendarResource"
>
import { nextTick, onMounted, useTemplateRef, watch } from 'vue';
import type {
CalendarEvent,
ResourceId,
TimelineItem,
TimelineRow as TimelineRowData,
WeekDay,
} from '@calends/core';
import {
CalendarRoot,
EventResizeHandle,
Timeline,
TimelineEvent,
TimelineNow,
TimelineRow,
TimelineSelection,
TimelineTrack,
type EventDropDetail,
type RangeSelectDetail,
} from '@calends/vue';
import CalendarToolbar from './CalendarToolbar.vue';
/**
* Hours run left to right across a day or week, with one row per resource, or a single row when
* `resources` is left unset. The `event` slot renders inside the positioned event, which carries
* the state attributes: style its content with `in-data-*` variants.
*/
const props = withDefaults(
defineProps<{
events?: readonly T[];
resources?: readonly R[];
getResourceIds?: (event: T) => readonly ResourceId[] | null | undefined;
resourceLabel?: (resource: R) => string;
resourceHeading?: string;
/** Names a trailing row for events that match no resource; leave unset to drop them. */
unassignedLabel?: string;
view?: 'day' | 'week';
/** First and last hour on each day's stretch of the axis. */
startHour?: number;
endHour?: number;
slotMinutes?: number;
/** Hour the track scrolls to when it first renders, on today if it's in view. */
scrollToHour?: number;
weekStartsOn?: WeekDay;
timeZone?: string;
locale?: string;
/** Lets events be moved and resized; listen for `event-drop` and `event-resize` to commit. */
editable?: boolean;
/** Lets people click or drag across empty hours to select a range; listen for `range-select`. */
selectable?: boolean;
snapMinutes?: number;
canEdit?: (event: T) => boolean;
}>(),
{
events: () => [],
resourceLabel: (resource: TimelineCalendarResource) =>
resource.title ?? resource.name ?? String(resource.id),
resourceHeading: 'Resource',
view: 'day',
startHour: 0,
endHour: 24,
slotMinutes: 60,
scrollToHour: 7,
weekStartsOn: 7,
snapMinutes: 15,
},
);
const emit = defineEmits<{
'event-drop': [detail: EventDropDetail<T>];
'event-resize': [detail: EventDropDetail<T>];
'range-select': [detail: RangeSelectDetail];
}>();
defineSlots<{
toolbar?(): unknown;
resource?(props: { resource: R | null; row: TimelineRowData }): unknown;
event?(props: { event: T; item: TimelineItem; resource: R | null; timeLabel: string }): unknown;
}>();
const date = defineModel<Temporal.PlainDate>('date', {
default: () => Temporal.Now.plainDateISO(),
});
const scroller = useTemplateRef('scroller');
/** Scrolls the track to `scrollToHour`, on today when it's in view. */
function scrollToStart() {
const container = scroller.value;
const day =
container?.querySelector<HTMLElement>('[data-day][data-today]') ??
container?.querySelector<HTMLElement>('[data-day]');
const label = container?.querySelector<HTMLElement>('[data-label-column]');
if (!container || !day) return;
const containerLeft = container.getBoundingClientRect().left;
const dayBox = day.getBoundingClientRect();
const fraction = (props.scrollToHour - props.startHour) / (props.endHour - props.startHour);
const target = dayBox.left - containerLeft + container.scrollLeft + dayBox.width * fraction;
container.scrollLeft = Math.max(target - (label?.offsetWidth ?? 0) - 16, 0);
}
onMounted(scrollToStart);
watch(
() => props.view,
() => nextTick(scrollToStart),
);
/** Inside the views the event and resource types are erased, so the recipe restores its own. */
const sourceOf = (event: CalendarEvent) => event.source as T;
const resourceOf = (row: TimelineRowData) => row.resource as R | null;
const labelFor = (row: TimelineRowData) => {
const resource = resourceOf(row);
return resource ? props.resourceLabel(resource) : props.unassignedLabel;
};
const slotLabel = (minutes: number) =>
Temporal.PlainTime.from({
hour: Math.floor(minutes / 60),
minute: minutes % 60,
}).toLocaleString(props.locale, {
hour: 'numeric',
minute: minutes % 60 ? '2-digit' : undefined,
});
const timeLabel = (event: CalendarEvent) =>
event.allDay
? 'All day'
: event.start.toLocaleString(props.locale, { hour: 'numeric', minute: '2-digit' });
</script>
<template>
<CalendarRoot
v-model:date="date"
:view="view"
:events="events"
:resources="resources"
:get-resource-ids="getResourceIds"
:unassigned="Boolean(unassignedLabel)"
:week-starts-on="weekStartsOn"
:time-zone="timeZone"
:locale="locale"
:slot-min-minutes="startHour * 60"
:slot-max-minutes="endHour * 60"
:slot-minutes="slotMinutes"
:editable="editable"
:selectable="selectable"
:snap-minutes="snapMinutes"
:can-edit="canEdit"
class="flex flex-col gap-3"
@event-drop="emit('event-drop', $event)"
@event-resize="emit('event-resize', $event)"
@range-select="emit('range-select', $event)"
>
<CalendarToolbar>
<slot name="toolbar" />
</CalendarToolbar>
<Timeline
v-slot="{ days, rows }"
:class="[
'overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-xs [--slot-width:4rem]',
resources ? '[--label-width:12rem]' : '[--label-width:0rem]',
]"
>
<div
ref="scroller"
class="overflow-x-auto"
>
<div
class="relative min-w-[calc(var(--label-width)+var(--slot-count)*var(--slot-width))]"
>
<div
class="grid grid-cols-[var(--label-width)_minmax(0,1fr)] border-b border-border bg-muted"
>
<div
data-label-column
class="sticky left-0 z-20 row-span-2 flex items-end bg-muted text-xs font-medium text-muted-foreground"
:class="resources ? 'border-r border-border px-3 py-1.5' : ''"
>
<template v-if="resources">{{ resourceHeading }}</template>
</div>
<div class="relative h-7 border-b border-border">
<div
v-for="day in days"
:key="day.date.toString()"
data-day
:data-today="day.isToday ? '' : undefined"
class="absolute inset-y-0 left-[calc(var(--day-offset)/var(--axis-minutes)*100%)] flex w-[calc(var(--window-minutes)/var(--axis-minutes)*100%)] items-center gap-1.5 border-l border-border px-2 text-xs font-medium text-foreground/80 first:border-l-0 data-today:text-primary"
:style="{ '--day-offset': day.offset }"
>
{{
day.date.toLocaleString(locale, {
weekday: 'short',
month: 'short',
day: 'numeric',
})
}}
</div>
</div>
<div class="relative h-6">
<template
v-for="day in days"
:key="day.date.toString()"
>
<span
v-for="slot in day.slots"
:key="slot"
class="absolute top-1 left-[calc((var(--day-offset)+var(--slot)-var(--slot-min))/var(--axis-minutes)*100%)] pl-1 text-xs text-muted-foreground"
:style="{
'--day-offset': day.offset,
'--slot': slot,
'--slot-min': day.slots[0],
}"
>
{{ slotLabel(slot) }}
</span>
</template>
</div>
</div>
<TimelineRow
v-for="row in rows"
:key="row.resource?.id ?? 'unassigned'"
:row="row"
:aria-label="labelFor(row)"
class="grid min-h-[calc(var(--row-lanes)*1.625rem+0.5rem)] grid-cols-[var(--label-width)_minmax(0,1fr)] border-b border-border last:border-b-0"
>
<div
class="sticky left-0 z-20 flex min-w-0 items-center bg-card"
:class="resources ? 'border-r border-border px-3' : ''"
>
<slot
v-if="resources"
name="resource"
:resource="resourceOf(row)"
:row="row"
>
<span
:class="[
'truncate text-sm font-medium',
row.resource
? 'text-foreground'
: 'text-muted-foreground italic',
]"
>
{{ labelFor(row) }}
</span>
</slot>
</div>
<TimelineTrack
:row="row"
class="relative bg-[linear-gradient(to_right,var(--border)_1px,transparent_1px)] bg-size-[calc(100%/var(--slot-count))_100%]"
>
<TimelineEvent
v-for="item in row.items"
:key="item.event.id"
:item="item"
:resource-id="resources ? (row.resource?.id ?? null) : undefined"
class="absolute top-[calc(0.25rem+var(--event-lane)*1.625rem)] left-[calc(var(--event-offset)+1px)] z-10 h-6 w-[max(calc(var(--event-length)-2px),0.75rem)] rounded-sm data-dragging:pointer-events-none data-dragging:z-30 data-dragging:shadow-lg data-editable:cursor-grab data-editable:select-none data-editable:[-webkit-touch-callout:none] data-ends-after:rounded-r-none data-past:opacity-60 data-starts-before:rounded-l-none"
>
<slot
name="event"
:event="sourceOf(item.event)"
:item="item"
:resource="resourceOf(row)"
:time-label="timeLabel(item.event)"
>
<div
:tabindex="editable ? 0 : undefined"
:style="{ '--event-color': sourceOf(item.event).color }"
class="flex h-full items-center gap-1.5 overflow-hidden rounded-[inherit] border-l-3 border-l-(--event-color) bg-(--event-color)/10 px-1.5 text-xs leading-6 whitespace-nowrap text-foreground outline-none [--event-color:var(--primary)] focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset in-data-highlighted:bg-(--event-color)/20"
>
<span class="min-w-0 truncate font-semibold">
{{ sourceOf(item.event).title ?? item.event.id }}
</span>
<span
class="min-w-0 shrink-[100] truncate text-muted-foreground"
>
{{ timeLabel(item.event) }}
</span>
</div>
</slot>
<EventResizeHandle
v-if="!item.startsBefore"
edge="start"
class="absolute inset-y-0 left-0 z-10 w-1.5 cursor-ew-resize pointer-coarse:w-3"
/>
<EventResizeHandle
v-if="!item.endsAfter"
edge="end"
class="absolute inset-y-0 right-0 z-10 w-1.5 cursor-ew-resize pointer-coarse:w-3"
/>
</TimelineEvent>
<TimelineSelection
:row="row"
class="pointer-events-none absolute inset-y-1 left-(--selection-offset) z-5 w-(--selection-length) rounded-sm bg-primary/15 ring-1 ring-primary/40 ring-inset"
/>
</TimelineTrack>
</TimelineRow>
<div
class="pointer-events-none absolute inset-y-0 right-0 left-(--label-width)"
>
<TimelineNow
class="absolute inset-y-0 left-(--now-offset) z-15 w-0.5 bg-red-500"
/>
</div>
</div>
</div>
</Timeline>
</CalendarRoot>
</template>The axis
<CalendarRoot
view="day"
:events="jobs"
:resources="technicians"
:get-resource-ids="(job) => job.techs"
:slot-min-minutes="6 * 60"
:slot-max-minutes="22 * 60"
:slot-minutes="60"
/>Each day contributes one window, from slot-min-minutes to slot-max-minutes, and the hours outside it aren't drawn. In a week, the seven windows sit end to end, so an overnight job is still one bar, jumping straight from one day's evening to the next morning.
viewisdayorweek.slot-minutessets the header slots (60 by default), not the snapping.- Without
resources, the timeline is a single row holding every event. - All-day events cover their days' whole windows.
Anatomy
<Timeline v-slot="{ days, rows }">
<TimelineRow v-for="row in rows" :row="row">
<TimelineTrack :row="row">
<TimelineEvent
v-for="item in row.items"
:item="item"
:resource-id="row.resource?.id ?? null"
>
<EventResizeHandle edge="start" />
<EventResizeHandle edge="end" />
</TimelineEvent>
<TimelineSelection :row="row" />
</TimelineTrack>
</TimelineRow>
<TimelineNow />
</Timeline>| Primitive | Renders | Notes |
|---|---|---|
Timeline | role="group", labelled with the title | Sets --axis-minutes, --window-minutes, --slot-minutes, and --slot-count. Slot: timeline, days, rows. |
TimelineRow | role="group" | Sets --row-lanes, and data-idle or data-unassigned. |
TimelineTrack | The row's time axis | Drops and selections are measured against its width, so give it the full axis. |
TimelineEvent | One event on the axis | Sets --event-offset and --event-length (percentages), --event-start and --event-end (axis minutes), and --event-lane. |
TimelineSelection | Only in the row being selected | Sets --selection-offset, --selection-length, --selection-start, and --selection-end. |
TimelineNow | Only while now is inside a visible window | Sets --now-offset, and --now in axis minutes. |
Each entry in days has an offset (where its window starts on the axis) and slots (the header slot starts, as minutes from midnight), for drawing the header.
--event-offset and --event-length are percentages of the axis, so they place an event as they are:
left: var(--event-offset);
width: var(--event-length);The axis-minute values behind them work against --axis-minutes for anything else.
Keyboard
With editable, Space picks a focused event up. Left and Right move it by snap-minutes, Up and Down move it to the previous or next row, Shift with Left or Right changes its end, Space drops it, and Escape puts it back.
Interactions
This covers what's particular to the view. Interactions covers the rest.
Drags snap to snap-minutes. As in the resource view, a drop in another row adds resourceId and previousResourceId to event-drop. A selection can cross days in the week view, and range-select reports zoned start and end with the row's resourceId.