feat: create detail text package and docs page (#3000)

Co-authored-by: Sarah <sali@twilio.com>

.changeset/angry-jeans-kneel.md

@@ -0,0 +1,6 @@
+---
+'@twilio-paste/detail-text': major
+'@twilio-paste/core': minor
+---
+
+[Detail Text] create the new DetailText component, meant to be used for short pieces of secondary text content.

.codesandbox/ci.json

@@ -32,6 +32,7 @@
     "/packages/paste-core/components/date-picker",
     "/packages/paste-core/components/description-list",
     "/packages/paste-design-tokens",
+    "/packages/paste-core/components/detail-text",
     "/packages/paste-core/components/disclosure",
     "/packages/paste-core/primitives/disclosure",
     "/packages/paste-core/components/display-heading",

cypress/integration/sitemap-vrt/constants.ts

@@ -26,6 +26,7 @@ export const SITEMAP = [
   '/components/chat-log/',
   '/components/checkbox/',
   '/components/data-grid/',
+  '/components/detail-text',
   '/components/description-list/',
   '/components/display-heading/',
   '/components/display-pill-group/',

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

@@ -71,6 +71,7 @@
   "DescriptionListSet": "@twilio-paste/core/description-list",
   "DescriptionListTerm": "@twilio-paste/core/description-list",
   "StyledDescriptionListSet": "@twilio-paste/core/description-list",
+  "DetailText": "@twilio-paste/core/detail-text",
   "AnimatedDisclosureContent": "@twilio-paste/core/disclosure",
   "Disclosure": "@twilio-paste/core/disclosure",
   "DisclosureContent": "@twilio-paste/core/disclosure",

packages/paste-core/components/detail-text/__tests__/index.spec.tsx

@@ -0,0 +1,72 @@
+import * as React from 'react';
+import {render, screen} from '@testing-library/react';
+import {CustomizationProvider} from '@twilio-paste/customization';
+
+import {DetailText} from '../src';
+
+describe('DetailText', () => {
+  it('should render', () => {
+    render(<DetailText>test</DetailText>);
+    expect(screen.getByText('test')).toBeDefined();
+  });
+
+  it('should render the element based on the as prop', () => {
+    render(<DetailText as="li">test</DetailText>);
+    expect(screen.getByRole('listitem')).toBeDefined();
+  });
+
+  describe('Customization', () => {
+    it('should set default data paste element attribute', () => {
+      render(<DetailText data-testid="detail-text">test</DetailText>);
+
+      expect(screen.getByTestId('detail-text').dataset.pasteElement).toEqual('DETAIL_TEXT');
+    });
+
+    it('should set custom data paste element attribute', () => {
+      render(
+        <DetailText data-testid="detail-text" element="MY_DETAIL_TEXT">
+          test
+        </DetailText>
+      );
+
+      expect(screen.getByTestId('detail-text').dataset.pasteElement).toEqual('MY_DETAIL_TEXT');
+    });
+
+    it('should add custom styles', () => {
+      render(
+        <CustomizationProvider
+          baseTheme="default"
+          theme={TestTheme}
+          elements={{
+            DETAIL_TEXT: {
+              color: 'colorTextNew',
+            },
+          }}
+        >
+          <DetailText data-testid="detail-text">test</DetailText>
+        </CustomizationProvider>
+      );
+      expect(screen.getByTestId('detail-text')).toHaveStyleRule('color', 'rgb(109, 46, 209)');
+    });
+
+    it('should add custom styles with a custom data paste element attribute', () => {
+      render(
+        <CustomizationProvider
+          baseTheme="default"
+          theme={TestTheme}
+          elements={{
+            MY_DETAIL_TEXT: {
+              color: 'colorTextNew',
+            },
+          }}
+        >
+          <DetailText data-testid="detail-text" element="MY_DETAIL_TEXT">
+            test
+          </DetailText>
+        </CustomizationProvider>
+      );
+
+      expect(screen.getByTestId('detail-text')).toHaveStyleRule('color', 'rgb(109, 46, 209)');
+    });
+  });
+});

packages/paste-core/components/detail-text/build.js

@@ -0,0 +1,3 @@
+const {build} = require('../../../../tools/build/esbuild');
+
+build(require('./package.json'));

packages/paste-core/components/detail-text/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@twilio-paste/detail-text",
+  "version": "0.0.0",
+  "category": "typography",
+  "status": "production",
+  "description": "Detail text is typography used for short pieces of secondary text content.",
+  "author": "Twilio Inc.",
+  "license": "MIT",
+  "main:dev": "src/index.tsx",
+  "main": "dist/index.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "yarn clean && NODE_ENV=production node build.js && tsc",
+    "build:js": "NODE_ENV=development node build.js",
+    "build:props": "typedoc --tsconfig ./tsconfig.json --json ./dist/prop-types.json",
+    "clean": "rm -rf ./dist",
+    "tsc": "tsc"
+  },
+  "peerDependencies": {
+    "@twilio-paste/animation-library": "^0.3.2",
+    "@twilio-paste/box": "^7.0.0",
+    "@twilio-paste/customization": "^5.0.0",
+    "@twilio-paste/design-tokens": "^8.0.0",
+    "@twilio-paste/style-props": "^6.0.0",
+    "@twilio-paste/styling-library": "^1.0.0",
+    "@twilio-paste/theme": "^8.0.0",
+    "@twilio-paste/types": "^3.1.1",
+    "prop-types": "^15.7.2",
+    "react": "^16.8.6 || ^17.0.2",
+    "react-dom": "^16.8.6 || ^17.0.2"
+  },
+  "devDependencies": {
+    "@twilio-paste/animation-library": "^0.3.2",
+    "@twilio-paste/box": "^7.0.0",
+    "@twilio-paste/customization": "^5.0.0",
+    "@twilio-paste/design-tokens": "^8.0.0",
+    "@twilio-paste/style-props": "^6.0.0",
+    "@twilio-paste/styling-library": "^1.0.0",
+    "@twilio-paste/theme": "^8.0.0",
+    "@twilio-paste/types": "^3.1.1",
+    "prop-types": "^15.7.2",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "typescript": "^4.9.4"
+  }
+}

packages/paste-core/components/detail-text/src/index.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import {Box, safelySpreadBoxProps} from '@twilio-paste/box';
+import type {BoxProps} from '@twilio-paste/box';
+
+export interface DetailTextProps extends Omit<React.ComponentPropsWithRef<'div'>, 'children'> {
+  children?: React.ReactNode;
+  element?: BoxProps['element'];
+  as?: BoxProps['as'];
+  marginTop?: 'space0' | 'space30';
+}
+
+export const DetailText = React.forwardRef<HTMLDivElement, DetailTextProps>(
+  ({element = 'DETAIL_TEXT', as = 'div', children, marginTop = 'space30', ...props}, ref) => {
+    return (
+      <Box
+        as={as}
+        ref={ref}
+        element={element}
+        {...safelySpreadBoxProps(props)}
+        marginTop={marginTop}
+        color="colorTextWeak"
+        fontSize="fontSize20"
+        lineHeight="lineHeight20"
+        fontWeight="fontWeightMedium"
+      >
+        {children}
+      </Box>
+    );
+  }
+);
+
+DetailText.displayName = 'DetailText';
+
+DetailText.propTypes = {
+  as: PropTypes.string as any,
+  children: PropTypes.node,
+  element: PropTypes.string,
+  marginTop: PropTypes.oneOf(['space0', 'space30']),
+};

packages/paste-core/components/detail-text/stories/index.stories.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import type {StoryFn} from '@storybook/react';
+import {Box} from '@twilio-paste/box';
+import {CustomizationProvider} from '@twilio-paste/customization';
+import {useTheme} from '@twilio-paste/theme';
+
+import {DetailText} from '../src';
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: 'Components/Detail Text',
+  component: DetailText,
+};
+
+export const Default: StoryFn = () => (
+  <Box>
+    <Box height="size10" width="size10" backgroundColor="colorBackgroundStrong" />
+    <DetailText>This is sample detail text.</DetailText>
+  </Box>
+);
+export const NoMargin: StoryFn = () => (
+  <Box>
+    <Box height="size10" width="size10" backgroundColor="colorBackgroundStrong" />
+    <DetailText marginTop="space0">This is sample detail text with no margin.</DetailText>
+  </Box>
+);
+
+export const Customized: StoryFn = () => {
+  const theme = useTheme();
+
+  return (
+    <CustomizationProvider
+      theme={theme}
+      elements={{
+        DETAIL_TEXT: {
+          color: 'colorTextNew',
+          marginTop: 'space60',
+        },
+      }}
+    >
+      <Box>
+        <Box height="size10" width="size10" backgroundColor="colorBackgroundStrong" />
+        <DetailText>This is customized detail text.</DetailText>
+      </Box>
+    </CustomizationProvider>
+  );
+};

packages/paste-core/components/detail-text/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

packages/paste-core/core-bundle/.gitignore

@@ -28,6 +28,7 @@
 /date-picker
 /description-list
 /design-tokens
+/detail-text
 /disclosure
 /disclosure-primitive
 /display-heading

packages/paste-core/core-bundle/package.json

@@ -52,6 +52,7 @@
     "@twilio-paste/date-picker": "^3.0.2",
     "@twilio-paste/description-list": "^1.0.0",
     "@twilio-paste/design-tokens": "^8.5.0",
+    "@twilio-paste/detail-text": "^0.0.0",
     "@twilio-paste/disclosure": "^9.0.3",
     "@twilio-paste/disclosure-primitive": "^0.3.10",
     "@twilio-paste/display-heading": "^1.0.1",

packages/paste-core/core-bundle/src/detail-text.tsx

@@ -0,0 +1 @@
+export * from '@twilio-paste/detail-text';

packages/paste-core/core-bundle/src/index.tsx

@@ -20,6 +20,7 @@ export * from '@twilio-paste/combobox-primitive';
 export * from '@twilio-paste/data-grid';
 export * from '@twilio-paste/date-picker';
 export * from '@twilio-paste/description-list';
+export * from '@twilio-paste/detail-text';
 export * from '@twilio-paste/disclosure';
 export * from '@twilio-paste/disclosure-primitive';
 export * from '@twilio-paste/display-heading';