Component

ChangelogTimeline

Turn git-cliff JSON into a release timeline with categories, stable dates, and links back to GitHub.

Usage

Import the component entry and start with its smallest complete example.

Import

import { ChangelogTimeline, compactGitCliffReleases, generateChangelogRss, type GitCliffRelease } from "@chitrank2050/monoline-ui/changelog"

Basic usage

// 1. Generate release data with git-cliff:
// $ git cliff --context -o changelog.json

import {
  ChangelogTimeline,
  compactGitCliffReleases,
  type GitCliffRelease,
} from "@chitrank2050/monoline-ui/changelog"
import rawChangelog from "./changelog.json"

// Helper function filters unreleased blocks and normalizes commit SHAs
const releases = compactGitCliffReleases(rawChangelog as unknown as GitCliffRelease[])

export default function ChangelogPage() {
  return (
    <ChangelogTimeline
      releases={releases}
      githubOwner="chitranklabs"
      githubRepo="monoline-ui"
      allowedGroups={["Features", "Bug Fixes", "Performance"]}
    />
  )
}

Usage guidance

Choose the component for its interaction model and semantics before customizing its appearance.

Use when

ChangelogTimeline turns git-cliff structured JSON (GitCliffRelease[]) generated from conventional commits into an accessible vertical release feed with SHA, PR, and author links.

Avoid when

The data is a general event timeline or does not follow the GitCliffRelease schema (version, timestamp, commits array).

Accessibility

The timeline uses semantic release version headings, categorized commit lists, and keyboard-accessible links back to GitHub pull requests and commit diffs.

Server Component

This component can render without adding a Monoline client boundary when its children and props are serializable.

API reference

Props, slots, and callbacks available on this component.

releasesGitCliffRelease[]Array of release objects matching git-cliff schema (version, timestamp, commits). Clean with `compactGitCliffReleases()`.

allowedGroupsstring[]Conventional categories to show (e.g. ['Features', 'Bug Fixes', 'Performance']). Default: ['Features', 'Bug Fixes', 'Performance']

maxCommitsPerReleasenumberMaximum number of commits to render per category group before collapsing with a '+N more' counter (default: 8)

githubOwnerstringGitHub org or owner name (e.g. 'chitranklabs') to form absolute release, commit, and PR links

githubRepostringGitHub repository name (e.g. 'monoline-ui') to form absolute release, commit, and PR links

showCommitHashbooleanShow short 7-character commit SHA links (default: true)

showAuthorbooleanShow contributor username and avatar links (default: true)

compactGitCliffReleases()Helper FunctionUtility to filter null unreleased blocks, truncate commit SHAs to 7 chars, and normalize raw git-cliff JSON data.

generateChangelogRss()Helper FunctionUtility to generate a standard RSS 2.0 / Atom XML feed string from parsed git-cliff release data.

Design tokens

Theme variables this component reads for color, spacing, and motion.

--border-strongCSS varChronological vertical timeline line color

--accentCSS varCircle release node border accent color

--destructiveCSS varBreaking change badge background fill color

Implementation

The source used by the example above, including any state it needs.

import {
  ChangelogTimeline,
  compactGitCliffReleases,
  generateChangelogRss,
  type GitCliffRelease,
} from "@chitrank2050/monoline-ui/changelog"
import rawChangelog from "./changelog.json"

/**
 * 1. UI TIMELINE INTEGRATION:
 * Helper function compactGitCliffReleases() cleans raw git-cliff JSON:
 * - Filters out null unreleased version blocks
 * - Normalizes commit IDs to 7-character short SHAs
 * - Strips automated version bump commits
 */
const releasesData: GitCliffRelease[] = compactGitCliffReleases(
  rawChangelog as unknown as GitCliffRelease[]
)

export function ChangelogView() {
  return (
    <section className="docs-page">
      <header className="mb-6">
        <h1 className="text-3xl font-bold font-mono">Changelog</h1>
        <p className="text-text-muted">
          Development log generated from conventional commits.
        </p>
      </header>

      <ChangelogTimeline
        releases={releasesData}
        githubOwner="chitranklabs"
        githubRepo="monoline-ui"
        allowedGroups={[
          "Features",
          "Bug Fixes",
          "Performance",
          "Documentation",
          "Maintenance",
        ]}
      />
    </section>
  )
}

/**
 * 2. RSS FEED ROUTE HANDLER (e.g. app/docs/changelog/feed.xml/route.ts):
 * Use generateChangelogRss() helper to serve an RSS 2.0 XML feed
 */
export async function getRssResponse(siteUrl: string) {
  const xml = generateChangelogRss({
    title: "Monoline UI Changelog",
    description: "Release notes and version updates",
    siteUrl,
    changelogPath: "/docs/changelog",
    releases: releasesData,
  })

  return new Response(xml, {
    headers: {
      "Content-Type": "application/xml; charset=utf-8",
      "Cache-Control": "public, max-age=3600, s-maxage=86400",
    },
  })
}

Compare related components or review the package and theme setup.

01ComponentEditorial LineComponent · ReferenceReference→02ComponentTocComponent · ReferenceReference→03SetupInstall Monoline UISetup · GuideGuide→04ThemeTailwind CSS v4 design tokensTheme · FoundationsFoundations→

Interactive preview