feat(example-text): create package (#4157)

.changeset/eight-windows-rescue.md

@@ -0,0 +1,5 @@
+---
+"@twilio-paste/codemods": minor
+---
+
+[Codemods] add new export ExampleText

.changeset/ninety-islands-trade.md

@@ -0,0 +1,6 @@
+---
+"@twilio-paste/example-text": major
+"@twilio-paste/core": minor
+---
+
+[Example Text] create new component Example Text which is a stylized text wrapper that distinguishes user input examples from body text.

.codesandbox/ci.json

@@ -43,6 +43,7 @@
     "/packages/paste-core/components/display-pill-group",
     "/packages/paste-libraries/dropdown",
     "/packages/paste-core/components/editable-code-block",
+    "/packages/paste-core/components/example-text",
     "/packages/paste-core/components/file-picker",
     "/packages/paste-core/components/file-uploader",
     "/packages/paste-core/layout/flex",

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

@@ -112,6 +112,7 @@
   "EditableCodeBlock": "@twilio-paste/core/editable-code-block",
   "EditableCodeBlockHeader": "@twilio-paste/core/editable-code-block",
   "EditableCodeBlockWrapper": "@twilio-paste/core/editable-code-block",
+  "ExampleText": "@twilio-paste/core/example-text",
   "FilePicker": "@twilio-paste/core/file-picker",
   "FilePickerButton": "@twilio-paste/core/file-picker",
   "FileUploader": "@twilio-paste/core/file-uploader",

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

@@ -0,0 +1,20 @@
+import { render } from "@testing-library/react";
+import * as React from "react";
+
+import { ExampleText } from "../src";
+
+describe("ExampleText", () => {
+  it("should render text in a <samp> and <kbd> tag", () => {
+    const { getByText } = render(<ExampleText>test</ExampleText>);
+    expect(getByText("test").tagName).toEqual("KBD");
+    expect(getByText("test").parentElement?.tagName).toEqual("SAMP");
+  });
+  it("should have a default element attribute", () => {
+    const { getByText } = render(<ExampleText>test</ExampleText>);
+    expect(getByText("test").getAttribute("data-paste-element")).toEqual("EXAMPLE_TEXT");
+  });
+  it("should have a custom element attribute when set", () => {
+    const { getByText } = render(<ExampleText element="MY_EXAMPLE_TEXT">test</ExampleText>);
+    expect(getByText("test").getAttribute("data-paste-element")).toEqual("MY_EXAMPLE_TEXT");
+  });
+});

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

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

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

@@ -0,0 +1,59 @@
+{
+  "name": "@twilio-paste/example-text",
+  "version": "0.0.0",
+  "category": "typography",
+  "status": "production",
+  "description": "Example Text is a stylized text wrapper that distinguishes user input examples from body text.",
+  "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:typedocs": "tsx ../../../../tools/build/generate-type-docs",
+    "clean": "rm -rf ./dist",
+    "tsc": "tsc"
+  },
+  "peerDependencies": {
+    "@twilio-paste/animation-library": "^2.0.0",
+    "@twilio-paste/box": "^10.2.0",
+    "@twilio-paste/color-contrast-utils": "^5.0.0",
+    "@twilio-paste/customization": "^8.1.1",
+    "@twilio-paste/design-tokens": "^10.3.0",
+    "@twilio-paste/style-props": "^9.1.1",
+    "@twilio-paste/styling-library": "^3.0.0",
+    "@twilio-paste/theme": "^11.0.1",
+    "@twilio-paste/types": "^6.0.0",
+    "@types/react": "^16.8.6 || ^17.0.2 || ^18.0.27",
+    "@types/react-dom": "^16.8.6 || ^17.0.2 || ^18.0.10",
+    "react": "^16.8.6 || ^17.0.2 || ^18.0.0",
+    "react-dom": "^16.8.6 || ^17.0.2 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@twilio-paste/animation-library": "^2.0.0",
+    "@twilio-paste/box": "^10.2.0",
+    "@twilio-paste/color-contrast-utils": "^5.0.0",
+    "@twilio-paste/customization": "^8.1.1",
+    "@twilio-paste/design-tokens": "^10.3.0",
+    "@twilio-paste/style-props": "^9.1.1",
+    "@twilio-paste/styling-library": "^3.0.0",
+    "@twilio-paste/theme": "^11.0.1",
+    "@twilio-paste/types": "^6.0.0",
+    "@types/react": "^18.0.27",
+    "@types/react-dom": "^18.0.10",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^4.9.4"
+  }
+}

packages/paste-core/components/example-text/src/ExampleText.tsx

@@ -0,0 +1,44 @@
+import { Box, safelySpreadBoxProps } from "@twilio-paste/box";
+import type { BoxProps } from "@twilio-paste/box";
+import type { HTMLPasteProps } from "@twilio-paste/types";
+import * as React from "react";
+
+export interface ExampleTextProps extends HTMLPasteProps<"samp"> {
+  children?: React.ReactNode;
+  /**
+   * Overrides the default element name to apply unique styles with the Customization Provider
+   * @default 'EXAMPLE_TEXT'
+   * @type {BoxProps['element']}
+   * @memberof ExampleTextProps
+   */
+  element?: BoxProps["element"];
+}
+
+const ExampleText = React.forwardRef<HTMLDivElement, ExampleTextProps>(
+  ({ element = "EXAMPLE_TEXT", children, ...props }, ref) => {
+    return (
+      <Box as="samp" display="inline-block" element={`${element}_WRAPPER`}>
+        <Box
+          {...safelySpreadBoxProps(props)}
+          as="kbd"
+          display="inline-block"
+          backgroundColor="colorBackground"
+          fontFamily="fontFamilyText"
+          fontWeight="fontWeightMedium"
+          fontSize="fontSize30"
+          lineHeight="lineHeight40"
+          borderRadius="borderRadius20"
+          paddingX="space30"
+          element={element}
+          ref={ref}
+        >
+          {children}
+        </Box>
+      </Box>
+    );
+  },
+);
+
+ExampleText.displayName = "ExampleText";
+
+export { ExampleText };

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

@@ -0,0 +1,2 @@
+export { ExampleText } from "./ExampleText";
+export type { ExampleTextProps } from "./ExampleText";

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

@@ -0,0 +1,55 @@
+import { Box } from "@twilio-paste/box";
+import { CustomizationProvider } from "@twilio-paste/customization";
+import { Paragraph } from "@twilio-paste/paragraph";
+import { useTheme } from "@twilio-paste/theme";
+import * as React from "react";
+
+import { ExampleText } from "../src";
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  title: "Components/Example Text",
+  component: ExampleText,
+};
+
+export const Default = (): React.ReactNode => {
+  return <ExampleText>HTTPBin echoes data in your HTTP request back to you</ExampleText>;
+};
+
+export const Inline = (): React.ReactNode => {
+  return (
+    <Box maxWidth="size50">
+      <Paragraph>
+        To create your account, provide your full name, a valid email address, and a secure password. Your password must
+        contain at least eight characters, including uppercase letters, lowercase letters, numbers, and a special
+        character. For example, <ExampleText>Password123!</ExampleText> is a strong option. You may be asked to verify
+        your email address by clicking a link sent to your inbox.
+      </Paragraph>
+    </Box>
+  );
+};
+
+export const Customized = (): React.ReactNode => {
+  const theme = useTheme();
+  return (
+    <CustomizationProvider
+      theme={theme}
+      elements={{
+        CUSTOMIZED_EXAMPLE_TEXT_WRAPPER: {
+          padding: "space30",
+          backgroundColor: "colorBackgroundBrand10",
+          borderRadius: "borderRadius30",
+        },
+        CUSTOMIZED_EXAMPLE_TEXT: { fontFamily: "fontFamilyCode" },
+      }}
+    >
+      <ExampleText element="CUSTOMIZED_EXAMPLE_TEXT">HTTPBin echoes data in your HTTP request back to you</ExampleText>
+    </CustomizationProvider>
+  );
+};
+Customized.parameters = {
+  a11y: {
+    // no need to a11y check customization
+    disable: true,
+  },
+};

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

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