Add new 'card' page to example site + new tests for cards (#305)

* Cards: Replace with data-grid

* Cards: Add new page to example site

* Cards: Add tests

* Cards: Small tweaks

* Cards: Updated card params in example site

* Cards: Fix bugs with the card due to merge

Author: lamATnginx

assets/css/v2/style.css

@@ -1482,13 +1482,21 @@ h6:has(a):hover {
 
     &.featured-section {
       /* Hide all the cards past 3 if it is a featured card section */
-      .card-section-content > *:nth-child(n + 4 of div.card) {
+      .card-section-content > *:nth-child(n + 4 of a.card) {
         display: none;
       }
     }
   }
 
   .card {
+    color: oklch(var(--color-foreground));
+    text-decoration: none;
+    order: 2;
+
+    &.featured-card {
+      order: 1;
+    }
+
     .card-container {
       display: flex;
       flex-direction: column;
@@ -1500,6 +1508,7 @@ h6:has(a):hover {
       flex-direction: row;
       gap: 1rem;
       align-items: center;
+      color: oklch(var(--color-brand));
 
       .card-brand-icon {
         height: 20px;

exampleSite/content/test-product/cards/_index.md

@@ -0,0 +1,5 @@
+---
+description: Card usage
+title: Cards
+weight: 300
+---

exampleSite/content/test-product/cards/permitted.md

@@ -0,0 +1,120 @@
+---
+description: Card usage
+title: Usage
+weight: 100
+---
+## General usage
+The structure of a card looks like the following:
+```plaintext
+<card-layout >
+    <card-section>
+        <card title="SOME_TITLE">SOME CONTENT icon="SOME_LUCIDE_ICON"><\card>
+        ...
+        <card>SOME CONTENT<\card>
+    </card-section>
+</card-layout >
+```
+
+and will render as the following:
+<div data-testid="cards-test__basic">
+  {{<card-layout >}}
+    {{<card-section>}}
+      {{<card title="SOME_TITLE">}}
+        SOME CONTENT
+      {{</card >}}
+    {{</card-section>}}
+  {{</card-layout >}}
+</div>
+
+### Params 
+To support customization, there are also some params you can add to the shortcode `<card>` such as `title`, `titleUrl`, `icon`, `brandIcon`, `isFeaturedCard`, `isFullSize`.
+
+* `title` (required) - Title of the card. 
+<br>
+* `titleUrl` (optional) - URL for the card.
+<br>
+* `icon` (optional) - Custom icon using <a href="https://lucide.dev/icons/">lucide</a> icons.
+<br>
+* `brandIcon` (optional) - Custom icon using image from  `nginx-hugo-theme/static/images/icons`.
+  * Usage: `<card brandIcon="NGINX-App-Protect-WAF-product-icon"...>`
+<br>
+* `isFeaturedCard` (optional) - Boolean indicating whether or not the card should be the first one and full size. By default, false.
+  * Usage: `<card isFeaturedCard="true"...>`
+<br>
+* `isFullSize` (optional) - Boolean indicating whether or not the card should be full size. By default, cards are half sized.
+  * Usage: `<card isFullSize="true"...>`
+
+For the `<card-section>`, there are some params you can add such as `title`, `isFeaturedSection`, and `showAsCards`.
+* `title` - Title of the section.
+<br>
+* `isFeaturedSection` (optional) - Boolean indicating whether or not the section is a featured one - will discuss later down the page. By default, false.
+<br> 
+* `showAsCards` (optional) - Boolean indicating whether or not the cards in the section should appear with borders. By default, false.
+
+### Additional Information
+While it may come immediate, you can't use a `<card>` shortcode on its own in your markdown or else the build will fail. This is because if you call a card, there is no way to structure it in a writer-friendly customizable way. 
+
+## Show as cards
+As you can see from the above example in 'General usage', it renders as a plain box that does not resemble a card. To change the appearance and render as a card, use the param `showAsCards` in the shortcode `<card-section>`. The usage as seen below:
+```plaintext
+<card-layout >
+    <card-section showAsCards="true">
+        <card title="SOME_TITLE">SOME CONTENT icon="SOME_LUCIDE_ICON"><\card>
+        ...
+        <card>SOME CONTENT<\card>
+    </card-section>
+</card-layout >
+```
+and will render as the following:
+<div data-testid="cards-test__showAsCards">
+  {{<card-layout >}}
+    {{<card-section showAsCards="true">}}
+      {{<card title="SOME_TITLE">}}
+        SOME CONTENT
+      {{</card >}}
+    {{</card-section>}}
+  {{</card-layout >}}
+</div>
+
+## Featured Section
+Denoted by the param `isFeaturedSection` in the shortcode `<card-layout>`, this block of cards can contain only up to three cards.
+
+<div data-testid="cards-test__featuredSection">
+  {{<card-layout >}}
+    {{<card-section showAsCards="true" isFeaturedSection="true">}}
+      {{<card title="Everything" titleUrl="everything" icon="circle-dot-dashed">}}
+        All shortcodes in one page.
+      {{</card >}}
+      {{<card title="Call Out usages" titleUrl="call-out/all-callouts/" icon="message-square">}}
+        Examples for call-out shortcode
+      {{</card >}}
+      {{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
+        Examples for codeblock shortcode
+      {{</card >}}
+      {{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
+        Examples for codeblock shortcode
+      {{</card >}}
+    {{</card-section>}}
+  {{</card-layout >}}
+</div>
+
+## Featured Card
+Denoted by the param `isFeaturedCard` in the shortcode `<card>`, this will push the card up to very top of the section and make it full length.
+<div data-testid="cards-test__featuredCard">
+  {{<card-layout >}}
+    {{<card-section showAsCards="true">}}
+      {{<card title="Everything" titleUrl="everything" icon="circle-dot-dashed">}}
+        All shortcodes in one page.
+      {{</card >}}
+      {{<card title="Call Out usages" titleUrl="call-out/all-callouts/" icon="message-square">}}
+        Examples for call-out shortcode
+      {{</card >}}
+      {{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code" isFeaturedCard="true">}}
+        Examples for codeblock shortcode
+      {{</card >}}
+      {{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
+        Examples for codeblock shortcode
+      {{</card >}}
+    {{</card-section>}}
+  {{</card-layout >}}
+</div>

layouts/shortcodes/card-layout.html

@@ -1,2 +1,2 @@
 <!-- Render the main content first with modifications, then render the custom content -->
-<div class="card-layout">{{- .Inner | markdownify -}}</div>
+<div class="card-layout" data-testid="card-layout">{{- .Inner | markdownify -}}</div>

layouts/shortcodes/card-section.html

@@ -1,6 +1,7 @@
 {{ $title := .Get "title" }}
 {{ $isFeaturedSectionParam := .Get "isFeaturedSection" | default "false" }}
 {{ $showAsCardsParam := .Get "showAsCards" | default "false"}}
+
 {{- /* Validate the parameter strictly */ -}}
 {{- if not (in (slice "true" "false") $showAsCardsParam) -}}
   {{- warnf "The '<card-section>' Shortcode parameter 'showAsCards' must be 'true' or 'false', but got: '%s'. This will now default to 'false'" $showAsCardsParam -}}
@@ -15,14 +16,18 @@
 {{- end -}}
 {{- $isFeaturedSection := cond (eq $isFeaturedSectionParam "true") "true" "false" -}}
 {{- $class := "card-grid" -}}
+
+{{- /* Get number of cards */ -}}
+{{ $cardCount := len (findRE "<div\\s+class=\"card\"[\\s\\S]*?>" .Inner) }}
+
 {{- /* Validate that the parent is card-layout */ -}}
 {{ if eq .Parent.Name "card-layout"}}
-  <div class="card-section{{if eq $isFeaturedSection "true"}}featured-section{{ end }}">
+  <div class="card-section {{if eq $isFeaturedSection "true"}}featured-section{{ end }}" data-testid="{{if eq $isFeaturedSection "true"}}card-section__featured-section{{else}}card-section{{ end }}">
     {{- if $title -}}
       <strong class="card-section-title">{{- $title -}}</strong>
-      <div class="card-section-content{{ if eq $showAsCards "true" }} {{ $class }}{{ end }}">{{ .Inner }}</div>    
+      <div class="card-section-content{{ if eq $showAsCards "true" }} {{ $class }}{{ end }}" data-testid="{{ if eq $showAsCards "true" }}card-section-content__card-grid{{else}}card-section-content{{ end }}">{{ .Inner }}</div>    
     {{ else }}
-      <div class="card-section-content{{ if eq $showAsCards "true" }} {{ $class }}{{ end }}">{{ .Inner }}</div>    
+      <div class="card-section-content{{ if eq $showAsCards "true" }} {{ $class }}{{ end }}" data-testid="{{ if eq $showAsCards "true" }}card-section-content__card-grid{{else}}card-section-content{{ end }}">{{ .Inner }}</div>    
     {{ end }}
   </div>
 {{ else }}

layouts/shortcodes/card.html

@@ -2,13 +2,13 @@
 {{- $titleUrl := .Get "titleUrl" | default "." -}} 
 {{- $icon := .Get "icon" | default "book-open" -}}
 {{- $brandIcon := .Get "brandIcon" -}}
-{{- $isFeaturedParam := .Get "isFeatured" | default "false" }}
+{{- $isFeaturedParam := .Get "isFeaturedCard" | default "false" }}
 {{- $isFullSizeParam := .Get "isFullSize" | default "false" -}}
 {{- $isLandingParam := .Get "isLanding" | default "false" }}
 
 {{- /* Validate the parameter strictly */ -}}
 {{- if not (in (slice "true" "false") $isFeaturedParam) -}}
-  {{- warnf "The '<card>' Shortcode parameter 'isFeatured' must be 'true' or 'false', but got: '%s'. This will now default to 'false'" $isFeaturedParam -}}
+  {{- warnf "The '<card>' Shortcode parameter 'isFeaturedCard' must be 'true' or 'false', but got: '%s'. This will now default to 'false'" $isFeaturedParam -}}
 {{- end -}}
 {{- $isFeatured := cond (eq $isFeaturedParam "true") "true" "false" -}}
 
@@ -34,7 +34,7 @@
 
 {{- /* Validate that the parent is card-section and under 3 cards */ -}}
 {{- if (eq .Parent.Name "card-section") -}}
-<a href="{{- $titleUrl -}}" alt="{{- $title -}}" class="card{{ if eq $isFeatured "true" }} featured-card{{ end }}" data-grid="{{ $dataGrid }}">
+<a href="{{- $titleUrl -}}" alt="{{- $title -}}" class="card{{ if eq $isFeatured "true" }} featured-card{{ end }}" data-grid="{{ $dataGrid }}" data-testid="{{ if eq $isFeatured "true" }}card__featured-card{{else}}card{{ end }}">
   <div class="card-container">
     {{- if $title -}}
       <div class="card-header">

tests/src/cards.spec.js

@@ -0,0 +1,71 @@
+import { expect, test } from '@playwright/test';
+
+test.describe('Testing for cards shortcode', () => {
+  test.beforeEach(async ({ page }) => {
+    const cardsUrl = 'test-product/cards/permitted';
+    await page.goto(`/${cardsUrl}`);
+  });
+
+  test('should test basic section', async ({ page }) => {
+    const section = await page.locator('data-testid=cards-test__basic');
+    const basicCode = await section.locator('data-testid=card-section-content');
+    const showAsCardCode = await section.locator(
+      'data-testid=card-section-content__card-grid'
+    );
+
+    expect(await basicCode.count()).toBeTruthy();
+    expect(await showAsCardCode.count()).toBe(0);
+  });
+
+  test('should test showAsCard section', async ({ page }) => {
+    const section = await page.locator('data-testid=cards-test__showAsCards');
+    const showAsCardCode = await section.locator(
+      'data-testid=card-section-content__card-grid'
+    );
+
+    expect(await showAsCardCode.count()).toBeTruthy();
+  });
+
+  test('should test featured section', async ({ page }) => {
+    const section = await page.locator(
+      'data-testid=cards-test__featuredSection'
+    );
+    const featuredSection = await section.locator(
+      'data-testid=card-section__featured-section'
+    );
+    const cards = await (
+      await featuredSection.locator('data-testid=card')
+    ).all();
+
+    // Test featured section exists AND there are less than or equal to 3 cards.
+    expect(await featuredSection.count()).toBeTruthy();
+    const visibleCards = [];
+    for (const card of cards) {
+      if (await card.isVisible()) {
+        visibleCards.push(card);
+      }
+    }
+    expect(visibleCards.length).toBeLessThanOrEqual(3);
+  });
+
+  test('should test featured card', async ({ page }) => {
+    const section = await page.locator('data-testid=cards-test__featuredCard');
+    const featuredCard = await section.locator(
+      'data-testid=card__featured-card'
+    );
+    const cards = await (await section.locator('data-testid=card')).all();
+    const featuredCardOrder = await featuredCard.evaluate((el) => {
+      return window.getComputedStyle(el).getPropertyValue('order');
+    });
+
+    // Test featured card exist AND is the first one in the order
+    expect(await featuredCard.count()).toBeTruthy();
+    expect(featuredCardOrder).toBe('1');
+    for (const card of cards) {
+      const order = await card.evaluate((el) => {
+        return window.getComputedStyle(el).getPropertyValue('order');
+      });
+      expect(order).toBe('2');
+    }
+  });
+});