Add semantic breadcrumbs to chart examples

src/components/Breadcrumbs.tsx

@@ -9,10 +9,17 @@ import {
   DropdownItem,
 } from './Dropdown'
 
+export type BreadcrumbItem = {
+  label: string
+  to: string
+  search?: true
+  preload?: false
+}
+
 type BreadcrumbsProps = {
   /** Section label (e.g., "Getting Started", "Blog") */
   section: string
-  items?: Array<{ label: string; to: string }>
+  items?: Array<BreadcrumbItem>
   /** Optional link for the section */
   sectionTo?: string
   headings?: MarkdownHeading[]
@@ -51,6 +58,8 @@ export function Breadcrumbs({
                   ) : (
                     <Link
                       to={item.to}
+                      search={item.search}
+                      preload={item.preload}
                       activeOptions={{ exact: true }}
                       className="hover:underline"
                     >

src/components/charts/ChartsCatalogPages.tsx

@@ -1,3 +1,5 @@
+import { Breadcrumbs } from '~/components/Breadcrumbs'
+import { getChartBreadcrumbItems } from '~/utils/chart-breadcrumbs'
 import {
   ArrowsOutSimpleIcon,
   ArrowUpRightIcon,
@@ -9,7 +11,6 @@ import type { ChartsCatalogIndexCase } from '~/utils/charts-catalog-index'
 import type { ExampleDefinition } from '~/utils/example-workspace'
 import {
   chartsCatalogCollections,
-  findChartsCatalogCollection,
   type ChartsCatalogAuthoredSource,
 } from '~/utils/charts-catalog'
 import { ChartsCatalogPreview } from './ChartsCatalogPreview'
@@ -161,34 +162,14 @@ export function ChartsCatalogDetail({
     }
   }
 }) {
-  const collection = catalogCase.collection
-    ? findChartsCatalogCollection(catalogCase.collection)
-    : undefined
-
   return (
     <CatalogSurface wide>
       <div className="mb-6 flex flex-wrap items-start justify-between gap-5">
         <div>
-          {collection ? (
-            <Link
-              className="text-sm text-gray-500 hover:text-blue-600 dark:hover:text-blue-400"
-              params={{ collectionId: collection.id }}
-              preload={false}
-              search={true}
-              to="/charts/catalog/collections/$collectionId"
-            >
-              {collection.title}
-            </Link>
-          ) : (
-            <Link
-              className="text-sm text-gray-500 hover:text-blue-600 dark:hover:text-blue-400"
-              preload={false}
-              search={true}
-              to="/charts/catalog"
-            >
-              Catalog
-            </Link>
-          )}
+          <Breadcrumbs
+            section="Catalog"
+            items={getChartBreadcrumbItems(catalogCase)}
+          />
           <h1 className="mt-2 text-2xl font-bold tracking-tight text-gray-950 dark:text-white sm:text-3xl">
             {catalogCase.title}
           </h1>

src/routes/_library/charts.catalog.charts.$caseId.tsx

@@ -1,3 +1,4 @@
+import { getChartBreadcrumbJsonLd } from '~/utils/chart-breadcrumbs'
 import { createFileRoute, notFound } from '@tanstack/react-router'
 import {
   ChartsCatalogDetail,
@@ -21,6 +22,16 @@ export const Route = createFileRoute('/_library/charts/catalog/charts/$caseId')(
     pendingMs: 250,
     component: ChartsCatalogCaseRoute,
     head: ({ loaderData }) => ({
+      scripts: loaderData
+        ? [
+            {
+              type: 'application/ld+json',
+              children: JSON.stringify(
+                getChartBreadcrumbJsonLd(loaderData.case),
+              ).replaceAll('<', '\\u003c'),
+            },
+          ]
+        : [],
       meta: seo({
         title: loaderData
           ? `${loaderData.case.title} | TanStack Charts`

src/utils/chart-breadcrumbs.ts

@@ -0,0 +1,39 @@
+import type { BreadcrumbItem } from '~/components/Breadcrumbs'
+import { findChartsCatalogCollection } from './charts-catalog'
+import { canonicalUrl } from './seo'
+
+type ChartBreadcrumbData = { id: string; title: string; collection?: string }
+
+export function getChartBreadcrumbItems(
+  chart: ChartBreadcrumbData,
+): Array<BreadcrumbItem> {
+  const collection = chart.collection
+    ? findChartsCatalogCollection(chart.collection)
+    : undefined
+  const items: Array<BreadcrumbItem> = [
+    { label: 'Catalog', to: '/charts/catalog', search: true, preload: false },
+  ]
+  if (collection) {
+    items.push({
+      label: collection.title,
+      to: `/charts/catalog/collections/${collection.id}`,
+      search: true,
+      preload: false,
+    })
+  }
+  items.push({ label: chart.title, to: `/charts/catalog/charts/${chart.id}` })
+  return items
+}
+
+export function getChartBreadcrumbJsonLd(chart: ChartBreadcrumbData) {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: getChartBreadcrumbItems(chart).map((item, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: item.label,
+      item: canonicalUrl(item.to),
+    })),
+  }
+}

tests/chart-breadcrumbs.test.ts

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import {
+  getChartBreadcrumbItems,
+  getChartBreadcrumbJsonLd,
+} from '../src/utils/chart-breadcrumbs'
+Object.assign(globalThis, { __TANSTACK_SITE_URL__: 'https://tanstack.com' })
+
+test('chart hierarchy includes only known collections and keeps navigation options out of canonical URLs', () => {
+  const chart = {
+    id: 'area-simple',
+    title: 'Area <simple>',
+    collection: 'shadcn',
+  }
+  const items = getChartBreadcrumbItems(chart)
+  assert.deepEqual(
+    items.map((item) => item.label),
+    ['Catalog', 'shadcn/ui Charts', 'Area <simple>'],
+  )
+  assert.equal(items[1].search, true)
+  assert.equal(items[1].preload, false)
+  const schema = getChartBreadcrumbJsonLd(chart)
+  assert.deepEqual(
+    schema.itemListElement.map((item) => item.position),
+    [1, 2, 3],
+  )
+  assert.equal(
+    schema.itemListElement[2].item,
+    'https://tanstack.com/charts/catalog/charts/area-simple',
+  )
+  for (const collection of [undefined, 'unknown']) {
+    assert.equal(getChartBreadcrumbItems({ ...chart, collection }).length, 2)
+  }
+})