feat: add page-header package

.changeset/grumpy-islands-sell.md

@@ -0,0 +1,5 @@
+---
+"@twilio-paste/codemods": minor
+---
+
+[Codemods] added a new package: page-header

.changeset/three-turtles-vanish.md

@@ -0,0 +1,6 @@
+---
+"@twilio-paste/page-header": major
+"@twilio-paste/core": minor
+---
+
+[Page Header] Create new Page Header package. Page Header is a layout component that wraps all top level components on a page.

.codesandbox/ci.json

@@ -66,6 +66,7 @@
     "/packages/paste-core/components/modal",
     "/packages/paste-core/primitives/modal-dialog",
     "/packages/paste-core/primitives/non-modal-dialog",
+    "/packages/paste-core/components/page-header",
     "/packages/paste-core/components/pagination",
     "/packages/paste-core/components/paragraph",
     "/packages/paste-core/components/popover",

.netlify/state.json

@@ -0,0 +1,3 @@
+{
+	"siteId": "27956759-b209-4ede-b295-528cad173647"
+}

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

@@ -166,6 +166,16 @@
   "ModalFooterActions": "@twilio-paste/core/modal",
   "ModalHeader": "@twilio-paste/core/modal",
   "ModalHeading": "@twilio-paste/core/modal",
+  "PageHeader": "@twilio-paste/core/page-header",
+  "PageHeaderActions": "@twilio-paste/core/page-header",
+  "PageHeaderContext": "@twilio-paste/core/page-header",
+  "PageHeaderDetailText": "@twilio-paste/core/page-header",
+  "PageHeaderDetails": "@twilio-paste/core/page-header",
+  "PageHeaderHeading": "@twilio-paste/core/page-header",
+  "PageHeaderInPageNavigation": "@twilio-paste/core/page-header",
+  "PageHeaderMeta": "@twilio-paste/core/page-header",
+  "PageHeaderParagraph": "@twilio-paste/core/page-header",
+  "PageHeaderPrefix": "@twilio-paste/core/page-header",
   "Pagination": "@twilio-paste/core/pagination",
   "PaginationArrow": "@twilio-paste/core/pagination",
   "PaginationEllipsis": "@twilio-paste/core/pagination",

packages/paste-core/components/page-header/__tests__/index.spec.tsx

@@ -0,0 +1,46 @@
+// eslint-disable-next-line import/no-extraneous-dependencies, import/order
+import { render, screen } from "@testing-library/react";
+
+import * as React from "react";
+
+import { Customized, Default } from "../stories/index.stories";
+
+describe("PageHeader", () => {
+  it("should render", () => {
+    const { getByText } = render(<Default />);
+    expect(getByText("Detail text")).toBeDefined();
+    expect(getByText("Page title")).toBeDefined();
+    expect(getByText("Badge")).toBeDefined();
+    expect(getByText("Paragraph text")).toBeDefined();
+  });
+});
+
+describe("Customization", () => {
+  it("should set defeault data-paste-element attribute on page header", () => {
+    render(<Customized />);
+    screen.debug();
+    expect(screen.getByTestId("page_header")).toHaveAttribute("data-paste-element", "PAGE_HEADER");
+    expect(screen.getByTestId("page_header_context")).toHaveAttribute("data-paste-element", "PAGE_HEADER_CONTEXT");
+    expect(screen.getByTestId("page_header_details")).toHaveAttribute("data-paste-element", "PAGE_HEADER_DETAILS");
+    expect(screen.getByTestId("page_header_detail_text")).toHaveAttribute(
+      "data-paste-element",
+      "PAGE_HEADER_DETAIL_TEXT",
+    );
+    expect(screen.getByTestId("page_header_prefix")).toHaveAttribute("data-paste-element", "PAGE_HEADER_PREFIX");
+    expect(screen.getByTestId("page_header_heading")).toHaveAttribute(
+      "data-paste-element",
+      "PAGE_HEADER_HEADING_WRAPPER",
+    );
+    expect(screen.getByTestId("page_header_heading").firstChild).toHaveAttribute(
+      "data-paste-element",
+      "PAGE_HEADER_HEADING",
+    );
+    expect(screen.getByTestId("page_header_actions")).toHaveAttribute("data-paste-element", "PAGE_HEADER_ACTIONS");
+    expect(screen.getByTestId("page_header_meta")).toHaveAttribute("data-paste-element", "PAGE_HEADER_META");
+    expect(screen.getByTestId("page_header_paragraph")).toHaveAttribute("data-paste-element", "PAGE_HEADER_PARAGRAPH");
+    expect(screen.getByTestId("page_header_in_page_navigation")).toHaveAttribute(
+      "data-paste-element",
+      "PAGE_HEADER_IN_PAGE_NAVIGATION",
+    );
+  });
+});

packages/paste-core/components/page-header/build.js

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

packages/paste-core/components/page-header/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@twilio-paste/page-header",
+  "version": "0.0.0",
+  "category": "layout",
+  "status": "production",
+  "description": "Page header is a layout component that wraps all top level components on a page.",
+  "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/heading": "^11.1.1",
+    "@twilio-paste/style-props": "^9.1.1",
+    "@twilio-paste/styling-library": "^3.0.0",
+    "@twilio-paste/text": "^10.1.1",
+    "@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/heading": "^11.1.1",
+    "@twilio-paste/style-props": "^9.1.1",
+    "@twilio-paste/styling-library": "^3.0.0",
+    "@twilio-paste/text": "^10.1.1",
+    "@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": "^3.12.10",
+    "typescript": "^4.9.4"
+  }
+}

packages/paste-core/components/page-header/src/PageHeader.tsx

@@ -0,0 +1,47 @@
+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 PageHeaderProps extends HTMLPasteProps<"div"> {
+  children?: React.ReactNode;
+  /**
+   * Size of the Page Header
+   * @default 'default'
+   * @type {'default' | 'compact''}
+   * @memberof PageHeaderProps
+   */
+  size?: "default" | "compact";
+  /**
+   * Overrides the default element name to apply unique styles with the Customization Provider
+   * @default 'PAGE_HEADER'
+   * @type {BoxProps['element']}
+   * @memberof PageHeaderProps
+   */
+  element?: BoxProps["element"];
+}
+
+export const PageHeaderContext = React.createContext<Pick<PageHeaderProps, "size">>({} as PageHeaderProps);
+
+const PageHeader = React.forwardRef<HTMLDivElement, PageHeaderProps>(
+  ({ element = "PAGE_HEADER", size, children, ...props }, ref) => {
+    return (
+      <PageHeaderContext.Provider value={{ size }}>
+        <Box
+          {...safelySpreadBoxProps(props)}
+          ref={ref}
+          element={element}
+          display="grid"
+          gridTemplateRows="auto auto auto"
+          gridTemplateAreas='"context" "details" "in_page_navigation"'
+        >
+          {children}
+        </Box>
+      </PageHeaderContext.Provider>
+    );
+  },
+);
+
+PageHeader.displayName = "PageHeader";
+
+export { PageHeader };

packages/paste-core/components/page-header/src/PageHeaderActions.tsx

@@ -0,0 +1,36 @@
+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 PageHeaderActionsProps extends HTMLPasteProps<"div"> {
+  children?: React.ReactNode;
+  /**
+   * Overrides the default element name to apply unique styles with the Customization Provider
+   * @default 'PAGE_HEADER_ACTIONS'
+   * @type {BoxProps['element']}
+   * @memberof PageHeaderActionsProps
+   */
+  element?: BoxProps["element"];
+}
+
+const PageHeaderActions = React.forwardRef<HTMLDivElement, PageHeaderActionsProps>(
+  ({ element = "PAGE_HEADER_ACTIONS", children, ...props }, ref) => {
+    return (
+      <Box
+        {...safelySpreadBoxProps(props)}
+        ref={ref}
+        element={element}
+        gridArea="actions"
+        justifySelf="end"
+        alignSelf="center"
+      >
+        {children}
+      </Box>
+    );
+  },
+);
+
+PageHeaderActions.displayName = "PageHeaderActions";
+
+export { PageHeaderActions };

packages/paste-core/components/page-header/src/PageHeaderContext.tsx

@@ -0,0 +1,38 @@
+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 PageHeaderContextProps extends HTMLPasteProps<"div"> {
+  children?: React.ReactNode;
+  /**
+   * Overrides the default element name to apply unique styles with the Customization Provider
+   * @default 'PAGE_HEADER_CONTEXT'
+   * @type {BoxProps['element']}
+   * @memberof PageHeaderContextProps
+   */
+  element?: BoxProps["element"];
+}
+
+const PageHeaderContext = React.forwardRef<HTMLDivElement, PageHeaderContextProps>(
+  ({ element = "PAGE_HEADER_CONTEXT", children, ...props }, ref) => {
+    return (
+      <Box
+        {...safelySpreadBoxProps(props)}
+        ref={ref}
+        element={element}
+        gridArea="context"
+        marginBottom="space50"
+        display="flex"
+        flexDirection="column"
+        rowGap="space130"
+      >
+        {children}
+      </Box>
+    );
+  },
+);
+
+PageHeaderContext.displayName = "PageHeaderContext";
+
+export { PageHeaderContext };

packages/paste-core/components/page-header/src/PageHeaderDetailText.tsx

@@ -0,0 +1,29 @@
+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 PageHeaderDetailTextProps extends HTMLPasteProps<"div"> {
+  children?: React.ReactNode;
+  /**
+   * Overrides the default element name to apply unique styles with the Customization Provider
+   * @default 'PAGE_HEADER_DETAIL_TEXT'
+   * @type {BoxProps['element']}
+   * @memberof PageHeaderDetailTextProps
+   */
+  element?: BoxProps["element"];
+}
+
+const PageHeaderDetailText = React.forwardRef<HTMLDivElement, PageHeaderDetailTextProps>(
+  ({ element = "PAGE_HEADER_DETAIL_TEXT", children, ...props }, ref) => {
+    return (
+      <Box {...safelySpreadBoxProps(props)} ref={ref} element={element} marginBottom="space30" gridArea="detail">
+        {children}
+      </Box>
+    );
+  },
+);
+
+PageHeaderDetailText.displayName = "PageHeaderDetailText";
+
+export { PageHeaderDetailText };

packages/paste-core/components/page-header/src/PageHeaderDetails.tsx

@@ -0,0 +1,38 @@
+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 PageHeaderDetailsProps extends HTMLPasteProps<"div"> {
+  children?: React.ReactNode;
+  /**
+   * Overrides the default element name to apply unique styles with the Customization Provider
+   * @default 'PAGE_HEADER_DETAILS'
+   * @type {BoxProps['element']}
+   * @memberof PageHeaderDetailsProps
+   */
+  element?: BoxProps["element"];
+}
+
+const PageHeaderDetails = React.forwardRef<HTMLDivElement, PageHeaderDetailsProps>(
+  ({ element = "PAGE_HEADER_DETAILS", children, ...props }, ref) => {
+    return (
+      <Box
+        {...safelySpreadBoxProps(props)}
+        ref={ref}
+        element={element}
+        marginBottom="space130"
+        display="grid"
+        gridTemplateColumns="auto auto 1fr"
+        gridTemplateRows="auto-fit"
+        gridTemplateAreas='"detail detail detail" "prefix heading actions" "meta meta meta" "paragraph paragraph paragraph"'
+      >
+        {children}
+      </Box>
+    );
+  },
+);
+
+PageHeaderDetails.displayName = "PageHeaderDetails";
+
+export { PageHeaderDetails };