From 2f5ee61a482add1693b23ced86058021408b7c51 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <im.alexcarpenter@gmail.com>
Date: Fri, 18 Oct 2024 14:13:32 -0400
Subject: [PATCH] chore(ui): Add `<Card />` descriptors (#4365)

---
 .changeset/empty-mangos-help.md               |   2 +
 .../ui/src/contexts/AppearanceContext.tsx     |  20 +-
 packages/ui/src/primitives/card.tsx           | 322 +++++++++++++-----
 3 files changed, 253 insertions(+), 91 deletions(-)
 create mode 100644 .changeset/empty-mangos-help.md

diff --git a/.changeset/empty-mangos-help.md b/.changeset/empty-mangos-help.md
new file mode 100644
index 0000000000..a845151cc8
--- /dev/null
+++ b/.changeset/empty-mangos-help.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/ui/src/contexts/AppearanceContext.tsx b/packages/ui/src/contexts/AppearanceContext.tsx
index 2a9bd62e12..466e449416 100644
--- a/packages/ui/src/contexts/AppearanceContext.tsx
+++ b/packages/ui/src/contexts/AppearanceContext.tsx
@@ -32,7 +32,25 @@ type ButtonDescriptorIdentifier =
 type ConnectionDescriptorIdentifier = 'connectionList' | 'connectionListItem';
 type SeparatorDescriptorIdentifier = 'separator';
 type SpinnerDescriptorIdentifier = 'spinner';
-type CardDescriptorIdentifier = 'logoBox' | 'logoLink' | 'logoImage';
+type CardDescriptorIdentifier =
+  | 'cardRoot'
+  | 'cardRootDefault'
+  | 'cardRootInner'
+  | 'cardHeader'
+  | 'cardContent'
+  | 'cardTitle'
+  | 'cardDescription'
+  | 'cardBody'
+  | 'cardActions'
+  | 'cardFooter'
+  | 'cardFooterAction'
+  | 'cardFooterActionText'
+  | 'cardFooterActionLink'
+  | 'cardFooterActionButton'
+  | 'cardFooterActionPageLink'
+  | 'cardLogoBox'
+  | 'cardLogoLink'
+  | 'cardLogoImage';
 
 /**
  * Union of all valid descriptors used throughout the components.
diff --git a/packages/ui/src/primitives/card.tsx b/packages/ui/src/primitives/card.tsx
index 3e0ee817d0..d031e0068e 100644
--- a/packages/ui/src/primitives/card.tsx
+++ b/packages/ui/src/primitives/card.tsx
@@ -1,57 +1,82 @@
-import { cva, cx } from 'cva';
+import { cx } from 'cva';
 import * as React from 'react';
 
 import { useAppearance } from '~/contexts';
 import { mergeDescriptors, type ParsedElementsFragment } from '~/contexts/AppearanceContext';
 import type { PolymorphicForwardRefExoticComponent, PolymorphicPropsWithoutRef } from '~/types/utils';
+import { applyDescriptors } from '~/utils/dva';
 
 import { ClerkLogo } from './clerk-logo';
 import { Image } from './image';
 
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardRoot
+ */
 const RootDefaultElement = 'div';
 type RootOwnProps = {
   children?: React.ReactNode;
   banner?: React.ReactNode;
 };
 
+const cardRootLayoutStyle = {
+  cardRoot: {
+    className: [
+      '[--card-banner-height:theme(size.4)]',
+      '[--card-body-px:theme(spacing.10)]',
+      '[--card-body-py:theme(spacing.8)]',
+      '[--card-content-rounded-b:theme(borderRadius.lg)]',
+      'relative w-full max-w-[25rem]',
+    ].join(' '),
+  },
+  cardRootDefault: {},
+  cardRootInner: {},
+};
+const cardRootVisualStyle = {
+  cardRoot: {
+    className: 'bg-gray-2 ring-gray-a3 rounded-xl ring-1',
+  },
+  cardRootDefault: {
+    className: 'shadow-[0px_5px_15px_0px_theme(colors.gray.a4),0px_15px_35px_-5px_theme(colors.gray.a4)]',
+  },
+  cardRootInner: {
+    className: 'overflow-hidden rounded-[inherit]',
+  },
+};
+
 export const Root: PolymorphicForwardRefExoticComponent<RootOwnProps, typeof RootDefaultElement> = React.forwardRef(
   function CardRoot<T extends React.ElementType = typeof RootDefaultElement>(
-    { as, banner, children, className, ...props }: PolymorphicPropsWithoutRef<RootOwnProps, T>,
+    { as, banner, children, ...props }: PolymorphicPropsWithoutRef<RootOwnProps, T>,
     forwardedRef: React.ForwardedRef<Element>,
   ) {
+    const { elements } = useAppearance().parsedAppearance;
     const Element: React.ElementType = as || RootDefaultElement;
+    const cardRootDescriptors = applyDescriptors(elements, 'cardRoot');
+    const cardRootDefaultDescriptors = applyDescriptors(elements, 'cardRootDefault');
     return (
       <Element
         ref={forwardedRef}
-        data-card-root=''
         {...props}
         className={cx(
-          '[--card-banner-height:theme(size.4)]',
-          '[--card-body-px:theme(spacing.10)]',
-          '[--card-body-py:theme(spacing.8)]',
-          '[--card-content-rounded-b:theme(borderRadius.lg)]',
-          'bg-gray-2 ring-gray-a3 relative w-full max-w-[25rem] rounded-xl ring-1',
+          cardRootDescriptors.className,
           banner
             ? [
                 'mt-[calc(var(--card-banner-height)/2)]',
                 'shadow-[0px_-1.5px_0px_0px_theme(colors.warning.DEFAULT),0px_5px_15px_0px_theme(colors.gray.a4),0px_15px_35px_-5px_theme(colors.gray.a4)]',
               ]
-            : 'shadow-[0px_5px_15px_0px_theme(colors.gray.a4),0px_15px_35px_-5px_theme(colors.gray.a4)]',
-          className,
+            : cardRootDefaultDescriptors.className,
         )}
       >
         {banner && (
           <div
-            data-card-root-banner=''
             className={cx(
               'pointer-events-none absolute inset-x-0 -top-[calc(var(--card-banner-height)/2)] isolate z-[500] flex justify-center',
-              className,
             )}
           >
             <p
               className={cx(
                 'bg-warning pointer-events-auto inline-flex h-[--card-banner-height] items-center rounded-full px-2 text-[0.6875rem] font-medium tracking-[2%] text-white',
-                className,
               )}
               {...props}
             >
@@ -59,71 +84,99 @@ export const Root: PolymorphicForwardRefExoticComponent<RootOwnProps, typeof Roo
             </p>
           </div>
         )}
-        {children && (
-          <div
-            data-card-root-inner=''
-            className={cx('overflow-hidden rounded-[inherit]', className)}
-          >
-            {children}
-          </div>
-        )}
+        {children && <div {...mergeDescriptors(elements.cardRootInner)}>{children}</div>}
       </Element>
     );
   },
 );
 
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardContent
+ */
+const cardContentLayoutStyle = {
+  cardContent: {
+    className: 'relative flex flex-col gap-8 px-[--card-body-px] py-[--card-body-py]',
+  },
+} satisfies ParsedElementsFragment;
+const cardContentVisualStyle = {
+  cardContent: {
+    className: [
+      'bg-gray-surface  rounded-b-[--card-content-rounded-b] rounded-t-none',
+      'ring-gray-a3 shadow-[0px_0px_2px_0px_theme(colors.gray.a4),0px_1px_2px_0px_theme(colors.gray.a3)] ring-1',
+    ].join(' '),
+  },
+} satisfies ParsedElementsFragment;
+
 export const Content = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(function CardContent(
   { children, className, ...props },
   forwardedRef,
 ) {
+  const { elements } = useAppearance().parsedAppearance;
   return (
     <div
       ref={forwardedRef}
-      data-card-content=''
       {...props}
-      className={cx(
-        'bg-gray-surface relative flex flex-col gap-8 rounded-b-[--card-content-rounded-b] rounded-t-none px-[--card-body-px] py-[--card-body-py]',
-        'ring-gray-a3 shadow-[0px_0px_2px_0px_theme(colors.gray.a4),0px_1px_2px_0px_theme(colors.gray.a3)] ring-1',
-        className,
-      )}
+      {...mergeDescriptors(elements.cardContent)}
     >
       {children}
     </div>
   );
 });
 
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardHeader
+ */
+const cardHeaderLayoutStyle = {
+  cardHeader: {
+    className: 'z-1 flex flex-col items-center gap-1 text-center',
+  },
+} satisfies ParsedElementsFragment;
+const cardHeaderVisualStyle = {
+  cardHeader: {},
+} satisfies ParsedElementsFragment;
+
 export const Header = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(function CardHeader(
   { children, className, ...props },
   forwardedRef,
 ) {
+  const { elements } = useAppearance().parsedAppearance;
   return (
     <div
       ref={forwardedRef}
-      data-card-header=''
       {...props}
-      className={cx('z-1 flex flex-col items-center gap-1 text-center', className)}
+      {...mergeDescriptors(elements.cardHeader)}
     >
       {children}
     </div>
   );
 });
 
-const logoLayoutStyle = {
-  logoBox: {
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardLogo
+ */
+const cardLogoLayoutStyle = {
+  cardLogoBox: {
     className: 'z-1 mb-5 flex h-8 justify-center',
   },
-  logoLink: {
+  cardLogoLink: {
     className: '-m-0.5 rounded-sm p-0.5 outline-none focus-visible:ring',
   },
-  logoImage: {
+  cardLogoImage: {
     className: 'size-full object-contain',
   },
 } satisfies ParsedElementsFragment;
-const logoVisualStyle = {
-  logoBox: {},
-  logoLink: {},
-  logoImage: {},
+const cardLogoVisualStyle = {
+  cardLogoBox: {},
+  cardLogoLink: {},
+  cardLogoImage: {},
 } satisfies ParsedElementsFragment;
+
 export const Logo = React.forwardRef(function CardLogo(
   {
     href,
@@ -142,19 +195,18 @@ export const Logo = React.forwardRef(function CardLogo(
   const img = (
     <Image
       ref={forwardedRef}
-      data-card-logo=''
       src={src}
       size={200}
       {...props}
-      {...mergeDescriptors(elements.logoImage)}
+      {...mergeDescriptors(elements.cardLogoImage)}
     />
   );
   return (
-    <div {...mergeDescriptors(elements.logoBox)}>
+    <div {...mergeDescriptors(elements.cardLogoBox)}>
       {href ? (
         <a
           href={href}
-          {...mergeDescriptors(elements.logoLink)}
+          {...mergeDescriptors(elements.cardLogoLink)}
         >
           {img}
         </a>
@@ -165,15 +217,30 @@ export const Logo = React.forwardRef(function CardLogo(
   );
 });
 
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardTitle
+ */
+const cardTitleLayoutStyle = {
+  cardTitle: {},
+} satisfies ParsedElementsFragment;
+const cardTitleVisualStyle = {
+  cardTitle: {
+    className: 'leading-medium text-gray-12 text-lg font-bold',
+  },
+} satisfies ParsedElementsFragment;
+
 export const Title = React.forwardRef<HTMLHeadingElement, React.HTMLAttributes<HTMLHeadingElement>>(function CardTitle(
   { children, className, ...props },
   forwardedRef,
 ) {
+  const { elements } = useAppearance().parsedAppearance;
   return (
     <h2
       ref={forwardedRef}
-      data-card-title=''
       {...props}
+      {...mergeDescriptors(elements.cardTitle)}
       className={cx('leading-medium text-gray-12 text-lg font-bold', className)}
     >
       {children}
@@ -181,13 +248,28 @@ export const Title = React.forwardRef<HTMLHeadingElement, React.HTMLAttributes<H
   );
 });
 
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardDescription
+ */
+const cardDescriptionLayoutStyle = {
+  cardDescription: {},
+} satisfies ParsedElementsFragment;
+const cardDescriptionVisualStyle = {
+  cardDescription: {
+    className: 'text-gray-a11 text-base',
+  },
+} satisfies ParsedElementsFragment;
+
 export const Description = React.forwardRef<HTMLHeadingElement, React.HTMLAttributes<HTMLHeadingElement>>(
   function CardDescription({ children, className, ...props }, forwardedRef) {
+    const { elements } = useAppearance().parsedAppearance;
     return (
       <p
         ref={forwardedRef}
         {...props}
-        className={cx('text-gray-a11 text-base', className)}
+        {...mergeDescriptors(elements.cardDescription)}
       >
         {children}
       </p>
@@ -195,64 +277,111 @@ export const Description = React.forwardRef<HTMLHeadingElement, React.HTMLAttrib
   },
 );
 
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardBody
+ */
+const cardBodyLayoutStyle = {
+  cardBody: {
+    className: 'z-1 flex flex-col gap-6',
+  },
+} satisfies ParsedElementsFragment;
+const cardBodyVisualStyle = {
+  cardBody: {},
+} satisfies ParsedElementsFragment;
+
 export const Body = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(function CardBody(
   { children, className, ...props },
   forwardedRef,
 ) {
+  const { elements } = useAppearance().parsedAppearance;
+
   return (
     <div
       ref={forwardedRef}
-      data-card-body=''
       {...props}
-      className={cx('z-1 flex flex-col gap-6', className)}
+      {...mergeDescriptors(elements.cardBody)}
     >
       {children}
     </div>
   );
 });
 
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardActions
+ */
+const cardActionsLayoutStyle = {
+  cardActions: {
+    className: [
+      'z-1 flex flex-col gap-3',
+      // Note:
+      // Prevents underline interractions triggering outside of the link text
+      // https://linear.app/clerk/issue/SDKI-192/#comment-ebf943b0
+      '[&_[data-link]]:self-center',
+    ].join(' '),
+  },
+} satisfies ParsedElementsFragment;
+const cardActionsVisualStyle = {
+  cardActions: {},
+} satisfies ParsedElementsFragment;
+
 export const Actions = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(function CardActions(
   { children, className, ...props },
   forwardedRef,
 ) {
+  const { elements } = useAppearance().parsedAppearance;
+
   return (
     <div
       ref={forwardedRef}
-      data-card-actions=''
       {...props}
-      className={cx(
-        'z-1 flex flex-col gap-3',
-        // Note:
-        // Prevents underline interractions triggering outside of the link text
-        // https://linear.app/clerk/issue/SDKI-192/#comment-ebf943b0
-        '[&_[data-link]]:self-center',
-        className,
-      )}
+      {...mergeDescriptors(elements.cardActions)}
     >
       {children}
     </div>
   );
 });
 
-export const Banner = React.forwardRef(function CardBanner(
-  { children, className, ...props }: React.HTMLAttributes<HTMLParagraphElement>,
-  forwardedRef: React.ForwardedRef<HTMLParagraphElement>,
-) {
-  return (
-    <div
-      data-card-banner=''
-      className={cx('pointer-events-none absolute -top-2 isolate z-[500]', className)}
-    >
-      <p
-        ref={forwardedRef}
-        className={cx('pointer-events-auto text-sm font-medium text-orange-500', className)}
-        {...props}
-      >
-        {children}
-      </p>
-    </div>
-  );
-});
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * CardFooter
+ */
+const cardFooterLayoutStyle = {
+  cardFooter: {
+    className: 'grid',
+  },
+  cardFooterAction: {
+    className: 'px-6 py-4',
+  },
+  cardFooterActionText: {},
+  cardFooterActionLink: {},
+  cardFooterActionButton: {},
+  cardFooterActionPageLink: {},
+} satisfies ParsedElementsFragment;
+const cardFooterVisualStyle = {
+  cardFooter: {},
+  cardFooterAction: {
+    className: 'border-gray-a3 border-b last-of-type:border-b-transparent',
+  },
+  cardFooterActionText: {
+    className: 'text-gray-a11 text-center text-base',
+  },
+  cardFooterActionLink: {
+    className:
+      'text-accent-a10 text-base font-medium hover:underline rounded-sm outline-none focus-visible:ring -mx-0.5 px-0.5',
+  },
+  cardFooterActionButton: {
+    className:
+      'text-accent-a10 text-base font-medium hover:underline rounded-sm outline-none focus-visible:ring -mx-0.5 px-0.5',
+  },
+  cardFooterActionPageLink: {
+    className: 'text-gray-a11 text-base font-medium hover:underline',
+  },
+} satisfies ParsedElementsFragment;
 
 export const Footer = React.forwardRef(function CardFooter(
   {
@@ -271,6 +400,7 @@ export const Footer = React.forwardRef(function CardFooter(
   } & React.HTMLAttributes<HTMLDivElement>,
   forwardedRef: React.ForwardedRef<HTMLDivElement>,
 ) {
+  const { elements } = useAppearance().parsedAppearance;
   const hasPageLinks = helpPageUrl || privacyPageUrl || termsPageUrl;
   const renderFooter = branded || hasPageLinks || children;
   const renderSubFooter = branded || hasPageLinks;
@@ -279,9 +409,8 @@ export const Footer = React.forwardRef(function CardFooter(
   return renderFooter ? (
     <div
       ref={forwardedRef}
-      data-card-footer=''
       {...props}
-      className={cx('grid', className)}
+      {...mergeDescriptors(elements.cardFooter)}
     >
       {children}
 
@@ -323,12 +452,12 @@ export const Footer = React.forwardRef(function CardFooter(
 
 export const FooterAction = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
   function CardFooterAction({ children, className, ...props }, forwardedRef) {
+    const { elements } = useAppearance().parsedAppearance;
     return (
       <div
         ref={forwardedRef}
-        data-card-footer-action=''
         {...props}
-        className={cx('border-gray-a3 border-b px-6 py-4 last-of-type:border-b-transparent', className)}
+        {...mergeDescriptors(elements.cardFooterAction)}
       >
         {children}
       </div>
@@ -338,12 +467,12 @@ export const FooterAction = React.forwardRef<HTMLDivElement, React.HTMLAttribute
 
 export const FooterActionText = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
   function CardFooterActionText({ children, className, ...props }, forwardedRef) {
+    const { elements } = useAppearance().parsedAppearance;
     return (
       <p
         ref={forwardedRef}
-        data-card-footer-action-text=''
         {...props}
-        className={cx('text-gray-a11 text-center text-base', className)}
+        {...mergeDescriptors(elements.cardFooterActionText)}
       >
         {children}
       </p>
@@ -351,20 +480,16 @@ export const FooterActionText = React.forwardRef<HTMLParagraphElement, React.HTM
   },
 );
 
-const footerActionButton = cva({
-  base: 'text-accent-a10 text-base font-medium hover:underline rounded-sm outline-none focus-visible:ring -mx-0.5 px-0.5',
-});
-
 export const FooterActionButton = React.forwardRef<HTMLButtonElement, React.ButtonHTMLAttributes<HTMLButtonElement>>(
   function CardFooterActionButton({ children, className, type = 'button', ...props }, forwardedRef) {
+    const { elements } = useAppearance().parsedAppearance;
     return (
       <button
         ref={forwardedRef}
-        data-card-footer-action-button=''
         // eslint-disable-next-line react/button-has-type
         type={type}
-        className={footerActionButton({ className })}
         {...props}
+        {...mergeDescriptors(elements.cardFooterActionButton)}
       >
         {children}
       </button>
@@ -374,12 +499,12 @@ export const FooterActionButton = React.forwardRef<HTMLButtonElement, React.Butt
 
 export const FooterActionLink = React.forwardRef<HTMLAnchorElement, React.AnchorHTMLAttributes<HTMLAnchorElement>>(
   function CardFooterActionLink({ children, className, ...props }, forwardedRef) {
+    const { elements } = useAppearance().parsedAppearance;
     return (
       <a
         ref={forwardedRef}
-        data-card-footer-action-link=''
         {...props}
-        className={footerActionButton({ className })}
+        {...mergeDescriptors(elements.cardFooterActionLink)}
       >
         {children}
       </a>
@@ -389,13 +514,14 @@ export const FooterActionLink = React.forwardRef<HTMLAnchorElement, React.Anchor
 
 const FooterPageLink = React.forwardRef<HTMLAnchorElement, React.AnchorHTMLAttributes<HTMLAnchorElement>>(
   function CardFooterPageLink({ children, className, ...props }, forwardedRef) {
+    const { elements } = useAppearance().parsedAppearance;
     return (
       <a
         ref={forwardedRef}
         {...props}
         target='_blank'
         rel='noopener'
-        className={cx('text-gray-a11 text-sm font-medium hover:underline', className)}
+        {...mergeDescriptors(elements.cardFooterActionPageLink)}
       >
         {children}
       </a>
@@ -404,9 +530,25 @@ const FooterPageLink = React.forwardRef<HTMLAnchorElement, React.AnchorHTMLAttri
 );
 
 export const layoutStyle = {
-  ...logoLayoutStyle,
+  ...cardRootLayoutStyle,
+  ...cardHeaderLayoutStyle,
+  ...cardContentLayoutStyle,
+  ...cardTitleLayoutStyle,
+  ...cardDescriptionLayoutStyle,
+  ...cardBodyLayoutStyle,
+  ...cardActionsLayoutStyle,
+  ...cardFooterLayoutStyle,
+  ...cardLogoLayoutStyle,
 } satisfies ParsedElementsFragment;
 
 export const visualStyle = {
-  ...logoVisualStyle,
+  ...cardRootVisualStyle,
+  ...cardHeaderVisualStyle,
+  ...cardContentVisualStyle,
+  ...cardTitleVisualStyle,
+  ...cardDescriptionVisualStyle,
+  ...cardBodyVisualStyle,
+  ...cardActionsVisualStyle,
+  ...cardFooterVisualStyle,
+  ...cardLogoVisualStyle,
 } satisfies ParsedElementsFragment;