Project Views

Preview

Install

1. 1. Add the registry to components.json, once per app. Without it, the shadcn CLI looks up @txbrendan in a public list that txbrendan/ui does not control.

   npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json"

2. 2. Add the theme, once per app. It replaces your color tokens with ones checked for contrast.

   npx shadcn@latest add @txbrendan/theme

3. 3. Add the block. It also adds every component it uses. Its own files go in your components folder, and they are yours to edit.

   npx shadcn@latest add @txbrendan/project-views

Props

• projects

  The projects, in order inside each stage. Use with onProjectsChange to own them. Each id is unique, and stage is a stage's id.

  { id: string; name: string; kind?: string; stage: string; description?: string; priority?: "high" | "medium" | "low"; urgent?: boolean; tasks?: { done: number; total: number }; people?: string[]; comments?: number; files?: number; start?: string; due?: string }[]

• defaultProjects

  The projects to start with, when the block owns them.

  Project[] · default []

• onProjectsChange

  Called with the whole new list after an add, a move, a remove, or an undo.

  (projects: Project[]) => void

• view

  Which view shows. Use with onViewChange.

  "board" | "list" | "timeline"

• defaultView

  The view to start on.

  "board" | "list" | "timeline" · default "board"

• onViewChange

  Called when a tab picks another view.

  (view: ProjectView) => void

• defaultSearch

  The search to start with.

  string · default ""

• stages

  The stages, in order. Each is a lane on the board and a group in the list.

  { id: string; title: string; tone?: "neutral" | "brand" | "danger" | "success" | "warning" }[] · default To do, In progress, In review, Done

• today

  Today as an ISO day, passed from the server.

  string

• locale

  The locale for dates.

  string · default "en-US"

• timeZone

  The time zone the timeline reads days in.

  string · default "UTC"

• loading

  Each view holds its space with placeholders, and the count waits.

  boolean · default false

• error

  Says what went wrong in place of the views.

  string

• onRetry

  Shows Retry beside the error.

  () => void

• className

  Extra classes on the outer section, which holds the container query.

  string

Accessibility

• The block is a section named by its heading. On a page with more than one, give each an aria-label, which then names it instead. The views are tabs, and the arrow keys move between them.
• Each card and each row has one button named by the project, which opens its sheet. The rest of a row opens it with a pointer.
• Each project's "…" button is named "More for" and the project, and opens Open, Move to, and Remove.
• After a move or a remove, focus goes to the project in its new place, or to the one beside where it was.
• List and Timeline are one table, with column headers, a row header for each project, and a row group for each stage.
• Each lane is a group named by its stage and count. Each "+" button is named for its stage, and its tooltip says Add project.
• The view that leaves is hidden from screen readers and from Tab while it fades.
• The count line and each stage's count roll to new numbers. Reduced motion takes out the slide, and motion off shows each view at once.

Examples

<ProjectViews
  today="2026-10-30"
  defaultProjects={[
    { id: "payments", name: "Payments page", kind: "Web", stage: "doing", priority: "high", urgent: true, tasks: { done: 9, total: 20 }, people: ["AK", "BL"], start: "2026-10-19", due: "2026-11-06" },
    { id: "help", name: "Help center", kind: "Web", stage: "review", tasks: { done: 18, total: 20 }, start: "2026-10-12", due: "2026-10-31" },
  ]}
/>

"use client";

function TeamProjects({ initial, today }: { initial: Project[]; today: string }) {
  const [projects, setProjects] = useState(initial);
  const [view, setView] = useState<ProjectView>("list");
  return (
    <ProjectViews
      projects={projects}
      onProjectsChange={(next) => {
        setProjects(next);
        saveProjects(next);
      }}
      view={view}
      onViewChange={setView}
      today={today}
    />
  );
}

<ProjectViews
  today="2026-10-30"
  stages={[
    { id: "ideas", title: "Ideas" },
    { id: "building", title: "Building", tone: "brand" },
    { id: "shipped", title: "Shipped", tone: "success" },
  ]}
  defaultProjects={[{ id: "search", name: "Search", stage: "ideas" }]}
/>

<ProjectViews
  projects={data ?? []}
  loading={isLoading}
  error={failed ? "Projects could not load." : undefined}
  onRetry={refetch}
/>