From 17b2cde021e46421c8c85e7b6d344b095454d5d3 Mon Sep 17 00:00:00 2001
From: Joonas Tiala <joonas.tiala@gmail.com>
Date: Fri, 26 Jan 2024 00:18:17 +0200
Subject: [PATCH] docs: improve typography components documentations

---
 .../react/src/components/Blockquote/Blockquote.tsx  |  2 +-
 packages/react/src/components/Heading/Heading.tsx   |  6 ++----
 packages/react/src/components/List/List.tsx         | 13 +++++--------
 packages/react/src/components/List/ListItem.tsx     |  2 +-
 .../react/src/components/Paragraph/Paragraph.tsx    |  2 +-
 5 files changed, 10 insertions(+), 15 deletions(-)

diff --git a/packages/react/src/components/Blockquote/Blockquote.tsx b/packages/react/src/components/Blockquote/Blockquote.tsx
index b26c766..118c176 100644
--- a/packages/react/src/components/Blockquote/Blockquote.tsx
+++ b/packages/react/src/components/Blockquote/Blockquote.tsx
@@ -29,7 +29,7 @@ const authorClassName = cn("blockquote-author");
 const sourceClassName = cn("blockquote-source");
 
 /**
- * Display an extended quotation.
+ * A visual element for displaying blockquotes or cited sections of text.
  */
 export function Blockquote({
   cite,
diff --git a/packages/react/src/components/Heading/Heading.tsx b/packages/react/src/components/Heading/Heading.tsx
index ac3e8b0..115bf83 100644
--- a/packages/react/src/components/Heading/Heading.tsx
+++ b/packages/react/src/components/Heading/Heading.tsx
@@ -18,13 +18,11 @@ export type HeadingProps = {
 const className = cn("heading");
 
 /**
- * Display a section heading.
+ * A heading.
  */
 export function Heading({ level, children, id, testId }: HeadingProps) {
-  const element = "h" + level;
-
   return createElement(
-    element,
+    `h${level}`,
     { className, id, "data-testid": testId },
     children,
   );
diff --git a/packages/react/src/components/List/List.tsx b/packages/react/src/components/List/List.tsx
index de306a5..62c3dfc 100644
--- a/packages/react/src/components/List/List.tsx
+++ b/packages/react/src/components/List/List.tsx
@@ -8,13 +8,11 @@ type ListItemElement = ReactElement<ListItemProps, typeof ListItem>;
 export type ListProps = {
   /**
    * Type of the list.
-   *
-   * @default unordered
    */
   type?: ListType;
 
   /**
-   * One or more <List.Item> elements.
+   * One or more `<List.Item>` elements.
    */
   children?: ListItemElement | ListItemElement[] | ReactNode; // ReactNode is needed for MDXComponents
 } & CommonComponentProps;
@@ -22,13 +20,12 @@ export type ListProps = {
 const className = cn("list");
 
 /**
- * Display a list of items.
+ * A list of items.
  */
-export function List({ type, children, id, testId }: ListProps) {
-  const element = type === "ordered" ? "ol" : "ul";
-
+export function List({ type = "unordered", children, id, testId }: ListProps) {
   return createElement(
-    element,
+    type === "ordered" ? "ol" : "ul",
+
     { className, id, "data-testid": testId },
     children,
   );
diff --git a/packages/react/src/components/List/ListItem.tsx b/packages/react/src/components/List/ListItem.tsx
index c742b5c..d3db3cf 100644
--- a/packages/react/src/components/List/ListItem.tsx
+++ b/packages/react/src/components/List/ListItem.tsx
@@ -9,7 +9,7 @@ export type ListItemProps = {
 } & CommonComponentProps;
 
 /**
- * Display a list item.
+ * A list item.
  */
 export function ListItem({ children, id, testId }: ListItemProps) {
   return (
diff --git a/packages/react/src/components/Paragraph/Paragraph.tsx b/packages/react/src/components/Paragraph/Paragraph.tsx
index 3922666..56f8079 100644
--- a/packages/react/src/components/Paragraph/Paragraph.tsx
+++ b/packages/react/src/components/Paragraph/Paragraph.tsx
@@ -11,7 +11,7 @@ export type ParagraphProps = {
 const className = cn("paragraph");
 
 /**
- * Display a text paragraph.
+ * A paragraph of text.
  */
 export function Paragraph({ children, id, testId }: ParagraphProps) {
   return (