Task Calendar

An operational planning matrix with week columns, clickable day cells, task previews and day details.

Planning calendar

July 06, 2026 - July 19, 2026

2 weeks

Jul 6 - Jul 12

Jul 13 - Jul 19

Mon

Tue

Wed

Thu

Fri

Sat

Sun

import { TaskCalendar, type TaskCalendarTask } from "@/components/patterns/task-calendar";

const tasks: TaskCalendarTask[] = [
  {
    id: "docs",
    title: "Docs API migration",
    date: "2026-07-09",
    calendarVisible: true,
  },
];

export function Example() {
  return <TaskCalendar startDate="2026-07-06" tasks={tasks} weeks={2} />;
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/task-calendar

Import

import {
  TaskCalendar,
  type TaskCalendarTask,
} from "@/components/patterns/task-calendar";

Need the machine-readable source metadata? View registry JSON.

Usage

TaskCalendar shows planning tasks across weeks with day details handled by the pattern.

import { TaskCalendar, type TaskCalendarTask } from "@/components/patterns/task-calendar";

const tasks: TaskCalendarTask[] = [
  {
    id: "docs",
    title: "Docs API migration",
    date: "2026-07-09",
    calendarVisible: true,
  },
];

export function Example() {
  return <TaskCalendar startDate="2026-07-06" tasks={tasks} weeks={2} />;
}

Purpose

Task Calendar is a registry:block for operational planning matrices: weeks are columns, weekdays are rows, day cells are clickable, and day details open in a large dialog.

API Reference

startDate is normalized to Monday. weeks defaults to seven and controls the visible planning range.
calendarVisible controls direct cell visibility; getVisibleTasks can replace that rule.
getDetailTasks controls the day detail list. The default keeps every task for that day.
maxVisibleTasks limits task pills per cell; set it to 0 to keep all tasks in the detail list only.
accent accepts chart-1 through chart-5 or muted. Accent is supplementary; keep status or assignee available as text.
dayDialogSize="wide" expands the detail dialog. dayDialogSidebarDensity="compact" tightens only its task selector.
renderDayDetail replaces the right detail region; renderDayHeaderEnd extends its header. Consumer fetching and product logic remain outside the pattern.
activeDate, activeTaskId, onDaySelect and onTaskSelect connect the pattern to controlled product state or routing.

Motion

Week navigation is immediate. Day navigation inside the open dialog uses the shared Calendar slide tokens.
Dialog, Popover and Resource List behavior remains native to the underlying primitives. Reduced motion removes non-essential movement.

Accessibility

Keep day cells, task pills and task-count controls as separate focusable targets with clear accessible names.
Day-navigation buttons in the dialog need explicit previous/next labels and must not compete with task selection.
Keep task identity, status and assignee available as text; accent color is supplementary.
Preserve the native Dialog focus trap, Escape dismissal and labelled title relationship.

Implementation Guidance

Use Task Calendar for operational planning; do not turn the date-picker Calendar primitive into a planning matrix.
Put task-type filtering in data or resolver functions rather than hardcoding product categories in the pattern.
Use renderDayDetail for product-specific detail content and keep task identity in the provided header.
Keep a direct path from every visible task pill to the full day-detail dialog.

Registry

Source Contract

Registry item: task-calendar

Files

src/components/patterns/task-calendar.tsx to components/patterns/task-calendar.tsx

Registry dependencies: @siteplane/base, @siteplane/button, @siteplane/dialog, @siteplane/popover, @siteplane/badge, @siteplane/resource-list

Package dependencies: lucide-react@1.18.0