refactor(many): remove checkerboard background in examples, fix TS type errors, use types from react-docgen

The checkedboard needed to go because dark squared did not meet WCAG 2.1 AA contrast requirements
against red error text.
Also type checking of docs during bootstrap and use types from react-docgen

Fixes INSTUI-4282

Author: matyasf

package-lock.json

@@ -24,6 +24,7 @@
 
 // This is the format of the saved JSON files
 import { Documentation } from 'react-docgen'
+import type { Theme } from '@instructure/ui-themes'
 
 type ProcessedFile =
   Documentation &
@@ -92,99 +93,6 @@ type JSDocFunctionReturns = {
     names: string[]
   }
 }
-// TODO these are from React-docgen Documentation.d.ts,
-// remove when react-docgen exports them
-interface MethodParameter {
-  name: string;
-  description?: string;
-  optional: boolean;
-  type?: TypeDescriptor<FunctionSignatureType> | null;
-}
-
-interface MethodReturn {
-  description?: string;
-  type: TypeDescriptor<FunctionSignatureType> | undefined;
-}
-
-interface PropDescriptor {
-  type?: PropTypeDescriptor;
-  flowType?: TypeDescriptor<FunctionSignatureType>;
-  tsType?: TypeDescriptor<TSFunctionSignatureType>;
-  required?: boolean;
-  defaultValue?: DefaultValueDescriptor;
-  description?: string;
-}
-
-interface PropTypeDescriptor {
-  name: 'any' | 'array' | 'arrayOf' | 'bool' | 'custom' | 'element' | 'elementType' | 'enum' | 'exact' | 'func' | 'instanceOf' | 'node' | 'number' | 'object' | 'objectOf' | 'shape' | 'string' | 'symbol' | 'union';
-  value?: unknown;
-  raw?: string;
-  computed?: boolean;
-  description?: string;
-  required?: boolean;
-}
-
-type TypeDescriptor<T = FunctionSignatureType> = ElementsType<T> | LiteralType | ObjectSignatureType<T> | SimpleType | T;
-
-interface DefaultValueDescriptor {
-  value: unknown;
-  computed: boolean;
-}
-interface BaseType {
-  required?: boolean;
-  nullable?: boolean;
-  alias?: string;
-}
-interface SimpleType extends BaseType {
-  name: string;
-  raw?: string;
-}
-interface LiteralType extends BaseType {
-  name: 'literal';
-  value: string;
-}
-interface ElementsType<T = FunctionSignatureType> extends BaseType {
-  name: string;
-  raw: string;
-  elements: Array<TypeDescriptor<T>>;
-}
-
-interface FunctionArgumentType<T> {
-  name: string
-  type?: TypeDescriptor<T>
-  rest?: boolean
-}
-
-interface FunctionSignatureType extends BaseType {
-  name: 'signature';
-  type: 'function';
-  raw: string;
-  signature: {
-    arguments: Array<FunctionArgumentType<FunctionSignatureType>>;
-    return?: TypeDescriptor<FunctionSignatureType>;
-  };
-}
-interface TSFunctionSignatureType extends FunctionSignatureType {
-  signature: {
-    arguments: Array<FunctionArgumentType<TSFunctionSignatureType>>;
-    return?: TypeDescriptor<TSFunctionSignatureType>;
-    this?: TypeDescriptor<TSFunctionSignatureType>;
-  };
-}
-interface ObjectSignatureType<T = FunctionSignatureType> extends BaseType {
-  name: 'signature';
-  type: 'object';
-  raw: string;
-  signature: {
-    properties: Array<{
-      key: TypeDescriptor<T> | string;
-      value: TypeDescriptor<T>;
-      description?: string;
-    }>;
-    constructor?: TypeDescriptor<T>;
-  };
-}
-// end react-docgen part
 
 type LibraryOptions = {
   name: string
@@ -237,7 +145,7 @@ type MainIconsData = {
 }
 
 type MainDocsData = {
-  themes: Record<string, { resource: any; requirePath: string }>
+  themes: Record<string, { resource: Theme; requirePath: string }>
   library: LibraryOptions
 } & ParsedDoc
 
@@ -246,16 +154,6 @@ export type {
   PackagePathData,
   YamlMetaInfo,
   JSDocFunctionReturns,
-  PropDescriptor,
-  MethodParameter,
-  MethodReturn,
-  TypeDescriptor,
-  TSFunctionSignatureType,
-  SimpleType,
-  LiteralType,
-  ElementsType,
-  ObjectSignatureType,
-  BaseType,
   LibraryOptions,
   Glyph,
   MainDocsData,

packages/__docs__/buildScripts/DataTypes.mts

@@ -22,10 +22,14 @@
  * SOFTWARE.
  */
 
-const themes = {
+import type { Theme } from '@instructure/ui-themes'
+// eslint-disable-next-line no-restricted-imports
+import type { ThemeFunctionsFunctional } from './src/App/props'
+
+const themes: ThemeFunctionsFunctional = {
   // TODO figure out subcomponents e.g.: Table.Cell
-  avatar: async (theme) =>
-    (await import('@instructure/ui-avatar/src/Avatar/theme.ts')).default(theme)
+  Avatar: async (theme: Theme) =>
+    (await import('@instructure/ui-avatar/src/Avatar/theme')).default(theme)
 }
 
 export default themes

packages/__docs__/functionalComponentThemes.ts

@@ -137,7 +137,7 @@
     "jsdoc-api": "^8.1.1",
     "mkdirp": "^3.0.1",
     "raw-loader": "^4.0.2",
-    "react-docgen": "^7.1.0",
+    "react-docgen": "^7.1.1",
     "svg-inline-loader": "^0.8.2",
     "webpack-bundle-analyzer": "^4.10.2"
   },

packages/__docs__/package.json

@@ -32,12 +32,7 @@ import {
 } from 'react'
 
 import { Alert } from '@instructure/ui-alerts'
-import {
-  InstUISettingsProvider,
-  withStyle,
-  jsx,
-  Global
-} from '@instructure/emotion'
+import { InstUISettingsProvider, withStyle, Global } from '@instructure/emotion'
 import { Flex } from '@instructure/ui-flex'
 import { Text } from '@instructure/ui-text'
 import { View } from '@instructure/ui-view'
@@ -398,7 +393,6 @@ class App extends Component<AppProps, AppState> {
 
     const { layout } = this.state
     const smallerScreens = layout === 'small' || layout === 'medium'
-
     const themeContent = (
       <View
         as="div"

packages/__docs__/src/App/index.tsx

@@ -30,6 +30,8 @@ import type {
   ProcessedFile
 } from '../../buildScripts/DataTypes.mts'
 import type { DocDataType } from '../Document/props'
+import type { Theme } from '@instructure/ui-themes'
+import type { ThemeVariables } from '@instructure/shared-types'
 
 type AppOwnProps = {
   trayWidth: number
@@ -97,8 +99,18 @@ type AppState = {
   currentDocData?: DocData
 }
 
+type ThemeFunctionsClassic = {
+  [K in keyof ThemeVariables]: (theme: Theme) => ThemeVariables[K]
+}
+
+export type ThemeFunctionsFunctional = Partial<{
+  [K in keyof ThemeVariables]: (theme: Theme) => Promise<ThemeVariables[K]>
+}>
+
 type DocData = ProcessedFile & {
-  componentInstance: any
+  componentInstance: Record<string, any> & {
+    generateComponentTheme?: ThemeFunctionsClassic[keyof ThemeFunctionsClassic]
+  }
   children: DocDataType[]
 }
 

packages/__docs__/src/App/props.ts

@@ -32,7 +32,9 @@ import { ColorTableProps } from './props'
 
 class ColorTable extends Component<ColorTableProps> {
   renderRows() {
-    const colorMap = Object.keys(this.props.colorNames).reduce((acc, color) => {
+    const colorMap: Record<string, string> = Object.keys(
+      this.props.colorNames
+    ).reduce((acc, color) => {
       const hex = this.props.colorNames[color]
       return { ...acc, [hex]: color }
     }, {})

packages/__docs__/src/ColorTable/index.tsx

@@ -25,8 +25,8 @@ import type { PropValidators } from '@instructure/shared-types'
 import PropTypes from 'prop-types'
 
 type ColorTableOwnProps = {
-  colors: any
-  colorNames: any
+  colors: Record<string, string>
+  colorNames: Record<string, string>
 }
 
 type PropKeys = keyof ColorTableOwnProps

packages/__docs__/src/ColorTable/props.ts

@@ -73,19 +73,20 @@ class Document extends Component<DocumentProps, DocumentState> {
 
   fetchGenerateComponentTheme = async () => {
     const { doc, themeVariables } = this.props
-    const generateComponentTheme =
-      doc?.componentInstance?.generateComponentTheme
+    const generateTheme = doc?.componentInstance?.generateComponentTheme
+    const generateThemeFunctional =
+      functionalComponentThemes[
+        doc.id as keyof typeof functionalComponentThemes
+      ]
     if (
-      generateComponentTheme &&
-      typeof generateComponentTheme === 'function' &&
+      generateTheme &&
+      typeof generateTheme === 'function' &&
       themeVariables
     ) {
-      this.setState({ componentTheme: generateComponentTheme(themeVariables) })
-    } else {
-      const componentTheme = await functionalComponentThemes[
-        doc.id.toLowerCase()
-      ](themeVariables)
-      this.setState({ componentTheme })
+      this.setState({ componentTheme: generateTheme(themeVariables) })
+    } else if (generateThemeFunctional && themeVariables) {
+      const componentTheme = await generateThemeFunctional(themeVariables)
+      this.setState({ componentTheme: componentTheme })
     }
   }
 

packages/__docs__/src/Document/index.tsx

@@ -24,19 +24,16 @@
 
 import PropTypes from 'prop-types'
 import type { ComponentStyle, WithStyleProps } from '@instructure/emotion'
-import type {
-  PropValidators,
-  BaseThemeVariables,
-  ComponentTheme
-} from '@instructure/shared-types'
+import type { PropValidators, ThemeVariables } from '@instructure/shared-types'
 import { DocData } from '../App/props'
+import { Theme } from '@instructure/ui-themes'
 
 type DocDataType = DocData & { legacyGitBranch?: string }
 
 type DocumentOwnProps = {
   doc: DocDataType
   description: string
-  themeVariables?: BaseThemeVariables & { key: string }
+  themeVariables?: Theme
   repository?: string
   layout?: 'small' | 'medium' | 'large' | 'x-large'
 }
@@ -73,7 +70,7 @@ type DocumentStyle = ComponentStyle<'githubCornerOctoArm' | 'githubCorner'>
 type DocumentState = {
   selectedDetailsTabIndex: number
   pageRef: HTMLDivElement | null
-  componentTheme: ComponentTheme
+  componentTheme: Partial<ThemeVariables[keyof ThemeVariables]>
 }
 
 const allowedProps: AllowedPropKeys = [