Timeline view

Resources as rows on a horizontal time axis. Overlapping events in a row stack, and the row grows to fit them. An event that crosses midnight is one bar.

import { timelineView } from '@calendar-tsx/core';

timelineView({ days: 7, groupBy: 'resource' }); // a week, one row per resource
timelineView({ days: 1, groupBy: 'resource', slotMinutes: 30 }); // a day
timelineView({ period: 'month', groupBy: 'resource', slotMinutes: 1440, minSlotWidth: '6rem' });
timelineView({ period: 'year', slotMinutes: 1440, minSlotWidth: '6rem' });

Nested resourcesCopy Anchor Link

Set a resource's parentId to another resource ID. Parents remain schedulable resources. Events, backgrounds and availability use direct resource IDs; collapsing a parent hides its descendants without moving their events into the parent row.

Register resourceExpansionFeature to enable expansion actions. Resources start expanded by default:

import { calendarFeatures, calendarViews, resourceExpansionFeature, timelineView } from '@calendar-tsx/core';

const features = calendarFeatures({ tree: resourceExpansionFeature({ initiallyExpanded: true }) });
const views = calendarViews({
  features,
  views: {
    timeline: timelineView({ days: 7, groupBy: 'resource' }),
    compact: timelineView({ days: 7, groupBy: 'resource', features: { tree: { initiallyExpanded: false } } }),
  },
});

Pass features and views to the calendar. Call calendar.api.resourceExpansion.toggle(id) or setExpanded(id, boolean). Leaf actions do nothing; unknown IDs throw. State is a resourceExpansion map of resource IDs to Boolean overrides. Omitted IDs use that view's initiallyExpanded default. Overrides persist by ID across navigation, view switches and resource replacement, including while an ancestor is collapsed.

For controlled expansion, pass state: { resourceExpansion } and apply the map emitted through onResourceExpansionChange. Rows change after acknowledgment. External stores use atoms: { resourceExpansion }. Without the feature, hierarchical Timeline rows remain fully expanded.

Render TimelineViewResourceToggle inside TimelineViewResource, passing row and the typed calendar instance. The native button exposes aria-expanded, supplies an accessible label, and renders only for parents. Supply its visible text or icon as children. preventDefault() skips the action. The existing Timeline examples show this composition for React and Solid. Labels and content remain consumer-owned. The parts retain the labelled-region semantics and native tab order; they do not implement treegrid arrow-key navigation.

Expansion affects only Timeline. Hidden resources remain in scheduling constraints. Hit detection and draft previews use visible rows; programmatic operations can still target a hidden resource. An active preview disappears if its target is collapsed and returns if expanded again.

SettingsCopy Anchor Link

Every view factory takes exactly one of days, weeks, months or period. Counts are positive integers.

Set minSlotWidth on month and year timelines to keep daily columns readable; the supplied themes then scroll the timeline horizontally.

• An event appears in every row whose resource it names.
• All-day events have no separate row. They stack with timed events, from the start of their first day to the start of the day after their last.
• A resource's availability is shaded as in the resource view.
• Background events shade the track without taking stack rows. Register backgroundFeature to add background layers.

Brief eventsCopy Anchor Link

A brief timed event is displayed at least minEventMinutes long, half a slot by default, measured in visible clock minutes across hidden dates and daylight-saving changes. With daily slots and minSlotWidth: '6rem', a bar is then at least 3rem wide. Stacking uses the enlarged span, so neighboring brief events stay separately selectable. The event keeps its real start and end for labels. Bars clip at the visible range's end, where one can be narrower than the minimum. All-day events keep their date spans. Keep CSS padding and borders inside the computed width: a CSS-only minimum would enlarge bars without restacking them.

Hidden weekdaysCopy Anchor Link

hiddenDays omits ISO weekdays. Use the exported DayOfWeek constants (DayOfWeek.Monday is 1, DayOfWeek.Sunday is 7) or the numbers; the same values work for firstDayOfWeek and weekly background daysOfWeek.

import { DayOfWeek, timeGridView } from '@calendar-tsx/core';

timeGridView({ weeks: 1, hiddenDays: [DayOfWeek.Saturday, DayOfWeek.Sunday] }); // a workweek

Hidden weekdays change neither the nominal period, the inclusive fetch range nor the navigation step. Hiding all seven weekdays throws. When every date in the range is hidden, such as a one-day view on a hidden Saturday, the range shows its dates anyway.

Visible hoursCopy Anchor Link

timeWindow limits the clock hours shown, in integer clock minutes: 0 <= startMinutes < 1440 and startMinutes < endMinutes <= startMinutes + 1440. The default is [0, 1440).

timeGridView({ days: 7, timeWindow: { startMinutes: 480, endMinutes: 1080 } }); // 08:00 to 18:00
timelineView({ days: 1, timeWindow: { startMinutes: 1320, endMinutes: 1800 } }); // 22:00 to 06:00

An overnight window belongs to its starting date, so hiding Tuesday still shows Monday's Tuesday-morning portion. All-day items keep their calendar dates. slotMinutes need not divide the window; the final slot keeps its actual size, and each slot's dayOffset labels after-midnight times. Fetch events for navigation's inputRange, which adds the following date when an overnight window needs it.

ExampleCopy Anchor Link

useLayout narrows the layout for <Show>; see narrowing the layout.

export const Timeline = (props: { calendar: DayCalendar }) => {
  const timeline = useLayout('timeline');

  return (
    <Show when={timeline()}>
      {timeline => (
        <TimelineView model={timeline()}>
          <TimelineViewHeader>
            <For each={timeline().days}>
              {day => (
                <TimelineViewDayHeader day={day}>
                  <TimelineViewDayTrigger calendar={props.calendar} day={day} view='day'>
                    {day.date.toLocaleString('en-US', { weekday: 'short', day: 'numeric' })}
                  </TimelineViewDayTrigger>
                </TimelineViewDayHeader>
              )}
            </For>
            <Show when={timeline().days.some(day => day.colSpan > 1)}>
              <For each={timeline().slots}>
                {slot => (
                  <TimelineViewSlotLabel slot={slot}>
                    {slot.time.toLocaleString('en-US', { hour: 'numeric', minute: '2-digit' })}
                  </TimelineViewSlotLabel>
                )}
              </For>
            </Show>
          </TimelineViewHeader>
          <TimelineViewBody>
            <For each={timeline().rows}>
              {row => (
                <TimelineViewRow row={row}>
                  <TimelineViewResource row={row}>
                    <Show when={props.calendar.api.resourceExpansion}>
                      {expansion => (
                        <TimelineViewResourceToggle row={row} calendar={{ api: { resourceExpansion: expansion() } }}>
                          <span aria-hidden='true'>{row.isExpanded ? '−' : '+'}</span>
                        </TimelineViewResourceToggle>
                      )}
                    </Show>
                    {row.resource?.title}
                  </TimelineViewResource>
                  <TimelineViewLane row={row}>
                    <For each={row.backgrounds}>{background => <TimelineViewBackground background={background} />}</For>
                    <For each={row.backgroundEvents}>
                      {segment => <TimelineViewBackgroundEvent segment={segment} />}
                    </For>
                    <For each={row.unavailable}>{segment => <TimelineViewUnavailable segment={segment} />}</For>
                    <For each={row.segments}>
                      {segment => (
                        <TimelineViewEvent
                          segment={segment}
                          title={formatEvent(segment.event)}
                          aria-label={formatEvent(segment.event)}
                        >
                          {segment.event.data.title}
                        </TimelineViewEvent>
                      )}
                    </For>
                  </TimelineViewLane>
                </TimelineViewRow>
              )}
            </For>
            <TimelineViewNowIndicator model={timeline()} />
          </TimelineViewBody>
        </TimelineView>
      )}
    </Show>
  );
};

PartsCopy Anchor Link