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

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

@@ -325,9 +325,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

@@ -42,9 +42,6 @@ describe('generatePackageExportsMap', () => {
       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/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"
   },
@@ -54,6 +55,7 @@
     "prop-types": "^15.7.2",
     "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,66 +1,2 @@
-import * as React from 'react';
-import PropTypes from 'prop-types';
-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';
-
-if (process.env.NODE_ENV === 'development') {
-  AspectRatio.propTypes = {
-    children: PropTypes.node.isRequired,
-    ratio: PropTypes.string.isRequired,
-  };
-}
-
-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"
   },
@@ -54,6 +55,7 @@
     "prop-types": "^15.7.2",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
+    "tsx": "^3.12.10",
     "typescript": "^4.9.4"
   }
 }

packages/paste-core/layout/flex/src/Flex.tsx

@@ -0,0 +1,131 @@
+import * as React from 'react';
+import {Box, safelySpreadBoxProps} from '@twilio-paste/box';
+import type {FlexboxProps} from '@twilio-paste/style-props';
+
+import type {FlexProps} from './types';
+import {getGrow, getShrink, getBasis, getVertical, getWrap, hAlignToProps, vAlignToProps} from './helpers';
+
+const getFlexStyles = (props: FlexProps): FlexboxProps => {
+  const styles: FlexboxProps = {
+    justifyContent: props.vertical ? vAlignToProps(props) : hAlignToProps(props),
+    alignItems: props.vertical ? hAlignToProps(props) : vAlignToProps(props),
+  };
+
+  if (props.grow || props.shrink || props.basis) {
+    styles.flexGrow = getGrow(props);
+    styles.flexShrink = getShrink(props);
+    styles.flexBasis = getBasis(props);
+  }
+
+  if (props.vertical) {
+    styles.flexDirection = getVertical(props);
+  }
+
+  if (props.wrap) {
+    styles.flexWrap = getWrap(props);
+  }
+
+  return styles;
+};
+
+const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
+  (
+    {
+      as,
+      basis,
+      children,
+      display,
+      element = 'FLEX',
+      hAlignContent,
+      grow,
+      marginTop,
+      marginRight,
+      marginBottom,
+      marginLeft,
+      margin,
+      marginX,
+      marginY,
+      paddingTop,
+      paddingRight,
+      paddingBottom,
+      paddingLeft,
+      padding,
+      paddingX,
+      paddingY,
+      maxWidth,
+      minWidth = 'size0',
+      width,
+      height,
+      minHeight,
+      maxHeight,
+      size,
+      shrink,
+      vertical,
+      vAlignContent,
+      wrap,
+      ...props
+    },
+    ref
+  ) => {
+    const FlexStyles = React.useMemo(
+      () => getFlexStyles({basis, hAlignContent, grow, shrink, vertical, vAlignContent, wrap}),
+      [basis, hAlignContent, grow, shrink, vertical, vAlignContent, wrap]
+    );
+
+    if (size && (width || height)) {
+      // eslint-disable-next-line no-console
+      console.error('[Paste Flex]: you cannot set a height or width when using the size attribute');
+    }
+    if (
+      (marginX && (margin || marginBottom || marginLeft || marginRight || marginTop)) ||
+      (marginY && (margin || marginBottom || marginLeft || marginRight || marginTop))
+    ) {
+      // eslint-disable-next-line no-console
+      console.error(
+        '[Paste Flex]: you cannot set a top, right, bottom or left margin when using the marginX or marginY attributes.'
+      );
+    }
+    if (
+      (paddingX && (padding || paddingBottom || paddingLeft || paddingRight || paddingTop)) ||
+      (paddingY && (padding || paddingBottom || paddingLeft || paddingRight || paddingTop))
+    ) {
+      // eslint-disable-next-line no-console
+      console.error(
+        '[Paste Flex]: you cannot set a top, right, bottom or left padding when using the paddingX or paddingY attributes.'
+      );
+    }
+
+    const margins =
+      marginX || marginY ? {marginX, marginY} : {margin, marginBottom, marginLeft, marginRight, marginTop};
+    const paddings =
+      paddingX || paddingY ? {paddingX, paddingY} : {padding, paddingBottom, paddingLeft, paddingRight, paddingTop};
+    const widths = size ? {size} : {height, width};
+
+    return (
+      <Box
+        {...FlexStyles}
+        {...safelySpreadBoxProps(props)}
+        ref={ref}
+        as={as}
+        display={display}
+        element={element}
+        {...margins}
+        {...paddings}
+        minHeight={minHeight}
+        maxHeight={maxHeight}
+        maxWidth={maxWidth}
+        minWidth={minWidth}
+        {...widths}
+      >
+        {children}
+      </Box>
+    );
+  }
+);
+
+Flex.displayName = 'Flex';
+Flex.defaultProps = {
+  display: 'flex',
+};
+
+export {Flex};