chore: auto generate package type exports (#3474)

* chore: poc for creating our own export to json * chore: pr feedback and spacing * chore: add component api toc * chore: update docs and templates * chore: typecheck * fix: side nav highlighting
twilio-labs · Sep 19, 2023 · e2d2d5c · e2d2d5c
1 parent 7d155c5
commit e2d2d5c
Show file tree

Hide file tree

Showing 115 changed files with 17,771 additions and 1,250 deletions.
diff --git a/.changeset/odd-oranges-knock.md b/.changeset/odd-oranges-knock.md
@@ -0,0 +1,6 @@
+---
+'@twilio-paste/user-dialog': patch
+'@twilio-paste/core': patch
+---
+
+[User Dialog]: small improvement to the `UserDiaglogButton` types to omit the color prop type from Global HTML attributes, to prevent a type clash
diff --git a/.changeset/shaggy-monkeys-talk.md b/.changeset/shaggy-monkeys-talk.md
@@ -0,0 +1,6 @@
+---
+'@twilio-paste/table': patch
+'@twilio-paste/core': patch
+---
+
+[Table] Added TsDoc type annotations
diff --git a/.changeset/shy-cups-move.md b/.changeset/shy-cups-move.md
@@ -0,0 +1,6 @@
+---
+'@twilio-paste/button': patch
+'@twilio-paste/core': patch
+---
+
+[Button] Added TsDoc type annotations
diff --git a/.changeset/strange-eggs-hear.md b/.changeset/strange-eggs-hear.md
@@ -0,0 +1,6 @@
+---
+'@twilio-paste/anchor': patch
+'@twilio-paste/core': patch
+---
+
+[Anchor] Add TsDoc type annotations
diff --git a/.danger/utils.ts b/.danger/utils.ts
@@ -75,7 +75,9 @@ export const getUnpublishedPackageNames = (touchedFiles: string[], publicPackage
       filePath.includes('/paste-design-tokens/tokens/') ||
       filePath.includes('/paste-design-tokens/formatters/') ||
       filePath.includes('/paste-design-tokens/types/') ||
-      filePath.includes('/paste-codemods/')
+      filePath.includes('/paste-codemods/bin/') ||
+      filePath.includes('/paste-codemods/transforms/') ||
+      filePath.includes('/paste-codemods/tools/.cache/')
     ) {
       uniquePackages.add(packageName);
     }

diff --git a/.yarn/releases/yarn-3.5.0.cjs → .yarn/releases/yarn-3.6.3.cjs b/.yarn/releases/yarn-3.5.0.cjs → .yarn/releases/yarn-3.6.3.cjs
diff --git a/.yarnrc.yml b/.yarnrc.yml
@@ -6,4 +6,4 @@ plugins:
   - path: .yarn/plugins/@yarnpkg/plugin-interactive-tools.cjs
     spec: "@yarnpkg/plugin-interactive-tools"
 
-yarnPath: .yarn/releases/yarn-3.5.0.cjs
+yarnPath: .yarn/releases/yarn-3.6.3.cjs
diff --git a/cypress/integration/sitemap-vrt/constants.ts b/cypress/integration/sitemap-vrt/constants.ts
@@ -21,6 +21,8 @@ export const SITEMAP = [
   '/components/account-switcher/',
   '/components/aspect-ratio/',
   '/components/anchor/',
+  '/components/anchor/api',
+  '/components/anchor/changelog',
   '/components/alert-dialog/',
   '/components/avatar/',
   '/components/breadcrumb/',
@@ -38,6 +40,8 @@ export const SITEMAP = [
   '/components/display-pill-group/',
   '/components/disclosure/',
   '/components/button/',
+  '/components/button/api',
+  '/components/button/changelog',
   '/components/button-group/',
   '/components/flex/',
   '/components/file-picker/',
@@ -91,6 +95,8 @@ export const SITEMAP = [
   '/components/user-dialog/',
   '/components/textarea/',
   '/components/table/',
+  '/components/table/api',
+  '/components/table/changelog',
   '/components/visual-picker/',
   '/core/',
   '/core/changelog/',

diff --git a/internal-docs/engineering/core/adding-customization-to-components.md b/internal-docs/engineering/core/adding-customization-to-components.md
@@ -2,7 +2,7 @@
 
 For components being exported:
 
-1. Add `element` to its Props and Types using Box (Pick&lt;BoxProps, ‘element’>)
+1. Add `element` to its Props and Types by listing `element?: BoxProps['element']` and using TsDoc comments to give it a description and `@default` value
 2. Refactor component to use Box and/or Text
 3. Add `element = ‘DEFAULT_NAME’` in the props of the component
 4. Have `element={element}` in the props for Box and/or Text when used

diff --git a/internal-docs/engineering/doc-site/mdx.md b/internal-docs/engineering/doc-site/mdx.md
@@ -17,3 +17,101 @@ export const getStaticProps = async () => {
   };
 };
 ```
+
+## Component pages
+
+Component pages have their own Layout, `ComponentPageLayout`. This layout handles a few things for you, like positioning the Table of Contents Aside and the Component Page header.
+
+This means you need to supply `getStaticProps` with some more data than `DefaultLayout` needs.
+
+```tsx
+import ComponentPageLayout from '../../../layouts/ComponentPageLayout';
+import {getFeature, getNavigationData} from '../../../utils/api'; // import this last to avoid issues with the MDXProvider
+
+export default ComponentPageLayout;
+
+export const getStaticProps = async () => {
+  const navigationData = await getNavigationData();
+  const feature = await getFeature('Anchor');
+  return {
+    props: {
+      data: {
+        ...packageJson,
+        ...feature,
+      },
+      // data for the side nav
+      navigationData,
+      // provided by a custom mdx plugin for the TOC
+      mdxHeadings,
+      // Everything needed to render a Page Header
+      pageHeaderData: {
+        categoryRoute: SidebarCategoryRoutes.COMPONENTS,
+        githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/anchor',
+        storybookUrl: '/?path=/story/components-anchor--default',
+      },
+    },
+  };
+};
+```
+
+`ComponentPageLayout` is designed to accomodate a three page component structure. Guidelines, API and Changelog.
+
+When building an API page you must fetch the ComponentAPI data you are documenting and wanting to render. The full API page might look something like.
+
+````tsx
+export const meta = {
+  title: 'Anchor - API',
+  package: '@twilio-paste/anchor',
+  description: 'The anchor can be used to hyperlink to another URL. It accepts both internal and external URLs.',
+  slug: '/components/anchor/api',
+};
+
+import Changelog from '@twilio-paste/anchor/CHANGELOG.md';
+import packageJson from '@twilio-paste/anchor/package.json';
+
+import {SidebarCategoryRoutes} from '../../../constants';
+import ComponentPageLayout from '../../../layouts/ComponentPageLayout';
+import {getFeature, getNavigationData, getComponentAPI} from '../../../utils/api';
+
+export default ComponentPageLayout;
+
+export const getStaticProps = async () => {
+  const navigationData = await getNavigationData();
+  const feature = await getFeature('Anchor');
+  const {componentAPI, componentApiTocData} = getComponentAPI('@twilio-paste/anchor');
+  return {
+    props: {
+      data: {
+        ...packageJson,
+        ...feature,
+      },
+      componentAPI,
+      mdxHeadings: [...mdxHeadings, ...componentApiTocData],
+      navigationData,
+      pageHeaderData: {
+        categoryRoute: SidebarCategoryRoutes.COMPONENTS,
+        githubUrl: 'https://github.com/twilio-labs/paste/tree/main/packages/paste-core/components/anchor',
+        storybookUrl: '/?path=/story/components-anchor--default',
+      },
+    },
+  };
+};
+
+## Installation
+
+```bash
+yarn add @twilio-paste/anchor - or - yarn add @twilio-paste/core
+````
+
+## Usage
+
+```jsx
+import {Anchor} from '@twilio-paste/core/anchor';
+
+const Component = () => <Anchor href="https://paste.twilio.design">Go to Paste</Anchor>;
+```
+
+## Props
+
+<PropsTable componentAPI={props.componentAPI} />
+```
diff --git a/nx.json b/nx.json
@@ -14,6 +14,7 @@
         "cacheableOperations": [
           "build",
           "build:js",
+          "build:typedocs",
           "tsc",
           "build:types",
           "build:codemods",
@@ -47,6 +48,10 @@
         "{projectRoot}/types"
       ]
     },
+    "build:typedocs": {
+      "dependsOn": ["^build:typedocs", "^tsc"],
+      "outputs": ["{projectRoot}/type-docs.json"]
+    },
     "tsc": {
       "dependsOn": ["^tsc"],
       "outputs": ["{projectRoot}/dist", "{projectRoot}/types"]

diff --git a/package.json b/package.json
@@ -30,9 +30,10 @@
     "start:token-contrast-checker": "yarn workspace @twilio-paste/token-contrast-checker start",
     "start:nextjs-template": "yarn workspace @twilio-paste/nextjs-template dev",
     "start:contrast-checking": "concurrently \"yarn:start:tokens\" \"yarn:start:token-contrast-checker\"",
-    "prebuild": "ts-node ./tools/build/pre-build.ts && yarn packages:check",
+    "prebuild": "tsx ./tools/build/pre-test.ts && tsx ./tools/build/pre-build.ts && yarn packages:check",
     "build": "yarn prebuild && yarn nx run-many --target=build --exclude @twilio-paste/website @twilio-paste/theme-designer @twilio-paste/nextjs-template @twilio-paste/token-contrast-checker",
     "build:js": "yarn prebuild && yarn nx run-many --target=build:js --exclude @twilio-paste/website @twilio-paste/theme-designer",
+    "build:typedocs": "yarn prebuild && yarn nx run-many --target=build:typedocs",
     "build:core": "yarn nx run @twilio-paste/core:build",
     "build:codemods": "yarn nx run @twilio-paste/codemods:build",
     "build:tokens": "yarn nx run @twilio-paste/design-tokens:tokens",
@@ -47,11 +48,11 @@
     "release": "yarn changeset publish",
     "release:next": "yarn lerna publish -m 'chore(release): pre release' --conventional-commits --canary --preid beta --dist-tag next",
     "version": "yarn changeset version && yarn install --mode=update-lockfile",
-    "sync-internal-peer-dependencies": "ts-node ./tools/build/version.ts",
-    "clean": "ts-node ./tools/build/clean-repo.ts && yarn nx run-many --target=clean && yarn",
-    "clean:full": "ts-node ./tools/build/clean-repo.ts && yarn nx run-many --target=clean && rm -rf node_modules/ && yarn",
+    "sync-internal-peer-dependencies": "tsx ./tools/build/version.ts",
+    "clean": "tsx ./tools/build/clean-repo.ts && yarn nx run-many --target=clean && yarn",
+    "clean:full": "tsx ./tools/build/clean-repo.ts && yarn nx run-many --target=clean && rm -rf node_modules/ && yarn",
     "clean:core": "yarn workspace @twilio-paste/core clean",
-    "pre-test": "ts-node ./tools/build/pre-test.ts",
+    "pre-test": "tsx ./tools/build/pre-test.ts",
     "test": "jest",
     "test:coverage": "jest --coverage",
     "test:website": "yarn cypress run --record",
@@ -72,14 +73,14 @@
     "lint:nextjs-template": "eslint -c ./templates/paste-nextjs-template/.eslintrc.json --ext .tsx,.ts ./templates/paste-nextjs-template",
     "lint:vscode-intellisense": "eslint -c ./apps/vs-code-intellisense/.eslintrc.json --ext .tsx,.ts ./apps/vs-code-intellisense",
     "lint:repo": "eslint -c .eslintrc.repo.js --ext .tsx,.ts .",
-    "type-check": "yarn nx run-many --target=tsc",
+    "type-check": "yarn prebuild && yarn nx run-many --target=tsc",
     "tsc": "echo 'Did you mean to run yarn type-check?'",
     "chromatic": "chromatic",
     "packages:check": "manypkg check && monopeers check",
     "packages:fix": "manypkg fix && monopeers fix",
     "changeset": "changeset",
     "create:package": "plop create-package",
-    "token-usage": "ts-node tools/build/token-usage-detector.ts",
+    "token-usage": "tsx tools/build/token-usage-detector.ts",
     "nx": "nx"
   },
   "dependencies": {
@@ -204,9 +205,8 @@
     "storybook": "7.2.0",
     "terser": "^5.14.2",
     "theo": "^8.1.5",
-    "ts-node": "^10.0.0",
     "tslib": "^2.0.3",
-    "typedoc": "^0.20.24",
+    "tsx": "^3.12.10",
     "typescript": "^4.9.4",
     "ui-box": "^5.4.0",
     "unist-util-visit-esm": "npm:unist-util-visit@^4.1.2",
@@ -225,7 +225,7 @@
       "pre-push": "if git-branch-is main; then yarn pre-push; fi"
     }
   },
-  "packageManager": "yarn@3.5.0",
+  "packageManager": "yarn@3.6.3",
   "browserslist": [
     "last 2 versions",
     "not dead",

diff --git a/packages/paste-codemods/package.json b/packages/paste-codemods/package.json
@@ -10,7 +10,7 @@
   },
   "bin": "./bin/paste-codemod.js",
   "scripts": {
-    "build": "ts-node ./tools/create-package-mappings.ts"
+    "build": "tsx ./tools/create-package-mappings.ts"
   },
   "dependencies": {
     "chalk": "4.1.2",
@@ -25,6 +25,7 @@
     "@babel/core": "^7.21.4",
     "@babel/plugin-proposal-object-rest-spread": "^7.20.7",
     "@babel/preset-env": "^7.21.4",
-    "@twilio-paste/core": "^20.3.0"
+    "@twilio-paste/core": "^20.3.0",
+    "tsx": "^3.12.10"
   }
 }
diff --git a/packages/paste-core/components/alert-dialog/package.json b/packages/paste-core/components/alert-dialog/package.json
@@ -77,6 +77,7 @@
     "@types/react-dom": "^18.0.10",
     "prop-types": "^15.7.2",
     "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0",
+    "typescript": "^4.9.4"
   }
 }
diff --git a/packages/paste-core/components/alert/package.json b/packages/paste-core/components/alert/package.json
@@ -69,6 +69,7 @@
     "@types/react-dom": "^18.0.10",
     "prop-types": "^15.7.2",
     "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0",
+    "typescript": "^4.9.4"
   }
 }
diff --git a/packages/paste-core/components/anchor/package.json b/packages/paste-core/components/anchor/package.json
@@ -18,8 +18,9 @@
     "dist"
   ],
   "scripts": {
-    "build": "yarn clean && NODE_ENV=production node build.js && tsc",
+    "build": "yarn clean && NODE_ENV=production node build.js && tsc && yarn build:typedocs",
     "build:js": "NODE_ENV=development node build.js",
+    "build:typedocs": "tsx ../../../../tools/build/generate-type-docs",
     "clean": "rm -rf ./dist",
     "tsc": "tsc"
   },
@@ -58,6 +59,7 @@
     "prop-types": "^15.7.2",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
+    "tsx": "^3.12.10",
     "typescript": "^4.9.4"
   }
 }