feat(ui): create DescriptionList with DescriptionTerm and DescriptionDefinition

.changeset/lucky-weeks-dance.md

@@ -0,0 +1,5 @@
+---
+"@cloudoperators/juno-ui-components": minor
+---
+
+Add `DescriptionList`, `DescriptionTerm` and `DescriptionDefinition` components and export them as `DL`, `DT`, `DD` shorthand.

packages/ui-components/src/components/DescriptionDefinition/DescriptionDefinition.component.tsx

@@ -0,0 +1,38 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React, { ReactNode } from "react"
+
+const baseStyles = `
+  jn:grid
+  jn:items-start
+  jn:border-b 
+  jn:border-theme-default
+  jn:bg-dd-background
+  jn:text-dd-text
+  jn:p-2
+  jn:col-span-3
+`
+
+export interface DescriptionDefinitionProps {
+  /**
+   * Content to be displayed as the description, accommodating text or more complex nodes to explain or define the associated term.
+   */
+  children: ReactNode
+  /**
+   * Additional class names for applying custom styles or overriding default styles on the <dd> element.
+   */
+  className?: string
+}
+
+/**
+ * Represents the definition or description in a description list, rendering as an HTML <dd> element.
+ * Pairs with DescriptionTerm to complete the term-description association, offering flexible content styling.
+ */
+export const DescriptionDefinition: React.FC<DescriptionDefinitionProps> = ({ children, className = "" }) => (
+  <dd className={`dd ${baseStyles} ${className}`}>{children}</dd>
+)
+
+export const DD = DescriptionDefinition

packages/ui-components/src/components/DescriptionDefinition/DescriptionDefinition.test.tsx

@@ -0,0 +1,39 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import { describe, it, expect } from "vitest"
+import { DescriptionDefinition } from "../DescriptionDefinition"
+
+describe("DescriptionDefinition", () => {
+  it("renders the children correctly", () => {
+    render(<DescriptionDefinition>Test Description</DescriptionDefinition>)
+    expect(screen.getByText("Test Description")).toBeInTheDocument()
+  })
+
+  it("applies custom className", () => {
+    const customClass = "custom-class"
+    render(<DescriptionDefinition className={customClass}>Test Description</DescriptionDefinition>)
+    const ddElement = screen.getByText("Test Description")
+    expect(ddElement).toHaveClass(customClass)
+  })
+
+  it("renders within a <dd> element", () => {
+    render(<DescriptionDefinition>Test Description</DescriptionDefinition>)
+    const ddElement = screen.getByText("Test Description")
+    expect(ddElement.tagName).toBe("DD")
+  })
+
+  it("can render complex children", () => {
+    render(
+      <DescriptionDefinition>
+        <span>Complex</span> <strong>Content</strong>
+      </DescriptionDefinition>
+    )
+    expect(screen.getByText("Complex")).toBeInTheDocument()
+    expect(screen.getByText("Content")).toBeInTheDocument()
+  })
+})

packages/ui-components/src/components/DescriptionDefinition/index.ts

@@ -0,0 +1,6 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { DescriptionDefinition, type DescriptionDefinitionProps } from "./DescriptionDefinition.component"

packages/ui-components/src/components/DescriptionList/DescriptionList.component.tsx

@@ -0,0 +1,43 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React, { ReactElement } from "react"
+import { DescriptionTermProps } from "../DescriptionTerm"
+import { DescriptionDefinitionProps } from "../DescriptionDefinition"
+
+export interface DescriptionListProps {
+  /**
+   * Child components must be either DescriptionTerm or DescriptionDefinition to maintain semantic structure.
+   * Supports multiple instances to create a detailed list of terms and definitions.
+   */
+  children:
+    | ReactElement<DescriptionTermProps | DescriptionDefinitionProps>
+    | Array<ReactElement<DescriptionTermProps | DescriptionDefinitionProps>>
+    | ReactElement<"div">
+  /**
+   * Determines the alignment of terms within the list. Align terms to the left or right based on preference for display style.
+   */
+  alignTerms?: "left" | "right"
+  /**
+   * Additional custom class names to apply styles to the <dl> element or to extend styling from the design system.
+   */
+  className?: string
+}
+
+/**
+ * A wrapper component that semantically represents a list of terms and their corresponding descriptions.
+ * This component enforces structure by expecting child elements of DescriptionTerm or DescriptionDefinition,
+ * aligning them according to the specified terms alignment.
+ */
+export const DescriptionList: React.FC<DescriptionListProps> = ({ children, alignTerms = "right", className = "" }) => (
+  <dl
+    className={`dl jn:grid jn:grid-cols-4 jn:group ${alignTerms === "right" ? "align-right" : "align-left"} ${className}`}
+    data-testid="description-list"
+  >
+    {children}
+  </dl>
+)
+
+export const DL = DescriptionList

packages/ui-components/src/components/DescriptionList/DescriptionList.stories.tsx

@@ -0,0 +1,87 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react-vite"
+import { DL } from "./DescriptionList.component"
+import { DT } from "../DescriptionTerm/DescriptionTerm.component"
+import { DD } from "../DescriptionDefinition/DescriptionDefinition.component"
+
+const meta: Meta<typeof DL> = {
+  title: "Components/DescriptionList",
+  component: DL,
+  parameters: {
+    docs: {
+      description: {
+        component: `
+A wrapper component that semantically represents a list of terms and their corresponding descriptions. 
+
+This component enforces structure by expecting child elements of \`DescriptionTerm\` or \`DescriptionDefinition\`.
+
+### Grid Layout
+- By default, the component uses a 4-column grid layout where each \`DescriptionTerm\` spans 1 column and each \`DescriptionDefinition\` spans 3 columns.
+- Customize the grid template by passing other Tailwind CSS grid classes via the \`className\` prop to override the defaults.
+
+#### Example
+\`\`\`jsx
+<DL className="jn:grid-cols-2">
+  <DT className="jn:col-span-1">Shipping Method</DT>
+  <DD className="jn:col-span-2">Standard shipping: 5-7 business days.</DD>
+</DL>
+\`\`\`
+        `,
+      },
+    },
+  },
+  argTypes: {
+    children: {
+      control: false,
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof DL>
+
+export const Default: Story = {
+  render: (args) => (
+    <DL {...args}>
+      <DT>Shipping</DT>
+      <DD>Standard shipping: 5-7 business days.</DD>
+      <DT>Payment Options</DT>
+      <DD>
+        Credit/Debit cards, PayPal, and bank transfer. Lots and lots and lots of options. Oh so many, many options.
+      </DD>
+      <DT>Delivery Time</DT>
+      <DD>1 day, 2 days, 3 days.</DD>
+    </DL>
+  ),
+}
+
+export const LeftAligned: Story = {
+  render: (args) => (
+    <DL alignTerms="left" {...args}>
+      <DT>Shipping Method</DT>
+      <DD>Standard shipping: 5-7 business days.</DD>
+      <DT>Payment Options</DT>
+      <DD>
+        Credit/Debit cards, PayPal, and bank transfer. Lots and lots of options available for a seamless transaction
+        experience.
+      </DD>
+      <DT>Delivery Time</DT>
+      <DD>Estimated delivery between 1 to 3 business days after shipping.</DD>
+      <DT>Return Policy</DT>
+      <DD>
+        Returns are accepted within 30 days of purchase. Items must be returned in their original packaging and
+        condition.
+      </DD>
+      <DT>Customer Support</DT>
+      <DD>
+        Available via phone, email, and live chat from 9 AM to 6 PM, Monday to Friday. Our support team is ready to
+        assist with any inquiries.
+      </DD>
+    </DL>
+  ),
+}

packages/ui-components/src/components/DescriptionList/DescriptionList.test.tsx

@@ -0,0 +1,70 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import { describe, it, expect } from "vitest"
+import { DescriptionList } from "./DescriptionList.component"
+import { DescriptionTerm } from "../DescriptionTerm"
+import { DescriptionDefinition } from "../DescriptionDefinition"
+
+describe("DescriptionList", () => {
+  it("renders child DescriptionTerm and DescriptionDefinition components correctly", () => {
+    render(
+      <DescriptionList>
+        <DescriptionTerm>Term 1</DescriptionTerm>
+        <DescriptionDefinition>Definition 1</DescriptionDefinition>
+      </DescriptionList>
+    )
+    expect(screen.getByText("Term 1")).toBeInTheDocument()
+    expect(screen.getByText("Definition 1")).toBeInTheDocument()
+  })
+
+  it("applies custom className to the <dl> element", () => {
+    const customClass = "custom-class"
+    render(
+      <DescriptionList className={customClass}>
+        <DescriptionTerm>Term 2</DescriptionTerm>
+        <DescriptionDefinition>Definition 2</DescriptionDefinition>
+      </DescriptionList>
+    )
+
+    const dlElement = screen.getByTestId("description-list")
+    expect(dlElement).toHaveClass(customClass)
+  })
+
+  it("aligns terms to the right by default", () => {
+    render(
+      <DescriptionList>
+        <DescriptionTerm>Term 3</DescriptionTerm>
+        <DescriptionDefinition>Definition 3</DescriptionDefinition>
+      </DescriptionList>
+    )
+  })
+
+  it("aligns terms to the left when specified", () => {
+    render(
+      <DescriptionList alignTerms="left">
+        <DescriptionTerm>Left Term</DescriptionTerm>
+        <DescriptionDefinition>Definition for Left Term</DescriptionDefinition>
+      </DescriptionList>
+    )
+  })
+
+  it("renders multiple terms and definitions in a single list", () => {
+    render(
+      <DescriptionList>
+        <DescriptionTerm>Term 4</DescriptionTerm>
+        <DescriptionDefinition>Definition 4</DescriptionDefinition>
+        <DescriptionTerm>Term 5</DescriptionTerm>
+        <DescriptionDefinition>Definition 5</DescriptionDefinition>
+      </DescriptionList>
+    )
+    expect(screen.getByText("Term 4")).toBeInTheDocument()
+    expect(screen.getByText("Definition 4")).toBeInTheDocument()
+    expect(screen.getByText("Term 5")).toBeInTheDocument()
+    expect(screen.getByText("Definition 5")).toBeInTheDocument()
+  })
+})

packages/ui-components/src/components/DescriptionList/index.ts

@@ -0,0 +1,6 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { DescriptionList, type DescriptionListProps } from "./DescriptionList.component"

packages/ui-components/src/components/DescriptionTerm/DescriptionTerm.component.tsx

@@ -0,0 +1,43 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React, { ReactNode } from "react"
+
+const baseStyles = `
+jn:grid 
+jn:items-start 
+jn:border-b 
+jn:border-theme-default
+jn:bg-dt-background
+jn:text-dt-text
+jn:font-bold
+jn:gap-y-[0.25rem]
+jn:whitespace-nowrap 
+jn:p-2
+jn:col-span-1
+jn:group-[.align-right]:text-right 
+jn:group-[.align-left]:text-left
+`
+
+export interface DescriptionTermProps {
+  /**
+   * Content to be displayed as the term, which could be simple text or any ReactNode, providing semantic meaning to the associated description.
+   */
+  children: ReactNode
+  /**
+   * Custom class names to apply additional styling to the <dt> element, useful for overrides or custom styles.
+   */
+  className?: string
+}
+
+/**
+ * Represents a term in a description list, rendering an HTML <dt> element.
+ * Used to denote terms, headers, or keys in a semantic way, allowing for flexible styling.
+ */
+export const DescriptionTerm: React.FC<DescriptionTermProps> = ({ children, className = "" }) => (
+  <dt className={`dt ${baseStyles} ${className}`}>{children}</dt>
+)
+
+export const DT = DescriptionTerm

packages/ui-components/src/components/DescriptionTerm/DescriptionTerm.test.tsx

@@ -0,0 +1,39 @@
+/*
+ * SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import { describe, it, expect } from "vitest"
+import { DescriptionTerm } from "./DescriptionTerm.component"
+
+describe("DescriptionTerm", () => {
+  it("renders the children properly", () => {
+    render(<DescriptionTerm>Test Term</DescriptionTerm>)
+    expect(screen.getByText("Test Term")).toBeInTheDocument()
+  })
+
+  it("applies custom className to the <dt> element", () => {
+    const customClass = "custom-class"
+    render(<DescriptionTerm className={customClass}>Styled Term</DescriptionTerm>)
+    const dtElement = screen.getByText("Styled Term")
+    expect(dtElement).toHaveClass(customClass)
+  })
+
+  it("renders within a <dt> element", () => {
+    render(<DescriptionTerm>Term Element</DescriptionTerm>)
+    const dtElement = screen.getByText("Term Element")
+    expect(dtElement.tagName.toLowerCase()).toBe("dt")
+  })
+
+  it("can render complex children", () => {
+    render(
+      <DescriptionTerm>
+        <span>Complex Term</span> <strong>Content</strong>
+      </DescriptionTerm>
+    )
+    expect(screen.getByText("Complex Term")).toBeInTheDocument()
+    expect(screen.getByText("Content")).toBeInTheDocument()
+  })
+})

packages/ui-components/src/components/DescriptionTerm/index.ts

@@ -0,0 +1,6 @@
+/*
+ * SPDX-FileCopyrightText: 2024 SAP SE or an SAP affiliate company and Juno contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { DescriptionTerm, type DescriptionTermProps } from "./DescriptionTerm.component"