docs(many): fix default theme variables sections on component doc pages

git-nandor · git-nandor · commit a98af824bc0e · 2026-06-03T11:26:27.000+02:00
diff --git a/packages/__docs__/buildScripts/build-docs.mts b/packages/__docs__/buildScripts/build-docs.mts
@@ -421,16 +421,34 @@ function parseThemes() {
     resource: { ...canvasHighContrast, resolvedComponents: resolveComponents(legacyCanvasHighContrast) }
   }
   parsed['canvas'] = {
-    resource: { ...legacyCanvas, resolvedColors: resolveNewThemeColors(legacyCanvas), description: canvas.description }
+    resource: {
+      ...legacyCanvas,
+      resolvedColors: resolveNewThemeColors(legacyCanvas),
+      resolvedComponents: resolveComponents(legacyCanvas),
+      description: canvas.description
+    }
   }
   parsed['canvas-high-contrast'] = {
-    resource: { ...legacyCanvasHighContrast, resolvedColors: resolveNewThemeColors(legacyCanvasHighContrast), description: canvasHighContrast.description }
+    resource: {
+      ...legacyCanvasHighContrast,
+      resolvedColors: resolveNewThemeColors(legacyCanvasHighContrast),
+      resolvedComponents: resolveComponents(legacyCanvasHighContrast),
+      description: canvasHighContrast.description
+    }
   }
   parsed[light.key] = {
-    resource: { ...light, resolvedColors: resolveNewThemeColors(light.newTheme as typeof legacyCanvas) }
+    resource: {
+      ...light,
+      resolvedColors: resolveNewThemeColors(light.newTheme as typeof legacyCanvas),
+      resolvedComponents: resolveComponents(light.newTheme as typeof legacyCanvas)
+    }
   }
   parsed[dark.key] = {
-    resource: { ...dark, resolvedColors: resolveNewThemeColors(dark.newTheme as typeof legacyCanvas) }
+    resource: {
+      ...dark,
+      resolvedColors: resolveNewThemeColors(dark.newTheme as typeof legacyCanvas),
+      resolvedComponents: resolveComponents(dark.newTheme as typeof legacyCanvas)
+    }
   }
   const canvasSemantics = legacyCanvas.semantics(legacyCanvas.primitives)
   parsed['shared-tokens'] = { resource: legacyCanvas.sharedTokens(canvasSemantics) }
diff --git a/packages/__docs__/src/Document/index.tsx b/packages/__docs__/src/Document/index.tsx
@@ -29,6 +29,7 @@ import { View } from '@instructure/ui-view'
 import { Tabs } from '@instructure/ui-tabs'
 import type { TabsProps } from '@instructure/ui-tabs'
 import type { NewBaseTheme } from '@instructure/ui-themes'
+import type { ComponentTheme as ComponentThemeData } from '@instructure/shared-types'
 import { SourceCodeEditor } from '@instructure/ui-source-code-editor'
 import { withStyleForDocs as withStyleNew } from '../withStyleForDocs'
 
@@ -78,47 +79,48 @@ class Document extends Component<DocumentProps, DocumentState> {
 
   fetchGenerateComponentTheme = async () => {
     const { doc, themeVariables } = this.props
-    let generateTheme
-    // Doc IDs use dot notation (e.g. "Menu.Item") but theme component keys
-    // use PascalCase without dots (e.g. "MenuItem").
-    // New-theme entries are in themeVariables.newTheme.components.
     const selectedId = this.state.selectedDetailsTabId
     type ComponentKey = keyof NewBaseTheme['components']
+    // When a child tab is selected, work from the child's doc/component;
+    // otherwise from the main doc's.
     const childDoc =
       selectedId !== doc.id
         ? doc?.children?.find((value) => value.id === selectedId)
         : null
-    // in case of some components, we need to display the theme variables of other components based on themeId (like displaying the theme variables of Options in Drillsdown.Group)
+    const currentComponentInstance =
+      selectedId === doc.id
+        ? doc?.componentInstance
+        : childDoc?.componentInstance
+    // Resolve the theme registry key. Default: doc id with dots stripped
+    // (e.g. "Menu.Item" → "MenuItem"). Two ways to override the default:
+    //  - `themeId:` in YAML frontmatter (read from childDoc.themeId) — used
+    //    when a doc page wants to show another component's tokens
+    //    (e.g. Drilldown.Group → 'Options').
+    //  - `static themeId` on the component class — used when a component
+    //    borrows another's tokens via `useTokensFrom` at runtime
+    //    (e.g. Button → 'BaseButton', ColorMixer.Slider → 'Slider').
     const themeKey: ComponentKey = (childDoc?.themeId ||
+      currentComponentInstance?.themeId ||
       selectedId?.replace(/\./g, '')) as ComponentKey
     const isLegacyTheme = this.context?.componentVersion == 'v11_6'
-    // new theme
+    // New theme: tokens are pre-resolved into plain objects at build time
+    // (the build emits JSON, so generator functions can't be carried through).
     if (!isLegacyTheme) {
-      // resolvedComponents contains pre-computed plain objects (built at build time)
       const resolvedComponents = (themeVariables as Record<string, unknown>)
         ?.resolvedComponents as Record<string, unknown> | undefined
       const newThemeEntry = resolvedComponents?.[themeKey as string]
-      const componentInstance =
-        selectedId === doc.id
-          ? doc?.componentInstance
-          : childDoc?.componentInstance
       if (
         newThemeEntry &&
-        typeof componentInstance?.generateComponentTheme !== 'function'
+        typeof currentComponentInstance?.generateComponentTheme !== 'function'
       ) {
-        // new theme - use pre-computed theme object directly
         this.setState({
           componentTheme: newThemeEntry as DocumentState['componentTheme']
         })
         return
       }
     }
-    // old theme - use generateComponentTheme function
-    if (selectedId === doc.id) {
-      generateTheme = doc?.componentInstance?.generateComponentTheme
-    } else {
-      generateTheme = childDoc?.componentInstance?.generateComponentTheme
-    }
+    // Legacy theme: call the component's generateComponentTheme directly.
+    const generateTheme = currentComponentInstance?.generateComponentTheme
     if (typeof generateTheme === 'function' && themeVariables) {
       this.setState({ componentTheme: generateTheme(themeVariables) })
     } else {
@@ -179,9 +181,7 @@ class Document extends Component<DocumentProps, DocumentState> {
             </code>
           </View>
         ) : null}
-        <ComponentTheme
-          componentTheme={componentTheme as any /* TODO-theme-types check */}
-        />
+        <ComponentTheme componentTheme={componentTheme as ComponentThemeData} />
 
         <View margin="x-large 0 0" display="block">
           <Heading
diff --git a/packages/__docs__/src/Document/props.ts b/packages/__docs__/src/Document/props.ts
@@ -46,12 +46,16 @@ type DocumentProps = DocumentOwnProps & WithStyleProps<null, DocumentStyle>
 
 type DocumentStyle = ComponentStyle<'githubCornerOctoArm' | 'githubCorner'>
 
+type ResolvedNewComponentTheme = ReturnType<
+  NewBaseTheme['components'][keyof NewBaseTheme['components']]
+>
+
 type DocumentState = {
   selectedDetailsTabId: string | undefined
   pageRef: HTMLDivElement | null
   componentTheme:
     | ThemeVariables[keyof ThemeVariables]
-    | NewBaseTheme['components'][keyof NewBaseTheme['components']]
+    | ResolvedNewComponentTheme
     | undefined
 }
 
diff --git a/packages/ui-buttons/src/Button/v2/index.tsx b/packages/ui-buttons/src/Button/v2/index.tsx
@@ -41,6 +41,8 @@ category: components
 @withStyleNew(null, 'BaseButton')
 class Button extends Component<ButtonProps> {
   static readonly componentId = 'Button'
+  // Button v2 uses BaseButton's tokens; tell Document where to look for theme variables
+  static readonly themeId = 'BaseButton'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-buttons/src/CloseButton/v2/index.tsx b/packages/ui-buttons/src/CloseButton/v2/index.tsx
@@ -44,6 +44,8 @@ category: components
 @withStyleNew(generateStyle, 'BaseButton')
 class CloseButton extends Component<CloseButtonProps> {
   static readonly componentId = 'CloseButton'
+  // Uses BaseButton's tokens; tell Document where to look for theme variables
+  static readonly themeId = 'BaseButton'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-buttons/src/CondensedButton/v2/index.tsx b/packages/ui-buttons/src/CondensedButton/v2/index.tsx
@@ -41,6 +41,8 @@ category: components
 @withStyleNew(null, 'BaseButton')
 class CondensedButton extends Component<CondensedButtonProps> {
   static readonly componentId = 'CondensedButton'
+  // Uses BaseButton's tokens; tell Document where to look for theme variables
+  static readonly themeId = 'BaseButton'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-buttons/src/IconButton/v2/index.tsx b/packages/ui-buttons/src/IconButton/v2/index.tsx
@@ -44,6 +44,8 @@ category: components
 @withStyleNew(null, 'BaseButton')
 class IconButton extends Component<IconButtonProps> {
   static readonly componentId = 'IconButton'
+  // Uses BaseButton's tokens; tell Document where to look for theme variables
+  static readonly themeId = 'BaseButton'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-checkbox/src/Checkbox/v2/CheckboxFacade/index.tsx b/packages/ui-checkbox/src/Checkbox/v2/CheckboxFacade/index.tsx
@@ -45,6 +45,7 @@ parent: Checkbox
 @withStyleNew(generateStyle, 'Checkbox')
 class CheckboxFacade extends Component<CheckboxFacadeProps> {
   static readonly componentId = 'CheckboxFacade'
+  static readonly themeId = 'Checkbox'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-checkbox/src/Checkbox/v2/ToggleFacade/index.tsx b/packages/ui-checkbox/src/Checkbox/v2/ToggleFacade/index.tsx
@@ -45,6 +45,7 @@ parent: Checkbox
 @withStyleNew(generateStyle, 'Toggle')
 class ToggleFacade extends Component<ToggleFacadeProps> {
   static readonly componentId = 'ToggleFacade'
+  static readonly themeId = 'Toggle'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-color-picker/src/ColorMixer/v2/ColorPalette/index.tsx b/packages/ui-color-picker/src/ColorMixer/v2/ColorPalette/index.tsx
@@ -50,6 +50,7 @@ private: true
 class ColorPalette extends Component<ColorPaletteProps, ColorPaletteState> {
   static allowedProps = allowedProps
   static readonly componentId = 'ColorMixer.Palette'
+  static readonly themeId = 'Palette'
 
   constructor(props: ColorPaletteProps) {
     super(props)
diff --git a/packages/ui-color-picker/src/ColorMixer/v2/RGBAInput/index.tsx b/packages/ui-color-picker/src/ColorMixer/v2/RGBAInput/index.tsx
@@ -44,6 +44,7 @@ private: true
 class RGBAInput extends Component<RGBAInputProps, RGBAInputState> {
   static allowedProps = allowedProps
   static readonly componentId = 'ColorMixer.RGBAInput'
+  static readonly themeId = 'RgbaInput'
 
   static defaultProps = {
     withAlpha: false
diff --git a/packages/ui-color-picker/src/ColorMixer/v2/Slider/index.tsx b/packages/ui-color-picker/src/ColorMixer/v2/Slider/index.tsx
@@ -44,6 +44,7 @@ private: true
 class Slider extends Component<SliderProps> {
   static allowedProps = allowedProps
   static readonly componentId = 'ColorMixer.Slider'
+  static readonly themeId = 'Slider'
 
   static defaultProps = {
     isColorSlider: false
diff --git a/packages/ui-modal/src/Modal/v2/ModalBody/index.tsx b/packages/ui-modal/src/Modal/v2/ModalBody/index.tsx
@@ -45,6 +45,7 @@ id: Modal.Body
 @withStyleNew(generateStyle, 'ModalBody')
 class ModalBody extends Component<ModalBodyProps> {
   static readonly componentId = 'Modal.Body'
+  static readonly themeId = 'ModalBody'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-modal/src/Modal/v2/ModalFooter/index.tsx b/packages/ui-modal/src/Modal/v2/ModalFooter/index.tsx
@@ -40,6 +40,7 @@ id: Modal.Footer
 @withStyleNew(generateStyle, 'ModalFooter')
 class ModalFooter extends Component<ModalFooterProps> {
   static readonly componentId = 'Modal.Footer'
+  static readonly themeId = 'ModalFooter'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-modal/src/Modal/v2/ModalHeader/index.tsx b/packages/ui-modal/src/Modal/v2/ModalHeader/index.tsx
@@ -51,6 +51,7 @@ id: Modal.Header
 @withStyleNew(generateStyle, 'ModalHeader')
 class ModalHeader extends Component<ModalHeaderProps> {
   static readonly componentId = 'Modal.Header'
+  static readonly themeId = 'ModalHeader'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-number-input/src/NumberInput/v2/index.tsx b/packages/ui-number-input/src/NumberInput/v2/index.tsx
@@ -371,6 +371,8 @@ const NumberInput = forwardRef<NumberInputHandle, NumberInputProps>(
 )
 
 NumberInput.displayName = 'NumberInput'
+// Uses TextInput's tokens; tell Document where to look for theme variables
+;(NumberInput as typeof NumberInput & { themeId: string }).themeId = 'TextInput'
 
 export interface NumberInputHandle {
   focus: () => void
diff --git a/packages/ui-pagination/src/Pagination/v2/PaginationPageInput/index.tsx b/packages/ui-pagination/src/Pagination/v2/PaginationPageInput/index.tsx
@@ -49,6 +49,7 @@ class PaginationPageInput extends Component<
   PaginationPageInputState
 > {
   static readonly componentId = 'Pagination.PageInput'
+  static readonly themeId = 'PaginationPageInput'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-side-nav-bar/src/SideNavBar/v2/SideNavBarItem/index.tsx b/packages/ui-side-nav-bar/src/SideNavBar/v2/SideNavBarItem/index.tsx
@@ -42,6 +42,7 @@ id: SideNavBar.Item
 @withStyleNew(generateStyle, 'SideNavBarItem')
 class SideNavBarItem extends Component<SideNavBarItemProps> {
   static readonly componentId = 'SideNavBar.Item'
+  static readonly themeId = 'SideNavBarItem'
 
   static allowedProps = allowedProps
 
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarActionItems/index.tsx b/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarActionItems/index.tsx
@@ -71,6 +71,7 @@ class TopNavBarActionItems extends Component<
   TopNavBarActionItemsState
 > {
   static readonly componentId = 'TopNavBar.ActionItems'
+  static readonly themeId = 'TopNavBarActionItems'
 
   static allowedProps = allowedProps
   static defaultProps = {}
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarBrand/index.tsx b/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarBrand/index.tsx
@@ -48,6 +48,7 @@ id: TopNavBar.Brand
 @withStyleNew(generateStyle, 'TopNavBarBrand')
 class TopNavBarBrand extends Component<TopNavBarBrandProps> {
   static readonly componentId = 'TopNavBar.Brand'
+  static readonly themeId = 'TopNavBarBrand'
   // TODO: add to the docs: making it static on parent and jsdocs parent/module settings, dont export child on its own
 
   static allowedProps = allowedProps
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarItem/index.tsx b/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarItem/index.tsx
@@ -80,6 +80,7 @@ id: TopNavBar.Item
 @withStyleNew(generateStyle, 'TopNavBarItem')
 class TopNavBarItem extends Component<TopNavBarItemProps, TopNavBarItemState> {
   static readonly componentId = 'TopNavBar.Item'
+  static readonly themeId = 'TopNavBarItem'
 
   static allowedProps = allowedProps
   static defaultProps = {
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarLayout/DesktopLayout/index.tsx b/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarLayout/DesktopLayout/index.tsx
@@ -46,6 +46,7 @@ private: true
 @withStyleNew(generateStyle, 'TopNavBarLayout')
 class TopNavBarDesktopLayout extends Component<TopNavBarDesktopLayoutProps> {
   static readonly componentId = 'TopNavBar.DesktopLayout'
+  static readonly themeId = 'TopNavBarLayout'
 
   static allowedProps = allowedProps
   static defaultProps = {}
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarLayout/SmallViewportLayout/index.tsx b/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarLayout/SmallViewportLayout/index.tsx
@@ -83,6 +83,7 @@ class TopNavBarSmallViewportLayout extends Component<
   TopNavBarSmallViewportLayoutState
 > {
   static readonly componentId = 'TopNavBar.SmallViewportLayout'
+  static readonly themeId = 'TopNavBarLayout'
 
   static allowedProps = allowedProps
   static defaultProps = {}
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarMenuItems/index.tsx b/packages/ui-top-nav-bar/src/TopNavBar/v2/TopNavBarMenuItems/index.tsx
@@ -66,6 +66,7 @@ class TopNavBarMenuItems extends Component<
   TopNavBarMenuItemsState
 > {
   static readonly componentId = 'TopNavBar.MenuItems'
+  static readonly themeId = 'TopNavBarMenuItems'
 
   static allowedProps = allowedProps
   static defaultProps = {}
diff --git a/packages/ui-tree-browser/src/TreeBrowser/v2/TreeButton/index.tsx b/packages/ui-tree-browser/src/TreeBrowser/v2/TreeButton/index.tsx
@@ -54,6 +54,7 @@ class TreeButton extends Component<
   { isHovered: boolean }
 > {
   static readonly componentId = 'TreeBrowser.Button'
+  static readonly themeId = 'TreeBrowserTreeButton'
 
   static allowedProps = allowedProps
 
diff --git a/packages/ui-tree-browser/src/TreeBrowser/v2/TreeCollection/index.tsx b/packages/ui-tree-browser/src/TreeBrowser/v2/TreeCollection/index.tsx
@@ -50,6 +50,7 @@ class TreeCollection extends Component<
   TreeCollectionState
 > {
   static readonly componentId = 'TreeBrowser.Collection'
+  static readonly themeId = 'TreeBrowserTreeCollection'
 
   static allowedProps = allowedProps
 
diff --git a/packages/ui-tree-browser/src/TreeBrowser/v2/TreeNode/index.tsx b/packages/ui-tree-browser/src/TreeBrowser/v2/TreeNode/index.tsx
@@ -53,6 +53,7 @@ in the TreeBrowser.
 @withStyleNew(generateStyles, 'TreeBrowserTreeButton')
 class TreeNode extends Component<TreeBrowserNodeProps, { isHovered: boolean }> {
   static readonly componentId = 'TreeBrowser.Node'
+  static readonly themeId = 'TreeBrowserTreeButton'
 
   static allowedProps = allowedProps
 
