Tighten up types used for landing pages (#56237)

Author: heiskr

src/frame/components/context/CategoryLandingContext.tsx

@@ -1,8 +1,8 @@
-import pick from 'lodash/pick'
 import { createContext, useContext } from 'react'
 import { LearningTrack } from './ArticleContext'
 import { FeaturedLink, getFeaturedLinksFromReq } from '@/landings/components/ProductLandingContext'
-import { TocItem } from '@/landings/types'
+import type { TocItem } from '@/landings/types'
+import { mapRawTocItemToTocItem } from '@/landings/types'
 
 export type CategoryLandingContextT = {
   title: string
@@ -37,8 +37,8 @@ export const getCategoryLandingContextFromRequest = (req: any): CategoryLandingC
     productCallout: req.context.page.product || '',
     permissions: req.context.page.permissions || '',
     intro: req.context.page.intro,
-    tocItems: (req.context.genericTocFlat || req.context.genericTocNested || []).map((obj: any) =>
-      pick(obj, ['fullPath', 'title', 'intro', 'childTocItems']),
+    tocItems: (req.context.genericTocFlat || req.context.genericTocNested || []).map(
+      mapRawTocItemToTocItem,
     ),
     variant: req.context.genericTocFlat ? 'expanded' : 'compact',
     featuredLinks: getFeaturedLinksFromReq(req),

src/frame/components/context/TocLandingContext.tsx

@@ -1,20 +1,15 @@
-import pick from 'lodash/pick'
 import { createContext, useContext } from 'react'
 import { LearningTrack } from './ArticleContext'
 import { FeaturedLink, getFeaturedLinksFromReq } from '@/landings/components/ProductLandingContext'
-
-export type TocItem = {
-  fullPath: string
-  title: string
-  intro?: string
-}
+import type { SimpleTocItem } from '@/landings/types'
+import { mapRawTocItemToSimpleTocItem } from '@/landings/types'
 
 export type TocLandingContextT = {
   title: string
   intro: string
   productCallout: string
   permissions: string
-  tocItems: Array<TocItem>
+  tocItems: Array<SimpleTocItem>
   variant?: 'compact' | 'expanded'
   featuredLinks: Record<string, Array<FeaturedLink>>
   renderedPage: string
@@ -39,8 +34,8 @@ export const getTocLandingContextFromRequest = (req: any): TocLandingContextT =>
     productCallout: req.context.page.product || '',
     permissions: req.context.page.permissions || '',
     intro: req.context.page.intro,
-    tocItems: (req.context.genericTocFlat || req.context.genericTocNested || []).map((obj: any) =>
-      pick(obj, ['fullPath', 'title', 'intro', 'childTocItems']),
+    tocItems: (req.context.genericTocFlat || req.context.genericTocNested || []).map(
+      mapRawTocItemToSimpleTocItem,
     ),
     variant: req.context.genericTocFlat ? 'expanded' : 'compact',
     featuredLinks: getFeaturedLinksFromReq(req),

src/landings/components/ProductLandingContext.tsx

@@ -1,15 +1,6 @@
 import { createContext, useContext } from 'react'
 import pick from 'lodash/pick'
-
-export type TocItem = {
-  fullPath: string
-  title: string
-  intro?: string
-  childTocItems?: Array<{
-    fullPath: string
-    title: string
-  }>
-}
+import type { SimpleTocItem } from '@/landings/types'
 export type FeaturedLink = {
   title: string
   href: string
@@ -60,7 +51,7 @@ export type ProductLandingContextT = {
   }>
   changelogUrl?: string
   whatsNewChangelog?: Array<{ href: string; title: string; date: string }>
-  tocItems: Array<TocItem>
+  tocItems: Array<SimpleTocItem>
   hasGuidesPage: boolean
   ghesReleases: Array<Release>
 }

src/landings/components/TableOfContents.tsx

@@ -3,7 +3,7 @@ import cx from 'classnames'
 
 import { ActionList } from '@primer/react'
 import { Link } from '@/frame/components/Link'
-import type { TocItem } from '@/landings/components/ProductLandingContext'
+import type { TocItem } from '@/landings/types'
 
 type Props = {
   items: Array<TocItem>

src/landings/types.ts

@@ -1,29 +1,113 @@
+// Base type for all TOC items with core properties
 export type BaseTocItem = {
   fullPath: string
   title: string
   intro?: string
 }
 
+// Valid octicon types that match the CookBookArticleCard component
+export type ValidOcticon =
+  | 'code'
+  | 'log'
+  | 'terminal'
+  | 'bug'
+  | 'lightbulb'
+  | 'gear'
+  | 'rocket'
+  | 'beaker'
+  | 'copilot'
+  | 'hubot'
+  | 'book'
+  | 'shield-lock'
+  | 'lock'
+
+// Extended type for child TOC items with additional metadata
 export type ChildTocItem = BaseTocItem & {
-  octicon?:
-    | 'code'
-    | 'log'
-    | 'terminal'
-    | 'bug'
-    | 'lightbulb'
-    | 'gear'
-    | 'rocket'
-    | 'beaker'
-    | 'copilot'
-    | 'hubot'
-    | 'book'
+  octicon?: ValidOcticon
   category?: string[]
   complexity?: string[]
   industry?: string[]
 }
 
+// Main TOC item type that can contain children
 export type TocItem = BaseTocItem & {
   childTocItems?: ChildTocItem[]
+  octicon?: ValidOcticon
+  category?: string[]
+  complexity?: string[]
+  industry?: string[]
 }
 
+// Type alias for article card components
 export type ArticleCardItems = ChildTocItem[]
+
+// Raw TOC type that matches the actual data structure from getTocItems()
+// This includes all properties that may be present in the source data
+export type RawTocItem = {
+  title: string
+  fullPath: string
+  intro: string | null
+  octicon: string | null
+  category: string[] | null
+  complexity: string[] | null
+  industry: string[] | null
+  childTocItems: RawTocItem[]
+}
+
+// Helper function to validate and cast octicon values
+export function isValidOcticon(octicon: string | null): octicon is ValidOcticon {
+  const validOcticons: ValidOcticon[] = [
+    'code',
+    'log',
+    'terminal',
+    'bug',
+    'lightbulb',
+    'gear',
+    'rocket',
+    'beaker',
+    'copilot',
+    'hubot',
+    'book',
+    'shield-lock',
+    'lock',
+  ]
+  return octicon !== null && validOcticons.includes(octicon as ValidOcticon)
+}
+
+// Simplified TOC item type for basic landing pages that don't need extended metadata
+export type SimpleTocItem = {
+  fullPath: string
+  title: string
+  intro?: string
+  childTocItems?: Array<{
+    fullPath: string
+    title: string
+  }>
+}
+
+// Reusable mapper function to convert RawTocItem to TocItem with full metadata
+export function mapRawTocItemToTocItem(raw: RawTocItem): TocItem {
+  return {
+    fullPath: raw.fullPath,
+    title: raw.title,
+    intro: raw.intro || undefined,
+    octicon: isValidOcticon(raw.octicon) ? raw.octicon : undefined,
+    category: raw.category || undefined,
+    complexity: raw.complexity || undefined,
+    industry: raw.industry || undefined,
+    childTocItems: raw.childTocItems?.map(mapRawTocItemToTocItem),
+  }
+}
+
+// Reusable mapper function to convert RawTocItem to SimpleTocItem
+export function mapRawTocItemToSimpleTocItem(raw: RawTocItem): SimpleTocItem {
+  return {
+    fullPath: raw.fullPath,
+    title: raw.title,
+    intro: raw.intro || undefined,
+    childTocItems: raw.childTocItems?.map((child) => ({
+      fullPath: child.fullPath,
+      title: child.title,
+    })),
+  }
+}

src/rest/pages/category.tsx

@@ -15,10 +15,10 @@ import {
 import type { MiniTocItem } from '@/frame/components/context/ArticleContext'
 import {
   getTocLandingContextFromRequest,
-  TocItem,
   TocLandingContext,
   TocLandingContextT,
 } from '@/frame/components/context/TocLandingContext'
+import type { TocItem } from '@/landings/types'
 import { TocLanding } from '@/landings/components/TocLanding'
 
 type MinitocItemsT = {

src/types.ts

@@ -2,6 +2,7 @@ import type { Request } from 'express'
 import type { Failbot } from '@github/failbot'
 
 import type enterpriseServerReleases from '@/versions/lib/enterprise-server-releases.d.ts'
+import type { ValidOcticon } from '@/landings/types'
 
 // Throughout our codebase we "extend" the Request object by attaching
 // things to it. For example `req.context = { currentCategory: 'foo' }`.
@@ -239,8 +240,12 @@ type Breadcrumb = {
 export type ToC = {
   title: string
   fullPath: string
-  intro: string
-  childTocItems: ToC[] | null
+  intro: string | null
+  octicon: ValidOcticon | null
+  category: string[] | null
+  complexity: string[] | null
+  industry: string[] | null
+  childTocItems: ToC[]
 }
 
 export type GHESRelease = {