Add New/Updated recency pills to docs sidebar (#959)

* Add New/Updated recency pills to docs sidebar

Doc pages can now surface a New or Updated pill in the docs sidebar,
driven by optional `addedAt` / `updatedAt` ISO dates in each library's
`docs/config.json`. Pills auto-expire after 7 days, so the sidebar
self-cleans with no follow-up edits and no per-page GitHub API calls.

- config.ts: add optional addedAt/updatedAt to the sidebar child valibot
  schema (core + per-framework) and the MenuItem type
- DocsLayout.tsx: add pure getDocRecency() helper (7-day window, guards
  invalid and future dates) and DocRecencyPill; render in both the
  external <a> and internal <Link> branches; New takes priority over
  Updated when both are recent
- tanstack-docs-config.schema.json: add the two fields so maintainers get
  editor validation/autocomplete

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: AlemTuzlak

src/components/DocsLayout.tsx

@@ -30,6 +30,75 @@ import { Card } from './Card'
 import { PartnersRail, RightRail } from './RightRail'
 import { trackEvent, useTrackedImpression } from '~/utils/analytics'
 
+// Number of days a doc page is flagged as "New"/"Updated" in the sidebar.
+const RECENCY_WINDOW_DAYS = 7
+const RECENCY_WINDOW_MS = RECENCY_WINDOW_DAYS * 24 * 60 * 60 * 1000
+
+type DocRecency = 'new' | 'updated' | null
+
+// Determine whether a doc page should show a recency pill, based on the
+// maintainer-supplied `addedAt` / `updatedAt` dates in the repo's docs/config.json.
+// "New" (added) takes priority over "Updated" (edited) when both are recent.
+function getDocRecency(addedAt?: string, updatedAt?: string): DocRecency {
+  const now = Date.now()
+
+  const isRecent = (iso?: string) => {
+    if (!iso) return false
+    const time = new Date(iso).getTime()
+    if (Number.isNaN(time)) return false
+    const age = now - time
+    // Reject future dates; only flag within the window.
+    return age >= 0 && age <= RECENCY_WINDOW_MS
+  }
+
+  if (isRecent(addedAt)) return 'new'
+  if (isRecent(updatedAt)) return 'updated'
+  return null
+}
+
+function DocRecencyPill({
+  recency,
+  date,
+}: {
+  recency: Exclude<DocRecency, null>
+  date?: string
+}) {
+  const isNew = recency === 'new'
+  const label = isNew ? 'New' : 'Updated'
+
+  let title: string | undefined
+  if (date) {
+    // Parse date-only strings (YYYY-MM-DD) as local time so the tooltip doesn't
+    // drift to the previous day in negative-UTC timezones (new Date('2026-06-01')
+    // is UTC midnight, which toLocaleDateString would render as the prior day).
+    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date)
+    const parsed = dateOnly
+      ? new Date(
+          Number(dateOnly[1]),
+          Number(dateOnly[2]) - 1,
+          Number(dateOnly[3]),
+        )
+      : new Date(date)
+    if (!Number.isNaN(parsed.getTime())) {
+      title = `${isNew ? 'Added' : 'Updated'} ${parsed.toLocaleDateString()}`
+    }
+  }
+
+  return (
+    <span
+      title={title}
+      className={twMerge(
+        'shrink-0 rounded-full px-1.5 py-0.5 text-[9px] font-bold uppercase tracking-wide leading-none',
+        isNew
+          ? 'bg-emerald-500/15 text-emerald-600 dark:text-emerald-400'
+          : 'bg-sky-500/15 text-sky-600 dark:text-sky-400',
+      )}
+    >
+      {label}
+    </span>
+  )
+}
+
 // Mobile partners strip - inline in the docs toggle bar
 function MobilePartnersStrip({
   partners,
@@ -696,6 +765,14 @@ export function DocsLayout({
                 ? ({ libraryId, version } as never)
                 : undefined
 
+            const recency = getDocRecency(child.addedAt, child.updatedAt)
+            const recencyPill = recency ? (
+              <DocRecencyPill
+                recency={recency}
+                date={recency === 'new' ? child.addedAt : child.updatedAt}
+              />
+            ) : null
+
             return (
               <li key={i}>
                 {child.to.startsWith('http') ? (
@@ -705,7 +782,8 @@ export function DocsLayout({
                     target="_blank"
                     rel="noopener noreferrer"
                   >
-                    {child.label}
+                    <span className="w-full">{child.label}</span>
+                    {recencyPill}
                   </a>
                 ) : (
                   <Link
@@ -741,6 +819,7 @@ export function DocsLayout({
                           >
                             {child.label}
                           </div>
+                          {recencyPill}
                         </div>
                       )
                     }}

src/utils/config.ts

@@ -12,6 +12,10 @@ export type MenuItem = {
     label: string | React.ReactNode
     to: string
     badge?: string
+    /** ISO date string marking when the page was added. Drives the "New" sidebar pill. */
+    addedAt?: string
+    /** ISO date string marking when the page was last meaningfully updated. Drives the "Updated" sidebar pill. */
+    updatedAt?: string
   }[]
   collapsible?: boolean
   defaultCollapsed?: boolean
@@ -26,6 +30,8 @@ const configSchema = v.object({
           label: v.string(),
           to: v.string(),
           badge: v.optional(v.string()),
+          addedAt: v.optional(v.string()),
+          updatedAt: v.optional(v.string()),
         }),
       ),
       frameworks: v.optional(
@@ -37,6 +43,8 @@ const configSchema = v.object({
                 label: v.string(),
                 to: v.string(),
                 badge: v.optional(v.string()),
+                addedAt: v.optional(v.string()),
+                updatedAt: v.optional(v.string()),
               }),
             ),
           }),

tanstack-docs-config.schema.json

@@ -53,6 +53,16 @@
                 },
                 "badge": {
                   "type": "string"
+                },
+                "addedAt": {
+                  "type": "string",
+                  "format": "date",
+                  "description": "Date the page was added (e.g. \"2026-06-01\"). Shows a \"New\" pill in the sidebar for 7 days."
+                },
+                "updatedAt": {
+                  "type": "string",
+                  "format": "date",
+                  "description": "Date the page was last meaningfully updated (e.g. \"2026-06-01\"). Shows an \"Updated\" pill in the sidebar for 7 days."
                 }
               }
             }
@@ -79,6 +89,16 @@
                       },
                       "badge": {
                         "type": "string"
+                      },
+                      "addedAt": {
+                        "type": "string",
+                        "format": "date",
+                        "description": "Date the page was added (e.g. \"2026-06-01\"). Shows a \"New\" pill in the sidebar for 7 days."
+                      },
+                      "updatedAt": {
+                        "type": "string",
+                        "format": "date",
+                        "description": "Date the page was last meaningfully updated (e.g. \"2026-06-01\"). Shows an \"Updated\" pill in the sidebar for 7 days."
                       }
                     }
                   }