Multi version

docs/contributor-docs/migrating-to-new-tokens.md

@@ -17,7 +17,7 @@ Changes needed:
 - Import token types from `@instructure/ui-themes` instead of `@instructure/shared-types`
 - Update `generateStyle` function to use `NewComponentTypes['ComponentName']` for the theme parameter
 - Replace old theme tokens with new token names from the design system
-- Replace `@withStyleRework` decorator with `@withStyle` and remove `generateComponentTheme`
+- Replace `@withStyleLegacy` decorator with `@withStyle` and remove `generateComponentTheme`
 - delete `theme.ts`
 
 If tokens are from a different (usually parent) components, add the `componentID` of that component as second paramater of `@withStyle` and use that name in the `generateStyle` function in `style.ts`: `NewComponentTypes['ParentComponentNameWithTheTokens']`

packages/__docs__/buildScripts/DataTypes.mts

@@ -155,5 +155,6 @@ export type {
   Glyph,
   MainDocsData,
   MainIconsData,
-  JsDocResult
+  JsDocResult,
+  Section
 }

packages/__docs__/buildScripts/build-docs.mts

@@ -48,7 +48,7 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 const require = createRequire(import.meta.url)
 
-// This needs to be required otherwise TSC will mess up the directory structure
+// This needs to be required, otherwise TSC will mess up the directory structure
 // in the output directory
 // eslint-disable-next-line @instructure/no-relative-imports
 const rootPackage = require('../../../package.json') // root package.json
@@ -65,21 +65,23 @@ const library: LibraryOptions = {
   scope: '@instructure'
 }
 
+// TODO this misses ui-react-utils/src/DeterministicIDContext/index.ts and maybe some others
 const pathsToProcess = [
   // these can be commented out for faster debugging
   'CHANGELOG.md',
-  '**/packages/**/*.md', // package READMEs
+  'CODE_OF_CONDUCT.md',
+  'LICENSE.md',
   '**/docs/**/*.md', // general docs
   '**/src/*.{ts,tsx}', // util src files
-  '**/src/*/*.{ts,tsx}', // component src files
-  '**/src/*/*/*.{ts,tsx}', // child component src files
-  'CODE_OF_CONDUCT.md',
-  'LICENSE.md'
+  // TODO expand this to support new components
+  '**/src/*/v1/*.md', // package READMEs
+  '**/src/*/v1/*.{ts,tsx}', // component src files
+  '**/src/*/v1/*/*.{ts,tsx}' // child component src files
 ]
 
 const pathsToIgnore = [
-  '**/macro.{js,ts}',
   '**/svg/**',
+  'packages/**/props.ts',
   'packages/*/README.md', // main package READMEs
   '**/packages/**/CHANGELOG.md',
   '**/config/**',
@@ -138,18 +140,30 @@ function buildDocs() {
         'Parsing markdown and source files... (' + matches.length + ' files)'
       )
       let docs = matches.map((relativePath) => {
-        // loop trough every source and Readme file
+        // loop through every source and Readme file
         return processSingleFile(path.resolve(relativePath))
       })
-      docs = docs.filter(Boolean) // filter out undefined
+      // filter out undefined and duplicates (because a component is parsed twice,
+      // by its index.ts and by its README)
+      const seen = new Set()
+      docs = docs.filter(item => {
+        if (!item) {
+          return false
+        } else if (seen.has(item.id)) {
+          return false
+        }
+        seen.add(item.id)
+        return true
+      })
+
       const themes = parseThemes()
       const clientProps = getClientProps(docs as ProcessedFile[], library)
-      const props: MainDocsData = {
+      const mainDocsData: MainDocsData = {
         ...clientProps,
         themes: themes,
         library
       }
-      const markdownsAndSources = JSON.stringify(props)
+      const markdownsAndSources = JSON.stringify(mainDocsData)
       fs.writeFileSync(
         buildDir + 'markdown-and-sources-data.json',
         markdownsAndSources
@@ -210,7 +224,7 @@ function processSingleFile(fullPath: string) {
   let docObject
   const dirName = path.dirname(fullPath)
   const fileName = path.parse(fullPath).name
-  if (fileName === 'index') {
+  if (fileName === 'index') { // e.g. ui/alerts/src/Alert/v1/index.tsx
     docObject = processFile(fullPath, projectRoot, library)
     if (!docObject) {
       return
@@ -221,8 +235,9 @@ function processSingleFile(fullPath: string) {
     docObject.description = readmeDesc
       ? docObject.description + readmeDesc
       : docObject.description
-  } else if (fileName === 'README') {
-    // if we edit a README, we'll need to add the changes to the components JSON
+  } else if (fileName === 'README') { // e.g. ui/alerts/src/Alert/v1/README.md
+    // If there is an index file in the same folder, it's a component, so
+    // the README will be the description and the props will be in the index file.
     let componentIndexFile: string | undefined
     if (fs.existsSync(path.join(dirName, 'index.tsx'))) {
       componentIndexFile = path.join(dirName, 'index.tsx')
@@ -244,6 +259,8 @@ function processSingleFile(fullPath: string) {
   if (!docObject) {
     return
   }
+  // eslint-disable-next-line no-console
+  console.info(`id: ${docObject.id} at ${fullPath}`)
   const docJSON = JSON.stringify(docObject)
   fs.writeFileSync(buildDir + 'docs/' + docObject.id + '.json', docJSON)
   return docObject

packages/__docs__/buildScripts/processFile.mts

@@ -33,8 +33,6 @@ export function processFile(
   projectRoot: string,
   library: LibraryOptions
 ): ProcessedFile | undefined {
-  // eslint-disable-next-line no-console
-  console.info(`Processing ${fullPath}`)
   const source = fs.readFileSync(fullPath)
   const dirName = path.dirname(fullPath) || process.cwd()
   const pathInfo = getPathInfo(fullPath, projectRoot, library)
@@ -49,13 +47,10 @@ export function processFile(
   let docId: string
   const lowerPath = docData.relativePath.toLowerCase()
   if (docData.id) {
-    // exist if it was in the description at the top
+    // exist if it was in the YAML description at the top
     docId = docData.id
-  } else if (
-    lowerPath.includes(path.sep + 'index.js') ||
-    lowerPath.includes(path.sep + 'index.tsx')
-  ) {
-    docId = path.basename(dirName) // return its folder name
+  } else if (lowerPath.includes(path.sep + 'index.tsx')) {
+    docId = docData.displayName!
   } else if (lowerPath.includes('readme.md')) {
     const folder = path.basename(dirName)
     docId = docData.describes ? folder + '__README' : folder

packages/__docs__/buildScripts/utils/getClientProps.mts

@@ -63,7 +63,7 @@ export function getClientProps(docs: ProcessedFile[], library: LibraryOptions) {
         tags: doc.tags
       }
       docIDs[id] = doc.srcPath
-      if (describes) {
+      if (describes) { // TODO unused
         parsed.descriptions[describes] = doc.description
       }
 

packages/__docs__/resolve.mjs

@@ -31,32 +31,32 @@ const alias = {
     import.meta.dirname,
     '../ui-a11y-content/src/'
   ),
-  '@instructure/ui-alerts$': path.resolve(import.meta.dirname, '../ui-alerts/src/'),
-  '@instructure/ui-avatar$': path.resolve(import.meta.dirname, '../ui-avatar/src/'),
-  '@instructure/ui-badge$': path.resolve(import.meta.dirname, '../ui-badge/src/'),
+  '@instructure/ui-alerts$': path.resolve(import.meta.dirname, '../ui-alerts/src/exports/a'),
+  '@instructure/ui-avatar$': path.resolve(import.meta.dirname, '../ui-avatar/src/exports/a'),
+  '@instructure/ui-badge$': path.resolve(import.meta.dirname, '../ui-badge/src/exports/a'),
   '@instructure/ui-billboard$': path.resolve(
     import.meta.dirname,
-    '../ui-billboard/src/'
+    '../ui-billboard/src/exports/a'
   ),
   '@instructure/ui-breadcrumb$': path.resolve(
     import.meta.dirname,
-    '../ui-breadcrumb/src/'
+    '../ui-breadcrumb/src/exports/a'
   ),
-  '@instructure/ui-buttons$': path.resolve(import.meta.dirname, '../ui-buttons/src/'),
-  '@instructure/ui-byline$': path.resolve(import.meta.dirname, '../ui-byline/src/'),
-  '@instructure/ui-calendar$': path.resolve(import.meta.dirname, '../ui-calendar/src/'),
-  '@instructure/ui-checkbox$': path.resolve(import.meta.dirname, '../ui-checkbox/src/'),
+  '@instructure/ui-buttons$': path.resolve(import.meta.dirname, '../ui-buttons/src/exports/a'),
+  '@instructure/ui-byline$': path.resolve(import.meta.dirname, '../ui-byline/src/exports/a'),
+  '@instructure/ui-calendar$': path.resolve(import.meta.dirname, '../ui-calendar/src/exports/a'),
+  '@instructure/ui-checkbox$': path.resolve(import.meta.dirname, '../ui-checkbox/src/exports/a'),
   '@instructure/ui-color-picker$': path.resolve(
     import.meta.dirname,
-    '../ui-color-picker/src/'
+    '../ui-color-picker/src/exports/a'
   ),
   '@instructure/ui-date-input$': path.resolve(
     import.meta.dirname,
-    '../ui-date-input/src/'
+    '../ui-date-input/src/exports/a'
   ),
   '@instructure/ui-date-time-input$': path.resolve(
     import.meta.dirname,
-    '../ui-date-time-input/src/'
+    '../ui-date-time-input/src/exports/a'
   ),
   '@instructure/ui-decorator$': path.resolve(import.meta.dirname, '../ui-decorator/src/'),
   '@instructure/ui-dialog$': path.resolve(import.meta.dirname, '../ui-dialog/src/'),
@@ -77,7 +77,7 @@ const alias = {
     import.meta.dirname,
     '../ui-expandable/src/'
   ),
-  '@instructure/ui-flex$': path.resolve(import.meta.dirname, '../ui-flex/src'),
+  '@instructure/ui-flex$': path.resolve(import.meta.dirname, '../ui-flex/src/exports/a'),
   '@instructure/ui-focusable$': path.resolve(
     import.meta.dirname,
     '../ui-focusable/src/'
@@ -88,34 +88,34 @@ const alias = {
   ),
   '@instructure/ui-form-field$': path.resolve(
     import.meta.dirname,
-    '../ui-form-field/src/'
+    '../ui-form-field/src/exports/a'
   ),
-  '@instructure/ui-grid$': path.resolve(import.meta.dirname, '../ui-grid/src/'),
+  '@instructure/ui-grid$': path.resolve(import.meta.dirname, '../ui-grid/src/exports/a'),
   '@instructure/ui-i18n$': path.resolve(import.meta.dirname, '../ui-i18n/src/'),
   '@instructure/ui-icons$': path.resolve(import.meta.dirname, '../ui-icons/src/'),
   '@instructure/ui-img$': path.resolve(import.meta.dirname, '../ui-img/src/'),
   '@instructure/ui-instructure$': path.resolve(import.meta.dirname, '../ui-instructure/src/'),
-  '@instructure/ui-link$': path.resolve(import.meta.dirname, '../ui-link/src/'),
-  '@instructure/ui-list$': path.resolve(import.meta.dirname, '../ui-list/src/'),
+  '@instructure/ui-link$': path.resolve(import.meta.dirname, '../ui-link/src/exports/a'),
+  '@instructure/ui-list$': path.resolve(import.meta.dirname, '../ui-list/src/exports/a'),
   '@instructure/ui-menu$': path.resolve(import.meta.dirname, '../ui-menu/src/'),
-  '@instructure/ui-metric$': path.resolve(import.meta.dirname, '../ui-metric/src/'),
+  '@instructure/ui-metric$': path.resolve(import.meta.dirname, '../ui-metric/src/exports/a'),
   '@instructure/ui-modal$': path.resolve(import.meta.dirname, '../ui-modal/src/'),
   '@instructure/ui-motion$': path.resolve(import.meta.dirname, '../ui-motion/src/'),
   '@instructure/ui-navigation$': path.resolve(
     import.meta.dirname,
-    '../ui-navigation/src/'
+    '../ui-navigation/src/exports/a'
   ),
   '@instructure/ui-number-input$': path.resolve(
     import.meta.dirname,
     '../ui-number-input/src/'
   ),
   '@instructure/ui-text-area$': path.resolve(
     import.meta.dirname,
-    '../ui-text-area/src/'
+    '../ui-text-area/src/exports/a'
   ),
   '@instructure/ui-text-input$': path.resolve(
     import.meta.dirname,
-    '../ui-text-input/src/'
+    '../ui-text-input/src/exports/a'
   ),
   '@instructure/ui-options$': path.resolve(import.meta.dirname, '../ui-options/src/'),
   '@instructure/ui-overlays$': path.resolve(import.meta.dirname, '../ui-overlays/src/'),
@@ -124,18 +124,18 @@ const alias = {
     '../ui-pagination/src/'
   ),
   '@instructure/ui-pages$': path.resolve(import.meta.dirname, '../ui-pages/src/'),
-  '@instructure/ui-pill$': path.resolve(import.meta.dirname, '../ui-pill/src/'),
-  '@instructure/ui-popover$': path.resolve(import.meta.dirname, '../ui-popover/src/'),
+  '@instructure/ui-pill$': path.resolve(import.meta.dirname, '../ui-pill/src/exports/a/'),
+  '@instructure/ui-popover$': path.resolve(import.meta.dirname, '../ui-popover/src/exports/a'),
   '@instructure/ui-position$': path.resolve(import.meta.dirname, '../ui-position/src/'),
   '@instructure/ui-portal$': path.resolve(import.meta.dirname, '../ui-portal/src/'),
-  '@instructure/ui-progress$': path.resolve(import.meta.dirname, '../ui-progress/src'),
+  '@instructure/ui-progress$': path.resolve(import.meta.dirname, '../ui-progress/src/exports/a'),
   '@instructure/ui-radio-input$': path.resolve(
     import.meta.dirname,
     '../ui-radio-input/src/'
   ),
   '@instructure/ui-range-input$': path.resolve(
     import.meta.dirname,
-    '../ui-range-input/src/'
+    '../ui-range-input/src/exports/a'
   ),
   '@instructure/ui-rating$': path.resolve(import.meta.dirname, '../ui-rating/src/'),
   '@instructure/ui-responsive$': path.resolve(
@@ -157,17 +157,17 @@ const alias = {
   ),
   '@instructure/ui-source-code-editor$': path.resolve(
     import.meta.dirname,
-    '../ui-source-code-editor/src/'
+    '../ui-source-code-editor/src/exports/a/'
   ),
-  '@instructure/ui-spinner$': path.resolve(import.meta.dirname, '../ui-spinner/src/'),
+  '@instructure/ui-spinner$': path.resolve(import.meta.dirname, '../ui-spinner/src/exports/a'),
   '@instructure/ui-svg-images$': path.resolve(
     import.meta.dirname,
     '../ui-svg-images/src/'
   ),
-  '@instructure/ui-table$': path.resolve(import.meta.dirname, '../ui-table/src/'),
-  '@instructure/ui-tabs$': path.resolve(import.meta.dirname, '../ui-tabs/src/'),
-  '@instructure/ui-tag$': path.resolve(import.meta.dirname, '../ui-tag/src/'),
-  '@instructure/ui-text$': path.resolve(import.meta.dirname, '../ui-text/src/'),
+  '@instructure/ui-table$': path.resolve(import.meta.dirname, '../ui-table/src//exports/a'),
+  '@instructure/ui-tabs$': path.resolve(import.meta.dirname, '../ui-tabs/src/exports/a'),
+  '@instructure/ui-tag$': path.resolve(import.meta.dirname, '../ui-tag/src/exports/a'),
+  '@instructure/ui-text$': path.resolve(import.meta.dirname, '../ui-text/src/exports/a'),
   '@instructure/ui-time-select$': path.resolve(
     import.meta.dirname,
     '../ui-time-select/src/'
@@ -176,26 +176,26 @@ const alias = {
     import.meta.dirname,
     '../ui-toggle-details/src/'
   ),
-  '@instructure/ui-tooltip$': path.resolve(import.meta.dirname, '../ui-tooltip/src/'),
+  '@instructure/ui-tooltip$': path.resolve(import.meta.dirname, '../ui-tooltip/src/exports/a'),
   '@instructure/ui-top-nav-bar$': path.resolve(
     import.meta.dirname,
-    '../ui-top-nav-bar/src/'
+    '../ui-top-nav-bar/src/exports/a'
   ),
-  '@instructure/ui-tray$': path.resolve(import.meta.dirname, '../ui-tray/src/'),
+  '@instructure/ui-tray$': path.resolve(import.meta.dirname, '../ui-tray/src/exports/a'),
   '@instructure/ui-tree-browser$': path.resolve(
     import.meta.dirname,
-    '../ui-tree-browser/src/'
+    '../ui-tree-browser/src/exports/a'
   ),
   '@instructure/ui-truncate-list$': path.resolve(
     import.meta.dirname,
-    '../ui-truncate-list/src/'
+    '../ui-truncate-list/src'
   ),
   '@instructure/ui-truncate-text$': path.resolve(
     import.meta.dirname,
     '../ui-truncate-text/src/'
   ),
   '@instructure/ui-utils$': path.resolve(import.meta.dirname, '../ui-utils/src/'),
-  '@instructure/ui-view$': path.resolve(import.meta.dirname, '../ui-view/src/'),
+  '@instructure/ui-view$': path.resolve(import.meta.dirname, '../ui-view/src/exports/a'),
   '@instructure/canvas-theme$': path.resolve(
     import.meta.dirname,
     '../canvas-theme/src/'
@@ -218,9 +218,9 @@ const alias = {
   ),
   '@instructure/ui-file-drop$': path.resolve(
     import.meta.dirname,
-    '../ui-file-drop/src/'
+    '../ui-file-drop/src/exports/a'
   ),
-  '@instructure/ui-heading$': path.resolve(import.meta.dirname, '../ui-heading/src/'),
+  '@instructure/ui-heading$': path.resolve(import.meta.dirname, '../ui-heading/src/exports/a'),
   '@instructure/emotion$': path.resolve(import.meta.dirname, '../emotion/src/')
 }
 

packages/__docs__/src/Nav/index.tsx

@@ -35,6 +35,7 @@ import { capitalizeFirstLetter } from '@instructure/ui-utils'
 import { NavToggle } from '../NavToggle'
 import type { NavProps, NavState } from './props'
 import { Alert } from '@instructure/ui-alerts'
+import type { Section } from '../../buildScripts/DataTypes.mjs'
 
 class Nav extends Component<NavProps, NavState> {
   _themeId: string
@@ -63,9 +64,9 @@ class Nav extends Component<NavProps, NavState> {
 
   setExpandedSections = (
     expanded: boolean,
-    sections: NavProps['sections']
-  ): NavProps['sections'] => {
-    const expandedSections: NavProps['sections'] = {}
+    sections: Record<string, boolean | Section>
+  ) => {
+    const expandedSections: Record<string, boolean> = {}
     Object.keys(sections).forEach((sectionId) => {
       expandedSections[sectionId] = expanded
     })
@@ -154,7 +155,9 @@ class Nav extends Component<NavProps, NavState> {
 
   matchQuery(str: string): boolean {
     const { query } = this.state
-    return query && typeof query.test === 'function' ? query.test(str) : true
+    return query && typeof (query as RegExp).test === 'function'
+      ? (query as RegExp).test(str)
+      : true
   }
 
   createNavToggle({
@@ -396,7 +399,7 @@ class Nav extends Component<NavProps, NavState> {
     } else {
       return this.createNavToggle({
         id: sectionId,
-        title: this.props.sections[sectionId].title,
+        title: this.props.sections[sectionId].title || '[no title]',
         children: this.renderSectionChildren(sectionId, markExpanded),
         variant
       })