Merge branch 'main' into joseph-lozano/SubdomainNavbar-overflow-fix

.changeset/export-windowsize-hook.md

@@ -0,0 +1,16 @@
+---
+'@primer/react-brand': patch
+---
+
+Added hook for `useWindowSize` to the library exports.
+
+Usage example:
+
+```js
+import {useWindowSize} from '@primer/react-brand'
+```
+
+```jsx
+const {width, height, isXSmall, isSmall, isMedium, isLarge, isXLarge, isXXLarge, currentBreakpointSize} =
+  useWindowSize()
+```

.changeset/fix-hero-refs.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+Enabled `forwardRef` on `Hero.Description`, `Hero.Label` and `Hero.Image`.

.changeset/friendly-suns-tease.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+Adds `Blockquote`, `Code`, `Figure` and `Figcaption` to the `Prose` component.

apps/docs/content/components/Card/index.mdx

@@ -7,7 +7,7 @@ import CustomVideoPlayer from '../../../src/components/custom-video-player'
 import ComponentLayout from '../../../src/layouts/component-layout'
 export default ComponentLayout
 
-![An image showing a card with a Copilot Octicon.](https://github.com/primer/brand/assets/912236/494d440c-98d2-4634-beec-8a80caca8926)
+![An image showing a card with a Copilot Octicon.](https://github.com/primer/brand/assets/6951037/5bb4e3dd-8f53-44c5-a5ed-987c732eaf8f)
 
 ## Usage
 
@@ -17,11 +17,11 @@ Cards should always be used in groups of two or more related concepts.
 
 <DoDontContainer>
   <Do>
-    <img src="https://github.com/primer/brand/assets/912236/d0da491e-8895-4ba2-9840-17eef7f2dd75" />
+    <img src="https://github.com/primer/brand/assets/6951037/139deb0e-0143-4051-a8c8-49b854b58727" />
     <Caption>Use cards in groups to display related information.</Caption>
   </Do>
   <Dont>
-    <img src="https://github.com/primer/brand/assets/912236/9f17706e-dfb1-4ef9-a87d-df6c8a1d3825" />
+    <img src="https://github.com/primer/brand/assets/6951037/1f009b98-01b8-4cb3-af30-83ccac31c8c9" />
     <Caption>
       Don't use isolated cards. Consider using a CTABanner instead.
     </Caption>
@@ -36,14 +36,14 @@ For a better visual experience, we recommend using similar length size for the h
 
 <DoDontContainer>
   <Do>
-    <img src="https://github.com/primer/brand/assets/912236/fced572e-c296-4a97-aaa8-3d4b357f2f6e" />
+    <img src="https://github.com/primer/brand/assets/6951037/28b8dbfa-9ed5-40ba-b1a3-d501ac3be4b8" />
     <Caption>
       Use the same type of visual asset for all cards and a similar length size
       for the content.
     </Caption>
   </Do>
   <Dont>
-    <img src="https://github.com/primer/brand/assets/912236/c612ccf8-7c98-4213-92b9-2fdf6f0f1398" />
+    <img src="https://github.com/primer/brand/assets/6951037/6d494165-312e-4e84-94df-199d1d82fd50" />
     <Caption>
       Don't use different length sizes for the title or the description.
     </Caption>
@@ -54,13 +54,13 @@ When using an image as the visual asset, we recommend using the same aspect rati
 
 <DoDontContainer>
   <Do>
-    <img src="https://github.com/primer/brand/assets/912236/0ec93c16-7091-4ebb-a1a0-b0626de7833f" />
+    <img src="https://github.com/primer/brand/assets/6951037/1a6decfc-a840-440b-8ec7-bf25b7716711" />
     <Caption>
       Use the same image ratio and a similar length sizes for the content.
     </Caption>
   </Do>
   <Dont>
-    <img src="https://github.com/primer/brand/assets/912236/0b8ffb2d-0753-4bdd-9165-0f30ec28a8c8" />
+    <img src="https://github.com/primer/brand/assets/6951037/cffafadf-2e9d-47f0-a6db-6f89fb48fabe" />
     <Caption>
       Don't use different image ratios and a different length size for the
       content.
@@ -73,7 +73,7 @@ Cards typically appear in groups of three or four in desktop viewports. For smal
 <div>
   <CustomVideoPlayer
     width="100%"
-    src="https://github.com/primer/brand/assets/912236/d8e76477-1b27-4be1-9bf5-d22186af8376"
+    src="https://github.com/primer/brand/assets/6951037/a9ceec00-59c9-4471-a274-f516790f43c9"
   />
   <Caption>
     Stack cards vertically so that the content has enough line length.
@@ -82,21 +82,21 @@ Cards typically appear in groups of three or four in desktop viewports. For smal
 
 ## Anatomy
 
-![An image showing the card anatomy with an icon as a visual asset, a heading, a description and a CTA text in a vertical order.](https://github.com/primer/brand/assets/912236/633b83d8-4ea8-49bd-9d6c-45a1989060d9)
+![An image showing the card anatomy with an icon as a visual asset, a heading, a description and a CTA text in a vertical order.](https://github.com/primer/brand/assets/6951037/2ae395d0-227d-4794-8e0b-f709a431e636)
 
 ### Visual asset
 
 The visual asset is optional and can be an image or an icon. It can be used to provide a visual cue to the user about the content of the card. To avoid visual noise, we recommend using only one icon or image, but not both in the same card.
 
-![An image showing two cards, one with an Icon and another with an Image as the visual assets options.](https://github.com/primer/brand/assets/912236/be65583b-f6f0-438a-8d2c-6b7a0a9fd3de)
+![An image showing two cards, one with an Icon and another with an Image as the visual assets options.](https://github.com/primer/brand/assets/6951037/21623e82-2ea5-499a-a78f-82b09915af16)
 
 <DoDontContainer>
   <Do>
-    <img src="https://github.com/primer/brand/assets/912236/863de864-5216-44bf-8b35-430821da8853" />
+    <img src="https://github.com/primer/brand/assets/6951037/e5494fd3-76b1-45fd-8aa7-4acfe834b159" />
     <Caption>Use only one visual asset per card.</Caption>
   </Do>
   <Dont>
-    <img src="https://github.com/primer/brand/assets/912236/9acdde97-42e3-4a7a-8102-b9be5e3c05fc" />
+    <img src="https://github.com/primer/brand/assets/6951037/bc29b10b-ee0b-421d-8bc4-0a95fad3791b" />
     <Caption>Don't use both icon and image as the visual asset.</Caption>
   </Dont>
 </DoDontContainer>
@@ -105,7 +105,7 @@ The visual asset is optional and can be an image or an icon. It can be used to p
 
 The label can be used to indicate the type of content or its status. For example, use it to indicate that the content is `new` or that it is a `beta` feature. The label is optional and can be used along with a visual asset.
 
-![An image showing two cards, one with a Label and another one with Label and Icon.](https://github.com/primer/brand/assets/912236/2d84fe89-2735-451e-9d1f-9a2f0297e7b5)
+![An image showing two cards, one with a Label and another one with Label and Icon.](https://github.com/primer/brand/assets/6951037/3e16bb51-9e19-4a98-a9c2-e289d4bf540c)
 
 ### Heading
 
@@ -119,6 +119,12 @@ The description is an optional short text that extends the information provided
 
 The call to action label indicates the action or resource the card links to. It defaults to "Learn more".
 
+## Options
+
+### Border
+
+Card offers a variation with a border. Border is disabled by default. 
+
 ## Related components
 
 - [Pillar](/components/Pillar): To display related content with less visual emphasis.

apps/docs/content/components/Prose.mdx

@@ -16,7 +16,7 @@ import {Prose} from '@primer/react-brand'
 
 The `Prose` component renders native HTML elements with Primer Brand styling. `Prose` doesn't sanitize the input data. We recommend sanitizing the data before passing it into `Prose`.
 
-`Prose` currently supports styling the following HTML elements: `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, `<h6>`, `<p>`, `<strong>`, `<em>`, `<a>`, `<ul>`, `<ol>`, `<li>`, `<img>`, and `<div>`.
+`Prose` currently supports styling the following HTML elements: `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, `<h6>`, `<p>`, `<strong>`, `<em>`, `<a>`, `<ul>`, `<ol>`, `<li>`, `<img>`, `<blockquote>`, `<code>`, `<figure>`, `<figcaption>` and `<div>`.
 
 </Note>
 
@@ -27,7 +27,12 @@ The `Prose` component renders native HTML elements with Primer Brand styling. `P
   html={`
     <h2>Heading level 2</h2>
     <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut tempor lectus ipsum, consectetur convallis diam pretium quis. Proin ut felis ut eros tristique tincidunt.</p>
-    <blockquote>Nulla ac odio eu magna hendrerit porta. Donec nec eros quis tortor tincidunt vulputate. Aenean id pharetra diam, sit amet auctor leo. Aliquam erat volutpat.</blockquote>
+    <figure>
+      <blockquote>
+        <p>Nulla ac odio eu magna hendrerit porta. Donec nec eros quis tortor tincidunt vulputate. Aenean id pharetra diam, sit amet auctor leo. Aliquam erat volutpat.</p>
+        <figcaption>Lisa Vanderschuit, Engineering Program Manager, Shopify</figcaption>
+      </blockquote>
+    </figure>
     <p>Integer pellentesque pretium nulla viverra molestie. Praesent quis pretium sapien. Sed convallis eget lectus et pulvinar:</p>
     <ul>
       <li>
@@ -57,6 +62,7 @@ The `Prose` component renders native HTML elements with Primer Brand styling. `P
       </li>
       <li>Quisque eu tortor suscipit, congue quam in, bibendum tellus.</li>
     </ol>
+    <p><code>for-each-ref</code> is extremely useful for listing references, finding which references point at a given object (with <code>--points-at</code>), which references have been merged into a given branch (with <code>--merged</code>), or which references contain a given commit (with <code>--contains</code>).</p>
     <h6>Heading level 6</h6>
     <p>Pellentesque non ornare ligula. Suspendisse nibh purus, pretium id tortor sit amet, tincidunt gravida augue.</p>
     <p>Nunc velit odio, posuere eu felis eget, consectetur fermentum nisi. Aenean tempor odio id ornare ultrices. Quisque blandit condimentum tellus, semper efficitur sapien dapibus nec. </p>

apps/docs/scripts/components-with-animation.js

@@ -6,15 +6,15 @@ export const supportedComponents = [
   'ComparisonTable',
   'FAQ',
   'Heading',
-  'Image',
   'Label',
+  'Image',
   'Pillar',
   'SectionIntro',
   'Stack',
   'Testimonial',
   'Text',
   'Timeline',
   'Animate',
-  'River',
   'RiverBreakout',
+  'River',
 ]

packages/design-tokens/src/tokens/functional/components/prose/base.json

@@ -6,7 +6,12 @@
       },
       "img": {
         "spacing": {
-          "value": "var(--brand-size-48)"
+          "value": "var(--base-size-48)"
+        }
+      },
+      "blockquote": {
+        "spacing": {
+          "value": "var(--base-size-24)"
         }
       }
     }

packages/react/src/Hero/Hero.tsx

@@ -104,32 +104,44 @@ type HeroDescriptionProps = {
   weight?: TextWeightVariants | ResponsiveWeightMap
 } & BaseProps<HTMLParagraphElement>
 
-function HeroDescription({size = '200', weight, children}: PropsWithChildren<HeroDescriptionProps>) {
-  return (
-    <Text className={styles['Hero-description']} as="p" size={size} weight={weight}>
-      {children}
-    </Text>
-  )
-}
+const HeroDescription = forwardRef<HTMLParagraphElement, PropsWithChildren<HeroDescriptionProps>>(
+  ({size = '200', weight, children}: PropsWithChildren<HeroDescriptionProps>, ref) => {
+    return (
+      <Text ref={ref} className={styles['Hero-description']} as="p" size={size} weight={weight}>
+        {children}
+      </Text>
+    )
+  },
+)
 
 type HeroImageProps = {
   position?: 'inline-end' | 'block-end'
 } & ImageProps &
   BaseProps<HTMLImageElement>
 
-function HeroImage({position = 'block-end', className, ...rest}: PropsWithChildren<HeroImageProps>) {
-  return <Image className={clsx(styles['Hero-image'], styles[`Hero-image--pos-${position}`], className)} {...rest} />
-}
+const HeroImage = forwardRef<HTMLImageElement, HeroImageProps>(
+  ({position = 'block-end', className, ...rest}: PropsWithChildren<HeroImageProps>, ref) => {
+    return (
+      <Image
+        ref={ref}
+        className={clsx(styles['Hero-image'], styles[`Hero-image--pos-${position}`], className)}
+        {...rest}
+      />
+    )
+  },
+)
 
 type HeroLabelProps = LabelProps & BaseProps<HTMLSpanElement>
 
-function HeroLabel({children, ...rest}: PropsWithChildren<HeroLabelProps>) {
-  return (
-    <Label className={styles['Hero-label']} {...rest}>
-      {children}
-    </Label>
-  )
-}
+const HeroLabel = forwardRef<HTMLSpanElement, HeroLabelProps>(
+  ({children, ...rest}: PropsWithChildren<HeroLabelProps>, ref) => {
+    return (
+      <Label ref={ref} className={styles['Hero-label']} {...rest}>
+        {children}
+      </Label>
+    )
+  },
+)
 
 type RestrictedPolymorphism =
   | (BaseProps<HTMLAnchorElement> & {as?: 'a'})

packages/react/src/Prose/Prose.features.stories.tsx

@@ -18,7 +18,12 @@ export default {
 const ExampleHtmlMarkup = `
 <h2>Heading level 2</h2>
     <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut tempor lectus ipsum, consectetur convallis diam pretium quis. Proin ut felis ut eros tristique tincidunt.</p>
-    <blockquote>Nulla ac odio eu magna hendrerit porta. Donec nec eros quis tortor tincidunt vulputate. Aenean id pharetra diam, sit amet auctor leo. Aliquam erat volutpat.</blockquote>
+    <figure>
+      <blockquote>
+        <p>Nulla ac odio eu magna hendrerit porta. Donec nec eros quis tortor tincidunt vulputate. Aenean id pharetra diam, sit amet auctor leo. Aliquam erat volutpat.</p>
+        <figcaption>Lisa Vanderschuit, Engineering Program Manager, Shopify</figcaption>
+      </blockquote>
+    </figure>
     <p>Integer pellentesque pretium nulla viverra molestie. Praesent quis pretium sapien. Sed convallis eget lectus et pulvinar:</p>
     <ul>
       <li>
@@ -50,6 +55,7 @@ const ExampleHtmlMarkup = `
     </ol>
     <h6>Heading level 6</h6>
     <p>Pellentesque non ornare ligula. Suspendisse nibh purus, pretium id tortor sit amet, tincidunt gravida augue.</p>
+    <p><code>for-each-ref</code> is extremely useful for listing references, finding which references point at a given object (with <code>--points-at</code>), which references have been merged into a given branch (with <code>--merged</code>), or which references contain a given commit (with <code>--contains</code>).</p>        
     <p>Nunc velit odio, posuere eu felis eget, consectetur fermentum nisi. Aenean tempor odio id ornare ultrices. Quisque blandit condimentum tellus, semper efficitur sapien dapibus nec. </p>
 `
 

packages/react/src/Prose/Prose.module.css

@@ -10,10 +10,11 @@
 /* 6. Lists                                                   */
 /* 7. Inline elements                                         */
 /* 8. Images                                                  */
+/* 9. Block elements                                          */
 /* ---------------------------------------------------------- */
 
 /* ---------------------------------------------------------- */
-/* 1, Container                                               */
+/* 1. Container                                               */
 /* ---------------------------------------------------------- */
 
 .Prose {
@@ -190,6 +191,15 @@
   border-color: var(--brand-InlineLink-color-pressed);
 }
 
+.Prose code {
+  font-family: var(--brand-fontStack-monospace);
+  font-size: var(--brand-text-size-100);
+  white-space: break-spaces;
+  padding: var(--base-size-4) var(--base-size-8);
+  border-radius: var(--brand-borderRadius-small);
+  background-color: var(--base-color-scale-indigo-0);
+}
+
 /* ---------------------------------------------------------- */
 /* 8. Images                                                  */
 /* ---------------------------------------------------------- */
@@ -203,3 +213,46 @@
   margin-right: auto;
   margin-block-end: var(--spacing);
 }
+
+/* ---------------------------------------------------------- */
+/* 9. Block elements                                          */
+/* ---------------------------------------------------------- */
+
+.Prose blockquote {
+  --spacing: var(--brand-Prose-blockquote-spacing);
+  position: relative;
+  font-size: var(--brand-text-size-400);
+  line-height: var(--brand-text-lineHeight-400);
+  padding-top: var(--base-size-48);
+  padding-left: var(--base-size-40);
+  padding-bottom: var(--base-size-8);
+  margin-bottom: var(--spacing);
+}
+
+.Prose blockquote::before {
+  content: '“';
+  font-size: var(--base-size-48);
+  line-height: var(--base-size-64);
+  font-weight: var(--base-text-weight-extrabold);
+  position: absolute;
+  top: 0;
+}
+
+.Prose blockquote::after {
+  content: '';
+  display: block;
+  position: absolute;
+  width: var(--brand-borderWidth-thick);
+  height: 100%;
+  top: 0;
+  left: 0;
+  background-color: var(--base-color-scale-indigo-5);
+  background-image: linear-gradient(180deg, var(--base-color-scale-blue-5), var(--base-color-scale-purple-5));
+}
+
+.Prose figure figcaption {
+  font-family: var(--brand-fontStack-monospace);
+  font-size: var(--brand-text-size-100);
+  line-height: var(--brand-text-lineHeight-100);
+  color: var(--brand-color-text-muted);
+}

packages/react/src/Prose/Prose.stories.tsx

@@ -22,15 +22,20 @@ export default {
 const ExampleHtmlMarkup = `
 <h2>Heading level 2</h2>
     <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut tempor lectus ipsum, consectetur convallis diam pretium quis. Proin ut felis ut eros tristique tincidunt.</p>
-    <blockquote>Nulla ac odio eu magna hendrerit porta. Donec nec eros quis tortor tincidunt vulputate. Aenean id pharetra diam, sit amet auctor leo. Aliquam erat volutpat.</blockquote>
+    <figure>
+      <blockquote>
+        <p>Nulla ac odio eu magna hendrerit porta. Donec nec eros quis tortor tincidunt vulputate. Aenean id pharetra diam, sit amet auctor leo. Aliquam erat volutpat.</p>
+        <figcaption>Lisa Vanderschuit, Engineering Program Manager, Shopify</figcaption>
+      </blockquote>
+    </figure>
     <p>Integer pellentesque pretium nulla viverra molestie. Praesent quis pretium sapien. Sed convallis eget lectus et pulvinar:</p>
     <ul>
       <li>
-        Vivamus eu risus nec lectus consequat rutrum at vel lacus.
+        <strong>Vivamus</strong> eu risus nec lectus consequat rutrum at vel lacus.
       </li>
-      <li>Donec at dolor ut metus imperdiet congue vel porta nunc.
+      <li><strong>Donec</strong> at dolor ut metus imperdiet congue vel porta nunc.
       </li>
-      <li>Quisque eu tortor suscipit, congue quam in, bibendum tellus.</li>
+      <li><strong>Quisque</strong> eu tortor suscipit, congue quam in, bibendum tellus.</li>
     </ul>
     <h3>Heading level 3</h3>
     <p>Pellentesque non ornare ligula. Suspendisse nibh purus, pretium id tortor sit amet, tincidunt gravida augue. Ut malesuada, nisl vel dignissim mollis</p>
@@ -52,6 +57,7 @@ const ExampleHtmlMarkup = `
       </li>
       <li>Quisque eu tortor suscipit, congue quam in, bibendum tellus.</li>
     </ol>
+    <p><code>for-each-ref</code> is extremely useful for listing references, finding which references point at a given object (with <code>--points-at</code>), which references have been merged into a given branch (with <code>--merged</code>), or which references contain a given commit (with <code>--contains</code>).</p>    
     <h6>Heading level 6</h6>
     <p>Pellentesque non ornare ligula. Suspendisse nibh purus, pretium id tortor sit amet, tincidunt gravida augue.</p>
     <p>Nunc velit odio, posuere eu felis eget, consectetur fermentum nisi. Aenean tempor odio id ornare ultrices. Quisque blandit condimentum tellus, semper efficitur sapien dapibus nec. </p>