feat!: create table cell for displaying links (#468)

Author: Fran McDade

package-lock.json

@@ -24,6 +24,7 @@
   "devDependencies": {
     "@commitlint/cli": "^17.4.2",
     "@commitlint/config-conventional": "^17.4.2",
+    "@emotion/jest": "^11.13.0",
     "@mui/types": "^7.4.0",
     "@next/eslint-plugin-next": "^14.2.28",
     "@storybook/addon-actions": "^8.6.4",

package.json

@@ -0,0 +1,63 @@
+import { LinkProps, Link as MLink, Typography } from "@mui/material";
+import { CellContext, RowData } from "@tanstack/react-table";
+import { BaseComponentProps } from "components/types";
+import React from "react";
+import { isValidUrl } from "../../../../../../common/utils";
+import { TYPOGRAPHY_PROPS } from "../../../../../../styles/common/mui/typography";
+import { isClientSideNavigation } from "../../../../../Links/common/utils";
+import { getComponent, getRelAttribute, getTargetAttribute } from "./utils";
+
+export const LinkCell = <
+  T extends RowData,
+  TValue extends LinkProps = LinkProps
+>({
+  getValue,
+}: BaseComponentProps & CellContext<T, TValue>): JSX.Element | null => {
+  const props = getValue();
+  const {
+    children,
+    className,
+    color,
+    href = "",
+    rel,
+    target,
+    underline,
+    ...linkProps
+  } = props;
+
+  // Determine if the href should use client-side navigation.
+  const isClientSide = isClientSideNavigation(href);
+
+  // Determine if the href is valid.
+  const isValid = isClientSide || isValidUrl(href);
+
+  // If the href is invalid, return a Typography component.
+  if (!isValid)
+    return (
+      <Typography
+        className={className}
+        color={TYPOGRAPHY_PROPS.COLOR.INHERIT}
+        component="span"
+        variant={TYPOGRAPHY_PROPS.VARIANT.INHERIT}
+        {...linkProps}
+      >
+        {children}
+      </Typography>
+    );
+
+  // If the href is valid, return a Link component.
+  return (
+    <MLink
+      className={className}
+      color={color}
+      component={getComponent(href, isClientSide)}
+      href={href}
+      rel={getRelAttribute(rel, isClientSide)}
+      target={getTargetAttribute(target, isClientSide)}
+      underline={underline}
+      {...linkProps}
+    >
+      {children}
+    </MLink>
+  );
+};

src/components/Table/components/TableCell/components/LinkCell/linkCell.tsx

@@ -0,0 +1,35 @@
+import { ComponentProps } from "react";
+import { TYPOGRAPHY_PROPS } from "../../../../../../../styles/common/mui/typography";
+import { LinkCell } from "../linkCell";
+import { GetValue } from "./types";
+
+export const CLIENT_SIDE_ARGS: Partial<ComponentProps<typeof LinkCell>> = {
+  getValue: (() => ({
+    children: "Explore",
+    href: "/",
+  })) as GetValue,
+};
+
+export const EXTERNAL_ARGS: Partial<ComponentProps<typeof LinkCell>> = {
+  getValue: (() => ({
+    children: "Explore",
+    href: "https://www.example.com",
+  })) as GetValue,
+};
+
+export const INVALID_ARGS: Partial<ComponentProps<typeof LinkCell>> = {
+  getValue: (() => ({
+    children: "Explore",
+  })) as GetValue,
+};
+
+export const WITH_CUSTOM_STYLE_ARGS: Partial<ComponentProps<typeof LinkCell>> =
+  {
+    getValue: (() => ({
+      children: "Explore",
+      color: "success",
+      href: "/",
+      underline: "none",
+      variant: TYPOGRAPHY_PROPS.VARIANT.TEXT_BODY_SMALL_400,
+    })) as GetValue,
+  };

src/components/Table/components/TableCell/components/LinkCell/stories/args.ts

@@ -0,0 +1,32 @@
+import { Meta, StoryObj } from "@storybook/react";
+import { LinkCell } from "../linkCell";
+import {
+  CLIENT_SIDE_ARGS,
+  EXTERNAL_ARGS,
+  INVALID_ARGS,
+  WITH_CUSTOM_STYLE_ARGS,
+} from "./args";
+
+const meta: Meta<typeof LinkCell> = {
+  component: LinkCell,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const ClientSide: Story = {
+  args: CLIENT_SIDE_ARGS,
+};
+
+export const External: Story = {
+  args: EXTERNAL_ARGS,
+};
+
+export const Invalid: Story = {
+  args: INVALID_ARGS,
+};
+
+export const WithCustomStyle: Story = {
+  args: WITH_CUSTOM_STYLE_ARGS,
+};

src/components/Table/components/TableCell/components/LinkCell/stories/linkCell.stories.tsx

@@ -0,0 +1,4 @@
+import { LinkProps } from "@mui/material";
+import { CellContext, RowData } from "@tanstack/react-table";
+
+export type GetValue = CellContext<RowData, LinkProps>["getValue"];

src/components/Table/components/TableCell/components/LinkCell/stories/types.ts

@@ -0,0 +1,59 @@
+import Link from "next/link";
+import { ElementType } from "react";
+import { isValidUrl } from "../../../../../../common/utils";
+import {
+  ANCHOR_TARGET,
+  REL_ATTRIBUTE,
+} from "../../../../../Links/common/entities";
+import {
+  assertAnchorRelAttribute,
+  assertAnchorTargetAttribute,
+} from "../../../../../common/Link/typeGuards";
+
+/**
+ * Returns the component to use for a link based on the given href and client-side navigation flag.
+ * @param href - The href attribute to use.
+ * @param isClientSide - Whether the link is a client-side navigation.
+ * @returns The component to use for the link.
+ */
+export function getComponent(href: string, isClientSide: boolean): ElementType {
+  if (isClientSide) return Link; // Use Next/Link for client-side navigation.
+  if (isValidUrl(href)) return "a"; // Use anchor tag for external links.
+  return "span"; // Use span for invalid links.
+}
+
+/**
+ * Returns the rel attribute for a link based on the given rel and client-side navigation flag.
+ * @param rel - The rel attribute to use.
+ * @param isClientSideNavigation - Whether the link is a client-side navigation.
+ * @returns The rel attribute for the link.
+ */
+export function getRelAttribute(
+  rel: string | undefined,
+  isClientSideNavigation: boolean
+): string {
+  if (rel) {
+    assertAnchorRelAttribute(rel);
+    return rel;
+  }
+  return isClientSideNavigation
+    ? REL_ATTRIBUTE.NO_OPENER
+    : REL_ATTRIBUTE.NO_OPENER_NO_REFERRER;
+}
+
+/**
+ * Returns the target attribute for a link based on the given target and client-side navigation flag.
+ * @param target - The target attribute to use.
+ * @param isClientSideNavigation - Whether the link is a client-side navigation.
+ * @returns The target attribute for the link.
+ */
+export function getTargetAttribute(
+  target: string | undefined,
+  isClientSideNavigation: boolean
+): string {
+  if (target) {
+    assertAnchorTargetAttribute(target);
+    return target;
+  }
+  return isClientSideNavigation ? ANCHOR_TARGET.SELF : ANCHOR_TARGET.BLANK;
+}

src/components/Table/components/TableCell/components/LinkCell/utils.ts

@@ -0,0 +1,35 @@
+import { ANCHOR_TARGET, REL_ATTRIBUTE } from "../../Links/common/entities";
+
+/**
+ * Asserts that the given value is a valid REL_ATTRIBUTE.
+ * @param value - Value to assert.
+ * @throws Error if the value is not a valid REL_ATTRIBUTE.
+ */
+export function assertAnchorRelAttribute(
+  value: string
+): asserts value is REL_ATTRIBUTE {
+  if (!Object.values(REL_ATTRIBUTE).includes(value as REL_ATTRIBUTE)) {
+    throw new Error(
+      `Expecting rel attribute: ${value} to be one of ${Object.values(
+        REL_ATTRIBUTE
+      )}`
+    );
+  }
+}
+
+/**
+ * Asserts that the given value is a valid ANCHOR_TARGET.
+ * @param value - Value to assert.
+ * @throws Error if the value is not a valid ANCHOR_TARGET.
+ */
+export function assertAnchorTargetAttribute(
+  value: string
+): asserts value is ANCHOR_TARGET {
+  if (!Object.values(ANCHOR_TARGET).includes(value as ANCHOR_TARGET)) {
+    throw new Error(
+      `Expecting anchor target: ${value} to be one of ${Object.values(
+        ANCHOR_TARGET
+      )}`
+    );
+  }
+}