feat: layout component type docs

.changeset/fast-buses-help.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/media-object': patch
+'@twilio-paste/core': patch
+---
+
+[Media Object]: Improved type annotations

.changeset/grumpy-boxes-pay.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/flex': patch
+'@twilio-paste/core': patch
+---
+
+[Flex]: Improved TsDoc annotations

.changeset/healthy-books-kneel.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/aspect-ratio': patch
+'@twilio-paste/core': patch
+---
+
+[Aspect Ratio]: improved TsDoc annotations

.changeset/neat-papayas-play.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/grid': patch
+'@twilio-paste/core': patch
+---
+
+[Grid]: Improved TsDoc annotations

.changeset/orange-flowers-sip.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/codemods': patch
+'@twilio-paste/core': patch
+---
+
+[Codemods] updated exports map

.changeset/poor-ways-collect.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/stack': patch
+'@twilio-paste/core': patch
+---
+
+[Stack]: Improved TsDoc annotations

cypress/integration/sitemap-vrt/constants.ts

@@ -20,6 +20,8 @@ export const SITEMAP = [
   '/blog/2023-08-02-paste-newsletter/',
   '/components/account-switcher/',
   '/components/aspect-ratio/',
+  '/components/aspect-ratio/api',
+  '/components/aspect-ratio/changelog',
   '/components/anchor/',
   '/components/anchor/api',
   '/components/anchor/changelog',
@@ -44,12 +46,16 @@ export const SITEMAP = [
   '/components/button/changelog',
   '/components/button-group/',
   '/components/flex/',
+  '/components/flex/api',
+  '/components/flex/changelog',
   '/components/file-picker/',
   '/components/file-uploader/',
   '/components/form/',
   '/components/combobox/',
   '/components/date-picker/',
   '/components/grid/',
+  '/components/grid/api',
+  '/components/grid/changelog',
   '/components/heading/',
   '/components/form-pill-group/',
   '/components/alert/',
@@ -64,6 +70,8 @@ export const SITEMAP = [
   '/components/list/',
   '/components/minimizable-dialog/',
   '/components/media-object/',
+  '/components/media-object/api',
+  '/components/media-object/changelog',
   '/components/meter',
   '/components/pagination/',
   '/components/modal/',
@@ -80,6 +88,8 @@ export const SITEMAP = [
   '/components/sidebar/',
   '/components/sidebar-navigation/',
   '/components/stack/',
+  '/components/stack/api',
+  '/components/stack/changelog',
   '/components/status-badge/',
   '/components/status-menu/',
   '/components/spinner/',

packages/paste-codemods/tools/.cache/mappings.json

@@ -307,9 +307,6 @@
   "MediaFigure": "@twilio-paste/core/media-object",
   "MediaObject": "@twilio-paste/core/media-object",
   "Stack": "@twilio-paste/core/stack",
-  "getStackChildMargins": "@twilio-paste/core/stack",
-  "getStackDisplay": "@twilio-paste/core/stack",
-  "getStackStyles": "@twilio-paste/core/stack",
   "BOX_PROPS_TO_BLOCK": "@twilio-paste/core/box",
   "Box": "@twilio-paste/core/box",
   "StyledBox": "@twilio-paste/core/box",

packages/paste-codemods/tools/__tests__/tools.spec.ts

@@ -34,17 +34,14 @@
     const mockMapping = await generatePackageExportsMap(mockGetPastePackages);
 
     expect(mockMapping).toEqual({
       BOX_PROPS_TO_BLOCK: '@twilio-paste/core/box',
       Box: '@twilio-paste/core/box',
       ComboboxPrimitive: '@twilio-paste/core/combobox-primitive',
       DisclosurePrimitive: '@twilio-paste/core/disclosure-primitive',
       DisclosurePrimitiveContent: '@twilio-paste/core/disclosure-primitive',
       Stack: '@twilio-paste/core/stack',
       StyledBox: '@twilio-paste/core/box',
       getCustomElementStyles: '@twilio-paste/core/box',
-      getStackChildMargins: '@twilio-paste/core/stack',
-      getStackDisplay: '@twilio-paste/core/stack',
-      getStackStyles: '@twilio-paste/core/stack',
       safelySpreadBoxProps: '@twilio-paste/core/box',
       useComboboxPrimitive: '@twilio-paste/core/combobox-primitive',
       useDisclosurePrimitiveState: '@twilio-paste/core/disclosure-primitive',

packages/paste-core/layout/aspect-ratio/__tests__/aspectRatio.spec.tsx

@@ -41,7 +41,7 @@ describe('handlePropValidation function', () => {
           <p>This is the AspectRatio utility without a valid ratio.</p>
         </AspectRatio>
       )
-    ).toThrow(`[Paste: AspectRatio] 'ratio' is invalid. Use a colon separated number pattern (4:3).`);
+    ).toThrow(`[Paste: AspectRatio] 'ratio' is invalid. Use a colon-separated number pattern (4:3).`);
   });
 
   it('should throw no errors if passed ratio prop is valid', () => {

packages/paste-core/layout/aspect-ratio/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"
   },
@@ -52,6 +53,7 @@
     "@types/react-dom": "^18.0.10",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
+    "tsx": "^3.12.10",
     "typescript": "^4.9.4"
   }
 }

packages/paste-core/layout/aspect-ratio/src/AspectRatio.tsx

@@ -0,0 +1,64 @@
+import * as React from 'react';
+import {Box} from '@twilio-paste/box';
+import {styled} from '@twilio-paste/styling-library';
+
+export interface AspectRatioProps {
+  /**
+   * Determines the aspect ratio of the element. Use a colon-separated number pattern (width:height).
+   *
+   * @type {string}
+   * @memberof AspectRatioProps
+   */
+  ratio: string;
+  children: NonNullable<React.ReactNode>;
+}
+
+const RATIO_REGEX = /^(\d+:\d*)$/;
+
+const isCorrectPattern = (ratio: string): boolean => RATIO_REGEX.test(ratio);
+
+const handlePropValidation = ({ratio}: AspectRatioProps): void => {
+  const hasRatio = ratio != null && ratio !== '';
+
+  if (!hasRatio) {
+    throw new Error(`[Paste: AspectRatio] Missing 'ratio' prop.`);
+  }
+
+  if (!isCorrectPattern(ratio)) {
+    throw new Error(`[Paste: AspectRatio] 'ratio' is invalid. Use a colon-separated number pattern (4:3).`);
+  }
+};
+
+const AspectRatioContainer = styled.div`
+  position: relative;
+
+  embed,
+  iframe,
+  object,
+  video {
+    position: absolute;
+    top: 0;
+    left: 0;
+    height: 100%;
+    width: 100%;
+  }
+`;
+
+const AspectRatio = React.forwardRef<HTMLDivElement, AspectRatioProps>((props, ref) => {
+  handlePropValidation(props);
+
+  const aspectArray = props.ratio.split(':').map(Number);
+  const aspectPercent = (aspectArray[1] / aspectArray[0]) * 100;
+
+  return (
+    <AspectRatioContainer ref={ref} style={{paddingBottom: `${aspectPercent}%`}}>
+      <Box position="absolute" top={0} right={0} bottom={0} left={0}>
+        {props.children}
+      </Box>
+    </AspectRatioContainer>
+  );
+});
+
+AspectRatio.displayName = 'AspectRatio';
+
+export {AspectRatio};

packages/paste-core/layout/aspect-ratio/src/index.tsx

@@ -1,58 +1,2 @@
-import * as React from 'react';
-import {Box} from '@twilio-paste/box';
-import {styled} from '@twilio-paste/styling-library';
-
-export interface AspectRatioProps {
-  ratio: string;
-  children: NonNullable<React.ReactNode>;
-}
-
-const RATIO_REGEX = /^(\d+:\d*)$/;
-
-const isCorrectPattern = (ratio: string): boolean => RATIO_REGEX.test(ratio);
-
-const handlePropValidation = ({ratio}: AspectRatioProps): void => {
-  const hasRatio = ratio != null && ratio !== '';
-
-  if (!hasRatio) {
-    throw new Error(`[Paste: AspectRatio] Missing 'ratio' prop.`);
-  }
-
-  if (!isCorrectPattern(ratio)) {
-    throw new Error(`[Paste: AspectRatio] 'ratio' is invalid. Use a colon separated number pattern (4:3).`);
-  }
-};
-
-const AspectRatioContainer = styled.div`
-  position: relative;
-
-  embed,
-  iframe,
-  object,
-  video {
-    position: absolute;
-    top: 0;
-    left: 0;
-    height: 100%;
-    width: 100%;
-  }
-`;
-
-const AspectRatio = React.forwardRef<HTMLDivElement, AspectRatioProps>((props, ref) => {
-  handlePropValidation(props);
-
-  const aspectArray = props.ratio.split(':').map(Number);
-  const aspectPercent = (aspectArray[1] / aspectArray[0]) * 100;
-
-  return (
-    <AspectRatioContainer ref={ref} style={{paddingBottom: `${aspectPercent}%`}}>
-      <Box position="absolute" top={0} right={0} bottom={0} left={0}>
-        {props.children}
-      </Box>
-    </AspectRatioContainer>
-  );
-});
-
-AspectRatio.displayName = 'AspectRatio';
-
-export {AspectRatio};
+export {AspectRatio} from './AspectRatio';
+export type {AspectRatioProps} from './AspectRatio';

packages/paste-core/layout/aspect-ratio/type-docs.json

@@ -0,0 +1,11 @@
+{
+  "AspectRatio": {
+    "ratio": {
+      "type": "string",
+      "defaultValue": null,
+      "required": true,
+      "externalProp": false,
+      "description": "Determines the aspect ratio of the element. Use a colon separated number pattern (width:height)."
+    }
+  }
+}

packages/paste-core/layout/flex/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"
   },
@@ -52,6 +53,7 @@
     "@types/react-dom": "^18.0.10",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
+    "tsx": "^3.12.10",
     "typescript": "^4.9.4"
   }
 }